PHP Manual

# Manual do PHP

2026-06-24

# Direitos Autorais

Copyright © 1997 - 2026 PHP Documentation Group. Este material pode ser distribuído apenas sob os termos e condições determinados pela Creative Commons Attribution 3.0 ou posterior. Uma cópia da licença Creative Commons Attribution 3.0 é distribuída com este manual. A última versão está disponível atualmente em » http://creativecommons.org/licenses/by/3.0/.

# Manual do PHP

# Sobre este manual

PHP, que significa PHP: Hypertext Preprocessor (pré-processador de hipertexto), é uma linguagem de script de uso geral de código aberto amplamente utilizada, especialmente adequada para desenvolvimento web e pode ser incorporada em HTML. Sua sintaxe baseia-se em C, Java e Perl, e é fácil de aprender. O objetivo principal da linguagem é permitir aos desenvolvedores escreverem páginas que serão geradas de forma dinâmica e rápida, mas pode-se fazer muito mais do que isso com o PHP.

Esse manual consiste primeiramente de uma referência de funções, mas ele também contém uma referência da linguagem, explicações sobre os recursos mais importantes do PHP, e outras informações suplementares.

Este manual inclui informações que cobrem as duas versões principais mais recentes do PHP (versões 7 e 8). Informações sobre extensões que não estão mais incluídas nessas versões do PHP e alterações em funções em versões anteriores não estão incluídas. Arquivos de versões mais antigas do manual que documentam versões anteriores do PHP estão disponíveis na seção "Mais documentação" na » página "Documentação" do site do PHP.

Este manual pode ser obtido em vários formatos em » https://www.php.net/download-docs.php. Mais informações sobre como este manual é desenvolvido podem ser encontradas no apêndice 'Sobre o manual'. Se você está interessado na história do PHP, consulte o apêndice correspondente.

# Autores e Contribuidores

Há um grande número de contribuidores que atualmente ajudam no nosso trabalho ou que forneceram uma grande ajuda ao projeto no passado. Existem também muitas pessoas não citadas que ajudam com as notas de usuários nas páginas do manual, que são incluídas continuamente nas referências, por cujo trabalho somos muito gratos. Todas as listas a seguir estão em ordem alfabética.

# Autores e Editores

Os seguintes contribuidores são reconhecidos pelo impacto que causaram e/ou continuam a causar ao adicionar conteúdo ao manual: Mehdi Achour, Bill Abt, Jouni Ahto, Alexander Aulbach, Stig Bakken, George Peter Banyard, Christoph M. Becker, Daniel Beckham, Friedhelm Betz, Nilgün Belma Bugüner, Jesus M. Castagnetto, Ron Chmara, Sean Coates, John Coggeshall, Simone Cortesi, Peter Cowburn, Antony Dovgal, Daniel Egeberg, Markus Fischer, Wez Furlong, Sara Golemon, Rui Hirokawa, Brad House, Pierre-Alain Joye, Etienne Kneuss, Moriyoshi Koizumi, Rasmus Lerdorf, Andrew Lindeman, Nuno Lopes, Hannes Magnusson, Stanislav Malyshev, Justin Martin, Rafael Martinez, Rick McGuire, Moacir de Oliveira Miranda Júnior, Kalle Sommer Nielsen, Yasuo Ohgaki, Philip Olson, Richard Quadling, Derick Rethans, Rob Richards, Georg Richter, Sander Roobol, Egon Schmid, Thomas Schoefbeck, Sascha Schumann, Dan Scott, Damien Seguy, Masahiro Takagi, Yoshinari Takaoka, Yannick Torres, Jakub Vrana, Michael Wallner, Lars Torben Wilson, Jim Winstead, Jeroen van Wolffelaar e Andrei Zmievski.

Os seguintes contribuidores fizeram um trabalho significativo editando o manual: Stig Bakken, Peter Cowburn, Gabor Hojtsy, Hartmut Holzgraefe, Philip Olson e Egon Schmid.

# Mantenedores de Notas de Usuários

Os mantenedores mais ativos atualmente são: Daniel Brown, Nuno Lopes, Felipe Pena, Thiago Pojda e Maciek Sokolewicz.

Estas pessoas também se esforçaram muito no gerenciamento de notas de usuários: Mehdi Achour, Daniel Beckham, Friedhelm Betz, Victor Boivie, Jesus M. Castagnetto, Nicolas Chaillan, Ron Chmara, Sean Coates, James Cox, Vincent Gevers, Sara Golemon, Zak Greant, Szabolcs Heilig, Oliver Hinckel, Hartmut Holzgraefe, Etienne Kneuss, Rasmus Lerdorf, Matthew Li, Andrew Lindeman, Aidan Lister, Hannes Magnusson, Maxim Maletsky, Bobby Matthis, James Moore, Philip Olson, Sebastian Picklum, Derick Rethans, Sander Roobol, Damien Seguy, Jason Sheets, Tom Sommer, Jani Taskinen, Yasuo Ohgaki, Jakub Vrana, Lars Torben Wilson, Jim Winstead, Jared Wyles e Jeroen van Wolffelaar.

# Começando

# O que é o PHP e o que ele pode fazer?

# O que é o PHP?

O PHP (um acrônimo recursivo para PHP: Hypertext Preprocessor) é uma linguagem de script open source de uso geral, muito utilizada, e especialmente adequada para o desenvolvimento web e que pode ser embutida dentro do HTML.

Ótimo, mas o que isso significa? Por exemplo:

Exemplo #1 Um exemplo introdutório

    <!DOCTYPE html>
    <html>
        <head>
            <title>Exemplo</title>
        </head>
        <body>

            <?php
                echo "Olá, eu sou um script PHP!";
            ?>

        </body>
    </html>

Em vez de muitos comandos para mostrar HTML (como acontece com C ou Perl), as páginas PHP contém HTML em código mesclado que faz alguma coisa (neste caso, mostra Olá, eu sou um script PHP!). O código PHP é delimitado pelas instruções de processamento (tags) de início e fim `<?php` e `?>` que permitem entrar e sair do modo PHP.

O que distingue o PHP de algo como o JavaScript no lado do cliente é que o código é executado no servidor, gerando o HTML que é então enviado para o navegador. O navegador recebe os resultados da execução desse script, mas não sabe qual era o código fonte. Um servidor web pode até mesmo ser configurado para processar todos os seus arquivos HTML com o PHP, e assim não haverá como os usuários dizerem que o PHP está sendo usado.

A melhor coisa em usar o PHP é que ele é extremamente simples para um iniciante, mas oferece muitos recursos avançados para um programador profissional. Não tenha medo de ler a longa lista de recursos do PHP. Com o PHP, praticamente qualquer pessoa pode começar a trabalhar e escrever scripts simples imediatamente.

Apesar do desenvolvimento do PHP ser focado nos scripts do lado do servidor, muito mais pode ser feito com ele. Leia mais sobre isso na seção O que o PHP pode fazer?, ou vá diretamente para o tutorial introdutório para começar a aprender sobre programação para a web.

# O que o PHP pode fazer?

Qualquer coisa. O PHP é focado principalmente nos scripts do lado do servidor, portanto ele pode fazer qualquer coisa que qualquer outro programa CGI pode fazer, como coletar dados de formulários, gerar páginas com conteúdo dinâmico ou enviar e receber cookies. Mas o PHP pode fazer muito mais.

Existem duas áreas principais onde os scripts PHP são usados:

- Execução de script no servidor. Este é o mais amplamente usado e o principal campo de atuação do PHP. Três coisas são necessárias para fazer isso funcionar: o interpretador do PHP (CGI ou módulo do servidor), um servidor web e um navegador web. Todos esses podem ser executados em uma máquina local para apenas experimentar a programação com o PHP. Consulte a seção sobre instruções de instalação para mais informações.
- Execução de scripts na linha de comando. Um script PHP pode ser executado sem qualquer servidor ou navegador, apenas o interpretador PHP é necessário para ser usado desta forma. Esse tipo de uso é ideal para scripts normalmente executados usando o cron (em Unix ou macOS) ou o Agendador de Tarefas (no Windows). Esses scripts podem ser usados também para rotinas de processamento de texto simples. Veja a seção Utilizando o PHP em linha de comando para mais informações.

O PHP pode ser utilizado na maioria dos sistemas operacionais, incluindo Linux, várias variantes do Unix (como HP-UX, Solaris e OpenBSD), Microsoft Windows, macOS, RISC OS e provavelmente outros. O PHP também tem suporte à maioria dos servidores web atualmente. Isso inclui o Apache, o IIS e muitos outros. E isso inclui qualquer servidor web que possa utilizar o binário FastCGI do PHP, como o lighttpd e o nginx. O PHP trabalha tanto como módulo quanto como um processador CGI.

Com o PHP, portanto, os desenvolvedores têm liberdade para escolher um sistema operacional e um servidor web. Além disso, podem escolher entre utilizar programação estruturada ou programação orientada a objeto (OOP), ou ainda uma mistura das duas.

O PHP não é limitado apenas a gerar HTML. As habilidades do PHP incluem gerar tipos de arquivos complexos, como imagens ou arquivos PDF, criptografar dados e enviar emails. Ele também pode gerar facilmente qualquer texto, como JSON ou XML. O PHP consegue gerar automaticamente esses arquivos, e gravá-los no sistema de arquivos, ao invés de apenas imprimir, possibilitando criar um cache no lado do servidor para conteúdo dinâmico.

Uma das características mais fortes e mais significativas do PHP é seu suporte a uma ampla variedade de banco de dados. Escrever uma página web consultando um banco de dados é incrivelmente simples usando uma das extensões específicas de banco de dados (por exemplo, mysql), ou usando uma camada de abstração como o PDO ou conectar a qualquer banco de dados que suporte o padrão "Open Database Connection" usando a extensão ODBC. Outros bancos de dados podem utilizar cURL ou sockets, como o CouchDB.

O PHP também tem suporte para comunicação com outros serviços utilizando protocolos como LDAP, IMAP, SNMP, NNTP, POP3, HTTP, COM (no Windows) e incontáveis outros. Ele pode também abrir soquetes brutos de rede e interagir usando qualquer outro protocolo. O PHP também suporta o intercâmbio de dados complexos WDDX entre virtualmente todas as linguagens de programação para web. Falando de interconexão, o PHP implementa a instanciação de objetos Java e os utiliza transparentemente como objetos PHP.

O PHP tem recursos úteis para processamento de texto, incluindo expressões regulares compatíveis com Perl (PCRE), e muitas outras extensões e ferramentas para analisar e acessar documentos XML. O PHP padroniza todas as extensões XML a partir da base sólida da libxml2, além de estender o conjunto de recursos adicionando suporte a SimpleXML, XMLReader e XMLWriter.

E existem muitas outras extensões interessantes, que são categorizadas tanto alfabeticamente quanto por categoria. E existem também as extensões PECL adicionais que podem, ou não, estar documentadas dentro do próprio manual do PHP, como a » XDebug.

Esta página não é suficiente para listar todos os recursos e benefícios que o PHP pode oferecer. Leia as seções sobre a instalação do PHP, e veja a parte de referência das funções para detalhes sobre as extensões mencionadas aqui.

# Um simples tutorial

## Índice

- Sua primeira página PHP
- Algo Útil
- Tratando Formulários
- O que vem a seguir?

Aqui nós iremos mostrar o básico do básico do PHP em um tutorial simples e curto. Este texto fala somente sobre a criação de páginas web dinâmicas com PHP, embora o PHP não seja apenas capaz de criar páginas web. Veja a seção intitulada O que o PHP pode fazer para mais informações.

Fazer páginas com PHP é o mesmo que criar páginas HTML e você pode criá-las e editá-las da mesma maneira que as páginas HTML comuns são criadas.

# Sua primeira página PHP

Este tutorial assume que o PHP já está instalado. Instruções de instalação podem ser encontradas na » página de download.

Crie um novo arquivo chamado hello.php com o seguinte conteúdo:

Exemplo #1 Nosso primeiro script PHP: hello.php

    <?php

    echo "Olá, Mundo!";

    ?>

Usando o terminal, navegue até o diretório contendo este arquivo e inicie o servidor de desenvolvimento com o seguinte comando:

    php -S localhost:8000

Use um navegador para acessar o arquivo com a URL do servidor web, terminando com a referência ao arquivo `/hello.php`. De acordo com o último comando executado, a URL será `http://localhost:8000/hello.php`. Se tudo estiver configurado corretamente, este arquivo será interpretado pelo PHP e a mensagem "Olá, Mundo!" será mostrada no navegador.

O PHP pode ser incorporado em uma página HTML normal. Isso significa que dentro do documento HTML podem ser escritas as instruções PHP, conforme demonstrado no exemplo a seguir:

    <!DOCTYPE html>
    <html>
        <head>
            <title>Teste PHP</title>
        </head>
        <body>
            <?php echo '<p>Olá, Mundo!</p>'; ?>
        </body>
    </html>

Isto resultará na seguinte saída:

    <!DOCTYPE html>
    <html>
        <head>
            <title>Teste PHP</title>
        </head>
        <body>
            <p>Olá, Mundo!</p>
        </body>
    </html>

Este programa é realmente simples e você não precisa do PHP para criar uma página assim (fixa). Tudo o que ela faz é mostrar: `Olá, Mundo!` utilizando a instrução echo. Note que o arquivo não precisa ser executável ou especial. O servidor web descobre que este arquivo precisa ser interpretado pelo PHP por causa da extensão ".php", que o servidor é configurado para repassar ao PHP. Pense nisso como um arquivo HTML normal que por acaso possui um conjunto de etiquetas especiais disponíveis para você fazer muitas coisas interessantes.

O objetivo do exemplo é mostrar o formato especial das etiquetas do PHP. Neste exemplo nós usamos `<?php` para indicar que a partir daquele ponto entramos no modo PHP. Então nós colocamos a instrução do PHP e saímos do modo PHP adicionando a etiqueta de fechamento, `?>`. Você pode entrar e sair do modo PHP num arquivo HTML desta maneira em qualquer lugar que você queira. Para mais detalhes, leia a seção do manual que fala da sintaxe básica do PHP.

> Nota: Uma Nota sobre Fins de linha

> Fins de linha têm pouco significado no HTML, entretanto ainda é uma boa idéia fazer o seu HTML ter uma boa aparência e organização através da divisão em linhas. Um fim de linha imediatamente após a etiqueta de fechamento `?>` será removido pelo PHP. Isso pode ser extremamente útil quando você está juntando vários blocos de PHP ou arquivos incluídos contendo apenas PHP que não deveriam imprimir nada no processo. Ao mesmo tempo isso pode ser um pouco confuso. Você pode colocar um espaço depois da tag de fechamento `?>` para forçar a impressão de um espaço e fim de linha ou você pode explicitamente imprimir o fim de linha com um último echo/print de dentro de seu bloco PHP.

> Nota: Uma Nota sobre os Editores de Texto

> Há muitos editores de textos e Ambientes de Desenvolvimento Integrado (IDEs - Integrated Development Enviroments) que você pode usar para criar, editar e gerenciar arquivos PHP. Uma lista parcial destas ferramentas pode ser vista na » Lista de Editores para PHP. Se você gostaria de recomendar um editor, por favor visite a página acima e peça ao administrador da página para adicionar o editor à lista. Ter um editor que destaca a sintaxe das etiquetas pode ser muito útil.

> Nota: Uma Nota sobre os Processadores de Texto

> Processadores de texto como o StarOffice Writer, Microsoft Word e Abiword não são boas escolhas para editar arquivos PHP. Se você deseja usar um desses para este script de teste, você precisa verificar se você está salvando o arquivo como texto puro ou o PHP não será capaz de ler e executar o script.

Agora que você criou com sucesso um script simples em PHP, é hora de criar o mais famoso dos scripts PHP! Uma chamada à função phpinfo() e você verá muitas informações úteis sobre seu sistema e configurações como as Variáveis Predefinidas disponíveis, módulos carregados pelo PHP, e as opções de configuração. Tire algum tempo para ver e revisar estas informações importantes.

Exemplo #2 Como obter informações sobre o PHP

    <?php

    phpinfo();

    ?>

# Algo Útil

Vamos fazer alguma coisa um pouco mais útil agora. Nós iremos checar qual é o tipo de navegador que o visitante está utilizando para ver a nossa página. Para fazer isto nós iremos checar qual é o valor da string agente que o navegador envia como parte de sua requisição HTTP. Esta informação é armazenada em uma variável. Variáveis sempre começam com um símbolo de cifrão no PHP. A variável que nos interessa no momento é $_SERVER['HTTP_USER_AGENT'].

> Nota:

> $_SERVER é uma variável especial reservada do PHP que contém todas as informações sobre o servidor web. Ela é conhecida como uma superglobal. Veja a página do manual relacionada às superglobais para mais informações.

Para exibir esta variável, nós podemos fazer isto:

Exemplo #1 Imprimindo uma variável (elemento do array)

    <?php

    echo $_SERVER['HTTP_USER_AGENT'];

    ?>

Um exemplo de saída desse script poderia ser:

    Mozilla/5.0 (Linux) Firefox/112.0

Há muitos tipos de variáveis disponíveis no PHP. No exemplo acima nós imprimimos um elemento do array. Arrays podem ser muito úteis.

$_SERVER é somente uma das variáveis que o PHP automaticamente disponibiliza para você. A lista destas variáveis pode ser vista na seção Variáveis Reservadas do manual ou você pode obter uma lista completa delas olhando o resultado da função phpinfo() utilizada no exemplo da seção anterior.

Você pode colocar múltiplas instruções PHP dentro da etiqueta PHP e criar pequenos blocos de códigos que fazem muito mais do que um simples 'echo'. Por exemplo, se você quiser verificar se o navegador é o Firefox você pode fazer isso:

Exemplo #2 Exemplo utilizando estruturas de controle e funções

    <?php

    if (str_contains($_SERVER['HTTP_USER_AGENT'], 'Firefox')) {
        echo 'Você está usando o Firefox.';
    }

    ?>

Um exemplo de saída desse script seria:

    Você está usando o Firefox.

Aqui nós introduzimos alguns conceitos novos. Nós temos a declaração if. Se você está familiarizado com a sintaxe básica usada pela linguagem C isto parecerá ser lógico para você. Se não, você provavelmente deve ver um livro introdutório de PHP e ler os capítulos iniciais, ou ainda ler a seção Referência da Linguagem do manual.

O segundo conceito que iremos abordar é a chamada à função str_contains(). A função str_contains() vem junto com o PHP e busca uma palavra em outra palavra. Neste caso nós estamos procurando pelo texto `'Firefox'` dentro de $_SERVER['HTTP_USER_AGENT']. Se o dado pesquisado for encontrado na coleção, a função retorna verdadeiro. Se não, ela retorna `false`. Se ela retornar `true`, o if avalia para `true` e o código dentro dos {colchetes} é executado. Caso contrário o código não roda. Tente criar exemplos similares com if, else, e outras funções como strtoupper() e strlen(). Cada página relacionada contém exemplos também. Se você estiver incerto em como utilizar funções você deve ler as páginas sobre como ler uma definição de função e a seção sobre funções do PHP.

Nós podemos avançar agora e mostrar a você como alternar entre os modos PHP mesmo que você esteja executando blocos de códigos:

Exemplo #3 Mesclando entre os modos PHP e HTML

    <?php
    if (str_contains($_SERVER['HTTP_USER_AGENT'], 'Firefox') !== false) {
        ?>
        <h3>str_contains() retornou não falso</h3>
        <p>Você está usando Firefox</p>
        <?php
    } else {
        ?>
        <h3>str_contains() retornou false</h3>
        <p>Você não está usando Firefox</p>
        <?php
    }
    ?>

Um exemplo de saída desse script poderia ser:

    <h3>str_contains() retornou não falso</h3>
    <p>Você está usando Firefox</p>

Ao invés de usar a declaração echo do PHP para imprimir a saída dos dados, nós saímos do modo do PHP e usamos o HTML normal. O importante a notar aqui é que a lógica do script continua intacta. Somente um dos blocos HTML será enviado dependendo do resultado da chamada à função str_contains(). Em outras palavras, depende se a palavra `Firefox` for encontrada ou não.

# Tratando Formulários

Uma das características mais fortes do PHP é a forma como ele trata formulários HTML. O conceito básico que é importante entender é que qualquer elemento de formulário irá automaticamente ficar disponível para seus scripts PHP. Por favor leia a seção Variáveis externas do PHP para mais informações e exemplos de como usar formulários com PHP. Aqui vai um exemplo de formulário HTML:

Exemplo #1 Um simples formulário HTML

    <form action="action.php" method="post">
        <label for="nome">Seu nome:</label>
        <input name="nome" id="nome" type="text">

        <label for="idade">Sua idade:</label>
        <input name="idade" id="idade" type="number">

        <button type="submit">Enviar</button>
    </form>

Não há nada de especial neste formulário. É um formulário HTML comum sem nenhuma etiqueta especial de qualquer tipo. Quando o usuário preencher este formulário e clicar no botão "Enviar", a página action.php é chamada. Neste arquivo nós teremos algo como isto:

Exemplo #2 Imprimindo dados de nosso formulário

    Olá, <?php echo htmlspecialchars($_POST['nome']); ?>.
    Você tem <?php echo (int) $_POST['idade']; ?> anos de idade.

Um exemplo de saída deste script seria:

    Olá, Maria. Você tem 22 anos de idade.

Para além de htmlspecialchars() e `(int)`, deve ser óbvio o que o script faz. htmlspecialchars() transforma caracteres que sejam especiais no HTML na sua forma codificada, de forma que não seja possível injetar etiquetas HTML ou JavaScript em sua página. O campo "idade", por ser um número, pode ser simplesmente convertido para um int que automaticamente eliminará qualquer caractere estranho. Você também pode fazer o PHP automaticamente fazer isso utilizando a extensão filter. As variáveis $_POST['nome'] e $_POST['idade'] são criadas automaticamente pelo PHP. Anteriormente utilizamos a superglobal $_SERVER; acima mostramos que a superglobal $_POST contém todos os dados POST. Perceba como o método (method) do formulário é POST. Se fosse utilizado o método GET, os dados do formulário acabariam na superglobal $_GET. Você também pode utilizar a superglobal $_REQUEST, se não se importar com a origem do dado enviado. Ela conterá os dados mesclados das origens GET, POST e COOKIE.

# O que vem a seguir?

Com este novo conhecimento fica fácil entender a maior parte do manual.

Em particular, você pode explorar os seguintes recursos:

- Ler e gravar arquivos com as funções de sistema de arquivos
- Lidar com envio de arquivos
- Obter páginas e arquivos remotos com o Curl
- Armazenar e analisar dados em um banco de dados com o PDO (SQLite pode ser usado sem executar um servidor de banco de dados)
- Manter dados persistentes através das Sessões

Existem várias bibliotecas e » frameworks para cada ocasião no » repositório Packagist, todas instaláveis pelo gerenciador de pacotes Composer.

Para ajuda e conselhos da comunidade, consulte a » página de Ajuda.

Para uma variedade de podcasts, apresentações e outros vídeos, confira a » comunidade PeerTube.

Outros recursos da comunidade que podem te ajudar incluem "listas incríveis" (diretórios selecionados de links) e "roteiros para desenvolvedores" (listas de tópicos relacionados).

Quando você estiver sem saber por onde começar, tente dividir seu projeto ou problema em partes menores, o que permitirá que você veja mais facilmente o que já sabe fazer e o que precisa aprender. A lista pode ser tão extensa/detalhada quanto você precisar. Por exemplo, a criação de um blog pode ser dividida nas seguintes partes:

- Listando e visualizando páginas
  - Lendo registros (páginas) de um banco de dados
- Criando páginas
  - Lidando com submissão de formulários
  - Gravando registros (páginas) em um banco de dados
- Login do administrador
  - Lendo registros (usuários) de um banco de dados
  - Lidando com senhas
  - Persistência de dados (login do usuário) entre requisições/páginas (sessões)

Se não houver nada específico que você queira construir, pode tentar procurar exercícios de programação como katas, desafios e "golfe de código". Mesmo que não sejam especificamente voltados para PHP, a maioria deve ser possível de concluir e provavelmente desafiará seu conhecimento e raciocínio.

- Introdução — O que é o PHP e o que ele pode fazer?
- Um simples tutorial
  - Sua primeira página PHP
  - Algo Útil
  - Tratando Formulários
  - O que vem a seguir?

# Instalação e Configuração

# Considerações Gerais sobre Instalação

Antes de começar a instalar o PHP, primeiro você deve saber o que você deseja fazer com ele. Existem duas principais formas de se usar o PHP, como descrito na seção O que o PHP pode fazer? do manual:

- Websites e aplicações web (script do lado do servidor)
- Scripts para linha de comando

Para a primeira forma, e a mais comum, você precisa de três coisas: o próprio PHP, um servidor web e um cliente (browser) web. Você provavelmente já tem um browser, e dependendo da configuração do seu sistema operacional, você pode também ter um servidor web (Ex.: Apache no Linux e macOS; IIS no Windows). Você também pode alugar um host em uma companhia qualquer. Dessa maneira, você não precisa configurar nada por conta própria, apenas escrever os seus scripts PHP, enviar (upload) para o servidor que você alugou, e ver os resultados no seu browser.

No caso de você instalar o servidor e o PHP por conta própria, você tem duas escolhas para o método de conexão do PHP com o servidor. Para muitos servidores o PHP tem uma interface direta de módulo (também chamada de SAPI). Entre esses servidores estão Apache, Microsoft Internet Information Server, Netscape e iPlanet. Se o PHP não tiver suporte de módulo para o seu servidor web, você também pode usá-lo como processador CGI ou FastCGI. Isso significa configurar seu servidor para usar o executável CGI do PHP para processar todas as requisições a arquivos PHP no servidor.

Se você também estiver interessado em usar o PHP para criar scripts em linha de comandos (Ex.: criar scripts que geram imagens enquanto estão offline, ou processar arquivos de texto dependendo de alguns argumentos que você passar ao script), você pode precisar do executável de linha de comando. Para mais informações, leia a seção sobre criando aplicações de linha de comando com o PHP. Nesse caso, você não precisa de servidor nem de um browser.

A partir daqui, esta seção trata da instalação do PHP em servidores web no Unix e Windows como módulos dos servidores e executáveis CGI. Você também pode encontrar informações sobre executáveis de linha de comando nas seções seguintes.

O código fonte do PHP e distribuições binárias para Windows podem ser encontradas em » https://www.php.net/downloads.php.

# Instalação em sistemas Unix

## Índice

- Instalando a partir de pacotes no Debian GNU/Linux e distribuições relacionadas
- Instalando a partir de pacotes em distribuições GNU/Linux que usam DNF
- Instalando a partir de pacotes ou portas no OpenBSD
- Instalando a partir do código-fonte em sistemas Unix e macOS
- CGI e instalações de linha de comando
- Apache 2.0 em sistemas Unix
- Nginx 1.4.x em sistemas Unix
- Lighttpd 1.4 em sistemas Unix
- Servidores Web LiteSpeed/OpenLiteSpeed em sistemas Unix
- Dicas de instalação específicas para o Solaris

A maioria dos sistemas operacionais e distribuições Unix (e Linux) possui uma versão empacotada de PHP e extensões disponíveis através de seu sistema de empacotamento. Existem seções com informações básicas sobre como instalar o PHP usando esses sistemas.

Para algumas distribuições, também existem repositórios de pacotes de terceiros que geralmente incluem uma variedade maior de versões e extensões disponíveis.

O PHP também pode ser instalado como um componente de alguns servidores de aplicações de terceiros.

Finalmente, o PHP sempre pode ser instalado a partir das distribuições de origem, o que permite maior flexibilidade na escolha de quais recursos, extensões e APIs de servidor ativar. Existem seções com informações sobre como compilar e configurar o PHP para uso com diferentes APIs de servidor em particular.

## Instalando a partir de pacotes no Debian GNU/Linux e distribuições relacionadas

O PHP pode ser instalado a partir do código-fonte, mas também está disponível através de pacotes do » Debian GNU/Linux. Isto também vale para outras distribuições baseadas em Debian, como Ubuntu, Kali Linux, e Linux Mint.

Aviso

Compilações de terceiros são consideradas não oficiais e não são suportadas diretamente pelo projeto PHP. Quaisquer problemas encontrados devem ser relatados ao fornecedor dessas compilações não oficiais, a menos que possam ser reproduzidos usando as compilações da » área de download oficial.

Os pacotes podem ser instalados usando os comandos apt ou aptitude. Essa página do manual utilizará esses dois comandos intercambiavelmente.

### Usando APT

Primeiro veja que outros pacotes relacionados podem ser desejados, como `libapache-mod-php` para integração com o Apache 2 e `php-pear` para o PEAR.

Segundo, antes de instalar um pacote é melhor garantir que a lista de pacotes está atualizada. Isso é feito rodando o comando apt update.

Exemplo #1 Exemplo de instalação no Debian com Apache 2

    # apt install php-common libapache2-mod-php php-cli

APT instalará automaticamente o módulo do PHP para Apache 2 e todas as suas dependências, depois ativando-o. O Apache deve ser inicializado para que as modificações tenham efeito. Por exemplo:

Exemplo #2 Parando e iniciando o Apache depois do PHP instalado

    # /etc/init.d/apache2 stop
    # /etc/init.d/apache2 start

### Controle melhor as configurações

Até então o PHP foi instalado apenas com os módulos principais. É bem provável que módulos adicionais sejam desejados, como MySQL, cURL, GD, etc. Estes também podem ser instalados pelo comando apt.

Exemplo #3 Métodos listar pacotes adicionais do PHP

    # apt-cache search php
    # apt search php | grep -i mysql
    # aptitude search php

A lista de pacotes mostrará uma grande quantidade de pacotes incluindo componentes básicos do PHP, como `php-cgi`, `php-cli` e `php-dev`, assim como muitas extensões do PHP. Quando extensões estão instaladas, pacotes adicionais serão instalados automaticamente conforme necessário para satisfazer as dependências desses pacotes.

Exemplo #4 Instalando PHP com MySQL e cURL

    # apt install php-mysql php-curl

O APT irá automaticamente adicionar as linhas apropriadas a arquivos php.ini relacionados, como /etc/php/7.4/php.ini, /etc/php/7.4/conf.d/*.ini, etc., e dependendo da da extensão irá ainda acrescentar diretivas similares a `extension=foo.so`. Entretanto é necessário reiniciar o servidor web para que essas alterações tenham efeito.

### Problemas comuns

- Se os scripts PHP não estão sendo interpretados pelo servidor web, então é provável que o PHP não tenha sido acrescentado aos arquivos de configuração do servidor web, que no Debian pode ser /etc/apache2/apache2.conf ou algo similar. Veja o manual do Debian para mais detalhes.
- Se uma extensão parece ter sido instalada e ainda assim funções permanecem não definidas, verifique que o arquivo .ini apropriado está sendo carregado e/ou se o servidor web foi reiniciado após a instalação.

## Instalando a partir de pacotes em distribuições GNU/Linux que usam DNF

Embora o PHP possa ser instalado a partir do código-fonte, ele também está disponível por meio de pacotes em sistemas que usam DNF, como Red Hat Enterprise Linux, OpenSUSE, Fedora, CentOS, Rocky Linux e Oracle Enterprise Linux.

Aviso

Compilações de terceiros são consideradas não oficiais e não são suportadas diretamente pelo projeto PHP. Quaisquer problemas encontrados devem ser relatados ao fornecedor dessas compilações não oficiais, a menos que possam ser reproduzidos usando as compilações da » área de download oficial.

Os pacotes podem ser instalados usando o comando dnf.

### Instalando pacotes

Primeiro, observe que outros pacotes relacionados podem ser desejados, como `php-pear` para » PEAR, ou `php-mysqlnd` para a extensão MySQL.

Segundo, antes de instalar um pacote, é aconselhável garantir que a lista de pacotes esteja atualizada. Normalmente, isso é feito executando o comando dnf update.

Exemplo #1 Exemplo de instalação DNF

    # dnf install php php-common

O DNF instalará automaticamente a configuração do PHP para o servidor web, mas pode ser necessário reinicializá-lo para que as alterações tenham efeito. Por exemplo:

Exemplo #2 Reiniciando o Apache depois que o PHP estiver instalado

    # sudo systemctl restart httpd

### Melhor controle da configuração

Na última seção, o PHP foi instalado apenas com módulos principais. É muito provável que módulos adicionais sejam desejados, como MySQL, cURL, GD, etc. Eles também podem ser instalados através do comando dnf.

Exemplo #3 Métodos para listar pacotes PHP adicionais

    # dnf search php

A lista de pacotes conterá um grande número de pacotes que incluem componentes básicos do PHP, como `php-cli`, `php-fpm` e `php-devel`, bem como muitas extensões PHP. Quando as extensões são instaladas, pacotes adicionais serão instalados automaticamente conforme necessário para satisfazer as dependências desses pacotes.

Exemplo #4 Instalando PHP com MySQL e GD

    # dnf install php-mysqlnd php-gd

O DNF adicionará automaticamente as linhas apropriadas aos diferentes arquivos php.ini relacionados como /etc/php/8.3/php.ini, /etc/php/8.3/conf.d/*.ini etc., e dependendo da extensão adicionará entradas semelhantes a `extension=foo.so`. No entanto, é necessário reiniciar o servidor web (como o Apache) antes que essas alterações tenham efeito.

## Instalando a partir de pacotes ou portas no OpenBSD

Essa seção contém notas e dicas específicas para a instalação do PHP no » OpenBSD.

### Usando Pacotes Binários

Usar pacotes binários para instalar o PHP no OpenBSD é o método recomendado e o mais simples. O pacote núcleo foi separado dos vários módulos, e cada um pode ser instalado e removido independentemente dos outros. Os arquivos necessários podem ser encontrados no CD do OpenBSD ou no FTP do site.

O pacote principal que você precisa instalar é o php, que contém o engine básico (mais gettext e iconv), e pode estar disponível dentre várias versões a escolher. Depois, olhe os pacotes com módulos, como o php-mysqli ou php-imap. Você precisa usar o comando phpxs para ativar e desativar esses módulos no seu arquivo php.ini.

Exemplo #1 Exemplo de instalação de pacote no OpenBSD

    # pkg_add php
    # pkg_add php-apache
    # pkg_add php-mysqli
      (install the PEAR libraries)
    # pkg_add pear

    Siga as instruções de cada pacote!

      (to remove packages)
    # pkg_delete php
    # pkg_delete php-apache
    # pkg_delete php-mysqli
    # pkg_delete pear

Leia o manual de » packages(7) para mais informações sobre pacotes binários no OpenBSD.

### Usando Ports

Você também pode compilar o PHP a partir dos fontes usando a » árvore ports. No entanto, isso só é recomendado para usuários familiarizados com OpenBSD. O port do PHP é dividido em núcleo e extensões. As extensões geram sub-pacotes para todos os módulos suportados pelo PHP. Se você achar que não quer criar alguns dos módulos, use o comando no_* FLAVOR. Por exemplo, se você quiser que o módulo imap seja ignorado, atribua à FLAVOR o valor no_imap.

### Problemas Comuns

- Apache e Nginx não são mais os servidores padrão no OpenBSD, mas eles podem ser facilmente encontrados em ports e pacotes. O novo servidor é chamado 'httpd'.
- A instalação padrão do Apache roda dentro de uma » prisão de chroot(2), que restringe os scripts PHP a acessar arquivos abaixo de /var/www. Você irá, portanto, precisar criar um diretório /var/www/tmp para que os arquivos de sessão do PHP sejam guardados, ou usar um backend alternativo para sessões. Além disso, sockets de bancos de dados devem ser colocados dentro da prisão ou escutar na interface localhost. Se você usar funções de rede, alguns arquivos do diretório /etc como /etc/resolv.conf e /etc/services precisarão ser movidos para /var/www/etc. O pacote OpenBSD PEAR se instala automaticamente nos diretórios chroot corretos.
- Os pacotes do OpenBSD package para a extensão » gd requer o Xorg para instalação. Isso é realizado na instalação com o acréscimo de o file set xbase.tgz, ou pode ser instalado posteriormente (veja » OpenBSD FAQ#4).

## Instalando a partir do código-fonte em sistemas Unix e macOS

Software pré-requisito para compilação:

- » GNU make
- Compilador AC (a partir do PHP 8.0.0, a compatibilidade com C99 é necessária; a partir do PHP 8.4.0, a compatibilidade com C11 é necessária)
- Um servidor web
- Quaisquer componentes específicos do módulo (como bibliotecas GD, PDF, etc.)

Ao compilar diretamente de fontes Git ou após modificações personalizadas, estas ferramentas adicionais podem ser necessárias:

- » autoconf:
  - PHP 7.3 e posteriores: 2.68+
  - PHP 7.2: 2.64+
  - PHP 7.1 e anteriores: 2.59+
- » re2c:
  - PHP 8.3 e posteriores: 1.0.3+
  - PHP 8.2 e anteriores: 0.13.4+
- » bison:
  - PHP 7.4 e posteriores: 3.0.0+
  - PHP 7.3 e anteriores: 2.4+ (incluindo Bison 3.x)

Para as etapas mais detalhadas da compilação do PHP a partir da fonte, consulte o » README.md no pacote do código-fonte.

O processo inicial de instalação e configuração do PHP é controlado pelo uso das opções de linha de comando do script configure. Uma lista de opções disponíveis junto com breves explicações pode ser mostrada executando ./configure --help. Este manual documenta as diferentes opções separadamente. As opções principais podem ser encontradas no apêndice, enquanto as diferentes opções específicas de extensão são descritas nas páginas de referência.

Após a execução do script de configuração, o PHP pode ser construído usando o comando make. A seção de Instalação das Perguntas Frequentes contém mais informações sobre como lidar com problemas de compilação.

> Nota: Alguns sistemas Unix (como OpenBSD e SELinux) podem proibir o mapeamento de páginas graváveis ​​e executáveis ​​por motivos de segurança, o que é chamado de » PaX MPROTECT ou » proteção contra violação W^X. Este tipo de mapeamento de memória é necessário para o suporte JIT do PCRE, então ou o PHP deve ser construído sem o suporte JIT do PCRE, ou o binário deve ser colocado na lista de permissões por qualquer meio fornecido pelo sistema.

> Nota: Atualmente, a compilação cruzada para ARM com o conjunto de ferramentas Android não é suportada.

## CGI e instalações de linha de comando

Por padrão o PHP é compilado como programas CLI e CGI, os quais podem ser utilizados para processamento CGI. Se você estiver executando um servidor web que suporta o PHP como módulo, você deve geralmente usar essa opção por razões de performance. No entanto, a versão CGI permite que usuários executem diferentes páginas com PHP usando diferentes ids de usuário.

Aviso

Um servidor instalado em modo CGI está aberto a várias vulnerabilidades possíveis. Leia nossa seção de segurança CGI para aprender como se defender de tais ataques.

### Testando

Se você compilou o PHP como um programa CGI, você pode testá-lo usando o comando make test. É sempre uma boa idéia testar os software que você compila. Dessa maneira, você pode achar um problema com o PHP na sua plataforma cedo, ao invés de ter de lidar com isso mais tarde.

### Usando Variáveis

Algumas variáveis de ambientes fornecidas pelo servidor não são definidas na atual » CGI/1.1 specification. Apenas as seguintes variáveis são definidas: AUTH_TYPE, CONTENT_LENGTH, CONTENT_TYPE, GATEWAY_INTERFACE, PATH_INFO, PATH_TRANSLATED, QUERY_STRING, REMOTE_ADDR, REMOTE_HOST, REMOTE_IDENT, REMOTE_USER, REQUEST_METHOD, SCRIPT_NAME, SERVER_NAME, SERVER_PORT, SERVER_PROTOCOL, e SERVER_SOFTWARE. Todo o resto deve ser tratado como 'vendor extensions'.

## Apache 2.0 em sistemas Unix

Esta seção contém notas e dicas específicas para a instalação do PHP no Apache 2.x em sistemas Unix.

Aviso

Não recomendamos usar um MPM com threads no Apache 2 em produção. Use o módulo prefork, que é o MPM padrão no Apache 2.0 e 2.2 e não usa threads. Para obter informações sobre o motivo, leia a FAQ sobre o uso do Apache2 com MPM com threads.

A » documentação do Apache é a fonte de informação com maior autoridade sobre o servidor Apache 2.x. Mais informações sobre opções de instalação para o Apache podem ser encontradas lá.

A versão mais recente do Servidor HTTP do Apache pode ser obtida do » site de download Apache, e uma versão correspondente do PHP pode ser obtida dos locais mencionados anteriormente. Esse guia rápido cobre apenas o básico para iniciar o uso do Apache 2.x e do PHP. Para mais informações, leia a » documentação do Apache. Os números de versão estão omitidos aqui, para garantir que as instruções não fiquem desatualizadas. Nos exemplos abaixo, 'NN' deve ser substituído com a versão específica do Apache utilizado.

Atualmente há duas versões do Apache 2.x. - 2.4 e 2.2. Embora haja várias razões para escolher entre elas, 2.4 é a versão mais atual, e aquela recomendada, se essa opção estiver disponível. Entretanto, as instruções aqui funcionarão para ambas as versões, 2.4 ou 2.2. Importante notar que o Apache httpd 2.2 está no final de sua vida, e nenhum novo desenvolvimento ou correções serão realizados nele.

1. Obtenha o Apache HTTP do endereço acima e descompacte:

       tar -xzf httpd-2.x.NN.tar.gz

2. Da mesma forma, obtenha e descompacte o código-fonte do PHP:

       tar -xzf php-NN.tar.gz

3. Compile e instale o Apache. Consulte a documentação de instalação do Apache para mais detalhes de compilação.

       cd httpd-2_x_NN
       ./configure --enable-so
       make
       make install

4. Agora haverá um Apache 2.x.NN disponível em /usr/local/apache2, configurado com suporte a módulos carregáveis e o MPM prefork padrão. Para testar a instalação, utilize o procedimento usual de inicialização do servidor Apache. Por exemplo:

       /usr/local/apache2/bin/apachectl start

   e depois pare o servidor para configurar o PHP:

       /usr/local/apache2/bin/apachectl stop

5. Agora configure e compile o PHP. Aqui pode-se personalizar o PHP com várias opções como, por exemplo, quais extensões estarão disponíveis. Execute './configure --help' para uma lista de opções disponíveis. Em nosso exemplo, iremos configurar apenas com suporte ao Apache 2 e MySQL.

   Se o Apache foi compilado a partir do código-fonte como descrito acima, os exemplos abaixo terão caminhos coincidentes do apxs, mas se foi instalado de outra forma, o caminho para o apxs precisará ser ajustado. Observe que algumas distribuições podem renomear apxs para apxs2.

       cd ../php-NN
       ./configure --with-apxs2=/usr/local/apache2/bin/apxs --with-pdo-mysql
       make
       make install

   Se for decidido modificar as configurações depois da instalação, os comandos configure, make e make install precisarão ser executados novamente. Só será necessário reiniciar o Apache para que o novo módulo seja carregado. Uma recompilação do Apache não será necessária.

   Note que, por padrão, make install também instalará o » PEAR, várias ferramentas do PHP como phpize, o PHP CLI, entre outros.

6. Configure o php.ini:

       cp php.ini-development /usr/local/lib/php.ini

   Pode-se editar o arquivo `.ini` para definir opções do PHP. Se desejar ter um php.ini em outra localização, utilize `--with-config-file-path=/algum/caminho` no passo 5.

   Se for preferível utilizar o php.ini-production, leia atentamente a lista de modificações desse arquivo, já que ele afeta o comportamento do PHP.

7. Edite o httpd.conf para carregar o módulo do PHP. O caminho à direita da instrução `LoadModule` precisa apontar para o caminho do módulo do PHP no sistema. O make install acima pode ter feito isso automaticamente, mas é bom confirmar.

   No PHP 8:

       LoadModule php_module modules/libphp.so

   No PHP 7:

       LoadModule php7_module modules/libphp7.so

8. Configure o Apache para interpretar certas extensões de arquivos como PHP. Por exemplo, configurar o Apache para interpretar arquivos `.php` como scripts PHP. Em vez de utilizar apenas a diretiva `AddType` do Apache, é recomendado evitar uploads potencialmente perigosos e nomes de arquivos como exploit.php.jpg que possam ser executados como scripts PHP. Nesse exemplo, pode-se ter quaisquer extensões interpretadas como PHP, simplesmente adicionando-as. Adicionaremos `.php` como demonstração.

       <FilesMatch \.php$>
           SetHandler application/x-httpd-php
       </FilesMatch>

   Alternativamente, para permitir que arquivos `.php`, `.php2`, `.php3`, `.php4`, `.php5`, `.php6` e `.phtml` sejam executados como PHP, mas nenhum outro, seria desta forma:

       <FilesMatch "\.ph(p[2-6]?|tml)$">
           SetHandler application/x-httpd-php
       </FilesMatch>

   Para permitir que arquivos `.phps` sejam interpretados pelo filtro de fontes do PHP e exibidos como código fonte destacado, utilize isto:

       <FilesMatch "\.phps$">
           SetHandler application/x-httpd-php-source
       </FilesMatch>

   `mod_rewrite` pode ser utilizado para permitir que qualquer arquivo `.php` seja exibido como código-fonte destacado, sem precisar ser renomeado ou copiado para um arquivo `.phps`:

       RewriteEngine On
       RewriteRule (.*\.php)s$ $1 [H=application/x-httpd-php-source]

   O filtro de fontes PHP não deve ser ativado em ambiente de produção, onde pode expor informações confidenciais ou sensíveis incorporadas no código-fonte.

9. Depois, utilize o procedimento normal de iniciar o servidor Apache, por exemplo:

       /usr/local/apache2/bin/apachectl start

   ou

       service httpd restart

Seguindo os passos acima, o servidor web Apache2 será executado com suporte ao PHP como um módulo `SAPI`. Existem muitas outras opções de configuração disponíveis para o Apache e para o PHP. Para mais informações execute ./configure --help no diretório do código-fonte correspondente.

O Apache pode ser construído com suporte a multi-tarefas através da seleção do MPM worker, em vez do padrão MPM prefork. Isso é possível acrescentado-se a seguinte opção ao argumento passado para ./configure no passo 3 acima:

    --with-mpm=worker

Isto não deve ser feito sem conhecer as consequências desta decisão, ou pelo menos ter uma boa noção de suas implicações. A documentação do Apache sobre » módulos MPM discute essas questões com muito mais detalhes.

> Nota:

> A seção de Perguntas Frequentes do Apache MultiViews discute o uso de MultiViews com o PHP.

> Nota:

> Para construir uma versão multi-tarefa do Apache, o sistema de destino precisa suportar threads. Neste caso, o PHP também deve ser construído com o Zend Thread Safety (ZTS). Nesta configuração, nem todas as extensões estarão disponíveis. A configuração recomendada é construir o Apache com o módulo MPM prefork padrão.

## Nginx 1.4.x em sistemas Unix

Esta documentação cobrirá a instalação e configuração do PHP com PHP-FPM para um servidor HTTP Nginx 1.4.x.

Este guia assume que o Nginx foi construído a partir da fonte e portanto todos os binários e arquivos de configuração estão localizados em `/usr/local/nginx`. Se não for este o caso e o Nginx foi obtido de outro modo então favor se referir à » Wiki Nginx para traduzir este manual para a sua configuração.

Este guia cobrirá o básico da configuração de um servidor Nginx para processar aplicações PHP e servi-las na porta 80. Recomenda-se que a documentação do Nginx e do PHP-FPM seja estudada se for desejado otimizar a configuração além do escopo desta documentação.

Favor notar que, ao longo desta documentação, números de versões foram trocados por um 'x' para assegurar que a informação se mantenha correta no futuro. Favor trocar, conforme necessário, com os números das versões correspondentes.

1. Recomenda-se a visita à página de » instalação da Wiki Nginx para obter e instalar o Nginx no seu sistema.

2. Obtenha e descompacte a fonte do PHP:

       tar zxf php-x.x.x

3. Configure e construa o PHP. Aqui é onde o PHP é customizado com várias opções, como quais extensões serão habilitadas. Execute ./configure --help para uma lista de opções disponíveis. No nosso exemplo faremos uma configuração simples com PHP-FPM e suporte MySQLi.

       cd ../php-x.x.x
       ./configure --enable-fpm --with-mysqli
       make
       sudo make install

4. Obtenha e mova os arquivos de configuração para suas localizações corretas

       cp php.ini-development /usr/local/php/php.ini
       cp /usr/local/etc/php-fpm.d/www.conf.default /usr/local/etc/php-fpm.d/www.conf
       cp sapi/fpm/php-fpm /usr/local/bin

5. É importante evitar que o Nginx passe requisições ao processo interno do PHP-FPM se o arquivo não existe, fazendo com que se impeça a injeção arbitrária de scripts.

   Isto pode ser feito configurando-se a diretiva cgi.fix_pathinfo para `0` no arquivo php.ini.

   Abra o php.ini:

       vim /usr/local/php/php.ini

   Localiza `cgi.fix_pathinfo=` e modifique como a seguir:

       cgi.fix_pathinfo=0

6. php-fpm.conf deve ser modificado para especificar que o php-fpm deve rodar como o usuário www-data e o grupo www-data antes do serviço ser iniciado:

       vim /usr/local/etc/php-fpm.d/www.conf

   Encontre e modifique o seguinte:

       ; Usuário/grupo de processos Unix
       ; Nota: O usuário é mandatório. Se o grupo não for definido, o grupo padrão do usuário
       ;       será usado.
       user = www-data
       group = www-data

   O serviço php-fpm pode agora ser iniciado:

       /usr/local/bin/php-fpm

   Este guia não irá configurar o php-fpm além disso, se houver interesse em configuração adicional do php-fpm favor consultar a documentação.

7. Nginx agora deve ser configurado para suportar o processamento de aplicações PHP:

       vim /usr/local/nginx/conf/nginx.conf

   Modifique o bloco de localização padrão para avisar que ele deve tentar servir arquivos .php:

       location / {
           root   html;
           index  index.php index.html index.htm;
       }

   O próximo passo é assegurar que os arquivos .php são passados ao processo interno do PHP-FPM. Abaixo do bloco comentado de localização padrão do PHP, entre com o seguinte:

       location ~* \.php$ {
           fastcgi_index   index.php;
           fastcgi_pass    127.0.0.1:9000;
           include         fastcgi_params;
           fastcgi_param   SCRIPT_FILENAME    $document_root$fastcgi_script_name;
           fastcgi_param   SCRIPT_NAME        $fastcgi_script_name;
       }

   Reinicie o Nginx.

       sudo /usr/local/nginx/sbin/nginx -s stop
       sudo /usr/local/nginx/sbin/nginx

8. Crie um arquivo de teste

       rm /usr/local/nginx/html/index.html
       echo "<?php phpinfo(); ?>" >> /usr/local/nginx/html/index.php

   Agora navegue até http://localhost. A informação de phpinfo() agora deve ser mostrada.

Ao seguir os passos acima o servidor web Nginx será executado com suporte para PHP como um módulo `SAPI` `FPM`. Obviamente existem muitas opções de configurações adicionais disponíveis para Nginx e PHP. Para mais informação digite ./configure --help na pasta correspondente a cada fonte.

## Lighttpd 1.4 em sistemas Unix

Esta seção contém notas e dicas específicas para instalações Lighttpd 1.4 do PHP em sistemas Unix.

Favor acessar o link » Lighttpd trac para aprender a instalar o Lighttpd adequadamente antes de continuar.

FastCGI é o método SAPI preferido para conectar o PHP ao Lighttpd. FastCGI é habilitado automaticamente no php-cgi.

### Deixando o Lighttpd iniciar processos PHP

Para configurar o Lighttpd para se conectar ao PHP e iniciar processos FastCGI, edite o arquivo lighttpd.conf. Sockets são a maneira preferida de se conectar a processos FastCGI no sistema local.

Exemplo #1 lighttpd.conf parcial

    server.modules += ( "mod_fastcgi" )

    fastcgi.server = ( ".php" =>
      ((
        "socket" => "/tmp/php.socket",
        "bin-path" => "/usr/local/bin/php-cgi",
        "bin-environment" => (
          "PHP_FCGI_CHILDREN" => "16",
          "PHP_FCGI_MAX_REQUESTS" => "10000"
        ),
        "min-procs" => 1,
        "max-procs" => 1,
        "idle-timeout" => 20
      ))
    )

A diretiva bin-path permite ao lighttpd iniciar processos FastCGI dinamicamente. O PHP irá iniciar processos-filhos de acordo com a variável de ambiente PHP_FCGI_CHILDREN. A diretiva `bin-environment` define o ambiente para os processos iniciados. O PHP irá fechar um processo filho depois que o número de requisições especificados por PHP_FCGI_MAX_REQUESTS for alcançado. As diretivas `min-procs` e `max-procs` devem geralmente ser evitadas com o PHP. O PHP gerencia seus próprios processos filhos, e caches opcode como APC somente irão compartilhar dados entre filhos gerenciados pelo PHP. Se `min-procs` for definido para algo maior que `1`, o número total de processos PHP será multiplicado por PHP_FCGI_CHILDREN (2 min-procs * 16 filhos são 32 processos).

### Iniciando processos com spawn-fcgi

Lighttpd fornece um programa chamado spawn-fcgi para tornar a tarefa de iniciar processos FastCGI mais fácil.

### Iniciando processo com php-cgi

É possível iniciar processos sem o spawn-fcgi, porém um pouco mais de esforço é requerido. Configurar a variável de ambiente PHP_FCGI_CHILDREN controla quantos processos filhos do PHP irão iniciar para lidar com as requisições que chegam. Configurar PHP_FCGI_MAX_REQUESTS irá determinar por quanto tempo (em requisições) cada filho ficará ativo. Aqui está um script bash simples para ajudar a iniciar processos PHP.

Exemplo #2 Iniciando processos FastCGI

    #!/bin/sh

    # Localização do binário php-cgi
    PHP=/usr/local/bin/php-cgi

    # Localização do arquivo PID
    PHP_PID=/tmp/php.pid

    # Ligação a um endereço
    #FCGI_BIND_ADDRESS=10.0.1.1:10000
    # Ligação a um socket
    FCGI_BIND_ADDRESS=/tmp/php.sock

    PHP_FCGI_CHILDREN=16
    PHP_FCGI_MAX_REQUESTS=10000

    env -i PHP_FCGI_CHILDREN=$PHP_FCGI_CHILDREN \
           PHP_FCGI_MAX_REQUESTS=$PHP_FCGI_MAX_REQUESTS \
           $PHP -b $FCGI_BIND_ADDRESS &

    echo $! > "$PHP_PID"

### Conectando a instâncias remotas FCGI

Instâncias FastCGI podem ser iniciadas em máquinas remotas múltiplas para expandir aplicações.

Exemplo #3 Conectando a instâncias remotas de php-fastcgi

    fastcgi.server = ( ".php" =>
       (( "host" => "10.0.0.2", "port" => 1030 ),
        ( "host" => "10.0.0.3", "port" => 1030 ))
    )

## Servidores Web LiteSpeed/OpenLiteSpeed em sistemas Unix

LiteSpeed PHP é uma compilação otimizada do PHP construída para funcionar com produtos LiteSpeed através do SAPI LiteSpeed. LSPHP é executado como seu próprio processo e tem seu próprio binário separado, que pode ser utilizado como um simples binário para executar scripts PHP da linha de comando.

O LSAPI é uma API altamente otimizada que permite comunicação entre o LiteSpeed e motores web de terceiros. Seu protocolo é similar ao FCGI, mas é mais eficiente.

Esta documentação cobrirá a instalação e configuração do PHP com LSAPI para um Servidor Web LiteSpeed e um Servidor Web OpenLiteSpeed.

Este guia assume que o LSWS ou o OLS está instalado com seus caminhos e configurações padrões. O diretório padrão de instalação para ambos os servidores web é /usr/local/lsws e ambos podem ser executados do subdiretório bin.

Favor notar que, ao longo desta documentação, números de versões foram trocados por um `x` para assegurar que a informação se mantenha correta no futuro. Favor trocar, conforme necessário, com os números das versões correspondentes.

1. Para obter e instalar o Servidor Web LiteSpeed ou o Servidor Web OpenLiteSpeed, acesse a documentação do LiteSpeed » página de instalação ou a documentação do OpenLiteSpeed » página de instalação.

2. Obtenha e descompacte o código fonte do PHP:

       mkdir /home/php
       cd /home/php
       wget http://us1.php.net/get/php-x.x.x.tar.gz/from/this/mirror
       tar -zxvf php-x.x.x.tar.gz
       cd php-x.x.x

3. Configure e construa o PHP. Aqui é onde o PHP pode ser customizado com várias opções, como quais extensões serão habilitadas. Execute ./configure --help para uma lista de opções disponíveis. No exemplo, serão usadas as opções de configuração padrão recomendadas para o LiteSpeed:

       ./configure ... '--with-litespeed'
       make
       sudo make install

4. Verificando a Instalação do LSPHP

   Uma das maneiras mais simples de verificar se a instalação do PHP teve sucesso é executar o seguinte código:

       cd /usr/local/lsws/fcgi-bin/
       ./lsphp5 -v

   Isso deve retornar informação sobre o novo PHP construído:

       PHP 5.6.17 (litespeed) (built: Mar 22 2016 11:34:19)
       Copyright (c) 1997-2014 The PHP Group
       Zend Engine v2.6.0, Copyright (c) 1998-2015 Zend Technologies

   Note o `litespeed` entre parênteses. Isso significa que o binário PHP foi construído com suporte LSAPI.

Seguindo os passos acima, LiteSpeed / OpenLiteSpeed devem agora estar rodando com suporte ao PHP como uma extensão SAPI. Existem muitas opções de configuração adicionais disponíveis para LSWS / OLS e PHP. Para mais informações, verifique a documentação do LiteSpeed sobre » PHP.

Usando LSPHP pela linha de comando:

LSPHP(LSAPI + PHP) no modo de linha de comando é usado para processar scripts PHP rodando em um servidor remoto que não necessariamente tem um servidor web em execução. É usado para processar scripts PHP que residem em um servidor web local (separado). Esta configuração é adequada para escalabilidade de serviços já que o processamento do PHP é descarregado para um servidor remoto.

Inicie o lsphp da linha de comando em um servidor remoto: LSPHP é um executável e pode ser iniciado manualmente e ligado a IPv4, IPv6 ou endereços de socket no domínio Unix com a opção -b socket_address

Exemplos:

Fazendo o LSPHP se ligar à porta 3000 em todos os endereços IPv4 e IPv6:

    /path/to/lsphp -b [::]:3000

Fazendo o LSPHP se ligar à porta 3000 em todos os endereços IPv4:

    /path/to/lsphp -b *:3000

Fazendo o LSPHP se ligar ao endereço 192.168.0.2:3000:

    /path/to/lsphp -b 192.168.0.2:3000

Fazendo o LSPHP aceitar requisições em socket de domínio Unix `/tmp/lsphp_manual.sock`:

    /path/to/lsphp -b /tmp/lsphp_manual.sock

Variáveis de ambiente podem ser adicionadas antes do executável LSPHP:

    PHP_LSAPI_MAX_REQUESTS=500 PHP_LSAPI_CHILDREN=35 /path/to/lsphp -b IP_address:port

Atualmente o LiteSpeed PHP pode ser usado com os servidoreso web LiteSpeed, OpenLiteSpeed e Apache mod_lsapi. Para os passos sobre a configuração no lado do servidor, visite as páginas de documentação para » LiteSpeed e » OpenLiteSpeed.

LSPHP também pode ser instalado de diversas outras maneiras.

CentOS: No CentOS, LSPHP pode ser instalado a partir do repositório LiteSpeed ou do repositório Remi usando » RPM.

Debian: No Debian, LSPHP pode ser instalado a partir do repositório do LiteSpeed usando » apt.

cPanel: Visite a respectiva » página de documentação. sobre como instalar o LSPHP com cPanel e LSWS/OLS usando EasyApache 4.

Plesk: Plesk pode ser usado com LSPHP no CentOS, CloudLinux, Debian e Ubuntu. Para mais detalhes sobre isso, visite a respectiva » página de documentação.

## Dicas de instalação específicas para o Solaris

Essa seção contém notas e dicas específicas para a instalação do PHP em sistemas Solaris.

### Software Necessário

Instalações do Solaris frequentemente não possuem compiladores C e suas ferramentas relacionadas. Leia esse FAQ para obter informações sobre porque usar versões GNU para algumas dessas ferramentas é necessário.

Para descompactar uma distribuição PHP você precisará de:

- tar
- gzip ou
- bzip2

Para compilar o PHP você precisará de:

- gcc (recomendado, outros compiladores C podem funcionar)
- make
- GNU sed

Para compilar extensões extras ou hackear o código do PHP você também precisará de:

- re2c
- bison
- m4
- autoconf
- automake

Além disso, você pode precisar instalar (e talvez até compilar) softwares específicos à sua configuração, como o Oracle ou MySQL.

### Utilizando pacotes

Você pode simplificar o processo de instalação no Solaris ao utilizar pkgadd para instalar os componentes mais comuns. O Image Packaging System (IPS) para Solaris 11 Express também contém os componentes mais comuns utilizando-se o comando pkg.

# Instalação no macOS

## Índice

- Instalação no macOS usando pacotes de terceiros
- Usando o pacote do PHP no macOS para versões anteriores ao macOS Monterey
- Compilando o PHP no MacOS

O PHP era incluído no macOS nas versões 10 e 11, mas já não é mais incluído desde o macOS versão 12 (Monterey). A instalação em versões mais recentes requer o uso de pacotes de terceiros, ou compilação a partir do código-fonte.

## Instalação no macOS usando pacotes de terceiros

Existem algumas versões do PHP empacotadas e pré-compiladas para o macOS. Isso pode ajudar na instalação de uma configuração padrão, mas se você precisar ter algumas características diferentes (como um servidor seguro, ou um driver de banco de dados diferente), você pode precisar compilar o PHP e/ou seu servidor web por conta própria. Se você não estiver familiarizado com o procedimento de compilar seu próprio software, vale a pena checar se alguém já fez um pacote do PHP com as características que você precisa.

Uma maneira fácil de instalar o PHP no macOS é com o gerenciador de pacotes » Homebrew.

1. Instale o homebrew, seguindo as instruções no site da web.

2. brew install php

Os seguintes recursos alternativos também oferecem pacotes fáceis de instalar e binários pré-compilados para usar o PHP no macOS:

- » MacPorts
- » Fink

## Usando o pacote do PHP no macOS para versões anteriores ao macOS Monterey

O PHP vem incluído com o macOS desde a versão macOS X (10.0.0) até a versão macOS Monterey (12.0.0). Habilitar o PHP no servidor web padrão requer apenas descomentar algumas linhas no arquivo de configuração do Apache (httpd.conf) enquanto que a versão CGI e/ou CLI estão disponíveis automaticamente (facilmente acessíveis pelo Terminal).

Habilitar o PHP usando as instruções abaixo tem como objetivo configurar rapidamente um ambiente de desenvolvimento local. É altamente recomendado sempre atualizar o PHP para a versão mais nova. Como qualquer software ativo, novas versões são criadas para corrigir problemas e adicionar funcionalidades e o PHP não é diferente. As seguintes instruções são direcionadas para iniciantes, os detalhes fornecidos permitem que uma configuração padrão funcione. Todos os usuários são encorajados a compilar ou a instalar uma versão nova do pacote.

O tipo de instalação padrão é usando mod_php, e habilitar o pacote mod_php no macOS para o servidor Apache (o servidor web padrão, que é acessível via Preferências de Sistema) envolve os seguintes passos:

1. Localize e abra o arquivo de configuração do Apache. Normalmente, ele está em: /private/etc/apache2/httpd.conf Usar `Finder` ou `Spotlight` para encontrar esse arquivo pode ser complicado, já que ele normalmente é privado e o dono é o usuário `root`.

   > Nota: Uma maneira de modificar o arquivo é usando um editor de texto baseado em Unix no Terminal, por exemplo `nano` e, como o proprietário do arquivo é o `root`, será usado o comando `sudo`. Para abri-lo (no usuário `root`), digite o seguinte comando no `Terminal` (será necessário digitar a senha): `sudo nano /private/etc/apache2/httpd.conf` Comandos importantes do nano: `^w` (buscar), `^o` (salvar), e `^x` (sair) onde `^` representa a tecla Ctrl.

   > Nota: Versões do Mac OS X anteriores a 10.5 foram empacotadas com versões mais antigas do PHP e do Apache. Devido a isso, o arquivo de configuração do Apache pode estar em /etc/httpd/httpd.conf.

2. Com um editor de texto, descomente as linhas (removendo os #) que parecem com as linhas abaixo (essas duas linhas normalmente não estão juntas, localize ambas no arquivo):

       # LoadModule php5_module libexec/httpd/libphp5.so

       # AddModule mod_php5.c

   Observe a localização/caminho. Quando compilar o PHP no futuro, os arquivos acima devem ser substituídos ou comentados.

3. Certifique-se que as extensões desejadas serão avaliadas como códigos PHP (exemplos: .php, .html e .inc).

   Como a seguinte instrução já existe no httpd.conf (a partir do Mac Panther), uma vez que o PHP for habilitado, os arquivos .php serão automaticamente interpretados como código PHP.

       <IfModule mod_php5.c>
           # If php is turned on, we respect .php and .phps files.
           AddType application/x-httpd-php .php
           AddType application/x-httpd-php-source .phps

           # Since most users will want index.php to work we
           # also automatically enable index.php
           <IfModule mod_dir.c>
               DirectoryIndex index.html index.php
           </IfModule>
       </IfModule>

   > Nota:

   > Antes do OS X 10.5 (Leopard), o PHP 4 vinha empacotado no lugar do PHP 5, neste caso as instruções acima serão um pouco diferentes, mudando de 5 para 4.

4. Assegure-se de que a diretiva DirectoryIndex carrega o arquivo de índice desejado. Isso também é configurável no arquivo httpd.conf. Tipicamente index.php e index.html são usados. Por padrão, index.php é habilitado porque também está na verificação mostrada abaixo. Modifique como desejar.
5. Configure a localização do arquivo php.ini ou use a padrão. Uma localização típica no macOS é /usr/local/php/php.ini e uma chamada à phpinfo() revelará essa informação. Se não for usado um arquivo php.ini, o PHP usará todos os valores padrão. Veja também o FAQ relacionado em encontrando o php.ini.
6. Localize ou configure `DocumentRoot`. Esse é o diretório raiz para todos os arquivos do servidor. Os arquivos nesse diretório serão servidos pelo servidor web, então os arquivos PHP serão interpretados como PHP antes de terem seu resultado enviado para o servidor. Um caminho padrão para isso é /Library/WebServer/Documents mas isso pode ser modificado para qualquer outro no arquivo httpd.conf. Alternativamente, o DocumentRoot para usuários individuais é /Users/yourusername/Sites
7. Crie um arquivo phpinfo().

   A função phpinfo() mostrará informações sobre o PHP. Considere criar um arquivo no DocumentRoot com o seguinte código PHP:

       <?php phpinfo(); ?>

8. Reinicie o Apache e carregue o arquivo PHP criado acima.

   Para reiniciar, execute `sudo apachectl graceful` no shell ou stop/start na opção "Personal Web Server" nas Preferências do Sistema no macOS. Geralmente, carregar arquivos locais no navegador pode ser feito usando uma URL assim: http://localhost/info.php ou se estiver usando o diretório DocumentRoot dentro de um diretório de usuário, seria assim: http://localhost/~yourusername/info.php

A versão CLI (ou CGI em versões mais antigas) tem o nome php e provavelmente está em /usr/bin/php. Abra um terminal, leia a seção sobre linha de comando do manual PHP e execute `php -v` para verificar a versão do PHP usada. Uma chamada ao phpinfo() também revelará essa informação.

## Compilando o PHP no MacOS

Use o Instalação em sistemas Unix para compilar o PHP no MacOS.

# Instalação em sistemas Windows

## Índice

- Configuração recomendada em sistemas Windows
- Instalação Manual de binários pré-compilados
- Instalação para Apache 2.x em sistemas Windows
- Instalação com IIS no Windows
- Ferramentas de terceiros para instalar o PHP
- Compilando a partir dos fontes
- Executando o PHP em linha de comando em sistemas Windows

As versões oficiais do PHP no Windows são as recomendadas para uso em ambiente de produção, mas o PHP também pode ser compilado a partir do código-fonte.

O PHP também pode ser instalado no Azure App Services (também conhecido como Microsoft Azure, Windows Azure, ou (Windows) Azure Web Apps).

A seção de Instalação das Perguntas Frequentes descreve problemas comuns de instalação e configuração que podem ser encontrados.

## Configuração recomendada em sistemas Windows

### OpCache

É altamente recomendado habilitar o OpCache. Esta extensão é incluída no PHP para Windows. Ela compila e otimiza os scripts PHP e os mantém na memória cache para que não sejam compilados toda vez que uma página é carregada.

Configure o php.ini:

Exemplo #1 Configuração recomendada do OpCache

    opcache.enable=On
    opcache.enable_cli=On

Reinicie o servidor web. Para mais informações, consulte: Configuração OpCache

### WinCache

Recomenda-se usar o WinCache se o IIS for usado, especialmente em um ambiente de hospedagem web compartilhado ou em armazenamento de arquivos de rede (NAS). Todas as aplicações PHP se beneficiam automaticamente do recurso de cache de arquivo do WinCache. Operações do sistema de arquivos são armazenadas em cache. WinCache também armazena em cache objetos de usuário e compartilha-os entre os processos php.exe ou php-cgi.exe (compartilha objetos entre requisições). Muitas das grandes aplicações web têm um plugin ou extensão ou opção de configuração para uso do WinCache para cache de objetos de usuário. Se um alto desempenho é requerido, deve-se usar cache de objetos na aplicação. Consulte: » https://pecl.php.net/package/WinCache para baixar uma DLL WinCache (or WINCACHE_*.tgz) para o diretório de extensões do PHP (extension_dir no php.ini). Configure o php.ini:

Exemplo #2 Configuração WinCache recomendada

    extension=php_wincache.dll
    wincache.fcenabled=1
    wincache.ocenabled=1 ; removida a partir do wincache 2.0.0.0

Para mais informações, consulte: Configuração WinCache

## Instalação Manual de binários pré-compilados

### Requisitos de instalação

O PHP está disponível somente para sistemas x86 de 32 bits ou x64 de 64 bits, e atualmente não funciona em Windows RT ou Windows em processadores ARM. A partir da versão 8.3.0, o PHP requer Windows 8 ou Windows Server 2012. Versões posteriores à 7.2.0 requerem Windows 2008 R2 ou Windows 7. Versões anteriores à 7.2.0 suportam Windows 2008 e Vista.

O PHP requer o Visual C Runtime (CRT). Muitas outras aplicações também o requerem, portanto é bem provável que ele já esteja instalado, mas se não estiver, o Microsoft Visual C++ Redistributable para Visual Studio 2022 é adequado para uso com todas as versões do PHP e pode ser » obtido da Microsoft.

O CRT x86 precisa ser obtido para uso com compilações PHP x86 e o CRT x64 para compilações PHP x64. Se o CRT já estiver instalado, o instalador mostrará uma mensagem avisando sobre isso e não fará nenhuma alteração. O instalador do CRT suporta as opções de linha de comando /quiet e /norestart, assim a instalação pode ser feita através de scripts.

### Onde obter os binários do PHP

Binários do Windows podem ser obtidos no » site do PHP para Windows. Todos os binários são otimizados (PGO), e as versões QA e GA são extensamente testadas.

### Extensões PECL pré-compiladas

Versões de extensões PECL pré-compiladas para Windows são distribuídas como arquivos DLL na página PECL da extensão.

Os binários não estão disponíveis para extensões que usam recursos específicos para outros sistemas, como Unix, ou que dependem de bibliotecas que não estão disponíveis no Windows.

### Tipos de Compilação

Existem 4 tipos de compilação do PHP:

- Thread-Safe (TS) - para servidores web de processo único, como Apache com mod_php.

- Non-Thread-Safe (NTS) - para IIS e outros servidores web FastCGI (Apache com mod_fastcgi) e recomendado para scripts de linha de comando.

- x86 - para sistemas de 32 bits.

- x64 - para sistemas de 64 bits.

## Instalação para Apache 2.x em sistemas Windows

Esta seção contém notas e dicas específicas para instalações do Apache 2.x do PHP em sistemas Microsoft Windows.

> Nota:

> Por favor, leia o manual das etapas de instalação primeiro!.

É altamente recomendável consultar a » Documentação Apache para obter uma compreensão básica do Servidor Apache 2.x. Considere, também, a leitura das » notas específicas do Windows para Apache 2.x antes de continuar.

Baixa a versão mais recente do » Apache 2.x e uma versão adequada do PHP. Siga os passos do manual de instalação e volte para prosseguir com a integração do PHP com o Apache.

Existem três maneiras de configurar o PHP para funcionar com o Apache 2.x no Windows. O PHP pode ser executado como um controlador, como um CGI ou em FastCGI.

> Nota: Lembre-se que ao adicionar caminhos nos arquivos de configuração do Apache no Windows, todas as barras invertidas como em c:\diretorio\arquivo.ext devem ser convertidas para barras: c:/diretorio/arquivo.ext. Uma barra final também pode ser necessária para diretórios.

### Instalando como um controlador Apache

> Nota: Ao usar o SAPI apache2handler SAPI, a versão segura para Threads (TS) do PHP precisa ser usada.

Para carregar o módulo PHP para Apache 2.x, as seguintes linhas no arquivo de configuração Apache httpd.conf precisam ser inseridas:

Exemplo #1 PHP e Apache 2.x como controlador

    # antes do PHP 8.0.0 o nome do módulo era php7_module
    LoadModule php_module "c:/php/php8apache2_4.dll"
    <FilesMatch \.php$>
        SetHandler application/x-httpd-php
    </FilesMatch>
    # configure caminho para php.ini
    PHPIniDir "C:/php"

> Nota: O caminho correto do PHP precisa ser substituído em vez de C:/php/ nos exemplos acima. Certifique-se de que o arquivo referenciado na diretiva `LoadModule` está no local especificado. Use php7apache2_4.dll para PHP 7, ou php8apache2_4.dll para PHP 8.

### Executando PHP como CGI

É altamente recomendável consultar a » documentação Apache CGI para uma compreensão mais completa da execução de CGI no Apache.

Para executar o PHP como CGI, os arquivos php-cgi precisarão ser colocados em um diretório designado como um diretório CGI usando a diretiva ScriptAlias.

Uma linha iniciada com `#!` precisará ser colocada nos arquivos PHP que apontam para a localização do binário do PHP:

Exemplo #2 PHP e Apache 2.x como CGI

    #!C:/php/php.exe
    <?php
        phpinfo();
    ?>

Aviso

Um servidor instalado em modo CGI está aberto a várias vulnerabilidades possíveis. Leia nossa seção de segurança CGI para aprender como se defender de tais ataques.

### Executando PHP sobre FastCGI

Executar o PHP no FastCGI tem uma série de vantagens sobre executá-lo como um CGI. Configurá-lo dessa forma é bastante simples:

Baixe `mod_fcgid` de » https://www.apachelounge.com. Os binários do Win32 estão disponíveis para download neste site. Instale o módulo de acordo com as instruções que o acompanham.

Configure o servidor web conforme mostrado abaixo, tendo o cuidado de ajustar quaisquer caminhos para refletir ele está instalado no sistema:

Exemplo #3 Configurando o Apache para executar o PHP como FastCGI

    LoadModule fcgid_module modules/mod_fcgid.so
    # Onde está o arquivo php.ini?
    FcgidInitialEnv PHPRC        "c:/php"
    <FilesMatch \.php$>
        SetHandler fcgid-script
    </FilesMatch>
    FcgidWrapper "c:/php/php-cgi.exe" .php

Arquivos com extensão `.php` agora serão executados pelo empacotador PHP FastCGI.

## Instalação com IIS no Windows

### Instalando o IIS

Internet Information Services (IIS) é incluído no Windows. No Windows Server, a função IIS pode ser adicionada através do Gerenciador do Servidor. O recurso CGI Role precisa ser incluído. No Windows Desktop, o IIS deve ser adicionado através da opção Adicionar/Remover Programas do Painel de Controle. A documentação da Microsoft tem » instruções detalhadas para habilitar o IIS. Para desenvolvimento, o » IIS/Express também pode ser usado.

> Nota: A versão Não Segura para Threads (NTS) do PHP deve ser instalada ao usar o manipulador FastCGI com o IIS.

### Configurando o PHP com o IIS

No Gerenciador IIS, instale o módulo FastCGI e adicione um manipulador para mapear a extensão `.php` para o caminho do php-cgi.exe (não para o php.exe).

A ferramenta de linha de comando APPCMD pode ser usada para executar a configuração do IIS através de script.

### Exemplo de script em lote

Exemplo #1 Linha de comando para configurar o IIS e o PHP

    @echo off

    REM obtenha o arquivo .ZIP da compilação PHP em http://windows.php.net/downloads/

    REM caminho para o diretório onde o arquivo .ZIP do PHP foi descompactado (sem \ no final)
    set phppath=c:\php

    REM Limpa os manipuladores de PHP atuais
    %windir%\system32\inetsrv\appcmd clear config /section:system.webServer/fastCGI
    REM O comando a seguir irá gerar uma mensagem de erro se o PHP não estiver instalado. Isto pode ser ignorado.
    %windir%\system32\inetsrv\appcmd set config /section:system.webServer/handlers /-[name='PHP_via_FastCGI']

    REM Configura o manipulador do PHP
    %windir%\system32\inetsrv\appcmd set config /section:system.webServer/fastCGI /+[fullPath='%phppath%\php-cgi.exe']
    %windir%\system32\inetsrv\appcmd set config /section:system.webServer/handlers /+[name='PHP_via_FastCGI',path='*.php',verb='*',modules='FastCgiModule',scriptProcessor='%phppath%\php-cgi.exe',resourceType='Unspecified']
    %windir%\system32\inetsrv\appcmd set config /section:system.webServer/handlers /accessPolicy:Read,Script

    REM Configura as variáveis FastCGI
    %windir%\system32\inetsrv\appcmd set config -section:system.webServer/fastCgi /[fullPath='%phppath%\php-cgi.exe'].instanceMaxRequests:10000
    %windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi /+"[fullPath='%phppath%\php-cgi.exe'].environmentVariables.[name='PHP_FCGI_MAX_REQUESTS',value='10000']"
    %windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi /+"[fullPath='%phppath%\php-cgi.exe'].environmentVariables.[name='PHPRC',value='%phppath%\php.ini']"

## Ferramentas de terceiros para instalar o PHP

Aviso

Compilações de terceiros são consideradas não oficiais e não são suportadas diretamente pelo projeto PHP. Quaisquer problemas encontrados devem ser relatados ao fornecedor dessas compilações não oficiais, a menos que possam ser reproduzidos usando as compilações da » área de download oficial.

» XAMPP, » WampServer, e » Bitnami também irão configurar aplicações PHP para uso com Apache no Windows.

## Compilando a partir dos fontes

Consulte as » instruções de compilação passo a passo para compilar com o Visual Studio.

## Executando o PHP em linha de comando em sistemas Windows

Esta seção contém notas e dicas específicas para que o PHP seja executado da linha de comando do Windows.

> Nota:

> Leia os passos de instalação manual primeiro!

Configurar o PHP para ser executado da linha de comando pode ser feito sem nenhuma mudança no Windows.

    C:\php\php.exe -f "C:\PHP Scripts\script.php" -- -arg1 -arg2 -arg3

Porém há alguns passos fáceis que podem ser seguidos para tornar o processo mais simples. Alguns desses passos podem já ter sido executados, mas estão repetidos aqui para fornecer uma sequência completa, passo a passo.

> Nota:

> PATH e PATHEXT são variáveis importantes de sistema pré-existentes no Windows, e deve-se tomar cuidado para não sobrescrever nenhuma das duas, apenas concatenar valores.

- Concatene a localização do executável do PHP (php.exe, php-win.exe ou php-cli.exe dependendo da versão do PHP e preferências de visualização) à variável de ambiente PATH. Leia mais sobre como adicionar a pasta do PHP à variável PATH na entrada FAQ correspondente.

- Adicione a extensão `.PHP` à variável de ambiente PATHEXT. Isto pode ser feito ao mesmo tempo que se adiciona à variável PATH. Siga os mesmos passos descritos no FAQ mas adicione à variável PATHEXT no lugar da variável PATH.

  > Nota:

  > A posição onde a extensão `.PHP` for inserida irá determinar qual script ou programa será executado quando o nome do arquivo for especificado. Por exemplo, inserir `.PHP` antes de `.BAT` irá fazer com que o script seja executado, em vez do arquivo de lote, se existir um arquivo de lote com o mesmo nome.

- Associe a extensão `.PHP` com o tipo de arquivo. Isto pode ser feito executando o seguinte comando:

      assoc .php=phpfile

- Associe o tipo de arquivo `phpfile` com o executável PHP apropriado. Isto pode ser feito executando o seguinte comando:

      ftype phpfile="C:\php\php.exe" -f "%1" -- %~2

Seguir estes passos irá permitir que os scripts PHP sejam executados de qualquer pasta sem a necessidade de digitar o executável PHP ou a extensão `.PHP` e todos os parâmetros serão fornecidos ao script para processamento.

O exemplo abaixo detalha algumas das alterações de registro que podem ser realizadas manualmente.

Exemplo #1 Alterações de Registro

    Windows Registry Editor Version 5.00

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\.php]
    @="phpfile"
    "Content Type"="application/php"

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile]
    @="PHP Script"
    "EditFlags"=dword:00000000
    "BrowserFlags"=dword:00000008
    "AlwaysShowExt"=""

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\DefaultIcon]
    @="C:\\php\\php-win.exe,0"

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell]
    @="Open"

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell\Open]
    @="&Open"

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell\Open\command]
    @="\"C:\\php\\php.exe\" -f \"%1\" -- %~2"

Com estas alterações o mesmo comando pode ser escrito como:

    "C:\PHP Scripts\script" -arg1 -arg2 -arg3

ou, se o diretório `"C:\PHP Scripts"` estiver na variável de ambiente PATH:

    script -arg1 -arg2 -arg3

> Nota:

> Existe um pequeno problema se a intenção for usar esta técnica e usar os scripts PHP como um filtro de linha de comando, como o exemplo abaixo:

>     dir | "C:\PHP Scripts\script" -arg1 -arg2 -arg3

> ou

>     dir | script -arg1 -arg2 -arg3

> Neste caso, o script poderá simplesmente travar e não produzir nenhuma saída. Para tornar esta opção operacional, deve-se fazer uma outra alteração no registro.

>     Windows Registry Editor Version 5.00

>     [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\policies\Explorer]
>     "InheritConsoleHandles"=dword:00000001

> Mais informações sobre este problema podem ser encontradas no artigo » Microsoft Knowledgebase Article : 321788. A partir do Windows 10, esta configuração foi invertida, fazendo com que a instalação padrão do Windows 10 suporte automaticamente esta opção. Esta postagem do » Microsoft Forum fornece a explicação.

# Instalação em Plataformas de Computação em Nuvem

## Índice

- Azure App Services
- Amazon EC2
- DigitalOcean

É possível instalar o PHP na nuvem. Para a nuvem PHP!

## Azure App Services

O PHP é frequentemente utilizado no Azure App Services (também conhecido como Microsoft Azure, Windows Azure, Azure Web Apps).

O Azure App Services gerencia pools de Servidores Web Windows para hospedar uma aplicação web, como uma alternativa ao gerenciamento do próprio servidor web do usuário em suas próprias VMs Azure Compute ou outros servidores.

O PHP já está automaticamente habilitado para o site web do Azure App Services. No Portal Azure, selecionando o site web pode-se escolher qual versão do PHP será usada. Uma versão mais recente que a padrão pode ser escolhida.

Como tal, o PHP e suas extensões serão executados no Azure App Services, assim como serão em outros servidores Windows. No entanto, a interface de gerenciamento para o Azure App Services é diferente:

- Portal Azure: criar, editar configurações e excluir sites web. » Portal Azure

- Dashboard Kudu: se o site tem a URL `nome_do_site.azurewebsites.net`, o Dashboard Kudu será `https://nome_do_site.scm.azurewebsites.net/`. O Dashboard dá acesso a algumas capacidades de depuração, gerenciamento de arquivos e extensões de site. As extensões de site são um mecanismo do Azure para adicionar programas extras, como compilações de pré-visualização do PHP, ao site web.

- Não podem ser usados o Gerenciador do IIS, o Gerenciador de Servidores ou o RDP.

Há também um SDK do PHP para programaticamente usar vários Azure Services a partir do código PHP. Consulte o » SDK do Azure para PHP.

Para obter mais informações, consulte o » Centro de Desenvolvedores PHP do Azure

### WinCache

O WinCache está habilitado por padrão no Azure App Services e é recomendado que fique habilitado. Se for instalada uma compilação customizada do PHP, deve-se habilitar o WinCache nela também.

### Compilação Customizada do PHP

Pode ser feito o envio de uma compilação customizada para D:\Home (C:\ NÃO é gravável). Em seguida, no Portal Azure, deve-se definir SCRIPT_PROCESSOR para .php como o caminho absoluto do arquivo php-cgi.exe nessa compilação.

## Amazon EC2

É possível instalar o PHP na » plataforma em nuvem EC2.

Veja também o » AWS SDK para PHP.

## DigitalOcean

DigitalOcean oferece as seguintes plataformas para instalação do PHP, e para executar aplicações web em sua infraestrutura de hospedagem em nuvem.

- » Cloudways: Implantação em um clique das principais aplicações PHP: WordPress, Magento, Drupal, Laravel, e mais.

- » Droplet: Máquinas virtuais e instalação do » Lamp em um servidor Linux .

- » Plataforma de Aplicações: Infraestrutura gerenciada para construir, implantar e escalar aplicações rapidamente. Aprenda » como executar aplicações PHP na Plataforma de Aplicações .

- » Funções: Plataforma sem servidor que permite aos desenvolvedores executar código sem provisionar ou manter servidores. O PHP é suportado de forma nativa. Aprenda » como criar funções sem servidores no PHP .

# FastCGI Process Manager (FPM)

## Índice

- Instalação
- Configuração

FPM (FastCGI Process Manager) é uma implementação PHP primária do FastCGI contendo alguns recursos úteis (principalmente) para sites pesados.

Entre as features estão incluídas:

- gerenciamento de processos avançado com stop/start;

- habilidade para começar a trabalhar com uid/gid/chroot/environment diferentes, ouvindo em diferentes portas e utilizando-se de php.ini distintos (troca de safe_mode);

- stdout e stderr logging configuráveis;

- reinício de emergência em caso de destruição acidental de opcode cache;

- acelera o processo de upload;

- "slowlog - log dos scripts (não apenas seus nomes, mas os backtraces PHP também, utilizando ptrace ou semelhantes para ler dados do processo remoto) ainda que sejam lentos de coletar;

- fastcgi_finish_request() - função especial para finalizar a requisição e enviar todos os dados, ao mesmo tempo continuando a fazer algo potencialmente demorado (conversão de vídeo, processamento de estatísticas, etc);

- criação de processos estático/dinâmico/sob demanda;

- informações de status básicas e estendidas (similar ao Apache mod_status) em vários formatos suportados, como: json, xml e openmetrics;

- php.ini-baseado em arquivos de configurações.

## Instalação

### Compilando o código fonte

Para habilitar o FPM na compilação do PHP deve ser adicionada a opção `--enable-fpm` na linha do comando "configure".

Há várias outras opções de configuração específicas para o FPM (todas opcionais):

- `--with-fpm-user` - configura o usuário FPM (padrão - nobody).

- `--with-fpm-group` - configura o grupo FPM (padrão - nobody).

- `--with-fpm-systemd` - Ativa a integração com o systemd (padrão - no).

- `--with-fpm-acl` - Usa Access Control Lists do POSIX (padrão - no).

- `--with-fpm-apparmor` - Ativa a integração com o AppArmor (padrão - no).

- `--with-fpm-selinux` - Ativa a integração com o SELinux (padrão - no).

### Registro de Alterações

Versão | Descrição
--- | ---
8.2.0 | A opção `--with-fpm-selinux` foi adicionada.
8.0.0 | A opção `--with-fpm-apparmor` foi adicionada.

## Configuração

FPM usa a sintaxe do php.ini para seus arquivos de configuração - php-fpm.conf, e para arquivos de configuração de conjuntos.

### Lista de diretivas globais php-fpm.conf

`pid` string

  Caminho para o arquivo PID. Valor padrão: nenhum.

`error_log` string

  Caminho para o arquivo de registro de erro. Valor padrão: `#INSTALL_PREFIX#/log/php-fpm.log`. Se configurado como "syslog", o registro será enviado para o syslogd em vez de ser escrito em um arquivo local.

`log_level` string

  Nível de registro de erro. Valores possíveis: alert, error, warning, notice, debug. Valor padrão: notice.

`log_limit` int

  Limite de tamanho das linhas de registro para permitir mensagens maiores que 1024 caracteres sem quebras. Valor padrão: 1024. Disponível desde o PHP 7.3.0.

`log_buffering` bool

  Log sem buffer extra (experimental). Valor padrão: yes. Disponível desde o PHP 7.3.0.

`syslog.facility` string

  Usado para especificar que tipo de programa está registrando a mensagem. Valor Padrão: daemon.

`syslog.ident` string

  String incluída no início de cada mensagem. Se houver múltiplas instâncias do FPM em execução no mesmo servidor, pode-se alterar o valor padrão para adaptar-se às necessidades. Valor padrão: php-fpm.

`emergency_restart_threshold` int

  Se esse número de processos filho sair com SIGSEGV ou SIGBUS dentro do intervalo de tempo definido pelo `emergency_restart_interval`, o FPM será reiniciado. Um valor 0 significa 'desligado'. Valor padrão: 0 (desligado).

`emergency_restart_interval` mixed

  Intervalo de tempo utilizado por `emergency_restart_interval` para determinar quando um reinício será feito. Pode ser útil para contornar corrupções acidentais em memória compartilhada de um acelerador. Unidades disponíveis: s(egundos), m(inutos), h(oras), ou d(ias). Unidade Padrão: segundos. Valor padrão: 0 (desligado).

`process_control_timeout` mixed

  Tempo limite para processos filhos esperarem por uma reação nos sinais do principal. Unidades disponíveis: s(egundos), m(inutos), h(oras) ou d(ias). Unidade Padrão: segundos. Valor padrão: 0.

`process.max` int

  O número máximo de processos que o FPM iniciará. Foi projetado para controlar o número global de processos ao utilizar gerenciamento dinâmico de processos em vários pools. Utilize com cautela. Valor padrão: 0.

`process.priority` int

  Especifica a prioridade de nice(2) a ser aplicada ao processo principal (somente se estiver configurado). O valor pode variar entre -19 (maior prioridade) e 20 (menor prioridade). Valor padrão: não definido.

`daemonize` bool

  Envia o FPM para execução em segundo plano. Defina como 'no' para manter o FPM em primeiro plano para fins de depuração. Valor padrão: yes.

`rlimit_files` int

  Define o limite de descritores de arquivos abertos para o processo principal. Valor padrão: valor definido pelo sistema operacional.

`rlimit_core` int

  Define o limite máximo do tamanho do núcleo do processo principal. Valor padrão: 0.

`events.mechanism` string

  Especifica o mecanismo de eventos que o FPM utilizará. Os seguintes estão disponíveis: epoll, kqueue (*BSD), port (Solaris), poll e select. Valor padrão: não definido (detecção automática com preferência para epoll e kqueue).

`systemd_interval` int

  Quando o FPM for compilado com integração ao systemd, especifica o intervalo, em segundos, entre notificações de relatório de saúde ao systemd. Defina com 0 para desabilitar. Valor padrão: 10.

### Lista de diretivas de conjuntos

Com o FPM, pode-se executar vários conjuntos (pools) de processos com configurações diferentes. Essas são as configurações que podem ser otimizadas por cada conjunto.

`listen` string

  O endereço onde as requisições FastCGI serão aceitas. Sintaxes válidas são: 'en.dere.ço.ip:porta', 'porta', '/caminho/para/soquete/unix'. Esta opção é obrigatória para cada conjunto.

`listen.backlog` int

  Define o acúmulo de listen(2). O valor de `-1` significa o máximo em sistemas BSD;. Valor padrão: `-1` (FreeBSD ou OpenBSD) ou `511` (Linux e outras plataformas).

`listen.allowed_clients` string

  Lista de endereços IPv4 ou IPv6 de clientes FastCGI que estão autorizados a conectar. Equivalente à variável de ambiente FCGI_WEB_SERVER_ADDRS no FastCGI original do PHP (5.2.2+). Só faz sentido com um soquete de escuta TCP. Cada endereço deve ser separado por uma vírgula. Se este valor for deixado em branco, conexões serão aceitas a partir de qualquer endereço IP. Valor padrão: não definido (qualquer endereço IP aceito).

`listen.owner` string

  Define permissões para soquete Unix, se utilizado. No Linux, permissões de leitura/gravação devem ser definidas de forma a permitir conexões a partir de um servidor web. Muitos sistemas derivados do BSD permitem conexões independentemente das permissões. Valores padrão: usuários e grupos são definidos como o usuário que está executando, o modo é definido como 0660.

`listen.group` string

  Veja `listen.owner`.

`listen.mode` string

  Veja `listen.owner`.

`listen.acl_users` string

  Quando o suporte ao Access Control Lists POSIX for suportado, pode-se configurá-lo utilizando esta opção. Ao configurá-lo, `listen.owner` e `listen.group` serão ignorados. Seu valor é uma lista de nomes de usuários, separados por vírgula.

`listen.acl_groups` string

  Veja `listen.acl_users`. Seu valor é uma lista de nomes de grupo, separados por vírgula.

`listen.setfib` int

  Define a tabela de roteamento associada (FIB). Somente FreeBSD. Valor padrão: `-1`. Desde o PHP 8.2.0.

`user` string

  Usuário Unix dos processos FPM. Esta opção é obrigatória.

`group` string

  Grupo Unix dos processos FPM. Se não for definido, o grupo padrão do usuário será utilizado.

`pm` string

  Define como o gerenciador de processos controlará o número de processos filhos. Valores possíveis: `static`, `ondemand` ou `dynamic`. Esta opção é obrigatória.

  `static` - o número de processos filho é fixo (`pm.max_children`).

  `ondemand` - os processos são criados sob demanda (quando solicitado, em oposição a "dynamic", onde `pm.start_servers` são iniciados quando o serviço é iniciado). `dynamic` - o número de processos filhos é definido dinamicamente com base nas seguintes diretivas: `pm.max_children`, `pm.start_servers`, `pm.min_spare_servers` e `pm.max_spare_servers`.
`pm.max_children` int
  O número de processos filhos a serem criados quando `pm` está definido como `static` e o número máximo de processos filhos a serem criados quando `pm` está definido como `dynamic` ou `ondemand`. Esta opção é obrigatória.

  Esta opção define o limite para o número de solicitações simultâneas que serão servidas. Equivalente à diretiva ApacheMaxClients com mpm_prefork e à variável de ambiente PHP_FCGI_CHILDREN no FastCGI original do PHP.

`pm.start_servers` int

  O número de processos filhos criados na inicialização. Usado apenas quando `pm` é definido para `dynamic`. Valor padrão: (min_spare_servers + max_spare_servers) / 2.

`pm.min_spare_servers` int

  O número mínimo desejado de processos servidores ociosos. Usado apenas quando `pm` está definido como `dynamic`. Também é obrigatório neste caso.

`pm.max_spare_servers` int

  O número máximo desejado de processos servidores ociosos. Usado apenas quando `pm` está definido como `dynamic`. Também é obrigatório neste caso.

`pm.max_spawn_rate` int

  A taxa de criação de processos filhos simultaneamente. Utilizado apenas quando `pm` é definido para `dynamic`. Valor padrão: 32

`pm.process_idle_timeout` mixed

  O número de segundos após o qual um processo ocioso será encerrado. Utilizado apenas quando `pm` é configurado como `ondemand`. Unidades disponíveis: s(egundos) - padrão, m(inutos), h(oras) ou d(ias). Valor padrão: 10s.

`pm.max_requests` int

  O número de solicitações que cada processo filho deve executar antes de ressurgir. Isto pode ser útil para contornar vazamentos de memória em bibliotecas de terceiros. Para processamento interminável de solicitação especifique '0'. Equivalente a PHP_FCGI_MAX_REQUESTS. Valor padrão: 0.

`pm.status_listen` string

  O endereço no qual serão aceitas requisições de status FastCGI. Isto cria um novo conjunto invisível que pode manipular as requisições independentemente. Útil se o conjunto principal está ocupado com requisições longas dado que é possível obter a página de status FPM antes de terminar essas requisições longas. A sintaxe é a mesma da diretiva listen. Valor padrão: none.

`pm.status_path` string

  O URI para visualizar a página de status do FPM. Este valor precisa começar com uma contra barra (/). Se o valor não estiver definido, nenhuma URI será reconhecida como uma página de status. Valor padrão: none.

`ping.path` string

  O URI de ping para chamar a página de monitoramento do FPM. Se este valor não estiver definido, nenhum URI será reconhecido como uma página de ping. Isto poderia ser usado para testar de fora que o FPM está vivo e respondendo. Observe que o valor deve começar com uma barra (/).

`ping.response` string

  Esta diretiva pode ser usada para personalizar a resposta a um pedido de ping. A resposta é formatada como text/plain com um código de resposta 200. Valor padrão: pong.

`process.priority` int

  Especifica a prioridade de nice(2) a ser aplicada ao processo (somente se informado). Esse valor pode variar de -19 (prioridade máxima) a 20 (prioridade mínima). Valor padrão: não definido.

`process.dumpable` bool

  Configura o sinalizador de despejo (PR_SET_DUMPABLE prctl) mesmo no caso do usuário ou ou grupo do processo for diferente usuário do processo principal. Permite criar despejos do núcleo do processo e rastrear o processo para o usuário do conjunto. Valor padrão: no. Desde o PHP 7.0.29, 7.1.17 e 7.2.5.

`prefix` string

  Especifica um prefixo para interpretação de caminhos.

`request_terminate_timeout` mixed

  O tempo limite para servir uma requisição única após o qual o processo será encerrado. Esta opção deveria ser usada quando a opção INI 'max_execution_time', não parar a execução do script por algum motivo. Um valor de '0' significa 'Off'. Unidades disponíveis: s(egundos) - padrão, m(inutos), h(oras) ou d(ias). Valor padrão: 0.

`request_terminate_timeout_track_finished` bool

  O limite de tempo configurado para request_terminate_timeout não é disparado depois de um fastcgi_finish_request ou quando a aplicação terminou e funções internas de desligamento estão sendo chamadas. Esta diretiva irá habilitar o limite de tempo incondicionalmente mesmo para esses casos. Valor padrão: no. Desde o PHP 7.3.0.

`request_slowlog_timeout` mixed

  O tempo limite para servir uma requisição única após o qual um rastreamento PHP será despejado para o arquivo 'slowlog'. Um valor de '0' significa 'Off'. Unidades disponíveis: s(egundos) - padrão, m(inutos), h(oras) ou d(ias). Valor padrão: 0.

`request_slowlog_trace_depth` int

  A profundidade do rastreamento de pilha para o registro de requisições lentas. Valor padrão: 20. Desde o PHP 7.2.0.

`slowlog` string

  O arquivo de log de requisições lentas. Valor padrão: `#INSTALL_PREFIX#/log/php-fpm.log.slow`.

`rlimit_files` int

  Define o limite de descritores de arquivos abertos para processos filhos neste conjunto. Valor padrão: valor definido pelo sistema.

`rlimit_core` int

  Define o limite máximo do tamanho do núcleo para processos filhos neste conjunto. Valores possíveis: 'unlimited' ou um número inteiro maior ou igual a 0. Valor padrão: valor definido pelo sistema.

`chroot` string

  Realiza um chroot para este diretório na inicialização. Este valor precisa ser definido como um caminho absoluto. Quando este valor não está definido, chroot não é usado.

`chdir` string

  Realiza um chdir neste diretório na inicialização. Este valor precisa ser um caminho absoluto. Valor padrão: diretório atual ou / no caso de chroot.

`catch_workers_output` bool

  Redireciona stdout e stderr para o registro de erros principal. Se não estiver definido, stdout e stderr serão redirecionadas para /dev/null de acordo com especificações FastCGI. Valor padrão: no.

`decorate_workers_output` bool

  Ativa a decoração de saída dos processos quando catch_workers_output estiver ativo. Valor padrão: yes. Disponível desde o PHP 7.3.0.

`clear_env` bool

  Limpa o ambiente nos processos do FPM. Evita que variáveis de ambiente arbitrárias alcancem os processos do FPM limpando o ambiente neles antes que as variáveis de ambientes especificados nesta configuração de conjunto sejam adicionadas. Valor padrão: Yes.

`security.limit_extensions` string

  Limita as extensões de arquivo do script principal que o FPM permitirá a interpretação. Isto pode evitar erros de configurações no lado do servidor web. FPM deve ser limitado a extensões .php para evitar que usuários maliciosos utilizem outras extensões para executar códigos php. Valor padrão: .php .phar

`apparmor_hat` string

  Se o AppArmor estiver ativo, isto permite modificar o "hat". Valor padrão: não definido.

`access.log` string

  O arquivo de registro de acessos. Valor padrão: não definido.

`access.format` string

  O formato do registro de acessos. Valor padrão: `"%R - %u %t \"%m %r\" %s"`:

  Opções válidas
  Marcador | Descrição
  --- | ---
  `%%` | Caractere `%`
  `%C` | %CPU usado pela requisição. Aceita estes formatos: `%{user}C` somente para CPU de usuário, `%{system}C` somente para CPU de sistema e `%{total}C` para CPU de usuário + sistema (padrão)
  `%d` | Tempo decorrido para servir a requisição. Aceita os seguintes formatos de precisão: `%{seconds}d` (segundos - padrão), `%{milliseconds}d` (milissegundos) e `%{microseconds}d` (microssegundos).
  `%{nome}e` | Uma variável de ambiente (o mesmo que $_ENV ou $_SERVER). O nome da variável de ambiente precisa ser informado entre chaves. Por exemplo, variáveis específicas de servidor como `%{REQUEST_METHOD}e` ou `%{SERVER_PROTOCOL}e`, cabeçalhos HTTP como `%{HTTP_HOST}e` ou `%{HTTP_USER_AGENT}e`.
  `%f` | Nome do arquivo do script
  `%l` | `Content-Length` da requisição (somente para requisições HTTP POST)
  `%m` | Método de requisição HTTP
  `%M` | Pico de memória alocada pelo PHP. Pode aceitar os seguintes formatos: `%{bytes}M` (padrão), `%{kilobytes}M` `%{kilo}M`, `%{megabytes}M` ou `%{mega}M`.
  `%n` | Nome do conjunto
  `%{nome}o` | Cabeçalho de saída. O nome do cabeçalho precisa ser especificado entre chaves. Por exemplo: `%{Content-Type}o`, `%{X-Powered-By}o`, `%{Transfer-Encoding}o`.
  `%p` | PID do processo filho que serviu à requisição
  `%P` | PID do processo pai do processo filho que serviu à requisição
  `%q` | String de consulta
  `%Q` | O caractere `'?'` ou a junção de `%q` e `%r`, se a string de consulta existir
  `%r` | URI de requisição sem a string de consulta, consulte `%q` e `%Q`
  `%R` | Endereço IP remoto
  `%s` | Status (código de resposta)
  `%t` | Horário do servidor em que a requisição foi recebida. Pode aceitar um formato de `strftime(3)`: `%d/%b/%Y:%H:%M:%S %z` (padrão). O formato `strftime(3)` precisa ser encapsulado em uma etiqueta `%{<strftime_format>}t`, por exemplo, para uma string de horário formatada em ISO8601, use: `%{%Y-%m-%dT%H:%M:%S%z}t`
  `%T` | Horário em que o registro foi preenchido (ao término da requisição). Pode aceitar um formato `strftime(3)`: `%d/%b/%Y:%H:%M:%S %z` (padrão). O formato `strftime(3)` precisa ser encapsulado em uma etiqueta `%{<strftime_format>}T`, por exemplo, para uma string de horário formatada em ISO8601, use: `%{%Y-%m-%dT%H:%M:%S%z}T`
  `%u` | Usuário autenticado pelo acesso básico, se especificado no cabeçalho `Authorization`

`access.suppress_path` array

  Uma lista de valores de URI de requisição que devem ser filtrados do registro de acessos. Valor padrão: não definido. Desde o PHP 8.2.0.

É possível passar variáveis de ambiente adicionais e atualizar as configurações do PHP de um determinado conjunto. Para fazer isso, precisa-se adicionar as seguintes opções no arquivo de configuração do conjunto.

Exemplo #1 Passando variáveis de ambiente e configurações do PHP para o conjunto

    env[HOSTNAME] = $HOSTNAME
    env[PATH] = /usr/local/bin:/usr/bin:/bin
    env[TMP] = /tmp
    env[TMPDIR] = /tmp
    env[TEMP] = /tmp

    php_admin_value[sendmail_path] = /usr/sbin/sendmail -t -i -f www@my.domain.com
    php_flag[display_errors] = off
    php_admin_value[error_log] = /var/log/fpm-php.www.log
    php_admin_flag[log_errors] = on
    php_admin_value[memory_limit] = 32M

Configurações do PHP feitas com `php_value` ou `php_flag` irão sobrescrever o valor anterior. Observe que a definição de disable_functions não irá substituir os valores previamente definidos no php.ini, mas adicionará o novo valor em seu lugar.

Configurações definidas com `php_admin_value` e `php_admin_flag` não podem ser sobrescritas com ini_set().

Configurações do PHP podem ser definidas no servidor web.

Exemplo #2 Definindo as configurações de PHP no nginx.conf

    set $php_value "pcre.backtrack_limit=424242";
    set $php_value "$php_value \n pcre.recursion_limit=99999";
    fastcgi_param  PHP_VALUE $php_value;

    fastcgi_param  PHP_ADMIN_VALUE "open_basedir=/var/www/htdocs";

Cuidado

Como essas configurações são passadas para o php-fpm como cabeçalhos FastCGI, o php-fpm não deve ser vinculado a um endereço amplamente acessível. Caso contrário, qualquer um poderá alterar as opções de configuração do PHP. Veja também: listen.allowed_clients.

> Nota: Conjuntos não são um mecanismo de segurança, dado que eles não fornecem uma separação total; por exemplo, todos os conjuntos utilizam uma única instância do OPcache.

# Instalação das extensões PECL

## Índice

- Introdução às Instalações PECL
- Baixando extensões PECL
- Instalando uma extensão PHP no Windows
- Compilando extensões PECL compartilhadas com o comando pecl
- Compilando extensões PECL compartilhadas com phpize
- php-config
- Compilando extensões PECL estaticamente no PHP

## Introdução às Instalações PECL

> Nota: PHP Installer for Extensions (PIE) é uma nova ferramenta que tornará o PECL obsoleto. É recomendado usar o PIE para instalar extensões. Descubra mais em » https://github.com/php/pie

» PECL é um repositório de extensões PHP disponibilizadas através do sistema de pacotes » PEAR. Esta seção do manual destina-se a demonstrar como obter e instalar extensões PECL.

Estas instruções assumem que `/path/to/php/src/dir/` seja o caminho para o código-fonte do PHP e que `extname` seja o nome da extensão PECL. Ajuste adequadamente. Estas instruções também assumem uma familiaridade com o » comando pear. As informações no manual do PEAR para o comando pear também se aplicam ao comando pecl.

Uma extensão compartilhada deve ser compilada, instalada e carregada para ser útil. Os métodos descritos abaixo fornecem várias instruções sobre como criar e instalar as extensões, mas não as carregam automaticamente. As extensões podem ser carregadas adicionando uma diretiva extension ao arquivo php.ini ou através do uso da função dl().

Ao compilar módulos PHP, é importante ter as versões apropriadas das ferramentas necessárias (autoconf, automake, libtool, etc.). Consulte as » Instruções para Acesso Anônimo ao Git para obter detalhes sobre as ferramentas e versões necessárias.

## Baixando extensões PECL

> Nota: PHP Installer for Extensions (PIE) é uma nova ferramenta que tornará o PECL obsoleto. É recomendado usar o PIE para instalar extensões. Descubra mais em » https://github.com/php/pie

Existem várias opções para baixar extensões PECL, como:

- O comando pecl install extname baixa o código das extensões automaticamente, portanto, neste caso, não há necessidade de baixar separadamente.
- » https://pecl.php.net/ O site do PECL contém informações sobre as extensões que a equipe de desenvolvimento do PHP oferece. As informações disponíveis aqui incluem changelogs, notas de versão, requisitos e outros detalhes semelhantes.
- pecl download extname As extensões PECL que possuem versões listadas no site do PECL estão disponíveis para download e instalação usando o » comando pecl. Revisões específicas também podem ser especificadas.
- git Muitas extensões PECL podem ser encontradas no GitHub.
- SVN Algumas extensões PECL também podem ser encontradas no SVN. Uma visualização web pode ser encontrada em » https://svn.php.net/pecl/. Para baixar direto do SVN, os seguintes comandos podem ser usados:

      $ svn checkout https://svn.php.net/repository/pecl/extname/trunk extname

- Downloads do Windows O Projeto PHP compila e oferece DLLs do Windows para a maioria das extensões PECL na página do pacote.

## Instalando uma extensão PHP no Windows

Existem duas maneiras de carregar uma extensão PHP no Windows: compilando-a no PHP ou carregando a DLL. Carregar uma extensão pré-compilada é a maneira mais fácil e preferida.

Para carregar uma extensão, ela deve estar disponível como um arquivo .dll no sistema. Todas as extensões são compiladas automaticamente e periodicamente pelo PHP Group (veja a próxima seção para download).

Para compilar uma extensão no PHP, consulte a documentação sobre compilação do código-fonte.

Para compilar uma extensão independente (um arquivo DLL), consulte a documentação sobre compilação do código-fonte. Se a DLL não estiver disponível na distribuição do PHP nem no PECL, pode ser necessário compilá-la antes que a extensão possa ser usada.

### Onde encontrar uma extensão?

As extensões do PHP geralmente são chamadas de php_*.dll (onde o asterisco representa o nome da extensão) e estão localizadas no diretório PHP\ext.

O PHP vem com as extensões mais úteis para a maioria dos desenvolvedores. Elas são chamadas extensões nativas do PHP.

Entretanto, se as extensões nativas não fornecerem a funcionalidade necessária, uma extensão que ofereça essa funcionalidade ainda pode ser encontrada no » PECL. A biblioteca comunitária de extensões PHP (PECL) é um repositório de extensões PHP, que fornece um diretório de todas as extensões conhecidas e recursos de hospedagem para download e desenvolvimento de extensões PHP.

Se uma extensão foi desenvolvida para usos específicos, ela pode ser hospedada no PECL para que outras pessoas com as mesmas necessidades possam se beneficiar delas. Um bom efeito colateral é que é uma excelente chance de receber feedbacks, agradecimentos, relatórios de erros e até mesmo correções/patches. Antes de enviar uma extensão para hospedagem no PECL, consulte sobre » Submissão ao PECL.

### Qual extensão baixar?

Muitas vezes, haverá várias versões disponíveis de cada DLL:

- Números de versão diferentes (pelo menos os dois primeiros números devem corresponder)
- Versões de thread safety diferentes
- Arquitetura de processador diferente (x86, x64, ...)
- Configurações de depuração diferentes
- `etc.`

Lembre-se de que as configurações de extensão devem corresponder a todas as configurações do executável PHP que está sendo usado. O script a seguir informará tudo sobre as configurações do PHP:

Exemplo #1 A função phpinfo()

    <?php
    phpinfo();
    ?>

Ou na linha de comando, execute:

    drive:\caminho\para\o\executavel\php.exe -i

### Carregando uma extensão

A forma mais comum de carregar uma extensão PHP é incluí-la no arquivo de configuração php.ini. Observe que muitas extensões já estão presentes no php.ini e só é preciso remover o ponto e vírgula para ativá-las.

A partir do PHP 7.2.0, o nome da extensão pode ser usado ao invés do nome do arquivo da extensão. Como é independente do sistema operacional é mais fácil, especialmente para iniciantes, essa é a maneira recomendada de especificar as extensões a serem carregadas. Os nomes dos arquivos continuam suportados para compatibilidade com versões anteriores.

    ;extension=php_extname.dll

    extension=php_extname.dll

    ; A partir do PHP 7.2.0, prefira:
    extension=extname
    zend_extension=another_extension

No entanto, isso pode causar confusão em alguns servidores web porque eles não usam o arquivo php.ini localizado junto do executável PHP. Para descobrir onde o arquivo php.ini está, procure seu caminho na função phpinfo():

    Configuration File (php.ini) Path  C:\WINDOWS

    Loaded Configuration File   C:\Program Files\PHP\8.2\php.ini

Depois de ativar uma extensão, salve o arquivo php.ini, reinicie o servidor web e verifique a função phpinfo() novamente. A nova extensão agora deve ter sua própria seção.

### Resolvendo problemas

Se uma extensão não aparecer na função phpinfo(), os logs devem ser verificados para saber de onde vem o problema.

Se o PHP estiver sendo usado na linha de comando (CLI), os erros de carregamento da extensão podem ser lidos diretamente na tela.

Se o PHP estiver sendo usado com um servidor web, a localização e o formato dos logs irão variar dependendo do software usado. Consulte a documentação do servidor web para localizar os logs, pois isso não está relacionado com o PHP.

Problemas comuns são a localização da DLL e das DLLs das quais ela depende, o valor da diretiva "extension_dir" no arquivo php.ini e incompatibilidades de configuração em tempo de compilação.

Se o problema estiver em uma incompatibilidade de configuração em tempo de compilação, provavelmente a DLL errada foi baixada. Tente baixar novamente a extensão com as configurações corretas. Novamente, a função phpinfo() pode ser de grande ajuda.

## Compilando extensões PECL compartilhadas com o comando pecl

O PECL facilita a criação de extensões PHP compartilhadas. Usando o » comando pecl, faça o seguinte:

    $ pecl install extname

Isso fará o download do código-fonte de extname, compilará e instalará extname.so em extension_dir. extname.so pode então ser carregada usando o php.ini.

Por padrão, o comando pecl não instalará pacotes marcados com o estado `alpha` ou `beta`. Se nenhum pacote `stable` estiver disponível, um pacote `beta` pode ser instalado usando o seguinte comando:

    $ pecl install extname-beta

Uma versão específica também pode ser instalada usando esta forma:

    $ pecl install extname-0.1

> Nota:

> Depois de habilitar a extensão no php.ini, será necessário reiniciar o serviço web para que as alterações sejam detectadas.

## Compilando extensões PECL compartilhadas com phpize

Às vezes, usar o instalador pecl não é uma opção. Isso pode ocorrer porque há um firewall ou porque a extensão que está sendo instalada não está disponível como um pacote compatível com o PECL, como extensões não lançadas do git. Se tal extensão precisar ser compilada, as ferramentas de compilação de baixo nível podem ser usadas para realizar a compilação manualmente.

O comando phpize é usado para preparar o ambiente de compilação para uma extensão PHP. No exemplo a seguir, o código-fonte de uma extensão está em um diretório chamado extname:

    $ cd extname
    $ phpize
    $ ./configure
    $ make
    # make install

Uma instalação bem sucedida criará um arquivo extname.so e o colocará no diretório de extensões PHP extension_dir. O arquivo php.ini precisará ser ajustado, e uma linha `extension=extname.so` precisará ser adicionada antes que a extensão possa ser usada.

Se o sistema não tiver o comando phpize e pacotes pré-compilados (como os do RPM) forem usados, certifique-se também de instalar a versão de desenvolvimento apropriada dos pacotes PHP, pois ela geralmente inclui o comando phpize juntamente com os arquivos de cabeçalho apropriados para compilar o PHP e suas extensões.

Execute phpize --help para exibir informações de uso adicionais.

## php-config

php-config é um script shell para obter informações sobre a configuração do PHP instalado.

Quando as extensões estão sendo compiladas, se várias versões do PHP estiverem instaladas, a instalação para a qual compilar pode ser especificada usando a opção --with-php-config durante a configuração, definindo o caminho do respectivo script php-config.

A lista de opções de linha de comando fornecida pelo script php-config pode ser consultada a qualquer momento executando php-config com a opção -h:

    Usage: /usr/local/bin/php-config [OPTION]
    Options:
      --prefix            [...]
      --includes          [...]
      --ldflags           [...]
      --libs              [...]
      --extension-dir     [...]
      --include-dir       [...]
      --php-binary        [...]
      --php-sapis         [...]
      --configure-options [...]
      --version           [...]
      --vernum            [...]

Opções de linha de comando
Opção | Descrição
--- | ---
--prefix | Prefixo do diretório onde o PHP está instalado, por exemplo /usr/local
--includes | Lista de opções `-I` com todos os arquivos de inclusão.
--ldflags | Flags `LD` com as quais o PHP foi compilado.
--libs | Bibliotecas extras com as quais o PHP foi compilado.
--extension-dir | Diretório onde as extensões são pesquisadas por padrão.
--include-dir | Prefixo do diretório onde os arquivos de cabeçalho são instalados por padrão.
--php-binary | Caminho completo para o binário php CLI ou CGI.
--php-sapis | Exibe todos os módulos SAPI disponíveis.
--configure-options | Opções de configuração para recriar a configuração da instalação atual do PHP.
--version | Versão do PHP.
--vernum | Versão do PHP como inteiro.

## Compilando extensões PECL estaticamente no PHP

Às vezes, pode ser necessário criar uma extensão PECL estaticamente no binário do PHP. Para isso, o código-fonte da extensão precisará ser colocado no diretório /caminho/para/o/diretorio/php/src/ext/, e será necessário que o sistema de compilação do PHP gere o script de configuração novamente.

    $ cd /caminho/para/o/diretorio/php/src/ext
    $ pecl download extname
    $ gzip -d < extname.tgz | tar -xvf -
    $ mv extname-x.x.x extname

Isso resultará no seguinte diretório:

    /caminho/para/o/diretorio/php/src/ext/extname

Depois disso, o PHP precisa ser forçado a reconstruir o script de configuração e, em seguida, pode ser compilado normalmente:

    $ cd /caminho/para/o/diretorio/php/src
    $ rm configure
    $ ./buildconf --force
    $ ./configure --help
    $ ./configure --with-extname --enable-someotherext --with-foobar
    $ make
    $ make install

> Nota: Para executar o script buildconf, o autoconf `2.68` e o automake `1.4+` serão necessários. As versões mais recentes do autoconf podem funcionar, mas não são suportadas.

O uso de --enable-extname ou --with-extname depende da extensão. Normalmente, uma extensão que não requer bibliotecas externas usa --enable. Para ter certeza, execute o seguinte após buildconf:

    $ ./configure --help | grep extname

# Instalação do Composer e pacotes de terceiros

## Introdução ao Composer

» Composer é um gerenciador de dependências para o PHP que torna possível definir pacotes de códigos de terceiros usados por um projeto que pode então ser facilmente instalado e atualizado. Ele aproveita os recursos de carregamento automático de classe do PHP, repositórios de pacotes PHP como » Packagist e convenções comuns de layout e codificação de projetos.

Por exemplo, se uma aplicação ou página em PHP precisa trabalhar com valores UUID, » o pacote `ramsey/uuid` de Ben Ramsey, que implementa os tipos de UUID amplamente conhecidos que são definidos pela » RFC 4122, poderia ser usado.

Resumidamente, isto é feito criando um arquivo `composer.json` no projeto, usando o Composer para instalar a última versão do pacote, e incluindo o script de autocarregamento do Composer para torná-lo disponível ao código. A » documentação de "Uso Básico" do Composer entra em mais detalhes sobre isso.

Exemplo #1 `composer.json` que requer um único pacote

    {
        "require": {
            "ramsey/uuid": "^4.7"
        }
    }

# Instalação do PIE e extensões de terceiros

## Introdução ao PIE

» PIE é um instalador para PHP que torna possível instalar extensões PHP de terceiros que podem ser facilmente aplicadas e atualizadas. Ele utiliza o repositório de extensões PHP do » Packagist para encontrar o código-fonte para construir a extensão, ou um binário do Windows para baixar, se existir. Se ele baixar o código-fonte, também saberá como compilá-lo e instalá-lo.

Após » instalar os requisitos e o próprio PIE, pode-se instalar a extensão MongoDB executando o seguinte na linha de comando.

Exemplo #1 Instalando a extensão MongoDB com PIE

    pie install mongodb/mongodb-extension

A » documentação "PIE Usage" aborda isso com mais detalhes.

# Configuração em tempo de execução

## Índice

- O arquivo de configuração
- Arquivos .user.ini
- Onde uma configuração deve ser definida
- Como mudar as configurações

## O arquivo de configuração

O arquivo de configuração (php.ini) é lido quando o PHP inicia. Para as versões de módulo de servidor, isso acontece apenas quando o servidor web for iniciado. Para as versões CGI e CLI, isso acontece a cada invocação.

php.ini é procurado nesses lugares (na ordem):

- Local específico do módulo SAPI (diretiva `PHPIniDir` no Apache 2, opção de linha de comando `-c` no CGI e CLI)
- A variável de ambiente PHPRC.
- A localização do arquivo `php.ini` pode ser definida para versões diferentes do PHP. A raiz do registro depende da compilação em 32 ou 64 bits do sistema operacional (SO) e do PHP. Para um PHP 32 bits em um SO de 32 bits ou um PHP de 64 bits em um SO de 64 bits use `[(HKEY_LOCAL_MACHINE\SOFTWARE\PHP]`, Para um PHP 32 bits em um SO de 64 bits use `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]`]. Para sistema onde a compilação em bits coincida, as seguintes chaves são examinadas, nessa ordem: `[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y.z]`, `[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y]` e `[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x]`, onde x, y e z significam os valores de versão PHP major, minor e release. Para PHP versão 32 bits em um SO de 64 bits, as seguintes chaves são examinadas em ordem: `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y.z]`, `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y]` e `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x]`, onde x, y e z significam os valores de versão PHP major, minor e release. Se houver um valor para `IniFilePath` nestas chaves, então o primeiro encontrado será utilizado para a localização do `php.ini` (apenas Windows).
- `[HKEY_LOCAL_MACHINE\SOFTWARE\PHP]` ou `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]`, valor de `IniFilePath` (Somente Windows).
- Diretório de trabalho atual (exceto CLI).
- O diretório do servidor web (para módulo SAPI), ou diretório do PHP (caso contrário, no Windows).
- Diretório do Windows (C:\windows ou C:\winnt) (para Windows), ou a opção de tempo de compilação `--with-config-file-path` .

Se php-SAPI.ini existe (onde SAPI é o SAPI usado, então o nome de arquivo é, por exemplo, php-cli.ini ou php-apache.ini), é usado ao invés do arquivo php.ini. O nome SAPI pode ser determinado pela função php_sapi_name().

> Nota:

> O servidor web Apache muda o diretório para raiz durante a inicialização, causando com que o PHP tente ler o arquivo php.ini da raiz do arquivo de sistema, se ele existir.

Variáveis de ambiente podem ser referenciadas dentro de valores de configuração no php.ini como mostrado abaixo. A partir do PHP 8.3.0, um valor padrão pode ser especificado e será usado quando a variável referenciada não estiver definida.

Exemplo #1 Variáveis de ambiente no php.ini

    ; PHP_MEMORY_LIMIT é lida das variáveis de ambiente
    memory_limit = ${PHP_MEMORY_LIMIT}
    ; Se PHP_MAX_EXECUTION_TIME não esitver definida, será usado o padrão de 30
    max_execution_time = ${PHP_MAX_EXECUTION_TIME:-30}

As diretivas do arquivo php.ini tratadas por extensões são documentadas nas respectivas páginas das próprias extensões. A lista de diretivas principais está disponível no apêndice. Nem todas as diretivas do PHP estão documentadas no manual. Para uma lista completa das diretivas disponíveis na sua versão do PHP, por favor leia seu arquivo php.ini. Alternativamente, você pode encontrar » a última versão do php.ini no Git, que também pode ser útil.

Exemplo #2 Exemplo de arquivo php.ini

    ; qualquer texto após um ponto e vírgula nú (;) é ignorado
    [php] ; marcadores de sessão (textos dentro de colchetes) também são ignorados
    ; Valores booleanos podem ser:
    ;    true, on, yes
    ; ou false, off, no, none
    register_globals = off
    track_errors = yes

    ; vocẽ pode organizar strings dentro de aspas
    include_path = ".:/usr/local/lib/php"

    ; contrabarra é tratado como um caractere normal
    include_path = ".;c:\php\lib"

É possível acessar as variáveis .ini dentro dos arquivos .ini. Exemplo: `open_basedir = ${open_basedir} ":/new/dir"`.

### Configuração em diretório

É possível configurar o PHP para procurar por arquivos .ini em um diretório após a leitura do php.ini. Isto é possível na compilação pela configuração da opção --with-config-file-scan-dir. No O diretório de configuração pode ser sobrescrito em tempo de execução através da configuração da variável de ambiente PHP_INI_SCAN_DIR.

É possível procurar em vários diretórios os separando com o delimitador específico da plataforma (`;` no Windows, NetWare e RISC OS; `:` em todas as outras plataformas; o PHP utilizará a constante `PATH_SEPARATOR`). Se um diretório em branco estiver informado em PHP_INI_SCAN_DIR, o PHP também procurará pelo diretório informado na diretiva de compilação --with-config-file-scan-dir.

Dentro de cada diretório o PHP irá pesquisar todos os arquivos terminados em `.ini` em ordem alfabética. A lista de arquivos é carregada, e nessa ordem são interpretados com uma chamada a php_ini_scanned_files(), o por rodar o PHP com a opção --ini.

    Assumindo que o PHP foi configurado com --with-config-file-scan-dir=/etc/php.d,
    e o separador de caminho é :...

    $ php
      PHP irá carregar todos os arquivos de configuração em in /etc/php.d/*.ini.

    $ PHP_INI_SCAN_DIR=/usr/local/etc/php.d php
      PHP irá carregar todos os arquivos de configuração em /usr/local/etc/php.d/*.ini.

    $ PHP_INI_SCAN_DIR=:/usr/local/etc/php.d php
      PHP irá carregar todos os arquivos de configuração em /etc/php.d/*.ini, e então em
      /usr/local/etc/php.d/*.ini.

    $ PHP_INI_SCAN_DIR=/usr/local/etc/php.d: php
      PHP irá carregar todos os arquivos de configuração em /usr/local/etc/php.d/*.ini, e então em
      /etc/php.d/*.ini.

## Arquivos .user.ini

O PHP tem suporte para arquivos de configuração INI por cada diretório. Esses arquivos são processados apenas pelo CGI/FastCGI SAPI. Essa funcionalidade torna obsoleta a extensão PECL htscanner. Se você estiver rodando o PHP como um módulo do Apache, use arquivos .htaccess para obter o mesmo efeito.

Além do arquivo php.ini principal, o PHP procura por arquivos INI em cada diretório, iniciando no diretório do arquivo PHP requisitado e continua o caminho até a raiz do documento atual (conforme definido na variável $_SERVER['DOCUMENT_ROOT']). Caso o arquivo PHP esteja fora da raiz do documento, apenas o seu diretório é procurado.

Somente configurações INI com os modos `INI_PERDIR` e `INI_USER` serão reconhecidos nos arquivos INI estilo .user.ini.

Duas novas diretivas INI, user_ini.filename e user_ini.cache_ttl controlam o uso de arquivos INI de usuário.

A diretiva user_ini.filename define o nome do arquivo que o PHP procura em cada diretório; se for definido como uma string vazia, o PHP não fará a varredura em tudo. O padrão é `.user.ini`.

A diretiva user_ini.cache_ttl controla a frequência de como os arquivos INI de usuário são relidos. O padrão é de 300 segundos (5 minutos).

## Onde uma configuração deve ser definida

Estes modos determinam quando e onde uma diretiva do PHP pode ou não pode ser definida, e cada diretiva no manual faz referência a um destes modos. Por exemplo, algumas definições podem ser feitas em um script PHP usando ini_set(), enquanto outras só podem ser feitas no php.ini ou httpd.conf.

Por exemplo, a configuração output_buffering é `INI_PERDIR` portanto não pode ser definida usando ini_set(). Entretanto a diretiva display_errors é `INI_ALL` portanto pode ser definida em qualquer lugar com ini_set().

Constantes de modo INI
`INI_USER` (int)
  A entrada pode ser definida em scripts do usuário (como com ini_set()) ou no registro do Windows. A entrada pode ser definida no .user.ini
`INI_PERDIR` (int)
  A entrada pode ser definida no php.ini, .htaccess, httpd.conf ou .user.ini
`INI_SYSTEM` (int)
  A entrada pode ser definida no php.ini ou httpd.conf
`INI_ALL` (int)
  A entrada pode ser definida em qualquer lugar

## Como mudar as configurações

### Executando PHP como módulo do Apache

Quando usar o PHP como módulo do Apache, você pode mudar as configurações usando diretivas nos arquivos de configuração do Apache (ex.: httpd.conf e .htaccess). Você precisará dos privilégios "AllowOverride Options" ou "AllowOverride All" para fazer isso.

Há várias diretivas do Apache que permitem que você mude a configuração do PHP de dentro dos arquivos de configuração do Apache. Para uma lista de quais diretivas são `INI_ALL`, `INI_PERDIR`, ou `INI_SYSTEM`, olhe no apêndice Lista de diretivas do arquivo php.ini.

`php_value` `name` `value`

  Define o valor da diretiva especificada. Pode ser usado apenas com diretivas do tipo `INI_ALL` e `INI_PERDIR`. Para limpar um valor definido anteriormente, use o valor `none`.

  > Nota: Não use `php_value` para definir valores booleanos. A diretiva `php_flag` deve ser usada (veja abaixo).

`php_flag` `name` `on|off`

  Usado para definir uma diretiva de configuração booleana. Pode ser usada apenas com diretivas dos tipos `INI_ALL` e `INI_PERDIR`.

`php_admin_value` `name` `value`

  Define o valor da diretiva especificada. Essa diretiva não pode ser usada em arquivos .htaccess. Qualquer tipo de diretiva definido com `php_admin_value` não pode ser sobrescrito pelo .htaccess ou pela função ini_set(). Para limpar um valor definido anteriormente, use o valor `none`.

`php_admin_flag` `name` `on|off`

  Usado para definir uma diretiva de configuração booleana. Essa diretiva não pode ser usada em arquivos .htaccess. Qualquer tipo de diretiva definido com `php_admin_flag` não pode ser sobrescrito pelo .htaccess ou pela função ini_set().

Exemplo #1 Exemplo de configuração do Apache

    <IfModule mod_php5.c>
      php_value include_path ".:/usr/local/lib/php"
      php_admin_flag engine on
    </IfModule>
    <IfModule mod_php4.c>
      php_value include_path ".:/usr/local/lib/php"
      php_admin_flag engine on
    </IfModule>

Cuidado

Constantes PHP não existem fora do PHP. Por exemplo, no arquivo httpd.conf você não pode usar constantes do PHP como `E_ALL` ou `E_NOTICE` para definir a diretiva error_reporting, já que elas não terão significado algum e serão avaliadas como 0. Ao invés disso, use os valores de máscara de bits associados. Essas constantes podem ser usados no php.ini

### Mudando configuração do PHP através do registro do Windows

Quando executar o PHP no Windows, os valores de configuração podem ser modificados para cada diretório, usando o registro do Windows. Os valores de configuração são armazenados na chave de registro `HKLM\SOFTWARE\PHP\Per Directory Values`, nas sub-chaves correspondentes aos caminhos dos diretórios. Por exemplo, valores para o diretório `c:\inetpub\wwwroot` estariam armazenados na chave `HKLM\SOFTWARE\PHP\Per Directory Values\c\inetpub\wwwroot`. As configurações para o diretório estarão ativas para qualquer script rodando neste diretório ou qualquer subdiretório dele. Os valores na chave devem ter o nome da diretiva de configuração do PHP e um valor string. Constantes PHP nos valores não são interpretados. Apenas valores de configuração modificáveis no `INI_USER` podem ser definidos desta forma, e valores do `INI_PERDIR` não podem, pois esses valores são recarregados em cada request.

### Outras interfaces para PHP

Independente de como você execute PHP, você pode mudar certos valores durante a execução de seus scripts através da função ini_set(). Veja a documentação na página ini_set() para mais informações.

Se você estiver interessado na lista completa das configurações definidas no seu sistema com os valores atuais, você pode executar a função phpinfo(), e revisar a página resultante. Você pode também acessar os valores de configurações de diretivas individuais em tempo de execução usando as funções ini_get() ou get_cfg_var().

- Considerações Gerais sobre Instalação
- Instalação em sistemas Unix
  - Instalando a partir de pacotes no Debian GNU/Linux e distribuições relacionadas
  - Instalando a partir de pacotes em distribuições GNU/Linux que usam DNF
  - Instalando a partir de pacotes ou portas no OpenBSD
  - Instalando a partir do código-fonte em sistemas Unix e macOS
  - CGI e instalações de linha de comando
  - Apache 2.0 em sistemas Unix
  - Nginx 1.4.x em sistemas Unix
  - Lighttpd 1.4 em sistemas Unix
  - Servidores Web LiteSpeed/OpenLiteSpeed em sistemas Unix
  - Dicas de instalação específicas para o Solaris
- Instalação no macOS
  - Instalação no macOS usando pacotes de terceiros
  - Usando o pacote do PHP no macOS para versões anteriores ao macOS Monterey
  - Compilando o PHP no MacOS
- Instalação em sistemas Windows
  - Configuração recomendada em sistemas Windows
  - Instalação Manual de binários pré-compilados
  - Instalação para Apache 2.x em sistemas Windows
  - Instalação com IIS no Windows
  - Ferramentas de terceiros para instalar o PHP
  - Compilando a partir dos fontes
  - Executando o PHP em linha de comando em sistemas Windows
- Instalação em Plataformas de Computação em Nuvem
  - Azure App Services
  - Amazon EC2
  - DigitalOcean
- FastCGI Process Manager (FPM)
  - Instalação
  - Configuração
- Instalação das extensões PECL
  - Introdução às Instalações PECL
  - Baixando extensões PECL
  - Instalando uma extensão PHP no Windows
  - Compilando extensões PECL compartilhadas com o comando pecl
  - Compilando extensões PECL compartilhadas com phpize
  - php-config
  - Compilando extensões PECL estaticamente no PHP
- Introdução ao Composer
- Introdução ao PIE
- Configuração em tempo de execução
  - O arquivo de configuração
  - Arquivos .user.ini
  - Onde uma configuração deve ser definida
  - Como mudar as configurações

# Referência da Linguagem

# Sintaxe Básica

## Índice

- Tags PHP
- Escapando o HTML
- Separação de instruções
- Comentários

## Tags PHP

Quando o PHP processa um arquivo, ele reconhece as etiquetas de abertura e fechamento, `<?php` e `?>`, para definir os limites da execução de código PHP. O conteúdo fora destas etiquetas é ignorado pelo interpretador PHP, permitindo que o PHP seja incluído em vários tipos de documentos.

Um caractere de espaço em branco (espaço, tabulação ou nova linha) precisa estar presente logo após `<?php` para assegurar uma separação correta de tokens. Omitir este espaço resultará em erro de sintaxe.

O PHP também inclui a etiqueta `<?=` que é um encurtamento para `<?php echo`.

Exemplo #1 Tags de Abertura e Fechamento do PHP

    1.  <?php echo 'Se quiser servir código PHP em documentos XHTML ou XML,
                    use essas tags'; ?>

    2.  A tag echo curta <?= 'imprima essa string' ?> também pode ser usada.
        Ela é equivalente a <?php echo 'imprima essa string' ?>.

    3.  <? echo 'Este código está entre tags curtas, mas só funcionará '.
                'se a diretiva short_open_tag estiver habilitada'; ?>

As tags curtas (exemplo 3) estão disponíveis por padrão, mas podem ser desabilitadas através da diretiva short_open_tag no arquivo de configuração php.ini, ou estarão desabilitadas por padrão se o PHP for compilado com a configuração --disable-short-tags.

> Nota:

> Como as tags curtas podem ser desabilitadas, é recomendado usar apenas as tags normais (`<?php ?>` e `<?= ?>`) para maximizar a compatibilidade.

Se um arquivo terminar com código PHP, é preferível omitir a tag de fechamento do PHP no final do arquivo. Isso evita que espaços em branco ou novas linhas sejam adicionados acidentalmente após a tag de fechamento do PHP, o que pode causar efeitos indesejados, porque o PHP iniciará o buffer de saída quando não houver intenção de enviar qualquer saída naquele ponto do script.

Exemplo #2 Arquivo apenas com código PHP

    <?php
    echo "Olá Mundo\n";

    // ... mais código

    echo "Última instrução\n";

    // o script termina aqui sem a tag de fechamento do PHP

## Escapando o HTML

Tudo fora de um par de tags de abertura e fechamento é ignorado pelo interpretador PHP, o que permite que arquivos PHP tenham conteúdo misto. Isso permite que o PHP seja incluído em documentos HTML, por exemplo, para criar templates.

Exemplo #1 Incorporando o PHP no HTML

    <p>Isso será ignorado pelo PHP e exibido pelo navegador.</p>
    <?php echo 'Enquanto isto vai ser interpretado.'; ?>
    <p>Isso também será ignorado pelo PHP e exibido no navegador.</p>

Isso funcionará como esperado, porque quando o interpretador PHP encontra a tag de fechamento ?>, ele simplesmente começa a repassar o que quer que encontre (exceto a nova linha imediata, veja a seção sobre separação de instruções), até encontrar outra tag de abertura, a menos que esteja no meio de uma declaração condicional, caso em que o interpretador determinará o resultado da condicional antes de decidir qual caminho tomar. Veja o próximo exemplo.

Usando estruturas com condições

Exemplo #2 Escape avançado usando condições

    <?php if ($expression == true): ?>
      Isso irá aparecer se a expressão for verdadeira.
    <?php else: ?>
      Senão isso irá aparecer.
    <?php endif; ?>

Neste exemplo, o PHP pulará os blocos onde a condição não for satisfeita, mesmo que os trechos de código estejam fora das tags de abertura e fechamento do PHP, pois o interpretador PHP pulará os blocos contidos em uma condição que não foi satisfeita.

Para imprimir grandes blocos de texto, sair do modo de interpretação do PHP é geralmente mais eficiente do que enviar todo o texto usando echo ou print.

> Nota:

> Se o PHP for incluído no XML ou XHTML, as tags normais `<?php ?>` devem ser usadas para manter a conformidade com os padrões.

## Separação de instruções

Como em C ou Perl, o PHP requer que as instruções sejam terminadas com um ponto e vírgula no final de cada declaração. A tag de fechamento de um bloco de código PHP implica automaticamente em um ponto e vírgula; a última linha de um bloco PHP não precisa ser terminada com um ponto e vírgula. A tag de fechamento do bloco incluirá uma nova linha em seguida, se estiver presente.

Exemplo #1 Exemplo mostrando a tag de fechamento incluindo uma nova linha final

    <?php echo "Algum texto"; ?>
    Sem nova linha
    <?= "Mas agora há uma nova linha" ?>

O exemplo acima produzirá:

    Algum textoSem nova linha
    Mas agora há uma nova linha

Exemplo #2 Exemplos de entrada e saída do interpretador PHP

    <?php
        echo "Isto é um teste\n";
    ?>

    <?php echo "Isto é um teste\n" ?>

    <?php echo "A última tag de fechamento foi omitida\n";

> Nota:

> A tag de fechamento de um bloco PHP no final de um arquivo é opcional e, em alguns casos, omiti-la é útil ao usar include ou require, assim espaços em branco indesejados não ocorrerão no final dos arquivos, e ainda será possível adicionar cabeçalhos à resposta posteriormente. Isso também é útil ao usar o buffer de saída, para evitar a inclusão de espaços em branco indesejados no final das partes geradas pelos arquivos incluídos.

## Comentários

O PHP suporta comentários no estilo C, C++ e Unix shell (estilo Perl). Por exemplo:

Exemplo #1 Comentários

    <?php
        echo "Isto é um teste\n"; // Este é um comentário de uma linha no estilo C++
        /* Este é um comentário de várias linhas
           mais uma linha de comentário */
        echo "Este é mais um teste\n";
        echo "Um teste final\n"; # Este é um comentário de uma linha no estilo shell
    ?>

Os estilos de comentário de uma linha comentam apenas até o final da linha ou do bloco atual de código PHP, o que ocorrer primeiro. Isso significa que o código HTML após `// ... ?>` ou `# ... ?>` SERÁ impresso: ?> sai do modo PHP e retorna ao modo HTML, e `//` ou `#` não podem influenciar isso.

Exemplo #2 Comentários de uma linha

    <h1>Este é um <?php # echo 'simples';?> exemplo</h1>
    <p>O cabeçalho acima dirá 'Este é um exemplo'.</p>

Os comentários no estilo C terminam no primeiro `*/` encontrado. Certifique-se de não aninhar comentários no estilo C. É fácil cometer esse erro ao tentar comentar um grande bloco de código.

    <?php
     /*
        echo 'Isto é um teste'; /* Este comentário causará um problema */
     */
    ?>

# Tipos

## Índice

- Introdução
- Sistema de tipagem
- NULL
- Booleanos
- Inteiros
- Números de ponto flutuante
- Strings
- Strings numéricas
- Arrays
- Objetos
- Enumerações
- Recursos
- Chamáveis
- Misto
- Void
- Never
- Tipos de classes relativas
- Tipos únicos
- Iterável
- Declarações de tipo
- Conversão automática de tipos

## Introdução

Cada expressão no PHP tem um dos seguintes tipos ou valores internos:

- null
- bool
- int
- float (número de ponto flutuante)
- string
- array
- object
- callable
- resource

O PHP é uma linguagem com tipagem dinâmica, o que significa que por padrão não existe a necessidade de especificar o tipo de uma variável, já que isso será determinado em tempo de execução. Entretanto, é possível restringir estaticamente os tipos através do uso de declarações de tipo. Os diferentes tipos suportados pelo PHP podem ser encontrados na página de sistema de tipos.

Os tipos restringem quais operações podem ser realizadas nos valores. Entretanto, se uma expressão ou variável for utilizada numa operação que o tipo não suporte, o PHP tentará transformar o valor em um tipo que suporte a operação. Esse processo depende do contexto de onde o valor é utilizado. Para mais informações, veja a seção sobre Transformações de tipos.

Dica

A tabela de comparação de tipos também pode ser útil, pelos vários exemplos de comparação de valores demonstrados.

> Nota: É possível forçar a reavaliação de uma expressão para um tipo específico através do uso de cast. Uma variável pode ser modificada para um tipo através da função settype().

Para verificar o valor e tipo de uma expressão, utilize a funçãovar_dump(). Para extrair o tipo de uma expressão, utilize a função get_debug_type(). Para apenas validar se uma expressão é de um certo tipo, utilize as funções `is_type`.

Exemplo #1 Tipos diferentes

    <?php
    $a_bool = true;   // um valor booleano
    $a_str  = "foo";  // um texto
    $a_str2 = 'foo';  // um texto
    $an_int = 12;     // um inteiro

    echo get_debug_type($a_bool), "\n";
    echo get_debug_type($a_str), "\n";

    // Se essa variável contiver um inteiro, aumenta o número em quatro
    if (is_int($an_int)) {
        $an_int += 4;
    }
    var_dump($an_int);

    // Se $a_bool for um texto, exibe
    if (is_string($a_bool)) {
        echo "String: $a_bool";
    }
    ?>

Saída do exemplo acima no PHP 8:

    bool
    string
    int(16)

> Nota: get_debug_type() tornou-se disponível no PHP 8.0.0. Antes dessa versão, a função gettype() podia ser utilizada. Entretanto, a função antiga não retorna nomes bem definidos.

## Sistema de tipagem

O PHP usa um sistema de tipagem nominal com uma forte relação de subtipagem comportamental. A relação de subtipagem é verificada em tempo de compilação, enquanto a verificação de tipos é verificada dinamicamente em tempo de execução.

O sistema de tipos do PHP suporta vários tipos atômicos que podem ser compostos juntos para criar tipos mais complexos. Alguns desses tipos podem ser escritos como declarações de tipo

### Tipos atômicos

Tipos atômicos são tipos internos que são fortemente integrados com a linguagem e não podem ser reproduzidos com tipos definidos pelo usuário.

A lista de tipos básicos é:

- Tipos integrados
  - Tipos escalares:
    - tipo bool
    - tipo int
    - tipo float
    - tipo string
  - tipo array
  - tipo object
  - tipo resource
  - tipo never
  - tipo void
  - Tipos de classes relativas: self, parent, e static
  - Tipos únicos
    - false
    - true
  - Tipos de unidade:
    - null
- Tipos definidos pelo usuário (geralmente chamados de tipos de classe)
  - Interfaces
  - Classes
  - Enumerações
- tipo callable

#### Tipos escalares

Um valor é considerado escalar se for do tipo int, float, string ou bool.

#### Tipos definidos pelo usuário

É possível definir tipos personalizados com interfaces, classes e enumerações. Essas são consideradas tipos definidos pelo usuário, ou tipos-classe. Por exemplo, uma classe chamada `Elephant` pode ser definida, em seguida objetos do tipo `Elephant` podem ser instanciados, e uma função pode requerer um parâmetro do tipo `Elephant`.

### Tipos compostos

É possível combinar vários tipos atômicos em tipos compostos. O PHP permite que os tipos sejam combinados das seguintes maneiras:

- Interseção de tipos de classes (interfaces e nomes de classes).
- União de tipos.

#### Tipos de interseção

Um tipo de interseção aceita valores que satisfazem várias declarações de tipo de classe, em vez de uma única. Os tipos individuais que formam o tipo de interseção são unidos pelo símbolo `&`. Portanto, um tipo de interseção composto pelos tipos `T`, `U`, e `V` será escrito como `T&U&V`.

#### Tipos de união

Um tipo de união aceita valores de vários tipos diferentes, em vez de um único. Tipos individuais que formam o tipo de união são unidos pelo `|` símbolo. Portanto, um tipo de união composto pelos tipos `T`, `U`, e `V` será escrito como `T|U|V`. Se um dos tipos for um tipo de interseção, ele precisa ser colocado entre parênteses para que seja escrito em DNF: `T|(X&Y)`.

### Alias de tipo

O PHP suporta dois aliases de tipo: mixed e iterable que corresponde ao tipo de união de `object|resource|array|string|float|int|bool|null` e `Traversable|array`, respectivamente.

> Nota: O PHP não suporta aliases de tipo definidos pelo usuário.

## NULL

O tipo null é um tipo unitário do PHP, ou seja, possui apenas um valor: `null`.

Variáveis indefinidas e com desfinição removida por unset() serão interpretadas como `null`.

### Sintaxe

Há apenas um valor do tipo null, que é a a constante `null`, insensível a maiúsculas/minúsculas.

    <?php
    $var = NULL;
    ?>

### Convertendo para `null`

Aviso

Este recurso foi DESCONTINUADO a partir do PHP 7.2.0 e foi REMOVIDO a partir do PHP 8.0.0. O uso deste recurso é fortemente desencorajado.

Converter uma variável para null utilizando `(unset) $var` não removerá nem a variável nem o seu valor. Apenas retornará um valor `null`.

### Veja Também

- is_null()
- unset()

## Booleanos

O tipo bool tem apenas dois valores e é usado para expressar um valor de verdade. Pode ser `true` ou `false`.

### Sintaxe

Para especificar um bool literal, use as palavras-chave `true` ou `false`. Ambas são case-insensitive.

    <?php

    $foo = True; // atribui o valor True para $foo

    var_dump($foo); // bool(true)
    ?>

Tipicamente, o resultado de um operador que retorne um valor bool, é passado para uma estrutura de controle.

    <?php

    $acao = "mostrar_versao";
    $exibir_separadores = true;

    // == É um operador que testa
    // igualdade e retorna um booleano.
    if ($acao == "mostrar_versao") {
        echo "A versão é 1.23";
    }

    // isto não é necessário ...
    if ($exibir_separadores == TRUE) {
        echo "<hr>\n";
    }

    // ... porque pode simplesmente ser escrito assim:
    if ($exibir_separadores) {
        echo "<hr>\n";
    }
    ?>

### Convertendo para booleano

Para converter explicitamente um valor em bool, use a conversão `(bool)`. Geralmente isso não é necessário porque quando um valor é usado em um contexto lógico ele será automaticamente interpretado como um valor do tipo bool. Para obter mais informações, consulte a página Manipulação de tipos.

Ao converter para bool, os seguintes valores são considerados `false`:

- o próprio booleano `false`
- o inteiro `0` (zero)
- os pontos flutuantes `0.0` e `-0.0` (zero)
- uma string vazia `""`, e a string `"0"`
- um array sem elementos
- o tipo especial NULL (incluindo variáveis não definidas)
- Objetos internos que sobrecarregam seu comportamento de conversão para booleano. Por exemplo, objetos GMP que representam o valor `0`.

Todos os outros valores são considerados `true` (incluindo resource e `NAN`).

Aviso

`-1` é considerado `true`, como qualquer número que não seja zero (negativos ou positivos)!

Exemplo #1 Convertendo para booleano

    <?php
    var_dump((bool) "");        // bool(false)
    var_dump((bool) "0");       // bool(false)
    var_dump((bool) 1);         // bool(true)
    var_dump((bool) -2);        // bool(true)
    var_dump((bool) "foo");     // bool(true)
    var_dump((bool) 2.3e5);     // bool(true)
    var_dump((bool) array(12)); // bool(true)
    var_dump((bool) array());   // bool(false)
    var_dump((bool) "false");   // bool(true)
    ?>

## Inteiros

Um int é um número do conjunto ℤ = {..., -2, -1, 0, 1, 2, ...}.

### Veja Também

- Números de ponto flutuante
- Precisão arbitrária / BCMath
- Número inteiro de comprimento arbitrário / GMP

### Sintaxe

Int pode ser especificado em notação decimal (base 10), hexadecimal (base 16), octal (base 8) ou binária (base 2). O sinal de menos pode ser usado para indicar um int negativo.

Para usar a notação octal, preceda o número com um `0` (zero). A partir do PHP 8.1.0, a notação octal também pode ser precedida por `0o` ou `0O`. Para utilizar a notação hexadecimal, preceda o número com `0x`. Para utilizar a notação binária, preceda o número com `0b`.

A partir do PHP 7.4.0, inteiros literais podem conter sublinhados (`_`) entre os dígitos, para melhorar a sua leitura. Estes sublinhados serão removidos pelo analisador do PHP.

Exemplo #1 Inteiros literais

    <?php
    $a = 1234; // número decimal
    $a = 0123; // número octal (equivalente a 83 em decimal)
    $a = 0o123; // número octal (a partir do PHP 8.1.0)
    $a = 0x1A; // número hexadecimal (equivalente a 26 em decimal)
    $a = 0b11111111; // número binário (equivalente a 255 em decimal)
    $a = 1_234_567; // número decimal (a partir do PHP 7.4.0)
    ?>

Formalmente, a estrutura para int literais é esta a partir do PHP 8.1.0 (anteriormente, os prefixos octal `0o` ou `0O` não eram permitidos, e antes do PHP 7.4.0 os sublinhados não eram permitidos):

    decimal     : [1-9][0-9]*(_[0-9]+)*
                | 0

    hexadecimal : 0[xX][0-9a-fA-F]+(_[0-9a-fA-F]+)*

    octal       : 0[oO]?[0-7]+(_[0-7]+)*

    binário     : 0[bB][01]+(_[01]+)*

    inteiro     : decimal
                | hexadecimal
                | octal
                | binário

O tamanho de um int depende da plataforma, embora um valor máximo de cerca de dois bilhões seja o valor usual (são 32 bits com sinal). As plataformas de 64 bits geralmente têm um valor máximo de cerca de 9E18. O PHP não suporta int sem sinal. O tamanho int pode ser determinado usando a constante `PHP_INT_SIZE`, o valor máximo usando a constante `PHP_INT_MAX` e o valor mínimo usando a constante `PHP_INT_MIN`.

### Overflow de inteiros

Se o PHP encontrar um número além dos limites do tipo int, ele será interpretado como um float. Assim, uma operação que resulte em um número além dos limites do tipo int, retornará um float.

Exemplo #2 Estouro de inteiros

    <?php
    $large_number = 50000000000000000000;
    var_dump($large_number);         // float(5.0E+19)

    var_dump(PHP_INT_MAX + 1);       // sistemas 32 bits: float(2147483648)
                                     // sistemas 64 bits: float(9.2233720368548E+18)
    ?>

### Divisão de inteiros

Não existe operador de divisão int no PHP, para isso deve ser usada a função intdiv(). `1/2` produz o float `0.5`. O valor pode ser convertido em um int para arredondar para zero ou pode ser usada a função round() para um controle mais preciso sobre o arredondamento.

Exemplo #3 Divisões

    <?php
    var_dump(25/7);         // float(3.5714285714286)
    var_dump((int) (25/7)); // int(3)
    var_dump(round(25/7));  // float(4)
    ?>

### Convertendo para inteiro

Para converter explicitamente um valor para int, use a conversão `(int)`. Entretanto, na maioria dos casos, o modificador não é necessário, já que o valor será automaticamente convertido se um operador, função ou estrutura de controle requerer um int como argumento. Um valor também pode ser convertido para int utilizando a função intval().

Se um resource for convertido para um int, resultará no número único do recurso, atribuído ao resource pelo PHP em tempo de execução.

Veja também Manipulação de Tipos.

#### Convertendo a partir de booleanos

`false` será retornado como `0` (zero), e `true` retornará `1` (um).

#### Convertendo a partir de números de ponto flutuante

Ao converter de float para int, o número será arredondado em direção ao zero. A partir do PHP 8.1.0, um aviso de descontinuação é emitido quando ocorre a conversão implícita de um float não integral para int que perca precisão.

Exemplo #4 Convertendo a partir de float

    <?php

    function foo($value): int {
      return $value;
    }

    var_dump(foo(8.1)); // Descontinuado: conversão implícita de float 8.1 para int perdendo precisão a partir do PHP 8.1.0
    var_dump(foo(8.1)); // 8 antes do PHP 8.1.0
    var_dump(foo(8.0)); // 8 em ambos os casos

    var_dump((int) 8.1); // 8 em ambos os casos
    var_dump(intval(8.1)); // 8 em ambos os casos
    ?>

Se o float estiver além dos limites de int (geralmente `+/- 2.15e+9 = 2^31` em plataformas de 32 bits e `+/- 9.22e+18 = 2^63` em plataformas de 64 bits), o resultado é indefinido, já que o float não tem precisão suficiente para fornecer um resultado int exato. Nenhum alerta, nem mesmo uma nota, será emitido quando isso acontecer!

> Nota:

> `NaN`, `Inf` e `-Inf` sempre serão zero quando convertidos para int.

Aviso

Nunca converta uma fração desconhecida para int porque isto pode, algumas vezes, levar a resultados inesperados.

    <?php
    echo (int) ( (0.1+0.7) * 10 ); // mostra 7!
    ?>

Veja também o alerta sobre a precisão de número flutuante.

#### Convertendo a partir de strings

Se a string for numérica ou inicialmente numérica, ela será convertida para o valor inteiro correspondente, caso contrário, será convertida para zero (`0`).

#### Convertendo a partir de NULL

`null` é sempre convertido para zero (`0`).

#### Convertendo a partir de outros tipos

Cuidado

O comportamento da conversão de um int é desconhecido para outros tipos. Não se deve depender de nenhum comportamento observado, pois ele pode ser alterado sem aviso.

## Números de ponto flutuante

Números de ponto flutuante (também conhecidos como "floats", "doubles" ou "números reais"), podem ser especificados utilizando qualquer uma das seguintes sintaxes:

    <?php
    $a = 1.234;
    $b = 1.2e3;
    $c = 7E-10;
    $d = 1_234.567; // a partir do PHP 7.4.0
    ?>

Formalmente a partir do PHP 7.4.0 (anteriormente, sublinhados não eram permitidos):

    LNUM          [0-9]+(_[0-9]+)*
    DNUM          ({LNUM}?"."{LNUM}) | ({LNUM}"."{LNUM}?)
    EXPONENT_DNUM (({LNUM} | {DNUM}) [eE][+-]? {LNUM})

O tamanho de um número de ponto flutuante depende da plataforma, sendo o máximo de ~1.8e308 com precisão de 14 dígitos decimais um valor comum (número de 64 bits no formato IEEE).

Aviso

# Precisão de números de ponto flutuante

Números de ponto flutuante tem precisão limitada. Embora dependa do sistema, o PHP geralmente utiliza o formato de precisão dupla do IEEE 754, que trará uma precisão máxima devida a arredondamentos da ordem de 1.11e-16. Operações matemáticas incomuns poderão ocasionar erros maiores, e, claro, a propagação de erros deve ser considerada quando várias operações forem realizadas.

Além disso, números racionais que têm representação exata em números em base 10, como `0.1` ou `0.7`, não possuem representação exata em ponto flutuante na base 2, o formato utilizado internamente, não importando o tamanho da mantissa. Portanto, não existe conversão para o formato interno sem uma pequena perda de precisão. Isso pode ocasionar resultados confusos: por exemplo, `floor((0.1+0.7)*10)` normalmente retornará `7`, em vez do resultado esperado `8`, porque a representação interna final será algo como `7.9999999999999991118...`.

Então, nunca confie em resultados com números de ponto flutuante até a última casa, e nunca compare números de ponto flutuante em igualdades. Se você realmente precisar de alta precisão, você pode utilizar as funções matemáticas de precisão arbitrária e as funções gmp estão disponíveis.

Para uma explicação "simples" dessa questão, veja o » guia sobre ponto flutuante, que também tem o título alternativo de "Porque meus números não somam direito?".

### Convertendo para float

#### A partir de strings

Se a string é numérica ou começa numérica então ela irá resolver para o valor float correspondente, do contrário ela é convertida em zero (`0`).

#### A partir de outros tipos

Para valores de outros tipos, a conversão é realizada convertendo o valor para int primeiro e em seguida para float. Veja Convertendo para inteiro para mais informações.

> Nota:

> Como certos tipos têm comportamento indefinido ao converter para int, este também é o caso ao converter para float.

### Comparando floats

Como notado acima, testar números de ponto flutuante com igualdade é problemático, por causa da maneira como são representados internamente. Entretanto existem maneiras de fazer comparações com números de ponto flutuante que contornam essas limitações.

Para testar números de ponto flutuante, utilize um "valor de erro máximo" na comparação utilizada. Esse valor é também chamado de epsilon, ou unidade de erro, e deve ser a diferença mínima aceitável no resultado dos cálculos.

$a e $b serão consideradas iguais até o 5º dígito de precisão.

Exemplo #1 Comparando números de ponto flutuante

    <?php
    $a = 1.23456789;
    $b = 1.23456780;
    $epsilon = 0.00001;

    if (abs($a - $b) < $epsilon) {
        echo "iguais";
    }
    ?>

### NaN

Algumas operações numéricas podem resultar em valores representados pela constante `NAN`. Esse resultado representa um valor desconhecido ou não representável nos cálculos de ponto flutuante. Qualquer comparação frouxa ou restrita deste valor com qualquer outro, inclusive ele mesmo, com exceção de `true`, terá como resultado `false`.

Como o `NAN` representa um resultado irrepresentável, `NAN` não deve ser comparado com outros valores, incluindo ele mesmo, em vez disso, deve-se checá-lo utilizando a função is_nan().

## Strings

Uma string é uma série de caracteres, onde um caractere é o mesmo que um byte. Isso significa que o PHP possui suporte a um conjunto de apenas 256 caracteres, e, portanto, não possui suporte nativo a Unicode. Veja mais detalhes do tipo string.

> Nota: Em sistemas de 32 bits, uma string pode ter até 2GB (2147483647 bytes).

### Sintaxe

Uma string literal pode ser especificada de quatro formas diferentes.

- aspas simples
- aspas duplas
- sintaxe heredoc
- sintaxe nowdoc

#### Aspas simples

A maneira mais simples de se especificar uma string é delimitá-la entre aspas simples (o caractere `'`).

Para especificar um apóstrofo, escape-o com uma contrabarra (`\`). Para especificar uma contrabarra literal, duplique-a (`\\`). Todas as outras ocorrências da contrabarra serão tratadas como uma contrabarra literal: isso significa que outras sequências de escape que se esteja acostumado a utilizar, como `\r` ou `\n`, serão literalmente impressas em vez de ter qualquer significado especial.

> Nota: Diferentemente das sintaxes com aspas duplas e heredoc, variáveis e sequências de escape para caracteres especiais não serão expandidas quando ocorrerem dentro de uma string delimitada por aspas simples.

Exemplo #1 Variantes de sintaxe

    <?php
    echo 'isto é uma string comum', PHP_EOL;

    echo 'Você pode incluir novas linhas em strings
    dessa maneira que estará
    tudo bem', PHP_EOL;

    // Exibe: Arnold disse uma vez: "I'll be back"
    echo 'Arnold disse uma vez: "I\'ll be back"', PHP_EOL;

    // Exibe: Você excluiu C:\*.*?
    echo 'Você excluiu C:\\*.*?', PHP_EOL;

    // Exibe: Você excluiu C:\*.*?
    echo 'Você excluiu C:\*.*?', PHP_EOL;

    // Exibe: Isto não será substituído por \n uma nova linha
    echo 'Isto não será substituído por \n uma nova linha', PHP_EOL;

    // Exibe: Variáveis $também não $expandem
    echo 'Variáveis $também não $expandem', PHP_EOL;
    ?>

#### Aspas duplas

Se a string for delimitada entre aspas duplas (`"`), o PHP interpretará a seguinte sequência de escape como caracteres especiais:

Sequências de escape
Sequências | Significado
--- | ---
`\n` | Nova linha (LF ou 0x0A (10) em ASCII)
`\r` | Retorno de carro (CR ou 0x0D (13) em ASCII)
`\t` | Tabulação horizontal (HT ou 0x09 (9) em ASCII)
`\v` | Tabulação vertical (VT ou 0x0B (11) em ASCII)
`\e` | Escape (ESC ou 0x1B (27) em ASCII)
`\f` | Form feed (FF ou 0x0C (12) em ASCII)
`\\` | contrabarra ou barra invertida
`\$` | Sinal de cifrão
`\"` | aspas duplas
`\[0-7]{1,3}` | Octal: uma sequência de caracteres que coincide com a expressão regular `[0-7]{1,3}` é um caractere em notação octal (por exemplo, `"\101" === "A"`), o qual é silenciosamente turcado para um byte (por exemplo `"\400" === "\000"`)
`\x[0-9A-Fa-f]{1,2}` | Hexadecimal: uma sequência de caracteres que coincide com a expressão regular `[0-9A-Fa-f]{1,2}` é um caractere em notação decimal (por exemplo, `"\x41" === "A"`)
`\u{[0-9A-Fa-f]+}` | Unicode: uma sequência de caracteres coincidindo com a expressão regular `[0-9A-Fa-f]+` é um codepoint Unicode, o qual terá como resultado uma string contendo a representação UTF-8 desses codepoints. Os colchetes são requeridos. Por exemplo, `"\u{41}" === "A"`

Como com as strings entre aspas simples, escapar qualquer outro caractere resultará em uma contrabarra sendo impressa.

O recurso mais importante de strings delimitadas por aspas duplas é o fato de que nomes de variáveis serão expandidos. Veja a interpolação de strings para detalhes.

#### Heredoc

Uma terceira maneira de delimitar strings é a sintaxe heredoc: `<<<`. Após este operador, um identificador é fornecido seguido de uma nova linha. A própria string é colocada em seguida e a seguir o mesmo identificador novamente para fechar a string.

O identificador de fechamento pode ser indentado com espaços ou tabulações, e nesse caso a indentação será removida de todas as linhas da doc string. Anteriormente ao PHP 7.3.0, o identificador precisava estar no começo da linha.

Além disso, o identificador de fechamento precisa seguir as mesmas convenções de nomes de outros identificadores do PHP: ele precisa conter apenas caracteres alfanuméricos e underlines, e precisa começar com uma letra ou underline.

Exemplo #2 Exemplo Heredoc simples no PHP 7.3.0

    <?php
    // Sem indentação
    echo <<<END
          a
         b
        c
    \n
    END;

    // 4 espaços de indentação
    echo <<<END
          a
         b
        c
        END;

Saída do exemplo acima no PHP 7.3:

          a
         b
        c

      a
     b
    c

Se o identificador de fechamento estiver identado diferentemente das linhas do corpo, um ParseError será lançado:

Exemplo #3 Identificador de fechamento indentado diferente das linhas do corpo

    <?php
    echo <<<END
      a
     b
    c
       END;

Saída do exemplo acima no PHP 7.3:

    Parse error: Invalid body indentation level (expecting an indentation level of at least 3) in example.php on line 4

Se o identificador de fechamento é identado, tabulações podem ser utilizadas, no entanto tabulações e espaços não podem estar misturados ou diferentes, entre a indentação do fechamento e a indentação do corpo Nesses casos, um ParseError será lançado. Essas restrições de whitespace estão incluídas dados que a mistura de tabulações e espaços são prejudiciais à legibilidade.

Exemplo #4 Indentação diferente entre corpo e fechamento

    <?php
    // Todos esses códidos falharão.

    // Indentação diferente entre corpo (espaços) e fechamento (tabulações)
    {
    echo <<<END
    a
    END;
    }

    // Misturar tabulações e espaços no corpo
    {
        echo <<<END
        a
         END;
    }

    // Misturar espaços e tabulações no identificador de fechamento
    {
    echo <<<END
    a
    END;
    }

Saída do exemplo acima no PHP 7.3:

    Parse error: Invalid indentation - tabs and spaces cannot be mixed in example.php line 8

O identificador de fechamento do corpo não necessita de um ponto e vírgula ou nova linha. Por exemplo, o seguinte código é permitido a partir do PHP7.3.0:

Exemplo #5 Continuando uma expressão após o identificador de fechamento

    <?php
    $values = [<<<END
    a
      b
        c
    END, 'd e f'];
    var_dump($values);

Saída do exemplo acima no PHP 7.3:

    array(2) {
      [0] =>
      string(11) "a
      b
        c"
      [1] =>
      string(5) "d e f"
    }

Aviso

Se o identificador de fechamento for encontrado no começo da linha, existe a ambiguidade de ele ser considerado ou não parte do texto, podendo também ser considerado como fechamento, pode causar um ParseError.

Exemplo #6 Identificador de fechamento no corpo da string pode causar um ParseError

    <?php
    $values = [<<<END
    a
    b
    END ING
    END, 'd e f'];

Saída do exemplo acima no PHP 7.3:

    Parse error: syntax error, unexpected identifier "ING", expecting "]" in example.php on line 5

Para evitar esse problema, basta seguir a seguinte regra: escolha identificadores que não aparecem no corpo do texto.

Aviso

Anteriormente ao PHP 7.3.0, era muito importante notar que a linha com o identificador de fechamento não poderia conter outros caracteres, exceto um ponto e vírgula (`;`). Isso significava que o identificador de fechamento não poderia ser identado, e que não poderia haver espaços ou tabulações antes ou depois do ponto e vírgula. É importante notar também que o primeiro caractere antes do fechamento deveria ser uma newline, como definido pelo sistema operacional. Ou seja, `\n` em sistemas Unix, incluindo o macOS. O identificador de fechamento também deveria ser seguido de um newline.

Se essa regra não for seguida, e o identificador de fechamento não estiver "limpo", ele não será considerado como fechamento, e o PHP continuará lendo o script como se fosse texto. Se um identificador de fechamento correto não for encontrado até o final do arquivo, um erro de interpretação será lançado na última linha.

Exemplo #7 Exemplo inválido, antes do PHP 7.3.0

    <?php
    class foo {
        public $bar = <<<EOT
    bar
        EOT;
    }
    // O identificador não deve ser indentado
    ?>

Exemplo #8 Exemplo válido, mesmo antes do PHP 7.3.0

    <?php
    class foo {
        public $bar = <<<EOT
    bar
    EOT;
    }
    ?>

Heredocs não podem ser usados para inicializar propriedades de classe.

Textos heredoc se comportam como strings delimitadas por aspas duplas, sem as aspas duplas. Isso significa que aspas simples em heredocs não precisam ser escapadas, apesar de que os códigos de escape listados acima podem continuar sendo utilizados. Variáveis são expandidas, mas o mesmo cuidado deve ser tomado ao expressar variáveis complexas dentro do heredoc assim como nas strings.

Exemplo #9 Exemplo de delimitação de strings heredoc

    <?php
    $str = <<<EOD
    Exemplo de uma string
    distribuída em várias linhas
    utilizando a sintaxe heredoc.
    EOD;

    /* Exemplo mais complexo, com variáveis */
    class foo
    {
        var $foo;
        var $bar;

        function __construct()
        {
            $this->foo = 'Foo';
            $this->bar = array('Bar1', 'Bar2', 'Bar3');
        }
    }

    $foo = new foo();
    $name = 'Meu nome';

    echo <<<EOT
    Meu nome é "$name". Eu estou imprimindo $foo->foo.
    Agora, eu estou imprimindo {$foo->bar[1]}.
    Isto deve imprimir um 'A' maiúsculo: \x41
    EOT;
    ?>

O exemplo acima produzirá:

    Meu nome é "Meu nome". Eu estou imprimindo Foo.
    Agora, eu estou imprimindo Bar2.
    Isto deve imprimir um 'A' maiúsculo: A

É possível também utilizar a sintaxe Heredoc para passar dados para argumentos de funções:

Exemplo #10 Exemplo de Heredoc em argumentos

    <?php
    var_dump(array(<<<EOD
    foobar!
    EOD
    ));
    ?>

É possível inicializar variáveis estáticas e propriedades/constantes de classe utilizando a sintaxe heredoc:

Exemplo #11 Utilizando o Heredoc na inicialização de valores estáticos

    <?php
    // Variáveis estáticas
    function foo()
    {
        static $bar = <<<LABEL
    Nada aqui...
    LABEL;
    }

    // Classe propriedades/constantes
    class foo
    {
        const BAR = <<<FOOBAR
    Exemplo de constante
    FOOBAR;

        public $baz = <<<FOOBAR
    Exemplo de propriedade
    FOOBAR;
    }
    ?>

O identificador de abertura do Heredoc pode ser opcionalmente delimitado por aspas duplas:

Exemplo #12 Usando aspas duplas no Heredoc

    <?php
    echo <<<"FOOBAR"
    Olá, mundo!
    FOOBAR;
    ?>

#### Nowdoc

Nowdocs estão para aspas simples assim como os heredocs estão para aspas duplas em strings. Um nowdoc é especificado similarmente a um heredoc, mas nenhuma interpolação é feita dentro de um nowdoc. A construção é ideal para colocar códigos PHP ou outros grandes blocos de texto sem a necessidade de usar escapes. Compartilha algumas características em comum com a construção SGML `<![CDATA[ ]]>`, assim é declarado um bloco de texto onde nada será analisado.

Um nowdoc é identificado com a mesma sequência `<<<` usada para heredocs, mas o identificador precisa ficar entre aspas simples, por exemplo. `<<<'EOT'`. Todas as regras para identificadores heredoc também se aplicam para identificadores nowdoc, especialmente aquelas referentes a aparência do identificador de fechamento.

Exemplo #13 Exemplo de string em Nowdoc

    <?php
    echo <<<'EOD'
    Exemplo de string abrangendo várias linhas
    usando a sintaxe nowdoc. As barras invertidas são sempre tratadas literalmente,
    por exemplo. \\ e \'.
    EOD;

O exemplo acima produzirá:

    Exemplo de string abrangendo várias linhas
    usando a sintaxe nowdoc. As barras invertidas são sempre tratadas literalmente,
    por exemplo. \\ e \'.

Exemplo #14 Exemplo de Nowdoc, com variáveis

    <?php
    class foo
    {
        public $foo;
        public $bar;

        function __construct()
        {
            $this->foo = 'Foo';
            $this->bar = array('Bar1', 'Bar2', 'Bar3');
        }
    }

    $foo = new foo();
    $name = 'MyName';

    echo <<<'EOT'
    Meu nome é "$nome". Estou imprimindo alguns $foo->foo.
    Agora, estou imprimindo alguns {$foo->bar[1]}.
    Isso não deve imprimir um 'A' maiúsculo: \x41
    EOT;
    ?>

O exemplo acima produzirá:

    Meu nome é "$nome". Estou imprimindo alguns $foo->foo.
    Agora, estou imprimindo alguns {$foo->bar[1]}.
    Isso não deve imprimir um 'A' maiúsculo: \x41

Exemplo #15 Exemplo de dado estático

    <?php
    class foo {
        public $bar = <<<'EOT'
    bar
    EOT;
    }
    ?>

#### Interpolação de strings

Quando uma string é especificada dentro de aspas duplas ou heredoc, as variáveis podem ser substituídas dentro dela.

Há dois tipos de sintaxe: uma básica e uma avançada. A sintaxe básica é a mais comum e conveniente. Provê uma maneira de incorporar uma variável, o valor de um array ou uma propriedade de object em uma string com o mínimo de esforço.

##### Sintaxe básica

Se um sinal de cifrão (`$`) for encontrado, os caracteres que o seguem, e que podem ser usados em nome de variável, serão interpretados como tal e substituídos.

Exemplo #16 Interpolação de string

    <?php
    $suco = "maçã";

    echo "Ele bebeu um pouco de suco de $suco." . PHP_EOL;

    ?>

O exemplo acima produzirá:

    Ele bebeu um pouco de suco de maçã.

Formalmente, a estrutura para a sintaxe básica de substituição de variável é o seguinte:

    string-variável::
         nome-de-variável   (posição-ou-propriedade)?
       | ${   expressão   }

    posição-ou-propriedade::
         posição-na-string
       | propriedade-na-string

    posição-na-string::
         [   nome   ]
       | [   nome-de-variável   ]
       | [   inteiro-literal   ]

    propriedade-na-string::
         ->  nome

    nome-de-variável::
         $   nome

    nome::
         [a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*

Aviso

A sintaxe `${ expressão }` foi descontinuada a partir do PHP 8.2.0, já que pode ser interpretada como variáveis variáveis:

    <?php
    const foo = 'bar';
    $foo = 'foo';
    $bar = 'bar';
    var_dump("${foo}");
    var_dump("${(foo)}");
    ?>

Saída do exemplo acima no PHP 8.2:

    Deprecated: Using ${var} in strings is deprecated, use {$var} instead in file on line 6

    Deprecated: Using ${expr} (variable variables) in strings is deprecated, use {${expr}} instead in file on line 9
    string(3) "foo"
    string(3) "bar"

O exemplo acima produzirá:

    string(3) "foo"
    string(3) "bar"

A sintaxe avançada de interpolação de string deve ser usada em seu lugar.

> Nota: Se não for possível formar um nome válido, o símbolo de cifrão permanece literalmente na string:

>     <?php
>     echo "Nenhuma interpolação $ aconteceu\n";
>     echo "Nenhuma interpolação $\n aconteceu\n";
>     echo "Nenhuma interpolação $2 aconteceu\n";
>     ?>

> O exemplo acima produzirá:

>     Nenhuma interpolação $ aconteceu
>     Nenhuma interpolação $
>      aconteceu
>     Nenhuma interpolação $2 aconteceu

Exemplo #17 Interpolando o valor da primeira dimensão de um array ou propriedade

    <?php
    $sucos = array("maça", "laranja", "chave_string" => "roxo");

    echo "Ele bebeu um pouco de suco de $sucos[0].";
    echo PHP_EOL;
    echo "Ele bebeu um pouco de suco de $sucos[1].";
    echo PHP_EOL;
    echo "Ele bebeu um pouco de suco de $sucos[chave_string].";
    echo PHP_EOL;

    class A {
        public $s = "string";
    }

    $o = new A();

    echo "Valor do objeto: $o->s.";
    ?>

O exemplo acima produzirá:

    Ele bebeu um pouco de suco de maçã.
    Ele bebeu um pouco de suco de laranja.
    Ele bebeu um pouco de suco de roxo.
    Valor do objeto: string.

> Nota: A chave do array deve ser sem aspas, e por isso não é possível referenciar uma constante como chave com a sintaxe básica. Use a sintaxe avançada em seu lugar.

A partir do PHP 7.1.0 índices numéricos negativos são suportados.

Exemplo #18 Índices numéricos negativos

    <?php
    $string = 'string';
    echo "O caractere no índice -2 é $string[-2].", PHP_EOL;
    $string[-3] = 'o';
    echo "Alterar o caractere no índice -3 para 'o' dá $string.", PHP_EOL;
    ?>

O exemplo acima produzirá:

    O caractere no índice -2 é n.
    Alterar o caractere no índice -3 para o dá strong.

Para qualquer coisa mais complexa, a sintaxe avançada deve ser usada.

##### Sintaxe avançada (com chaves)

A sintaxe avançada permite a interpolação de variáveis com acessadores arbitrários.

Qualquer variável escalar, elemento de array ou propriedade de objeto (static ou não) com uma representação de uma string pode ser incluída com essa sintaxe. A expressão é escrita da mesma forma como apareceria fora da string e então coloque-o entre `{` e `}`. Já que que `{` não pode escapado, esta sintaxe será somente reconhecida quando o `$` seguir, imediatamente, o `{`. Use `{\$` para obter um literal `{$`. Alguns exemplos que tornam isto claro:

Exemplo #19 Sintaxe com chaves

    <?php
    const DATA_KEY = 'chave-const';
    $fantastico = 'fantástico';
    $arr = [
        '1',
        '2',
        '3',
        [41, 42, 43],
        'chave' => 'Valor indexado',
        'chave-const' => 'Chave com sinal de menos',
        'foo' => ['foo1', 'foo2', 'foo3']
    ];

    // Não vai funcionar, resultado: Isso é { fantástico}
    echo "Isso é { $fantastico}" . PHP_EOL;

    // Funciona, resultado: Isso é fantástico
    echo "Isso é {$fantastico}" . PHP_EOL;

    // Para mostrar chaves na saída:
    echo "Isso é {{$fantastico}}" . PHP_EOL;

    class Square {
        public $width;

        public function __construct(int $width) { $this->width = $width; }
    }

    $square = new Square(5);

    // Funciona
    echo "Este quadrado tem {$square->width}00 centímetros de largura." . PHP_EOL;

    // Funciona, as chaves entre aspas funcionam apenas usando a sintaxe de chaves
    echo "Isso funciona: {$arr['chave']}" . PHP_EOL;

    // Funciona
    echo "Isso funciona: {$arr[3][2]}" . PHP_EOL;

    echo "Isso funciona: {$arr[DATA_KEY]}" . PHP_EOL;

    // Ao usar arrays multidimensionais, sempre use chaves em torno dos arrays
    // quando dentro de strings
    echo "Funciona: {$arr['foo'][2]}" . PHP_EOL;

    echo "Funciona: {$obj->values[3]->name}" . PHP_EOL;

    echo "Funciona: {$obj->$staticProp}" . PHP_EOL;

    // Não funciona, imprime: C:\diretório\{fantástico}.txt
    echo "C:\diretório\{$fantastico}.txt" . PHP_EOL;

    // Funciona, imprime: C:\diretório\fantástico.txt
    echo "C:\\diretório\\{$fantastico}.txt" . PHP_EOL;
    ?>

> Nota: Como esta sintaxe permite expressões arbitrárias, é possível usar variáveis variáveis dentro da sintaxe avançada.

#### Acesso e modificação da string por caractere

É possível acessar e modificar caracteres dentro de strings especificando a posição, baseada em zero, do caractere desejado na string usando colchetes, parecido com arrays, por exemplo $str[42]. Imagine uma string como um array de caracteres. As funções substr() e substr_replace(), podem ser utilizadas quando se deseja extrair ou substituir mais que 1 caractere.

> Nota: A partir do PHP 7.1.0, posições negativas para strings são suportadas. Estas especificam a posição do final da string. Antes, posições negativas emitiam um `E_NOTICE` para leitura (gerando um string vazia) e um `E_WARNING` para escrita (deixando a string intocada).

> Nota: Anteriormente ao PHP 8.0.0, strings também poderiam ser usados utilizando chaves, por exemplo $str{42}. Essa sintaxe por chaves foi descontinuada desde o PHP 7.4.0 e não é mais suportada a partir do PHP 8.0.0.

Aviso

Escrever em uma posição fora do intervalo preenche a string com espaços. Tipos diferentes de inteiro são convertidos para inteiro. Tipo ilegal de deslocamento emite um `E_WARNING`. Apenas o primeiro caractere de uma string atribuída é usado. A partir de PHP 7.1.0, a atribuição de uma string vazia lança um erro fatal. Antes, era atribuído o byte NULL.

Aviso

Internamente, as strings do PHP são arrays de bytes. Como resultado, acessar ou modificar uma string usando colchetes não é seguro com multi-bytes e deve ser feito somente em strings que utilizem apenas um byte em sua codificação, como a ISO-8859-1.

> Nota: A partir do PHP 7.1.0, aplicar um operador de índice vazio em uma string lança um erro fatal Antes, a string vazia era convertida em um array.

Exemplo #20 Alguns exemplos com strings

    <?php
    // Obtém o primeiro caractere de uma string
    $str = 'Isto é um teste.';
    $first = $str[0];
    var_dump($first);

    // Obtém o terceiro caractere de uma string
    $third = $str[2];
    var_dump($third);

    // Obtém o último caractere de uma string
    $str = 'Isto ainda é um teste.';
    $last = $str[strlen($str)-1];
    var_dump($last);

    // Modifica o último caractere de uma string
    $str = 'Olhe para a onda';
    $str[strlen($str)-1] = 'e';
    var_dump($str);
    ?>

Índices de strings devem ser inteiros ou strings parecidos com inteiros, de outra forma um aviso é lançado.

Exemplo #21 Exemplo de índices inválidos em strings

    <?php
    $str = 'abc';

    $keys = [ '1', '1.0', 'x', '1x' ];

    foreach ($keys as $keyToTry) {
        var_dump(isset($str[$keyToTry]));

        try {
            var_dump($str[$keyToTry]);
        } catch (TypeError $e) {
            echo $e->getMessage(), PHP_EOL;
        }

        echo PHP_EOL;
    }
    ?>

O exemplo acima produzirá:

    bool(true)
    string(1) "b"

    bool(false)
    Cannot access offset of type string on string

    bool(false)
    Cannot access offset of type string on string

    bool(false)

    Warning: Illegal string offset "1x" in Standard input code on line 10
    string(1) "b"

> Nota:

> Acessar variáveis de outros tipos (excluindo-se arrays ou objetos que implementem certas interfaces) usando `[]` ou `{}` silenciosamente retornará `null`.

> Nota:

> Caracteres dentro de strings literais podem ser acessados utilizando `[]` ou `{}`.

> Nota:

> Acessar caracteres em strings utilizando a sintax por `{}` foi descontinuada desde o PHP 7.4, e não existe no PHP 8.0.

### Funções e operadores úteis

Strings podem ser concatenadas utilizando o operador '.' (ponto). Note que o operador '+' (adição) não funciona para isso. Veja operadores de string para mais informações.

Há bastantes funções úteis para manipulação de strings.

Veja a seção de funções de string para funções gerais e funções de expressões regulares compatíveis com Perl para funcionalidades avançadas de localização & e substituição.

Há também funções para strings URL e funções para criptografia/descriptografia de strings (Sodium e Hash).

Finalmente, veja também as funções de tipos de caracteres.

### Conversão em strings

Um valor pode ser convertido em uma string utilizando o modificador `(string)` ou a função strval(). A conversão em string é automaticamente realizada no escopo de uma expressão onde uma string é necessária. Isto acontece no uso das funções echo ou print ou quando o valor de uma variável é comparado com uma string. As seções Tipos e Conversão de Tipos tornarão um pouco mais claro o assunto. Veja também a função settype().

O valor bool `true` é convertido para a string `"1"`. O bool `false` é convertido para `""` (uma string vazia). Isso permite converter nos dois sentidos entre os valores bool e string.

Um int ou um float é convertido para uma string representando o número textualmente (incluindo a parte do expoente nos floats). Números de ponto flutuante podem ser convertidos usando a notação exponencial (`4.1E+6`).

> Nota:

> A partir do PHP 8.0.0, o caractere de separação de decimais sempre é um ponto ("`.`"). Anteriormente ao PHP 8.0.0, o separador de decimais era definido pela localidade do script (LC_NUMERIC). Veja mais detalhes na função setlocale().

Arrays são sempre convertidos para uma string `"Array"`; por isso echo e print não podem, por si só, mostrar o conteúdo de um array. Para visualizar um único elemento, use uma construção como `echo $arr['foo']`. Veja abaixo dicas de como visualizar todo seu conteúdo.

Para converter objects em strings, o método mágico __toString deve ser usado.

Resources são sempre convertidos para strings na estrutura `"Resource id #1"` onde `1` é o número único do resource atribuído pelo PHP em tempo de execução. Apesar de que a estrutura exata desta string não seja confiável e esteja sujeita a modificações, será sempre única a um dado recurso dentro do ciclo de vida de um script sendo executado (por exemplo, em uma requisição Web ou em um processo CLI) e não será reutilizada. Para obter o tipo de um resource, utilize a função get_resource_type().

`null` é sempre convertido para uma string vazia.

Como declarado acima, converter diretamente um array, object ou resource para uma string não fornece nenhuma informação útil sobre o valor, a não ser seu tipo. Veja as funções print_r() e var_dump() para maneiras mais efetivas de inspecionar o conteúdo destes tipos.

A maioria dos valores no PHP também podem ser convertidos em strings para armazenamento permanente. Este método é chamado de serialização e pode ser feito com a função serialize().

### Detalhes do tipo string

A string no PHP é implementada como um array de bytes e um inteiro indicando seu tamanho no buffer. Não existem informações de como esses bytes são traduzidos em caracteres, ficando essa tarefa com o programador. Não existem limitações sobre a composição dos valores da string; em particular, bytes com valor `0` (“NUL bytes”) são permitidos em qualquer lugar da string (entretanto, algumas funções, mencionadas neste manual como não “binary safe”, podem repassar as strings para bibliotecas que ignorem os dados após o byte nulo.)

Esta natureza do tipo string explica o motivo de não haver o tipo "byte" disponível no PHP – as strings assumem este papel. Funções que não retornam nenhuma informação textual – por exemplo, dados arbitrários lidos de um socket de rede – continuarão retornando strings.

Dado que o PHP não dita uma codificação específica para strings, pode-se questionar como strings literais seriam codificadas. Por exemplo, a string `"á"` é equivalente a `"\xE1"` (ISO-8859-1), `"\xC3\xA1"` (UTF-8, C form), `"\x61\xCC\x81"` (UTF-8, D form) ou qualquer outra representação possível? A resposta é que a string poderá ser codificada em qualquer forma que o arquivo de script estiver codificado. Assim, se o script for escrito na codificação ISO-8859-1, a string será codificada como ISO-8859-1 e assim por diante. Entretanto, isso não se aplica se o Zend Multibyte estiver ativado; neste caso, o script pode ser escrito em uma codificação arbitrária (que é declarada explicitamente ou é detectada) e então convertida em um codificação interna, a qual será a codificação utilizada nas strings literais. Note que há algumas restrições na codificação do script (ou na codificação interna caso o Zend Multibyte esteja ativo) – isso quase sempre significa que essa codificação deve ser um conjunto que contenha dentro de si a ASCII, como UTF-8 ou ISO-8859-1. Note, entretanto, que codificações que são dependentes de estado, onde os mesmos valores de bytes possam ser utilizados tanto em estados iniciais quanto não iniciais, podem ser problemáticos.

Claro que, para serem úteis, funções que operam em textos podem ter que fazer certas suposições sobre como as strings foram codificadas. Infelizmente, existem muitas variações sobre este assunto através das funções do PHP:

- Algumas funções assumem que a string foi codificada em alguma (qualquer) codificação de byte único, mas elas não precisam interpretar estes bytes como caracteres específicos. Este é por exemplo o caso das funções substr(), strpos(), strlen() ou strcmp(). Outra forma de refletir sobre essas funções é que elas operam em buffers de memória, isto é, elas trabalham com bytes e deslocamento de bytes.
- Outras funções recebem a codificação da string, possivelmente elas assumem um padrão se nenhuma informação lhes for passada. Este é o caso da função htmlentities() e da maioria das funções da extensão mbstring.
- Outras utilizam o idioma atual (veja setlocale()), mas elas operam byte-a-byte.
- Finalmente, elas podem simplesmente assumir que a string esteja utilizando uma codificação específica, geralmente UTF-8. Este é o caso da maioria das funções das extensões intl e PCRE (na segunda, somente quando o modificador `u` é utilizado).

Por fim, isso significa que escrever programas corretos utilizando Unicode depende de evitar cuidadosamente funções que não funcionam e que provavelmente irão corromper os dados e usar, em substituição, funções que se comportem corretamente, geralmente das extensões intl e mbstring. Entretanto, usar funções que manipulam codificação Unicode é somente o começo. Não importa as funções que a linguagem provê, é essencial saber a especificação Unicode. Por exemplo, um programa que supõe que só existem maiúsculas e mínusculas está fazendo uma suposição errada.

## Strings numéricas

Uma string PHP é considerada numérica se puder ser interpretada como int ou float.

Formalmente a partir do PHP 8.0.0:

    WHITESPACES      \s*
    LNUM             [0-9]+
    DNUM             ([0-9]*[\.]{LNUM}) | ({LNUM}[\.][0-9]*)
    EXPONENT_DNUM    (({LNUM} | {DNUM}) [eE][+-]? {LNUM})
    INT_NUM_STRING   {WHITESPACES} [+-]? {LNUM} {WHITESPACES}
    FLOAT_NUM_STRING {WHITESPACES} [+-]? ({DNUM} | {EXPONENT_DNUM}) {WHITESPACES}
    NUM_STRING       ({INT_NUM_STRING} | {FLOAT_NUM_STRING})

O PHP também tem um conceito de strings numéricas principais. Isso é simplesmente uma string que começa como uma string numérica seguida por qualquer caractere.

> Nota:

> Qualquer string que contenha a letra `E` (sem distinção entre maiúsculas e minúsculas) delimitada por números será vista como um número expresso em notação científica. Isso pode produzir resultados inesperados.

> Exemplo #1 Comparações de notações científicas

>     <?php
>     var_dump("0D1" == "000"); // falso, "0D1" não é notação científica
>     var_dump("0E1" == "000"); // verdadeiro, "0E1" é 0 * (10 ^ 1), ou 0
>     var_dump("2E1" == "020"); // verdadeiro, "2E1" é 2 * (10 ^ 1), ou 20
>     ?>

### Strings usadas em contextos numéricos

Quando uma string precisa ser avaliada como número (por exemplo, operações aritméticas, declaração de tipo int, etc.), as seguintes etapas são executadas para determinar o resultado:

1. Se a string for numérica, resolva para um int se a string for uma string numérica inteira e se encaixar nos limites do tipo int (conforme definido por `PHP_INT_MAX`), caso contrário resolva para um float.
2. Se o contexto permitir strings numéricas iniciais e a string for uma, resolva para um int se a parte inicial da string for uma string numérica inteira e se encaixar nos limites do tipo int (conforme definido por `PHP_INT_MAX`), caso contrário resolva para um float. Além disso, um erro de nível `E_WARNING` é gerado.
3. A string não é numérica, lance um TypeError.

### Comportamento antes do PHP 8.0.0

Antes do PHP 8.0.0, uma string era considerada numérica apenas se tivesse espaços em branco à esquerda, se tivesse espaços em branco à direita, a string era considerada numérica à esquerda.

Antes do PHP 8.0.0, quando uma string era usada em um contexto numérico, ela executava as mesmas etapas acima com as seguintes diferenças:

- O uso de uma sequência numérica inicial geraria um `E_NOTICE` em vez de um `E_WARNING`.
- Se a string não for numérica, um `E_WARNING` foi levantado e o valor `0` seria retornado.

Antes do PHP 7.1.0, nem `E_NOTICE` nem `E_WARNING` eram gerados.

    <?php
    $foo = 1 + "10.5";                // $foo é float (11.5)
    $foo = 1 + "-1.3e3";              // $foo é float (-1299)
    $foo = 1 + "bob-1.3e3";           // TypeError a partir do PHP 8.0.0, $foo é inteiro (1) anteriormente
    $foo = 1 + "bob3";                // TypeError a partir do PHP 8.0.0, $foo é inteiro (1) anteriormente
    $foo = 1 + "10 Small Pigs";       // $foo é inteiro (11) e um E_WARNING é levantado no PHP 8.0.0, E_NOTICE anteriormente
    $foo = 4 + "10.2 Little Piggies"; // $foo é float (14.2) e um E_WARNING é levantado no PHP 8.0.0, E_NOTICE anteriormente
    $foo = "10.0 pigs " + 1;          // $foo é float (11) e um E_WARNING é levantado no PHP 8.0.0, E_NOTICE anteriormente
    $foo = "10.0 pigs " + 1.0;        // $foo é float (11) e um E_WARNING é levantado no PHP 8.0.0, E_NOTICE anteriormente
    ?>

## Arrays

Para uma lista de todas as funções de array, consulte o capítulo sobre funções de array na documentação.

Um array no PHP é na verdade um mapa ordenado. Um mapa é um tipo que relaciona valores a chaves. Este tipo é otimizado para vários usos diferentes: ele pode ser tratado como um array, uma lista (vetor), tabela de hashes (que é uma implementação de mapa), dicionário, coleção, pilha, fila e provavelmente mais. Assim como existe a possibilidade dos valores do array serem outros arrays, árvores e arrays multidimensionais.

A explicação dessas estruturas está além do escopo deste manual, mas pelo menos um exemplo é dado para cada uma delas. Para mais informações, busque a considerável literatura que existe sobre esse extenso tópico.

### Sintaxe

#### Especificando com array()

Um array pode ser criado com o construtor de linguagem array(). Ele leva qualquer quantidade de pares separados por vírgula `chave => valor` como argumentos.

    array(
        chave  => valor,
        chave2 => valor2,
        chave3 => valor3,
        ...
    )

A vírgula após o último elemento do array é opcional e pode ser omitida. Isso geralmente é feito para arrays em uma única linha, por exemplo, `array(1, 2)` é preferível em vez de `array(1, 2, )`. Para arrays escritos em várias linhas, por outro lado, a vírgula à direita do último elemento é usada frequentemente, para permitir a adição de forma simples de novos elementos ao final.

> Nota:

> Existe uma sintaxe curta que substitui `array()` por `[]`.

Exemplo #1 Um array simples

    <?php
    $array1 = array(
        "foo" => "bar",
        "bar" => "foo",
    );

    // Utilizando a sintaxe curta
    $array2 = [
        "foo" => "bar",
        "bar" => "foo",
    ];

    var_dump($array1, $array2);
    ?>

A chave pode ser um int ou uma string. O valor pode ser de qualquer tipo.

Adicionalmente, as seguintes coerções ocorrerão a chave:

- strings contendo quaisquer ints válidos, que não sejam precedidos do sinal de `+`, serão convertidos para o tipo int. Por exemplo, a chave`"8"` será, na verdade, armazenada como `8`. Entretanto, `"08"` não será convertido, por não ser um inteiro decimal válido.
- floats também são convertidos para ints, isso significa que a parte fracionária será removida. Por exemplo, a chave `8.7` será na verdade armazenada como `8`.
- bools são convertidos para ints, igualmente, por exemplo, a chave `true`, será na verdade armazenada como `1` e a chave `false` como `0`.
- null será convertido para uma string vazia, por exemplo, a chave `null` na verdade será armazenada como `""`.
- arrays e objects não podem ser usados como chaves. Fazer isso resultará em um aviso: `Illegal offset type`.

Se vários elementos na declaração do array utilizam a mesma chave, apenas o último será utilizado, enquanto todos os outros serão sobrescritos.

Exemplo #2 Exemplo de conversão de tipo e sobrescrita

    <?php
    $array = array(
        1    => "a",
        "1"  => "b",
        1.5  => "c",
        true => "d",
    );
    var_dump($array);
    ?>

O exemplo acima produzirá:

    array(1) {
      [1]=>
      string(1) "d"
    }

Como todas as chaves do exemplo acima foram convertidas para `1`, o valor será sobrescrito a cada novo elemento e o valor final atribuído `"d"`, será o único que restará.

As chaves dos arrays no PHP podem conter, ao mesmo tempo, int e string, porque o PHP não faz distinção entre arrays indexados e associativos.

Exemplo #3 Misturando int e string nas chaves

    <?php
    $array = array(
        "foo" => "bar",
        "bar" => "foo",
        100   => -100,
        -100  => 100,
    );
    var_dump($array);
    ?>

O exemplo acima produzirá:

    array(4) {
      ["foo"]=>
      string(3) "bar"
      ["bar"]=>
      string(3) "foo"
      [100]=>
      int(-100)
      [-100]=>
      int(100)
    }

A key é opcional. Se não for especificada, o PHP utilizará o incremento da chave do tipo int com maior valor utilizado.

Exemplo #4 Arrays indexados sem chaves

    <?php
    $array = array("foo", "bar", "hello", "world");
    var_dump($array);
    ?>

O exemplo acima produzirá:

    array(4) {
      [0]=>
      string(3) "foo"
      [1]=>
      string(3) "bar"
      [2]=>
      string(5) "hello"
      [3]=>
      string(5) "world"
    }

É possível especificar a chave somente para alguns elementos e omití-las para outros:

Exemplo #5 Chaves em alguns elementos

    <?php
    $array = array(
             "a",
             "b",
        6 => "c",
             "d",
    );
    var_dump($array);
    ?>

O exemplo acima produzirá:

    array(4) {
      [0]=>
      string(1) "a"
      [1]=>
      string(1) "b"
      [6]=>
      string(1) "c"
      [7]=>
      string(1) "d"
    }

Como pode ver, o último valor `"d"` foi atribuído à chave `7`. Isso acontece porque a chave com maior inteiro antes dela era `6`.

Exemplo #6 Exemplo de sobrescrita e cast de tipo complexo

Este exemplo inclui todas as variações de cast de tipo de chaves e sobrescrita de elementos.

    <?php
    $array = array(
        1    => 'a',
        '1'  => 'b', // o valor "a" será sobrescrito por "b"
        1.5  => 'c', // o valor "b" será sobrescrito por "c"
        -1 => 'd',
        '01'  => 'e', // não é uma string de inteiro e NÃO sobrescreve a chave 1
        '1.5' => 'f', // não é uma string de inteiro e NÃO sobrescreve a chave 1
        true => 'g', // o valor "c" será sobrescrito por "g"
        false => 'h',
        '' => 'i',
        null => 'j', // o valor "i" será sobrescrito por "j"
        'k',      // o valor "k" será alocado na chave 2. Isto porque é o maior inteiro após a chave 1
        2 => 'l', // o valor "k" será sobrescrito por "l"
    );

    var_dump($array);
    ?>

O exemplo acima produzirá:

    array(7) {
      [1]=>
      string(1) "g"
      [-1]=>
      string(1) "d"
      ["01"]=>
      string(1) "e"
      ["1.5"]=>
      string(1) "f"
      [0]=>
      string(1) "h"
      [""]=>
      string(1) "j"
      [2]=>
      string(1) "l"
    }

Exemplo #7 Exemplo de índice negativo

Ao atribuir uma chave inteira negativa `n`, o PHP irá atribuir `n+1` à chave seguinte.

    <?php
    $array = [];

    $array[-5] = 1;
    $array[] = 2;

    var_dump($array);
    ?>

O exemplo acima produzirá:

    array(2) {
      [-5]=>
      int(1)
      [-4]=>
      int(2)
    }

Aviso

Antes do PHP 8.3.0, atribuir uma chave inteira negativa `n` causaria a atribuição de `0` à chave seguinte, portando o exemplo anterior teria este resultado:

    array(2) {
      [-5]=>
      int(1)
      [0]=>
      int(2)
    }

#### Acessando elementos do array com colchetes

Elementos do array podem ser acessados utilizando a sintaxe `array[chave]`.

Exemplo #8 Acessando elementos do array

    <?php
    $array = array(
        "foo" => "bar",
        42    => 24,
        "multi" => array(
             "dimensional" => array(
                 "array" => "foo"
             )
        )
    );

    var_dump($array["foo"]);
    var_dump($array[42]);
    var_dump($array["multi"]["dimensional"]["array"]);
    ?>

O exemplo acima produzirá:

    string(3) "bar"
    int(24)
    string(3) "foo"

> Nota:

> Anteriormente ao PHP 8.0.0, chaves e colchetes podiam ser utilizados para acessar elementos de um array (por exemplo, `$array[42]` e `$array{42}` irão fazer a mesma coisa que o exemplo anterior). O acesso por chaves foi descontinuado a partir do PHP 7.4.0 e não é mais suportado a partir do PHP 8.0.0.

Exemplo #9 Referenciando elemento de um array

    <?php
    function getArray() {
        return array(1, 2, 3);
    }

    $secondElement = getArray()[1];

    var_dump($secondElement);
    ?>

> Nota:

> Tentativas de acesso a uma chave de array que não foi definida é o mesmo que acessar qualquer outra variável indefinida: uma mensagem de erro de nível `E_WARNING` (`E_NOTICE` anteriormente ao PHP 8.0.0) será emitida, e o resultado será `null`.

> Nota:

> Acessar um array através de uma chave que não é string retorna `null`. Anteriormente ao PHP 7.4.0 não era emitida uma mensagem. A partir do PHP 7.4.0 emite um `E_NOTICE`; e a partir do PHP 8.0.0 é emitido um `E_WARNING`.

#### Criando/modificando com a sintaxe de colchetes

Você pode também modificar um array existente explicitamente assimilando valores a ele.

Isto é feito apenas assimilando valores para o array enquanto especifica a chave em colchetes. Você pode omitir a chave, colocando um par vazio de colchetes (`[]`).

    $arr[chave] = valor;
    $arr[] = valor;
    // chave pode ser tanto um int quanto uma string
    // valor pode ser qualquer valor de qualquer tipo

Se $arr ainda não existir ou estiver definido como `null` ou `false`, ele será criado, por isso também é uma alternativa para criação de um array. Entretanto, essa prática é desencorajada por que se $arr conter algum valor (por exemplo, uma string de uma variável de requisição), então este valor permanecerá e o `[]` funcionará como um operador de acesso a string. Sempre será recomendado a inicialização de uma variável por atribuição direta.

> Nota: A partir do PHP 7.1.0, aplicar um operador de índice vazio a uma string lança um erro fatal. Antes, a string era silenciosamente convertida em um array.

> Nota: A partir do PHP 8.1.0, criar um novo array a partir do valor `false` foi descontinuado. Criar um array a partir de `null` e valores indefinidos ainda é permitido.

Para mudar um certo valor, apenas atribua um novo valor a um elemento especificado por sua chave. Se a intenção for remover um par de chave/valor, é necessário aplicar a função unset() na chave.

Exemplo #10 Usando colchetes com arrays

    <?php
    $arr = array(5 => 1, 12 => 2);

    $arr[] = 56;    // Isto é o mesmo que $arr[13] = 56;
                    // nesse ponto do script

    $arr["x"] = 42; // Isto acrescenta um novo elemento
                    // para o array com a chave "x"

    unset($arr[5]); // Isto remove um elemento do array

    var_dump($arr);

    unset($arr);    // E isto apaga todo o array

    var_dump($arr);
    ?>

> Nota: Se nenhuma chave for especificada, ela será igual ao maior índice inteiro existente + `1`. Se o array não tiver índices inteiros positivos, a chave será `0`. A partir do PHP 8.3.0, também pode ser um inteiro negativo.

> Note que a chave inteira de maior valor utilizada não precisa necessariamente existir no array. Ele precisa ter existido no array em algum momento desde a última reindexação do array. Veja o exemplo a seguir:

>     <?php
>     // Criando um array normal
>     $array = array(1, 2, 3, 4, 5);
>     print_r($array);

>     // Agora apagando todos os itens, mas deixando o array intacto:
>     foreach ($array as $i => $value) {
>         unset($array[$i]);
>     }
>     print_r($array);

>     // Acrescentando um item (note que a chave é 5, em vez de zero).
>     $array[] = 6;
>     print_r($array);

>     // Reindexando:
>     $array = array_values($array);
>     $array[] = 7;
>     print_r($array);
>     ?>

> O exemplo acima produzirá:

>     Array
>     (
>         [0] => 1
>         [1] => 2
>         [2] => 3
>         [3] => 4
>         [4] => 5
>     )
>     Array
>     (
>     )
>     Array
>     (
>         [5] => 6
>     )
>     Array
>     (
>         [0] => 6
>         [1] => 7
>     )

#### Desconstruindo arrays

Arrays podem ser desconstruídos utilizando `[]` (a partir do PHP 7.1.0) ou list(). Esses constructos podem ser utilizados para desconstruir o array em variáveis distintas.

Exemplo #11 Desconstruindo arrays

    <?php
    $source_array = ['foo', 'bar', 'baz'];

    [$foo, $bar, $baz] = $source_array;

    echo $foo, PHP_EOL;    // exibe "foo"
    echo $bar, PHP_EOL;    // exibe "bar"
    echo $baz, PHP_EOL;    // exibe "baz"
    ?>

A desconstrução de arrays pode ser utilizada no `foreach` para desconstruir um array multidimensional enquanto o percorre.

Exemplo #12 Desconstruindo arrays em Foreach

    <?php
    $source_array = [
        [1, 'John'],
        [2, 'Jane'],
    ];

    foreach ($source_array as [$id, $name]) {
        echo "{$id}: '{$name}'\n";
    }
    ?>

Elementos de arrays serão ignorados se a variável não for providenciada. A desconstrução de arrays sempre inicia no índice `0`.

Exemplo #13 Ignorando Elementos

    <?php
    $source_array = ['foo', 'bar', 'baz'];

    // Atribui o elemento de índice 2 na variável $baz
    [, , $baz] = $source_array;

    echo $baz;    // exibe "baz"
    ?>

A partir do PHP 7.1.0, é possível desconstruir arrays associativos. Isto permite fácil seleção do elemento correto de uma forma indexada numericamente dado que os índices podem ser especificados.

Exemplo #14 Desconstruindo arrays associativos

    <?php
    $source_array = ['foo' => 1, 'bar' => 2, 'baz' => 3];

    // Atribui o elemento de índice 'baz' na variável $three
    ['baz' => $three] = $source_array;

    echo $three, PHP_EOL;    // exibe 3

    $source_array = ['foo', 'bar', 'baz'];

    // Atribui o elemento de índice 2 na variável $baz
    [2 => $baz] = $source_array;

    echo $baz, PHP_EOL;    // exibe "baz"
    ?>

A desconstrução de arrays pode ser utilizada para trocar duas variáveis.

Exemplo #15 Trocando duas variáveis

    <?php
    $a = 1;
    $b = 2;

    [$b, $a] = [$a, $b];

    echo $a, PHP_EOL;    // exibe 2
    echo $b, PHP_EOL;    // exibe 1
    ?>

> Nota:

> O operador de espalhamento (`...`) não é suportado em atribuições.

> Nota:

> Tentar acessar uma chave indefinida têm o mesmo efeito de acessar uma variável indefinida: um aviso `E_WARNING` (`E_NOTICE` anteriormente ao PHP 8.0.0) será emitido, e o resultado será `null`.

> Nota:

> A desconstrução de um valor escalar atribui `null` a todas as variáveis.

### Funções úteis

Há uma série de funções úteis para trabalhar com arrays. Veja a seção sobre funções para arrays.

> Nota:

> A função unset() permite apagar chaves de um array. Esteja avisado que o array não será reindexado. Se um comportamento como "remover e deslocar" é o desejado, o array poderá ser reindexado utilizando a função array_values().

> Exemplo #16 Eliminando elementos intermediários

>     <?php
>     $a = array( 1 => 'um', 2 => 'dois', 3 => 'três' );

>     /* irá produzir um array que pode ser definido como
>        $a = array( 1=>'um', 3=>'três');
>        e NÃO
>        $a = array( 1 => 'um', 2 => 'três');
>     */
>     unset($a[2]);
>     var_dump($a);

>     $b = array_values($a);
>     // Agora $b é o  array(0 => 'um', 1 =>'três')
>     var_dump($b);
>     ?>

A estrutura de controle `foreach` existe especificamente para lidar com arrays. Ele provê uma maneira fácil de percorrer um array.

### Array: o que fazer e o que não fazer

#### Porque `$foo[bar]` está errado?

Sempre utilize delimitadores em torno dos índices do array. Por exemplo, `$foo['bar']` está correto, enquanto que `$foo[bar]`, não está. Mas porque? É comum encontrar essa sintaxe em scripts antigos:

    <?php
    $foo[bar] = 'inimigo';
    echo $foo[bar];
    // etc
    ?>

Isto está errado, mas funciona. A razão é que este código possui uma constante indefinida (`bar`) em vez de uma string (`'bar'` - repare nas aspas simples). Isto funciona, porque o PHP converte automaticamente uma string base (uma string não delimitada que não corresponde a nenhum símbolo conhecido) em uma string que contém a string base. Por exemplo, se não existir uma constante definida com o nome `bar`, então o PHP irá substituí-la pela string `'bar'` e usá-la.

Aviso

O fallback que trata uma constante indefinida como uma string lança um erro do nível `E_NOTICE`. Isso foi descontinuado desde o PHP 7.2.0, e lança um erro do nível `E_WARNING`. A partir do PHP 8.0.0, esse fallback foi removido e agora lança uma exceção Error.

Isto não significa que deve-se sempre delimitar as chaves. Não delimite chaves que sejam constantes ou variáveis, porque isso impedirá o PHP de interpretá-las.

Exemplo #17 Delimitando chaves

    <?php
    error_reporting(E_ALL);
    ini_set('display_errors', true);
    ini_set('html_errors', false);

    // Arrays simples:
    $array = array(1, 2);
    $count = count($array);

    for ($i = 0; $i < $count; $i++) {
        echo "\nVerificando $i: \n";
        echo "Ruim: " . $array['$i'] . "\n";
        echo "Bom: " . $array[$i] . "\n";
        echo "Ruim: {$array['$i']}\n";
        echo "Bom: {$array[$i]}\n";
    }
    ?>

O exemplo acima produzirá:

    Verificando 0:
    Notice: Undefined index:  $i in /path/to/script.html on line 9
    Ruim:
    Bom: 1
    Notice: Undefined index:  $i in /path/to/script.html on line 11
    Ruim:
    Bom: 1

    Verificando 1:
    Notice: Undefined index:  $i in /path/to/script.html on line 9
    Ruim:
    Bom: 2
    Notice: Undefined index:  $i in /path/to/script.html on line 11
    Ruim:
    Bom: 2

Mais exemplos para demonstrar esse comportamento:

Exemplo #18 Mais exemplos

    <?php
    // Mostrando todos os erros
    error_reporting(E_ALL);

    $arr = array('fruta' => 'maçã', 'legume' => 'cenoura');

    // Correto
    echo $arr['fruta'], PHP_EOL;  // maçã
    echo $arr['legume'], PHP_EOL; // cenoura

    // Errado. Isto não funciona e lança um erro PHP por causa
    // de uma constante indefinida de nome 'fruta'
    //
    // Error: Undefined constant "fruta"
    try {
        echo $arr[fruta];
    } catch (Error $e) {
        echo get_class($e), ': ', $e->getMessage(), PHP_EOL;
    }

    // Esta instrução define uma constante para demonstrar o que acontece. O valor 'legume'
    // é atribuído a uma constante denominada 'fruta'
    define('fruta', 'legume');

    // Observe a diferença agora
    echo $arr['fruta'], PHP_EOL;  // maçã
    echo $arr[fruta], PHP_EOL;    // cenoura

    // O exemplo seguinte está ok, já que está dentro de uma string. Constantes não são
    // observadas dentro de strings e por isso nenhum erro acontece aqui
    echo "Olá $arr[fruta]", PHP_EOL;      // Olá maçã

    // Com uma exceção: chaves envolvendo arrays dentro de strings
    // ativam a checagem de constantes, como em
    echo "Olá {$arr[fruta]}", PHP_EOL;    // Olá cenoura
    echo "Olá {$arr['fruta']}", PHP_EOL;  // Olá maçã

    // Concatenação é uma outra opção
    echo "Olá " . $arr['fruta'], PHP_EOL; // Olá maçã
    ?>

    <?php
    // E isso não funciona, resultando em um erro de interpretação do tipo:
    // Parse error: parse error, expecting T_STRING' or T_VARIABLE' or T_NUM_STRING'
    // Isso também se aplica ao uso de superglobais em strings
    print "Olá $arr['fruta']";
    print "Olá $_GET['foo']";
    ?>

Como especificado na seção sobre sintaxe, o que estiver entre os colchetes ('`[`' e '`]`'), precisa ser uma expressão. Isso significa que códigos como estes funcionam:

    <?php
    echo $arr[algumafuncao($bar)];
    ?>

Isto é um exemplo de utilização de um valor de retorno de função como um índice de array. O PHP também aceita constantes:

    <?php
    $error_descriptions[E_ERROR] = "Um erro fatal ocorreu";
    $error_descriptions[E_WARNING] = "O PHP emitiu um alarme";
    $error_descriptions[E_NOTICE] = "Apenas um aviso informal";
    ?>

Observe que `E_ERROR` também é um identificador válido, assim como `bar` no primeiro exemplo. Mas no último exemplo seria, na verdade, o mesmo que escrever:

    <?php
    $error_descriptions[1] = "Um erro fatal ocorreu";
    $error_descriptions[2] = "O PHP emitiu um alarme";
    $error_descriptions[8] = "Apenas um aviso informal";
    ?>

porque `E_ERROR` é igual a `1`, e assim por diante.

##### Então porque isso é tão ruim?

Se em algum ponto do futuro, o time do PHP quiser acrescentar outra constante ou palavra chave, ou você mesmo introduzir outra constante na sua aplicação, você terá problemas. Por exemplo, já não se pode utilizar as palavras `empty` e `default` dessa maneira, desde que elas são palavras reservadas especiais.

> Nota: Para reforçar, dentro de uma string delimitada por aspas duplas, é válido não englobar o índice do array com aspas simples, então `"$foo[bar]"` é válido. Veja os exemplos anteriores para detalhes assim como a seção sobre interpretação de variáveis em strings.

### Convertendo para array

Para qualquer dos tipos: int, float, string, bool e resource, converter um valor para um array, resultará em um array com um único elemento com índice zero e valor escalar convertido. Em outras palavras, `(array) $scalarValue` é exatamente o mesmo que `array($scalarValue)`.

Se um object é convertido para um array, o resultado será um array em que seus elementos serão as propriedades do object. As chaves serão os nomes das propriedades com pequenas notáveis exceções: propriedades inteiras serão inacessíveis; variáveis privadas tem o nome da classe prefixando o nome da variável; variáveis protegidas tem um '*' prefixando o nome da variável. Esses valores prefixados têm um byte `NUL` em cada lado. Propriedades tipadas não inicializadas são ignoradas.

Exemplo #19 Convertendo para um array

    <?php

    class A {
        private $B;
        protected $C;
        public $D;
        function __construct()
        {
            $this->{1} = null;
        }
    }

    var_export((array) new A());
    ?>

O exemplo acima produzirá:

    array (
      '' . "\0" . 'A' . "\0" . 'B' => NULL,
      '' . "\0" . '*' . "\0" . 'C' => NULL,
      'D' => NULL,
      1 => NULL,
    )

Esses `NUL` podem ocasionar comportamentos inesperados:

Exemplo #20 Convertendo um objeto em um Array

    <?php

    class A {
        private $A; // Transformado na chave '\0A\0A'
    }

    class B extends A {
        private $A; // Transformado na chave '\0B\0A'
        public $AA; // Transformado na chave 'AA'
    }

    var_dump((array) new B());
    ?>

O exemplo acima produzirá:

    array(3) {
      ["BA"]=>
      NULL
      ["AA"]=>
      NULL
      ["AA"]=>
      NULL
    }

Acima aparecem duas chaves chamadas 'AA', embora uma delas é, na verdade, nomeada '\0A\0A'.

Converter um valor `null` para um array resultará em um array vazio.

### Comparando

É possível comparar arrays utilizando a função array_diff() e com a utilização dos operadores de array.

### Expansão de arrays

Um array prefixado com `...` será expandido no local desse operador. Somente arrays e objetos que implementem Traversable podem ser expandidos. A expansão de arrays com `...` está disponível desde o PHP 7.4.0. Ele também é chamado de operador de expansão.

É possível realizar a expansão várias vezes, e adicionar elementos antes ou depois do operador`...`:

Exemplo #21 Expansão de arrays

    <?php
    // Utilizando a sintaxe curta.
    // Também funciona com a sintax array().
    $arr1 = [1, 2, 3];
    $arr2 = [...$arr1]; // [1, 2, 3]
    $arr3 = [0, ...$arr1]; // [0, 1, 2, 3]
    $arr4 = [...$arr1, ...$arr2, 111]; // [1, 2, 3, 1, 2, 3, 111]
    $arr5 = [...$arr1, ...$arr1]; // [1, 2, 3, 1, 2, 3]

    function getArr() {
      return ['a', 'b'];
    }
    $arr6 = [...getArr(), 'c' => 'd']; // ['a', 'b', 'c' => 'd']

    var_dump($arr1, $arr2, $arr3, $arr4, $arr5, $arr6);
    ?>

Expandir um array com `...` segue a semântica da função array_merge(). Ou seja, chaves strings sobrescrevem valores antigo e chaves inteiros são renumerados:

Exemplo #22 Expansão de arrays com chaves duplicadas

    <?php
    // chave string
    $arr1 = ["a" => 1];
    $arr2 = ["a" => 2];
    $arr3 = ["a" => 0, ...$arr1, ...$arr2];
    var_dump($arr3); // ["a" => 2]

    // chave inteira
    $arr4 = [1, 2, 3];
    $arr5 = [4, 5, 6];
    $arr6 = [...$arr4, ...$arr5];
    var_dump($arr6); // [1, 2, 3, 4, 5, 6]
    // Que resulta em [0 => 1, 1 => 2, 2 => 3, 3 => 4, 4 => 5, 5 => 6]
    // pois as chaves inteiras anteriores não são preservadas.
    ?>

> Nota:

> Chaves que não sejam inteiros ou strings lançam um TypeError. Essas chaves podem ser geradas por um objeto Traversable.

> Nota:

> Anteriormente ao PHP 8.1, expansão de arrays com chave string não era suportado:

>     <?php

>     $arr1 = [1, 2, 3];
>     $arr2 = ['a' => 4];
>     $arr3 = [...$arr1, ...$arr2];
>     // Fatal error: Uncaught Error: Cannot unpack array with string keys in example.php:5

>     $arr4 = [1, 2, 3];
>     $arr5 = [4, 5];
>     $arr6 = [...$arr4, ...$arr5]; // works. [1, 2, 3, 4, 5]
>     ?>

### Exemplos

O tipo array do PHP é muito versátil. Temos aqui alguns exemplos:

Exemplo #23 Versatilidade do array

    <?php
    // Isso:
    $a = array( 'color' => 'red',
                'taste' => 'sweet',
                'shape' => 'round',
                'name'  => 'apple',
                4        // a chave será 0
              );

    $b = array('a', 'b', 'c');

    var_dump($a, $b);

    // ...é totalmente equivalente a isso:
    $a = array();
    $a['color'] = 'red';
    $a['taste'] = 'sweet';
    $a['shape'] = 'round';
    $a['name']  = 'apple';
    $a[]        = 4;        // a chave será 0

    $b = array();
    $b[] = 'a';
    $b[] = 'b';
    $b[] = 'c';

    // Após a execução do código acima, $ será o array
    // array('color' => 'red', 'taste' => 'sweet', 'shape' => 'round',
    // 'name' => 'apple', 0 => 4), e $b será o array
    // array(0 => 'a', 1 => 'b', 2 => 'c'), ou simplesmente array('a', 'b', 'c').

    var_dump($a, $b);
    ?>

Exemplo #24 Utilizando array()

    <?php
    // Array como (propriedade-)mapa
    $map = array( 'versao'     => 4,
                  'OS'         => 'Linux',
                  'lang'       => 'inglês',
                  'short_tags' => true
                );
    var_dump($map);

    // apenas chaves numéricas
    // isto é o mesmo que array(0 => 7, 1 => 8, ...)
    $array = array( 7,
                    8,
                    0,
                    156,
                    -10
                  );
    var_dump($array);

    $switching = array(         10, // chave = 0
                        5    =>  6,
                        3    =>  7,
                        'a'  =>  4,
                                11, // chave = 6 (o índice máximo era 5)
                        '8'  =>  2, // chave = 8 (inteiro!)
                        '02' => 77, // chave = '02'
                        0    => 12  // o valor 10 será sobrescrito por 12
                      );
    var_dump($switching);

    // array vazio
    $empty = array();
    var_dump($empty);
    ?>

Exemplo #25 Coleção

    <?php
    $cores = array('vermelho', 'azul', 'verde', 'amarelo');

    foreach ($cores as $cor) {
        echo "Você gosta de $cor?\n";
    }

    ?>

O exemplo acima produzirá:

    Você gosta de vermelho?
    Você gosta de azul?
    Você gosta de verde?
    Você gosta de amarelo?

É possível alterar diretamente os valores de um array passando-os como referência.

Exemplo #26 Alterando valores em um laço

    <?php
    $cores = array('vermelho', 'azul', 'verde', 'amarelo');

    foreach ($cores as &$cor) {
        $cor = mb_strtoupper($cor);
    }
    unset($cor); /* garante que as próximas alterações em
    $cor não modificam o último elemento do array */

    print_r($cores);
    ?>

O exemplo acima produzirá:

    Array
    (
        [0] => VERMELHO
        [1] => AZUL
        [2] => VERDE
        [3] => AMARELO
    )

Este exemplo cria um array na base 1.

Exemplo #27 Array baseado em 1

    <?php
    $primeiroquarto = array(1 => 'Janeiro', 'Fevereiro', 'Março');
    print_r($primeiroquarto);
    ?>

O exemplo acima produzirá:

    Array
    (
        [1] => Janeiro
        [2] => Fevereiro
        [3] => Março
    )

Exemplo #28 Preenchendo um array

    <?php
    // preenchendo um array com todos os itens de um diretório
    $handle = opendir('.');
    while (false !== ($file = readdir($handle))) {
        $files[] = $file;
    }
    closedir($handle);

    var_dump($files);
    ?>

arrays são ordenados. A ordem pode ser modificada utilizando várias funções de ordenação. Veja a seção de funções de arrays para mais informações. A função count() pode ser utilizada para contar o número de itens em um array.

Exemplo #29 Ordenando arrays

    <?php
    sort($files);
    print_r($files);
    ?>

Como o valor de um array pode ser qualquer coisa, isso significa que também poderá ser outro array. Isso habilita a criação de arrays recursivos e multidimensionais.

Exemplo #30 Arrays recursivos e multidimensionais

    <?php
    $fruits = array ( "frutas"  => array ( "a" => "laranja",
                                           "b" => "banana",
                                           "c" => "maçã"
                                         ),
                      "numeros" => array ( 1,
                                           2,
                                           3,
                                           4,
                                           5,
                                           6
                                         ),
                      "buracos" => array (      "primeiro",
                                           5 => "segundo",
                                                "terceiro",
                                         )
                    );
    var_dump($fruits);

    // Alguns exemplos de endereços dos valores do array acima
    echo $fruits["buracos"][5];   // imprime "segundo"
    echo $fruits["frutas"]["a"];  // imprime "laranja"
    unset($fruits["buracos"][0]); // remove  "primeiro"

    // Criando um novo array multidimensional
    $sucos["maca"]["verde"] = "bom";
    var_dump($juices);
    ?>

Atribuições de array sempre envolvem cópias de valores. Use o operador de referência para copiar um array por referência.

Exemplo #31 Copiando arrays

    <?php
    $arr1 = array(2, 3);
    $arr2 = $arr1;
    $arr2[] = 4; // $arr2 é modificado,
                 // $arr1 continua sendo apenas array(2, 3)

    $arr3 = &$arr1;
    $arr3[] = 4; // agora $arr1 e $arr3 são os mesmos

    var_dump($arr1, $arr2, $arr3);
    ?>

## Objetos

### Inicialização de objetos

Para criar um novo object, utilize a instrução `new` para instanciar uma classe:

Exemplo #1 Construção de objeto

    <?php
    class foo
    {
        function do_foo()
        {
            echo "Fazendo foo.";
        }
    }

    $bar = new foo;
    $bar->do_foo();
    ?>

Para uma discussão completa, veja o capítulo Classes e Objetos.

### Convertendo para objetos

Se um object é convertido para um object, ele não é modificado. Se um valor de qualquer outro tipo é convertido para um object, uma nova instância da classe interna stdClass é criada. Se o valor for `null`, a nova instância será vazia. Um array é convertido para um object com as propriedades nomeadas pelas chaves e os valores correspondentes, com exceção de chaves numéricas que ficarão inacessíveis a menos que sejam iteradas.

Exemplo #2 Convertendo para um objeto

    <?php
    $obj = (object) array('1' => 'foo');
    var_dump(isset($obj->{'1'})); // exibe 'bool(true)'

    // Descontinuado a partir do PHP 8.1
    var_dump(key($obj)); // exibe 'string(1) "1"'
    ?>

Para qualquer outro valor, uma propriedade chamada `scalar` conterá o valor.

Exemplo #3 Conversão com `(object)`

    <?php
    $obj = (object) 'ciao';
    echo $obj->scalar;  // exibe 'ciao'
    ?>

## Enumerações

(PHP 8 >= 8.1.0)

### Enumerações Básicas

Enumerações são uma camada de restrição sobre classes e constantes de classe, destinadas a fornecer uma maneira de definir um conjunto fechado de valores possíveis para um tipo.

    <?php
    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    function do_stuff(Suit $s)
    {
        // ...
    }

    do_stuff(Suit::Spades);
    ?>

Para uma discussão completa, consulte o capítulo sobre enumerações.

### Casting

Se um enum for convertido em um object, ele não será modificado. Se um enum for convertido em um array, será criado um array com uma única chave de `name` (para enumerações puras) ou um array com chaves `name` e `value` (para enumerações com backup). Todos os outros tipos de conversão resultarão em erro.

## Recursos

Um resource é uma variável especial, que mantém uma referência a um recurso externo. Recursos são criados e usados por funções especiais. Veja o apêndice para uma lista de todas essas funções e seus tipos resource correspondentes.

Veja também a função get_resource_type().

### Convertendo para recurso

Como as variáveis resource mantém manipuladores especiais para arquivos abertos, conexões de bancos de dados, canvas de imagens e coisas do tipo, converter para resource não faz sentido algum.

### Liberando recursos

Graças ao sistema de contagem de referência introduzido com a Engine da Zend, um resource sem referências é detectado automaticamente, e liberado pelo coletor de lixo. Por esta razão, é rara a necessidade de liberação de memória manualmente.

> Nota: Conexões persistentes de bancos são exceções à regra. Elas não são destruídas pelo coletor de lixo. Veja também a seção conexões persistentes para mais informações.

## Chamáveis

Um chamável é uma referência a uma função ou a um método que é passada a outra função como um argumento. Chamáveis são representados com a declaração de tipo callable.

    <?php
    function foo(callable $callback) {
        $callback();
    }
    ?>

Algumas funções aceitam funções como um parâmetro, por exemplo, array_map(), usort() ou preg_replace_callback().

### Criação de chamáveis

Um objeto chamável é um tipo que representa algo que pode ser invocado. Os objetos invocáveis ​​podem ser passados ​​como argumentos para funções ou métodos que esperam um parâmetro de função de retorno (callback) ou podem ser invocados diretamente. O tipo callable não pode ser usado como uma declaração de tipo para propriedades de classe. Em vez disso, use uma declaração de tipo Closure.

Chamáveis podem ser criados de diferentes formas:

- Objeto Closure
- string contendo o nome de uma função ou método
- array contendo um nome de classe ou um object no índice 0 e o nome do método no índice 1
- object implementando a método mágico __invoke()

Um objeto Closure pode ser criado usando-se a sintaxe de função anônima, de função seta, de chamável de primeira classe, ou com o médoto Closure::fromCallable().

> Nota: A sintaxe de chamável de primeira classe está disponível somente a partir do PHP 8.1.0.

Exemplo #1 Exemplo de função de retorno usando Closure

    <?php
    // Usando a sintaxe de função anônima
    $double1 = function ($a) {
        return $a * 2;
    };

    // Usando a sintaxe de chamável de primeira classe
    function double_function($a) {
        return $a * 2;
    }
    $double2 = double_function(...);

    // Usando a sintaxe de função seta
    $double3 = fn($a) => $a * 2;

    // Usando Closure::fromCallable
    $double4 = Closure::fromCallable('double_function');

    // Usando o closure como uma função de retorno aqui para
    // duplicar o tamanho de cada elemento no intervalo
    $new_numbers = array_map($double1, range(1, 5));
    print implode(' ', $new_numbers) . PHP_EOL;

    $new_numbers = array_map($double2, range(1, 5));
    print implode(' ', $new_numbers) . PHP_EOL;

    $new_numbers = array_map($double3, range(1, 5));
    print implode(' ', $new_numbers) . PHP_EOL;

    $new_numbers = array_map($double4, range(1, 5));
    print implode(' ', $new_numbers);

    ?>

Saída do exemplo acima no PHP 8.1:

    2 4 6 8 10
    2 4 6 8 10
    2 4 6 8 10
    2 4 6 8 10

Um chamável também pode ser uma string contendo o nome de uma função ou de um método estático. Qualquer função interna ou definida pelo usuário pode ser utilizada, com exceção dos construtores de linguagem como: array(), echo, empty(), eval(), isset(), list(), print ou unset().

Métodos estáticos também podem ser passados sem a instância de um object dessa classe criando um array com o nome da classe no índice 0 e o nome do método no índice 1 ou usando a sintaxe especial com operador de resolução de escopo `::` como em `'ClassName::methodName'`.

Um método de um object instanciado pode ser um chamável quando fornecido como um array com o object no índice 0 e o nome do método no índice 1.

A principal diferença entre um objeto Closure e o tipo callable é que um objeto Closure é independente de escopo e sempre pode ser invocado, enquanto um tipo 'callable' pode ser dependente de escopo e pode não ser invocado diretamente. Closure é a maneira preferida de criar objetos chamáveis.

> Nota: Embora os objetos Closure estejam vinculados ao escopo onde são criados, os objetos chamáveis ​​que referenciam métodos de classe como strings ou arrays são resolvidos no escopo onde são chamados. Para criar um objeto chamável a partir de um método privado ou protegido, que pode então ser invocado de fora do escopo da classe, use Closure::fromCallable() ou a sintaxe de chamável de primeira classe.

O PHP permite a criação de chamáveis que podem ser usados como argumento de função de retorno mas não podem ser chamadas diretamente. Essas são funções dependentes do contexto que fazem referência a um método de classe na hierarquia de herança de uma classe, por exemplo: `'parent::method'` ou `["static", "method"]`.

> Nota: A partir do PHP 8.2.0, chamáveis dependentes de contexto foram descontinuados. Remova a dependência de contexto substituindo `'parent::method'` por `parent::class . '::method'` ou use a sintaxe de chamável de primeira classe.

Exemplo #2 Invocando vários tipos de chamáveis com call_user_function()

    <?php

    // Exemplo de função de retorno
    function minha_funcao_retorno() {
        echo 'olá mundo!', PHP_EOL;
    }

    // Exemplo de método de retorno
    class MinhaClasse {
        static function meuMetodoRetorno() {
            echo 'Olá Mundo!', PHP_EOL;
        }
    }

    // Tipo 1: Função de Retorno Simples
    call_user_func('minha_funcao_retorno');

    // Tipo 2: Chamada a métodos estáticos
    call_user_func(['MinhaClasse', 'meuMetodoRetorno']);

    // Tipo 3: Chamada a métodos de objetos
    $obj = new MinhaClasse();
    call_user_func([$obj, 'meuMetodoRetorno']);

    // Tipo 4: Chamada a métodos estáticos
    call_user_func('MinhaClasse::meuMetodoRetorno');

    // Tipo 5: Chamada a métodos estáticos usando a palavra-chave ::class
    call_user_func([MyClass::class, 'myCallbackMethod']);

    // Type 6: Relative static class method call
    class A {
        public static function quem() {
            echo "A\n", PHP_EOL;
        }
    }

    class B extends A {
        public static function quem() {
            echo "B\n", PHP_EOL;
        }
    }

    call_user_func(['B', 'parent::quem']); // descontinuado a partir do PHP 8.2.0

    // Type 7: Objetos que implementam __invoke podem ser utilizados como chamáveis
    class C {
        public function __invoke($nome) {
            echo 'Olá ', $nome;
        }
    }

    $c = new C();
    call_user_func($c, 'PHP!');
    ?>

O exemplo acima produzirá:

    olá mundo!
    Olá Mundo!
    Olá Mundo!
    Olá Mundo!
    Olá Mundo!

    Deprecated: Callables of the form ["B", "parent::who"] are deprecated in script on line 41
    A
    Olá, PHP!

> Nota: Callbacks registrados com funções como call_user_func() e call_user_func_array() não serão chamados se houver uma exceção não capturada que foi lançada em um callback anterior.

## Misto

O tipo mixed aceita todos os valores. É equivalente ao tipo de união `object|resource|array|string|float|int|bool|null`. Disponível a partir do PHP 8.0.0.

mixed é, na linguagem da teoria dos tipos, o tipo universal. O que significa que todos os outros tipos são um subtipo dele.

## Void

void é uma declaração de tipo de retorno indicando que a função não retorna um valor, mas a função ainda pode terminar. Portanto, não pode fazer parte de uma declaração de tipo de união. Disponível a partir do PHP 7.1.0.

> Nota: Mesmo que uma função tenha um tipo de retorno void, ela ainda retornará um valor, esse valor é sempre `null`.

### Descartando um valor com `(void)`

A sintaxe `(void)` pode ser usada para descartar explicitamente o resultado de uma expressão. Isso é útil para indicar que ignorar um valor de retorno é intencional, especialmente ao chamar uma função ou método marcado com o atributo NoDiscard.

Diferentemente de outras conversões, `(void)` não converte o valor para outro tipo e não produz um valor. É uma instrução e não pode ser usada como parte de uma expressão.

Exemplo #1 Descartando um valor de retorno

    <?php
    #[\NoDiscard]
    function process(): bool {
        return true;
    }

    (void) process(); // Descarta explicitamente o valor de retorno
    ?>

## Never

never é um tipo de retorno que indica que a função não termina. Isso significa que a função chama exit(), lança uma exceção ou é um loop infinito. Portanto, não pode fazer parte de uma declaração de tipo de união. Disponível a partir do PHP 8.1.0.

never é, na linguagem da teoria dos tipos, o tipo inferior. O que significa que é o subtipo de todos os outros tipos e pode substituir qualquer outro tipo de retorno durante a herança.

## Tipos de classes relativas

Essas declarações de tipos só podem ser usadas dentro de classes.

### self

O valor deve ser uma `instanceof` da mesma classe daquela em que a declaração de tipo é usada.

### parent

O valor deve ser uma `instanceof` de um pai da classe na qual a declaração de tipo é usada.

### static

static é um tipo somente de retorno que requer que o valor retornado seja uma `instanceof` da mesma classe em que o método é chamado. Disponível a partir do PHP 8.0.0.

## Tipos únicos

Tipos únicos são aqueles que permitem apenas um valor. O PHP tem suporte para dois tipos únicos: false a partir do PHP 8.0.0, e true a partir do PHP 8.2.0.

Aviso

Antes do PHP 8.2.0 o tipo false só podia ser usado como parte de um tipo união.

> Nota: Não é possível definir tipos únicos customizados. Considere usar enumerações como alternativa.

## Iterável

Iterable é um sinônimo de tipo integrado em tempo de compilação para `array|Traversable`. Desde sua introdução no PHP 7.1.0 e antes do PHP 8.2.0, iterable era um pseudotipo integrado que atuava como o sinônimo de tipo mencionado anteriormente e podia ser usado como uma declaração de tipo. Um tipo iterável pode ser usado em `foreach` e com yield from de dentro de um gerador.

> Nota:

> As funções que declaram iterável como um tipo de retorno também podem ser geradoras.

> Exemplo #1 Exemplo de tipo de retorno do gerador iterável

>     <?php

>     function gen(): iterable {
>         yield 1;
>         yield 2;
>         yield 3;
>     }

>     foreach(gen() as $value) {
>         echo $value, "\n";
>     }
>     ?>

## Declarações de tipo

As declarações de tipo podem ser adicionadas a argumentos de função, valores de retorno, a partir do PHP 7.4.0, propriedades de classe e, a partir do PHP 8.3.0, constantes de classe. Elas garantem que o valor seja do tipo especificado no momento da chamada, caso contrário, um TypeError é lançado.

Cada tipo que o PHP suporta, com exceção de resource, pode ser usado dentro de uma declaração de tipo de usuário. Esta página contém um changelog de disponibilidade dos diferentes tipos e documentação sobre o uso deles em declarações de tipo.

> Nota:

> Quando uma classe implementa um método de interface ou reimplementa um método já definido por uma classe pai, ela deve ser compatível com a definição acima. Um método é compatível se seguir as regras de variância.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Suporte à constantes em classes, interfaces, traits e enums foi adicionado.
8.2.0 | O suporte para tipos DNF foi adicionado.
8.2.0 | O suporte para o tipo literal true foi adicionado.
8.2.0 | Os tipos null e false agora podem ser usados de forma independente.
8.1.0 | O suporte para tipos de interseção foi adicionado.
8.1.0 | Retornar por referência de uma função void agora foi descontinuado.
8.1.0 | O suporte para o tipo somente retorno never foi adicionado.
8.0.0 | O suporte para mixed foi adicionado.
8.0.0 | O suporte para o tipo de retorno apenas static foi adicionado.
8.0.0 | O suporte para tipos de união foi adicionado.
7.4.0 | Suporte para propriedades tipadas foi adicionado.
7.2.0 | Suporte para object foi adicionado.
7.1.0 | Suporte para iterable foi adicionado.
7.1.0 | Suporte para void foi adicionado.
7.1.0 | O suporte para tipos anuláveis foi adicionado.

### Notas de uso em tipos atômicos

Os tipos atômicos têm um comportamento direto com algumas ressalvas menores que são descritas nesta seção.

#### Tipos escalares

Aviso

Aliases de nome para tipos escalares (bool, int, float, string) não são suportados. Em vez disso, eles são tratados como nomes de classe ou interface. Por exemplo, usar `boolean` como uma declaração de tipo exigirá que o valor seja uma `instanceof` da classe ou interface `boolean`, em vez do tipo bool:

    <?php
        function test(boolean $param) {}
        test(true);
    ?>

Saída do exemplo acima no PHP 8:

    Warning: "boolean" will be interpreted as a class name. Did you mean "bool"? Write "\boolean" to suppress this warning in /in/9YrUX on line 2

    Fatal error: Uncaught TypeError: test(): Argument #1 ($param) must be of type boolean, bool given, called in - on line 3 and defined in -:2
    Stack trace:
    #0 -(3): test(true)
    #1 {main}
      thrown in - on line 2

#### void

> Nota:

> Retornar por referência de uma função void foi descontinuado a partir do PHP 8.1.0, porque tal função é contraditória. Anteriormente, ele já emitia o seguinte `E_NOTICE` quando chamado: Only variable references should be returned by reference.

>     <?php
>     function &test(): void {}
>     ?>

#### Tipos que podem ser chamados

Este tipo não pode ser usado como uma declaração de tipo de propriedade de classe.

> Nota: Não é possível especificar a assinatura da função.

#### Declarações de tipo em parâmetros de passagem por referência

Se um parâmetro de passagem por referência tiver uma declaração de tipo, o tipo da variável é somente verificado na entrada da função, no início da chamada, mas não quando a função retorna. Isso significa que uma função pode alterar o tipo de referência de variável.

Exemplo #1 Parâmetros de passagem por referência digitados

    <?php
    function array_baz(array &$param)
    {
        $param = 1;
    }
    $var = [];
    array_baz($var);
    var_dump($var);
    array_baz($var);
    ?>

O exemplo acima produzirá algo semelhante a:

    int(1)

    Fatal error: Uncaught TypeError: array_baz(): Argument #1 ($param) must be of type array, int given, called in - on line 9 and defined in -:2
    Stack trace:
    #0 -(9): array_baz(1)
    #1 {main}
      thrown in - on line 2

### Notas de Uso de Tipos Compostos

As declarações de tipo composto estão sujeitas a algumas restrições e realizarão uma verificação de redundância no tempo de compilação para evitar erros simples.

Cuidado

Antes do PHP 8.2.0 e da introdução dos tipos DNF, não era possível combinar tipos de interseção com tipos de união.

#### União de tipos

Aviso

Não é possível combinar os dois tipos únicos false e true juntos em um tipo de união. Em vez disso, use bool.

Cuidado

Antes do PHP 8.2.0, como false e null não podiam ser usados como tipos autônomos, um tipo de união composto apenas por esses tipos não era permitido. Isso inclui os seguintes tipos: false, `false|null`, e `?false`.

##### Açúcar sintático do tipo anulável

Uma única declaração de tipo base pode ser marcada como anulável prefixando o tipo com um ponto de interrogação (`?`). Assim, `?T` e `T|null` são idênticos.

> Nota: Esta sintaxe é suportada a partir do PHP 7.1.0, e é anterior ao suporte generalizado de tipos de união.

> Nota:

> Também é possível obter argumentos anuláveis tornando `null` o valor padrão. Isso não é recomendado, pois se o valor padrão for alterado em uma classe filha, uma violação de compatibilidade de tipo será gerada, pois o tipo null precisará ser adicionado à declaração de tipo. Este comportamento também foi descontinuado desde o PHP 8.4.

> Exemplo #2 Maneira antiga de tornar os argumentos anuláveis

>     <?php
>     class C {}

>     function f(C $c = null) {
>         var_dump($c);
>     }

>     f(new C);
>     f(null);
>     ?>

> O exemplo acima produzirá:

>     object(C)#1 (0) {
>     }
>     NULL

#### Tipos duplicados e redundantes

Para capturar bugs simples em declarações de tipo composto, tipos redundantes que podem ser detectados sem executar o carregamento de classe resultarão em um erro de tempo de compilação. Isso inclui:

- Cada tipo resolvido por nome pode ocorrer apenas uma vez. Tipos como `int|string|INT` ou `Countable&Traversable&COUNTABLE` resultam em erro.
- O uso de mixed ou never resulta em um erro.
- Para tipos de união:
  - Se bool for usado, false ou true não pode ser usado adicionalmente.
  - Se object for usado, os tipos de classe não podem ser usados adicionalmente.
  - Se iterable for usado, array e Traversable não podem ser usados adicionalmente.
- Para interseção de tipos:
  - Usar um tipo que não é um tipo de classe resulta em erro.
  - O uso de self, parent ou static resulta em erro.
- Para tipos DNF:
  - Se um tipo mais genérico for usado, o mais restritivo será redundante.
  - Usando dois tipos de interseção idênticos.

> Nota: Isso não garante que o tipo seja “mínimo”, porque isso exigiria o carregamento de todos os tipos de classe usados.

Por exemplo, se `A` e `B` são aliases de classe, `A|B` continua sendo um tipo de união legal, mesmo que possa ser reduzido a `A` ou `B`. Da mesma forma, se a classe `B extends A {}`, `A|B` também é um tipo de união legal, embora pudesse ser reduzida a apenas `A`.

    <?php
    function foo(): int|INT {} // Proibido
    function foo(): bool|false {} // Proibido
    function foo(): int&Traversable {} // Proibido
    function foo(): self&Traversable {} // Proibido

    use A as B;
    function foo(): A|B {} // Não permitido ("use" faz parte da resolução de nomes)
    function foo(): A&B {} // Não permitido ("use" faz parte da resolução de nomes)

    class_alias('X', 'Y');
    function foo(): X|Y {} // Permitido (a redundância só é conhecida em tempo de execução)
    function foo(): X&Y {} // Permitido (a redundância só é conhecida em tempo de execução)
    ?>

### Exemplos

Exemplo #3 Declaração de tipo de classe básica

    <?php
    class C {}
    class D extends C {}

    // Isso não estende C.
    class E {}

    function f(C $c) {
        echo get_class($c)."\n";
    }

    f(new C);
    f(new D);
    f(new E);
    ?>

Saída do exemplo acima no PHP 8:

    C
    D

    Fatal error: Uncaught TypeError: f(): Argument #1 ($c) must be of type C, E given, called in /in/gLonb on line 14 and defined in /in/gLonb:8
    Stack trace:
    #0 -(14): f(Object(E))
    #1 {main}
      thrown in - on line 8

Exemplo #4 Declaração de tipo de interface básica

    <?php
    interface I { public function f(); }
    class C implements I { public function f() {} }

    // Isso não implementa I.
    class E {}

    function f(I $i) {
        echo get_class($i)."\n";
    }

    f(new C);
    f(new E);
    ?>

Saída do exemplo acima no PHP 8:

    C

    Fatal error: Uncaught TypeError: f(): Argument #1 ($i) must be of type I, E given, called in - on line 13 and defined in -:8
    Stack trace:
    #0 -(13): f(Object(E))
    #1 {main}
      thrown in - on line 8

Exemplo #5 Declaração de tipo de retorno básico

    <?php
    function sum($a, $b): float {
        return $a + $b;
    }

    // Observe que um float será retornado.
    var_dump(sum(1, 2));
    ?>

O exemplo acima produzirá:

    float(3)

Exemplo #6 Retornando um objeto

    <?php
    class C {}

    function getC(): C {
        return new C;
    }

    var_dump(getC());
    ?>

O exemplo acima produzirá:

    object(C)#1 (0) {
    }

Exemplo #7 Declaração de tipo de argumento anulável

    <?php
    class C {}

    function f(?C $c) {
        var_dump($c);
    }

    f(new C);
    f(null);
    ?>

O exemplo acima produzirá:

    object(C)#1 (0) {
    }
    NULL

Exemplo #8 Declaração de tipo de retorno anulável

    <?php
    function get_item(): ?string {
        if (isset($_GET['item'])) {
            return $_GET['item'];
        } else {
            return null;
        }
    }
    ?>

Exemplo #9 Declaração de tipo de propriedade

    <?php
    class User {
        public static string $foo = 'foo';

        public int $id;
        public string $username;

        public function __construct(int $id, string $username) {
            $this->id = $id;
            $this->username = $username;
        }
    }
    ?>

### Tipagem estrita

Por padrão, o PHP forçará valores do tipo errado na declaração de tipo escalar esperada, se possível. Por exemplo, uma função que recebe um int para um parâmetro que espera uma string obterá uma variável do tipo string.

É possível ativar o modo estrito por arquivo. No modo estrito, apenas um valor correspondente exatamente à declaração do tipo será aceito, caso contrário, um TypeError será lançado. A única exceção a essa regra é que um valor int passará por uma declaração do tipo float.

Aviso

Chamadas de função dentro de funções internas não serão afetadas pela declaração `strict_types`.

Para habilitar o modo estrito, a `declare` é usada com a declaração `strict_types`:

> Nota:

> A digitação estrita se aplica a chamadas de função feitas de dentro do arquivo com tipagem estrita habilitada, não para as funções declaradas dentro desse arquivo. Se um arquivo sem tipagem estrita habilitada fizer uma chamada para uma função que foi definida em um arquivo com tipagem estrita, a preferência do chamador (tipagem coercitiva) será respeitada e o valor será convertido.

> Nota:

> A tipagem estrita é definida apenas para declarações de tipo escalar.

Exemplo #10 Tipagem estrita para valores de argumentos

    <?php
    declare(strict_types=1);

    function sum(int $a, int $b) {
        return $a + $b;
    }

    var_dump(sum(1, 2));
    var_dump(sum(1.5, 2.5));
    ?>

Saída do exemplo acima no PHP 8:

    int(3)

    Fatal error: Uncaught TypeError: sum(): Argument #1 ($a) must be of type int, float given, called in - on line 9 and defined in -:4
    Stack trace:
    #0 -(9): sum(1.5, 2.5)
    #1 {main}
      thrown in - on line 4

Exemplo #11 Tipagem coercitiva para valores de argumento

    <?php
    function sum(int $a, int $b) {
        return $a + $b;
    }

    var_dump(sum(1, 2));

    // Estes serão convertidos em números inteiros: observe a saída abaixo!
    var_dump(sum(1.5, 2.5));
    ?>

O exemplo acima produzirá:

    int(3)
    int(3)

Exemplo #12 Tipagem estrita para valores de retorno

    <?php
    declare(strict_types=1);

    function sum($a, $b): int {
        return $a + $b;
    }

    var_dump(sum(1, 2));
    var_dump(sum(1, 2.5));
    ?>

O exemplo acima produzirá:

    int(3)

    Fatal error: Uncaught TypeError: sum(): Return value must be of type int, float returned in -:5
    Stack trace:
    #0 -(9): sum(1, 2.5)
    #1 {main}
      thrown in - on line 5

## Conversão automática de tipos

O PHP não requer a tipagem explícita em declarações de variáveis. Nesse caso, o tipo de uma variável é determinado pelo valor armazenado. Ou seja, se uma string é armazenada numa variável $var, então $var terá o tipo string. Se após isso um valor int for armazenado em $var, ele será do tipo int.

O PHP pode tentar converter o tipo de um valor em outro, automaticamente, em alguns contextos. Esses contextos são:

- Numérico
- String
- Lógico
- Inteiro e string
- Comparação
- Função

> Nota: Quando um valor precisa ser interpretado como um tipo diferente, o valor em si não se altera, apenas uma "cópia" é convertido.

Para forçar uma variável ser avaliada como um certo tipo, veja a seção Conversão de tipo. Se desejar mudar o tipo de uma variável, veja a função settype().

### Contexto numérico

Esse contexto é utilizando em operadores aritméticos.

Esse contexto ocorre se um dos operandos é um float (e não interpretável como int), se ambos os operandos são interpretados como float, ou se o resultado é um float. Se não, se os operandos são interpretados como int, ou o resultado é um int. A partir do 8.0.0, se um dos operandos não pode ser reinterpretado, um erro do tipo TypeError é lançado.

### Contextos string

Esse contexto ocorre ao se utilizar echo, print, interpolação de strings, o operador de concatenação.

Nesse contexto, o valor será interpretado como string. Se o valor não puder ser interpretado, então TypeError é lançado. Anteriormente ao 7.4.0, um alerta `E_RECOVERABLE_ERROR` era emitido.

### Contextos lógicos

Este contexto ocorre em instruções condicionais, no uso do operador ternário, ou em uma operação lógica.

Nesse contexto, o valor será interpretado como bool.

### Contextos inteiros e string

Este contexto ocorre quando utilizando operadores bitwise.

Este contexto ocorre se todos os operandos são do tipo string, ou o valor retornado é string. Se não, os operados são interpretados como int, ou o resultado é um int. A partir do PHP 8.0.0, se um dos operandos não puder ser reinterpretado, então TypeError é lançado.

### Contextos de comparação

Este contexto ocorre quando utilizando operadores de comparação.

As conversões de tipo que ocorrem nesse contexto são explicados na tabela de sobre comparação entre vários tipos, explicadas aqui.

### Contextos de função

Este contexto ocorre quando um valor é um parâmetro tipado, ou quando uma propriedade ou valor retornado de uma função declara um tipo.

Nesse contexto, o valor precisa do tipo informado. Duas alternativas existem. A primeira: se o valor é do tipo int e o tipo declarado é float, então o inteiro é convertido num número de ponto flutuante. A segunda alternativa: se o tipo declarado é um escalar, e o valor é conversível no tipo escalar, juntamente com o modo de conversão coercivo no estado ativo (o padrão), o valor pode ser convertido no valor escalar. Veja abaixo uma descrição detalhada desse comportamento.

Aviso

Funções internas convertem automaticamente `null` para tipos escalares, mas esse comportamento foi DESCONTINUADO desde o PHP 8.1.0.

#### Coerção de tipos com tipos declarados

- Declaração bool: o valor é convertido para bool.
- Declaração int: o valor é convertido para int quando a conversão for bem definida. Por exemplo, quando uma string é numérica.
- Declaração float: o valor é convertido para float quando a conversão for bem definida. Por exemplo, quando uma string é numérica.
- Declaração string: o valor é convertido para string.

#### Conversão de tipos em tipos union

Quando `strict_types` está desativado, declarações de tipos escalares estão sujeitas a conversões implícitas e limitadas. Se o tipo exato do valor não é parte da união, então o tipo final da conversão é escolhido na seguinte ordem de preferência:

1. int
2. float
3. string
4. bool

Se o tipo existe na união e o valor puder ser convertido pela mesma semântica do PHP, então esse tipo é escolhido. Senão, um tipo seguinte é tentado.
Cuidado

Existe uma exceção, no caso do valor ser uma string, e ambos int e float serem partes da união, o tipo preferido será determinado pela semântica de strings numéricas. Por exemplo, para `"42"` o tipo int é escolhido, enquanto que para `"42.0"` o tipo escolhido é float.

> Nota:

> Tipos que não fazem parte da lista acima não são elegíveis para destinos da conversão implícita. Em particular, não existem conversões implícitas para os tipos null, false e true.

Exemplo #1 Exemplo de tipos que podem ser convertidos em tipos union

    <?php
    // int|string
    42    --> 42          // tipo exato
    "42"  --> "42"        // tipo exato
    new ObjectWithToString --> "Resultado de __toString()"
                          // e objero não compatível com int, padrão para string
    42.0  --> 42          // float compatível com int
    42.1  --> 42          // float compatível com int
    1e100 --> "1.0E+100"  // float muito grande para int, padrão para string
    INF   --> "INF"       // float muito grande para int, padrão para string
    true  --> 1           // bool compatível com int
    []    --> TypeError   // array não é compatível com int ou string

    // int|float|bool
    "45"    --> 45        // string numérica int
    "45.0"  --> 45.0      // string numérica float

    "45X"   --> true      // string não numérica, padrão para bool
    ""      --> false     // string não numérica, padrão para bool
    "X"     --> true      // string não numérica, padrão para bool
    []      --> TypeError // array não é compatível com int, float ou bool
    ?>

### Conversão explícita

Converte o valor do tipo para o tipo escolhido através da escrita do tipo entre parênteses, antes do valor a ser convertido.

Exemplo #2 Conversão de tipo

    <?php
    $foo = 10;           // $foo é um inteiro
    $bar = (bool) $foo;  // $bar é um booleano

    var_dump($bar);
    ?>

As conversões previstas são:

- `(int)` - converte para int
- `(bool)` - converte para bool
- `(float)` - converte para float
- `(string)` - converte para string
- `(array)` - converte para array
- `(object)` - converte para object
- `(unset)` - converte para NULL

A conversão `(void)` também está disponível a partir do PHP 8.5.0, mas não é uma conversão de valor. Ela é usada como uma instrução para descartar explicitamente o resultado de uma expressão.

Aviso

`(integer)` é um sinônimo de `(int)`. `(boolean)` é um sinônimo de `(bool)`. `(binary)` é um sinônimo de `(string)`. `(double)` e `(real)` são sinônimos de `(float)`. Essas conversões alternativas não usam o nome canônico de tipo e foram descontinuadas a partir do PHP 8.5.0.

Aviso

A conversão `(real)` foi descontinuada a partir do PHP 7.4.0 e removida a partir do PHP 8.0.0.

Aviso

A conversão `(unset)` foi descontinuada a partir do PHP 7.2.0. Observe que a conversão `(unset)` tem o mesmo efeito que informar o valor NULL para a variável ou chamada de função. A conversão `(unset)` foi removida no PHP 8.0.0.

Cuidado

A conversão `(binary)` e o prefixo `b` ainda existem para compatibilidade. Atualmente `(binary)` e `(string)` são idênticos, no entanto isso pode mudar e não deve ser considerado estável.

> Nota:

> Espaços são ignorados dentro dos parênteses de uma conversão. Portanto, as linhas seguintes são equivalentes:

>     <?php
>     $foo = (int) $bar;
>     $foo = ( int ) $bar;
>     ?>

Convertendo string e variáveis para strings binárias:

    <?php
    $binary = (binary) $string;
    $binary = b"binary string";
    ?>

Em vez de converter uma variável para string, é possível delimitar a variável entre aspas.

Exemplo #3 Diferentes mecanismos de conversão

    <?php
    $foo = 10;            // $foo é int
    $str = "$foo";        // $str é string
    $fst = (string) $foo; // $fst também é string

    // Isto exibe "são iguais"
    if ($fst === $str) {
        echo "são iguais", PHP_EOL;
    }
    ?>

Não é tão óbvio o que acontece ao converter entre certos tipos. Para mais informações, veja as seções:

- Convertendo para boolean
- Convertendo para integer
- Convertendo para float
- Convertendo para string
- Convertendo para array
- Convertendo para object
- Convertendo para resource
- Convertendo para NULL
- Descartando um valor com `(void)`
- Tabela de conversão de tipos

> Nota: O PHP suporta a indexação de string utilizando a mesma sintaxe de arrays, de forma que o exemplo seguinte é válido em todas as versões do PHP:

> Exemplo #4 Usando índice de array com uma string

>     <?php
>     $a    = 'car'; // $a é uma string
>     $a[0] = 'b';   // $a ainda é uma string
>     echo $a;       // bar
>     ?>

> Veja a seção sobre Acesso a caracteres da string para mais informações.

# Variáveis

## Índice

- Básico
- Variáveis Predefinidas
- Escopo de variáveis
- Variáveis variáveis
- Variáveis de fontes externas

## Básico

As variáveis no PHP são representadas por um cifrão ($) seguido pelo nome da variável. Os nomes de variável são sensíveis a maiúsculas e minúsculas.

Um nome válido de variável inicia com uma letra (`A-Z`, `a-z`, ou os bytes de 128 a 255) ou sublinhado, seguido de qualquer número de letras, números ou sublinhados. Em uma expressão regular, poderia ser representado assim: `^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$`

> Nota: O PHP não suporta nomes de variáveis em Unicode, porém, algumas codificações de caracteres (tal como UTF-8) codificam os caracteres de uma forma que todos os bytes de um caractere multibyte fiquem dentro da faixa permitida, fazendo com que o nome da variável seja válido.

> Nota: `$this` é uma variável especial que não pode ser atribuída. Antes do PHP 7.1.0, atribuição indireta (por exemplo, usando variáveis variáveis) era possível.

Dica

Veja também o Guia de nomenclatura em espaço de usuário.

Exemplo #1 Nomes de variáveis válidos

    <?php
    $var = 'Bob';
    $Var = 'Joe';
    echo "$var, $Var";      // exibe "Bob, Joe"

    $_4site = 'not yet';    // válido; começa com um sublinhado
    $täyte = 'mansikka';    // válido; 'ä' é um caracter ASCII (estendido) 228

Exemplo #2 Nomes de variáveis inválidos

    <?php
    $4site = 'not yet';     // inválido; começa com um número

O PHP aceita uma sequência de quaisquer bytes como um nome de variável. Nomes de variáveis que não seguem as regras de nomenclatura mencionadas acima só podem ser acessadas dinamicamente no momento da execução. Consulte a seção sobre variáveis variáveis para informação sobre como acessá-las.

Exemplo #3 Acessando nomes obscuros de variáveis

    <?php
    ${'invalid-name'} = 'bar';
    $name = 'invalid-name';
    echo ${'invalid-name'}, " ", $$name;

O exemplo acima produzirá:

    bar bar

Por padrão, as variáveis são sempre atribuídas por valor. Isto significa que ao atribuir uma expressão a uma variável, o valor da expressão original é copiado integralmente para a variável de destino. Isto significa também que, após atribuir o valor de uma variável a outra, a alteração de uma destas variáveis não afetará a outra. Para maiores informações sobre este tipo de atribuição, veja o capítulo em Expressões.

O PHP também oferece um outro meio de atribuir valores a variáveis: atribuição por referência. Isto significa que a nova variável simplesmente referencia (em outras palavras, "torna-se um apelido para" ou "aponta para") a variável original. Alterações na nova variável afetam a original, e vice-versa.

Para atribuir por referência, simplesmente adicione um e-comercial (&) na frente do nome da variável que estiver sendo atribuída (variável de origem). Por exemplo, o trecho de código abaixo exibe '`My name is Bob`' duas vezes:

    <?php
    $foo = 'Bob';              // Atribui o valor 'Bob' a variável $foo
    $bar = &$foo;              // Referencia $foo através de $bar.
    $bar = "My name is $bar";  // Altera $bar...
    echo $bar . PHP_EOL;
    echo $foo . PHP_EOL;       // $foo é alterada também.

Uma observação importante a se fazer, é que somente variáveis podem ser atribuídas por referência.

    <?php
    $original = 25;
    $ref1 = &$original;      // Esta atribuição é válida.
    $ref2 = &(24 * 7);       // Inválida; referencia uma expressão sem nome.

    <?php
    // Observe a falta de & indicando uma referência retornada na declaração da função,
    // ou seja, a função não retorna uma referência, portanto o resultado não pode ser atribuído por referência
    function test()
    {
       $original = 25;
       return $original;
    }

    // Nota: Um aviso é emitido mas o valor de não-referência é atribuído
    $result1 = &test();   // Inválido porque test() não retorna uma variável por referência.
    var_dump($result1);

    // A definição desta função mostra que ela retorna uma referência mas não retorna uma variável
    function &test2()
    {
        return 26;        // Inválido porque o valor de retorno não é uma referência a uma variável.
    }

    // Nota: o valor de não-referência é atribuído
    $result2 = &test2();
    var_dump($result2);

Não é necessário declarar variáveis no PHP, contudo é uma ótima prática. Acessar uma variável indefinida resultará em um `E_WARNING` (antes do PHP 8.0.0, `E_NOTICE`). Uma variável indefinida tem um valor padrão de `null`. O construtor de linguagem isset() pode ser usado para detectar se uma variável já foi inicializada.

Exemplo #4 Valor padrão de uma variável não inicializada

    <?php
    // Variável não definida E não referenciada (sem contexto de uso);
    var_dump($unset_var);

O exemplo acima produzirá:

    Warning: Undefined variable $unset_var in ...
    NULL

O PHP permite autovivificação de array (criação automática de novos arrays) a partir de uma variável indefinida. Anexar um elemento a uma variável indefinida criará um novo array e não gerará um alerta.

Exemplo #5 Autovivificação de um array a partir de uma variável indefinida

    <?php
    $unset_array[] = 'value'; // Não gera um alerta.
    var_dump($unset_array);

Aviso

Depender do valor padrão de uma variável não inicializada é problemático ao incluir um arquivo em outro que usa o mesmo nome de variável.

Uma variável pode ser destruída usando o construtor de linguagem unset().

Para obter informações sobre funções relacionadas a variáveis, consulte a referência de funções variáveis.

## Variáveis Predefinidas

O PHP fornece um número de variáveis predefinidas. O PHP também fornece um conjunto adicional de arrays predefinidos contendo as variáveis do servidor web (se aplicável), as variáveis de ambiente e as entradas do usuário. Esses estão automaticamente disponíveis em qualquer escopo. Por essa razão, também são conhecidos como "superglobais" (não há um mecanismo no PHP para superglobais definidos pelo usuário). Consulte a lista de superglobais para mais detalhes.

> Nota: Variáveis variáveis

> Superglobais não podem ser utilizadas como variáveis variáveis dentro de funções ou métodos de classe.

Se determinadas variáveis não estiverem definidas na diretiva variables_order, seus arrays predefinidos também estarão vazios.

## Escopo de variáveis

O escopo de uma variável é o contexto onde ela está definida. O PHP tem um escopo de função e um escopo global. Qualquer variável definida fora de uma função está limitada ao escopo global. Quando um arquivo é incluído, o código que ele contém herda o escopo da variável da linha na qual a inclusão ocorre.

Exemplo #1 Exemplo de escopo global de variável

    <?php
    $a = 1;
    include 'b.inc'; // Variável $a estará disponível dentro de b.inc

Qualquer variável criada dentro de uma função nomeada ou de uma função anônima é limitada ao escopo do corpo da função. Entretanto, funções de seta vinculam variáveis ​​do escopo pai para disponibilizá-las dentro do corpo. Se uma inclusão de arquivo ocorrer dentro de uma função dentro do arquivo chamador, as variáveis ​​contidas no arquivo chamado estarão disponíveis como se tivessem sido definidas dentro da função chamadora.

Exemplo #2 Exemplo de escopo local de variável

    <?php
    $a = 1; // escopo global

    function test()
    {
        var_dump($a); // Variável $a é indefinida já que refere-se a uma versão local de $a
    }

    test();

O exemplo acima irá gerar um `E_WARNING` de variável indefinida (ou um `E_NOTICE` antes do PHP 8.0.0). Isto acontece porque a instrução echo refere-se a uma versão local da variável $a, e não possui nenhum valor atribuído neste escopo. Pode-se perceber que esta é uma pequena diferença em relação à linguagem C, em que variáveis globais estão automaticamente disponíveis para funções a menos que tenham sido substituídas por uma definição local. Isto pode causar problemas quando uma variável global for inadvertidamente modificada. No PHP, as variáveis globais precisam ser declaradas como globais dentro de uma função, se elas precisarem ser utilizadas na função.

### A palavra-chave `global`

A palavra-chave `global` é usada para vincular uma variável de um escopo global a um escopo local. A palavra-chave pode ser usada com uma lista de variáveis ​​ou com uma única variável. Uma variável local será criada referenciando a variável global de mesmo nome. Se a variável global não existir, a variável será criada no escopo global e receberá o valor `null`.

Exemplo #3 Usando `global`

    <?php
    $a = 1;
    $b = 2;

    function Soma()
    {
        global $a, $b;

        $b = $a + $b;
    }

    Soma();
    echo $b;

O exemplo acima produzirá:

    3

Declarar $a e $b como globais na função fará com que todas as referências a essas variáveis refiram-se às versões globais. Não há um limite para o número de variáveis globais que podem ser manipuladas por uma função.

Uma segunda maneira de acessar variáveis do escopo global é utilizando o array especial $GLOBALS definido pelo PHP. O exemplo anterior poderia ser reescrito como:

Exemplo #4 Usando $GLOBALS no lugar de global

    <?php
    $a = 1;
    $b = 2;

    function Soma()
    {
        $GLOBALS['b'] = $GLOBALS['a'] + $GLOBALS['b'];
    }

    Soma();
    echo $b;

O array $GLOBALS é um array associativo, com o nome da variável global na chave e o conteúdo dessa variável no valor do elemento do array. Veja que $GLOBALS existe em qualquer escopo, isto porque $GLOBALS é uma superglobal. Eis um exemplo demonstrando o poder das superglobais:

Exemplo #5 Exemplo demonstrando superglobals e escopos

    <?php
    function test_superglobal()
    {
        echo $_POST['name'];
    }

> Nota: Utilizar a instrução `global` fora de uma função não é um erro. Pode ser utilizado se o arquivo for incluído de dentro de uma função.

### Utilizando variáveis `static`

Outro recurso importante do escopo de variáveis é a variável estática. Uma variável estática existe somente no escopo local da função, mas não perde seu valor quando a execução do programa deixa o escopo. Considere o seguinte exemplo:

Exemplo #6 Exemplo demonstrando a necessidade de variáveis estáticas

    <?php
    function Teste()
    {
        $a = 0;
        echo $a . PHP_EOL;
        $a++;
    }

    test();
    test();
    test();

Essa função é inútil, já que cada vez que é chamada, define $a com o valor `0`, e exibe `0`. A instrução $a++ , que aumenta o valor da variável, não tem sentido já que assim que a função termina, a variável $a desaparece. Para fazer um função de contagem útil, que não perderá a contagem atual, a variável $a será declarada como estática:

Exemplo #7 Exemplo de uso de variáveis estáticas

    <?php
    function Teste()
    {
        static $a = 0;
        echo $a . PHP_EOL;
        $a++;
    }

    test();
    test();
    test();

Agora, a variável $a é inicializada apenas na primeira chamada da função e cada vez que a função `test()` for chamada, exibirá o valor de $a e depois o incrementará.

Variáveis estáticas fornecem uma solução para lidar com funções recursivas. A seguinte função recursiva conta até 10, utilizando a variável estática $count para saber quando parar:

Exemplo #8 Variáveis estáticas em funções recursivas

    <?php
    function Teste()
    {
        static $count = 0;

        $count++;
        echo $count . PHP_EOL;
        if ($count < 10) {
            Teste();
        }
        $count--;
    }

    test();

Antes do PHP 8.3.0, variáveis estáticas somente poderiam ser inicializadas usando uma expressão constante. A partir do PHP 8.3.0, expressões dinâmicas (por exemplos, chamadas de funções) também são permitidas:

Exemplo #9 Declarando variáveis estáticas

    <?php
    function foo(){
        static $int = 0;          // correto
        static $int = 1+2;        // correto
        static $int = sqrt(121);  // correto a partir do PHP 8.3

        $int++;
        echo $int;
    }

Variáveis ​​estáticas dentro de funções anônimas persistem apenas dentro daquela instância de função específica. Se a função anônima for recriada em cada chamada, a variável estática será reinicializada.

Exemplo #10 Variáveis ​​estáticas em funções anônimas

    <?php
    function funcaoExemplo($input) {
        $result = (static function () use ($input) {
            static $counter = 0;
            $counter++;
            return "Entrada: $input, Contador: $counter\n";
        });

        return $result();
    }

    // Chamadas a funcaoExemplo irão recriar a função anônima, de forma
    // que a variável estática não reterá seu valor.
    echo funcaoExemplo('A'); // Exibe: Entrada: A, Contador: 1
    echo funcaoExemplo('B'); // Exibe: Entrada: B, Contador: 1

A partir do PHP 8.1.0, quando um método com variáveis estáticas é herdado (mas não sobrescrito), o método herdado não compartilhará as variáveis estáticas do método acima. Isso significa que variáveis estáticas nos métodos agora se comportam da mesma forma que propriedades estáticas.

A partir do PHP 8.3.0, variáveis estáticas podem ser inicializadas com expressões arbitrárias. Isto significa que chamadas de métodos, por exemplo, podem ser usadas para iniciá-las.

Exemplo #11 Uso de variáveis estáticas em métodos herdados

    <?php
    class Foo {
        public static function counter() {
            static $counter = 0;
            $counter++;
            return $counter;
        }
    }
    class Bar extends Foo {}
    var_dump(Foo::counter()); // int(1)
    var_dump(Foo::counter()); // int(2)
    var_dump(Bar::counter()); // int(3), e antes do PHP 8.1.0 int(1)
    var_dump(Bar::counter()); // int(4), e antes do PHP 8.1.0 int(2)

### Referências em variáveis `global` e `static`

O PHP implementa os modificadores static e global para variáveis, em termo de referências. Por exemplo, uma variável global verdadeira, importada dentro do escopo de uma função com a instrução `global`, na verdade, cria uma referência para a variável global. Isto pode levar a comportamentos imprevisíveis nos seguintes casos:

    <?php
    function test_global_ref() {
        global $obj;
        $new = new stdClass;
        $obj = &$new;
    }

    function test_global_noref() {
        global $obj;
        $new = new stdClass;
        $obj = $new;
    }

    test_global_ref();
    var_dump($obj);
    test_global_noref();
    var_dump($obj);

O exemplo acima produzirá:

    NULL
    object(stdClass)#1 (0) {
    }

Um comportamento similar se aplica à declaração `static`. Referências não são armazenadas estaticamente:

    <?php
    function &get_instance_ref() {
        static $obj;

        echo 'Objeto estático: ';
        var_dump($obj);
        if (!isset($obj)) {
            $new = new stdClass;
            // Atribui uma referência à variável estática
            $obj = &$new;
        }
        if (!isset($obj->property)) {
            $obj->property = 1;
        } else {
            $obj->property++;
        }
        return $obj;
    }

    function &get_instance_noref() {
        static $obj;

        echo "Objeto estático: ";
        var_dump($obj);
        if (!isset($obj)) {
            $new = new stdClass;
            // Atribui o objeto à variável estática
            $obj = $new;
        }
        if (!isset($obj->property)) {
            $obj->property = 1;
        } else {
            $obj->property++;
        }
        return $obj;
    }

    $obj1 = get_instance_ref();
    $still_obj1 = get_instance_ref();
    echo "\n";
    $obj2 = get_instance_noref();
    $still_obj2 = get_instance_noref();

O exemplo acima produzirá:

    Objeto estático: NULL
    Objeto estático: NULL

    Objeto estático: NULL
    Objeto estático: object(stdClass)#3 (1) {
      ["property"]=>
      int(1)
    }

Este exemplo demonstra que ao atribuir uma referência a uma variável estática, ela não será lembrada quando a função `&get_instance_ref()` for chamada uma segunda vez.

## Variáveis variáveis

Às vezes, é conveniente possuir nome variáveis para variáveis. Isto é, o nome de uma variável que pode ser definido e utilizado dinamicamente. Uma variável normal é definida com uma instrução como:

    <?php
    $a = 'hello';
    var_dump($a);

Uma variável variável obtém o valor de uma variável e a trata como o nome de uma variável. No exemplo acima, hello pode ser utilizado como o nome de uma variável utilizando dois sinais de cifrão:

    <?php
    $a = 'hello';
    $$a = "world";
    var_dump($hello);

Neste ponto, duas variáveis foram definidas e armazenadas na árvore de símbolos do PHP: $a que contém "hello" e $hello que contém "world". Assim, esta instrução:

    <?php
    $a = 'hello';
    $$a = 'world';
    echo "$a {$$a}";

produz a mesma saída que:

    <?php
    $a = 'hello';
    $$a = 'world';
    echo "$a $hello";

assim sendo, as duas produzem: hello world.

Para poder utilizar variáveis variáveis com arrays, é necessário resolver um problema de ambiguidade. Isso é, se for escrito $$a[1], o interpretador precisa saber se a intenção é utilizar $a[1] como uma variável ou se a intenção é usar $$a como uma variável e `[1]` como o índice dessa variável. A sintaxe para resolver essa ambiguidade é ${$a[1]} para o primeiro caso e ${$a}[1] para o segundo.

Propriedades de classes também podem ser acessadas utilizando-se nomes de propriedades variáveis. O nome de propriedade variável será resolvido dentro do escopo em que a chamada foi feita. Por exemplo, se houver uma expressão como $foo->$bar, o escopo local será examinado procurando por $bar e seu valor será utilizado como o nome da propriedade $foo. Isso também funciona se $bar for um array.

Chaves também podem ser utilizadas para delimitar claramente os nomes de propriedade. São muito úteis ao acessar valores de uma propriedade que contenham um array, quando o nome da propriedade tem várias partes, ou quando o nome da propriedade contém caracteres que não são válidos (por exemplo, em saídas da função json_decode() ou SimpleXML).

Exemplo #1 Exemplo de propriedade variável

    <?php
    class Foo {
        public $bar = 'Eu sou bar.';
        public $arr = ['Eu sou A.', 'Eu sou B.', 'Eu sou C.'];
        public $r   = 'Eu sou r.';
    }

    $foo = new Foo();
    $bar = 'bar';
    $baz = ['foo', 'bar', 'baz', 'quux'];
    echo $foo->$bar . "\n";
    echo $foo->{$baz[1]} . "\n";

    $start = 'b';
    $end   = 'ar';
    echo $foo->{$start . $end} . "\n";

    $arr = 'arr';
    echo $foo->{$arr[1]} . "\n";
    echo $foo->{$arr}[1] . "\n";

O exemplo acima produzirá:

    Eu sou bar.
    Eu sou bar.
    Eu sou bar.
    Eu sou r.
    Eu sou B.

Aviso

Observe que variáveis variáveis não podem ser utilizadas nos arrays superglobais dentro de funções ou métodos de classe. A variável `$this` também é uma variável especial que não pode ser referenciada dinamicamente.

## Variáveis de fontes externas

### Formulários HTML (GET e POST)

Quando um formulário é submetido para um script PHP, a informação deste formulário estará automaticamente disponível para o script. Há algumas maneiras de acessar estas informações, por exemplo:

Exemplo #1 Um formulário HTML simples

    <form action="foo.php" method="post">
        Nome:  <input type="text" name="username" /><br />
        Email: <input type="text" name="email" /><br />
        <input type="submit" name="submit" value="Me aperte!" />
    </form>

Existem apenas duas formas de acessar dados de formulários HTML. Os métodos disponíveis atualmente são listadas a seguir:

Exemplo #2 Acessando dados de um formulário HTML via POST

    <?php
    echo $_POST['username'];
    echo $_REQUEST['username'];

Utilizar um formulário GET é similar, exceto que será utilizada a variável predefinida GET em seu lugar. GET também se aplica à variável `QUERY_STRING` (a informação depois do '?' numa URL). Então, por exemplo, `http://www.example.com/test.php?id=3` contém os dados GET que estarão acessíveis com $_GET['id']. Veja também $_REQUEST.

> Nota:

> Pontos e espaços em nomes de variáveis são convertidos para sublinhados. Por exemplo `<input name="a.b" />` se tornará `$_REQUEST["a_b"]`.

O PHP também entende arrays no contexto de variáveis de formulário (veja essa FAQ). Pode-se, por exemplo, agrupar variáveis relacionadas, ou utilizar este recurso para obter valores de uma entrada de seleção múltipla. No exemplo abaixo, o formulário é enviado para si mesmo, e depois de submetido, os dados são mostrados:

Exemplo #3 Variáveis de formulários mais complexos

    <?php
    if ($_POST) {
        echo '<pre>';
        echo htmlspecialchars(print_r($_POST, true));
        echo '</pre>';
    }
    ?>
    <form action="" method="post">
        Nome:  <input type="text" name="personal[name]" /><br />
        Email: <input type="text" name="personal[email]" /><br />
        Cerveja: <br />
        <select multiple name="beer[]">
            <option value="heineken">Heineken</option>
            <option value="stella">Stella Artois</option>
            <option value="av42">Double Rye Ipa</option>
        </select><br />
        <input type="submit" value="Enviar dados!" />
    </form>

> Nota: Se um nome de variável externa se parece com sintaxe de array válida, as letras finais são silenciosamente ignoradas. Por exemplo, `<input name="foo[bar]baz">` se torna `$_REQUEST['foo']['bar']`.

#### Nomes de variáveis SUBMIT IMAGE

Ao submeter um formulário, é possível utilizar imagens em vez do botão de submissão padrão com uma tag do tipo:

    <input type="image" src="image.gif" name="sub" />

Quando o usuário clicar em algum lugar da imagem, o formulário será transmitido para o servidor com duas variáveis adicionais, sub_x e sub_y. Elas contém as coordenadas do clique do usuário na imagem. Os mais experientes percebem que os nomes reais dessas variáveis enviadas ao navegador contêm um ponto ao invés de um sublinhado, mas o PHP converte o ponto para um sublinhado automaticamente.

### Cookies HTTP

O PHP suporta transparentemente cookies HTTP como os definidos pela » RFC 6265. Cookies são um mecanismo o armazenamento de dados no navegador, rastreando e identificando o retorno de usuários. Você pode definir cookies com a função setcookie(). Cookies são parte do cabeçalho HTTP, então a função SetCookie precisa ser chamada antes de qualquer saída ser enviada ao navegador. Esta é a mesma restrição da função header(). Dados de cookies estão disponíveis nos arrays de dados de cookies apropriados, como $_COOKIE e também em $_REQUEST. Veja o manual de setcookie() para mais detalhes e exemplos.

> Nota: A partir dos PHP 7.2.34, 7.3.23 e 7.4.11, respectivamente, os nomes dos cookies recebidos não são decodificados (a partir do formato URL) por razões de segurança.

Se a intenção for atribuir vários valores a uma única variável do cookie, deve-se atribuí-la como um array:

    <?php
    setcookie("MyCookie[foo]", 'Testing 1', time()+3600);
    setcookie("MyCookie[bar]", 'Testing 2', time()+3600);

Isso criará dois cookies separados embora MyCookie será agora um único array no script. Se a intenção for definir apenas um cookie com vários valores, pode-se utilizar serialize() ou explode() nos valores primeiro.

Note que um cookie substituirá um anterior com o mesmo nome no navegador, a menos que o caminho ou o domínio seja diferente. Portanto, para uma aplicação de carrinho de compras, pode-se manter um contador e repassá-lo:

Exemplo #4 Um exemplo de setcookie()

    <?php
    if (isset($_COOKIE['count'])) {
        $count = $_COOKIE['count'] + 1;
    } else {
        $count = 1;
    }
    setcookie('count', $count, time()+3600);
    setcookie("Cart[$count]", $item, time()+3600);

### Pontos em nomes de variáveis recebidas

Normalmente o PHP não altera o nome de variáveis quando elas são passadas para um script. Entretanto, deve ser notado que o ponto (ponto final) não é um caractere válido em nome de variável do PHP. Para ilustrar o motivo, veja o seguinte exemplo:

    <?php
    $varname.ext;  /* nome de variável inválido */

Dessa forma, o interpretador entende isso como uma variável com nome de $varname, seguida do operador de concatenação de strings, seguida de uma string crua (uma string não delimitada que não bate com nenhuma palavra-chave ou reservada) 'ext'. Obviamente, isso não tem os resultados pretendidos.

Nessa situação, é importante notar que o PHP substituirá automaticamente qualquer ponto nos nomes de variáveis recebidas por sublinhados.

### Determinando o tipo das variáveis

Como o PHP determina os tipos de variáveis e faz conversões (geralmente) quando necessário, nem sempre é óbvio o tipo de uma variável em cada momento. O PHP inclui várias funções que permitem determinar qual o tipo de uma variável, por exemplo: gettype(), is_array(), is_float(), is_int(), is_object(),e is_string(). Veja também o capítulo sobre Tipos.

Pelo fato do HTTP ser um protocolo de texto, a maioria, se não todo o conteúdo presente nos arrays superglobais como $_POST e $_GET permanecerão como strings. O PHP não tentará converter valores para um tipo específico. No exemplo abaixo, $_GET["var1"] conterá a string "null" e $_GET["var2"] conterá a string "123".

    /index.php?var1=null&var2=123

### Registro de Alterações

Versão | Descrição
--- | ---
7.2.34, 7.3.23, 7.4.11 | Os nomes dos cookies recebidos não são mais decodificados (a partir do formato URL) por razões de segurança.

# Constantes

## Índice

- Sintaxe
- Constantes Predefinidas
- Constantes Mágicas

Uma constante é um identificador (nome) para um valor simples. Como o nome sugere, esse valor não pode mudar durante a execução do script (exceto para as constantes mágicas, que na verdade não são constantes). As constantes diferenciam maiúsculas de minúsculas. Por convenção, identificadores de constantes são sempre em maiúsculas.

> Nota:

> Antes do PHP 8.0.0, as constantes definidas usando a função define() podem não diferenciar maiúsculas de minúsculas.

O nome de uma constante segue as mesmas regras de qualquer rótulo no PHP. Um nome de constante válido começa com uma letra ou sublinhado, seguido por qualquer número de letras, números ou sublinhados. Como uma expressão regular, seria expresso assim: `^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$`

É possível usar define() para definir constantes com nomes reservados ou mesmo inválidos, cujo valor só pode ser recuperado com a função constant(). No entanto, isso não é recomendado.

Dica

Veja também o Guia de nomenclatura em espaço de usuário.

Exemplo #1 Nomes de constantes válidos e inválidos

    <?php

    // Nomes de constantes válidos
    define("FOO",     "alguma coisa");
    define("FOO2",    "alguma outra coisa");
    define("FOO_BAR", "alguma coisa mais");

    // Nomes de constantes inválidos
    define("2FOO",    "alguma coisa");

    // Isso é válido, mas deve ser evitado:
    // O PHP pode um dia fornecer uma constante mágica
    // que quebrará seu script
    define("__FOO__", "alguma coisa");

> Nota: Para os exemplos aqui, uma letra é a-z, A-Z e os caracteres ASCII de 128 a 255 (0x80-0xff).

Como as superglobals, o escopo de uma constante é global. As constantes podem ser acessadas de qualquer lugar em um script, independentemente do escopo. Para mais informações sobre escopo, leia a seção do manual escopo de variáveis.

> Nota: A partir do PHP 7.1.0, as constantes de classe podem ser declaradas com visibilidade protected ou private, tornando-as disponíveis apenas no escopo hierárquico da classe em que foram definidas.

## Sintaxe

As constantes podem ser definidas usando a palavra-chave `const` ou usando a função define(). Enquanto define() permite que uma constante seja definida usando uma expressão arbitrária, a palavra-chave `const` possui restrições, conforme descrito no próximo parágrafo. Uma vez definida, a constante nunca poderá ser modificada ou anulada.

Ao usar a palavra-chave `const`, somente expressões escalares (bool, int, float e string) e arrays constantes contendo apenas expressões escalares são aceitos. É possível definir constantes como um resource, mas isso deve ser evitado, pois pode causar resultados inesperados.

O valor de uma constante é acessado simplesmente informando seu nome. Ao contrário das variáveis, uma constante não é precedida por um `$`. Também é possível usar a função constant() para ler o valor de uma constante se o nome da constante for obtido dinamicamente. Use get_defined_constants() para obter uma lista de todas as constantes definidas.

> Nota: As constantes e variáveis (globais) estão em espaços de nomes diferentes. Isso implica que, por exemplo, `true` e $TRUE são geralmente diferentes.

Se uma constante indefinida for usada, um erro Error será lançado. Antes do PHP 8.0.0, constantes indefinidas eram interpretadas como uma simples string, ou seja, CONSTANTE vs. "CONSTANTE". Esse mecanismo alternativo foi descontinuado a partir do PHP 7.2.0 e um alerta de nível `E_WARNING` será lançado quando isso acontecer. Antes do PHP 7.2.0, um erro de nível E_NOTICE era lançado. Veja também por que $foo[bar] é errado (a não ser que `bar` seja uma constante). Isso não se aplica às constantes (totalmente) qualificadas, que sempre lançarão um Error se forem indefinidas.

> Nota: Para verificar se uma constante está definida, use a função defined().

Estas são as diferenças entre constantes e variáveis:

- Constantes não têm um cifrão (`$`) antes delas;
- Constantes podem ser definidas e acessadas em qualquer lugar sem considerar as regras de escopo de variáveis;
- Constantes não podem ser redefinidas ou anuladas depois de definidas; e
- Constantes só podem ter valores escalares ou arrays.

Exemplo #1 Definindo Constantes

    <?php
    define("CONSTANTE", "Olá Mundo.");
    echo CONSTANTE; // imprime "Olá Mundo."
    echo Constante; // Lança um erro Error: Undefined constant "Constante"
                   // Antes do PHP 8.0.0, imprime "Constante" e emite um aviso.

Exemplo #2 Definindo Constantes usando a palavra-chave `const`

    <?php
    // Valor escalar simples
    const CONSTANTE = 'Olá Mundo';

    echo CONSTANTE . "\n";

    // Expressão escalar
    const OUTRA_CONSTANTE = CONSTANTE . '; Adeus Mundo';
    echo OUTRA_CONSTANTE . "\n";

    const ANIMAIS = array('cachorro', 'gato', 'pássaro');
    echo ANIMAIS[1] . "\n"; // imprime "gato"

    // Array constante
    define('ANIMAIS_DEF', array(
        'cachorro',
        'gato',
        'pássaro'
    ));
    echo ANIMAIS_DEF[1] . "\n"; // imprime "gato"

> Nota:

> Ao contrário das constantes definidas usando define(), as constantes definidas usando a palavra-chave `const` devem ser declaradas no escopo mais externo porque são definidas em tempo de compilação. Isto significa que constantes não podem ser declaradas dentro de funções, loops, declarações `if` ou blocos `try`/`catch`.

### Veja Também

- Constantes de Classe

## Constantes Predefinidas

O PHP fornece um grande número de constantes predefinidas para qualquer script executado. Muitas dessas constantes, no entanto, são criadas por várias extensões e só estarão presentes quando essas extensões estiverem disponíveis, seja por carregamento dinâmico ou porque foram compiladas.

## Constantes Mágicas

Existem algumas constantes mágicas que mudam dependendo de onde são usadas. Por exemplo, o valor de `__LINE__` depende da linha em que é usada no script. Todas essas constantes "mágicas" são resolvidas em tempo de compilação, ao contrário das constantes regulares, que são resolvidas em tempo de execução. Essas constantes especiais não diferenciam maiúsculas de minúsculas e são as seguintes:

Constantes Mágicas do PHP
Nome | Descrição
--- | ---
`__LINE__` | O número da linha atual do arquivo.
`__FILE__` | O caminho completo e o nome do arquivo com links simbólicos resolvidos. Se usada dentro de um include, o nome do arquivo incluído será retornado.
`__DIR__` | O diretório do arquivo. Se usada dentro de um include, o diretório do arquivo incluído será retornado. Isso é equivalente a `dirname(__FILE__)`. O nome do diretório não possui barra no final, a menos que seja o diretório raiz.
`__FUNCTION__` | O nome da função ou `{closure}` para funções anônimas.
`__CLASS__` | O nome da classe. O nome da classe inclui o namespace em que foi declarada (por exemplo, `Foo\Bar`). Quando usada dentro de um método de trait, `__CLASS__` é o nome da classe em que o trait for usado.
`__TRAIT__` | O nome do trait. O nome do trait inclui o namespace em que foi declarado (por exemplo, `Foo\Bar`).
`__METHOD__` | O nome do método da classe.
`__PROPERTY__` | Válido somente dentro de um gancho de propriedade. É igual ao nome da propriedade.
`__NAMESPACE__` | O nome do namespace atual.
`ClassName::class` | O nome totalmente qualificado da classe.

### Veja Também

- ::class
- get_class()
- get_object_vars()
- file_exists()
- function_exists()

# Expressões

Expressões são os blocos de construção mais importantes do PHP. No PHP, quase tudo o que você escreve são expressões. A maneira mais simples e ainda mais precisa de definir uma expressão é "tudo o que tem um valor".

As formas mais básicas de expressões são constantes e variáveis. Quando você digita `$a = 5`, você está atribuindo `5` dentro de $a. `5` obviamente tem o valor 5, ou em outras palavras `5` é uma expressão com o valor de 5 (nesse caso `5` é uma constante inteira).

Depois desta atribuição, você pode esperar que o valor de $a seja 5 também, assim se você escrever `$b = $a`, você pode esperar que ele se comporte da mesma forma que se você escrevesse `$b = 5`. Em outras palavras, $a é uma expressão com valor 5 também. Se tudo funcionou bem isto é exatamente o que aconteceu.

Exemplos ligeiramente mais complexos para expressões são as funções. Por exemplo, considere a seguinte função:

    <?php
    function foo ()
    {
        return 5;
    }
    ?>

Assumindo que você está familiarizado com o conceito de funções (se não estiver, dê uma olhada no capítulo sobre funções), você pode assumir que digitar `$c = foo()` é essencialmente a mesma coisa que escrever `$c = 5`, e você está certo. Funções são expressões com o valor igual ao seu valor de retorno. Como `foo()` retorna 5, o valor da expressão '`foo()`' é 5. Geralmente, as funções não retornam apenas um valor estático, mas computam algo.

Claro, valores em PHP não tem que ser inteiros, e muito comumente eles não são. O PHP suporta quatro tipos de valores escalares: valores int (inteiros), valores de ponto flutuante (float), valores string (caracteres) e valores bool (booleano) (valores escalares são valores que você não pode partir em peças menores, diferentemente de arrays, por exemplo). O PHP também suporta dois tipos compostos (não escalar): arrays e objetos. Cada um desses valores podem ser definidos em uma variável ou retornados de uma função.

O PHP leva as expressões muito além, da mesma maneira que muitas outras linguagens fazem. O PHP é uma linguagem orientada a expressões, no sentido de que quase tudo são expressões. Considere o exemplo com o qual já lidamos, `$a = 5`. É fácil ver que há dois valores envolvidos aqui, o valor da constante inteira `5`, e o valor de $a que está sendo atualizado para 5 também. Mas a verdade é que há um valor adicional envolvido aqui, e que é o próprio valor da atribuição. A própria atribuição é avaliada com o valor atribuído, neste caso 5. Na prática, significa que `$a = 5`, independente do que faça, é uma expressão com o valor 5. Portanto, escrever algo como `$b = ($a = 5)` é como escrever `$a = 5; $b = 5;` (um ponto-e-vírgula marca o fim do comando). Como as atribuições são analisadas da direita para a esquerda, você também pode escrever `$b = $a = 5`.

Outro bom exemplo de orientação de expressão é o pré e o pós-incremento e decremento. Usuários de PHP 2 e muitas outras linguagens podem estar familiarizados com a notação de `variable++` e `variable--`. Estes são operadores de incremento e decremento. Em PHP, como em C, há dois tipos de incremento - pré-incremento e pós-incremento. Tanto o pré-incremento quanto o pós-incremento, essencialmente, incrementam as variáveis, e o efeito sobre a variável é idêntico. A diferença é com o valor da expressão de incremento. O pré-incremento, que é escrito `++$variable`', é avaliado como o valor de incremento (o PHP incrementa a variável antes de ler seu valor, por isso o nome pré-incremento). O pós-incremento, que é escrito `$variable++` é avaliado como o valor original de $variable, antes de ser incrementada (o PHP incrementa a variável depois de ler seu valor, por isso o nome 'pós-incremento').

Um tipo muito comum de expressões são expressões de comparação. Estas expressões avaliam como `false` ou `true`. O PHP suporta > (maior que), >= (maior ou igual a), == (igual), != (diferente), < (menor que) e <= (menor ou igual a). A linguagem também suporta um conjunto de operador de equivalência estrita: === (igual a e do mesmo tipo) e !== (diferente de ou não do mesmo tipo). Estas expressões são mais comumente usadas dentro de execução condicional como comandos `if`.

O último exemplo de expressões com que nós vamos lidar aqui são as expressões combinadas operador-atribuição. Você já sabe que se você quer incrementar $a de 1, você só precisa escrever `$a++` ou `++$a`. Mas e se você quiser somar mais que um a ele, por exemplo 3? Você poderia escrever `$a++` várias vezes, mas esta obviamente não é uma forma muito eficiente ou confortável. Uma prática muito mais comum é escrever `$a = $a + 3`. `$a + 3` é avaliada como o valor de $a mais 3, e é atribuído de volta a $a, que resulta em incrementar $a em 3. Em PHP, como em várias outras linguagens como o C, você pode escrever isto de uma forma mais curta, que com o tempo se torna mais limpa e rápida de se entender. Somar 3 ao valor corrente de $a pode ser escrito `$a += 3`. Isto significa exatamente "pegue o valor de $a, some 3 a ele, e atribua-o de volta a $a." Além de ser mais curto e mais limpo, isto também resulta em execução mais rápida. O valor de `$a += 3`, como o valor de uma atribuição regular, é o valor atribuído. Note que NÃO é 3, mas o valor combinado de $a mais 3 (este é o valor que é atribuído a $a). Qualquer operador de dois parâmetros pode ser usado neste modo operador-atribuição, por exemplo `$a -= 5` (subtrai 5 do valor de $a), `$b *= 7` (multiplica o valor de $b por 7), etc.

Há mais uma expressão que podem parecer estranha se você não a viu em outras linguagens, o operador condicional ternário:

    <?php
    $primeira ? $segunda : $terceira
    ?>

Se o valor da primeira sub-expressão é verdadeiro (`true`, não-zero), então a segunda sub-expressão é avaliada, e este é o resultado da expressão condicional. Caso contrário, a terceira sub-expressão é avaliada e este é o valor.

O seguinte exemplo deve ajudá-lo a entender um pouco melhor pré e pós-incremento e expressões em geral:

    <?php
    function double($i)
    {
        return $i * 2;
    }

    $b = $a = 5;        /* atribui o valor cinco às variáveis $a e $b */
    $c = $a++;          /* pós-incremento, atribui o valor original de $a
                           (5) para $c */
    print "a = {$a}; b = {$b}; c = {$c}" . PHP_EOL;

    $e = $d = ++$b;     /* pré-incremento, atribui o valor incrementado de
                           $b (6) a $d e $e */
    print "b = {$b}; d = {$d}; e = {$e}" . PHP_EOL;

    /* neste ponto, tanto $d quanto $e são iguais a 6 */

    $f = double($d++);  /* atribui o dobro do valor de $d antes
                           do incremento, 2*6 = 12 a $f */
    print "d = {$d}; f = {$f}" . PHP_EOL;

    $g = double(++$e);  /* atribui o dobro do valor de $e depois
                           do incremento, 2*7 = 14 a $g */
    print "e = {$e}; g = {$g}" . PHP_EOL;

    $h = $g += 10;      /* primeiro, $g é incrementado de 10 e termina com o
                           valor 24. o valor da atribuição (24) é
                           então atribuído a $h, e $h termina com o valor
                           24 também. */
    print "g = {$g}; h = {$h}" . PHP_EOL;
    ?>

Algumas expressões podem ser consideradas instruções. Neste caso, uma instrução na forma '`expr ;`' ou seja, uma expressão seguida de um ponto e vírgula. Em `$b = $a = 5;`, `$a = 5` é uma expressão válida, mas não é um comando por si só. `$b = $a = 5;` porém é um comando válido.

Uma última coisa que vale mencionar é o valor-verdade de expressões. Em muitos eventos, principalmente em instruções condicionais e loops, você não está interessado no valor específico da expressão, mas somente se ela significa `true` ou `false` (o PHP não tem um tipo booleano dedicado). As constantes `true` e `false` (insensitivas ao caso) são seus dois valores booleanos possíveis. Às vezes uma expressão é automaticamente convertida para um booleano. Veja a seção sobre type-casting para detalhes de como isso é feito.

O PHP fornece uma implementação completa e poderosa de expressões, e a completa documentação dela vai além do escopo deste manual. Os exemplos acima devem dar a você uma boa ideia sobre o que são as expressões e como você pode construir expressões úteis. Através do restante do manual nós escreveremos expr (ou expressão) para indicar qualquer expressão PHP válida.

# Operadores

## Índice

- Precedência de Operadores
- Aritméticos
- Incremento e Decremento
- Atribuição
- Binários
- Comparação
- Controle de Erro
- Execução
- Lógica
- String
- Arrays
- Tipo
- Funcional

Um operador é algo que recebe um ou mais valores (ou expressões, no jargão de programação) e que devolve outro valor (e por isso os operadores são expressões também).

Operadores podem ser agrupados segundo o número de valores que aceitam. Operadores unários recebem um único valor, por exemplo `!` (o operador lógico de negação) ou `++` (o operador de incremento). Operadores binários aceitam dois valores, como os operadores aritméticos `+` (soma) e `-` (subtração), além da maioria dos operadores PHP dessa categoria. Finalmente há um único operador ternário, `? :`, que aceita três valores; normalmente conhecido simplesmente como "o operador ternário" (embora um nome melhor fosse operador condicional).

A lista completa dos operadores no PHP está na seção sobre Precedência de Operadores. Essa seção também explica precedência e combinações, que governam exatamente como expressões contendo vários operadores são avaliados.

## Precedência de Operadores

A precedência de um operador especifica quem tem mais prioridade quando há duas delas juntas. Por exemplo, na expressão `1 + 5 * 3`, a resposta é `16` e não `18` porque o operador de multiplicação ("*") tem prioridade de precedência que o operador de adição ("+"). Parênteses podem ser utilizados para forçar a precedência, se necessário. Assim, `(1 + 5) * 3` é avaliado como `18`.

Quando operadores têm precedência igual a associatividade decide como os operadores são agrupados. Por exemplo "-" é associado à esquerda, de forma que `1 - 2 - 3` é agrupado como `(1 - 2) - 3` e resulta em `-4`. "=" por outro lado associa para a direita, de forma que `$a = $b = $c` é agrupado como `$a = ($b = $c)`.

Operadores de igual precedência e associatividade não podem ser utilizados uns próximos aos outros. Por exemplo `1 < 2 > 1` é ilegal no PHP. A expressão `1 <= 1 == 1` por outro lado é válida, porque o operador `==` tem menor precedência que o operador `<=`.

A associatividade somente faz sentido para operadores binários e ternários. Operadores unários são precedentes ou seguintes, de forma que essa outra noção não se aplica. Por exemplo `!!$a` somente pode ser agrupado como `!(!$a)`.

O uso de parênteses, embora não estritamente necessário, pode melhorar a leitura do código ao deixar o agrupamento explícito em vez de depender da associatividade e precedências implícitos.

A tabela seguinte mostra a precedência dos operadores, com a maior precedência no começo. Operadores com a mesma precedência estão na mesma linha, nesses casos a associatividade deles decidirá qual ordem eles serão avaliados.

Precedência dos operadores
Associação | Operadores | Informação Adicional
--- | --- | ---
(não aplicável) | `clone` `new` | clone e new
direita | `**` | aritmético
(não aplicável) | `+` `-` `++` `--` `~` `(int)` `(float)` `(string)` `(array)` `(object)` `(bool)` `@` | aritméticos (unário `+` e `-`), incremento/decremento, binário, conversão de tipo e controle de erro
esquerda | `instanceof` | tipo
(não aplicável) | `!` | lógico
esquerda | `*` `/` `%` | aritméticos
esquerda | `+` `-` `.` | aritméticos (binário `+` e `-`), array e string (`.` anteriormente ao PHP 8.0.0)
esquerda | `<<` `>>` | binários
esquerda | `.` | string (a partir do PHP 8.0.0)
esquerda | `|>` | pipe
não associativo | `<` `<=` `>` `>=` | comparação
não associativo | `==` `!=` `===` `!==` `<>` `<=>` | comparação
esquerda | `&` | binário e referências
esquerda | `^` | binário
esquerda | `|` | binário
esquerda | `&&` | lógico
esquerda | `||` | lógico
direita | `??` | coalescência nula
não associativo | `? :` | ternário (esquerda anteriormente ao PHP 8.0.0)
direita | `=` `+=` `-=` `*=` `**=` `/=` `.=` `%=` `&=` `|=` `^=` `<<=` `>>=` `??=` | atribuição
(não aplicável) | `yield from` | yield from
(não aplicável) | `yield` | yield
(não aplicável) | `print` | print
esquerda | `and` | lógicos
esquerda | `xor` | lógicos
esquerda | `or` | lógicos
(n/a) | `throw` | throw

> Nota: Os operadores unários que compartilham a linha com os operadores de conversão (`~`, `@`, e os unários `+`/`-`) se ligam com mais força que `instanceof`, enquanto que `!` se liga com menos força. Consequentemente, `(int) $x instanceof Foo` é agrupado como `((int) $x) instanceof Foo`, enquanto que `!$x instanceof Foo` é agrupado como `!($x instanceof Foo)`.

Exemplo #1 Associação

    <?php
    $a = 3 * 3 % 5; // (3 * 3) % 5 = 4
    var_dump($a);

    $a = 1;
    $b = 2;
    $a = $b += 3; // $a = ($b += 3) -> $a = 5, $b = 5
    var_dump($a, $b);
    ?>

O operador ternário requer especificamente o uso de parênteses para remover a ambiguidade de precedência.

Exemplo #2 Precedência explícita

    <?php
    $a = true ? 0 : (true ? 1 : 2);
    var_dump($a);

    // isto não é permitido desde o PHP 8
    // $a = true ? 0 : true ? 1 : 2;
    ?>

A precedência e a associatividade apenas determinam como as expressões são agrupadas, mas não especificam a ordem de avaliação. O PHP (geralmente) não especifica em que ordem as expressões são avaliadas, então códigos que assumem ordens específicas de avaliação devem ser evitados porque o comportamento pode ser alterado entre versões do PHP ou dependendo do código em volta.

Exemplo #3 Ordem de avaliação não definida

    <?php
    $a = 1;
    echo $a + $a++; // pode exibir 2 ou 3

    $i = 1;
    $array[$i] = $i++; // pode definir o índice 1 ou 2
    ?>

Exemplo #4 Precedência de `+`, `-` e `.`

    <?php
    $x = 4;
    // esta linha pode resultar em uma saída inesperada:
    echo "x menos um é igual a " . $x-1 . ", ou assim eu espero\n";

    // a precedência desejada pode ser aplicada utilizando parênteses:
    echo "x menos um é igual a " . ($x-1) . ", ou assim eu espero\n";

    // isto não é permitido e lança um TypeError:
    echo (("x menos um é igual a " . $x) - 1) . ", ou assim eu espero\n";
    ?>

O exemplo acima produzirá:

    -1, ou assim eu espero
    -1, ou assim eu espero
    Fatal error: Uncaught TypeError: Unsupported operand types: string - int

Exemplo #5 Antes do PHP 8, `+`, `-` e `.` tinham a mesma precedência

    <?php
    $x = 4;
    // this line might result in unexpected output:
    echo "x menos um é igual a " . $x-1 . ", ou assim eu espero\n";

    // porque é avaliada como esta linha (antes do PHP  8.0.0):
    echo (("x menos um é igual a " . $x) - 1) . ", ou assim eu espero\n";

    // a precedência desejada pode ser aplicada utilizando parênteses:
    echo "x menos um é igual a " . ($x-1) . ", ou assim eu espero\n";
    ?>

O exemplo acima produzirá:

    -1, ou assim eu espero
    -1, ou assim eu espero
    x menos um é igual a 3, ou assim eu espero

> Nota:

> Embora o `=` tenha uma precedência menor que a maioria dos operadores, o PHP ainda permite expressões similares a `if (!$a = foo())`, onde o valor retornado de `foo()` é colocado em $a.

> Isso é possível porque o lado esquerdo de uma atribuição deve ser uma variável, portanto a atribuição é agrupada com essa variável em vez de com o operador de prefixo de precedência superior circundante. O mesmo se aplica aos outros operadores de prefixo que recebem um operando de expressão, tal como `clone`, os operadores de conversão, `@` e `~`: por exemplo, `clone $a = $b` é agrupado como `clone ($a = $b)`, e não `(clone $a) = $b`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Concatenação de strings (`.`) tem uma precedência menor que adição/subtração (`+` e `-`) e shift de bits à esquerda/direita (`<<` e `>>`); anteriormente ele tinha a mesma precedência que `+` e `-` uma precedência maior que `<<` e `>>`.
8.0.0 | O operador ternário (`? :`) agora é não associativo; anteriormente associava a esquerda.
7.4.0 | Depender da precedência da concatenação de strings (`.`) em relação à adição/subtração (`+` ou `-`) ou shift de bits a esquerda/direta (`<<` ou `>>`), ou seja, os usar numa mesma expressão, foi descontinuado.
7.4.0 | Depender da associatividade à esquerda do operador ternário (`? :`), ou seja, o utilizar em várias expressões sem parênteses, foi descontinuado.

## Operadores Aritméticos

Lembra-se da aritmética básica da escola? Estes operadores funcionam exatamente como aqueles.

Operadores Aritméticos
Exemplo | Nome | Resultado
--- | --- | ---
`+$a` | Identidade | Conversão de $a para int ou float conforme apropriado.
`-$a` | Negativação | Oposto de $a.
`$a + $b` | Adição | Soma de $a e $b.
`$a - $b` | Subtração | Diferença entre $a e $b.
`$a * $b` | Multiplicação | Produto de $a e $b.
`$a / $b` | Divisão | Quociente de $a e $b.
`$a % $b` | Resto | Resto de $a dividido por $b.
`$a ** $b` | Exponenciação | Resultado de $a elevado à potência de $b.

O operador de divisão `/` retorna um valor float, a não ser que os dois operandos sejam int (ou strings numéricas que são convertidas para int) e o numerador seja um múltiplo do divisor, neste caso será retornado um valor inteiro. Para divisão de inteiros, consulte intdiv().

Operandos da operação de resto de divisão são convertidos para int antes do processamento. Para restos de divisão de números em ponto flutuante, veja fmod().

O resultado do operador de resto `%` tem o mesmo sinal do dividendo — ou seja, o resultado de `$a % $b` terá o mesmo sinal de $a. Exemplos:

Exemplo #1 O Operador de Resto

    <?php
    var_dump(5 % 3);
    var_dump(5 % -3);
    var_dump(-5 % 3);
    var_dump(-5 % -3);
    ?>

O exemplo acima produzirá:

    int(2)
    int(2)
    int(-2)
    int(-2)

### Veja Também

- Funções matemáticas

## Operadores de Incremento/Decremento

O PHP suporta operadores de pré e pós-incremento operadores de decremento. Esses operadores unários permitem aumentar o diminuir o valor por um.

Operadores de Incremento/Decremento
Exemplo | Nome | Efeito
--- | --- | ---
++$a | Pré-incremento | Incrementa $a em um, e então retorna $a.
$a++ | Pós-incremento | Retorna $a, e então incrementa $a em um.
--$a | Pré-decremento | Diminuiu $a em um, e então retorna $a.
$a-- | Pós-decremento | Retorna $a, e então diminui $a em um.

Exemplo #1 Exemplos de incremento/decremento

    <?php
    echo 'Pós-incremento:', PHP_EOL;
    $a = 5;
    var_dump($a++);
    var_dump($a);

    echo 'Pré-incremento:', PHP_EOL;
    $a = 5;
    var_dump(++$a);
    var_dump($a);

    echo 'Pós-incremento:', PHP_EOL;
    $a = 5;
    var_dump($a--);
    var_dump($a);

    echo 'Pré-decremento:', PHP_EOL;
    $a = 5;
    var_dump(--$a);
    var_dump($a);
    ?>

O exemplo acima produzirá:

    Pós-incremento:
    int(5)
    int(6)
    Pré-incremento:
    int(6)
    int(6)
    Pós-incremento:
    int(5)
    int(4)
    Pós-decremento:
    int(4)
    int(4)

Aviso

Os operadores de incremento e decremento não tem efeitos em valores do tipo bool. Um `E_WARNING` é emitido desde o PHP 8.3.0, porque isso causará uma conversão implícita para um tipo int no futuro.

O operador de decremento não tem efeito em valores do tipo null. Um `E_WARNING` é emitido desde o PHP 8.3.0, porque isso causará uma conversão implícita para um tipo int no futuro.

O operador de decremento não tem efeito em strings não numéricas. Um `E_WARNING` é emitido desde o PHP 8.3.0, porque isso lançará um TypeError no futuro.

> Nota:

> Objetos internos que suportam a sobrecarga de adição ou subtração também podem ser incrementados ou decrementados. Um exemplo de objeto assim é o GMP.

### Incremento de strings no estilo PERL

Aviso

Esse recurso está desencorajado desde o PHP 8.3.0. A função str_increment() deve ser utilizada.

É possível incremente strings não numéricas no PHP. A string precisa ser um texto ASCII. O efeito é incrementar a última letra até a próxima, e quando é alcançada a letra `Z` o incremento é carregado para a letra à esquerda. Por exemplo, `$a = 'Z'; $a++;` transforma $a em `'AA'`.

Exemplo #2 Exemplo de incremento de string estilo PERL

    <?php
    echo '== String alfabética ==' . PHP_EOL;
    $s = 'W';
    for ($n=0; $n<6; $n++) {
        echo ++$s . PHP_EOL;
    }
    // String alfanuméricas tem outro comportamento
    echo '== Strings alfanuméricas ==' . PHP_EOL;
    $d = 'A8';
    for ($n=0; $n<6; $n++) {
        echo ++$d . PHP_EOL;
    }
    $d = 'A08';
    for ($n=0; $n<6; $n++) {
        echo ++$d . PHP_EOL;
    }
    ?>

O exemplo acima produzirá:

    == String alfabética ==
    X
    Y
    Z
    AA
    AB
    AC
    == Strings alfanuméricas ==
    A9
    B0
    B1
    B2
    B3
    B4
    A09
    A10
    A11
    A12
    A13
    A14

Aviso

Se uma string alfanumérica pode ser interpretada como uma string numérica ela será convertida para um int ou float. Isso pode ser um problema para strings que parecem como números de ponto flutuante escritos em notação exponencial. A função str_increment() não sofre desse problema de conversão implícita.

Exemplo #3 Strings alfanuméricas convertida para float

    <?php
    $s = "5d9";
    var_dump(++$s);
    var_dump(++$s);
    ?>

O exemplo acima produzirá:

    string(3) "5e0"
    float(6)

Isto ocorre porque o valor `"5e0"` é interpretado como float e é convertido para o valor de `5.0` antes de ser incrementado.

## Operadores de Atribuição

O operador básico de atribuição é "=". A primeira inclinação seria pensar nisto como "é igual". Não é verdade. Isto quer dizer que o operando da esquerda recebe o valor da expressão da direita (ou seja, "é definido para").

O valor de uma expressão de atribuição é o valor atribuído. Ou seja, o valor de "`$a = 3`" é 3. Isto permite alguns truques:

Exemplo #1 Atribuições aninhadas

    <?php
    $a = ($b = 4) + 5; // $a é igual a 9 agora e $b foi definido como 4.
    var_dump($a);
    ?>

Além do operador básico de atribuição, há "operadores combinados" para todos os operadores aritméticos, de array e string que permitem a você pegar um valor de uma expressão e então usar seu próprio valor para o resultado daquela expressão. Por exemplo:

Exemplo #2 Atribuições combinadas

    <?php
    $a = 3;
    $a += 5; // define $a para 8, como se disséssemos: $a = $a + 5;
    $b = "Bom ";
    $b .= "Dia!"; // define $b para "Bom Dia!", como em $b = $b . "Dia!";

    var_dump($a, $b);
    ?>

Note que a atribuição copia a variável original para a nova (atribuição por valor), assim a mudança de uma não afeta a outra. Isto pode ser relevante se você precisa copiar algo como um grande array dentro de um loop apertado.

Uma exceção ao comportamento geral de atribuição ocorre com objects, que são atribuídos por referência. Objetos podem ser explicitamente copiados através da instrução clone.

### Atribuição por referência

Atribuição por referência também é possível, utilizando-se a sintaxe "$var = &$othervar;". A atribuição por referência significa que ambas as variáveis apontam para o mesmo dado, e nada é copiado.

Exemplo #3 Atribuição por referência

    <?php
    $a = 3;
    $b = &$a; // $b é uma referência de $a

    print "$a\n"; // imprime 3
    print "$b\n"; // imprime 3

    $a = 4; // modificamos $a

    print "$a\n"; // imprime 4
    print "$b\n"; // imprime 4 também, pois $b é uma referência de $a, que foi
                  // modificada
    ?>

O operador new retorna uma referência automaticamente, de forma que a atribuição de um resultado de new por referência é um erro.

Exemplo #4 Operador new por referência

    <?php
    class C {}

    $o = &new C;
    ?>

O exemplo acima produzirá:

    Parse error: syntax error, unexpected token ";", expecting "("

Mais informações sobre referências e seus potenciais usos podem ser encontrados na seção Explicando Referências do manual.

### Arithmetic Assignment Operators

Exemplo | Equivalente | Operação
--- | --- | ---
$a += $b | $a = $a + $b | Adição
$a -= $b | $a = $a - $b | Subtração
$a *= $b | $a = $a * $b | Multiplicação
$a /= $b | $a = $a / $b | Divisão
$a %= $b | $a = $a % $b | Módulo
$a **= $b | $a = $a ** $b | Exponentiation

### Operadores de bits

Exemplo | Equivalente | Operação
--- | --- | ---
$a &= $b | $a = $a & $b | Bitwise E
$a |= $b | $a = $a | $b | Bitwise Ou
$a ^= $b | $a = $a ^ $b | Bitwise Xor
$a <<= $b | $a = $a << $b | Desloca para esquerda
$a >>= $b | $a = $a >> $b | Desloca para direita

### Outras operações de assimilação

Exemplo | Equivalente | Operação
--- | --- | ---
$a .= $b | $a = $a . $b | Concatenação de strings
$a ??= $b | $a = $a ?? $b | Aglutinação de nulls (null coalesce)

### Veja Também

- operadores aritméticos
- operadores em bits
- operador de aglutinação de null

## Operadores Binários

Operadores binários permitem a avaliação e modificação de bits específicos em um tipo inteiro.

Operadores binários
Exemplo | Nome | Resultado
--- | --- | ---
`$a & $b` | E (AND) | Os bits que estão ativos tanto em $a quanto em $b são ativados.
`$a | $b` | OU (OR inclusivo) | Os bits que estão ativos em $a ou em $b são ativados.
`$a ^ $b` | XOR (OR exclusivo) | Os bits que estão ativos em $a ou em $b, mas não em ambos, são ativados.
`~ $a` | NÃO (NOT) | Os bits que estão ativos em $a não são ativados, e vice-versa.
`$a << $b` | Deslocamento à esquerda | Desloca os bits de $a em $b passos para a esquerda (cada passo significa "multiplica por dois")
`$a >> $b` | Deslocamento à direita | Desloca os bits de $a em $b passos para a direita (cada passo significa "divide por dois")

O deslocamento de bits no PHP é aritmético. Bits deslocados no lado final são descartados. Deslocamentos à esquerda tem zeros inseridos à direita e o bit de sinal é perdido, e assim o sinal do operando não é preservado. Deslocamentos à direita têm cópias do bit de sinal à esquerda, e assim o sinal do operando é preservado.

Utilize parênteses para garantir a precedência desejada. Por exemplo `$a & $b == true` avalia primeiro a equivalência e depois a operação de bits, enquanto que `($a & $b) == true` avalia primeiro a operação de bits e só depois a equivalência.

Se ambos os operandos de `&`, `|` e `^` forem strings então a operação será realizada nos valores ASCII dos caracteres das strings, e o resultado final será uma string. Em todos os outros casos ambos os operandos serão convertidos para inteiros e o resultado será um inteiro.

Se o operando de `~` for uma string então a operação será realizada nos valores ASCII dos caracteres da string, e o resultado será uma string. Nos demais casos o operando e o resultado serão tratados como inteiros.

Ambos os operandos e o resultado para `<<` e `>>` sempre são tratados como inteiros.

A configuração error_reporting ini utiliza valores posicionados em bits, fornecendo um exemplo real de ligar ou desligar bits. Para mostrar todos os erros mas não os alertas coloque no php.ini: `E_ALL & ~E_NOTICE`

         Isto funciona pois começa com E_ALL:
         00000000000000000111011111111111
         Depois pegando o valor de E_NOTICE...
         00000000000000000000000000001000
         ... que invertido através de ~:
         11111111111111111111111111110111
         ... é finalmente mesclado via E (&) e assim o valor final
         se torna:
         00000000000000000111011111110111

Outra forma de conseguir esse efeito seria através do XOR (`^`) para encontrar os bits que estão ativos em apenas um ou no outro: `E_ALL ^ E_NOTICE`

O error_reporting pode também ser utilizado para demonstrar a ativação de bits. Para mostrar apenas erros e erros recuperáveis: `E_ERROR | E_RECOVERABLE_ERROR`

         Este processo combina E_ERROR
         00000000000000000000000000000001
         e
         00000000000000000001000000000000
         utilizando OU (|)
         para pegar os bits ativos de ambos os valores:
         00000000000000000001000000000001

Exemplo #1 Operações bitwise AND, OR e XOR em inteiros

    <?php
    /*
     * Ignore essa primeira parte,
     * que é apenas para deixar a impressão mais limpa.
     */

    $format = '(%1$2d = %1$04b) = (%2$2d = %2$04b)'
            . ' %3$s (%4$2d = %4$04b)' . "\n";

    echo <<<EOH
     ---------     ---------  -- ---------
     resultado     valor      op teste
     ---------     ---------  -- ---------
    EOH;

    /*
     * Agora os exemplos
     */

    $values = array(0, 1, 2, 4, 8);
    $test = 1 + 4;

    echo "\n Operador de bit E \n";
    foreach ($values as $value) {
        $result = $value & $test;
        printf($format, $result, $value, '&', $test);
    }

    echo "\n Operador de bit OU inclusivo \n";
    foreach ($values as $value) {
        $result = $value | $test;
        printf($format, $result, $value, '|', $test);
    }

    echo "\n Operador de bit OU Exclusivo (XOR) \n";
    foreach ($values as $value) {
        $result = $value ^ $test;
        printf($format, $result, $value, '^', $test);
    }
    ?>

O exemplo acima produzirá:

     ---------     ---------  -- ---------
     resultado     valor      op teste
     ---------     ---------  -- ---------
     Operador de bit E
    ( 0 = 0000) = ( 0 = 0000) & ( 5 = 0101)
    ( 1 = 0001) = ( 1 = 0001) & ( 5 = 0101)
    ( 0 = 0000) = ( 2 = 0010) & ( 5 = 0101)
    ( 4 = 0100) = ( 4 = 0100) & ( 5 = 0101)
    ( 0 = 0000) = ( 8 = 1000) & ( 5 = 0101)

     Operador de bit OU inclusivo
    ( 5 = 0101) = ( 0 = 0000) | ( 5 = 0101)
    ( 5 = 0101) = ( 1 = 0001) | ( 5 = 0101)
    ( 7 = 0111) = ( 2 = 0010) | ( 5 = 0101)
    ( 5 = 0101) = ( 4 = 0100) | ( 5 = 0101)
    (13 = 1101) = ( 8 = 1000) | ( 5 = 0101)

     Operador de bit OU exclusivo (XOR)
    ( 5 = 0101) = ( 0 = 0000) ^ ( 5 = 0101)
    ( 4 = 0100) = ( 1 = 0001) ^ ( 5 = 0101)
    ( 7 = 0111) = ( 2 = 0010) ^ ( 5 = 0101)
    ( 1 = 0001) = ( 4 = 0100) ^ ( 5 = 0101)
    (13 = 1101) = ( 8 = 1000) ^ ( 5 = 0101)

Exemplo #2 Operações de bit XOR em strings

    <?php
    echo 12 ^ 9, PHP_EOL; // Exibe '5'

    echo "12" ^ "9", PHP_EOL; // Exibe caractere backspace (ASCII 8)
                              // ('1' (ASCII 49)) ^ ('9' (ASCII 57)) = #8

    echo "hallo" ^ "hello";, PHP_EOL // Exibe os valores ASCII #0 #4 #0 #0 #0
                                     // 'a' ^ 'e' = #4

    echo 2 ^ "3", PHP_EOL; // Exibe 1
                           // 2 ^ ((int) "3") == 1

    echo "2" ^ 3, PHP_EOL; // Exibe 1
                           // ((int) "2") ^ 3 == 1
    ?>

Exemplo #3 Deslocamento de bits em inteiros

    <?php
    /*
     * Aqui estão os exemplos.
     */

    echo "\n--- MOVENDO BITS A DIREITA EM INTEIROS POSITIVOS ---\n";

    $val = 4;
    $places = 1;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'cópia do bit de sinal trocada para a esquerda');

    $val = 4;
    $places = 2;
    $res = $val >> $places;
    p($res, $val, '>>', $places);

    $val = 4;
    $places = 3;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'move os bits para fora da direita');

    $val = 4;
    $places = 4;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'mesmo resultado que acima; não se pode mover além do 0');

    echo "\n--- MOVENDO BITS A DIREITA EM INTEIROS NEGATIVOS ---\n";

    $val = -4;
    $places = 1;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'cópia do bit de sinal trocada para a esquerda');

    $val = -4;
    $places = 2;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'move os bits para fora da direita');

    $val = -4;
    $places = 3;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'mesmo resultado que acima; não se pode mover além do -1');

    echo "\n--- MOVENDO BITS A ESQUERDA EM INTEIROS POSITIVOS ---\n";

    $val = 4;
    $places = 1;
    $res = $val << $places;
    p($res, $val, '<<', $places, 'preenche com zeros o lado direito');

    $val = 4;
    $places = (PHP_INT_SIZE * 8) - 4;
    $res = $val << $places;
    p($res, $val, '<<', $places);

    $val = 4;
    $places = (PHP_INT_SIZE * 8) - 3;
    $res = $val << $places;
    p($res, $val, '<<', $places, 'bit de sinal movido para fora');

    $val = 4;
    $places = (PHP_INT_SIZE * 8) - 2;
    $res = $val << $places;
    p($res, $val, '<<', $places, 'bits movidos para fora da esquerda');

    echo "\n--- MOVENDO BITS A ESQUERDA EM INTEIROS NEGATIVOS ---\n";

    $val = -4;
    $places = 1;
    $res = $val << $places;
    p($res, $val, '<<', $places, 'preenche com zeros o lado direito');

    $val = -4;
    $places = (PHP_INT_SIZE * 8) - 3;
    $res = $val << $places;
    p($res, $val, '<<', $places);

    $val = -4;
    $places = (PHP_INT_SIZE * 8) - 2;
    $res = $val << $places;
    p($res, $val, '<<', $places, 'bits movidos para fora pela esquerda, incluindo o bit de sinal');

    /*
     * Ignore essa seção abaixo,
     * é apenas para formatar a saída e deixar mais clara a apresentação.
     */

    function p($res, $val, $op, $places, $note = '') {
        $format = '%0' . (PHP_INT_SIZE * 8) . "b\n";

        printf("Expressão: %d = %d %s %d\n", $res, $val, $op, $places);

        echo " Decimal:\n";
        printf("  val=%d\n", $val);
        printf("  res=%d\n", $res);

        echo " Binário:\n";
        printf('  val=' . $format, $val);
        printf('  res=' . $format, $res);

        if ($note) {
            echo " NOTA: $note\n";
        }

        echo "\n\n";
    }
    ?>

Saída do exemplo acima em máquinas de 32 bits:

    --- MOVENDO BITS A DIREITA EM INTEIROS POSITIVOS ---
    Expressão: 2 = 4 >> 1
     Decimal:
      val=4
      res=2
     Binário:
      val=00000000000000000000000000000100
      res=00000000000000000000000000000010
     NOTA: cópia do bit de sinal trocada para a esquerda

    Expressão: 1 = 4 >> 2
     Decimal:
      val=4
      res=1
     Binário:
      val=00000000000000000000000000000100
      res=00000000000000000000000000000001

    Expressão: 0 = 4 >> 3
     Decimal:
      val=4
      res=0
     Binário:
      val=00000000000000000000000000000100
      res=00000000000000000000000000000000
     NOTA: move os bits para fora da direita

    Expressão: 0 = 4 >> 4
     Decimal:
      val=4
      res=0
     Binário:
      val=00000000000000000000000000000100
      res=00000000000000000000000000000000
     NOTA: mesmo resultado que acima; não se pode mover além do 0

    --- MOVENDO BITS A DIREITA EM INTEIROS NEGATIVOS ---
    Expressão: -2 = -4 >> 1
     Decimal:
      val=-4
      res=-2
     Binário:
      val=11111111111111111111111111111100
      res=11111111111111111111111111111110
     NOTA: cópia do bit de sinal trocada para a esquerda

    Expressão: -1 = -4 >> 2
     Decimal:
      val=-4
      res=-1
     Binário:
      val=11111111111111111111111111111100
      res=11111111111111111111111111111111
     NOTA: move os bits para fora da direita

    Expressão: -1 = -4 >> 3
     Decimal:
      val=-4
      res=-1
     Binário:
      val=11111111111111111111111111111100
      res=11111111111111111111111111111111
     NOTA: mesmo resultado que acima; não se pode mover além do -1

    --- MOVENDO BITS A ESQUERDA EM INTEIROS POSITIVOS ---
    Expressão: 8 = 4 << 1
     Decimal:
      val=4
      res=8
     Binário:
      val=00000000000000000000000000000100
      res=00000000000000000000000000001000
     NOTA: preenche com zeros o lado direito

    Expressão: 1073741824 = 4 << 28
     Decimal:
      val=4
      res=1073741824
     Binário:
      val=00000000000000000000000000000100
      res=01000000000000000000000000000000

    Expressão: -2147483648 = 4 << 29
     Decimal:
      val=4
      res=-2147483648
     Binário:
      val=00000000000000000000000000000100
      res=10000000000000000000000000000000
     NOTA: bit de sinal movido para fora

    Expressão: 0 = 4 << 30
     Decimal:
      val=4
      res=0
     Binário:
      val=00000000000000000000000000000100
      res=00000000000000000000000000000000
     NOTA: bits movidos para fora da esquerda

    --- MOVENDO BITS A ESQUERDA EM INTEIROS NEGATIVOS ---
    Expressão: -8 = -4 << 1
     Decimal:
      val=-4
      res=-8
     Binário:
      val=11111111111111111111111111111100
      res=11111111111111111111111111111000
     NOTA: preenche com zeros o lado direito

    Expressão: -2147483648 = -4 << 29
     Decimal:
      val=-4
      res=-2147483648
     Binário:
      val=11111111111111111111111111111100
      res=10000000000000000000000000000000

    Expressão: 0 = -4 << 30
     Decimal:
      val=-4
      res=0
     Binário:
      val=11111111111111111111111111111100
      res=00000000000000000000000000000000
     NOTA: bits movidos para fora pela esquerda, incluindo o bit de sinal

Saída do exemplo acima em máquinas de 64 bits:

    --- MOVENDO BITS A DIREITA EM INTEIROS POSITIVOS ---
    Expressão: 2 = 4 >> 1
     Decimal:
      val=4
      res=2
     Binário:
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000000010
     NOTA: cópia do bit de sinal trocada para a esquerda

    Expressão: 1 = 4 >> 2
     Decimal:
      val=4
      res=1
     Binário:
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000000001

    Expressão: 0 = 4 >> 3
     Decimal:
      val=4
      res=0
     Binário:
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000000000
     NOTA: move os bits para fora da direita

    Expressão: 0 = 4 >> 4
     Decimal:
      val=4
      res=0
     Binário:
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000000000
     NOTA: mesmo resultado que acima; não se pode mover além do 0

    --- MOVENDO BITS A DIREITA EM INTEIROS NEGATIVOS ---
    Expressão: -2 = -4 >> 1
     Decimal:
      val=-4
      res=-2
     Binário:
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=1111111111111111111111111111111111111111111111111111111111111110
     NOTA: cópia do bit de sinal trocada para a esquerda

    Expressão: -1 = -4 >> 2
     Decimal:
      val=-4
      res=-1
     Binário:
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=1111111111111111111111111111111111111111111111111111111111111111
     NOTA: move os bits para fora da direita

    Expressão: -1 = -4 >> 3
     Decimal:
      val=-4
      res=-1
     Binário:
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=1111111111111111111111111111111111111111111111111111111111111111
     NOTA: mesmo resultado que acima; não se pode mover além do -1

    --- MOVENDO BITS A ESQUERDA EM INTEIROS POSITIVOS ---
    Expressão: 8 = 4 << 1
     Decimal:
      val=4
      res=8
     Binário:
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000001000
     NOTA: preenche com zeros o lado direito

    Expressão: 4611686018427387904 = 4 << 60
     Decimal:
      val=4
      res=4611686018427387904
     Binário:
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0100000000000000000000000000000000000000000000000000000000000000

    Expressão: -9223372036854775808 = 4 << 61
     Decimal:
      val=4
      res=-9223372036854775808
     Binário:
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=1000000000000000000000000000000000000000000000000000000000000000
     NOTA: bit de sinal movido para fora

    Expressão: 0 = 4 << 62
     Decimal:
      val=4
      res=0
     Binário:
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000000000
     NOTA: bits movidos para fora da esquerda

    --- MOVENDO BITS A ESQUERDA EM INTEIROS NEGATIVOS ---
    Expressão: -8 = -4 << 1
     Decimal:
      val=-4
      res=-8
     Binário:
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=1111111111111111111111111111111111111111111111111111111111111000
     NOTA: preenche com zeros o lado direito

    Expressão: -9223372036854775808 = -4 << 61
     Decimal:
      val=-4
      res=-9223372036854775808
     Binário:
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=1000000000000000000000000000000000000000000000000000000000000000

    Expressão: 0 = -4 << 62
     Decimal:
      val=-4
      res=0
     Binário:
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=0000000000000000000000000000000000000000000000000000000000000000
     NOTA: bits movidos para fora pela esquerda, incluindo o bit de sinal

Aviso

Utilize as funções da extensão gmp para manipulações de troca de bit em números maiores que `PHP_INT_MAX`.

### Veja Também

- pack()
- unpack()
- gmp_and()
- gmp_or()
- gmp_xor()
- gmp_testbit()
- gmp_clrbit()

## Operadores de Comparação

Operadores de comparação, como os seus nomes implicam, permitem que você compare dois valores. Você pode se interessar em ver as tabelas de comparação de tipos, que tem exemplo das várias comparações entre tipos relacionadas.

Operadores de comparação
Exemplo | Nome | Resultado
--- | --- | ---
$a == $b | Igual | `true` se $a é igual a $b após equalização de tipos.
$a === $b | Idêntico | `true` se $a é igual a $b, e eles são do mesmo tipo.
$a != $b | Diferente | `true` se $a não é igual a $b depois de equalização de ativos.
$a <> $b | Diferente | `true` se $a não é igual a $b depois de equalização de ativos.
$a !== $b | Não idêntico | `true` se $a não é igual a $b, ou eles não são do mesmo tipo.
$a < $b | Menor que | `true` se $a é estritamente menor que $b.
$a > $b | Maior que | `true` se $a é estritamente maior que $b.
$a <= $b | Menor ou igual | `true` se $a é menor ou igual a $b.
$a >= $b | Maior ou igual | `true` se $a é maior ou igual a $b.
$a <=> $b | Spaceship (nave espacial) | Um int menor que, igual a ou maior que zero quando $a é, respectivamente, menor que, igual a ou maior que $b.

Se ambos os operadores são strings numéricas, ou um operando é um número e o outro é uma string numérica, então a comparação é realizada numericamente. Estas regras se aplicam à instrução switch. A conversão de tipos não é realizada quando a comparação é realizada através `===` ou `!==` porque aqui é realizada a comparação de tipos, além de valores.

Aviso

Anteriormente ao PHP 8.0.0, se uma string era comparada a um número ou uma string numérica, então a string era convertida para número antes de realizar a comparação. Isto pode levar a resultados inesperados, como observado no exemplo a seguir:

    <?php
    var_dump(0 == "a");
    var_dump("1" == "01");
    var_dump("10" == "1e1");
    var_dump(100 == "1e2");

    switch ("a") {
    case 0:
        echo "0";
        break;
    case "a":
        echo "a";
        break;
    }
    ?>

Saída do exemplo acima no PHP 7:

    bool(true)
    bool(true)
    bool(true)
    bool(true)
    0

Saída do exemplo acima no PHP 8:

    bool(false)
    bool(true)
    bool(true)
    bool(true)
    a

Exemplo #1 Operadores de Comparação

    <?php
    // Inteiros
    echo 1 <=> 1, ' '; // 0
    echo 1 <=> 2, ' '; // -1
    echo 2 <=> 1, ' '; // 1

    // Floats
    echo 1.5 <=> 1.5, ' '; // 0
    echo 1.5 <=> 2.5, ' '; // -1
    echo 2.5 <=> 1.5, ' '; // 1

    // Strings
    echo "a" <=> "a", ' '; // 0
    echo "a" <=> "b", ' '; // -1
    echo "b" <=> "a", ' '; // 1

    echo "a" <=> "aa", ' ';  // -1
    echo "zz" <=> "aa", ' '; // 1

    // Arrays
    echo [] <=> [], ' ';               // 0
    echo [1, 2, 3] <=> [1, 2, 3], ' '; // 0
    echo [1, 2, 3] <=> [], ' ';        // 1
    echo [1, 2, 3] <=> [1, 2, 1], ' '; // 1
    echo [1, 2, 3] <=> [1, 2, 4], ' '; // -1

    // Objetos
    $a = (object) ["a" => "b"];
    $b = (object) ["a" => "b"];
    echo $a <=> $b, ' '; // 0

    $a = (object) ["a" => "b"];
    $b = (object) ["a" => "c"];
    echo $a <=> $b, ' '; // -1

    $a = (object) ["a" => "c"];
    $b = (object) ["a" => "b"];
    echo $a <=> $b, ' '; // 1

    // valores e tipos precisam coincidir
    $a = (object) ["a" => "b"];
    $b = (object) ["b" => "b"];
    echo $a <=> $b, ' '; // 1

    ?>

Para vários tipos, comparações são feitas de acordo com a seguinte tabela (em ordem).

Comparação com vários tipos
Tipo do 1º operando | Tipo do 2º operando | Resultado
--- | --- | ---
null ou string | string | Converte `null` para "", numérico ou comparação léxica
bool ou null | qualquer | Converte para bool, `false` < `true`
object | object | Classes nativas podem definir suas próprias comparações, classes diferentes são incomparáveis, same class see Comparação de Objetos
string, resource, int ou float | string, resource, int ou float | Transforma strings e resources para números
array | array | Array com menos membros é menor, se a chave do operando 1 não é encontrada no operando 2, então os arrays são incomparáveis, caso contrário compara valor por valor (veja o seguinte exemplo)
object | qualquer | object é sempre maior
array | qualquer | array é sempre maior

Exemplo #2 Comparações de boolean e null

    <?php
    // bool e null são sempre comparados como booleanos
    var_dump(1 == TRUE);  // TRUE - o mesmo que (bool) 1 == TRUE
    var_dump(0 == FALSE); // TRUE - o mesmo que (bool) 0 == FALSE
    var_dump(100 < TRUE); // FALSE - o mesmo que (bool) 100 < TRUE
    var_dump(-10 < FALSE);// FALSE - o mesmo que (bool) -10 < FALSE
    var_dump(min(-100, -10, NULL, 10, 100)); // NULL - (bool) NULL < (bool) -100 é FALSE < TRUE
    ?>

Exemplo #3 Transcrição do padrão de comparação de array

    <?php
    // Arrays são comparados assim quando utilizando-se os operadores padrão e operador nave-espacial
    function standard_array_compare($op1, $op2)
    {
        if (count($op1) < count($op2)) {
            return -1; // $op1 < $op2
        } elseif (count($op1) > count($op2)) {
            return 1; // $op1 > $op2
        }
        foreach ($op1 as $key => $val) {
            if (!array_key_exists($key, $op2)) {
                return 1;
            } elseif ($val < $op2[$key]) {
                return -1;
            } elseif ($val > $op2[$key]) {
                return 1;
            }
        }
        return 0; // $op1 == $op2
    }
    ?>

Aviso

# Comparison of floating point numbers

Por conta da forma que floats são representados internamente não se deve testar dois floats com o comparador de igualdade.

Veja a documentação de float para mais detalhes.

> Nota: Cuidado. A conversão automática de tipos do PHP não é sempre tão óbvia, quando comparando valores de tipos diferentes, particularmente comparando ints para bools ou ints para strings. No geral é recomendado utilizar as comparações `===` e `!==` em vez de utilizar `==` e `!=` na maioria dos casos.

### Valores não comparáveis

Embora a comparação de identidade (`===` e `!==`) possa ser aplicada para valores arbitrários, os outros operadores de comparação somente devem ser aplicados a valores comparáveis. O resultado de comparação de valores não comparáveis não é definido, e não pode ser garantido.

### Veja Também

- strcasecmp()
- strcmp()
- Array operators
- Types

### Operador Ternário

Outro operador condicional é o operador "?:" (ou ternário).

Exemplo #4 Atribuindo um valor padrão

    <?php
    // Example usage for: Ternary Operator
    $action = (empty($_POST['action'])) ? 'default' : $_POST['action'];

    // O código acima é idêntico a esta instrução if/else
    if (empty($_POST['action'])) {
        $action = 'default';
    } else {
        $action = $_POST['action'];
    }
    ?>

A expressão `(expr1) ? (expr2) : (expr3)` é avaliada para expr2 se expr1 é avaliada como `true`, ou expr3 se expr1 é avaliada como `false`.

É possível deixar vazia a parte central do operador ternário. A expressão `expr1 ?: expr3` retorna o resultado de expr1 se expr1 avaliar para `true`, e expr3 se não. expr1 somente é avaliada nessa única situação.

> Nota: Note que o operador ternário é uma expressão, e ele não é avaliado para uma variável, mas para o resultado de uma expressão. Isto é importante saber se você quer retornar uma variável por referência. A declaração `return $var == 42 ? $a : $b;` em uma função que retorna por referência conseqüêntemente não irá funcionar e será avisado.

> Nota:

> É recomendado evitar empilhar operadores ternários. O comportamento do PHP quando utilizando mais de um operador ternário sem parênteses numa única expressão é menos óbvia, comparada a outras linguagens. Antes do PHP 8.0.0, os operadores ternários eram avaliados com associatividade à esquerda, em vez de associatividade à direita, como na maioria de outras linguagens. Depender da associatividade à esquerda foi descontinuado a partir do PHP 7.4.0. A partir do PHP 8.0.0, o operador ternário é não associativo.

> Exemplo #5 Comportamento não óbvio do ternário

>     <?php
>     // Pode parecer que a expressão a seguir imprime 'true'
>     echo (true ? 'true' : false ? 't' : 'f');

>     // No entanto, a saída é na verdade 't' antes do PHP 8.0.0
>     // Isto ocorre porque operadores ternários são associativos à esquerda

>     // O seguinte é a versão mais intuitiva do código acima
>     echo ((true ? 'true' : false) ? 't' : 'f');

>     // Aqui, é possível ver que a primeira expressão avalia para 'true', e então
>     // é avaliada para (bool) true, e portanto retorna o variante true da
>     // segunda expressão ternária
>     ?>

> Nota:

> Encadeamento de ternários curtos (`?:`), é estável, e comporta-se intuitivamente. Ele avaliará como o primeiro argumento que avalia para uma valor não falso. Observe que valores não definidos irão emitir um alerta.

> Exemplo #6 Encadeamento de ternários curtos

>     <?php
>     echo 0 ?: 1 ?: 2 ?: 3, PHP_EOL; //1
>     echo 0 ?: 0 ?: 2 ?: 3, PHP_EOL; //2
>     echo 0 ?: 0 ?: 0 ?: 3, PHP_EOL; //3
>     ?>

### Operador de aglutinação null (Null Coalescing)

Existe ainda o operador "??" (ou null coalescing).

Exemplo #7 Atribuindo um valor padrão

    <?php
    // Exemplo do operador Null Coalesce
    $action = $_POST['action'] ?? 'default';

    // O conteúdo acima é idêntico à essa declaração if/else
    if (isset($_POST['action'])) {
        $action = $_POST['action'];
    } else {
        $action = 'default';
    }
    ?>

A expressão `(expr1) ?? (expr2)` é avaliada para expr2 se expr1 for `null`, e expr1 do contrário.

Esse operador em particular não emite aviso caso o valor da esquerda não exista, assim como isset(). Sendo especialmente útil em chaves de arrays.

> Nota: Note que o operador null coalescing é uma expressão, e ele não é avaliado para uma variável, mas para o resultado de uma expressão. Isto é importante saber se você quer retornar uma variável por referência. A declaração `return $foo ?? $bar;` em uma função que retorna por referência conseqüêntemente não irá funcionar e será avisado.

> Nota:

> O operador de aglutinação null tem baixa precedência. Isso significa que misturá-lo com outros operadores (como por exemplo concatenação ou aritmética) irá provavelmente exigir parênteses.

>     <?php
>     // Emite um aviso que $name não está definido.
>     print 'Mr. ' . $name ?? 'Anonymous';

>     // Exibe "Mr. Anonymous"
>     print 'Mr. ' . ($name ?? 'Anonymous');
>     ?>

> Nota:

> Note que o operador null coalescing permite a criação de aninhamentos simples:

> Exemplo #8 Aninhando o operador null coalescing

>     <?php

>     $foo = null;
>     $bar = null;
>     $baz = 1;
>     $qux = 2;

>     echo $foo ?? $bar ?? $baz ?? $qux; // exibe 1

>     ?>

## Operadores de Controle de Erro

O PHP suporta um operador de controle de erro: o sinal 'arroba' (`@`). Quando ele precede uma expressão em PHP, qualquer mensagem de erro que possa ser gerada por aquela expressão será ignorada.

Se um manipulador de erro personalizado estiver configurado com set_error_handler(), ele ainda assim será chamado, mesmo com a mensagem de diagnóstico suprimida.

Aviso

Antes do PHP 8.0.0, error_reporting() chamada dentro de um manipulador de erro sempre retornava `0` se a mensagem de erro era suprimida pelo operador `@`. Desde o PHP 8.0.0, ele retorna o valor da expressão bitwise dos valores: `E_ERROR | E_CORE_ERROR | E_COMPILE_ERROR | E_USER_ERROR | E_RECOVERABLE_ERROR | E_PARSE`.

Quaisquer mensagens de erro geradas na expressão ficam disponíveis no elemento `"message"` do array retornado por error_get_last(). O resultado daquela função irá se alterar em cada erro, então é necessário fazer a verificação imediatamente.

Exemplo #1 Erro de arquivo intencional

    <?php
    $my_file = @file ('arquivo_nao_existente') or
        die ("Falha abrindo arquivo: erro foi '" . error_get_last()['message'] . "'");
    ?>

Exemplo #2 Suprimindo expressões

    <?php
    // Isto funciona para qualquer expressão, não apenas para funções:
    $value = @$cache[$key];
    // não haverá nenhum aviso se a chave $key não existir.
    ?>

> Nota: O operador `@` funciona somente em expressões. Uma regra simples para lembrar disso: se você pode pegar o valor de alguma coisa, você pode prefixar isso com o operador `@`. Por exemplo, ele pode prefixar variáveis, chamadas de funções, alguns constructos de linguagem (include), e assim por diante. O operador não pode ser prefixado em definições de classes ou funções, estruturas condicionais como `if`, `foreach`, e semelhantes.

Aviso

Antes do PHP 8.0.0, o operador `@` conseguia inibir erros críticos que iriam encerrar a execução do script. Por exemplo, prefixar `@` numa chamada de uma função inexistente, por estar indisponível ou por erro de digitação, iria encerrar o script sem nenhuma indicação da causa.

### Veja Também

- error_reporting()
- Manipulação de erros e funções de log

## Operadores de Execução

O PHP suporta um operador de execução: acentos graves (````). Note que não são aspas simples! O PHP tentará executar o conteúdo dentro dos acentos graves como um comando do shell; a saída será retornada (isto é, ela não será simplesmente mostrada na tela; ela pode ser atribuída a uma variável). A utilização do operador de execução é idêntica a da função shell_exec().

Exemplo #1 Operador de execução

    <?php
    $output = `ls -al`;
    echo "<pre>$output</pre>";
    ?>

> Nota:

> O operador de execução fica desabilitado quando shell_exec() está desabilitado.

> Nota:

> Ao contrário de outras linguagens, acentos graves não têm sentido especial dentro de strings delimitadas por aspas.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | O operador de execução como um sinônimo para shell_exec() foi descontinuado.

### Veja Também

- Funções de execução de programas
- popen()
- proc_open()
- Utilizando o PHP em linha de comando

## Operadores Lógicos

Operadores Lógicos
Exemplo | Nome | Resultado
--- | --- | ---
$a and $b | E | `true` se ambos $a e $b são `true`.
$a or $b | OU | `true` se $a ou $b é `true`.
$a xor $b | XOR | `true` se $a ou $b é `true`, mas não ambos ao mesmo tempo.
! $a | Não | `true` se $a não é `true`.
$a && $b | E | `true` se ambos $a e $b são `true`.
$a || $b | OU | `true` se $a ou $b é `true`.

A razão para as duas variantes dos operandos "and" e "or" é que eles operam com precedências diferentes. (Veja Precedência de Operadores.)

Exemplo #1 Ilustrando operadores lógicos

    <?php

    // --------------------
    // foo() nunca será chamada porque toda a expressão sofre curto circuito

    $a = (false && foo());
    $b = (true  || foo());
    $c = (false and foo());
    $d = (true  or  foo());

    // --------------------
    // "||" tem maior precedência que "or"

    // O resultado da expressão (false || true) é atribuído em $e
    // Funciona como: ($e = (false || true))
    $e = false || true;

    // A constante false é atribuída a $f antes que o "or" ocorra
    // Funciona como: (($f = false) or true)
    $f = false or true;

    var_dump($e, $f);

    // --------------------
    // "&&" tem maior precedência que "and"

    // O resultado da expressão (true && false) é atribuído em $g
    // Funciona como: ($g = (true && false))
    $g = true && false;

    // A constante true é atribuída em $h antes que o "and" ocorra
    // Funciona como: (($h = true) and false)
    $h = true and false;

    var_dump($g, $h);
    ?>

O exemplo acima produzirá algo semelhante a:

    bool(true)
    bool(false)
    bool(false)
    bool(true)

## Operadores de String

Há dois operadores de string. O primeiro é o operador de concatenação ('.'), que retorna a concatenação dos seus argumentos direito e esquerdo. O segundo é o operador de atribuição de concatenação ('`.=`'), que acrescenta o argumento do lado direito no argumento do lado esquerdo. Veja em Operadores de Atribuição para mais informações.

Exemplo #1 Concatenação de strings

    <?php
    $a = "Olá ";
    $b = $a . "mundo!"; // agora $b contém "Olá mundo!"
    var_dump($b);

    $a = "Olá ";
    $a .= "mundo!";     // agora $a contém "Olá mundo!"
    var_dump($a);
    ?>

### Veja Também

- Tipo string
- Funções string

## Operadores de Arrays

Operadores de array
Exemplo | Nome | Resultado
--- | --- | ---
$a + $b | União | União de $a e $b.
$a == $b | Igualdade | `true` se $a e $b têm as mesmas chaves e valores.
$a === $b | Identidade | `true` se $a e $b têm as mesmas chaves e valores, na mesma ordem e com os mesmos tipos.
$a != $b | Desigualdade | `true` se $a não é igual $b.
$a <> $b | Desigualdade | `true` se $a não é igual $b.
$a !== $b | Não identidade | `true` se $a não é idêntico a $b.

O operador `+` retorna o array à direita anexado ao array da esquerda. Para chaves que existam nos dois arrays os elementos do array à esquerda serão mantidos, os valores de mesma chave no array da direita são ignorados.

Exemplo #1 Operador de união de array

    <?php
    $a = array("a" => "apple", "b" => "banana");
    $b = array("a" => "pear", "b" => "strawberry", "c" => "cherry");

    $c = $a + $b; // União de $a e $b
    echo "União de \$a e \$b: \n";
    var_dump($c);

    $c = $b + $a; // União de $b e $a
    echo "União de \$b e \$a: \n";
    var_dump($c);

    $a += $b; // União de $a += $b é $a e $b
    echo "União de \$a += \$b: \n";
    var_dump($a);
    ?>

O exemplo acima produzirá:

    União de $a e $b:
    array(3) {
      ["a"]=>
      string(5) "apple"
      ["b"]=>
      string(6) "banana"
      ["c"]=>
      string(6) "cherry"
    }
    União de $b e $a:
    array(3) {
      ["a"]=>
      string(4) "pear"
      ["b"]=>
      string(10) "strawberry"
      ["c"]=>
      string(6) "cherry"
    }
    União de $a += $b:
    array(3) {
      ["a"]=>
      string(5) "apple"
      ["b"]=>
      string(6) "banana"
      ["c"]=>
      string(6) "cherry"
    }

Elementos do array são iguais para efeitos de comparação se eles possuem o mesmo valor e chave.

Exemplo #2 Comparando arrays

    <?php
    $a = array("maçã", "banana");
    $b = array(1 => "banana", "0" => "maçã");

    var_dump($a == $b); // bool(true)
    var_dump($a === $b); // bool(false)
    ?>

### Veja Também

- Tipo array
- Funções em arrays

## Operadores de Tipo

`instanceof` é usado para determinar se um variável do PHP é uma objeto instanciado de uma certa classe:

Exemplo #1 Usando `instanceof` com classes

    <?php
    class MyClass
    {
    }

    class NotMyClass
    {
    }
    $a = new MyClass;

    var_dump($a instanceof MyClass);
    var_dump($a instanceof NotMyClass);
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(false)

`instanceof` pode também ser usado para determinar se uma variável é um objeto instanciado de uma classe que herda de uma classe pai:

Exemplo #2 Usando `instanceof` com herança

    <?php
    class ParentClass
    {
    }

    class MyClass extends ParentClass
    {
    }

    $a = new MyClass;

    var_dump($a instanceof MyClass);
    var_dump($a instanceof ParentClass);
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(true)

Para verificar se um objeto não é uma instância de uma classe, o operador lógico `not` pode ser usado.

Exemplo #3 Usando `instanceof` para verificar se o objeto não é uma instância da classe

    <?php
    class MyClass
    {
    }

    $a = new MyClass;
    var_dump(!($a instanceof stdClass));
    ?>

O exemplo acima produzirá:

    bool(true)

Por fim, `instanceof` pode também ser usado para determinar se uma variável é um objeto instanciado de uma classe que implementa uma interface:

Exemplo #4 Usando `instanceof` para classe

    <?php
    interface MyInterface
    {
    }

    class MyClass implements MyInterface
    {
    }

    $a = new MyClass;

    var_dump($a instanceof MyClass);
    var_dump($a instanceof MyInterface);
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(true)

Embora `instanceof` é usualmente usado com um nome de classe literal, ele pode também ser usado com outro objeto ou uma variável string:

Exemplo #5 Usando `instanceof` com outras variáveis

    <?php
    interface MyInterface
    {
    }

    class MyClass implements MyInterface
    {
    }

    $a = new MyClass;
    $b = new MyClass;
    $c = 'MyClass';
    $d = 'NotMyClass';

    var_dump($a instanceof $b); // $b é um objeto da classe MyClass
    var_dump($a instanceof $c); // $c é uma string 'MyClass'
    var_dump($a instanceof $d); // $d é uma string 'NotMyClass'
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(true)
    bool(false)

instanceof não lança erros se a variável testada não for um objeto, apenas retorna `false`. Constantes não são permitidas anteriormente ao PHP 7.3.0.

Exemplo #6 Utilizando `instanceof` para testar outras variáveis

    <?php
    $a = 1;
    $b = NULL;
    $c = fopen('/tmp/', 'r');
    var_dump($a instanceof stdClass); // $a é um inteiro
    var_dump($b instanceof stdClass); // $b é NULL
    var_dump($c instanceof stdClass); // $c é um recurso
    var_dump(FALSE instanceof stdClass);
    ?>

O exemplo acima produzirá:

    bool(false)
    bool(false)
    bool(false)
    PHP Fatal error:  instanceof expects an object instance, constant given

Desde o PHP 7.3.0, constantes são permitidas à esquerda do operador `instanceof`.

Exemplo #7 Utilizando `instanceof` em constantes

    <?php
    var_dump(FALSE instanceof stdClass);
    ?>

Saída do exemplo acima no PHP 7.3:

    bool(false)

Desde o PHP 8.0.0, `instanceof` pode ser utilizado em expressões arbitrárias. A expressão precisa estar dentro de parênteses e produzir uma string.

Exemplo #8 Usando `instanceof` em expressões arbitrárias

    <?php

    class ClassA extends \stdClass {}
    class ClassB extends \stdClass {}
    class ClassC extends ClassB {}
    class ClassD extends ClassA {}

    function getSomeClass(): string
    {
        return ClassA::class;
    }

    var_dump(new ClassA instanceof ('std' . 'Class'));
    var_dump(new ClassB instanceof ('Class' . 'B'));
    var_dump(new ClassC instanceof ('Class' . 'A'));
    var_dump(new ClassD instanceof (getSomeClass()));
    ?>

Saída do exemplo acima no PHP 8:

    bool(true)
    bool(true)
    bool(false)
    bool(true)

O operador `instanceof` tem uma variação funcional chamada is_a().

### Veja Também

- get_class()
- is_a()

## Operadores Funcionais

O PHP 8.5 e versões posteriores suportam um operador que funciona diretamente em chamáveis. O operador `|>`, ou "pipe", aceita um chamável de parâmetro único à direita e passa o valor do lado esquerdo para ele, avaliando o resultado do chamável. O chamável à direita pode ser qualquer chamável PHP válido: um Closure, um chamável de primeira classe, um objeto que implementa __invoke(), etc.

Isso significa que as duas linhas seguintes são logicamente equivalentes.

Exemplo #1 Usando `|>`

    <?php
    $result = "Hello World" |> strlen(...);
    echo $result, PHP_EOL;

    $result = strlen("Hello World");
    echo $result, PHP_EOL;
    ?>

O exemplo acima produzirá:

    11
    11

Para uma única chamada, isso não é muito útil. Torna-se útil quando várias chamadas são encadeadas. Ou seja, os dois fragmentos de código a seguir são logicamente equivalentes:

Exemplo #2 Encadeando chamadas com |>

    <?php
    $result = "PHP Rocks"
        |> htmlentities(...)
        |> str_split(...)
        |> (fn($x) => array_map(strtoupper(...), $x))
        |> (fn($x) => array_filter($x, fn($v) => $v != 'O'))
    ;
    print_r($result);

    $temp = "PHP Rocks";
    $temp = htmlentities($temp);
    $temp = str_split($temp);
    $temp = array_map(strtoupper(...), $temp);
    $temp = array_filter($temp, fn($v) => $v != 'O');
    $result = $temp;
    print_r($result);
    ?>

O exemplo acima produzirá:

    Array
    (
        [0] => P
        [1] => H
        [2] => P
        [3] =>
        [4] => R
        [6] => C
        [7] => K
        [8] => S
    )
    Array
    (
        [0] => P
        [1] => H
        [2] => P
        [3] =>
        [4] => R
        [6] => C
        [7] => K
        [8] => S
    )

O lado esquerdo do pipe pode ser qualquer valor ou expressão. O lado direito pode ser qualquer chamável PHP válido que receba um único parâmetro, ou qualquer expressão que seja avaliado como tal chamável. Funções com mais de um parâmetro obrigatório não são permitidas e falharão como se fossem chamadas normalmente com argumentos insuficientes. Funções que recebem uma variável por referência não são permitidas. Se o lado direito não for avaliado como um chamável válido, será gerado um erro.

> Nota:

> Esteja ciente de que, para evitar ambiguidade de sintaxe, funções de seta PRECISAM ser colocadas entre parênteses quando usadas com um operador de pipe, como nos exemplos acima. Caso contrário, ocorrerá um erro fatal.

### Veja Também

- Closure

# Estruturas de Controle

## Índice

- Introdução
- if
- else
- elseif/else if
- Sintaxe Alternativa para estruturas de controle
- while
- do-while
- for
- foreach
- break
- continue
- switch
- match
- declare
- return
- require
- include
- require_once
- include_once
- goto

## Introdução

Qualquer script PHP é construído por uma série de instruções. Uma instrução pode ser uma atribuição, uma chamada de função, um laço de repetição, uma instrução condicional, ou mesmo uma instrução que não faz nada (um comando vazio). Instruções geralmente terminam com um ponto e vírgula. Além disso, as instruções podem ser agrupadas em um bloco de comandos através do encapsulamento de um grupo de comandos com chaves. Um grupo de comandos é uma instrução também. Os vários tipos de instruções são descritos neste capítulo.

### Veja Também

Os itens seguintes são considerados como construtos da linguagem, mesmo que eles sejam referenciados como funções neste manual.

- list()
- array()
- echo
- eval()
- print

## if

(PHP 4, PHP 5, PHP 7, PHP 8)

O construtor `if` é um dos recursos mais importantes em muitas linguagens, inclusive no PHP. Permite a execução condicional de fragmentos de código. O PHP apresenta uma estrutura `if` semelhante a do C:

    if (expr)
      statement

Como descrito na seção sobre expressões, expressões são avaliadas por seus valores Booleanos. Se uma expressão for avaliada como `true`, o PHP executará a declaração, e se avaliá-la como `false` - ignorá-la. Mais informações sobre quais valores são avaliados como `false` podem ser encontradas na seção 'Conversão para booleano' .

O exemplo a seguir exibirá a é maior que b se $a for maior que $b:

    <?php
    if ($a > $b)
      echo "a é maior que b";
    ?>

Muitas vezes deseja-se que mais de uma declaração seja condicionalmente executada. É claro que não é necessário envolver cada declaração em uma cláusula `if`. Em vez disso, pode-se agrupar várias declarações em grupos. Por exemplo, este código exibirá a é maior que b se $a for maior que $b, e atribuirá o valor de $a em $b:

    <?php
    if ($a > $b) {
      echo "a é maior que b";
      $b = $a;
    }
    ?>

A declaração `If` pode ser aninhada indefinidamente dentro de outras declarações `if`, fornecendo completa flexibilidade para execução condicional de várias partes do programa.

## else

(PHP 4, PHP 5, PHP 7, PHP 8)

Muitas vezes deseja-se executar uma instrução se uma certa condição for válida, e uma instrução diferente se a mesma condição não for válida. Para isso que o `else` serve. O `else` estende a instrução `if` para executar outras caso a expressão no `if` retornar `false`. Por exemplo, o código a seguir exibirá a é maior que b se $a for maior que $b, e a NÃO é maior que b caso contrário:

    <?php
    if ($a > $b) {
      echo "a é maior que b";
    } else {
      echo "a NÃO é maior que b";
    }
    ?>

A instrução `else` só é executada se a expressão de avaliação do `if` for avaliada como `false`, e se tiver qualquer expressão `elseif` - somente se também retornarem `false` (veja elseif).

> Nota: Else pendurado

> Em caso de declarações `if`-`else` aninhadas, um `else` é sempre associado com o `if` mais próximo.

>     <?php
>     $a = false;
>     $b = true;
>     if ($a)
>         if ($b)
>             echo "b";
>     else
>         echo "c";
>     ?>

> Apesar da indentação (o que não importa para o PHP), o `else` é associado com o `if ($b)`, então o exemplo não produz nenhuma saída. Embora seja válido confiar nesse comportamento, é recomendado evitá-lo usando chaves para resolver ambiguidades em potencial.

## elseif/else if

(PHP 4, PHP 5, PHP 7, PHP 8)

`elseif`, como o nome sugere, é uma combinação do `if` e `else`. Como o `else`, estende um `if` para executar instruções diferentes no caso da expressão `if` original ser avaliada como `false`. Entretanto, diferentemente do `else`, executará uma expressão alternativa somente se a expressão condicional do `elseif` for avaliada como `true`. Por exemplo, o código a seguir exibirá a é maior que b, a é igual a b ou a é menor que b:

    <?php
    if ($a > $b) {
        echo "a é maior que b";
    } elseif ($a == $b) {
        echo "a é igual a b";
    } else {
        echo "a é menor que b";
    }
    ?>

Pode haver vários `elseif`s dentro da mesma instrução `if`. A primeira expressão `elseif` (se houver) que retornar `true` será executada. No PHP, pode-se escrever `else if` (em duas palavras), e o comportamento será idêntico ao do `elseif` (em uma única palavra). O significado sintático é um pouco diferente (se você está familiarizado com C, mas, no final, ambos terão exatamente o mesmo comportamento.

O `elseif` só é executado se o `if` precedente ou qualquer `elseif` for avaliado como `false`, e o `elseif` corrente for avaliado como `true`.

> Nota: Note que o `elseif` e `else if` só serão considerados exatamente iguais se usados com chaves como no exemplo abaixo. Ao utilizar os dois pontos (:) para definir as condições de `if`/`elseif`, então o uso de `elseif` como uma única palavras se torna necessário, ou o PHP falhará com um erro de interpretação se `else if` estiver separado em duas palavras.

    <?php

    /* Método Incorreto: */
    if ($a > $b):
        echo $a." é maior que ".$b;
    else if ($a == $b): // Não irá compilar.
        echo "A linha acima causa um erro de análise.";
    endif;

    <?php
    /* Método Correto: */
    if ($a > $b):
        echo $a." é maior que ".$b;
    elseif ($a == $b): // Note a combinação das palavras.
        echo $a." é igual a ".$b;
    else:
        echo $a." não é maior nem igual a ".$b;
    endif;

    ?>

## Sintaxe Alternativa para estruturas de controle

(PHP 4, PHP 5, PHP 7, PHP 8)

O PHP oferece uma sintaxe alternativa para algumas estruturas de controle; a saber, `if`, `while`, `for`, `foreach`, e `switch`. Em cada caso, basicamente a sintaxe alternativa é trocar a chave de abertura por dois pontos (:) e a chave de fechamento por `endif;`, `endwhile;`, `endfor;`, `endforeach;`, ou `endswitch;`, respectivamente.

    <?php if ($a == 5): ?>
    A é igual a 5
    <?php endif; ?>

No exemplo acima, o bloco HTML "A é igual a 5" está dentro de um `if` escrito na sintaxe alternativa. O bloco HTML será exibido somente se $a for igual a 5.

A sintaxe alternativa também se aplica ao `else` e `elseif`. A seguir um exemplo de um `if` com `elseif` e `else` no formato alternativo:

    <?php
    if ($a == 5):
        echo "a é igual a 5";
        echo "...";
    elseif ($a == 6):
        echo "a é igual a 6";
        echo "!!!";
    else:
        echo "a não é 5 nem 6";
    endif;
    ?>

> Nota:

> Misturar a sintaxe no mesmo bloco de controle não é suportado.

Aviso

Qualquer saída (inclusive espaços em branco) entre um `switch` e o primeiro `case` irá resultar em um erro de sintaxe. O exemplo abaixo é inválido:

    <?php switch ($foo): ?>
        <?php case 1: ?>
        // ...
    <?php endswitch; ?>

Enquanto que este é válido, já que a quebra de linha depois do `switch` é considerado parte da tag de fechamento `?>` e, portanto, nenhuma saída será enviada entre o `switch` e `case`:

    <?php switch ($foo): ?>
    <?php case 1: ?>
        ...
    <?php endswitch; ?>

Veja mais sobre while, for, e if para outros exemplos.

## while

(PHP 4, PHP 5, PHP 7, PHP 8)

Laços `while` são os mais simples tipos de laços do PHP. Possui comportamento semelhante ao C. O formato básico de uma declaração `while` é:

    while (expr)
        statement

O propósito da declaração `while` é simples. Ele dirá ao PHP para executar as declarações aninhadas repetidamente, enquanto a expressão do `while` for avaliada como `true`. O valor da expressão é checado a cada vez que o laço é iniciado, então, mesmo seu valor mude durante a execução das declarações aninhadas, a execução não será interrompida até o final da iteração (cada vez que o PHP executa as declarações dentro do laço é uma iteração). Se a expressão do `while` for avaliada como `false` desde o início, as declarações aninhadas não serão executadas nenhuma vez.

Similar a declaração `if`, pode-se agrupar múltiplas declarações no mesmo laço `while` delimitando o grupo de declarações por chaves, ou utilizando a sintaxe alternativa:

    while (expr):
        statement
        ...
    endwhile;

Os exemplos a seguir são idênticos, e ambos imprimem os números de 1 a 10.

    <?php
    /* example 1 */

    $i = 1;
    while ($i <= 10) {
        echo $i++;  /* o valor exibido seria
                       $i antes do incremento
                       (incrementa depois) */
    }

    /* example 2 */

    $i = 1;
    while ($i <= 10):
        echo $i;
        $i++;
    endwhile;
    ?>

## do-while

(PHP 4, PHP 5, PHP 7, PHP 8)

Os laços `do-while` são muito similares aos laços `while`, com exceção que a expressão de avaliação é verificada ao final de cada iteração em vez de no começo. A maior diferença para o laço `while` é que a primeira iteração do laço `do-while` sempre é executada (a expressão de avaliação é executada somente no final da iteração), considerando que no laço `while` não é necessariamente executada (a expressão de avaliação é executada no começo de cada iteração, se avaliada como `false` logo no começo, a execução do laço será abortada imediatamente).

Só há uma sintaxe para o laço `do-while`:

    <?php
    $i = 0;
    do {
        echo $i;
    } while ($i > 0);
    ?>

O laço acima será executado somente uma vez, pois após a primeira iteração, quando a expressão de avaliação for executada, resultará em `false` ($i não é maior que 0) e a execução do laço será encerrada.

Usuários avançados de C devem estar familiarizados com um uso diferente do laço `do-while`, que permite parar a execução no meio do bloco de códigos, encapsulando-os em um `do-while` (0), e usando o `break`. O código a seguir demonstra isso:

    <?php
    do {
        if ($i < 5) {
            echo "i não é grande o suficiente";
            break;
        }
        $i *= $factor;
        if ($i < $minimum_limit) {
            break;
        }
        echo "i está ok";

        /* processa i */

    } while (0);
    ?>

É possível usar o `goto` ao invés desse truque.

## for

(PHP 4, PHP 5, PHP 7, PHP 8)

Os laços `for` são os mais complexos no PHP. Possui comportamento semelhante ao C. A sintaxe do laço `for` é:

    for (expr1; expr2; expr3)
        statement

A primeira expressão (expr1) é avaliada (executada), uma vez, incondicionalmente, no início do laço.

No começo de cada iteração a expr2 é avaliada. Se a avaliada como `true`, o laço continuará e as instruções aninhadas serão executadas. Se avaliada como `false`, a execução do laço terminará.

No final de cada iteração, a expr3 é avaliada (executada).

Cada uma das expressões podem ser vazias ou conter múltiplas expressões separadas por vírgulas. Na expr2, todas as expressões separadas por vírgula são avaliadas mas o resultado é obtido da última parte. Se a expr2 estiver vazia significa que o laço deve ser executado indefinidamente (O PHP considera implicitamente como `true`, igual ao C). Isto não é inútil como se imagina, pois muitas vezes deseja-se interromper o laço utilizando a instrução `break` ao invés de usar a expressão verdade do `for`.

Analise os seguintes exemplos. Todos exibem números de 1 até 10:

    <?php
    /* exemplo 1 */

    for ($i = 1; $i <= 10; $i++) {
        echo $i;
    }

    /* exemplo 2 */

    for ($i = 1; ; $i++) {
        if ($i > 10) {
            break;
        }
        echo $i;
    }

    /* exemplo 3 */

    $i = 1;
    for (; ; ) {
        if ($i > 10) {
            break;
        }
        echo $i;
        $i++;
    }

    /* exemplo 4 */

    for ($i = 1, $j = 0; $i <= 10; $j += $i, print $i, $i++);
    ?>

É claro que o primeiro exemplo aparenta ser o mais simpático (ou talvez o quarto), mas pode-se achar que o uso de expressões vazias no laço `for`, seja vantajoso em algumas ocasiões.

O PHP também suporta a sintaxe alternativa "dois pontos" para o laço `for`.

    for (expr1; expr2; expr3):
        statement
        ...
    endfor;

É comum, para muitos usuários, iterar em arrays como no exemplo abaixo.

    <?php
    /*
     * Este é um array com alguns dados que devem ser modificados
     * durante a execução do loop for.
     */
    $pessoas = array(
        array('nome' => 'Lucas', 'salt' => 856412),
        array('nome' => 'André', 'salt' => 215863)
    );

    for($i = 0; $i < count($pessoas); ++$i) {
        $pessoas[$i]['salt'] = mt_rand(000000, 999999);
    }
    ?>

O código acima pode se tornar lento, pois o tamanho do array será calculado a cada iteração. Desde que o tamanho nunca mude, o laço pode ser facilmente otimizado usando uma variável intermediária para armazenar o tamanho em vez de executar repetidamente o count():

    <?php
    $pessoas = array(
        array('nome' => 'Lucas', 'salt' => 856412),
        array('nome' => 'André', 'salt' => 215863)
    );

    for($i = 0, $tamanho = count($pessoas); $i < $tamanho; ++$i) {
        $pessoas[$i]['salt'] = mt_rand(000000, 999999);
    }
    ?>

## foreach

(PHP 4, PHP 5, PHP 7, PHP 8)

O construtor `foreach` fornece uma maneira fácil de iterar sobre arrays e objetos Traversable. O `foreach` emitirá um erro quando usado com uma variável contendo um tipo de dado diferente ou com uma variável não inicializada.

`foreach` pode, opcionalmente, obter a chave (`key`) de cada elemento:

    foreach (expressão_iterável as $valor) {
        lista_de_instruções
    }

    foreach (expressão_iterável as $chave => $valor) {
        lista_de_instruções
    }

A primeira forma percorre o iterável dado por `iterable_expression`. A cada iteração, o valor do elemento atual é atribuído à variável `$valor`.

A segunda forma irá, adicionalmente, atribuir a chave do elemento corrente à variável `$chave` a cada iteração.

Note que o `foreach` não modifica o ponteiro interno do array, que é usado por funções como current() e key().

É possível customizar a iteração em objetos.

Exemplo #1 Usos comuns de `foreach`

    <?php

    /* Exemplo: somente valor */
    $array = [1, 2, 3, 17];

    foreach ($array as $value) {
        echo "Elemento atual de \$array: $value.\n";
    }

    /* Exemplo: chave e valor */
    $array = [
        "um" => 1,
        "dois" => 2,
        "três" => 3,
        "dezessete" => 17
    ];

    foreach ($array as $key => $value) {
        echo "Chave: $key => Valor: $value\n";
    }

    /* Exemplo: arrays chave-valor multidimensionais */
    $grid = [];
    $grid[0][0] = "a";
    $grid[0][1] = "b";
    $grid[1][0] = "y";
    $grid[1][1] = "z";

    foreach ($grid as $y => $row) {
        foreach ($row as $x => $value) {
            echo "Valor na posição x=$x e y=$y: $value\n";
        }
    }

    /* Exemplo: arrays dinâmicos */
    foreach (range(1, 5) as $value) {
        echo "$value\n";
    }
    ?>

> Nota:

> `foreach` não suporta a capacidade de supressão de mensagens de erro usando o operador `@`.

### Desempacotando arrays aninhados

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

É possível iterar sobre um array de arrays e desempacotar o array aninhado em variáveis do laço usando desconstrução de array através de `[]` ou usando a construção de linguagem list() como o valor.

> Nota: Observe que a desconstrução de array através de `[]` só é possível a partir do PHP 7.1.0.

Em ambos os exemplos a seguir, `$a` será definida para o primeiro elemento do array aninhado e `$b` conterá o segundo elemento:

    <?php
    $array = [
        [1, 2],
        [3, 4],
    ];

    foreach ($array as [$a, $b]) {
        echo "A: $a; B: $b\n";
    }

    foreach ($array as list($a, $b)) {
        echo "A: $a; B: $b\n";
    }
    ?>

O exemplo acima produzirá:

    A: 1; B: 2
    A: 3; B: 4

Ao fornecer menos variáveis que o número de elementos no array, os elementos restantes serão ignorados. Da mesma forma, elementos podem ser pulados usando uma vírgula:

    <?php
    $array = [
        [1, 2, 5],
        [3, 4, 6],
    ];

    foreach ($array as [$a, $b]) {
        // Observe que não existe $c aqui.
        echo "$a $b\n";
    }

    foreach ($array as [, , $c]) {
        // Pulando $a e $b
        echo "$c\n";
    }
    ?>

O exemplo acima produzirá:

    1 2
    3 4
    5
    6

Um aviso será gerado se não houver elementos suficientes no array para o preenchimento do construtor list():

    <?php
    $array = [
        [1, 2],
        [3, 4],
    ];

    foreach ($array as [$a, $b, $c]) {
        echo "A: $a; B: $b; C: $c\n";
    }
    ?>

O exemplo acima produzirá:

    Notice: Undefined offset: 2 in example.php on line 7
    A: 1; B: 2; C:

    Notice: Undefined offset: 2 in example.php on line 7
    A: 3; B: 4; C:

### foreach e referências

É possível modificar elementos de array diretamente dentro de um laço, precedendo `$value` com `&`. Neste caso, o valor será atribuído por referência.

    <?php
    $arr = [1, 2, 3, 4];
    foreach ($arr as &$value) {
        $value = $value * 2;
    }
    // $arr agora é [2, 4, 6, 8]
    unset($value); // quebra a referência com o último elemento
    ?>

Aviso

A referência a um `$value` do último elemento do array permanece mesmo depois do laço `foreach`. É recomendado destruir essas referências usando unset(). Caso contrário, o comportamento a seguir irá ocorrer:

    <?php
    $arr = [1, 2, 3, 4];
    foreach ($arr as &$value) {
        $value = $value * 2;
    }
    // $arr agora é [2, 4, 6, 8]

    // sem um unset($value), $value ainda é uma referência ao último item: $arr[3]

    foreach ($arr as $key => $value) {
        // $arr[3] será atualizado com cada valor de $arr...
        echo "{$key} => {$value} ";
        print_r($arr);
    }
    // ...até finalmente o penúltimo valor ser copiado no último valor
    ?>

O exemplo acima produzirá:

    0 => 2 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 2 )
    1 => 4 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 4 )
    2 => 6 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 6 )
    3 => 6 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 6 )

Exemplo #2 Iterando valores de um array constante por referência

    <?php
    foreach ([1, 2, 3, 4] as &$value) {
        $value = $value * 2;
    }
    ?>

### Veja Também

- array
- Traversable
- iterable
- list()

## break

(PHP 4, PHP 5, PHP 7, PHP 8)

`break` finaliza a execução da estrutura `for`, `foreach`, `while`, `do-while` ou `switch` atual.

`break` aceita um argumento numérico opcional que diz quantas estruturas aninhadas deverão ser interrompidas. O valor padrão é `1`, somente a estrutura imediata é interrompida.

    <?php
    $arr = array('um', 'dois', 'três', 'quatro', 'pare', 'cinco');
    foreach ($arr as $val) {
        if ($val == 'pare') {
            break;    /* Pode-se também usar 'break 1;' aqui. */
        }
        echo "$val<br />\n";
    }

    /* Usando o argumento opcional. */

    $i = 0;
    while (++$i) {
        switch ($i) {
            case 5:
                echo "No 5<br />\n";
                break 1;  /* Sai apenas do switch. */
            case 10:
                echo "No 10; saindo<br />\n";
                break 2;  /* Sai do switch e do while. */
            default:
                break;
        }
    }
    ?>

## continue

(PHP 4, PHP 5, PHP 7, PHP 8)

`continue` é usado em estruturas de repetição para pular o restante da iteração atual do laço e continuar a execução na validação da condição e depois no início da próxima iteração.

> Nota: No PHP, a instrução switch é considerada uma estrutura de repetição para os propósitos de `continue`. `continue` se comporta como `break` (quando nenhum argumento é passado), mas emitirá um aviso, pois é provável que seja um erro. Se um `switch` estiver dentro de um laço, `continue 2` continuará na próxima iteração do laço externo.

`continue` aceita um argumento numérico opcional que informa quantos níveis de laços aninhados ele deve pular. O valor padrão é `1`, pulando assim para o final do laço atual.

    <?php
    $array = ['zero', 'um', 'dois', 'três', 'quatro', 'cinco', 'seis'];
    foreach ($array as $chave => $valor) {
        if (!($chave % 2)) { // pula membros com chaves pares
            continue;
        }
        echo $valor . "\n";
    }
    ?>

Os exemplos acima produzirão:

    um
    três
    cinco

    <?php
    $i = 0;
    while ($i++ < 5) {
        echo "Externo\n";
        while (1) {
            echo "Meio\n";
            while (1) {
                echo "Interno\n";
                continue 3;
            }
            echo "Isso nunca é exibido.\n";
        }
        echo "Nem isso.\n";
    }
    ?>

Os exemplos acima produzirão:

    Externo
    Meio
    Interno
    Externo
    Meio
    Interno
    Externo
    Meio
    Interno
    Externo
    Meio
    Interno
    Externo
    Meio
    Interno

Omitir o ponto e vírgula após `continue` pode causar confusão. Abaixo está um exemplo do que não se deve fazer.

    <?php
    for ($i = 0; $i < 5; ++$i) {
        if ($i == 2)
            continue
        print "$i\n";
    }
    ?>

O resultado esperado poderia ser:

    0
    1
    3
    4

Lista de modificações de `continue`
Versão | Descrição
--- | ---
7.3.0 | `continue` em um `switch` que está tentando agir como uma declaração `break` para o `switch` gerará um `E_WARNING`.

## switch

(PHP 4, PHP 5, PHP 7, PHP 8)

A declaração `switch` é similar a uma série de declarações IF na mesma expressão. Em muitos casos, se deseja comparar as mesmas variáveis (ou expressões), com diferentes valores, e executar pedaços diferentes de código dependendo de qual valor ela é igual. Esta é exatamente a serventia da declaração `switch`.

> Nota: Note que ao contrário de outras linguagens, a declaração continue aplica-se ao `switch` e age similarmente ao `break`. Se possuir um `switch` dentro de um laço, e deseja continuar na próxima iteração do laço externo, utilize `continue 2`.

> Nota:

> Note que o switch/case faz comparação frouxa.

No exemplo a seguir, cada bloco de código é equivalente. Um usa uma série de declarações `if` e `elseif`, e o outra usa uma declaração `switch`. A saída é a mesm a em ambos os casos.

Exemplo #1 Estrutura do `switch`

    <?php
    // Esta declaração switch:

    switch ($i) {
        case 0:
            echo "i é igual a 0";
            break;
        case 1:
            echo "i é igual a 1";
            break;
        case 2:
            echo "i é igual a 2";
            break;
    }

    // É equivalente a:

    if ($i == 0) {
        echo "i é igual a 0";
    } elseif ($i == 1) {
        echo "i é igual a 1";
    } elseif ($i == 2) {
        echo "i é igual a 2";
    }
    ?>

É importante entender como a declaração `switch` é executada a fim de evitar enganos. A declaração `switch` executa linha por linha (na verdade, declaração por declaração). No início, nenhum código é executado. Somente quando uma declaração `case` é encontrada, cuja expressão avalia um valor que corresponde ao valor do `switch`, o PHP começará a executar a declaração. O PHP continuará a executar a declaração até o fim do bloco `switch`, ou até a primeira declaração `break` encontrada. Se não for escrita uma declaração `break` ao final da lista de declarações do case, o PHP continuará executando as declarações dos próximos cases. Por exemplo:

    <?php
    switch ($i) {
        case 0:
            echo "i é igual a 0";
        case 1:
            echo "i é igual a 1";
        case 2:
            echo "i é igual a 2";
    }
    ?>

Neste exemplo, se a variável $i for igual a 0, o PHP executará todas as declarações echo! Se a variável $i for igual a 1, o PHP executará as duas últimas declarações echo. Somente se obterá o comportamento esperado ('i equals 2' será exibido), se $i for igual a 2. Sendo assim, é importante não esquecer as declarações `break` (mesmo quando se quer evitar, de propósito, sua omissão em certas circunstâncias).

Em uma declaração `switch`, a condição é avaliada somente uma vez, e o resultado é comparado a cada declaração `case`. Em uma declaração `elseif`. a condição é avaliada outra vez. Se a condição for mais complicada que uma simples comparação e/ou está em um laço pequeno, a declaração `switch` pode ser mais rápida.

A lista de declarações de um case também pode estar vazia, passando o controle da lista de declarações para o próximo case.

    <?php
    switch ($i) {
        case 0:
        case 1:
        case 2:
            echo "i é menor que 3 mas não é negativo";
            break;
        case 3:
            echo "i é 3";
    }
    ?>

Um case especial é o `default`. Este case corresponde a tudo que não foi correspondido pelos outros cases. Por exemplo:

    <?php
    switch ($i) {
        case 0:
            echo "i é igual a 0";
            break;
        case 1:
            echo "i é igual a 1";
            break;
        case 2:
            echo "i é igual a 2";
            break;
        default:
           echo "i não é igual a 0, 1 ou 2";
    }
    ?>

> Nota: Múltiplos casos padrões irão emitir um erro `E_COMPILE_ERROR`.

> Nota: Tecnicamente o caso `default` pode ser listado em qualquer ordem. Ele será usado apenas se nenhum outro caso corresponder. No entanto, por conversão, é melhor inseri-lo no fim como a última ramificação.

Se nenhuma ramificação `case` corresponder, e não existe nenhuma ramificação `default`, então nenhum código será executado, assim como se nenhuma declaração `if` fosse verdadeira.

Um valor de caso pode ser dado como uma expressão. No entanto, essa expressão será avaliada de forma isolada, e então será frouxamente comparada com o valor do switch. Isso significa que ela não pode ser usada para avaliações complexas do valor do switch. Por exemplo:

    <?php
    $alvo = 1;
    $inicio = 3;

    switch ($alvo) {
        case $inicio - 1:
            print "A";
            break;
        case $inicio - 2:
            print "B";
            break;
        case $inicio - 3:
            print "C";
            break;
        case $inicio - 4:
            print "D";
            break;
    }

    // Imprime "B"
    ?>

Para comparações mais complexas, o valor `true` pode ser usado como o valor do switch. Ou, alternativamente, `if`-`else` em vez do `switch`.

    <?php
    $deslocamento = 1;
    $inicio = 3;

    switch (true) {
        case $inicio - $deslocamento === 1:
            print "A";
            break;
        case $inicio - $deslocamento === 2:
            print "B";
            break;
        case $inicio - $deslocamento === 3:
            print "C";
            break;
        case $inicio - $deslocamento === 4:
            print "D";
            break;
    }

    // Imprime "B"
    ?>

A sintaxe alternativa das estruturas de controle é suportada por switches. Para mais informações, veja Sintaxe alternativa para estruturas de controle.

    <?php
    switch ($i):
        case 0:
            echo "i é igual a 0";
            break;
        case 1:
            echo "i é igual a 1";
            break;
        case 2:
            echo "i é igual a 2";
            break;
        default:
            echo "i não é igual a 0, 1 ou 2";
    endswitch;
    ?>

É possível utilizar o ponto e vírgula ao invés dos dois pontos em um case, como:

    <?php
    switch($cerveja)
    {
        case 'amstel';
        case 'brahma';
        case 'stella';
        case 'heineken';
            echo 'Boa escolha';
            break;
        default;
            echo 'Por favor faça uma nova seleção...';
            break;
    }
    ?>

### Veja Também

- match

## match

(PHP 8)

A expressão `match` ramifica a avaliação baseada em uma verificação de identidade de um valor. Semelhante a uma declaração `switch`, uma expressão `match` possui uma expressão sujeito que é comparada com múltiplas alternativas. Ao contrário da `switch`, ela irá avaliar para um valor assim como as expressões ternárias. Diferente da `switch`, a comparação é uma verificação de identidade (`===`) em vez de uma comparação de igualdade fraca (`==`). Expressões match estão disponíveis a partir do PHP 8.0.0.

Exemplo #1 Estrutura de uma expressão `match`

    <?php
    $valor_de_retorno = match (expressao_sujeito) {
        expressao_condicional_unica => expressao_de_retorno,
        expressao_condicional1, expressao_condicional2 => expressao_de_retorno,
    };
    ?>

Exemplo #2 Uso básico de `match`

    <?php
    $comida = 'bolo';

    $valor_de_retorno = match ($comida) {
        'apple' => 'Essa comida é uma maçã',
        'bar' => 'Essa comida é um bar',
        'bolo' => 'Essa comida é um bolo',
    };

    var_dump($valor_de_retorno);
    ?>

O exemplo acima produzirá:

    string(19) "Essa comida é um bolo"

Exemplo #3 Exemplo de uso de `match` com operadores de comparação

    <?php
    $age = 18;

    $output = match (true) {
        $age < 2 => "Bebê",
        $age < 13 => "Criança",
        $age <= 19 => "Adolescente",
        $age >= 40 => "Adulto"
        $age > 19 => "Adulto Jovem"
    };

    var_dump($output);
    ?>

O exemplo acima produzirá:

    string(11) "Adolescente"

> Nota: O resultado de uma expressão `match` não precisa ser usado.

> Nota: Quando uma expressão `match` é usada como uma expressão única, ela precisa ser terminada com um ponto-e-vírgula `;`.

A expressão `match` é similar a uma declaração `switch` mas tem algumas diferenças importantes:

- Um braço `match` compara valores estritamente (`===`) em vez de frouxamente como a declaração switch faz.
- Uma expressão `match` retorna um valor.
- Braços `match` não seguem para casos posteriores da maneira que declarações `switch` seguem.
- Uma expressão `match` deve ser exaustiva.

Assim como as declarações `switch`, expressões `match` são executadas a cada ramo de correspondência. No início, nenhum código é executado. As expressões condicionais só são avaliadas se todas as expressões condicionais anteriores não corresponderem à expressão sujeito. Apenas a expressão de retorno pertencente à expressão condicional de correspondência será avaliada. Por exemplo:

    <?php
    $resultado = match ($x) {
        foo() => 'value',
        $this->bar() => 'value', // $this->bar() não é chamado se foo() === $x
        $this->baz => beep(), // beep() não é chamado a não ser que $x === $this->baz
        // etc.
    };
    ?>

Braços da expressão `match` podem conter múltiplas expressões separadas por uma vírgula. Isso é um OR lógico, e é uma forma abreviada para múltiplos braços de correspondência com o mesmo lado direito.

    <?php
    $resultado = match ($x) {
        // Este braço de correspondência:
        $a, $b, $c => 5,
        // É equivalente a estes três braços de correspondência:
        $a => 5,
        $b => 5,
        $c => 5,
    };
    ?>

Um caso especial é o padrão `default`. Esse padrão atende a qualquer coisa que não tenha sido correspondida anteriormente. Por exemplo:

    <?php
    $resultadoDaExpressao = match ($condicao) {
        1, 2 => foo(),
        3, 4 => bar(),
        default => baz(),
    };
    ?>

> Nota: Múltiplos padrões 'default' irão emitir um erro `E_FATAL_ERROR`.

Uma expressão `match` deve ser exaustiva. Se a expressão sujeito não for tratada por nenhum braço de correspondência um UnhandledMatchError é lançado.

Exemplo #4 Exemplo de uma expressão match não tratada

    <?php
    $condicao = 5;

    try {
        match ($condicao) {
            1, 2 => foo(),
            3, 4 => bar(),
        };
    } catch (\UnhandledMatchError $e) {
        var_dump($e);
    }
    ?>

O exemplo acima produzirá:

    object(UnhandledMatchError)#1 (7) {
      ["message":protected]=>
      string(33) "Unhandled match value of type int"
      ["string":"Error":private]=>
      string(0) ""
      ["code":protected]=>
      int(0)
      ["file":protected]=>
      string(9) "/in/ICgGK"
      ["line":protected]=>
      int(6)
      ["trace":"Error":private]=>
      array(0) {
      }
      ["previous":"Error":private]=>
      NULL
    }

### Usando expressões match para tratar verificações sem identidade

É possível usar uma expressão `match` para tratar casos condicionais sem identidade usando `true` como a expressão sujeito.

Exemplo #5 Usando uma expressão match generalizada para ramificar com base em intervalos de inteiros

    <?php

    $idade = 23;

    $resultado = match (true) {
        $idade >= 65 => 'senhor',
        $idade >= 25 => 'adulto',
        $idade >= 18 => 'adolescente',
        default => 'criança',
    };

    var_dump($resultado);
    ?>

O exemplo acima produzirá:

    string(11) "adolescente"

Exemplo #6 Usando uma expressão match generalizada para ramificar com base no conteúdo de strings

    <?php

    $texto = 'Bienvenue chez nous';

    $resultado = match (true) {
        str_contains($text, 'Welcome'), str_contains($text, 'Hello') => 'en',
        str_contains($text, 'Bienvenue'), str_contains($text, 'Bonjour') => 'fr',
        // ...
    };

    var_dump($resultado);
    ?>

O exemplo acima produzirá:

    string(2) "fr"

## declare

(PHP 4, PHP 5, PHP 7, PHP 8)

A instrução `declare` é usada para definir diretivas de execução para um bloco de código. A sintaxe do `declare` é similar à sintaxe de outros construtos de controle de fluxo:

    declare (directive)
        statement

A seção `directive` permite que o comportamento do bloco do `declare` seja definido. Atualmente somente três diretivas são reconhecidas:

- `ticks`
- `encoding`
- `strict_types`

As diretivas são manipuladas na compilação do arquivo, somente literais podem ser usadas como valores da diretiva. Variáveis e constantes não podem ser usadas. Para ilustrar:

    <?php
    // Isto é válido:
    declare(ticks=1);

    // isto é inválido:
    const TICK_VALUE = 1;
    declare(ticks=TICK_VALUE);
    ?>

A parte `statement` do bloco do `declare` será executada - como é executada e quais os efeitos colaterais que ocorrem durante a execução depende da diretiva definida no bloco `directive`.

O construtor do `declare` também pode ser usado no escopo global, afetando todo o código que o segue (entretanto se o arquivo com o `declare` for incluído, não afetará o arquivo principal).

    <?php
    // Os exemplos abaixo tem o mesmo efeito

    // Pode ser usado assim:
    declare(ticks=1) {
        // script aqui
    }

    // ou assim:
    declare(ticks=1);
    // script inteiro aqui
    ?>

### Ticks

Um 'tick' é um evento que ocorre a cada N declarações de baixo nível executadas pelo interpretador dentro do bloco `declare`. O valor de N é especificado usando `ticks=N` dentro do bloco `declare` da seção `directive`.

Nem todas declarações são passíveis de executar um 'tick'. Normalmente, expressões de condições e argumentos de expressões não são.

Os eventos que serão executados a cada tick são especificados usando a função register_tick_function(). Veja o exemplo abaixo para mais detalhes. Note que mais de um evento pode ser executado para cada tick.

Exemplo #1 Exemplo de uso do Tick

    <?php

    declare(ticks=1);

    // A função a ser chamada em cada evento tick
    function tick_handler()
    {
        echo "tick_handler() chamada.\n";
    }

    register_tick_function('tick_handler'); // Causa um evento tick

    $a = 1; // Causa um evento tick

    if ($a > 0) {
        $a += 2; // Causa um evento tick
        print $a; // Causa um evento tick
    }

    ?>

Consulte também register_tick_function() e unregister_tick_function().

### Codificação

A codificação de um script pode ser especificada em cada arquivo com uma diretiva `encoding`.

Exemplo #2 Declarando a codificação do script

    <?php
    declare(encoding='ISO-8859-1');
    // código aqui
    ?>

Cuidado

Quando usada com namespaces, a única sintaxe válida para declarar é `declare(encoding='...');` onde `...` é o valor da codificação. `declare(encoding='...') {}` irá resultar em um erro de sintaxe quando usada com namespaces.

Veja mais zend.script_encoding.

## return

(PHP 4, PHP 5, PHP 7, PHP 8)

A declaração `return` retorna o controle do programa para o módulo que o chamou. A execução continuará na expressão seguinte à invocação do módulo.

Se chamada dentro de uma função, a declaração `return` terminará imediatamente sua execução, e retornará seus argumentos como valor à chamada da função. A declaração `return` também termina a execução de uma declaração eval() ou um arquivo de script.

Se chamada no escopo global, a execução do script atual é finalizada. Se o arquivo de script atual for incluído ou requerido com as funções include ou require, o controle é passado de volta ao script que está chamando. Além disso, se o script atual foi incluído com a função include, o valor informado ao `return` será retornado como o valor da chamada de include. Se um `return` for chamado de dentro do script principal, sua execução será finalizada. Se o script atual for mencionado nas opções de configuração auto_prepend_file ou auto_append_file php.ini, a execução do script será finalizada.

Para mais informações, consulte a seção sobre Retornando Valores.

> Nota: Observe que, como `return` é um construtor de linguagem e não uma função, os parênteses que envolvem seus argumentos não são exigidos e seu uso é desencorajado.

> Nota: Se nenhum parâmetro for informado, e os parênteses omitidos, `null` será retornado. Chamar um `return` com parênteses mas sem argumentos resultará em um erro de interpretação.

A partir do PHP 7.1.0, declarações 'return' sem um argumento em funções que declaram um tipo de retorno acionam `E_COMPILE_ERROR`, a não ser que o tipo de retorno seja void, nesse caso declarações 'return' com um argumento acionam esse erro.

## require

(PHP 4, PHP 5, PHP 7, PHP 8)

A declaração `require` é idêntica à include exceto que em caso de falha também produzirá uma exceção Error (erro de nível `E_COMPILE_ERROR` antes do PHP 8.0.0) enquanto que include apenas emitirá um alerta (nível de erro `E_WARNING`).

Veja a documentação include para saber como isso funciona.

## include

(PHP 4, PHP 5, PHP 7, PHP 8)

A expressão `include` inclui e avalia o arquivo informado.

A documentação a seguir também se aplica à declaração require.

Os arquivos são incluídos baseando-se no caminho do arquivo informado ou, se não informado, o include_path especificado. Se o arquivo não for encontrado no include_path, `include` verificará no diretório do script que o executa e no diretório de trabalho corrente antes de falhar. O construtor `include` emitirá um `E_WARNING` se não localizar o arquivo; possui um comportamento diferente do require, que emitirá um `E_ERROR`.

Note que ambas `include` e `require` emitem `E_WARNING`s adicionais, se o arquivo não puder ser acessado, antes de emitir o `E_WARNING` ou `E_ERROR` final, respectivamente.

Se um caminho for definido — seja absoluto (iniciando com a letra da unidade ou `\` no Windows, ou `/` no Unix/Linux ), ou relativo ao diretório atual (começando com `.` ou `..`) — o include_path será completamente ignorado. Por exemplo, se o nome do arquivo iniciar com `../`, o interpretador irá procurar pelo arquivo no diretório pai.

Para mais informações de como o PHP trabalha ao incluir arquivos e o caminho de inclusão, veja a documentação de include_path.

Quando um arquivo é incluído, o código herda o escopo de variáveis da da linha que a inclusão ocorrer. Qualquer variável disponível no arquivo que o incluiu estará disponível no arquivo incluído, daquela linha em diante. Entretanto, todas as funções e classes definidas no arquivo incluído estarão no escopo global.

Exemplo #1 Exemplo básico do construtor `include`

    vars.php
    <?php

    $color = 'green';
    $fruit = 'apple';

    ?>

    test.php
    <?php

    echo "A $color $fruit"; // A

    include 'vars.php';

    echo "A $color $fruit"; // A green apple

    ?>

Se a inclusão ocorrer dentro de uma função, todo o código contido no arquivo incluído irá se comportar como se tivesse sido definido dentro da função. Portanto seguirá o escopo de variáveis da função. Uma exceção para essa regra são as constantes mágicas que são interpretadas antes da inclusão ocorrer.

Exemplo #2 Inclusão em funções

    <?php

    function foo()
    {
        global $color;

        include 'vars.php';

        echo "A $color $fruit";
    }

    /* vars.php está no escopo de foo() por isso *
    * $fruit NÃO está disponível fora deste      *
    * escopo. $color está, porque foi declarada  *
    * como global.                               */

    foo();                    // A green apple
    echo "A $color $fruit";   // A green

    ?>

Quando um arquivo é incluído, o interpretador sai do modo PHP e entra no modo HTML no começo do arquivo incluído, e volta novamente no final. Por esta razão, qualquer código dentro do arquivo incluído que necessite ser executado como PHP deve estar entre tags válidas de início e fim do PHP.

Se os "empacotadores de inclusão de URL" estiverem habilitados no PHP, pode-se definir um arquivo a ser incluído usando uma URL (via HTTP ou outro protocolo suportado - veja Protocolos e empacotadores suportados para uma lista de protocolos) ao invés de um caminho local. Se o servidor de destino interpretar o arquivo incluído como PHP, variáveis podem ser passadas para o arquivo incluído usando uma URL de requisição com HTTP GET. Isso não significa a mesma coisa que incluir e compartilhar o escopo de variáveis com o arquivo incluído; o script é executado no servidor remoto e o resultado é incluído no script local.

Exemplo #3 Usando `include` via HTTP

    <?php

    /* Este exemplo assume que www.exemplo.com.br está configurado para processar
    * arquivos .php e não arquivos .txt. Além disso, 'Funciona' aqui significa
    * que as variáveis $foo e $bar estão disponíveis dentro do arquivo incluído. */

    // Não vai funcionar; arquivo.txt não foi tratado por www.exemplo.com.br como PHP
    include 'http://www.exemplo.com.br/arquivo.txt?foo=1&bar=2';

    // Não vai funcionar; procura por um arquivo chamado 'arquivo.php?foo=1&bar=2' no
    // sistema de arquivos local.
    include 'arquivo.php?foo=1&bar=2';

    // Funciona.
    include 'http://www.exemplo.com.br/arquivo.php?foo=1&bar=2';
    ?>

Aviso

# Avisos de Segurança

O arquivo remoto pode ser processado pelo servidor remoto (dependendo da extensão do arquivo e se o servidor remoto executa, ou não,arquivos PHP), mas ainda precisa produzir um código PHP válido pois será processado pelo servidor local. Se o arquivo do servidor remoto deve ser processado como um texto simples, a função readfile() é uma opção muito melhor a ser usada. Caso contrário, deve-se ter um cuidado especial para garantir que o servidor remoto produza um código PHP válido.

Veja também Arquivos Remotos, fopen() e file() para informações relacionadas.

Manipulando retornos: `include` retorna `FALSE` ao falhar e emite um aviso. Inclusões bem sucedidas, ao menos que seja sobrescritas pelo arquivo incluído, retornam `1`. É possível utilizar a declaração return dentro do arquivo incluído para finalizar o processamento e retornar para o arquivo que o incluiu. Além disso, é possível retornar valor a partir do arquivo incluído. Pode-se usar o valor do arquivo incluído como em uma função normal. Isso não é, entretanto, possível quando incluímos arquivos remotos a menos que a saída do arquivo remoto tenha tags válidas de início e fim do PHP (como em um arquivo local). Pode-se declarar as variáveis necessárias dentro dessas tags e estarão disponíveis em qualquer ponto do arquivo que o incluiu.

Pelo fato do `include` ser um construtor especial da linguagem, parênteses não são necessários ao redor do argumento. Tome cuidado ao comparar valores de retorno.

Exemplo #4 Comparando valores de retorno do include

    <?php
    // não vai funcionar, avaliado como include(('vars.php') == TRUE), isto é: include('1')
    if (include('vars.php') == TRUE) {
        echo 'OK';
    }

    // funciona
    if ((include 'vars.php') == TRUE) {
        echo 'OK';
    }
    ?>

Exemplo #5 `include` e a instrução return

    return.php
    <?php

    $var = 'PHP';

    return $var;

    ?>

    noreturn.php
    <?php

    $var = 'PHP';

    ?>

    testreturns.php
    <?php

    $foo = include 'return.php';

    echo $foo; // imprime 'PHP'

    $bar = include 'noreturn.php';

    echo $bar; // imprime 1

    ?>

`$bar` tem o valor `1` porque a inclusão foi bem sucedida. Note a diferença entre os dois exemplos. O primeiro usa return, enquanto o outro não. Se o arquivo não puder ser incluído, `false` é retornado e um `E_WARNING` emitido.

Se funções forem definidas no arquivo incluído, elas podem ser utilizadas no arquivo principal independente se estão antes ou depois do return. Se o arquivo for incluído duas vezes, o PHP emitirá um erro fatal, pois as funções já foram declaradas. É recomendado usar o include_once ao invés de verificar se o arquivo já foi incluído manualmente dentro do arquivo incluído.

Outra forma de "incluir" um arquivo PHP em uma variável é capturar a saída usando as Funções de Controle de Saída com o `include`. Por exemplo:

Exemplo #6 Usando buffer de saída para incluir um arquivo PHP em uma string

    <?php
    $string = get_include_contents('somefile.php');

    function get_include_contents($filename) {
        if (is_file($filename)) {
            ob_start();
            include $filename;
            return ob_get_clean();
        }
        return false;
    }

    ?>

Para automatizar a inclusão de arquivos nos scripts, veja também as configurações auto_prepend_file e auto_append_file contidas no php.ini.

> Nota: Como esta é uma construção da linguagem e não uma função, ela não pode ser chamada usando funções variáveis ou argumentos nomeados.

Veja também require, require_once, include_once, get_included_files(), readfile(), virtual(), e include_path.

## require_once

(PHP 4, PHP 5, PHP 7, PHP 8)

A expressão `require_once` é idêntica à require, exceto que o PHP verificará se o arquivo já foi incluído, e em caso afirmativo, não o incluirá (exigirá) novamente.

Veja a documentação include_once para informação sobre o comportamento `_once`, e como ele difere de seus irmãos `_once`.

## include_once

(PHP 4, PHP 5, PHP 7, PHP 8)

A expressão `include_once` inclui e avalia o arquivo informado durante a execução do script. Este é um comportamento similar à expressão include, com a única diferença que, se o código do arquivo já foi incluído, não o fará novamente, e a include_once retornará `true`. Como o nome sugere, o arquivo será incluído somente uma vez.

A `include_once` pode ser utilizada em casos em que o mesmo arquivo pode ser incluído e validado mais de uma vez durante uma execução de um script em particular, neste caso, ajudará a evitar problemas como redefinição de funções, reatribuição de valores de variáveis, etc.

Consulte a documentação da expressão include para informações sobre como ela funciona.

## goto

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Imagem cortesia do » xkcd

O operador `goto` pode ser usado para pular para outra seção do programa. O ponto de destino é definido por um rótulo sensível a maiúsculas e minúsculas seguido de dois pontos, e a instrução é usada como `goto` seguida do rótulo de destino desejado. O uso do `goto` não é completamente irrestrito. O rótulo de destino deve estar no mesmo arquivo e contexto, significando que não se pode pular para fora ou para dentro de uma função ou método. Também não pode-se saltar para dentro de um laço ou estrutura switch. Pode-se saltar para fora deles, e um uso comum é usar o `goto` no lugar de um `break` multinível.

Exemplo #1 Exemplo da estrutura de controle `goto`

    <?php

    goto a;
    echo 'Foo';

    a:
    echo 'Bar';

    ?>

O exemplo acima produzirá:

    Bar

Exemplo #2 Exemplo da estrutura de controle `goto` em um laço

    <?php

    for ($i = 0, $j = 50; $i < 100; $i++) {
        while ($j--) {
            if ($j == 17) {
                goto end;
            }
        }
    }
    echo "i = $i";
    end:
    echo 'j chegou em 17';

    ?>

O exemplo acima produzirá:

    j chegou em 17

Exemplo #3 Isto não irá funcionar

    <?php

    goto loop;
    for ($i = 0, $j = 50; $i < 100; $i++) {
        while ($j--) {
            loop:
        }
    }
    echo "$i = $i";

    ?>

O exemplo acima produzirá:

    Fatal error: 'goto' into loop or switch statement is disallowed in
    script on line 2

# Funções

## Índice

- Funções definidas pelo usuário
- Parâmetros e argumentos de funções
- Retornando valores
- Funções variáveis
- Funções internas
- Funções anônimas
- Funções de Seta
- Sintaxe de Chamáveis de Primeira Classe

## Funções definidas pelo usuário

Uma função é definida pelo uso da palavra-chave `function`, um nome, uma lista de parâmetros (que pode estar vazia) separados por vírgulas (`,`) entre parênteses, seguidos pelo corpo da função entre chaves, como a seguir:

Exemplo #1 Declarando uma nova função chamada `foo`

    <?php
    function foo($arg_1, $arg_2, /* ..., */ $arg_n)
    {
        echo "Exemplo de função.\n";
        return $valor_retornado;
    }

> Nota:

> A partir do PHP 8.0.0, a lista de parâmetros pode ter uma vírgula no final:

>     <?php
>     function foo($arg_1, $arg_2,) { }

Qualquer código PHP válido pode aparecer dentro do corpo de uma função, mesmo outras funções e definições de classes.

Nomes de funções seguem as mesmas regras que outros nomes no PHP. Um nome de função válido começa com uma letra ou um sublinhado, seguido por qualquer número de letras, números ou sublinhados. Com uma expressão regular, seria expressado com: `^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$`.

Dica

Veja também o Guia de nomenclatura em espaço de usuário.

As funções não precisam ser criadas antes de serem referenciadas, exceto quando uma função é condicionalmente definida como mostrado nos dois exemplos abaixo.

Quando uma função é definida condicionalmente como nos dois exemplos abaixo, sua definição precisa ser processada antes de ser chamada.

Exemplo #2 Funções definidas condicionalmente

    <?php
    $makefoo = true;

    /* Não podemos chamar foo() daqui
       porque ela ainda não existe,
       mas podemos chamar bar() */
    if (function_exists('foo')) {
        foo();
    } else {
        echo "Função foo não existe (ainda).\n";
    }

    bar();

    if ($makefoo) {
      function foo()
      {
        echo "Eu não existo até que o programa passe por aqui.\n";
      }
    }

    /* Agora podemos chamar foo()
       porque $makefoo foi avaliado como true */

    if ($makefoo) foo();

    function bar()
    {
      echo "Eu existo imediatamente desde o programa começar.\n";
    }

Exemplo #3 Funções dentro de funções

    <?php
    function foo()
    {
      function bar()
      {
        echo "Eu não existo até foo() ser chamada.\n";
      }
    }

    /* Nós não podemos chamar bar() ainda
       porque ela ainda não foi definida. */
    if (function_exists('bar')) {
        bar();
    }

    foo();

    /* Agora nós podemos chamar bar(),
       porque o processamento de foo()
       tornou a primeira acessível */

    bar();

Todas as funções e classes no PHP tem escopo global - elas podem ser chamadas fora de uma função mesmo que tenham sido definidas dentro e vice-versa.

O PHP não suporta sobrecarga de funções, e também não é possível cancelar ou alterar a definição de funções previamente declaradas.

> Nota: Nomes de funções são case-insensitive para caracteres ASCII `A` até `Z`, mas é melhor chamar as funções da mesma forma que elas aparecem nas declarações.

Ambos número variável de argumentos e argumentos padrões são suportados em funções. veja também as referências das funções func_num_args(), func_get_arg() e func_get_args() para mais informações.

É possível chamar funções recursivas no PHP.

Exemplo #4 Funções Recursivas

    <?php
    function recursion($a)
    {
        if ($a < 20) {
            echo "$a\n";
            recursion($a + 1);
        }
    }

    recursion(17);

> Nota: Chamadas recursivas a funções/métodos acima de 100-200 níveis podem exaurir a pilha e causar o término do script. Especificamente, recursão infinita é considerada um erro de programação.

## Parâmetros e argumentos de funções

Os parâmetros de uma função são declarados em sua assinatura. Informações podem ser passadas para funções através da lista de argumentos, que é uma lista de expressões delimitadas por vírgulas. Os argumentos são avaliados da esquerda para a direita, e o resultado é atribuído aos parâmetros da função, antes que a função seja efetivamente chamada (avaliação ansiosa).

O PHP suporta a passagem de argumentos por valor (o padrão), passagem por referência e valores padrões de argumentos. Lista de argumentos de tamanho variável e argumentos nomeados também são suportados.

> Nota:

> A partir do PHP 7.3.0, é possível ter uma vírgula no final da lista de argumentos para chamadas de função:

>     <?php
>     $v = foo(
>         $arg_1,
>         $arg_2,
>     );

A partir do PHP 8.0.0, a lista de parâmetros de uma função pode incluir uma vírgula final, que será ignorada. Isto é particularmente útil nos casos em que a lista de parâmetros é longa ou contém nomes de variáveis longos, tornando conveniente listar os parâmetros verticalmente.

Exemplo #1 Parâmetros de função com uma vírgula final

    <?php
    function takes_many_args(
        $primeiro,
        $segundo,
        $uma_variavel_com_nome_longo,
        $parametro_com_default = 5,
        $de_novo = 'argumento padrão', // Essa vírgula final não era permitida antes do PHP 8.0.0.
    )
    {
        // ...
    }

### Passando argumentos por referência

Por padrão, argumentos de função são passados por valor (de forma que se você mudar o valor do parâmetro dentro da função, ele não é alterado fora da função). Para permitir que uma função modifique os seus argumentos, eles devem ser passados por referência.

Para ter um argumento para uma função sempre passado por referência, adicione antes dele um "e comercial" (&) ao nome do parâmetro na definição da função:

Exemplo #2 Passando argumentos de função por referência

    <?php
    function add_some_extra(&$string)
    {
        $string .= ' e alguma coisa mais.';
    }
    $str = 'Isto é uma string,';
    add_some_extra($str);
    echo $str;    // exibe 'Isto é uma string, e alguma coisa mais.'

É um erro passar uma expressão constante como um argumento para um parâmetro que espera ser passado por referência.

### Valores padrão de parâmetros

Uma função pode definir valores padrão para parâmetros usando sintaxe similar à atribuição de uma variável. O padrão é usado apenas quando o argumento do parâmetro não é passado. Observe que passar `null` não atribui o valor padrão.

Exemplo #3 Utilizando parâmetros padrão em funções

    <?php
    function makecoffee($type = "cappuccino")
    {
        return "Fazendo uma xícara de café $type.\n";
    }
    echo makecoffee();
    echo makecoffee(null);
    echo makecoffee("espresso");

O exemplo acima produzirá:

    Fazendo uma xícara de café cappuccino.
    Fazendo uma xícara de café.
    Fazendo uma xícara de café espresso.

Valores padrões de parâmetro podem ser valores escalares, arrays, o tipo especial `null` e, a partir do PHP 8.1.0, objetos usando a sintaxe new ClassName().

Exemplo #4 Usando tipos não escalares como valores padrões

    <?php
    function fazercafe($tipos = array("cappuccino"), $cafeteira = NULL)
    {
        $dispositivo = is_null($cafeteira) ? "as mãos" : $cafeteira;
        return "Fazendo uma xícara de ".join(", ", $tipos)." com $dispositivo.\n";
    }
    echo fazercafe();
    echo fazercafe(array("cappuccino", "lavazza"), "chaleira");

O exemplo acima produzirá:

    Fazendo uma xícara de cappuccino com as mãos.
    Fazendo uma xícara de cappuccino, lavazza com chaleira.

Exemplo #5 Usando objetos como valores padrão (a partir do PHP 8.1.0)

    <?php
    class CafeteiraPadrao {
        public function preparar() {
            return 'Fazendo café.\n';
        }
    }
    class CafeteiraChique {
        public function preparar() {
            return 'Preparando um belo café só para você.\n';
        }
    }
    function fazercafe($cafeteira = new CafeteiraPadrao)
    {
        return $cafeteira->preparar();
    }
    echo fazercafe();
    echo fazercafe(new CafeteiraChique);

O exemplo acima produzirá:

    Fazendo café.
    Preparando um belo café só para você.

O valor padrão precisa ser uma expressão constante, não (por exemplo) uma variável, um membro de classe ou uma chamada de função.

Observe que quaisquer parâmetros opcionais devem ser especificados após os parâmetros obrigatórios, caso contrário, eles não podem ser omitidos das chamadas. Considere o seguinte exemplo:

Exemplo #6 Uso incorreto de parâmetros padrão de função

    <?php
    function fazeriogurte($recipiente = "tigela", $sabor)
    {
        return "Fazendo um(a) $recipiente de iogurte de $sabor.\n";
    }

    echo fazeriogurte("framboesa"); // "framboesa" é $recipiente, não $sabor

O exemplo acima produzirá:

    Deprecated: fazeriogurte(): Optional parameter $recipiente declared before required parameter $sabor is implicitly treated as a required parameter in script on line 2

    Fatal error: Uncaught ArgumentCountError: Too few arguments to function fazeriogurte(), 1 passed in script on line 7 and exactly 2 expected in script:2
    Stack trace:
    #0 script(7): fazeriogurte('framboesa')
    #1 {main}
      thrown in script on line 2

Agora, compare o que está acima com este:

Exemplo #7 Uso correto de parâmetros padrão de função

    <?php
    function fazeriogurte($sabor, $recipiente = "tigela")
    {
        return "Fazendo um(a) $recipiente de iogurte de $sabor.\n";
    }

    echo fazeriogurte("framboesa"); // "framboesa" é $sabor

O exemplo acima produzirá:

    Fazendo um(a) tigela de iogurte de framboesa.

A partir do PHP 8.0.0, argumentos nomeados podem ser usados para pular vários parâmetros opcionais.

Exemplo #8 Uso correto de parâmetros padrão de função

    <?php
    function fazeriogurte($recipiente = "tigela", $sabor = "framboesa", $estilo = "Grego")
    {
        return "Fazendo um(a) $recipiente de iogurte $estilo de $sabor.\n";
    }

    echo fazeriogurte(estilo: "natural");

O exemplo acima produzirá:

    Fazendo um(a) tigela de iogurte natural de framboesa.

A partir do PHP 8.0.0, declarar parâmetros obrigatórios após parâmetros opcionais está descontinuado. Isso geralmente pode ser resolvido descartando o valor padrão, pois nunca será usado. Uma exceção a essa regra são parâmetros no formato `Type $param = null`, onde o padrão `null` torna o tipo implicitamente anulável. Este uso foi descontinuado a partir do PHP 8.4.0, e um tipo anulável explícito deve ser usado.

Exemplo #9 Declarando parâmetros opcionais após parâmetros obrigatórios

    <?php
    function foo($a = [], $b) {}     // Padrão não utilizado; descontinuado a partir do PHP 8.0.0
    function foo($a, $b) {}          // Funcionalmente equivalente, sem aviso de descontinuação

    function bar(A $a = null, $b) {} // A partir do PHP 8.1.0, $a é implicitamente requerido
                                     // (porque vem antes do parâmetro requerido),
                                     // porém implicitamente anulável (descontinuado a partir do PHP 8.4.0),
                                     // porque o valor padrão do parâmetro é null
    function bar(?A $a, $b) {}       // Recomendado

> Nota: A partir do PHP 7.1.0, omitir um parâmetro que não especifica um padrão lança um ArgumentCountError; em versões anteriores isso emitia um Aviso.

> Nota: Parâmetros que esperam o argumento por referência podem ter um valor padrão.

### Número variável de argumentos

O PHP suporta argumentos em quantidade variável em funções definidas pelo usuário, utilizando o token `...`.

Listas de parâmetros podem conter o token `...` para indicar que a função aceita um número variável de argumentos. Os argumentos serão passados na variável informada como um array:

Exemplo #10 Utilizando `...` para acessar argumentos variáveis

    <?php
    function sum(...$numbers) {
        $acc = 0;
        foreach ($numbers as $n) {
            $acc += $n;
        }
        return $acc;
    }

    echo sum(1, 2, 3, 4);

O exemplo acima produzirá:

    10

Você também pode utilizar `...` quando chamando funções para transformar uma variável array, Traversable ou literal em uma lista de argumentos.

Exemplo #11 Utilizando `...` para fornecer argumentos

    <?php
    function add($a, $b) {
        return $a + $b;
    }

    echo add(...[1, 2])."\n";

    $a = [1, 2];
    echo add(...$a);

O exemplo acima produzirá:

    3
    3

Podem ser especificados parâmetros posicionais antes do indicador. `...`. Nesse caso comente os argumentos finais, que não pareiam com um argumento posicional, serão adicionados ao array gerado por `...`.

É também possível adicionar uma dica de tipo antes do indicador `...`. Se presente, todos os argumentos capturados por `...` deverão conformar com o tipo do parâmetro.

Exemplo #12 Argumentos variáveis com dica de tipo

    <?php
    function total_intervals($unit, DateInterval ...$intervals) {
        $time = 0;
        foreach ($intervals as $interval) {
            $time += $interval->$unit;
        }
        return $time;
    }

    $a = new DateInterval('P1D');
    $b = new DateInterval('P2D');
    echo total_intervals('d', $a, $b).' days';

    // Isto falhará, já que null não é um objeto DateInterval.
    echo total_intervals('d', null);

O exemplo acima produzirá:

    3 days
    Fatal error: Uncaught TypeError: total_intervals(): Argument #2 must be of type DateInterval, null given, called in script on line 15 and defined in script:2
    Stack trace:
    #0 script(15): total_intervals('d', NULL)
    #1 {main}
      thrown in script on line 2

Finalmente, também podem ser passados argumentos variáveis por referência ao prefixar `...` com um `&`.

### Argumentos nomeados

O PHP 8.0.0 introduziu os argumentos nomeados como uma extensão aos parâmetros posicionais. Argumentos nomeados permitem a passagem de argumentos para uma função utilizando-se os nomes dos parâmetros ao invés das posições deles. Isto torna o significado do argumento documentado automaticamente, e torna os argumentos independentes da ordem, além de permitir pular argumentos opcionais.

Argumentos nomeados são passados ao prefixar o valor com o nome do parâmetro e dois pontos. Usar palavras reservadas como nomes de parâmetros é permitido. O nome do parâmetro precisa ser um identificador e uma resolução dinâmica não é permitida.

Exemplo #13 Sintaxe dos argumentos nomeados

    <?php
    minhaFuncao(nomeParametro: $valor);
    array_foobar(array: $value);

    // NÃO suportado
    nome_funcao($variavelQueGuardaNomeDoParametro: $valor);

Exemplo #14 Comparando argumentos posicionais e nomeados

    <?php
    // Utilizando argumentos posicionais:
    array_fill(0, 100, 50);

    // Utilizando argumetos nomeados:
    array_fill(start_index: 0, count: 100, value: 50);

A ordem em que argumentos nomeados são passados não importa.

Exemplo #15 Mesmo exemplo com argumentos em ordem diferente

    <?php
    array_fill(value: 50, count: 100, start_index: 0);

Argumentos nomeados podem ser combinados com argumentos posicionais. Nesse caso, os argumentos nomeados precisam estar depois dos argumentos posicionais. Também é possível especificar somente alguns dos argumentos opcionais de uma função, independente da ordem.

Exemplo #16 Combinando argumentos posicionais e nomeados

    <?php
    htmlspecialchars($string, double_encode: false);
    // Mesmo que
    htmlspecialchars($string, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401, 'UTF-8', false);

Passar o mesmo argumento mais de uma vez resulta em uma exceção Error.

Exemplo #17 Erro lançado ao passar um argumento ao mesmo parâmetro nomeado múltiplas vezes

    <?php
    function foo($param) { ... }

    foo(param: 1, param: 2);
    // Error: Named parameter $param overwrites previous argument

    foo(1, param: 2);
    // Error: Named parameter $param overwrites previous argument

A partir do PHP 8.1.0, é possível usar argumentos nomeados após desempacotar os argumentos. Um argumento nomeado não deve sobrepor argumentos já desempacotados.

Exemplo #18 Usando argumentos nomeados após desempacotar

    <?php
    function foo($a, $b, $c = 3, $d = 4) {
      return $a + $b + $c + $d;
    }

    var_dump(foo(...[1, 2], d: 40)); // 46
    var_dump(foo(...['b' => 2, 'a' => 1], d: 40)); // 46

    var_dump(foo(...[1, 2], b: 20)); // Fatal error. Named parameter $b overwrites previous argument

## Retornando valores

Os valores podem ser retornados utilizando a instrução opcional return. Qualquer tipo pode ser retornado, incluindo arrays e objetos. Isto faz com que as função termine sua execução imediatamente e passa o controle de volta para a linha de onde ela foi chamada. Veja a documentação da função return para maiores informações.

> Nota:

> Se return for omitido então o valor `null` será retornado.

### Sintaxe do return

Exemplo #1 O uso de return

    <?php
    function quadrado($num)
    {
        return $num * $num;
    }
    echo quadrado(4); // exibe '16'.

Você não pode retornar múltiplos valores a partir de uma função, mas resultados similares podem ser obtidos retornando um array.

Exemplo #2 Retornando um array para devolver vários valores

    <?php
    function primeiros_numeros()
    {
        return [0, 1, 2];
    }
    // Desconstruir o array coleta cada item individualmente
    [$zero, $one, $two] = primeiros_numeros();
    var_dump($zero, $one, $two);

    // Anteriormente ao 7.1.0 a única alternativa era usar list()
    list($zero, $one, $two) = primeiros_numeros();

Para retornar uma referência de uma função, use o operador de referência & em ambas a declaração da função e quando definindo o valor para a variável.

Exemplo #3 Retornando uma referência de uma função

    <?php
    function &retorna_referencia()
    {
        return $alguma_referencia;
    }

    $nova_referencia =& retorna_referencia();

Para mais detalhes sobre referências, leia a seção Referências.

## Funções variáveis

O PHP suporta o conceito de funções variáveis. Isto significa que se um nome de variável tem parênteses no final dela, o PHP procurará uma função com o mesmo nome, qualquer que seja a avaliação da variável, e tentará executá-la. Entre outras coisas, isto pode ser usado para implementar callbacks, tabelas de função e assim por diante.

Funções variáveis não funcionam com construtores de linguagem como echo, print, unset(), isset(), empty(), include, require e outras assim. Utilize uma função de encapsulamento para usar quaisquer um destes construtores como uma função variável.

Exemplo #1 Exemplo de funções variáveis

    <?php
    function foo() {
        echo "Chamou foo()\n";
    }

    function bar($arg = '')
    {
        echo "Chamou bar(); com argumento '$arg'.\n";
    }

    // Essa é uma função encapsuladora para echo()
    function echoit($string)
    {
        echo $string;
    }

    $func = 'foo';
    $func();        // Chama foo()

    $func = 'bar';
    $func('test');  // Chama bar()

    $func = 'echoit';
    $func('test');  // Chama echoit()

Um método de um objeto também pode ser chamado com a sintaxe de funções variáveis.

Exemplo #2 Exemplo de chamada de um método variável

    <?php
    class Foo
    {
        function MetodoVariavel()
        {
            $name = 'Bar';
            $this->$name(); // Isto chama o método Bar()
        }

        function Bar()
        {
            echo "Bar foi chamada!";
        }
    }

    $foo = new Foo();
    $funcname = "MetodoVariavel";
    $foo->$funcname();  // Isto chama $foo->MetodoVariavel()

Quando chamando métodos estáticos, uma chamada de função tem preferência que uma propriedade estática.

Exemplo #3 Método variávei com propriedades estáticas

    <?php
    class Foo
    {
        static $variable = 'propriedade estática';
        static function Variable()
        {
            echo "Método Variable chamado\n";
        }
    }

    echo Foo::$variable . "\n"; // Isto exibe 'static property'. Ele busca $variable no escopo da classe.
    $variable = "Variable";
    Foo::$variable();  // Isto chama $foo->Variable(), lendo a $variable no escopo da chamada.

O exemplo acima produzirá:

    static property
    Método Variable chamado

Exemplo #4 Chamáveis complexos

    <?php
    class Foo
    {
        static function bar()
        {
            echo "bar\n";
        }
        function baz()
        {
            echo "baz\n";
        }
    }

    $func = array("Foo", "bar");
    $func(); // exibe "bar"
    $func = array(new Foo, "baz");
    $func(); // exibe "baz"
    $func = "Foo::bar";
    $func(); // exibe "bar"

### Veja Também

- is_callable()
- call_user_func()
- function_exists()
- variáveis variáveis

## Funções internas

O PHP vem por padrão com muitas funções e construtores. Também existem funções que necessitam que uma extensão específica esteja compilada, se não erros fatais "undefined function" (função não definida) irão aparecer. Por exemplo, para usar as funções image como imagecreatetruecolor(), o PHP deve ser compilado com suporte GD. Ou, para usar mysqli_connect(), PHP deve ser compilado com suporte MySQLi. Existem muitas funções do núcleo que são incluídas em cada versão do PHP, como string e variable. Uma chamada a phpinfo() ou get_loaded_extensions() irá mostrar quais extensões estão carregadas no PHP. Note também que várias extensões são ativadas por padrão e que o manual do PHP é dividido por extensão. Veja configuração, instalação, e os capítulos individuais das extensões para como configurar o PHP.

A leitura e entendimento de um protótipo de função é explicado na seção do manual intitulada como ler uma definição de função. É importante perceber o que a função retorna ou se a função trabalha diretamente no valor passado como argumento. Por exemplo, str_replace() irá retornar a string modificada enquanto usort() trabalha na própria variável passada no argumento. Cada página do manual também contém informações específicas de cada função, como: parâmetros da função, mudanças de comportamento, valores de retorno tanto para sucesso e erros, como outras informações disponíveis. O conhecimento destas diferenças importantes é crucial para escrever corretamente seu código PHP.

> Nota: Se os parâmetros dados a uma função não forem o que ela espera, como passar um array onde uma string é esperada, o valor de retorno da função é indefinido. Neste caso provavelmente irá retornar `null` mas isto é apenas uma convenção, e você não pode depender disso. A partir do PHP 8.0.0, uma exceção TypeError é lançada nesses casos.

> Nota:

> Tipos escalares para funções embutidas são anuláveis por padrão no modo coercivo. A partir do PHP 8.1.0, passar `null` para um parâmetro de uma função interna que não é declarado anulável é desencorajado e emite um aviso de descontinuação no modo coercitivo para alinhar com o comportamento de funções definidas pelo usuário, onde tipos escalares precisam ser marcados como anuláveis explícitamente.

> Por exemplo, a função strlen() espera que o parâmetro `$string` seja uma string não anulável. Por razões históricas, o PHP permite a passagem de `null` para esse parâmetro no modo coercivo, e o parâmetro é implicitamente convertido para string, resultando em um valor `""`. Em contrapartida, um TypeError é emitido no modo estrito.

>     <?php
>     var_dump(strlen(null));
>     // "Deprecated: Passing null to parameter #1 ($string) of type string is deprecated" as of PHP 8.1.0
>     // int(0)

>     var_dump(str_contains("foobar", null));
>     // "Deprecated: Passing null to parameter #2 ($needle) of type string is deprecated" as of PHP 8.1.0
>     // bool(true)

### Veja Também

- function_exists()
- A referência das funções
- get_extension_funcs()
- dl()

## Funções anônimas

Funções anônimas, também conhecidas como `closures`, permitem a criação de funções que não têm o nome especificado. Elas são mais úteis como o valor de parâmetros do tipo callable, mas podem ter vários outros usos.

Funções anônimas são implementadas utilizando a classe Closure

Exemplo #1 Exemplo de função anônima

    <?php
    echo preg_replace_callback('~-([a-z])~', function ($match) {
        return strtoupper($match[1]);
    }, 'hello-world');
    // exibe helloWorld

Closures também podem ser utilizadas como valores de variáveis; o PHP automaticamente converte expressões assim em instâncias da classe interna Closure. Definindo um closure a uma variável usa a mesma sintaxe que qualquer outra definição, incluindo o ponto-e-vírgula:

Exemplo #2 Exemplo de como definir uma função anônima para uma variável

    <?php
    $greet = function($name) {
        printf("Hello %s\r\n", $name);
    };

    $greet('World');
    $greet('PHP');

Closures também podem herdar variáveis do escopo pai. Essas variáveis precisam ser referenciadas utilizando a instrução `use`. A partir do PHP 7.1, essas variáveis não devem incluir superglobals, $this, ou variáveis com o mesmo nome como um parâmetro. A declaração de tipo de retorno de uma função deve ser posicionada depois de uma instrução `use`.

Exemplo #3 Herdando variáveis do escopo anterior

    <?php
    $message = 'hello';

    // Sem "use"
    $example = function () {
        var_dump($message);
    };
    $example();

    // Inherit $message
    $example = function () use ($message) {
        var_dump($message);
    };
    $example();

    // Herdando valor da variável quando a função é definida,
    // não quando é chamada
    $message = 'world';
    $example();

    // Altera a mensagem
    $message = 'hello';

    // Herdando por referência
    $example = function () use (&$message) {
        var_dump($message);
    };
    $example();

    // O valor modificado no escopo pai
    // reflete quando a função é chamada
    $message = 'world';
    $example();

    // Closures também aceitam argumentos normais
    $example = function ($arg) use ($message) {
        var_dump($arg . ' ' . $message);
    };
    $example("hello");

    // Declaração de tipo de retorno após a instrução 'use'
    $example = function () use ($message): string {
        return "hello $message";
    };
    var_dump($example());

O exemplo acima produzirá algo semelhante a:

    Notice: Undefined variable: message in /example.php on line 6
    NULL
    string(5) "hello"
    string(5) "hello"
    string(5) "hello"
    string(5) "world"
    string(11) "hello world"
    string(11) "hello world"

A partir do PHP 8.0.0 a lista de variáveis herdadas no escopo podem incluir uma vírgula final, que será ignorada.

Herdar variáveis do escopo pai não é o mesmo que usar variáveis globais. Variáveis globais existem no escopo global, o qual é o mesmo não importa a função sendo executada. O escopo pai de um closure é a função no qual o closure foi declarado (não necessariamente a função a partir do qual ele foi chamado). Veja o exemplo a seguir:

Exemplo #4 Closures e escopo

    <?php
    // Um exemplo básico de carrinho de compras que contém uma lista de produtos
    // e a quantidade de cada produto. Inclui um método que
    // calcula o preço total dos itens no carrinho utilizando uma
    // closure como função de retorno.
    class Cart
    {
        const PRICE_BUTTER  = 1.00;
        const PRICE_MILK    = 3.00;
        const PRICE_EGGS    = 6.95;

        protected $products = array();

        public function add($product, $quantity)
        {
            $this->products[$product] = $quantity;
        }

        public function getQuantity($product)
        {
            return isset($this->products[$product]) ? $this->products[$product] :
                   FALSE;
        }

        public function getTotal($tax)
        {
            $total = 0.00;

            $callback =
                function ($quantity, $product) use ($tax, &$total)
                {
                    $pricePerItem = constant(__CLASS__ . "::PRICE_" .
                        strtoupper($product));
                    $total += ($pricePerItem * $quantity) * ($tax + 1.0);
                };

            array_walk($this->products, $callback);
            return round($total, 2);
        }
    }

    $my_cart = new Cart;

    // Adiciona alguns itens no carrinho
    $my_cart->add('butter', 1);
    $my_cart->add('milk', 3);
    $my_cart->add('eggs', 6);

    // Exibe o total com uma taxa de venda de 5%.
    print $my_cart->getTotal(0.05) . "\n";
    // O resultado é 54.29

Exemplo #5 Vinculação automática do `$this`

    <?php
    class Test
    {
        public function testing()
        {
            return function() {
                var_dump($this);
            };
        }
    }

    $object = new Test;
    $function = $object->testing();
    $function();

O exemplo acima produzirá:

    object(Test)#1 (0) {
    }

Quando declarada no contexto de uma classe, a classe corrente é automaticamente vinculada a ela, tornando `$this` disponível dentro do escopo da função. Se essa vinculação automática da classe corrente não for o comportamento esperado, funções anônimas estáticas podem ser utilizadas.

### Funções anônimas estáticas

Funções anônimas podem ser declaradas estaticamente. Evita que a classe corrente seja automaticamente vinculada a ela. Objetos também podem não ser vinculados a ela em tempo de execução.

Exemplo #6 Tentando utilizar o `$this` de dentro de uma função anônima estática

    <?php
    class Foo
    {
        function __construct()
        {
            $func = static function() {
                var_dump($this);
            };
            $func();
        }
    };
    new Foo();

O exemplo acima produzirá:

    Fatal error: Uncaught Error: Using $this when not in object context in script:7
    Stack trace:
    #0 script(9): Foo::{closure:Foo::__construct():6}()
    #1 script(12): Foo->__construct()
    #2 {main}
      thrown in script on line 7

Exemplo #7 Tentando vincular um objeto a uma função anônima estática

    <?php
    $func = static function() {
        // corpo da função
    };
    $func = $func->bindTo(new stdClass);
    $func();

O exemplo acima produzirá:

    Warning: Cannot bind an instance to a static closure, this will be an error in PHP 9 in script on line 5

    Fatal error: Uncaught Error: Value of type null is not callable in script:6
    Stack trace:
    #0 {main}
      thrown in script on line 6

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Closures criadas a partir de métodos mágicos podem aceitar parâmetros nomeados.
7.1.0 | Funções anônimas podem não incluir superglobals, $this, ou qualquer variável com o mesmo nome como um parâmetro.

### Notas

> Nota: É possível utilizar func_num_args(), func_get_arg() e func_get_args() dentro de closures.

## Funções de Seta

Funções de seta foram introduzidas a partir do PHP 7.4 como uma sintaxe mais concisa para funções anônimas.

Funções anônimas e funções de seta são implementadas usando a classe Closure.

Funções de seta têm a forma básica `fn (argument_list) => expr`.

Funções de seta possuem as mesmas características das funções anônimas, exceto que o uso de variáveis do escopo pai é sempre automático.

Quando uma variável usada na expressão é definida no escopo pai, ela será implicitamente capturada por valor. No exemplo a seguir, as funções $fn1 e $fn2comportam-se da mesma maneira.

Exemplo #1 Funções de seta capturam variáveis por valor automaticamente

    <?php
    $y = 1;

    $fn1 = fn($x) => $x + $y;
    // Equivalente ao usar $y por valor:
    $fn2 = function ($x) use ($y) {
        return $x + $y;
    };

    var_export($fn1(3));

O exemplo acima produzirá:

    4

Isso também funciona se as funções de seta estiverem aninhadas:

Exemplo #2 Funções de seta capturam variáveis por valor automaticamente, mesmo quando aninhadas

    <?php
    $z = 1;
    $fn = fn($x) => fn($y) => $x * $y + $z;
    // Outputs 51
    var_export($fn(5)(10));

Da mesma forma que funções anônimas, a sintaxe das funções de seta permitem assinaturas de função arbitrária, incluindo parâmetros e tipos de retorno, valores padrão, variadics, bem como por referência passando e retornando. Todos os exemplos válidos de funções de seta:

Exemplo #3 Exemplos de funções de seta

    <?php
    fn(array $x) => $x;
    static fn($x): int => $x;
    fn($x = 42) => $x;
    fn(&$x) => $x;
    fn&($x) => $x;
    fn($x, ...$rest) => $rest;

Funções de seta usam vinculação de variável por valor. Isso é aproximadamente equivalente a realizar um `use($x)` para cada variável $x usada dentro da funções de seta. Uma passagem de variável por valor, significa que não é possível modificar quaisquer valores do escopo externo. Funções anônimas podem ser usadas em vez disso para passagem de variável por referência.

Exemplo #4 Valores do escopo externo não podem ser modificados por funções de seta

    <?php
    $x = 1;
    $fn = fn() => $x++; // Não tem efeito
    $fn();
    var_export($x);  // Exibe 1

### Registro de Alterações

Versão | Descrição
--- | ---
7.4.0 | Funções de seta tornaram-se disponíveis.

### Notas

> Nota: É possível usar func_num_args(), func_get_arg(), e func_get_args() de dentro de uma função de seta.

## Sintaxe de Chamáveis de Primeira Classe

A sintaxe de chamáveis de primeira classe é introduzida a partir do PHP 8.1.0, como uma maneira de criar funções anônimas a partir de um chamável. Ela substitui a sintaxe de chamáveis existente usando strings e arrays. A vantagem dessa sintaxe é que ela é acessível à análise estática, e usa o escopo no ponto onde o chamável é adquirido.

A sintaxe `CallableExpr(...)` é usada para criar um objeto Closure a partir de um chamável. `CallableExpr` aceita qualquer expressão que possa ser diretamente chamada na gramática do PHP:

Exemplo #1 Sintaxe de chamável de primeira classe simples

    <?php
    class Foo {
       public function metodo() {}
       public static function metodoestatico() {}
       public function __invoke() {}
    }

    $obj = new Foo();
    $strClasse = 'Foo';
    $strMetodo = 'metodo';
    $strMetodoestatico = 'metodoestatico';

    $f1 = strlen(...);
    $f2 = $obj(...);  // objeto chamável
    $f3 = $obj->metodo(...);
    $f4 = $obj->$strMetodo(...);
    $f5 = Foo::metodoestatico(...);
    $f6 = $strClasse::$strMetodoestatico(...);

    // Chamável tradicional usando string, array
    $f7 = 'strlen'(...);
    $f8 = [$obj, 'metodo'](...);
    $f9 = [Foo::class, 'metodoestatico'](...);

> Nota:

> As reticências `...` são parte da sintaxe e não uma omissão.

`CallableExpr(...)` tem a mesma semântica que Closure::fromCallable(). Isto é, ao contrário de um chamável usando string e array, `CallableExpr(...)` respeita o escopo no ponto onde ela é criada:

Exemplo #2 Comparação de escopo de `CallableExpr(...)` e chamável tradicional

    <?php
    class Foo {
        public function obterMetodoPrivado() {
            return [$this, 'metodoPrivado'];
        }

        private function metodoPrivado() {
            echo __METHOD__, "\n";
        }
    }

    $foo = new Foo;
    $metodoPrivado = $foo->obterMetodoPrivado();
    $metodoPrivado();
    // Fatal error: Call to private method Foo::metodoPrivado() from global scope
    // Isso acontece porque a chamada é realizada fora de Foo e a visibilidade será verificada a partir desse ponto.

    <?php
    class Foo1 {
        public function obterMetodoPrivado() {
            // Usa o escopo onde o chamável é adquirido.
            return $this->metodoPrivado(...); // Idêntico a Closure::fromCallable([$this, 'metodoPrivado']);
        }

        private function metodoPrivado() {
            echo __METHOD__, "\n";
        }
    }

    $foo1 = new Foo1;
    $metodoPrivado = $foo1->obterMetodoPrivado();
    $metodoPrivado();  // Foo1::metodoPrivado

> Nota:

> Criação de objetos por essa sintaxe (por exemplo `new Foo(...)`) não é suportada porque a sintaxe `new Foo()` não é considerada uma chamada.

> Nota:

> A sintaxe de chamável de primeira classe não pode ser combinada com o operador nullsafe. Ambos os resultados a seguir resultam em um erro de tempo de compilação:

>     <?php
>     $obj?->metodo(...);
>     $obj?->prop->metodo(...);

# Classes e Objetos

## Índice

- Introdução
- O Básico
- Propriedades
- Ganchos de Propriedade
- Constantes de Classe
- Autocarregamento de Classes
- Construtores e Destrutores
- Visibilidade
- Herança de Objetos
- Operador de Resolução de Escopo (::)
- Palavra-Chave 'static'
- Abstração de Classes
- Interfaces de Objetos
- Traits
- Classes Anônimas
- Sobrecarga
- Iteração de Objetos
- Métodos Mágicos
- final
- Clonando Objetos
- Comparando Objetos
- Vinculações Estáticas Tardias
- Objetos e Referências
- Serialização de Objetos
- Covariância e Contravariância
- Objetos Lentos
- Lista de alterações da POO

## Introdução

O PHP inclui uma modelagem a objetos completa. Entre os recursos disponíveis há: visibilidade, classes e métodos abstratos e finais, métodos mágicos adicionais, interfaces e clonagem.

O PHP trata objetos da mesma maneira que referências ou manipuladores, significando que cada variável contém uma referência a um objeto ao invés de uma cópia de todo o objeto. Veja Objetos e Referências

Dica

Veja também o Guia de nomenclatura em espaço de usuário.

## O Básico

### Classe

A definição de uma classe começa com a palavra chave `class`, seguida do nome da classe, seguido de um par de chaves que englobam as definições de propriedades e métodos pertencentes à classe.

O nome de uma classe pode ser qualquer identificador válido, que não seja uma palavra reservada do PHP. A partir do PHP 8.4.0, usar um único sublinhado `_` como nome de classe foi descontinuado. Um nome de classe válido começa com uma letra ou sublinhado, seguido de qualquer sequência de letras, números e sublinhados. Como uma expressão regular, pode ser expressada assim: `^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$`.

Uma classe pode conter suas próprias constantes, variáveis (chamadas de "propriedades") e funções (chamadas de "métodos").

Exemplo #1 Definição Simples de uma Classe

    <?php
    class SimpleClass
    {
        // declaração de propriedade
        public $var = 'um valor padrão';

        // declaração de método
        public function displayVar() {
            echo $this->var;
        }
    }
    ?>

A pseudo-variável $this está disponível quando um método é chamado a partir de um contexto de um objeto. $this é o valor do objeto chamado.

Aviso

Chamar um método não estático de maneira estática lança um Error. Anteriormente ao PHP 8.0.0, isto iria gerar um aviso de descontinuação, e $this estaria indefinido.

Exemplo #2 Alguns exemplos da pseudo variável $this

    <?php
    class A
    {
        function foo()
        {
            if (isset($this)) {
                echo '$this está definida (';
                echo get_class($this);
                echo ")\n";
            } else {
                echo "\$this não está definida.\n";
            }
        }
    }

    class B
    {
        function bar()
        {
            A::foo();
        }
    }

    $a = new A();
    $a->foo();

    A::foo();

    $b = new B();
    $b->bar();

    B::bar();
    ?>

Saída do exemplo acima no PHP 7:

    $this está definida (A)

    Deprecated: Non-static method A::foo() should not be called statically in %s  on line 27
    $this não está definida.

    Deprecated: Non-static method A::foo() should not be called statically in %s  on line 20
    $this não está definida.

    Deprecated: Non-static method B::bar() should not be called statically in %s  on line 32

    Deprecated: Non-static method A::foo() should not be called statically in %s  on line 20
    $this não está definida.

Saída do exemplo acima no PHP 8:

    $this está definida (A)

    Fatal error: Uncaught Error: Non-static method A::foo() cannot be called statically in %s :27
    Stack trace:
    #0 {main}
      thrown in %s  on line 27

#### Classes somente leitura

A partir do PHP 8.2.0, uma classe pode ser marcada com o modificador readonly. Marcar uma classe como readonly irá acrescentar o modificador readonly em cada propriedade declarada, e prevenir a criação de propriedades dinâmicas. Além disso, será impossível de acrescentar suportes a propriedades dinâmicas utilizando o atributo AllowDynamicProperties. Acrescentar o atributo em classes somente leitura irá disparar um erro de compilação.

    <?php
    #[\AllowDynamicProperties]
    readonly class Foo {
    }

    // Fatal error: Cannot apply #[AllowDynamicProperties] to readonly class Foo
    ?>

Como as propriedades estáticas ou sem tipo não podem ser marcadas com o modificador `readonly`, as classes somente leitura também não podem declará-las:

    <?php
    readonly class Foo
    {
        public $bar;
    }

    // Fatal error: Readonly property Foo::$bar must have type
    ?>

    <?php
    readonly class Foo
    {
        public static int $bar;
    }

    // Fatal error: Readonly class Foo cannot declare static properties
    ?>

Uma classe readonly pode ser estendida se, e somente se, a classe filha também ser uma classe readonly.

### Nova instância

Para criar uma instância de uma classe, a instrução `new` deve ser utilizada. Um objeto sempre será criado a não ser que a classe tenha um construtor definido que dispare uma exceção em caso de erro. Classes devem ser definidas antes de instanciadas (e em alguns casos isso é obrigatório).

Se uma variável contendo uma string com o nome da classe for utilizado com `new`, uma nova instância da classe será criada. Se a classe estiver dentro de um namespace, seu nome qualificado completo deve ser utilizado ao fazer isto.

> Nota:

> Se não há argumentos a serem passados para o construtor da classe, os parênteses após o nome da classe podem ser omitidos.

Exemplo #3 Criando uma instância

    <?php
    class SimpleClass {
    }

    $instance = new SimpleClass();
    var_dump($instance);

    // Também pode ser feito com uma variável:
    $className = 'SimpleClass';
    $instance = new $className(); // new SimpleClass()
    var_dump($instance);
    ?>

A partir do PHP 8.0.0, usar `new` com expressões arbitrárias é suportado. Isso permite instanciação mais complexa se a expressão produzir uma string. As expressões devem ser envolvidas em parênteses.

Exemplo #4 Criando uma instância usando uma expressão arbitrária

No exemplo fornecido mostramos múltiplos exemplos de expressões arbitrárias válidas que produzem um nome de classe. Isto mostra uma chamada para uma função, concatenação de string, e a constante `::class`.

    <?php

    class ClasseA extends \stdClass {}
    class ClasseB extends \stdClass {}
    class ClasseC extends ClasseB {}
    class ClasseD extends ClasseA {}

    function obterAlgumaClasse(): string
    {
        return 'ClasseA';
    }

    var_dump(new (obterAlgumaClasse()));
    var_dump(new ('Classe' . 'B'));
    var_dump(new ('Classe' . 'C'));
    var_dump(new (ClasseD::class));
    ?>

Saída do exemplo acima no PHP 8:

    object(ClasseA)#1 (0) {
    }
    object(ClasseB)#1 (0) {
    }
    object(ClasseC)#1 (0) {
    }
    object(ClasseD)#1 (0) {
    }

No contexto da classe, é possível criar um novo objeto com `new self` e `new parent`.

Ao atribuir uma instância de uma classe já criada, a uma variável nova, a variável nova irá acessar a mesma instância do objeto que foi atribuído. Este comportamento se mantém ao se passar instâncias a uma função. Uma cópia de um objeto criado pode ser feita clonando o mesmo.

Exemplo #5 Atribuição de Objetos

    <?php
    class SimpleClass {
        public string $var;
    }

    $instance = new SimpleClass();

    $assigned   =  $instance;
    $reference  =& $instance;

    $instance->var = '$assigned terá esse valor';

    $instance = null; // $instance e $reference tornam-se nulos

    var_dump($instance);
    var_dump($reference);
    var_dump($assigned);
    ?>

O exemplo acima produzirá:

    NULL
    NULL
    object(SimpleClass)#1 (1) {
       ["var"]=>
         string(30) "$assigned terá esse valor"
    }

É possível usar algumas formas de criar instâncias de um objeto:

Exemplo #6 Criando novos objetos

    <?php

    class Test
    {
        public static function getNew()
        {
            return new static();
        }
    }

    class Child extends Test {}

    $obj1 = new Test();  // Usando o nome da classe
    $obj2 = new $obj1(); // Usando a variável que contém o objeto
    var_dump($obj1 !== $obj2);

    $obj3 = Test::getNew();   // Usando o método da classe
    var_dump($obj3 instanceof Test);

    $obj4 = Child::getNew();  // Usando o método através da classe filha
    var_dump($obj4 instanceof Child);

    ?>

O exemplo acima produzirá:

    bool(true)
    bool(true)
    bool(true)

É possível acessar um membro do objeto recém criado em uma expressão simples:

Exemplo #7 Acessando um membro de um novo objeto criado

    <?php
    echo (new DateTime())->format('Y'), PHP_EOL;

    // parênteses envolvendo o objeto são opcionais a partir do PHP 8.4.0
    echo new DateTime()->format('Y'), PHP_EOL;
    ?>

O exemplo acima produzirá algo semelhante a:

    2025
    2025

> Nota: Anteriormente ao PHP 7.1, os argumentos não são avaliados se não houver um construtor definido.

### Propriedades e métodos

Propriedades e métodos de classe vivem em "namespaces" separados, de forma que é possível ter uma propriedade e método com mesmos nomes. A referência a propriedades e métodos tem a mesma notação, e a decisão de se uma propriedade será acessada ou uma chamada a um método feita, depende somente do contexto, ou seja, se está tentando acessar uma variável ou chamar um método.

Exemplo #8 Acesso a propriedade vs. chamar um método

    <?php
    class Foo
    {
        public $bar = 'propriedade';

        public function bar() {
            return 'método';
        }
    }

    $obj = new Foo();
    echo $obj->bar, PHP_EOL, $obj->bar(), PHP_EOL;

O exemplo acima produzirá:

    propriedade
    método

Isto significa que chamar diretamente uma função anônima atribuída a uma propriedade não é possível. Em vez disso, por exemplo, a propriedade deve primeiro ser atribuída a uma variável. É possível chamar uma propriedade diretamente colocando-a entre parênteses.

Exemplo #9 Chamando uma função anônima armazenada em uma propriedade

    <?php
    class Foo
    {
        public $bar;

        public function __construct() {
            $this->bar = function() {
                return 42;
            };
        }
    }

    $obj = new Foo();

    echo ($obj->bar)(), PHP_EOL;

O exemplo acima produzirá:

    42

### Herança

Uma classe pode herdar constantes, métodos e propriedades de outra classe usando a palavra-chave `extends` na declaração da classe. Não é possível herdar múltiplas classes; uma classe só pode herdar uma classe base.

Os métodos e propriedades herdados podem ser sobrescritos declarando-os com o mesmo nome definido na classe base. Entretanto, se a classe mãe definiu um método ou constante como final, eles não poderão ser sobrescritos. É possível acessar os métodos sobrescritos ou propriedades estáticas referenciado-os com parent::.

> Nota: A partir do PHP 8.1.0, constantes podem ser declaradas como finais.

Exemplo #10 Herança simples de classe

    <?php
    class SimpleClass
    {
        function displayVar()
        {
            echo "Classe Pai\n";
        }
    }

    class ExtendClass extends SimpleClass
    {
        // Redefine o método pai
        function displayVar()
        {
            echo "Classe Herdeira\n";
            parent::displayVar();
        }
    }

    $extended = new ExtendClass();
    $extended->displayVar();
    ?>

O exemplo acima produzirá:

    Classe Herdeira
    Classe Pai

#### Regras de compatibilidade de assinaturas

Ao sobrescrever um método, sua assinatura precisa ser compatível com a do método original. Caso contrário um erro fatal é emitido, ou, antes do PHP 8.0.0, um alerta `E_WARNING` seria gerado. Uma assinatura é compatível se ela respeita as regras de variância, se ela transforma um parâmetro obrigatório em opcional, se ela adiciona novos parâmetros opcionais, e se ela não restringe ou apenas aumenta a visibilidade. Isso é conhecido como Princípio de Substituição de Liskov, ou LSP. O construtor, e membros `private` não precisam seguir essas regras de compatibilidade, e portanto não há emissão de erros fatais no caso de assinaturas incompatíveis.

Exemplo #11 Métodos compatíveis

    <?php

    class Base
    {
        public function foo(int $a) {
            echo "Valid\n";
        }
    }

    class Extend1 extends Base
    {
        function foo(int $a = 5)
        {
            parent::foo($a);
        }
    }

    class Extend2 extends Base
    {
        function foo(int $a, $b = 5)
        {
            parent::foo($a);
        }
    }

    $extended1 = new Extend1();
    $extended1->foo();
    $extended2 = new Extend2();
    $extended2->foo(1);

O exemplo acima produzirá:

    Valid
    Valid

Os exemplos a seguir demonstram que um método derivado, que remove um parâmetro ou transforma um parâmetro opcional em mandatório, não é compatível com o método original.

Exemplo #12 Erro fatal quando um método derivado remove um parâmetro

    <?php

    class Base
    {
        public function foo(int $a = 5) {
            echo "Válido?\n";
        }
    }

    class Extend extends Base
    {
        function foo()
        {
            parent::foo(1);
        }
    }

A saída do exemplo acima no PHP 8 é semelhante a:

    Fatal error: Declaration of Extend::foo() must be compatible with Base::foo(int $a = 5) in /in/evtlq on line 13

Exemplo #13 Erro fatal quando um método derivado transforma um parâmetro opcional em mandatório

    <?php

    class Base
    {
        public function foo(int $a = 5) {
            echo "Válido?\n";
        }
    }

    class Extend extends Base
    {
        function foo(int $a)
        {
            parent::foo($a);
        }
    }

A saída do exemplo acima no PHP 8 é semelhante a:

    Fatal error: Declaration of Extend::foo(int $a) must be compatible with Base::foo(int $a = 5) in /in/qJXVC on line 13

Aviso

Renomear um parâmetro em uma classe derivada não é uma quebra de assinatura. Entretanto isso é desencorajado porque ocasionará um Error se argumentos nomeados forem utilizados na chamada.

Exemplo #14 Erro ao utilizar argumentos renomeados em uma classe derivada

    <?php

    class A {
        public function test($foo, $bar) {}
    }

    class B extends A {
        public function test($a, $b) {}
    }

    $obj = new B;

    // Passando parâmetros de acordo com o contrato de A::test()
    $obj->test(foo: "foo", bar: "bar"); // ERROR!

O exemplo acima produzirá algo semelhante a:

    Fatal error: Uncaught Error: Unknown named parameter $foo in /in/XaaeN:14
    Stack trace:
    #0 {main}
      thrown in /in/XaaeN on line 14

### ::class

A palavra-chave `class` também pode ser utilizada para resolução de nome de classes. Pode-se obter o nome completo e qualificado da classe `ClassName` utilizando `ClassName::class`. Isso é particularmente útil em classes com namespaces.

Exemplo #15 Resolução de nome da classe

    <?php
    namespace NS {
        class ClassName {
        }

        echo ClassName::class;
    }
    ?>

O exemplo acima produzirá:

    NS\ClassName

> Nota:

> A resolução do nome de classe através de `::class` é uma transformação em tempo de compilação. Isso significa que no momento em que o texto do nome da classe é criado, o auto carregamento ainda não ocorreu. Como consequência, nomes de classe são expandidos mesmo se a classe não existir. Não é emitido erro nestes casos.

> Exemplo #16 Resolução de um nome de classe ausente

>     <?php
>     print Does\Not\Exist::class;
>     ?>

> O exemplo acima produzirá:

>     Does\Not\Exist

A partir do PHP 8.0.0, a constante `::class` também pode ser utilizada em objetos. Essa resolução acontece em tempo de execução, e não em tempo de compilação. O efeito é o mesmo de chamar get_class() em um objeto.

Exemplo #17 Resolução de nome de objeto

    <?php
    namespace NS {
        class ClassName {
        }

        $c = new ClassName();
        print $c::class;
    }
    ?>

O exemplo acima produzirá:

    NS\ClassName

### Métodos e propriedades nullsafe

A partir do PHP 8.0.0, propriedades e métodos também podem ser acessados com o operador "nullsafe": `?->`. O operador nullsafe funciona da mesma forma que os acessos de métodos e variáveis, exceto que se o objeto referenciado é `null`, então `null` será retornado ao invés de uma exceção ser lançada. Se uma desreferência for parte de uma cadeia de chamadas, o resto da cadeia é ignorado.

O resultado é similar a encapsular cada acesso dentro de um teste is_null(), mas mais compacto.

Exemplo #18 Operador nullsafe

    <?php

    // A partir do PHP 8.0.0, esta linha:
    $result = $repository?->getUser(5)?->name;

    // É o equivalente ao seguinte código:
    if (is_null($repository)) {
        $result = null;
    } else {
        $user = $repository->getUser(5);
        if (is_null($user)) {
            $result = null;
        } else {
            $result = $user->name;
        }
    }
    ?>

> Nota:

> O operador nullsafe é melhor utilizado quando null é considerado um valor válido e esperado de uma propriedade ou retorno de método. Para indicar um erro, uma exceção lançada é preferível.

## Propriedades

Variáveis membros de classes são chamados de propriedades. Eles também são conhecidos por outros termos, como campos (field), mas para propósitos deste manual será utilizado o termo propriedade. Elas podem ser definidas com ao menos um modificador opcional (ver Visibilidade, Palavra-Chave 'static', ou, a partir do PHP 8.1.0, readonly), (exceto para propriedades `readonly` properties), a partir do PHP 7.4, seguido também de uma declaração de tipo, finalizando com um nome de variável comum. Essa declaração pode ainda incluir uma inicialização, desde que essa inicialização seja um valor constante.

> Nota:

> Uma forma obsoleta de declarar propriedades de classe é através da instrução `var` ao invés de um modificador.

> Nota: Uma propriedade declarada sem um modificador de Visibilidade funcionará como uma propriedade `public`.

Internamente às classes, métodos não estáticos podem ser acessados utilizando-se `->` (operador de objeto): $this->property (onde `property` é o nome da propriedade). Propriedades estáticas são acessadas utilizando-se o operador `::` (duplo dois pontos), assim: self::$property. Veja Palavra-Chave 'static' para mais informações sobre a diferença de propriedades estáticas e não estáticas.

A pseudo-variável $this está disponível dentro de qualquer classe de método chamada no contexto do objeto. $this é uma referência ao objeto de contexto do qual o método foi chamado.

Exemplo #1 Declaração de propriedades

    <?php
    class SimpleClass
    {
       public $var1 = 'Olá ' . 'mundo';
       public $var2 = <<<EOD
    Olá mundo
    EOD;
       public $var3 = 1+2;
       // Declaração de propriedade inválida
       public $var4 = self::myStaticMethod();
       public $var5 = $myVar;

       // Declaração de propriedade válida
       public $var6 = myConstant;
       public $var7 = [true, false];

       public $var8 = <<<'EOD'
    Olá mundo
    EOD;

       // Sem um modificador de visibilidade:
       static $var9;
       readonly int $var10;
    }
    ?>

> Nota:

> Existem várias funções para manipular classes e objetos. Veja a seção sobre funções sobre classes/objetos para mais detalhes.

### Declaração de propriedades tipadas

A partir do PHP 7.4.0, definições de propriedades podem incluir uma Declarações de tipo, com exceção do tipo callable.

Exemplo #2 Exemplo de propriedades tipadas

    <?php

    class User
    {
        public int $id;
        public ?string $name;

        public function __construct(int $id, ?string $name)
        {
            $this->id = $id;
            $this->name = $name;
        }
    }

    $user = new User(1234, null);

    var_dump($user->id);
    var_dump($user->name);

    ?>

O exemplo acima produzirá:

    int(1234)
    NULL

Propriedades tipadas precisam ser inicializadas antes de serem acessadas, senão um Error é lançado.

Exemplo #3 Acessando propriedades

    <?php

    class Forma
    {
        public int $numeroDeLados;
        public string $nome;

        public function setnumeroDeLados(int $numeroDeLados): void
        {
            $this->numeroDeLados = $numeroDeLados;
        }

        public function setNome(string $nome): void
        {
            $this->nome = $nome;
        }

        public function getnumeroDeLados(): int
        {
            return $this->numeroDeLados;
        }

        public function getNome(): string
        {
            return $this->nome;
        }
    }

    $triangle = new Forma();
    $triangle->setNome("triângulo");
    $triangle->setnumeroDeLados(3);
    var_dump($triangle->getNome());
    var_dump($triangle->getnumeroDeLados());

    $circle = new Forma();
    $circle->setNome("cículo");
    var_dump($circle->getNome());
    var_dump($circle->getnumeroDeLados());
    ?>

O exemplo acima produzirá:

    string(9) "triângulo"
    int(3)
    string(7) "círculo"

    Fatal error: Uncaught Error: Typed property Forma::$numeroDeLados must not be accessed before initialization

### Propriedades somente leitura

A partir do PHP 8.1.0, uma propriedade pode ser declarada com o modificador `readonly`, o que evita modificação da propriedade após a inicialização. Antes do PHP 8.4.0, uma propriedade `readonly` era implicitamente private-set e só poderia ser escrita na mesma classe. A partir do PHP 8.4.0, as propriedades `readonly` são implicitamente `protected(set)`, por isso podem ser definidas a partir de classes filhas. Isso pode ser substituído explicitamente, se desejado.

Exemplo #4 Exemplo de propriedade somente leitura

    <?php

    class Test {
       public readonly string $prop;

       public function __construct(string $prop) {
           // Inicialização permitida.
           $this->prop = $prop;
       }
    }

    $test = new Test("foobar");
    // Legal read.
    var_dump($test->prop); // string(6) "foobar"

    // Modificação ilegal. Não importa que o valor seja o mesmo.
    $test->prop = "foobar";
    // Error: Cannot modify readonly property Test::$prop
    ?>

> Nota:

> O modificador readonly somente pode ser aplicado a propriedades tipadas. Uma propriedade somente leitura sem restrições de tipo pode ser declarada utilizando o tipo Misto.

> Nota:

> Propriedades estáticas não são suportadas.

Uma propriedade somente leitura somente pode ser inicializada uma única vez, e somente do escopo onde ela foi declarada. Quaisquer outras modificações da propriedade resultam em um Error.

Exemplo #5 Inicilização ilegal de propriedades somente leitura.

    <?php
    class Test1 {
        public readonly string $prop;
    }

    $test1 = new Test1;
    // Inicialização ilegal fora do escopo privado.
    $test1->prop = "foobar";
    // Error: Cannot initialize readonly property Test1::$prop from global scope
    ?>

> Nota:

> Especificar um valor default para uma propriedade somente leitura não é permitido, porque uma propriedade com um valor default é essencialmente uma constante, e portanto não tem outro propósito.

>     <?php

>     class Test {
>         // Fatal error: Readonly property Test::$prop cannot have default value
>         public readonly int $prop = 42;
>     }
>     ?>

> Nota:

> Propriedades somente leitura não podem ser unset() depois de inicializadas. Entretanto é possível realizar essa operação antes da inicialização, dentro do escopo onde a variável foi declarada.

Nenhum tipo de modificação é permitido, e o seguintes casos resultarão em um Error:

    <?php

    class Test {
        public function __construct(
            public readonly int $i = 0,
            public readonly array $ary = [],
        ) {}
    }

    $test = new Test;
    $test->i += 1;
    $test->i++;
    ++$test->i;
    $test->ary[] = 1;
    $test->ary[0][] = 1;
    unset($test->ary[0]);
    $ref =& $test->i;
    $test->i =& $ref;
    byRef($test->i);
    foreach ($test as &$prop);
    ?>

Entretanto, propriedades somente leitura não proíbem mutação. Objetos ou recursos armazenados em propriedades somente leitura ainda podem ser modificados internamente:

    <?php

    class Test {
        public function __construct(public readonly object $obj) {}
    }

    $test = new Test(new stdClass);
    // Modificação interna permitida
    $test->obj->foo = 1;
    // Reinicialização proibida.
    $test->obj = new stdClass;
    ?>

A partir do PHP 8.3.0, propriedades somente-leitura podem ser reinicializadas ao clonar um objeto usando o método __clone().

Exemplo #6 Propriedades somente-leitura e clonagem

    <?php
    class Test1 {
        public readonly ?string $prop;

        public function __clone() {
            $this->prop = null;
        }

        public function setProp(string $prop): void {
            $this->prop = $prop;
        }
    }

    $test1 = new Test1;
    $test1->setProp('foobar');

    $test2 = clone $test1;
    var_dump($test2->prop); // NULL
    ?>

### Propriedades dinâmicas

Ao tentar atribuir uma propriedade inexistente em um object, o PHP irá automaticamente criar a propriedade. Essa propriedade criada dinamicamente será disponível apenas naquela instância específica.

Aviso

Propriedades dinâmicas foram descontinuadas a partir do PHP 8.2.0. É recomendado declarar todas as propriedades previamente. Para suportar nomes de propriedades arbitrárias, a classe deve implementar os métodos mágicos __get() e __set(). Como último recurso, a classe pode ser marcada com o atributo `#[\AllowDynamicProperties]`.

## Ganchos de Propriedade

Ganchos de propriedade, também conhecidos como "acessadores de propriedade" em algumas outras linguagens, são uma forma de interceptar e substituir o comportamento de leitura e gravação de uma propriedade. Esta funcionalidade tem dois propósitos:

1. Permite que as propriedades sejam usadas diretamente, sem os métodos 'get' e 'set', deixando aberta a opção de incluir comportamento adicional no futuro. Isso torna desnecessários a maioria dos métodos 'get'/'set' padronizados, mesmo sem usar ganchos.
2. Permite propriedades que descrevem um objeto sem a necessidade de armazenar um valor diretamente.

Existem dois ganchos disponíveis em propriedades não estáticas: `get` e `set`. Eles permitem substituir o comportamento de leitura e gravação de uma propriedade, respectivamente. Os ganchos estão disponíveis para propriedades tipadas e não tipadas.

Uma propriedade pode ser "apoiada" ou "virtual". Uma propriedade apoiada é aquela que realmente armazena um valor. Qualquer propriedade que não tenha ganchos será apoiada. Uma propriedade virtual é aquela que possui ganchos e esses ganchos não interagem com a propriedade em si. Nesse caso, os ganchos são efetivamente iguais aos métodos, e o objeto não usa nenhum espaço para armazenar um valor para aquela propriedade.

Ganchos de propriedade são incompatíveis com propriedades `readonly` (somente-leitura). Se houver necessidade de restringir acesso a uma operação `get` ou `set` além de alterar seu comportamento, deve ser usada a visibilidade de propriedade assimétrica.

> Nota: Informação de Versão
> Ganchos de Propriedade foram introduzidos no PHP 8.4.

### Sintaxe Básica de Gancho

A sintaxe geral para declarar um gancho é a seguinte.

Exemplo #1 Ganchos de propriedade (versão completa)

    <?php
    class Example
    {
        private bool $modified = false;

        public string $foo = 'default value' {
            get {
                if ($this->modified) {
                    return $this->foo . ' (modified)';
                }
                return $this->foo;
            }
            set(string $value) {
                $this->foo = strtolower($value);
                $this->modified = true;
            }
        }
    }

    $example = new Example();
    $example->foo = 'changed';
    print $example->foo;
    ?>

A propriedade $foo termina com `{}`, em vez de ponto e vírgula. Isso indica a presença de ganchos. Ambos os ganchos `get` e `set` são definidos, embora seja permitido definir apenas um ou outro. Ambos os ganchos possuem um corpo, indicado por `{}`, que pode conter código arbitrário.

O gancho `set` permite adicionalmente especificar o tipo e o nome de um valor recebido, usando a mesma sintaxe de um método. O tipo deve ser igual ao tipo da propriedade ou uma contravariante (mais amplo) a ela. Por exemplo, uma propriedade do tipo string poderia ter um gancho `set` que aceita string|Stringable, mas não aquele que aceita apenas array.

Pelo menos um dos ganchos faz referência a `$this->foo`, a própria propriedade. Isso significa que a propriedade será "apoiada". Ao chamar `$example->foo = 'changed'`, a string fornecida será primeiro convertida em minúsculas e depois salva no valor de apoio. Ao ler a propriedade, o valor salvo anteriormente pode ser anexado condicionalmente com texto adicional.

Existem também várias variantes de sintaxe abreviada para lidar com casos comuns.

Se o gancho `get` for uma expressão única, `{}` poderá ser omitido e substituído por uma expressão de seta.

Exemplo #2 Expressão para leitura de propriedade

Este exemplo é equivalente ao anterior.

    <?php
    class Example
    {
        private bool $modified = false;

        public string $foo = 'default value' {
            get => $this->foo . ($this->modified ? ' (modified)' : '');

            set(string $value) {
                $this->foo = strtolower($value);
                $this->modified = true;
            }
        }
    }
    ?>

Se o tipo de parâmetro do gancho `set` for igual ao tipo de propriedade (o que é típico), ele poderá ser omitido. Nesse caso, o valor a ser definido recebe automaticamente o nome $value.

Exemplo #3 Padrão de definição de propriedade

Este exemplo é equivalente ao anterior.

    <?php
    class Example
    {
        private bool $modified = false;

        public string $foo = 'default value' {
            get => $this->foo . ($this->modified ? ' (modified)' : '');

            set {
                $this->foo = strtolower($value);
                $this->modified = true;
            }
        }
    }
    ?>

Se o gancho `set` estiver apenas definindo uma versão modificada do valor passado, então ele também poderá ser simplificado para uma expressão de seta. O valor avaliado pela expressão será definido no valor de apoio.

Exemplo #4 Expressão para definição de propriedade

    <?php
    class Example
    {
        private bool $modified = false;

        public string $foo = 'default value' {
            get => $this->foo . ($this->modified ? ' (modified)' : '');
            set => strtolower($value);
        }
    }
    ?>

Este exemplo não é exatamente equivalente ao anterior, pois também não modifica `$this->modified`. Se várias instruções forem necessárias no corpo do gancho definido, use a versão entre chaves.

Uma propriedade pode implementar zero, um ou ambos os ganchos conforme a situação exigir. Todas as versões abreviadas são mutuamente independentes. Ou seja, usar um 'get' curto com um 'set' longo, ou um 'set' curto com um tipo explícito, ou assim por diante, é válido.

Em uma propriedade apoiada, omitir um gancho `get` ou `set` significa que o comportamento padrão de leitura ou gravação será usado.

> Nota: Ganchos podem ser definidos ao usar promoção de propriedade de construtor. No entanto, quando isso é feito, os valores fornecidos ao construtor precisam ter o tipo associado à propriedade correspondido, independentemente do que o gancho `set` possa permitir. Considere o seguinte:

>     <?php
>     class Example
>     {
>         public function __construct(
>             public private(set) DateTimeInterface $created {
>                 set (string|DateTimeInterface $value) {
>                     if (is_string($value)) {
>                         $value = new DateTimeImmutable($value);
>                     }
>                     $this->created = $value;
>                 }
>             },
>         ) {
>         }
>     }

> Internamente, o mecanismo decompõe para o seguinte:

>     <?php
>     class Example
>     {
>         public private(set) DateTimeInterface $created {
>             set (string|DateTimeInterface $value) {
>                 if (is_string($value)) {
>                     $value = new DateTimeImmutable($value);
>                 }
>                 $this->created = $value;
>             }
>         }

>         public function __construct(
>             DateTimeInterface $created,
>         ) {
>             $this->created = $created;
>         }
>     }

> Quaisquer tentativas de definir a propriedade fora do construtor permitirão valores do tipo string ou DateTimeInterface mas o construtor permitirá apenas DateTimeInterface. Isto acontece porque o tipo definido para a propriedade (DateTimeInterface) é usado como o tipo do parâmetro dentro da assinatura do construtor, não importando o que o gancho `set` permite. Se este tipo de comportamento do construtor for necessário, a promoção de propriedade no construtor não pode ser usada.

### Propriedades virtuais

Propriedades virtuais são propriedades que não possuem valor de apoio. Uma propriedade é virtual se nem seu gancho `get` nem seu gancho `set` fizerem referência à própria propriedade usando sintaxe exata. Ou seja, uma propriedade chamada `$foo` cujo gancho contém `$this->foo` será apoiada. Mas a seguinte não é uma propriedade apoiada e causará erro:

Exemplo #5 Propriedade virtual inválida

    <?php
    class Example
    {
        public string $foo {
            get {
                $temp = __PROPERTY__;
                return $this->$temp; // Não faz referência a $this->foo, por isso não é válida.
            }
        }
    }
    ?>

Para propriedades virtuais, se um gancho for omitido, essa operação não existe e tentar usá-la produzirá um erro. As propriedades virtuais não ocupam espaço de memória em um objeto. As propriedades virtuais são adequadas para propriedades "derivadas", como aquelas que são a combinação de duas outras propriedades.

Exemplo #6 Propriedade virtual

    <?php
    class Rectangle
    {
        // Uma propriedade virtual.
        public int $area {
            get => $this->h * $this->w;
        }

        public function __construct(public int $h, public int $w) {}
    }

    $s = new Rectangle(4, 5);
    print $s->area; // exibe 20
    $s->area = 30; // Erro, pois não há operação 'set' definida.
    ?>

Definir ambos os ganchos `get` e `set` em uma propriedade virtual também é permitido.

### Escopo

Todos os ganchos operam no escopo do objeto que está sendo modificado. Isso significa que eles têm acesso a todos os métodos públicos, privados ou protegidos do objeto, bem como a quaisquer propriedades públicas, privadas ou protegidas, incluindo propriedades que possam ter seus próprios ganchos de propriedade. Acessar outra propriedade de dentro de um gancho não ignora os ganchos definidos nesta propriedade.

A implicação mais notável disso é que ganchos não triviais podem fazer subchamadas a um método arbitrariamente complexo, se desejarem.

Exemplo #7 Chamando um método a partir de um gancho

    <?php
    class Person {
        public string $phone {
            set => $this->sanitizePhone($value);
        }

        private function sanitizePhone(string $value): string {
            $value = ltrim($value, '+');
            $value = ltrim($value, '1');

            if (!preg_match('/\d\d\d\-\d\d\d\-\d\d\d\d/', $value)) {
                throw new \InvalidArgumentException();
            }
            return $value;
        }
    }
    ?>

### Referências

Como a presença de ganchos intercepta o processo de leitura e gravação de propriedades, eles causam problemas ao adquirir uma referência a uma propriedade ou com modificação indireta, como `$this->arrayProp['chave'] = 'valor';`. Isso ocorre porque qualquer tentativa de modificação do valor por referência ignoraria um gancho 'set', se algum estiver definido.

No caso raro de ser necessário obter uma referência a uma propriedade que tenha ganchos definidos, o gancho `get` pode ser prefixado com `&` para fazer com que ele retorne por referência. Definir `get` e `&get` na mesma propriedade é um erro de sintaxe.

Não é permitido definir ganchos `&get` e `set` em uma propriedade apoiada. Conforme observado acima, escrever no valor retornado por referência ignoraria o gancho `set`. Nas propriedades virtuais, não há nenhum valor comum necessário compartilhado entre os dois ganchos, portanto, é permitido definir ambos.

Escrever em um índice de uma propriedade de array também envolve uma referência implícita. Por esse motivo, gravar em uma propriedade de array apoiada com ganchos definidos é permitido se e somente se ela definir apenas um gancho `&get`. Em uma propriedade virtual, escrever no array retornado de `get` ou `&get` é legal, mas se isso terá algum impacto no objeto depende da implementação do gancho.

Substituir toda a propriedade do array é aceitável e se comporta da mesma forma que qualquer outra propriedade. Trabalhar apenas com elementos do array requer cuidados especiais.

### Herança

#### Ganchos finais

Um gancho pode também ser declarado como final, neste caso ele não pode ser substituído.

Exemplo #8 Ganchos finais

    <?php
    class User
    {
        public string $username {
            final set => strtolower($value);
        }
    }

    class Manager extends User
    {
        public string $username {
            // Isto é permitido
            get => strtoupper($this->username);

            // Mas isto NÃO é permitido, porque 'set' é final na classe superior.
            set => strtoupper($value);
        }
    }
    ?>

Uma propriedade também pode ser declarada como final. Uma propriedade final não pode ser declarada novamente por uma classe filha de forma alguma, o que impede a alteração de ganchos ou a ampliação de seu acesso.

Declarar ganchos como finais em uma propriedade declarada como final é redundante e será silenciosamente ignorado. Este é o mesmo comportamento dos métodos finais.

Uma classe filha pode definir ou redefinir ganchos individuais em uma propriedade redefinindo a propriedade e apenas os ganchos que deseja substituir. Uma classe filha também pode adicionar ganchos a uma propriedade que não possui nenhum. Isto é, essencialmente, como se os ganchos fossem métodos.

Exemplo #9 Herança de gancho

    <?php
    class Point
    {
        public int $x;
        public int $y;
    }

    class PositivePoint extends Point
    {
        public int $x {
            set {
                if ($value < 0) {
                    throw new \InvalidArgumentException('Muito pequeno');
                }
                $this->x = $value;
            }
        }
    }
    ?>

Cada gancho substitui as implementações pai independentemente umas das outras. Se uma classe filha adicionar ganchos, qualquer valor padrão definido na propriedade será removido e deverá ser declarado novamente. Isso é consistente com o modo como a herança funciona em propriedades sem gancho.

#### Acessando ganchos pais

Um gancho em uma classe filha pode acessar a propriedade da classe pai usando a palavra-chave `parent::$prop`, seguida pelo gancho desejado. Por exemplo, `parent::$propName::get()`. Pode ser lido como "acessar a prop definida na classe pai e então executar sua operação 'get'" (ou operação 'set', conforme apropriado).

Se não for acessado dessa forma, o gancho da classe pai será ignorado. Esse comportamento é consistente com o funcionamento de todos os métodos. Isso também oferece uma maneira de acessar o armazenamento da classe pai, se houver. Se não houver gancho na propriedade pai, seu comportamento 'get'/'set' padrão será usado. Os ganchos não podem acessar nenhum outro gancho, exceto seu próprio pai em sua própria propriedade.

O exemplo acima poderia ser reescrito da seguinte maneira, que permitiria que a classe `Point` adicionasse seu próprio grancho `set` no futuro sem problemas (no exemplo anterior, um gancho adicionado à classe pai seria ignorado na classe filha).

Exemplo #10 Acessando gancho pai ('set')

    <?php
    class Point
    {
        public int $x;
        public int $y;
    }

    class PositivePoint extends Point
    {
        public int $x {
            set {
                if ($value < 0) {
                    throw new \InvalidArgumentException('Muito pequeno');
                }
                parent::$x::set($value);
            }
        }
    }
    ?>

Um exemplo de substituição apenas de um gancho 'get' poderia ser:

Exemplo #11 Acessando gancho pai ('get')

    <?php
    class Strings
    {
        public string $val;
    }

    class CaseFoldingStrings extends Strings
    {
        public bool $uppercase = true;

        public string $val {
            get => $this->uppercase
                ? strtoupper(parent::$val::get())
                : strtolower(parent::$val::get());
        }
    }
    ?>

### Serialização

O PHP possui diversas maneiras diferentes pelas quais um objeto pode ser serializado, seja para consumo público ou para fins de depuração. O comportamento dos ganchos varia dependendo do caso de uso. Em alguns casos, o valor bruto de apoio de uma propriedade será usado, ignorando quaisquer ganchos. Em outros, a propriedade será lida ou escrita "através" do gancho, assim como qualquer outra ação normal de leitura/gravação.

- var_dump(): Usa valor bruto
- serialize(): Usa valor bruto
- unserialize(): Usa valor bruto
- __serialize()/__unserialize(): Lógica customizada, usa gancho 'get'/'set'
- Conversão de array: Usa valor bruto
- var_export(): Usa gancho 'get'
- json_encode(): Usa gancho 'get'
- JsonSerializable: Lógica customizada, usa gancho 'get'
- get_object_vars(): Usa gancho 'get'
- get_mangled_object_vars(): Usa valor bruto

## Constantes de Classe

É possível definir constantes em cada classe separadamente. A visibilidade padrão de constantes de classe é `public`.

> Nota:

> Constantes de classe podem ser redefinidas em classes filhas. A partir do PHP 8.1.0, constantes de classe não podem ser redefinidas numa classe filha se ela for qualificada como final.

Também é possível que interfaces tenham constantes. Veja na documentação de interface os exemplos.

É possível referenciar a classe usando uma variável. O valor da variável não pode ser uma palavra-chave (e.g. `self`, `parent` e `static`).

Constantes de classe são alocadas por classe, e não em cada instância da classe.

A partir do PHP 8.3.0, constantes de classe podem ter um tipo escalar tal como `bool`, `int`, `float`, `string` ou mesmo `array`. Ao usar `array`, seu conteúdo só pode ser de outros tipos escalares.

Exemplo #1 Definindo e usando uma constante

    <?php
    class MinhaClasse
    {
        const CONSTANTE = 'valor constante';

        function mostrarConstante() {
            echo  self::CONSTANTE . "\n";
        }
    }

    echo MinhaClasse::CONSTANTE . "\n";

    $classname = "MinhaClasse";
    echo $classname::CONSTANTE;

    $classe = new MinhaClasse();
    $classe->mostrarConstante();

    echo $classe::CONSTANTE;
    ?>

A constante especial `::class` permite a resolução de classes pelo seu nome completo em tempo de compilação, e isso é útil em classes com namespaces:

Exemplo #2 Exemplo com informação estática

    <?php
    namespace foo {
        class bar {
        }

        echo bar::class; // foo\bar
    }
    ?>

Exemplo #3 Exemplo de expressão constante

    <?php
    const UM = 1;
    class foo {
        const DOIS = UM * 2;
        const TRES = UM + self::DOIS;
        const FRASE = 'O valor de TRES é '.self::TRES;
    }
    ?>

Exemplo #4 Modificadores de visibilidade em constantes de classe

    <?php
    class Foo {
        public const BAR = 'bar';
        private const BAZ = 'baz';
    }
    echo Foo::BAR, PHP_EOL;
    echo Foo::BAZ, PHP_EOL;
    ?>

Saída do exemplo acima no PHP 7.1:

    bar

    Fatal error: Uncaught Error: Cannot access private const Foo::BAZ in …

> Nota:

> Modificadores de visibilidade estão disponíveis desde o PHP 7.1.0.

Exemplo #5 Verificando variância de visibilidade de constantes de classe, a partir do PHP 8.3.0

    <?php

    interface MyInterface
    {
        public const VALUE = 42;
    }

    class MyClass implements MyInterface
    {
        protected const VALUE = 42;
    }
    ?>

Saída do exemplo acima no PHP 8.3:

    Fatal error: Access level to MyClass::VALUE must be public (as in interface MyInterface) …

> Nota: A partir do PHP 8.3.0, a variância de visibilidade é verificada mais estritamente. Antes desta versão, a visibilidade de uma constante de classe poderia ser diferente da visibilidade da constante na interface implementada.

Exemplo #6 Sintaxe de busca de constante de classe, a partir do PHP 8.3.0

    <?php
    class Foo {
        public const BAR = 'bar';
        private const BAZ = 'baz';
    }

    $name = 'BAR';
    echo Foo::{$name}, PHP_EOL; // bar
    ?>

> Nota:

> A partir do PHP 8.3.0, constantes de classe podem ser buscadas dinamicamente usando uma variável.

Exemplo #7 Atribuindo tipos a constantes de classe, a partir do PHP 8.3.0

    <?php

    class MyClass {
        public const bool MY_BOOL = true;
        public const int MY_INT = 1;
        public const float MY_FLOAT = 1.01;
        public const string MY_STRING = 'one';
        public const array MY_ARRAY = [self::MY_BOOL, self::MY_INT, self::MY_FLOAT, self::MY_STRING];
    }

    var_dump(MyClass::MY_BOOL);
    var_dump(MyClass::MY_INT);
    var_dump(MyClass::MY_FLOAT);
    var_dump(MyClass::MY_STRING);
    var_dump(MyClass::MY_ARRAY);
    ?>

Saída do exemplo acima no PHP 8.3:

    bool(true)
    int(1)
    float(1.01)
    string(3) "one"
    array(4) {
      [0]=>
      bool(true)
      [1]=>
      int(1)
      [2]=>
      float(1.01)
      [3]=>
      string(3) "one"
    }

## Autocarregamento de Classes

Muitos programadores, ao desenvolver aplicações orientadas a objeto, criam um arquivo PHP para cada definição de classe. Um dos maiores contratempos é ter de escrever uma longa lista de "includes" no início de cada script (um para cada classe).

A função spl_autoload_register() registra qualquer número de autocarregadores, permitindo que classes e interfaces sejam automaticamente carregadas se elas não ainda não tiverem sido definidas. Ao registrar autocarregadores, o PHP tem uma última chance de carregar classes e interfaces antes que falhem com um erro.

Qualquer construção semelhante a uma classe pode ser carregada automaticamente da mesma maneira. Isso inclui classes, interfaces, traits e enumerações.

Cuidado

Antes do PHP 8.0.0, era possível usar __autoload() para fazer autocarregamento de classes e interfaces. No entanto, ela é uma alternativa menos flexível a spl_autoload_register() e __autoload() está descontinuada a partir do PHP 7.2.0, e removida a partir do PHP 8.0.0.

> Nota:

> spl_autoload_register() pode ser chamada várias vezes para registrar múltiplos autocarregadores. No entanto, lançar uma exceção em uma função de autocarregamento interrompe esse processo e não permitirá que outras funções de autocarregamento sejam executadas. Por esse motivo, o lançamento de exceções em funções de autocarregamento é altamente desencorajado.

Exemplo #1 Exemplo de autocarregamento

Esse exemplo tenta carregar as classes `MyClass1` e `MyClass2` dos arquivos MyClass1.php e MyClass2.php, respectivamente.

    <?php
    spl_autoload_register(function ($class_name) {
        include $class_name . '.php';
    });

    $obj  = new MyClass1();
    $obj2 = new MyClass2();
    ?>

Exemplo #2 Outro exemplo de autocarregamento

Este exemplo tenta carregar a interface `ITest`.

    <?php

    spl_autoload_register(function ($name) {
        var_dump($name);
    });

    class Foo implements ITest {
    }

    /*
    string(5) "ITest"

    Fatal error: Interface 'ITest' not found in ...
    */
    ?>

Exemplo #3 Usando o autocarregador do Composer

» Composer gera um `vendor/autoload.php` que é configurado para carregar automaticamente pacotes gerenciados pelo Composer. Ao incluir este arquivo, esses pacotes podem ser usados sem nenhum trabalho adicional.

    <?php
    require __DIR__ . '/vendor/autoload.php';

    $uuid = Ramsey\Uuid\Uuid::uuid7();

    echo "Gerado novo UUID -> ", $uuid->toString(), "\n";
    ?>

### Veja Também

- unserialize()
- unserialize_callback_func
- unserialize_max_depth
- spl_autoload_register()
- spl_autoload()
- __autoload()

## Construtores e Destrutores

### Construtores

function __construct(mixed `...$values` = ""): void

O PHP permite aos desenvolvedores declararem métodos construtores para as classes. Classes que têm um método construtor chamam o método a cada objeto recém criado, sendo apropriado para qualquer inicialização que o objeto necessite antes de ser utilizado.

> Nota: Construtores pais não são chamados implicitamente se a classe filha define um construtor. Para executar o construtor da classe pai, uma chamada a parent::__construct() dentro do construtor da classe filha é necessária. Se a classe filha não definir um construtor, será herdado da classe pai como um método normal (se não foi declarado como privado).

Exemplo #1 Construtoras em herança

    <?php
    class BaseClass {
        function __construct() {
            print "In BaseClass constructor\n";
        }
    }

    class SubClass extends BaseClass {
        function __construct() {
            parent::__construct();
            print "In SubClass constructor\n";
        }
    }

    class OtherSubClass extends BaseClass {
        // inherits BaseClass's constructor
    }

    // In BaseClass constructor
    $obj = new BaseClass();

    // In BaseClass constructor
    // In SubClass constructor
    $obj = new SubClass();

    // In BaseClass constructor
    $obj = new OtherSubClass();
    ?>

Diferente de outros métodos, __construct() não precisa seguir as regras usuais de compatibilidade de assinatura em objetos derivados.

Construtores são métodos ordinários que são chamados durante a criação do objeto correspondente. Eles podem definir um número arbitrário de argumentos, quais podem ser obrigatórios, podem ter um tipo, e podem ter valores padrão. Argumentos de construtores são informados dentro de parênteses depois do nome da classe.

Exemplo #2 Utilizando argumentos de construtor

    <?php
    class Point {
        protected int $x;
        protected int $y;

        public function __construct(int $x, int $y = 0) {
            $this->x = $x;
            $this->y = $y;
        }
    }

    // Passagem de ambos os argumentos.
    $p1 = new Point(4, 5);
    // Passar somente o argumento obrigatório, $y terá o valor padrão zero.
    $p2 = new Point(4);
    // Com parâmetros nomeados (a partir do PHP 8.0):
    $p3 = new Point(y: 5, x: 4);
    ?>

Se a classe não tem construtor, ou o construtor não tem argumentos obrigatórios, o parêntesis pode ser omitido.

#### Construtores em estilo antigo

Anteriormente ao PHP 8.0.0 as classes no namespace global interpretam um método com o mesmo nome da classe como sendo um construtor válido. Essa sintaxe foi descontinuada, e gerará um erro `E_DEPRECATED` embora ainda continue funcionando como um construtor. Se ambos o __construct() e um método homônimo da classe estiverem definidos, __construct() que será chamado.

Em classes dentro de namespaces, ou quaisquer classes a partir do PHP 8, um método homônimo ao nome da classe não tem um significado especial.

Sempre utilize __construct() em novos códigos.

#### Promoção de propriedades no construtor

A partir do PHP 8, parâmetros de construtores podem ser promovidos a uma propriedade do objeto. Isto é bastante comum quando parâmetros do construtor são informados em uma propriedade no construtor, sem nenhum processamento. Promoção de construtor fornece uma sintaxe reduzida para esse caso. O exemplo acima pode ser reescrito assim:

Exemplo #3 Utilizando promoção de propriedades no construtor

    <?php
    class Point {
        public function __construct(protected int $x, protected int $y = 0) {
        }
    }

Quanto um argumento de construtor inclui um modificador, o PHP interpreta como sendo uma propriedade de objeto e como um argumento do construtor, e assimilará o valor do argumento a uma propriedade de mesmo nome. O corpo do construtor pode estar vazio ou conter outras operações. Quaisquer operações serão executadas após os valores dos argumentos serem definidos nas respectivas propriedades.

Nem todos os argumentos são promovidos. É possível misturar os argumentos promovidos e não promovidos em qualquer ordem. Argumentos promovidos não têm impacto no código chamador do construtor.

> Nota:

> Utilizar um modificador de visibilidade (`public`, `protected` ou `private`) é o modo mais expressivo de gerar a promoção de propriedades, mas qualquer outro modificador (como por exemplo `readonly`) terá o mesmo efeito.

> Nota:

> Propriedades de objeto não podem ser do tipo callable dado uma ambiguidade que poderia introduzir. Argumentos promovidos, portanto, não podem ser do tipo callable. Quaisquer outra declaração de tipo é permitida.

> Nota:

> Propriedades promovidas são convertidas em uma propriedade normal assim como um parâmetro de função, portanto todas as restrições de nomeação de propriedades e parâmetros se aplicam.

> Nota:

> Atributos informados em um argumento promovido será replicado tanto na propriedade como no no argumento. Valores padrão de argumentos promovidos no construtor serão replicados apenas no argumento, mas não na propriedade.

#### New em inicializadores de parâmetros

A partir do PHP 8.1.0, objetos podem ser utilizados como valores padrão de parâmetros, variáveis estáticas e constantes globais, assim como argumentos de atributos. Novos objetos também podem ser passados na instrução define().

> Nota:

> Não é permitido nomes de classe não-string ou classes anônimas. Não é permitido o espalhamento de argumentos. Não é permitido o uso de expressões.

Exemplo #4 New em inicializações

    <?php

    // Permitido:
    static $x = new Foo;

    const C = new Foo;

    function test($param = new Foo) {}

    #[AnAttribute(new Foo)]
    class Test {
        public function __construct(
            public $prop = new Foo,
        ) {}
    }

    // Não permitido, resulta em erro de compilação:
    function test(
        $a = new (CLASS_NAME_CONSTANT)(), // Nome dinâmico de classe
        $b = new class {}, // Classe anônima
        $c = new A(...[]), // Espalhamento de argumento
        $d = new B($abc), // Expressão
    ) {}
    ?>

#### Métodos de criação estáticos

O PHP suporta apenas um único construtor por classe. Em alguns casos pode ser desejável de permitir a um objeto ser construído de maneiras diferentes, a partir de argumentos diferentes. O método recomendado para realizar isso é através de métodos estáticos, utilizados como empacotadores do construtor.

Exemplo #5 Utilizando métodos estáticos para construção

    <?php
    $some_json_string = '{ "id": 1004, "name": "Elephpant" }';
    $some_xml_string = "<animal><id>1005</id><name>Elephpant</name></animal>";

    class Product {

        private ?int $id;
        private ?string $name;

        private function __construct(?int $id = null, ?string $name = null) {
            $this->id = $id;
            $this->name = $name;
        }

        public static function fromBasicData(int $id, string $name): static {
            $new = new static($id, $name);
            return $new;
        }

        public static function fromJson(string $json): static {
            $data = json_decode($json, true);
            return new static($data['id'], $data['name']);
        }

        public static function fromXml(string $xml): static {
            $data = simplexml_load_string($xml);
            $new = new static();
            $new->id = (int) $data->id;
            $new->name = $data->name;
            return $new;
        }
    }

    $p1 = Product::fromBasicData(5, 'Widget');
    $p2 = Product::fromJson($some_json_string);
    $p3 = Product::fromXml($some_xml_string);

    var_dump($p1, $p2, $p3);

O construtor pode ser privado ou protegido para evitar que ele seja chamado externamente. Nesses casos, apenas um construtor estático será capaz de instanciar a classe. Por estarem na mesma definição de classe, os métodos estáticos são capazes de instanciar o objeto, mesmo em uma instância diferente. O construtor privado é opcional e pode não fazer sentido em todos os casos.

Os três métodos estáticos a seguir demonstram as maneiras diferentes de instanciar um objeto.

- `fromBasicData()` obtém os exatos parâmetros que são necessários, e então cria o objeto através da chamada do construtor e retorna o resultado
- `fromJson()` aceita uma string JSON, realiza algum pré-processamento para converter os dados no formato necessário ao construtor. Só então retorna o novo objeto.
- `fromXml()` aceita uma string XML, pré-processa, e então cria um objeto limpo. O construtor é chamado, mas com todos os parâmetros opcionais o método os ignora. Por fim, os valores nas propriedades do objeto são associados antes de retornar o resultado.

Nos três casos, a palavra chave `static` é convertida no nome da classe onde o código reside. Nesse caso a classe `Product`.

### Destrutor

function __destruct(): void

O PHP introduz um conceito de destrutor similar ao de outras linguagens orientadas a objeto, como C++. O método destrutor será chamado assim que todas as referências a um objeto particular forem removidas ou quando o objeto for explicitamente destruído ou qualquer ordem na sequência de encerramento.

Exemplo #6 Exemplo de Destrutor

    <?php

    class MyDestructableClass
    {
        function __construct() {
            print "In constructor\n";
        }

        function __destruct() {
            print "Destroying " . __CLASS__ . "\n";
        }
    }

    $obj = new MyDestructableClass();

Assim como os construtores, os destrutores da classe pai não serão chamados implicitamente pelo PHP. Para executar o destrutor pai, deve-se fazer uma chamada explícita a parent::__destruct() no corpo do destrutor. Assim como construtores, uma classe filha pode herdar o destrutor caso não implemente um.

O destrutor será chamado mesmo se o script for terminado utilizando-se exit(). Chamar exit() em um destrutor irá impedir que as demais rotinas de encerramento executem.

Se um destrutor criar novas referências ao seu objeto, ele não será chamado uma segunda vez quando a contagem de referências atingir zero novamente ou durante a sequência de desligamento.

A partir do PHP 8.4.0, quando ciclos de coleta ocorrem durante a execução de uma Fiber, os destrutores de objetos programados para coleta são executados em uma Fiber separada, chamada `gc_destructor_fiber`. Se esta Fiber for suspensa, uma nova será criada para executar quaisquer destrutores restantes. O `gc_destructor_fiber` anterior não será mais referenciado pelo coletor de lixo e poderá ser coletado se não for referenciado em outro lugar. Objetos cujo destrutor está suspenso não serão coletados até que o destrutor retorne ou a própria Fiber seja coletada.

> Nota:

> Destrutores chamados durante o encerramento da execução do script já enviaram os cabeçalhos HTTP. O diretório atual na fase de encerramento do script pode ser diferente em alguns SAPIs (e.g. Apache).

> Nota:

> Tentar disparar uma exceção em um destrutor (chamado no término do script), lançará um erro fatal.

## Visibilidade

A visibilidade de uma propriedade ou método ou constante pode ser definida prefixando a declaração com as palavras-chave `public`, `protected` ou `private`. Membros de classes declarados como públicos podem ser acessados de qualquer lugar. Membros declarados como protegidos podem ser acessados na própria classe ou de classes referenciadas por herança acima. Membros declarados como privados só podem ser acessados por classes que definem esse membro.

### Visibilidade de propriedades

Propriedades de classes podem ser declaradas como públicas, privadas ou protegidas. Propriedades declaradas sem visibilidade são definidas como públicas.

Exemplo #1 Declaração de propriedade

    <?php
    /**
     * Define MinhaClasse
     */
    class MinhaClasse
    {
        public $publica = 'Public';
        protected $protegida = 'Protected';
        private $privada = 'Private';

        function imprimeAlo()
        {
            echo $this->publica;
            echo $this->protegida;
            echo $this->privada;
        }
    }

    $obj = new MinhaClasse();
    echo $obj->publica; // Funciona
    echo $obj->protegida; // Erro Fatal
    echo $obj->privada; // Erro Fatal
    $obj->imprimeAlo(); // Mostra Public, Protected e Private

    /**
     * Define MinhaClasse2
     */
    class MinhaClasse2 extends MinhaClasse
    {
        // É possível redeclarar as propriedades públicas e protegidas, mas não as privadas
        public $publica = 'Public2';
        protected $protegida = 'Protected2';

        function imprimeAlo()
        {
            echo $this->publica;
            echo $this->protegida;
            echo $this->privada;
        }
    }

    $obj2 = new MinhaClasse2();
    echo $obj2->publica;   // Funciona
    echo $obj2->protegida; // Erro fatal
    echo $obj2->privada;   // Não definida
    $obj2->imprimeAlo(); // Mostra Public, Protected2, Undefined

    ?>

#### Visibilidade de propriedade assimétrica

A partir do PHP 8.4, as propriedades de objeto também podem ter sua visibilidade definida de forma assimétrica, com escopo diferente para leitura (`get`) e escrita (`set`). Especificamente, a visibilidade `set` pode ser especificada separadamente, desde que não seja mais permissiva que a visibilidade padrão.

Exemplo #2 Visibilidade de propriedade assimétrica

    <?php
    class Book
    {
        public function __construct(
            public private(set) string $title,
            public protected(set) string $author,
            protected private(set) int $pubYear,
        ) {}
    }

    class SpecialBook extends Book
    {
        public function update(string $author, int $year): void
        {
            $this->author = $author; // OK
            $this->pubYear = $year; // Erro fatal
        }
    }

    $b = new Book('How to PHP', 'Peter H. Peterson', 2024);

    echo $b->title; // Funciona
    echo $b->author; // Funciona
    echo $b->pubYear; // Erro fatal

    $b->title = 'How not to PHP'; // Erro fatal
    $b->author = 'Pedro H. Peterson'; // Erro fatal
    $b->pubYear = 2023; // Erro fatal
    ?>

A partir do PHP 8.5, a visibilidade `set` também pode ser aplicada a propriedades estáticas de classes.

Exemplo #3 Visibilidade assimétrica de propriedade estática

    <?php
    class Manager
    {
        public private(set) static int $calls = 0;

        public function doAThing(): string
        {
            self::$calls++;
            // Faz outras coisas.
            return "uma string";
        }
    }

    $m = new Manager();

    $m->doAThing(); // Funciona
    echo Manager::$calls; // Funciona
    Manager::$calls = 5; // Erro fatal
    ?>

O exemplo acima produzirá:

    1
    Fatal error: Uncaught Error: Cannot modify private(set) property Manager::$calls from global scope in /algum/arquivo.php

Existem algumas advertências em relação à visibilidade assimétrica:

- Somente propriedades tipadas podem ter uma visibilidade `set` separada.
- A visibilidade `set` deve ser a mesma de `get` ou mais restritiva. Ou seja, `public protected(set)` e `protected protected(set)` são permitidos, mas `protected public(set)` causará um erro de sintaxe.
- Se uma propriedade for `public`, a visibilidade principal poderá ser omitida. Ou seja, `public private(set)` e `private(set)` terão o mesmo resultado.
- Uma propriedade com visibilidade `private(set)` é automaticamente `final` e não pode ser declarada novamente em uma classe filha.
- A obtenção de uma referência para uma propriedade segue a visibilidade `set`, não `get`. Isso ocorre porque uma referência pode ser usada para modificar o valor da propriedade.
- Da mesma forma, tentar escrever em uma propriedade de array envolve uma operação `get` e `set` internamente e, portanto, seguirá a visibilidade `set`, como é sempre a mais restritiva.

> Nota: Espaços não são permitidos na declaração de visibilidade "set". `private(set)` está correto. `private( set )` não está correto e resultará em erro de análise.

Quando uma classe estende outra, a classe filha pode redefinir qualquer propriedade que não seja `final`. Ao fazer isso, pode ampliar a visibilidade principal ou a visibilidade `set`, desde que a nova visibilidade seja igual ou mais ampla que a classe pai. Entretanto, esteja ciente de que se uma propriedade `private` for substituída, ela na verdade não altera a propriedade da classe pai, mas cria uma nova propriedade com um nome interno diferente.

Exemplo #4 Herança de propriedade assimétrica

    <?php
    class Book
    {
        protected string $title;
        public protected(set) string $author;
        protected private(set) int $pubYear;
    }

    class SpecialBook extends Book
    {
        public protected(set) string $title; // OK, pois a leitura é mais ampla e a escrita igual.
        public string $author; // OK, pois a leitura é a mesma e a escrita é mais ampla.
        public protected(set) int $pubYear; // Erro fatal. propriedades private(set) são finais.
    }
    ?>

### Visibilidades de métodos

Métodos de classe podem ser definidos como público, privado ou protegido. Métodos sem qualquer declaração explícita serão definidos como público.

Exemplo #5 Declaração de método

    <?php
    /**
     * Define MinhaClasse
     */
    class MinhaClasse
    {
        // Declara um construtor público
        public function __construct() { }

        // Declara um método público
        public function MeuPublico() { }

        // Declara um método protegido
        protected function MeuProtegido() { }

        // Declara um método privado
        private function MeuPrivado() { }

        // Esse é público
        function Foo()
        {
            $this->MeuPublico();
            $this->MeuProtegido();
            $this->MeuPrivado();
        }
    }

    $minhaclasse = new MinhaClasse;
    $minhaclasse->MeuPublico(); // Funciona
    $minhaclasse->MeuProtegido(); // Erro Fatal
    $minhaclasse->MeuPrivado(); // Erro Fatal
    $minhaclasse->Foo(); // Public, Protected e Private funcionam

    /**
     * Define MinhaClasse2
     */
    class MinhaClasse2 extends MinhaClasse
    {
        // Esse é public
        function Foo2()
        {
            $this->MeuPublico();
            $this->MeuProtegido();
            $this->MeuPrivado(); // Erro Fatal
        }
    }

    $minhaclasse2 = new MinhaClasse2;
    $minhaclasse2->MeuPublico(); // Funciona
    $minhaclasse2->Foo2(); // Public e Protected funcionam, Private não

    class Bar
    {
        public function test() {
            $this->testPrivate();
            $this->testPublic();
        }

        public function testPublic() {
            echo "Bar::testPublic\n";
        }

        private function testPrivate() {
            echo "Bar::testPrivate\n";
        }
    }

    class Foo extends Bar
    {
        public function testPublic() {
            echo "Foo::testPublic\n";
        }

        private function testPrivate() {
            echo "Foo::testPrivate\n";
        }
    }

    $myFoo = new foo();
    $myFoo->test(); // Bar::testPrivate
                    // Foo::testPublic
    ?>

### Visibilidade de constantes

A partir do PHP 7.1.0, constantes de classe podem ser definidas como públicas, protegidas ou privadas. Constantes declaradas sem visibilidade explícita são definidas como públicas.

Exemplo #6 Declaração de constantes (desde o PHP 7.1.0)

    <?php
    /**
     * Define MyClass
     */
    class MyClass
    {
        // Declara uma constante pública
        public const MY_PUBLIC = 'public';

        // Declara uma constante protegida
        protected const MY_PROTECTED = 'protected';

        // Declara uma constante privada
        private const MY_PRIVATE = 'private';

        public function foo()
        {
            echo self::MY_PUBLIC;
            echo self::MY_PROTECTED;
            echo self::MY_PRIVATE;
        }
    }

    $myclass = new MyClass();
    MyClass::MY_PUBLIC;    // Funciona
    MyClass::MY_PROTECTED; // Erro fatal
    MyClass::MY_PRIVATE;   // Erro fatal
    $myclass->foo();       // Todos os acessos funcionam dentro do método

    /**
     * Define MyClass2
     */
    class MyClass2 extends MyClass
    {
        // Isto é público
        function foo2()
        {
            echo self::MY_PUBLIC;
            echo self::MY_PROTECTED;
            echo self::MY_PRIVATE; // Fatal Error
        }
    }

    $myclass2 = new MyClass2;
    echo MyClass2::MY_PUBLIC; // Funciona
    $myclass2->foo2(); // Public e Protected funcionam, mas não Private
    ?>

### Visibilidade de outros objetos

Objetos do mesmo tipo terão acesso a outros mementos privados e protegidos mesmo que não sejam da mesma instância. Isso acontece por que os detalhes específicos de implementação já são conhecidos dentro destes objetos.

Exemplo #7 Acessando membros privados entre objetos do mesmo tipo

    <?php
    class Test
    {
        private $foo;

        public function __construct($foo)
        {
            $this->foo = $foo;
        }

        private function bar()
        {
            echo 'Acessou o método privado.';
        }

        public function baz(Test $other)
        {
            // Pode-se alterar a propriedade privada:
            $other->foo = 'hello';
            var_dump($other->foo);

            // Pode-se chamar método privado:
            $other->bar();
        }
    }

    $test = new Test('test');

    $test->baz(new Test('other'));
    ?>

O exemplo acima produzirá:

    string(5) "hello"
    Acessou o método privado.

## Herança de Objetos

Herança é um conceito de programação estabelecido, e o PHP faz uso deste em seu modelo de objetos. Este princípio afeta a forma com que classes e objetos se relacionam com outras.

Por exemplo, ao estender uma classe, a subclasse herda todos os métodos públicos e protegidos, propriedades e constantes da classe pai. A não que uma classe sobrescreva estes métodos, eles manterão sua funcionalidade original.

Isto é útil para definir uma funcionalidade abstrata, e permitir a implementação de uma funcionalidade adicional em objetos similares sem a necessidade de reimplementar todas as funcionalidades compartilhadas.

Os métodos privados de uma classe pai não são acessíveis a uma classe filha. Como resultado, as classes filhas podem reimplementar um método privado sem levar em conta as regras normais de herança. Antes do PHP 8.0.0, entretanto, as restrições `final` e `static` eram aplicadas aos métodos privados. Desde o PHP 8.0.0, a única restrição de método privado que é aplicada é `private final` para construtores, já que essa é uma maneira comum de "desabilitar" o construtor ao usar métodos de fábrica estáticos.

A visibilidade de métodos, propriedades e constantes pode ser relaxada, por exemplo, um método com `protected` pode ser marcado como `public`, mas não pode ser restrito, por exemplo, marcar uma propriedade que tenha `public` como `private`. Uma exceção são os construtores, cuja visibilidade pode ser restrita, ou seja, um construtor `public` pode ser declarado como `private` numa classe filha.

> Nota:

> A não ser que o autoload seja usado, as classes devem ser definidas antes de utilizadas. Se uma classe estende outra, a classe pai deve ser declarada antes da estrutura da classe filha. Esta regra se aplica a classes que herdam outras classes e interfaces.

> Nota:

> Não é permitido sobrescrever uma propriedade de leitura/gravação com um propriedade somente de leitura ou vice-versa.

>     <?php

>     class A {
>         public int $prop;
>     }
>     class B extends A {
>         // Ilegal: leitura-gravação -> somente-leitura
>         public readonly int $prop;
>     }
>     ?>

Exemplo #1 Exemplo de Herança

    <?php

    class Foo
    {
        public function printItem($string)
        {
            echo 'Foo: ' . $string . PHP_EOL;
        }

        public function printPHP()
        {
            echo 'PHP é ótimo' . PHP_EOL;
        }
    }

    class Bar extends Foo
    {
        public function printItem($string)
        {
            echo 'Bar: ' . $string . PHP_EOL;
        }
    }

    $foo = new Foo();
    $bar = new Bar();
    $foo->printItem('baz'); // Saída: 'Foo: baz'
    $foo->printPHP();       // Saída: 'PHP é ótimo'
    $bar->printItem('baz'); // Saída: 'Bar: baz'
    $bar->printPHP();       // Saída: 'PHP é ótimo'

    ?>

### Compatibilidade de Tipo de Retorno com Classes Internas

Antes do PHP 8.1, a maioria das classes ou métodos internos não declaravam seus tipos de retorno, e qualquer tipo de retorno era permitido ao estendê-los.

A partir do PHP 8.1.0, a maioria dos métodos internos começaram a declarar seu tipo de retorno de forma "experimental", nesse caso o tipo de retorno dos métodos deve ser compatível com o pai sendo estendido, do contrário, um aviso de descontinuação é emitido. Note que a ausência de uma declaração de retorno explícita também é considerada uma incompatibilidade de assinatura e, portanto, resulta no aviso de descontinuação.

Se o tipo de retorno não puder ser declarado para um método que sobrepõe devido à preocupações com compatibilidade entre versões PHP, um atributo ReturnTypeWillChange pode ser adicionado para silenciar o aviso de descontinuação.

Exemplo #2 O método que sobrepõe não declara nenhum tipo de retorno

    <?php
    class MeuDateTime extends DateTime
    {
        public function modify(string $modifier) { return false; }
    }

    // "Deprecated: Return type of MeuDateTime::modify(string $modifier) should either be compatible with DateTime::modify(string $modifier): DateTime|false, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice" a partir do PHP 8.1.0
    ?>

Exemplo #3 O método que sobrepõe declara um tipo de retorno errado

    <?php
    class MeuDateTime extends DateTime
    {
        public function modify(string $modifier): ?DateTime { return null; }
    }

    // "Deprecated: Return type of MeuDateTime::modify(string $modifier): ?DateTime should either be compatible with DateTime::modify(string $modifier): DateTime|false, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice" a partir do PHP 8.1.0
    ?>

Exemplo #4 O método que sobrepõe declara um tipo de retorno errado sem um aviso de descontinuação

    <?php
    class MeuDateTime extends DateTime
    {
        /**
         * @return DateTime|false
         */
        #[\ReturnTypeWillChange]
        public function modify(string $modifier) { return false; }
    }

    // Nenhum aviso é emitido
    ?>

## Operador de Resolução de Escopo (::)

O Operador de Resolução de Escopo (também chamado de Paamayim Nekudotayim), ou em termos mais simples, dois pontos duplos, é um símbolo que permite acesso a uma constante, a uma propriedade estática, ou a um método estático de uma classe ou a um dos pais dessa classe. Além disso, propriedades ou métodos estáticos podem ser substituídos através de vinculação estática tardia.

Ao referenciar estes itens do lado de fora da definição da classe, use o nome da classe.

É possível referenciar a classe usando uma variável. O valor da variável não pode ser uma palavra-chave (por exemplo, `self`, `parent` e `static`).

Paamayim Nekudotayim pode parecer, de início, uma escolha estranha para chamar dois pontos duplos. No entanto, na hora de escrever o Motor Zend 0.5 (que equipa o PHP 3), foi como a equipe da Zend decidiu chamá-lo. Na verdade, vem do hebraico e significa literalmente "duplo dois pontos".

Exemplo #1 :: de fora da definição da classe

    <?php
    class MyClass {
        const CONST_VALUE = 'Um valor constante';
    }

    $classname = 'MyClass';
    echo $classname::CONST_VALUE;

    echo MyClass::CONST_VALUE;
    ?>

Três palavras-chave especiais, self, parent e static, são utilizadas para acessar propriedades e métodos de dentro de uma definição de classe.

Exemplo #2 :: de dentro da definição da classe

    <?php
    class MyClass {
        const CONST_VALUE = 'Um valor constante';
    }

    class OtherClass extends MyClass
    {
        public static $my_static = 'variável estática';

        public static function doubleColon() {
            echo parent::CONST_VALUE . "\n";
            echo self::$my_static . "\n";
        }
    }

    $classname = 'OtherClass';
    echo $classname::doubleColon();

    OtherClass::doubleColon();
    ?>

Quando uma subclasse substitui a definição de um método do pai, o PHP não chamará o método pai. Fica a cargo da subclasse chamar o método pai ou não. Isso também se aplica a definições de métodos Construtores e Destrutores, de Sobrecarga e Mágicos.

Exemplo #3 Chamando um método pai

    <?php
    class MyClass
    {
        protected function myFunc() {
            echo "MyClass::myFunc()\n";
        }
    }

    class OtherClass extends MyClass
    {
        // Substitui a definição do método pai
        public function myFunc()
        {
            // Mas ainda consegue chamar o método da classe herdada
            parent::myFunc();
            echo "OtherClass::myFunc()\n";
        }
    }

    $class = new OtherClass();
    $class->myFunc();
    ?>

Veja também alguns exemplos de chamadas estáticas mais complexas.

## Palavra-Chave 'static'

Dica

Esta página descreve o uso da palavra-chave `static` na definição de métodos e propriedades estáticas. A palavra-chave `static` também pode ser utilizada para definir variáveis estáticas, definir funções anônimas estáticas e em late static bindings. Veja essas páginas para informações desses outros usos de `static`.

Declarar propriedades ou métodos de uma classe como estáticos faz deles acessíveis sem a necessidade de instanciar a classe. Um membro declarado como estático não pode ser acessado através de uma instância da classe.

### Métodos estáticos

Como métodos estáticos podem ser chamados sem uma instância do objeto criada, a pseudo-variável $this não está disponível dentro de um método declarado como estático.

Aviso

Chamar métodos não estáticos, estaticamente, lança um Error.

Anteriormente ao PHP 8.0.0, chamar um método não estático estaticamente estava descontinuado, e gerava um aviso `E_DEPRECATED`.

Exemplo #1 Exemplo de método estático

    <?php
    class Foo {
        public static function aStaticMethod() {
            // ...
        }
    }

    Foo::aStaticMethod();
    $classname = 'Foo';
    $classname::aStaticMethod();
    ?>

### Propriedades estáticas

Propriedades estáticas são acessíveis utilizando o Operador de Resolução de Escopo (`::`) e não podem ser acessados através do operador de objeto (`->`).

É possível referenciar a classe usando uma variável. O valor da variável não pode ser uma palavra chave (por exemplo, `self`, `parent` e `static`).

Exemplo #2 Exemplo de propriedade estática

    <?php
    class Foo
    {
        public static $my_static = 'foo';

        public function staticValue() {
            return self::$my_static;
        }
    }

    class Bar extends Foo
    {
        public function fooStatic() {
            return parent::$my_static;
        }
    }

    print Foo::$my_static . "\n";

    $foo = new Foo();
    print $foo->staticValue() . "\n";
    print $foo->my_static . "\n"; // "Propriedade" não definida, my_static

    print $foo::$my_static . "\n";
    $classname = 'Foo';
    print $classname::$my_static . "\n";

    print Bar::$my_static . "\n";
    $bar = new Bar();
    print $bar->fooStatic() . "\n";
    ?>

A saída do exemplo acima no PHP 8 é semelhante a:

    foo
    foo

    Notice: Accessing static property Foo::$my_static as non static in /in/V0Rvv on line 23

    Warning: Undefined property: Foo::$my_static in /in/V0Rvv on line 23

    foo
    foo
    foo
    foo

## Abstração de Classes

O PHP possui métodos, classes e propriedades abstratas. Classes definidas como abstratas não podem ser instanciadas, e qualquer classe que contenha ao menos um método abstrato ou uma propriedade abstrata também deve ser abstrata. Métodos definidos como abstratos simplesmente declaram a assinatura e se ele é público ou protegido; eles não podem definir a implementação. Propriedades definidas como abstratas podem declarar um requisito para o comportamento de `get` ou `set`, e podem fornecer uma implementação para uma das operações, mas não para ambas.

Quando herdando de uma classe abstrata, todos os métodos marcados como abstratos da classe herdada precisam ser definidos na classe implementante. além de seguir as regras usuais de herança e compatibilidade de assinatura.

A partir do PHP 8.4, uma classe abstrata pode declarar uma propriedade abstrata, seja pública ou protegida. Uma propriedade abstrata protegida pode ser satisfeita por uma propriedade que pode ser lida/gravada no escopo protegido ou público.

Uma propriedade abstrata pode ser satisfeita por uma propriedade padrão ou por uma propriedade com ganchos definidos, correspondentes à operação necessária.

Exemplo #1 Exemplo de método abstrato

    <?php

    abstract class ClasseAbstrata
    {
        // Força a classe que estende ClasseAbstrata a definir esse método
        abstract protected function pegarValor();
        abstract protected function valorComPrefixo( $prefixo );

        // Método comum
        public function imprimir()
        {
            print $this->pegarValor();
        }
    }

    class ClasseConcreta1 extends ClasseAbstrata
    {
        protected function pegarValor()
        {
            return "ClasseConcreta1";
        }

        public function valorComPrefixo( $prefixo )
        {
            return "{$prefixo}ClasseConcreta1";
        }
    }

    class ClasseConcreta2 extends ClasseAbstrata
    {
        protected function pegarValor()
        {
            return "ClasseConcreta2";
        }

        public function valorComPrefixo( $prefixo )
        {
            return "{$prefixo}ClasseConcreta2";
        }
    }

    $classe1 = new ClasseConcreta1();
    $classe1->imprimir();
    echo $classe1->valorComPrefixo('FOO_'), "\n";

    $classe2 = new ClasseConcreta2();
    $classe2->imprimir();
    echo $classe2->valorComPrefixo('FOO_'), "\n";

    ?>

O exemplo acima produzirá:

    ConcreteClass1
    FOO_ConcreteClass1
    ConcreteClass2
    FOO_ConcreteClass2

Exemplo #2 Exemplo de método abstrato

    <?php

    abstract class ClasseAbstrata
    {
        // Um método abstrato precisa definir apenas os parâmetros requeridos
        abstract protected function prefixName($name);
    }

    class ClasseConcreta extends ClasseAbstrata
    {
        // Uma classe filha pode definir parâmetros opcionais que não estão presentes na assinatura da classe superior
        public function prefixName($name, $separator = ".")
        {
            if ($name == "Pacman") {
                $prefix = "Mr";
            } elseif ($name == "Pacwoman") {
                $prefix = "Mrs";
            } else {
                $prefix = "";
            }

            return "{$prefix}{$separator} {$name}";
        }
    }

    $class = new ClasseConcreta();
    echo $class->prefixName("Pacman"), "\n";
    echo $class->prefixName("Pacwoman"), "\n";

    ?>

O exemplo acima produzirá:

    Mr. Pacman
    Mrs. Pacwoman

Exemplo #3 Exemplo de propriedade abstrata

    <?php

    abstract class A
    {
        // A extensão de classes deve ter uma propriedade que pode ser obtida publicamente.
        abstract public string $readable {
            get;
        }

        // A extensão de classes deve ter uma propriedade gravável protegida ou pública.
        abstract protected string $writeable {
            set;
        }

        // A extensão de classes deve ter uma propriedade simétrica protegida ou pública.
        abstract protected string $both {
            get;
            set;
        }
    }

    class C extends A
    {
        // Isto satisfaz o requisito e também o torna configurável, o que é válido.
        public string $readable;

        // Isso NÃO satisfaria o requisito, pois não é legível publicamente.
        protected string $readable;

        // Isso satisfaz exatamente o requisito, portanto é suficiente.
        // Pode ser alterado, somente a partir do escopo protegido.
        protected string $writeable {
            set => $value;
        }

        // Isso expande a visibilidade de protegida para pública, o que é aceitável.
        public string $both;
    }

    ?>

Uma propriedade abstrata em uma classe abstrata pode fornecer implementações para qualquer gancho, mas deve ter `get` ou `set` declarado, mas não definido (como no exemplo acima).

Exemplo #4 Exemplo de propriedade abstrata com ganchos

    <?php

    abstract class A
    {
        // Isso fornece uma implementação de conjunto padrão (mas substituível)
        // e requer que classes filhas forneçam uma implementação get.
        abstract public string $foo {
            get;

            set {
                $this->foo = $value
            }
        }
    }

    ?>

## Interfaces de Objetos

Interfaces de objetos permitem a criação de códigos que especificam quais métodos e propriedades uma classe deve implementar, sem definir como esses métodos ou propriedades serão implementados. Interfaces compartilham um namespace com classes, traits e enumerações, por isso eles não podem usar os mesmos nomes.

Interfaces são definidas da mesma forma que classes, mas com a palavra-chave `interface` substituindo `class` e com nenhum dos métodos tendo seu conteúdo definido.

Todos os métodos declarados em uma interface devem ser públicos, essa é a natureza de uma interface.

Na prática, interfaces servem a dois propósitos distintos:

- Elas permitem os desenvolvedores de criar objetos de classes diferentes que podem ser substituídos dado que eles implementam a mesma ou as mesmas interfaces. Um exemplo seriam os serviços variados de acesso a banco de dados, vários sistemas de pagamentos, ou estratégias de cache. Implementações diferentes podem ser substituídas sem requerer modificações nos códigos que as usam.
- Para permitir que uma função ou método aceite e opere em um parâmetro que se molda a uma interface, ao mesmo tempo que não se importa como a funcionalidade é implementada. Estas interfaces são conhecidas como `Iterable`, `Cacheable`, `Renderable`, e assim por diante, e descrevem o comportamento significativo.

Interfaces podem definir métodos mágicos para exigir que as classes implementantes também implementem esses métodos.

> Nota:

> Apesar de possível, incluir construtores em interfaces é altamente desencorajado. Fazer isso reduz significativamente a flexibilidade do objeto implementante da interface. Além disso, construtores não são verificados pelas regras de herança, o que pode causar comportamentos inconsistentes ou inesperados.

### `implements`

Para implementar uma interface, o operador `implements` é utilizado. Todos os métodos na interface devem ser implementados na classe; não fazê-lo resultará em um erro fatal. Classes podem implementar mais de uma interface se assim for desejado, separando cada interface com uma vírgula.

Aviso

Uma classe que implemente uma interface pode utilizar um nome diferente para seus parâmetros, em relação à interface. Entretanto, o PHP 8.0 suporta argumentos nomeados, ou seja, chamadores podem usar os nomes de parâmetros conforme definidos na interface implementada. Por essa razão, é altamente recomendado que desenvolvedores utilizem os mesmos nomes de parâmetros que da interface implementada.

> Nota:

> Interfaces podem ser estendidas como as classes, usando o operador extends.

> Nota:

> A classe que implementa a interface precisa declarar todos os métodos da interface com uma assinatura compatível. Uma classe pode implementar várias interfaces que declarem um método com o mesmo nome. Neste caso, a implementação precisa seguir as regras de compatibilidade de assinaturas de todas as interfaces. É possível assim aplicar covariância e contravariância.

### Constantes

É possível ter constantes em interfaces. Constantes de interfaces funcionam exatamente como constantes de classes, com exceção de não podem ser sobrescritas por uma classe/interface herdeira.

### Propriedades

A partir do PHP 8.4.0, as interfaces também podem declarar propriedades. Se o fizerem, a declaração deverá especificar se a propriedade deve ser legível, gravável ou ambas. A declaração da interface se aplica apenas ao acesso público de leitura e gravação.

Uma classe pode satisfazer uma propriedade de interface de diversas maneiras. Pode definir uma propriedade pública. Pode definir uma propriedade virtual pública que implementa apenas o gancho correspondente. Ou uma propriedade de leitura pode ser satisfeita por uma propriedade `somente leitura`. Entretanto, uma propriedade de interface configurável não pode ser `somente leitura`.

Exemplo #1 Exemplo de propriedades de interface

    <?php
    interface I
    {
        // Uma classe de implementação DEVE ter uma propriedade legível publicamente,
        // mas ser ou não configurável publicamente é irrestrito.
        public string $readable { get; }

        // Uma classe de implementação DEVE ter uma propriedade gravável publicamente,
        // mas ser ou não legível publicamente é irrestrito.
        public string $writeable { set; }

        // Uma classe de implementação DEVE ter uma propriedade que seja
        // tanto legível quanto gravável publicamente.
        public string $both { get; set; }
    }

        // Esta classe implementa todas as três propriedades como propriedades tradicionais
        // e sem ganchos; Isso é totalmente válido.
    class C1 implements I
    {
        public string $readable;

        public string $writeable;

        public string $both;
    }

    // Esta classe implementa todas as três propriedades usando apenas os
    // ganchos solicitados. Isto também é inteiramente válido.
    class C2 implements I
    {
        private string $written = '';
        private string $all = '';

        // Usa apenas um gancho get para criar uma propriedade virtual.
        // Isso satisfaz o requisito "public get".
        // Não é gravável, mas não é exigido pela interface.
        public string $readable { get => strtoupper($this->writeable); }

        // A interface requer apenas que a propriedade seja configurável,
        // mas incluir operações get também é totalmente válido.
        // Este exemplo cria uma propriedade virtual, o que é aceitável.
        public string $writeable {
            get => $this->written;
            set {
                $this->written = $value;
            }
        }

        // Esta propriedade exige que tanto a leitura quanto a gravação
        // sejam possíveis, portanto, precisamos implementar ambas ou
        // permitir que ela tenha o comportamento padrão.
        public string $both {
            get => $this->all;
            set {
                $this->all = strtoupper($value);
            }
        }
    }
    ?>

### Exemplos

Exemplo #2 Exemplo de Interface

    <?php

    // Declara a interface 'Template'
    interface Template
    {
        public function setVariable($name, $var);
        public function getHtml($template);
    }

    // Implementa a interface
    // Exemplo correto
    class WorkingTemplate implements Template
    {
        private $vars = [];

        public function setVariable($name, $var)
        {
            $this->vars[$name] = $var;
        }

        public function getHtml($template)
        {
            foreach($this->vars as $name => $value) {
                $template = str_replace('{' . $name . '}', $value, $template);
            }

            return $template;
        }
    }

    // Exemplo incorreto
    // Fatal error: Class BadTemplate contains 1 abstract methods
    // and must therefore be declared abstract (Template::getHtml)
    class BadTemplate implements Template
    {
        private $vars = [];

        public function setVariable($name, $var)
        {
            $this->vars[$name] = $var;
        }
    }
    ?>

Exemplo #3 Interfaces extensíveis

    <?php
    interface A
    {
        public function foo();
    }

    interface B extends A
    {
        public function baz(Baz $baz);
    }

    // Isto funciona
    class C implements B
    {
        public function foo()
        {
        }

        public function baz(Baz $baz)
        {
        }
    }

    // Isso não funcionará, e gerará um erro fatal
    class D implements B
    {
        public function foo()
        {
        }

        public function baz(Foo $foo)
        {
        }
    }
    ?>

Exemplo #4 Compatibilidade de variância com interfaces múltiplas

    <?php
    class Foo {}
    class Bar extends Foo {}

    interface A {
        public function myfunc(Foo $arg): Foo;
    }

    interface B {
        public function myfunc(Bar $arg): Bar;
    }

    class MyClass implements A, B
    {
        public function myfunc(Foo $arg): Bar
        {
            return new Bar();
        }
    }
    ?>

Exemplo #5 Herança de várias interfaces

    <?php
    interface A
    {
        public function foo();
    }

    interface B
    {
        public function bar();
    }

    interface C extends A, B
    {
        public function baz();
    }

    class D implements C
    {
        public function foo()
        {
        }

        public function bar()
        {
        }

        public function baz()
        {
        }
    }
    ?>

Exemplo #6 Interfaces com constantes

    <?php
    interface A
    {
        const B = 'Constante de interface';
    }

    // Imprime: Constante de interface
    echo A::B;

    class B implements A
    {
        const B = 'Constante de classe';
    }

    // Imprime: Constante de classe
    // Anteriormente ao PHP 8.1.0 isto não funcionaria porque não era possível
    // sobrescrever constantes.
    echo B::B;
    ?>

Exemplo #7 Interfaces com classes abstratas

    <?php
    interface A
    {
        public function foo(string $s): string;

        public function bar(int $i): int;
    }

    // Uma classe abstrata pode implementar apenas uma parte da interface.
    // Classes que estendem a classe abstrata precisam implementar o resto.
    abstract class B implements A
    {
        public function foo(string $s): string
        {
            return $s . PHP_EOL;
        }
    }

    class C extends B
    {
        public function bar(int $i): int
        {
            return $i * 2;
        }
    }
    ?>

Exemplo #8 Estendendo e implementando ao mesmo tempo

    <?php

    class One
    {
        /* ... */
    }

    interface Usable
    {
        /* ... */
    }

    interface Updatable
    {
        /* ... */
    }

    // A ordem de palavras chave aqui é importante. 'extends' precisa aparecer primeiro.
    class Two extends One implements Usable, Updatable
    {
        /* ... */
    }
    ?>

Uma interface, juntamente com a declaração de tipo, fornecem uma boa maneira de garantir que um objeto em particular possua determinados métodos. Veja o operador instanceof e declaração de tipo.

## Traits

O PHP implementa uma maneira de reúso de código chamada Traits.

Traits (Traços, Características) são um mecanismo para reúso de código em linguagens de herança simples como o PHP. A intenção de uma Trait é reduzir algumas limitações de herança simples permitindo que um desenvolvedor reutilize livremente conjuntos de métodos em várias classes independentes habitando em diferentes hierarquias de classe. A semântica da combinação de Traits e classes é definida de uma maneira que reduz a complexidade, e evita os problemas típicos associados com herança múltipla e Mixins.

Uma Trait é similar a uma classe, mas destina-se apenas a agrupar funcionalidade de uma forma refinada e consistente. Não é possível instanciar uma Trait por si só. Ela é uma adição à herança tradicional e permite composição e comportamento horizontais; isto é, a aplicação de membros de classe sem exigir herança.

Exemplo #1 Exemplo de Trait

    <?php

    trait TraitA {
        public function sayHello() {
            echo 'Olá,';
        }
    }

    trait TraitB {
        public function sayWorld() {
            echo 'mundo';
        }
    }

    class MyHelloWorld
    {
        use TraitA, TraitB; // Uma classe pode usar vários Traits

        public function sayHelloWorld() {
            $this->sayHello();
            echo ' ';
            $this->sayWorld();
            echo "!\n";
        }
    }

    $myHelloWorld = new MyHelloWorld();
    $myHelloWorld->sayHelloWorld();

    ?>

O exemplo acima produzirá:

    Olá, mundo!

### Precedência

Um membro herdado de uma classe base é substituído por um membro inserido por uma Trait. Na ordem de precedência, os membros da classe atual substituem os métodos da Trait, que por sua vez substituem os métodos herdados.

Exemplo #2 Exemplo de Ordem de Precedência

Um membro herdado de uma classe base é substituído pelo método inserido em MyHelloWorld da Trait SayWorld. O comportamento é o mesmo para métodos definidos na classe MyHelloWorld. Na ordem de precedência, os métodos da classe atual sobrescrevem os métodos da Trait, que por sua vez substituem os métodos da classe base.

    <?php
    class Base {
        public function sayHello() {
            echo 'Hello ';
        }
    }

    trait SayWorld {
        public function sayHello() {
            parent::sayHello();
            echo 'World!';
        }
    }

    class MyHelloWorld extends Base {
        use SayWorld;
    }

    $o = new MyHelloWorld();
    $o->sayHello();
    ?>

O exemplo acima produzirá:

    Hello World!

Exemplo #3 Exemplo de Ordem de Precedência Alternativa

    <?php
    trait HelloWorld {
        public function sayHello() {
            echo 'Hello World!';
        }
    }

    class TheWorldIsNotEnough {
        use HelloWorld;
        public function sayHello() {
            echo 'Hello Universe!';
        }
    }

    $o = new TheWorldIsNotEnough();
    $o->sayHello();
    ?>

O exemplo acima produzirá:

    Hello Universe!

### Traits Múltiplas

Traits múltiplas podem ser inseridas em uma classe, listando-as na declaração `use`, separadas por vírgulas.

Exemplo #4 Uso de Traits Múltiplas

    <?php
    trait Hello {
        public function sayHello() {
            echo 'Hello ';
        }
    }

    trait World {
        public function sayWorld() {
            echo 'World';
        }
    }

    class MyHelloWorld {
        use Hello, World;
        public function sayExclamationMark() {
            echo '!';
        }
    }

    $o = new MyHelloWorld();
    $o->sayHello();
    $o->sayWorld();
    $o->sayExclamationMark();
    ?>

O exemplo acima produzirá:

    Hello World!

### Resolução de Conflitos

Se duas Trais inserem dois métodos com o mesmo nome, um erro fatal é gerado, se o conflito não for explicitamente resolvido.

Para resolver conflitos de nomes entre Traits usados na mesma classe, o operador `insteadof` deve ser usado para escolher exatamente um dos métodos conflitantes.

Como isto permite apenas excluir métodos, o operador `as` pode ser usado para adicionar um apelido a um dos métodos. Note que o operador `as` não renomeia o método e também não afeta nenhum outro método.

Exemplo #5 Exemplo de Resolução de Conflito

Neste exemplo, Talker usa as Traits A e B. Como A e B possuem métodos conflitantes, a classe define a variante de smallTalk da Trait B, e a variante bigTalk da Trait A.

A classe Aliased_Talker usa o operador `as` para perrmitir o uso da implementação bigTalk da Trait B sob um apelido adicional `talk`.

    <?php
    trait A {
        public function smallTalk() {
            echo 'a';
        }
        public function bigTalk() {
            echo 'A';
        }
    }

    trait B {
        public function smallTalk() {
            echo 'b';
        }
        public function bigTalk() {
            echo 'B';
        }
    }

    class Talker {
        use A, B {
            B::smallTalk insteadof A;
            A::bigTalk insteadof B;
        }
    }

    class Aliased_Talker {
        use A, B {
            B::smallTalk insteadof A;
            A::bigTalk insteadof B;
            B::bigTalk as talk;
        }
    }
    ?>

### Mudando a Visibilidade de Método

Ao utilizar a sintaxe `as`, pode-se também ajustar a visibilidade de métodos na classe.

Exemplo #6 Exemplo de Mudança de Visibilidade de Método

    <?php
    trait HelloWorld {
        public function sayHello() {
            echo 'Hello World!';
        }
    }

    // Modifica a visibilidade de sayHello
    class MyClass1 {
        use HelloWorld { sayHello as protected; }
    }

    // Apelido de método com visibilidade modificada
    // Visibilidade de sayHello não é modificada
    class MyClass2 {
        use HelloWorld { sayHello as private myPrivateHello; }
    }
    ?>

### Traits Compostas de Traits

Assim como as classes podem usar Trais, outros Traits também podem. Ao utilizar uma ou mais Traits em uma definição de Trait, ela pode ser composta parcialmente ou integralmente dos membros definidos nessas outras Traits.

Exemplo #7 Exemplo de Traits Compostas de Traits

    <?php
    trait Hello {
        public function sayHello() {
            echo 'Hello ';
        }
    }

    trait World {
        public function sayWorld() {
            echo 'World!';
        }
    }

    trait HelloWorld {
        use Hello, World;
    }

    class MyHelloWorld {
        use HelloWorld;
    }

    $o = new MyHelloWorld();
    $o->sayHello();
    $o->sayWorld();
    ?>

O exemplo acima produzirá:

    Hello World!

### Membros abstratos de Traits

Traits suportam o uso de métodos abstratos para impor requisitos sobre uma classe expositora. Métodos públicos, protegidos e privados são suportados. Antes do PHP 8.0.0, apenas métodos abstratos públicos e protegidos eram suportados.

Cuidado

A partir do PHP 8.0.0, a assinatura de um método concreto deverá seguir as regras de compatibilidade de assinaturas. Anteriormente, sua assinatura poderia ser diferente.

Exemplo #8 Requisitos Expressos por Métodos Abstratos

    <?php
    trait Hello {
        public function sayHelloWorld() {
            echo 'Hello'.$this->getWorld();
        }
        abstract public function getWorld();
    }

    class MyHelloWorld {
        private $world;
        use Hello;
        public function getWorld() {
            return $this->world;
        }
        public function setWorld($val) {
            $this->world = $val;
        }
    }
    ?>

### Membros Estáticos de Traits

Traits podem definir variáveis estáticas, métodos estáticos e propriedades estáticas.

> Nota:

> A partir do PHP 8.1.0, chamar um método estático, ou acessar uma propriedade estática diretamente em uma Trait foi descontinuado. Métodos estáticos e propriedades somente devem ser acessados em uma classe utilizando a Trait.

Exemplo #9 Variáveis Estáticas

    <?php

    trait Counter
    {
        public function inc()
        {
            static $c = 0;
            $c = $c + 1;
            echo "$c\n";
        }
    }

    class C1
    {
        use Counter;
    }

    class C2
    {
        use Counter;
    }

    $o = new C1();
    $o->inc();
    $p = new C2();
    $p->inc();

    ?>

O exemplo acima produzirá:

    1
    1

Exemplo #10 Métodos Estáticos

    <?php

    trait StaticExample
    {
        public static function doSomething()
        {
            return 'Fazendo algo';
        }
    }

    class Example
    {
        use StaticExample;
    }

    echo Example::doSomething();

    ?>

O exemplo acima produzirá:

    Fazendo algo

Exemplo #11 Propriedades Estáticas

Cuidado

Antes do PHP 8.3.0, propriedades estáticas definidas em um trait eram compartilhadas por todas as classes na mesma herança hierárquica que usavam o trait. A partir do PHP 8.3.0, se uma classe filha usa um trait com uma propriedade estática, ela será considerada distinta daquela definida na classe pai.

    <?php

    trait T
    {
        public static $counter = 1;
    }

    class A
    {
        use T;

        public static function incrementCounter()
        {
            static::$counter++;
        }
    }

    class B extends A
    {
        use T;
    }

    A::incrementCounter();

    echo A::$counter, "\n";
    echo B::$counter, "\n";

    ?>

Saída do exemplo acima no PHP 8.3:

    2
    1

### Propriedades

Traits podem também definir propriedades.

Exemplo #12 Definindo Propriedades

    <?php

    trait PropertiesTrait
    {
        public $x = 1;
    }

    class PropertiesExample
    {
        use PropertiesTrait;
    }

    $example = new PropertiesExample();
    $example->x;

    ?>

Se uma Trait define uma propriedade, uma classe não pode definir uma propriedade com o mesmo nome a menos que seja compatível (mesma visibilidade, tipo, modificador de somente-leitura e valor inicial), caso contrário um erro fatal é emitido.

Exemplo #13 Resolução de Conflito

    <?php
    trait PropertiesTrait {
        public $same = true;
        public $different1 = false;
        public bool $different2;
        public bool $different3;
    }

    class PropertiesExample {
        use PropertiesTrait;
        public $same = true;
        public $different1 = true; // Fatal error
        public string $different2; // Fatal error
        readonly protected bool $different3; // Fatal error
    }
    ?>

### Constantes

Traits podem, a partir do PHP 8.2.0, também definir constantes.

Exemplo #14 Definindo Constantes

    <?php
    trait ConstantsTrait {
        public const FLAG_MUTABLE = 1;
        final public const FLAG_IMMUTABLE = 5;
    }

    class ConstantsExample {
        use ConstantsTrait;
    }

    $example = new ConstantsExample;
    echo $example::FLAG_MUTABLE;
    ?>

O exemplo acima produzirá:

    1

Se uma Trait define uma constante, uma classe não pode definir uma constante com o mesmo nome a não ser que seja compatível (mesma visibilidade, valor inicial, e finalidade), caso contrário um erro fatal é emitido.

Exemplo #15 Resolução de Conflito

    <?php
    trait ConstantsTrait {
        public const FLAG_MUTABLE = 1;
        final public const FLAG_IMMUTABLE = 5;
    }

    class ConstantsExample {
        use ConstantsTrait;
        public const FLAG_IMMUTABLE = 5; // Fatal error
    }
    ?>

### Métodos finais

A partir do PHP 8.3.0, o modificador final pode ser aplicado, com o uso do operador `as`, a métodos importados de traits. Isto pode ser usado para evitar que classes filhas substituam o método. Entretanto, a classe que usa o trait ainda poderá substituir o método.

Exemplo #16 Definindo um método originário de um trait como `final`

    <?php

    trait ConstantsTrait
    {
        public function method()
        {
            echo 'Olá';
        }
    }

    class FinalExampleA
    {
        use CommonTrait {
            CommonTrait::method as final; // O 'final' evita que classes filhas substituam o método
        }
    }

    class FinalExampleB extends FinalExampleA
    {
         public function method() {}
    }

    ?>

O exemplo acima produzirá algo semelhante a:

    Fatal error: Cannot override final method FinalExampleA::method() in ...

## Classes Anônimas

Classes anônimas são úteis quando objetos simples e descartáveis precisarem ser criados.

    <?php

    // Usando uma classe explícita
    class Logger
    {
        public function log($msg)
        {
            echo $msg;
        }
    }

    $util->setLogger(new Logger());

    // Usando uma classe anônima
    $util->setLogger(new class {
        public function log($msg)
        {
            echo $msg;
        }
    });

Podem passar argumentos através de seus construtores, estender outras classes, implementar interfaces, e usar traits como uma classe normal faz:

    <?php

    class SomeClass {}
    interface SomeInterface {}
    trait SomeTrait {}

    var_dump(new class(10) extends SomeClass implements SomeInterface {
        private $num;

        public function __construct($num)
        {
            $this->num = $num;
        }

        use SomeTrait;
    });

O exemplo acima produzirá:

    object(class@anonymous)#1 (1) {
      ["Command line code0x104c5b612":"class@anonymous":private]=>
      int(10)
    }

Aninhar uma classe anônima dentro de outra classe não dá acesso a nenhum método privado ou protegido, ou propriedades da classe externa. Para utilizar os métodos e propriedades protegidas da classe externa, a classe anônima pode estender a classe externa. Para utilizar as propriedades privadas da classe externa na classe anônima, elas devem ser passadas através do construtor:

    <?php

    class Outer
    {
        private $prop = 1;
        protected $prop2 = 2;

        protected function func1()
        {
            return 3;
        }

        public function func2()
        {
            return new class($this->prop) extends Outer {
                private $prop3;

                public function __construct($prop)
                {
                    $this->prop3 = $prop;
                }

                public function func3()
                {
                    return $this->prop2 + $this->prop3 + $this->func1();
                }
            };
        }
    }

    echo (new Outer)->func2()->func3();

O exemplo acima produzirá:

    6

Todos os objetos criados pela mesma declaração de classe anônima são instâncias desta mesma classe.

    <?php
    function anonymous_class()
    {
        return new class {};
    }

    if (get_class(anonymous_class()) === get_class(anonymous_class())) {
        echo 'same class';
    } else {
        echo 'different class';
    }

O exemplo acima produzirá:

    same class

> Nota:

> Classes anônimas têm nomes atribuídos automaticamente como demonstrado no exemplo a seguir. Este nome deve ser considerado apenas um detalhe não confiável na implementação.

>     <?php
>     echo get_class(new class {});

> O exemplo acima produzirá algo semelhante a:

>     class@anonymous/in/oNi1A0x7f8636ad2021

### Classes anônimas somente-leitura

A partir do PHP 8.3.0, o modificador `readonly` pode ser aplicado a classes anônimas.

Exemplo #1 Definindo uma classe anônima somente-leitura

    <?php
    // Usando uma classe anônima
    var_dump(new readonly class('[DEBUG]') {
        public function __construct(private string $prefix)
        {
        }

        public function log($msg)
        {
            echo $this->prefix . ' ' . $msg;
        }
    });

## Sobrecarga

Sobrecarga em PHP provê recursos para criar dinamicamente propriedades e métodos. Estas entidades dinâmicas são processadas por métodos mágicos fornecendo a uma classe vários tipos de ações.

Os métodos de sobrecarga são invocados ao interagir com propriedades ou métodos que não foram declarados ou não são visíveis no escopo corrente. O resto desta seção usará os termos propriedades inacessíveis e métodos inacessíveis para referir-se a esta combinação de declaração e visibilidade.

Todos os métodos de sobrecarga devem ser definidos como `public`.

> Nota:

> Nenhum dos argumentos dos métodos mágicos podem ser passados por referência.

> Nota:

> A interpretação do PHP de sobrecarga é diferente da maioria das linguagens orientadas a objetos. Sobrecarga, tradicionalmente, provê a habilidade de ter múltiplos métodos com o mesmo nome, mas com quantidades e tipos de argumentos diferentes.

### Sobrecarga de propriedades

public function __set(string `$name`, mixed `$value`): void
public function __get(string `$name`): mixed
public function __isset(string `$name`): bool
public function __unset(string `$name`): void

__set() é executado ao escrever dados em propriedades inacessíveis (private ou protected) ou propriedades inexistentes.

__get() é utilizado para ler dados de propriedades inacessíveis (private ou protected) ou propriedades inexistentes.

__isset() é disparado ao chamar a função isset() ou empty() em propriedades inacessíveis (private ou protected) ou propriedades inexistentes.

__unset() é invocado ao usar o construtor unset() em propriedades inacessíveis (private ou protected) ou propriedades inexistentes.

O argumento $name é o nome da propriedade com o qual se está interagindo. O argumento $value do método __set() especifica o valor para o qual a propriedade $name deveria ser definida.

A sobrecarga de propriedades funciona somente no contexto de objeto. Estes métodos mágicos não são disparados em contexto estático. Portanto estes métodos não podem ser declarados como static. Um aviso é emitido se algum método mágico de sobrecarga é declarado como `static`.

> Nota:

> O valor de retorno de __set() é ignorado por causa da forma que o PHP processa o operador de atribuição. Similarmente, o método __get() nunca é chamado em atribuições encadeadas como essa: ``

>      $a = $obj->b = 8;

> Nota:

> O PHP não irá chamar métodos sobrecarregados a partir do próprio método sobrecarregado. Isso significa, por exemplo, que escrever `return $this->foo` dentro de um __get() irá retornar `null` e lançar um `E_WARNING` se não houver uma `foo` propriedade definida, ao invés de chamar __get() uma segunda vez. Entretanto, métodos sobrecarregados podem invocar outros métodos sobrecarregados implicitamente (como um __set() chamando um __get()).

Exemplo #1 Sobrecarregando propriedades com __get(), __set(), __isset() e __unset()

    <?php
    class PropertyTest
    {
        /** Local para dados sobrecarregados. */
        private $data = array();

        /** Sobrecarga não usada em propriedades declaradas. */
        public $declared = 1;

        /** Sobrecarga usada somente neste quando acessada fora da classe. */
        private $hidden = 2;

        public function __set($name, $value)
        {
            echo "Definindo '$name' para '$value'\n";
            $this->data[$name] = $value;
        }

        public function __get($name)
        {
            echo "Obtendo '$name'\n";
            if (array_key_exists($name, $this->data)) {
                return $this->data[$name];
            }

            $trace = debug_backtrace();
            trigger_error(
                'Propriedade indefinida via __get(): ' . $name .
                ' em ' . $trace[0]['file'] .
                ' na linha ' . $trace[0]['line'],
                E_USER_NOTICE);
            return null;
        }

        public function __isset($name)
        {
            echo "'$name' está definido?\n";
            return isset($this->data[$name]);
        }

        public function __unset($name)
        {
            echo "Removendo a definição de '$name'\n";
            unset($this->data[$name]);
        }

        /** Não é um método mágico, está aqui somente para exemplo. */
        public function getHidden()
        {
            return $this->hidden;
        }
    }

    $obj = new PropertyTest;

    $obj->a = 1;
    echo $obj->a . "\n\n";

    var_dump(isset($obj->a));
    unset($obj->a);
    var_dump(isset($obj->a));
    echo "\n";

    echo $obj->declared . "\n\n";

    echo "Vamos experimentar com a propriedade privada chamada 'hidden':\n";
    echo "Propriedades privadas são visíveis dentro da classe, por isso __get() não é usado...\n";
    echo $obj->getHidden() . "\n";
    echo "Propriedades privadas não são visíveis fora da classe, por isso __get() é usado...\n";
    echo $obj->hidden . "\n";
    ?>

O exemplo acima produzirá:

    Definindo 'a' to '1'
    Obtendo 'a'
    1

    'a' está definido?
    bool(true)
    Removendo a definição de 'a'
    'a' está definido?
    bool(false)

    1

    Vamos experimentar com a propriedade privada chamada 'hidden':
    Propriedades privadas são visíveis dentro da classe, por isso __get() não é usado...
    2
    Propriedades privadas não são visíveis fora da classe, por isso __get() é usado...
    Obtendo 'hidden'

    Notice:  Propriedade indefinida via __get(): hidden em <file> na linha 70 em <file> na linha 29

### Sobrecarga de método

public function __call(string `$name`, array `$arguments`): mixed
public static function __callStatic(string `$name`, array `$arguments`): mixed

__call() é disparado ao invocar métodos inacessíveis em um contexto de objeto.

__callStatic() é disparado quando invocando métodos inacessíveis em um contexto estático.

O argumento $name é o nome do método sendo chamado. O argumento $arguments é um array enumerado contendo os parâmetros passados para o método $name.

Exemplo #2 Sobrecarga de métodos instanciados com __call() e __callStatic()

    <?php
    class MethodTest
    {
        public function __call($name, $arguments)
        {
            // Observação: valor de $name é sensível a maiúsculas/minúsculas.
            echo "Chamando método '$name' do objeto "
                 . implode(', ', $arguments). "\n";
        }

        public static function __callStatic($name, $arguments)
        {
            // Observação: valor de $name é sensível a maiúsculas/minúsculas.
            echo "Chamando método '$name' estático "
                 . implode(', ', $arguments). "\n";
        }
    }

    $obj = new MethodTest;
    $obj->runTest('no contexto do objeto');

    MethodTest::runTest('no contexto estático');
    ?>

O exemplo acima produzirá:

    Chamando método 'runTest' do objeto no contexto do objeto
    Chamando método 'runTest' estático no contexto estático

## Iteração de Objetos

O PHP fornece uma maneira de definir objetos para que seja possível iterar por uma lista de itens, como, por exemplo, a instrução `foreach`. Por padrão, todas as propriedades visíveis serão utilizadas para a iteração.

Exemplo #1 Iteração simples de objetos

    <?php
    class MyClass
    {
        public $var1 = 'valor 1';
        public $var2 = 'valor 2';
        public $var3 = 'valor 3';

        protected $protected = 'protected var';
        private   $private   = 'private var';

        function iterateVisible() {
           echo "MyClass::iterateVisible:\n";
           foreach ($this as $key => $value) {
               print "$key => $value\n";
           }
        }
    }

    $class = new MyClass();

    foreach($class as $key => $value) {
        print "$key => $value\n";
    }
    echo "\n";

    $class->iterateVisible();

    ?>

O exemplo acima produzirá:

    var1 => valor 1
    var2 => valor 2
    var3 => valor 3

    MyClass::iterateVisible:
    var1 => valor 1
    var2 => valor 2
    var3 => valor 3
    protected => protected var
    private => private var

Como a saída mostra, o `foreach` passou por cada uma das variáveis visíveis que podem ser acessadas.

### Veja Também

- Generators
- Iterator
- IteratorAggregate
- SPL Iterators

## Métodos Mágicos

Métodos mágicos são métodos especiais que sobrescrevem o comportamento padrão do PHP quando certas operações são realizadas em um objeto.

Cuidado

Todos os métodos prefixados com `__` são reservados pelo PHP. Portanto, não é recomendado utilizar nomes de métodos com esse prefixo a não ser para sobrescrever o comportamento do PHP.

Os seguintes nomes de métodos são considerados mágicos: __construct(), __destruct(), __call(), __callStatic(), __get(), __set(), __isset(), __unset(), __serialize(), __unserialize(), __sleep(), __wakeup(), __toString(), __invoke(), __set_state(), __clone() e __debugInfo()

Aviso

Os métodos acima, com exceção de __construct(), __destruct() e __clone(), precisam ser declarados como `public`, de outra forma um `E_WARNING` é emitido. Anteriormente ao PHP 8.0.0, nenhum diagnóstico era emitido para os métodos mágicos __sleep(), __wakeup(), __serialize(), __unserialize() e __set_state().

Aviso

Se tipos forem utilizados na declaração de métodos mágicos, eles precisam ser idênticos às assinaturas previstas aqui. Senão, um erro fatal é lançado. Anteriormente ao PHP 8.0.0, nenhum diagnóstico era emitido. Entretanto, __construct() e __destruct() não devem declarar um tipo de retorno, senão um erro fatal é lançado.

### __serialize() e __unserialize()

public function __serialize(): array
public function __unserialize(array `$data`): void

serialize() verifica se a classe contém uma função com o nome mágico __serialize(). Se sim, essa função é executada antes de qualquer serialização. Ela precisa construir e retornar um array associativo de chaves-valores que representam a forma serializada do objeto. Se o array não for retornado então um erro TypeError será lançado.

> Nota:

> Se ambos __serialize() e __sleep() estiverem definidos no mesmo objeto, somente __serialize() será chamado. __sleep() será ignorado. Se o objeto implementa a interface Serializable, o método `serialize()` da interface será ignorado e o método mágico __serialize() será utilizado.

O uso pretendido de __serialize() é definir uma representação arbitrária, amigável, da representação do objeto. Elementos do array podem corresponder a propriedades do objeto diretamente, mas isso não é obrigatório.

Inversamente, unserialize() verifica a presença da função mágica __unserialize(). Se presente, essa função será chamada com o array retornado de __serialize(). Ela poderá, então, restaurar as propriedades do objeto a partir do array.

> Nota:

> Se ambos __unserialize() e __wakeup() estiverem definidos, somente __unserialize() será chamado, e __wakeup() será ignorado.

> Nota:

> Esse recurso está disponível desde o PHP 7.4.0.

Exemplo #1 Serialize e unserialize

    <?php
    class Connection
    {
        protected $link;
        private $dsn, $username, $password;

        public function __construct($dsn, $username, $password)
        {
            $this->dsn = $dsn;
            $this->username = $username;
            $this->password = $password;
            $this->connect();
        }

        private function connect()
        {
            $this->link = new PDO($this->dsn, $this->username, $this->password);
        }

        public function __serialize(): array
        {
            return [
              'dsn' => $this->dsn,
              'user' => $this->username,
              'pass' => $this->password,
            ];
        }

        public function __unserialize(array $data): void
        {
            $this->dsn = $data['dsn'];
            $this->username = $data['user'];
            $this->password = $data['pass'];

            $this->connect();
        }
    }?>

### __sleep() e __wakeup()

Aviso

Este mecanismo de serialização está praticamente descontinuado a partir do PHP 8.5.0. Foi mantido para compatibilidade com versões anteriores. Entretanto, código novo ou existente deve ser atualizado para uso dos métodos mágicos __serialize() e __unserialize() em seu lugar.

public function __sleep(): array
public function __wakeup(): void

serialize() verifica se a classe tem uma função com o nome mágico __sleep(). Se tiver, a função é executada antes de qualquer serialização. Ela pode limpar o objeto e deve retornar um array com os nomes de todas as variáveis do objeto que devem ser serializadas. Se o método não retornar nada, então `null` é serializado e um `E_NOTICE` é emitido.

> Nota:

> Não é possível que __sleep() retorne nomes de propriedades privadas da classe superior. Fazer isso causará um erro de nível `E_NOTICE`. Como alternativa, utilize __serialize().

> Nota:

> A partir do PHP 8.0.0, retornar um valor que não seja um array originado de __sleep() gera um alerta. Anteriormente gerava um aviso.

O intuito do método __sleep() é enviar dados pendentes ou realizar tarefas de limpeza similares. Além disso, a função é útil se um objeto muito grande não precisar ser completamente salvo.

Ao mesmo tempo, unserialize() verifica a presença da função com o nome mágico __wakeup(). Se presente, essa função pode reconstruir quaisquer recursos que o objeto possa ter.

O intuito do método __wakeup() é restabelecer quaisquer conexões com bancos de dados que possam ter sido perdidas durante a serialização e realizar outras tarefas de reinicialização.

Exemplo #2 Sleep e wakeup

    <?php
    class Connection
    {
        protected $link;
        private $dsn, $username, $password;

        public function __construct($dsn, $username, $password)
        {
            $this->dsn = $dsn;
            $this->username = $username;
            $this->password = $password;
            $this->connect();
        }

        private function connect()
        {
            $this->link = new PDO($this->dsn, $this->username, $this->password);
        }

        public function __sleep()
        {
            return array('dsn', 'username', 'password');
        }

        public function __wakeup()
        {
            $this->connect();
        }
    }?>

### __toString()

public function __toString(): string

O método __toString() permite que uma classe decida como se comportar quando convertida para uma string. Por exemplo, o que `echo $obj;` irá imprimir.

Aviso

A partir do PHP 8.0.0, o valor de retorno segue a mesma semântica de tipo do PHP, significando que o valor será convertido para string se possível e se strict typing estiver desligado.

Um objeto Stringable não é aceito para uma declaração string se strict typing estiver ativo. Caso esse comportamento seja desejado, a declaração precisa indicar Stringable e string através de um tipo união.

A partir do PHP 8.0.0, quaisquer classe que contenha o método __toString() também implementa implicitamente a interface Stringable, e portanto passa os testes para essa interface. Implementar explicitamente essa interface é o recomendado.

No PHP 7.4, o valor retornado precisa ser uma string, senão um erro Error é lançado.

Anteriormente ao PHP 7.4.0, o valor retornado precisa ser uma string, senão um erro fatal `E_RECOVERABLE_ERROR` é emitido.

Aviso

Não era possível lançar uma exception de dentro de um método __toString() antes do PHP 7.4.0. Isso gera um erro fatal.

Exemplo #3 Exemplo Simples

    <?php
    // Declara uma classe simples
    class TestClass
    {
        public $foo;

        public function __construct($foo)
        {
            $this->foo = $foo;
        }

        public function __toString()
        {
            return $this->foo;
        }
    }

    $class = new TestClass('Hello');
    echo $class;
    ?>

O exemplo acima produzirá:

    Hello

### __invoke()

function __invoke( `...$values`): mixed

O método __invoke() é chamado quando um script tenta chamar um objeto como uma função.

Exemplo #4 Usando __invoke()

    <?php
    class CallableClass
    {
        public function __invoke($x)
        {
            var_dump($x);
        }
    }
    $obj = new CallableClass;
    $obj(5);
    var_dump(is_callable($obj));
    ?>

O exemplo acima produzirá:

    int(5)
    bool(true)

Exemplo #5 Exemplo de __invoke()

    <?php
    class Sort
    {
        private $key;

        public function __construct(string $key)
        {
            $this->key = $key;
        }

        public function __invoke(array $a, array $b): int
        {
            return $a[$this->key] <=> $b[$this->key];
        }
    }

    $customers = [
        ['id' => 1, 'first_name' => 'John', 'last_name' => 'Do'],
        ['id' => 3, 'first_name' => 'Alice', 'last_name' => 'Gustav'],
        ['id' => 2, 'first_name' => 'Bob', 'last_name' => 'Filipe']
    ];

    // Ordena os clientes pelo primeiro nome
    usort($customers, new Sort('first_name'));
    print_r($customers);

    // Ordena os clientes pelo último nome
    usort($customers, new Sort('last_name'));
    print_r($customers);
    ?>

O exemplo acima produzirá:

    Array
    (
        [0] => Array
            (
                [id] => 3
                [first_name] => Alice
                [last_name] => Gustav
            )

        [1] => Array
            (
                [id] => 2
                [first_name] => Bob
                [last_name] => Filipe
            )

        [2] => Array
            (
                [id] => 1
                [first_name] => John
                [last_name] => Do
            )

    )
    Array
    (
        [0] => Array
            (
                [id] => 1
                [first_name] => John
                [last_name] => Do
            )

        [1] => Array
            (
                [id] => 2
                [first_name] => Bob
                [last_name] => Filipe
            )

        [2] => Array
            (
                [id] => 3
                [first_name] => Alice
                [last_name] => Gustav
            )

    )

### __set_state()

static function __set_state(array `$properties`): object

Esse método estático é chamado em classes exportadas por var_export().

O único parâmetro deste método é um array contendo propriedades exportadas no formato `['propriedade' => valor, ...]`.

Exemplo #6 Usando __set_state()

    <?php

    class A
    {
        public $var1;
        public $var2;

        public static function __set_state($an_array)
        {
            $obj = new A;
            $obj->var1 = $an_array['var1'];
            $obj->var2 = $an_array['var2'];
            return $obj;
        }
    }

    $a = new A;
    $a->var1 = 5;
    $a->var2 = 'foo';

    $b = var_export($a, true);
    var_dump($b);
    eval('$c = ' . $b . ';');
    var_dump($c);
    ?>

O exemplo acima produzirá:

    string(60) "A::__set_state(array(
       'var1' => 5,
       'var2' => 'foo',
    ))"
    object(A)#2 (2) {
      ["var1"]=>
      int(5)
      ["var2"]=>
      string(3) "foo"
    }

> Nota: Quando exportando um objeto, var_export() não verifica se __set_state() está implementado na classe do objeto, de forma que re-importar esses objetos falham com um erro Error na ausência de __set_state(). Isto afeta particularmente algumas classes internas. É responsabilidade do programador verificar se todos os objetos podem ser re-importados, ou seja, que todas as classes implementam __set_state().

### __debugInfo()

function __debugInfo(): array

Este método é chamado pela função var_dump() ao despejar um objeto para obter as propriedades que devem ser exibidas. Se este método não for definido em um objeto, todas as propriedades públicas, protegidas e privadas serão exibidas.

Exemplo #7 Utilizando o __debugInfo()

    <?php
    class C {
        private $prop;

        public function __construct($val) {
            $this->prop = $val;
        }

        public function __debugInfo() {
            return [
                'propSquared' => $this->prop ** 2,
            ];
        }
    }

    var_dump(new C(42));
    ?>

O exemplo acima produzirá:

    object(C)#1 (1) {
      ["propSquared"]=>
      int(1764)
    }

## final

A palavra-chave final evita que classes filhas sobrescrevam um método, propriedade ou constante prefixando a definição com `final`. Se a própria classe estiver definida como final, ela não pode ser estendida.

Exemplo #1 Exemplo de método final

    <?php
    class ClasseBase {
       public function teste() {
           echo "ClasseBase::teste() chamado\n";
       }

       final public function maisTeste() {
           echo "ClasseBase::maisTeste() chamado\n";
       }
    }

    class ClasseFilha extends ClasseBase {
       public function maisTeste() {
           echo "ClasseFilha::maisTeste() called\n";
       }
    }
    // Resulta em erro fatal: Não é possível substituir o método final ClasseBase::maisTeste()
    ?>

Exemplo #2 Exemplo de classe final

    <?php
    final class ClasseBase {
       public function teste() {
           echo "Método ClasseBase::teste() chamado\n";
       }

       // Como a classe já é final, a palavra-chave final é rendundante.
       final public function maisTeste() {
           echo "Método ClasseBase::maisTeste() chamado\n";
       }
    }

    class ClasseFilha extends ClasseBase {
    }
    // Resulta em erro fatal: Classe ClasseFilha não pode herdar da classe final (ClasseBase)
    ?>

Exemplo #3 Exemplo de propriedade final a partir do PHP 8.4.0

    <?php
    class ClasseBase {
       final protected string $teste;
    }

    class ClasseFilha extends ClasseBase {
        public string $teste;
    }
    // Resulta em erro fatal: Não é possível substituir a propriedade final ClasseBase::$teste
    ?>

Exemplo #4 Exemplo de constante final a partir do PHP 8.1.0

    <?php
    class Foo
    {
        final public const X = "foo";
    }

    class Bar extends Foo
    {
        public const X = "bar";
    }

    // Erro fatal: Bar::X não pode substituir a constante final Foo::X
    ?>

> Nota: A partir do PHP 8.0.0, métodos privados não podem ser declarados finais, com exceção do construtor.

> Nota: Uma propriedade que é declarada `private(set)` é, implicitamente, `final`.

## Clonando Objetos

Criar uma cópia de um objeto com propriedades totalmente replicadas nem sempre é o comportamento desejado. Um bom exemplo da necessidade para cópia de construtores, e quando possuir um objeto que representa uma janela do GTK e o objeto guarda o recurso dessa janela GTK. ao criar uma duplicata, pode-se desejar a criação de uma nova janela com as mesmas propriedades e fazer o novo objeto guardar o recurso da nova janela. Outro exemplo é se seu objeto guarda uma referência a outro objeto que usa e ao replicar o objeto pai, deseja-se que seja criada uma nova instância desse outro objeto para que a réplica tenha sua própria cópia separada.

Uma cópia de objeto é criada usando a palavra-chave `clone` (que chama o método __clone() do objeto, se possível).

    $copia_do_objeto = clone $objeto;

Ao clonar um objeto, o PHP fará uma cópia superficial de todas as propriedades do objeto. Qualquer propriedade que seja referência a outra variável, permanecerá como referência.

function __clone(): void

Depois que a clonagem se completa, se um método __clone() estiver definido, o objeto recém criado terá seu método __clone() chamado, permitindo que qualquer propriedade seja alterada.

Exemplo #1 Clonando um objeto

    <?php
    class SubObject
    {
        static $instances = 0;
        public $instance;

        public function __construct() {
            $this->instance = ++self::$instances;
        }

        public function __clone() {
            $this->instance = ++self::$instances;
        }
    }

    class MyCloneable
    {
        public $object1;
        public $object2;

        function __clone()
        {
            // Força uma cópia de this->object, caso contrário
            // aponta para o mesmo objeto.
            $this->object1 = clone $this->object1;
        }
    }

    $obj = new MyCloneable();

    $obj->object1 = new SubObject();
    $obj->object2 = new SubObject();

    $obj2 = clone $obj;

    print "Objeto original:\n";
    print_r($obj);

    print "Objeto clonado:\n";
    print_r($obj2);

    ?>

O exemplo acima produzirá:

    Objeto original:
    MyCloneable Object
    (
        [object1] => SubObject Object
            (
                [instance] => 1
            )

        [object2] => SubObject Object
            (
                [instance] => 2
            )

    )
    Objeto clonado:
    MyCloneable Object
    (
        [object1] => SubObject Object
            (
                [instance] => 3
            )

        [object2] => SubObject Object
            (
                [instance] => 2
            )

    )

É possível acessar um membro de um objeto recém clonado em uma expressão única:

Exemplo #2 Acessar um membro de um objeto recém clonado

    <?php
    $dateTime = new DateTime();
    echo (clone $dateTime)->format('Y');
    ?>

O exemplo acima produzirá algo semelhante a:

    2016

## Comparando Objetos

Ao usar o operador de comparação (`==`), as variáveis dos objetos são comparadas de maneira simples, nominalmente: Duas instâncias de objetos são iguais se possuem os mesmos atributos e valores (valores são comparados com `==`), e são instâncias da mesma classe.

Ao usar o operador de identidade (`===`), as variáveis dos objetos serão idênticas, se e somente se, referirem a mesma instância da mesma classe.

Um exemplo evidenciará essas regras.

Exemplo #1 Exemplo de comparação de objetos

    <?php
    function bool2str($bool)
    {
        if ($bool === false) {
            return 'FALSO';
        } else {
            return 'VERDADEIRO';
        }
    }

    function compareObjects(&$o1, &$o2)
    {
        echo 'o1 == o2 : ' . bool2str($o1 == $o2) . "\n";
        echo 'o1 != o2 : ' . bool2str($o1 != $o2) . "\n";
        echo 'o1 === o2 : ' . bool2str($o1 === $o2) . "\n";
        echo 'o1 !== o2 : ' . bool2str($o1 !== $o2) . "\n";
    }

    class Flag
    {
        public $flag;

        function __construct($flag = true) {
            $this->flag = $flag;
        }
    }

    class OtherFlag
    {
        public $flag;

        function __construct($flag = true) {
            $this->flag = $flag;
        }
    }

    $o = new Flag();
    $p = new Flag();
    $q = $o;
    $r = new OtherFlag();

    echo "Duas instâncias da mesma classe\n";
    compareObjects($o, $p);

    echo "\nDuas referências para a mesma instância\n";
    compareObjects($o, $q);

    echo "\nInstâncias de duas classes diferentes\n";
    compareObjects($o, $r);
    ?>

O exemplo acima produzirá:

    Duas instâncias da mesma classe
    o1 == o2 : VERDADEIRO
    o1 != o2 : FALSO
    o1 === o2 : FALSO
    o1 !== o2 : VERDADEIRO

    Duas referências para a mesma instância
    o1 == o2 : VERDADEIRO
    o1 != o2 : FALSO
    o1 === o2 : VERDADEIRO
    o1 !== o2 : FALSO

    Instâncias de duas classes diferentes
    o1 == o2 : FALSO
    o1 != o2 : VERDADEIRO
    o1 === o2 : FALSO
    o1 !== o2 : VERDADEIRO

> Nota:

> Extensões podem definir suas próprias regras para comparação de objetos (`==`).

## Vinculações Estáticas Tardias

O PHP implementa um recurso chamado Vinculações Estáticas Tardias que pode ser usado para referenciar a classe chamada no contexto de herança estática.

Mais precisamente, as Vinculações Estáticas Tardias funcionam através do armazenamento do nome da classe na última "chamada não encaminhada". No caso de chamadas a métodos estáticos, é a classe explicitamente chamada (normalmente o nome à esquerda do operador `::`); no caso de chamadas a métodos não estáticos, é o nome da classe do objeto. Uma "chamada encaminhada" é àquela estática, realizada pelos prefixos `self::`, `parent::`, `static::`, ou, se subindo na hierarquia de classes, forward_static_call(). A função get_called_class() pode ser utilizada para recuperar uma string com o nome da classe chamada e `static::` introduz seu escopo.

Esse recurso foi chamado de "Vinculações Estáticas Tardias" de uma perspectiva interna em mente. "Vinculação tardia" vem do fato que `static::` não será resolvido usando a classe onde o método foi definido, mas computada utilizando informações em tempo de execução. É também chamado "vinculação estática" pois pode ser utilizado em (mas não limitado a) chamadas de métodos estáticos.

### Limitações do `self::`

Referências estáticas para a atual classe como `self::` ou `__CLASS__` são resolvidas usando a classe na qual a função pertence, como onde ele foi definido:

Exemplo #1 Uso do `self::`

    <?php

    class A
    {
        public static function who()
        {
            echo __CLASS__;
        }

        public static function test()
        {
            self::who();
        }
    }

    class B extends A
    {
        public static function who()
        {
            echo __CLASS__;
        }
    }

    B::test();

    ?>

O exemplo acima produzirá:

    A

### Uso de Vinculações Estáticas Tardias

Vinculações Estáticas Tardias tentam resolver a limitação introduzindo uma palavra-chave que referencia a classe que foi inicialmente chamada em tempo de execução. Basicamente, é uma palavra-chave que permite referenciar `B` em `test()`, no exemplo anterior. Foi decidido não introduzir uma nova palavra-chave, mas usar `static`, já reservada.

Exemplo #2 Uso simples de `static::`

    <?php

    class A
    {
        public static function who()
        {
            echo __CLASS__;
        }

        public static function test()
        {
            static::who(); // Aqui acontecem as Vinculações Estáticas Tardias
        }
    }

    class B extends A
    {
        public static function who()
        {
            echo __CLASS__;
        }
    }

    B::test();

    ?>

O exemplo acima produzirá:

    B

> Nota:

> Em contextos não estáticos, a classe chamada será a classe da instância do objeto. Assim como `$this->` chamará métodos privados do mesmo escopo, utilizar `static::` pode ter resultados diferentes. Outra diferença é que `static::` só pode referenciar propriedades estáticas.

Exemplo #3 Uso de `static::` em um contexto não-estático

    <?php

    class A
    {
        private function foo()
        {
            echo "successo!\n";
        }

        public function test()
        {
            $this->foo();
            static::foo();
        }
    }

    class B extends A
    {
       /* foo() será copiado para B, assim seu escopo ainda será A e
        * e a chamada funcionará */
    }

    class C extends A
    {
        private function foo()
        {
            /* método original foi substituído, escopo agora é C */
        }
    }

    $b = new B();
    $b->test();

    $c = new C();
    try {
        $c->test();
    } catch (Error $e) {
        echo $e->getMessage();
    }

    ?>

O exemplo acima produzirá:

    successo!
    successo!
    successo!
    Call to private method C::foo() from scope A

> Nota:

> As resoluções de Vinculações Estáticas Tardias terminarão quando a chamada for realizada sem retorno. Por outro lado, chamadas estáticas utilizando instruções como `parent::` ou `self::` irão repassar a informação do chamador.

> Exemplo #4 Chamadas repassadas e não repassadas

>     <?php

>     class A
>     {
>         public static function foo()
>         {
>             static::who();
>         }

>         public static function who()
>         {
>             echo __CLASS__."\n";
>         }
>     }

>     class B extends A
>     {
>         public static function test()
>         {
>             A::foo();
>             parent::foo();
>             self::foo();
>         }

>         public static function who()
>         {
>             echo __CLASS__."\n";
>         }
>     }

>     class C extends B
>     {
>         public static function who()
>         {
>             echo __CLASS__."\n";
>         }
>     }

>     C::test();

>     ?>

> O exemplo acima produzirá:

>     A
>     C
>     C

## Objetos e Referências

Um dos pontos fortes frequentemente mencionado da POO no PHP, é que "objetos são passados por referências por padrão". Isto não é completamente verdade. Esta seção retifica esse pensamento comum usando alguns exemplos.

Uma referência do PHP é um sinônimo, que permite duas variáveis diferentes escreverem para o mesmo valor. Em PHP, uma variável objeto não contém o próprio objeto como valor. Ela contém um identificador do objeto que permite que os acessadores do objeto encontrem o objeto real. Quando um objeto é enviado por argumento, retornado ou atribuído a outra variável, as variáveis diferentes não são sinônimos: elas armazenam uma cópia do identificador, que aponta para o mesmo objeto.

Exemplo #1 Referências e Objetos

    <?php
    class A {
        public $foo = 1;
    }

    $a = new A;
    $b = $a;     // $a e $b são cópias do mesmo identificador
                 // ($a) = ($b) = <id>
    $b->foo = 2;
    echo $a->foo."\n";

    $c = new A;
    $d = &$c;    // $c e $d são referências
                 // ($c,$d) = <id>

    $d->foo = 2;
    echo $c->foo."\n";

    $e = new A;

    function foo($obj) {
        // ($obj) = ($e) = <id>
        $obj->foo = 2;
    }

    foo($e);
    echo $e->foo."\n";

    ?>

O exemplo acima produzirá:

    2
    2
    2

## Serialização de Objetos - Objetos em sessões

A função serialize() retorna uma string contendo uma representação em fluxo de bytes de qualquer valor que pode ser armazenado pelo PHP. A função unserialize() pode utilizar essa string para recriar os valores originais da variável. Utilizar a serialização para salvar um objeto, salvará todas as variáveis de um objeto. Os métodos de um objeto não são salvos, apenas o nome da classe.

Para desserializar um objeto com a função unserialize(), a classe desse objeto precisa estar definida. Isto é, se possuir um objeto da classe A e serializá-lo, você obterá uma string que referencia a classe A e contêm todos os valores de variáveis contidas nele. Se desejar desserializar este objeto em outro arquivo, um objeto da classe A, a definição da classe A deve estar presente neste arquivo. Isso pode ser feito, por exemplo, armazenando a definição da classe A em um arquivo, e incluí-lo, fazendo uso da função spl_autoload_register().

    <?php
    // A.php:

      class A {
          public $one = 1;

          public function show_one() {
              echo $this->one;
          }
      }

    // page1.php:

      include "A.php";

      $a = new A;
      $s = serialize($a);
      // armazena $s em algum lugar onde page2.php possa encontrar.
      file_put_contents('caixa', $s);

    // page2.php:

      // isto é necessário para que a desserialização funcione adequadamente.
      include "A.php";

      $s = file_get_contents('caixa');
      $a = unserialize($s);

      // agora usa a função show_one() do objeto $a.
      $a->show_one();
    ?>

É fortemente recomendado que, quando uma aplicação serializa seus objetos, para uso posterior na aplicação, esta inclua a definição da classe do objeto em questão ao longo de toda aplicação. Não fazer isso pode resultar em objetos serem desserializados sem a definição da classe, que acarretará no PHP entregar um objeto da classe __PHP_Incomplete_Class_Name, que não possui métodos, tornando o objeto inútil.

Então, se, no exemplo anterior, $a se tornou parte da sessão adicionando uma nova chave no array superglobal $_SESSION, você deve incluir o arquivo `A.php` em todas suas páginas, e não somente em page1.php e page2.php.

Além dos conselhos acima, note que pode-se capturar os eventos de serialização e desserialização de um objeto usando os métodos __sleep() e __wakeup(). Usar o método __sleep() também lhe permitirá serializar somente subconjuntos de propriedades de um objeto.

## Covariância e Contravariância

No 7.2.0, a contravariância parcial foi introduzida removendo as restrições de tipo nos parâmetros em um método filho. A partir do PHP 7.4.0, foi adicionado suporte a covariância e contravariância completas.

A covariância permite que um método de uma classe filha retorne um tipo mais específico que o tipo de retorno do método da classe pai. A contravariância permite a um tipo de parâmetro ser menos específico em um método de classe filha, em relação à classe pai.

Uma declaração de tipo é considerada mais específica nos seguintes casos:

- Um tipo é removido de um tipo união
- Um tipo é adicionado a um tipo interseção
- Um tipo de classe é alterado para um tipo de classe filha
- iterable é alterado para array ou Traversable

Uma classe de tipo é considerada menos específica se o oposto for verdadeiro.

### Covariância

Para ilustrar como uma variância funciona, uma classe pai abstrata simples, Animal é criada. Animal será estendida por classes filhas, Cat e Dog.

    <?php

    abstract class Animal
    {
        protected string $name;

        public function __construct(string $name)
        {
            $this->name = $name;
        }

        abstract public function speak();
    }

    class Dog extends Animal
    {
        public function speak()
        {
            echo $this->name . " barks";
        }
    }

    class Cat extends Animal
    {
        public function speak()
        {
            echo $this->name . " meows";
        }
    }

Observe que não há nenhum método que retorne valores neste exemplo. Serão adicionados alguns métodos que retornam um novo objeto do tipo de classe Animal, Cat ou Dog.

    <?php

    interface AnimalShelter
    {
        public function adopt(string $name): Animal;
    }

    class CatShelter implements AnimalShelter
    {
        public function adopt(string $name): Cat // em vez de retornar o tipo Animal, pode retornar o tipo Cat
        {
            return new Cat($name);
        }
    }

    class DogShelter implements AnimalShelter
    {
        public function adopt(string $name): Dog // em vez de retornar o tipo Animal, pode retornar o tipo Dog
        {
            return new Dog($name);
        }
    }

    $kitty = (new CatShelter)->adopt("Ricky");
    $kitty->speak();
    echo "\n";

    $doggy = (new DogShelter)->adopt("Mavrick");
    $doggy->speak();

O exemplo acima produzirá:

    Ricky meows
    Mavrick barks

### Contravariância

Continuando com o exemplo anterior com as classes Animal, Cat e Dog, duas classes chamadas Food e AnimalFood serão incluídas, e um método eat(AnimalFood $food) é adicionado à classe abstrata Animal.

    <?php

    class Food {}

    class AnimalFood extends Food {}

    abstract class Animal
    {
        protected string $name;

        public function __construct(string $name)
        {
            $this->name = $name;
        }

        public function eat(AnimalFood $food)
        {
            echo $this->name . " eats " . get_class($food);
        }
    }

Para ver o comportamento da contravariância, o método eat é substituído na classe Dog para permitir qualquer objeto do tipo Food. A classe Cat permanece inalterada.

    <?php

    class Dog extends Animal
    {
        public function eat(Food $food) {
            echo $this->name . " eats " . get_class($food);
        }
    }

O próximo exemplo irá mostrar o comportamento da contravariância.

    <?php

    $kitty = (new CatShelter)->adopt("Ricky");
    $catFood = new AnimalFood();
    $kitty->eat($catFood);
    echo "\n";

    $doggy = (new DogShelter)->adopt("Mavrick");
    $banana = new Food();
    $doggy->eat($banana);

O exemplo acima produzirá:

    Ricky eats AnimalFood
    Mavrick eats Food

Mas o que acontece se $kitty tentar comer (eat()) a $banana?

    $kitty->eat($banana);

O exemplo acima produzirá:

    Fatal error: Uncaught TypeError: Argument 1 passed to Animal::eat() must be an instance of AnimalFood, instance of Food given

### Variância de propriedade

Por padrão, as propriedades não são covariantes nem contravariantes e, portanto, invariantes. Ou seja, o tipo delas não pode mudar em nenhuma classe filha. A razão para isso é que as operações "get" devem ser covariantes e as operações "set" devem ser contravariantes. A única maneira de uma propriedade satisfazer ambos os requisitos é ser invariante.

A partir do PHP 8.4.0, com a adição de propriedades abstratas (em uma interface ou classe abstrata) e propriedades virtuais, é possível declarar uma propriedade que possui apenas uma operação get ou set. Como resultado, propriedades abstratas ou propriedades virtuais que exigem apenas uma operação "get" podem ser covariantes. Da mesma forma, uma propriedade abstrata ou propriedade virtual que requerem apenas uma operação "set" pode ser contravariante.

Uma vez que uma propriedade tenha uma operação get e set, entretanto, ela não será mais covariante ou contravariante para extensão adicional. Ou seja, agora é invariante.

Exemplo #1 Variância do tipo de propriedade

    <?php
    class Animal {}
    class Dog extends Animal {}
    class Poodle extends Dog {}

    interface PetOwner
    {
        // Apenas uma operação get é necessária, portanto isso pode ser covariante.
        public Animal $pet { get; }
    }

    class DogOwner implements PetOwner
    {
        // Este pode ser um tipo mais restritivo, já que o lado "get"
        // ainda retorna um Animal.  Porém, como propriedade nativa,
        // os filhos desta classe não podem mais alterar o tipo.
        public Dog $pet;
    }

    class PoodleOwner extends DogOwner
    {
        // Isso NÃO É PERMITIDO, porque DogOwner::$pet tem operações
        // get e set definidas e obrigatórias.
        public Poodle $pet;
    }
    ?>

## Objetos Lentos

Um objeto lento é um objeto cuja inicialização é adiada até que seu estado seja observado ou modificado. Alguns exemplos de casos de uso incluem componentes de injeção de dependência que fornecem serviços lentos totalmente inicializados somente se necessário, ORMs fornecendo entidades lentas que se hidratam do banco de dados somente quando acessados, ou um analisador JSON que atrasa a análise até que os elementos sejam acessados.

Duas estratégias de objetos lentos são suportadas: Objetos Fantasmas e Proxies Virtuais, doravante denominados "fantasmas lentos" e "proxies lentos". Em ambas as estratégias, o objeto lento é anexado a um inicializador ou fábrica que é chamado automaticamente quando seu estado é observado ou modificado pela primeira vez. Do ponto de vista da abstração, os objetos fantasmas lentos são indistinguíveis dos não-lentos: eles podem ser usados ​​sem que se saiba que são lentos, permitindo que sejam passados ​​e usados ​​por códigos que desconhecem a lentidão. Os proxies lentos são igualmente transparentes, mas deve-se ter cuidado ao usar sua identidade, pois o proxy e sua instância real possuem identidades diferentes.

> Nota: Informação de Versão
> Objetos Lentos foram introduzidos no PHP 8.4.

### Criando Objetos Lentos

É possível criar uma instância lenta de qualquer classe definida pelo usuário ou da classe stdClass (outras classes internas não são suportadas), ou redefinir uma instância dessas classes para torná-la lenta. Os pontos de entrada para criar um objeto lento são os métodos ReflectionClass::newLazyGhost() e ReflectionClass::newLazyProxy().

Ambos os métodos aceitam uma função que é chamada quando o objeto requer inicialização. O comportamento esperado da função varia dependendo da estratégia em uso, conforme descrito na documentação de referência de cada método.

Exemplo #1 Criando um Fantasma Lento

    <?php
    class Example
    {
        public function __construct(public int $prop)
        {
            echo __METHOD__, "\n";
        }
    }

    $reflector = new ReflectionClass(Example::class);
    $lazyObject = $reflector->newLazyGhost(function (Example $object) {
        // Inicializa o objeto no local
        $object->__construct(1);
    });

    var_dump($lazyObject);
    var_dump(get_class($lazyObject));

    // Dispara a inicialização
    var_dump($lazyObject->prop);
    ?>

O exemplo acima produzirá:

    lazy ghost object(Example)#3 (0) {
    ["prop"]=>
    uninitialized(int)
    }
    string(7) "Example"
    Example::__construct
    int(1)

Exemplo #2 Criando um Proxy Lento

    <?php
    class Example
    {
        public function __construct(public int $prop)
        {
            echo __METHOD__, "\n";
        }
    }

    $reflector = new ReflectionClass(Example::class);
    $lazyObject = $reflector->newLazyProxy(function (Example $object) {
        // Cria e retorna a instância real
        return new Example(1);
    });

    var_dump($lazyObject);
    var_dump(get_class($lazyObject));

    // Dispara a inicialização
    var_dump($lazyObject->prop);
    ?>

O exemplo acima produzirá:

    lazy proxy object(Example)#3 (0) {
      ["prop"]=>
      uninitialized(int)
    }
    string(7) "Example"
    Example::__construct
    int(1)

Qualquer acesso às propriedades de um objeto lento aciona sua inicialização (inclusive via ReflectionProperty). No entanto, certas propriedades podem ser conhecidas antecipadamente e não devem acionar a inicialização quando acessadas:

Exemplo #3 Inicializando Propriedades Ansiosamente

    <?php
    class BlogPost
    {
        public function __construct(
            public int $id,
            public string $title,
            public string $content,
        ) { }
    }

    $reflector = new ReflectionClass(BlogPost::class);

    $post = $reflector->newLazyGhost(function ($post) {
        $data = fetch_from_store($post->id);
        $post->__construct($data['id'], $data['title'], $data['content']);
    });

    // Sem esta linha, a seguinte chamada a ReflectionProperty::setValue()
    // acionaria a inicialização.
    $reflector->getProperty('id')->skipLazyInitialization($post);
    $reflector->getProperty('id')->setValue($post, 123);

    // Alternativamente, pode-se usar isso diretamente:
    $reflector->getProperty('id')->setRawValueWithoutLazyInitialization($post, 123);

    // A propriedade id pode ser acessada sem acionar a inicialização
    var_dump($post->id);
    ?>

Os métodos ReflectionProperty::skipLazyInitialization() e ReflectionProperty::setRawValueWithoutLazyInitialization() oferecem maneiras de contornar a inicialização lenta ao acessar uma propriedade.

### Sobre Estratégias de Objetos Lentos

Fantasmas lentos são objetos que se inicializam no local e, uma vez inicializados, são indistinguíveis de um objeto que nunca foi lento. Esta estratégia é adequada quando são controladas tanto a instanciação quanto a inicialização do objeto, tornando-a inadequada se qualquer um deles for gerenciado por outra parte.

Proxies lentos, uma vez inicializados, atuam como proxies para uma instância real: qualquer operação em um proxy lento inicializado é encaminhada para a instância real. A criação da instância real pode ser delegada a outra parte, tornando esta estratégia útil nos casos em que fantasmas lentos são inadequados. Embora os proxies lentos sejam quase tão transparentes quanto os fantasmas lentos, é necessário cautela quando sua identidade é usada, pois o proxy e sua instância real possuem identidades distintas.

### Ciclo de Vida de Objetos Lentos

Os objetos podem se tornar lentos no momento da instanciação usando ReflectionClass::newLazyGhost() ou ReflectionClass::newLazyProxy(), ou após a instanciação usando ReflectionClass::resetAsLazyGhost() ou ReflectionClass::resetAsLazyProxy(). Depois disso, um objeto lento pode ser inicializado por meio de uma das seguintes operações:

- Interagir com o objeto de uma forma que acione a inicialização automática. Consulte Gatilhos de inicialização.
- Marcar todas as suas propriedades como não-lentas usando ReflectionProperty::skipLazyInitialization() ou ReflectionProperty::setRawValueWithoutLazyInitialization().
- Chamar explicitamente ReflectionClass::initializeLazyObject() ou ReflectionClass::markLazyObjectAsInitialized().

Como os objetos lentos são inicializados quando todas as suas propriedades são marcadas como não-lentas, os métodos acima não marcarão um objeto como lento se nenhuma propriedade puder ser marcada como lenta.

### Gatilhos de Inicialização

Objetos lentos são projetados para serem totalmente transparentes para seus consumidores, portanto, operações normais que observam ou modificam o estado do objeto acionará automaticamente a inicialização antes que a operação seja executada. Isto inclui, mas não está limitado às seguintes operações:

- Ler ou escrever uma propriedade.
- Testar se uma propriedade está definida ou desativada.
- Acessar ou modificar uma propriedade via ReflectionProperty::getValue(), ReflectionProperty::getRawValue(), ReflectionProperty::setValue() ou ReflectionProperty::setRawValue().
- Listae propriedades com ReflectionObject::getProperties(), ReflectionObject::getProperty() ou get_object_vars().
- Iterar sobre propriedades de um objeto que não implementa Iterator ou IteratorAggregate usando foreach.
- Serializar o objeto com serialize(), json_encode() etc.
- Clonar o objeto.

Chamadas de método que não acessam o estado do objeto não acionarão a inicialização. Da mesma forma, as interações com o objeto que invocam métodos mágicos ou funções de gancho não acionarão a inicialização se esses métodos ou funções não acessarem o estado do objeto.

#### Operações sem Acionamento

Os métodos específicos ou operações de baixo nível a seguir permitem acesso ou modificação de objetos lentos sem acionar a inicialização:

- Marcar propriedades como não-lentas com ReflectionProperty::skipLazyInitialization() ou ReflectionProperty::setRawValueWithoutLazyInitialization().
- Recuperar a representação interna de propriedades usando get_mangled_object_vars() ou através da conversão de um objeto para um array.
- Usar serialize() quando `ReflectionClass::SKIP_INITIALIZATION_ON_SERIALIZE` está definida, a menos que __serialize() ou __sleep() acionem a inicialização.
- Chamar ReflectionObject::__toString().
- Usar var_dump() ou debug_zval_dump(), a menos que __debugInfo() acione a inicialização.

### Sequência de Inicialização

Esta seção descreve a sequência de operações executadas quando a inicialização é acionada, com base na estratégia em uso.

#### Objetos Fantasmas

- O objeto é marcado como não-lento.
- Propriedades não inicializadas com ReflectionProperty::skipLazyInitialization() ou ReflectionProperty::setRawValueWithoutLazyInitialization() são definidas com seus valores padrão, se houver. Neste estágio, o objeto se assemelha a um criado com ReflectionClass::newInstanceWithoutConstructor(), exceto pelas propriedades já inicializadas.
- A função inicializadora é então chamada com o objeto como seu primeiro parâmetro. A função é esperada, mas não obrigatória, para inicializar o estado do objeto e deve retornar `null` ou nenhum valor. O objeto não é mais lento neste ponto, então a função pode acessar suas propriedades diretamente.

Após a inicialização, o objeto é indistinguível de um objeto que nunca foi lento.

#### Objetos Proxy

- O objeto é marcado como não-lento.
- Ao contrário dos objetos fantasmas, as propriedades do objeto não são modificadas neste estágio.
- A função de fábrica é chamada com o objeto como seu primeiro parâmetro e deve retornar uma instância não-lenta de uma classe compatível (veja ReflectionClass::newLazyProxy()).
- A instância retornada é chamada de instância real e é anexada ao proxy.
- Os valores das propriedades do proxy são descartados como se unset() tivesse sido chamada.

Após a inicialização, acessar qualquer propriedade no proxy produzirá o mesmo resultado que acessar a propriedade correspondente na instância real; todos os acessos de propriedade no proxy são encaminhados para a instância real, incluindo propriedades declaradas, dinâmicas, inexistentes ou marcadas com ReflectionProperty::skipLazyInitialization() ou ReflectionProperty::setRawValueWithoutLazyInitialization().

O objeto proxy em si não é substituído pela instância real.

Embora a fábrica receba o proxy como primeiro parâmetro, não se espera modificá-lo (modificações são permitidas, mas serão perdidas durante a etapa final de inicialização). Entretanto, o proxy pode ser usado para decisões baseadas nos valores das propriedades inicializadas, na classe, no próprio objeto ou em sua identidade. Por exemplo, o inicializador pode usar o valor de uma propriedade inicializada ao criar a instância real.

#### Comportamento Comum

O escopo e o contexto $this do inicializador ou da função de fábrica permanecem inalterados e as restrições de visibilidade usuais se aplicam.

Após a inicialização bem-sucedida, o inicializador ou função de fábrica não é mais referenciado pelo objeto e pode ser liberado se não tiver outras referências.

Se o inicializador lançar uma exceção, o estado do objeto será revertido para seu estado de pré-inicialização e o objeto será marcado como lento novamente. Em outras palavras, todos os efeitos no próprio objeto são revertidos. Outros efeitos colaterais, como efeitos em outros objetos, não são revertidos. Isso evita a exposição de uma instância parcialmente inicializada em caso de falha.

### Clonagem

Clonar um objeto lento aciona sua inicialização antes do clone ser criado, resultando em um objeto inicializado.

Para objetos proxy, tanto o proxy quanto sua instância real são clonados e o clone do proxy é retornado. O método `__clone` é chamado na instância real, não no proxy. O proxy clonado e a instância real são vinculados como estão durante a inicialização, portanto, os acessos ao clone do proxy são encaminhados para o clone da instância real.

Esse comportamento garante que o clone e o objeto original mantenham estados separados. As alterações no objeto original ou no estado de seu inicializador após a clonagem não afetam o clone. Clonar o proxy e sua instância real, em vez de retornar apenas um clone da instância real, garante que a operação de clonagem retorne consistentemente um objeto da mesma classe.

### Destrutores

Para fantasmas lentos, o destrutor só é chamado se o objeto tiver sido inicializado. Para proxies, o destrutor só é chamado na instância real, se existir.

Os métodos ReflectionClass::resetAsLazyGhost() e ReflectionClass::resetAsLazyProxy() podem invocar o destrutor do objeto que está sendo redefinido.

## Lista de alterações da POO

As alterações no modelo de POO do PHP são registradas aqui. Descrições e outras notas relacionadas a estes recursos estão documentadas na documentação do modelo POO.

Versão | Descrição
--- | ---
8.4.0 | Adicionado: suporte para Ganchos de Propriedade.
8.4.0 | Adicionado: suporte para Objetos Lentos.
8.1.0 | Adicionado: suporte ao modificador final para constantes de classe. Além disso, as constantes de interface agora são substituíveis por padrão.
8.0.0 | Adicionado: suporte ao operador nullsafe ?-> para acessar propriedades e métodos em objetos que podem ser nulos.
7.4.0 | Alterado: agora é possível lançar uma exceção dentro de __toString().
7.4.0 | Adicionado: suporte a covariância limitada de tipo de retorno e contravariância de tipo de argumento. O suporte completo à variância só estará disponível se o carregamento automático for usado. Dentro de um único arquivo, apenas referências de tipo não cíclicas são possíveis.
7.4.0 | Adicionado: agora é possível usar tipos nas propriedades da classe.
7.3.0 | Incompatibilidade: o desempacotamento de argumentos com instâncias de Traversable com chaves não-int não é mais suportado. Esse comportamento não era intencional e, portanto, foi removido.
7.3.0 | Incompatibilidade: nas versões anteriores era possível separar as propriedades estáticas atribuindo uma referência. Isso foi removido.
7.3.0 | Alterado: o operador instanceof agora permite literais como o primeiro operando, caso em que o resultado é sempre `false`.
7.2.0 | Descontinuado: a função __autoload() foi descontinuada em favor da função spl_autoload_register().
7.2.0 | Alterado: o seguinte nome não pode ser usado para nomear classes, interfaces ou traits: `object`.
7.2.0 | Alterado: uma vírgula à direita agora pode ser adicionada à sintaxe de agrupamento de use para namespaces.
7.2.0 | Alterado: extensão do tipo de parâmetro. Os tipos de parâmetro de métodos sobrescritos e de implementações de interface agora podem ser omitidos.
7.2.0 | Alterado: métodos abstratos agora podem ser sobrescritos quando uma classe abstrata estende outra classe abstrata.
7.1.0 | Alterado: os nomes a seguir não podem ser usados para nomear classes, interfaces ou traits: `void` e `iterable`.
7.1.0 | Adicionado: agora é possível especificar a visibilidade das constantes de classe.
7.0.0 | Descontinuado: chamadas estáticas a métodos que não são declarados estáticos.
7.0.0 | Descontinuado: construtor no estilo do PHP 4. Ou seja, métodos com o mesmo nome da classe em que eles são definidos.
7.0.0 | Adicionado: a declaração use de grupo: classes, funções e constantes importadas do mesmo namespace agora podem ser agrupadas em uma única declaração use.
7.0.0 | Adicionado: o suporte a classes anônimas foi adicionado via `new class`.
7.0.0 | Incompatibilidade: iterar sobre um object que não seja uma instância de Traversable agora terá o mesmo comportamento que iterar sobre arrays por referência.
7.0.0 | Alterado: definir propriedades (compatíveis) em duas traits não dispara mais um erro.
5.6.0 | Adicionado: o método __debugInfo().
5.5.0 | Adicionado: a constante mágica ::class.
5.5.0 | Adicionado: finally para manipular exceções.
5.4.0 | Adicionado: traits.
5.4.0 | Alterado: se uma classe abstrata definir uma assinatura para o construtor, agora ela será imposta.
5.3.3 | Alterado: métodos com o mesmo nome do último elemento de uma classe com namespace não serão mais tratados como construtores. Esta alteração não afeta classes sem namespace.
5.3.0 | Alterado: classes que implementam interfaces com métodos que possuem valores padrão no protótipo não precisam mais corresponder ao valor padrão da interface.
5.3.0 | Alterado: agora é possível referenciar a classe usando uma variável (por exemplo, `echo $nome_da_classe::CONSTANTE;`). O valor da variável não pode ser uma palavra-chave (por exemplo, `self`, `parent` ou `static`).
5.3.0 | Alterado: um erro de nível `E_WARNING` será emitido se os métodos mágicos de sobrecarga forem declarados estáticos. Também impõe o requisito de visibilidade pública.
5.3.0 | Alterado: antes do PHP 5.3.0, as exceções lançadas na função __autoload() não podiam ser capturadas no bloco catch e resultariam em um erro fatal. Agora as exceções lançadas na função __autoload podem ser capturadas no bloco catch, com uma condição. Se uma exceção personalizada for lançada, a classe de exceção personalizada deve estar disponível. A função __autoload pode ser usada recursivamente para carregar automaticamente a classe de exceção personalizada.
5.3.0 | Adicionado: o método __callStatic.
5.3.0 | Adicionado: suporte a heredoc e nowdoc nas definições de constantes e propriedades de classe. Nota: os valores heredoc devem seguir as mesmas regras que strings com aspas duplas, (por exemplo, sem variáveis dentro).
5.3.0 | Adicionado: Late Static Bindings.
5.3.0 | Adicionado: o método __invoke().
5.2.0 | Alterado: o método __toString() só era chamado quando combinado diretamente com echo ou print. Mas agora, ele é chamado em qualquer contexto de string (por exemplo, em printf() com o modificador `%s`), mas não em outros contextos de tipos (por exemplo, com o modificador `%d`). A partir do PHP 5.2.0, a conversão de objects sem um método __toString para string emitirá um erro de nível `E_RECOVERABLE_ERROR`.
5.1.3 | Alterado: nas versões anteriores do PHP 5, o uso de `var` era considerado descontinuado e emitiria um erro de nível `E_STRICT`. Agora não é mais descontinuado, portanto não emite o erro.
5.1.0 | Alterado: o método estático __set_state() agora é chamado por classes exportadas com a função var_export().
5.1.0 | Adicionado: os métodos __isset() e __unset().

# Namespaces

## Índice

- Visão Geral
- Namespaces
- Sub-namespaces
- Definindo vários namespaces no mesmo arquivo
- Fundamentos
- Namespaces e recursos de linguagem dinâmica
- Palavra-chave namespace e __NAMESPACE__
- Apelidando e Importando
- Espaço Global
- Recorrendo ao espaço global
- Regras de resolução de nomes
- Perguntas Frequentes

## Visão geral de Namespaces

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

O que são namespaces? Na definição mais ampla, os namespaces (na tradução literal, "espaços de nomes") são uma forma de encapsular itens. Isso é visto como um conceito abstrato em muitos lugares. Por exemplo, em qualquer sistema operacional, os diretórios servem para agrupar arquivos relacionados, e agem como um namespace para os arquivos dentro deles. Como um exemplo concreto, o arquivo `foo.txt` pode existir em ambos os diretórios `/home/greg` e `/home/other`, mas duas cópias de `foo.txt` não podem coexistir em um mesmo diretório. Além disso, para acessar o arquivo `foo.txt` fora do diretório `/home/greg`, o nome do diretório deve ser prefixado ao nome do arquivo usando o separador de diretórios para obter `/home/greg/foo.txt`. Esse mesmo princípio se estende a namespaces no mundo da programação.

No mundo PHP, os namespaces são projetados para resolver dois problemas que os autores de bibliotecas e aplicações encontram ao criar elementos de código reutilizáveis, como classes ou funções:

1. Colisões de nomes entre o código criado e classes/funções/constantes internas do PHP ou classes/funções/constantes de terceiros.
2. Capacidade de criar apelidos (ou encurtar) Nomes_Extralongos projetados para aliviar o primeiro problema, melhorando a legibilidade do código-fonte.

Os Namespaces do PHP fornecem uma maneira de agrupar classes, interfaces, funções e constantes relacionadas. Aqui está um exemplo da sintaxe de namespace em PHP:

Exemplo #1 Exemplo da sintaxe de namespace

    <?php
    namespace meu\nome; // veja a seção "Definindo Namespaces"

    class MinhaClasse {}
    function minhafuncao() {}
    const MINHACONST = 1;

    $a = new MinhaClasse;
    print $a::class . "\n";
    $c = new \meu\nome\MinhaClasse; // veja a seção "Espaço Global"
    print $c::class . "\n";

    $a = strlen('oi'); // veja a seção "Usando namespaces: recorrendo a
                       // funções/constantes globais"
    print $a . "\n";

    $d = namespace\MINHACONST; // veja a seção "operador de namespace
                               // e constante __NAMESPACE__"
    print $d . "\n";
    $d = __NAMESPACE__ . '\MINHACONST';
    echo constant($d); // veja a seção "Namespaces e recursos de linguagem dinâmica"

> Nota: Nomes de namespace não diferenciam maiúsculas de minúsculas.

> Nota:

> O nome do namespace `PHP` e os nomes compostos que começam com esse nome (como `PHP\Classes`) são reservados para uso interno da linguagem e não devem ser usados no código criado pelo usuário.

## Definindo namespaces

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Embora qualquer código PHP válido possa estar contido em um namespace, apenas os seguintes tipos de código são afetados por namespaces: classes (incluindo abstratas, traits e enumerações), interfaces, funções e constantes.

Namespaces são declarados usando a palavra-chave `namespace`. Um arquivo contendo um namespace deve declarar o namespace no início do arquivo antes de qualquer outro código - com uma exceção: a palavra-chave declare.

Exemplo #1 Declarando um único namespace

    <?php
    namespace MeuProjeto;

    const CONEXAO_OK = 1;
    class Conexao { /* ... */ }
    function conectar() { /* ... */ }

> Nota: Nomes totalmente qualificados (ou seja, nomes que começam com uma barra invertida) não são permitidos em declarações de namespace, por serem construções interpretadas como expressões de namespace relativos.

A única construção de código permitida antes de uma declaração de namespace é a declaração `declare`, para definir a codificação de um arquivo-fonte. Além disso, nenhum código não-PHP pode preceder uma declaração de namespace, incluindo espaço em branco extra:

Exemplo #2 Declarando um único namespace

    <html>
    <?php
    namespace MeuProjeto; // erro fatal - namespace precisa ser a primeira declaração no script

Além disso, ao contrário de qualquer outra construção do PHP, o mesmo namespace pode ser definido em vários arquivos, permitindo a divisão do conteúdo de um namespace no sistema de arquivos.

## Declarando sub-namespaces

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Assim como diretórios e arquivos, os namespaces do PHP podem especificar uma hierarquia de namespaces. Assim, um namespace pode ser definido com subníveis.

Exemplo #1 Declarando um único namespace com hierarquia

    <?php
    namespace MeuProjeto\Nivel\SubNivel;

    const CONEXAO_OK = 1;
    class Conexao { /* ... */ }
    function conectar() { /* ... */  }

O exemplo acima cria a constante `MeuProjeto\Nivel\SubNivel\CONEXAO_OK`, a classe `MeuProjeto\Nivel\SubNivel\Conexao` e a função `MeuProjeto\Nivel\SubNivel\conectar`.

## Definindo vários namespaces no mesmo arquivo

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Vários namespaces também podem ser declarados no mesmo arquivo. Existem duas sintaxes permitidas.

Exemplo #1 Declarando vários namespaces, sintaxe de combinação simples

    <?php
    namespace MeuProjeto;

    const CONEXAO_OK = 1;
    class Conexao { /* ... */ }
    function conectar() { /* ... */  }

    namespace OutroProjeto;

    const CONEXAO_OK = 1;
    class Conexao { /* ... */ }
    function conectar() { /* ... */  }

Essa sintaxe não é recomendada para combinar namespaces em um único arquivo. Em vez disso, é recomendado usar a sintaxe alternativa de colchetes.

Exemplo #2 Declarando vários namespaces, sintaxe de colchetes

    <?php
    namespace MeuProjeto {

    const CONEXAO_OK = 1;
    class Conexao { /* ... */ }
    function conectar() { /* ... */  }
    }

    namespace OutroProjeto {

    const CONEXAO_OK = 1;
    class Conexao { /* ... */ }
    function conectar() { /* ... */  }
    }

É altamente desaconselhado como prática de programação combinar vários namespaces no mesmo arquivo. O principal caso de uso é combinar vários scripts PHP no mesmo arquivo.

Para combinar código global sem namespace com código com namespace, apenas a sintaxe de colchetes é suportada. O código global deve ser encapsulado em uma declaração de namespace sem nome de namespace, como em:

Exemplo #3 Declarando vários namespaces e código sem namespace

    <?php
    namespace MeuProjeto {

    const CONEXAO_OK = 1;
    class Conexao {
        public static function iniciar() {
            print __METHOD__ . "\n";
        }
    }

    function conectar() {
        print __FUNCTION__ . "\n";
    }
    }

    namespace { // código global
    print strlen("olá") . "\n";
    MeuProjeto\conectar();
    MeuProjeto\Conexao::iniciar();
    }

Nenhum código PHP pode existir fora dos colchetes do namespace, exceto uma declaração declare de abertura.

Exemplo #4 Declarando vários namespaces e código sem namespace

    <?php
    declare(strict_types=1);
    namespace MeuProjeto {

    const CONEXAO_OK = 1;
    class Conexao {
        public static function iniciar() {
            print __METHOD__ . "\n";
        }
    }

    function conectar() {
        print __FUNCTION__ . "\n";
    }
    }

    namespace { // código global
    print strlen("olá") . "\n";
    MeuProjeto\conectar();
    MeuProjeto\Conexao::iniciar();
    }

## Usando namespaces: Fundamentos

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Antes de discutir o uso de namespaces, é importante entender como o PHP sabe qual elemento de namespace seu código está solicitando. Uma analogia simples pode ser feita entre os namespaces do PHP e um sistema de arquivos. Existem três maneiras de acessar um arquivo em um sistema de arquivos:

1. Nome de arquivo relativo como `foo.txt`. Será resolvido para `diretorioatual/foo.txt` onde `diretorioatual` é o diretório ocupado atualmente. Então, se o diretório atual for `/home/foo`, o nome será resolvido para `/home/foo/foo.txt`.
2. Nome de caminho relativo como `subdiretorio/foo.txt`. Será resolvido para `diretorioatual/subdiretorio/foo.txt`.
3. Nome de caminho absoluto como `/main/foo.txt`. Será resolvido para `/main/foo.txt`.

O mesmo princípio pode ser aplicado a elementos com namespace no PHP. Por exemplo, um nome de classe pode ser referenciado de três maneiras:

1. Nome não qualificado ou nome de classe sem prefixo como `$a = new foo();` ou `foo::metodoestatico();`. Se o namespace atual for `namespaceatual`, ele será resolvido para `namespaceatual\foo`. Se o código for global, sem namespace, ele será resolvido para `foo`. Uma ressalva: nomes não qualificados para funções e constantes serão resolvidos para funções e constantes globais se a função ou constante com namespace não for definida. Veja Usando namespaces: recorrendo a funções/constantes globais para obter detalhes.
2. Nome qualificado ou um nome de classe prefixado como `$a = new subnamespace\foo();` ou `subnamespace\foo::metodoestatico();`. Se o namespace atual for `namespaceatual`, ele será resolvido para `namespaceatual\subnamespace\foo`. Se o código for global, sem namespace, ele será resolvido para `subnamespace\foo`.
3. Nome totalmente qualificado ou um nome prefixado com um operador de prefixo global como `$a = new \namespaceatual\foo();` ou `\namespaceatual\foo::metodoestatico();`. Ele sempre será resolvido para o nome literal especificado no código, `namespaceatual\foo`.

Aqui está um exemplo dos três tipos de sintaxe em código real:

arquivo1.php

    <?php
    namespace Foo\Bar\subnamespace;

    const FOO = 1;
    function foo() {}
    class foo
    {
        static function metodoestatico() {}
    }

arquivo2.php

    <?php
    namespace Foo\Bar;
    include 'arquivo1.php';

    const FOO = 2;
    function foo() {}
    class foo
    {
        static function metodoestatico() {}
    }

    /* Nome não qualificado */
    foo(); // será resolvido para a função Foo\Bar\foo
    foo::metodoestatico(); // será resolvido para a classe Foo\Bar\foo, método metodoestatico
    echo FOO; // será resolvido para a constante Foo\Bar\FOO

    /* Nome qualificado */
    subnamespace\foo(); // será resolvido para a função Foo\Bar\subnamespace\foo
    subnamespace\foo::metodoestatico(); // será resolvido para a classe Foo\Bar\subnamespace\foo,
                                        // método metodoestatico
    echo subnamespace\FOO; // será resolvido para a constante constant Foo\Bar\subnamespace\FOO

    /* Nome totalmente qualificado */
    \Foo\Bar\foo(); // será resolvido para a função Foo\Bar\foo
    \Foo\Bar\foo::metodoestatico(); // será resolvido para a classe Foo\Bar\foo, método metodoestatico
    echo \Foo\Bar\FOO; // será resolvido para a constante Foo\Bar\FOO

Note que para acessar qualquer classe, função ou constante global, um nome totalmente qualificado pode ser usado, como \strlen() ou \Exception ou \`INI_ALL`.

Exemplo #1 Acessando classes, funções e constantes globais em um namespace

    <?php
    namespace Foo;

    function strlen() {}
    const INI_ALL = 3;
    class Exception {}

    print \strlen('olá') . "\n"; // chama a função global strlen
    print \INI_ALL . "\n"; // acessa a constante global INI_ALL
    $c = new \Exception('erro'); // instancia um objeto da classe global Exception
    print $c::class . "\n";

## Namespaces e recursos de linguagem dinâmica

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

A implementação de namespaces do PHP é influenciada por sua natureza dinâmica como linguagem de programação. Assim, para converter código como o exemplo a seguir em código com namespace:

Exemplo #1 Acessando elementos dinamicamente

exemplo1.php:

    <?php
    class nomedaclasse
    {
        function __construct()
        {
            echo __METHOD__,"\n";
        }
    }
    function nomedafuncao()
    {
        echo __FUNCTION__,"\n";
    }
    const nomedaconstante = "global";

    $a = 'nomedaclasse';
    $obj = new $a; // imprime nomedaclasse::__construct
    $b = 'nomedafuncao';
    $b(); // imprime nomedafuncao
    echo constant('nomedaconstante'), "\n"; // imprime global

Deve-se usar o nome totalmente qualificado (nome da classe prefixado com o namespace). Observe que, como não há diferença entre um nome qualificado e um nome totalmente qualificado em um nome de classe, nome de função ou nome de constante dinâmico, a barra invertida inicial não é necessária.

Exemplo #2 Acessando dinamicamente elementos com namespace

    <?php
    namespace nomedonamespace;
    class nomedaclasse
    {
        function __construct()
        {
            echo __METHOD__,"\n";
        }
    }
    function nomedafuncao()
    {
        echo __FUNCTION__,"\n";
    }
    const nomedaconstante = "comnamespace";

    /* note que, ao usar aspas duplas, "\\nomedonamespace\\nomedaclasse" deve ser usado */
    $a = '\nomedonamespace\nomedaclasse';
    $obj = new $a; // imprime nomedonamespace\nomedaclasse::__construct
    $a = 'nomedonamespace\nomedaclasse';
    $obj = new $a; // também imprime nomedonamespace\nomedaclasse::__construct
    $b = 'nomedonamespace\nomedafuncao';
    $b(); // imprime nomedonamespace\nomedafuncao
    $b = '\nomedonamespace\nomedafuncao';
    $b(); // também imprime nomedonamespace\nomedafuncao
    echo constant('\nomedonamespace\nomedaconstante'), "\n"; // imprime comnamespace
    echo constant('nomedonamespace\nomedaconstante'), "\n"; // também imprime comnamespace

Certifique-se de ler a nota sobre escapamento de namespaces em strings.

## Palavra-chave namespace e constante __NAMESPACE__

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

O PHP suporta duas maneiras de acessar elementos de forma abstrata dentro do namespace atual, a constante mágica `__NAMESPACE__` e a palavra-chave `namespace`.

O valor de `__NAMESPACE__` é uma string que contém o nome do namespace atual. Em código global, sem namespace, ela contém uma string vazia.

Exemplo #1 Exemplo de __NAMESPACE__, código com namespace

    <?php
    namespace MeuProjeto;

    echo '"', __NAMESPACE__, '"'; // produz "MeuProjeto"

Exemplo #2 Exemplo de __NAMESPACE__, código global

    <?php
    echo '"', __NAMESPACE__, '"'; // produz ""

A constante `__NAMESPACE__` é útil para construir nomes de forma dinâmica, por exemplo:

Exemplo #3 Usando __NAMESPACE__ para construção dinâmica de nomes

    <?php
    namespace MeuProjeto;

    function get($nomedaclasse)
    {
        $a = __NAMESPACE__ . '\\' . $nomedaclasse;
        return new $a;
    }

A palavra-chave `namespace` pode ser usada para solicitar explicitamente um elemento do namespace atual ou um subnamespace. Ela é o equivalente para namespaces do operador `self` para classes.

Exemplo #4 O operador namespace, em um namespace

    <?php
    namespace MeuProjeto;

    use bla\bla as meu; // Veja "Usando namespaces: Apelidando/Importando"

    bla\meu(); // chama a função MeuProjeto\bla\meu()
    namespace\bla\meu(); // chama a função MeuProjeto\bla\meu()

    namespace\funcao(); // chama a função MeuProjeto\funcao()
    namespace\sub\funcao(); // chama a função MeuProjeto\sub\funcao()
    namespace\nomedaclasse::metodo(); // chama o método estático "metodo" da classe MeuProjeto\nomedaclasse
    $a = new namespace\sub\nomedaclasse(); // instancia um objeto da classe MeuProjeto\sub\nomedaclasse
    $b = namespace\CONSTANTE; // atribui o valor da constante MeuProjeto\CONSTANTE a $b

Exemplo #5 O operador namespace, em código global

    <?php

    namespace\funcao(); // chama a função funcao()
    namespace\sub\funcao(); // chama a função sub\funcao()
    namespace\nomedaclasse::metodo(); // chama o método estático "metodo" da classe nomedaclasse
    $a = new namespace\sub\nomedaclasse(); // instancia um objeto da classe sub\nomedaclasse
    $b = namespace\CONSTANTE; // atribui o valor da constante CONSTANTE a $b

## Usando namespaces: Apelidando/Importando

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

A capacidade de se referir a um nome totalmente qualificado externo com um apelido, ou importação, é um recurso importante dos namespaces. Isso é semelhante à capacidade dos sistemas de arquivos baseados em Unix de criar links simbólicos para um arquivo ou diretório.

O PHP pode apelidar ou importar constantes, funções, classes, interfaces, traits, enums e namespaces.

A criação de apelidos é realizada com o operador `use`. Aqui está um exemplo mostrando todos os 5 tipos de importação:

Exemplo #1 Importando ou apelidando com o operador use

    <?php
    namespace foo;
    use Caminho\Completo\Classe as Outra;

    // Isso é o mesmo que use Caminho\Completo\NomeNamespace as NomeNamespace
    use Caminho\Completo\NomeNamespace;

    // Importando uma classe global
    use ArrayObject;

    // Importando uma função
    use function Caminho\Completo\nomeFuncao;

    // Apelidando uma função
    use function Caminho\Completo\nomeFuncao as funcao;

    // Importando uma constante
    use const Caminho\Completo\CONSTANTE;

    $obj = new namespace\Outra; // Instancia um objeto da classe foo\Outra
    $obj = new Outra; // Instancia um objeto da classe Caminho\Completo\Classe
    NomeNamespace\SubNamespace\funcao(); // Chama a função Caminho\Completo\NomeNamespace\SubNamespace\funcao
    $a = new ArrayObject(array(1)); // Instancia um objeto da classe ArrayObject
    // Sem a declaração "use ArrayObject" teria sido instanciado um objeto da classe foo\ArrayObject
    funcao(); // chama a função Caminho\Completo\nomeFuncao
    echo CONSTANTE; // imprime o valor de Caminho\Completo\CONSTANTE

Note que para nomes com namespaces (nomes de namespaces totalmente qualificados contendo o separador de namespace, como `Foo\Bar`, em oposição a nomes globais sem separadores, como `FooBar`), a barra invertida inicial não é necessária e não é recomendada, pois nomes importados precisam ser totalmente qualificados e não são processados em relação ao namespace atual.

O PHP também suporta um atalho de conveniência para colocar várias instruções use na mesma linha.

Exemplo #2 Importando ou criando apelidos com várias declarações use combinadas

    <?php
    use Caminho\Completo\Classe as Outra, Caminho\Completo\NomeNamespace;

    $obj = new Outra;    // Instancia um objeto da classe Caminho\Completo\Classe
    NomeNamespace\SubNamespace\funcao(); // Chama a função Caminho\Completo\NomeNamespace\SubNamespace\funcao

A importação é realizada em tempo de compilação e por isso, não afeta classes, funções ou nomes de constantes gerados dinamicamente.

Exemplo #3 Importação e nomes dinâmicos

    <?php
    use Caminho\Completo\Classe as Outra, Caminho\Completo\NomeNamespace;

    $obj = new Outra; // Instancia um objeto da classe Caminho\Completo\Classe
    $a = 'Outra';
    $obj = new $a;    // Instancia um objeto da classe Outra

Além disso, a importação afeta apenas nomes não qualificados e qualificados. Nomes totalmente qualificados são absolutos e não são afetados pelas importações.

Exemplo #4 Importação e nomes completamente qualificados

    <?php
    use Caminho\Completo\Classe as Outra, Caminho\Completo\NomeNamespace;

    $obj = new Outra;        // Instancia um objeto da classe Caminho\Completo\Classe
    $obj = new \Outra;       // Instancia um objeto da classe Outra
    $obj = new Outra\Coisa;  // Instancia um objeto da classe Caminho\Completo\Classe\Coisa
    $obj = new \Outra\Coisa; // Instancia um objeto da classe Outra\Coisa

### Regras de escopo para importação

A palavra-chave `use` precisa ser declarada no escopo mais externo do arquivo (o escopo global) ou dentro de declarações de namespaces. Isso ocorre por a importação ser realizada em tempo de compilação e não em tempo de execução, portanto, não pode ter escopo de bloco. O exemplo a seguir mostra um uso inválido da palavra-chave `use`:

Exemplo #5 Regra de importação inválida

    <?php
    namespace Linguas;

    function paraGroenlandes()
    {
        use Linguas\Dinamarques;

        // ...
    }

> Nota:

> As regras de importação são por arquivo, o que significa que os arquivos incluídos NÃO herdarão as regras de importação do arquivo pai.

### Declarações `use` em grupo

Classes, funções e constantes importadas do mesmo `namespace` podem ser agrupadas numa única declaração `use`.

    <?php

    use algum\namespace\ClasseA;
    use algum\namespace\ClasseB;
    use algum\namespace\ClasseC as C;

    use function algum\namespace\fn_a;
    use function algum\namespace\fn_b;
    use function algum\namespace\fn_c;

    use const algum\namespace\ConstA;
    use const algum\namespace\ConstB;
    use const algum\namespace\ConstC;

    // É equivalente à seguinte declaração "use" agrupada
    use algum\namespace\{ClasseA, ClasseB, ClasseC as C};
    use function algum\namespace\{fn_a, fn_b, fn_c};
    use const algum\namespace\{ConstA, ConstB, ConstC};

## Espaço Global

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Quando um namespace não é definido, todas as definições de classes e funções são colocadas no espaço global, como era no PHP antes de os namespaces serem suportados. Prefixar um nome com `\` especificará que o nome é necessário no espaço global, mesmo no contexto do namespace.

Exemplo #1 Usando a especificação do espaço global

    <?php
    namespace A\B\C;

    /* Esta função é A\B\C\fopen */
    function fopen() {
         /* ... */
         $f = \fopen(...); // chama a função fopen global
         return $f;
    }

## Usando namespaces: recorrendo ao espaço global para funções e constantes

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Dentro de um namespace, quando o PHP encontra um nome não qualificado em um nome de classe, função ou contexto de constante, eles são resolvidos com diferentes prioridades. Nomes de classe sempre são resolvidos para o nome do namespace atual. Portanto, para acessar classes internas ou classes de usuário sem namespace, deve-se referir a elas com o nome totalmente qualificado como em:

Exemplo #1 Acessando classes globais em um namespace

    <?php
    namespace A\B\C;
    class Exception extends \Exception {}

    $a = new Exception('oi'); // $a é um objeto da classe A\B\C\Exception
    var_dump($a::class);
    $b = new \Exception('oi'); // $b é um objeto da classe Exception
    var_dump($b::class);

    $c = new ArrayObject; // erro fatal, classe A\B\C\ArrayObject não encontrada

Para funções e constantes, o PHP recorrerá a funções ou constantes globais se a função ou constante com namespace não existir.

Exemplo #2 Recorrendo a funções/constantes globais em um namespace

    <?php
    namespace A\B\C;

    const E_ERROR = 45;
    function strlen($str)
    {
        return \strlen($str) - 1;
    }

    echo E_ERROR, "\n"; // imprime "45"
    echo INI_ALL, "\n"; // imprime "7" - recorre à constante INI_ALL global

    echo strlen('oi'), "\n"; // imprime "1"
    if (is_array('oi')) { // imprime "não é array"
        echo "é array\n";
    } else {
        echo "não é array\n";
    }

## Regras de resolução de nomes

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Para efeitos destas regras de resolução, aqui estão algumas definições importantes:

Definições de nomes de namespace
Nome não qualificado

  Este é um identificador sem separador de namespace, como `Foo`.

Nome qualificado

  Este é um identificador com separador de namespace, como `Foo\Bar`.

Nome totalmente qualificado

  Este é um identificador com separador de namespace que começa com um separador de namespace, como `\Foo\Bar`. O namespace `\Foo` também é um nome totalmente qualificado.

Nome relativo

  Este é um identificador que começa com `namespace`, como `namespace\Foo\Bar`.

Os nomes são resolvidos seguindo estas regras de resolução:

1. Nomes totalmente qualificados sempre são resolvidos para o nome sem separador de namespace à esquerda. Por exemplo, `\A\B` será resolvido para `A\B`.
2. Nomes relativos sempre são resolvidos para o nome com `namespace` substituído pelo namespace atual. Se o nome ocorrer no namespace global, o prefixo `namespace\` será removido. Por exemplo, `namespace\A` dentro do namespace `X\Y` será resolvido para `X\Y\A`. O mesmo nome dentro do namespace global será resolvido para `A`.
3. Para nomes qualificados, o primeiro segmento do nome será traduzido conforme a tabela de importação de classe/namespace atual. Por exemplo, se o namespace `A\B\C` for importado como `C`, o nome `C\D\E` será traduzido para `A\B\C\D\E`.
4. Para nomes qualificados, se nenhuma regra de importação se aplicar, o namespace atual será prefixo ao nome. Por exemplo, o nome `C\D\E` dentro do namespace `A\B`, será resolvido para `A\B\C\D\E`.
5. Para nomes não qualificados, o nome será traduzido conforme a tabela de importação atual para o respectivo tipo de símbolo. Isso significa que nomes semelhantes a classes serão traduzidos conforme a tabela de importação de classe/namespace, nomes de funções conforme a tabela de importação de funções e constantes conforme a tabela de importação de constantes. Por exemplo, após a declaração `use A\B\C;` um uso como `new C()` será resolvido para o nome `A\B\C()`. Da mesma forma, após a declaração `use function A\B\foo;` um uso como `foo()` será resolvido para o nome `A\B\foo`.
6. Para nomes não qualificados, se nenhuma regra de importação se aplicar e o nome se referir a um símbolo de classe, o namespace atual será prefixo. Por exemplo `new C()` dentro do namespace `A\B` será resolvido para o nome `A\B\C`.
7. Para nomes não qualificados, se nenhuma regra de importação se aplicar e o nome se referir a uma função ou constante e o código estiver fora do namespace global, o nome será resolvido em tempo de execução. Supondo que o código esteja no namespace `A\B`, é assim que uma chamada para a função `foo()` será resolvida:
   1. Procura pela função no namespace atual: `A\B\foo()`.
   2. Tenta encontrar e chamar a função global `foo()`.

Exemplo #1 Resoluções de nomes ilustradas

    <?php
    namespace A;
    use B\D, C\E as F;

    // chamadas de funções

    foo();       // primeiro tenta chamar "foo" definida no namespace "A"
                 // então chama a função global "foo"

    \foo();      // chama a função "foo" definida no escopo global

    minha\foo(); // chama a função "foo" definida no namespace "A\minha"

    F();         // primeiro tenta chamar "F" definida no namespace "A"
                 // e então chama a função global "F"

    // referências de classe

    new B();    // cria um objeto da classe "B" definida no namespace "A"
                // se não for encontrada, tenta carregar automaticamente a classe  "A\B"

    new D();    // usando regras de importação, cria um objeto da classe "D" definida no namespace "B"
                // se não for encontrada, tenta carregar automaticamente a classe "B\D"

    new F();    // usando regras de importação, cria um objeto da classe "E" definida no namespace "C"
                // se não for encontrada, tenta carregar automaticamente a classe "C\E"

    new \B();   // cria um objeto da classe "B" definida no escopo global
                // se não for encontrada, tenta carregar automaticamente a classe "B"

    new \D();   // cria um objeto da classe "D" definida no escopo global
                // se não for encontrado, tenta carregar automaticamente a classe "D"

    new \F();   // cria um objeto da classe "F" definida no escopo global
                // se não for encontrada, tenta carregar automaticamente a classe "F"

    // métodos estáticos/funções de namespace de outro namespace

    B\foo();    // chama a função "foo" do namespace "A\B"

    B::foo();   // chama o método "foo" da classe "B" definida no namespace "A"
                // se a classe "A\B" não for encontrada, tenta carregar automaticamente a classe "A\B"

    D::foo();   // usando regras de importação, chama o método "foo" da classe "D" definida no namespace "B"
                // se a classe "B\D" não for encontrada, tenta carregar automaticamente a classe "B\D"

    \B\foo();   // chama a função "foo" do namespace "B"

    \B::foo();  // chama o método "foo" da classe "B" do escopo global
                // se a classe "B" não for encontrada, tenta carregar automaticamente a classe "B"

    // métodos estáticos/funções de namespace do namespace atual

    A\B::foo();   // chama o método "foo" da classe "B" do namespace "A\A"
                  // se a classe "A\A\B" não for encontrada, tenta carregar automaticamente a class "A\A\B"

    \A\B::foo();  // chama o método "foo" da classe "B" do namespace "A"
                  // se a classe "A\B" não for encontrada, tenta carregar automaticamente a classe "A\B"

## Perguntas Frequentes: Coisas que você precisa saber sobre namespaces

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Estas perguntas frequentes são divididas em duas seções: perguntas comuns e alguns detalhes de implementação úteis para entender os pormenores.

Primeiro, as perguntas comuns.

1. Se não usar namespaces, devo me importar com esta documentação?
2. Como usar classes internas ou globais em um namespace?
3. Como usar classes, funções ou constantes de namespace em seu próprio namespace?
4. Como nomes como `\meu\nome` ou `\nome` são resolvidos?
5. Como um nome como `meu\nome` é resolvido?
6. Como um nome de classe não qualificado como `nome` é resolvido?
7. Como um nome de função não qualificado ou nome de constante não qualificado como `nome` é resolvido?

Há alguns detalhes de implementação dos namespaces úteis para entendê-los melhor.

1. Nomes de importação não devem entrar em conflito com classes definidas no mesmo arquivo
2. Namespaces aninhados não são permitidos.
3. Nomes de namespace dinâmicos (identificadores entre aspas) devem escapar a barra invertida
4. Constantes indefinidas referenciadas usando qualquer barra invertida geram erro fatal
5. Não é possível substituir as constantes especiais `null`, `true` ou `false`

### Se não usar namespaces, devo me importar com esta documentação?

Não. Namespaces não afetam nenhum código existente de forma alguma, ou qualquer código ainda a ser escrito que não contenha namespaces. Você pode escrever este código se desejar:

Exemplo #1 Acessando classes globais fora de um namespace

    <?php
    $a = new \stdClass;
    print $a::class;

O exemplo acima é equivalente ao seguinte código:

Exemplo #2 Acessando classes globais fora de um namespace

    <?php
    $a = new stdClass;
    print $a::class;

### Como usar classes internas ou globais em um namespace?

Exemplo #3 Acessando classes internas em namespaces

    <?php
    namespace foo;
    $a = new \stdClass;
    print $a::class;

    function test(?\ArrayObject $parameter_type_example = null) {}

    $a = \FilesystemIterator::CURRENT_AS_FILEINFO;
    print $a . "\n";

    // estendendo uma classe interna ou global
    class MinhaExcecao extends \Exception {}
    print MinhaExcecao::class . "\n";

### Como usar classes, funções ou constantes de namespace em seu próprio namespace?

Exemplo #4 Acessando classes, funções ou constantes internas em namespaces

    <?php
    namespace foo;

    class MinhaClasse {}

    // usando uma classe do namespace atual como tipo de parâmetro
    function test(?MinhaClasse $exemplo_com_tipo_de_parametro = null) {}
    // outra forma de usar a classe do namespace atual como tipo de parâmetro
    function test(?\foo\MinhaClasse $exemplo_com_tipo_de_parametro = null) {}

    // estendendo uma classe do namespace atual
    class Estendida extends MinhaClasse {}
    print Estendida::class . "\n";

    // acessando uma função global
    $a = \strlen("teste");
    print $a . "\n";

    // acessando uma constante global
    $b = \INI_ALL;
    print $b . "\n";

### Como nomes como `\meu\nome` ou `\nome` são resolvidos?

Nomes que começam com uma barra invertida (`\`) sempre são resolvidos para seu conteúdo exato, então `\meu\nome` é o mesmo que `meu\nome` e `\Exception` é o mesmo que `Exception`.

Exemplo #5 Nomes totalmente qualificados

    <?php
    namespace foo;
    $a = new \meu\nome(); // instancia um objeto da classe "meu\nome"
    echo \strlen('olá'); // invoca a função "strlen"
    $a = \INI_ALL; // define $a com o valor da constante "INI_ALL"

### Como um nome como `meu\nome` é resolvido?

Nomes que contêm barra invertida, mas não começam com uma barra invertida, como `meu\nome` podem ser resolvidos de duas maneiras diferentes.

Se houver uma instrução de importação que cria o apelido `meu` para outro nome, então o apelido da importação será aplicado ao `meu` em `meu\nome`.

Caso contrário, o nome do namespace atual será prefixado a `meu\nome`.

Exemplo #6 Nomes qualificados

    <?php
    namespace foo;
    use bla\bla as foo;

    $a = new meu\nome(); // instancia um objeto da classe "foo\meu\nome"
    foo\bar::nome(); // chama o método estático "nome" na classe "bla\bla\bar"
    minha\bar(); // chama a função "foo\minha\bar"
    $a = minha\BAR; // define $a com o valor da constante "foo\minha\BAR"

### Como um nome de classe não qualificado como `nome` é resolvido?

Nomes de classes que não contêm barra invertida como `nome` podem ser resolvidos de duas maneiras diferentes.

Se houver uma instrução de importação que cria o apelido `nome` para outro nome, então o apelido da importação será aplicado.

Caso contrário, o nome do namespace atual será prefixado a `nome`.

Exemplo #7 Nomes de classe não qualificados

    <?php
    namespace foo;
    use bla\bla as foo;

    $a = new nome(); // instancia um objeto da classe "foo\nome"
    foo::nome(); // chama o método estático "nome" na classe "bla\bla"

### Como um nome de função não qualificado ou nome de constante não qualificado como `nome` é resolvido?

Nomes de funções ou constantes que não contêm barra invertida como `nome` podem ser resolvidos de duas maneiras diferentes.

Primeiro, o nome do namespace atual será prefixado a `nome`.

Finalmente, se a constante ou função `nome` não existir no namespace atual, uma constante ou função global `nome` será usada se existir.

Exemplo #8 Nomes de funções ou constantes não qualificados

    <?php
    namespace foo;
    use bla\bla as foo;

    const FOO = 1;

    function minha() {
        print __FUNCTION__ . "\n";
    }
    function foo() {
        print __FUNCTION__ . "\n";
    }
    function sort(&$a)
    {
        \sort($a); // chama a função global "sort"
        $a = array_flip($a);
        return $a;
    }

    minha(); // chama "foo\minha"
    print strlen('olá') . "\n"; // chama a função global "strlen" porque não existe "foo\strlen"
    $arr = array(1,3,2);
    $b = sort($arr); // chama a função "foo\sort"
    var_dump($b);
    foo(); // chama a função "foo\foo" - a importação não é aplicada

    $a = FOO; // define $a com o valor da constante "foo\FOO" - a importação não é aplicada
    print $a;
    $b = INI_ALL; // define $b com o valor da constante global "INI_ALL"
    print $b;

### Nomes de importação não devem entrar em conflito com classes definidas no mesmo arquivo

As seguintes combinações de script são válidas:

arquivo1.php

    <?php
    namespace minha\coisa;
    class MinhaClasse {}

outra.php

    <?php
    namespace outra;
    class coisa {}

arquivo2.php

    <?php
    namespace minha\coisa;
    include 'arquivo1.php';
    include 'outra.php';

    use outra\coisa as MinhaClasse;
    $a = new MinhaClasse; // instancia um objeto da classe coisa do namespace outra

Não há conflito de nomes, mesmo que a classe `MinhaClasse` exista dentro do namespace `minha\coisa`, porque a definição de MinhaClasse está em um arquivo separado. No entanto, o próximo exemplo causa um erro fatal de conflito de nomes porque MinhaClasse está definida no mesmo arquivo que a declaração use.

    <?php
    namespace minha\coisa;
    use outra\coisa as MinhaClasse;
    class MinhaClasse {} // erro fatal: MinhaClasse está em conflito com a declaração de importação
    $a = new MinhaClasse;

### Namespaces aninhados não são permitidos

O PHP não permite aninhar namespaces.

    <?php
    namespace minha\coisa {
        namespace aninhada {
            class foo {}
        }
    }

No entanto, é fácil simular namespaces aninhados da seguinte forma:

    <?php
    namespace minha\coisa\aninhada {
        class foo {}
    }

### Nomes de namespace dinâmicos (identificadores entre aspas) devem escapar a barra invertida

É muito importante perceber que, como a barra invertida é usada como um caractere de escape dentro de strings, ela sempre deve ser duplicada quando usada em uma string. Caso contrário, existe o risco de consequências não desejadas:

Exemplo #9 Perigos do uso de nomes com namespace em uma string com aspas duplas

    <?php
    $a = "\nome\perigoso"; // \n é uma nova linha dentro de strings com aspas duplas!
    $obj = new $a;

    $a = 'nada\perigoso'; // não há problemas aqui.
    $obj = new $a;

Dentro de uma string com aspas simples, a sequência de escape da barra invertida é muito mais segura de usar, mas ainda é uma prática recomendada escapar as barras invertidas em todas as strings.

### Constantes indefinidas referenciadas usando qualquer barra invertida geram erro fatal

Qualquer constante indefinida não qualificada como `FOO` gerará um alerta explicando que o PHP assumiu que `FOO` era o valor da constante. Qualquer constante, qualificada ou totalmente qualificada, que contenha uma barra invertida produzirá um erro fatal se não for encontrada.

Exemplo #10 Constantes não definidas

    <?php
    namespace bar;
    $a = FOO; // Produz um alerta - constante indefinida FOO assumiu "FOO"
    $a = \FOO; // Erro fatal, constante de namespace indefinida FOO
    $a = Bar\FOO; // Erro fatal, constante de namespace indefinida bar\Bar\FOO
    $a = \Bar\FOO; // Erro fatal, constante de namespace indefinida Bar\FOO

### Não é possível substituir as constantes especiais `null`, `true` ou `false`

Qualquer tentativa de definir uma constante de namespace que seja uma constante especial nativa resultará em um erro fatal.

Exemplo #11 Constantes não definidas

    <?php
    namespace bar;
    const NULL = 0; // Erro fatal
    const true = 'verdadeiro'; // Também um erro fatal
    // etc.

# Enumerações

## Índice

- Visão Geral das Enumerações
- Enumerações Básicas
- Enumerações Apoiadas
- Métodos de enumerações
- Métodos estáticos de enumerações
- Constantes de enumeração
- Traits
- Valores de enumeração em expressões constantes
- Diferenças de objetos
- Listagem de valores
- Serialização
- Porque enumerações não são extensíveis
- Exemplos

## Visão Geral das Enumerações

(PHP 8 >= 8.1.0)

Enumerações, ou "Enums", permitem que um desenvolvedor defina um tipo personalizado que está limitado a um número discreto de valores possíveis. Isso pode ser especialmente útil ao definir um modelo de domínio, pois permite "tornar estados inválidos irrepresentáveis."

Enumerações aparecem em muitas linguagens com uma variedade de recursos diferentes. No PHP, Enumerações são um tipo especial de objeto. A enumeração em si é uma classe, e seus possíveis casos são todos objetos de instância única dessa classe. Isso significa que casos de enumeração são objetos válidos e podem ser usados em qualquer lugar em que um objeto pode ser usado, incluindo verificações de tipo.

O exemplo mais popular de enumerações é o tipo embutido booleano, que é um tipo enumerado com valores válidos `true` e `false`. Enumerações permitem que os desenvolvedores definam suas próprias enumerações robustas.

## Enumerações Básicas

Enumerações são similares às classes e compartilham o mesmo namespaces que classes, interfaces, e traits. Elas também podem ser carregadas automaticamente da mesma maneira. Uma Enumeração define um novo tipo, que possui um número fixo e limitado de valores legais possíveis.

    <?php

    enum Naipe
    {
        case Copas;
        case Ouros;
        case Paus;
        case Espadas;
    }

Essa declaração cria um novo tipo enumerado chamado `Naipe`, que possui quatro e apenas quatro valores permitidos: `Naipe::Copas`, `Naipe::Ouros`, `Naipe::Paus`, e `Naipe::Espadas`. Variáveis podem ser atribuídas a um desses valores permitidos. Uma função pode ser tipada contra um tipo enumerado, caso em que apenas os valores desse tipo podem ser passados.

    <?php

    enum Naipe
    {
        case Copas;
        case Ouros;
        case Paus;
        case Espadas;
    }

    function pegar_uma_carta(Naipe $naipe)
    {
        var_dump($naipe);
    }

    $val = Naipe::Ouros;

    // OK
    pegar_uma_carta($val);

    // OK
    pegar_uma_carta(Naipe::Paus);

    // TypeError: pegar_uma_carta(): Argument #1 ($naipe) must be of type Naipe, string given
    pegar_uma_carta('Espadas');

Uma enumeração pode ter zero ou mais definições `case`, sem limite máximo. Uma enumeração sem nenhum caso é sintaticamente válida, embora inútil.

Os nomes dos casos seguem as mesmas regras de sintaxe de qualquer nome do PHP, mais detalhados na seção sobre Constantes.

Por padrão, os casos não são internamente associados por um valor escalar. Ou seja, `Naipe::Copas` não é igual a `"0"`. Ao invés disso, cada caso é apoiado por um objeto único com esse nome. Isso significa que:

    <?php

    enum Naipe
    {
        case Copas;
        case Ouros;
        case Paus;
        case Espadas;
    }

    $a = Naipe::Espadas;
    $b = Naipe::Espadas;

    if ($a === $b) {
        print "Naipes correspondem usando ===\n";
    }

    if ($a instanceof Suit) {
        print "Naipes correspondem instanceof\n";
    }

    if ($a !== 'Spades') {
        print "O naipe não corresponde à string\n";
    }

Isso também significa que os valores de enumeração nunca são `<` ou `>` do que o outro, uma vez que essas comparações não fazem sentido em objetos. Essas comparações sempre retornarão `false` ao trabalhar com valores de enumeração.

Esse tipo de caso, sem dados relacionados, é chamado de "Caso Puro". Uma enumeração que contém apenas Casos Puros é chamada de Enumeração Pura.

Todos os Casos Puros são implementados como instâncias de seus tipos 'enum'. O tipo 'enum' é representado internamente como uma classe.

Todos os Casos têm uma propriedade somente leitura, `name`, que é o nome (sensível a maiúsculas e minúsculas) do próprio caso.

    <?php

    enum Naipe
    {
        case Copas;
        case Ouros;
        case Paus;
        case Espadas;
    }

    print Naipe::Espadas->name;
    // exibe "Espadas"

É possível também utilizar as funções defined() e constant() para verificar a existência ou ler um item de enumeração se o nome for obtido dinamicamente. Isto é desencorajado, já que utilizar Enumerações Apoiadas funciona para a maioria dos casos.

## Enumerações Apoiadas

Por padrão, os Casos não possuem um equivalente escalar. Eles são apenas objetos singleton. No entanto, existem muitos casos em que um Caso Enumerado precisa ser capaz de fazer fazer uma conversão de ida e volta para um banco de dados ou um armazenamento de dados semelhante, então ter um escalar embutido (e, portanto, trivialmente serializável) equivalente definido intrinsecamente é útil.

Para definir um equivalente escalar para uma Enumeração, a sintaxe é a seguinte:

    <?php

    enum Naipe: string
    {
        case Copas = 'C';
        case Ouros = 'O';
        case Paus = 'P';
        case Espadas = 'E';
    }

Um caso que possui um equivalente escalar é chamado de Caso Apoiado, sendo "Apoiado" no sentido de lastreado, suportado, por um valor mais simples. Uma enumeração que possui todos Casos Apoiados é chamada Enumeração Apoiada. Uma Enumeração Apoiada pode conter apenas Casos Apoiados. Uma Enumeração Pura pode conter apenas Casos Puros.

Uma Enumeração Apoiada pode associar valores de tipos `int` ou `string`, e uma determinada enumeração suporta apenas um único tipo de cada vez (isto é, sem união de `int|string`). Se uma enumeração for marcada como tendo um equivalente escalar, então todos os casos devem possuir um escalar equivalente único definido explicitamente. Não existem equivalentes escalares gerados automaticamente (p. ex.: inteiros sequenciais). Casos apoiados devem ser únicos; dois casos apoiados não podem ter o mesmo equivalente escalar. No entanto, uma constante pode se referir a um caso, efetivamente criando um apelido. Veja as constantes de enumeração.

Valores equivalentes podem ser uma expressão escalar constante. Antes do PHP 8.2.0, os valores equivalentes deveriam ser literais ou expressões literais. Isto significa que constantes e expressões constantes não eram suportadas. Isto é, `1 + 1` era permitido, mas `1 + SOME_CONST` não era.

Casos Apoiados possuem uma propriedade somente leitura adicional, `value`, que é o valor especificado na definição.

    <?php

    enum Naipe: string
    {
        case Copas = 'C';
        case Ouros = 'O';
        case Paus = 'P';
        case Espadas = 'E';
    }

    print Naipe::Paus->value;
    // Exibe "P"

Para impor a propriedade `value` como somente leitura, uma variável não pode ser atribuída como uma referência para ela. Isto é, o seguinte lança um erro:

    <?php

    enum Naipe: string
    {
        case Copas = 'C';
        case Ouros = 'O';
        case Paus = 'P';
        case Espadas = 'E';
    }

    $naipe = Naipe::Paus;
    $ref = &$naipe->value;
    // Erro fatal: Não é possível modificar indiretamente a propriedade somente-leitura Naipe::$value

Enumerações Apoiadas implementam uma interface interna BackedEnum, que expõe dois métodos adicionais:

- `from(int|string): self` recebe um escalar e retornará o caso correspondente da enumeração. Se não for encontrado, ela lançará um ValueError. Isso é útil principalmente nas situações somente valores previstos são permitidos e um valor de enumeração ausente deve ser considerado um erro de interrupção de aplicação.
- `tryFrom(int|string): ?self` recebe uma escalar e retornará o caso de enumeração correspondente. Se um não for encontrado, ela retornará `null`. Isso é útil principalmente em casos onde o escalar de entrada não é confiável e o chamador quer implementar sua própria lógica de manipulação de erros ou de valor padrão.

Os métodos `from()` e `tryFrom()` seguem as regras padrão de tipagem fraca/forte. No modo de tipagem fraca, passar um inteiro ou string é aceitável e o sistema irá coagir o valor de acordo. Passar um float também irá funcionar e será convertido. No modo de tipagem estrita, passar um inteiro para `from()` em uma enumeração associada a strings (ou vice-versa) irá resultar em um TypeError, assim como um float irá lançar um erro em todas as circunstâncias. Todos os outros tipos de parâmetro lançarão um TypeError em ambos os modos.

    <?php

    enum Naipe: string
    {
        case Copas = 'C';
        case Ouros = 'O';
        case Paus = 'P';
        case Espadas = 'E';
    }

    function obter_dados_do_banco($id) {
        return [
            'naipe' => 'E',
        ];
    }

    $registro = obter_dados_do_banco(42);
    print $registro['naipe'] . "\n";

    $naipe = Naipe::tryFrom('A') ?? Naipe::Espadas;
    // Dados inválidos retornam null, então Naipe::Espadas em seu lugar.
    print $naipe->value . "\n";

    $naipe =  Naipe::from('X');
    // Dados inválidos lançam um ValueError: "X" não é um valor escalar de apoio válido para a enumeração Naipe
    print $naipe->value . "\n";

Definir manualmente um método `from()` ou `tryFrom()` em uma Enumeração Apoiada irá resultar em um erro fatal.

## Métodos de enumerações

Enumerações (tanto Puras quanto Apoiadas) podem conter métodos e podem implementar interfaces. Se uma enumeração implementa uma interface, qualquer verificação de tipo para aquela interface também aceitará todos os casos daquela enumeração.

    <?php

    interface Colorido
    {
        public function cor(): string;
    }

    enum Naipe implements Colorido
    {
        case Copas;
        case Ouros;
        case Paus;
        case Espadas;

        // Cumpre o contrato da interface.
        public function cor(): string
        {
            return match ($this) {
                Naipe::Copas, Naipe::Ouros => 'Vermelho',
                Naipe::Paus, Naipe::Espadas => 'Preto',
            };
        }

        // Não faz parte de uma interface; tudo bem.
        public function forma(): string
        {
            return "Retângulo";
        }
    }

    function pintar(Colorido $c)
    {
       print $c->cor() . "\n";
    }

    pintar(Naipe::Paus);  // Funciona

    print Naipe::Ouros->forma(); // imprime "Retângulo"

Nesse exemplo, todas as quatro instâncias de `Naipe` possuem dois métodos, `cor()` e `forma()`. Até onde o código chamador e as checagens de tipo sabem, elas se comportam exatamente da mesma forma que qualquer outra instância de objeto.

Em uma Enumeração Apoiada, a declaração de interface vai após a declaração do tipo de lastro.

    <?php

    interface Colorido
    {
        public function cor(): string;
    }

    enum Naipe: string implements Colorido
    {
        case Copas = 'C';
        case Ouros = 'O';
        case Paus = 'P';
        case Espadas = 'E';

        // Cumpre o contrato da interface.
        public function cor(): string
        {
            return match ($this) {
                Naipe::Copas, Naipe::Ouros => 'Vermelho',
                Naipe::Paus, Naipe::Espadas => 'Preto',
            };
        }
    }

Dentro de um método, a variável `$this` é definida e se refere à instância do Caso.

Métodos podem ser arbitrariamente complexos, mas na prática geralmente retornam um valor estático ou match no `$this` para fornecer resultados diferentes para casos diferentes.

Note que nesse caso, uma prática melhor de modelagem de dados seria definir também um Tipo 'enum' `CorDeNaipe` com valores Preto e Vermelho e retornar isso no seu lugar. No entanto, isso complicaria esse exemplo.

A hierarquia acima é logicamente similar a seguinte estrutura de classes (embora esse não seja o código real que é executado):

    <?php

    interface Colorido
    {
        public function cor(): string;
    }

    final class Naipe implements UnitEnum, Colorido
    {
        public const Copas = new self('Copas');
        public const Ouros = new self('Ouros');
        public const Paus = new self('Paus');
        public const Espadas = new self('Espadas');

        private function __construct(public readonly string $nome) {}

        public function cor(): string
        {
            return match ($this) {
                Naipe::Copas, Naipe::Ouros => 'Vermelho',
                Naipe::Paus, Naipe::Espadas => 'Preto',
            };
        }

        public function forma(): string
        {
            return "Retângulo";
        }

        public static function cases(): array
        {
            // Método ilegal, porque definir manualmente um método cases() em uma enumeração não é permitido.
            // Veja também a seção "Listagem de valores".
        }
    }

Métodos podem ser públicos, privados ou protegidos, apesar dos privados e protegidos serem equivalentes na prática, pois herança não é permitida.

## Métodos estáticos de enumerações

Enumerações também podem ter métodos estáticos. O uso para métodos estáticos na própria enumeração é primariamente para construtores alternativos. Por exemplo:

    <?php

    enum Tamanho
    {
        case Pequeno;
        case Medio;
        case Grande;

        public static function deComprimento(int $cm): self
        {
            return match (true) {
                $cm < 50 => self::Pequeno,
                $cm < 100 => self::Medio,
                default => self::Grande,
            };
        }
    }

    var_dump(Tamanho::fromLength(50));

Métodos estáticos podem ser públicos, privados ou protegidos apesar dos privados e protegidos serem equivalentes na prática, pois herança não é permitida.

## Constantes de enumeração

Enumerações podem incluir constantes, que podem ser públicas, privadas ou protegidas, apesar das privadas e protegidas serem equivalentes na prática, pois herança não é permitida.

Uma constante de enumeração pode se referir a um caso de enumeração:

    <?php

    enum Tamanho
    {
        case Pequeno;
        case Medio;
        case Grande;

        public const Enorme = self::Grande;
    }

    var_dump(Tamanho::Enorme);

## Traits

Enumerações podem utilizar Traits, que se comportam da mesma maneira que nas classes. A limitação é que usados com `use` em uma enumeração não podem conter propriedades. Eles podem incluir apenas métodos, métodos estáticos e constantes. Um Trait com propriedades resultará em um erro fatal.

    <?php

    interface Colorido
    {
        public function cor(): string;
    }

    trait Retangulo
    {
        public function forma(): string
        {
            return "Retângulo";
        }
    }

    enum Naipe implements Colorido
    {
        use Retangulo;

        case Copas;
        case Ouros;
        case Paus;
        case Espadas;

        public function cor(): string
        {
            return match ($this) {
                Naipe::Copas, Naipe::Ouros => 'Vermelho',
                Naipe::Paus, Naipe::Espadas => 'Preto',
            };
        }
    }

    $naipe = Naipe::Espadas;
    var_dump($naipe->cor());
    var_dump($naipe->forma());

## Valores de enumeração em expressões constantes

Como os casos são representados como constantes na própria enumeração, eles podem ser usados como valores estáticos na maioria das expressões constantes: padrões de propriedades, padrões de variáveis estáticas, padrões de parâmetros, valores constantes globais e de classes. Eles não podem ser usados em outros valores de caso de enumeração, mas constantes normais podem se referir a um caso.

No entanto, chamadas implícitas de métodos mágicos como ArrayAccess em enumerações não são permitidas em definições estáticas ou de constantes já que não podemos garantir absolutamente que o valor resultante é determinístico ou que a invocação do método é livre de efeitos colaterais. Chamadas de funções, chamadas de métodos e acesso às propriedades continuam a ser operações inválidas em expressões constantes.

    <?php

    // Esta é uma definição de enumeração perfeitamente legal.
    enum Direcao implements ArrayAccess
    {
        case Cima;
        case Baixo;

        public function offsetExists($offset): bool
        {
            return false;
        }

        public function offsetGet($offset): mixed
        {
            return null;
        }

        public function offsetSet($offset, $value): void
        {
            throw new Exception();
        }

        public function offsetUnset($offset): void
        {
            throw new Exception();
        }
    }

    class Foo
    {
        // Isto é permitido.
        const BAIXO = Direcao::Baixo;

        // Isto não é permitido, pois pode não ser determinístico.
        const CIMA = Direcao::Cima['curta'];
        // Fatal error: Cannot use [] on enums in constant expression
    }

    // Isto é perfeitamente legal, porque não é uma expressão constante.
    $x = Direcao::Cima['curta'];
    var_dump("\$x é " . var_export($x, true));

    $foo = new Foo();

## Diferenças de objetos

Apesar de enumerações serem construídas sobre classes e objetos, elas não suportam todas as funcionalidades relacionadas a objetos. Em particular, casos de enumeração são proibidos de ter estado.

- Construtores e Destrutores são proibidos.
- Herança não é suportada. Enumerações não podem estender ou ser estendidas.
- Propriedades estáticas ou de objeto não são permitidas.
- Clonar um caso de enumeração não é suportado, pois os casos devem ser instâncias únicas.
- Métodos mágicos, exceto para aqueles listados abaixo, não são permitidos.
- Enumerações sempre precisam ser declaradas antes de serem utilizadas.

As seguintes funcionalidades de objeto estão disponíveis, e se comportam exatamente como em qualquer outro objeto:

- Métodos públicos, privados e protegidos.
- Métodos estáticos públicos, privados e protegidos.
- Constantes públicas, privadas e protegidas.
- Enumerações podem implementar qualquer número de interfaces.
- Enumerações e casos podem ter atributos anexados a eles. O filtro de alvo `TARGET_CLASS` inclui as próprias enumerações. O filtro de alvo `TARGET_CLASS_CONST` inclui Casos de Enumeração.
- Os métodos mágicos __call, __callStatic, e __invoke
- Constantes `__CLASS__` e `__FUNCTION__` se comportam normalmente

A constante mágica `::class` em um tipo 'enum' avalia ao nome do tipo incluindo qualquer namespace, exatamente o mesmo que um objeto. A constante mágica `::class` em uma instância de Caso também avalia para o tipo 'enum', pois ele é uma instância daquele tipo.

Adicionalmente, casos não podem ser instanciados diretamente com `new`, nem com ReflectionClass::newInstanceWithoutConstructor() em reflexão. Ambos resultarão em um erro.

    <?php

    $trevos = new Naipe();
    // Erro: Não é possível instanciar a enumeração Naipe

    $ferraduras = (new ReflectionClass(Naipe::class))->newInstanceWithoutConstructor()
    // Erro: Não é possível instanciar a enumeração Naipe

## Listagem de valores

Tanto Enumerações Puras quanto Enumerações Apoiadas implementam uma interface interna chamada UnitEnum. `UnitEnum` inclui um método estático `cases()`. `cases()` retorna um array embalado com todos os Casos definidos na ordem de declaração.

    <?php

    enum Naipe
    {
        case Copas;
        case Ouros;
        case Paus;
        case Espadas;
    }

    var_dump(Naipe::cases());

    enum NaipeApoiado: string
    {
        case Copas = 'C';
        case Ouros = 'O';
        case Paus = 'P';
        case Espadas = 'E';
    }

    var_dump(NaipeApoiado::cases());

Definir manualmente um método `cases()` em uma enumeração resultará em um erro fatal.

## Serialização

As enumerações são serializadas de maneira diferente dos objetos. Especificamente, elas têm um novo código de serialização, `"E"`, que especifica o nome do caso de enumeração. A rotina de desserialização pode então usar isso para definir uma variável para o valor singleton existente. Isso garante que:

    <?php

    enum Naipe: string
    {
        case Copas = 'C';
        case Ouros = 'O';
        case Paus = 'P';
        case Espadas = 'E';
    }

    Naipe::Copas === unserialize(serialize(Naipe::Copas));

    print serialize(Naipe::Copas);
    // E:11:"Naipe:Copas";

Na desserialização, se uma enumeração de um caso não pode ser encontrada para combinar com um valor serializado, um aviso será emitido e `false` retornado.

A opção `allowed_classes` de unserialize() não afeta Enumerações.

Se uma Enumeração Pura for serializada para JSON, um erro será lançado. Se uma Enumeração Apoiada for serializada para JSON, ela será representada apenas por seu valor escalar, no tipo apropriado. O comportamento de ambas pode ser sobrescrito ao implementar JsonSerializable.

Para print_r(), a saída de um caso de enumeração é ligeiramente diferente dos objetos para minimizar confusões.

    <?php

    enum Foo
    {
        case Bar;
    }

    enum Baz: int
    {
        case Beep = 5;
    }

    print_r(Foo::Bar);
    print_r(Baz::Beep);

    /* Produz

    Foo Enum (
        [name] => Bar
    )
    Baz Enum:int {
        [name] => Beep
        [value] => 5
    }
    */

## Porque enumerações não são extensíveis

Classes possuem contratos em seus métodos:

    <?php

    class A {}
    class B extends A {}

    function foo(A $a) {}

    function bar(B $b)
    {
        foo($b);
    }

Esse código é correto para tipos, pois B segue o contrato de A, e através da co e contra variância, quaisquer expectativas a respeito dos métodos será atendida.

Enumerações possuem contratos em seus itens, não em seus métodos:

    <?php

    enum ErrorCode
    {
        case SOMETHING_BROKE;
    }

    function quux(ErrorCode $errorCode)
    {
        // Nesse primeiro momento, esse código prevê todos os casos
        match ($errorCode) {
            ErrorCode::SOMETHING_BROKE => true,
        };
    }

A instrução match na função `quux` pode ser analisada estaticamente para verificar se cobre todos os casos possíveis em ErrorCode.

Mas imagine que seja possível estender enumerações, assim:

    <?php

    // Apenas para o exemplo onde enumerações não são finais.
    // Isto *não* funciona no PHP.
    enum MoreErrorCode extends ErrorCode
    {
        case PEBKAC;
    }

    function fot(MoreErrorCode $errorCode)
    {
        quux($errorCode);
    }

    fot(MoreErrorCode::PEBKAC);

Em condições normais de herança, uma classe que estende outra passará na checagem de tipos.

O problema ocorreria na instrução match da função `quux()` que agora não cobre todos os casos. Porque a função não prevê o item `MoreErrorCode::PEBKAC` o match irá falhar com uma exceção.

Por conta disso, as enumerações são finais e não podem ser estendidas.

## Exemplos

Exemplo #1 Valores limitados básicos

    <?php

    enum Ordem
    {
        case Asc;
        case Desc;
    }

    function consulta($campos, $filtros, Ordem $ordem = Ordem::Asc)
    {
         /* ... */
    }

A função `consulta()` agora pode prosseguir segura, sabendo que a `$ordem` tem garantia de ser `Ordem::Asc` ou `Ordem::Desc`. Qualquer outro valor resultaria em um TypeError, então nenhuma verificação ou teste de erro é necessária.

Exemplo #2 Valores exclusivos avançados

    <?php

    enum EstadoDeUsuario: string
    {
        case Pendente = 'P';
        case Ativo = 'A';
        case Suspenso = 'S';
        case CanceladoPeloUsuario = 'C';

        public function rotulo(): string
        {
            return match ($this) {
                self::Pendente => 'Pendente',
                self::Ativo => 'Ativo',
                self::Suspenso => 'Suspenso',
                self::CanceladoPeloUsuario => 'Cancelado pelo usuário',
            };
        }
    }

    $status = EstadoDeUsuario::Suspenso;
    var_dump($status->rotulo());

Neste exemplo, o estado de um usuário pode ser, exclusivamente, `EstadoDeUsuario::Pendente`, `EstadoDeUsuario::Ativo`, `EstadoDeUsuario::Suspenso`, ou `EstadoDeUsuario::CanceladoPeloUsuario`. Uma função pode tipar um parâmetro contra `EstadoDeUsuario` e aceitar então apenas aqueles quatro valores, ponto final.

Todos os quatros valores possuem um método `rotulo()`, que retorna uma string legível para humanos. Essa string é independente da string equivalente escalar do "nome de máquina", que pode ser usado em, por exemplo, um campo de banco de dados um uma caixa de seleção HTML.

    <?php

    enum EstadoDeUsuario: string
    {
        case Pendente = 'P';
        case Ativo = 'A';
        case Suspenso = 'S';
        case CanceladoPeloUsuario = 'C';

        public function rotulo(): string
        {
            return match($this) {
                self::Pendente => 'Pendente',
                self::Ativo => 'Ativo',
                self::Suspenso => 'Suspenso',
                self::CanceladoPeloUsuario => 'Cancelado pelo usuário',
            };
        }
    }

    foreach (EstadoDeUsuario::cases() as $caso) {
        printf(
            "<option value=\"%s\">%s</option>\n",
            htmlentities($caso->value),
            htmlentities($caso->rotulo())
        );
    }

# Erros

## Índice

- Básico
- Erros no PHP 7

## Introdução

Infelizmente, não importa quão cuidadosos somos escrevendo nossos códigos, erros são fatos da vida. O PHP reportará erros, advertências e avisos para muitos problemas comuns de codificação e problemas em tempo de execução, e saber como detectar e lidar com estes erros farão o processo de depuração muito mais fácil.

## Básico

O PHP retornará erros em resposta a inúmeras condições de erros internos. Eles podem ser utilizados para sinalizar inúmeras condições diferentes e podem ser exibidos e/ou registrados conforme a necessidade.

Cada erro que o PHP gera inclui um tipo. A lista destes tipos de erros está disponível, junto a uma breve descrição de seu comportamento e como podem ser causados.

### Manuseando erros com o PHP

Se nenhum manipulador de erro for definido, o PHP tratará todos os que ocorrerem de acordo com sua configuração. Quais erros são reportados, e quais são ignorados é controlado pela diretiva `error_reporting` no php.ini, ou em tempo de execução, chamando a função error_reporting(). É altamente recomendável que esta diretiva de configuração seja definida, entretanto, alguns erros podem ocorrer antes da execução do script começar.

Em um ambiente de desenvolvimento, deve-se sempre definir a diretiva `error_reporting` para `E_ALL`, para estar ciente, e corrigir, problemas informados pelo PHP. Em produção, deve-se definir para um nível menos verboso, como `E_ALL & ~E_NOTICE & ~E_DEPRECATED`, mas em muitos casos `E_ALL` também é apropriado, pois pode antecipar avisos de problemas em potencial.

O que o PHP faz com estes erros depende de mais duas diretivas no php.ini. A diretiva `display_errors` controla se o erro será mostrado como parte da saída do script. Esta diretiva deve sempre estar desativada no ambiente de produção, já que pode incluir informações confidenciais como senhas do banco de dados, mas é útil habilitá-la em desenvolvimento, já que garante o reporte imediato de problemas.

Além de mostrar os erros, o PHP pode logar erros quando a diretiva `log_errors` estiver habilitada. Isso logará qualquer erro para um arquivo ou para o syslog definido com a diretiva `error_log`. Pode ser extremamente útil no ambiente de produção, já que pode-se logar os erros que ocorrerem e então gerar relatórios baseados nestes erros.

### Manipuladores de erros personalizados

Se o manipulador de erros padrão do PHP for inadequado, pode-se manipular diversos tipos de erro com manipuladores de erros próprios ao instalá-los com a função set_error_handler(). Embora alguns tipos de erros não possam ser manipulados desta maneira, aqueles que puderem, serão manipulados da forma que o script decidir: por exemplo, pode ser utilizado para exibir uma página de erro customizada ao usuário e reportar mais precisamente que por log, como enviando um e-mail.

## Erros no PHP 7

O PHP 7 modificou como a maioria dos erros são reportados pelo PHP. Em vez de reportá-los através do mecanismo tradicional de reporte de erros utilizado pelo PHP 5, a maioria dos erros, agora são reportados lançando exceções Error

Assim como exceções normais, as exceções Error serão elevadas até alcançarem o primeiro bloco `catch` correspondente. Se não existir nenhum bloco correspondente, qualquer manipulador de exceção padrão instalado com a função set_exception_handler() será chamado, e se não existir nenhum manipulador padrão de exceção, a exceção será convertida em um erro fatal e será tratada como um erro tradicional.

Já que a hierarquia de Error não herda de Exception, códigos que utilizam blocos `catch (Exception $e) { ... }` para manipular exceções que não foram capturadas no PHP 5, descobrirão que esses Errors não são capturados por estes blocos. Um bloco `catch (Error $e) { ... }`, ou um manipulador definido com a função set_exception_handler() será necessário.

### Hierarquia de Error

- Throwable
  - Error
    - ArithmeticError
      - DivisionByZeroError
    - AssertionError
    - CompileError
      - ParseError
    - TypeError
      - ArgumentCountError
    - ValueError
    - UnhandledMatchError
    - FiberError
    - RequestParseBodyException
  - Exception
    - ...

# Exceções

## Índice

- Estendendo exceções

> Nota: Consulte também a classe Exception

O PHP possui um modelo de exceções similar ao de outras linguagens de programação. Uma exceção pode ser lançada (`throw`) e capturada (`catch`). Código pode ser envolvido por um bloco `try` para facilitar a captura de exceções potenciais. Cada bloco `try` precisa ter ao menos um bloco `catch` ou `finally` correspondente.

Se uma exceção é lançada e o escopo atual não possui nenhum block `catch`, a exceção irá "desempilhar" o call stack pelas funções chamadoras até encontrar um bloco `catch` compatível. Todos os blocos `finally` encontrados pelo caminho serão executados. Se a pilha é esvaziada até o escopo global sem encontrar um block `catch` compatível, o programa irá terminar com um erro fatal a não ser que um manipulador global de exceções tenha sido configurado.

O objeto lançado precisa ser uma `instanceof` Throwable. Tentar lançar um objeto sem essa ascendência resultará em um erro fatal.

A partir do PHP 8.0.0, a palavra chave `throw` é uma expressão e pode ser utilizada em qualquer contexto de expressão. Em versões anteriores era considerado uma instrução e portanto precisava constar em sua própria linha.

## `catch`

Um bloco `catch` define como o código responde a uma exceção lançada. Um bloco `catch` define um ou mais tipos de exceções ou erros que ele pode processar, e opcionalmente uma variável para receber a exceção lançada. (A variável era requerida anteriormente ao PHP 8.0.0.) O primeiro bloco `catch` que uma exceção ou erro lançados encontram que seja compatível com o tipo objeto lançado irá processar esse objeto.

Múltiplos blocos `catch` podem ser utilizados para capturar exceções diferentes. A execução normal (quando nenhuma exceção é lançada dentro de um `try`) irão continuar a execução após o último `catch` definido em sequência. Exceções podem ser lançadas ou relançadas (`throw`) dentro um bloco `catch`. Caso contrário, a execução irá continuar após o bloco `catch` que foi acionado.

Quando uma exceção é lançada o código seguinte não é executado, e o PHP tentará encontrar o primeiro bloco `catch` coincidente. Se uma exceção não for capturada, um erro PHP fatal será lançado com a mensagem "`Uncaught Exception ...`" na ausência de uma função definida com set_exception_handler().

A partir do PHP 7.1 um bloco `catch` pode especificar múltiplas exceções usando o caractere pipe (`|`). Isto é útil quando diferentes exceções de diferentes hierarquias de classes são tratadas da mesma forma.

A partir do PHP 8.0.0, o nome de variável que captura a exceção é opcional. Se não especificada, o bloco `catch` compatível ainda executará, mas não terá acesso ao objeto lançado.

## `finally`

Um bloco `finally` pode ser especificado após ou no lugar de blocos `catch`. Códigos dentro de `finally` sempre serão executados depois do `try` ou `catch`, independente se houve o lançamento de uma exceção, e antes que a execução normal continue.

Uma interação notável ocorre entre um bloco `finally` e a instrução `return`. Se uma instrução `return` é encontrada dentro um bloco `try` ou `catch`, o bloco `finally` ainda assim será executado. Além disso, a instrução `return` é avaliada no ponto que é encontrada, mas o resultado só será retornado após o bloco `finally` ser executado. Se o bloco `finally` também tiver uma instrução `return`, o valor da instrução de `finally` que será retornado.

Outra interação notável é entre uma exceção lançada de dentro de um bloco `try` e uma lançada de dentro de um bloco `finally`. Se ambos os blocos lançarem uma exceção, a que for lançada de dentro do bloco `finally` será a propagada, e a lançada de dentro do bloco `try` será usada como sua exceção anterior.

## Manipulador de exceções global

Se uma exceção alcança o escopo global, ela ainda pode ser capturada por um manipulador global de exceções, opcional. A função set_exception_handler() pode configurar uma função que será chamada no lugar de um bloco `catch` na ausẽncia de outros blocos. O efeito é essencialmente o mesmo que ter o programa inteiro envelopado dentro de um bloco `try`-`catch` e a função informada funcionando como o `catch`.

## Notas

> Nota:

> Funções internas ao PHP utilizam principalmente aviso de erros. Apenas extensões orientadas a objetos utilizam exceções. No entanto, os erros podem ser transformados em exceções com ErrorException. Essa técnica não funciona para erros fatais.

> Exemplo #1 Convertendo avisos de erros em exceções

>     <?php
>     function exceptions_error_handler($severity, $message, $filename, $lineno) {
>         throw new ErrorException($message, 0, $severity, $filename, $lineno);
>     }

>     set_error_handler('exceptions_error_handler');

Dica

A biblioteca padrão do PHP (SPL) fornece várias exceções nativas.

## Exemplos

Exemplo #2 Lançando uma exceção

    <?php
    function inverse($x) {
        if (!$x) {
            throw new Exception('Divisão por zero.');
        }
        return 1/$x;
    }

    try {
        echo inverse(5) . "\n";
        echo inverse(0) . "\n";
    } catch (Exception $e) {
        echo 'Exceção capturada: ',  $e->getMessage(), "\n";
    }

    // A execução continua
    echo "Olá mundo\n";

O exemplo acima produzirá:

    0.2
    Exceção capturada: Divisão por zero.
    Olá mundo

Exemplo #3 Manipulação de exceções com bloco `finally`

    <?php
    function inverse($x) {
        if (!$x) {
            throw new Exception('Divisão por zero.');
        }
        return 1/$x;
    }

    try {
        echo inverse(5) . "\n";
    } catch (Exception $e) {
        echo 'Exceção capturada: ',  $e->getMessage(), "\n";
    } finally {
        echo "Primeiro finaly.\n";
    }

    try {
        echo inverse(0) . "\n";
    } catch (Exception $e) {
        echo 'Exceção capturada: ',  $e->getMessage(), "\n";
    } finally {
        echo "Segundo finally.\n";
    }

    // A execução continua
    echo "Olá mundo\n";

O exemplo acima produzirá:

    0.2
    Primeiro finally.
    Exceção capturada: Divisão por zero.
    Segundo finally.
    Olá mundo

Exemplo #4 Interação entre blocos `finally` e `return`

    <?php

    function test() {
        try {
            throw new Exception('foo');
        } catch (Exception $e) {
            return 'catch';
        } finally {
            return 'finally';
        }
    }

    echo test();

O exemplo acima produzirá:

    finally

Exemplo #5 Exceção aninhada

    <?php

    class MyException extends Exception { }

    class Test {
        public function testing() {
            try {
                try {
                    throw new MyException('foo!');
                } catch (MyException $e) {
                    // rethrow it
                    throw $e;
                }
            } catch (Exception $e) {
                var_dump($e->getMessage());
            }
        }
    }

    $foo = new Test;
    $foo->testing();

O exemplo acima produzirá:

    string(4) "foo!"

Exemplo #6 Manipulação de múltiplas exceções no mesmo bloco catch

    <?php

    class MyException extends Exception { }

    class MyOtherException extends Exception { }

    class Test {
        public function testing() {
            try {
                throw new MyException();
            } catch (MyException | MyOtherException $e) {
                var_dump(get_class($e));
            }
        }
    }

    $foo = new Test;
    $foo->testing();

O exemplo acima produzirá:

    string(11) "MyException"

Exemplo #7 Omissão da variável de captura de exceções

Permitido a partir do PHP 8.0.0.

    <?php

    class SpecificException extends Exception {}

    function test() {
        throw new SpecificException('Oopsie');
    }

    try {
        test();
    } catch (SpecificException) {
        print "Uma exceção SpecificException foi lançada, mas os detalhes não importam.";
    }

O exemplo acima produzirá:

    Uma exceção SpecificException foi lançada, mas os detalhes não importam.

Exemplo #8 Throw como uma expressão

Permitido apenas no PHP 8.0.0 e posteriores.

    <?php

    function test() {
        do_something_risky() or throw new Exception('Não funcionou');
    }

    function do_something_risky() {
        return false; // Simula falha
    }

    try {
        test();
    } catch (Exception $e) {
        print $e->getMessage();
    }

O exemplo acima produzirá:

    Não funcionou

Exemplo #9 Exceção em bloco try e bloco finally

    <?php

    try {
        try {
            throw new Exception(message: 'Terceira', previous: new Exception('Quarta'));
        } finally {
            throw new Exception(message: 'Primeira', previous: new Exception('Segunda'));
        }
    } catch (Exception $e) {
        var_dump(
            $e->getMessage(),
            $e->getPrevious()->getMessage(),
            $e->getPrevious()->getPrevious()->getMessage(),
            $e->getPrevious()->getPrevious()->getPrevious()->getMessage(),
        );
    }

O exemplo acima produzirá:

    string(5) "Primeira"
    string(6) "Segunda"
    string(5) "Terceira"
    string(6) "Quarta"

## Estendendo exceções

Uma classe de exceção definida pelo usuário pode ser criada herdando a classe Exception. Os membros e propriedades abaixo mostram o que é acessível a partir da classe filha que deriva da Exception.

Exemplo #1 A classe nativa Exception

    <?php
    class Exception implements Throwable
    {
        protected $message = 'Unknown exception';   // Mensagem da exceção
        private   $string;                          // Cache __toString
        protected $code = 0;                        // Código definido pelo usuário
        protected $file;                            // Nome do arquivo onde a exceção originou
        protected $line;                            // Número da linha onde a exceção originou
        private   $trace;                           // Backtrace
        private   $previous;                        // Exceção anterior (se exceção empilhada)

        public function __construct($message = '', $code = 0, ?Throwable $previous = null);

        final private function __clone();           // Inibe a clonagem de exceções

        final public  function getMessage();        // Mensagem da exceção
        final public  function getCode();           // Código definido pelo usuário
        final public  function getFile();           // Nome do arquivo onde a exceção originou
        final public  function getLine();           // Número da linha onde a exceção originou
        final public  function getTrace();          // Um array do backtrace()
        final public  function getPrevious();       // Exceção anterior
        final public  function getTraceAsString();  // Backtrace formatado como string

        // Pode ser sobrescrito
        public function __toString();               // String formatada da exceção
    }

Se uma classe estender a classe Exception e redefinir o construtor, então é altamente recomendável que também seja chamado o parent::__construct() para garantir que todos os dados estejam corretamente informados. O método __toString() pode ser sobrescrito para fornecer uma representação customizada do objeto quando utilizado como string.

> Nota:

> Exceções não podem ser clonadas. Tentativas de clonar um Exception resultarão em erros `E_ERROR` fatais.

Exemplo #2 Estendendo a classe Exception

    <?php
    /**
     * Define uma classe de exceção
     */
    class MyException extends Exception
    {
        // Redefine a exceção de forma que a mensagem não seja opcional
        public function __construct($message, $code = 0, ?Throwable $previous = null) {
            // código

            // garante que tudo está corretamente inicializado
            parent::__construct($message, $code, $previous);
        }

        // Personaliza a apresentação do objeto como string
        public function __toString() {
            return __CLASS__ . ": [{$this->code}]: {$this->message}\n";
        }

        public function customFunction() {
            echo "Uma função específica desse tipo de exceção\n";
        }
    }

    /**
     * Cria uma classe para testar a exceção
     */
    class TestException
    {
        public $var;

        const THROW_NONE    = 0;
        const THROW_CUSTOM  = 1;
        const THROW_DEFAULT = 2;

        function __construct($avalue = self::THROW_NONE) {

            switch ($avalue) {
                case self::THROW_CUSTOM:
                    // lança a exceção customizada
                    throw new MyException('1 é um parâmetro inválido', 5);
                    break;

                case self::THROW_DEFAULT:
                    // throw default one.
                    throw new Exception('2 não é um parâmetro permitido', 6);
                    break;

                default:
                    // Sem exceção, o objeto será criado
                    $this->var = $avalue;
                    break;
            }
        }
    }

    echo "# Exemplo 1\n";
    try {
        $o = new TestException(TestException::THROW_CUSTOM);
    } catch (MyException $e) {      // Entrará aqui ...
        echo "Pegou MyException\n", $e;
        $e->customFunction();
    } catch (Exception $e) {        // ... mas não aqui.
        echo "Pegou Exception padrão\n", $e;
    }

    // A execução continua
    var_dump($o); // Null

    echo "\n\n# Exemplo 2\n";
    try {
        $o = new TestException(TestException::THROW_DEFAULT);
    } catch (MyException $e) {      // Não entrará aqui ...
        echo "Pegou MyException\n", $e;
        $e->customFunction();
    } catch (Exception $e) {        // ... porque entrará aqui.
        echo "Pegou Exception padrão\n", $e;
    }

    // A execução continua
    var_dump($o); // Null

    echo "\n\n# Exemplo 3\n";
    try {
        $o = new TestException(TestException::THROW_CUSTOM);
    } catch (Exception $e) {        // Entrará aqui
        echo "Pegou exceção padrão\n", $e;
    }

    // A execução continua
    var_dump($o); // Null

    echo "\n\n# Exemplo 4\n";
    try {
        $o = new TestException();
    } catch (Exception $e) {        // Não entrará, sem exceção
        echo "Pegou Exception padrão\n", $e;
    }

    // A execução continua
    var_dump($o); // TestException

# Fibers

### Visão geral de Fibers

(PHP 8 >= 8.1.0)

Fibers representam funções interruptíveis de pilha completa. Fibers podem ser suspensas de qualquer lugar na pilha de chamadas, pausando a execução dentro de Fiber até que Fiber seja retomada posteriormente.

Fibers pausam toda a pilha de execução, portanto, o chamador direto da função não precisa alterar a forma como invoca a função.

A execução pode ser interrompida em qualquer lugar na pilha de chamadas usando Fiber::suspend() (ou seja, a chamada para Fiber::suspend() pode estar em uma função profundamente aninhada ou nem mesmo existir).

Ao contrário dos Generators, cada Fiber tem sua própria pilha de chamadas, permitindo que sejam pausadas em chamadas de função profundamente aninhadas. Uma função que declara um ponto de interrupção (isto é, chamando Fiber::suspend()) não precisa alterar seu tipo de retorno, ao contrário de uma função que usa `yield`, que deve retornar uma instância de Generator.

Fibers podem ser suspensas em qualquer chamada de função, incluindo aquelas chamadas de dentro da VM PHP, como funções fornecidas para array_map() ou métodos chamados por `foreach` em um objeto Iterator.

Uma vez suspensa, a execução de Fiber pode ser retomada com qualquer valor usando Fiber::resume() ou lançando uma exceção na Fiber usando Fiber::throw(). O valor é retornado (ou exceção lançada) de Fiber::suspend().

> Nota: Antes do PHP 8.4.0, trocas de Fibers durante a execução de um destrutor de objeto não eram permitidas.

Exemplo #1 Uso básico

    <?php
    $fiber = new Fiber(function (): void {
       $value = Fiber::suspend('fiber');
       echo "Value used to resume fiber: ", $value, PHP_EOL;
    });

    $value = $fiber->start();

    echo "Value from fiber suspending: ", $value, PHP_EOL;

    $fiber->resume('test');
    ?>

O exemplo acima produzirá:

    Value from fiber suspending: fiber
    Value used to resume fiber: test

# Geradores

## Índice

- Geradores, visão geral
- Sintaxe do Gerador
- Comparando geradores com objetos Iterator

## Geradores, visão geral

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Os geradores fornecem uma maneira fácil de implementar iteradores simples sem a sobrecarga ou complexidade de criar uma classe que implemente a interface Iterator.

Um gerador oferece uma maneira conveniente de fornecer dados a loops `foreach` sem ter que construir um array na memória antecipadamente, o que pode fazer com que o programa exceda um limite de memória ou exija uma quantidade considerável de tempo de processamento para essa geração. Em vez disso, uma função geradora pode ser usada, que é o mesmo que uma função normal, exceto que ao invés do retorno ocorrer uma única vez, um gerador pode executar `yield` quantas vezes forem necessárias para fornecer os valores a serem iterados. Tal como acontece com os iteradores, o acesso aleatório aos dados não é possível.

Um exemplo simples para isso é reimplementar a função range(). A função range() padrão tem que gerar um array com cada valor dentro dele e retorná-lo, o que pode resultar em grandes arrays: por exemplo, chamar range(0, 1000000) irá resultar numa utilização de memória de mais de 100 MB.

Como alternativa, nós podemos implementar um gerador `xrange()`, que só precisará de memória suficiente para criar um objeto Iterator e acompanhar o estado atual do gerador internamente, que utiliza menos de 1 kilobyte de memória.

Exemplo #1 Implementando range() como um gerador

    <?php
    function xrange($start, $limit, $step = 1) {
        if ($start <= $limit) {
            if ($step <= 0) {
                throw new LogicException('O passo precisa ser positivo');
            }

            for ($i = $start; $i <= $limit; $i += $step) {
                yield $i;
            }
        } else {
            if ($step >= 0) {
                throw new LogicException('O passo precisa ser negativo');
            }

            for ($i = $start; $i >= $limit; $i += $step) {
                yield $i;
            }
        }
    }

    /*
     * Observe abaixo que ambos range() e xrange() tem a mesma
     * saída.
     */

    echo 'Números ímpares a partir de range():  ';
    foreach (range(1, 9, 2) as $number) {
        echo "$number ";
    }
    echo "\n";

    echo 'Números ímpares a partir de xrange(): ';
    foreach (xrange(1, 9, 2) as $number) {
        echo "$number ";
    }

O exemplo acima produzirá:

    Números ímpares a partir de range():  1 3 5 7 9
    Números ímpares a partir de xrange(): 1 3 5 7 9

### Objetos Generator

Quando uma função geradora é chamada, um objeto interno de tipo Generator é retornado. Este objeto implementa a interface Iterator que um objeto somente leitura de uma direção implementaria, provendo também métodos que podem ser utilizados para manipular o estado do gerador, incluindo enviar e retornar valores.

## Sintaxe do Gerador

Uma função geradora se parece com uma função normal, exceto que ao invés de retornar um valor, um gerador pode executar `yield` quantas vezes forem necessárias. Qualquer função que contenha `yield` é uma função geradora.

Quando uma função geradora é chamada, ela retorna um objeto que pode ser iterado. Quando você itera através desse objeto (por exemplo, por um loop `foreach`), o PHP irá chamar os métodos de iteração do objeto toda vez que precisar de um valor, em seguida salva o estado do gerador quando o valor é produzido, de modo que possa ser retomado quando o próximo valor for necessário.

Quando não houver mais valores a serem produzidos, o gerador pode simplesmente retornar, e o código que chamou continua como se um array tivesse ficado sem valores.

> Nota:

> Um gerador pode retornar valores, que podem ser recuperados usando Generator::getReturn().

### A palavra-chave yield

O coração de uma função geradora é a palavra-chave yield. Na sua forma mais simples, uma declaração yield se parece muito com um retorno, exceto que em vez de parar a execução da função e retornar, o yield fornece um valor para o código de loop sobre o gerador e pausa a execução da função do gerador.

Exemplo #1 Um exemplo simples de valores yield

    <?php
    function gen_one_to_three() {
        for ($i = 1; $i <= 3; $i++) {
            // Observe que $i é preservado entre chamadas.
            yield $i;
        }
    }

    $generator = gen_one_to_three();
    foreach ($generator as $value) {
        echo "$value\n";
    }

O exemplo acima produzirá:

    1
    2
    3

> Nota:

> Internamente, chaves inteiras sequenciais serão pareadas com os valores entregues, assim como um array não associativo.

#### Produzindo valores com chaves

O PHP suporta arrays associativos e geradores não são diferentes. Além de produzir valores simples, como mostrado acima, você também pode produzir uma chave ao mesmo tempo.

A sintaxe para preparar um par de chave/valor é muito semelhante ao utilizado para definir um array associativo, como mostrado abaixo.

Exemplo #2 Produzindo um par de chave/valor

    <?php
    /*
     * A saída são valores separados por ponto e vírgula, com o primeiro
     * valor sendo usado como um id ou chave.
     */

    $input = <<<'EOF'
    1;PHP;Likes dollar signs
    2;Python;Likes whitespace
    3;Ruby;Likes blocks
    EOF;

    function input_parser($input) {
        foreach (explode("\n", $input) as $line) {
            $fields = explode(';', $line);
            $id = array_shift($fields);

            yield $id => $fields;
        }
    }

    foreach (input_parser($input) as $id => $fields) {
        echo "$id:\n";
        echo "    $fields[0]\n";
        echo "    $fields[1]\n";
    }

O exemplo acima produzirá:

    1:
        PHP
        Likes dollar signs
    2:
        Python
        Likes whitespace
    3:
        Ruby
        Likes blocks

#### Produzindo valores nulos

O yield pode ser chamado sem um argumento para produzir um valor `null` com uma chave automática.

Exemplo #3 Produzindo valores `null`

    <?php
    function gen_three_nulls() {
        foreach (range(1, 3) as $i) {
            yield;
        }
    }

    var_dump(iterator_to_array(gen_three_nulls()));

O exemplo acima produzirá:

    array(3) {
      [0]=>
      NULL
      [1]=>
      NULL
      [2]=>
      NULL
    }

#### Produzindo valores por referência

Funções geradoras são capazes de produzir valores por referência bem como por valor. Isso é feito da mesma forma que retornar referências de funções: incluindo um & no início do nome da função.

Exemplo #4 Produzindo valores por referência

    <?php
    function &gen_reference() {
        $value = 3;

        while ($value > 0) {
            yield $value;
        }
    }

    /*
     * Observe que podemos mudar $number dentro do loop, e
     * porque o gerador retorna referências, $value
     * dentro de gen_reference() é modificado.
     */
    foreach (gen_reference() as &$number) {
        echo (--$number).'... ';
    }

O exemplo acima produzirá:

    2... 1... 0...

#### Delegação de gerador via yield from

A delegação de gerador permite retornar valores de outro gerador, objeto Traversable ou um array utilizando para isso a instrução yield from. O gerador externo retornará todos os valores do gerador interno, objeto ou array até que o mesmo não seja mais válido, a partir de onde a execução continuará no gerador externo.

Se um gerador é utilizado com yield from, a expressão yield from também retornará qualquer valor retornado pelo gerador interno.

Cuidado

# Armazenando em um array (por exemplo, com iterator_to_array())

yield from não redefine as chaves. Ele preserva as chaves retornadas pelo objeto Traversable, ou array. Deste modo, alguns valores podem compartilhar uma chave em comum com outro yield ou yield from, o qual, após inserido em um array, irá sobrescrever os valores anteriores com essa chave.

Um caso onde isso importa é a função iterator_to_array() retornando um array com chaves por padrão, levando a resultados possivelmente inesperados. iterator_to_array() possui um segundo parâmetro `preserve_keys` que pode ser definido como `false` para coletar todos os valores enquanto ignora as chaves retornadas pelo Generator.

Exemplo #5 yield from com iterator_to_array()

    <?php
    function inner() {
        yield 1; // chave 0
        yield 2; // chave 1
        yield 3; // chave 2
    }
    function gen() {
        yield 0; // chave 0
        yield from inner(); // chaves 0-2
        yield 4; // chave 1
    }
    // Passe false no segundo parâmetro para obter um array [0, 1, 2, 3, 4]
    var_dump(iterator_to_array(gen()));

O exemplo acima produzirá:

    array(3) {
      [0]=>
      int(1)
      [1]=>
      int(4)
      [2]=>
      int(3)
    }

Exemplo #6 Uso básico de yield from

    <?php
    function count_to_ten() {
        yield 1;
        yield 2;
        yield from [3, 4];
        yield from new ArrayIterator([5, 6]);
        yield from seven_eight();
        yield 9;
        yield 10;
    }

    function seven_eight() {
        yield 7;
        yield from eight();
    }

    function eight() {
        yield 8;
    }

    foreach (count_to_ten() as $num) {
        echo "$num ";
    }

O exemplo acima produzirá:

    1 2 3 4 5 6 7 8 9 10

Exemplo #7 yield from e valores retornados

    <?php
    function count_to_ten() {
        yield 1;
        yield 2;
        yield from [3, 4];
        yield from new ArrayIterator([5, 6]);
        yield from seven_eight();
        return yield from nine_ten();
    }

    function seven_eight() {
        yield 7;
        yield from eight();
    }

    function eight() {
        yield 8;
    }

    function nine_ten() {
        yield 9;
        return 10;
    }

    $gen = count_to_ten();
    foreach ($gen as $num) {
        echo "$num ";
    }
    echo $gen->getReturn();

O exemplo acima produzirá:

    1 2 3 4 5 6 7 8 9 10

## Comparando geradores com objetos Iterator

A principal vantagem dos geradores é a sua simplicidade. Muito menos código clichê tem de ser reescrito em comparação com a implementação de uma classe Iterator, e o código geralmente é muito mais legível. Por exemplo, a seguinte função e classe são equivalentes:

    <?php
    function getLinesFromFile($fileName) {
        if (!$fileHandle = fopen($fileName, 'r')) {
            return;
        }

        while (false !== $line = fgets($fileHandle)) {
            yield $line;
        }

        fclose($fileHandle);
    }

    // ao invés de:

    class LineIterator implements Iterator {
        protected $fileHandle;

        protected $line;
        protected $i;

        public function __construct($fileName) {
            if (!$this->fileHandle = fopen($fileName, 'r')) {
                throw new RuntimeException('Não foi possível abrir o arquivo "' . $fileName . '"');
            }
        }

        public function rewind() {
            fseek($this->fileHandle, 0);
            $this->line = fgets($this->fileHandle);
            $this->i = 0;
        }

        public function valid() {
            return false !== $this->line;
        }

        public function current() {
            return $this->line;
        }

        public function key() {
            return $this->i;
        }

        public function next() {
            if (false !== $this->line) {
                $this->line = fgets($this->fileHandle);
                $this->i++;
            }
        }

        public function __destruct() {
            fclose($this->fileHandle);
        }
    }

No entanto, essa flexibilidade tem um custo: os geradores somente movem-se para frente e não podem ser rebobinados após a iteração ter sido iniciada. Isso também significa que o geradores não pode ser iterado múltiplas vezes: o gerador precisará ser reconstruído chamando a função geradora novamente.

### Veja Também

- Iteração de Objetos

# Atributos

## Índice

- Visão geral dos atributos
- Sintaxe de Atributo
- Lendo Atributos com a API Reflection
- Declarando Classes de Atributos

## Visão geral dos atributos

(PHP 8)

Os atributos PHP fornecem metadados estruturados e legíveis por máquina para classes, métodos, funções, parâmetros, propriedades e constantes. Eles podem ser inspecionados no momento da execução por meio da API Reflection, permitindo comportamento dinâmico sem modificar o código. Os atributos fornecem uma maneira declarativa de anotar código com metadados.

Atributos permitem o desacoplamento da implementação de um recurso de seu uso. Enquanto interfaces definem estrutura ao impor métodos, atributos fornecem metadados em vários elementos, incluindo métodos, funções, propriedades e constantes. Diferentemente de interfaces, que impõem implementações de métodos, atributos anotam código sem alterar sua estrutura.

Atributos podem complementar ou substituir métodos de interface opcionais fornecendo metadados em vez de estrutura imposta. Considere uma interface `ActionHandler` que representa uma operação em um aplicativo. Algumas implementações podem exigir uma etapa de configuração, enquanto outras não. Em vez de forçar todas as classes que implementam `ActionHandler` a definir um método `setUp()`, um atributo pode indicar requisitos de configuração. Essa abordagem aumenta a flexibilidade, permitindo que os atributos sejam aplicados várias vezes quando necessário.

Exemplo #1 Implementando métodos opcionais de uma interface com Atributos

    <?php
    interface ActionHandler
    {
        public function execute();
    }

    #[Attribute]
    class SetUp {}

    class CopyFile implements ActionHandler
    {
        public string $fileName;
        public string $targetDirectory;

        #[SetUp]
        public function fileExists()
        {
            if (!file_exists($this->fileName)) {
                throw new RuntimeException("Arquivo não existe");
            }
        }

        #[SetUp]
        public function targetDirectoryExists()
        {
            if (!file_exists($this->targetDirectory)) {
                mkdir($this->targetDirectory);
            } elseif (!is_dir($this->targetDirectory)) {
                throw new RuntimeException("Diretório de destino $this->targetDirectory não é um diretório");
            }
        }

        public function execute()
        {
            copy($this->fileName, $this->targetDirectory . '/' . basename($this->fileName));
        }
    }

    function executeAction(ActionHandler $actionHandler)
    {
        $reflection = new ReflectionObject($actionHandler);

        foreach ($reflection->getMethods() as $method) {
            $attributes = $method->getAttributes(SetUp::class);

            if (count($attributes) > 0) {
                $methodName = $method->getName();

                $actionHandler->$methodName();
            }
        }

        $actionHandler->execute();
    }

    $copyAction = new CopyFile();
    $copyAction->fileName = "/tmp/foo.jpg";
    $copyAction->targetDirectory = "/home/user";

    executeAction($copyAction);

## Sintaxe de Atributo

A sintaxe de atributo consiste em vários componentes-chave. Uma declaração de atributo começa com `#[` e termina com `]`. Dentro, um ou mais atributos podem ser listados, separados por vírgulas. O nome do atributo pode ser não qualificado, qualificado, ou totalmente qualificado, conforme descrito em Usando Namespaces Básicos. Argumentos para o atributo são opcionais e colocados entre parênteses `()`. Argumentos podem ser apenas valores literais ou expressões constantes. Tanto a sintaxe de argumento posicional quanto a de argumento nomeado são suportadas.

Nomes de atributos e seus argumentos são resolvidos para uma classe, e os argumentos são passados ​​para seu construtor quando uma instância do atributo é solicitada por meio da API Reflection. Portanto, é recomendado introduzir uma classe para cada atributo.

Exemplo #1 Sintaxe de Atributo

    <?php
    // a.php
    namespace MyExample;

    use Attribute;

    #[Attribute]
    class MyAttribute
    {
        const VALUE = 'value';

        private $value;

        public function __construct($value = null)
        {
            $this->value = $value;
        }
    }

    // b.php

    namespace Another;

    use MyExample\MyAttribute;

    #[MyAttribute]
    #[\MyExample\MyAttribute]
    #[MyAttribute(1234)]
    #[MyAttribute(value: 1234)]
    #[MyAttribute(MyAttribute::VALUE)]
    #[MyAttribute(array("key" => "value"))]
    #[MyAttribute(100 + 200)]
    class Thing
    {
    }

    #[MyAttribute(1234), MyAttribute(5678)]
    class AnotherThing
    {
    }

## Lendo Atributos com a API Reflection

Para acessar atributos de classes, métodos, funções, parâmetros, propriedades e constantes de classe, use o método getAttributes() fornecido pela API Reflection. Este método retorna um array de instâncias de ReflectionAttribute. Essas instâncias podem ser consultadas para o nome do atributo, argumentos e podem ser usadas para instanciar o atributo representado.

Separar a representação do atributo refletido de sua instância real fornece mais controle sobre o tratamento de erros, como classes de atributos ausentes, argumentos digitados incorretamente ou valores ausentes. Objetos da classe de atributo são instanciados somente após chamar ReflectionAttribute::newInstance(), garantindo que a validação do argumento ocorra naquele ponto.

Exemplo #1 Lendo Atributos Usando a API Reflection

    <?php

    #[Attribute]
    class MyAttribute
    {
        public $value;

        public function __construct($value)
        {
            $this->value = $value;
        }
    }

    #[MyAttribute(value: 1234)]
    class Thing
    {
    }

    function dumpAttributeData($reflection) {
        $attributes = $reflection->getAttributes();

        foreach ($attributes as $attribute) {
           var_dump($attribute->getName());
           var_dump($attribute->getArguments());
           var_dump($attribute->newInstance());
        }
    }

    dumpAttributeData(new ReflectionClass(Thing::class));

O exemplo acima produzirá:

    string(11) "MyAttribute"
    array(1) {
      ["value"]=>
      int(1234)
    }
    object(MyAttribute)#3 (1) {
      ["value"]=>
      int(1234)
    }

Em vez de iterar sobre todos os atributos na instância de reflexão, você pode recuperar apenas aqueles de uma classe de atributo específica passando o nome da classe de atributo como um argumento.

Exemplo #2 Lendo Atributos Específicos Usando a API Reflection

    <?php
    #[Attribute]
    class MyAttribute
    {
        public $value;

        public function __construct($value)
        {
            $this->value = $value;
        }
    }

    #[MyAttribute(value: 1234)]
    class Thing
    {
    }

    function dumpMyAttributeData($reflection) {
        $attributes = $reflection->getAttributes(MyAttribute::class);

        foreach ($attributes as $attribute) {
           var_dump($attribute->getName());
           var_dump($attribute->getArguments());
           var_dump($attribute->newInstance());
        }
    }

    dumpMyAttributeData(new ReflectionClass(Thing::class));

## Declarando Classes de Atributos

É recomendado definir uma classe separada para cada atributo. No caso mais simples, uma classe vazia com a declaração `#[Attribute]` é suficiente. O atributo pode ser importado do namespace global usando uma declaração `use`.

Exemplo #1 Classe de Atributo Simples

    <?php

    namespace Example;

    use Attribute;

    #[Attribute]
    class MyAttribute
    {
    }

Para restringir os tipos de declarações às quais um atributo pode ser aplicado, passe uma máscara de bits como o primeiro argumento para a declaração `#[Attribute]`.

Exemplo #2 Usando a especificação de destino para restringir onde os atributos podem ser usados

    <?php

    namespace Example;

    use Attribute;

    #[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION)]
    class MyAttribute
    {
    }

Declarar MyAttribute em outro tipo agora lançará uma exceção durante a chamada para ReflectionAttribute::newInstance()

Os seguintes alvos podem ser especificados:

- `Attribute::TARGET_CLASS`
- `Attribute::TARGET_FUNCTION`
- `Attribute::TARGET_METHOD`
- `Attribute::TARGET_PROPERTY`
- `Attribute::TARGET_CLASS_CONSTANT`
- `Attribute::TARGET_PARAMETER`
- `Attribute::TARGET_ALL`

Por padrão, um atributo só pode ser usado uma vez por declaração. Para permitir que um atributo seja repetível, especifique-o na máscara de bits da declaração `#[Attribute]` usando o sinalizador `Attribute::IS_REPEATABLE`.

Exemplo #3 Usando IS_REPEATABLE para permitir o atributo em uma declaração várias vezes

    <?php

    namespace Example;

    use Attribute;

    #[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION | Attribute::IS_REPEATABLE)]
    class MyAttribute
    {
    }

# Referências

## Índice

- O que são referências
- O que as referências fazem
- O que referências não são
- Passagem por referência
- Retornando referências
- Destruindo referências
- Demonstrando referências

## O que são referências

Referência em PHP significa acessar o mesmo conteúdo de variável através de vários nomes. Isto não é parecido com os ponteiros em C. Por exemplo, não é possível efetuar aritmética de ponteiros com referências, já que elas não são endereços de memória. Consulte O que referências não são para mais informações. Ao invés disso, elas são apelidos para tabela de símbolos. Observe que no PHP, um nome de variável e um conteúdo de variável são coisas diferentes, portanto o mesmo conteúdo pode ter nomes diferentes. A analogia mais próxima é com arquivos e nomes de arquivos Unix - os nomes de variáveis são como entradas de diretórios, enquanto que o conteúdo de variável é com o conteúdo do arquivo em si. Referências são parecidas com ligações concretas no sistema de arquivo Unix.

## O que as referências fazem

Há três operações básicas ao se utilizar referências: atribuição por referência, passagem por referência, e retorno por referência. Esta seção fará uma introdução dessas operações, com atalhos para leituras posteriores.

### Atribuição por referência

Referências no PHP permitem criar duas variáveis que se referem ao mesmo conteúdo. Ou seja, quando se faz:

    <?php
    $a =& $b;

$a e $b apontam para o mesmo conteúdo.

> Nota:

> $a e $b são completamente iguais aqui, mas não porque $a está apontando para $b ou vice-versa, mas sim que $a e $b apontam para o mesmo lugar.

> Nota:

> Se uma variável indefinida for atribuída, passada ou retornada por referência, ela será criada.

> Exemplo #1 Usando referência com variáveis indefinidas

>     <?php

>     function foo(&$var) {}

>     foo($a); // $a é "criada" e definida como null

>     $b = array();
>     foo($b['b']);
>     var_dump(array_key_exists('b', $b)); // bool(true)

>     $c = new stdClass();
>     foo($c->d);
>     var_dump(property_exists($c, 'd')); // bool(true)

A mesma sintaxe pode ser utilizada com funções que retornem referências:

    <?php
    $foo =& find_var($bar);

Usar essa mesma sintaxe com uma função que não retorna por referência irá gerar um erro, da mesma forma no caso do operador new. Ainda que objetos sejam internamente passados como ponteiros, isso não é o mesmo que uma referência, como explicado em Objetos e Referências.

Aviso

Se for atribuída uma referência para uma variável declarada `global` dentro da função, a referência será visível somente dentro da função. Pode-se evitar isso usando o array $GLOBALS.

Exemplo #2 Referenciando variáveis globais de dentro de funções

    <?php
    $var1 = "Variável de exemplo";
    $var2 = "";

    function global_references($use_globals)
    {
        global $var1, $var2;

        if (!$use_globals) {
            $var2 =& $var1; // visível somente dentro da função
        } else {
            $GLOBALS["var2"] =& $var1; // visível também no contexto global
        }
    }

    global_references(false);
    echo "var2 é definida como '$var2'\n"; // var2 é definida como ''

    global_references(true);
    echo "var2 é definida como '$var2'\n"; // var2 é definida como 'Variável de exemplo'

Veja `global $var;` como atalho para `$var =& $GLOBALS['var'];`. Assim, atribuir outra referência para `$var` somente modifica a variável de referência local.

> Nota:

> Se um valor for atribuído por referência a uma variável numa instrução `foreach`, a referência também é modificada.

> Exemplo #3 Referências e o comando foreach

>     <?php
>     $ref = 0;
>     $row =& $ref;

>     foreach (array(1, 2, 3) as $row) {
>         // Faz alguma coisa
>     }

>     echo $ref; // 3 - último elemento do array iterado

Ainda que não seja uma atribuição por referência explícita, expressões criadas com o construtor `array()` também podem se comportar como tais com o prefixo `&` no elemento de array a ser acrescentado. Exemplo:

    <?php
    $a = 1;
    $b = array(2, 3);

    $arr = array(&$a, &$b[0], &$b[1]);
    $arr[0]++;
    $arr[1]++;
    $arr[2]++;
    /* $a == 2, $b == array(3, 4); */
    var_dump($a);
    var_dump($b);

Note que referências dentro de arrays são potencialmente perigosas. Fazer uma atribuição normal (sem referência) com uma referência à direita não transforma a expressão a esquerda numa referência, mas referências dentro de arrays são preservadas nessas atribuições normais. Isso também se aplica a chamadas de função onde arrays são passados por valor. Exemplo:

    <?php

    /* Atribuição de variáveis escalares */
    $a = 1;
    $b =& $a;
    $c = $b;
    $c = 7; // $c não é referência; não modifica $a ou $b
    print "a = {$a}; b = {$b}; c = {$c}\n\n";

    /* Atribuição de variáveis do array */
    $arr = array(1);
    $a =& $arr[0]; // $a e $arr[0] estão no mesmo conjunto de referências
    $arr2 = $arr; // Não atribui por referência!
    $arr2[0]++;
    /* $a == 2, $arr == array(2) */
    /* O conteúdo de $arr é modificado embora ele não seja uma referência! */
    print "a = {$a}\n";
    var_dump($arr);
    var_dump($arr2);

Em outras palavras, o comportamento de referências em arrays é definido elemento por elemento. O comportamento de referências dos elementos individuais é dissociado do status da referência do array que os contém.

### Passagem por referência

A segunda coisa que referências fazem é passar variáveis por referência. Isso é feito com a criação de uma variável local em uma função e uma variável no escopo chamador que referenciam o mesmo conteúdo. Assim:

    <?php
    function foo(&$var)
    {
        $var++;
    }

    $a = 5;
    foo($a);
    print $a;

a variável $a será 6 no final. Isto ocorre porque na função foo a variável $var se referem ao mesmo conteúdo de $a. Para mais informações disso veja a seção de passagem por referência.

### Retorno por referência

A terceira coisa que as referências fazem é retorno por referência.

## O que referências não são

Como dito anteriormente, referências não são ponteiros. Isso significa que a construção a seguir não funciona como se possa esperar:

    <?php
    function foo(&$var)
    {
        $var =& $GLOBALS["baz"];
    }

    foo($bar);

O que acontece é que $var em foo será ligada com $bar pelo chamador, mas depois será re-ligada com $GLOBALS["baz"]. Não há como ligar $bar no escopo chamador para outra coisa utilizando-se o mecanismo de referência, pois $bar não está disponível na função foo (ela é representada por $var, mas $var somente tem o conteúdo da variável e não a vinculação nome-valor na tabela de símbolos do chamador). Pode-se utilizar retorno por referência para referenciar variáveis selecionadas pela função.

## Passagem por referência

Uma variável pode ser passada por referência a uma função de forma que a função possa modificar a variável. A sintaxe é a seguinte:

    <?php
    function foo(&$var)
    {
        $var++;
    }

    $a = 5;
    foo($a);
    print $a; // $a é 6 aqui

> Nota: Não há o sinal de referência na chamada da função - apenas nas definições de função. As definições de função, sozinhas, são suficientes para passar o argumento por referência.

Os itens seguintes podem ser passados por referência:

- Variáveis, como `foo($a)`

- Referências retornadas de funções, como:

      <?php

      function foo(&$var)
      {
          $var++;
          print $var;
      }

      function &bar()
      {
          $a = 5;
          return $a;
      }

      foo(bar());

  Veja mais sobre isso em retorno por referência.

Nenhuma outra expressão pode ser passada por referência pois não tem comportamento definido. Os seguintes exemplos de passagem por referência são inválidos:

    <?php

    function foo(&$var)
    {
        $var++;
    }

    function bar() // Repare que falta &
    {
        $a = 5;
        return $a;
    }

    foo(bar()); // Gera um aviso

    foo($a = 5); // Expressão, não uma variável
    foo(5); // Gera um erro fatal

    class Foobar {}

    foo(new Foobar()) // Produz um aviso no PHP 7.0.7
                      // Somente variáveis devem ser passadas por referência

## Retornando referências

Retorno por referência é útil quando é necessário utilizar uma função para localizar variáveis cuja referência precisa ser obtida. Não deve ser usado retorno por referência para aumentar desempenho, o mecanismo é esperto o bastante para otimizar isso. Referências somente devem ser retornadas quando existir uma razão técnica para isso! Para retornar referências, a sintaxe abaixo deve ser usada:

    <?php

    class Foo
    {
        public $value = 42;

        public function &getValue()
        {
            return $this->value;
        }
    }

    $obj = new Foo();
    $myValue = &$obj->getValue(); // $myValue é uma referência a $obj->value, que é 42
    $obj->value = 2;
    echo $myValue;                // exibe o valor valor de $obj->value, ou seja, 2

Neste exemplo, a propriedade do objeto retornado pela função getValue precisa ser assimilada, não copiada, como acontecerá se não utilizar a sintaxe de referências.

> Nota: Diferentemente da passagem de parâmetros por referência, aqui é necessário utilizar `&` em ambos os lugares - primeiro para indicar o retorno por referência (e não a cópia), e depois para indicar a ligação da referência (em vez da assimilação convencional) que precisa ser explícita para $myValue.

> Nota: Se houver tentativa de retornar uma referência de uma função com a sintaxe `return ($this->value);`, isto não funcionará como esperado para retornar o resultado de uma expressão, e não uma variável, por referência. Deve-se retornar variáveis por referência somente para uma função - nada além disso.

Para utilizar a referência retornada, é necessário utilizar a atribuição por referência:

    <?php

    function &collector()
    {
        static $collection = array();
        return $collection;
    }

    $collection = &collector();
    // Agora $collection é uma variável por referência que referencia o array estático dentro da função

    $collection[] = 'foo';

    print_r(collector());

O exemplo acima produzirá:

    Array
    (
        [0] => foo
    )

> Nota: Se a atribuição for feita sem o símbolo `&` symbol, por exemplo, `$collection = collector();`, a variável $collection receberá uma cópia do valor, e não a referência retornada pela função.

Para passar a referência retornada para outra função que espera uma referência, a seguinte sintaxe pode ser utilizada:

    <?php

    function &collector()
    {
        static $collection = array();
        return $collection;
    }

    array_push(collector(), 'foo');

> Nota: Note que `array_push(&collector(), 'foo');` não funcionará, e retornará um erro fatal.

## Destruindo referências

Quando uma referência é quebrada, ela apenas para de fazer o apontamento entre o nome da variável e o conteúdo. Mas isto não significa que o conteúdo da variável é destruído. Por exemplo:

    <?php

    $a = 1;
    $b =& $a;
    unset ($a);
    var_dump($a);
    var_dump($b);

não apaga $b, apenas $a.

Novamente, é mais fácil pensar em analogia ao comando UNIX unlink.

## Demonstrando referências

Vários construtores sintáticos do PHP são implementados através de mecanismos de referência, assim, tudo o explicado até aqui sobre referências também se aplica a esses construtores. Alguns desses construtores, como a passagem e o retorno de referências foram mencionados acima. Outros construtores que também utilizam referências são:

### Referências globais

Quando uma variável é declarada como global $var, de fato uma referência está sendo criada para a variável global. Isto significa que isto é o mesmo que:

    <?php
    $var =& $GLOBALS["var"];

O que significa também que destruir $var não apaga a variável global.

# Variáveis predefinidas

O PHP fornece variáveis predefinidas que representam variáveis externas, variáveis nativas de ambiente e outras informações sobre o ambiente de execução, como o número e os valores dos argumentos passados para o script no ambiente CLI.

# Superglobais

Superglobais — Variáveis nativas que estão sempre disponíveis em todos escopos

### Descrição

Várias variáveis predefinidas no PHP são "superglobais", que significa que elas estão disponíveis em todos os escopos para todo o script. Não há necessidade de fazer global $variable; para acessá-lo dentro de funções ou métodos.

Estas variáveis superglobais são:

- $GLOBALS
- $_SERVER
- $_GET
- $_POST
- $_FILES
- $_COOKIE
- $_SESSION
- $_REQUEST
- $_ENV

### Notas

> Nota: Disponibilidade da variável

> Por padrão, todas as superglobais estão disponíveis, mas há diretivas que afetam esta disponibilidade. Para mais informações, consulte na documentação sobre variables_order.

> Nota: Variável variáveis

> Superglobais não podem ser usadas como variável variáveis dentro de função ou métodos de classes.

### Veja Também

- escopo de variável
- A diretiva variables_order
- A extensão filter

# $GLOBALS

(PHP 4, PHP 5, PHP 7, PHP 8)

$GLOBALS — Referencia todas variáveis disponíveis no escopo global

### Descrição

Um array associativo contendo referências para todas as variáveis que estão atualmente definidas no escopo global do script. O nome das variáveis são chaves do array.

### Exemplos

Exemplo #1 Exemplo da $GLOBALS

    <?php

    function teste()
    {
        $foo = "variável local";

        echo '$foo no escopo global: ' . $GLOBALS["foo"] . "\n";
        echo '$foo no escopo atual: ' . $foo . "\n";
    }

    $foo = "Conteúdo de exemplo";
    teste();

    ?>

O exemplo acima produzirá algo semelhante a:

    $foo no escopo global: Conteúdo de exemplo
    $foo no escopo atual: variável local

Aviso

A partir do 8.1.0, acesso de escrita a todo o array $GLOBALS não é mais suportado:

Exemplo #2 Escrever em todo o $GLOBALS irá resultar em um erro.

    <?php

    // Gera um erro em tempo de compilação:
    $GLOBALS = [];
    $GLOBALS += [];
    $GLOBALS =& $x;
    $x =& $GLOBALS;
    unset($GLOBALS);
    array_pop($GLOBALS);
    // ...e qualquer outra operação de escrita/leitura em $GLOBALS

    ?>

### Notas

> Nota: Esta é uma variável 'superglobal' ou variável global automática. Isso significa simplesmente que ela está disponível em todos os escopos de um script. Não há necessidade de usar global $variable; para acessá-la dentro de funções ou métodos.

> Nota: Disponibilidade da variável

> Diferente de todas as outras superglobais, $GLOBALS tem essencialmente sempre estado disponível no PHP.

> Nota:

> A partir do PHP 8.1.0, $GLOBALS agora é uma cópia somente-leitura da tabela de símbolos globais. Isto é, variáveis globais não podem ser modificadas por meio de suas cópias. Anteriormente, o array $GLOBALS era excluído do comportamento usual "por valor" dos arrays PHP e variáveis globais podiam ser modificadas por meio de suas cópias.

>     <?php

>     // Antes do PHP 8.1.0
>     $a = 1;

>     $globals = $GLOBALS; // Cópia ostensiva "por valor"
>     $globals['a'] = 2;
>     var_dump($a); // int(2)

>     // A partir do PHP 8.1.0,
>     // isto não mais modifica $a. O comportamento anterior violava a semântica "por valor".
>     $globals = $GLOBALS;
>     $globals['a'] = 1;

>     // Para restaurar o comportamento anterior, itera sua cópia e atribui cada propriedade de volta ao $GLOBALS.
>     foreach ($globals as $key => $value) {
>         $GLOBALS[$key] = $value;
>     }

>     ?>

# $_SERVER

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_SERVER — Informação do servidor e ambiente de execução

### Descrição

$_SERVER é um array contendo informação como cabeçalhos, caminhos, e outras informações do script. As informações nesse array são criadas pelo servidor web específico, e portanto não há garantias que sempre existirão as mesmas informações, podendo algumas serem omitidas ou adicionadas em relação à lista a seguir. Entretanto, a maioria dessas variáveis são documentadas na » especificação CGI/1.1, e estão normalmente definidas.

> Nota: Quando PHP é executado na linha de comando a maioria dessas informações não estará disponível ou não terá qualquer sentido.

Além dos valores listados a seguir, o PHP irá criar itens adicionais com valores dos cabeçalhos de requisição. Esses itens serão prefixados com `HTTP_` seguido do nome do cabeçalho, capitalizados e com sublinhados ao invés de hifens. Por exemplo, o cabeçalho `Accept-Language` estará disponível como `$_SERVER['HTTP_ACCEPT_LANGUAGE']`.

### Índices

'PHP_SELF'
  O nome do arquivo do script que está sendo executado, relativo à raiz do documento. Por exemplo, $_SERVER['PHP_SELF'] em um script no endereço http://example.com/foo/bar.php seria /foo/bar.php. A constante __FILE__ contém o caminho completo e nome do arquivo atual (possivelmente incluído). Se o PHP estiver sendo executado em linha de comando, esta variável contém o nome do script.
'argv'
  Array de argumentos passado para o script. Quando o script é executado na linha de comando, isto permite um acesso aos parâmetros de linha de comando no estilo da linguagem C. Quando chamado via método GET, ele conterá a string da consulta.
'argc'
  Contém o número de parâmetros da linha de comando passados para o script (se executando da linha de comando).
'GATEWAY_INTERFACE'
  O número de revisão da especificação CGI que o servidor está utilizando, por exemplo: `'CGI/1.1'`.
'SERVER_ADDR'
  O endereço IP do servidor onde está o script em execução.
'SERVER_NAME'
  O nome host do servidor onde o script atual é executado. Se o script estiver sendo executado em um host virtual, este será o valor definido para esse host.

  > Nota: No Apache 2, você deve definir `UseCanonicalName = On` e `ServerName`. Caso contrário, este valor refletirá o nome do servidor fornecido pelo cliente, que pode ser forjado. Não é seguro confiar neste valor em contextos que dependem de segurança.

'SERVER_SOFTWARE'
  A string de identificação do servidor, fornecida nos cabeçalhos ao responder a requisições.
'SERVER_PROTOCOL'
  Nome e número da revisão do protocolo de informação pelo qual a página foi requerida, por exemplo`'HTTP/1.0'`;
'REQUEST_METHOD'
  Contém o método de requisição utilizado para acessar a página. Geralmente '`'GET'`', '`'HEAD'`', '`'POST'`' ou '`'PUT'`'.

  > Nota:

  > O script PHP é terminado depois dos cabeçalhos enviados (ou seja, depois de produzir alguma saída sem saída do buffer) se o método da requisição for `HEAD`.

'REQUEST_TIME'
  O timestamp de quando o PHP começou a processar a requisição.
'REQUEST_TIME_FLOAT'
  O timestamp de quando o PHP começou a processar a requisição, com precisão em microssegundos.
'QUERY_STRING'
  A string de consulta, se houver, pela qual a página foi acessada.
'DOCUMENT_ROOT'
  O diretório raiz sob o qual o script atual é executado, como definido no arquivo de configuração do servidor.
'HTTPS'
  Definido para um valor não vazio se o script foi requisitado através do protocolo HTTPS.
'REMOTE_ADDR'
  O endereço IP de onde o usuário está visualizando a página atual.
'REMOTE_HOST'
  O nome do host que o usuário utilizou para chamar a página atual. O DNS reverso do REMOTE_ADDR do usuário.

  > Nota: O servidor web precisa estar configurado para criar essa variável. Por exemplo, no Apache é necessário inserir um `HostnameLookups On` dentro do httpd.conf. Veja também gethostbyaddr().

'REMOTE_PORT'
  A porta TCP na máquina do usuário utilizada para comunicação com o servidor web.
'REMOTE_USER'
  O usuário autenticado.
'REDIRECT_REMOTE_USER'
  O usuário autenticado utilizado se a requisição foi redirecionada internamente.
'SCRIPT_FILENAME'

  O caminho absoluto do script atualmente em execução.

  > Nota:

  > Se o script for executado pela CLI com um caminho relativo, como file.php ou ../file.php, $_SERVER['SCRIPT_FILENAME'] irá conter o caminho relativo especificado pelo usuário.

'SERVER_ADMIN'
  O valor fornecido pela diretiva SERVER_ADMIN (do Apache) no arquivo de configuração do servidor. Se o script está sendo executado em um host virtual, este será o valor definido para esse host virtual.
'SERVER_PORT'
  A porta na máquina servidora utilizada pelo servidor web para comunicação. Como padrão, este valor é '`'80'`'. Utilizando SSL, entretanto, esse valor será alterado para a porta HTTP de comunicação segura.

  > Nota: Utilizando o Apache 2, deve-se configurar `UseCanonicalName = On`, assim como `UseCanonicalPhysicalPort = On` para se obter a porta física (real), caso contrário, este valor pode ser forjado e pode, ou não, retornar como valor a porta física. Não é seguro confiar neste valor em contextos que dependem de segurança.

'SERVER_SIGNATURE'
  String contendo a versão do servidor e nome do host virtual que é adicionado às páginas geradas no servidor, se ativo.
'PATH_TRANSLATED'
  O caminho real do script relativo ao sistema de arquivos (não a raiz dos documentos), depois de realizados todos os mapeamentos de caminhos (virtuais para reais).

  > Nota: Usuários do Apache 2 podem usar `AcceptPathInfo = On` dentro do httpd.conf para definir o PATH_INFO.

'SCRIPT_NAME'
  Contém o caminho completo do script atual. Útil para páginas que precisam apontar para elas mesmas (dinamicamente). A constante __FILE__ contém o caminho completo e nome do arquivo atual (mesmo se tiver sido incluído).
'REQUEST_URI'
  O URI fornecido para acessar a página atual, por exemplo, '`/index.html`'.
'PHP_AUTH_DIGEST'
  Quando executando no Apache como módulo fazendo autenticação HTTP, esta variável é definida para o cabeçalho 'Authorization' enviado pelo cliente (que então pode ser usado para fazer a validação apropriada).
'PHP_AUTH_USER'
  Ao efetuar autenticação HTTP, esta variável estará definida com o nome de usuário fornecido pelo usuário.
'PHP_AUTH_PW'
  Ao efetuar autenticação HTTP, esta variável estará definida com a senha fornecida pelo usuário.
'AUTH_TYPE'
  Ao efetuar autenticação HTTP, esta variável estará definida com o tipo de autenticação utilizado.
'PATH_INFO'
  Contém qualquer informação fornecida pelo usuário, se disponível, que leve ao nome do script atual, precedendo a string de consulta. Por exemplo, se o script atual fosse acessado via a URL http://www.example.com/php/path_info.php/some/stuff?foo=bar, então $_SERVER['PATH_INFO'] teria como valor `/some/stuff`
'ORIG_PATH_INFO'
  Versão original do 'PATH_INFO' antes de ser processada pelo PHP.

### Exemplos

Exemplo #1 Exemplo de $_SERVER

    <?php
    echo $_SERVER['SERVER_NAME'];
    ?>

O exemplo acima produzirá algo semelhante a:

    www.example.com

### Notas

> Nota: Esta é uma variável 'superglobal' ou variável global automática. Isso significa simplesmente que ela está disponível em todos os escopos de um script. Não há necessidade de usar global $variable; para acessá-la dentro de funções ou métodos.

### Veja Também

- A extensão filter

# $_GET

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_GET — Variáveis de string de consulta

### Descrição

Um array associativo de variáveis passadas para o script atual através dos parâmetros da URL (também conhecidos como string de consulta). Observe que este array é preenchido sempre que uma string de consulta estiver presente, independentemente do método de requisição HTTP.

### Exemplos

Exemplo #1 Exemplo da $_GET

    <?php
    echo 'Olá ' . htmlspecialchars($_GET["nome"]) . '!';
    ?>

Assumindo que o usuário digitou `http://example.com/?name=Hannes`.

O exemplo acima produzirá algo semelhante a:

    Olá Hannes!

### Notas

> Nota: Esta é uma variável 'superglobal' ou variável global automática. Isso significa simplesmente que ela está disponível em todos os escopos de um script. Não há necessidade de usar global $variable; para acessá-la dentro de funções ou métodos.

> Nota:

> Os valores em $_GET são passados automaticamente através de urldecode().

### Veja Também

- Manuseamento de variáveis externas
- A extensão filter

# $_POST

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_POST — Dados de formulário de requisições POST HTTP

### Descrição

Um array associativo de variáveis passados para o script atual via método HTTP POST quando utilizado `application/x-www-form-urlencoded` ou `multipart/form-data` como valor do cabeçalho HTTP Content-Type na requisição.

### Exemplos

Exemplo #1 Exemplo da $_POST

    <?php
    echo 'Hello ' . htmlspecialchars($_POST["name"]) . '!';
    ?>

Assumindo que o usuário enviou uma requisição POST com `name=Hannes` no corpo.

O exemplo acima produzirá algo semelhante a:

    Hello Hannes!

### Notas

> Nota: Esta é uma variável 'superglobal' ou variável global automática. Isso significa simplesmente que ela está disponível em todos os escopos de um script. Não há necessidade de usar global $variable; para acessá-la dentro de funções ou métodos.

> Nota: Para ler dados POST enviados com outros tipos de conteúdo (por exemplo `application/json` ou `application/xml`), deve-se usar php://input. Ao contrário de $_POST que só funciona com `application/x-www-form-urlencoded` e `multipart/form-data`, o uso de php://input fornece acesso direto ao dado bruto do corpo da requisição.

### Veja Também

- Manipulando variáveis externas
- A extensão filter

# $_FILES

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_FILES — Variáveis de Upload de Arquivos HTTP

### Descrição

Um array associativo de items enviado através do script atual pelo método HTTP POST. A estrutura deste array é detalhada na seção Uploads com o método POST.

### Notas

> Nota: Esta é uma variável 'superglobal' ou variável global automática. Isso significa simplesmente que ela está disponível em todos os escopos de um script. Não há necessidade de usar global $variable; para acessá-la dentro de funções ou métodos.

### Veja Também

- move_uploaded_file() - Move um arquivo enviado para uma nova localização
- Manuseamento de upload de arquivos

# $_REQUEST

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_REQUEST — Variáveis de requisição HTTP

### Descrição

Um array associativo que por padrão contém informações de $_GET, $_POST e $_COOKIE.

### Notas

> Nota: Esta é uma variável 'superglobal' ou variável global automática. Isso significa simplesmente que ela está disponível em todos os escopos de um script. Não há necessidade de usar global $variable; para acessá-la dentro de funções ou métodos.

> Nota:

> Quando executando em linha de comando , esta não incluirá as entradas argv e argc; estas estão presentes no array $_SERVER.

> Nota:

> As variáveis em $_REQUEST são providas para o script via mecanismos de entradas GET, POST, e COOKIE e portanto poderia ser modificadas por um usuário remoto e não podem ser confiadas. A presença e ordem das variáveis listadas neste array é definido de acordo com o PHP request_order, e variables_order diretivas de configuração

### Veja Também

- Manuseamento de variáveis externas
- A extensão filter

# $_SESSION

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_SESSION — Variáveis de sessão

### Descrição

Um array associativo contendo variáveis de sessão disponíveis para o atual script. Veja a documentação das funções de Sessão para mais informação em como usar isto.

### Notas

> Nota: Esta é uma variável 'superglobal' ou variável global automática. Isso significa simplesmente que ela está disponível em todos os escopos de um script. Não há necessidade de usar global $variable; para acessá-la dentro de funções ou métodos.

### Veja Também

- session_start() - Inicia uma nova sessão ou continua uma sessão existente

# $_ENV

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_ENV — Variáveis de ambiente

### Descrição

Um array associativo de variáveis passadas para o script atual via o método do ambiente.

Estas variáveis são importadas para o PHP do ambiente sob o qual o parser do PHP é executado. Muitas são providas pelo shell sob o qual o PHP é executado e diferentes sistemas são prováveis executar diferentes tipos de shells, uma lista definitiva é impossível. Veja a documentação de shell para saber a lista de variáveis de ambiente definidas.

Outras variáveis de ambiente incluem variáveis CGI, elas aparecem desconsiderando se o PHP é executado como um módulo do servidor ou processador CGI.

### Exemplos

Exemplo #1 Exemplo da $_ENV

    <?php
    echo 'Meu nome de usuário é ' .$_ENV["USER"] . '!';
    ?>

Assumindo que "bjori" executou este script

O exemplo acima produzirá algo semelhante a:

    Meu nome de usuário é bjori!

### Notas

> Nota: Esta é uma variável 'superglobal' ou variável global automática. Isso significa simplesmente que ela está disponível em todos os escopos de um script. Não há necessidade de usar global $variable; para acessá-la dentro de funções ou métodos.

### Veja Também

- getenv() - Obtém o valor de uma única ou de todas as variáveis ​​de ambiente
- A extensão filter

# $_COOKIE

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_COOKIE — Cookies HTTP

### Descrição

Um array associativo de variáveis passadas para o atual script via HTTP Cookies.

### Exemplos

Exemplo #1 Exemplo da $_COOKIE

    <?php
    echo 'Hello ' . htmlspecialchars($_COOKIE["name"]) . '!';
    ?>

Assumindo que o "nome" do cookie tenha sido definido antes

O exemplo acima produzirá algo semelhante a:

    Hello Hannes!

### Notas

> Nota: Esta é uma variável 'superglobal' ou variável global automática. Isso significa simplesmente que ela está disponível em todos os escopos de um script. Não há necessidade de usar global $variable; para acessá-la dentro de funções ou métodos.

### Veja Também

- setcookie() - Envia um cookie
- Manuseando variáveis externas
- A extensão filter

# $php_errormsg

(PHP 4, PHP 5, PHP 7)

$php_errormsg — A mensagem de erro anterior

Aviso

Este recurso foi DESCONTINUADO a partir do PHP 7.2.0 e foi REMOVIDO a partir do PHP 8.0.0. O uso deste recurso é fortemente desencorajado.

Use error_get_last() em seu lugar.

### Descrição

$php_errormsg é uma variável contendo o texto da última mensagem de erro gerada pelo PHP. Esta variável somente estará disponível dentro do escopo no qual o erro ocorreu e somente se a opção de configuração track_errors estiver "on" (o padrão é "off").

Aviso

Se um manipulador de erro definido pelo usuário (set_error_handler()) estiver configurado, $php_errormsg somente será definida se a função retornar `false`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | A diretiva track_errors que criava a variável $php_errormsg foi removida.
7.2.0 | A diretiva track_errors que criava a variável $php_errormsg foi descontinuada.

### Exemplos

Exemplo #1 Exemplo de $php_errormsg

    <?php
    @strpos();
    echo $php_errormsg;
    ?>

O exemplo acima produzirá algo semelhante a:

    Wrong parameter count for strpos()

### Veja Também

- error_get_last() - Obtém o último erro ocorrido

# $http_response_header

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

$http_response_header — Cabeçalhos de resposta HTTP

Aviso

Este recurso foi DESCONTINUADO a partir do PHP 8.5.0. O uso deste recurso é fortemente desencorajado.

Use http_get_last_response_headers() em seu lugar.

### Descrição

O array $http_response_header é similar à função get_headers(). Ao usar o empacotador HTTP, a variável $http_response_header será populada com os cabeçalhos da resposta HTTP. $http_response_header será criada no escopo local.

### Exemplos

Exemplo #1 Exemplo de $http_response_header

    <?php
    function get_contents() {
      file_get_contents("http://example.com");
      var_dump($http_response_header); // variável é populada no escopo local
    }
    get_contents();
    var_dump($http_response_header); // uma chamada a get_contents() não popula a variável fora do escopo da função
    ?>

O exemplo acima produzirá algo semelhante a:

    array(9) {
      [0]=>
      string(15) "HTTP/1.1 200 OK"
      [1]=>
      string(35) "Date: Sat, 12 Apr 2008 17:30:38 GMT"
      [2]=>
      string(29) "Server: Apache/2.2.3 (CentOS)"
      [3]=>
      string(44) "Last-Modified: Tue, 15 Nov 2005 13:24:10 GMT"
      [4]=>
      string(27) "ETag: "280100-1b6-80bfd280""
      [5]=>
      string(20) "Accept-Ranges: bytes"
      [6]=>
      string(19) "Content-Length: 438"
      [7]=>
      string(17) "Connection: close"
      [8]=>
      string(38) "Content-Type: text/html; charset=UTF-8"
    }

    Warning: Undefined variable $http_response_header
    NULL

### Veja Também

- http_get_last_response_headers() - Recupera os últimos cabeçalhos de reposta HTTP
- http_clear_last_response_headers() - Limpa os cabeçalhos de resposta HTTP armazenados

# $argc

(PHP 4, PHP 5, PHP 7, PHP 8)

$argc — O número de argumentos passados para o script

### Descrição

Contém o número de argumentos passados para o atual script quando executando através da linha de comando.

> Nota: O nome do arquivo do script é sempre passado como um argumento para o script, portanto o valor mínimo de $argc é `1`.

> Nota: Esta variável não está disponível quando register_argc_argv está desabilitada.

### Exemplos

Exemplo #1 Exemplo da $argc

    <?php
    var_dump($argc);
    ?>

Quando executando o exemplo com: php script.php arg1 arg2 arg3

O exemplo acima produzirá algo semelhante a:

    int(4)

### Notas

> Nota:

> Isto também está disponível como $_SERVER['argc'].

### Veja Também

- getopt() - Obtêm opções da linha de comando
- $argv

# $argv

(PHP 4, PHP 5, PHP 7, PHP 8)

$argv — Array de argumentos passados para o script

### Descrição

Contém um array de todos argumentos passados para o script quando executando através da linha de comando.

> Nota: O primeiro argumento é sempre o nome do arquivo do script atual, portanto $argv[0] é o nome do script.

> Nota: Esta variável não está disponível quando register_argc_argv está desabilitada.

Aviso

Para testar se um script está sendo executado a partir da linha de comando, php_sapi_name() deve ser usada em vez de verificar se $argv ou $_SERVER['argv'] estão definidas.

### Exemplos

Exemplo #1 Exemplo de $argv

    <?php
    var_dump($argv);
    ?>

Quando executando o exemplo com: php script.php arg1 arg2 arg3

O exemplo acima produzirá algo semelhante a:

    array(4) {
      [0]=>
      string(10) "script.php"
      [1]=>
      string(4) "arg1"
      [2]=>
      string(4) "arg2"
      [3]=>
      string(4) "arg3"
    }

### Notas

> Nota:

> Isto também está disponível como $_SERVER['argv'].

### Veja Também

- getopt() - Obtêm opções da linha de comando
- $argc

## Índice

- Superglobais — Variáveis nativas que estão sempre disponíveis em todos escopos
- $GLOBALS — Referencia todas variáveis disponíveis no escopo global
- $_SERVER — Informação do servidor e ambiente de execução
- $_GET — Variáveis de string de consulta
- $_POST — Dados de formulário de requisições POST HTTP
- $_FILES — Variáveis de Upload de Arquivos HTTP
- $_REQUEST — Variáveis de requisição HTTP
- $_SESSION — Variáveis de sessão
- $_ENV — Variáveis de ambiente
- $_COOKIE — Cookies HTTP
- $php_errormsg — A mensagem de erro anterior
- $http_response_header — Cabeçalhos de resposta HTTP
- $argc — O número de argumentos passados para o script
- $argv — Array de argumentos passados para o script

# Exceções predefinidas

## Índice

- Exception
- ErrorException
- ClosedGeneratorException
- Error
- ArgumentCountError
- ArithmeticError
- AssertionError
- DivisionByZeroError
- CompileError
- ParseError
- TypeError
- ValueError
- UnhandledMatchError
- FiberError
- RequestParseBodyException

Veja também as Exceções da SPL.

# Exception

(PHP 5, PHP 7, PHP 8)

## Introdução

Exception é a classe base para todas as exceções.

## Resumo da classe

class Exception implements Throwable {
/* Propriedades */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
public function __construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function getMessage(): string
final public function getPrevious(): ?Throwable
final public function getCode(): int
final public function getFile(): string
final public function getLine(): int
final public function getTrace(): array
final public function getTraceAsString(): string
public function __toString(): string
private function __clone(): void
}

## Propriedades

message

  A mensagem da exceção

code

  O código da exceção

file

  O nome do arquivo onde a exceção foi criada

line

  A linha onde a exceção foi criada

previous

  A exceção previamente lançada, se informada

string

  O rastreamento de pilha na forma string

trace

  O rastreamento de pilha na forma de array

# Exception::__construct

(PHP 5, PHP 7, PHP 8)

Exception::__construct — Construtor da exceção

### Descrição

public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)

Construtor de Exception.

### Parâmetros

`message`

  A mensagem da exceção.

`code`

  O código da exceção.

`previous`

  A exceção anterior, para o encadeamento de exceções.

> Nota: Chamar o construtor da classe Exception de uma classe herdada faz ignorar os argumentos padrão, caso as propriedades $code e $message já estiverem configuradas.

### Notas

> Nota:

> A `message` NÃO é binary safe.

# Exception::getMessage

(PHP 5, PHP 7, PHP 8)

Exception::getMessage — Obtém a mensagem da exceção

### Descrição

final public function Exception::getMessage(): string

Retorna a mensagem da exceção.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a mensagem da exceção como uma string.

### Exemplos

Exemplo #1 Exemplo da Exception::getMessage()

    <?php
    try {
        throw new Exception("Alguma mensagem de erro.");
    } catch(Exception $e) {
        echo $e->getMessage();
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Alguma mensagem de erro.

### Veja Também

- Throwable::getMessage() - Obtém a mensagem

# Exception::getPrevious

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Exception::getPrevious — Retorna o Throwable anterior

### Descrição

final public function Exception::getPrevious(): ?Throwable

Retorna o Throwable anterior (o terceiro valor passado no construtor Exception::__construct()).

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a Throwable anterior se disponível, ou senão `null`.

### Exemplos

Exemplo #1 Exemplo de Exception::getPrevious()

Iterando e imprimindo a pilha de erro.

    <?php
    class MyCustomException extends Exception {}

    function doStuff() {
        try {
            throw new InvalidArgumentException("Primeiro erro lançado.", 112);
        } catch(Exception $e) {
            throw new MyCustomException("Segundo erro lançado.", 911, $e);
        }
    }

    try {
        doStuff();
    } catch(Exception $e) {
        do {
            printf("%s:%d %s (%d) [%s]\n", $e->getFile(), $e->getLine(), $e->getMessage(), $e->getCode(), get_class($e));
        } while($e = $e->getPrevious());
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    /home/bjori/ex.php:8 Segundo erro lançado. (911) [MyCustomException]
    /home/bjori/ex.php:6 Primeiro erro lançado. (112) [InvalidArgumentException]

### Veja Também

- Throwable::getPrevious() - Retorna o Throwable anterior

# Exception::getCode

(PHP 5, PHP 7, PHP 8)

Exception::getCode — Obtém o código da exceção

### Descrição

final public function Exception::getCode(): int

Retorna o código da exceção.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o código da Exceção como um int da Exception mas possivelmente outros tipos descendentes de Exception (PDOException, por exemplo, retorna como string).

### Exemplos

Exemplo #1 Exemplo da Exception::getCode()

    <?php
    try {
        throw new Exception("Alguma mensagem de erro.", 30);
    } catch(Exception $e) {
        echo "O código da exceção é: " . $e->getCode();
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    O código da exceção é: 30

### Veja Também

- Throwable::getCode() - Obtém o código da exceção

# Exception::getFile

(PHP 5, PHP 7, PHP 8)

Exception::getFile — Obtém o arquivo no qual a exceção foi criada

### Descrição

final public function Exception::getFile(): string

Obtém o nome do arquivo de onde a exceção foi criada.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o nome do arquivo no qual a exceção foi criada.

### Exemplos

Exemplo #1 Exemplo da Exception::getFile()

    <?php
    try {
        throw new Exception;
    } catch(Exception $e) {
        echo $e->getFile();
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    /home/bjori/tmp/ex.php

### Veja Também

- Throwable::getFile() - Obtém o arquivo no qual o objeto foi criado

# Exception::getLine

(PHP 5, PHP 7, PHP 8)

Exception::getLine — Obtém a linha na qual a exceção foi criada

### Descrição

final public function Exception::getLine(): int

Retorna o número da linha onde a exceção foi disparada.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número da linha onde a exceção foi disparada.

### Exemplos

Exemplo #1 Exemplo da Exception::getLine()

    <?php
    try {
        throw new Exception("Alguma mensagem de erro");
    } catch(Exception $e) {
        echo "A exceção foi criada na linha: " . $e->getLine();
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    A exceção foi criada na linha: 3

### Veja Também

- Throwable::getLine() - Obtém a linha na qual o objeto foi instanciado

# Exception::getTrace

(PHP 5, PHP 7, PHP 8)

Exception::getTrace — Obtém a stack trace

### Descrição

final public function Exception::getTrace(): array

Retorna a stack trace da exceção.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a stack trace da exceção como um array.

### Exemplos

Exemplo #1 Exemplo da Exception::getTrace()

    <?php
    function test() {
     throw new Exception;
    }

    try {
     test();
    } catch(Exception $e) {
     var_dump($e->getTrace());
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    array(1) {
      [0]=>
      array(4) {
        ["file"]=>
        string(22) "/home/bjori/tmp/ex.php"
        ["line"]=>
        int(7)
        ["function"]=>
        string(4) "test"
        ["args"]=>
        array(0) {
        }
      }
    }

### Veja Também

- Throwable::getTrace() - Obtém o rastreamento de pilha

# Exception::getTraceAsString

(PHP 5, PHP 7, PHP 8)

Exception::getTraceAsString — Obtém a stack trace como uma string

### Descrição

final public function Exception::getTraceAsString(): string

Retorna a stack trace da exceção como uma string.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a stack trace da exceção como uma string.

### Exemplos

Exemplo #1 Exemplo da Exception::getTraceAsString()

    <?php
    function test() {
        throw new Exception;
    }

    try {
        test();
    } catch(Exception $e) {
        echo $e->getTraceAsString();
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    #0 /home/bjori/tmp/ex.php(7): test()
    #1 {main}

### Veja Também

- Throwable::getTraceAsString() - Obtém o rastreamento de pilha como uma string

# Exception::__toString

(PHP 5, PHP 7, PHP 8)

Exception::__toString — Representação em string da exceção

### Descrição

public function Exception::__toString(): string

Retorna a representação string da exceção.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a representação string da exceção.

### Exemplos

Exemplo #1 Exemplo da Exception::__toString()

    <?php
    try {
        throw new Exception("Alguma mensagem de erro.");
    } catch(Exception $e) {
        echo $e;
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    exception 'Exception' with message 'Alguma mensagem de erro.' in /home/bjori/tmp/ex.php:3
    Stack trace:
    #0 {main}

### Veja Também

- Throwable::__toString() - Obtém uma representação em string do objeto disparado

# Exception::__clone

(PHP 5, PHP 7, PHP 8)

Exception::__clone — Clona a exceção

### Descrição

private function Exception::__clone(): void

Exceptions não podem ser clonadas, e isso resultará no lançamento de um Error.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

Exceções não são clonáveis.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Exception::__clone() não é mais final.

## Índice

- Exception::__construct — Construtor da exceção
- Exception::getMessage — Obtém a mensagem da exceção
- Exception::getPrevious — Retorna o Throwable anterior
- Exception::getCode — Obtém o código da exceção
- Exception::getFile — Obtém o arquivo no qual a exceção foi criada
- Exception::getLine — Obtém a linha na qual a exceção foi criada
- Exception::getTrace — Obtém a stack trace
- Exception::getTraceAsString — Obtém a stack trace como uma string
- Exception::__toString — Representação em string da exceção
- Exception::__clone — Clona a exceção

# ErrorException

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

## Introdução

Uma exceção Error.

## Resumo da classe

class ErrorException extends Exception {
/* Propriedades */
protected int $severity = E_ERROR;
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
public function __construct(
string `$message` = "",
int `$code` = 0,
int `$severity` = `E_ERROR`,
?string `$filename` = `null`,
?int `$line` = `null`,
?Throwable `$previous` = `null`
)
final public function getSeverity(): int
/* Métodos herdados */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Propriedades

severity

  O nível da exceção

## Exemplos

Exemplo #1 Uso da função set_error_handler() para transformar mensagens de erro em ErrorException

    <?php

    set_error_handler(function (int $errno, string $errstr, string $errfile, int $errline) {
        if (!(error_reporting() & $errno)) {
            // Este código de erro não é incluído em error_reporting.
            return;
        }

        if ($errno === E_DEPRECATED || $errno === E_USER_DEPRECATED) {
            // Não lança uma exceção para avisos de obsolescência porque avisos
            // inesperados podem quebrar a aplicação.
            return;
        }

        throw new \ErrorException($errstr, 0, $errno, $errfile, $errline);
    });

    // Desserializar dados errados emite um alerta que será convertido em um
    // ErrorException pelo manipulador.
    unserialize('broken data');

    ?>

O exemplo acima produzirá algo semelhante a:

    Fatal error: Uncaught ErrorException: unserialize(): Error at offset 0 of 11 bytes in test.php:16
    Stack trace:
    #0 [internal function]: {closure}(2, 'unserialize(): ...', 'test.php', 16)
    #1 test.php(16): unserialize('broken data')
    #2 {main}
      thrown in test.php on line 16

# ErrorException::__construct

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ErrorException::__construct — Constrói a exceção

### Descrição

public function ErrorException::__construct(
string `$message` = "",
int `$code` = 0,
int `$severity` = `E_ERROR`,
?string `$filename` = `null`,
?int `$line` = `null`,
?Throwable `$previous` = `null`
)

Construtor da Exception.

### Parâmetros

`message`

  A mensagem da exceção.

`code`

  O código da exceção.

`severity`

  A severidade da exceção.

  > Nota:

  > Como a severidade da seção pode ser qualquer valor int, é desejado que as constantes de erro sejam utilizadas.

`filename`

  O nome do arquivo onde a exceção é disparada.

`line`

  A número da linha onde a exceção é disparada.

`previous`

  A exceção anterior, usada para encadeamento de exceções.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `filename` e `line` agora podem ser null. Anteriormente seus padrões eram `__FILE__` e `__LINE__`, respectivamente.

# ErrorException::getSeverity

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ErrorException::getSeverity — Obtém o nível da exceção

### Descrição

final public function ErrorException::getSeverity(): int

Retorna o nível da exceção.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o nível da exceção.

### Exemplos

Exemplo #1 Exemplo do método ErrorException::getSeverity()

    <?php
    try {
        throw new ErrorException("Exception message", 0, E_USER_ERROR);
    } catch(ErrorException $e) {
        echo "A severidade desta exceção é: " . $e->getSeverity();
        var_dump($e->getSeverity() === E_USER_ERROR);
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    A severidade desta exceção é: 256
    bool(true)

## Índice

- ErrorException::__construct — Constrói a exceção
- ErrorException::getSeverity — Obtém o nível da exceção

# A classe ClosedGeneratorException

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introdução

Uma exceção ClosedGeneratorException é lançada ao se tentar obter um valor de um Generator fechado.

## Resumo da classe

class ClosedGeneratorException extends Exception {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Error

(PHP 7, PHP 8)

## Introdução

Error é a classe base para todas as exceções de erros internos do PHP.

## Resumo da classe

class Error implements Throwable {
/* Propriedades */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
public function __construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function getMessage(): string
final public function getPrevious(): ?Throwable
final public function getCode(): int
final public function getFile(): string
final public function getLine(): int
final public function getTrace(): array
final public function getTraceAsString(): string
public function __toString(): string
private function __clone(): void
}

## Propriedades

message

  A mensagem de erro

code

  O código do erro

file

  O nome do arquivo onde o erro aconteceu

line

  A linha onde o erro aconteceu

previous

  A exceção anteriormente lançada

string

  Uma representação string do stack trace

trace

  O stack trace no formato array

# Error::__construct

(PHP 7, PHP 8)

Error::__construct — Constrói o objeto error

### Descrição

public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)

Constrói um erro.

### Parâmetros

`message`

  A mensagem de erro.

`code`

  O código do erro.

`previous`

  O throwable anterior, utilizado para o encadeamento de exceção.

### Notas

> Nota:

> O parâmetro `message` NÃO é binary safe.

# Error::getMessage

(PHP 7, PHP 8)

Error::getMessage — Recupera a mensagem de erro

### Descrição

final public function Error::getMessage(): string

Recupera a mensagem de erro.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Recupera a mensagem de erro como uma string.

### Exemplos

Exemplo #1 Exemplo do método Error::getMessage()

    <?php
    try {
        throw new Error("Mensagem de erro");
    } catch(Error $e) {
        echo $e->getMessage();
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Mensagem de erro

### Veja Também

- Throwable::getMessage() - Obtém a mensagem

# Error::getPrevious

(PHP 7, PHP 8)

Error::getPrevious — Retorna o último Throwable

### Descrição

final public function Error::getPrevious(): ?Throwable

Retorna Throwable anterior (o terceiro parâmetro do Error::__construct()).

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna Throwable anterior, se disponível, ou `null`.

### Exemplos

Exemplo #1 Exemplo do método Error::getPrevious()

Iterando e imprimindo a pilha de erro.

    <?php
    class MyCustomError extends Error {}

    function doStuff() {
        try {
            throw new InvalidArgumentError("Um erro!", 112);
        } catch(Error $e) {
            throw new MyCustomError("Algo aconteceu.", 911, $e);
        }
    }

    try {
        doStuff();
    } catch(Error $e) {
        do {
            printf("%s:%d %s (%d) [%s]\n", $e->getFile(), $e->getLine(), $e->getMessage(), $e->getCode(), get_class($e));
        } while($e = $e->getPrevious());
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    /home/bjori/ex.php:8 Algo aconteceu. (911) [MyCustomError]
    /home/bjori/ex.php:6 Um erro! (112) [InvalidArgumentError]

### Veja Também

- Throwable::getPrevious() - Retorna o Throwable anterior

# Error::getCode

(PHP 7, PHP 8)

Error::getCode — Recupera o código do erro

### Descrição

final public function Error::getCode(): int

Retorna o código do erro.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o código do erro como um int

### Exemplos

Exemplo #1 Exemplo do método Error::getCode()

    <?php
    try {
        throw new Error("Mensagem de erro", 30);
    } catch(Error $e) {
        echo "O código do erro é: " . $e->getCode();
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    O código do erro é: 30

### Veja Também

- Throwable::getCode() - Obtém o código da exceção

# Error::getFile

(PHP 7, PHP 8)

Error::getFile — Recupera o nome do arquivo onde o erro ocorreu

### Descrição

final public function Error::getFile(): string

Recupera o nome do arquivo onde o erro ocorreu.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o nome do arquivo onde o erro ocorreu.

### Exemplos

Exemplo #1 Exemplo do método Error::getFile()

    <?php
    try {
        throw new Error;
    } catch(Error $e) {
        echo $e->getFile();
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    /home/bjori/tmp/ex.php

### Veja Também

- Throwable::getFile() - Obtém o arquivo no qual o objeto foi criado

# Error::getLine

(PHP 7, PHP 8)

Error::getLine — Recupera a linha onde o erro ocorreu

### Descrição

final public function Error::getLine(): int

Recupera o número da linha onde o erro ocorreu.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número da linha onde o erro ocorreu.

### Exemplos

Exemplo #1 Exemplo do método Error::getLine()

    <?php
    try {
        throw new Error("Mensagem de erro");
    } catch(Error $e) {
        echo "O erro foi criado na linha: " . $e->getLine();
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    O erro foi criado na linha: 3

### Veja Também

- Throwable::getLine() - Obtém a linha na qual o objeto foi instanciado

# Error::getTrace

(PHP 7, PHP 8)

Error::getTrace — Recupera a pilha de rastreio

### Descrição

final public function Error::getTrace(): array

Recupera a pilha de rastreio.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Recupera a pilha de rastreio como um array.

### Exemplos

Exemplo #1 Exemplo do método Error::getTrace()

    <?php
    function test() {
     throw new Error;
    }

    try {
     test();
    } catch(Error $e) {
     var_dump($e->getTrace());
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    array(1) {
      [0]=>
      array(4) {
        ["file"]=>
        string(22) "/home/bjori/tmp/ex.php"
        ["line"]=>
        int(7)
        ["function"]=>
        string(4) "test"
        ["args"]=>
        array(0) {
        }
      }
    }

### Veja Também

- Throwable::getTrace() - Obtém o rastreamento de pilha

# Error::getTraceAsString

(PHP 7, PHP 8)

Error::getTraceAsString — Recupera a pilha de rastreio como uma string

### Descrição

final public function Error::getTraceAsString(): string

Recupera a pilha de rastreio como uma string.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Recupera a pilha de rastreio como uma string.

### Exemplos

Exemplo #1 Exemplo do método Error::getTraceAsString()

    <?php
    function test() {
        throw new Error;
    }

    try {
        test();
    } catch(Error $e) {
        echo $e->getTraceAsString();
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    #0 /home/bjori/tmp/ex.php(7): test()
    #1 {main}

### Veja Também

- Throwable::getTraceAsString() - Obtém o rastreamento de pilha como uma string

# Error::__toString

(PHP 7, PHP 8)

Error::__toString — Representação em string do erro

### Descrição

public function Error::__toString(): string

Retorna a representação em string do erro.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a representação do erro em string.

### Exemplos

Exemplo #1 Exemplo do método Error::__toString()

    <?php
    try {
        throw new Error("Mensagem de erro.");
    } catch(Error $e) {
        echo $e;
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Error: Mensagem de erro. in /home/bjori/tmp/ex.php:3
    Stack trace:
    #0 {main}

### Veja Também

- Throwable::__toString() - Obtém uma representação em string do objeto disparado

# Error::__clone

(PHP 7, PHP 8)

Error::__clone — Clona o erro

### Descrição

private function Error::__clone(): void

Error não pode ser clonada, então o método resulta em um erro fatal.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

Erros não podem ser clonados.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Error::__clone() não é mais final.

## Índice

- Error::__construct — Constrói o objeto error
- Error::getMessage — Recupera a mensagem de erro
- Error::getPrevious — Retorna o último Throwable
- Error::getCode — Recupera o código do erro
- Error::getFile — Recupera o nome do arquivo onde o erro ocorreu
- Error::getLine — Recupera a linha onde o erro ocorreu
- Error::getTrace — Recupera a pilha de rastreio
- Error::getTraceAsString — Recupera a pilha de rastreio como uma string
- Error::__toString — Representação em string do erro
- Error::__clone — Clona o erro

# ArgumentCountError

(PHP 7 >= PHP 7.1.0, PHP 8)

## Introdução

ArgumentCountError é disparado quando parâmetros insuficientes são passados para uma função ou método definidos pelo usuário.

Este erro também é disparado quando argumentos demais são passados para uma função interna não variável.

## Resumo da classe

class ArgumentCountError extends TypeError {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# ArithmeticError

(PHP 7, PHP 8)

## Introdução

ArithmeticError é lançado quando um erro ocorre ao executar operações matemáticas. Esses erros incluem a tentativa de executar um deslocamento de bits por uma quantidade negativa, e qualquer chamada para a função intdiv() que resultaria num valor fora dos possíveis limites para um tipo int.

## Resumo da classe

class ArithmeticError extends Error {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# AssertionError

(PHP 7, PHP 8)

## Introdução

AssertionError é lançada quando uma afirmação feita por meio da função assert() falha.

## Resumo da classe

class AssertionError extends Error {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# DivisionByZeroError

(PHP 7, PHP 8)

## Introdução

DivisionByZeroError é lançada quando uma tentativa de dividir um número por zero é feita.

## Resumo da classe

class DivisionByZeroError extends ArithmeticError {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# CompileError

(PHP 7 > 7.3.0, PHP 8)

## Introdução

CompileError é disparado para alguns erros de compilação, que anteriormente emitiam um erro fatal.

## Resumo da classe

class CompileError extends Error {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# ParseError

(PHP 7, PHP 8)

## Introdução

ParseError é lançado quando um erro ocorre na interpretação do código PHP, como quando a função eval() é chamada.

> Nota: ParseError estende CompileError a partir do PHP 7.3.0. Anteriormente estendia de Error.

## Resumo da classe

class ParseError extends CompileError {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# TypeError

(PHP 7, PHP 8)

## Introdução

Um TypeError pode ser lançado quando:

- Um valor sendo informado em uma propriedade de classe que não corresponde com o tipo declarado.
- O tipo do argumento que é passado para uma função que não coincide com o tipo declarado para parâmetro.
- Um valor sendo retornado de uma função que não coincide com o tipo declarado da função.

## Resumo da classe

class TypeError extends Error {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

## Registro de Alterações

Versão | Descrição
--- | ---
7.1.0 | Em modo estrito, passar um número incorreto de argumentos para uma função interna do PHP não resulta mais em um TypeError genérico. Em vez disso, é lançado um ArgumentCountError mais específico, que estende TypeError.

# ValueError

(PHP 8)

## Introdução

ValueError é disparado quando o tipo de um argumento está correto mas o seu valor está incorreto. Por exemplo, ao passar um inteiro negativo quando a função espera um positivo, ou ao passar uma string ou array vazio quando a função espera que não seja vazio.

## Resumo da classe

class ValueError extends Error {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# UnhandledMatchError

(PHP 8)

## Introdução

Um UnhandledMatchError é lançado quando o sujeito passado para uma expressão match não é tratado por nenhum braço da expressão match.

## Resumo da classe

class UnhandledMatchError extends Error {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# FiberError

(PHP 8 >= 8.1.0)

## Introdução

FiberError é disparada quando uma operação inválida é realizada em uma Fiber.

## Resumo da classe

final class FiberError extends Error {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
public function __construct()
/* Métodos herdados */
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# FiberError::__construct

(PHP 8 >= 8.1.0)

FiberError::__construct — Construtor para não permitir instanciação direta

### Descrição

public function FiberError::__construct()

### Parâmetros

Esta função não possui parâmetros.

### Erros/Exceções

Dispara uma exceção Error quando chamada.

## Índice

- FiberError::__construct — Construtor para não permitir instanciação direta

# RequestParseBodyException

(PHP 8 >= 8.4.0)

## Introdução

Uma exceção RequestParseBodyException é lançada na função request_parse_body() quando o corpo da requisição é inválido, de acordo com o cabeçalho `Content-Type`.

## Resumo da classe

class RequestParseBodyException extends Exception {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Interfaces e Classes predefinidas

## Índice

- Traversable
- Iterator
- IteratorAggregate
- InternalIterator
- Throwable
- Countable
- ArrayAccess
- Serializable
- Closure
- stdClass
- Generator
- Fiber
- WeakReference
- WeakMap
- Stringable
- UnitEnum
- BackedEnum
- SensitiveParameterValue
- __PHP_Incomplete_Class

Veja também as Interfaces SPL e classes reservadas.

# A interface Traversable

(PHP 5, PHP 7, PHP 8)

## Introdução

Interface para detectar se uma classe é percorrível utilizando o `foreach`.

Interface básica abstrata que não pode ser implementada sozinha. Ao invés, deve ser implementada as interfaces IteratorAggregate ou Iterator.

## Resumo da Interface

interface Traversable {
}

Esta interface não possui métodos, seu único propósito é servir como interface base para todas as classes percorríveis.

## Registro de Alterações

Versão | Descrição
--- | ---
7.4.0 | A interface Traversable agora pode ser implementada em classes abstratas. Classes estendidas precisam implementar Iterator ou IteratorAggregate.

## Notas

> Nota:

> Classes internas (built-in) que implementam essa interface podem ser utilizadas em um construtor de linguagem `foreach` e não precisam implementar as interfaces IteratorAggregate ou Iterator.

> Nota:

> Anteriormente ao PHP 7.4.0, esta funcionalidade interna não podia ser implementada em scripts PHP. Ou IteratorAggregate ou Iterator precisavam ser utilizados.

# A interface Iterator

(PHP 5, PHP 7, PHP 8)

## Introdução

Interface para iteradores externos ou objetos poderem ser iterados por eles mesmos internamente.

## Resumo da Interface

interface Iterator extends Traversable {
/* Métodos */
public function current(): mixed
public function key(): mixed
public function next(): void
public function rewind(): void
public function valid(): bool
}

## Iterators predefinidos

O PHP já possui diversos iteradores para muitas das tarefas do dia a dia. Veja iteradores SPL para uma lista.

## Exemplos

Exemplo #1 Utilização básica

Este exemplo demonstra em qual ordem os métodos são chamados quando estiver usando um `foreach` em um iterador.

    <?php
    class myIterator implements Iterator {
        private $position = 0;
        private $array = array(
            "firstelement",
            "secondelement",
            "lastelement",
        );

        public function __construct() {
            $this->position = 0;
        }

        public function rewind(): void {
            var_dump(__METHOD__);
            $this->position = 0;
        }

        #[\ReturnTypeWillChange]
        public function current() {
            var_dump(__METHOD__);
            return $this->array[$this->position];
        }

        #[\ReturnTypeWillChange]
        public function key() {
            var_dump(__METHOD__);
            return $this->position;
        }

        public function next(): void {
            var_dump(__METHOD__);
            ++$this->position;
        }

        public function valid(): bool {
            var_dump(__METHOD__);
            return isset($this->array[$this->position]);
        }
    }

    $it = new myIterator;

    foreach($it as $key => $value) {
        var_dump($key, $value);
        echo "\n";
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    string(18) "myIterator::rewind"
    string(17) "myIterator::valid"
    string(19) "myIterator::current"
    string(15) "myIterator::key"
    int(0)
    string(12) "firstelement"

    string(16) "myIterator::next"
    string(17) "myIterator::valid"
    string(19) "myIterator::current"
    string(15) "myIterator::key"
    int(1)
    string(13) "secondelement"

    string(16) "myIterator::next"
    string(17) "myIterator::valid"
    string(19) "myIterator::current"
    string(15) "myIterator::key"
    int(2)
    string(11) "lastelement"

    string(16) "myIterator::next"
    string(17) "myIterator::valid"

## Veja Também

Veja também a iteração em objetos.

# Iterator::current

(PHP 5, PHP 7, PHP 8)

Iterator::current — Retorna o elemento atual

### Descrição

public function Iterator::current(): mixed

Retorna o elemento atual.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Pode retornar qualquer tipo.

# Iterator::key

(PHP 5, PHP 7, PHP 8)

Iterator::key — Retorna a chave do elemento atual

### Descrição

public function Iterator::key(): mixed

Retorna a chave do elemento atual.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorta um scalar em caso de sucesso, ou `null` em caso de falha.

### Erros/Exceções

Emite `E_NOTICE` em caso de falha.

# Iterator::next

(PHP 5, PHP 7, PHP 8)

Iterator::next — Move para o próximo elemento

### Descrição

public function Iterator::next(): void

Move a posição atual para o próximo elemento.

> Nota:

> Este método é chamado após cada loop `foreach`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Qualquer valor retornado é ignorado.

# Iterator::rewind

(PHP 5, PHP 7, PHP 8)

Iterator::rewind — Retrocede o Iterator para o primeiro elemento

### Descrição

public function Iterator::rewind(): void

Retrocede para o primeiro elemento do Iterator.

> Nota:

> Este é o primeiro método chamado quando se inicia um loop `foreach`. Ele não será executado depois de laços `foreach`.

> Como o `foreach` sempre chama rewind() antes de iniciar uma iteração, o avanço manual (por exemplo através de SplFileObject::seek()) irá reiniciar o iterador. Para iterar sem retroceder o iterador, encapsule-o em um NoRewindIterator.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Qualquer valor retornado é ignorado.

# Iterator::valid

(PHP 5, PHP 7, PHP 8)

Iterator::valid — Verifica se a posição atual é válida

### Descrição

public function Iterator::valid(): bool

Este método é chamado após Iterator::rewind() e Iterator::next() para verificar se a posição atual é válida.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O valor retornado será convertido para bool e então avaliado. Retorna `true` em caso de sucesso ou `false` em caso de falha.

## Índice

- Iterator::current — Retorna o elemento atual
- Iterator::key — Retorna a chave do elemento atual
- Iterator::next — Move para o próximo elemento
- Iterator::rewind — Retrocede o Iterator para o primeiro elemento
- Iterator::valid — Verifica se a posição atual é válida

# A interface IteratorAggregate

(PHP 5, PHP 7, PHP 8)

## Introdução

Interface para criar um iterador externo.

## Resumo da Interface

interface IteratorAggregate extends Traversable {
/* Métodos */
public function getIterator(): Traversable
}

## Exemplos

Exemplo #1 Uso básico

    <?php

    class myData implements IteratorAggregate
    {
        public function getIterator(): Traversable
        {
            return new ArrayIterator([
                "key one" => "item one",
                "key two" => "item two",
                "key three" => "item three"
            ]);
        }
    }

    $obj = new myData();

    foreach ($obj as $key => $value) {
        var_dump($key, $value);
        echo "\n";
    }

O exemplo acima produzirá algo semelhante a:

    string(7) "key one"
    string(8) "item one"

    string(7) "key two"
    string(8) "item two"

    string(9) "key three"
    string(10) "item three"

# IteratorAggregate::getIterator

(PHP 5, PHP 7, PHP 8)

IteratorAggregate::getIterator — Recupera um iterador ou Traversable externo

### Descrição

public function IteratorAggregate::getIterator(): Traversable

Retorna um iterador ou Traversable externo.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Uma instância de um objeto que implementa Iterator ou Traversable

### Erros/Exceções

Lança uma Exception em caso de falha.

## Índice

- IteratorAggregate::getIterator — Recupera um iterador ou Traversable externo

# A classe InternalIterator

(PHP 8)

## Introdução

Classe para facilitar a implementação de IteratorAggregate para classes internas.

## Resumo da classe

final class InternalIterator implements Iterator {
/* Métodos */
private function __construct()
public function current(): mixed
public function key(): mixed
public function next(): void
public function rewind(): void
public function valid(): bool
}

# InternalIterator::__construct

(PHP 8)

InternalIterator::__construct — Construtor privado para não permitir instanciação direta

### Descrição

private function InternalIterator::__construct()

### Parâmetros

Esta função não possui parâmetros.

# InternalIterator::current

(PHP 8)

InternalIterator::current — Retorna o elemento atual

### Descrição

public function InternalIterator::current(): mixed

Retorna o elemento atual.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o elemento atual.

# InternalIterator::key

(PHP 8)

InternalIterator::key — Retorna a chave do elemento atual

### Descrição

public function InternalIterator::key(): mixed

Retorna a chave do elemento atual.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a chave do elemento atual.

# InternalIterator::next

(PHP 8)

InternalIterator::next — Move para o próximo elemento

### Descrição

public function InternalIterator::next(): void

Move a posição atual para o próximo elemento.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

# InternalIterator::rewind

(PHP 8)

InternalIterator::rewind — Retrocede o Iterator para o primeiro elemento

### Descrição

public function InternalIterator::rewind(): void

Retrocede para o primeiro elemento do Iterator.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

# InternalIterator::valid

(PHP 8)

InternalIterator::valid — Verifica se a posição atual é válida

### Descrição

public function InternalIterator::valid(): bool

Verifica se a posição atual é válida.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna verdadeiro se a posição atual é válida, falso se inválida.

## Índice

- InternalIterator::__construct — Construtor privado para não permitir instanciação direta
- InternalIterator::current — Retorna o elemento atual
- InternalIterator::key — Retorna a chave do elemento atual
- InternalIterator::next — Move para o próximo elemento
- InternalIterator::rewind — Retrocede o Iterator para o primeiro elemento
- InternalIterator::valid — Verifica se a posição atual é válida

# A classe Throwable

(PHP 7, PHP 8)

## Introdução

Throwable é a interface base para qualquer objeto lançável usando a declaração `throw`, incluindo as classes Error e Exception.

> Nota:

> As classes do PHP não podem implementar a interface Throwable diretamente, e devem, ao invés, estender a classe Exception.

## Resumo da Interface

interface Throwable extends Stringable {
/* Métodos */
public function getMessage(): string
public function getCode(): int
public function getFile(): string
public function getLine(): int
public function getTrace(): array
public function getTraceAsString(): string
public function getPrevious(): ?Throwable
public function __toString(): string
/* Métodos herdados */
public function Stringable::__toString(): string
}

## Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Throwable implementa a interface Stringable.

# Throwable::getMessage

(PHP 7, PHP 8)

Throwable::getMessage — Obtém a mensagem

### Descrição

public function Throwable::getMessage(): string

Retorna a mensagem associada com o objeto disparado.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a mensagem associada com o objeto disparado.

### Veja Também

- Exception::getMessage() - Obtém a mensagem da exceção

# Throwable::getCode

(PHP 7, PHP 8)

Throwable::getCode — Obtém o código da exceção

### Descrição

public function Throwable::getCode(): int

Retorna o código de erro associado com o objeto de exceção disparado.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o código de exceção como int na classe Exception mas possivelmente como outro tipo em descendentes de Exception (por exemplo como string em PDOException).

### Veja Também

- Exception::getCode() - Obtém o código da exceção

# Throwable::getFile

(PHP 7, PHP 8)

Throwable::getFile — Obtém o arquivo no qual o objeto foi criado

### Descrição

public function Throwable::getFile(): string

Obtém o nome do arquivo no qual o objeto disparado foi criado.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Obtém o nome do arquivo no qual o objeto disparado foi criado.

### Veja Também

- Exception::getFile() - Obtém o arquivo no qual a exceção foi criada

# Throwable::getLine

(PHP 7, PHP 8)

Throwable::getLine — Obtém a linha na qual o objeto foi instanciado

### Descrição

public function Throwable::getLine(): int

Retorna o número da linha onde o objeto disparado foi instanciado.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número da linha onde o objeto disparado foi instanciado.

### Veja Também

- Exception::getLine() - Obtém a linha na qual a exceção foi criada

# Throwable::getTrace

(PHP 7, PHP 8)

Throwable::getTrace — Obtém o rastreamento de pilha

### Descrição

public function Throwable::getTrace(): array

Obtém o rastreamento de pilha como um array.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o rastreamento de pilha como um array no mesmo formato de debug_backtrace().

### Veja Também

- Exception::getTrace() - Obtém a stack trace

# Throwable::getTraceAsString

(PHP 7, PHP 8)

Throwable::getTraceAsString — Obtém o rastreamento de pilha como uma string

### Descrição

public function Throwable::getTraceAsString(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o rastreamento de pilha como uma string.

### Veja Também

- Exception::getTraceAsString() - Obtém a stack trace como uma string

# Throwable::getPrevious

(PHP 7, PHP 8)

Throwable::getPrevious — Retorna o Throwable anterior

### Descrição

public function Throwable::getPrevious(): ?Throwable

Retorna qualquer Throwable anterior (por exemplo, aquele fornecido como o terceiro parâmetro para Exception::__construct()).

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o Throwable anterior se disponível, ou `null` caso contrário.

### Veja Também

- Exception::getPrevious() - Retorna o Throwable anterior

# Throwable::__toString

(PHP 7, PHP 8)

Throwable::__toString — Obtém uma representação em string do objeto disparado

### Descrição

public function Throwable::__toString(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a representação em string do objeto disparado.

### Veja Também

- Exception::__toString() - Representação em string da exceção

## Índice

- Throwable::getMessage — Obtém a mensagem
- Throwable::getCode — Obtém o código da exceção
- Throwable::getFile — Obtém o arquivo no qual o objeto foi criado
- Throwable::getLine — Obtém a linha na qual o objeto foi instanciado
- Throwable::getTrace — Obtém o rastreamento de pilha
- Throwable::getTraceAsString — Obtém o rastreamento de pilha como uma string
- Throwable::getPrevious — Retorna o Throwable anterior
- Throwable::__toString — Obtém uma representação em string do objeto disparado

# A interface Countable

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

## Introdução

Classes que implementam Countable podem ser usadas com a função count().

## Resumo da Interface

interface Countable {
/* Métodos */
public function count(): int
}

# Countable::count

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Countable::count — Conta elementos de um objeto

### Descrição

public function Countable::count(): int

Este método é executado quando o parâmetro `value` para a função count() é um objeto que implementa Countable.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O número personalizado como um int.

### Exemplos

Exemplo #1 Exemplo de Countable::count()

    <?php

    class Counter implements Countable
    {
        private $count = 0;

        public function count(): int
        {
            return ++$this->count;
        }
    }

    $counter = new Counter();

    for ($i = 0; $i < 10; ++$i) {
        echo "Eu fui contado " . count($counter) . " vezes\n";
    }

    ?>

O exemplo acima produzirá algo semelhante a:

    Eu fui contado 1 vezes
    Eu fui contado 2 vezes
    Eu fui contado 3 vezes
    Eu fui contado 4 vezes
    Eu fui contado 5 vezes
    Eu fui contado 6 vezes
    Eu fui contado 7 vezes
    Eu fui contado 8 vezes
    Eu fui contado 9 vezes
    Eu fui contado 10 vezes

## Índice

- Countable::count — Conta elementos de um objeto

# A interface ArrayAccess

(PHP 5, PHP 7, PHP 8)

## Introdução

Interface que provê o acesso a objetos como se fossem arrays.

## Resumo da Interface

interface ArrayAccess {
/* Métodos */
public function offsetExists(mixed `$offset`): bool
public function offsetGet(mixed `$offset`): mixed
public function offsetSet(mixed `$offset`, mixed `$value`): void
public function offsetUnset(mixed `$offset`): void
}

## Exemplos

Exemplo #1 Utilização básica

    <?php
    class Obj implements ArrayAccess {
        public $container = [
            "one"   => 1,
            "two"   => 2,
            "three" => 3,
        ];

        public function offsetSet($offset, $value): void {
            if (is_null($offset)) {
                $this->container[] = $value;
            } else {
                $this->container[$offset] = $value;
            }
        }

        public function offsetExists($offset): bool {
            return isset($this->container[$offset]);
        }

        public function offsetUnset($offset): void {
            unset($this->container[$offset]);
        }

        public function offsetGet($offset): mixed {
            return isset($this->container[$offset]) ? $this->container[$offset] : null;
        }
    }

    $obj = new Obj;

    var_dump(isset($obj["two"]));
    var_dump($obj["two"]);
    unset($obj["two"]);
    var_dump(isset($obj["two"]));
    $obj["two"] = "A value";
    var_dump($obj["two"]);
    $obj[] = 'Append 1';
    $obj[] = 'Append 2';
    $obj[] = 'Append 3';
    print_r($obj);

O exemplo acima produzirá algo semelhante a:

    bool(true)
    int(2)
    bool(false)
    string(7) "A value"
    Obj Object
    (
        [container] => Array
            (
                [one] => 1
                [three] => 3
                [two] => A value
                [0] => Append 1
                [1] => Append 2
                [2] => Append 3
            )

    )

# ArrayAccess::offsetExists

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetExists — Verifica se uma posição existe

### Descrição

public function ArrayAccess::offsetExists(mixed `$offset`): bool

Verifica se uma posição existe ou não.

Este método é executado ao utilizar-se a função isset() ou empty() em objetos que implementem ArrayAccess.

> Nota:

> Ao utilizar a função empty(), o método ArrayAccess::offsetGet() será chamado e checado por vazio somente se o método ArrayAccess::offsetExists() retornar `true`

### Parâmetros

`offset`

  Uma posição a ser checada.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

> Nota:

> O valor de retorno será convertido para bool se um não booleano for retornado.

### Exemplos

Exemplo #1 Exemplo do método ArrayAccess::offsetExists()

    <?php
    class obj implements ArrayAccess {
        public function offsetSet($offset, $value): void {
            var_dump(__METHOD__);
        }
        public function offsetExists($var): bool {
            var_dump(__METHOD__);
            if ($var == "foobar") {
                return true;
            }
            return false;
        }
        public function offsetUnset($var): void {
            var_dump(__METHOD__);
        }
        #[\ReturnTypeWillChange]
        public function offsetGet($var) {
            var_dump(__METHOD__);
            return "value";
        }
    }

    $obj = new obj;

    echo "Executa obj::offsetExists()\n";
    var_dump(isset($obj["foobar"]));

    echo "\nExecuta obj::offsetExists() e obj::offsetGet()\n";
    var_dump(empty($obj["foobar"]));

    echo "\nExecuta obj::offsetExists(), *não executa* obj:offsetGet()\n";
    var_dump(empty($obj["foobaz"]));
    ?>

O exemplo acima produzirá algo semelhante a:

    Executa obj::offsetExists()
    string(17) "obj::offsetExists"
    bool(true)

    Executa obj::offsetExists() e obj::offsetGet()
    string(17) "obj::offsetExists"
    string(14) "obj::offsetGet"
    bool(false)

    Executa obj::offsetExists(), *não executa* obj:offsetGet()
    string(17) "obj::offsetExists"
    bool(true)

# ArrayAccess::offsetGet

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetGet — Posição a ser obtida

### Descrição

public function ArrayAccess::offsetGet(mixed `$offset`): mixed

Retorna o valor de uma posição específica.

Este método é executado ao checar se uma posição está vazia, com a função empty().

### Parâmetros

`offset`

  A posição a ser obtida.

### Valor Retornado

Pode retornar valores de qualquer tipo.

### Notas

> Nota:

> É possível para implementações deste método serem retornadas por referência. Isso modifica indiretamente a sobrecarga de dimensões do array de objetos ArrayAccess possíveis.

> Uma modificação direta é aquela que substitui completamente o valor de uma dimensão do array, como em `$obj[6] = 7`. Uma modificação indireta, por outro lado, modifica somente parte da dimensão, ou tenta atribuir a dimensão por referência a outra variável, como em `$obj[6][7] = 7` ou `$var =& $obj[6]`. Incrementos com `++` e decrementos com `--` também são implementados de forma a exigirem modificações indiretas.

> Enquanto uma modificação direta engatilha uma chamada ao método ArrayAccess::offsetSet(), uma modificação indireta engatilha uma chamada ao ArrayAccess::offsetGet(). Neste caso, a implementação do método ArrayAccess::offsetGet() deve permitir o retorno por referência, caso contrário uma mensagem `E_NOTICE` será disparada.

### Veja Também

- ArrayAccess::offsetExists() - Verifica se uma posição existe

# ArrayAccess::offsetSet

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetSet — Atribui um valor a uma posição específica

### Descrição

public function ArrayAccess::offsetSet(mixed `$offset`, mixed `$value`): void

Atribui um valor a uma posição específica.

### Parâmetros

`offset`

  A posição na qual se deseja atribuir um valor.

`value`

  O valor a ser atribuído.

### Valor Retornado

Nenhum valor é retornado.

### Notas

> Nota:

> O parâmetro `offset` será definido como `null` se outro valor não for informado, como no exemplo a seguir.

>     <?php
>     $arrayaccess[] = "first value";
>     $arrayaccess[] = "second value";
>     print_r($arrayaccess);
>     ?>

> O exemplo acima produzirá:

>     Array
>     (
>         [0] => first value
>         [1] => second value
>     )

> Nota:

> Esta função não é chamada em atribuições por referência e outras modificações indiretas as dimensões de arrays sobrecarregados com ArrayAccess (indiretas no sentido de e não serem feitas para modificar a dimensão diretamente, mas para modificar uma subdimensão ou uma subpropriedade, ou atribuir a dimensão do array por referência a outra variável). Em vez disso, o método ArrayAccess::offsetGet() será chamado. A operação será bem sucedida somente se este método retornar por referência.

# ArrayAccess::offsetUnset

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetUnset — Remove uma posição

### Descrição

public function ArrayAccess::offsetUnset(mixed `$offset`): void

Destrói uma posição.

> Nota:

> Este método não será chamado ao se fazer conversão de tipo com (unset)

### Parâmetros

`offset`

  A posição a ser removida.

### Valor Retornado

Nenhum valor é retornado.

## Índice

- ArrayAccess::offsetExists — Verifica se uma posição existe
- ArrayAccess::offsetGet — Posição a ser obtida
- ArrayAccess::offsetSet — Atribui um valor a uma posição específica
- ArrayAccess::offsetUnset — Remove uma posição

# A interface Serializable

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

## Introdução

Interface para serialização personalizada.

Classes que implementam esta interface não possuem mais suporte aos métodos __sleep() e __wakeup(). O método de serialização é chamado não importando se uma instância possui a necessidade de ser serializada. Não invoca o método __destruct(), ou possui qualquer outro efeito colateral a não ser que programado no método. Quando os dados são desserializados, a classe toma conhecimento e o método unserialize() apropriado é chamado como um construtor, em vez de chamar o método __construct(). Se for necessário executar o construtor padrão, pode-se fazer isso no método.

Aviso

A partir do PHP 8.1.0, uma classe que implementa Serializable sem implementar __serialize() e __unserialize() gerará um aviso de descontinuação.

## Resumo da Interface

interface Serializable {
/* Métodos */
public function serialize(): ?string
public function unserialize(string `$data`): void
}

## Exemplos

Exemplo #1 Uso básico

    <?php
    class obj implements Serializable {
        private $data;
        public function __construct() {
            $this->data = "My private data";
        }
        public function serialize() {
            return serialize($this->data);
        }
        public function unserialize($data) {
            $this->data = unserialize($data);
        }
        public function getData() {
            return $this->data;
        }
    }

    $obj = new obj;
    $ser = serialize($obj);

    var_dump($ser);

    $newobj = unserialize($ser);

    var_dump($newobj->getData());
    ?>

O exemplo acima produzirá algo semelhante a:

    Deprecated: obj implements the Serializable interface, which is deprecated. Implement __serialize() and __unserialize() instead (or in addition, if support for old PHP versions is necessary) in script on line 2
    string(38) "C:3:"obj":23:{s:15:"My private data";}"
    string(15) "My private data"

# Serializable::serialize

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Serializable::serialize — Representação em string de um objeto

### Descrição

public function Serializable::serialize(): ?string

Deve retornar uma representação em string do objeto.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma representação em string do objeto ou `null`.

### Erros/Exceções

Dispara uma Exception quando retorna outros tipos diferentes de string ou `null`.

### Veja Também

- __sleep()
- __serialize()

# Serializable::unserialize

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Serializable::unserialize — Constrói o objeto

### Descrição

public function Serializable::unserialize(string `$data`): void

Chamado durante a desserialização do objeto.

> Nota:

> Este método age como o construtor do objeto. O método __construct() não será chamado depois deste método.

### Parâmetros

`data`

  A representação em string do objeto.

### Valor Retornado

O valor de retorno deste método é ignorado.

### Veja Também

- __wakeup()
- __unserialize()

## Índice

- Serializable::serialize — Representação em string de um objeto
- Serializable::unserialize — Constrói o objeto

# A classe Closure

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Introdução

Classe usada para representar funções anônimas.

Funções anônimas, produzem objetos desse tipo. Esta classe possui métodos que permitem ainda mais controle de funções anônimas após sua criação.

Além dos métodos listados aqui, a classe também possui o método `__invoke`. Para consistência com outras classes que implementam o invoque mágico, já que esse método não é utilizado para chamar a função.

## Resumo da classe

final class Closure {
/* Métodos */
private function __construct()
public static function bind(Closure `$closure`, ?object `$newThis`, object|string|null `$newScope` = "static"): ?Closure
public function bindTo(?object `$newThis`, object|string|null `$newScope` = "static"): ?Closure
public function call(object `$newThis`, mixed `...$args`): mixed
public static function fromCallable(callable `$callback`): Closure
public static function getCurrent(): Closure
}

## Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | O resultado de Closure::__debugInfo() agora inclui o nome, a linha e o arquivo do closure.

## Notas

> Nota: Objetos Closure não podem ser serializados porque podem conter variáveis vinculadas e um contexto de execução específico. A tentativa de serializar lançará uma Exception.

# Closure::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Closure::__construct — Construtor que desabilita a instanciação

### Descrição

private function Closure::__construct()

Este método existe somente para desabilitar a instanciação da classe Closure. Objetos desta classe são criados como descrito na página de funções anônimas.

### Parâmetros

Esta função não possui parâmetros.

### Veja Também

- Funções anônimas

# Closure::bind

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

Closure::bind — Duplica uma closure com um objeto vinculado e um escopo de classe

### Descrição

public static function Closure::bind(Closure `$closure`, ?object `$newThis`, object|string|null `$newScope` = "static"): ?Closure

Este método é uma versão estática do Closure::bindTo(). Veja a documentação do método para mais informações.

### Parâmetros

`closure`

  A função anônima a ser vincular.

`newThis`

  O objeto que a função anônima fornecida deve vincular, ou `null` para a closure não vincular.

`newScope`

  O escopo da classe ao qual a closure deve ser informado, ou 'static' para manter o atual. Se um objeto é fornecido, o tipo do objeto será usado. Isso determina a visibilidade dos métodos protegidos e privados do objeto vinculado. Não é permitido passar uma (objeto da) classe interna como parâmetro this.

### Valor Retornado

Retorna um novo objeto Closure ou `null` em caso de falha.

### Exemplos

Exemplo #1 Exemplo do método Closure::bind()

    <?php
    class A {
        private static $sfoo = 1;
        private $ifoo = 2;
    }
    $cl1 = static function() {
        return A::$sfoo;
    };
    $cl2 = function() {
        return $this->ifoo;
    };

    $bcl1 = Closure::bind($cl1, null, 'A');
    $bcl2 = Closure::bind($cl2, new A(), 'A');
    echo $bcl1(), "\n";
    echo $bcl2(), "\n";
    ?>

O exemplo acima produzirá algo semelhante a:

    1
    2

### Veja Também

- Funções anônimas
- Closure::bindTo() - Duplica a closure com um novo objeto vinculado e escopo de classe.

# Closure::bindTo

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

Closure::bindTo — Duplica a closure com um novo objeto vinculado e escopo de classe.

### Descrição

public function Closure::bindTo(?object `$newThis`, object|string|null `$newScope` = "static"): ?Closure

Cria e retorna uma nova função anônima com o mesmo corpo e mesmas variáveis ligadas como a original, mas possivelmente com um diferente objeto ligado e um novo escopo de classe.

O “obeto ligado” determina o valor que `$this` terá no corpo da função e o “escopo de classe” representa uma classe que determina quais membros privados e protegidos a função anônima será capaz de acessar. Nomeadamente, os membros que estarão visíveis serão os mesmos que estariam, se a função anônima fosse um método da classe informada como valor do parâmetro `newScope`.

Closures estáticas não podem ter nenhum objeto ligado (o valor do parâmetro `newThis` deveria ser `null`), mas este método pode entretanto ser utilizada para alterar seus escopos de classe.

Este método vai assegurar que, para uma closure não estática, possuir uma instância ligada irá implicar em ter escopo definido e vice-versa. Para este fim, closures não estáticas que recebem um escopo com instância `null` são tornadas estáticas; e closures não estáticas sem escopo que recebem uma instância não nula têm o escopo definido para uma classe não especificada.

> Nota:

> Se for requerido duplicar as funções anônimas, pode ser utilizada clonagem alternativamente.

### Parâmetros

`newThis`

  O objeto ao qual a função anônima informada deve ser ligada, ou `null` para que a closure seja não ligada.

`newScope`

  O escopo de classe ao qual a closure deve ser associada, ou 'static' para manter a atual. Se um objeto for informado, o tipo do objeto será usado no lugar. Isto determina a visibilidade de métodos protegidos e privados do objeto ligado. Não é permitido passar (um objeto de) uma classe interna neste parâmetro.

### Valor Retornado

Retorna o novo objeto Closure criado ou `null` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de Closure::bindTo()

    <?php

    class A
    {
        private $val;

        public function __construct($val)
        {
            $this->val = $val;
        }

        public function getClosure()
        {
            // Retorna a closure ligada a este objeto e escopo
            return function() {
                return $this->val;
            };
        }
    }

    $ob1 = new A(1);
    $ob2 = new A(2);

    $cl = $ob1->getClosure();
    echo $cl(), "\n";

    $cl = $cl->bindTo($ob2);
    echo $cl(), "\n";

    ?>

O exemplo acima produzirá algo semelhante a:

    1
    2

### Veja Também

- Funções Anônimas
- Closure::bind() - Duplica uma closure com um objeto vinculado e um escopo de classe

# Closure::call

(PHP 7, PHP 8)

Closure::call — Vincula e chama a closure

### Descrição

public function Closure::call(object `$newThis`, mixed `...$args`): mixed

Vincula temporáriamente a closure ao `newThis`, e a chama com qualquer parâmetro fornecido.

### Parâmetros

`newThis`

  O object a ser vinculado a closure enquanto durar a chamada.

`args`

  Zero ou mais parâmetros, que serão fornecidos como parâmetros para a closure.

### Valor Retornado

Retorna o valor de retorno da closure.

### Exemplos

Exemplo #1 Exemplo do método Closure::call()

    <?php
    class Value {
        protected $value;

        public function __construct($value) {
            $this->value = $value;
        }

        public function getValue() {
            return $this->value;
        }
    }

    $three = new Value(3);
    $four = new Value(4);

    $closure = function ($delta) { var_dump($this->getValue() + $delta); };
    $closure->call($three, 4);
    $closure->call($four, 4);
    ?>

O exemplo acima produzirá:

    int(7)
    int(8)

# Closure::fromCallable

(PHP 7 >= 7.1.0)

Closure::fromCallable — Converte um chamável em uma closure

### Descrição

public static function Closure::fromCallable(callable `$callback`): Closure

Cria e retorna uma nova função anônima a partir do `callback` fornecido usando o escopo atual. Esse método verifica se o `callback` é chamável no escopo atual e lança um TypeError se ele não for.

> Nota:

> A partir do PHP 8.1.0, Sintaxe de chamáveis de primeira classe possui a mesma semântica que este método.

### Parâmetros

`callback`

  O chamável a ser convertido.

### Valor Retornado

Retorna a recém-criada Closure ou lança um TypeError se o `callback` não é chamável no escopo atual.

### Veja Também

- Funções anônimas
- Sintaxe de chamável de primeira classe

# Closure::getCurrent

(PHP 8 >= 8.5.0)

Closure::getCurrent — Retorna o closure em execução no momento

### Descrição

public static function Closure::getCurrent(): Closure

Retorna o closure em execução no momento. Este método é útil principalmente para implementar closures recursivos sem a necessidade de capturar uma referência à variável do closure com a palavra-chave `use`.

Este método precisa ser chamado de dentro de um closure; chamá-lo de fora de um contexto de closure resultará em um erro `Error: Current function is not a closure.`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a instância do Closure em execução.

### Erros/Exceções

Lança um Error se chamado de fora de um contexto de closure.

### Exemplos

Exemplo #1 Exemplo de Closure::getCurrent()

Usando Closure::getCurrent() para implementar uma função de Fibonacci recursiva:

    <?php
    $fibonacci = function (int $n) {
        if ($n === 0 || $n === 1) {
            return $n;
        }

        $fn = Closure::getCurrent();
        return $fn($n - 1) + $fn($n - 2);
    };

    echo $fibonacci(10); // Exibe: 55
    ?>

Exemplo #2 Comparação com método tradicional

Antes do PHP 8.5, para implementar closures recursivos era necessário capturar uma referência à variável do closure usando a palavra-chave `use`:

    <?php
    // Método tradicional (ainda funciona no PHP 8.5)
    $fibonacci = function (int $n) use (&$fibonacci) {
        if ($n === 0) return 0;
        if ($n === 1) return 1;
        return $fibonacci($n - 1) + $fibonacci($n - 2);
    };

    echo $fibonacci(10); // Exibe: 55
    ?>

O método Closure::getCurrent() elimita a necessidade de declarar a variável com uma referência na cláusula `use`, tornando o código mais limpo e menos suscetível a erros.

## Índice

- Closure::__construct — Construtor que desabilita a instanciação
- Closure::bind — Duplica uma closure com um objeto vinculado e um escopo de classe
- Closure::bindTo — Duplica a closure com um novo objeto vinculado e escopo de classe.
- Closure::call — Vincula e chama a closure
- Closure::fromCallable — Converte um chamável em uma closure
- Closure::getCurrent — Retorna o closure em execução no momento

# A classe stdClass

(PHP 4, PHP 5, PHP 7, PHP 8)

## Introdução

Uma classe vazia genérica com propriedades dinâmicas.

Objetos desta classe podem ser instaciados com o operador new ou criados por conversores de tipo para o objeto. Muitas funções do PHP também criam instâncias desta classe, ex.: json_decode(), mysqli_fetch_object() ou PDOStatement::fetchObject().

Apesar de não implementar os métodos mágicos __get()/__set(), esta classe permite propriedades dinâmicas e não requer o atributo `#[\AllowDynamicProperties]`.

Esta não é uma classe base já que o PHP não possui um conceito de uma classe base universal. Entretanto, é possível criar uma classe customizada que se estende a partir de stdClass e como resultado herda a funcionalidade de propriedades dinâmicas.

## Resumo da classe

#[\AllowDynamicProperties]
class stdClass {
}

Esta classe não tem métodos ou propriedades padrão.

## Exemplos

Exemplo #1 Criado como resultado de uma conversão de tipo em um objeto

    <?php
    $obj = (object) array('foo' => 'bar');
    var_dump($obj);

O exemplo acima produzirá:

    object(stdClass)#1 (1) {
      ["foo"]=>
      string(3) "bar"
    }

Exemplo #2 Criado como resultado da função json_decode()

    <?php
    $json = '{"foo":"bar"}';
    var_dump(json_decode($json));

O exemplo acima produzirá:

    object(stdClass)#1 (1) {
      ["foo"]=>
      string(3) "bar"
    }

Exemplo #3 Declarando propriedades dinâmicas

    <?php
    $obj = new stdClass();
    $obj->foo = 42;
    $obj->{1} = 42;
    var_dump($obj);

O exemplo acima produzirá:

    object(stdClass)#1 (2) {
      ["foo"]=>
      int(42)
      ["1"]=>
      int(42)
    }

# A classe Generator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introdução

Os objetos Generator são retornados por geradores.

Cuidado

Os objetos Generator não podem ser instanciados através do construtor new.

## Resumo da classe

final class Generator implements Iterator {
/* Métodos */
public function current(): mixed
public function getReturn(): mixed
public function key(): mixed
public function next(): void
public function rewind(): void
public function send(mixed `$value`): mixed
public function throw(Throwable `$exception`): mixed
public function valid(): bool
public function __wakeup(): void
}

## Veja Também

See also object iteration.

# Generator::current

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::current — Obtém o valor gerado

### Descrição

public function Generator::current(): mixed

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o valor gerado.

# Generator::getReturn

(PHP 7, PHP 8)

Generator::getReturn — Obtém o valor de retorno de um gerador

### Descrição

public function Generator::getReturn(): mixed

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o valor de retorno de um gerador, assim que finalizada sua execução.

### Exemplos

Exemplo #1 Exemplo do método Generator::getReturn()

    <?php

    $gen = (function() {
        yield 1;
        yield 2;

        return 3;
    })();

    foreach ($gen as $val) {
        echo $val, PHP_EOL;
    }

    echo $gen->getReturn(), PHP_EOL;

O exemplo acima produzirá:

    1
    2
    3

# Generator::key

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::key — Obtém o chave gerada

### Descrição

public function Generator::key(): mixed

Obtém a chave do valor gerado.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a chave gerada.

### Exemplos

Exemplo #1 Exemplo do método Generator::key()

    <?php

    function Gen()
    {
        yield 'key' => 'value';
    }

    $gen = Gen();

    echo "{$gen->key()} => {$gen->current()}";

O exemplo acima produzirá:

    key => value

# Generator::next

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::next — Continua a execução do gerador

### Descrição

public function Generator::next(): void

Chamar Generator::next() tem o mesmo efeito que chamar Generator::send() com o argumento `null`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

# Generator::rewind

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::rewind — Executa o gerador até o primeiro "yield" inclusive

### Descrição

public function Generator::rewind(): void

Executa o gerador até o primeiro `yield`, inclusive. Se o gerador já estiver no primeiro `yield`, nenhuma ação será tomada. Se o gerador já tiver avançado além de uma expressão `yield`, este método lançará uma Exception.

> Nota:

> Este é o primeiro método chamado ao iniciar um laço `foreach`. Ele não será executado após os laços `foreach`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de Generator::rewind()

    <?php

    function generator(): Generator
    {
        echo "Eu sou um gerador!\n";

        for ($i = 1; $i <= 3; $i++) {
            yield $i;
        }
    }

    // Inicializa o gerador
    $generator = generator();

    // Retrocede o gerador para o início da primeira expressão yield,
    // se já não estava lá
    $generator->rewind(); // Eu sou um gerador!

    // Nada acontece aqui. O gerador já está retrocedido.
    $generator->rewind(); // Sem saída (NULL)

    // Isto retrocede o gerador para a primeira expressão yield,
    // se já não estava lá, e itera sobre o gerador.
    foreach ($generator as $value) {
        // Após gerar o primeiro valor, o gerador permanece na
        // primeira expressão yield até que continue a execução e avance ao próximo yield
        echo $value, PHP_EOL; // 1

        break;
    }

    // Continua e retrocede novamente. Nenhum erro ocorre porque o gerador não avançou além do primeiro yield
    $generator->rewind();

    echo $generator->current(), PHP_EOL; // 1

    // Nenhum erro ocorre, o gerador ainda está no primeiro yield
    $generator->rewind();

    // Isto avança o gerador para a segunda expressão yield
    $generator->next();

    try {
        // Aqui uma Exception é lançada
        // porque o gerador já avançou para o segundo yield
        $generator->rewind(); // Fatal error: Uncaught Exception: Cannot rewind a generator that was already run
    } catch (Exception $e) {
        echo $e->getMessage();
    }

    ?>

O exemplo acima produzirá:

    Eu sou um gerador!
    1
    1
    Cannot rewind a generator that was already run

# Generator::send

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::send — Envia um valor ao gerador

### Descrição

public function Generator::send(mixed `$value`): mixed

Envia o valor informado ao gerador como resultado da expressão `yield` corrente e retorna a execução do gerador.

Se o gerador não estiver na expressão `yield` quando o método for chamado, primeiro será deixado avançar para a primeira expressão `yield` antes de enviar o valor. Assim como não é necessário "forçar" os geradores do PHP com uma chamada ao método Generator::next() (como é feito em Python).

### Parâmetros

`value`

  Valor a ser enviado ao gerador. Este valor será o retornado pela expressão `yield` em que o gerador estiver.

### Valor Retornado

Retorna o valor gerado.

### Exemplos

Exemplo #1 Usando o método Generator::send() para injetar valores

    <?php
    function printer() {
        echo "Valor inicial.".PHP_EOL;
        while (true) {
            $string = yield;
            echo $string.PHP_EOL;
        }
    }

    $printer = printer();
    $printer->send('Envio 1.');
    $printer->send('Envio 2.');
    ?>

O exemplo acima produzirá:

    Valor inicial.
    Envio 1.
    Envio 2.

# Generator::throw

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::throw — Lança uma exceção no gerador

### Descrição

public function Generator::throw(Throwable `$exception`): mixed

Lança uma exceção no gerador e retorna a execução do gerador. O comportamento será o mesmo como se a expressão `yield` corrente fosse substituída por uma declaração `throw $exception`.

Se o gerador já tiver sido fechado ao invocar este método, a exceção será lançada no contexto daquele que o chamou.

### Parâmetros

`exception`

  Exceção a ser lançada no gerador.

### Valor Retornado

Retorna o valor gerado.

### Exemplos

Exemplo #1 Lança uma exceção no gerador

    <?php
    function gen() {
        echo "Foo\n";
        try {
            yield;
        } catch (Exception $e) {
            echo "Exception: {$e->getMessage()}\n";
        }
        echo "Bar\n";
    }

    $gen = gen();
    $gen->rewind();
    $gen->throw(new Exception('Test'));
    ?>

O exemplo acima produzirá:

    Foo
    Exception: Test
    Bar

# Generator::valid

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::valid — Verifica se o gerador está ativo

### Descrição

public function Generator::valid(): bool

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `false` se o gerador foi fechado. Caso contrário retornará `true`.

# Generator::__wakeup

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::__wakeup — Serializa o gerador (sempre falha)

### Descrição

public function Generator::__wakeup(): void

Lança uma exceção, já que geradores não podem ser serializados.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

## Índice

- Generator::current — Obtém o valor gerado
- Generator::getReturn — Obtém o valor de retorno de um gerador
- Generator::key — Obtém o chave gerada
- Generator::next — Continua a execução do gerador
- Generator::rewind — Executa o gerador até o primeiro "yield" inclusive
- Generator::send — Envia um valor ao gerador
- Generator::throw — Lança uma exceção no gerador
- Generator::valid — Verifica se o gerador está ativo
- Generator::__wakeup — Serializa o gerador (sempre falha)

# A classe Fiber

(PHP 8 >= 8.1.0)

## Introdução

Fibers representam funções interruptíveis de pilha completa. Fibers podem ser suspensas de qualquer lugar na pilha de chamadas, pausando a execução dentro de Fiber até que ela seja retomada posteriormente.

## Resumo da classe

final class Fiber {
/* Métodos */
public function __construct(callable `$callback`)
public function start(mixed `...$args`): mixed
public function resume(mixed `$value` = `null`): mixed
public function throw(Throwable `$exception`): mixed
public function getReturn(): mixed
public function isStarted(): bool
public function isSuspended(): bool
public function isRunning(): bool
public function isTerminated(): bool
public static function suspend(mixed `$value` = `null`): mixed
public static function getCurrent(): ?Fiber
}

## Veja Também

Visão geral de Fibers

# Fiber::__construct

(PHP 8 >= 8.1.0)

Fiber::__construct — Cria uma nova instância de Fiber

### Descrição

public function Fiber::__construct(callable `$callback`)

### Parâmetros

`callback`

  O callable a ser invocado ao iniciar a Fiber. Argumentos informados a Fiber::start() serão fornecidos como argumentos ao callable informado.

# Fiber::start

(PHP 8 >= 8.1.0)

Fiber::start — Inicia execução de uma Fibra

### Descrição

public function Fiber::start(mixed `...$args`): mixed

Uma lista variável de argumentos a ser fornecida para o callable usado na construção da Fiber.

Se a Fiber já tiver sido iniciada quando este método for chamado, uma exceção FiberError será disparada.

### Parâmetros

`args`

  Os argumentos que serão utilizados na chamada ao callable fornecido ao construtor da Fiber.

### Valor Retornado

O valor fornecido à primeira chamada a Fiber::suspend() ou `null` se a Fiber retornar. Se a Fiber disparar uma exceção antes de ser suspensa, ela será disparada a partir da chamada a este método.

# Fiber::resume

(PHP 8 >= 8.1.0)

Fiber::resume — Retoma a execução de uma Fiber com um valor

### Descrição

public function Fiber::resume(mixed `$value` = `null`): mixed

Retoma a execução da Fiber usando o valor fornecido como resultado da chamada Fiber::suspend() atual.

Se a Fiber não estiver suspensa quando este método for chamado, uma exceção FiberError será disparada.

### Parâmetros

`value`

  O valor para retomar a Fiber. Este valor será o valor de retorno da chamada atual de Fiber::suspend().

### Valor Retornado

O valor fornecido para a próxima chamada de Fiber::suspend() ou `null` se a Fiber retornar. Se a Fiber disparar uma exceção antes de ser suspensa, ela será disparada a partir da chamada a este método.

# Fiber::throw

(PHP 8 >= 8.1.0)

Fiber::throw — Retoma a execução de uma Fiber com uma exceção

### Descrição

public function Fiber::throw(Throwable `$exception`): mixed

Retoma a Fiber disparando a exceção informada a partir da chamada Fiber::suspend() atual.

Se a Fiber não estiver suspensa quando este método é chamado, uma exceção FiberError será disparada.

### Parâmetros

`exception`

  A exceção a ser disparada na Fiber a partir da chamada Fiber::suspend() atual.

### Valor Retornado

O valor fornecido à próxima chamada a Fiber::suspend() ou `null` se a Fiber retornar. Se a Fiber disparar uma exceção antes de ser suspensa, ela será disparada a partir da chamada a este método.

### Exemplos

    <?php

    $fiber = new Fiber(function () {
       try {
           // Suspende execução do fiber declarando um ponto de interrupção
           Fiber::suspend();
       } catch (Throwable $e) {
           echo $e->getMessage();
       }
    });

    $fiber->start();

    // Continua a execução do fiber passando
    // a exceção a ser lançada no ponto de interrupção
    $fiber->throw(new Exception('Mensagem de uma exceção lançada no ponto de interrupção atual'));

    ?>

O exemplo acima produzirá algo semelhante a:

    Mensagem de uma exceção lançada no ponto de interrupção atual

# Fiber::getReturn

(PHP 8 >= 8.1.0)

Fiber::getReturn — Obtém o valor retornado pela Fiber

### Descrição

public function Fiber::getReturn(): mixed

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o valor retornado pela callable fornecida a Fiber::__construct(). Se a Fiber não retornar um valor, por não ter iniciado ou terminado, ou por ter disparado uma exceção, uma FiberError será disparada.

# Fiber::isStarted

(PHP 8 >= 8.1.0)

Fiber::isStarted — Determina se uma Fiber foi iniciada

### Descrição

public function Fiber::isStarted(): bool

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` apenas se a Fiber foi iniciada; caso contrário retorna `false`.

# Fiber::isSuspended

(PHP 8 >= 8.1.0)

Fiber::isSuspended — Determina se uma Fiber está suspensa

### Descrição

public function Fiber::isSuspended(): bool

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se uma Fiber está atualmente suspensa; caso contrário retorna `false`.

# Fiber::isRunning

(PHP 8 >= 8.1.0)

Fiber::isRunning — Determina se a Fiber está em execução

### Descrição

public function Fiber::isRunning(): bool

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` apenas se a Fiber estiver em execução. Um Fiber é considerado em execução após uma chamada a Fiber::start(), Fiber::resume() ou Fiber::throw() que ainda não retornaram. Retorna `false` se a Fiber não está em execução.

# Fiber::isTerminated

(PHP 8 >= 8.1.0)

Fiber::isTerminated — Determina se a Fiber terminou

### Descrição

public function Fiber::isTerminated(): bool

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` apenas após a Fiber ter terminado, ou retornando da execução ou disparando uma exceção; caso contrário retorna `false`.

# Fiber::suspend

(PHP 8 >= 8.1.0)

Fiber::suspend — Suspende a execução da Fiber atual

### Descrição

public static function Fiber::suspend(mixed `$value` = `null`): mixed

Suspende a execução da Fiber atual. O valor fornecido a este método será retornado da chamada a Fiber::start(), Fiber::resume() ou Fiber::throw() que mudou a execução para a Fiber atual.

Quando a Fiber é retomada, este método retorna o valor fornecido a Fiber::resume(). Se a Fiber é retomada usando Fiber::throw(), a exceção fornecida àquele método será disparada a partir da chamada a este método.

Se este método for chamado de fora de uma Fiber, uma exceção FiberError será disparada.

### Parâmetros

`value`

  O valor a retornar da chamada a Fiber::start(), Fiber::resume() ou Fiber::throw() que mudou a execução para a Fiber atual.

### Valor Retornado

O valor fornecido a Fiber::resume().

# Fiber::getCurrent

(PHP 8 >= 8.1.0)

Fiber::getCurrent — Obtém a instância de Fiber sendo executada no momento

### Descrição

public static function Fiber::getCurrent(): ?Fiber

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a instância de Fiber sendo executada no momento ou `null` se este método é chamado do lado de fora de uma Fiber.

## Índice

- Fiber::__construct — Cria uma nova instância de Fiber
- Fiber::start — Inicia execução de uma Fibra
- Fiber::resume — Retoma a execução de uma Fiber com um valor
- Fiber::throw — Retoma a execução de uma Fiber com uma exceção
- Fiber::getReturn — Obtém o valor retornado pela Fiber
- Fiber::isStarted — Determina se uma Fiber foi iniciada
- Fiber::isSuspended — Determina se uma Fiber está suspensa
- Fiber::isRunning — Determina se a Fiber está em execução
- Fiber::isTerminated — Determina se a Fiber terminou
- Fiber::suspend — Suspende a execução da Fiber atual
- Fiber::getCurrent — Obtém a instância de Fiber sendo executada no momento

# A classe WeakReference

(PHP 7 >= 7.4.0, PHP 8)

## Introdução

Referências fracas permitem que o programador mantenha uma referência a um objeto que não impede que o objeto seja destruído. Eles são úteis para implementar estruturas como cache. Se o objeto original tiver sido destruído, `null` será retornado ao chamar o método WeakReference::get(). O objeto original será destruído quando o refcount dele cair para zero; criar referências fracas não aumenta o `refcount` do objeto que está sendo referenciado.

WeakReferences não podem ser serializadas.

## Resumo da classe

final class WeakReference {
/* Métodos */
public function __construct()
public static function create(object `$object`): WeakReference
public function get(): ?object
}

## Exemplos de referência fraca

Exemplo #1 Uso básico de referência fraca

    <?php

    $obj = new stdClass();
    $weakref = WeakReference::create($obj);

    var_dump($weakref->get());

    unset($obj);

    var_dump($weakref->get());

    ?>

O exemplo acima produzirá algo semelhante a:

    object(stdClass)#1 (0) {
    }
    NULL

## Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | O resultado de WeakReference::__debugInfo() agora inclui o objeto referenciado ou `NULL` se a referência não for mais válida.

# WeakReference::__construct

(PHP 7 >= 7.4.0, PHP 8)

WeakReference::__construct — Construtor que desabilita a instanciação

### Descrição

public function WeakReference::__construct()

Este método existe apenas para desabilitar a instanciação da classe WeakReference. Referências fracas devem ser instanciadas com o método de fábrica WeakReference::create().

### Parâmetros

Esta função não possui parâmetros.

### Veja Também

- WeakReference::create() - Cria uma nova referência fraca

# WeakReference::create

(PHP 7 >= 7.4.0, PHP 8)

WeakReference::create — Cria uma nova referência fraca

### Descrição

public static function WeakReference::create(object `$object`): WeakReference

Cria uma nova WeakReference.

### Parâmetros

`object`

  O objeto a ser referenciado fracamente.

### Valor Retornado

Retorna um novo objeto WeakReference, ou a instância existente se já houver uma WeakReference para o mesmo objeto.

# WeakReference::get

(PHP 7 >= 7.4.0, PHP 8)

WeakReference::get — Obtém um objeto referenciado fracamente

### Descrição

public function WeakReference::get(): ?object

Obtém um objeto referenciado fracamente. Se o objeto já tiver sido destruído, retorna `null`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o object referenciado ou `null` se o objeto tiver sido destruído.

## Índice

- WeakReference::__construct — Construtor que desabilita a instanciação
- WeakReference::create — Cria uma nova referência fraca
- WeakReference::get — Obtém um objeto referenciado fracamente

# A classe WeakMap

(PHP 8)

## Introdução

Um WeakMap é um mapa (ou dicionário) que aceita objetos como chaves. Entretanto, diferentemente do objeto similar SplObjectStorage, um objeto em uma chave de um WeakMap não contribui com a contagem de referência do objeto. Isto é, se em algum ponto a única referência restante a um objeto é a chave de um WeakMap, o objeto sofrerá uma coleta de lixo e será removido do WeakMap. Seu caso de uso primário é construir caches de dados derivados de um objeto que não precisam durar mais que o objeto.

WeakMap implementa ArrayAccess, Traversable (via IteratorAggregate) e Countable, por isso na maioria dos casos pode ser usada da mesma forma que um array associativo.

## Resumo da classe

final class WeakMap implements ArrayAccess, Countable, IteratorAggregate {
/* Métodos */
public function count(): int
public function getIterator(): Iterator
public function offsetExists(object `$object`): bool
public function offsetGet(object `$object`): mixed
public function offsetSet(object `$object`, mixed `$value`): void
public function offsetUnset(object `$object`): void
}

## Exemplos

Exemplo #1 Exemplo de uso de Weakmap

    <?php
    $wm = new WeakMap();

    $o = new stdClass;

    class A {
        public function __destruct() {
            echo "Dead!\n";
        }
    }

    $wm[$o] = new A;

    var_dump(count($wm));
    echo "Unsetting...\n";
    unset($o);
    echo "Done\n";
    var_dump(count($wm));

O exemplo acima produzirá:

    int(1)
    Unsetting...
    Dead!
    Done
    int(0)

# WeakMap::count

(PHP 8)

WeakMap::count — Conta o número de entradas ativas no mapa

### Descrição

public function WeakMap::count(): int

Conta o número de entradas ativas no mapa.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número de entradas ativas no mapa.

# WeakMap::getIterator

(PHP 8)

WeakMap::getIterator — Obtém um iterador externo

### Descrição

public function WeakMap::getIterator(): Iterator

Retorna um iterador externo.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Uma instância de um objeto que implementa a classe Iterator ou Traversable

### Erros/Exceções

Dispara uma Exception em caso de falha.

# WeakMap::offsetExists

(PHP 8)

WeakMap::offsetExists — Verifica se um certo objeto está no mapa

### Descrição

public function WeakMap::offsetExists(object `$object`): bool

Verifica se o objeto informado está referenciado no mapa.

### Parâmetros

`object`

  Objeto a ser verificado.

### Valor Retornado

Retorna `true` se o objeto estiver contido no mapa, `false` caso contrário.

# WeakMap::offsetGet

(PHP 8)

WeakMap::offsetGet — Retorna o valor apontado por um certo objeto

### Descrição

public function WeakMap::offsetGet(object `$object`): mixed

Retorna o valor apontado por um certo objeto.

### Parâmetros

`object`

  Algum objeto contido como chave em um mapa.

### Valor Retornado

Retorna o valor associado ao objeto passado como argumento.

### Erros/Exceções

Lança uma exceção da classe Error em caso de falha.

# WeakMap::offsetSet

(PHP 8)

WeakMap::offsetSet — Atualiza o mapa com um novo par chave-valor

### Descrição

public function WeakMap::offsetSet(object `$object`, mixed `$value`): void

Atualiza o mapa com um novo par chave-valor. Se a chave já existia no mapa, o valor antigo é substituído pelo novo.

### Parâmetros

`object`

  O objeto que serve como chave no par de chave-valor.

`value`

  O dado arbitrário que serve como valor no par chave-valor..

### Valor Retornado

Nenhum valor é retornado.

# WeakMap::offsetUnset

(PHP 8)

WeakMap::offsetUnset — Remove uma entrada do mapa

### Descrição

public function WeakMap::offsetUnset(object `$object`): void

Remove uma entrada do mapa.

### Parâmetros

`object`

  O objeto chave a ser removido do mapa.

### Valor Retornado

Nenhum valor é retornado.

## Índice

- WeakMap::count — Conta o número de entradas ativas no mapa
- WeakMap::getIterator — Obtém um iterador externo
- WeakMap::offsetExists — Verifica se um certo objeto está no mapa
- WeakMap::offsetGet — Retorna o valor apontado por um certo objeto
- WeakMap::offsetSet — Atualiza o mapa com um novo par chave-valor
- WeakMap::offsetUnset — Remove uma entrada do mapa

# A interface Stringable

(PHP 8)

## Introdução

A interface Stringable denota uma classe que tenha um método __toString(). Diferentemente da maioria das interfaces, Stringable está implicitamente presente em qualquer classe que possua o método mágico __toString() definido, embora ela possa e deveria ser declarada explicitamente.

Seu principal valor é permitir que funções façam verificações de tipo em uniões `string|Stringable` para aceitar tanto uma string primitiva quanto um objeto que possa ser convertido para uma string.

## Resumo da Interface

interface Stringable {
/* Métodos */
public function __toString(): string
}

## Exemplos de Stringable

Exemplo #1 Uso Básico de Stringable

Este exemplo usa a promoção de propriedade do construtor.

    <?php
    class IPv4Address implements Stringable {
        public function __construct(
            private string $oct1,
            private string $oct2,
            private string $oct3,
            private string $oct4,
        ) {}

        public function __toString(): string {
            return "$this->oct1.$this->oct2.$this->oct3.$this->oct4";
        }
    }

    function showStuff(string|Stringable $value) {
        // Para um Stringable, isto irá chamar __toString() implicitamente.
        print $value;
    }

    $ip = new IPv4Address('123', '234', '42', '9');

    showStuff($ip);
    ?>

O exemplo acima produzirá algo semelhante a:

    123.234.42.9

# Stringable::__toString

(PHP 8)

Stringable::__toString — Obtém a representação em string do objeto

### Descrição

public function Stringable::__toString(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a representação em string do objeto.

### Veja Também

- __toString()

## Índice

- Stringable::__toString — Obtém a representação em string do objeto

# A interface UnitEnum

(PHP 8 >= 8.1.0)

## Introdução

A interface UnitEnum é aplicada automaticamente a todas as enumerações pelo motor do PHP. Não pode ser implementada por classes definidas pelo usuário. Enumerações não podem substituir seus métodos, já que implementações padrão são fornecidas pelo motor. Está disponível apenas para verificações de tipo.

## Resumo da Interface

interface UnitEnum {
/* Métodos */
public static function cases(): array
}

# UnitEnum::cases

(PHP 8 >= 8.1.0)

UnitEnum::cases — Gera uma lista de casos de uma enumeração

### Descrição

public static function UnitEnum::cases(): array

Este método irá retornar um array de todos os casos de uma enumeração, em ordem de declaração.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array de todos os casos definidos desta enumeração, em ordem de declaração.

### Exemplos

Exemplo #1 Uso básico

O exemplo a seguir ilustra como os casos de enumeração são retornados.

    <?php
    enum Naipe
    {
        case Copas;
        case Ouros;
        case Paus;
        case Espadas;
    }

    var_dump(Naipe::cases());

O exemplo acima produzirá:

    array(4) {
      [0]=>
      enum(Naipe::Copas)
      [1]=>
      enum(Naipe::Ouros)
      [2]=>
      enum(Naipe::Paus)
      [3]=>
      enum(Naipe::Espadas)
    }

## Índice

- UnitEnum::cases — Gera uma lista de casos de uma enumeração

# A interface BackedEnum

(PHP 8 >= 8.1.0)

## Introdução

A interface BackedEnum é aplicada automaticamente pelo motor do PHP a enumerações lastreadas. Não pode ser implementada por classes definidas pelo usuário. Enumerações não podem substituir seus métodos, já que as implementações padrões são fornecidas pelo motor. Está disponível apenas para verificações de tipo.

## Resumo da Interface

interface BackedEnum extends UnitEnum {
/* Métodos */
public static function from(int|string `$value`): static
public static function tryFrom(int|string `$value`): ?static
/* Métodos herdados */
public static function UnitEnum::cases(): array
}

# BackedEnum::from

(PHP 8 >= 8.1.0)

BackedEnum::from — Mapeia um escalar para uma instância de enumeração

### Descrição

public static function BackedEnum::from(int|string `$value`): static

O método from() traduz uma string ou um int para o caso correspondente do Enum, se houver. Se não houver caso correspondente definido, ele irá emitir um ValueError.

### Parâmetros

`value`

  O valor escalar a ser mapeado para um caso de enumeração.

### Valor Retornado

Uma instância de caso para esta enumeração.

### Exemplos

Exemplo #1 Uso Básico

O exemplo a seguir ilustra como os casos de enumeração são retornados.

    <?php
    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    $h = Suit::from('H');

    var_dump($h);

    $b = Suit::from('B');
    ?>

O exemplo acima produzirá:

    enum(Suit::Hearts)

    Fatal error: Uncaught ValueError: "B" is not a valid backing value for enum "Suit" in /file.php:15

### Veja Também

- UnitEnum::cases() - Gera uma lista de casos de uma enumeração
- BackedEnum::tryFrom() - Mapeia um escalar para uma instância de enumeração ou nulo

# BackedEnum::tryFrom

(PHP 8 >= 8.1.0)

BackedEnum::tryFrom — Mapeia um escalar para uma instância de enumeração ou nulo

### Descrição

public static function BackedEnum::tryFrom(int|string `$value`): ?static

O método tryFrom() traduz uma string ou um int para o caso correspondente do Enum, se houver. Se não houver caso correspondente definido, ele irá retornar nulo.

### Parâmetros

`value`

  O valor escalar a ser mapeado para um caso de enumeração.

### Valor Retornado

Uma instância de caso para esta enumeração, ou null se não encontrado.

### Exemplos

Exemplo #1 Uso básico

O exemplo a seguir ilustra como os casos de enumeração são retornados.

    <?php
    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    $h = Suit::tryFrom('H');

    var_dump($h);

    $b = Suit::tryFrom('B') ?? Suit::Spades;

    var_dump($b);
    ?>

O exemplo acima produzirá:

    enum(Suit::Hearts)
    enum(Suit::Spades)

### Veja Também

- UnitEnum::cases() - Gera uma lista de casos de uma enumeração
- BackedEnum::from() - Mapeia um escalar para uma instância de enumeração

## Índice

- BackedEnum::from — Mapeia um escalar para uma instância de enumeração
- BackedEnum::tryFrom — Mapeia um escalar para uma instância de enumeração ou nulo

# A classe SensitiveParameterValue

(PHP 8 >= 8.2.0)

## Introdução

A classe SensitiveParameterValue permite empacotar valores sensíveis para protegê-los de exposição acidental.

Valores de parâmetros que possuem o atributo SensitiveParameter serão automaticamente empacotados dentro de um objeto SensitiveParameterValue entre os rastreamentos de pilha.

## Resumo da classe

final class SensitiveParameterValue {
/* Propriedades */
private readonly mixed $value;
/* Métodos */
public function __construct(mixed `$value`)
public function __debugInfo(): array
public function getValue(): mixed
}

## Propriedades

value

  O valor sensível a ser protegido de exposição acidental.

# SensitiveParameterValue::__construct

(PHP 8 >= 8.2.0)

SensitiveParameterValue::__construct — Constrói um novo objeto SensitiveParameterValue

### Descrição

public function SensitiveParameterValue::__construct(mixed `$value`)

Constrói um objeto SensitiveParameterValue que contém um valor sensível.

### Parâmetros

`value`

  Um valor arbitrário que deve ser armazenado no objeto SensitiveParameterValue.

# SensitiveParameterValue::__debugInfo

(PHP 8 >= 8.2.0)

SensitiveParameterValue::__debugInfo — Protege os valores sensíveis de exposição acidental

### Descrição

public function SensitiveParameterValue::__debugInfo(): array

Retorna um array vazio para proteger o valor sensível de exposição acidental quando var_dump() for usado.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array vazio.

### Exemplos

Exemplo #1 Passando um objeto SensitiveParameterValue para var_dump()

    <?php
    $s = new \SensitiveParameterValue('secret');

    var_dump($s);
    ?>

O exemplo acima produzirá:

    object(SensitiveParameterValue)#1 (0) {
    }

# SensitiveParameterValue::getValue

(PHP 8 >= 8.2.0)

SensitiveParameterValue::getValue — Retorna o valor sensível

### Descrição

public function SensitiveParameterValue::getValue(): mixed

Obtém o valor sensível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O valor sensível.

### Exemplos

Exemplo #1 Exemplo de SensitiveParameterValue::getValue()

    <?php
    $s = new \SensitiveParameterValue('secret');

    echo "O valor protegido é: ", $s->getValue(), "\n";
    ?>

O exemplo acima produzirá:

    O valor protegido é: secret

## Índice

- SensitiveParameterValue::__construct — Constrói um novo objeto SensitiveParameterValue
- SensitiveParameterValue::__debugInfo — Protege os valores sensíveis de exposição acidental
- SensitiveParameterValue::getValue — Retorna o valor sensível

# A classe __PHP_Incomplete_Class

(PHP 4 >=4.0.1, PHP 5, PHP 7, PHP 8)

## Introdução

Criada por unserialize() ao tentar desserializar uma classe indefinida ou uma classe não listada nas classes permitidas na chave `allowed_classes` do array do parâmetro `options` da função unserialize().

Antes do PHP 7.2.0, usar is_object() na classe __PHP_Incomplete_Class retornaria `false`. A partir do PHP 7.2.0, será retornado `true`.

## Resumo da classe

#[\AllowDynamicProperties]
final class __PHP_Incomplete_Class {
}

Esta classe não tem propriedades ou métodos padrões. Quando criada por unserialize(), além de todas as propriedades e valores desserializados, o objeto terá uma propriedade `__PHP_Incomplete_Class_Name` que conterá o nome da classe desserializada.

## Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Esta classe agora é `final`.

## Exemplos

Exemplo #1 Criada por unserialize()

    <?php

    class MyClass
    {
        public string $property = "myValue";
    }

    $myObject = new MyClass;

    $foo = serialize($myObject);

    // desserializa todos os objetos em objetos __PHP_Incomplete_Class
    $disallowed = unserialize($foo, ["allowed_classes" => false]);

    var_dump($disallowed);

    // desserializa todos os objetos em objetos __PHP_Incomplete_Class exceto os de MyClass2 e MyClass3
    $disallowed2 = unserialize($foo, ["allowed_classes" => ["MyClass2", "MyClass3"]]);

    var_dump($disallowed2);

    // desserializa uma classe indefinida em objeto __PHP_Incomplete_Class
    $undefinedClass = unserialize('O:16:"MyUndefinedClass":0:{}');

    var_dump($undefinedClass);

O exemplo acima produzirá:

    object(__PHP_Incomplete_Class)#2 (2) {
      ["__PHP_Incomplete_Class_Name"]=>
      string(7) "MyClass"
      ["property"]=>
      string(7) "myValue"
    }
    object(__PHP_Incomplete_Class)#3 (2) {
      ["__PHP_Incomplete_Class_Name"]=>
      string(7) "MyClass"
      ["property"]=>
      string(7) "myValue"
    }
    object(__PHP_Incomplete_Class)#4 (1) {
      ["__PHP_Incomplete_Class_Name"]=>
      string(16) "MyUndefinedClass"
    }

# Atributos Predefinidos

## Índice

- Attribute
- AllowDynamicProperties
- DelayedTargetValidation
- Deprecated
- NoDiscard
- Override
- ReturnTypeWillChange
- SensitiveParameter

O PHP fornece alguns atributos predefinidos que podem ser usados.

# O atributo Attribute

(PHP 8)

## Introdução

Atributos oferecem a capacidade de adicionar informações estruturadas de metadados e legíveis por máquina em declarações no código: classes, métodos, funções, parâmetros, propriedades e constantes de classes podem ser alvos de um atributo. Os metadados definidos pelos atributos podem ser inspecionados em tempo de execução usando as APIs de Reflexão. Dessa forma, os atributos podem ser pensados como uma linguagem de configuração incorporada diretamente no código.

## Resumo da classe

#[\Attribute]
final class Attribute {
/* Constantes */
const int TARGET_CLASS;
const int TARGET_FUNCTION;
const int TARGET_METHOD;
const int TARGET_PROPERTY;
const int TARGET_CLASS_CONSTANT;
const int TARGET_PARAMETER;
const int TARGET_CONSTANT;
const int TARGET_ALL;
const int IS_REPEATABLE;
/* Propriedades */
public int $flags;
/* Métodos */
public function __construct(int `$flags` = Attribute::TARGET_ALL)
}

## Constantes predefinidas

Attribute::TARGET_CLASS

Attribute::TARGET_FUNCTION

Attribute::TARGET_METHOD

Attribute::TARGET_PROPERTY

Attribute::TARGET_CLASS_CONSTANT

Attribute::TARGET_PARAMETER

Attribute::TARGET_CONSTANT

Attribute::TARGET_ALL

Attribute::IS_REPEATABLE

## Propriedades

flags

## Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | Adicionada a constante `Attribute::TARGET_CONSTANT`.

## Veja Também

Visão geral dos atributos

# Attribute::__construct

(PHP 8)

Attribute::__construct — Constrói uma nova instância da classe Attribute

### Descrição

public function Attribute::__construct(int `$flags` = `Attribute::TARGET_ALL`)

Constrói uma nova instância da classe Attribute.

### Parâmetros

`flags`

## Índice

- Attribute::__construct — Constrói uma nova instância da classe Attribute

# O atributo AllowDynamicProperties

(PHP 8 >= 8.2.0)

## Introdução

Este atributo é usado para marcar classes que permitem propriedades dinâmicas.

> Nota: Embora os atributos em si não sejam herdados, o efeito do atributo `AllowDynamicProperties` é herdado. Classes filhas de uma classe marcada com este atributo também permitirão propriedades dinâmicas, mesmo se elas não declararem explicitamente o atributo.

## Resumo da classe

#[\Attribute]
final class AllowDynamicProperties {
/* Métodos */
public function __construct()
}

## Exemplos

As propriedades dinâmicas foram descontinuadas a partir do PHP 8.2.0, portanto, usá-las sem marcar a classe com este atributo emitirá um aviso de descontinuação.

Exemplo #1 AllowDynamicProperties com propriedade não existente

    <?php
    class DefaultBehaviour { }

    #[\AllowDynamicProperties]
    class ClassAllowsDynamicProperties { }

    $o1 = new DefaultBehaviour();
    $o2 = new ClassAllowsDynamicProperties();

    $o1->nonExistingProp = true;
    $o2->nonExistingProp = true;
    ?>

Saída do exemplo acima no PHP 8.2:

    Deprecated: Creation of dynamic property DefaultBehaviour::$nonExistingProp is deprecated in file on line 10

Exemplo #2 AllowDynamicProperties com propriedade não existente em classe herdada

    <?php
    class DefaultBehaviour { }

    #[\AllowDynamicProperties]
    class ClassAllowsDynamicProperties { }

    class InheritedClassAllowsDynamicProperties extends ClassAllowsDynamicProperties { }

    $o1 = new DefaultBehaviour();
    $o2 = new InheritedClassAllowsDynamicProperties();

    $o1->nonExistingProp = true;
    $o2->nonExistingProp = true;
    ?>

Saída do exemplo acima no PHP 8.2:

    Deprecated: Creation of dynamic property DefaultBehaviour::$nonExistingProp is deprecated in file on line 12

## Veja Também

Visão geral dos atributos

# AllowDynamicProperties::__construct

(PHP 8 >= 8.2.0)

AllowDynamicProperties::__construct — Constrói uma nova instância do atributo AllowDynamicProperties

### Descrição

public function AllowDynamicProperties::__construct()

Constrói uma nova instância de AllowDynamicProperties.

### Parâmetros

Esta função não possui parâmetros.

## Índice

- AllowDynamicProperties::__construct — Constrói uma nova instância do atributo AllowDynamicProperties

# O atributo DelayedTargetValidation

(PHP 8 >= 8.5.0)

## Introdução

Este atributo atrasa os erros de validação de destino para atributos internos do momento da compilação até o momento em que o atributo é instanciado por meio da API de Reflexão.

Quando aplicado a uma declaração, qualquer uso inválido de atributos internos no mesmo destino não acionará um erro de tempo de compilação. Em vez disso, a validação é adiada e realizada quando o atributo é instanciado por meio de ReflectionAttribute::newInstance().

Isso visa principalmente a compatibilidade futura, permitindo que o código use atributos que podem obter destinos válidos adicionais em versões futuras do PHP sem quebrar em versões mais antigas.

## Resumo da classe

#[\Attribute]
final class DelayedTargetValidation {
}

## Exemplos

Exemplo #1 Atrasar a validação de um destino inválido

    <?php

    class Base {
        protected function foo(): void {}
    }

    class Child extends Base {

        #[\DelayedTargetValidation]
        #[\Override]
        public const NAME = 'child';

        #[\Override]
        protected function foo(): void {}
    }

Em versões do PHP onde Override não é permitido em constantes de classe, isso não produz um erro de tempo de compilação.

Exemplo #2 A validação ocorre durante a reflexão

    <?php

    $reflection = new ReflectionClassConstant(Child::class, 'NAME');

    foreach ($reflection->getAttributes() as $attribute) {
        $attribute->newInstance(); // Pode lançar exceção se for inválido
    }

Quando qualquer atributo aplicado ao mesmo destino (exceto o próprio DelayedTargetValidation) é instanciado via reflexão usando ReflectionAttribute::newInstance(), a validação do destino é realizada e uma exceção pode ser lançada se o atributo for usado em um destino não suportado.

## Notas

Este atributo afeta apenas a validação de destino dos atributos internos.

Não suprime a validação funcional realizada por esses atributos. Por exemplo, Override ainda emitirá um erro se um método não sobrescrever de fato um método pai.

## Veja Também

- Visão geral de atributos
- Override

# O atributo Deprecated

(PHP 8 >= 8.4.0)

## Introdução

Este atributo é usado para marcar uma funcionalidade como descontinuada. Usar uma funcionalidade descontinuada causará a emissão de um erro `E_USER_DEPRECATED`.

## Resumo da classe

#[\Attribute]
final class Deprecated {
/* Propriedades */
public readonly ?string $message;
public readonly ?string $since;
/* Métodos */
public function __construct(?string `$message` = null, ?string `$since` = null)
}

## Propriedades

message

  Uma mensagem opcional explicando o motivo da descontinuação e a possível funcionalidade de substituição. Será incluída na mensagem de descontinuação emitida.

since

  Uma string opcional que indica desde quando a funcionalidade foi descontinuada. Os conteúdos não são validados pelo PHP e podem conter um número de versão, uma data ou qualquer outro valor que seja considerado apropriado. Será incluída na mensagem de descontinuação emitida.

  A funcionalidade que fizer parte do PHP usará a versão principal.secundária como o valor de since, por exemplo `'8.4'`

## Exemplos

    <?php

    #[\Deprecated(message: "use safe_replacement() instead", since: "1.5")]
    function unsafe_function()
    {
       echo "Isto não é seguro", PHP_EOL;
    }

    unsafe_function();

    ?>

A saída do exemplo acima no PHP 8.4 é semelhante a:

    Deprecated: Function unsafe_function() is deprecated since 1.5, use safe_replacement() instead in example.php on line 9
    Isto não é seguro

## Veja Também

- Visão geral de atributos
- ReflectionFunctionAbstract::isDeprecated()
- ReflectionClassConstant::isDeprecated()
- `E_USER_DEPRECATED`

# Deprecated::__construct

(PHP 8 >= 8.4.0)

Deprecated::__construct — Constrói uma nova instância do atributo Deprecated

### Descrição

public function Deprecated::__construct(?string `$message` = `null`, ?string `$since` = `null`)

Constrói uma nova instância de Deprecated.

### Parâmetros

`message`

  O valor da propriedade message.

`since`

  O valor da propriedade since.

## Índice

- Deprecated::__construct — Constrói uma nova instância do atributo Deprecated

# O atributo NoDiscard

(PHP 8 >= 8.5.0)

## Introdução

Este atributo pode ser usado para indicar que o valor de retorno de uma função ou método não deve ser descartado. Se o valor de retorno não for usado de nenhuma forma, um aviso será emitido.

Isso é útil para funções onde não verificar o valor de retorno provavelmente é um bug.

Para descartar intencionalmente o valor de retorno de tal função, use a conversão (void) para suprimir o aviso.

> Nota: Como os atributos são projetados para serem retrocompatíveis, `#[\NoDiscard]` pode ser adicionado a funções e métodos mesmo quando o PHP 8.4 ou versões anteriores são suportados, ele simplesmente não fará nada. No PHP 8.5 e versões posteriores, um aviso será emitido se o resultado não for usado. Para suprimir o aviso sem usar `(void)`, que não é suportado antes do PHP 8.5, considere usar uma variável como `$_`.

> Nota: `#[\NoDiscard]` aplica-se à função ou método específico na declaração em que é escrito, e o aviso é emitido com base na declaração que é realmente chamada. Como resultado, adicionar `#[\NoDiscard]` a um método de interface ou a um método abstrato não emite um aviso, porque o método invocado é o método que implementa ou substitui. Da mesma forma, um método que substitui um método `#[\NoDiscard]` não emite o aviso, a menos que ele próprio esteja marcado com o atributo. Em contraste, um método importado de uma trait mantém o atributo, porque o método da trait é copiado para a classe que o utiliza como se tivesse sido declarado lá.

## Resumo da classe

#[\Attribute]
final class NoDiscard {
/* Propriedades */
public readonly ?string $message;
/* Métodos */
public function __construct(?string `$message` = null)
}

## Propriedades

message
  Uma mensagem opcional explicando por que o valor retornado não deve ser descartado.

## Exemplos

Exemplo #1 Uso básico

    <?php

    /**
     * Processa todos os itens fornecidos e retorna um array com os resultados da
     * operação para cada item. `null` indica sucesso e uma exceção indica
     * um erro. As chaves do array de resultados correspondem às chaves do array $items.
     *
     * @param array<string> $items
     * @return array<null|Exception>
     */
    #[\NoDiscard("pois o processamento pode falhar para itens individuais")]
    function bulk_process(array $items): array {
        $results = [];

        foreach ($items as $key => $item) {
            if (\random_int(0, 9999) < 9999) {
       // Finge fazer algo útil com $item,
       // o que terá sucesso em 99,99% dos casos.
                echo "Processando {$item}", PHP_EOL;
                $error = null;
            } else {
                $error = new \Exception("Falha ao processar {$item}.");
            }

            $results[$key] = $error;
        }

        return $results;
    }

    bulk_process($items);

    ?>

A saída do exemplo acima no PHP 8.5 é semelhante a:

    Warning: The return value of function bulk_process() should either be used or intentionally ignored by casting it as (void), pois o processamento pode falhar para itens individuais

Exemplo #2 Descartar intencionalmente o valor de retorno

    <?php

    #[\NoDiscard]
    function some_command(): int {
        return 1;
    }

    // Suprimir o aviso usando (void) - PHP 8.5+
    (void) some_command();

    // Para compatibilidade com versões do PHP anteriores à 8.5, utilize uma variável temporária
    $_ = some_command();

    ?>

## Veja Também

- Visão geral dos atributos

# NoDiscard::__construct

(PHP 8 >= 8.5.0)

NoDiscard::__construct — Constrói uma nova instância do atributo NoDiscard.

### Descrição

public function NoDiscard::__construct(?string `$message` = `null`)

Constrói uma nova instância de NoDiscard.

### Parâmetros

`message`
  O valor da propriedade message.

## Índice

- NoDiscard::__construct — Constrói uma nova instância do atributo NoDiscard.

# O atributo Override

(PHP 8 >= 8.3.0)

## Introdução

Este atributo é usado para indicar que um método ou uma propriedade se destina a substituir um método ou uma propriedade de uma classe superior ou que ele/ela implementa um método ou propriedade definido(a) em uma interface.

Se nenhum método ou propriedade com o mesmo nome existir em uma classe superior ou em uma interface implementada, um erro será emitido no momento da compilação.

O atributo não pode ser usado no método __construct(), que é isento de verificação de assinaturas.

## Resumo da classe

#[\Attribute]
final class Override {
/* Métodos */
public function __construct()
}

## Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | Override pode ser aplicada a propriedades.

## Exemplos

Exemplo #1 Uso com métodos

    <?php

    class Base {
        protected function foo(): void {}
    }

    final class Extended extends Base {
        #[\Override]
        protected function boo(): void {}
    }

    ?>

A saída do exemplo acima no PHP 8.3 é semelhante a:

    Fatal error: Extended::boo() has #[\Override] attribute, but no matching parent method exists

Exemplo #2 Uso com propriedades

    <?php

    class Base {
        protected string $foo;
    }

    final class Extended extends Base {
        #[\Override]
        protected string $boo;
    }

    ?>

A saída do exemplo acima no PHP 8.5 é semelhante a:

    Fatal error: Extended::$boo has #[\Override] attribute, but no matching parent property exists

## Veja Também

- Visão geral de atributos

# Override::__construct

(PHP 8 >= 8.3.0)

Override::__construct — Constrói uma nova instância de atributo Override

### Descrição

public function Override::__construct()

Constrói uma nova instância de Override.

### Parâmetros

Esta função não possui parâmetros.

## Índice

- Override::__construct — Constrói uma nova instância de atributo Override

# O atributo ReturnTypeWillChange

(PHP 8 >= 8.1.0)

## Introdução

A maioria dos métodos internos não finais agora requerem que os métodos substitutos declarem um tipo de retorno compatível, caso contrário, um aviso de descontinuação é emitido durante a validação da herança. Isto introduz uma fase de tipo de retorno provisório: o mecanismo emite uma nota de descontinuação em vez de um erro fatal quando os tipo de retorno são incompatíveis, antes que sejam obrigatórios em uma versão futura. Caso o tipo de retorno não possa ser declarado para um método substituto devido a preocupação com compatibilidade entre versões do PHP, um atributo `#[\ReturnTypeWillChange]` pode ser adicionado para silenciar o aviso de descontinuação.

Aviso

O atributo ReturnTypeWillChange suprime os avisos de descontinuação somente durante a fase de tipo de retorno provisório. Ele não tem efeito ao substituir métodos definidos em classes definidas pelo usuário. Assim que os métodos internos adotarem tipos estritos, a não correspondência em substituições de assinaturas de métodos causará um erro fatal e este atributo não terá mais nenhum efeito.

## Resumo da classe

#[\Attribute]
final class ReturnTypeWillChange {
/* Métodos */
public function __construct()
}

## Veja Também

Visão geral dos atributos

# ReturnTypeWillChange::__construct

(PHP 8 >= 8.1.0)

ReturnTypeWillChange::__construct — Constrói uma nova instância do atributo ReturnTypeWillChange

### Descrição

public function ReturnTypeWillChange::__construct()

Constrói uma nova instância de ReturnTypeWillChange.

### Parâmetros

Esta função não possui parâmetros.

## Índice

- ReturnTypeWillChange::__construct — Constrói uma nova instância do atributo ReturnTypeWillChange

# O atributo SensitiveParameter

(PHP 8 >= 8.2.0)

## Introdução

Esse atributo é usado para marcar um parâmetro que é confidencial e deve ter seu valor ocultado se estiver presente em um stack trace.

## Resumo da classe

#[\Attribute]
final class SensitiveParameter {
/* Métodos */
public function __construct()
}

## Exemplos

    <?php

    function defaultBehavior(
        string $secret,
        string $normal
    ) {
        throw new Exception('Error!');
    }

    function sensitiveParametersWithAttribute(
        #[\SensitiveParameter]
        string $secret,
        string $normal
    ) {
        throw new Exception('Error!');
    }

    try {
        defaultBehavior('password', 'normal');
    } catch (Exception $e) {
        echo $e, PHP_EOL, PHP_EOL;
    }

    try {
        sensitiveParametersWithAttribute('password', 'normal');
    } catch (Exception $e) {
        echo $e, PHP_EOL, PHP_EOL;
    }

    ?>

A saída do exemplo acima no PHP 8.2 é semelhante a:

    Exception: Error! in example.php:7
    Stack trace:
    #0 example.php(19): defaultBehavior('password', 'normal')
    #1 {main}

    Exception: Error! in example.php:15
    Stack trace:
    #0 example.php(25): sensitiveParametersWithAttribute(Object(SensitiveParameterValue), 'normal')
    #1 {main}

## Veja Também

- Visão geral dos atributos
- SensitiveParameterValue

# SensitiveParameter::__construct

(PHP 8 >= 8.2.0)

SensitiveParameter::__construct — Constrói uma nova instância do atributo SensitiveParameter

### Descrição

public function SensitiveParameter::__construct()

Constrói uma nova instância de SensitiveParameter.

### Parâmetros

Esta função não possui parâmetros.

## Índice

- SensitiveParameter::__construct — Constrói uma nova instância do atributo SensitiveParameter

# Opções e parâmetros de contexto

O PHP oferece várias opções e parâmetros de contexto que podem ser usados com todos os sistemas de arquivos e empacotadores de fluxo. O contexto é criado com a função stream_context_create(). As opções são definidas com a função stream_context_set_option() e os parâmetros com a função stream_context_set_params().

# Opções de contexto de Socket

Opções de contexto de Socket — Lista de opções de contexto de Socket

### Descrição

As opções de contextos para Socket estão disponíveis em todos os empacotadores que trabalham em sockets, como `tcp`, `http` e `ftp`.

### Opções

`bindto`

  Utilizado para especificar o endereço IP (tanto IPv4 quanto IPv6) e/ou o número da porta que o PHP usará para acessar a rede. A sintaxe é `ip:port` para endereços IPv4, e `[ip]:port` para endereços IPv6. Definir o IP ou a porta com `0` fará com que o sistema escolha o IP e/ou a porta.

  > Nota:

  > Como o FTP cria duas conexões socket durante sua operação normal, o número da porta não poderá ser especificado ao se usar esta opção.

`backlog`

  Utilizado para limitar o número de conexões excedentes na fila de escuta do socket.

  > Nota:

  > Este parâmetro só é aplicável na função stream_socket_server().

`ipv6_v6only`

  Sobrescreve a diretiva do sistema operacional no que se refere ao mapeamento IPv4 em IPv6.

  > Nota:

  > Isto é importante quando tentando ouvir em um endereço IPv4 separadamente da existência de um binding em `[::]`.

  > Somente aplicável em stream_socket_server().

`so_reuseport`

  Permite várias ligações no mesmo IP:porta, mesmo de processos separados.

  > Nota:

  > Somente aplicável em stream_socket_server().

`so_broadcast`

  Permite enviar e receber dados de/para endereços de transmissão ampla.

  > Nota:

  > Somente aplicável a stream_socket_server().

`tcp_nodelay`

  Ao ativar essa opção com `true` será configurado `SOL_TCP,NO_DELAY=1`, de forma a desabilitar o algoritmo Nagle TCP.

### Registro de Alterações

Versão | Descrição
--- | ---
7.1.0 | Adicionado o parâmetro `tcp_nodelay`.
7.0.1 | Adicionado o parâmetro `ipv6_v6only`.

### Exemplos

Exemplo #1 Exemplo básico de uso do parâmetro `bindto`

    <?php
    // conecta à internet usando o IP '192.168.0.100'
    $opts = array(
        'socket' => array(
            'bindto' => '192.168.0.100:0',
        ),
    );

    // conecta à internet usando o IP '192.168.0.100' e a porta '7000'
    $opts = array(
        'socket' => array(
            'bindto' => '192.168.0.100:7000',
        ),
    );

    // conecta à internet usando o endereço IPv6 '2001:db8::1'
    // e a porta '7000'
    $opts = array(
        'socket' => array(
            'bindto' => '[2001:db8::1]:7000',
        ),
    );

    // conecta à internet usando a porta '7000'
    $opts = array(
        'socket' => array(
            'bindto' => '0:7000',
        ),
    );

    // cria o contexto...
    $context = stream_context_create($opts);

    // ...que será utilizado para buscar os dados
    echo file_get_contents('http://www.example.com', false, $context);

    ?>

# Opções de contexto do HTTP

Opções de contexto do HTTP — Lista de opções de contexto do HTTP

### Descrição

Opções de contexto dos transportadores `http://` e `https://`.

### Opções

`method` string

  `GET`, `POST` ou qualquer outro método HTTP suportado pelo servidor remoto.

  `GET` é o padrão.

`header` array ou string

  Cabeçalhos adicionais que devem ser enviados durante a requisição. Valores nesta opção sobrescrevem outros valores (como `User-agent:`, `Host:`, e `Authentication:`), mesmo ao seguir redirecionamentos `Location:`. Portanto, não é recomendado definir um cabeçalho `Host:`, se `follow_location` estiver habilitado.

  Os valores em string devem ser pares de `Chave: valor` delimitados por `\r\n`, por exemplo,. `"Content-Type: application/json\r\nConnection: close"`. Os valores em array devem ser uma lista de pares de `Chave: valor`, por exemplo, `["Content-Type: application/json", "Connection: close"]`.

`user_agent` string

  Valor a ser enviado no cabeçalho `User-Agent:`. Este valor só é utilizado se o user-agent não for especificado na opção de contexto `header` acima.

  Por padrão, a configuração user_agent do php.ini é utilizada.

`content` string

  Dados adicionais a serem enviados depois dos cabeçalhos. Tipicamente utilizado em requisições POST ou PUT.

`proxy` string

  URI que especifica o endereço do servidor de proxy (ex.: `tcp://proxy.example.com:5100`).

`request_fulluri` bool

  Quando definido como `true`, todo o URI será utilizado na construção da requisição (ex.: `GET http://www.example.com/path/to/file.html HTTP/1.0`). Mesmo não sendo um formato padronizado de requisição, alguns servidores de proxy o exigem.

  `false` é o padrão.

`follow_location` int

  Segue os redirecionamentos feitos com o cabeçalho `Location`. Defina com `0` para desabilitar.

  `1` é o padrão.

`max_redirects` int

  O número máximo de redirecionamentos a serem feitos. O valor `1` ou inferior significam que os redirecionamentos não serão feitos.

  `20` é o padrão.

`protocol_version` float

  Versão do protocolo HTTP.

  O padrão é `1.1` a partir do PHP 8.0.0; antes dessa versão o padrão era `1.0`.

`timeout` float

  Limite de tempo de leitura em segundos, especificado com um float (por exemplo, `10.5`).

  Por padrão, a configuração default_socket_timeout do php.ini é utilizada.

`ignore_errors` bool

  Retorna o conteúdo mesmo que códigos de status de falha sejam retornados.

  `false`.

### Exemplos

Exemplo #1 Buscando uma página e enviando dados pelo método POST

    <?php

    $postdata = http_build_query(
        [
            'var1' => 'some content',
            'var2' => 'doh'
        ]
    );

    $opts = [
        'http' => [
            'method'  => 'POST',
            'header'  => 'Content-type: application/x-www-form-urlencoded',
            'content' => $postdata
        ]
    ];

    $context = stream_context_create($opts);

    $result = file_get_contents('http://example.com/submit.php', false, $context);

    ?>

Exemplo #2 Ignorando redirecionamentos mas trazendo os cabeçalhos e conteúdo

    <?php

    $url = "http://www.example.org/header.php";

    $opts = [
        'http' => [
            'method' => 'GET',
            'max_redirects' => '0',
            'ignore_errors' => '1'
        ]
    ];

    $context = stream_context_create($opts);
    $stream = fopen($url, 'r', false, $context);

    // informação de cabeçalho e metadados
    // sobre o fluxo
    var_dump(stream_get_meta_data($stream));

    // dados reais no $url
    var_dump(stream_get_contents($stream));
    fclose($stream);
    ?>

### Notas

> Nota: Opções de contextos de soquetes de fluxo básicos
> Opções de contextos adicionais podem ser suportadas em transportes básicos Em fluxos `http://`, use as opções de contexto do transporte `tcp://`. Em fluxos `https://`, use as opções de contexto do transporte `ssl://`.

> Nota: Linha de status HTTP
> Quando este empacotador de fluxo faz um redirecionamento, o `wrapper_data` retornado pela função stream_get_meta_data() pode não conter necessariamente a linha de status HTTP, que atualmente se aplica ao conteúdo no índice `0`.

>     array (
>       'wrapper_data' =>
>       array (
>         0 => 'HTTP/1.0 301 Moved Permanently',
>         1 => 'Cache-Control: no-cache',
>         2 => 'Connection: close',
>         3 => 'Location: http://example.com/foo.jpg',
>         4 => 'HTTP/1.1 200 OK',
>         ...

> A primeira requisição retornou `301` (redirecionamento permanente), com isso o empacotador de fluxo fará o redirecionamento automaticamente para conseguir uma resposta `200` (índice = `4`).

### Veja Também

- http://
- Opções de contexto de Socket
- Opções de contexto de SSL

# Opções de contexto do FTP

Opções de contexto do FTP — Lista de opções de contexto do FTP

### Descrição

Opções de contexto para os transportadores `ftp://` e `ftps://`.

### Opções

`overwrite` bool

  Permite a sobrescrita de arquivos existentes no servidor remoto. Aplicável somente no modo de escrita (uploading).

  `false` como padrão.

`resume_pos` int

  Deslocamento do arquivo a se começar a transferência. Aplicável somente no modo de leitura (downloading).

  `0` (Início do arquivo), como padrão.

`proxy` string

  Requisição Proxy FTP pelo servidor proxy http. Aplicável em arquivos somente em operações de leitura. Ex: `tcp://squid.example.com:8000`.

### Notas

> Nota: Opções de contexto de fluxos de socket subjacentes
> Opções de contextos adicionais podem ser suportadas pelo transporte subjacente. Para fluxos `ftp://`, refira-se às opções para o transporte `tcp://`. Para `ftps://`, refira-se às opções de contexto do transporte `ssl://`.

### Veja Também

- ftp://
- Opções de contexto de Socket
- Opções de contexto de SSL

# Opções de contexto de SSL

Opções de contexto de SSL — Lista de opções de contexto de SSL

### Descrição

Opções de contexto dos transportadores `ssl://` e `tls://`.

### Opções

`peer_name` string

  Nome do peer a ser utilizado. Se este valor não for definido, o nome será adivinhado com base no nome do servidor utilizado na abertura do fluxo.

`verify_peer` bool

  Exige a verificação do certificado SSL utilizado.

  `true` como padrão.

`verify_peer_name` bool

  Exige a verificação do nome do peer.

  `true` como padrão.

`allow_self_signed` bool

  Permite certificados auto assinados. Precisa do parâmetro `verify_peer`.

  `false` como padrão.

`cafile` string

  Localização do arquivo de Autoridade Certificadora no sistema de arquivos que deve ser usado pela opção de contexto `verify_peer` para autenticar a identidade do peer remoto.

`capath` string

  Se a opção `cafile` não for especificada, ou o certificado não for encontrado, o diretório apontado pela opção `capath` será utilizado na busca de um certificado adequado. A opção `capath` deve ser um diretório de certificado com hash correto.

`local_cert` string

  Caminho para o certificado local no sistema de arquivos. Deve ser um arquivo PEM codificado que contém seu certificado e chave privada. Pode opcionalmente conter a cadeia de certificados dos emitentes. A chave privada também pode estar em um arquivo separado especificado pela opção `local_pk`.

`local_pk` string

  Caminho para a chave privada local no sistema de arquivos, em caso de se usar arquivos separados para o certificado (`local_cert`) e para a chave privada.

`passphrase` string

  Senha usada para codificar o arquivo `local_cert`

`verify_depth` int

  Abortará se a cadeia de certificados for muito profunda.

  Não verificar por padrão.

`ciphers` string

  Define a lista de cifras disponíveis. O formato desta string é descrito em » ciphers(1).

  `DEFAULT` como padrão.

`capture_peer_cert` bool

  Se definida como `true`, a opção de contexto `peer_certificate` será criada contendo o certificado peer.

`capture_peer_cert_chain` bool

  Se definida como `true`, a opção de contexto `peer_certificate_chain` será criada contendo a cadeia de certificados.

`SNI_enabled` bool

  Se definida como `true`, o indicador do nome do servidor será habilitado. Habilitar a SNI permite múltiplos certificados no mesmo endereço IP.

`disable_compression` bool

  Se definida, desabilita a compressão TLS. Pode ajudar a mitigar o vetor de ataque CRIME.

`peer_fingerprint` string | array

  Abortará quando o certificado resumido remoto não corresponder a um hash especificado.

  Quando uma string for utilizada, o tamanho determinará qual algoritmo de hash será aplicado, "md5" (32) ou "sha1" (40).

  Quando um array for utilizado, as chaves indicarão o nome do hash e os valores correspondentes ao resumo esperado.

`security_level` int

  Define o nível de segurança. Se não especificado, o padrão da biblioteca é usado. Os níveis de segurança são descritos em » SSL_CTX_get_security_level(3).

  Disponível a partir do PHP 7.2.0 e OpenSSL 1.1.0.

### Registro de Alterações

Versão | Descrição
--- | ---
7.2.0 | Adicionado o parâmetro `security_level`. Requer OpenSSL >= 1.1.0.

### Notas

> Nota: Por `ssl://` ser um transporte básico para os empacotadores `https://` e `ftps://`, quaisquer opções de contexto aplicáveis a `ssl://`, também se aplicam a `https://` e `ftps://`.

> Nota: Para SNI (Server Name Indication - Indicador de Nome de Servidor) estar disponível, o PHP deve ser compilado com o OpenSSL 0.9.8j ou superior. Utilize a constante `OPENSSL_TLSEXT_SERVER_NAME` para determinar o suporte ao SNI.

### Veja Também

- Opções de contexto de Socket

# Opções de contexto do Phar

Opções de contexto do Phar — Lista de opções de contexto do Phar

### Descrição

Opções de contexto do empacotador `phar://`.

### Opções

`compress` int

  Uma das constantes de compressão do Phar.

`metadata` mixed

  Metadados do Phar. Consulte o método Phar::setMetadata().

### Veja Também

- phar://
- Empacotador de fluxo do Phar

# Parâmetros de contexto

Parâmetros de contexto — Listagem de parâmetros de contexto

### Descrição

Estes `parâmetros` podem ser definidos em um `contexto` usando a função stream_context_set_params().

### Parâmetros

`notification` callable

  Um callable pode ser chamado quando um evento ocorre em um fluxo.

  Veja stream_notification_callback para mais detalhes.

# Opções de contexto para Zip

Opções de contexto para Zip — Lista de opções de contexto de Zip

### Descrição

Opções de contexto para Zip estão disponíveis para empacotadores `zip`.

### Opções

`password`

  Utilizado para especificar a senha definida para o arquivo criptografado.

### Registro de Alterações

Versão | Descrição
--- | ---
7.2.0, PECL zip 1.14.0 | Incluído o parâmetro `password`.

### Exemplos

Exemplo #1 Exemplo básico de uso de `password`

    <?php
    // Ler o arquivo criptografado
    $opts = array(
        'zip' => array(
            'password' => 'secret',
        ),
    );
    // criar o contexto...
    $context = stream_context_create($opts);

    // ...e usá-lo para obter os dados
    echo file_get_contents('zip://test.zip#test.txt', false, $context);

    ?>

# Opções de contexto Zlib

Opções de contexto Zlib — Lista de opções de contexto de Zlib

### Descrição

Opções de contexto Zlib estão disponíveis para empacotadores `zlib`.

### Opções

`level`

  Usado para especificar o nível de compressão (`0` - `9`).

### Registro de Alterações

Versão | Descrição
--- | ---
7.3.0 | O parâmetro `level` foi incluído.

## Índice

- Opções de contexto de Socket — Lista de opções de contexto de Socket
- Opções de contexto do HTTP — Lista de opções de contexto do HTTP
- Opções de contexto do FTP — Lista de opções de contexto do FTP
- Opções de contexto de SSL — Lista de opções de contexto de SSL
- Opções de contexto do Phar — Lista de opções de contexto do Phar
- Parâmetros de contexto — Listagem de parâmetros de contexto
- Opções de contexto para Zip — Lista de opções de contexto de Zip
- Opções de contexto Zlib — Lista de opções de contexto de Zlib

# Protocolos e empacotadores suportados

O PHP vem com muitos empacotadores para vários protocolos no estilo URL para uso com as funções do sistema de arquivos, tais como fopen(), copy(), file_exists() e filesize(). Além desses empacotadores, é possível registrar empacotadores customizados usando a função stream_wrapper_register().

> Nota: A sintaxe de URL usada para descrever um empacotadores suporta apenas a sintaxe `esquema://...`. As sintaxes `esquema:/` e `esquema:` não são suportadas.

# file://

file:// — Acessando o sistema de arquivos local

### Descrição

`file://` é o empacotador padrão usado com o PHP e representa o sistema de arquivos local. Quando um caminho relativo é especificado (um caminho que não começa com `/`, `\`, `\\`, ou uma letra de unidade do Windows), o caminho fornecido será aplicado ao diretório atual de trabalho. Em muitos casos este é o diretório no qual o script reside a menos que tenha sido alterado. Usando o SAPI CLI, o padrão é o diretório do qual o script foi chamado.

Com algumas funções, tais como fopen() e file_get_contents(), `include_path` pode opcionalmente ser pesquisado com caminho relativo também.

### Uso

- /caminho/para/arquivo.ext
- caminho/relativo/para/arquivo.ext
- arquivoNoDiretorioAtual.ext
- C:/caminho/para/arquivoWindows.ext
- C:\caminho\para\arquivoWindows.ext
- \\smbserver\share\caminho\para\arquivoWindows.ext
- file:///caminho/para/arquivo.ext

### Opções

Sumário do Empacotador
Atributo | Suportado
--- | ---
Restrito por allow_url_fopen | Não
Permite Leitura | Sim
Permite Escrita | Sim
Permite Adição | Sim
Permite Leitura e Escrita Simultâneas | Sim
Suporta stat() | Sim
Suporta unlink() | Sim
Suporta rename() | Sim
Suporta mkdir() | Sim
Suporta rmdir() | Sim

# http://

# https://

http:// -- https:// — Acessando URLs HTTP(s)

### Descrição

Permite acesso somente leitura a arquivos/recursos via HTTP. Por padrão um GET HTTP 1.0 é usado. Um cabeçalho `Host:` é enviado com a requisição para lidar com hosts virtuais baseados em nomes. Se estiver configurado uma string user_agent no arquivo php.ini ou no contexto do fluxo, ele também será incluído na requisição.

O fluxo permite acesso ao corpo do recurso; os cabeçalhos são armazenados na variável $http_response_header.

Se for importante conhecer o URL do recurso de onde o documento se originou (depois de todos os redirecionamentos processados), será necessário processar a série de cabeçalhos de resposta retornados pelo fluxo.

A diretiva from será usada para o cabeçalho `From:` se definida e não sobrescrita pelo Opções e parâmetros de contexto.

### Uso

- http://example.com
- http://example.com/arquivo.php?var1=val1&var2=val2
- http://usuario:senha@example.com
- https://example.com
- https://example.com/arquivo.php?var1=val1&var2=val2
- https://usuario:senha@example.com

### Opções

Sumário do Empacotador
Atributo | Suportado
--- | ---
Restrito por allow_url_fopen | Sim
Permite Leitura | Sim
Permite Escrita | Não
Permite Adição | Não
Permite Leitura e Escrita Simultâneas | N/A
Suporta stat() | Não
Suporta unlink() | Não
Suporta rename() | Não
Suporta mkdir() | Não
Suporta rmdir() | Não

### Exemplos

Exemplo #1 Detectando a qual se chegou depois de todos os redirecionamentos

    <?php
    $url = 'http://www.example.com/redirecting_page.php';

    $fp = fopen($url, 'r');

    $meta_data = stream_get_meta_data($fp);
    foreach ($meta_data['wrapper_data'] as $response) {

        /* Fomos redirecionados? */
        if (strtolower(substr($response, 0, 10)) == 'location: ') {

            /* atualiza $url para onde fomos redirecionados */
            $url = substr($response, 10);
        }

    }

    ?>

### Notas

> Nota: HTTPS só é suportado quando a extensão openssl estiver habilitada.

Conexões HTTP são somente leitura; escrever dados ou copiar arquivos para um recurso HTTP não é suportado.

Enviar requisições POST e PUT, por exemplo, pode ser feito com a ajuda de Contextos HTTP.

### Veja Também

- Opções de contexto do HTTP
- $http_response_header
- stream_get_meta_data() - Obtém cabeçalhos/metadados de ponteiros de arquivos/fluxos

# ftp://

# ftps://

ftp:// -- ftps:// — Acessando URLs FTP(s)

### Descrição

Permite acesso de leitura a arquivos existentes e criação de novos arquivos via FTP. Se o servidor não suportar modo ftp passivo, a conexão irá falhar.

Pode-se abrir arquivos tanto para leitura quanto para escrita, mas não para ambos simultaneamente. Se o arquivo remoto já existir no servidor ftp e houver tentativa de abri-lo para escrita, mas não estiver especificada a opção de contexto `overwrite`, a conexão irá falhar. Se for necessário sobrescrever os arquivos existentes via ftp, deve-se especificar a opção `overwrite` no contexto e abrir o arquivo para escrita. Alternativamente, pode ser usada a extensão FTP.

Se estiver configurada a diretiva from no php.ini, então este valor será enviado como a senha do FTP anônimo.

### Uso

- ftp://example.com/pub/arquivo.txt
- ftp://usuario:senha@example.com/pub/arquivo.txt
- ftps://example.com/pub/arquivo.txt
- ftps://usuario:senha@example.com/pub/arquivo.txt

### Opções

Sumário do Empacotador
Atributo | Suportado
--- | ---
Restrito por allow_url_fopen | Sim
Permite Leitura | Sim
Permite Escrita | Sim (arquivos novos/existentes com `overwrite`)
Permite Adição | Sim
Permite Leitura e Escrita Simultâneas | Não
Suporta stat() | Somente os elementos filesize(), filemtime(), filetype(), file_exists(), is_file() e is_dir().
Suporta unlink() | Sim
Suporta rename() | Sim
Suporta mkdir() | Sim
Suporta rmdir() | Sim

### Notas

> Nota:

> FTPS somente é suportado quando a extensão openssl estiver habilitada.

> Se o servidor não suportar SSL, a conexão cairá para um FTP comum não criptografado.

> Nota: Adição
> Arquivos podem ter conteúdo acrescentado pelo empacotador de URL `ftp://`.

### Veja Também

- Opções de contexto do FTP

# php://

php:// — Acessando vários fluxos de E/S

### Descrição

O PHP fornece um número de fluxos de E/S miscelâneos que permitem acesso aos fluxos de entrada e saída do próprio PHP, a entrada padrão, descritores de arquivo de saída e de erro, fluxos de arquivos temporário em memória e em disco, e filtros que podem manipular outros recursos de arquivo enquanto eles são lidos ou escritos.

#### php://stdin, php://stdout e php://stderr

php://stdin, php://stdout e php://stderr permitem acesso direto ao fluxo correspondente de entrada ou saída do processo PHP. O fluxo referencia um descritor de arquivo duplicado, para que quando um php://stdin for aberto e depois fechado, apenas a cópia do descritor será fechada - o fluxo real referenciado por `STDIN` não é afetado. Recomenda-se que as constantes `STDIN`, `STDOUT` e `STDERR` sejam usadas no lugar de abrir manualmente os fluxos utilizando estes empacotadores.

php://stdin é somente leitura, enquanto que php://stdout e php://stderr são somente escrita.

#### php://input

php://input é um fluxo somente leitura que permite a leitura de dados brutos do corpo da requisição. php://input não está disponível em requisições POST com `enctype="multipart/form-data"` se a opção enable_post_data_reading estiver habilitada.

#### php://output

php://output é um fluxo somente escrita que permite escrita ao mecanismo de buffer de saída da mesma maneira que print e echo.

#### php://fd

php://fd permite acesso direto ao descritor de arquivo fornecido. Por exemplo, php://fd/3 se refere ao descritor de arquivo 3.

#### php://memory e php://temp

php://memory e php://temp são fluxos somente leitura que permitem que dados temporários sejam armazenados em um empacotador parecido com um arquivo. Uma diferença entre os dois é que php://memory irá sempre armazenar seus dados na memória, enquanto que php://temp irá usar um arquivo temporário assim que a quantidade de dado armazenado atingir um limite predefinido (o padrão é 2 MB). A localização deste arquivo temporário é determinada da mesma forma que a função sys_get_temp_dir().

O limite de memória de php://temp pode ser controlado concatenando-se `/maxmemory:NN`, onde `NN` é a quantidade máxima de dados a manter na memória antes de usar um arquivo temporário, em bytes.

Cuidado

Algumas extensões PHP podem requerer um fluxo padrão de E/S, e podem tentar converter um fluxo fornecido para um fluxo de E/S padrão. Esta conversão pode falhar para fluxos de memória já que ela requer que a função C fopencookie() esteja dispnível. Esta função C não está disponível no Windows.

#### php://filter

php://filter é um tipo de meta-empacotador projetado para permitir a aplicação de filtros a um fluxo no momento da abertura. Isto é útil para funções de arquivo completas como readfile(), file() e file_get_contents() pois não haveria oportunidade de aplicar um filtro ao fluxo antes que os conteúdo fosse lido.

O alvo do php://filter utiliza os parâmetros a seguir como parte de seu caminho. Cadeias múltiplas de filtro podem ser especificadas em um caminho. Favor referir-se aos exemplos para especificidades no uso destes parâmetros.

Parâmetros de php://filter
Nome | Descrição
--- | ---
`resource=<fluxo a ser filtrado>` | Este parâmetro é requerido. Ele especifica o fluxo que deseja-se filtrar.
`read=<lista de filtros a aplicar à cadeia de leitura>` | Este parâmetro é opcional. Um ou mais nomes de filtros podem ser fornecidos, separados pelo caractere de barra vertical (`|`).
`write=<lista de filtros a aplicar à cadeia de escrita>` | Este parâmetro é opcional. Um ou mais nomes de filtros podem ser fornecidos, separados pelo caractere de barra vertical (`|`).
`<lista de filtros a aplicar a ambas as cadeias>` | Quaisquer listas de filtros que não são prefixadas por `read=` ou `write=` serão aplicadas tanto às cadeias de leitura quanto às de escrita, conforme apropriado.

### Opções

Sumário do Empacotador (para `php://filter`, refira-se ao sumário do empacotador sendo filtrado)
Atributo | Suportado
--- | ---
Restrito por allow_url_fopen | Não
Restrito por allow_url_include | `php://input`, `php://stdin`, `php://memory` e `php://temp` somente.
Permite Leitura | `php://stdin`, `php://input`, `php://fd`, `php://memory` e `php://temp` somente.
Permite Escrita | `php://stdout`, `php://stderr`, `php://output`, `php://fd`, `php://memory` e `php://temp` somente.
Permite Adição | `php://stdout`, `php://stderr`, `php://output`, `php://fd`, `php://memory` e `php://temp` somente. (Equivalente a escrita)
Permite Leitura e Escrita Simultâneas | `php://fd`, `php://memory` e `php://temp` somente.
Suporta stat() | Não. Entretanto, `php://memory` e `php://temp` suportam fstat().
Suporta unlink() | Não
Suporta rename() | Não
Suporta mkdir() | Não
Suporta rmdir() | Não
Suporta stream_select() | `php://stdin`, `php://stdout`, `php://stderr`, `php://fd` e `php://temp` somente.

### Exemplos

Exemplo #1 php://temp/maxmemory

Este parâmetro opcional permite configurar o limite de memória antes que php://temp comece a usar um arquivo temporário.

    <?php
    // Define o limite para 5 MB.
    $fiveMBs = 5 * 1024 * 1024;
    $fp = fopen("php://temp/maxmemory:$fiveMBs", 'r+');

    fputs($fp, "hello\n");

    // Lê o que foi escrito.
    rewind($fp);
    echo stream_get_contents($fp);
    ?>

Exemplo #2 php://filter/resource=<fluxo a ser filtrado>

Este parâmetro deve ser localizado no final da especificação php://filter e deve ser apontado ao fluxo que deseja-se filtrar.

    <?php
    /* Isto é equivalente a simplesmente:
      readfile("http://www.example.com");
      já que nenhum filtro é realmente especificado */

    readfile("php://filter/resource=http://www.example.com");
    ?>

Exemplo #3 php://filter/read=<lista de filtros a aplicar à cadeia de leitura>

Este parâmetro leva um ou mais nomes de filtros separados pelo caractere de barra vertical `|`.

    <?php
    /* Isto irá mostrar o conteúdo de
      www.example.com inteiramente em letras maiúsculas */
    readfile("php://filter/read=string.toupper/resource=http://www.example.com");

    /* Isto fará o mesmo que o comando acima
      mas também irá codificar com ROT13 */
    readfile("php://filter/read=string.toupper|string.rot13/resource=http://www.example.com");
    ?>

Exemplo #4 php://filter/write=<lista de filtros a aplicar à cadeia de escrita>

Este parâmetro leva um ou mais nomes de filtros separados pelo caractere de barra vertical `|`.

    <?php
    /* Isto irá filtrar a string "Olá Mundo"
      através do filtro rot13 filter, e então escrever no
      exemplo.txt no diretório atual */
    file_put_contents("php://filter/write=string.rot13/resource=exemplo.txt","Olá Mundo");
    ?>

Exemplo #5 php://memory e php://temp não são reutilizáveis

php://memory e php://temp não são reutilizáveis, isto é, depois que os fluxos foram fechados não há como referir-se a eles novamente.

    <?php
    file_put_contents('php://memory', 'PHP');
    echo file_get_contents('php://memory'); // não imprime nada

Exemplo #6 php://input para leitura de dados JSON do corpo da requisição

Este exemplo demonstra como ler dados JSON brutos de requisições POST, PUT e PATCH usando php://input.

    <?php
    $input = file_get_contents("php://input");
    $json_array = json_decode(
      json: $input,
      associative: true,
      flags: JSON_THROW_ON_ERROR
    );

    echo "Dados JSON recebidos: ";
    print_r($json_array);
    ?>

# zlib://

# bzip2://

# zip://

zlib:// -- bzip2:// -- zip:// — Fluxos de compactação

### Descrição

compress.zlib:// e compress.bzip2://

zlib: funciona como gzopen(), exceto que o fluxo pode ser usado com fread() e outras funções do sistema de arquivos. Isso foi descontinuado devido a ambiguidades com nomes de arquivos contendo caracteres ':'; use compress.zlib:// em vez disso.

compress.zlib:// e compress.bzip2:// são equivalentes para gzopen() e bzopen() respectivamente, e funcionam mesmo em sistemas que não suportam fopencookie.

A extensão ZIP registra o empacotador zip:. a partir do PHP 7.2.0 e libzip 1.2.0+, foi adicionado suporte para as senhas para arquivos criptografados, permitindo que as senhas sejam fornecidas por contextos de fluxo. As senhas podem ser definidas usando `'password'`, uma opção de contexto de fluxo.

### Uso

- compress.zlib://file.gz
- compress.bzip2://file.bz2
- zip://archive.zip#dir/file.txt

### Opções

Resumo do Empacotador
Atributo | Suportado
--- | ---
Restringido por allow_url_fopen | Não
Permite leitura | Sim
Permite escrita | Sim (exceto `zip://`)
Permite adição | Sim (exceto `zip://`)
Permite leitura e escrita simultâneas | Não
Suporta stat() | Não, use o empacotador `file://` para verificar o "stat" de arquivos compactados.
Suporta unlink() | Não, use o empacotador `file://` para excluir arquivos compactados.
Suporta rename() | Não
Suporta mkdir() | Não
Suporta rmdir() | Não

### Veja Também

- Opções de contexto Zlib

# data://

data:// — Dados (RFC 2397)

### Descrição

O empacotador de fluxo data: (» RFC 2397).

### Uso

- data://text/plain;base64,

### Opções

Sumário do Empacotador
Atributo | Suportado
--- | ---
Restrito por allow_url_fopen | Sim
Restrito por allow_url_include | Sim
Permite Leitura | Sim
Permite Escrita | Não
Permite Adição | Não
Permite Leitura e Escrita Simultâneas | Não
Suporta stat() | Não
Suporta unlink() | Não
Suporta rename() | Não
Suporta mkdir() | Não
Suporta rmdir() | Não

### Exemplos

Exemplo #1 Imprimir conteúdo de data://

    <?php
    // prints "I love PHP"
    echo file_get_contents('data://text/plain;base64,SSBsb3ZlIFBIUAo=');
    ?>

Exemplo #2 Obtém o tipo de mídia

    <?php
    $fp   = fopen('data://text/plain;base64,', 'r');
    $meta = stream_get_meta_data($fp);

    // prints "text/plain"
    echo $meta['mediatype'];
    ?>

# glob://

glob:// — Encontra caminhos que correspondem a um padrão

### Descrição

O empacotador de fluxo glob:.

### Uso

- glob://

### Opções

Sumário do Empacotador
Atributo | Suportado
--- | ---
Restrito por allow_url_fopen | Não
Restrito por allow_url_include | Não
Permite Leitura | Não
Permite Escrita | Não
Permite Adição | Não
Permite Leitura e Escrita Simultâneas | Não
Suporta stat() | Não
Suporta unlink() | Não
Suporta rename() | Não
Suporta mkdir() | Não
Suporta rmdir() | Não

### Exemplos

Exemplo #1 Uso básico

    <?php
    // Percorre todos os arquivos *.php no diretório ext/spl/examples/
    // e mostra o nome do arquivo e seu tamanho
    $it = new DirectoryIterator("glob://ext/spl/examples/*.php");
    foreach($it as $f) {
        printf("%s: %.1FK\n", $f->getFilename(), $f->getSize()/1024);
    }
    ?>

    tree.php: 1.0K
    findregex.php: 0.6K
    findfile.php: 0.7K
    dba_dump.php: 0.9K
    nocvsdir.php: 1.1K
    phar_from_dir.php: 1.0K
    ini_groups.php: 0.9K
    directorytree.php: 0.9K
    dba_array.php: 1.1K
    class_tree.php: 1.8K

# phar://

phar:// — Arquivo PHP

### Descrição

O empacotador de fluxo phar://. Consulte Empacotador de fluxo Phar para uma descrição detalhada.

### Uso

- phar://

### Opções

Sumário do Empacotador
Atributo | Suportado
--- | ---
Restrito por allow_url_fopen | Não
Restrito por allow_url_include | Não
Permite Leitura | Sim
Permite Escrita | Sim
Permite Adição | Não
Permite Leitura e Escrita Simultâneas | Sim
Suporta stat() | Sim
Suporta unlink() | Sim
Suporta rename() | Sim
Suporta mkdir() | Sim
Suporta rmdir() | Sim

### Veja Também

- Opções de contexto do Phar

# ssh2://

ssh2:// — Shell Seguro 2

### Descrição

ssh2.shell:// ssh2.exec:// ssh2.tunnel:// ssh2.sftp:// ssh2.scp:// (PECL)

> Nota: Este empacotador não é habilitado por padrão.
> Para utilizar os empacotadores ssh2.*://, a extensão » SSH2 disponível em » PECL deve estar instalada.

Além de aceitar detalhes de login URI tradicionais, os empacotadores ssh2 também farão reúso de conexões abertas através da passagem do recurso da conexão na parte do host da URL.

### Uso

- ssh2.shell://usuario:senha@example.com:22/xterm
- ssh2.exec://usuario:senha@example.com:22/usr/local/bin/algumcomando
- ssh2.tunnel://usuario:senha@example.com:22/192.168.0.1:14
- ssh2.sftp://usuario:senha@example.com:22/caminho/para/arquivo

### Opções

Sumário do Empacotador
Atributo | ssh2.shell | ssh2.exec | ssh2.tunnel | ssh2.sftp | ssh2.scp
--- | --- | --- | --- | --- | ---
Restrito por allow_url_fopen | Sim | Sim | Sim | Sim | Sim
Permite Leitura | Sim | Sim | Sim | Sim | Sim
Permite Escrita | Sim | Sim | Sim | Sim | Não
Permite Adição | Não | Não | Não | Sim (quando suportado pelo servidor) | Não
Permite Leitura e Escrita Simultâneas | Sim | Sim | Sim | Sim | Não
Suporta stat() | Não | Não | Não | Sim | Não
Suporta unlink() | Não | Não | Não | Sim | Não
Suporta rename() | Não | Não | Não | Sim | Não
Suporta mkdir() | Não | Não | Não | Sim | Não
Suporta rmdir() | Não | Não | Não | Sim | Não

Opções de contexto
Nome | Uso | Padrão
--- | --- | ---
`session` | Recurso ssh2 pré-conectado a ser reutilizado |
`sftp` | Recurso sftp pré-alocado a ser reutilizado |
`methods` | Métodos de troca de chaves, de chave de host, de cifras, de compressão e de MAC a serem usados |
`callbacks` |  |
`username` | Nome de usuário a ser conectado |
`password` | Senha a ser usada com a autenticação |
`pubkey_file` | Nome do arquivo de chave pública a ser usado com a autenticação |
`privkey_file` | Nome do arquivo de chave privada a ser usado com a autenticação |
`env` | Array associativo de variáveis de ambiente a ser configurado |
`term` | Tipo de emulação de terminal a ser requisitado quando da alocação de um pty |
`term_width` | Largura do terminal requisitado quando da alocação de um pty |
`term_height` | Altura do terminal requisitado quando da alocação de um pty |
`term_units` | Unidadem usadas em term_width e term_height | `SSH2_TERM_UNIT_CHARS`

### Exemplos

Exemplo #1 Abrindo um fluxo para conexão ativa

    <?php
    $session = ssh2_connect('example.com', 22);
    ssh2_auth_pubkey_file($session, 'username', '/home/username/.ssh/id_rsa.pub',
                                                '/home/username/.ssh/id_rsa', 'secret');
    $stream = fopen("ssh2.tunnel://$session/remote.example.com:1234", 'r');
    ?>

Exemplo #2 Esta variável $session deve ser mantida disponível!

Para usar os empacotadores ssh2.*://$session, a variável de recurso $session deve ser mantida. O código abaixo não terá o efeito desejado:

    <?php
    $session = ssh2_connect('example.com', 22);
    ssh2_auth_pubkey_file($session, 'username', '/home/username/.ssh/id_rsa.pub',
                                                '/home/username/.ssh/id_rsa', 'secret');
    $connection_string = "ssh2.sftp://$session/";
    unset($session);
    $stream = fopen($connection_string . "path/to/file", 'r');
    ?>

unset() fecha a sessão, porque $connection_string não contém uma referência à variável $session, somente uma string convertida derivada dela. Isto também acontece quando a função unset() está implícita devido a uma saída de escopo (como em uma função).

# rar://

rar:// — RAR

### Descrição

Este empacotador usa o caminho para o arquivo RAR (relativo ou absoluto) codificado em url, um asterisco opcional (`*`), um símbolo de número opcional (`#`) e uma entrada de nome opcional codificada em url, como armazenado no arquivo. Especificar uma entrada de nome requer o símbolo de número; Uma barra (/) no início da entrada de nome é opcional.

Este empacotador pode abrir tanto arquivos quanto diretórios. Quando abre diretórios, o asterisco força o retorno não codificado dos nomes das entradas do diretório. Se não houver asterisco, eles serão retornados com codificação url – a razão para isto é permitir que o empacotador seja usado corretamente com funcionalidades internas como RecursiveDirectoryIterator na presença de nomes de arquivo que se parecem com dados codificados de url.

Se o símbolo de número (#) e a parte de nome de entrada não forem incluídos, a raiz dos arquivos será mostrada. Isto difere de diretórios comuns pelo fato que o fluxo resultante não conterá informações como horário de modificação, já que o diretório raiz não é armazenado em uma entrada individual no arquivo. O uso do empacotador com RecursiveDirectoryIterator requer que o símbolo de número seja incluído na URL ao acessar a raiz, para que as URLs dos ramos filhos sejam construídos corretamente.

> Nota: Este empacotador não é habilitado por padrão
> Para usar o empacotador rar://, a extensão » rar disponível em » PECL deve ser instalada.

rar:// Disponível desde o PECL rar 3.0.0

### Uso

- rar://<nome de arquivo codificado como url>[*][#[<nome de entrada codificado como url>]]

### Opções

Sumário do Empacotador
Atributo | Suportado
--- | ---
Restrito por allow_url_fopen | Não
Restrito por allow_url_include | Não
Permite Leitura | Sim
Permite Escrita | Não
Permite Adição | Não
Permite Leitura e Escrita Simultâneas | Não
Suporta stat() | Sim
Suporta unlink() | Não
Suporta rename() | Não
Suporta mkdir() | Não
Suporta rmdir() | Não

Opções de contexto
Nome | Uso | Padrão
--- | --- | ---
`open_password` | A senha utilizada para criptografar os cabeçalhos do arquivo, se houver. WinRAR irá criptografar todos os arquivos com a mesma senha do cabeçalho quando ela estiver presente, ou seja, para arquivos com cabeçalhos criptografados, `file_password` será ignorada. |
`file_password` | A senha utilizada para criptografar um arquivo, se houver. Se os cabeçalhos também estiverem criptografados, esta opção será ignorada em favor de `open_password`. A razão pela qual existem duas opções é para cobrir a possibilidade de suportar arquivos com senhas diferentes para cabeçalhos e arquivos, se este tipo de arquivo porventura vier a existir. Note que se o arquivo não tiver seus cabeçalhos criptografados, `open_password` será ignorada e esta opção deve ser usada no lugar. |
`volume_callback` | Um callback para determinar o caminho de volumes faltantes. Consulte RarArchive::open() para mais informação. |

### Exemplos

Exemplo #1 Explorando um arquivo RAR

    <?php

    class MyRecDirIt extends RecursiveDirectoryIterator {
        function current() {
            return rawurldecode($this->getSubPathName()) .
                (is_dir(parent::current())?" [DIR]":"");
        }
    }

    $f = "rar://" . rawurlencode(dirname(__FILE__)) .
        DIRECTORY_SEPARATOR . 'dirs_and_extra_headers.rar#';

    $it = new RecursiveTreeIterator(new MyRecDirIt($f));

    foreach ($it as $s) {
        echo $s, "\n";
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    |-allow_everyone_ni [DIR]
    |-file1.txt
    |-file2_אּ.txt
    |-with_streams.txt
    \-אּ [DIR]
      |-אּ\%2Fempty%2E [DIR]
      | \-אּ\%2Fempty%2E\file7.txt
      |-אּ\empty [DIR]
      |-אּ\file3.txt
      |-אּ\file4_אּ.txt
      \-אּ\אּ_2 [DIR]
        |-אּ\אּ_2\file5.txt
        \-אּ\אּ_2\file6_אּ.txt

Exemplo #2 Abrindo um arquivo criptografado (criptografia de cabeçalho)

    <?php
    $stream = fopen("rar://" .
        rawurlencode(dirname(__FILE__)) . DIRECTORY_SEPARATOR .
        'encrypted_headers.rar' . '#encfile1.txt', "r", false,
        stream_context_create(
            array(
                'rar' =>
                    array(
                        'open_password' => 'samplepassword'
                    )
                )
            )
        );
    var_dump(stream_get_contents($stream));
    /* datas de criação e de último acesso são opcionais no WinRAR, por isso a maioria
     * dos arquivos não as possui */
    var_dump(fstat($stream));
    ?>

O exemplo acima produzirá algo semelhante a:

    string(26) "Encrypted file 1 contents."
    Array
    (
        [0] => 0
        [1] => 0
        [2] => 33206
        [3] => 1
        [4] => 0
        [5] => 0
        [6] => 0
        [7] => 26
        [8] => 0
        [9] => 1259550052
        [10] => 0
        [11] => -1
        [12] => -1
        [dev] => 0
        [ino] => 0
        [mode] => 33206
        [nlink] => 1
        [uid] => 0
        [gid] => 0
        [rdev] => 0
        [size] => 26
        [atime] => 0
        [mtime] => 1259550052
        [ctime] => 0
        [blksize] => -1
        [blocks] => -1
    )

# ogg://

ogg:// — Fluxos de áudio

### Descrição

Os arquivos abertos para leitura por meio do empacotador ogg:// são tratados como áudio compactado codificado usando o codec `OGG/Vorbis`. Da mesma forma, os arquivos abertos para gravação ou adição por meio do empacotador ogg:// são gravados como dados de áudio compactados. stream_get_meta_data(), quando usado em um arquivo `OGG/Vorbis` aberto para leitura, retornará vários detalhes sobre o fluxo, incluído a etiqueta `vendor`, quaisquer comentários incluídos em `comments`, o número de canais em `channels`, a taxa no parâmetro `rate`, e o intervalo da taxa de codificação descrito por: `bitrate_lower`, `bitrate_upper`, `bitrate_nominal`, e `bitrate_window`.

ogg:// (PECL)

> Nota: Este empacotador não é habilitado por padrão
> Para poder utilizar o empacotador ogg://, a extensão » OGG/Vorbis disponível em » PECL precisa estar instalada.

### Uso

- ogg://soundfile.ogg
- ogg:///path/to/soundfile.ogg
- ogg://http://www.example.com/path/to/soundstream.ogg

### Opções

Resumo do Empacotador
Atributo | Suportado
--- | ---
Restringido por allow_url_fopen | Não
Permite leitura | Sim
Permite escrita | Sim
Permite adição | Sim
Permite leitura e ecrita simultâneas | Não
Suporta stat() | Não
Suporta unlink() | Não
Suporta rename() | Não
Suporta mkdir() | Não
Suporta rmdir() | Não

Opções de contexto
Nome | Uso | Padrão | Modo
--- | --- | --- | ---
`pcm_mode` | Codificação PCM a ser aplicada durante a leitura, uma das seguintes constantes: `OGGVORBIS_PCM_U8`, `OGGVORBIS_PCM_S8`, `OGGVORBIS_PCM_U16_BE`, `OGGVORBIS_PCM_S16_BE`, `OGGVORBIS_PCM_U16_LE` e `OGGVORBIS_PCM_S16_LE`. (8 bits versus 16 bits, com sinal ou sem sinal, big ou little `endian`) | OGGVORBIS_PCM_S16_LE | Leitura
`rate` | Taxa de amostragem de dados de entrada, expressa em Hz | 44100 | Escrita/Adição
`bitrate` | Quando fornecido como um número inteiro, refere-se à taxa de bits fixa para codificação. (16000 to 131072) Quando fornecido como um float, refere-se à qualidade da taxa de bits variável a ser utilizada. (-1.0 to 1.0) | 128000 | Escrita/Adição
`channels` | O número de canais de áudio a serem codificados, geralmente 1 (mono) ou 2 (estéreo). Pode variar até 16. | 2 | Escrita/Adição
`comments` | Um array de strings para codificar no cabeçalho da faixa. |  | Escrita/Adição

# expect://

expect:// — Fluxos de Interação entre Processos

### Descrição

Fluxos abertos através do empacotador expect:// fornecem acesso ao stdin, stdout e stderr do processo via PTY.

> Nota: Este empacotador não é habilitado por padrão
> Para usar o empacotador expect://, a extensão » Expect disponível em » PECL deve ser instalada.

expect:// (PECL)

### Uso

- expect://command

### Opções

Sumário do Empacotador
Atributo | Suportado
--- | ---
Restrito por allow_url_fopen | Não
Permite Leitura | Sim
Permite Escrita | Sim
Permite Adição | Sim
Permite Leitura e Escrita Simultâneas | Não
Suporta stat() | Não
Suporta unlink() | Não
Suporta rename() | Não
Suporta mkdir() | Não
Suporta rmdir() | Não

## Índice

- file:// — Acessando o sistema de arquivos local
- http:// — Acessando URLs HTTP(s)
- ftp:// — Acessando URLs FTP(s)
- php:// — Acessando vários fluxos de E/S
- zlib:// — Fluxos de compactação
- data:// — Dados (RFC 2397)
- glob:// — Encontra caminhos que correspondem a um padrão
- phar:// — Arquivo PHP
- ssh2:// — Shell Seguro 2
- rar:// — RAR
- ogg:// — Fluxos de áudio
- expect:// — Fluxos de Interação entre Processos

- Sintaxe Básica
  - Tags PHP
  - Escapando o HTML
  - Separação de instruções
  - Comentários
- Tipos
  - Introdução
  - Sistema de tipagem
  - NULL
  - Booleanos
  - Inteiros
  - Números de ponto flutuante
  - Strings
  - Strings numéricas
  - Arrays
  - Objetos
  - Enumerações
  - Recursos
  - Chamáveis
  - Misto
  - Void
  - Never
  - Tipos de classes relativas
  - Tipos únicos
  - Iterável
  - Declarações de tipo
  - Conversão automática de tipos
- Variáveis
  - Básico
  - Variáveis Predefinidas
  - Escopo de variáveis
  - Variáveis variáveis
  - Variáveis de fontes externas
- Constantes
  - Sintaxe
  - Constantes Predefinidas
  - Constantes Mágicas
- Expressões
- Operadores
  - Precedência de Operadores
  - Aritméticos — Operadores Aritméticos
  - Incremento e Decremento — Operadores de Incremento/Decremento
  - Atribuição — Operadores de Atribuição
  - Binários — Operadores Binários
  - Comparação — Operadores de Comparação
  - Controle de Erro — Operadores de Controle de Erro
  - Execução — Operadores de Execução
  - Lógica — Operadores Lógicos
  - String — Operadores de String
  - Arrays — Operadores de Arrays
  - Tipo — Operadores de Tipo
  - Funcional — Operadores Funcionais
- Estruturas de Controle
  - Introdução
  - if
  - else
  - elseif/else if
  - Sintaxe Alternativa para estruturas de controle
  - while
  - do-while
  - for
  - foreach
  - break
  - continue
  - switch
  - match
  - declare
  - return
  - require
  - include
  - require_once
  - include_once
  - goto
- Funções
  - Funções definidas pelo usuário
  - Parâmetros e argumentos de funções
  - Retornando valores
  - Funções variáveis
  - Funções internas
  - Funções anônimas
  - Funções de Seta
  - Sintaxe de Chamáveis de Primeira Classe
- Classes e Objetos
  - Introdução
  - O Básico
  - Propriedades
  - Ganchos de Propriedade
  - Constantes de Classe
  - Autocarregamento de Classes
  - Construtores e Destrutores
  - Visibilidade
  - Herança de Objetos
  - Operador de Resolução de Escopo (::)
  - Palavra-Chave 'static'
  - Abstração de Classes
  - Interfaces de Objetos
  - Traits
  - Classes Anônimas
  - Sobrecarga
  - Iteração de Objetos
  - Métodos Mágicos
  - final
  - Clonando Objetos
  - Comparando Objetos
  - Vinculações Estáticas Tardias
  - Objetos e Referências
  - Serialização de Objetos — Serialização de Objetos - Objetos em sessões
  - Covariância e Contravariância
  - Objetos Lentos
  - Lista de alterações da POO
- Namespaces
  - Visão Geral — Visão geral de Namespaces
  - Namespaces — Definindo namespaces
  - Sub-namespaces — Declarando sub-namespaces
  - Definindo vários namespaces no mesmo arquivo
  - Fundamentos — Usando namespaces: Fundamentos
  - Namespaces e recursos de linguagem dinâmica
  - Palavra-chave namespace e __NAMESPACE__ — Palavra-chave namespace e constante __NAMESPACE__
  - Apelidando e Importando — Usando namespaces: Apelidando/Importando
  - Espaço Global
  - Recorrendo ao espaço global — Usando namespaces: recorrendo ao espaço global para funções e constantes
  - Regras de resolução de nomes
  - Perguntas Frequentes — Perguntas Frequentes: Coisas que você precisa saber sobre namespaces
- Enumerações
  - Visão Geral das Enumerações
  - Enumerações Básicas
  - Enumerações Apoiadas
  - Métodos de enumerações
  - Métodos estáticos de enumerações
  - Constantes de enumeração
  - Traits
  - Valores de enumeração em expressões constantes
  - Diferenças de objetos
  - Listagem de valores
  - Serialização
  - Porque enumerações não são extensíveis
  - Exemplos
- Erros
  - Básico
  - Erros no PHP 7
- Exceções
  - Estendendo exceções
- Fibers
- Geradores
  - Geradores, visão geral
  - Sintaxe do Gerador
  - Comparando geradores com objetos Iterator
- Atributos
  - Visão geral dos atributos
  - Sintaxe de Atributo
  - Lendo Atributos com a API Reflection
  - Declarando Classes de Atributos
- Referências
  - O que são referências
  - O que as referências fazem
  - O que referências não são
  - Passagem por referência
  - Retornando referências
  - Destruindo referências
  - Demonstrando referências
- Variáveis predefinidas
  - Superglobais — Variáveis nativas que estão sempre disponíveis em todos escopos
  - $GLOBALS — Referencia todas variáveis disponíveis no escopo global
  - $_SERVER — Informação do servidor e ambiente de execução
  - $_GET — Variáveis de string de consulta
  - $_POST — Dados de formulário de requisições POST HTTP
  - $_FILES — Variáveis de Upload de Arquivos HTTP
  - $_REQUEST — Variáveis de requisição HTTP
  - $_SESSION — Variáveis de sessão
  - $_ENV — Variáveis de ambiente
  - $_COOKIE — Cookies HTTP
  - $php_errormsg — A mensagem de erro anterior
  - $http_response_header — Cabeçalhos de resposta HTTP
  - $argc — O número de argumentos passados para o script
  - $argv — Array de argumentos passados para o script
- Exceções predefinidas
  - Exception
  - ErrorException
  - ClosedGeneratorException — A classe ClosedGeneratorException
  - Error
  - ArgumentCountError
  - ArithmeticError
  - AssertionError
  - DivisionByZeroError
  - CompileError
  - ParseError
  - TypeError
  - ValueError
  - UnhandledMatchError
  - FiberError
  - RequestParseBodyException
- Interfaces e Classes predefinidas
  - Traversable — A interface Traversable
  - Iterator — A interface Iterator
  - IteratorAggregate — A interface IteratorAggregate
  - InternalIterator — A classe InternalIterator
  - Throwable — A classe Throwable
  - Countable — A interface Countable
  - ArrayAccess — A interface ArrayAccess
  - Serializable — A interface Serializable
  - Closure — A classe Closure
  - stdClass — A classe stdClass
  - Generator — A classe Generator
  - Fiber — A classe Fiber
  - WeakReference — A classe WeakReference
  - WeakMap — A classe WeakMap
  - Stringable — A interface Stringable
  - UnitEnum — A interface UnitEnum
  - BackedEnum — A interface BackedEnum
  - SensitiveParameterValue — A classe SensitiveParameterValue
  - __PHP_Incomplete_Class — A classe __PHP_Incomplete_Class
- Atributos Predefinidos
  - Attribute — O atributo Attribute
  - AllowDynamicProperties — O atributo AllowDynamicProperties
  - DelayedTargetValidation — O atributo DelayedTargetValidation
  - Deprecated — O atributo Deprecated
  - NoDiscard — O atributo NoDiscard
  - Override — O atributo Override
  - ReturnTypeWillChange — O atributo ReturnTypeWillChange
  - SensitiveParameter — O atributo SensitiveParameter
- Opções e parâmetros de contexto
  - Opções de contexto de Socket — Lista de opções de contexto de Socket
  - Opções de contexto do HTTP — Lista de opções de contexto do HTTP
  - Opções de contexto do FTP — Lista de opções de contexto do FTP
  - Opções de contexto de SSL — Lista de opções de contexto de SSL
  - Opções de contexto do Phar — Lista de opções de contexto do Phar
  - Parâmetros de contexto — Listagem de parâmetros de contexto
  - Opções de contexto para Zip — Lista de opções de contexto de Zip
  - Opções de contexto Zlib — Lista de opções de contexto de Zlib
- Protocolos e empacotadores suportados
  - file:// — Acessando o sistema de arquivos local
  - http:// — Acessando URLs HTTP(s)
  - ftp:// — Acessando URLs FTP(s)
  - php:// — Acessando vários fluxos de E/S
  - zlib:// — Fluxos de compactação
  - data:// — Dados (RFC 2397)
  - glob:// — Encontra caminhos que correspondem a um padrão
  - phar:// — Arquivo PHP
  - ssh2:// — Shell Seguro 2
  - rar:// — RAR
  - ogg:// — Fluxos de áudio
  - expect:// — Fluxos de Interação entre Processos

# Segurança

# Introdução

PHP é uma linguagem poderosa e um interpretador, seja incluído em um servidor web como um módulo ou executado separadamente como binário CGI, é possível acessar arquivos, executar comandos e abrir conexões de rede no servidor. Essas propriedades fazem qualquer coisa executando em um servidor web inseguras por padrão. PHP é desenhado especificamente para ser uma linguagem mais segura para escrever programas CGI que Perl ou C, e com a escolha correta de opções de configuração em tempo compilação ou de execução, e práticas corretas de programação, ela pode dar a combinação exata de liberdade e segurança que você precisa.

Como existem diferentes maneiras de utilizar o PHP, existem várias opções de configuração controlando seu comportamento. Um grande leque de opções garante que você pode usar o PHP para vários propósitos, mas também significa que existem combinações dessas opções e configurações do servidor que resultam em uma instalação insegura.

A flexibilidade de configuração do PHP é comparável com a flexibilidade de código. PHP pode ser usado para montar um servidor de aplicações completo, com todo o poder de um usuário shell, ou pode ser usado para inclusão simples de arquivos no lado do servidor com pouco risco em um ambiente bem controlado. Como montar o ambiente, e o quão seguro ele é, depende muito do desenvolvedor.

Esse capítulo começa com alguns conselhos genéricos de segurança, explica as diferentes combinações de opções de configuração e as situações nas quais elas podem ser usadas com segurança e descreve diferentes considerações quanto ao desenvolvimento para diferentes níveis de segurança.

# Considerações Gerais

Um sistema completamente seguro é virtualmente impossível de se conseguir, então uma abordagem freqüentemente usada em segurança é um compromisso entre risco e usabilidade. Se cada variável enviada pelo usuário precisar de duas formas de validação biométrica (como escaneamento de retina e impressão digital), você teria um nível de checagem extremamente alto. Demoraria meia hora para preencher um formulário mais ou menos complexo, o que incentiva os usuários a achar maneiras de burlar a segurança.

A melhor segurança é frequentemente aquele preenche os requerimentos sem obstruir o usuário a fazer o seu trabalho, ou sobrecarregando o programador com complexidade excessiva. De fato, alguns ataques de segurança exploram esse tipo de segurança super-produzida, que tende a degradar com o tempo.

Uma frase que vale a pena lembrar: Um sistema é tão bom quanto o elo mais fraco na corrente. Se todas as transações são maciçamente registradas baseado no tempo, localização, tipo de transação, etc. mas o usuário só é verificado baseado em um único cookie, a validade de ligar os usuários ao registro de transação torna-se muito fraca.

Quando estiver testando, tenha em mente que você não será capaz de testar todas as possibilidades nem mesmo para as páginas mais simples. A entrada que você pode esperar será totalmente diferente da entrada dada por um empregado irritado, um cracker com meses livres para tentar quebrar o sistema, ou um gato andando pelo teclado. Por isso é melhor olhar para o código da perspectiva lógica, para discernir onde dados inesperados podem ser introduzidos, e depois seguir onde o mesmo é modificado, reduzido ou amplificado.

A Internet está cheia de gente tentando fazer o próprio nome quebrando o código dos outros, derrubando sites, enviando conteúdo indevido e de outras formas fazendo seu dia interessante. Não importa se você tem um site grande ou pequeno, você é um alvo simplesmente por estar online, tendo um servidor que pode ser conectado. Muitos programas de cracking não discernem por tamanho, eles simplesmente vasculham blocos gigantes de IPs procurando por vítimas. Tente não se tornar um.

# Instalando como binário CGI

## Índice

- Ataque Possível
- Caso 1: apenas arquivos públicos são disponibilizados
- Caso 2: usando cgi.force_redirect
- Caso 3: configurando doc_root ou user_dir
- Caso 4: Interpretador do PHP fora da árvore de diretórios do servidor web

## Ataque Possível

Usando o PHP como binário CGI é uma opção de instalação que por alguma razão não deseja integrar o PHP como um módulo no servidor (como o Apache), ou usará o PHP com tipos diferentes de empacotadores CGI para criar ambientes chroot e setuid seguros para os scripts. Esta configuração geralmente envolve a instalação do binário php executável para o diretório cgi-bin do servidor web. A CERT Advisory » CA-96.11 recomenda não colocar nenhum interpretador em cgi-bin. Mesmo se o binário php possa ser usado como um interpretador autônomo, o PHP foi projetado para evitar os ataques que essa forma de instalação torna possível:

- Acessar arquivos de sistema: http://my.host/cgi-bin/php?/etc/passwd A informação de consulta em uma URL depois da interrogação (`?`) é passada como argumentos de linha de comando para o interpretador pela interface CGI. Normalmente os interpretadores abrem e executam o arquivo especificado como primeiro argumento na linha de comando. Quando invocado como binário CGI, o php se recusa a interpretar os argumentos de linha de comando.
- Acessar qualquer domento web no servidor: http://my.host/cgi-bin/php/secret/doc.html A parte de informação de caminho da URL depois do nome do binário do PHP, /secret/doc.html é convencionalmente usada para especificar o nome do arquivo a ser aberto e interpretado pelo programa CGI Normalmente algumas diretivas de configuração do servidor web (Apache: `Action`) são usadas para redirecionar requisições para documentos como http://my.host/secret/script.php para o interpretados do PHP. Dessa maneira, o servidor web primeiro checa as permissões de acesso ao diretório /secret, e depois cria a requisição redirecionada http://my.host/cgi-bin/php/secret/script.php. Infelizmente, se a requisição é dada originalmente nessa forma, a checagem de permissão não é feita para o arquivo /secret/script.php, mas apenas para o arquivo /cgi-bin/php. Dessa maneira qualquer usuário que pode acessar /cgi-bin/php pode acessar quaisquer documentos protegidos no servidor web. No PHP, as diretivas de tempo de execução cgi.force_redirect, doc_root e user_dir podem ser usadas para prevenir esse ataque, se a árvore de documentos do servidor tiver qualquer diretório com restrições de acesso. Veja abaixo a explicação completa das diferentes combinações.

## Caso 1: apenas arquivos públicos são disponibilizados

Se o seu servidor não tiver qualquer conteúdo que não seja restringido por senha ou por IP, não há necessidade para essas opções de configuração. Se seu servidor web não permitir que você faça redirecionamento, ou o servidor não tem uma maneira de comunicar ao binário PHP que a requisição é uma redirecionada de maneira segura, você pode especificar a opção --enable-force-cgi-redirect no script configure. Você ainda tem que assegurar que os seus scripts PHP não confiem com uma ou outra maneira de chamar o script, nem diretamente http://my.host/cgi-bin/php/dir/script.php nem por redirecionamento http://my.host/dir/script.php.

Redirecionamento pode ser configurado no Apache usando `AddHandler` e diretivas `Action` (veja abaixo).

## Caso 2: usando `cgi.force_redirect`

A diretiva de configuração cgi.force_redirect impede que php seja chamado diretamente com uma URL do tipo http://my.host/cgi-bin/php/secretdir/script.php. Ao invés disso, PHP só irá executar dessa forma se tiver passado por um servidor web com essa diretiva.

Normalmente o redirecionamento na configuração do Apache é feita com as seguintes diretivas:

    Action php-script /cgi-bin/php
    AddHandler php-script .php

Essa opção só foi testada com o servidor Apache, e confia no Apache para configurar a variável de ambiente não-padrão do CGI REDIRECT_STATUS em requisições redirecionadas. Se seu servidor web não suporta nenhuma maneira de dizer se a requisição é direta ou redirecionada, você não pode usar essa opção e você deve usar uma das outras maneiras de executar a versão do CGI documentada aqui.

## Caso 3: configurando doc_root ou user_dir

Para incluir conteúdo ativo, como script e executáveis, nos diretórios de documentos do servidor é algumas vezes considerada uma prática insegura. Se, por conta de um erro de configuração, os scripts não são executados mas mostrados como documentos HTML normais, isso pode resultar em vazamento de propriedade intelectual ou informação de segurança, como senhas. Portanto, muitos administradores preferem configurar outra estrutura de diretório para scripts que são acessíveis apenas pelo CGI do PHP, e, portanto, sempre interpretados e não enviados ao navegador.

Além disso, se o método para assegurar que as requisições não são redirecionadas, como descrito na seção anterior, não estiver disponível, é necessário configurar um doc_root no script que seja diferente do diretório raiz dos documentos do servidor web.

Você pode configurar a raiz de documentos dos scripts PHP pela diretiva de configuração doc_root no arquivo de configuração, ou você pode criar a variável de ambiente PHP_DOCUMENT_ROOT. Se ela existir, a versão CGI do PHP sempre construirá o nome de arquivo para ser aberto com esse `doc_root` e a informação de caminho na requisição, para assegurar que nenhum script é executado fora desse diretório (exceto por `user_dir` abaixo).

Outra opção utilizável é user_dir. Quando `user_dir` for indefinido, a única coisa controlando o arquivo aberto é `doc_root`. Abrir uma URL como http://my.host/~user/doc.php não resulta em abrir um arquivo no diretório home de users, mas um arquivo chamado ~user/doc.php dentro de `doc_root` (sim, um nome de diretório começando com til [`~`]).

Se `user_dir` estiver, por exemplo, definido para public_php, uma requisição como http://my.host/~user/doc.php abrirá o arquivo chamado doc.php no diretório chamado public_php dentro do diretório home do usuário. Se o home do usuário é /home/user, o arquivo executado é /home/user/public_php/doc.php.

A expansão de `user_dir` acontece independente da configuração de `doc_root`, para que você possa controlar a raiz de documentos e de acesso de diretório do usuário separadamente.

## Caso 4: Interpretador do PHP fora da árvore de diretórios do servidor web

Uma maneira muito segura é colocar o interpretador do PHP em algum lugar longe dos arquivos da árvore de diretórios do servidor. Em /usr/local/bin, por exemplo. A única desvantagem real para essa opção é que você terá que colocar uma linha similar à:

    #!/usr/local/bin/php

como a primeira linha de qualquer arquivo contento tags do PHP. Você também terá que tornar o arquivo executável. Isso é, tratá-lo exatamente como você trataria qualquer script CGI escrito em Perl ou sh ou qualquer outra linguagem de script comum que usa o mecanismo de escape de shell `#!` para ser executado.

Para fazer o PHP tratar as informações de PATH_INFO e PATH_TRANSLATED corretamente com essa configuração, o interpretador do PHP deve ser compilado com a opção de configure --enable-discard-path.

# Instalando como módulo do Apache

Quando o PHP é usado como módulo do Apache, ele herda as permissões do usuário do Apache (normalmente as do usuário "nobody"). Isso tem vários impactos de segurança e autorização. Por exemplo, se você estiver usando o PHP para acessar um banco de dados, a menos que o banco de dados tenha um controle de acesso interno, você terá que fazer com que o banco de dados seja acessível ao usuário "nobody". Isso significa que um script malicioso pode acessar e modificar o banco de dados, mesmo sem um usuário e senha. É possível que um web spider possa passar em uma página web de administração do banco de dados e remover todos os bancos de dados. Você pode se proteger contra isso usando autorização do Apache, ou você pode desenvolver seu modelo de acesso próprio usando LDAP, arquivos .htaccess, etc. e incluir esse código como parte dos seus scripts PHP.

Normalmente, uma vez que a segurança está estabelecida até esse ponto onde o usuário do PHP (no caso, o usuário apache) tem pouco risco atribuído a ele, você descobre que o PHP não tem permissão de escrita nos diretórios dos usuários. Ou talvez tenha sido proibido de acessar ou alterar bancos de dados. Também foi proibido de escrever arquivos, bons ou ruins, ou fazer transações de bancos de dados, boas ou ruins.

Um erro frequente de segurança feito até esse ponto é permitir ao Apache permissões de administrador (root), ou aumentar as habilidades do Apache de qualquer outra forma.

Aumentar as permissões do usuário do Apache para a de administrador é extremamente perigoso e pode comprometer o sistema inteiro, então executar com sudo, com chroot, ou então executar como root não deve ser considerado por aqueles que não são profissionais em segurança.

Existem algumas soluções mais simples. Usando a diretiva open_basedir pode-se controlar e restringir quais diretórios o PHP tem permissão de usar. Você também pode configurar áreas exclusivas para o Apache, restringir todas as atividades web para arquivos que não sejam de algum usuário ou do sistema.

# Segurança da Sessão

É importante manter o gerenciamento de sessão HTTP seguro. A segurança relacionada a sessão está descrita na seção Segurança de Sessão da referência Módulo de Sessão.

# Segurança do Sistema de Arquivos

## Índice

- Problemas relacionados aos bytes nulos (NUL)

O PHP está sujeito à segurança encontrada na maioria dos sistemas de servidor com respeito às permissões de arquivos e diretórios. Isso permite que seja controlado que arquivos no sistema podem ser lidos e por quem. É preciso ter cuidado com quaisquer arquivos que são lidos por todos para assegurar que eles podem ser lidos por todos os usuários que têm acesso ao sistema de arquivos.

Já que o PHP foi projetado para permitir acesso em nível de usuário ao sistema de arquivos, é possível escrever um script PHP que permitirá ler arquivos do sistema como o /etc/passwd, modificar suas conexões de rede, enviar inúmeros trabalhos de impressão, etc. Isso tem algumas implicações óbvias, já que é necessário garantir que os arquivos lidos e gravados são apropriados.

Considere o seguinte script, onde um usuário indica que quer apagar um arquivo no seu diretório "home". Isso presume uma situação onde uma interface web PHP é usada regularmente para controle de arquivos, então o usuário do Apache tem permissão de apagar arquivos nos diretórios "home" dos usuários.

Exemplo #1 Verificação fraca de variáveis resulta em....

    <?php

    // Remove um arquivo do diretório "home" do usuário
    $username = $_POST['user_submitted_name'];
    $userfile = $_POST['user_submitted_filename'];
    $homedir  = "/home/$username";

    unlink("$homedir/$userfile");

    echo "O arquivo foi removido!";

    ?>

Já que o nome do usuário e do arquivo são enviados pelo formulário, um usuário pode enviar um nome de usuário e de arquivo que pertença a outra pessoa, e apagá-lo, mesmo que eles não tenham permissão para fazê-lo. Nesse caso, é preciso ter alguma outra forma de autenticação. Considere o que poderia acontecer se as variáveis enviadas forem `"../etc/"` e `"passwd"`. O código então leria efetivamente:

Exemplo #2 ... um ataque ao sistema de arquivos

    <?php

    // Remove um arquivo de qualquer lugar no disco rígido
    // que o usuário do PHP tenha acesso. Se o PHP tiver acesso de administrador (root):
    $username = $_POST['user_submitted_name']; // "../etc"
    $userfile = $_POST['user_submitted_filename']; // "passwd"
    $homedir  = "/home/$username"; // "/home/../etc"

    unlink("$homedir/$userfile"); // "/home/../etc/passwd"

    echo "O arquivo foi removido!";

    ?>

Existem duas medidas importantes que você deve tomar para prevenir esses problemas.

- Dar permissões limitadas ao usuário web binário do PHP.
- Checar todas as variáveis que são enviadas.

Aqui temos um script melhorado:

Exemplo #3 Checagem com mais segura do nome do arquivo

    <?php

    // Remove um arquivo do disco rígido que o
    // usuário do PHP tenha acesso.
    $username = $_SERVER['REMOTE_USER']; // usando um mecanismo de autenticação
    $userfile = basename($_POST['user_submitted_filename']);
    $homedir  = "/home/$username";

    $filepath = "$homedir/$userfile";

    if (file_exists($filepath) && unlink($filepath)) {
        $logstring = "Removido $filepath\n";
    } else {
        $logstring = "Falha ao remover $filepath\n";
    }

    $fp = fopen("/home/logging/filedelete.log", "a");
    fwrite($fp, $logstring);
    fclose($fp);

    echo htmlentities($logstring, ENT_QUOTES);

    ?>

No entanto, ele ainda possui falhas. Se seu sistema de autenticação permitir que os usuários criem seus próprios logins, e um usuário escolher o login `"../etc/"`, o sistema está novamente exposto. Por essa razão, é preferível escrever uma verificação mais personalizada:

Exemplo #4 Verificação mais segura do nome do arquivo

    <?php

    $username     = $_SERVER['REMOTE_USER']; // usando um mecanismo de autenticação
    $userfile     = $_POST['user_submitted_filename'];
    $homedir      = "/home/$username";

    $filepath     = "$homedir/$userfile";

    if (!ctype_alnum($username) || !preg_match('/^(?:[a-z0-9_-]|\.(?!\.))+$/iD', $userfile)) {
        die("Usuário/arquivo inválido");
    }

    // etc.

    ?>

Dependendo do sistema operacional, existe uma variedade enorme de arquivos com os quais se preocupar, incluindo dispositivos (/dev/ ou COM1), arquivos de configuração (arquivos /etc/ e arquivos `.ini`), áreas de armazenamento de arquivo bem conhecidas (/home/, My Documents), etc. Por essa razão, normalmente é mais fácil criar uma política onde se proíbe tudo exceto aquilo que for explicitamente permitido.

## Problemas relacionados aos bytes nulos (NUL)

Como o PHP usa funções em C para operações relacionadas ao sistema de arquivos, ele pode lidar com bytes nulos de maneira inesperada. Como bytes nulos denotam fim de string em C, strings que os contém não serão consideradas de forma inteira, mas apenas até que um byte nulo ocorra. O seguinte exemplo mostra um código vulnerável que demonstra esse problema:

Exemplo #1 Script vulnerável a bytes nulos

    <?php

    $file = $_GET['file']; // "../../etc/passwd\0"

    if (file_exists('/home/wwwrun/' . $file. '.php')) {
        // file_exists retornará true porque o arquivo /home/wwwrun/../../etc/passwd existe
        include '/home/wwwrun/' . $file . '.php';
        // o arquivo /etc/passwd será incluído

    }

    ?>

Portanto, qualquer string comprometida que é usada em uma operação de sistema de arquivos deve sempre ser validada corretamente. Aqui está uma versão melhorada do exemplo anterior:

Exemplo #2 Validando entrada corretamente

    <?php

    $file = $_GET['file'];

    // Autorizando valores possíveis
    switch ($file) {
        case 'main':
        case 'foo':
        case 'bar':
            include '/home/wwwrun/include/' . $file . '.php';
            break;
        default:
            include '/home/wwwrun/include/main.php';
    }

    ?>

# Segurança de Bancos de Dados

## Índice

- Desenhando Bancos de Dados
- Conectando com o Banco de Dados
- Modelo de Armazenamento Criptografado
- Injeção de SQL

Hoje em dia, bancos de dados são componentes cardinais de qualquer aplicação web permitindo que websites forneçam conteúdo dinâmico variável. Uma vez que informações muito sensíveis e/ou secretas podem ser guardadas em um banco de dados, proteger seus bancos de dados é essencial.

Para retirar ou guardar qualquer informação, você precisa conectar-se ao banco de dados, enviar uma consulta (query) legítima, pegar o resultado e fechar a conexão. Atualmente, a linguagem mais usada para consulta nessa interação é a Structured Query Language (SQL). Veja como um atacante pode manipular uma consulta SQL.

O PHP não pode proteger seu banco de dados sozinho. As seções a seguir tentam ser uma introdução básica em relação a como acessar e manipular banco de dados a partir de scripts PHP.

É preciso manter em mente essa regra simples: defesa em profundidade. Em quanto mais lugares há ações para aumentar a proteção do banco de dados, menor a probabilidade de um atacante ter sucesso em expor ou abusar de qualquer informação guardada. Uma boa modelagem do esquema (schema) do banco de dados e da aplicação para lidar com os maiores medos.

## Desenhando Bancos de Dados

O primeiro passo é sempre criar o banco de dados, a não ser que você queira usar um de terceiros. Quando um banco de dados é criado, ele é atribuído a um dono, o mesmo que executou os comandos de criação. Normalmente, só o dono (ou um superusuário) pode fazer algo com os objetos naquele banco de dados, e para permitir que outros usuários usem, privilégios devem ser concedidos.

Aplicações nunca devem conectar-se ao banco de dados como seu dono ou um superusuário, porque esses usuários podem executar qualquer consulta que quiserem como, por exemplo, modificar o esquema (ex.: destruindo tabelas) ou removendo seu conteúdo completamente.

Devem ser criados usuários de bancos de dados diferentes para cada aspecto da sua aplicação com direitos bem limitados aos objetos do banco de dados. Apenas os privilégios necessários devem ser concedidos, e deve-se evitar que o mesmo usuário possa interagir com o banco de dados em casos de uso diferentes. Isso significa que se invasores conseguirem acessar seu banco de dados usando credenciais da sua aplicação, eles só podem afetar o banco tanto quanto sua aplicação poderia.

## Conectando com o Banco de Dados

Deve-se estabelecer as conexões sobre SSL para criptografar as comunicações cliente/servidor para aumentar a segurança, ou você pode usar ssh para criptografar a conexão de rede entre clientes e o servidor de banco de dados. Se uma dessas opções for usada, o monitoramento do seu tráfego e obtenção de informação sobre seu banco de dados serão dificultados para um possível atacante.

## Modelo de Armazenamento Criptografado

SSL/SSH protege dados transitando de um cliente para o servidor, mas não protege os dados guardados em um banco de dados. SSL é um protocolo on-the-wire.

Uma vez que o atacante ganhe acesso direto ao seu banco de dados (perpassando o servidor web), os dados armazenados podem ser expostos ou usados inadequadamente, a não ser que a informação seja protegida pelo banco em si. Criptografar os dados é uma boa maneira de diminuir essa ameaça, mas poucos bancos de dados oferecem esse tipo de criptografia de dados.

A maneira mais fácil de contornar esse problema é primeiro criar seu próprio pacote de criptografia, e então usá-lo no seus scripts PHP. O PHP pode ajudá-lo com várias extensões, tais como OpenSSL e Sodium, cobrindo uma grande variedade de algoritmos de criptografia. O script criptografa os dados antes de inseri-los no banco de dados e descriptografa quando os recupera. Veja as referências para outros exemplos de como a criptografia funciona.

### Hashing

No caso de dados realmente ocultos, se sua representação bruta não for necessária (ou seja, não será exibido), o hashing deve ser levado em consideração. O exemplo conhecido de hashing é armazenar o hash criptográfico de uma senha em um banco de dados, em vez da própria senha.

As funções password fornecem uma maneira conveniente para criar o hash de dados confidenciais e trabalhar com esses hashes.

password_hash() é usado para criar o hash uma determinada string usando o algoritmo mais forte atualmente disponível e password_verify() verifica se a senha fornecida corresponde ao hash armazenado no banco de dados.

Exemplo #1 Usando campo de senha hasheado

    <?php

    // guardando hash da senha
    $query  = sprintf("INSERT INTO users(name,pwd) VALUES('%s','%s');",
                pg_escape_string($username),
                password_hash($password, PASSWORD_DEFAULT));
    $result = pg_query($connection, $query);

    // consultando se o usuário enviou a senha correta
    $query = sprintf("SELECT pwd FROM users WHERE name='%s';",
                pg_escape_string($username));
    $row = pg_fetch_assoc(pg_query($connection, $query));

    if ($row && password_verify($password, $row['pwd'])) {
        echo 'Bem-vindo, ' . htmlspecialchars($username) . '!';
    } else {
        echo 'Autenticação falhou para ' . htmlspecialchars($username) . '.';
    }

    ?>

## Injeção de SQL

A injeção de SQL é uma técnica onde o agressor explora falhas no código da aplicação responsável em criar e povoar instruções SQL. O agressor pode assim obter acesso privilegiado a partes da aplicação, extrair todos os dados do banco de dados, alterar os dados, e até mesmo executar comandos perigosos em nível do sistema onde o banco de dados roda. A falha ocorre quando desenvolvedores concatenam ou interpolam dados arbitrários em instruções SQL.

Exemplo #1 Dividindo o conjunto de resultados em páginas ... e criando super-usuários (PostgreSQL)

No exemplo a seguir, dados de usuário são diretamente interpolados na instrução SQL, permitindo ao agressor obter uma conta de superusuário no banco de dados.

    <?php

    $offset = $_GET['offset']; // Usando os dados sem validação!
    $query  = "SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET $offset;";
    $result = pg_query($conn, $query);

    ?>

Usuários normais clicam nos links 'próxima' e 'anterior' onde $offset é codificado na URL. O script espera que o valor de $offset seja um número decimal. No entanto, e se alguém tentar quebrar a instrução SQL, utilizando a seguinte URL:

    0;
    insert into pg_shadow(usename,usesysid,usesuper,usecatupd,passwd)
        select 'crack', usesysid, 't','t','crack'
        from pg_shadow where usename='postgres';
    --

Se isso acontecesse, então o script daria de presente acesso de superusuário ao atacante. Perceba que `0;` é para fornecer uma deslocamento válido para a consulta original e terminá-la.

> Nota:

> É uma técnica comum forçar o avaliador de SQL ignorar o resto da consulta escrita pelo desenvolvedor com `--`, que é o sinal de comentário no SQL.

Uma maneira de ganhar senhas é desviar suas páginas de resultado de busca. A única coisa que o atacante precisa fazer é ver se alguma variável enviada é usada em um comando SQL que não é tratado corretamente. Esses filtros podem ser configurados de forma a personalizar cláusulas `WHERE, ORDER BY, LIMIT` e `OFFSET` em cláusulas `SELECT` Se seu banco de dados suporta o construtor `UNION`, o atacante pode tentar adicionar uma consulta inteira à consulta original para listar senhas de uma tabela arbitrária. É altamente recomendável gravar apenas hashs criptográficos das senhas, ao invés de gravar a senha.

Exemplo #2 Listando artigos ... e algumas senhas (qualquer banco de dados)

    <?php

    $query  = "SELECT id, name, inserted, size FROM products
               WHERE size = '$size'";
    $result = odbc_exec($conn, $query);

    ?>

A parte estática da consulta pode ser combinada com outro comando `SELECT` que revela todas as senhas:

    '
    union select '1', concat(uname||'-'||passwd) as name, '1971-01-01', '0' from usertable;
    --

Instruções `UPDATE` e `INSERT` também podem ser abusadas em ataques.

Exemplo #3 De recuperando uma senha ... para ganhando mais privilégios (qualquer banco de dados)

    <?php
    $query = "UPDATE usertable SET pwd='$pwd' WHERE uid='$uid';";
    ?>

Se um usuário malicioso envia o valor `' or uid like'%admin%` para $uid para mudar a senha do administrador, ou simplesmente configura $pwd para `hehehe', trusted=100, admin='yes` (com um espaço sobrando) para ganhar mais privilégios. Então, a consulta ficará retorcida:

    <?php

    // $uid: ' or uid like '%admin%
    $query = "UPDATE usertable SET pwd='...' WHERE uid='' or uid like '%admin%';";

    // $pwd: hehehe', trusted=100, admin='yes
    $query = "UPDATE usertable SET pwd='hehehe', trusted=100, admin='yes' WHERE
    ...;";

    ?>

Pode parecer que o agressor precisa saber alguma coisa da arquitetura do banco para conduzir um ataque efetivo, mas obter esse tipo de informação é geralmente bem simples. Por exemplo, o código pode ser parte de um sistema open source e publicamente disponível. Esse tipo de informação pode também pode ser obtido em sistemas de código fechado -- mesmo no caso dele estar ofuscado ou compilado -- e mesmo através do seu próprio código, através de mensagens de erro. Outros métodos incluem o uso de nomes típicos de tabelas e colunas. Por exemplo, um formulário de login normalmente utiliza tabelas chamadas 'user' com colunas chamadas 'id', 'username', e 'password'.

Exemplo #4 Atacando o sistema de um banco de dados (MSSQL Server)

Um exemplo assustador de como comandos do sistema operacional podem ser acessados em alguns bancos de dados.

    <?php

    $query  = "SELECT * FROM products WHERE id LIKE '%$prod%'";
    $result = mssql_query($query);

    ?>

Se o atacante enviar o valor `a%' exec master..xp_cmdshell 'net user test testpass /ADD' --` para $prod, então $query terá o valor:

    <?php

    $query  = "SELECT * FROM products
               WHERE id LIKE '%a%'
               exec master..xp_cmdshell 'net user test testpass /ADD'--";
    $result = mssql_query($query);

    ?>

O MSSQL Server executa comandos SQL em um lote incluindo um comando para adicionar um novo usuário para o banco de dados de contas locais. Se essa aplicação estiver sendo executada como `sa` e o serviço MSSQLSERVER estivesse sendo executado com privilégios suficientes, o atacante teria agora uma conta com a qual poderia acessar essa máquina.

> Nota:

> Alguns dos exemplos acima estão ligados a bancos específicos. Isso não significa que um ataque similar é impossível contra outros produtos. Seu servidor de banco de dados pode ter uma vulnerabilidade similar de outra maneira.

Imagem cortesia de » xkcd

### Técnicas para evitar ataques

A maneira recomendada de evitar ataques de injeção de SQL é informar todos os dados em instruções preparadas. Usar instruções parametrizadas não é o suficiente para evitar SQL injection, mas é a maneira mais rápida e segura de fornecer dados a instruções SQL. Todos os dados dinâmicos em `WHERE`, `SET`, e `VALUES` precisam ser substituídos por âncoras. Os dados em si serão informados durante a execução, e serão enviados separadamente do comando SQL.

Informar dados via parâmetros deve ser utilizado apenas para dados. Outras partes dinâmicas de uma instrução SQL precisa ser filtrada por uma lista prévia e conhecida de valores válidos.

Exemplo #5 Evitando SQL injection ao utilizar instruções preparadas PDO

    <?php

    // A parte SQL dinâmica precisa é validada a partir de dados prévios
    $sortingOrder = $_GET['sortingOrder'] === 'DESC' ? 'DESC' : 'ASC';
    $productId = $_GET['productId'];
    // O SQL é preparado utilizando âncoras
    $stmt = $pdo->prepare("SELECT * FROM products WHERE id LIKE ? ORDER BY price {$sortingOrder}");
    // O valor é informado, incluindo caracteres curinga
    $stmt->execute(["%{$productId}%"]);

    ?>

Instruções preparadas são fornecidas no PDO, no MySQLi, e por outras bibliotecas de bancos de dados.

Ataques de injeção de SQL são principalmente baseados na exploração de código que não é escrito pensando em segurança. Nunca confie em nenhum dado enviado pelo usuário, e menos ainda em dados enviados pelo navegador, mesmo que o dado venha de um option box ou um campo hidden, nem mesmo cookies. O primeiro exemplo mostra como uma instrução SQL muito simples pode causar um dano desastroso.

Uma estratégia de defesa envolve várias boas práticas de codificação:

- Nunca se conecte ao banco de dados utilizando um usuário administrador ou dono dos objetos do banco. Sempre utilize usuários com privilégios mínimos.
- Sempre verifique se o dado enviado tem o tipo esperado. O PHP possui várias funções de validação de dados, de coisas simples como as encontradas em funções de variável e em funções de string (por exemplo, is_numeric(), ctype_digit()) a coisas mais avançadas como suporte a expressões regulares compatíveis com Perl.
- Se a aplicação espera dados numéricos, considere verificar os dados com ctype_digit(), ou modificar os dados utilizando settype(), ou ainda reformatar o dado com sprintf().
- Se o banco de dados não suportar enviar dados por parâmetros, então é necessário escapar todos os dados de usuário não numéricos, passando o dado para funções específicas de escape do banco (por exemplo mysql_real_escape_string(), sqlite_escape_string(), etc). Funções genéricas como addslashes() são úteis apenas em contextos específicos (por exemplo, no MySQL é possível modificar o comportamento das aspas com NO_BACKSLASH_ESCAPES), então o escape específico é necessário.
- Nunca imprima nenhum dado ou erro específico do banco de dados, especialmente dados referentes a schema. Veja também exibição de erros e funções de manipulação e log de erros.

Além disso, você ganha em relatar consultas ou dentro do script ou no próprio banco de dados, se esse suportar. Obviamente, o relatório é incapaz de prevenir qualquer tentativa danosa, mas pode ser útil para ajudar a rastrear qual aplicação foi atacada. O relatório não é útil em si, mas através da informação que ele contém. Mais detalhes geralmente é melhor que menos.

# Relatando Erros

Com relação a segurança, relatório de erros é uma faca de dois gumes. Pode beneficiar o aumento da segurança, ou fornecer informação ao atacante.

Uma tática padrão de ataque envolve determinar como um sistema funciona entrando dados incorretos e checando os tipos e contextos dos erros que são retornados. Isso permite que um cracker sonde por informações sobre o servidor, para determinar possíveis fraquezas. Por exemplo, se um atacantes tinha recolhido informação sobre uma página baseado em uma submissão de dados anterior, ele pode tentar sobrescrever variáveis, ou modificá-las:

Exemplo #1 Atacando variáveis com uma página HTML personalizada

    <form method="post" action="attacktarget?username=badfoo&amp;password=badfoo">
    <input type="hidden" name="username" value="badfoo" />
    <input type="hidden" name="password" value="badfoo" />
    </form>

Os erros do PHP que são retornados normalmente podem ser úteis para um desenvolvedor que está tentando depurar um script, indicando coisas como a função ou arquivo que falhou, o arquivo PHP no qual a falha ocorreu, e o número da linha de código causadora da falha. Toda essa informação pode ser explorada. Não é incomum para um desenvolvedor PHP usar show_source(), highlight_string(), ou highlight_file() como medidas de depuração, mas em um site de produção, isso pode expor variáveis ocultas, sintaxe incorreta, ou outra informações perigosas. Especialmente perigoso é rodar código de fontes conhecidas com tratadores de depuração integrados, ou usar técnicas de depuração comuns. Se o atacante pode determinar qual técnica geral você estiver usando, eles podem tentar, por força-bruta, enviar várias strings de depuração comuns para a página:

Exemplo #2 Explorando variáveis comuns de depuração

    <form method="post" action="attacktarget?errors=Y&amp;showerrors=1&amp;debug=1">
    <input type="hidden" name="errors" value="Y" />
    <input type="hidden" name="showerrors" value="1" />
    <input type="hidden" name="debug" value="1" />
    </form>

Independente do método de tratamento de erros, a habilidade de sondar um sistema por erros acaba dando informações úteis a um atacante.

Por exemplo, o próprio estilo de um erro genérico do PHP indica que o sistema está rodando o PHP. Se o atacante estava procurando por uma página `.html`, e queria sondar qual o back-end (para procurar fraquezas conhecidas no sistema) enviando dados incorretos, ele pode ser capaz de determinar que um sistema foi feito com PHP.

Uma função de erro pode indicar se o sistema pode está executando um engine de banco de dados específico, ou dar dicas de como uma página foi programada ou desenhada. Isso permite uma investigação profunda sobre portas abertas de bancos de dados, ou procurar por bugs específicos ou fraquezas de uma página. Enviando diferentes pedaços de dados ruins, por exemplo, um atacante pode determinar a ordem de autenticação em um script, (a partir da linha do erro) assim como sondar por exploits que podem ser aproveitados em diferentes partes do script.

Um erro geral do PHP ou do sistema de arquivos indicam quais permissões o servidor web tem, assim como a estrutura e organização dos arquivos no servidor web. Códigos de erros escritos pelo desenvolvedor podem agravar o problema, levando à exploração fácil de informação até então "escondida".

Existem três soluções principais para esse problema. A primeira é verificar exaustivamente todas as funções, e tentar compensar pelo volume dos erros. A segunda é desabilitar completamente os relatórios de erros no código de produção. A terceira é usar as funções personalizáveis de tratamento de erro do PHP para criar seu próprio tratador de erro. Dependendo da sua política de segurança, você pode perceber que todas são aplicáveis à sua situação.

Uma maneira de perceber esse problema antes que o pior aconteça é usar a diretiva error_reporting(), para ajudar a aumentar a segurança de seu código e achar uso de variáveis que pode ser perigoso. Ao testar o seu código, antes de colocar em produção, com `E_ALL`, você pode rapidamente encontrar áreas onde suas variáveis podem sofrer alterações nocivas ou modificações quaisquer. Uma vez que esteja pronto para produção, você deve ou desabilitar mensagens de erro completamente configurando a diretiva error_reporting() com o valor 0, ou desligar o envio de erros usando a opção `display_errors` do arquivo php.ini, para evitar sondagem do seu código. Se você escolher a segunda opção, você deve também definir o caminho para o arquivo de registro usando a diretiva `error_log`, e ligar a diretiva `log_errors`.

Exemplo #3 Encontrado variáveis perigosas com E_ALL

    <?php
    if ($username) { // Não inicializado ou verificado antes do uso
        $good_login = 1;
    }
    if ($good_login == 1) { // Se o teste acima falhar, não inicializado ou verificado antes do uso
        readfile ("/dados/altamente/sensiveis/index.html");
    }
    ?>

# Dados Enviados pelo Usuário

A maior fraqueza na maioria dos programas PHP não é inerente à linguagem em si, mas meramente um problema de código escrito desconsiderando a segurança. Por essa razão, você sempre deve investir um pouco de tempo considerando as implicações de um certo pedaço de código, para ter certeza que o dano possível se uma variável não esperada for submetida ao mesmo.

Exemplo #1 Uso Perigoso de Variáveis

    <?php
    // remove um arquivo do diretório home do usuário... ou talvez
    // de outra pessoa?
    unlink ($evil_var);

    // Escreve registro do acesso... ou talvez uma entrada em /etc/passwd?
    fwrite ($fp, $evil_var);

    // Executa algo trivial... ou rm -rf *?
    system ($evil_var);
    exec ($evil_var);

    ?>

Você sempre deve examinar cuidadosamente seu código para se assegurar que quaisquer variáveis sendo enviadas do navegador web estão sendo checadas de maneira correta, e faz a si mesmo as seguintes perguntas:

- Seu script só afetará os arquivos desejados?
- Dados incomuns ou indesejados podem ser utilizados?
- Esse script pode ser usado de maneiras não intencionadas?
- Ele pode ser usado em conjunto com outros scripts de maneira negativa?
- As transações serão registradas adequadamente?

Respondendo essas perguntas adequadamente enquanto escrevendo o script, ao invés de depois, previne a reescrita indesejada quando você precisar aumentar a segurança. Começando com essa linha de raciocínio, você não garante a segurança do seu sistema, mas pode ajudar a aumentá-la.

Melhore a segurança desabilitando configurações de conveniência que obscurecem a origem, validade ou integridade dos dados de entrada. A criação implícita de variáveis ​​e a entrada não verificada podem levar a vulnerabilidades como ataques de injeção e manipulação de dados.

Recursos como `register_globals` e `magic_quotes` (ambos removidos no PHP 5.4.0) contribuíram para esses riscos criando variáveis ​​automaticamente a partir da entrada do usuário e escapando dados inconsistentemente. Embora não esteja mais no PHP, riscos semelhantes persistem se o tratamento de entrada for mal gerenciado.

Habilite error_reporting(E_ALL) para ajudar a detectar variáveis ​​não inicializadas e validar a entrada. Use tipos estritos (declare(strict_types=1), introduzido no PHP 7) para reforçar a segurança de tipos, evitar conversões de tipos não intencionais e melhorar a segurança geral.

# Escondendo o PHP

Em geral, segurança por obscuridade é uma das maneiras mais fracas de segurança. Mas em alguns casos, cada pequena medida de segurança extra é desejável.

Algumas técnicas simples podem ajudar a esconder o PHP, possivelmente retardando um atacante que está tentando descobrir fraquezas no seu sistema. Configurar a diretiva expose_php para `off` no arquivo php.ini, reduz a quantidade de informação disponível aos atacantes.

Outra tática é configurar o servidor web, como o Apache, para executar tipos de arquivos diferentes pelo PHP, ou por uma diretiva de arquivo .htaccess, ou no próprio arquivo de configuração do Apache. É possível usar extensões de arquivos como disfarce:

Exemplo #1 Escondendo o PHP como outra linguagem

    # Fazer código PHP parecer com outros tipos de códigos
    AddType application/x-httpd-php .asp .py .pl

Ou obscurecer completamente:

Exemplo #2 Usando extensões desconhecidas para o PHP

    # Fazer código PHP parecer com tipos desconhecidos
    AddType application/x-httpd-php .bop .foo .133t

Ou esconder ele como código HTML, o que tem uma pequena queda de performance porque todo HTML será avaliado pelo engine do PHP:

Exemplo #3 Usando extensão HTML para arquivos PHP

    # Fazer código PHP parecer com HTML
    AddType application/x-httpd-php .htm .html

Para isso funcionar efetivamente, deve-se renomear os arquivos PHP com as extensões acima. Embora seja uma forma de segurança por obscuridade, é uma pequena medida preventiva e com poucos custos.

# Mantendo-se Atualizado

PHP, como qualquer outro sistema grande, está sob constante revisão e melhoramento. Cada versão nova normalmente incluirá mudanças, sejam grandes ou pequenas, para melhorar a segurança e reparar falhas, erros de configuração, e outros problemas que podem afetar a segurança geral e estabilidade do seu sistema.

Como outras linguagens de script e programas de nível de sistema, a melhor política é atualizar frequentemente e manter-se atento às novas versões e suas mudanças.

- Introdução
- Considerações Gerais
- Instalando como binário CGI
  - Ataque Possível
  - Caso 1: apenas arquivos públicos são disponibilizados
  - Caso 2: usando cgi.force_redirect
  - Caso 3: configurando doc_root ou user_dir
  - Caso 4: Interpretador do PHP fora da árvore de diretórios do servidor web
- Instalando como módulo do Apache
- Segurança da Sessão
- Segurança do Sistema de Arquivos
  - Problemas relacionados aos bytes nulos (NUL)
- Segurança de Bancos de Dados
  - Desenhando Bancos de Dados
  - Conectando com o Banco de Dados
  - Modelo de Armazenamento Criptografado
  - Injeção de SQL
- Relatando Erros
- Dados Enviados pelo Usuário
- Escondendo o PHP
- Mantendo-se Atualizado

# Características

# Autenticação HTTP com PHP

Pode-se utilizar a função header() para enviar uma mensagem de `"Authentication Required"` para o navegador cliente, causando o aparecimento de uma janela para a entrada de Nome de Usuário/Senha. Uma vez que o usuário preencha um nome de usuário e uma senha, a URL contendo o script PHP será chamada mais uma vez com as variáveis predefinidas PHP_AUTH_USER, PHP_AUTH_PW, e AUTH_TYPE para determinar o nome de usuário, senha e tipo da autenticação, respectivamente. Estas variáveis predefinidas são encontradas no array $_SERVER. Somente o método de autenticação "Basic" é suportado. Consulte a função header() para mais informações.

Um exemplo de fragmento de script que forçaria a autenticação do cliente em uma página:

Exemplo #1 Exemplo de Autenticação HTTP "Basic"

    <?php
    if (!isset($_SERVER['PHP_AUTH_USER'])) {
        header('HTTP/1.1 401 Unauthorized');
        header('WWW-Authenticate: Basic realm="My Realm"');
        echo 'Texto enviado caso o usuário clique no botão Cancelar';
        exit;
    } else {
        echo "<p>Olá, {$_SERVER['PHP_AUTH_USER']}.</p>";
        echo "<p>Você digitou {$_SERVER['PHP_AUTH_PW']} como sua senha.</p>";
    }
    ?>

> Nota: Compatibilidade

> Por favor, seja cauteloso ao codificar as linhas do cabeçalho HTTP. Para garantir máxima compatibilidade com todos os clientes, a palavra-chave "Basic" deve ser escrita com um "B" maiúsculo, a string realm deve ser envolvida por aspas duplas (nunca por aspas simples), e apenas um espaço deve preceder o código 401 na linha do cabeçalho HTTP/1.1 401. Parâmetros de autenticação precisam ser separados por vírgula.

Ao invés de simplesmente exibir PHP_AUTH_USER e PHP_AUTH_PW, como no exemplo acima, talvez queira verificar a validade do nome de usuário e senha. Talvez enviando uma consulta a um banco de dados, ou procurando o usuário em um arquivo dbm.

> Nota: Configuração do Apache

> O PHP usa uma diretiva chamada `AuthType` para determinar se a autenticação externa está em efeito.

Perceba, entretanto, que a diretiva citada acima não previne que alguém que controle uma URL não autenticada roube senhas de URLs autenticadas no mesmo servidor.

> Nota: Comportamento do navegador
> A autenticação básica HTTP é realmente básica e não foi projetada para suportar logouts. Como o HTTP é um protocolo sem estado, a maioria dos navegadores armazena em cache as credenciais fornecidas assim que um código de status `2xx` é detectado, e as envia em todas as requisições, até que o navegador seja fechado. Não há uma maneira definida para um servidor solicitar uma nova solicitação de credenciais. Ao longo dos anos, várias soluções alternativas para isso se espalharam como conselhos na internet, mas todas dependem de como diferentes navegadores optaram por lidar com casos extremos indefinidos (ou mesmo violações do padrão HTTP). É melhor evitar essas soluções alternativas e não usar a autenticação básica para nada sério.

> Nota: Configuração do IIS
> Para que a autenticação HTTP funcione no servidor IIS com a versão CGI do PHP, a diretiva php.ini cgi.rfc2616_headers deve ser definida como `0` (o valor padrão) e a configuração do IIS em "`Directory Security`" (ou "Segurança do Diretório" / "Autenticação") deve ser editada. Clique em "`Edit`" (ou "Editar") e marque apenas "`Anonymous Access`" (ou "Acesso Anônimo"), deixando todos os outros campos desmarcados.

# Cookies

O PHP suporta de forma transparente cookies HTTP. Cookies são um mecanismo para armazenar dados no navegador remoto e assim rastrear ou identificar usuários que retornam. Você pode criar cookies usando as funções setcookie() ou setrawcookie(). Cookies fazem parte do cabeçalho HTTP, logo, setcookie() deve ser chamada antes que qualquer saída seja enviada ao navegador. Esta é a mesma limitação que a função header() tem. Você pode usar as funções de buffering de saída para atrasar as impressões no script até que você tenha decidido se vai ou não configurar qualquer cookie ou enviar quaisquer cabeçalhos.

Qualquer cookie enviado para o servidor pelo cliente será automaticamente incluído no array auto-global $_COOKIE se variables_order contém "C". Se você deseja definir vários valores em um único cookie, simplesmente acrescente `[]` ao nome do cookie.

Para mais detalhes, incluindo comentários sobre problemas de browsers, veja as funções setcookie() e setrawcookie().

# Sessões

Suporte a sessões no PHP consiste de uma maneira de preservar dados através de acessos subsequentes. Isso permite a criação de aplicações mais personalizadas e aumenta o apelo do seu web site. Todas as informações estão na seção Session reference.

# Gerenciamento de envio de arquivos

## Índice

- Envio de arquivos com o método POST
- Explicando mensagens de erro
- Problemas Comuns
- Enviando múltiplos arquivos
- Suporte ao método PUT
- Veja Também

## Envio de arquivos com o método POST

Este recurso permite realizar envios de arquivos de texto e binários. Com as funções de autenticação e manipulação de arquivos do PHP, você tem o controle completo de quem pode fazer o envio e o que deve ser feito com o arquivo após o envio estar completo.

O PHP é capaz de receber envios de arquivos de qualquer navegador compatível com RFC-1867.

> Nota: Nota Sobre Configurações Relacionadas

> Veja também as diretivas file_uploads, upload_max_filesize, upload_tmp_dir, post_max_size, max_input_time no php.ini

O PHP também suporta o método PUT para envio de arquivos como o usado pelo Netscape Composer e clientes para Amaya W3C. Veja Suporte ao Método PUT para maiores detalhes.

Exemplo #1 Formulário para Envio de Arquivo

Uma interface para envio de arquivo pode ser criada com um formulário especial parecido com este:

    <!-- O tipo de codificação de dados, enctype, DEVE ser especificado abaixo -->
    <form enctype="multipart/form-data" action="__URL__" method="POST">
        <!-- MAX_FILE_SIZE deve preceder o campo input -->
        <input type="hidden" name="MAX_FILE_SIZE" value="30000" />
        <!-- O nome do elemento input determina o nome do array $_FILES -->
        Enviar esse arquivo: <input name="userfile" type="file" />
        <input type="submit" value="Enviar arquivo" />
    </form>

O parâmetro `__URL__` no exemplo acima deve ser substituído e apontar para um arquivo PHP.

O campo escondido (input type="hidden") `MAX_FILE_SIZE` (medido em bytes) deve preceder o campo de entrada do arquivo (input type="file"), e o seu valor é o tamanho limite aceito pelo PHP. Este elemento do formulário deve sempre ser usado para evitar que usuários tenham o problema de ter que esperar pela transferência de um arquivo para só então descobrir que ele era grande demais e a transferência falhar. Fique ciente: é muito simples burlar esse parâmetro pelo lado do navegador, portanto nunca dependa exclusivamente desse recurso para bloquear arquivos com maior tamanho. Isso é um recurso meramente conveniente para usuários da aplicação no lado do cliente. Os parâmetros do PHP (no servidor) para "maximum-size", no entanto, não podem ser burlados.

> Nota:

> Tenha certeza que seu formulário de envio tenha o atributo `enctype="multipart/form-data"` do contrário o envio não irá funcionar.

A variável global $_FILES conterá toda a informação do arquivo enviado. O conteúdo do formulário de exemplo acima será como o exemplo descrito abaixo. Note que isso assume o nome do arquivo enviado userfile, como foi usado no script de exemplo acima, contudo isso pode ter qualquer nome.

$_FILES['userfile']['name']

  O nome original do arquivo na máquina do cliente.

$_FILES['userfile']['type']

  O tipo mime do arquivo, se o navegador fornecer essa informação. Um exemplo poderia ser `"image/gif"`. O tipo mime não é verificado pelo PHP portanto não considere que esse valor será concedido.

$_FILES['userfile']['size']

  O tamanho, em bytes, do arquivo enviado.

$_FILES['userfile']['tmp_name']

  O nome temporário com o qual o arquivo enviado foi armazenado no servidor.

$_FILES['userfile']['error']

  O código de erro associado a esse envio de arquivo.

$_FILES['userfile']['full_path']

  O caminho completo conforme enviado pelo navegador. Esse valor nem sempre contém uma estrutura de diretórios real, e não se pode confiar nele. Disponível a partir do PHP 8.1.0.

Os arquivos serão guardados por padrão no diretório temporário do servidor, a menos que outro local seja especificado através da diretiva upload_tmp_dir no php.ini. O diretório padrão do servidor pode ser alterado através da configuração da variável de ambiente TMPDIR no ambiente onde o PHP está sendo executado. Configurando isso usando putenv() em um script PHP não irá funcionar. Esta variável de ambiente também pode ser usada para certificar que outras operações também estão funcionando nos arquivos enviados.

Exemplo #2 Validando o envio de arquivos

Veja também as funções is_uploaded_file() e move_uploaded_file() para maiores informações. O exemplo a seguir irá processar o envio de um arquivo que vem de um formulário.

    <?php
    $uploaddir = '/var/www/uploads/';
    $uploadfile = $uploaddir . basename($_FILES['userfile']['name']);

    echo '<pre>';
    if (move_uploaded_file($_FILES['userfile']['tmp_name'], $uploadfile)) {
        echo "Arquivo válido e enviado com sucesso.\n";
    } else {
        echo "Possível ataque de upload de arquivo!\n";
    }

    echo 'Aqui está mais informações de debug:';
    print_r($_FILES);

    print "</pre>";

    ?>

O script PHP que recebe o arquivo enviado deve implementar qualquer lógica que for necessária para determinar o que deve ser feito com o arquivo enviado. Você pode, por exemplo, usar a variável $_FILES['userfile']['size'] para descartar qualquer arquivo que seja muito pequeno ou muito grande. Você pode usar a variável $_FILES['userfile']['type'] para descartar arquivos incompatíveis com um determinado critério, mas use isso apenas como a primeira de uma série de verificações, porque esse valor está totalmente sob o controle do cliente e não é verificado pelo PHP. Você também pode usar $_FILES['userfile']['error'] e planejar sua lógica de acordo com os Códigos de erro. Independente da lógica, você também deve apagar o arquivo do diretório temporário ou movê-lo para outro local.

Se nenhum arquivo for selecionado em seu formulário, o PHP irá retornar $_FILES['userfile']['size'] como 0, e $_FILES['userfile']['tmp_name'] como "none" (nenhum).

O arquivo será excluído do diretório temporário ao fim da requisição se ele não for movido ou renomeado.

Exemplo #3 Enviando um array de arquivos

O PHP suporta array HTML mesmo com arquivos.

    <form action="" method="post" enctype="multipart/form-data">
    <p>Imagens:
    <input type="file" name="pictures[]" />
    <input type="file" name="pictures[]" />
    <input type="file" name="pictures[]" />
    <input type="submit" value="Enviar" />
    </p>
    </form>

    <?php
    foreach ($_FILES["pictures"]["error"] as $key => $error) {
        if ($error == UPLOAD_ERR_OK) {
            $tmp_name = $_FILES["pictures"]["tmp_name"][$key];
            // basename() pode prevenir ataques de percorrer o sistema de arquivos,
            // mas mais validações são necessárias
            $name = basename($_FILES["pictures"]["name"][$key]);
            move_uploaded_file($tmp_name, "data/$name");
        }
    }
    ?>

O progresso do envio de arquivos pode ser implementado usando a Sessão de Progresso de Envio.

## Explicando mensagens de erro

O PHP retorna um código de erro apropriado na array do arquivo. O código de erro pode ser encontrado no segmento `error` da array que é criada pelo PHP durante o envio do arquivo. Em outras palavras, o erro pode ser encontrado em $_FILES['userfile']['error'].

O valor desse código de erro é uma das constantes `UPLOAD_ERR_*`.

## Problemas Comuns

O item `MAX_FILE_SIZE` não pode assumir um tamanho de arquivo maior que o tamanho de arquivo configurado em upload_max_filesize no arquivo php.ini. O valor padrão é de 2 megabytes.

Se um limite de memória está ativo, um valor maior para o limite de memória no parâmetro memory_limit pode ser necessário. Tenha certeza de estabelecer um limite de memória grande o suficiente através do parâmetro memory_limit.

Se o tempo máximo de execução definido através do parâmetro max_execution_time for muito pequeno, a execução do script pode ultrapassar o limite de tempo. Tenha certeza de estabelecer um tempo máximo de execução grande o suficiente através do parâmetro `max_execution_time`.

> Nota: O parâmetro max_execution_time somente afeta o tempo de execução do script em si. Qualquer tempo gasto com atividades que aconteçam fora da execução do script como chamadas de sistema usando system(), a função sleep(), pesquisas em banco de dados, tempo gasto pelo processo de enviar um arquivo, etc. não são considerados no momento de determinar o limite de tempo máximo de um script em execução.

Aviso

O parâmetro max_input_time define o tempo máximo, em segundos, que é permitido ao script a receber entradas, isto inclui envio de arquivos. Para um arquivo grande, múltiplos arquivos ou usuários com conexões lentas, o padrão de `60` segundos pode ser ultrapassado.

Se o parâmetro post_max_size for muito pequeno, arquivos grandes podem não ser carregados. Tenha certeza de definir o parâmetro `post_max_size` grande o suficiente.

O parâmetro max_file_uploads controla o número máximo de arquivos que podem ser enviados em uma única requisição. Caso sejam enviados mais arquivos que o definido neste limite, então $_FILES interrompe o processamento de arquivos uma vez que o limite tenha sido atingido. Por exemplo, se o parâmetro max_file_uploads está definido como `10`, então $_FILES nunca possuirá mais de 10 itens.

Não validar o arquivo que você está operando pode permitir que os usuários acessem informações sensíveis em outros diretórios.

Devido ao grande número de estilos de listagem de diretórios não podemos garantir que arquivos com nomes exóticos (como os que contém espaços) sejam manuseados corretamente.

Um desenvolvedor não deve misturar campos comuns de entrada `input` e campos de envio de arquivo na mesma variável de formulário (usando um nome de campo `input` como `foo[]`).

## Enviando múltiplos arquivos

Múltiplos arquivos podem ser enviados usando diferentes nomes (`name`) para entradas (`input`).

Também é possível carregar vários arquivos simultaneamente e ter a informação automaticamente organizada em arrays. Para isso, é necessário usar a mesma sintaxe das arrays submetidas pelo formulário HTML que você usa para múltiplos selects e checkboxes:

Exemplo #1 Carregando múltiplos arquivos

    <form action="file-upload.php" method="post" enctype="multipart/form-data">
      Envie esses arquivos:<br />
      <input name="userfile[]" type="file" /><br />
      <input name="userfile[]" type="file" /><br />
      <input type="submit" value="Enviar arquivos" />
    </form>

Quando o formulário acima é submetido, os arrays $_FILES['userfile'], $_FILES['userfile']['name'], e $_FILES['userfile']['size'] serão inicializados.

Por exemplo, suponha os nomes dos arquivos /home/test/review.html e /home/test/xwp.out. Neste caso, $_FILES['userfile']['name'][0] deve conter o valor review.html, e $_FILES['userfile']['name'][1] deve conter o valor xwp.out. Similarmente, $_FILES['userfile']['size'][0] deve conter o tamanho do arquivo review.html, e assim por diante.

$_FILES['userfile']['name'][0], $_FILES['userfile']['tmp_name'][0], $_FILES['userfile']['size'][0], e $_FILES['userfile']['type'][0] também são definidas.

Aviso

O parâmetro max_file_uploads atua como um limite no número de arquivos que podem ser enviados em uma única requisição. Você precisa ter certeza que seu formulário não tentará enviar mais arquivos que o limite definido.

Exemplo #2 Carregando um diretório inteiro

Nos campos de carregamento de arquivos HTML, é possível carregar um diretório inteiro com o atributo `webkitdirectory`. Esse recurso é suportado na maioria dos navegadores modernos.

Com a informação `full_path`, é possível armazenar os caminhos relativos, ou reconstruir o mesmo diretório no servidor.

    <form action="file-upload.php" method="post" enctype="multipart/form-data">
      Enviar este diretório:<br />
      <input name="userfile[]" type="file" webkitdirectory multiple />
      <input type="submit" value="Enviar arquivos" />
    </form>

Aviso

O atributo `webkitdirectory` não é padronizado e não está no roteiro de padronização. Não utilize-o em sites em produção voltados para a Web: ele não funcionará para todos os usuários. Também podem haver grandes incompatibilidades entre implementações e o comportamento pode mudar no futuro.

O PHP analisa apenas a informação de caminho relativo enviada pelo navegador/user-agent, e passa essa informação para o array $_FILES. Não há garantia de que os valores no array `full_path` contenham uma estrutura de diretórios real, e a aplicação PHP não deve confiar nesta informação.

## Suporte ao método PUT

O PHP oferece suporte para o método HTTP PUT utilizado por alguns clientes para armazenar arquivos em um servidor. Requisições PUT são muito mais simples que o envio de arquivos usando requisições POST, elas se parecem com algo assim:

    PUT /path/filename.html HTTP/1.1

Isso normalmente significaria que o cliente remoto gostaria de salvar o seguinte conteúdo: /path/filename.html em seu diretório web. É óbvio não se tratar de uma boa ideia que o Apache ou o PHP permitam automaticamente que todos sobrescrevam qualquer arquivo em seu diretório web. Então, para considerar isso como uma requisição é necessário dizer ao seu servidor web que você quer que um determinado script PHP cuide dessa requisição. Para fazer isso no Apache utilize a diretiva Script. Ela pode ser colocada quase em qualquer local de seu arquivo de configuração do Apache. Um local comum é dentro de um bloco `<Directory>` ou talvez dentro de um bloco `<VirtualHost>`. Uma linha como a seguinte deve funcionar:

    Script PUT /put.php

Isto diz ao Apache para enviar todas as requisições PUT para as URIs que combinem com o contexto dessa linha para o script put.php. Isto assume que o PHP esteja ativo e permite extensões .php. O destino para todas as requisições PUT para esse script deve ser o próprio script, não o nome do arquivo enviado.

Com o PHP pode ser feito algo como se segue no script put.php. Isso copia o conteúdo de um arquivo enviado para o arquivo myputfile.ext no servidor. Provavelmente é necessário a realização de algumas verificações e/ou autenticação de usuário antes de realizar essa cópia.

Exemplo #1 Salvando arquivos HTTP PUT

    <?php
    /* PUT data vem do fluxo stdin */
    $putdata = fopen("php://input", "r");

    /* Abre um arquivo para escrita */
    $fp = fopen("myputfile.ext", "w");

    /* Lê os dados 1KB de cada vez
       e escreve no arquivo */
    while ($data = fread($putdata,1024))
      fwrite($fp,$data);

    /* Fecha os fluxos */
    fclose($fp);
    fclose($putdata);
    ?>

## Veja Também

- Segurança do sistema de arquivos

# Usando arquivos remotos

Enquanto allow_url_fopen estiver disponível no arquivo php.ini, você pode usar URLs HTTP e FTP com a maioria das funções que recebem um nome de arquivo como parâmetro. Além disso, URLs podem ser usadas com as funções include, include_once, require e require_once (allow_url_include precisa estar habilitado para isto). Veja Protocolos e empacotadores suportados para mais informações sobre protocolos suportados pelo PHP.

Por exemplo, você pode usar isso para abrir um arquivo em um web server remoto, avaliar a saída para a informação que você precisa, e então usar a informação em uma query de banco de dados, ou simplesmente mostrar em um estilo que combine com o resto do seu website.

Exemplo #1 Pegando o título de uma página remota

    <?php
    $file = fopen ("http://www.example.com/", "r");
    if (!$file) {
        echo "<p>Incapaz de abrir arquivo remoto.\n";
        exit;
    }
    while (!feof ($file)) {
        $line = fgets ($file, 1024);
        /* Isso só funciona se o título e suas tags estiverem na mesma linha */
        if (preg_match ("@\<title\>(.*)\</title\>@i", $line, $out)) {
            $title = $out[1];
            break;
        }
    }
    fclose($file);
    ?>

Você também pode escrever arquivos em um servidor FTP (presumindo que você se conectou como um usuário com os direitos de acesso corretos). Você só pode criar arquivos novos usando esse método. Se você tentar sobrescrever um arquivo que já existe, a chamada para fopen() falhará.

Para conectar como um usuário diferente de 'anonymous', você precisa especificar o nome de usuário (e possivelmente a senha) dentro da URL, como '`ftp://user:password@ftp.example.com/path/to/file`'. (Você pode usar o mesmo tipo de sintaxe para acessar arquivos via HTTP quando eles requerem autenticação Basic).

Exemplo #2 Guardando informação em um servidor remoto

    <?php
    $file = fopen ("ftp://ftp.example.com/incoming/outputfile", "w");
    if (!$file) {
        echo "<p>Incapaz de abrir arquivo remoto para escrita.\n";
        exit;
    }
    /* Escreva informações aqui. */
    fwrite ($file, $_SERVER['HTTP_USER_AGENT'] . "\n");
    fclose ($file);
    ?>

> Nota:

> Você talvez tenha tido a idéia, pelo exemplo acima, de usar essa técnica para escrever para um arquivo de log remoto. Infelizmente isso não funcionaria porque a chamada a fopen() falhará se o arquivo remoto já existir. Para fazer logs distribuídos dessa maneira, você deve dar uma olhada na função syslog().

# Tratamento de Conexões

O estado de uma conexão é mantido internamente no PHP. Existem 4 estados possíveis:

- 0 - NORMAL
- 1 - ABORTADO
- 2 - EXPIRADO
- 3 - ABORTADO e EXPIRADO

Quando um script PHP está sendo executado normalmente, o estado NORMAL está ativo. Se o cliente remoto desconectar, o estado ABORTADO é ativado. Uma desconexão do cliente remoto é normalmente causada pelo usuário pressionando o botão de parada. Se o tempo limite imposto pelo PHP (veja set_time_limit()) é alcançado, o estado EXPIRADO é ativado.

É possível decidir se a desconexão do cliente cause ou não uma interrupção no script. As vezes é útil deixar o script em execução até que seja concluído mesmo se não houver nenhum navegador remoto recebendo a saída. O comportamento padrão, no entanto, é a interrupção do script quando o cliente remoto se desconecta. Esse comportamento pode ser configurado através da diretiva ignore_user_abort do php.ini, assim como pela diretiva correspondente `php_value ignore_user_abort` no httpd.conf do Apache ou com a função ignore_user_abort(). Se o PHP não for instruído a ignorar o aborto por parte do usuário e ele abortar, o script será encerrado. A única exceção é se uma função de finalização tiver sido registrada usando register_shutdown_function(). Com uma função de finalização, quando um usuário remoto clica no botão de parada, a próxima vez que o script tentar gerar alguma saída, o PHP detectará que a conexão foi cancelada e a função de finalização é chamada. Essa função de finalização também será chamada no fim do script mesmo que ele termine normalmente, então para fazer algo diferente caso o cliente desconecte, a função connection_aborted() pode ser usada. Essa função retorna `true` se a conexão foi abortada.

O script também pode ser finalizado pelo temporizador interno. O tempo limite padrão é de 30 segundos. Pode ser alterado usando a diretiva max_execution_time do php.ini ou a diretiva correspondente no httpd.conf do Apache `php_value max_execution_time` assim como com a função set_time_limit(). Quando o temporizador chega ao limite, o script será abortado e assim como o caso acima de desconexão pelo cliente, se uma função de finalização foi registrada, ela será chamada. Dentro da função de finalização, pode ser verificado se a causa da finalização foi tempo limite excedido chamando-se a função connection_status(). Essa função retorna 2 se a causa foi tempo limite excedido.

Importante notar que ambos os estados ABORTADO e EXPIRADO podem estar ativos ao mesmo tempo. Isso é possível se o PHP for instruído a ignorar o aborto causado pelo usuário. O PHP continuará a perceber que o usuário pode ter quebrado a conexão, mas o script continuará sendo executado. Se o tempo limite for alcançado, ele será abortado e sua função de finalização, se existente, será chamada. Nesse ponto, a função connection_status() retornará 3.

# Conexões Persistentes com o Banco de Dados

### O que são Conexões Persistentes?

Conexões persistentes são conexões que não fecham quando a execução do script termina. Quando uma conexão persistente é requisitada, o PHP verifica se uma conexão persistente idêntica (que foi mantida aberta anteriormente) já existe; se existir, ela é reutilizada, senão, uma nova conexão é criada. Uma conexão 'idêntica' é uma aberta para o mesmo host com o mesmo nome de usuário e a mesma senha (onde for aplicável).

Não há nenhuma maneira de solicitar uma conexão específica ou de garantir que a conexão retornada sera uma existente ou uma nova (se todas as conexões existentes estiverem em uso ou se a solicitação estiver sendo atendida por um trabalhador diferente, que tem um conjunto separado de conexões).

Portanto, conexões persistentes do PHP não podem ser usadas para, por exemplo:

- atribuir uma sessão de banco de dados específica a um usuário da web específico
- criar uma grande transação em várias solicitações
- iniciar uma consulta em uma solicitação e coletar os resultados em outra

Conexões persistentes não fornecem nenhuma funcionalidade que não seria possível com conexões não persistentes.

### Solicitações da Web

Existem duas maneiras pelas quais um servidor web pode utilizar o PHP para gerar páginas web:

O primeiro método é usar o PHP como um CGI "wrapper". Quando executado dessa maneira, uma instância do interpretador do PHP é criada e destruída para cada requisição de página (para uma página PHP) para o servidor web. Como ela é destruída após cada requisição, quaisquer recursos que ela adquirir (como uma conexão para um servidor de banco de dados SQL) são fechados quando ela é destruída. Nesse caso, não há ganho em usar conexões persistentes - elas simplesmente não persistem.

O segundo método, e o mais popular, é rodar o PHP-FPM ou o PHP como um módulo em um servidor web com multi-processos (atualmente somente o Apache). Essas configurações têm tipicamnente um processo (o pai) que coordena uma série de processos (seus filhos) que realmente fazem o trabalho de servir as páginas web. Quando uma requisição chega de um cliente, ela é entregue à um dos filhos que já não estiver servindo outro cliente. Isso significa que quando o mesmo cliente faz uma segunda requisição para o servidor, ele pode ser atendido por um processo filho diferente do que da primeira vez. Uma vez que uma conexão persistente tenha sido aberta, cada página subsequente servida pelo mesmo processo filho pode reutilizar a conexão já estabelecida ao servidor SQL.

> Nota:

> O método em uso pode ser consultado verificando o valor de "Server API" na saída de phpinfo() ou o valor de `PHP_SAPI`, executado a partir de uma solicitação web.

> Se a API do Servidor for "Apache 2 Handler" ou "FPM/FastCGI", as conexões persistentes serão usadas em todas as solicitações atendidas pelo mesmo trabalhador. Para qualquer outro valor, as conexões persistentes não persistirão após cada solicitação.

### Command-line Processes

Como a linha de comando PHP usa um novo processo para cada script, conexões persistentes não são compartilhadas entre scripts de linha de comando, portanto, não há nenhum valor em usá-las em scripts transitórios, como crons ou comandos. No entanto, elas podem ser úteis, por exemplo, em um servidor de aplicação de longa duração que atende a muitas solicitações ou tarefas, onde cada uma pode precisar de sua própria conexão com o banco de dados.

### Por que usá-las?

Conexões persistentes são benéficas quando a sobrecarga para criar uma conexão ao servidor SQL é alta. Se essa sobrecarga é realmente significativa depende de vários fatores como o tipo de banco de dados, se reside na mesma máquina do servidor web e o quão carregada está a máquina. Quando a sobrecarga de conexão é alta, conexões persistentes podem ajudar consideravelmente: cada processo filho se conecta uma vez só durante toda sua duração, e não a cada vez que ele processa uma página que requer uma conexão ao servidor SQL. Isso significa que cada filho que abre uma conexão persistente manterá sua própria conexão persistente ao servidor. Por exemplo, se cada um de 20 processos filhos diferentes rodarem um script que faz uma conexão persistente ao servidor SQL, haverá 20 conexões separadas a esse servidor, uma de cada filho.

### Possíveis desvantagens: limites de conexão

Perceba, no entanto, que isso pode ter desvantagens ao usar um banco de dados com limite de conexões que são excedidas pela conexões persistentes dos filhos. Se o banco de dados tem um limite de 16 conexões simultâneas e durante uma sessão movimentada do servidor 17 processos filhos tentarem se conectar, um deles falhará. Se houver bugs nos scripts que não permitem que as conexões se fechem (como loops infinitos), um banco de dados com apenas 16 conexões pode rapidamente ficar atolado.

Conexões persistentes geralmente aumentam o número de conexões abertas a qualquer momento, pois os trabalhadores ociosos ainda manterão as conexões para as solicitações anteriores. Se um grande número de trabalhadores for criado para lidar com um pico de solicitações, as conexões que eles abriram permanecerão até que o trabalhador seja encerrado ou que o servidor de banco de dados feche a conexão.

Certifique-se de que o número máximo de conexões permitidas pelo servidor de banco de dados seja maior que o número máximo de trabalhadores de solicitação da web (além de qualquer outro uso, como crons ou conexões administrativas).

Consulte a documentação do banco de dados para obter informações sobre como lidar com conexões abandonadas ou ociosas (tempo limite). Tempo limite longo pode aumentar significativamente o número de conexões persistentes abertas ao mesmo tempo.

### Possíveis desvantagens: manter o estado de conexão

Algumas extensões de banco de dados realizam limpeza automática quando a conexão é reutilizada; outras deixam essa tarefa a critério do desenvolvedor da aplicação. Dependendo da extensão de banco de dados escolhida e do projeto da aplicação, a limpeza manual pode ser necessária antes da saída do script. Alterações que podem deixar conexões em um estado inesperado incluem:

- Banco de dados selecionado / padrão
- Bloqueio de tabelas
- Transações não confirmadas
- Tabelas temporárias
- Configurações ou recursos específicos de conexão, como perfilagem

Bloqueios de tabela e transações que não são limpos ou fechados podem fazer com que outras consultas sejam bloqueadas indefinidamente e/ou causar a reutilização subsequente da conexão, causando alterações inesperadas.

Selecionar o banco de dados errado fará com que a reutilização subsequente da conexão não consiga executar as consultas conforme o esperado (ou executá-las no banco de dados errado se os esquemas forem semelhantes o suficiente).

Se as tabelas temporárias não forem limpas, as solicitações subsequentes não conseguirão recriar a mesma tabela.

Pode-se implementar a limpeza usando destruidores de classe ou register_shutdown_function(). Podem ser considerados também proxies de grupo de conexão dedicados que incluam isso como parte de sua funcionalidade.

### Palavras Finais

Considerando seu comportamento e as potenciais desvantagens descritas acima, não se deve usar conexões persistentes sem uma análise cuidadosa. Elas não devem ser usadas sem implementar alterações adicionais na aplicação ou sem um configuração cuidadosa do servidor de banco de dados e servidor web e/ou PHP-FPM.

Considere soluções alternativas, como investigar e corrigir as causas de sobrecargas na criação de conexões (por exemplo, desabilitando pesquisas reversas de DNS no servidor de banco de dados) ou proxies de grupo de conexões dedicados.

Para APIs da web de alto volume, considere usar tempos de execução alternativos ou servidores de aplicações de longa execução.

### Veja Também

- ibase_pconnect()
- oci_pconnect()
- odbc_pconnect()
- pfsockopen()
- pg_connect()
- MySQLi e Conexões Persistentes
- Gerenciamento de Conexões PDO

# Usando PHP a partir da linha de comando

## Índice

- Diferenças em relação a outros SAPIs
- Opções
- Uso
- Fluxos de E/S
- Shell interativo
- Servidor web embutido
- Configurações INI

## Introdução

O principal foco do CLI SAPI é o desenvolvimento de aplicações shell com PHP. Existem algumas diferenças entre CLI SAPI e outras SAPIs que são explicadas neste capítulo. Vale a pena ressaltar que CLI e CGI são diferentes SAPIs embora compartilhem boa parte dos mesmos comportamentos.

O CLI SAPI é ativado por padrão usando --enable-cli, mas pode ser desativado usando a opção --disable-cli quando se executa o comando ./configure durante o processo de compilação do PHP.

O nome, a localização e a existência dos arquivos binários do CLI/CGI podem ser diferentes dependendo de como o PHP está instalado no seu sistema. Por padrão, quando executado o make, ambos CGI e CLI são compilados e colocados em sapi/cgi/php-cgi e sapi/cli/php, respectivamente, no seu diretório fonte do PHP. Você vai notar que ambos são nomeados php. O que acontece durante o make install depende da sua linha de configuração. Se o módulo SAPI é escolhido durante a configuração, como apxs, ou a opção --disable-cgi é utilizada, o CLI é copiado para {PREFIX}/bin/php durante make install, caso contrário o CGI é colocado lá. Assim, por exemplo, se o --with-apxs está na sua linha de configuração, em seguida, o CLI é copiado para {PREFIX}/bin/php durante o make install. Se você quiser substituir a instalação do binário CGI, use make install-cli depois de make install. Alternativamente, você pode especificar --disable-cgi na sua linha de configuração.

> Nota:

> Porque ambos --enable-cli e --enable-cgi são ativadas por padrão, ter simplesmente um --enable-cli na sua linha de configuração não significa necessariamente que o CLI será copiado para {PREFIX}/bin/php durante o make install.

O binário CLI é distribuído na pasta principal como php.exe no Windows. A versão CGI é distribuída como php-cgi.exe. Além disso, um php-win.exe é distribuído se o PHP é configurado com --enable-cli-win32. Isso faz o mesmo que a versão CLI, exceto que ele não exibe nenhum output e também não disponibiliza nenhum console.

> Nota: Qual SAPI eu tenho?

> A partir da linha de comando, digitar php -v lhe dirá se o php é CGI ou CLI. Veja também a função php_sapi_name() e a constante `PHP_SAPI`.

> Nota:

> A página do `man` Unix está disponível digitando man php no ambiente shell.

## Diferenças em relação a outros SAPIs

Diferenças notáveis do CLI SAPI em comparação com outros SAPIs:

- Diferente do CGI SAPI, nenhum cabeçalho é enviado para a saída.

  Embora o CGI SAPI forneça uma maneira de suprimir os cabeçalhos HTTP, não existe nenhuma forma equivalente de habilitá-los no CLI SAPI.

  CLI é inicializado no modo silencioso por padrão, embora as chaves -q e --no-header são mantidas por compatibilidade para que seja possível usar scripts CGI antigos.

  Ele não altera o diretório atual para aquele no qual o script está sendo executado (As opções -C e --no-chdir são mantidas por compatibilidade)

  Mensagens de erro em texto plano (sem formatação HTML).

- Existem certas diretivas do php.ini que são sobrescritas pelas do CLI SAPI porque elas não fazem sentido em um ambiente de linha de comando:

  Diretivas do php.ini sobrescritas
  Diretiva | Valor padrão do CLI SAPI | Comentário
  --- | --- | ---
  html_errors | `false` | Tem como padrão `false`, já que pode ser bem difícil ler mensagens de erro na linha de comando quando elas estão misturadas com tags HTML não interpretadas.
  implicit_flush | `true` | Em um ambiente de linha de comando, é geralmente desejado para a saída, como a partir de print, echo e similares, que elas sejam exibidas imediatamente, e não mantidas em um buffer. Apesar disso, ainda é possível usar output buffering para atrasar ou manipular a saída padrão.
  max_execution_time | 0 (unlimited) | O PHP em um ambiente de linha de comando tende a ser usado com um número de propostas muito mais diversas do que para aplicações web típicas, e como essas formas podem ter muito mais longevidade, o tempo máximo de execução é definido como sem limite.
  register_argc_argv | `true` | Definir isso como `true` significa que o script executado a partir do CLI SAPI sempre terá acesso ao argc (número de argumentos passados para a aplicação) e argv (array contendo os valores dos argumentos). As variáveis $argc e $argv do PHP são automaticamente definidas com seus valores apropriados quando usando o CLI SAPI. Esses valores podem também ser encontrados no array $_SERVER, por exemplo: $_SERVER['argv']. Aviso A presença de $argv ou $_SERVER['argv'] não é uma indicação confiável de que um script está sendo executado da linha de comando porque elas podem ser definidas em outros contextos quando register_argc_argv está habilitada. O valor retornado por php_sapi_name() é o que deve ser verificado.
      <?php

      if (php_sapi_name() === 'cli') {
          echo "Este script está sendo executado da linha de comando!\n";
      }
  Aviso Este recurso foi DESCONTINUADO a partir do PHP 8.5.0. O uso deste recurso é fortemente desencorajado.
  output_buffering | `false` | Apesar do valor no php.ini ser explicitamente definido como `false`, as funções de Output buffering estão disponíveis.
  max_input_time | `false` | O PHP CLI não suporta GET, POST ou upload de arquivos.

  > Nota:

  > Essas diretivas não podem ser inicializadas com outro valor no arquivo de configuração php.ini ou um valor personalizado (caso seja especificado). Essa limitação ocorre pois os valores são aplicados depois que todos os arquivos de configuração foram lidos. Entretanto, seus valores podem ser alterados em tempo de execução (porém isso não se aplica a todos eles como register_argc_argv).

  > Nota:

  > É recomendado definir ignore_user_abort para aplicações de linha de comando. Veja ignore_user_abort() para mais informações.

- Para facilitar o trabalho em ambientes de linha de comando, um número de constantes é definido para fluxos de E/S.

- O CLI SAPI não altera o diretório de trabalho para o diretório de onde o arquivo é executado.

  Exemplo #1 Exemplo demonstrando a diferença entre CGI e SAPI:

      <?php
      // Um script de teste simples chamado test.php
      echo getcwd(), "\n";
      ?>

  Quando é utilizada a versão CGI a saída é:

      $ pwd
      /tmp

      $ php -q another_directory/test.php
      /tmp/another_directory

  Isso demonstra claramente que o PHP altera o diretório de trabalho para o diretório onde o arquivo é executado.

  Usando o CLI SAPI temos:

      $ pwd
      /tmp

      $ php -f another_directory/test.php
      /tmp

  Isso permite grande flexibilidade no desenvolvimento de ferramentas de linha de comando em PHP.

  > Nota:

  > O CGI SAPI suporta esse comportamento do CLI SAPI através da opção -C utilizada quando executado a partir da linha de comando.

## Opções de linha de comando

A lista de opções de linha de comando fornecidas pelo binário do PHP pode ser requisitada a qualquer momento bastando executar o PHP com a opção -h:

    Usage: php [options] [-f] <file> [--] [args...]
       php [options] -r <code> [--] [args...]
       php [options] [-B <begin_code>] -R <code> [-E <end_code>] [--] [args...]
       php [options] [-B <begin_code>] -F <file> [-E <end_code>] [--] [args...]
       php [options] -- [args...]
       php [options] -a

      -a               Run interactively
      -c <path>|<file> Look for php.ini file in this directory
      -n               No php.ini file will be used
      -d foo[=bar]     Define INI entry foo with value 'bar'
      -e               Generate extended information for debugger/profiler
      -f <file>        Parse and execute <file>.
      -h               This help
      -i               PHP information
      -l               Syntax check only (lint)
      -m               Show compiled in modules
      -r <code>        Run PHP <code> without using script tags <?..?>
      -B <begin_code>  Run PHP <begin_code> before processing input lines
      -R <code>        Run PHP <code> for every input line
      -F <file>        Parse and execute <file> for every input line
      -E <end_code>    Run PHP <end_code> after processing all input lines
      -H               Hide any passed arguments from external tools.
      -S <addr>:<port> Run with built-in web server.
      -t <docroot>     Specify document root <docroot> for built-in web server.
      -s               Output HTML syntax highlighted source.
      -v               Version number
      -w               Output source with stripped comments and whitespace.

      args...          Arguments passed to script. Use -- args when first argument
                       starts with - or script is read from stdin

      --ini            Show configuration file names

      --rf <name>      Show information about function <name>.
      --rc <name>      Show information about class <name>.
      --re <name>      Show information about extension <name>.
      --rz <name>      Show information about Zend extension <name>.
      --ri <name>      Show configuration for extension <name>.

Opções de linha de comando
Opção | Opção Estendida | Descrição
--- | --- | ---
-a | --interactive | Executa o PHP interativamente. Para mais informações veja a seção Shell interativo.
-b | --bindpath | Vincula o Path para o modo externo do servidor FASTCGI (apenas em CGI).
-C | --no-chdir | Não executa chdir para o diretório do script (apenas em CGI).
-q | --no-header | Modo silencioso. Suprime os cabeçalhos HTTP na saída (apenas em CGI).
-T | --timing | Calcula o tempo de execução do script repetidas count de vezes (apenas em CGI).
-c | --php-ini | Especifica um diretório para procurar pelo php.ini, ou um arquivo `INI` personalizado (que não precisa se chamar php.ini), exemplo:
    $ php -c /custom/directory/ my_script.php

    $ php -c /custom/directory/custom-file.ini my_script.php
Se essa opção não for especificada, o php.ini será procurado no local padrão.
-n | --no-php-ini | Ignore o php.ini completamente.
-d | --define | Define um valor personalizado para qualquer uma das diretivas de configuração permitidas em arquivos php.ini. A sintaxe é:
     -d configuration_directive[=value]
Exemplo #1 Exemplo de uso de `-d` para definir uma configuração INI
    # Omitir o valor irá configurar a diretiva para "1"
    $ php -d max_execution_time
            -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
    string(1) "1"

    # Passar um valor vazio irá configurar a detiva para ""
    php -d max_execution_time=
            -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
    string(0) ""

    # A diretiva de configudação será configurada para tudo o que estiver depois do sinal de '='
    $ php -d max_execution_time=20
            -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
    string(2) "20"
    $ php
            -d max_execution_time=doesntmakesense
            -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
    string(15) "doesntmakesense"
-e | --profile-info | Ativa o modo de informação estendido, para ser usado por um debugger/profiler.
-f | --file | Lê e executa o arquivo especificado. A opção -f é opcional e pode ser omitida - fornecer somente o nome do arquivo a ser executado é suficiente.
-h e -? | --help e --usage | Exibe uma lista de opções de linha de comando com a descrição do seu funcionamento.
-i | --info | Invoca phpinfo(), e exibe o resultado. Caso o PHP não esteja executando corretamente, é aconselhável usar o comando php -i e verificar se alguma mensagem de erro é informada antes ou no lugar da tabela de informações. Esteja ciente de que ao usar o modo CGI a saída será em HTML e portanto bastante longa.
-l | --syntax-check | Verifica a sintaxe mas não executa o código PHP informado. A entrada padrão será processada se nenhum arquivo for especificado, caso contrário cada arquivo será verificado. Em caso de sucesso, o texto `No syntax errors detected in <filename>` é escrito na saída padrão. Em caso de falha, o texto `Errors parsing <filename>` é escrito na saída padrão junto com o erro do analisador interno. Se alguma falha for encontrada nos arquivos especificados (ou na entrada padrão), o código de retorno do shell será `-1`, caso contrário o código de retorno será `0`. Esta opção encontrará erros fatais (como funções indefinidas) que requerem a execução do código. Nota: Antes do PHP 8.3.0, só era possível especificar um nome de arquivo para ser verificado. Nota: Essa opção não funciona em conjunto com a opção -r.
-m | --modules | Exemplo #2 Retorna os módulos PHP e Zend integrados e carregados
    $ php -m
    [PHP Modules]
    xml
    tokenizer
    standard
    session
    posix
    pcre
    overload
    mysql
    mbstring
    ctype

    [Zend Modules]
> -r | --run | Habilita a execução do código PHP incluído diretamente na linha de comando. As tags de abertura e fechamento do PHP (`<?php` e `?>`) não são necessárias e irão causar um erro de leitura caso sejam incluídas. Nota: Deve-se ter cuidado ao usar esta forma do PHP para não colidir com a substituição de variáveis de linha de comando realizadas pelo shell. Exemplo #3 Obtendo um erro de sintaxe ao usar aspas duplas
>     $ php -r "$foo = get_defined_constants();"
>     PHP Parse error:  syntax error, unexpected '=' in Command line code on line 1

>     Parse error: syntax error, unexpected '=' in Command line code on line 1
> O problema aqui é que o sh/bash realiza substituições de variáveis mesmo usando aspas duplas `"`. já que a variável $foo provavelmente não está definida, ela será avaliada como nada, o que faz com que o código passado ao PHP para execução na verdade seja lido como:
>     $ php -r " = get_defined_constants();"
> A maneira correta é usar aspas simples `'`. Variáveis em strings de aspas simples não são substituídas pelo sh/bash. Exemplo #4 Usando aspas simples para evitar a substituição de variáveis do shell
>     $ php -r '$foo = get_defined_constants(); var_dump($foo);'
>     array(370) {
>       ["E_ERROR"]=>
>       int(1)
>       ["E_WARNING"]=>
>       int(2)
>       ["E_PARSE"]=>
>       int(4)
>       ["E_NOTICE"]=>
>       int(8)
>       ["E_CORE_ERROR"]=>
>       [...]
Se estiver usando um ambiente de linha de comando que não seja sh/bash, outros problemas podem ser encontrados - caso necessário, um relato de problema pode ser aberto em » https://github.com/php/php-src/issues. Ainda assim é muito fácil encontrar problemas ao tentar usar variáveis (do shell ou do PHP) em código de linha de comando, ou usando barra invertida para escapar, por isso tenha muito cuidado quando fizer isso. Você foi avisado! Nota: -r está disponível no CLI SAPI, mas não no SAPI CGI. Nota: Essa opção é normalmente utilizada com código muito básico, portanto algumas diretivas de configuração (como auto_prepend_file e auto_append_file) são ignoradas nesse modo.
-B | --process-begin | Código PHP a ser executado antes de processar a entrada padrão.
-R | --process-code | Código PHP a ser executado para cada linha de entrada. Existem duas variáveis especiais disponíveis nesse modo: $argn e $argi. $argn conterá a linha que o PHP estiver processando no momento, enquanto $argi irá conter o número da linha.
-F | --process-file | Arquivo PHP a ser executado para cada linha de entrada.
-E | --process-end | Código PHP a ser executado após processar a entrada. Exemplo #5 Usando as opções -B, -R e -E para contar o número de linhas de um projeto.
    $ find my_proj | php -B '$l=0;' -R '$l += count(@file($argn));' -E 'echo "Total Lines: $l\n";'
    Total Lines: 37328
-S | --server | Inicia o servidor interno do PHP.
-t | --docroot | Específica a raiz do documento para o servidor interno do PHP.
-s | --syntax-highlight e --syntax-highlighting | Exibe o código com destaque de sintaxe em cores. Essa opção usa os mecanismos internos para interpretar os arquivos e escrever uma versão HTML colorida do código para a saída padrão. Repare que tudo que ele faz é gerar um bloco de tags HTML `<code> [...] </code>`, sem os cabeçalhos HTML. Nota: Essa opção não funciona em conjunto com a opção -r.
-v | --version | Exemplo #6 Usando -v para obter o nome do SAPI e a versão do PHP e do Zend
    $ php -v
    PHP 5.3.1 (cli) (built: Dec 11 2009 19:55:07)
    Copyright (c) 1997-2009 The PHP Group
    Zend Engine v2.3.0, Copyright (c) 1998-2009 Zend Technologies
-w | --strip | Exibe o código com remoção de comentários e de espaços em branco. Nota: Essa opção não funciona em conjunto com a opção -r.
| --ini | Exibir nomes de arquivos de configuração e diretórios verificados. Opcionalmente, passe `--ini=diff` para mostrar as diferenças entre os arquivos de configuração carregados e a configuração padrão. Exemplo #7 Exemplo de `--ini`
    $ php --ini
    Configuration File (php.ini) Path: /usr/dev/php/5.2/lib
    Loaded Configuration File:         /usr/dev/php/5.2/lib/php.ini
    Scan for additional .ini files in: (none)
    Additional .ini files parsed:      (none)
Nota: A opção `--ini=diff` não está disponivel em versões anteriores ao PHP 8.5.0.
--rf | --rfunction | Exibe informações sobre a função ou método de objeto informado (como por exemplo o número e nome dos parâmetros). Essa opção só está disponível se o PHP for compilado com suporte a Reflexão. Exemplo #8 uso básico da opção `--rf`
    $ php --rf var_dump
    Function [ <internal> public function var_dump ] {

      - Parameters [2] {
        Parameter #0 [ <required> $var ]
        Parameter #1 [ <optional> $... ]
      }
    }
--rc | --rclass | Exibe informações sobre uma determinada classe (lista de constantes, propriedades e métodos). Essa opção só está disponível se o PHP for compilado com suporte a Reflexão. Exemplo #9 exemplo de `--rc`
    $ php --rc Directory
    Class [ <internal:standard> class Directory ] {

      - Constants [0] {
      }

      - Static properties [0] {
      }

      - Static methods [0] {
      }

      - Properties [0] {
      }

      - Methods [3] {
        Method [ <internal> public method close ] {
        }

        Method [ <internal> public method rewind ] {
        }

        Method [ <internal> public method read ] {
        }
      }
    }
--re | --rextension | Exibe informações sobre uma determinada extensão (lista de opções do php.ini, funções definidas, constantes e classes). Essa opção só está disponível se o PHP for compilado com suporte a Reflexão. Exemplo #10 Exemplo de `--re`
    $ php --re json
    Extension [ <persistent> extension #19 json version 1.2.1 ] {

      - Functions {
        Function [ <internal> function json_encode ] {
        }
        Function [ <internal> function json_decode ] {
        }
      }
    }
--rz | --rzendextension | Exibe as informações de configuração de uma determinada extensão Zend (a mesma informação retornada pela phpinfo()).
--ri | --rextinfo | Exibe as informações de configuração de uma determinada extensão (as mesmas informações retornadas pela phpinfo()). As informações de configurações do núcleo da linguagem estão disponíveis usando "main" como nome da extensão. Exemplo #11 exemplo de `--ri`
    $ php --ri date

    date

    date/time support => enabled
    "Olson" Timezone Database Version => 2009.20
    Timezone Database => internal
    Default timezone => Europe/Oslo

    Directive => Local Value => Master Value
    date.timezone => Europe/Oslo => Europe/Oslo
    date.default_latitude => 59.930972 => 59.930972
    date.default_longitude => 10.776699 => 10.776699
    date.sunset_zenith => 90.583333 => 90.583333
    date.sunrise_zenith => 90.583333 => 90.583333

> Nota:

> As opções `-rBRFEH`, `--ini` e `--r[fcezi]` estão disponíveis somente no CLI.

## Executando arquivos PHP

Existem três formas de fornecer código PHP para ser executado pelo CLI SAPI:

1. Diga ao PHP para executar determinado arquivo.

       $ php my_script.php

       $ php -f my_script.php

   As duas formas (usando ou não a opção -f) executam o arquivo my_script.php. Note que não existe restrição sobre quais arquivos podem ser executados; em particular, o nome do arquivo não precisa conter a extensão `.php`.

2. Passa o código PHP diretamente através da linha de comando.

       $ php -r 'print_r(get_defined_constants());'

   Um cuidado especial deve ser tomado em relação a substituição de variáveis e o uso de aspas.

   > Nota:

   > Leia o exemplo cuidadosamente: não existem tags de abertura e fechamento! A opção -r simplesmente não necessita delas, e usá-las irá gerar um erro de interpretação.

3. Direciona a entrada padrão (`stdin`) para o código PHP.

   Isso dá a poderosa habilidade de criar código PHP dinamicamente e alimentar o binário, assim como demonstrado nesse exemplo fictício:

       $ some_application | some_filter | php | sort -u > final_output.txt

Você não pode combinar essas formas de executar o código.

Assim como qualquer aplicação de linha de comando, o PHP aceita qualquer quantidade de argumentos; entretanto, os scripts PHP também podem receber outros argumentos. A quantidade de argumentos que podem ser passados para o script não é limitada pelo PHP (e apesar do shell ter um limite no número de caracteres que podem ser passados, ele não é geralmente atingido). Os argumentos passados para os scripts ficam disponíveis no array global $argv. O primeiro índice (zero) sempre contém o nome do script que está sendo chamado pela linha de comando. Note que, se o código é executado diretamente usando a opção de linha de comando -r, o valor de $argv[0] será `"Standard input code"`; anteriormente ao PHP 7.2.0, isso era um hífen (`"-"`). A mesma coisa ocorre se o código é executado via um pipe a partir do `STDIN`.

Uma segunda variável global, $argc, contém o número de elementos contidos no array$argv array (não o número de argumentos passados para o script).

Desde que os argumentos passados pelo script não comecem com o caractere `-`, não existe nada em especial com que você deva se preocupar. Passar um argumento para o script que comece com `-` irá causar problemas, porque o interpretador do PHP irá pensar que ele mesmo deve manipular esse argumento, mesmo antes de executar o script. Para prevenir isso use o separador de lista de argumentos `--`. Depois que esse separador é interpretado pelo PHP, cada argumento seguinte é passado intocado para o script.

    # Isto não executará o código, apenas mostrará as opções do PHP
    $ php -r 'var_dump($argv);' -h
    Usage: php [options] [-f] <file> [args...]
    [...]

    # Isto passará o argumento '-h' para o script, assim evitando do PHP interpretá-lo
    $ php -r 'var_dump($argv);' -- -h
    array(2) {
      [0]=>
      string(1) "-"
      [1]=>
      string(2) "-h"
    }

Entretanto, em sistemas Unix existe uma outra maneira de usar o PHP em linha de comando: fazer com que a primeira linha do script comece com `#!/usr/bin/php` (ou qualquer que seja o caminho para o binário do PHP CLI caso seja diferente. O restante do arquivo deve conter código PHP normal com as já tradicionais tags de abertura e fechamento. Uma vez que os atributos de execução do arquivo estejam apropriadamente definidos (exemplo. chmod +x test), o script poderá ser executado como qualquer outro script shell ou perl:

Exemplo #1 Executando scripts PHP como shell scripts

    #!/usr/bin/php
    <?php
    var_dump($argv);
    ?>

Assumindo que esse arquivo tenha o nome test no diretório atual, é possível fazer o seguinte:

    $ chmod +x test
    $ ./test -h -- foo
    array(4) {
      [0]=>
      string(6) "./test"
      [1]=>
      string(2) "-h"
      [2]=>
      string(2) "--"
      [3]=>
      string(3) "foo"
    }

Como pode ser visto, nesse caso nenhum cuidado especial precisa ser tomado ao passar parâmetros começando com `-`.

O executável do PHP pode ser usado para rodar scripts absolutamente independentes do servidor web. Em sistemas Unix, a primeira linha especial `#!` (ou "shebang") deve ser adicionada a scripts PHP para que o sistema possa automaticamente dizer qual programa deve executar o script. Em plataformas Windows, é possível associar o php.exe com um clique duplo no arquivos com extensão `.php`, ou um arquivo batch pode ser criado para rodar scripts através do PHP. A primeira linha especial shebang para Unix não causa nenhum efeito no Windows (já que é formatada como um comentário PHP), então programas multiplataforma podem ser escritos com a inclusão disso. Um exemplo simples de programa de linha de comando em PHP é mostrado abaixo.

Exemplo #2 Script planejado para ser executado na linha de comando (script.php)

    #!/usr/bin/php
    <?php

    if ($argc != 2 || in_array($argv[1], array('--help', '-help', '-h', '-?'))) {
    ?>

    This is a command line PHP script with one option.

      Usage:
      <?php echo $argv[0]; ?> <option>

      <option> can be some word you would like
      to print out. With the --help, -help, -h,
      or -? options, you can get this help.

    <?php
    } else {
        echo $argv[1];
    }
    ?>

O script acima inclui a shebang na primeira linha para indicar que esse arquivo deve ser executado pelo PHP. Nós estamos trabalhando com a versão CLI aqui, então nenhum cabeçalho HTTP será exibido.

O programa primeiramente verifica se o primeiro argumento obrigatório foi passado (juntamente com o nome do arquivo, que também é contabilizado). Em caso negativo, ou caso o argumento seja --help, -help, -h ou -?, uma mensagem de ajuda é disparada, usando $argv[0] para imprimir dinamicamente o nome do script como foi digitado na linha de comando. Do contrário, o argumento é exibido da forma como foi escrito.

Para executar o script acima em sistemas Unix, ele deve ser tornado executável, e chamado simplesmente com script.php echothis ou script.php -h. Em sistemas Windows, um arquivo batch similar ao seguinte pode ser criado para essa tarefa:

Exemplo #3 Arquivo batch para rodar um script de linha de comando em PHP (script.bat)

    @echo OFF
    "C:\php\php.exe" script.php %*

Assumindo que o programa acima foi nomeado como script.php, e que o CLI php.exe está em C:\php\php.exe, esse arquivo batch irá executá-lo, repassando todas as opções: script.bat echothis ou script.bat -h.

Veja também a documentação da extensão Readline com mais funções usadas para melhorar as aplicações de linha de comando em PHP.

No Windows, o PHP pode ser configurado para rodar sem a necessidade de informar o C:\php\php.exe ou a extensão`.php`, como descrito em PHP para linha de comando no Microsoft Windows.

> Nota:

> No Windows é recomendado rodar o PHP em uma conta de usuário normal. Ao rodar em uma conta de serviço certas operações podem falhar, por conta da situação "No mapping between account names and security IDs was done" (não foi feito nenhum mapeamento entre nomes de contas e IDs de segurança).

## Fluxos de entrada/saída

O CLI SAPI define algumas constantes para fluxos de E/S com o objetivo de tornar a programação em linha de comando um pouco mais fácil.

Constantes específicas da CLI
Constante | Descrição
--- | ---
`STDIN` | Um fluxo já aberto para o `stdin`. Isso evita ter que abrí-lo com
    <?php
    $stdin = fopen('php://stdin', 'r');
    ?>
Se você desejar ler uma única linha do `stdin`, você pode usar
    <?php
    $line = trim(fgets(STDIN)); // Lê uma linha do STDIN
    fscanf(STDIN, "%d\n", $number); // Lê um número do STDIN
    ?>
`STDOUT` | Um fluxo já aberto para o `stdout`. Isso evitar ter que abrí-lo com
    <?php
    $stdout = fopen('php://stdout', 'w');
    ?>
`STDERR` | Um fluxo já aberto com `stderr`. Isso evita ter que abri-lo com
    <?php
    $stderr = fopen('php://stderr', 'w');
    ?>

Como dito acima, não é necessário, por exemplo, abrir um fluxo para `stderr` por si mesmo, basta usar a constante ao invés do recurso do fluxo:

    php -r 'fwrite(STDERR, "stderr\n");'

Você não precisa fechar explicitamente esses fluxos, já que eles serão automaticamente fechados pelo PHP quando o script terminar.

> Nota:

> Essas constantes não estão disponíveis se estiver lendo os scripts PHP de `stdin`.

## Shell interativo

O CLI SAPI fornece um shell interativo usando a opção -a se o PHP for compilado com a opção --with-readline. A partir do PHP 7.1.0 o shell interativo também está disponível no Windows, se a extensão readline estiver habilitada.

Usando o shell interativo você será capaz de escrever código PHP e executá-lo diretamente.

Exemplo #1 Executando código usando o shell interativo

    $ php -a
    Interactive shell

    php > echo 5+8;
    13
    php > function addTwo($n)
    php > {
    php { return $n + 2;
    php { }
    php > var_dump(addtwo(2));
    int(4)
    php >

O shell interativo também possui sugestões de complemento com tab para funções, constantes, nomes de classes, variáveis, chamadas para métodos estáticos e constantes de classe.

Exemplo #2 Sugestões de complemento com tab

Pressionar a tecla tab duas vezes quando tiver mais de uma sugestão de complemento resultará numa lista desses complementos.

    php > strp[TAB][TAB]
    strpbrk   strpos    strptime
    php > strp

Quando existir apenas um possível complemento, pressionar a tecla tab uma vez irá completar o restante da mesma linha:

    php > strpt[TAB]ime(

Complementos também funcionarão para nomes que forem definidos durante a mesma sessão do shell interativo:

    php > $fooThisIsAReallyLongVariableName = 42;
    php > $foo[TAB]ThisIsAReallyLongVariableName

O shell interativo armazena seu histórico que pode ser acessado usando as teclas para cima e para baixo. O histórico é salvo no arquivo ~/.php_history. A partir do PHP 8.4.0, o caminho para o arquivo de histórico pode ser definido usando a variável de ambiente PHP_HISTFILE.

O CLI SAPI fornece as configurações do php.ini `cli.pager` e `cli.prompt`. A configuração `cli.pager` permite que um programa externo (como o less) aja como uma alternativa para a saída ao invés dela ser exibida diretamente na tela. A configuração `cli.prompt` faz com que seja possível alterar a saída `php >`.

Também é possível definir configurações php.ini no shell interativo usando uma notação abreviada.

Exemplo #3 Definindo configurações php.ini no shell interativo

A opção `cli.prompt`:

    php > #cli.prompt=hello world :>
    hello world :>

Usando acento grave é possível executar o PHP diretamente no terminal:

    php > #cli.prompt=`echo date('H:i:s');` php >
    15:49:35 php > echo 'hi';
    hi
    15:49:43 php > sleep(2);
    15:49:45 php >

Setando o paginador paraless:

    php > #cli.pager=less
    php > phpinfo();
    (output displayed in less)
    php >

A configuração `cli.prompt` suporta algumas sequências de escape:

Sequências de escape do `cli.prompt`
Sequência | Descrição
--- | ---
`\e` | Usada para adicionar cores ao terminal. Um exemplo pode ser `\e[032m\v \e[031m\b \e[34m\> \e[0m`
`\v` | A versão do PHP.
`\b` | Indica em qual bloco o PHP está. Por exemplo `/*` irá indicar que o PHP está dentro de um comentário de múltiplas linhas. O escopo externo será denominado por `php`.
`\>` | Indica o caractere do terminal. Por padrão é `>`, mas pode alterar quando o shell estiver dentro de um bloco indeterminado ou de uma string. Possíveis caracteres são: `' " { ( >`

> Nota:

> Arquivos incluídos através de auto_prepend_file e auto_append_file são interpretados nesse modo porém com algumas restrições - Exemplo: funções devem ser definidas antes de sua chamada.

## Modo interarativo

Se a extensão readline não estiver disponível, anteriormente ao PHP 8.1.0, chamar o CLI SAPI com a opção -a fornecia o modo interativo. Nesse modo, um script PHP completo deveria ser fornecido via STDIN, terminado por uma sequência de ``CTRL` +`D`` (POSIX) ou ``CTRL` +`Z`` seguido de +`ENTER` (Windows), para que o script seja avaliado. Isto é basicamente o mesmo que invocar CLI SAPI sem a opção -a.

A partir do PHP 8.1.0, chamar a CLI SAPI com a opção -a falhará na ausência da extensão readline.

## Servidor web embutido

Aviso

Esse servidor web foi desenvolvido para auxiliar no desenvolvimento de aplicações. Ele também pode ser útil para testes ou para demonstrações de aplicações que forem executadas em ambientes controlados. Ele não foi desenvolvido para ser um web server completo. Ele não deve ser utilizado em uma rede pública.

O CLI SAPI fornece um servidor web embutido.

Esse servidor embutido roda apenas um processo single-thread, de forma que aplicações PHP irão congelar se uma requisição bloquear.

Requisições de URI são servidas a partir do diretório atual onde o PHP foi iniciado, a não ser que a opção -t seja usada para especificar uma raiz de documento explicitamente. Se uma requisição de URI especificar um arquivo específico então ou o index.php ou index.html no diretório em questão será retornado. Se nenhum deles existir, a procura por index.php e index.html continuará nos diretórios superiores até que algum deles seja encontrado ou o document root seja alcançado. Caso um index.php ou index.html seja encontrado então é retornado e $_SERVER['PATH_INFO'] é configurado para a parte final da URI. Caso contrário, uma resposta 404 é retornada.

Se um arquivo PHP for fornecido na linha de comando quando o servidor web for iniciado ele será tratado como roteador. O script é executado no início de cada requisição HTTP. Se o script retornar `false`, então o recurso requisitado será retornado da maneira como estiver. Do contrário, a saída do script será retornada para o navegador.

Tipos MIME padrão serão retornados para arquivos com extensões: `.3gp`, `.apk`, `.avi`, `.bmp`, `.css`, `.csv`, `.doc`, `.docx`, `.flac`, `.gif`, `.gz`, `.gzip`, `.htm`, `.html`, `.ics`, `.jpe`, `.jpeg`, `.jpg`, `.js`, `.kml`, `.kmz`, `.m4a`, `.mov`, `.mp3`, `.mp4`, `.mpeg`, `.mpg`, `.odp`, `.ods`, `.odt`, `.oga`, `.ogg`, `.ogv`, `.pdf`, `.png`, `.pps`, `.pptx`, `.qt`, `.svg`, `.swf`, `.tar`, `.text`, `.tif`, `.txt`, `.wav`, `.webm`, `.wmv`, `.xls`, `.xlsx`, `.xml`, `.xsl`, `.xsd`, `.zip` .

A partir do PHP 7.4.0, o servidor web interno pode ser configurado para se bifurcar em múltiplos processos para testar código que requer múltiplas requisições concorrentes ao servidor web interno. Configure a variável de ambiente PHP_CLI_SERVER_WORKERS para o número de processos desejados antes de iniciar o servidor.

> Nota: Este recurso não é suportado no Windows.

> Nota: Para informações sobre o uso e as opções do PHP em linha de comando, execute php --help ou man php. Nem todas as opções se aplicam quando o PHP está sendo executado como servidor web.

Aviso

Este recurso experimental não foi projetado para uso em ambiente de produção. Geralmente, o servidor web interno não tem o objetivo de ser usado em ambiente de produção.

Exemplo #1 Iniciando o servidor web

    $ cd ~/public_html
    $ php -S localhost:8000

O terminal irá exibir:

    PHP 5.4.0 Development Server started at Thu Jul 21 10:43:28 2011
    Listening on localhost:8000
    Document root is /home/me/public_html
    Press Ctrl-C to quit

Após serem feitas requisições de URI para for http://localhost:8000/ e http://localhost:8000/myscript.html o terminal irá exibir algo similar a:

    PHP 5.4.0 Development Server started at Thu Jul 21 10:43:28 2011
    Listening on localhost:8000
    Document root is /home/me/public_html
    Press Ctrl-C to quit.
    [Thu Jul 21 10:48:48 2011] ::1:39144 GET /favicon.ico - Request read
    [Thu Jul 21 10:48:50 2011] ::1:39146 GET / - Request read
    [Thu Jul 21 10:48:50 2011] ::1:39147 GET /favicon.ico - Request read
    [Thu Jul 21 10:48:52 2011] ::1:39148 GET /myscript.html - Request read
    [Thu Jul 21 10:48:52 2011] ::1:39149 GET /favicon.ico - Request read

Note que antes do PHP 7.4.0, recursos estáticos representados por symlinks não eram acessíveis pelo Windows, sendo necessário um script de roteamento nesses casos.

Exemplo #2 Iniciando o servidor web com um diretório raiz específico

    $ cd ~/public_html
    $ php -S localhost:8000 -t foo/

O terminal irá exibir:

    PHP 5.4.0 Development Server started at Thu Jul 21 10:50:26 2011
    Listening on localhost:8000
    Document root is /home/me/public_html/foo
    Press Ctrl-C to quit

Exemplo #3 Usando um script de roteamento

Nesse exemplo, requisições para imagens serão exibidas, mas requisições para arquivos HTML irão exibir "Welcome to PHP":

    <?php
    // router.php
    if (preg_match('/\.(?:png|jpg|jpeg|gif)$/', $_SERVER["REQUEST_URI"])) {
        return false;    // serve o recurso requisitado sem modificação.
    } else {
        echo "<p>Welcome to PHP</p>";
    }
    ?>

    $ php -S localhost:8000 router.php

Exemplo #4 Verificando o Uso do CLI Web Server

Para reutilizar um script de roteamento específico de um framework durante o desenvolvimento com o servidor web CLI e depois também em um servidor de produção:

    <?php
    // router.php
    if (php_sapi_name() == 'cli-server') {
        /* roteia ativos estáticos e retorna false */
    }
    /* continua com operações normais do index.php */
    ?>

    $ php -S localhost:8000 router.php

Exemplo #5 Tratando de tipos de arquivos não suportados

Se você precisar servir um recurso estático cujo MIME type não é tratado pelo servidor web CLI, use:

    <?php
    // router.php
    $path = pathinfo($_SERVER["SCRIPT_FILENAME"]);
    if ($path["extension"] == "el") {
        header("Content-Type: text/x-script.elisp");
        readfile($_SERVER["SCRIPT_FILENAME"]);
    }
    else {
        return FALSE;
    }
    ?>

    $ php -S localhost:8000 router.php

Exemplo #6 Acessando o servidor web CLI de máquinas remotas

Você pode tornar o servidor web acessível na porta 8000 para qualquer interface com:

    $ php -S 0.0.0.0:8000

Aviso

O servidor web embutido não deve ser exposto em redes públicas.

## Configurações INI

Opções de configuração da CLI SAPI
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
cli_server.color | "0" | `INI_ALL` |

Aqui está uma breve explicação das diretivas de configuração.

`cli_server.color` bool

  Habilita o uso de cores ANSI na saída do terminal pelo servidor web.

# Coletor de Lixo

## Índice

- Básico sobre Contagem de Referência
- Ciclos de Coleta
- Considerações de Desempenho

Esta seção explica os méritos do novo mecanismo do Coletor de Lixo (também conhecido como GC - Garbage Collector) que é parte do PHP 5.3.

## Básico sobre Contagem de Referência

Uma variável PHP é armazenada em um contêiner chamado "zval". Um zval contém, além do tipo e do valor da variável, dois bits adicionais de informação. O primeiro é chamado de "is_ref" e é um valor booleano que indica se a variável é parte de um "conjunto de referência" ou não. Com este bit, o motor do PHP sabe como diferenciar variáveis normais de referências. Como o PHP permite referências no nível do usuário, como as criadas pelo operador &, um contêiner zval também tem um mecanismo de contagem de referência interno para otimizar o uso de memória. Esta segunda parte de informação adicional, chamado "refcount", contém a quantidade de nomes de variáveis (também chamadas de símbolos) que apontam para este contêiner. Todos os símbolos são armazenados em uma tabela de símbolos, e existe uma por escopo. Existe um escopo para o script principal (ou seja, aquele requisitado através do navegador), assim como um escopo para cada função ou método.

Um contêiner zval é criado quando uma nova variável é criada com um valor constante, como em:

Exemplo #1 Criando um novo contêiner zval

    <?php
    $a = "new string";
    ?>

Neste caso, o nome do símbolo, `a`, é criado no escopo atual, e um novo contêiner de variável é criado com o tipo string e o valor `new string`. O bit "is_ref" é por padrão definido para `false` porque nenhuma referência no nível do usuário foi criada. O "refcount" é definido para `1` já que existe apenas um símbolo que faz uso deste contêiner de variável. Note que referências (isto é, "is_ref" igual a `true`) com "refcount" igual a `1`, são tratadas como se elas não fossem referências (como se "is_ref" fosse `false`). Se o » Xdebug estiver instalado, esta informação pode ser mostrada chamando-se a função xdebug_debug_zval().

Exemplo #2 Mostrando a informação zval

    <?php
    $a = "new string";
    xdebug_debug_zval('a');
    ?>

O exemplo acima produzirá:

    a: (refcount=1, is_ref=0)='new string'

Atribuir esta variável a outro nome de variável irá aumentar o "refcount".

Exemplo #3 Aumentando o "refcount" de um zval

    <?php
    $a = "new string";
    $b = $a;
    xdebug_debug_zval( 'a' );
    ?>

O exemplo acima produzirá:

    a: (refcount=2, is_ref=0)='new string'

O refcount é `2` aqui, porque o mesmo contêiner de variável está ligado tanto com a quanto com b. O PHP é inteligente o suficiente para não copiar o contêiner real da variável quando não for necessário. Contêineres são destruídos quando o "refcount" atinge zero. O "refcount" é diminuído em uma unidade quando qualquer símbolo ligado ao contêiner da variável deixa o escopo (ex.: quando a função termina) ou quando um símbolo perde a atribuição (ex.: chamando unset()). O exemplo a seguir mostra isso:

Exemplo #4 Diminuindo o "refcount" de zval

    <?php
    $a = "new string";
    $c = $b = $a;
    xdebug_debug_zval( 'a' );
    $b = 42;
    xdebug_debug_zval( 'a' );
    unset( $c );
    xdebug_debug_zval( 'a' );
    ?>

O exemplo acima produzirá:

    a: (refcount=3, is_ref=0)='new string'
    a: (refcount=2, is_ref=0)='new string'
    a: (refcount=1, is_ref=0)='new string'

Se agora `unset($a);` for chamada, o contêiner da variável, incluindo o tipo e o valor, serão removidos da memória.

### Tipos Compostos

As coisas ficam um pouco mais complexas com tipos compostos como arrays e objects. Ao contrário dos valores escalares, arrays e objects armazenam suas propriedades em uma tabela de símbolos própria. Isto significa que o exemplo a seguir cria três contêineres zval:

Exemplo #5 Criando um zval de array

    <?php
    $a = array( 'meaning' => 'life', 'number' => 42 );
    xdebug_debug_zval( 'a' );
    ?>

O exemplo acima produzirá algo semelhante a:

    a: (refcount=1, is_ref=0)=array (
       'meaning' => (refcount=1, is_ref=0)='life',
       'number' => (refcount=1, is_ref=0)=42
    )

Ou graficamente

Os três contêineres zval são: a, meaning, e number. Regras similares se aplicam para aumento e redução de "refcounts". Abaixo, outro elemento é adicionado ao array, e define seu valor ao conteúdo de um elemento já existente:

Exemplo #6 Adicionando elemento já existente a um array

    <?php
    $a = array( 'meaning' => 'life', 'number' => 42 );
    $a['life'] = $a['meaning'];
    xdebug_debug_zval( 'a' );
    ?>

O exemplo acima produzirá algo semelhante a:

    a: (refcount=1, is_ref=0)=array (
       'meaning' => (refcount=2, is_ref=0)='life',
       'number' => (refcount=1, is_ref=0)=42,
       'life' => (refcount=2, is_ref=0)='life'
    )

Ou graficamente

Pela saída do Xdebug acima, pode-se perceber que tanto o elemento antigo do array quanto o novo agora apontam para um contêiner zval cujo "refcount" é `2`. Embora a saída do Xdebug mostre dois contêineres zval com valor `'life'`, eles são o mesmo. A função xdebug_debug_zval() não mostra isso, mas pode-se ver isso mostrando o ponteiro de memória.

Remover o elemento de um array é como remover um símbolo de um escopo. Fazendo isso, o "refcount" de um contêiner ao qual um elemento do array aponta é reduzido. Novamente, quando o "refcount" atinge zero, o contêiner da variável é removido da memória. Um exemplo para mostrar isto:

Exemplo #7 Removendo um elemento de um array

    <?php
    $a = array( 'meaning' => 'life', 'number' => 42 );
    $a['life'] = $a['meaning'];
    unset( $a['meaning'], $a['number'] );
    xdebug_debug_zval( 'a' );
    ?>

O exemplo acima produzirá algo semelhante a:

    a: (refcount=1, is_ref=0)=array (
       'life' => (refcount=1, is_ref=0)='life'
    )

Agora, as coisas ficam interessantes se o próprio array for adicionado como um elemento do array, o que é mostrado no exemplo a seguir, onde também um operador de referência foi inserido, senão o PHP criaria uma cópia:

Exemplo #8 Adicionando o próprio array como um elemento de si mesmo

    <?php
    $a = array( 'one' );
    $a[] =& $a;
    xdebug_debug_zval( 'a' );
    ?>

O exemplo acima produzirá algo semelhante a:

    a: (refcount=2, is_ref=1)=array (
       0 => (refcount=1, is_ref=0)='one',
       1 => (refcount=2, is_ref=1)=...
    )

Ou graficamente

Pode-se perceber que a variável do array (a) assim como o segundo elemento (1) agora apontam para um contêiner de variável que tem um "refcount" de `2`. Os "..." no exemplo acima mostram que há recursão envolvida, e que, obviamente, neste caso significa que os "..." apontam de volta ao array original.

Como antes, tirar a atribuição de uma variável remove o símbolo, e a contagem de referência do contêiner da variável à qual o símbolo aponta é reduzida em uma unidade. Então, se a variável $a perder a atribuição após execução do código acima, a contagem de referência do contêiner da variável à qual $a e o elemento "1" apontam será diminuída em uma unidade, de "2" para "1". Isto pode ser representado assim:

Exemplo #9 Removendo a atribuição de $a

    (refcount=1, is_ref=1)=array (
       0 => (refcount=1, is_ref=0)='one',
       1 => (refcount=1, is_ref=1)=...
    )

Ou graficamente

### Problemas na Limpeza

Embora não haja mais um símbolo em nenhum escopo apontando para esta estrutura, ela não pode ser limpa porque o elemento "1" do array ainda aponta para este mesmo array. Como não há símbolo externo apontando para ela, não há como um usuário limpar esta estrutura; e aí acontece o vazamento de memória. Felizmente, o PHP irá limpar esta estrutura de dados no final da requisição, mas até lá, ela irá ocupar um espaço valioso na memória. Esta situação ocorre frequentemente quando se está implementando algoritmos de interpretação ou outros onde existe um elemento "filho" apontando de volta para um elemento "pai". A mesma situação também pode com certeza ocorrer com objetos, onde na verdade existe mais probabilidade de ocorrer, já que objetos são sempre implicitamente usados "por referência".

Isso pode não ser um problema quanto acontecer somente uma ou duas vezes, mas se houver milhares, ou até milhões dessas perdas de memória, obviamente começa a ser um problema. É especialmente problemático em scripts de execução longa, como daemons onde a requisição basicamente nunca termina, ou em grandes conjuntos de testes de unidades. Este último já causou problemas durante a execução de testes de unidades para o componente Template da bilioteca eZ Components. Em alguns casos, era necessário mais de 2GB de memória, que o servidor de testes não tinha.

## Ciclos de Coleta

Tradicionalmente, mecanismos de memória de contagem de referência, como os usados anteriormente pelo PHP, falham ao lidar com vazamentos de memória de referência circular; entretanto, desde a versão 5.3.0, o PHP implementa o algoritmo síncrono do artigo » Concurrent Cycle Collection in Reference Counted Systems que lida com este problema.

Uma explicação completa de como o algoritmo funciona estaria um pouco além do escopo desta seção, mas o básico é explicado aqui. Primeiramente, deve-se estabelecer algumas regras gerais. Se um "refcount" é incrementado, ele ainda está em uso e, portanto, não é lixo. Se o refcount é reduzido e alcança zero, o zval pode ser liberado. Isso significa que os ciclos de coleta somente podem ser criados quando um argumento "refcount" é reduzido para um valor diferente de zero. Adicionalmente, em um ciclo de coleta, é possível descobrir quais partes são lixo, verificando se é possível reduzir seus "refcounts" em uma unidade, e então observando quais dos zvals têm um "refcount" diferente de zero.

Para evitar chamadas de verificação de ciclos de coleta com qualquer redução possível de um refcount, o algoritmo em vez disso coloca todas as raízes (zvals) possíveis no "buffer de raízes" (tornando-os "roxos"). Ele também certifica que cada raiz possível chegue ao buffer apenas uma vez. Apenas quando o buffer de raízes está cheio é que o mecanismo de coleta se inicia para todos os diferentes zvals contidos. Veja o passo A na figura acima.

No passo B, o algoritmo executa uma pesquisa em profundidade em todas as raízes possíveis para reduzir em um os refcounts de cada zval que ele encontra, certificando-se de não reduzir um refcount no mesmo zval duas vezes (marcando-os de "cinza"). No passo C, o algoritmo novamente executa uma pesquisa em profundidade a partir de cada nó de raiz, para verificar o refcount de cada zval de novo. Se ele encontra o valor zero, o zval é marcado de "branco" (azul na figura). Se ele for maior que zero, ele reverte a redução do refcount em uma unidade com uma pesquisa em profundidade daquele ponto em diante, e eles são marcados de "preto" novamente. No último passo (D), o algoritmo percorre o buffer de raízes removendo as raízes de zval de lá e, ao mesmo tempo, verifica quais zvals foram marcados de "branco" no passo anterior. Cada zval marcado de "branco" será liberado da memória.

Agora que há um entendimento básico de como o algoritmo funciona, vejamos como isto se integra com o PHP. Por padrão, o coletor de lixo do PHP fica habilitado. Existe, porém uma configuração do php.ini que permite mudar isso: zend.enable_gc.

Quando o coletor de lixo é habilitado, o algoritmo de pesquisa de ciclos como descrito acima é executado toda vez que o buffer ficar cheio. O buffer de raízes tem um tamanho fixo de 10.000 raízes possíveis (embora isso possa ser alterado mudando-se a constante `GC_THRESHOLD_DEFAULT` em `Zend/zend_gc.c` no código-fonte do PHP, e recompilando-o). Quando o coletor de lixo é desabilitado, o algoritmo de pesquisa de ciclos nunca será executado. Entretanto, possíveis raízes serão sempre registradas no buffer de raízes, não importando se o mecanismo de coleta de lixo tenha sido ou não habilitado com esta configuração.

Se o buffer de raízes ficar cheio de raízes possíveis enquanto o mecanismo de coleta de lixo está desabilitado, as possíveis raízes adicionais simplesmente não serão registradas. Essas raízes não registradas nunca serão analisadas pelo algoritmo. Se eles fossem parte de um ciclo de referência circular, eles nunca seriam eliminados e iriam criar um vazamento de memória.

O motivo pelo qual as raízes possíveis são registradas mesmo se o mecanismo for desabilitado é porque é mais rápido registrar raízes possíveis do que ter que verificar se o mecanismo está ligado toda vez que uma raiz possível puder ser encontrada. O próprio mecanismo de coleta e análise de lixo, no entanto, pode levar um tempo considerável.

Além de mudar a configuração zend.enable_gc, também é possível habilitar e desabilitar o mecanismo de coleta de lixo chamando-se gc_enable() ou gc_disable() respectivamente. Chamar estas funções tem o mesmo efeito de ligar ou desligar o mecanismo com a configuração. Também é possível forçar a coleta de ciclos mesmo se o buffer de raízes possíveis não estiver cheio. Para isto, pode-se usar a função gc_collect_cycles(). Esta função retorna quantos ciclos foram coletados pelo algoritmo.

A razão por trás da possibilidade do próprio usuário ligar e desligar o mecanismo, e iniciar a coleta de ciclos, é que algumas partes de aplicações podem ser altamente sensíveis a tempo de execução. Nesses casos, pode não ser desejado que o mecanismo de coleta inicie. Obviamente, desligar o coletor de lixo para certas partes de uma aplicação cria o risco de gerar vazamentos de memória porque algumas raízes possíveis podem não caber no buffer limitado. Portanto, provavelmente é mais sábio chamar a função gc_collect_cycles() logo antes de chamar a função gc_disable() para liberar a memória que poderia ser perdida através de raízes possíveis que estariam já registradas no buffer. Isso então leva a um buffer vazio para que haja mais espaço para armazenar raízes possíveis enquanto o mecanismo de ciclos de coleta está desligado.

## Considerações de Desempenho

Já foi mencionado na seção anterior que simplesmente coletar as raízes possíveis tem um impacto muito pequeno em desempenho, mas isso quando compara-se o PHP 5.2 com o PHP 5.3. Embora o registro de raízes possíveis comparado ao não registro, como no PHP 5.2, seja mais lento, outras mudanças em tempo de execução no PHP 5.3 evitam que esta perda particular de desempenho apareça.

Existem duas grandes áreas onde o desempenho é afetado. A primeira é o uso reduzido de memória, e a segunda é o atraso em tempo de execução quando o mecanismo de coleta de lixo faz suas limpezas de memória. Estes dois problemas serão mostrados a seguir.

### Uso Reduzido de Memória

Primeiramente, o grande motivo pelo qual o mecanismo de coleta de lixo existe é para reduzir o uso de memória através de limpeza de variáveis em referência circular assim que os pré-requisitos são preenchidos. Na implementação do PHP, isso acontece assim que o buffer de raízes fica cheio, ou quando a função gc_collect_cycles() é chamada. No gráfico abaixo, é mostrado o uso de memória do script a seguir, tanto no PHP 5.2 quanto no PHP 5.3, excluindo a memória básica que o próprio PHP usa quando se inicia.

Exemplo #1 Exemplo de uso de memória

    <?php
    class Foo
    {
        public $var = '3.14159265359';
        public $self;
    }

    $baseMemory = memory_get_usage();

    for ( $i = 0; $i <= 100000; $i++ )
    {
        $a = new Foo;
        $a->self = $a;
        if ( $i % 500 === 0 )
        {
            echo sprintf( '%8d: ', $i ), memory_get_usage() - $baseMemory, "\n";
        }
    }
    ?>

Neste exemplo bem acadêmico, está sendo criado um objeto no qual uma propriedade é definida para apontar para o próprio objeto. Quando a variável $a no script é re-atribuída na iteração seguinte do loop, um vazamento de memória normalmente iria acontecer. Neste caso, dois contêineres são vazados (o zval objeto e o zval propriedade), mas apenas uma raiz possível é encontrada: a variável que perdeu a atribuição. Quando o buffer de raízes está cheio depois de 10.000 iterações (com um total de 10.000 raízes possíveis), o mecanismo de coleta de lixo entra e libera a memória associada com essas raízes possíveis. Isto pode ser visto claramente com o gráfico irregular de uso de memória para o PHP 5.3. Depois de 10.000 iterações, o mecanismo entre e libera a memória associada com as variáveis com referência circular.. O mecanismo em si não tem muito trabalho neste exemplo, porque a estrutura que é vazada é extremamente simples. Pelo diagrama, pode-se verificar que o uso de memória no PHP 5.3 é de aproximadamente 9Mb, enquanto que no PHP 5.2 o uso de memória continua crescendo.

### Atraso em Tempo de Execução

A segunda área onde o mecanismo de coleta de lixo influencia o desempenho é o tempo gasto quando o mecanismo entra para liberar a memória "vazada". Para verificar quanto é este tempo, o script anterior foi minimamente modificado para permitir um número maior de iterações e a remoção dos números de uso de memória intermediária. O segundo script está apresentado a seguir:

Exemplo #2 Influência do Coletor de Lixo no desempenho

    <?php
    class Foo
    {
        public $var = '3.14159265359';
        public $self;
    }

    for ( $i = 0; $i <= 1000000; $i++ )
    {
        $a = new Foo;
        $a->self = $a;
    }

    echo memory_get_peak_usage(), "\n";
    ?>

O script será executado duas vezes, uma com a configuração zend.enable_gc habilitada, e outra desabilitada:

Exemplo #3 Executando o script acima

    time php -dzend.enable_gc=0 -dmemory_limit=-1 -n example2.php
    # e
    time php -dzend.enable_gc=1 -dmemory_limit=-1 -n example2.php

Em uma máquina específica, o primeiro comando parece levar 10.7 segundos, enquanto que o segundo leva 11.4 segundos. Isto é um atraso de aproximadamente 7%. Entretanto, a quantidade máxima de memória usada pelo script é reduzida em 98%, de 931Mb para 10Mb. Esta referência não é muito científica, ou mesmo representativa para aplicações do mundo real, mas demonstra os benefícios de uso de memória que este mecanismo de coleta de lixo fornece. A boa notícia é que este atraso é sempre de 7% para este script particular, enquanto que as capacidades de redução de memória economizam mais e mais memória quando referências circulares adicionais são encontradas durante a execução do script.

### Estatísticas de GC Internas do PHP

É possível obter um pouco mais de informação sobre como o o mecanismo de coleta de lixo é executado no PHP. Mas para fazer isto, deve-se recompilar o PHP para habilitar o benchmark e o código de coleta de dados. Deve-se definir a variável de ambiente `CFLAGS` para `-DGC_BENCH=1` antes de executar `./configure` com as opções desejadas. A sequência a seguir deve fazer este truque:

Exemplo #4 Recompilando o PHP para habilitar o benchmarking de GC

    export CFLAGS=-DGC_BENCH=1
    ./config.nice
    make clean
    make

Quando o exemplo acima for executado novamente com o novo binário do PHP, o resultado abaixo será visualizado assim que o PHP terminar a execução:

Exemplo #5 Estatísticas GC

    GC Statistics
    -------------
    Runs:               110
    Collected:          2072204
    Root buffer length: 0
    Root buffer peak:   10000

          Possible            Remove from  Marked
            Root    Buffered     buffer     grey
          --------  --------  -----------  ------
    ZVAL   7175487   1491291    1241690   3611871
    ZOBJ  28506264   1527980     677581   1025731

As estatísticas mais informativas são mostradas no primeiro bloco. Pode-se ver aqui que o mecanismo de coleta de lixo foi executado 110 vezes, e no total, mais de 2 milhões de alocações de memória foram liberadas durante estas 110 execuções. Assim que o mecanismo tenha sido executado pelo menos uma vez, o "Root buffer peak" (pico do buffer de raízes) será sempre 10.000.

### Conclusão

Em geral, o coletor de lixo no PHP irá causar um atraso apenas quando o algoritmo de coleta realmente for executado, enquanto que em scripts normais (menores), não deve haver nenhum prejuízo no desempenho.

Entretanto, em casos onde o mecanismo de coleta é executado em scripts normais, a redução de memória que ele vai proporcionar irá permitir que mais desses scripts possam ser executados ao mesmo tempo no servidor, já que a quantidade de memória usada no total não será muito grande.

Os benefícios são mais aparentes para scripts de longa execução, como os scripts de conjunto de testes ou daemons. Adicionalmente, para aplicações » PHP-GTK que geralmente tendem a rodar por mais tempo que scripts para a Web, o novo mecanismo deve fazer uma diferença considerável em relação a vazamentos de memória que insistem em acontecer.

# Instrumentação dinâmica DTrace

## Índice

- Introdução ao PHP e DTrace
- Usando PHP e DTrace
- Usando SystemTap com Sondas Estáticas DTrace
- Usando bpftrace com Sondas Estáticas DTrace do PHP

## Introdução ao PHP e DTrace

DTrace é um framework de instrumentação com alta disponibilidade e pequena sobrecarga, disponível em um número de plataformas incluindo Solaris, macOS, Oracle Linux e BSD. DTrace pode instrumentar comportamento do sistema operacional e execução de programa de usuário. Ele pode exibir valores de argumentos e ser usado para inferir estatísticas de desempenho. As sondas são monitoradas nos scripts criados pelo usuário escritos na linguagem própria do DTrace (D). Isto permite uma análise eficiente de pontos de dados.

Sondas PHP que não estão monitoradas ativamente por um script D do usuário não contêm código instrumentado, então não há degradação de desempenho durante a execução normal da aplicação. Sondas que estão sendo monitoradas incorrem em uma sobrecarga pequena o suficiente para permitir monitoramento pelo DTrace em sistemas ativos em fase de produção.

PHP incorpora sondas com "Instrumentação Estaticamente Definida no Nível de Usuário" (USDT em inglês) que são ativadas em tempo de execução. Por exemplo, quando um script D está monitorando a sonda de `function-entry` do PHP, a cada momento que uma função do PHP é chamada, esta sonda é disparada e o código de ação do script D associado é executado. Este código de ação poderia, por exemplo, imprimir argumentos de sonda como a localização do arquivo-fonte da função PHP. Ou a ação poderia agregar dados como o número de vezes que cada função é chamada.

Apenas as sondas USDT do PHP são descritas aqui. Refira-se à literatura externa do Dtrace, tanto geral quanto específica do sistema operacional, para entender como o DTrace pode ser usado para instrumentar funções arbitrárias, e como ele pode ser usado para instrumentar comportamento do sistema operacional. Note que nem todas as características do DTrace estão disponíveis em todas as implementações.

As sondas estáticas do Dtrace no PHP podem alternativamente ser utilizadas com a ferramenta SystemTap de algumas distribuições Linux.

## Usando PHP e DTrace

O PHP pode ser configurado com sondas estáticas do DTrace em plataformas que suportam a Instrumentação Dinâmica do DTrace.

### Configurando o PHP para Sondas Estáticas DTrace

Refira-se à documentação externa específica da plataforma para habilitar o suporte do DTrace no sistema operacional. Por exemplo, no Oracle Linux inicialize um kernel UEK3 e rode os seguintes comandos:

    # modprobe fasttrap
    # chmod 666 /dev/dtrace/helper

Ao invés de usar `chmod`, pode-se alternativamente usar uma regra de pacote ACL para limitar o acesso a um dispositivo para um usuário específico.

Construa o PHP com o parâmetro de configuração `--enable-dtrace`:

    # ./configure --enable-dtrace ...
    # make
    # make install

Isto faz com que as sondas estáticas estejam disponíveis no núcleo do PHP. Quaisquer extensões PHP que fornecem seus próprios sondas devem ser construídas separadamente como extensões compartilhadas.

Para habilitar as sondas, defina a variável de ambiente USE_ZEND_DTRACE=1 para os processos alvos do PHP.

### Sondas Estáticos DTrace no Núcleo do PHP

As sondas estáticos a seguir estão disponíveis no PHP
Nome da Sonda | Descrição da Sonda | Argumentos da Sonda
--- | --- | ---
`request-startup` | Dispara quando uma requisição inicia. | char *file, char *request_uri, char *request_method
`request-shutdown` | Dispara quando uma requisição termina. | char *file, char *request_uri, char *request_method
`compile-file-entry` | Dispara quando a compilação de um script inicia. | char *compile_file, char *compile_file_translated
`compile-file-return` | Dispara quando a compilação de um script termina. | char *compile_file, char *compile_file_translated
`execute-entry` | Dispara quando um array de opcode está para ser executado. Por exemplo, ele dispara em chamadas de função, de includes e em continuação de geradores. | char *request_file, int lineno
`execute-return` | Dispara depois da execução de um array de opcode. | char *request_file, int lineno
`function-entry` | Dispara quando o motor do PHP entra em uma chamada de função ou método. | char *function_name, char *request_file, int lineno, char *classname, char *scope
`function-return` | Dispara quando o motor do PHP retorna de uma chamada de função ou método. | char *function_name, char *request_file, int lineno, char *classname, char *scope
`exception-thrown` | Dispara quando uma exceção é disparada. | char *classname
`exception-caught` | Dispara quando uma exceção é capturada. | char *classname
`error` | Dispara quando um erro ocorre, independente do nível de error_reporting. | char *errormsg, char *request_file, int lineno

Extensões de PHP podem também conter sondas estáticas adicionais.

### Listando As Sondas Estáticas DTrace no PHP

Para listar as sondas disponíveis, inicie um processo PHP e então execute:

    # dtrace -l

A saída será similar a:

       ID   PROVIDER            MODULE                          FUNCTION NAME
       [ . . . ]
        4   php15271               php               dtrace_compile_file compile-file-entry
        5   php15271               php               dtrace_compile_file compile-file-return
        6   php15271               php                        zend_error error
        7   php15271               php  ZEND_CATCH_SPEC_CONST_CV_HANDLER exception-caught
        8   php15271               php     zend_throw_exception_internal exception-thrown
        9   php15271               php                 dtrace_execute_ex execute-entry
       10   php15271               php           dtrace_execute_internal execute-entry
       11   php15271               php                 dtrace_execute_ex execute-return
       12   php15271               php           dtrace_execute_internal execute-return
       13   php15271               php                 dtrace_execute_ex function-entry
       14   php15271               php                 dtrace_execute_ex function-return
       15   php15271               php              php_request_shutdown request-shutdown
       16   php15271               php               php_request_startup request-startup

Os valores da coluna Provider consistem de `php` mais o id do processo PHP sendo executado.

Se o servidor web Apache estiver rodando, o módulo poderia ser, por exemplo, libphp5.so, e haveria múltiplos blocos de listagens, um para cada processo Apache em execução.

A coluna Function refere-se aos nomes das funções da implementação interna do PHP, em C, onde cada fornecedor está localizado.

Se um processo PHP não estiver em execução, então nenhuma sonda PHP será mostrada.

### Exemplo de DTrace com PHP

Este exemplo mostra o básico da linguagem D de scripts DTrace.

Exemplo #1 Arquivo all_probes.d para instrumentar todas as Sondas Estáticas do PHP com DTrace

    #!/usr/sbin/dtrace -Zs

    #pragma D option quiet

    php*:::compile-file-entry
    {
        printf("PHP compile-file-entry\n");
        printf("  compile_file              %s\n", copyinstr(arg0));
        printf("  compile_file_translated   %s\n", copyinstr(arg1));
    }

    php*:::compile-file-return
    {
        printf("PHP compile-file-return\n");
        printf("  compile_file              %s\n", copyinstr(arg0));
        printf("  compile_file_translated   %s\n", copyinstr(arg1));
    }

    php*:::error
    {
        printf("PHP error\n");
        printf("  errormsg                  %s\n", copyinstr(arg0));
        printf("  request_file              %s\n", copyinstr(arg1));
        printf("  lineno                    %d\n", (int)arg2);
    }

    php*:::exception-caught
    {
        printf("PHP exception-caught\n");
        printf("  classname                 %s\n", copyinstr(arg0));
    }

    php*:::exception-thrown
    {
        printf("PHP exception-thrown\n");
        printf("  classname                 %s\n", copyinstr(arg0));
    }

    php*:::execute-entry
    {
        printf("PHP execute-entry\n");
        printf("  request_file              %s\n", copyinstr(arg0));
        printf("  lineno                    %d\n", (int)arg1);
    }

    php*:::execute-return
    {
        printf("PHP execute-return\n");
        printf("  request_file              %s\n", copyinstr(arg0));
        printf("  lineno                    %d\n", (int)arg1);
    }

    php*:::function-entry
    {
        printf("PHP function-entry\n");
        printf("  function_name             %s\n", copyinstr(arg0));
        printf("  request_file              %s\n", copyinstr(arg1));
        printf("  lineno                    %d\n", (int)arg2);
        printf("  classname                 %s\n", copyinstr(arg3));
        printf("  scope                     %s\n", copyinstr(arg4));
    }

    php*:::function-return
    {
        printf("PHP function-return\n");
        printf("  function_name             %s\n", copyinstr(arg0));
        printf("  request_file              %s\n", copyinstr(arg1));
        printf("  lineno                    %d\n", (int)arg2);
        printf("  classname                 %s\n", copyinstr(arg3));
        printf("  scope                     %s\n", copyinstr(arg4));
    }

    php*:::request-shutdown
    {
        printf("PHP request-shutdown\n");
        printf("  file                      %s\n", copyinstr(arg0));
        printf("  request_uri               %s\n", copyinstr(arg1));
        printf("  request_method            %s\n", copyinstr(arg2));
    }

    php*:::request-startup
    {
        printf("PHP request-startup\n");
        printf("  file                      %s\n", copyinstr(arg0));
        printf("  request_uri               %s\n", copyinstr(arg1));
        printf("  request_method            %s\n", copyinstr(arg2));
    }

Este script usa a opção `-Z` para a aplicação dtrace, permitindo que ela seja executada quando não há processo PHP em execução. Se esta opção fosse omitida, o script iria terminar imediatamente porque ele saberia que nenhuma das sondas a serem monitoradas existiriam.

O script instrumenta todos os pontos de sondas estáticas do núcleo do PHP durante toda a duração de um script PHP em execução. Execute o script D:

    # ./all_probes.d

Executa um script PHP ou aplicação. O script D de monitoramento terá como saída os argumentos de cada uma das sondas quando for disparado.

Quando o monitoramento estiver completo, o script D pode ser terminado com ``CTRL`+`C``.

Em máquinas com múltiplas CPUs, pode parecer que as sondas estão em ordem não sequencial. Isto depende de qual CPU está processando as sondas, e como as threads migram através dos CPUs. Mostrar os timestamps das sondas irá ajudar a reduzir a confusão, por exemplo:

    php*:::function-entry
    {
          printf("%lld: PHP function-entry ", walltimestamp);
          [ . . .]
    }

### Veja Também

- Instrumentação Dinâmica OCI8 e DTrace

## Usando SystemTap com Sondas Estáticas DTrace

Em algumas distribuições Linux, o utilitário SystemTap de instrumentação pode ser usado para instrumentar sondas estáticas do PHP. Isso está disponível no PHP 5.4.20 e PHP 5.5.

### Instalando PHP com SystemTap

Instale o pacote de desenvolvimento do SystemTap, SDT:

    # yum install systemtap-sdt-devel

Instale o PHP com as sondas DTrace habilitadas:

    # ./configure --enable-dtrace ...
    # make

### Listando as Sondas Estáticas com SystemTap

As sondas estáticas em PHP podem ser listados usando stap:

    # stap -l 'process.provider("php").mark("*")' -c 'sapi/cli/php -i'

A saída será:

    process("sapi/cli/php").provider("php").mark("compile__file__entry")
    process("sapi/cli/php").provider("php").mark("compile__file__return")
    process("sapi/cli/php").provider("php").mark("error")
    process("sapi/cli/php").provider("php").mark("exception__caught")
    process("sapi/cli/php").provider("php").mark("exception__thrown")
    process("sapi/cli/php").provider("php").mark("execute__entry")
    process("sapi/cli/php").provider("php").mark("execute__return")
    process("sapi/cli/php").provider("php").mark("function__entry")
    process("sapi/cli/php").provider("php").mark("function__return")
    process("sapi/cli/php").provider("php").mark("request__shutdown")
    process("sapi/cli/php").provider("php").mark("request__startup")

### Exemplo de SystemTap com PHP

Exemplo #1 all_probes.stp para instrumentação de todos as Sondas Estáticas do PHP com SystemTap

    probe process("sapi/cli/php").provider("php").mark("compile__file__entry") {
        printf("Probe compile__file__entry\n");
        printf("  compile_file %s\n", user_string($arg1));
        printf("  compile_file_translated %s\n", user_string($arg2));
    }
    probe process("sapi/cli/php").provider("php").mark("compile__file__return") {
        printf("Probe compile__file__return\n");
        printf("  compile_file %s\n", user_string($arg1));
        printf("  compile_file_translated %s\n", user_string($arg2));
    }
    probe process("sapi/cli/php").provider("php").mark("error") {
        printf("Probe error\n");
        printf("  errormsg %s\n", user_string($arg1));
        printf("  request_file %s\n", user_string($arg2));
        printf("  lineno %d\n", $arg3);
    }
    probe process("sapi/cli/php").provider("php").mark("exception__caught") {
        printf("Probe exception__caught\n");
        printf("  classname %s\n", user_string($arg1));
    }
    probe process("sapi/cli/php").provider("php").mark("exception__thrown") {
        printf("Probe exception__thrown\n");
        printf("  classname %s\n", user_string($arg1));
    }
    probe process("sapi/cli/php").provider("php").mark("execute__entry") {
        printf("Probe execute__entry\n");
        printf("  request_file %s\n", user_string($arg1));
        printf("  lineno %d\n", $arg2);
    }
    probe process("sapi/cli/php").provider("php").mark("execute__return") {
        printf("Probe execute__return\n");
        printf("  request_file %s\n", user_string($arg1));
        printf("  lineno %d\n", $arg2);
    }
    probe process("sapi/cli/php").provider("php").mark("function__entry") {
        printf("Probe function__entry\n");
        printf("  function_name %s\n", user_string($arg1));
        printf("  request_file %s\n", user_string($arg2));
        printf("  lineno %d\n", $arg3);
        printf("  classname %s\n", user_string($arg4));
        printf("  scope %s\n", user_string($arg5));
    }
    probe process("sapi/cli/php").provider("php").mark("function__return") {
        printf("Probe function__return: %s\n", user_string($arg1));
        printf(" function_name %s\n", user_string($arg1));
        printf("  request_file %s\n", user_string($arg2));
        printf("  lineno %d\n", $arg3);
        printf("  classname %s\n", user_string($arg4));
        printf("  scope %s\n", user_string($arg5));
    }
    probe process("sapi/cli/php").provider("php").mark("request__shutdown") {
        printf("Probe request__shutdown\n");
        printf("  file %s\n", user_string($arg1));
        printf("  request_uri %s\n", user_string($arg2));
        printf("  request_method %s\n", user_string($arg3));
    }
    probe process("sapi/cli/php").provider("php").mark("request__startup") {
        printf("Probe request__startup\n");
        printf("  file %s\n", user_string($arg1));
        printf("  request_uri %s\n", user_string($arg2));
        printf("  request_method %s\n", user_string($arg3));
    }

O script acima irá instrumentar todos os pontos de sondas estáticas do núcleo do PHP durante toda a duração de um script PHP em execução:

    # stap -c 'sapi/cli/php test.php' all_probes.stp

## Usando bpftrace com Sondas Estáticas DTrace do PHP

Em distribuições Linux com um kernel que suporta eBPF, o utilitário bpftrace pode se conectar diretamente às sondas USDT DTrace do PHP, sem precisar do SystemTap.

### Instalando o bpftrace

Instale o bpftrace usando o gerenciador de pacotes da distribuição. Por exemplo, no Oracle Linux, RHEL ou Fedora:

    # dnf install bpftrace

Ou, no Debian ou Ubuntu:

    # apt install bpftrace

Os exemplos abaixo assumem que o binário PHP alvo está instalado em /usr/bin/php.

As mesmas sondas USDT também são expostas por outras SAPIs construídas a partir da mesma árvore de fontes, então o alvo da sonda pode ser, ao invés disso, o módulo do Apache (libphp.so) ou o binário do FastCGI Process Manager (php-fpm); substitua o caminho apropriado ou conecte-se pelo PID com `-p` conforme necessário.

Certifique-se de que o binário alvo foi construído com o DTrace e que a variável de ambiente está configurado corretamente. Veja Configurando o PHP para Sondas Estáticas DTrace para detalhes.

As sondas estáticas do PHP podem ser listadas usando bpftrace:

    # bpftrace -l 'usdt:/usr/bin/php:php:*'

A saída é:

    usdt:/usr/bin/php:php:compile__file__entry
    usdt:/usr/bin/php:php:compile__file__return
    usdt:/usr/bin/php:php:error
    usdt:/usr/bin/php:php:exception__caught
    usdt:/usr/bin/php:php:exception__thrown
    usdt:/usr/bin/php:php:execute__entry
    usdt:/usr/bin/php:php:execute__return
    usdt:/usr/bin/php:php:function__entry
    usdt:/usr/bin/php:php:function__return
    usdt:/usr/bin/php:php:request__shutdown
    usdt:/usr/bin/php:php:request__startup

Exemplo #1 all_probes.bt para instrumentação de todas as Sondas Estáticas do PHP com bpftrace

    #!/usr/bin/env bpftrace

    usdt:/usr/bin/php:php:compile__file__entry
    {
        printf("Probe compile__file__entry\n");
        printf("  compile_file %s\n", str(arg0));
        printf("  compile_file_translated %s\n", str(arg1));
    }
    usdt:/usr/bin/php:php:compile__file__return
    {
        printf("Probe compile__file__return\n");
        printf("  compile_file %s\n", str(arg0));
        printf("  compile_file_translated %s\n", str(arg1));
    }
    usdt:/usr/bin/php:php:error
    {
        printf("Probe error\n");
        printf("  errormsg %s\n", str(arg0));
        printf("  request_file %s\n", str(arg1));
        printf("  lineno %d\n", (int32)arg2);
    }
    usdt:/usr/bin/php:php:exception__caught
    {
        printf("Probe exception__caught\n");
        printf("  classname %s\n", str(arg0));
    }
    usdt:/usr/bin/php:php:exception__thrown
    {
        printf("Probe exception__thrown\n");
        printf("  classname %s\n", str(arg0));
    }
    usdt:/usr/bin/php:php:execute__entry
    {
        printf("Probe execute__entry\n");
        printf("  request_file %s\n", str(arg0));
        printf("  lineno %d\n", (int32)arg1);
    }
    usdt:/usr/bin/php:php:execute__return
    {
        printf("Probe execute__return\n");
        printf("  request_file %s\n", str(arg0));
        printf("  lineno %d\n", (int32)arg1);
    }
    usdt:/usr/bin/php:php:function__entry
    {
        printf("Probe function__entry\n");
        printf("  function_name %s\n", str(arg0));
        printf("  request_file %s\n", str(arg1));
        printf("  lineno %d\n", (int32)arg2);
        printf("  classname %s\n", str(arg3));
        printf("  scope %s\n", str(arg4));
    }
    usdt:/usr/bin/php:php:function__return
    {
        printf("Probe function__return\n");
        printf("  function_name %s\n", str(arg0));
        printf("  request_file %s\n", str(arg1));
        printf("  lineno %d\n", (int32)arg2);
        printf("  classname %s\n", str(arg3));
        printf("  scope %s\n", str(arg4));
    }
    usdt:/usr/bin/php:php:request__shutdown
    {
        printf("Probe request__shutdown\n");
        printf("  file %s\n", str(arg0));
        printf("  request_uri %s\n", str(arg1));
        printf("  request_method %s\n", str(arg2));
    }
    usdt:/usr/bin/php:php:request__startup
    {
        printf("Probe request__startup\n");
        printf("  file %s\n", str(arg0));
        printf("  request_uri %s\n", str(arg1));
        printf("  request_method %s\n", str(arg2));
    }

O script acima irá instrumentar todos os pontos de sondas estáticas do núcleo do PHP durante toda a duração de um script PHP em execução. O bpftrace requer privilégios de root:

    # USE_ZEND_DTRACE=1 bpftrace -c '/usr/bin/php test.php' all_probes.bt

Para instrumentar um processo PHP já em execução (por exemplo, um worker do php-fpm ou um processo Apache carregando libphp.so), conecte-se pelo PID:

    # bpftrace -p $PID all_probes.bt

O caminho alvo `usdt:` no script deve corresponder ao binário do processo em execução; ajuste `usdt:/usr/bin/php` para o binário do php-fpm ou para libphp.so conforme apropriado.

- Autenticação HTTP com PHP
- Cookies
- Sessões
- Gerenciamento de envio de arquivos
  - Envio de arquivos com o método POST
  - Explicando mensagens de erro
  - Problemas Comuns
  - Enviando múltiplos arquivos
  - Suporte ao método PUT
  - Veja Também
- Usando arquivos remotos
- Tratamento de Conexões
- Conexões Persistentes com o Banco de Dados
- Uso da linha de Comando — Usando PHP a partir da linha de comando
  - Diferenças em relação a outros SAPIs
  - Opções — Opções de linha de comando
  - Uso — Executando arquivos PHP
  - Fluxos de E/S — Fluxos de entrada/saída
  - Shell interativo
  - Servidor web embutido
  - Configurações INI
- Coletor de Lixo
  - Básico sobre Contagem de Referência
  - Ciclos de Coleta
  - Considerações de Desempenho
- Instrumentação dinâmica DTrace
  - Introdução ao PHP e DTrace
  - Usando PHP e DTrace
  - Usando SystemTap com Sondas Estáticas DTrace
  - Usando bpftrace com Sondas Estáticas DTrace do PHP

# Referência das Funções

Dica

Veja também Categorização/Lista das Extensões.

# Afetando o comportamento do PHP

# Cache de Usuário APC

# Introdução

APCu é um armazenamento em memória de chave-valor para o PHP. Chaves são do tipo string e valores podem ser quaisquer variáveis PHP. APCu suporta somente cache de variáveis no nível do usuário.

O cache APCu é feito por processo no Windows, portando ao usar um SAPI baseado em processo (e não baseado em thread), ele não será compartilhado entre os diferentes processos.

APCu é o APC com o cache opcode removido.

O primeiro código APCu tinha a versão 4.0.0 e foi derivado do ramo master do APC naquele momento. O suporte ao PHP está disponível a partir do APCu 5.0.0. O suporte ao PHP 8 está disponível a partir do APCu 5.1.19.

# Instalação/Configuração

## Índice

- Instalação
- Configurações em Execução

## Instalação

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/apcu.

Dica

O PHP 7 tem um módulo separado (» apcu-bc) para compatibilidade com versões anteriores do APC.

Em modo de compatibilidade, o APCu registra as funções APC aplicáveis com protótipos compatíveis com versões anteriores.

Onde uma função APC aceitar o parâmetro `cache_type`, ele é simplemente ignorado pela versão de compatibilidade, e omitida pelo protótipo para a versão APCu.

Aviso

A partir do PHP 8.0.0, apcu-bc não é mais suportado.

> Nota: No Windows, o APCu precisa de um diretório temporário existente e com permissão de escrita pelo servidor web. Ele verifica as variáveis de ambiente TMP, TEMP e USERPROFILE, nesta ordem, e finalmente tenta o diretório do WINDOWS se nenhum dos outros estiver definido.

> Nota: Para detalhes de implementação altamente técnicos e mais aprofundados, consulte o » arquivo de NOTAS TÉCNICAS fornecido pelo desenvolvedor .

O código-fonte do APCu pode ser encontrado » aqui.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Embora as configurações padrão do APCu são adequadas para muitas instalações, usuários devem considerar ajustes para os parâmetros abaixo.

Existe uma decisão a ser tomada ao configurar o APCu: quanta memória será alocada ao APCu. A diretiva ini que controla isso é `apc.shm_size`, leia cuidadosamente as seções sobre este assunto abaixo.

Uma vez que o servidor está em execução, o script `apc.php` que é incluído com a extensão deve ser copiado para algum lugar dentro do diretório raiz dos documentos e visualizado com um navegador pois ele fornece uma análise detalhada do funcionamento interno do APCu. Se a GD estiver habilitada no PHP, ele irá mostrar inclusive alguns gráficos interessantes.

Se o APCu estiver funcionando, o número `Cache full count` (na esquerda) mostrará o número de vezes que o cache atingiu a capacidade máxima e teve que despejar entradas para liberar memória. Durante o despejo, se `apc.ttl` foi especificado, o APCu inicialmente tentará remover entradas expiradas, isto é, entradas cujo TTL tenha expirado ou entradas que não tenham o TTL definido e não tenham sido acessadas nos últimos `apc.ttl` segundos. Se `apc.ttl` não foi definido, ou se a remoção de entradas expiradas não liberou espaço suficiente, o APCu limpará o cache inteiro.

O número de despejos deve ser mínimo em um cache bem configurado. Se o cache está constantemente atingindo o limite, e por isso sendo liberado à força, a agitação resultante terá efeitos depreciativos no desempenho do script. A maneira mais fácil de minimizar este número é alocar mais memória para o APCu.

Quando o APCu é compilado com suporte a mmap (Mapeamento de Memória), ele usará somente um segmento de memória, ao contrário de quando for compilado com suporte a SHM (Memória Compartilhada SysV) que usa múltiplos segmentos. MMAP não tem um limite máximo como o SHM em `/proc/sys/kernel/shmmax`. Em geral o suporte MMAP é recomendado porque ele irá recuparar a memória mais rapidamente quando o servidor web for reiniciado e, sumazirando, reduzirá o impacto na alocação de memória na inicialização.

Opções de configuração APCu
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
apc.enabled | 1 | `INI_SYSTEM` |
apc.shm_segments | 1 | `INI_SYSTEM` |
apc.shm_size | "32M" | `INI_SYSTEM` |
apc.entries_hint | 512 * apc.shm_size | `INI_SYSTEM` | Antes do APCu 5.1.25, o padrão era 4096
apc.ttl | 0 | `INI_SYSTEM` |
apc.gc_ttl | 3600 | `INI_SYSTEM` |
apc.mmap_file_mask | NULL | `INI_SYSTEM` |
apc.slam_defense | 0 | `INI_SYSTEM` |
apc.enable_cli | 0 | `INI_SYSTEM` |
apc.use_request_time | 0 | `INI_ALL` | Antes do APCu 5.1.19, o padrão era `1`.
apc.serializer | "php" | `INI_SYSTEM` | Antes do APCu 5.1.15, o padrão era `"default"`.
apc.coredump_unmap | 0 | `INI_SYSTEM` |
apc.preload_path | NULL | `INI_SYSTEM` |

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`apc.enabled` bool
  `apc.enabled` pode ser definido para 0 para desabilitar o APC. Isto é útil principalmente quando o APC é compilado estaticamente no PHP, já que não há outra maneira de desabilitá-lo (quando compilado como um DSO, a linha `extension` no `php.ini` pode ser simplesmente comentada).
`apc.shm_segments` int
  O número de segmentos de memória compartilhada a alocar para o cache do compilador. Se o APC estiver com pouca memória compartilhada mas `apc.shm_size` estiver definido com um valor tão alto quanto o sistema permite, aumentar este valor pode evitar que o APC tenha a memória exaurida.
`apc.shm_size` string
  O tamanho de cada segmento de memória compartilhada, informado como uma notação reduzida como descrito neste FAQ. Por padrão, alguns sistemas (incluindo a maior parte das variantes BSD) têm limites muito baixos no tamanho de um segmento de memória compartilhada.
`apc.entries_hint` int
  Uma "pista" sobre o número de variáveis distintas que podem ser armazenadas. Defina para zero ou omita se não tiver essa informação.
`apc.ttl` int
  Considera que entradas de cache sem um TTL explícito estão expiradas se não foram acessadas nos segundos definidos por esta diretiva. Efetivamente, isto permite que tais entradas sejam removida oportunamente durante uma inserção de cache ou antes de uma eliminação completa. Observe que devido à remoção ser oportunap, as entradas ainda podem ser lidas mesmo se forem mais antigas que `apc.ttl` segundos. Esta configuração não tem efeito em entradas de cache que tenham um TTL explícito especificado.
`apc.gc_ttl` int
  O número de segundos que uma entrada de cache pode permanecer na lista de coleta de lixo após ser removida ou inicializada. Uma entrada é elegível a remoção se sua contagem de referência for zero, ou se exceder este limite de tempo. Se definido para `0`, a limpeza baseada em tempo é desativada, e as entradas só serão removidas quando suas contagens de referência caírem para zero.
`apc.mmap_file_mask` string
  Se compilado com suporte MMAP usando `--enable-mmap` esta é a máscara de arquivo em estilo mktemp a ser passada ao módulo mmap para determinar se a região de memória mapeada pelo MMAP será apoiada por arquivo ou apoiada por memória comparilhada. Para MMAP diretamente apoiada por arquivo, defina para algo como `/tmp/apc.XXXXXX` (exatamente 6 `X`). Oara usar shm_open/mmap em estilo POSIX, insira um `.shm` em algum lugar da máscara (por exemplo, `/apc.shm.XXXXXX`). Pode-se também defini-la para `/dev/zero` para usar a interface `/dev/zero` do kernel para memória mapeada anonimamente. Deixar este valor indefinido força um mapeamento anônimo.
`apc.slam_defense` bool
  Em um servidor muito ocupado, toda vez que ele for reiniciado ou quando arquivos forem modificados, pode-se criar uma condição de corrida onde muitos processos tentam inserir o mesmo arquivo no cache ao mesmo tempo. Definir `apc.slam_defense` para `1` pode ajudar a evitar que múltiplos processos tentem fazer cache do mesmo arquivo ao mesmo tempo, através da introdução de um mecanismo probabilístico. Se a mesma chave sofrer tentativa de cache dentro de um intervalo curto de tempo por diferentes processos, ele pula a tarefa de cache do processo atual para mitigar potenciais conflitos de cache.
`apc.enable_cli` int
  Esta diretiva serve principalmente para teste e depuração. Habilita APC para a versão CLI do PHP. Em circunstâncias normais, não é ideal criar, popular e destruir o cache APC a cada requisição CLI, mas para vários cenários de teste é útil para ser capaz de habilitar o APC para a versão CLI do PHP facilmente.
`apc.serializer` string
  Usada para configurar o APC para usar um serializador de terceiros.
`apc.coredump_unmap` bool
  Habilita o gerenciamento APC de sinais, tal como SIGSEGV, que grava arquivos de núcleo quando sinalizado. Quandos esses sinais são recebidos, o APC tentará desmapear o segmento de memória compartilhada para excluí-lo do arquivo de núcleo. Esta configuração pode melhorar a estabilidade do sistema quando sinais fatais são recebidos e um grande segmento de memória compartilhada APC estiver configurado.
  Aviso

  Este recurso é potencialmente perigoso. Desmapear o segmento de memória compartilhada em um gerenciador de sinal fatal pode causar comportamento indefinido de um erro fatal ocorrer.

  > Nota: Embora alguns kernels possam fornecer um recurso para ignorar vários tipos de memória compartilhada ao gerar um arquivo de despejo de núcleo, estas implementações podem também ignorar segmentos de memória compartilhada importantes tal como o Scoreboard do Apache.

`apc.preload_path` string
  Opcionalmente, define um caminho para o diretório onde o APC irá carregar dados de cache na inicialização.
`apc.use_request_time` bool
  Usa o horário de início da requisição SAPI para o TTL.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`APC_ITER_ALL` (int)
`APC_ITER_ATIME` (int)
`APC_ITER_CTIME` (int)
`APC_ITER_DEVICE` (int)
`APC_ITER_DTIME` (int)
`APC_ITER_FILENAME` (int)
`APC_ITER_INODE` (int)
`APC_ITER_KEY` (int)
`APC_ITER_MD5` (int)
`APC_ITER_MEM_SIZE` (int)
`APC_ITER_MTIME` (int)
`APC_ITER_NONE` (int)
`APC_ITER_NUM_HITS` (int)
`APC_ITER_REFCOUNT` (int)
`APC_ITER_TTL` (int)
`APC_ITER_TYPE` (int)
`APC_ITER_VALUE` (int)
`APC_LIST_ACTIVE` (int)
`APC_LIST_DELETED` (int)

# APCu Funções

# apcu_add

(PECL apcu >= 4.0.0)

apcu_add — Faz cache de uma nova variável no armazenamento de dados

### Descrição

function apcu_add(string `$key`, mixed `$var`, int `$ttl` = 0): bool
function apcu_add(array `$values`, mixed `$unused` = NULL, int `$ttl` = 0): array

Faz cache de uma variável no armazenamento de dados, somente se já não estiver armazenada.

> Nota: Deferentemente de outros mecanismos no PHP, variáveis armazenadas usando apcu_add() irão persistir entre requisições (até que o valor seja removido do cache).

### Parâmetros

`key`
  Armazena a variável usando este nome. Uma chave definida por `key` deve ser única no cache, portanto tentar usar apcu_add() para armazenar dados com uma chave que já existe não substutuirá os dados existentes, e ao invés disso retornará `false`. Esta é a única diferença entre apcu_add() e apcu_store().
`var`
  A variável a ser armazenada
`ttl`
  Tempo de vida (Time To Live); armazena `var` no cache por `ttl` segundos. Depois que `ttl` segundos tiverem decorrido, a variável armazenada será excluída do cache (na próxima requisição). Se o parâmetro `ttl` não for fornecido (ou se `ttl` for `0`), o valor persistirá até que seja removido do cache manualmente, ou se não existir mais no cache (em uma limpeza, reinício, etc.).
`values`
  Nomes nas chaves, variáveis no valor.

### Valor Retornado

Retorna TRUE se algo foi efetivamente adicionado ao chace, FALSE caso contrário. A segunda sintaxe retorna um array com chaves de erros.

### Exemplos

Exemplo #1 Um exemplo de apcu_add()

    <?php
    $bar = 'BAR';
    apcu_add('foo', $bar);
    var_dump(apcu_fetch('foo'));
    echo "\n";
    $bar = 'NEVER GETS SET';
    apcu_add('foo', $bar);
    var_dump(apcu_fetch('foo'));
    echo "\n";
    ?>

O exemplo acima produzirá:

    string(3) "BAR"
    string(3) "BAR"

### Veja Também

- apcu_store() - Armazena uma variável em cache
- apcu_fetch() - Busca uma variável armazenada no cache
- apcu_delete() - Remove uma variável armazenada do cache

# apcu_cache_info

(PECL apcu >= 4.0.0)

apcu_cache_info — Recupera informação em cache a partir do armazenamento de dados do APCu

### Descrição

function apcu_cache_info(bool `$limited` = `false`): array|false

Recupera informação em cache e meta-dados a partir do armazenamento de dados do APCu.

### Parâmetros

`limited`
  Se `limited` for `true`, o valor de retorno excluirá a lista individual de entradas de cache. Isto é útil ao tentar otimizar chamadas para obtenção de estatísticas.

### Valor Retornado

Array de dados em cache (e meta-dados) ou `false` em caso de falha

> Nota: apcu_cache_info() irá emitir um alerta se não conseguir recuperar dados em cache do APCu. Isto tipicamente ocorre quando o APCu não está habilitado.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL apcu 3.0.11 | O parâmetro `limited` foi introduzido.
PECL apcu 3.0.16 | A opção "`filehits`" para parâmetro `cache_type` foi introduzida.

### Exemplos

Exemplo #1 Um exemplo de apcu_cache_info()

    <?php
    print_r(apcu_cache_info());
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [num_slots] => 2000
        [ttl] => 0
        [num_hits] => 9
        [num_misses] => 3
        [start_time] => 1123958803
        [cache_list] => Array
            (
                [0] => Array
                    (
                        [filename] => /path/to/apcu_test.php
                        [device] => 29954
                        [inode] => 1130511
                        [type] => file
                        [num_hits] => 1
                        [mtime] => 1123960686
                        [creation_time] => 1123960696
                        [deletion_time] => 0
                        [access_time] => 1123962864
                        [ref_count] => 1
                        [mem_size] => 677
                    )
                [1] => Array (...itera para cada arquivo em cache)
    )

### Veja Também

- Diretivas de configuração APCu
- APCUIterator::getTotalSize() - Obtém o tamanho total do cache
- APCUIterator::getTotalHits() - Obtém o total de entradas de cache
- APCUIterator::getTotalCount() - Obtém a contagem total

# apcu_cas

(PECL apcu >= 4.0.0)

apcu_cas — Atualiza um valor antigo com um novo

### Descrição

function apcu_cas(string `$key`, int `$old`, int `$new`): bool

apcu_cas() atualiza um valor inteiro já existente se o parâmetro `old` corresponder ao valor armazenado atualmente com o valor do parâmetro `new`.

### Parâmetros

`key`
  A chave do valor sendo atualizado.
`old`
  O valor antigo (o valor atualmente armazenado).
`new`
  O novo valor com o qual a chave será atualizada.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de apcu_cas()

    <?php
    apcu_store('foobar', 2);
    echo '$foobar = 2', PHP_EOL;
    echo '$foobar == 1 ? 2 : 1 = ', (apcu_cas('foobar', 1, 2) ? 'ok' : 'falha'), PHP_EOL;
    echo '$foobar == 2 ? 1 : 2 = ', (apcu_cas('foobar', 2, 1) ? 'ok' : 'falha'), PHP_EOL;

    echo '$foobar = ', apcu_fetch('foobar'), PHP_EOL;

    echo '$f__bar == 1 ? 2 : 1 = ', (apcu_cas('f__bar', 1, 2) ? 'ok' : 'falha'), PHP_EOL;

    apcu_store('perfection', 'xyz');
    echo '$perfection == 2 ? 1 : 2 = ', (apcu_cas('perfection', 2, 1) ? 'ok' : 'falha épica'), PHP_EOL;

    echo '$foobar = ', apcu_fetch('foobar'), PHP_EOL;
    ?>

O exemplo acima produzirá algo semelhante a:

    $foobar = 2
    $foobar == 1 ? 2 : 1 = falha
    $foobar == 2 ? 1 : 2 = ok
    $foobar = 1
    $f__bar == 1 ? 2 : 1 = falha
    $perfection == 2 ? 1 : 2 = falha épica
    $foobar = 1

### Veja Também

- apcu_dec() - Decrementa um número armazenado
- apcu_store() - Armazena uma variável em cache

# apcu_clear_cache

(PECL apcu >= 4.0.0)

apcu_clear_cache — Limpa o cache APCu

### Descrição

function apcu_clear_cache(): bool

Limpa o cache.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna sempre `true`

### Veja Também

- apcu_cache_info() - Recupera informação em cache a partir do armazenamento de dados do APCu

# apcu_dec

(PECL apcu >= 4.0.0)

apcu_dec — Decrementa um número armazenado

### Descrição

function apcu_dec(
string `$key`,
int `$step` = 1,
bool `&$success` = ?,
int `$ttl` = 0
): int|false

Decrementa um valor inteiro armazenado.

### Parâmetros

`key`
  A chave do valor sendo decrementado.
`step`
  A quantidade, ou valor a decrementar.
`success`
  Opcionalmente, o valor booleano de sucesso ou falha é passado para esta variável de referência.
`ttl`
  TTL a ser usado se a operação inserir um novo valor (ao invés de decrementar um existente).

### Valor Retornado

Retorna o valor atual do valor da chave definida em `key` em caso de sucesso, ou `false` em caso de falha

### Exemplos

Exemplo #1 Exemplo de apcu_dec()

    <?php
    echo "Fazendo algo que funciona", PHP_EOL;

    apcu_store('numeral', 42);

    echo apcu_fetch('numeral'), PHP_EOL;

    echo apcu_dec('numeral'), PHP_EOL;
    echo apcu_dec('numeral', 10), PHP_EOL;
    echo apcu_dec('numeral', 10, $success), PHP_EOL;

    var_dump($success);

    echo "Agora, algo que falha", PHP_EOL, PHP_EOL;

    apcu_store('uma_string', 'foo');

    $ret = apcu_dec('uma_string', 1, $fail);

    var_dump($ret);
    var_dump($fail);
    ?>

O exemplo acima produzirá algo semelhante a:

    Fazendo algo que funciona
    42
    41
    31
    21
    bool(true)
    Agora, algo que falha

    bool(false)
    bool(false)

### Veja Também

- apcu_inc() - Incrementa um número armazenado

# apcu_delete

(PECL apcu >= 4.0.0)

apcu_delete — Remove uma variável armazenada do cache

### Descrição

function apcu_delete(mixed `$key`): mixed

Remove uma variável armazenada do cache.

### Parâmetros

`key`
  O parâmetro `key` é uma chave usada para armazenar o valor como uma string para uma chave única, ou como um array de strings para várias chaves, ou como um objeto (object) da classe APCUIterator.

### Valor Retornado

Se `key` for um array, um array indexado das chaves é retornado. Caso contrário `true` é retornado em caso de sucesso, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Um exemplo de apcu_delete()

    <?php
    $bar = 'BAR';
    apcu_store('foo', $bar);
    apcu_delete('foo');
    // obviamente inútil nesta forma

    // Alternativamente remove múltiplas chaves.
    apcu_delete(['foo', 'bar', 'baz']);

    // Ou usa um iterador com uma expressão regular.
    apcu_delete(new APCUIterator('#^myprefix_#'));
    ?>

### Veja Também

- apcu_store() - Armazena uma variável em cache
- apcu_fetch() - Busca uma variável armazenada no cache
- apcu_clear_cache() - Limpa o cache APCu
- APCUIterator

# apcu_enabled

(PECL apcu >= 4.0.3)

apcu_enabled — Informa se o APCu está disponível no ambiente atual

### Descrição

function apcu_enabled(): bool

Informa se o APCu está utilizável no ambiente atual.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` quando o APCu está utilizável no ambiente atual, `false` caso contrário.

# apcu_entry

(PECL apcu >= 5.1.0)

apcu_entry — Busca ou gera atomicamente uma entrada de cache

### Descrição

function apcu_entry(string `$key`, callable `$callback`, int `$ttl` = 0): mixed

Tenta atomicamente encontrar `key` no cache, se não puder ser encontrado, `callback` é chamado, passando `key` como único argumento. O valor de retorno da chamada é então armazenado em cache com o `ttl` especificado opcionalmente e retornado.

> Nota: Quando o controle entra em apcu_entry() a trava para o cache é adquirida exclusivamente, ela é liberada quando o controle sai de apcu_entry(): Na verdade, isso transforma o corpo do `callback` em uma seção crítica, impedindo que dois processos executem os mesmos caminhos de código simultaneamente. Além disso, proíbe a execução simultânea de quaisquer outras funções da APCu, pois irão adquirir a mesma trava.

Aviso

A única função APCu que pode ser chamada com segurança por `callback` é apcu_entry().

### Parâmetros

`key`
  Identidade da entrada de cache
`callback`
  Uma função chamável que aceite `key` como o único argumento e retorne o valor para o cache.
`ttl`
  Tempo de Vida (Time To Live); armazena o valor de retorno de `callback` no cache por `ttl` segundos. Depois desses `ttl` segundos, a entrada armazenada será excluída do cache (na próxima requisição). Se nenhum parâmetro `ttl` for informado (ou se `ttl` for `0`), o valor persistirá até que seja removido do cache manualmente, ou caso deixe de existir no cache (limpeza, reinício, etc.).

### Valor Retornado

Retorna o valor armazenado em cache

### Exemplos

Exemplo #1 Um exemplo de apcu_entry()

    <?php
    $config = apcu_entry("config", function($key) {
     return [
       "fruta" => apcu_entry("config.fruta", function($key){
         return [
           "abacaxis",
           "bananas"
         ];
       }),
       "pessoas" => apcu_entry("config.pessoas", function($key){
         return [
          "Marcelo",
          "Pedro",
          "Maria"
         ];
       })
     ];
    });

    var_dump($config);
    ?>

O exemplo acima produzirá:

    array(2) {
      ["fruta"]=>
      array(2) {
        [0]=>
        string(6) "abacaxis"
        [1]=>
        string(5) "bananas"
      }
      ["pessoas"]=>
      array(3) {
        [0]=>
        string(3) "Marcelo"
        [1]=>
        string(3) "Pedro"
        [2]=>
        string(4) "Maria"
      }
    }

### Veja Também

- apcu_store() - Armazena uma variável em cache
- apcu_fetch() - Busca uma variável armazenada no cache
- apcu_delete() - Remove uma variável armazenada do cache

# apcu_exists

(PECL apcu >= 4.0.0)

apcu_exists — Verifica se uma entrada existe

### Descrição

function apcu_exists(string|array `$keys`): bool|array

Verifica se uma ou mais entradas do APCu existem.

### Parâmetros

`keys`
  Uma string ou um array de strings que contenha chaves.

### Valor Retornado

Retorna `true` se a chave existir, caso contrário `false`; ou se um array foi informado em `keys`, um array que contém todas as chaves existentes é retornado, ou um array vazio se nenhuma existir.

### Exemplos

Exemplo #1 Exemplo de apcu_exists()

    <?php
    $fruit  = 'banana';
    $veggie = 'cenoura';

    apcu_store('foo', $fruit);
    apcu_store('bar', $veggie);

    if (apcu_exists('foo')) {
        echo "Foo existe: ";
        echo apcu_fetch('foo');
    } else {
        echo "Foo não existe";
    }

    echo PHP_EOL;
    if (apcu_exists('baz')) {
        echo "Baz existe.";
    } else {
        echo "Baz não existe";
    }

    echo PHP_EOL;

    $ret = apcu_exists(array('foo', 'naoexiste', 'bar'));
    var_dump($ret);

    ?>

O exemplo acima produzirá algo semelhante a:

    Foo existe: banana
    Baz não existe
    array(2) {
      ["foo"]=>
      bool(true)
      ["bar"]=>
      bool(true)
    }

### Veja Também

- apcu_cache_info() - Recupera informação em cache a partir do armazenamento de dados do APCu
- apcu_fetch() - Busca uma variável armazenada no cache

# apcu_fetch

(PECL apcu >= 4.0.0)

apcu_fetch — Busca uma variável armazenada no cache

### Descrição

function apcu_fetch(mixed `$key`, bool `&$success` = ?): mixed

Busca uma entrada do cache.

### Parâmetros

`key`
  O parâmetro `key` contém a chave usada para armazenar o valor (com apcu_store()). Se um array for informado, cada elemento é buscado e retornado.
`success`
  Definido para `true` em caso de sucesso e `false` em caso de falha.

### Valor Retornado

A variável armazenada ou array de variáveis em caso de sucesso; `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL apcu 3.0.17 | O parâmetro `success` foi adicionado.

### Exemplos

Exemplo #1 Um exemplo de apcu_fetch()

    <?php
    $bar = 'BAR';
    apcu_store('foo', $bar);
    var_dump(apcu_fetch('foo'));
    ?>

O exemplo acima produzirá:

    string(3) "BAR"

### Veja Também

- apcu_store() - Armazena uma variável em cache
- apcu_delete() - Remove uma variável armazenada do cache
- APCUIterator

# apcu_inc

(PECL apcu >= 4.0.0)

apcu_inc — Incrementa um número armazenado

### Descrição

function apcu_inc(
string `$key`,
int `$step` = 1,
bool `&$success` = ?,
int `$ttl` = 0
): int|false

Incrementa um número armazenado.

### Parâmetros

`key`
  A chave do valor sendo incrementado.
`step`
  A quantidade, ou o valor a incrementar.
`success`
  Opcionalmente o valor booleano de sucesso ou falha é armazenado nesta variável passada por referência.
`ttl`
  TTL a ser usado se a operação inserir um novo valor (ao invés de incrementar um existente).

### Valor Retornado

Retorna o valor atual do valor da chave definida em `key` em caso de sucesso, ou `false` em caso de falha

### Exemplos

Exemplo #1 Exemplo de apcu_inc()

    <?php
    echo "Fazendo algo que funciona", PHP_EOL;

    apcu_store('numeral', 42);

    echo apcu_fetch('numeral'), PHP_EOL;

    echo apcu_inc('numeral'), PHP_EOL;
    echo apcu_inc('numeral', 10), PHP_EOL;
    echo apcu_inc('numeral', 10, $success), PHP_EOL;

    var_dump($success);

    echo "Agora, algo que falha", PHP_EOL, PHP_EOL;

    apcu_store('uma_string', 'foo');

    $ret = apcu_inc('uma_string', 1, $fail);

    var_dump($ret);
    var_dump($fail);
    ?>

O exemplo acima produzirá algo semelhante a:

    Fazendo algo que funciona
    42
    43
    53
    63
    bool(true)
    Agora, algo que falha

    bool(false)
    bool(false)

### Veja Também

- apcu_dec() - Decrementa um número armazenado

# apcu_key_info

(PECL apcu >= 4.0.2)

apcu_key_info — Obtém informação detalhada sobre uma chave em cache

### Descrição

function apcu_key_info(string `$key`): ?array

Obtém informação detalhada sobre a chave em cache

### Parâmetros

`key`
  Chave para a qual deseja-se obter a informação.

### Valor Retornado

Um array contendo informação detalhada sobre a chave em cache, ou `null` se a chave não existir.

### Exemplos

Exemplo #1 Um exemplo de apcu_key_info()

    <?php
    apcu_add('a','b');
    var_dump(apcu_key_info('a'));
    ?>

O exemplo acima produzirá:

    array(7) {
      ["hits"]=>
      int(0)
      ["access_time"]=>
      int(1606701783)
      ["mtime"]=>
      int(1606701783)
      ["creation_time"]=>
      int(1606701783)
      ["deletion_time"]=>
      int(0)
      ["ttl"]=>
      int(0)
      ["refs"]=>
      int(0)
    }

### Veja Também

- apcu_store() - Armazena uma variável em cache
- apcu_fetch() - Busca uma variável armazenada no cache
- apcu_delete() - Remove uma variável armazenada do cache

# apcu_sma_info

(PECL apcu >= 4.0.0)

apcu_sma_info — Obtém informação de Alocação de Memória Compartilhada (SMA) do APCu

### Descrição

function apcu_sma_info(bool `$limited` = `false`): array|false

Obtém informação de Alocação de Memória Compartilhada (SMA) do APCu.

### Parâmetros

`limited`
  Quando definido para `false` (o padrão), apcu_sma_info() retornará uma informação detalhada sobre cada segmento.

### Valor Retornado

Array de dados de Alocação de Memória Compartilhada; `false` em caso de falha.

### Exemplos

Exemplo #1 Um exemplo de apcu_sma_info()

    <?php
    print_r(apcu_sma_info());
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [num_seg] => 1
        [seg_size] => 31457280
        [avail_mem] => 31448408
        [block_lists] => Array
            (
                [0] => Array
                    (
                        [0] => Array
                            (
                                [size] => 31448408
                                [offset] => 8864
                            )

                    )

            )

    )

### Veja Também

- Diretivas de configuração APCu

# apcu_store

(PECL apcu >= 4.0.0)

apcu_store — Armazena uma variável em cache

### Descrição

function apcu_store(string `$key`, mixed `$var`, int `$ttl` = 0): bool
function apcu_store(array `$values`, mixed `$unused` = NULL, int `$ttl` = 0): array

Armazena uma variável em cache.

> Nota: Diferentemente de muitos outros mecanismos no PHP, variáveis armazenadas usando apcu_store() persistirão entre requisições (até que o valor seja removido do cache).

### Parâmetros

`key`
  Armazena a variável usando o nome informado em `key`, que deve ser única no cache. Portanto, armazenar um segundo valor com o mesmo valor de `key` irá substituir o valor original.
`var`
  A variável a ser armazenada
`ttl`
  Tempo de Vida (Time To Live); armazena `var` no cache por `ttl` segundos. Depois desses `ttl` segundos, a variável armazenada será excluída do cache (na próxima requisição). Se nenhum parâmetro `ttl` for informado (ou se `ttl` for `0`), o valor persistirá até que seja removido do cache manualmente, ou caso deixe de existir no cache (limpeza, reinício, etc.).
`values`
  Nomes nas chaves, variáveis nos valores.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha. A segunda sintaxe retorna um array com chaves de erros.

### Exemplos

Exemplo #1 Um exemplo de apcu_store()

    <?php
    $bar = 'BAR';
    apcu_store('foo', $bar);
    var_dump(apcu_fetch('foo'));
    ?>

O exemplo acima produzirá:

    string(3) "BAR"

### Veja Também

- apcu_add() - Faz cache de uma nova variável no armazenamento de dados
- apcu_fetch() - Busca uma variável armazenada no cache
- apcu_delete() - Remove uma variável armazenada do cache

## Índice

- apcu_add — Faz cache de uma nova variável no armazenamento de dados
- apcu_cache_info — Recupera informação em cache a partir do armazenamento de dados do APCu
- apcu_cas — Atualiza um valor antigo com um novo
- apcu_clear_cache — Limpa o cache APCu
- apcu_dec — Decrementa um número armazenado
- apcu_delete — Remove uma variável armazenada do cache
- apcu_enabled — Informa se o APCu está disponível no ambiente atual
- apcu_entry — Busca ou gera atomicamente uma entrada de cache
- apcu_exists — Verifica se uma entrada existe
- apcu_fetch — Busca uma variável armazenada no cache
- apcu_inc — Incrementa um número armazenado
- apcu_key_info — Obtém informação detalhada sobre uma chave em cache
- apcu_sma_info — Obtém informação de Alocação de Memória Compartilhada (SMA) do APCu
- apcu_store — Armazena uma variável em cache

# A classe APCUIterator

(PECL apcu >= 5.0.0)

## Introdução

A classe APCUIterator torna mais fácil iterar sobre grandes caches APCu. Ela é útil pois permite iterar sobre grandes caches em etapas, capturando um número definido de entradas por instância de trava, portanto ela libera as travas de cache para outras atividades ao invés de segurar todo o cache para capturar 100 entradas (que é o padrão). Além disso, usar correspondências com expressões regulares é mais eficiente pois opera no nível de linguagem C.

## Resumo da classe

class APCUIterator implements Iterator {
/* Métodos */
public function __construct(
array|string|null `$search` = `null`,
int `$format` = APC_ITER_ALL,
int `$chunk_size` = 100,
int `$list` = APC_LIST_ACTIVE
)
public function current(): mixed
public function getTotalCount(): int
public function getTotalHits(): int
public function getTotalSize(): int
public function key(): string
public function next(): bool
public function rewind(): void
public function valid(): bool
}

# APCUIterator::__construct

(PECL apcu >= 5.0.0)

APCUIterator::__construct — Constrói um objeto iterador APCUIterator

### Descrição

public function APCUIterator::__construct(
array|string|null `$search` = `null`,
int `$format` = APC_ITER_ALL,
int `$chunk_size` = 100,
int `$list` = APC_LIST_ACTIVE
)

Constrói um object da classe APCUIterator.

### Parâmetros

`search`
  Pode ser uma expressão regular PCRE que corresponda a nomes de chaves APCu, informada como uma string. Ou um array de strings com nomes de chaves APCu. Ou, opcionalmente, `null` para não fazer a pesquisa.
`format`
  O formato desejado, como configurado com um ou mais das constantes APC_ITER_*.
`chunk_size`
  O tamanho do pacote. Deve ser um valor maior que 0. O valor padrão é 100.
`list`
  O tipo a ser listado. Podem ser passadas as constantes `APC_LIST_ACTIVE` ou `APC_LIST_DELETED`.

### Exemplos

Exemplo #1 Um exemplo de APCUIterator::__construct()

    <?php
    foreach (new APCUIterator('/^counter\./') as $counter) {
        echo "$counter[key]: $counter[value]\n";
        apc_dec($counter['key'], $counter['value']);
    }
    ?>

### Veja Também

- apcu_exists() - Verifica se uma entrada existe
- apcu_cache_info() - Recupera informação em cache a partir do armazenamento de dados do APCu

# APCUIterator::current

(PECL apcu >= 5.0.0)

APCUIterator::current — Obtém o item atual

### Descrição

public function APCUIterator::current(): mixed

Obtém o item atual da pilha do APCUIterator.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o item atual em caso de sucesso; ou `false` se não existirem mais itens ou em caso de falha.

### Veja Também

- APCUIterator::next() - Move o ponteiro para o próximo item
- Iterator::current() - Retorna o elemento atual

# APCUIterator::getTotalCount

(PECL apcu >= 5.0.0)

APCUIterator::getTotalCount — Obtém a contagem total

### Descrição

public function APCUIterator::getTotalCount(): int

Obtém a contagem total.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

A contagem total.

### Veja Também

- APCUIterator::getTotalHits() - Obtém o total de entradas de cache
- APCUIterator::getTotalSize() - Obtém o tamanho total do cache
- apcu_cache_info() - Recupera informação em cache a partir do armazenamento de dados do APCu

# APCUIterator::getTotalHits

(PECL apcu >= 5.0.0)

APCUIterator::getTotalHits — Obtém o total de entradas de cache

### Descrição

public function APCUIterator::getTotalHits(): int

Obtém o número total de entradas de cache.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O número de entradas em caso de sucesso, ou `false` em caso de falha.

### Veja Também

- APCUIterator::getTotalCount() - Obtém a contagem total
- APCUIterator::getTotalSize() - Obtém o tamanho total do cache
- apcu_cache_info() - Recupera informação em cache a partir do armazenamento de dados do APCu

# APCUIterator::getTotalSize

(PECL apcu >= 5.0.0)

APCUIterator::getTotalSize — Obtém o tamanho total do cache

### Descrição

public function APCUIterator::getTotalSize(): int

Obtém o tamanho total do cache.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O tamanho total do cache.

### Veja Também

- APCUIterator::getTotalCount() - Obtém a contagem total
- APCUIterator::getTotalHits() - Obtém o total de entradas de cache
- apc_cache_info()

# APCUIterator::key

(PECL apcu >= 5.0.0)

APCUIterator::key — Obtém a chave do iterador

### Descrição

public function APCUIterator::key(): string

Obtém a chave atual do iterador.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a chave em caso de sucesso, ou `false` em caso de falha.

### Veja Também

- APCUIterator::current() - Obtém o item atual
- Iterator::key() - Retorna a chave do elemento atual

# APCUIterator::next

(PECL apcu >= 5.0.0)

APCUIterator::next — Move o ponteiro para o próximo item

### Descrição

public function APCUIterator::next(): bool

Move o ponteiro do iterador para o próximo elemento.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- APCUIterator::current() - Obtém o item atual
- APCUIterator::rewind() - Rebobina o iterador
- Iterator::next() - Move para o próximo elemento

# APCUIterator::rewind

(PECL apcu >= 5.0.0)

APCUIterator::rewind — Rebobina o iterador

### Descrição

public function APCUIterator::rewind(): void

Retrocede o iterador para o primeiro elemento.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

### Veja Também

- APCUIterator::next() - Move o ponteiro para o próximo item
- Iterator::next() - Move para o próximo elemento

# APCUIterator::valid

(PECL apcu >= 5.0.0)

APCUIterator::valid — Verifica se a posição atual é válida

### Descrição

public function APCUIterator::valid(): bool

Verifica se a posição atual do iterador é válida.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se a posição atual do iterador for válida, caso contrário retorna `false`.

### Veja Também

- APCUIterator::current() - Obtém o item atual
- Iterator::valid() - Verifica se a posição atual é válida

## Índice

- APCUIterator::__construct — Constrói um objeto iterador APCUIterator
- APCUIterator::current — Obtém o item atual
- APCUIterator::getTotalCount — Obtém a contagem total
- APCUIterator::getTotalHits — Obtém o total de entradas de cache
- APCUIterator::getTotalSize — Obtém o tamanho total do cache
- APCUIterator::key — Obtém a chave do iterador
- APCUIterator::next — Move o ponteiro para o próximo item
- APCUIterator::rewind — Rebobina o iterador
- APCUIterator::valid — Verifica se a posição atual é válida

- Instalação/Configuração
  - Instalação
  - Configurações em Execução
- Constantes predefinidas
- APCu Funções
  - apcu_add — Faz cache de uma nova variável no armazenamento de dados
  - apcu_cache_info — Recupera informação em cache a partir do armazenamento de dados do APCu
  - apcu_cas — Atualiza um valor antigo com um novo
  - apcu_clear_cache — Limpa o cache APCu
  - apcu_dec — Decrementa um número armazenado
  - apcu_delete — Remove uma variável armazenada do cache
  - apcu_enabled — Informa se o APCu está disponível no ambiente atual
  - apcu_entry — Busca ou gera atomicamente uma entrada de cache
  - apcu_exists — Verifica se uma entrada existe
  - apcu_fetch — Busca uma variável armazenada no cache
  - apcu_inc — Incrementa um número armazenado
  - apcu_key_info — Obtém informação detalhada sobre uma chave em cache
  - apcu_sma_info — Obtém informação de Alocação de Memória Compartilhada (SMA) do APCu
  - apcu_store — Armazena uma variável em cache
- APCUIterator — A classe APCUIterator
  - APCUIterator::__construct — Constrói um objeto iterador APCUIterator
  - APCUIterator::current — Obtém o item atual
  - APCUIterator::getTotalCount — Obtém a contagem total
  - APCUIterator::getTotalHits — Obtém o total de entradas de cache
  - APCUIterator::getTotalSize — Obtém o tamanho total do cache
  - APCUIterator::key — Obtém a chave do iterador
  - APCUIterator::next — Move o ponteiro para o próximo item
  - APCUIterator::rewind — Rebobina o iterador
  - APCUIterator::valid — Verifica se a posição atual é válida

# Componere

# Introdução

Componere (latim, português: compor) tem como alvo ambientes de produção e fornece uma API para composição de classes, alteração dinâmica de código durante a execução e conversões.

##### Composição:

Componere\Definition é usado para definir (ou redefinir) uma classe em tempo de execução; A classe pode então ser registrada, e no caso de redefinição ela substitui a classe original enquanto o Componere\Definition existir.

public function Componere\Definition::__construct(string `$name`)
public function Componere\Definition::__construct(string `$name`, string `$parent`)
public function Componere\Definition::__construct(string `$name`, array `$interfaces`)
public function Componere\Definition::__construct(string `$name`, string `$parent`, array `$interfaces`)

##### Alteração dinâmica:

Componere\Patch é usado para alterar a classe de uma instância específica de um objeto em tempo de execução; Após a aplicação, o patch permanecerá aplicado enquanto o Componere\Patch existir e poderá ser revertido explicitamente.

public function Componere\Patch::__construct(object `$instance`)
public function Componere\Patch::__construct(object `$instance`, array `$interfaces`)

##### Conversão:

As funções de conversão do Componere\ podem converter entre tipos compatíveis definidos pelo usuário; Onde compatível significa que Type é sub ou super ao tipo de `object`.

function Componere\cast(string `$type`, object `$object`): object
function Componere\cast_by_ref(string `$type`, object `$object`): object

# Instalação/Configuração

## Índice

- Dependências
- Instalação

## Dependências

Reflection é necessária

## Instalação

A fonte e os lançamentos do Componere estão disponíveis em » github

# A classe Componere\Abstract\Definition

(Componere 2 >= 2.1.0)

## Introdução

Este final abstract representa uma entrada de classe e não deve ser usado pelo programador.

## Resumo da classe

final abstract class Componere\Abstract\Definition {
/* Métodos */
public function addInterface(string `$interface`): Definition
public function addMethod(string `$name`, Componere\Method `$method`): Definition
public function addTrait(string `$trait`): Definition
public function getReflector(): ReflectionClass
}

# Componere\Abstract\Definition::addInterface

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::addInterface — Adiciona Interface

### Descrição

public function Componere\Abstract\Definition::addInterface(string `$interface`): Definition

Implementa a interface informada na definição atual.

### Parâmetros

`interface`
  O nome de uma interface, insensível a maiúsculas/minúsculas.

### Valor Retornado

A definição atual.

### Exceções

Aviso

Lança uma RuntimeException se Definition já estava registrada.

# Componere\Abstract\Definition::addMethod

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::addMethod — Adiciona método

### Descrição

public function Componere\Abstract\Definition::addMethod(string `$name`, Componere\Method `$method`): Definition

Cria ou substitui um método na definição atual.

### Parâmetros

`name`
  O nome de um método, insensível a maiúsculas/minúsculas.
`method`
  Componere\Method que não tenha sido adicionado a outra Definition.

### Valor Retornado

A definição atual.

### Exceptions

Aviso

Lança uma RuntimeException se Definition já estava registrada.

Aviso

Lança uma RuntimeException se o método já havia sido adicionado a outra definição.

# Componere\Abstract\Definition::addTrait

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::addTrait — Adiciona Trait

### Descrição

public function Componere\Abstract\Definition::addTrait(string `$trait`): Definition

Usa o trait fornecido para a definição atual.

### Parâmetros

`trait`
  O nome de um trait, insensível a maiúsculas/minúsculas.

### Valor Retornado

A definição atual.

### Exceptions

Aviso

Lança uma RuntimeException se Definition já estava registrada.

# Componere\Abstract\Definition::getReflector

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::getReflector — Cria ou obtém uma reflexão

### Descrição

public function Componere\Abstract\Definition::getReflector(): ReflectionClass

Cria ou retorna uma ReflectionClass.

### Valor Retornado

Uma ReflectionClass para a definição atual (em cache).

## Índice

- Componere\Abstract\Definition::addInterface — Adiciona Interface
- Componere\Abstract\Definition::addMethod — Adiciona método
- Componere\Abstract\Definition::addTrait — Adiciona Trait
- Componere\Abstract\Definition::getReflector — Cria ou obtém uma reflexão

# A classe Componere\Definition

(Componere 2 >= 2.1.0)

## Introdução

A classe Definition permite ao programador construir e registrar um tipo em tempo de execução.

Caso uma Definition substitua uma classe existente, a classe existente será restaurada quando a Definition for destruída.

## Resumo da classe

final class Componere\Definition extends Componere\Abstract\Definition {
/* Constructors */
public function __construct(string `$name`)
public function __construct(string `$name`, string `$parent`)
public function __construct(string `$name`, array `$interfaces`)
public function __construct(string `$name`, string `$parent`, array `$interfaces`)
/* Métodos */
public function addConstant(string `$name`, Componere\Value `$value`): Definition
public function addProperty(string `$name`, Componere\Value `$value`): Definition
public function register(): void
public function isRegistered(): bool
public function getClosure(string `$name`): Closure
public function getClosures(): array
/* Métodos herdados */
public function Componere\Abstract\Definition::addInterface(string `$interface`): Definition
public function Componere\Abstract\Definition::addMethod(string `$name`, Componere\Method `$method`): Definition
public function Componere\Abstract\Definition::addTrait(string `$trait`): Definition
public function Componere\Abstract\Definition::getReflector(): ReflectionClass
}

# Componere\Definition::__construct

(Componere 2 >= 2.1.0)

Componere\Definition::__construct — Construção da definição

### Descrição

public function Componere\Definition::__construct(string `$name`)
public function Componere\Definition::__construct(string `$name`, string `$parent`)
public function Componere\Definition::__construct(string `$name`, array `$interfaces`)
public function Componere\Definition::__construct(string `$name`, string `$parent`, array `$interfaces`)

### Parâmetros

`name`
  O nome de uma classe, insensível a maiúsculas/minúsculas.
`parent`
  O nome de uma classe, insensível a maiúsculas/minúsculas.
`interfaces`
  Um array de nomes de classe, insensíveis a maiúsculas/minúsculas.

### Exceptions

Aviso

Lança uma InvalidArgumentException se for feita uma tentativa de substituir uma classe interna.

Aviso

Lança uma InvalidArgumentException se for feita uma tentativa de substituir uma interface.

Aviso

Lança uma InvalidArgumentException se for feita uma tentativa de substituir um trait.

Aviso

Lança uma RuntimeException se um classe em `interfaces` não puder ser encontrada.

Aviso

Lança uma RuntimeException se uma classe em `interfaces` não for uma interface.

# Componere\Definition::addConstant

(Componere 2 >= 2.1.0)

Componere\Definition::addConstant — Adiciona constante

### Descrição

public function Componere\Definition::addConstant(string `$name`, Componere\Value `$value`): Definition

Declara uma constante de classe na definição atual.

### Parâmetros

`name`
  O nome para a constante, insensível a maiúsculas/minúsculas.
`value`
  O valor para a constante, não pode ser indefinida ou estática.

### Valor Retornado

A definição atual.

### Exceptions

Aviso

Lança uma RuntimeException se Definition já estiver registrada.

Aviso

Lança uma RuntimeException se `name` já estiver declarado como uma constante.

Aviso

Lança uma RuntimeException se `value` for estático.

Aviso

Lança uma RuntimeException se `value` for indefinido.

# Componere\Definition::addProperty

(Componere 2 >= 2.1.0)

Componere\Definition::addProperty — Adiciona propriedade

### Descrição

public function Componere\Definition::addProperty(string `$name`, Componere\Value `$value`): Definition

Declara uma propriedade de classe na definição atual.

### Parâmetros

`name`
  O nome para a propriedade, insensível a maiúsculas/minúsculas.
`value`
  O valor padrão para a propriedade.

### Valor Retornado

A definição atual.

### Exceptions

Aviso

Lança uma RuntimeException se a Definition já estiver registrada.

Aviso

Lança uma RuntimeException se `name` já estiver declarada como uma propriedade.

# Componere\Definition::register

(Componere 2 >= 2.1.0)

Componere\Definition::register — Registro

### Descrição

public function Componere\Definition::register(): void

Registra a definição atual.

### Exceptions

Aviso

Lança uma RuntimeException se a Definition já estiver registrada.

# Componere\Definition::isRegistered

(Componere 2 >= 2.1.0)

Componere\Definition::isRegistered — Detecção de estado

### Descrição

public function Componere\Definition::isRegistered(): bool

Detecta o estado de registro desta definição.

### Valor Retornado

Retorna true se esta definição já estiver registrada.

# Componere\Definition::getClosure

(Componere 2 >= 2.1.0)

Componere\Definition::getClosure — Obtém Closure

### Descrição

public function Componere\Definition::getClosure(string `$name`): Closure

Retorna uma Closure para o método especificado pelo nome.

### Parâmetros

`name`
  O nome do método, insensível a maiúsculas/minúsculas.

### Valor Retornado

Uma Closure vinculada ao escopo atual.

### Exceptions

Aviso

Lança uma RuntimeException se a Definition já estiver registrada.

Aviso

Lança uma RuntimeException se `name` não puder ser encontrada.

# Componere\Definition::getClosures

(Componere 2 >= 2.1.0)

Componere\Definition::getClosures — Obtém Closures

### Descrição

public function Componere\Definition::getClosures(): array

Retorna um array de Closures.

### Valor Retornado

Retorna todos os métodos como um array de objetos Closure ligados ao escopo correto.

### Exceptions

Aviso

Lança uma RuntimeException se Definition já estiver registrada.

## Índice

- Componere\Definition::__construct — Construção da definição
- Componere\Definition::addConstant — Adiciona constante
- Componere\Definition::addProperty — Adiciona propriedade
- Componere\Definition::register — Registro
- Componere\Definition::isRegistered — Detecção de estado
- Componere\Definition::getClosure — Obtém Closure
- Componere\Definition::getClosures — Obtém Closures

# A classe Componere\Patch

(Componere 2 >= 2.1.0)

## Introdução

A classe Patch permite ao programador alterar o tipo de uma instância em tempo de execução sem registrar uma nova Definição (Definition)

Quando um Patch é destruído, ele é revertido, de modo que as instâncias que foram corrigidas durante a vida do Patch sejam restauradas ao seu tipo formal.

## Resumo da classe

final class Componere\Patch extends Componere\Abstract\Definition {
/* Constructors */
public function __construct(object `$instance`)
public function __construct(object `$instance`, array `$interfaces`)
/* Métodos */
public function apply(): void
public function revert(): void
public function isApplied(): bool
public function derive(object `$instance`): Patch
public function getClosure(string `$name`): Closure
public function getClosures(): array
/* Métodos herdados */
public function Componere\Abstract\Definition::addInterface(string `$interface`): Definition
public function Componere\Abstract\Definition::addMethod(string `$name`, Componere\Method `$method`): Definition
public function Componere\Abstract\Definition::addTrait(string `$trait`): Definition
public function Componere\Abstract\Definition::getReflector(): ReflectionClass
}

# Componere\Patch::__construct

(Componere 2 >= 2.1.0)

Componere\Patch::__construct — Construção de Patch

### Descrição

public function Componere\Patch::__construct(object `$instance`)
public function Componere\Patch::__construct(object `$instance`, array `$interfaces`)

### Parâmetros

`instance`
  O destino para este Patch
`interfaces`
  Um array de nomes de classe, insensíveis a maiúsculas/minúsculas.

### Exceções

Aviso

Lança uma RuntimeException se uma classe em `interfaces` não puder ser encontrada.

Aviso

Lança uma RuntimeException se uma classe em `interfaces` não for uma interface.

# Componere\Patch::apply

(Componere 2 >= 2.1.0)

Componere\Patch::apply — Aplica o patch

### Descrição

public function Componere\Patch::apply(): void

Aplica o patch atual.

# Componere\Patch::revert

(Componere 2 >= 2.1.0)

Componere\Patch::revert — Reversão

### Descrição

public function Componere\Patch::revert(): void

Reverte o Patch atual.

# Componere\Patch::isApplied

(Componere 2 >= 2.1.0)

Componere\Patch::isApplied — Definição de estado

### Descrição

public function Componere\Patch::isApplied(): bool

# Componere\Patch::derive

(Componere 2 >= 2.1.1)

Componere\Patch::derive — Derivaçaõ de Patch

### Descrição

public function Componere\Patch::derive(object `$instance`): Patch

Deriva um Patch para a `instance` informada.

### Parâmetros

`instance`
  O destino para o Patch derivado.

### Valor Retornado

Patch para `instance` derivado do Patch atual.

### Exceções

Aviso

Lança uma InvalidArgumentException se `instance` não for compatível.

# Componere\Patch::getClosure

(Componere 2 >= 2.1.0)

Componere\Patch::getClosure — Obtém Closure

### Descrição

public function Componere\Patch::getClosure(string `$name`): Closure

Retorna uma Closure para o método especificado pelo nome.

### Parâmetros

`name`
  O nome do método, insensível a maiúsculas/minúsculas.

### Valor Retornado

Uma Closure vinculada ao escopo e objeto corretos.

### Exceptions

Aviso

Lança uma RuntimeException se `name` não puder ser encontrado.

# Componere\Patch::getClosures

(Componere 2 >= 2.1.0)

Componere\Patch::getClosures — Obtém Closures

### Descrição

public function Componere\Patch::getClosures(): array

Retorna um array de Closures.

### Valor Retornado

Retorna todos os métodos como um array de objetos Closure vinculados ao escopo e objeto corretos.

## Índice

- Componere\Patch::__construct — Construção de Patch
- Componere\Patch::apply — Aplica o patch
- Componere\Patch::revert — Reversão
- Componere\Patch::isApplied — Definição de estado
- Componere\Patch::derive — Derivaçaõ de Patch
- Componere\Patch::getClosure — Obtém Closure
- Componere\Patch::getClosures — Obtém Closures

# A classe Componere\Method

(Componere 2 >= 2.1.0)

## Introdução

Um Method representa uma função com opções de acessibilidade modificáveis

## Resumo da classe

final class Componere\Method {
/* Constructor */
public function __construct(Closure `$closure`)
/* Métodos */
public function setPrivate(): Method
public function setProtected(): Method
public function setStatic(): Method
public function getReflector(): ReflectionMethod
}

# Componere\Method::__construct

(Componere 2 >= 2.1.0)

Componere\Method::__construct — Construção de método

### Descrição

public function Componere\Method::__construct(Closure `$closure`)

### Parâmetros

`closure`

# Componere\Method::setPrivate

(Componere 2 >= 2.1.0)

Componere\Method::setPrivate — Modificação de acessibilidade

### Descrição

public function Componere\Method::setPrivate(): Method

### Valor Retornado

O método atual.

### Exceptions

Aviso

Lança uma RuntimeException se o nível de acesso já tiver sido definido anteriormente.

# Componere\Method::setProtected

(Componere 2 >= 2.1.0)

Componere\Method::setProtected — Modificação de acessibilidade

### Descrição

public function Componere\Method::setProtected(): Method

### Valor Retornado

O método atual.

### Exceptions

Aviso

Lança uma RuntimeException se o nível de acesso já tiver sido definido anteriormente.

# Componere\Method::setStatic

(Componere 2 >= 2.1.0)

Componere\Method::setStatic — Modificação de acessibilidade

### Descrição

public function Componere\Method::setStatic(): Method

### Valor Retornado

O método atual.

# Componere\Method::getReflector

(Componere 2 >= 2.1.0)

Componere\Method::getReflector — Cria ou obtém Reflexão

### Descrição

public function Componere\Method::getReflector(): ReflectionMethod

Cria ou retorna um ReflectionMethod.

### Valor Retornado

Um ReflectionMethod para o método atual (em cache).

## Índice

- Componere\Method::__construct — Construção de método
- Componere\Method::setPrivate — Modificação de acessibilidade
- Componere\Method::setProtected — Modificação de acessibilidade
- Componere\Method::setStatic — Modificação de acessibilidade
- Componere\Method::getReflector — Cria ou obtém Reflexão

# A classe Componere\Value

(Componere 2 >= 2.1.0)

## Introdução

Um valor representa uma variável PHP de todos os tipos, incluindo indefinida

## Resumo da classe

final class Componere\Value {
/* Constructor */
public function __construct(mixed `$default` = ?)
/* Métodos */
public function setPrivate(): Value
public function setProtected(): Value
public function setStatic(): Value
public function isPrivate(): bool
public function isProtected(): bool
public function isStatic(): bool
public function hasDefault(): bool
}

# Componere\Value::__construct

(Componere 2 >= 2.1.0)

Componere\Value::__construct — Construção de Valor

### Descrição

public function Componere\Value::__construct(mixed `$default` = ?)

### Parâmetros

`default`

### Exceções

Aviso

Lança uma InvalidArgumentException se `default` não tiver um valor adequado.

# Componere\Value::setPrivate

(Componere 2 >= 2.1.0)

Componere\Value::setPrivate — Modificação de acessibilidade

### Descrição

public function Componere\Value::setPrivate(): Value

### Valor Retornado

O objeto Value atual.

### Exceptions

Aviso

Lança uma RuntimeException se o nível de acesso já tiver sido definido anteriormente.

# Componere\Value::setProtected

(Componere 2 >= 2.1.0)

Componere\Value::setProtected — Modificação de acessibilidade

### Descrição

public function Componere\Value::setProtected(): Value

### Valor Retornado

O objeto Value atual.

### Exceptions

Aviso

Lança uma RuntimeException se o nível de acesso já tiver sido definido anteriormente.

# Componere\Value::setStatic

(Componere 2 >= 2.1.0)

Componere\Value::setStatic — Modificação de acessibilidade

### Descrição

public function Componere\Value::setStatic(): Value

### Valor Retornado

O objeto Value atual.

# Componere\Value::isPrivate

(Componere 2 >= 2.1.0)

Componere\Value::isPrivate — Detecção de acessibilidade

### Descrição

public function Componere\Value::isPrivate(): bool

# Componere\Value::isProtected

(Componere 2 >= 2.1.0)

Componere\Value::isProtected — Detecção de acessibilidade

### Descrição

public function Componere\Value::isProtected(): bool

# Componere\Value::isStatic

(Componere 2 >= 2.1.0)

Componere\Value::isStatic — Detecção de acessibilidade

### Descrição

public function Componere\Value::isStatic(): bool

# Componere\Value::hasDefault

(Componere 2 >= 2.1.0)

Componere\Value::hasDefault — Intereção de Valor

### Descrição

public function Componere\Value::hasDefault(): bool

## Índice

- Componere\Value::__construct — Construção de Valor
- Componere\Value::setPrivate — Modificação de acessibilidade
- Componere\Value::setProtected — Modificação de acessibilidade
- Componere\Value::setStatic — Modificação de acessibilidade
- Componere\Value::isPrivate — Detecção de acessibilidade
- Componere\Value::isProtected — Detecção de acessibilidade
- Componere\Value::isStatic — Detecção de acessibilidade
- Componere\Value::hasDefault — Intereção de Valor

# Funções de Componere

# Componere\cast

(Componere 2 >= 2.1.2)

Componere\cast — Conversão

### Descrição

function Componere\cast(string `$type`, object `$object`): object

### Parâmetros

`type`
  Um tipo definido pelo usuário.
`object`
  Um objeto com um tipo definido pelo usuário, compatível com Type

### Valor Retornado

Um object do tipo Type, convertido de `object`

### Erros/Exceções

Aviso

Lança uma InvalidArgumentException se o tipo de `object` for uma classe interna ou derivado de uma classe interna.

Aviso

Lança uma InvalidArgumentException se Type for uma interface

Aviso

Lança uma InvalidArgumentException se Type for um trait

Aviso

Lança uma InvalidArgumentException se Type for um abstract

Aviso

Lança uma InvalidArgumentException se Type não for compatível com o tipo de `object`

### Veja Também

- Componere\cast_by_ref

# Componere\cast_by_ref

(Componere 2 >= 2.1.2)

Componere\cast_by_ref — Conversão

### Descrição

function Componere\cast_by_ref(string `$type`, object `$object`): object

### Parâmetros

type
  Um tipo definido pelo usuário
`object`
  Um objeto com um tipo definido pelo usuário, compatível com Type

### Valor Retornado

Um object do tipo Type, convertido de `object`, onde os membros são referências aos membros de `object`

### Erros/Exceções

Aviso

Lança uma InvalidArgumentException se o tipo de `object` for uma classe interna ou derivado de uma classe interna.

Aviso

Lança uma InvalidArgumentException se Type for uma interface

Aviso

Lança uma InvalidArgumentException se Type for um trait

Aviso

Lança uma InvalidArgumentException se Type for um abstract

Aviso

Lança uma InvalidArgumentException se Type não for compatível com o tipo de `object`

### Veja Também

- Componere\cast

## Índice

- Componere\cast — Conversão
- Componere\cast_by_ref — Conversão

- Instalação/Configuração
  - Dependências
  - Instalação
- Componere\Abstract\Definition — A classe Componere\Abstract\Definition
  - Componere\Abstract\Definition::addInterface — Adiciona Interface
  - Componere\Abstract\Definition::addMethod — Adiciona método
  - Componere\Abstract\Definition::addTrait — Adiciona Trait
  - Componere\Abstract\Definition::getReflector — Cria ou obtém uma reflexão
- Componere\Definition — A classe Componere\Definition
  - Componere\Definition::__construct — Construção da definição
  - Componere\Definition::addConstant — Adiciona constante
  - Componere\Definition::addProperty — Adiciona propriedade
  - Componere\Definition::register — Registro
  - Componere\Definition::isRegistered — Detecção de estado
  - Componere\Definition::getClosure — Obtém Closure
  - Componere\Definition::getClosures — Obtém Closures
- Componere\Patch — A classe Componere\Patch
  - Componere\Patch::__construct — Construção de Patch
  - Componere\Patch::apply — Aplica o patch
  - Componere\Patch::revert — Reversão
  - Componere\Patch::isApplied — Definição de estado
  - Componere\Patch::derive — Derivaçaõ de Patch
  - Componere\Patch::getClosure — Obtém Closure
  - Componere\Patch::getClosures — Obtém Closures
- Componere\Method — A classe Componere\Method
  - Componere\Method::__construct — Construção de método
  - Componere\Method::setPrivate — Modificação de acessibilidade
  - Componere\Method::setProtected — Modificação de acessibilidade
  - Componere\Method::setStatic — Modificação de acessibilidade
  - Componere\Method::getReflector — Cria ou obtém Reflexão
- Componere\Value — A classe Componere\Value
  - Componere\Value::__construct — Construção de Valor
  - Componere\Value::setPrivate — Modificação de acessibilidade
  - Componere\Value::setProtected — Modificação de acessibilidade
  - Componere\Value::setStatic — Modificação de acessibilidade
  - Componere\Value::isPrivate — Detecção de acessibilidade
  - Componere\Value::isProtected — Detecção de acessibilidade
  - Componere\Value::isStatic — Detecção de acessibilidade
  - Componere\Value::hasDefault — Intereção de Valor
- Funções de Componere
  - Componere\cast — Conversão
  - Componere\cast_by_ref — Conversão

# Gerenciamento e Registro de Erros

# Introdução

Estas são funções para lidar com gerenciamento e registro de erros. Elas permitem a definição de regras personalizadas de gerenciamento de erros e e de maneiras de se registrá-los. Isto possibilita que os relators de erros sejam modificados e melhorados para se adequar às necessidades do programador.

Com as funções de registro, pode-se enviar mensagens diretamente para outras máquinas, para um email (ou email para um portal de pagers), para os registros do sistema etc., de forma que seja possível registrar e monitorar as partes mais importantes das aplicações e sites da internet.

As funções relatórios de erro permitem customizar quais níveis e tipos de retorno de erro são fornecidos, desde notas simples até funções personalizadas retornadas durante os erros.

# Instalação/Configuração

## Índice

- Configurações em Execução

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de Configuração de Erros e de Registros
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
error_reporting | NULL | `INI_ALL` |
fatal_error_backtraces | "1" | `INI_ALL` | Disponível a partir do PHP 8.5.0.
display_errors | "1" | `INI_ALL` |
display_startup_errors | "1" | `INI_ALL` | Antes do PHP 8.0.0, o valor padrão era `"0"`.
log_errors | "0" | `INI_ALL` |
log_errors_max_len | "1024" | `INI_ALL` | Sem efeito a partir do PHP 8.0.0, removido a partir do PHP 8.1.0.
ignore_repeated_errors | "0" | `INI_ALL` |
ignore_repeated_source | "0" | `INI_ALL` |
report_memleaks | "1" | `INI_ALL` | Descontinuada a partir do PHP 8.5.0
track_errors | "0" | `INI_ALL` | Descontinuado a partir do PHP 7.2.0, removido a partir do PHP 8.0.0.
html_errors | "1" | `INI_ALL` |
xmlrpc_errors | "0" | `INI_SYSTEM` |
xmlrpc_error_number | "0" | `INI_ALL` |
docref_root | "" | `INI_ALL` |
docref_ext | "" | `INI_ALL` |
error_prepend_string | NULL | `INI_ALL` |
error_append_string | NULL | `INI_ALL` |
error_log | NULL | `INI_ALL` |
error_log_mode | 0o644 | `INI_ALL` | Disponível a partir do PHP 8.2.0
syslog.facility | "LOG_USER" | `INI_SYSTEM` | Disponível a partir do PHP 7.3.0.
syslog.filter | "no-ctrl" | `INI_ALL` | Disponível a partir do PHP 7.3.0.
syslog.ident | "php" | `INI_SYSTEM` | Disponível a partir do PHP 7.3.0.

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`error_reporting` int

  Define o nível das reportagens de erros. O parâmetro é ou um inteiro representando um campo de bits ou constantes nomeadas. Os níveis e constantes de reportagens de erros estão descritos em Constantes Predefinidas e no arquivo php.ini. Para definir em tempo de execução, use a função error_reporting(). Consulte também a diretiva display_errors.

  O padrão é `E_ALL`.

  Antes do PHP 8.0.0, o valor padrão era: ``E_ALL` & ~`E_NOTICE` & ~`E_STRICT` & ~`E_DEPRECATED``. Isto significa que os diagnósticos de nível `E_NOTICE`, `E_STRICT` e `E_DEPRECATED` não eram mostrados.

  > Nota: Constantes do PHP fora do PHP

  > Usar constantes do PHP fora do PHP, como no httpd.conf, não terão significado algum, portanto, nesses casos, os valores int são necessários. E, como níveis de erro serão adicionados ao longo do tempo, o valor máximo (para `E_ALL`) provavelmente será alterado. Portanto, no lugar de `E_ALL`, considere usar um valor maior para cobrir todos os campos de bits, tanto os de hoje como os do futuro, um valor numérico como `2147483647` (inclui todos os erros, não apenas `E_ALL`).

`fatal_error_backtraces` bool
  Constrola se erros fatais devem incluir um rastreamento de pilha. Erros fatais são `E_ERROR`, `E_CORE_ERROR`, `E_COMPILE_ERROR`, `E_USER_ERROR`, `E_RECOVERABLE_ERROR` e `E_PARSE`.
`display_errors` string

  Este parâmetro determina se os erros devem ser mostrados na tela como parte da saída ou se devem ser ocultados do usuário.

  - `Off` - não mostra nenhum erro.
  - `On` ou `stdout` - mostra erros em `stdout`. É o padrão.
  - `stderr` - mostra erros em `stderr`. Efetivo somento nos SAPIs `CLI`, `phpdbg` e `CGI`.
  O arquivo `php.ini-development` define para `On`; já o arquivo `php.ini-production` define para `Off`.

  > Nota: Este é um recurso para dar suporte ao desenvolvimento e nunca deve ser usado em sistemas de produção (por exemplo, sistemas conectados à internet).

  > Nota:

  > Embora display_errors possa ser configurado em tempo de execução (com ini_set()), ele não terá nenhum efeito se o script tiver erros fatais. Isso ocorre porque a ação desejada em tempo de execução não é executada.

`display_startup_errors` bool

  Mesmo quando display_errors está ativado, erros que ocorrem durante a sequência de inicialização do PHP não são exibidos. É altamente recomendável manter display_startup_errors desativado, exceto para depuração.

`log_errors` bool

  Informa se as mensagens de erro de script devem ser gravadas no registro de erros do servidor ou no local indicado por error_log. Essa opção é, portanto, específica do servidor.

  > Nota:

  > É altamente aconselhável usar o registro de erros em vez de exibir erros em sites de produção.

`log_errors_max_len` int

  Define o comprimento máximo de log_errors em bytes. Em error_log, informações sobre a fonte são adicionadas. O padrão é 1024, e 0 permite não aplicar limite de comprimento. Esse tamanho é aplicado a erros registrados, erros exibidos e também a $php_errormsg, mas não a funções chamadas explicitamente como error_log().

  Quando um int é usado, o valor é medido em bytes. A notação abreviada, como descrita nesta FAQ, também pode ser usada.
`ignore_repeated_errors` bool

  Não registra mensagens repetidas. Erros repetidos devem ocorrer no mesmo arquivo e na mesma linha, a menos que ignore_repeated_source seja definido como verdadeiro.

`ignore_repeated_source` bool

  Ignora a fonte da mensagem quando estiver ignorando mensagens repetidas. Quando esta configuração estiver On, não serão registrados erros com mensagens repetidas de arquivos ou linhas diferentes.

`report_memleaks` bool
  Se este parâmetro estiver definido como On (o padrão), este parâmetro mostrará um relatório de vazamentos de memória detectados pelo gerenciador de memória do Zend. Este relatório será enviado para stderr em plataformas Posix. No Windows, ele será enviado ao depurador usando o OutputDebugString() e poderá ser visualizado com ferramentas como » DbgView. Este parâmetro só tem efeito em uma compilação de depuração e se error_reporting incluir `E_WARNING` na lista de erros permitidos.
  Aviso

  Este recurso foi DESCONTINUADO a partir do PHP 8.5.0. O uso deste recurso é fortemente desencorajado.

`track_errors` bool

  Se habilitado, a última mensagem de erro estará sempre presente na variável $php_errormsg.

`html_errors` bool

  Se ativado, as mensagens de erro incluirão tags HTML. O formato para erros de HTML produz mensagens clicáveis que direcionam o usuário para uma página descrevendo o erro ou a função que está causando o erro. Essas referências são afetadas por docref_root e docref_ext.

  Se desativado, a mensagem de erro será apenas texto simples.

`xmlrpc_errors` bool

  Se ativado, desativa o relatório de erros normal e formata os erros como mensagem de erro XML-RPC.

`xmlrpc_error_number` int

  Usado como o valor do elemento faultCode do XML-RPC.

`docref_root` string

  O novo formato de erro contém uma referência a uma página que descreve o erro ou a função que está causando o erro. No caso de páginas de manual, pode-se baixar o manual no idioma próprio e definir esta diretiva ini para a URL da cópia local. Se a cópia local do manual puder ser alcançada por `"/manual/"` pode-se simplesmente usar `docref_root=/manual/`. Além disso, é necessário definir docref_ext para corresponder às extensões de arquivo da cópia local `docref_ext=.html`. É possível usar referências externas. Por exemplo, pode-se usar `docref_root=http://manual/en/` ou `docref_root="http://landonize.it/?how=url&theme=classic&filter=Landon &url=http%3A%2F%2Fwww.php.net%2F"`

  Na maioria das vezes, é desejado que o valor docref_root termine com uma barra `"/"`. Mas veja o segundo exemplo acima, que não tem nem precisa dela.

  > Nota:

  > Este é um recurso para dar suporte ao desenvolvimento, pois facilita a pesquisa da descrição de uma função. No entanto, nunca deve ser usado em sistemas de produção (por exemplo, sistemas conectados à internet).

`docref_ext` string

  Consulte docref_root.

  > Nota:

  > O valor de docref_ext deve começar com um ponto `"."`.

`error_prepend_string` string

  String a ser mostrado antes de uma mensagem de erro. Usado apenas quando a mensagem de erro é mostrada na tela. O propósito principal é prover a capacidade de prefixar uma marcação HTML adicional à mensagem de erro.

`error_append_string` string

  String para mostrar após uma mensagem de erro. Usado apenas quando a mensagem de erro é mostrada na tela. O propósito principal é prover a capacidade de posfixar uma marcação HTML adicional à mensagem de erro.

`error_log` string

  Nome do arquivo onde os erros de script devem ser registrados. O arquivo deve ter permissão de escrita pelo usuário do servidor da web. Se o valor especial `syslog` for usado, os erros serão enviados ao registrador de erros do sistema. No Unix, isso significa syslog(3) e no Windows significa o Log de Eventos. Veja também: syslog(). Se esta diretiva não estiver definida, os erros serão enviados para o registrador de erros SAPI. Por exemplo, é um log de erros no Apache ou `stderr` no CLI. Consulte também error_log().

`error_log_mode` int

  Modo de arquivo para o arquivo definido em error_log.

`syslog.facility` string

  Especifica qual tipo de programa está registrando a mensagem. Apenas efetivo se error_log estiver definido como "syslog".

`syslog.filter` string

  Especifica o tipo de filtro para filtrar as mensagens registradas. Caracteres permitidos são passados sem modificações; todos os outros são escritos em sua representação hexadecimal prefixados com `\x`.

  - `all` - a string registrada será partida nos caracteres de novas linhas, e todos os caracteres serão passados inalterados
  - `ascii` - a string registrada será partida nos caracteres de novas linhas, e qualquer caractere ASCII de 7 bits não imprimível será escapado
  - `no-ctrl` - a string registrada será partida nos caracteres de novas linhas, e qualquer caractere não imprimível será escapado
  - `raw` - todos os caracteres são passados ao registrador do sistema logger inalterados, sem separação novas linhas (idêntico ao PHP antes do 7.3)
  Esta configuração irá afetar o registro através de error_log definido para "syslog" e chamadas a syslog().

  > Nota:

  > O tipo de filtro `raw` está disponível a partir do PHP 7.3.8 e do PHP 7.4.0.

  Esta diretiva não é suportada no Windows.
`syslog.ident` string

  Especifica a string de identificação que é anexada a todas as mensagens. Somente é efetivo se error_log estiver definido como "syslog".

# Constantes predefinidas

As constantes abaixo estão sempre disponíveis como parte do núcleo do PHP.

As constantes a seguir (seus valores numéricos ou seus nomes simbólicos) são usadas como máscaras de bits para especificar que erros devem ser reportados. É possível usar operadores binários para combinar estes valores ou mascarar certos tipos de erro.

Dica

Os nomes destas constantes podem ser usados no php.ini, no lugar de valores numéricos puros aos quais elas correspondem. Entretanto, apenas os operadores `|`, `~`, `^`, `!` e `&` são compreendidos dentro do php.ini.

Aviso

Não é possível usar os nomes simbólicos fora do PHP. Por exemplo, no httpd.conf, deve ser usado o valor da máscara de bits computada.

`E_ERROR` (int)
  Erros fatais em tempo de execução. Indicam erros a partir dos quais não é possível retomar a execução, como problema de alocação de memória por exemplo. A execução do script é terminada. Valor da constante: `1`
`E_WARNING` (int)
  Alertas em tempo de executação (erros não fatais). A execução do script não é terminada. Valor da constante: `2`
`E_PARSE` (int)
  Erro de análise em tempo de compilação. Erros de análise somente devem ser gerados pelo analisador. Valor da constante: `4`
`E_NOTICE` (int)
  Avisos em tempo de execução. Indicam que o script encontrou algo que pode indicar um erro, mas também pode acontecer no curso normal de execução de um script. Valor da constante: `8`
`E_CORE_ERROR` (int)
  Erros fatais que ocorrem durante a inicialização do PHP. É como um `E_ERROR`, exceto por ser gerado pelo núcleo do PHP. Valor da constante: `16`
`E_CORE_WARNING` (int)
  Alertas (erros não fatais) que ocorrem na inicialização do PHP. É como um `E_WARNING`, exceto por ser gerado pelo núcleo do PHP. Valor da constante: `32`
`E_COMPILE_ERROR` (int)
  Erros fatais em tempo de compilação. É como um `E_ERROR`, exceto por ser gerado pelo mecanismo de scripts Zend. Valor da constante: `64`
`E_COMPILE_WARNING` (int)
  Alertas em tempo de compilação (erros não fatais). É como um `E_WARNING`, exceto por ser gerado pelo mecanismo de scripts Zend. Valor da constante: `128`
`E_DEPRECATED` (int)
  Avisos de descontinuação em tempo de execução. Habilite para receber alertas sobre código que não funcionará em versões futuras. Valor da constante: `8192`
`E_USER_ERROR` (int)
  Mensagem de erro gerada pelo usuário. É como um `E_ERROR`, exceto por ser gerada no código PHP através do uso da função trigger_error(). Valor da constante: `256`
  Aviso

  O uso desta constante com trigger_error() foi descontinuado a partir do PHP 8.4.0. É recomendado, alternativamente, fazer uso de `throw` com uma Exception ou chamar exit().

`E_USER_WARNING` (int)
  Mensagem de alerta gerada pelo usuário. É como um `E_WARNING`, exceto por ser gerada no código PHP através do uso da função trigger_error(). Valor da constante: `512`
`E_USER_NOTICE` (int)
  Mensagem de aviso gerada pelo usuário. É como um `E_NOTICE`, exceto por ser gerada no código PHP através do uso da função trigger_error(). Valor da constante: `1024`
`E_USER_DEPRECATED` (int)
  Mensagem de descontinuação gerada pelo usuário. É como `E_DEPRECATED`, exceto por ser gerada nop código PHP através do uso da função trigger_error(). Valor da constante: `16384`
`E_STRICT` (int)
  Sugestões em tempo de execução emitidas pelo PHP sobre o código executado para assegurar compatibilidade com versões futuras. Valor da constante: `2048`
  Aviso

  Este nível de erro não é utilizado e foi descontinuado a partir do PHP 8.4.0.

`E_RECOVERABLE_ERROR` (int)
  "Exceções" legadas do mecanismo, que correspondem a um erro fatal capturável. Parecida com Error mas precisam ser capturadas através de um manipulador de erro definido pelo usuário (consulte set_error_handler()). Se não tratado, se comporta como `E_ERROR`. Valor da constante: `4096`

  > Nota: Este nível de erro está efetivamente sem uso, o único caso onde pode acontecer é na falha ao interpretar um object como um bool. Isto só pode acontecer para objetos internos. O exemplo mais comum, antes do PHP 8.4.0, é usar uma instância de GMP em uma condicional.

`E_ALL` (int)
  Máscara de bits que contém todos os erros, alertas e avisos. Valor da constante: `30719`
  Aviso

  Antes do PHP 8.4, o valor da constante era `32767`.

# Exemplos

Pode-se ver abaixo um exemplo de uso das capacidades de gerenciamento de erros no PHP. Define-se uma função de gerenciamento de erros que registra as informações dentro de um arquivo (usando um formato XML), e envia um e-mail ao desenvolvador se um erro crítico na lógica acontecer.

Exemplo #1 Usando gerenciamento de erro em um script

    <?php
    // fazendo o próprio gerenciamento de erro
    error_reporting(0);

    // função de gerenciamento de erro definida pelo usuário
    function userErrorHandler($errno, $errmsg, $filename, $linenum, $vars)
    {
        // horário do erro
        $dt = date("Y-m-d H:i:s (T)");

        // Define um array associativo de strings de erro.
        // Na realidade, as únicas entradas que devem ser
        // consideradas são E_WARNING, E_NOTICE, E_USER_ERROR,
        // E_USER_WARNING e E_USER_NOTICE
        $errortype = array (
                    E_ERROR              => 'Erro',
                    E_WARNING            => 'Alerta',
                    E_PARSE              => 'Erro de Interpretação',
                    E_NOTICE             => 'Nota',
                    E_CORE_ERROR         => 'Erro de Núcleo',
                    E_CORE_WARNING       => 'Alerta de Núcleo',
                    E_COMPILE_ERROR      => 'Erro de Compilação',
                    E_COMPILE_WARNING    => 'Alerta de Compilação',
                    E_USER_ERROR         => 'Erro de Usuário',
                    E_USER_WARNING       => 'Alerta de Usuário',
                    E_USER_NOTICE        => 'Nota de Usuário',
                    E_STRICT             => 'Nota em Tempo de Execução',
                    E_RECOVERABLE_ERROR  => 'Erro Fatal Recuperável'
                    );
        // conjunto de erros para os quais um rastreamento de variáveis será gravado
        $user_errors = array(E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE);

        $err = "<errorentry>\n";
        $err .= "\t<datetime>" . $dt . "</datetime>\n";
        $err .= "\t<errornum>" . $errno . "</errornum>\n";
        $err .= "\t<errortype>" . $errortype[$errno] . "</errortype>\n";
        $err .= "\t<errormsg>" . $errmsg . "</errormsg>\n";
        $err .= "\t<scriptname>" . $filename . "</scriptname>\n";
        $err .= "\t<scriptlinenum>" . $linenum . "</scriptlinenum>\n";

        if (in_array($errno, $user_errors)) {
            $err .= "\t<vartrace>" . wddx_serialize_value($vars, "Variáveis") . "</vartrace>\n";
        }
        $err .= "</errorentry>\n\n";

        // para testes:
        // echo $err;

        // grava no registro de erros, e envia e-mail se houver um erro crítico
        error_log($err, 3, "/usr/local/php/error.log");
        if ($errno == E_USER_ERROR) {
            mail("phpdev@example.com", "Critical User Error", $err);
        }
    }

    function distance($vect1, $vect2)
    {
        if (!is_array($vect1) || !is_array($vect2)) {
            trigger_error("Parâmetros incorretos, arrays esperados", E_USER_ERROR);
            return NULL;
        }

        if (count($vect1) != count($vect2)) {
            trigger_error("Vetores devem ser do mesmo tamanho", E_USER_ERROR);
            return NULL;
        }

        for ($i=0; $i<count($vect1); $i++) {
            $c1 = $vect1[$i]; $c2 = $vect2[$i];
            $d = 0.0;
            if (!is_numeric($c1)) {
                trigger_error("Coordenada $i no vetor 1 não é um número, usando zero",
                                E_USER_WARNING);
                $c1 = 0.0;
            }
            if (!is_numeric($c2)) {
                trigger_error("Coordenada $i no vetor 2 não é um número, usando zero",
                                E_USER_WARNING);
                $c2 = 0.0;
            }
            $d += $c2*$c2 - $c1*$c1;
        }
        return sqrt($d);
    }

    $old_error_handler = set_error_handler("userErrorHandler");

    // constante não definida, gera um alerta
    $t = I_AM_NOT_DEFINED;

    // define alguns "vetores"
    $a = array(2, 3, "foo");
    $b = array(5.5, 4.3, -1.6);
    $c = array(1, -3);

    // gera um erro de usuário
    $t1 = distance($c, $b) . "\n";

    // gera um outro erro de usuário
    $t2 = distance($b, "eu não sou um array") . "\n";

    // gera um alerta
    $t3 = distance($a, $b) . "\n";

    ?>

# Funções para Manuseamento de Erros

# Veja Também

Veja também syslog().

# debug_backtrace

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

debug_backtrace — Gera uma rastreamento retroativo

### Descrição

function debug_backtrace(int `$options` = `DEBUG_BACKTRACE_PROVIDE_OBJECT`, int `$limit` = 0): array

debug_backtrace() gera um rastreamento retroativo do PHP.

### Parâmetros

`options`

  Este parâmetro é uma máscara de bits para as seguintes opções:

  Opções de debug_backtrace()
  DEBUG_BACKTRACE_PROVIDE_OBJECT | Define se o índice "object" deve ou não ser preenchido.
  DEBUG_BACKTRACE_IGNORE_ARGS | Define se o índice "args" deve ou não ser omitido, e consequentemente todos os argumentos de métodos e funções, para economizar memória.

  > Nota:

  > Existem quatro combinações possíveis:

  > Opções de debug_backtrace()
  > `debug_backtrace()` | Preenche ambos os índices
  > `debug_backtrace(DEBUG_BACKTRACE_PROVIDE_OBJECT)`
  > `debug_backtrace(~DEBUG_BACKTRACE_PROVIDE_OBJECT)` | Omite o índice `"object"` e preenche o índice `"args"`.
  > `debug_backtrace(0)`
  > `debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS)` | Omite ambos os índices `"object"` e `"args"`.
  > `debug_backtrace(~DEBUG_BACKTRACE_PROVIDE_OBJECT | DEBUG_BACKTRACE_IGNORE_ARGS)`
  > `debug_backtrace(DEBUG_BACKTRACE_PROVIDE_OBJECT|DEBUG_BACKTRACE_IGNORE_ARGS)` | Preenche o índice `"object"` e omite o índice `"args"`.

`limit`

  Este parâmetro pode ser usado para limitar o número de estruturas de pilha retornados. Por padrão (`limit`=`0`) todas as estruturas são retornadas.

### Valor Retornado

Retorna um array de arrays associativos. Os elementos possíveis retornados são os seguintes:

Elementos possíveis retornados de debug_backtrace()
Nome | Tipo | Descrição
--- | --- | ---
function | string | O nome da função atual. Consulte também __FUNCTION__.
line | int | O número da linha atual. Consulte também __LINE__.
file | string | O nome do arquivo atual. Consulte também __FILE__.
class | string | O nome da classe atual. Consulte também __CLASS__
object | object | O objeto atual de `DEBUG_BACKTRACE_PROVIDE_OBJECT` for informada.
type | string | O tipo de chamada atual. Se for chamada de método, "->" é retornado. Se for chamada de método estático, "::" é retornado. Se for chamada de função, nada é retornado.
args | array | Se for dentro de uma função, isto lista os arumentos da função. Se for dentro de um arquivo incluído, isto lista o nome do arquivo incluído. A menos que `DEBUG_BACKTRACE_IGNORE_ARGS` seja informada.

### Exemplos

Exemplo #1 Exemplo de debug_backtrace()

    <?php
    // filename: /tmp/a.php

    function a_test($str)
    {
        echo "\nHi: $str";
        var_dump(debug_backtrace());
    }

    a_test('friend');
    ?>

    <?php
    // filename: /tmp/b.php
    include_once '/tmp/a.php';
    ?>

Resultados similares ao seguinte ao executar /tmp/b.php:

    Hi: friend
    array(2) {
    [0]=>
    array(4) {
        ["file"] => string(10) "/tmp/a.php"
        ["line"] => int(10)
        ["function"] => string(6) "a_test"
        ["args"]=>
        array(1) {
          [0] => &string(6) "friend"
        }
    }
    [1]=>
    array(4) {
        ["file"] => string(10) "/tmp/b.php"
        ["line"] => int(2)
        ["args"] =>
        array(1) {
          [0] => string(10) "/tmp/a.php"
        }
        ["function"] => string(12) "include_once"
      }
    }

### Veja Também

- trigger_error() - Gera uma mensagem a nível de usuário de erro/alerta/nota
- debug_print_backtrace() - Mostra um rastreamento retroativo

# debug_print_backtrace

(PHP 5, PHP 7, PHP 8)

debug_print_backtrace — Mostra um rastreamento retroativo

### Descrição

function debug_print_backtrace(int `$options` = 0, int `$limit` = 0): void

A função debug_print_backtrace() mostra um rastreamento retroativo do PHP. Ela mostra as chamadas de função, arquivos incluídos por include ou requeridos por require, e resultados de avaliações de eval().

### Parâmetros

`options`

  Este parâmetro é uma máscara de bits para as opções a seguir:

  Opções de debug_print_backtrace()
  DEBUG_BACKTRACE_IGNORE_ARGS | Omitir os índices de "args", e portanto todos os argumentos de funções/métodos, para economizar memória.

`limit`

  Este parâmetro pode ser usado para limitar o número de seções de pilha mostradas. Por padrão (`limit`=`0`) ela mostra todas as seções da pilha.

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de debug_print_backtrace()

    <?php
    // arquivo include.php

    function a() {
        b();
    }

    function b() {
        c();
    }

    function c(){
        debug_print_backtrace();
    }

    a();

    ?>

    <?php
    // arquivo test.php
    // este é o arquivo que deve ser executado

    include 'include.php';
    ?>

O exemplo acima produzirá algo semelhante a:

    #0  c() called at [/tmp/include.php:10]
    #1  b() called at [/tmp/include.php:6]
    #2  a() called at [/tmp/include.php:17]
    #3  include(/tmp/include.php) called at [/tmp/test.php:3]

### Veja Também

- debug_backtrace() - Gera uma rastreamento retroativo

# error_clear_last

(PHP 7, PHP 8)

error_clear_last — Limpa o erro mais recente

### Descrição

function error_clear_last(): void

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Limpa o erro mais recente, fazendo com que não seja possível recuperá-los com error_get_last().

### Exemplos

Exemplo #1 Um exemplo de error_clear_last()

    <?php
    var_dump(error_get_last());
    error_clear_last();
    var_dump(error_get_last());

    @$a = $b;

    var_dump(error_get_last());
    error_clear_last();
    var_dump(error_get_last());
    ?>

O exemplo acima produzirá algo semelhante a:

    NULL
    NULL
    array(4) {
      ["type"]=>
      int(8)
      ["message"]=>
      string(21) "Undefined variable: b"
      ["file"]=>
      string(9) "%s"
      ["line"]=>
      int(6)
    }
    NULL

### Veja Também

- Constantes de erro

# error_get_last

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

error_get_last — Obtém o último erro ocorrido

### Descrição

function error_get_last(): ?array

Obtém informações sobre o último erro que ocorreu.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array associativo que descreve o último erro com as chaves "type", "message", "file" e "line". Se o erro foi causado por uma função interna do PHP, então a "message" começa com o nome da função. Retorna `null` se ainda não houve erro.

### Exemplos

Exemplo #1 Um exemplo de error_get_last()

    <?php
    echo $a;
    print_r(error_get_last());
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [type] => 8
        [message] => Undefined variable: a
        [file] => C:\WWW\index.php
        [line] => 2
    )

### Veja Também

- Constantes de erro
- Variável $php_errormsg
- error_clear_last() - Limpa o erro mais recente
- Diretiva `display_errors`
- Diretiva `html_errors`
- Diretiva `xmlrpc_errors`

# error_log

(PHP 4, PHP 5, PHP 7, PHP 8)

error_log — Envia uma mensagem de erro para as rotinas de tratamento de erros definidas

### Descrição

function error_log(
string `$message`,
int `$message_type` = 0,
?string `$destination` = `null`,
?string `$additional_headers` = `null`
): bool

Envia uma mensagem de erro para o registro de erros do servidor web ou para um arquivo.

### Parâmetros

`message`

  A mensagem de erro que deve ser registrada.

`message_type`

  Indica para onde o erro deve ser direcionado. Os possíveis tipos de mensagem são os seguintes:

  Tipos de logs de error_log()
  0 | `message` é enviado para sistema de logs do PHP, usando o mecanismo de log do sistema operacional ou um arquivo, dependendo do que a diretiva de configuração error_log estiver definida. Esta é a opção padrão.
  1 | `message` é enviado por e-mail para o endereço no parâmetro `destination`. Este é o único tipo de mensagem em que o quarto parâmetro, `additional_headers`, é utilizado.
  2 | Não é mais uma opção.
  3 | `message` é adicionada ao arquivo `destination`. Uma nova linha não é automaticamente adicionada ao final da string `message`.
  4 | `message` é enviado diretamente para o manipulador de log do SAPI.

`destination`

  O destino. Seu significado depende do parâmetro `message_type`, conforme descrito acima.

`additional_headers`

  Os cabeçalhos adicionais. É usado quando o parâmetro `message_type` está definido como `1`. Este tipo de mensagem usa a mesma função interna que mail() utiliza.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha. Se `message_type` for zero, esta função sempre retorna `true`, independentemente de o erro poder ser registrado ou não.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `destination` e `additional_headers` agora permitem null.

### Exemplos

Exemplo #1 Exemplos error_log()

    <?php
    // Envia uma notificação através do registro do servidor se não conseguirmos
    // conectar ao banco de dados.
    if (!Ora_Logon($username, $password)) {
        error_log("Banco de dados Oracle não disponível!", 0);
    }

    // Notificar o administrador por e-mail se ficarmos sem FOO
    if (!($foo = allocate_new_foo())) {
        error_log("Grande problema, estamos sem FOOs!", 1,
                   "operator@example.com");
    }

    // Outra forma de chamar error_log():
    error_log("Você cometeu um erro!", 3, "/var/tmp/my-errors.log");
    ?>

### Notas

Aviso

error_log() não é seguro para binários. `message` será truncado pelo caractere nulo.

Dica

`message` não deve conter o caractere nulo. Observe que `message` pode ser enviado para arquivo, e-mail, syslog, etc. Use a função apropriada de conversão/escape, como base64_encode(), rawurlencode() ou addslashes() antes de chamar error_log().

# error_reporting

(PHP 4, PHP 5, PHP 7, PHP 8)

error_reporting — Define quais erros do PHP são relatados

### Descrição

function error_reporting(?int `$error_level` = `null`): int

A função error_reporting() define a diretiva error_reporting em tempo de execução. O PHP possui muitos níveis de erros, e o uso desta função define esse nível para a duração (tempo de execução) do seu script. Se o parâmetro opcional `error_level` não for definido, a função error_reporting() retornará apenas o nível de relatório de erros atual.

### Parâmetros

`error_level`

  O novo nível de error_reporting. Pode ser uma máscara de bits ou constantes nomeadas. É altamente recomendado o uso de constantes nomeadas para garantir compatibilidade com futuras versões. Conforme são adicionados níveis de erro, o intervalo de inteiros aumenta, então os níveis de erro baseados em inteiros mais antigos nem sempre se comportarão como esperado.

  As constantes de nível de erro disponíveis e os significados reais desses níveis de erro são descritos nas constantes predefinidas.

### Valor Retornado

Retorna o nível de error_reporting antes que ele seja alterado para `error_level`.

> Nota: O operador de controle de erro `@` altera o `error_level` durante o tratamento de erros.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `error_level` agora permite null.

### Exemplos

Exemplo #1 Exemplo error_reporting()

    <?php

    // Desativar todos os relatórios de erros
    error_reporting(0);

    // Relatar erros simples durante a execução
    error_reporting(E_ERROR | E_WARNING | E_PARSE);

    // Relatar E_NOTICE também pode ser útil (para relatar variáveis não inicializadas
    // ou capturar erros de digitação nos nomes das variáveis...)
    error_reporting(E_ERROR | E_WARNING | E_PARSE | E_NOTICE);

    // Relatar todos os erros, exceto E_NOTICE
    error_reporting(E_ALL & ~E_NOTICE);

    // Relatar todos os erros do PHP
    error_reporting(E_ALL);

    // Relatar todos os erros do PHP
    error_reporting(-1);

    // O mesmo que error_reporting(E_ALL);
    ini_set('error_reporting', E_ALL);

    ?>

### Notas

Dica

Passar o valor `-1` mostrará todos os erros possíveis, mesmo quando novos níveis e constantes forem adicionados em futuras versões do PHP. O comportamento é equivalente a passar a constante `E_ALL`.

### Veja Também

- A diretiva display_errors
- A diretiva html_errors
- A diretiva xmlrpc_errors
- O operador error control
- ini_set() - Define o valor de uma opção de configuração

# get_error_handler

(PHP 8 >= 8.5.0)

get_error_handler — Obtém a função de manipulação de erro definida pelo usuário

### Descrição

function get_error_handler(): ?callable

Retorna a função de manipulação de erro atual, se houver.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a função de manipulação de erro atualmente definida (se houver). Se o manipulador interno estiver sendo usado, retorna `null`.

O manipulador retornado é o valor chamável exato que foi passado a set_error_handler() para defini-lo.

### Exemplos

Exemplo #1 Exemplo de get_error_handler()

    <?php

    $handler = function (int $errno, string $errstr, ?string $errfile, ?int $errline) {
         echo "Erro: " . $errstr . "\n";
    };

    var_dump(get_error_handler()); // NULL

    set_error_handler($handler);

    var_dump(get_error_handler() === $handler); // bool(true)

    ?>

### Notas

Dica

Antes do PHP 8.5.0, esta funcionalidade poderia ser fornecida pelo código a seguir:

    <?php
    if (!function_exists('get_error_handler')) {
        function noop_error_handler() {
        }
        function get_error_handler(): ?callable {
            $handler = set_error_handler('noop_error_handler');
            restore_error_handler();
            return $handler;
        }
    }
    ?>

### Veja Também

- error_reporting() - Define quais erros do PHP são relatados
- set_error_handler() - Define uma função de usuário para manipulação de erro
- restore_error_handler() - Restaura a função anterior de gerenciamento de erro
- trigger_error() - Gera uma mensagem a nível de usuário de erro/alerta/nota
- Constantes de nível de erro

# get_exception_handler

(PHP 8 >= 8.5.0)

get_exception_handler — Obtém a função de manipulação de exceção definida pelo usuário

### Descrição

function get_exception_handler(): ?callable

Retorna a função de manipulação de exceção atual, se houver.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a função de manipulação de exceção atualmente definida (se houver). Se nenhum manipulador estiver definido, retorna `null`.

O manipulador retornado é o valor chamável exato que foi passado a set_exception_handler() para defini-lo.

### Exemplos

Exemplo #1 Exemplo de get_exception_handler()

    <?php

    $handler = function (Throwable $ex) {
         echo "Exceção: " . $ex::class . ": " . $ex->getMessage() . "\n";
    };

    var_dump(get_exception_handler()); // NULL

    set_exception_handler($handler);

    var_dump(get_exception_handler() === $handler); // bool(true)

    ?>

### Notas

Dica

Antes do PHP 8.5.0, esta funcionalidade poderia ser fornecida pelo código a seguir:

    <?php
    if (!function_exists('get_exception_handler')) {
        function noop_exception_handler() {
        }
        function get_exception_handler(): ?callable {
            $handler = set_exception_handler('noop_exception_handler');
            restore_exception_handler();
            return $handler;
        }
    }
    ?>

### Veja Também

- set_exception_handler() - Define uma função de manipulação de exceção definida pelo usuário
- restore_exception_handler() - Restaura a função de manipulação de exceção anteriormente definida
- restore_error_handler() - Restaura a função anterior de gerenciamento de erro
- error_reporting() - Define quais erros do PHP são relatados
- Exceções

# restore_error_handler

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

restore_error_handler — Restaura a função anterior de gerenciamento de erro

### Descrição

function restore_error_handler(): true

Usada após mudar a função que gerencia os erros usando set_error_handler(), para reverter para a função anterior (que pode ser a função interna ou outra função definida pelo usuário).

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Sempre retorna `true`.

### Exemplos

Exemplo #1 Exemplo de restore_error_handler()

Decide se unserialize() causou um erro, então restaura o gerenciador de erro original.

    <?php
    function unserialize_handler($errno, $errstr)
    {
        echo "Valor serializado inválido.\n";
    }

    $serialized = 'foo';
    set_error_handler('unserialize_handler');
    $original = unserialize($serialized);
    restore_error_handler();
    ?>

O exemplo acima produzirá:

    Valor serializado inválido.

### Veja Também

- error_reporting() - Define quais erros do PHP são relatados
- set_error_handler() - Define uma função de usuário para manipulação de erro
- get_error_handler() - Obtém a função de manipulação de erro definida pelo usuário
- restore_exception_handler() - Restaura a função de manipulação de exceção anteriormente definida
- trigger_error() - Gera uma mensagem a nível de usuário de erro/alerta/nota

# restore_exception_handler

(PHP 5, PHP 7, PHP 8)

restore_exception_handler — Restaura a função de manipulação de exceção anteriormente definida

### Descrição

function restore_exception_handler(): true

Usada após alteração da função de manipulação de exceção ao usar set_exception_handler(), para reverter ao manipulador de exceção anterior (que pode ser o integrado ou uma função definida pelo usuário).

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Sempre retorna `true`.

### Exemplos

Exemplo #1 Exemplo restore_exception_handler()

    <?php
        function manipulador_excecao_1(Exception $e)
        {
            echo '[' . __FUNCTION__ . '] ' . $e->getMessage();
        }

        function manipulador_excecao_2(Exception $e)
        {
            echo '[' . __FUNCTION__ . '] ' . $e->getMessage();
        }

        set_exception_handler('manipulador_excecao_1');
        set_exception_handler('manipulador_excecao_2');

        restore_exception_handler();

        throw new Exception('Isto dispara o primeiro manipulador de exceção...');
    ?>

O exemplo acima produzirá:

    [manipulador_excecao_1] Isto dispara o primeiro manipulador de exceção...

### Veja Também

- set_exception_handler() - Define uma função de manipulação de exceção definida pelo usuário
- get_exception_handler() - Obtém a função de manipulação de exceção definida pelo usuário
- set_error_handler() - Define uma função de usuário para manipulação de erro
- restore_error_handler() - Restaura a função anterior de gerenciamento de erro
- error_reporting() - Define quais erros do PHP são relatados

# set_error_handler

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

set_error_handler — Define uma função de usuário para manipulação de erro

### Descrição

function set_error_handler(?callable `$callback`, int `$error_levels` = `E_ALL`): ?callable

Define uma função de usuário (`callback`) para lidar com erros em um script.

Esta função pode ser usada para definir manipuladores de erros customizados em tempo de execução, por exemplo em aplicações que precisem limpar arquivos/dados quando um erro crítico ocorrer, ou no disparo de um erro em resposta a certas condições (usando trigger_error()).

É importante ressaltar que o manipulador padrão de erros do PHP é completamente ignorado para os tipos de erro especificados por `error_levels` a menos que a função de retorno devolva `false`. As configurações de error_reporting() não terão efeito e o manipulador de erro será chamado de qualquer maneira - entretanto, ainda será possível ler o valor atual de error_reporting e atuar apropriadamente.

Note também que é responsabilidade do manipulador para a execução do script se for necessário, chamando-se exit(). Se a função de manipulação de erro simplesmente retornar, a execução do script continuará com a declaração seguinte à que causou o erro.

Os seguintes tipos de erro não podem ser manipulados com uma função definida pelo usuário: `E_ERROR`, `E_PARSE`, `E_CORE_ERROR`, `E_CORE_WARNING`, `E_COMPILE_ERROR`, `E_COMPILE_WARNING` independentemente de onde eles surgirem, e a maior parte dos erros `E_STRICT` originados no arquivo onde a função set_error_handler() for chamada.

Se erros ocorrerem antes que o script seja executado (ex.: em envios de arquivos), o manipulador customizado de erros não poderá ser chamado já que ainda não estará registrado nesse momento.

### Parâmetros

`callback`

  Se `null` for passado, o manipulador será redefinido a seu estado padrão. Caso contrário, o manipulador é uma função de retorno com a seguinte assinatura:

  function handler(
  int `$errno`,
  string `$errstr`,
  string `$errfile` = ?,
  int `$errline` = ?,
  array `$errcontext` = ?
  ): bool
  `errno`
    O primeiro parâmetro, `errno`, que conterá o nível do erro, como um inteiro.
  `errstr`
    O segundo parâmetro, `errstr`, que conterá a mensagem de erro, como uma string.
  `errfile`
    Se a função de retorno aceitar um terceiro parâmetro, `errfile`, será passado o nome do arquivo no qual o erro se originou, como uma string.
  `errline`
    Se a função de retorno aceitar um quarto parâmetro, `errline`, será passado o número da linha onde o erro ocorreu, como um inteiro.
  `errcontext`
    Se a função de retorno aceitar um quinto parâmetro, `errcontext`, será passado um array que aponta para a tabela de símbolos ativa no ponto onde o erro ocorreu. Em outras palavras, `errcontext` conterá um array com cada variável existente no escopo em que o erro surgiu. Manipuladores de erro de usuário não devem modificar o contexto de erro.
    Aviso

    Este parâmetro tornou-se DESCONTINUADO a partir do PHP 7.2.0, e foi REMOVIDO a partir do PHP 8.0.0. Se a função definir este parâmetro sem um valor padrão, um erro do tipo "too few arguments" será emitido quando ela for chamada.

  Se a função retornar `false`, o manipulador de erros normal continua.

`error_levels`

  Pode ser usado para mascarar a chamada da função `callback` da mesma forma que a configuração ini error_reporting controla quais erros são mostrados. Sem a definição desta máscara, a função `callback` será chamada para todo erro, indenpendentemente da configuração de error_reporting.

### Valor Retornado

Retorna o manipulador de erro anterior (se existente) como um callable. Se o manipulador interno for usado, `null` é retornado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `errcontext` foi removido e não mais será passado para chamadas de retorno de usuário.
7.2.0 | `errcontext` foi descontinuado. O uso deste parâmetro agora emite uma nota `E_DEPRECATED`.

### Exemplos

Exemplo #1 Manipulação de erro com set_error_handler() e trigger_error()

O exemplo abaixo mostra a manipulação de exceções internas através de disparo de erros e uso de função definida pelo usuário:

    <?php
    // função de manipulação de erro
    function myErrorHandler($errno, $errstr, $errfile, $errline)
    {
        if (!(error_reporting() & $errno)) {
            // Este código de erro não está incluído em error_reporting, então será
            // passado ao manipulador padrão de erros do PHP
            return false;
        }

        // $errstr pode precisar de escape:
        $errstr = htmlspecialchars($errstr);

        switch ($errno) {
        case E_USER_ERROR:
            echo "<b>Meu ERRO</b> [$errno] $errstr<br />\n";
            echo "  Erro fatal na linha $errline no arquivo $errfile";
            echo ", PHP " . PHP_VERSION . " (" . PHP_OS . ")<br />\n";
            echo "Abortando...<br />\n";
            exit(1);

        case E_USER_WARNING:
            echo "<b>Meu ALERTA</b> [$errno] $errstr<br />\n";
            break;

        case E_USER_NOTICE:
            echo "<b>Minha NOTA</b> [$errno] $errstr<br />\n";
            break;

        default:
            echo "Tipo de erro desconhecido: [$errno] $errstr<br />\n";
            break;
        }

        /* Não executa o manipulador interno do PHP */
        return true;
    }

    // função para testar a manipulação de erro
    function scale_by_log($vect, $scale)
    {
        if (!is_numeric($scale) || $scale <= 0) {
            trigger_error("log(x) para x <= 0 é indefinido, foi usado: escala = $scale", E_USER_ERROR);
        }

        if (!is_array($vect)) {
            trigger_error("Vetor de entrada incorreto, esperado array de valores", E_USER_WARNING);
            return null;
        }

        $temp = array();
        foreach($vect as $pos => $value) {
            if (!is_numeric($value)) {
                trigger_error("Valor na posição $pos não é um número, usando 0 (zero)", E_USER_NOTICE);
                $value = 0;
            }
            $temp[$pos] = log($scale) * $value;
        }

        return $temp;
    }

    // define para o manipulador de erro de usuário
    $old_error_handler = set_error_handler("myErrorHandler");

    // dispara alguns erros, primeiro define um array misto com um item não numérico
    echo "vetor a\n";
    $a = array(2, 3, "foo", 5.5, 43.3, 21.11);
    print_r($a);

    // agora gera um segundo array
    echo "----\nvetor b - uma nota (b = log(PI) * a)\n";
    /* Valor na posição $pos não é um número, usando 0 (zero) */
    $b = scale_by_log($a, M_PI);
    print_r($b);

    // isto é um problema, passando uma string ao invés de um array
    echo "----\nvetor c - um alerta\n";
    /* Vetor de entrada incorreto, esperado array de valores */
    $c = scale_by_log("not array", 2.3);
    var_dump($c); // NULL

    // aqui um erro crítico, log de zero ou número negativo não é definido
    echo "----\nvetor d - erro fatal\n";
    /* log(x) para x <= 0 é indefinido, foi usado: escala = $scale" */
    $d = scale_by_log($a, -2.5);
    var_dump($d); // Nunca alcançado
    ?>

O exemplo acima produzirá algo semelhante a:

    vetor a
    Array
    (
        [0] => 2
        [1] => 3
        [2] => foo
        [3] => 5.5
        [4] => 43.3
        [5] => 21.11
    )
    ----
    vetor b - uma nota (b = log(PI) * a)
    <b>Minha NOTA</b> [1024] Valor na posição 2 não é um número, usando 0 (zero)<br />
    Array
    (
        [0] => 2.2894597716988
        [1] => 3.4341896575482
        [2] => 0
        [3] => 6.2960143721717
        [4] => 49.566804057279
        [5] => 24.165247890281
    )
    ----
    vetor c - um alerta
    <b>Meu ALERTA</b> [512] Vetor de entrada incorreto, esperado array de valores<br />
    NULL
    ----
    vetor d - erro fatal
    <b>Meu ERRO</b> [256] log(x) para x <= 0 é indefinido, foi usado: escala = -2.5<br />
      Erro fatal na linha 35 no arquivo trigger_error.php, PHP 5.2.1 (FreeBSD)<br />
    Abortando...<br />

### Veja Também

- ErrorException
- error_reporting() - Define quais erros do PHP são relatados
- restore_error_handler() - Restaura a função anterior de gerenciamento de erro
- get_error_handler() - Obtém a função de manipulação de erro definida pelo usuário
- trigger_error() - Gera uma mensagem a nível de usuário de erro/alerta/nota
- Constantes de nível de erro

# set_exception_handler

(PHP 5, PHP 7, PHP 8)

set_exception_handler — Define uma função de manipulação de exceção definida pelo usuário

### Descrição

function set_exception_handler(?callable `$callback`): ?callable

Define o manipulador de exceção padrão se uma exceção não for capturada dentro de um bloco try/catch. A execução irá parar após a função definida no parâmetro `callback` for chamada.

### Parâmetros

`callback`

  A função a ser chamada quando uma exceção não capturada ocorrer. Esta função de manipulação precisa aceitar um parâmetro, que será o objeto Throwable que foi lançado. Tanto Error quanto Exception implementam a interface Throwable. Esta é a assinatura do manipulador:

  function handler(Throwable `$ex`): void

  `null` pode ser passado no lugar, para redefinir este manipulador ao seu estado inicial.

### Valor Retornado

Retorna o manipulador de exceção anteriormente definido, ou `null` em caso de erro. Se nenhum manipulador anterior estava definido, `null` também é retornado.

### Exemplos

Exemplo #1 Exemplo de set_exception_handler()

    <?php
    function exception_handler(Throwable $exception) {
      echo "Exceção não capturada: " , $exception->getMessage(), "\n";
    }

    set_exception_handler('exception_handler');

    throw new Exception('Exceção Não Capturada');
    echo "Não Executado\n";
    ?>

### Veja Também

- get_exception_handler() - Obtém a função de manipulação de exceção definida pelo usuário
- restore_exception_handler() - Restaura a função de manipulação de exceção anteriormente definida
- restore_error_handler() - Restaura a função anterior de gerenciamento de erro
- error_reporting() - Define quais erros do PHP são relatados
- Exceções

# trigger_error

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

trigger_error — Gera uma mensagem a nível de usuário de erro/alerta/nota

### Descrição

function trigger_error(string `$message`, int `$error_level` = `E_USER_NOTICE`): true

Usado para disparar uma condição de erro, pode ser usado em conjunto com o gerenciador de erro interno, ou com uma função definida pelo usuário que tenha sido definida como novo gerenciador de erro (set_error_handler()).

Esta função é útil quando for necessário gerar uma resposta em particular a uma exceção em tempo de execução.

### Parâmetros

`message`

  A mensagem de erro designada para este erro. É limitada a 1024 bytes em tamanho. Quaisquer caracteres adicionais além de 1024 bytes serão truncados.

`error_level`

  O tipo de erro designado para este erro. Funciona apenas com a família de constantes `E_USER_*`, e o padrão é `E_USER_NOTICE`.

  Aviso

  Passar `E_USER_ERROR` como o `error_level` agora foi descontinuado. Alternativamente, uma Exception pode ser lançada ou exit() pode ser chamada.

### Valor Retornado

Sempre retorna `true`.

### Erros/Exceções

Esta função lança uma exceção ValueError se `error_level` não for uma das constantes `E_USER_ERROR`, `E_USER_WARNING`, `E_USER_NOTICE` ou `E_USER_DEPRECATED`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Passar `E_USER_ERROR` como `error_level` agora foi descontinuado. Alternativamente, uma Exception pode ser lançada ou exit() pode ser chamada.
8.4.0 | A função agora tem um tipo de retorno true ao invés de bool.
8.0.0 | A função agora lança uma exceção ValueError se um `error_level` inválido for especificado. Anteriormente, retornava `false`.

### Exemplos

Exemplo #1 Exemplo de trigger_error()

Consulte set_error_handler() para um exemplo mais extensivo.

    <?php
    $password = $_POST['password'] ?? '';
    if ($password === '') {
        trigger_error("Usar uma senha vazia não é seguro", E_USER_WARNING);
    }
    $hash = password_hash($password, PASSWORD_DEFAULT);
    ?>

### Notas

Aviso

As entidades HTML contidas no parâmetro `message` não são escapadas. Utilize htmlentities() na mensagem se for necessário exibir o erro em um navegador.

### Veja Também

- error_reporting() - Define quais erros do PHP são relatados
- set_error_handler() - Define uma função de usuário para manipulação de erro
- restore_error_handler() - Restaura a função anterior de gerenciamento de erro
- As constantes de nível de erro
- O atributo Deprecated

# user_error

(PHP 4, PHP 5, PHP 7, PHP 8)

user_error — Sinônimo de trigger_error()

### Descrição

Esta função é um apelido para: trigger_error().

## Índice

- debug_backtrace — Gera uma rastreamento retroativo
- debug_print_backtrace — Mostra um rastreamento retroativo
- error_clear_last — Limpa o erro mais recente
- error_get_last — Obtém o último erro ocorrido
- error_log — Envia uma mensagem de erro para as rotinas de tratamento de erros definidas
- error_reporting — Define quais erros do PHP são relatados
- get_error_handler — Obtém a função de manipulação de erro definida pelo usuário
- get_exception_handler — Obtém a função de manipulação de exceção definida pelo usuário
- restore_error_handler — Restaura a função anterior de gerenciamento de erro
- restore_exception_handler — Restaura a função de manipulação de exceção anteriormente definida
- set_error_handler — Define uma função de usuário para manipulação de erro
- set_exception_handler — Define uma função de manipulação de exceção definida pelo usuário
- trigger_error — Gera uma mensagem a nível de usuário de erro/alerta/nota
- user_error — Sinônimo de trigger_error

- Instalação/Configuração
  - Configurações em Execução
- Constantes predefinidas
- Exemplos
- Funções para Manuseamento de Erros
  - debug_backtrace — Gera uma rastreamento retroativo
  - debug_print_backtrace — Mostra um rastreamento retroativo
  - error_clear_last — Limpa o erro mais recente
  - error_get_last — Obtém o último erro ocorrido
  - error_log — Envia uma mensagem de erro para as rotinas de tratamento de erros definidas
  - error_reporting — Define quais erros do PHP são relatados
  - get_error_handler — Obtém a função de manipulação de erro definida pelo usuário
  - get_exception_handler — Obtém a função de manipulação de exceção definida pelo usuário
  - restore_error_handler — Restaura a função anterior de gerenciamento de erro
  - restore_exception_handler — Restaura a função de manipulação de exceção anteriormente definida
  - set_error_handler — Define uma função de usuário para manipulação de erro
  - set_exception_handler — Define uma função de manipulação de exceção definida pelo usuário
  - trigger_error — Gera uma mensagem a nível de usuário de erro/alerta/nota
  - user_error — Sinônimo de trigger_error

# Interface de função externa

# Introdução

Esta extensão permite o carregamento de bibliotecas compartilhadas (.DLL ou .so), a chamada de funções escritas em C e o acesso à estruturas de dados de C em PHP puro, sem a necessidade de maiores conhecimentos da API de extensões do Zend, e sem a necessidade de aprender uma terceira linguagem "intermediária". A API pública é implementada como uma única classe FFI com diversos métodos estáticos (alguns deles podem ser chamados dinamicamente) e métodos de objetos sobrecarregados, que realizam a interação com os dados em C.

Cuidado

A FFI é perigosa, visto que permite a interface com o sistema em um nível muito baixo. A extensão FFI deve ser usada apenas por desenvolvedores que possuam experiência com C e com as APIs de C utilizadas. Para minimizar o risco, a utilização da API da FFI pode ser restringida com a opção ffi.enable do php.ini.

> Nota: A extensão FFI não torna a API de extensão clássica do PHP obsoleta; ela é apenas fornecida para interface ad-hoc com funções e estruturas de dados em C.

Dica

Atualmente, acessar estruturas de dados com a FFI é significativamente mais lento (aproximadamente 2 vezes) do que acessar arrays e objetos nativos de PHP. Portanto, não faz sentido utilizar a extensão FFI para ganhos de desempenho; entretanto, pode fazer sentido utilizá-la para reduzir o consumo de memória.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução

## Dependências

Esta extensão precisa que a » biblioteca libffi esteja instalada.

## Instalação

Para habilitar a extensão FFI, o PHP precisa ser configurado com --with-ffi.

Usuários do Windows precisam incluir php_ffi.dll no php.ini para habilitar a extensão FFI.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

FFI Opções de Configuração
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
ffi.enable | "preload" | `INI_SYSTEM` |
ffi.preload | "" | `INI_SYSTEM` |

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`ffi.enable` string
  Permite habilitar (`"true"`) ou desabilitar (`"false"`) o uso da API FFI, ou restringi-la apenas à SAPI CLI e arquivos pré-carregados (`"preload"`). As restrições da API FFI afetam apenas a classe FFI, mas não as funções sobrecarregadas dos objetos FFI\CData. Isto significa que é possível criar alguns objetos FFI\CData em arquivos pré-carregados e então usá-los diretamente em scripts PHP.
`ffi.preload` string
  Permite o pré-carregamento de ligações FFI durante a inicialização, o que não é possível com FFI::load() se opcache.preload_user estiver definida. Esta diretiva aceita uma lista delimitada de nomes de arquivos por `DIRECTORY_SEPARATOR`. As ligações pré-carregadas podem ser acessadas chamando FFI::scope().

# Exemplos

## Índice

- Uso básico da FFI
- Funções de retorno PHP
- Um exemplo completo de PHP/FFI/pré-carregamento

## Uso básico da FFI

Antes de mergulhar nos detalhes da API da FFI, seguem abaixo alguns exemplos demonstrando a simplicidade de seu uso para tarefas regulares.

> Nota: Alguns destes exemplos requerem o libc.so.6 e por isso não funcionarão em sistemas onde ele não estiver disponível.

Exemplo #1 Chamando uma função de uma biblioteca compartilhada

    <?php
    // cria o objeto FFI, carregando a libc e exportando a função printf()
    $ffi = FFI::cdef(
        "int printf(const char *format, ...);", // esta é uma declaração normal em C
        "libc.so.6");
    // chama printf() da linguagem C
    $ffi->printf("Olá, %s!\n", "mundo");
    ?>

O exemplo acima produzirá:

    Olá, mundo!

> Nota: Observe que algumas funções de C precisam de convenções específicas de chamada, por exemplo `__fastcall`, `__stdcall` ou `,__vectorcall`.

Exemplo #2 Chamando uma função e retornando uma estrutura através de um argumento

    <?php
    // cria uma ligação a gettimeofday()
    $ffi = FFI::cdef("
        typedef unsigned int time_t;
        typedef unsigned int suseconds_t;

        struct timeval {
            time_t      tv_sec;
            suseconds_t tv_usec;
        };

        struct timezone {
            int tz_minuteswest;
            int tz_dsttime;
        };

        int gettimeofday(struct timeval *tv, struct timezone *tz);
    ", "libc.so.6");
    // cria estrutura de dados em C
    $tv = $ffi->new("struct timeval");
    $tz = $ffi->new("struct timezone");
    // chama a função C gettimeofday()
    var_dump($ffi->gettimeofday(FFI::addr($tv), FFI::addr($tz)));
    // acessa campo da estrutura de dados C
    var_dump($tv->tv_sec);
    // exibe toda a estrutura de dados C
    var_dump($tz);
    ?>

O exemplo acima produzirá algo semelhante a:

    int(0)
    int(1555946835)
    object(FFI\CData:struct timezone)#3 (2) {
      ["tz_minuteswest"]=>
      int(0)
      ["tz_dsttime"]=>
      int(0)
    }

Exemplo #3 Acessando variáveis C existentes

    <?php
    // cria o objeto FFI, carregando a libc e exportando a variável errno
    $ffi = FFI::cdef(
        "int errno;", // esta é uma declaração normal em C
        "libc.so.6");
    // exibe o errno de C
    var_dump($ffi->errno);
    ?>

O exemplo acima produzirá:

    int(0)

Exemplo #4 Criando e modificando variáveis C

    <?php
    // cria uma nova variável int em C
    $x = FFI::new("int");
    var_dump($x->cdata);

    // atribuição simples
    $x->cdata = 5;
    var_dump($x->cdata);

    // atribuição composta
    $x->cdata += 2;
    var_dump($x->cdata);
    ?>

O exemplo acima produzirá:

    int(0)
    int(5)
    int(7)

Exemplo #5 Trabalhando com arrays C

    <?php
    // cria estrutura de dados C
    $a = FFI::new("long[1024]");
    // trabalhando com ela como um array normal do PHP
    for ($i = 0; $i < count($a); $i++) {
        $a[$i] = $i;
    }
    var_dump($a[25]);
    $sum = 0;
    foreach ($a as $n) {
        $sum += $n;
    }
    var_dump($sum);
    var_dump(count($a));
    var_dump(FFI::sizeof($a));
    ?>

O exemplo acima produzirá:

    int(25)
    int(523776)
    int(1024)
    int(8192)

Exemplo #6 Trabalhando com enumerações C

    <?php
    $a = FFI::cdef('typedef enum _zend_ffi_symbol_kind {
        ZEND_FFI_SYM_TYPE,
        ZEND_FFI_SYM_CONST = 2,
        ZEND_FFI_SYM_VAR,
        ZEND_FFI_SYM_FUNC
    } zend_ffi_symbol_kind;
    ');
    var_dump($a->ZEND_FFI_SYM_TYPE);
    var_dump($a->ZEND_FFI_SYM_CONST);
    var_dump($a->ZEND_FFI_SYM_VAR);
    ?>

O exemplo acima produzirá:

    int(0)
    int(2)
    int(3)

## Funções de retorno PHP

É possível atribuir um closure do PHP a uma variável nativa do tipo ponteiro de função ou passá-lo como um argumento de função:

Exemplo #1 Atribuindo um Closure PHP a um ponteiro de função C

    <?php
    $zend = FFI::cdef("
        typedef int (*zend_write_func_t)(const char *str, size_t str_length);
        extern zend_write_func_t zend_write;
    ");

    echo "Olá, Mundo 1!\n";

    $orig_zend_write = clone $zend->zend_write;
    $zend->zend_write = function($str, $len) {
        global $orig_zend_write;
        $orig_zend_write("{\n\t", 3);
        $ret = $orig_zend_write($str, $len);
        $orig_zend_write("}\n", 2);
        return $ret;
    };
    echo "Olá, Mundo 2!\n";
    $zend->zend_write = $orig_zend_write;
    echo "Olá, Mundo 3!\n";
    ?>

O exemplo acima produzirá:

    Olá, Mundo 1!
    {
            Olá, Mundo 2!
    }
    Olá, Mundo 3!

Embora isso funciona, esta funcionalidade não é suportada em todas as plataformas libffi, não é eficiente e apresenta vazamento de recursos ao final da requisição.
Dica

Portanto, é recomendado minimizar o uso de chamadas de retorno do PHP.

## Um exemplo completo de PHP/FFI/pré-carregamento

php.ini

    ffi.enable=preload
    opcache.preload=preload.php

preload.php

    <?php
    FFI::load(__DIR__ . "/dummy.h");
    opcache_compile_file(__DIR__ . "/dummy.php");
    ?>

dummy.h

    #define FFI_SCOPE "DUMMY"
    #define FFI_LIB "libc.so.6"

    int printf(const char *format, ...);

dummy.php

    <?php
    final class Dummy {
        private static $ffi = null;
        function __construct() {
            if (is_null(self::$ffi)) {
                self::$ffi = FFI::scope("DUMMY");
            }
        }
        function printf($format, ...$args) {
           return (int) self::$ffi->printf($format, ...$args);
        }
    }
    ?>

test.php

    <?php
    $d = new Dummy();
    $d->printf("Olá, %s!\n", "mundo");
    ?>

# Interface principal ao código e aos dados em C

(PHP 7 >= 7.4.0, PHP 8)

## Introdução

Os objetos desta classe são criados pelos métodos de construção FFI::cdef(), FFI::load() ou FFI::scope(). Variáveis ​​C definidas são disponibilizadas como propriedades da instância FFI e funções C definidas são disponibilizadas como métodos da instância FFI. Os tipos C declarados podem ser usados ​​para criar novas estruturas de dados C usando FFI::new() e FFI::type().

A análise da definição FFI e o carregamento da biblioteca compartilhada podem levar um tempo significativo. Não é útil fazer isso em cada solicitação HTTP em um ambiente Web. Entretanto, é possível pré-carregar definições e bibliotecas FFI na inicialização do PHP e instanciar objetos FFI quando necessário. Os arquivos de cabeçalho podem ser estendidos com definições especiais de `FFI_SCOPE` (por exemplo, `#define FFI_SCOPE "foo"`; o escopo padrão é "C") e então carregados por FFI::load() durante o pré-carregamento. Isto leva à criação de uma ligação persistente, que estará disponível para todas as solicitações seguintes através de FFI::scope(). Consulte o exemplo completo de PHP/FFI/pré-carregamento para obter detalhes.

É possível pré-carregar mais de um arquivo de cabeçalho C no mesmo escopo.

## Resumo da classe

final class FFI {
/* Constantes */
public const int __BIGGEST_ALIGNMENT__;
/* Métodos */
public static function addr(FFI\CData `&$ptr`): FFI\CData
public static function alignof(FFI\CData|FFI\CType `&$ptr`): int
public static function arrayType(FFI\CType `$type`, array `$dimensions`): FFI\CType
public function cast(FFI\CType|string `$type`, FFI\CData|int|float|bool|null `&$ptr`): ?FFI\CData
public static function cdef(string `$code` = "", ?string `$lib` = `null`): FFI
public static function free(FFI\CData `&$ptr`): void
public static function isNull(FFI\CData `&$ptr`): bool
public static function load(string `$filename`): ?FFI
public static function memcmp(string|FFI\CData `&$ptr1`, string|FFI\CData `&$ptr2`, int `$size`): int
public static function memcpy(FFI\CData `&$to`, FFI\CData|string `&$from`, int `$size`): void
public static function memset(FFI\CData `&$ptr`, int `$value`, int `$size`): void
public function new(FFI\CType|string `$type`, bool `$owned` = `true`, bool `$persistent` = `false`): ?FFI\CData
public static function scope(string `$name`): FFI
public static function sizeof(FFI\CData|FFI\CType `&$ptr`): int
public static function string(FFI\CData `&$ptr`, ?int `$size` = `null`): string
public function type(string `$type`): ?FFI\CType
public static function typeof(FFI\CData `&$ptr`): FFI\CType
}

## Constantes predefinidas

`FFI::__BIGGEST_ALIGNMENT__`

# FFI::addr

(PHP 7 >= 7.4.0, PHP 8)

FFI::addr — Cria um ponteiro não gerenciado para dado C

### Descrição

public static function FFI::addr(FFI\CData `&$ptr`): FFI\CData

Cria um ponteiro não gerenciado para o dado C representado pelo FFI\CData informado. O ponteiro de origem `ptr` precisa sobreviver ao ponteiro resultante. Esta função é útil principalmente para passar argumentos para funções C através de ponteiro.

### Parâmetros

`ptr`
  O identificador do ponteiro para uma estrutura de dado C.

### Valor Retornado

Retorna o objeto FFI\CData recentemente criado.

# FFI::alignof

(PHP 7 >= 7.4.0, PHP 8)

FFI::alignof — Obtém o alinhamento

### Descrição

public static function FFI::alignof(FFI\CData|FFI\CType `&$ptr`): int

Obtém o alinhamento do objeto FFI\CData ou FFI\CType informado.

### Parâmetros

`ptr`
  O identificador do dado ou do tipo C.

### Valor Retornado

Retorna o alinhamento do objeto FFI\CData ou FFI\CType informado.

# FFI::arrayType

(PHP 7 >= 7.4.0, PHP 8)

FFI::arrayType — Constrói dinamicamente um novo array tipo C

### Descrição

public static function FFI::arrayType(FFI\CType `$type`, array `$dimensions`): FFI\CType

Constrói dinamicamente um novo array tipo C com elementos do tipo definido por `type` e dimensões especificadas por `dimensions`. No exemplo a seguir, `$t1` e `$t2` são tipos de array equivalentes:

    <?php
    $t1 = FFI::type("int[2][3]");
    $t2 = FFI::arrayType(FFI::type("int"), [2, 3]);
    ?>

### Parâmetros

`type`
  Uma declaração C válida como uma string ou como uma instância de FFI\CType que já tenha sido criada.
`dimensions`
  As dimensões do tipo como um array.

### Valor Retornado

Retorna o objeto FFI\CType recentemente criado.

# FFI::cast

(PHP 7 >= 7.4.0, PHP 8)

FFI::cast — Realiza um conversão de tipo C

### Descrição

public function FFI::cast(FFI\CType|string `$type`, FFI\CData|int|float|bool|null `&$ptr`): ?FFI\CData

FFI::cast() cria um novo objeto FFI\CData, que referencia a mesma estrutura de dados C, mas é associado com um tipo diferente. O objeto resultante não detém o dado C, e o ponteiro de origem `ptr` precisa sobreviver ao resultado. O tipo C pode ser especificado como uma string com qualquer declaração de tipo C válida ou como objeto FFI\CType, criado antes. Qualquer tipo declarado para a instância é permitido.

### Parâmetros

`type`
  Uma declaração válida em C como uma string ou uma instância de FFI\CType que já tenha sido criada.
`ptr`
  O identificador do ponteiro para uma estrutura de dados C.

### Valor Retornado

Retorna o objeto FFI\CData recentemente criado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Chamar FFI::cast() estaticamente agora foi descontinuado.

# FFI::cdef

(PHP 7 >= 7.4.0, PHP 8)

FFI::cdef — Cria um novo objeto FFI

### Descrição

public static function FFI::cdef(string `$code` = "", ?string `$lib` = `null`): FFI

Cria um novo objeto FFI.

### Parâmetros

`code`
  Uma string contendo uma sequência de declarações em liguagem C usual (tipos, estruturas, funções, variáveis etc.). Na verdade, esta string pode ser copiada e colada a partir de arquivos de cabeçalho C.

  > Nota: As diretivas de pré-processamento C não são suportadas, ou seja, `#include`, `#define` e macros CPP não funcionam.

`lib`
  O nome de um arquivo de biblioteca compartilhada, a ser carregado e conectado com as definições.

  > Nota: Se `lib` for omitido ou `null`, as plaraformas que suportam `RTLD_DEFAULT` tentarão localizar símbolos declarados em `code` no escopo global normal. Outros sistemas falharão ao tentar resolver estes símbolos.

### Valor Retornado

Retorna o objeto FFI criado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Funções C que retornam `void` irão retornar um tipo null do PHP ao invés de FFI\CType::TYPE_VOID.
8.0.0 | `lib` agora pode ser nulo.

# FFI::free

(PHP 7 >= 7.4.0, PHP 8)

FFI::free — Libera uma estrutura de dados não gerenciada

### Descrição

public static function FFI::free(FFI\CData `&$ptr`): void

Libera manualmente uma estrutura de dados não gerenciada criada anteriormente.

### Parâmetros

`ptr`
  O identificador do ponteiro não gerenciado a um estrutura de dados C.

### Valor Retornado

Nenhum valor é retornado.

# FFI::isNull

(PHP 7 >= 7.4.0, PHP 8)

FFI::isNull — Verifica se um FFI\CData é um ponteiro nulo

### Descrição

public static function FFI::isNull(FFI\CData `&$ptr`): bool

Verifica se um FFI\CData é um ponteiro nulo.

### Parâmetros

`ptr`
  O identificador do ponteiro a uma estrutura de dados C.

### Valor Retornado

Retorna se FFI\CData é um ponteiro nulo.

# FFI::load

(PHP 7 >= 7.4.0, PHP 8)

FFI::load — Carrega declarações C a partir de um arquivo de cabeçalho

### Descrição

public static function FFI::load(string `$filename`): ?FFI

Carrega declarações C a partir de um arquivo de cabeçalho. É possível especificar bibliotecas compartilhadas que devem ser carregadas, usando definições especiais `FFI_LIB` no arquivo de cabeçalho carregado.

### Parâmetros

`filename`
  O nome de um arquivo de cabeçalho C. Diretivas de pré-processamento C não são suportadas, ou seja, `#include`, `#define` e macros CPP não funcionam, exceto para casos especiais listados abaixo. O arquivo de cabeçalho deveria conter uma declaração `#define` para a variável `FFI_SCOPE`, ex.: `#define FFI_SCOPE "MYLIB"`. Refira à introdução desta classe para detalhes. O arquivo de cabeçalho pode conter uma declaração `#define` para a variável `FFI_LIB` para especificar a biblioteca que a ser exposta. Se for uma biblioteca de sistema, apenas o nome é necessário, ex.: `#define FFI_LIB "libc.so.6"`. Se for uma biblioteca customizada, um caminho relativo é necessário, ex.: `#define FFI_LIB "./mylib.so"`.

### Valor Retornado

Retorna o objeto FFI recém criado ou `null` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | FFI::load() agora é permitido em scripts de pré-carregamento quando o usuário de sistema atual é o mesmo que foi definido na diretiva de configuração `opcache.preload_user`.

### Veja Também

- FFI::scope() - Instancia um objeto FFI com declarações C analisadas durante o pré-carregamento

# FFI::memcmp

(PHP 7 >= 7.4.0, PHP 8)

FFI::memcmp — Compara áreas da memória

### Descrição

public static function FFI::memcmp(string|FFI\CData `&$ptr1`, string|FFI\CData `&$ptr2`, int `$size`): int

Compara o número de bytes definido em `size` das áreas de memória `ptr1` e `ptr2`. Ambos `ptr1` e `ptr2` podem ser quaisquer estruturas de dados nativas (FFI\CData) ou strings PHP.

### Parâmetros

`ptr1`
  O início de uma área de memória.
`ptr2`
  O início de outra área de memória.
`size`
  O número de bytes a serem comparados.

### Valor Retornado

Retorna um valor menor que `0` se o conteúdo da área de memória iniciando em `ptr1` for considerado menor que o conteúdo da área de memória iniciando em `ptr2`, um número maior que `0` se o conteúdo da primeira área de memória for considerado maior que o segundo, e `0` se forem iguais.

# FFI::memcpy

(PHP 7 >= 7.4.0, PHP 8)

FFI::memcpy — Copia uma área da memória para outra

### Descrição

public static function FFI::memcpy(FFI\CData `&$to`, FFI\CData|string `&$from`, int `$size`): void

Copia o número de bytes informado em `size` da área de memória `from` para a área de memória `to`.

### Parâmetros

`to`
  O início da área de memória de destino da cópia.
`from`
  O início da área de memória de origem da cópia.
`size`
  O número de bytes a serem copiados.

### Valor Retornado

Nenhum valor é retornado.

# FFI::memset

(PHP 7 >= 7.4.0, PHP 8)

FFI::memset — Preenche uma área de memória

### Descrição

public static function FFI::memset(FFI\CData `&$ptr`, int `$value`, int `$size`): void

Preenche, com o número de bytes informado em `size`, a área de memória apontada por `ptr` com o valor de byte definido por `value`.

### Parâmetros

`ptr`
  O início da área de memória a ser preenchida.
`value`
  O byte para preenchimento.
`size`
  O número de bytes a serem preenchidos.

### Valor Retornado

Nenhum valor é retornado.

# FFI::new

(PHP 7 >= 7.4.0, PHP 8)

FFI::new — Cria uma estrutura de dados C

### Descrição

public function FFI::new(FFI\CType|string `$type`, bool `$owned` = `true`, bool `$persistent` = `false`): ?FFI\CData

Cria uma estrutura de dados nativa do tipo C fornecido. Qualquer tipo declarado para a instância é permitido.

### Parâmetros

`type`
  `type` é uma declaração C válida como uma string ou uma instância de FFI\CType que já tenha sido criada.
`owned`
  Define se serão criados dados próprios (ou seja, gerenciados) ou não gerenciados. Os dados gerenciados residem junto com o objeto FFI\CData retornado e são liberados quando a última referência a esse objeto é liberada pela contagem regular de referências do PHP ou pelo GC. Dados não gerenciados devem ser liberados chamando FFI::free(), quando não forem mais necessários.
`persistent`
  Define se a estrutura de dados C será alocada permanentemente na memória do sistema (usando malloc()) ou na memória de requisição do PHP (usando emalloc()).

### Valor Retornado

Retorna o objeto FFI\CData recém criado ou `null` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Chamar FFI::new() estaticamente agora foi descontinuado.

# FFI::scope

(PHP 7 >= 7.4.0, PHP 8)

FFI::scope — Instancia um objeto FFI com declarações C analisadas durante o pré-carregamento

### Descrição

public static function FFI::scope(string `$name`): FFI

Instancia um objeto FFI com declarações C analisadas durante o pré-carregamento.

O método FFI::scope() é seguro para ser chamado várias vezes para o mesmo escopo. Várias referências ao mesmo escopo podem ser carregadas ao mesmo tempo.

### Parâmetros

`name`
  O nome do escopo definido por uma definição especial `FFI_SCOPE`.

### Valor Retornado

Retorna o objeto FFI recém-criado.

### Veja Também

- FFI::load() - Carrega declarações C a partir de um arquivo de cabeçalho

# FFI::sizeof

(PHP 7 >= 7.4.0, PHP 8)

FFI::sizeof — Obtém o tamanho do dado ou tipo C

### Descrição

public static function FFI::sizeof(FFI\CData|FFI\CType `&$ptr`): int

Retorna o tamanho do objeto FFI\CData ou FFI\CType fornecido.

### Parâmetros

`ptr`
  O identificador do dado ou tipo C.

### Valor Retornado

O tamanho da área de memória apontada por `ptr`.

# FFI::string

(PHP 7 >= 7.4.0, PHP 8)

FFI::string — Cria uma string PHP a partir de uma área de memória

### Descrição

public static function FFI::string(FFI\CData `&$ptr`, ?int `$size` = `null`): string

Cria uma string PHP com o número de bytes informados em `size` a partir da área de memória apontada por `ptr`.

### Parâmetros

`ptr`
  O início da área de memória a partir da qual será criada uma string.
`size`
  O número de bytes a serem copiados para a string. Se `size` for omitido ou `null`, `ptr` deverá ser um array de `char` C terminado em zero.

### Valor Retornado

A string recém-criada do PHP.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `size` agora pode ser nulo; anteriormente seu padrão era `0`.

# FFI::type

(PHP 7 >= 7.4.0, PHP 8)

FFI::type — Cria um objeto FFI\CType a partir de uma declaração C

### Descrição

public function FFI::type(string `$type`): ?FFI\CType

Esta função cria e retorna um objeto FFI\CType para a string fornecida contendo uma declaração de tipo C. Qualquer tipo declarado para a instância é permitido.

### Parâmetros

`type`
  Uma string com uma declaração C válida.

### Valor Retornado

Retorna o objeto FFI\CType recém-criado ou `null` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Chamar FFI::type() estaticamente agora foi descontinuado.

# FFI::typeof

(PHP 7 >= 7.4.0, PHP 8)

FFI::typeof — Obtém o FFI\CType de FFI\CData

### Descrição

public static function FFI::typeof(FFI\CData `&$ptr`): FFI\CType

Obtém o objeto FFI\CType que representa o tipo do objeto FFI\CData fornecido.

### Parâmetros

`ptr`
  O identificador do ponteiro para uma estrutura de dados C.

### Valor Retornado

Retorna o objeto FFI\CType que representa o tipo do objeto FFI\CData fornecido.

## Índice

- FFI::addr — Cria um ponteiro não gerenciado para dado C
- FFI::alignof — Obtém o alinhamento
- FFI::arrayType — Constrói dinamicamente um novo array tipo C
- FFI::cast — Realiza um conversão de tipo C
- FFI::cdef — Cria um novo objeto FFI
- FFI::free — Libera uma estrutura de dados não gerenciada
- FFI::isNull — Verifica se um FFI\CData é um ponteiro nulo
- FFI::load — Carrega declarações C a partir de um arquivo de cabeçalho
- FFI::memcmp — Compara áreas da memória
- FFI::memcpy — Copia uma área da memória para outra
- FFI::memset — Preenche uma área de memória
- FFI::new — Cria uma estrutura de dados C
- FFI::scope — Instancia um objeto FFI com declarações C analisadas durante o pré-carregamento
- FFI::sizeof — Obtém o tamanho do dado ou tipo C
- FFI::string — Cria uma string PHP a partir de uma área de memória
- FFI::type — Cria um objeto FFI\CType a partir de uma declaração C
- FFI::typeof — Obtém o FFI\CType de FFI\CData

# Identificadores de dados em C

(PHP 7 >= 7.4.0, PHP 8)

## Introdução

Objetos FFI\CData podem ser usados de várias maneiras como dados comuns do PHP:

- Dados em C de tipos escalares podem ser lidos e atribuídos através da propriedade $cdata, por exemplo, `$x = FFI::new('int'); $x->cdata = 42;`
- Campos de estruturas e uniões em C podem ser acessados como uma propriedade comum de objeto PHP, por exemplo, `$cdata->field`
- Elementos de array em C podem ser acessados como elementos de array comuns do PHP, por exemplo, `$cdata[$offset]`
- Arrays em C podem ser iterados usando instruções `foreach`.
- Arrays em C podem ser usados como argumentos de count().
- Ponteiros em C podem ser desreferenciados como arrays, por exemplo, `$cdata[0]`
- Ponteiros em C podem ser comparados usando operadores comuns de comparação (`<`, `<=`, `==`, `!=`, `>=`, `>`).
- Ponteiros em C podem ser incrementados e decrementads usando as operações comuns `+`/`-`/ `++`/`--`, por exemplo, `$cdata += 5`
- Ponteiros em C podem ser subtraídos de outros usando operações normais de subtração `-`.
- Ponteiros para funções em C podem ser chamados como closures normais de PHP, por exemplo, `$cdata()`
- Qualquer dado em C pode ser duplicado usando o operador clone, por exemplo, `$cdata2 = clone $cdata;`
- Qualquer dado em C pode ser visualizado usando var_dump(), print_r() etc.
- FFI\CData agora pode ser atribuído a estruturas e campos a partir do PHP 8.3.0.

> Nota: Limitações notáveis são: instâncias FFI\CData não suportam isset(), empty() e unset(); e estruturas e uniões C encapsuladas não implementam Traversable.

## Resumo da classe

namespace FFI;
final class CData {
}

## Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | FFI\CData agora pode ser atribuído a estruturas e campos.

# Identificadores de Tipo em C

(PHP 7 >= 7.4.0, PHP 8)

## Introdução

## Resumo da classe

namespace FFI;
final class CType {
/* Constantes */
public const int TYPE_VOID;
public const int TYPE_FLOAT;
public const int TYPE_DOUBLE;
public const int TYPE_LONGDOUBLE;
public const int TYPE_UINT8;
public const int TYPE_SINT8;
public const int TYPE_UINT16;
public const int TYPE_SINT16;
public const int TYPE_UINT32;
public const int TYPE_SINT32;
public const int TYPE_UINT64;
public const int TYPE_SINT64;
public const int TYPE_ENUM;
public const int TYPE_BOOL;
public const int TYPE_CHAR;
public const int TYPE_POINTER;
public const int TYPE_FUNC;
public const int TYPE_ARRAY;
public const int TYPE_STRUCT;
public const int ATTR_CONST;
public const int ATTR_INCOMPLETE_TAG;
public const int ATTR_VARIADIC;
public const int ATTR_INCOMPLETE_ARRAY;
public const int ATTR_VLA;
public const int ATTR_UNION;
public const int ATTR_PACKED;
public const int ATTR_MS_STRUCT;
public const int ATTR_GCC_STRUCT;
public const int ABI_DEFAULT;
public const int ABI_CDECL;
public const int ABI_FASTCALL;
public const int ABI_THISCALL;
public const int ABI_STDCALL;
public const int ABI_PASCAL;
public const int ABI_REGISTER;
public const int ABI_MS;
public const int ABI_SYSV;
public const int ABI_VECTORCALL;
/* Métodos */
public function getAlignment(): int
public function getArrayElementType(): FFI\CType
public function getArrayLength(): int
public function getAttributes(): int
public function getEnumKind(): int
public function getFuncABI(): int
public function getFuncParameterCount(): int
public function getFuncParameterType(int `$index`): FFI\CType
public function getFuncReturnType(): FFI\CType
public function getKind(): int
public function getName(): string
public function getPointerType(): FFI\CType
public function getSize(): int
public function getStructFieldNames(): array
public function getStructFieldOffset(string `$name`): int
public function getStructFieldType(string `$name`): FFI\CType
}

## Constantes predefinidas

`FFI\CType::TYPE_VOID`
`FFI\CType::TYPE_FLOAT`
`FFI\CType::TYPE_DOUBLE`
`FFI\CType::TYPE_LONGDOUBLE`
`FFI\CType::TYPE_UINT8`
`FFI\CType::TYPE_SINT8`
`FFI\CType::TYPE_UINT16`
`FFI\CType::TYPE_SINT16`
`FFI\CType::TYPE_UINT32`
`FFI\CType::TYPE_SINT32`
`FFI\CType::TYPE_UINT64`
`FFI\CType::TYPE_SINT64`
`FFI\CType::TYPE_ENUM`
`FFI\CType::TYPE_BOOL`
`FFI\CType::TYPE_CHAR`
`FFI\CType::TYPE_POINTER`
`FFI\CType::TYPE_FUNC`
`FFI\CType::TYPE_ARRAY`
`FFI\CType::TYPE_STRUCT`
`FFI\CType::ATTR_CONST`
`FFI\CType::ATTR_INCOMPLETE_TAG`
`FFI\CType::ATTR_VARIADIC`
`FFI\CType::ATTR_INCOMPLETE_ARRAY`
`FFI\CType::ATTR_VLA`
`FFI\CType::ATTR_UNION`
`FFI\CType::ATTR_PACKED`
`FFI\CType::ATTR_MS_STRUCT`
`FFI\CType::ATTR_GCC_STRUCT`
`FFI\CType::ABI_DEFAULT`
`FFI\CType::ABI_CDECL`
`FFI\CType::ABI_FASTCALL`
`FFI\CType::ABI_THISCALL`
`FFI\CType::ABI_STDCALL`
`FFI\CType::ABI_PASCAL`
`FFI\CType::ABI_REGISTER`
`FFI\CType::ABI_MS`
`FFI\CType::ABI_SYSV`
`FFI\CType::ABI_VECTORCALL`

# FFI\CType::getAlignment

(PHP 8 >= 8.1.0)

FFI\CType::getAlignment — Descrição

### Descrição

public function FFI\CType::getAlignment(): int

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# FFI\CType::getArrayElementType

(PHP 8 >= 8.1.0)

FFI\CType::getArrayElementType — Descrição

### Descrição

public function FFI\CType::getArrayElementType(): FFI\CType

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# FFI\CType::getArrayLength

(PHP 8 >= 8.1.0)

FFI\CType::getArrayLength — Descrição

### Descrição

public function FFI\CType::getArrayLength(): int

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# FFI\CType::getAttributes

(PHP 8 >= 8.1.0)

FFI\CType::getAttributes — Descrição

### Descrição

public function FFI\CType::getAttributes(): int

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# FFI\CType::getEnumKind

(PHP 8 >= 8.1.0)

FFI\CType::getEnumKind — Descrição

### Descrição

public function FFI\CType::getEnumKind(): int

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# FFI\CType::getFuncABI

(PHP 8 >= 8.1.0)

FFI\CType::getFuncABI — Descrição

### Descrição

public function FFI\CType::getFuncABI(): int

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# FFI\CType::getFuncParameterCount

(PHP 8 >= 8.1.0)

FFI\CType::getFuncParameterCount — Obtém a contagem de parâmetros de um tipo de função

### Descrição

public function FFI\CType::getFuncParameterCount(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número de parâmetros para o tipo de função subjacente. Se o tipo não for uma função, uma exceção FFI\Exception é lançada.

# FFI\CType::getFuncParameterType

(PHP 8 >= 8.1.0)

FFI\CType::getFuncParameterType — Obtém o tipo de um parâmetro de função

### Descrição

public function FFI\CType::getFuncParameterType(int `$index`): FFI\CType

Retorna o tipo de um parâmetro para o tipo da função subjacente.

### Parâmetros

`index`
  Índice do parâmetro da função, baseado em zero.

### Valor Retornado

Retorna o tipo de um parâmetro para o tipo da função subjacente. Se o tipo subjacente não for uma função, ou se o ínice informado estiver fora do intervalo de parâmetros da função, uma FFI\Exception será lançada.

# FFI\CType::getFuncReturnType

(PHP 8 >= 8.1.0)

FFI\CType::getFuncReturnType — Descrição

### Descrição

public function FFI\CType::getFuncReturnType(): FFI\CType

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# FFI\CType::getKind

(PHP 8 >= 8.1.0)

FFI\CType::getKind — Descrição

### Descrição

public function FFI\CType::getKind(): int

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# FFI\CType::getName

(PHP 7 >= 7.4.0, PHP 8)

FFI\CType::getName — Descrição

### Descrição

public function FFI\CType::getName(): string

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# FFI\CType::getPointerType

(PHP 8 >= 8.1.0)

FFI\CType::getPointerType — Descrição

### Descrição

public function FFI\CType::getPointerType(): FFI\CType

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# FFI\CType::getSize

(PHP 8 >= 8.1.0)

FFI\CType::getSize — Descrição

### Descrição

public function FFI\CType::getSize(): int

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# FFI\CType::getStructFieldNames

(PHP 8 >= 8.1.0)

FFI\CType::getStructFieldNames — Descrição

### Descrição

public function FFI\CType::getStructFieldNames(): array

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# FFI\CType::getStructFieldOffset

(PHP 8 >= 8.1.0)

FFI\CType::getStructFieldOffset — Descrição

### Descrição

public function FFI\CType::getStructFieldOffset(string `$name`): int

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`name`

### Valor Retornado

# FFI\CType::getStructFieldType

(PHP 8 >= 8.1.0)

FFI\CType::getStructFieldType — Descrição

### Descrição

public function FFI\CType::getStructFieldType(string `$name`): FFI\CType

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`name`

### Valor Retornado

## Índice

- FFI\CType::getAlignment — Descrição
- FFI\CType::getArrayElementType — Descrição
- FFI\CType::getArrayLength — Descrição
- FFI\CType::getAttributes — Descrição
- FFI\CType::getEnumKind — Descrição
- FFI\CType::getFuncABI — Descrição
- FFI\CType::getFuncParameterCount — Obtém a contagem de parâmetros de um tipo de função
- FFI\CType::getFuncParameterType — Obtém o tipo de um parâmetro de função
- FFI\CType::getFuncReturnType — Descrição
- FFI\CType::getKind — Descrição
- FFI\CType::getName — Descrição
- FFI\CType::getPointerType — Descrição
- FFI\CType::getSize — Descrição
- FFI\CType::getStructFieldNames — Descrição
- FFI\CType::getStructFieldOffset — Descrição
- FFI\CType::getStructFieldType — Descrição

# Exceções FFI

(PHP 7 >= 7.4.0, PHP 8)

## Introdução

## Resumo da classe

namespace FFI;
class Exception extends Error {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# Exceções do Analisador FFI

(PHP 7 >= 7.4.0, PHP 8)

## Introdução

## Resumo da classe

namespace FFI;
final class ParserException extends FFI\Exception {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
- Exemplos
  - Uso básico da FFI
  - Funções de retorno PHP
  - Um exemplo completo de PHP/FFI/pré-carregamento
- FFI — Interface principal ao código e aos dados em C
  - FFI::addr — Cria um ponteiro não gerenciado para dado C
  - FFI::alignof — Obtém o alinhamento
  - FFI::arrayType — Constrói dinamicamente um novo array tipo C
  - FFI::cast — Realiza um conversão de tipo C
  - FFI::cdef — Cria um novo objeto FFI
  - FFI::free — Libera uma estrutura de dados não gerenciada
  - FFI::isNull — Verifica se um FFI\CData é um ponteiro nulo
  - FFI::load — Carrega declarações C a partir de um arquivo de cabeçalho
  - FFI::memcmp — Compara áreas da memória
  - FFI::memcpy — Copia uma área da memória para outra
  - FFI::memset — Preenche uma área de memória
  - FFI::new — Cria uma estrutura de dados C
  - FFI::scope — Instancia um objeto FFI com declarações C analisadas durante o pré-carregamento
  - FFI::sizeof — Obtém o tamanho do dado ou tipo C
  - FFI::string — Cria uma string PHP a partir de uma área de memória
  - FFI::type — Cria um objeto FFI\CType a partir de uma declaração C
  - FFI::typeof — Obtém o FFI\CType de FFI\CData
- FFI\CData — Identificadores de dados em C
- FFI\CType — Identificadores de Tipo em C
  - FFI\CType::getAlignment — Descrição
  - FFI\CType::getArrayElementType — Descrição
  - FFI\CType::getArrayLength — Descrição
  - FFI\CType::getAttributes — Descrição
  - FFI\CType::getEnumKind — Descrição
  - FFI\CType::getFuncABI — Descrição
  - FFI\CType::getFuncParameterCount — Obtém a contagem de parâmetros de um tipo de função
  - FFI\CType::getFuncParameterType — Obtém o tipo de um parâmetro de função
  - FFI\CType::getFuncReturnType — Descrição
  - FFI\CType::getKind — Descrição
  - FFI\CType::getName — Descrição
  - FFI\CType::getPointerType — Descrição
  - FFI\CType::getSize — Descrição
  - FFI\CType::getStructFieldNames — Descrição
  - FFI\CType::getStructFieldOffset — Descrição
  - FFI\CType::getStructFieldType — Descrição
- FFI\Exception — Exceções FFI
- FFI\ParserException — Exceções do Analisador FFI

# OPcache

# Introdução

OPcache melhora o desempenho do PHP armazenando bytecode de script pré-compilado na memória compartilhada, eliminando assim a necessidade do PHP carregar e analisar scripts em cada solicitação.

Esta extensão é empacotada com o PHP 5.5.0 e posterior, e está » disponível no PECL para PHP versões 5.2, 5.3 e 5.4.

# Instalação/Configuração

## Índice

- Instalação
- Configurações em Execução

## Instalação

OPcache só pode ser compilado como uma extensão compartilhada. Se você desativou a construção de extensões padrão com --disable-all, você deve compilar o PHP com a opção --enable-opcache para que o OPcache esteja disponível.

Uma vez compilado, você pode usar a diretiva de configuração zend_extension para carregar a extensão OPcache no PHP. Isso pode ser feito com `zend_extension=/full/path/to/opcache.so` em plataformas não Windows e `zend_extension=C:\path\to\php_opcache.dll` no Windows.

> Nota: Se você quiser usar o OPcache com » Xdebug, você deve carregar o OPcache antes do Xdebug.

### Configurações recomendadas do php.ini

As seguintes configurações são geralmente recomendadas para fornecer um bom desempenho:

    opcache.memory_consumption=128
    opcache.interned_strings_buffer=8
    opcache.max_accelerated_files=4000
    opcache.revalidate_freq=60
    opcache.fast_shutdown=1 ; prior to PHP 7.2.0
    opcache.enable_cli=1

Você também pode querer considerar desabilitar opcache.save_comments e habilitar opcache.enable_file_override, no entanto, observe que você terá que testar seu código antes de usá-los na produção, pois eles são conhecidos por quebrar algumas estruturas e aplicativos, particularmente nos casos em que são usadas anotações de comentários na documentação.

No Windows, opcache.file_cache_fallback deve ser habilitado e opcache.file_cache deve ser definido como um diretório já existente e gravável.

Uma lista completa de diretivas de configuração suportadas pelo OPcache também está disponível.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de configuração do OPcache
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
opcache.enable | 1 | `INI_ALL` |
opcache.enable_cli | 0 | `INI_SYSTEM` | Entre PHP 7.1.2 e 7.1.6 inclusive, o padrão era `1`
opcache.memory_consumption | 128 | `INI_SYSTEM` |
opcache.interned_strings_buffer | 8 | `INI_SYSTEM` |
opcache.max_accelerated_files | 10000 | `INI_SYSTEM` |
opcache.max_wasted_percentage | 5 | `INI_SYSTEM` |
opcache.use_cwd | 1 | `INI_SYSTEM` |
opcache.validate_timestamps | 1 | `INI_ALL` |
opcache.revalidate_freq | 2 | `INI_ALL` |
opcache.revalidate_path | 0 | `INI_ALL` |
opcache.save_comments | 1 | `INI_SYSTEM` |
opcache.fast_shutdown | 0 | `INI_SYSTEM` | Removido no PHP 7.2.0
opcache.enable_file_override | 0 | `INI_SYSTEM` |
opcache.optimization_level | 0x7FFEBFFF | `INI_SYSTEM` | Alterado de `0x7FFFBFFF` no PHP 7.3.0
opcache.inherited_hack | 1 | `INI_SYSTEM` | Removido no PHP 7.3.0
opcache.dups_fix | 0 | `INI_ALL` |
opcache.blacklist_filename | "" | `INI_SYSTEM` |
opcache.max_file_size | 0 | `INI_SYSTEM` |
opcache.consistency_checks | 0 | `INI_ALL` | Desativado a partir do 8.1.18 e 8.2.5. Removido a partir do PHP 8.3.0
opcache.force_restart_timeout | 180 | `INI_SYSTEM` |
opcache.error_log | "" | `INI_SYSTEM` |
opcache.log_verbosity_level | 1 | `INI_SYSTEM` |
opcache.record_warnings | 0 | `INI_SYSTEM` | Disponível a partir do PHP 8.0.0
opcache.preferred_memory_model | "" | `INI_SYSTEM` |
opcache.protect_memory | 0 | `INI_SYSTEM` |
opcache.mmap_base | `null` | `INI_SYSTEM` |
opcache.restrict_api | "" | `INI_SYSTEM` |
opcache.file_update_protection | 2 | `INI_ALL` |
opcache.huge_code_pages | 0 | `INI_SYSTEM` |
opcache.lockfile_path | "/tmp" | `INI_SYSTEM` |
opcache.opt_debug_level | 0 | `INI_SYSTEM` | Disponível a partir do PHP 7.1.0
opcache.file_cache | `null` | `INI_SYSTEM` |
opcache.file_cache_only | 0 | `INI_SYSTEM` |
opcache.file_cache_consistency_checks | 1 | `INI_SYSTEM` |
opcache.file_cache_fallback | 1 | `INI_SYSTEM` | Somente Windows.
opcache.validate_permission | 0 | `INI_SYSTEM` | Disponível a partir do PHP 7.0.14
opcache.validate_root | 0 | `INI_SYSTEM` | Disponível a partir do PHP 7.0.14
opcache.preload | "" | `INI_SYSTEM` | Disponível a partir do PHP 7.4.0
opcache.preload_user | "" | `INI_SYSTEM` | Disponível a partir do PHP 7.4.0
opcache.cache_id | "" | `INI_SYSTEM` | Somente Windows. Disponível a partir do PHP 7.4.0
opcache.jit | "disable" | `INI_ALL` | Disponível a partir do PHP 8.0.0. Antes do PHP 8.4.0, o valor padrão era "tracing".
opcache.jit_buffer_size | 64M | `INI_SYSTEM` | Disponível a partir do PHP 8.0.0. Antes do PHP 8.4.0, o valor padrão era 0.
opcache.jit_debug | 0 | `INI_ALL` | Disponível a partir do PHP 8.0.0
opcache.jit_bisect_limit | 0 | `INI_ALL` | Disponível a partir do PHP 8.0.0
opcache.jit_prof_threshold | 0.005 | `INI_ALL` | Disponível a partir do PHP 8.0.0
opcache.jit_max_root_traces | 1024 | `INI_SYSTEM` | Disponível a partir do PHP 8.0.0
opcache.jit_max_side_traces | 128 | `INI_SYSTEM` | Disponível a partir do PHP 8.0.0
opcache.jit_max_exit_counters | 8192 | `INI_SYSTEM` | Disponível a partir do PHP 8.0.0
opcache.jit_hot_loop | 61 | `INI_SYSTEM` | Disponível a partir do PHP 8.0.0, antes do PHP 8.5.0, o valor padrão era 64
opcache.jit_hot_func | 127 | `INI_SYSTEM` | Disponível a partir do PHP 8.0.0
opcache.jit_hot_return | 8 | `INI_SYSTEM` | Disponível a partir do PHP 8.0.0
opcache.jit_hot_side_exit | 8 | `INI_SYSTEM` | Disponível a partir do PHP 8.0.0
opcache.jit_blacklist_root_trace | 16 | `INI_ALL` | Disponível a partir do PHP 8.0.0
opcache.jit_blacklist_side_trace | 8 | `INI_ALL` | Disponível a partir do PHP 8.0.0
opcache.jit_max_loop_unrolls | 8 | `INI_ALL` | Disponível a partir do PHP 8.0.0
opcache.jit_max_recursive_calls | 2 | `INI_ALL` | Disponível a partir do PHP 8.0.0
opcache.jit_max_recursive_returns | 2 | `INI_ALL` | Disponível a partir do PHP 8.0.0
opcache.jit_max_polymorphic_calls | 2 | `INI_ALL` | Disponível a partir do PHP 8.0.0

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`opcache.enable` bool
  Habilita o cache opcode. Quando desabilitado, o código não é otimizado ou armazenado em cache. A configuração `opcache.enable` não pode ser habilitada em tempo de execução através de ini_set(), ela só pode ser desabilitada. Tentar ativá-lo em um script gerará um aviso.
`opcache.enable_cli` bool
  Ativa o cache opcode para a versão CLI do PHP.
`opcache.memory_consumption` int
  O tamanho do armazenamento de memória compartilhada usado pelo OPcache, em megabytes. O valor mínimo permitido é `"8"`, que é aplicado se um valor menor for definido.
`opcache.interned_strings_buffer` int
  A quantidade de memória usada para armazenar strings internas, em megabytes. O valor máximo é de 32767 em arquiteturas de 64 bits., e 4095 nas de 32 bits.

  > Nota: Antes do PHP 8.4.0, o valor máximo era de 4095 megabytes para todas as arquiteturas.

`opcache.max_accelerated_files` int
  O número máximo de chaves (e, portanto, scripts) na tabela de hash do OPcache. O valor real usado será o primeiro número no conjunto de números primos `{ 223, 463, 983, 1979, 3907, 7963, 16229, 32531, 65407, 130987, 262237, 524521, 1048793 }` que é maior ou igual ao valor configurado. O valor mínimo é 200. O valor máximo é 1.000.000. Valores fora desta faixa são fixados na faixa permitida.
`opcache.max_wasted_percentage` int
  A porcentagem máxima de memória desperdiçada que é permitida antes de uma reinicialização ser planejada, se houver memória livre insuficiente. O valor máximo permitido é `"50"`, que é aplicado se um valor maior for definido.
`opcache.use_cwd` bool
  Se ativado, o OPcache anexa o diretório de trabalho atual à chave de script, eliminando assim possíveis colisões entre arquivos com o mesmo nome de base. Desativar esta diretiva melhora o desempenho, mas pode interromper os aplicativos existentes.
`opcache.validate_timestamps` bool

  Se ativado, o OPcache verificará os scripts atualizados a cada opcache.revalidate_freq segundos. Quando esta diretiva é desativada, você deve redefinir o OPcache manualmente via opcache_reset(), opcache_invalidate() ou reiniciando o servidor Web para que as alterações no sistema de arquivos entrem em vigor.

  > Nota: O OPcache ainda pode validar o carimbo de data e hora de um arquivo durante o tempo de compilação se as opções opcache.file_update_protection ou opcache.max_file_size estiverem definidas com valores diferentes de zero.

`opcache.revalidate_freq` int
  Com que frequência verificar carimbos de data/hora do script para atualizações, em segundos. `0` resultará na verificação de atualizações do OPcache em cada solicitação. Esta diretiva de configuração será ignorada se opcache.validate_timestamps estiver desativado.
`opcache.revalidate_path` bool
  Se desativado, os arquivos em cache existentes usando o mesmo include_path serão reutilizados. Assim, se um arquivo com o mesmo nome estiver em outro lugar no include_path, ele não será encontrado.
`opcache.save_comments` bool
  Se desativado, todos os comentários da documentação serão descartados do cache do opcode para reduzir o tamanho do código otimizado. Desativar esta diretiva de configuração pode interromper aplicativos e frameworks que dependem da análise de comentários para anotações, incluindo Doctrine, Zend Framework 2 e PHPUnit.
`opcache.fast_shutdown` bool
  Se ativado, uma sequência de desligamento rápido é usada que não libera cada bloco alocado, mas depende do gerenciador de memória do Zend Engine para desalocar todo o conjunto de variáveis de solicitação em massa. Esta diretiva foi removida no PHP 7.2.0. Uma variante da sequência de desligamento rápido foi integrada ao PHP e será usada automaticamente, se possível.
`opcache.enable_file_override` bool
  Quando ativado, o cache opcode será verificado para saber se um arquivo já foi armazenado em cache quando file_exists(), is_file() e is_readable() são chamados. Isso pode aumentar o desempenho em aplicativos que verificam a existência e legibilidade de scripts PHP, mas corre o risco de retornar dados desatualizados se opcache.validate_timestamps estiver desabilitado.
`opcache.optimization_level` int
  Uma máscara de bits que controla quais passos de otimização são executados. O valor padrão é `0x7FFEBFFF`, que habilita todas as otimizações seguras. Desabilitar otimizações ou habilitar otimizações inseguras é útil na maioria das vezes para depurar/desenvolver o otimizador. Cada bit da máscara habilita um passo específico da otimização:

  Máscara de Bits de Passos da Otimização
  Bit | Nome do Passo | Descrição | Padrão
  --- | --- | --- | ---
  0 | PASS_1 | Otimizações simples de olho mágico | Ligado
  1 | PASS_2 | Não utilizado (mesclado ao PASS_1) | Ligado
  2 | PASS_3 | Otimização de salto simples | Ligado
  3 | PASS_4 | Otimização de chamadas | Ligado
  4 | PASS_5 | Otimização baseada em grafo de fluxo de controle | Ligado
  5 | PASS_6 | Otimização baseada em análise de fluxo de dados | Ligado
  6 | PASS_7 | Se o grafo de chamadas deve ser usado para otimizações baseadas em SSA. | Ligado
  7 | PASS_8 | Propagação esparsa de constantes condicionais | Ligado
  8 | PASS_9 | Otimização de variáveis ​​temporárias | Ligado
  9 | PASS_10 | Remoção de opcodes NOP | Ligado
  10 | PASS_11 | Compactação literal | Ligado
  11 | PASS_12 | Pré-calcular o tamanho da pilha de chamadas | Ligado
  12 | PASS_13 | Remoção de variáveis ​​não utilizadas | Ligado
  13 | PASS_14 | Eliminação de código morto | Ligado
  14 | PASS_15 | Coletar e substituir declarações constantes (inseguro) | Desligado
  15 | PASS_16 | Inlining de função trivial (parte da otimização de chamadas) | Ligado
  16 | (Flag) | Ignorar a possibilidade de sobrecarga do operador (inseguro) | Desligado

  > Nota: Otimizações Seguras versus Inseguras
  > Otimizações Seguras (habilitadas por padrão) preservam o comportamento exato do código PHP enquanto melhora o desempenho. Elas incluem eliminação de código morto, a redução de constantes e a otimização de saltos. Otimizações Inseguras (desabilitadas por padrão) podem alterar o comportamento em casos extremos:

  > - Bit 14: Coletando constantes. As constantes são substituídas no momento da compilação, ignorando a ordem de declaração do momento da execução:

  >       <?php
  >       echo getA();         // Resultado: "hello" em vez de lançar um Error
  >       const A = "hello";
  >       function getA() { return A; }

  > - Bit 16: Ignorando a sobrecarga do operador. Inseguro ao usar classes com `do_operation` (ex.: GMP, BCMath) em operações aritméticas. Com declarações de tipo, o otimizador pode aplicar as mesmas otimizações de forma segura.

`opcache.inherited_hack` bool
  Esta diretiva de configuração é ignorada.
`opcache.dups_fix` bool
  Este hack só deve ser ativado para contornar os erros "Cannot redeclare class".
`opcache.blacklist_filename` string
  A localização do arquivo de eliminação do OPcache. Um arquivo de eliminação é um arquivo de texto contendo os nomes dos arquivos que não devem ser acelerados, um por linha. Curingas(*) são permitidos e prefixos também podem ser fornecidos. As linhas iniciadas com ponto e vírgula são ignoradas como comentários. Um arquivo de eliminação simples pode ter a seguinte aparência:

      ; Corresponde a um arquivo específico.
      /var/www/broken.php
      ; Um prefixo que corresponde a todos os arquivos que começam com x.
      /var/www/x
      ; Uma correspondência curinga.
      /var/www/*-broken.php

`opcache.max_file_size` int
  O tamanho máximo do arquivo que será armazenado em cache, em bytes. Se for `0`, todos os arquivos serão armazenados em cache.
`opcache.consistency_checks` int
  Se diferente de zero, o OPcache verificará a soma de verificação do cache a cada N solicitações, onde N é o valor desta diretiva de configuração. Isso só deve ser ativado durante a depuração, pois prejudicará o desempenho.

  > Nota: Desativado a partir do 8.1.18 e 8.2.5. Removido a partir do PHP 8.3.0.

`opcache.force_restart_timeout` int
  O tempo de espera para iniciar uma reinicialização agendada se o cache não estiver ativo, em segundos. Se o tempo limite for atingido, o OPcache assumirá que algo está errado e eliminará os processos que mantêm bloqueios no cache para permitir uma reinicialização. Se opcache.log_verbosity_level for definido como 2 ou superior, um aviso será registrado no log de erros quando isso ocorrer. Esta diretiva não é suportada no Windows.
`opcache.error_log` string
  O log de erros para erros do OPcache. Uma string vazia é tratada da mesma forma que `stderr` e resultará no envio de logs para erro padrão (que será o log de erro do servidor Web na maioria dos casos).
`opcache.log_verbosity_level` int
  O nível de verbosidade do log. Por padrão, apenas erros fatais (nível 0) e erros (nível 1) são registrados. Outros níveis disponíveis são avisos (nível 2), mensagens informativas (nível 3) e mensagens de depuração (nível 4).
`opcache.record_warnings` bool
  Se ativado, o OPcache registrará avisos em tempo de compilação e os reproduzirá na próxima inclusão, mesmo que seja servido do cache.
`opcache.preferred_memory_model` string
  O modelo de memória preferencial para uso do OPcache. Se deixado em branco, o OPcache escolherá o modelo mais adequado, que é o comportamento correto em praticamente todos os casos. Os valores possíveis incluem `mmap`, `shm`, `posix` e `win32`.
`opcache.protect_memory` bool
  Protege a memória compartilhada contra gravações inesperadas durante a execução de scripts. Isso é útil apenas para depuração interna.
`opcache.mmap_base` string
  A base usada para segmentos de memória compartilhada no Windows. Todos os processos PHP precisam mapear a memória compartilhada no mesmo espaço de endereço. O uso desta diretiva permite que os erros "Unable to reattach to base address" sejam corrigidos.
`opcache.restrict_api` string
  Permite chamar funções da API do OPcache apenas de scripts PHP cujo caminho é iniciado a partir da string especificada. O padrão `""` significa nenhuma restrição.
`opcache.file_update_protection` string
  Impede o armazenamento em cache de arquivos que tenham menos de um determinado número de segundos desde a última modificação. Isso protege contra o armazenamento em cache de arquivos que tenham sido atualizados de forma incompleta. Caso todas as atualizações forem atômicas, o desempenho pode ser aumentado definindo isso como `0`. Isso permitirá que os arquivos sejam armazenados em cache imediatamente.
`opcache.huge_code_pages` bool
  Ativa ou desativa a cópia do código PHP (segmento de texto) em PÁGINAS ENORMES. Isso deve melhorar o desempenho, mas requer configuração de sistema operacional apropriada. Disponível no Linux a partir do PHP 7.0.0 e no FreeBSD a partir do PHP 7.4.0.
`opcache.lockfile_path` string
  Caminho absoluto usado para armazenar arquivos de bloqueio compartilhados (somente para * nix)
`opcache.opt_debug_level` string
  Produz opcode dumps para depurar diferentes estágios de otimizações. 0x10000 produzirá opcodes conforme o compilador os produziu antes que qualquer otimização ocorra, enquanto 0x20000 produzirá códigos otimizados.
`opcache.file_cache` string
  Ativa e define o diretório de cache de segundo nível. Ele deve melhorar o desempenho quando a memória SHM estiver cheia, na reinicialização do servidor ou na reinicialização do SHM. O padrão `""` desativa o cache baseado em arquivo.
`opcache.file_cache_only` bool
  Ativa ou desativa o armazenamento em cache opcode na memória compartilhada.

  > Nota: Antes do PHP 8.1.0, desabilitar esta diretiva com um cache de arquivo já preenchido era necessário para limpar manualmente o cache de arquivo.

`opcache.file_cache_consistency_checks` bool
  Ativa ou desativa a validação da soma de verificação quando o script é carregado do cache do arquivo.
`opcache.file_cache_fallback` bool
  Implica em `opcache.file_cache_only=1` para um determinado processo que falhou ao se reconectar à memória compartilhada (somente para Windows). É necessário habilitar explicitamente o cache de arquivos.
  Cuidado

  Desativar esta opção de configuração pode impedir que os processos sejam iniciados e, portanto, é desencorajado.

`opcache.validate_permission` bool
  Valida as permissões do arquivo em cache no usuário atual.
`opcache.validate_root` bool
  Evita colisões de nomes em ambientes chroot'ed. Isso deve ser ativado em todos os ambientes chroot'ed para impedir o acesso a arquivos fora do chroot.
`opcache.preload` string
  Especifica um script PHP que será compilado e executado na inicialização do servidor e que pode pré-carregar outros arquivos, seja por includeing ou usando a função opcache_compile_file(). Todas as entidades (por exemplo, funções e classes) definidas nesses arquivos estarão disponíveis para solicitações prontas para uso, até que o servidor seja desligado.

  > Nota: O pré-carregamento não é suportado no Windows.

`opcache.preload_user` string
  Permite que o pré-carregamento seja executado como o usuário do sistema especificado. Isso é útil para servidores que inicializam como root antes de alternar para um usuário de sistema sem privilégios. O pré-carregamento como root não é permitido por padrão por motivos de segurança, a menos que esta diretiva seja explicitamente definida como `root`. A partir do PHP 8.3.0, esta diretiva não precisa ser definida para permitir pré-carregamento quando executado como root ao usar o CLI SAPI ou o SAPI phpdbg.
`opcache.cache_id` string

  No Windows, todos os processos executando o mesmo PHP SAPI na mesma conta de usuário com o mesmo ID de cache compartilham uma única instância do OPcache. O valor do cache ID pode ser escolhido livremente.

  Dica

  Para IIS, diferentes pools de aplicativos podem ter sua própria instância OPcache usando a variável de ambiente APP_POOL_ID como `opcache.cache_id`.

`opcache.jit` string|int
  Para uso típico, esta opção aceita um dos quatro valores de string:
  - `disable`: Completamente desativado, não pode ser ativado em tempo de execução.
  - `off`: Desativado, mas pode ser ativado em tempo de execução.
  - `tracing`/`on`:Use rastreamento JIT. Ativado por padrão e recomendado para a maioria dos usuários.
  - `function`: Use function JIT.

  Para uso avançado, esta opção aceita um `CRTO` inteiro de 4 dígitos, onde os dígitos significam:

  `C` (CPU-sinalizadores de otimização específicos)
    - `0`: Desative a otimização específica da CPU.
    - `1`: Habilite o uso do AVX, se a CPU for compatível.
  `R` (alocação de registro)
    - `0`: Não execute alocação de registro.
    - `1`: Execute a alocação de registrador local de bloco.
    - `2`: Execute a alocação global de registradores.
  `T` (gatilho(trigger))
    - `0`: Compile todas as funções no carregamento do script.
    - `1`: Compile funções na primeira execução.
    - `2`: Funções de perfil no primeiro pedido e compilação das funções mais quentes depois.
    - `3`: Crie perfis em tempo real e compile funções importantes.
    - `4`: Atualmente sem uso.
    - `5`: Use tracing JIT. Crie perfis em tempo real e compile rastreamentos para segmentos de código dinâmico.
  `O` (nível de otimização)
    - `0`: Sem JIT.
    - `1`: JIT mínimo (chamada de manipuladores de VM padrão).
    - `2`: Manipuladores de VM embutidos.
    - `3`: Use inferência de tipo.
    - `4`: Usar gráfico de chamada.
    - `5`: Otimize todo o script.
  O modo `"tracing"` corresponde a `CRTO = 1254`, o modo `"function"` corresponde a `CRTO = 1205`.
`opcache.jit_buffer_size` int
  A quantidade de memória compartilhada a ser reservada para o código JIT compilado. Um valor zero desativa o JIT. Quando um int é usado, o valor é medido em bytes. A notação abreviada, como descrita nesta FAQ, também pode ser usada.
`opcache.jit_debug` int
  Uma máscara de bits especificando qual saída de depuração JIT habilitar. Para possíveis valores, consulte » zend_jit.h (procure por definições de macro começando com `ZEND_JIT_DEBUG`).
`opcache.jit_bisect_limit` int
  Opção de depuração que desativa a compilação JIT após a compilação de um determinado número de funções. Isso pode ser útil para dividir a origem de um erro de compilação JIT. Observação: esta opção só funciona quando o gatilho JIT é definido como 0 (compilar no carregamento do script) ou 1 (compilar na primeira execução), por exemplo, `opcache.jit=1215`. Veja mais na opção opcache.jit.
`opcache.jit_prof_threshold` float
  Ao usar o modo de trigger "profile on first request", esse limite determina se uma função é considerada ativa. O número de chamadas para a função dividido pelo número de chamadas para todas as funções deve estar acima do limite. Por exemplo, um limite de 0,005 significa que as funções que representam mais de 0,5% de todas as chamadas serão compiladas por JIT.
`opcache.jit_max_root_traces` int
  Número máximo de root traces. O root trace é um fluxo de execução que percorre primeiro um caminho através do código, que é uma unidade de compilação JIT. O JIT não compilará o novo código se atingir esse limite.
`opcache.jit_max_side_traces` int
  Número máximo de side traces que um root trace pode ter. O side trace é outro fluxo de execução que não segue o caminho do root trace compilado. Os sides traces pertencentes ao mesmo root trace não serão compilados se atingirem esse limite.
`opcache.jit_max_exit_counters` int
  Número máximo de contadores de saída de side trace. Isso limita o número total de side traces que podem existir, em todos os root traces.
`opcache.jit_hot_loop` int
  Depois de quantas iterações um laço é considerado ativo. O intervalo de valores válidos é `[0,255]`; para qualquer configuração fora desse intervalo, por exemplo, `-1` ou `256`, o valor padrão será usado. O valor `0` desabilitará o JIT para rastrear ou compilar quaisquer laços.

  > Nota: É recomendado que este parâmetro seja definido para um número primo para evitar que ele seja um múltiplo da contagem de laços de iteração.

`opcache.jit_hot_func` int
  Depois de quantas chamadas uma função é considerada ativa. O intervalo de valores válidos é `[0,255]`; para qualquer configuração fora desse intervalo, por exemplo, `-1` ou `256`, o valor padrão será usado. O valor `0` desabilitará o JIT para rastrear e compilar quaisquer funções.
`opcache.jit_hot_return` int
  Depois de quantos retornos, um retorno é considerado ativo. O intervalo de valores válidos é `[0,255]`; para qualquer configuração fora desse intervalo, por exemplo, `-1` ou `256`, o valor padrão será usado. O valor `0` desabilitará o JIT para rastrear e compilar quaisquer retornos.
`opcache.jit_hot_side_exit` int
  Depois de quantas saídas uma saída secundária é considerada ativa. O intervalo de valores válidos é `[0,255]`; para qualquer configuração fora desse intervalo, por exemplo, `-1` ou `256`, o valor padrão será usado. O valor zero `0` desabilitará o JIT para rastrear e compilar quaisquer saídas secundárias.
`opcache.jit_blacklist_root_trace` int
  Número máximo de vezes que a compilação de um root trace é tentada antes de ser incluída na blacklist.
`opcache.jit_blacklist_side_trace` int
  Número máximo de vezes que a compilação de um side trace é tentada antes de ser incluída na blacklist.
`opcache.jit_max_loop_unrolls` int
  Número máximo de tentativas de resolver um loop em um traço lateral, tentando alcançar o root trace e fechar o loop externo.
`opcache.jit_max_recursive_calls` int
  Número máximo de loops de chamada recursiva.
`opcache.jit_max_recursive_returns` int
  Número máximo de loops de retorno recursivos.
`opcache.jit_max_polymorphic_calls` int
  Número máximo de tentativas de chamadas polimórficas (dinâmicas ou de método) embutidas. As chamadas acima desse limite são tratadas como megamórficas e não são embutidas.

# Preloading

A partir do PHP 7.4.0, o PHP pode ser configurado para pré-carregar scripts no opcache quando o mecanismo é iniciado. Quaisquer funções, classes, interfaces ou traits (mas não constantes) nestes arquivos ficarão globalmente disponíveis para todas as solicitações sem precisar ser incluídas explicitamente. Isso troca conveniência e desempenho (porque o código está sempre disponível) para uso de memória de linha de base. Também requer a reinicialização do processo PHP para limpar os scripts pré-carregados, o que significa que esse recurso é prático apenas para uso em produção, não em um ambiente de desenvolvimento.

Observe que a compensação ideal entre desempenho e memória pode variar de acordo com o aplicativo. "Pré-carregar tudo" pode ser a estratégia mais fácil, mas não necessariamente a melhor estratégia. Além disso, o pré-carregamento só é útil quando há um processo persistente de uma solicitação para outra. Isso significa que, embora possa funcionar em um script CLI se o opcache estiver ativado, geralmente é inútil. A exceção é ao usar o pré-carregamento em bibliotecas FFI.

> Nota: O pré-carregamento não é suportado no Windows.

A configuração do pré-carregamento envolve duas etapas e requer que o opcache esteja ativado. Primeiro, defina o valor opcache.preload em php.ini:

    opcache.preload=preload.php

preload.php é um arquivo arbitrário que será executado uma vez na inicialização do servidor (PHP-FPM, mod_php, etc.) e carregará o código na memória persistente. Em servidores que iniciam como root antes de alternar para um usuário de sistema sem privilégios, ou se o PHP for executado como root (não recomendado), o valor opcache.preload_user pode especificar o usuário do sistema para executar o pré-carregamento. A execução do pré-carregamento como root não é permitida por padrão. Configure `opcache.preload_user=root` para permiti-lo explicitamente.

No script preload.php, qualquer arquivo referenciado por include, include_once, require, require_once ou opcache_compile_file() será analisado na memória persistente. No exemplo a seguir, todos os arquivos .php no diretório src serão pré-carregados, a menos que sejam um arquivo `Test`.

    <?php
    $directory = new RecursiveDirectoryIterator(__DIR__ . '/src');
    $fullTree = new RecursiveIteratorIterator($directory);
    $phpFiles = new RegexIterator($fullTree, '/.+((?<!Test)+\.php$)/i', RecursiveRegexIterator::GET_MATCH);

    foreach ($phpFiles as $key => $file) {
        require_once $file[0];
    }
    ?>

Ambos include e opcache_compile_file() funcionarão, mas têm implicações diferentes sobre como o código é tratado.

- include executará o código no arquivo, enquanto opcache_compile_file() não. Isso significa que apenas o primeiro suporta declaração condicional (funções declaradas dentro de um bloco if).
- Como include executará o código, os arquivos includes aninhados também serão analisados e suas declarações pré-carregadas.
- opcache_compile_file() pode carregar arquivos em qualquer ordem. Ou seja, se a.php define a classe `A` e b.php define a classe `B` que estende `A`, então opcache_compile_file() pode carregar esses dois arquivos em qualquer ordem. Ao usar include, no entanto, a.php deve ser incluído primeiro.
- Em ambos os casos, se um script posterior incluir um arquivo que já foi pré-carregado, seu conteúdo ainda será executado, mas quaisquer símbolos que ele definir não serão redefinidos. O uso de include_once não impedirá que o arquivo seja incluído uma segunda vez. Pode ser necessário carregar um arquivo novamente para incluir as constantes globais definidas nele, pois elas não são tratadas pelo pré-carregamento.

Qual abordagem é melhor, portanto, depende do comportamento desejado. Com código que, de outra forma, usaria um autoloader, opcache_compile_file() permite maior flexibilidade. Com o código que seria carregado manualmente, include será mais robusta.

# Funções de OPcache

# opcache_compile_file

(PHP 5 >= 5.5.5, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_compile_file — Compila e armazena em cache um script PHP sem executá-lo

### Descrição

function opcache_compile_file(string `$filename`): bool

Esta função compila um script PHP e o adiciona ao cache opcode sem executá-lo. Isso pode ser usado para preparar o cache após a reinicialização de um servidor da Web, armazenando previamente em cache os arquivos que serão incluídos em solicitações posteriores.

### Parâmetros

`filename`
  O caminho para o script PHP a ser compilado.

### Valor Retornado

Retorna `true` se `filename` foi compilado com sucesso ou `false` em caso de falha.

### Erros/Exceções

Se `filename` não puder ser carregado ou compilado, um erro de nível `E_WARNING` será gerado. Você pode usar @ para suprimir este aviso.

### Veja Também

- opcache_invalidate() - Invalida um script em cache

# opcache_get_configuration

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_get_configuration — Obtém informações de configuração sobre o cache

### Descrição

function opcache_get_configuration(): array|false

Esta função retorna informações de configuração sobre a instância de cache

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma série de informações, incluindo ini, blacklist e versão

### Erros/Exceções

Se `opcache.restrict_api` estiver em uso e o caminho atual violar a regra, um E_WARNING será emitido; nenhuma informação de status será retornada.

### Veja Também

- opcache_get_status() - Obtém informações de status sobre o cache

# opcache_get_status

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_get_status — Obtém informações de status sobre o cache

### Descrição

function opcache_get_status(bool `$include_scripts` = `true`): array|false

Essa função retorna informações de estado sobre a instância do cache na memória. Ele não retornará nenhuma informação sobre o cache do arquivo.

### Parâmetros

`include_scripts`
  Incluir informações de estado específicas do script

### Valor Retornado

Retorna um array de informações, opcionalmente contendo informações de estado específicas do script, ou `false` em caso de falha.

### Erros/Exceções

Se `opcache.restrict_api` estiver em uso e o caminho atual violar a regra, um E_WARNING será emitido; nenhuma informação de status será retornada.

### Registro de Alterações

Versão | Descrição
--- | ---
PHP 8.3.0 | `opcache_get_status()['scripts'][n]['revalidate']` agora contém um timestamp Unix de quando a próxima revalidação do timestamp dos scripts vencem, como ditado pela diretiva INI `opcache.revalidate_freq` .

### Exemplos

Exemplo #1 Um exemplo de opcache_get_status()

    <?php
    var_dump(opcache_get_status());
    ?>

O exemplo acima produzirá algo semelhante a:

    array(9) {
      'opcache_enabled' =>
      bool(true)
      'cache_full' =>
      bool(false)
      'restart_pending' =>
      bool(false)
      'restart_in_progress' =>
      bool(false)
      'memory_usage' =>
      array(4) {
        'used_memory' =>
        int(9167936)
        'free_memory' =>
        int(125049792)
        'wasted_memory' =>
        int(0)
        'current_wasted_percentage' =>
        double(0)
      }
      'interned_strings_usage' =>
      array(4) {
        'buffer_size' =>
        int(8388608)
        'used_memory' =>
        int(2593616)
        'free_memory' =>
        int(5794992)
        'number_of_strings' =>
        int(10358)
      }
      'opcache_statistics' =>
      array(13) {
        'num_cached_scripts' =>
        int(0)
        'num_cached_keys' =>
        int(0)
        'max_cached_keys' =>
        int(16229)
        'hits' =>
        int(0)
        'start_time' =>
        int(1733310010)
        'last_restart_time' =>
        int(0)
        'oom_restarts' =>
        int(0)
        'hash_restarts' =>
        int(0)
        'manual_restarts' =>
        int(0)
        'misses' =>
        int(0)
        'blacklist_misses' =>
        int(0)
        'blacklist_miss_ratio' =>
        double(0)
        'opcache_hit_rate' =>
        double(0)
      }
      'scripts' =>
      array(0) {
      }
      'jit' =>
      array(7) {
        'enabled' =>
        bool(false)
        'on' =>
        bool(false)
        'kind' =>
        int(5)
        'opt_level' =>
        int(4)
        'opt_flags' =>
        int(6)
        'buffer_size' =>
        int(0)
        'buffer_free' =>
        int(0)
      }
    }

### Veja Também

- opcache_get_configuration() - Obtém informações de configuração sobre o cache

# opcache_invalidate

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.0)

opcache_invalidate — Invalida um script em cache

### Descrição

function opcache_invalidate(string `$filename`, bool `$force` = `false`): bool

Esta função invalida um determinado script do cache opcode. Se `force` não estiver definido ou for `false`, o script só será invalidado se o horário de modificação do script for mais recente que os opcodes armazenados em cache. Esta função invalida apenas o cache na memória e não o cache do arquivo.

### Parâmetros

`filename`
  O caminho para o script que está sendo invalidado.
`force`
  Se definido como `true`, o script será invalidado independentemente de a invalidação ser necessária.

### Valor Retornado

Retorna `true` se o cache do opcode para `filename` foi invalidado ou se não havia nada para invalidar, ou `false` se o cache do opcode está desabilitado.

### Veja Também

- opcache_compile_file() - Compila e armazena em cache um script PHP sem executá-lo
- opcache_reset() - Redefine o conteúdo do cache opcode

# opcache_is_script_cached

(PHP 5 >= 5.5.11, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.4)

opcache_is_script_cached — Informa se um script é armazenado em cache no OPCache

### Descrição

function opcache_is_script_cached(string `$filename`): bool

Esta função verifica se um script PHP foi armazenado em cache no OPCache. Isso pode ser usado para detectar mais facilmente o "aquecimento" do cache para um determinado script. Esta função verifica apenas o cache na memória, não o cache do arquivo. Para verificar o cache de arquivo, use opcache_is_script_cached_in_file_cache().

### Parâmetros

`filename`
  O caminho para o script PHP a ser verificado.

### Valor Retornado

Retorna `true` se `filename` estiver armazenado no cache de memória do OPCache, `false` caso contrário.

### Veja Também

- opcache_compile_file() - Compila e armazena em cache um script PHP sem executá-lo
- opcache_is_script_cached_in_file_cache() - Informa se um script está armazenado no cache de arquivo do OPCache

# opcache_is_script_cached_in_file_cache

(PHP 8 >= 8.5.0)

opcache_is_script_cached_in_file_cache — Informa se um script está armazenado no cache de arquivo do OPCache

### Descrição

function opcache_is_script_cached_in_file_cache(string `$filename`): bool

Esta função verifica se um script PHP foi armazenado no cache do OPCache. Isso pode ser usado para detectar melhor o "aquecimento" do cache para um script em particular. Esta função apenas verifica o cache de arquivo, não o cache de memória. Para verificar o de memória, use opcache_is_script_cached().

### Parâmetros

`filename`
  O caminho para o script PHP a ser verificado.

### Valor Retornado

Retorna `true` se `filename` estiver em cache no OPCache, `false` caso contrário.

### Veja Também

- opcache_compile_file() - Compila e armazena em cache um script PHP sem executá-lo
- opcache_is_script_cached() - Informa se um script é armazenado em cache no OPCache

# opcache_jit_blacklist

(PHP 8 >= 8.4.0)

opcache_jit_blacklist — Impede que uma função seja compilada pelo JIT

### Descrição

function opcache_jit_blacklist( Closure `$closure` ): void

Esta função impede que uma função em particular seja compilada pelo JIT quando o rastreamento JIT estiver em uso. Esta função é especificada usando um Closure.

Aviso

Qualquer parte da função que já tenha sido compilada pelo JIT permacece não afetada e ainda será compilada pelo JIT.

### Parâmetros

`closure`
  A função a ser impedida, representada como um chamável de primeira classe. Também é possível passar uma função anônima, e nesse caso a própria função anônima é impedida.

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo básico de opcache_jit_blacklist()

    <?php
    function foo() {
        $x = 1;
        $x += 0;
        ++$x;
        var_dump($x);
    }
    opcache_jit_blacklist(foo(...));
    foo();
    ?>

### Veja Também

- opcache_invalidate() - Invalida um script em cache
- opcache_reset() - Redefine o conteúdo do cache opcode

# opcache_reset

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.0)

opcache_reset — Redefine o conteúdo do cache opcode

### Descrição

function opcache_reset(): bool

Esta função redefine todo o cache do opcode. Depois de chamar opcache_reset(), todos os scripts serão recarregados e reanalisados na próxima vez que forem atingidos. Esta função redefine apenas o cache na memória, não o cache do arquivo.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se o cache de opcode foi redefinido, ou `false` se o cache de opcode estiver desativado ou se a reinicialização estiver pendente ou em progresso (consulte opcache_get_status()).

### Veja Também

- opcache_invalidate() - Invalida um script em cache
- opcache_get_status() - Obtém informações de status sobre o cache

## Índice

- opcache_compile_file — Compila e armazena em cache um script PHP sem executá-lo
- opcache_get_configuration — Obtém informações de configuração sobre o cache
- opcache_get_status — Obtém informações de status sobre o cache
- opcache_invalidate — Invalida um script em cache
- opcache_is_script_cached — Informa se um script é armazenado em cache no OPCache
- opcache_is_script_cached_in_file_cache — Informa se um script está armazenado no cache de arquivo do OPCache
- opcache_jit_blacklist — Impede que uma função seja compilada pelo JIT
- opcache_reset — Redefine o conteúdo do cache opcode

- Instalação/Configuração
  - Instalação
  - Configurações em Execução
- Preloading
- Funções de OPcache
  - opcache_compile_file — Compila e armazena em cache um script PHP sem executá-lo
  - opcache_get_configuration — Obtém informações de configuração sobre o cache
  - opcache_get_status — Obtém informações de status sobre o cache
  - opcache_invalidate — Invalida um script em cache
  - opcache_is_script_cached — Informa se um script é armazenado em cache no OPCache
  - opcache_is_script_cached_in_file_cache — Informa se um script está armazenado no cache de arquivo do OPCache
  - opcache_jit_blacklist — Impede que uma função seja compilada pelo JIT
  - opcache_reset — Redefine o conteúdo do cache opcode

# Controle de Buffer de Saída

# Introdução

As funções de Controle de Saída permitem controlar quando a saída é enviada do script. Isto pode ser útil em situações diversas, especialmente se for necessário enviar cabeçalhos para o navegador depois que o script começou a enviar dados. As funções de Controle de Saída não afetam os cabeçalhos enviados por funções como header() ou setcookie(), apenas funções como echo e dados entre blocos de código PHP.

# Instalação/Configuração

## Índice

- Configurações em Execução

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de configuração de Controle de Saída
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
output_buffering | `"0"` | `INI_PERDIR` |
output_handler | `null` | `INI_PERDIR` |
implicit_flush | `"0"` | `INI_ALL` |
url_rewriter.tags | `"form="` | `INI_ALL` | A partir do PHP 7.1.0, esta configuração INI afeta somente output_add_rewrite_var(). Antes do PHP 7.1.0, esta configuração INI habilitava duporte a ID de sessão transparente (veja session.trans_sid_tags).
url_rewriter.hosts | `$_SERVER['HTTP_HOST']` é usado como padrão. | `INI_ALL` | Disponível a partir do PHP 7.1.0

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`output_buffering` bool/int

  Buffer de saída para todos os arquivos pode ser habilitado configurando-se esta diretiva para `"On"`. Para limitar o tamanho do buffer, um número/quantidade correspondendo ao número máximo de bytes permitidos pode ser usado no lugar de `"On"` para o valor desta diretiva. Por exemplo, `output_buffering=4096`. Esta diretiva é sempre "Off" no PHP-CLI.

`output_handler` string

  A saída de scripts pode ser redirecionada para uma função. Por exemplo, ao configurar `output_handler` para mb_output_handler(), a codificação de caracteres será convertida de forma trasnparente para a codificação especificada. Configurar qualquer manipulador de saída automaticamente habilita o buffer de saída.

  > Nota:

  > mb_output_handler() e ob_iconv_handler() não podem ser usadas juntas; e ob_gzhandler() e zlib.output_compression não podem ser usadas com nenhuma das funções a seguir: mb_output_handler(), ob_gzhandler(), zlib.output_compression, o manipulador 'URL-Rewriter' (veja session.use_trans_sid e output_add_rewrite_var()).

  > Nota:

  > Apenas funções internas do PHP podem ser usadas com esta diretiva. Para funções definidas pelo usuário, use ob_start().

`implicit_flush` bool

  `false` por padrão. Alterar para `true` indica ao PHP que a camada de saída deve se descarregar automaticamente após cada bloco de saída. Isto é equivalente a chamar a função do PHP flush() após cada chamada a qualquer função que produza saída (tal como print ou echo) e cada bloco HTML.

  Ao usar o PHP em um ambiente web, habilitar esta opção tem implicações sérias em desempenho e é geralmente recomendada apenas para depuração. O valor deste parâmetro é `true` ao operar sob o `CLI SAPI`.

  Consulte também ob_implicit_flush().

`url_rewriter.tags` string
  `url_rewriter.tags` especifica etiquetas e atributos HTML cujas URLs são re-escritas pelos valores de output_add_rewrite_var(). O padrão é `"form="`. Adicionar `"form="` ou qualquer atributo `form` irá adicionar um elemento `input` oculto ao `form` com um atributo de nome e valor para cada par de nome-valor passado para output_add_rewrite_var().
  Cuidado

  Caso seja adicionada a mesma etiqueta mais de uma vez a `url_rewriter.tags`, apenas a primeira será usada durante o processo de re-escrita da URL.

  > Nota: Antes do PHP 7.1.0, url_rewriter.tags era usado para especificar session.trans_sid_tags.

`url_rewriter.hosts` string
  `url_rewriter.hosts` especifica quais hosts são re-escritos para incluir os valores output_add_rewrite_var(). O padrão é `$_SERVER['HTTP_HOST']`. Múltiplos hosts podem ser especificados por uma lista separada por vírgulas que não contenha espaços. Por exemplo, `"php.net,wiki.php.net,bugs.php.net"`.

# Constantes predefinidas

As constantes abaixo estão sempre disponíveis como parte do núcleo do PHP.

Opções de status passadas ao manipulador de saída

As opções a seguir são passadas no segundo parâmetro (`phase`) do manipulador de saída definido por ob_start() como parte de uma máscara de bits:

`PHP_OUTPUT_HANDLER_START` (int)

  Indica que o buffer de saída iniciou.

`PHP_OUTPUT_HANDLER_WRITE` (int)

  Indica que o buffer de saída está sendo despejado, e tinha dados para enviar.

`PHP_OUTPUT_HANDLER_FLUSH` (int)

  Indica que o buffer de saída foi despejado.

`PHP_OUTPUT_HANDLER_CLEAN` (int)

  Indica que o buffer de saída foi limpo.

`PHP_OUTPUT_HANDLER_FINAL` (int)

  Indica que esta é a operação de buffer de saída final.

`PHP_OUTPUT_HANDLER_CONT` (int)

  Indica que o buffer de saída foi despejado, mas que operação de buffer de saída irá continuar.

  Este é um apelido para `PHP_OUTPUT_HANDLER_WRITE`.

`PHP_OUTPUT_HANDLER_END` (int)

  Indica que o buffer de saída terminou.

  Este é um apelido para `PHP_OUTPUT_HANDLER_FINAL`.

Opções de controle de buffer de saída

As opções a seguir podem ser passadas no terceiro parâmetro (`flags`) do manipulador de saída definido por ob_start() como uma máscara de bits.:

`PHP_OUTPUT_HANDLER_CLEANABLE` (int)

  Controla se um buffer de saída criado por ob_start() pode ser limpo por ob_clean(). Esta opção não controla o comportamento de ob_end_clean() ou ob_get_clean().

`PHP_OUTPUT_HANDLER_FLUSHABLE` (int)

  Controla se um buffer de saída criado por ob_start() pode ser despejado por ob_flush(). Esta opção não controla o comportamento de ob_end_flush() ou ob_get_flush().

`PHP_OUTPUT_HANDLER_REMOVABLE` (int)

  Controla se um buffer de saída criado por ob_start() pode ser removido antes do final do script ou ao chamar ob_end_clean(), ob_end_flush(), ob_get_clean() ou ob_get_flush().

`PHP_OUTPUT_HANDLER_STDFLAGS` (int)

  O conjunto padrão de opções de buffer de saída; atualmente equivalente a `PHP_OUTPUT_HANDLER_CLEANABLE` | `PHP_OUTPUT_HANDLER_FLUSHABLE` | `PHP_OUTPUT_HANDLER_REMOVABLE`.

Opções de status do manipulador de saída

As opções a seguir são parte da máscara de bits `flags` retornada por ob_get_status():

`PHP_OUTPUT_HANDLER_STARTED` (int)

  Indica que um manipulador de saída foi chamado.

`PHP_OUTPUT_HANDLER_DISABLED` (int)

  Indica que o manipulador de saída está desabilitado. Esta opção é definida quando o manipulador de saída retorna `false` ou falha durante o processamento do buffer. Antes do PHP 8.4.0, esta opção poderia ser definida ao iniciar um buffer de saída.

`PHP_OUTPUT_HANDLER_PROCESSED` (int)

  Indica que o manipulador de saída processou o buffer com sucesso. Disponível a partir do PHP 8.4.0.

# Buffer de Saída

O buffer de saída é o buffer (armazenamento temporário) da saída antes de ela ser descarregada (enviada e descartada) para o navegador (em um contexto da web) ou para o shell (na linha de comando). Enquanto o buffer de saída estiver ativo, nenhuma saída será enviada do script; em vez disso, a saída será armazenada em um buffer interno.

## Buffer Afetando o PHP

O PHP depende da infraestrutura de software/hardware subjacente ao descarregar a saída. O buffer implementado por consoles na linha de comando (por exemplo, buffer de linha) ou servidores web e navegador em um contexto web (por exemplo, totalmente bufferizado) afeta quando a saída é exibida para o usuário final. Alguns desses efeitos podem ser eliminados ajustando as configurações do servidor e/ou alinhando os tamanhos dos buffers das diversas camadas.

## Controle de Buffer de Saída no PHP

O PHP fornece um buffer de saída em nível de usuário totalmente armazenado em buffer com funções para iniciar, manipular e desligar o buffer (a maioria das funções ob_*) e duas funções para descarregar os buffers subjacentes do sistema (flush() e ob_implicit_flush()). Algumas dessas funcionalidades podem ser definidas e/ou configuradas usando também as configurações apropriadas do php.ini.

## Casos de Uso

O buffer de saída geralmente é útil em situações em que a saída armazenada em buffer é modificada ou inspecionada ou é usada mais de uma vez em uma solicitação; ou quando a descarga controlada da saída é desejada. Os casos de uso específicos incluem:

- Armazenar em cache o resultado de scripts com uso intensivo de tempo/computação, por exemplo, gerando páginas `HTML` estáticas.
- Reutilizar a saída gerada exibindo-a, salvando-a em um arquivo e/ou enviando-a por e-mail.
- Enviar a tag `head` de uma página `HTML`, antes da tag `body` permite que os navegadores carreguem recursos externos enquanto o script executa processos potencialmente mais demorados (por exemplo, acesso a banco de dados e arquivos, conexão de rede externa). Isto só é útil se o código de status `HTTP` não puder ser alterado após o envio dos cabeçalhos.
- Extrair informações de funções que de outra forma produziriam saída (por exemplo, phpinfo()).
- Controlar a saída de código de terceiros modificando/usando partes (por exemplo, extraindo dados, substituindo palavras/frases, adicionando tags `HTML` ausentes) ou descartando-o inteiramente sob certas condições (por exemplo, erros).
- Preenchendo certas funcionalidades indisponíveis do servidor web (por exemplo, compactação ou codificação de saída)

# Descarregando Buffers de Sistema

O PHP fornece duas maneiras relacionadas para descarregar os buffers de sistema (enviar e descartar o conteúdo): chamando-se a função flush() e habilitando o descarregamento implicitamente com a função ob_implicit_flush() ou com a configuração implicit_flush do php.ini.

## Comportamento do Descarregameto da Saída

Com o descarregamento implícito desabilitado, o PHP irá descarregar a saída somente quendo flush() for chamada ou quando o script terminar.

Com o descarregamento implícito habilitado, o PHP tentará descarregar após cada bloco de código que resulte em uma saída. A saída neste contexto é um dado de comprimento maior que zero que:

- esteja fora das tags `<?php ?>`
- seja exibido por construções de linguagem e funções cujo propósito explícito é mostrar variáveis fornecidas pelo usuário ou strings tais como echo, print, printf(), var_dump(), var_export() e vprintf()
- seja exibido por funções cujo propósito é coletar e mostrar dados/informações no script em execução ou no PHP tais como debug_print_backtrace(), phpcredits() e phpinfo(), ReflectionExtension::info()
- seja mostrado pelo PHP em uma exceção não capturada ou erro não gerenciado (sujeitos às configurações de display_errors e error_reporting)
- seja qualquer coisa escrita em `php://output`

> Nota: Exibir strings vazias ou enviar cabeçalhos não é considerado saída e não resultará em operação de descarregamento.

Aviso

Se o descarregamento implícito estiver habilitado, caracteres de controle (ex.: `"\n"`, `"\r"`, `"\0"`) também irão ativar o descarregamento.

## Limitações

Esta funcionalidade não pode descarregar buffers de saída no nível do usuário. Para usá-los juntos, buffers de saída no nível do usuário devem ser descarregados antes do descarregamento ds buffers de sistema para que o PHP produza qualquer saída.

Aviso

Chamar flush() ou habilitar o descarregamento implícito pode interferir com os manipuladores de saída de buffers no nível do usuário que definem e enviam cabeçalhos em um contexto web (ex.: ob_gzhandler()) enviando cabeçalhos antes que estes manipuladores o façam.

Buffer implementado pelo software/hardware subjacente não podem ser substituídos pelo PHP e devem ser levados em consideração ao se trabalhar com as funções de controle de buffer do PHP. Verificar as configurações de buffer dos servidores web, navegadores e consoles e trabalhar com elas pode aliviar possíveis problemas. Trabalhar em um contexto web, tanto as configurações de buffer do servidor quanto de buffer do script podem ser ajustadas para operar sequencialmente enquanto que contornar as estratégias de buffer de vários navegadores pode ser conseguido ajustando o buffer no script PHP. Em consoles que implementam buffer de linha, caracteres de nova linha podem ser inseridos nos locais apropriados antes de liberar a saída.

## Diferenças SAPI No Descarregamento

Embora o descarregamento seja implementado por cada SAPI de uma maneira ligeiramente diferente, essas implementações se enquadram em uma de duas categorias:

- SAPIs usadas em um contexto web irão descarregar cabeçalhos primeiro, e depois a saída. `Apache2Handler`, `CGI`, `FastCGI` e `FPM` são tais SAPIs.
- Outras SAPIs tais como `CLI` e `embed` irão descarregar somente a saída.

# Buffers de Saída em Nível de Usuário

## Índice

- Que Saída é Armazenada em Buffer?
- Aninhando Buffers de Saída
- Tamanho do Buffer
- Operações permitidas em buffers
- Manipuladores de Saída
- Trabalhando com Manipuladores de Saída
- Opções Passadas aos Manipuladores de Saída
- Valores de Retorno do Menipulador de Saída

Os buffers de saída no nível do usuário podem ser iniciados, manipulados e finalizados a partir do código PHP. Cada um desses buffers inclui um buffer de saída e uma função de manipulador de saída associada.

## Que Saída é Armazenada em Buffer?

Os buffers de saída em nível de usuário do PHP armazenam toda a saída após serem iniciados, até que sejam desligados ou o script termine. A saída no contexto do buffer de saída no nível do usuário do PHP é tudo o que o PHP exibiria ou enviaria de volta ao navegador. Em termos práticos, a saída são dados de comprimento diferente de zero que são:

- esteja fora das tags `<?php ?>`
- seja exibido por construções de linguagem e funções cujo propósito explícito é mostrar variáveis fornecidas pelo usuário ou strings tais como echo, print, printf(), var_dump(), var_export() e vprintf()
- seja exibido por funções cujo propósito é coletar e mostrar dados/informações no script em execução ou no PHP tais como debug_print_backtrace(), phpcredits() e phpinfo(), ReflectionExtension::info()
- seja mostrado pelo PHP em uma exceção não capturada ou erro não gerenciado (sujeitos às configurações de display_errors e error_reporting)
- seja qualquer coisa escrita em `php://output`

> Nota: Os dados gravados diretamente em `stdout` ou passados ​​para uma função SAPI com funcionalidade semelhante não serão capturados pelos buffers de saída no nível do usuário. Isso inclui escrever dados em `stdout` com fwrite() ou enviar cabeçalhos usando header() ou setcookie().

## Ativando o buffer de saída

O buffer de saída pode ser ativado usando a função ob_start() ou definindo as configurações output_buffering e output_handler do php.ini. Embora ambas possam criar buffers de saída, ob_start() é mais flexível, pois aceita funções definidas pelo usuário como manipuladores de saída e as operações permitidas no buffer (liberar, limpar, remover) também podem ser definidas. Buffers iniciados com ob_start() estarão ativos a partir da linha em que a função foi chamada, enquanto aqueles iniciados com output_buffering irão armazenar a saída em buffer a partir da primeira linha do script.

O PHP também é fornecido com um manipulador de saída `"URL-Rewriter"` integrado que inicia seu próprio buffer de saída e permite até no máximo duas instâncias dele em execução a qualquer momento (uma para reescrita de URL no nível de usuário e uma para suporte transparente ao ID de sessão). Esses buffers podem ser iniciados chamando a função output_add_rewrite_var() e/ou ativando a configuração session.use_trans_sid do php.ini.

A extensão `zlib` incluída tem seu próprio buffer de saída que pode ser ativado usando a configuração zlib.output_compression do php.ini.

> Nota: Embora `"URL-Rewriter"` seja especial porque permite apenas até duas instâncias dele em execução ao mesmo tempo, todos os buffers de saída em nível de usuário usam os mesmos buffers subjacentes usados ​​por ob_start() com sua funcionalidade implementada por uma função de manipulador de saída personalizada. Como tal, todas as suas funcionalidades podem ser emuladas pelo código do usuário.

## Aninhando Buffers de Saída

Se houver um buffer de saída ativo quando um novo buffer for iniciado, o novo buffer será aninhado dentro do buffer ativo anteriormente. O buffer interno se comportará da mesma maneira, independentemente de estar aninhado, mas a saída armazenada em buffer por ele não será armazenada em buffer pelo buffer externo. Somente a saída liberada pelo buffer interno será armazenada no buffer externo.

A maioria das funções `ob_*` só funcionam com o buffer de saída ativo (o último iniciado), portanto, apenas o buffer ativo pode ser descarregado, limpo e desligado. As funções que funcionam com outros buffers são ob_list_handlers() que retorna a lista de todos os manipuladores de saída em uso e ob_get_status() que pode retornar informações apenas sobre o buffer ativo ou sobre todos os buffers em uso .

Chamar ob_get_level() ou ob_get_status() retornará o nível de aninhamento do buffer de saída ativo.

Cuidado

O valor para níveis idênticos entre ob_get_level() e ob_get_status() está desfasado em um. Para ob_get_level() o primeiro nível é `1`, enquanto para ob_get_status() o primeiro nível é `0`.

## Tamanho do Buffer

Os tamanhos dos buffers são expressos por números inteiros e representam o número de bytes que o buffer pode armazenar sem descarregar. Quando o tamanho da saída no buffer excede o tamanho do buffer, o conteúdo do buffer é enviado para o manipulador de saída, seu valor de retorno é descarregado e o buffer é limpo.

Com exceção de `"URL-Rewriter"`, o tamanho dos buffers de saída pode ser definido quando o buffer é iniciado. Se definido como `0`, o buffer de saída será limitado apenas pela memória disponível para o PHP. Se definido como `1`, o buffer será descarregado após cada bloco de código produzir qualquer saída de comprimento diferente de zero.

O tamanho dos buffers de saída pode ser recuperado chamando ob_get_status().

Buffers de saída iniciados com ob_start() terão seus tamanhos de buffer definidos para o valor inteiro passado para o segundo parâmetro `chunk_size` da função. Se omitido, será definido como `0`.

O buffer de saída iniciado com output_buffering definido como `"On"` terá seu tamanho de buffer definido como 0. Se definido como um número inteiro, o tamanho do buffer corresponderá a esse número.

O tamanho do buffer do `"URL-Rewriter"`está definido como `0`, portanto ele é limitado apenas pela memória disponível para o PHP.

O tamanho do buffer de saída do `zlib` é controlado pela configuração zlib.output_compression do php.ini. Se definido como `"On"` o tamanho do buffer será `"16K"`(`16384`). Se definido como um número inteiro, o tamanho do buffer corresponderá a esse número em bytes.

## Operações permitidas em buffers

As operações permitidas em buffers podem ser controladas passando uma das opções de controle de buffer para o terceiro parâmetro `flags` de ob_start(). Se omitido, todas as operações serão permitidas por padrão. Se `0` for usado, o buffer não poderá ser descarregado, limpo ou removido, mas seu conteúdo ainda poderá ser recuperado.

`PHP_OUTPUT_HANDLER_CLEANABLE` permite que ob_clean() limpe o conteúdo do buffer.

Aviso

A ausência da opção `PHP_OUTPUT_HANDLER_CLEANABLE` não impedirá que ob_end_clean() ou ob_get_clean() limpem o conteúdo do buffer.

`PHP_OUTPUT_HANDLER_FLUSHABLE` permite que ob_flush() descarregue o conteúdo do buffer.

Aviso

A ausência da opção `PHP_OUTPUT_HANDLER_FLUSHABLE` não impedriá que ob_end_flush() ou ob_get_flush() descarreguem o conteúdo do buffer.

`PHP_OUTPUT_HANDLER_REMOVABLE` permite que ob_end_clean(), ob_end_flush(), ob_get_clean() ou ob_get_flush() desliguem o buffer.

`PHP_OUTPUT_HANDLER_STDFLAGS`, a combinação das três opções irá permitir que cada uma das três operações seja realizada no buffer.

## Descarregando, Acessando e Limpando o Conteúdo do Buffer

A descarga envia e descarta o conteúdo do buffer ativo. Os buffers de saída são descarregados quando o tamanho da saída excede o tamanho do buffer; quando o script termina; ou quando ob_flush(), ob_end_flush() ou ob_get_flush() são chamados.

Cuidado

Chamar ob_end_flush() ou ob_get_flush() irá desligar o buffer ativo.

Cuidado

A descarga de buffers liberará o valor de retorno do manipulador de saída, que pode ser diferente do conteúdo do buffer. Por exemplo, usar ob_gzhandler() compactará a saída e liberará a saída compactada.

O conteúdo do buffer ativo pode ser recuperado chamando ob_get_contents(), ob_get_clean() ou ob_get_flush().

Se apenas o comprimento do conteúdo do buffer for necessário, ob_get_length() ou ob_get_status() retornação o comprimento do conteúdo em bytes.

Cuidado

Chamar ob_get_clean() ou ob_get_flush() irá desligar o buffer ativo depois de retornar seu conteúdo.

O conteúdo do buffer ativo pode ser limpo chamando ob_clean(), ob_end_clean() ou ob_get_clean().

Cuidado

Chamar ob_end_clean() ou ob_get_clean() desligará o buffer ativo.

## Desligando Buffers

Buffers de saída podem ser desligados chamando ob_end_clean(), ob_end_flush(), ob_get_flush() ou ob_get_clean().

Aviso

Buffers de saída iniciados sem a opção `PHP_OUTPUT_HANDLER_REMOVABLE` não podem ser desligados e podem gerar um `E_NOTICE`.

Todo buffer de saída que não tiver sido fechado até o final do script, ou quando a função exit() for chamada, será descarregado e desligado pelo processo de desligamento do PHP. Os buffers serão descarregados e desligados na ordem inversa de sua inicialização. O último buffer iniciado será o primeiro, o primeiro buffer iniciado será o último a ser descarregado e desligado.

Cuidado

Se a descarga do conteúdo do buffer não for desejada, um manipulador de saída personalizado deverá ser usado para evitar a descarga durante o desligamento.

## Manipuladores de Saída

Manipuladores de saída são funções do tipo callable associadas com buffers de saída que são invocados ao chamar ob_clean(), ob_flush(), ob_end_flush(), ob_get_flush(), ob_end_clean(), ob_get_clean() ou durante o processo de desligamento do PHP.

> Nota: O processo de desligamento irá descarregar o valor de retorno do manipulador.

Se omitido ou `null` ao iniciar o buffer de saída, o `"default output handler"` (manipulador de saída padão) interno será usado, retornando o conteúdo não modificado do buffer quando invocado. Manipuladores de saída podem ser usados ​​para retornar uma versão modificada do conteúdo do buffer e/ou ter efeitos colaterais (por exemplo, enviar cabeçalhos).

O PHP vem com dois manipuladores de saída internos: `"default output handler"` e `"URL-Rewriter"` (que é integrado em seu próprio buffer de saída e no máximo duas instâncias dele podem ser iniciadas).

As extensões incluídas no PHP são equipadas com quatro manipuladores de saída adicionais: mb_output_handler(), ob_gzhandler(), ob_iconv_handler() e ob_tidyhandler().

## Trabalhando com Manipuladores de Saída

Quando invocados, os manipuladores de saída recebem o conteúdo do buffer e uma máscara de bits indicando o status do buffer de saída.

function handler ( string `$buffer` , int `$phase` = ?): string

`buffer`
  Conteúdo do buffer de saída.
`phase`
  Máscara de bits das constantes `PHP_OUTPUT_HANDLER_*` .

Aviso

Chamar qualquer das funções a seguir de dentro de um manipulador de saída resultará em um erro fatal: ob_clean(), ob_end_clean(), ob_end_flush(), ob_flush(), ob_get_clean(), ob_get_flush() ou ob_start().

> Nota: Se a constante `PHP_OUTPUT_HANDLER_DISABLED` de um manipulador estiver definida, ele não será invocado chamando ob_end_clean(), ob_end_flush(), ob_get_clean(), ob_get_flush(), ob_clean(), ob_flush() ou durante o processo de desligamento do PHP. Antes do PHP 8.4.0 esta opção não tinha efeito ao chamar ob_clean() ou ob_flush().

> Nota: O diretório de trabalho do script pode mudar dentro da função de desligamento em alguns servidores web, por ex. Apache ou o servidor web integrado.

## Opções Passadas aos Manipuladores de Saída

A máscara de bits passada para o segundo parâmetro `phase` do manipulador de saída fornece informações sobre a invocação do manipulador.

> Nota: A máscara de bits pode incluir mais de uma opção e o operador binário `&` deve ser usado para verificar se uma opção está definida.

Aviso

O valor de `PHP_OUTPUT_HANDLER_WRITE` e seu apelido `PHP_OUTPUT_HANDLER_CONT` é `0` portanto, se ele está definido ou não só pode ser determinado usando-se um operador de igualdade (`==` ou `===`).

As seguintes opções são definidas em uma fase específica do ciclo de vida do manipulador: `PHP_OUTPUT_HANDLER_START` é definida quando um manipulador é invocado pela primeira vez. `PHP_OUTPUT_HANDLER_FINAL` ou seu apelido `PHP_OUTPUT_HANDLER_END` é definida quando um manipulador é invocado pela última vez, ou seja, ele está sendo desligado. Esta opção também é definida quando os buffers estão sendo desligados pelo processo de desligamento do PHP.

As seguintes opções são definidas por uma invocação específica do manipulador: `PHP_OUTPUT_HANDLER_FLUSH` é definida quando o manipulador é invocado chamando-se ob_flush(). `PHP_OUTPUT_HANDLER_WRITE` ou seu apelido `PHP_OUTPUT_HANDLER_CONT` é definida quando o tamanho de seu conteúdo é igual ou excede o tamanho do buffer e o manipulador é invocado enquanto o buffer está sendo descarregado automaticamente. `PHP_OUTPUT_HANDLER_FLUSH` é definida quando o manipulador é invocado chamando-se ob_clean(), ob_end_clean() ou ob_get_clean(). Quando ob_end_clean() ou ob_get_clean() são chamados, `PHP_OUTPUT_HANDLER_FINAL` também é definida.

> Nota: Quando ob_end_flush() ou ob_get_flush() são chamadas, `PHP_OUTPUT_HANDLER_FINAL` é definida mas `PHP_OUTPUT_HANDLER_FLUSH` não é.

## Valores de Retorno do Menipulador de Saída

O valor de retorno do manipulador de saída é internamente forçado para uma string seguindo a semântica padrão de tipos do PHP, com duas exceções: arrays e booleanos.

Arrays são convertidos na string `"Array"` mas o alerta `Array to string conversion` (conversão de array para string) não é emitido.

Se o manipulador retorna `false`, o conteúdo do buffer é retornado. Se o manipulador retorna `true`, uma string vazia é retornada.

> Nota: Se o manipulador retorna `false` ou lança uma exceção, sua constante de estado `PHP_OUTPUT_HANDLER_DISABLED` é definida.

## Exceções Lançadas em Manipuladores de Saída

Se uma exceção não capturada é lançada em um manipulador de saída, o programa termina e o manipulador é invocado pelo processo de desligamento depois do qual a mensagem de erro `"Uncaught Exception"` (exceção não capturada) é descarregada.

Se a exceção não capturada é lançada em um manipulador invocado por ob_flush(), ob_end_flush() ou ob_get_flush(), o conteúdo do buffer é descarregado antes da mensagem de erro.

Se uma exceção não capturada é lançada em um manipulador de saída durante o desligamento, o manipulador é terminado e nem o conteúdo do buffer nem a mensagem de erro são descarregados.

> Nota: Se um manipulador lança uma exceção, sua constante de estado `PHP_OUTPUT_HANDLER_DISABLED` é definida.

## Erros Emitidos em Manipuladores de Saída

Se um erro não fatal for gerado em um manipulador de saída, o programa continuará a execução.

Se o erro não fatal for gerado em um manipulador invocado por ob_flush(), ob_end_flush() ou ob_get_flush(), o buffer descarrega determinados dados dependendo do valor de retorno do manipulador. Se o manipulador retornar `false`, o buffer e a mensagem de erro são descarregados. Se retornar qualquer outra coisa, o valor de retorno do manipulador será descarregado, mas a mensagem de erro não.

> Nota: Se um manipulador retornar `false`, sua constante de estado `PHP_OUTPUT_HANDLER_DISABLED` será definida.

Se um erro fatal for gerado em um manipulador de saída, o programa será encerrado e o manipulador será invocado pelo processo de desligamento, após o qual a mensagem de erro será descarregada.

Se o erro fatal for gerado em um manipulador invocado por ob_flush(), ob_end_flush() ou ob_get_flush(), o conteúdo dos buffers será descarregado antes da mensagem de erro.

Se um erro fatal for gerado em um manipulador de saída durante o desligamento, o programa será encerrado sem descarregar o buffer ou a mensagem de erro.

## Saída nos Manipuladores de Saída

Em circunstâncias específicas, a saída produzida no manipulador é descarregada junto com o conteúdo do buffer. Esta saída não é anexada ao buffer e não faz parte da string retornada por ob_get_flush().

Durante operações de descarga (ao chamar ob_flush(), ob_end_flush(), ob_get_flush() e durante o desligamento), se o valor de retorno de um manipulador for `false`, o conteúdo do buffer é descarregado seguido pela saída. Se o manipulador não for invocado durante o desligamento, o fato do manipulador lançar uma exceção ou chamar a função exit() resultará no mesmo comportamento.

> Nota: Se um manipulador retornar `false`, sua constante de estado `PHP_OUTPUT_HANDLER_DISABLED` é definida.

## Constantes de Estado do Manipulador de Saída

As constantes de estado de manipulador da máscara de bits `flags` do buffer são definidas toda vez que o manipulador de saída é invocado e são parte das `flags` retornadas por ob_get_status(). Se o manipulador executa com sucesso e não retorna `false`, `PHP_OUTPUT_HANDLER_STARTED` e `PHP_OUTPUT_HANDLER_PROCESSED` são definidas. Se o manipulador retonar `false` ou lança uma exceção durante a execução, `PHP_OUTPUT_HANDLER_STARTED` e `PHP_OUTPUT_HANDLER_DISABLED` são definidas.

> Nota: Se a constante `PHP_OUTPUT_HANDLER_DISABLED` de um manipulador for definida, o manipulador não será invocado chamando-se ob_end_clean(), ob_end_flush(), ob_get_clean(), ob_get_flush(), ob_clean(), ob_flush() ou durante o processo de desligamento do PHP. Antes do PHP 8.4.0, esta constante não tinha efeito ao chamar ob_clean() ou ob_flush().

# Exemplos

## Índice

- Uso básico
- Uso de re-escrita na saída

## Uso básico

Exemplo #1 Exemplo de Controle de Saída

    <?php

    ob_start();
    echo "Hello\n";

    setcookie("cookiename", "cookiedata");

    ob_end_flush();

    ?>

No exemplo acima, a saída de echo seria armazenada no buffer de saída até que ob_end_flush() fosse chamada. Neste meio tempo, a chamada a setcookie() armazenou com sucesso um cookie sem causar um erro. (Normalmente não se pode enviar cabeçalhos ao navegador depois que dados já foram enviados.)

## Uso de re-escrita na saída

Desde o PHP 7.1.0, output_add_rewrite_var() e output_reset_rewrite_vars() usam buffer dedicado de saída, isto é, não usam o buffer de saída trans sid.

Exemplo #1 Exemplo de re-escrita na saída

    <?php
    // Este código funciona com PHP 7.1.0, 7.0.10, 5.6.25 e posteriores.

    // HTTP_HOST é o servidor alvo padrão. Defina manualmente para fazer com o que o código de exemplo funcione.
    $_SERVER['HTTP_HOST'] = 'php.net';

    // Re-escrita na saída re-escreve apenas formulários. Adicione a=href.
    // Etiquetas podem ser especificadas nome_da_etiqueta=atribulo_url, ex.: img=src,iframe=src
    // Não é permitido espaço em branco entre as definições.
    // Etiqueta 'form' é uma etiqueta especial que adiciona entrada oculta.
    ini_set('url_rewriter.tags','a=href,form=');
    var_dump(ini_get('url_rewriter.tags'));

    // Isto é adicionado à URL e ao formulário
    output_add_rewrite_var('test', 'value');
    ?>
    <a href="//php.net/index.php?bug=1234">bug1234</a>
    <form action="https://php.net/?bug=1234&edit=1" method="post">
     <input type="text" name="title" />
    </form>

O exemplo acima produzirá:

    <a href="//php.net/?bug=1234&test=value">bug1234</a>
    <form action="https://php.net/?bug=1234&edit=1" method="post"><input type="hidden" name="test" value="value" />
     <input type="text" name="title" />
    </form>

Desde o PHP 7.1.0, funções de re-escrita na saída têm suas próprias configurações INI, url_rewriter.tags e url_rewriter.hosts.

# Funções para Control de Saída

# Veja Também

Veja também header() e setcookie().

# flush

(PHP 4, PHP 5, PHP 7, PHP 8)

flush — Descarrega o buffer na saída do sistema

### Descrição

function flush(): void

Descarrega os buffers de escrita do PHP e do backend usado pelo pelo PHP (ex.: CGI, um servidor web). Em um ambiente de linha de comando, flush() tentará descarregar somente o conteúdo do buffer enquanto que em um contexto web, os cabeçalhos e o conteúdo do buffer são descarregados.

> Nota: flush() pode não ser capaz de passar por cima do esquema de buffer do servidor web e não tem efeito sobre nenhum sistema de buffer cliente-servidor no navegador.

> Nota: Esta função não tem nenhum efeito sobre manipuladores de saída de usuário como os inicializados por ob_start() ou output_add_rewrite_var().

Aviso

flush() pode interferir com manipuladores de saída que definem e enviam cabeçalhos em um contexto web (ex.: ob_gzhandler()), enviando cabeçalhos antes que esses manipuladores possam fazê-lo.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Descarregar cabeçalhos sem um corpo agora terá sucesso no FastCGI.

### Veja Também

- ob_flush() - Descarrega (envia) o valor de retorno do manipulador de saída ativo
- ob_clean() - Limpa (apaga) o conteúdo do buffer de saída ativo
- ob_end_flush() - Descarrega (envia) o valor de retorno do manipulador de saída ativo e desliga o buffer de saída ativo
- ob_end_clean() - Limpa (apaga) o conteúdo do buffer de saída ativo e desliga-o

# ob_clean

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_clean — Limpa (apaga) o conteúdo do buffer de saída ativo

### Descrição

function ob_clean(): bool

Esta função chama o manipulador de saída (com a opção `PHP_OUTPUT_HANDLER_CLEAN`), descarta seu valor de retorno e limpa (apaga) o conteúdo do buffer de saída ativo.

Esta função não desliga o buffer de saída ativo como a função ob_end_clean() ou ob_get_clean() fazem.

ob_clean() falhará sem um buffer de saída ativo iniciado com a opção `PHP_OUTPUT_HANDLER_CLEANABLE`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Se a função falhar ela gera um `E_NOTICE`.

### Veja Também

- ob_start() - Ativa o buffer de saída
- ob_get_contents() - Retorna o conteúdo do buffer de saída
- ob_end_clean() - Limpa (apaga) o conteúdo do buffer de saída ativo e desliga-o
- ob_get_clean() - Obtém o conteúdo do buffer de saída ativo e desliga-o
- ob_flush() - Descarrega (envia) o valor de retorno do manipulador de saída ativo

# ob_end_clean

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_end_clean — Limpa (apaga) o conteúdo do buffer de saída ativo e desliga-o

### Descrição

function ob_end_clean(): bool

Esta função chama o manipulador de saída (com as opções `PHP_OUTPUT_HANDLER_CLEAN` e `PHP_OUTPUT_HANDLER_FINAL`), descarta seu valor de retorno, descarta o conteúdo do buffer de saída ativo e desliga o mesmo.

ob_end_clean() falhará sem um buffer de saída ativo com a opção `PHP_OUTPUT_HANDLER_REMOVABLE`.

ob_end_clean() irá descartar o conteúdo do buffer de saída ativo mesmo se tiver sido iniciado sem a opção `PHP_OUTPUT_HANDLER_CLEANABLE`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Se a função falhar, ela gera um `E_NOTICE`.

### Exemplos

O exemplo a seguir mostra uma maneira fácil de se livrar do conteúdo do buffer de saída ativo:

Exemplo #1 Exemplo de ob_end_clean()

    <?php
    ob_start();
    echo 'Este texto não será mostrado.';
    ob_end_clean();
    ?>

### Veja Também

- ob_start() - Ativa o buffer de saída
- ob_get_contents() - Retorna o conteúdo do buffer de saída
- ob_clean() - Limpa (apaga) o conteúdo do buffer de saída ativo
- ob_get_clean() - Obtém o conteúdo do buffer de saída ativo e desliga-o
- ob_end_flush() - Descarrega (envia) o valor de retorno do manipulador de saída ativo e desliga o buffer de saída ativo

# ob_end_flush

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_end_flush — Descarrega (envia) o valor de retorno do manipulador de saída ativo e desliga o buffer de saída ativo

### Descrição

function ob_end_flush(): bool

Esta função chama o manipulador de saída (com a opção `PHP_OUTPUT_HANDLER_FINAL`), descarrega (envia) seu valor de retorno, descarta o conteúdo do buffer de saída ativo e o desliga.

ob_end_flush() irá falhar sem um buffer de saída ativo iniciado com a opção `PHP_OUTPUT_HANDLER_REMOVABLE`.

ob_end_flush() irá descarregar (enviar) e retornar o valor do manipulador de saída mesmo se o buffer de saída ativo tiver iniciado sem a opção `PHP_OUTPUT_HANDLER_FLUSHABLE`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Se a função falhar, ela gera um `E_NOTICE`.

### Exemplos

Exemplo #1 Exemplo de ob_end_flush()

O exemplo a seguir mostra uma maneira fácil de descarregar e terminar todos os buffers de saída:

    <?php
      while (@ob_end_flush());
    ?>

### Veja Também

- ob_start() - Ativa o buffer de saída
- ob_get_contents() - Retorna o conteúdo do buffer de saída
- ob_flush() - Descarrega (envia) o valor de retorno do manipulador de saída ativo
- ob_get_flush() - Descarrega (envia) o valor de retorno do manipulador de saída ativo, retorna o conteúdo do buffer de saída ativo e desliga-o
- ob_end_clean() - Limpa (apaga) o conteúdo do buffer de saída ativo e desliga-o

# ob_flush

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_flush — Descarrega (envia) o valor de retorno do manipulador de saída ativo

### Descrição

function ob_flush(): bool

Esta função chama o manipulador de saída (com a opção `PHP_OUTPUT_HANDLER_FLUSH`), descarrega (envia) seu valor de retorno e descarta o conteúdo do buffer de saída ativo.

Esta função não desliga o buffer de saída ativo como as funções ob_end_flush() ou ob_get_flush() fazem.

ob_flush() falhará sem um buffer de saída ativo iniciado com a opção `PHP_OUTPUT_HANDLER_FLUSHABLE`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Se a função falhar ela gera um `E_NOTICE`.

### Veja Também

- ob_start() - Ativa o buffer de saída
- ob_get_contents() - Retorna o conteúdo do buffer de saída
- ob_end_flush() - Descarrega (envia) o valor de retorno do manipulador de saída ativo e desliga o buffer de saída ativo
- ob_get_flush() - Descarrega (envia) o valor de retorno do manipulador de saída ativo, retorna o conteúdo do buffer de saída ativo e desliga-o
- ob_clean() - Limpa (apaga) o conteúdo do buffer de saída ativo

# ob_get_clean

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_get_clean — Obtém o conteúdo do buffer de saída ativo e desliga-o

### Descrição

function ob_get_clean(): string|false

Esta função chama o manipulador de saída (com as opções `PHP_OUTPUT_HANDLER_CLEAN` e `PHP_OUTPUT_HANDLER_FINAL`), descarta seu valor de retorno, retorna o conteúdo do buffer de saída ativo e desliga o mesmo.

ob_get_clean() irá falhar sem um buffer de saída ativo iniciado com a opção `PHP_OUTPUT_HANDLER_REMOVABLE`.

ob_get_clean() irá descartar o conteúdo do buffer de saída ativo mesmo se tiver sido iniciado sem a opção `PHP_OUTPUT_HANDLER_CLEANABLE`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o conteúdo do buffer de saída ativo em caso de sucesso ou `false` em caso de falha.

Cuidado

ob_get_clean() retornará false mas não irá gerar um `E_NOTICE` se não houver buffer de saída ativo.

### Erros/Exceções

Se a função falhar, ela gerará um `E_NOTICE`.

### Exemplos

Exemplo #1 Um exemplo simples de ob_get_clean()

    <?php

    ob_start();

    echo "Olá, Mundo!";

    $out = ob_get_clean();
    $out = strtolower($out);

    var_dump($out);
    ?>

O exemplo acima produzirá:

    string(11) "olá, mundo!"

### Veja Também

- ob_start() - Ativa o buffer de saída
- ob_get_contents() - Retorna o conteúdo do buffer de saída
- ob_clean() - Limpa (apaga) o conteúdo do buffer de saída ativo
- ob_end_clean() - Limpa (apaga) o conteúdo do buffer de saída ativo e desliga-o
- ob_get_flush() - Descarrega (envia) o valor de retorno do manipulador de saída ativo, retorna o conteúdo do buffer de saída ativo e desliga-o

# ob_get_contents

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_get_contents — Retorna o conteúdo do buffer de saída

### Descrição

function ob_get_contents(): string|false

Obtém o conteúdo do buffer de saída sem limpá-lo.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o conteúdo do buffer de saída ou `false`, se o buffer de saída não estiver ativo.

### Exemplos

Exemplo #1 Um simples exemplo de ob_get_contents()

    <?php

    ob_start();

    echo "Olá, ";

    $out1 = ob_get_contents();

    echo "Mundo";

    $out2 = ob_get_contents();

    ob_end_clean();

    var_dump($out1, $out2);
    ?>

O exemplo acima produzirá:

    string(5) "Olá, "
    string(10) "Olá, Mundo"

### Veja Também

- ob_start() - Ativa o buffer de saída
- ob_get_length() - Retorna o comprimento do buffer de saída

# ob_get_flush

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_get_flush — Descarrega (envia) o valor de retorno do manipulador de saída ativo, retorna o conteúdo do buffer de saída ativo e desliga-o

### Descrição

function ob_get_flush(): string|false

Esta função chama o manipulador de saída (com a opção `PHP_OUTPUT_HANDLER_FINAL`), descarrega (envia) seu valor de retorno, retorna o conteúdo do buffer de saída ativo e desliga o mesmo.

ob_get_flush() irá falhar sem um buffer de saída ativo iniciado com a opção `PHP_OUTPUT_HANDLER_REMOVABLE`.

ob_get_flush() irá descarregar (enviar) o valor de retorno do manipulador de saída mesmo se o buffer de saída ativo tiver sido iniciado sem a opção `PHP_OUTPUT_HANDLER_FLUSHABLE`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o conteúdo do buffer de saída ativo em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Se a função falhar, ela gera um `E_NOTICE`.

### Exemplos

Exemplo #1 Exemplo de ob_get_flush()

    <?php
    // Usando output_buffering=On
    print_r(ob_list_handlers());

    // Grava o buffer em um arquivo
    $buffer = ob_get_flush();
    file_put_contents('buffer.txt', $buffer);

    print_r(ob_list_handlers());
    ?>

O exemplo acima produzirá:

    Array
    (
        [0] => default output handler
    )
    Array
    (
    )

### Veja Também

- ob_start() - Ativa o buffer de saída
- ob_get_contents() - Retorna o conteúdo do buffer de saída
- ob_flush() - Descarrega (envia) o valor de retorno do manipulador de saída ativo
- ob_end_flush() - Descarrega (envia) o valor de retorno do manipulador de saída ativo e desliga o buffer de saída ativo
- ob_get_clean() - Obtém o conteúdo do buffer de saída ativo e desliga-o

# ob_get_length

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

ob_get_length — Retorna o comprimento do buffer de saída

### Descrição

function ob_get_length(): int|false

Esta função retornará o comprimento do conteúdo do buffer de saída, em bytes.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o comprimento do conteúdo do buffer de saída ou `false` se o buffer não estiver ativo.

### Exemplos

Exemplo #1 Um simples exemplo de ob_get_length()

    <?php

    ob_start();

    echo "Olá, ";

    $len1 = ob_get_length();

    echo "Mundo";

    $len2 = ob_get_length();

    ob_end_clean();

    echo $len1 . ", ." . $len2;
    ?>

O exemplo acima produzirá:

    5, 10

### Veja Também

- ob_start() - Ativa o buffer de saída
- ob_get_contents() - Retorna o conteúdo do buffer de saída

# ob_get_level

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_get_level — Retorna o nível de aninhamento do mecanismo de buffer de saída

### Descrição

function ob_get_level(): int

Retorna o nível de aninhamento do mecanismo de buffer de saída.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o nível de manipuladores de buffer de saída aninhados ou zero se o buffer de saída não estiver ativo.

Cuidado

Os valores para níveis idênticos entre ob_get_level() e ob_get_status() são deslocados em uma unidade. Para ob_get_level() o primeiro nível é `1`, enquanto que para ob_get_status() o primeiro nível é `0`.

### Veja Também

- ob_start() - Ativa o buffer de saída
- ob_get_status() - Obtém status dos buffers de saída
- ob_get_contents() - Retorna o conteúdo do buffer de saída

# ob_get_status

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_get_status — Obtém status dos buffers de saída

### Descrição

function ob_get_status(bool `$full_status` = `false`): array

ob_get_status() retorna informação de status do buffer de saída do nível mais alto ou de todos os níveis de buffers de saída ativos se `full_status` estiver definido para `true`.

### Parâmetros

`full_status`

  `true` para retornar todos os níveis de buffers de saída ativos. Se for `false` ou não definido, somente o buffer de saída de nível mais alto é retornado.

### Valor Retornado

Se `full_status` for omitido ou `false` um array simples contendo informações de status no nível de saída ativo é retornado.

Se `full_status` for `true` um array com um elemento para cada nível de buffer de saída ativo é retornado. O nível de saída é usado como chave do array de nível superior e cada elemento do array em si é outro array que contém informações de status sobre um nível de saída ativo.

Um array vazio será retornada se o buffer de saída não estiver ativado.

Elementos do array de retorno de ob_get_status()
Chave | Valor
--- | ---
name | Nome do manipulador de saída ativo (veja os valores de retorno de ob_list_handlers() para detalhes)
type | `0` (manipulador interno) ou `1` (manipulador fornecido pelo usuário)
flags | Máscara de bits das opções definidas por ob_start(), o tipo de manipulador de saída (veja acima) e o status do processo de buffer (constantes `PHP_OUTPUT_HANDLER_*` ). Se o manipulador processou o buffer com sucesso e não retornou `false`, `PHP_OUTPUT_HANDLER_STARTED` e `PHP_OUTPUT_HANDLER_PROCESSED` serão definidas. Se o manipulador falhou ao processar o buffer ou retornou `false`, `PHP_OUTPUT_HANDLER_STARTED` e `PHP_OUTPUT_HANDLER_DISABLED` serão definidas.
level | Nível de aninhamento de saída (com base em zero). Observe que o valor retornado para o mesmo nível por ob_get_level() está deslocado em uma unidade. O primeiro nível é `0` para ob_get_status() e `1` para ob_get_level().
chunk_size | Tamanho do bloco em bytes. Definido por ob_start() ou se output_buffering estiver habilitado e seu valor estiver definido como um número inteiro positivo.
buffer_size | Tamanho do buffer de saída em bytes
buffer_used | Tamanho dos dados no buffer de saída em bytes (o mesmo que o valor de retorno do tipo inteiro de ob_get_length())

### Exemplos

Exemplo #1 Array retornado quando `full_status` é `false`

    Array
    (
        [name] => URL-Rewriter
        [type] => 0
        [flags] => 112
        [level] => 2
        [chunk_size] => 0
        [buffer_size] => 16384
        [buffer_used] => 1024
    )

Exemplo #2 Array retornado quando `full_status` é `true`

    Array
    (
        [0] => Array
            (
                [name] => default output handler
                [type] => 0
                [flags] => 112
                [level] => 1
                [chunk_size] => 0
                [buffer_size] => 16384
                [buffer_used] => 2048
            )

        [1] => Array
            (
                [name] => URL-Rewriter
                [type] => 0
                [flags] => 112
                [level] => 2
                [chunk_size] => 0
                [buffer_size] => 16384
                [buffer_used] => 1024
            )

    )

### Veja Também

- ob_get_level() - Retorna o nível de aninhamento do mecanismo de buffer de saída
- ob_list_handlers() - Lista todos os manipuladores de saída em uso
- ob_get_length() - Retorna o comprimento do buffer de saída
- ob_start() - Ativa o buffer de saída

# ob_implicit_flush

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_implicit_flush — Liga ou desliga o descarregamento implícito

### Descrição

function ob_implicit_flush(bool `$enable` = `true`): void

ob_implicit_flush() ativará ou desativará o descarregamento implícito. O descarregamento implícito resultará em uma operação de envio após cada bloco de código que resulte em saída, de modo que chamadas explícitas a flush() não serão mais necessárias.

> Nota: Imprimir strings vazias ou enviar cabeçalhos não é considerado saída e não resultará em uma operação de descarregamento.

> Nota: Esta função não tem nenhum efeito nos manipuladores de saída no nível do usuário, como aqueles iniciados por ob_start() ou output_add_rewrite_var().

### Parâmetros

`enable`

  `true` para ligar o descarregamento implícito, `false` para desligar.

### Valor Retornado

Nenhum valor é retornado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `enable` agora espera um valor do tipo bool; anteriormente, um int era esperado.

### Veja Também

- flush() - Descarrega o buffer na saída do sistema
- ob_start() - Ativa o buffer de saída
- ob_end_flush() - Descarrega (envia) o valor de retorno do manipulador de saída ativo e desliga o buffer de saída ativo

# ob_list_handlers

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_list_handlers — Lista todos os manipuladores de saída em uso

### Descrição

function ob_list_handlers(): array

Lista todos os manipuladores de saída em uso.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Isso retornará um array com os manipuladores de saída em uso (se houver).

Se output_buffering estiver ativado e nenhum output_handler estiver definido, ou nenhuma função de retorno ou `null` foi passada para ob_start(), `"default output handler"` é retornado. Ativar output_buffering e definir um output_handler é equivalente a passar uma função interna (integrada) para ob_start().

Se um callable foi passado para ob_start(), o nome totalmente qualificado do callable é retornado. Se o callable for um objeto que implementa __invoke(), o nome totalmente qualificado do método __invoke() do objeto é retornado. Se o callable for um Closure, `"Closure::__invoke"` será retornado.

### Exemplos

Exemplo #1 Exemplo de ob_list_handlers()

    <?php
    // usando output_buffering=On, nenhum manipulador de saída definido
    var_dump(ob_list_handlers());
    ob_end_flush();

    // nenhuma chamada de retorno ou null
    ob_start();
    var_dump(ob_list_handlers());
    ob_end_flush();

    // função anônima
    ob_start(function($string) { return $string; });
    var_dump(ob_list_handlers());
    ob_end_flush();

    // função seta
    ob_start(fn($string) => $string);
    var_dump(ob_list_handlers());
    ob_end_flush();

    // chamável de primeira classe
    $firstClassCallable = userDefinedFunction(...);

    ob_start([$firstClassCallable, '__invoke']);
    var_dump(ob_list_handlers());
    ob_end_flush();

    // função interna (integrada)
    ob_start('print_r');
    var_dump(ob_list_handlers());
    ob_end_flush();

    // função definida pelo usuário
    function userDefinedFunction($string, $flags) { return $string; };

    ob_start('userDefinedFunction');
    var_dump(ob_list_handlers());
    ob_end_flush();

    class MyClass {
        public static function staticHandle($string) {
            return $string;
        }

        public static function handle($string) {
            return $string;
        }

        public function __invoke($string) {
            return $string;
        }
    }

    // classe e método estático
    ob_start(['MyClass','staticHandle']);
    var_dump(ob_list_handlers());
    ob_end_flush();

    // objeto e método não estático
    ob_start([new MyClass,'handle']);
    var_dump(ob_list_handlers());
    ob_end_flush();

    // objeto invocável
    ob_start(new MyClass);
    var_dump(ob_list_handlers());
    ob_end_flush();
    ?>

O exemplo acima produzirá:

    array(1) {
      [0]=>
      string(22) "default output handler"
    }
    array(1) {
      [0]=>
      string(22) "default output handler"
    }
    array(1) {
      [0]=>
      string(7) "print_r"
    }
    array(1) {
      [0]=>
      string(19) "userDefinedFunction"
    }
    array(1) {
      [0]=>
      string(17) "Closure::__invoke"
    }
    array(1) {
      [0]=>
      string(17) "Closure::__invoke"
    }
    array(1) {
      [0]=>
      string(17) "Closure::__invoke"
    }
    array(1) {
      [0]=>
      string(21) "MyClass::staticHandle"
    }
    array(1) {
      [0]=>
      string(15) "MyClass::handle"
    }
    array(1) {
      [0]=>
      string(17) "MyClass::__invoke"
    }

### Veja Também

- ob_end_clean() - Limpa (apaga) o conteúdo do buffer de saída ativo e desliga-o
- ob_end_flush() - Descarrega (envia) o valor de retorno do manipulador de saída ativo e desliga o buffer de saída ativo
- ob_get_flush() - Descarrega (envia) o valor de retorno do manipulador de saída ativo, retorna o conteúdo do buffer de saída ativo e desliga-o
- ob_start() - Ativa o buffer de saída

# ob_start

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_start — Ativa o buffer de saída

### Descrição

function ob_start(?callable `$callback` = `null`, int `$chunk_size` = 0, int `$flags` = `PHP_OUTPUT_HANDLER_STDFLAGS`): bool

Esta função irá ativar o buffer de saída. Enquanto o buffer de saída estiver ativo, não é enviada a saída do script, (outros que não sejam cabeçalhos), ao invés disto a saída é guardada em um buffer interno. Consulte Que Saída é Armazenada em Buffer? sobre exatamente que saída é afetada.

Buffers de saída são empilháveis, ou seja, ob_start() pode ser chamada enquanto outro buffer estiver ativo. Se múltiplos buffers de saída estiverem ativos, a saída será filtrada sequencialmente atráves de cada uma delas na ordem de aninhamento. Consulte Aninhando Buffers de Saída para mais detalhes.

Consulte Buffers de Saída em Nível de Usuário para uma descrição detalhada de buffers de saída.

### Parâmetros

`callback`

  Uma função `callback` do tipo callable pode ser especificada. Ela também pode ser ignorada passando-se `null`.

  `callback` é chamada quando o buffer de saída é descarregado (enviado), limpo, ou quando o buffer de saída é descarregado no final da execução do script.

  A assinatura da função `callback` deve ser da seguinte forma:

  function handler(string `$buffer`, int `$phase` = ?): string
  `buffer`
    O conteúdo original do buffer.
  `phase`
    Máscara de bits das constantes `PHP_OUTPUT_HANDLER_*` . Consulte Opções Passadas aos Manipuladores de Saída para mais detalhes.

  Se `callback` retornar `false`, o conteúdo do buffer é retornado. Consulte Valores de Retorno do Menipulador de Saída para mais detalhes.

  Aviso

  Chamar qualquer das funções a seguir de dentro de um manipulador de saída resultará em erro fatal: ob_clean(), ob_end_clean(), ob_end_flush(), ob_flush(), ob_get_clean(), ob_get_flush() e ob_start().

  Consulte Manipuladores de Saída e Trabalhando com Manipuladores de Saída para mais detalhes sobre as funções `callback` (manipuladores de saída).

`chunk_size`

  Se o parâmetro opcional `chunk_size` for informado, o buffer será descarregado depois que algum bloco de código que produza saída faça com que o tamanho do buffer fique igual ou maior que `chunk_size`. O valor padrão é `0`, que significa que toda a saída fica em buffer até que ele seja desligado. Consulte Tamanho do Buffer para mais detalhes.

`flags`

  O parâmetro `flags` é uma máscara de bits que controla as operações que podem ser realizadas no buffer de saída. O padrão é permitir que o buffer de saída possa ser limpo, descarregado ou removido, o que pode ser configurado explicitamente através das opções de controle de buffer . Consulte Operações permitidas em buffers para mais detalhes.

  Cada opção controla o acesso das funções, como descrito a seguir:

  Constante | Funções
  --- | ---
  `PHP_OUTPUT_HANDLER_CLEANABLE` | ob_clean()
  `PHP_OUTPUT_HANDLER_FLUSHABLE` | ob_flush()
  `PHP_OUTPUT_HANDLER_REMOVABLE` | ob_end_clean(), ob_end_flush(), ob_get_clean() e ob_get_flush()

  > Nota: Antes do PHP 8.4.0, o parâmetro flags poderia definir também as opções de status do manipulador de saída.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de uma função de callback

    <?php

    function callback($buffer)
    {
      // substitui apples por oranges
      return (str_replace("apples", "oranges", $buffer));
    }

    ob_start("callback");

    ?>
    <html>
    <body>
    <p>It's like comparing apples to oranges.</p>
    </body>
    </html>
    <?php

    ob_end_flush();

    ?>

O exemplo acima produzirá:

    <html>
    <body>
    <p>It's like comparing oranges to oranges.</p>
    </body>
    </html>

Exemplo #2 Criando um buffer de saída não apagável

    <?php

    ob_start(null, 0, PHP_OUTPUT_HANDLER_STDFLAGS ^ PHP_OUTPUT_HANDLER_REMOVABLE);

    ?>

### Veja Também

- ob_get_contents() - Retorna o conteúdo do buffer de saída
- ob_end_clean() - Limpa (apaga) o conteúdo do buffer de saída ativo e desliga-o
- ob_end_flush() - Descarrega (envia) o valor de retorno do manipulador de saída ativo e desliga o buffer de saída ativo
- ob_implicit_flush() - Liga ou desliga o descarregamento implícito
- ob_gzhandler() - Função de chamada de retorno de ob_start para comprimir o buffer de saída com gzip
- ob_iconv_handler() - Converte codificação de caracteres como manipulador de buffer de saída
- mb_output_handler() - Callback converte a codificação de caracteres no buffer de saída
- ob_tidyhandler() - Função de retorno ob_start para reparar o buffer

# output_add_rewrite_var

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

output_add_rewrite_var — Adiciona valores de reescritor de URL

### Descrição

function output_add_rewrite_var(string `$name`, string `$value`): bool

Esta função inicia o manipulador de buffer de saída `'URL-Rewriter'` se ele não estiver ativo, armazena os parâmetros `name` e `value`, e quando o buffer é descarregado reescreve os URLs e formulários com base nas configurações ini aplicáveis. As chamadas subsequentes a esta função armazenarão todos os pares nome/valor adicionais até que o manipulador seja desligado.

Quando o buffer de saída é descarregado (chamando ob_flush(), ob_end_flush(), ob_get_flush() ou no final do script), o manipulador `'URL-Rewriter'` adiciona os pares nome/valor como parâmetros de consulta para URLs em atributos de etiquetas HTML e adiciona campos ocultos aos formulários com base nos valores das diretivas de configuração url_rewriter.tags e url_rewriter.hosts.

Cada par nome/valor adicionado ao manipulador `'URL-Rewriter'` é adicionado aos URLs e/ou formulários, mesmo que isso resulte em parâmetros de consulta de URL duplicados ou elementos com atributos de mesmo nome.

> Nota: Depois que o manipulador `'URL-Rewriter'` for desligado, ele não poderá ser iniciado novamente.

Aviso

Antes do PHP 8.4.0, os hosts a serem sobrescritos eram definidos em session.trans_sid_hosts ao invés de url_rewriter.hosts.

### Parâmetros

`name`

  O nome da variável.

`value`

  O valor da variável.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
7.1.0 | A partir do PHP 7.1.0, um buffer de saída dedicado é usado, url_rewriter.tags é usado somente para funções de saída e url_rewriter.hosts está disponível. Antes do PHP 7.1.0, variáveis ​​de reescrita definidas por output_add_rewrite_var() compartilhavam um buffer de saída com suporte transparente para ID de sessão (veja session.trans_sid_tags).

### Exemplos

Exemplo #1 Exemplo de output_add_rewrite_var()

    <?php
    ini_set('url_rewriter.tags', 'a=href,form=');

    output_add_rewrite_var('var', 'value');

    // alguns "links"
    echo '<a href="file.php">link</a>
    <a href="http://example.com">link2</a>';

    // um formulário
    echo '<form action="script.php" method="post">
    <input type="text" name="var2" />
    </form>';

    print_r(ob_list_handlers());
    ?>

O exemplo acima produzirá:

    <a href="file.php?var=value">link</a>
    <a href="http://example.com">link2</a>

    <form action="script.php" method="post">
    <input type="hidden" name="var" value="value" />
    <input type="text" name="var2" />
    </form>

    Array
    (
        [0] => URL-Rewriter
    )

### Veja Também

- output_reset_rewrite_vars() - Redefine valores de reescritor de URL
- ob_flush() - Descarrega (envia) o valor de retorno do manipulador de saída ativo
- ob_list_handlers() - Lista todos os manipuladores de saída em uso
- url_rewriter.tags
- url_rewriter.hosts

# output_reset_rewrite_vars

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

output_reset_rewrite_vars — Redefine valores de reescritor de URL

### Descrição

function output_reset_rewrite_vars(): bool

Esta função remove todas as variáveis ​​de reescrita previamente definidas pela função output_add_rewrite_var().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
7.1.0 | Antes do PHP 7.1.0, as variáveis de reescrita definidas por output_add_rewrite_var() usavam o mesmo buffer de saída "trans sid" do módulo de sessão. Desde o PHP 7.1.0, um buffer de saída dedicado é usado e output_reset_rewrite_vars() apenas remove variáveis de reescrita definidas por output_add_rewrite_var().

### Exemplos

Exemplo #1 Exemplo de output_reset_rewrite_vars()

    <?php
    ini_set('url_rewriter.tags', 'a=href');

    output_add_rewrite_var('var', 'value');

    echo '<a href="file.php">link</a>';
    ob_flush();

    output_reset_rewrite_vars();
    echo '<a href="file.php">link</a>';
    ?>

O exemplo acima produzirá:

    <a href="file.php?var=value">link</a>
    <a href="file.php">link</a>

### Veja Também

- output_add_rewrite_var() - Adiciona valores de reescritor de URL
- ob_flush() - Descarrega (envia) o valor de retorno do manipulador de saída ativo
- ob_list_handlers() - Lista todos os manipuladores de saída em uso
- url_rewriter.tags
- url_rewriter.hosts
- session.trans_sid_tags
- session.trans_sid_hosts

## Índice

- flush — Descarrega o buffer na saída do sistema
- ob_clean — Limpa (apaga) o conteúdo do buffer de saída ativo
- ob_end_clean — Limpa (apaga) o conteúdo do buffer de saída ativo e desliga-o
- ob_end_flush — Descarrega (envia) o valor de retorno do manipulador de saída ativo e desliga o buffer de saída ativo
- ob_flush — Descarrega (envia) o valor de retorno do manipulador de saída ativo
- ob_get_clean — Obtém o conteúdo do buffer de saída ativo e desliga-o
- ob_get_contents — Retorna o conteúdo do buffer de saída
- ob_get_flush — Descarrega (envia) o valor de retorno do manipulador de saída ativo, retorna o conteúdo do buffer de saída ativo e desliga-o
- ob_get_length — Retorna o comprimento do buffer de saída
- ob_get_level — Retorna o nível de aninhamento do mecanismo de buffer de saída
- ob_get_status — Obtém status dos buffers de saída
- ob_implicit_flush — Liga ou desliga o descarregamento implícito
- ob_list_handlers — Lista todos os manipuladores de saída em uso
- ob_start — Ativa o buffer de saída
- output_add_rewrite_var — Adiciona valores de reescritor de URL
- output_reset_rewrite_vars — Redefine valores de reescritor de URL

- Instalação/Configuração
  - Configurações em Execução
- Constantes predefinidas
- Buffer de Saída
- Descarregando Buffers de Sistema
- Buffers de Saída em Nível de Usuário
  - Que Saída é Armazenada em Buffer?
  - Aninhando Buffers de Saída
  - Tamanho do Buffer
  - Operações permitidas em buffers
  - Manipuladores de Saída
  - Trabalhando com Manipuladores de Saída
  - Opções Passadas aos Manipuladores de Saída
  - Valores de Retorno do Menipulador de Saída
- Exemplos
  - Uso básico
  - Uso de re-escrita na saída
- Funções para Control de Saída
  - flush — Descarrega o buffer na saída do sistema
  - ob_clean — Limpa (apaga) o conteúdo do buffer de saída ativo
  - ob_end_clean — Limpa (apaga) o conteúdo do buffer de saída ativo e desliga-o
  - ob_end_flush — Descarrega (envia) o valor de retorno do manipulador de saída ativo e desliga o buffer de saída ativo
  - ob_flush — Descarrega (envia) o valor de retorno do manipulador de saída ativo
  - ob_get_clean — Obtém o conteúdo do buffer de saída ativo e desliga-o
  - ob_get_contents — Retorna o conteúdo do buffer de saída
  - ob_get_flush — Descarrega (envia) o valor de retorno do manipulador de saída ativo, retorna o conteúdo do buffer de saída ativo e desliga-o
  - ob_get_length — Retorna o comprimento do buffer de saída
  - ob_get_level — Retorna o nível de aninhamento do mecanismo de buffer de saída
  - ob_get_status — Obtém status dos buffers de saída
  - ob_implicit_flush — Liga ou desliga o descarregamento implícito
  - ob_list_handlers — Lista todos os manipuladores de saída em uso
  - ob_start — Ativa o buffer de saída
  - output_add_rewrite_var — Adiciona valores de reescritor de URL
  - output_reset_rewrite_vars — Redefine valores de reescritor de URL

# Informações e Opções do PHP

# Introdução

Estas funções permitem obter muitas informações sobre o PHP em si, por exemplo, configurações em tempo de execução, extensões carregadas, versão e muito mais. Também podem ser encontradas funções para definir opções para o PHP em execução. A função que é provavelmente a mais conhecida do PHP - phpinfo() - pode ser encontrada aqui.

# Instalação/Configuração

## Índice

- Configurações em Execução

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de configuração do PHP
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
assert.active | "1" | `INI_ALL` | Descontinuado desde o PHP 8.3.0
assert.bail | "0" | `INI_ALL` | Descontinuado desde o PHP 8.3.0
assert.warning | "1" | `INI_ALL` | Descontinuado desde o PHP 8.3.0
assert.callback | NULL | `INI_ALL` | Descontinuado desde o PHP 8.3.0
assert.quiet_eval | "0" | `INI_ALL` | Removido desde o PHP 8.0.0
assert.exception | "1" | `INI_ALL` | Anteriormente ao PHP 8.0.0 o padrão era `"0"`. Desencorajado desde o PHP 8.3.0
enable_dl | "1" | `INI_SYSTEM` | Este recurso descontinuado será certamente removido no futuro.
max_execution_time | "30" | `INI_ALL` |
max_input_time | "-1" | `INI_PERDIR` |
max_input_nesting_level | "64" | `INI_PERDIR` |
max_input_vars | 1000 | `INI_PERDIR` |
zend.enable_gc | "1" | `INI_ALL` |
zend.max_allowed_stack_size | "0" | `INI_SYSTEM` | Disponível a partir do PHP 8.3.0.
zend.reserved_stack_size | "0" | `INI_SYSTEM` | Disponível a partir do PHP 8.3.0.
fiber.stack_size |  | `INI_ALL` | Disponível a partir do PHP 8.1.0.

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`assert.active` bool

  Ativa a avaliação de assert(). zend.assertions deve ser utilizado para controlar o comportamento de assert().

  Aviso

  Este recurso foi DESCONTINUADO a partir do PHP 8.3.0. O uso deste recurso é fortemente desencorajado.

`assert.bail` bool

  Termina a execução de scripts se uma asserção falharem.

  Aviso

  Este recurso foi DESCONTINUADO a partir do PHP 8.3.0. O uso deste recurso é fortemente desencorajado.

`assert.warning` bool

  Emite um warning para cada falha de assert.

  Aviso

  Este recurso foi DESCONTINUADO a partir do PHP 8.3.0. O uso deste recurso é fortemente desencorajado.

`assert.callback` string

  Função a chamar em caso de asserts falharem.

  Aviso

  Este recurso foi DESCONTINUADO a partir do PHP 8.3.0. O uso deste recurso é fortemente desencorajado.

`assert.quiet_eval` bool
  Aviso

  Este recurso foi REMOVIDO a partir do PHP 8.0.0.

  Utilize a configuração atual de error_reporting() durante a avaliação de expressões assert. Se ativo então nenhum erro é mostrado (padrão é error_reporting(0)) nas avaliações. Se desativa erros são mostrados de acordo com as configurações de error_reporting()

`assert.exception` bool

  Lança uma exceção AssertionError no caso de um assert falhar.

  Aviso

  Este recurso foi DESCONTINUADO a partir do PHP 8.3.0. O uso deste recurso é fortemente desencorajado.

`enable_dl` bool

  Esta diretiva permite ativar ou desativar o carregamento dinâmico de extensões do PHP com dl() .

  A razão principal para desligar o carregamento dinâmico é segurança. Com carregamento dinâmico é possível ignorar todas as restrições de open_basedir. O padrão é permitir carregamento dinâmico.

`max_execution_time` int

  Isso configura o tempo máximo, em segundos, que um script é permitido executar antes de ser terminado. Isso ajuda a prevenir que scripts mal escritos de lotar os servidores. O padrão é de `30` segundos. Quando rodando o PHP a partir da linha de comando o padrão é zero `0`.

  O tempo máximo de execução não é afetado por chamadas de sistema, operações em fluxos, etc. Veja a documentação da função set_time_limit() para mais detalhes.

  Seu servidor web pode ter outras configurações de timeout que também interrompam a execução do PHP. Apache possui uma diretiva `Timeout` e o IIS tem uma função de timeout CGI. Ambos com padrão de 300 segundos. Veja a documentação do servidor web para mais detalhes.

`max_input_time` int

  Configura o tempo máximo, em segundos, que um script é permitido dispensar interpretando dados de entrada, como GET e POST. O cronômetro começa no momento que o PHP é chamado pelo servidor e termina quando a execução começa. A configuração padrão é `-1`, o que significa que o valor de max_execution_time será usado. Defina como `0` para permitir tempo ilimitado.

`max_input_nesting_level` int

  Configura a profundidade máxima de níveis das variáveis de entrada ( $_GET, $_POST).

`max_input_vars` int

  Configura quantas variáveis de entrada serão aceitas, com o limte aplicado a cada super global $_GET, $_POST e $_COOKIE separadamente). O uso dessa diretiva mitiga a possibilidade de ataques de negação de serviço que utilizam colisões de hash. Se houver mais variáveis do que o especificado nessa diretiva um `E_WARNING` é lançado, e variáveis de entrada adicionais são ignorados.

`zend.enable_gc` bool

  Ativa ou desativa o coletor de refefências circulares.

`zend.max_allowed_stack_size` int

  O espaço máximo de pilha nativa que o sistema operacional permite que o programa consuma. Tentar consumir mais do que o sistema operacional permite normalmente resulta em uma falha grave, sem informações de depuração facilmente disponíveis. Para facilitar a depuração, o mecanismo lança uma exceção Error antes que isso aconteça (quando o programa usa mais que zend.max_allowed_stack_size-zend.reserved_stack_size bytes de pilha).

  A recursão no código definido pelo usuário não consome espaço de pilha nativo. No entanto, funções internas e métodos mágicos sim. A recursão muito profunda envolvendo essas funções pode fazer com que o programa esgote todo o espaço de pilha nativa disponível.

  Os valores possíveis para este parâmetro são:

  - `0`: Detecta automaticamente o espaço máximo de pilha nativa que o sistema operacional permite que o programa consuma. Este é o padrão. Quando a detecção não é possível, um padrão conhecido do sistema é usado.
  - `-1`: Desativa a verificação do tamanho da pilha no mecanismo.
  - Inteiro positivo: um tamanho fixo, em bytes. Definir esse valor muito alto tem o mesmo efeito que desabilitar a verificação do tamanho da pilha.

  Como o tamanho da pilha dos fibers é determinado por fiber.stack_size, o valor deste parâmetro é usado em vez do zend.max_allowed_stack_size ao verificar o uso da pilha durante a execução de um Fiber.

  > Nota:

  > Isso não está relacionado a estouros de buffer de pilha e não é um recurso de segurança.

`zend.reserved_stack_size` int

  O tamanho da pilha reservada, em bytes. Isso é subtraído do tamanho máximo permitido da pilha, como um buffer, ao verificar o tamanho da pilha.

  Os valores possíveis para este parâmetro são:

  - `0`: Detecta automaticamente um tamanho razoável.
  - Inteiro positivo: um tamanho fixo, em bytes.
`fiber.stack_size` int

  O tamanho da pilha nativa, em bytes, alocado para cada Fiber.

  O valor padrão é 1MiB em sistemas com tamanho de ponteiro inferior a 8 bytes ou 2MiB caso contrário.

# Constantes predefinidas

As constantes abaixo estão sempre disponíveis como parte do núcleo do PHP.

Constantes | Descrição
--- | ---
Constantes predefinidas da função phpcredits()
`CREDITS_GROUP` (int) | Uma lista do núcleo de desenvolvedores
`CREDITS_GENERAL` (int) | Créditos em geral: design e conceito da linguagem, autores do PHP e módulo SAPI.
`CREDITS_SAPI` (int) | Uma lista dos módulos API dos servidores para o PHP, e seus autores.
`CREDITS_MODULES` (int) | Uma lista dos módulos de extensão para o PHP, e seus autores.
`CREDITS_DOCS` (int) | Os créditos para a equipe de documentação.
`CREDITS_FULLPAGE` (int) | Normalmente usada em combinação com as outras opções. Indica que uma página HTML completa precisa ser mostrada incluindo a informação indicada pelas outras opções.
`CREDITS_QA` (int) | Os créditos para a equipe de controle de qualidade.
`CREDITS_ALL` (int) | Todos os créditos, equivalente a usar: `CREDITS_DOCS | CREDITS_GENERAL | CREDITS_GROUP | CREDITS_MODULES | CREDITS_QA | CREDITS_FULLPAGE`. Gera uma página HTML completa com as etiquetas apropriadas. Este é o valor padrão.

Constantes | Descrição
--- | ---
Constantes da função phpinfo()
`INFO_GENERAL` (int) | A linha da configuração, localização do php.ini, data de construção, servidor web, sistema e mais.
`INFO_CREDITS` (int) | Créditos do PHP. Veja também phpcredits().
`INFO_CONFIGURATION` (int) | Valores atuais e principais para as diretivas de configuração do PHP. Veja também ini_get().
`INFO_MODULES` (int) | Módulos carregados e suas respectivas configurações.
`INFO_ENVIRONMENT` (int) | Informações das variáveis de ambiente que também estão disponíveis em $_ENV.
`INFO_VARIABLES` (int) | Mostra todas as variáveis predefinidas do `EGPCS` (ENV, GET, POST, COOKIE, SERVER).
`INFO_LICENSE` (int) | Informação sobre a licença do PHP. Veja também » a seção sobre licença.
`INFO_ALL` (int) | Mostra todas as opções acima. Este é o valor padrão.

Constantes | Descrição
--- | ---
Constantes de modo INI
`INI_USER` (int) | A entrada pode der definida em scripts do usuário (como com ini_set()) ou no registro do Windows. A entrada pode ser definida no .user.ini.
`INI_PERDIR` (int) | A entrada pode der definida no php.ini, .htaccess, httpd.conf ou .user.ini.
`INI_SYSTEM` (int) | A entrada pode der definida no php.ini ou httpd.conf.
`INI_ALL` (int) | A entrada pode der definida em qualquer lugar.

Constantes de assetividade. Estes valores são usados para definir as opções de assertividade em assert_options().

Constantes | Descrição
--- | ---
Constantes da função assert()
`ASSERT_ACTIVE` (int) | Habilita avaliação da função assert(). Aviso Este recurso foi DESCONTINUADO a partir do PHP 8.3.0. O uso deste recurso é fortemente desencorajado.
`ASSERT_CALLBACK` (int) | Função de retorno a ser chamada em afirmações falhadas. Aviso Este recurso foi DESCONTINUADO a partir do PHP 8.3.0. O uso deste recurso é fortemente desencorajado.
`ASSERT_BAIL` (int) | Termina execução em afirmações falhadas. Aviso Este recurso foi DESCONTINUADO a partir do PHP 8.3.0. O uso deste recurso é fortemente desencorajado.
`ASSERT_EXCEPTION` (int) | Emite uma AssertionError para cada afirmação falhada. Aviso Este recurso foi DESCONTINUADO a partir do PHP 8.3.0. O uso deste recurso é fortemente desencorajado.
`ASSERT_WARNING` (int) | Emite um alerta do PHP para cada afirmação falhada. Aviso Este recurso foi DESCONTINUADO a partir do PHP 8.3.0. O uso deste recurso é fortemente desencorajado.
`ASSERT_QUIET_EVAL` (int) | Desabilita `error_reporting` durante avaliação de expressão de afirmação. Aviso Este recurso foi REMOVIDO a partir do PHP 8.0.0.

As constantes a seguir somente estão disponíveis se o sistema operacional do servidor for Windows, e detalham diferentes informações de versão de forma a possibilitar detecção de vários recursos e fazer uso deles.

Constantes | Descrição
--- | ---
Constantes específicas do Windows
`PHP_WINDOWS_VERSION_MAJOR` (int) | A versão principal do Windows, que pode ser `4` (NT4/Me/98/95), `5` (XP/2003 R2/2003/2000) ou `6` (Vista/2008/7/8/8.1).
`PHP_WINDOWS_VERSION_MINOR` (int) | A versão secundária do Windows, que pode ser `0` (Vista/2008/2000/NT4/95), `1` (XP), `2` (2003 R2/2003/XP x64), `10` (98) ou `90` (ME).
`PHP_WINDOWS_VERSION_BUILD` (int) | O número de construção do Windows (por exemplo, Windows Vista com SP1 aplicado tem o número 6001)
`PHP_WINDOWS_VERSION_PLATFORM` (int) | A plataforma em que o PHP está atualmente em execução, este valor é `2` no Windows Vista/XP/2000/NT4, Server 2008/2003 e `1` no Windows ME/98/95.
`PHP_WINDOWS_VERSION_SP_MAJOR` (int) | A versão principal do pacote de serviço instalado, este valor é `0` se não houver nenhum instalado. Por exemplo, Windows XP com pacote de serviço 3 instalado terá valor de `3`.
`PHP_WINDOWS_VERSION_SP_MINOR` (int) | A versão secundária do pacote de serviço instalado, este valor é `0` se não houver nenhum.
`PHP_WINDOWS_VERSION_SUITEMASK` (int) | Uma máscara de bits que informa se vários recursos do Windows estão instalados, consulte a tabela abaixo para possível valores.
`PHP_WINDOWS_VERSION_PRODUCTTYPE` (int) | Contém o valor usado para determinar as constantes `PHP_WINDOWS_NT_*`. Este valor pode ser uma das constantes `PHP_WINDOWS_NT_*` que indicam o tipo de plataforma.
`PHP_WINDOWS_NT_DOMAIN_CONTROLLER` (int) | Este é um controlador de domínio.
`PHP_WINDOWS_NT_SERVER` (int) | Este é um sistema de servidor (ex.: Server 2008/2003/2000), observe que se este for um controlador de domínio, será reportado como `PHP_WINDOWS_NT_DOMAIN_CONTROLLER`.
`PHP_WINDOWS_NT_WORKSTATION` (int) | Este é um sistema de estação de trabalho (ex.: Vista/XP/2000/NT4).

Esta tabela mostra uma lista de recursos que podem ser verificados para uso da máscara de bits `PHP_WINDOWS_VERSION_SUITEMASK`.

Campos de bits para suítes Windows
Bits | Descrição
--- | ---
`0x00000004` | Componentes do Microsoft BackOffice estão instalados.
`0x00000400` | Windows Server 2003, Web Edition está instalado.
`0x00004000` | Windows Server 2003, Compute Cluster Edition está instalado.
`0x00000080` | Windows Server 2008 Datacenter, Windows Server 2003, Datacenter Edition ou Windows 2000 Datacenter Server estão instalados.
`0x00000002` | Windows Server 2008 Enterprise, Windows Server 2003, Enterprise Edition, Windows 2000 Advanced Server ou Windows NT Server 4.0 Enterprise Edition estão instalados.
`0x00000040` | Windows XP Embedded está instalado.
`0x00000200` | Windows Vista Home Premium, Windows Vista Home Basic ou Windows XP Home Edition estão instalados.
`0x00000100` | Área de Trabalho Remota é suportada, mas somente uma sessão interativa é suportada. Este valor estará definido a menos que o sistema esteja sendo executado em modo de servidor de aplicação.
`0x00000001` | Microsoft Small Business Server foi instalado uma vez no sistema, mas pode ter sido atualizado para outra versão do Windows.
`0x00000020` | Microsoft Small Business Server está instalado com a licença de cliente restritiva.
`0x00002000` | Windows Storage Server 2003 R2 ou Windows Storage Server 2003 está instalado.
`0x00000010` | Terminal Services está instalado. Este valor sempre estará definido. Se este valor estiver definido mas `0x00000100` não estiver, então o sistema está sendo executado em modo de servidor de aplicação.
`0x00008000` | Windows Home Server está instalado.

# Funções para Opções/Info do PHP

# assert

(PHP 4, PHP 5, PHP 7, PHP 8)

assert — Executa uma asserção

### Descrição

function assert(mixed `$assertion`, Throwable|string|null `$description` = `null`): bool

assert() permite a definição de expectativas: asserções são verificadas em ambientes de desenvolvimento ou testes, mas que são removidas por otimização a custo zero em produção.

Asserções podem ser utilizadas para ajudar em depuração. Um dos usos é para funcionar como verificações de sanidade para precondições que precisam ser sempre `true` e caso elas não sejam confirmadas, isto indica algum erro de programação. Outro uso é garantir a presença de certos recursos, como por exemplo funções de extensões ou certos recursos ou limites de sistema.

As asserções podem ser configurados para serem eliminados, e elas não não devem ser utilizados em operações comuns como por exemplo a validação de parâmetros. Como regra geral, o código deve se comportar igual mesmo no caso das asserções estarem desativadas.

assert() verificará se a expectativa informada no parâmetro `assertion` é válida. Se não, o resultado avaliado é `false`, ocorrerá a ação apropriada, dependendo em como assert() está configurado.

O comportamento de assert() é ditado pelas seguintes configurações INI:

Opções de Configuração de Assert
Nome | Padrão | Descrição | Registro de Alterações
--- | --- | --- | ---
zend.assertions | `1` | `1`: gera e executa o código (modo de desenvolvimento) `0`: gera o código mas ignora durante a execução `-1`: não gera o código (modo de produção) |
assert.active | `true` | Se `false`, assert() não verifica a expectativa e retorna `true` imediatamente. | Descontinuado desde o PHP 8.3.0.
assert.callback | `null` | Uma função definida pelo usuário a ser chamada quando a asserção falha. Sua assinatura deve ser: function assert_callback( string `$file`, int `$line`, null `$assertion`, string `$description` = ? ): void | Anteriormente ao PHP 8.0.0, a assinatura deveria ser: function assert_callback( string `$file`, int `$line`, string `$assertion`, string `$description` = ? ): void Descontinuado a partir do PHP 8.3.0.
assert.exception | `true` | Se `true` irá lançar um AssertionError no caso da expectativa não ser válida. | Descontinuado desde o PHP 8.3.0.
assert.bail | `false` | Se `true` então a execução do script PHP será abortada caso a expectativa não seja válida. | Descontinuado desde o PHP 8.3.0.
assert.warning | `true` | Se `true`, será emitido um `E_WARNING` no caso da expectativa não seja válida. Essa configuração INI é inefetiva caso assert.exception esteja ativo. | Descontinuado desde o PHP 8.3.0.

### Parâmetros

`assertion`

  Pode ser qualquer expressão que retorna um valor, qual será executado e o resultado é utilizado para indicar se a asserção deve passar ou falhar.

  Aviso

  Anteriormente ao PHP 8.0.0, se `assertion` era uma string ela era interpretada como código PHP e executada via eval(). A string era passada para o argumento do callback no terceiro argumento. Este comportamento está DESCONTINUADO desde o PHP 7.2.0, e foi REMOVIDO no PHP 8.0.0.

`description`

  Se `description` é uma instância de Throwable, ela será lançada somente se `assertion` for executada e falhar.

  > Nota:

  > A partir do 8.0.0, isto ocorria antes de chamar a função de callback potencialmente definida.

  > Nota:

  > A partir do PHP 8.0.0, o object será lançado independente da configuração de assert.exception.

  > Nota:

  > A partird do PHP 8.0.0, a configuração assert.bail não terá efeito nesse caso.

  Se `description` é uma string esta mensagem será utilizada em uma exceção ou em um aviso. Uma descrição opcional que será incluída na mensagem de falha no caso de `assertion` falhar.

  Se `description` é omitido. Uma descrição padrão, igual ao código fonte na invocação de assert() é criada em tempo de compilação.

### Valor Retornado

assert() sempre retorna `true` se ao menos uma das seguintes condições forem verdadeiras:

- `zend.assertions=0`
- `zend.assertions=-1`
- `assert.active=0`
- `assert.exception=1`
- `assert.bail=1`
- Um objeto exception foi passado em `description`.

Se nenhuma das condições forem verdadeiras assert() ainda pode retornar `true` se `assertion` possa ser convertido em um valor verdadeiro, ou `false` nos demais casos.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Todas as configurações INI `assert.` estão desencorajadas.
8.0.0 | assert() não mais avaliará argumentos strings, e por outro lado elas serão tratadas como um argumento comum. `assert($a == $b)` deve ser utilizado ao invés de `assert('$a == $b')`. A diretiva `assert.quiet_eval` php.ini e a constante `ASSERT_QUIET_EVAL` também foram removidos, dado que elas não tem mais nenhum efeito.
8.0.0 | Se `description` é uma instância de Throwable, a exceção é lançada no caso da asserção falhar, independentemente do valor de assert.exception.
8.0.0 | Se `description` é uma instância de Throwable, o callback não é chamado, mesmo que ele seja informado.
8.0.0 | Declarar uma função chamada `assert()` dentro de um namespace não é mais permitido, e emite um `E_COMPILE_ERROR`.
7.3.0 | Declarar uma função chamada `assert()` dentro de um namespace foi descontinuado. Uma declaração assim emite um `E_DEPRECATED`.
7.2.0 | Uso de strings no argumento `assertion` foi descontinuado. Isto agora emite um aviso `E_DEPRECATED` quando ambos assert.active e zend.assertions estão configurados para `1`.

### Exemplos

Exemplo #1 Exemplo de assert()

    <?php
    assert(1 > 2);
    echo 'Hi!';

Se as asserções estiverem ativadas (`zend.assertions=1`), o exemplo acima emitirá:

    Fatal error: Uncaught AssertionError: assert(1 > 2) in example.php:2
    Stack trace:
    #0 example.php(2): assert(false, 'assert(1 > 2)')
    #1 {main}
      thrown in example.php on line 2

Se as asserções estiverem desativadas (`zend.assertions=0` ou `zend.assertions=-1`), o exemplo acima emitirá:

    Hi!

Exemplo #2 Utilizando uma mensagem customizada

    <?php
    assert(1 > 2, "Esperado que um seja maior que dois");
    echo 'Hi!';

Se as asserções estiverem ativadas, o código acima emitirá:

    Fatal error: Uncaught AssertionError: Esperado que um seja maior que dois in example.php:2
    Stack trace:
    #0 example.php(2): assert(false, 'Esperado que um...')
    #1 {main}
      thrown in example.php on line 2

Se as asserções estiverem desativadas, o código acima emitirá:

    Hi!

Exemplo #3 Utilizando uma classe de exceção

    <?php
    class ArithmeticAssertionError extends AssertionError {}

    assert(1 > 2, new ArithmeticAssertionError("Esperado que um seja maior que dois"));
    echo 'Hi!';

Se as asserções estiverem ativas, o exemplo acima emitirá:

    Fatal error: Uncaught ArithmeticAssertionError: Esperado que um seja maior que dois in example.php:4
    Stack trace:
    #0 {main}
      thrown in example.php on line 4

Se as asserções estiverem desativadas o exemplo acima emitirá:

    Hi!

### Veja Também

- assert_options() - Define/obtém as várias opções de asserção

# assert_options

(PHP 4, PHP 5, PHP 7, PHP 8)

assert_options — Define/obtém as várias opções de asserção

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.3.0. O uso desta função é fortemente desencorajado.

### Descrição

function assert_options(int `$option`, mixed `$value` = ?): mixed

Define as várias opções de controle de assert() ou apenas consulta suas várias configurações.

> Nota: O uso de assert_options() é desencorajado em favor de definir e obter as diretivas zend.assertions e assert.exception do php.ini com ini_set() e ini_get(), respectivamente.

### Parâmetros

`option`

  Opções de Asserção
  Opção | Configuração INI | Valor padrão | Descrição
  --- | --- | --- | ---
  ASSERT_ACTIVE | assert.active | 1 | habilita avaliação de assert()
  ASSERT_EXCEPTION | assert.exception | 1 | lança uma exceção AssertionError para cada asserção falhada
  ASSERT_WARNING | assert.warning | 1 | emite um alerta PHP para cada asserção falhada
  ASSERT_BAIL | assert.bail | 0 | termina a execução em asserções falhadas
  ASSERT_QUIET_EVAL | assert.quiet_eval | 0 | desabilita registro de erros durante avaliação de expressões de asserção. Removido a partir do PHP 8.0.0.
  ASSERT_CALLBACK | assert.callback | (`null`) | Função de retorno a ser chamada em asserções falhadas

`value`

  Um novo valor opcional para a opção.

  A função de retorno definida via `ASSERT_CALLBACK` ou assert.callback deve ter a seguinte assinatura:

  function assert_callback(
  string `$file`,
  int `$line`,
  ?string `$assertion`,
  string `$description` = ?
  ): void
  `file`
    O arquivo onde assert() foi chamada.
  `line`
    A linha onde assert() foi chamada.
  `assertion`
    Antes do PHP 8.0.0, a asserção que foi passada a assert(), mas somente quando a asserção for informada como uma string. (Se a asserção for uma condição booleana, este parâmetro será uma string vazia.) A partir do PHP 8.0.0, este parâmetro é sempre `null`.
  `description`
    A descrição que foi passada a assert().

Passar uma string vazia no parâmetro `value` redefine a função de retorno da asserção.

### Valor Retornado

Retorna a configuração original de qualquer opção.

### Erros/Exceções

Se `option` não for uma opção válida, uma exceção ValueError é lançada.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | assert_options() agora foi descontinuada.
8.0.0 | Se `option` não for uma opção válida, uma exceção ValueError é lançada. Anteriormente, `false` era retornado.

### Exemplos

Exemplo #1 Exemplo de assert_options()

    <?php
    // Esta é nossa função para manipular
    // falhas de asserção
    function assert_failure($file, $line, $assertion, $message)
    {
        echo "A asserção $assertion em $file na linha $line falhou: $message";
    }

    // Esta é nossa função de teste
    function test_assert($parameter)
    {
        assert(is_bool($parameter));
    }

    // Define as opções de asserção
    assert_options(ASSERT_ACTIVE,   true);
    assert_options(ASSERT_BAIL,     true);
    assert_options(ASSERT_WARNING,  false);
    assert_options(ASSERT_CALLBACK, 'assert_failure');

    // Cria uma asserção que iria falhar
    test_assert(1);

    // Isto nunca é alcançado devido a ASSERT_BAIL
    // definido como verdadeiro
    echo 'Nunca alcançado';
    ?>

### Veja Também

- assert() - Executa uma asserção

# cli_get_process_title

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

cli_get_process_title — Retorna o título do processo atual

### Descrição

function cli_get_process_title(): ?string

Retorna o título do processo atual, conforme definido por cli_set_process_title(). Observe que isso pode não corresponder exatamente ao que é mostrado em ps ou top, dependendo do seu sistema operacional.

Esta função está disponível somente no modo CLI.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string com o título do processo atual ou `null` em caso de erro.

### Erros/Exceções

Um `E_WARNING` será gerado se o sistema operacional não for compatível.

### Exemplos

Exemplo #1 Exemplo de cli_get_process_title()

    <?php
    echo "Título do processo: " . cli_get_process_title() . "\n";
    ?>

### Veja Também

- cli_set_process_title() - Define o título do processo

# cli_set_process_title

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

cli_set_process_title — Define o título do processo

### Descrição

function cli_set_process_title(string `$title`): bool

Define o título do processo, visível em ferramentas como top e ps. Esta função está disponível apenas no modo CLI.

### Parâmetros

`title`
  O novo título.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Um `E_WARNING` será gerado se o sistema operacional não for compatível.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | cli_set_process_title() agora emite um `E_WARNING` ao definir um título muito longo para um processo; anteriormente o título seria truncado.

### Exemplos

    <?php
    $title = "Meu Super Script PHP";
    $pid = getmypid(); // pode-se usar isto para ver o título do processo no comando "ps"

    if (!cli_set_process_title($title)) {
        echo "Não foi possível definir o título do processo para o PID $pid...\n";
        exit(1);
    } else {
        echo "O título '$title' para o PID $pid foi definido para o seu processo!\n";
        sleep(5);
    }
    ?>

### Veja Também

- cli_get_process_title() - Retorna o título do processo atual

# dl

(PHP 4, PHP 5, PHP 7, PHP 8)

dl — Carrega uma extensão do PHP durante a execução

### Descrição

function dl(string `$extension_filename`): bool

Carrega a extensão do PHP indicada pelo parâmetro `extension_filename`.

Use extension_loaded() para testar se uma extensão está disponível ou não. Isto funciona para extensões internas e para aquelas carregadas dinamicamente (através do php.ini ou da função dl()).

Aviso

Esta função somente está disponível no modos CLI e SAPI internalizado, e na SAPI CGI quando rodado em linha de comando.

### Parâmetros

`extension_filename`

  Este parâmetro é somente o nome do arquivo da extensão a carregar o qual também depende da sua plataforma. Por exemplo, a extensão sockets (se compilada como módulo compartilhado, não o padrão!) seria chamada sockets.so em plataformas Unix enquanto é chamada php_sockets.dll na plataforma Windows.

  O diretório a partir do qual a extensão é carregada depende da sua plataforma:

  Windows - Se não for explicitamente definido no php.ini, a extensão é carregada a partir de C:\php5\ por padrão.

  Unix - Se não for explicitamente definido no php.ini, o diretório padrão das extensões depende de

  - se o PHP foi compilado com `--enable-debug` ou não
  - se o PHP foi compilado com suporte ZTS (Zend Thread Safety) ou não
  - O `ZEND_MODULE_API_NO` (o número Zend internal module API, o que é basicamente a data onde houve uma mudança maior na API ex. `20010901`)
  Levando em conta o acima, o diretório padrão poderá ser `<install-dir>/lib/php/extensions/ <debug-or-not>-<zts-or-not>-ZEND_MODULE_API_NO`, e.g. /usr/local/php/lib/php/extensions/debug-non-zts-20010901 ou /usr/local/php/lib/php/extensions/no-debug-zts-20010901.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha. Se a funcionalidade de carregar módulos não estiver disponível ou foi desabilitada (por configurar enable_dl como off no php.ini) então um erro `E_ERROR` é disparado e a execução é interrompida. Se dl() falhar porque a biblioteca especificada não puder ser carregada, além de retornar `false` uma mensagem `E_WARNING` é emitida.

### Exemplos

Exemplo #1 Exemplos de dl()

    <?php
    // Exemplo de carregamento de uma extensão com base no sistema operacional
    if (!extension_loaded('sqlite')) {
        if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
            dl('php_sqlite.dll');
        } else {
            dl('sqlite.so');
        }
    }

    // Ou, a constante PHP_SHLIB_SUFFIX está disponível desde o PHP 4.3.0
    if (!extension_loaded('sqlite')) {
        $prefix = (PHP_SHLIB_SUFFIX === 'dll') ? 'php_' : '';
        dl($prefix . 'sqlite.' . PHP_SHLIB_SUFFIX);
    }
    ?>

### Notas

> Nota:

> dl() diferencia maiúsculas e minúsculas em sistemas Unix.

### Veja Também

- Diretivas de carregamento de extensões
- extension_loaded() - Descobre se uma extensão está carregada

# extension_loaded

(PHP 4, PHP 5, PHP 7, PHP 8)

extension_loaded — Descobre se uma extensão está carregada

### Descrição

function extension_loaded(string `$extension`): bool

Descobre se uma extensão está carregada.

### Parâmetros

`extension`

  O nome da extensão. O parâmetro não faz distinção de maiúsculas/minúsculas.

  Pode-se ver os nomes de várias extensões usando phpinfo(); ou se estiver sendo usada a versão `CGI` ou `CLI` do PHP, pode-se usar a opção -m para listar todas as extensões disponíveis:

      $ php -m
      [PHP Modules]
      xml
      tokenizer
      standard
      sockets
      session
      posix
      pcre
      overload
      mysql
      mbstring
      ctype

      [Zend Modules]

### Valor Retornado

Retorna `true` se a extensão identificada por `extension` estiver carregada, `false` caso contrário.

### Exemplos

Exemplo #1 Exemplo de extension_loaded()

    <?php
    if (!extension_loaded('gd')) {
        if (!dl('gd.so')) {
            exit;
        }
    }
    ?>

### Veja Também

- get_loaded_extensions() - Retorna um array com os nomes de todos os módulos compilados e carregados
- get_extension_funcs() - Retorna um array com os nomes das funções de um módulo
- phpinfo() - Mostra informações sobre a configuração do PHP
- dl() - Carrega uma extensão do PHP durante a execução
- function_exists() - Retorna true se a função informada estiver definida

# gc_collect_cycles

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_collect_cycles — Força a coleta de quaisquer ciclos de lixo existentes.

### Descrição

function gc_collect_cycles(): int

Força a coleta de quaisquer ciclos de lixo existentes.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número de ciclos coletados.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | O valor de retorno não mais inclui strings e recursos que foram indiretamente coletados através dos ciclos.

### Veja Também

- Coleta de Lixo

# gc_disable

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_disable — Desativa o coletor de referência circular

### Descrição

function gc_disable(): void

Desativa o coletor de referência circular, definindo zend.enable_gc para `0`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

### Veja Também

- Coleta de Lixo

# gc_enable

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_enable — Ativa o coletor de referência circular

### Descrição

function gc_enable(): void

Ativa o coletor de referência circular, definindo zend.enable_gc para `1`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

### Veja Também

- Coleta de Lixo

# gc_enabled

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_enabled — Retorna o status do coletor de referência circular

### Descrição

function gc_enabled(): bool

Retorna o status do coletor de referência circular.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se o coletor de lixo estiver habilitado, `false` caso contrário.

### Exemplos

Exemplo #1 Um exemplo de gc_enabled()

    <?php
    if(gc_enabled()) gc_collect_cycles();
    ?>

### Veja Também

- Coleta de Lixo

# gc_mem_caches

(PHP 7, PHP 8)

gc_mem_caches — Recupera memória usada pelo gerenciador de memória Zend Engine

### Descrição

function gc_mem_caches(): int

Recupera memória usada pelo gerenciador de memória Zend Engine.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número de bytes liberados.

### Veja Também

- Coleta de Lixo

# gc_status

(PHP 7 >= 7.3.0, PHP 8)

gc_status — Obtém informações sobre o coletor de lixo

### Descrição

function gc_status(): array

Obtém informações sobre o status atual do coletor de lixo.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array associativo com os seguintes elementos:

- `"runs"`
- `"collected"`
- `"threshold"`
- `"roots"`
- `"running"`
- `"protected"`
- `"full"`
- `"buffer_size"`
- `"application_time"`
- `"collector_time"`
- `"destructor_time"`
- `"free_time"`

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | gc_status() agora retorna os seguintes campos adicionais: `"running"`, `"protected"`, `"full"`, `"buffer_size"`, `"application_time"`, `"collector_time"`, `"destructor_time"` e `"free_time"`.

### Exemplos

Exemplo #1 Uso de gc_status()

    <?php

    // cria árvore de objetos que precisam de coleta de lixo
    $a = new stdClass();
    $a->b = [];
    for ($i = 0; $i < 100000; $i++) {
        $b = new stdClass();
        $b->a = $a;
        $a->b[] = $b;
    }
    unset($a);
    unset($b);
    gc_collect_cycles();

    var_dump(gc_status());

O exemplo acima produzirá algo semelhante a:

    array(4) {
      ["runs"]=>
      int(5)
      ["collected"]=>
      int(100002)
      ["threshold"]=>
      int(50001)
      ["roots"]=>
      int(0)
    }

A saída do exemplo acima no PHP 8.3 é semelhante a:

    array(12) {
      ["running"]=>
      bool(false)
      ["protected"]=>
      bool(false)
      ["full"]=>
      bool(false)
      ["runs"]=>
      int(5)
      ["collected"]=>
      int(100002)
      ["threshold"]=>
      int(50001)
      ["buffer_size"]=>
      int(131072)
      ["roots"]=>
      int(0)
      ["application_time"]=>
      float(0.031182458)
      ["collector_time"]=>
      float(0.020106291)
      ["destructor_time"]=>
      float(0)
      ["free_time"]=>
      float(0.003707167)
    }

### Veja Também

- Coleta de Lixo

# get_cfg_var

(PHP 4, PHP 5, PHP 7, PHP 8)

get_cfg_var — Obtém o valor de uma opção de configuração do PHP

### Descrição

function get_cfg_var(string `$option`): string|array|false

Obtém o valor de uma opção de configuração do PHP definida em `option`.

Esta função não retornará informações de configuração definidas quando o PHP foi compilado ou lidas de um arquivo de configuração do Apache.

Para verificar se o sistema está usando um arquivo de configuração, tente recuperar o valor da configuração cfg_file_path. Se estiver disponível, um arquivo de configuração está sendo usado.

### Parâmetros

`option`

  O nome da opção de configuração.

### Valor Retornado

Retorna o valor atual da variável de configuração do PHP especificada por `option` ou `false` se ocorrer um erro.

### Veja Também

- ini_get() - Obtém o valor de uma opção de configuração
- ini_get_all() - Obtém todas as opções de configuração

# get_current_user

(PHP 4, PHP 5, PHP 7, PHP 8)

get_current_user — Obtém o nome do proprietário do script PHP atual

### Descrição

function get_current_user(): string

Obtém o nome do proprietário do script PHP atual.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o nome de usuário como uma string.

### Exemplos

Exemplo #1 Exemplo de get_current_user()

    <?php
    echo 'Proprietário do script atual: ' . get_current_user();
    ?>

O exemplo acima produzirá algo semelhante a:

    Proprietário do script atual: SYSTEM

### Veja Também

- getmyuid() - Obtém o UID do proprietário do script PHP
- getmygid() - Obtém o GID do proprietário do script PHP
- getmypid() - Obtém o ID do processo PHP
- getmyinode() - Obtém o inode do script atual
- getlastmod() - Obtém o horário da última modificação na página

# get_defined_constants

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

get_defined_constants — Retorna um array associativo com os nomes de todas as constantes e seus valores

### Descrição

function get_defined_constants(bool `$categorize` = `false`): array

Retorna os nomes e valores de todas as constantes definidas atualmente. Isto inclui aquelas criadas por extensões, bem como aquelas criados com a função define().

### Parâmetros

`categorize`

  Faz com que esta função retorne um array multidimensional com categorias nas chaves da primeira dimensão e constantes e seus valores na segunda dimensão.

      <?php
      define("MY_CONSTANT", 1);
      print_r(get_defined_constants(true));
      ?>

  O exemplo acima produzirá algo semelhante a:

      Array
      (
          [Core] => Array
              (
                  [E_ERROR] => 1
                  [E_WARNING] => 2
                  [E_PARSE] => 4
                  [E_NOTICE] => 8
                  [E_CORE_ERROR] => 16
                  [E_CORE_WARNING] => 32
                  [E_COMPILE_ERROR] => 64
                  [E_COMPILE_WARNING] => 128
                  [E_USER_ERROR] => 256
                  [E_USER_WARNING] => 512
                  [E_USER_NOTICE] => 1024
                  [E_ALL] => 2047
                  [TRUE] => 1
              )

          [pcre] => Array
              (
                  [PREG_PATTERN_ORDER] => 1
                  [PREG_SET_ORDER] => 2
                  [PREG_OFFSET_CAPTURE] => 256
                  [PREG_SPLIT_NO_EMPTY] => 1
                  [PREG_SPLIT_DELIM_CAPTURE] => 2
                  [PREG_SPLIT_OFFSET_CAPTURE] => 4
                  [PREG_GREP_INVERT] => 1
              )

          [user] => Array
              (
                  [MY_CONSTANT] => 1
              )

      )

### Valor Retornado

Retorna um array de nome de constante => valor da constante, opcionalmente agrupado por nome de extensão que registrou a constante.

### Exemplos

Exemplo #1 Exemplo de get_defined_constants()

    <?php
    print_r(get_defined_constants());
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [E_ERROR] => 1
        [E_WARNING] => 2
        [E_PARSE] => 4
        [E_NOTICE] => 8
        [E_CORE_ERROR] => 16
        [E_CORE_WARNING] => 32
        [E_COMPILE_ERROR] => 64
        [E_COMPILE_WARNING] => 128
        [E_USER_ERROR] => 256
        [E_USER_WARNING] => 512
        [E_USER_NOTICE] => 1024
        [E_ALL] => 2047
        [TRUE] => 1
    )

### Veja Também

- defined() - Verifica se existe uma constante com o nome informado
- constant() - Retorna o valor de uma constante
- get_loaded_extensions() - Retorna um array com os nomes de todos os módulos compilados e carregados
- get_defined_functions() - Retorna um array com todas as funções definidas
- get_defined_vars() - Retorna um array com todas variáveis definidas

# get_extension_funcs

(PHP 4, PHP 5, PHP 7, PHP 8)

get_extension_funcs — Retorna um array com os nomes das funções de um módulo

### Descrição

function get_extension_funcs(string `$extension`): array|false

Esta função retorna os nomes de todas as funções definidas no módulo indicado por `extension`.

### Parâmetros

`extension`

  O nome do módulo.

  > Nota:

  > Este parâmetro precisa estar em minúsculas.

### Valor Retornado

Retorna um array com todas as funções, ou `false` se `extension` não for uma extensão válida.

### Exemplos

Exemplo #1 Imprime as funções de XML

    <?php
    print_r(get_extension_funcs("xml"));
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => xml_parser_create
        [1] => xml_parser_create_ns
        [2] => xml_set_object
        [3] => xml_set_element_handler
        [4] => xml_set_character_data_handler
        [5] => xml_set_processing_instruction_handler
        [6] => xml_set_default_handler
        [7] => xml_set_unparsed_entity_decl_handler
        [8] => xml_set_notation_decl_handler
        [9] => xml_set_external_entity_ref_handler
        [10] => xml_set_start_namespace_decl_handler
        [11] => xml_set_end_namespace_decl_handler
        [12] => xml_parse
        [13] => xml_parse_into_struct
        [14] => xml_get_error_code
        [15] => xml_error_string
        [16] => xml_get_current_line_number
        [17] => xml_get_current_column_number
        [18] => xml_get_current_byte_index
        [19] => xml_parser_free
        [20] => xml_parser_set_option
        [21] => xml_parser_get_option
    )

### Veja Também

- get_loaded_extensions() - Retorna um array com os nomes de todos os módulos compilados e carregados
- ReflectionExtension::getFunctions() - Obtém funções de extensão

# get_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

get_include_path — Obtém a opção de configuração include_path atual

### Descrição

function get_include_path(): string|false

Obtém a opção de configuração include_path atual.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o caminho, como uma string, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de get_include_path()

    <?php
    echo get_include_path();

    // Ou usando ini_get()
    echo ini_get('include_path');
    ?>

### Veja Também

- ini_get() - Obtém o valor de uma opção de configuração
- restore_include_path() - Restaura o valor da opção de configuração include_path
- set_include_path() - Define a opção de configuração include_path
- include - include

# get_included_files

(PHP 4, PHP 5, PHP 7, PHP 8)

get_included_files — Retorna um array com os nomes dos arquivos incluídos ou requeridos

### Descrição

function get_included_files(): array

Obtém os nomes de todos os arquivos que foram incluídos usando include, include_once, require ou require_once.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array com os nomes de todos os arquivos.

O script chamado originalmente é considerado um "arquivo incluído", portanto será listado junto com os arquivos referenciados por include e cia.

Os arquivos incluídos ou requeridos várias vezes aparecem apenas uma vez no array retornado.

### Exemplos

Exemplo #1 Exemplo de get_included_files()

    <?php
    // Este arquivo é o abc.php

    include 'test1.php';
    include_once 'test2.php';
    require 'test3.php';
    require_once 'test4.php';

    $included_files = get_included_files();

    foreach ($included_files as $filename) {
        echo "$filename\n";
    }

    ?>

O exemplo acima produzirá:

    /caminho/para/abc.php
    /caminho/para/test1.php
    /caminho/para/test2.php
    /caminho/para/test3.php
    /caminho/para/test4.php

### Veja Também

- include - include
- include_once - include_once
- require - require
- require_once - require_once
- get_required_files() - Sinônimo de get_included_files

# get_loaded_extensions

(PHP 4, PHP 5, PHP 7, PHP 8)

get_loaded_extensions — Retorna um array com os nomes de todos os módulos compilados e carregados

### Descrição

function get_loaded_extensions(bool `$zend_extensions` = `false`): array

Esta função retorna os nomes de todos os módulos compilados e carregados no interpretador PHP.

### Parâmetros

`zend_extensions`

  Retorna apenas extensões Zend, caso contrário, extensões comuns, como mysqli, serão listadas. O padrão é `false` (retorna extensões comuns).

### Valor Retornado

Retorna um array indexado com todos os nomes dos módulos.

### Exemplos

Exemplo #1 Exemplo de get_loaded_extensions()

    <?php
    print_r(get_loaded_extensions());
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Core
        [1] => date
        [2] => libxml
        [3] => pcre
        [4] => sqlite3
        [5] => zlib
        [6] => ctype
        [7] => dom
        [8] => fileinfo
        [9] => filter
        [10] => hash
        [11] => json
        [12] => mbstring
        [13] => SPL
        [14] => PDO
        [15] => session
        [16] => posix
        [17] => Reflection
        [18] => standard
        [19] => SimpleXML
        [20] => pdo_sqlite
        [21] => Phar
        [22] => tokenizer
        [23] => xml
        [24] => xmlreader
        [25] => xmlwriter
        [26] => gmp
        [27] => iconv
        [28] => intl
        [29] => bcmath
        [30] => sodium
        [31] => Zend OPcache
    )

### Veja Também

- get_extension_funcs() - Retorna um array com os nomes das funções de um módulo
- extension_loaded() - Descobre se uma extensão está carregada
- dl() - Carrega uma extensão do PHP durante a execução
- phpinfo() - Mostra informações sobre a configuração do PHP

# get_magic_quotes_gpc

(PHP 4, PHP 5, PHP 7)

get_magic_quotes_gpc — Obtém a configuração atual de magic_quotes_gpc

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.4.0 e foi REMOVIDA a partir do PHP 8.0.0. O uso desta função é fortemente desencorajado.

### Descrição

function get_magic_quotes_gpc(): false

Sempre retorna `false`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Sempre retorna `false`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Esta função foi removida.
7.4.0 | Esta função foi descontinuada.

### Veja Também

- addslashes() - Adiciona barras invertidas a uma string
- stripslashes() - Desfaz os escapes de uma string escapada
- get_magic_quotes_runtime() - Obtém a configuração ativa para magic_quotes_runtime
- ini_get() - Obtém o valor de uma opção de configuração

# get_magic_quotes_runtime

(PHP 4, PHP 5, PHP 7)

get_magic_quotes_runtime — Obtém a configuração ativa para magic_quotes_runtime

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.4.0 e foi REMOVIDA a partir do PHP 8.0.0. O uso desta função é fortemente desencorajado.

### Descrição

function get_magic_quotes_runtime(): false

Sempre retorna `false`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Sempre retorna `false`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Esta função foi removida.
7.4.0 | Esta função foi descontinuada.

### Veja Também

- get_magic_quotes_gpc() - Obtém a configuração atual de magic_quotes_gpc

# get_required_files

(PHP 4, PHP 5, PHP 7, PHP 8)

get_required_files — Sinônimo de get_included_files()

### Descrição

Esta função é um apelido para: get_included_files().

# get_resources

(PHP 7, PHP 8)

get_resources — Retorna recursos ativos

### Descrição

function get_resources(?string `$type` = `null`): array

Retorna um array de todos os recursos do tipo resource atualmente ativos, opcionalmente filtrados por tipo de recurso.

> Nota: Esta função destina-se a fins de depuração e teste. Não deve ser usada em ambientes de produção, especialmente para não acessar ou mesmo manipular recursos que normalmente não são acessíveis (por exemplo, o recurso de fluxo subjacente de instâncias de SplFileObject).

### Parâmetros

`type`

  Se definido, isso fará com que get_resources() retorne apenas recursos do tipo especificado. Uma lista de tipos de recursos está disponível.

  Se a string `Unknown` for fornecida como o tipo, somente os recursos de tipo desconhecido serão retornados.

  Se omitido, todos os recursos serão devolvidos.

### Valor Retornado

Retorna um array de recursos atualmente ativos, indexados pelo número do recurso.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `type` agora pode ser nulo.

### Exemplos

Exemplo #1 get_resources() sem filtro

    <?php
    $fp = tmpfile();
    var_dump(get_resources());
    ?>

O exemplo acima produzirá algo semelhante a:

    array(1) {
      [1]=>
      resource(1) of type (stream)
    }

Exemplo #2 get_resources() com filtro

    <?php
    $fp = tmpfile();
    var_dump(get_resources('stream'));
    var_dump(get_resources('curl'));
    ?>

O exemplo acima produzirá algo semelhante a:

    array(1) {
      [1]=>
      resource(1) of type (stream)
    }
    array(0) {
    }

### Veja Também

- get_loaded_extensions() - Retorna um array com os nomes de todos os módulos compilados e carregados
- get_defined_constants() - Retorna um array associativo com os nomes de todas as constantes e seus valores
- get_defined_functions() - Retorna um array com todas as funções definidas
- get_defined_vars() - Retorna um array com todas variáveis definidas

# getenv

(PHP 4, PHP 5, PHP 7, PHP 8)

getenv — Obtém o valor de uma única ou de todas as variáveis ​​de ambiente

### Descrição

function getenv(?string `$name` = `null`, bool `$local_only` = `false`): string|array|false

Obtém o valor de uma única ou de todas as variáveis ​​de ambiente.

Uma lista de todas as variáveis dem ambiente pode ser vista usando phpinfo(). Muitas dessas variáveis ​​estão listadas na » RFC 3875, especificamente na seção 4.1, "Request Meta-Variables".

### Parâmetros

`name`

  O nome da variável como uma string ou `null`.

`local_only`

  Quando definido como `true`, apenas variáveis ​​de ambiente locais são retornadas, definidas pelo sistema operacional ou por putenv. Só tem efeito quando `name` é uma string.

### Valor Retornado

Retorna o valor da variável de ambiente `name` ou `false` se a variável de ambiente `name` não existir. Se `name` for `null`, todas as variáveis ​​de ambiente serão retornadas como um array associativo.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `name` agora pode ser nulo.
7.1.0 | O `name` agora pode ser omitido para recuperar um array associativo de todas as variáveis ​​de ambiente.
7.0.9 | O parâmetro `local_only` foi adicionado.

### Exemplos

Exemplo #1 Exemplo de getenv()

    <?php
    // Exemplo de uso de getenv()
    $ip = getenv('REMOTE_ADDR');

    // Ou simplesmente usa uma variável super global ($_SERVER ou $_ENV)
    $ip = $_SERVER['REMOTE_ADDR'];

    // Obtenha com segurança o valor de uma variável de ambiente, ignorando se
    // ela foi definida ou não por uma SAPI ou se foi alterada com putenv
    $ip = getenv('REMOTE_ADDR', true) ?: getenv('REMOTE_ADDR')
    ?>

### Notas

Aviso

Se o PHP estiver sendo executado em uma SAPI como o Fast CGI, esta função sempre retornará o valor de uma variável de ambiente definida pela SAPI, mesmo que putenv() tenha sido usada para definir uma variável de ambiente local de mesmo nome. Use o parâmetro `local_only` para retornar o valor das variáveis ​​de ambiente definidas localmente.

### Veja Também

- putenv() - Define o valor de uma variável de ambiente
- apache_getenv() - Retorna uma variável subprocess_env do Apache
- Super Globais

# getlastmod

(PHP 4, PHP 5, PHP 7, PHP 8)

getlastmod — Obtém o horário da última modificação na página

### Descrição

function getlastmod(): int|false

Obtém o horário da última modificação do script principal de execução.

Se o objetivo for obter o horário da última modificação de um arquivo diferente, considere usar filemtime().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o tempo da última modificação na página atual. O valor é retornado como um timestamp Unix, útil para usar com a função date(). Retorna `false` em caso de erro.

### Exemplos

Exemplo #1 Exemplo de getlastmod()

    <?php
    // mostra por exemplo 'Última Modificação: March 04 1998 20:43:59.'
    echo "Última Modificação: " . date ("F d Y H:i:s.", getlastmod());
    ?>

### Veja Também

- date() - Formata um timestamp Unix
- getmyuid() - Obtém o UID do proprietário do script PHP
- getmygid() - Obtém o GID do proprietário do script PHP
- get_current_user() - Obtém o nome do proprietário do script PHP atual
- getmyinode() - Obtém o inode do script atual
- getmypid() - Obtém o ID do processo PHP
- filemtime() - Obtém o horário de modificação do arquivo

# getmygid

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

getmygid — Obtém o GID do proprietário do script PHP

### Descrição

function getmygid(): int|false

Obtém o ID do grupo do script atual.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ID do grupo do script atual, ou `false` em caso de erro.

### Veja Também

- getmyuid() - Obtém o UID do proprietário do script PHP
- getmypid() - Obtém o ID do processo PHP
- get_current_user() - Obtém o nome do proprietário do script PHP atual
- getmyinode() - Obtém o inode do script atual
- getlastmod() - Obtém o horário da última modificação na página

# getmyinode

(PHP 4, PHP 5, PHP 7, PHP 8)

getmyinode — Obtém o inode do script atual

### Descrição

function getmyinode(): int|false

Obtém o inode do script atual.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o inode do script atual como um número inteiro ou `false` em caso de erro.

### Veja Também

- getmygid() - Obtém o GID do proprietário do script PHP
- getmyuid() - Obtém o UID do proprietário do script PHP
- getmypid() - Obtém o ID do processo PHP
- get_current_user() - Obtém o nome do proprietário do script PHP atual
- getlastmod() - Obtém o horário da última modificação na página

# getmypid

(PHP 4, PHP 5, PHP 7, PHP 8)

getmypid — Obtém o ID do processo PHP

### Descrição

function getmypid(): int|false

Obtém o ID do processo atual do PHP.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ID do processo atual do PHP, ou `false` em caso de erro.

### Notas

Aviso

IDs de processos não são únicos, portanto são uma fonte de entropia fraca. Recomenda-se não confiar em PIDs em contextos que dependam de segurança.

### Veja Também

- getmygid() - Obtém o GID do proprietário do script PHP
- getmyuid() - Obtém o UID do proprietário do script PHP
- get_current_user() - Obtém o nome do proprietário do script PHP atual
- getmyinode() - Obtém o inode do script atual
- getlastmod() - Obtém o horário da última modificação na página

# getmyuid

(PHP 4, PHP 5, PHP 7, PHP 8)

getmyuid — Obtém o UID do proprietário do script PHP

### Descrição

function getmyuid(): int|false

Obtém o ID do usuário do script atual.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ID do usuário do script atual, ou `false` em caso de erro.

### Veja Também

- getmygid() - Obtém o GID do proprietário do script PHP
- getmypid() - Obtém o ID do processo PHP
- get_current_user() - Obtém o nome do proprietário do script PHP atual
- getmyinode() - Obtém o inode do script atual
- getlastmod() - Obtém o horário da última modificação na página

# getopt

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

getopt — Obtêm opções da linha de comando

### Descrição

function getopt(string `$short_options`, array `$long_options` = [], int `&$rest_index` = `null`): array|false

Extrai as opções passadas para o script.

### Parâmetros

`short_options`
  Cada caracter nessa string será usada como uma opção e comparada contra as opções passadas para o script prefixadas com um único hífen (`-`). Por exemplo, a string `"x"` reconhece a opção `-x`. Somente a-z, A-Z e 0-9 são permitidos.
`long_options`
  Um array de opções. Cada elemento desse array será usado como uma string de opção e comparada contra as opções passadas para o script com dois hífens (`--`). Por exemplo, um elemento longopts `"opt"` reconhece a opção `--opt`.
`rest_index`
  Se o parâmetro `rest_index` estiver presente, então o índice onde a interpretação de argumentos parou será escrita nessa variável.

O parâmetro `short_options` pode conter os elementos a seguir:

- Letras individuais (não aceita valores)
- Letras seguidas de um dois pontos (parâmetro requer valores)
- Letras seguidas de dois dois pontos(valor opcional)

Valores de opções são o primeiro argumento depois da string. Se o valor é exigido então não importa se o valor tem um espaço na frente ou não. Veja nota.

> Nota: Valores opcionais não aceitam `" "` (espaço) como separador.

O array `long_options` pode conter:

- String (parâmetro que não aceita valores)
- String seguida por único dois pontos parâmetro requer valor)
- String seguida por dois dois pontos (valor opcional)

> Nota:

> O formado para `short_options` e `long_options` é quase o mesmo, com a única diferença sendo que `long_options` é informado como um array de opções (onde cada elemento é a opção), enquanto `short_options` é informado como uma string (onde cada caracter é um opção).

### Valor Retornado

Esta função retorna um array de pares de opções e argumentos, ou `false` em caso de falha.

> Nota:

> A interpretação de opções irá parar na primeira opção desconhecida, e tudo o mais será descartado.

### Registro de Alterações

Versão | Descrição
--- | ---
7.1.0 | Acrescentando o parâmetro `rest_index`.

### Exemplos

Exemplo #1 Exemplo básico de getopt()

    <?php
    // Script example.php
    $options = getopt("f:hp:");
    var_dump($options);
    ?>

    shell> php example.php -fvalue -h

O exemplo acima produzirá:

    array(2) {
      ["f"]=>
      string(5) "value"
      ["h"]=>
      bool(false)
    }

Exemplo #2 Exemplo de getopt() com opções longas

    <?php
    // Script example.php
    $shortopts  = "";
    $shortopts .= "f:";  // Valor exigido
    $shortopts .= "v::"; // Valor opcional
    $shortopts .= "abc"; // Essas opções não aceitam valores

    $longopts  = array(
        "required:",     // Valor exigido
        "optional::",    // Valor opcional
        "option",        // Sem valor
        "opt",           // Sem valor
    );
    $options = getopt($shortopts, $longopts);
    var_dump($options);
    ?>

    shell> php example.php -f "value for f" -v -a --required value --optional="optional value" --option

O exemplo acima produzirá:

    array(6) {
      ["f"]=>
      string(11) "value for f"
      ["v"]=>
      bool(false)
      ["a"]=>
      bool(false)
      ["required"]=>
      string(5) "value"
      ["optional"]=>
      string(14) "optional value"
      ["option"]=>
      bool(false)
    }

Exemplo #3 Exemplo de getopt(): passando múltiplas opções como uma só

    <?php
    // Script example.php
    $options = getopt("abc");
    var_dump($options);
    ?>

    shell> php example.php -aaac

O exemplo acima produzirá:

    array(2) {
      ["a"]=>
      array(3) {
        [0]=>
        bool(false)
        [1]=>
        bool(false)
        [2]=>
        bool(false)
      }
      ["c"]=>
      bool(false)
    }

Exemplo #4 Exemplo de getopt() com `rest_index`

    <?php
    // Script example.php
    $rest_index = null;
    $opts = getopt('a:b:', [], $rest_index);
    $pos_args = array_slice($argv, $rest_index);
    var_dump($pos_args);

    shell> php example.php -a 1 -b 2 -- test

O exemplo acima produzirá:

    array(1) {
      [0]=>
      string(4) "test"
    }

### Veja Também

- $argv

# getrusage

(PHP 4, PHP 5, PHP 7, PHP 8)

getrusage — Obtém os usos atuais de recursos

### Descrição

function getrusage(int `$mode` = 0): array|false

Esta é uma interface para getrusage(2). Ele obtém dados retornados a partir da chamada de sistema.

### Parâmetros

`mode`

  Se `mode` for 1, getrusage será chamado com `RUSAGE_CHILDREN`.

### Valor Retornado

Retorna um array associativo contendo os dados retornados da chamada de sistema. Todas as entradas são acessíveis usando seus nomes de campo documentados. Retorna `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de getrusage()

    <?php
    $dat = getrusage();
    echo $dat["ru_oublock"];       // número de operações de saída em bloco
    echo $dat["ru_inblock"];       // número de operações de entrada em bloco
    echo $dat["ru_msgsnd"];        // número de mensagens IPC enviadas
    echo $dat["ru_msgrcv"];        // número de mensagens IPC recebidas
    echo $dat["ru_maxrss"];        // tamanho máximo de conjunto residente
    echo $dat["ru_ixrss"];         // tamanho integral da memória compartilhada
    echo $dat["ru_idrss"];         // tamanho integral de dados não compartilhados
    echo $dat["ru_minflt"];        // número de recuperações de página (falhas de página soft)
    echo $dat["ru_majflt"];        // número de falhas de página (falhas de página graves)
    echo $dat["ru_nsignals"];      // número de sinais recebidos
    echo $dat["ru_nvcsw"];         // número de mudanças voluntárias de contexto
    echo $dat["ru_nivcsw"];        // número de mudanças de contexto involuntárias
    echo $dat["ru_nswap"];         // número de trocas de páginas
    echo $dat["ru_utime.tv_usec"]; // tempo usado pelo usuário (microssegundos)
    echo $dat["ru_utime.tv_sec"];  // tempo usado pelo usuário (segundos)
    echo $dat["ru_stime.tv_usec"]; // tempo do sistema usado (microssegundos)
    echo $dat["ru_stime.tv_sec"];  // tempo do sistema usado (segundos)
    ?>

### Notas

> Nota:

> No Windows, getrusage() irá retornar somente os seguintes membros:

> - `"ru_stime.tv_sec"`
> - `"ru_stime.tv_usec"`
> - `"ru_utime.tv_sec"`
> - `"ru_utime.tv_usec"`
> - `"ru_majflt"` (somente se `mode` for `RUSAGE_SELF`)
> - `"ru_maxrss"` (somente se `mode` for `RUSAGE_SELF`)

> Se getrusage() for chamada com `mode` definido como `1` (`RUSAGE_CHILDREN`), então o uso de recursos para threads será coletado (ou seja, que internamente a função é chamada com `RUSAGE_THREAD`).

> Nota:

> No BeOS 2000, apenas os seguintes membros são retornados:

> - `"ru_stime.tv_sec"`
> - `"ru_stime.tv_usec"`
> - `"ru_utime.tv_sec"`
> - `"ru_utime.tv_usec"`

### Veja Também

- Página do manual do sistema operacional sobre o comando getrusage(2)

# ini_alter

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_alter — Sinônimo de ini_set()

### Descrição

Esta função é um apelido para: ini_set().

# ini_get

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_get — Obtém o valor de uma opção de configuração

### Descrição

function ini_get(string `$option`): string|false

Retorna o valor da opção de configuração em caso de sucesso.

### Parâmetros

`option`

  O nome da opção de configuração.

### Valor Retornado

Retorna o valor da opção de configuração como uma string em caso de sucesso ou uma string vazia para valores `null`. Retorna `false` se a opção de configuração não existir.

### Exemplos

Exemplo #1 Alguns exemplos de ini_get()

    <?php

    /*
    Considere o php.ini com as seguintes configurações:

    display_errors = On
    opcache.enable_cli = Off
    post_max_size = 8M
    */

    echo 'display_errors = ' . ini_get('display_errors') . "\n";
    echo 'opcache.enable_cli = ' . (int) ini_get('opcache.enable_cli') . "\n";
    echo 'post_max_size = ' . ini_get('post_max_size') . "\n";
    echo 'post_max_size + 1 = ' . (rtrim(ini_get('post_max_size'), 'KMG') + 1) . "\n";
    echo 'post_max_size in bytes = ' . ini_parse_quantity(ini_get('post_max_size'));

    ?>

O exemplo acima produzirá algo semelhante a:

    display_errors = 1
    opcache.enable_cli = 0
    post_max_size = 8M
    post_max_size+1 = 9
    post_max_size em bytes = 8388608

### Notas

> Nota: Ao consultar valores booleanos

> Um valor booleano ini `off` será retornado como uma string vazia ou "0", enquanto um valor booleano ini `on` será retornado como "1". A função também pode retornar a string literal do valor INI.

> Nota: Ao consultar valores de tamanho de memória

> Muitos valores de tamanho de memória ini, como upload_max_filesize, são armazenados no arquivo php.ini em notação abreviada. ini_get() retornará a string exata armazenada no arquivo php.ini e NÃO o seu equivalente int. Tentar funções aritméticas normais com esses valores não trará os resultados esperados. A função ini_parse_quantity() pode ser usada para converter a notação abreviada em bytes.

> Nota:

> ini_get() não consegue ler opções ini de "array" como, por exemplo, `pdo.dsn.*`, e retorna `false` neste caso.

### Veja Também

- get_cfg_var() - Obtém o valor de uma opção de configuração do PHP
- ini_get_all() - Obtém todas as opções de configuração
- ini_parse_quantity() - Obtém o tamanho interpretado da sintaxe abreviada do ini
- ini_restore() - Restaura o valor de uma opção de configuração
- ini_set() - Define o valor de uma opção de configuração

# ini_get_all

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ini_get_all — Obtém todas as opções de configuração

### Descrição

function ini_get_all(?string `$extension` = `null`, bool `$details` = `true`): array|false

Retorna todas as opções de configuração cadastradas.

### Parâmetros

`extension`

  Um nome de extensão opcional. Se diferente de `null` ou igual à string `core`, a função retorna apenas opções específicas para aquela extensão.

`details`

  Recupera configurações detalhadas ou apenas o valor atual de cada configuração. O padrão é `true` (recuperar detalhes).

### Valor Retornado

Retorna um array associativo com o nome da diretiva como chave do array. Retorna `false` e gera um erro de nível `E_WARNING` se a extensão informada em `extension` não existir.

Quando `details` for `true` (padrão) o array conterá `global_value` (definido no php.ini), `local_value` (talvez definido com ini_set() ou .htaccess) e `access` (o nível de acesso).

Quando `details` for `false` o valor será o atual da opção.

Consulte a seção do manual para informação sobre o que significam os níveis de acesso.

> Nota:

> É possível que uma diretiva tenha múltiplos níveis de acesso, e é por isso que `access` mostra os valores apropriados da máscara de bits.

### Exemplos

Exemplo #1 Exemplos de ini_get_all()

    <?php
    print_r(ini_get_all("pcre"));
    print_r(ini_get_all());
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [pcre.backtrack_limit] => Array
            (
                [global_value] => 100000
                [local_value] => 100000
                [access] => 7
            )

        [pcre.recursion_limit] => Array
            (
                [global_value] => 100000
                [local_value] => 100000
                [access] => 7
            )

    )
    Array
    (
        [allow_call_time_pass_reference] => Array
            (
                [global_value] => 0
                [local_value] => 0
                [access] => 6
            )

        [allow_url_fopen] => Array
            (
                [global_value] => 1
                [local_value] => 1
                [access] => 4
            )

        ...

    )

Exemplo #2 Desabilitando `details`

    <?php
    print_r(ini_get_all("pcre", false)); // Adicionado no PHP 5.3.0
    print_r(ini_get_all(null, false)); // Adicionado no PHP 5.3.0
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [pcre.backtrack_limit] => 100000
        [pcre.recursion_limit] => 100000
    )
    Array
    (
        [allow_call_time_pass_reference] => 0
        [allow_url_fopen] => 1
        ...
    )

### Notas

> Nota:

> ini_get_all() ignora opções ini de "array" como, por exemplo, `pdo.dsn.*`.

### Veja Também

- Como mudar as configurações
- ini_get() - Obtém o valor de uma opção de configuração
- ini_restore() - Restaura o valor de uma opção de configuração
- ini_set() - Define o valor de uma opção de configuração
- get_loaded_extensions() - Retorna um array com os nomes de todos os módulos compilados e carregados
- phpinfo() - Mostra informações sobre a configuração do PHP
- ReflectionExtension::getINIEntries() - Obtém entradas de extensão ini

# ini_parse_quantity

(PHP 8 >= 8.2.0)

ini_parse_quantity — Obtém o tamanho interpretado da sintaxe abreviada do ini

### Descrição

function ini_parse_quantity(string `$shorthand`): int

Retorna o tamanho interpretado em bytes em caso de sucesso a partir de uma notação abreviada ini.

### Parâmetros

`shorthand`

  Notação abreviada ini a ser interpretada, precisa ser um número seguido por um multiplicador opcional. Os seguintes multiplicadores são suportados: `k`/`K` (`1024`), `m`/`M` (`1048576`), `g`/`G` (`1073741824`). O número pode ser um decimal, hexadecimal (prefixado com `0x` ou `0X`), octal (prefixado com `0o`, `0O` ou `0`) ou binário (prefixado com `0b` ou `0B`)

### Valor Retornado

Retorna o tamanho interpretado em bytes como um número int.

### Erros/Exceções

Se o valor não puder ser interpretado, ou se um multiplicador inválido for utilizado, um `E_WARNING` é emitido.

### Exemplos

Exemplo #1 Alguns exemplos de ini_parse_quantity()

    <?php

    var_dump(ini_parse_quantity('1024'));
    var_dump(ini_parse_quantity('1024M'));
    var_dump(ini_parse_quantity('512K'));
    var_dump(ini_parse_quantity('0xFFk'));
    var_dump(ini_parse_quantity('0b1010k'));
    var_dump(ini_parse_quantity('0o1024'));
    var_dump(ini_parse_quantity('01024'));
    var_dump(ini_parse_quantity('Foobar'));
    var_dump(ini_parse_quantity('10F'));

    ?>

O exemplo acima produzirá:

    int(1024)
    int(1073741824)
    int(524288)
    int(261120)
    int(10240)
    int(532)
    int(532)

    Warning: Invalid quantity "Foobar": no valid leading digits, interpreting as "0" for backwards compatibility
    int(0)

    Warning: Invalid quantity "10F": unknown multiplier "F", interpreting as "10" for backwards compatibility
    int(10)

### Veja Também

- ini_get() - Obtém o valor de uma opção de configuração

# ini_restore

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_restore — Restaura o valor de uma opção de configuração

### Descrição

function ini_restore(string `$option`): void

Restaura uma determinada opção de configuração ao seu valor original.

### Parâmetros

`option`

  O nome da opção de configuração.

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ini_restore()

    <?php
    $setting = 'html_errors';

    echo 'Valor atual para \'' . $setting . '\': ' . ini_get($setting), PHP_EOL;

    ini_set($setting, ini_get($setting) ? 0 : 1);
    echo 'Novo valor para \'' . $setting . '\': ' . ini_get($setting), PHP_EOL;

    ini_restore($setting);
    echo 'Valor original para \'' . $setting . '\': ' . ini_get($setting), PHP_EOL;
    ?>

O exemplo acima produzirá:

    Valor atual para 'html_errors': 1
    Novo valor para 'html_errors': 0
    Valor original para 'html_errors': 1

### Veja Também

- ini_get() - Obtém o valor de uma opção de configuração
- ini_get_all() - Obtém todas as opções de configuração
- ini_set() - Define o valor de uma opção de configuração

# ini_set

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_set — Define o valor de uma opção de configuração

### Descrição

function ini_set(string `$option`, string|int|float|bool|null `$value`): string|false

Define o valor da opção de configuração fornecida. A opção de configuração manterá este novo valor durante a execução do script e será restaurada ao final do script.

### Parâmetros

`option`

  Nem todas as opções disponíveis podem ser alteradas usando ini_set(). Há uma lista de todas as opções disponíveis no apêndice.

`value`

  O novo valor da opção.

### Valor Retornado

Retorna o valor antigo em caso de sucesso, `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | `value` agora aceita qualquer tipo escalar (incluindo `null`). Anteriormente, apenas valores string eram aceitos.

### Exemplos

Exemplo #1 Configurando uma opção ini

    <?php
    echo ini_get('display_errors');

    if (!ini_get('display_errors')) {
        ini_set('display_errors', '1');
    }

    echo ini_get('display_errors');
    ?>

### Veja Também

- get_cfg_var() - Obtém o valor de uma opção de configuração do PHP
- ini_get() - Obtém o valor de uma opção de configuração
- ini_get_all() - Obtém todas as opções de configuração
- ini_restore() - Restaura o valor de uma opção de configuração
- Como alterar as definições de configuração

# memory_get_peak_usage

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

memory_get_peak_usage — Retorna o pico de memória alocada pelo PHP

### Descrição

function memory_get_peak_usage(bool `$real_usage` = `false`): int

Retorna o pico de memória, em bytes, que foi alocado para o script PHP.

### Parâmetros

`real_usage`

  Defina este parâmetro como `true` para obter o tamanho real da memória alocada do sistema. Se não estiver definido ou se for informado como `false`, apenas a memória usada por `emalloc()` é relatada.

### Valor Retornado

Retorna o pico de memória em bytes.

### Veja Também

- memory_get_usage() - Retorna a quantidade de memória alocada para o PHP
- memory_reset_peak_usage() - Redefine o pico de uso de memória
- memory_limit

# memory_get_usage

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

memory_get_usage — Retorna a quantidade de memória alocada para o PHP

### Descrição

function memory_get_usage(bool `$real_usage` = `false`): int

Retorna a quantidade de memória, em bytes, que está sendo alocada atualmente para o script PHP.

### Parâmetros

`real_usage`

  Defina isso como `true` para obter a memória total alocada do sistema, incluindo páginas não utilizadas. Se não estiver definido ou informado como `false`, apenas a memória usada é relatada.

> Nota:

> O PHP não rastreia memória que não é alocada por `emalloc()`

### Valor Retornado

Retorna a quantidade de memória em bytes.

### Exemplos

Exemplo #1 Um exemplo de memory_get_usage()

    <?php
    // Este é apenas um exemplo, os número abaixo serão
    // diferentes dependendo do sistema

    echo memory_get_usage() . "\n"; // 36640

    $a = str_repeat("Hello", 4242);

    echo memory_get_usage() . "\n"; // 57960

    unset($a);

    echo memory_get_usage() . "\n"; // 36744

    ?>

### Veja Também

- memory_get_peak_usage() - Retorna o pico de memória alocada pelo PHP
- memory_limit

# memory_reset_peak_usage

(PHP 8 >= 8.2.0)

memory_reset_peak_usage — Redefine o pico de uso de memória

### Descrição

function memory_reset_peak_usage(): void

Redefine o pico de uso de memória retornado pela função memory_get_peak_usage().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de memory_reset_peak_usage()

    <?php

    var_dump(memory_get_peak_usage());

    $a = str_repeat("Hello", 424242);
    var_dump(memory_get_peak_usage());

    unset($a);
    memory_reset_peak_usage();

    $a = str_repeat("Hello", 2424);
    var_dump(memory_get_peak_usage());

    ?>

O exemplo acima produzirá algo semelhante a:

    int(422440)
    int(2508672)
    int(399208)

### Veja Também

- memory_get_peak_usage() - Retorna o pico de memória alocada pelo PHP

# php_ini_loaded_file

(PHP 5 >= 5.2.4, PHP 7, PHP 8)

php_ini_loaded_file — Obtém o caminho para o arquivo php.ini carregado

### Descrição

function php_ini_loaded_file(): string|false

Verifica se um php.ini arquivo está carregado e retorna seu caminho.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O caminho do arquivo php.ini, ou `false` se nenhum tiver sido carregado.

### Exemplos

Exemplo #1 Exemplo de php_ini_loaded_file()

    <?php
    $inipath = php_ini_loaded_file();

    if ($inipath) {
        echo 'Arquivo php.ini carregado: ' . $inipath;
    } else {
        echo 'Nenhum arquivo php.ini carregado';
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Arquivo php.ini carregado: /usr/local/php/php.ini

### Veja Também

- php_ini_scanned_files() - Retorna uma lista de arquivos .ini analisados ​​do diretório ini adicional
- phpinfo() - Mostra informações sobre a configuração do PHP
- O arquivo de configuração

# php_ini_scanned_files

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

php_ini_scanned_files — Retorna uma lista de arquivos .ini analisados ​​do diretório ini adicional

### Descrição

function php_ini_scanned_files(): string|false

php_ini_scanned_files() retorna uma lista separada por vírgulas de arquivos de configuração analisados ​​após o php.ini. Os diretórios pesquisados ​​são definidos por uma opção em tempo de compilação e, opcionalmente, por uma variável de ambiente em tempo de execução: mais informações podem ser encontradas no guia de instalação.

Os arquivos de configuração retornados incluem o caminho completo.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma sequência separada por vírgulas de arquivos .ini em caso de sucesso. Cada vírgula é seguida por uma nova linha. Se a diretiva --with-config-file-scan-dir do comando configure não tiver sido definida e a variável de ambiente PHP_INI_SCAN_DIR também não estiver definida, `false` é retornado. Se foi definida e o diretório estiver vazio, uma string vazia será retornada. Se um arquivo estiver irreconhecível, o arquivo ainda aparecerá na string retornada, mas também ocorrerá um erro de PHP. Este erro do PHP será visto tanto em tempo de compilação quanto durante o uso de php_ini_scanned_files().

### Exemplos

Exemplo #1 Um exemplo simples para listar os arquivos ini retornados

    <?php
    if ($filelist = php_ini_scanned_files()) {
        if (strlen($filelist) > 0) {
            $files = explode(',', $filelist);

            foreach ($files as $file) {
                echo "<li>" . trim($file) . "</li>\n";
            }
        }
    }
    ?>

### Veja Também

- ini_set() - Define o valor de uma opção de configuração
- phpinfo() - Mostra informações sobre a configuração do PHP
- php_ini_loaded_file() - Obtém o caminho para o arquivo php.ini carregado

# php_sapi_name

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

php_sapi_name — Retorna o tipo de interface entre o servidor web e o PHP

### Descrição

function php_sapi_name(): string|false

Retorna uma string em minúsculas que descreve o tipo de interface (API do Servidor, SAPI) que o PHP está usando. Por exemplo, no PHP CLI esta string será "cli" e no Apache poderá ter vários valores diferentes dependendo da SAPI exata sendo usada. Os valores possíveis estão listados abaixo.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o tipo de interface como uma string em minúsculas ou `false` em caso de falha.

Embora não seja uma lista exaustiva, os valores possíveis incluem `apache`, `apache2handler`, `cgi` (até o PHP 5.3), `cgi-fcgi`, `cli`, `cli-server`, `embed`, `fpm-fcgi`, `litespeed`, `phpdbg`.

### Exemplos

Exemplo #1 Exemplo de php_sapi_name()

Este exemplo procura pela sub-string `cgi` porque a interface também pode ser `cgi-fcgi`.

    <?php
    $sapi_type = php_sapi_name();
    if (substr($sapi_type, 0, 3) == 'cgi') {
        echo "Você está usando o PHP CGI.\n";
    } else {
        echo "Você não está usando o PHP CGI.\n";
    }
    ?>

### Notas

> Nota: Uma abordagem alternativa

> A constante `PHP_SAPI` do PHP tem o mesmo valor retornado pela função php_sapi_name().

Dica

# Uma potencial armadilha

A SAPI definida pode não ser óbvia porque, por exemplo, ao invés de `apache` ela pode estar definida como `apache2handler`.

### Veja Também

- PHP_SAPI

# php_uname

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

php_uname — Retorna informações sobre o sistema operacional em que o PHP está sendo executado

### Descrição

function php_uname(string `$mode` = "a"): string

php_uname() retorna uma descrição do sistema operacional em que o PHP está sendo executado. Esta é a mesma string que você vê no topo da saída de phpinfo(). Para o nome apenas do sistema operacional, considere usar a constante `PHP_OS`, mas tenha em mente que esta constante conterá o sistema operacional no qual o PHP foi construído.

Em algumas plataformas UNIX mais antigas, pode não ser possível determinar as informações atuais do sistema operacional e, nesse caso, a função reverterá para a exibição do sistema operacional no qual o PHP foi construído. Isso só acontecerá se a chamada da biblioteca uname() não existir ou não funcionar.

### Parâmetros

`mode`

  `mode` é um único caractere que define quais informações são retornadas:

  - `'a'`: É o padrão. Retorna a mesma informação que os modos individuais `'s'`, `'n'`, `'r'`, `'v'`, `'m'` separados por espaços.

  - `'s'`: Nome do sistema operacional. Ex: `FreeBSD`.
  - `'n'`: Nome do servidor. Ex.: `localhost.example.com`.
  - `'r'`: Nome da distribuição. Ex.: `5.1.2-RELEASE`.
  - `'v'`: Informação de versão. Varia muito entre sistemas operacionais.
  - `'m'`: Tipo de máquina. Ex.: `i386`.

### Valor Retornado

Retorna a descrição, como uma string.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Lança um ValueError quando um `mode` inválido for especificado.

### Exemplos

Exemplo #1 Alguns exemplos de php_uname()

    <?php
    echo php_uname();
    echo PHP_OS;

    /* Alguns resultados possíveis:
    Linux localhost 2.4.21-0.13mdk #1 Fri Mar 14 15:08:06 EST 2003 i686
    Linux

    FreeBSD localhost 3.2-RELEASE #15: Mon Dec 17 08:46:02 GMT 2001
    FreeBSD

    Windows NT XN1 5.1 build 2600
    WINNT
    */

    if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
        echo 'Este é um servidor que usa Windows!';
    } else {
        echo 'Este é um servidor que não usa Windows!';
    }

    ?>

Também existem algumas Constantes Predefinidas do PHP relacionadas que podem ser úteis, por exemplo:

Exemplo #2 Exemplos de algumas constantes relacionadas a sistema operacional

    <?php
    // *nix
    echo DIRECTORY_SEPARATOR; // /
    echo PHP_SHLIB_SUFFIX;    // so
    echo PATH_SEPARATOR;      // :

    // Win*
    echo DIRECTORY_SEPARATOR; // \
    echo PHP_SHLIB_SUFFIX;    // dll
    echo PATH_SEPARATOR;      // ;
    ?>

### Veja Também

- phpversion() - Obtém a versão atual do PHP
- php_sapi_name() - Retorna o tipo de interface entre o servidor web e o PHP
- phpinfo() - Mostra informações sobre a configuração do PHP

# phpcredits

(PHP 4, PHP 5, PHP 7, PHP 8)

phpcredits — Mostra os créditos para o PHP

### Descrição

function phpcredits(int `$flags` = `CREDITS_ALL`): true

Esta função imprime os créditos listando os desenvolvedores do PHP, dos módulos, etc. Ela gera os códigos HTML apropriados para inserir as informações em uma página.

### Parâmetros

`flags`

  Para gerar uma página de créditos personalizada, pode-se usar o parâmetro `flags`.

  Opções predefinidas de phpcredits()
  nome | descrição
  --- | ---
  CREDITS_ALL | Todos os créditos, equivalente a usar: `CREDITS_DOCS` + `CREDITS_GENERAL` + `CREDITS_GROUP` + `CREDITS_MODULES` + `CREDITS_FULLPAGE`. Gera uma página HTML completa e independente com as etiquetas HTML apropriadas.
  CREDITS_DOCS | Os créditos para a equipe de documentação
  CREDITS_FULLPAGE | Geralmente usada em combinação com outras opções. Indica que uma página HTML independente completa precisa ser mostrada incluindo as informações indicadas pelas outras opções.
  CREDITS_GENERAL | Créditos gerais: Projeto e conceito de linguagem, autores do PHP e módulo SAPI.
  CREDITS_GROUP | Uma lista dos desenvolvedores do núcleo
  CREDITS_MODULES | Uma lista dos módulos de extensão para PHP e seus autores.
  CREDITS_SAPI | Uma lista dos módulos de API de servidor para PHP e seus autores.

### Valor Retornado

Sempre retorna `true`.

### Exemplos

Exemplo #1 Mostra os créditos gerais

    <?php
    phpcredits(CREDITS_GENERAL);
    ?>

Exemplo #2 Mostra os desenvolvedores do núcleo e o grupo de documentação

    <?php
    phpcredits(CREDITS_GROUP | CREDITS_DOCS | CREDITS_FULLPAGE);
    ?>

Exemplo #3 Mostra todos os créditos

    <html>
     <head>
      <title>Minha página de créditos</title>
     </head>
     <body>
    <?php
    // algum código
    phpcredits(CREDITS_ALL - CREDITS_FULLPAGE);
    // mais código
    ?>
     </body>
    </html>

### Notas

> Nota:

> phpcredits() mostra texto puro ao invés de HTML quando o modo CLI está sendo usado.

### Veja Também

- phpversion() - Obtém a versão atual do PHP
- phpinfo() - Mostra informações sobre a configuração do PHP

# phpinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

phpinfo — Mostra informações sobre a configuração do PHP

### Descrição

function phpinfo(int `$flags` = `INFO_ALL`): true

Mostra uma grande quantidade de informações sobre o estado atual do PHP. Isso inclui informações sobre opções e extensões de compilação do PHP, a versão do PHP, informações do servidor e ambiente (se compilado como um módulo), o ambiente do PHP, informações da versão do sistema operacional, caminhos, valores principais e locais das opções de configuração, cabeçalhos HTTP e a Licença do PHP.

Como cada sistema é configurado de maneira diferente, phpinfo() é comumente usado para verificar definições de configuração e disponibilidade de variáveis predefinidas em um determinado sistema.

phpinfo() também é uma ferramenta de depuração valiosa, pois contém todos os dados EGPCS (Environment - ambiente, GET, POST, Cookie, Servidor).

### Parâmetros

`flags`

  A saída pode ser personalizada passando um ou mais dos seguintes valores de constantes bit a bit somados no parâmetro opcional `flags`. Também é possível combinar as respectivas constantes ou valores bit a bit com o operador binário OR.

  Opções de phpinfo()
  Nome (constante) | Valor | Descrição
  --- | --- | ---
  INFO_GENERAL | 1 | A linha de configuração, localização do php.ini, data de construção, servidor Web, sistema e muito mais.
  INFO_CREDITS | 2 | Créditos do PHP. Veja também phpcredits().
  INFO_CONFIGURATION | 4 | Valores atuais das diretivas do PHP locais e principais. Veja também ini_get().
  INFO_MODULES | 8 | Módulos carregados e suas respectivas configurações. Veja também get_loaded_extensions().
  INFO_ENVIRONMENT | 16 | Informações sobre variáveis ​​de ambiente que também estão disponíveis em $_ENV.
  INFO_VARIABLES | 32 | Mostra todas as variáveis ​​predefinidas de EGPCS (Environment - ambiente, GET, POST, Cookie, Servidor).
  INFO_LICENSE | 64 | Informações de Licença do PHP. Veja também a seção de » Perguntas e Respostas sobre Licença.
  INFO_ALL | -1 | Mostra todas as informações acima.

### Valor Retornado

Sempre retorna `true`.

### Exemplos

Exemplo #1 Exemplo de phpinfo()

    <?php

    // Mostra todas as informações, equivalente ao padrão INFO_ALL
    phpinfo();

    // Mostra apenas informações sobre módulos.
    // phpinfo(8) gera resultados idênticos.
    phpinfo(INFO_MODULES);

    ?>

### Notas

> Nota:

> Nas versões do PHP anteriores à 5.5, partes das informações exibidas eram desativadas quando a configuração expose_php estava definida como `off`. Isso incluía os logotipos PHP e Zend e os créditos.

> Nota:

> phpinfo() gera texto puro ao invés de HTML ao usar o modo CLI.

### Veja Também

- phpversion() - Obtém a versão atual do PHP
- phpcredits() - Mostra os créditos para o PHP
- ini_get() - Obtém o valor de uma opção de configuração
- ini_set() - Define o valor de uma opção de configuração
- get_loaded_extensions() - Retorna um array com os nomes de todos os módulos compilados e carregados
- Variáveis Predefinidas

# phpversion

(PHP 4, PHP 5, PHP 7, PHP 8)

phpversion — Obtém a versão atual do PHP

### Descrição

function phpversion(?string `$extension` = `null`): string|false

Retorna uma string contendo a versão do interpretador ou extensão do PHP atualmente em execução.

### Parâmetros

`extension`

  Um nome de extensão opcional.

### Valor Retornado

Retorna a versão atual do PHP como uma string. Se um argumento string for fornecido para o parâmetro `extension`, phpversion() retornará a versão dessa extensão, ou `false` se não houver informações de versão associadas ou se a extensão não estiver habilitada.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `extension` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo de phpversion()

    <?php

    // mostra por exemplo 'Versão atual do PHP: 8.3.12'
    echo 'Versão atual do PHP: ' . phpversion();

    // mostra por exemplo '1.22.3' ou nada se a extensão não estiver habilitada
    echo phpversion('zip');

    ?>

Exemplo #2 Exemplo e uso de `PHP_VERSION_ID`

    <?php

    /**
     * PHP_VERSION_ID é definida como um número, onde quanto mais alto ele
     * for, mais recente é a versão do PHP usada. É definida de acordo com a expressão
     * abaixo:
     *
     * $id_versao = $versao_principal * 10000 + $versao_secundaria * 100 + $versao_distribuicao;
     *
     * Com PHP_VERSION_ID, pode-se procurar por recursos que esta versão do PHP
     * possa ter, e não é necessário usar version_compare() toda vez
     * para verificar se a versão atual do PHP pode ou não suportar um recurso.
     *
     * Por exemplo, pode-se definir aqui as constantes PHP_*_VERSION que
     * não estão disponíveis em versões anteriores à 5.2.7
     */

    if (PHP_VERSION_ID < 50207) {
        define('PHP_MAJOR_VERSION',   $version[0]);
        define('PHP_MINOR_VERSION',   $version[1]);
        define('PHP_RELEASE_VERSION', $version[2]);

        // e assim por diante, ...
    }

    ?>

### Notas

> Nota:

> Esta informação também está disponível na constante predefinida `PHP_VERSION`. Mais informações sobre versionamento estão disponíveis usando as constantes `PHP_*_VERSION`.

> Nota:

> Algumas extensões podem definir seu próprio número de versão. No entanto, a maioria das extensões incluídas usará a versão do PHP como número de versão.

### Veja Também

- Constantes PHP_VERSION
- version_compare() - Compara duas strings de número de versão no "padrão PHP"
- phpinfo() - Mostra informações sobre a configuração do PHP
- phpcredits() - Mostra os créditos para o PHP
- zend_version() - Obtém a versão do motor Zend atual

# putenv

(PHP 4, PHP 5, PHP 7, PHP 8)

putenv — Define o valor de uma variável de ambiente

### Descrição

function putenv(string `$assignment`): bool

Adiciona `assignment` no ambiente do servidor. A variável de ambiente irá existir somente durante a requisição atual. Ao final da requisição o ambiente é restaurado ao seu estado original.

### Parâmetros

`assignment`

  A definição, como `"FOO=BAR"`

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Definindo uma variável de ambiente

    <?php
    putenv("UNIQID=$uniqid");
    ?>

### Veja Também

- getenv() - Obtém o valor de uma única ou de todas as variáveis ​​de ambiente
- apache_setenv() - Define uma variável subprocess_env do Apache

# restore_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7)

restore_include_path — Restaura o valor da opção de configuração include_path

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.4.0 e foi REMOVIDA a partir do PHP 8.0.0. O uso desta função é fortemente desencorajado.

### Descrição

function restore_include_path(): void

Restaura a opção de configuração include_path de volta ao seu valor original master como definido no php.ini

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Esta função foi removida.
7.4.0 | Esta função foi descontinuada.

### Exemplos

Exemplo #1 Exemplo de restore_include_path()

    <?php

    echo get_include_path();  // .:/usr/local/lib/php

    set_include_path('/inc');

    echo get_include_path();  // /inc

    restore_include_path();

    // Ou usando ini_restore()
    ini_restore('include_path');

    echo get_include_path();  // .:/usr/local/lib/php

    ?>

### Veja Também

- ini_restore() - Restaura o valor de uma opção de configuração
- get_include_path() - Obtém a opção de configuração include_path atual
- set_include_path() - Define a opção de configuração include_path
- include - include

# set_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

set_include_path — Define a opção de configuração include_path

### Descrição

function set_include_path(string `$include_path`): string|false

Define a opção de configuração include_path para toda a duração do script.

### Parâmetros

`include_path`

  O novo valor para o include_path

### Valor Retornado

Retorna o include_path antigo em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de set_include_path()

    <?php
    set_include_path('/usr/lib/pear');

    // Ou usando ini_set()
    ini_set('include_path', '/usr/lib/pear');
    ?>

Exemplo #2 Adicionando ao caminho de inclusão

Fazendo uso da constante `PATH_SEPARATOR`, é possível estender o caminho de inclusão independentemente do sistema operacional.

Neste exemplo foi adicionado o caminho /usr/lib/pear no final do `include_path` existente.

    <?php
    $path = '/usr/lib/pear';
    set_include_path(get_include_path() . PATH_SEPARATOR . $path);
    ?>

### Veja Também

- ini_set() - Define o valor de uma opção de configuração
- get_include_path() - Obtém a opção de configuração include_path atual
- restore_include_path() - Restaura o valor da opção de configuração include_path
- include - include

# set_time_limit

(PHP 4, PHP 5, PHP 7, PHP 8)

set_time_limit — Limita o máximo tempo de execução

### Descrição

function set_time_limit(int `$seconds`): bool

Define um tempo em segundos em que um script poderá ser executado. Se este tempo for alcançado, o script retorna um erro fatal. O limite padrão é de 30 segundos ou, se exitente, o valor de `max_execution_time` definido no php.ini.

Quando chamada, set_time_limit() reinicia o contador do limite a partir do zero. Em outras palavras, se o limite for o padrão de 30 segundos, e já houver 25 segundos decorridos desde o início do script, quando uma chamada chamada tipo `set_time_limit(20)` é feita, o script será executado por um total de 45 segundos antes de expirar.

### Parâmetros

`seconds`

  O tempo máximo de execução, em segundos. Se definido para zero, nenhum limite será imposto.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Notas

> Nota:

> A função set_time_limit() e a diretiva de configuração max_execution_time afetam apenas o tempo de execução do próprio script. Qualquer tempo gasto em atividades que acontecem fora da execução do script, como chamadas de sistema usando system(), operações de fluxo, consultas de banco de dados, etc., não é incluído na determinação do tempo máximo de execução do script. Isso não acontece no Windows, onde o tempo medido é real.

### Veja Também

- max_execution_time
- max_input_time

# sys_get_temp_dir

(PHP 5 >= 5.2.1, PHP 7, PHP 8)

sys_get_temp_dir — Retorna o caminho do diretório usado para arquivos temporários

### Descrição

function sys_get_temp_dir(): string

Retorna o caminho do diretório onde o PHP armazena arquivos temporários por padrão.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o caminho do diretório de arquivos temporários.

### Exemplos

Exemplo #1 Exemplo de sys_get_temp_dir()

    <?php
    // Cria um arquivo no diretório de
    // arquivos temporários usando sys_get_temp_dir()
    $temp_file = tempnam(sys_get_temp_dir(), 'Tux');

    echo $temp_file;
    ?>

O exemplo acima produzirá algo semelhante a:

    C:\Windows\Temp\TuxA318.tmp

### Veja Também

- tmpfile() - Cria um arquivo temporário
- tempnam() - Cria arquivo com nome único

# version_compare

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

version_compare — Compara duas strings de número de versão no "padrão PHP"

### Descrição

function version_compare(string `$version1`, string `$version2`, ?string `$operator` = `null`): int|bool

version_compare() compara duas strings de número de versão no "padrão PHP".

A função primeiro substitui `_`, `-` e `+` por um ponto `.` nas strings de versão e também insere pontos `.` antes e depois de qualquer não-número para que, por exemplo, '4.3.2RC1' se torne '4.3.2.RC.1'. Em seguida, compara as partes começando da esquerda para a direita. Se uma parte contiver strings especiais de versão, elas serão tratadas na seguinte ordem: `qualquer string não encontrada nesta lista` < `dev` < `alpha` = `a` < `beta` = `b` < `RC` = `rc` < `#` < `pl` = `p`. Desta forma, não apenas versões com níveis diferentes como '4.1' e '4.1.2' podem ser comparadas, mas também qualquer versão específica do PHP contendo estado de desenvolvimento.

### Parâmetros

`version1`

  Primeiro número de versão.

`version2`

  Segundo número de versão.

`operator`

  Um operador opcional. Os operadores possíveis são: `<`, `lt`, `<=`, `le`, `>`, `gt`, `>=`, `ge`, `==`, `=`, `eq`, `!=`, `<>`, `ne` respectivamente.

  Este parâmetro diferencia maiúsculas de minúsculas, os valores devem estar em minúsculas.

### Valor Retornado

Por padrão, version_compare() retorna `-1` se a primeira versão for inferior à segunda, `0` se forem iguais e `1` se a segunda for menor.

Ao usar o argumento opcional `operator`, a função retornará `true` se o relacionamento for aquele especificado pelo operador, `false` caso contrário.

### Exemplos

Os exemplos abaixo utilizam a constante `PHP_VERSION`, pois ela contém o valor da versão do PHP que está executando o código.

Exemplo #1 Exemplos de version_compare()

    <?php
    if (version_compare(PHP_VERSION, '7.0.0') >= 0) {
        echo 'Estou pelo menos na versão 7.0.0 do PHP, minha versão: ' . PHP_VERSION . "\n";
    }

    if (version_compare(PHP_VERSION, '5.3.0') >= 0) {
        echo 'Estou pelo menos na versão 5.3.0 do PHP, minha versão: ' . PHP_VERSION . "\n";
    }

    if (version_compare(PHP_VERSION, '5.0.0', '>=')) {
        echo 'Estou pelo menos na versão 5.0.0 do PHP, minha versão: ' . PHP_VERSION . "\n";
    }

    if (version_compare(PHP_VERSION, '5.0.0', '<')) {
        echo 'Ainda estou na versão 4 do PHP, minha versão: ' . PHP_VERSION . "\n";
    }
    ?>

### Notas

> Nota:

> A constante `PHP_VERSION` contém a versão atual do PHP.

> Nota:

> Observe que as versões de pré-lançamento, como 5.3.0-dev, são consideradas inferiores às suas versões finais correspondentes (como 5.3.0).

> Nota:

> Strings especiais de versões como `alpha` e `beta` diferenciam maiúsculas de minúsculas. Strings de versão de fontes arbitrárias que não aderem ao padrão do PHP podem precisar ser convertidas para minúsculas com strtolower() antes de chamar version_compare().

### Veja Também

- phpversion() - Obtém a versão atual do PHP
- php_uname() - Retorna informações sobre o sistema operacional em que o PHP está sendo executado
- function_exists() - Retorna true se a função informada estiver definida

# zend_thread_id

(PHP 5, PHP 7, PHP 8)

zend_thread_id — Retorna um identificador exclusivo para o thread atual

### Descrição

function zend_thread_id(): int

Retorna um identificador exclusivo para o thread atual.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ID do thread como um número inteiro.

### Exemplos

Exemplo #1 Exemplo de zend_thread_id()

    <?php
    $thread_id = zend_thread_id();

    echo 'ID do thread atual é: ' . $thread_id;
    ?>

O exemplo acima produzirá algo semelhante a:

    ID do thread atual é: 7864

### Notas

> Nota:

> Esta função só está disponível se o PHP tiver sido construído com suporte ao ZTS (Zend Thread Safety) e com modo de depuração (`--enable-debug`).

# zend_version

(PHP 4, PHP 5, PHP 7, PHP 8)

zend_version — Obtém a versão do motor Zend atual

### Descrição

function zend_version(): string

Retorna uma string contendo a versão atual do motor Zend Engine atualmente em execução.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número da versão do motor Zend, como uma string.

### Exemplos

Exemplo #1 Exemplo de zend_version()

    <?php
    echo "Versão do motor Zend: " . zend_version();
    ?>

O exemplo acima produzirá algo semelhante a:

    Versão do motor Zend: 2.2.0

### Veja Também

- phpinfo() - Mostra informações sobre a configuração do PHP
- phpcredits() - Mostra os créditos para o PHP
- phpversion() - Obtém a versão atual do PHP

## Índice

- assert — Executa uma asserção
- assert_options — Define/obtém as várias opções de asserção
- cli_get_process_title — Retorna o título do processo atual
- cli_set_process_title — Define o título do processo
- dl — Carrega uma extensão do PHP durante a execução
- extension_loaded — Descobre se uma extensão está carregada
- gc_collect_cycles — Força a coleta de quaisquer ciclos de lixo existentes.
- gc_disable — Desativa o coletor de referência circular
- gc_enable — Ativa o coletor de referência circular
- gc_enabled — Retorna o status do coletor de referência circular
- gc_mem_caches — Recupera memória usada pelo gerenciador de memória Zend Engine
- gc_status — Obtém informações sobre o coletor de lixo
- get_cfg_var — Obtém o valor de uma opção de configuração do PHP
- get_current_user — Obtém o nome do proprietário do script PHP atual
- get_defined_constants — Retorna um array associativo com os nomes de todas as constantes e seus valores
- get_extension_funcs — Retorna um array com os nomes das funções de um módulo
- get_include_path — Obtém a opção de configuração include_path atual
- get_included_files — Retorna um array com os nomes dos arquivos incluídos ou requeridos
- get_loaded_extensions — Retorna um array com os nomes de todos os módulos compilados e carregados
- get_magic_quotes_gpc — Obtém a configuração atual de magic_quotes_gpc
- get_magic_quotes_runtime — Obtém a configuração ativa para magic_quotes_runtime
- get_required_files — Sinônimo de get_included_files
- get_resources — Retorna recursos ativos
- getenv — Obtém o valor de uma única ou de todas as variáveis ​​de ambiente
- getlastmod — Obtém o horário da última modificação na página
- getmygid — Obtém o GID do proprietário do script PHP
- getmyinode — Obtém o inode do script atual
- getmypid — Obtém o ID do processo PHP
- getmyuid — Obtém o UID do proprietário do script PHP
- getopt — Obtêm opções da linha de comando
- getrusage — Obtém os usos atuais de recursos
- ini_alter — Sinônimo de ini_set
- ini_get — Obtém o valor de uma opção de configuração
- ini_get_all — Obtém todas as opções de configuração
- ini_parse_quantity — Obtém o tamanho interpretado da sintaxe abreviada do ini
- ini_restore — Restaura o valor de uma opção de configuração
- ini_set — Define o valor de uma opção de configuração
- memory_get_peak_usage — Retorna o pico de memória alocada pelo PHP
- memory_get_usage — Retorna a quantidade de memória alocada para o PHP
- memory_reset_peak_usage — Redefine o pico de uso de memória
- php_ini_loaded_file — Obtém o caminho para o arquivo php.ini carregado
- php_ini_scanned_files — Retorna uma lista de arquivos .ini analisados ​​do diretório ini adicional
- php_sapi_name — Retorna o tipo de interface entre o servidor web e o PHP
- php_uname — Retorna informações sobre o sistema operacional em que o PHP está sendo executado
- phpcredits — Mostra os créditos para o PHP
- phpinfo — Mostra informações sobre a configuração do PHP
- phpversion — Obtém a versão atual do PHP
- putenv — Define o valor de uma variável de ambiente
- restore_include_path — Restaura o valor da opção de configuração include_path
- set_include_path — Define a opção de configuração include_path
- set_time_limit — Limita o máximo tempo de execução
- sys_get_temp_dir — Retorna o caminho do diretório usado para arquivos temporários
- version_compare — Compara duas strings de número de versão no "padrão PHP"
- zend_thread_id — Retorna um identificador exclusivo para o thread atual
- zend_version — Obtém a versão do motor Zend atual

- Instalação/Configuração
  - Configurações em Execução
- Constantes predefinidas
- Funções para Opções/Info do PHP
  - assert — Executa uma asserção
  - assert_options — Define/obtém as várias opções de asserção
  - cli_get_process_title — Retorna o título do processo atual
  - cli_set_process_title — Define o título do processo
  - dl — Carrega uma extensão do PHP durante a execução
  - extension_loaded — Descobre se uma extensão está carregada
  - gc_collect_cycles — Força a coleta de quaisquer ciclos de lixo existentes.
  - gc_disable — Desativa o coletor de referência circular
  - gc_enable — Ativa o coletor de referência circular
  - gc_enabled — Retorna o status do coletor de referência circular
  - gc_mem_caches — Recupera memória usada pelo gerenciador de memória Zend Engine
  - gc_status — Obtém informações sobre o coletor de lixo
  - get_cfg_var — Obtém o valor de uma opção de configuração do PHP
  - get_current_user — Obtém o nome do proprietário do script PHP atual
  - get_defined_constants — Retorna um array associativo com os nomes de todas as constantes e seus valores
  - get_extension_funcs — Retorna um array com os nomes das funções de um módulo
  - get_include_path — Obtém a opção de configuração include_path atual
  - get_included_files — Retorna um array com os nomes dos arquivos incluídos ou requeridos
  - get_loaded_extensions — Retorna um array com os nomes de todos os módulos compilados e carregados
  - get_magic_quotes_gpc — Obtém a configuração atual de magic_quotes_gpc
  - get_magic_quotes_runtime — Obtém a configuração ativa para magic_quotes_runtime
  - get_required_files — Sinônimo de get_included_files
  - get_resources — Retorna recursos ativos
  - getenv — Obtém o valor de uma única ou de todas as variáveis ​​de ambiente
  - getlastmod — Obtém o horário da última modificação na página
  - getmygid — Obtém o GID do proprietário do script PHP
  - getmyinode — Obtém o inode do script atual
  - getmypid — Obtém o ID do processo PHP
  - getmyuid — Obtém o UID do proprietário do script PHP
  - getopt — Obtêm opções da linha de comando
  - getrusage — Obtém os usos atuais de recursos
  - ini_alter — Sinônimo de ini_set
  - ini_get — Obtém o valor de uma opção de configuração
  - ini_get_all — Obtém todas as opções de configuração
  - ini_parse_quantity — Obtém o tamanho interpretado da sintaxe abreviada do ini
  - ini_restore — Restaura o valor de uma opção de configuração
  - ini_set — Define o valor de uma opção de configuração
  - memory_get_peak_usage — Retorna o pico de memória alocada pelo PHP
  - memory_get_usage — Retorna a quantidade de memória alocada para o PHP
  - memory_reset_peak_usage — Redefine o pico de uso de memória
  - php_ini_loaded_file — Obtém o caminho para o arquivo php.ini carregado
  - php_ini_scanned_files — Retorna uma lista de arquivos .ini analisados ​​do diretório ini adicional
  - php_sapi_name — Retorna o tipo de interface entre o servidor web e o PHP
  - php_uname — Retorna informações sobre o sistema operacional em que o PHP está sendo executado
  - phpcredits — Mostra os créditos para o PHP
  - phpinfo — Mostra informações sobre a configuração do PHP
  - phpversion — Obtém a versão atual do PHP
  - putenv — Define o valor de uma variável de ambiente
  - restore_include_path — Restaura o valor da opção de configuração include_path
  - set_include_path — Define a opção de configuração include_path
  - set_time_limit — Limita o máximo tempo de execução
  - sys_get_temp_dir — Retorna o caminho do diretório usado para arquivos temporários
  - version_compare — Compara duas strings de número de versão no "padrão PHP"
  - zend_thread_id — Retorna um identificador exclusivo para o thread atual
  - zend_version — Obtém a versão do motor Zend atual

# Depurador PHP Interativo

# Introdução

Implementado como um módulo SAPI, o phpdbg pode exercer controle total sobre o ambiente sem afetar a funcionalidade ou o desempenho do seu código.

O phpdbg visa ser uma plataforma de depuração leve, poderosa e fácil de usar para PHP. Ele oferece os seguintes recursos:

- Depuração passo a passo
- Pontos de interrupção flexíveis(método de classe, função, arquivo: linha, endereço, opcode)
- Fácil acesso ao PHP com built-in eval()
- API de usuário
- SAPI Agnóstico - Facilmente integrado
- Suporte ao arquivo de configuração do PHP
- JIT super globais
- Suporte readline opcional - operação confortável do terminal
- Operação fácil - Veja ajuda :)

Opções de linha de comando
Opção | Exemplo de Argumento | Descrição
--- | --- | ---
-c | -c/my/php.ini | Defina o arquivo php.ini para carregar
-d | -dmemory_limit=4G | Definir uma diretiva php.ini
-n |  | Desativar php.ini padrão
-q |  | Suprimir mensagem de boas-vindas
-v |  | Ativar saída do oplog
-b |  | Desativar cor
-i | -imy.init | Definir arquivo .phpdbginit
-I |  | Ignorar .phpdbginit padrão
-O | -Omy.oplog | Definir arquivo de saída oplog
-r |  | Executar contexto de execução
-rr |  | Execute o contexto de execução e saia após a execução (não respeitando os pontos de interrupção)
-e |  | Gerar informações estendidas para depurador/criador de perfil
-E |  | Habilitar eval passo a passo, cuidado!
-s | -s=, -s=foo | Leia o código para executar a partir do stdin com um delimitador opcional
-S | -Scli | Substitua o nome SAPI, cuidado!
-l | -l4000 | Configurar portas de console remoto
-a | -a192.168.0.3 | Configurar endereço de ligação do console remoto
-x |  | Ativar saída xml (em vez da saída de texto normal)
-p | -p, -p=func, -p* | Opcodes de saída e sair
-h |  | Imprima a visão geral da ajuda
-V |  | Número da versão impressa
-- | -- arg1 arg2 | Use para delimitar argumentos phpdbg e php $argv; acrescente qualquer argumento $argv depois dele

# Instalação/Configuração

## Índice

- Configurações em Execução

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de Configuração de phpdbg
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
phpdbg.eol | 2 | `INI_ALL` | Removida a partir do PHP 8.1.0
phpdbg.path |  | 6 | Removida a partir do PHP 8.1.0

Aqui está uma breve explicação das diretivas de configuração.

`phpdbg.eol` mixed

  O tipo de fim de linha usado para a saída. Para configurar o valor, um dos apelidos de string precisa ser usado.

  Valor int | Apelido string
  --- | ---
  `0` | `CRLF`, `crlf`, `DOS`, `dos`
  `1` | `LF`, `lf`, `UNIX`, `unix`
  `2` | `CR`, `cr`, `MAC`, `mac`

`phpdbg.path` string

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`PHPDBG_VERSION` (string)
`PHPDBG_FILE` (int)
  Removido a partir do PHP 7.3.0.
`PHPDBG_METHOD` (int)
  Removido a partir do PHP 7.3.0.
`PHPDBG_LINENO` (int)
  Removido a partir do PHP 7.3.0.
`PHPDBG_FUNC` (int)
  Removido a partir do PHP 7.3.0.
`PHPDBG_COLOR_PROMPT` (int)
`PHPDBG_COLOR_NOTICE` (int)
`PHPDBG_COLOR_ERROR` (int)

# phpdbg Funções

# phpdbg_break_file

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_file — Insere um ponto de interrupção em uma linha de um arquivo

### Descrição

function phpdbg_break_file(string `$file`, int `$line`): void

Insere um ponto de interrupção na `line` fornecida no `file` fornecido.

### Parâmetros

`file`
  O nome do arquivo.
`line`
  O número da linha.

### Valor Retornado

Nenhum valor é retornado.

### Veja Também

- phpdbg_break_function() - Insere um ponto de interrupção na entrada de uma função
- phpdbg_break_method() - Insere um ponto de interrupção na entrada de um método
- phpdbg_break_next() - Insere um ponto de interrupção no próximo opcode
- phpdbg_clear() - Limpa todos os pontos de interrupção

# phpdbg_break_function

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_function — Insere um ponto de interrupção na entrada de uma função

### Descrição

function phpdbg_break_function(string `$function`): void

Insere um ponto de interrupção na entrada da `function` fornecida.

### Parâmetros

`function`
  O nome da função.

### Valor Retornado

Nenhum valor é retornado.

### Veja Também

- phpdbg_break_file() - Insere um ponto de interrupção em uma linha de um arquivo
- phpdbg_break_method() - Insere um ponto de interrupção na entrada de um método
- phpdbg_break_next() - Insere um ponto de interrupção no próximo opcode
- phpdbg_clear() - Limpa todos os pontos de interrupção

# phpdbg_break_method

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_method — Insere um ponto de interrupção na entrada de um método

### Descrição

function phpdbg_break_method(string `$class`, string `$method`): void

Insere um ponto de interrupção na entrada do `method` fornecido da `class` especificada.

### Parâmetros

`class`
  O nome da classe.
`method`
  O nome do método.

### Valor Retornado

Nenhum valor é retornado.

### Veja Também

- phpdbg_break_file() - Insere um ponto de interrupção em uma linha de um arquivo
- phpdbg_break_function() - Insere um ponto de interrupção na entrada de uma função
- phpdbg_break_next() - Insere um ponto de interrupção no próximo opcode
- phpdbg_clear() - Limpa todos os pontos de interrupção

# phpdbg_break_next

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_next — Insere um ponto de interrupção no próximo opcode

### Descrição

function phpdbg_break_next(): void

Insere um ponto de interrupção no próximo opcode.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

### Veja Também

- phpdbg_break_file() - Insere um ponto de interrupção em uma linha de um arquivo
- phpdbg_break_function() - Insere um ponto de interrupção na entrada de uma função
- phpdbg_break_method() - Insere um ponto de interrupção na entrada de um método
- phpdbg_clear() - Limpa todos os pontos de interrupção

# phpdbg_clear

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_clear — Limpa todos os pontos de interrupção

### Descrição

function phpdbg_clear(): void

Limpa todos os pontos de interrupção que foram definidos, por meio de uma das funções phpdbg_break_*() ou interativamente no console.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

### Veja Também

- phpdbg_break_file() - Insere um ponto de interrupção em uma linha de um arquivo
- phpdbg_break_function() - Insere um ponto de interrupção na entrada de uma função
- phpdbg_break_method() - Insere um ponto de interrupção na entrada de um método
- phpdbg_break_next() - Insere um ponto de interrupção no próximo opcode

# phpdbg_color

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_color — Define a cor de certos elementos

### Descrição

function phpdbg_color(int `$element`, string `$color`): void

Define a cor informada no parâmetro `color` para o elemento do parâmetro `element`.

### Parâmetros

`element`
  Uma das constantes `PHPDBG_COLOR_*`.
`color`
  Uma string com o nome da cor. Um dos valores `white` (branca), `red` (vermelha), `green` (verde), `yellow` (amarela), `blue` (azul), `purple` (roxa), `cyan` (ciano) ou `black` (preta), opcionalmente com um traço `-bold` (negrito) ou `-underline` (sublinhado), por exemplo, `white-bold` ou `green-underline`.

### Valor Retornado

Nenhum valor é retornado.

### Veja Também

- phpdbg_prompt() - Define o prompt de comando

# phpdbg_end_oplog

(PHP 7, PHP 8)

phpdbg_end_oplog — Termina um oplog

### Descrição

function phpdbg_end_oplog(array `$options` = []): ?array

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`options`

### Valor Retornado

# phpdbg_exec

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_exec — Tenta definir o contexto de execução

### Descrição

function phpdbg_exec(string `$context`): string|bool

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`context`

### Valor Retornado

Se o contexto de execução foi definido anteriormente, ele é retornado. Se o contexto de execução não foi definido anteriormente, `true` é retornado. Se a solicitação para definir o contexto falhar, `false` será retornado e um `E_WARNING` será gerado.

# phpdbg_get_executable

(PHP 7, PHP 8)

phpdbg_get_executable — Obtém um executável

### Descrição

function phpdbg_get_executable(array `$options` = []): array

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`options`

### Valor Retornado

# phpdbg_prompt

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_prompt — Define o prompt de comando

### Descrição

function phpdbg_prompt(string `$string`): void

Define o prompt de comando para a `string` fornecida.

### Parâmetros

`string`
  A string a ser usada como prompt de comando.

### Valor Retornado

Nenhum valor é retornado.

### Veja Também

- phpdbg_color() - Define a cor de certos elementos

# phpdbg_start_oplog

(PHP 7, PHP 8)

phpdbg_start_oplog — Inicia um oplog

### Descrição

function phpdbg_start_oplog(): void

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

## Índice

- phpdbg_break_file — Insere um ponto de interrupção em uma linha de um arquivo
- phpdbg_break_function — Insere um ponto de interrupção na entrada de uma função
- phpdbg_break_method — Insere um ponto de interrupção na entrada de um método
- phpdbg_break_next — Insere um ponto de interrupção no próximo opcode
- phpdbg_clear — Limpa todos os pontos de interrupção
- phpdbg_color — Define a cor de certos elementos
- phpdbg_end_oplog — Termina um oplog
- phpdbg_exec — Tenta definir o contexto de execução
- phpdbg_get_executable — Obtém um executável
- phpdbg_prompt — Define o prompt de comando
- phpdbg_start_oplog — Inicia um oplog

- Instalação/Configuração
  - Configurações em Execução
- Constantes predefinidas
- phpdbg Funções
  - phpdbg_break_file — Insere um ponto de interrupção em uma linha de um arquivo
  - phpdbg_break_function — Insere um ponto de interrupção na entrada de uma função
  - phpdbg_break_method — Insere um ponto de interrupção na entrada de um método
  - phpdbg_break_next — Insere um ponto de interrupção no próximo opcode
  - phpdbg_clear — Limpa todos os pontos de interrupção
  - phpdbg_color — Define a cor de certos elementos
  - phpdbg_end_oplog — Termina um oplog
  - phpdbg_exec — Tenta definir o contexto de execução
  - phpdbg_get_executable — Obtém um executável
  - phpdbg_prompt — Define o prompt de comando
  - phpdbg_start_oplog — Inicia um oplog

# runkit7

# Introdução

A extensão runkit7 fornece meios para modificar constantes, funções definidas pelo usuário e classes definidas pelo usuário. Ela também fornece variáveis ​​superglobais personalizadas.

Este pacote é uma bifurcação do pacote » runkit que fornece suporte ao PHP 7.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução

## Dependências

Modificação de constantes, funções, classes e métodos assim como superglobais personalizadas funcionam com todas as versões do PHP 7. Nenhum requisito especial é necessário.

## Instalação

Esta extensão » PECL não é distribuída com o PHP.

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/runkit7.

Binários do Windows (arquivos DLL) para esta extensão PECL estão disponíveis no site do PECL.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de configuração de Runkit
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
runkit.superglobal | "" | `INI_PERDIR` |
runkit.internal_override | "0" | `INI_SYSTEM` |

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`runkit.superglobal` string
  Lista separada por vírgulas de nomes de variáveis ​​a serem tratadas como superglobais. Este valor deve ser definido no arquivo php.ini do sistema, mas pode funcionar em contextos de configuração por diretório, dependendo do SAPI.

  Exemplo #1 Superglobais personalizados com runkit.superglobal=_FOO,_BAR no php.ini

      <?php
      function show_values() {
        echo "Foo é $_FOO\n";
        echo "Bar é $_BAR\n";
        echo "Baz é $_BAZ\n";
      }

      $_FOO = 'foo';
      $_BAR = 'bar';
      $_BAZ = 'baz';

      /* Exibe foo e bar, mas não baz */
      show_values();
      ?>

`runkit.internal_override` bool
  Permite modificar/renomear/remover funções internas.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`RUNKIT7_IMPORT_FUNCTIONS` (int)
  Sinalizador de runkit7_import() indicando que funções normais devem ser importadas do arquivo especificado.
`RUNKIT7_IMPORT_CLASS_METHODS` (int)
  Sinalizador de runkit7_import() indicando que os métodos de classe devem ser importados do arquivo especificado.
`RUNKIT7_IMPORT_CLASS_CONSTS` (int)
  Sinalizador de runkit7_import() indicando que as constantes de classe devem ser importadas do arquivo especificado.
`RUNKIT7_IMPORT_CLASS_PROPS` (int)
  Sinalizador de runkit7_import() indicando que as propriedades padrão da classe devem ser importadas do arquivo especificado.
`RUNKIT7_IMPORT_CLASS_STATIC_PROPS` (int)
  Sinalizador de runkit7_import() que indica que as propriedades estáticas da classe devem ser importadas do arquivo especificado. Disponível desde o Runkit 1.0.1.
`RUNKIT7_IMPORT_CLASSES` (int)
  O sinalizador de runkit7_import() representa um OR binário das constantes `RUNKIT7_IMPORT_CLASS_*`.
`RUNKIT7_IMPORT_OVERRIDE` (int)
  Sinalizador de runkit7_import() que indica que se alguma das funções, métodos, constantes ou propriedades importadas já existirem, elas devem ser substituídas pelas novas definições. Se este sinalizador não estiver definido, quaisquer definições importadas que já existam serão descartadas.
`RUNKIT7_ACC_RETURN_REFERENCE` (int)
  Inclua este sinalizador para fazer com que a função ou método que está sendo criado ou redeclarado retorne uma referência.
`RUNKIT7_ACC_PUBLIC` (int)
  Sinalizador para runkit7_method_add() e runkit7_method_redefine() para tornar o método público.
`RUNKIT7_ACC_PROTECTED` (int)
  Sinalizador para runkit7_method_add() e runkit7_method_redefine() para tornar o método protegido.
`RUNKIT7_ACC_PRIVATE` (int)
  Sinalizador para runkit7_method_add() e runkit7_method_redefine() para tornar o método privado.
`RUNKIT7_ACC_STATIC` (int)
  Sinalizador para runkit7_method_add() e runkit7_method_redefine() para tornar o método estático.
`RUNKIT7_FEATURE_MANIPULATION` (int)
  Igual a 1 se a manipulação de tempo de execução estiver habilitada e 0 caso contrário.
`RUNKIT7_FEATURE_SUPERGLOBALS` (int)
  Igual a 1 se superglobais personalizados estiverem habilitados e 0 caso contrário.
`RUNKIT7_FEATURE_SANDBOX` (int)
  Sempre 0, é impraticável implementar o recurso sandbox no PHP 7.

# Funções de runkit7

# runkit7_constant_add

(PECL runkit7 >= Unknown)

runkit7_constant_add — Semelhante a define(), mas permite definir também em definições de classe

### Descrição

function runkit7_constant_add(string `$constant_name`, mixed `$value`, int `$newVisibility` = ?): bool

### Parâmetros

`constant_name`
  Nome da constante a ser declarada. Uma string para indicar uma constante global, ou `classname::constname` para indicar uma constante de classe.
`value`
  Valor NULL, Bool, Long, Double, String, Array ou Resource para armazenar na nova constante.
`newVisibility`
  Visibilidade da constante, para constantes de classe. Pública por padrão. Uma das constantes `RUNKIT7_ACC_*`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- define() - Define uma constante com nome
- runkit7_constant_redefine() - Redefine uma constante já definida
- runkit7_constant_remove() - Remove/exclui uma constante já definida

# runkit7_constant_redefine

(PECL runkit7 >= Unknown)

runkit7_constant_redefine — Redefine uma constante já definida

### Descrição

function runkit7_constant_redefine(string `$constant_name`, mixed `$value`, int `$new_visibility` = ?): bool

### Parâmetros

`constant_name`
  Constante a ser redefinida. O nome de uma constante global, ou `classname::constname` indicando uma constante de classe.
`value`
  Valor a ser atribuído à constante.
`new_visibility`
  A nova visibilidade da constante, para constantes de classe. Inalterado por padrão. Uma das constantes `RUNKIT7_ACC_*`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- runkit7_constant_add() - Semelhante a define(), mas permite definir também em definições de classe
- runkit7_constant_remove() - Remove/exclui uma constante já definida

# runkit7_constant_remove

(PECL runkit7 >= Unknown)

runkit7_constant_remove — Remove/exclui uma constante já definida

### Descrição

function runkit7_constant_remove(string `$constant_name`): bool

### Parâmetros

`constant_name`
  Nome da constante a ser removida. Pode ser o nome de uma constante global, ou `classname::constname`, indicando uma constante de classe.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- define() - Define uma constante com nome
- runkit7_constant_add() - Semelhante a define(), mas permite definir também em definições de classe
- runkit7_constant_redefine() - Redefine uma constante já definida

# runkit7_function_add

(PECL runkit7 >= Unknown)

runkit7_function_add — Adiciona uma nova função, semelhante a create_function()

### Descrição

function runkit7_function_add(
string `$function_name`,
string `$argument_list`,
string `$code`,
bool `$return_by_reference` = `null`,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool
function runkit7_function_add(
string `$function_name`,
Closure `$closure`,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool

### Parâmetros

`function_name`
  Nome da função a ser criada
`argument_list`
  Lista de argumentos separados por vírgula
`code`
  Código que compõe a função
`closure`
  Um closure que define a função.
`return_by_reference`
  Informa se a função deve retornar por referência.
`doc_comment`
  O comentário documental da função.
`return_type`
  O tipo de retorno da função.
`is_strict`
  Informa se a função deve se comportar como se tivesse sido declarada em um arquivo com `strict_types=1`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Um exemplo de runkit7_function_add()

    <?php
    runkit7_function_add('testme','$a,$b','echo "O valor de a é $a\n"; echo "O valor de b é $b\n";');
    testme(1,2);
    ?>

O exemplo acima produzirá:

    O valor de a é 1
    O valor de b é 2

### Veja Também

- create_function() - Cria uma função dinamicamente avaliando uma string de código
- runkit7_function_redefine() - Substitui uma definição de função por uma nova implementação
- runkit7_function_copy() - Copia uma função para um novo nome de função
- runkit7_function_rename() - Altera o nome de uma função
- runkit7_function_remove() - Remove uma definição de função
- runkit7_method_add() - Adiciona dinamicamente um novo método a uma determinada classe

# runkit7_function_copy

(PECL runkit7 >= Unknown)

runkit7_function_copy — Copia uma função para um novo nome de função

### Descrição

function runkit7_function_copy(string `$source_name`, string `$target_name`): bool

### Parâmetros

`source_name`
  Nome da função existente.
`target_name`
  Nome da nova função para a qual a definição será copiada.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Um exemplo de runkit7_function_copy()

    <?php
    function original() {
      echo "Dentro de uma função\n";
    }
    runkit7_function_copy('original','duplicate');
    original();
    duplicate();
    ?>

O exemplo acima produzirá:

    Dentro de uma função
    Dentro de uma função

### Veja Também

- runkit7_function_add() - Adiciona uma nova função, semelhante a create_function
- runkit7_function_redefine() - Substitui uma definição de função por uma nova implementação
- runkit7_function_rename() - Altera o nome de uma função
- runkit7_function_remove() - Remove uma definição de função

# runkit7_function_redefine

(PECL runkit7 >= Unknown)

runkit7_function_redefine — Substitui uma definição de função por uma nova implementação

### Descrição

function runkit7_function_redefine(
string `$function_name`,
string `$argument_list`,
string `$code`,
bool `$return_by_reference` = `null`,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool
function runkit7_function_redefine(
string `$function_name`,
Closure `$closure`,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool

> Nota: Por padrão, apenas funções criadas pelo usuário podem ser removidas, renomeadas ou modificadas. Para sobrescrever funções internas, a configuração `runkit.internal_override` deve ser habilitada no php.ini.

### Parâmetros

`function_name`
  Nome da função a ser redefinida
`argument_list`
  Nova lista de argumentos a serem aceitos pela função
`code`
  Implementação de novo código
`closure`
  Um closure que define a função.
`return_by_reference`
  Informa se a função deve retornar por referência.
`doc_comment`
  O comentário documental da função.
`return_type`
  O tipo de retorno da função.
`is_strict`
  Informa se a função se comporta como se tivesse sido declarada em um arquivo com `strict_types=1`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Um exemplo de runkit7_function_redefine()

    <?php
    function testme() {
      echo "Implementação original de Testme\n";
    }
    testme();
    runkit7_function_redefine('testme','','echo "Nova implementação de Testme\n";');
    testme();
    ?>

O exemplo acima produzirá:

    Implementação original de Testme
    Nova implementação de Testme

### Veja Também

- runkit7_function_add() - Adiciona uma nova função, semelhante a create_function
- runkit7_function_copy() - Copia uma função para um novo nome de função
- runkit7_function_rename() - Altera o nome de uma função
- runkit7_function_remove() - Remove uma definição de função
- runkit7_method_redefine() - Altera dinamicamente o código do método fornecido

# runkit7_function_remove

(PECL runkit7 >= Unknown)

runkit7_function_remove — Remove uma definição de função

### Descrição

function runkit7_function_remove(string `$function_name`): bool

> Nota: Por padrão, apenas funções criadas pelo usuário podem ser removidas, renomeadas ou modificadas. Para sobrescrever funções internas, a configuração `runkit.internal_override` deve ser habilitada no php.ini.

### Parâmetros

`function_name`
  Nome da função a ser excluída

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- runkit7_function_add() - Adiciona uma nova função, semelhante a create_function
- runkit7_function_copy() - Copia uma função para um novo nome de função
- runkit7_function_redefine() - Substitui uma definição de função por uma nova implementação
- runkit7_function_rename() - Altera o nome de uma função

# runkit7_function_rename

(PECL runkit7 >= Unknown)

runkit7_function_rename — Altera o nome de uma função

### Descrição

function runkit7_function_rename(string `$source_name`, string `$target_name`): bool

> Nota: Por padrão, apenas funções criadas pelo usuário podem ser removidas, renomeadas ou modificadas. Para sobrescrever funções internas, a configuração `runkit.internal_override` deve ser habilitada no php.ini.

### Parâmetros

`source_name`
  Nome atual da função.
`target_name`
  Novo nome da função.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- runkit7_function_add() - Adiciona uma nova função, semelhante a create_function
- runkit7_function_copy() - Copia uma função para um novo nome de função
- runkit7_function_redefine() - Substitui uma definição de função por uma nova implementação
- runkit7_function_remove() - Remove uma definição de função

# runkit7_import

(PECL runkit7 >= Unknown)

runkit7_import — Processa um arquivo PHP importando definições de função e classe, substituindo quando apropriado

Aviso

This feature has been removed in PECL runkit7 4.0.0.

### Descrição

function runkit7_import(string `$filename`, int `$flags` = ?): bool

Semelhante a include. No entanto, qualquer código que resida fora de uma função ou classe é simplesmente ignorado. Além disso, dependendo do valor de `flags`, quaisquer funções ou classes que já existam no ambiente em execução podem ser substituídas automaticamente por suas novas definições.

### Parâmetros

`filename`
  Nome do arquivo do qual as definições de função e classe serão importadas.
`flags`
  OR binário da família de constantes `RUNKIT7_IMPORT_*`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# runkit7_method_add

(PECL runkit7 >= Unknown)

runkit7_method_add — Adiciona dinamicamente um novo método a uma determinada classe

### Descrição

function runkit7_method_add(
string `$class_name`,
string `$method_name`,
string `$argument_list`,
string `$code`,
int `$flags` = RUNKIT7_ACC_PUBLIC,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool
function runkit7_method_add(
string `$class_name`,
string `$method_name`,
Closure `$closure`,
int `$flags` = RUNKIT7_ACC_PUBLIC,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool

### Parâmetros

`class_name`
  A classe à qual este método será adicionado.
`method_name`
  O nome do método a ser adicionado.
`argument_list`
  Lista de argumentos delimitada por vírgulas para o método recém-criado.
`code`
  O código a ser avaliado quando `method_name` é chamado.
`closure`
  Um closure que define o método.
`flags`
  O tipo de método a ser criado pode ser `RUNKIT7_ACC_PUBLIC`, `RUNKIT7_ACC_PROTECTED` ou `RUNKIT7_ACC_PRIVATE`, opcionalmente combinado via OR binário com `RUNKIT7_ACC_STATIC`.
`doc_comment`
  O comentário documental do método.
`return_type`
  O tipo de retorno do método.
`is_strict`
  Informa se o método se comporta como se tivesse sido declarado em um arquivo com `strict_types=1`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de runkit7_method_add()

    <?php
    class Example {
        function foo() {
            echo "foo!\n";
        }
    }

    // cria um objeto da classe Example
    $e = new Example();

    // Adiciona um novo método público
    runkit7_method_add(
        'Example',
        'add',
        '$num1, $num2',
        'return $num1 + $num2;',
        RUNKIT7_ACC_PUBLIC
    );

    // adiciona 12 + 4
    echo $e->add(12, 4);
    ?>

O exemplo acima produzirá:

    16

### Veja Também

- runkit7_method_copy() - Copia um método de uma classe para outra
- runkit7_method_redefine() - Altera dinamicamente o código do método fornecido
- runkit7_method_remove() - Remove dinamicamente o método fornecido
- runkit7_method_rename() - Altera dinamicamente o nome do método fornecido
- runkit7_function_add() - Adiciona uma nova função, semelhante a create_function

# runkit7_method_copy

(PECL runkit7 >= Unknown)

runkit7_method_copy — Copia um método de uma classe para outra

### Descrição

function runkit7_method_copy(
string `$destination_class`,
string `$destination_method_name`,
string `$source_class`,
string `$source_method_name` = ?
): bool

### Parâmetros

`destination_class`
  Classe de destino para o método copiado
`destination_method_name`
  Nome do método de destino
`source_class`
  Classe de origem do método a ser copiado
`source_method_name`
  Nome do método a ser copiado da classe de origem. Se este parâmetro for omitido, o valor de `destination_method_name` será assumido.

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de runkit7_method_copy()

    <?php
    class Foo {
        function example() {
            return "foo!\n";
        }
    }

    class Bar {
        // inicialmente, nenhum método
    }

    // copia o método example() da classe Foo para a classe Bar, como baz()
    runkit7_method_copy('Bar', 'baz', 'Foo', 'example');

    // exibe a função copiada
    echo Bar::baz();
    ?>

O exemplo acima produzirá:

    foo!

### Veja Também

- runkit7_method_add() - Adiciona dinamicamente um novo método a uma determinada classe
- runkit7_method_redefine() - Altera dinamicamente o código do método fornecido
- runkit7_method_remove() - Remove dinamicamente o método fornecido
- runkit7_method_rename() - Altera dinamicamente o nome do método fornecido
- runkit7_function_copy() - Copia uma função para um novo nome de função

# runkit7_method_redefine

(PECL runkit7 >= Unknown)

runkit7_method_redefine — Altera dinamicamente o código do método fornecido

### Descrição

function runkit7_method_redefine(
string `$class_name`,
string `$method_name`,
string `$argument_list`,
string `$code`,
int `$flags` = RUNKIT7_ACC_PUBLIC,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool
function runkit7_method_redefine(
string `$class_name`,
string `$method_name`,
Closure `$closure`,
int `$flags` = RUNKIT7_ACC_PUBLIC,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool

### Parâmetros

`class_name`
  A classe na qual o método será redefinido.
`method_name`
  O nome do método a ser redefinido.
`argument_list`
  Lista de argumentos delimitada por vírgulas para o método redefinido.
`code`
  O novo código a ser avaliado quando `method_name` for chamado.
`closure`
  Um closure que define o método.
`flags`
  O método redefinido pode ser `RUNKIT7_ACC_PUBLIC`, `RUNKIT7_ACC_PROTECTED` ou `RUNKIT7_ACC_PRIVATE`, opcionalmente combinado via OR binário com `RUNKIT7_ACC_STATIC`.
`doc_comment`
  O comentário documental do método.
`return_type`
  O tipo de retorno do método.
`is_strict`
  Informa se o método deve se comportar como se tivesse sido declarado em um arquivo com `strict_types=1`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de runkit7_method_redefine()

    <?php
    class Example {
        function foo() {
            return "foo!\n";
        }
    }

    // cria um objeto da classe Example
    $e = new Example();

    // exibe Example::foo() (antes da redefinição)
    echo "Antes: " . $e->foo();

    // Redefine o método 'foo'
    runkit7_method_redefine(
        'Example',
        'foo',
        '',
        'return "bar!\n";',
        RUNKIT7_ACC_PUBLIC
    );

    // exibe Example::foo() (depois da redefinição)
    echo "Depois: " . $e->foo();
    ?>

O exemplo acima produzirá:

    Antes: foo!
    Depois: bar!

### Veja Também

- runkit7_method_add() - Adiciona dinamicamente um novo método a uma determinada classe
- runkit7_method_copy() - Copia um método de uma classe para outra
- runkit7_method_remove() - Remove dinamicamente o método fornecido
- runkit7_method_rename() - Altera dinamicamente o nome do método fornecido
- runkit7_function_redefine() - Substitui uma definição de função por uma nova implementação

# runkit7_method_remove

(PECL runkit7 >= Unknown)

runkit7_method_remove — Remove dinamicamente o método fornecido

### Descrição

function runkit7_method_remove(string `$class_name`, string `$method_name`): bool

> Nota: Esta função não pode ser usada para manipular o método atualmente em execução (ou encadeado).

### Parâmetros

`class_name`
  A classe da qual o método deve ser removido.
`method_name`
  O nome do método a ser removido.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de runkit7_method_remove()

    <?php
    class Example {
        function foo() {
            return "foo!\n";
        }

        function bar() {
            return "bar!\n";
        }
    }

    // Remove o método 'foo'
    runkit7_method_remove(
        'Example',
        'foo'
    );

    echo implode(' ', get_class_methods('Example'));

    ?>

O exemplo acima produzirá:

    bar

### Veja Também

- runkit7_method_add() - Adiciona dinamicamente um novo método a uma determinada classe
- runkit7_method_copy() - Copia um método de uma classe para outra
- runkit7_method_redefine() - Altera dinamicamente o código do método fornecido
- runkit7_method_rename() - Altera dinamicamente o nome do método fornecido
- runkit7_function_remove() - Remove uma definição de função

# runkit7_method_rename

(PECL runkit7 >= Unknown)

runkit7_method_rename — Altera dinamicamente o nome do método fornecido

### Descrição

function runkit7_method_rename(string `$class_name`, string `$source_method_name`, string `$target_method_name`): bool

> Nota: Esta função não pode ser usada para manipular o método atualmente em execução (ou encadeado).

### Parâmetros

`class_name`
  A classe na qual o método deve ser renomeado
`source_method_name`
  O nome do método a ser renomeado.
`target_method_name`
  O novo nome a ser dado ao método.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de runkit7_method_rename()

    <?php
    class Example {
        function foo() {
            return "foo!\n";
        }
    }

    // Renomeia o método 'foo' para 'bar'
    runkit7_method_rename(
        'Example',
        'foo',
        'bar'
    );

    // exibe o método renomeado
    echo (new Example)->bar();
    ?>

O exemplo acima produzirá:

    foo!

### Veja Também

- runkit7_method_add() - Adiciona dinamicamente um novo método a uma determinada classe
- runkit7_method_copy() - Copia um método de uma classe para outra
- runkit7_method_redefine() - Altera dinamicamente o código do método fornecido
- runkit7_method_remove() - Remove dinamicamente o método fornecido
- runkit7_function_rename() - Altera o nome de uma função

# runkit7_object_id

(PECL runkit7 >= Unknown)

runkit7_object_id — Retorna o identificador inteiro do objeto fornecido

### Descrição

function runkit7_object_id(object `$obj`): int

Esta função é equivalente a spl_object_id().

Esta função retorna um identificador único para o objeto. O ID do objeto é único durante toda a vida útil do objeto. Uma vez que o objeto é destruído, seu ID pode ser reutilizado para outros objetos. Este comportamento é semelhante a spl_object_hash().

### Parâmetros

`obj`
  Qualquer objeto.

### Valor Retornado

Um identificador inteiro que é único para cada objeto existente e é sempre o mesmo para cada objeto.

### Notas

> Nota: Quando um objeto é destruído, seu identificador pode ser reutilizado para outros objetos.

### Veja Também

- spl_object_id() - Retorna o identificador inteiro do objeto fornecido

# runkit7_superglobals

(PECL runkit7 >= Unknown)

runkit7_superglobals — Retorna um array indexado numericamente de superglobais registradas

### Descrição

function runkit7_superglobals(): array

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array indexada numericamente das superglobais atualmente registradas. ou seja, _GET, _POST, _REQUEST, _COOKIE, _SESSION, _SERVER, _ENV e _FILES.

### Veja Também

- Escopo de variáveis

# runkit7_zval_inspect

(PECL runkit7 >= Unknown)

runkit7_zval_inspect — Retorna informações sobre o valor passado com tipos de dados, contagens de referência, etc.

### Descrição

function runkit7_zval_inspect(string `$value`): array

### Parâmetros

`value`
  O valor do qual a representação será retornada.

### Valor Retornado

O array retornado por esta função contém os seguintes elementos:

- `address`(endereço)
- `refcount` (contagem de referência - opcional)
- `is_ref` (informa se é referência - opcional)
- `type` (tipo)

### Exemplos

Exemplo #1 Exemplo de runkit7_zval_inspect()

    <?php

    $var = new DateTime();
    var_dump(runkit7_zval_inspect($var));

    $var = 1;
    var_dump(runkit7_zval_inspect($var));
    ?>

O exemplo acima produzirá:

    array(4) {
      ["address"]=>
      string(14) "0x7f45ab21b1e0"
      ["refcount"]=>
      int(2)
      ["is_ref"]=>
      bool(false)
      ["type"]=>
      int(8)
    }

    array(2) {
      ["address"]=>
      string(14) "0x7f45ab21b1e0"
      ["type"]=>
      int(4)
    }

### Veja Também

- Referências explicadas
- » Referências explicadas (por Derick Rethans)

## Índice

- runkit7_constant_add — Semelhante a define(), mas permite definir também em definições de classe
- runkit7_constant_redefine — Redefine uma constante já definida
- runkit7_constant_remove — Remove/exclui uma constante já definida
- runkit7_function_add — Adiciona uma nova função, semelhante a create_function
- runkit7_function_copy — Copia uma função para um novo nome de função
- runkit7_function_redefine — Substitui uma definição de função por uma nova implementação
- runkit7_function_remove — Remove uma definição de função
- runkit7_function_rename — Altera o nome de uma função
- runkit7_import — Processa um arquivo PHP importando definições de função e classe, substituindo quando apropriado
- runkit7_method_add — Adiciona dinamicamente um novo método a uma determinada classe
- runkit7_method_copy — Copia um método de uma classe para outra
- runkit7_method_redefine — Altera dinamicamente o código do método fornecido
- runkit7_method_remove — Remove dinamicamente o método fornecido
- runkit7_method_rename — Altera dinamicamente o nome do método fornecido
- runkit7_object_id — Retorna o identificador inteiro do objeto fornecido
- runkit7_superglobals — Retorna um array indexado numericamente de superglobais registradas
- runkit7_zval_inspect — Retorna informações sobre o valor passado com tipos de dados, contagens de referência, etc.

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
- Constantes predefinidas
- Funções de runkit7
  - runkit7_constant_add — Semelhante a define(), mas permite definir também em definições de classe
  - runkit7_constant_redefine — Redefine uma constante já definida
  - runkit7_constant_remove — Remove/exclui uma constante já definida
  - runkit7_function_add — Adiciona uma nova função, semelhante a create_function
  - runkit7_function_copy — Copia uma função para um novo nome de função
  - runkit7_function_redefine — Substitui uma definição de função por uma nova implementação
  - runkit7_function_remove — Remove uma definição de função
  - runkit7_function_rename — Altera o nome de uma função
  - runkit7_import — Processa um arquivo PHP importando definições de função e classe, substituindo quando apropriado
  - runkit7_method_add — Adiciona dinamicamente um novo método a uma determinada classe
  - runkit7_method_copy — Copia um método de uma classe para outra
  - runkit7_method_redefine — Altera dinamicamente o código do método fornecido
  - runkit7_method_remove — Remove dinamicamente o método fornecido
  - runkit7_method_rename — Altera dinamicamente o nome do método fornecido
  - runkit7_object_id — Retorna o identificador inteiro do objeto fornecido
  - runkit7_superglobals — Retorna um array indexado numericamente de superglobais registradas
  - runkit7_zval_inspect — Retorna informações sobre o valor passado com tipos de dados, contagens de referência, etc.

# Operações do usuário para Zend

# Introdução

A extensão uopz - Operações do Usuário para Zend - expõe a funcionalidade do mecanismo Zend normalmente usada em tempo de compilação e execução para permitir a modificação das estruturas internas que representam o código PHP, e para que o código do usuário interaja com a Máquina Virtual.

A uopz apoia as seguintes atividades:

- Sobrecarga de alguns opcodes, incluindo ZEND_EXIT e ZEND_NEW
- Funções e métodos de backup e restauração
- Renomeação de funções e métodos
- Cópia de funções e métodos
- Exclusão de funções e métodos
- Redefinição de constantes globais e de classe
- Exclusão de constantes globais e de classe
- Composição e modificação de classes em tempo de execução

> Nota:

> Todas as atividades suportadas são compatíveis com opcache.

Cuidado

PECL uopz 6.1.1 não é compatível com Xdebug >= 2.9.4. Versões posteriores do uopz não são compatíveis com Xdebug < 2.9.4.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução

## Dependências

A partir do uopz 5.0, é necessário PHP 7.0. A partir do uopz 5.1, é necessário PHP 7.1+.

## Instalação

As versões do uopz são hospedadas pelo PECL e o código-fonte pelo » github, o caminho mais fácil para a instalação é o caminho normal do PECL: » https://pecl.php.net/package/uopz.

Usuários do Windows podem baixar binários de lançamento pré-compilados no site » PECL.

A partir do uopz 5.0.0 a extensão deveria ser carregada como extension. Antes dessa versão, ela deveria ser carregada como zend_extension.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de Configuração de uopz
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
uopz.disable | "0" | `INI_SYSTEM` | Disponível a partir do uopz 5.0.2.
uopz.exit | "0" | `INI_SYSTEM` | Disponível a partir do uopz 6.0.1.
uopz.overloads | "1" | `INI_SYSTEM` | Disponível a partir do uopz 2.0.2. Removida a partir do uopz 5.0.0.

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`uopz.disable` bool

  Se habilitada, o uopz não deverá mais ter qualquer efeito no mecanismo.

`uopz.exit` bool

  Permitir ou não a execução de opcodes de saída. Esta configuração pode ser substituída durante a execução chamando uopz_allow_exit().

`uopz.overloads` bool

  Habilita a capacidade de usar uopz_overload().

> Nota: Ao executar com o OPcache habilitado, pode ser necessário desabilitar todas as otimizações do OPcache (`opcache.optimization_level=0`).

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

Os seguintes opcodes são definidos como constantes pelo uopz antes da versão 5.0.0:

`ZEND_EXIT` (int)
  Invocado por exit() e die(), não recebe argumentos. Retorna o booleano `true` para sair, `false` para continuar.
`ZEND_NEW` (int)
  Invocado pela construção do objeto, recebe a classe do objeto que está sendo criado como único argumento.
`ZEND_THROW` (int)
  Invocado pela construção throw, recebe a classe da exceção lançada como único argumento.
`ZEND_FETCH_CLASS` (int)
  Invocado após a composição, recebe o nome da classe que está sendo buscada como único argumento.
`ZEND_ADD_TRAIT` (int)
  Invocado após a composição, recebe a classe à qual o Trait está sendo adicionada como o primeiro argumento, e o nome do Trait como o segundo argumento.
`ZEND_ADD_INTERFACE` (int)
  Invocado após a composição, recebe a classe à qual a interface está sendo adicionada como o primeiro argumento, e o nome da interface como o segundo argumento
`ZEND_INSTANCEOF` (int)
  Invocado pelo operador instanceof, recebe o objeto a ser verificado como o primeiro argumento, e o nome da classe à qual esse objeto deve pertencer como o segundo argumento.

As seguintes constantes controlam o comportamento da máquina virtual após a invocação de um manipulador de usuário. Tenha muito cuidado! Essas constantes foram removidas a partir do uopz 5.0.0.

`ZEND_USER_OPCODE_CONTINUE` (int)
  Avança 1 opcode e continua.
`ZEND_USER_OPCODE_ENTER` (int)
  Entra em novo op_array sem recursão.
`ZEND_USER_OPCODE_LEAVE` (int)
  Retorna para chamar op_array dentro do mesmo executor.
`ZEND_USER_OPCODE_DISPATCH` (int)
  Envia para o manipulador de opcode original.
`ZEND_USER_OPCODE_DISPATCH_TO` (int)
  Envia para um manipulador específico (operação OR com constante de opcode ZEND).
`ZEND_USER_OPCODE_RETURN` (int)
  Sai do executor (retorna da função).

Os seguintes modificadores são registrados como constantes pelo uopz:

`ZEND_ACC_PUBLIC` (int)
  Marca as funções como públicas, o padrão.
`ZEND_ACC_PROTECTED` (int)
  Marca as funções como protegidas.
`ZEND_ACC_PRIVATE` (int)
  Marca as funções como privadas.
`ZEND_ACC_STATIC` (int)
  Marca as funções como estáticas.
`ZEND_ACC_FINAL` (int)
  Marca as funções como finais.
`ZEND_ACC_ABSTRACT` (int)
  Marca as funções como abstratas.
`ZEND_ACC_CLASS` (int)
  Fictício registrado para consistência, o tipo padrão de entrada de classe. Removido a partir do uopz 5.0.0.
`ZEND_ACC_INTERFACE` (int)
  Marca as classes como interfaces. Removido a partir do uopz 5.0.0.
`ZEND_ACC_TRAIT` (int)
  Marca as classes como Traits. Removido a partir do uopz 5.0.0.
`ZEND_ACC_FETCH` (int)
  Usado somente para obtenção de sinalizadores. Removido a partir do uopz 5.0.0.

# Funções de Uopz

# uopz_add_function

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_add_function — Adiciona função ou método inexistente

### Descrição

function uopz_add_function(string `$function`, Closure `$handler`, int `&$flags` = ZEND_ACC_PUBLIC): bool
function uopz_add_function(
string `$class`,
string `$function`,
Closure `$handler`,
int `&$flags` = ZEND_ACC_PUBLIC,
int `&$all` = `true`
): bool

Adiciona uma função ou um método inexistente.

### Parâmetros

`class`

  O nome da classe.

`function`

  O nome da função ou do método.

`handler`

  O Closure que define a nova função ou método.

`flags`

  Sinalizadores a serem definidos para a nova função ou método.

`all`

  Informa se todas as classes que descendem de `class` também serão afetadas.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

uopz_add_function() lança uma RuntimeException se a função ou método a ser adicionado já existir.

### Exemplos

Exemplo #1 Uso básico de uopz_add_function()

    <?php
    uopz_add_function('foo', function () {echo 'bar';});
    foo();
    ?>

O exemplo acima produzirá:

    bar

### Veja Também

- uopz_del_function() - Exclui função ou método adicionado anteriormente
- uopz_set_return() - Fornece um valor de retorno para uma função existente

# uopz_allow_exit

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_allow_exit — Permite o controle sobre o código de operação de saída desabilitado

### Descrição

function uopz_allow_exit(bool `$allow`): void

Por padrão, o uopz desabilita o opcode de saída, então chamadas exit() são praticamente ignoradas. uopz_allow_exit() permite controlar esse comportamento.

### Parâmetros

`allow`

  Informa se deve ou não ser permitida a execução de opcodes de saída.

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de uopz_allow_exit()

    <?php
    exit(1);
    echo 1;
    uopz_allow_exit(true);
    exit(2);
    echo 2;
    ?>

O exemplo acima produzirá:

    1

### Notas

Cuidado

OPcache otimiza o código morto após a saída incondicional.

### Veja Também

- uopz_get_exit_status() - Recupera o último status de saída definido

# uopz_backup

(PECL uopz 1 >= 1.0.3, PECL uopz 2)

uopz_backup — Faz backup de uma função

Aviso

Esta função foi REMOVIDA na uopz 5.0.0 no PECL.

### Descrição

function uopz_backup(string `$function`): void
function uopz_backup(string `$class`, string `$function`): void

Faz backup de uma função em tempo de execução, para ser restaurada no desligamento.

### Parâmetros

`class`

  O nome da classe que contém a função para backup

`function`

  O nome da função

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de uopz_backup()

    <?php
    uopz_backup("fgets");
    uopz_function("fgets", function(){
        return true;
    });
    var_dump(fgets());
    ?>

O exemplo acima produzirá:

    bool(true)

# uopz_compose

(PECL uopz 1, PECL uopz 2)

uopz_compose — Compõe uma classe

Aviso

Esta função foi REMOVIDA na uopz 5.0.0 no PECL.

### Descrição

function uopz_compose(
string `$name`,
array `$classes`,
array `$methods` = ?,
array `$properties` = ?,
int `$flags` = ?
): void

Cria uma nova classe com o nome fornecido que implementa, estende ou usa todas as classes fornecidas.

### Parâmetros

`name`

  Um nome de classe válido.

`classes`

  Um array de nomes de classes, interfaces e traits.

`methods`

  Um array associativa de métodos, os valores são Closures ou [modificadores => Closure].

`properties`

  Um array associativa de propriedades, chaves são nomes, valores são modificadores.

`flags`

  Tipo da entrada, por padrão ZEND_ACC_CLASS.

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de uopz_compose()

    <?php
    class myClass {}
    trait myTrait {}
    interface myInterface {}

    uopz_compose(
        Composed::class, [
            myClass::class,
            myTrait::class,
            myInterface::class
        ], [
        "__construct" => function() {
            /* ... */
        }
    ]);

    var_dump(
     class_uses(Composed::class),
     class_parents(Composed::class),
     class_implements(Composed::class));
    ?>

O exemplo acima produzirá:

    array(1) {
      ["myTrait"]=>
      string(7) "myTrait"
    }
    array(1) {
      ["myClass"]=>
      string(7) "myClass"
    }
    array(1) {
      ["myInterface"]=>
      string(11) "myInterface"
    }

# uopz_copy

(PECL uopz 1 >= 1.0.4, PECL uopz 2)

uopz_copy — Copia uma função

Aviso

Esta função foi REMOVIDA na uopz 5.0.0 no PECL.

### Descrição

function uopz_copy(string `$function`): Closure
function uopz_copy(string `$class`, string `$function`): Closure

Copia uma função por nome.

### Parâmetros

`class`

  O nome da classe que contém a função a ser copiada.

`function`

  O nome da função

### Valor Retornado

Um Closure para a função especificada.

### Exemplos

Exemplo #1 Exemplo de uopz_copy()

    <?php
    $strtotime = uopz_copy('strtotime');

    uopz_function("strtotime", function($arg1, $arg2) use($strtotime) {
        /* pode chamar o strtotime original daqui */
        var_dump($arg1);
    });

    var_dump(strtotime('dummy'));
    ?>

O exemplo acima produzirá:

    string(5) "dummy"

# uopz_del_function

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_del_function — Exclui função ou método adicionado anteriormente

### Descrição

function uopz_del_function(string `$function`): bool
function uopz_del_function(string `$class`, string `$function`, int `&$all` = `true`): bool

Exclui função ou método adicionado anteriormente.

### Parâmetros

`class`

  O nome da classe.

`function`

  O nome da função ou do método.

`all`

  Informa se todas as classes que descendem de `class` também serão afetadas.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

uopz_del_function() lança uma RuntimeException se a função ou método a ser excluído não tiver sido adicionado por uopz_add_function().

### Exemplos

Exemplo #1 Uso básico de uopz_del_function()

    <?php
    uopz_add_function('foo', function () {echo 'bar';});
    var_dump(function_exists('foo'));
    uopz_del_function('foo');
    var_dump(function_exists('foo'));
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(false)

### Veja Também

- uopz_add_function() - Adiciona função ou método inexistente
- uopz_unset_return() - Desfaz um valor de retorno previamente definido para uma função

# uopz_delete

(PECL uopz 1, PECL uopz 2)

uopz_delete — Exclui uma função

Aviso

Esta função foi REMOVIDA na uopz 5.0.0 no PECL.

### Descrição

function uopz_delete(string `$function`): void
function uopz_delete(string `$class`, string `$function`): void

Exclui uma função ou um método.

### Parâmetros

`class`

`function`

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de uopz_delete()

    <?php
    uopz_delete("strlen");

    echo strlen("Hello World");
    ?>

O exemplo acima produzirá algo semelhante a:

    PHP Fatal error: Call to undefined function strlen() in /path/to/script.php on line 4

Exemplo #2 Exemplo de uopz_delete() com uma classe

    <?php
    class My {
        public static function strlen($arg) {
            return strlen($arg);
        }
    }

    uopz_delete(My::class, "strlen");

    echo My::strlen("Hello World");
    ?>

O exemplo acima produzirá algo semelhante a:

    PHP Fatal error: Call to undefined method My::strlen() in /path/to/script.php on line 10

# uopz_extend

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7 < 7.1.0)

uopz_extend — Estende uma classe em tempo de execução

### Descrição

function uopz_extend(string `$class`, string `$parent`): bool

Faz a classe em `class` estender a classe pai em `parent`.

### Parâmetros

`class`

  O nome da classe a ser estendida.

`parent`

  O nome da classe a herdar.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

A partir do PHP 7.4.0, uopz_extend() lança uma RuntimeException, se OPcache estiver habilitado, e a entrada de classe de `class` ou `parent` (se for uma trait) for imutável.

### Exemplos

Exemplo #1 Exemplo de uopz_extend()

    <?php
    class A {}
    class B {}

    uopz_extend(A::class, B::class);

    var_dump(class_parents(A::class));
    ?>

O exemplo acima produzirá:

    array(1) {
      ["B"]=>
      string(1) "B"
    }

# uopz_flags

(PECL uopz 2 >= 2.0.2, PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_flags — Obtém ou define sinalizadores em função ou classe

### Descrição

function uopz_flags(string `$function`, int `$flags` = PHP_INT_MAX): int
function uopz_flags(string `$class`, string `$function`, int `$flags` = PHP_INT_MAX): int

Obtém ou define os sinalizadores em uma entrada de classe ou função em tempo de execução.

### Parâmetros

`class`

  O nome de uma classe

`function`

  O nome da função. Se `class` for fornecido e uma string vazia for passada como `function`, uopz_flags() obtém ou define os sinalizadores da entrada da classe.

`flags`

  Um conjunto válido de sinalizadores ZEND_ACC_. Se omitido, uopz_flags() atua como obtentora.

### Valor Retornado

Se os sinalizadores estiverem sendo definidos, retorna os anteriores, senão retorna os atuais.

### Erros/Exceções

A partir do PHP 7.4.0, se o parâmetro `flags` for passado, uopz_flags() lança uma RuntimeException, se OPcache estiver habilitado, e a entrada de classe de `class` ou a entrada de função de `function` for imutável.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL uopz 5.0.0 | O parâmetro `flags` agora é opcional. Anteriormente, `ZEND_ACC_FETCH` precisava ser passado para usar uopz_flags() como obtentora.

### Exemplos

Exemplo #1 Exemplo de uopz_flags()

    <?php
    class Test {
        public function method() {
            return __CLASS__;
        }
    }

    $flags = uopz_flags("Test", "method");

    var_dump((bool) (uopz_flags("Test", "method") & ZEND_ACC_PRIVATE));
    var_dump((bool) (uopz_flags("Test", "method") & ZEND_ACC_STATIC));

    var_dump(uopz_flags("Test", "method", $flags|ZEND_ACC_STATIC|ZEND_ACC_PRIVATE));

    var_dump((bool) (uopz_flags("Test", "method") & ZEND_ACC_PRIVATE));
    var_dump((bool) (uopz_flags("Test", "method") & ZEND_ACC_STATIC));
    ?>

O exemplo acima produzirá:

    bool(false)
    bool(false)
    int(1234567890)
    bool(true)
    bool(true)

Exemplo #2 "Desfinalizando" uma classe

    <?php
    final class MyClass
    {
    }

    $flags = uopz_flags(MyClass::class, '');
    uopz_flags(MyClass::class, '', $flags & ~ZEND_ACC_FINAL);
    var_dump((new ReflectionClass(MyClass::class))->isFinal());
    ?>

O exemplo acima produzirá:

    bool(false)

# uopz_function

(PECL uopz 1, PECL uopz 2)

uopz_function — Cria uma função em tempo de execução

Aviso

Esta função foi REMOVIDA na uopz 5.0.0 no PECL.

### Descrição

function uopz_function(string `$function`, Closure `$handler`, int `$modifiers` = ?): void
function uopz_function(
string `$class`,
string `$function`,
Closure `$handler`,
int `$modifiers` = ?
): void

Cria uma função em tempo de execução.

### Parâmetros

`class`

  O nome da classe que irá receber a nova função.

`function`

  O nome da função

`handler`

  O Closure para a função.

`modifiers`

  Os modificadores para a função, por padrão copiados ou ZEND_ACC_PUBLIC.

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de uopz_function()

    <?php
    uopz_function("my_strlen", function($arg) {
        return strlen($arg);
    });
    echo my_strlen("Hello World");
    ?>

O exemplo acima produzirá:

    11

Exemplo #2 Exemplo de uopz_function() com uma classe

    <?php
    class My {}

    uopz_function(My::class, "strlen", function($arg) {
        return strlen($arg);
    }, ZEND_ACC_STATIC);

    echo My::strlen("Hello World");
    ?>

O exemplo acima produzirá:

    11

# uopz_get_exit_status

(PECL uopz 5, PECL uopz , PECL uopz 7)

uopz_get_exit_status — Recupera o último status de saída definido

### Descrição

function uopz_get_exit_status(): mixed

Recupera o último status de saída definido, ou seja, o valor passado para exit().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Esta função retorna o último status de saída, ou `null` se exit() não tiver sido chamada.

### Exemplos

Exemplo #1 Exemplo de uopz_get_exit_status()

    <?php
    exit(123);
    echo uopz_get_exit_status();?>

O exemplo acima produzirá:

    123

### Notas

Cuidado

OPcache otimiza o código morto após a saída incondicional.

### Veja Também

- uopz_allow_exit() - Permite o controle sobre o código de operação de saída desabilitado

# uopz_get_hook

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_hook — Obtém o gancho previamente definido na função ou método

### Descrição

function uopz_get_hook(string `$function`): Closure
function uopz_get_hook(string `$class`, string `$function`): Closure

Obtém o gancho previamente definido na função ou método.

### Parâmetros

`class`

  O nome da classe.

`function`

  O nome da função ou do método.

### Valor Retornado

Retorna o gancho definido anteriormente em uma função ou método, ou `null` se nenhum gancho tiver sido definido.

### Exemplos

Exemplo #1 Uso básico de uopz_get_hook()

    <?php
    function foo() {
        echo 'foo';
    }
    uopz_set_hook('foo', function () {echo 'bar';});
    var_dump(uopz_get_hook('foo'));
    ?>

O exemplo acima produzirá algo semelhante a:

    object(Closure)#2 (0) {
    }

### Veja Também

- uopz_set_hook() - Define o gancho a ser executado ao entrar em uma função ou método
- uopz_unset_hook() - Remove o gancho definido anteriormente na função ou método

# uopz_get_mock

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_mock — Obtém o mock atual para uma classe

### Descrição

function uopz_get_mock(string `$class`): mixed

Retorna o mock atual para `class`.

### Parâmetros

`class`

  O nome da classe simulada.

### Valor Retornado

Uma string contendo o nome do mock, ou um objeto, ou `null` se nenhum mock tiver sido definido.

### Exemplos

Exemplo #1 Exemplo de uopz_get_mock()

    <?php
    class A {
        public static function who() {
            echo "A";
        }
    }

    class mockA {
        public static function who() {
            echo "mockA";
        }
    }

    uopz_set_mock(A::class, mockA::class);
    echo uopz_get_mock(A::class);
    ?>

O exemplo acima produzirá:

    mockA

### Veja Também

- uopz_set_mock() - Usa mock em vez de classe para novos objetos
- uopz_unset_mock() - Remove a definição de um mock previamente definido

# uopz_get_property

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_property — Obtém o valor da propriedade de classe ou instância

### Descrição

function uopz_get_property(string `$class`, string `$property`): mixed
function uopz_get_property(object `$instance`, string `$property`): mixed

Obtém o valor de uma propriedade de classe estática, se `class` for fornecido, ou o valor de uma propriedade de instância, se `instance` for fornecido.

### Parâmetros

`class`

  O nome da classe.

`instance`

  A instância do objeto.

`property`

  O nome da propriedade.

### Valor Retornado

Retorna o valor da propriedade de classe ou instância, ou `null` se a propriedade não estiver definida.

### Exemplos

Exemplo #1 Uso básico de uopz_get_property()

    <?php
    class Foo {
        private static $staticBar = 10;
        private $bar = 100;
    }
    $foo = new Foo;
    var_dump(uopz_get_property('Foo', 'staticBar'));
    var_dump(uopz_get_property($foo, 'bar'));
    ?>

O exemplo acima produzirá algo semelhante a:

    int(10)
    int(100)

### Veja Também

- uopz_set_property() - Define o valor da classe existente ou propriedade de instância

# uopz_get_return

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_return — Obtém um valor de retorno definido anteriormente para uma função

### Descrição

function uopz_get_return(string `$function`): mixed
function uopz_get_return(string `$class`, string `$function`): mixed

Obtém o valor de retorno da função `function` definida anteriormente por uopz_set_return().

### Parâmetros

`class`

  O nome da classe que contém a função.

`function`

  O nome da função.

### Valor Retornado

O valor de retorno ou Closure definido anteriormente.

### Exemplos

Exemplo #1 Exemplo de uopz_get_return()

    <?php
    uopz_set_return("strlen", 42);
    echo uopz_get_return("strlen");
    ?>

O exemplo acima produzirá:

    42

# uopz_get_static

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_static — Obtém as variáveis ​​estáticas do escopo da função ou método

### Descrição

function uopz_get_static(string `$class`, string `$function`): array
function uopz_get_static(string `$function`): array

Obtém as variáveis ​​estáticas do escopo da função ou método.

### Parâmetros

`class`

  O nome da classe.

`function`

  O nome da função ou do método.

### Valor Retornado

Retorna um array associativo de nomes de variáveis ​​mapeados para seus valores atuais em caso de sucesso, ou `null` se a função ou método não existir.

A partir do PHP 8.3.0, os inicializadores estáticos são computados durante o tempo de compilação, ou, se isso não for possível, somente quando a função ou método é executado pela primeira vez, caso em que o valor da variável estática é relatado como `null` antes da primeira invocação.

### Exemplos

Exemplo #1 Uso básico de uopz_get_static()

    <?php
    function foo() {
        static $bar = 'baz';
    }
    var_dump(uopz_get_static('foo'));
    ?>

O exemplo acima produzirá:

    array(1) {
      ["bar"]=>
      string(3) "baz"
    }

### Veja Também

- ReflectionFunctionAbstract::getStaticVariables() - Obtém variáveis estáticas
- uopz_set_static() - Define as variáveis ​​estáticas no escopo da função ou método

# uopz_implement

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7 < 7.1.0)

uopz_implement — Implementa uma interface em tempo de execução

### Descrição

function uopz_implement(string `$class`, string `$interface`): bool

Faz com que `class` implemente `interface`.

### Parâmetros

`class`

`interface`

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

A partir do PHP 7.4.0, uopz_implement() lança uma RuntimeException, se OPcache estiver habilitado, e a entrada de classe de `class` for imutável.

### Exemplos

Exemplo #1 Exemplo de uopz_implement()

    <?php
    interface myInterface {}

    class myClass {}

    uopz_implement(myClass::class, myInterface::class);

    var_dump(class_implements(myClass::class));
    ?>

O exemplo acima produzirá:

    array(1) {
      ["myInterface"]=>
      string(11) "myInterface"
    }

# uopz_overload

(PECL uopz 1, PECL uopz 2)

uopz_overload — Sobrecarrega um opcode da máquina virtual

Aviso

Esta função foi REMOVIDA na uopz 5.0.0 no PECL.

### Descrição

function uopz_overload(int `$opcode`, Callable `$callable`): void

Sobrecarrega o `opcode` especificado com a função definida pelo usuário.

### Parâmetros

`opcode`

  Um opcode válido, veja constantes para detalhes dos códigos suportados.

`callable`

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de uopz_overload()

    <?php
    uopz_overload(ZEND_EXIT, function(){});

    exit();
    echo "Hello World";
    ?>

O exemplo acima produzirá:

    Hello World

# uopz_redefine

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_redefine — Redefine uma constante

### Descrição

function uopz_redefine(string `$constant`, mixed `$value`): bool
function uopz_redefine(string `$class`, string `$constant`, mixed `$value`): bool

Redefine a constante `constant` para o valor em `value`.

### Parâmetros

`class`

  O nome da classe que contém a constante.

`constant`

  O nome da constante.

`value`

  O novo valor para a constante deve ser um tipo válido para uma variável constante.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de uopz_redefine()

    <?php
    define("MY", 100);

    uopz_redefine("MY", 1000);

    echo MY;
    ?>

O exemplo acima produzirá:

    1000

# uopz_rename

(PECL uopz 1, PECL uopz 2)

uopz_rename — Renomeia uma função em tempo de execução

Aviso

Esta função foi REMOVIDA na uopz 5.0.0 no PECL.

### Descrição

function uopz_rename(string `$function`, string `$rename`): void
function uopz_rename(string `$class`, string `$function`, string `$rename`): void

Renomeia a função `function` para o nome `rename`.

> Nota:

> Se ambas as funções existirem, isso efetivamente troca seus nomes.

### Parâmetros

`class`

  O nome da classe que contém a função.

`function`

  O nome de uma função existente

`rename`

  O novo nome da função

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de uopz_rename()

    <?php
    uopz_rename("strlen", "original_strlen");

    echo original_strlen("Hello World");
    ?>

O exemplo acima produzirá:

    11

Exemplo #2 Exemplo de uopz_rename() com uma classe

    <?php
    class My {
        public function strlen($arg) {
            return strlen($arg);
        }
    }

    uopz_rename(My::class, "strlen", "original_strlen");

    echo My::original_strlen("Hello World");
    ?>

O exemplo acima produzirá:

    11

# uopz_restore

(PECL uopz 1 >= 1.0.3, PECL uopz 2)

uopz_restore — Restaura uma função a partir de um backup

Aviso

Esta função foi REMOVIDA na uopz 5.0.0 no PECL.

### Descrição

function uopz_restore(string `$function`): void
function uopz_restore(string `$class`, string `$function`): void

Restaura uma função a partir de um backup.

### Parâmetros

`class`

  O nome da classe que contém a função a ser restaurada.

`function`

  O nome da função.

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de uopz_restore()

    <?php
    uopz_backup("fgets");
    uopz_function("fgets", function(){
        return true;
    });
    var_dump(fgets());
    uopz_restore('fgets');
    fgets();
    ?>

O exemplo acima produzirá algo semelhante a:

    Warning: fgets() expects at least 1 parameter, 0 given in /path/to/script.php on line 8

# uopz_set_hook

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_hook — Define o gancho a ser executado ao entrar em uma função ou método

### Descrição

function uopz_set_hook(string `$function`, Closure `$hook`): bool
function uopz_set_hook(string `$class`, string `$function`, Closure `$hook`): bool

Define o gancho a ser executado ao entrar em uma função ou método.

### Parâmetros

`class`

  O nome da classe.

`function`

  O nome da função ou do método.

`hook`

  Um Closure ser executado ao entrar na função ou método.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Uso básico de uopz_set_hook()

    <?php
    function foo() {
        echo 'foo';
    }
    uopz_set_hook('foo', function () {echo 'bar';});
    foo();
    ?>

O exemplo acima produzirá:

    barfoo

### Veja Também

- uopz_get_hook() - Obtém o gancho previamente definido na função ou método
- uopz_unset_hook() - Remove o gancho definido anteriormente na função ou método

# uopz_set_mock

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_mock — Usa mock em vez de classe para novos objetos

### Descrição

function uopz_set_mock(string `$class`, mixed `$mock`): void

Se `mock` for uma string contendo o nome de uma classe, ela será instanciada em vez de `class`. `mock` também pode ser um objeto.

> Nota:

> Somente o acesso dinâmico a propriedades e métodos utilizará o objeto `mock`. O acesso estático ainda utiliza a classe original do parâmetro `class`. Veja o exemplo abaixo.

### Parâmetros

`class`

  O nome da classe a ter o mock usado.

`mock`

  O mock a ser usado é uma string contendo o nome da classe a ser usada ou de um objeto. Se uma string for passada, ela deve ser o nome completo da classe. É recomendado usar a constante mágica `::class` neste caso.

### Valor Retornado

Nenhum valor é retornado.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL uopz 6.0.0 | Esta função não suporta mais o mock de membros estáticos. uopz_redefine() e uopz_set_return(), ou Componere podem ser usados ​​em seu lugar.

### Exemplos

Exemplo #1 Exemplo de uopz_set_mock()

    <?php
    class A {
        public function who() {
            echo "A";
        }
    }

    class mockA {
        public function who() {
            echo "mockA";
        }
    }

    uopz_set_mock(A::class, mockA::class);
    (new A)->who();
    ?>

O exemplo acima produzirá:

    mockA

Exemplo #2 Exemplo de uopz_set_mock()

    <?php
    class A {
        public function who() {
            echo "A";
        }
    }

    uopz_set_mock(A::class, new class {
                                public function who() {
                                    echo "mockA";
                                }
                            });
    (new A)->who();
    ?>

O exemplo acima produzirá:

    mockA

Exemplo #3 uopz_set_mock() e membros estáticos

A partir do uopz 6.0.0, o mock de membros estáticos não é mais suportada.

    <?php
    class A {
        const CON = 'A';
        public static function who() {
            echo "A";
        }
    }

    uopz_set_mock(A::class, new class {
                                const CON = 'mockA';
                                public static function who() {
                                    echo "mockA";
                                }
                            });
    echo A::CON, PHP_EOL;
    A::who();
    ?>

O exemplo acima produzirá:

    A
    A

Saída do exemplo acima no uopz 5:

    mockA
    mockA

### Veja Também

- uopz_get_mock() - Obtém o mock atual para uma classe
- uopz_unset_mock() - Remove a definição de um mock previamente definido

# uopz_set_property

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_property — Define o valor da classe existente ou propriedade de instância

### Descrição

function uopz_set_property(string `$class`, string `$property`, mixed `$value`): void
function uopz_set_property(object `$instance`, string `$property`, mixed `$value`): void

Define o valor de uma propriedade de classe estática existente, se `class` for fornecido, ou o valor de uma propriedade de instância (independentemente de a propriedade de instância já existir), se `instance` for fornecido.

### Parâmetros

`class`

  O nome da classe.

`instance`

  A instância do objeto.

`property`

  O nome da propriedade.

`value`

  O valor a ser atribuído à propriedade.

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Uso básico de uopz_set_property()

    <?php
    class Foo {
       private static $staticBar;
       private $bar;
       public static function testStaticBar() {
          return self::$staticBar;
       }
       public function testBar() {
          return $this->bar;
       }
    }
    $foo = new Foo;
    uopz_set_property('Foo', 'staticBar', 10);
    uopz_set_property($foo, 'bar', 100);
    var_dump(Foo::testStaticBar());
    var_dump($foo->testBar());
    ?>

O exemplo acima produzirá:

    int(10)

### Veja Também

- uopz_get_property() - Obtém o valor da propriedade de classe ou instância

# uopz_set_return

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_return — Fornece um valor de retorno para uma função existente

### Descrição

function uopz_set_return(string `$function`, mixed `$value`, bool `$execute` = `false`): bool
function uopz_set_return(
string `$class`,
string `$function`,
mixed `$value`,
bool `$execute` = `false`
): bool

Define o valor de retorno de `function` como `value`. Se `value` for um Closure e `execute` estiver definido, o Closure será executado no lugar da função original. É possível chamar a função original a partir do Closure.

> Nota:

> Esta função substitui uopz_rename().

### Parâmetros

`class`

  O nome da classe que contém a função.

`function`

  O nome de uma função existente.

`value`

  O valor que a função deve retornar. Se um Closure for fornecido e o sinalizador de execução estiver definido, o Closure será executado no lugar da função original.

`execute`

  Se for igual a true e um Closure tiver sido fornecido como valor, o Closure será executado no lugar da função original.

### Valor Retornado

True se for bem-sucedido, false caso contrário.

### Exemplos

Exemplo #1 Exemplo de uopz_set_return()

    <?php
    uopz_set_return("strlen", 42);
    echo strlen("Banana");
    ?>

O exemplo acima produzirá:

    42

Exemplo #2 Exemplo de uopz_set_return()

    <?php
    uopz_set_return("strlen", function($str) { return strlen($str) * 2; }, true );
    echo strlen("Banana");
    ?>

O exemplo acima produzirá:

    12

Exemplo #3 Exemplo de uopz_set_return() com uma classe

    <?php
    class My {
        public static function strlen($arg) {
            return strlen($arg);
        }
    }
    uopz_set_return(My::class, "strlen", function($str) { return strlen($str) * 2; }, true );
    echo My::strlen("Banana");
    ?>

O exemplo acima produzirá:

    12

# uopz_set_static

(PECL uopz 5, PECL uopz , PECL uopz 7)

uopz_set_static — Define as variáveis ​​estáticas no escopo da função ou método

### Descrição

function uopz_set_static(string `$function`, array `$static`): void
function uopz_set_static(string `$class`, string `$function`, array `$static`): void

Define as variáveis ​​estáticas no escopo da função ou método.

### Parâmetros

`class`

  O nome da classe.

`function`

  O nome da função ou do método.

`static`

  O array associativo de nomes de variáveis ​​mapeados para seus valores.

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Uso básico de uopz_set_static()

    <?php
    function foo() {
        static $bar = 'baz';
        var_dump($bar);
    }
    uopz_set_static('foo', ['bar' => 'qux']);
    foo();
    ?>

O exemplo acima produzirá:

    string(3) "qux"

### Veja Também

- uopz_get_static() - Obtém as variáveis ​​estáticas do escopo da função ou método

# uopz_undefine

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_undefine — Indefine uma constante

### Descrição

function uopz_undefine(string `$constant`): bool
function uopz_undefine(string `$class`, string `$constant`): bool

Remove a constante em tempo de execução

### Parâmetros

`class`

  O nome da classe que contém `constant`.

`constant`

  O nome de uma constante existente.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de uopz_undefine()

    <?php
    define("MY", true);

    uopz_undefine("MY");

    var_dump(defined("MY"));
    ?>

O exemplo acima produzirá:

    bool(false)

# uopz_unset_hook

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_unset_hook — Remove o gancho definido anteriormente na função ou método

### Descrição

function uopz_unset_hook(string `$function`): bool
function uopz_unset_hook(string `$class`, string `$function`): bool

Remove o gancho definido anteriormente na função ou método.

### Parâmetros

`class`

  O nome da classe.

`function`

  O nome da função ou do método.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Uso básico de uopz_unset_hook()

    <?php
    function foo() {
        echo 'foo';
    }
    uopz_set_hook('foo', function () {echo 'bar';});
    foo();
    echo PHP_EOL;
    uopz_unset_hook('foo');
    foo();
    ?>

O exemplo acima produzirá:

    barfoo
    foo

### Veja Também

- uopz_set_hook() - Define o gancho a ser executado ao entrar em uma função ou método
- uopz_get_hook() - Obtém o gancho previamente definido na função ou método

# uopz_unset_mock

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_unset_mock — Remove a definição de um mock previamente definido

### Descrição

function uopz_unset_mock(string `$class`): void

Remove a definição de um mock previamente definido para a classe em `class`.

### Parâmetros

`class`

  O nome da classe com mock.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

Uma RuntimeException é lançada se nenhum mock foi definido anteriormente para `class`.

### Exemplos

Exemplo #1 Exemplo de uopz_unset_mock()

    <?php
    class A {
        public static function who() {
            echo "A";
        }
    }

    class mockA {
        public static function who() {
            echo "mockA";
        }
    }

    uopz_set_mock(A::class, mockA::class);
    uopz_unset_mock(A::class);
    A::who();
    ?>

O exemplo acima produzirá:

    A

### Veja Também

- uopz_set_mock() - Usa mock em vez de classe para novos objetos
- uopz_get_mock() - Obtém o mock atual para uma classe

# uopz_unset_return

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_unset_return — Desfaz um valor de retorno previamente definido para uma função

### Descrição

function uopz_unset_return(string `$function`): bool
function uopz_unset_return(string `$class`, string `$function`): bool

Desfaz o valor de retorno da função `function` definida anteriormente por uopz_set_return().

### Parâmetros

`class`

  O nome da classe que contém a função.

`function`

  O nome da função

### Valor Retornado

True em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de uopz_unset_return()

    <?php
    uopz_set_return("strlen", 42);
    $len = strlen("Banana");
    uopz_unset_return("strlen");
    echo $len + strlen("Banana");
    ?>

O exemplo acima produzirá:

    48

## Índice

- uopz_add_function — Adiciona função ou método inexistente
- uopz_allow_exit — Permite o controle sobre o código de operação de saída desabilitado
- uopz_backup — Faz backup de uma função
- uopz_compose — Compõe uma classe
- uopz_copy — Copia uma função
- uopz_del_function — Exclui função ou método adicionado anteriormente
- uopz_delete — Exclui uma função
- uopz_extend — Estende uma classe em tempo de execução
- uopz_flags — Obtém ou define sinalizadores em função ou classe
- uopz_function — Cria uma função em tempo de execução
- uopz_get_exit_status — Recupera o último status de saída definido
- uopz_get_hook — Obtém o gancho previamente definido na função ou método
- uopz_get_mock — Obtém o mock atual para uma classe
- uopz_get_property — Obtém o valor da propriedade de classe ou instância
- uopz_get_return — Obtém um valor de retorno definido anteriormente para uma função
- uopz_get_static — Obtém as variáveis ​​estáticas do escopo da função ou método
- uopz_implement — Implementa uma interface em tempo de execução
- uopz_overload — Sobrecarrega um opcode da máquina virtual
- uopz_redefine — Redefine uma constante
- uopz_rename — Renomeia uma função em tempo de execução
- uopz_restore — Restaura uma função a partir de um backup
- uopz_set_hook — Define o gancho a ser executado ao entrar em uma função ou método
- uopz_set_mock — Usa mock em vez de classe para novos objetos
- uopz_set_property — Define o valor da classe existente ou propriedade de instância
- uopz_set_return — Fornece um valor de retorno para uma função existente
- uopz_set_static — Define as variáveis ​​estáticas no escopo da função ou método
- uopz_undefine — Indefine uma constante
- uopz_unset_hook — Remove o gancho definido anteriormente na função ou método
- uopz_unset_mock — Remove a definição de um mock previamente definido
- uopz_unset_return — Desfaz um valor de retorno previamente definido para uma função

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
- Constantes predefinidas
- Funções de Uopz
  - uopz_add_function — Adiciona função ou método inexistente
  - uopz_allow_exit — Permite o controle sobre o código de operação de saída desabilitado
  - uopz_backup — Faz backup de uma função
  - uopz_compose — Compõe uma classe
  - uopz_copy — Copia uma função
  - uopz_del_function — Exclui função ou método adicionado anteriormente
  - uopz_delete — Exclui uma função
  - uopz_extend — Estende uma classe em tempo de execução
  - uopz_flags — Obtém ou define sinalizadores em função ou classe
  - uopz_function — Cria uma função em tempo de execução
  - uopz_get_exit_status — Recupera o último status de saída definido
  - uopz_get_hook — Obtém o gancho previamente definido na função ou método
  - uopz_get_mock — Obtém o mock atual para uma classe
  - uopz_get_property — Obtém o valor da propriedade de classe ou instância
  - uopz_get_return — Obtém um valor de retorno definido anteriormente para uma função
  - uopz_get_static — Obtém as variáveis ​​estáticas do escopo da função ou método
  - uopz_implement — Implementa uma interface em tempo de execução
  - uopz_overload — Sobrecarrega um opcode da máquina virtual
  - uopz_redefine — Redefine uma constante
  - uopz_rename — Renomeia uma função em tempo de execução
  - uopz_restore — Restaura uma função a partir de um backup
  - uopz_set_hook — Define o gancho a ser executado ao entrar em uma função ou método
  - uopz_set_mock — Usa mock em vez de classe para novos objetos
  - uopz_set_property — Define o valor da classe existente ou propriedade de instância
  - uopz_set_return — Fornece um valor de retorno para uma função existente
  - uopz_set_static — Define as variáveis ​​estáticas no escopo da função ou método
  - uopz_undefine — Indefine uma constante
  - uopz_unset_hook — Remove o gancho definido anteriormente na função ou método
  - uopz_unset_mock — Remove a definição de um mock previamente definido
  - uopz_unset_return — Desfaz um valor de retorno previamente definido para uma função

# Cache do Windows para PHP

# Introdução

A Extensão de Cache do Windows para PHP é um acelerador PHP usado para aumentar a velocidade de aplicativos PHP em execução no Windows e no Windows Server. Uma vez que a Extensão de Cache do Windows para PHP é habilitada e carregada pelo mecanismo PHP, os aplicativos PHP podem aproveitar a funcionalidade sem nenhuma modificação no código.

A Extensão de Cache do Windows inclui 5 tipos diferentes de cache. A seguir, descrevemos a finalidade de cada tipo de cache e os benefícios que ele oferece.

- Cache de Opcode PHP - PHP é um mecanismo de processamento de scripts que lê um fluxo de entrada de dados que contém texto e/ou instruções PHP e produz outro fluxo de dados, mais comumente no formato HTML. Isso significa que, em um servidor web, o mecanismo PHP lê, analisa, compila e executa um script PHP cada vez que ele é solicitado por um cliente web. As operações de leitura, análise e compilação colocam carga adicional na CPU e no sistema de arquivos do servidor web e, portanto, afetam o desempenho geral de uma aplicação web PHP. O cache de bytecode (opcode) do PHP é usado para armazenar o bytecode do script compilado na memória compartilhada, para que ele possa ser reutilizado pelo mecanismo PHP em execuções subsequentes do mesmo script.

  O suporte para cache de opcode foi removido no `Wincache 2.0.0`. Todos os usuários que desejam ter um opcache devem usar a extensão OPcache incluída no PHP.

- Cache de Arquivos - Mesmo com o cache de opcode PHP habilitado, o mecanismo PHP precisa acessar os arquivos de script em um sistema de arquivos. Quando scripts PHP são armazenados em um compartilhamento de arquivos UNC remoto, as operações de arquivo apresentam uma sobrecarga significativa de desempenho. A Extensão de Cache do Windows para PHP inclui um cache de arquivos que é usado para armazenar o conteúdo dos arquivos de script PHP na memória compartilhada, o que reduz a quantidade de operações do sistema de arquivos realizadas pelo mecanismo PHP.

- Cache de Resolução de Caminho de Arquivo - Scripts PHP frequentemente incluem ou operam com arquivos usando caminhos de arquivo relativos. Cada caminho de arquivo precisa ser normalizado para um caminho de arquivo absoluto pelo mecanismo PHP. Quando uma aplicação PHP usa muitos arquivos PHP e os acessa por caminhos relativos, a operação de resolução dos caminhos pode impactar negativamente o desempenho da aplicação. A Extensão de Cache do Windows para PHP fornece um cache de Resolução de Caminho de Arquivo, que é usado para armazenar os mapeamentos entre caminhos de arquivo relativos e absolutos, reduzindo assim o número de resoluções de caminho que o mecanismo PHP precisa executar.

- Cache do Usuário (disponível desde a versão 1.1.0) - Scripts PHP podem aproveitar o cache de memória compartilhada usando as APIs de cache do usuário. Objetos e variáveis ​​PHP podem ser armazenados no cache do usuário e reutilizados em requisições subsequentes. Isso pode ser usado para melhorar o desempenho de scripts PHP e para compartilhar os dados entre vários processos PHP.

- Manipulador de Sessão (disponível desde a versão 1.1.0) - O manipulador de sessão do WinCache pode ser usado para armazenar os dados da sessão PHP no cache de memória compartilhada. Isso evita operações do sistema de arquivos para leitura e gravação de dados da sessão, o que melhora o desempenho quando uma grande quantidade de dados é armazenada na sessão PHP.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução
- Script de estatísticas do WinCache
- Manipulador de Sessão WinCache
- Redirecionamentos de funções do WinCache

## Dependências

Atualmente, a extensão é suportada apenas nas seguintes configurações:

Sistemas Operacionais Windows:

- Windows XP SP3 com IIS 5.1 e » extensão FastCGI
- Windows Server 2003 com IIS 6.0 e » extensão FastCGI
- Windows Vista SP1 com IIS 7.0 e módulo FastCGI
- Windows Server 2008 com IIS 7.0 e módulo FastCGI
- Windows 7 com IIS 7.5 e módulo FastCGI
- Windows Server 2008 R2 com IIS 7.5 e módulo FastCGI

PHP:

- PHP 5.2.X, construção NTS (não seguro para threads)
- PHP 5.3 X86, construção VC9 NTS (não seguro para threads)

> Nota: A extensão WinCache só pode ser usada quando o IIS estiver configurado para executar PHP via FastCGI.

## Instalação

Esta extensão » PECL não é distribuída com o PHP.

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/wincache.

Existem dois pacotes para esta extensão: um pacote é para as versões 5.2.X do PHP, e o outro pacote é para o PHP 5.3.X. Selecione o pacote apropriado para a versão do PHP em uso.

Para instalar e habilitar a extensão, siga estas etapas:

1. Descomprima o pacote em algum local temporário.

2. Copie o arquivo php_wincache.dll para a pasta de extensões do PHP. Normalmente, essa pasta é chamada de "ext" e está localizada na mesma pasta com todos os arquivos binários do PHP. Por exemplo: C:\Arquivos de Programas\PHP\ext.

3. Usando um editor de texto, abra o arquivo php.ini, que geralmente está localizado na mesma pasta onde estão todos os arquivos binários do PHP. Por exemplo: C:\Arquivos de Programas\PHP\php.ini.

4. Adicione a seguinte linha ao final do arquivo php.ini: `extension = php_wincache.dll`.

5. Salve e feche o arquivo php.ini.

6. Recicle os Pools de Aplicativos do IIS para PHP para obter as alterações de configuração. Para verificar se a extensão foi habilitada, crie um arquivo chamado phpinfo.php com um código PHP que chama a função phpinfo.

7. Salve o arquivo phpinfo.php na pasta raiz de um site IIS que utilize PHP, abra um navegador e faça uma solicitação para http://localhost/phpinfo.php. Procure na página web retornada por uma seção chamada `wincache`. Se a extensão estiver habilitada, a saída phpinfo listará as configurações fornecidas pelo WinCache.

> Nota: Não se esqueça de remover o arquivo phpinfo.php da pasta raiz do site após verificar se a extensão foi habilitada.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

A tabela a seguir lista e explica as configurações fornecidas pela extensão WinCache:

Opções de configuração do WinCache
Nome | Padrão | Mínimo | Máximo | Modificável | Registro de Alterações
--- | --- | --- | --- | --- | ---
wincache.fcenabled | "1" | "0" | "1" | `INI_ALL` | Disponível a partir do WinCache 1.0.0
wincache.fcenabledfilter | "NULL" | "NULL" | "NULL" | `INI_SYSTEM` | Disponível a partir do WinCache 1.0.0
wincache.fcachesize | "24" | "5" | "255" | `INI_SYSTEM` | Disponível a partir do WinCache 1.0.0
wincache.fcndetect | "1" | "0" | "1" | `INI_SYSTEM` | Disponível a partir do WinCache 1.1.0
wincache.maxfilesize | "256" | "10" | "2048" | `INI_SYSTEM` | Disponível a partir do WinCache 1.0.0
wincache.ocenabled | "1" | "0" | "1" | `INI_ALL` | Disponível a partir do WinCache 1.0.0. Removida a partir do 2.0.0.0
wincache.ocenabledfilter | "NULL" | "NULL" | "NULL" | `INI_SYSTEM` | Disponível a partir do WinCache 1.0.0. Removida a partir do 2.0.0.0
wincache.ocachesize | "96" | "15" | "255" | `INI_SYSTEM` | Disponível a partir do WinCache 1.0.0. Removida a partir do 2.0.0.0
wincache.filecount | "4096" | "1024" | "16384" | `INI_SYSTEM` | Disponível a partir do WinCache 1.0.0
wincache.chkinterval | "30" | "0" | "300" | `INI_SYSTEM` | Disponível a partir do WinCache 1.0.0
wincache.ttlmax | "1200" | "0" | "7200" | `INI_SYSTEM` | Disponível a partir do WinCache 1.0.0
wincache.enablecli | 0 | 0 | 1 | `INI_SYSTEM` | Disponível a partir do WinCache 1.0.0
wincache.ignorelist | NULL | NULL | NULL | `INI_ALL` | Disponível a partir do WinCache 1.0.0
wincache.namesalt | NULL | NULL | NULL | `INI_SYSTEM` | Disponível a partir do WinCache 1.0.0
wincache.ucenabled | 1 | 0 | 1 | `INI_SYSTEM` | Disponível a partir do WinCache 1.1.0
wincache.ucachesize | 8 | 5 | 85 | `INI_SYSTEM` | Disponível a partir do WinCache 1.1.0
wincache.scachesize | 8 | 5 | 85 | `INI_SYSTEM` | Disponível a partir do WinCache 1.1.0
wincache.rerouteini | NULL | NULL | NULL | `INI_SYSTEM` | Disponível a partir do WinCache 1.2.0. Removida a partir do 1.3.7
wincache.reroute_enabled | 1 | 0 | 1 | `INI_SYSTEM`|`INI_PERDIR` | Disponível a partir do WinCache 1.3.7
wincache.srwlocks | 1 | 0 | 1 | `INI_SYSTEM` | Disponível a partir do WinCache 1.3.6.3. Removida a partir do 2.0.0.0
wincache.filemapdir | NULL | NULL | NULL | `INI_SYSTEM` | Disponível a partir do WinCache 1.3.7.4

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`wincache.fcenabled` bool
  Habilita ou desabilita a funcionalidade de cache de arquivos.
`wincache.fcenabledfilter` string
  Define uma lista separada por vírgulas de identificadores de sites do IIS onde o cache de arquivos deve ser habilitado ou desabilitado. Esta configuração funciona em conjunto com `wincache.fcenabled`: se `wincache.fcenabled` for definido como 1, os sites listados em `wincache.fcenabledfilter` terão o cache de arquivos desativado; se `wincache.fcenabled` for definido como 0, os sites listados em `wincache.fcenabledfilter` terão o cache de arquivos ativado.
`wincache.fcachesize` int
  Define o tamanho máximo de memória (em megabytes) alocado para o cache de arquivos. Se o tamanho total de todos os arquivos em cache exceder o valor especificado nesta configuração, a maioria dos arquivos obsoletos será removida do cache de arquivos.
`wincache.fcndetect` bool
  Habilita ou desabilita a funcionalidade de detecção de notificação de alteração de arquivo. Se a notificação de alteração de arquivo for suportada, ela será usada para atualizar o opcode e as entradas de cache de arquivos assim que os arquivos correspondentes forem modificados em um sistema de arquivos. Se a notificação de alteração de arquivo não for suportada, por exemplo, ao usar compartilhamentos de arquivos de rede, o wincache verificará as alterações de arquivo em intervalos regulares especificados por `wincache.chkinterval`.
`wincache.maxfilesize` int
  Define o tamanho máximo permitido (em quilobytes) para que um único arquivo seja armazenado em cache. Se o tamanho de um arquivo exceder o valor especificado, ele não será armazenado em cache. Esta configuração se aplica apenas ao cache de arquivos.
`wincache.ocenabled` bool
  Aviso

  Esta opção foi REMOVIDA a partir do 2.0.0.0

  Habilita ou desabilita a funcionalidade de cache do opcode
`wincache.ocenabledfilter` string
  Aviso

  Esta opção foi REMOVIDA a partir do 2.0.0.0

  Define uma lista separada por vírgulas de identificadores de sites do IIS onde o cache de opcode deve ser habilitado ou desabilitado. Esta configuração funciona em conjunto com `wincache.ocenabled`: se `wincache.ocenabled` for definido como 1, os sites listados no `wincache.ocenabledfilter` terão o cache de opcode desativado; se `wincache.ocenabled` for definido como 0, os sites listados no `wincache.ocenabledfilter` terão o cache de opcode ativado.
`wincache.ocachesize` int
  Aviso

  Esta opção foi REMOVIDA a partir do 2.0.0.0

  Define o tamanho máximo de memória (em megabytes) alocado para o cache do opcode. Se o tamanho do opcode armazenado em cache exceder o valor especificado, a maior parte do opcode obsoleto será removida do cache. Observe que o tamanho do cache do opcode deve ser pelo menos 3 vezes maior que o tamanho do cache do arquivo. Caso contrário, o tamanho do cache do opcode será aumentado automaticamente.
`wincache.filecount` int
  Define quantos arquivos devem ser armazenados em cache pela extensão, para que o tamanho de memória apropriado seja alocado na inicialização. Se o número de arquivos exceder o valor especificado, o WinCache realocará mais memória conforme necessário.
`wincache.chkinterval` int
  Define a frequência (em segundos) em que a extensão verifica se há alterações no arquivo para atualizar o cache. Definir como 0 desabilitará a atualização do cache. As alterações no arquivo não serão refletidas no cache, a menos que a entrada de cache para esse arquivo seja removida pelo scavenger ou o pool de aplicativos do IIS seja reciclado ou a função wincache_refresh_if_changed seja chamada.
`wincache.ttlmax` int
  Define o tempo máximo de vida (em segundos) para uma entrada em cache sem ser utilizada. Definir como 0 desabilitará a limpeza de cache, de forma que as entradas em cache nunca serão removidas do cache durante o tempo de vida do processo de trabalho do IIS.
`wincache.enablecli` bool
  Define se o cache está habilitado quando o PHP está sendo executado no modo de linha de comando (CLI).
`wincache.ignorelist` string

  Define uma lista de arquivos que não devem ser armazenados em cache pela extensão. A lista de arquivos é especificada usando apenas nomes de arquivos, separados pelo símbolo de barra vertical - "|".

  Exemplo #1 Exemplo de `wincache.ignorelist`

      wincache.ignorelist = "index.php|misc.php|admin.php"

`wincache.namesalt` string
  Define uma string que será usada ao nomear a extensão de objetos específicos armazenados na memória compartilhada. Isso é usado para evitar conflitos que podem ser causados ​​se outros aplicativos dentro de um processo de trabalho do IIS tentarem acessar a memória compartilhada. O comprimento da string namesalt não pode exceder 8 caracteres.
`wincache.ucenabled` bool
  Habilita ou desabilita a funcionalidade de cache do usuário.
`wincache.ucachesize` int
  Define o tamanho máximo de memória em megabytes alocado para o cache do usuário. Se o tamanho total das variáveis ​​armazenadas no cache do usuário exceder o valor especificado, as variáveis ​​mais obsoletas serão removidas do cache.
`wincache.scachesize` int
  Define o tamanho máximo de memória em megabytes alocado para o cache de sessão. Se o tamanho total dos dados armazenados no cache de sessão exceder o valor especificado, os dados mais obsoletos serão removidos do cache.
`wincache.rerouteini` string
  Aviso

  Esta opção foi REMOVIDA a partir do 1.3.7. Veja `wincache.reroute_enabled` para funcionalidade similar a partir do 1.3.7.

  Especifica um caminho absoluto ou relativo para o arquivo reroute.ini que contém a lista de funções PHP cuja implementação deve ser substituída pelos equivalentes da função WinCache. Se um caminho relativo for especificado então, presume-se que seja relativo à localização do arquivo php-cgi.exe.
`wincache.reroute_enabled` bool
  Habilita ou desabilita o redirecionamento de determinadas funções de E/S de arquivo por meio do cache de arquivo.
`wincache.srwlocks` bool
  Aviso

  Esta opção foi REMOVIDA a partir do 2.0.0.0

  Habilita ou desabilita o uso de bloqueios compartilhados de leitor/gravador. Desabilitar é útil na solução de condições de impasse no WinCache.
`wincache.filemapdir` string
  Especifica um caminho absoluto para um diretório onde o WinCache armazenará os arquivos temporários usados ​​para segmentos de memória compartilhada. Este diretório deve estar na máquina local e não em um sistema de arquivos em rede. Se o diretório não for especificado, o WinCache usará o arquivo de paginação do sistema Windows para todos os segmentos de memória compartilhada.

## Script de estatísticas do WinCache

O pacote de instalação do WinCache inclui um script PHP, wincache.php, que pode ser usado para obter informações de cache e estatísticas.

Se a extensão WinCache foi instalada por meio do Microsoft Web Platform Installer, este script está localizado em %SystemDrive%\Arquivos de Programas\IIS\Windows Cache for PHP\. Em uma versão de 64 bits do sistema operacional Windows Server, o script está localizado em %SystemDrive%\Arquivos de Programas (x86)\IIS\Windows Cache for PHP. Se a extensão foi instalada manualmente, o wincache.php estará localizado na mesma pasta de onde o conteúdo do pacote de instalação foi extraído.

Para usar wincache.php, copie-o para a pasta raiz de um site ou para qualquer subpasta. Para proteger o script, abra-o em qualquer editor de texto e substitua os valores das constantes USERNAME e PASSWORD. Se qualquer outra autenticação do IIS estiver habilitada no servidor, siga as instruções nos comentários:

Exemplo #1 Configuração de autenticação para wincache.php

    <?php
    /**
     * ======================== DEFINIÇÕES DE CONFIGURAÇÃO ==============================
     * Se você não quiser usar autenticação para esta página, defina USE_AUTHENTICATION como 0.
     * Se você usar autenticação, substitua a senha padrão.
     */
    define('USE_AUTHENTICATION', 1);
    define('USERNAME', 'wincache');
    define('PASSWORD', 'wincache');

    /**
     * A autenticação básica do PHP funcionará somente quando o IIS estiver configurado para suportar
     * Autenticação Anônima e nada mais. Se o IIS estiver configurado para suportar/usar
     * qualquer outro tipo de autenticação, como Básica/Negociação/Digest, etc., isso não funcionará.
     * Nesse caso, use o array abaixo para definir os nomes dos usuários em seu
     * domínio/rede/grupo de trabalho aos quais você deseja conceder acesso.
     */
    $user_allowed = array('DOMAIN\user1', 'DOMAIN\user2', 'DOMAIN\user3');

    /**
     * Se o array contiver a string 'all', todos os usuários autenticados pelo IIS
     * terão acesso à página. Descomente a linha abaixo e comente a linha acima
     * para conceder acesso a todos os usuários autenticados pelo IIS.
     */
    /* $user_allowed = array('all'); */

    /** ===================== FIM DAS DEFINIÇÕES DE CONFIGURAÇÃO ========================== */
    ?>

> Nota: Sempre proteja o script wincache.php usando a autenticação integrada ou o mecanismo de autenticação do servidor. Deixar este script desprotegido pode comprometer a segurança do seu aplicativo web e do servidor web.

## Manipulador de Sessão WinCache

O manipulador de sessão do WinCache (disponível desde o WinCache 1.1.0) pode ser usado para configurar o PHP para armazenar os dados da sessão no cache de sessão de memória compartilhada. Usar memória compartilhada em vez do armazenamento de sessão de arquivo padrão ajuda a melhorar o desempenho de aplicativos PHP que armazenam grandes quantidades de dados em objetos de sessão. O cache de sessão do WinCache utiliza memória compartilhada com suporte a arquivos, o que garante que os dados da sessão não sejam perdidos durante a reciclagem de pools de aplicativos do IIS.

Para configurar o PHP para usar o manipulador de sessão WinCache, defina a configuração php.ini session.save_handler como wincache. Por padrão, o local do arquivo temporário do Windows é usado para armazenar os dados da sessão. Para alterar o local do arquivo de sessão, use a diretiva session.save_path.

Exemplo #1 Habilitando o manipulador de sessão do WinCache

    session.save_handler = wincache
    session.save_path = C:\inetpub\temp\session\

## Redirecionamentos de funções do WinCache

NOTA: wincache.rerouteini foi removida a partir do WinCache 1.3.7.0. Ela foi substituída por redirecionamentos de função automática. Consulte: wincache.reroute_enabled.

As funções de redirecionamento do WinCache (disponíveis desde o WinCache 1.2.0, removidas desde o WinCache 1.3.7.0) podem ser usadas para substituir funções PHP integradas por suas equivalentes que são otimizadas para uma finalidade específica. A extensão WinCache inclui uma implementação otimizada para Windows de funções de arquivo PHP que podem melhorar o desempenho de aplicativos PHP nos casos em que o PHP precisa acessar arquivos em compartilhamentos de rede. A implementação otimizada é fornecida para as seguintes funções:

- file_exists
- file_get_contents
- readfile
- is_readable
- is_writable
- is_dir
- realpath
- filesize

Para configurar o WinCache para usar as funções de redirecionamento, utilize o arquivo reroute.ini incluído no pacote de instalação do WinCache. Copie este arquivo para o mesmo diretório onde o arquivo php.ini está localizado. Em seguida, adicione a configuração wincache.rerouteini em php.ini e especifique um caminho absoluto ou relativo para o arquivo reroute.ini.

Exemplo #1 Habilitando redirecionamentos de funções do WinCache

    wincache.rerouteini = C:\PHP\reroute.ini

> Nota: Se os redirecionamentos das funções do WinCache estiverem habilitados, é recomendável aumentar o tamanho do cache do arquivo WinCache. Isso pode ser feito usando a configuração wincache.fcachesize.

O arquivo reroute.ini contém os mapeamentos entre as funções nativas do PHP e seus equivalentes no WinCache. Cada linha do arquivo define um mapeamento usando a seguinte sintaxe:

`<Nome da função PHP>:[<número de parâmetros da função>]=<nome da função wincache>`

O exemplo do arquivo é mostrado abaixo. Neste exemplo, as chamadas para a função PHP file_get_contents() serão substituídas por chamadas para wincache_file_get_contents() somente se o número de parâmetros passados ​​para a função for menor ou igual a 2. Especificar o número de parâmetros é útil quando a função de substituição não lida com todos os parâmetros da função.

Exemplo #2 Conteúdo do arquivo reroute.ini

    [FunctionRerouteList]
    file_exists=wincache_file_exists
    file_get_contents:2=wincache_file_get_contents
    readfile:2=wincache_readfile
    is_readable=wincache_is_readable
    is_writable=wincache_is_writable
    is_writeable=wincache_is_writable
    is_file=wincache_is_file
    is_dir=wincache_is_dir
    realpath=wincache_realpath
    filesize=wincache_filesize

# Funções de WinCache

# wincache_fcache_fileinfo

(PECL wincache >= 1.0.0)

wincache_fcache_fileinfo — Recupera informações sobre arquivos armazenados em cache no cache de arquivos

### Descrição

function wincache_fcache_fileinfo(bool `$summaryonly` = `false`): array|false

Recupera informações sobre o conteúdo do cache de arquivos e seu uso.

### Parâmetros

`summaryonly`

  Controla se o array retornado conterá informações sobre entradas de cache individuais junto com o resumo do cache do arquivo.

### Valor Retornado

Array de metadados sobre o cache de arquivos ou `false` em caso de falha

O array retornado por esta função contém os seguintes elementos:

- `total_cache_uptime` - tempo total em segundos que o cache de arquivo esteve ativo
- `total_file_count` - número total de arquivos que estão atualmente no cache de arquivos
- `total_hit_count` - número de vezes que os arquivos foram servidos do cache de arquivos
- `total_miss_count` - número de vezes que os arquivos não foram encontrados no cache de arquivos

- `file_entries` - um array que contém informações sobre todos os arquivos em cache:

  - `file_name` - nome absoluto do arquivo em cache
  - `add_time` - tempo em segundos desde que o arquivo foi adicionado ao cache de arquivos
  - `use_time` - tempo em segundos desde que o arquivo foi acessado no cache de arquivos
  - `last_check` - tempo em segundos desde que o arquivo foi verificado para modificações
  - `hit_count` - número de vezes que o arquivo foi servido do cache
  - `file_size` - tamanho do arquivo em cache em bytes

### Exemplos

Exemplo #1 Um exemplo de wincache_fcache_fileinfo()

    <pre>
    <?php
    print_r(wincache_fcache_fileinfo());
    ?>
    </pre>

O exemplo acima produzirá:

    Array
    (   [total_cache_uptime] => 3234
        [total_file_count] => 5
        [total_hit_count] => 0
        [total_miss_count] => 1
        [file_entries] => Array
            (
                [1] => Array
                    (
                        [file_name] => c:\inetpub\wwwroot\checkcache.php
                        [add_time] => 1
                        [use_time] => 0
                        [last_check] => 1
                        [hit_count] => 1
                        [file_size] => 2435
                    )
                [2] => Array (...itera para cada arquivo em cache)
            )
    )

### Veja Também

- wincache_fcache_meminfo() - Recupera informações sobre o uso da memória cache do arquivo
- wincache_ocache_fileinfo() - Recupera informações sobre arquivos armazenados em cache no cache do opcode
- wincache_ocache_meminfo() - Recupera informações sobre o uso da memória cache do opcode
- wincache_rplist_fileinfo() - Recupera informações sobre o cache do caminho do arquivo de resolução
- wincache_rplist_meminfo() - Recupera informações sobre o uso de memória pelo cache do caminho do arquivo de resolução
- wincache_refresh_if_changed() - Atualiza as entradas de cache para os arquivos armazenados em cache
- wincache_ucache_meminfo() - Recupera informações sobre o uso da memória cache do usuário
- wincache_ucache_info() - Recupera informações sobre dados armazenados no cache do usuário
- wincache_scache_info() - Recupera informações sobre arquivos armazenados em cache no cache de sessão
- wincache_scache_meminfo() - Recupera informações sobre o uso da memória cache da sessão

# wincache_fcache_meminfo

(PECL wincache >= 1.0.0)

wincache_fcache_meminfo — Recupera informações sobre o uso da memória cache do arquivo

### Descrição

function wincache_fcache_meminfo(): array|false

Recupera informações sobre o uso de memória pelo cache de arquivos.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Array de metadados sobre o uso da memória cache do arquivo ou `false` em caso de falha

O array retornado por esta função contém os seguintes elementos:

- `memory_total` - quantidade de memória em bytes alocada para o cache de arquivos
- `memory_free` - quantidade de memória livre em bytes disponível para o cache de arquivos
- `num_used_blks` - número de blocos de memória usados ​​pelo cache de arquivo
- `num_free_blks` - número de blocos de memória livres disponíveis para o cache de arquivos
- `memory_overhead` - quantidade de memória em bytes usada para as estruturas internas do cache de arquivos

### Exemplos

Exemplo #1 Um exemplo de wincache_fcache_meminfo()

    <pre>
    <?php
    print_r(wincache_fcache_meminfo());
    ?>
    </pre>

O exemplo acima produzirá:

    Array
    (
        [memory_total] => 134217728
        [memory_free] => 131339120
        [num_used_blks] => 361
        [num_free_blks] => 3
        [memory_overhead] => 5856
    )

### Veja Também

- wincache_fcache_fileinfo() - Recupera informações sobre arquivos armazenados em cache no cache de arquivos
- wincache_ocache_fileinfo() - Recupera informações sobre arquivos armazenados em cache no cache do opcode
- wincache_ocache_meminfo() - Recupera informações sobre o uso da memória cache do opcode
- wincache_rplist_fileinfo() - Recupera informações sobre o cache do caminho do arquivo de resolução
- wincache_rplist_meminfo() - Recupera informações sobre o uso de memória pelo cache do caminho do arquivo de resolução
- wincache_refresh_if_changed() - Atualiza as entradas de cache para os arquivos armazenados em cache
- wincache_ucache_meminfo() - Recupera informações sobre o uso da memória cache do usuário
- wincache_ucache_info() - Recupera informações sobre dados armazenados no cache do usuário
- wincache_scache_info() - Recupera informações sobre arquivos armazenados em cache no cache de sessão
- wincache_scache_meminfo() - Recupera informações sobre o uso da memória cache da sessão

# wincache_lock

(PECL wincache >= 1.1.0)

wincache_lock — Adquire um bloqueio exclusivo em uma determinada chave

### Descrição

function wincache_lock(string `$key`, bool `$isglobal` = `false`): bool

Obtém um bloqueio exclusivo em uma determinada chave. A execução do script atual será bloqueada até que o bloqueio seja obtido. Uma vez obtido o bloqueio, os outros scripts que tentarem solicitá-lo usando a mesma chave serão bloqueados, até que o script atual libere o bloqueio usando wincache_unlock().

Aviso

O uso de wincache_lock() e wincache_unlock() pode causar deadlocks ao executar scripts PHP em um ambiente multiprocesso como o FastCGI. Não use essas funções a menos que tenha absoluta certeza de que precisa usá-las. Para a maioria das operações no cache do usuário, não é necessário usar essas funções.

### Parâmetros

`key`

  Nome da chave no cache para obter o bloqueio.

`isglobal`

  Controla se o escopo do bloqueio é de todo o sistema ou local. Os bloqueios locais têm como escopo o pool de aplicativos no caso do IIS FastCGI ou todos os processos PHP que possuem o mesmo identificador de processo pai.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Usando wincache_lock()

    <?php
    $fp = fopen("/tmp/lock.txt", "r+");
    if (wincache_lock(“lock_txt_lock”)) { // faz um bloqueio exclusivo
        ftruncate($fp, 0); // trunca o arquivo
        fwrite($fp, "Escreve algo aqui\n");
        wincache_unlock(“lock_txt_lock”); // libera o bloqueio
    } else {
        echo "Não foi possível obter o bloqueio!";
    }
    fclose($fp);
    ?>

### Veja Também

- wincache_unlock() - Libera um bloqueio exclusivo em uma determinada chave
- wincache_ucache_set() - Adiciona uma variável no cache do usuário e substitui uma variável se ela já existir no cache
- wincache_ucache_get() - Obtém uma variável armazenada no cache do usuário
- wincache_ucache_delete() - Exclui variáveis ​​do cache do usuário
- wincache_ucache_clear() - Exclui todo o conteúdo do cache do usuário
- wincache_ucache_exists() - Verifica se uma variável existe no cache do usuário
- wincache_ucache_meminfo() - Recupera informações sobre o uso da memória cache do usuário
- wincache_ucache_info() - Recupera informações sobre dados armazenados no cache do usuário
- wincache_scache_info() - Recupera informações sobre arquivos armazenados em cache no cache de sessão

# wincache_ocache_fileinfo

(PECL wincache >= 1.0.0)

wincache_ocache_fileinfo — Recupera informações sobre arquivos armazenados em cache no cache do opcode

### Descrição

function wincache_ocache_fileinfo(bool `$summaryonly` = `false`): array|false

Recupera informações sobre o conteúdo do cache do opcode e seu uso.

Aviso

Esta função foi REMOVIDA a partir do PHP 7.0.0.

### Parâmetros

`summaryonly`

  Controla se o array retornado conterá informações sobre entradas de cache individuais junto com o resumo do cache do opcode.

### Valor Retornado

Array de metadados sobre o cache do opcode ou `false` em caso de falha

O array retornado por esta função contém os seguintes elementos:

- `total_cache_uptime` - tempo total em segundos que o cache do opcode esteve ativo
- `total_file_count` - número total de arquivos que estão atualmente no cache do opcode
- `total_hit_count` - número de vezes que o opcode compilado foi servido do cache
- `total_miss_count` - número de vezes que o opcode compilado não foi encontrado no cache
- `is_local_cache` - true se os metadados do cache forem para uma instância de cache local, false se os metadados forem para o cache global

- `file_entries` - um array que contém informações sobre todos os arquivos em cache:

  - `file_name` - nome absoluto do arquivo em cache
  - `add_time` - tempo em segundos desde que o arquivo foi adicionado ao cache do opcode
  - `use_time` - tempo em segundos desde que o arquivo foi acessado no cache do opcode
  - `last_check` - tempo em segundos desde que o arquivo foi verificado para modificações
  - `hit_count` - número de vezes que o arquivo foi servido do cache
  - `function_count` - número de funções no arquivo em cache
  - `class_count` - número de classes no arquivo em cache

### Exemplos

Exemplo #1 Um exemplo de wincache_ocache_fileinfo()

    <pre>
    <?php
    print_r(wincache_ocache_fileinfo());
    ?>
    </pre>

O exemplo acima produzirá:

    Array
    (
        [total_cache_uptime] => 17357
        [total_file_count] => 121
        [total_hit_count] => 36562
        [total_miss_count] => 201
        [file_entries] => Array
            (
                [1] => Array
                    (
                        [file_name] => c:\inetpub\wwwroot\checkcache.php
                        [add_time] => 17356
                        [use_time] => 7
                        [last_check] => 10
                        [hit_count] => 454
                        [function_count] => 0
                        [class_count] => 1
                    )
                [2] => Array (...itera para cada arquivo em cache)
            )
    )

### Veja Também

- wincache_fcache_fileinfo() - Recupera informações sobre arquivos armazenados em cache no cache de arquivos
- wincache_fcache_meminfo() - Recupera informações sobre o uso da memória cache do arquivo
- wincache_ocache_meminfo() - Recupera informações sobre o uso da memória cache do opcode
- wincache_rplist_fileinfo() - Recupera informações sobre o cache do caminho do arquivo de resolução
- wincache_rplist_meminfo() - Recupera informações sobre o uso de memória pelo cache do caminho do arquivo de resolução
- wincache_refresh_if_changed() - Atualiza as entradas de cache para os arquivos armazenados em cache
- wincache_ucache_meminfo() - Recupera informações sobre o uso da memória cache do usuário
- wincache_ucache_info() - Recupera informações sobre dados armazenados no cache do usuário
- wincache_scache_info() - Recupera informações sobre arquivos armazenados em cache no cache de sessão
- wincache_scache_meminfo() - Recupera informações sobre o uso da memória cache da sessão

# wincache_ocache_meminfo

(PECL wincache >= 1.0.0)

wincache_ocache_meminfo — Recupera informações sobre o uso da memória cache do opcode

### Descrição

function wincache_ocache_meminfo(): array|false

Recupera informações sobre o uso de memória pelo cache de opcode.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Array de metadados sobre o uso da memória cache do opcode ou `false` em caso de falha

O array retornado por esta função contém os seguintes elementos:

- `memory_total` - quantidade de memória em bytes alocada para o cache de opcode
- `memory_free` - quantidade de memória livre em bytes disponível para o cache de opcode
- `num_used_blks` - número de blocos de memória usados ​​pelo cache de opcode
- `num_free_blks` - número de blocos de memória livres disponíveis para o cache de opcode
- `memory_overhead` - quantidade de memória em bytes usada para as estruturas internas do cache de opcode

Aviso

Esta função foi REMOVIDA a partir do PHP 7.0.0.

### Exemplos

Exemplo #1 Um exemplo de wincache_ocache_meminfo()

    <pre>
    <?php
    print_r(wincache_ocache_meminfo());
    ?>
    </pre>

O exemplo acima produzirá:

    Array
    (
        [memory_total] => 134217728
        [memory_free] => 112106972
        [num_used_blks] => 15469
        [num_free_blks] => 4
        [memory_overhead] => 247600
    )

### Veja Também

- wincache_fcache_fileinfo() - Recupera informações sobre arquivos armazenados em cache no cache de arquivos
- wincache_fcache_meminfo() - Recupera informações sobre o uso da memória cache do arquivo
- wincache_ocache_fileinfo() - Recupera informações sobre arquivos armazenados em cache no cache do opcode
- wincache_rplist_fileinfo() - Recupera informações sobre o cache do caminho do arquivo de resolução
- wincache_rplist_meminfo() - Recupera informações sobre o uso de memória pelo cache do caminho do arquivo de resolução
- wincache_refresh_if_changed() - Atualiza as entradas de cache para os arquivos armazenados em cache
- wincache_ucache_meminfo() - Recupera informações sobre o uso da memória cache do usuário
- wincache_ucache_info() - Recupera informações sobre dados armazenados no cache do usuário
- wincache_scache_info() - Recupera informações sobre arquivos armazenados em cache no cache de sessão
- wincache_scache_meminfo() - Recupera informações sobre o uso da memória cache da sessão

# wincache_refresh_if_changed

(PECL wincache >= 1.0.0)

wincache_refresh_if_changed — Atualiza as entradas de cache para os arquivos armazenados em cache

### Descrição

function wincache_refresh_if_changed(array `$files` = NULL): bool

Atualiza as entradas de cache dos arquivos cujos nomes foram passados ​​no argumento de entrada. Se nenhum argumento for especificado, atualiza todas as entradas no cache.

### Parâmetros

`files`

  Um array de nomes de arquivos para arquivos que precisam ser atualizados. É possível usar caminhos de arquivo absolutos ou relativos.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

O WinCache realiza verificações regulares nos arquivos em cache para garantir que, se algum arquivo for alterado, a entrada correspondente no cache seja atualizada. Por padrão, essa verificação é realizada a cada 30 segundos. Se, por exemplo, um script PHP atualizar outro script PHP onde as configurações do aplicativo estão armazenadas, pode acontecer que, após as configurações terem sido salvas em um arquivo, o aplicativo ainda esteja usando as configurações antigas por algum tempo até que o cache seja atualizado. Nesses casos, pode ser preferível atualizar o cache logo após a alteração do arquivo. O exemplo a seguir mostra como isso pode ser feito.

Exemplo #1 Um exemplo de wincache_refresh_if_changed()

    <?php
    $filename = 'C:\inetpub\wwwroot\config.php';
    $handle = fopen($filename, 'w+');
    if ($handle === FALSE) die('Falha ao abrir o arquivo '.$filename.' para gravação');
    fwrite($handle, '<?php $setting=something; ?>');
    fclose($handle);
    wincache_refresh_if_changed(array($filename));
    ?>

### Veja Também

- wincache_fcache_fileinfo() - Recupera informações sobre arquivos armazenados em cache no cache de arquivos
- wincache_fcache_meminfo() - Recupera informações sobre o uso da memória cache do arquivo
- wincache_ocache_fileinfo() - Recupera informações sobre arquivos armazenados em cache no cache do opcode
- wincache_ocache_meminfo() - Recupera informações sobre o uso da memória cache do opcode
- wincache_rplist_fileinfo() - Recupera informações sobre o cache do caminho do arquivo de resolução
- wincache_rplist_meminfo() - Recupera informações sobre o uso de memória pelo cache do caminho do arquivo de resolução
- wincache_ucache_meminfo() - Recupera informações sobre o uso da memória cache do usuário
- wincache_ucache_info() - Recupera informações sobre dados armazenados no cache do usuário

# wincache_rplist_fileinfo

(PECL wincache >= 1.0.0)

wincache_rplist_fileinfo — Recupera informações sobre o cache do caminho do arquivo de resolução

### Descrição

function wincache_rplist_fileinfo(bool `$summaryonly` = `false`): array|false

Recupera informações sobre mapeamentos em cache entre caminhos de arquivo relativos e caminhos de arquivo absolutos correspondentes.

### Parâmetros

`summaryonly`

### Valor Retornado

Array de metadados sobre o cache do caminho do arquivo de resolução ou `false` em caso de falha

O array retornado por esta função contém os seguintes elementos:

- `total_file_count` - número total de mapeamentos de caminho de arquivo armazenados no cache

- `rplist_entries` - um array que contém informações sobre todos os caminhos de arquivos armazenados em cache:

  - `resolve_path` - caminho para um arquivo
  - `subkey_data` - caminho absoluto correspondente para um arquivo

### Exemplos

Exemplo #1 Um exemplo de wincache_rplist_fileinfo()

    <pre>
    <?php
    print_r(wincache_rplist_fileinfo());
    ?>
    </pre>

O exemplo acima produzirá:

    Array
    (
        [total_file_count] => 5
        [rplist_entries] => Array
            (
                [1] => Array
                    (
                        [resolve_path] => checkcache.php
                        [subkey_data] => c:\inetpub\wwwroot|c:\inetpub\wwwroot\checkcache.php
                    )

                [2] => Array (...itera para cada arquivo em cache)
            )
    )

### Veja Também

- wincache_fcache_meminfo() - Recupera informações sobre o uso da memória cache do arquivo
- wincache_fcache_fileinfo() - Recupera informações sobre arquivos armazenados em cache no cache de arquivos
- wincache_ocache_fileinfo() - Recupera informações sobre arquivos armazenados em cache no cache do opcode
- wincache_ocache_meminfo() - Recupera informações sobre o uso da memória cache do opcode
- wincache_rplist_meminfo() - Recupera informações sobre o uso de memória pelo cache do caminho do arquivo de resolução
- wincache_refresh_if_changed() - Atualiza as entradas de cache para os arquivos armazenados em cache
- wincache_ucache_meminfo() - Recupera informações sobre o uso da memória cache do usuário
- wincache_ucache_info() - Recupera informações sobre dados armazenados no cache do usuário
- wincache_scache_info() - Recupera informações sobre arquivos armazenados em cache no cache de sessão
- wincache_scache_meminfo() - Recupera informações sobre o uso da memória cache da sessão

# wincache_rplist_meminfo

(PECL wincache >= 1.0.0)

wincache_rplist_meminfo — Recupera informações sobre o uso de memória pelo cache do caminho do arquivo de resolução

### Descrição

function wincache_rplist_meminfo(): array|false

Recupera informações sobre o uso de memória resolvendo o cache do caminho do arquivo.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Array de metadados que descreve o uso de memória por cache de caminho de arquivo resolvido. ou `false` em caso de falha

O array retornado por esta função contém os seguintes elementos:

- `memory_total` - quantidade de memória em bytes alocada para o cache do caminho do arquivo de resolução
- `memory_free` - quantidade de memória livre em bytes disponível para o cache do caminho do arquivo de resolução
- `num_used_blks` - número de blocos de memória usados ​​pelo cache do caminho do arquivo de resolução
- `num_free_blks` - número de blocos de memória livres disponíveis para o cache do caminho do arquivo de resolução
- `memory_overhead` - quantidade de memória em bytes usada para as estruturas internas do cache do caminho do arquivo de resolução

### Exemplos

Exemplo #1 Um exemplo de wincache_rplist_meminfo()

    <pre>
    <?php
    print_r(wincache_rplist_meminfo());
    ?>
    </pre>

O exemplo acima produzirá:

    Array
    (
        [memory_total] => 9437184
        [memory_free] => 9416744
        [num_used_blks] => 23
        [num_free_blks] => 1
        [memory_overhead] => 416
    )

### Veja Também

- wincache_fcache_fileinfo() - Recupera informações sobre arquivos armazenados em cache no cache de arquivos
- wincache_fcache_meminfo() - Recupera informações sobre o uso da memória cache do arquivo
- wincache_ocache_fileinfo() - Recupera informações sobre arquivos armazenados em cache no cache do opcode
- wincache_ocache_meminfo() - Recupera informações sobre o uso da memória cache do opcode
- wincache_rplist_fileinfo() - Recupera informações sobre o cache do caminho do arquivo de resolução
- wincache_refresh_if_changed() - Atualiza as entradas de cache para os arquivos armazenados em cache
- wincache_ucache_meminfo() - Recupera informações sobre o uso da memória cache do usuário
- wincache_ucache_info() - Recupera informações sobre dados armazenados no cache do usuário
- wincache_scache_info() - Recupera informações sobre arquivos armazenados em cache no cache de sessão
- wincache_scache_meminfo() - Recupera informações sobre o uso da memória cache da sessão

# wincache_scache_info

(PECL wincache >= 1.1.0)

wincache_scache_info — Recupera informações sobre arquivos armazenados em cache no cache de sessão

### Descrição

function wincache_scache_info(bool `$summaryonly` = `false`): array|false

Recupera informações sobre o conteúdo do cache de sessão e seu uso.

### Parâmetros

`summaryonly`

  Controla se o array retornado conterá informações sobre entradas de cache individuais junto com o resumo do cache da sessão.

### Valor Retornado

Array de metadados sobre o cache de sessão ou `false` em caso de falha

O array retornado por esta função contém os seguintes elementos:

- `total_cache_uptime` - tempo total em segundos que o cache da sessão esteve ativo
- `total_item_count` - número total de elementos que estão atualmente no cache da sessão
- `is_local_cache` - true se os metadados do cache forem para uma instância de cache local, false se os metadados forem para o cache global
- `total_hit_count` - número de vezes que os dados foram servidos do cache
- `total_miss_count` - número de vezes que os dados não foram encontrados no cache

- `scache_entries` - um array que contém informações sobre todos os itens armazenados em cache:

  - `key_name` - nome da chave que é usada para armazenar os dados
  - `value_type` - tipo de valor armazenado pela chave
  - `use_time` - tempo em segundos desde que o arquivo foi acessado no cache do opcode
  - `last_check` - tempo em segundos desde que o arquivo foi verificado para modificações
  - `ttl_seconds` - tempo restante para os dados permanecerem no cache, 0 significando infinito
  - `age_seconds` - tempo decorrido desde o momento em que os dados foram adicionados ao cache
  - `hitcount` - número de vezes que os dados foram fornecidos pelo cache

### Exemplos

Exemplo #1 Um exemplo de wincache_scache_info()

    <pre>
    <?php
    print_r(wincache_scache_info());
    ?>
    </pre>

O exemplo acima produzirá:

    Array
    (
        [total_cache_uptime] => 17357
        [total_file_count] => 121
        [total_hit_count] => 36562
        [total_miss_count] => 201
        [scache_entries] => Array
            (
                [1] => Array
                    (
                        [file_name] => c:\inetpub\wwwroot\checkcache.php
                        [add_time] => 17356
                        [use_time] => 7
                        [last_check] => 10
                        [hit_count] => 454
                        [function_count] => 0
                        [class_count] => 1
                    )
                [2] => Array (...itera para cada arquivo em cache)
            )
    )

### Veja Também

- wincache_fcache_fileinfo() - Recupera informações sobre arquivos armazenados em cache no cache de arquivos
- wincache_fcache_meminfo() - Recupera informações sobre o uso da memória cache do arquivo
- wincache_ocache_meminfo() - Recupera informações sobre o uso da memória cache do opcode
- wincache_rplist_fileinfo() - Recupera informações sobre o cache do caminho do arquivo de resolução
- wincache_rplist_meminfo() - Recupera informações sobre o uso de memória pelo cache do caminho do arquivo de resolução
- wincache_refresh_if_changed() - Atualiza as entradas de cache para os arquivos armazenados em cache
- wincache_ucache_meminfo() - Recupera informações sobre o uso da memória cache do usuário
- wincache_ucache_info() - Recupera informações sobre dados armazenados no cache do usuário
- wincache_scache_meminfo() - Recupera informações sobre o uso da memória cache da sessão

# wincache_scache_meminfo

(PECL wincache >= 1.1.0)

wincache_scache_meminfo — Recupera informações sobre o uso da memória cache da sessão

### Descrição

function wincache_scache_meminfo(): array|false

Recupera informações sobre o uso de memória pelo cache de sessão.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Array de metadados sobre uso de memória cache de sessão ou `false` em caso de falha

O array retornado por esta função contém os seguintes elementos:

- `memory_total` - quantidade de memória em bytes alocada para o cache de sessão
- `memory_free` - quantidade de memória livre em bytes disponível para o cache de sessão
- `num_used_blks` - número de blocos de memória usados ​​pelo cache de sessão
- `num_free_blks` - número de blocos de memória livres disponíveis para o cache de sessão
- `memory_overhead` - quantidade de memória em bytes usada para as estruturas internas do cache de sessão

### Exemplos

Exemplo #1 Um exemplo de wincache_scache_meminfo()

    <pre>
    <?php
    print_r(wincache_scache_meminfo());
    ?>
    </pre>

O exemplo acima produzirá:

    Array
    (
        [memory_total] => 5242880
        [memory_free] => 5215056
        [num_used_blks] => 6
        [num_free_blks] => 3
        [memory_overhead] => 176
    )

### Veja Também

- wincache_fcache_fileinfo() - Recupera informações sobre arquivos armazenados em cache no cache de arquivos
- wincache_fcache_meminfo() - Recupera informações sobre o uso da memória cache do arquivo
- wincache_ocache_fileinfo() - Recupera informações sobre arquivos armazenados em cache no cache do opcode
- wincache_rplist_fileinfo() - Recupera informações sobre o cache do caminho do arquivo de resolução
- wincache_rplist_meminfo() - Recupera informações sobre o uso de memória pelo cache do caminho do arquivo de resolução
- wincache_refresh_if_changed() - Atualiza as entradas de cache para os arquivos armazenados em cache
- wincache_ucache_info() - Recupera informações sobre dados armazenados no cache do usuário
- wincache_scache_info() - Recupera informações sobre arquivos armazenados em cache no cache de sessão

# wincache_ucache_add

(PECL wincache >= 1.1.0)

wincache_ucache_add — Adiciona uma variável no cache do usuário somente se a variável ainda não existir no cache

### Descrição

function wincache_ucache_add(string `$key`, mixed `$value`, int `$ttl` = 0): bool
function wincache_ucache_add(array `$values`, mixed `$unused` = NULL, int `$ttl` = 0): bool

Adiciona uma variável ao cache do usuário, somente se esta variável ainda não existir no cache. A variável adicionada permanece no cache do usuário, a menos que seu tempo de vida expire ou seja excluída usando as funções wincache_ucache_delete() ou wincache_ucache_clear().

### Parâmetros

`key`

  Armazene a variável usando este nome `key`. Se uma variável com a mesma chave já estiver presente, a função falhará e retornará `false`. `key` diferencia maiúsculas de minúsculas. Para substituir o valor mesmo se `key` estiver presente, use a função wincache_ucache_set() em vez disso. `key` também pode receber um array de pares nome => valor, onde os nomes serão usados ​​como chaves. Isso pode ser usado para adicionar vários valores ao cache em uma única operação, evitando assim condições de corrida.

`value`

  Valor de uma variável a ser armazenada. `Value` suporta todos os tipos de dados, exceto recursos, como identificadores de arquivo. Este parâmetro é ignorado se o primeiro argumento for um array. Uma orientação geral é passar `null` como `value` enquanto usa array como `key`. Se `value` for um objeto ou um array contendo objetos, os objetos serão serializados. Consulte __sleep() para obter detalhes sobre a serialização de objetos.

`values`

  Array associativo de chaves e valores.

`ttl`

  Tempo que a variável permanece no cache em segundos. Após o valor especificado em `ttl` ser excedido, a variável armazenada será excluída do cache. Este parâmetro assume o valor padrão de `0`, o que significa que a variável permanecerá no cache, a menos que seja explicitamente excluída usando as funções wincache_ucache_delete() ou wincache_ucache_clear().

### Valor Retornado

Se `key` for uma string, a função retornará `true` em caso de sucesso e `false` em caso de falha.

Se `key` for um array, a função retornará:

- Se todos os pares nome => valor no array puderem ser definidos, a função retornará um array vazio;
- Se todos os pares nome => valor no array não puderem ser definidos, a função retornará `false`;
- Se alguns puderem ser definidos enquanto outros não, a função retornará um array com par nome=>valor para o qual a adição falhou no cache do usuário.

### Exemplos

Exemplo #1 wincache_ucache_add() com `key` sendo uma string

    <?php
    $bar = 'BAR';
    var_dump(wincache_ucache_add('foo', $bar));
    var_dump(wincache_ucache_add('foo', $bar));
    var_dump(wincache_ucache_get('foo'));
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(false)
    string(3) "BAR"

Exemplo #2 wincache_ucache_add() com `key` sendo um array

    <?php
    $colors_array = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
    var_dump(wincache_ucache_add($colors_array));
    var_dump(wincache_ucache_add($colors_array));
    var_dump(wincache_ucache_get('Blue'));
    ?>

O exemplo acima produzirá:

    array(0) { }
    array(4) {
      ["green"]=> int(-1)
      ["Blue"]=> int(-1)
      ["yellow"]=> int(-1)
      ["cyan"]=> int(-1)
    }
    string(1) "6"

### Veja Também

- wincache_ucache_set() - Adiciona uma variável no cache do usuário e substitui uma variável se ela já existir no cache
- wincache_ucache_get() - Obtém uma variável armazenada no cache do usuário
- wincache_ucache_delete() - Exclui variáveis ​​do cache do usuário
- wincache_ucache_clear() - Exclui todo o conteúdo do cache do usuário
- wincache_ucache_exists() - Verifica se uma variável existe no cache do usuário
- wincache_ucache_meminfo() - Recupera informações sobre o uso da memória cache do usuário
- wincache_ucache_info() - Recupera informações sobre dados armazenados no cache do usuário
- __sleep()

# wincache_ucache_cas

(PECL wincache >= 1.1.0)

wincache_ucache_cas — Compara a variável com o valor antigo e atribui um novo valor a ela

### Descrição

function wincache_ucache_cas(string `$key`, int `$old_value`, int `$new_value`): bool

Compara a variável associada à chave `key` com o valor antigo em `old_value` e, se corresponder, atribui o novo valor em `new_value` a ela.

### Parâmetros

`key`

  O parâmetro `key` é usado para armazenar a variável no cache. `key` diferencia maiúsculas de minúsculas.

`old_value`

  Valor antigo da variável apontada por `key` no cache do usuário. O valor deve ser do tipo `long`, caso contrário, a função retorna `false`.

`new_value`

  Novo valor que será atribuído ao ponteiro da variável por `key` se uma correspondência for encontrada. O valor deve ser do tipo `long`, caso contrário, a função retorna `false`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Usando wincache_ucache_cas()

    <?php
    wincache_ucache_set('counter', 2922);
    var_dump(wincache_ucache_cas('counter', 2922, 1));
    var_dump(wincache_ucache_get('counter'));
    ?>

O exemplo acima produzirá:

    bool(true)
    int(1)

### Veja Também

- wincache_ucache_inc() - Incrementa o valor associado à chave
- wincache_ucache_dec() - Decrementa o valor associado à chave

# wincache_ucache_clear

(PECL wincache >= 1.1.0)

wincache_ucache_clear — Exclui todo o conteúdo do cache do usuário

### Descrição

function wincache_ucache_clear(): bool

Limpa/exclui todos os valores armazenados no cache do usuário.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Usando wincache_ucache_clear()

    <?php
    wincache_ucache_set('green', 1);
    wincache_ucache_set('red', 2);
    wincache_ucache_set('orange', 4);
    wincache_ucache_set('blue', 8);
    wincache_ucache_set('cyan', 16);
    $array1 = array('green', 'red', 'orange', 'blue', 'cyan');
    var_dump(wincache_ucache_get($array1));
    var_dump(wincache_ucache_clear());
    var_dump(wincache_ucache_get($array1));
    ?>

O exemplo acima produzirá:

    array(5) { ["green"]=> int(1)
               ["red"]=> int(2)
               ["orange"]=> int(4)
               ["blue"]=> int(8)
               ["cyan"]=> int(16) }
    bool(true)
    bool(false)

### Veja Também

- wincache_ucache_set() - Adiciona uma variável no cache do usuário e substitui uma variável se ela já existir no cache
- wincache_ucache_add() - Adiciona uma variável no cache do usuário somente se a variável ainda não existir no cache
- wincache_ucache_delete() - Exclui variáveis ​​do cache do usuário
- wincache_ucache_get() - Obtém uma variável armazenada no cache do usuário
- wincache_ucache_exists() - Verifica se uma variável existe no cache do usuário
- wincache_ucache_meminfo() - Recupera informações sobre o uso da memória cache do usuário
- wincache_ucache_info() - Recupera informações sobre dados armazenados no cache do usuário

# wincache_ucache_dec

(PECL wincache >= 1.1.0)

wincache_ucache_dec — Decrementa o valor associado à chave

### Descrição

function wincache_ucache_dec(string `$key`, int `$dec_by` = 1, bool `&$success` = ?): mixed

Decrementa o valor associado à chave `key` em 1 ou conforme especificado por `dec_by`.

### Parâmetros

`key`

  O parâmetro `key` é a chave que foi usada para armazenar a variável no cache. `key` diferencia maiúsculas de minúsculas.

`dec_by`

  O valor pelo qual a variável associada a `key` será decrementada. Se o argumento for um número de ponto flutuante, ele será truncado para o inteiro mais próximo. A variável associada a `key` deve ser do tipo `long`, caso contrário, a função falha e retorna `false`.

`success`

  Será definido como `true` em caso de sucesso e `false` em caso de falha.

### Valor Retornado

Retorna o valor decrementado em caso de sucesso e `false` em caso de falha.

### Exemplos

Exemplo #1 Usando wincache_ucache_dec()

    <?php
    wincache_ucache_set('counter', 1);
    var_dump(wincache_ucache_dec('counter', 2923, $success));
    var_dump($success);
    ?>

O exemplo acima produzirá:

    int(2922)
    bool(true)

### Veja Também

- wincache_ucache_inc() - Incrementa o valor associado à chave
- wincache_ucache_cas() - Compara a variável com o valor antigo e atribui um novo valor a ela

# wincache_ucache_delete

(PECL wincache >= 1.1.0)

wincache_ucache_delete — Exclui variáveis ​​do cache do usuário

### Descrição

function wincache_ucache_delete(mixed `$key`): bool

Exclui os elementos no cache do usuário apontados por `key`.

### Parâmetros

`key`

  O parâmetro `key` é a chave usada para armazenar a variável no cache. `key` diferencia maiúsculas de minúsculas. `key` pode ser um array de chaves.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

Se `key` for um array, a função retornará `false` se todos os elementos do array não forem excluídos do cache do usuário; caso contrário, retornará um array que consiste em todas as chaves que foram excluídas.

### Exemplos

Exemplo #1 Usando wincache_ucache_delete() com `key` sendo uma string

    <?php
    wincache_ucache_set('foo', 'bar');
    var_dump(wincache_ucache_delete('foo'));
    var_dump(wincache_ucache_exists('foo'));
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(false)

Exemplo #2 Usando wincache_ucache_delete() com `key` sendo um array

    <?php
    $array1 = array('verde' => '5', 'azul' => '6', 'amarelo' => '7', 'ciano' => '8');
    wincache_ucache_set($array1);
    $array2 = array('verde', 'azul', 'amarelo', 'ciano');
    var_dump(wincache_ucache_delete($array2));
    ?>

O exemplo acima produzirá:

    array(4) { [0]=> string(5) "verde"
               [1]=> string(4) "azul"
               [2]=> string(7) "amarelo"
               [3]=> string(5) "ciano" }

Exemplo #3 Usando wincache_ucache_delete() com `key` sendo um array onde alguns elementos não podem ser excluídos

    <?php
    $array1 = array('verde' => '5', 'azul' => '6', 'amarelo' => '7', 'ciano' => '8');
    wincache_ucache_set($array1);
    $array2 = array('laranja', 'vermelho', 'amarelo', 'ciano');
    var_dump(wincache_ucache_delete($array2));
    ?>

O exemplo acima produzirá:

    array(2) { [0]=> string(7) "amarelo"
               [1]=> string(5) "ciano" }

### Veja Também

- wincache_ucache_set() - Adiciona uma variável no cache do usuário e substitui uma variável se ela já existir no cache
- wincache_ucache_add() - Adiciona uma variável no cache do usuário somente se a variável ainda não existir no cache
- wincache_ucache_get() - Obtém uma variável armazenada no cache do usuário
- wincache_ucache_clear() - Exclui todo o conteúdo do cache do usuário
- wincache_ucache_exists() - Verifica se uma variável existe no cache do usuário
- wincache_ucache_meminfo() - Recupera informações sobre o uso da memória cache do usuário
- wincache_ucache_info() - Recupera informações sobre dados armazenados no cache do usuário

# wincache_ucache_exists

(PECL wincache >= 1.1.0)

wincache_ucache_exists — Verifica se uma variável existe no cache do usuário

### Descrição

function wincache_ucache_exists(string `$key`): bool

Verifica se uma variável com a chave `key` existe no cache do usuário ou não.

### Parâmetros

`key`

  O parâmetro `key` é a chave usada para armazenar a variável no cache. `key` diferencia maiúsculas de minúsculas.

### Valor Retornado

Retorna `true` se a variável com a chave `key` existir, caso contrário, retorna `false`.

### Exemplos

Exemplo #1 Usando wincache_ucache_exists()

    <?php
    if (!wincache_ucache_exists('green'))
        wincache_ucache_set('green', 1);
    var_dump(wincache_ucache_exists('green'));
    ?>

O exemplo acima produzirá:

    bool(true)

### Veja Também

- wincache_ucache_set() - Adiciona uma variável no cache do usuário e substitui uma variável se ela já existir no cache
- wincache_ucache_add() - Adiciona uma variável no cache do usuário somente se a variável ainda não existir no cache
- wincache_ucache_get() - Obtém uma variável armazenada no cache do usuário
- wincache_ucache_clear() - Exclui todo o conteúdo do cache do usuário
- wincache_ucache_delete() - Exclui variáveis ​​do cache do usuário
- wincache_ucache_meminfo() - Recupera informações sobre o uso da memória cache do usuário
- wincache_ucache_info() - Recupera informações sobre dados armazenados no cache do usuário

# wincache_ucache_get

(PECL wincache >= 1.1.0)

wincache_ucache_get — Obtém uma variável armazenada no cache do usuário

### Descrição

function wincache_ucache_get(mixed `$key`, bool `&$success` = ?): mixed

Obtém uma variável armazenada no cache do usuário,

### Parâmetros

`key`

  O parâmetro `key` é a chave usada para armazenar a variável no cache. `key` diferencia maiúsculas de minúsculas. `key` pode ser um array de chaves. Neste caso, o valor de retorno será um array de valores de cada elemento no array `key`. Se um objeto, ou um array contendo objetos, for retornado, os objetos serão desserializados. Consulte __wakeup() para obter detalhes sobre a desserialização de objetos.

`success`

  Será definido como `true` em caso de sucesso e `false` em caso de falha.

### Valor Retornado

Se `key` for uma string, a função retornará o valor da variável armazenada com essa chave. `success` é definido como `true` em caso de sucesso e como `false` em caso de falha.

Se `key` for um array, o parâmetro `success` será sempre definido como `true`. O array retornado (pares nome => valor) conterá apenas os pares nome => valor para os quais a operação de obtenção no cache do usuário foi bem-sucedida. Se nenhuma das chaves no array de chaves encontrar uma correspondência no cache do usuário, um array vazio será retornado.

### Exemplos

Exemplo #1 wincache_ucache_get() com `key` sendo uma string

    <?php
    wincache_ucache_add('color', 'blue');
    var_dump(wincache_ucache_get('color', $success));
    var_dump($success);
    ?>

O exemplo acima produzirá:

    string(4) "blue"
    bool(true)

Exemplo #2 wincache_ucache_get() com `key` sendo um array

    <?php
    $array1 = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
    wincache_ucache_set($array1);
    $array2 = array('green', 'Blue', 'yellow', 'cyan');
    var_dump(wincache_ucache_get($array2, $success));
    var_dump($success);
    ?>

O exemplo acima produzirá:

    array(4) { ["green"]=> string(1) "5"
               ["Blue"]=> string(1) "6"
               ["yellow"]=> string(1) "7"
               ["cyan"]=> string(1) "8" }
    bool(true)

### Veja Também

- wincache_ucache_add() - Adiciona uma variável no cache do usuário somente se a variável ainda não existir no cache
- wincache_ucache_set() - Adiciona uma variável no cache do usuário e substitui uma variável se ela já existir no cache
- wincache_ucache_delete() - Exclui variáveis ​​do cache do usuário
- wincache_ucache_clear() - Exclui todo o conteúdo do cache do usuário
- wincache_ucache_exists() - Verifica se uma variável existe no cache do usuário
- wincache_ucache_meminfo() - Recupera informações sobre o uso da memória cache do usuário
- wincache_ucache_info() - Recupera informações sobre dados armazenados no cache do usuário
- __wakeup()

# wincache_ucache_inc

(PECL wincache >= 1.1.0)

wincache_ucache_inc — Incrementa o valor associado à chave

### Descrição

function wincache_ucache_inc(string `$key`, int `$inc_by` = 1, bool `&$success` = ?): mixed

Incrementa o valor associado à chave `key` em 1 ou conforme especificado por `inc_by`.

### Parâmetros

`key`

  O parâmetro `key` é a chave usada para armazenar a variável no cache. `key` diferencia maiúsculas de minúsculas.

`inc_by`

  O valor pelo qual a variável associada a `key` será incrementada. Se o argumento for um número de ponto flutuante, ele será truncado para o inteiro mais próximo. A variável associada a `key` deve ser do tipo `long`, caso contrário, a função falha e retorna `false`.

`success`

  Será definido como `true` em caso de sucesso e `false` em caso de falha.

### Valor Retornado

Retorna o valor incrementado em caso de sucesso e `false` em caso de falha.

### Exemplos

Exemplo #1 Usando wincache_ucache_inc()

    <?php
    wincache_ucache_set('counter', 1);
    var_dump(wincache_ucache_inc('counter', 2921, $success));
    var_dump($success);
    ?>

O exemplo acima produzirá:

    int(2922)
    bool(true)

### Veja Também

- wincache_ucache_dec() - Decrementa o valor associado à chave
- wincache_ucache_cas() - Compara a variável com o valor antigo e atribui um novo valor a ela

# wincache_ucache_info

(PECL wincache >= 1.1.0)

wincache_ucache_info — Recupera informações sobre dados armazenados no cache do usuário

### Descrição

function wincache_ucache_info(bool `$summaryonly` = `false`, string `$key` = NULL): array|false

Recupera informações sobre dados armazenados no cache do usuário.

### Parâmetros

`summaryonly`

  Controla se o array retornado conterá informações sobre entradas de cache individuais junto com o resumo do cache do usuário.

`key`

  A chave de uma entrada no cache do usuário. Se especificado, o array retornado conterá informações apenas sobre essa entrada de cache. Se não especificado e `summaryonly` estiver definido como `false`, o array retornado conterá informações sobre todas as entradas no cache.

### Valor Retornado

Array de metadados sobre cache do usuário ou `false` em caso de falha

O array retornado por esta função contém os seguintes elementos:

- `total_cache_uptime` - tempo total em segundos que o cache do usuário esteve ativo
- `total_item_count` - número total de elementos que estão atualmente no cache do usuário
- `is_local_cache` - true se os metadados do cache forem para uma instância de cache local, false se os metadados forem para o cache global
- `total_hit_count` - número de vezes que os dados foram servidos do cache
- `total_miss_count` - número de vezes que os dados não foram encontrados no cache

- `ucache_entries` - um array que contém informações sobre todos os itens armazenados em cache:

  - `key_name` - nome da chave que é usada para armazenar os dados
  - `value_type` - tipo de valor armazenado pela chave
  - `use_time` - tempo em segundos desde que o arquivo foi acessado no cache do opcode
  - `last_check` - tempo em segundos desde que o arquivo foi verificado para modificações
  - `is_session` - indica se os dados são uma variável de sessão
  - `ttl_seconds` - tempo restante para os dados permanecerem no cache, 0 significando infinito
  - `age_seconds` - tempo decorrido desde o momento em que os dados foram adicionados ao cache
  - `hitcount` - número de vezes que os dados foram fornecidos pelo cache

### Exemplos

Exemplo #1 Usando wincache_ucache_info()

    <?php
    wincache_ucache_get('green');
    wincache_ucache_set('green', 2922);
    wincache_ucache_get('green');
    wincache_ucache_get('green');
    wincache_ucache_get('green');
    print_r(wincache_ucache_info());
    ?>

O exemplo acima produzirá:

    Array
    ( ["total_cache_uptime"] => int(0)
      ["is_local_cache"] => bool(false)
      ["total_item_count"] => int(1)
      ["total_hit_count"] => int(3)
      ["total_miss_count"] => int(1)
      ["ucache_entries"] => Array(1)
        ( [1] => Array(6)
          (
            ["key_name"] => string(5) "green"
            ["value_type"] => string(4) "long"
            ["is_session"] => int(0)
            ["ttl_seconds"] => int(0)
            ["age_seconds"] => int(0)
            ["hitcount"] => int(3)
           )
        )
    )

### Veja Também

- wincache_fcache_meminfo() - Recupera informações sobre o uso da memória cache do arquivo
- wincache_ocache_fileinfo() - Recupera informações sobre arquivos armazenados em cache no cache do opcode
- wincache_ocache_meminfo() - Recupera informações sobre o uso da memória cache do opcode
- wincache_rplist_meminfo() - Recupera informações sobre o uso de memória pelo cache do caminho do arquivo de resolução
- wincache_rplist_fileinfo() - Recupera informações sobre o cache do caminho do arquivo de resolução
- wincache_refresh_if_changed() - Atualiza as entradas de cache para os arquivos armazenados em cache
- wincache_ucache_meminfo() - Recupera informações sobre o uso da memória cache do usuário
- wincache_scache_info() - Recupera informações sobre arquivos armazenados em cache no cache de sessão
- wincache_scache_meminfo() - Recupera informações sobre o uso da memória cache da sessão

# wincache_ucache_meminfo

(PECL wincache >= 1.1.0)

wincache_ucache_meminfo — Recupera informações sobre o uso da memória cache do usuário

### Descrição

function wincache_ucache_meminfo(): array|false

Recupera informações sobre o uso de memória pelo cache do usuário.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Array de metadados sobre uso de memória cache do usuário ou `false` em caso de falha

O array retornado por esta função contém os seguintes elementos:

- `memory_total` - quantidade de memória em bytes alocada para o cache do usuário
- `memory_free` - quantidade de memória livre em bytes disponível para o cache do usuário
- `num_used_blks` - número de blocos de memória usados ​​pelo cache do usuário
- `num_free_blks` - número de blocos de memória livres disponíveis para o cache do usuário
- `memory_overhead` - aquantidade de memória em bytes usada para estruturas internas do cache do usuário

### Exemplos

Exemplo #1 Um exemplo de wincache_ucache_meminfo()

    <pre>
    <?php
    print_r(wincache_ucache_meminfo());
    ?>
    </pre>

O exemplo acima produzirá:

    Array
    (
        [memory_total] => 5242880
        [memory_free] => 5215056
        [num_used_blks] => 6
        [num_free_blks] => 3
        [memory_overhead] => 176
    )

### Veja Também

- wincache_fcache_fileinfo() - Recupera informações sobre arquivos armazenados em cache no cache de arquivos
- wincache_fcache_meminfo() - Recupera informações sobre o uso da memória cache do arquivo
- wincache_ocache_fileinfo() - Recupera informações sobre arquivos armazenados em cache no cache do opcode
- wincache_rplist_fileinfo() - Recupera informações sobre o cache do caminho do arquivo de resolução
- wincache_rplist_meminfo() - Recupera informações sobre o uso de memória pelo cache do caminho do arquivo de resolução
- wincache_refresh_if_changed() - Atualiza as entradas de cache para os arquivos armazenados em cache
- wincache_ucache_info() - Recupera informações sobre dados armazenados no cache do usuário
- wincache_scache_info() - Recupera informações sobre arquivos armazenados em cache no cache de sessão
- wincache_scache_meminfo() - Recupera informações sobre o uso da memória cache da sessão

# wincache_ucache_set

(PECL wincache >= 1.1.0)

wincache_ucache_set — Adiciona uma variável no cache do usuário e substitui uma variável se ela já existir no cache

### Descrição

function wincache_ucache_set(mixed `$key`, mixed `$value`, int `$ttl` = 0): bool
function wincache_ucache_set(array `$values`, mixed `$unused` = NULL, int `$ttl` = 0): bool

Adiciona uma variável ao cache do usuário. Substitui uma variável se ela já existir no cache. A variável adicionada ou atualizada permanece no cache do usuário, a menos que seu tempo de vida expire ou seja excluída usando as funções wincache_ucache_delete() ou wincache_ucache_clear().

### Parâmetros

`key`

  Armazene a variável usando este nome `key`. Se uma variável com o mesmo `key` já estiver presente, a função substituirá o valor anterior pelo novo. `key` diferencia maiúsculas de minúsculas. `key` também pode receber um array de pares nome => valor, onde os nomes serão usados ​​como chaves. Isso pode ser usado para adicionar vários valores ao cache em uma única operação, evitando assim condições de corrida.

`value`

  Valor de uma variável a ser armazenada. `Value` suporta todos os tipos de dados, exceto recursos, como identificadores de arquivo. Este parâmetro é ignorado se o primeiro argumento for um array. Uma orientação geral é passar `null` como `value` enquanto usa array como `key`. Se `value` for um objeto ou um array contendo objetos, os objetos serão serializados. Consulte __sleep() para obter detalhes sobre a serialização de objetos.

`values`

  Array associativo de chaves e valores.

`ttl`

  Tempo que a variável permanece no cache em segundos. Após o valor especificado em `ttl` ser excedido, a variável armazenada será excluída do cache. Este parâmetro assume o valor padrão de `0`, o que significa que a variável permanecerá no cache, a menos que seja explicitamente excluída usando as funções wincache_ucache_delete() ou wincache_ucache_clear().

### Valor Retornado

Se `key` for uma string, a função retornará `true` em caso de sucesso e `false` em caso de falha.

Se `key` for um array, a função retornará:

- Se todos os pares nome => valor no array puderem ser definidos, a função retornará um array vazio;
- Se todos os pares nome => valor no array não puderem ser definidos, a função retornará `false`;
- Se alguns puderem ser definidos enquanto outros não, a função retornará um array com par nome=>valor para o qual a adição falhou no cache do usuário.

### Exemplos

Exemplo #1 wincache_ucache_set() com `key` sendo uma string

    <?php
    $bar = 'BAR';
    var_dump(wincache_ucache_set('foo', $bar));
    var_dump(wincache_ucache_get('foo'));
    $bar1 = 'BAR1';
    var_dump(wincache_ucache_set('foo', $bar1));
    var_dump(wincache_ucache_get('foo'));
    ?>

O exemplo acima produzirá:

    bool(true)
    string(3) "BAR"
    bool(true)
    string(3) "BAR1"

Exemplo #2 wincache_ucache_set() com `key` sendo um array

    <?php
    $colors_array = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
    var_dump(wincache_ucache_set($colors_array));
    var_dump(wincache_ucache_set($colors_array));
    var_dump(wincache_ucache_get('Blue'));
    ?>

O exemplo acima produzirá:

    array(0) {}
    array(0) {}
    string(1) "6"

### Veja Também

- wincache_ucache_add() - Adiciona uma variável no cache do usuário somente se a variável ainda não existir no cache
- wincache_ucache_get() - Obtém uma variável armazenada no cache do usuário
- wincache_ucache_delete() - Exclui variáveis ​​do cache do usuário
- wincache_ucache_clear() - Exclui todo o conteúdo do cache do usuário
- wincache_ucache_exists() - Verifica se uma variável existe no cache do usuário
- wincache_ucache_meminfo() - Recupera informações sobre o uso da memória cache do usuário
- wincache_ucache_info() - Recupera informações sobre dados armazenados no cache do usuário
- __sleep()

# wincache_unlock

(PECL wincache >= 1.1.0)

wincache_unlock — Libera um bloqueio exclusivo em uma determinada chave

### Descrição

function wincache_unlock(string `$key`): bool

Libera um bloqueio exclusivo obtido em uma determinada chave usando wincache_lock(). Se qualquer outro processo estiver bloqueado aguardando o bloqueio nesta chave, esse processo poderá obter o bloqueio.

Aviso

O uso de wincache_lock() e wincache_unlock() pode causar impasses ao executar scripts PHP em um ambiente multiprocesso como o FastCGI. Não use essas funções a menos que tenha absoluta certeza de que precisa usá-las. Para a maioria das operações no cache do usuário, não é necessário usar essas funções.

### Parâmetros

`key`

  Nome da chave no cache para liberar o bloqueio.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Usando wincache_unlock()

    <?php
    $fp = fopen("/tmp/lock.txt", "r+");
    if (wincache_lock(“lock_txt_lock”)) { // faz um bloqueio exclusivo
        ftruncate($fp, 0); // trunca o arquivo
        fwrite($fp, "Escreva algo aqui\n");
        wincache_unlock(“lock_txt_lock”); // libera o bloqueio
    } else {
        echo "Não foi possível obter o bloqueio!";
    }
    fclose($fp);
    ?>

### Veja Também

- wincache_lock() - Adquire um bloqueio exclusivo em uma determinada chave
- wincache_ucache_set() - Adiciona uma variável no cache do usuário e substitui uma variável se ela já existir no cache
- wincache_ucache_get() - Obtém uma variável armazenada no cache do usuário
- wincache_ucache_delete() - Exclui variáveis ​​do cache do usuário
- wincache_ucache_clear() - Exclui todo o conteúdo do cache do usuário
- wincache_ucache_exists() - Verifica se uma variável existe no cache do usuário
- wincache_ucache_meminfo() - Recupera informações sobre o uso da memória cache do usuário
- wincache_ucache_info() - Recupera informações sobre dados armazenados no cache do usuário
- wincache_scache_info() - Recupera informações sobre arquivos armazenados em cache no cache de sessão

## Índice

- wincache_fcache_fileinfo — Recupera informações sobre arquivos armazenados em cache no cache de arquivos
- wincache_fcache_meminfo — Recupera informações sobre o uso da memória cache do arquivo
- wincache_lock — Adquire um bloqueio exclusivo em uma determinada chave
- wincache_ocache_fileinfo — Recupera informações sobre arquivos armazenados em cache no cache do opcode
- wincache_ocache_meminfo — Recupera informações sobre o uso da memória cache do opcode
- wincache_refresh_if_changed — Atualiza as entradas de cache para os arquivos armazenados em cache
- wincache_rplist_fileinfo — Recupera informações sobre o cache do caminho do arquivo de resolução
- wincache_rplist_meminfo — Recupera informações sobre o uso de memória pelo cache do caminho do arquivo de resolução
- wincache_scache_info — Recupera informações sobre arquivos armazenados em cache no cache de sessão
- wincache_scache_meminfo — Recupera informações sobre o uso da memória cache da sessão
- wincache_ucache_add — Adiciona uma variável no cache do usuário somente se a variável ainda não existir no cache
- wincache_ucache_cas — Compara a variável com o valor antigo e atribui um novo valor a ela
- wincache_ucache_clear — Exclui todo o conteúdo do cache do usuário
- wincache_ucache_dec — Decrementa o valor associado à chave
- wincache_ucache_delete — Exclui variáveis ​​do cache do usuário
- wincache_ucache_exists — Verifica se uma variável existe no cache do usuário
- wincache_ucache_get — Obtém uma variável armazenada no cache do usuário
- wincache_ucache_inc — Incrementa o valor associado à chave
- wincache_ucache_info — Recupera informações sobre dados armazenados no cache do usuário
- wincache_ucache_meminfo — Recupera informações sobre o uso da memória cache do usuário
- wincache_ucache_set — Adiciona uma variável no cache do usuário e substitui uma variável se ela já existir no cache
- wincache_unlock — Libera um bloqueio exclusivo em uma determinada chave

# Construindo para Windows

## Índice

- Pré-requisitos
- Compilando e construindo
- Verificando a compilação

## Pré-requisitos

A construção da extensão WinCache exigirá:

1. Código-fonte do PHP
2. Ambiente de compilação/construção PHP
3. Código-fonte do WinCache

Para concluir os dois primeiros passos, siga o guia passo a passo sobre como » compilar o PHP no Windows.

Para obter o código-fonte do WinCache, siga as instruções descritas em Baixando extensões PECL.

## Compilando e construindo

As etapas a seguir descrevem como compilar e criar o WinCache no sistema operacional Windows:

1. Abra um prompt de comando que é usado para construir PHP

2. Vá para a pasta raiz onde as fontes PHP estão presentes

3. Execute o comando:

       cscript.exe win32\build\buildconf.js

4. Execute o comando:

       configure.bat --help

   A saída conterá um novo sinalizador `--enable-wincache`.

5. Execute o comando:

       configure.js [all options used to build PHP] --enable-wincache

   `--enable-wincache` é a única opção extra necessária para garantir que a extensão WinCache seja compilada corretamente. Esta opção compilará o WinCache e o vinculará estaticamente à DLL do PHP. Para compilar a extensão WinCache como uma DLL independente, use a opção `--enable-wincache=shared`.

6. Execute o comando:

       nmake

## Verificando a compilação

As etapas a seguir descrevem como verificar se o WinCache foi criado corretamente:

1. Vá para a pasta onde os binários do PHP são construídos.

2. Execute o comando:

       php.exe -n -d extension=php_wincache.dll -re wincache

   Se o WinCache tiver sido criado corretamente, a saída deste comando listará as diretivas e funções INI suportadas pelo WinCache.

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
  - Script de estatísticas do WinCache
  - Manipulador de Sessão WinCache
  - Redirecionamentos de funções do WinCache
- Funções de WinCache
  - wincache_fcache_fileinfo — Recupera informações sobre arquivos armazenados em cache no cache de arquivos
  - wincache_fcache_meminfo — Recupera informações sobre o uso da memória cache do arquivo
  - wincache_lock — Adquire um bloqueio exclusivo em uma determinada chave
  - wincache_ocache_fileinfo — Recupera informações sobre arquivos armazenados em cache no cache do opcode
  - wincache_ocache_meminfo — Recupera informações sobre o uso da memória cache do opcode
  - wincache_refresh_if_changed — Atualiza as entradas de cache para os arquivos armazenados em cache
  - wincache_rplist_fileinfo — Recupera informações sobre o cache do caminho do arquivo de resolução
  - wincache_rplist_meminfo — Recupera informações sobre o uso de memória pelo cache do caminho do arquivo de resolução
  - wincache_scache_info — Recupera informações sobre arquivos armazenados em cache no cache de sessão
  - wincache_scache_meminfo — Recupera informações sobre o uso da memória cache da sessão
  - wincache_ucache_add — Adiciona uma variável no cache do usuário somente se a variável ainda não existir no cache
  - wincache_ucache_cas — Compara a variável com o valor antigo e atribui um novo valor a ela
  - wincache_ucache_clear — Exclui todo o conteúdo do cache do usuário
  - wincache_ucache_dec — Decrementa o valor associado à chave
  - wincache_ucache_delete — Exclui variáveis ​​do cache do usuário
  - wincache_ucache_exists — Verifica se uma variável existe no cache do usuário
  - wincache_ucache_get — Obtém uma variável armazenada no cache do usuário
  - wincache_ucache_inc — Incrementa o valor associado à chave
  - wincache_ucache_info — Recupera informações sobre dados armazenados no cache do usuário
  - wincache_ucache_meminfo — Recupera informações sobre o uso da memória cache do usuário
  - wincache_ucache_set — Adiciona uma variável no cache do usuário e substitui uma variável se ela já existir no cache
  - wincache_unlock — Libera um bloqueio exclusivo em uma determinada chave
- Construindo para Windows
  - Pré-requisitos
  - Compilando e construindo
  - Verificando a compilação

# Perfilador Hierárquico

# Introdução

O XHProf é um profiler hierárquico e instrumentado leve. Durante a fase de coleta de dados, ele monitora a contagem de chamadas e métricas inclusivas para arcos no gráfico de chamadas dinâmico de um programa. Ele calcula métricas exclusivas na fase de relatório/pós-processamento, como tempo de espera (decorrido), tempo de CPU e uso de memória. Um perfil de funções pode ser dividido por chamadores ou chamados. O XHProf lida com funções recursivas detectando ciclos no gráfico de chamadas no próprio momento da coleta de dados e evitando os ciclos, atribuindo nomes qualificados de profundidade exclusivos para as invocações recursivas.

O XHProf inclui uma interface de usuário simples baseada em HTML (escrita em PHP). A interface de usuário baseada em navegador para visualizar os resultados do perfilador facilita a visualização ou o compartilhamento de resultados com os pares. Uma visualização de imagem de gráfico de chamadas também é suportada.

Os relatórios XHProf podem frequentemente ser úteis para entender a estrutura do código em execução. A natureza hierárquica dos relatórios pode ser usada para determinar, por exemplo, qual cadeia de chamadas levou à chamada de uma função específica.

O XHProf suporta a capacidade de comparar duas execuções (também conhecidos como relatórios "diff") ou agregar dados de várias execuções. Relatórios de comparação e agregação, assim como relatórios de execução única, oferecem visualizações "planas" e "hierárquicas" do perfil.

Documentação adicional pode ser encontrada no site » facebook xhprof.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução

## Dependências

Embora não seja mandatória, o xhprof inclui uma interface escrita em PHP. Ela é usada para salvar e exibir os dados perfilados de forma utilizável, sendo a visualização feita por meio de um navegador web. Portanto, um servidor web com PHP provavelmente tornará a experiência com o xhprof mais útil.

Há também uma bifurcação da interface GUI em » http://github.com/preinheimer/xhprof

## Instalação

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/xhprof

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de Configuração de Xhprof
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
xhprof.output_dir | "" | `INI_ALL` |

Aqui está uma breve explicação das diretivas de configuração.

`xhprof.output_dir` string

  Diretório usado pela implementação padrão da interface iXHProfRuns (ou seja, a classe XHProfRuns_Default) para armazenar execuções XHProf.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`XHPROF_FLAGS_NO_BUILTINS` (int)
  Usado para pular todas as funções internas.
`XHPROF_FLAGS_CPU` (int)
  Usado para adicionar informações de perfil de CPU à saída.
`XHPROF_FLAGS_MEMORY` (int)
  Usado para adicionar informações de perfil de memória à saída.

# Exemplos

Exemplo #1 Exemplo de Xhprof com a GUI opcional

Este exemplo inicia e interrompe o perfilador e, em seguida, usa a interface gráfica incluída para salvar e analisar os resultados. Em outras palavras, o código da própria extensão termina na chamada para xhprof_disable().

    <?php
    xhprof_enable(XHPROF_FLAGS_CPU + XHPROF_FLAGS_MEMORY);

    for ($i = 0; $i <= 1000; $i++) {
        $a = $i * $i;
    }

    $xhprof_data = xhprof_disable();

    $XHPROF_ROOT = "/tools/xhprof/";
    include_once $XHPROF_ROOT . "/xhprof_lib/utils/xhprof_lib.php";
    include_once $XHPROF_ROOT . "/xhprof_lib/utils/xhprof_runs.php";

    $xhprof_runs = new XHProfRuns_Default();
    $run_id = $xhprof_runs->save_run($xhprof_data, "xhprof_testing");

    echo "http://localhost/xhprof/xhprof_html/index.php?run={$run_id}&source=xhprof_testing\n";

    ?>

O exemplo acima produzirá algo semelhante a:

    http://localhost/xhprof/xhprof_html/index.php?run=t11_4bdf44d21121f&source=xhprof_testing

# Funções de Xhprof

# xhprof_disable

(PECL xhprof >= 0.9.0)

xhprof_disable — Interrompe o perfilador xhprof

### Descrição

function xhprof_disable(): ?array

Interrompe o perfilador e retorna dados xhprof da execução.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array de dados xhprof da execução. Retorna `null` se a perfilagem não estiver habilitada.

### Exemplos

Exemplo #1 Exemplo de xhprof_disable()

    <?php
    xhprof_enable();

    $foo = strlen("foo bar");

    $xhprof_data = xhprof_disable();

    print_r($xhprof_data);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [main()==>strlen] => Array
            (
                [ct] => 1
                [wt] => 279
            )

        [main()==>xhprof_disable] => Array
            (
                [ct] => 1
                [wt] => 9
            )

        [main()] => Array
            (
                [ct] => 1
                [wt] => 610
            )

    )

# xhprof_enable

(PECL xhprof >= 0.9.0)

xhprof_enable — Inicia o perfilador xhprof

### Descrição

function xhprof_enable(int `$flags` = 0, array `$options` = ?): void

Inicia o perfilador xhprof.

### Parâmetros

`flags`

  Sinalizadores opcionais para adicionar informações adicionais ao perfil. Consulte as constantes XHprof para mais informações sobre esses sinalizadores, por exemplo, `XHPROF_FLAGS_MEMORY` para habilitar o perfil de memória.

`options`

  Um array de opções, nomeadamente, a opção 'ignored_functions' para passar as funções que serão ignoradas durante a perfilagem.

### Valor Retornado

`null`

### Registro de Alterações

Versão | Descrição
--- | ---
PECL xhprof 0.9.2 | O parâmetro opcional `options` foi adicionado.

### Exemplos

Exemplo #1 Exemplos de xhprof_enable()

    <?php
    // 1. perfilagem de tempo decorrido + memória + CPU; e ignora funções internas
    xhprof_enable(XHPROF_FLAGS_NO_BUILTINS | XHPROF_FLAGS_CPU | XHPROF_FLAGS_MEMORY);

    // 2. perfilagem de tempo decorrido; ignora call_user_func* durante a perfilagem
    xhprof_enable(
        0,
        array('ignored_functions' =>  array('call_user_func',
                                            'call_user_func_array')));

    // 3. perfilagem de tempo decorrido + memória; ignora call_user_func* durante a perfilagem
    xhprof_enable(
        XHPROF_FLAGS_MEMORY,
        array('ignored_functions' =>  array('call_user_func',
                                            'call_user_func_array')));
    ?>

### Veja Também

- xhprof_disable() - Interrompe o perfilador xhprof
- xhprof_sample_enable() - Inicia o perfilador do XHProf no modo de amostragem
- memory_get_usage() - Retorna a quantidade de memória alocada para o PHP
- getrusage() - Obtém os usos atuais de recursos

# xhprof_sample_disable

(PECL xhprof >= 0.9.0)

xhprof_sample_disable — Interrompe o perfilador de amostra xhprof

### Descrição

function xhprof_sample_disable(): ?array

Interrompe o perfilador xhprof do modo de amostragem e retorna as informações do perfil.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array de dados de amostra do xhprof, da execução. Retorna `null` se a criação de perfil não estiver habilitada.

### Exemplos

Exemplo #1 Exemplo de xhprof_sample_disable()

    <?php
    xhprof_sample_enable();

    for ($i = 0; $i <= 10000; $i++) {
        $a = strlen($i);
        $b = $i * $a;
        $c = rand();
    }

    $xhprof_data = xhprof_sample_disable();

    print_r($xhprof_data);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [1272935300.800000] => main()
        [1272935300.900000] => main()
    )

# xhprof_sample_enable

(PECL xhprof >= 0.9.0)

xhprof_sample_enable — Inicia o perfilador do XHProf no modo de amostragem

### Descrição

function xhprof_sample_enable(): void

Inicia a criação de perfil no modo de amostragem, que é uma versão mais leve de xhprof_enable(). O intervalo de amostragem é de 0.1 segundo, e as amostras registram a pilha completa de chamadas de função. O principal caso de uso é quando uma menor sobrecarga é necessária ao realizar monitoramento e diagnóstico de desempenho.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

`null`

### Veja Também

- xhprof_sample_disable() - Interrompe o perfilador de amostra xhprof
- xhprof_enable() - Inicia o perfilador xhprof
- memory_get_usage() - Retorna a quantidade de memória alocada para o PHP
- getrusage() - Obtém os usos atuais de recursos

## Índice

- xhprof_disable — Interrompe o perfilador xhprof
- xhprof_enable — Inicia o perfilador xhprof
- xhprof_sample_disable — Interrompe o perfilador de amostra xhprof
- xhprof_sample_enable — Inicia o perfilador do XHProf no modo de amostragem

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
- Constantes predefinidas
- Exemplos
- Funções de Xhprof
  - xhprof_disable — Interrompe o perfilador xhprof
  - xhprof_enable — Inicia o perfilador xhprof
  - xhprof_sample_disable — Interrompe o perfilador de amostra xhprof
  - xhprof_sample_enable — Inicia o perfilador do XHProf no modo de amostragem

# Yac

# Introdução

Yac (Yet Another cache), é um cache de dados do usuário de memória compartilhada e sem bloqueio, que pode ser usado para substituir o APC ou o memcache local.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução
- Tipos de Recurso

## Dependências

## Instalação

Esta extensão » PECL não é distribuída com o PHP.

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/yac.

Binários do Windows (arquivos DLL) para esta extensão PECL estão disponíveis no site do PECL.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de Configuração de Yac
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
yac.compress_threshold | -1 | `INI_SYSTEM` |
yac.debug | 0 | `INI_ALL` |
yac.enable | 1 | `INI_SYSTEM` |
yac.enable_cli | 0 | `INI_SYSTEM` |
yac.keys_memory_size | 4M | `INI_SYSTEM` |
yac.serializer | php | `INI_SYSTEM` |
yac.values_memory_size | 64M | `INI_SYSTEM` |

Aqui está uma breve explicação das diretivas de configuração.

`yac.compress_threshold` int

`yac.debug` int

`yac.enable` int

`yac.enable_cli` int

`yac.keys_memory_size` string

`yac.serializer` string

`yac.values_memory_size` string

## Tipos de Recurso

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`YAC_VERSION` (string)
`YAC_MAX_KEY_LEN` (int)
  O comprimento máximo de uma chave, 48 bytes.
`YAC_MAX_VALUE_RAW_LEN` (int)
`YAC_MAX_RAW_COMPRESSED_LEN` (int)
`YAC_SERIALIZER_PHP` (int)
  Usa o serializador do PHP "serialize".
`YAC_SERIALIZER_JSON` (int)
  Usa JSON como serializador (requer --enable-json)
`YAC_SERIALIZER_IGBINARY` (int)
  Usa "igbinary" como serializador (requer --enable-igbinary)
`YAC_SERIALIZER_MSGPACK` (int)
  Usa msgpack como serializador (requer --enable-msgpack)
`YAC_SERIALIZER` (string)
  Que serializador o Yac usa.

# A classe Yac

(PECL yac >= 1.0.0)

## Introdução

## Resumo da classe

class Yac {
/* Propriedades */
protected $_prefix;
/* Métodos */
public function __construct(string `$prefix` = "")
public function add(string `$keys`, mixed `$value`, int `$ttl` = 0): bool
public function add(array `$key_vals`): bool
public function delete(string|array `$keys`, int `$ttl` = ?): bool
public function dump(int `$$num`): mixed
public function flush(): bool
public function get(string|array `$key`, int `&$cas` = `null`): mixed
public function __get(string `$key`): mixed
public function info(): array
public function set(string `$keys`, mixed `$value`, int `$ttl` = 0): bool
public function add(array `$key_vals`): bool
public function __set(string `$keys`, mixed `$value`): mixed
}

## Propriedades

_prefix

# Yac::add

(PECL yac >= 1.0.0)

Yac::add — Armazena em cache

### Descrição

public function Yac::add(string `$keys`, mixed `$value`, int `$ttl` = 0): bool
public function Yac::add(array `$key_vals`): bool

Adiciona um item ao cache.

### Parâmetros

`keys`

  string de chaves.

`value`

  Valor, todos os tipos do PHP podem ser armazenados, exceto resource.

`ttl`

  Tempo de vida.

### Valor Retornado

bool, `true` em caso de sucesso, ou `false` em caso de falha.

> Nota:

> Yac::add() pode falhar se uma trava CAS não puder ser obtida, portanto, se for necessário que o valor seja armazenado adequadamente, pode-se escrever um codigo como este:

> Exemplo #1 Garantindo que um item é armazenado

>     while(!$yac->set("chave", "valor"));

# Yac::__construct

(PECL yac >= 1.0.0)

Yac::__construct — Construtor

### Descrição

public function Yac::__construct(string `$prefix` = "")

O parâmetro "prefix" é usado para prefixar chaves. Isso pode ser usado para evitar conflitos entre aplicações.

### Parâmetros

`prefix`

  string de prefixo.

### Erros/Exceções

Lança uma Exception se o Yac não estiver habilitado. Lança uma Exception se `prefix` exceder o comprimento máximo de 48 (`YAC_MAX_KEY_LEN`) bytes.

# Yac::delete

(PECL yac >= 1.0.0)

Yac::delete — Exclui itens do cache

### Descrição

public function Yac::delete(string|array `$keys`, int `$ttl` = ?): bool

Exclui itens do cache.

### Parâmetros

`keys`

  Chave string, ou array com múltiplas chaves a serem removidas.

`ttl`

  Tempo em segundos para marcar os itens como inválidos.

### Valor Retornado

# Yac::dump

(PECL yac >= 1.0.0)

Yac::dump — Despeja o cache

### Descrição

public function Yac::dump(int `$$num`): mixed

Despeja os valores armazenados em cache.

### Parâmetros

`num`

  O máximo número de itens que devem ser retornados.

### Valor Retornado

Retorna os valores despejados.

# Yac::flush

(PECL yac >= 1.0.0)

Yac::flush — Descarrega o cache

### Descrição

public function Yac::flush(): bool

Remove todos os valores em cache.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Sempre retorna true.

# Yac::get

(PECL yac >= 1.0.0)

Yac::get — Obtém valores do cache

### Descrição

public function Yac::get(string|array `$key`, int `&$cas` = `null`): mixed

Obtém valores do cache.

### Parâmetros

`key`

  Chaves string ou array de várias chaves.

`cas`

  Se não for `null`, será definido para o CAS do item obtido.

### Valor Retornado

Retorna o valor em caso de sucesso, false em caso de falha.

# Yac::__get

(PECL yac >= 1.0.0)

Yac::__get — Obtém valores do cache

### Descrição

public function Yac::__get(string `$key`): mixed

Obtém valores do cache.

### Parâmetros

`key`

  Chave string

### Valor Retornado

Retorna o valor em caso de sucesso, `null` em caso de falha.

# Yac::info

(PECL yac >= 1.0.0)

Yac::info — Obtém o status do cache

### Descrição

public function Yac::info(): array

Obtém o status do sistema de cache.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array com as seguintes chaves: "memory_size", "slots_memory_size", "values_memory_size", "segment_size", "segment_num", "miss", "hits", "fails", "kicks", "recycles", "slots_size" e "slots_used".

# Yac::set

(PECL yac >= 1.0.0)

Yac::set — Armazena no cache

### Descrição

public function Yac::set(string `$keys`, mixed `$value`, int `$ttl` = 0): bool
public function Yac::add(array `$key_vals`): bool

Adiciona um item ao cache e, se a chave já existir, substitui o item.

### Parâmetros

`keys`

  Chave string.

`value`

  Valor a ser armazenado, de qualquer tipo PHP exceto resource.

`ttl`

  Tempo de vida.

### Valor Retornado

O próprio valor.

# Yac::__set

(PECL yac >= 1.0.0)

Yac::__set — Armazena no cache

### Descrição

public function Yac::__set(string `$keys`, mixed `$value`): mixed

Armazena um item no cache.

### Parâmetros

`keys`

  Chave string.

`value`

  Valor a ser armazenado, de qualquer tipo PHP exceto resource.

### Valor Retornado

Sempre retorna o próprio valor.

## Índice

- Yac::add — Armazena em cache
- Yac::__construct — Construtor
- Yac::delete — Exclui itens do cache
- Yac::dump — Despeja o cache
- Yac::flush — Descarrega o cache
- Yac::get — Obtém valores do cache
- Yac::__get — Obtém valores do cache
- Yac::info — Obtém o status do cache
- Yac::set — Armazena no cache
- Yac::__set — Armazena no cache

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
  - Tipos de Recurso
- Constantes predefinidas
- Yac — A classe Yac
  - Yac::add — Armazena em cache
  - Yac::__construct — Construtor
  - Yac::delete — Exclui itens do cache
  - Yac::dump — Despeja o cache
  - Yac::flush — Descarrega o cache
  - Yac::get — Obtém valores do cache
  - Yac::__get — Obtém valores do cache
  - Yac::info — Obtém o status do cache
  - Yac::set — Armazena no cache
  - Yac::__set — Armazena no cache

- APCu — Cache de Usuário APC
  - Instalação/Configuração
  - Constantes predefinidas
  - APCu Funções
  - APCUIterator — A classe APCUIterator
- Componere
  - Instalação/Configuração
  - Componere\Abstract\Definition — A classe Componere\Abstract\Definition
  - Componere\Definition — A classe Componere\Definition
  - Componere\Patch — A classe Componere\Patch
  - Componere\Method — A classe Componere\Method
  - Componere\Value — A classe Componere\Value
  - Funções de Componere
- Gerenciamento de Erros — Gerenciamento e Registro de Erros
  - Instalação/Configuração
  - Constantes predefinidas
  - Exemplos
  - Funções para Manuseamento de Erros
- FFI — Interface de função externa
  - Instalação/Configuração
  - Exemplos
  - FFI — Interface principal ao código e aos dados em C
  - FFI\CData — Identificadores de dados em C
  - FFI\CType — Identificadores de Tipo em C
  - FFI\Exception — Exceções FFI
  - FFI\ParserException — Exceções do Analisador FFI
- OPcache
  - Instalação/Configuração
  - Preloading
  - Funções de OPcache
- Controle de Saída — Controle de Buffer de Saída
  - Instalação/Configuração
  - Constantes predefinidas
  - Buffer de Saída
  - Descarregando Buffers de Sistema
  - Buffers de Saída em Nível de Usuário
  - Exemplos
  - Funções para Control de Saída
- Opções/Info do PHP — Informações e Opções do PHP
  - Instalação/Configuração
  - Constantes predefinidas
  - Funções para Opções/Info do PHP
- phpdbg — Depurador PHP Interativo
  - Instalação/Configuração
  - Constantes predefinidas
  - phpdbg Funções
- runkit7
  - Instalação/Configuração
  - Constantes predefinidas
  - Funções de runkit7
- uopz — Operações do usuário para Zend
  - Instalação/Configuração
  - Constantes predefinidas
  - Funções de Uopz
- WinCache — Cache do Windows para PHP
  - Instalação/Configuração
  - Funções de WinCache
  - Construindo para Windows
- Xhprof — Perfilador Hierárquico
  - Instalação/Configuração
  - Constantes predefinidas
  - Exemplos
  - Funções de Xhprof
- Yac
  - Instalação/Configuração
  - Constantes predefinidas
  - Yac — A classe Yac

# Manipulação de Formatos de Áudio

# Ligações de áudio OpenAL

# Introdução

Ligações de áudio independentes de plataforma. Requer a » biblioteca OpenAL.

# Instalação/Configuração

## Índice

- Instalação
- Tipos de Recurso

## Instalação

Esta extensão » PECL não é distribuída com o PHP.

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/openal.

Uma DLL para esta extensão PECL não está disponível no momento. Veja também a seção Compilando no Windows.

## Tipos de Recurso

Esta extensão define quatro tipos de recursos: Open AL(Dispositivo) - Retornado por openal_device_open(), Open AL(Contexto) - Retornado por openal_context_create(), Open AL(Buffer) - Retornado por openal_buffer_create(), e Open AL(Fonte) - Retornado por openal_source_create().

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`ALC_FREQUENCY` (int)
  Atributo de contexto
`ALC_REFRESH` (int)
  Atributo de contexto
`ALC_SYNC` (int)
  Atributo de contexto
`AL_FREQUENCY` (int)
  Configuração de buffer
`AL_BITS` (int)
  Configuração de buffer
`AL_CHANNELS` (int)
  Configuração de buffer
`AL_SIZE` (int)
  Configuração de buffer
`AL_BUFFER` (int)
  Configuração de origem/ouvinte (Inteiro)
`AL_SOURCE_RELATIVE` (int)
  Configuração de origem/ouvinte (Inteiro)
`AL_SOURCE_STATE` (int)
  Configuração de origem/ouvinte (Inteiro)
`AL_PITCH` (int)
  Configuração de origem/ouvinte (Flutuante)
`AL_GAIN` (int)
  Configuração de origem/ouvinte (Flutuante)
`AL_MIN_GAIN` (int)
  Configuração de origem/ouvinte (Flutuante)
`AL_MAX_GAIN` (int)
  Configuração de origem/ouvinte (Flutuante)
`AL_MAX_DISTANCE` (int)
  Configuração de origem/ouvinte (Flutuante)
`AL_ROLLOFF_FACTOR` (int)
  Configuração de origem/ouvinte (Flutuante)
`AL_CONE_OUTER_GAIN` (int)
  Configuração de origem/ouvinte (Flutuante)
`AL_CONE_INNER_ANGLE` (int)
  Configuração de origem/ouvinte (Flutuante)
`AL_CONE_OUTER_ANGLE` (int)
  Configuração de origem/ouvinte (Flutuante)
`AL_REFERENCE_DISTANCE` (int)
  Configuração de origem/ouvinte (Flutuante)
`AL_POSITION` (int)
  Configuração de origem/ouvinte (Vetor flutuante)
`AL_VELOCITY` (int)
  Configuração de origem/ouvinte (Vetor flutuante)
`AL_DIRECTION` (int)
  Configuração de origem/ouvinte (Vetor flutuante)
`AL_ORIENTATION` (int)
  Configuração de origem/ouvinte (Vetor flutuante)
`AL_FORMAT_MONO8` (int)
  Formato PCM
`AL_FORMAT_MONO16` (int)
  Formato PCM
`AL_FORMAT_STEREO8` (int)
  Formato PCM
`AL_FORMAT_STEREO16` (int)
  Formato PCM
`AL_INITIAL` (int)
  Estado de origem
`AL_PLAYING` (int)
  Estado de origem
`AL_PAUSED` (int)
  Estado de origem
`AL_STOPPED` (int)
  Estado de origem
`AL_LOOPING` (int)
  Estado de origem
`AL_TRUE` (int)
  Valor booleano reconhecido pelo OpenAL
`AL_FALSE` (int)
  Valor booleano reconhecido pelo OpenAL

# Funções de OpenAL

# openal_buffer_create

(PECL openal >= 0.1.0)

openal_buffer_create — Gera buffer OpenAL

### Descrição

function openal_buffer_create(): resource

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um recurso Open AL(Buffer) em caso de sucesso ou `false` em caso de falha.

### Veja Também

- openal_buffer_loadwav() - Carrega um arquivo .wav em um buffer
- openal_buffer_data() - Carrega um buffer com dados

# openal_buffer_data

(PECL openal >= 0.1.0)

openal_buffer_data — Carrega um buffer com dados

### Descrição

function openal_buffer_data(
resource `$buffer`,
int `$format`,
string `$data`,
int `$freq`
): bool

### Parâmetros

`buffer`
  Um recurso Open AL(Buffer) (criado anteriormente por openal_buffer_create()).
`format`
  Formato de `data`, um dos seguintes: `AL_FORMAT_MONO8`, `AL_FORMAT_MONO16`, `AL_FORMAT_STEREO8` e `AL_FORMAT_STEREO16`
`data`
  Bloco de dados de áudio binários no formato especificado por `format` e frequência informada em `freq`.
`freq`
  Frequência de `data` informada em Hz.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- openal_buffer_loadwav() - Carrega um arquivo .wav em um buffer
- openal_stream() - Inicia a transmissão de uma origem

# openal_buffer_destroy

(PECL openal >= 0.1.0)

openal_buffer_destroy — Destrói um buffer OpenAL

### Descrição

function openal_buffer_destroy(resource `$buffer`): bool

### Parâmetros

`buffer`
  Um recurso Open AL(Buffer) (criado anteriormente por openal_buffer_create()).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- openal_buffer_create() - Gera buffer OpenAL

# openal_buffer_get

(PECL openal >= 0.1.0)

openal_buffer_get — Recupera uma propriedade de buffer OpenAL

### Descrição

function openal_buffer_get(resource `$buffer`, int `$property`): int|false

### Parâmetros

`buffer`
  Um recurso Open AL(Buffer) (criado anteriormente por openal_buffer_create()).
`property`
  Propriedade específica, uma de: `AL_FREQUENCY`, `AL_BITS`, `AL_CHANNELS` e `AL_SIZE`.

### Valor Retornado

Retorna um valor inteiro apropriado para a propriedade solicitata em `property` ou `false` em caso de falha.

### Veja Também

- openal_buffer_create() - Gera buffer OpenAL

# openal_buffer_loadwav

(PECL openal >= 0.1.0)

openal_buffer_loadwav — Carrega um arquivo .wav em um buffer

### Descrição

function openal_buffer_loadwav(resource `$buffer`, string `$wavfile`): bool

### Parâmetros

`buffer`
  Um recurso Open AL(Buffer) (criado anteriormente por openal_buffer_create()).
`wavfile`
  Caminho para o arquivo .wav no sistema de arquivos local.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- openal_buffer_data() - Carrega um buffer com dados
- openal_stream() - Inicia a transmissão de uma origem

# openal_context_create

(PECL openal >= 0.1.0)

openal_context_create — Cria um contexto de processamento de áudio

### Descrição

function openal_context_create(resource `$device`): resource

### Parâmetros

`device`
  Um recurso Open AL(Device) (criado anteriormente por openal_device_open()).

### Valor Retornado

Retorna um recurso Open AL(Context) em caso de sucesso ou `false` em caso de falha.

### Veja Também

- openal_device_open() - Inicializa a camada de áudio OpenAL
- openal_context_destroy() - Destrói um contexto

# openal_context_current

(PECL openal >= 0.1.0)

openal_context_current — Torna o contexto especificado atual

### Descrição

function openal_context_current(resource `$context`): bool

### Parâmetros

`context`
  Um recurso Open AL(Context) (criado anteriormente por openal_context_create()).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- openal_context_create() - Cria um contexto de processamento de áudio

# openal_context_destroy

(PECL openal >= 0.1.0)

openal_context_destroy — Destrói um contexto

### Descrição

function openal_context_destroy(resource `$context`): bool

### Parâmetros

`context`
  Um recurso Open AL(Context) (criado anteriormente por openal_context_create()).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- openal_context_create() - Cria um contexto de processamento de áudio

# openal_context_process

(PECL openal >= 0.1.0)

openal_context_process — Processa o contexto especificado

### Descrição

function openal_context_process(resource `$context`): bool

### Parâmetros

`context`
  Um recurso Open AL(Context) (criado anteriormente por openal_context_create()).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- openal_context_create() - Cria um contexto de processamento de áudio
- openal_context_current() - Torna o contexto especificado atual
- openal_context_suspend() - Suspende o contexto especificado

# openal_context_suspend

(PECL openal >= 0.1.0)

openal_context_suspend — Suspende o contexto especificado

### Descrição

function openal_context_suspend(resource `$context`): bool

### Parâmetros

`context`
  Um recurso Open AL(Context) (criado anteriormente por openal_context_create()).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- openal_context_create() - Cria um contexto de processamento de áudio
- openal_context_current() - Torna o contexto especificado atual
- openal_context_process() - Processa o contexto especificado

# openal_device_close

(PECL openal >= 0.1.0)

openal_device_close — Fecha um dispositivo OpenAL

### Descrição

function openal_device_close(resource `$device`): bool

### Parâmetros

`device`
  Um recurso Open AL(Device) (criado anteriormente por openal_device_open()) a ser fechado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- openal_device_open() - Inicializa a camada de áudio OpenAL

# openal_device_open

(PECL openal >= 0.1.0)

openal_device_open — Inicializa a camada de áudio OpenAL

### Descrição

function openal_device_open(string `$device_desc` = ?): resource

### Parâmetros

`device_desc`
  Abre um dispositivo de áudio opcionalmente especificado por `device_desc`. Se `device_desc` não for especificado, o primeiro dispositivo de áudio disponível será usado.

### Valor Retornado

Retorna um recurso Open AL(Device) em caso de sucesso ou `false` em caso de falha.

### Veja Também

- openal_device_close() - Fecha um dispositivo OpenAL
- openal_context_create() - Cria um contexto de processamento de áudio

# openal_listener_get

(PECL openal >= 0.1.0)

openal_listener_get — Recupera uma propriedade do ouvinte

### Descrição

function openal_listener_get(int `$property`): mixed

### Parâmetros

`property`
  Propriedade a ser recuperada, uma de: `AL_GAIN` (float), `AL_POSITION` (array(float,float,float)), `AL_VELOCITY` (array(float,float,float)) e `AL_ORIENTATION` (array(float,float,float)).

### Valor Retornado

Retorna um float ou um array de floats (conforme apropriado) ou `false` em caso de falha.

### Veja Também

- openal_listener_set() - Define uma propriedade de ouvinte

# openal_listener_set

(PECL openal >= 0.1.0)

openal_listener_set — Define uma propriedade de ouvinte

### Descrição

function openal_listener_set(int `$property`, mixed `$setting`): bool

### Parâmetros

`property`
  Propriedade a ser definida, uma de: `AL_GAIN` (float), `AL_POSITION` (array(float,float,float)), `AL_VELOCITY` (array(float,float,float)) e `AL_ORIENTATION` (array(float,float,float)).
`setting`
  Valor a ser definido, float ou um array de floats, conforme apropriado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- openal_listener_get() - Recupera uma propriedade do ouvinte

# openal_source_create

(PECL openal >= 0.1.0)

openal_source_create — Gera um recurso de origem

### Descrição

function openal_source_create(): resource

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um recurso Open AL(Source) em caso de sucesso ou `false` em caso de falha.

### Veja Também

- openal_source_set() - Define propriedade da origem
- openal_source_play() - Começa a reproduzir a origem
- openal_source_destroy() - Destrói um recurso de origem

# openal_source_destroy

(PECL openal >= 0.1.0)

openal_source_destroy — Destrói um recurso de origem

### Descrição

function openal_source_destroy(resource `$source`): bool

### Parâmetros

`source`
  Um recurso Open AL(Source) (criado anteriormente por openal_source_create()).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- openal_source_create() - Gera um recurso de origem

# openal_source_get

(PECL openal >= 0.1.0)

openal_source_get — Recupera uma propriedade de origem OpenAL

### Descrição

function openal_source_get(resource `$source`, int `$property`): mixed

### Parâmetros

`source`
  Um recurso Open AL(Source) (criado anteriormente por openal_source_create()).
`property`
  Propriedade a ser obtida, uma das seguintes: `AL_SOURCE_RELATIVE` (int), `AL_SOURCE_STATE` (int), `AL_PITCH` (float), `AL_GAIN` (float), `AL_MIN_GAIN` (float), `AL_MAX_GAIN` (float), `AL_MAX_DISTANCE` (float), `AL_ROLLOFF_FACTOR` (float), `AL_CONE_OUTER_GAIN` (float), `AL_CONE_INNER_ANGLE` (float), `AL_CONE_OUTER_ANGLE` (float), `AL_REFERENCE_DISTANCE` (float), `AL_POSITION` (array(float,float,float)), `AL_VELOCITY` (array(float,float,float)), `AL_DIRECTION` (array(float,float,float)).

### Valor Retornado

Retorna o tipo associado à propriedade que está sendo recuperada ou `false` em caso de falha.

### Veja Também

- openal_source_create() - Gera um recurso de origem
- openal_source_set() - Define propriedade da origem
- openal_source_play() - Começa a reproduzir a origem

# openal_source_pause

(PECL openal >= 0.1.0)

openal_source_pause — Pausa a origem

### Descrição

function openal_source_pause(resource `$source`): bool

### Parâmetros

`source`
  Um recurso Open AL(Source) (criado anteriormente por openal_source_create()).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- openal_source_stop() - Para de reproduzir a origem
- openal_source_play() - Começa a reproduzir a origem
- openal_source_rewind() - Retrocede a origem

# openal_source_play

(PECL openal >= 0.1.0)

openal_source_play — Começa a reproduzir a origem

### Descrição

function openal_source_play(resource `$source`): bool

### Parâmetros

`source`
  Um recurso Open AL(Source) (criado anteriormente por openal_source_create()).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- openal_source_stop() - Para de reproduzir a origem
- openal_source_pause() - Pausa a origem
- openal_source_rewind() - Retrocede a origem

# openal_source_rewind

(PECL openal >= 0.1.0)

openal_source_rewind — Retrocede a origem

### Descrição

function openal_source_rewind(resource `$source`): bool

### Parâmetros

`source`
  Um recurso Open AL(Source) (criado anteriormente por openal_source_create()).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- openal_source_stop() - Para de reproduzir a origem
- openal_source_pause() - Pausa a origem
- openal_source_play() - Começa a reproduzir a origem

# openal_source_set

(PECL openal >= 0.1.0)

openal_source_set — Define propriedade da origem

### Descrição

function openal_source_set(resource `$source`, int `$property`, mixed `$setting`): bool

### Parâmetros

`source`
  Um recurso Open AL(Source) (criado anteriormente por openal_source_create()).
`property`
  Propriedade a definir, uma das seguintes: `AL_BUFFER` (OpenAL(Source)), `AL_LOOPING` (bool), `AL_SOURCE_RELATIVE` (int), `AL_SOURCE_STATE` (int), `AL_PITCH` (float), `AL_GAIN` (float), `AL_MIN_GAIN` (float), `AL_MAX_GAIN` (float), `AL_MAX_DISTANCE` (float), `AL_ROLLOFF_FACTOR` (float), `AL_CONE_OUTER_GAIN` (float), `AL_CONE_INNER_ANGLE` (float), `AL_CONE_OUTER_ANGLE` (float), `AL_REFERENCE_DISTANCE` (float), `AL_POSITION` (array(float,float,float)), `AL_VELOCITY` (array(float,float,float)), `AL_DIRECTION` (array(float,float,float)).
`setting`
  Valor a ser atribuído à propriedade especificada em `property`. Consulte a descrição de cada propriedade possível de `property` para uma descrição do(s) valor(es) esperado(s).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- openal_source_create() - Gera um recurso de origem
- openal_source_get() - Recupera uma propriedade de origem OpenAL
- openal_source_play() - Começa a reproduzir a origem

# openal_source_stop

(PECL openal >= 0.1.0)

openal_source_stop — Para de reproduzir a origem

### Descrição

function openal_source_stop(resource `$source`): bool

### Parâmetros

`source`
  Um recurso Open AL(Source) (criado anteriormente por openal_source_create()).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- openal_source_play() - Começa a reproduzir a origem
- openal_source_pause() - Pausa a origem
- openal_source_rewind() - Retrocede a origem

# openal_stream

(PECL openal >= 0.1.0)

openal_stream — Inicia a transmissão de uma origem

### Descrição

function openal_stream(resource `$source`, int `$format`, int `$rate`): resource|false

### Parâmetros

`source`
  Um recurso Open AL(Source) (criado anteriormente por openal_source_create()).
`format`
  Formato de `data`, um dos seguintes: `AL_FORMAT_MONO8`, `AL_FORMAT_MONO16`, `AL_FORMAT_STEREO8` e `AL_FORMAT_STEREO16`
`rate`
  Frequência de dados a serem transmitidos em Hz.

### Valor Retornado

Retorna um recurso de fluxo em caso de sucesso ou `false` em caso de falha.

### Veja Também

- openal_source_create() - Gera um recurso de origem
- fwrite() - Escrita binary-safe em arquivos

## Índice

- openal_buffer_create — Gera buffer OpenAL
- openal_buffer_data — Carrega um buffer com dados
- openal_buffer_destroy — Destrói um buffer OpenAL
- openal_buffer_get — Recupera uma propriedade de buffer OpenAL
- openal_buffer_loadwav — Carrega um arquivo .wav em um buffer
- openal_context_create — Cria um contexto de processamento de áudio
- openal_context_current — Torna o contexto especificado atual
- openal_context_destroy — Destrói um contexto
- openal_context_process — Processa o contexto especificado
- openal_context_suspend — Suspende o contexto especificado
- openal_device_close — Fecha um dispositivo OpenAL
- openal_device_open — Inicializa a camada de áudio OpenAL
- openal_listener_get — Recupera uma propriedade do ouvinte
- openal_listener_set — Define uma propriedade de ouvinte
- openal_source_create — Gera um recurso de origem
- openal_source_destroy — Destrói um recurso de origem
- openal_source_get — Recupera uma propriedade de origem OpenAL
- openal_source_pause — Pausa a origem
- openal_source_play — Começa a reproduzir a origem
- openal_source_rewind — Retrocede a origem
- openal_source_set — Define propriedade da origem
- openal_source_stop — Para de reproduzir a origem
- openal_stream — Inicia a transmissão de uma origem

- Instalação/Configuração
  - Instalação
  - Tipos de Recurso
- Constantes predefinidas
- Funções de OpenAL
  - openal_buffer_create — Gera buffer OpenAL
  - openal_buffer_data — Carrega um buffer com dados
  - openal_buffer_destroy — Destrói um buffer OpenAL
  - openal_buffer_get — Recupera uma propriedade de buffer OpenAL
  - openal_buffer_loadwav — Carrega um arquivo .wav em um buffer
  - openal_context_create — Cria um contexto de processamento de áudio
  - openal_context_current — Torna o contexto especificado atual
  - openal_context_destroy — Destrói um contexto
  - openal_context_process — Processa o contexto especificado
  - openal_context_suspend — Suspende o contexto especificado
  - openal_device_close — Fecha um dispositivo OpenAL
  - openal_device_open — Inicializa a camada de áudio OpenAL
  - openal_listener_get — Recupera uma propriedade do ouvinte
  - openal_listener_set — Define uma propriedade de ouvinte
  - openal_source_create — Gera um recurso de origem
  - openal_source_destroy — Destrói um recurso de origem
  - openal_source_get — Recupera uma propriedade de origem OpenAL
  - openal_source_pause — Pausa a origem
  - openal_source_play — Começa a reproduzir a origem
  - openal_source_rewind — Retrocede a origem
  - openal_source_set — Define propriedade da origem
  - openal_source_stop — Para de reproduzir a origem
  - openal_stream — Inicia a transmissão de uma origem

- OpenAL — Ligações de áudio OpenAL
  - Instalação/Configuração
  - Constantes predefinidas
  - Funções de OpenAL

# Serviços de Autenticação

# Radius

# Introdução

Este pacote é baseado no libradius (Remote Authentication Dial In User Service) do FreeBSD. Ele permite que clientes realizem autenticação e contabilidade por meio de solicitações de rede a servidores remotos.

Esta extensão PECL adiciona suporte completo para Autenticação Radius (» RFC 2865) e Contabilidade Radius (» RFC 2866). Este pacote está disponível para Unix (testado em FreeBSD e Linux) e para Windows.

> Nota: Uma descrição exata do libradius pode ser encontrada » aqui. Uma descrição detalhada do arquivo de configuração pode ser encontrada » aqui.

# Instalação/Configuração

## Índice

- Instalação

## Instalação

Esta extensão » PECL não é distribuída com o PHP.

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/radius.

# Constantes predefinidas

## Índice

- RADIUS Options
- Tipos de pacotes RADIUS
- Tipos de atributos RADIUS
- Tipos de atributos RADIUS específicos do fornecedor

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`RADIUS_MPPE_KEY_LEN` (int)
  O comprimento máximo das chaves MPPE.

## RADIUS Options

Várias funções RADIUS aceitam sinalizadores de opção como máscaras de bits. As constantes que representam esses sinalizadores estão listadas abaixo.

`RADIUS_OPTION_SALT` (int)
  Quando definida, esta opção fará com que o valor do atributo seja criptografado com salt.
`RADIUS_OPTION_TAGGED` (int)
  Quando definida, esta opção fará com que o valor do atributo seja marcado com o valor do parâmetro tag.

## Tipos de pacotes RADIUS

Pacotes RADIUS, sejam solicitações ou respostas, sempre incluem um tipo. Essas constantes são fornecidas para facilitar a especificação de tipos ao usar radius_create_request() e ao comparar o resultado de radius_send_request().

`RADIUS_ACCESS_REQUEST` (int)
  Uma solicitação de acesso, usada para autenticar um usuário em um servidor RADIUS. Os pacotes de solicitação de acesso devem incluir um atributo `RADIUS_NAS_IP_ADDRESS` ou `RADIUS_NAS_IDENTIFIER`, e também devem incluir um atributo `RADIUS_USER_PASSWORD`, `RADIUS_CHAP_PASSWORD` ou `RADIUS_STATE` e devem incluir um atributo `RADIUS_USER_NAME`.
`RADIUS_ACCESS_ACCEPT` (int)
  Uma resposta de Aceitação de Acesso a uma Solicitação de Acesso, indicando que o servidor RADIUS autenticou o usuário com sucesso.
`RADIUS_ACCESS_REJECT` (int)
  Uma resposta de rejeição de acesso a uma solicitação de acesso indicando que o servidor RADIUS não conseguiu autenticar o usuário.
`RADIUS_ACCESS_CHALLENGE` (int)
  Uma resposta de Desafio de Acesso a uma Solicitação de Acesso, indicando que o servidor RADIUS requer mais informações em outra Solicitação de Acesso antes de autenticar o usuário.
`RADIUS_ACCOUNTING_REQUEST` (int)
  Uma solicitação de contabilidade, usada para transmitir informações contábeis de um serviço ao servidor RADIUS.
`RADIUS_ACCOUNTING_RESPONSE` (int)
  Uma resposta de Contabilidade a uma Solicitação de Contabilidade.
`RADIUS_COA_REQUEST` (int)
  Uma Solicitação CoA, enviada do servidor RADIUS para indicar que as autorizações na sessão do usuário foram alteradas. Uma resposta deve ser enviada na forma de um CoA-ACK ou um CoA-NAK. Esta constante está disponível no PECL radius 1.3.0 e posteriores.
`RADIUS_COA_ACK` (int)
  Um CoA-ACK, enviado ao servidor RADIUS para indicar que as autorizações do usuário foram atualizadas. Esta constante está disponível no PECL radius 1.3.0 e posteriores.
`RADIUS_COA_NAK` (int)
  Um CoA-NAK, enviado ao servidor RADIUS para indicar que as autorizações do usuário não puderam ser atualizadas. Esta constante está disponível no PECL radius 1.3.0 e posteriores.
`RADIUS_DISCONNECT_REQUEST` (int)
  Uma solicitação de desconexão, enviada do servidor RADIUS para indicar que a sessão do usuário deve ser encerrada. Esta constante está disponível no PECL radius 1.3.0 e posteriores.
`RADIUS_DISCONNECT_ACK` (int)
  Um reconhecimento de desconexão, enviado ao servidor RADIUS para indicar que a sessão do usuário foi encerrada. Esta constante está disponível no PECL radius 1.3.0 e posteriores.
`RADIUS_DISCONNECT_NAK` (int)
  Um não reconhecimento de desconexão, enviado ao servidor RADIUS para indicar que a sessão do usuário não pôde ser encerrada. Esta constante está disponível no PECL radius 1.3.0 e posteriores.

## Tipos de atributos RADIUS

Essas constantes definem tipos de atributos RADIUS que podem ser usados ​​com radius_put_addr(), radius_put_attr(), radius_put_int() e radius_put_string().

`RADIUS_USER_NAME` (int)
  O atributo "User-Name". O valor do atributo deve ser uma string contendo o nome do usuário que está sendo autenticado, e pode ser definido usando radius_put_attr().
`RADIUS_USER_PASSWORD` (int)
  O atributo "User-Password". O valor do atributo deve ser uma string contendo a senha do usuário e pode ser definido usando radius_put_attr(). Este valor será ofuscado na transmissão, conforme descrito na » seção 5.2 da RFC 2865.
`RADIUS_CHAP_PASSWORD` (int)
  O atributo "Chap-Password". O valor do atributo deve ser uma string com o primeiro byte contendo o identificador CHAP, e os 16 bytes subsequentes contendo o hash MD5 do identificador CHAP, a senha em texto simples e o valor do desafio CHAP, concatenados. Observe que o valor do desafio CHAP também deve ser enviado separadamente em um atributo `RADIUS_CHAP_CHALLENGE`.

  Exemplo #1 Usando senhas CHAP

      <?php
      // Primeiro, criaremos um identificador de autenticação e uma solicitação.
      $radh = radius_auth_open();
      radius_add_server($radh, $server, $port, $secret, 3, 3);
      radius_create_request($radh, RADIUS_ACCESS_REQUEST);

      // Supondo que $password contém a senha em texto simples, agora:

      // Gere um desafio.
      $challenge = mt_rand();

      // Especifique um identificador CHAP.
      $ident = 1;

      // Adicione o atributo Chap-Password.
      $cp = hash('md5', pack('Ca*', $ident, $password.$challenge), true);
      radius_put_attr($radh, RADIUS_CHAP_PASSWORD, pack('C', $ident).$cp);

      // Adicione o atributo Chap-Challenge.
      radius_put_attr($radh, RADIUS_CHAP_CHALLENGE, $challenge);

      /* A partir daqui, seriam adicionados os atributos restantes e
      * a função radius_send_request() seria chamada. */
      ?>

`RADIUS_NAS_IP_ADDRESS` (int)
  O atributo "NAS-IP-Address". O valor do atributo é esperado para o endereço IP do cliente RADIUS, codificado como um int, que pode ser definido usando radius_put_addr().
`RADIUS_NAS_PORT` (int)
  O atributo "NAS-Port". O valor do atributo deve ser a porta física do usuário no cliente RADIUS, codificada como um int, que pode ser definido usando radius_put_int().
`RADIUS_SERVICE_TYPE` (int)
  O atributo "Service-Type". O valor do atributo indica o tipo de serviço que o usuário está solicitando e deve ser um int, que pode ser definido usando radius_put_int().

  Várias constantes são fornecidas para representar os valores possíveis deste atributo. Elas incluem:

  - `RADIUS_LOGIN`
  - `RADIUS_FRAMED`
  - `RADIUS_CALLBACK_LOGIN`
  - `RADIUS_CALLBACK_FRAMED`
  - `RADIUS_OUTBOUND`
  - `RADIUS_ADMINISTRATIVE`
  - `RADIUS_NAS_PROMPT`
  - `RADIUS_AUTHENTICATE_ONLY`
  - `RADIUS_CALLBACK_NAS_PROMPT`
`RADIUS_FRAMED_PROTOCOL` (int)

  O atributo "Framed-Protocol". O valor do atributo deve ser um int indicando o enquadramento a ser usado para acesso enquadrado e pode ser definido usando radius_put_int(). Os valores possíveis do atributo incluem estas constantes:

  - `RADIUS_PPP`
  - `RADIUS_SLIP`
  - `RADIUS_ARAP`
  - `RADIUS_GANDALF`
  - `RADIUS_XYLOGICS`
`RADIUS_FRAMED_IP_ADDRESS` (int)
  O atributo "Framed-IP-Address". O valor do atributo deve ser o endereço de rede do usuário codificado como um int, que pode ser definido usando radius_put_addr() e recuperado usando radius_cvt_addr().
`RADIUS_FRAMED_IP_NETMASK` (int)
  O atributo "Framed-IP-Netmask". O valor do atributo deve ser a máscara de rede da rede do usuário, codificada como um int, que pode ser definida usando radius_put_addr() e recuperada usando radius_cvt_addr().
`RADIUS_FRAMED_ROUTING` (int)
  O atributo "Framed-Routing". O valor do atributo deve ser um int indicando o método de roteamento para o usuário, que pode ser definido usando radius_put_int().

  Os valores possíveis incluem:

  - `0`: Sem roteamento
  - `1`: Enviar pacotes de roteamento
  - `2`: Escutar pacotes de roteamento
  - `3`: Enviar e escutar
`RADIUS_FILTER_ID` (int)
  O atributo "Filter-ID". O valor do atributo deve ser uma string de filtros específica da implementação e legível por humanos, que pode ser definida usando radius_put_attr().
`RADIUS_FRAMED_MTU` (int)
  O atributo "Framed-MTU". O valor do atributo deve ser um int indicando o MTU a ser configurado para o usuário, e pode ser definido usando radius_put_int().
`RADIUS_FRAMED_COMPRESSION` (int)

  O atributo "Framed-Compression". O valor do atributo deve ser um int indicando o protocolo de compressão a ser utilizado, e pode ser definido usando radius_put_int(). Os valores possíveis incluem estas constantes:

  - `RADIUS_COMP_NONE`: Sem compressão
  - `RADIUS_COMP_VJ`: Compressão de cabeçalho TCP/IP VJ
  - `RADIUS_COMP_IPXHDR`: Compressão de cabeçalho IPX
  - `RADIUS_COMP_STAC_LZS`: Compressão Stac-LZS (adicionada no raio PECL 1.3.0b2)
`RADIUS_LOGIN_IP_HOST` (int)
  O atributo "Login-IP-Host". O valor do atributo é esperado para o endereço IP ao qual o usuário se conectará, codificado como um int, que pode ser definido usando radius_put_addr().
`RADIUS_LOGIN_SERVICE` (int)
  O atributo "Login-Service". O valor do atributo é um int que indica o serviço ao qual o usuário se conectará no host de login. O valor pode ser convertido para um inteiro PHP via radius_cvt_int().
`RADIUS_LOGIN_TCP_PORT` (int)
  O atributo "Login-TCP-Port". O valor do atributo é um int que indica a porta para conectar o usuário no host de login. O valor pode ser convertido para um inteiro PHP via radius_cvt_int().
`RADIUS_REPLY_MESSAGE` (int)
  O atributo "Reply-Message". O valor do atributo é uma string contendo texto que pode ser exibido ao usuário em resposta a uma solicitação de acesso.
`RADIUS_CALLBACK_NUMBER` (int)
  O atributo "Callback-Number". O valor do atributo é uma string contendo a string de discagem a ser usada para o retorno de chamada.
`RADIUS_CALLBACK_ID` (int)
  O atributo "Callback-Id". O valor do atributo é uma string contendo um nome específico da implementação do local a ser chamado.
`RADIUS_FRAMED_ROUTE` (int)
  O atributo "Framed-Route". O valor do atributo é uma string contendo um conjunto de rotas específicas da implementação a serem configuradas para o usuário.
`RADIUS_FRAMED_IPX_NETWORK` (int)
  O atributo "Framed-IPX-Network". O valor do atributo é um int contendo a rede IPX a ser configurada para o usuário, ou `0xFFFFFFFE` para indicar que o cliente RADIUS deve selecionar a rede, e pode ser acessado via radius_cvt_int().
`RADIUS_STATE` (int)
  O atributo "State". O valor do atributo é uma string definida pela implementação, incluída em um Desafio de Acesso de um servidor que deve ser incluída na Solicitação de Acesso subsequente e pode ser definida usando radius_put_attr().
`RADIUS_CLASS` (int)
  O atributo "Class". O valor do atributo é uma string arbitrária incluída em uma mensagem Access-Accept que deve então ser enviada ao servidor de contabilidade em mensagens Accounting-Request, e pode ser definida usando radius_put_attr().
`RADIUS_VENDOR_SPECIFIC` (int)
  O atributo "Vendor-Specific". Em geral, os valores do atributo do fornecedor devem ser definidos usando radius_put_vendor_addr(), radius_put_vendor_attr(), radius_put_vendor_int() e radius_put_vendor_string(), em vez de diretamente. Esta constante é útil principalmente ao interpretar atributos específicos do fornecedor em respostas de um servidor RADIUS; quando um atributo específico do fornecedor é recebido, a função radius_get_vendor_attr() deve ser usada para acessar o ID do fornecedor, o tipo de atributo e o valor do atributo.
`RADIUS_SESSION_TIMEOUT` (int)
  Tempo limite da sessão
`RADIUS_IDLE_TIMEOUT` (int)
  Tempo limite de inatividade
`RADIUS_TERMINATION_ACTION` (int)
  Ação de terminação
`RADIUS_CALLED_STATION_ID` (int)
  ID da estação chamada
`RADIUS_CALLING_STATION_ID` (int)
  ID da estação que faz a chamada
`RADIUS_NAS_IDENTIFIER` (int)
  ID NAS
`RADIUS_PROXY_STATE` (int)
  Estado do proxy
`RADIUS_LOGIN_LAT_SERVICE` (int)
  Serviço de Login LAT
`RADIUS_LOGIN_LAT_NODE` (int)
  Nó de Login LAT
`RADIUS_LOGIN_LAT_GROUP` (int)
  Grupo de Login LAT
`RADIUS_FRAMED_APPLETALK_LINK` (int)
  Link de Framed Appletalk
`RADIUS_FRAMED_APPLETALK_NETWORK` (int)
  Rede de Framed Appletalk
`RADIUS_FRAMED_APPLETALK_ZONE` (int)
  Zona de Framed Appletalk
`RADIUS_CHAP_CHALLENGE` (int)
  Desafio
`RADIUS_NAS_PORT_TYPE` (int)

  Tipo de porta NAS, um dos seguintes:

  - `RADIUS_ASYNC`
  - `RADIUS_SYNC`
  - `RADIUS_ISDN_SYNC`
  - `RADIUS_ISDN_ASYNC_V120`
  - `RADIUS_ISDN_ASYNC_V110`
  - `RADIUS_VIRTUAL`
  - `RADIUS_PIAFS`
  - `RADIUS_HDLC_CLEAR_CHANNEL`
  - `RADIUS_X_25`
  - `RADIUS_X_75`
  - `RADIUS_G_3_FAX`
  - `RADIUS_SDSL`
  - `RADIUS_ADSL_CAP`
  - `RADIUS_ADSL_DMT`
  - `RADIUS_IDSL`
  - `RADIUS_ETHERNET`
  - `RADIUS_XDSL`
  - `RADIUS_CABLE`
  - `RADIUS_WIRELESS_OTHER`
  - `RADIUS_WIRELESS_IEEE_802_11`
`RADIUS_PORT_LIMIT` (int)
  Limite de porta
`RADIUS_LOGIN_LAT_PORT` (int)
  Porta de Login LAT
`RADIUS_CONNECT_INFO` (int)
  Informação de conexão
`RADIUS_ACCT_STATUS_TYPE` (int)

  Tipo de status contábil, um dos seguintes:

  - `RADIUS_START`
  - `RADIUS_STOP`
  - `RADIUS_ACCOUNTING_ON`
  - `RADIUS_ACCOUNTING_OFF`
`RADIUS_ACCT_DELAY_TIME` (int)
  Tempo de atraso contábil
`RADIUS_ACCT_INPUT_OCTETS` (int)
  Bytes de entrada contábil
`RADIUS_ACCT_OUTPUT_OCTETS` (int)
  Bytes de saída contábil
`RADIUS_ACCT_SESSION_ID` (int)
  ID da sessão contábil
`RADIUS_ACCT_AUTHENTIC` (int)

  Tipo de autenticação de contabilidade, uma das constantes:

  - `RADIUS_AUTH_RADIUS`
  - `RADIUS_AUTH_LOCAL`
  - `RADIUS_AUTH_REMOTE`
`RADIUS_ACCT_SESSION_TIME` (int)
  Tempo de sessão de contabilidade
`RADIUS_ACCT_INPUT_PACKETS` (int)
  Pacotes de entrada de contabilidade
`RADIUS_ACCT_OUTPUT_PACKETS` (int)
  Pacotes de saída de contabilidade
`RADIUS_ACCT_TERMINATE_CAUSE` (int)

  Causa de encerramento da contabilidade, uma das seguintes:

  - `RADIUS_TERM_USER_REQUEST`
  - `RADIUS_TERM_LOST_CARRIER`
  - `RADIUS_TERM_LOST_SERVICE`
  - `RADIUS_TERM_IDLE_TIMEOUT`
  - `RADIUS_TERM_SESSION_TIMEOUT`
  - `RADIUS_TERM_ADMIN_RESET`
  - `RADIUS_TERM_ADMIN_REBOOT`
  - `RADIUS_TERM_PORT_ERROR`
  - `RADIUS_TERM_NAS_ERROR`
  - `RADIUS_TERM_NAS_REQUEST`
  - `RADIUS_TERM_NAS_REBOOT`
  - `RADIUS_TERM_PORT_UNNEEDED`
  - `RADIUS_TERM_PORT_PREEMPTED`
  - `RADIUS_TERM_PORT_SUSPENDED`
  - `RADIUS_TERM_SERVICE_UNAVAILABLE`
  - `RADIUS_TERM_CALLBACK`
  - `RADIUS_TERM_USER_ERROR`
  - `RADIUS_TERM_HOST_REQUEST`
`RADIUS_ACCT_MULTI_SESSION_ID` (int)
  ID de multissessão de contabilidade
`RADIUS_ACCT_LINK_COUNT` (int)
  Contagem de conexões de contabilidade

Constantes de tipo de serviço
`RADIUS_LOGIN`
`RADIUS_FRAMED`
`RADIUS_CALLBACK_LOGIN`
`RADIUS_CALLBACK_FRAMED`
`RADIUS_OUTBOUND`
`RADIUS_ADMINISTRATIVE`
`RADIUS_NAS_PROMPT`
`RADIUS_AUTHENTICATE_ONLY`
`RADIUS_CALLBACK_NAS_PROMPT`

Constantes de Framed-Protocol
`RADIUS_PPP`
`RADIUS_SLIP`
`RADIUS_ARAP`
`RADIUS_GANDALF`
`RADIUS_XYLOGICS`

Constantes de Framed-Compression
`RADIUS_COMP_NONE`
`RADIUS_COMP_VJ`
`RADIUS_COMP_IPXHDR`
`RADIUS_COMP_STAC_LZS`

Constantes de Tipo de Porta NAS
`RADIUS_ASYNC`
`RADIUS_SYNC`
`RADIUS_ISDN_SYNC`
`RADIUS_ISDN_ASYNC_V120`
`RADIUS_ISDN_ASYNC_V110`
`RADIUS_VIRTUAL`
`RADIUS_PIAFS`
`RADIUS_HDLC_CLEAR_CHANNEL`
`RADIUS_X_25`
`RADIUS_X_75`
`RADIUS_G_3_FAX`
`RADIUS_SDSL`
`RADIUS_ADSL_CAP`
`RADIUS_ADSL_DMT`
`RADIUS_IDSL`
`RADIUS_ETHERNET`
`RADIUS_XDSL`
`RADIUS_CABLE`
`RADIUS_WIRELESS_OTHER`
`RADIUS_WIRELESS_IEEE_802_11`

Constantes de Tipo de Status de Contabilidade
`RADIUS_START`
`RADIUS_STOP`
`RADIUS_ACCOUNTING_ON`
`RADIUS_ACCOUNTING_OFF`

Constantes de Autenticação de Contabilidade
`RADIUS_AUTH_RADIUS`
`RADIUS_AUTH_LOCAL`
`RADIUS_AUTH_REMOTE`

Constantes de Causa de Término de Contabilidade
`RADIUS_TERM_USER_REQUEST`
`RADIUS_TERM_LOST_CARRIER`
`RADIUS_TERM_LOST_SERVICE`
`RADIUS_TERM_IDLE_TIMEOUT`
`RADIUS_TERM_SESSION_TIMEOUT`
`RADIUS_TERM_ADMIN_RESET`
`RADIUS_TERM_ADMIN_REBOOT`
`RADIUS_TERM_PORT_ERROR`
`RADIUS_TERM_NAS_ERROR`
`RADIUS_TERM_NAS_REQUEST`
`RADIUS_TERM_NAS_REBOOT`
`RADIUS_TERM_PORT_UNNEEDED`
`RADIUS_TERM_PORT_PREEMPTED`
`RADIUS_TERM_PORT_SUSPENDED`
`RADIUS_TERM_SERVICE_UNAVAILABLE`
`RADIUS_TERM_CALLBACK`
`RADIUS_TERM_USER_ERROR`
`RADIUS_TERM_HOST_REQUEST`

## Tipos de atributos RADIUS específicos do fornecedor

`RADIUS_VENDOR_MICROSOFT` (int)

  Atributos de fornecedores específicos da Microsoft (» RFC 2548), um dos seguintes:

  - `RADIUS_MICROSOFT_MS_CHAP_RESPONSE`
  - `RADIUS_MICROSOFT_MS_CHAP_ERROR`
  - `RADIUS_MICROSOFT_MS_CHAP_PW_1`
  - `RADIUS_MICROSOFT_MS_CHAP_PW_2`
  - `RADIUS_MICROSOFT_MS_CHAP_LM_ENC_PW`
  - `RADIUS_MICROSOFT_MS_CHAP_NT_ENC_PW`
  - `RADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY`
  - `RADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES`
  - `RADIUS_MICROSOFT_MS_RAS_VENDOR`
  - `RADIUS_MICROSOFT_MS_CHAP_DOMAIN`
  - `RADIUS_MICROSOFT_MS_CHAP_CHALLENGE`
  - `RADIUS_MICROSOFT_MS_CHAP_MPPE_KEYS`
  - `RADIUS_MICROSOFT_MS_BAP_USAGE`
  - `RADIUS_MICROSOFT_MS_LINK_UTILIZATION_THRESHOLD`
  - `RADIUS_MICROSOFT_MS_LINK_DROP_TIME_LIMIT`
  - `RADIUS_MICROSOFT_MS_MPPE_SEND_KEY`
  - `RADIUS_MICROSOFT_MS_MPPE_RECV_KEY`
  - `RADIUS_MICROSOFT_MS_RAS_VERSION`
  - `RADIUS_MICROSOFT_MS_OLD_ARAP_PASSWORD`
  - `RADIUS_MICROSOFT_MS_NEW_ARAP_PASSWORD`
  - `RADIUS_MICROSOFT_MS_ARAP_PASSWORD_CHANGE_REASON`
  - `RADIUS_MICROSOFT_MS_FILTER`
  - `RADIUS_MICROSOFT_MS_ACCT_AUTH_TYPE`
  - `RADIUS_MICROSOFT_MS_ACCT_EAP_TYPE`
  - `RADIUS_MICROSOFT_MS_CHAP2_RESPONSE`
  - `RADIUS_MICROSOFT_MS_CHAP2_SUCCESS`
  - `RADIUS_MICROSOFT_MS_CHAP2_PW`
  - `RADIUS_MICROSOFT_MS_PRIMARY_DNS_SERVER`
  - `RADIUS_MICROSOFT_MS_SECONDARY_DNS_SERVER`
  - `RADIUS_MICROSOFT_MS_PRIMARY_NBNS_SERVER`
  - `RADIUS_MICROSOFT_MS_SECONDARY_NBNS_SERVER`
  - `RADIUS_MICROSOFT_MS_ARAP_CHALLENGE`
`RADIUS_MICROSOFT_MS_CHAP_RESPONSE`
`RADIUS_MICROSOFT_MS_CHAP_ERROR`
`RADIUS_MICROSOFT_MS_CHAP_PW_1`
`RADIUS_MICROSOFT_MS_CHAP_PW_2`
`RADIUS_MICROSOFT_MS_CHAP_LM_ENC_PW`
`RADIUS_MICROSOFT_MS_CHAP_NT_ENC_PW`
`RADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY`
`RADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES`
`RADIUS_MICROSOFT_MS_RAS_VENDOR`
`RADIUS_MICROSOFT_MS_CHAP_DOMAIN`
`RADIUS_MICROSOFT_MS_CHAP_CHALLENGE`
`RADIUS_MICROSOFT_MS_CHAP_MPPE_KEYS`
`RADIUS_MICROSOFT_MS_BAP_USAGE`
`RADIUS_MICROSOFT_MS_LINK_UTILIZATION_THRESHOLD`
`RADIUS_MICROSOFT_MS_LINK_DROP_TIME_LIMIT`
`RADIUS_MICROSOFT_MS_MPPE_SEND_KEY`
`RADIUS_MICROSOFT_MS_MPPE_RECV_KEY`
`RADIUS_MICROSOFT_MS_RAS_VERSION`
`RADIUS_MICROSOFT_MS_OLD_ARAP_PASSWORD`
`RADIUS_MICROSOFT_MS_NEW_ARAP_PASSWORD`
`RADIUS_MICROSOFT_MS_ARAP_PASSWORD_CHANGE_REASON`
`RADIUS_MICROSOFT_MS_FILTER`
`RADIUS_MICROSOFT_MS_ACCT_AUTH_TYPE`
`RADIUS_MICROSOFT_MS_ACCT_EAP_TYPE`
`RADIUS_MICROSOFT_MS_CHAP2_RESPONSE`
`RADIUS_MICROSOFT_MS_CHAP2_SUCCESS`
`RADIUS_MICROSOFT_MS_CHAP2_PW`
`RADIUS_MICROSOFT_MS_PRIMARY_DNS_SERVER`
`RADIUS_MICROSOFT_MS_SECONDARY_DNS_SERVER`
`RADIUS_MICROSOFT_MS_PRIMARY_NBNS_SERVER`
`RADIUS_MICROSOFT_MS_SECONDARY_NBNS_SERVER`
`RADIUS_MICROSOFT_MS_ARAP_CHALLENGE`

# Exemplos

Como começar?

- obtenha um recurso radius
- configure a biblioteca
- cria a requisição
- informe os atributos
- envie a requisição
- receba os atributos
- feche o recurso radius (opcional)

Dê uma olhada também nos exemplos neste pacote.

O pacote contém um script PHP de exemplo. Este script demonstra como autenticar com o RADIUS usando PAP ou CHAP (md5). Se a autenticação for feita com servidores Microsoft Radius, não será possível usar CHAP (md5). Se a intenção for autenticar com servidores Microsoft, deverá ser usado MS-CHAPv1 ou MS-CHAPv2, mas é mais complicado, pois será necessário md4, sha1 e des para gerar os dados corretos. Os exemplos inclusos demonstram todos os métodos de autenticação, incluindo MS-CHAPv1 e MS-CHAPv2. Para que o MS-CHAP funcione, são necessárias as extensões mcrypt e mhash. A partir da versão 1.2 do pacote, a extensão mcrypt não é mais necessária.

# Funções de Radius

# radius_acct_open

(PECL radius >= 1.1.0)

radius_acct_open — Cria um identificador Radius para contabilidade

### Descrição

function radius_acct_open(): resource

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um identificador em caso de sucesso e `false` em caso de erro. Esta função só falha se não houver memória suficiente disponível.

### Exemplos

Exemplo #1 Exemplo de radius_acct_open()

    <?php
    $res = radius_acct_open ()
        or die ("Não foi possível criar o identificador");
    print "Identificador criado com sucesso";
    ?>

# radius_add_server

(PECL radius >= 1.1.0)

radius_add_server — Adiciona um servidor

### Descrição

function radius_add_server(
resource `$radius_handle`,
string `$hostname`,
int `$port`,
string `$secret`,
int `$timeout`,
int `$max_tries`
): bool

radius_add_server() pode ser chamada várias vezes e pode ser usada em conjunto com radius_config(). No máximo 10 servidores podem ser especificados. Quando vários servidores são fornecidos, eles são testados em rodízio até que uma resposta válida seja recebida ou até que o limite de `max_tries` de cada servidor seja atingido.

### Parâmetros

`radius_handle`
`hostname`
  O parâmetro `hostname` especifica o host do servidor, como um nome de domínio totalmente qualificado ou como um endereço IP de quatro números com pontos em formato de texto.
`port`

  O parâmetro `port` especifica a porta UDP a ser contatada no servidor. Se a porta for fornecida como 0, a biblioteca procura o serviço `radius/udp` ou `radacct/udp` no banco de dados de serviços de rede e usa a porta encontrada lá. Se nenhuma entrada for encontrada, a biblioteca usa as portas Radius padrão, 1812 para autenticação e 1813 para contabilidade.

`secret`
  O segredo compartilhado para o host do servidor é passado para o parâmetro `secret`. O protocolo Radius ignora todos, exceto os 128 bytes iniciais, do segredo compartilhado.
`timeout`
  O tempo limite para recebimento de respostas do servidor é passado para o parâmetro `timeout`, em unidades de segundos.
`max_tries`
  O número máximo de solicitações repetidas a serem feitas antes de desistir é passado para o `max_tries`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de radius_add_server()

    <?php
    if (!radius_add_server($res, 'radius.example.com', 1812, 'testing123', 3, 3)) {
        echo 'RadiusError:' . radius_strerror($res). "\n<br>";
        exit;
    }
    ?>

### Veja Também

- radius_config() - Faz com que a biblioteca leia o arquivo de configuração fornecido

# radius_auth_open

(PECL radius >= 1.1.0)

radius_auth_open — Cria um identificador Radius para autenticação

### Descrição

function radius_auth_open(): resource

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um identificador em caso de sucesso e `false` em caso de erro. Esta função só falha se não houver memória suficiente disponível.

### Exemplos

Exemplo #1 Exemplo de radius_auth_open()

    <?php
    $radh = radius_auth_open()
        or die ("Não foi possível criar o identificador");
    echo "Identificador criado com sucesso";
    ?>

# radius_close

(PECL radius >= 1.1.0)

radius_close — Libera todos os recursos

### Descrição

function radius_close(resource `$radius_handle`): bool

Não é necessário chamar esta função porque o PHP libera todos os recursos ao final de cada solicitação.

### Parâmetros

`radius_handle`
  O resource RADIUS.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# radius_config

(PECL radius >= 1.1.0)

radius_config — Faz com que a biblioteca leia o arquivo de configuração fornecido

### Descrição

function radius_config(resource `$radius_handle`, string `$file`): bool

Antes de emitir qualquer solicitação Radius, a biblioteca deve estar ciente dos servidores que pode contatar. A maneira mais fácil de configurar a biblioteca é chamar radius_config(). radius_config() faz com que a biblioteca leia um arquivo de configuração cujo formato é descrito em » radius.conf.

### Parâmetros

`radius_handle`
`file`
  O caminho do arquivo de configuração é passado como argumento de arquivo para radius_config(). A biblioteca também pode ser configurada programaticamente por meio de chamadas para radius_add_server().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- radius_add_server() - Adiciona um servidor

# radius_create_request

(PECL radius >= 1.1.0)

radius_create_request — Cria solicitação de contabilidade ou de autenticação

### Descrição

function radius_create_request(resource `$radius_handle`, int `$type`): bool

Uma requisição Radius consiste em um código que especifica o tipo de requisição e zero ou mais atributos que fornecem informações adicionais. Para começar a construir uma nova requisição, chame radius_create_request().

> Nota: Atenção: esta função deve ser chamada antes se inserir qualquer atributo!

### Parâmetros

`radius_handle`
`type`
  O tipo, `RADIUS_ACCESS_REQUEST` ou `RADIUS_ACCOUNTING_REQUEST`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de radius_create_request()

    <?php
    if (!radius_create_request($res, RADIUS_ACCESS_REQUEST)) {
        echo 'RadiusError:' . radius_strerror($res). "\n<br />";
        exit;
    }
    ?>

### Veja Também

- radius_send_request() - Envia a solicitação e aguarda uma resposta

# radius_cvt_addr

(PECL radius >= 1.1.0)

radius_cvt_addr — Converte dados brutos em endereço IP

### Descrição

function radius_cvt_addr(string `$data`): string

Converte dados brutos em endereço IP.

### Parâmetros

`data`
  Dados de entrada

### Valor Retornado

Retorna o endereço IP.

### Exemplos

Exemplo #1 Exemplo de radius_cvt_addr()

    <?php
    while ($resa = radius_get_attr($res)) {

        if (!is_array($resa)) {
            printf ("Erro ao obter atributo: %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];

        switch ($attr) {

        case RADIUS_FRAMED_IP_ADDRESS:
            $ip = radius_cvt_addr($data);
            echo "IP: $ip<br>\n";
            break;

        case RADIUS_FRAMED_IP_NETMASK:
            $mask = radius_cvt_addr($data);
            echo "MASK: $mask<br>\n";
            break;
        }
    }
    ?>

### Veja Também

- radius_cvt_int() - Converte dados brutos em número inteiro
- radius_cvt_string() - Converte dados brutos em string

# radius_cvt_int

(PECL radius >= 1.1.0)

radius_cvt_int — Converte dados brutos em número inteiro

### Descrição

function radius_cvt_int(string `$data`): int

Converte dados brutos em um número inteiro.

### Parâmetros

`data`
  Dados de entrada

### Valor Retornado

Retorna o inteiro, recuperado dos dados.

### Exemplos

Exemplo #1 Exemplo de radius_cvt_int()

    <?php
    while ($resa = radius_get_attr($res)) {

        if (!is_array($resa)) {
            printf ("Erro ao obter atributo: %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];

        switch ($attr) {

        case RADIUS_FRAMED_MTU:
            $mtu = radius_cvt_int($data);
            echo "MTU: $mtu<br>\n";
            break;
        }
    }
    ?>

### Veja Também

- radius_cvt_addr() - Converte dados brutos em endereço IP
- radius_cvt_string() - Converte dados brutos em string

# radius_cvt_string

(PECL radius >= 1.1.0)

radius_cvt_string — Converte dados brutos em string

### Descrição

function radius_cvt_string(string `$data`): string

Converte dados brutos em string.

### Parâmetros

`data`
  Dados de entrada

### Valor Retornado

Retorna a string recuperada dos dados.

### Exemplos

Exemplo #1 Exemplo de radius_cvt_string()

    <?php
    while ($resa = radius_get_attr($res)) {

        if (!is_array($resa)) {
            printf ("Erro ao obter atributo: %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];

        switch ($attr) {

        case RADIUS_FILTER_ID:
            $id = radius_cvt_string($data);
            echo "ID do filtro: $id<br>\n";
            break;
        }
    }
    ?>

### Veja Também

- radius_cvt_addr() - Converte dados brutos em endereço IP
- radius_cvt_int() - Converte dados brutos em número inteiro

# radius_demangle

(PECL radius >= 1.2.0)

radius_demangle — Descriptografa dados

### Descrição

function radius_demangle(resource `$radius_handle`, string `$mangled`): string

Alguns dados (senhas, chaves MPPE MS-CHAPv1) são criptografados por motivos de segurança e devem ser descriptografados antes que você possa usá-los.

### Parâmetros

`radius_handle`
  O resource RADIUS.
`mangled`
  Os dados a serem descriptografados.

### Valor Retornado

Retorna a string descriptografada ou `false` em caso de erro.

# radius_demangle_mppe_key

(PECL radius >= 1.2.0)

radius_demangle_mppe_key — Deriva chaves mppe de dados criptografados

### Descrição

function radius_demangle_mppe_key(resource `$radius_handle`, string `$mangled`): string

Ao usar MPPE com MS-CHAPv2, as chaves de envio e recebimento são criptografadas (consulte » RFC 2548). No entanto, esta função é não é útil, pois ainda não existe e não há planos para uma implementação PPTP-MPPE em PHP.

### Parâmetros

`radius_handle`
  O resource RADIUS.
`mangled`
  Os dados criptografados para serem descriptografados.

### Valor Retornado

Retorna os dados descriptografados ou `false` em caso de erro.

# radius_get_attr

(PECL radius >= 1.1.0)

radius_get_attr — Extrai um atributo

### Descrição

function radius_get_attr(resource `$radius_handle`): mixed

Assim como as requisições Radius, cada resposta pode conter zero ou mais atributos. Após uma resposta ser recebida com sucesso por radius_send_request(), seus atributos podem ser extraídos um por um usando radius_get_attr(). Cada vez que radius_get_attr() é chamada, ela obtém o próximo atributo da resposta atual.

### Parâmetros

`radius_handle`
  O resource RADIUS.

### Valor Retornado

Retorna um array associativo contendo o tipo de atributo e os dados, ou número de erro <= 0.

### Exemplos

Exemplo #1 Exemplo de radius_get_attr()

    <?php
    while ($resa = radius_get_attr($res)) {

        if (!is_array($resa)) {
            printf("Erro ao obter atributo: %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];
        printf("Obtido atributo:%d %d Bytes %s\n", $attr, strlen($data), bin2hex($data));
    }
    ?>

### Veja Também

- radius_put_attr() - Anexa um atributo binário
- radius_get_vendor_attr() - Extrai um atributo específico de fornecedor
- radius_put_vendor_attr() - Anexa um atributo binário específico de fornecedor
- radius_send_request() - Envia a solicitação e aguarda uma resposta

# radius_get_tagged_attr_data

(PECL radius >= 1.3.0)

radius_get_tagged_attr_data — Extrai os dados de um atributo marcado

### Descrição

function radius_get_tagged_attr_data(string `$data`): string|false

Se um atributo marcado foi retornado de radius_get_attr(), radius_get_tagged_attr_data() retornará os dados do atributo.

### Parâmetros

`data`
  O atributo marcado a ser decodificado.

### Valor Retornado

Retorna os dados do atributo marcado ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de radius_get_tagged_attr_data()

    <?php
    while ($resa = radius_get_attr($res)) {
        if (!is_array($resa)) {
            printf ("Erro ao obter atributo: %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];

        $tag = radius_get_tagged_attr_tag($data);
        $value = radius_get_tagged_attr_data($data);

        printf("Obtido atributo marcado com %d e valor %s\n", $tag, $value);
    }
    ?>

### Veja Também

- radius_get_attr() - Extrai um atributo
- radius_get_tagged_attr_tag() - Extrai a marcação de um atributo marcado

# radius_get_tagged_attr_tag

(PECL radius >= 1.3.0)

radius_get_tagged_attr_tag — Extrai a marcação de um atributo marcado

### Descrição

function radius_get_tagged_attr_tag(string `$data`): int|false

Se um atributo marcado foi retornado de radius_get_attr(), radius_get_tagged_attr_data() retornará a marcação do atributo.

### Parâmetros

`data`
  O atributo marcado a ser decodificado.

### Valor Retornado

Retorna a tag do atributo marcado ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de radius_get_tagged_attr_tag()

    <?php
    while ($resa = radius_get_attr($res)) {
        if (!is_array($resa)) {
            printf ("Erro ao obter atributo: %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];

        $tag = radius_get_tagged_attr_tag($data);
        $value = radius_get_tagged_attr_data($data);

        printf("Obtido atributo marcado com %d e valor %s\n", $tag, $value);
    }
    ?>

### Veja Também

- radius_get_attr() - Extrai um atributo
- radius_get_tagged_attr_data() - Extrai os dados de um atributo marcado

# radius_get_vendor_attr

(PECL radius >= 1.1.0)

radius_get_vendor_attr — Extrai um atributo específico de fornecedor

### Descrição

function radius_get_vendor_attr(string `$data`): array|false

Se radius_get_attr() retornar `RADIUS_VENDOR_SPECIFIC`, radius_get_vendor_attr() pode ser chamado para determinar o fornecedor.

### Parâmetros

`data`
  Dados de entrada

### Valor Retornado

Retorna um array associativo contendo o tipo de atributo, o fornecedor e os dados, ou `false` em caso de erro.

### Exemplos

Exemplo #1 Exemplo de radius_get_vendor_attr()

    <?php
    while ($resa = radius_get_attr($res)) {

        if (!is_array($resa)) {
            printf ("Erro ao obter atributo: %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];
        printf("Obtido atributo:%d %d Bytes %s\n", $attr, strlen($data), bin2hex($data));
        if ($attr == RADIUS_VENDOR_SPECIFIC) {

            $resv = radius_get_vendor_attr($data);
            if (is_array($resv)) {
                $vendor = $resv['vendor'];
                $attrv = $resv['attr'];
                $datav = $resv['data'];
                printf("Obtido atributo de fornecedor:%d %d Bytes %s\n", $attrv, strlen($datav), bin2hex($datav));
            }

        }
    }
    ?>

### Veja Também

- radius_get_attr() - Extrai um atributo
- radius_put_vendor_attr() - Anexa um atributo binário específico de fornecedor

# radius_put_addr

(PECL radius >= 1.1.0)

radius_put_addr — Anexa um atributo de endereço IP

### Descrição

function radius_put_addr(
resource `$radius_handle`,
int `$type`,
string `$addr`,
int `$options` = 0,
int `$tag` = ?
): bool

Anexa um atributo de endereço IP à solicitação RADIUS atual.

> Nota: Uma requisição deve ser criada por meio de radius_create_request() antes que esta função possa ser chamada.

### Parâmetros

`radius_handle`
  O resource RADIUS.
`type`
  O tipo de atributo.
`addr`
  Um endereço IPv4 em formato de string, como `10.0.0.1`.
`options`
  Uma máscara de bits das opções de atributo. As opções disponíveis incluem `RADIUS_OPTION_TAGGED` e `RADIUS_OPTION_SALT`.
`tag`
  A tag de atributo. Este parâmetro é ignorado, a menos que a opção `RADIUS_OPTION_TAGGED` esteja definida.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL radius 1.3.0 | Os parâmetros `options` e `tag` foram adicionados.

# radius_put_attr

(PECL radius >= 1.1.0)

radius_put_attr — Anexa um atributo binário

### Descrição

function radius_put_attr(
resource `$radius_handle`,
int `$type`,
string `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Anexa um atributo binário à solicitação RADIUS atual.

> Nota: Uma requisição deve ser criada por meio de radius_create_request() antes que esta função possa ser chamada.

### Parâmetros

`radius_handle`
  O resource RADIUS.
`type`
  O tipo de atributo.
`value`
  O valor do atributo, que será tratado como uma string binária bruta.
`options`
  Uma máscara de bits das opções de atributo. As opções disponíveis incluem `RADIUS_OPTION_TAGGED` e `RADIUS_OPTION_SALT`.
`tag`
  A tag de atributo. Este parâmetro é ignorado, a menos que a opção `RADIUS_OPTION_TAGGED` esteja definida.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL radius 1.3.0 | Os parâmetros `options` e `tag` foram adicionados.

### Exemplos

Exemplo #1 Exemplo de radius_put_attr()

    <?php
    mt_srand(time());
    $chall = mt_rand();
    $chapval = hash('md5', pack('Ca*',1 , 'sepp' . $chall));
    $pass = pack('CH*', 1, $chapval);
    if (!radius_put_attr($res, RADIUS_CHAP_PASSWORD, $pass)) {
        echo 'RadiusError:' . radius_strerror($res). "\n<br />";
        exit;
    }
    ?>

### Veja Também

- radius_get_attr() - Extrai um atributo
- radius_get_vendor_attr() - Extrai um atributo específico de fornecedor
- radius_put_vendor_attr() - Anexa um atributo binário específico de fornecedor

# radius_put_int

(PECL radius >= 1.1.0)

radius_put_int — Anexa um atributo de número inteiro

### Descrição

function radius_put_int(
resource `$radius_handle`,
int `$type`,
int `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Anexa um atributo de número inteiro à solicitação RADIUS atual.

> Nota: Uma requisição deve ser criada por meio de radius_create_request() antes que esta função possa ser chamada.

### Parâmetros

`radius_handle`
  O resource RADIUS.
`type`
  O tipo de atributo.
`value`
  O valor do atributo.
`options`
  Uma máscara de bits das opções de atributo. As opções disponíveis incluem `RADIUS_OPTION_TAGGED` e `RADIUS_OPTION_SALT`.
`tag`
  A tag de atributo. Este parâmetro é ignorado, a menos que a opção `RADIUS_OPTION_TAGGED` esteja definida.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL radius 1.3.0 | Os parâmetros `options` e `tag` foram adicionados.

### Exemplos

Exemplo #1 Exemplo de radius_put_int()

    <?php
    if (!radius_put_int($res, RAD_FRAMED_PROTOCOL, RAD_PPP)) {
       echo 'RadiusError:' . radius_strerror($res). "\n<br />";
       exit;
    }
    ?>

### Veja Também

- radius_put_string() - Anexa um atributo de string
- radius_put_vendor_int() - Anexa um atributo de número inteiro específico de fornecedor
- radius_put_vendor_string() - Anexa um atributo de string específico de fornecedor

# radius_put_string

(PECL radius >= 1.1.0)

radius_put_string — Anexa um atributo de string

### Descrição

function radius_put_string(
resource `$radius_handle`,
int `$type`,
string `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Anexa um atributo de string à requisição RADIUS atual. Em geral, radius_put_attr() é uma função mais útil para anexar atributos de string, pois é segura em termos binários.

> Nota: Uma requisição deve ser criada por meio de radius_create_request() antes que esta função possa ser chamada.

### Parâmetros

`radius_handle`
  O resource RADIUS.
`type`
  O tipo de atributo.
`value`
  O valor do atributo. A biblioteca subjacente espera que este valor seja terminado em nulo, portanto, este parâmetro não é seguro para binários.
`options`
  Uma máscara de bits das opções de atributo. As opções disponíveis incluem `RADIUS_OPTION_TAGGED` e `RADIUS_OPTION_SALT`.
`tag`
  A tag de atributo. Este parâmetro é ignorado, a menos que a opção `RADIUS_OPTION_TAGGED` esteja definida.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL radius 1.3.0 | Os parâmetros `options` e `tag` foram adicionados.

### Exemplos

Exemplo #1 Exemplo de radius_put_string()

    <?php
    if (!radius_put_string($res, RADIUS_USER_NAME, 'billy')) {
        echo 'RadiusError:' . radius_strerror($res). "\n<br />";
        exit;
    }
    ?>

### Veja Também

- radius_put_int() - Anexa um atributo de número inteiro
- radius_put_vendor_int() - Anexa um atributo de número inteiro específico de fornecedor
- radius_put_vendor_string() - Anexa um atributo de string específico de fornecedor

# radius_put_vendor_addr

(PECL radius >= 1.1.0)

radius_put_vendor_addr — Anexa um atributo de endereço IP específico de fornecedor

### Descrição

function radius_put_vendor_addr(
resource `$radius_handle`,
int `$vendor`,
int `$type`,
string `$addr`
): bool

Anexa um atributo específico de fornecedor de endereço IP à solicitação RADIUS atual.

> Nota: Uma requisição deve ser criada por meio de radius_create_request() antes que esta função possa ser chamada.

### Parâmetros

`radius_handle`
  O resource RADIUS.
`vendor`
  O ID do fornecedor.
`type`
  O tipo de atributo.
`addr`
  Um endereço IPv4 em formato de string, como `10.0.0.1`.
`options`
  Uma máscara de bits das opções de atributo. As opções disponíveis incluem `RADIUS_OPTION_TAGGED` e `RADIUS_OPTION_SALT`.
`tag`
  A tag de atributo. Este parâmetro é ignorado, a menos que a opção `RADIUS_OPTION_TAGGED` esteja definida.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL radius 1.3.0 | Os parâmetros `options` e `tag` foram adicionados.

# radius_put_vendor_attr

(PECL radius >= 1.1.0)

radius_put_vendor_attr — Anexa um atributo binário específico de fornecedor

### Descrição

function radius_put_vendor_attr(
resource `$radius_handle`,
int `$vendor`,
int `$type`,
string `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Anexa um atributo binário específico de fornecedor à solicitação RADIUS atual.

> Nota: Uma requisição deve ser criada por meio de radius_create_request() antes que esta função possa ser chamada.

### Parâmetros

`radius_handle`
  O resource RADIUS.
`vendor`
  O ID do fornecedor.
`type`
  O tipo de atributo.
`value`
  O valor do atributo, que será tratado como uma string binária bruta.
`options`
  Uma máscara de bits das opções de atributo. As opções disponíveis incluem `RADIUS_OPTION_TAGGED` e `RADIUS_OPTION_SALT`.
`tag`
  A tag de atributo. Este parâmetro é ignorado, a menos que a opção `RADIUS_OPTION_TAGGED` esteja definida.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL radius 1.3.0 | Os parâmetros `options` e `tag` foram adicionados.

### Exemplos

Exemplo #1 Exemplo de radius_put_vendor_attr()

    <?php
    if (!radius_put_vendor_attr($res, RADIUS_VENDOR_MICROSOFT, RAD_MICROSOFT_MS_CHAP_CHALLENGE, $challenge)) {
        echo 'RadiusError:' . radius_strerror($res). "\n<br />";
        exit;
    }
    ?>

### Veja Também

- radius_get_vendor_attr() - Extrai um atributo específico de fornecedor

# radius_put_vendor_int

(PECL radius >= 1.1.0)

radius_put_vendor_int — Anexa um atributo de número inteiro específico de fornecedor

### Descrição

function radius_put_vendor_int(
resource `$radius_handle`,
int `$vendor`,
int `$type`,
int `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Anexa um atributo de número inteiro específico de fornecedor à solicitação RADIUS atual.

> Nota: Uma requisição deve ser criada por meio de radius_create_request() antes que esta função possa ser chamada.

### Parâmetros

`radius_handle`
  O resource RADIUS.
`vendor`
  O ID do fornecedor.
`type`
  O tipo de atributo.
`value`
  O valor do atributo.
`options`
  Uma máscara de bits das opções de atributo. As opções disponíveis incluem `RADIUS_OPTION_TAGGED` e `RADIUS_OPTION_SALT`.
`tag`
  A tag de atributo. Este parâmetro é ignorado, a menos que a opção `RADIUS_OPTION_TAGGED` esteja definida.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL radius 1.3.0 | Os parâmetros `options` e `tag` foram adicionados.

### Veja Também

- radius_put_vendor_string() - Anexa um atributo de string específico de fornecedor

# radius_put_vendor_string

(PECL radius >= 1.1.0)

radius_put_vendor_string — Anexa um atributo de string específico de fornecedor

### Descrição

function radius_put_vendor_string(
resource `$radius_handle`,
int `$vendor`,
int `$type`,
string `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Anexa um atributo de string específico de fornecedor à solicitação RADIUS atual. Em geral, radius_put_vendor_attr() é uma função mais útil para anexar atributos de string, pois é seguro para binários.

> Nota: Uma requisição deve ser criada por meio de radius_create_request() antes que esta função possa ser chamada.

### Parâmetros

`radius_handle`
  O resource RADIUS.
`vendor`
  O ID do fornecedor.
`type`
  O tipo de atributo.
`value`
  O valor do atributo. A biblioteca subjacente espera que este valor seja terminado em nulo, portanto, este parâmetro não é seguro para binários.
`options`
  Uma máscara de bits das opções de atributo. As opções disponíveis incluem `RADIUS_OPTION_TAGGED` e `RADIUS_OPTION_SALT`.
`tag`
  A tag de atributo. Este parâmetro é ignorado, a menos que a opção `RADIUS_OPTION_TAGGED` esteja definida.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL radius 1.3.0 | Os parâmetros `options` e `tag` foram adicionados.

### Veja Também

- radius_put_vendor_int() - Anexa um atributo de número inteiro específico de fornecedor

# radius_request_authenticator

(PECL radius >= 1.1.0)

radius_request_authenticator — Retorna o autenticador de solicitação

### Descrição

function radius_request_authenticator(resource `$radius_handle`): string

O autenticador de solicitação é necessário para decodificar dados codificados, como senhas e chaves de criptografia.

### Parâmetros

`radius_handle`
  O resource RADIUS.

### Valor Retornado

Retorna o autenticador de solicitação como string ou `false` em caso de erro.

### Veja Também

- radius_demangle() - Descriptografa dados

# radius_salt_encrypt_attr

(PECL radius >= 1.3.0)

radius_salt_encrypt_attr — Criptografa um valor com salt

### Descrição

function radius_salt_encrypt_attr(resource `$radius_handle`, string `$data`): string|false

Aplica o algoritmo RADIUS de criptografia com salt ao valor fornecido.

Em geral, isso é conseguido automaticamente ao fornecer a opção `RADIUS_OPTION_SALT` a uma função definidora de atributos, mas essa função pode ser usada se a construção de uma solicitação de baixo nível for necessária.

### Parâmetros

`data`
  Os dados a serem criptografados com salt.

### Valor Retornado

Retorna os dados criptografados com salt ou `false` em caso de falha.

### Veja Também

- radius_put_addr() - Anexa um atributo de endereço IP
- radius_put_attr() - Anexa um atributo binário
- radius_put_int() - Anexa um atributo de número inteiro
- radius_put_string() - Anexa um atributo de string

# radius_send_request

(PECL radius >= 1.1.0)

radius_send_request — Envia a solicitação e aguarda uma resposta

### Descrição

function radius_send_request(resource `$radius_handle`): int

Após a solicitação Radius ser construída, ela é enviada por radius_send_request().

A função radius_send_request() envia a solicitação e aguarda uma resposta válida, repetindo as tentativas nos servidores definidos em rodízio conforme necessário.

### Parâmetros

`radius_handle`
  O resource RADIUS.

### Valor Retornado

Se uma resposta válida for recebida, radius_send_request() retorna o código Radius que especifica o tipo de resposta. Este será normalmente `RADIUS_ACCESS_ACCEPT`, `RADIUS_ACCESS_REJECT` ou `RADIUS_ACCESS_CHALLENGE`. Se nenhuma resposta válida for recebida, radius_send_request() retornará `false`.

### Veja Também

- radius_create_request() - Cria solicitação de contabilidade ou de autenticação

# radius_server_secret

(PECL radius >= 1.1.0)

radius_server_secret — Retorna o segredo compartilhado

### Descrição

function radius_server_secret(resource `$radius_handle`): string

O segredo compartilhado é necessário como salt para decodificar dados como senhas e chaves de criptografia.

### Parâmetros

`radius_handle`
  O resource RADIUS.

### Valor Retornado

Retorna o segredo compartilhado do servidor como string ou `false` em caso de erro.

# radius_strerror

(PECL radius >= 1.1.0)

radius_strerror — Retorna uma mensagem de erro

### Descrição

function radius_strerror(resource `$radius_handle`): string

Se as funções Radius falharem, elas registram uma mensagem de erro. Essa mensagem de erro pode ser recuperada com esta função.

### Parâmetros

`radius_handle`
  O resource RADIUS.

### Valor Retornado

Retorna mensagens de erro como string de funções Radius com falha.

## Índice

- radius_acct_open — Cria um identificador Radius para contabilidade
- radius_add_server — Adiciona um servidor
- radius_auth_open — Cria um identificador Radius para autenticação
- radius_close — Libera todos os recursos
- radius_config — Faz com que a biblioteca leia o arquivo de configuração fornecido
- radius_create_request — Cria solicitação de contabilidade ou de autenticação
- radius_cvt_addr — Converte dados brutos em endereço IP
- radius_cvt_int — Converte dados brutos em número inteiro
- radius_cvt_string — Converte dados brutos em string
- radius_demangle — Descriptografa dados
- radius_demangle_mppe_key — Deriva chaves mppe de dados criptografados
- radius_get_attr — Extrai um atributo
- radius_get_tagged_attr_data — Extrai os dados de um atributo marcado
- radius_get_tagged_attr_tag — Extrai a marcação de um atributo marcado
- radius_get_vendor_attr — Extrai um atributo específico de fornecedor
- radius_put_addr — Anexa um atributo de endereço IP
- radius_put_attr — Anexa um atributo binário
- radius_put_int — Anexa um atributo de número inteiro
- radius_put_string — Anexa um atributo de string
- radius_put_vendor_addr — Anexa um atributo de endereço IP específico de fornecedor
- radius_put_vendor_attr — Anexa um atributo binário específico de fornecedor
- radius_put_vendor_int — Anexa um atributo de número inteiro específico de fornecedor
- radius_put_vendor_string — Anexa um atributo de string específico de fornecedor
- radius_request_authenticator — Retorna o autenticador de solicitação
- radius_salt_encrypt_attr — Criptografa um valor com salt
- radius_send_request — Envia a solicitação e aguarda uma resposta
- radius_server_secret — Retorna o segredo compartilhado
- radius_strerror — Retorna uma mensagem de erro

- Instalação/Configuração
  - Instalação
- Constantes predefinidas
  - RADIUS Options
  - Tipos de pacotes RADIUS
  - Tipos de atributos RADIUS
  - Tipos de atributos RADIUS específicos do fornecedor
- Exemplos
- Funções de Radius
  - radius_acct_open — Cria um identificador Radius para contabilidade
  - radius_add_server — Adiciona um servidor
  - radius_auth_open — Cria um identificador Radius para autenticação
  - radius_close — Libera todos os recursos
  - radius_config — Faz com que a biblioteca leia o arquivo de configuração fornecido
  - radius_create_request — Cria solicitação de contabilidade ou de autenticação
  - radius_cvt_addr — Converte dados brutos em endereço IP
  - radius_cvt_int — Converte dados brutos em número inteiro
  - radius_cvt_string — Converte dados brutos em string
  - radius_demangle — Descriptografa dados
  - radius_demangle_mppe_key — Deriva chaves mppe de dados criptografados
  - radius_get_attr — Extrai um atributo
  - radius_get_tagged_attr_data — Extrai os dados de um atributo marcado
  - radius_get_tagged_attr_tag — Extrai a marcação de um atributo marcado
  - radius_get_vendor_attr — Extrai um atributo específico de fornecedor
  - radius_put_addr — Anexa um atributo de endereço IP
  - radius_put_attr — Anexa um atributo binário
  - radius_put_int — Anexa um atributo de número inteiro
  - radius_put_string — Anexa um atributo de string
  - radius_put_vendor_addr — Anexa um atributo de endereço IP específico de fornecedor
  - radius_put_vendor_attr — Anexa um atributo binário específico de fornecedor
  - radius_put_vendor_int — Anexa um atributo de número inteiro específico de fornecedor
  - radius_put_vendor_string — Anexa um atributo de string específico de fornecedor
  - radius_request_authenticator — Retorna o autenticador de solicitação
  - radius_salt_encrypt_attr — Criptografa um valor com salt
  - radius_send_request — Envia a solicitação e aguarda uma resposta
  - radius_server_secret — Retorna o segredo compartilhado
  - radius_strerror — Retorna uma mensagem de erro

- Radius
  - Instalação/Configuração
  - Constantes predefinidas
  - Exemplos
  - Funções de Radius

# Extensões Específicas para Linha de Comando

# Readline GNU

# Introdução

As funções readline implementam uma interface para a biblioteca Readline GNU. Estas são funções que fornecem linhas de comando editáveis. Um exeplo é a maneira que o Bash permite usar as teclas de setas para inserir caracteres ou navegar pelo histórico dos comandos. Por causa da naturesa interativa desta biblioteca, ela será de pouco uso para escrever aplicações Web, mas pode ser util ao escrever scripts usados a partir de uma linha de comando.

A partir do PHP 7.1.0 esta extensão é suportada no Windows.

Cuidado

A extensão readline não é segura para threads! Portanto, o uso dela com qualquer SAPI verdadeiramente segura para threads (como mod_winnt do Apache) é fortemente desencorajado.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução

## Dependências

Para usar as funções readline, é necessário instalar o libreadlinem que pode ser encontrado na página inicial do projeto Readline GNU, em » https://tiswww.case.edu/php/chet/readline/rltop.html. É mantido por Chet Ramey, que também é autor do Bash.

Essas funções também podem ser usadas com a biblioteca libedit, uma substituição não-GPL para a biblioteca readline. A biblioteca libedit é licenciada por BSD e está disponível para download em » http://www.thrysoee.dk/editline/.

## Instalação

Para usar estas funções, as versões CGI ou CLI do PHP devem ser compiladas com suporte a readline. É necessário configurar o PHP com a opção --with-readline[=DIR]. Se a intenção for usar a biblioteca substituta libedit, o PHP deve ser configurado com --with-libedit[=DIR].

No Windows, esta extensão está disponível por padrão a partir do PHP 7.1.0.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de Configuração de Readline
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
cli.pager | "" | `INI_ALL` |
cli.prompt | "\\b \\> " | `INI_ALL` |

Aqui está uma breve explicação das diretivas de configuração.

`cli.pager` string
  Ferramenta externa para mostrar a saída da linha de comando.
`cli.prompt` string
  Prompt da linha de comando.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`READLINE_LIB` (string)
  A biblioteca usada para suporte ao Readline; atualmente pode ser `readline` ou `libedit`.

# Funções da extensão Readline

# readline

(PHP 4, PHP 5, PHP 7, PHP 8)

readline — Lê uma linha

### Descrição

function readline(?string `$prompt` = `null`): string|false

Lê uma única linha do usuário. Esta linha precisa ser adicionada manualmente ao histórico usando readline_add_history().

### Parâmetros

`prompt`
  Pode-se especificar uma string que será o prompt para o usuário.

### Valor Retornado

Retorna uma string do usuário. A linha retornada tem o caractere de nova linha removido do final. Se não houver mais dados para ler, então `false` é retornado.

### Exemplos

Exemplo #1 readline()

    <?php
    // Obtém três comandos do usuário
    for ($i=0; $i < 3; $i++) {
            $line = readline("Command: ");
            readline_add_history($line);
    }

    // Mostra o histórico
    print_r(readline_list_history());

    // Mostra as variáveis
    print_r(readline_info());
    ?>

# readline_add_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_add_history — Adiciona uma linha ao histórico

### Descrição

function readline_add_history(string `$prompt`): true

Esta função adiciona uma linha ao histórico da linha de comando.

### Parâmetros

`prompt`
  A linha a ser adicionada ao histórico.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | O tipo do retorno agora é `true`; anteriormente, era bool.

# readline_callback_handler_install

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_handler_install — Inicializa a interface de chamada de retorno e o terminal de readline, mostra o prompt e retorna imediatamente

### Descrição

function readline_callback_handler_install(string `$prompt`, callable `$callback`): true

Configura uma interface de chamada de retorno readline, mostra o `prompt` e retorna imediatamente. Chamar esta função duas vezes sem remover a interface de chamada anterior irá automaticamente e convenientemente sobrescrever a interface antiga.

O recurso de chamada de retorno é útil quando combinada com stream_select() já que permite as it allows intercalação de E/S e de entrada de usuário, diferentemente da função readline().

### Parâmetros

`prompt`
  A mensagem do prompt.
`callback`
  A função definida em `callback` leva um parâmetro; a entrada do usuário retornada.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | O tipo do retorno agora é `true`; anteriormente, era bool.

### Exemplos

Exemplo #1 Exemplo de Interface de Chamada de Retorno de Readline

    <?php
    function rl_callback($ret)
    {
        global $c, $prompting;

        echo "Você digitou: $ret\n";
        $c++;

        if ($c > 10) {
            $prompting = false;
            readline_callback_handler_remove();
        } else {
            readline_callback_handler_install("[$c] Digite algo: ", 'rl_callback');
        }
    }

    $c = 1;
    $prompting = true;

    readline_callback_handler_install("[$c] Digite algo: ", 'rl_callback');

    while ($prompting) {
        $w = NULL;
        $e = NULL;
        $n = stream_select($r = array(STDIN), $w, $e, null);
        if ($n && in_array(STDIN, $r)) {
            // lê um caractere, irá chamar a função de retorno quando uma nova linha for lida
            readline_callback_read_char();
        }
    }

    echo "Prompt desabilitado. Tudo pronto.\n";
    ?>

### Veja Também

- readline_callback_handler_remove() - Remove um manipulador de chamada de retorno previamente instalado e restaura a configuração do terminal
- readline_callback_read_char() - Lê um caractere e informa a interface de chamada de retorno de readline quando uma linha é recebida
- stream_select() - Executa o equivalente à chamada de sistema select() nos arrays de fluxos informados com um limite de tempo especificado por segundos e microssegundos

# readline_callback_handler_remove

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_handler_remove — Remove um manipulador de chamada de retorno previamente instalado e restaura a configuração do terminal

### Descrição

function readline_callback_handler_remove(): bool

Remove um manipulador de chamada de retorno previamente instalado e restaura a configuração do terminal.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se o manipulador de chamada de retorno previamente instalado for removido, ou `false` se ele não puder ser encontrado.

### Exemplos

Consulte readline_callback_handler_install() para um exemplo de como usar a interface de chamada de retorno de readline.

### Veja Também

- readline_callback_handler_install() - Inicializa a interface de chamada de retorno e o terminal de readline, mostra o prompt e retorna imediatamente
- readline_callback_read_char() - Lê um caractere e informa a interface de chamada de retorno de readline quando uma linha é recebida

# readline_callback_read_char

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_read_char — Lê um caractere e informa a interface de chamada de retorno de readline quando uma linha é recebida

### Descrição

function readline_callback_read_char(): void

Lê um caractere de entrada do usuário. Quando uma linha é recebida, esta função informa a interface de chamada de retorno de readline, instalada usando readline_callback_handler_install(), que uma linha está pronta para entrada.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Consulte readline_callback_handler_install() para um exemplo de como usar a interface de chamada de retorno de readline.

### Veja Também

- readline_callback_handler_install() - Inicializa a interface de chamada de retorno e o terminal de readline, mostra o prompt e retorna imediatamente
- readline_callback_handler_remove() - Remove um manipulador de chamada de retorno previamente instalado e restaura a configuração do terminal

# readline_clear_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_clear_history — Limpa o histórico

### Descrição

function readline_clear_history(): true

Esta função limpa todo o histórico da linha de comando.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | O tipo do retorno agora é `true`; anteriormente, era bool.

# readline_completion_function

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_completion_function — Registra uma função de completamento

### Descrição

function readline_completion_function(callable `$callback`): bool

Esta função registra uma função de completamento. Este é o mesmo tipo de funcionamento ao pressionar a tecla de tabulação enquanto estiver usando o Bash.

### Parâmetros

`callback`
  Deve-se usar o nome de uma função existente que aceite uma linha de comando parcial e retorne um array de combinações possíveis.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# readline_info

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_info — Obtém/Define várias variáveis internas de readline

### Descrição

function readline_info(?string `$var_name` = `null`, int|string|bool|null `$value` = `null`): mixed

Obtém ou define várias variáveis internas da readline.

### Parâmetros

`var_name`
  Um nome de variável.
`value`
  Se fornecido, este será o novo valor.

### Valor Retornado

Se for utilizada sem parâmetros, esta função retorna um array de valores para as configurações que a readline usa. Os elementos serão indexados pelos seguintes valores: `done`, `end`, `erase_empty_line`, `library_version`, `line_buffer`, `mark`, `pending_input`, `point`, `prompt`, `readline_name`, e `terminal_name`. O array conterá apenas os elementos suportados pela biblioteca usada para construir a extensão readline.

Se for utilizada com um ou dois parâmetros, o antigo valor é retornado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `var_name` e `value` agora são anuláveis.

# readline_list_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_list_history — Lista o histórico

### Descrição

function readline_list_history(): array

Obtém o histório completo da linha de comando.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array do histórico completo da linha de comando. Os elementos são indexados por inteiros iniciando de zero.

# readline_on_new_line

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_on_new_line — Informa à readline que o cursor se moveu para uma nova linha

### Descrição

function readline_on_new_line(): void

Informa à readline que o cursor se moveu para uma nova linha.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

### Notas

> Nota: Esta função somente está disponível se suportada pela biblioteca readline subjacente. Não é suportada no Windows.

# readline_read_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_read_history — Lê o histórico

### Descrição

function readline_read_history(?string `$filename` = `null`): bool

Esta função lê o histórico de comandos de um arquivo.

### Parâmetros

`filename`
  Caminho para o nome do arquivo contendo o histórico de comando.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `filename` é anulável agora.

# readline_redisplay

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_redisplay — Redesenha a tela

### Descrição

function readline_redisplay(): void

Redesenha readline para atualizar a tela.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

# readline_write_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_write_history — Grava o histórico

### Descrição

function readline_write_history(?string `$filename` = `null`): bool

Esta função escreve o histórico dos comandos em um arquivo.

### Parâmetros

`filename`
  Caminho para salvar o arquivo.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `filename` é anulável agora.

## Índice

- readline — Lê uma linha
- readline_add_history — Adiciona uma linha ao histórico
- readline_callback_handler_install — Inicializa a interface de chamada de retorno e o terminal de readline, mostra o prompt e retorna imediatamente
- readline_callback_handler_remove — Remove um manipulador de chamada de retorno previamente instalado e restaura a configuração do terminal
- readline_callback_read_char — Lê um caractere e informa a interface de chamada de retorno de readline quando uma linha é recebida
- readline_clear_history — Limpa o histórico
- readline_completion_function — Registra uma função de completamento
- readline_info — Obtém/Define várias variáveis internas de readline
- readline_list_history — Lista o histórico
- readline_on_new_line — Informa à readline que o cursor se moveu para uma nova linha
- readline_read_history — Lê o histórico
- readline_redisplay — Redesenha a tela
- readline_write_history — Grava o histórico

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
- Constantes predefinidas
- Funções da extensão Readline
  - readline — Lê uma linha
  - readline_add_history — Adiciona uma linha ao histórico
  - readline_callback_handler_install — Inicializa a interface de chamada de retorno e o terminal de readline, mostra o prompt e retorna imediatamente
  - readline_callback_handler_remove — Remove um manipulador de chamada de retorno previamente instalado e restaura a configuração do terminal
  - readline_callback_read_char — Lê um caractere e informa a interface de chamada de retorno de readline quando uma linha é recebida
  - readline_clear_history — Limpa o histórico
  - readline_completion_function — Registra uma função de completamento
  - readline_info — Obtém/Define várias variáveis internas de readline
  - readline_list_history — Lista o histórico
  - readline_on_new_line — Informa à readline que o cursor se moveu para uma nova linha
  - readline_read_history — Lê o histórico
  - readline_redisplay — Redesenha a tela
  - readline_write_history — Grava o histórico

- Readline — Readline GNU
  - Instalação/Configuração
  - Constantes predefinidas
  - Funções da extensão Readline

# Extensões de Arquivo e Compressão

# Bzip2

# Introdução

As funções para bzip2 são usadas para ler e escrever, de forma transparente, arquivos compactados do tipo bzip2 (.bz2).

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Tipos de Recurso

## Dependências

Este módulo utiliza as funções da biblioteca » bzip2 desenvolvida por Julian Seward. Este módulo requer bzip2/libbzip2 versão >= 1.0.x.

## Instalação

O suporte a Bzip2 no PHP não está habilitado por padrão. A opção de configuração --with-bz2[=DIR] precisará ser usada ao compilar o PHP para habilitar o suporte a bzip2.

## Tipos de Recurso

Esta extensão define um tipo de recurso (resource): um ponteiro para arquivo que identifica o arquivo bzip2 que está sendo usado.

# Exemplos

Este exemplo abre um arquivo temporário e escreve uma string de teste nele, e então mostra o conteúdo do arquivo.

Exemplo #1 Um exemplo simples de bzip2

    <?php

    $filename = "/tmp/testfile.bz2";
    $str = "Este é um texto de teste.\n";

    // abre o arquivo para escrita
    $bz = bzopen($filename, "w");

    // escreve string no arquivo
    bzwrite($bz, $str);

    // fecha o arquivo
    bzclose($bz);

    // abre o arquivo para leitura
    $bz = bzopen($filename, "r");

    // lê 10 caracteres
    echo bzread($bz, 10);

    // exibe até o final do arquivo (ou os próximos 1024 caracteres) e o fecha.
    echo bzread($bz);

    bzclose($bz);

    ?>

# Bzip2 Funções

# bzclose

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzclose — Fecha um ponteiro de arquivo bzip2

### Descrição

function bzclose(resource `$bz`): bool

Fecha o dado ponteiro de arquivo bzip2.

### Parâmetros

`bz`
  O ponteiro de arquivo. Ele precisa ser válido e precisa apontar para um arquivo devidamente aberto com sucesso por bzopen().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- bzopen() - Abre um arquivo comprimido com bzip2

# bzcompress

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzcompress — Comprime uma string em dados codificados com bzip2

### Descrição

function bzcompress(string `$data`, int `$block_size` = 4, int `$work_factor` = 0): string|int

bzcompress() comprime a string fornecida e retorna-a como dados codificados com bzip2.

### Parâmetros

`data`
  A string a comprimir.
`block_size`
  Especifica o tamanho de bloco usado durante a compressão e deve ser um número de 1 a 9, sendo 9 a melhor compressão mas usando mais recursos para fazê-la.
`work_factor`
  Controla como a fase de compressão se comporta quando apresentada com o pior caso, dados de entrada altamente repetitivos. O valor pode ser entre 0 e 250, sendo 0 um caso especial. Independente do parâmetro `work_factor`, a saída gerada é a mesma.

### Valor Retornado

A string comprimida, ou um número de erro se um erro ocorrer.

### Exemplos

Exemplo #1 Comprimindo dados

    <?php
    $str = "dado de exemplo";
    $bzstr = bzcompress($str, 9);
    echo $bzstr;
    ?>

### Veja Também

- bzdecompress() - Descomprime dados codificados com bzip2

# bzdecompress

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzdecompress — Descomprime dados codificados com bzip2

### Descrição

function bzdecompress(string `$data`, bool `$use_less_memory` = `false`): string|int|false

bzdecompress() descomprime a string fornecida que contém dados codificados com bzip2.

### Parâmetros

`data`
  A string a ser descomprimida.
`use_less_memory`
  Se `true`, uma algoritmo alternativo de descompressão que usa menos memória será usado (o requisito máximo de memória baixa para um valor em torno de 2300K) mas trabalha com a metade da velocidade aproximadamente. Consulte a » documentação bzip2 para mais informações sobre este recurso.

### Valor Retornado

A string descomprimida, ou `false` ou um número de erro se um erro ocorrer.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O tipo do parâmetro `use_less_memory` mudou de int para bool. Anteriormente, o valor padrão era `0`.

### Exemplos

Exemplo #1 Descomprimindo uma String

    <?php
    $start_str = "O rato roeu a roupa do rei de Roma.";
    $bzstr = bzcompress($start_str);

    echo "String Comprimida: ";
    echo $bzstr;
    echo "\n<br />\n";

    $str = bzdecompress($bzstr);
    echo "String Descomprimida: ";
    echo $str;
    echo "\n<br />\n";
    ?>

### Veja Também

- bzcompress() - Comprime uma string em dados codificados com bzip2

# bzerrno

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerrno — Retorna um número de erro da bzip2

### Descrição

function bzerrno(resource `$bz`): int

Retorna o número do erro de qualquer erro da bzip2 retornado pelo ponteiro de arquivo fornecido.

### Parâmetros

`bz`
  O ponteiro do arquivo. Deve ser válido e apontar para um arquivo aberto com sucesso por bzopen().

### Valor Retornado

Retorna o número do erro como um número inteiro.

### Veja Também

- bzerror() - Retorna o número e string de erro do bzip2 em um array
- bzerrstr() - Retorna a string de erro do bzip2

# bzerror

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerror — Retorna o número e string de erro do bzip2 em um array

### Descrição

function bzerror(resource `$bz`): array

Retorna o número e string do erro de um erro da bzip2 retornado pelo dado ponteiro de arquivo.

### Parâmetros

`bz`
  O ponteiro do arquivo - Ele precisa ser válido e precisa apontar para um arquivo aberto com sucesso pela bzopen().

### Valor Retornado

Retorna um array associativo, com o código de erro na entrada `errno`, e a mensagem de erro na entrada `errstr`.

### Exemplos

Exemplo #1 Exemplo da bzerror()

    <?php
    $error = bzerror($bz);

    echo $error["errno"];
    echo $error["errstr"];
    ?>

### Veja Também

- bzerrno() - Retorna um número de erro da bzip2
- bzerrstr() - Retorna a string de erro do bzip2

# bzerrstr

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerrstr — Retorna a string de erro do bzip2

### Descrição

function bzerrstr(resource `$bz`): string

Obtém a string de erro de um erro da bzip2 retornado para um dado ponteiro de arquivo.

### Parâmetros

`bz`
  O ponteiro do arquivo. Ele precisa ser válido e precisa apontar para um arquivo aberto com sucesso pela bzopen().

### Valor Retornado

Retorna uma string contendo a mensagem de erro.

### Veja Também

- bzerrno() - Retorna um número de erro da bzip2
- bzerror() - Retorna o número e string de erro do bzip2 em um array

# bzflush

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzflush — Sem efeitos

### Descrição

function bzflush(resource `$bz`): bool

Força a escrita de todos os dados do bzip2 que estão em buffer para o ponteiro de arquivo `bz`, mas é implementado como uma função vazia na libbz2, e portanto não gera efeitos.

### Parâmetros

`bz`
  O ponteiro do arquivo. Ele precisa ser válido e precisa apontar para um arquivo aberto com sucesso por bzopen().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- bzread() - Leitura binária segura de arquivo bzip2
- bzwrite() - Gravação binária segura em arquivo bzip2

# bzopen

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzopen — Abre um arquivo comprimido com bzip2

### Descrição

function bzopen(string|resource `$file`, string `$mode`): resource|false

bzopen() abre um arquivo bzip2 (.bz2) para leitura ou gravação.

### Parâmetros

`file`
  O nome do arquivo a abrir, ou um recurso de fluxo existente.
`mode`
  Os modos `'r'` (leitura), e `'w'` (gravação) são suportados. Qualquer outro valor fará com que bzopen() retorne `false`.

### Valor Retornado

Se a abertura falhar, bzopen() retorna `false`, caso contrário retorna um ponteiro para o arquivo aberto.

### Exemplos

Exemplo #1 Exemplo de bzopen()

    <?php

    $file = "/tmp/foo.bz2";
    $bz = bzopen($file, "r") or die("Não foi possível abrir $file para leitura");

    bzclose($bz);

    ?>

### Veja Também

- bzclose() - Fecha um ponteiro de arquivo bzip2

# bzread

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzread — Leitura binária segura de arquivo bzip2

### Descrição

function bzread(resource `$bz`, int `$length` = 1024): string|false

bzread() faz leitura de um ponteiro de arquivo bzip2 fornecido.

A leitura para quando o número de bytes (não comprimidos) informado em `length` tiver sido alcançado ou o final do arquivo, o que ocorrer primeiro.

### Parâmetros

`bz`
  O ponteiro do arquivo. Precisa ser válido e apontar para um arquivo aberto com sucesso pela função bzopen().
`length`
  Se não especificado, a função bzread() lerá 1024 bytes (não comprimidos) de cada vez. Um máximo de 8192 bytes não comprimidos será lido de cada vez.

### Valor Retornado

Retorna os dados descomprimidos, ou `false` em caso de erro.

### Exemplos

Exemplo #1 Exemplo de bzread()

    <?php

    $file = "/tmp/foo.bz2";
    $bz = bzopen($file, "r") or die("Não foi possível abrir $file");

    $decompressed_file = '';
    while (!feof($bz)) {
        $decompressed_file .= bzread($bz, 4096);
    }
    bzclose($bz);

    echo "O conteúdo de $file é: <br />\n";
    echo $decompressed_file;

    ?>

### Veja Também

- bzwrite() - Gravação binária segura em arquivo bzip2
- feof() - Testa pelo fim-de-arquivo em um ponteiro de arquivo
- bzopen() - Abre um arquivo comprimido com bzip2

# bzwrite

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzwrite — Gravação binária segura em arquivo bzip2

### Descrição

function bzwrite(resource `$bz`, string `$data`, ?int `$length` = `null`): int|false

bzwrite() escreve uma string no arquivo bzip2 informado.

### Parâmetros

`bz`
  O ponteiro do arquivo. Precisa ser válido e apontar a um arquivo aberto com sucesso por bzopen().
`data`
  Os dados gravados.
`length`
  Se fornecido, a gravação irá parar depois que os bytes (não comprimidos) informados em `length` tiverem sido escritos ou o final de `data` tiver sido alcançado, o que ocorrer primeiro.

### Valor Retornado

Retorna o número de bytes gravados, ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `length` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo de bzwrite()

    <?php
    $str = "dados descomprimidos";
    $bz = bzopen("/tmp/foo.bz2", "w");
    bzwrite($bz, $str, strlen($str));
    bzclose($bz);
    ?>

### Veja Também

- bzread() - Leitura binária segura de arquivo bzip2
- bzopen() - Abre um arquivo comprimido com bzip2

## Índice

- bzclose — Fecha um ponteiro de arquivo bzip2
- bzcompress — Comprime uma string em dados codificados com bzip2
- bzdecompress — Descomprime dados codificados com bzip2
- bzerrno — Retorna um número de erro da bzip2
- bzerror — Retorna o número e string de erro do bzip2 em um array
- bzerrstr — Retorna a string de erro do bzip2
- bzflush — Sem efeitos
- bzopen — Abre um arquivo comprimido com bzip2
- bzread — Leitura binária segura de arquivo bzip2
- bzwrite — Gravação binária segura em arquivo bzip2

- Instalação/Configuração
  - Dependências
  - Instalação
  - Tipos de Recurso
- Exemplos
- Bzip2 Funções
  - bzclose — Fecha um ponteiro de arquivo bzip2
  - bzcompress — Comprime uma string em dados codificados com bzip2
  - bzdecompress — Descomprime dados codificados com bzip2
  - bzerrno — Retorna um número de erro da bzip2
  - bzerror — Retorna o número e string de erro do bzip2 em um array
  - bzerrstr — Retorna a string de erro do bzip2
  - bzflush — Sem efeitos
  - bzopen — Abre um arquivo comprimido com bzip2
  - bzread — Leitura binária segura de arquivo bzip2
  - bzwrite — Gravação binária segura em arquivo bzip2

# LZF

# Introdução

LZF é um algoritmo de compressão muito rápido, ideal para economizar espaço com um pequeno custo de velocidade. Ele pode ser otimizado para velocidade ou espaço em tempo de compilação. Esta extensão usa para suas operações a biblioteca » liblzf de Marc Lehmann.

# Instalação/Configuração

## Índice

- Instalação

## Instalação

Esta extensão » PECL não é distribuída com o PHP. Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/lzf.

Para usar estas funções você precisa compilar PHP com suporte a lzf usando a opção de configuração --with-lzf[=DIR]. Você pode também passar --enable-lzf-better-compression para otimizar o LZF mais para espaço do que para velocidade.

Usuários Windows podem habilitar a php_lzf.dll no php.ini para usar estas funções.

# Funções da LZF

# lzf_compress

(PECL lzf >= 0.1.0)

lzf_compress — Compressão LZF

### Descrição

function lzf_compress(string `$data`): string

lzf_compress() comprime a string `data` usando a codificação LZF.

### Parâmetros

`data`
  Retorna a string comprimida.

### Valor Retornado

Retorna a informação comprimida ou `false` se um erro ocorreu.

### Veja Também

- lzf_decompress() - Descompressão LZF

# lzf_decompress

(PECL lzf >= 0.1.0)

lzf_decompress — Descompressão LZF

### Descrição

function lzf_decompress(string `$data`): string

lzf_compress() descomprime a string informada em `data` que contém dados com codificação lzf.

### Parâmetros

`data`
  A string comprimida.

### Valor Retornado

Retorna a informação descomprimida ou `false` se um erro ocorreu.

### Veja Também

- lzf_compress() - Compressão LZF

# lzf_optimized_for

(PECL lzf >= 1.0.0)

lzf_optimized_for — Determina para quê a extensão LZF foi otimizada

### Descrição

function lzf_optimized_for(): int

Determina para quê a extensão LZF foi otimizada durante a compilação.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna 1 se LZF foi otimizada para velocidade, 0 para compressão.

## Índice

- lzf_compress — Compressão LZF
- lzf_decompress — Descompressão LZF
- lzf_optimized_for — Determina para quê a extensão LZF foi otimizada

- Instalação/Configuração
  - Instalação
- Funções da LZF
  - lzf_compress — Compressão LZF
  - lzf_decompress — Descompressão LZF
  - lzf_optimized_for — Determina para quê a extensão LZF foi otimizada

# Phar

# Introdução

A extensão phar fornece uma maneira de colocar aplicações PHP inteiras em um único arquivo chamado "phar" (Arquivo PHP) para fácil distribuição e instalação. Além de fornecer este serviço, a extensão phar também fornece um método de abstração de formato de arquivo para criar e manipular arquivos tar e zip através da classe PharData, assim como o PDO fornece uma interface unificada para acessar diferentes bancos de dados. Ao contrário do PDO, que não pode converter entre bancos de dados diferentes, o Phar também pode converter entre os formatos de arquivo tar, zip e phar com uma única linha de código. Veja Phar::convertToExecutable() para um exemplo.

O que é phar? Arquivos phar são melhor caracterizados como uma maneira conveniente de agrupar vários arquivos em um único arquivo. Assim, um arquivo phar fornece uma maneira de distribuir uma aplicação PHP completa em um único arquivo e executá-la a partir desse arquivo sem a necessidade de extraí-la para o disco. Além disso, arquivos phar podem ser executados pelo PHP tão facilmente quanto qualquer outro arquivo, tanto na linha de comando quanto em um servidor web. Phar é como um pen drive para aplicações PHP.

Phar implementa essa funcionalidade por meio de um empacotador de fluxo. Normalmente, para usar um arquivo externo dentro de um script PHP, seria usado include:

Exemplo #1 Using an external file

    <?php
     include '/caminho/para/arquivo/externo.php';
     ?>

Pode-se pensar que o PHP está, na verdade, traduzindo `/caminho/para/arquivo/externo.php` em um empacotador de fluxo como `arquivo:///caminho/para/arquivo/externo.php` e, nos bastidores, ele de fato usa as funções do empacotador de fluxo de arquivo simples para acessar todos os arquivos locais.

Para usar um arquivo chamado `arquivo.php` contido em um arquivo phar `/caminho/para/meuphar.phar`, a sintaxe é muito semelhante à sintaxe `file://` acima.

Exemplo #2 Usando um arquivo dentro de um arquivo phar

    <?php
     include 'phar:///caminho/para/meuphar.phar/arquivo.php';
     ?>

De fato, é possível tratar um arquivo phar exatamente como se fosse um disco externo, usando qualquer uma das funções relacionadas a fopen(), opendir() e funções relacionadas a mkdir() para ler, alterar ou criar novos arquivos e diretórios dentro do arquivo phar. Isso permite que aplicações PHP completas sejam distribuídas em um único arquivo e executadas diretamente a partir dele.

O uso mais comum de um arquivo phar é distribuir uma aplicação completa em um único arquivo. Por exemplo, o Instalador PEAR, que acompanha as versões do PHP é distribuído como um arquivo phar. Para usar um arquivo phar distribuído desta forma, o arquivo pode ser executado na linha de comando ou por meio de um servidor web.

Os arquivos Phar podem ser distribuídos como arquivos `tar`, arquivos `zip` ou como o formato de arquivo `phar` personalizado projetado especificamente para a extensão phar. Cada formato de arquivo tem vantagens e desvantagens. Os formatos de arquivo tar e zip podem ser lidos ou extraídos por qualquer ferramenta de terceiros que possa ler o formato, mas que requer a extensão phar para executar com PHP. O formato de arquivo phar é personalizado e exclusivo para a extensão phar, e só pode ser criado pela extensão phar ou pelo pacote PEAR » PHP_Archive, mas tem a vantagem de que as aplicações criadas neste formato serão executadas mesmo se a extensão phar não estiver habilitada.

Em outras palavras, mesmo com a extensão phar desabilitada, é possível executar ou incluir um arquivo baseado em phar. Acessar arquivos individuais dentro de um arquivo phar só é possível com a extensão phar, a menos que o arquivo phar tenha sido criado pelo PHP_Archive.

A extensão phar também é capaz de converter um arquivo phar de tar para zip ou para o formato de arquivo phar em um único comando:

Exemplo #3 Convertendo um arquivo phar do formato phar para tar

    <?php
    $phar = new Phar('meuphar.phar');
    $pgz = $phar->convertToExecutable(Phar::TAR, Phar::GZ); // cria meuphar.phar.tar.gz
    ?>

O Phar pode compactar arquivos individuais ou um arquivo inteiro usando a compactação gzip ou bzip2, e pode verificar a integridade do arquivo automaticamente por meio do uso de assinaturas MD5, SHA-1, SHA-256 ou SHA-512.

Por fim, a extensão Phar é voltada para a segurança e desabilita o acesso de gravação aos arquivos Phar executáveis ​​por padrão, além de exigir a desativação, em nível de sistema, da configuração `phar.readonly` do php.ini para criar ou modificar arquivos Phar. Arquivos tar e zip normais sem um stub executável sempre podem ser criados ou modificados usando a classe PharData.

Se aplicações para distribuição estiverem sendo criadas, leia Como criar arquivos Phar. Se quiser mais informações sobre as diferenças entre os três formatos de arquivo suportados pelo Phar, leia Phar, Tar e Zip.

Se aplicações Phar estiverem sendo usadas, há dicas úteis em Como usar os Arquivos Phar.

A palavra `phar` é uma junção de `PHP` e `Archive` e é vagamente baseada no `jar` (Java Archive), familiar aos desenvolvedores Java.

A implementação para arquivos Phar é baseada no pacote PEAR » PHP_Archive, e os detalhes de implementação são semelhantes, embora a extensão Phar seja muito mais poderosa. Além disso, a extensão Phar permite que a maioria das aplicações PHP sejam executadas sem modificações, enquanto os arquivos Phar baseados em PHP_Archive geralmente exigem modificações extensas para funcionar.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução
- Tipos de Recurso

## Dependências

Opcionalmente, podeme ser habilitadas as extensões zlib e bzip2 para aproveitar o suporte a phar compactado. Além disso, para aproveitar a assinatura OpenSSL, a extensão OpenSSL deve estar habilitada.

Se zend.multibyte estiver habilitado, zend.detect_unicode também deverá ser habilitado.

## Instalação

A extensão Phar está incluída no PHP e é habilitada por padrão. Para desabilitar o suporte a Phar, use --disable-phar.

O Phar pode ser instalado por meio da extensão PECL com versões anteriores do PHP, e a » página PECL do Phar contém mais informações e histórico.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de configuração de sistema de arquivos e fluxos
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
phar.readonly | "1" | `INI_ALL` |
phar.require_hash | "1" | `INI_ALL` |
phar.cache_list | "" | `INI_SYSTEM` |

Aqui está uma breve explicação das diretivas de configuração.

`phar.readonly` bool

  Esta opção desabilita a criação ou modificação de arquivos Phar usando o fluxo `phar` ou o suporte de gravação do objeto Phar. Esta configuração deve estar sempre habilitada em máquinas de produção, pois o suporte conveniente de gravação da extensão phar pode permitir a criação direta de um vírus baseado em PHP quando combinado com outras vulnerabilidades de segurança comuns.

  > Nota:

  > Esta configuração só pode ser desativada no arquivo php.ini por motivos de segurança. Se `phar.readonly` estiver desabilitado no arquivo php.ini, o usuário poderá habilitar `phar.readonly` em um script ou desabilitá-lo posteriormente. Se `phar.readonly` estiver habilitado no arquivo php.ini, um script poderá "reabilitar" a variável INI sem causar danos, mas não poderá desabilitá-la.

`phar.require_hash` bool

  Esta opção forçará todos os arquivos Phar abertos a conter algum tipo de assinatura (atualmente MD5, SHA1, SHA256, SHA512 e OpenSSL são suportados) e se recusará a processar qualquer arquivo Phar que não contenha uma assinatura.

  > Nota:

  > Esta configuração só pode ser desativada em php.ini. Se `phar.require_hash` estiver desabilitado em php.ini, o usuário poderá habilitar `phar.require_hash` em um script ou desabilitá-lo posteriormente. Se `phar.require_hash` estiver habilitado em php.ini, um script poderá "reabilitar" a variável INI sem causar danos, mas não poderá desabilitá-la.

  > Esta configuração não afeta a leitura de arquivos tar simples com a classe PharData.

  Cuidado

  `phar.require_hash` não fornece nenhuma segurança por si só, é apenas uma medida contra a execução acidental de arquivos Phar corrompidos, porque qualquer um que conseguisse adulterar o Phar poderia facilmente consertar a assinatura posteriormente.

`phar.cache_list` string

  Permite que o mapeamento de arquivos phar seja pré-analisado na inicialização do servidor web, proporcionando uma melhoria de desempenho que aproxima a execução de arquivos de um arquivo phar da velocidade de execução desses arquivos de uma instalação tradicional baseada em disco.

  Exemplo #1 Exemplo de uso de phar.cache_list

      no php.ini (windows):
      phar.cache_list =C:\caminho\para\phar1.phar;C:\caminho\para\phar2.phar
      no php.ini (unix):
      phar.cache_list =/caminho/para/phar1.phar:/caminho/para/phar2.phar

## Tipos de Recurso

A extensão Phar fornece o fluxo `phar`, que permite acessar arquivos contidos em um phar de forma transparente. Veja também a descrição do formato de arquivo Phar.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

Constantes de compactação Phar
Constante | Valor | Descrição
--- | --- | ---
`Phar::NONE` (int) | 0x00000000 | sem compactação
`Phar::COMPRESSED` (int) | 0x0000F000 | máscara de bits que pode ser usada com sinalizadores de arquivo para determinar se há alguma compactação presente
`Phar::GZ` (int) | 0x00001000 | compactação zlib (gzip)
`Phar::BZ2` (int) | 0x00002000 | compactação bzip2

Constantes de formato de arquivo Phar
Constante | Valor | Descrição
--- | --- | ---
`Phar::PHAR` (int) | 1 | formato de arquivo phar
`Phar::TAR` (int) | 2 | formato de arquivo tar
`Phar::ZIP` (int) | 3 | formato de arquivo zip

Constantes de assinatura Phar
Constante | Valor | Descrição
--- | --- | ---
`Phar::MD5` (int) | 0x0001 | assinatura com algoritmo de hash md5
`Phar::SHA1` (int) | 0x0002 | assinatura com algoritmo de hash sha1
`Phar::SHA256` (int) | 0x0003 | assinatura com algoritmo de hash sha256 (requer extensão hash)
`Phar::SHA512` (int) | 0x0004 | assinatura com algoritmo de hash sha512 (requer extensão hash)
`Phar::OPENSSL` (int) | 0x0010 | assinatura com par de chaves pública/privada OpenSSL; esta é uma verdadeira assinatura de chave assimétrica
`Phar::OPENSSL_SHA256` (int) |  |
`Phar::OPENSSL_SHA512` (int) |  |

Constantes de substituição de MIME Phar webPhar
Constante | Valor | Descrição
--- | --- | ---
`Phar::PHP` (int) | 0 | usado para instruir o parâmetro mimeoverrides de Phar::webPhar() que a extensão deve ser analisada como um arquivo PHP
`Phar::PHPS` (int) | 1 | usado para instruir o parâmetro mimeoverrides de Phar::webPhar() que a extensão deve ser analisada como um arquivo-fonte PHP por meio de highlight_file()

# Usando Arquivos Phar

## Índice

- Usando Arquivos Phar: Introdução
- Usando Arquivos Phar: o empacotador de fluxo phar
- Usando Arquivos Phar: as classes Phar e PharData

## Usando Arquivos Phar: Introdução

Os arquivos Phar são semelhantes em conceito aos arquivos JAR do Java, mas são adaptados às necessidades e à flexibilidade de aplicações PHP. Um arquivo Phar é usado para distribuir uma aplicação ou biblioteca PHP completa em um único arquivo. Uma aplicação de arquivo Phar é usada exatamente como qualquer outra aplicação PHP:

    php aplicacaoincrivel.phar

Usar uma biblioteca de arquivo Phar é idêntico ao uso de qualquer outra biblioteca PHP:

    <?php
    include 'bibliotecafantastica.phar';
    ?>

O empacotador de fluxo `phar` fornece o núcleo da extensão phar e é explicado em detalhes aqui. O empacotador de fluxo phar permite acessar os arquivos dentro de um arquivo phar usando as funções de arquivo padrão do PHP fopen(), opendir() e outras que funcionam em arquivos comuns. O empacotador de fluxo `phar` suporta todas as operações de leitura/gravação em arquivos e diretórios.

    <?php
    include 'phar://bibliotecafantastica.phar/interno/arquivo.php';
    header('Content-type: image/jpeg');
    // phars pode ser acessado pelo caminho completo ou por apelido
    echo file_get_contents('phar:///caminhocompleto/para/bibliotecafantastica.phar/imagens/uau.jpg');
    ?>

A classe Phar implementa funcionalidades avançadas para acessar arquivos e criar arquivos phar. A classe Phar é explicada em detalhes aqui.

    <?php
    try {
        // abre um phar existente
        $p = new Phar('bibliotecafantastica.phar', 0);
        // Phar estende a classe DirectoryIterator do SPL
        foreach (new RecursiveIteratorIterator($p) as $file) {
            // $file é uma classe PharFileInfo e herda de SplFileInfo
            echo $file->getFileName() . "\n";
            echo file_get_contents($file->getPathName()) . "\n"; // exibir conteúdo;
        }
        if (isset($p['internal/file.php'])) {
            var_dump($p['internal/file.php']->getMetadata());
        }

        // cria um novo phar - phar.readonly deve ser 0 em php.ini
        // phar.readonly é habilitado por padrão por motivos de segurança.
        // Em servidores de produção, Phars nunca precisam ser criados,
        // apenas executados.
        if (Phar::canWrite()) {
            $p = new Phar('novophar.tar.phar', 0, 'novophar.tar.phar');
            // faz deste um arquivo phar baseado em tar, compactado com compressão gzip (.tar.gz)
            $p = $p->convertToExecutable(Phar::TAR, Phar::GZ);

            // cria transação - nada é escrito em novophar.phar
            // até que stopBuffering() seja chamado, embora seja necessário armazenamento temporário
            $p->startBuffering();
            // adiciona todos os arquivos em /caminho/para/projeto, salvando no phar com o prefixo "projeto"
            $p->buildFromIterator(new RecursiveIteratorIterator(new RecursiveDirectoryIterator('/caminho/para/projeto')), '/caminho/para/');

            // adiciona um novo arquivo por meio da API de acesso a array
            $p['arquivo1.txt'] = 'Informação';
            $fp = fopen('arquivogigante.dat', 'rb');
            // copia todos os dados do fluxo
            $p['dados/arquivogigante.dat'] = $fp;

            if (Phar::canCompress(Phar::GZ)) {
                $p['dados/arquivogigante.dat']->compress(Phar::GZ);
            }

            $p['imagens/uau.jpg'] = file_get_contents('imagens/uau.jpg');
            // qualquer valor pode ser salvo como metadados específicos do arquivo
            $p['imagens/uau.jpg']->setMetadata(array('mime-type' => 'image/jpeg'));
            $p['index.php'] = file_get_contents('index.php');
            $p->setMetadata(array('bootstrap' => 'index.php'));

            // salva o arquivo phar no disco
            $p->stopBuffering();
        }
    } catch (Exception $e) {
        echo 'Não foi possível abrir o Phar: ', $e;
    }
    ?>

Além disso, a verificação do conteúdo do arquivo phar pode ser feita usando qualquer um dos algoritmos de hash simétricos suportados (MD5, SHA1, SHA256 e SHA512 se ext/hash estiver habilitado) e usando assinatura assimétrica de chave pública/privada usando OpenSSL. Para aproveitar a assinatura OpenSSL, é necessário gerar um par de chaves pública/privada e usar a chave privada para definir a assinatura usando Phar::setSignatureAlgorithm(). Adicionalmente, a chave pública extraída usando este código:

    <?php
    $public = openssl_get_publickey(file_get_contents('private.pem'));
    $pkey = '';
    openssl_pkey_export($public, $pkey);
    ?>

deve ser salva adjacente ao arquivo phar que ela verifica. Se o arquivo phar for salvo como `/caminho/para/meu.phar`, a chave pública deve ser salva como `/caminho/para/meu.phar.pubkey`, ou o phar não conseguirá verificar a assinatura OpenSSL.

A classe Phar também fornece 3 métodos estáticos, Phar::webPhar(), Phar::mungServer() e Phar::interceptFileFuncs(), que são cruciais para empacotar aplicações PHP projetadas para uso em sistemas de arquivos comuns e para aplicações web. Phar::webPhar() implementa um controlador de frente que roteia chamadas HTTP para o local correto dentro do arquivo phar. Phar::mungServer() é usado para modificar os valores do array $_SERVER para enganar aplicações que processam esses valores. Phar::interceptFileFuncs() instrui o Phar a interceptar chamadas para fopen(), file_get_contents(), opendir() e todas as funções baseadas em estatísticas (file_exists(), is_readable() e assim por diante) e rotear todos os caminhos relativos para locais dentro do arquivo phar.

Por exemplo, empacotar uma versão do popular aplicativo phpMyAdmin para uso como um arquivo phar requer apenas este script simples e então `phpMyAdmin.phar.tar.php` pode ser acessado como um arquivo normal a partir do servidor web após modificar o usuário/senha:

    <?php
    @unlink('phpMyAdmin.phar.tar.php');
    copy('phpMyAdmin-2.11.3-english.tar.gz', 'phpMyAdmin.phar.tar.php');
    $a = new Phar('phpMyAdmin.phar.tar.php');
    $a->startBuffering();
    $a["phpMyAdmin-2.11.3-english/config.inc.php"] = '<?php
    /* Configuração de servidores */
    $i = 0;

    /* Servidor localhost (config:root) [1] */
    $i++;
    $cfg[\'Servers\'][$i][\'host\'] = \'localhost\';
    $cfg[\'Servers\'][$i][\'extension\'] = \'mysqli\';
    $cfg[\'Servers\'][$i][\'connect_type\'] = \'tcp\';
    $cfg[\'Servers\'][$i][\'compress\'] = false;
    $cfg[\'Servers\'][$i][\'auth_type\'] = \'config\';
    $cfg[\'Servers\'][$i][\'user\'] = \'root\';
    $cfg[\'Servers\'][$i][\'password\'] = \'\';

    /* Fim da configuração dos servidores */
    if (strpos(PHP_OS, \'WIN\') !== false) {
        $cfg[\'UploadDir\'] = getcwd();
    } else {
        $cfg[\'UploadDir\'] = \'/tmp/pharphpmyadmin\';
        @mkdir(\'/tmp/pharphpmyadmin\');
        @chmod(\'/tmp/pharphpmyadmin\', 0777);
    }';
    $a->setStub('<?php
    Phar::interceptFileFuncs();
    Phar::webPhar("phpMyAdmin.phar", "phpMyAdmin-2.11.3-english/index.php");
    echo "O phpMyAdmin foi projetado para ser executado a partir de um navegador da web\n";
    exit -1;
    __HALT_COMPILER();
    ');
    $a->stopBuffering();
    ?>

## Usando Arquivos Phar: o empacotador de fluxo phar

O empacotador de fluxo Phar suporta totalmente fopen() para leitura e gravação (não anexação), unlink(), stat(), fstat(), fseek(), rename() e operações de fluxo de diretório opendir(), rmdir() e mkdir().

A compactação de arquivos individuais e os metadados por arquivo também podem ser manipulados em um arquivo Phar usando contextos de fluxo:

    <?php
    $context = stream_context_create(array('phar' =>
                                        array('compress' => Phar::GZ)),
                                        array('metadata' => array('user' => 'cellog')));
    file_put_contents('phar://meu.phar/algumarquivo.php', 0, $context);
    ?>

O empacotador de fluxo `phar` não opera em arquivos remotos, e não pode operar em arquivos remotos, sendo, portanto, permitido mesmo quando as opções INI allow_url_fopen e allow_url_include estão desabilitadas.

Embora seja possível criar arquivos PHAR do zero usando apenas operações de fluxo, é melhor usar a funcionalidade incorporada à classe Phar. O empacotador de fluxo é mais adequado para operações somente leitura.

## Usando Arquivos Phar: as classes Phar e PharData

A classe Phar suporta leitura e manipulação de arquivos Phar, bem como iteração por meio da funcionalidade herdada da classe RecursiveDirectoryIterator. Com suporte à interface ArrayAccess, os arquivos dentro de um arquivo Phar podem ser acessados ​​como se fossem parte de um array associativo.

A classe PharData estende a classe Phar e permite criar e modificar arquivos tar e zip não executáveis ​​(de dados), mesmo que `phar.readonly`=1 em php.ini. Dessa forma, PharData::setAlias() e PharData::setStub() estão desabilitados, pois os conceitos de alias e stub são exclusivos dos arquivos phar executáveis.

É importante observar que, ao criar um arquivo Phar, o caminho completo deve ser passado para o construtor do objeto Phar. Caminhos relativos não serão inicializados.

Supondo que `$p` é um objeto Phar inicializado da seguinte maneira:

    <?php
    $p = new Phar('/caminho/para/meuphar.phar', 0, 'meuphar.phar');
    ?>

Um arquivo Phar vazio será criado em `/caminho/para/meuphar.phar`, ou, se `/caminho/para/meuphar.phar` já existir, ele será aberto novamente. O literal `meuphar.phar` demonstra o conceito de um apelido que pode ser usado para referenciar `/caminho/para/meuphar.phar` em URLs como em:

    <?php
    // essas duas chamadas para file_get_contents() são equivalentes se
    // /caminho/para/meuphar.phar tiver um apelido explícito de "meuphar.phar"
    // em seu manifesto, ou se o phar foi inicializado com a
    // configuração do objeto Phar do exemplo anterior
    $f = file_get_contents('phar:///caminho/para/meuphar.phar/qualquercoisa.txt');
    $f = file_get_contents('phar://meuphar.phar/qualquercoisa.txt');
    ?>

Com o objeto `$p` Phar recém-criado, o seguinte é possível:

- `$a = $p['arquivo.php']` cria uma classe PharFileInfo que se refere ao conteúdo de `phar://meuphar.phar/arquivo.php`
- `$p['arquivo.php'] = $v` cria um novo arquivo (`phar://meuphar.phar/arquivo.php`) ou sobrescreve um arquivo existente dentro de `meuphar.phar`. `$v` pode ser uma string ou um ponteiro para arquivo aberto, caso em que todo o conteúdo do arquivo será usado para criar o novo arquivo. Observe que `$p->addFromString('arquivo.php', $v)` é funcionalmente equivalente ao acima. Também é possível adicionar o conteúdo de um arquivo com `$p->addFile('/caminho/para/arquivo.php', 'arquivo.php')`. Por fim, um diretório vazio pode ser criado com `$p->addEmptyDir('empty')`.
- `isset($p['arquivo.php'])` pode ser usado para determinar se `phar://meuphar.phar/arquivo.php` existe dentro de `meuphar.phar`.
- `unset($p['arquivo.php'])` apaga `phar://meuphar.phar/arquivo.php` de `meuphar.phar`.

Além disso, o objeto Phar é a única maneira de acessar metadados específicos do Phar, por meio de Phar::getMetadata(), e a única maneira de definir ou recuperar o stub do carregador PHP de um arquivo Phar por meio de Phar::getStub() e Phar::setStub(). Além disso, a compactação de todo o arquivo Phar de uma só vez só pode ser manipulada usando a classe Phar.

A lista completa de funcionalidades do objeto Phar está documentada abaixo.

A classe PharFileInfo estende a classe SplFileInfo e adiciona vários métodos para manipular detalhes específicos de Phar de um arquivo contido em um Phar, como manipular compactação e metadados.

# Criando Arquivos Phar

## Índice

- Criando Arquivos Phar: Introdução

## Criando Arquivos Phar: Introdução

Será escrito na íntegra em breve. Antes de ler isto, leia Como usar os Arquivos Phar.

Um ótimo lugar para começar é lendo sobre Phar::buildFromIterator(), e as especificações das opções de formato de arquivo disponíveis para arquivos. Uma boa compreensão do que é e o que faz um stub é crucial para a criação de arquivos phar, portanto, Phar::setStub() e Phar::createDefaultStub() também são bons lugares para começar. Se uma aplicação baseada na web estiver sendo distribuída, é crucial conhecer Phar::webPhar() e o método relacionado Phar::mungServer(). Qualquer aplicação que acesse seus próprios arquivos também deve considerar o uso de Phar::interceptFileFuncs().

# O que faz um phar ser um phar e não um tar ou um zip?

## Índice

- Ingredientes de todos os arquivos Phar, independentemente do formato do arquivo
- Stub de arquivo Phar
- Comparação direta de Phar, Tar e Zip
- Phars baseados em Tar
- Phars baseados em Zip
- Formato de arquivo phar
- Sinalizadores globais Phar em mapa de bits
- Definição de entrada do arquivo de manifesto Phar
- Formato de assinatura Phar

## Ingredientes de todos os arquivos Phar, independentemente do formato do arquivo

Todos os arquivos Phar contêm de três a quatro seções:

1. um stub

2. um manifesto descrevendo o conteúdo

3. o conteúdo do arquivo

4. [opcional] uma assinatura para verificar a integridade do Phar (somente formato de arquivo phar)

## Stub de arquivo Phar

Um stub de Phar é um arquivo PHP simples. O menor stub possível é o seguinte:

    <?php __HALT_COMPILER();

Um stub deve conter, no mínimo, o token `__HALT_COMPILER();` em sua conclusão. Normalmente, um stub conterá a funcionalidade do carregador como a seguir:

    <?php
    Phar::mapPhar();
    include 'phar://meuphar.phar/index.php';
    __HALT_COMPILER();

Não há restrições quanto ao conteúdo de um stub Phar, exceto pelo requisito de que ele termine com `__HALT_COMPILER();`. A tag PHP de fechamento ``

    ?>

pode ser incluída ou omitida, mas não pode haver mais de 1 espaço entre `;` e a tag de fechamento `

    ?>

` ou a extensão phar não conseguirá processar o manifesto do arquivo Phar.

Em um arquivo Phar baseado em tar ou zip, o stub é armazenado no arquivo `.phar/stub.php`. O stub padrão para arquivos Phar baseados em Phar contém aproximadamente 7k de código para extrair o conteúdo do Phar e executá-lo. Consulte Phar::createDefaultStub() para mais detalhes.

O apelido phar é armazenado em um arquivo phar tar ou zip no arquivo `.phar/alias.txt` como texto simples.

## Comparação direta de Phar, Tar e Zip

Quais são os pontos positivos e negativos dos três formatos de arquivo suportados na extensão phar? Esta tabela tenta responder a essa pergunta.

Matriz de Características: Phar vs. Tar vs. Zip
Característica | Phar | Tar | Zip
--- | --- | --- | ---
Formato de arquivo padrão | Não | Sim | Sim
Pode ser executado sem a extensão Phar [1] | Sim | Não | Não
Compactação por arquivo | Sim | Não | Sim
Compactação de arquivo inteiro | Sim | Sim | Não
Validação de assinatura de arquivo inteiro | Sim | Sim | Sim
Suporte a aplicativos específicos da Web | Sim | Sim | Sim
Metadados por arquivo | Sim | Sim | Sim
Metadados de arquivo inteiro | Sim | Sim | Sim
Criação/modificação de arquivo [2] | Sim | Sim | Sim
Suporte total para todas as funções do empacotador de fluxo | Sim | Sim | Sim
Pode ser criado/modificado mesmo que phar.readonly=1 [3] | Não | Sim | Sim

Dica

[1] O PHP só pode acessar diretamente o conteúdo de um arquivo Phar sem a extensão Phar se estiver usando um `stub` que extrai o conteúdo do arquivo Phar. O stub criado por Phar::createDefaultStub() extrai o arquivo Phar e executa seu conteúdo a partir de um diretório temporário se nenhuma extensão Phar for encontrada.

Dica

[2] Todo acesso de gravação requer que `phar.readonly` seja desabilitado no php.ini ou diretamente na linha de comando.

Dica

[3] Somente arquivos tar e zip sem `.phar` em seu nome de arquivo e sem um stub executável `.phar/stub.php` podem ser criados se phar.readonly=1.

## Phars baseados em Tar

Arquivos baseados no formato tar seguem o formato de arquivo USTAR mais moderno. O design do cabeçalho do arquivo tar os torna mais eficientes de acessar do que o formato zip e quase tão eficientes quanto o formato phar. Os nomes de arquivo são limitados a 255 bytes, incluindo o caminho completo dentro do arquivo phar. Não há limite para o número de arquivos dentro de um arquivo phar baseado em tar. Esses arquivos podem ser totalmente compactados no formato gzip ou bzip2 e ainda serem executados pela extensão Phar.

Há suporte limitado para leitura de tarballs no formato de intercâmbio pax, mas todos os cabeçalhos pax reconhecidos (atualmente, typeflag `x` e `g`) são ignorados silenciosamente. Também há suporte limitado para Arquivos GNU Tar; atualmente, os cabeçalhos `././@LongLink` são resolvidos.

Para compactar um arquivo inteiro, use Phar::compress(). Para descompactar um arquivo inteiro, use Phar::decompress().

## Phars baseados em Zip

Arquivos baseados no formato de arquivo zip suportam diversos recursos incorporados ao formato de arquivo zip. Metadados por arquivo e de todo o arquivo são armazenados no comentário do arquivo zip como uma string serializada. Comentários zip pré-existentes serão lidos com sucesso como uma string. A leitura/gravação de compactação por arquivo é suportada com a compactação DEFLATE do zlib, e o acesso de leitura é suportado com a compactação bzip2. Não há limite para o número de arquivos dentro de um arquivo phar baseado em zip. Diretórios vazios são armazenados no arquivo zip como arquivos com uma barra final, como `meu/diretorio/`.

## Formato de arquivo phar

O formato do arquivo phar é literalmente definido como stub/manifesto/conteúdo/assinatura e armazena as informações cruciais do que está incluído no arquivo phar em seu `manifest`o.

O manifesto Phar é um formato altamente otimizado que permite a especificação por arquivo da compactação, das permissões e até mesmo dos metadados definidos pelo usuário, como usuário ou grupo do arquivo. Todos os valores maiores que 1 byte são armazenados na ordem little-endian, com exceção da versão da API, que por razões históricas é armazenada como 3 nibbles na ordem big-endian.

Todos os sinalizadores não utilizados são reservados para uso futuro e não devem ser usados para armazenar informações personalizadas. Use o recurso de metadados por arquivo para armazenar informações personalizadas sobre arquivos específicos.

O formato básico de arquivo de um manifesto de arquivo Phar é o seguinte:

Formato global de manifesto Phar
Tamanho em bytes | Descrição
--- | ---
4 bytes | Comprimento do manifesto em bytes (limite de 1 MB)
4 bytes | Número de arquivos no Phar
2 bytes | Versão da API do manifesto Phar (atualmente 1.0.0)
4 bytes | Sinalizadores globais Phar em mapa de bits
4 bytes | Comprimento do apelido Phar
?? | Apelido Phar (comprimento com base no anterior)
4 bytes | Comprimento dos metadados Phar (`0` para nenhum)
?? | Metadados Phar serializados, armazenados no formato serialize()
pelo menos 24 * número de bytes de entradas | entradas para cada arquivo

## Sinalizadores globais Phar em mapa de bits

Aqui estão os sinalizadores de mapa de bits atualmente reconhecidos pela extensão Phar para o mapa de bits global Phar:

Valores de mapa de bits reconhecidos
Valor | Descrição
--- | ---
`0x00010000` | Se definido, este Phar contém uma assinatura de verificação
`0x00001000` | Se definido, este Phar contém pelo menos 1 arquivo compactado com DEFLATE do zlib
`0x00002000` | Se definido, este Phar contém pelo menos 1 arquivo compactado com bzip2

## Definição de entrada do arquivo de manifesto Phar

Cada arquivo no manifesto contém as seguintes informações:

Entrada no arquivo Phar Manifest
Tamanho em bytes | Descrição
--- | ---
4 bytes | Comprimento do nome do arquivo em bytes
?? | Nome do arquivo (comprimento especificado anteriormente)
4 bytes | Tamanho do arquivo não compactado em bytes
4 bytes | Timestamp Unix do arquivo
4 bytes | Tamanho do arquivo compactado em bytes
4 bytes | Soma de verificação CRC32 do conteúdo do arquivo não compactado
4 bytes | Sinalizadores específicos de arquivo mapeados em bits
4 bytes | Comprimento de metadados de arquivo serializado (`0` para nenhum)
?? | Metadados de arquivo serializados, armazenados no formato serialize()

Observe que, a partir da versão 1.1.1 da API, diretórios vazios são armazenados como nomes de arquivos com uma barra final como `meu/diretorio/`.

Os valores reconhecidos de mapa de bits específicos para arquivo são:

Valores reconhecidos de mapa de bits
Valor | Descrição
--- | ---
`0x000001FF` | Esses bits são reservados para definir permissões específicas de um arquivo. As permissões são usadas para fstat() e podem ser usadas para recriar as permissões desejadas na extração.
`0x00001000` | Se definido, este arquivo será compactado com DEFLATE zlib.
`0x00002000` | Se definido, este arquivo será compactado com bzip2.

## Formato de assinatura Phar

Phars que contêm uma assinatura sempre têm a assinatura anexada ao final do arquivo Phar, após o carregador, o manifesto e o conteúdo do arquivo. Os formatos de assinatura suportados no momento são MD5, SHA1, SHA256, SHA512 e OPENSSL.

Formato de assinatura
Comprimento em bytes | Descrição
--- | ---
variável | A assinatura real: 20 bytes para uma assinatura SHA1, 16 bytes para uma assinatura MD5, 32 bytes para uma assinatura SHA256 e 64 bytes para uma assinatura SHA512. O comprimento de uma assinatura OPENSSL depende do tamanho da chave privada.
4 bytes | Sinalizadores de assinatura. `0x0001` é usado para definir uma assinatura MD5, `0x0002` é usado para definir uma assinatura SHA1, `0x0003` é usado para definir uma assinatura SHA256 e `0x0004` é usado para definir uma assinatura SHA512. O suporte às assinaturas SHA256 e SHA512 está disponível a partir da versão 1.1.0 da API. `0x0010` é usado para definir uma assinatura OPENSSL, que está disponível a partir da versão 1.1.1 da API, se o OpenSSL estiver disponível.
4 bytes | Palavra mágica `GBMB` usada para definir a presença de uma assinatura.

# A classe Phar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

## Introdução

A classe Phar fornece uma interface de alto nível para acessar e criar arquivos phar.

## Resumo da classe

class Phar extends RecursiveDirectoryIterator implements Countable, ArrayAccess {
/* Constantes herdadas */
public const int FilesystemIterator::CURRENT_MODE_MASK;
public const int FilesystemIterator::CURRENT_AS_PATHNAME;
public const int FilesystemIterator::CURRENT_AS_FILEINFO;
public const int FilesystemIterator::CURRENT_AS_SELF;
public const int FilesystemIterator::KEY_MODE_MASK;
public const int FilesystemIterator::KEY_AS_PATHNAME;
public const int FilesystemIterator::FOLLOW_SYMLINKS;
public const int FilesystemIterator::KEY_AS_FILENAME;
public const int FilesystemIterator::NEW_CURRENT_AND_KEY;
public const int FilesystemIterator::OTHER_MODE_MASK;
public const int FilesystemIterator::SKIP_DOTS;
public const int FilesystemIterator::UNIX_PATHS;
/* Constantes */
const int BZ2;
const int GZ;
const int NONE;
const int PHAR;
const int TAR;
const int ZIP;
const int COMPRESSED;
const int PHP;
const int PHPS;
const int MD5;
const int OPENSSL;
const int OPENSSL_SHA256;
const int OPENSSL_SHA512;
const int SHA1;
const int SHA256;
const int SHA512;
/* Métodos */
public function __construct(string `$filename`, int `$flags` = FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS, ?string `$alias` = `null`)
public function addEmptyDir(string `$directory`): void
public function addFile(string `$filename`, ?string `$localName` = `null`): void
public function addFromString(string `$localName`, string `$contents`): void
final public static function apiVersion(): string
public function buildFromDirectory(string `$directory`, string `$pattern` = ""): array
public function buildFromIterator(Traversable `$iterator`, ?string `$baseDirectory` = `null`): array
final public static function canCompress(int `$compression` = 0): bool
final public static function canWrite(): bool
public function compress(int `$compression`, ?string `$extension` = `null`): ?Phar
public function compressFiles(int `$compression`): void
public function convertToData(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?PharData
public function convertToExecutable(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?Phar
public function copy(string `$from`, string `$to`): true
public function count(int `$mode` = `COUNT_NORMAL`): int
final public static function createDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): string
public function decompress(?string `$extension` = `null`): ?Phar
public function decompressFiles(): true
public function delMetadata(): true
public function delete(string `$localName`): true
public function extractTo(string `$directory`, array|string|null `$files` = `null`, bool `$overwrite` = `false`): bool
public function getAlias(): ?string
public function getMetadata(array `$unserializeOptions` = []): mixed
public function getModified(): bool
public function getPath(): string
public function getSignature(): array|false
public function getStub(): string
final public static function getSupportedCompression(): array
final public static function getSupportedSignatures(): array
public function getVersion(): string
public function hasMetadata(): bool
final public static function interceptFileFuncs(): void
public function isBuffering(): bool
public function isCompressed(): int|false
public function isFileFormat(int `$format`): bool
final public static function isValidPharFilename(string `$filename`, bool `$executable` = `true`): bool
public function isWritable(): bool
final public static function loadPhar(string `$filename`, ?string `$alias` = `null`): bool
final public static function mapPhar(?string `$alias` = `null`, int `$offset` = 0): bool
final public static function mount(string `$pharPath`, string `$externalPath`): void
final public static function mungServer(array `$variables`): void
public function offsetExists(string `$localName`): bool
public function offsetGet(string `$localName`): SplFileInfo
public function offsetSet(string `$localName`, resource|string `$value`): void
public function offsetUnset(string `$localName`): void
final public static function running(bool `$returnPhar` = `true`): string
public function setAlias(string `$alias`): true
public function setDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): true
public function setMetadata(mixed `$metadata`): void
public function setSignatureAlgorithm(int `$algo`, ?string `$privateKey` = `null`): void
public function setStub(resource|string `$stub`, int `$length` = -1): true
public function startBuffering(): void
public function stopBuffering(): void
final public static function unlinkArchive(string `$filename`): true
final public static function webPhar(
?string `$alias` = `null`,
?string `$index` = `null`,
?string `$fileNotFoundScript` = `null`,
array `$mimeTypes` = [],
?callable `$rewrite` = `null`
): void
public function __destruct()
/* Métodos herdados */
public function RecursiveDirectoryIterator::getChildren(): RecursiveDirectoryIterator
public function RecursiveDirectoryIterator::getSubPath(): string
public function RecursiveDirectoryIterator::getSubPathname(): string
public function RecursiveDirectoryIterator::hasChildren(bool `$allowLinks` = `false`): bool
public function RecursiveDirectoryIterator::key(): string
public function RecursiveDirectoryIterator::next(): void
public function RecursiveDirectoryIterator::rewind(): void
public function FilesystemIterator::current(): string|SplFileInfo|FilesystemIterator
public function FilesystemIterator::getFlags(): int
public function FilesystemIterator::key(): string
public function FilesystemIterator::next(): void
public function FilesystemIterator::rewind(): void
public function FilesystemIterator::setFlags(int `$flags`): void
public function DirectoryIterator::current(): mixed
public function DirectoryIterator::getBasename(string `$suffix` = ""): string
public function DirectoryIterator::getExtension(): string
public function DirectoryIterator::getFilename(): string
public function DirectoryIterator::isDot(): bool
public function DirectoryIterator::key(): mixed
public function DirectoryIterator::next(): void
public function DirectoryIterator::rewind(): void
public function DirectoryIterator::seek(int `$offset`): void
public function DirectoryIterator::__toString(): string
public function DirectoryIterator::valid(): bool
public function SplFileInfo::getATime(): int|false
public function SplFileInfo::getBasename(string `$suffix` = ""): string
public function SplFileInfo::getCTime(): int|false
public function SplFileInfo::getExtension(): string
public function SplFileInfo::getFileInfo(?string `$class` = `null`): SplFileInfo
public function SplFileInfo::getFilename(): string
public function SplFileInfo::getGroup(): int|false
public function SplFileInfo::getInode(): int|false
public function SplFileInfo::getLinkTarget(): string|false
public function SplFileInfo::getMTime(): int|false
public function SplFileInfo::getOwner(): int|false
public function SplFileInfo::getPath(): string
public function SplFileInfo::getPathInfo(?string `$class` = `null`): ?SplFileInfo
public function SplFileInfo::getPathname(): string
public function SplFileInfo::getPerms(): int|false
public function SplFileInfo::getRealPath(): string|false
public function SplFileInfo::getSize(): int|false
public function SplFileInfo::getType(): string|false
public function SplFileInfo::isDir(): bool
public function SplFileInfo::isExecutable(): bool
public function SplFileInfo::isFile(): bool
public function SplFileInfo::isLink(): bool
public function SplFileInfo::isReadable(): bool
public function SplFileInfo::isWritable(): bool
public function SplFileInfo::openFile(string `$mode` = "r", bool `$useIncludePath` = `false`, ?resource `$context` = `null`): SplFileObject
public function SplFileInfo::setFileClass(string `$class` = `SplFileObject::class`): void
public function SplFileInfo::setInfoClass(string `$class` = `SplFileInfo::class`): void
public function SplFileInfo::__toString(): string
}

## Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Adicionado suporte para a extensão de timestamp Unix para arquivos baseados em Zip.
8.0.0 | Metadados não são mais desserializados ao abrir o arquivo, esta atividade é adiada até que Phar::getMetadata() seja chamado.

## Notas

Cuidado

Anteriormente ao PHP 8.0.0, os metadados eram desserializados na abertura do arquivo. Isso poderia levar a vulnerabilidades de segurança. Iniciando com o PHP 8.0.0, os metadados são desserializados somente ao chamar Phar::getMetadata(), que tem opções para restringir a desserialização por motivos de segurança.

# Phar::addEmptyDir

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::addEmptyDir — Adiciona um diretório vazio ao arquivo phar

### Descrição

public function Phar::addEmptyDir(string `$directory`): void

> Nota: Este método requer que a configuração `phar.readonly` do php.ini seja definida como `0` para funcionar com objetos Phar. Caso contrário, uma exceção PharException será lançada.

Com este método, um diretório vazio é criado com o caminho `dirname`. Este método é semelhante a ZipArchive::addEmptyDir().

### Parâmetros

`directory`

  O nome do diretório vazio a ser criado no arquivo phar

### Valor Retornado

Nenhum valor de retorno, exceção é lançada em caso de falha.

### Exemplos

Exemplo #1 Um exemplo de Phar::addEmptyDir()

    <?php
    try {
        $a = new Phar('/caminho/para/phar.phar');

        $a->addEmptyDir('/caminho/completo/para/arquivo');
        // demonstra como este arquivo é armazenado
        $b = $a['full/path/to/file']->isDir();
    } catch (Exception $e) {
        // manipula os erros aqui
    }
    ?>

### Veja Também

- PharData::addEmptyDir() - Adiciona um diretório vazio ao arquivo tar/zip
- Phar::addFile() - Adiciona um arquivo do sistema de arquivos ao arquivo phar
- Phar::addFromString() - Adiciona um arquivo a partir de uma string ao arquivo phar

# Phar::addFile

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::addFile — Adiciona um arquivo do sistema de arquivos ao arquivo phar

### Descrição

public function Phar::addFile(string `$filename`, ?string `$localName` = `null`): void

> Nota: Este método requer que a configuração `phar.readonly` do php.ini seja definida como `0` para funcionar com objetos Phar. Caso contrário, uma exceção PharException será lançada.

Com este método, qualquer arquivo ou URL pode ser adicionado ao arquivo phar. Se o segundo parâmetro opcional `localName` for uma string, o arquivo será armazenado no arquivo com esse nome; caso contrário, o parâmetro `file` será usado como o caminho para armazenar o arquivo. URLs devem ter um nome local ou uma exceção será lançada. Este método é semelhante a ZipArchive::addFile().

### Parâmetros

`filename`

  Caminho completo ou relativo para um arquivo no disco a ser adicionado ao arquivo phar.

`localName`

  Caminho onde o arquivo será armazenado no arquivo compactado.

### Valor Retornado

Nenhum valor de retorno, exceção é lançada em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `localName` agora é anulável.

### Exemplos

Exemplo #1 Um exemplo de Phar::addFile()

    <?php
    try {
        $a = new Phar('/path/to/phar.phar');

        $a->addFile('/full/path/to/file');
        // demonstra como este arquivo é armazenado
        $b = $a['full/path/to/file']->getContent();

        $a->addFile('/full/path/to/file', 'my/file.txt');
        $c = $a['my/file.txt']->getContent();

        // demonstra o uso de URL
        $a->addFile('http://www.example.com', 'example.html');
    } catch (Exception $e) {
        // manipula erros aqui
    }
    ?>

### Notas

> Nota: Phar::addFile(), Phar::addFromString() e Phar::offsetSet() salvam um novo arquivo phar cada vez que são chamadas. Se o desempenho for uma preocupação, Phar::buildFromDirectory() ou Phar::buildFromIterator() devem ser usadas.

### Veja Também

- Phar::offsetSet() - Define o conteúdo de um arquivo interno para o de um arquivo externo
- PharData::addFile() - Adiciona um arquivo do sistema de arquivos ao arquivo tar/zip
- Phar::addFromString() - Adiciona um arquivo a partir de uma string ao arquivo phar
- Phar::addEmptyDir() - Adiciona um diretório vazio ao arquivo phar

# Phar::addFromString

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::addFromString — Adiciona um arquivo a partir de uma string ao arquivo phar

### Descrição

public function Phar::addFromString(string `$localName`, string `$contents`): void

> Nota: Este método requer que a configuração `phar.readonly` do php.ini seja definida como `0` para funcionar com objetos Phar. Caso contrário, uma exceção PharException será lançada.

Com este método, qualquer string pode ser adicionada ao arquivo phar. O arquivo será armazenado no arquivo com `localname` como seu caminho. Este método é semelhante a ZipArchive::addFromString().

### Parâmetros

`localName`

  Caminho onde o arquivo será armazenado no arquivo compactado.

`contents`

  O conteúdo do arquivo a ser armazenado

### Valor Retornado

Nenhum valor de retorno, exceção é lançada em caso de falha.

### Exemplos

Exemplo #1 Um exemplo de Phar::addFromString()

    <?php
    try {
        $a = new Phar('/path/to/phar.phar');

        $a->addFromString('path/to/file.txt', 'my simple file');
        $b = $a['path/to/file.txt']->getContent();

        // para adicionar conteúdo de um identificador de fluxo para arquivos grandes, use offsetSet()
        $c = fopen('/path/to/hugefile.bin');
        $a['largefile.bin'] = $c;
        fclose($c);
    } catch (Exception $e) {
        // manipula erros aqui
    }
    ?>

### Notas

> Nota: Phar::addFile(), Phar::addFromString() e Phar::offsetSet() salvam um novo arquivo phar cada vez que são chamadas. Se o desempenho for uma preocupação, Phar::buildFromDirectory() ou Phar::buildFromIterator() devem ser usadas.

### Veja Também

- Phar::offsetSet() - Define o conteúdo de um arquivo interno para o de um arquivo externo
- PharData::addFromString() - Adiciona um arquivo de uma string ao arquivo tar/zip
- Phar::addFile() - Adiciona um arquivo do sistema de arquivos ao arquivo phar
- Phar::addEmptyDir() - Adiciona um diretório vazio ao arquivo phar

# Phar::apiVersion

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::apiVersion — Retorna a versão da API

### Descrição

final public static function Phar::apiVersion(): string

Retorna a versão da API do formato de arquivo phar que será usado ao criar phars. A extensão Phar suporta a leitura da API versão 1.0.0 ou mais recente. A versão 1.1.0 da API é necessária para hashes SHA-256 e SHA-512 e a versão 1.1.1 da API é necessária para armazenar diretórios vazios.

### Parâmetros

### Valor Retornado

A string de versão da API como em `"1.0.0"`.

### Exemplos

Exemplo #1 Um exemplo de Phar::apiVersion()

    <?php
    echo Phar::apiVersion();
    ?>

O exemplo acima produzirá:

    1.1.1

# Phar::buildFromDirectory

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::buildFromDirectory — Constrói um arquivo phar a partir dos arquivos dentro de um diretório

### Descrição

public function Phar::buildFromDirectory(string `$directory`, string `$pattern` = ""): array

> Nota: Este método requer que a configuração `phar.readonly` do php.ini seja definida como `0` para funcionar com objetos Phar. Caso contrário, uma exceção PharException será lançada.

Preenche um arquivo phar a partir do conteúdo do diretório. O segundo parâmetro opcional é uma expressão regular (pcre) usada para excluir arquivos. Qualquer nome de arquivo que corresponda à expressão regular será incluído, todos os outros serão excluídos. Para um controle mais refinado, use Phar::buildFromIterator().

### Parâmetros

`directory`

  O caminho completo ou relativo para o diretório que contém todos os arquivos a serem adicionados ao arquivo.

`pattern`

  Uma expressão regular pcre opcional usada para filtrar a lista de arquivos. Somente caminhos de arquivo que correspondam à expressão regular serão incluídos no arquivo.

### Valor Retornado

Phar::buildFromDirectory() retorna um array associativo mapeando o caminho interno do arquivo para o caminho completo do arquivo no sistema de arquivos.

### Erros/Exceções

Este método lança BadMethodCallException quando não é possível instanciar os iteradores de diretório interno, ou uma PharException se houver erros ao salvar o arquivo phar.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Phar::buildFromDirectory() não retorna mais `false`.

### Exemplos

Exemplo #1 Um exemplo de Phar::buildFromDirectory()

    <?php
    // cria com o apelido "project.phar"
    $phar = new Phar('project.phar', 0, 'project.phar');
    // adiciona todos os arquivos no projeto
    $phar->buildFromDirectory(dirname(__FILE__) . '/project');
    $phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));

    $phar2 = new Phar('project2.phar', 0, 'project2.phar');
    // adiciona todos os arquivos do projeto, inclui apenas arquivos php
    $phar2->buildFromDirectory(dirname(__FILE__) . '/project', '/\.php$/');
    $phar2->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
    ?>

### Veja Também

- Phar::buildFromIterator() - Constrói um arquivo phar a partir de um iterador

# Phar::buildFromIterator

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::buildFromIterator — Constrói um arquivo phar a partir de um iterador

### Descrição

public function Phar::buildFromIterator(Traversable `$iterator`, ?string `$baseDirectory` = `null`): array

> Nota: Este método requer que a configuração `phar.readonly` do php.ini seja definida como `0` para funcionar com objetos Phar. Caso contrário, uma exceção PharException será lançada.

Preenche um arquivo phar a partir de um iterador. Dois estilos de iteradores são suportados: iteradores que mapeiam o nome do arquivo dentro do phar para o nome de um arquivo em disco, e iteradores como DirectoryIterator, que retornam objetos SplFileInfo. Para iteradores que retornam objetos SplFileInfo, o segundo parâmetro é obrigatório.

### Parâmetros

`iterator`

  Qualquer iterador que mapeia associativamente o arquivo phar para um local ou que retorna objetos SplFileInfo.

`baseDirectory`

  Para iteradores que retornam objetos SplFileInfo, a parte do caminho completo de cada arquivo a ser removida ao adicionar ao arquivo phar.

### Valor Retornado

Phar::buildFromIterator() retorna um array associativo mapeando o caminho interno do arquivo para o caminho completo do arquivo no sistema de arquivos.

### Erros/Exceções

Este método retorna UnexpectedValueException quando o iterador retorna valores incorretos, como uma chave inteira em vez de uma string, uma BadMethodCallException quando um iterador baseado em SplFileInfo é passado sem um parâmetro `baseDirectory` ou uma PharException se houver erros ao salvar o arquivo phar.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Phar::buildFromIterator() não retorna mais `false`.
8.0.0 | `baseDirectory` agora é anulável.

### Exemplos

Exemplo #1 Um exemplo de Phar::buildFromIterator() com SplFileInfo

Para a maioria dos arquivos phar, o arquivo refletirá uma organização de diretório real, e o segundo estilo é o mais útil. Por exemplo, para criar um arquivo phar contendo os arquivos nesta organização de diretório de exemplo:

    /caminho/para/projeto/
                     config/
                            dist.xml
                            debug.xml
                     lib/
                         file1.php
                         file2.php
                     src/
                         processthing.php
                     www/
                         index.php
                     cli/
                         index.php

Este código poderia ser usado para adicionar esses arquivos ao arquivo phar "project.phar":

    <?php
    // cria com apelido "project.phar"
    $phar = new Phar('project.phar', 0, 'project.phar');
    $phar->buildFromIterator(
        new RecursiveIteratorIterator(
         new RecursiveDirectoryIterator('/caminho/para/projeto')),
        '/caminho/para/projeto');
    $phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
    ?>

O arquivo project.phar pode então ser usado imediatamente. Phar::buildFromIterator() não define valores como compressão, metadados, e isso pode ser feito após a criação do arquivo phar.

Como observação interessante, Phar::buildFromIterator() também pode ser usado para copiar o conteúdo de um arquivo phar existente, já que o objeto Phar descende de DirectoryIterator:

    <?php
    // cria com apelido "project.phar"
    $phar = new Phar('project.phar', 0, 'project.phar');
    $phar->buildFromIterator(
        new RecursiveIteratorIterator(
         new Phar('/caminho/para/outro_phar.phar')),
        'phar:///caminho/para/outro_phar.phar/caminho/para/projeto');
    $phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
    ?>

Exemplo #2 Um exemplo de Phar::buildFromIterator() com outros iteradores

A segunda forma do iterador pode ser usada com qualquer iterador que retorne um mapeamento chave => valor, como um ArrayIterator:

    <?php
    // cria com apelido "project.phar"
    $phar = new Phar('project.phar', 0, 'project.phar');
    $phar->buildFromIterator(
        new ArrayIterator(
         array(
            'internos/arquivo.php' => dirname(__FILE__) . '/algum_arquivo.php',
            'outros/arquivo.jpg' => fopen('/caminho/para/arquivo_grande.jpg', 'rb'),
         )));
    $phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
    ?>

### Veja Também

- Phar::buildFromDirectory() - Constrói um arquivo phar a partir dos arquivos dentro de um diretório

# Phar::canCompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::canCompress — Retorna se a extensão phar suporta compactação usando zlib ou bzip2

### Descrição

final public static function Phar::canCompress(int `$compression` = 0): bool

Isso deve ser usado para testar se a compactação é possível antes de carregar um arquivo phar contendo arquivos compactados.

### Parâmetros

`compression`

  Tanto `Phar::GZ` quanto `Phar::BZ2` podem ser usados ​​para testar se a compressão é possível com um algoritmo de compressão específico (zlib ou bzip2).

### Valor Retornado

`true` se a compactação/descompactação estiver disponível, `false` caso contrário.

### Exemplos

Exemplo #1 Um exemplo de Phar::canCompress()

    <?php
    if (Phar::canCompress()) {
        echo file_get_contents('phar://pharcompactado.phar/internos/arquivo.txt');
    } else {
        echo 'nenhuma compactação disponível';
    }
    ?>

### Veja Também

- PharFileInfo::getCompressedSize() - Retorna o tamanho real do arquivo (com compactação) dentro do arquivo Phar
- PharFileInfo::isCompressed() - Informa se a entrada está compactada
- PharFileInfo::compress() - Compacta a entrada Phar atual com zlib ou bzip2
- PharFileInfo::decompress() - Descompacta a entrada Phar atual dentro do phar
- Phar::isCompressed() - Retorna Phar::GZ ou PHAR::BZ2 se todo o arquivo phar estiver compactado (.tar.gz/tar.bz e assim por diante)
- Phar::compressFiles() - Compacta todos os arquivos no arquivo Phar atual
- Phar::decompressFiles() - Descompacta todos os arquivos no arquivo Phar atual
- Phar::getSupportedCompression() - Retorna um array de algoritmos de compactação suportados
- Phar::convertToExecutable() - Converte um arquivo phar em outro formato de arquivo executável phar
- Phar::convertToData() - Converte um arquivo phar em um arquivo tar ou zip não executável

# Phar::canWrite

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::canWrite — Retorna se a extensão phar suporta a escrita e criação de phars

### Descrição

final public static function Phar::canWrite(): bool

Este método estático determina se o acesso de gravação foi desabilitado no sistema php.ini por meio da variável ini phar.readonly.

### Parâmetros

### Valor Retornado

`true` se o acesso de gravação estiver habilitado, `false` se estiver desabilitado.

### Exemplos

Exemplo #1 Um exemplo de Phar::canWrite()

    <?php
    if (Phar::canWrite()) {
        file_put_contents('phar://meuphar.phar/arquivo.txt', 'olá mundo');
    }
    ?>

### Veja Também

- phar.readonly
- Phar::isWritable() - Informa se o arquivo phar pode ser modificado

# Phar::compress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::compress — Compacta todo o arquivo Phar usando compactação Gzip ou Bzip2

### Descrição

public function Phar::compress(int `$compression`, ?string `$extension` = `null`): ?Phar

> Nota: Este método requer que a configuração `phar.readonly` do php.ini seja definida como `0` para funcionar com objetos Phar. Caso contrário, uma exceção PharException será lançada.

Para arquivos PHAR baseados em tar e PHAR, este método compacta o arquivo inteiro usando compactação gzip ou bzip2. O arquivo resultante pode ser processado com o comando gunzip/bunzip ou acessado direta e transparentemente com a extensão Phar.

Para arquivos phar baseados em Zip, este método falha com uma exceção. A extensão zlib deve estar habilitada para compactar com compactação gzip, a extensão bzip2 deve estar habilitada para compactar com compactação bzip2. Como acontece com todas as funcionalidades que modificam o conteúdo de um phar, a variável INI phar.readonly deve estar desativada para funcionar.

Além disso, este método renomeia automaticamente o arquivo, anexando `.gz`, `.bz2` ou removendo a extensão se `Phar::NONE` for passado para remover a compactação. Alternativamente, uma extensão de arquivo pode ser especificada com o segundo parâmetro.

### Parâmetros

`compression`

  A compactação deve ser `Phar::GZ`, `Phar::BZ2` para adicionar compactação ou `Phar::NONE` para remover compactação.

`extension`

  Por padrão, a extensão é `.phar.gz` ou `.phar.bz2` para compactar arquivos phar, e `.phar.tar.gz` ou `.phar.tar.bz2` para compactar arquivos tar. Para descompactação, as extensões de arquivo padrão são `.phar` e `.phar.tar`.

### Valor Retornado

Retorna um objeto Phar ou `null` em caso de falha.

### Erros/Exceções

Lança BadMethodCallException se a variável INI phar.readonly estiver ativada, a extensão zlib não estiver disponível ou a extensão bzip2 não estiver habilitada.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `extension` agora é anulável.

### Exemplos

Exemplo #1 Um exemplo de Phar::compress()

    <?php
    $p = new Phar('/caminho/para/meu.phar', 0, 'meu.phar');
    $p['meuarquivo.txt'] = 'olá';
    $p['meuarquivo2.txt'] = 'olá';
    $p1 = $p->compress(Phar::GZ); // copia para /caminho/para/meu.phar.gz
    $p2 = $p->compress(Phar::BZ2); // copia para /caminho/para/meu.phar.bz2
    $p3 = $p2->compress(Phar::NONE); // exceção: /caminho/para/meu.phar já existe
    ?>

### Veja Também

- PharFileInfo::getCompressedSize() - Retorna o tamanho real do arquivo (com compactação) dentro do arquivo Phar
- PharFileInfo::isCompressed() - Informa se a entrada está compactada
- PharFileInfo::compress() - Compacta a entrada Phar atual com zlib ou bzip2
- PharFileInfo::decompress() - Descompacta a entrada Phar atual dentro do phar
- PharData::compress() - Compacta todo o arquivo tar/zip usando Gzip ou Bzip2
- Phar::canCompress() - Retorna se a extensão phar suporta compactação usando zlib ou bzip2
- Phar::isCompressed() - Retorna Phar::GZ ou PHAR::BZ2 se todo o arquivo phar estiver compactado (.tar.gz/tar.bz e assim por diante)
- Phar::decompress() - Descompacta todo o arquivo Phar
- Phar::getSupportedCompression() - Retorna um array de algoritmos de compactação suportados
- Phar::compressFiles() - Compacta todos os arquivos no arquivo Phar atual
- Phar::decompressFiles() - Descompacta todos os arquivos no arquivo Phar atual

# Phar::compressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::compressFiles — Compacta todos os arquivos no arquivo Phar atual

### Descrição

public function Phar::compressFiles(int `$compression`): void

> Nota: Este método requer que a configuração `phar.readonly` do php.ini seja definida como `0` para funcionar com objetos Phar. Caso contrário, uma exceção PharException será lançada.

Para arquivos phar baseados em tar, este método gera uma BadMethodCallException, pois a compactação de arquivos individuais dentro de um arquivo tar não é suportada pelo formato de arquivo. Use Phar::compress() para compactar um arquivo phar inteiro baseado em tar.

Para arquivos phar baseados em zip e phar, este método compacta todos os arquivos no arquivo Phar usando a compactação especificada. As extensões zlib ou bzip2 devem estar habilitadas para aproveitar este recurso. Além disso, se algum arquivo já estiver compactado usando a compactação bzip2/zlib, a respectiva extensão deve ser habilitada para descompactá-lo antes da compactação. Assim como acontece com todas as funcionalidades que modificam o conteúdo de um arquivo Phar, a variável INI phar.readonly deve estar desativada para funcionar.

### Parâmetros

`compression`

  Deve ser `Phar::GZ`, `Phar::BZ2` para adicionar compactação ou `Phar::NONE` para remover compactação.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

Lança BadMethodCallException se a variável INI phar.readonly estiver ativada, a extensão zlib não estiver disponível ou se algum arquivo estiver compactado usando a compactação bzip2 e a extensão bzip2 não estiver habilitada.

### Exemplos

Exemplo #1 Um exemplo de Phar::compressFiles()

    <?php
    $p = new Phar('/caminho/para/meu.phar', 0, 'meu.phar');
    $p['meuarquivo.txt'] = 'olá';
    $p['meuarquivo2.txt'] = 'olá';
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    $p->compressFiles(Phar::GZ);
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    ?>

O exemplo acima produzirá:

    string(14) "meuarquivo.txt"
    bool(false)
    bool(false)
    bool(false)
    string(15) "meuarquivo2.txt"
    bool(false)
    bool(false)
    bool(false)
    string(14) "meuarquivo.txt"
    int(4096)
    bool(false)
    bool(true)
    string(15) "meuarquivo2.txt"
    int(4096)
    bool(false)
    bool(true)

### Veja Também

- PharFileInfo::getCompressedSize() - Retorna o tamanho real do arquivo (com compactação) dentro do arquivo Phar
- PharFileInfo::isCompressed() - Informa se a entrada está compactada
- PharFileInfo::compress() - Compacta a entrada Phar atual com zlib ou bzip2
- PharFileInfo::decompress() - Descompacta a entrada Phar atual dentro do phar
- Phar::canCompress() - Retorna se a extensão phar suporta compactação usando zlib ou bzip2
- Phar::isCompressed() - Retorna Phar::GZ ou PHAR::BZ2 se todo o arquivo phar estiver compactado (.tar.gz/tar.bz e assim por diante)
- Phar::decompressFiles() - Descompacta todos os arquivos no arquivo Phar atual
- Phar::getSupportedCompression() - Retorna um array de algoritmos de compactação suportados
- Phar::compress() - Compacta todo o arquivo Phar usando compactação Gzip ou Bzip2
- Phar::decompress() - Descompacta todo o arquivo Phar

# Phar::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::__construct — Constrói um objeto de arquivo Phar

### Descrição

public function Phar::__construct(string `$filename`, int `$flags` = FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS, ?string `$alias` = `null`)

### Parâmetros

`filename`

  Caminho para um arquivo Phar existente ou um arquivo a ser criado. A extensão do nome do arquivo deve conter .phar.

`flags`

  Sinalizadores a serem passados ​​para a classe pai RecursiveDirectoryIterator.

`alias`

  Apelido ​​com o qual este arquivo Phar deve ser referenciado em chamadas para funcionalidade de fluxo.

### Erros/Exceções

Lança BadMethodCallException se chamado duas vezes, UnexpectedValueException se o arquivo phar não puder ser aberto.

### Exemplos

Exemplo #1 Um exemplo de Phar::__construct()

    <?php
    try {
        $p = new Phar('/caminho/para/meu.phar', FilesystemIterator::CURRENT_AS_FILEINFO | FilesystemIterator::KEY_AS_FILENAME,
                      'meu.phar');
    } catch (UnexpectedValueException $e) {
        die('Não foi possível abrir meu.phar');
    } catch (BadMethodCallException $e) {
        echo 'tecnicamente, isso não pode acontecer';
    }
    // isso funciona agora
    echo file_get_contents('phar://meu.phar/exemplo.txt');
    // e funciona como se tivesse sido digitado
    echo file_get_contents('phar:///caminho/para/meu.phar/exemplo.txt');
    ?>

# Phar::convertToData

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::convertToData — Converte um arquivo phar em um arquivo tar ou zip não executável

### Descrição

public function Phar::convertToData(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?PharData

Este método é usado para converter um arquivo executável phar em um arquivo tar ou zip. Para tornar o tar ou zip não executável, o stub phar e os arquivos de alias phar são removidos do arquivo recém-criado.

Se nenhuma alteração for especificada, este método lança uma BadMethodCallException se o arquivo estiver no formato phar. Para arquivos no formato tar ou zip, este método converte o arquivo em um arquivo não executável.

Se bem-sucedido, o método cria um novo arquivo no disco e retorna um objeto PharData. O arquivo antigo não é removido do disco e deve ser removido manualmente após a conclusão do processo.

### Parâmetros

`format`

  Deve ser um dos seguintes: `Phar::TAR` ou `Phar::ZIP`. Se definido como `null`, o formato de arquivo existente será preservado.

`compression`

  Deve ser um dos seguintes: `Phar::NONE` para nenhuma compactação de arquivo, `Phar::GZ` para compactação baseada em zlib e `Phar::BZ2` para compactação baseada em bzip.

`extension`

  Este parâmetro é usado para substituir a extensão de arquivo padrão para um arquivo convertido. Observe que `.phar` não pode ser usado em nenhum lugar no nome do arquivo para um arquivo tar ou zip não executável.

  Ao converter para um arquivo phar baseado em tar, as extensões padrão são `.tar`, `.tar.gz`, e `.tar.bz2`, dependendo da compactação especificada. Para arquivos baseados em zip, a extensão padrão é `.zip`.

### Valor Retornado

O método retorna um objeto PharData em caso de sucesso, ou `null` em caso de falha.

### Erros/Exceções

Este método lança BadMethodCallException quando não é possível compactar, um método de compactação desconhecido foi especificado, o arquivo solicitado está armazenando em buffer com Phar::startBuffering() e não foi concluído com Phar::stopBuffering(), e uma PharException se algum problema for encontrado durante o processo de criação do phar.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `format`, `compression` e `extension` agora são anuláveis.

### Exemplos

Exemplo #1 Um exemplo de Phar::convertToData()

Using Phar::convertToData():

    <?php
    try {
        $tarphar = new Phar('meuphar.phar.tar');
        // observe que meuphar.phar.tar *não* é excluído
        // converte para o formato de arquivo tar não executável
        // cria meuphar.tar
        $tar = $tarphar->convertToData();
        // converte para formato zip não executável, cria meuphar.zip
        $zip = $tarphar->convertToData(Phar::ZIP);
        // cria meuphar.tbz
        $tgz = $tarphar->convertToData(Phar::TAR, Phar::BZ2, '.tbz');
        // cria meuphar.phar.tgz
        $phar = $tarphar->convertToData(Phar::PHAR); // lança exceção
    } catch (Exception $e) {
        // manipula os erros aqui
    }
    ?>

### Veja Também

- Phar::convertToExecutable() - Converte um arquivo phar em outro formato de arquivo executável phar
- PharData::convertToExecutable() - Converte um arquivo tar/zip não executável em um arquivo phar executável
- PharData::convertToData() - Converte um arquivo phar em um arquivo tar ou zip não executável

# Phar::convertToExecutable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::convertToExecutable — Converte um arquivo phar em outro formato de arquivo executável phar

### Descrição

public function Phar::convertToExecutable(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?Phar

> Nota: Este método requer que a configuração `phar.readonly` do php.ini seja definida como `0` para funcionar com objetos Phar. Caso contrário, uma exceção PharException será lançada.

Este método é usado para converter um arquivo PHAR para outro formato de arquivo. Por exemplo, ele pode ser usado para criar um arquivo PHAR executável baseado em tar a partir de um arquivo PHAR executável em zip ou de um arquivo PHAR executável no formato PHAR. Além disso, ele pode ser usado para aplicar compactação de todo o arquivo a um arquivo baseado em tar ou PHAR.

Se nenhuma alteração for especificada, este método lançará uma BadMethodCallException.

Se bem-sucedido, o método cria um novo arquivo no disco e retorna um objeto Phar. O arquivo antigo não é removido do disco e deve ser removido manualmente após a conclusão do processo.

### Parâmetros

`format`

  Deve ser um dos seguintes: `Phar::PHAR`, `Phar::TAR`, ou `Phar::ZIP`. Se definido como `null`, o formato de arquivo existente será preservado.

`compression`

  Deve ser um dos seguintes: `Phar::NONE` para nenhuma compactação de arquivo inteiro, `Phar::GZ` para compactação baseada em zlib e `Phar::BZ2` para compactação baseada em bzip.

`extension`

  Este parâmetro é usado para substituir a extensão de arquivo padrão para um arquivo convertido. Observe que todos os arquivos phar baseados em zip e tar devem conter `.phar` em sua extensão para serem processados ​​como um arquivo phar.

  Ao converter para um arquivo baseado em PHAR, as extensões padrão são `.phar`, `.phar.gz` ou `.phar.bz2` dependendo da compactação especificada. Para arquivos PHAR baseados em tar, as extensões padrão são `.phar.tar`, `.phar.tar.gz` e `.phar.tar.bz2`. Para arquivos PHAR baseados em ZIP, a extensão padrão é `.phar.zip`.

### Valor Retornado

O método retorna um objeto Phar em caso de sucesso, ou `null` em caso de falha.

### Erros/Exceções

Este método lança uma BadMethodCallException quando não é possível compactar, um método de compactação desconhecido foi especificado, o arquivo solicitado está armazenando em buffer com Phar::startBuffering() e não foi concluído com Phar::stopBuffering(); uma UnexpectedValueException se o suporte à gravação estiver desabilitado; e uma PharException se algum problema for encontrado durante o processo de criação do phar.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `format`, `compression` e `extension` agora são anuláveis.

### Exemplos

Exemplo #1 Um exemplo de Phar::convertToExecutable()

Using Phar::convertToExecutable():

    <?php
    try {
        $tarphar = new Phar('meuphar.phar.tar');
        // converte para o formato de arquivo phar
        // observe que meuphar.phar.tar *não* é excluído
        $phar = $tarphar->convertToExecutable(Phar::PHAR); // cria meuphar.phar
        $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
        // cria meuphar.phar.tgz
        $compressed = $phar->convertToExecutable(Phar::TAR, Phar::GZ, '.phar.tgz');
    } catch (Exception $e) {
        // lida com o erro aqui
    }
    ?>

### Veja Também

- Phar::convertToData() - Converte um arquivo phar em um arquivo tar ou zip não executável
- PharData::convertToExecutable() - Converte um arquivo tar/zip não executável em um arquivo phar executável
- PharData::convertToData() - Converte um arquivo phar em um arquivo tar ou zip não executável

# Phar::copy

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::copy — Copia um arquivo interno do arquivo phar para outro novo arquivo dentro do phar

### Descrição

public function Phar::copy(string `$from`, string `$to`): true

> Nota: Este método requer que a configuração `phar.readonly` do php.ini seja definida como `0` para funcionar com objetos Phar. Caso contrário, uma exceção PharException será lançada.

Copia um arquivo interno do arquivo phar para outro novo arquivo dentro do phar. Esta é uma alternativa orientada a objetos ao uso de copy() com o empacotador de fluxo phar.

### Parâmetros

`from`

`to`

### Valor Retornado

Sempre retorna `true`.

### Erros/Exceções

Lança uma UnexpectedValueException se o arquivo de origem não existir, se o arquivo de destino já existir, se o acesso de gravação estiver desabilitado, se a abertura do arquivo falhar, se a leitura do arquivo de origem falhar ou uma PharException se a gravação das alterações no arquivo phar falhar.

### Exemplos

Exemplo #1 Um exemplo de Phar::copy()

Este exemplo mostra o uso de Phar::copy() e o desempenho equivalente do empacotador de fluxo para a mesma coisa. A principal diferença entre as duas abordagens é o tratamento de erros. Todos os métodos Phar geram exceções, enquanto o empacotador de fluxo usa trigger_error().

    <?php

    try {
        $phar = new Phar('meuphar.phar');

        $phar['a'] = 'olá';
        $phar->copy('a', 'b');

        echo $phar['b']; // Exibe "phar://meuphar.phar/b"
    } catch (Exception $e) {
        // Lida com o erro
    }

    // O empacotador de fluxo equivalente ao código acima.
    // E_WARNING são acionados em caso de erro em vez de uma exceção
    copy('phar://meuphar.phar/a', 'phar//meuphar.phar/c');
    echo file_get_contents('phar://meuphar.phar/c'); // Exibe "olá"

    ?>

# Phar::count

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::count — Retorna o número de entradas (arquivos) no arquivo Phar

### Descrição

public function Phar::count(int `$mode` = `COUNT_NORMAL`): int

### Parâmetros

`mode`

  `mode` é um valor inteiro que especifica o modo de contagem a ser usado. Por padrão, é definido como `COUNT_NORMAL`, que conta apenas o número de itens no arquivo que não foram excluídos ou ocultados. Quando definido como `COUNT_RECURSIVE`, conta todos os itens no arquivo, incluindo aqueles que foram excluídos ou ocultados.

### Valor Retornado

O número de arquivos contidos neste phar, ou `0` (o número zero) se não houver nenhum.

### Exemplos

Exemplo #1 Um exemplo de Phar::count()

    <?php
    // garantindo que o arquivo não existe
    @unlink('brandnewphar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
    } catch (Exception $e) {
        echo 'Não foi possível criar o phar:', $e;
    }
    echo 'O novo phar tem ' . $p->count() . " entradas\n";
    $p['file.txt'] = 'olá';
    echo 'O novo phar tem ' . $p->count() . " entradas\n";
    ?>

O exemplo acima produzirá:

    O novo phar tem 0 entradas
    O novo phar tem 1 entradas

# Phar::createDefaultStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::createDefaultStub — Cria um stup de formato específico de arquivo phar

### Descrição

final public static function Phar::createDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): string

Este método destina-se à criação de stubs específicos para o formato de arquivo phar e não se destina ao uso com arquivos phar baseados em tar ou zip.

Os arquivos Phar contêm um carregador de inicialização, ou `stub` escrito em PHP que é executado quando o arquivo é executado em PHP, seja por meio de include:

    <?php
    include 'meuphar.phar';
    ?>

ou por execução direta:

    php meuphar.phar

Este método fornece uma maneira simples e fácil de criar um stub que irá executar um arquivo de inicialização a partir do arquivo phar. Além disso, arquivos diferentes podem ser especificados para executar o arquivo phar a partir da linha de comando ou através de um servidor web. O stub do carregador também chama Phar::interceptFileFuncs() para permitir o agrupamento fácil de uma aplicação PHP que acessa o sistema de arquivos. Se a extensão phar não estiver presente, o stub do carregador extrairá o arquivo phar para um diretório temporário e, em seguida, operará nos arquivos. Uma função de desligamento apaga os arquivos temporários ao sair.

### Parâmetros

`index`

  Caminho relativo dentro do arquivo phar para execução se acessado na linha de comando

`webIndex`

  Caminho relativo dentro do arquivo phar para ser executado se acessado por meio de um navegador da web

### Valor Retornado

Retorna uma string contendo o conteúdo de um carregador de inicialização personalizado (stub) que permite que o arquivo Phar criado funcione com ou sem a extensão Phar habilitada.

### Erros/Exceções

Lança UnexpectedValueException se qualquer parâmetro for maior que 400 bytes.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `index` e `webIndex` agora são anuláveis.

### Exemplos

Exemplo #1 Um exemplo de Phar::createDefaultStub()

    <?php
    try {
        $phar = new Phar('meuphar.phar');
        $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
    } catch (Exception $e) {
        // lida com os erros
    }
    ?>

### Veja Também

- Phar::setStub() - Usado para definir o carregador PHP ou o stub de inicialização de um arquivo Phar
- Phar::getStub() - Retorna o carregador PHP ou o stub de inicialização de um arquivo Phar

# Phar::decompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::decompress — Descompacta todo o arquivo Phar

### Descrição

public function Phar::decompress(?string `$extension` = `null`): ?Phar

> Nota: Este método requer que a configuração `phar.readonly` do php.ini seja definida como `0` para funcionar com objetos Phar. Caso contrário, uma exceção PharException será lançada.

Para arquivos phar baseados em tar e phar, esse método descompacta o arquivo inteiro.

Para arquivos phar baseados em Zip, este método falha com uma exceção. A extensão zlib deve ser habilitada para descompactar um arquivo compactado com compactação gzip, e a extensão bzip2 deve ser habilitada para descompactar um arquivo compactado com compactação bzip2. Como acontece com todas as funcionalidades que modificam o conteúdo de um phar, a variável INI phar.readonly deve estar desativada para ter sucesso.

Além disso, este método altera automaticamente a extensão do arquivo, `.phar` por padrão para arquivos phar, ou `.phar.tar` para arquivos phar baseados em tar. Alternativamente, uma extensão de arquivo pode ser especificada com o segundo parâmetro.

### Parâmetros

`extension`

  Para descompactação, as extensões de arquivo padrão são `.phar` e `.phar.tar`. Use este parâmetro para especificar outra extensão de arquivo. Esteja ciente de que todos os arquivos executáveis ​​phar devem conter `.phar` em seus nomes.

### Valor Retornado

Um objeto Phar é retornado em caso de sucesso e `null` em caso de falha.

### Erros/Exceções

Lança BadMethodCallException se a variável INI phar.readonly estiver ativada, se a extensão zlib não estiver disponível ou se a extensão bzip2 não estiver habilitada.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `extension` agora é anulável.

### Exemplos

Exemplo #1 Um exemplo de Phar::decompress()

    <?php
    $p = new Phar('/caminho/para/meu.phar', 0, 'meu.phar.gz');
    $p['meuarquivo.txt'] = 'olá';
    $p['meuarquivo2.txt'] = 'olá';
    $p3 = $p2->decompress(); // cria /caminho/para/meu.phar
    ?>

### Veja Também

- PharFileInfo::getCompressedSize() - Retorna o tamanho real do arquivo (com compactação) dentro do arquivo Phar
- PharFileInfo::isCompressed() - Informa se a entrada está compactada
- PharFileInfo::compress() - Compacta a entrada Phar atual com zlib ou bzip2
- PharFileInfo::decompress() - Descompacta a entrada Phar atual dentro do phar
- PharData::compress() - Compacta todo o arquivo tar/zip usando Gzip ou Bzip2
- Phar::canCompress() - Retorna se a extensão phar suporta compactação usando zlib ou bzip2
- Phar::isCompressed() - Retorna Phar::GZ ou PHAR::BZ2 se todo o arquivo phar estiver compactado (.tar.gz/tar.bz e assim por diante)
- Phar::compress() - Compacta todo o arquivo Phar usando compactação Gzip ou Bzip2
- Phar::getSupportedCompression() - Retorna um array de algoritmos de compactação suportados
- Phar::compressFiles() - Compacta todos os arquivos no arquivo Phar atual
- Phar::decompressFiles() - Descompacta todos os arquivos no arquivo Phar atual

# Phar::decompressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::decompressFiles — Descompacta todos os arquivos no arquivo Phar atual

### Descrição

public function Phar::decompressFiles(): true

> Nota: Este método requer que a configuração `phar.readonly` do php.ini seja definida como `0` para funcionar com objetos Phar. Caso contrário, uma exceção PharException será lançada.

Para arquivos PHAR baseados em tar, este método gera uma BadMethodCallException, pois a compactação de arquivos individuais dentro de um arquivo tar não é suportada pelo formato de arquivo. Use Phar::compress() para compactar um arquivo PHAR baseado em tar inteiro.

Para arquivos phar baseados em Zip e phar, este método descompacta todos os arquivos no arquivo Phar. As extensões zlib ou bzip2 devem ser habilitadas para aproveitar este recurso caso algum arquivo seja compactado usando a compactação bzip2/zlib. Assim como acontece com todas as funcionalidades que modificam o conteúdo de um phar, a variável INI phar.readonly deve estar desativada para funcionar.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Sempre retorna `true`.

### Erros/Exceções

Lança BadMethodCallException se a variável INI phar.readonly estiver ativada, a extensão zlib não estiver disponível ou se algum arquivo estiver compactado usando a compactação bzip2 e a extensão bzip2 não estiver habilitada.

### Exemplos

Exemplo #1 Um exemplo de Phar::decompressFiles()

    <?php
    $p = new Phar('/caminho/para/meu.phar', 0, 'meu.phar');
    $p['meuarquivo.txt'] = 'olá';
    $p['meuarquivo2.txt'] = 'olá';
    $p->compressFiles(Phar::GZ);
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    $p->decompressFiles();
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    ?>

O exemplo acima produzirá:

    string(14) "meuarquivo.txt"
    int(4096)
    bool(false)
    bool(true)
    string(15) "meuarquivo2.txt"
    int(4096)
    bool(false)
    bool(true)
    string(14) "meuarquivo.txt"
    bool(false)
    bool(false)
    bool(false)
    string(15) "meuarquivo2.txt"
    bool(false)
    bool(false)
    bool(false)

### Veja Também

- PharFileInfo::getCompressedSize() - Retorna o tamanho real do arquivo (com compactação) dentro do arquivo Phar
- PharFileInfo::isCompressed() - Informa se a entrada está compactada
- PharFileInfo::compress() - Compacta a entrada Phar atual com zlib ou bzip2
- PharFileInfo::decompress() - Descompacta a entrada Phar atual dentro do phar
- Phar::canCompress() - Retorna se a extensão phar suporta compactação usando zlib ou bzip2
- Phar::isCompressed() - Retorna Phar::GZ ou PHAR::BZ2 se todo o arquivo phar estiver compactado (.tar.gz/tar.bz e assim por diante)
- Phar::compressFiles() - Compacta todos os arquivos no arquivo Phar atual
- Phar::getSupportedCompression() - Retorna um array de algoritmos de compactação suportados
- Phar::compress() - Compacta todo o arquivo Phar usando compactação Gzip ou Bzip2
- Phar::decompress() - Descompacta todo o arquivo Phar

# Phar::delMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::delMetadata — Exclui os metadados globais do phar

### Descrição

public function Phar::delMetadata(): true

> Nota: Este método requer que a configuração `phar.readonly` do php.ini seja definida como `0` para funcionar com objetos Phar. Caso contrário, uma exceção PharException será lançada.

Exclui os metadados globais do phar.

### Parâmetros

### Valor Retornado

Sempre retorna `true`.

### Erros/Exceções

Lança PharException se ocorrerem erros durante a descarga de alterações no disco.

### Exemplos

Exemplo #1 Um exemplo de Phar::delMetaData()

    <?php
    try {
        $phar = new Phar('meuphar.phar');
        var_dump($phar->getMetadata());
        $phar->setMetadata("olá mundo");
        var_dump($phar->getMetadata());
        $phar->delMetadata();
        var_dump($phar->getMetadata());
    } catch (Exception $e) {
        // lida com erros
    }
    ?>

O exemplo acima produzirá:

    NULL
    string(9) "olá mundo"
    NULL

### Veja Também

- Phar::getMetadata() - Retorna metadados do arquivo phar
- Phar::setMetadata() - Define metadados do arquivo phar
- Phar::hasMetadata() - Informa se o phar tem metadados globais

# Phar::delete

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::delete — Exclui um arquivo dentro de um arquivo phar

### Descrição

public function Phar::delete(string `$localName`): true

> Nota: Este método requer que a configuração `phar.readonly` do php.ini seja definida como `0` para funcionar com objetos Phar. Caso contrário, uma exceção PharException será lançada.

Exclui um arquivo dentro de um arquivo compactado. Este é o equivalente funcional de chamar unlink() no equivalente do empacotador de fluxo, como mostrado no exemplo abaixo.

### Parâmetros

`localName`

  Caminho dentro de um arquivo para o arquivo a ser excluído.

### Valor Retornado

Sempre retorna `true`.

### Erros/Exceções

Lança PharException se ocorrerem erros durante a descarga de alterações no disco.

### Exemplos

Exemplo #1 Um exemplo de Phar::delete()

    <?php
    try {
        $phar = new Phar('meuphar.phar');
        $phar->delete('unlink/eu.php');
        // isso é equivalente a:
        unlink('phar://meuphar.phar/unlink/eu.php');
    } catch (Exception $e) {
        // lida com erros
    }
    ?>

### Veja Também

- PharData::delete() - Exclui um arquivo dentro de um arquivo tar/zip
- Phar::unlinkArchive() - Remove completamente um arquivo phar do disco e da memória

# Phar::__destruct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::__destruct — Destrói um objeto de arquivo Phar

### Descrição

public function Phar::__destruct()

### Parâmetros

Esta função não possui parâmetros.

# Phar::extractTo

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::extractTo — Extrai o conteúdo de um arquivo phar para um diretório

### Descrição

public function Phar::extractTo(string `$directory`, array|string|null `$files` = `null`, bool `$overwrite` = `false`): bool

Extrai todos os arquivos de um arquivo phar para o disco. Os arquivos e diretórios extraídos preservam as permissões conforme armazenadas no arquivo. Os parâmetros opcionais permitem controle opcional sobre quais arquivos são extraídos e se os arquivos existentes no disco podem ser sobrescritos. O segundo parâmetro `files` pode ser o nome de um arquivo ou diretório a ser extraído, ou um array de nomes de arquivos e diretórios a serem extraídos. Por padrão, este método não sobrescreve arquivos existentes; o terceiro parâmetro pode ser definido como true para habilitar a sobrescrita de arquivos. Este método é semelhante a ZipArchive::extractTo().

### Parâmetros

`directory`

  Caminho para o qual os arquivos informados em `files` serão extraídos.

`files`

  O nome de um arquivo ou diretório a ser extraído ou um array de arquivos/diretórios a serem extraídos; `null` para pular este parâmetro.

`overwrite`

  Defina como `true` para habilitar a substituição de arquivos existentes

### Valor Retornado

Retorna `true` em caso de sucesso, mas é melhor verificar por exceções e assumir sucesso se nenhuma tiver sido lançada.

### Erros/Exceções

Lança PharException se ocorrerem erros durante a descarga de alterações no disco.

### Exemplos

Exemplo #1 Um exemplo de Phar::extractTo()

    <?php
    try {
        $phar = new Phar('meuphar.phar');
        $phar->extractTo('/caminho/completo'); // extrai todos os arquivos
        $phar->extractTo('/caminho/alternativo', 'arquivo.txt'); // extrai somente arquivo.txt
        $phar->extractTo('/este/caminho',
            array('arquivo1.txt', 'arquivo2.txt')); // extrai somente 2 arquivos
        $phar->extractTo('/terceiro/caminho', null, true); // extrai todos os arquivos e sobrescreve
    } catch (Exception $e) {
        // lida com erros
    }
    ?>

### Notas

> Nota: O sistema de arquivos NTFS do Windows não suporta alguns caracteres em nomes de arquivos, como `<|>*?":`. Nomes de arquivos que terminam com ponto também não são suportados. Ao contrário de algumas ferramentas de extração, este método não substitui estes caracteres por um sublinhado, mas falha ao extrair esses arquivos.

### Veja Também

- PharData::extractTo() - Extrai o conteúdo de um arquivo tar/zip para um diretório

# Phar::getAlias

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.1)

Phar::getAlias — Obtém o apelido para o Phar

### Descrição

public function Phar::getAlias(): ?string

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o apelido ou `null` se não houver apelido.

# Phar::getMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getMetadata — Retorna metadados do arquivo phar

### Descrição

public function Phar::getMetadata(array `$unserializeOptions` = []): mixed

Recupera metadados de arquivo. Metadados podem ser qualquer variável PHP que possa ser serializada.

Cuidado

Accessar os metadados iniciará a desserialização, que pode ativar a execução de código PHP arbitrário. Não use isso em arquivos phar não confiáveis ou configure o parâmetro `unserializeOptions` de maneira segura.

### Parâmetros

Sem parâmetros.

### Valor Retornado

Qualquer valor PHP que possa ser serializado e armazenado como metadados para o arquivo Phar, ou `null` se nenhum metadado tiver sido armazenado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `unserializeOptions` foi adicionado.

### Exemplos

Exemplo #1 Um exemplo de Phar::getMetadata()

    <?php
    // garantindo que o arquivo não existe
    @unlink('novophar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/novophar.phar', 0, 'novophar.phar');
        $p['arquivo.php'] = '<?php echo "olá";';
        $p->setMetadata(array('bootstrap' => 'arquivo.php'));
        var_dump($p->getMetadata());
    } catch (Exception $e) {
        echo 'Não foi possível modificar o phar:', $e;
    }
    ?>

O exemplo acima produzirá:

    array(1) {
      ["bootstrap"]=>
      string(11) "arquivo.php"
    }

### Veja Também

- Phar::setMetadata() - Define metadados do arquivo phar
- Phar::delMetadata() - Exclui os metadados globais do phar
- Phar::hasMetadata() - Informa se o phar tem metadados globais

# Phar::getModified

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getModified — Informa se o phar foi modificado

### Descrição

public function Phar::getModified(): bool

Este método pode ser usado para determinar se um phar teve um arquivo interno excluído ou o conteúdo de um arquivo alterado de alguma forma.

### Parâmetros

Sem parâmetros.

### Valor Retornado

`true` se o phar foi modificado desde que foi aberto, `false` caso contrário.

# Phar::getPath

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Phar::getPath — Obtém o caminho real para o arquivo Phar no disco

### Descrição

public function Phar::getPath(): string

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# Phar::getSignature

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getSignature — Retorna a assinatura MD5/SHA1/SHA256/SHA512/OpenSSL de um arquivo Phar

### Descrição

public function Phar::getSignature(): array|false

Retorna a assinatura de verificação de um arquivo phar em uma string hexadecimal.

### Parâmetros

### Valor Retornado

Array com a assinatura do arquivo aberto na chave `hash` e `MD5`, `SHA-1`, `SHA-256`, `SHA-512` ou `OpenSSL` em `hash_type`. Esta assinatura é um hash calculado sobre todo o conteúdo do arquivo phar e pode ser usada para verificar a integridade do arquivo. Uma assinatura válida é absolutamente necessária para todos os arquivos phar executáveis ​​se a variável INI phar.require_hash estiver definida como true. Se não houver assinatura, a função retornará `false`.

# Phar::getStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getStub — Retorna o carregador PHP ou o stub de inicialização de um arquivo Phar

### Descrição

public function Phar::getStub(): string

Os arquivos Phar contêm um carregador bootstrap, ou `stub` escrito em PHP que é executado quando o arquivo é executado em PHP, seja por meio de include:

    <?php
    include 'meuphar.phar';
    ?>

ou por execução simples:

    php meuphar.phar

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string contendo o conteúdo do carregador bootstrap (stub) do arquivo Phar atual.

### Erros/Exceções

Lança RuntimeException se não for possível ler o stub do arquivo Phar.

### Exemplos

Exemplo #1 Um exemplo de Phar::getStub()

    <?php
    $p = new Phar('/caminho/para/meu.phar', 0, 'meu.phar');
    echo $p->getStub();
    echo "==NEXT==\n";
    $p->setStub("<?php
    function __autoload($class)
    {
        include 'phar://' . str_replace('_', '/', $class);
    }
    Phar::mapPhar('meuphar.phar');
    include 'phar://meuphar.phar/startup.php';
    __HALT_COMPILER(); ?>");
    echo $p->getStub();
    ?>

O exemplo acima produzirá:

    <?php __HALT_COMPILER(); ?>
    ==NEXT==
    <?php
    function __autoload($class)
    {
        include 'phar://' . str_replace('_', '/', $class);
    }
    Phar::mapPhar('meuphar.phar');
    include 'phar://meuphar.phar/startup.php';
    __HALT_COMPILER(); ?>

### Veja Também

- Phar::setStub() - Usado para definir o carregador PHP ou o stub de inicialização de um arquivo Phar
- Phar::createDefaultStub() - Cria um stup de formato específico de arquivo phar

# Phar::getSupportedCompression

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::getSupportedCompression — Retorna um array de algoritmos de compactação suportados

### Descrição

final public static function Phar::getSupportedCompression(): array

### Parâmetros

Sem parâmetros.

### Valor Retornado

Retorna um array contendo qualquer um dos seguintes: `Phar::GZ` ou `Phar::BZ2`, dependendo da disponibilidade da extensão zlib ou da extensão bz2.

### Veja Também

- PharFileInfo::getCompressedSize() - Retorna o tamanho real do arquivo (com compactação) dentro do arquivo Phar
- PharFileInfo::isCompressed() - Informa se a entrada está compactada
- PharFileInfo::compress() - Compacta a entrada Phar atual com zlib ou bzip2
- PharFileInfo::decompress() - Descompacta a entrada Phar atual dentro do phar
- Phar::compress() - Compacta todo o arquivo Phar usando compactação Gzip ou Bzip2
- Phar::decompress() - Descompacta todo o arquivo Phar
- Phar::canCompress() - Retorna se a extensão phar suporta compactação usando zlib ou bzip2
- Phar::isCompressed() - Retorna Phar::GZ ou PHAR::BZ2 se todo o arquivo phar estiver compactado (.tar.gz/tar.bz e assim por diante)
- Phar::compressFiles() - Compacta todos os arquivos no arquivo Phar atual
- Phar::decompressFiles() - Descompacta todos os arquivos no arquivo Phar atual

# Phar::getSupportedSignatures

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.1.0)

Phar::getSupportedSignatures — Retorna um array de tipos de assinatura suportados

### Descrição

final public static function Phar::getSupportedSignatures(): array

Retorna um array de tipos de assinatura suportados.

### Parâmetros

Sem parâmetros.

### Valor Retornado

Retorna um array contendo qualquer um dos seguintes: `MD5`, `SHA-1`, `SHA-256`, `SHA-512` ou `OpenSSL`.

### Veja Também

- Phar::getSignature() - Retorna a assinatura MD5/SHA1/SHA256/SHA512/OpenSSL de um arquivo Phar
- Phar::setSignatureAlgorithm() - Define o algoritmo de assinatura para um phar e o aplica

# Phar::getVersion

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getVersion — Retorna informações da versão do arquivo Phar

### Descrição

public function Phar::getVersion(): string

Retorna a versão da API de um arquivo Phar aberto.

### Parâmetros

### Valor Retornado

A versão da API do arquivo aberto. Não deve ser confundida com a versão da API que a extensão phar carregada usará para criar novos phars. Cada arquivo Phar tem a versão da API codificada em seu manifesto. Consulte a documentação do formato de arquivo Phar para obter mais informações.

### Veja Também

- Phar::apiVersion() - Retorna a versão da API

# Phar::hasMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::hasMetadata — Informa se o phar tem metadados globais

### Descrição

public function Phar::hasMetadata(): bool

Informa se o phar tem metadados globais definidos.

### Parâmetros

Sem parâmetros.

### Valor Retornado

Retorna `true` se os metadados foram definidos e `false` caso contrário.

### Exemplos

Exemplo #1 Um exemplo de Phar::hasMetadata()

    <?php
    try {
        $phar = new Phar('meuphar.phar');
        var_dump($phar->hasMetadata());
        $phar->setMetadata(array('teste' => 'olá'));
        var_dump($phar->hasMetadata());
        $phar->delMetadata();
        var_dump($phar->hasMetadata());
    } catch (Exception $e) {
        // lida com erros
    }
    ?>

O exemplo acima produzirá:

    bool(false)
    bool(true)
    bool(false)

### Veja Também

- Phar::getMetadata() - Retorna metadados do arquivo phar
- Phar::setMetadata() - Define metadados do arquivo phar
- Phar::delMetadata() - Exclui os metadados globais do phar

# Phar::interceptFileFuncs

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::interceptFileFuncs — Instrui phar a interceptar fopen, file_get_contents, opendir e todas as funções relacionadas a stat

### Descrição

final public static function Phar::interceptFileFuncs(): void

Instrui o phar a interceptar fopen(), readfile(), file_get_contents(), opendir() e todas as funções relacionadas a stat. Se qualquer uma dessas funções for chamada de dentro de um arquivo phar com um caminho relativo, a chamada será modificada para acessar um arquivo dentro do arquivo phar. Caminhos absolutos são considerados tentativas de carregar arquivos externos do sistema de arquivos.

Esta função possibilita executar aplicações PHP projetadas para rodar em um disco rígido como uma aplicação PHAR.

### Parâmetros

Sem parâmetros.

### Valor Retornado

### Exemplos

Exemplo #1 Um exemplo de Phar::interceptFileFuncs()

    <?php
    Phar::interceptFileFuncs();
    include 'phar://' . __FILE__ . '/file.php';
    ?>

Supondo que este phar esteja em `/path/to/myphar.phar` e contenha `file.php` e `file2.txt`, se `file.php` contiver este código:

Exemplo #2 Um exemplo de Phar::interceptFileFuncs()

    <?php
    echo file_get_contents('file2.txt');
    ?>

Normalmente, o PHP pesquisaria o diretório atual por `file2.txt`, que seria traduzido como o diretório de file.php ou o diretório atual de um usuário de linha de comando. Phar::interceptFileFuncs() instrui o PHP a considerar o diretório atual como `phar:///path/to/myphar.phar/` e, assim, abre `phar:///path/to/myphar.phar/file2.txt` no código de exemplo acima.

# Phar::isBuffering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::isBuffering — Usado para determinar se as operações de gravação Phar estão sendo armazenadas em buffer ou estão sendo liberadas diretamente no disco

### Descrição

public function Phar::isBuffering(): bool

Este método pode ser usado para determinar se um Phar salvará as alterações no disco imediatamente ou se uma chamada para Phar::stopBuffering() é necessária para permitir o salvamento das alterações.

O buffer de gravação Phar é por arquivo, o buffer ativo para o arquivo Phar `foo.phar` não afeta as alterações no arquivo Phar `bar.phar`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se as operações de gravação estão sendo armazenadas em buffer, `false` caso contrário.

### Exemplos

Exemplo #1 Um exemplo de Phar::isBuffering()

    <?php
    $p = new Phar(dirname(__FILE__) . '/novo.phar', 0, 'novo.phar');
    $p2 = new Phar('pharexistente.phar');
    $p['arquivo1.txt'] = 'olá';
    var_dump($p->isBuffering());
    var_dump($p2->isBuffering());
    ?>
    =2=
    <?php
    $p->startBuffering();
    var_dump($p->isBuffering());
    var_dump($p2->isBuffering());
    $p->stopBuffering();
    ?>
    =3=
    <?php
    var_dump($p->isBuffering());
    var_dump($p2->isBuffering());
    ?>

O exemplo acima produzirá:

    bool(false)
    bool(false)
    =2=
    bool(true)
    bool(false)
    =3=
    bool(false)
    bool(false)

### Veja Também

- Phar::startBuffering() - Inicia o buffer das operações de gravação Phar, não modifica o objeto Phar no disco
- Phar::stopBuffering() - Interrompe o buffer de solicitações de gravação no arquivo Phar e salva as alterações no disco

# Phar::isCompressed

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::isCompressed — Retorna Phar::GZ ou PHAR::BZ2 se todo o arquivo phar estiver compactado (.tar.gz/tar.bz e assim por diante)

### Descrição

public function Phar::isCompressed(): int|false

> Nota: Este método requer que a configuração `phar.readonly` do php.ini seja definida como `0` para funcionar com objetos Phar. Caso contrário, uma exceção PharException será lançada.

Retorna Phar::GZ ou PHAR::BZ2 se todo o arquivo phar estiver compactado (.tar.gz/tar.bz e assim por diante). Arquivos phar baseados em ZIP não podem ser compactados como um arquivo e, portanto, este método sempre retornará `false` se um arquivo phar baseado em ZIP for consultado.

### Parâmetros

Sem parâmetros.

### Valor Retornado

`Phar::GZ`, `Phar::BZ2` ou `false`.

### Exemplos

Exemplo #1 Um exemplo de Phar::isCompressed()

    <?php
    try {
        $phar1 = new Phar('meuphar.zip.phar');
        var_dump($phar1->isCompressed());
        $phar2 = new Phar('meudescompactado.tar.phar');
        var_dump($phar2->isCompressed());
        $phar2->compress(Phar::GZ);
        var_dump($phar2->isCompressed() == Phar::GZ);
    } catch (Exception $e) {
    }
    ?>

O exemplo acima produzirá:

    bool(false)
    bool(false)
    bool(true)

### Veja Também

- PharFileInfo::getCompressedSize() - Retorna o tamanho real do arquivo (com compactação) dentro do arquivo Phar
- PharFileInfo::isCompressed() - Informa se a entrada está compactada
- PharFileInfo::decompress() - Descompacta a entrada Phar atual dentro do phar
- PharFileInfo::compress() - Compacta a entrada Phar atual com zlib ou bzip2
- Phar::decompress() - Descompacta todo o arquivo Phar
- Phar::compress() - Compacta todo o arquivo Phar usando compactação Gzip ou Bzip2
- Phar::canCompress() - Retorna se a extensão phar suporta compactação usando zlib ou bzip2
- Phar::compressFiles() - Compacta todos os arquivos no arquivo Phar atual
- Phar::decompressFiles() - Descompacta todos os arquivos no arquivo Phar atual
- Phar::getSupportedCompression() - Retorna um array de algoritmos de compactação suportados

# Phar::isFileFormat

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::isFileFormat — Informa se o arquivo phar é baseado no formato de arquivo tar/phar/zip dependendo do parâmetro

### Descrição

public function Phar::isFileFormat(int `$format`): bool

### Parâmetros

`format`

  `Phar::PHAR`, `Phar::TAR` ou `Phar::ZIP` para testar o formato do arquivo.

### Valor Retornado

Retorna `true` se o arquivo phar corresponder ao formato de arquivo solicitado pelo parâmetro.

### Erros/Exceções

PharException é lançada se o parâmetro for um especificador de formato de arquivo desconhecido.

### Veja Também

- Phar::convertToExecutable() - Converte um arquivo phar em outro formato de arquivo executável phar
- Phar::convertToData() - Converte um arquivo phar em um arquivo tar ou zip não executável

# Phar::isValidPharFilename

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::isValidPharFilename — Informa se o nome de arquivo fornecido é um nome de arquivo phar válido

### Descrição

final public static function Phar::isValidPharFilename(string `$filename`, bool `$executable` = `true`): bool

Retorna se o nome de arquivo fornecido é um nome de arquivo PHAR válido que será reconhecido como um arquivo PHAR pela extensão PHAR. Isso pode ser usado para testar um nome sem precisar instanciar um arquivo PHAR e capturar a inevitável exceção que será gerada se um nome inválido for especificado.

### Parâmetros

`filename`

  O nome ou caminho completo para um arquivo phar ainda não criado

`executable`

  Este parâmetro determina se o nome do arquivo deve ser tratado como um arquivo executável phar ou um arquivo não executável de dados.

### Valor Retornado

Retorna `true` se o nome do arquivo for válido, `false` caso contrário.

# Phar::isWritable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::isWritable — Informa se o arquivo phar pode ser modificado

### Descrição

public function Phar::isWritable(): bool

Este método retorna `true` se `phar.readonly` for `0`, e o arquivo phar atual no disco não for somente leitura.

### Parâmetros

Sem parâmetros.

### Valor Retornado

Retorna `true` se o arquivo phar puder ser modificado.

### Veja Também

- Phar::canWrite() - Retorna se a extensão phar suporta a escrita e criação de phars
- PharData::isWritable() - Informa se o arquivo tar/zip pode ser modificado

# Phar::loadPhar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::loadPhar — Carrega qualquer arquivo phar com um apelido

### Descrição

final public static function Phar::loadPhar(string `$filename`, ?string `$alias` = `null`): bool

Isto pode ser usado para ler o conteúdo de um arquivo Phar externo. Isto é mais útil para atribuir um apelido a um phar para que referências subsequentes ao phar possam usar o apelido mais curto, ou para carregar arquivos Phar que contêm apenas dados e não se destinam à execução/inclusão em scripts PHP.

### Parâmetros

`filename`

  O caminho completo ou relativo do arquivo phar a ser aberto.

`alias`

  O apelido que pode ser usado para se referir ao arquivo phar. Observe que muitos arquivos phar especificam um apelido explícito dentro do arquivo phar, e uma PharException será lançada se um novo apelido for especificado neste caso.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

PharException é lançada se um apelido for passado e o arquivo phar já tiver um apelido explícito.

### Exemplos

Exemplo #1 Um exemplo de Phar::loadPhar()

Phar::loadPhar pode ser usado em qualquer lugar para carregar um arquivo Phar externo, enquanto Phar::mapPhar deve ser usado em um stub de carregador para um Phar.

    <?php
    try {
        Phar::loadPhar('/caminho/para/phar.phar', 'meu.phar');
        echo file_get_contents('phar://meu.phar/arquivo.txt');
    } catch (PharException $e) {
        echo $e;
    }
    ?>

### Veja Também

- Phar::mapPhar() - Lê o arquivo atualmente em execução (um phar) e registra seu manifesto

# Phar::mapPhar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::mapPhar — Lê o arquivo atualmente em execução (um phar) e registra seu manifesto

### Descrição

final public static function Phar::mapPhar(?string `$alias` = `null`, int `$offset` = 0): bool

Este método estático só pode ser usado dentro do stub do carregador de um arquivo Phar para inicializar o phar quando ele for executado diretamente ou quando for incluído em outro script.

### Parâmetros

`alias`

  O apelido que pode ser usado em URLs `phar://` para se referir a este arquivo, em vez do seu caminho completo.

`offset`

  Variável não utilizada, serve apenas para compatibilidade com o PHP_Archive do PEAR.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

PharException é lançada se não for chamada diretamente na execução do PHP, se nenhum token __HALT_COMPILER(); for encontrado no arquivo de origem atual ou se o arquivo não puder ser aberto para leitura.

### Exemplos

Exemplo #1 Um exemplo de Phar::mapPhar()

Este método deve ser usado apenas dentro do stub de carregamento de um Phar. Use loadPhar para carregar um Phar externo na memória.

Aqui está um exemplo de stub do carregador Phar que usa mapPhar.

    <?php
    function __autoload($class)
    {
        include 'phar://me.phar/' . str_replace('_', '/', $class) . '.php';
    }
    try {
        Phar::mapPhar('me.phar');
        include 'phar://me.phar/startup.php';
    } catch (PharException $e) {
        echo $e->getMessage();
        die('Não foi possível inicializar o Phar');
    }
    __HALT_COMPILER();

### Veja Também

- Phar::loadPhar() - Carrega qualquer arquivo phar com um apelido

# Phar::mount

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::mount — Monta um caminho externo ou arquivo em um local virtual dentro do arquivo phar

### Descrição

final public static function Phar::mount(string `$pharPath`, string `$externalPath`): void

Assim como o conceito do sistema de arquivos Unix de montar dispositivos externos em caminhos dentro da árvore de diretórios, Phar::mount() permite referenciar arquivos e diretórios externos como se estivessem dentro de um arquivo. Isso permite uma abstração poderosa como, por exemplo, referenciar arquivos de configuração externos como se estivessem dentro do arquivo.

### Parâmetros

`pharPath`

  O caminho interno dentro do arquivo phar a ser usado como local do caminho montado. Este deve ser um caminho relativo dentro do arquivo phar e não deve existir ainda.

`externalPath`

  Um caminho ou URL para um arquivo ou diretório externo para montar dentro do arquivo phar

### Valor Retornado

Sem retorno. PharException é lançada em caso de falha.

### Erros/Exceções

Lança PharException se ocorrer algum problema ao montar o caminho.

### Exemplos

Exemplo #1 Um exemplo de Phar::mount()

O exemplo a seguir mostra o acesso a um arquivo de configuração externo como se fosse um caminho dentro de um arquivo phar.

Primeiro, o código dentro de um arquivo phar:

    <?php
    $configuration = simplexml_load_string(file_get_contents(
        Phar::running(false) . '/config.xml'));
    ?>

A seguir, o código externo usado para montar o arquivo de configuração:

    <?php
    // primeiro configura a associação entre o config.xml abstrato
    // e o real no disco
    Phar::mount('phar://config.xml', '/etc/exemplo/config.xml');
    // agora executa a aplicação
    include '/caminho/para/arquivo.phar';
    ?>

Outro método é colocar o código de montagem dentro do stub do arquivo phar. Aqui está um exemplo de configuração de um arquivo de configuração padrão caso nenhuma configuração de usuário seja especificada:

    <?php
    // primeiro configura a associação entre o config.xml abstrato
    // e o real no disco
    if (defined('EXTERNAL_CONFIG')) {
        Phar::mount('config.xml', EXTERNAL_CONFIG);
        if (file_exists(__DIR__ . '/extra_config.xml')) {
            Phar::mount('extra.xml', __DIR__ . '/extra_config.xml');
        }
    } else {
        Phar::mount('config.xml', 'phar://' . __FILE__ . '/config_padrao.xml');
        Phar::mount('extra.xml', 'phar://' . __FILE__ . '/extra_padrao.xml');
    }
    // agora executa a aplicação
    include 'phar://' . __FILE__ . '/index.php';
    __HALT_COMPILER();
    ?>

...e o código externo para carregar este arquivo phar:

    <?php
    define('EXTERNAL_CONFIG', '/etc/exemplo/config.xml');
    // agora executa a aplicação
    include '/caminho/para/arquivo.phar';
    ?>

# Phar::mungServer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::mungServer — Define uma lista de até 4 variáveis ​​$_SERVER que devem ser modificadas para execução

### Descrição

final public static function Phar::mungServer(array `$variables`): void

Phar::mungServer() só deve ser chamado dentro do stub de um arquivo phar.

Define uma lista de até 4 variáveis ​​$_SERVER que devem ser modificadas para execução. As variáveis ​​que podem ser modificadas para remover rastros da execução do PHAR são `REQUEST_URI`, `PHP_SELF`, `SCRIPT_NAME` e `SCRIPT_FILENAME`.

Por si só, este método não faz nada. Somente quando combinado com Phar::webPhar() ele entra em vigor, e somente quando o arquivo solicitado é um arquivo PHP a ser analisado. Observe que as variáveis `PATH_INFO` e `PATH_TRANSLATED` são sempre modificadas.

Os valores originais das variáveis ​​modificadas são armazenados no array SERVER com `PHAR_` prefixado, então, por exemplo, `SCRIPT_NAME` seria salvo como `PHAR_SCRIPT_NAME`.

### Parâmetros

`variables`

  Um array de qualquer uma das strings `REQUEST_URI`, `PHP_SELF`, `SCRIPT_NAME` e `SCRIPT_FILENAME`. Outros valores disparam uma exceção, e Phar::mungServer() diferencia maiúsculas de minúsculas.

### Valor Retornado

Sem retorno.

### Erros/Exceções

Lança UnexpectedValueException se algum problema for encontrado com os dados passados.

### Exemplos

Exemplo #1 Um exemplo de Phar::mungServer()

    <?php
    // stub de exemplo
    Phar::mungServer(array('REQUEST_URI'));
    Phar::webPhar();
    __HALT_COMPILER();
    ?>

### Veja Também

- Phar::webPhar() - Encaminha uma solicitação de um navegador da web para um arquivo interno dentro do arquivo phar
- Phar::setStub() - Usado para definir o carregador PHP ou o stub de inicialização de um arquivo Phar

# Phar::offsetExists

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetExists — Determina se um arquivo existe no phar

### Descrição

public function Phar::offsetExists(string `$localName`): bool

Esta é uma implementação da interface ArrayAccess que permite a manipulação direta do conteúdo de um arquivo Phar usando colchetes de acesso a arrays.

offsetExists() é chamado sempre que isset() é chamado.

### Parâmetros

`localName`

  O nome do arquivo (caminho relativo) a ser procurado em um Phar.

### Valor Retornado

Retorna `true` se o arquivo existe dentro do phar, ou `false` caso contrário.

### Exemplos

Exemplo #1 Um exemplo de Phar::offsetExists()

    <?php
    $p = new Phar(dirname(__FILE__) . '/meu.phar', 0, 'meu.phar');
    $p['primeiroarquivo.txt'] = 'primeiro arquivo';
    $p['segundoarquivo.txt'] = 'segundo arquivo';
    // o próximo conjunto de linhas chama offsetExists() indiretamente
    var_dump(isset($p['primeiroarquivo.txt']));
    var_dump(isset($p['naoexiste.txt']));
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(false)

### Veja Também

- Phar::offsetGet() - Obtém um objeto PharFileInfo para um arquivo específico
- Phar::offsetSet() - Define o conteúdo de um arquivo interno para o de um arquivo externo
- Phar::offsetUnset() - Remove um arquivo de um phar

# Phar::offsetGet

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetGet — Obtém um objeto PharFileInfo para um arquivo específico

### Descrição

public function Phar::offsetGet(string `$localName`): SplFileInfo

Esta é uma implementação da interface ArrayAccess que permite a manipulação direta do conteúdo de um arquivo Phar usando colchetes de acesso a arrays. Phar::offsetGet() é usado para recuperar arquivos de um arquivo Phar.

### Parâmetros

`localName`

  O nome do arquivo (caminho relativo) a ser procurado em um Phar.

### Valor Retornado

Um objeto PharFileInfo é retornado e pode ser usado para iterar sobre o conteúdo de um arquivo ou recuperar informações sobre o arquivo atual.

### Erros/Exceções

Este método lança BadMethodCallException se o arquivo não existir no arquivo Phar.

### Exemplos

Exemplo #1 Exemplo de Phar::offsetGet()

Assim como todas as classes que implementam a interface ArrayAccess, Phar::offsetGet() é automaticamente chamado ao usar o operador de colchetes angulares `[]`.

    <?php
    $p = new Phar(dirname(__FILE__) . '/meuphar.phar', 0, 'meuphar.phar');
    $p['existe.txt'] = "arquivo existe\n";
    try {
        // chama offsetGet() automaticamente
        echo $p['existe.txt'];
        echo $p['naoexiste.txt'];
    } catch (BadMethodCallException $e) {
        echo $e;
    }
    ?>

O exemplo acima produzirá:

    arquivo existe
    Entry naoexiste.txt does not exist

### Veja Também

- Phar::offsetExists() - Determina se um arquivo existe no phar
- Phar::offsetSet() - Define o conteúdo de um arquivo interno para o de um arquivo externo
- Phar::offsetUnset() - Remove um arquivo de um phar

# Phar::offsetSet

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetSet — Define o conteúdo de um arquivo interno para o de um arquivo externo

### Descrição

public function Phar::offsetSet(string `$localName`, resource|string `$value`): void

> Nota: Este método requer que a configuração `phar.readonly` do php.ini seja definida como `0` para funcionar com objetos Phar. Caso contrário, uma exceção PharException será lançada.

Esta é uma implementação da interface ArrayAccess que permite a manipulação direta do conteúdo de um arquivo Phar usando colchetes de acesso a arrays. offsetSet é usado para modificar um arquivo existente ou adicionar um novo arquivo a um arquivo Phar.

### Parâmetros

`localName`

  O nome do arquivo (caminho relativo) a ser modificado em um Phar.

`value`

  Conteúdo do arquivo.

### Valor Retornado

Sem valores de retorno.

### Erros/Exceções

Se phar.readonly for `1`, BadMethodCallException será lançada, pois modificar um Phar só é permitido quando phar.readonly estiver definido como `0`. Lança PharException se houver algum problema ao liberar as alterações feitas no arquivo Phar para o disco.

### Exemplos

Exemplo #1 Um exemplo de Phar::offsetSet()

offsetSet não deve ser acessado diretamente, mas sim usado por meio de acesso a array com o operador `[]`.

    <?php
    $p = new Phar('/caminho/para/meu.phar', 0, 'meu.phar');
    try {
        // chama offsetSet
        $p['arquivo.txt'] = 'Olá mundo';
    } catch (Exception $e) {
        echo 'Não foi possível modificar arquivo.txt:', $e;
    }
    ?>

### Notas

> Nota: Phar::addFile(), Phar::addFromString() e Phar::offsetSet() salvam um novo arquivo phar cada vez que são chamadas. Se o desempenho for uma preocupação, Phar::buildFromDirectory() ou Phar::buildFromIterator() devem ser usadas.

### Veja Também

- Phar::offsetExists() - Determina se um arquivo existe no phar
- Phar::offsetGet() - Obtém um objeto PharFileInfo para um arquivo específico
- Phar::offsetUnset() - Remove um arquivo de um phar

# Phar::offsetUnset

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetUnset — Remove um arquivo de um phar

### Descrição

public function Phar::offsetUnset(string `$localName`): void

> Nota: Este método requer que a configuração `phar.readonly` do php.ini seja definida como `0` para funcionar com objetos Phar. Caso contrário, uma exceção PharException será lançada.

Esta é uma implementação da interface ArrayAccess que permite a manipulação direta do conteúdo de um arquivo Phar usando colchetes de acesso a arrays. offsetUnset é usado para excluir um arquivo existente e é chamado pela construção de linguagem unset().

### Parâmetros

`localName`

  O nome do arquivo (caminho relativo) a ser modificado em um Phar.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

Se phar.readonly for `1`, BadMethodCallException será lançada, pois modificar um Phar só é permitido quando phar.readonly estiver definido como `0`. Lança PharException se houver algum problema ao liberar as alterações feitas no arquivo Phar para o disco.

### Exemplos

Exemplo #1 Um exemplo de Phar::offsetUnset()

    <?php
    $p = new Phar('/caminho/para/meu.phar', 0, 'meu.phar');
    try {
        // exclui arquivo.txt de meu.phar chamando offsetUnset
        unset($p['arquivo.txt']);
    } catch (Exception $e) {
        echo 'Não foi possível excluir arquivo.txt: ', $e;
    }
    ?>

### Veja Também

- Phar::offsetExists() - Determina se um arquivo existe no phar
- Phar::offsetGet() - Obtém um objeto PharFileInfo para um arquivo específico
- Phar::offsetSet() - Define o conteúdo de um arquivo interno para o de um arquivo externo
- Phar::unlinkArchive() - Remove completamente um arquivo phar do disco e da memória
- Phar::delete() - Exclui um arquivo dentro de um arquivo phar

# Phar::running

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::running — Retorna o caminho completo no disco ou a URL completa do arquivo Phar em execução no momento

### Descrição

final public static function Phar::running(bool `$returnPhar` = `true`): string

Retorna o caminho completo para o arquivo phar em execução. Isso se destina a ser usado de forma muito semelhante à constante mágica `__FILE__` e só tem efeito dentro de um arquivo phar em execução.

Dentro do stub de um arquivo, Phar::running() retorna `""`. Basta usar `__FILE__` para acessar o phar em execução dentro de um stub.

### Parâmetros

`returnPhar`

  Se `false`, o caminho completo no disco para o arquivo phar é retornado. Se `true`, uma URL phar completa é retornada.

### Valor Retornado

Retorna o nome do arquivo se válido, string vazia caso contrário.

### Exemplos

Exemplo #1 Um exemplo de Phar::running()

Para o exemplo a seguir, suponha que o arquivo phar esteja localizado em `/path/to/phar/my.phar`.

    <?php
    $a = Phar::running(); // $a é "phar:///path/to/phar/my.phar"
    $b = Phar::running(false); // $b é "/path/to/phar/my.phar"
    ?>

# Phar::setAlias

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.1)

Phar::setAlias — Define o apelido para o arquivo Phar

### Descrição

public function Phar::setAlias(string `$alias`): true

> Nota: Este método requer que a configuração `phar.readonly` do php.ini seja definida como `0` para funcionar com objetos Phar. Caso contrário, uma exceção PharException será lançada.

Define o apelido para o arquivo Phar e o grava como o apelido permanente para este arquivo Phar. Um apelido pode ser usado internamente em um arquivo Phar para garantir que o uso do empacotador de fluxo `phar` para acessar arquivos internos sempre funcione, independentemente da localização do arquivo Phar no sistema de arquivos. Outra alternativa é confiar na interceptação de Phar de include ou usar Phar::interceptFileFuncs() e usar caminhos relativos.

### Parâmetros

`alias`

  Uma string abreviada à qual este arquivo pode ser referenciado no acesso ao empacotador de fluxo `phar`.

### Valor Retornado

Sempre retorna `true`.

### Erros/Exceções

Lança UnexpectedValueException quando o acesso de gravação está desabilitado e PharException se o apelido já estiver em uso ou se algum problema for encontrado ao liberar as alterações no disco.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Phar::setAlias() agora tem um retorno provisório de true.

### Exemplos

Exemplo #1 Um exemplo de Phar::setAlias()

    <?php
    try {
        $phar = new Phar('meuphar.phar');
        $phar->setAlias('mp.phar');
    } catch (Exception $e) {
        // lida com erros
    }
    ?>

### Veja Também

- Phar::__construct() - Constrói um objeto de arquivo Phar
- Phar::interceptFileFuncs() - Instrui phar a interceptar fopen, file_get_contents, opendir e todas as funções relacionadas a stat

# Phar::setDefaultStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::setDefaultStub — Usado para definir o carregador PHP ou o stub de bootstrap de um arquivo Phar para o carregador padrão

### Descrição

public function Phar::setDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): true

> Nota: Este método requer que a configuração `phar.readonly` do php.ini seja definida como `0` para funcionar com objetos Phar. Caso contrário, uma exceção PharException será lançada.

Este método é um método de conveniência que combina a funcionalidade de Phar::createDefaultStub() e Phar::setStub().

### Parâmetros

`index`

  Caminho relativo dentro do arquivo phar para execução se acessado na linha de comando

`webIndex`

  Caminho relativo dentro do arquivo phar para ser executado se acessado por meio de um navegador da web

### Valor Retornado

Sempre retorna `true`.

### Erros/Exceções

UnexpectedValueException é lançada se phar.readonly estiver habilitado no php.ini. PharException é lançada se algum problema for encontrado ao liberar alterações no disco.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Phar::setDefaultStub() agora tem um retorno provisório de true.
8.0.0 | `webIndex` agora é anulável.

### Exemplos

Exemplo #1 Um exemplo de Phar::setDefaultStub()

    <?php
    try {
        $phar = new Phar('meuphar.phar');
        $phar->setDefaultStub('cli.php', 'web/index.php');
        // isso é o mesmo que:
        // $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
    } catch (Exception $e) {
        // lida com erros
    }
    ?>

### Veja Também

- Phar::setStub() - Usado para definir o carregador PHP ou o stub de inicialização de um arquivo Phar
- Phar::createDefaultStub() - Cria um stup de formato específico de arquivo phar

# Phar::setMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::setMetadata — Define metadados do arquivo phar

### Descrição

public function Phar::setMetadata(mixed `$metadata`): void

> Nota: Este método requer que a configuração `phar.readonly` do php.ini seja definida como `0` para funcionar com objetos Phar. Caso contrário, uma exceção PharException será lançada.

Phar::setMetadata() deve ser usado para armazenar dados personalizados que descrevam algo sobre o arquivo phar como uma entidade completa. PharFileInfo::setMetadata() deve ser usado para metadados específicos do arquivo. Metadados podem reduzir o desempenho do carregamento de um arquivo phar se os dados forem grandes.

Alguns usos possíveis para metadados incluem especificar qual arquivo dentro do arquivo deve ser usado para inicialização, ou a localização de um manifesto de arquivo como o arquivo package.xml do » PEAR. No entanto, quaisquer dados úteis que descrevam o arquivo phar podem ser armazenados.

### Parâmetros

`metadata`

  Qualquer variável PHP contendo informações para armazenar que descrevem o arquivo phar.

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Um exemplo de Phar::setMetadata()

    <?php
    // garantindo que o arquivo não existe
    @unlink('novophar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/novophar.phar', 0, 'novophar.phar');
        $p['arquivo.php'] = '<?php echo "olá"';
        $p->setMetadata(array('bootstrap' => 'arquivo.php'));
        var_dump($p->getMetadata());
    } catch (Exception $e) {
        echo 'Não foi possível criar e/ou modificar o phar:', $e;
    }
    ?>

O exemplo acima produzirá:

    array(1) {
      ["bootstrap"]=>
      string(11) "arquivo.php"
    }

### Veja Também

- Phar::getMetadata() - Retorna metadados do arquivo phar
- Phar::delMetadata() - Exclui os metadados globais do phar
- Phar::hasMetadata() - Informa se o phar tem metadados globais

# Phar::setSignatureAlgorithm

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.1.0)

Phar::setSignatureAlgorithm — Define o algoritmo de assinatura para um phar e o aplica

### Descrição

public function Phar::setSignatureAlgorithm(int `$algo`, ?string `$privateKey` = `null`): void

> Nota: Este método requer que a configuração `phar.readonly` do php.ini seja definida como `0` para funcionar com objetos Phar. Caso contrário, uma exceção PharException será lançada.

Define o algoritmo de assinatura para um Phar e o aplica. O algoritmo de assinatura deve ser um dos seguintes: `Phar::MD5`, `Phar::SHA1`, `Phar::SHA256`, `Phar::SHA512` ou `Phar::OPENSSL`.

Observe que todos os arquivos phar executáveis ​​têm uma assinatura criada automaticamente, `SHA1` por padrão. Arquivos de dados baseados em tar ou zip (arquivos criados com a classe PharData) devem ter sua assinatura criada e definida explicitamente via Phar::setSignatureAlgorithm().

### Parâmetros

`algo`

  Um dos seguintes: `Phar::MD5`, `Phar::SHA1`, `Phar::SHA256`, `Phar::SHA512` ou `Phar::OPENSSL`.

`privateKey`

  O conteúdo de uma chave privada OpenSSL, conforme extraído de um certificado ou arquivo de chave OpenSSL:

      <?php
      $private = openssl_get_privatekey(file_get_contents('private.pem'));
      $pkey = '';
      openssl_pkey_export($private, $pkey);
      $p->setSignatureAlgorithm(Phar::OPENSSL, $pkey);
      ?>

  Consulte introdução ao phar para obter instruções sobre nomeação e posicionamento do arquivo de chave pública.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

Lança UnexpectedValueException para vários erros, e uma PharException se ocorrer algum problema ao liberar as alterações no disco.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `privateKey` agora é anulável.

### Veja Também

- Phar::getSupportedSignatures() - Retorna um array de tipos de assinatura suportados
- Phar::getSignature() - Retorna a assinatura MD5/SHA1/SHA256/SHA512/OpenSSL de um arquivo Phar

# Phar::setStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::setStub — Usado para definir o carregador PHP ou o stub de inicialização de um arquivo Phar

### Descrição

public function Phar::setStub(resource|string `$stub`, int `$length` = -1): true

> Nota: Este método requer que a configuração `phar.readonly` do php.ini seja definida como `0` para funcionar com objetos Phar. Caso contrário, uma exceção PharException será lançada.

Este método é usado para adicionar um stub de carregador de inicialização PHP a um novo arquivo Phar, ou para substituir o stub de carregador em um arquivo Phar existente.

O stub do carregador para um arquivo Phar é usado sempre que um arquivo é incluído diretamente como neste exemplo:

    <?php
    include 'meuphar.phar';
    ?>

ou por execução simples:

    php meuphar.phar

O carregador não é acessado ao incluir um arquivo por meio do empacotador de fluxo `phar` como a seguir:

    <?php
    include 'phar://meuphar.phar/algumarquivo.php';
    ?>

### Parâmetros

`stub`

  Uma string ou um identificador de fluxo aberto para usar como stub executável para este arquivo phar.

`length`
  Comprimento de `stub` em bytes.
  Aviso

  Passar o argumento `length` com um resource no primeiro argumento está DESCONTINUADO a partir do PHP 8.3.0. Em vez disso, use `$phar->setStub(stream_get_contents($resource))`.

### Valor Retornado

Sempre retorna `true`.

### Erros/Exceções

UnexpectedValueException é lançada se phar.readonly estiver habilitado no php.ini. PharException é lançada se algum problema for encontrado ao liberar alterações no disco.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | O tipo do retorno agora é `true`; anteriormente, era bool.
8.3.0 | Chamar Phar::setStub() com um resource e um `length` agora está descontinuado. Tais chamadas devem ser substituídas por: `$phar->setStub(stream_get_contents($resource));`

### Exemplos

Exemplo #1 Um exemplo de Phar::setStub()

    <?php

    try {
        $p = new Phar(dirname(__FILE__) . '/novophar.phar', 0, 'novophar.phar');
        $p['a.php'] = '<?php var_dump("Olá");';
        $p->setStub('<?php var_dump("Primeiro"); Phar::mapPhar("novophar.phar"); __HALT_COMPILER(); ?>');
        include 'phar://novophar.phar/a.php';
        var_dump($p->getStub());

        $p['b.php'] = '<?php var_dump("Mundo");';
        $p->setStub('<?php var_dump("Segundo"); Phar::mapPhar("novophar.phar"); __HALT_COMPILER(); ?>');
        include 'phar://novophar.phar/b.php';
        var_dump($p->getStub());
    } catch (Exception $e) {
        echo 'As operações de gravação falharam em novophar.phar: ', $e;
    }
    ?>

O exemplo acima produzirá:

    string(5) "Olá"
    string(82) "<?php var_dump("Primeiro"); Phar::mapPhar("novophar.phar"); __HALT_COMPILER(); ?>"
    string(5) "Mundo"
    string(83) "<?php var_dump("Segundo"); Phar::mapPhar("novophar.phar"); __HALT_COMPILER(); ?>"

### Veja Também

- Phar::getStub() - Retorna o carregador PHP ou o stub de inicialização de um arquivo Phar
- Phar::createDefaultStub() - Cria um stup de formato específico de arquivo phar

# Phar::startBuffering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::startBuffering — Inicia o buffer das operações de gravação Phar, não modifica o objeto Phar no disco

### Descrição

public function Phar::startBuffering(): void

Embora tecnicamente desnecessário, o método Phar::startBuffering() pode proporcionar um aumento significativo de desempenho ao criar ou modificar um arquivo Phar com um grande número de arquivos. Normalmente, sempre que um arquivo dentro de um arquivo Phar é criado ou modificado de alguma forma, todo o arquivo Phar será recriado com as alterações. Dessa forma, o arquivo estará atualizado com a atividade realizada nele.

No entanto, isso pode ser desnecessário ao simplesmente criar um novo arquivo Phar, quando faria mais sentido gravar o arquivo inteiro de uma só vez. Da mesma forma, muitas vezes é necessário fazer uma série de alterações e garantir que todas elas sejam possíveis antes de fazer qualquer alteração no disco, semelhante ao conceito de transações de banco de dados relacional. O par de métodos Phar::startBuffering()/Phar::stopBuffering() é fornecido para esse propósito.

O buffer de gravação Phar é por arquivo, o buffer ativo para o arquivo Phar `foo.phar` não afeta as alterações no arquivo Phar `bar.phar`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Um exemplo de Phar::startBuffering()

    <?php
    // garantindo que o arquivo não existe
    @unlink('novophar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/novophar.phar', 0, 'novophar.phar');
    } catch (Exception $e) {
        echo 'Não foi possível criar o phar:', $e;
    }
    echo 'O novo phar tem ' . $p->count() . " entradas\n";
    $p->startBuffering();
    $p['arquivo.txt'] = 'olá';
    $p['arquivo2.txt'] = 'pessoal';
    $p['arquivo2.txt']->setCompressedGZ();
    $p['arquivo3.txt'] = 'carafeliz';
    $p['arquivo3.txt']->setMetadata(42);
    $p->setStub("<?php
    function __autoload($class)
    {
        include 'phar://meuphar.phar/' . str_replace('_', '/', $class) . '.php';
    }
    Phar::mapPhar('meuphar.phar');
    include 'phar://meuphar.phar/startup.php';
    __HALT_COMPILER();");
    $p->stopBuffering();
    ?>

### Veja Também

- Phar::stopBuffering() - Interrompe o buffer de solicitações de gravação no arquivo Phar e salva as alterações no disco
- Phar::isBuffering() - Usado para determinar se as operações de gravação Phar estão sendo armazenadas em buffer ou estão sendo liberadas diretamente no disco

# Phar::stopBuffering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::stopBuffering — Interrompe o buffer de solicitações de gravação no arquivo Phar e salva as alterações no disco

### Descrição

public function Phar::stopBuffering(): void

Phar::stopBuffering() é usado em conjunto com o método Phar::startBuffering(). Phar::startBuffering() pode proporcionar um aumento significativo de desempenho ao criar ou modificar um arquivo Phar com um grande número de arquivos. Normalmente, sempre que um arquivo dentro de um arquivo Phar é criado ou modificado de alguma forma, todo o arquivo Phar será recriado com as alterações. Dessa forma, o arquivo estará atualizado com a atividade realizada nele.

No entanto, isso pode ser desnecessário ao simplesmente criar um novo arquivo Phar, quando faria mais sentido gravar o arquivo inteiro de uma só vez. Da mesma forma, muitas vezes é necessário fazer uma série de alterações e garantir que todas elas sejam possíveis antes de fazer qualquer alteração no disco, semelhante ao conceito de transações de banco de dados relacional. O par de métodos Phar::startBuffering()/Phar::stopBuffering() é fornecido para esse propósito.

O buffer de gravação Phar é por arquivo, o buffer ativo para o arquivo Phar `foo.phar` não afeta as alterações no arquivo Phar `bar.phar`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

PharException é lançada se algum problema for encontrado ao liberar as alterações no disco.

### Exemplos

Exemplo #1 Um exemplo de Phar::stopBuffering()

    <?php
    $p = new Phar(dirname(__FILE__) . '/novophar.phar', 0, 'novophar.phar');
    $p['arquivo.txt'] = 'olá';
    $p->startBuffering();
    var_dump($p->getStub());
    $p->setStub("<?php
    function __autoload(\$class)
    {
        include 'phar://novophar.phar/' . str_replace('_', '/', \$class) . '.php';
    }
    Phar::mapPhar('novophar.phar');
    include 'phar://novophar.phar/startup.php';
    __HALT_COMPILER();");
    $p->stopBuffering();
    var_dump($p->getStub());
    ?>

O exemplo acima produzirá:

    string(24) "<?php __HALT_COMPILER();"
    string(195) "<?php
    function __autoload($class)
    {
        include 'phar://' . str_replace('_', '/', $class);
    }
    Phar::mapPhar('novophar.phar');
    include 'phar://novophar.phar/startup.php';
    __HALT_COMPILER();"

### Veja Também

- Phar::startBuffering() - Inicia o buffer das operações de gravação Phar, não modifica o objeto Phar no disco
- Phar::isBuffering() - Usado para determinar se as operações de gravação Phar estão sendo armazenadas em buffer ou estão sendo liberadas diretamente no disco

# Phar::unlinkArchive

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::unlinkArchive — Remove completamente um arquivo phar do disco e da memória

### Descrição

final public static function Phar::unlinkArchive(string `$filename`): true

Remove um arquivo phar do disco e da memória.

### Parâmetros

`filename`

  O caminho no disco para o arquivo phar.

### Valor Retornado

Sempre retorna `true`.

### Erros/Exceções

PharException é lançada se houver algum ponteiro de arquivo aberto para o arquivo phar, ou qualquer objeto Phar, PharData, ou PharFileInfo existente que faça referência ao arquivo phar.

### Exemplos

Exemplo #1 Um exemplo de Phar::unlinkArchive()

    <?php
    // uso simples
    Phar::unlinkArchive('/caminho/para/meu.phar');

    // mais um exemplo comum:
    $p = new Phar('meu.phar');
    $fp = fopen('phar://meu.phar/arquivo.txt', 'r');
    // isto cria 'meu.phar.gz'
    $gp = $p->compress(Phar::GZ);
    // remove todas as referências ao arquivo
    unset($p);
    fclose($fp);
    // agora remove todos os vestígios do arquivo
    Phar::unlinkArchive('meu.phar');
    ?>

### Veja Também

- Phar::delete() - Exclui um arquivo dentro de um arquivo phar
- Phar::offsetUnset() - Remove um arquivo de um phar

# Phar::webPhar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::webPhar — Encaminha uma solicitação de um navegador da web para um arquivo interno dentro do arquivo phar

### Descrição

final public static function Phar::webPhar(
?string `$alias` = `null`,
?string `$index` = `null`,
?string `$fileNotFoundScript` = `null`,
array `$mimeTypes` = [],
?callable `$rewrite` = `null`
): void

Phar::webPhar() serve como Phar::mapPhar() para phars baseados na web. Este método analisa $_SERVER['REQUEST_URI'] e encaminha uma solicitação de um navegador web para um arquivo interno dentro do arquivo phar. Ele simula um servidor web, encaminhando solicitações para o arquivo correto, ecoando os cabeçalhos corretos e analisando arquivos PHP conforme necessário. Combinado com Phar::mungServer() e Phar::interceptFileFuncs(), qualquer aplicação web pode ser usada sem modificações a partir de um arquivo phar.

Phar::webPhar() só deve ser chamado a partir do stub de um arquivo phar (veja aqui para mais informações sobre o que é um stub).

### Parâmetros

`alias`

  O apelido que pode ser usado em URLs `phar://` para se referir a este arquivo, em vez do seu caminho completo.

`index`

  A localização dentro do phar do índice do diretório.

`fileNotFoundScript`

  O local do script a ser executado quando um arquivo não for encontrado. Este script deve gerar os cabeçalhos HTTP 404 corretos.

`mimeTypes`

  Um array mapeando extensões de arquivo adicionais para o tipo MIME. Se o mapeamento padrão for suficiente, passe um array vazio. Por padrão, essas extensões são mapeadas para os seguintes tipos MIME:

      <?php
      $mimes = array(
          'phps' => Phar::PHPS, // passado para highlight_file()
          'c' => 'text/plain',
          'cc' => 'text/plain',
          'cpp' => 'text/plain',
          'c++' => 'text/plain',
          'dtd' => 'text/plain',
          'h' => 'text/plain',
          'log' => 'text/plain',
          'rng' => 'text/plain',
          'txt' => 'text/plain',
          'xsd' => 'text/plain',
          'php' => Phar::PHP, // interpretado como PHP
          'inc' => Phar::PHP, // interpretado como PHP
          'avi' => 'video/avi',
          'bmp' => 'image/bmp',
          'css' => 'text/css',
          'gif' => 'image/gif',
          'htm' => 'text/html',
          'html' => 'text/html',
          'htmls' => 'text/html',
          'ico' => 'image/x-ico',
          'jpe' => 'image/jpeg',
          'jpg' => 'image/jpeg',
          'jpeg' => 'image/jpeg',
          'js' => 'application/x-javascript',
          'midi' => 'audio/midi',
          'mid' => 'audio/midi',
          'mod' => 'audio/mod',
          'mov' => 'movie/quicktime',
          'mp3' => 'audio/mp3',
          'mpg' => 'video/mpeg',
          'mpeg' => 'video/mpeg',
          'pdf' => 'application/pdf',
          'png' => 'image/png',
          'swf' => 'application/shockwave-flash',
          'tif' => 'image/tiff',
          'tiff' => 'image/tiff',
          'wav' => 'audio/wav',
          'xbm' => 'image/xbm',
          'xml' => 'text/xml',
      );
      ?>

`rewrite`

  Uma função que recebe uma string como seu único parâmetro e deve retornar uma string ou `false`.

  Se fast-cgi ou cgi estiverem sendo usados, o parâmetro passado para a função será o valor da variável $_SERVER['PATH_INFO']. Caso contrário, o parâmetro passado para a função será o valor da variável $_SERVER['REQUEST_URI'].

  Se uma string for retornada, ela será usada como caminho interno do arquivo. Se `false` for retornado, webPhar() enviará um código HTTP 403 Forbidden (Proibido).

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

Lança PharException quando não for possível abrir o arquivo interno para saída, ou se for chamado de um arquivo não stub. Se um valor de array inválido for passado para `mimeTypes` ou uma função de retorno inválida for passado para `rewrite`, uma UnexpectedValueException será lançada.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `fileNotFoundScript` e `rewrite` agora são anuláveis.

### Exemplos

Exemplo #1 Um exemplo de Phar::webPhar()

Com o exemplo abaixo, o phar criado exibirá `Hello World` se alguém navegar para `/myphar.phar/index.php` ou para `/myphar.phar`, e exibirá a fonte de `index.phps` se alguém navegar para `/myphar.phar/index.phps`.

    <?php
    // criando o arquivo phar:
    try {
        $phar = new Phar('myphar.phar');
        $phar['index.php'] = '<?php echo "Olá Mundo"; ?>';
        $phar['index.phps'] = '<?php echo "Olá Mundo"; ?>';
        $phar->setStub('<?php
    Phar::webPhar();
    __HALT_COMPILER(); ?>');
    } catch (Exception $e) {
        // lida com erros
    }
    ?>

### Veja Também

- Phar::mungServer() - Define uma lista de até 4 variáveis ​​$_SERVER que devem ser modificadas para execução
- Phar::interceptFileFuncs() - Instrui phar a interceptar fopen, file_get_contents, opendir e todas as funções relacionadas a stat

## Índice

- Phar::addEmptyDir — Adiciona um diretório vazio ao arquivo phar
- Phar::addFile — Adiciona um arquivo do sistema de arquivos ao arquivo phar
- Phar::addFromString — Adiciona um arquivo a partir de uma string ao arquivo phar
- Phar::apiVersion — Retorna a versão da API
- Phar::buildFromDirectory — Constrói um arquivo phar a partir dos arquivos dentro de um diretório
- Phar::buildFromIterator — Constrói um arquivo phar a partir de um iterador
- Phar::canCompress — Retorna se a extensão phar suporta compactação usando zlib ou bzip2
- Phar::canWrite — Retorna se a extensão phar suporta a escrita e criação de phars
- Phar::compress — Compacta todo o arquivo Phar usando compactação Gzip ou Bzip2
- Phar::compressFiles — Compacta todos os arquivos no arquivo Phar atual
- Phar::__construct — Constrói um objeto de arquivo Phar
- Phar::convertToData — Converte um arquivo phar em um arquivo tar ou zip não executável
- Phar::convertToExecutable — Converte um arquivo phar em outro formato de arquivo executável phar
- Phar::copy — Copia um arquivo interno do arquivo phar para outro novo arquivo dentro do phar
- Phar::count — Retorna o número de entradas (arquivos) no arquivo Phar
- Phar::createDefaultStub — Cria um stup de formato específico de arquivo phar
- Phar::decompress — Descompacta todo o arquivo Phar
- Phar::decompressFiles — Descompacta todos os arquivos no arquivo Phar atual
- Phar::delMetadata — Exclui os metadados globais do phar
- Phar::delete — Exclui um arquivo dentro de um arquivo phar
- Phar::__destruct — Destrói um objeto de arquivo Phar
- Phar::extractTo — Extrai o conteúdo de um arquivo phar para um diretório
- Phar::getAlias — Obtém o apelido para o Phar
- Phar::getMetadata — Retorna metadados do arquivo phar
- Phar::getModified — Informa se o phar foi modificado
- Phar::getPath — Obtém o caminho real para o arquivo Phar no disco
- Phar::getSignature — Retorna a assinatura MD5/SHA1/SHA256/SHA512/OpenSSL de um arquivo Phar
- Phar::getStub — Retorna o carregador PHP ou o stub de inicialização de um arquivo Phar
- Phar::getSupportedCompression — Retorna um array de algoritmos de compactação suportados
- Phar::getSupportedSignatures — Retorna um array de tipos de assinatura suportados
- Phar::getVersion — Retorna informações da versão do arquivo Phar
- Phar::hasMetadata — Informa se o phar tem metadados globais
- Phar::interceptFileFuncs — Instrui phar a interceptar fopen, file_get_contents, opendir e todas as funções relacionadas a stat
- Phar::isBuffering — Usado para determinar se as operações de gravação Phar estão sendo armazenadas em buffer ou estão sendo liberadas diretamente no disco
- Phar::isCompressed — Retorna Phar::GZ ou PHAR::BZ2 se todo o arquivo phar estiver compactado (.tar.gz/tar.bz e assim por diante)
- Phar::isFileFormat — Informa se o arquivo phar é baseado no formato de arquivo tar/phar/zip dependendo do parâmetro
- Phar::isValidPharFilename — Informa se o nome de arquivo fornecido é um nome de arquivo phar válido
- Phar::isWritable — Informa se o arquivo phar pode ser modificado
- Phar::loadPhar — Carrega qualquer arquivo phar com um apelido
- Phar::mapPhar — Lê o arquivo atualmente em execução (um phar) e registra seu manifesto
- Phar::mount — Monta um caminho externo ou arquivo em um local virtual dentro do arquivo phar
- Phar::mungServer — Define uma lista de até 4 variáveis ​​$_SERVER que devem ser modificadas para execução
- Phar::offsetExists — Determina se um arquivo existe no phar
- Phar::offsetGet — Obtém um objeto PharFileInfo para um arquivo específico
- Phar::offsetSet — Define o conteúdo de um arquivo interno para o de um arquivo externo
- Phar::offsetUnset — Remove um arquivo de um phar
- Phar::running — Retorna o caminho completo no disco ou a URL completa do arquivo Phar em execução no momento
- Phar::setAlias — Define o apelido para o arquivo Phar
- Phar::setDefaultStub — Usado para definir o carregador PHP ou o stub de bootstrap de um arquivo Phar para o carregador padrão
- Phar::setMetadata — Define metadados do arquivo phar
- Phar::setSignatureAlgorithm — Define o algoritmo de assinatura para um phar e o aplica
- Phar::setStub — Usado para definir o carregador PHP ou o stub de inicialização de um arquivo Phar
- Phar::startBuffering — Inicia o buffer das operações de gravação Phar, não modifica o objeto Phar no disco
- Phar::stopBuffering — Interrompe o buffer de solicitações de gravação no arquivo Phar e salva as alterações no disco
- Phar::unlinkArchive — Remove completamente um arquivo phar do disco e da memória
- Phar::webPhar — Encaminha uma solicitação de um navegador da web para um arquivo interno dentro do arquivo phar

# A classe PharData

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

## Introdução

A classe PharData fornece uma interface de alto nível para acessar e criar arquivos tar e zip não executáveis. Como esses arquivos não contêm um stub e não podem ser executados pela extensão phar, é possível criar e manipular arquivos zip e tar comuns usando a classe PharData, mesmo que a configuração `phar.readonly` do php.ini seja `1`.

## Resumo da classe

class PharData extends RecursiveDirectoryIterator implements Countable, ArrayAccess {
/* Constantes herdadas */
public const int FilesystemIterator::CURRENT_MODE_MASK;
public const int FilesystemIterator::CURRENT_AS_PATHNAME;
public const int FilesystemIterator::CURRENT_AS_FILEINFO;
public const int FilesystemIterator::CURRENT_AS_SELF;
public const int FilesystemIterator::KEY_MODE_MASK;
public const int FilesystemIterator::KEY_AS_PATHNAME;
public const int FilesystemIterator::FOLLOW_SYMLINKS;
public const int FilesystemIterator::KEY_AS_FILENAME;
public const int FilesystemIterator::NEW_CURRENT_AND_KEY;
public const int FilesystemIterator::OTHER_MODE_MASK;
public const int FilesystemIterator::SKIP_DOTS;
public const int FilesystemIterator::UNIX_PATHS;
/* Métodos */
public function __construct(
string `$filename`,
int `$flags` = FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS,
?string `$alias` = `null`,
int `$format` = 0
)
public function addEmptyDir(string `$directory`): void
public function addFile(string `$filename`, ?string `$localName` = `null`): void
public function addFromString(string `$localName`, string `$contents`): void
public function buildFromDirectory(string `$directory`, string `$pattern` = ""): array
public function buildFromIterator(Traversable `$iterator`, ?string `$baseDirectory` = `null`): array
public function compress(int `$compression`, ?string `$extension` = `null`): ?PharData
public function compressFiles(int `$compression`): void
public function convertToData(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?PharData
public function convertToExecutable(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?Phar
public function copy(string `$from`, string `$to`): true
public function decompress(?string `$extension` = `null`): ?PharData
public function decompressFiles(): true
public function delMetadata(): true
public function delete(string `$localName`): true
public function extractTo(string `$directory`, array|string|null `$files` = `null`, bool `$overwrite` = `false`): bool
public function isWritable(): bool
public function offsetSet(string `$localName`, resource|string `$value`): void
public function offsetUnset(string `$localName`): void
public function setAlias(string `$alias`): bool
public function setDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): bool
public function setMetadata(mixed `$metadata`): void
public function setSignatureAlgorithm(int `$algo`, ?string `$privateKey` = `null`): void
public function setStub(resource|string `$stub`, int `$length` = -1): true
public function __destruct()
/* Métodos herdados */
public function RecursiveDirectoryIterator::getChildren(): RecursiveDirectoryIterator
public function RecursiveDirectoryIterator::getSubPath(): string
public function RecursiveDirectoryIterator::getSubPathname(): string
public function RecursiveDirectoryIterator::hasChildren(bool `$allowLinks` = `false`): bool
public function RecursiveDirectoryIterator::key(): string
public function RecursiveDirectoryIterator::next(): void
public function RecursiveDirectoryIterator::rewind(): void
public function FilesystemIterator::current(): string|SplFileInfo|FilesystemIterator
public function FilesystemIterator::getFlags(): int
public function FilesystemIterator::key(): string
public function FilesystemIterator::next(): void
public function FilesystemIterator::rewind(): void
public function FilesystemIterator::setFlags(int `$flags`): void
public function DirectoryIterator::current(): mixed
public function DirectoryIterator::getBasename(string `$suffix` = ""): string
public function DirectoryIterator::getExtension(): string
public function DirectoryIterator::getFilename(): string
public function DirectoryIterator::isDot(): bool
public function DirectoryIterator::key(): mixed
public function DirectoryIterator::next(): void
public function DirectoryIterator::rewind(): void
public function DirectoryIterator::seek(int `$offset`): void
public function DirectoryIterator::__toString(): string
public function DirectoryIterator::valid(): bool
public function SplFileInfo::getATime(): int|false
public function SplFileInfo::getBasename(string `$suffix` = ""): string
public function SplFileInfo::getCTime(): int|false
public function SplFileInfo::getExtension(): string
public function SplFileInfo::getFileInfo(?string `$class` = `null`): SplFileInfo
public function SplFileInfo::getFilename(): string
public function SplFileInfo::getGroup(): int|false
public function SplFileInfo::getInode(): int|false
public function SplFileInfo::getLinkTarget(): string|false
public function SplFileInfo::getMTime(): int|false
public function SplFileInfo::getOwner(): int|false
public function SplFileInfo::getPath(): string
public function SplFileInfo::getPathInfo(?string `$class` = `null`): ?SplFileInfo
public function SplFileInfo::getPathname(): string
public function SplFileInfo::getPerms(): int|false
public function SplFileInfo::getRealPath(): string|false
public function SplFileInfo::getSize(): int|false
public function SplFileInfo::getType(): string|false
public function SplFileInfo::isDir(): bool
public function SplFileInfo::isExecutable(): bool
public function SplFileInfo::isFile(): bool
public function SplFileInfo::isLink(): bool
public function SplFileInfo::isReadable(): bool
public function SplFileInfo::isWritable(): bool
public function SplFileInfo::openFile(string `$mode` = "r", bool `$useIncludePath` = `false`, ?resource `$context` = `null`): SplFileObject
public function SplFileInfo::setFileClass(string `$class` = `SplFileObject::class`): void
public function SplFileInfo::setInfoClass(string `$class` = `SplFileInfo::class`): void
public function SplFileInfo::__toString(): string
}

# PharData::addEmptyDir

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::addEmptyDir — Adiciona um diretório vazio ao arquivo tar/zip

### Descrição

public function PharData::addEmptyDir(string `$directory`): void

Com este método, um diretório vazio é criado com o caminho `dirname`. Este método é semelhante a ZipArchive::addEmptyDir().

### Parâmetros

`directory`

  O nome do diretório vazio a ser criado no arquivo phar

### Valor Retornado

Nenhum valor de retorno, exceção é lançada em caso de falha.

### Exemplos

Exemplo #1 Um exemplo de PharData::addEmptyDir()

    <?php
    try {
        $a = new PharData('/caminho/para/meu.tar');

        $a->addEmptyDir('/caminho/completo/para/diretorio');
        // demonstra como este diretório é armazenado
        $b = $a['/caminho/completo/para/diretorio']->isDir();
    } catch (Exception $e) {
        // manipula erros aqui
    }
    ?>

### Veja Também

- Phar::addEmptyDir() - Adiciona um diretório vazio ao arquivo phar
- PharData::addFile() - Adiciona um arquivo do sistema de arquivos ao arquivo tar/zip
- PharData::addFromString() - Adiciona um arquivo de uma string ao arquivo tar/zip

# PharData::addFile

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::addFile — Adiciona um arquivo do sistema de arquivos ao arquivo tar/zip

### Descrição

public function PharData::addFile(string `$filename`, ?string `$localName` = `null`): void

Com este método, qualquer arquivo ou URL pode ser adicionado ao arquivo tar/zip. Se o segundo parâmetro opcional `localname` for especificado, o arquivo será armazenado no arquivo com esse nome; caso contrário, o parâmetro `file` será usado como caminho para armazenamento no arquivo. URLs devem ter um localname, ou uma exceção será lançada. Este método é semelhante a ZipArchive::addFile().

### Parâmetros

`filename`

  Caminho completo ou relativo para um arquivo no disco a ser adicionado ao arquivo phar.

`localName`

  Caminho onde o arquivo será armazenado no arquivo compactado.

### Valor Retornado

Nenhum valor de retorno, exceção é lançada em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `localName` agora é anulável.

### Exemplos

Exemplo #1 Um exemplo de PharData::addFile()

    <?php
    try {
        $a = new PharData('/caminho/para/meu.tar');

        $a->addFile('/caminho/completo/para/arquivo');
        // demonstra como este arquivo é armazenado
        $b = $a['/caminho/completo/para/arquivo']->getContent();

        $a->addFile('/caminho/completo/para/arquivo', 'meu/arquivo.txt');
        $c = $a['meu/arquivo.txt']->getContent();

        // demonstra o uso de URL
        $a->addFile('http://www.example.com', 'example.html');
    } catch (Exception $e) {
        // manipula erros aqui
    }
    ?>

### Notas

> Nota: PharData::addFile(), PharData::addFromString() e PharData::offsetSet() salvam um novo arquivo phar cada vez que são chamadas. Se o desempenho for uma preocupação, PharData::buildFromDirectory() ou PharData::buildFromIterator() devem ser usadas.

### Veja Também

- PharData::offsetSet() - Define o conteúdo de um arquivo dentro do tar/zip para o de um arquivo externo ou string
- Phar::addFile() - Adiciona um arquivo do sistema de arquivos ao arquivo phar
- PharData::addFromString() - Adiciona um arquivo de uma string ao arquivo tar/zip
- PharData::addEmptyDir() - Adiciona um diretório vazio ao arquivo tar/zip

# PharData::addFromString

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::addFromString — Adiciona um arquivo de uma string ao arquivo tar/zip

### Descrição

public function PharData::addFromString(string `$localName`, string `$contents`): void

Com este método, qualquer string pode ser adicionada ao arquivo tar/zip. O arquivo será armazenado no arquivo com `localname` como seu caminho. Este método é semelhante a ZipArchive::addFromString().

### Parâmetros

`localName`

  Caminho onde o arquivo será armazenado no arquivo compactado.

`contents`

  O conteúdo do arquivo a ser armazenado

### Valor Retornado

Nenhum valor de retorno, exceção é lançada em caso de falha.

### Exemplos

Exemplo #1 Um exemplo de PharData::addFromString()

    <?php
    try {
        $a = new PharData('/caminho/para/meu.tar');

        $a->addFromString('caminho/para/arquivo.txt', 'meu arquivo simples');
        $b = $a['caminho/para/arquivo.txt']->getContent();

        // para adicionar conteúdo de um identificador de fluxo para arquivos grandes, use offsetSet()()
        $c = fopen('/caminho/para/arquivogigante.bin');
        $a['arquivogigante.bin'] = $c;
        fclose($c);
    } catch (Exception $e) {
        // manipula erros aqui
    }
    ?>

### Notas

> Nota: PharData::addFile(), PharData::addFromString() e PharData::offsetSet() salvam um novo arquivo phar cada vez que são chamadas. Se o desempenho for uma preocupação, PharData::buildFromDirectory() ou PharData::buildFromIterator() devem ser usadas.

### Veja Também

- PharData::offsetSet() - Define o conteúdo de um arquivo dentro do tar/zip para o de um arquivo externo ou string
- Phar::addFromString() - Adiciona um arquivo a partir de uma string ao arquivo phar
- PharData::addFile() - Adiciona um arquivo do sistema de arquivos ao arquivo tar/zip
- PharData::addEmptyDir() - Adiciona um diretório vazio ao arquivo tar/zip

# PharData::buildFromDirectory

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::buildFromDirectory — Constrói um arquivo tar/zip a partir dos arquivos dentro de um diretório

### Descrição

public function PharData::buildFromDirectory(string `$directory`, string `$pattern` = ""): array

Preenche um arquivo tar/zip a partir do conteúdo do diretório. O segundo parâmetro opcional é uma expressão regular (pcre) usada para excluir arquivos. Qualquer nome de arquivo que corresponda à expressão regular será incluído, todos os outros serão excluídos. Para um controle mais refinado, use PharData::buildFromIterator().

### Parâmetros

`directory`

  O caminho completo ou relativo para o diretório que contém todos os arquivos a serem adicionados ao arquivo.

`pattern`

  Uma expressão regular pcre opcional usada para filtrar a lista de arquivos. Somente caminhos de arquivo que correspondam à expressão regular serão incluídos no arquivo.

### Valor Retornado

Phar::buildFromDirectory() retorna um array associativo mapeando o caminho interno do arquivo para o caminho completo do arquivo no sistema de arquivos, ou `false` em caso de falha.

### Erros/Exceções

Este método lança BadMethodCallException quando não é possível instanciar os iteradores de diretório interno, ou uma PharException se houver erros ao salvar o arquivo phar.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | PharData::buildFromDirectory() não retorna mais `false`.

### Exemplos

Exemplo #1 Um exemplo de PharData::buildFromDirectory()

    <?php
    $phar = new PharData('project.tar');
    // adiciona todos os arquivos no projeto
    $phar->buildFromDirectory(dirname(__FILE__) . '/project');

    $phar2 = new PharData('project2.zip');
    // adiciona todos os arquivos no projeto, inclui somente arquivos php
    $phar2->buildFromDirectory(dirname(__FILE__) . '/project', '/\.php$/');
    ?>

### Veja Também

- Phar::buildFromDirectory() - Constrói um arquivo phar a partir dos arquivos dentro de um diretório
- PharData::buildFromIterator() - Constrói um arquivo tar ou zip a partir de um iterador

# PharData::buildFromIterator

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::buildFromIterator — Constrói um arquivo tar ou zip a partir de um iterador

### Descrição

public function PharData::buildFromIterator(Traversable `$iterator`, ?string `$baseDirectory` = `null`): array

Preenche um arquivo tar ou zip a partir de um iterador. Dois estilos de iteradores são suportados: iteradores que mapeiam o nome do arquivo dentro do tar/zip para o nome de um arquivo em disco, e iteradores como DirectoryIterator, que retornam objetos SplFileInfo. Para iteradores que retornam objetos SplFileInfo, o segundo parâmetro é obrigatório.

### Parâmetros

`iterator`

  Qualquer iterador que mapeia associativamente um arquivo tar/zip para um local ou retorna objetos SplFileInfo.

`baseDirectory`

  Para iteradores que retornam objetos SplFileInfo, a parte do caminho completo de cada arquivo a ser removida ao adicionar ao arquivo tar/zip.

### Valor Retornado

PharData::buildFromIterator() retorna um array associativo mapeando o caminho interno do arquivo para o caminho completo do arquivo no sistema de arquivos.

### Erros/Exceções

Este método retorna UnexpectedValueException quando o iterador retorna valores incorretos, como uma chave inteira em vez de uma string, uma BadMethodCallException quando um iterador baseado em SplFileInfo é passado sem um parâmetro `baseDirectory` ou uma PharException se houver erros ao salvar o arquivo phar.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | PharData::buildFromIterator() não retorna mais `false`.
8.0.0 | `baseDirectory` agora é anulável.

### Exemplos

Exemplo #1 Um exemplo de PharData::buildFromIterator() com SplFileInfo

Para a maioria dos arquivos tar/zip, o arquivo refletirá um layout de diretório real, e o segundo estilo é o mais útil. Por exemplo, para criar um arquivo tar/zip contendo os arquivos neste layout de diretório de exemplo:

    /caminho/para/projeto/
                     config/
                            dist.xml
                            debug.xml
                     lib/
                         file1.php
                         file2.php
                     src/
                         processthing.php
                     www/
                         index.php
                     cli/
                         index.php

Este código pode ser usado para adicionar esses arquivos ao arquivo tar "projeto.tar":

    <?php
    $phar = new PharData('projeto.tar');
    $phar->buildFromIterator(
        new RecursiveIteratorIterator(
         new RecursiveDirectoryIterator('/caminho/para/projeto')),
        '/caminho/para/projeto');
    ?>

O arquivo `projeto.tar` pode então ser usado imediatamente. PharData::buildFromIterator() não define valores como compactação e metadados, e isso pode ser feito após a criação do arquivo tar/zip.

Como observação interessante, PharData::buildFromIterator() também pode ser usado para copiar o conteúdo de um arquivo phar, tar ou zip existente, já que o objeto PharData descende de DirectoryIterator:

    <?php
    $phar = new PharData('projeto.tar');
    $phar->buildFromIterator(
        new RecursiveIteratorIterator(
         new Phar('/caminho/para/outrophar.phar')),
        'phar:///caminho/parao/outrophar.phar/caminho/para/projeto');
    $phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
    ?>

Exemplo #2 Um exemplo de PharData::buildFromIterator() com outros iteradores

A segunda forma do iterador pode ser usada com qualquer iterador que retorne um mapeamento chave => valor, como um ArrayIterator:

    <?php
    $phar = new PharData('projeto.tar');
    $phar->buildFromIterator(
        new ArrayIterator(
         array(
            'internos/arquivo.php' => dirname(__FILE__) . '/algumarquivo.php',
            'outros/arquivo.jpg' => fopen('/caminho/para/arquivogrande.jpg', 'rb'),
         )));
    ?>

### Veja Também

- Phar::buildFromIterator() - Constrói um arquivo phar a partir de um iterador

# PharData::compress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::compress — Compacta todo o arquivo tar/zip usando Gzip ou Bzip2

### Descrição

public function PharData::compress(int `$compression`, ?string `$extension` = `null`): ?PharData

Para arquivos tar, este método compacta o arquivo inteiro usando gzip ou bzip2. O arquivo resultante pode ser processado com o comando gunzip/comando bunzip ou acessado direta e transparentemente com a extensão Phar.

Para arquivos zip, este método falha com uma exceção. A extensão zlib deve estar habilitada para compactar com gzip, a extensão bzip2 deve estar habilitada para compactar com bzip2.

Além disso, este método renomeia automaticamente o arquivo, anexando `.gz`, `.bz2` ou removendo a extensão se `Phar::NONE` for passado para remover a compactação. Alternativamente, uma extensão de arquivo pode ser especificada com o segundo parâmetro.

### Parâmetros

`compression`

  A compactação. Deve ser `Phar::GZ`, `Phar::BZ2` para adicionar compactação ou `Phar::NONE` para remover compactação.

`extension`

  Por padrão, a extensão é `.tar.gz` ou `.tar.bz2` para compactar um tar e `.tar` para descompactar.

### Valor Retornado

Um objeto PharData é retornado em caso de sucesso, ou `null` em caso de falha.

### Erros/Exceções

Lança BadMethodCallException se a extensão zlib não estiver disponível ou se a extensão bzip2 não estiver habilitada.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `extension` agora é anulável.

### Exemplos

Exemplo #1 Um exemplo de PharData::compress()

    <?php
    $p = new PharData('/caminho/para/meu.tar');
    $p['meuarquivo.txt'] = 'olá';
    $p['meuarquivo2.txt'] = 'olá';
    $p1 = $p->compress(Phar::GZ); // copia para /caminho/para/meu.tar.gz
    $p2 = $p->compress(Phar::BZ2); // copia para /caminho/para/meu.tar.bz2
    $p3 = $p2->compress(Phar::NONE); // exceção: /caminho/para/meu.tar já existe
    ?>

### Veja Também

- Phar::compress() - Compacta todo o arquivo Phar usando compactação Gzip ou Bzip2

# PharData::compressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::compressFiles — Compacta todos os arquivos no arquivo tar/zip atual

### Descrição

public function PharData::compressFiles(int `$compression`): void

Para arquivos baseados em tar, este método lança uma BadMethodCallException, pois a compactação de arquivos individuais dentro de um arquivo tar não é suportada pelo formato de arquivo. Use PharData::compress() para compactar um arquivo inteiro baseado em tar.

Para arquivos Zip, este método compacta todos os arquivos usando a compactação especificada. As extensões zlib ou bzip2 devem estar habilitadas para aproveitar este recurso. Além disso, se algum arquivo já estiver compactado usando bzip2/zlib, a respectiva extensão deverá ser habilitada para descompactar os arquivos antes de compactar novamente.

### Parâmetros

`compression`

  A compactação. Deve ser `Phar::GZ` ou `Phar::BZ2` para adicionar compactação; ou `Phar::NONE` para remover compactação.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

Lança BadMethodCallException se a variável INI phar.readonly estiver ativada, a extensão zlib não estiver disponível ou se algum arquivo estiver compactado usando a bzip2 e a extensão bzip2 não estiver habilitada.

### Exemplos

Exemplo #1 Um exemplo de PharData::compressFiles()

    <?php
    $p = new Phar('/caminho/para/meu.phar', 0, 'meu.phar');
    $p['meuarquivo.txt'] = 'olá';
    $p['meuarquivo2.txt'] = 'olá';
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    $p->compressFiles(Phar::GZ);
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    ?>

O exemplo acima produzirá:

    string(14) "meuarquivo.txt"
    bool(false)
    bool(false)
    bool(false)
    string(15) "meuarquivo2.txt"
    bool(false)
    bool(false)
    bool(false)
    string(14) "meuarquivo.txt"
    int(4096)
    bool(false)
    bool(true)
    string(15) "meuarquivo2.txt"
    int(4096)
    bool(false)
    bool(true)

### Veja Também

- PharFileInfo::getCompressedSize() - Retorna o tamanho real do arquivo (com compactação) dentro do arquivo Phar
- PharFileInfo::isCompressed() - Informa se a entrada está compactada
- PharFileInfo::compress() - Compacta a entrada Phar atual com zlib ou bzip2
- PharFileInfo::decompress() - Descompacta a entrada Phar atual dentro do phar
- Phar::canCompress() - Retorna se a extensão phar suporta compactação usando zlib ou bzip2
- Phar::isCompressed() - Retorna Phar::GZ ou PHAR::BZ2 se todo o arquivo phar estiver compactado (.tar.gz/tar.bz e assim por diante)
- PharData::decompressFiles() - Descompacta todos os arquivos no arquivo zip atual
- Phar::getSupportedCompression() - Retorna um array de algoritmos de compactação suportados
- PharData::compress() - Compacta todo o arquivo tar/zip usando Gzip ou Bzip2
- PharData::decompress() - Descompacta todo o arquivo Phar

# PharData::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::__construct — Constrói um objeto de arquivo tar ou zip não executável

### Descrição

public function PharData::__construct(
string `$filename`,
int `$flags` = FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS,
?string `$alias` = `null`,
int `$format` = 0
)

### Parâmetros

`filename`

  Caminho para um arquivo tar/zip existente ou arquivo a ser criado

`flags`

  Sinalizadores a serem passados ​​para a classe pai Phar, RecursiveDirectoryIterator.

`alias`

  Apelido ​​com o qual este arquivo Phar deve ser referenciado em chamadas para funcionalidade de fluxo.

`format`

  Uma das constantes de formato de arquivo disponíveis na classe Phar.

### Erros/Exceções

Lança BadMethodCallException se chamado duas vezes; UnexpectedValueException se o arquivo Phar não puder ser aberto.

### Exemplos

Exemplo #1 Um exemplo de PharData::__construct()

    <?php
    try {
        $p = new PharData('/caminho/para/meu.tar', Phar::CURRENT_AS_FILEINFO | Phar::KEY_AS_FILENAME);
    } catch (UnexpectedValueException $e) {
        die('Não foi possível abrir meu.tar');
    } catch (BadMethodCallException $e) {
        echo 'Tecnicamente, isto não pode acontecer';
    }
    echo file_get_contents('phar:///caminho/para/meu.tar/exemplo.txt');
    ?>

# PharData::convertToData

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::convertToData — Converte um arquivo phar em um arquivo tar ou zip não executável

### Descrição

public function PharData::convertToData(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?PharData

Este método é usado para converter um arquivo tar ou zip não executável para outro formato não executável.

Se nenhuma alteração for especificada, este método lança uma BadMethodCallException. Este método deve ser usado para converter um arquivo tar para o formato zip ou vice-versa. Embora seja possível simplesmente alterar a compactação de um arquivo tar usando este método, é melhor usar o método PharData::compress() para consistência lógica.

Se bem-sucedido, o método cria um novo arquivo no disco e retorna um objeto PharData. O arquivo antigo não é removido do disco e deve ser removido manualmente após a conclusão do processo.

### Parâmetros

`format`

  Deve ser um dos seguintes: `Phar::TAR` ou `Phar::ZIP`. Se definido como `null`, o formato de arquivo existente será preservado.

`compression`

  Deve ser um dos seguintes: `Phar::NONE` para nenhuma compactação de arquivo inteiro, `Phar::GZ` para compactação baseada em zlib e `Phar::BZ2` para compactação baseada em bzip.

`extension`

  Este parâmetro é usado para substituir a extensão de arquivo padrão para um arquivo convertido. Observe que `.phar` não pode ser usado em nenhum lugar no nome do arquivo para um arquivo tar ou zip não executável.

  Ao converter para um arquivo phar baseado em tar, as extensões padrão são `.tar`, `.tar.gz`, e `.tar.bz2`, dependendo da compactação especificada. Para arquivos baseados em zip, a extensão padrão é `.zip`.

### Valor Retornado

O método retorna um objeto PharData em caso de sucesso, ou `null` em caso de falha.

### Erros/Exceções

Este método lança uma BadMethodCallException quando não é possível compactar, ou se um método de compactação desconhecido foi especificado, ou se o arquivo solicitado está armazenando em buffer com Phar::startBuffering() e não foi concluído com Phar::stopBuffering(), e uma PharException se algum problema for encontrado durante o processo de criação do phar.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `format`, `compression` e `extension` agora são anuláveis.

### Exemplos

Exemplo #1 Um exemplo de PharData::convertToData()

Usando PharData::convertToData():

    <?php
    try {
        $tarphar = new PharData('meuphar.tar');
        // Observe que meuphar.tar *não* é excluído.
        // Converte para o formato tar não executável.
        // Cria meuphar.zip
        $zip = $tarphar->convertToData(Phar::ZIP);
        // Cria meuphar.tbz
        $tgz = $zip->convertToData(Phar::TAR, Phar::BZ2, '.tbz');
        // Cria meuphar.phar.tgz
        $phar = $tarphar->convertToData(Phar::PHAR); // lança exceção
    } catch (Exception $e) {
        // lida com erros
    }
    ?>

### Veja Também

- Phar::convertToExecutable() - Converte um arquivo phar em outro formato de arquivo executável phar
- Phar::convertToData() - Converte um arquivo phar em um arquivo tar ou zip não executável
- PharData::convertToExecutable() - Converte um arquivo tar/zip não executável em um arquivo phar executável

# PharData::convertToExecutable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::convertToExecutable — Converte um arquivo tar/zip não executável em um arquivo phar executável

### Descrição

public function PharData::convertToExecutable(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?Phar

> Nota: Este método requer que a configuração `phar.readonly` do php.ini seja definida como `0` para funcionar com objetos Phar. Caso contrário, uma exceção PharException será lançada.

Este método é usado para converter um arquivo tar ou zip não executável em um arquivo phar executável. Qualquer um dos três formatos de arquivo executável (phar, tar ou zip) pode ser usado, e a compactação de todo o arquivo também pode ser realizada.

Se nenhuma alteração for especificada, este método lançará uma BadMethodCallException.

Se bem-sucedido, o método cria um novo arquivo no disco e retorna um objeto Phar. O arquivo antigo não é removido do disco e deve ser removido manualmente após a conclusão do processo.

### Parâmetros

`format`

  Deve ser um dos seguintes: `Phar::PHAR`, `Phar::TAR`, ou `Phar::ZIP`. Se definido como `null`, o formato de arquivo existente será preservado.

`compression`

  Deve ser um dos seguintes: `Phar::NONE` para nenhuma compactação de arquivo inteiro, `Phar::GZ` para compactação baseada em zlib e `Phar::BZ2` para compactação baseada em bzip.

`extension`

  Este parâmetro é usado para substituir a extensão de arquivo padrão para um arquivo convertido. Observe que todos os arquivos phar baseados em zip e tar devem conter `.phar` em sua extensão para serem processados ​​como um arquivo phar.

  Ao converter para um arquivo baseado em PHAR, as extensões padrão são `.phar`, `.phar.gz` ou `.phar.bz2` dependendo da compactação especificada. Para arquivos PHAR baseados em tar, as extensões padrão são `.phar.tar`, `.phar.tar.gz` e `.phar.tar.bz2`. Para arquivos PHAR baseados em ZIP, a extensão padrão é `.phar.zip`.

### Valor Retornado

O método retorna um objeto Phar em caso de sucesso, ou `null` em caso de falha.

### Erros/Exceções

Este método lança uma BadMethodCallException quando não é possível compactar, ou se um método de compressão desconhecido foi especificado, ou se o arquivo solicitado está armazenando em buffer com Phar::startBuffering() e não foi concluído com Phar::stopBuffering(); uma UnexpectedValueException se o suporte à gravação estiver desabilitado; e uma PharException se algum problema for encontrado durante o processo de criação do phar.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `format`, `compression` e `localName` agora são anuláveis.

### Exemplos

Exemplo #1 Um exemplo de PharData::convertToExecutable()

Usando PharData::convertToExecutable():

    <?php
    try {
        $tarphar = new PharData('meuphar.tar');
        // Converte para o formato phar
        // Observe que meuphar.tar *não* é excluído
        $phar = $tarphar->convertToExecutable(Phar::PHAR); // cria meuphar.phar
        $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
        // cria meuphar.phar.tgz
        $compressed = $tarphar->convertToExecutable(Phar::TAR, Phar::GZ, '.phar.tgz');
    } catch (Exception $e) {
        // lida com erros
    }
    ?>

### Veja Também

- Phar::convertToExecutable() - Converte um arquivo phar em outro formato de arquivo executável phar
- Phar::convertToData() - Converte um arquivo phar em um arquivo tar ou zip não executável
- PharData::convertToData() - Converte um arquivo phar em um arquivo tar ou zip não executável

# PharData::copy

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::copy — Copia um arquivo interno do arquivo tar/zip para outro arquivo novo dentro do mesmo arquivo

### Descrição

public function PharData::copy(string `$from`, string `$to`): true

Copia um arquivo interno do arquivo tar/zip para outro arquivo novo dentro do mesmo arquivo. Esta é uma alternativa orientada a objetos ao uso de copy() com o empacotador de fluxo phar.

### Parâmetros

`from`

`to`

### Valor Retornado

Sempre retorna `true`.

### Erros/Exceções

Lança UnexpectedValueException se o arquivo de origem não existir, se o arquivo de destino já existir, se o acesso de gravação estiver desabilitado, se a abertura do arquivo falhar, se a leitura do arquivo de origem falhar ou uma PharException se a gravação das alterações no arquivo phar falhar.

### Exemplos

Exemplo #1 Um exemplo de PharData::copy()

Este exemplo mostra o uso de PharData::copy() e o desempenho equivalente do empacotador de fluxo para a mesma coisa. A principal diferença entre as duas abordagens é o tratamento de erros. Todos os métodos PharData geram exceções, enquanto o empacotador de fluxo usa trigger_error().

    <?php

    try {
        $phar = new PharData('meuphar.tar');

        $phar['a'] = 'olá';
        $phar->copy('a', 'b');

        echo $phar['b']; // Exibe "phar://meuphar.tar/b"
    } catch (Exception $e) {
        // Lida com erros
    }

    // O equivalente em empacotador de fluxo para o código acima.
    // E_WARNING é gerado em caso de erros em vez de exceções
    copy('phar://meuphar.tar/a', 'phar//meuphar.tar/c');
    echo file_get_contents('phar://meuphar.tar/c'); // Exibe "olá"

    ?>

# PharData::decompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::decompress — Descompacta todo o arquivo Phar

### Descrição

public function PharData::decompress(?string `$extension` = `null`): ?PharData

Para arquivos baseados em tar, esse método descompacta o arquivo inteiro.

Para arquivos Zip, este método falha com uma exceção. A extensão zlib deve ser habilitada para descompactar um arquivo compactado com gzip, e a bzip2 deve ser habilitada para descompactar um arquivo compactado com bzip2.

Além disso, este método renomeia automaticamente a extensão do arquivo compactado, `.tar` por padrão. Como alternativa, uma extensão de arquivo pode ser especificada com o parâmetro `extension`.

### Parâmetros

`extension`

  Para descompactação, a extensão de arquivo padrão é `.tar`. Use este parâmetro para especificar outra extensão de arquivo. Esteja ciente de que apenas arquivos executáveis ​​podem conter `.phar` em seus nomes.

### Valor Retornado

Um objeto PharData é retornado em caso de sucesso, ou `null` em caso de falha.

### Erros/Exceções

Lança BadMethodCallException se a extensão zlib não estiver disponível ou se a extensão bzip2 não estiver habilitada.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `extension` agora é anulável.

### Exemplos

Exemplo #1 Um exemplo de PharData::decompress()

    <?php
    $p = new PharData('/caminho/para/meu.tar.gz');
    $p->decompress(); // cria /caminho/para/meu.tar
    ?>

### Veja Também

- PharFileInfo::getCompressedSize() - Retorna o tamanho real do arquivo (com compactação) dentro do arquivo Phar
- PharFileInfo::isCompressed() - Informa se a entrada está compactada
- PharFileInfo::compress() - Compacta a entrada Phar atual com zlib ou bzip2
- PharFileInfo::decompress() - Descompacta a entrada Phar atual dentro do phar
- PharData::compress() - Compacta todo o arquivo tar/zip usando Gzip ou Bzip2
- Phar::canCompress() - Retorna se a extensão phar suporta compactação usando zlib ou bzip2
- Phar::isCompressed() - Retorna Phar::GZ ou PHAR::BZ2 se todo o arquivo phar estiver compactado (.tar.gz/tar.bz e assim por diante)
- PharData::compress() - Compacta todo o arquivo tar/zip usando Gzip ou Bzip2
- Phar::getSupportedCompression() - Retorna um array de algoritmos de compactação suportados
- PharData::compressFiles() - Compacta todos os arquivos no arquivo tar/zip atual
- PharData::decompressFiles() - Descompacta todos os arquivos no arquivo zip atual

# PharData::decompressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::decompressFiles — Descompacta todos os arquivos no arquivo zip atual

### Descrição

public function PharData::decompressFiles(): true

> Nota: Este método requer que a configuração `phar.readonly` do php.ini seja definida como `0` para funcionar com objetos Phar. Caso contrário, uma exceção PharException será lançada.

Para arquivos baseados em tar, este método lança uma BadMethodCallException, pois a compactação de arquivos individuais dentro de um arquivo tar não é suportada pelo formato de arquivo. Use PharData::compress() para compactar um arquivo inteiro baseado em tar.

Para arquivos Zip, este método descompacta todos os arquivos no arquivo. As extensões zlib ou bzip2 devem ser habilitadas para aproveitar este recurso se algum arquivo for compactado usando bzip2/zlib.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Sempre retorna `true`.

### Erros/Exceções

Lança BadMethodCallException se a extensão zlib não estiver disponível ou se algum arquivo estiver compactado usando a bzip2 e a extensão bzip2 não estiver habilitada.

### Exemplos

Exemplo #1 Um exemplo de PharData::decompressFiles()

    <?php
    $p = new PharData('/caminho/para/meu.zip');
    $p['meuarquivo.txt'] = 'olá';
    $p['meuarquivo2.txt'] = 'olá';
    $p->compressFiles(Phar::GZ);
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    $p->decompressFiles();
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    ?>

O exemplo acima produzirá:

    string(14) "meuarquivo.txt"
    int(4096)
    bool(false)
    bool(true)
    string(15) "meuarquivo2.txt"
    int(4096)
    bool(false)
    bool(true)
    string(14) "meuarquivo.txt"
    bool(false)
    bool(false)
    bool(false)
    string(15) "meuarquivo2.txt"
    bool(false)
    bool(false)
    bool(false)

### Veja Também

- PharFileInfo::getCompressedSize() - Retorna o tamanho real do arquivo (com compactação) dentro do arquivo Phar
- PharFileInfo::isCompressed() - Informa se a entrada está compactada
- PharFileInfo::compress() - Compacta a entrada Phar atual com zlib ou bzip2
- PharFileInfo::decompress() - Descompacta a entrada Phar atual dentro do phar
- Phar::canCompress() - Retorna se a extensão phar suporta compactação usando zlib ou bzip2
- Phar::isCompressed() - Retorna Phar::GZ ou PHAR::BZ2 se todo o arquivo phar estiver compactado (.tar.gz/tar.bz e assim por diante)
- PharData::compressFiles() - Compacta todos os arquivos no arquivo tar/zip atual
- Phar::getSupportedCompression() - Retorna um array de algoritmos de compactação suportados
- PharData::compress() - Compacta todo o arquivo tar/zip usando Gzip ou Bzip2
- PharData::decompress() - Descompacta todo o arquivo Phar

# PharData::delMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::delMetadata — Exclui os metadados globais de um arquivo zip

### Descrição

public function PharData::delMetadata(): true

> Nota: Este método requer que a configuração `phar.readonly` do php.ini seja definida como `0` para funcionar com objetos Phar. Caso contrário, uma exceção PharException será lançada.

Exclui os metadados globais de um arquivo zip.

### Parâmetros

### Valor Retornado

Sempre retorna `true`.

### Erros/Exceções

Lança PharException se ocorrerem erros durante a descarga de alterações no disco.

### Exemplos

Exemplo #1 Um exemplo de PharData::delMetaData()

    <?php
    try {
        $phar = new PharData('meuphar.zip');
        var_dump($phar->getMetadata());
        $phar->setMetadata("olá mundo");
        var_dump($phar->getMetadata());
        $phar->delMetadata();
        var_dump($phar->getMetadata());
    } catch (Exception $e) {
        // lida com erros
    }
    ?>

O exemplo acima produzirá:

    NULL
    string(9) "olá mundo"
    NULL

### Veja Também

- Phar::delMetadata() - Exclui os metadados globais do phar

# PharData::delete

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::delete — Exclui um arquivo dentro de um arquivo tar/zip

### Descrição

public function PharData::delete(string `$localName`): true

Exclui um arquivo dentro de um arquivo compactado. Este é o equivalente funcional de chamar unlink() no equivalente do empacotador de fluxo, como mostrado no exemplo abaixo.

### Parâmetros

`localName`

  Caminho dentro de um arquivo para o arquivo a ser excluído.

### Valor Retornado

Sempre retorna `true`.

### Erros/Exceções

Lança PharException se ocorrerem erros durante a descarga de alterações no disco.

### Exemplos

Exemplo #1 Um exemplo de PharData::delete()

    <?php
    try {
        $phar = new PharData('meuphar.zip');
        $phar->delete('remova/me.php');
        // isto é equivalente a:
        unlink('phar://meuphar.phar/remova/me.php');
    } catch (Exception $e) {
        // lida com erros
    }
    ?>

### Veja Também

- Phar::delete() - Exclui um arquivo dentro de um arquivo phar

# PharData::__destruct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::__destruct — Destrói um objeto de arquivo tar ou zip não executável

### Descrição

public function PharData::__destruct()

### Parâmetros

Esta função não possui parâmetros.

# PharData::extractTo

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::extractTo — Extrai o conteúdo de um arquivo tar/zip para um diretório

### Descrição

public function PharData::extractTo(string `$directory`, array|string|null `$files` = `null`, bool `$overwrite` = `false`): bool

Extrai todos os arquivos de um arquivo tar/zip para o disco. Os arquivos e diretórios extraídos preservam as permissões conforme armazenadas no arquivo. Os parâmetros opcionais permitem controle opcional sobre quais arquivos são extraídos e se os arquivos existentes no disco podem ser sobrescritos. O segundo parâmetro `files` pode ser o nome de um arquivo ou diretório a ser extraído, ou um array de nomes de arquivos e diretórios a serem extraídos. Por padrão, este método não sobrescreve arquivos existentes; o terceiro parâmetro pode ser definido como true para habilitar a sobrescrita de arquivos. Este método é semelhante a ZipArchive::extractTo().

### Parâmetros

`directory`

  Caminho para o qual devem ser extraídos os arquivos informados em `files`.

`files`

  O nome de um arquivo ou diretório a ser extraído, ou um array de arquivos/diretórios a serem extraídos.

`overwrite`

  Defina como `true` para habilitar a substituição de arquivos existentes.

### Valor Retornado

Retorna `true` em caso de sucesso, mas é melhor verificar se há exceções lançadas e assumir sucesso se nenhuma for lançada.

### Erros/Exceções

Lança PharException se ocorrerem erros durante a descarga de alterações no disco.

### Exemplos

Exemplo #1 Um exemplo de PharData::extractTo()

    <?php
    try {
        $phar = new PharData('meuphar.tar');
        $phar->extractTo('/caminho/completo'); // extrai todos os arquivos
        $phar->extractTo('/caminho/alternativo', 'arquivo.txt'); // extrai somente arquivo.txt
        $phar->extractTo('/este/caminho',
            array('arquivo1.txt', 'arquivo2.txt')); // extrai somente 2 arquivos
        $phar->extractTo('/terceiro/caminho', null, true); // extrai todos os arquivos e sobrescreve
    } catch (Exception $e) {
        // lida com erros
    }
    ?>

### Notas

> Nota: O sistema de arquivos NTFS do Windows não suporta alguns caracteres em nomes de arquivos, como `<|>*?":`. Nomes de arquivos que terminam com ponto também não são suportados. Ao contrário de algumas ferramentas de extração, este método não substitui estes caracteres por um sublinhado, mas falha ao extrair esses arquivos.

### Veja Também

- Phar::extractTo() - Extrai o conteúdo de um arquivo phar para um diretório

# PharData::isWritable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::isWritable — Informa se o arquivo tar/zip pode ser modificado

### Descrição

public function PharData::isWritable(): bool

Este método retorna `true` se o arquivo tar/zip no disco não for somente leitura. Ao contrário de Phar::isWritable(), arquivos tar/zip somente dados podem ser modificados mesmo se `phar.readonly` estiver definido como `1`.

### Parâmetros

Sem parâmetros.

### Valor Retornado

Retorna `true` se o arquivo tar/zip puder ser modificado.

### Veja Também

- Phar::canWrite() - Retorna se a extensão phar suporta a escrita e criação de phars
- Phar::isWritable() - Informa se o arquivo phar pode ser modificado

# PharData::offsetSet

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::offsetSet — Define o conteúdo de um arquivo dentro do tar/zip para o de um arquivo externo ou string

### Descrição

public function PharData::offsetSet(string `$localName`, resource|string `$value`): void

Esta é uma implementação da interface ArrayAccess que permite a manipulação direta do conteúdo de um arquivo tar/zip usando colchetes de acesso a arrays. offsetSet é usado para modificar um arquivo existente ou adicionar um novo arquivo a um arquivo tar/zip.

### Parâmetros

`localName`

  O nome do arquivo (caminho relativo) a ser modificado em um arquivo tar ou zip.

`value`

  Conteúdo do arquivo.

### Valor Retornado

Sem valores de retorno.

### Erros/Exceções

Lança PharException se houver algum problema ao liberar as alterações feitas no arquivo tar/zip para o disco.

### Exemplos

Exemplo #1 Um exemplo de PharData::offsetSet()

offsetSet não deve ser acessado diretamente, mas sim usado por meio de acesso a array com o operador `[]`.

    <?php
    $p = new PharData('/caminho/para/meu.tar');
    try {
        // chama offsetSet
        $p['arquivo.txt'] = 'Olá mundo';
    } catch (Exception $e) {
        echo 'Não foi possível modificar arquivo.txt:', $e;
    }
    ?>

### Notas

> Nota: PharData::addFile(), PharData::addFromString() e PharData::offsetSet() salvam um novo arquivo phar cada vez que são chamadas. Se o desempenho for uma preocupação, PharData::buildFromDirectory() ou PharData::buildFromIterator() devem ser usadas.

### Veja Também

- Phar::offsetSet() - Define o conteúdo de um arquivo interno para o de um arquivo externo

# PharData::offsetUnset

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::offsetUnset — Remove um arquivo de um arquivo tar/zip

### Descrição

public function PharData::offsetUnset(string `$localName`): void

Esta é uma implementação da interface ArrayAccess que permite a manipulação direta do conteúdo de um arquivo tar/zip usando colchetes de acesso a arrays. offsetUnset é usado para excluir um arquivo existente e é chamado pela construção de linguagem unset().

### Parâmetros

`localName`

  O nome do arquivo (caminho relativo) a ser modificado no arquivo tar/zip.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

Lança PharException se houver algum problema ao liberar as alterações feitas no arquivo tar/zip para o disco.

### Exemplos

Exemplo #1 Um exemplo de PharData::offsetUnset()

    <?php
    $p = new PharData('/caminho/para/meu.zip');
    try {
        // exclui arquivo.txt de meu.zip chamando offsetUnset
        unset($p['arquivo.txt']);
    } catch (Exception $e) {
        echo 'Não foi possível excluir arquivo.txt: ', $e;
    }
    ?>

### Veja Também

- Phar::offsetUnset() - Remove um arquivo de um phar

# PharData::setAlias

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::setAlias — Função fictícia (Phar::setAlias ​​não é válido para PharData)

### Descrição

public function PharData::setAlias(string `$alias`): bool

Arquivos tar/zip não executáveis ​​não podem ter um apelido, então esse método simplesmente gera uma exceção.

### Parâmetros

`alias`

  Uma string abreviada à qual este arquivo pode ser referenciado no acesso ao empacotador de fluxo `phar`. Este parâmetro é ignorado.

### Valor Retornado

### Erros/Exceções

Lança PharException em todas as chamadas do método.

### Veja Também

- Phar::setAlias() - Define o apelido para o arquivo Phar

# PharData::setDefaultStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::setDefaultStub — Função fictícia (Phar::setDefaultStub não é válido para PharData)

### Descrição

public function PharData::setDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): bool

Arquivos tar/zip não executáveis ​​não podem ter um stub, então esse método simplesmente gera uma exceção.

### Parâmetros

`index`

  Caminho relativo dentro do arquivo phar para execução se acessado na linha de comando

`webIndex`

  Caminho relativo dentro do arquivo phar para ser executado se acessado por meio de um navegador da web

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Lança PharException em todas as chamadas do método

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `webIndex` agora é anulável.

### Veja Também

- Phar::setDefaultStub() - Usado para definir o carregador PHP ou o stub de bootstrap de um arquivo Phar para o carregador padrão

# PharData::setMetadata

(No version information available, might only be in Git)

PharData::setMetadata — Define metadados do arquivo phar

### Descrição

public function PharData::setMetadata(mixed `$metadata`): void

> Nota: Este método requer que a configuração `phar.readonly` do php.ini seja definida como `0` para funcionar com objetos Phar. Caso contrário, uma exceção PharException será lançada.

Phar::setMetadata() deve ser usado para armazenar dados personalizados que descrevam algo sobre o arquivo phar como uma entidade completa. PharFileInfo::setMetadata() deve ser usado para metadados específicos do arquivo. Metadados podem reduzir o desempenho do carregamento de um arquivo phar se os dados forem grandes.

Alguns usos possíveis para metadados incluem especificar qual arquivo dentro do arquivo deve ser usado para inicializar o arquivo, ou a localização de um manifesto de arquivo como o arquivo package.xml do » PEAR. No entanto, quaisquer dados úteis que descrevam o arquivo phar podem ser armazenados.

### Parâmetros

`metadata`

  Qualquer variável PHP contendo informações para armazenar que descrevem o arquivo phar

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Um exemplo de Phar::setMetadata()

    <?php
    // garantindo que o arquivo não existe
    @unlink('novophar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/novophar.phar', 0, 'novophar.phar');
        $p['arquivo.php'] = '<?php echo "olá"';
        $p->setMetadata(array('bootstrap' => 'arquivo.php'));
        var_dump($p->getMetadata());
    } catch (Exception $e) {
        echo 'Não foi possível criar e/ou modificar o phar:', $e;
    }
    ?>

O exemplo acima produzirá:

    array(1) {
      ["bootstrap"]=>
      string(11) "arquivo.php"
    }

### Veja Também

- Phar::getMetadata() - Retorna metadados do arquivo phar
- Phar::delMetadata() - Exclui os metadados globais do phar
- Phar::hasMetadata() - Informa se o phar tem metadados globais

# PharData::setSignatureAlgorithm

(No version information available, might only be in Git)

PharData::setSignatureAlgorithm — Define o algoritmo de assinatura para um phar e o aplica

### Descrição

public function PharData::setSignatureAlgorithm(int `$algo`, ?string `$privateKey` = `null`): void

> Nota: Este método requer que a configuração `phar.readonly` do php.ini seja definida como `0` para funcionar com objetos Phar. Caso contrário, uma exceção PharException será lançada.

Define o algoritmo de assinatura para um phar e o aplica. O algoritmo de assinatura deve ser um dos seguintes: `Phar::MD5`, `Phar::SHA1`, `Phar::SHA256`, `Phar::SHA512` ou `Phar::OPENSSL`.

### Parâmetros

`algo`

  Um dos seguintes: `Phar::MD5`, `Phar::SHA1`, `Phar::SHA256`, `Phar::SHA512` ou `Phar::OPENSSL`

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

Lança UnexpectedValueException para muitos erros, BadMethodCallException se chamado para um arquivo zip ou um arquivo phar baseado em tar, e uma PharException se ocorrer algum problema ao liberar as alterações no disco.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `privateKey` agora é anulável.

### Veja Também

- Phar::getSupportedSignatures() - Retorna um array de tipos de assinatura suportados
- Phar::getSignature() - Retorna a assinatura MD5/SHA1/SHA256/SHA512/OpenSSL de um arquivo Phar

# PharData::setStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::setStub — Função fictícia (Phar::setStub não é válido para PharData)

### Descrição

public function PharData::setStub(resource|string `$stub`, int `$length` = -1): true

Arquivos tar/zip não executáveis ​​não podem ter um stub, então esse método simplesmente gera uma exceção.

### Parâmetros

`stub`
  Formalmente, uma string ou um identificador de fluxo aberto para usar como stub executável para este arquivo phar. Este parâmetro é ignorado.
`length`
  `stub` em bytes. Este parâmetro é ignorado.

### Valor Retornado

Sempre retorna `true`.

### Erros/Exceções

Lança PharException em todas as chamadas do método

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | O tipo do retorno agora é `true`; anteriormente, era bool.

### Veja Também

- Phar::setStub() - Usado para definir o carregador PHP ou o stub de inicialização de um arquivo Phar

## Índice

- PharData::addEmptyDir — Adiciona um diretório vazio ao arquivo tar/zip
- PharData::addFile — Adiciona um arquivo do sistema de arquivos ao arquivo tar/zip
- PharData::addFromString — Adiciona um arquivo de uma string ao arquivo tar/zip
- PharData::buildFromDirectory — Constrói um arquivo tar/zip a partir dos arquivos dentro de um diretório
- PharData::buildFromIterator — Constrói um arquivo tar ou zip a partir de um iterador
- PharData::compress — Compacta todo o arquivo tar/zip usando Gzip ou Bzip2
- PharData::compressFiles — Compacta todos os arquivos no arquivo tar/zip atual
- PharData::__construct — Constrói um objeto de arquivo tar ou zip não executável
- PharData::convertToData — Converte um arquivo phar em um arquivo tar ou zip não executável
- PharData::convertToExecutable — Converte um arquivo tar/zip não executável em um arquivo phar executável
- PharData::copy — Copia um arquivo interno do arquivo tar/zip para outro arquivo novo dentro do mesmo arquivo
- PharData::decompress — Descompacta todo o arquivo Phar
- PharData::decompressFiles — Descompacta todos os arquivos no arquivo zip atual
- PharData::delMetadata — Exclui os metadados globais de um arquivo zip
- PharData::delete — Exclui um arquivo dentro de um arquivo tar/zip
- PharData::__destruct — Destrói um objeto de arquivo tar ou zip não executável
- PharData::extractTo — Extrai o conteúdo de um arquivo tar/zip para um diretório
- PharData::isWritable — Informa se o arquivo tar/zip pode ser modificado
- PharData::offsetSet — Define o conteúdo de um arquivo dentro do tar/zip para o de um arquivo externo ou string
- PharData::offsetUnset — Remove um arquivo de um arquivo tar/zip
- PharData::setAlias — Função fictícia (Phar::setAlias ​​não é válido para PharData)
- PharData::setDefaultStub — Função fictícia (Phar::setDefaultStub não é válido para PharData)
- PharData::setMetadata — Define metadados do arquivo phar
- PharData::setSignatureAlgorithm — Define o algoritmo de assinatura para um phar e o aplica
- PharData::setStub — Função fictícia (Phar::setStub não é válido para PharData)

# A classe PharFileInfo

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

## Introdução

A classe PharFileInfo fornece uma interface de alto nível para o conteúdo e atributos de um único arquivo dentro de um arquivo phar.

## Resumo da classe

class PharFileInfo extends SplFileInfo {
/* Métodos */
public function __construct(string `$filename`)
public function chmod(int `$perms`): void
public function compress(int `$compression`): true
public function decompress(): true
public function delMetadata(): true
public function getCRC32(): int
public function getCompressedSize(): int
public function getContent(): string
public function getMetadata(array `$unserializeOptions` = []): mixed
public function getPharFlags(): int
public function hasMetadata(): bool
public function isCRCChecked(): bool
public function isCompressed(?int `$compression` = `null`): bool
public function setMetadata(mixed `$metadata`): void
public function __destruct()
/* Métodos herdados */
public function SplFileInfo::getATime(): int|false
public function SplFileInfo::getBasename(string `$suffix` = ""): string
public function SplFileInfo::getCTime(): int|false
public function SplFileInfo::getExtension(): string
public function SplFileInfo::getFileInfo(?string `$class` = `null`): SplFileInfo
public function SplFileInfo::getFilename(): string
public function SplFileInfo::getGroup(): int|false
public function SplFileInfo::getInode(): int|false
public function SplFileInfo::getLinkTarget(): string|false
public function SplFileInfo::getMTime(): int|false
public function SplFileInfo::getOwner(): int|false
public function SplFileInfo::getPath(): string
public function SplFileInfo::getPathInfo(?string `$class` = `null`): ?SplFileInfo
public function SplFileInfo::getPathname(): string
public function SplFileInfo::getPerms(): int|false
public function SplFileInfo::getRealPath(): string|false
public function SplFileInfo::getSize(): int|false
public function SplFileInfo::getType(): string|false
public function SplFileInfo::isDir(): bool
public function SplFileInfo::isExecutable(): bool
public function SplFileInfo::isFile(): bool
public function SplFileInfo::isLink(): bool
public function SplFileInfo::isReadable(): bool
public function SplFileInfo::isWritable(): bool
public function SplFileInfo::openFile(string `$mode` = "r", bool `$useIncludePath` = `false`, ?resource `$context` = `null`): SplFileObject
public function SplFileInfo::setFileClass(string `$class` = `SplFileObject::class`): void
public function SplFileInfo::setInfoClass(string `$class` = `SplFileInfo::class`): void
public function SplFileInfo::__toString(): string
}

# PharFileInfo::chmod

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::chmod — Define bits de permissão específicos do arquivo

### Descrição

public function PharFileInfo::chmod(int `$perms`): void

PharFileInfo::chmod() permite a configuração do bit de permissão do arquivo executável, bem como bits somente leitura. Os bits graváveis ​​são ignorados e definidos em tempo de execução com base na variável INI phar.readonly. Assim como acontece com todas as funcionalidades que modificam o conteúdo de um phar, a variável INI phar.readonly deve estar desativada para funcionar se o arquivo estiver dentro de um arquivo Phar. Arquivos dentro de arquivos PharData não têm essa restrição.

### Parâmetros

`perms`

  permissões (consulte chmod())

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Um exemplo de PharFileInfo::chmod()

    <?php
    // garantindo que o arquivo não existe
    @unlink('novophar.phar');
    try {
        $p = new Phar('novophar.phar', 0, 'novophar.phar');
        $p['arquivo.sh'] = '#!/usr/local/lib/php
        <?php echo "olá"; ?>';
        // define o bit executável
        $p['arquivo.sh']->chmod(0555);
        var_dump($p['arquivo.sh']->isExecutable());
    } catch (Exception $e) {
        echo 'Não foi possível criar/modificar o phar: ', $e;
    }
    ?>

O exemplo acima produzirá:

    bool(true)

# PharFileInfo::compress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharFileInfo::compress — Compacta a entrada Phar atual com zlib ou bzip2

### Descrição

public function PharFileInfo::compress(int `$compression`): true

Este método compacta o arquivo dentro do arquivo Phar usando a compactação bzip2 ou zlib. A extensão bzip2 ou zlib deve estar habilitada para aproveitar este recurso. Além disso, se o arquivo já estiver compactado, a respectiva extensão deve ser habilitada para descompactá-lo. Assim como acontece com todas as funcionalidades que modificam o conteúdo de um arquivo Phar, a variável INI phar.readonly deve estar desativada para funcionar se o arquivo estiver dentro de um arquivo Phar. Arquivos dentro de arquivos PharData não têm essa restrição.

### Parâmetros

`compression`

  A compactação deve ser `Phar::GZ` ou `Phar::BZ2`.

### Valor Retornado

Sempre retorna `true`.

### Erros/Exceções

Lança BadMethodCallException se a variável INI phar.readonly estiver ativada ou se a extensão bzip2/zlib não estiver disponível.

### Exemplos

Exemplo #1 Um exemplo de PharFileInfo::compress()

    <?php
    try {
        $p = new Phar('/caminho/para/meu.phar', 0, 'meu.phar');
        $p['meuarquivo.txt'] = 'olá';
        $file = $p['meuarquivo.txt'];
        var_dump($file->isCompressed(Phar::BZ2));
        $p['meuarquivo.txt']->compress(Phar::BZ2);
        var_dump($file->isCompressed(Phar::BZ2));
    } catch (Exception $e) {
        echo 'Operações de criação/modificação em meu.phar falhou: ', $e;
    }
    ?>

O exemplo acima produzirá:

    bool(false)
    bool(true)

### Veja Também

- PharFileInfo::getCompressedSize() - Retorna o tamanho real do arquivo (com compactação) dentro do arquivo Phar
- PharFileInfo::isCompressed() - Informa se a entrada está compactada
- PharFileInfo::decompress() - Descompacta a entrada Phar atual dentro do phar
- Phar::canCompress() - Retorna se a extensão phar suporta compactação usando zlib ou bzip2
- Phar::isCompressed() - Retorna Phar::GZ ou PHAR::BZ2 se todo o arquivo phar estiver compactado (.tar.gz/tar.bz e assim por diante)
- Phar::compressFiles() - Compacta todos os arquivos no arquivo Phar atual
- Phar::decompressFiles() - Descompacta todos os arquivos no arquivo Phar atual
- Phar::compress() - Compacta todo o arquivo Phar usando compactação Gzip ou Bzip2
- Phar::decompress() - Descompacta todo o arquivo Phar
- Phar::getSupportedCompression() - Retorna um array de algoritmos de compactação suportados

# PharFileInfo::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::__construct — Constrói um objeto de entrada Phar

### Descrição

public function PharFileInfo::__construct(string `$filename`)

Este método não deve ser chamado diretamente. Em vez disso, um objeto PharFileInfo é inicializado chamando Phar::offsetGet() por meio de acesso a array.

### Parâmetros

`filename`

  A URL completa para recuperar um arquivo. Se for necessário recuperar as informações do arquivo `meu/arquivo.php` do diretório `boo.phar`, a entrada deve ser `phar://boo.phar/meu/arquivo.php`.

### Erros/Exceções

Lança BadMethodCallException se __construct() for chamado duas vezes. Lança UnexpectedValueException se a URL do phar solicitada estiver incorreta, o phar solicitado não puder ser aberto ou o arquivo não puder ser encontrado dentro do phar.

### Exemplos

Exemplo #1 Um exemplo de PharFileInfo::__construct()

    <?php
    try {
        $p = new Phar('/caminho/para/meu.phar', 0, 'meu.phar');
        $p['arquivoteste.txt'] = "bom\ndia\npessoal";
        $file = $p['arquivoteste.txt'];
        foreach ($file as $line => $text) {
            echo "linha número $line: $text";
        }
        // isto também funciona
        $file = new PharFileInfo('phar:///caminho/para/meu.phar/arquivoteste.txt');
        foreach ($file as $line => $text) {
            echo "linha número $line: $text";
        }
    } catch (Exception $e) {
        echo 'Operações Phar falharam: ', $e;
    }
    ?>

O exemplo acima produzirá:

    linha número 1: bom
    linha número 2: dia
    linha número 3: pessoal
    linha número 1: bom
    linha número 2: dia
    linha número 3: pessoal

# PharFileInfo::decompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharFileInfo::decompress — Descompacta a entrada Phar atual dentro do phar

### Descrição

public function PharFileInfo::decompress(): true

Este método descompacta o arquivo dentro do arquivo Phar. Dependendo de como o arquivo é compactado, as extensões bzip2 ou zlib devem estar habilitadas para aproveitar este recurso. Assim como acontece com todas as funcionalidades que modificam o conteúdo de um phar, a variável INI phar.readonly deve estar desativada para funcionar se o arquivo estiver dentro de um arquivo Phar. Arquivos dentro de arquivos PharData não têm esta restrição.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Sempre retorna `true`.

### Erros/Exceções

Lança BadMethodCallException se a variável INI phar.readonly estiver ativada ou se a extensão bzip2/zlib não estiver disponível.

### Exemplos

Exemplo #1 Um exemplo de PharFileInfo::decompress()

    <?php
    try {
        $p = new Phar('/caminho/para/meu.phar', 0, 'meu.phar');
        $p['meuarquivo.txt'] = 'olá';
        $file = $p['meuarquivo.txt'];
        $file->compress(Phar::GZ);
        var_dump($file->isCompressed());
        $p['meuarquivo.txt']->decompress();
        var_dump($file->isCompressed());
    } catch (Exception $e) {
        echo 'Criação/modificação falhou para meu.phar: ', $e;
    }
    ?>

O exemplo acima produzirá:

    int(4096)
    bool(false)

### Veja Também

- PharFileInfo::getCompressedSize() - Retorna o tamanho real do arquivo (com compactação) dentro do arquivo Phar
- PharFileInfo::isCompressed() - Informa se a entrada está compactada
- PharFileInfo::compress() - Compacta a entrada Phar atual com zlib ou bzip2
- Phar::canCompress() - Retorna se a extensão phar suporta compactação usando zlib ou bzip2
- Phar::isCompressed() - Retorna Phar::GZ ou PHAR::BZ2 se todo o arquivo phar estiver compactado (.tar.gz/tar.bz e assim por diante)
- Phar::compressFiles() - Compacta todos os arquivos no arquivo Phar atual
- Phar::decompressFiles() - Descompacta todos os arquivos no arquivo Phar atual
- Phar::compress() - Compacta todo o arquivo Phar usando compactação Gzip ou Bzip2
- Phar::decompress() - Descompacta todo o arquivo Phar
- Phar::getSupportedCompression() - Retorna um array de algoritmos de compactação suportados

# PharFileInfo::delMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

PharFileInfo::delMetadata — Exclui os metadados da entrada

### Descrição

public function PharFileInfo::delMetadata(): true

Exclui os metadados da entrada, se existirem.

### Parâmetros

Sem parâmetros.

### Valor Retornado

Sempre retorna `true`. Assim como acontece com todas as funcionalidades que modificam o conteúdo de um phar, a variável INI phar.readonly deve estar desativada para funcionar se o arquivo estiver dentro de um arquivo Phar. Arquivos dentro de arquivos PharData não têm essa restrição.

### Erros/Exceções

Lança PharException se ocorrerem erros ao liberar as alterações no disco e BadMethodCallException se o acesso de gravação estiver desabilitado.

### Exemplos

Exemplo #1 Um exemplo de PharFileInfo::delMetaData()

    <?php
    try {
        $a = new Phar('meuphar.phar');
        $a['olá'] = 'olá';
        var_dump($a['olá']->delMetadata());
        $a['olá']->setMetadata('pessoal');
        var_dump($a['olá']->delMetadata());
        var_dump($a['olá']->delMetadata());
    } catch (Exception $e) {
        // lida com erros
    }
    ?>

O exemplo acima produzirá:

    bool(false)
    bool(true)
    bool(false)

### Veja Também

- PharFileInfo::setMetadata() - Define metadados específicos de arquivo salvos com um arquivo
- PharFileInfo::hasMetadata() - Retorna os metadados da entrada
- PharFileInfo::getMetadata() - Retorna metadados específicos do arquivo salvos com um arquivo
- Phar::setMetadata() - Define metadados do arquivo phar
- Phar::hasMetadata() - Informa se o phar tem metadados globais
- Phar::getMetadata() - Retorna metadados do arquivo phar

# PharFileInfo::__destruct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::__destruct — Destrói um objeto de entrada Phar

### Descrição

public function PharFileInfo::__destruct()

### Parâmetros

Esta função não possui parâmetros.

# PharFileInfo::getCRC32

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getCRC32 — Retorna o código CRC32 ou lança uma exceção se o CRC não tiver sido verificado

### Descrição

public function PharFileInfo::getCRC32(): int

Isso retorna a soma de verificação crc32() do arquivo dentro do arquivo Phar.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

A soma de verificação crc32() do arquivo dentro do arquivo Phar.

### Erros/Exceções

Lança BadMethodCallException se o arquivo ainda não teve seu CRC32 verificado. Isso deveria ser impossível com o uso normal, pois o CRC é verificado ao abrir o arquivo para leitura ou escrita.

### Exemplos

Exemplo #1 Um exemplo de PharFileInfo::getCRC32()

    <?php
    try {
        $p = new Phar('/caminho/para/meu.phar', 0, 'meu.phar');
        $p['meuarquivo.txt'] = 'olá';
        $file = $p['meuarquivo.txt'];
        echo $file->getCRC32();
    } catch (Exception $e) {
        echo 'As operações de gravação em meu.phar falharam: ', $e;
    }
    ?>

O exemplo acima produzirá:

    1120542206

# PharFileInfo::getCompressedSize

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getCompressedSize — Retorna o tamanho real do arquivo (com compactação) dentro do arquivo Phar

### Descrição

public function PharFileInfo::getCompressedSize(): int

Isso retorna o tamanho do arquivo dentro do arquivo Phar. Arquivos descompactados retornarão o mesmo valor para getCompressedSize que retornariam com filesize().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O tamanho em bytes do arquivo dentro do arquivo Phar no disco.

### Exemplos

Exemplo #1 Um exemplo de PharFileInfo::getCompressedSize()

    <?php
    try {
        $p = new Phar('/caminho/para/meu.phar', 0, 'meu.phar');
        $p['meuarquivo.txt'] = 'olá';
        $file = $p['meuarquivo.txt'];
        echo $file->getCompressedSize();
    } catch (Exception $e) {
        echo 'As operações de gravação falharam em meu.phar: ', $e;
    }
    ?>

O exemplo acima produzirá:

    4

### Veja Também

- PharFileInfo::isCompressed() - Informa se a entrada está compactada
- PharFileInfo::decompress() - Descompacta a entrada Phar atual dentro do phar
- PharFileInfo::compress() - Compacta a entrada Phar atual com zlib ou bzip2
- Phar::canCompress() - Retorna se a extensão phar suporta compactação usando zlib ou bzip2
- Phar::isCompressed() - Retorna Phar::GZ ou PHAR::BZ2 se todo o arquivo phar estiver compactado (.tar.gz/tar.bz e assim por diante)
- Phar::compress() - Compacta todo o arquivo Phar usando compactação Gzip ou Bzip2
- Phar::decompress() - Descompacta todo o arquivo Phar
- Phar::getSupportedCompression() - Retorna um array de algoritmos de compactação suportados
- Phar::decompressFiles() - Descompacta todos os arquivos no arquivo Phar atual
- Phar::compressFiles() - Compacta todos os arquivos no arquivo Phar atual

# PharFileInfo::getContent

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

PharFileInfo::getContent — Obtém o conteúdo completo do arquivo de entrada

### Descrição

public function PharFileInfo::getContent(): string

Esta função se comporta como file_get_contents(), porém para Phar.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o conteúdo do arquivo.

# PharFileInfo::getMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getMetadata — Retorna metadados específicos do arquivo salvos com um arquivo

### Descrição

public function PharFileInfo::getMetadata(array `$unserializeOptions` = []): mixed

Retorna metadados que foram salvos no manifesto do arquivo Phar para este arquivo.

### Parâmetros

### Valor Retornado

Qualquer variável PHP que possa ser serializada e armazenada como metadados para o arquivo, ou `null` se nenhum metadado for armazenado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `unserializeOptions` foi adicionado.

### Exemplos

Exemplo #1 Um exemplo de PharFileInfo::getMetadata()

    <?php
    // garantindo que o arquivo não existe
    @unlink('novophar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/novophar.phar', 0, 'novophar.phar');
        $p['arquivo.txt'] = 'olá';
        $p['arquivo.txt']->setMetadata(array('usuario' => 'igor', 'mime-type' => 'text/plain'));
        var_dump($p['arquivo.txt']->getMetadata());
    } catch (Exception $e) {
        echo 'Não foi possível criar/modificar novophar.phar: ', $e;
    }
    ?>

O exemplo acima produzirá:

    array(2) {
      ["usuario"]=>
      string(4) "igor"
      ["mime-type"]=>
      string(10) "text/plain"
    }

### Veja Também

- PharFileInfo::setMetadata() - Define metadados específicos de arquivo salvos com um arquivo
- PharFileInfo::hasMetadata() - Retorna os metadados da entrada
- PharFileInfo::delMetadata() - Exclui os metadados da entrada
- Phar::setMetadata() - Define metadados do arquivo phar
- Phar::hasMetadata() - Informa se o phar tem metadados globais
- Phar::getMetadata() - Retorna metadados do arquivo phar

# PharFileInfo::getPharFlags

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getPharFlags — Retorna os sinalizadores de entrada do arquivo Phar

### Descrição

public function PharFileInfo::getPharFlags(): int

Este método retorna os sinalizadores definidos no manifesto para um Phar. Sempre retornará `0` na implementação atual.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Os sinalizadores Phar (sempre `0` na implementação atual)

### Exemplos

Exemplo #1 Um exemplo de PharFileInfo::getPharFlags()

    <?php
    try {
        $p = new Phar('/caminho/para/meu.phar', 0, 'meu.phar');
        $p['meuarquivo.txt'] = 'olá';
        $file = $p['meuarquivo.txt'];
        var_dump($file->getPharFlags());
    } catch (Exception $e) {
        echo 'Não foi possível criar/modificar meu.phar: ', $e;
    }
    ?>

O exemplo acima produzirá:

    int(0)

# PharFileInfo::hasMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

PharFileInfo::hasMetadata — Retorna os metadados da entrada

### Descrição

public function PharFileInfo::hasMetadata(): bool

Retorna os metadados de um arquivo dentro de um arquivo phar.

### Parâmetros

Sem parâmetros.

### Valor Retornado

Retorna `false` se nenhum metadado for definido ou for `null`, `true` se os metadados não forem `null`

### Veja Também

- PharFileInfo::setMetadata() - Define metadados específicos de arquivo salvos com um arquivo
- PharFileInfo::getMetadata() - Retorna metadados específicos do arquivo salvos com um arquivo
- PharFileInfo::delMetadata() - Exclui os metadados da entrada
- Phar::setMetadata() - Define metadados do arquivo phar
- Phar::hasMetadata() - Informa se o phar tem metadados globais
- Phar::getMetadata() - Retorna metadados do arquivo phar

# PharFileInfo::isCRCChecked

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::isCRCChecked — Informa se a entrada do arquivo teve seu CRC verificado

### Descrição

public function PharFileInfo::isCRCChecked(): bool

Este método retorna se um arquivo dentro de um arquivo Phar teve seu CRC verificado.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

`true` se o arquivo teve seu CRC verificado, `false` caso contrário.

### Exemplos

Exemplo #1 Um exemplo de PharFileInfo::isCRCChecked()

    <?php
    try {
        $p = new Phar('/caminho/para/meu.phar', 0, 'meu.phar');
        $p['meuarquivo.txt'] = 'olá';
        $file = $p['meuarquivo.txt'];
        var_dump($file->isCRCChecked());
    } catch (Exception $e) {
        echo 'As operações de criação/modificação falharam em meu.phar: ', $e;
    }
    ?>

O exemplo acima produzirá:

    bool(true)

# PharFileInfo::isCompressed

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::isCompressed — Informa se a entrada está compactada

### Descrição

public function PharFileInfo::isCompressed(?int `$compression` = `null`): bool

Isso retorna se um arquivo está compactado dentro de um arquivo Phar com Gzip ou Bzip2.

### Parâmetros

`compression`

  Um dos seguintes: `Phar::GZ` ou `Phar::BZ2`, o padrão é qualquer compactação.

### Valor Retornado

`true` se o arquivo estiver compactado dentro do arquivo Phar, `false` caso contrário.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `compression` agora é anulável.

### Exemplos

Exemplo #1 Um exemplo de PharFileInfo::isCompressed()

    <?php
    try {
        $p = new Phar('/caminho/para/meu.phar', 0, 'meu.phar');
        $p['meuarquivo.txt'] = 'olá';
        $p['meuarquivo2.txt'] = 'olá';
        $p['meuarquivo2.txt']->setCompressedGZ();
        $file = $p['meuarquivo.txt'];
        $file2 = $p['meuarquivo2.txt'];
        var_dump($file->isCompressed());
        var_dump($file2->isCompressed());
    } catch (Exception $e) {
        echo 'Falha ao criar/modificar meu.phar: ', $e;
    }
    ?>

O exemplo acima produzirá:

    bool(false)
    bool(true)

### Veja Também

- PharFileInfo::getCompressedSize() - Retorna o tamanho real do arquivo (com compactação) dentro do arquivo Phar
- PharFileInfo::decompress() - Descompacta a entrada Phar atual dentro do phar
- PharFileInfo::compress() - Compacta a entrada Phar atual com zlib ou bzip2
- Phar::decompress() - Descompacta todo o arquivo Phar
- Phar::compress() - Compacta todo o arquivo Phar usando compactação Gzip ou Bzip2
- Phar::canCompress() - Retorna se a extensão phar suporta compactação usando zlib ou bzip2
- Phar::isCompressed() - Retorna Phar::GZ ou PHAR::BZ2 se todo o arquivo phar estiver compactado (.tar.gz/tar.bz e assim por diante)
- Phar::getSupportedCompression() - Retorna um array de algoritmos de compactação suportados
- Phar::decompressFiles() - Descompacta todos os arquivos no arquivo Phar atual
- Phar::compressFiles() - Compacta todos os arquivos no arquivo Phar atual

# PharFileInfo::setMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::setMetadata — Define metadados específicos de arquivo salvos com um arquivo

### Descrição

public function PharFileInfo::setMetadata(mixed `$metadata`): void

PharFileInfo::setMetadata() deve ser usado apenas para armazenar dados personalizados que não podem ser representados com informações existentes armazenadas em um arquivo. Metadados podem reduzir significativamente o desempenho do carregamento de um arquivo phar se os dados forem grandes ou se houver muitos arquivos contendo metadados. É importante observar que as permissões de arquivo são suportadas nativamente dentro de um phar; é possível defini-las com o método PharFileInfo::chmod(). Assim como acontece com todas as funcionalidades que modificam o conteúdo de um phar, a variável INI phar.readonly deve estar desativada para funcionar se o arquivo estiver dentro de um arquivo Phar. Arquivos dentro de arquivos PharData não têm essa restrição.

Alguns usos possíveis para metadados incluem a passagem de um usuário/grupo que deve ser definido quando um arquivo é extraído do PHAR para o disco. Outros usos podem incluir a especificação explícita de um tipo MIME a ser retornado. No entanto, quaisquer dados úteis que descrevam um arquivo, mas que não devam estar contidos nele, podem ser armazenados.

### Parâmetros

`metadata`

  Qualquer variável PHP contendo informações para armazenar junto com um arquivo

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Um exemplo de PharFileInfo::setMetadata()

    <?php
    // garantindo que o arquivo não existe
    @unlink('novophar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/novophar.phar', 0, 'novophar.phar');
        $p['arquivo.txt'] = 'olá';
        $p['arquivo.txt']->setMetadata(array('usuario' => 'igor', 'mime-type' => 'text/plain'));
        var_dump($p['arquivo.txt']->getMetaData());
    } catch (Exception $e) {
        echo 'Não foi possível criar/modificar o phar: ', $e;
    }
    ?>

O exemplo acima produzirá:

    array(2) {
      ["usuario"]=>
      string(4) "igor"
      ["mime-type"]=>
      string(10) "text/plain"
    }

### Veja Também

- PharFileInfo::hasMetadata() - Retorna os metadados da entrada
- PharFileInfo::getMetadata() - Retorna metadados específicos do arquivo salvos com um arquivo
- PharFileInfo::delMetadata() - Exclui os metadados da entrada
- Phar::setMetadata() - Define metadados do arquivo phar
- Phar::hasMetadata() - Informa se o phar tem metadados globais
- Phar::getMetadata() - Retorna metadados do arquivo phar

## Índice

- PharFileInfo::chmod — Define bits de permissão específicos do arquivo
- PharFileInfo::compress — Compacta a entrada Phar atual com zlib ou bzip2
- PharFileInfo::__construct — Constrói um objeto de entrada Phar
- PharFileInfo::decompress — Descompacta a entrada Phar atual dentro do phar
- PharFileInfo::delMetadata — Exclui os metadados da entrada
- PharFileInfo::__destruct — Destrói um objeto de entrada Phar
- PharFileInfo::getCRC32 — Retorna o código CRC32 ou lança uma exceção se o CRC não tiver sido verificado
- PharFileInfo::getCompressedSize — Retorna o tamanho real do arquivo (com compactação) dentro do arquivo Phar
- PharFileInfo::getContent — Obtém o conteúdo completo do arquivo de entrada
- PharFileInfo::getMetadata — Retorna metadados específicos do arquivo salvos com um arquivo
- PharFileInfo::getPharFlags — Retorna os sinalizadores de entrada do arquivo Phar
- PharFileInfo::hasMetadata — Retorna os metadados da entrada
- PharFileInfo::isCRCChecked — Informa se a entrada do arquivo teve seu CRC verificado
- PharFileInfo::isCompressed — Informa se a entrada está compactada
- PharFileInfo::setMetadata — Define metadados específicos de arquivo salvos com um arquivo

# A classe PharException

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

## Introdução

A classe PharException fornece uma classe de exceção específica para Phar para blocos try/catch.

## Resumo da classe

class PharException extends Exception {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
  - Tipos de Recurso
- Constantes predefinidas
- Usando Arquivos Phar
  - Usando Arquivos Phar: Introdução
  - Usando Arquivos Phar: o empacotador de fluxo phar
  - Usando Arquivos Phar: as classes Phar e PharData
- Criando Arquivos Phar
  - Criando Arquivos Phar: Introdução
- O que faz um phar ser um phar e não um tar ou um zip?
  - Ingredientes de todos os arquivos Phar, independentemente do formato do arquivo
  - Stub de arquivo Phar
  - Comparação direta de Phar, Tar e Zip
  - Phars baseados em Tar
  - Phars baseados em Zip
  - Formato de arquivo phar
  - Sinalizadores globais Phar em mapa de bits
  - Definição de entrada do arquivo de manifesto Phar
  - Formato de assinatura Phar
- Phar — A classe Phar
  - Phar::addEmptyDir — Adiciona um diretório vazio ao arquivo phar
  - Phar::addFile — Adiciona um arquivo do sistema de arquivos ao arquivo phar
  - Phar::addFromString — Adiciona um arquivo a partir de uma string ao arquivo phar
  - Phar::apiVersion — Retorna a versão da API
  - Phar::buildFromDirectory — Constrói um arquivo phar a partir dos arquivos dentro de um diretório
  - Phar::buildFromIterator — Constrói um arquivo phar a partir de um iterador
  - Phar::canCompress — Retorna se a extensão phar suporta compactação usando zlib ou bzip2
  - Phar::canWrite — Retorna se a extensão phar suporta a escrita e criação de phars
  - Phar::compress — Compacta todo o arquivo Phar usando compactação Gzip ou Bzip2
  - Phar::compressFiles — Compacta todos os arquivos no arquivo Phar atual
  - Phar::__construct — Constrói um objeto de arquivo Phar
  - Phar::convertToData — Converte um arquivo phar em um arquivo tar ou zip não executável
  - Phar::convertToExecutable — Converte um arquivo phar em outro formato de arquivo executável phar
  - Phar::copy — Copia um arquivo interno do arquivo phar para outro novo arquivo dentro do phar
  - Phar::count — Retorna o número de entradas (arquivos) no arquivo Phar
  - Phar::createDefaultStub — Cria um stup de formato específico de arquivo phar
  - Phar::decompress — Descompacta todo o arquivo Phar
  - Phar::decompressFiles — Descompacta todos os arquivos no arquivo Phar atual
  - Phar::delMetadata — Exclui os metadados globais do phar
  - Phar::delete — Exclui um arquivo dentro de um arquivo phar
  - Phar::__destruct — Destrói um objeto de arquivo Phar
  - Phar::extractTo — Extrai o conteúdo de um arquivo phar para um diretório
  - Phar::getAlias — Obtém o apelido para o Phar
  - Phar::getMetadata — Retorna metadados do arquivo phar
  - Phar::getModified — Informa se o phar foi modificado
  - Phar::getPath — Obtém o caminho real para o arquivo Phar no disco
  - Phar::getSignature — Retorna a assinatura MD5/SHA1/SHA256/SHA512/OpenSSL de um arquivo Phar
  - Phar::getStub — Retorna o carregador PHP ou o stub de inicialização de um arquivo Phar
  - Phar::getSupportedCompression — Retorna um array de algoritmos de compactação suportados
  - Phar::getSupportedSignatures — Retorna um array de tipos de assinatura suportados
  - Phar::getVersion — Retorna informações da versão do arquivo Phar
  - Phar::hasMetadata — Informa se o phar tem metadados globais
  - Phar::interceptFileFuncs — Instrui phar a interceptar fopen, file_get_contents, opendir e todas as funções relacionadas a stat
  - Phar::isBuffering — Usado para determinar se as operações de gravação Phar estão sendo armazenadas em buffer ou estão sendo liberadas diretamente no disco
  - Phar::isCompressed — Retorna Phar::GZ ou PHAR::BZ2 se todo o arquivo phar estiver compactado (.tar.gz/tar.bz e assim por diante)
  - Phar::isFileFormat — Informa se o arquivo phar é baseado no formato de arquivo tar/phar/zip dependendo do parâmetro
  - Phar::isValidPharFilename — Informa se o nome de arquivo fornecido é um nome de arquivo phar válido
  - Phar::isWritable — Informa se o arquivo phar pode ser modificado
  - Phar::loadPhar — Carrega qualquer arquivo phar com um apelido
  - Phar::mapPhar — Lê o arquivo atualmente em execução (um phar) e registra seu manifesto
  - Phar::mount — Monta um caminho externo ou arquivo em um local virtual dentro do arquivo phar
  - Phar::mungServer — Define uma lista de até 4 variáveis ​​$_SERVER que devem ser modificadas para execução
  - Phar::offsetExists — Determina se um arquivo existe no phar
  - Phar::offsetGet — Obtém um objeto PharFileInfo para um arquivo específico
  - Phar::offsetSet — Define o conteúdo de um arquivo interno para o de um arquivo externo
  - Phar::offsetUnset — Remove um arquivo de um phar
  - Phar::running — Retorna o caminho completo no disco ou a URL completa do arquivo Phar em execução no momento
  - Phar::setAlias — Define o apelido para o arquivo Phar
  - Phar::setDefaultStub — Usado para definir o carregador PHP ou o stub de bootstrap de um arquivo Phar para o carregador padrão
  - Phar::setMetadata — Define metadados do arquivo phar
  - Phar::setSignatureAlgorithm — Define o algoritmo de assinatura para um phar e o aplica
  - Phar::setStub — Usado para definir o carregador PHP ou o stub de inicialização de um arquivo Phar
  - Phar::startBuffering — Inicia o buffer das operações de gravação Phar, não modifica o objeto Phar no disco
  - Phar::stopBuffering — Interrompe o buffer de solicitações de gravação no arquivo Phar e salva as alterações no disco
  - Phar::unlinkArchive — Remove completamente um arquivo phar do disco e da memória
  - Phar::webPhar — Encaminha uma solicitação de um navegador da web para um arquivo interno dentro do arquivo phar
- PharData — A classe PharData
  - PharData::addEmptyDir — Adiciona um diretório vazio ao arquivo tar/zip
  - PharData::addFile — Adiciona um arquivo do sistema de arquivos ao arquivo tar/zip
  - PharData::addFromString — Adiciona um arquivo de uma string ao arquivo tar/zip
  - PharData::buildFromDirectory — Constrói um arquivo tar/zip a partir dos arquivos dentro de um diretório
  - PharData::buildFromIterator — Constrói um arquivo tar ou zip a partir de um iterador
  - PharData::compress — Compacta todo o arquivo tar/zip usando Gzip ou Bzip2
  - PharData::compressFiles — Compacta todos os arquivos no arquivo tar/zip atual
  - PharData::__construct — Constrói um objeto de arquivo tar ou zip não executável
  - PharData::convertToData — Converte um arquivo phar em um arquivo tar ou zip não executável
  - PharData::convertToExecutable — Converte um arquivo tar/zip não executável em um arquivo phar executável
  - PharData::copy — Copia um arquivo interno do arquivo tar/zip para outro arquivo novo dentro do mesmo arquivo
  - PharData::decompress — Descompacta todo o arquivo Phar
  - PharData::decompressFiles — Descompacta todos os arquivos no arquivo zip atual
  - PharData::delMetadata — Exclui os metadados globais de um arquivo zip
  - PharData::delete — Exclui um arquivo dentro de um arquivo tar/zip
  - PharData::__destruct — Destrói um objeto de arquivo tar ou zip não executável
  - PharData::extractTo — Extrai o conteúdo de um arquivo tar/zip para um diretório
  - PharData::isWritable — Informa se o arquivo tar/zip pode ser modificado
  - PharData::offsetSet — Define o conteúdo de um arquivo dentro do tar/zip para o de um arquivo externo ou string
  - PharData::offsetUnset — Remove um arquivo de um arquivo tar/zip
  - PharData::setAlias — Função fictícia (Phar::setAlias ​​não é válido para PharData)
  - PharData::setDefaultStub — Função fictícia (Phar::setDefaultStub não é válido para PharData)
  - PharData::setMetadata — Define metadados do arquivo phar
  - PharData::setSignatureAlgorithm — Define o algoritmo de assinatura para um phar e o aplica
  - PharData::setStub — Função fictícia (Phar::setStub não é válido para PharData)
- PharFileInfo — A classe PharFileInfo
  - PharFileInfo::chmod — Define bits de permissão específicos do arquivo
  - PharFileInfo::compress — Compacta a entrada Phar atual com zlib ou bzip2
  - PharFileInfo::__construct — Constrói um objeto de entrada Phar
  - PharFileInfo::decompress — Descompacta a entrada Phar atual dentro do phar
  - PharFileInfo::delMetadata — Exclui os metadados da entrada
  - PharFileInfo::__destruct — Destrói um objeto de entrada Phar
  - PharFileInfo::getCRC32 — Retorna o código CRC32 ou lança uma exceção se o CRC não tiver sido verificado
  - PharFileInfo::getCompressedSize — Retorna o tamanho real do arquivo (com compactação) dentro do arquivo Phar
  - PharFileInfo::getContent — Obtém o conteúdo completo do arquivo de entrada
  - PharFileInfo::getMetadata — Retorna metadados específicos do arquivo salvos com um arquivo
  - PharFileInfo::getPharFlags — Retorna os sinalizadores de entrada do arquivo Phar
  - PharFileInfo::hasMetadata — Retorna os metadados da entrada
  - PharFileInfo::isCRCChecked — Informa se a entrada do arquivo teve seu CRC verificado
  - PharFileInfo::isCompressed — Informa se a entrada está compactada
  - PharFileInfo::setMetadata — Define metadados específicos de arquivo salvos com um arquivo
- PharException — A classe PharException

# Arquivamento Rar

# Introdução

Rar é um arquivador poderoso e eficaz criado por Eugene Roshal. Esta extensão dá a possibilidade de ler arquivos Rar, mas não suporta a gravação de arquivos Rar, porque isso não é suportado pela biblioteca UnRar e é diretamente proibido por sua licença.

Mais informações sobre Rar e UnRar pode ser encontrado em » http://www.rarlabs.com/.

# Instalação/Configuração

## Índice

- Instalação
- Tipos de Recurso

## Instalação

Rar está atualmente disponível através do PECL » https://pecl.php.net/package/rar.

Além disso, você pode usar o instalador PECL para instalar a extensão Rar, usando o seguinte comando: pecl -v install rar.

Você sempre pode baixar o pacote tar.gz e instalar o Rar manualmente:

Exemplo #1 Instalação Rar

    gunzip rar-xxx.tgz
    tar -xvf rar-xxx.tar
    cd rar-xxx
    phpize
    ./configure && make && make install

Os usuários do Windows ativarão o php_rar.dll dentro do php.ini para usar essas funções.

## Tipos de Recurso

Esta extensão registra três classes internas: as representações de arquivo retornadas por rar_open() – RarArchive, as representações de entrada retornadas por rar_list() e rar_entry_get() – RarEntry e o tipo de exceção RarException.

Esta extensão também registra um recurso de fluxo, denominado "rar" e um empacotador de URL denominado "rar wrapper" e registrado sob o prefixo "rar".

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`RAR_HOST_MSDOS` (int)
  Use `RarEntry::HOST_MSDOS` no lugar.
`RAR_HOST_OS2` (int)
  Use `RarEntry::HOST_OS2` no lugar.
`RAR_HOST_WIN32` (int)
  Use `RarEntry::HOST_WIN32` no lugar.
`RAR_HOST_UNIX` (int)
  Use `RarEntry::HOST_UNIX` no lugar.
`RAR_HOST_BEOS` (int)
  Use `RarEntry::HOST_BEOS` no lugar.

# Exemplos

Veja também os exemplos do empacotador `rar://`.

Exemplo #1 Descompressão instantânea

    <?php

    if (!array_key_exists("i", $_GET) || !is_numeric($_GET["i"]))
        die("Índice não especificado ou não numérico");
    $index = (int) $_GET["i"];

    $arch = RarArchive::open("example.rar");
    if ($arch === FALSE)
        die("Cannot open example.rar");

    $entries = $arch->getEntries();
    if ($entries === FALSE)
        die("Cannot retrieve entries");

    if (!array_key_exists($index, $entries))
        die("No such index: $index");

    $orfilename = $entries[$index]->getName(); //UTF-8 encoded

    $filesize = $entries[$index]->getUnpackedSize();

    /* HTTP_IF_MODIFIED_SINCE pode ser verificado aqui e comparado com
     * $entries[$index]->getFileTime(). Também pode ser enviado
     * um cabeçalho "Last modified"*/

    $fp = $entries[$index]->getStream();
    if ($fp === FALSE)
        die("Não foi possível abrir arquivo com índice $index dentro do arquivo.");

    $arch->close(); // não é mais necessário; fluxo é independente

    function detectUserAgent() {
        if (!array_key_exists('HTTP_USER_AGENT', $_SERVER))
            return "Other";

        $uas = $_SERVER['HTTP_USER_AGENT'];
        if (preg_match("@Opera/@", $uas))
            return "Opera";
        if (preg_match("@Firefox/@", $uas))
            return "Firefox";
        if (preg_match("@Chrome/@", $uas))
            return "Chrome";
        if (preg_match("@MSIE ([0-9.]+);@", $uas, $matches)) {
            if (((float) $matches[1]) >= 7.0)
                return "IE";
        }

        return "Outro";
    }

    /*
     * Temos 3 opções:
     * - Para FF e Opera, que suportam RFC 2231, use esse formato.
     * - Para IE e Chrome, use attwithfnrawpctenclong
     *   (http://greenbytes.de/tech/tc2231/#attwithfnrawpctenclong)
     * - Para os demais, converta para ISO-8859-1, se possível
     */
    $formatRFC2231 = 'Content-Disposition: attachment; filename*=UTF-8\'\'%s';
    $formatDef = 'Content-Disposition: attachment; filename="%s"';

    switch (detectUserAgent()) {
        case "Opera":
        case "Firefox":
            $orfilename = rawurlencode($orfilename);
            $format = $formatRFC2231;
            break;

        case "IE":
        case "Chrome":
            $orfilename = rawurlencode($orfilename);
            $format = $formatDef;
            break;
        default:
            if (function_exists('iconv'))
                $orfilename =
                    @iconv("UTF-8", "ISO-8859-1//TRANSLIT", $orfilename);
            $format = $formatDef;
    }

    header(sprintf($format, $orfilename));
    // não é possível enviar mensagens de erro a partir de agora (cabeçalhos já enviados)

    // substitua pelo tipo de conteúdo real, talvez inferindo da extensão do arquivo
    $contentType = "application/octet-stream";
    header("Content-Type: $contentType");

    header("Content-Transfer-Encoding: binary");

    header("Content-Length: $filesize");

    if ($_SERVER['REQUEST_METHOD'] == "HEAD")
        die();

    while (!feof($fp)) {
        $s = @fread($fp, 8192);
        if ($s === false)
            break; // inútil enviar mensagens de erro

        echo $s;
    }
    ?>

Este exemplo abre um arquivo RAR e apresenta o arquivo solicitado dentro do arquivo RAR para download no cliente.

Exemplo #2 Exemplo de extração de sistema de arquivos com extensão RAR

    <?php

    $rar_file = rar_open('example.rar') or die("Não foi possível abrir arquivo Rar");

    $entries = rar_list($rar_file);

    foreach ($entries as $entry) {
        echo 'Filename: ' . $entry->getName() . "\n";
        echo 'Packed size: ' . $entry->getPackedSize() . "\n";
        echo 'Unpacked size: ' . $entry->getUnpackedSize() . "\n";

        $entry->extract('/dir/extract/to/');
    }

    rar_close($rar_file);

    ?>

Este exemplo abre um arquivo RAR e extrai cada entrada para o diretório especificado.

# Funções de Rar

# rar_wrapper_cache_stats

(PECL rar >= 3.0.0)

rar_wrapper_cache_stats — Acertos e erros de cache para o empacotador de URL

### Descrição

function rar_wrapper_cache_stats(): string

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

## Índice

- rar_wrapper_cache_stats — Acertos e erros de cache para o empacotador de URL

# A classe RarArchive

(PECL rar >= 2.0.0)

## Introdução

Esta classe representa um arquivo RAR, que pode ser formado por vários volumes (partes) e que contém uma série de entradas RAR (ou seja, arquivos, diretórios e outros objetos especiais, como links simbólicos).

Objetos desta classe podem ser percorridos, gerando as entradas armazenadas no respectivo arquivo RAR. Essas entradas também podem ser obtidas através de RarArchive::getEntry() e RarArchive::getEntries().

## Resumo da classe

final class RarArchive implements Traversable {
/* Métodos */
public function close(): bool
public function getComment(): string
public function getEntries(): array|false
public function getEntry(string `$entryname`): RarEntry|false
public function isBroken(): bool
public function isSolid(): bool
public static function open(string `$filename`, string `$password` = NULL, callable `$volume_callback` = NULL): RarArchive|false
public function setAllowBroken(bool `$allow_broken`): bool
public function __toString(): string
}

# RarArchive::close

# rar_close

(PECL rar >= 2.0.0)

RarArchive::close -- rar_close — Fecha o arquivo RAR e libera todos os recursos

### Descrição

Estilo orientado a objetos (method):

public function RarArchive::close(): bool

Estilo procedural:

function rar_close(RarArchive `$rarfile`): bool

Fecha o arquivo RAR e libera todos os recursos alocados.

### Parâmetros

`rarfile`
  Um objeto RarArchive, aberto com rar_open().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL rar 2.0.0 | As entradas RAR retornadas por RarArchive::getEntry() e RarArchive::getEntries() agora são invalidadas ao chamar este método. Isso significa que todos os métodos de instância chamados para tais entradas não têm garantia de sucesso.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php
    $rar_arch = RarArchive::open('latest_winrar.rar');
    echo $rar_arch."\n";
    $rar_arch->close();
    echo $rar_arch."\n";
    ?>

O exemplo acima produzirá algo semelhante a:

    RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar"
    RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" (closed)

Exemplo #2 Estilo procedural

    <?php
    $rar_arch = rar_open('latest_winrar.rar');
    echo $rar_arch."\n";
    rar_close($rar_arch);
    echo $rar_arch."\n";
    ?>

# RarArchive::getComment

# rar_comment_get

(PECL rar >= 2.0.0)

RarArchive::getComment -- rar_comment_get — Obtém o texto de comentário do arquivo RAR

### Descrição

Estilo orientado a objetos (method):

public function RarArchive::getComment(): string

Estilo procedural:

function rar_comment_get(RarArchive `$rarfile`): string

Obtém o comentário (global) armazenado no arquivo RAR. Pode ter até 64 KiB de comprimento.

> Nota: Esta extensão não oferece suporte a comentários no nível de entrada.

### Parâmetros

`rarfile`
  Um objeto RarArchive, aberto com rar_open().

### Valor Retornado

Retorna o comentário ou `null` se não houver nenhum.

> Nota: Atualmente, o RAR não oferece suporte para comentários Unicode. A codificação do resultado desta função não está especificada, mas provavelmente será Windows-1252.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php
    $rar_arch = RarArchive::open('commented.rar');
    echo $rar_arch->getComment();
    ?>

O exemplo acima produzirá algo semelhante a:

    Este é o comentário do arquivo commented.rar.

Exemplo #2 Estilo procedural

    <?php
    $rar_arch = rar_open('commented.rar');
    echo rar_comment_get($rar_arch);
    ?>

# RarArchive::getEntries

# rar_list

(PECL rar >= 2.0.0)

RarArchive::getEntries -- rar_list — Obtém a lista completa de entradas do arquivo RAR

### Descrição

Estilo orientado a objetos (method):

public function RarArchive::getEntries(): array|false

Estilo procedural:

function rar_list(RarArchive `$rarfile`): array|false

Obtém a lista de entradas (arquivos e diretórios) do arquivo RAR.

> Nota: Se o arquivo tiver entradas com o mesmo nome, este método, juntamente com a iteração RarArchive `foreach` e o acesso tipo array com índices numéricos, são os únicos a acessar todas as entradas (ou seja, RarArchive::getEntry() e o empacotador `rar://` são insuficientes).

### Parâmetros

`rarfile`
  Um objeto RarArchive, aberto com rar_open().

### Valor Retornado

rar_list() retorna um array de objetos RarEntry ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL rar 3.0.0 | O suporte para arquivos RAR com nomes de entrada repetidos não apresenta mais defeitos.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php
    $rar_arch = RarArchive::open('solid.rar');
    if ($rar_arch === FALSE)
        die("Não foi possível abrir o arquivo RAR.");

    $rar_entries = $rar_arch->getEntries();
    if ($rar_entries === FALSE)
        die("Não foi possível recuperar entradas.");

    echo "Encontradas " . count($rar_entries) . " entradas.\n";

    foreach ($rar_entries as $e) {
        echo $e;
        echo "\n";
    }
    $rar_arch->close();
    ?>

O exemplo acima produzirá algo semelhante a:

    Encontradas 2 entradas.
    RarEntry for file "tese.txt" (23b93a7a)
    RarEntry for file "unrardll.txt" (2ed64b6e)

Exemplo #2 Estilo procedural

    <?php
    $rar_arch = rar_open('solid.rar');
    if ($rar_arch === FALSE)
        die("Não foi possível abrir o arquivo RAR.");

    $rar_entries = rar_list($rar_arch);
    if ($rar_entries === FALSE)
        die("Não foi possível recuperar entradas.");

    echo "Encontradas " . count($rar_entries) . " entradas.\n";

    foreach ($rar_entries as $e) {
        echo $e;
        echo "\n";
    }
    rar_close($rar_arch);
    ?>

### Veja Também

- RarArchive::getEntry() - Obtém o objeto de entrada do arquivo RAR
- Empacotador `rar://`

# RarArchive::getEntry

# rar_entry_get

(PECL rar >= 2.0.0)

RarArchive::getEntry -- rar_entry_get — Obtém o objeto de entrada do arquivo RAR

### Descrição

Estilo orientado a objetos (method):

public function RarArchive::getEntry(string `$entryname`): RarEntry|false

Estilo procedural:

function rar_entry_get(RarArchive `$rarfile`, string `$entryname`): RarEntry|false

Obtém o objeto de entrada (arquivo ou diretório) do arquivo RAR.

> Nota: Você também pode obter objetos de entrada usando RarArchive::getEntries(). Observe que um arquivo RAR pode ter múltiplas entradas com o mesmo nome; este método recuperará apenas o primeiro.

### Parâmetros

`rarfile`
  Um objeto RarArchive, aberto com rar_open().
`entryname`
  Caminho para a entrada no arquivo RAR.

  > Nota: O caminho deve ser o mesmo retornado por RarEntry::getName().

### Valor Retornado

Retorna o objeto RarEntry correspondente ou `false` em caso de falha.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php
    $rar_arch = RarArchive::open('solid.rar');
    if ($rar_arch === FALSE)
        die("Não foi possível abrir o arquivo RAR.");
    $rar_entry = $rar_arch->getEntry('tese.txt');
    if ($rar_entry === FALSE)
        die("Não foi possível recupera esta entrada");
    echo get_class($rar_entry)."\n";
    echo $rar_entry;
    $rar_arch->close();
    ?>

O exemplo acima produzirá algo semelhante a:

    RarEntry
    RarEntry for file "tese.txt" (23b93a7a)

Exemplo #2 Estilo procedural

    <?php
    $rar_arch = rar_open('solid.rar');
    if ($rar_arch === FALSE)
        die("Não foi possível abrir o arquivo RAR.");
    $rar_entry = rar_entry_get($rar_arch, 'tese.txt');
    if ($rar_entry === FALSE)
        die("Não foi possível recupera esta entrada");
    echo get_class($rar_entry)."\n";
    echo $rar_entry;
    rar_close($rar_arch);
    ?>

### Veja Também

- RarArchive::getEntries() - Obtém a lista completa de entradas do arquivo RAR
- Empacotador `rar://`

# RarArchive::isBroken

# rar_broken_is

(PECL rar >= 3.0.0)

RarArchive::isBroken -- rar_broken_is — Testa se um arquivo está quebrado (incompleto)

### Descrição

Estilo orientado a objetos (method):

public function RarArchive::isBroken(): bool

Estilo procedural:

function rar_broken_is(RarArchive `$rarfile`): bool

Esta função determina se um arquivo está incompleto, ou seja, se um volume está faltando ou se um volume está truncado.

### Parâmetros

`rarfile`
  Um objeto RarArchive, aberto com rar_open().

### Valor Retornado

Retorna `true` se o arquivo estiver quebrado, `false` caso contrário. Esta função também pode retornar `false` se o arquivo passado já tiver sido fechado. A única maneira de diferenciar os dois casos é habilitar exceções com RarException::setUsingExceptions(); entretanto, isso deve ser desnecessário, pois um programa não deve operar em arquivos fechados.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php
    function retnull() { return null; }
    $file = dirname(__FILE__) . "/multi_broken.part1.rar";
    /* O terceiro argumento é usado para omitir o aviso */
    $arch = RarArchive::open($file, null, 'retnull');
    var_dump($arch->isBroken());
    ?>

O exemplo acima produzirá algo semelhante a:

    bool(true)

Exemplo #2 Estilo procedural

    <?php
    function retnull() { return null; }
    $file = dirname(__FILE__) . "/multi_broken.part1.rar";
    /* O terceiro argumento é usado para omitir o aviso */
    $arch = rar_open($file, null, 'retnull');
    var_dump(rar_broken_is($arch));
    ?>

### Veja Também

- RarArchive::setAllowBroken() - Se é permitido abrir arquivos quebrados

# RarArchive::isSolid

# rar_solid_is

(PECL rar >= 2.0.0)

RarArchive::isSolid -- rar_solid_is — Verifica se o arquivo RAR é sólido

### Descrição

Estilo orientado a objetos (method):

public function RarArchive::isSolid(): bool

Estilo procedural:

function rar_solid_is(RarArchive `$rarfile`): bool

Verifique se o arquivo RAR é sólido. A extração de arquivos individuais é mais lenta em arquivos sólidos.

### Parâmetros

`rarfile`
  Um objeto RarArchive, aberto com rar_open().

### Valor Retornado

Retorna `true` se o arquivo for sólido, `false` caso contrário.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php
    $arch1 = RarArchive::open("store_method.rar");
    $arch2 = RarArchive::open("solid.rar");
    echo "$arch1: " . ($arch1->isSolid()?'yes':'no') ."\n";
    echo "$arch2: " . ($arch2->isSolid()?'yes':'no') . "\n";
    ?>

O exemplo acima produzirá algo semelhante a:

    RAR Archive "C:\php_rar\trunk\tests\store_method.rar": no
    RAR Archive "C:\php_rar\trunk\tests\solid.rar": yes

Exemplo #2 Estilo procedural

    <?php
    $arch1 = rar_open("store_method.rar");
    $arch2 = rar_open("solid.rar");
    echo "$arch1: " . (rar_solid_is($arch1)?'yes':'no') ."\n";
    echo "$arch2: " . (rar_solid_is($arch2)?'yes':'no') . "\n";
    ?>

# RarArchive::open

# rar_open

(PECL rar >= 2.0.0)

RarArchive::open -- rar_open — Abre arquivo RAR

### Descrição

Estilo orientado a objetos (method):

public static function RarArchive::open(string `$filename`, string `$password` = NULL, callable `$volume_callback` = NULL): RarArchive|false

Estilo procedural:

function rar_open(string `$filename`, string `$password` = NULL, callable `$volume_callback` = NULL): RarArchive|false

Abre o arquivo RAR especificado e retorna a instância RarArchive que o representa.

> Nota: Se estiver abrindo um arquivo multivolume, o caminho do primeiro volume deverá ser passado como o primeiro parâmetro. Caso contrário, nem todos os arquivos serão mostrados. Isso ocorre intencionalmente.

### Parâmetros

`filename`
  Caminho para o arquivo Rar.
`password`
  Uma senha simples, se necessária para descriptografar os cabeçalhos. Ele também será usado por padrão se forem encontrados arquivos criptografados. Observe que os arquivos podem ter senhas diferentes em relação aos cabeçalhos e entre eles.
`volume_callback`
  Uma função que recebe um parâmetro – o caminho do volume que não foi encontrado – e retorna uma string com o caminho correto para tal volume ou `null` se tal volume não existir ou não for conhecido. O programador deve garantir que a função passada não cause loops, pois esta função é chamada repetidamente se o caminho retornado em uma chamada anterior não corresponder ao volume necessário. A especificação deste parâmetro omite o aviso que seria emitido sempre que um volume não fosse encontrado; uma implementação que retorna apenas `null` pode, portanto, ser usado para simplesmente omitir tais avisos.

Aviso

Antes da versão 2.0.0, esta função não manipulava caminhos relativos corretamente. Use realpath() como solução alternativa.

### Valor Retornado

Retorna a instância RarArchive solicitada ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL rar 3.0.0 | `volume_callback` foi adicionado.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php
    $rar_arch = RarArchive::open('encrypted_headers.rar', 'samplepassword');
    if ($rar_arch === FALSE)
        die("Falha ao abrir o arquivo");

    $entries = $rar_arch->getEntries();
    if ($entries === FALSE)
        die("Falha ao buscar as entradas");

    echo "Encontrados " . count($entries) . " arquivos.\n";

    if (empty($entries))
        die("Nenhuma entrada válida encontrada.");

    $stream = reset($entries)->getStream();
    if ($stream === FALSE)
        die("Falha ao abrir o primeiro arquivo");

    $rar_arch->close();

    echo "Conteúdo do primeiro arquivo é o seguinte:\n";
    echo stream_get_contents($stream);

    fclose($stream);
    ?>

O exemplo acima produzirá algo semelhante a:

    Encontrados 2 arquivos.
    Conteúdo do primeiro arquivo é o seguinte:
    Conteúdo do primeiro arquivo criptografado.

Exemplo #2 Estilo procedural

    <?php
    $rar_arch = rar_open('encrypted_headers.rar', 'samplepassword');
    if ($rar_arch === FALSE)
        die("Falha ao abrir o arquivo");

    $entries = rar_list($rar_arch);
    if ($entries === FALSE)
        die("Falha ao buscar as entradas");

    echo "Encontrados " . count($entries) . " files.\n";

    if (empty($entries))
        die("Nenhuma entrada válida encontrada.");

    $stream = reset($entries)->getStream();
    if ($stream === FALSE)
        die("Falha ao abrir o primeiro arquivo");

    rar_close($rar_arch);

    echo "Conteúdo do primeiro arquivo é o seguinte:\n";
    echo stream_get_contents($stream);

    fclose($stream);
    ?>

Exemplo #3 Retorno de chamada de volume

    <?php
    /* Neste exemplo, há um volume chamado multi_broken.part1.rar
     * cujo próximo volume é denominado multi.part2.rar */
    function resolve($vol) {
        if (preg_match('/_broken/', $vol))
            return str_replace('_broken', '', $vol);
        else
            return null;
    }
    $rar_file1 = rar_open(dirname(__FILE__).'/multi_broken.part1.rar', null, 'resolve');
    $entry = $rar_file1->getEntry('file2.txt');
    $entry->extract(null, dirname(__FILE__) . "/temp_file2.txt");
    ?>

### Veja Também

- Empacotador `rar://`

# RarArchive::setAllowBroken

(PECL rar >= 3.0.0)

RarArchive::setAllowBroken — Se é permitido abrir arquivos quebrados

### Descrição

Estilo orientado a objetos (method):

public function RarArchive::setAllowBroken(bool `$allow_broken`): bool

Estilo procedural:

function rar_allow_broken_set(RarArchive `$rarfile`, bool `$allow_broken`): bool

Este método define se os arquivos quebrados podem ser lidos ou se todas as operações que tentam extrair as entradas do arquivo falharão. Arquivos quebrados são arquivos para os quais nenhum erro é detectado quando o arquivo é aberto, mas ocorre um erro ao ler as entradas.

### Parâmetros

`rarfile`
  Um objeto RarArchive, aberto com rar_open().
`allow_broken`
  Se deve permitir a leitura de arquivos quebrados (`true`) ou não (`false`).

### Valor Retornado

Retorna `true` ou `false` em caso de falha. Só falhará se o arquivo já tiver sido fechado.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php
    function retnull() { return null; }
    $file = dirname(__FILE__) . "/multi_broken.part1.rar";
    /* O terceiro argumento omite a mensagem "volume not found" */
    $a = RarArchive::open($file, null, 'retnull');
    $a->setAllowBroken(true);
    foreach ($a->getEntries() as $e) {
        echo "$e\n";
    }
    var_dump(count($a));
    ?>

O exemplo acima produzirá algo semelhante a:

    RarEntry for file "file1.txt" (52b28202)
    int(1)

Exemplo #2 Estilo procedural

    <?php
    function retnull() { return null; }
    $file = dirname(__FILE__) . "/multi_broken.part1.rar";
    /* O terceiro argumento omite a mensagem "volume not found" */
    $a = rar_open($file, null, 'retnull');
    rar_allow_broken_set($a, true);
    foreach (rar_list($a) as $e) {
        echo "$e\n";
    }
    var_dump(count($a));
    ?>

### Veja Também

- RarArchive::isBroken() - Testa se um arquivo está quebrado (incompleto)

# RarArchive::__toString

(PECL rar >= 2.0.0)

RarArchive::__toString — Obtém representação de texto

### Descrição

public function RarArchive::__toString(): string

Fornece uma representação de string para este objeto RarArchive. Atualmente mostra o nome completo do caminho do volume de arquivo que foi aberto e se o recurso é válido ou já foi fechado através de uma chamada para RarArchive::close().

Este método pode ser utilizado apenas para fins de depuração, pois não há garantias sobre quais informações o resultado contém ou como ele é formatado.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Uma representação textual deste objeto RarArchive. O conteúdo desta representação não é especificado.

### Exemplos

Exemplo #1 Exemplo de RarArchive::__toString()

    <?php
    $rar_arch = RarArchive::open('latest_winrar.rar');
    echo $rar_arch."\n";
    $rar_arch->close();
    echo $rar_arch."\n";
    ?>

O exemplo acima produzirá algo semelhante a:

    RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar"
    RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" (closed)

## Índice

- RarArchive::close — Fecha o arquivo RAR e libera todos os recursos
- RarArchive::getComment — Obtém o texto de comentário do arquivo RAR
- RarArchive::getEntries — Obtém a lista completa de entradas do arquivo RAR
- RarArchive::getEntry — Obtém o objeto de entrada do arquivo RAR
- RarArchive::isBroken — Testa se um arquivo está quebrado (incompleto)
- RarArchive::isSolid — Verifica se o arquivo RAR é sólido
- RarArchive::open — Abre arquivo RAR
- RarArchive::setAllowBroken — Se é permitido abrir arquivos quebrados
- RarArchive::__toString — Obtém representação de texto

# A classe RarEntry

(PECL rar >= 0.1)

## Introdução

Uma entrada RAR, representando um diretório ou arquivo compactado dentro de um arquivo RAR.

## Resumo da classe

final class RarEntry {
/* Constantes */
const int HOST_MSDOS = 0;
const int HOST_OS2 = 1;
const int HOST_WIN32 = 2;
const int HOST_UNIX = 3;
const int HOST_MACOS = 4;
const int HOST_BEOS = 5;
const int ATTRIBUTE_WIN_READONLY = 1;
const int ATTRIBUTE_WIN_HIDDEN = 2;
const int ATTRIBUTE_WIN_SYSTEM = 4;
const int ATTRIBUTE_WIN_DIRECTORY = 16;
const int ATTRIBUTE_WIN_ARCHIVE = 32;
const int ATTRIBUTE_WIN_DEVICE = 64;
const int ATTRIBUTE_WIN_NORMAL = 128;
const int ATTRIBUTE_WIN_TEMPORARY = 256;
const int ATTRIBUTE_WIN_SPARSE_FILE = 512;
const int ATTRIBUTE_WIN_REPARSE_POINT = 1024;
const int ATTRIBUTE_WIN_COMPRESSED = 2048;
const int ATTRIBUTE_WIN_OFFLINE = 4096;
const int ATTRIBUTE_WIN_NOT_CONTENT_INDEXED = 8192;
const int ATTRIBUTE_WIN_ENCRYPTED = 16384;
const int ATTRIBUTE_WIN_VIRTUAL = 65536;
const int ATTRIBUTE_UNIX_WORLD_EXECUTE = 1;
const int ATTRIBUTE_UNIX_WORLD_WRITE = 2;
const int ATTRIBUTE_UNIX_WORLD_READ = 4;
const int ATTRIBUTE_UNIX_GROUP_EXECUTE = 8;
const int ATTRIBUTE_UNIX_GROUP_WRITE = 16;
const int ATTRIBUTE_UNIX_GROUP_READ = 32;
const int ATTRIBUTE_UNIX_OWNER_EXECUTE = 64;
const int ATTRIBUTE_UNIX_OWNER_WRITE = 128;
const int ATTRIBUTE_UNIX_OWNER_READ = 256;
const int ATTRIBUTE_UNIX_STICKY = 512;
const int ATTRIBUTE_UNIX_SETGID = 1024;
const int ATTRIBUTE_UNIX_SETUID = 2048;
const int ATTRIBUTE_UNIX_FINAL_QUARTET = 61440;
const int ATTRIBUTE_UNIX_FIFO = 4096;
const int ATTRIBUTE_UNIX_CHAR_DEV = 8192;
const int ATTRIBUTE_UNIX_DIRECTORY = 16384;
const int ATTRIBUTE_UNIX_BLOCK_DEV = 24576;
const int ATTRIBUTE_UNIX_REGULAR_FILE = 32768;
const int ATTRIBUTE_UNIX_SYM_LINK = 40960;
const int ATTRIBUTE_UNIX_SOCKET = 49152;
/* Métodos */
public function extract(
string `$dir`,
string `$filepath` = "",
string `$password` = NULL,
bool `$extended_data` = `false`
): bool
public function getAttr(): int
public function getCrc(): string
public function getFileTime(): string
public function getHostOs(): int
public function getMethod(): int
public function getName(): string
public function getPackedSize(): int
public function getStream(string `$password` = ?): resource|false
public function getUnpackedSize(): int
public function getVersion(): int
public function isDirectory(): bool
public function isEncrypted(): bool
public function __toString(): string
}

## Constantes predefinidas

`RarEntry::HOST_MSDOS`
  Se o valor de retorno de RarEntry::getHostOs() for igual a esta constante, o MS-DOS foi usado para adicionar esta entrada. Use em vez de `RAR_HOST_MSDOS`.
`RarEntry::HOST_OS2`
  Se o valor de retorno de RarEntry::getHostOs() for igual a esta constante, o OS/2 foi utilizado para adicionar esta entrada. Destinado a substituir `RAR_HOST_OS2`.
`RarEntry::HOST_WIN32`
  Se o valor de retorno de RarEntry::getHostOs() for igual a essa constante, o Microsoft Windows foi usado para adicionar essa entrada. Destinado a substituir `RAR_HOST_WIN32`.
`RarEntry::HOST_UNIX`
  Se o valor de retorno de RarEntry::getHostOs() for igual a esta constante, um sistema operacional UNIX não especificado foi usado para adicionar esta entrada. Destinado a substituir `RAR_HOST_UNIX`.
`RarEntry::HOST_MACOS`
  Se o valor de retorno de RarEntry::getHostOs() for igual a esta constante, o Mac OS foi usado para adicionar esta entrada.
`RarEntry::HOST_BEOS`
  Se o valor de retorno de RarEntry::getHostOs() for igual a esta constante, o BeOS foi usado para adicionar esta entrada. Destinado a substituir `RAR_HOST_BEOS`.
`RarEntry::ATTRIBUTE_WIN_READONLY`
  Bit que representa uma entrada do Windows com um atributo somente leitura. Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é o Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_HIDDEN`
  Bit que representa uma entrada do Windows com um atributo oculto. Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é o Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_SYSTEM`
  Bit que representa uma entrada do Windows com um atributo oculto. Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é o Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_DIRECTORY`
  Bit que representa uma entrada do Windows com um atributo de diretório (a entrada é um diretório). Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é o Microsoft Windows. Veja também RarEntry::isDirectory(), que também funciona com entradas que não foram adicionadas no WinRAR.
`RarEntry::ATTRIBUTE_WIN_ARCHIVE`
  Bit que representa uma entrada do Windows com um atributo de arquivo. Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é o Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_DEVICE`
  Bit que representa uma entrada do Windows com um atributo de dispositivo. Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é o Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_NORMAL`
  Bit que representa uma entrada do Windows com um atributo de arquivo normal (a entrada NÃO é um diretório). Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é o Microsoft Windows. Veja também RarEntry::isDirectory(), que também funciona com entradas que não foram adicionadas no WinRAR.
`RarEntry::ATTRIBUTE_WIN_TEMPORARY`
  Bit que representa uma entrada do Windows com um atributo temporário. Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é o Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_SPARSE_FILE`
  Bit que representa uma entrada do Windows com um atributo de arquivo esparso (o arquivo é um arquivo esparso NTFS). Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é o Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_REPARSE_POINT`
  Bit que representa uma entrada do Windows com um atributo de ponto de nova análise (a entrada é um ponto de nova análise NTFS, por exemplo, uma junção de diretório ou um sistema de arquivos de montagem). Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é o Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_COMPRESSED`
  Bit que representa uma entrada do Windows com um atributo compactado (somente NTFS). Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é o Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_OFFLINE`
  Bit que representa uma entrada do Windows com um atributo offline (a entrada está offline e não acessível). Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é o Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_NOT_CONTENT_INDEXED`
  Bit que representa uma entrada do Windows com um atributo não indexado por conteúdo (a entrada deve ser indexada). Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é o Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_ENCRYPTED`
  Bit que representa uma entrada do Windows com um atributo criptografado (somente NTFS). Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é o Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_VIRTUAL`
  Bit que representa uma entrada do Windows com um atributo virtual. Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é o Microsoft Windows.
`RarEntry::ATTRIBUTE_UNIX_WORLD_EXECUTE`
  Bit que representa uma entrada UNIX que é executável mundialmente. Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é UNIX.
`RarEntry::ATTRIBUTE_UNIX_WORLD_WRITE`
  Bit que representa uma entrada UNIX que pode ser escrita mundialmente. Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é UNIX.
`RarEntry::ATTRIBUTE_UNIX_WORLD_READ`
  Bit que representa uma entrada UNIX legível mundialmente. Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é UNIX.
`RarEntry::ATTRIBUTE_UNIX_GROUP_EXECUTE`
  Bit que representa uma entrada UNIX executável em grupo. Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é UNIX.
`RarEntry::ATTRIBUTE_UNIX_GROUP_WRITE`
  Bit que representa uma entrada UNIX que pode ser escrita em grupo. Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é UNIX.
`RarEntry::ATTRIBUTE_UNIX_GROUP_READ`
  Bit que representa uma entrada UNIX legível em grupo. Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é UNIX.
`RarEntry::ATTRIBUTE_UNIX_OWNER_EXECUTE`
  Bit que representa uma entrada UNIX executável pelo proprietário. Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é UNIX.
`RarEntry::ATTRIBUTE_UNIX_OWNER_WRITE`
  Bit que representa uma entrada UNIX que pode ser escrita pelo proprietário. Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é UNIX.
`RarEntry::ATTRIBUTE_UNIX_OWNER_READ`
  Bit que representa uma entrada UNIX legível pelo proprietário. Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é UNIX.
`RarEntry::ATTRIBUTE_UNIX_STICKY`
  Bit que representa o sticky bit do UNIX. Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é UNIX.
`RarEntry::ATTRIBUTE_UNIX_SETGID`
  Bit que representa o atributo setgid do UNIX. Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é UNIX.
`RarEntry::ATTRIBUTE_UNIX_SETUID`
  Bit que representa o atributo setuid do UNIX. Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é UNIX.
`RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`
  Máscara para isolar os últimos quatro bits (nibble) dos atributos UNIX (_S_IFMT, o tipo de máscara de arquivo). Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é UNIX e com as constantes `RarEntry::ATTRIBUTE_UNIX_FIFO`, `RarEntry::ATTRIBUTE_UNIX_CHAR_DEV`, `RarEntry::ATTRIBUTE_UNIX_DIRECTORY`, `RarEntry::ATTRIBUTE_UNIX_BLOCK_DEV`, `RarEntry::ATTRIBUTE_UNIX_REGULAR_FILE`, `RarEntry::ATTRIBUTE_UNIX_SYM_LINK` e `RarEntry::ATTRIBUTE_UNIX_SOCKET`.
`RarEntry::ATTRIBUTE_UNIX_FIFO`
  FIFOs Unix terão atributos cujos últimos quatro bits possuem este valor. Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é UNIX e com a constante `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`.
`RarEntry::ATTRIBUTE_UNIX_CHAR_DEV`
  Dispositivos de caracteres Unix terão atributos cujos últimos quatro bits possuem este valor. Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é UNIX e com a constante `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`.
`RarEntry::ATTRIBUTE_UNIX_DIRECTORY`
  Os diretórios Unix terão atributos cujos últimos quatro bits possuem este valor. Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é UNIX e com a constante `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`. Consulte também RarEntry::isDirectory(), que também funciona com entradas que foram adicionadas em outros sistemas operacionais.
`RarEntry::ATTRIBUTE_UNIX_BLOCK_DEV`
  Dispositivos de bloco Unix terão atributos cujos últimos quatro bits possuem este valor. Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é UNIX e com a constante `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`.
`RarEntry::ATTRIBUTE_UNIX_REGULAR_FILE`
  Arquivos regulares Unix (não diretórios) terão atributos cujos últimos quatro bits possuem este valor. Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é UNIX e com a constante `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`. Consulte também RarEntry::isDirectory(), que também funciona com entradas que foram adicionadas em outros sistemas operacionais.
`RarEntry::ATTRIBUTE_UNIX_SYM_LINK`
  Links simbólicos Unix terão atributos cujos últimos quatro bits possuem este valor. Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é UNIX e com a constante `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`.
`RarEntry::ATTRIBUTE_UNIX_SOCKET`
  Os soquetes Unix terão atributos cujos últimos quatro bits possuem este valor. Para ser usado com RarEntry::getAttr() em entradas cujo sistema operacional host é UNIX e com a constante `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`.

# RarEntry::extract

(PECL rar >= 0.1)

RarEntry::extract — Extrai entrada do arquivo

### Descrição

public function RarEntry::extract(
string `$dir`,
string `$filepath` = "",
string `$password` = NULL,
bool `$extended_data` = `false`
): bool

RarEntry::extract() extrai os dados da entrada. Ele criará um novo arquivo no `dir` especificado com o nome idêntico ao nome da entrada, a menos que o segundo argumento seja especificado. Veja abaixo para mais informações.

### Parâmetros

`dir`
  Caminho para o diretório onde os arquivos devem ser extraídos. Este parâmetro é considerado se e somente se `filepath` não for. Se ambos os parâmetros estiverem vazios, será tentada uma extração para o diretório atual.
`filepath`
  Caminho (relativo ou absoluto) contendo o diretório e o nome do arquivo extraído. Este parâmetro substitui o parâmetro `dir` e o nome do arquivo original.
`password`
  A senha usada para criptografar esta entrada. Se a entrada não estiver criptografada, este valor não será utilizado e poderá ser omitido. Se este parâmetro for omitido e a entrada for criptografada, será usada a senha fornecida para rar_open(), se houver. Se uma senha errada for fornecida, explícita ou implicitamente via rar_open(), a verificação CRC falhará e este método falhará e retornará `false`. Se nenhuma senha for fornecida e uma for necessária, este método falhará e retornará `false`. Você pode verificar se uma entrada está criptografada com RarEntry::isEncrypted().
`extended_data`
  Se `true`, informações estendidas, como ACLs NTFS e informações do proprietário do Unix, serão definidas nos arquivos de extração, desde que estejam presentes no arquivo.

Aviso

Antes da versão 2.0.0, esta função não tratava caminhos corretamente. Use realpath() como solução alternativa.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL rar 3.0.0 | `extended_data` foi adicionado.
PECL rar 3.0.0 | O suporte para arquivos RAR com nomes de entrada repetidos não apresenta mais defeitos.

### Exemplos

Exemplo #1 Exemplo de RarEntry::extract()

    <?php

    $rar_file = rar_open('example.rar') or die("Falha ao abrir arquivo Rar");

    $entry = rar_entry_get($rar_file, 'Dir/arquivo.txt') or die("Falha ao pesquisar entrada");

    $entry->extract('/dir/oara'); // cria /dir/para/Dir/arquivo.txt
    $entry->extract(false, '/dir/para/novo_nome.txt'); // cria /dir/para/novo_nome.txt

    ?>

Exemplo #2 Como extrair todos os arquivos do arquivo:

    <?php

    /* exemplo por Erik Jenssen também conhecido como erix */

    $filename = "foobar.rar";
    $filepath = "/home/foo/bar/";

    $rar_file = rar_open($filepath.$filename);
    $list = rar_list($rar_file);
    foreach($list as $file) {
        $entry = rar_entry_get($rar_file, $file);
        $entry->extract("."); // extrai para o diretório atual
    }
    rar_close($rar_file);

    ?>

### Veja Também

- RarEntry::getStream() - Obtém manipulador de arquivo para entrada
- Empacotador `rar://`

# RarEntry::getAttr

(PECL rar >= 0.1)

RarEntry::getAttr — Obtém atributos da entrada

### Descrição

public function RarEntry::getAttr(): int

Retorna os atributos dependentes do sistema operacional da entrada de arquivo.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna os atributos ou `false` em caso de erro.

### Exemplos

Exemplo #1 Exemplo de RarEntry::getAttr()

    <?php

    $rar_file = rar_open('example.rar') or die("Não foi possível abrir arquivo Rar");

    $entry = rar_entry_get($rar_file, 'dir/in/the/archive') or die("Não foi possível pesquisar tal entrada");

    $host_os = $entry->getHostOs();
    $attr = $entry->getAttr();

    switch($host_os) {
        case RAR_HOST_MSDOS:
        case RAR_HOST_OS2:
        case RAR_HOST_WIN32:
        case RAR_HOST_MACOS:
            printf("%c%c%c%c%c%c\n",
                    ($attr & 0x08) ? 'V' : '.',
                    ($attr & 0x10) ? 'D' : '.',
                    ($attr & 0x01) ? 'R' : '.',
                    ($attr & 0x02) ? 'H' : '.',
                    ($attr & 0x04) ? 'S' : '.',
                    ($attr & 0x20) ? 'A' : '.');
            break;
        case RAR_HOST_UNIX:
        case RAR_HOST_BEOS:
            switch ($attr & 0xF000)
            {
                case 0x4000:
                    printf("d");
                    break;
                case 0xA000:
                    printf("l");
                    break;
                default:
                    printf("-");
                    break;
            }
            printf("%c%c%c%c%c%c%c%c%c\n",
                    ($attr & 0x0100) ? 'r' : '-',
                    ($attr & 0x0080) ? 'w' : '-',
                    ($attr & 0x0040) ? (($attr & 0x0800) ? 's':'x'):(($attr & 0x0800) ? 'S':'-'),
                    ($attr & 0x0020) ? 'r' : '-',
                    ($attr & 0x0010) ? 'w' : '-',
                    ($attr & 0x0008) ? (($attr & 0x0400) ? 's':'x'):(($attr & 0x0400) ? 'S':'-'),
                    ($attr & 0x0004) ? 'r' : '-',
                    ($attr & 0x0002) ? 'w' : '-',
                    ($attr & 0x0001) ? 'x' : '-');
            break;
    }

    rar_close($rar_file);

    ?>

### Veja Também

- RarEntry::getHostOs() - Obtém sistema operacional host de entrada
- As constantes em RarEntry

# RarEntry::getCrc

(PECL rar >= 0.1)

RarEntry::getCrc — Obtém CRC da entrada

### Descrição

public function RarEntry::getCrc(): string

Retorna uma representação de string hexadecimal do CRC da entrada do arquivo.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o CRC da entrada do arquivo ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL rar 2.0.0 | Este método agora retorna valores corretos para arquivos de vários volumes.

# RarEntry::getFileTime

(PECL rar >= 0.1)

RarEntry::getFileTime — Obtém hora da última modificação da entrada

### Descrição

public function RarEntry::getFileTime(): string

Obtém a hora da última modificação da entrada.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a hora da última modificação da entrada como string no formato `YYYY-MM-DD HH:II:SS` ou `false` em caso de erro.

# RarEntry::getHostOs

(PECL rar >= 0.1)

RarEntry::getHostOs — Obtém sistema operacional host de entrada

### Descrição

public function RarEntry::getHostOs(): int

Retorna o código do sistema operacional host da entrada do arquivo.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o código do sistema operacional host ou `false` em caso de erro.

### Exemplos

Exemplo #1 Exemplo de RarEntry::getHostOs() (versão >= 2.0.0)

    <?php

    $rar_file = rar_open('exemplo.rar') or die("Falha ao abrir arquivo Rar");

    $entry = rar_entry_get($rar_file, 'Dir/arquivo.txt') or die("Falha ao pesquisar tal entrada");

    switch ($entry->getHostOs()) {
        case RarEntry::HOST_MSDOS:
            echo "MS-DOS\n";
            break;
        case RarEntry::HOST_OS2:
            echo "OS2\n";
            break;
        case RarEntry::HOST_WIN32:
            echo "Win32\n";
            break;
        case RarEntry::HOST_MACOS:
            echo "MacOS\n";
            break;
        case RarEntry::HOST_UNIX:
            echo "Unix/Linux\n";
            break;
        case RarEntry::HOST_BEOS:
            echo "BeOS\n";
            break;
    }

    ?>

Exemplo #2 Exemplo de RarEntry::getHostOs() (versão <= 1.0.0)

    <?php

    $rar_file = rar_open('exemplo.rar') or die("Falha ao abrir arquivo Rar");

    $entry = rar_entry_get($rar_file, 'Dir/arquivo.txt') or die("Falha ao pesquisar tal entrada");

    switch ($entry->getHostOs()) {
        case RAR_HOST_MSDOS:
            echo "MS-DOS\n";
            break;
        case RAR_HOST_OS2:
            echo "OS2\n";
            break;
        case RAR_HOST_WIN32:
            echo "Win32\n";
            break;
        case RAR_HOST_MACOS:
            echo "MacOS\n";
            break;
        case RAR_HOST_UNIX:
            echo "Unix/Linux\n";
            break;
        case RAR_HOST_BEOS:
            echo "BeOS\n";
            break;
    }

    ?>

### Veja Também

- RarEntry::extract() - Extrai entrada do arquivo

# RarEntry::getMethod

(PECL rar >= 0.1)

RarEntry::getMethod — Obtém método pack da entrada

### Descrição

public function RarEntry::getMethod(): int

RarEntry::getMethod() retorna o número do método usado ao adicionar a entrada atual do arquivo.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número do método ou `false` em caso de erro.

### Exemplos

Exemplo #1 Exemplo de RarEntry::getMethod()

    <?php

    $rar_file = rar_open('exemplo.rar') or die("Falha ao abrir arquivo Rar");

    $entry = rar_entry_get($rar_file, 'Dir/arquivo.txt') or die("Falha ao pesquisar tal entrada");

    echo "Método número: " . $entry->getMethod();

    ?>

# RarEntry::getName

(PECL rar >= 0.1)

RarEntry::getName — Obtém o nome da entrada

### Descrição

public function RarEntry::getName(): string

Retorna o nome (com caminho) da entrada do arquivo.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o nome da entrada como uma string ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL rar 2.0.0 | A partir da versão 2.0.0, a string retornada é codificada em Unicode/UTF-8.

### Exemplos

Exemplo #1 Exemplo de RarEntry::getName()

    <?php

    //este exemplo é seguro mesmo em páginas não codificadas em UTF-8
    //para aqueles codificados em UTF-8, a chamada para mb_convert_encoding é desnecessária

    $rar_file = rar_open('exemplo.rar') or die("Falha ao abrir arquivo Rar");

    $entry = rar_entry_get($rar_file, 'Dir/arquivo.txt') or die("Falha ao pesquisar tal entrada");

    echo "Entry name: " . mb_convert_encoding(
        htmlentities(
            $entry->getName(),
            ENT_COMPAT,
            "UTF-8"
        ),
        "HTML-ENTITIES",
        "UTF-8"
    );

    ?>

# RarEntry::getPackedSize

(PECL rar >= 0.1)

RarEntry::getPackedSize — Obtém o tamanho compactado da entrada

### Descrição

public function RarEntry::getPackedSize(): int

Obtém o tamanho compactado da entrada do arquivo.

> Nota: Observe que em plataformas com comprimentos de 32 bits (que inclui Windows x64), o tamanho máximo retornado é limitado a 2 GiB. Verifique a constante `PHP_INT_MAX`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o tamanho compactado ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL rar 2.0.0 | Este método agora retorna valores corretos de tamanhos compactados maiores que 2 GiB em plataformas com ints de 64 bits e nunca retorna valores negativos em outras plataformas.

### Exemplos

Exemplo #1 Exemplo de RarEntry::getPackedSize()

    <?php

    $rar_file = rar_open('exemplo.rar') or die("Falha ao abrir arquivo Rar");

    $entry = rar_entry_get($rar_file, 'Dir/arquivo.txt') or die("Falha ao pesquisar tal entrada");

    echo "Tamanho compactado de " . $entry->getName() . " = " . $entry->getPackedSize() . " bytes";

    ?>

# RarEntry::getStream

(PECL rar >= 2.0.0)

RarEntry::getStream — Obtém manipulador de arquivo para entrada

### Descrição

public function RarEntry::getStream(string `$password` = ?): resource|false

Retorna um manipulador de arquivos que oferece suporte a operações de leitura. Este manipulador fornece descompressão instantânea para esta entrada.

manipulador não é invalidado chamando rar_close().

Aviso

O fluxo resultante não possui verificação de integridade. Em particular, a corrupção e a descriptografia de arquivos com uma chave errada não serão detectadas. É responsabilidade do programador usar o CRC da entrada para verificar a integridade, se assim desejar.

### Parâmetros

`password`
  A senha usada para criptografar esta entrada. Se a entrada não estiver criptografada, este valor não será usado e poderá ser omitido. Se este parâmetro for omitido e a entrada for criptografada, será usada a senha fornecida para rar_open(), se houver. Se uma senha errada for fornecida, explícita ou implicitamente via rar_open(), o fluxo resultante deste método produzirá uma saída errada. Se nenhuma senha for fornecida e uma for necessária, este método falhará e retornará `false`. Você pode verificar se uma entrada está criptografada com RarEntry::isEncrypted().

### Valor Retornado

O manipulador de arquivo ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL rar 3.0.0 | O suporte para arquivos RAR com nomes de entrada repetidos não apresenta mais defeitos.

### Exemplos

Exemplo #1 Exemplo de RarEntry::getStream()

    <?php

    $rar_file = rar_open('exemplo.rar');
    if ($rar_file === false)
        die("Falha ao abrir arquivo Rar");

    $entry = rar_entry_get($rar_file, 'Dir/arquivo.txt');
    if ($entry === false)
        die("Falha ao pesquisar tal entrada");

    $stream = $entry->getStream();
    if ($stream === false)
        die("Falha ao obter fluxo.");

    rar_close($rar_file); // fluxo é independente do arquivo

    while (!feof($stream)) {
        $buff = fread($stream, 8192);
        if ($buff !== false)
            echo $buff;
        else
            break; // erro em fread
    }

    fclose($stream);

    ?>

### Veja Também

- RarEntry::extract() - Extrai entrada do arquivo
- Empacotador `rar://`

# RarEntry::getUnpackedSize

(PECL rar >= 0.1)

RarEntry::getUnpackedSize — Obtém o tamanho descompactado da entrada

### Descrição

public function RarEntry::getUnpackedSize(): int

Obtém o tamanho descompactado da entrada do arquivo.

> Nota: Observe que em plataformas com comprimentos de 32 bits (que inclui Windows x64), o tamanho máximo retornado é limitado a 2 GiB. Verifique a constante `PHP_INT_MAX`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o tamanho descompactado ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL rar 2.0.0 | Este método agora retorna valores corretos de tamanhos descompactados maiores que 2 GiB em plataformas com ints de 64 bits e nunca retorna valores negativos em outras plataformas.

### Valor Retornado

Exemplo #1 Exemplo de RarEntry::getUnpackedSize()

    <?php

    $rar_file = rar_open('exemplo.rar') or die("Falha ao abrir arquivo Rar");

    $entry = rar_entry_get($rar_file, 'Dir/arquivo.txt') or die("Falha ao pesquisar tal entrada");

    echo "Tamanho descompactado de " . $entry->getName() . " = " . $entry->getUnpackedSize() . " bytes";

    ?>

# RarEntry::getVersion

(PECL rar >= 0.1)

RarEntry::getVersion — Obtém a versão mínima do programa RAR necessária para descompactar a entrada

### Descrição

public function RarEntry::getVersion(): int

Retorna a versão mínima do programa RAR (por exemplo, WinRAR) necessária para descompactar a entrada. É codificado como 10 * versão principal + versão secundária.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a versão ou `false` em caso de erro.

### Exemplos

Exemplo #1 Exemplo de RarEntry::getVersion()

    <?php

    $rar_file = rar_open('exemplo.rar') or die("Falha ao abrir arquivo Rar");

    $entry = rar_entry_get($rar_file, 'Dir/arquivo.txt') or die("Falha ao pesquisar tal entrada");

    echo "Versão Rar requerida para descompactar: " . $entry->getVersion();

    ?>

# RarEntry::isDirectory

(PECL rar >= 2.0.0)

RarEntry::isDirectory — Testa se uma entrada representa um diretório

### Descrição

public function RarEntry::isDirectory(): bool

Testa se a entrada atual é um diretório.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se esta entrada for um diretório e `false` caso contrário.

### Notas

Esta função só está disponível a partir da versão 2.0.0, mas também é possível testar se uma entrada é um diretório verificando os atributos da entrada, como este (funciona apenas para arquivos compactados em RAR para Windows ou Unix):

    <?php
    //...
    //Abre o arquivo, obtém a entrada e armazena na variável $e...
    //...

    $isDirectory = (bool) ((($e->getHostOs() == RAR_HOST_WIN32) && ($e->getAttr() & 0x10)) ||
        (($e->getHostOs() == RAR_HOST_UNIX) && (($e->getAttr() & 0xf000) == 0x4000)));
    ?>

# RarEntry::isEncrypted

(PECL rar >= 2.0.0)

RarEntry::isEncrypted — Testa se uma entrada está criptografada

### Descrição

public function RarEntry::isEncrypted(): bool

Testa se o conteúdo da entrada atual está criptografado.

> Nota: A senha usada pode diferir entre arquivos dentro do mesmo arquivo RAR.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se a entrada atual estiver criptografada e `false` caso contrário.

# RarEntry::__toString

(PECL rar >= 2.0.0)

RarEntry::__toString — Obtém representação em texto da entrada

### Descrição

public function RarEntry::__toString(): string

RarEntry::__toString() retorna uma representação textual para esta entrada. Inclui se a entrada é um arquivo ou diretório (links simbólicos e outros objetos especiais serão tratados como arquivos), o nome UTF-8 da entrada e seu CRC. A forma e o conteúdo desta representação podem ser alterados no futuro, portanto não podem ser considerados confiáveis.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Uma representação textual para a entrada.

## Índice

- RarEntry::extract — Extrai entrada do arquivo
- RarEntry::getAttr — Obtém atributos da entrada
- RarEntry::getCrc — Obtém CRC da entrada
- RarEntry::getFileTime — Obtém hora da última modificação da entrada
- RarEntry::getHostOs — Obtém sistema operacional host de entrada
- RarEntry::getMethod — Obtém método pack da entrada
- RarEntry::getName — Obtém o nome da entrada
- RarEntry::getPackedSize — Obtém o tamanho compactado da entrada
- RarEntry::getStream — Obtém manipulador de arquivo para entrada
- RarEntry::getUnpackedSize — Obtém o tamanho descompactado da entrada
- RarEntry::getVersion — Obtém a versão mínima do programa RAR necessária para descompactar a entrada
- RarEntry::isDirectory — Testa se uma entrada representa um diretório
- RarEntry::isEncrypted — Testa se uma entrada está criptografada
- RarEntry::__toString — Obtém representação em texto da entrada

# A classe RarException

(PECL rar >= 2.0.0)

## Introdução

Esta classe tem dois propósitos: é o tipo de exceções lançadas pelas funções e métodos da extensão RAR e permite, através de métodos estáticos consultar e definir o comportamento de erro da extensão, ou seja, se exceções são lançadas ou apenas avisos são emitidos.

Os seguintes códigos de erro são usados:

- -1 - erro fora da biblioteca UnRAR
- 11 - memória insuficiente
- 12 - dados ruins
- 13 - arquivo ruim
- 14 - formato desconhecido
- 15 - erro ao abrir arquivo
- 16 - erro de criação de arquivo
- 17 - erro de fechamento de arquivo
- 18 - erro de leitura
- 19 - erro de gravação
- 20 - buffer muito pequeno
- 21 - erro RAR desconhecido
- 22 - senha necessária, mas não fornecida

## Resumo da classe

final class RarException extends Exception {
/* Métodos */
public static function isUsingExceptions(): bool
public static function setUsingExceptions(bool `$using_exceptions`): void
/* Métodos herdados */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# RarException::isUsingExceptions

(PECL rar >= 2.0.0)

RarException::isUsingExceptions — Verifica se o tratamento de erros com exceções está em uso

### Descrição

public static function RarException::isUsingExceptions(): bool

Verifica se as funções RAR emitirão avisos e retornarão valores de erro ou se lançarão exceções na maioria das circunstâncias (não inclui alguns erros programáticos, como passar o tipo errado de argumentos).

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se exceções estão sendo usadas, `false` caso contrário.

### Exemplos

Exemplo #1 Exemplo de RarException::isUsingExceptions()

    <?php
    //O padrão é não usar exceções
    var_dump(RarException::isUsingExceptions());
    ?>

O exemplo acima produzirá algo semelhante a:

    bool(false)

### Veja Também

- RarException::setUsingExceptions() - Ativa e desativa o tratamento de erros com exceções

# RarException::setUsingExceptions

(PECL rar >= 2.0.0)

RarException::setUsingExceptions — Ativa e desativa o tratamento de erros com exceções

### Descrição

public static function RarException::setUsingExceptions(bool `$using_exceptions`): void

Se e somente se o argumento for `true`, então, em vez de emitir avisos e retornar um valor especial indicando erro quando a biblioteca UnRAR encontrar um erro, uma exceção do tipo RarException será lançada.

Exceções também serão lançadas para os seguintes erros, que ocorrem fora da biblioteca (seu código de erro será -1):

- tentar algumas operações em um objeto RarArchive fechado ou em um objeto RarEntry relativo ao primeiro;
- tentar obter uma entrada que não existe com RarArchive::getEntry().

### Parâmetros

`using_exceptions`
  Deve ser `true` para ativar o lançamento de exceções, `false` para desativar (o padrão).

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de RarException::setUsingExceptions()

    <?php
    var_dump(RarException::isUsingExceptions());
    $arch = RarArchive::open("nao_existe.rar");
    var_dump($arch);

    RarException::setUsingExceptions(true);
    var_dump(RarException::isUsingExceptions());
    $arch = RarArchive::open("nao_existe.rar");
    var_dump($arch); // não alcançado
    ?>

O exemplo acima produzirá algo semelhante a:

    bool(false)

    Warning: RarArchive::open(): Failed to open nao_existe.rar: ERAR_EOPEN (file open error) in C:\php_rar\trunk\tests\test.php on line 3
    bool(false)
    bool(true)

    Fatal error: Uncaught exception 'RarException' with message 'unRAR internal error: Failed to open nao_existe.rar: ERAR_EOPEN (file open error)' in C:\php_rar\trunk\tests\test.php:8
    Stack trace:
    #0 C:\php_rar\trunk\tests\test.php(8): RarArchive::open('nao_existe....')
    #1 {main}
      thrown in C:\php_rar\trunk\tests\test.php on line 8

### Veja Também

- RarException::isUsingExceptions() - Verifica se o tratamento de erros com exceções está em uso

## Índice

- RarException::isUsingExceptions — Verifica se o tratamento de erros com exceções está em uso
- RarException::setUsingExceptions — Ativa e desativa o tratamento de erros com exceções

- Instalação/Configuração
  - Instalação
  - Tipos de Recurso
- Constantes predefinidas
- Exemplos
- Funções de Rar
  - rar_wrapper_cache_stats — Acertos e erros de cache para o empacotador de URL
- RarArchive — A classe RarArchive
  - RarArchive::close — Fecha o arquivo RAR e libera todos os recursos
  - RarArchive::getComment — Obtém o texto de comentário do arquivo RAR
  - RarArchive::getEntries — Obtém a lista completa de entradas do arquivo RAR
  - RarArchive::getEntry — Obtém o objeto de entrada do arquivo RAR
  - RarArchive::isBroken — Testa se um arquivo está quebrado (incompleto)
  - RarArchive::isSolid — Verifica se o arquivo RAR é sólido
  - RarArchive::open — Abre arquivo RAR
  - RarArchive::setAllowBroken — Se é permitido abrir arquivos quebrados
  - RarArchive::__toString — Obtém representação de texto
- RarEntry — A classe RarEntry
  - RarEntry::extract — Extrai entrada do arquivo
  - RarEntry::getAttr — Obtém atributos da entrada
  - RarEntry::getCrc — Obtém CRC da entrada
  - RarEntry::getFileTime — Obtém hora da última modificação da entrada
  - RarEntry::getHostOs — Obtém sistema operacional host de entrada
  - RarEntry::getMethod — Obtém método pack da entrada
  - RarEntry::getName — Obtém o nome da entrada
  - RarEntry::getPackedSize — Obtém o tamanho compactado da entrada
  - RarEntry::getStream — Obtém manipulador de arquivo para entrada
  - RarEntry::getUnpackedSize — Obtém o tamanho descompactado da entrada
  - RarEntry::getVersion — Obtém a versão mínima do programa RAR necessária para descompactar a entrada
  - RarEntry::isDirectory — Testa se uma entrada representa um diretório
  - RarEntry::isEncrypted — Testa se uma entrada está criptografada
  - RarEntry::__toString — Obtém representação em texto da entrada
- RarException — A classe RarException
  - RarException::isUsingExceptions — Verifica se o tratamento de erros com exceções está em uso
  - RarException::setUsingExceptions — Ativa e desativa o tratamento de erros com exceções

# Zip

# Introdução

Esta extensão habilita você a ler ou escrever arquivos ZIP e os arquivos compactados internamente.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Tipos de Recurso

## Dependências

Esta extensão requer » libzip. A versão 1.1.2 era internalizada no PHP até a versão 7.3.

A versão mínima necessária é 0.11, mas uma versão mais recente é recomendada.

- A versão 1.2 é requerida para suporte criptografia, veja ZipArchive::setEncryptionIndex()
- A versão 1.3 é requerida para suporte progresso, veja ZipArchive::registerProgressCallback()
- A versão 1.6 é requerida para suporte de cancelamento, veja ZipArchive::registerCancelCallback()

## Instalação

## Sistemas Linux

Para usar estas funções, o PHP deve ser compilado com suporte ZIP usando-se a opção de configuração --with-zip.

Antes do PHP 7.4.0, libzip era incluída no PHP, e para compilar a extensão era necessário usar a opção de configuração --enable-zip. Compilar com a libzip inclusa era desencorajado a partir do PHP 7.3.0, mas ainda possível, usando-se a opção de configuração --without-libzip.

Um opção de configuração --with-libzip=DIR foi adicionada para usar uma instalação libzip de sistema. A versão 0.11 da libzip é requerida, com 0.11.2 ou posterior recomendada.

## Windows

A partir do PHP 8.2.0, a DLL php_zip.dll precisa ser ativada no php.ini. Anteriormente, esta extensão era interna.

## Instalação via PECL

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/zip.

## Tipos de Recurso

Há dois tipos de recursos neste módulo. O primeiro é um Zip directory para arquivo Zip, o segundo Zip Entry para entradas de arquivos.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

ZipArchive utiliza constantes de classe. Existem vários tipos de constantes, os principais são: Opções (prefixadas com `FL_`), Opções globais (prefixadas com `AFL_`), erros (prefixadas com `ER_`) e modo (sem prefixo).

Modos de abertura do arquivo
`ZipArchive::CREATE` (int)
  Cria o arquivo se ele não existir.
`ZipArchive::OVERWRITE` (int)
  Se o arquivo existir, ignora seu conteúdo atual. Em outras palavras, manipule-o da mesma maneira que um arquivo vazio.
`ZipArchive::EXCL` (int)
  Erro se o arquivo já existir.
`ZipArchive::RDONLY` (int)
  Abre o arquivo apenas para leitura. Disponível a partir do PHP 7.4.3 e PECL zip 1.17.1, respectivamente, se compilado com libzip ≥ 1.0.0.
`ZipArchive::CHECKCONS` (int)
  Realiza verificações de consistência adicionais no arquivo e gera erro se falhar.

Opções globais do arquivo
`ZipArchive::AFL_RDONLY` (int)
  O arquivo é somente leitura, não pode ser limpo. Disponível a partir do PHP 8.3.0 e PECL zip 1.22.0, respectivamente, se compilado com libzip ≥ 1.10.0.
`ZipArchive::AFL_IS_TORRENTZIP` (int)
  O arquivo atual está zipado como torrent. Disponível a partir do PHP 8.3.0 e PECL zip 1.22.0, respectivamente, se compilado com libzip ≥ 1.10.0.
`ZipArchive::AFL_WANT_TORRENTZIP` (int)
  Escreve o arquivo no formato torrentzip. Disponível a partir do PHP 8.3.0 e PECL zip 1.22.0, respectivamente, se compilado com libzip ≥ 1.10.0.
`ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE` (int)
  Não remover o arquivo se o arquivo estiver vazio. Disponível a partir do PHP 8.3.0 e PECL zip 1.22.0, respectivamente, se compilado com libzip ≥ 1.10.0.

Opções do arquivo
`ZipArchive::FL_NOCASE` (int)
  Ignora a diferenciação entre maiúsculas e minúsculas na busca por nomes.
`ZipArchive::FL_NODIR` (int)
  Ignora o componente de diretório.
`ZipArchive::FL_COMPRESSED` (int)
  Lê dados compactados.
`ZipArchive::FL_UNCHANGED` (int)
  Usa os dados originais, ignorando alterações.
`ZipArchive::FL_RECOMPRESS` (int)
  Força a recompressão dos dados. Disponível a partir do PHP 8.0.0 e PECL zip 1.18.0. Descontinuado a partir do PHP 8.3.0 e PECL zip 1.22.1, será removido em uma versão futura do libzip.
`ZipArchive::FL_ENCRYPTED` (int)
  Lê dados criptografados (implica FL_COMPRESSED). Disponível a partir do PHP 8.0.0 e PECL zip 1.18.0.
`ZipArchive::FL_OVERWRITE` (int)
  Se o arquivo com o nome existir, substitua-o. Disponível a partir do PHP 8.0.0 e PECL zip 1.18.0.
`ZipArchive::FL_LOCAL` (int)
  No cabeçalho local. Disponível a partir do PHP 8.0.0 e PECL zip 1.18.0.
`ZipArchive::FL_CENTRAL` (int)
  No diretório central. Disponível a partir do PHP 8.0.0 e PECL zip 1.18.0.
`ZipArchive::FL_ENC_GUESS` (int)
  Suposição de codificação de string (é o padrão). Disponível a partir do PHP 7.0.8.
`ZipArchive::FL_ENC_RAW` (int)
  Obter a string não modificada. Disponível a partir do PHP 7.0.8.
`ZipArchive::FL_ENC_STRICT` (int)
  Seguir estritamente a especificação. Disponível a partir do PHP 7.0.8.
`ZipArchive::FL_ENC_UTF_8` (int)
  A string é codificada em UTF-8. Disponível a partir do PHP 7.0.8.
`ZipArchive::FL_ENC_CP437` (int)
  A string é codificada em CP437. Disponível a partir do PHP 7.0.8.
`ZipArchive::FL_OPEN_FILE_NOW` (int)
  Abre o arquivo quando adicionado em vez de esperar o arquivo zip ser fechado. Esteja ciente do consumo de descritores de arquivo. Disponível a partir do PHP 8.3.0 e PECL zip 1.22.1.

Modos de compressão
`ZipArchive::CM_DEFAULT` (int)
  melhor de deflate ou store.
`ZipArchive::CM_STORE` (int)
  armazenado (não comprimido).
`ZipArchive::CM_SHRINK` (int)
  reduzido
`ZipArchive::CM_REDUCE_1` (int)
  reduzido com fator 1
`ZipArchive::CM_REDUCE_2` (int)
  reduzido com fator 2
`ZipArchive::CM_REDUCE_3` (int)
  reduzido com fator 3
`ZipArchive::CM_REDUCE_4` (int)
  reduzido com fator 4
`ZipArchive::CM_IMPLODE` (int)
  implode
`ZipArchive::CM_DEFLATE` (int)
  desinflado
`ZipArchive::CM_DEFLATE64` (int)
  deflate64
`ZipArchive::CM_PKWARE_IMPLODE` (int)
  implode PKWARE
`ZipArchive::CM_BZIP2` (int)
  algoritmo BZIP2
`ZipArchive::CM_LZMA` (int)
  algoritmo LZMA
`ZipArchive::CM_LZMA2` (int)
  algoritmo LZMA2. Disponível a partir do PHP 7.4.3 e PECL zip 1.16.0, respectivamente, se compilado com libzip ≥ 1.6.0.
`ZipArchive::CM_ZSTD` (int)
  algoritmo Zstandard. Disponível a partir do PHP 8.0.0 e PECL zip 1.19.1, respectivamente, se compilado com libzip ≥ 1.8.0.
`ZipArchive::CM_XZ` (int)
  algoritmo XZ. Disponível a partir do PHP 7.4.3 e PECL zip 1.16.1, respectivamente, se compilado com libzip ≥ 1.6.0.
`ZipArchive::CM_TERSE` (int)
`ZipArchive::CM_LZ77` (int)
`ZipArchive::CM_WAVPACK` (int)
`ZipArchive::CM_PPMD` (int)

Erros
`ZipArchive::ER_OK` (int)
  Sem erro.
`ZipArchive::ER_MULTIDISK` (int)
  Arquivos zip multi-disco não suportados.
`ZipArchive::ER_RENAME` (int)
  Falha ao renomear arquivo temporário.
`ZipArchive::ER_CLOSE` (int)
  Falha ao fechar o arquivo zip.
`ZipArchive::ER_SEEK` (int)
  Erro de busca.
`ZipArchive::ER_READ` (int)
  Erro de leitura.
`ZipArchive::ER_WRITE` (int)
  Erro de escrita.
`ZipArchive::ER_CRC` (int)
  Erro CRC.
`ZipArchive::ER_ZIPCLOSED` (int)
  O arquivo zip contido foi fechado.
`ZipArchive::ER_NOENT` (int)
  Arquivo não encontrado.
`ZipArchive::ER_EXISTS` (int)
  Arquivo já existe.
`ZipArchive::ER_OPEN` (int)
  Não é possível abrir o arquivo.
`ZipArchive::ER_TMPOPEN` (int)
  Falha ao criar arquivo temporário.
`ZipArchive::ER_ZLIB` (int)
  Erro do Zlib.
`ZipArchive::ER_MEMORY` (int)
  Falha na alocação de memória.
`ZipArchive::ER_CHANGED` (int)
  Entrada foi alterada.
`ZipArchive::ER_COMPNOTSUPP` (int)
  Método de compressão não suportado.
`ZipArchive::ER_EOF` (int)
  EOF prematuro.
`ZipArchive::ER_INVAL` (int)
  Argumento inválido.
`ZipArchive::ER_NOZIP` (int)
  Não é um arquivo zip.
`ZipArchive::ER_INTERNAL` (int)
  Erro interno.
`ZipArchive::ER_INCONS` (int)
  Arquivo zip inconsistente.
`ZipArchive::ER_REMOVE` (int)
  Não é possível remover o arquivo.
`ZipArchive::ER_DELETED` (int)
  Entrada foi deletada.
`ZipArchive::ER_ENCRNOTSUPP` (int)
  Método de criptografia não suportado. Disponível a partir do PHP 7.4.3 e PECL zip 1.16.1, respectivamente.
`ZipArchive::ER_RDONLY` (int)
  Arquivo só de leitura. Disponível a partir do PHP 7.4.3 e PECL zip 1.16.1, respectivamente.
`ZipArchive::ER_NOPASSWD` (int)
  Nenhuma senha fornecida. Disponível a partir do PHP 7.4.3 e PECL zip 1.16.1, respectivamente.
`ZipArchive::ER_WRONGPASSWD` (int)
  Senha incorreta fornecida. Disponível a partir do PHP 7.4.3 e PECL zip 1.16.1, respectivamente.
`ZipArchive::ER_OPNOTSUPP` (int)
  Operação não suportada. Disponível a partir do PHP 7.4.3 e PECL zip 1.16.1, respectivamente, se compilado com libzip ≥ 1.0.0.
`ZipArchive::ER_INUSE` (int)
  Recurso ainda em uso. Disponível a partir do PHP 7.4.3 e PECL zip 1.16.1, respectivamente, se compilado com libzip ≥ 1.0.0.
`ZipArchive::ER_TELL` (int)
  Erro ao comunicar. Disponível a partir do PHP 7.4.3 e PECL zip 1.16.1, respectivamente, se compilado com libzip ≥ 1.0.0.
`ZipArchive::ER_COMPRESSED_DATA` (int)
  Dados comprimidos inválidos. Disponível a partir do PHP 7.4.3 e PECL zip 1.16.1, respectivamente, se compilado com libzip ≥ 1.6.0.
`ZipArchive::ER_CANCELLED` (int)
  Operação cancelada. Disponível a partir do PHP 7.4.3 e PECL zip 1.16.1, respectivamente, se compilado com libzip ≥ 1.6.0.
`ZipArchive::ER_DATA_LENGTH` (int)
  Comprimento de dados inesperado. Disponível a partir do PHP 8.3.0 e PECL zip 1.22.0, respectivamente, se compilado com libzip ≥ 1.10.0.
`ZipArchive::ER_NOT_ALLOWED` (int)
  Não permitido no torrentzip. Disponível a partir do PHP 8.3.0 e PECL zip 1.22.0, respectivamente, se compilado com libzip ≥ 1.10.0.
`ZipArchive::ER_TRUNCATED_ZIP` (int)
  Arquivo zip possivelmente truncado ou corrompido. Disponível a partir do PHP 8.4.0 e PECL zip 1.22.4, respectivamente, se construído com libzip ≥ 1.11.1.

Modos de criptografia
`ZipArchive::EM_NONE` (int)
  Sem criptografia. Disponível a partir do PHP 7.2.0 e PECL zip 1.14.0, respectivamente.
`ZipArchive::EM_TRAD_PKWARE` (int)
  Criptografia PKWARE tradicional. Disponível a partir do PHP 8.0.0 e PECL zip 1.19.0, respectivamente.
`ZipArchive::EM_AES_128` (int)
  Criptografia AES 128. Disponível a partir do PHP 7.2.0 e PECL zip 1.14.0, respectivamente, se compilado com libzip ≥ 1.2.0.
`ZipArchive::EM_AES_192` (int)
  Criptografia AES 192. Disponível a partir do PHP 7.2.0 e PECL zip 1.14.0, respectivamente, se compilado com libzip ≥ 1.2.0.
`ZipArchive::EM_AES_256` (int)
  Criptografia AES 256. Disponível a partir do PHP 7.2.0 e PECL zip 1.14.0, respectivamente, se compilado com libzip ≥ 1.2.0.
`ZipArchive::EM_UNKNOWN` (int)
  Algoritmo de criptografia desconhecido. Disponível a partir do PHP 8.0.0 e PECL zip 1.19.0, respectivamente.

Constantes de parâmetros de comprimento
`ZipArchive::LENGTH_TO_END` (int)
  Utilize o tamanho do arquivo; se o arquivo crescer, dados adicionais serão ignorados; se o arquivo encolher, um erro será gerado (`ZipArchive::ER_DATA_LENGTH`). Disponível a partir do PHP 8.3.0 e PECL zip 1.22.2.
`ZipArchive::LENGTH_UNCHECKED` (int)
  Utilize todos os dados disponíveis. Disponível a partir do PHP 8.3.0 e PECL zip 1.22.2, se compilado com libzip ≥ 1.10.1.

Outras constantes
`ZipArchive::LIBZIP_VERSION` (string)
  Versão da biblioteca Zip. Disponível a partir do PHP 7.4.3 e PECL zip 1.16.0.

Constantes do sistema operacional para atributos externos
`ZipArchive::OPSYS_DOS` (int)
`ZipArchive::OPSYS_AMIGA` (int)
`ZipArchive::OPSYS_OPENVMS` (int)
`ZipArchive::OPSYS_UNIX` (int)
`ZipArchive::OPSYS_VM_CMS` (int)
`ZipArchive::OPSYS_ATARI_ST` (int)
`ZipArchive::OPSYS_OS_2` (int)
`ZipArchive::OPSYS_MACINTOSH` (int)
`ZipArchive::OPSYS_Z_SYSTEM` (int)
`ZipArchive::OPSYS_CPM` (int)
`ZipArchive::OPSYS_WINDOWS_NTFS` (int)
`ZipArchive::OPSYS_MVS` (int)
`ZipArchive::OPSYS_VSE` (int)
`ZipArchive::OPSYS_ACORN_RISC` (int)
`ZipArchive::OPSYS_VFAT` (int)
`ZipArchive::OPSYS_ALTERNATE_MVS` (int)
`ZipArchive::OPSYS_BEOS` (int)
`ZipArchive::OPSYS_TANDEM` (int)
`ZipArchive::OPSYS_OS_400` (int)
`ZipArchive::OPSYS_OS_X` (int)
`ZipArchive::OPSYS_DEFAULT` (int)
  Desde PECL zip 1.12.4

# Exemplos

Exemplo #1 Criando um arquivo Zip

    <?php

    $zip = new ZipArchive();
    $filename = "./test112.zip";

    if ($zip->open($filename, ZipArchive::CREATE)!==TRUE) {
        exit("não foi possível abrir <$filename>\n");
    }

    $zip->addFromString("testfilephp.txt" . time(), "#1 Esta é uma string de teste adicionada como testfilephp.txt.\n");
    $zip->addFromString("testfilephp2.txt" . time(), "#2 Esta é uma string de teste adicionada como testfilephp2.txt.\n");
    $zip->addFile($thisdir . "/too.php","/testfromfile.php");
    echo "número de arquivos: " . $zip->numFiles . "\n";
    echo "status:" . $zip->status . "\n";
    $zip->close();
    ?>

Exemplo #2 Exibindo detalhes dos arquivos e listando-os

    <?php
    $za = new ZipArchive();

    $za->open('test_with_comment.zip');
    print_r($za);
    var_dump($za);
    echo "número de arquivos: " . $za->numFiles . "\n";
    echo "status: " . $za->status  . "\n";
    echo "status sistema: " . $za->statusSys . "\n";
    echo "arquivo: " . $za->filename . "\n";
    echo "comentário: " . $za->comment . "\n";

    for ($i=0; $i<$za->numFiles;$i++) {
        echo "índice: $i\n";
        print_r($za->statIndex($i));
    }
    echo "número de arquivos:" . $za->numFiles . "\n";
    ?>

Exemplo #3 Empacotador de fluxo zip, lendo metainformações do OpenOffice

    <?php
    $reader = new XMLReader();

    $reader->open('zip://' . dirname(__FILE__) . '/test.odt#meta.xml');
    $odt_meta = array();
    while ($reader->read()) {
        if ($reader->nodeType == XMLREADER::ELEMENT) {
            $elm = $reader->name;
        } else {
            if ($reader->nodeType == XMLREADER::END_ELEMENT && $reader->name == 'office:meta') {
                break;
            }
            if (!trim($reader->value)) {
                continue;
            }
            $odt_meta[$elm] = $reader->value;
        }
    }
    print_r($odt_meta);
    ?>

Este exemplo usa a velha API (PHP 4), ela abre um arquivo ZIP, ler cada arquivo do arquivo e imprime o conteúdo deles. O arquivo test2.zip usado neste exemplo é um arquivo de teste do fonte da distribuição ZZIPlib.

Exemplo #4 Exemplo de uso

    <?php

    $zip = zip_open("/tmp/test2.zip");

    if ($zip) {
        while ($zip_entry = zip_read($zip)) {
            echo "Nome:                    " . zip_entry_name($zip_entry) . "\n";
            echo "Tamanho real do arquivo: " . zip_entry_filesize($zip_entry) . "\n";
            echo "Tamanho compactado:      " . zip_entry_compressedsize($zip_entry) . "\n";
            echo "Método de compactação:   " . zip_entry_compressionmethod($zip_entry) . "\n";

            if (zip_entry_open($zip, $zip_entry, "r")) {
                echo "Conteúdo do arquivo:\n";
                $buf = zip_entry_read($zip_entry, zip_entry_filesize($zip_entry));
                echo "$buf\n";

                zip_entry_close($zip_entry);
            }
            echo "\n";

        }

        zip_close($zip);

    }
    ?>

# A classe ZipArchive

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

## Introdução

Um arquivo compactado com Zip.

## Resumo da classe

class ZipArchive implements Countable {
/* Constantes */
public const int CREATE;
public const int EXCL;
public const int CHECKCONS;
public const int OVERWRITE;
public const int RDONLY;
public const int FL_NOCASE;
public const int FL_NODIR;
public const int FL_COMPRESSED;
public const int FL_UNCHANGED;
public const int FL_RECOMPRESS;
public const int FL_ENCRYPTED;
public const int FL_OVERWRITE;
public const int FL_LOCAL;
public const int FL_CENTRAL;
public const int FL_ENC_GUESS;
public const int FL_ENC_RAW;
public const int FL_ENC_STRICT;
public const int FL_ENC_UTF_8;
public const int FL_ENC_CP437;
public const int FL_OPEN_FILE_NOW;
public const int CM_DEFAULT;
public const int CM_STORE;
public const int CM_SHRINK;
public const int CM_REDUCE_1;
public const int CM_REDUCE_2;
public const int CM_REDUCE_3;
public const int CM_REDUCE_4;
public const int CM_IMPLODE;
public const int CM_DEFLATE;
public const int CM_DEFLATE64;
public const int CM_PKWARE_IMPLODE;
public const int CM_BZIP2;
public const int CM_LZMA;
public const int CM_LZMA2;
public const int CM_ZSTD;
public const int CM_XZ;
public const int CM_TERSE;
public const int CM_LZ77;
public const int CM_WAVPACK;
public const int CM_PPMD;
public const int ER_OK;
public const int ER_MULTIDISK;
public const int ER_RENAME;
public const int ER_CLOSE;
public const int ER_SEEK;
public const int ER_READ;
public const int ER_WRITE;
public const int ER_CRC;
public const int ER_ZIPCLOSED;
public const int ER_NOENT;
public const int ER_EXISTS;
public const int ER_OPEN;
public const int ER_TMPOPEN;
public const int ER_ZLIB;
public const int ER_MEMORY;
public const int ER_CHANGED;
public const int ER_COMPNOTSUPP;
public const int ER_EOF;
public const int ER_INVAL;
public const int ER_NOZIP;
public const int ER_INTERNAL;
public const int ER_INCONS;
public const int ER_REMOVE;
public const int ER_DELETED;
public const int ER_ENCRNOTSUPP;
public const int ER_RDONLY;
public const int ER_NOPASSWD;
public const int ER_WRONGPASSWD;
public const int ER_OPNOTSUPP;
public const int ER_INUSE;
public const int ER_TELL;
public const int ER_COMPRESSED_DATA;
public const int ER_CANCELLED;
public const int ER_DATA_LENGTH;
public const int ER_NOT_ALLOWED;
public const int ER_TRUNCATED_ZIP;
public const int AFL_RDONLY;
public const int AFL_IS_TORRENTZIP;
public const int AFL_WANT_TORRENTZIP;
public const int AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE;
public const int OPSYS_DOS;
public const int OPSYS_AMIGA;
public const int OPSYS_OPENVMS;
public const int OPSYS_UNIX;
public const int OPSYS_VM_CMS;
public const int OPSYS_ATARI_ST;
public const int OPSYS_OS_2;
public const int OPSYS_MACINTOSH;
public const int OPSYS_Z_SYSTEM;
public const int OPSYS_CPM;
public const int OPSYS_WINDOWS_NTFS;
public const int OPSYS_MVS;
public const int OPSYS_VSE;
public const int OPSYS_ACORN_RISC;
public const int OPSYS_VFAT;
public const int OPSYS_ALTERNATE_MVS;
public const int OPSYS_BEOS;
public const int OPSYS_TANDEM;
public const int OPSYS_OS_400;
public const int OPSYS_OS_X;
public const int OPSYS_DEFAULT;
public const int EM_NONE;
public const int EM_TRAD_PKWARE;
public const int EM_AES_128;
public const int EM_AES_192;
public const int EM_AES_256;
public const int EM_UNKNOWN;
public const string LIBZIP_VERSION;
public const int LENGTH_TO_END;
public const int LENGTH_UNCHECKED;
/* Propriedades */
public readonly int $lastId;
public readonly int $status;
public readonly int $statusSys;
public readonly int $numFiles;
public readonly string $filename;
public readonly string $comment;
/* Métodos */
public function addEmptyDir(string `$dirname`, int `$flags` = 0): bool
public function addFile(
string `$filepath`,
string `$entryname` = "",
int `$start` = 0,
int `$length` = `ZipArchive::LENGTH_TO_END`,
int `$flags` = `ZipArchive::FL_OVERWRITE`
): bool
public function addFromString(string `$name`, string `$content`, int `$flags` = `ZipArchive::FL_OVERWRITE`): bool
public function addGlob(string `$pattern`, int `$flags` = 0, array `$options` = []): array|false
public function addPattern(string `$pattern`, string `$path` = ".", array `$options` = []): array|false
public function clearError(): void
public function close(): bool
public function count(): int
public function deleteIndex(int `$index`): bool
public function deleteName(string `$name`): bool
public function extractTo(string `$pathto`, array|string|null `$files` = `null`): bool
public function getArchiveComment(int `$flags` = 0): string|false
public function getArchiveFlag(int `$flag`, int `$flags` = 0): int
public function getCommentIndex(int `$index`, int `$flags` = 0): string|false
public function getCommentName(string `$name`, int `$flags` = 0): string|false
public function getExternalAttributesIndex(
int `$index`,
int `&$opsys`,
int `&$attr`,
int `$flags` = 0
): bool
public function getExternalAttributesName(
string `$name`,
int `&$opsys`,
int `&$attr`,
int `$flags` = 0
): bool
public function getFromIndex(int `$index`, int `$len` = 0, int `$flags` = 0): string|false
public function getFromName(string `$name`, int `$len` = 0, int `$flags` = 0): string|false
public function getNameIndex(int `$index`, int `$flags` = 0): string|false
public function getStatusString(): string
public function getStream(string `$name`): resource|false
public function getStreamIndex(int `$index`, int `$flags` = 0): resource|false
public function getStreamName(string `$name`, int `$flags` = 0): resource|false
public static function isCompressionMethodSupported(int `$method`, bool `$enc` = `true`): bool
public static function isEncryptionMethodSupported(int `$method`, bool `$enc` = `true`): bool
public function locateName(string `$name`, int `$flags` = 0): int|false
public function open(string `$filename`, int `$flags` = 0): bool|int
public function registerCancelCallback(callable `$callback`): bool
public function registerProgressCallback(float `$rate`, callable `$callback`): bool
public function renameIndex(int `$index`, string `$new_name`): bool
public function renameName(string `$name`, string `$new_name`): bool
public function replaceFile(
string `$filepath`,
int `$index`,
int `$start` = 0,
int `$length` = `ZipArchive::LENGTH_TO_END`,
int `$flags` = 0
): bool
public function setArchiveComment(string `$comment`): bool
public function setArchiveFlag(int `$flag`, int `$value`): bool
public function setCommentIndex(int `$index`, string `$comment`): bool
public function setCommentName(string `$name`, string `$comment`): bool
public function setCompressionIndex(int `$index`, int `$method`, int `$compflags` = 0): bool
public function setCompressionName(string `$name`, int `$method`, int `$compflags` = 0): bool
public function setEncryptionIndex(int `$index`, int `$method`, #[\SensitiveParameter]?string `$password` = `null`): bool
public function setEncryptionName(string `$name`, int `$method`, #[\SensitiveParameter]?string `$password` = `null`): bool
public function setExternalAttributesIndex(
int `$index`,
int `$opsys`,
int `$attr`,
int `$flags` = 0
): bool
public function setExternalAttributesName(
string `$name`,
int `$opsys`,
int `$attr`,
int `$flags` = 0
): bool
public function setMtimeIndex(int `$index`, int `$timestamp`, int `$flags` = 0): bool
public function setMtimeName(string `$name`, int `$timestamp`, int `$flags` = 0): bool
public function setPassword(#[\SensitiveParameter]string `$password`): bool
public function statIndex(int `$index`, int `$flags` = 0): array|false
public function statName(string `$name`, int `$flags` = 0): array|false
public function unchangeAll(): bool
public function unchangeArchive(): bool
public function unchangeIndex(int `$index`): bool
public function unchangeName(string `$name`): bool
}

## Propriedades

lastId
  Valor do índice da última entrada adicionada (arquivo ou diretório). Disponível a partir do PHP 8.0.0 e PECL zip 1.18.0.
status
  Status do arquivo Zip. Disponível para arquivos fechados, a partir do PHP 8.0.0 e PECL zip 1.18.0.
statusSys
  Status do sistema do arquivo Zip. Disponível para arquivos fechados, a partir do PHP 8.0.0 e PECL zip 1.18.0.
numFiles
  Número de arquivos no arquivo Zip
filename
  Nome do arquivo no sistema de arquivos
comment
  Comentário para o arquivo Zip

# ZipArchive::addEmptyDir

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.8.0)

ZipArchive::addEmptyDir — Adiciona um novo diretório

### Descrição

public function ZipArchive::addEmptyDir(string `$dirname`, int `$flags` = 0): bool

Adiciona um diretório vazio no arquivo.

### Parâmetros

`dirname`
  O diretório a ser adicionado.
`flags`
  Máscara de bits consistindo de `ZipArchive::FL_ENC_GUESS`, `ZipArchive::FL_ENC_UTF_8`, `ZipArchive::FL_ENC_CP437`. O comportamento dessas constantes é descrito na página de constantes ZIP.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL zip 1.18.0 | `flags` foi adicionado.

### Exemplos

Exemplo #1 Criar um novo diretório em um arquivo

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        if($zip->addEmptyDir('newDirectory')) {
            echo 'Criado um novo diretório raiz';
        } else {
            echo 'Não foi possível criar o diretório';
        }
        $zip->close();
    } else {
        echo 'falha';
    }
    ?>

# ZipArchive::addFile

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::addFile — Adiciona um arquivo a um arquivo ZIP a partir do caminho fornecido

### Descrição

public function ZipArchive::addFile(
string `$filepath`,
string `$entryname` = "",
int `$start` = 0,
int `$length` = `ZipArchive::LENGTH_TO_END`,
int `$flags` = `ZipArchive::FL_OVERWRITE`
): bool

Adiciona um arquivo a um arquivo ZIP a partir de um caminho fornecido.

> Nota: Para portabilidade máxima, é recomendável sempre usar barras normais (`/`) como separador de diretório em nomes de arquivos ZIP.

### Parâmetros

`filepath`
  O caminho para o arquivo a ser adicionado.
`entryname`
  Se fornecido e não vazio, este é o nome local dentro do arquivo ZIP que substituirá o `filepath`.
`start`
  Para cópia parcial, posição de início.
`length`
  Para cópia parcial, comprimento a ser copiado, se `ZipArchive::LENGTH_TO_END` (0) o tamanho do arquivo é usado, se `ZipArchive::LENGTH_UNCHECKED` o arquivo inteiro é usado (a partir de `start`).
`flags`
  Máscara de bits consistindo de `ZipArchive::FL_OVERWRITE`, `ZipArchive::FL_ENC_GUESS`, `ZipArchive::FL_ENC_UTF_8`, `ZipArchive::FL_ENC_CP437`, `ZipArchive::FL_OPEN_FILE_NOW`. O comportamento dessas constantes é descrito na página de constantes ZIP.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL zip 1.18.0 | `flags` foi adicionado.
8.3.0, PECL zip 1.22.1 | `ZipArchive::FL_OPEN_FILE_NOW` foi adicionado.
8.3.0, PECL zip 1.22.2 | `ZipArchive::LENGTH_TO_END` e `ZipArchive::LENGTH_UNCHECKED` foram adicionadas.

### Exemplos

Este exemplo abre um arquivo ZIP test.zip e adiciona o arquivo /caminho/para/index.txt. como newname.txt.

Exemplo #1 Abrir e adicionar

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        $zip->addFile('/path/to/index.txt', 'newname.txt');
        $zip->close();
        echo 'ok';
    } else {
        echo 'falha';
    }
    ?>

### Notas

> Nota: Quando um arquivo é configurado para ser adicionado ao arquivo, o PHP irá bloquear o arquivo. O bloqueio é liberado apenas depois que o objeto ZipArchive foi fechado, seja via ZipArchive::close() ou o objeto ZipArchive sendo destruído. Isso pode impedir que você consiga excluir o arquivo sendo adicionado até depois que o bloqueio tenha sido liberado.

### Veja Também

- ZipArchive::replaceFile() - Substitui um arquivo no arquivo ZIP por um caminho fornecido

# ZipArchive::addFromString

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::addFromString — Adiciona um arquivo a um arquivo ZIP usando seu conteúdo

### Descrição

public function ZipArchive::addFromString(string `$name`, string `$content`, int `$flags` = `ZipArchive::FL_OVERWRITE`): bool

Adiciona um arquivo a um arquivo ZIP usando seu conteúdo.

> Nota: Para portabilidade máxima, é recomendável sempre usar barras normais (`/`) como separador de diretório em nomes de arquivos ZIP.

### Parâmetros

`name`
  O nome da entrada a ser criada.
`content`
  O conteúdo a ser usado para criar a entrada. É usado em um modo binário seguro.
`flags`
  Máscara de bits consistindo de `ZipArchive::FL_OVERWRITE`, `ZipArchive::FL_ENC_GUESS`, `ZipArchive::FL_ENC_UTF_8`, `ZipArchive::FL_ENC_CP437`. O comportamento dessas constantes é descrito na página de constantes ZIP.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL zip 1.18.0 | `flags` foi adicionado.

### Exemplos

Exemplo #1 Adicionar uma entrada a um novo arquivo

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFromString('test.txt', 'file content goes here');
        $zip->close();
        echo 'ok';
    } else {
        echo 'falha';
    }
    ?>

Exemplo #2 Adicionar arquivo a um diretório dentro de um arquivo

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        $zip->addFromString('dir/test.txt', 'file content goes here');
        $zip->close();
        echo 'ok';
    } else {
        echo 'falha';
    }
    ?>

# ZipArchive::addGlob

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL zip >= 1.9.0)

ZipArchive::addGlob — Adicionar arquivos de um diretório por padrão glob

### Descrição

public function ZipArchive::addGlob(string `$pattern`, int `$flags` = 0, array `$options` = []): array|false

Adiciona arquivos de um diretório que correspondem ao `pattern` glob.

> Nota: Para portabilidade máxima, é recomendável sempre usar barras normais (`/`) como separador de diretório em nomes de arquivos ZIP.

### Parâmetros

`pattern`
  Um padrão glob() contra o qual os arquivos serão correspondidos.
`flags`
  Uma máscara de bits de opções `glob()`.
`options`

  Um array associativo de opções. As opções disponíveis são:

  - `"add_path"` Prefixo a ser adicionado ao traduzir para o caminho local do arquivo dentro do arquivo. Isso é aplicado após quaisquer operações de remoção definidas pelas opções `"remove_path"` ou `"remove_all_path"`.
  - `"remove_path"` Prefixo a ser removido dos caminhos de arquivo correspondentes antes de serem adicionados ao arquivo.
  - `"remove_all_path"` `true` para usar apenas o nome do arquivo e adicionar à raiz do arquivo.
  - `"flags"` Máscara de bits consistindo em `ZipArchive::FL_OVERWRITE`, `ZipArchive::FL_ENC_GUESS`, `ZipArchive::FL_ENC_UTF_8`, `ZipArchive::FL_ENC_CP437`, `ZipArchive::FL_OPEN_FILE_NOW`. O comportamento dessas constantes é descrito na página de constantes ZIP.
  - `"comp_method"` Método de compressão, uma das constantes `ZipArchive::CM_*`,
  - `"comp_flags"` Nível de compressão.
  - `"enc_method"` Método de criptografia, um dos constantes `ZipArchive::EM_*`.
  - `"enc_password"` Senha usada para criptografia.

### Valor Retornado

Um array de arquivos adicionados em caso de sucesso ou `false` em caso de falha

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL zip 1.18.0 | `"flags"` em `options` foi adicionado.
8.0.0, PECL zip 1.18.1 | `"comp_method"`, `"comp_flags"`, `"enc_method"` e `"enc_password"` em `options` foram adicionados.
8.3.0, PECL zip 1.22.1 | `ZipArchive::FL_OPEN_FILE_NOW` foi adicionado.

### Exemplos

Exemplo #1 Exemplo de ZipArchive::addGlob()

Adiciona todos os scripts php e arquivos de texto do diretório de trabalho atual

    <?php
    $zip = new ZipArchive();
    $ret = $zip->open('application.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE);
    if ($ret !== TRUE) {
        printf('Falha com código %d', $ret);
    } else {
        $options = array('add_path' => 'sources/', 'remove_all_path' => TRUE);
        $zip->addGlob('*.{php,txt}', GLOB_BRACE, $options);
        $zip->close();
    }
    ?>

### Veja Também

- ZipArchive::addFile() - Adiciona um arquivo a um arquivo ZIP a partir do caminho fornecido
- ZipArchive::addPattern() - Adiciona arquivos de um diretório por padrão PCRE

# ZipArchive::addPattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL zip >= 1.9.0)

ZipArchive::addPattern — Adiciona arquivos de um diretório por padrão PCRE

### Descrição

public function ZipArchive::addPattern(string `$pattern`, string `$path` = ".", array `$options` = []): array|false

Adiciona arquivos de um diretório que correspondem à expressão regular `pattern`. A operação não é recursiva. O padrão será correspondido apenas ao nome do arquivo.

### Parâmetros

`pattern`
  Uma expressão regular PCRE com a qual os arquivos serão correspondidos.
`path`
  O diretório que será examinado. O padrão é o diretório de trabalho atual.
`options`
  Um array associativo de opções aceitas por ZipArchive::addGlob().

### Valor Retornado

Um array de arquivos adicionados em caso de sucesso ou `false` em caso de falha

### Exemplos

Exemplo #1 Exemplo de ZipArchive::addPattern()

Adiciona todos os scripts php e arquivos de texto do diretório atual

    <?php
    $zip = new ZipArchive();
    $ret = $zip->open('application.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE);
    if ($ret !== TRUE) {
        printf('Falha com código %d', $ret);
    } else {
        $directory = realpath('.');
        $options = array('add_path' => 'sources/', 'remove_path' => $directory);
        $zip->addPattern('/\.(?:php|txt)$/', $directory, $options);
        $zip->close();
    }
    ?>

### Veja Também

- ZipArchive::addFile() - Adiciona um arquivo a um arquivo ZIP a partir do caminho fornecido
- ZipArchive::addGlob() - Adicionar arquivos de um diretório por padrão glob

# ZipArchive::clearError

(PHP 8 >= 8.2.0, PECL zip >= 1.20.0)

ZipArchive::clearError — Limpa a mensagem de erro de status, mensagens do sistema e/ou do zip

### Descrição

public function ZipArchive::clearError(): void

Limpa a mensagem de erro de status, mensagens do sistema e/ou do zip.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

### Veja Também

- ZipArchive::getStatusString() - Retorna a mensagem de erro de status, mensagens do sistema e/ou zip

# ZipArchive::close

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::close — Fecha o arquivo de arquivo ativo (aberto ou recém-criado)

### Descrição

public function ZipArchive::close(): bool

Fecha o arquivo aberto ou criado e salva as alterações. Este método é chamado automaticamente no final do script.

Se o arquivo não contiver arquivos, o arquivo é completamente removido por padrão (nenhum arquivo vazio é gravado) de acordo com o valor do `ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE` global flag.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ZipArchive::setArchiveFlag() - Define uma opção global de um arquivo ZIP

# ZipArchive::count

(PHP 7 >= 7.2.0, PHP 8, PECL zip >= 1.15.0)

ZipArchive::count — Conta o número de arquivos no arquivo

### Descrição

public function ZipArchive::count(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número de arquivos no arquivo.

# ZipArchive::deleteIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::deleteIndex — Exclui uma entrada no arquivo usando seu índice

### Descrição

public function ZipArchive::deleteIndex(int `$index`): bool

Exclui uma entrada no arquivo usando seu índice.

### Parâmetros

`index`
  Índice da entrada a ser excluída.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Excluir arquivo do arquivo usando seu índice

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        $zip->deleteIndex(2);
        $zip->close();
        echo 'ok';
    } else {
        echo 'falha';
    }
    ?>

# ZipArchive::deleteName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::deleteName — Exclui uma entrada no arquivo usando seu nome

### Descrição

public function ZipArchive::deleteName(string `$name`): bool

Exclui uma entrada no arquivo usando seu nome.

### Parâmetros

`name`
  Nome da entrada a ser excluída.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Excluindo um arquivo e diretório de um arquivo, usando nomes

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test1.zip') === TRUE) {
        $zip->deleteName('testfromfile.php');
        $zip->deleteName('testDir/');
        $zip->close();
        echo 'ok';
    } else {
        echo 'falha';
    }
    ?>

# ZipArchive::extractTo

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::extractTo — Extrai o conteúdo do arquivo

### Descrição

public function ZipArchive::extractTo(string `$pathto`, array|string|null `$files` = `null`): bool

Extrai o arquivo completo ou os arquivos fornecidos para o destino especificado.

Aviso

As permissões padrão para os arquivos e diretórios extraídos dão o acesso mais amplo possível. Isso pode ser restrito configurando o umask atual, que pode ser alterado usando umask().

Por motivos de segurança, as permissões originais não são restauradas. Para um exemplo de como restaurá-las, consulte o exemplo de código na página ZipArchive::getExternalAttributesIndex().

### Parâmetros

`pathto`
  Local para onde extrair os arquivos.
`files`
  As entradas para extrair. Aceita um único nome de entrada ou um array de nomes.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Extrair todas as entradas

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        $zip->extractTo('/my/destination/dir/');
        $zip->close();
        echo 'ok';
    } else {
        echo 'falha';
    }
    ?>

Exemplo #2 Extrair duas entradas

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test_im.zip');
    if ($res === TRUE) {
        $zip->extractTo('/my/destination/dir/', array('pear_item.gif', 'testfromfile.php'));
        $zip->close();
        echo 'ok';
    } else {
        echo 'falha';
    }
    ?>

### Notas

> Nota: O sistema de arquivos NTFS do Windows não suporta alguns caracteres em nomes de arquivos, como `<|>*?":`. Nomes de arquivos que terminam com ponto também não são suportados. Ao contrário de algumas ferramentas de extração, este método não substitui estes caracteres por um sublinhado, mas falha ao extrair esses arquivos.

# ZipArchive::getArchiveComment

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getArchiveComment — Retorna o comentário do arquivo Zip

### Descrição

public function ZipArchive::getArchiveComment(int `$flags` = 0): string|false

Retorna o comentário do arquivo Zip.

### Parâmetros

`flags`
  Se a opção estiver definida como `ZipArchive::FL_UNCHANGED`, o comentário original e não alterado é retornado.

### Valor Retornado

Retorna o comentário do arquivo Zip ou `false` em caso de falha.

### Exemplos

Exemplo #1 Imprimir um comentário de arquivo

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test_with_comment.zip');
    if ($res === TRUE) {
        var_dump($zip->getArchiveComment());
        /* Ou usando a propriedade do arquivo */
        var_dump($zip->comment);
    } else {
        echo 'falha, código:' . $res;
    }
    ?>

# ZipArchive::getArchiveFlag

(PHP >= 8.3.0, PECL zip >= 1.22.0)

ZipArchive::getArchiveFlag — Retorna o valor de uma opção global do arquivo Zip

### Descrição

public function ZipArchive::getArchiveFlag(int `$flag`, int `$flags` = 0): int

Retorna o valor de uma opção global do arquivo Zip.

### Parâmetros

`flag`

  A opção global a ser recuperada, entre as constantes `AFL_*`:

  - `ZipArchive::AFL_RDONLY`
  - `ZipArchive::AFL_IS_TORRENTZIP`
  - `ZipArchive::AFL_WANT_TORRENTZIP`
  - `ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE`
`flags`
  Se o parâmetro `flags` estiver definido como `ZipArchive::FL_UNCHANGED`, a opção original inalterada é retornada.

### Valor Retornado

Retorna 1 se a opção estiver definida para o arquivo, 0 se não estiver, e -1 se ocorrer um erro.

### Exemplos

Exemplo #1 Testar se o arquivo é um formato torrentzip

    <?php

    $zip = new ZipArchive();
    $res = $zip->open('test.zip');

    if ($res === true) {
        var_dump($zip->getArchiveFlag(ZipArchive::AFL_IS_TORRENTZIP));
    } else {
        echo 'falha, código: ' . $res;
    }

    ?>

### Veja Também

- ZipArchive::setArchiveFlag() - Define uma opção global de um arquivo ZIP

# ZipArchive::getCommentIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::getCommentIndex — Retorna o comentário de uma entrada usando o índice da entrada

### Descrição

public function ZipArchive::getCommentIndex(int `$index`, int `$flags` = 0): string|false

Retorna o comentário de uma entrada usando o índice da entrada.

### Parâmetros

`index`
  Índice da entrada
`flags`
  Se flags estiver definido como `ZipArchive::FL_UNCHANGED`, o comentário original e não alterado é retornado.

### Valor Retornado

Retorna o comentário em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Imprimir o comentário de uma entrada

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test1.zip');
    if ($res === TRUE) {
        var_dump($zip->getCommentIndex(1));
    } else {
        echo 'falha, código:' . $res;
    }
    ?>

# ZipArchive::getCommentName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::getCommentName — Retorna o comentário de uma entrada usando o nome da entrada

### Descrição

public function ZipArchive::getCommentName(string `$name`, int `$flags` = 0): string|false

Retorna o comentário de uma entrada usando o nome da entrada.

### Parâmetros

`name`
  Nome da entrada
`flags`
  Se flags estiver definido como `ZipArchive::FL_UNCHANGED`, o comentário original e não alterado é retornado.

### Valor Retornado

Retorna o comentário em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Imprime o comentário de uma entrada

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test1.zip');
    if ($res === TRUE) {
        var_dump($zip->getCommentName('test/entry1.txt'));
    } else {
        echo 'falha, código:' . $res;
    }
    ?>

# ZipArchive::getExternalAttributesIndex

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::getExternalAttributesIndex — Recupera os atributos externos de uma entrada definida pelo seu índice

### Descrição

public function ZipArchive::getExternalAttributesIndex(
int `$index`,
int `&$opsys`,
int `&$attr`,
int `$flags` = 0
): bool

Recupera os atributos externos de uma entrada definida pelo seu índice.

### Parâmetros

`index`
  Índice da entrada.
`opsys`
  Em caso de sucesso, recebe o código do sistema operacional definido por uma das constantes ZipArchive::OPSYS_.
`attr`
  Em caso de sucesso, recebe os atributos externos. O valor depende do sistema operacional.
`flags`
  Se flags estiver definido como `ZipArchive::FL_UNCHANGED`, os atributos originais inalterados são retornados.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Este exemplo extrai todas as entradas de um arquivo ZIP test.zip e define os direitos Unix a partir dos atributos externos.

Exemplo #1 Extrair todas as entradas com direitos Unix

    <?php
    $zip = new ZipArchive();
    if ($zip->open('test.zip') === TRUE) {
        for ($idx=0 ; $s = $zip->statIndex($idx) ; $idx++) {
            if ($zip->extractTo('.', $s['name'])) {
                if ($zip->getExternalAttributesIndex($idx, $opsys, $attr)
                    && $opsys==ZipArchive::OPSYS_UNIX) {
                   chmod($s['name'], ($attr >> 16) & 0777);
                }
            }
        }
        $zip->close();
        echo "Ok\n";
    } else {
        echo "KO\n";
    }
    ?>

# ZipArchive::getExternalAttributesName

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::getExternalAttributesName — Recupera os atributos externos de uma entrada definida pelo seu nome

### Descrição

public function ZipArchive::getExternalAttributesName(
string `$name`,
int `&$opsys`,
int `&$attr`,
int `$flags` = 0
): bool

Recupera os atributos externos de uma entrada definida pelo seu nome.

### Parâmetros

`name`
  Nome da entrada.
`opsys`
  Em caso de sucesso, recebe o código do sistema operacional definido por uma das constantes ZipArchive::OPSYS_.
`attr`
  Em caso de sucesso, recebe os atributos externos. O valor depende do sistema operacional.
`flags`
  Se flags estiver definido como `ZipArchive::FL_UNCHANGED`, os atributos originais inalterados são retornados.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# ZipArchive::getFromIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getFromIndex — Retorna o conteúdo da entrada usando seu índice

### Descrição

public function ZipArchive::getFromIndex(int `$index`, int `$len` = 0, int `$flags` = 0): string|false

Retorna o conteúdo da entrada usando seu índice.

### Parâmetros

`index`
  Índice da entrada
`len`
  O comprimento a ser lido da entrada. Se `0`, então a entrada inteira é lida.
`flags`

  As opções a serem usadas para abrir o arquivo. Os seguintes valores podem ser ORed a ele.

  - `ZipArchive::FL_UNCHANGED`
  - `ZipArchive::FL_COMPRESSED`

### Valor Retornado

Retorna o conteúdo da entrada em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Obter o conteúdo do arquivo

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        echo $zip->getFromIndex(2);
        $zip->close();
    } else {
        echo 'falha';
    }
    ?>

### Veja Também

- ZipArchive::getFromName() - Retorna o conteúdo da entrada usando seu nome

# ZipArchive::getFromName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getFromName — Retorna o conteúdo da entrada usando seu nome

### Descrição

public function ZipArchive::getFromName(string `$name`, int `$len` = 0, int `$flags` = 0): string|false

Retorna o conteúdo da entrada usando seu nome.

### Parâmetros

`name`
  Nome da entrada
`len`
  O comprimento a ser lido da entrada. Se `0`, então a entrada inteira é lida.
`flags`

  As opções a serem usadas para encontrar a entrada. Os seguintes valores podem ser ORed.

  - `ZipArchive::FL_UNCHANGED`
  - `ZipArchive::FL_COMPRESSED`
  - `ZipArchive::FL_NOCASE`

### Valor Retornado

Retorna o conteúdo da entrada em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Obter o conteúdo do arquivo

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test1.zip') === TRUE) {
        echo $zip->getFromName('testfromfile.php');
        $zip->close();
    } else {
        echo 'falha';
    }
    ?>

Exemplo #2 Converter uma imagem de uma entrada zip

    <?php
    $z = new ZipArchive();
    if ($z->open(dirname(__FILE__) . '/test_im.zip')) {
        $im_string = $z->getFromName("pear_item.gif");
        $im = imagecreatefromstring($im_string);
        imagepng($im, 'b.png');
    }
    ?>

### Veja Também

- ZipArchive::getFromIndex() - Retorna o conteúdo da entrada usando seu índice

# ZipArchive::getNameIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::getNameIndex — Retorna o nome de uma entrada usando seu índice

### Descrição

public function ZipArchive::getNameIndex(int `$index`, int `$flags` = 0): string|false

Retorna o nome de uma entrada usando seu índice.

### Parâmetros

`index`
  Índice da entrada.
`flags`
  Se flags estiver definido como `ZipArchive::FL_UNCHANGED`, o nome original inalterado é retornado.

### Valor Retornado

Retorna o nome em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de ZipArchive::getNameIndex()

    <?php
    if ($zip->open('test.zip') == TRUE) {
     for ($i = 0; $i < $zip->numFiles; $i++) {
         $filename = $zip->getNameIndex($i);
         // ...
     }
    }
    ?>

# ZipArchive::getStatusString

(PHP 5 >= 5.2.7, PHP 7, PHP 8)

ZipArchive::getStatusString — Retorna a mensagem de erro de status, mensagens do sistema e/ou zip

### Descrição

public function ZipArchive::getStatusString(): string

Retorna a mensagem de erro de status, mensagens do sistema e/ou zip.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string com a mensagem de status.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL zip 1.18.0 | Este método pode ser chamado em um arquivo fechado.
8.0.0, PECL zip 1.18.0 | Este método não retorna mais `false` em caso de falha.

# ZipArchive::getStream

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getStream — Obtém um manipulador de arquivo para a entrada definida pelo seu nome (somente leitura)

### Descrição

public function ZipArchive::getStream(string `$name`): resource|false

Obtém um manipulador de arquivo para a entrada definida pelo seu nome. Por enquanto, suporta apenas operações de leitura.

### Parâmetros

`name`
  O nome da entrada a ser usado.

### Valor Retornado

Retorna um ponteiro de arquivo (recurso) em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Obter o conteúdo da entrada com fread() e armazená-lo

    <?php
    $contents = '';
    $z = new ZipArchive();
    if ($z->open('test.zip')) {
        $fp = $z->getStream('test');
        if(!$fp) exit("falha\n");

        while (!feof($fp)) {
            $contents .= fread($fp, 2);
        }

        fclose($fp);
        file_put_contents('t',$contents);
        echo "pronto.\n";
    }
    ?>

Exemplo #2 Mesmo que o exemplo anterior, mas com fopen() e o empacotador de fluxo zip

    <?php
    $contents = '';
    $fp = fopen('zip://' . dirname(__FILE__) . '/test.zip#test', 'r');
    if (!$fp) {
        exit("não foi possível abrir\n");
    }
    while (!feof($fp)) {
        $contents .= fread($fp, 2);
    }
    echo "$contents\n";
    fclose($fp);
    echo "pronto.\n";
    ?>

Exemplo #3 Empacotador de fluxo e imagem, pode ser usado também com a função xml

    <?php
    $im = imagecreatefromgif('zip://' . dirname(__FILE__) . '/test_im.zip#pear_item.gif');
    imagepng($im, 'a.png');
    ?>

### Veja Também

- ZipArchive::getStreamIndex() - Obtém um manipulador de arquivo para a entrada definida pelo seu índice (somente leitura)
- ZipArchive::getStreamName() - Obtém um manipulador de arquivo para a entrada definida pelo seu nome (somente leitura)
- Fluxos de Compressão

# ZipArchive::getStreamIndex

(PHP 8 >= 8.2.0, PECL zip >= 1.20.0)

ZipArchive::getStreamIndex — Obtém um manipulador de arquivo para a entrada definida pelo seu índice (somente leitura)

### Descrição

public function ZipArchive::getStreamIndex(int `$index`, int `$flags` = 0): resource|false

Obtenha um manipulador de arquivo para a entrada definida pelo seu índice. Por enquanto, suporta apenas operações de leitura.

### Parâmetros

`index`
  Índice da entrada
`flags`
  Se flags estiver definido como `ZipArchive::FL_UNCHANGED`, o fluxo original inalterado é retornado.

### Valor Retornado

Retorna um ponteiro de arquivo (recurso) em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Obtém o conteúdo da entrada com fread() e armazená-lo

    <?php
    $contents = '';
    $z = new ZipArchive();
    if ($z->open('test.zip')) {
        $fp = $z->getStreamIndex(1, ZipArchive::FL_UNCHANGED);
        if(!$fp) die($z->getStatusString());

        echo stream_get_contents($fp);

        fclose($fp);
    }
    ?>

### Veja Também

- ZipArchive::getStreamName() - Obtém um manipulador de arquivo para a entrada definida pelo seu nome (somente leitura)

# ZipArchive::getStreamName

(PHP 8 >= 8.2.0, PECL zip >= 1.20.0)

ZipArchive::getStreamName — Obtém um manipulador de arquivo para a entrada definida pelo seu nome (somente leitura)

### Descrição

public function ZipArchive::getStreamName(string `$name`, int `$flags` = 0): resource|false

Obtém um manipulador de arquivo para a entrada definida pelo seu nome. Por enquanto, suporta apenas operações de leitura.

### Parâmetros

`name`
  O nome da entrada a ser usado.
`flags`
  Se flags estiver definido como `ZipArchive::FL_UNCHANGED`, o fluxo original inalterado é retornado.

### Valor Retornado

Retorna um ponteiro de arquivo (recurso) em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Obtém o conteúdo da entrada com fread() e armazená-lo

    <?php
    $contents = '';
    $z = new ZipArchive();
    if ($z->open('test.zip')) {
        $fp = $z->getStreamName('test', ZipArchive::FL_UNCHANGED);
        if(!$fp) die($z->getStatusString());

        echo stream_get_contents($fp);

        fclose($fp);
    }
    ?>

### Veja Também

- ZipArchive::getStreamIndex() - Obtém um manipulador de arquivo para a entrada definida pelo seu índice (somente leitura)

# ZipArchive::isCompressionMethodSupported

(PHP >= 8.0.0, PECL zip >= 1.19.0)

ZipArchive::isCompressionMethodSupported — Verifica se um método de compressão é suportado pelo libzip

### Descrição

public static function ZipArchive::isCompressionMethodSupported(int `$method`, bool `$enc` = `true`): bool

Verifica se um método de compressão é suportado pelo libzip.

### Parâmetros

`method`
  O método de compressão, uma das constantes `ZipArchive::CM_*`.
`enc`
  Se `true`, verifica a compressão; caso contrário, verifica a descompressão.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Notas

> Nota: Esta função está disponível apenas se compilada contra libzip ≥ 1.7.0.

### Veja Também

- ZipArchive::setCompressionIndex() - Define o método de compressão de uma entrada definida pelo seu índice
- ZipArchive::setCompressionName() - Define o método de compressão de uma entrada definida pelo seu nome

# ZipArchive::isEncryptionMethodSupported

(PHP >= 8.0.0, PECL zip >= 1.19.0)

ZipArchive::isEncryptionMethodSupported — Verifica se um método de criptografia é suportado pelo libzip

### Descrição

public static function ZipArchive::isEncryptionMethodSupported(int `$method`, bool `$enc` = `true`): bool

Verifica se um método de criptografia é suportado pelo libzip.

### Parâmetros

`method`
  O método de criptografia, uma das constantes `ZipArchive::EM_*`.
`enc`
  Se `true`, verifica a criptografia; caso contrário, verifica a descriptografia.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Notas

> Nota: Esta função está disponível apenas se compilada com libzip ≥ 1.7.0.

### Veja Também

- ZipArchive::setEncryptionIndex() - Define o método de criptografia de uma entrada definida pelo seu índice
- ZipArchive::setEncryptionName() - Define o método de criptografia de uma entrada definida pelo seu nome

# ZipArchive::locateName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::locateName — Retorna o índice da entrada no arquivo compactado

### Descrição

public function ZipArchive::locateName(string `$name`, int `$flags` = 0): int|false

Localiza uma entrada usando seu nome.

### Parâmetros

`name`
  O nome da entrada a ser procurada
`flags`

  As opções são especificadas através da operação OR nos seguintes valores, ou 0 para nenhum deles.

  - `ZipArchive::FL_NOCASE`
  - `ZipArchive::FL_NODIR`

### Valor Retornado

Retorna o índice da entrada em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Criar um arquivo compactado e em seguida usá-lo com ZipArchive::locateName()

    <?php
    $file = 'testlocate.zip';

    $zip = new ZipArchive;
    if ($zip->open($file, ZipArchive::CREATE) !== TRUE) {
        exit('falha');
    }

    $zip->addFromString('entry1.txt', 'entry #1');
    $zip->addFromString('entry2.txt', 'entry #2');
    $zip->addFromString('dir/entry2d.txt', 'entry #2');

    if ($zip->status !== ZipArchive::ER_OK) {
        echo "falha ao escrever zip\n";
    }
    $zip->close();

    if ($zip->open($file) !== TRUE) {
        exit('falha');
    }

    echo $zip->locateName('entry1.txt') . "\n";
    echo $zip->locateName('eNtry2.txt') . "\n";
    echo $zip->locateName('eNtry2.txt', ZipArchive::FL_NOCASE) . "\n";
    echo $zip->locateName('enTRy2d.txt', ZipArchive::FL_NOCASE|ZipArchive::FL_NODIR) . "\n";
    $zip->close();

    ?>

O exemplo acima produzirá:

    0

    1
    2

# ZipArchive::open

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::open — Abre um arquivo compactado ZIP

### Descrição

public function ZipArchive::open(string `$filename`, int `$flags` = 0): bool|int

Abre um arquivo compactado ZIP novo ou existente para leitura, escrita ou modificação.

Desde o libzip 1.6.0, um arquivo vazio não é mais um arquivo compactado válido.

### Parâmetros

`filename`
  O nome do arquivo compactado ZIP a ser aberto.
`flags`

  O modo a ser usado para abrir o arquivo compactado.

  - `ZipArchive::OVERWRITE`
  - `ZipArchive::CREATE`
  - `ZipArchive::RDONLY`
  - `ZipArchive::EXCL`
  - `ZipArchive::CHECKCONS`

### Valor Retornado

Retorna `true` em caso de sucesso, `false` ou um dos seguintes códigos de erro em caso de falha:

`ZipArchive::ER_EXISTS`
  Arquivo já existe.
`ZipArchive::ER_INCONS`
  Arquivo compactado inconsistente.
`ZipArchive::ER_INVAL`
  Argumento inválido.
`ZipArchive::ER_MEMORY`
  Falha ao alocar memória.
`ZipArchive::ER_NOENT`
  Arquivo não encontrado.
`ZipArchive::ER_NOZIP`
  Não é um arquivo compactado ZIP.
`ZipArchive::ER_OPEN`
  Não é possível abrir o arquivo.
`ZipArchive::ER_READ`
  Erro de leitura.
`ZipArchive::ER_SEEK`
  Erro de busca.

### Exemplos

Exemplo #1 Abrir e extrair

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        echo 'ok';
        $zip->extractTo('test');
        $zip->close();
    } else {
        echo 'falha, código:' . $res;
    }
    ?>

Exemplo #2 Cria um arquivo

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFromString('test.txt', 'o conteúdo do arquivo vai aqui');
        $zip->addFile('data.txt', 'entryname.txt');
        $zip->close();
        echo 'ok';
    } else {
        echo 'falhou';
    }
    ?>

Exemplo #3 Cria um arquivo temporário

    <?php
    $name = tempnam(sys_get_temp_dir(), "FOO");
    $zip = new ZipArchive;
    $res = $zip->open($name, ZipArchive::OVERWRITE); /* truncar pois um arquivo vazio não é válido */
    if ($res === TRUE) {
        $zip->addFile('data.txt', 'nomedaentrada.txt');
        $zip->close();
        echo 'ok';
    } else {
        echo 'falhou';
    }
    ?>

# ZipArchive::registerCancelCallback

(PHP >= 8.0.0, PECL zip >= 1.17.0)

ZipArchive::registerCancelCallback — Registra um callback para permitir o cancelamento durante o fechamento do arquivo compactado.

### Descrição

public function ZipArchive::registerCancelCallback(callable `$callback`): bool

Registra uma função de `callback` para permitir o cancelamento durante o fechamento do arquivo compactado.

### Parâmetros

`callback`
  Se esta função retornar 0, a operação continuará; qualquer outro valor resultará no cancelamento.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Este exemplo cria um arquivo compactado ZIP php.zip e cancela a operação em algumas condições de execução.

Exemplo #1 Arquivar um arquivo

    <?php
    $zip = new ZipArchive();
    if ($zip->open('php.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE)) {
        $zip->addFile(PHP_BINARY, 'php');
        $zip->registerCancelCallback(function () {
            return ($someruncondition ? -1 : 0);
        });
        $zip->close();
    }

### Notas

> Nota: Esta função só está disponível se for construída com libzip ≥ 1.6.0.

### Veja Também

- ZipArchive::registerProgressCallback() - Registrar um callback para fornecer atualizações durante o fechamento do arquivo compactado.

# ZipArchive::registerProgressCallback

(PHP >= 8.0.0, PECL zip >= 1.17.0)

ZipArchive::registerProgressCallback — Registrar um callback para fornecer atualizações durante o fechamento do arquivo compactado.

### Descrição

public function ZipArchive::registerProgressCallback(float `$rate`, callable `$callback`): bool

Registra uma função de `callback` para fornecer atualizações durante o fechamento do arquivo compactado.

### Parâmetros

`rate`
  Alteração entre cada chamada do retorno de chamada (de 0.0 a 1.0).
`callback`
  Esta função receberá o `state` atual como um float (de 0.0 a 1.0).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Este exemplo cria um arquivo compactado ZIP php.zip e mostra a progressão.

Exemplo #1 Archive a file

    $zip = new ZipArchive();
    if ($zip->open('php.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE)) {
        $zip->addFile(PHP_BINARY, 'php');
        $zip->registerProgressCallback(0.05, function ($r) {
            printf("%d%%\n", $r * 100);
        });
        $zip->close();
    }

### Notas

> Nota: Esta função só está disponível se for construída com libzip ≥ 1.3.0.

### Veja Também

- ZipArchive::registerCancelCallback() - Registra um callback para permitir o cancelamento durante o fechamento do arquivo compactado.

# ZipArchive::renameIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::renameIndex — Renomeia uma entrada definida pelo seu índice

### Descrição

public function ZipArchive::renameIndex(int `$index`, string `$new_name`): bool

Renomeia uma entrada definida pelo seu índice.

### Parâmetros

`index`
  Índice da entrada a ser renomeada.
`new_name`
  Novo nome.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Renomear uma entrada

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        $zip->renameIndex(2,'newname.txt');
        $zip->close();
    } else {
        echo 'falha, código:' . $res;
    }
    ?>

# ZipArchive::renameName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::renameName — Renomeia uma entrada definida pelo seu nome

### Descrição

public function ZipArchive::renameName(string `$name`, string `$new_name`): bool

Renomeia uma entrada definida pelo seu nome.

### Parâmetros

`name`
  Nome da entrada a ser renomeada.
`new_name`
  Novo nome.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Renomear uma entrada

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        $zip->renameName('currentname.txt','newname.txt');
        $zip->close();
    } else {
        echo 'falha, código:' . $res;
    }
    ?>

# ZipArchive::replaceFile

(PHP >= 8.0.0, PECL zip >= 1.18.0)

ZipArchive::replaceFile — Substitui um arquivo no arquivo ZIP por um caminho fornecido

### Descrição

public function ZipArchive::replaceFile(
string `$filepath`,
int `$index`,
int `$start` = 0,
int `$length` = `ZipArchive::LENGTH_TO_END`,
int `$flags` = 0
): bool

Substitui um arquivo no arquivo ZIP por um caminho fornecido.

> Nota: Para portabilidade máxima, é recomendável sempre usar barras normais (`/`) como separador de diretório em nomes de arquivos ZIP.

### Parâmetros

`filepath`
  O caminho para o arquivo a ser adicionado.
`index`
  O índice do arquivo a ser substituído, seu nome não é alterado.
`start`
  Para cópia parcial, posição inicial.
`length`
  Para cópia parcial, comprimento a ser copiado, se `ZipArchive::LENGTH_TO_END` (0), o tamanho do arquivo é usado, se `ZipArchive::LENGTH_UNCHECKED`, o arquivo inteiro é usado (a partir de `start`).
`flags`
  Máscara de bits consistindo em `ZipArchive::FL_ENC_GUESS`, `ZipArchive::FL_ENC_UTF_8`, `ZipArchive::FL_ENC_CP437`, `ZipArchive::FL_OPEN_FILE_NOW`. O comportamento dessas constantes é descrito na página constantes do ZIP.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0, PECL zip 1.22.1 | `ZipArchive::FL_OPEN_FILE_NOW` foi adicionado.
8.3.0, PECL zip 1.22.2 | `ZipArchive::LENGTH_TO_END` e `ZipArchive::LENGTH_UNCHECKED` foram adicionados.

### Exemplos

Este exemplo abre um arquivo ZIP test.zip e substitui a entrada do índice 1 pelo arquivo /path/to/index.txt.

Exemplo #1 Abrir e substituir

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        $zip->replaceFile('/path/to/index.txt', 1);
        $zip->close();
        echo 'ok';
    } else {
        echo 'falha';
    }
    ?>

### Veja Também

- ZipArchive::addFile() - Adiciona um arquivo a um arquivo ZIP a partir do caminho fornecido

# ZipArchive::setArchiveComment

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setArchiveComment — Define o comentário de um arquivo ZIP

### Descrição

public function ZipArchive::setArchiveComment(string `$comment`): bool

Define o comentário de um arquivo ZIP.

### Parâmetros

`comment`
  O conteúdo do comentário.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Criar um arquivo e definir um comentário

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFromString('test.txt', 'file content goes here');
        $zip->setArchiveComment('new archive comment');
        $zip->close();
        echo 'ok';
    } else {
        echo 'falha';
    }
    ?>

# ZipArchive::setArchiveFlag

(PHP >= 8.3.0, PECL zip >= 1.22.0)

ZipArchive::setArchiveFlag — Define uma opção global de um arquivo ZIP

### Descrição

public function ZipArchive::setArchiveFlag(int `$flag`, int `$value`): bool

Define uma opção global de um arquivo ZIP.

### Parâmetros

`flag`

  A opção global a ser alterada, entre as constantes `AFL_*`.

  - `ZipArchive::AFL_WANT_TORRENTZIP`
  - `ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE`
`value`
  O novo valor da opção.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Criar um arquivo torrentzip

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->setArchiveFlag(ZipArchive::AFL_WANT_TORRENTZIP, 1);
        $zip->addFromString('test.txt', 'file content goes here');
        $zip->close();
        echo 'ok';
    } else {
        echo 'falha';
    }
    ?>

### Veja Também

- ZipArchive::getArchiveFlag() - Retorna o valor de uma opção global do arquivo Zip

# ZipArchive::setCommentIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setCommentIndex — Define o comentário de uma entrada definida pelo seu índice

### Descrição

public function ZipArchive::setCommentIndex(int `$index`, string `$comment`): bool

Define o comentário de uma entrada definida pelo seu índice.

### Parâmetros

`index`
  Índice da entrada.
`comment`
  O conteúdo do comentário.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Abrir um arquivo e definir um comentário para uma entrada

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        $zip->setCommentIndex(2, 'new entry comment');
        $zip->close();
        echo 'ok';
    } else {
        echo 'falha';
    }
    ?>

# ZipArchive::setCommentName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setCommentName — Define o comentário de uma entrada definida pelo seu nome

### Descrição

public function ZipArchive::setCommentName(string `$name`, string `$comment`): bool

Define o comentário de uma entrada definida pelo seu nome.

### Parâmetros

`name`
  Nome da entrada.
`comment`
  O conteúdo do comentário.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Abrir um arquivo e definir um comentário para uma entrada

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        $zip->setCommentName('entry1.txt', 'new entry comment');
        $zip->close();
        echo 'ok';
    } else {
        echo 'falha';
    }
    ?>

# ZipArchive::setCompressionIndex

(PHP 7, PHP 8, PECL zip >= 1.13.0)

ZipArchive::setCompressionIndex — Define o método de compressão de uma entrada definida pelo seu índice

### Descrição

public function ZipArchive::setCompressionIndex(int `$index`, int `$method`, int `$compflags` = 0): bool

Define o método de compressão de uma entrada definida pelo seu índice.

### Parâmetros

`index`
  Índice da entrada.
`method`
  O método de compressão, uma das constantes `ZipArchive::CM_*`.
`compflags`
  Nível de compressão.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Adicionar arquivos com diferentes métodos de compressão a um arquivo

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFromString('foo', 'Some text');
        $zip->addFromString('bar', 'Some other text');
        $zip->setCompressionIndex(0, ZipArchive::CM_STORE);
        $zip->setCompressionIndex(1, ZipArchive::CM_DEFLATE);
        $zip->close();
        echo 'ok';
    } else {
        echo 'falha';
    }
    ?>

# ZipArchive::setCompressionName

(PHP 7, PHP 8, PECL zip >= 1.13.0)

ZipArchive::setCompressionName — Define o método de compressão de uma entrada definida pelo seu nome

### Descrição

public function ZipArchive::setCompressionName(string `$name`, int `$method`, int `$compflags` = 0): bool

Define o método de compressão de uma entrada definida pelo seu nome.

### Parâmetros

`name`
  Nome da entrada.
`method`
  O método de compressão, uma das constantes `ZipArchive::CM_*`.
`compflags`
  Nível de compressão.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Adicionar arquivos com diferentes métodos de compressão a um arquivo

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFromString('foo', 'Some text');
        $zip->addFromString('bar', 'Some other text');
        $zip->setCompressionName('foo', ZipArchive::CM_STORE);
        $zip->setCompressionName('bar', ZipArchive::CM_DEFLATE);
        $zip->close();
        echo 'ok';
    } else {
        echo 'falha';
    }
    ?>

Exemplo #2 Adicionar arquivo e definir método de compressão

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFile('foo.jpg', 'bar.jpg');
        $zip->setCompressionName('bar.jpg', ZipArchive::CM_XZ);
        $zip->close();
        echo 'ok';
    } else {
        echo 'falha';
    }
    ?>

# ZipArchive::setEncryptionIndex

(PHP >= 7.2.0, PHP 8, PECL zip >= 1.14.0)

ZipArchive::setEncryptionIndex — Define o método de criptografia de uma entrada definida pelo seu índice

### Descrição

public function ZipArchive::setEncryptionIndex(int `$index`, int `$method`, #[\SensitiveParameter]?string `$password` = `null`): bool

Define o método de criptografia de uma entrada definida pelo seu índice.

### Parâmetros

`index`
  Índice da entrada.
`method`
  O método de criptografia definido por uma das constantes ZipArchive::EM_.
`password`
  Senha opcional, usada por padrão quando ausente.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `password` é anulável agora.

### Notas

> Nota: Esta função está disponível apenas se construída contra libzip ≥ 1.2.0.

### Veja Também

- ZipArchive::setPassword() - Define a senha para o arquivo ZIP ativo
- ZipArchive::setEncryptionName() - Define o método de criptografia de uma entrada definida pelo seu nome

# ZipArchive::setEncryptionName

(PHP >= 7.2.0, PHP 8, PECL zip >= 1.14.0)

ZipArchive::setEncryptionName — Define o método de criptografia de uma entrada definida pelo seu nome

### Descrição

public function ZipArchive::setEncryptionName(string `$name`, int `$method`, #[\SensitiveParameter]?string `$password` = `null`): bool

Define o método de criptografia de uma entrada definida pelo seu nome.

### Parâmetros

`name`
  Nome da entrada.
`method`
  O método de criptografia definido por uma das constantes ZipArchive::EM_.
`password`
  Senha opcional, usada por padrão quando ausente.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `password` é anulável agora.

### Exemplos

Este exemplo cria um arquivo ZIP test.zip e adiciona o arquivo test.txt criptografado usando o método AES 256.

Exemplo #1 Arquivar e criptografar um arquivo

    <?php
    $zip = new ZipArchive();
    if ($zip->open('test.zip', ZipArchive::CREATE) === TRUE) {
        $zip->setPassword('secret');
        $zip->addFile('text.txt');
        $zip->setEncryptionName('text.txt', ZipArchive::EM_AES_256);
        $zip->close();
        echo "Ok\n";
    } else {
        echo "KO\n";
    }
    ?>

### Notas

> Nota: Esta função está disponível apenas se construída contra libzip ≥ 1.2.0.

### Veja Também

- ZipArchive::setPassword() - Define a senha para o arquivo ZIP ativo
- ZipArchive::setEncryptionIndex() - Define o método de criptografia de uma entrada definida pelo seu índice

# ZipArchive::setExternalAttributesIndex

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::setExternalAttributesIndex — Define os atributos externos de uma entrada definida pelo seu índice

### Descrição

public function ZipArchive::setExternalAttributesIndex(
int `$index`,
int `$opsys`,
int `$attr`,
int `$flags` = 0
): bool

Define os atributos externos de uma entrada definida pelo seu índice.

### Parâmetros

`index`
  Índice da entrada.
`opsys`
  O código do sistema operacional definido por uma das constantes ZipArchive::OPSYS_.
`attr`
  Os atributos externos. O valor depende do sistema operacional.
`flags`
  Opções opcionais. Atualmente não utilizado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# ZipArchive::setExternalAttributesName

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::setExternalAttributesName — Define os atributos externos de uma entrada definida pelo seu nome

### Descrição

public function ZipArchive::setExternalAttributesName(
string `$name`,
int `$opsys`,
int `$attr`,
int `$flags` = 0
): bool

Define os atributos externos de uma entrada definida pelo seu nome.

### Parâmetros

`name`
  Nome da entrada.
`opsys`
  O código do sistema operacional definido por uma das constantes ZipArchive::OPSYS_.
`attr`
  Os atributos externos. O valor depende do sistema operacional.
`flags`
  Opções opcionais. Atualmente não utilizado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Este exemplo abre um arquivo ZIP test.zip e adiciona o arquivo test.txt com seus direitos Unix como atributos externos.

Exemplo #1 Arquivar um arquivo, com seus direitos Unix

    <?php
    $zip = new ZipArchive();
    $stat = stat($filename='test.txt');
    if (is_array($stat) && $zip->open('test.zip', ZipArchive::CREATE) === TRUE) {
        $zip->addFile($filename);
        $zip->setExternalAttributesName($filename, ZipArchive::OPSYS_UNIX, $stat['mode'] << 16);
        $zip->close();
        echo "Ok\n";
    } else {
        echo "KO\n";
    }
    ?>

# ZipArchive::setMtimeIndex

(PHP >= 8.0.0, PECL zip >= 1.16.0)

ZipArchive::setMtimeIndex — Define o tempo de modificação de uma entrada definida pelo seu índice

### Descrição

public function ZipArchive::setMtimeIndex(int `$index`, int `$timestamp`, int `$flags` = 0): bool

Define o tempo de modificação de uma entrada definida pelo seu índice.

### Parâmetros

`index`
  Índice da entrada.
`timestamp`
  O tempo de modificação (timestamp Unix) do arquivo.
`flags`
  Opções opcionais, não utilizados por enquanto.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Este exemplo cria um arquivo ZIP test.zip e adiciona o arquivo test.txt com sua data de modificação.

Exemplo #1 Arquivar um arquivo

    <?php
    $zip = new ZipArchive();
    if ($zip->open('test.zip', ZipArchive::CREATE) === TRUE) {
        $zip->addFile('text.txt');
        $zip->setMtimeIndex(0, mktime(0,0,0,12,25,2019));
        $zip->close();
        echo "Ok\n";
    } else {
        echo "KO\n";
    }
    ?>

### Notas

> Nota: Esta função só está disponível se compilada com libzip ≥ 1.0.0.

### Veja Também

- ZipArchive::setMtimeName() - Define o tempo de modificação de uma entrada definida pelo seu nome

# ZipArchive::setMtimeName

(PHP >= 8.0.0, PECL zip >= 1.16.0)

ZipArchive::setMtimeName — Define o tempo de modificação de uma entrada definida pelo seu nome

### Descrição

public function ZipArchive::setMtimeName(string `$name`, int `$timestamp`, int `$flags` = 0): bool

Define o tempo de modificação de uma entrada definida pelo seu nome.

### Parâmetros

`name`
  Nome da entrada.
`timestamp`
  O tempo de modificação (timestamp Unix) do arquivo.
`flags`
  Opções opcionais, não utilizados por enquanto.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Este exemplo cria um arquivo ZIP test.zip e adiciona o arquivo test.txt com sua data de modificação.

Exemplo #1 Arquivar um arquivo

    <?php
    $zip = new ZipArchive();
    if ($zip->open('test.zip', ZipArchive::CREATE) === TRUE) {
        $zip->addFile('text.txt');
        $zip->setMtimeName('text.txt', mktime(0,0,0,12,25,2019));
        $zip->close();
        echo "Ok\n";
    } else {
        echo "KO\n";
    }
    ?>

### Notas

> Nota: Esta função só está disponível se compilada com libzip ≥ 1.0.0.

### Veja Também

- ZipArchive::setMtimeIndex() - Define o tempo de modificação de uma entrada definida pelo seu índice

# ZipArchive::setPassword

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::setPassword — Define a senha para o arquivo ZIP ativo

### Descrição

public function ZipArchive::setPassword(#[\SensitiveParameter]string `$password`): bool

Define a senha para o arquivo ZIP ativo.

### Parâmetros

`password`
  A senha a ser usada para o arquivo.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Notas

> Nota: A partir do PHP 7.2.0 e libzip 1.2.0, a senha é usada para descompactar o arquivo ZIP e também é a senha padrão para ZipArchive::setEncryptionName() e ZipArchive::setEncryptionIndex(). Anteriormente, esta função apenas definia a senha a ser usada para descompactar o arquivo ZIP; ela não transformava um ZipArchive sem senha em um ZipArchive com senha.

### Veja Também

- ZipArchive::setEncryptionIndex() - Define o método de criptografia de uma entrada definida pelo seu índice
- ZipArchive::setEncryptionName() - Define o método de criptografia de uma entrada definida pelo seu nome

# ZipArchive::statIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::statIndex — Obtenha os detalhes de uma entrada definida pelo seu índice

### Descrição

public function ZipArchive::statIndex(int `$index`, int `$flags` = 0): array|false

A função obtém informações sobre a entrada definida pelo seu índice.

### Parâmetros

`index`
  Índice da entrada
`flags`
  `ZipArchive::FL_UNCHANGED` pode ser ORed para solicitar informações sobre o arquivo original no arquivo, ignorando quaisquer alterações feitas.

### Valor Retornado

Retorna um array contendo os detalhes da entrada ou `false` em caso de falha.

### Exemplos

Exemplo #1 Impressão das informações stat de uma entrada

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        print_r($zip->statIndex(3));
        $zip->close();
    } else {
        echo 'falha, código:' . $res;
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [name] => foobar/baz
        [index] => 3
        [crc] => 499465816
        [size] => 27
        [mtime] => 1123164748
        [comp_size] => 24
        [comp_method] => 8
    )

# ZipArchive::statName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::statName — Obtém os detalhes de uma entrada definida pelo seu nome

### Descrição

public function ZipArchive::statName(string `$name`, int `$flags` = 0): array|false

A função obtém informações sobre a entrada definida pelo seu nome.

### Parâmetros

`name`
  Nome da entrada
`flags`

  O argumento flags especifica como a pesquisa pelo nome deve ser feita. Além disso, `ZipArchive::FL_UNCHANGED` pode ser ORed para solicitar informações sobre o arquivo original no arquivo, ignorando quaisquer alterações feitas.

  - `ZipArchive::FL_NOCASE`
  - `ZipArchive::FL_NODIR`
  - `ZipArchive::FL_UNCHANGED`

### Valor Retornado

Retorna um array contendo os detalhes da entrada ou `false` em caso de falha.

### Exemplos

Exemplo #1 Impressão das informações stat de uma entrada

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        print_r($zip->statName('foobar/baz'));
        $zip->close();
    } else {
        echo 'falha, código:' . $res;
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [name] => foobar/baz
        [index] => 3
        [crc] => 499465816
        [size] => 27
        [mtime] => 1123164748
        [comp_size] => 24
        [comp_method] => 8
    )

# ZipArchive::unchangeAll

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeAll — Desfaz todas as alterações feitas no arquivo

### Descrição

public function ZipArchive::unchangeAll(): bool

Desfaz todas as alterações feitas no arquivo.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# ZipArchive::unchangeArchive

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeArchive — Reverte todas as alterações globais feitas no arquivo

### Descrição

public function ZipArchive::unchangeArchive(): bool

Reverte todas as alterações globais feitas no arquivo. Por enquanto, isso só reverte alterações no comentário do arquivo.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# ZipArchive::unchangeIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeIndex — Reverte todas as alterações feitas a uma entrada no índice fornecido

### Descrição

public function ZipArchive::unchangeIndex(int `$index`): bool

Reverter todas as alterações feitas a uma entrada no índice fornecido.

### Parâmetros

`index`
  Índice da entrada.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# ZipArchive::unchangeName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::unchangeName — Reverte todas as alterações feitas a uma entrada com o nome fornecido

### Descrição

public function ZipArchive::unchangeName(string `$name`): bool

Reverte todas as alterações feitas a uma entrada.

### Parâmetros

`name`
  Nome da entrada.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

## Índice

- ZipArchive::addEmptyDir — Adiciona um novo diretório
- ZipArchive::addFile — Adiciona um arquivo a um arquivo ZIP a partir do caminho fornecido
- ZipArchive::addFromString — Adiciona um arquivo a um arquivo ZIP usando seu conteúdo
- ZipArchive::addGlob — Adicionar arquivos de um diretório por padrão glob
- ZipArchive::addPattern — Adiciona arquivos de um diretório por padrão PCRE
- ZipArchive::clearError — Limpa a mensagem de erro de status, mensagens do sistema e/ou do zip
- ZipArchive::close — Fecha o arquivo de arquivo ativo (aberto ou recém-criado)
- ZipArchive::count — Conta o número de arquivos no arquivo
- ZipArchive::deleteIndex — Exclui uma entrada no arquivo usando seu índice
- ZipArchive::deleteName — Exclui uma entrada no arquivo usando seu nome
- ZipArchive::extractTo — Extrai o conteúdo do arquivo
- ZipArchive::getArchiveComment — Retorna o comentário do arquivo Zip
- ZipArchive::getArchiveFlag — Retorna o valor de uma opção global do arquivo Zip
- ZipArchive::getCommentIndex — Retorna o comentário de uma entrada usando o índice da entrada
- ZipArchive::getCommentName — Retorna o comentário de uma entrada usando o nome da entrada
- ZipArchive::getExternalAttributesIndex — Recupera os atributos externos de uma entrada definida pelo seu índice
- ZipArchive::getExternalAttributesName — Recupera os atributos externos de uma entrada definida pelo seu nome
- ZipArchive::getFromIndex — Retorna o conteúdo da entrada usando seu índice
- ZipArchive::getFromName — Retorna o conteúdo da entrada usando seu nome
- ZipArchive::getNameIndex — Retorna o nome de uma entrada usando seu índice
- ZipArchive::getStatusString — Retorna a mensagem de erro de status, mensagens do sistema e/ou zip
- ZipArchive::getStream — Obtém um manipulador de arquivo para a entrada definida pelo seu nome (somente leitura)
- ZipArchive::getStreamIndex — Obtém um manipulador de arquivo para a entrada definida pelo seu índice (somente leitura)
- ZipArchive::getStreamName — Obtém um manipulador de arquivo para a entrada definida pelo seu nome (somente leitura)
- ZipArchive::isCompressionMethodSupported — Verifica se um método de compressão é suportado pelo libzip
- ZipArchive::isEncryptionMethodSupported — Verifica se um método de criptografia é suportado pelo libzip
- ZipArchive::locateName — Retorna o índice da entrada no arquivo compactado
- ZipArchive::open — Abre um arquivo compactado ZIP
- ZipArchive::registerCancelCallback — Registra um callback para permitir o cancelamento durante o fechamento do arquivo compactado.
- ZipArchive::registerProgressCallback — Registrar um callback para fornecer atualizações durante o fechamento do arquivo compactado.
- ZipArchive::renameIndex — Renomeia uma entrada definida pelo seu índice
- ZipArchive::renameName — Renomeia uma entrada definida pelo seu nome
- ZipArchive::replaceFile — Substitui um arquivo no arquivo ZIP por um caminho fornecido
- ZipArchive::setArchiveComment — Define o comentário de um arquivo ZIP
- ZipArchive::setArchiveFlag — Define uma opção global de um arquivo ZIP
- ZipArchive::setCommentIndex — Define o comentário de uma entrada definida pelo seu índice
- ZipArchive::setCommentName — Define o comentário de uma entrada definida pelo seu nome
- ZipArchive::setCompressionIndex — Define o método de compressão de uma entrada definida pelo seu índice
- ZipArchive::setCompressionName — Define o método de compressão de uma entrada definida pelo seu nome
- ZipArchive::setEncryptionIndex — Define o método de criptografia de uma entrada definida pelo seu índice
- ZipArchive::setEncryptionName — Define o método de criptografia de uma entrada definida pelo seu nome
- ZipArchive::setExternalAttributesIndex — Define os atributos externos de uma entrada definida pelo seu índice
- ZipArchive::setExternalAttributesName — Define os atributos externos de uma entrada definida pelo seu nome
- ZipArchive::setMtimeIndex — Define o tempo de modificação de uma entrada definida pelo seu índice
- ZipArchive::setMtimeName — Define o tempo de modificação de uma entrada definida pelo seu nome
- ZipArchive::setPassword — Define a senha para o arquivo ZIP ativo
- ZipArchive::statIndex — Obtenha os detalhes de uma entrada definida pelo seu índice
- ZipArchive::statName — Obtém os detalhes de uma entrada definida pelo seu nome
- ZipArchive::unchangeAll — Desfaz todas as alterações feitas no arquivo
- ZipArchive::unchangeArchive — Reverte todas as alterações globais feitas no arquivo
- ZipArchive::unchangeIndex — Reverte todas as alterações feitas a uma entrada no índice fornecido
- ZipArchive::unchangeName — Reverte todas as alterações feitas a uma entrada com o nome fornecido

# Funções Zip

Aviso

A API procedural foi descontinuada desde o PHP 8.0.0. A classe ZipArchive deve ser usada em seu lugar.

# zip_close

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_close — Fecha um arquivo ZIP

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.0.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
function zip_close(resource `$zip`): void

Fecha um dado arquivo ZIP.

### Parâmetros

`zip`
  Um arquivo ZIP previamente aberto com zip_open().

### Valor Retornado

Nenhum valor é retornado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Esta função foi descontinuada em favor da API orientada a objetos, veja ZipArchive::close().

### Veja Também

- zip_open() - Abre um arquivo ZIP
- zip_read() - Lê o próximo item em um arquivo ZIP

# zip_entry_close

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_close — Fecha o arquivo que está aberto

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.0.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
function zip_entry_close(resource `$zip_entry`): bool

Fecha uma especificada lista de entrada.

### Parâmetros

`zip_entry`
  Um diretório de entrada previamente aberto com zip_entry_open().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Esta função foi descontinuada em favor da API orientada a objetos.

### Veja Também

- zip_entry_open() - Abre um arquivo para leitura
- zip_entry_read() - Obtém dados de um arquivo

# zip_entry_compressedsize

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_compressedsize — Obtém o tamanho comprimido do item

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.0.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
function zip_entry_compressedsize(resource `$zip_entry`): int|false

Retorna o tamanho do arquivo compactado dentro do arquivo ZIP especificado.

### Parâmetros

`zip_entry`
  Uma lista de entrada retornada pela zip_read().

### Valor Retornado

O tamanho comprimido, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Esta função foi descontinuada em favor da API orientada a objetos, veja ZipArchive::statIndex().

### Veja Também

- zip_open() - Abre um arquivo ZIP
- zip_read() - Lê o próximo item em um arquivo ZIP

# zip_entry_compressionmethod

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_compressionmethod — Recupera qual o método de compressão foi utilizado no arquivo

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.0.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
function zip_entry_compressionmethod(resource `$zip_entry`): string|false

Recupera qual o método de compressão foi utilizado no arquivo passado por `zip_entry`.

### Parâmetros

`zip_entry`
  Uma lista de entrada retornada pela zip_read().

### Valor Retornado

O método de compressão, ou , ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Esta função foi descontinuada em favor da API orientada a objetos, veja ZipArchive::statIndex().

### Veja Também

- zip_open() - Abre um arquivo ZIP
- zip_read() - Lê o próximo item em um arquivo ZIP

# zip_entry_filesize

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_filesize — Retorna o tamanho de um item de diretório

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.0.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
function zip_entry_filesize(resource `$zip_entry`): int|false

Retorna o tamanho atual do especificado diretório de entrada.

### Parâmetros

`zip_entry`
  Um diretório de entrada retornado por zip_read().

### Valor Retornado

O tamanho do item de diretório, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Esta função está desencorajada em relação a API orientada a objeto, veja ZipArchive::statIndex().

### Veja Também

- zip_open() - Abre um arquivo ZIP
- zip_read() - Lê o próximo item em um arquivo ZIP

# zip_entry_name

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_name — Retorna o nome do arquivo

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.0.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
function zip_entry_name(resource `$zip_entry`): string|false

Retorna o nome do arquivo especificado.

### Parâmetros

`zip_entry`
  A lista de entrada retornada pela zip_read().

### Valor Retornado

O nome do arquivo, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Esta função está desencorajada em relação a API orientada a objeto, veja ZipArchive::statIndex().

### Veja Também

- zip_open() - Abre um arquivo ZIP
- zip_read() - Lê o próximo item em um arquivo ZIP

# zip_entry_open

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_open — Abre um arquivo para leitura

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.0.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
function zip_entry_open(resource `$zip_dp`, resource `$zip_entry`, string `$mode` = "rb"): bool

Abre um arquivo para leitura.

### Parâmetros

`zip_dp`
  Um recurso válido retornado por zip_open().
`zip_entry`
  Uma entrada de diretório retornada por zip_read().
`mode`
  Algum dos modos especificados na documentação da fopen().

  > Nota: Atualmente, o parâmetro `mode` é ignorado e o modo padrão suportado é `"rb"`. Isto é devido ao fato que o suporte a zip no PHP é apenas de leitura.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

> Nota: Diferentemente de fopen() e outras funções similares, o valor retornado de zip_entry_open() somente indica o resultado da operação, e não o valor em si não é necessário para a leitura ou fechamento recurso.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Esta função está desencorajada em relação a API orientada a objeto.

### Veja Também

- zip_entry_close() - Fecha o arquivo que está aberto
- zip_entry_read() - Obtém dados de um arquivo

# zip_entry_read

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_read — Obtém dados de um arquivo

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.0.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
function zip_entry_read(resource `$zip_entry`, int `$len` = 1024): string|false

Obtém dados de um arquivo.

### Parâmetros

`zip_entry`
  Um arquivo retornado pela zip_read().
`len`
  O número de bytes para retornar.

  > Nota: Este deve ser o tamanho não comprimido que você deseja ler.

### Valor Retornado

Retorna a informação lida, string vazia no fim de um arquivo, ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Essa função está desencorajada em relação à API orientada a objetos, veja ZipArchive::getFromIndex().

### Veja Também

- zip_entry_open() - Abre um arquivo para leitura
- zip_entry_close() - Fecha o arquivo que está aberto
- zip_entry_filesize() - Retorna o tamanho de um item de diretório

# zip_open

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_open — Abre um arquivo ZIP

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.0.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
function zip_open(string `$filename`): resource|int|false

Abre um arquivo ZIP para ser lido.

### Parâmetros

`filename`
  O nome do arquivo ZIP para abrir.

### Valor Retornado

Retorna um identificador que pode ser usado com as funções zip_read() e zip_close() ou retorna `false` ou ainda o número de erro se `filename` não existir e/ou outras situações.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Essa função está desencorajada em relação à API orientada a objetos, veja ZipArchive::open().

### Veja Também

- zip_read() - Lê o próximo item em um arquivo ZIP
- zip_close() - Fecha um arquivo ZIP

# zip_read

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_read — Lê o próximo item em um arquivo ZIP

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.0.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
function zip_read(resource `$zip`): resource|false

Lê o próximo item dentro de uma arquivo ZIP.

### Parâmetros

`zip`
  Um arquivo ZIP anteriormente aberto com zip_open().

### Valor Retornado

Retorna uma conexao com o arquivo ZIP para ser usado com as funções `zip_entry_...`, ou `false` se não houver arquivos para serem lidos, ou um código de erro caso ocorra algum.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Essa função está desencorajada em relação à API orientada a objetos, veja ZipArchive::statIndex().

### Veja Também

- zip_open() - Abre um arquivo ZIP
- zip_close() - Fecha um arquivo ZIP
- zip_entry_open() - Abre um arquivo para leitura
- zip_entry_read() - Obtém dados de um arquivo

## Índice

- zip_close — Fecha um arquivo ZIP
- zip_entry_close — Fecha o arquivo que está aberto
- zip_entry_compressedsize — Obtém o tamanho comprimido do item
- zip_entry_compressionmethod — Recupera qual o método de compressão foi utilizado no arquivo
- zip_entry_filesize — Retorna o tamanho de um item de diretório
- zip_entry_name — Retorna o nome do arquivo
- zip_entry_open — Abre um arquivo para leitura
- zip_entry_read — Obtém dados de um arquivo
- zip_open — Abre um arquivo ZIP
- zip_read — Lê o próximo item em um arquivo ZIP

- Instalação/Configuração
  - Dependências
  - Instalação
  - Tipos de Recurso
- Constantes predefinidas
- Exemplos
- ZipArchive — A classe ZipArchive
  - ZipArchive::addEmptyDir — Adiciona um novo diretório
  - ZipArchive::addFile — Adiciona um arquivo a um arquivo ZIP a partir do caminho fornecido
  - ZipArchive::addFromString — Adiciona um arquivo a um arquivo ZIP usando seu conteúdo
  - ZipArchive::addGlob — Adicionar arquivos de um diretório por padrão glob
  - ZipArchive::addPattern — Adiciona arquivos de um diretório por padrão PCRE
  - ZipArchive::clearError — Limpa a mensagem de erro de status, mensagens do sistema e/ou do zip
  - ZipArchive::close — Fecha o arquivo de arquivo ativo (aberto ou recém-criado)
  - ZipArchive::count — Conta o número de arquivos no arquivo
  - ZipArchive::deleteIndex — Exclui uma entrada no arquivo usando seu índice
  - ZipArchive::deleteName — Exclui uma entrada no arquivo usando seu nome
  - ZipArchive::extractTo — Extrai o conteúdo do arquivo
  - ZipArchive::getArchiveComment — Retorna o comentário do arquivo Zip
  - ZipArchive::getArchiveFlag — Retorna o valor de uma opção global do arquivo Zip
  - ZipArchive::getCommentIndex — Retorna o comentário de uma entrada usando o índice da entrada
  - ZipArchive::getCommentName — Retorna o comentário de uma entrada usando o nome da entrada
  - ZipArchive::getExternalAttributesIndex — Recupera os atributos externos de uma entrada definida pelo seu índice
  - ZipArchive::getExternalAttributesName — Recupera os atributos externos de uma entrada definida pelo seu nome
  - ZipArchive::getFromIndex — Retorna o conteúdo da entrada usando seu índice
  - ZipArchive::getFromName — Retorna o conteúdo da entrada usando seu nome
  - ZipArchive::getNameIndex — Retorna o nome de uma entrada usando seu índice
  - ZipArchive::getStatusString — Retorna a mensagem de erro de status, mensagens do sistema e/ou zip
  - ZipArchive::getStream — Obtém um manipulador de arquivo para a entrada definida pelo seu nome (somente leitura)
  - ZipArchive::getStreamIndex — Obtém um manipulador de arquivo para a entrada definida pelo seu índice (somente leitura)
  - ZipArchive::getStreamName — Obtém um manipulador de arquivo para a entrada definida pelo seu nome (somente leitura)
  - ZipArchive::isCompressionMethodSupported — Verifica se um método de compressão é suportado pelo libzip
  - ZipArchive::isEncryptionMethodSupported — Verifica se um método de criptografia é suportado pelo libzip
  - ZipArchive::locateName — Retorna o índice da entrada no arquivo compactado
  - ZipArchive::open — Abre um arquivo compactado ZIP
  - ZipArchive::registerCancelCallback — Registra um callback para permitir o cancelamento durante o fechamento do arquivo compactado.
  - ZipArchive::registerProgressCallback — Registrar um callback para fornecer atualizações durante o fechamento do arquivo compactado.
  - ZipArchive::renameIndex — Renomeia uma entrada definida pelo seu índice
  - ZipArchive::renameName — Renomeia uma entrada definida pelo seu nome
  - ZipArchive::replaceFile — Substitui um arquivo no arquivo ZIP por um caminho fornecido
  - ZipArchive::setArchiveComment — Define o comentário de um arquivo ZIP
  - ZipArchive::setArchiveFlag — Define uma opção global de um arquivo ZIP
  - ZipArchive::setCommentIndex — Define o comentário de uma entrada definida pelo seu índice
  - ZipArchive::setCommentName — Define o comentário de uma entrada definida pelo seu nome
  - ZipArchive::setCompressionIndex — Define o método de compressão de uma entrada definida pelo seu índice
  - ZipArchive::setCompressionName — Define o método de compressão de uma entrada definida pelo seu nome
  - ZipArchive::setEncryptionIndex — Define o método de criptografia de uma entrada definida pelo seu índice
  - ZipArchive::setEncryptionName — Define o método de criptografia de uma entrada definida pelo seu nome
  - ZipArchive::setExternalAttributesIndex — Define os atributos externos de uma entrada definida pelo seu índice
  - ZipArchive::setExternalAttributesName — Define os atributos externos de uma entrada definida pelo seu nome
  - ZipArchive::setMtimeIndex — Define o tempo de modificação de uma entrada definida pelo seu índice
  - ZipArchive::setMtimeName — Define o tempo de modificação de uma entrada definida pelo seu nome
  - ZipArchive::setPassword — Define a senha para o arquivo ZIP ativo
  - ZipArchive::statIndex — Obtenha os detalhes de uma entrada definida pelo seu índice
  - ZipArchive::statName — Obtém os detalhes de uma entrada definida pelo seu nome
  - ZipArchive::unchangeAll — Desfaz todas as alterações feitas no arquivo
  - ZipArchive::unchangeArchive — Reverte todas as alterações globais feitas no arquivo
  - ZipArchive::unchangeIndex — Reverte todas as alterações feitas a uma entrada no índice fornecido
  - ZipArchive::unchangeName — Reverte todas as alterações feitas a uma entrada com o nome fornecido
- Funções Zip
  - zip_close — Fecha um arquivo ZIP
  - zip_entry_close — Fecha o arquivo que está aberto
  - zip_entry_compressedsize — Obtém o tamanho comprimido do item
  - zip_entry_compressionmethod — Recupera qual o método de compressão foi utilizado no arquivo
  - zip_entry_filesize — Retorna o tamanho de um item de diretório
  - zip_entry_name — Retorna o nome do arquivo
  - zip_entry_open — Abre um arquivo para leitura
  - zip_entry_read — Obtém dados de um arquivo
  - zip_open — Abre um arquivo ZIP
  - zip_read — Lê o próximo item em um arquivo ZIP

# Compressão Zlib

# Introdução

Este módulo permite que você leia e escreva arquivos comprimidos gzip (.gz) de forma transparente, através de versões da maioria das funções do sistema de arquivos que funcionam com arquivos comprimidos gzip (e também com arquivos não comprimidos, mas não com sockets).

> Nota:

> O PHP vem com um empacotador fopen para arquivos .gz. Mais informações estão disponíveis na seção sobre zlib://.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução
- Tipos de Recurso

## Dependências

Este módulo usa as funções da » zlib por Jean-loup Gailly e Mark Adler. A partir do PHP 8.4.0, a mínima versão da zlib requerida é 1.2.11. Antes do PHP 8.4.0, a mínima versão da zlib requerida era 1.2.0.4.

## Instalação

O suporte a Zlib no PHP não esta ativado por padrão. Você precisa configurar o PHP com --with-zlib[=DIR]

A versão do PHP para Windows tem suporte nativo para esta extensão. Nenhuma extensão adicional precisa ser carregada para usar essas funções.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

A extensão zlib oferece a opção de comprimir transparentemente suas páginas em tempo real, se o navegador requisitante suportar isto. Então existem três opções no arquivo de configuração php.ini.

Opções de Configuração da Zlib
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
zlib.output_compression | "0" | `INI_ALL` |
zlib.output_compression_level | "-1" | `INI_ALL` |
zlib.output_handler | "" | `INI_ALL` |

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`zlib.output_compression` bool/int

  Indica se as páginas deverm ser comprimidas de modo transparente. Se esta opção for mudada para "On" no php.ini ou na configuração do Apache, as páginas serão comprimidas se o navegador enviar um cabeçalho "Accept-Encoding: gzip" ou "deflate". "Content-Encoding: gzip" (respectivamente "deflate") e cabeçalhos "Vary: Accept-Encoding" serão adicionados para a saída. Em tempo de execução, isso só pode ser definido antes de enviar qualquer saída.

  Esta opção também aceita valores inteiros em vez de valores booleanos "On"/"Off", usando isto você pode configurar o tamanho do buffer de saída (o padrão é 4KB).

  > Nota:

  > output_handler deve estar vazio se a diretriz estiver configurada em 'On'! Em vez disso, utilize `zlib.output_handler`.

`zlib.output_compression_level` int

  Nível de compressão utilizado. Especifique um valor entre 0 (sem compressão) ou 9 (compressão máxima). O valor padrão -1 permite ao servidor escolher que nível utilizar.

`zlib.output_handler` string

  Você não pode especificar tratamentos adicionais de saída se zlib.output_compression for ativado. Esta configuração faz o mesmo que a output_handler mas em uma ordem diferente.

## Tipos de Recurso

Esta extensão define um ponteiro de arquivo resource retornado pela gzopen(). Antes do PHP 8.0.0, recursos `zlib.deflate` e `zlib.inflate` também eram definidos.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`FORCE_GZIP` (int)
`FORCE_DEFLATE` (int)
`ZLIB_ENCODING_RAW` (int)
  Algotítmo DEFLATE conforme RFC 1951.
`ZLIB_ENCODING_DEFLATE` (int)
  Algorítimo ZLIB conforme RFC 1950.
`ZLIB_ENCODING_GZIP` (int)
  Algorítimo GZIP conforme RFC 1952.
`ZLIB_FILTERED` (int)
`ZLIB_HUFFMAN_ONLY` (int)
`ZLIB_FIXED` (int)
`ZLIB_RLE` (int)
`ZLIB_DEFAULT_STRATEGY` (int)
`ZLIB_BLOCK` (int)
`ZLIB_NO_FLUSH` (int)
`ZLIB_PARTIAL_FLUSH` (int)
`ZLIB_SYNC_FLUSH` (int)
`ZLIB_FULL_FLUSH` (int)
`ZLIB_FINISH` (int)
`ZLIB_VERSION` (string)
  Versão da `zlib` como uma string.
`ZLIB_VERNUM` (int)
  Versão da `zlib` como um int.
`ZLIB_OK` (int)
  Sem error ou informações de status.
`ZLIB_STREAM_END` (int)
  Fluxo concluído com sucesso.
`ZLIB_NEED_DICT` (int)
  É necessário dicionário preset.
`ZLIB_ERRNO` (int)
  Erro de operação em arquivo.
`ZLIB_STREAM_ERROR` (int)
  O estado do fluxo está inconsistente ou o parâmetro é inválido.
`ZLIB_DATA_ERROR` (int)
  Dados de entrada corrompidos.
`ZLIB_MEM_ERROR` (int)
  Memória insuficiente.
`ZLIB_BUF_ERROR` (int)
  Progresso não é possível por espaço insuficiente no buffer ou final inesperao do fluxo de entrada.
`ZLIB_VERSION_ERROR` (int)
  Versão da biblioteca `zlib` é incompatível com a versão esperada pelo chamador.

# Exemplos

Este exemplo abre um arquivo temporário e gera uma string teste dentro dele, então ela mostra o conteúdo deste arquivo duas vezes.

Exemplo #1 Pequeno Exemplo da Zlib

    <?php

    $filename = tempnam('/tmp', 'zlibtest') . '.gz';
    echo "<html>\n<head></head>\n<body>\n<pre>\n";
    $s = "Only a test, test, test, test, test, test, test, test!\n";

    // Abre um arquivo para escrever os dados comprimidos
    $zp = gzopen($filename, "w9");

    // Escreve o texto no arquivo
    gzwrite($zp, $s);

    // Fecha o arquivo
    gzclose($zp);

    // Abre o arquivo
    $zp = gzopen($filename, "r");

    // Lê três bytes
    echo gzread($zp, 3);

    // Imprime até o final do arquivo e o fecha
    gzpassthru($zp);
    gzclose($zp);

    echo "\n";

    // Abre e imprime o arquivo, uma segunda vez
    if (readgzfile($filename) != strlen($s)) {
            echo "Erro com as funções zlib!";
    }
    unlink($filename);
    echo "</pre>\n</body>\n</html>\n";

    ?>

Exemplo #2 Utilizando a API de compressão/expansão incremental

    <?php
    // Realiza uma compressão GZIP:
    $deflateContext = deflate_init(ZLIB_ENCODING_GZIP);
    $compressed = deflate_add($deflateContext, "Data to compress", ZLIB_NO_FLUSH);
    $compressed .= deflate_add($deflateContext, ", more data", ZLIB_NO_FLUSH);
    $compressed .= deflate_add($deflateContext, ", and even more data!", ZLIB_FINISH);

    // Realiza uma expansão GZIP:
    $inflateContext = inflate_init(ZLIB_ENCODING_GZIP);
    $uncompressed = inflate_add($inflateContext, $compressed, ZLIB_NO_FLUSH);
    $uncompressed .= inflate_add($inflateContext, NULL, ZLIB_FINISH);
    echo $uncompressed;
    ?>

O exemplo acima produzirá:

    Data to compress, more data, and even more data!

# Funções da Zlib

# deflate_add

(PHP 7, PHP 8)

deflate_add — Comprime dados incrementalmente

### Descrição

function deflate_add(DeflateContext `$context`, string `$data`, int `$flush_mode` = `ZLIB_SYNC_FLUSH`): string|false

Comprime dados incrementalmente no contexto especificado.

### Parâmetros

`context`

  Um contexto criado com deflate_init().

`data`

  Um pedaço de dados para comprimir.

`flush_mode`

  Uma das constantes `ZLIB_BLOCK`, `ZLIB_NO_FLUSH`, `ZLIB_PARTIAL_FLUSH`, `ZLIB_SYNC_FLUSH` (padrão), `ZLIB_FULL_FLUSH`, `ZLIB_FINISH`. Normalmente, você vai querer definir `ZLIB_NO_FLUSH` para maximizar a compressão, e `ZLIB_FINISH` para terminar com o último pedaço de dados. Veja o » manual do zlib para uma descrição detalhada dessas constantes.

### Valor Retornado

Retorna um pedaço de dados comprimidos, ou `false` em caso de falha.

### Erros/Exceções

Se argumentos inválidos forem fornecidos, um erro de nível `E_WARNING` é gerado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `context` espera agora uma instância de DeflateContext; anteriormente, era esperado um resource.

### Veja Também

- deflate_init() - Inicializa um contexto de compressão incremental

# deflate_init

(PHP 7, PHP 8)

deflate_init — Inicializa um contexto de compressão incremental

### Descrição

function deflate_init(int `$encoding`, array|object `$options` = []): DeflateContext|false

Inicializa um contexto de compressão incremental usando o `encoding` especificado.

Note que a opção `window` aqui apenas define o tamanho da janela do algoritmo, de forma diferente dos filtros zlib onde o mesmo parâmetro também define a codificação a ser usada; a codificação deve ser definida com o parâmetro `encoding`.

Limitação: atualmente não há maneira de definir as informações de cabeçalho em um fluxo comprimido GZIP, que são definidas da seguinte forma: assinatura GZIP (`\x1f\x8B`); método de compressão (`\x08` == DEFLATE); 6 bytes zero; o sistema operacional definido para o sistema atual (`\x00` = Windows, `\x03` = Unix, etc.)

### Parâmetros

`encoding`

  Uma das constantes `ZLIB_ENCODING_*`.

`options`

  Um array associativo que pode conter os seguintes elementos:

  level

    O nível de compressão no intervalo -1..9; padrão é -1.

  memory

    O nível de memória de compressão no intervalo 1..9; padrão é 8.

  window

    O tamanho da janela zlib (logarítmico) no intervalo `8`..`15`; padrão é `15`. zlib muda um tamanho de janela de `8` para `9`, e a partir do zlib 1.2.8 falha com um aviso, se um tamanho de janela de `8` for solicitado para `ZLIB_ENCODING_RAW` ou `ZLIB_ENCODING_GZIP`.

  strategy

    Uma das constantes `ZLIB_FILTERED`, `ZLIB_HUFFMAN_ONLY`, `ZLIB_RLE`, `ZLIB_FIXED` ou `ZLIB_DEFAULT_STRATEGY` (o padrão).

  dictionary

    Uma string ou um array de strings do dicionário predefinido (padrão: nenhum dicionário predefinido).

### Valor Retornado

Retorna um recurso de contexto de compressão (`zlib.deflate`) em caso de sucesso, ou `false` em caso de falha.

### Erros/Exceções

Se uma opção inválida for passada para `options` ou o contexto não puder ser criado, um erro de nível `E_WARNING` é gerado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Em caso de sucesso, esta função retorna agora uma instância de DeflateContext; anteriormente, um resource era retornado.

### Veja Também

- deflate_add() - Comprime dados incrementalmente
- inflate_init() - Inicializa um contexto de descompressão incremental

# gzclose

(PHP 4, PHP 5, PHP 7, PHP 8)

gzclose — Fecha um ponteiro para um arquivo-gz

### Descrição

function gzclose(resource `$stream`): bool

Fecha o ponteiro para arquivo gz dado.

### Parâmetros

`stream`

  O ponteiro de arquivo gz. Ele deve ser válido,e apontar para um arquivo aberto de maneira correta pela função gzopen().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo gzclose()

    <?php
    $gz = gzopen('algum_arquivo.gz','w9');
    gzputs ($gz, 'Fui adicionado a algum_arquivo.gz');
    gzclose($gz);
    ?>

### Veja Também

- gzopen() - Abre arquivo gz

# gzcompress

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

gzcompress — Comprime uma string

### Descrição

function gzcompress(string `$data`, int `$level` = -1, int `$encoding` = `ZLIB_ENCODING_DEFLATE`): string|false

+ Esta função comprime a string fornecida usando o formato de dados `ZLIB`.

Para detalhes sobre o algoritmo de compressão ZLIB, consulte o documento "» Formato de dados compactados ZLIB Especificação versão 3.3" (RFC 1950).

> Nota:

> Isso não é o mesmo que compressão gzip, que inclui alguns dados de cabeçalho. Veja gzencode() para compressão gzip.

### Parâmetros

`data`

  Os dados a serem comprimidos.

`level`

  O nível de compressão. Pode ser dado como 0 para nenhuma compressão até 9 para máxima compressão.

  Se -1 for usado, a compressão padrão da biblioteca zlib é usada, que é 6.

`encoding`

  Uma das constantes `ZLIB_ENCODING_*`.

### Valor Retornado

A string comprimida ou `false` se ocorrer um erro.

### Exemplos

Exemplo #1 Exemplo de gzcompress()

    <?php
    $compressed = gzcompress('Me comprima', 9);
    echo $compressed;
    ?>

### Veja Também

- gzdeflate() - Desinfla uma string
- gzinflate() - Descomprime uma string comprimida
- gzuncompress() - Descomprime uma string comprimida
- gzencode() - Cria uma string comprimida no formato gzip

# gzdecode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

gzdecode — Decodifica uma string comprimida usando o gzip

### Descrição

function gzdecode(string `$data`, int `$max_length` = 0): string|false

Essa função retorna a versão decodifica de `data`.

### Parâmetros

`data`

  Os dados a serem decodificados, encodificados por gzencode().

`max_length`

  Tamanho máximo dos dados a serem decodificados.

### Valor Retornado

A string decodificada, ou ou `false` em caso de falha.

### Erros/Exceções

Em caso de problemas, uma mensagem `E_WARNING` é emitida.

### Veja Também

- gzencode() - Cria uma string comprimida no formato gzip

# gzdeflate

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzdeflate — Desinfla uma string

### Descrição

function gzdeflate(string `$data`, int `$level` = -1, int `$encoding` = `ZLIB_ENCODING_RAW`): string|false

Esta função comprime a string fornecida usando o formato de dados `DEFLATE`.

Para detalhes sobre o algoritmo de compressão DEFLATE, consulte o documento "» Especificação de Formato de Dados Comprimidos DEFLATE versão 1.3" (RFC 1951).

### Parâmetros

`data`

  Os dados a serem desinflados.

`level`

  O nível de compressão. Pode ser dado como 0 para nenhuma compressão até 9 para máxima compressão. Se não fornecido, o nível de compressão padrão será o nível de compressão padrão da biblioteca zlib.

`encoding`

  Uma das constantes `ZLIB_ENCODING_*`.

### Valor Retornado

A string desinflada ou `false` se ocorrer um erro.

### Exemplos

Exemplo #1 Exemplo de gzdeflate()

    <?php
    $compressed = gzdeflate('Me comprima', 9);
    echo $compressed;
    ?>

### Veja Também

- gzinflate() - Descomprime uma string comprimida
- gzcompress() - Comprime uma string
- gzuncompress() - Descomprime uma string comprimida
- gzencode() - Cria uma string comprimida no formato gzip

# gzencode

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzencode — Cria uma string comprimida no formato gzip

### Descrição

function gzencode(string `$data`, int `$level` = -1, int `$encoding` = `ZLIB_ENCODING_GZIP`): string|false

Esta função retorna uma versão comprimida dos dados de entrada `data` compatível com a saída do programa gzip.

Para mais informações sobre o formato de arquivo GZIP, consulte o documento: » Especificação do formato de arquivo GZIP versão 4.3 (RFC 1952).

### Parâmetros

`data`

  Os dados a serem codificados.

`level`

  O nível de compressão. Pode ser dado como 0 para nenhuma compressão até 9 para máxima compressão. Se não fornecido, o nível de compressão padrão será o nível de compressão padrão da biblioteca zlib.

`encoding`

  O modo de codificação. Pode ser `FORCE_GZIP` (o padrão) ou `FORCE_DEFLATE`.

  `FORCE_DEFLATE` gera saída compatível com o RFC 1950, consistindo de um cabeçalho zlib, os dados desinflados e um checksum Adler.

### Valor Retornado

A string codificada, ou `false` se ocorrer um erro.

### Exemplos

Os dados resultantes contêm os cabeçalhos e a estrutura de dados apropriados para criar um arquivo .gz padrão, por exemplo:

Exemplo #1 Criando um arquivo gzip

    <?php
    $data = file_get_contents("arquivogrande.txt");
    $gzdata = gzencode($data, 9);
    file_put_contents("arquivogrande.txt.gz", $gzdata);
    ?>

### Veja Também

- gzdecode() - Decodifica uma string comprimida usando o gzip
- gzdeflate() - Desinfla uma string
- gzinflate() - Descomprime uma string comprimida
- gzuncompress() - Descomprime uma string comprimida
- gzcompress() - Comprime uma string
- » Especificação do Formato de Dados Comprimidos ZLIB (RFC 1950)

# gzeof

(PHP 4, PHP 5, PHP 7, PHP 8)

gzeof — Testar o EOF em um ponteiro de arquivo gz

### Descrição

function gzeof(resource `$stream`): bool

Testa o ponteiro de arquivo GZ fornecido para o EOF.

### Parâmetros

`stream`

  O ponteiro de arquivo gz. Deve ser válido e deve apontar para um arquivo aberto com sucesso por gzopen().

### Valor Retornado

Retorna `true` se o ponteiro de arquivo gz estiver no EOF ou se ocorrer um erro; caso contrário, retorna `false`.

### Exemplos

Exemplo #1 Exemplo de gzeof()

    <?php
    $gz = gzopen('algumarquivo.gz', 'r');
    while (!gzeof($gz)) {
      echo gzgetc($gz);
    }
    gzclose($gz);
    ?>

# gzfile

(PHP 4, PHP 5, PHP 7, PHP 8)

gzfile — Lê todo o arquivo gz em um array

### Descrição

function gzfile(string `$filename`, bool `$use_include_path` = `false`): array|false

Esta função é idêntica à readgzfile(), exceto que ela retorna o arquivo em um array.

### Parâmetros

`filename`

  O nome do arquivo.

`use_include_path`
  Se definido para `true`, arquivos no include_path também são pesquisados.

### Valor Retornado

Um array contendo o arquivo, uma linha por célula, linhas vazias incluídas, e com novas linhas ainda anexadas, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | `use_include_path` agora é do tipo bool. Anteriormente era do tipo int.

### Exemplos

Exemplo #1 Exemplo de gzfile()

    <?php
    $lines = gzfile('algumarquivo.gz');
    foreach ($lines as $line) {
        echo $line;
    }
    ?>

### Veja Também

- readgzfile() - Exibe um arquivo gz
- gzopen() - Abre arquivo gz

# gzgetc

(PHP 4, PHP 5, PHP 7, PHP 8)

gzgetc — Obtém caractere de um ponteiro de arquivo gz

### Descrição

function gzgetc(resource `$stream`): string|false

Retorna uma string contendo um único caractere (não comprimido) lido do ponteiro de arquivo gz fornecido.

### Parâmetros

`stream`

  O ponteiro de arquivo gz. Deve ser válido e deve apontar para um arquivo aberto com sucesso por gzopen().

### Valor Retornado

O caractere não comprimido ou `false` em EOF (ao contrário de gzeof()).

### Exemplos

Exemplo #1 Exemplo de gzgetc()

    <?php
    $gz = gzopen('algumarquivo.gz', 'r');
    while (!gzeof($gz)) {
      echo gzgetc($gz);
    }
    gzclose($gz);
    ?>

### Veja Também

- gzopen() - Abre arquivo gz
- gzgets() - Obtém uma linha de um ponteiro de arquivo

# gzgets

(PHP 4, PHP 5, PHP 7, PHP 8)

gzgets — Obtém uma linha de um ponteiro de arquivo

### Descrição

function gzgets(resource `$stream`, ?int `$length` = `null`): string|false

Obtém uma (descomprimida) string até o tamanho length - 1 bytes lidos a partir do ponteiro de arquivo dado. A leitura termina quando length - 1 bytes tiverem sido lidos, em uma nova liha ou em EOF (o que vier primeiro).

### Parâmetros

`stream`

  O ponteiro do arquivo deve ser válido, e deve apontar para um arquivo aberto corretamente com gzopen().

`length`

  O tamanho dos dados a pegar.

### Valor Retornado

A string descomprimida, ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `length` pode ser null; anteriormente, o padrão era `1024`.

### Exemplos

Exemplo #1 Exemplo de gzgets()

    <?php
    $handle = gzopen('somefile.gz', 'r');
    while (!gzeof($handle)) {
       $buffer = gzgets($handle, 4096);
       echo $buffer;
    }
    gzclose($handle);
    ?>

### Veja Também

- gzopen() - Abre arquivo gz
- gzgetc() - Obtém caractere de um ponteiro de arquivo gz
- gzwrite() - Escrita segura para binário em arquivo-gz

# gzgetss

(PHP 4, PHP 5, PHP 7)

gzgetss — Obtém linha de um ponteiro de arquivo gz e remover tags HTML

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.3.0 e foi REMOVIDA a partir do PHP 8.0.0. O uso desta função é fortemente desencorajado.

### Descrição

function gzgetss(resource `$zp`, int `$length`, string `$allowable_tags` = ?): string

Idêntico a gzgets(), exceto que gzgetss() tenta remover quaisquer tags HTML e PHP do texto que ele lê.

### Parâmetros

`zp`

  O ponteiro de arquivo gz. Deve ser válido e deve apontar para um arquivo aberto com sucesso por gzopen().

`length`

  O comprimento dos dados a serem obtidos.

`allowable_tags`

  Você pode usar este parâmetro opcional para especificar tags que não devem ser removidas.

### Valor Retornado

A string não comprimida e sem tags, ou `false` em caso de erro.

### Exemplos

Exemplo #1 Exemplo de gzgetss()

    <?php
    $handle = gzopen('algumarquivo.gz', 'r');
    while (!gzeof($handle)) {
       $buffer = gzgetss($handle, 4096);
       echo $buffer;
    }
    gzclose($handle);
    ?>

### Veja Também

- gzopen() - Abre arquivo gz
- gzgets() - Obtém uma linha de um ponteiro de arquivo
- strip_tags() - Retira as tags HTML e PHP de uma string

# gzinflate

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzinflate — Descomprime uma string comprimida

### Descrição

function gzinflate(string `$data`, int `$max_length` = 0): string|false

Esta função descomprime uma string comprimida.

### Parâmetros

`data`

  Os dados comprimidos por gzdeflate().

`max_length`

  O comprimento máximo dos dados decodificados.

### Valor Retornado

Os dados não comprimidos originais ou `false` em caso de erro.

A função retornará um erro se o tamanho dos dados não comprimidos for maior que 32.768 vezes o comprimento da entrada comprimida `data` ou, a menos que `max_length` seja `0`, se for maior que o parâmetro opcional `max_length`.

### Exemplos

Exemplo #1 Exemplo de gzinflate()

    <?php
    $compressed   = gzdeflate('Me comprima', 9);
    $uncompressed = gzinflate($compressed);
    echo $uncompressed;
    ?>

### Veja Também

- gzdeflate() - Desinfla uma string
- gzcompress() - Comprime uma string
- gzuncompress() - Descomprime uma string comprimida
- gzencode() - Cria uma string comprimida no formato gzip

# gzopen

(PHP 4, PHP 5, PHP 7, PHP 8)

gzopen — Abre arquivo gz

### Descrição

function gzopen(string `$filename`, string `$mode`, bool `$use_include_path` = `false`): resource|false

Abre um arquivo gzip (.gz) para leitura ou escrita.

gzopen() pode ser usado para ler um arquivo que não está no formato gzip; nesse caso, gzread() lerá diretamente do arquivo sem descompressão.

### Parâmetros

`filename`

  O nome do arquivo.

`mode`

  Como em fopen() (`rb` ou `wb`) mas também pode incluir um nível de compressão (`wb9`) ou uma estratégia: `f` para dados filtrados como em `wb6f`, `h` para `compressão Huffman` como em `wb1h`. (Consulte a descrição de `deflateInit2` em zlib.h para mais informações sobre o parâmetro de estratégia.)

`use_include_path`
  Se definido para `true`, arquivos no include_path também são pesquisados.

### Valor Retornado

Retorna um ponteiro de arquivo para o arquivo aberto, depois disso, tudo o que você lê deste descritor de arquivo será descomprimido de forma transparente e o que você escreve será comprimido.

Se a abertura falhar, a função retorna `false`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | `use_include_path` agora é do tipo bool. Anteriormente era do tipo int.

### Exemplos

Exemplo #1 Exemplo de gzopen()

    <?php
    $fp = gzopen("/tmp/arquivo.gz", "r");
    ?>

### Veja Também

- gzclose() - Fecha um ponteiro para um arquivo-gz

# gzpassthru

(PHP 4, PHP 5, PHP 7, PHP 8)

gzpassthru — Escreve na saída todos os dados restantes em um ponteiro de arquivo gz

### Descrição

function gzpassthru(resource `$stream`): int

Lê até o final do arquivo (EOF) no ponteiro de arquivo gz dado a partir da posição atual e escreve os resultados (não comprimidos) na saída padrão.

> Nota:

> Você pode precisar chamar gzrewind() para redefinir o ponteiro de arquivo para o início do arquivo se você já tiver escrito dados nele.

Dica

Se você apenas deseja descarregar o conteúdo de um arquivo no buffer de saída, sem modificar primeiro ou procurar uma posição específica, pode usar a função readgzfile(), que economiza a chamada gzopen().

### Parâmetros

`stream`

  O ponteiro de arquivo gz. Ele deve ser válido e deve apontar para um arquivo aberto com sucesso por gzopen().

### Valor Retornado

O número de caracteres não comprimidos lidos de `gz` e passados para a entrada.

### Exemplos

Exemplo #1 Exemplo de gzpassthru()

    <?php
    $fp = gzopen('arquivo.gz', 'r');
    gzpassthru($fp);
    gzclose($fp);
    ?>

# gzputs

(PHP 4, PHP 5, PHP 7, PHP 8)

gzputs — Sinônimo de gzwrite()

### Descrição

Esta função é um apelido para: gzwrite().

# gzread

(PHP 4, PHP 5, PHP 7, PHP 8)

gzread — Leitura de arquivo gz binária segura

### Descrição

function gzread(resource `$stream`, int `$length`): string|false

gzread() lê até `length` bytes do ponteiro de arquivo gz dado. A leitura para quando `length` bytes (não comprimidos) tiverem sido lidos ou quando EOF é alcançado, o que ocorrer primeiro.

### Parâmetros

`stream`

  O ponteiro de arquivo gz. Ele deve ser válido e deve apontar para um arquivo aberto com sucesso por gzopen().

`length`

  O número de bytes a serem lidos.

### Valor Retornado

Os dados que foram lidos, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
7.4.0 | Esta função agora retorna `false` em caso de falha; anteriormente, `0` era retornado.

### Exemplos

Exemplo #1 Exemplo de gzread()

    <?php
    // obter o conteúdo de um arquivo gz em uma string
    $filename = "/usr/local/algumacoisa.txt.gz";
    $zd = gzopen($filename, "r");
    $contents = gzread($zd, 10000);
    gzclose($zd);
    ?>

### Veja Também

- gzwrite() - Escrita segura para binário em arquivo-gz
- gzopen() - Abre arquivo gz
- gzgets() - Obtém uma linha de um ponteiro de arquivo
- gzgetss() - Obtém linha de um ponteiro de arquivo gz e remover tags HTML
- gzfile() - Lê todo o arquivo gz em um array
- gzpassthru() - Escreve na saída todos os dados restantes em um ponteiro de arquivo gz

# gzrewind

(PHP 4, PHP 5, PHP 7, PHP 8)

gzrewind — Retorna ao início a posição de um ponteiro para um arquivo-gz

### Descrição

function gzrewind(resource `$stream`): bool

Define o indicador de posição para o dado arquivo gz para o início do arquivo.

### Parâmetros

`stream`

  O ponteiro do arquivo gz. Ele deve ser válido e deve apontar para um arquivo aberto corretamente com gzopen().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- gzseek() - Posiciona um ponteiro de arquivo gz
- gztell() - Indica a posição de leitura/gravação em um ponteiro para arquivo-gz

# gzseek

(PHP 4, PHP 5, PHP 7, PHP 8)

gzseek — Posiciona um ponteiro de arquivo gz

### Descrição

function gzseek(resource `$stream`, int `$offset`, int `$whence` = `SEEK_SET`): int

Define o indicador de posição de arquivo para o ponteiro de arquivo dado no byte de deslocamento na sequência de arquivo. Equivalente a chamar (em C) `gzseek(zp, offset, SEEK_SET)`.

Se o arquivo estiver aberto para leitura, esta função é emulada mas pode ser extremamente lenta. Se o arquivo estiver aberto para escrita, apenas buscas para frente são suportadas; gzseek() então comprime uma sequência de zeros até a nova posição inicial.

### Parâmetros

`stream`

  O ponteiro de arquivo gz. Ele deve ser válido e deve apontar para um arquivo aberto com sucesso por gzopen().

`offset`

  O deslocamento buscado.

`whence`

  Valores de `whence` podem ser:

  - `SEEK_SET` - Define a posição igual a `offset` bytes.
  - `SEEK_CUR` - Define a posição para a localização atual mais `offset`.

  Se `whence` não for especificado, assume-se que é `SEEK_SET`.

### Valor Retornado

Em caso de sucesso, retorna 0; caso contrário, retorna -1. Note que buscar além do EOF não é considerado um erro.

### Exemplos

Exemplo #1 Exemplo de gzseek()

    <?php
    $gz = gzopen('algumarquivo.gz', 'r');
    gzseek($gz,2);
    echo gzgetc($gz);
    gzclose($gz);
    ?>

### Veja Também

- gztell() - Indica a posição de leitura/gravação em um ponteiro para arquivo-gz
- gzrewind() - Retorna ao início a posição de um ponteiro para um arquivo-gz

# gztell

(PHP 4, PHP 5, PHP 7, PHP 8)

gztell — Indica a posição de leitura/gravação em um ponteiro para arquivo-gz

### Descrição

function gztell(resource `$stream`): int|false

Obtém a posição do ponteiro de arquivo, ou seja, seu índice dentro do arquivo.

### Parâmetros

`stream`

  O ponteiro de arquivo gz. Precisa ser válido, e deve apontar para um arquivo aberto corretamente com gzopen().

### Valor Retornado

A posição do ponteiro do arquivo ou `false` se um erro ocorrer.

### Veja Também

- gzopen() - Abre arquivo gz
- gzseek() - Posiciona um ponteiro de arquivo gz
- gzrewind() - Retorna ao início a posição de um ponteiro para um arquivo-gz

# gzuncompress

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

gzuncompress — Descomprime uma string comprimida

### Descrição

function gzuncompress(string `$data`, int `$max_length` = 0): string|false

Esta função descomprime uma string comprimida.

### Parâmetros

`data`

  Os dados comprimidos por gzcompress().

`max_length`

  O comprimento máximo dos dados a serem decodificados.

### Valor Retornado

Os dados descomprimidos originais ou `false` em caso de erro.

A função retornará um erro se os dados descomprimidos forem mais do que 32768 vezes o comprimento dos dados comprimidos de entrada `data` ou mais do que o parâmetro opcional `max_length`.

### Exemplos

Exemplo #1 Exemplo de gzuncompress()

    <?php
    $compressed   = gzcompress('Me comprima', 9);
    $uncompressed = gzuncompress($compressed);
    echo $uncompressed;
    ?>

### Veja Também

- gzcompress() - Comprime uma string
- gzinflate() - Descomprime uma string comprimida
- gzdeflate() - Desinfla uma string
- gzencode() - Cria uma string comprimida no formato gzip

# gzwrite

(PHP 4, PHP 5, PHP 7, PHP 8)

gzwrite — Escrita segura para binário em arquivo-gz

### Descrição

function gzwrite(resource `$stream`, string `$data`, ?int `$length` = `null`): int|false

gzwrite() escreve o conteúdo de `data` para o arquivo-gz.

### Parâmetros

`stream`

  O ponteiro do arquivo gz. Precisa ser válido, e apontar para um arquivo aberto com sucesso por gzopen().

`data`

  A string a ser escrita.

`length`

  O número de bytes descompactados a escrever. Se fornecido, a escrita irá parar depois de `length` bytes (descompactados) terem sido escritos, ou ao final de `data`, o que vier primeiro.

### Valor Retornado

Retorna o número de bytes (descompactados) escritos no fluxo informado do arquivo gz, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `length` permite null; anteriormente o default era `0`.
7.4.0 | Esta função agora retorna `false` em caso de falha; anteriormente retornava `0`.

### Exemplos

Exemplo #1 Exemplo da gzwrite()

    <?php
    $string = 'Some information to compress';
    $gz = gzopen('somefile.gz','w9');
    gzwrite($gz, $string);
    gzclose($gz);
    ?>

### Veja Também

- gzread() - Leitura de arquivo gz binária segura
- gzopen() - Abre arquivo gz

# inflate_add

(PHP 7, PHP 8)

inflate_add — Descomprime incrementalmente dados codificados

### Descrição

function inflate_add(InflateContext `$context`, string `$data`, int `$flush_mode` = `ZLIB_SYNC_FLUSH`): string|false

Descomprime incrementalmente dados codificados no contexto expecificado em `context`.

Limitação: informações de cabeçalho de dados comprimidos GZIP não estão disponíveis.

### Parâmetros

`context`

  Um contexto criado com inflate_init().

`data`

  Um pedaço de dados comprimidos.

`flush_mode`

  Uma das constantes `ZLIB_BLOCK`, `ZLIB_NO_FLUSH`, `ZLIB_PARTIAL_FLUSH`, `ZLIB_SYNC_FLUSH` (padrão), `ZLIB_FULL_FLUSH`, `ZLIB_FINISH`. Normalmente, você desejará definir `ZLIB_NO_FLUSH` para maximizar a compressão e `ZLIB_FINISH` para terminar com o último pedaço de dados. Consulte o » manual do zlib para obter uma descrição detalhada dessas constantes.

### Valor Retornado

Retorna um pedaço de dados descomprimidos, ou `false` em caso de falha.

### Erros/Exceções

Se parâmetros inválidos forem fornecidos, ou se a descompressão dos dados requerer um dicionário predefinido e nenhum for especificado, o se o fluxo comprimido estiver corrompido ou tiver uma soma de verificação inválida, um erro de nível `E_WARNING` é gerado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `context` espera uma instância de InflateContext agora; anteriormente, era esperado um resource.

### Veja Também

- inflate_init() - Inicializa um contexto de descompressão incremental

# inflate_get_read_len

(PHP 7 >= 7.2.0, PHP 8)

inflate_get_read_len — Obtém o número de bytes lidos até o momento

### Descrição

function inflate_get_read_len(InflateContext `$context`): int

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`context`

### Valor Retornado

Retorna o número de bytes lidos até o momento ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `context` espera uma instância de InflateContext agora; anteriormente, era esperado um resource.

# inflate_get_status

(PHP 7 >= 7.2.0, PHP 8)

inflate_get_status — Obtém o status da descompressão

### Descrição

function inflate_get_status(InflateContext `$context`): int

Normalmente retorna `ZLIB_OK` ou `ZLIB_STREAM_END`.

### Parâmetros

`context`

### Valor Retornado

Retorna o status da descompressão.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `context` agora espera uma instância de InflateContext; anteriormente, esperava-se um resource.

# inflate_init

(PHP 7, PHP 8)

inflate_init — Inicializa um contexto de descompressão incremental

### Descrição

function inflate_init(int `$encoding`, array|object `$options` = []): InflateContext|false

Inicializa um contexto de descompressão incremental com o `encoding` especificado.

### Parâmetros

`encoding`

  Uma das constantes `ZLIB_ENCODING_*`.

`options`

  Um array associativo que pode conter os seguintes elementos:

  level

    O nível de compressão no intervalo -1..9; padrão é -1.

  memory

    O nível de memória de compressão no intervalo 1..9; padrão é 8.

  window

    O tamanho da janela zlib (logarítmico) no intervalo 8..15; padrão é 15.

  strategy

    Uma das constantes `ZLIB_FILTERED`, `ZLIB_HUFFMAN_ONLY`, `ZLIB_RLE`, `ZLIB_FIXED` ou `ZLIB_DEFAULT_STRATEGY` (o padrão).

  dictionary

    Uma string ou um array de strings do dicionário predefinido (padrão: nenhum dicionário predefinido).

### Valor Retornado

Retorna um recurso de contexto de descompressão (`zlib.inflate`) em caso de sucesso, ou `false` em caso de falha.

### Erros/Exceções

Se uma codificação ou opção inválida for passada para `options`, ou o contexto não puder ser criado, um erro de nível `E_WARNING` é gerado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Em caso de sucesso, esta função agora retorna uma instância de InflateContext; anteriormente, um resource era retornado.

### Notas

Cuidado

Ao contrário de gzinflate(), contextos de descompressão incremental não restringem o comprimento dos dados decodificados, portanto, não oferecem proteção automática contra bombas Zip.

### Veja Também

- inflate_add() - Descomprime incrementalmente dados codificados
- deflate_init() - Inicializa um contexto de compressão incremental

# ob_gzhandler

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

ob_gzhandler — Função de chamada de retorno de ob_start para comprimir o buffer de saída com gzip

### Descrição

function ob_gzhandler(string `$data`, int `$flags`): string|false

ob_gzhandler() é destinada a ser usado como uma função de chamada de retorno para ob_start() para facilitar o envio de dados codificados em gzip para navegadores da web que suportam páginas da web comprimidas. Antes de ob_gzhandler() enviar realmente dados comprimidos, ela determina qual tipo de codificação de conteúdo o navegador aceitará ("gzip", "deflate" ou nenhum) e retornará sua saída de acordo. Todos os navegadores são suportados, pois cabe ao navegador enviar o cabeçalho correto dizendo que aceita páginas da web comprimidas. Se um navegador não suporta páginas comprimidas, esta função retorna `false`.

### Parâmetros

`data`

`flags`

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de ob_gzhandler()

    <?php

    ob_start("ob_gzhandler");

    ?>
    <html>
    <body>
    <p>Esta deve ser uma página comprimida.</p>
    </body>
    </html>

### Notas

> Nota:

> ob_gzhandler() requer a extensão zlib.

> Nota:

> ob_gzhandler() e zlib.output_compression não podem ser usadas ao mesmo tempo. Também observe que usar zlib.output_compression é preferível a ob_gzhandler().

### Veja Também

- ob_start() - Ativa o buffer de saída
- ob_end_flush() - Descarrega (envia) o valor de retorno do manipulador de saída ativo e desliga o buffer de saída ativo

# readgzfile

(PHP 4, PHP 5, PHP 7, PHP 8)

readgzfile — Exibe um arquivo gz

### Descrição

function readgzfile(string `$filename`, bool `$use_include_path` = `false`): int|false

Lê um arquivo, descomprime-o e escreve-o na saída padrão.

readgzfile() pode ser usada para ler um arquivo que não está em formato gzip; neste caso, readgzfile() irá diretamente ler do arquivo sem descompressão.

### Parâmetros

`filename`

  O nome do arquivo. Este arquivo será aberto do sistema de arquivos e seu conteúdo será escrito na saída padrão.

`use_include_path`
  Quando definido para `true`, o include_path será usado para determinar que arquivo deve ser aberto.

### Valor Retornado

Retorna o número de bytes (descomprimidos) lidos do arquivo com sucesso, ou `false` em caso de falha

### Erros/Exceções

Em caso de falha, um `E_WARNING` será emitido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | `use_include_path` agora é do tipo bool. Anteriormente era do tipo int.

### Veja Também

- gzpassthru() - Escreve na saída todos os dados restantes em um ponteiro de arquivo gz
- gzfile() - Lê todo o arquivo gz em um array
- gzopen() - Abre arquivo gz

# zlib_decode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

zlib_decode — Descomprime qualquer dado codificado em raw/gzip/zlib

### Descrição

function zlib_decode(string `$data`, int `$max_length` = 0): string|false

Descomprime qualquer dado codificado em raw/gzip/zlib.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`data`

`max_length`

### Valor Retornado

Retorna os dados descomprimidos, ou `false` em caso de falha.

### Veja Também

- zlib_encode() - Comprime dados com o codificador especificado

# zlib_encode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

zlib_encode — Comprime dados com o codificador especificado

### Descrição

function zlib_encode(string `$data`, int `$encoding`, int `$level` = -1): string|false

Comprime dados com o codificador especificado.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`data`

  Os dados a serem comprimidos.

`encoding`

  O algoritmo de compressão. Pode ser `ZLIB_ENCODING_RAW`, `ZLIB_ENCODING_DEFLATE` ou `ZLIB_ENCODING_GZIP`.

`level`

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de zlib_encode()

    <?php
    $str = 'hello world';
    $enc = zlib_encode($str, ZLIB_ENCODING_DEFLATE);
    echo bin2hex($enc);
    ?>

O exemplo acima produzirá:

    789ccb48cdc9c95728cf2fca4901001a0b045d

### Veja Também

- zlib_decode() - Descomprime qualquer dado codificado em raw/gzip/zlib

# zlib_get_coding_type

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

zlib_get_coding_type — Retorna o tipo de codificação para a compressão de saída

### Descrição

function zlib_get_coding_type(): string|false

Retorna o tipo de codificação para a compressão de saída.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Possíveis valores de retorno são `gzip`, `deflate`, ou `false`.

### Veja Também

- A diretiva zlib.output_compression

## Índice

- deflate_add — Comprime dados incrementalmente
- deflate_init — Inicializa um contexto de compressão incremental
- gzclose — Fecha um ponteiro para um arquivo-gz
- gzcompress — Comprime uma string
- gzdecode — Decodifica uma string comprimida usando o gzip
- gzdeflate — Desinfla uma string
- gzencode — Cria uma string comprimida no formato gzip
- gzeof — Testar o EOF em um ponteiro de arquivo gz
- gzfile — Lê todo o arquivo gz em um array
- gzgetc — Obtém caractere de um ponteiro de arquivo gz
- gzgets — Obtém uma linha de um ponteiro de arquivo
- gzgetss — Obtém linha de um ponteiro de arquivo gz e remover tags HTML
- gzinflate — Descomprime uma string comprimida
- gzopen — Abre arquivo gz
- gzpassthru — Escreve na saída todos os dados restantes em um ponteiro de arquivo gz
- gzputs — Sinônimo de gzwrite
- gzread — Leitura de arquivo gz binária segura
- gzrewind — Retorna ao início a posição de um ponteiro para um arquivo-gz
- gzseek — Posiciona um ponteiro de arquivo gz
- gztell — Indica a posição de leitura/gravação em um ponteiro para arquivo-gz
- gzuncompress — Descomprime uma string comprimida
- gzwrite — Escrita segura para binário em arquivo-gz
- inflate_add — Descomprime incrementalmente dados codificados
- inflate_get_read_len — Obtém o número de bytes lidos até o momento
- inflate_get_status — Obtém o status da descompressão
- inflate_init — Inicializa um contexto de descompressão incremental
- ob_gzhandler — Função de chamada de retorno de ob_start para comprimir o buffer de saída com gzip
- readgzfile — Exibe um arquivo gz
- zlib_decode — Descomprime qualquer dado codificado em raw/gzip/zlib
- zlib_encode — Comprime dados com o codificador especificado
- zlib_get_coding_type — Retorna o tipo de codificação para a compressão de saída

# A classe DeflateContext

(PHP 8)

## Introdução

Uma classe totalmente opaca que substitui os recursos `zlib.deflate` a partir do PHP 8.0.0.

## Resumo da classe

final class DeflateContext {
}

# A classe InflateContext

(PHP 8)

## Introdução

Uma classe totalmente opaca que substitui os recursos `zlib.inflate` a partir do PHP 8.0.0.

## Resumo da classe

final class InflateContext {
}

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
  - Tipos de Recurso
- Constantes predefinidas
- Exemplos
- Funções da Zlib
  - deflate_add — Comprime dados incrementalmente
  - deflate_init — Inicializa um contexto de compressão incremental
  - gzclose — Fecha um ponteiro para um arquivo-gz
  - gzcompress — Comprime uma string
  - gzdecode — Decodifica uma string comprimida usando o gzip
  - gzdeflate — Desinfla uma string
  - gzencode — Cria uma string comprimida no formato gzip
  - gzeof — Testar o EOF em um ponteiro de arquivo gz
  - gzfile — Lê todo o arquivo gz em um array
  - gzgetc — Obtém caractere de um ponteiro de arquivo gz
  - gzgets — Obtém uma linha de um ponteiro de arquivo
  - gzgetss — Obtém linha de um ponteiro de arquivo gz e remover tags HTML
  - gzinflate — Descomprime uma string comprimida
  - gzopen — Abre arquivo gz
  - gzpassthru — Escreve na saída todos os dados restantes em um ponteiro de arquivo gz
  - gzputs — Sinônimo de gzwrite
  - gzread — Leitura de arquivo gz binária segura
  - gzrewind — Retorna ao início a posição de um ponteiro para um arquivo-gz
  - gzseek — Posiciona um ponteiro de arquivo gz
  - gztell — Indica a posição de leitura/gravação em um ponteiro para arquivo-gz
  - gzuncompress — Descomprime uma string comprimida
  - gzwrite — Escrita segura para binário em arquivo-gz
  - inflate_add — Descomprime incrementalmente dados codificados
  - inflate_get_read_len — Obtém o número de bytes lidos até o momento
  - inflate_get_status — Obtém o status da descompressão
  - inflate_init — Inicializa um contexto de descompressão incremental
  - ob_gzhandler — Função de chamada de retorno de ob_start para comprimir o buffer de saída com gzip
  - readgzfile — Exibe um arquivo gz
  - zlib_decode — Descomprime qualquer dado codificado em raw/gzip/zlib
  - zlib_encode — Comprime dados com o codificador especificado
  - zlib_get_coding_type — Retorna o tipo de codificação para a compressão de saída
- DeflateContext — A classe DeflateContext
- InflateContext — A classe InflateContext

- Bzip2
  - Instalação/Configuração
  - Exemplos
  - Bzip2 Funções
- LZF
  - Instalação/Configuração
  - Funções da LZF
- Phar
  - Instalação/Configuração
  - Constantes predefinidas
  - Usando Arquivos Phar
  - Criando Arquivos Phar
  - O que faz um phar ser um phar e não um tar ou um zip?
  - Phar — A classe Phar
  - PharData — A classe PharData
  - PharFileInfo — A classe PharFileInfo
  - PharException — A classe PharException
- Rar — Arquivamento Rar
  - Instalação/Configuração
  - Constantes predefinidas
  - Exemplos
  - Funções de Rar
  - RarArchive — A classe RarArchive
  - RarEntry — A classe RarEntry
  - RarException — A classe RarException
- Zip
  - Instalação/Configuração
  - Constantes predefinidas
  - Exemplos
  - ZipArchive — A classe ZipArchive
  - Funções Zip
- Zlib — Compressão Zlib
  - Instalação/Configuração
  - Constantes predefinidas
  - Exemplos
  - Funções da Zlib
  - DeflateContext — A classe DeflateContext
  - InflateContext — A classe InflateContext

# Extensões para Criptografia

# Estrutura de resumo de mensagens Hash

# Introdução

Esta extensão fornece funções que podem ser usadas para processamento direto ou incremental de mensagens de comprimento arbitrário usando uma variedade de algortimos de hash, incluindo a geração de valores HMAC e derivações chave, incluindo HKDF e PBKDF2.

De forma geral, existem três categorias de algoritmos de hash. Uma lista completa de algoritmos pode ser encontrada na documentação da função hash_algos().

- Algoritmos de soma de verificação (como `"crc32b"` ou `"adler32"`): Estes são usados para calcular somas de verificação, úteis em situações em que erros de transmissão precisam ser detectados. São geralmente muito rápidos. Estes algoritmos frequentemente geram valores que facilmente "previsíveis" ou podem ser manipulados para criar colisões, portanto são totalmente inadequados para uso em criptografia.
- Algoritmos não criptográficos (como a família xxHash): Estes são frequentemente usados para calcular valores de hash para tabelas de hash, já que são projetados para gerar uma boa distribuição sobre strings de entrada arbitrárias. Também são geralmente rápidos, mas também inadequados para uso em criptografia.
- Algoritmos criptográficos (como a família SHA-2): Estes são projetados para gerar valores de hash que são representativos de suas entradas mas não são previsíveis e nem sujeitos a colisões. O desempenho geralmente é uma preocupação secundária, mas os equipamentos modernos frequentemente suportam um gerenciamento especial para estes algoritmos que o PHP tenta fazer uso quando disponível. O Centro de Recursos de Segurança Computacional do NIST tem uma » explicação dos algoritmos atualmente aprovados pelos padrões de processamento de informação dos Estados Unidos.
  Cuidado

  Já foi provado que alguns dos primeiros algoritmos criptográficos, tais como `"md4"`, `"md5"` e `"sha1"`, estão sujeiros a ataques de colisão e por isso é recomendado que não sejam mais usados para aplicações de criptografia.

Consulte também as Perguntas Frequentes sobre Hash Seguro de Senhas para informação sobre melhores práticas para o uso de funções de hash ao lidar com senhas.

# Instalação/Configuração

## Índice

- Instalação
- Tipos de Recurso

## Instalação

A extensão Hash é uma extensão do núcleo do PHP, por isso está sempre habilitada.

Antes do PHP 7.4.0, a extensão Hash era incluída e compilada no PHP por padrão mas podia ser desabilitada explicitamente usando --disable-hash.

Antes do PHP 5.1.2, a extensão Hash era instalada como um » módulo PECL.

## Tipos de Recurso

Esta extensão define um recurso de Contexto de Hash retornado por hash_init().

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`HASH_HMAC` (int)
  Sinalizador opcional para hash_init(). Indica que o algoritmo de chaveamento de digestão HMAC deve ser aplicado ao contexto de hash atual.

# The HashContext class

(PHP 7 >= 7.2.0, PHP 8)

## Introdução

## Resumo da classe

final class HashContext {
/* Métodos */
private function __construct()
public function __debugInfo(): array
public function __serialize(): array
public function __unserialize(array `$data`): void
}

# HashContext::__construct

(PHP 7 >= 7.2.0, PHP 8)

HashContext::__construct — Construtor privado para impedir instanciação direta

### Descrição

private function HashContext::__construct()

### Parâmetros

Esta função não possui parâmetros.

# HashContext::__debugInfo

(PHP 8 >= 8.4.0)

HashContext::__debugInfo — Retorna informação de depuração sobre o contexto de hash

### Descrição

public function HashContext::__debugInfo(): array

Este método não foi feito para ser chamado diretamente; ele é invocado por var_dump() e funções relacionadas ao inspecionar uma instância de HashContext instance.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array associativo com informações de depuração. Ele contém uma chave `algo` com o nome do algoritmo de hash em uso pelo contexto.

### Exemplos

Exemplo #1 Exemplo de HashContext::__debugInfo() example

    <?php
    $ctx = hash_init('sha256');
    var_dump($ctx);
    ?>

O exemplo acima produzirá:

    object(HashContext)#1 (1) {
      ["algo"]=>
      string(6) "sha256"
    }

### Veja Também

- hash_init() - Inicializa um contexto de hash incremental
- var_dump() - Despeja na saída informações sobre uma variável

# HashContext::__serialize

(PHP 8)

HashContext::__serialize — Serializa o objeto HashContext

### Descrição

public function HashContext::__serialize(): array

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

# HashContext::__unserialize

(PHP 8)

HashContext::__unserialize — Desserializa o parâmetro `data` em um objeto HashContext

### Descrição

public function HashContext::__unserialize(array `$data`): void

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`data`

  O valor a ser desserializado.

### Valor Retornado

Nenhum valor é retornado.

## Índice

- HashContext::__construct — Construtor privado para impedir instanciação direta
- HashContext::__debugInfo — Retorna informação de depuração sobre o contexto de hash
- HashContext::__serialize — Serializa o objeto HashContext
- HashContext::__unserialize — Desserializa o parâmetro data em um objeto HashContext

# Hash Funções

# hash

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash — Gera um valor hash (resumo da mensagem)

### Descrição

function hash(
string `$algo`,
string `$data`,
bool `$binary` = `false`,
array `$options` = []
): string

### Parâmetros

`algo`

  Nome do algoritmo de hash selecionado (por exemplo, `"sha256"`). Para uma lista de algoritmos suportados, veja hash_algos().

`data`

  Mensagem a ter o hash gerado.

`binary`

  Quando definido como `true`, gera dados binários brutos. `false` gera caracteres hexadecimais minúsculos.

`options`

  Um array de opções para os vários algoritmos de hash. Atualmente, apenas o parâmetro `"seed"` é suportado pelas variantes MurmurHash.

### Valor Retornado

Retorna uma string contendo o resumo da mensagem calculado como caracteres hexadecimais minúsculos a menos que `binary` seja definido como true, caso em que a representação binária bruta do resumo da mensagem é retornada.

### Erros/Exceções

Lança uma exceção ValueError se `algo` for desconhecido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `options` foi adicionado.
8.0.0 | Agora lança uma exceção ValueError se `algo` for desconhecido; anteriormente, `false` era retornado e uma mensagem `E_WARNING` era emitida.

### Exemplos

Exemplo #1 Um exemplo de hash()

    <?php
    echo hash('sha256', 'The quick brown fox jumped over the lazy dog.');
    ?>

O exemplo acima produzirá:

    68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483

### Veja Também

- hash_init() - Inicializa um contexto de hash incremental
- hash_file() - Gera um valor hash usando o conteúdo de um arquivo fornecido
- hash_hmac() - Gera um valor de hash com chave usando o método HMAC

# hash_algos

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_algos — Retorna uma lista de algoritmos de hash registrados

### Descrição

function hash_algos(): array

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array indexado numericamente contendo a lista de algoritmos de hash suportados.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Foi adicionado suporte para algoritmos MurmurHash3 e xxHash.
7.4.0 | Foi adicionado suporte para crc32c.
7.1.0 | Suporte para sha512/224, sha512/256, sha3-224, sha3-256, sha3-384 e sha3-512 foi adicionado.

### Exemplos

Exemplo #1 Exemplo de hash_algos()

A partir do PHP 8.1.0, hash_algos() retornará a seguinte lista de nomes de algoritmos.

    <?php
    print_r(hash_algos());
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => md2
        [1] => md4
        [2] => md5
        [3] => sha1
        [4] => sha224
        [5] => sha256
        [6] => sha384
        [7] => sha512/224
        [8] => sha512/256
        [9] => sha512
        [10] => sha3-224
        [11] => sha3-256
        [12] => sha3-384
        [13] => sha3-512
        [14] => ripemd128
        [15] => ripemd160
        [16] => ripemd256
        [17] => ripemd320
        [18] => whirlpool
        [19] => tiger128,3
        [20] => tiger160,3
        [21] => tiger192,3
        [22] => tiger128,4
        [23] => tiger160,4
        [24] => tiger192,4
        [25] => snefru
        [26] => snefru256
        [27] => gost
        [28] => gost-crypto
        [29] => adler32
        [30] => crc32
        [31] => crc32b
        [32] => crc32c
        [33] => fnv132
        [34] => fnv1a32
        [35] => fnv164
        [36] => fnv1a64
        [37] => joaat
        [38] => murmur3a
        [39] => murmur3c
        [40] => murmur3f
        [41] => xxh32
        [42] => xxh64
        [43] => xxh3
        [44] => xxh128
        [45] => haval128,3
        [46] => haval160,3
        [47] => haval192,3
        [48] => haval224,3
        [49] => haval256,3
        [50] => haval128,4
        [51] => haval160,4
        [52] => haval192,4
        [53] => haval224,4
        [54] => haval256,4
        [55] => haval128,5
        [56] => haval160,5
        [57] => haval192,5
        [58] => haval224,5
        [59] => haval256,5
    )

### Veja Também

- hash() - Gera um valor hash (resumo da mensagem)
- hash_hmac_algos() - Retorna uma lista de algoritmos de hash registrados adequados para hash_hmac

# hash_copy

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

hash_copy — Copia contexto de hash

### Descrição

function hash_copy(HashContext `$context`): HashContext

### Parâmetros

`context`

  Contexto de hash retornado por hash_init().

### Valor Retornado

Retorna uma cópia do contexto de hash.

### Registro de Alterações

Versão | Descrição
--- | ---
7.2.0 | Aceita e retorna HashContext em vez de recurso.

### Exemplos

Exemplo #1 Exemplo de hash_copy()

    <?php
    $context = hash_init("sha256");
    hash_update($context, "The quick brown fox ");

    /* copia o contexto para poder continuar a usá-lo */
    $copy_context = hash_copy($context);

    echo hash_final($context), "\n";

    hash_update($copy_context, "jumped over the lazy dog.");
    echo hash_final($copy_context), "\n";
    ?>

O exemplo acima produzirá:

    b29d66e56ed90cce9b0165c43fedec612b60a071974d8be4513e18580d55b5bd
    68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483

# hash_equals

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

hash_equals — Comparação de strings segura para ataque de temporização

### Descrição

function hash_equals(#[\SensitiveParameter]string `$known_string`, #[\SensitiveParameter]string `$user_string`): bool

Verifica se duas strings são iguais sem vazar informações sobre o conteúdo de `known_string` por meio do tempo de execução.

Esta função pode ser usada para mitigar ataques de temporização. Executar uma comparação regular com `===` levará mais ou menos tempo para executar dependendo se os dois valores são diferentes ou não e em qual posição a primeira diferença pode ser encontrada, vazando assim informações sobre o conteúdo do `known_string` secreto.

Cuidado

É importante fornecer a string fornecida pelo usuário como o segundo parâmetro, em vez do primeiro.

### Parâmetros

`known_string`

  A string conhecida que deve ser mantida em segredo.

`user_string`

  A string fornecida pelo usuário para comparação.

### Valor Retornado

Retorna `true` quando as duas strings são iguais, `false` caso contrário.

### Exemplos

Exemplo #1 Exemplo de hash_equals()

    <?php
    $secretKey = '8uRhAeH89naXfFXKGOEj';

    // O valor e a assinatura são fornecidos pelo usuário, por exemplo, dentro da URL
    // e recuperados usando $_GET.
    $value = 'username=rasmuslerdorf';
    $signature = '8c35009d3b50caf7f5d2c1e031842e6b7823a1bb781d33c5237cd27b57b5f327';

    if (hash_equals(hash_hmac('sha256', $value, $secretKey), $signature)) {
        echo "O valor está assinado corretamente.", PHP_EOL;
    } else {
        echo "O valor foi adulterado.", PHP_EOL;
    }
    ?>

O exemplo acima produzirá:

    O valor está assinado corretamente.

### Notas

> Nota:

> Ambos os argumentos devem ter o mesmo comprimento para serem comparados com sucesso. Quando argumentos de comprimentos diferentes são fornecidos, `false` é retornado imediatamente e o comprimento da string conhecida pode ser vazado em caso de um ataque de temporização.

### Veja Também

- hash_hmac() - Gera um valor de hash com chave usando o método HMAC

# hash_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_file — Gera um valor hash usando o conteúdo de um arquivo fornecido

### Descrição

function hash_file(
string `$algo`,
string `$filename`,
bool `$binary` = `false`,
array `$options` = []
): string|false

### Parâmetros

`algo`

  Nome do algoritmo de hash selecionado (por exemplo, `"sha256"`). Para uma lista de algoritmos suportados, veja hash_algos().

`filename`

  URL que descreve o local do arquivo a ter o hash gerado; Suporta empacotadores fopen().

`binary`

  Quando definido como `true`, gera dados binários brutos. `false` caracteres gera hexadecimais minúsculos.

`options`

  Um array de opções para os vários algoritmos de hash. Atualmente, apenas o parâmetro `"seed"` é suportado pelas variantes MurmurHash.

### Valor Retornado

Retorna uma string contendo o resumo da mensagem calculado como caracteres hexadecimais minúsculos a menos que `binary` seja definido como true, caso em que a representação binária bruta do resumo da mensagem é retornada, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `options` foi adicionado.

### Exemplos

Exemplo #1 Usando hash_file()

    <?php
    /* Cria um arquivo para cálculo de seu hash */
    file_put_contents('example.txt', 'The quick brown fox jumped over the lazy dog.');

    echo hash_file('sha256', 'example.txt');
    ?>

O exemplo acima produzirá:

    68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483

### Veja Também

- hash_init() - Inicializa um contexto de hash incremental
- hash_hmac_file() - Gera um valor hash com chave usando o método HMAC e o conteúdo de um arquivo fornecido

# hash_final

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_final — Finaliza um hash incremental e retorna o resumo resultante

### Descrição

function hash_final(HashContext `$context`, bool `$binary` = `false`): string

### Parâmetros

`context`

  Contexto de hash retornado por hash_init().

`binary`

  Quando definido como `true`, gera dados binários brutos. `false` gera caracteres hexadecimais minúsculos.

### Valor Retornado

Retorna uma string contendo o resumo da mensagem calculado como caracteres hexadecimais minúsculos a menos que `binary` seja definido como true, caso em que a representação binária bruta do resumo da mensagem é retornada.

### Registro de Alterações

Versão | Descrição
--- | ---
7.2.0 | Aceita HashContext em vez de recurso.

### Veja Também

- hash_init() - Inicializa um contexto de hash incremental
- hash_update() - Injeta dados em um contexto de hash ativo
- hash_update_stream() - Injeta dados em um contexto de hash ativo a partir de um fluxo
- hash_update_file() - Injeta dados em um contexto de hash ativo a partir de um arquivo

# hash_hkdf

(PHP 7 >= 7.1.2, PHP 8)

hash_hkdf — Gera uma derivação de chave HKDF de uma entrada de chave fornecida

### Descrição

function hash_hkdf(
string `$algo`,
#[\SensitiveParameter]string `$key`,
int `$length` = 0,
string `$info` = "",
string `$salt` = ""
): string

### Parâmetros

`algo`

  Nome do algoritmo de hash selecionado (por exemplo, `"sha256"`). Para uma lista de algoritmos suportados, veja hash_hmac_algos().

  > Nota:

  > Funções de hash não criptográficas não são permitidas.

`key`

  Material de chaveamento de entrada (binário bruto). Não pode estar vazio.

`length`

  Comprimento de saída desejado em bytes. Não pode ser maior que 255 vezes o tamanho da função hash escolhida.

  Se `length` for `0`, o comprimento de saída será definido como padrão para o tamanho da função hash escolhida.

`info`

  String de informação específica da aplicação/contexto.

`salt`

  Salt a ser usado na derivação.

  Embora opcional, adicionar salt aleatório melhora significativamente a força do HKDF.

### Valor Retornado

Retorna uma string contendo uma representação binária bruta da chave derivada (também conhecida como material de chaveamento de saída - OKM).

### Erros/Exceções

Lança uma exceção ValueError se `key` estiver vazio, `algo` for desconhecido ou não criptográfico, `length` for menor que `0` ou muito grande (maior que 255 vezes o tamanho da função hash).

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Agora lança uma exceção ValueError em caso de erro. Anteriormente, `false` era retornado e uma mensagem `E_WARNING` era emitida.

### Exemplos

O exemplo abaixo produz um par de chaves separadas, adequadas para a criação de uma construção de criptografia seguida de HMAC, usando AES-256 e SHA-256 para criptografia e autenticação, respectivamente.

Exemplo #1 Exemplo de hash_hkdf()

    <?php
    // Gera uma chave aleatória e adiciona um salt para fortalecê-la durante a derivação.
    $inputKey = random_bytes(32);
    $salt = random_bytes(16);

    // Deriva um par de chaves separadas, usando a mesma entrada criada acima.
    $encryptionKey = hash_hkdf('sha256', $inputKey, 32, 'aes-256-encryption', $salt);
    $authenticationKey = hash_hkdf('sha256', $inputKey, 32, 'sha-256-authentication', $salt);

    var_dump($encryptionKey !== $authenticationKey); // bool(true)
    ?>

### Veja Também

- hash_pbkdf2() - Gera uma derivação de chave PBKDF2 de uma senha fornecida
- » RFC 5869
- » implementação do usuário

# hash_hmac

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_hmac — Gera um valor de hash com chave usando o método HMAC

### Descrição

function hash_hmac(
string `$algo`,
string `$data`,
#[\SensitiveParameter]string `$key`,
bool `$binary` = `false`
): string

### Parâmetros

`algo`

  Nome do algoritmo de hash selecionado (por exemplo, `"sha256"`). Para uma lista de algoritmos suportados, veja hash_hmac_algos().

  > Nota:

  > Funções de hash não criptográficas não são permitidas.

`data`

  Mensagem a ter o hash gerado.

`key`

  Chave secreta compartilhada usada para gerar a variante HMAC do resumo da mensagem.

`binary`

  Quando definido como `true`, gera dados binários brutos. `false` gera caracteres hexadecimais minúsculos.

### Valor Retornado

Retorna uma string contendo o resumo da mensagem calculado como caracteres hexadecimais minúsculos a menos que `binary` seja definido como true, caso em que a representação binária bruta do resumo da mensagem é retornada.

### Erros/Exceções

Lança uma exceção ValueError se `algo` for desconhecido ou for uma função hash não criptográfica.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Agora lança uma exceção ValueError se `algo` for desconhecido ou for uma função hash não criptográfica; anteriormente, `false` era retornado e uma mensagem `E_WARNING` era emitida.
7.2.0 | O uso de funções de hash não criptográficas (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) foi desabilitado.

### Exemplos

Exemplo #1 Exemplo de hash_hmac()

    <?php
    echo hash_hmac('sha256', 'The quick brown fox jumped over the lazy dog.', 'secret');
    ?>

O exemplo acima produzirá:

    9c5c42422b03f0ee32949920649445e417b2c634050833c5165704b825c2a53b

### Veja Também

- hash_hmac_algos() - Retorna uma lista de algoritmos de hash registrados adequados para hash_hmac
- hash_hmac_file() - Gera um valor hash com chave usando o método HMAC e o conteúdo de um arquivo fornecido
- hash_equals() - Comparação de strings segura para ataque de temporização

# hash_hmac_algos

(PHP 7 >= 7.2.0, PHP 8)

hash_hmac_algos — Retorna uma lista de algoritmos de hash registrados adequados para hash_hmac

### Descrição

function hash_hmac_algos(): array

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array indexado numericamente contendo a lista de algoritmos de hash suportados adequados para hash_hmac().

### Exemplos

Exemplo #1 Exemplo de hash_hmac_algos()

    <?php
    print_r(hash_hmac_algos());

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => md2
        [1] => md4
        [2] => md5
        [3] => sha1
        [4] => sha224
        [5] => sha256
        [6] => sha384
        [7] => sha512/224
        [8] => sha512/256
        [9] => sha512
        [10] => sha3-224
        [11] => sha3-256
        [12] => sha3-384
        [13] => sha3-512
        [14] => ripemd128
        [15] => ripemd160
        [16] => ripemd256
        [17] => ripemd320
        [18] => whirlpool
        [19] => tiger128,3
        [20] => tiger160,3
        [21] => tiger192,3
        [22] => tiger128,4
        [23] => tiger160,4
        [24] => tiger192,4
        [25] => snefru
        [26] => snefru256
        [27] => gost
        [28] => gost-crypto
        [29] => haval128,3
        [30] => haval160,3
        [31] => haval192,3
        [32] => haval224,3
        [33] => haval256,3
        [34] => haval128,4
        [35] => haval160,4
        [36] => haval192,4
        [37] => haval224,4
        [38] => haval256,4
        [39] => haval128,5
        [40] => haval160,5
        [41] => haval192,5
        [42] => haval224,5
        [43] => haval256,5
    )

### Notas

> Nota:

> Antes do PHP 7.2.0, o único meio de obter uma lista de algoritmos de hash suportados era chamar hash_algos() que também retorna algoritmos de hash que não são adequados para hash_hmac().

### Veja Também

- hash_hmac() - Gera um valor de hash com chave usando o método HMAC
- hash_algos() - Retorna uma lista de algoritmos de hash registrados

# hash_hmac_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_hmac_file — Gera um valor hash com chave usando o método HMAC e o conteúdo de um arquivo fornecido

### Descrição

function hash_hmac_file(
string `$algo`,
string `$filename`,
#[\SensitiveParameter]string `$key`,
bool `$binary` = `false`
): string|false

### Parâmetros

`algo`

  Nome do algoritmo de hash selecionado (por exemplo, `"sha256"`). Para uma lista de algoritmos suportados, veja hash_hmac_algos().

  > Nota:

  > Funções de hash não criptográficas não são permitidas.

`filename`

  URL descrevendo o local do arquivo a ter o hash gerado; Suporta empacotadores fopen.

`key`

  Chave secreta compartilhada usada para gerar a variante HMAC do resumo da mensagem.

`binary`

  Quando definido como `true`, gera dados binários brutos. `false` gera caracteres hexadecimais minúsculos.

### Valor Retornado

Retorna uma string contendo o resumo da mensagem calculado como caracteres hexadecimais minúsculos a menos que `binary` esteja definido como true, caso em que a representação binária bruta do resumo da mensagem é retornada. Retorna `false` se o arquivo `filename` não puder ser lido.

### Erros/Exceções

Lança uma exceção ValueError se `algo` for desconhecido ou for uma função hash não criptográfica.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Agora lança uma exceção ValueError se `algo` for desconhecido ou for uma função hash não criptográfica; anteriormente, `false` era retornado e uma mensagem `E_WARNING` era emitida.
7.2.0 | O uso de funções de hash não criptográficas (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) foi desabilitado.

### Exemplos

Exemplo #1 Exemplo de hash_hmac_file()

    <?php
    /*  Cria um arquivo para cálculo de seu hash */
    file_put_contents('example.txt', 'The quick brown fox jumped over the lazy dog.');

    echo hash_hmac_file('sha256', 'example.txt', 'secret');
    ?>

O exemplo acima produzirá:

    9c5c42422b03f0ee32949920649445e417b2c634050833c5165704b825c2a53b

### Veja Também

- hash_hmac() - Gera um valor de hash com chave usando o método HMAC
- hash_hmac_algos() - Retorna uma lista de algoritmos de hash registrados adequados para hash_hmac
- hash_init() - Inicializa um contexto de hash incremental
- hash_equals() - Comparação de strings segura para ataque de temporização

# hash_init

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_init — Inicializa um contexto de hash incremental

### Descrição

function hash_init(
string `$algo`,
int `$flags` = 0,
#[\SensitiveParameter]string `$key` = "",
array `$options` = []
): HashContext

### Parâmetros

`algo`

  Nome do algoritmo de hash selecionado (por exemplo, `"sha256"`). Para uma lista de algoritmos suportados, veja hash_algos().

  > Nota:

  > Funções de hash não criptográficas não são permitidas se o sinalizador `HASH_HMAC` for especificado.

`flags`

  Configurações opcionais para geração de hash, atualmente suporta apenas uma opção: `HASH_HMAC`. Quando especificado, o `key` precisa ser especificado.

`key`

  Quando `HASH_HMAC` é especificado para `flags`, uma chave secreta compartilhada a ser usada com o método de hash HMAC deve ser fornecida neste parâmetro.

`options`

  Um array de opções para os vários algoritmos de hash. Atualmente, apenas o parâmetro `"seed"` é suportado pelas variantes MurmurHash.

### Valor Retornado

Retorna um contexto de hash para uso com hash_update(), hash_update_stream(), hash_update_file(), e hash_final().

### Erros/Exceções

- Lança uma exceção ValueError se `algo` for desconhecido ou for uma função hash não criptográfica ou se `key` estiver vazio.
- Passar opções de configuração do tipo errado em `options` agora emitirá um erro `E_DEPRECATED` porque elas podem ser interpretadas incorretamente. Isso se tornará um ValueError no futuro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Passar opções de um tipo errado foi descontinuado.
8.1.0 | O parâmetro `options` foi adicionado.
8.0.0 | Agora lança uma exceção ValueError se o `algo` for desconhecido ou for uma função hash não criptográfica ou se `key` estiver vazio. Anteriormente, `false` era retornado e uma mensagem `E_WARNING` era emitida.
7.2.0 | O uso de funções hash não criptográficas (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) com `HASH_HMAC` foi desabilitado.
7.2.0 | Retorna HashContext em vez de recurso.

### Exemplos

Exemplo #1 Exemplo de hash incremental

    <?php
    $hash = hash('sha256', 'The quick brown fox jumped over the lazy dog.');

    $ctx = hash_init('sha256');
    hash_update($ctx, 'The quick brown fox ');
    hash_update($ctx, 'jumped over the lazy dog.');
    $incremental_hash = hash_final($ctx);

    echo $incremental_hash, PHP_EOL;
    var_dump($hash === $incremental_hash);
    ?>

O exemplo acima produzirá:

    68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483
    bool(true)

### Veja Também

- hash_algos() - Retorna uma lista de algoritmos de hash registrados
- hash_update() - Injeta dados em um contexto de hash ativo
- hash_update_file() - Injeta dados em um contexto de hash ativo a partir de um arquivo
- hash_update_stream() - Injeta dados em um contexto de hash ativo a partir de um fluxo
- hash_final() - Finaliza um hash incremental e retorna o resumo resultante

# hash_pbkdf2

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

hash_pbkdf2 — Gera uma derivação de chave PBKDF2 de uma senha fornecida

### Descrição

function hash_pbkdf2(
string `$algo`,
#[\SensitiveParameter]string `$password`,
string `$salt`,
int `$iterations`,
int `$length` = 0,
bool `$binary` = `false`,
array `$options` = []
): string

### Parâmetros

`algo`

  Nome do algoritmo de hash selecionado (por exemplo, `"sha256"`). Para uma lista de algoritmos suportados, veja hash_hmac_algos().

  > Nota:

  > Funções de hash não criptográficas não são permitidas.

`password`

  A senha a ser usada para a derivação.

`salt`

  O salt a ser usado para a derivação. Este valor deve ser gerado aleatoriamente.

`iterations`

  O número de iterações internas a serem executadas para a derivação.

`length`

  O comprimento da string de saída. Se `binary` for `true` isso corresponde ao comprimento em bytes da chave derivada, se `binary` for `false` isso corresponde ao dobro do comprimento em bytes da chave derivada (pois cada byte da chave é retornado como dois caracteres hexadecimais).

  Se `0` for passado, toda a saída do algoritmo fornecido será usada.

`binary`

  Quando definido como `true`, gera dados binários brutos. `false` gera caracteres hexadecimais minúsculos.

`options`

  Um array de opções para os vários algoritmos de hash. Atualmente, apenas a chave `"seed"` é suportada pelas variantes MurmurHash.

### Valor Retornado

Retorna uma string contendo a chave derivada como hexadecimais minúsculos, a menos que `binary` esteja definido como `true`, nesse caso, a representação binária bruta da chave derivada é retornada.

### Erros/Exceções

Lança uma exceção ValueError se o algoritmo for desconhecido, o parâmetro `iterations` for menor ou igual a `0`, o parâmetro `length` for menor que `0` ou o parâmetro `salt` for muito longo (maior que `INT_MAX``- 4`).

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Agora lança uma exceção ValueError em caso de erro. Anteriormente, `false` era retornado e uma mensagem `E_WARNING` era emitida.
7.2.0 | O uso de funções de hash não criptográficas (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) foi desabilitado.

### Exemplos

Exemplo #1 Exemplo de hash_pbkdf2(), uso básico

    <?php
    $password = "password";
    $iterations = 600000;

    // Gera um salt aleatório criptograficamente seguro usando random_bytes()
    $salt = random_bytes(16);

    $hash = hash_pbkdf2("sha256", $password, $salt, $iterations, 20);
    var_dump($hash);

    // para binário bruto, $length precisa ser reduzido pela metade para resultados equivalentes
    $hash = hash_pbkdf2("sha256", $password, $salt, $iterations, 10, true);
    var_dump(bin2hex($hash));?>

O exemplo acima produzirá algo semelhante a:

    string(20) "120fb6cffcf8b32c43e7"
    string(20) "120fb6cffcf8b32c43e7"

### Notas

Cuidado

O método PBKDF2 pode ser usado para fazer hash de senhas para armazenamento. No entanto, deve ser notado que password_hash() ou crypt() com `CRYPT_BLOWFISH` são mais adequados para armazenamento de senhas.

### Veja Também

- password_hash() - Cria um hash de senha
- hash_hkdf() - Gera uma derivação de chave HKDF de uma entrada de chave fornecida
- sodium_crypto_pwhash() - Deriva uma chave de uma senha, usando Argon2

# hash_update

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_update — Injeta dados em um contexto de hash ativo

### Descrição

function hash_update(HashContext `$context`, string `$data`): true

### Parâmetros

`context`

  Contexto de hash retornado por hash_init().

`data`

  Mensagem a ser incluída no resumo do hash.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Agora tem um tipo de retorno de true em vez de bool.
7.2.0 | Aceita HashContext em vez de recurso.

### Veja Também

- hash_init() - Inicializa um contexto de hash incremental
- hash_update_file() - Injeta dados em um contexto de hash ativo a partir de um arquivo
- hash_update_stream() - Injeta dados em um contexto de hash ativo a partir de um fluxo
- hash_final() - Finaliza um hash incremental e retorna o resumo resultante

# hash_update_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_update_file — Injeta dados em um contexto de hash ativo a partir de um arquivo

### Descrição

function hash_update_file(HashContext `$context`, string `$filename`, ?resource `$stream_context` = `null`): bool

### Parâmetros

`context`

  Contexto de hash retornado por hash_init().

`filename`

  URL que descreve o local do arquivo a ser hash; Suporta empacotadores fopen().

`stream_context`

  Contexto de fluxo conforme retornado por stream_context_create().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `stream_context` agora pode ser nulo.
7.2.0 | Aceita HashContext no lugar de um recurso.

### Veja Também

- hash_init() - Inicializa um contexto de hash incremental
- hash_update() - Injeta dados em um contexto de hash ativo
- hash_update_stream() - Injeta dados em um contexto de hash ativo a partir de um fluxo
- hash_final() - Finaliza um hash incremental e retorna o resumo resultante
- hash_file() - Gera um valor hash usando o conteúdo de um arquivo fornecido

# hash_update_stream

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_update_stream — Injeta dados em um contexto de hash ativo a partir de um fluxo

### Descrição

function hash_update_stream(HashContext `$context`, resource `$stream`, int `$length` = -1): int

### Parâmetros

`context`

  Contexto de hash retornado por hash_init().

`stream`

  Identificador de arquivo aberto conforme retornado por qualquer função de criação de fluxo.

`length`

  Número máximo de caracteres a serem copiados de `stream` para o contexto de hash.

### Valor Retornado

Número real de bytes adicionados ao contexto de hash de `stream`.

### Registro de Alterações

Versão | Descrição
--- | ---
7.2.0 | Aceita HashContext em vez de recurso.

### Exemplos

Exemplo #1 Exemplo de hash_update_stream()

    <?php
    $fp = tmpfile();
    fwrite($fp, 'jumped over the lazy dog.');
    rewind($fp);

    $ctx = hash_init('sha256');
    hash_update($ctx, 'The quick brown fox ');
    hash_update_stream($ctx, $fp);
    echo hash_final($ctx);
    ?>

O exemplo acima produzirá:

    68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483

### Veja Também

- hash_init() - Inicializa um contexto de hash incremental
- hash_update() - Injeta dados em um contexto de hash ativo
- hash_final() - Finaliza um hash incremental e retorna o resumo resultante

## Índice

- hash — Gera um valor hash (resumo da mensagem)
- hash_algos — Retorna uma lista de algoritmos de hash registrados
- hash_copy — Copia contexto de hash
- hash_equals — Comparação de strings segura para ataque de temporização
- hash_file — Gera um valor hash usando o conteúdo de um arquivo fornecido
- hash_final — Finaliza um hash incremental e retorna o resumo resultante
- hash_hkdf — Gera uma derivação de chave HKDF de uma entrada de chave fornecida
- hash_hmac — Gera um valor de hash com chave usando o método HMAC
- hash_hmac_algos — Retorna uma lista de algoritmos de hash registrados adequados para hash_hmac
- hash_hmac_file — Gera um valor hash com chave usando o método HMAC e o conteúdo de um arquivo fornecido
- hash_init — Inicializa um contexto de hash incremental
- hash_pbkdf2 — Gera uma derivação de chave PBKDF2 de uma senha fornecida
- hash_update — Injeta dados em um contexto de hash ativo
- hash_update_file — Injeta dados em um contexto de hash ativo a partir de um arquivo
- hash_update_stream — Injeta dados em um contexto de hash ativo a partir de um fluxo

- Instalação/Configuração
  - Instalação
  - Tipos de Recurso
- Constantes predefinidas
- HashContext — The HashContext class
  - HashContext::__construct — Construtor privado para impedir instanciação direta
  - HashContext::__debugInfo — Retorna informação de depuração sobre o contexto de hash
  - HashContext::__serialize — Serializa o objeto HashContext
  - HashContext::__unserialize — Desserializa o parâmetro data em um objeto HashContext
- Hash Funções
  - hash — Gera um valor hash (resumo da mensagem)
  - hash_algos — Retorna uma lista de algoritmos de hash registrados
  - hash_copy — Copia contexto de hash
  - hash_equals — Comparação de strings segura para ataque de temporização
  - hash_file — Gera um valor hash usando o conteúdo de um arquivo fornecido
  - hash_final — Finaliza um hash incremental e retorna o resumo resultante
  - hash_hkdf — Gera uma derivação de chave HKDF de uma entrada de chave fornecida
  - hash_hmac — Gera um valor de hash com chave usando o método HMAC
  - hash_hmac_algos — Retorna uma lista de algoritmos de hash registrados adequados para hash_hmac
  - hash_hmac_file — Gera um valor hash com chave usando o método HMAC e o conteúdo de um arquivo fornecido
  - hash_init — Inicializa um contexto de hash incremental
  - hash_pbkdf2 — Gera uma derivação de chave PBKDF2 de uma senha fornecida
  - hash_update — Injeta dados em um contexto de hash ativo
  - hash_update_file — Injeta dados em um contexto de hash ativo a partir de um arquivo
  - hash_update_stream — Injeta dados em um contexto de hash ativo a partir de um fluxo

# Mcrypt

# Introdução

Aviso

Este recurso foi DESCONTINUADO a partir do PHP 7.1.0 e foi REMOVIDO a partir do PHP 7.2.0.

Alternativas a este recurso incluem:

- Sodium (disponível a partir do PHP 7.2.0)
- OpenSSL

> Nota: Esta extensão foi movida para o repositório » PECL e não é mais distribuída com o PHP desde a versão 7.2.0.

Esta é uma interface para a biblioteca mcrypt, que suporta uma ampla variedade de algoritmos de bloco, como DES, TripleDES, Blowfish (padrão), 3-WAY, SAFER-SK64, SAFER-SK128, TWOFISH, TEA, RC2 e GOST nos modos de cifra CBC, OFB, CFB e ECB. Além disso, suporta RC6 e IDEA, que são considerados "não livres". CFB/OFB são 8 bits por padrão.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução
- Tipos de Recurso

## Dependências

Essas funções utilizam » mcrypt. Para utilizá-lo, faça o download do libmcrypt-x.x.tar.gz em » http://mcrypt.sourceforge.net/ e siga as instruções de instalação incluídas.

A versão 2.5.6 ou superior do libmcrypt é necessária.

Usuários do Windows encontrarão a biblioteca nas versões binárias do PHP 5.2. As versões binárias do PHP 5.3 utilizam a versão estática da biblioteca MCrypt, sem a necessidade de DLLs.

Se você vinculou com libmcrypt 2.4.x ou superior, os seguintes algoritmos de bloco adicionais são suportados: CAST, LOKI97, RIJNDAEL, SAFERPLUS, SERPENT, e os seguintes cifradores de fluxo: ENIGMA (crypt), PANAMA, RC4 e WAKE. Com libmcrypt 2.4.x ou superior, um outro modo de cifragem também está disponível; nOFB.

## Instalação

Esta extensão foi movida para o repositório » PECL e não é mais distribuída com o PHP desde a versão 7.2.0

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/mcrypt.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de Configuração do Mcrypt
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
mcrypt.algorithms_dir | `null` | `INI_ALL` |
mcrypt.modes_dir | `null` | `INI_ALL` |

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`mcrypt.algorithms_dir` string
  O diretório que contém os algoritmos. Padrão para os diretórios compilados dentro do libmcrypt, que é tipicamente /usr/local/lib/libmcrypt. Consulte mcrypt_list_algorithms() para detalhes adicionais.
`mcrypt.modes_dir` string
  O diretório que contém os modos. Padrão para os diretórios compilados dentro do libmcrypt, que é tipicamente /usr/local/lib/libmcrypt. Consulte mcrypt_list_modes() para detalhes adicionais.

## Tipos de Recurso

mcrypt_module_open() retorna um descritor de criptografia.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

Mcrypt pode operar em quatro modos de cifra de bloco (`CBC`, `OFB`, `CFB` e `ECB`). Se vinculado à libmcrypt-2.4.x ou superior, as funções também podem operar no modo de cifra de bloco `nOFB` e no modo `STREAM`. Abaixo você encontra uma lista com todos modos de criptografia suportados juntamente com as constantes que são definidas para o modo de criptografia. Para uma referência mais completa e discussão, consulte Applied Cryptography by Schneier (ISBN 0-471-11709-9).

- `MCRYPT_MODE_ECB` (`electronic codebook`) é um modo de cifra de bloco geralmente inadequado para a maioria dos propósitos. O uso deste modo não é recomendado.
- `MCRYPT_MODE_CBC` (`cipher block chaining`) é um modo de cifra de bloco significativamente mais seguro do que o modo `ECB`.
- `MCRYPT_MODE_CFB` (`cipher feedback, em modo de 8 bits`) é um modo de cifra de fluxo. É recomendado usar o modo `NCFB` em vez de modo `CFB`.
- `MCRYPT_MODE_OFB` (`output feedback, em modo de 8 bits`) é um modo de cifra de fluxo comparável a `CFB`, mas pode ser usado em aplicações onde a propagação de erros não pode ser tolerada. Recomenda-se usar o modo `NOFB` em vez de modo `OFB`.
- `MCRYPT_MODE_NOFB` (`output feedback, em modo n-bit`) é comparável ao modo `OFB`, mas opera no tamanho completo do bloco do algoritmo.
- `MCRYPT_MODE_STREAM` é um modo extra para incluir alguns algoritmos de fluxo como `"WAKE"` ou `"RC4"`.

Mcrypt suporta alguns outros modos de operação para os quais não existem constantes predefinidas. Eles podem ser utilizados passando uma string no lugar das constantes ausentes.

- `"ctr"` (`counter mode`) é um modo de cifra de fluxo.
- `"ncfb"` (`cipher feedback, em modo n-bit`) é comparável ao modo `CFB`, mas opera no tamanho completo do bloco do algoritmo.

Algumas outras constantes de modo e dispositivo aleatório:

`MCRYPT_ENCRYPT` (int)
`MCRYPT_DECRYPT` (int)
`MCRYPT_DEV_RANDOM` (int)
`MCRYPT_DEV_URANDOM` (int)
`MCRYPT_RAND` (int)

# Cifras de Mcrypt

Aqui está uma lista de cifras que são atualmente suportadas pela extensão mcrypt. Para uma lista completa de cifras suportadas, consulte as definições no final do arquivo mcrypt.h. A regra geral com a API mcrypt-2.2.x é que a cifra pode ser acessada no PHP com MCRYPT_ciphername. Com as APIs libmcrypt-2.4.x e libmcrypt-2.5.x, essas constantes também funcionam, mas é possível especificar o nome da cifra como uma string com uma chamada a mcrypt_module_open().

- MCRYPT_3DES
- MCRYPT_ARCFOUR_IV (libmcrypt > 2.4.x somente)
- MCRYPT_ARCFOUR (libmcrypt > 2.4.x somente)
- MCRYPT_BLOWFISH
- MCRYPT_CAST_128
- MCRYPT_CAST_256
- MCRYPT_CRYPT
- MCRYPT_DES
- MCRYPT_DES_COMPAT (libmcrypt 2.2.x somente)
- MCRYPT_ENIGMA (libmcrypt > 2.4.x somente, alias para MCRYPT_CRYPT)
- MCRYPT_GOST
- MCRYPT_IDEA (não-livre)
- MCRYPT_LOKI97 (libmcrypt > 2.4.x somente)
- MCRYPT_MARS (libmcrypt > 2.4.x somente, não-livre)
- MCRYPT_PANAMA (libmcrypt > 2.4.x somente)
- MCRYPT_RIJNDAEL_128 (libmcrypt > 2.4.x somente)
- MCRYPT_RIJNDAEL_192 (libmcrypt > 2.4.x somente)
- MCRYPT_RIJNDAEL_256 (libmcrypt > 2.4.x somente)
- MCRYPT_RC2
- MCRYPT_RC4 (libmcrypt 2.2.x somente)
- MCRYPT_RC6 (libmcrypt > 2.4.x somente)
- MCRYPT_RC6_128 (libmcrypt 2.2.x somente)
- MCRYPT_RC6_192 (libmcrypt 2.2.x somente)
- MCRYPT_RC6_256 (libmcrypt 2.2.x somente)
- MCRYPT_SAFER64
- MCRYPT_SAFER128
- MCRYPT_SAFERPLUS (libmcrypt > 2.4.x somente)
- MCRYPT_SERPENT(libmcrypt > 2.4.x somente)
- MCRYPT_SERPENT_128 (libmcrypt 2.2.x somente)
- MCRYPT_SERPENT_192 (libmcrypt 2.2.x somente)
- MCRYPT_SERPENT_256 (libmcrypt 2.2.x somente)
- MCRYPT_SKIPJACK (libmcrypt > 2.4.x somente)
- MCRYPT_TEAN (libmcrypt 2.2.x somente)
- MCRYPT_THREEWAY
- MCRYPT_TRIPLEDES (libmcrypt > 2.4.x somente)
- MCRYPT_TWOFISH (para versões antigas do mcrypt 2.x ou mcrypt > 2.4.x)
- MCRYPT_TWOFISH128 (TWOFISHxxx estão disponíveis em versões mais recentes 2.x versions, mas não nas versões 2.4.x)
- MCRYPT_TWOFISH192
- MCRYPT_TWOFISH256
- MCRYPT_WAKE (libmcrypt > 2.4.x somente)
- MCRYPT_XTEA (libmcrypt > 2.4.x somente)

É obrigatório (nos modos `CFB` e `OFB`) ou opcional (no modo `CBC`) fornecer um vetor de inicialização (IV) para a função de criptografia respectiva. O IV deve ser único e deve ser o mesmo ao descriptografar/criptografar. Com dados que são armazenados criptografados, pode-se pegar a saída de uma função do índice sob o qual o dados são armazenados (por exemplo, a chave MD5 do nome do arquivo). Alternativamente, pode-se transmitir o IV junto com os dados criptografados (consulte o capítulo 9.3 de Applied Cryptography by Schneier (ISBN 0-471-11709-9) para uma discussão sobre esse tópico).

# Mcrypt Funções

# mcrypt_create_iv

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_create_iv — Cria um vetor de inicialização (IV) a partir de uma fonte aleatória

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0.

Alternativas a esta função incluem:

- random_bytes()

### Descrição

function mcrypt_create_iv(int `$size`, int `$source` = MCRYPT_DEV_URANDOM): string

Cria um vetor de inicialização (IV) a partir de uma fonte aleatória.

O IV serve apenas para dar uma semente alternativa às rotinas de criptografia. Este IV não precisa ser secreto, embora possa ser desejável. Pode-se até mesmo enviá-lo junto com o texto criptografado sem perder a segurança.

### Parâmetros

`size`
  O tamanho do IV.
`source`
  A fonte do IV. A fonte pode ser `MCRYPT_RAND` (gerador de números aleatórios do sistema), `MCRYPT_DEV_RANDOM` (leitura de dados de /dev/random) e `MCRYPT_DEV_URANDOM` (leitura de dados de /dev/urandom). Antes da versão 5.3.0, `MCRYPT_RAND` era o único suportado no Windows. Observe que o valor padrão deste parâmetro era `MCRYPT_DEV_RANDOM` antes do PHP 5.6.0.

  > Nota: Observe que `MCRYPT_DEV_RANDOM` pode bloquear até que mais entropia esteja disponível.

### Valor Retornado

Retorna o vetor de inicialização ou `false` em caso de erro.

### Exemplos

Exemplo #1 Exemplo de mcrypt_create_iv()

    <?php
        $size = mcrypt_get_iv_size(MCRYPT_CAST_256, MCRYPT_MODE_CFB);
        $iv = mcrypt_create_iv($size, MCRYPT_DEV_RANDOM);
    ?>

### Veja Também

- » http://www.ciphersbyritter.com/GLOSSARY.HTM#IV
- » http://www.quadibloc.com/crypto/co0409.htm
- Capítulo 9.3 de Applied Cryptography by Schneier (ISBN 0-471-11709-9)
- random_bytes() - Obtém bytes aleatórios criptograficamente seguros

# mcrypt_decrypt

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_decrypt — Descriptografa texto criptografado com parâmetros fornecidos

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_decrypt(
string `$cipher`,
string `$key`,
string `$data`,
string `$mode`,
string `$iv` = ?
): string|false

Descriptografa os dados em `data` e retorna os dados não criptografados.

### Parâmetros

`cipher`
  Uma das constantes `MCRYPT_nome_da_cifra` ou o nome do algoritmo como string.
`key`
  A chave com a qual os dados foram criptografados. Se o tamanho da chave fornecida não for suportado pela cifra, a função emitirá um aviso e retornará `false`
`data`
  Os dados que serão descriptografados com `cipher` e `mode` fornecidos. Se o tamanho dos dados não for n * tamanho_do_bloco, os dados serão preenchidos com '`\0`'.
`mode`
  Uma das constantes `MCRYPT_MODE_nome_do_modo` ou uma das seguintes strings: "ecb", "cbc", "cfb", "ofb", "nofb" ou "stream".
`iv`
  Usado para a inicialização nos modos CBC, CFB, OFB e em alguns algoritmos no modo STREAM. Se o tamanho do IV fornecido não for suportado pelo modo de encadeamento ou nenhum IV for fornecido, mas o modo de encadeamento exigir um, a função emitirá um aviso e retornará `false`.

### Valor Retornado

Retorna os dados descriptografados como uma string ou `false` em caso de falha.

### Veja Também

- mcrypt_encrypt() - Criptografa texto simples com parâmetros fornecidos

# mcrypt_enc_get_algorithms_name

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_algorithms_name — Retorna o nome do algoritmo aberto

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_enc_get_algorithms_name(resource `$td`): string

Esta função retorna o nome do algoritmo.

### Parâmetros

`td`
  O descritor de criptografia.

### Valor Retornado

Retorna o nome do algoritmo aberto como uma string.

### Exemplos

Exemplo #1 Exemplo de mcrypt_enc_get_algorithms_name()

    <?php
    $td = mcrypt_module_open(MCRYPT_CAST_256, '', MCRYPT_MODE_CFB, '');
    echo mcrypt_enc_get_algorithms_name($td). "\n";

    $td = mcrypt_module_open('cast-256', '', MCRYPT_MODE_CFB, '');
    echo mcrypt_enc_get_algorithms_name($td). "\n";
    ?>

O exemplo acima produzirá:

    CAST-256
    CAST-256

# mcrypt_enc_get_block_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_block_size — Retorna o tamanho do bloco do algoritmo aberto

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_enc_get_block_size(resource `$td`): int

Obtém o tamanho do bloco do algoritmo aberto.

### Parâmetros

`td`
  O descritor de criptografia.

### Valor Retornado

Retorna o tamanho do bloco do algoritmo especificado em bytes.

# mcrypt_enc_get_iv_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_iv_size — Retorna o tamanho do IV do algoritmo aberto

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_enc_get_iv_size(resource `$td`): int

Esta função retorna o tamanho do IV do algoritmo especificado pelo descritor de criptografia em bytes. Um IV é usado nos modos cbc, cfb e ofb, e em alguns algoritmos no modo de fluxo.

### Parâmetros

`td`
  O descritor de criptografia.

### Valor Retornado

Retorna o tamanho do IV, ou 0 se o IV for ignorado pelo algoritmo.

# mcrypt_enc_get_key_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_key_size — Retorna o tamanho máximo de chave suportado do modo aberto

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_enc_get_key_size(resource `$td`): int

Obtém o tamanho máximo de chave suportado pelo algoritmo em bytes.

### Parâmetros

`td`
  O descritor de criptografia.

### Valor Retornado

Retorna o tamanho máximo de chave suportado pelo algoritmo em bytes.

# mcrypt_enc_get_modes_name

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_modes_name — Retorna o nome do modo aberto

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_enc_get_modes_name(resource `$td`): string

Esta função retorna o nome do modo.

### Parâmetros

`td`
  O descritor de criptografia.

### Valor Retornado

Retorna o nome como uma string.

### Exemplos

Exemplo #1 Exemplo de mcrypt_enc_get_modes_name()

    <?php
    $td = mcrypt_module_open (MCRYPT_CAST_256, '', MCRYPT_MODE_CFB, '');
    echo mcrypt_enc_get_modes_name($td). "\n";

    $td = mcrypt_module_open ('cast-256', '', 'ecb', '');
    echo mcrypt_enc_get_modes_name($td). "\n";
    ?>

O exemplo acima produzirá:

    CFB
    ECB

# mcrypt_enc_get_supported_key_sizes

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_supported_key_sizes — Retorna um array com os tamanhos de chaves suportados do algoritmo aberto

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_enc_get_supported_key_sizes(resource `$td`): array

Obtém os tamanhos de chave suportados pelo algoritmo aberto.

### Parâmetros

`td`
  O descritor de criptografia.

### Valor Retornado

Retorna um array com os tamanhos de chave suportados pelo algoritmo especificado pelo descritor de criptografia. Se retornar um array vazio, todos os tamanhos de chave entre 1 e mcrypt_enc_get_key_size() são suportados pelo algoritmo.

### Exemplos

Exemplo #1 Exemplo de mcrypt_enc_get_supported_key_sizes()

    <?php
        $td = mcrypt_module_open('rijndael-256', '', 'ecb', '');
        var_dump(mcrypt_enc_get_supported_key_sizes($td));
    ?>

O exemplo acima produzirá:

    array(3) {
      [0]=>
      int(16)
      [1]=>
      int(24)
      [2]=>
      int(32)
    }

# mcrypt_enc_is_block_algorithm

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_is_block_algorithm — Verifica se o algoritmo do modo aberto é um algoritmo de bloco

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_enc_is_block_algorithm(resource `$td`): bool

Informa se o algoritmo do modo aberto é um algoritmo de bloco.

### Parâmetros

`td`
  O descritor de criptografia.

### Valor Retornado

Retorna `true` se o algoritmo for um algoritmo de bloco ou `false` se for um algoritmo de fluxo.

# mcrypt_enc_is_block_algorithm_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_is_block_algorithm_mode — Verifica se a criptografia do modo aberto funciona em blocos

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_enc_is_block_algorithm_mode(resource `$td`): bool

Informa se o algoritmo do modo aberto funciona em blocos (por exemplo, `false` para fluxo e `true` para cbc, cfb, ofb).

### Parâmetros

`td`
  O descritor de criptografia.

### Valor Retornado

Informa se o algoritmo do modo aberto funciona em blocos (por exemplo, `false` para fluxo e `true` para cbc, cfb, ofb).

# mcrypt_enc_is_block_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_is_block_mode — Verifica se o modo aberto produz blocos

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_enc_is_block_mode(resource `$td`): bool

Informa se o modo aberto produz blocos (por exemplo, `true` para cbc e ecb, e `false` para cfb e fluxo).

### Parâmetros

`td`
  O descritor de criptografia.

### Valor Retornado

Retorna `true` se o modo produz blocos de bytes, ou `false` se produz apenas bytes.

# mcrypt_enc_self_test

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_self_test — Executa um autoteste no módulo aberto

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_enc_self_test(resource `$td`): int

Esta função executa o autoteste no algoritmo especificado pelo descritor `td`.

### Parâmetros

`td`
  O descritor de criptografia.

### Valor Retornado

Retorna `0` em caso de sucesso e um int negativo em caso de falha.

# mcrypt_encrypt

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_encrypt — Criptografa texto simples com parâmetros fornecidos

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_encrypt(
string `$cipher`,
string `$key`,
string `$data`,
string `$mode`,
string `$iv` = ?
): string|false

Criptografa os dados e os retorna.

### Parâmetros

`cipher`
  Uma das constantes `MCRYPT_nome_da_cifra` ou o nome do algoritmo como string.
`key`
  A chave com a qual os dados serão criptografados. Se o tamanho da chave fornecida não for suportado pela cifra, a função emitirá um aviso e retornará `false`.
`data`
  Os dados que serão criptografados com `cipher` e `mode` fornecidos. Se o tamanho dos dados não for n * tamanho_do_bloco, os dados serão preenchidos com '`\0`'. O texto criptografado retornado pode ser maior que o tamanho dos dados que foram fornecidos por `data`.
`mode`
  Uma das constantes `MCRYPT_MODE_nome_do_modo` ou uma das seguintes strings: "ecb", "cbc", "cfb", "ofb", "nofb" ou "stream".
`iv`
  Usado para a inicialização nos modos CBC, CFB, OFB e em alguns algoritmos no modo STREAM. Se o tamanho do IV fornecido não for suportado pelo modo de encadeamento ou nenhum IV for fornecido, mas o modo de encadeamento exigir um, a função emitirá um aviso e retornará `false`.

### Valor Retornado

Retorna os dados criptografados como uma string ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de mcrypt_encrypt()

    <?php
        # --- CRIPTOGRAFIA ---

        # A chave deve ser binária aleatória, use scrypt, bcrypt ou PBKDF2 para
        # converter uma string em uma chave.
        # A chave é especificada usando hexadecimal
        $key = pack('H*', "bcb04b7e103a0cd8b54763051cef08bc55abe029fdebae5e1d417e2ffb2a00a3");

        # Mostra o tamanho da chave. Use chaves de 16, 24 ou 32 bytes para AES-128, 192
        # e 256 respectivamente
        $key_size =  strlen($key);
        echo "Tamanho da chave: " . $key_size . "\n";

        $plaintext = "This string was AES-256 / CBC / ZeroBytePadding encrypted.";

        # Cria um IV aleatório para usar com codificação CBC
        $iv_size = mcrypt_get_iv_size(MCRYPT_RIJNDAEL_128, MCRYPT_MODE_CBC);
        $iv = mcrypt_create_iv($iv_size, MCRYPT_RAND);

        # Cria um texto criptografado compatível com AES (tamanho do bloco Rijndael = 128)
        # para manter o texto confidencial.
        # Adequado somente para entrada codificada que nunca termina com o valor 00h
        # (por causa do preenchimento padrão com zero).
        $ciphertext = mcrypt_encrypt(MCRYPT_RIJNDAEL_128, $key,
                                     $plaintext, MCRYPT_MODE_CBC, $iv);

        # Adiciona o IV para que ele fique disponível para descriptografia
        $ciphertext = $iv . $ciphertext;

        # Codifica o texto criptografado resultante para que possa ser representado por uma string
        $ciphertext_base64 = base64_encode($ciphertext);

        echo  $ciphertext_base64 . "\n";

        # === ALERTA ===

        # O texto criptografado resultante não tem integridade ou autenticidade adicionada
        # e não é protegido contra ataques "padding oracle".

        # --- DESCRIPTOGRAFIA ---

        $ciphertext_dec = base64_decode($ciphertext_base64);

        # Recupera o IV, iv_size deve ser criado usando mcrypt_get_iv_size()
        $iv_dec = substr($ciphertext_dec, 0, $iv_size);

        # Recupera o texto criptografado (tudo, exceto o $iv_size na frente)
        $ciphertext_dec = substr($ciphertext_dec, $iv_size);

        # Pode remover caracteres com valor 00h do final do texto simples
        $plaintext_dec = mcrypt_decrypt(MCRYPT_RIJNDAEL_128, $key,
                                        $ciphertext_dec, MCRYPT_MODE_CBC, $iv_dec);

        echo  $plaintext_dec . "\n";
    ?>

O exemplo acima produzirá:

    Tamanho da chave: 32
    ENJW8mS2KaJoNB5E5CoSAAu0xARgsR1bdzFWpEn+poYw45q+73az5kYi4j+0haevext1dGrcW8Qi59txfCBV8BBj3bzRP3dFCp3CPQSJ8eU=
    This string was AES-256 / CBC / ZeroBytePadding encrypted.

### Veja Também

- mcrypt_decrypt() - Descriptografa texto criptografado com parâmetros fornecidos
- mcrypt_module_open() - Abre o módulo do algoritmo e o modo a ser utilizado

# mcrypt_generic

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_generic — Esta função criptografa dados

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_generic(resource `$td`, string `$data`): string

Esta função criptografa dados. Os dados são preenchidos com "`\0`" para garantir que o comprimento dos dados seja n * tamanho_do_bloco. Esta função retorna os dados criptografados. Observe que o comprimento da string retornada pode, de fato, ser maior que a entrada, devido ao preenchimento dos dados.

Se houver necessidade de armazenar os dados criptografados em um banco de dados, certifique-se de armazenar a string inteira conforme retornada por mcrypt_generic, ou a string não será totalmente descriptografada corretamente. Se a string original tiver 10 caracteres e o tamanho do bloco for 8 (use mcrypt_enc_get_block_size() para determinar o tamanho do bloco), seriam necessários pelo menos 16 caracteres no campo do banco de dados. Observe que a string retornada por mdecrypt_generic() terá 16 caracteres também... use rtrim($str, "\0") para remover o preenchimento.

Se os dados forem, por exemplo, armazenados em um banco de dados MySQL, lembre-se de que campos "varchar" automaticamente têm espaços finais removidos durante a inserção. Como dados criptografados podem terminar em um espaço (ASCII 32), os dados serão corrompidos por essa remoção. Em vez disso, armazene os dados em um campo tinyblob/tinytext (ou maior).

### Parâmetros

`td`
  O descritor de criptografia. O identificador de criptografia deve sempre ser inicializado com mcrypt_generic_init() com uma chave e um IV antes de chamar esta função. Onde a criptografia é feita, devem ser liberados os buffers de criptografia chamando mcrypt_generic_deinit(). Veja mcrypt_module_open() para um exemplo.
`data`
  Os dados a serem criptografados.

### Valor Retornado

Retorna os dados criptografados.

### Veja Também

- mdecrypt_generic() - Descriptografa dados
- mcrypt_generic_init() - Esta função inicializa todos os buffers necessários para criptografia
- mcrypt_generic_deinit() - Esta função desinicializa um módulo de criptografia

# mcrypt_generic_deinit

(PHP 4 >= 4.0.7, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_generic_deinit — Esta função desinicializa um módulo de criptografia

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_generic_deinit(resource `$td`): bool

Esta função encerra a criptografia especificada pelo descritor de criptografia (`td`). Ela limpa todos os buffers, mas não fecha o módulo. É necessário chamar mcrypt_module_close() por conta própria. Porém, o PHP faz isso automaticamente no final do script.

### Parâmetros

`td`
  O descritor de criptografia.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- mcrypt_module_open() - Abre o módulo do algoritmo e o modo a ser utilizado
- mcrypt_generic_init() - Esta função inicializa todos os buffers necessários para criptografia

# mcrypt_generic_init

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_generic_init — Esta função inicializa todos os buffers necessários para criptografia

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_generic_init(resource `$td`, string `$key`, string `$iv`): int

É necessário chamar esta função antes de cada chamada a mcrypt_generic() ou mdecrypt_generic().

### Parâmetros

`td`
  O descritor de criptografia.
`key`
  O comprimento máximo da chave deve ser aquele obtido chamando mcrypt_enc_get_key_size() e todo valor menor que esse é válido.
`iv`
  O IV normalmente deve ter o tamanho do bloco de algoritmos, mas o tamanho deve ser obtido chamando mcrypt_enc_get_iv_size(). O IV é ignorado no ECB. O IV DEVE existir nos modos CFB, CBC, fluxo, nOFB e OFB. Ele precisa ser aleatório e único (mas não secreto). O mesmo IV deve ser usado para criptografia/descriptografia. Se não houver intenção de usá-lo, deve ser definido como zeros, mas isso não é recomendado.

### Valor Retornado

A função retorna um valor negativo em caso de erro: -3 quando o comprimento da chave estiver incorreto, -4 quando houver um problema de alocação de memória e qualquer outro valor de retorno é um erro desconhecido. Se ocorrer um erro, um aviso será exibido apropriadamente. `false` é retornado se forem passados parâmetros incorretos.

### Veja Também

- mcrypt_module_open() - Abre o módulo do algoritmo e o modo a ser utilizado

# mcrypt_get_block_size

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_block_size — Obtém o tamanho do bloco da cifra especificada

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_get_block_size(int `$cipher`): int|false
function mcrypt_get_block_size(string `$cipher`, string `$mode`): int|false

O primeiro protótipo é quando compilado com libmcrypt 2.2.x, o segundo quando compilado com libmcrypt 2.4.x ou 2.5.x.

mcrypt_get_block_size() é usado para obter o tamanho de um bloco do `cipher` especificado (em combinação com um modo de criptografia).

É mais útil usar a função mcrypt_enc_get_block_size(), pois ela usa o recurso retornado por mcrypt_module_open().

### Parâmetros

`cipher`
  Uma das constantes `MCRYPT_nome_da_cifra` ou o nome do algoritmo como string.
`mode`
  Uma das constantes `MCRYPT_MODE_nome_do_modo` ou uma das seguintes strings: "ecb", "cbc", "cfb", "ofb", "nofb" ou "stream".

### Valor Retornado

Retorna o tamanho do bloco do algoritmo em bytes ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de mcrypt_get_block_size()

Este exemplo mostra como usar esta função quando compilada com libmcrypt 2.4.x e 2.5.x.

    <?php

    echo mcrypt_get_block_size('tripledes', 'ecb'); // 8

    ?>

### Veja Também

- mcrypt_get_key_size() - Obtém o tamanho da chave da cifra especificada
- mcrypt_enc_get_block_size() - Retorna o tamanho do bloco do algoritmo aberto
- mcrypt_encrypt() - Criptografa texto simples com parâmetros fornecidos

# mcrypt_get_cipher_name

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_cipher_name — Obtém o nome da cifra especificada

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_get_cipher_name(int `$cipher`): string
function mcrypt_get_cipher_name(string `$cipher`): string

mcrypt_get_cipher_name() é usada para obter o nome da cifra especificada.

mcrypt_get_cipher_name() recebe o número da cifra como um argumento (libmcrypt 2.2.x) ou recebe o nome da cifra como um argumento (libmcrypt 2.4.x ou superior) e retorna o nome da cifra ou `false`, se a cifra não existir.

### Parâmetros

`cipher`
  Uma das constantes `MCRYPT_nome_da_cifra` ou o nome do algoritmo como string.

### Valor Retornado

Esta função retorna o nome da cifra ou `false` se a cifra não existir.

### Exemplos

Exemplo #1 Exemplo de mcrypt_get_cipher_name()

    <?php
       $cipher = MCRYPT_TripleDES;

       echo mcrypt_get_cipher_name($cipher);
    ?>

O exemplo acima produzirá:

    3DES

# mcrypt_get_iv_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_iv_size — Retorna o tamanho do IV pertencente a uma combinação específica de cifra/modo

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_get_iv_size(string `$cipher`, string `$mode`): int

Obtém o tamanho do IV pertencente a uma combinação `cipher`/`mode` específica.

É mais útil usar a função mcrypt_enc_get_iv_size(), pois ela usa o recurso retornado por mcrypt_module_open().

### Parâmetros

`cipher`
  Uma das constantes `MCRYPT_nome_da_cifra` ou o nome do algoritmo como string.
`mode`
  Uma das constantes `MCRYPT_MODE_nome_do_modo` ou uma das seguintes strings: "ecb", "cbc", "cfb", "ofb", "nofb" ou "stream". O IV é ignorado no modo ECB, pois este modo não o requer. É necessário ter o mesmo IV (pense: ponto de partida) tanto nos estágios de criptografia quanto de descriptografia, caso contrário, a criptografia falhará.

### Valor Retornado

Retorna o tamanho do Vetor de Inicialização (IV) em bytes. Em caso de erro, a função retorna `false`. Se o IV for ignorado na combinação cifra/modo especificada, zero é retornado.

### Exemplos

Exemplo #1 Exemplo de mcrypt_get_iv_size()

    <?php
        echo mcrypt_get_iv_size(MCRYPT_CAST_256, MCRYPT_MODE_CFB) . "\n";

        echo mcrypt_get_iv_size('des', 'ecb') . "\n";
    ?>

### Veja Também

- mcrypt_get_block_size() - Obtém o tamanho do bloco da cifra especificada
- mcrypt_enc_get_iv_size() - Retorna o tamanho do IV do algoritmo aberto
- mcrypt_create_iv() - Cria um vetor de inicialização (IV) a partir de uma fonte aleatória

# mcrypt_get_key_size

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_key_size — Obtém o tamanho da chave da cifra especificada

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_get_key_size(int `$cipher`): int|false
function mcrypt_get_key_size(string `$cipher`, string `$mode`): int|false

O primeiro protótipo é quando compilado com libmcrypt 2.2.x, o segundo quando compilado com libmcrypt 2.4.x ou 2.5.x.

mcrypt_get_key_size() é usado para obter o tamanho de uma chave do `cipher` especificado (em combinação com um modo de criptografia).

É mais útil usar a função mcrypt_enc_get_key_size(), pois ela usa o recurso retornado por mcrypt_module_open().

### Parâmetros

`cipher`
  Uma das constantes `MCRYPT_nome_da_cifra` ou o nome do algoritmo como string.
`mode`
  Uma das constantes `MCRYPT_MODE_nome_do_modo` ou uma das seguintes strings: "ecb", "cbc", "cfb", "ofb", "nofb" ou "stream".

### Valor Retornado

Retorna o tamanho máximo de chave suportado pelo algoritmo em bytes ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de mcrypt_get_key_size()

    <?php
        echo mcrypt_get_key_size('tripledes', 'ecb');
    ?>

O exemplo acima mostra como usar esta função quando compilado com libmcrypt 2.4.x ou 2.5.x.

O exemplo acima produzirá:

    24

### Veja Também

- mcrypt_get_block_size() - Obtém o tamanho do bloco da cifra especificada
- mcrypt_enc_get_key_size() - Retorna o tamanho máximo de chave suportado do modo aberto
- mcrypt_encrypt() - Criptografa texto simples com parâmetros fornecidos

# mcrypt_list_algorithms

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_list_algorithms — Obtém um array de todas as cifras suportadas

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_list_algorithms(string `$lib_dir` = ini_get("mcrypt.algorithms_dir")): array

Obtém a lista de todos os algoritmos suportados no parâmetro `lib_dir`.

### Parâmetros

`lib_dir`
  Especifica o diretório onde todos os algoritmos estão localizados. Se não especificado, o valor da diretiva `mcrypt.algorithms_dir` do php.ini é usado.

### Valor Retornado

Retorna um array com todos os algoritmos suportados.

### Exemplos

Exemplo #1 Exemplo de mcrypt_list_algorithms()

    <?php
    $algorithms = mcrypt_list_algorithms();
    print_r($algorithms);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => cast-128
        [1] => gost
        [2] => rijndael-128
        [3] => twofish
        [4] => arcfour
        [5] => cast-256
        [6] => loki97
        [7] => rijndael-192
        [8] => saferplus
        [9] => wake
        [10] => blowfish-compat
        [11] => des
        [12] => rijndael-256
        [13] => serpent
        [14] => xtea
        [15] => blowfish
        [16] => enigma
        [17] => rc2
        [18] => tripledes
    )

# mcrypt_list_modes

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_list_modes — Obtém um array de todos os modos suportados

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_list_modes(string `$lib_dir` = ini_get("mcrypt.modes_dir")): array

Obtém a lista de todos os modos suportados no parâmetro `lib_dir`.

### Parâmetros

`lib_dir`
  Especifica o diretório onde todos os modos estão localizados. Se não especificado, o valor da diretiva `mcrypt.modes_dir` do php.ini é usado.

### Valor Retornado

Retorna um array com todos os modos suportados.

### Exemplos

Exemplo #1 Exemplo de mcrypt_list_modes()

    <?php
        $modes = mcrypt_list_modes();

        foreach ($modes as $mode) {
            echo "$mode <br />\n";
        }
    ?>

O exemplo acima produzirá uma lista com todos os algoritmos suportados no diretório padrão dos modos. Se não estiver definido com a diretiva `mcrypt.modes_dir` do php.ini, o diretório padrão do mcrypt é usado (que é /usr/local/lib/libmcrypt).

# mcrypt_module_close

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_close — Fecha o módulo mcrypt

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_module_close(resource `$td`): bool

Fecha o identificador de criptografia especificado.

### Parâmetros

`td`
  O descritor de criptografia.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- mcrypt_module_open() - Abre o módulo do algoritmo e o modo a ser utilizado

# mcrypt_module_get_algo_block_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_get_algo_block_size — Retorna o tamanho do bloco do algoritmo especificado

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_module_get_algo_block_size(string `$algorithm`, string `$lib_dir` = ?): int

Obtém o tamanho do bloco do algoritmo especificado.

### Parâmetros

`algorithm`
  O nome do algoritmo.
`lib_dir`
  Este parâmetro opcional pode conter o local onde o módulo de modo está no sistema.

### Valor Retornado

Retorna o tamanho do bloco do algoritmo especificado, em bytes.

# mcrypt_module_get_algo_key_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_get_algo_key_size — Retorna o tamanho máximo de chave suportado do modo aberto

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_module_get_algo_key_size(string `$algorithm`, string `$lib_dir` = ?): int

Obtém o tamanho máximo de chave suportado do modo aberto.

### Parâmetros

`algorithm`
  O nome do algoritmo.
`lib_dir`
  Este parâmetro opcional pode conter o local onde o módulo de modo está no sistema.

### Valor Retornado

Esta função retorna o tamanho máximo de chave suportado do algoritmo especificado em bytes.

# mcrypt_module_get_supported_key_sizes

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_get_supported_key_sizes — Retorna um array com os tamanhos de chaves suportados do algoritmo aberto

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_module_get_supported_key_sizes(string `$algorithm`, string `$lib_dir` = ?): array

Retorna um array com os tamanhos de chave suportados pelo algoritmo especificado. Se retornar um array vazio, todos os tamanhos de chave entre 1 e mcrypt_module_get_algo_key_size() são suportados pelo algoritmo.

### Parâmetros

`algorithm`
  O algoritmo a ser usado.
`lib_dir`
  O parâmetro opcional `lib_dir` pode conter o local onde o módulo de algoritmo está no sistema.

### Valor Retornado

Retorna um array com os tamanhos de chave suportados pelo algoritmo especificado. Se retornar um array vazio, todos os tamanhos de chave entre 1 e mcrypt_module_get_algo_key_size() são suportados pelo algoritmo.

### Veja Também

- mcrypt_enc_get_supported_key_sizes() - Retorna um array com os tamanhos de chaves suportados do algoritmo aberto

# mcrypt_module_is_block_algorithm

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_is_block_algorithm — Esta função verifica se o algoritmo especificado é um algoritmo de bloco

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_module_is_block_algorithm(string `$algorithm`, string `$lib_dir` = ?): bool

Esta função retorna `true` se o algoritmo especificado for um algoritmo de bloco ou `false` se for um algoritmo de fluxo.

### Parâmetros

`algorithm`
  O algoritmo a ser verificado.
`lib_dir`
  O parâmetro opcional `lib_dir` pode conter o local onde o módulo de algoritmo está no sistema.

### Valor Retornado

Esta função retorna `true` se o algoritmo especificado for um algoritmo de bloco ou `false` se for um algoritmo de fluxo.

# mcrypt_module_is_block_algorithm_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_is_block_algorithm_mode — Retorna se o módulo especificado é um algoritmo de bloco ou não

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_module_is_block_algorithm_mode(string `$mode`, string `$lib_dir` = ?): bool

Esta função retorna `true` se o modo for para uso com algoritmos de bloco, caso contrário, retorna `false`. (por exemplo, `false` para fluxo e `true` para cbc, cfb, ofb).

### Parâmetros

`mode`
  O modo a ser verificado.
`lib_dir`
  O parâmetro opcional `lib_dir` pode conter o local onde o módulo de algoritmo está no sistema.

### Valor Retornado

Esta função retorna `true` se o modo for para uso com algoritmos de bloco, caso contrário, retorna `false`. (por exemplo, `false` para fluxo e `true` para cbc, cfb, ofb).

# mcrypt_module_is_block_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_is_block_mode — Retorna se o modo especificado produz blocos ou não

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_module_is_block_mode(string `$mode`, string `$lib_dir` = ?): bool

Esta função retorna `true` se o modo produz blocos de bytes ou `false` se produz apenas bytes. (por exemplo, `true` para cbc e ecb, e `false` para cfb e fluxo).

### Parâmetros

`mode`
  Uma das constantes `MCRYPT_MODE_nome_do_modo` ou uma das seguintes strings: "ecb", "cbc", "cfb", "ofb", "nofb" ou "stream".
`lib_dir`
  O parâmetro opcional `lib_dir` pode conter o local onde o módulo de algoritmo está no sistema.

### Valor Retornado

Esta função retorna `true` se o modo produz blocos de bytes ou `false` se produz apenas bytes. (por exemplo, `true` para cbc e ecb, e `false` para cfb e fluxo).

# mcrypt_module_open

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_open — Abre o módulo do algoritmo e o modo a ser utilizado

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_module_open(
string `$algorithm`,
string `$algorithm_directory`,
string `$mode`,
string `$mode_directory`
): resource

Esta função abre o módulo do algoritmo e o modo a ser usado. O nome do algoritmo é especificado em "algorithm", por exemplo, `"twofish"` ou é uma das constantes `MCRYPT_ciphername`. O módulo é fechado chamando mcrypt_module_close().

### Parâmetros

`algorithm`
  Uma das constantes `MCRYPT_nome_da_cifra` ou o nome do algoritmo como string.
`algorithm_directory`
  O parâmetro `algorithm_directory` é usado para localizar o módulo de criptografia. Quando é informado um nome de diretório, ele é usado. Quando ele é definido como uma string vazia (`""`), o valor definido pela diretiva `mcrypt.algorithms_dir` do php.ini é usado. Quando ele não é definido, o diretório padrão usado é aquele que foi compilado no libmcrypt (geralmente /usr/local/lib/libmcrypt).
`mode`
  Uma das constantes `MCRYPT_MODE_nome_do_modo` ou uma das seguintes strings: "ecb", "cbc", "cfb", "ofb", "nofb" ou "stream".
`mode_directory`
  O parâmetro `mode_directory` é usado para localizar o módulo de criptografia. Quando é informado um nome de diretório, ele é usado. Quando ele é definido como uma string vazia (`""`), o valor definido pela diretiva `mcrypt.modes_dir` do php.ini é usado. Quando ele não é definido, o diretório padrão usado é aquele que foi compilado em no libmcrypt (geralmente /usr/local/lib/libmcrypt).

### Valor Retornado

Normalmente, ele retorna um descritor de criptografia ou `false` em caso de erro.

### Exemplos

Exemplo #1 Exemplos de mcrypt_module_open()

    <?php
        $td = mcrypt_module_open(MCRYPT_DES, '',
            MCRYPT_MODE_ECB, '/usr/lib/mcrypt-modes');

        $td = mcrypt_module_open('rijndael-256', '', 'ofb', '');
    ?>

A primeira linha no exemplo acima tentará abrir a cifra `DES` do diretório padrão e o modo `ECB` do diretório /usr/lib/mcrypt-modes. O segundo exemplo usa strings como nome para a cifra e modo, isso só funciona quando a extensão é compilada com o libmcrypt 2.4.x ou 2.5.x.

Exemplo #2 Usando mcrypt_module_open() em criptografia

    <?php
        /* Abre a cifra */
        $td = mcrypt_module_open('rijndael-256', '', 'ofb', '');

        /* Cria o IV e determina o comprimento da chave, use MCRYPT_RAND
         * no Windows */
        $iv = mcrypt_create_iv(mcrypt_enc_get_iv_size($td), MCRYPT_DEV_RANDOM);
        $ks = mcrypt_enc_get_key_size($td);

        /* Cria a chave (somente como exemplo: MD5 não é um bom algoritmo de hash para isso) */
        $key = substr(hash('md5', 'very secret key'), 0, $ks);

        /* Inicializa a criptografia */
        mcrypt_generic_init($td, $key, $iv);

        /* Criptografa os dados */
        $encrypted = mcrypt_generic($td, 'This is very important data');

        /* Desinicializa o identificador de criptografia */
        mcrypt_generic_deinit($td);

        /* Inicializa o módulo de criptografia para descriptografia */
        mcrypt_generic_init($td, $key, $iv);

        /* Descriptografa a string criptografada */
        $decrypted = mdecrypt_generic($td, $encrypted);

        /* Desinicializa o identificador de criptografia e fecha o módulo */
        mcrypt_generic_deinit($td);
        mcrypt_module_close($td);

        /* Exibe a string */
        echo trim($decrypted) . "\n";
    ?>

### Veja Também

- mcrypt_module_close() - Fecha o módulo mcrypt
- mcrypt_generic() - Esta função criptografa dados
- mdecrypt_generic() - Descriptografa dados
- mcrypt_generic_init() - Esta função inicializa todos os buffers necessários para criptografia
- mcrypt_generic_deinit() - Esta função desinicializa um módulo de criptografia

# mcrypt_module_self_test

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_self_test — Executa um autoteste no módulo especificado

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mcrypt_module_self_test(string `$algorithm`, string `$lib_dir` = ?): bool

Esta função executa o autoteste no algoritmo especificado.

### Parâmetros

`algorithm`
  Uma das constantes `MCRYPT_nome_da_cifra` ou o nome do algoritmo como string.
`lib_dir`
  O parâmetro opcional `lib_dir` pode conter o local onde o módulo de algoritmo está no sistema.

### Valor Retornado

A função retorna `true` se o autoteste for bem-sucedido ou `false` quando ele falhar.

### Exemplos

Exemplo #1 Exemplo de mcrypt_module_self_test()

    <?php
    var_dump(mcrypt_module_self_test(MCRYPT_RIJNDAEL_128)) . "\n";
    var_dump(mcrypt_module_self_test(MCRYPT_BOGUS_CYPHER));
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(false)

# mdecrypt_generic

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mdecrypt_generic — Descriptografa dados

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.1.0 e foi REMOVIDA a partir do PHP 7.2.0. O uso desta função é fortemente desencorajado.

### Descrição

function mdecrypt_generic(resource `$td`, string `$data`): string

Esta função descriptografa dados. Note que o comprimento da string retornada pode de fato ser maior que a string não criptografada, devido ao preenchimento dos dados.

### Parâmetros

`td`
  Um descritor de criptografia retornado por mcrypt_module_open().
`data`
  Dados criptografados.

### Valor Retornado

Retorna a string descriptografada.

### Exemplos

Exemplo #1 Exemplo de mdecrypt_generic()

    <?php
        /* Dados */
        $key = 'this is a very long key, even too long for the cipher';
        $plain_text = 'very important data';

        /* Abre o módulo e cria o IV */
        $td = mcrypt_module_open('des', '', 'ecb', '');
        $key = substr($key, 0, mcrypt_enc_get_key_size($td));
        $iv_size = mcrypt_enc_get_iv_size($td);
        $iv = mcrypt_create_iv($iv_size, MCRYPT_RAND);

        /* Inicializa o identificador de criptografia */
        if (mcrypt_generic_init($td, $key, $iv) != -1) {

            /* Criptografa os dados */
            $c_t = mcrypt_generic($td, $plain_text);
            mcrypt_generic_deinit($td);

            /* Reinicializa buffers para descriptografia */
            mcrypt_generic_init($td, $key, $iv);
            $p_t = mdecrypt_generic($td, $c_t);

            /* Limpa tudo */
            mcrypt_generic_deinit($td);
            mcrypt_module_close($td);
        }

        if (strncmp($p_t, $plain_text, strlen($plain_text)) == 0) {
            echo "ok\n";
        } else {
            echo "erro\n";
        }
    ?>

O exemplo acima mostra como verificar se os dados antes da criptografia são os mesmos que os dados após a descriptografia. É muito importante reinicializar o buffer de criptografia com mcrypt_generic_init() antes de tentar descriptografar os dados.

O identificador de descriptografia deve sempre ser inicializado com mcrypt_generic_init() com uma chave e um IV antes de chamar esta função. Quando a criptografia tiver terminado, deve-se liberar os buffers de criptografia chamando mcrypt_generic_deinit(). Veja mcrypt_module_open() para um exemplo.

### Veja Também

- mcrypt_generic() - Esta função criptografa dados
- mcrypt_generic_init() - Esta função inicializa todos os buffers necessários para criptografia
- mcrypt_generic_deinit() - Esta função desinicializa um módulo de criptografia

## Índice

- mcrypt_create_iv — Cria um vetor de inicialização (IV) a partir de uma fonte aleatória
- mcrypt_decrypt — Descriptografa texto criptografado com parâmetros fornecidos
- mcrypt_enc_get_algorithms_name — Retorna o nome do algoritmo aberto
- mcrypt_enc_get_block_size — Retorna o tamanho do bloco do algoritmo aberto
- mcrypt_enc_get_iv_size — Retorna o tamanho do IV do algoritmo aberto
- mcrypt_enc_get_key_size — Retorna o tamanho máximo de chave suportado do modo aberto
- mcrypt_enc_get_modes_name — Retorna o nome do modo aberto
- mcrypt_enc_get_supported_key_sizes — Retorna um array com os tamanhos de chaves suportados do algoritmo aberto
- mcrypt_enc_is_block_algorithm — Verifica se o algoritmo do modo aberto é um algoritmo de bloco
- mcrypt_enc_is_block_algorithm_mode — Verifica se a criptografia do modo aberto funciona em blocos
- mcrypt_enc_is_block_mode — Verifica se o modo aberto produz blocos
- mcrypt_enc_self_test — Executa um autoteste no módulo aberto
- mcrypt_encrypt — Criptografa texto simples com parâmetros fornecidos
- mcrypt_generic — Esta função criptografa dados
- mcrypt_generic_deinit — Esta função desinicializa um módulo de criptografia
- mcrypt_generic_init — Esta função inicializa todos os buffers necessários para criptografia
- mcrypt_get_block_size — Obtém o tamanho do bloco da cifra especificada
- mcrypt_get_cipher_name — Obtém o nome da cifra especificada
- mcrypt_get_iv_size — Retorna o tamanho do IV pertencente a uma combinação específica de cifra/modo
- mcrypt_get_key_size — Obtém o tamanho da chave da cifra especificada
- mcrypt_list_algorithms — Obtém um array de todas as cifras suportadas
- mcrypt_list_modes — Obtém um array de todos os modos suportados
- mcrypt_module_close — Fecha o módulo mcrypt
- mcrypt_module_get_algo_block_size — Retorna o tamanho do bloco do algoritmo especificado
- mcrypt_module_get_algo_key_size — Retorna o tamanho máximo de chave suportado do modo aberto
- mcrypt_module_get_supported_key_sizes — Retorna um array com os tamanhos de chaves suportados do algoritmo aberto
- mcrypt_module_is_block_algorithm — Esta função verifica se o algoritmo especificado é um algoritmo de bloco
- mcrypt_module_is_block_algorithm_mode — Retorna se o módulo especificado é um algoritmo de bloco ou não
- mcrypt_module_is_block_mode — Retorna se o modo especificado produz blocos ou não
- mcrypt_module_open — Abre o módulo do algoritmo e o modo a ser utilizado
- mcrypt_module_self_test — Executa um autoteste no módulo especificado
- mdecrypt_generic — Descriptografa dados

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
  - Tipos de Recurso
- Constantes predefinidas
- Cifras de Mcrypt
- Mcrypt Funções
  - mcrypt_create_iv — Cria um vetor de inicialização (IV) a partir de uma fonte aleatória
  - mcrypt_decrypt — Descriptografa texto criptografado com parâmetros fornecidos
  - mcrypt_enc_get_algorithms_name — Retorna o nome do algoritmo aberto
  - mcrypt_enc_get_block_size — Retorna o tamanho do bloco do algoritmo aberto
  - mcrypt_enc_get_iv_size — Retorna o tamanho do IV do algoritmo aberto
  - mcrypt_enc_get_key_size — Retorna o tamanho máximo de chave suportado do modo aberto
  - mcrypt_enc_get_modes_name — Retorna o nome do modo aberto
  - mcrypt_enc_get_supported_key_sizes — Retorna um array com os tamanhos de chaves suportados do algoritmo aberto
  - mcrypt_enc_is_block_algorithm — Verifica se o algoritmo do modo aberto é um algoritmo de bloco
  - mcrypt_enc_is_block_algorithm_mode — Verifica se a criptografia do modo aberto funciona em blocos
  - mcrypt_enc_is_block_mode — Verifica se o modo aberto produz blocos
  - mcrypt_enc_self_test — Executa um autoteste no módulo aberto
  - mcrypt_encrypt — Criptografa texto simples com parâmetros fornecidos
  - mcrypt_generic — Esta função criptografa dados
  - mcrypt_generic_deinit — Esta função desinicializa um módulo de criptografia
  - mcrypt_generic_init — Esta função inicializa todos os buffers necessários para criptografia
  - mcrypt_get_block_size — Obtém o tamanho do bloco da cifra especificada
  - mcrypt_get_cipher_name — Obtém o nome da cifra especificada
  - mcrypt_get_iv_size — Retorna o tamanho do IV pertencente a uma combinação específica de cifra/modo
  - mcrypt_get_key_size — Obtém o tamanho da chave da cifra especificada
  - mcrypt_list_algorithms — Obtém um array de todas as cifras suportadas
  - mcrypt_list_modes — Obtém um array de todos os modos suportados
  - mcrypt_module_close — Fecha o módulo mcrypt
  - mcrypt_module_get_algo_block_size — Retorna o tamanho do bloco do algoritmo especificado
  - mcrypt_module_get_algo_key_size — Retorna o tamanho máximo de chave suportado do modo aberto
  - mcrypt_module_get_supported_key_sizes — Retorna um array com os tamanhos de chaves suportados do algoritmo aberto
  - mcrypt_module_is_block_algorithm — Esta função verifica se o algoritmo especificado é um algoritmo de bloco
  - mcrypt_module_is_block_algorithm_mode — Retorna se o módulo especificado é um algoritmo de bloco ou não
  - mcrypt_module_is_block_mode — Retorna se o modo especificado produz blocos ou não
  - mcrypt_module_open — Abre o módulo do algoritmo e o modo a ser utilizado
  - mcrypt_module_self_test — Executa um autoteste no módulo especificado
  - mdecrypt_generic — Descriptografa dados

# Mhash

# Introdução

Essas funções são planejadas para trabalhar com » mhash. Mhash pode ser usada para criar somas de verificação, resumos de mensagens, códigos de autenticação de mensagens e mais.

Esta é uma interface para a biblioteca mhash. Mhash suporta uma grande variedade de algoritmos de hash como MD5, SHA1, GOST e muitos outros. Para uma lista completa das hashs suportadas, verifique a página de constantes. A regra geral é que o algoritmo de hash pode ser acessado a partir do PHP com `MHASH_hashname`. Por exemplo, para acessar o algoritmo TIGER, utiliza-se a constante `MHASH_TIGER`.

> Nota:

> Esta extensão foi descontinuada em relação à Hash.

> Nota:

> A partir do PHP 7.0.0 a extensão Mhash está totalmente integrada à extensão Hash. Portanto, não é mais possível detectar o suporte a Mhash com a função extension_loaded(); use em seu lugar a função function_exists(). Adicionalmente, Mhash não é mais suportada por get_loaded_extensions() e recursos relacionados.

# Instalação/Configuração

## Índice

- Dependências
- Instalação

## Dependências

Para usá-las, faça o download da distribuição do mhash em » seu site e siga as instruções de instalação inclusas.

## Instalação

É necessário compilar o PHP com o parâmetro --with-mhash[=DIR] para habilitar esta extensão. DIR é o diretório de instalação da mhash.

A partir do PHP 5.3.0, a extensão mhash extension é emulada através da extensão Hash. Isto faz com que o diretório de instalação da mhash não tenha efeito, e requer a extensão hash habilitada para que o suporte a mhash esteja disponível.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

Aqui está uma lista de hashes que são atualmente suportadas por mhash. Se uma hash não está listada aqui, mas é listada na documentação do mhash como suportada, pode-se assumir seguramente que esta documentação está desatualizada.

`MHASH_ADLER32` (int)
`MHASH_CRC32` (int)
`MHASH_CRC32B` (int)
`MHASH_CRC32C` (int)
  Disponível a partir do PHP 7.4.0.
`MHASH_FNV132` (int)
`MHASH_FNV1A32` (int)
`MHASH_FNV164` (int)
`MHASH_FNV1A64` (int)
`MHASH_GOST` (int)
`MHASH_HAVAL128` (int)
`MHASH_HAVAL160` (int)
`MHASH_HAVAL192` (int)
`MHASH_HAVAL224` (int)
`MHASH_HAVAL256` (int)
`MHASH_JOAAT` (int)
`MHASH_MD2` (int)
`MHASH_MD4` (int)
`MHASH_MD5` (int)
`MHASH_MURMUR3A` (int)
  Disponível a partir do PHP 8.1.0.
`MHASH_MURMUR3C` (int)
  Disponível a partir do PHP 8.1.0.
`MHASH_MURMUR3F` (int)
  Disponível a partir do PHP 8.1.0.
`MHASH_RIPEMD128` (int)
`MHASH_RIPEMD160` (int)
`MHASH_RIPEMD256` (int)
`MHASH_RIPEMD320` (int)
`MHASH_SHA1` (int)
`MHASH_SHA224` (int)
`MHASH_SHA256` (int)
`MHASH_SHA384` (int)
`MHASH_SHA512` (int)
`MHASH_SNEFRU256` (int)
`MHASH_TIGER` (int)
`MHASH_TIGER128` (int)
`MHASH_TIGER160` (int)
`MHASH_WHIRLPOOL` (int)
`MHASH_XXH32` (int)
`MHASH_XXH64` (int)
`MHASH_XXH3` (int)
`MHASH_XXH128` (int)

# Exemplos

Exemplo #1 Calcula o hash e hmac MD5 e exibe como hexadecimal

    <?php
    $input = "what do ya want for nothing?";
    $hash = mhash(MHASH_MD5, $input);
    echo "O hash é " . bin2hex($hash) . "<br />\n";
    $hash = mhash(MHASH_MD5, $input, "Jefe");
    echo "O hmac é " . bin2hex($hash) . "<br />\n";
    ?>

O exemplo acima produzirá:

    O hash é d03cb659cbf9192dcd066272249f8412
    O hmac é 750c783e6ab0b503eaa86e310a5db738

# Funções da Mhash

# mhash

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash — Computa a hash

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.1.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
function mhash(int `$algo`, string `$data`, ?string `$key` = null): string|false

mhash() aplica a função hash especificada por `algo` ao parâmetro `data`.

### Parâmetros

`algo`

  O ID da hash. Uma das constantes `MHASH_hashname`.

`data`

  A entrada do usuário, como uma string.

`key`

  Se especificado, a função irá retornar o HMAC resultante. HMAC é o hashing com chave para autenticações de mensagens, ou simplesmente um resumo de mensagem que depende da chave especificada. Nem todos os algoritmos suportados em mhash podem ser usados em modo HMAC.

### Valor Retornado

Retorna o hash resultante (também chamado resumo ou digest) ou HMAC como uma string, ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Esta função foi descontinuada. Use as funções `hash_*()` em seu lugar.
8.0.0 | `key` agora pode ser nulo.

# mhash_count

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash_count — Obtém o ID de hash mais alto disponível

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.1.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
function mhash_count(): int

Obtém o ID de hash mais alto disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ID de hash mais alto disponível. Hashes são numeradas de 0 até este ID de hash.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Esta função foi descontinuada. Use as funções `hash_*()` em seu lugar.

### Exemplos

Exemplo #1 Listando todas as hashes

    <?php

    $nr = mhash_count();

    for ($i = 0; $i <= $nr; $i++) {
        echo sprintf("O tamanho de bloco de %s é %d\n",
            mhash_get_hash_name($i),
            mhash_get_block_size($i));
    }
    ?>

# mhash_get_block_size

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash_get_block_size — Obtém o tamanho de bloco da hash especificada

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.1.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
function mhash_get_block_size(int `$algo`): int|false

Obtém o tamanho de um bloco da hash informada em `algo`.

### Parâmetros

`algo`

  O ID da hash. Uma das constantes `MHASH_hashname`.

### Valor Retornado

Retorna o tamanho em bytes ou `false`, se a hash em `algo` não existir.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Esta função foi descontinuada. Use as funções `hash_*()` em seu lugar.

### Exemplos

Exemplo #1 Exemplo de mhash_get_block_size()

    <?php

    echo mhash_get_block_size(MHASH_MD5); // 16

    ?>

# mhash_get_hash_name

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash_get_hash_name — Obtém o nome da hash especificada

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.1.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
function mhash_get_hash_name(int `$algo`): string|false

Obtém o nome da hash especificada em `algo`.

### Parâmetros

`algo`

  O ID da hash. Uma das constantes `MHASH_hashname`.

### Valor Retornado

Retorna o nome da hash ou `false`, se a hash não existir.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Esta função foi descontinuada. Use as funções `hash_*()` em seu lugar.

### Exemplos

Exemplo #1 Exemplo de mhash_get_hash_name()

    <?php

    echo mhash_get_hash_name(MHASH_MD5); // MD5

    ?>

# mhash_keygen_s2k

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

mhash_keygen_s2k — Gera uma chave

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.1.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
function mhash_keygen_s2k(
int `$algo`,
string `$password`,
string `$salt`,
int `$length`
): string|false

Gera um chave de acordo com o parâmetro `algo` a partir de uma senha de usuário informada em `password`.

Este é o algoritmo Salted S2K como especificado no documento OpenPGP (» RFC 2440).

Tenha em mente que senhas fornecidas pelos usuários não são adequadas para uso como chaves em algoritmos criptográficos, pois os usuários normalmente escolhem chaves que podem ser escritas no teclado. Estas senhas usam somente 6 a 7 bits por caractere (ou menos). É altamente recomendado usar algum tipo de transformação (como esta função) na chave informada pelo usuário.

### Parâmetros

`algo`

  O ID da hash usada para criar a chave. Um das constantes `MHASH_hashname`.

`password`

  Uma senha fornecida pelo usuário.

`salt`

  Deve ser diferente e aleatório o suficiente para cada chave gerada de forma que sejam criadas chaves diferentes. Como `salt` precisa ser conhecido quando se verifica as chaves, é uma boa prática concatenar a chave a ele. Salt tem um comprimento fixo de 8 bytes e será completado com zeros forem fornecidos menos bytes.

`length`

  O tamanho da chave, em bytes.

### Valor Retornado

Retorna a chave gerada como uma string, ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Esta função foi descontinuada. Use as funções `hash_*()` em seu lugar.

## Índice

- mhash — Computa a hash
- mhash_count — Obtém o ID de hash mais alto disponível
- mhash_get_block_size — Obtém o tamanho de bloco da hash especificada
- mhash_get_hash_name — Obtém o nome da hash especificada
- mhash_keygen_s2k — Gera uma chave

- Instalação/Configuração
  - Dependências
  - Instalação
- Constantes predefinidas
- Exemplos
- Funções da Mhash
  - mhash — Computa a hash
  - mhash_count — Obtém o ID de hash mais alto disponível
  - mhash_get_block_size — Obtém o tamanho de bloco da hash especificada
  - mhash_get_hash_name — Obtém o nome da hash especificada
  - mhash_keygen_s2k — Gera uma chave

# OpenSSL

# Introdução

Esta extensão vincula funções da biblioteca » OpenSSL para criptografia e descriptografia simétrica e assimétrica, PBKDF2, PKCS7, PKCS12, X509 e outras operações de criptografia. Além disso, fornece implementação de fluxos TLS.

O OpenSSL oferece muitos recursos que este módulo não suporta atualmente. Alguns deles podem ser adicionados no futuro.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução
- Tipos de Recurso

## Dependências

Para usar as funções do OpenSSL, é necessário instalar a biblioteca » OpenSSL. O PHP 7.0 requer OpenSSL >= 0.9.8, < 1.2. O PHP 7.1-8.0 requer OpenSSL >= 1.0.1, < 3.0. O PHP >= 8.1 requer OpenSSL >= 1.0.2, < 4.0. PHP >= 8.4 requer OpenSSL >= 1.1.1, < 4.0.

Aviso

É altamente recomendável usar uma versão OpenSSL mantida, caso contrário, seu servidor web pode ficar vulnerável a ataques.

## Instalação

Para usar o suporte OpenSSL do PHP, o PHP deve ser compilado com --with-openssl.

A biblioteca OpenSSL também tem requisitos adicionais para operação normal em tempo de execução. Mais notavelmente, o OpenSSL requer acesso a um gerador de números aleatórios ou pseudoaleatórios; na maioria das plataformas Unix e similares (incluindo Linux), isso significa que ele deve ter acesso a um dispositivo `/dev/urandom` ou `/dev/random`.

A opção --with-system-ciphers do comando "configure" está disponível, o que faz com que o PHP use a lista de cifras do sistema em vez de um padrão fixo codificado.

> Nota: Nota para usuários do Win32

> Para que esta extensão funcione, existem arquivos DLL que devem estar disponíveis no PATH do sistema Windows. Para saber como fazer isso, veja a FAQ intitulada "Como eu adiciono o meu diretório PHP ao PATH do Windows". Embora copiar arquivos DLL da pasta do PHP para o diretório system do Windows também funcione (porque o diretório system está, por padrão, no PATH do sistema), isso não é recomendado. Esta extensão requer que os seguintes arquivos estejam no PATH: libeay32.dll, ou, a partir do OpenSSL 1.1, libcrypto-*.dll

> Além disso, se houver planos de usar as funções de geração de chaves e assinatura de certificados, será necessário instalar um arquivo openssl.cnf válido em seu sistema. Existe um arquivo de configuração de exemplo incluído nas distribuições binárias do PHP para Win32, no diretório extras/ssl.

> O PHP pesquisará o openssl.cnf usando a seguinte lógica:

> - a variável de ambiente `OPENSSL_CONF`, se definida, será usada como o caminho (incluindo o nome do arquivo) do arquivo de configuração.
> - a variável de ambiente `SSLEAY_CONF`, se definida, será usada como o caminho (incluindo o nome do arquivo) do arquivo de configuração.
> - Será assumido que o arquivo openssl.cnf deve ser encontrado na área padrão de certificados, conforme configurado no momento em que a DLL do openssl foi compilada. Isso geralmente significa que o nome de arquivo padrão é C:\Program Files\Common Files\SSL\openssl.cnf (x64) ou C:\Program Files (x86)\Common Files\SSL\openssl.cnf (x86), ou, antes do PHP 7.4.0, C:\usr\local\ssl\openssl.cnf.
> É necessário escolher de o arquivo de configuração deve ser instalado no caminho padrão ou em outro lugar e usar variáveis de ambiente (possivelmente uma configuração para cada host virtual) para localizar o arquivo de configuração. Observe que é possível substituir o caminho padrão do script usando as opções no parâmetro `options` das funções que exigem um arquivo de configuração.
> Cuidado

> Deve ser assegurado que usuários não privilegiados não tenham permissão para modificar openssl.cnf.

> A partir do OpenSSL 3.0.0, que é usado no Windows por padrão a partir do PHP 8.2.0, vários algoritmos foram considerados legados. Esses algoritmos comumente caíram em desuso, foram considerados inseguros pela comunidade criptográfica ou algo semelhante. Esses algoritmos ainda estão disponíveis através do provedor legado (extras/ssl/legacy.dll); seu uso é descrito na seção sobre » configuração do provedor no manual do OpenSSL.

### Registro de Alterações

Versão | Descrição
--- | ---
7.4.0 | A opção --with-openssl[=DIR] não aceita mais um argumento de diretório, em favor da configuração da variável pkg-config PKG_CONFIG_PATH para a localização do OpenSSL ou especificando as variáveis OPENSSL_LIBS e OPENSSL_CFLAGS.
7.4.0 | O caminho de configuração padrão do OpenSSL foi alterado de C:\usr\local\ssl para C:\Program Files\Common Files\SSL e C:\Program Files (x86)\Common Files\SSL, respectivamente.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de Configuração de openssl
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
openssl.cafile | "" | `INI_PERDIR` |
openssl.capath | "" | `INI_PERDIR` |
openssl.libctx | "custom" | `INI_PERDIR` |

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`openssl.cafile` string

  Localização do arquivo da Autoridade de Certificação no sistema de arquivos local que deve ser usado com a opção de contexto verify_peer para autenticar a identidade do peer remoto.

`openssl.capath` string

  Se cafile não for especificado ou se o certificado não for encontrado lá, o diretório apontado por capath será pesquisado para um certificado adequado. capath deve ser um diretório de certificado com hash correto.

`openssl.libctx` string
  Especifica o tipo de contexto de biblioteca OpenSSL a ser usado. O valor padrão, `custom`, cria um contexto de biblioteca separado para cada trabalhador ou thread. Isso melhora o isolamento em relação a outras bibliotecas que estejam usando OpenSSL e, em compilações ZTS, aumenta a separação entre threads. Também é possível usar o valor `default`, que faz com que o PHP use o contexto de biblioteca padrão global do OpenSSL.

Veja também as opções de contexto de fluxo SSL.

## Tipos de Recurso

Antes do PHP 8.0.0, havia 3 tipos de recursos definidos no módulo OpenSSL:

- `OpenSSL key`
- `OpenSSL X.509`
- `OpenSSL X.509 CSR`

# Constantes predefinidas

## Índice

- Opções de verificação de propósito
- Opções de preenchimento para criptografia assimétrica
- Tipos de chave
- Opções/Constantes PKCS7
- Opções/Constantes CMS
- Algoritmos de Assinatura
- Cifras (Ciphers)
- Constantes de versão
- Constantes de indicação de nome do servidor
- Outras constantes

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

## Opções de verificação de propósito

`X509_PURPOSE_SSL_CLIENT` (int)
`X509_PURPOSE_SSL_SERVER` (int)
`X509_PURPOSE_NS_SSL_SERVER` (int)
`X509_PURPOSE_SMIME_SIGN` (int)
`X509_PURPOSE_SMIME_ENCRYPT` (int)
`X509_PURPOSE_CRL_SIGN` (int)
`X509_PURPOSE_ANY` (int)
`X509_PURPOSE_OCSP_HELPER` (int)
  Verifica o certificado para uso como auxiliar de resposta OCSP. Disponível a partir do PHP 8.4.0.
`X509_PURPOSE_TIMESTAMP_SIGN` (int)
  Verifica o certificado para uso como um signatário de timestamp confiável. Disponível a partir do PHP 8.4.0.

## Opções de preenchimento para criptografia assimétrica

`OPENSSL_PKCS1_PADDING` (int)
`OPENSSL_SSLV23_PADDING` (int)
`OPENSSL_NO_PADDING` (int)
`OPENSSL_PKCS1_OAEP_PADDING` (int)
`OPENSSL_PKCS1_PSS_PADDING` (int)
  Preenchimento RSA-PSS. Disponível a partir do PHP 8.5.0.

## Tipos de chave

`OPENSSL_KEYTYPE_RSA` (int)
  Tipo de chave RSA.
`OPENSSL_KEYTYPE_DSA` (int)
  Tipo de chave DSA.
`OPENSSL_KEYTYPE_DH` (int)
  Tipo de chave DH (Diffie-Hellman).
`OPENSSL_KEYTYPE_EC` (int)
  Tipo de chave curva elíptica.
`OPENSSL_KEYTYPE_X25519` (int)
  Tipo de chave curva X25519. Esta constante só está disponível quando o PHP for compilado com o OpenSSL 3.0+.
`OPENSSL_KEYTYPE_ED25519` (int)
  Tipo de chave curva Ed25519. Esta constante só está disponível quando o PHP for compilado com o OpenSSL 3.0+.
`OPENSSL_KEYTYPE_X448` (int)
  Tipo de chave curva X448. Esta constante só está disponível quando o PHP for compilado com o OpenSSL 3.0+.
`OPENSSL_KEYTYPE_ED448` (int)
  Tipo de chave curva Ed448. Esta constante só está disponível quando o PHP for compilado com o OpenSSL 3.0+.

## Opções/Constantes PKCS7

As funções S/MIME usam opções que são especificadas usando um campo de bits que pode incluir um ou mais dos seguintes valores:

CONSTANTES PKCS7
Constante | Descrição
--- | ---
`PKCS7_TEXT` (int) | Adiciona cabeçalhos de tipo de conteúdo `text/plain` à mensagem criptografada/assinada. Se estiver descriptografando ou verificando, ele remove esses cabeçalhos da saída - se a mensagem descriptografada ou verificada não for do tipo MIME `text/plain`, então ocorrerá um erro.
`PKCS7_BINARY` (int) | Normalmente, a mensagem de entrada é convertida para o formato "canônico", que está efetivamente usando `CR` e `LF` como fim de linha: conforme exigido pela especificação S/MIME. Quando esta opção está presente, nenhuma tradução ocorre. Isso é útil ao manipular dados binários que podem não estar no formato MIME.
`PKCS7_NOINTERN` (int) | Ao verificar uma mensagem, os certificados (se houver) incluídos na mensagem são normalmente pesquisados para o certificado de assinatura. Com esta opção, apenas os certificados especificados no parâmetro `untrusted_certificates_filename` de openssl_pkcs7_verify() são usados. No entanto, os certificados fornecidos ainda podem ser usados como CAs não confiáveis.
`PKCS7_NOVERIFY` (int) | Não verifica o certificado do signatário de uma mensagem assinada.
`PKCS7_NOCHAIN` (int) | Não encadeia a verificação de certificados de signatários: ou seja, não usa os certificados na mensagem assinada como CAs não confiáveis.
`PKCS7_NOCERTS` (int) | Ao assinar uma mensagem, o certificado do signatário normalmente é incluído - com esta opção, ele é excluído. Isso reduzirá o tamanho da mensagem assinada, mas o verificador deve ter uma cópia do certificado do signatário disponível localmente (passado usando o `untrusted_certificates_filename` para openssl_pkcs7_verify(), por exemplo).
`PKCS7_NOATTR` (int) | Normalmente, quando uma mensagem é assinada, um conjunto de atributos é incluído, que inclui o tempo de assinatura e os algoritmos simétricos suportados. Com esta opção, eles não são incluídos.
`PKCS7_DETACHED` (int) | Ao assinar uma mensagem, usa a assinatura de texto simples com o tipo MIME `"multipart/signed"`. Este é o padrão não for especificada nsenhuma opção no parâmetro `flags` para openssl_pkcs7_sign(). Se esta opção for desativada, a mensagem será assinada usando assinatura opaca, que é mais resistente à tradução por retransmissões de e-mail, mas não pode ser lida por agentes de e-mail que não suportam S/MIME.
`PKCS7_NOSIGS` (int) | Não tenta verificar as assinaturas em uma mensagem
`PKCS7_NOOLDMIMETYPE` (int) | Disponível a partir do PHP 8.3.0. Define o content-type como `application/pkcs7-mime` em vez de `application/x-pkcs7-mime` para criptografar uma mensagem.
`PKCS7_NOSMIMECAP` (int) | Disponível a partir do PHP 8.5.0. Não inclui as capacidades S/MIME (SMIMECapabilities) na assinatura.
`PKCS7_CRLFEOL` (int) | Disponível a partir do PHP 8.5.0. Usa `CRLF` como fim de linha na saída.
`PKCS7_NOCRL` (int) | Disponível a partir do PHP 8.5.0. Não inclui as CRLs na estrutura PKCS7.
`PKCS7_NO_DUAL_CONTENT` (int) | Disponível a partir do PHP 8.5.0. Não inclui conteúdo duplicado, evitando a duplicação do conteúdo assinado.

## Opções/Constantes CMS

As funções do CMS usam opções que são especificados usando um campo de bits que pode incluir um ou mais dos seguintes valores:

CONSTANTES CMS
Constante | Descrição
--- | ---
`OPENSSL_CMS_TEXT` (int) | Adiciona cabeçalhos de tipo de conteúdo text/plain a mensagens criptografadas/assinadas. Se estiver descriptografando ou verificando, ela remove esses cabeçalhos da saída - se a mensagem descriptografada ou verificada não for do tipo MIME text/plain, ocorrerá um erro.
`OPENSSL_CMS_BINARY` (int) | Normalmente, a mensagem de entrada é convertida para o formato "canônico", que está efetivamente usando `CR` e `LF` como fim de linha: conforme exigido pela especificação CMS. Quando esta opção está presente, nenhuma tradução ocorre. Isso é útil ao manipular dados binários que podem não estar no formato CMS.
`OPENSSL_CMS_NOINTERN` (int) | Ao verificar uma mensagem, os certificados (se houver) incluídos na mensagem são normalmente pesquisados para o certificado de assinatura. Com esta opção, apenas os certificados especificados no parâmetro `untrusted_certificates_filename` de openssl_cms_verify() são usados. No entanto, os certificados fornecidos ainda podem ser usados como CAs não confiáveis.
`OPENSSL_CMS_NOVERIFY` (int) | Não verifica o certificado do signatário de uma mensagem assinada.
`OPENSSL_CMS_NOCERTS` (int) | Ao assinar uma mensagem, o certificado do signatário normalmente é incluído - com esta opção, ele é excluído. Isso reduzirá o tamanho da mensagem assinada, mas o verificador deve ter uma cópia do certificado do signatário disponível localmente (passado usando o `untrusted_certificates_filename` para openssl_cms_verify(), por exemplo).
`OPENSSL_CMS_NOATTR` (int) | Normalmente, quando uma mensagem é assinada, um conjunto de atributos é incluído, que inclui o tempo de assinatura e os algoritmos simétricos suportados. Com esta opção, eles não são incluídos.
`OPENSSL_CMS_DETACHED` (int) | Ao assinar uma mensagem, use a assinatura de texto simples com o tipo MIME `"multipart/signed"`. Este é o padrão se não for especificada nenhuma opção no parâmetro `flags` para openssl_cms_sign(). Se esta opção for desativada, a mensagem será assinada usando assinatura opaca, que é mais resistente à tradução por retransmissões de e-mail, mas não pode ser lida por agentes de e-mail que não suportam S/MIME.
`OPENSSL_CMS_NOSIGS` (int) | Não tenta verificar as assinaturas em uma mensagem
`OPENSSL_CMS_OLDMIMETYPE` (int) | Disponível a partir do PHP 8.3.0. Define o content-type como `application/x-pkcs7-mime` em vez de `application/pkcs7-mime` para criptografar uma mensagem.

## Algoritmos de Assinatura

`OPENSSL_ALGO_DSS1` (int)
`OPENSSL_ALGO_SHA1` (int)
  Usado como algoritmo padrão por openssl_sign() e openssl_verify().
`OPENSSL_ALGO_SHA224` (int)
`OPENSSL_ALGO_SHA256` (int)
`OPENSSL_ALGO_SHA384` (int)
`OPENSSL_ALGO_SHA512` (int)
`OPENSSL_ALGO_RMD160` (int)
`OPENSSL_ALGO_MD5` (int)
`OPENSSL_ALGO_MD4` (int)
`OPENSSL_ALGO_MD2` (int)
  Esta constante só está disponível se o PHP for compilado com suporte a MD2. Isso requer passar o CFLAG `-DHAVE_OPENSSL_MD2_H` ao compilar o PHP, e `enable-md2` ao compilar o OpenSSL 1.0.0+.

## Cifras (Ciphers)

`OPENSSL_DEFAULT_STREAM_CIPHERS` (string)
  Lista de cifras padrão.
`OPENSSL_CIPHER_RC2_40` (int)
`OPENSSL_CIPHER_RC2_128` (int)
`OPENSSL_CIPHER_RC2_64` (int)
`OPENSSL_CIPHER_DES` (int)
`OPENSSL_CIPHER_3DES` (int)

`OPENSSL_CIPHER_AES_128_CBC` (int)
`OPENSSL_CIPHER_AES_192_CBC` (int)
`OPENSSL_CIPHER_AES_256_CBC` (int)

## Constantes de versão

`OPENSSL_VERSION_TEXT` (string)
`OPENSSL_VERSION_NUMBER` (int)

## Constantes de indicação de nome do servidor

`OPENSSL_TLSEXT_SERVER_NAME` (int)
  Se o suporte SNI está disponível ou não.

> Nota:

> Esta constante requer que o PHP seja compilado com OpenSSL 0.9.8j ou superior.

## Outras constantes

`OPENSSL_RAW_DATA` (int)
  Se `OPENSSL_RAW_DATA` for definido em openssl_encrypt() ou openssl_decrypt(), os dados serão retornados sem alteração. Quando não for especificada, os dados codificados em Base64 serão retornados ao chamador.
`OPENSSL_DONT_ZERO_PAD_KEY` (int)
  Evita que openssl_encrypt() preencha chaves menores que o comprimento padrão.
`OPENSSL_ZERO_PADDING` (int)
  Por padrão, as operações de criptografia são preenchidas usando o preenchimento de bloco padrão e o preenchimento é verificado e removido ao descriptografar. Se `OPENSSL_ZERO_PADDING` for definido em `options` como openssl_encrypt() ou openssl_decrypt(), nenhum preenchimento será realizado, a quantidade total de dados criptografados ou descriptografados deve ser um múltiplo do tamanho do bloco ou ocorrerá um erro.
`OPENSSL_ENCODING_SMIME` (int)
  Indica que a codificação é S/MIME.
`OPENSSL_ENCODING_DER` (int)
  Indica que a codificação é DER.
`OPENSSL_ENCODING_PEM` (int)
  Indica que a codificação é PEM.

# Parâmetros de chave/certificado

Várias funções openssl exigem um parâmetro de chave ou certificado. Os seguintes métodos podem ser usados para obtê-los:

- Certificados

  1. Uma instância OpenSSLCertificate (ou antes do PHP 8.0.0, um resource do tipo `OpenSSL X.509`) retornada de openssl_x509_read()
  2. Uma string com o formato file://path/to/cert.pem; o arquivo nomeado deve conter um certificado codificado PEM
  3. Uma string contendo o conteúdo de um certificado, codificado em PEM, pode começar com `-----BEGIN CERTIFICATE-----`

- Solicitações de assinatura de certificado (CSRs)

  1. Uma instância de OpenSSLCertificateSigningRequest (ou antes do PHP 8.0.0, um resource do tipo `OpenSSL X.509 CSR`) retornado de openssl_csr_new()
  2. Uma string com o formato file://path/to/csr.pem; o arquivo nomeado deve conter um CSR codificado em PEM.
  3. Uma string contendo o conteúdo de um CSR, codificado em PEM, pode começar com `-----BEGIN CERTIFICATE REQUEST-----`

- Chaves Públicas/Privadas

  1. Uma instância de OpenSSLAsymmetricKey (ou anterior ao PHP 8.0.0, um resource do tipo `OpenSSL key`) retornada de openssl_get_publickey() ou openssl_get_privatekey()
  2. Somente para chaves públicas: uma instância de OpenSSLCertificate (ou anterior ao PHP 8.0.0, um resource do tipo `OpenSSL X.509`)
  3. Uma string com o formato file://path/to/file.pem - o arquivo nomeado deve conter um certificado e/ou chave privada codificado em PEM (pode conter ambos)
  4. Uma string contendo o conteúdo de um certificado/chave, codificado em PEM, pode começar com `-----BEGIN PUBLIC KEY-----`
  5. Para chaves privadas, pode ser usada também a sintaxe `array($key, $passphrase)` onde $key representa uma chave especificada usando a notação file:// ou de conteúdo textual acima, e $passphrase representa uma string contendo a senha para essa chave privada

# Verificação de Certificado

Ao chamar uma função que verificará uma assinatura/certificado, o parâmetro `ca_info` é um array contendo nomes de arquivo e diretório que especificam os locais de arquivos CA confiáveis. Se um diretório for especificado, ele deve ser um diretório com hash corretamente formado, como o comando openssl usaria.

# Funções de OpenSSL

# openssl_cipher_iv_length

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

openssl_cipher_iv_length — Obtém o comprimento do vetor de inicialização da cifra

### Descrição

function openssl_cipher_iv_length(string `$cipher_algo`): int|false

Obtém o comprimento do vetor de inicialização (iv) da cifra

### Parâmetros

`cipher_algo`

  O método de criptografia, consulte openssl_get_cipher_methods() para uma lista de valores possíveis.

### Valor Retornado

Retorna o comprimento da cifra em caso de sucesso, ou `false` em caso de falha.

### Erros/Exceções

Emite um erro de nível `E_WARNING` quando o algoritmo de criptografia é desconhecido.

### Exemplos

Exemplo #1 Exemplo de openssl_cipher_iv_length()

    <?php
    $method = 'AES-128-CBC';
    $ivlen = openssl_cipher_iv_length($method);

    echo $ivlen;
    ?>

O exemplo acima produzirá algo semelhante a:

    16

# openssl_cipher_key_length

(PHP 8 >= 8.2.0)

openssl_cipher_key_length — Obtém o comprimento da chave da cifra

### Descrição

function openssl_cipher_key_length(string `$cipher_algo`): int|false

Obtém o comprimento da chave da cifra.

### Parâmetros

`cipher_algo`

  O método de criptografia, consulte openssl_get_cipher_methods() para uma lista de valores possíveis.

### Valor Retornado

Retorna o comprimento da cifra em caso de sucesso, ou `false` em caso de falha.

### Erros/Exceções

Emite um erro de nível `E_WARNING` quando o algoritmo de criptografia é desconhecido.

### Exemplos

Exemplo #1 Exemplo de openssl_cipher_key_length()

    <?php
    $method = 'AES-128-CBC';

    var_dump(openssl_cipher_key_length($method));
    ?>

O exemplo acima produzirá algo semelhante a:

    int(16)

# openssl_cms_decrypt

(PHP 8)

openssl_cms_decrypt — Descriptografa uma mensagem CMS

### Descrição

function openssl_cms_decrypt(
string `$input_filename`,
string `$output_filename`,
#[\SensitiveParameter]OpenSSLCertificate|string `$certificate`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string|null `$private_key` = `null`,
int `$encoding` = `OPENSSL_ENCODING_SMIME`
): bool

Descriptografa uma mensagem CMS.

### Parâmetros

`input_filename`

  O nome de um arquivo que contém conteúdo criptografado.

`output_filename`

  O nome do arquivo para depositar o conteúdo descriptografado.

`certificate`

  O nome do arquivo que contém um certificado do destinatário.

`private_key`

  O nome do arquivo que contém uma chave PKCS#8.

`encoding`

  A codificação do arquivo de entrada. Uma das constantes `OPENSSL_ENCODING_SMIME`, `OPENSSL_ENCODING_DER` ou `OPENSSL_ENCODING_PEM`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# openssl_cms_encrypt

(PHP 8)

openssl_cms_encrypt — Criptografa uma mensagem CMS

### Descrição

function openssl_cms_encrypt(
string `$input_filename`,
string `$output_filename`,
OpenSSLCertificate|array|string `$certificate`,
?array `$headers`,
int `$flags` = 0,
int `$encoding` = `OPENSSL_ENCODING_SMIME`,
string|int `$cipher_algo` = `OPENSSL_CIPHER_AES_128_CBC`
): bool

Esta função criptografa o conteúdo para um ou mais destinatários, com base nos certificados que são passados ​​para ela.

### Parâmetros

`input_filename`

  O arquivo a ser criptografado.

`output_filename`

  O arquivo de saída.

`certificate`

  Destinatários para criptografar.

`headers`

  Cabeçalhos a serem incluídos quando S/MIME for usado.

`flags`

  Opções a serem passadas ​​para CMS_sign.

`encoding`

  Uma codificação para saída. Uma das constantes `OPENSSL_ENCODING_SMIME`, `OPENSSL_ENCODING_DER` ou `OPENSSL_ENCODING_PEM`.

`cipher_algo`

  Uma cifra para ser usada.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | `cipher_algo` agora é do tipo int ou string. Anteriormente, era do tipo int.
8.1.0 | O algoritmo de criptografia padrão (`cipher_algo`) agora é AES-128-CBC (`OPENSSL_CIPHER_AES_128_CBC`). Anteriormente, PKCS7/CMS era usado (`OPENSSL_CIPHER_RC2_40`).

# openssl_cms_read

(PHP 8)

openssl_cms_read — Exporta o arquivo CMS para um array de certificados PEM

### Descrição

function openssl_cms_read(string `$input_filename`, array `&$certificates`): bool

Realiza exatamente o análogo de openssl_pkcs7_read().

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`input_filename`

`certificates`

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# openssl_cms_sign

(PHP 8)

openssl_cms_sign — Assina um arquivo

### Descrição

function openssl_cms_sign(
string `$input_filename`,
string `$output_filename`,
OpenSSLCertificate|string `$certificate`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
?array `$headers`,
int `$flags` = 0,
int `$encoding` = `OPENSSL_ENCODING_SMIME`,
?string `$untrusted_certificates_filename` = `null`
): bool

Esta função assina um arquivo com uma certificado X.509 e uma chave.

### Parâmetros

`input_filename`

  O nome do arquivo a ser assinado.

`output_filename`

  O nome do arquivo onde os resultados serão armazenados.

`certificate`

  O certificado para assinatura. Consulte os parâmetros de chave/certificado para uma lista de valores válidos.

`private_key`

  A chave associada ao certificado informado no parâmetro `certificate`. Consulte os parâmetros de chave/certificado para uma lista de valores válidos.

`headers`

  Um array de cabeçalhos a serem incluídos na saída S/MIME.

`flags`

  Opções a serem passadas a cms_sign().

`encoding`

  A codificação do arquivo de saída. Uma das constantes `OPENSSL_ENCODING_SMIME`, `OPENSSL_ENCODING_DER` ou `OPENSSL_ENCODING_PEM`.

`untrusted_certificates_filename`

  Certificados intermediários a serem incluídos na assinatura.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de openssl_cms_sign()

    <?php

    openssl_cms_sign('entrada.txt', 'saída.txt', 'file://certificado.pem', 'file://chaveprivada.pem', null, OPENSSL_CMS_BINARY, OPENSSL_ENCODING_DER, 'cadeia_de_certificados.pem');
    ?>

# openssl_cms_verify

(PHP 8)

openssl_cms_verify — Verifica uma assinatura CMS

### Descrição

function openssl_cms_verify(
string `$input_filename`,
int `$flags` = 0,
?string `$certificates` = `null`,
array `$ca_info` = [],
?string `$untrusted_certificates_filename` = `null`,
?string `$content` = `null`,
?string `$pk7` = `null`,
?string `$sigfile` = `null`,
int `$encoding` = `OPENSSL_ENCODING_SMIME`
): bool

Esta função verifica uma assinatura CMS, anexada ou não, com a codificação especificada.

### Parâmetros

`input_filename`

  O arquivo de entrada.

`flags`

  Opções a serem passadas a cms_verify().

`certificates`

  Um arquivo com o certificado do signatário e opcionalmente certificados intermediários.

`ca_info`

  Um array contendo certificados de autoridades certificadoras autoassinados.

`untrusted_certificates_filename`

  Um arquivo contendo certificados intermediários adicionais.

`content`

  Um arquivo apontando para o conteúdo quando as assinaturas não estão anexadas.

`pk7`

`sigfile`

  Um arquivo onde a assinatura será gravada.

`encoding`

  A codificação do arquivo de entrada. Uma das constantes `OPENSSL_ENCODING_SMIME`, `OPENSSL_ENCODING_DER` ou `OPENSSL_ENCODING_PEM`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# openssl_csr_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_export — Exporta um CSR como uma string

### Descrição

function openssl_csr_export(OpenSSLCertificateSigningRequest|string `$csr`, string `&$output`, bool `$no_text` = `true`): bool

openssl_csr_export() exporta a Requisição de Assinatura de Certificado, representada pelo parâmetro `csr`, em formato PEM, na variável informada em `output`, que é passada por referência.

### Parâmetros

`csr`
  Consulte Parâmetros CSR para obter uma lista de valores válidos.
`output`

  Em caso de sucesso, esta string conterá o CSR codificado no formato PEM

`no_text`
  O parâmetro opcional `notext` afeta a verbosidade da saída; se for `false`, então informações adicionais legíveis para humanos serão incluídas na saída. O valor padrão de `notext` é `true`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `csr` aceita agora uma instância de OpenSSLCertificateSigningRequest; anteriormente, um resource do tipo `OpenSSL X.509 CSR` era aceito.

### Exemplos

Exemplo #1 Exemplo de openssl_csr_export()

    <?php
    $subject = array(
        "commonName" => "example.com",
    );
    $private_key = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));
    $configargs = array(
        'digest_alg' => 'sha256WithRSAEncryption'
    );
    $csr = openssl_csr_new($subject, $private_key, $configargs);
    openssl_csr_export($csr, $csr_string);
    echo $csr_string;
    ?>

### Veja Também

- openssl_csr_export_to_file() - Exporta um CSR para um arquivo
- openssl_csr_new() - Gera um CSR
- openssl_csr_sign() - Assina um CSR com outro certificado (ou ele mesmo) e gera um certificado

# openssl_csr_export_to_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_export_to_file — Exporta um CSR para um arquivo

### Descrição

function openssl_csr_export_to_file(OpenSSLCertificateSigningRequest|string `$csr`, string `$output_filename`, bool `$no_text` = `true`): bool

openssl_csr_export_to_file() grava a Requisição de Assinatura de Certificado, representada pelo parâmetro `csr`, em formato PEM, no arquivo informado em `output_filename`.

### Parâmetros

`csr`
  Consulte Parâmetros CSR para obter uma lista de valores válidos.
`output_filename`

  Caminho para o arquivo de saída.

`no_text`
  O parâmetro opcional `notext` afeta a verbosidade da saída; se for `false`, então informações adicionais legíveis para humanos serão incluídas na saída. O valor padrão de `notext` é `true`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `csr` aceita agora uma instância de OpenSSLCertificateSigningRequest; anteriormente, um resource do tipo `OpenSSL X.509 CSR` era aceito.

### Exemplos

Exemplo #1 Exemplo de openssl_csr_export_to_file()

    <?php
    $subject = array(
        "commonName" => "example.com",
    );
    $private_key = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));
    $csr = openssl_csr_new($subject, $private_key, array('digest_alg' => 'sha384') );
    openssl_pkey_export_to_file($private_key, 'chave-privada.key');
    // Junto com o assunto, o CSR contém a chave pública correspondente à chave privada
    openssl_csr_export_to_file($csr, 'csr-exemplo.pem');
    ?>

### Veja Também

- openssl_csr_export() - Exporta um CSR como uma string
- openssl_csr_new() - Gera um CSR
- openssl_csr_sign() - Assina um CSR com outro certificado (ou ele mesmo) e gera um certificado

# openssl_csr_get_public_key

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

openssl_csr_get_public_key — Retorna a chave pública de um CSR

### Descrição

function openssl_csr_get_public_key(OpenSSLCertificateSigningRequest|string `$csr`, bool `$short_names` = `true`): OpenSSLAsymmetricKey|false

openssl_csr_get_public_key() extrai a chave pública de `csr` e a prepara para uso por outras funções.

### Parâmetros

`csr`
  Consulte Parâmetros CSR para obter uma lista de valores válidos.
`short_names`
  Aviso

  Este parâmetro é ignorado

### Valor Retornado

Retorna um OpenSSLAsymmetricKey em caso de sucesso ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Em caso de sucesso, esta função retorna uma instância OpenSSLAsymmetricKey agora; anteriormente, retornava um resource do tipo `OpenSSL key`.
8.0.0 | `csr` aceita uma instância OpenSSLCertificateSigningRequest agora; anteriormente, um resource do tipo `OpenSSL X.509 CSR` era aceito.

### Exemplos

Exemplo #1 Exemplo de openssl_csr_get_public_key()

    <?php
    $subject = array(
        "commonName" => "example.com",
    );
    $private_key = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));
    $csr = openssl_csr_new($subject, $private_key, array('digest_alg' => 'sha256') );
    $public_key = openssl_csr_get_public_key($csr);
    $info = openssl_pkey_get_details($public_key);
    echo $info['key'];
    ?>

### Veja Também

- openssl_csr_get_subject() - Retorna o assunto de um CSR
- openssl_csr_new() - Gera um CSR
- openssl_pkey_get_details() - Retorna um array com os detalhes da chave
- openssl_pkey_export_to_file() - Obtém uma representação exportável de uma chave em um arquivo
- openssl_pkey_export() - Obtém uma representação exportável de uma chave em uma string

# openssl_csr_get_subject

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

openssl_csr_get_subject — Retorna o assunto de um CSR

### Descrição

function openssl_csr_get_subject(OpenSSLCertificateSigningRequest|string `$csr`, bool `$short_names` = `true`): array|false

openssl_csr_get_subject() retorna informações de nome distinto do assunto codificadas em `csr` incluindo os campos commonName (CN), OrganizationName (O), countryName (C) etc.

### Parâmetros

`csr`
  Consulte Parâmetros CSR para obter uma lista de valores válidos.
`short_names`

  `short_names` controla como os dados são indexados no array - se `short_names` for `true` (o padrão), os campos serão indexados com o formato de nome abreviado, caso contrário, o formato de nome longo será usado - por exemplo: CN é o formato de nome abreviado de commonName.

### Valor Retornado

Retorna um array associativo com a descrição do assunto, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `csr` aceita uma instância OpenSSLCertificateSigningRequest agora; anteriormente, um resource do tipo `OpenSSL X.509 CSR` era aceito.

### Exemplos

Exemplo #1 Exemplo de openssl_csr_get_subject()

    <?php
    $subject = array(
        "countryName" => "CA",
        "stateOrProvinceName" => "Alberta",
        "localityName" => "Calgary",
        "organizationName" => "XYZ Widgets Inc",
        "organizationalUnitName" => "PHP Documentation Team",
        "commonName" => "Wez Furlong",
        "emailAddress" => "wez@example.com",
    );
    $private_key = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));
    $configargs = array(
        'digest_alg' => 'sha512WithRSAEncryption'
    );
    $csr = openssl_csr_new($subject, $privkey, $configargs);
    print_r(openssl_csr_get_subject($csr));
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [C] => CA
        [ST] => Alberta
        [L] => Calgary
        [O] => XYZ Widgets Inc
        [OU] => PHP Documentation Team
        [CN] => Wez Furlong
        [emailAddress] => wez@example.com
    )

### Veja Também

- openssl_csr_new() - Gera um CSR
- openssl_csr_get_public_key() - Retorna a chave pública de um CSR
- openssl_x509_parse() - Analisa um certificado X509 e retorna as informações como um array

# openssl_csr_new

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_new — Gera um CSR

### Descrição

function openssl_csr_new(
array `$distinguished_names`,
#[\SensitiveParameter]?OpenSSLAsymmetricKey `&$private_key`,
?array `$options` = `null`,
?array `$extra_attributes` = `null`
): OpenSSLCertificateSigningRequest|bool

openssl_csr_new() gera um novo CSR com base na informação fornecida por `distinguished_names`.

> Nota: É preciso ter um arquivo openssl.cnf válido instalado para que esta função funcione corretamente. Consulte as notas na seção de instalação para obter mais informações.

### Parâmetros

`distinguished_names`

  O Nome Distinto (DN) ou campos de assunto a serem usados no certificado. O parâmetro `distinguished_names` é um array associativo onde as chaves representam os nomes de atributo dos Nomes Distintos e os valores podem ser strings (para valores simples) ou arrays (se for necessário definir múltiplos valores).

`private_key`

  `private_key` deve ser definido par uma chave privada que tenha sido gerada anteriormente por openssl_pkey_new() (ou de outra forma obtida pelas outras funções da família openssl_pkey), ou uma variável `null`. Se o valor for uma variável `null`, uma nova chave primária será gerada com base no parâmetro `options` fornecido e será atribuída à variável informada. A parte pública correspondente da chave será usada para assinar o CSR.

`options`

  Por padrão, a informação no `openssl.conf` do sistema é utilizada para inicializar a requisição; uma seção do arquivo de configuração pode ser especificada configurando a chave `config_section_section` no parâmetro `options`. Um arquivo de configuração Openssl alternativo pode ser especificado configurando o valor da chave `config` para o caminho do arquivo a ser usado. As chaves a seguir, se estiverem presentes em `options`, comportam-se como suas equivalentes no `openssl.conf`, como listadas na tabela abaixo.

  Subsituição de configuração
  Chave `options` | Tipo | Equivalente no `openssl.conf` | Descrição
  --- | --- | --- | ---
  digest_alg | string | default_md | Método de resumo ou de hash de assinatura, normalmente um dos métodos informados por openssl_get_md_methods()
  x509_extensions | string | x509_extensions | Seleciona quais extensões devem ser usadas ao criar um certificado x509
  req_extensions | string | req_extensions | Seleciona quais extensões devem ser usadas ao criar um CSR
  private_key_bits | int | default_bits | Especifica quantos bits devem ser usados para gerar uma chave privada
  private_key_type | int | none | Especifica o tipo de chave privada a ser criada. Pode ser uma das constantes `OPENSSL_KEYTYPE_DSA`, `OPENSSL_KEYTYPE_DH`, `OPENSSL_KEYTYPE_RSA` ou `OPENSSL_KEYTYPE_EC`. O valor padrão é `OPENSSL_KEYTYPE_RSA`.
  encrypt_key | bool | encrypt_key | Uma chave exportada (com senha) deve ser criptografada?
  encrypt_key_cipher | int | none | Uma das constantes de cifra.
  curve_name | string | none | Um dos nomes de curva informados por openssl_get_curve_names().
  config | string | N/A | Caminho para o arquivo alternativo openssl.conf.

`extra_attributes`

  `extra_attributes` é usado para especificar atributos adicionais para o CSR. É um array associativo cujas chaves são convertidas para OIDs e aplicadas como atributos CSR.

### Valor Retornado

Retorna o CSR em caso de sucesso, `true` se a criação do CSR for bem sucedida mas a assintura falhar ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | O array associativo do parâmetro `distinguished_names` agora suporta arrays como valores, permitindo que múltiplos sejam especificados para um único atributo.
8.4.0 | O parâmetro `extra_attributes` agora define corretamente os atributos CSR, ao invés de modificar o Nome Distinto do assunto como fazia antes incorretamente.
8.0.0 | Em caso de sucesso, esta função agora retorna uma instância de OpenSSLCertificateSigningRequest; anteriormente, retornava um resource do tipo `OpenSSL X.509 CSR`.
8.0.0 | `private_key` agora aceita uma instância de OpenSSLAsymmetricKey; anteriormente, aceitava um resource do tipo `OpenSSL key`.
7.1.0 | `options` agora também suporta `curve_name`.

### Exemplos

Exemplo #1 Criando um certificado autoassinado

    <?php
    // para certificados SSL de servidor, o commonName é o domínio a ser protegido
    // para certificados de e-mail S/MIME, o commonName é o proprietário do endereço de e-mail
    // campos de localização e identificação referem-se ao proprietário do domínio ou do e-mail a serem protegidos
    $dn = array(
        "countryName" => "GB",
        "stateOrProvinceName" => "Somerset",
        "localityName" => "Glastonbury",
        "organizationName" => "The Brain Room Limited",
        "organizationalUnitName" => "PHP Documentation Team",
        "commonName" => "Wez Furlong",
        "emailAddress" => "wez@example.com"
    );

    // Gera um novo par de chaves privadas (e públicas)
    $privkey = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));

    // Gera uma requisição de assinatura de certificado
    $csr = openssl_csr_new($dn, $privkey, array('digest_alg' => 'sha256'));

    // Gera um certificado autoassinado, válido por 365 dias
    $x509 = openssl_csr_sign($csr, null, $privkey, $days=365, array('digest_alg' => 'sha256'));

    // Grava a chave privada, o CSR e o certificado autoassinado para uso posterior
    openssl_csr_export($csr, $csrout)var_dump($csrout);
    openssl_x509_export($x509, $certout) and var_dump($certout);
    openssl_pkey_export($privkey, $pkeyout, "mypassword") and var_dump($pkeyout);

    // Exibe erros que possam ter ocorrido
    while (($e = openssl_error_string()) !== false) {
        echo $e . "\n";
    }
    ?>

Exemplo #2 Criando um certificado ECC autoassinado (a partir do PHP 7.1.0)

    <?php
    $subject = array(
        "commonName" => "docs.php.net",
    );

    // Gere um novo par de chaves privadas (e públicas)
    $private_key = openssl_pkey_new(array(
        "private_key_type" => OPENSSL_KEYTYPE_EC,
        "curve_name" => 'prime256v1',
    ));

    // Gera uma requisição de assinatura de certificado
    $csr = openssl_csr_new($subject, $private_key, array('digest_alg' => 'sha384'));

    // Gera um certificado EC autoassinado
    $x509 = openssl_csr_sign($csr, null, $private_key, $days=365, array('digest_alg' => 'sha384'));
    openssl_x509_export_to_file($x509, 'ecc-cert.pem');
    openssl_pkey_export_to_file($private_key, 'ecc-private.key');
    ?>

### Veja Também

- openssl_csr_sign() - Assina um CSR com outro certificado (ou ele mesmo) e gera um certificado

# openssl_csr_sign

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_sign — Assina um CSR com outro certificado (ou ele mesmo) e gera um certificado

### Descrição

function openssl_csr_sign(
OpenSSLCertificateSigningRequest|string `$csr`,
OpenSSLCertificate|string|null `$ca_certificate`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
int `$days`,
?array `$options` = `null`,
int `$serial` = 0,
?string `$serial_hex` = `null`
): OpenSSLCertificate|false

openssl_csr_sign() gera um certificado x509 a partir do CSR fornecido.

> Nota: É preciso ter um arquivo openssl.cnf válido instalado para que esta função funcione corretamente. Consulte as notas na seção de instalação para obter mais informações.

### Parâmetros

`csr`

  Um CSR gerado anteriormente por openssl_csr_new(). Também pode ser o caminho para um CSR codificado em PEM quando especificado como file://caminho/para/csr ou uma string exportada gerada por openssl_csr_export().

`ca_certificate`

  O certificado gerado será assinado por `ca_certificate`. Se `ca_certificate` for `null`, o certificado gerado será um certificado autoassinado.

`private_key`

  `private_key` é a chave privada que corresponde a `ca_certificate`.

`days`

  `days` especifica o período de validade do certificado gerado, em dias.

`options`

  A assinatura do CSR pode ter um ajuste fino usando `options`. Consulte openssl_csr_new() para mais informação sobre `options`.

`serial`

  Um número de série opcional do certificado emitido. Se não for especificado, o padrão será 0.

`serial_hex`

  Uma string hexadecimal opcional representando o número serial do certificado emitido. Se definido, tome precedência sobre o valor do parâmetro `serial`. Se não especificado ou se definido como `null`, o valor do parâmetro `serial` é usado no lugar.

### Valor Retornado

Retorna um OpenSSLCertificate em caso de sucesso, `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | O parâmetro `serial_hex` foi adicionado.
8.0.0 | Em caso de sucesso, esta função agora retorna uma instância de OpenSSLCertificate; anteriormente, retornava um resource do tipo `OpenSSL X.509`.
8.0.0 | `csr` aceita uma instância OpenSSLCertificateSigningRequest agora; anteriormente, um resource do tipo `OpenSSL X.509 CSR` era aceito.
8.0.0 | `ca_certificate` agora aceita uma instância de OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL X.509` era aceito.
8.0.0 | `private_key` agora aceita uma instância de OpenSSLAsymmetricKey ou de OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL key` ou do tipo `OpenSSL X.509` era aceito.

### Exemplos

Exemplo #1 Exemplo de openssl_csr_sign() - assinando um CSR (como implementar sua própria CA)

    <?php
    // Vamos supor que este script esteja configurado para receber
    // um CSR que foi colado em uma área de texto de outra página
    $csrdata = $_POST["CSR"];

    // Assinaremos a solicitação usando nosso próprio certificado de "autoridade
    // de certificação". Pode ser usado qualquer certificado para assinar outro, mas
    // o processo é inútil, a menos que o certificado de assinatura seja confiável
    // para o software/usuários que lidarão com o certificado recém-assinado

    // Precisamos do nosso certificado CA e de sua chave privada
    $cacert = "file://caminho/para/ca.crt";
    $privkey = array("file://caminho/para/ca.key", "sua_senha_da_chave_CA");

    $usercert = openssl_csr_sign($csrdata, $cacert, $privkey, 365, array('digest_alg'=>'sha256') );

    // Agora o certificado gerado é exibido para que o usuário possa
    // copiá-lo e colá-lo em sua configuração local (como um arquivo
    // para armazenar o certificado para o servidor SSL)
    openssl_x509_export($usercert, $certout);
    echo $certout;

    // Mostra todos os erros que ocorreram aqui
    while (($e = openssl_error_string()) !== false) {
        echo $e . "\n";
    }
    ?>

# openssl_decrypt

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_decrypt — Descritografa dados

### Descrição

function openssl_decrypt(
string `$data`,
string `$cipher_algo`,
#[\SensitiveParameter]string `$passphrase`,
int `$options` = 0,
string `$iv` = "",
?string `$tag` = `null`,
string `$aad` = ""
): string|false

Descriptografa uma string bruta ou codificada em base64 usando um determinado método e senha.

### Parâmetros

`data`

  A mensagem criptografada a ser descriptografada.

`cipher_algo`

  O método de criptografia. Para obter uma lista de métodos de criptografia disponíveis, use openssl_get_cipher_methods().

`passphrase`

  A senha. Se a senha for menor que o esperado, ela será preenchida silenciosamente com caracteres `NUL`; se a senha for maior que o esperado, ela será truncada silenciosamente.

  Cuidado

  Não há função de derivação de chave usada para `passphrase` como o próprio nome pode sugerir. A única operação utilizada é o preenchimento com caracteres `NUL` ou truncamento se o comprimento for diferente do esperado.

`options`

  `options` pode ser uma das constantes `OPENSSL_RAW_DATA`, `OPENSSL_ZERO_PADDING` ou `OPENSSL_DONT_ZERO_PAD_KEY`.

`iv`

  Um Vetor de Inicialização (IV) não-`null`. Se o IV for menor que o esperado, ele será preenchido com caracteres `NUL` e um alerta será emitido; se a senha for maior que o esperado, ela será truncada e um alerta será emitido.

`tag`

  A etiqueta de autenticação no modo de criptografia AEAD. Se estiver incorreto, a autenticação falha e a função retorna `false`.

  Cuidado

  O comprimento da etiqueta `tag` não é verificado pela função. É responsabilidade do chamador garantir que o comprimento da etiqueta corresponda ao comprimento da etiqueta recuperada quando openssl_encrypt() for chamada. Caso contrário, a descriptografia poderá ser bem-sucedida se a etiqueta fornecida corresponder apenas ao início da etiqueta adequada.

`aad`

  Dados autenticados adicionais.

### Valor Retornado

A string descriptografada em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Emite um erro de nível `E_WARNING` se um algoritmo de criptografia desconhecido for passado através do parâmetro `cipher_algo`.

Emite um erro de nível `E_WARNING` se um valor vazio for passado através do parâmetro `iv`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | `tag` agora pode ser nulo.
7.1.0 | Os parâmetros `tag` e `aad` foram adicionados.

### Veja Também

- openssl_encrypt() - Criptografa dados

# openssl_dh_compute_key

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_dh_compute_key — Calcula o segredo compartilhado para o valor público da chave pública DH remota e da chave DH local

### Descrição

function openssl_dh_compute_key(string `$public_key`, #[\SensitiveParameter]OpenSSLAsymmetricKey `$private_key`): string|false

O segredo compartilhado retornado por openssl_dh_compute_key() é frequentemente usado como uma chave de criptografia para comunicação secreta com uma parte remota. Isso é conhecido como intercâmbio de chaves Diffie-Hellman.

Cuidado

É importante usar os mesmos parâmetros DH para pares de chaves locais e remotos; caso contrário, o segredo gerado entre as duas partes não corresponderá.

> Nota: ECDH só é suportado a partir do PHP 8.1.0 e OpenSSL 3.0.0.

### Parâmetros

`public_key`

  Chave pública DH do ponto remoto.

`private_key`

  Uma chave privada DH local, correspondente à chave pública a ser compartilhada com o ponto remoto.

### Valor Retornado

Retorna o segredo compartilhado em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `private_key` agora aceita um OpenSSLAsymmetricKey; anteriormente, um resource do tipo `OpenSSL key` era aceito.

### Exemplos

Exemplo #1 Calculando um segredo compartilhado

Primeiro gera um par de chaves DH pública/privada localmente e faz com que a parte remota faça o mesmo. É necessário usar o utilitário `openssl` de linha de comando.

    # gera par de chaves privada/pública
    openssl dhparam -out dhparam.pem 2048
    openssl genpkey -paramfile dhparam.pem -out privatekey.pem

    # extrai apenas a chave pública
    openssl pkey -in privatekey.pem -pubout -out publickey.pem

Em seguida, a chave pública é enviada à parte remota. O comando `openssl pkey` é usado para visualizar a chave pública recebida da parte remota.

    openssl pkey -pubin -in remotepublickey.pem -text -noout

O exemplo acima produzirá algo semelhante a:

    PKCS#3 DH Public-Key: (2048 bit)
        public-key:
            67:e5:e5:fa:e0:7b:0f:96:2c:dc:96:44:5f:50:02:
            9e:8d:c2:6c:04:68:b0:d1:1d:75:66:fc:63:f5:e3:
            42:30:b8:96:c1:45:cc:08:60:b4:21:3b:dd:ee:66:
            88:db:77:d9:1e:11:89:d4:5c:f2:7a:f2:f1:fe:1c:
            77:9d:6f:13:b8:b2:56:00:ef:cb:3b:60:79:74:02:
            98:f5:f9:8e:3e:b5:62:08:de:ca:8c:c3:40:4a:80:
            79:d5:43:06:17:a8:19:56:af:cc:95:5e:e2:32:2d:
            d2:14:7b:76:5a:9a:f1:3c:76:76:35:cc:7b:c1:a5:
            f4:39:e5:b6:ca:71:3f:7c:3f:97:e5:ab:86:c1:cd:
            0e:e6:ee:04:c9:e6:2d:80:7e:59:c0:49:eb:b6:64:
            4f:a8:f9:bb:a3:87:b3:3d:76:01:9e:2b:16:94:a4:
            37:30:fb:35:e2:63:be:23:90:b9:ef:3f:46:46:04:
            94:8f:60:79:7a:51:55:d6:1a:1d:f5:d9:7f:4a:3e:
            aa:ac:b0:d0:82:cc:c2:e0:94:e0:54:c1:17:83:0b:
            74:08:4d:5a:79:ae:ff:7f:1c:04:ab:23:39:4a:ae:
            87:83:55:43:ab:7a:7c:04:9d:20:80:bb:af:5f:16:
            a3:e3:20:b9:21:47:8c:f8:7f:a8:60:80:9e:61:77:
            36
     [...abreviado...]

Esta chave pública é usada como parâmetro em openssl_dh_compute_key() para computar o segredo compartilhado.

    <?php
    $remote_public_key = '67e5e5fae07b0f962cdc96445f50029e8dc26c0468b0d11d7566fc63f5e34230b896c145cc0860b4213bddee6688db77d91e1189d45cf27af2f1fe1c779d6f13b8b25600efcb3b6079740298f5f98e3eb56208deca8cc3404a8079d5430617a81956afcc955ee2322dd2147b765a9af13c767635cc7bc1a5f439e5b6ca713f7c3f97e5ab86c1cd0ee6ee04c9e62d807e59c049ebb6644fa8f9bba387b33d76019e2b1694a43730fb35e263be2390b9ef3f464604948f60797a5155d61a1df5d97f4a3eaaacb0d082ccc2e094e054c117830b74084d5a79aeff7f1c04ab23394aae87835543ab7a7c049d2080bbaf5f16a3e320b921478cf87fa860809e617736';

    $local_priv_key = openssl_pkey_get_private('file://privatekey.pem');

    $shared_secret = openssl_dh_compute_key(hex2bin($remote_public_key), $local_priv_key);
    echo bin2hex($shared_secret)."\n";
    ?>

Exemplo #2 Gerando um par de chaves DH pública/privada no PHP

Primeiro, um número primo DH é gerado

    openssl dhparam -out dhparam.pem 2048
    openssl dh -in dhparam.pem -noout  -text

O exemplo acima produzirá algo semelhante a:

    PKCS#3 DH Parameters: (2048 bit)
            prime:
                00:a3:25:1e:73:3f:44:b9:2b:ee:f4:9d:9f:37:6a:
                4b:fd:1d:bd:f4:af:da:c8:10:77:59:41:c6:5f:73:
                d2:88:29:39:cd:1c:5f:c3:9f:0f:22:d2:9c:20:c1:
                e4:c0:18:03:b8:b6:d8:da:ad:3b:39:a6:da:8e:fe:
                12:30:e9:03:5d:22:ba:ef:18:d2:7b:69:f9:5b:cb:
                78:c6:0c:8c:6b:f2:49:92:c2:49:e0:45:77:72:b3:
                55:36:30:f2:40:17:89:18:50:03:fa:2d:54:7a:7f:
                34:4c:73:32:b6:88:14:51:14:be:80:57:95:e6:a3:
                f6:51:ff:17:47:4f:15:d6:0e:6c:47:53:72:2c:2a:
                4c:21:cb:7d:f3:49:97:c9:47:5e:40:33:7b:99:52:
                7e:7a:f3:52:27:80:de:1b:26:6b:40:bb:14:11:0b:
                fb:e6:d8:2f:cf:a0:06:2f:96:b9:1c:0b:b4:cb:d3:
                a6:62:9c:48:67:f6:81:f2:c6:ff:45:03:0a:9d:67:
                9d:ce:27:d9:6b:48:5d:ca:fb:c2:5d:84:9b:8b:cb:
                40:c7:a4:0c:8a:6e:f4:ab:ba:b6:10:c3:b8:25:4d:
                cf:60:96:f4:db:e8:00:1c:58:47:7a:fb:51:86:d1:
                22:d7:4e:94:31:7a:d5:da:3d:53:de:da:bb:64:8d:
                62:6b
            generator: 2 (0x2)

Valores do número primo e do gerador são passados como 'p' e 'g' à função openssl_pkey_new()

    <?php
    $configargs = array();
    $configargs['p'] = hex2bin('00a3251e733f44b92beef49d9f376a4bfd1dbdf4afdac810775941c65f73d2882939cd1c5fc39f0f22d29c20c1e4c01803b8b6d8daad3b39a6da8efe1230e9035d22baef18d27b69f95bcb78c60c8c6bf24992c249e0457772b3553630f2401789185003fa2d547a7f344c7332b688145114be805795e6a3f651ff17474f15d60e6c4753722c2a4c21cb7df34997c9475e40337b99527e7af3522780de1b266b40bb14110bfbe6d82fcfa0062f96b91c0bb4cbd3a6629c4867f681f2c6ff45030a9d679dce27d96b485dcafbc25d849b8bcb40c7a40c8a6ef4abbab610c3b8254dcf6096f4dbe8001c58477afb5186d122d74e94317ad5da3d53dedabb648d626b');
    $configargs['g'] = hex2bin('02');
    $private_key = openssl_pkey_new(array('dh' => $configargs));
    openssl_pkey_export_to_file($private_key,'privatekey.pem',$passphrase='y0urp@s5phr@se');

    $details = openssl_pkey_get_details($private_key);
    $local_pub_key = $details['dh']['pub_key'];
    echo bin2hex($local_pub_key)."\n"; // a chave pública pode ser passada à parte remota

    $details = openssl_pkey_get_details(openssl_pkey_get_public("file://remotepublickey.pem"));
    $remote_public_key = $details['dh']['pub_key'];
    $shared_secret = openssl_dh_compute_key($remote_public_key, $private_key);
    echo bin2hex($shared_secret)."\n";
    ?>

### Veja Também

- openssl_pkey_new() - Gera uma nova chave privada
- openssl_pkey_get_details() - Retorna um array com os detalhes da chave
- openssl_pkey_get_private() - Obtém uma chave privada
- openssl_pkey_get_public() - Extrai a chave pública do certificado e prepara-a para uso

# openssl_digest

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_digest — Computa um resumo

### Descrição

function openssl_digest(string `$data`, string `$digest_algo`, bool `$binary` = `false`): string|false

Calcula um valor de hash de resumo para os dados fornecidos usando um determinado método e retorna uma string bruta ou codificada em binário hexadecimal.

### Parâmetros

`data`

  Os dados.

`digest_algo`

  O método de resumo a ser utilizado, por exemplo, "sha256", consulte openssl_get_md_methods() para uma lista de métodos de resumo disponíveis.

`binary`

  Se este parâmetro for igual a `true`, os dados serão retornados brutos, caso contrário o valor de retorno será codificado em binário hexadecimal.

### Valor Retornado

Retorna o valor de hash em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Emite um erro de nível `E_WARNING` se um algoritmo de assinatura desconhecido for passado no parâmetro `digest_algo`.

### Veja Também

- openssl_get_md_methods() - Obtém métodos de resumo disponíveis

# openssl_encrypt

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_encrypt — Criptografa dados

### Descrição

function openssl_encrypt(
#[\SensitiveParameter]string `$data`,
string `$cipher_algo`,
#[\SensitiveParameter]string `$passphrase`,
int `$options` = 0,
string `$iv` = "",
string `&$tag` = `null`,
string `$aad` = "",
int `$tag_length` = 16
): string|false

Criptografa dados fornecidos com determinado método e senha, retorna uma string bruta ou codificada em base64.

### Parâmetros

`data`

  Os dados da mensagem de texto simples a serem criptografados.

`cipher_algo`

  O método de criptografia. Para obter uma lista de métodos de criptografia disponíveis, use openssl_get_cipher_methods().

`passphrase`

  A senha. Se a senha for menor que o esperado, ela será preenchida silenciosamente com caracteres `NUL`; se a senha for maior que o esperado, ela será truncada silenciosamente.

  Cuidado

  Não há função de derivação de chave usada para `passphrase` como o próprio nome pode sugerir. A única operação utilizada é o preenchimento com caracteres `NUL` ou truncamento se o comprimento for diferente do esperado.

`options`

  `options` é uma disjunção binária das opções `OPENSSL_RAW_DATA` e `OPENSSL_ZERO_PADDING` ou `OPENSSL_DONT_ZERO_PAD_KEY`.

`iv`

  Um Vetor de Inicialização não-`null`. Se for menor que o esperado, será preenchido com caracteres `NUL` e um alerta será emitido; se for maior que o o esperado, será truncado e um alerta será emitido.

`tag`

  A etiqueta de autenticação passada por referência ao usar o modo de criptografia AEAD (GCM ou CCM).

`aad`

  Dados autenticados adicionais.

`tag_length`

  O comprimento da etiqueta de autenticação (parâmetro `tag`). Seu valor pode estar entre 4 e 16 para o modo GCM.

### Valor Retornado

Retorna a string criptografada em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Emite um erro de nível `E_WARNING` se um algoritmo de criptografia desconhecido for passado através do parâmetro `cipher_algo`.

Emite um erro de nível `E_WARNING` se um valor vazio for passado através do parâmetro `iv`.

### Registro de Alterações

Versão | Descrição
--- | ---
7.1.0 | Os parâmetros `tag`, `aad` e `tag_length` foram adicionados.

### Exemplos

Exemplo #1 Exemplo de criptografia autenticada AES no modo GCM para PHP 7.1+

    <?php
    // $key deve ter sido gerada previamente de forma criptograficamente segura, como openssl_random_pseudo_bytes
    $plaintext = "mensagem a ser criptografada";
    $cipher = "aes-128-gcm";
    if (in_array($cipher, openssl_get_cipher_methods()))
    {
        $ivlen = openssl_cipher_iv_length($cipher);
        $iv = openssl_random_pseudo_bytes($ivlen);
        $ciphertext = openssl_encrypt($plaintext, $cipher, $key, $options=0, $iv, $tag);
        // armazena $cipher, $iv e $tag para descriptografia posterior
        $original_plaintext = openssl_decrypt($ciphertext, $cipher, $key, $options=0, $iv, $tag);
        echo $original_plaintext."\n";
    }
    ?>

Exemplo #2 Exemplo de criptografia autenticada AES antes do PHP 7.1

    <?php
    // $key gerada anteriormente com segurança, ou seja: openssl_random_pseudo_bytes
    $plaintext = "mensagem a ser criptografada";
    $ivlen = openssl_cipher_iv_length($cipher="AES-128-CBC");
    $iv = openssl_random_pseudo_bytes($ivlen);
    $ciphertext_raw = openssl_encrypt($plaintext, $cipher, $key, $options=OPENSSL_RAW_DATA, $iv);
    $hmac = hash_hmac('sha256', $ciphertext_raw, $key, $as_binary=true);
    $ciphertext = base64_encode( $iv.$hmac.$ciphertext_raw );

    // descriptografa mais tarde....
    $c = base64_decode($ciphertext);
    $ivlen = openssl_cipher_iv_length($cipher="AES-128-CBC");
    $iv = substr($c, 0, $ivlen);
    $hmac = substr($c, $ivlen, $sha2len=32);
    $ciphertext_raw = substr($c, $ivlen+$sha2len);
    $original_plaintext = openssl_decrypt($ciphertext_raw, $cipher, $key, $options=OPENSSL_RAW_DATA, $iv);
    $calcmac = hash_hmac('sha256', $ciphertext_raw, $key, $as_binary=true);
    if (hash_equals($hmac, $calcmac))// comparação segura contra ataque de temporização
    {
        echo $original_plaintext."\n";
    }
    ?>

### Veja Também

- openssl_decrypt() - Descritografa dados

# openssl_error_string

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_error_string — Retorna mensagem de erro do openSSL

### Descrição

function openssl_error_string(): string|false

openssl_error_string() retorna o último erro da biblioteca openSSL. As mensagens de erro são enfileiradas, portanto esta função deve ser chamadas múltiplas vezes para coletar toda a informação. O último erro será o mais recente.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string com a mensagem de erro ou `false` se não houver mais mensagem de erro para retornar.

### Exemplos

Exemplo #1 Exemplo de openssl_error_string()

    <?php
    // vamos supor que uma função openssl acabou de ser chamada e falhou
    while ($msg = openssl_error_string())
        echo $msg . "<br />\n";
    ?>

# openssl_free_key

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_free_key — Libera recurso de chave

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.0.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
function openssl_free_key(OpenSSLAsymmetricKey `$key`): void

openssl_free_key() libera da memória a chave associada ao parâmetro `key`.

### Parâmetros

`key`

### Valor Retornado

Nenhum valor é retornado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Esta função foi descontinuada e não tem mais nenhum efeito.
8.0.0 | `key` agora aceita um OpenSSLAsymmetricKey; anteriormente, um resource do tipo `OpenSSL key` era aceito.

# openssl_get_cert_locations

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_get_cert_locations — Recupera os locais de certificados disponíveis

### Descrição

function openssl_get_cert_locations(): array

openssl_get_cert_locations() retorna um array com informações sobre os locais de certificados disponíveis que serão pesquisados ​​por certificados SSL.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array com os locais de certificados disponíveis.

### Exemplos

Exemplo #1 Exemplo de openssl_get_cert_locations()

    <?php
    var_dump(openssl_get_cert_locations());
    ?>

O exemplo acima produzirá:

    array(8) {
      ["default_cert_file"]=>
      string(21) "/usr/lib/ssl/cert.pem"
      ["default_cert_file_env"]=>
      string(13) "SSL_CERT_FILE"
      ["default_cert_dir"]=>
      string(18) "/usr/lib/ssl/certs"
      ["default_cert_dir_env"]=>
      string(12) "SSL_CERT_DIR"
      ["default_private_dir"]=>
      string(20) "/usr/lib/ssl/private"
      ["default_default_cert_area"]=>
      string(12) "/usr/lib/ssl"
      ["ini_cafile"]=>
      string(0) ""
      ["ini_capath"]=>
      string(0) ""
    }

# openssl_get_cipher_methods

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_get_cipher_methods — Obtém métodos de criptografia disponíveis

### Descrição

function openssl_get_cipher_methods(bool `$aliases` = `false`): array

Obtém uma lista de métodos de criptografia disponíveis.

### Parâmetros

`aliases`

  Defina como `true` se os sinônimos de métodos de criptografia devem ser incluídos no array retornado.

### Valor Retornado

Um array de métodos de cifra disponíveis. Observe que antes do OpenSSL 1.1.1, os métodos de criptografia eram retornados em letras maiúsculas e minúsculas; a partir do OpenSSL 1.1.1, apenas as variantes em minúsculas são retornadas.

### Exemplos

Exemplo #1 Exemplo de openssl_get_cipher_methods()

Mostra a aparência dos métodos de criptografia disponíveis e também quais sinônimos podem estar disponíveis.

    <?php
    $ciphers             = openssl_get_cipher_methods();
    $ciphers_and_aliases = openssl_get_cipher_methods(true);
    $cipher_aliases      = array_diff($ciphers_and_aliases, $ciphers);

    // O modo ECB deve ser evitado
    $ciphers = array_filter( $ciphers, function($n) { return stripos($n,"ecb")===FALSE; } );

    // Pelo menos já em agosto de 2016, Openssl declarou os seguintes como fracos: baseados em RC2, RC4, DES, 3DES e MD5
    $ciphers = array_filter( $ciphers, function($c) { return stripos($c,"des")===FALSE; } );
    $ciphers = array_filter( $ciphers, function($c) { return stripos($c,"rc2")===FALSE; } );
    $ciphers = array_filter( $ciphers, function($c) { return stripos($c,"rc4")===FALSE; } );
    $ciphers = array_filter( $ciphers, function($c) { return stripos($c,"md5")===FALSE; } );
    $cipher_aliases = array_filter($cipher_aliases,function($c) { return stripos($c,"des")===FALSE; } );
    $cipher_aliases = array_filter($cipher_aliases,function($c) { return stripos($c,"rc2")===FALSE; } );

    print_r($ciphers);
    print_r($cipher_aliases);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => aes-128-cbc
        [1] => aes-128-cbc-hmac-sha1
        [2] => aes-128-cbc-hmac-sha256
        [3] => aes-128-ccm
        [4] => aes-128-cfb
        [5] => aes-128-cfb1
        [6] => aes-128-cfb8
        [7] => aes-128-ctr
        [9] => aes-128-gcm
        [10] => aes-128-ocb
        [11] => aes-128-ofb
        [12] => aes-128-xts
        [13] => aes-192-cbc
        [14] => aes-192-ccm
        [15] => aes-192-cfb
        [16] => aes-192-cfb1
        [17] => aes-192-cfb8
        [18] => aes-192-ctr
        [20] => aes-192-gcm
        [21] => aes-192-ocb
        [22] => aes-192-ofb
        [23] => aes-256-cbc
        [24] => aes-256-cbc-hmac-sha1
        [25] => aes-256-cbc-hmac-sha256
        [26] => aes-256-ccm
        [27] => aes-256-cfb
        [28] => aes-256-cfb1
        [29] => aes-256-cfb8
        [30] => aes-256-ctr
        [32] => aes-256-gcm
        [33] => aes-256-ocb
        [34] => aes-256-ofb
        [35] => aes-256-xts
        [36] => aria-128-cbc
        [37] => aria-128-ccm
        [38] => aria-128-cfb
        [39] => aria-128-cfb1
        [40] => aria-128-cfb8
        [41] => aria-128-ctr
        [43] => aria-128-gcm
        [44] => aria-128-ofb
        [45] => aria-192-cbc
        [46] => aria-192-ccm
        [47] => aria-192-cfb
        [48] => aria-192-cfb1
        [49] => aria-192-cfb8
        [50] => aria-192-ctr
        [52] => aria-192-gcm
        [53] => aria-192-ofb
        [54] => aria-256-cbc
        [55] => aria-256-ccm
        [56] => aria-256-cfb
        [57] => aria-256-cfb1
        [58] => aria-256-cfb8
        [59] => aria-256-ctr
        [61] => aria-256-gcm
        [62] => aria-256-ofb
        [63] => bf-cbc
        [64] => bf-cfb
        [66] => bf-ofb
        [67] => camellia-128-cbc
        [68] => camellia-128-cfb
        [69] => camellia-128-cfb1
        [70] => camellia-128-cfb8
        [71] => camellia-128-ctr
        [73] => camellia-128-ofb
        [74] => camellia-192-cbc
        [75] => camellia-192-cfb
        [76] => camellia-192-cfb1
        [77] => camellia-192-cfb8
        [78] => camellia-192-ctr
        [80] => camellia-192-ofb
        [81] => camellia-256-cbc
        [82] => camellia-256-cfb
        [83] => camellia-256-cfb1
        [84] => camellia-256-cfb8
        [85] => camellia-256-ctr
        [87] => camellia-256-ofb
        [88] => cast5-cbc
        [89] => cast5-cfb
        [91] => cast5-ofb
        [92] => chacha20
        [93] => chacha20-poly1305
        [111] => id-aes128-CCM
        [112] => id-aes128-GCM
        [113] => id-aes128-wrap
        [114] => id-aes128-wrap-pad
        [115] => id-aes192-CCM
        [116] => id-aes192-GCM
        [117] => id-aes192-wrap
        [118] => id-aes192-wrap-pad
        [119] => id-aes256-CCM
        [120] => id-aes256-GCM
        [121] => id-aes256-wrap
        [122] => id-aes256-wrap-pad
        [124] => idea-cbc
        [125] => idea-cfb
        [127] => idea-ofb
        [137] => seed-cbc
        [138] => seed-cfb
        [140] => seed-ofb
        [141] => sm4-cbc
        [142] => sm4-cfb
        [143] => sm4-ctr
        [145] => sm4-ofb
    )
    Array
    (
        [36] => aes128
        [37] => aes128-wrap
        [38] => aes192
        [39] => aes192-wrap
        [40] => aes256
        [41] => aes256-wrap
        [69] => aria128
        [70] => aria192
        [71] => aria256
        [72] => bf
        [77] => blowfish
        [99] => camellia128
        [100] => camellia192
        [101] => camellia256
        [102] => cast
        [103] => cast-cbc
        [146] => idea
        [164] => seed
        [169] => sm4
    )

### Veja Também

- openssl_get_md_methods() - Obtém métodos de resumo disponíveis

# openssl_get_curve_names

(PHP 7 >= 7.1.0, PHP 8)

openssl_get_curve_names — Obtém lista de nomes de curvas disponíveis para ECC

### Descrição

function openssl_get_curve_names(): array|false

Obtém a lista de nomes de curvas disponíveis para uso em ECC (criptografia de curva elíptica) para operações de chave pública/privada. As duas curvas mais amplamente padronizadas/suportadas são prime256v1 (NIST P-256) e secp384r1 (NIST P-384).

Equivalências aproximadas de tamanhos de chave AES, RSA, DSA e ECC
Tamanho de chave simétrico AES (bits) | Tamanho de chave RSA e DSA (bits) | Tamanho da chave ECC (bits)
--- | --- | ---
80 | 1024 | 160
112 | 2048 | 224
128 | 3072 | 256
192 | 7680 | 384
256 | 15360 | 512

» O NIST recomenda o uso de curvas ECC com pelo menos 256 bits.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array de nomes de curvas disponíveis, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de openssl_get_curve_names()

    <?php
    $curve_names = openssl_get_curve_names();
    print_r($curve_names);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => secp112r1
        [1] => secp112r2
        [2] => secp128r1
        [3] => secp128r2
        [4] => secp160k1
        [5] => secp160r1
        [6] => secp160r2
        [7] => secp192k1
        [8] => secp224k1
        [9] => secp224r1
        [10] => secp256k1
        [11] => secp384r1
        [12] => secp521r1
        [13] => prime192v1
        [14] => prime192v2
        [15] => prime192v3
        [16] => prime239v1
        [17] => prime239v2
        [18] => prime239v3
        [19] => prime256v1
        [20] => sect113r1
        [21] => sect113r2
        [22] => sect131r1
        [23] => sect131r2
        [24] => sect163k1
        [25] => sect163r1
        [26] => sect163r2
        [27] => sect193r1
        [28] => sect193r2
        [29] => sect233k1
        [30] => sect233r1
        [31] => sect239k1
        [32] => sect283k1
        [33] => sect283r1
        [34] => sect409k1
        [35] => sect409r1
        [36] => sect571k1
        [37] => sect571r1
        [38] => c2pnb163v1
        [39] => c2pnb163v2
        [40] => c2pnb163v3
        [41] => c2pnb176v1
        [42] => c2tnb191v1
        [43] => c2tnb191v2
        [44] => c2tnb191v3
        [45] => c2pnb208w1
        [46] => c2tnb239v1
        [47] => c2tnb239v2
        [48] => c2tnb239v3
        [49] => c2pnb272w1
        [50] => c2pnb304w1
        [51] => c2tnb359v1
        [52] => c2pnb368w1
        [53] => c2tnb431r1
        [54] => wap-wsg-idm-ecid-wtls1
        [55] => wap-wsg-idm-ecid-wtls3
        [56] => wap-wsg-idm-ecid-wtls4
        [57] => wap-wsg-idm-ecid-wtls5
        [58] => wap-wsg-idm-ecid-wtls6
        [59] => wap-wsg-idm-ecid-wtls7
        [60] => wap-wsg-idm-ecid-wtls8
        [61] => wap-wsg-idm-ecid-wtls9
        [62] => wap-wsg-idm-ecid-wtls10
        [63] => wap-wsg-idm-ecid-wtls11
        [64] => wap-wsg-idm-ecid-wtls12
        [65] => Oakley-EC2N-3
        [66] => Oakley-EC2N-4
        [67] => brainpoolP160r1
        [68] => brainpoolP160t1
        [69] => brainpoolP192r1
        [70] => brainpoolP192t1
        [71] => brainpoolP224r1
        [72] => brainpoolP224t1
        [73] => brainpoolP256r1
        [74] => brainpoolP256t1
        [75] => brainpoolP320r1
        [76] => brainpoolP320t1
        [77] => brainpoolP384r1
        [78] => brainpoolP384t1
        [79] => brainpoolP512r1
        [80] => brainpoolP512t1
    )

# openssl_get_md_methods

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_get_md_methods — Obtém métodos de resumo disponíveis

### Descrição

function openssl_get_md_methods(bool `$aliases` = `false`): array

Obtém uma lista de métodos de resumo disponíveis.

### Parâmetros

`aliases`

  Defina como `true` se os sinônimos de métodos de resumo devem ser incluídos no array retornado.

### Valor Retornado

Um array de métodos de resumo disponíveis.

### Exemplos

Exemplo #1 Exemplo de openssl_get_md_methods()

Mostra a aparência dos métodos de resumo disponíveis e também quais sinônimos podem estar disponíveis.

    <?php
    $digests             = openssl_get_md_methods();
    $digests_and_aliases = openssl_get_md_methods(true);
    $digest_aliases      = array_diff($digests_and_aliases, $digests);

    print_r($digests);

    print_r($digest_aliases);

    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => DSA
        [1] => DSA-SHA
        [2] => MD2
        [3] => MD4
        [4] => MD5
        [5] => RIPEMD160
        [6] => SHA
        [7] => SHA1
        [8] => SHA224
        [9] => SHA256
        [10] => SHA384
        [11] => SHA512
        [12] => dsaEncryption
        [13] => dsaWithSHA
        [14] => ecdsa-with-SHA1
        [15] => md2
        [16] => md4
        [17] => md5
        [18] => ripemd160
        [19] => sha
        [20] => sha1
        [21] => sha224
        [22] => sha256
        [23] => sha384
        [24] => sha512
    )
    Array
    (
        [2] => DSA-SHA1
        [3] => DSA-SHA1-old
        [4] => DSS1
        [9] => RSA-MD2
        [10] => RSA-MD4
        [11] => RSA-MD5
        [12] => RSA-RIPEMD160
        [13] => RSA-SHA
        [14] => RSA-SHA1
        [15] => RSA-SHA1-2
        [16] => RSA-SHA224
        [17] => RSA-SHA256
        [18] => RSA-SHA384
        [19] => RSA-SHA512
        [28] => dsaWithSHA1
        [29] => dss1
        [32] => md2WithRSAEncryption
        [34] => md4WithRSAEncryption
        [36] => md5WithRSAEncryption
        [37] => ripemd
        [39] => ripemd160WithRSA
        [40] => rmd160
        [43] => sha1WithRSAEncryption
        [45] => sha224WithRSAEncryption
        [47] => sha256WithRSAEncryption
        [49] => sha384WithRSAEncryption
        [51] => sha512WithRSAEncryption
        [52] => shaWithRSAEncryption
        [53] => ssl2-md5
        [54] => ssl3-md5
        [55] => ssl3-sha1
    )

### Veja Também

- openssl_digest() - Computa um resumo
- openssl_get_cipher_methods() - Obtém métodos de criptografia disponíveis

# openssl_get_privatekey

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_get_privatekey — Sinônimo de openssl_pkey_get_private()

### Descrição

Esta função é um apelido para: openssl_pkey_get_private().

# openssl_get_publickey

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_get_publickey — Sinônimo de openssl_pkey_get_public()

### Descrição

Esta função é um apelido para: openssl_pkey_get_public().

# openssl_open

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_open — Abre dados lacrados

### Descrição

function openssl_open(
string `$data`,
#[\SensitiveParameter]string `&$output`,
string `$encrypted_key`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
string `$cipher_algo`,
?string `$iv` = `null`
): bool

openssl_open() abre (descriptografa) os dados do parâmetro `data` usando uma chave de envelope que é descriptografada da chave `encrypted_key` usando a chave privada de `private_key`. A descriptografia é feita usando o método `cipher_algo` e o vetor de inicialização `iv`. O IV é necessário apenas se o método de criptografia exigir. A função preenche a variável em `output` com os dados descriptografados. A chave do envelope normalmente é gerada quando os dados são lacrados por meio de uma chave pública associada à chave privada. Consulte openssl_seal() para obter mais informações.

### Parâmetros

`data`

  Os dados lacrados.

`output`

  Se a chamada for bem-sucedida, os dados abertos serão retornados neste parâmetro.

`encrypted_key`

  A chave simétrica criptografada que pode ser descriptografada usando `private_key`.

`private_key`

  A chave privada usada para descriptografar `encrypted_key`.

`cipher_algo`

  O método de criptografia usado para descriptografar `data`.

  Cuidado

  O valor padrão para versões do PHP anteriores a 8.0 é (`'RC4'`) que é considerado inseguro. É altamente recomendável especificar explicitamente um método de criptografia seguro.

`iv`

  O vetor de inicialização usado para descriptografia de `data`. É necessário se o método de criptografia exigi-lo. Isso pode ser descoberto chamando openssl_cipher_iv_length() com `cipher_algo`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `private_key` agora aceita uma instância de OpenSSLAsymmetricKey ou de OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL key` ou `OpenSSL X.509 CSR` era aceito.
8.0.0 | `cipher_algo` não é mais um parâmetro opcional.

### Exemplos

Exemplo #1 Exemplo de openssl_open()

    <?php

    // Presume-se que $sealed, $env_key e $iv contenham os dados selados,
    // a chave de envelope e IV. Tudo recebido de quem criptografou.

    // Busca a chave privada do arquivo localizado em private_key.pem
    $pkey = openssl_get_privatekey("file://private_key.pem");

    // Descriptografa os dados e os armazena em $open
    if (openssl_open($sealed, $open, $env_key, $pkey, 'AES256', $iv)) {
        echo "Aqui estão os dados abertos: ", $open;
    } else {
        echo "Falha ao abrir dados";
    }

    ?>

### Veja Também

- openssl_seal() - Sela (criptografa) dados

# openssl_password_hash

(PHP 8 >= 8.4.0)

openssl_password_hash — Cria um hash de senha usando a implementação Argon2 do OpenSSL

### Descrição

function openssl_password_hash(string `$algo`, string `$password`, array `$options` = []): string

Cria um hash de senha usando a implementação Argon2 do OpenSSL. Esta é uma alternativa à função password_hash() que usa o OpenSSL como backend, que pode oferecer aceleração de hardware em algumas plataformas.

Esta função só está disponível quando o PHP é compilado com suporte a OpenSSL que inclui Argon2 (`HAVE_OPENSSL_ARGON2`).

### Parâmetros

`algo`

  O algoritmo de hash de senha. Valores suportados: `"argon2id"` e `"argon2i"`.

`password`

  A senha do usuário.

`options`

  Um array associativo de opções. Chaves suportadas:

  - `memory_cost` - Memória máxima (em KiB) que pode ser usada para computar o hash
  - `time_cost` - Tempo máximo que pode ser usado para computar o hash
  - `threads` - Número de threads a ser usado para computar o hash

### Valor Retornado

Retorna o hash de senha como uma string.

### Erros/Exceções

Lança um ValueError se `algo` não for um dos valores suportados (`"argon2i"` ou `"argon2id"`).

Lança um Error se a operação de hash falhar por um motivo desconhecido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Função adicionada.

### Exemplos

Exemplo #1 Exemplo de openssl_password_hash()

    <?php
    $hash = openssl_password_hash('argon2id', 'my-secret-password');
    echo $hash;
    ?>

O exemplo acima produzirá algo semelhante a:

    $argon2id$v=19$m=65536,t=4,p=1$c29tZXNhbHR2YWx1ZQ$valordehash...

Exemplo #2 openssl_password_hash() com opções personalizadas

    <?php
    $hash = openssl_password_hash('argon2id', 'my-secret-password', [
        'memory_cost' => 65536,
        'time_cost'   => 4,
        'threads'     => 1,
    ]);
    ?>

### Veja Também

- openssl_password_verify() - Verifica uma senha em relação a um hash usando a implementação Argon2 do OpenSSL
- password_hash() - Cria um hash de senha

# openssl_password_verify

(PHP 8 >= 8.4.0)

openssl_password_verify — Verifica uma senha em relação a um hash usando a implementação Argon2 do OpenSSL

### Descrição

function openssl_password_verify(string `$algo`, string `$password`, string `$hash`): bool

Verifica que uma senha corresponde a um hash criado por openssl_password_hash().

Esta função só está disponível quando o PHP é compilado com suporte a OpenSSL que inclui Argon2 (`HAVE_OPENSSL_ARGON2`).

### Parâmetros

`algo`

  O algoritmo de hash de senha. Valores suportados: `"argon2id"` e `"argon2i"`.

`password`

  A senha do usuário.

`hash`

  Um hash criado por openssl_password_hash().

### Valor Retornado

Retorna `true` se houver correspondência entre o hash e a senha ou `false` caso contrário.

### Erros/Exceções

Lança um ValueError se `algo` não for um dos valores suportados (`"argon2i"` ou `"argon2id"`).

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Função adicionada.

### Exemplos

Exemplo #1 Exemplo de openssl_password_verify()

    <?php
    $hash = openssl_password_hash('argon2id', 'my-secret-password');

    if (openssl_password_verify('argon2id', 'my-secret-password', $hash)) {
        echo 'Senha corresponde.';
    } else {
        echo 'Senha não corresponde.';
    }
    ?>

### Veja Também

- openssl_password_hash() - Cria um hash de senha usando a implementação Argon2 do OpenSSL
- password_verify() - Verifica se uma senha corresponde a um hash

# openssl_pbkdf2

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

openssl_pbkdf2 — Gera uma string PKCS5 v2 PBKDF2

### Descrição

function openssl_pbkdf2(
#[\SensitiveParameter]string `$password`,
string `$salt`,
int `$key_length`,
int `$iterations`,
string `$digest_algo` = "sha1"
): string|false

openssl_pbkdf2() calcula PBKDF2 (Função 2 de derivação de chave baseada em senha), uma função de derivação de chave definida em PKCS5 v2.

### Parâmetros

`password`

  Senha a partir da qual a chave derivada é gerada.

`salt`
  PBKDF2 recomenda um sal criptográfico de pelo menos 128 bits (16 bytes).
`key_length`

  Comprimento da chave de saída desejada.

`iterations`

  O número de iterações desejadas. » O NIST recomenda pelo menos 1.000. A partir de 2023, a OWASP recomenda 600.000 iterações para PBKDF2-HMAC-SHA256 e 210.000 para PBKDF2-HMAC-SHA512.

`digest_algo`

  Algoritmo opcional de hash ou de resumo de openssl_get_md_methods(). O padrão é SHA-1. Recomenda-se configurá-lo para SHA-256 ou SHA-512.

### Valor Retornado

Retorna string binária bruta ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de openssl_pbkdf2()

    <?php
    $password = 'password';
    $salt = openssl_random_pseudo_bytes(16);
    $keyLength = 20;
    $iterations = 600000;
    $generated_key = openssl_pbkdf2($password, $salt, $keyLength, $iterations, 'sha256');
    echo bin2hex($generated_key)."\n";
    echo base64_encode($generated_key)."\n";
    ?>

### Veja Também

- hash_pbkdf2() - Gera uma derivação de chave PBKDF2 de uma senha fornecida
- openssl_get_md_methods() - Obtém métodos de resumo disponíveis

# openssl_pkcs12_export

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

openssl_pkcs12_export — Exporta um arquivo de armazenamento de certificados compatível com PKCS#12 para uma variável

### Descrição

function openssl_pkcs12_export(
OpenSSLCertificate|string `$certificate`,
string `&$output`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
#[\SensitiveParameter]string `$passphrase`,
array `$options` = []
): bool

openssl_pkcs12_export() armazena o certificado informado no parâmetro `certificate` na string especificada em `output` em um formato PKCS#12.

### Parâmetros

`certificate`
  Consulte Parâmetros Chave/Certificado para obter uma lista de valores válidos.
`output`

  Em caso de sucesso, conterá o certificado PKCS#12.

`private_key`

  Componente da chave privada do certificado PKCS#12. Consulte os parâmetros de chave pública/privada para uma lista de valores válidos.

`passphrase`

  Senha de criptografia para desbloquear o certificado PKCS#12.

`options`

  Array opcional, outras chaves serão ignoradas.

  Chave | Descrição
  --- | ---
  `"extracerts"` | array de certificados extras ou um único certificado a ser incluído na string PKCS#12.
  `"friendly_name"` | string a ser usada para o certificado e chave fornecidos

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `certificate` agora aceita uma instância de OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL X.509 CSR` era aceito.
8.0.0 | `private_key` agora aceita uma instância de OpenSSLAsymmetricKey ou de OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL key` ou `OpenSSL X.509` era aceito.

# openssl_pkcs12_export_to_file

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

openssl_pkcs12_export_to_file — Exporta um arquivo de armazenamento de certificados compatível com PKCS#12

### Descrição

function openssl_pkcs12_export_to_file(
OpenSSLCertificate|string `$certificate`,
string `$output_filename`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
#[\SensitiveParameter]string `$passphrase`,
array `$options` = []
): bool

openssl_pkcs12_export_to_file() armazena o certificado informado no parâmetro `certificate` em um arquivo nomeado por `output_filename` em um formato de arquivo PKCS#12.

### Parâmetros

`certificate`
  Consulte Parâmetros Chave/Certificado para obter uma lista de valores válidos.
`output_filename`

  Caminho para o arquivo de saída.

`private_key`

  Componente de chave privada do arquivo PKCS#12. Consulte Parâmetros de chave pública/privada para obter uma lista de valores válidos.

`passphrase`

  Senha de criptografia para desbloquear o arquivo PKCS#12.

`options`

  Array opcional, outras chaves serão ignoradas.

  Chave | Descrição
  --- | ---
  `"extracerts"` | array de certificados extras ou um único certificado a ser incluído no arquivo PKCS#12.
  `"friendly_name"` | string a ser usada para o certificado e chave fornecidos

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `certificate` agora aceita uma instância de OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL X.509 CSR` era aceito.
8.0.0 | `private_key` agora aceita uma instância de OpenSSLAsymmetricKey ou de OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL key` ou `OpenSSL X.509` era aceito.

# openssl_pkcs12_read

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

openssl_pkcs12_read — Analisa um armazenamento de certificados PKCS#12 em um array

### Descrição

function openssl_pkcs12_read(string `$pkcs12`, array `&$certificates`, #[\SensitiveParameter]string `$passphrase`): bool

openssl_pkcs12_read() analisa o armazenamento de certificado PKCS#12 informado em `pkcs12` e insere o resultado em um array nomeado por `certificates`.

### Parâmetros

`pkcs12`

  O conteúdo do armazenamento de certificado, e não o nome de um arquivo.

`certificates`

  Em caso de sucesso, esta variável conterá o array com os dados do armazenamento de certificado.

`passphrase`

  Senha de criptografia para desbloquear o certificado PKCS#12.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de openssl_pkcs12_read()

    <?php
    if (!$cert_store = file_get_contents("/certs/file.p12")) {
        echo "Erro: não é possível ler o arquivo do certificado\n";
        exit;
    }

    if (openssl_pkcs12_read($cert_store, $cert_info, "minha_senha_secreta")) {
        echo "Informação do certificado\n";
        print_r($cert_info);
    } else {
        echo "Erro: não é possível ler o armazenamento de certificados.\n";
        exit;
    }
    ?>

# openssl_pkcs7_decrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_decrypt — Descriptografa uma mensagem criptografada S/MIME

### Descrição

function openssl_pkcs7_decrypt(
string `$input_filename`,
string `$output_filename`,
#[\SensitiveParameter]OpenSSLCertificate|string `$certificate`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string|null `$private_key` = `null`
): bool

Descriptografa a mensagem criptografada S/MIME contida no arquivo especificado por `input_filename` usando o certificado informado em `certificate` e sua chave privada associada especificada por `private_key`.

### Parâmetros

`input_filename`

`output_filename`

  A mensagem descriptografada é gravada no arquivo especificado por `output_filename`.

`certificate`

`private_key`

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `private_key` agora aceita uma instância de OpenSSLAsymmetricKey ou de OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL key` ou `OpenSSL X.509 CSR` era aceito.

### Exemplos

Exemplo #1 Exemplo de openssl_pkcs7_decrypt()

    <?php
    // Presume-se que $cert e $key contenham o seu certificado pessoal e par de
    // chaves privadas e que você seja o destinatário de uma mensagem S/MIME
    $infilename = "encrypted.msg";  // este arquivo contém sua mensagem criptografada
    $outfilename = "decrypted.msg"; // certifique-se de que você pode gravar neste arquivo

    if (openssl_pkcs7_decrypt($infilename, $outfilename, $cert, $key)) {
        echo "descriptografado!";
    } else {
        echo "falha ao descriptografar!";
    }
    ?>

# openssl_pkcs7_encrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_encrypt — Criptografa uma mensagem S/MIME

### Descrição

function openssl_pkcs7_encrypt(
string `$input_filename`,
string `$output_filename`,
OpenSSLCertificate|array|string `$certificate`,
?array `$headers`,
int `$flags` = 0,
int `$cipher_algo` = `OPENSSL_CIPHER_AES_128_CBC`
): bool

openssl_pkcs7_encrypt() pega o conteúdo do arquivo chamado `input_filename` e o criptografa usando uma cifra RC2 de 40 bits para que só possa ser lido pelos destinatários pretendidos especificados pelo certificado especificado em `certificate`.

### Parâmetros

`input_filename`

`output_filename`

`certificate`

  Um certificado X.509 único ou um array de certificados X.509.

`headers`

  `headers` é um array de cabeçalhos que serão anexados aos dados após serem criptografados.

  `headers` pode ser um array associativo codificado pelo nome do cabeçalho ou um array indexado, onde cada elemento contém uma única linha de cabeçalho.

`flags`

  `flags` pode ser usado ​​para especificar opções que afetam o processo de codificação - veja constantes PKCS7.

`cipher_algo`

  Uma das constantes de método de criptografia.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O algoritmo de criptografia padrão (`cipher_algo`) agora é AES-128-CBC (`OPENSSL_CIPHER_AES_128_CBC`). Anteriormente, PKCS7/CMS era usado (`OPENSSL_CIPHER_RC2_40`).
8.0.0 | `certificate` agora aceita uma instância de OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL X.509 CSR` era aceito.

### Exemplos

Exemplo #1 Exemplo de openssl_pkcs7_encrypt()

    <?php
    // A mensagem que se deseja criptografar e enviar ao agente
    // secreto em campo, conhecido como Falcão Noturno. O certificado
    // dele fica no arquivo falcão_noturno.pem.
    $data = <<<EOD
    Falcão Noturno,

    Segredo absoluto, apenas para seus cuidados!

    O inimigo se aproxima! Encontre-me no Café às 8:30 da manhã
    para coletar seu passaporte falsificado!

    QG
    EOD;

    // carrega a chave
    $key = file_get_contents("falcão_noturno.pem");

    // grava mensagem no arquivo
    $fp = fopen("msg.txt", "w");
    fwrite($fp, $data);
    fclose($fp);

    // criptografa a mensagem
    if (openssl_pkcs7_encrypt("msg.txt", "crip.txt", $key,
        array("To" => "falcao_noturno@example.com", // sintaxe de chaves
              "From: QG <qg@example.com>", // sintaxe de índice
              "Subject" => "Ultra secreto"))) {
        // mensagem criptografada - enviar!
        exec(ini_get("sendmail_path") . " < crip.txt");
    }
    ?>

# openssl_pkcs7_read

(PHP 7 >= 7.2.0, PHP 8)

openssl_pkcs7_read — Exporta o arquivo PKCS7 para um array de certificados PEM

### Descrição

function openssl_pkcs7_read(string `$data`, array `&$certificates`): bool

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`data`

  A sequência de dados a ser analisada (formato p7b).

`certificates`

  O array de certificados PEM dos dados de entrada p7b.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Obtendo um array PEM de um arquivo P7B

    <?php

    $file = 'certs.p7b';

    $f = file_get_contents($file);
    $p7 = array();
    $r = openssl_pkcs7_read($f, $p7);

    if ($r === false) {
        printf("ERRO: %s não é um arquivo p7b válido".PHP_EOL, $file);
            for($e = openssl_error_string(), $i = 0; $e; $e = openssl_error_string(), $i++)
                printf("SSL l%d: %s".PHP_EOL, $i, $e);
        exit(1);
    }

    print_r($p7);
    ?>

### Veja Também

- openssl_csr_sign() - Assina um CSR com outro certificado (ou ele mesmo) e gera um certificado

# openssl_pkcs7_sign

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_sign — Assina uma mensagem S/MIME

### Descrição

function openssl_pkcs7_sign(
string `$input_filename`,
string `$output_filename`,
OpenSSLCertificate|string `$certificate`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
?array `$headers`,
int `$flags` = `PKCS7_DETACHED`,
?string `$untrusted_certificates_filename` = `null`
): bool

openssl_pkcs7_sign() pega o conteúdo do arquivo chamado `input_filename` e o assina usando o certificado informado em `certificate` e sua chave privada correspondente especificada por `private_key`.

### Parâmetros

`input_filename`

  O arquivo de entrada a ser assinado digitalmente.

`output_filename`

  O arquivo no qual a assinatura digital será gravada.

`certificate`

  O certificado X.509 usado para assinar digitalmente `input_filename`. Consulte Parâmetros de chave/certificado para obter uma lista de valores válidos.

`private_key`

  `private_key` é a chave privada correspondente ao `certificate`. Consulte Parâmetros de chave pública/privada para obter uma lista de valores válidos.

`headers`

  `headers` é um array de cabeçalhos que serão anexados aos dados após serem assinados (veja openssl_pkcs7_encrypt() para mais informações sobre o formato deste parâmetro).

`flags`

  `flags` são opções que podem ser usadas para alterar a saída - veja as constantes PKCS7.

`untrusted_certificates_filename`

  `untrusted_certificates_filename` especifica o nome de um arquivo contendo vários certificados extras para incluir na assinatura que pode, por exemplo, ser usado para ajudar o destinatário a verificar o certificado que você usou.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `certificate` agora aceita uma instância de OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL X.509 CSR` era aceito.
8.0.0 | `private_key` agora aceita uma instância de OpenSSLAsymmetricKey ou de OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL key` ou `OpenSSL X.509 CSR` era aceito.

### Exemplos

Exemplo #1 Exemplo de openssl_pkcs7_sign()

    <?php
    // a mensagem que se deseja assinar para que o destinatário possa ter certeza de que
    // foi você quem a enviou
    $data = <<<EOD

    Você tem minha autorização para gastar R$ 10 mil em despesas de jantar.

    O Presidente
    EOD;
    // salva mensagem em arquivo
    $fp = fopen("msg.txt", "w");
    fwrite($fp, $data);
    fclose($fp);
    // criptografa o arquivo
    if (openssl_pkcs7_sign("msg.txt", "assinado.txt", "file://meu_certificado.pem",
        array("file://meu_certificado.pem", "minha_senha"),
        array("To" => "fulanodetal@example.com", // sintaxe de chaves
              "From: HQ <presidente@example.com>", // sintaxe de índice
              "Subject" => "Ultra secreto")
        )) {
        // mensagem assinada - enviando!
        exec(ini_get("sendmail_path") . " < assinado.txt");
    }
    ?>

# openssl_pkcs7_verify

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_verify — Verifica a assinatura de uma mensagem assinada por S/MIME

### Descrição

function openssl_pkcs7_verify(
string `$input_filename`,
int `$flags`,
?string `$signers_certificates_filename` = `null`,
array `$ca_info` = [],
?string `$untrusted_certificates_filename` = `null`,
?string `$content` = `null`,
?string `$output_filename` = `null`
): bool|int

openssl_pkcs7_verify() lê a mensagem S/MIME contida no arquivo fornecido e examina a assinatura digital.

### Parâmetros

`input_filename`

  Caminho para a o arquivo com a mensagem.

`flags`

  `flags` contém opções que podem ser usadas ​​para afetar como a assinatura é verificada - consulte constantes PKCS7 para obter mais informações.

`signers_certificates_filename`

  Se o `signers_certificates_filename` for especificado, deverá ser uma string contendo o nome de um arquivo no qual os certificados das pessoas que assinaram as mensagens serão armazenados no formato PEM.

`ca_info`

  Se `ca_info` for especificado, ele deverá conter informações sobre os certificados de CA confiáveis ​​a serem usados ​​no processo de verificação - consulte verificação de certificado para obter mais informações informações sobre este parâmetro.

`untrusted_certificates_filename`

  Se `untrusted_certificates_filename` for especificado, é o nome de um arquivo que contém vários certificados para usar como CAs não confiáveis.

`content`

  Pode ser especificado um nome de arquivo com `content` que será preenchido com os dados verificados, mas sem as informações da assinatura.

`output_filename`

### Valor Retornado

Retorna `true` se a assinatura for verificada, `false` se não estiver correto (a mensagem foi adulterada ou o certificado de assinatura é inválido) ou -1 em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `signers_certificates_filename`, `untrusted_certificates_filename`, `content` e `output_filename` agora podem ser nulos.
7.2.0 | O parâmetro `output_filename` foi adicionado.

### Notas

> Nota: Como especificado na RFC 2045, as linhas não podem ser mais longas que 76 caracteres no arquivo informado em `input_filename`.

# openssl_pkey_derive

(PHP 7 >= 7.3.0, PHP 8)

openssl_pkey_derive — Calcula o segredo compartilhado para o valor público da chave DH ou ECDH remota e local

### Descrição

function openssl_pkey_derive(OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`, #[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`, int `$key_length` = 0): string|false

openssl_pkey_derive() pega um conjunto de `public_key` e `private_key` e deriva um segredo compartilhado, para chaves DH ou EC.

### Parâmetros

`public_key`

  `public_key` é a chave pública para a derivação. Consulte Parâmetros de chave pública/privada para obter uma lista de valores válidos.

`private_key`

  `private_key` é a chave privada para a derivação. Consulte Parâmetros de chave pública/privada para obter uma lista de valores válidos.

`key_length`

  Se não for zero, tentará definir o comprimento desejado do segredo derivado.

  Cuidado

  Este parâmetro foi descontinuado e não deve ser utilizado, pois não funciona conforme o esperado. Ele nunca retorna um segredo maior que o tamanho do primo. Se o comprimento desejado for menor que o tamanho do primo, ele truncará o comprimento apenas para chaves ECDH, mas falhará para chaves DH.

### Valor Retornado

O segredo derivado em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | O parâmetro `key_length` foi descontinuado.

### Exemplos

Exemplo #1 Exemplo de openssl_pkey_derive()

    <?php
    // Carrega a chave privada
    $priv = openssl_pkey_get_private("-----BEGIN PRIVATE KEY-----
    MIICJgIBADCCARcGCSqGSIb3DQEDATCCAQgCggEBAJLxRCaZ933uW+AXmabHFDDy
    upojBIRlbmQLJZfigDaSA1f9YOTsIv+WwVFTX/J1mtCyx9uBcz0Nt2kmVwxWuc2f
    VtCEMPsmLsVXX7xRUFLpyX1Y1IYGBVXQOoOvLWYQjpZgnx47Pkh1Ok1+smffztfC
    0DCNt4KorWrbsPcmqBejXHN79KvWFjZmXOksRiNu/Bn76RiqvofC4z8Ri3kHXQG2
    197JGZzzFXHadGC3xbkg8UxsNbYhVMKbm0iANfafUH7/hoS9UjAVQYtvwe7YNiW/
    HnyfVCrKwcc7sadd8Iphh+3lf5P1AhaQEAMytanrzq9RDXKBxuvpSJifRYasZYsC
    AQIEggEEAoIBAGwAYC2E81Y1U2Aox0U7u1+vBcbht/OO87tutMvc4NTLf6NLPHsW
    cPqBixs+3rSn4fADzAIvdLBmogjtiIZoB6qyHrllF/2xwTVGEeYaZIupQH3bMK2b
    6eUvnpuu4Ytksiz6VpXBBRMrIsj3frM+zUtnq8vKUr+TbjV2qyKR8l3eNDwzqz30
    dlbKh9kIhZafclHfRVfyp+fVSKPfgrRAcLUgAbsVjOjPeJ90xQ4DTMZ6vjiv6tHM
    hkSjJIcGhRtSBzVF/cT38GyCeTmiIA/dRz2d70lWrqDQCdp9ArijgnpjNKAAulSY
    CirnMsGZTDGmLOHg4xOZ5FEAzZI2sFNLlcw=
    -----END PRIVATE KEY-----
    ");

    // Carrega a chave pública
    $pub = openssl_pkey_get_public("-----BEGIN PUBLIC KEY-----
    MIICJDCCARcGCSqGSIb3DQEDATCCAQgCggEBAJLxRCaZ933uW+AXmabHFDDyupoj
    BIRlbmQLJZfigDaSA1f9YOTsIv+WwVFTX/J1mtCyx9uBcz0Nt2kmVwxWuc2fVtCE
    MPsmLsVXX7xRUFLpyX1Y1IYGBVXQOoOvLWYQjpZgnx47Pkh1Ok1+smffztfC0DCN
    t4KorWrbsPcmqBejXHN79KvWFjZmXOksRiNu/Bn76RiqvofC4z8Ri3kHXQG2197J
    GZzzFXHadGC3xbkg8UxsNbYhVMKbm0iANfafUH7/hoS9UjAVQYtvwe7YNiW/Hnyf
    VCrKwcc7sadd8Iphh+3lf5P1AhaQEAMytanrzq9RDXKBxuvpSJifRYasZYsCAQID
    ggEFAAKCAQAiCSBpxvGgsTorxAWtcAlSmzAJnJxFgSPef0g7OjhESytnc8G2QYmx
    ovMt5KVergcitztWh08hZQUdAYm4rI+zMlAFDdN8LWwBT/mGKSzRkWeprd8E7mvy
    ucqC1YXCMqmIwPySvLQUB/Dl8kgau7BLAnIJm8VP+MVrn8g9gghD0qRCgPgtEaDV
    vocfgnOU43rhKnIgO0cHOKtw2qybSFB8QuZrYugq4j8Bwkrzh6rdMMeyMl/ej5Aj
    c0wamOzuBDtXt0T9+Fx3khHaowjCc7xJZRgZCxg43SbqMWJ9lUg94I7+LTX61Gyv
    dtlkbGbtoDOnxeNnN93gwQZngGYZYciu
    -----END PUBLIC KEY-----
    ");

    // Produz a versão hexadecimal da chave derivada
    echo bin2hex(openssl_pkey_derive($pub,$priv));

# openssl_pkey_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_export — Obtém uma representação exportável de uma chave em uma string

### Descrição

function openssl_pkey_export(
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$key`,
string `&$output`,
#[\SensitiveParameter]?string `$passphrase` = `null`,
?array `$options` = `null`
): bool

openssl_pkey_export() exporta a chave `key` como uma string codificada em PEM e a armazena na string `output` (que é passada por referência).

> Nota: É preciso ter um arquivo openssl.cnf válido instalado para que esta função funcione corretamente. Consulte as notas na seção de instalação para obter mais informações.

### Parâmetros

`key`

`output`

`passphrase`

  A chave é opcionalmente protegida por uma senha informada em `passphrase`.

`options`

  `options` pode ser usado para fazer ajuste fino do processo de exportação especificando e/ou substituindo opções para o arquivo de configuração do openssl. Consulte openssl_csr_new() para obter mais informações sobre `options`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `key` agora aceita uma instância de OpenSSLAsymmetricKey ou OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL key` ou `OpenSSL X.509` era aceito.

# openssl_pkey_export_to_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_export_to_file — Obtém uma representação exportável de uma chave em um arquivo

### Descrição

function openssl_pkey_export_to_file(
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$key`,
string `$output_filename`,
#[\SensitiveParameter]?string `$passphrase` = `null`,
?array `$options` = `null`
): bool

openssl_pkey_export_to_file() salva uma versão ASCII blindada (codificada em PEM) de `key` no arquivo nomeado por `output_filename`.

> Nota: É preciso ter um arquivo openssl.cnf válido instalado para que esta função funcione corretamente. Consulte as notas na seção de instalação para obter mais informações.

### Parâmetros

`key`

`output_filename`

  Caminho para o arquivo de saída.

`passphrase`

  A chave pode ser opcionalmente protegida por uma senha definida no parâmetro `passphrase`.

`options`

  `options` pode ser usado para fazer ajuste fino do processo de exportação especificando e/ou substituindo opções para o arquivo de configuração do openssl. Consulte openssl_csr_new() para obter mais informações sobre `options`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `key` agora aceita uma instância de OpenSSLAsymmetricKey ou OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL key` ou `OpenSSL X.509` era aceito.

# openssl_pkey_free

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_free — Libera uma chave privada

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.0.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
function openssl_pkey_free(OpenSSLAsymmetricKey `$key`): void

> Nota: Esta função não tem efeito. Antes do PHP 8.0.0, esta função era usada para fechar o recurso.

Esta função libera uma chave privada criada por openssl_pkey_new().

### Parâmetros

`key`

  Recurso que contém a chave.

### Valor Retornado

Nenhum valor é retornado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Esta função agora está descontinuada e não tem mais efeito.
8.0.0 | `key` agora aceita uma instância de OpenSSLAsymmetricKey; anteriormente, um resource do tipo `OpenSSL key` era aceito.

# openssl_pkey_get_details

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

openssl_pkey_get_details — Retorna um array com os detalhes da chave

### Descrição

function openssl_pkey_get_details(OpenSSLAsymmetricKey `$key`): array|false

Esta função retorna os detalhes da chave (bits, chave, tipo).

### Parâmetros

`key`

  Recurso que contém a chave.

### Valor Retornado

Retorna um array com os principais detalhes em caso de sucesso ou `false` em caso de falha. O array retornado tem os índices `bits` (número de bits), `key` (representação em string da chave pública) e `type` (tipo da chave que é uma das constantes `OPENSSL_KEYTYPE_RSA`, `OPENSSL_KEYTYPE_DSA`, `OPENSSL_KEYTYPE_DH`, `OPENSSL_KEYTYPE_EC`, `OPENSSL_KEYTYPE_X25519`, `OPENSSL_KEYTYPE_ED25519`, `OPENSSL_KEYTYPE_X448`, `OPENSSL_KEYTYPE_ED448`, ou `-1` que significa desconhecido).

Dependendo do tipo de chave utilizado, detalhes adicionais poderão ser retornados. Observe que alguns elementos podem nem sempre estar disponíveis.

- `OPENSSL_KEYTYPE_RSA`, uma chave de array adicional chamada `"rsa"`, contendo os dados da chave, é retornada.

  Chave | Descrição
  --- | ---
  `"n"` | módulo
  `"e"` | expoente público
  `"d"` | expoente privado
  `"p"` | primo número 1
  `"q"` | primo número 2
  `"dmp1"` | expoente 1, d mod (p-1)
  `"dmq1"` | expoente 2, d mod (q-1)
  `"iqmp"` | coeficiente, (inverso de q) mod p

- `OPENSSL_KEYTYPE_DSA`, uma chave de array adicional chamada `"dsa"`, contendo os dados da chave, é retornada.

  Chave | Descrição
  --- | ---
  `"p"` | número primo (público)
  `"q"` | sub-primo de 160 bits, q | p-1 (público)
  `"g"` | gerador de subgrupo (público)
  `"priv_key"` | chave privada x
  `"pub_key"` | chave pública y = g^x

- `OPENSSL_KEYTYPE_DH`, uma chave de array adicional chamada `"dh"`, contendo os dados da chave, é retornada.

  Chave | Descrição
  --- | ---
  `"p"` | número primo (compartilhado)
  `"g"` | gerador de Z_p (compartilhado)
  `"priv_key"` | valor DH privado x
  `"pub_key"` | valor DH público g^x

- `OPENSSL_KEYTYPE_X25519`, `OPENSSL_KEYTYPE_ED25519`, `OPENSSL_KEYTYPE_X448`, ou `OPENSSL_KEYTYPE_ED448`. Uma chave de array adicional chamada `"x25519"`, `"ed25519"`, `"x448"`, ou `"ed448"` respectivamente, é retornada, contendo os dados da chave.

  Chave | Descrição
  --- | ---
  `"priv_key"` | chave privada
  `"pub_key"` | chave pública

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Adicionado suporte às chaves baseadas em Curve25519 e Curve448. Especificamente, os campos `x25519`, `ed25519`, `x448` e `ed448` foram introduzidos.
8.0.0 | `key` agora aceita uma instância de OpenSSLAsymmetricKey; anteriormente, um resource do tipo `OpenSSL key` era aceito.

# openssl_pkey_get_private

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_get_private — Obtém uma chave privada

### Descrição

function openssl_pkey_get_private(#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`, #[\SensitiveParameter]?string `$passphrase` = `null`): OpenSSLAsymmetricKey|false

openssl_pkey_get_private() analisa a chave privada `private_key` e prepara-a para uso por outras funções.

### Parâmetros

`private_key`

  `private_key` pode ser uma das seguintes opções:

  1. uma string no formato file://caminho/para/arquivo.pem. O arquivo precisa conter uma chave privada ou certificado (pode conter ambos) codificados em PEM.
  2. Uma chave privada no formato PEM.
`passphrase`

  O parâmetro opcional `passphrase` contém uma senha que precisa ser usada se a chave especificada for criptografada (protegida por uma senha).

### Valor Retornado

Retorna uma instância de OpenSSLAsymmetricKey em caso de sucesso ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Em caso de sucesso, esta função retorna uma instância OpenSSLAsymmetricKey agora; anteriormente, retornava um resource do tipo `OpenSSL key`.
8.0.0 | `private_key` agora aceita uma instância de OpenSSLAsymmetricKey ou OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL key` ou `OpenSSL X.509` era aceito.
8.0.0 | `passphrase` agora pode ser nulo.

# openssl_pkey_get_public

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_get_public — Extrai a chave pública do certificado e prepara-a para uso

### Descrição

function openssl_pkey_get_public(OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`): OpenSSLAsymmetricKey|false

openssl_pkey_get_public() extrai a chave pública de `public_key` e prepara-a para uso por outras funções.

### Parâmetros

`public_key`

  `public_key` pode ser uma das seguintes opções:

  1. uma instância de OpenSSLAsymmetricKey
  2. uma string no formato file://caminho/para/arquivo.pem. O arquivo precisa conter uma chave pública ou certificado (pode conter ambos) codificados em PEM.
  3. Uma chave pública no formato PEM.

### Valor Retornado

Retorna uma instância de OpenSSLAsymmetricKey em caso de sucesso ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Em caso de sucesso, esta função retorna uma instância OpenSSLAsymmetricKey agora; anteriormente, retornava um resource do tipo `OpenSSL key`.
8.0.0 | `public_key` agora aceita uma instância de OpenSSLAsymmetricKey ou OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL key` ou `OpenSSL X.509` era aceito.

# openssl_pkey_new

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_new — Gera uma nova chave privada

### Descrição

function openssl_pkey_new(?array `$options` = `null`): OpenSSLAsymmetricKey|false

openssl_pkey_new() gera uma nova chave privada. Como obter o componente público da chave é mostrado no exemplo abaixo.

> Nota: É preciso ter um arquivo openssl.cnf válido instalado para que esta função funcione corretamente. Consulte as notas na seção de instalação para obter mais informações.

### Parâmetros

`options`

  É possível fazer ajuste fino na geração de chaves (como especificar o número de bits ou parâmetros) usando `options`. Estas opções podem ser parâmetro específicos do algoritmo usado para geração da chave ou opções genéricas usadas também na geração de CSR se não especificadas. Consulte openssl_csr_new() para obter mais informações sobre como usar o parâmetro `options` para um CSR. Entre estas opções, somente `private_key_bits`, `private_key_type`, `curve_name`, e `config` são usadas para geração de chaves. Opções específicas de algoritmos são usadas se o array associativo incluir uma das chaves específicas.

  - Chave `"rsa"` para definir os parâmetros RSA.

    Opções | Tipo | Formato | Obrigatória | Descrição
    --- | --- | --- | --- | ---
    `"n"` | string | número binário | sim | resto
    `"e"` | string | número binário | não | expoente público
    `"d"` | string | número binário | sim | expoente privado
    `"p"` | string | número binário | não | primo 1
    `"q"` | string | número binário | não | primo 2
    `"dmp1"` | string | número binário | não | expoente 1, d mod (p-1)
    `"dmq1"` | string | número binário | não | expoente 2, d mod (q-1)
    `"iqmp"` | string | número binário | não | coeficiente, (inverso de q) mod p

  - Chave `"dsa"` para definir parâmetros DSA.

    Opções | Tipo | Formato | Obrigatória | description
    --- | --- | --- | --- | ---
    `"p"` | string | número binário | não | número primo (público)
    `"q"` | string | número binário | não | subprimo de 160 bits, q | p-1 (público)
    `"g"` | string | número binário | não | gerador de subgrupo (público)
    `"priv_key"` | string | chave PEM | não | chave privada x
    `"pub_key"` | string | chave PEM | não | chave pública y = g^x

  - Chave `"dh"` para parâmetros DH (troca de chaves Diffie–Hellman).

    Opções | Tipo | Formato | Obrigatória | Descrição
    --- | --- | --- | --- | ---
    `"p"` | string | número binário | não | número primo (compartilhado)
    `"g"` | string | número binário | não | gerador de Z_p (compartilhado)
    `"priv_key"` | string | chave PEM | não | valor x do DH privado
    `"pub_key"` | string | chave PEM | não | valor g^x do DH público

  - Chave `"ec"` para parâmetros de curva elíptica

    Opções | Tipo | Formato | Obrigatória | Descrição
    --- | --- | --- | --- | ---
    `"curve_name"` | string | Nome | não | Nome da curva, consulte openssl_get_curve_names()
    `"p"` | string | número binário | não | primo do campo para a curva sobre Fp
    `"a"` | string | número binário | não | coeficiente da curva para Fp: y^2 mod p = x^3 + ax + b mod p
    `"b"` | string | número binário | não | coeficiente da curva para Fp: y^2 mod p = x^3 + ax + b mod p
    `"seed"` | string | número binário | não | semente de número aleatório opcional usada para gerar o coeficiente b
    `"generator"` | string | ponto codificado em binário | não | ponto de geração da curva
    `"g_x"` | string | número binário | não | coordenada x do ponto de geração da curva
    `"g_y"` | string | número binário | não | coordenada y do ponto de geração da curva
    `"cofactor"` | string | número binário | não | co-fator da curva
    `"order"` | string | número binário | não | ordem da curva
    `"x"` | string | número binário | não | coordenada x (pública)
    `"y"` | string | número binário | não | coordenada y (pública)
    `"d"` | string | número binário | não | chave privada

  - Chaves `"x25519"`, `"x448"`, `"ed25519"` e `"ed448"` para parâmetros Curve25519 e Curve448.

    Opções | Tipo | Formato | Obrigatória | Descrição
    --- | --- | --- | --- | ---
    `"priv_key"` | string | chave PEM | não | chave privada
    `"pub_key"` | string | chave PEM | não | chave pública

### Valor Retornado

Retorna uma instância de OpenSSLAsymmetricKey para a chave privada em caso de sucesso ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Adicionado suporte para chaves baseadas em Curve25519 e Curve448 com a instrodução dos campos `x25519`, `ed25519`, `x448` e `ed448`.
8.3.0 | Adicionado suporte para geração de chaves EC com parâmetros EC customizados. Especificamente, com a introdução das opções EC: `p`, `a`, `b`, `seed`, `generator`, `g_x`, `g_y`, `cofactor` e `order`.
8.0.0 | Em caso de sucesso, esta função retorna uma instância OpenSSLAsymmetricKey agora; anteriormente, retornava um resource do tipo `OpenSSL key`.
7.1.0 | A chave `curve_name` do parâmetro `options` foi adicionada para tornar possível a criação de chaves EC com base nos algoritmos de Curva Elíptica.

### Exemplos

Exemplo #1 Obtendo a chave pública de uma chave privada

    <?php

    $private_key = openssl_pkey_new();

    $public_key_pem = openssl_pkey_get_details($private_key)['key'];
    echo $public_key_pem, PHP_EOL;

    $public_key = openssl_pkey_get_public($public_key_pem);
    var_dump($public_key);

    ?>

O exemplo acima produzirá algo semelhante a:

    // Saída anterior ao PHP 8.0.0; observe que a função retorna um recurso
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwknBFEherZe74BiRjTFA
    hqwZ1SK7brwq7C/afnLXKhRR7jnrpfM0ypC46q8xz5UZswenZakJ7kd5fls+r4Bv
    3P8XsKYLTh2m1GiWQhV1g77cNIN4qNWh70PiDO3fB2446o1LBgToQYuRZS5YQRfJ
    rVD0ysgtVcCU9tjaey28HlgApOpYFTaaKPj2MBmEYpMC+kG2HhL12GfpHUi2eiXI
    dXT2WskWHWvUrmQ7fJIfI92JlDokV62DH/q1oiedLs9OPNb0rL1aAmYdzaVN6XNH
    x/o4Lh125v2vAPV9E3fZCDc/HDEUaahpjanMiCQEgEDp5Hr+CRkvERT5/ydN+p08
    5wIDAQAB
    -----END PUBLIC KEY-----

    resource(6) of type (OpenSSL key)

    // Saída a partir do PHP 8.0.0; observe que a função retorna um objeto
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwknBFEherZe74BiRjTFA
    hqwZ1SK7brwq7C/afnLXKhRR7jnrpfM0ypC46q8xz5UZswenZakJ7kd5fls+r4Bv
    3P8XsKYLTh2m1GiWQhV1g77cNIN4qNWh70PiDO3fB2446o1LBgToQYuRZS5YQRfJ
    rVD0ysgtVcCU9tjaey28HlgApOpYFTaaKPj2MBmEYpMC+kG2HhL12GfpHUi2eiXI
    dXT2WskWHWvUrmQ7fJIfI92JlDokV62DH/q1oiedLs9OPNb0rL1aAmYdzaVN6XNH
    x/o4Lh125v2vAPV9E3fZCDc/HDEUaahpjanMiCQEgEDp5Hr+CRkvERT5/ydN+p08
    5wIDAQAB
    -----END PUBLIC KEY-----

    object(OpenSSLAsymmetricKey)#2 (0) {
    }

Exemplo #2 Gerando chave RSA a partir de parâmetros

    <?php

    $nhex = "BBF82F090682CE9C2338AC2B9DA871F7368D07EED41043A440D6B6F07454F51F" .
            "B8DFBAAF035C02AB61EA48CEEB6FCD4876ED520D60E1EC4619719D8A5B8B807F" .
            "AFB8E0A3DFC737723EE6B4B7D93A2584EE6A649D060953748834B2454598394E" .
            "E0AAB12D7B61A51F527A9A41F6C1687FE2537298CA2A8F5946F8E5FD091DBDCB";

    $ehex = "11";
    $dhex = "A5DAFC5341FAF289C4B988DB30C1CDF83F31251E0668B42784813801579641B2" .
            "9410B3C7998D6BC465745E5C392669D6870DA2C082A939E37FDCB82EC93EDAC9" .
            "7FF3AD5950ACCFBC111C76F1A9529444E56AAF68C56C092CD38DC3BEF5D20A93" .
            "9926ED4F74A13EDDFBE1A1CECC4894AF9428C2B7B8883FE4463A4BC85B1CB3C1";

    $phex = "EECFAE81B1B9B3C908810B10A1B5600199EB9F44AEF4FDA493B81A9E3D84F632" .
            "124EF0236E5D1E3B7E28FAE7AA040A2D5B252176459D1F397541BA2A58FB6599";

    $qhex = "C97FB1F027F453F6341233EAAAD1D9353F6C42D08866B1D05A0F2035028B9D86" .
            "9840B41666B42E92EA0DA3B43204B5CFCE3352524D0416A5A441E700AF461503";

    $dphex = "11";
    $dqhex = "11";
    $qinvhex = "b06c4fdabb6301198d265bdbae9423b380f271f73453885093077fcd39e2119f" .
               "c98632154f5883b167a967bf402b4e9e2e0f9656e698ea3666edfb25798039f7";

    $rsa= openssl_pkey_new([
        'rsa' => [
            'n' => hex2bin($nhex),
            'e' => hex2bin($ehex),
            'd' => hex2bin($dhex),
            'p' => hex2bin($phex),
            'q' => hex2bin($qhex),
            'dmp1' => hex2bin($dphex),
            'dmq1' => hex2bin($dqhex),
            'iqmp' => hex2bin($qinvhex),
        ],
    ]);
    $details = openssl_pkey_get_details($rsa);
    var_dump($details);

    ?>

# openssl_private_decrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_private_decrypt — Descriptografa dados com chave privada

### Descrição

function openssl_private_decrypt(
string `$data`,
#[\SensitiveParameter]string `&$decrypted_data`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
int `$padding` = `OPENSSL_PKCS1_PADDING`,
?string `$digest_algo` = `null`
): bool

openssl_private_decrypt() descriptografa os dados em `data` que foram criptografados anteriormente via openssl_public_encrypt() e armazena o resultado em `decrypted_data`.

Esta função pode ser usada, por exemplo, para descriptografar dados que suportamente estão disponíveis apenas ao destinatário.

### Parâmetros

`data`

`decrypted_data`

`private_key`

  `private_key` deve ser a chave privada que corresponde à chave pública que foi usada para criptografar os dados.

`padding`

  `padding` pode ser uma das constantes `OPENSSL_PKCS1_PADDING`, `OPENSSL_SSLV23_PADDING`, `OPENSSL_PKCS1_OAEP_PADDING` ou `OPENSSL_NO_PADDING`.

`digest_algo`
  O algoritmo de resumo para preenchimento OAEP, ou `null` para usar o algoritmo padrão.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | O parâmetro opcional `digest_algo` foi adicionado.
8.0.0 | `private_key` agora aceita uma instância de OpenSSLAsymmetricKey ou OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL key` ou `OpenSSL X.509` era aceito.

### Veja Também

- openssl_public_encrypt() - Criptografa dados com chave pública
- openssl_public_decrypt() - Descriptografa dados com chave pública

# openssl_private_encrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_private_encrypt — Criptografa dados com chave privada

### Descrição

function openssl_private_encrypt(
#[\SensitiveParameter]string `$data`,
string `&$encrypted_data`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
int `$padding` = `OPENSSL_PKCS1_PADDING`
): bool

openssl_private_encrypt() criptografa os dados em `data` com a chave privada `private_key` e armazena o resultado em `encrypted_data`. Dados criptografados podem ser descriptografados pela função openssl_public_decrypt().

Esta função pode ser usada, por exemplo, para assinar dados (ou seu hash) para provar que não foram escritos por outra pessoa.

### Parâmetros

`data`

`encrypted_data`

`private_key`

  `private_key` deve ser a chave privada que corresponde à chave pública que foi usada para criptografar os dados.

`padding`

  `padding` pode ser uma das constantes `OPENSSL_PKCS1_PADDING` ou `OPENSSL_NO_PADDING`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `private_key` agora aceita uma instância de OpenSSLAsymmetricKey ou OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL key` ou `OpenSSL X.509` era aceito.

### Veja Também

- openssl_public_encrypt() - Criptografa dados com chave pública
- openssl_public_decrypt() - Descriptografa dados com chave pública

# openssl_public_decrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_public_decrypt — Descriptografa dados com chave pública

### Descrição

function openssl_public_decrypt(
string `$data`,
#[\SensitiveParameter]string `&$decrypted_data`,
OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`,
int `$padding` = `OPENSSL_PKCS1_PADDING`
): bool

openssl_public_decrypt() descriptografa os dados de `data` que foram criptografados anteriormente via openssl_private_encrypt() e armazena o resultado em `decrypted_data`.

Esta função pode ser usada, por exemplo, para verificar se a mensagem foi escrita pelo proprietário da chave privada.

### Parâmetros

`data`

`decrypted_data`

`public_key`

  `public_key` deve ser a chave pública que corresponde à chave privada que foi usada para criptografar os dados.

`padding`

  `padding` pode ser uma das constantes `OPENSSL_PKCS1_PADDING` ou `OPENSSL_NO_PADDING`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `public_key` agora aceita uma instância de OpenSSLAsymmetricKey ou OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL key` ou `OpenSSL X.509` era aceito.

### Veja Também

- openssl_private_encrypt() - Criptografa dados com chave privada
- openssl_private_decrypt() - Descriptografa dados com chave privada

# openssl_public_encrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_public_encrypt — Criptografa dados com chave pública

### Descrição

function openssl_public_encrypt(
#[\SensitiveParameter]string `$data`,
string `&$encrypted_data`,
OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`,
int `$padding` = `OPENSSL_PKCS1_PADDING`,
?string `$digest_algo` = `null`
): bool

openssl_public_encrypt() criptografa os dados em `data` a chave pública `public_key` e armazena o resultado em `encrypted_data`. Os dados criptografados podem ser descriptografados pela função openssl_private_decrypt().

Esta função pode ser usada, por exemplo, para criptografar mensagem que possa depois ser lida somente pelo proprietário da chave privada. Também pode ser usada para armazenar dados de forma segura em um banco de dados.

### Parâmetros

`data`

`encrypted_data`

  Esta variável conterá o resultado da criptografia.

`public_key`

  `public_key` deve ser a chave pública que corresponde à chave privada que foi usada para criptografar os dados.

`padding`

  `padding` pode ser uma das constantes `OPENSSL_PKCS1_PADDING`, `OPENSSL_SSLV23_PADDING`, `OPENSSL_PKCS1_OAEP_PADDING` ou `OPENSSL_NO_PADDING`.

`digest_algo`
  O algoritmo de resumo para preenchimento OAEP, ou `null` para usar o algoritmo padrão.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | O parâmetro opcional `digest_algo` foi adicionado.
8.0.0 | `public_key` agora aceita uma instância de OpenSSLAsymmetricKey ou OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL key` ou `OpenSSL X.509` era aceito.

### Veja Também

- openssl_private_encrypt() - Criptografa dados com chave privada
- openssl_private_decrypt() - Descriptografa dados com chave privada

# openssl_random_pseudo_bytes

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_random_pseudo_bytes — Gera uma sequência pseudo-aleatória de bytes

### Descrição

function openssl_random_pseudo_bytes(int `$length`, bool `&$strong_result` = `null`): string

Gera uma string de bytes pseudo-aleatórios, com o número de bytes determinado pelo parâmetro `length`.

Também indica se um algoritmo criptograficamente forte foi usado para produzir os bytes pseudo-aleatórios, e faz isso através do parâmetro opcional `strong_result`. É raro que isso seja `false`, mas alguns sistemas podem estar quebrados ou antigos.

### Parâmetros

`length`

  O comprimento da sequência de bytes desejada. Deve ser um número inteiro positivo menor ou igual a `2147483647`. O PHP tentará converter este parâmetro em um número inteiro não nulo para usá-lo.

`strong_result`

  Se passado para a função, conterá um valor bool que determina se o algoritmo usado era "criptograficamente forte", por exemplo, seguro para uso com GPG, senhas, etc. `true` se sim, caso contrário `false`.

### Valor Retornado

Retorna a string de bytes gerada.

### Erros/Exceções

openssl_random_pseudo_bytes() lança uma Exception em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `strong_result` agora pode ser nulo.
7.4.0 | A função não retorna mais `false` em caso de falha, mas em vez disso lança uma Exception.

### Exemplos

Exemplo #1 Exemplo de openssl_random_pseudo_bytes()

    <?php
    for ($i = 1; $i <= 4; $i++) {
        $bytes = openssl_random_pseudo_bytes($i, $cstrong);
        $hex   = bin2hex($bytes);

        echo "Comprimentos: Bytes: $i e Hex: " . strlen($hex) . PHP_EOL;
        var_dump($hex);
        var_dump($cstrong);
        echo PHP_EOL;
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Comprimentos: Bytes: 1 e Hex: 2
    string(2) "42"
    bool(true)

    Comprimentos: Bytes: 2 e Hex: 4
    string(4) "dc6e"
    bool(true)

    Comprimentos: Bytes: 3 e Hex: 6
    string(6) "288591"
    bool(true)

    Comprimentos: Bytes: 4 e Hex: 8
    string(8) "ab86d144"
    bool(true)

### Veja Também

- random_bytes() - Obtém bytes aleatórios criptograficamente seguros
- bin2hex() - Converte um dado binário em representação hexadecimal
- crypt() - Hash unidirecional de string
- random_int() - Obtém um número inteiro selecionado uniformemente e criptograficamente seguro

# openssl_seal

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_seal — Sela (criptografa) dados

### Descrição

function openssl_seal(
#[\SensitiveParameter]string `$data`,
string `&$sealed_data`,
array `&$encrypted_keys`,
array `$public_key`,
string `$cipher_algo`,
string `&$iv` = `null`
): int|false

openssl_seal() sela (criptografa) os dados de `data` usando o algoritmo de criptografia `cipher_algo` com uma chave secreta gerada aleatoriamente. A chave é então criptografada com cada uma das chaves públicas no array `public_key`, e cada chave de envelope criptografada é retornada em `encrypted_keys`. Isso permite que dados selados sejam enviados a vários destinatários (desde que suas chaves públicas estejam disponíveis). Cada destinatário deve receber os dados selados e a chave do envelope que foi criptografada com a chave pública do destinatário. O IV (Vetor de Inicialização) é gerado e seu valor é retornado em `iv`.

### Parâmetros

`data`

  Os dados a serem selados.

`sealed_data`

  Os dados selados.

`encrypted_keys`

  Array de chaves criptografadas.

`public_key`

  Array de instâncias de OpenSSLAsymmetricKey contendo chaves públicas.

`cipher_algo`

  O método de criptografia.

  Cuidado

  O valor padrão para versões do PHP anteriores a 8.0 é (`'RC4'`) que é considerado inseguro. É altamente recomendável especificar explicitamente um método de criptografia seguro.

`iv`

  O vetor de inicialização para descriptografia de `data`. É necessário se o método de criptografia exigir IV. Isso pode ser descoberto chamando openssl_cipher_iv_length() com `cipher_algo`.

  Cuidado

  O IV não pode ser definido explicitamente. Qualquer valor definido nele é substituído por um valor gerado aleatoriamente.

### Valor Retornado

Retorna o comprimento dos dados selados em caso de sucesso ou `false` em caso de erro. Se for bem-sucedido, os dados selados serão retornados em `sealed_data` e as chaves do envelope em `encrypted_keys`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `public_key` agora aceita um array de instâncias de OpenSSLAsymmetricKey; anteriormente, um array de resources do tipo `OpenSSL key` era aceito.
8.0.0 | `cipher_algo` não é mais um parâmetro opcional.
8.0.0 | `iv` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo de openssl_seal()

    <?php
    // Presume-se que $data contenha os dados a serem selados
    $data = "test";

    // busca chaves públicas
    $pk1 = openssl_get_publickey("file://cert1.pem");
    $pk2 = openssl_get_publickey("file://cert2.pem");

    // sela a mensagem, apenas os proprietários de $pk1 e $pk2 podem descriptografar $sealed com as chaves
    // $ekeys[0] e $ekeys[1] respectivamente.
    if (openssl_seal($data, $sealed, $ekeys, array($pk1, $pk2), 'AES256', $iv) > 0) {
        // possivelmente armazena os valores $sealed e $iv e usa mais tarde em openssl_open
        echo "sucesso\n";
    }
    ?>

### Veja Também

- openssl_open() - Abre dados lacrados

# openssl_sign

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_sign — Gera assinatura

### Descrição

function openssl_sign(
string `$data`,
string `&$signature`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
string|int `$algorithm` = `OPENSSL_ALGO_SHA1`,
int `$padding` = 0
): bool

openssl_sign() calcula uma assinatura para os dados informados em `data` gerando uma assinatura digital criptográfica usando a chave privada associada a `private_key`. Observe que os dados em si não são criptografados.

### Parâmetros

`data`

  A string de dados a ser assinada.

`signature`

  Se a chamada for bem-sucedida, a assinatura será retornada em `signature`.

`private_key`

  OpenSSLAsymmetricKey - uma chave, retornada por openssl_get_privatekey()

  string - uma chave no formato PEM

`algorithm`

  int - um destes Algoritmos de Assinatura.

  string - uma string válida retornada por openssl_get_md_methods(), por exemplo, "sha256WithRSAEncryption" ou "sha384".

`padding`
  Preenchimento PSS RSA a ser usado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | O parâmetro opcional `padding` foi adicionado.
8.0.0 | `private_key` agora aceita uma instância de OpenSSLAsymmetricKey ou OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL key` ou `OpenSSL X.509` era aceito.

### Exemplos

Exemplo #1 Exemplo de openssl_sign()

    <?php
    // Presume-se que $data contenha os dados a serem assinados

    // busca a chave privada do arquivo e a prepara
    $pkeyid = openssl_pkey_get_private("file://src/openssl-0.9.6/demos/sign/key.pem");

    // calcula assinatura
    openssl_sign($data, $signature, $pkeyid);

    // libera a chave da memória
    openssl_free_key($pkeyid);
    ?>

Exemplo #2 Exemplo de openssl_sign()

    <?php
    // dados a serem assinados
    $data = 'my data';

    // cria nova chave pública e privada
    $new_key_pair = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));
    openssl_pkey_export($new_key_pair, $private_key_pem);

    $details = openssl_pkey_get_details($new_key_pair);
    $public_key_pem = $details['key'];

    // cria assinatura
    openssl_sign($data, $signature, $private_key_pem, OPENSSL_ALGO_SHA256);

    // grava para mais tarde
    file_put_contents('private_key.pem', $private_key_pem);
    file_put_contents('public_key.pem', $public_key_pem);
    file_put_contents('signature.dat', $signature);

    // verifica assinatura
    $r = openssl_verify($data, $signature, $public_key_pem, "sha256WithRSAEncryption");
    var_dump($r);
    ?>

### Veja Também

- openssl_verify() - Verifica assinatura

# openssl_spki_export

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_export — Exporta uma chave pública assinada válida e formatada em PEM e um desafio

### Descrição

function openssl_spki_export(string `$spki`): string|false

Exporta chave pública formatada em PEM de chave pública assinada codificada e desafio

### Parâmetros

`spki`

  Espera uma chave pública assinada válida e um desafio

### Valor Retornado

Retorna a chave pública formatada em PEM associada ou `false` em caso de falha.

### Erros/Exceções

Emite um erro de nível `E_WARNING` se um argumento inválido for passado através do parâmetro `spki`.

### Exemplos

Exemplo #1 Exemplo de openssl_spki_export()

Extrai a chave pública formatada em PEM associada ou `null` em caso de falha.

    <?php
    $pkey = openssl_pkey_new('senha secreta');
    $spkac = openssl_spki_new($pkey, 'string de desafio');
    $pubKey = openssl_spki_export(preg_replace('/SPKAC=/', '', $spkac));

    if ($pubKey) {
        echo $pubKey;
    }
    ?>

Exemplo #2 Exemplo de openssl_spki_export() a partir de <keygen>

Extrai a chave pública formatada em PEM associada emitida pelo elemento <keygen>

    <?php
    $spkac = openssl_spki_export(preg_replace('/SPKAC=/', '', $_POST['spkac']));
    if ($spkac != NULL) {
        echo $spkac;
    } else {
        echo "Extração de chave pública falhou";
    }
    ?>
    <keygen name="spkac" challenge="string de desafio" keytype="RSA">

### Veja Também

- openssl_spki_new() - Gera uma nova chave pública assinada e um desafio
- openssl_spki_verify() - Verifica uma chave pública assinada e um desafio
- openssl_spki_export_challenge() - Exporta o desafio associado a uma chave pública assinada e a um desafio
- openssl_get_md_methods() - Obtém métodos de resumo disponíveis
- openssl_csr_new() - Gera um CSR
- openssl_csr_sign() - Assina um CSR com outro certificado (ou ele mesmo) e gera um certificado

# openssl_spki_export_challenge

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_export_challenge — Exporta o desafio associado a uma chave pública assinada e a um desafio

### Descrição

function openssl_spki_export_challenge(string `$spki`): string|false

Exporta o desafio a partir da chave pública assinada codificada e do desafio.

### Parâmetros

`spki`

  Espera uma chave pública assinada válida e um desafio

### Valor Retornado

Retorna a string de desafio associada ou `false` em caso de falha.

### Erros/Exceções

Emite um erro de nível `E_WARNING` se um argumento inválido for passado através do parâmetro `spki`.

### Exemplos

Exemplo #1 Exemplo de openssl_spki_export_challenge()

Extrai a string de desafio associada ou NULL em caso de falha.

    <?php
    $pkey = openssl_pkey_new('senha secreta');
    $spkac = openssl_spki_new($pkey, 'string de desafio');
    $challenge = openssl_spki_export_challenge(preg_replace('/SPKAC=/', '', $spkac));
    ?>

Exemplo #2 Exemplo de openssl_spki_export_challenge() a partir de <keygen>

Extrai a string de desafio associada emitida do elemento <keygen>

    <?php
    $challenge = openssl_spki_export_challenge(preg_replace('/SPKAC=/', '', $_POST['spkac']));
    ?>
    <keygen name="spkac" challenge="string de desafio" keytype="RSA">

### Veja Também

- openssl_spki_new() - Gera uma nova chave pública assinada e um desafio
- openssl_spki_verify() - Verifica uma chave pública assinada e um desafio
- openssl_spki_export() - Exporta uma chave pública assinada válida e formatada em PEM e um desafio
- openssl_get_md_methods() - Obtém métodos de resumo disponíveis
- openssl_csr_new() - Gera um CSR
- openssl_csr_sign() - Assina um CSR com outro certificado (ou ele mesmo) e gera um certificado

# openssl_spki_new

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_new — Gera uma nova chave pública assinada e um desafio

### Descrição

function openssl_spki_new(#[\SensitiveParameter]OpenSSLAsymmetricKey `$private_key`, string `$challenge`, int `$digest_algo` = `OPENSSL_ALGO_MD5`): string|false

Gera uma chave pública assinada e um desafio usando um algoritmo de hash especificado.

### Parâmetros

`private_key`

  `private_key` deve ser definido como uma chave privada que foi gerada anteriormente por openssl_pkey_new() (ou obtida de outra família de funções openssl_pkey). A parte pública correspondente da chave será usada para assinar o CSR.

`challenge`

  O desafio associado à associação ao SPKAC.

`digest_algo`

  O algoritmo de resumo. Consulte openssl_get_md_method().

### Valor Retornado

Retorna uma chave pública assinada e uma string de desafio ou `false` em caso de falha.

### Erros/Exceções

Emite um erro de nível `E_WARNING` se um algoritmo de assinatura desconhecido for passado através do parâmetro `digest_algo`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `private_key` agora aceita uma instância de OpenSSLAsymmetricKey; anteriormente, um resource do tipo `OpenSSL key` era aceito.

### Exemplos

Exemplo #1 Exemplo de openssl_spki_new()

Gera um novo SPKAC com o resumo padrão (MD5)

    <?php
    $pkey = openssl_pkey_new('senha secreta');
    $spkac = openssl_spki_new($pkey, 'testando');

    if ($spkac !== NULL) {
        echo $spkac;
    } else {
        echo "Falha de geração de SPKAC";
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    MIICRzCCAS8wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDM3V3sS4o4
    mB9dczziRnjGAmSp+JwPrHoYMAFGvDNmZGyiWfU586X4BKs++BAj7e/FsAfno0Hd
    hN9FwpCNFSox30L03nQvLYJE7f/WqigwBeMRT7Op/xvFks4sT70xP2HRYv4KqP9a
    WRcKU6cFH8VxhFhqM2txEIxZKdFLaL28yT7bEDmcglf4JLDdgNMb9rET1dkgtKE6
    dOaJHPGjf1uvnOH4YwkQr7n4sLUR3Kdbh0ZJAFuQVDZulo+LLzxBBkqJJcB6FhF+
    oXCdHTKZnqAhpWDz+NXYytAmevab6IYm5TWPWsJUv1YKJA5lg2mXbbloIZlN9Mgc
    i9fi03bdw+crAgMBAAEWB3Rlc3RpbmcwDQYJKoZIhvcNAQEEBQADggEBALyUvP/o
    pPSoWBlorFyZ2RnGwKf9qMpE0q2IJP7G3oDR4LyK/m933DUiZ+YnqThrH/CWb4Ek
    y5I3OCyl3S4wCuU1ibZZwDVwYShr5ELp0J9PEf7qMQZOhNsizoC7k+Czb2xB6hYW
    sKfsfTKm3cXBtH3fdgc/Z1Z7VSWnAzYo38snqm72NTf5yFRnrQdphNNXi+kn1zHA
    lxXRyFDXHOcYsOnwAWfyXFA4QDHQ0ezz0UoCY8gJXovcZb4GRYqOLUAsF2HcNboy
    29WN8VqE29sL9QxVZFlwMcqyoLcNnyw38GvNvAGqSvzzbnEFP2MAQXJVe0H0hdp/
    MML5G2iNVgNozAo=

### Veja Também

- openssl_spki_verify() - Verifica uma chave pública assinada e um desafio
- openssl_spki_export_challenge() - Exporta o desafio associado a uma chave pública assinada e a um desafio
- openssl_spki_export() - Exporta uma chave pública assinada válida e formatada em PEM e um desafio
- openssl_get_md_methods() - Obtém métodos de resumo disponíveis
- openssl_csr_new() - Gera um CSR
- openssl_csr_sign() - Assina um CSR com outro certificado (ou ele mesmo) e gera um certificado

# openssl_spki_verify

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_verify — Verifica uma chave pública assinada e um desafio

### Descrição

function openssl_spki_verify(string `$spki`): bool

Valida a chave pública assinada e o desafio fornecidos.

### Parâmetros

`spki`

  Espera uma chave pública assinada válida e um desafio

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Emite um erro de nível `E_WARNING` se um argumento inválido for passado através do parâmetro `spki`.

### Exemplos

Exemplo #1 Exemplo de openssl_spki_verify()

Valida uma chave pública assinada existente e um desafio

    <?php
    $pkey = openssl_pkey_new('senha secreta');
    $spkac = openssl_spki_new($pkey, 'string de desafio');

    if (openssl_spki_verify(preg_replace('/SPKAC=/', '', $spkac))) {
        echo $spkac;
    } else {
        echo "Validação de SPKAC falhou";
    }
    ?>

Exemplo #2 Exemplo de openssl_spki_verify() a partir de <keygen>

Valida uma chave pública assinada existente e um desafio emitido pelo elemento <keygen>.

    <?php
    if (openssl_spki_verify(preg_replace('/SPKAC=/', '', $_POST['spkac']))) {
        echo $spkac;
    } else {
        echo "Validação de SPKAC falhou";
    }
    ?>
    <keygen name="spkac" challenge="string de desafio" keytype="RSA">

### Veja Também

- openssl_spki_new() - Gera uma nova chave pública assinada e um desafio
- openssl_spki_export_challenge() - Exporta o desafio associado a uma chave pública assinada e a um desafio
- openssl_spki_export() - Exporta uma chave pública assinada válida e formatada em PEM e um desafio
- openssl_get_md_methods() - Obtém métodos de resumo disponíveis
- openssl_csr_new() - Gera um CSR
- openssl_csr_sign() - Assina um CSR com outro certificado (ou ele mesmo) e gera um certificado

# openssl_verify

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_verify — Verifica assinatura

### Descrição

function openssl_verify(
string `$data`,
string `$signature`,
OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`,
string|int `$algorithm` = `OPENSSL_ALGO_SHA1`,
int `$padding` = 0
): int|false

openssl_verify() verifica que a assinatura em `signature` está correta para os dados especificados em `data` usans a chave pública `public_key`. Esta precisa ser a chave pública correspondente à chave privada utilizada para assinatura.

### Parâmetros

`data`

  A sequência de dados usada para gerar a assinatura anteriormente

`signature`

  Uma string binária bruta, gerada por openssl_sign() ou meios similares

`public_key`

  OpenSSLAsymmetricKey - uma chave, retornada por openssl_get_publickey()

  string - uma chave no formato PEM (por exemplo `-----BEGIN PUBLIC KEY----- MIIBCgK...`)

`algorithm`

  int - um destes Algoritmos de Assinatura.

  string - uma string válida retornada por openssl_get_md_methods(), por exemplo, "sha1WithRSAEncryption" ou "sha512".

`padding`
  Preenchimento PSS RSA a ser usado.

### Valor Retornado

Retorna 1 se a assinatura estiver correta, 0 se estiver incorreta e -1 ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | O parâmetro opcional `padding` foi adicionado.
8.0.0 | `public_key` agora aceita uma instância de OpenSSLAsymmetricKey ou OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL key` ou `OpenSSL X.509` era aceito.

### Exemplos

Exemplo #1 Exemplo de openssl_verify()

    <?php
    // Presume-se que $data e $signature contenham os dados e a assinatura

    // busca a chave pública do certificado e a prepara
    $pubkeyid = openssl_pkey_get_public("file://src/openssl-0.9.6/demos/sign/cert.pem");

    // afirma se a assinatura está correta ou não
    $ok = openssl_verify($data, $signature, $pubkeyid);
    if ($ok == 1) {
        echo "boa";
    } elseif ($ok == 0) {
        echo "ruim";
    } else {
        echo "erro ao verificar assinatura";
    }
    // libera a chave da memória
    openssl_free_key($pubkeyid);
    ?>

Exemplo #2 Exemplo de openssl_verify()

    <?php
    // dados a serem assinados
    $data = 'my data';

    // cria uma nova chave privada e pública
    $private_key_res = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));
    $details = openssl_pkey_get_details($private_key_res);
    $public_key_res = openssl_pkey_get_public($details['key']);

    // cira assinatura
    openssl_sign($data, $signature, $private_key_res, "sha256WithRSAEncryption");

    // verifica assinatura
    $ok = openssl_verify($data, $signature, $public_key_res, OPENSSL_ALGO_SHA256);
    if ($ok == 1) {
        echo "válida";
    } elseif ($ok == 0) {
        echo "inválida";
    } else {
        echo "erro: ".openssl_error_string();
    }
    ?>

### Veja Também

- openssl_sign() - Gera assinatura

# openssl_x509_check_private_key

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_x509_check_private_key — Verifica se uma chave privada corresponde a um certificado

### Descrição

function openssl_x509_check_private_key(OpenSSLCertificate|string `$certificate`, #[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`): bool

Verifica se a chave privada informada em `private_key` é a que corresponde ao certificado fornecidor em `certificate`.

Aviso

A função não verifica se `private_key` é de fato uma chave privada ou não. Ela apenas compara os materiais públicos (por exemplo, expoente e módulo de uma chave RSA) e/ou parâmetros da chave (por exemplo, parâmetros EC de uma chave EC) de um par de chaves.

Isto significa, por exemplo, que uma chave pública poderia ser informada em `private_key` e a função poderia retornar `true`.

### Parâmetros

`certificate`

  O certificado.

`private_key`

  A chave privada.

### Valor Retornado

Retorna `true` se `private_key` for a chave privada que corresponde ao certificado do parâmetro `certificate`, ou `false` caso contrário.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `certificate` agora aceita uma instância de OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL X.509` era aceito.
8.0.0 | `private_key` agora aceita uma instância de OpenSSLAsymmetricKey ou OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL key` ou `OpenSSL X.509` era aceito.

# openssl_x509_checkpurpose

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_checkpurpose — Verifica se um certificado pode ser usado para uma finalidade específica

### Descrição

function openssl_x509_checkpurpose(
OpenSSLCertificate|string `$certificate`,
int `$purpose`,
array `$ca_info` = [],
?string `$untrusted_certificates_file` = `null`
): bool|int

openssl_x509_checkpurpose() examina um certificado para ver se pode ser usado para o a finalidade especificada em `purpose`.

### Parâmetros

`certificate`

  O certificado examinado.

`purpose`

  openssl_x509_checkpurpose() purposes
  Constante | Descrição
  --- | ---
  X509_PURPOSE_SSL_CLIENT | O certificado pode ser usado no lado do cliente de uma conexão SSL?
  X509_PURPOSE_SSL_SERVER | O certificado pode ser usado no lado do servidor de uma conexão SSL?
  X509_PURPOSE_NS_SSL_SERVER | O certificado pode ser usado para o servidor Netscape SSL?
  X509_PURPOSE_SMIME_SIGN | O certificado pode ser usado para assinar e-mail S/MIME?
  X509_PURPOSE_SMIME_ENCRYPT | O certificado pode ser usado para criptografar e-mails S/MIME?
  X509_PURPOSE_CRL_SIGN | O certificado pode ser usado para assinar uma lista de certificados revogados (CRL)?
  X509_PURPOSE_ANY | O certificado pode ser usado para qualquer/todos os fins?

  Estas opções não são campos de bits - somente uma pode ser especificada!
`ca_info`

  `ca_info` deve ser um array de arquivos/diretórios CA confiáveis como descrito em Verificação de Certificados.

`untrusted_certificates_file`

  Se especificado, este deve ser o nome de um arquivo codificado em PEM contendo certificados que podem ser usados ​​para ajudar a verificar o certificado, embora nenhuma confiança seja colocada nos certificados provenientes desse arquivo.

### Valor Retornado

Retorna `true` se o certificado puder ser usado para a finalidade pretendida, `false` se não puder, ou -1 em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `certificate` agora aceita uma instância de OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL X.509` era aceito.
8.0.0 | `untrusted_certificates_file` agora pode ser nulo.

# openssl_x509_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_x509_export — Exporta um certificado como uma string

### Descrição

function openssl_x509_export(OpenSSLCertificate|string `$certificate`, string `&$output`, bool `$no_text` = `true`): bool

openssl_x509_export() armazena o certificado informado no parâmetro `certificate` em uma string especificada por `output` em um formato PEM.

### Parâmetros

`certificate`
  Consulte Parâmetros Chave/Certificado para obter uma lista de valores válidos.
`output`

  Em caso de sucesso, esta variável conterá o PEM.

`no_text`
  O parâmetro opcional `notext` afeta a verbosidade da saída; se for `false`, então informações adicionais legíveis para humanos serão incluídas na saída. O valor padrão de `notext` é `true`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `certificate` agora aceita uma instância de OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL X.509` era aceito.

# openssl_x509_export_to_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_x509_export_to_file — Exporta um certificado para arquivo

### Descrição

function openssl_x509_export_to_file(OpenSSLCertificate|string `$certificate`, string `$output_filename`, bool `$no_text` = `true`): bool

openssl_x509_export_to_file() armazena o certificado informado no parâmetro `certificate` em um arquivo de nome `output_filename` em um formato PEM.

### Parâmetros

`certificate`
  Consulte Parâmetros Chave/Certificado para obter uma lista de valores válidos.
`output_filename`

  Caminho para o arquivo de saída.

`no_text`
  O parâmetro opcional `notext` afeta a verbosidade da saída; se for `false`, então informações adicionais legíveis para humanos serão incluídas na saída. O valor padrão de `notext` é `true`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `certificate` agora aceita uma instância de OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL X.509` era aceito.

# openssl_x509_fingerprint

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_x509_fingerprint — Calcula a impressão digital, ou resumo, de um determinado certificado X.509

### Descrição

function openssl_x509_fingerprint(OpenSSLCertificate|string `$certificate`, string `$digest_algo` = "sha1", bool `$binary` = `false`): string|false

openssl_x509_fingerprint() retorna o resumo de `certificate` como uma string.

### Parâmetros

`certificate`
  Consulte Parâmetros Chave/Certificado para obter uma lista de valores válidos.
`digest_algo`

  O método de resumo ou algoritmo de hash a ser usado, por exemplo "sha256", um dos métodos de openssl_get_md_methods().

`binary`

  Quando definido como `true`, gera dados binários brutos. `false` gera hexadecimais em minúsculas.

### Valor Retornado

Retorna uma string contendo a impressão digital do certificado calculada como hexadecimais em minúsculas, a menos que `binary` esteja definido como `true` nesse caso, a representação binária bruta do resumo da mensagem é retornada.

Retorna `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `certificate` agora aceita uma instância de OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL X.509` era aceito.

# openssl_x509_free

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_free — Libera recurso de certificado

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.0.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
function openssl_x509_free(OpenSSLCertificate `$certificate`): void

> Nota: Esta função não tem efeito. Antes do PHP 8.0.0, esta função era usada para fechar o recurso.

openssl_x509_free() libera da memória o certificado associado com o recurso especificado no parâmetro `certificate`.

### Parâmetros

`certificate`

### Valor Retornado

Nenhum valor é retornado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Esta função agora está descontinuada e não tem mais efeito.
8.0.0 | `certificate` agora aceita uma instância de OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL X.509` era aceito.

# openssl_x509_parse

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_parse — Analisa um certificado X509 e retorna as informações como um array

### Descrição

function openssl_x509_parse(OpenSSLCertificate|string `$certificate`, bool `$short_names` = `true`): array|false

openssl_x509_parse() retorna informações sobre o certificado fornecido em `certificate`, incluindo campos como nome do assunto, nome do emissor, finalidades, intervalo de datas válidas etc.

### Parâmetros

`certificate`

  Certificado X509. Consulte os parâmetros de chave/certificado para uma lista de valores válidos.

`short_names`

  `short_names` controla como os dados são indexados no array - se `short_names` for `true` (o padrão), os campos serão indexados com o formato de nome abreviado, caso contrário, o formato de nome longo será usado - por exemplo: CN é o formato de nome abreviado de commonName.

### Valor Retornado

A estrutura dos dados retornados ainda não está documentada (deliberadamente), pois ainda está sujeita a alterações.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | A análise de certificado sem os segundos no horário UTC não é mais permitida para nenhuma versão do OpenSSL. Já não era permitida para as versões 3.3+ do OpenSSL.
8.0.0 | `certificate` agora aceita uma instância de OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL X.509` era aceito.

# openssl_x509_read

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_read — Analisa um certificado X.509 e retorna um objeto para ele

### Descrição

function openssl_x509_read(OpenSSLCertificate|string `$certificate`): OpenSSLCertificate|false

openssl_x509_read() analisa o certificado fornecido por `certificate` e retorna um objeto OpenSSLCertificate para ele.

### Parâmetros

`certificate`

  Certificado X509. Consulte os parâmetros de chave/certificado para uma lista de valores válidos.

### Valor Retornado

Retorna um OpenSSLCertificate em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Um `E_WARNING` é emitido que o certificado X.509 não puder ser recuperado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Em caso de sucesso, esta função agora retorna uma instância de OpenSSLCertificate; anteriormente, retornava um resource do tipo `OpenSSL X.509`.
8.0.0 | `certificate` agora aceita uma instância de OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL X.509` era aceito.

# openssl_x509_verify

(PHP 7 >= 7.4.0, PHP 8)

openssl_x509_verify — Verifica a assinatura digital do certificado x509 em relação a uma chave pública

### Descrição

function openssl_x509_verify(OpenSSLCertificate|string `$certificate`, OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`): int

openssl_x509_verify() verifica se o certificado `certificate` foi assinado pela chave privada correspondente à chave pública `public_key`.

### Parâmetros

`certificate`
  Consulte Parâmetros Chave/Certificado para obter uma lista de valores válidos.
`public_key`

  OpenSSLAsymmetricKey - uma chave, retornada por openssl_get_publickey()

  string - uma chave no formato PEM (por exemplo, `-----BEGIN PUBLIC KEY----- MIIBCgK...`)

### Valor Retornado

Retorna 1 se a assinatura estiver correta, 0 se estiver incorreta e -1 em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `certificate` agora aceita uma instância de OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL X.509` era aceito.
8.0.0 | `public_key` agora aceita uma instância de OpenSSLAsymmetricKey ou OpenSSLCertificate; anteriormente, um resource do tipo `OpenSSL key` ou `OpenSSL X.509` era aceito.

### Exemplos

Exemplo #1 Exemplo de openssl_x509_verify()

    <?php
    $hostname = "news.php.net";
    $ssloptions = array(
        "capture_peer_cert" => true,
        "capture_peer_cert_chain" => true,
        "allow_self_signed"=> false,
        "CN_match" => $hostname,
        "verify_peer" => true,
        "SNI_enabled" => true,
        "SNI_server_name" => $hostname,
    );

    $ctx = stream_context_create( array("ssl" => $ssloptions) );
    $result = stream_socket_client("ssl://$hostname:443", $errno, $errstr, 30, STREAM_CLIENT_CONNECT, $ctx);
    $cont = stream_context_get_params($result);
    $x509 = $cont["options"]["ssl"]["peer_certificate"];
    $certparsed = openssl_x509_parse($x509);

    foreach($cont["options"]["ssl"]["peer_certificate_chain"] as $chaincert)
    {
        $chainparsed = openssl_x509_parse($chaincert);
        $chain_public_key = openssl_get_publickey($chaincert);
        $r = openssl_x509_verify($x509, $chain_public_key);
        if ($r==1)
        {
            echo $certparsed['subject']['CN'];
            echo " foi assinado digitalmente por ";
            echo $chainparsed['subject']['CN']."\n";
        }
    }
    ?>

### Veja Também

- openssl_verify() - Verifica assinatura
- openssl_get_publickey() - Sinônimo de openssl_pkey_get_public

## Índice

- openssl_cipher_iv_length — Obtém o comprimento do vetor de inicialização da cifra
- openssl_cipher_key_length — Obtém o comprimento da chave da cifra
- openssl_cms_decrypt — Descriptografa uma mensagem CMS
- openssl_cms_encrypt — Criptografa uma mensagem CMS
- openssl_cms_read — Exporta o arquivo CMS para um array de certificados PEM
- openssl_cms_sign — Assina um arquivo
- openssl_cms_verify — Verifica uma assinatura CMS
- openssl_csr_export — Exporta um CSR como uma string
- openssl_csr_export_to_file — Exporta um CSR para um arquivo
- openssl_csr_get_public_key — Retorna a chave pública de um CSR
- openssl_csr_get_subject — Retorna o assunto de um CSR
- openssl_csr_new — Gera um CSR
- openssl_csr_sign — Assina um CSR com outro certificado (ou ele mesmo) e gera um certificado
- openssl_decrypt — Descritografa dados
- openssl_dh_compute_key — Calcula o segredo compartilhado para o valor público da chave pública DH remota e da chave DH local
- openssl_digest — Computa um resumo
- openssl_encrypt — Criptografa dados
- openssl_error_string — Retorna mensagem de erro do openSSL
- openssl_free_key — Libera recurso de chave
- openssl_get_cert_locations — Recupera os locais de certificados disponíveis
- openssl_get_cipher_methods — Obtém métodos de criptografia disponíveis
- openssl_get_curve_names — Obtém lista de nomes de curvas disponíveis para ECC
- openssl_get_md_methods — Obtém métodos de resumo disponíveis
- openssl_get_privatekey — Sinônimo de openssl_pkey_get_private
- openssl_get_publickey — Sinônimo de openssl_pkey_get_public
- openssl_open — Abre dados lacrados
- openssl_password_hash — Cria um hash de senha usando a implementação Argon2 do OpenSSL
- openssl_password_verify — Verifica uma senha em relação a um hash usando a implementação Argon2 do OpenSSL
- openssl_pbkdf2 — Gera uma string PKCS5 v2 PBKDF2
- openssl_pkcs12_export — Exporta um arquivo de armazenamento de certificados compatível com PKCS#12 para uma variável
- openssl_pkcs12_export_to_file — Exporta um arquivo de armazenamento de certificados compatível com PKCS#12
- openssl_pkcs12_read — Analisa um armazenamento de certificados PKCS#12 em um array
- openssl_pkcs7_decrypt — Descriptografa uma mensagem criptografada S/MIME
- openssl_pkcs7_encrypt — Criptografa uma mensagem S/MIME
- openssl_pkcs7_read — Exporta o arquivo PKCS7 para um array de certificados PEM
- openssl_pkcs7_sign — Assina uma mensagem S/MIME
- openssl_pkcs7_verify — Verifica a assinatura de uma mensagem assinada por S/MIME
- openssl_pkey_derive — Calcula o segredo compartilhado para o valor público da chave DH ou ECDH remota e local
- openssl_pkey_export — Obtém uma representação exportável de uma chave em uma string
- openssl_pkey_export_to_file — Obtém uma representação exportável de uma chave em um arquivo
- openssl_pkey_free — Libera uma chave privada
- openssl_pkey_get_details — Retorna um array com os detalhes da chave
- openssl_pkey_get_private — Obtém uma chave privada
- openssl_pkey_get_public — Extrai a chave pública do certificado e prepara-a para uso
- openssl_pkey_new — Gera uma nova chave privada
- openssl_private_decrypt — Descriptografa dados com chave privada
- openssl_private_encrypt — Criptografa dados com chave privada
- openssl_public_decrypt — Descriptografa dados com chave pública
- openssl_public_encrypt — Criptografa dados com chave pública
- openssl_random_pseudo_bytes — Gera uma sequência pseudo-aleatória de bytes
- openssl_seal — Sela (criptografa) dados
- openssl_sign — Gera assinatura
- openssl_spki_export — Exporta uma chave pública assinada válida e formatada em PEM e um desafio
- openssl_spki_export_challenge — Exporta o desafio associado a uma chave pública assinada e a um desafio
- openssl_spki_new — Gera uma nova chave pública assinada e um desafio
- openssl_spki_verify — Verifica uma chave pública assinada e um desafio
- openssl_verify — Verifica assinatura
- openssl_x509_check_private_key — Verifica se uma chave privada corresponde a um certificado
- openssl_x509_checkpurpose — Verifica se um certificado pode ser usado para uma finalidade específica
- openssl_x509_export — Exporta um certificado como uma string
- openssl_x509_export_to_file — Exporta um certificado para arquivo
- openssl_x509_fingerprint — Calcula a impressão digital, ou resumo, de um determinado certificado X.509
- openssl_x509_free — Libera recurso de certificado
- openssl_x509_parse — Analisa um certificado X509 e retorna as informações como um array
- openssl_x509_read — Analisa um certificado X.509 e retorna um objeto para ele
- openssl_x509_verify — Verifica a assinatura digital do certificado x509 em relação a uma chave pública

# A classe OpenSSLCertificate

(PHP 8)

## Introdução

Uma classe totalmente opaca que substitui os recursos do `OpenSSL X.509` a partir do PHP 8.0.0.

## Resumo da classe

final class OpenSSLCertificate {
}

# A classe OpenSSLCertificateSigningRequest

(PHP 8)

## Introdução

Uma classe totalmente opaca que substitui os recursos `OpenSSL X.509 CSR` a partir do PHP 8.0.0.

## Resumo da classe

final class OpenSSLCertificateSigningRequest {
}

# A classe OpenSSLAsymmetricKey

(PHP 8)

## Introdução

Uma classe totalmente opaca que substitui os recursos de `OpenSSL key` a partir do PHP 8.0.0.

## Resumo da classe

final class OpenSSLAsymmetricKey {
}

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
  - Tipos de Recurso
- Constantes predefinidas
  - Opções de verificação de propósito
  - Opções de preenchimento para criptografia assimétrica
  - Tipos de chave
  - Opções/Constantes PKCS7
  - Opções/Constantes CMS
  - Algoritmos de Assinatura
  - Cifras (Ciphers)
  - Constantes de versão
  - Constantes de indicação de nome do servidor
  - Outras constantes
- Parâmetros de chave/certificado
- Verificação de Certificado
- Funções de OpenSSL
  - openssl_cipher_iv_length — Obtém o comprimento do vetor de inicialização da cifra
  - openssl_cipher_key_length — Obtém o comprimento da chave da cifra
  - openssl_cms_decrypt — Descriptografa uma mensagem CMS
  - openssl_cms_encrypt — Criptografa uma mensagem CMS
  - openssl_cms_read — Exporta o arquivo CMS para um array de certificados PEM
  - openssl_cms_sign — Assina um arquivo
  - openssl_cms_verify — Verifica uma assinatura CMS
  - openssl_csr_export — Exporta um CSR como uma string
  - openssl_csr_export_to_file — Exporta um CSR para um arquivo
  - openssl_csr_get_public_key — Retorna a chave pública de um CSR
  - openssl_csr_get_subject — Retorna o assunto de um CSR
  - openssl_csr_new — Gera um CSR
  - openssl_csr_sign — Assina um CSR com outro certificado (ou ele mesmo) e gera um certificado
  - openssl_decrypt — Descritografa dados
  - openssl_dh_compute_key — Calcula o segredo compartilhado para o valor público da chave pública DH remota e da chave DH local
  - openssl_digest — Computa um resumo
  - openssl_encrypt — Criptografa dados
  - openssl_error_string — Retorna mensagem de erro do openSSL
  - openssl_free_key — Libera recurso de chave
  - openssl_get_cert_locations — Recupera os locais de certificados disponíveis
  - openssl_get_cipher_methods — Obtém métodos de criptografia disponíveis
  - openssl_get_curve_names — Obtém lista de nomes de curvas disponíveis para ECC
  - openssl_get_md_methods — Obtém métodos de resumo disponíveis
  - openssl_get_privatekey — Sinônimo de openssl_pkey_get_private
  - openssl_get_publickey — Sinônimo de openssl_pkey_get_public
  - openssl_open — Abre dados lacrados
  - openssl_password_hash — Cria um hash de senha usando a implementação Argon2 do OpenSSL
  - openssl_password_verify — Verifica uma senha em relação a um hash usando a implementação Argon2 do OpenSSL
  - openssl_pbkdf2 — Gera uma string PKCS5 v2 PBKDF2
  - openssl_pkcs12_export — Exporta um arquivo de armazenamento de certificados compatível com PKCS#12 para uma variável
  - openssl_pkcs12_export_to_file — Exporta um arquivo de armazenamento de certificados compatível com PKCS#12
  - openssl_pkcs12_read — Analisa um armazenamento de certificados PKCS#12 em um array
  - openssl_pkcs7_decrypt — Descriptografa uma mensagem criptografada S/MIME
  - openssl_pkcs7_encrypt — Criptografa uma mensagem S/MIME
  - openssl_pkcs7_read — Exporta o arquivo PKCS7 para um array de certificados PEM
  - openssl_pkcs7_sign — Assina uma mensagem S/MIME
  - openssl_pkcs7_verify — Verifica a assinatura de uma mensagem assinada por S/MIME
  - openssl_pkey_derive — Calcula o segredo compartilhado para o valor público da chave DH ou ECDH remota e local
  - openssl_pkey_export — Obtém uma representação exportável de uma chave em uma string
  - openssl_pkey_export_to_file — Obtém uma representação exportável de uma chave em um arquivo
  - openssl_pkey_free — Libera uma chave privada
  - openssl_pkey_get_details — Retorna um array com os detalhes da chave
  - openssl_pkey_get_private — Obtém uma chave privada
  - openssl_pkey_get_public — Extrai a chave pública do certificado e prepara-a para uso
  - openssl_pkey_new — Gera uma nova chave privada
  - openssl_private_decrypt — Descriptografa dados com chave privada
  - openssl_private_encrypt — Criptografa dados com chave privada
  - openssl_public_decrypt — Descriptografa dados com chave pública
  - openssl_public_encrypt — Criptografa dados com chave pública
  - openssl_random_pseudo_bytes — Gera uma sequência pseudo-aleatória de bytes
  - openssl_seal — Sela (criptografa) dados
  - openssl_sign — Gera assinatura
  - openssl_spki_export — Exporta uma chave pública assinada válida e formatada em PEM e um desafio
  - openssl_spki_export_challenge — Exporta o desafio associado a uma chave pública assinada e a um desafio
  - openssl_spki_new — Gera uma nova chave pública assinada e um desafio
  - openssl_spki_verify — Verifica uma chave pública assinada e um desafio
  - openssl_verify — Verifica assinatura
  - openssl_x509_check_private_key — Verifica se uma chave privada corresponde a um certificado
  - openssl_x509_checkpurpose — Verifica se um certificado pode ser usado para uma finalidade específica
  - openssl_x509_export — Exporta um certificado como uma string
  - openssl_x509_export_to_file — Exporta um certificado para arquivo
  - openssl_x509_fingerprint — Calcula a impressão digital, ou resumo, de um determinado certificado X.509
  - openssl_x509_free — Libera recurso de certificado
  - openssl_x509_parse — Analisa um certificado X509 e retorna as informações como um array
  - openssl_x509_read — Analisa um certificado X.509 e retorna um objeto para ele
  - openssl_x509_verify — Verifica a assinatura digital do certificado x509 em relação a uma chave pública
- OpenSSLCertificate — A classe OpenSSLCertificate
- OpenSSLCertificateSigningRequest — A classe OpenSSLCertificateSigningRequest
- OpenSSLAsymmetricKey — A classe OpenSSLAsymmetricKey

# Hash de Senhas

# Introdução

A API de hash de senhas fornece uma interface em torno de crypt() de fácil utilização e alguns outros algoritmos de hash de senha, para facilitar a criação e o gerenciamento de senhas de forma segura.

# Instalação/Configuração

## Índice

- Dependências
- Instalação

## Dependências

Nenhuma biblioteca externa é necessária para compilar esta extensão.

Para o hash de senha Argon2, é necessário o uso do » libargon2 ou, a partir do PHP 8.4.0, OpenSSL versão 3.2 ou superior. A partir do PHP 7.3.0, é necessário ter a versão 20161029 ou posterior do libargon2.

## Instalação

Nenhuma instalação é necessária para usar estas funções; elas fazem parte do núcleo do PHP.

No entanto, para habilitar o hash de senha Argon2, o PHP deve ser compilado com suporte ao libargon2 utilizando a opção de configuração --with-password-argon2 ou a partir do PHP 8.4.0, com o OpenSSL usando --with-openssl e --with-openssl-argon2.

Antes do PHP 8.1.0, era possível especificar o diretório argon2 com --with-password-argon2[=DIR].

# Constantes predefinidas

As constantes abaixo estão sempre disponíveis como parte do núcleo do PHP.

`PASSWORD_BCRYPT` (string)

  `PASSWORD_BCRYPT` é usada para criar novas hashes de senha usando o algoritmo `CRYPT_BLOWFISH`.

  Sempre terminará com um hash usando o formato de criptografia "$2y$", com 60 caracteres.

  Opções suportadas:

  - `salt` (string) - para fornecer manualmente um salt que será usado ao fazer o hash da senha. Observe que isso irá substituir e evitar que um salt seja gerado automaticamente.

    Se omitido, um salt aleatório será gerado pela função password_hash() para cada senha sofrendo hash. Esse é o modo de operação desejado e a partir do PHP 7.0.0 a opção salt foi descontinuada.

  - `cost` (int) - indica o custo de algoritmo que deve ser usado. Exemplos desses valores podem ser encontrados na página da função crypt().

    Se omitido, um valor padrão de `12` será usado. Esta é uma boa base de custo, mas pode-se considerar aumentar esse valor dependendo do equipamento.

`PASSWORD_BCRYPT_DEFAULT_COST` (int)

`PASSWORD_ARGON2I` (string)

  `PASSWORD_ARGON2I` é utilizado para criar novos hashes utilizando o algoritmo Argon2i.

  Opções:

  - `memory_cost` (int) - Memória máxima (em bytes) que poderá ser utilizada para calcular o hash Argon2. Padrão: `PASSWORD_ARGON2_DEFAULT_MEMORY_COST`.

  - `time_cost` (int) - Tempo máximo que poderá demorar para calcula o hash Argon2. Padrão: `PASSWORD_ARGON2_DEFAULT_TIME_COST`.

  - `threads` (int) - Número de threads utilizada para calcular o hash Argon2. Padrão: `PASSWORD_ARGON2_DEFAULT_THREADS`. Somente disponível com libargon2, mas não na implementação libsodium.

  Disponível a partir do PHP 7.2.0.

`PASSWORD_ARGON2ID` (string)

  `PASSWORD_ARGON2ID` é utilizado para criar novos hashes de senha com o algoritmo Argon2id. Ele suporta as mesmas opções de `PASSWORD_ARGON2I`.

  Disponível a partir do PHP 7.3.0.

`PASSWORD_ARGON2_DEFAULT_MEMORY_COST` (int)

  Quantidade de memória padrão, em bytes, que será utilizado ao tentar calcular um hash.

  Disponível a partir do PHP 7.2.0.

`PASSWORD_ARGON2_DEFAULT_TIME_COST` (int)

  Quantidade de tempo padrão que será gasto tentando calcular um hash.

  Disponível a partir do PHP 7.2.0.

`PASSWORD_ARGON2_DEFAULT_THREADS` (int)

  Número de threads padrão qual a Argon2lib irá utilizar. Não disponível na implementação libsodium.

  Disponível a partir do PHP 7.2.0.

`PASSWORD_ARGON2_PROVIDER` (string)

  Disponível a partir do PHP 7.4.0.

`PASSWORD_DEFAULT` (string)

  O algoritmo padrão a ser usado para fazer o hash se nenhum algoritmo for fornecido. Ele pode mudar com as novas versões do PHP quando algoritmos de hash novos e mais fortes forem suportados.

  É importante notar que ao longo do tempo essa constante pode mudar. Assim sendo, deve-se estar ciente que o comprimento do hash resultante pode mudar. Portanto, ao usar `PASSWORD_DEFAULT`, o hash resultante deve ser armazanado de uma forma que possa armazenar hashes arbitrários, o comprimento recomendado é de `255` bytes.

  Atualmente é um sinônimo de `PASSWORD_BCRYPT`.

##### Registro de Alterações

Versão | Descrição
--- | ---
7.4.0 | Os valores informados como IDs de algoritimo (`PASSWORD_BCRYPT`, `PASSWORD_ARGON2I`, `PASSWORD_ARGON2ID` e `PASSWORD_DEFAULT`) agora são do tipo string. Anteriormente eles eram do tipo int.

# Funções da extensão Password Hashing

# password_algos

(PHP 7 >= 7.4.0, PHP 8)

password_algos — Obtém IDs de algoritmos disponíveis de hash de senhas

### Descrição

function password_algos(): array

Retorna uma lista completa de todos os IDs de algoritmos registrados de hash de senhas como um array de strings.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna os IDs de algoritmos disponíveis de hash de senhas.

### Exemplos

Exemplo #1 Uso básico de password_algos()

    <?php
    print_r(password_algos());
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => 2y
        [1] => argon2i
        [2] => argon2id
    )

# password_get_info

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_get_info — Retorna a informações sobre o hash fornecido

### Descrição

function password_get_info(string `$hash`): array

Quando for fornecido um hash válido criado por um algoritmo suportado pela função password_hash(), esta função retornará um array com as informações sobre esse hash.

### Parâmetros

`hash`

  Um hash criado por password_hash().

### Valor Retornado

Retorna um array associativo com três elementos:

- `algo`, que corresponderá a uma constante de algoritmo de senha
- `algoName`, que terá o nome legível do algoritmo
- `options`, que inclui as opções fornecidas ao se chamar a função password_hash()

# password_hash

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_hash — Cria um hash de senha

### Descrição

function password_hash(#[\SensitiveParameter]string `$password`, string|int|null `$algo`, array `$options` = []): string

password_hash() cria um novo hash de senha usando um algoritmo forte de hash de mão única.

Os seguintes algoritmos são suportados atualmente:

- `PASSWORD_DEFAULT` - Usa o algoritmo bcrypt (padrão desde o PHP 5.5.0). Perceba que essa constante foi desenhada para mudar ao longo do tempo a medida que novos algoritmos mais fortes forem adicionados ao PHP. Por essa razão, o comprimento do resultado da utilização desse identificador pode mudar ao longo do tempo. Por isso, é recomendado que armazene o resultado em uma coluna do banco de dados que possa ser expandida além dos 60 bytes (255 bytes seria uma boa escolha).
- `PASSWORD_BCRYPT` - Usa o algoritmo bcrypt para criar o hash. Produzirá um hash compatível com o padrão crypt() usando o identificador `$2y$`.
- `PASSWORD_ARGON2I` - Usa o algoritmo Argon2i para criar o hash. Este algoritmo somente estará disponível se o PHP tiver sido compilado com suporte a Argon2.
- `PASSWORD_ARGON2ID` - Usa o algoritmo Argon2id para criar o hash. Este algoritmo somente estará disponível se o PHP tiver sido compilado com suporte a Argon2.

Opções suportadas por `PASSWORD_BCRYPT`:

- `salt` (string) - para fornecer manualmente um salt a ser usado quando estiver sendo feito o hash da senha. Perceba que isso irá sobrepor e evitar que um salt seja gerado automaticamente.

  Se omitido, um salt aleatório será gerado pela função password_hash() para cada senha sofrendo hash. Esse é o modo de operação desejado.

  Aviso

  A opção salt foi descontinuada. Agora é preferível que simplesmente se utilize o salt que é gerado por padrão. A partir do PHP 8.0.0, um salt fornecido explicitamente será ignorado.

- `cost` (int) - indica o custo de algoritmo que deve ser usado. Exemplos desses valores podem ser encontrados na página da função crypt().

  Se omitido, um valor padrão `12` será usado. Este é um bom patamar de custo, mas deve ser ajustado dependendo do equipamento em uso.

Opções suportadas por `PASSWORD_ARGON2I` e `PASSWORD_ARGON2ID`:

- `memory_cost` (int) - Máximo de mémoria (em kibibytes) que pode ser utilizado para computar o hash Argon2. O valor padrão é `PASSWORD_ARGON2_DEFAULT_MEMORY_COST`.

- `time_cost` (int) - Quantidade máxima de tempo que pode levar para computar o hash Argon2. O valor padrão é `PASSWORD_ARGON2_DEFAULT_TIME_COST`.

- `threads` (int) - Número de threads para computar o hash Argon2. O valor padrão é `PASSWORD_ARGON2_DEFAULT_THREADS`.

  Aviso

  Disponível somente quando o PHP usa a libargon2, e não com a implementação libsodium.

### Parâmetros

`password`

  A senha do usuário.

  Cuidado

  Usando `PASSWORD_BCRYPT` como algoritmo, resultará no parâmetro `password` sendo truncado em um comprimento máximo de 72 bytes.

`algo`

  Uma constante de algoritmo de senha denotando o algoritmo a ser usado ao fazer o hash da senha.

`options`

  Um array associativo contendo opções. Consulte as constantes de algoritmo de senha para obter a documentação sobre as opções suportadas por cada algoritmo.

### Valor Retornado

Retorna o hash da senha.

O algoritmo, o custo e o salt utilizados são retornados como parte do hash. Dessa forma, toda informação necessária para verificar o hash é incluída nele. Isso permite que a função password_verify() verifique o hash sem precisar de um armazenamento separado para a informação do salt ou do algoritmo.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | O valor padrão da opção `cost` do algoritmo `PASSWORD_BCRYPT` foi aumentado de `10` para `12`.
8.3.0 | password_hash() agora define a exceção Random\RandomException subjacente como a Exception::$previous quando uma exceção ValueError é lançada devido a uma falha na geração do salt.
8.0.0 | password_hash() não mais retorna `false` em caso de falha, em vez disso uma exceção ValueError será lançada se o algoritmo de hash da senha não for válido, ou uma exceção Error se o cálculo do hash falhou por motivo desconhecido.
8.0.0 | O parâmetros `algo` agora pode ser nulo.
7.4.0 | O parâmetro `algo` agora espera uma string, mas ainda aceita ints para compatibilidade com versões anteriores.
7.4.0 | A extensão sodium fornece uma implementação alternativa para senhas Argon2.
7.3.0 | Suporte para senhas Argon2id usando `PASSWORD_ARGON2ID` foi adicionado.
7.2.0 | Suporte para senhas Argon2i usando `PASSWORD_ARGON2I` foi adicionado.

### Exemplos

Exemplo #1 Exemplo de password_hash()

    <?php
    echo password_hash("rasmuslerdorf", PASSWORD_DEFAULT);
    ?>

O exemplo acima produzirá algo semelhante a:

    $2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.

Exemplo #2 Exemplo de configuração do custo de password_hash() manualmente

    <?php
    $options = [
        // Aumenta o custo bcrypt de 12 para 13.
        'cost' => 13,
    ];
    echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options);
    ?>

O exemplo acima produzirá algo semelhante a:

    $2y$13$xeDfQumlmdm0Sco.4qmH1OGfUUmOcuRmfae0dPJhjX1Bq0yYhqbNi

Exemplo #3 Exemplo de busca de um bom custo para password_hash()

Este código fará um benchmark da máquina para determinar o quão alto um custo pode ser usado sem deteriorar a experiência do usuário. É recomendado definir o custo mais alto que não desacelere outras operações que a máquina precisa executar. 11 é uma boa linha de base, e mais é melhor se a máquina for rápida o suficiente. O código abaixo visa um tempo de alongamento ≤ 350 milissegundos, que é um atraso apropriado para sistemas que lidam com logins interativos.

    <?php
    $timeTarget = 0.350; // 350 milissegundos

    $cost = 11;
    do {
        $cost++;
        $start = microtime(true);
        password_hash("test", PASSWORD_BCRYPT, ["cost" => $cost]);
        $end = microtime(true);
    } while (($end - $start) < $timeTarget);

    echo "Custo Apropriado Encontrado: " . $cost - 1;
    ?>

O exemplo acima produzirá algo semelhante a:

    Custo Apropriado Encontrado: 13

Exemplo #4 Exemplo de password_hash() usando Argon2i

    <?php
    echo 'Argon2i hash: ' . password_hash('rasmuslerdorf', PASSWORD_ARGON2I);
    ?>

O exemplo acima produzirá algo semelhante a:

    Argon2i hash: $argon2i$v=19$m=1024,t=2,p=2$YzJBSzV4TUhkMzc3d3laeg$zqU/1IN0/AogfP4cmSJI1vc8lpXRW9/S0sYY2i2jHT0

### Notas

Cuidado

É fortemente recomendado não fornecer um salt explícito para esta função. Ela criará um salt seguro automaticamente se um não for especificado.

Como apontado acima, fornecer a opção `salt` no PHP 7.0.0 gerará um alerta de descontinuação. O suporte para fornecer um salt explicitamente foi removido no PHP 8.0.

> Nota:

> É recomendado testar esta função na máquina usada, ajustando o parâmetro custo para que a execução da função leve menos do que 350 milissegundos em sistemas interativos. O script do exemplo acima ajudará a escolher um custo bcrypt apropriado para uma determinada máquina.

> Nota: Atualizações dos algoritmos suportados por esta função (ou alterações no algoritmo padrão) precisam seguir as seguintes regras:

> - Qualquer novo algoritmo precisa estar no core por pelo menos 1 versão completa do PHP antes de se tornar padrão. Assim se, por exemplo, um novo algoritmo for adicionado na versão 7.5.5, ela não seria elegível para padrão até a versão 7.7 (uma vez que a 7.6 seria a primeira versão completa). Mas se um algoritmo diferente for adicionado na versão 7.6.0, ela seria elegível para padrão na 7.7.0.
> - O padrão deve mudar apenas em uma versão completa (7.3.0, 8.0.8 etc.) e não em uma versão de revisão. A única exceção seria uma emergênca caso uma falha de segurança crítica fosse encontrada no padrão atual.

### Veja Também

- password_verify() - Verifica se uma senha corresponde a um hash
- password_needs_rehash() - Verifica se o hash informado corresponde às opções especificadas
- crypt() - Hash unidirecional de string
- sodium_crypto_pwhash_str() - Obtém um hash codificado em ASCII

# password_needs_rehash

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_needs_rehash — Verifica se o hash informado corresponde às opções especificadas

### Descrição

function password_needs_rehash(string `$hash`, string|int|null `$algo`, array `$options` = []): bool

Esta função verifica se o hash fornecido implementa o algoritmo e as opções indicadas. Se não, ela assume que o hash precisa ser recalculado.

### Parâmetros

`hash`

  Um hash criado por password_hash().

`algo`

  Uma constante de algoritmo de senha denotando o algoritmo a ser usado ao fazer o hash da senha.

`options`

  Um array associativo contendo opções. Consulte as constantes de algoritmo de senha para obter a documentação sobre as opções suportadas por cada algoritmo.

### Valor Retornado

Retorna `true` se o hash deve ser recalculado para corresponder ao algortimo informado em `algo` e às opções em `options`, ou `false` caso contrário.

### Registro de Alterações

Versão | Descrição
--- | ---
7.4.0 | O parâmetro `algo` agora espera uma string, mas ainda aceita ints para compatibilidade com versões anteriores.

### Exemplos

Exemplo #1 Utilização de password_needs_rehash()

    <?php

    $password = 'rasmuslerdorf';
    $hash = '$2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.';

    $algorithm = PASSWORD_BCRYPT;
    // o parâmetro de custo de bcrypt pode mudar com o tempo com a evloução dos equipamentos
    $options = ['cost' => 13];

    // Verifica o hash armazenado comparando com uma senha em texto puro
    if (password_verify($password, $hash)) {
        // Verifica se o algoritmo ou o custo mudaram
        if (password_needs_rehash($hash, $algorithm, $options)) {
            // Caso positivo, cria um hash novo, e substitui o antigo
            $newHash = password_hash($password, $algorithm, $options);

            // Atualiza o registro do usuário com $newHash
        }

        // Faz login
    }
    ?>

# password_verify

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_verify — Verifica se uma senha corresponde a um hash

### Descrição

function password_verify(#[\SensitiveParameter]string `$password`, string `$hash`): bool

Verifica se o hash fornecido corresponde à senha informada password_verify() é compatível com crypt(). Portanto, hashes de senha criadas por crypt() podem ser usados com password_verify().

Perceba que password_hash() retorna o algoritmo, custo e o salt como parte do hash retornado. Por isso, toda a informação necessária para verificar o hash está incluída nele. Isso permite que a função de verificação faça isso sem precisar de um armazenamento separado para a informação do salt ou do algoritmo.

Esta função é segura contra ataques de sincronismo.

### Parâmetros

`password`

  A senha do usuário.

`hash`

  Um hash criado por password_hash().

### Valor Retornado

Retorna `true` se o password e o hash corresponderem, ou `false` caso contrário.

### Exemplos

Exemplo #1 Exemplo de password_verify()

Este é um exemplo simplificado; é recomendável recalcular o hash de uma senha correta se necessário; consulte a página da função password_needs_rehash() para um exemplo.

    <?php
    // Veja o exemplo de password_hash() para ver de onde veio esta string.
    $hash = '$2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.';

    if (password_verify('rasmuslerdorf', $hash)) {
        echo 'Senha válida!';
    } else {
        echo 'Senha inválida';
    }
    ?>

O exemplo acima produzirá:

    Senha válida!

### Veja Também

- password_needs_rehash() - Verifica se o hash informado corresponde às opções especificadas
- password_hash() - Cria um hash de senha
- sodium_crypto_pwhash_str_verify() - Verifica se uma senha corresponde a um hash

## Índice

- password_algos — Obtém IDs de algoritmos disponíveis de hash de senhas
- password_get_info — Retorna a informações sobre o hash fornecido
- password_hash — Cria um hash de senha
- password_needs_rehash — Verifica se o hash informado corresponde às opções especificadas
- password_verify — Verifica se uma senha corresponde a um hash

- Instalação/Configuração
  - Dependências
  - Instalação
- Constantes predefinidas
- Funções da extensão Password Hashing
  - password_algos — Obtém IDs de algoritmos disponíveis de hash de senhas
  - password_get_info — Retorna a informações sobre o hash fornecido
  - password_hash — Cria um hash de senha
  - password_needs_rehash — Verifica se o hash informado corresponde às opções especificadas
  - password_verify — Verifica se uma senha corresponde a um hash

# Rnp

# Introdução

Aviso

Esta extensão é EXPERIMENTAL. O comportamento desta extensão, incluindo os nomes de suas funções e qualquer outra documentação relacionada a esta extensão, pode mudar sem aviso prévio em futuras versões do PHP. Use por sua conta e risco.

Este módulo permite usar a biblioteca » RNP. RNP é uma biblioteca OpenPGP em C++ de alto desempanho usada pelo Mozilla Thunderbird.

# Instalação/Configuração

## Índice

- Dependências
- Instalação

## Dependências

Para usar as funções RNP é necessário instalar a biblioteca » RNP. Versão >= 0.16.2 da biblioteca é requerida.

## Instalação

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/rnp

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`RNP_KEYSTORE_GPG` (string)
  Formato de armazenamento de chave "GPG".
`RNP_KEYSTORE_KBX` (string)
  Formato de armazenamento de chave "KBX". Somente para chaves públicas. Uma caixa de chaves é um formato usado para armazenar chaves públicas junto com metainformação e índices.
`RNP_KEYSTORE_G10` (string)
  Formato de armazenamento de chave "G10". Para chaves privadas.
`RNP_LOAD_SAVE_PUBLIC_KEYS` (integer)
  Carrega ou salva apenas chaves públicas. Pode ser feito OR com `RNP_LOAD_SAVE_SECRET_KEYS` para carregar chaves públicas e privadas no contexto FFI ou salvá-las a partir do contexto.
`RNP_LOAD_SAVE_SECRET_KEYS` (integer)
  Carrega ou salva apenas chaves secretas. Pode ser feito OR com `RNP_LOAD_SAVE_PUBLIC_KEYS` para carregar chaves públicas e privadas no contexto FFI ou salvá-las a partir do contexto.
`RNP_LOAD_SAVE_PERMISSIVE` (integer)
  Permite ignorar pacotes de assinatura/chave/subchave incorretos durante a importação de chaves.
`RNP_LOAD_SAVE_SINGLE` (integer)
  Se definida, apenas a primeira chave será carregada.
`RNP_LOAD_SAVE_BASE64` (integer)
  Permitir a importação de chaves codificadas em base64 (autocriptografadas).
`RNP_FEATURE_SYMM_ALG` (string)
  Lista os algoritmos de criptografia simétrica disponíveis.
`RNP_FEATURE_AEAD_ALG` (string)
  Lista os algoritmos AEAD disponíveis.
`RNP_FEATURE_PROT_MODE` (string)
  Lista os modos de proteção disponíveis.
`RNP_FEATURE_PK_ALG` (string)
  Lista os algoritmos de chave pública disponíveis.
`RNP_FEATURE_HASH_ALG` (string)
  Lista os algoritmos de hash disponíveis.
`RNP_FEATURE_COMP_ALG` (string)
  Lista os algoritmos de compactação disponíveis.
`RNP_FEATURE_CURVE` (string)
  Lista as curvas elípticas disponíveis.
`RNP_DUMP_MPI` (integer)
  Despeja valores MPI (número inteiro de multiprecisão).
`RNP_DUMP_RAW` (integer)
  Despeja também o conteúdo bruto do pacote.
`RNP_DUMP_GRIP` (integer)
  Despeja impressões digitais de chaves e grips de chaves.
`RNP_JSON_DUMP_MPI` (integer)
  Despeja valores MPI (número inteiro de multiprecisão) em JSON.
`RNP_JSON_DUMP_RAW` (integer)
  Despeja também o conteúdo bruto do pacote em JSON.
`RNP_JSON_DUMP_GRIP` (integer)
  Despeja impressões digitais de chaves e grips de chaves em JSON.
`RNP_ENCRYPT_NOWRAP` (integer)
  Permite criptografia de mensagem assinada. A mensagem não está encapsulada em um pacote de dados literal.
`RNP_KEY_EXPORT_ARMORED` (integer)
  Habilita a blindagem ASCII dos dados exportados.
`RNP_KEY_EXPORT_PUBLIC` (integer)
  Exporta chave pública.
`RNP_KEY_EXPORT_SECRET` (integer)
  Exporta chave secreta.
`RNP_KEY_EXPORT_SUBKEYS` (integer)
  Se a chave primária estiver sendo exportada, todas as subchaves também serão exportadas.
`RNP_KEY_EXPORT_BASE64` (integer)
  Exporta a chave de criptografia automática codificada em base64 em vez de binária.
`RNP_KEY_REMOVE_PUBLIC` (integer)
  Remove a chave pública.
`RNP_KEY_REMOVE_SECRET` (integer)
  Remove a chave secreta.
`RNP_KEY_REMOVE_SUBKEYS` (integer)
  Se a chave primária estiver sendo excluída, todas as suas subchaves também serão removidas.

# Exemplos

## Índice

- Texto Clearsign

## Texto Clearsign

Este exemplo faz assinatura clearsign em um texto.

Exemplo #1 Exemplo de clearsign RNP

    <?php
    // inicializa objeto FFI
    $ffi = rnp_ffi_create('GPG', 'GPG');

    // gera chave RSA
    $key = rnp_op_generate_key($ffi, 'test@example.com', 'RSA');

    // assina
    $data = "Texto de exemplo para assinar";
    $signature = rnp_op_sign_cleartext($ffi, $data, array($key));

    echo $signature;

    // destrói o objeto FFI
    rnp_ffi_destroy($ffi);
    ?>

# Funções de Rnp

# rnp_backend_string

(PECL rnp >= 0.1.1)

rnp_backend_string — Retorna o nome da biblioteca de back-end criptográfico

### Descrição

function rnp_backend_string(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

String de nome de back-end. Os backends atualmente suportados são "Botan" e "OpenSSL".

# rnp_backend_version

(PECL rnp >= 0.1.1)

rnp_backend_version — Retorna a versão da biblioteca de back-end criptográfico

### Descrição

function rnp_backend_version(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

String de versão.

# rnp_decrypt

(PECL rnp >= 0.1.1)

rnp_decrypt — Descriptografa mensagem PGP

### Descrição

function rnp_decrypt(RnpFFI `$ffi`, string `$input`): string|false

As chaves privadas usadas para descriptografia devem ser carregadas no objeto FFI antes de chamar esta função. Se a criptografia de senha tiver sido usada, o provedor de senha deverá ser definido chamando rnp_ffi_set_pass_provider().

### Parâmetros

`ffi`
  O objeto FFI retornado por rnp_ffi_create().
`input`
  Mensagem criptografada.

### Valor Retornado

Mensagem descriptografada em caso de sucesso ou `false` em caso de falha.

# rnp_dump_packets

(PECL rnp >= 0.1.1)

rnp_dump_packets — Despeja informação de fluxo de pacotes OpenPGP em formato legível

### Descrição

function rnp_dump_packets(string `$input`, int `$flags`): string|false

### Parâmetros

`input`
  String de entrada contendo dados OpenPGP, em formato binário ou blindado ASCII.
`flags`
  Consulte as constantes predefinidas `RNP_DUMP_*`.

### Valor Retornado

Texto descrevendo a sequência de pacotes ou `false` em caso de falha.

# rnp_dump_packets_to_json

(PECL rnp >= 0.1.1)

rnp_dump_packets_to_json — Despejar informações de fluxo de pacotes OpenPGP para a string JSON

### Descrição

function rnp_dump_packets_to_json(string `$input`, int `$flags`): string|false

### Parâmetros

`input`
  String de entrada contendo dados OpenPGP, em formato binário ou blindado ASCII.
`flags`
  Consulte as constantes predefinidas `RNP_JSON_DUMP_*`.

### Valor Retornado

String JSON com dados despejados ou `false` em caso de falha.

# rnp_ffi_create

(PECL rnp >= 0.1.1)

rnp_ffi_create — Cria o objeto de nível superior usado para interagir com a biblioteca

### Descrição

function rnp_ffi_create(string `$pub_format`, string `$sec_format`): RnpFFI|false

### Parâmetros

`pub_format`
  O formato do chaveiro público, RNP_KEYSTORE_GPG ou outra constante RNP_KEYSTORE_*.
`sec_format`
  O formato do chaveiro secreto, RNP_KEYSTORE_GPG ou outra constante RNP_KEYSTORE_*.

### Valor Retornado

Retorna um objeto RnpFFI em caso de sucesso ou `false` em caso de falha.

# rnp_ffi_destroy

(PECL rnp >= 0.1.1)

rnp_ffi_destroy — Destrói o objeto de nível superior usado para interagir com a biblioteca

### Descrição

function rnp_ffi_destroy(RnpFFI `$ffi`): void

### Parâmetros

`ffi`
  O objeto FFI retornado por rnp_ffi_create().

### Valor Retornado

# rnp_ffi_set_pass_provider

(PECL rnp >= 0.1.1)

rnp_ffi_set_pass_provider — Definir função de retorno do provedor de senha

### Descrição

function rnp_ffi_set_pass_provider(RnpFFI `$ffi`, callable `$password_callback`): bool

Define a função do provedor de senha. Esta função pode solicitar a senha em uma entrada padrão (se o script PHP for executado em um ambiente de linha de comando), exibir a caixa de diálogo da interface gráfica ou fornecer a senha de qualquer outra maneira possível. As senhas solicitadas são usadas para criptografar ou descriptografar chaves secretas ou realizar operações simétricas de criptografia/descriptografia.

### Parâmetros

`ffi`
  O objeto FFI retornado por rnp_ffi_create().
`password_callback`

  A função que deve ser chamada para cada solicitação de senha. Possui a seguinte assinatura:

  function password_callback(string `$key_fp`, string `$pgp_context`, string `&$password`): bool
  - `$key_fp` - A impressão digital da chave, se houver. Pode ser vazio.
  - `$pgp_context` - String que descreve por que a chave está sendo solicitada.
  - `$password` - Variável de referência onde a senha fornecida deve ser armazenada como string.
  A função de retorno deve retornar `true` se a senha foi definida com sucesso ou `false` em caso de falha.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 exemplo de função de retorno simples

    <?php
    function password_callback(string $key_fp, string $pgp_context, string &$password)
    {
        $password = "password";

        return true;
    }

    $ffi = rnp_ffi_create('GPG', 'GPG');

    rnp_ffi_set_pass_provider($ffi, 'password_callback');

# rnp_import_keys

(PECL rnp >= 0.1.1)

rnp_import_keys — Importa chaves da string PHP para o chaveiro e recebe JSON descrevendo chaves novas/atualizadas

### Descrição

function rnp_import_keys(RnpFFI `$ffi`, string `$input`, int `$flags`): string|false

### Parâmetros

`ffi`
  O objeto FFI retornado por rnp_ffi_create().
`input`
  Pacotes OpenPGP contendo chaves a serem carregadas. Pode ser binário ou blindado ASCII.
`flags`
  Consulte as constantes predefinidas`RNP_LOAD_SAVE_*`.

### Valor Retornado

String JSON com informações sobre chaves novas e atualizadas em caso de sucesso ou `false` em caso de falha.

# rnp_import_signatures

(PECL rnp >= 0.1.1)

rnp_import_signatures — Importa assinaturas independentes para o chaveiro e recebe JSON descrevendo chaves atualizadas

### Descrição

function rnp_import_signatures(RnpFFI `$ffi`, string `$input`, int `$flags`): string|false

### Parâmetros

`ffi`
  O objeto FFI retornado por rnp_ffi_create().
`input`
  Pacotes OpenPGP contendo assinaturas a serem importadas. Pode ser binário ou blindado ASCII.
`flags`
  Atualmente precisar ser 0.

### Valor Retornado

String JSON com informações sobre chaves atualizadas em caso de sucesso ou `false` em caso de falha.

# rnp_key_export

(PECL rnp >= 0.1.1)

rnp_key_export — Exporta uma chave

### Descrição

function rnp_key_export(RnpFFI `$ffi`, string `$key_fp`, int `$flags`): string|false

### Parâmetros

`ffi`
  O objeto FFI retornado por rnp_ffi_create().
`key_fp`
  Impressão digital da chave.
`flags`
  Consulta as constantes predefinidas `RNP_KEY_EXPORT_*` (exceto `RNP_KEY_EXPORT_BASE64`).

### Valor Retornado

Pacotes OpenPGP de chaves exportadas (binárias ou ASCII blindada) em caso de sucesso ou `false` em caso de falha.

# rnp_key_export_autocrypt

(PECL rnp >= 0.1.1)

rnp_key_export_autocrypt — Exporte o mínimo de chaves para o recurso de criptografia automática (apenas 5 pacotes: chave, uid, assinatura, subchave de criptografia, assinatura)

### Descrição

function rnp_key_export_autocrypt(
RnpFFI `$ffi`,
string `$key_fp`,
string `$subkey_fp`,
string `$uid`,
int `$flags`
): string|false

### Parâmetros

`ffi`
  O objeto FFI retornado por rnp_ffi_create().
`key_fp`
  Impressão digital da chave primária.
`subkey_fp`
  Subchave para exportar. Pode ser uma string vazia para selecionar a primeira subchave adequada.
`uid`
  ID do usuário a ser exportado. Pode ser uma string vazia se a chave exportada tiver apenas um uid.
`flags`
  Apenas `RNP_KEY_EXPORT_BASE64` é suportada atualmente. Ativá-la exportaria dados de chave codificados em base64 em vez de binários.

### Valor Retornado

Pacotes OpenPGP de chave exportada em caso de sucesso ou `false` em caso de falha.

# rnp_key_export_revocation

(PECL rnp >= 0.1.1)

rnp_key_export_revocation — Gera e exporta assinatura de revogação de chave primária

### Descrição

function rnp_key_export_revocation(
RnpFFI `$ffi`,
string `$key_fp`,
int `$flags`,
array `$options` = ?
): string|false

Nota: para revogar uma chave é preciso importar esta assinatura para o armazenamento de chaves ou usar a função rnp_key_revoke().

### Parâmetros

`ffi`
  O objeto FFI retornado por rnp_ffi_create().
`key_fp`
  Impressão digital da chave primária a ser revogada.
`flags`
  `RNP_KEY_EXPORT_ARMORED` ou 0.
`options`
  Um array associativo com opções.

  Chave | Tipo de dado | Descrição
  --- | --- | ---
  `"hash"` | string | Define o algoritmo de hash usado durante cálculo da assinatura.
  `"code"` | string | Código do motivo da revogação. Valores possíveis são: 'no' (não), 'superseded' (substituída), 'compromised' (comprometida) e 'retired' (aposentada). Se não definida, o valor 'no' será usado por padrão.
  `"reason"` | string | Representação textual do motivo da revogação.

### Valor Retornado

Assinatura de revogação exportada em caso de sucesso ou `false` em caso de falha.

# rnp_key_get_info

(PECL rnp >= 0.1.1)

rnp_key_get_info — Obtém informação sobre a chave

### Descrição

function rnp_key_get_info(RnpFFI `$ffi`, string `$key_fp`): array|false

### Parâmetros

`ffi`
  O objeto FFI retornado por rnp_ffi_create().
`key_fp`
  Impressão digital da chave.

### Valor Retornado

Um array associativo com informação sobre a chave ou `false` em caso de falha.

Chave | Tipo de dado | Descrição
--- | --- | ---
`"is_primary"` | booleano | `true` se esta chave for a primária.
`"is_sub"` | booleano | `true` se esta chave for uma subchave.
`"is_valid"` | booleano | `true` se a chave pública for válida. Isto inclui verificações de auto-assinatura, tempo de expiração, revogação e assim por diante.
`"is_revoked"` | booleano | `true` se esta chave estiver revogada.
`"is_superseded"` | booleano | `true` se esta chave tiver sido substituída. Presente somente se a chave estiver revogada.
`"is_compromised"` | booleano | `true` se esta chave estiver comprometida. Presente somente se a chave estiver revogada.
`"is_retired"` | booleano | `true` se esta chave estiver aposentada. Presente somente se a chave estiver revogada.
`"is_expired"` | booleano | `true` se esta chave estiver expirada.
`"have_secret"` | booleano | `true` se esta chave tiver parte secreta.
`"is_locked"` | booleano | `true` se esta chave estiver atualmente bloqueada. Presente apenas para chaves secretas.
`"is_protected"` | booleano | `true` se esta chave estiver protegida. Presente apenas para chaves secretas. Uma chave protegida é aquela criptografada e que pode ser mantida com segurança na memória e bloquada/desbloqueada quando necessário.
`"have_public"` | booleano | `true` se esta chave tiver parte pública. Geralmente todas as chaves teriam uma parte pública.
`"valid_till"` | inteiro | O timestamp até o qual a chave pode ser considerada válida. Nota: isso levará em consideração não apenas a expiração da chave, mas também as revogações. Para a subchave, o tempo de validade da chave primária também será verificado.
`"bits"` | inteiro | Número de bits na chave. Para chaves baseadas em EC, conterá o tamanho da curva.
`"alg"` | string | Nome do algoritmo da chave.
`"subkeys"` | array | Um array indexado contendo sequências de impressões digitais de subchaves. Presente apenas para chaves primárias. Pode estar vazio se a chave primária não tiver subchaves.
`"uids"` | array | Um array indexado contendo strings de ID do usuário. Presente apenas para chaves primárias. Pode estar vazio se a chave primária não tiver IDs de usuário.

# rnp_key_remove

(PECL rnp >= 0.1.1)

rnp_key_remove — Remover uma chave de chaveiro(s)

### Descrição

function rnp_key_remove(RnpFFI `$ffi`, string `$key_fp`, int `$flags`): bool

Nota: é necessário chamar rnp_save_keys() para gravar o(s) chaveiro(s) atualizado(s).

### Parâmetros

`ffi`
  O objeto FFI retornado por rnp_ffi_create().
`key_fp`
  Impressão digital da chave.
`flags`
  Consulte as constantes `RNP_KEY_REMOVE_*`. A opção `RNP_KEY_REMOVE_SUBKEYS` funcionará somente para a chave primária e também removerá todas as suas subchaves.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# rnp_key_revoke

(PECL rnp >= 0.1.1)

rnp_key_revoke — Revogar uma chave ou subchave gerando e adicionando assinatura de revogação

### Descrição

function rnp_key_revoke(
RnpFFI `$ffi`,
string `$key_fp`,
int `$flags`,
array `$options` = ?
): bool

Nota: é necessário chamar rnp_save_keys() para gravar o(s) chaveiro(s) atualizado(s).

### Parâmetros

`ffi`
  O objeto FFI retornado por rnp_ffi_create().
`key_fp`
  Impressão digital da chave.
`flags`
  Atualmente precisa ser 0.
`options`
  Um array associativo com opções.

  Chave | Tipo de dado | Descrição
  --- | --- | ---
  `"hash"` | string | Define o algoritmo de hash usado durante cálculo da assinatura.
  `"code"` | string | Código do motivo da revogação. Valores possíveis são: 'no' (não), 'superseded' (substituída), 'compromised' (comprometida) e 'retired' (aposentada). Se não definida, o valor 'no' será usado por padrão.
  `"reason"` | string | Representação textual do motivo da revogação.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# rnp_list_keys

(PECL rnp >= 0.1.1)

rnp_list_keys — Enumera todas as chaves presentes em um chaveiro por tipo de identificador especificado

### Descrição

function rnp_list_keys(RnpFFI `$ffi`, string `$identifier_type`): array|false

### Parâmetros

`ffi`
  O objeto FFI retornado por rnp_ffi_create().
`identifier_type`
  Tipo de identificador de chave ("userid", "keyid", "grip", "fingerprint").

### Valor Retornado

Um array associativo onde a chave é uma string identificadora e o valor é uma impressão digital da chave PGP ou `false` em caso de falha.

# rnp_load_keys

(PECL rnp >= 0.1.1)

rnp_load_keys — Carrega chaves da string PHP

### Descrição

function rnp_load_keys(
RnpFFI `$ffi`,
string `$format`,
string `$input`,
int `$flags`
): bool

Observe que para G10 a entrada deve ser um diretório (que já deve existir).

### Parâmetros

`ffi`
  O objeto FFI retornado por rnp_ffi_create().
`format`
  O formato de chave dos dados (GPG, KBX, G10).
`input`
  Pacotes OpenPGP contendo chaves a serem carregadas. Pode ser binário ou blindado ASCII.
`flags`
  Consulte a descrição das opções `RNP_LOAD_SAVE_*`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# rnp_load_keys_from_path

(PECL rnp >= 0.1.1)

rnp_load_keys_from_path — Carrega chaves do caminho especificado

### Descrição

function rnp_load_keys_from_path(
RnpFFI `$ffi`,
string `$format`,
string `$input_path`,
int `$flags`
): bool

Observe que para G10 a entrada deve ser um diretório (que já deve existir).

### Parâmetros

`ffi`
  O objeto FFI retornado por rnp_ffi_create().
`format`
  O formato de chave dos dados (GPG, KBX, G10).
`input_path`
  Arquivo ou diretório contendo as chaves.
`flags`
  Consulte a descrição das opções `RNP_LOAD_SAVE_*`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# rnp_locate_key

(PECL rnp >= 0.1.1)

rnp_locate_key — Procura a chave

### Descrição

function rnp_locate_key(RnpFFI `$ffi`, string `$identifier_type`, string `$identifier`): string|false

Nota: apenas IDs de usuário válidos são verificados durante a pesquisa por ID de usuário.

### Parâmetros

`ffi`
  O objeto FFI retornado por rnp_ffi_create().
`identifier_type`
  String do tipo de identificador: "userid", "keyid", "fingerprint", "grip".
`identifier`
  ID de usuário PGP (nome e e-mail) para o tipo "userid", string hexadecimal que representa o ID da chave, impressão digital ou controle de chave.

### Valor Retornado

Retorna a impressão digital hexadecimal da chave encontrada em caso de sucesso ou `false` em caso de falha.

# rnp_op_encrypt

(PECL rnp >= 0.1.1)

rnp_op_encrypt — Criptografa mensagem

### Descrição

function rnp_op_encrypt(
RnpFFI `$ffi`,
string `$message`,
array `$recipient_keys_fp`,
array `$options` = ?
): string|false

### Parâmetros

`ffi`
  O objeto FFI retornado por rnp_ffi_create().
`message`
  Mensagem a ser criptografada.
`recipient_keys_fp`
  Array com impressões digitais das chaves do destinatário. Pelo menos uma chave deve estar presente.
`options`
  Um array associativo com opções.

  Chave | Tipo de dado | Descrição
  --- | --- | ---
  `"compression_alg"` | string | Algoritmo de compressão. Tanto `"compression_alg"` quanto `"compression_level"` precisam ser definidos para ativar a compactação de dados.
  `"compression_level"` | inteiro | Nível de compactação, 0-9. 0 desativa a compactação.
  `"armor"` | booleano | Habilita a saída blindada ASCII. Desativado por padrão.
  `"add_signature"` | booleano | A mensagem criptografada também será assinada.
  `"hash"` | string | Define o algoritmo hash usado durante o cálculo da assinatura. A opção "add_signature" deve ser definida como `true`
  `"creation_time"` | inteiro | Define o horário de criação da assinatura em segundos desde 1º de janeiro de 1970 UTC. Por padrão, o horário atual é usado.
  `"expiration_time"` | inteiro | Define o tempo de expiração da assinatura em segundos desde o momento da criação. O valor 0 é usado para marcar a assinatura como não expirante (valor padrão).
  `"password"` | string | Adiciona a senha que é usada para criptografar dados.
  `"cipher"` | string | Define o algoritmo de criptografia simétrica. Os valores possíveis são "IDEA", "TRIPLEDES", "CAST5", "BLOWFISH", "AES128", "AES192", "AES256", "TWOFISH", "CAMELLIA128", "CAMELLIA192", "CAMELLIA256" e "SM4" .
  `"aead"` | string | Define o algoritmo do modo AEAD. Os valores possíveis são "None" para desabilitar AEAD, "EAX" e "OCB".
  `"aead_bits"` | inteiro | Define o comprimento do bloco para o modo AEAD por meio do número de bits por bloco. Deve estar entre 0 e 56.
  `"flags"` | inteiro | Define opções de criptografia adicionais. Opções suportadas: RNP_ENCRYPT_NOWRAP - não encapsula os dados em um pacote de dados literal. Isso permitiria criptografar dados já assinados.
  `"file_name"` | string | Define o nome do arquivo armazenado internamente para os dados que estão sendo criptografados. O valor especial _CONSOLE pode ser usado para marcar a mensagem como 'somente para seus olhos', ou seja, ela não deve ser armazenada em qualquer lugar, mas apenas exibida para o receptor. O padrão é a string vazia.
  `"file_mtime"` | inteiro | Define a data de modificação do arquivo de entrada em segundos desde 1º de janeiro de 1970 UTC.

### Valor Retornado

Dados criptografados em caso de sucesso ou `false` em caso de falha.

# rnp_op_generate_key

(PECL rnp >= 0.1.1)

rnp_op_generate_key — Gera chave

### Descrição

function rnp_op_generate_key(
RnpFFI `$ffi`,
string `$userid`,
string `$key_alg`,
string `$sub_alg` = ?,
array `$options` = ?
): string|false

### Parâmetros

`ffi`
  O objeto FFI retornado por rnp_ffi_create().
`userid`
  ID de usuário PGP - texto cuja intenção é representar o nome e endereço de e-mail do titular da chave.
`key_alg`
  Algoritmo de chave primária (ou seja, 'RSA', 'DSA', etc).
`sub_alg`
  Algoritmo de subchave. Se não for definido, a subchave não será gerada.
`options`
  Um array associativo com opções.

  Chave | Tipo de dado | Descrição
  --- | --- | ---
  `"bits"` | inteiro | Tamanho da chave primária em bits. Aplicável apenas às chaves RSA, DSA e El-Gamal.
  `"hash"` | string | Algoritmo hash usado em autoassinatura ou assinatura de ligação de subchave.
  `"dsa_qbits"` | inteiro | Define o tamanho de um parâmetro `q` para a chave DSA. Nota: o valor padrão apropriado será definido, dependendo dos bits da chave. No entanto, ele pode ser substituído, se necessário.
  `"curve"` | string | Define a curva usada para a chave ECC. Nota: isto só é aplicável para chaves ECDSA, ECDH e SM2.
  `"request_password"` | booleano | Habilita a solicitação de senha por meio do provedor de senha. Esta senha será usada para criptografia de chave. A função de retorno do provedor de senha deve ser definida antecipadamente chamando rnp_ffi_set_pass_provider(). Nota: esta configuração será ignorada se a senha for definida via`"password"`
  `"password"` | string | Define a senha usada para criptografar os dados da chave secreta.
  `"expiration"` | inteiro | Define o tempo de expiração da chave e da subchave em segundos.
  `"sub_bits"` | inteiro | Tamanho da subchave em bits. Aplicável apenas às chaves RSA, DSA e El-Gamal.
  `"sub_hash"` | string | Algoritmo hash usado na autoassinatura de subchave ou assinatura de ligação de subchave.
  `"sub_curve"` | string | Define a curva usada para a subchave ECC. Nota: isto só é aplicável para chaves ECDSA, ECDH e SM2.

### Valor Retornado

Impressão digital da chave primária gerada ou `false` em caso de falha. Esta impressão digital pode ser usada posteriormente para fazer referência à chave em operações de assinatura e criptografia. Os dados da chave são armazenados no contexto da memória FFI e podem ser salvos usando rnp_save_keys() ou rnp_save_keys_to_path().

# rnp_op_sign

(PECL rnp >= 0.1.1)

rnp_op_sign — Executa operação de assinatura em dados binários, retornar assinatura(s) incorporada(s)

### Descrição

function rnp_op_sign(
RnpFFI `$ffi`,
string `$data`,
array `$keys_fp`,
array `$options` = ?
): string|false

### Parâmetros

`ffi`
  O objeto FFI retornado por rnp_ffi_create().
`data`
  Dados a serem assinados.
`keys_fp`
  Array com impressões digitais de chaves. Pelo menos uma chave deve ser fornecida. As chaves devem estar presentes no parâmetro `ffi`.
`options`
  Um array associativo com opções.

  Chave | Tipo de dado | Descrição
  --- | --- | ---
  `"compression_alg"` | string | Algoritmo de compressão. Tanto `"compression_alg"` quanto `"compression_level"` precisam ser definidos para ativar a compactação de dados.
  `"compression_level"` | inteiro | Nível de compactação, 0-9. 0 desativa a compactação.
  `"armor"` | booleano | Habilita a saída blindada ASCII. Desativado por padrão.
  `"hash"` | string | Define o algoritmo hash usado durante o cálculo da assinatura.
  `"creation_time"` | inteiro | Define o horário de criação da assinatura em segundos desde 1º de janeiro de 1970 UTC. Por padrão, o horário atual é usado.
  `"expiration_time"` | inteiro | Define o tempo de expiração da assinatura em segundos desde o momento da criação. O valor 0 é usado para marcar a assinatura como não expirante (valor padrão).
  `"file_name"` | string | Define o nome do arquivo de entrada. O valor especial _CONSOLE pode ser usado para marcar a mensagem como 'somente para seus olhos', ou seja, ela não deve ser armazenada em qualquer lugar, mas apenas exibida para o receptor. O padrão é a string vazia.
  `"file_mtime"` | inteiro | Define a data de modificação do arquivo de entrada em segundos desde 1º de janeiro de 1970 UTC.

### Valor Retornado

Dados com assinatura(s) incorporada(s) em caso de sucesso ou `false` em caso de falha.

# rnp_op_sign_cleartext

(PECL rnp >= 0.1.1)

rnp_op_sign_cleartext — Executa operação de assinatura em dados textuais, retornar mensagem assinada em texto não criptografado

### Descrição

function rnp_op_sign_cleartext(
RnpFFI `$ffi`,
string `$data`,
array `$keys_fp`,
array `$options` = ?
): string|false

### Parâmetros

`ffi`
  O objeto FFI retornado por rnp_ffi_create().
`data`
  Dados a serem assinados.
`keys_fp`
  Array com impressões digitais de chaves. Pelo menos uma chave deve ser fornecida. As chaves devem estar presentes no parâmetro `ffi`.
`options`
  Um array associativo com opções.

  Chave | Tipo de dado | Descrição
  --- | --- | ---
  `"armor"` | booleano | Habilita a saída blindada ASCII. Desativado por padrão.
  `"hash"` | string | Define o algoritmo hash usado durante o cálculo da assinatura.
  `"creation_time"` | inteiro | Define o horário de criação da assinatura em segundos desde 1º de janeiro de 1970 UTC. Por padrão, o horário atual é usado.
  `"expiration_time"` | inteiro | Define o tempo de expiração da assinatura em segundos desde o momento da criação. O valor 0 é usado para marcar a assinatura como não expirante (valor padrão).

### Valor Retornado

Mensagem assinada em texto simples contendo dados de origem com cabeçalhos adicionais e assinatura blindada ASCII em caso de sucesso ou `false` em caso de falha.

# rnp_op_sign_detached

(PECL rnp >= 0.1.1)

rnp_op_sign_detached — Executa operação de assinatura, retorna assinatura(s) separada(s)

### Descrição

function rnp_op_sign_detached(
RnpFFI `$ffi`,
string `$data`,
array `$keys_fp`,
array `$options` = ?
): string|false

### Parâmetros

`ffi`
  O objeto FFI retornado por rnp_ffi_create().
`data`
  Dados a serem assinados.
`keys_fp`
  Array com impressões digitais de chaves. Pelo menos uma chave deve ser fornecida. As chaves devem estar presentes no parâmetro `ffi`.
`options`
  Um array associativo com opções.

  Chave | Tipo de dado | Descrição
  --- | --- | ---
  `"armor"` | booleano | Habilita a saída blindada ASCII. Desativado por padrão.
  `"hash"` | string | Define o algoritmo hash usado durante o cálculo da assinatura.
  `"creation_time"` | inteiro | Define o horário de criação da assinatura em segundos desde 1º de janeiro de 1970 UTC. Por padrão, o horário atual é usado.
  `"expiration_time"` | inteiro | Define o tempo de expiração da assinatura em segundos desde o momento da criação. O valor 0 é usado para marcar a assinatura como não expirante (valor padrão).

### Valor Retornado

Dados de assinatura(s) desanexados em caso de sucesso ou `false` em caso de falha.

# rnp_op_verify

(PECL rnp >= 0.1.1)

rnp_op_verify — Verifica assinaturas incorporadas ou em texto não criptografado

### Descrição

function rnp_op_verify(RnpFFI `$ffi`, string `$data`): array|false

### Parâmetros

`ffi`
  O objeto FFI retornado por rnp_ffi_create().
`data`
  Dados assinados.

### Valor Retornado

Um array associativo com informações sobre os resultados da verificação ou `false` em caso de falha.

Chave | Tipo de dado | Descrição
--- | --- | ---
`"verification_status"` | string | Resultado geral da verificação, string "Success" ou mensagem de erro apropriada. O resultado "Success" é definido quando pelo menos uma assinatura for válida e verificada com sucesso. Os resultados da verificação individual para cada assinatura podem ser verificados no array "signatures".
`"file_name"` | string | Nome do arquivo
`"file_mtime"` | inteiro | Horário de modificação do arquivo
`"mode"` | string | Modo de proteção de dados (criptografia) usado na mensagem processada. Os valores atualmente definidos são "none", "cfb", "cfb-mdc", "aead-ocb" e "aead-eax".
`"cipher"` | string | Cifra simétrica usada para criptografia de dados
`"valid_integrity"` | booleano | `true` se a proteção de integridade da mensagem foi usada (ou seja, MDC ou AEAD) e foi validada com sucesso.
`"signatures"` | array | Um array associativo que descreve cada assinatura encontrada. Veja a descrição abaixo.

Sub-array "signatures".

Chave | Tipo de dado | Descrição
--- | --- | ---
"verification_status" | string | Status de verificação de assinatura, string "Success" ou mensagem de erro apropriada.
"creation_time" | inteiro | Horário de criação da assinatura em segundos desde 1º de janeiro de 1970 UTC.
"expiration_time" | inteiro | Tempo de expiração da assinatura em segundos desde o momento da criação ou 0 se a assinatura nunca expirar.
"hash" | string | Algoritmo de função hash usado para calcular a assinatura.
"signing_key" | string | Impressão digital da chave usada para assinatura. Poderia ser "Not found" se a chave pública correspondente não estiver carregada no objeto FFI.
"signature_type" | string | Tipo de assinatura. Valores atualmente definidos: 'binary', 'text', 'standalone', 'certification (generic)', 'certification (persona)', 'certification (casual)', 'certification (positive)', 'subkey binding', 'primary key binding', 'direct', 'key revocation', 'subkey revocation', 'certification revocation', 'timestamp', 'uknown: 0..255'.

# rnp_op_verify_detached

(PECL rnp >= 0.1.1)

rnp_op_verify_detached — Verifica assinaturas separadas

### Descrição

function rnp_op_verify_detached(RnpFFI `$ffi`, string `$data`, string `$signature`): array|false

### Parâmetros

`ffi`
  O objeto FFI retornado por rnp_ffi_create().
`data`
  Dados de origem.
`signature`
  Dados de assinatura separados.

### Valor Retornado

Um array associativo com informações sobre os resultados da verificação ou `false` em caso de falha.

Chave | Tipo de dado | Descrição
--- | --- | ---
`"verification_status"` | string | Resultado geral da verificação, string "Success" ou mensagem de erro apropriada. O resultado "Success" é definido quando pelo menos uma assinatura for válida e verificada com sucesso. Os resultados da verificação individual para cada assinatura podem ser verificados no array "signatures".
`"file_name"` | string | Nome do arquivo
`"file_mtime"` | inteiro | Horário de modificação do arquivo
`"mode"` | string | Modo de proteção de dados (criptografia) usado na mensagem processada. Os valores atualmente definidos são "none", "cfb", "cfb-mdc", "aead-ocb" e "aead-eax".
`"cipher"` | string | Cifra simétrica usada para criptografia de dados
`"valid_integrity"` | booleano | `true` se a proteção de integridade da mensagem foi usada (ou seja, MDC ou AEAD) e foi validada com sucesso.
`"signatures"` | array | Um array associativo que descreve cada assinatura encontrada. Veja a descrição abaixo.

Sub-array "signatures".

Chave | Tipo de dado | Descrição
--- | --- | ---
"verification_status" | string | Status de verificação de assinatura, string "Success" ou mensagem de erro apropriada.
"creation_time" | inteiro | Horário de criação da assinatura em segundos desde 1º de janeiro de 1970 UTC.
"expiration_time" | inteiro | Tempo de expiração da assinatura em segundos desde o momento da criação ou 0 se a assinatura nunca expirar.
"hash" | string | Algoritmo de função hash usado para calcular a assinatura.
"signing_key" | string | Impressão digital da chave usada para assinatura. Poderia ser "Not found" se a chave pública correspondente não estiver carregada no objeto FFI.
"signature_type" | string | Tipo de assinatura. Valores atualmente definidos: 'binary', 'text', 'standalone', 'certification (generic)', 'certification (persona)', 'certification (casual)', 'certification (positive)', 'subkey binding', 'primary key binding', 'direct', 'key revocation', 'subkey revocation', 'certification revocation', 'timestamp', 'uknown: 0..255'.

# rnp_save_keys

(PECL rnp >= 0.1.1)

rnp_save_keys — Salva chaves em string PHP

### Descrição

function rnp_save_keys(
RnpFFI `$ffi`,
string `$format`,
string `&$output`,
int `$flags`
): bool

Observe que para G10, a saída deve ser um diretório (que já deve existir).

### Parâmetros

`ffi`
  O objeto FFI retornado por rnp_ffi_create().
`format`
  O formato de chave dos dados (GPG, KBX, G10).
`output`
  Pacotes de chave serão salvos na string referenciada por `output`.
`flags`
  Consulte a descrição das opções `RNP_LOAD_SAVE_*`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# rnp_save_keys_to_path

(PECL rnp >= 0.1.1)

rnp_save_keys_to_path — Salva chaves no caminho especificado

### Descrição

function rnp_save_keys_to_path(
RnpFFI `$ffi`,
string `$format`,
string `$output_path`,
int `$flags`
): bool

Salva as chaves presentes no objeto FFI (carregado ou gerado) no arquivo ou diretório especificado.

### Parâmetros

`ffi`
  O objeto FFI retornado por rnp_ffi_create().
`format`
  O formato de chave dos dados (GPG, KBX, G10).
`output_path`
  Caminho do arquivo ou diretório onde as chaves devem ser salvas.
`flags`
  Consulte a descrição das opções `RNP_LOAD_SAVE_*`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# rnp_supported_features

(PECL rnp >= 0.1.1)

rnp_supported_features — Obtém recursos suportados no formato JSON

### Descrição

function rnp_supported_features(string `$type`): string|false

Obtém a string formatada em JSON contendo o array de valores de recursos RNP suportados (algoritmos, curvas, etc.) por tipo.

### Parâmetros

`type`
  Consulte as constantes RNP_FEATURE_* para valores suportados.

### Valor Retornado

String contendo array formatado em JSON com algoritmos, curvas, etc. ou `false` em caso de falha.

# rnp_version_string

(PECL rnp >= 0.1.1)

rnp_version_string — Versão da biblioteca RNP

### Descrição

function rnp_version_string(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a string da versão da biblioteca RNP.

# rnp_version_string_full

(PECL rnp >= 0.1.1)

rnp_version_string_full — String da versão completa da biblioteca RNP

### Descrição

function rnp_version_string_full(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a string da versão completa da biblioteca RNP.

## Índice

- rnp_backend_string — Retorna o nome da biblioteca de back-end criptográfico
- rnp_backend_version — Retorna a versão da biblioteca de back-end criptográfico
- rnp_decrypt — Descriptografa mensagem PGP
- rnp_dump_packets — Despeja informação de fluxo de pacotes OpenPGP em formato legível
- rnp_dump_packets_to_json — Despejar informações de fluxo de pacotes OpenPGP para a string JSON
- rnp_ffi_create — Cria o objeto de nível superior usado para interagir com a biblioteca
- rnp_ffi_destroy — Destrói o objeto de nível superior usado para interagir com a biblioteca
- rnp_ffi_set_pass_provider — Definir função de retorno do provedor de senha
- rnp_import_keys — Importa chaves da string PHP para o chaveiro e recebe JSON descrevendo chaves novas/atualizadas
- rnp_import_signatures — Importa assinaturas independentes para o chaveiro e recebe JSON descrevendo chaves atualizadas
- rnp_key_export — Exporta uma chave
- rnp_key_export_autocrypt — Exporte o mínimo de chaves para o recurso de criptografia automática (apenas 5 pacotes: chave, uid, assinatura, subchave de criptografia, assinatura)
- rnp_key_export_revocation — Gera e exporta assinatura de revogação de chave primária
- rnp_key_get_info — Obtém informação sobre a chave
- rnp_key_remove — Remover uma chave de chaveiro(s)
- rnp_key_revoke — Revogar uma chave ou subchave gerando e adicionando assinatura de revogação
- rnp_list_keys — Enumera todas as chaves presentes em um chaveiro por tipo de identificador especificado
- rnp_load_keys — Carrega chaves da string PHP
- rnp_load_keys_from_path — Carrega chaves do caminho especificado
- rnp_locate_key — Procura a chave
- rnp_op_encrypt — Criptografa mensagem
- rnp_op_generate_key — Gera chave
- rnp_op_sign — Executa operação de assinatura em dados binários, retornar assinatura(s) incorporada(s)
- rnp_op_sign_cleartext — Executa operação de assinatura em dados textuais, retornar mensagem assinada em texto não criptografado
- rnp_op_sign_detached — Executa operação de assinatura, retorna assinatura(s) separada(s)
- rnp_op_verify — Verifica assinaturas incorporadas ou em texto não criptografado
- rnp_op_verify_detached — Verifica assinaturas separadas
- rnp_save_keys — Salva chaves em string PHP
- rnp_save_keys_to_path — Salva chaves no caminho especificado
- rnp_supported_features — Obtém recursos suportados no formato JSON
- rnp_version_string — Versão da biblioteca RNP
- rnp_version_string_full — String da versão completa da biblioteca RNP

# A classe RnpFFI

(PECL rnp >= 0.1.1)

## Introdução

## Resumo da classe

class RnpFFI {
}

- Instalação/Configuração
  - Dependências
  - Instalação
- Constantes predefinidas
- Exemplos
  - Texto Clearsign
- Funções de Rnp
  - rnp_backend_string — Retorna o nome da biblioteca de back-end criptográfico
  - rnp_backend_version — Retorna a versão da biblioteca de back-end criptográfico
  - rnp_decrypt — Descriptografa mensagem PGP
  - rnp_dump_packets — Despeja informação de fluxo de pacotes OpenPGP em formato legível
  - rnp_dump_packets_to_json — Despejar informações de fluxo de pacotes OpenPGP para a string JSON
  - rnp_ffi_create — Cria o objeto de nível superior usado para interagir com a biblioteca
  - rnp_ffi_destroy — Destrói o objeto de nível superior usado para interagir com a biblioteca
  - rnp_ffi_set_pass_provider — Definir função de retorno do provedor de senha
  - rnp_import_keys — Importa chaves da string PHP para o chaveiro e recebe JSON descrevendo chaves novas/atualizadas
  - rnp_import_signatures — Importa assinaturas independentes para o chaveiro e recebe JSON descrevendo chaves atualizadas
  - rnp_key_export — Exporta uma chave
  - rnp_key_export_autocrypt — Exporte o mínimo de chaves para o recurso de criptografia automática (apenas 5 pacotes: chave, uid, assinatura, subchave de criptografia, assinatura)
  - rnp_key_export_revocation — Gera e exporta assinatura de revogação de chave primária
  - rnp_key_get_info — Obtém informação sobre a chave
  - rnp_key_remove — Remover uma chave de chaveiro(s)
  - rnp_key_revoke — Revogar uma chave ou subchave gerando e adicionando assinatura de revogação
  - rnp_list_keys — Enumera todas as chaves presentes em um chaveiro por tipo de identificador especificado
  - rnp_load_keys — Carrega chaves da string PHP
  - rnp_load_keys_from_path — Carrega chaves do caminho especificado
  - rnp_locate_key — Procura a chave
  - rnp_op_encrypt — Criptografa mensagem
  - rnp_op_generate_key — Gera chave
  - rnp_op_sign — Executa operação de assinatura em dados binários, retornar assinatura(s) incorporada(s)
  - rnp_op_sign_cleartext — Executa operação de assinatura em dados textuais, retornar mensagem assinada em texto não criptografado
  - rnp_op_sign_detached — Executa operação de assinatura, retorna assinatura(s) separada(s)
  - rnp_op_verify — Verifica assinaturas incorporadas ou em texto não criptografado
  - rnp_op_verify_detached — Verifica assinaturas separadas
  - rnp_save_keys — Salva chaves em string PHP
  - rnp_save_keys_to_path — Salva chaves no caminho especificado
  - rnp_supported_features — Obtém recursos suportados no formato JSON
  - rnp_version_string — Versão da biblioteca RNP
  - rnp_version_string_full — String da versão completa da biblioteca RNP
- RnpFFI — A classe RnpFFI

# Sodium

# Introdução

Sodium é uma biblioteca de software moderna e fácil de usar para criptografia, descriptografia, assinaturas, hash de senha e mais. Seu objetivo é fornecer todas as operações essenciais necessárias para construir ferramentas criptográficas de alto nível.

# Instalação/Configuração

## Índice

- Dependências
- Instalação

## Dependências

Esta extensão requer » libsodium ≥ 1.0.8.

## Instalação

Desde o PHP 7.2.0 esta extensão é empacotada com o PHP. Para versões mais antigas do PHP esta extensão está disponível via PECL.

## Sistemas Linux

Para usar esta extensão, o PHP deve ser compilado com suporte ao sodium usando a opção de configuração --with-sodium[=DIR].

## Windows

Para usar esta extensão, `extension=php_sodium.dll` deve ser adicionado ao php.ini.

## Instalação via PECL

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/libsodium

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`SODIUM_LIBRARY_VERSION` (string)
`SODIUM_LIBRARY_MAJOR_VERSION` (int)
`SODIUM_LIBRARY_MINOR_VERSION` (int)
`SODIUM_BASE64_VARIANT_ORIGINAL` (int)
`SODIUM_BASE64_VARIANT_ORIGINAL_NO_PADDING` (int)
`SODIUM_BASE64_VARIANT_URLSAFE` (int)
`SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING` (int)
`SODIUM_CRYPTO_AEAD_AEGIS128L_KEYBYTES` (int)
  Disponível a partir do PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS128L_NSECBYTES` (int)
  Disponível a partir do PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS128L_NPUBBYTES` (int)
  Disponível a partir do PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS128L_ABYTES` (int)
  Disponível a partir do PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS256_KEYBYTES` (int)
  Disponível a partir do PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS256_NSECBYTES` (int)
  Disponível a partir do PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS256_NPUBBYTES` (int)
  Disponível a partir do PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS256_ABYTES` (int)
  Disponível a partir do PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AES256GCM_KEYBYTES` (int)
`SODIUM_CRYPTO_AEAD_AES256GCM_NSECBYTES` (int)
`SODIUM_CRYPTO_AEAD_AES256GCM_NPUBBYTES` (int)
`SODIUM_CRYPTO_AEAD_AES256GCM_ABYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_KEYBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_NSECBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_NPUBBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_ABYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_KEYBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_NSECBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_NPUBBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_ABYTES` (int)
`SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_ABYTES` (int)
`SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_KEYBYTES` (int)
`SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NPUBBYTES` (int)
`SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NSECBYTES` (int)
`SODIUM_CRYPTO_AUTH_BYTES` (int)
`SODIUM_CRYPTO_AUTH_KEYBYTES` (int)
`SODIUM_CRYPTO_BOX_SEALBYTES` (int)
`SODIUM_CRYPTO_BOX_SECRETKEYBYTES` (int)
`SODIUM_CRYPTO_BOX_PUBLICKEYBYTES` (int)
`SODIUM_CRYPTO_BOX_KEYPAIRBYTES` (int)
`SODIUM_CRYPTO_BOX_MACBYTES` (int)
`SODIUM_CRYPTO_BOX_NONCEBYTES` (int)
`SODIUM_CRYPTO_BOX_SEEDBYTES` (int)
`SODIUM_CRYPTO_KDF_BYTES_MIN` (int)
`SODIUM_CRYPTO_KDF_BYTES_MAX` (int)
`SODIUM_CRYPTO_KDF_CONTEXTBYTES` (int)
`SODIUM_CRYPTO_KDF_KEYBYTES` (int)
`SODIUM_CRYPTO_KX_SEEDBYTES` (int)
`SODIUM_CRYPTO_KX_SESSIONKEYBYTES` (int)
`SODIUM_CRYPTO_KX_PUBLICKEYBYTES` (int)
`SODIUM_CRYPTO_KX_SECRETKEYBYTES` (int)
`SODIUM_CRYPTO_KX_KEYPAIRBYTES` (int)
`SODIUM_CRYPTO_GENERICHASH_BYTES` (int)
`SODIUM_CRYPTO_GENERICHASH_BYTES_MIN` (int)
`SODIUM_CRYPTO_GENERICHASH_BYTES_MAX` (int)
`SODIUM_CRYPTO_GENERICHASH_KEYBYTES` (int)
`SODIUM_CRYPTO_GENERICHASH_KEYBYTES_MIN` (int)
`SODIUM_CRYPTO_GENERICHASH_KEYBYTES_MAX` (int)
`SODIUM_CRYPTO_PWHASH_ALG_ARGON2I13` (int)
`SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13` (int)
`SODIUM_CRYPTO_PWHASH_ALG_DEFAULT` (int)
`SODIUM_CRYPTO_PWHASH_SALTBYTES` (int)
`SODIUM_CRYPTO_PWHASH_STRPREFIX` (string)
`SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE` (int)
`SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE` (int)
`SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE` (int)
`SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE` (int)
`SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE` (int)
`SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE` (int)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_SALTBYTES` (int)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_STRPREFIX` (string)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_INTERACTIVE` (int)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_INTERACTIVE` (int)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_SENSITIVE` (int)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_SENSITIVE` (int)
`SODIUM_CRYPTO_CORE_RISTRETTO255_BYTES` (int)
  Disponível a partir do PHP 8.1.0.
`SODIUM_CRYPTO_CORE_RISTRETTO255_HASHBYTES` (int)
  Disponível a partir do PHP 8.1.0.
`SODIUM_CRYPTO_CORE_RISTRETTO255_NONREDUCEDSCALARBYTES` (int)
  Disponível a partir do PHP 8.1.0.
`SODIUM_CRYPTO_CORE_RISTRETTO255_SCALARBYTES` (int)
  Disponível a partir do PHP 8.1.0.
`SODIUM_CRYPTO_SCALARMULT_BYTES` (int)
`SODIUM_CRYPTO_SCALARMULT_SCALARBYTES` (int)
`SODIUM_CRYPTO_SCALARMULT_RISTRETTO255_BYTES` (int)
  Disponível a partir do PHP 8.1.0.
`SODIUM_CRYPTO_SCALARMULT_RISTRETTO255_SCALARBYTES` (int)
  Disponível a partir do PHP 8.1.0.
`SODIUM_CRYPTO_SHORTHASH_BYTES` (int)
`SODIUM_CRYPTO_SHORTHASH_KEYBYTES` (int)
`SODIUM_CRYPTO_SECRETBOX_KEYBYTES` (int)
`SODIUM_CRYPTO_SECRETBOX_MACBYTES` (int)
`SODIUM_CRYPTO_SECRETBOX_NONCEBYTES` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_ABYTES` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_HEADERBYTES` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_KEYBYTES` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_MESSAGEBYTES_MAX` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_PUSH` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_REKEY` (int)
`SODIUM_CRYPTO_SIGN_BYTES` (int)
`SODIUM_CRYPTO_SIGN_SEEDBYTES` (int)
`SODIUM_CRYPTO_SIGN_PUBLICKEYBYTES` (int)
`SODIUM_CRYPTO_SIGN_SECRETKEYBYTES` (int)
`SODIUM_CRYPTO_SIGN_KEYPAIRBYTES` (int)
`SODIUM_CRYPTO_STREAM_NONCEBYTES` (int)
`SODIUM_CRYPTO_STREAM_KEYBYTES` (int)
`SODIUM_CRYPTO_STREAM_XCHACHA20_KEYBYTES` (int)
  Disponível a partir do PHP 8.1.0.
`SODIUM_CRYPTO_STREAM_XCHACHA20_NONCEBYTES` (int)
  Disponível a partir do PHP 8.1.0.

# Funções da Sodium

# sodium_add

(PHP 7 >= 7.2.0, PHP 8)

sodium_add — Soma números grandes

### Descrição

function sodium_add(string `&$string1`, string `$string2`): void

Adiciona o parâmetro `string2` ao `string1`, substituindo o valor armazenado em `string1`. Esta função assume que ambos os parâmetros são strings binárias que representam inteiros sem sinal na ordem de bytes little-endian.

### Parâmetros

`string1`
  String representando um número inteiro sem sinal de tamanho arbitrário na ordem de bytes little-endian. Este parâmetro é passado por referência e conterá a soma dos dois parâmetros.
`string2`
  String representando um número inteiro sem sinal de tamanho arbitrário na ordem de bytes little-endian.

### Valor Retornado

Nenhum valor é retornado.

# sodium_base642bin

(PHP 7 >= 7.2.0, PHP 8)

sodium_base642bin — Decodifica uma string codificada em base64 para binário bruto.

### Descrição

function sodium_base642bin(#[\SensitiveParameter]string `$string`, int `$id`, string `$ignore` = ""): string

Converte uma string codificada em base64 para binário bruto. Ao contrário de base64_decode(), sodium_base642bin() é de tempo constante (uma propriedade que é importante para qualquer código que toca entradas criptográficas, como textos simples ou chaves) e suporta vários conjuntos de caracteres.

### Parâmetros

`string`
  string; String codificada.
`id`
  - `SODIUM_BASE64_VARIANT_ORIGINAL` para codificação Base64 padrão (`A-Za-z0-9/\+`).
  - `SODIUM_BASE64_VARIANT_ORIGINAL_NO_PADDING` para codificação Base64 padrão (`A-Za-z0-9/\+`), sem os caracteres de preenchimento `=`.
  - `SODIUM_BASE64_VARIANT_URLSAFE` para codificação Base64 segura para URL (`A-Za-z0-9\-_`).
  - `SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING` para codificação Base64 segura para URL (`A-Za-z0-9\-_`), sem os caracteres de preenchimento `=`.
`ignore`
  Caracteres a serem ignorados ao decodificar (por exemplo, caracteres de espaço em branco).

### Valor Retornado

String decodificada.

# sodium_bin2base64

(PHP 7 >= 7.2.0, PHP 8)

sodium_bin2base64 — Codifica uma string binária bruta com base64.

### Descrição

function sodium_bin2base64(#[\SensitiveParameter]string `$string`, int `$id`): string

Converte uma string binária bruta em uma string codificada em base64. Ao contrário de base64_encode(), sodium_bin2base64() é de tempo constante (uma propriedade que é importante para qualquer código que toca entradas criptográficas, como textos simples ou chaves) e suporta vários conjuntos de caracteres.

### Parâmetros

`string`
  String binária bruta.
`id`
  - `SODIUM_BASE64_VARIANT_ORIGINAL` para codificação Base64 padrão (`A-Za-z0-9/\+`).
  - `SODIUM_BASE64_VARIANT_ORIGINAL_NO_PADDING` para codificação Base64 padrão (`A-Za-z0-9/\+`), sem os caracteres de preenchimento `=`.
  - `SODIUM_BASE64_VARIANT_URLSAFE` para codificação Base64 segura para URL (`A-Za-z0-9\-_`).
  - `SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING` para codificação Base64 segura para URL (`A-Za-z0-9\-_`), sem os caracteres de preenchimento `=`.

### Valor Retornado

String codificada em Base64.

# sodium_bin2hex

(PHP 7 >= 7.2.0, PHP 8)

sodium_bin2hex — Codifica para hexadecimal

### Descrição

function sodium_bin2hex(#[\SensitiveParameter]string `$string`): string

Converte uma string binária bruta em uma string codificada em hexadecimal. Ao contrário da função de codificação hexadecimal padrão, sodium_bin2hex() é de tempo constante (uma propriedade importante para qualquer código que toca entradas criptográficas, como textos simples ou chaves).

### Parâmetros

`string`
  String binária bruta.

### Valor Retornado

String codificada em hexadecimal.

# sodium_compare

(PHP 7 >= 7.2.0, PHP 8)

sodium_compare — Compara números grandes

### Descrição

function sodium_compare(#[\SensitiveParameter]string `$string1`, #[\SensitiveParameter]string `$string2`): int

Compara duas strings como se fossem inteiros little-endian sem sinal, de tamanho arbitrário, sem vazamento de canal lateral.

### Parâmetros

`string1`
  Operando esquerdo
`string2`
  Operando direito

### Valor Retornado

Retorna `-1` se `string1` for menor que `string2`.

Retorna `1` se `string1` for maior que `string2`.

Retorna `0` se ambas as strings forem iguais.

# sodium_crypto_aead_aegis128l_decrypt

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis128l_decrypt — Verifica e descriptografa uma mensagem com AEGIS-128L

### Descrição

function sodium_crypto_aead_aegis128l_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Verifica e descriptografa uma mensagem com AEGIS-128L.

### Parâmetros

`ciphertext`
  Precisa estar no formato informado por sodium_crypto_aead_aegis128l_encrypt().
`additional_data`
  Dados adicionais e autenticados. São usados ​​na verificação da tag de autenticação anexada ao texto cifrado, mas não são criptografados nem armazenados no texto cifrado.
`nonce`
  Um número que deve ser usado apenas uma vez por mensagem.
`key`
  Chave de criptografia (128-bit).

### Valor Retornado

Retorna o texto simples em caso de sucesso, ou `false` em caso de falha.

### Veja Também

- sodium_crypto_aead_aegis128l_encrypt() - Criptografa e autentica uma mensagem com AEGIS-128L
- sodium_crypto_aead_aegis128l_keygen() - Gera uma chave AEGIS-128L aleatória

# sodium_crypto_aead_aegis128l_encrypt

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis128l_encrypt — Criptografa e autentica uma mensagem com AEGIS-128L

### Descrição

function sodium_crypto_aead_aegis128l_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Criptografa e autentica uma mensagem com AEGIS-128L.

### Parâmetros

`message`
  A mensagem de texto simples a ser criptografada.
`additional_data`
  Dados adicionais e autenticados. São usados ​​na verificação da tag de autenticação anexada ao texto cifrado, mas não são criptografados nem armazenados no texto cifrado.
`nonce`
  Um número que deve ser usado apenas uma vez por mensagem.
`key`
  Chave de criptografia (128-bit).

### Valor Retornado

Retorna o texto cifrado e a tag de autenticação como uma sequência de bytes binários brutos.

### Veja Também

- sodium_crypto_aead_aegis128l_decrypt() - Verifica e descriptografa uma mensagem com AEGIS-128L
- sodium_crypto_aead_aegis128l_keygen() - Gera uma chave AEGIS-128L aleatória

# sodium_crypto_aead_aegis128l_keygen

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis128l_keygen — Gera uma chave AEGIS-128L aleatória

### Descrição

function sodium_crypto_aead_aegis128l_keygen(): string

Gera uma chave aleatória para uso com sodium_crypto_aead_aegis128l_encrypt() e sodium_crypto_aead_aegis128l_decrypt().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma chave 128-bit aleatória.

### Veja Também

- sodium_crypto_aead_aegis128l_decrypt() - Verifica e descriptografa uma mensagem com AEGIS-128L
- sodium_crypto_aead_aegis128l_encrypt() - Criptografa e autentica uma mensagem com AEGIS-128L

# sodium_crypto_aead_aegis256_decrypt

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis256_decrypt — Verifica e descriptografa uma mensagem com AEGIS-256

### Descrição

function sodium_crypto_aead_aegis256_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Verifica e descriptografa uma mensagem com AEGIS-256.

### Parâmetros

`ciphertext`
  Precisa estar no formato informado por sodium_crypto_aead_aegis256_encrypt().
`additional_data`
  Dados adicionais e autenticados. São usados ​​na verificação da tag de autenticação anexada ao texto cifrado, mas não são criptografados nem armazenados no texto cifrado.
`nonce`
  Um número que deve ser usado apenas uma vez por mensagem.
`key`
  Chave de criptografia (256-bit).

### Valor Retornado

Retorna o texto simples em caso de sucesso, ou `false` em caso de falha.

### Veja Também

- sodium_crypto_aead_aegis256_encrypt() - Criptografa e autentica uma mensagem com AEGIS-256
- sodium_crypto_aead_aegis256_keygen() - Gera uma chave AEGIS-256 aleatória

# sodium_crypto_aead_aegis256_encrypt

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis256_encrypt — Criptografa e autentica uma mensagem com AEGIS-256

### Descrição

function sodium_crypto_aead_aegis256_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Criptografa e autentica uma mensagem com AEGIS-256.

### Parâmetros

`message`
  A mensagem de texto simples a ser criptografada.
`additional_data`
  Dados adicionais e autenticados. São usados ​​na verificação da tag de autenticação anexada ao texto cifrado, mas não são criptografados nem armazenados no texto cifrado.
`nonce`
  Um número que deve ser usado apenas uma vez por mensagem.
`key`
  Chave de criptografia (256-bit).

### Valor Retornado

Retorna o texto cifrado e a tag de autenticação como uma sequência de bytes binários brutos.

### Veja Também

- sodium_crypto_aead_aegis256_decrypt() - Verifica e descriptografa uma mensagem com AEGIS-256
- sodium_crypto_aead_aegis256_keygen() - Gera uma chave AEGIS-256 aleatória

# sodium_crypto_aead_aegis256_keygen

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis256_keygen — Gera uma chave AEGIS-256 aleatória

### Descrição

function sodium_crypto_aead_aegis256_keygen(): string

Gera uma chave aleatória para uso com sodium_crypto_aead_aegis256_encrypt() e sodium_crypto_aead_aegis256_decrypt().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma chave 256-bit aleatória.

### Veja Também

- sodium_crypto_aead_aegis256_decrypt() - Verifica e descriptografa uma mensagem com AEGIS-256
- sodium_crypto_aead_aegis256_encrypt() - Criptografa e autentica uma mensagem com AEGIS-256

# sodium_crypto_aead_aes256gcm_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_decrypt — Verifica e descriptografa uma mensagem com AES-256-GCM

### Descrição

function sodium_crypto_aead_aes256gcm_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Verifica e descriptografa uma mensagem com AES-256-GCM. Disponível somente se sodium_crypto_aead_aes256gcm_is_available() retornar `true`.

### Parâmetros

`ciphertext`
  Precisa estar no formato fornecido por sodium_crypto_aead_aes256gcm_encrypt() (texto cifrado e texto, concatenados).
`additional_data`
  Dados adicionais e autenticados. São usados ​​na verificação da tag de autenticação anexada ao texto cifrado, mas não são criptografados nem armazenados no texto cifrado.
`nonce`
  Um número que deve ser usado apenas uma vez por mensagem. 12 bytes long.
`key`
  Chave de criptografia (256-bit).

### Valor Retornado

Retorna o texto simples em caso de sucesso, ou `false` em caso de falha.

# sodium_crypto_aead_aes256gcm_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_encrypt — Criptografa e autentica com AES-256-GCM

### Descrição

function sodium_crypto_aead_aes256gcm_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Criptografa e autentica com AES-256-GCM. Disponível somente se sodium_crypto_aead_aes256gcm_is_available() retornar `true`.

### Parâmetros

`message`
  A mensagem de texto simples a ser criptografada.
`additional_data`
  Dados adicionais e autenticados. São usados ​​na verificação da tag de autenticação anexada ao texto cifrado, mas não são criptografados nem armazenados no texto cifrado.
`nonce`
  Um número que deve ser usado apenas uma vez por mensagem. 12 bytes long.
`key`
  Chave de criptografia (256-bit).

### Valor Retornado

Retorna o texto cifrado e a tag de autenticação como uma sequência de bytes binários brutos. (Formato: texto cifrado e depois tag.)

# sodium_crypto_aead_aes256gcm_is_available

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_is_available — Verifica se o equipamento suporta AES256-GCM

### Descrição

function sodium_crypto_aead_aes256gcm_is_available(): bool

O valor de retorno desta função depende se o equipamento suporta ou não AES acelerado por hardware.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se for seguro criptografar com AES-256-GCM e `false` caso contrário.

# sodium_crypto_aead_aes256gcm_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_keygen — Gera uma chave AES-256-GCM aleatória

### Descrição

function sodium_crypto_aead_aes256gcm_keygen(): string

Gera uma chave aleatória para uso com sodium_crypto_aead_aes256gcm_encrypt() e sodium_crypto_aead_aes256gcm_decrypt().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma chave 256-bit aleatória.

# sodium_crypto_aead_chacha20poly1305_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_decrypt — Verifica e descriptografa com ChaCha20-Poly1305

### Descrição

function sodium_crypto_aead_chacha20poly1305_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Verifica e descriptografa com ChaCha20-Poly1305.

### Parâmetros

`ciphertext`
  Precisa estar no formato fornecido por sodium_crypto_aead_chacha20poly1305_encrypt() (texto cifrado e tag, concatenados).
`additional_data`
  Dados adicionais e autenticados. São usados ​​na verificação da tag de autenticação anexada ao texto cifrado, mas não são criptografados nem armazenados no texto cifrado.
`nonce`
  Um número que deve ser usado apenas uma vez por mensagem. 8 bytes long.
`key`
  Chave de criptografia (256-bit).

### Valor Retornado

Retorna o texto simples em caso de sucesso, ou `false` em caso de falha.

# sodium_crypto_aead_chacha20poly1305_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_encrypt — Criptografa e autentica com ChaCha20-Poly1305

### Descrição

function sodium_crypto_aead_chacha20poly1305_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Criptografa e autentica com ChaCha20-Poly1305.

### Parâmetros

`message`
  A mensagem de texto simples a ser criptografada.
`additional_data`
  Dados adicionais e autenticados. São usados ​​na verificação da tag de autenticação anexada ao texto cifrado, mas não são criptografados nem armazenados no texto cifrado.
`nonce`
  Um número que deve ser usado apenas uma vez por mensagem. 8 bytes long.
`key`
  Chave de criptografia (256-bit).

### Valor Retornado

Retorna o texto cifrado e tag em caso de sucesso, ou `false` em caso de falha.

# sodium_crypto_aead_chacha20poly1305_ietf_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_ietf_decrypt — Verifica se o texto cifrado inclui uma tag válida

### Descrição

function sodium_crypto_aead_chacha20poly1305_ietf_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Verifica e descriptografa com ChaCha20-Poly1305 (variante IETF).

A variante IETF usa nonces de 96 bits e contadores internos de 32 bits, em vez de 64 bits para ambos.

### Parâmetros

`ciphertext`
  Precisa estar no formato fornecido por sodium_crypto_aead_chacha20poly1305_ietf_encrypt() (texto cifrado e tag, concatenados).
`additional_data`
  Dados adicionais e autenticados. São usados ​​na verificação da tag de autenticação anexada ao texto cifrado, mas não são criptografados nem armazenados no texto cifrado.
`nonce`
  Um número que deve ser usado apenas uma vez por mensagem. 12 bytes long.
`key`
  Chave de criptografia (256-bit).

### Valor Retornado

Retorna o texto simples em caso de sucesso, ou `false` em caso de falha.

# sodium_crypto_aead_chacha20poly1305_ietf_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_ietf_encrypt — Criptografa uma mensagem

### Descrição

function sodium_crypto_aead_chacha20poly1305_ietf_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Criptografa e autentica com ChaCha20-Poly1305 (variant IETF).

A variante IETF usa nonces de 96 bits e contadores internos de 32 bits, em vez de 64 bits para ambos.

### Parâmetros

`message`
  A mensagem de texto simples a ser criptografada.
`additional_data`
  Dados adicionais e autenticados. São usados ​​na verificação da tag de autenticação anexada ao texto cifrado, mas não são criptografados nem armazenados no texto cifrado.
`nonce`
  Um número que deve ser usado apenas uma vez por mensagem. 12 bytes long.
`key`
  Chave de criptografia (256-bit).

### Valor Retornado

Retorna o texto cifrado e tag em caso de sucesso, ou `false` em caso de falha.

# sodium_crypto_aead_chacha20poly1305_ietf_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_ietf_keygen — Gera uma chave ChaCha20-Poly1305 (IETF) aleatória

### Descrição

function sodium_crypto_aead_chacha20poly1305_ietf_keygen(): string

Gera uma chave aleatória para uso com sodium_crypto_aead_chacha20poly1305_ietf_encrypt() e sodium_crypto_aead_chacha20poly1305_ietf_decrypt().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma chave 256-bit aleatória.

# sodium_crypto_aead_chacha20poly1305_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_keygen — Gera uma chave ChaCha20-Poly1305 aleatória

### Descrição

function sodium_crypto_aead_chacha20poly1305_keygen(): string

Gera uma chave aleatória para uso com sodium_crypto_aead_chacha20poly1305_encrypt() e sodium_crypto_aead_chacha20poly1305_decrypt().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma chave 256-bit aleatória.

# sodium_crypto_aead_xchacha20poly1305_ietf_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_xchacha20poly1305_ietf_decrypt — (Preferido) Verifica e descriptografa com XChaCha20-Poly1305

### Descrição

function sodium_crypto_aead_xchacha20poly1305_ietf_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Verifica e descriptografa com ChaCha20-Poly1305 (variante eXtended-nonce).

Geralmente, o XChaCha20-Poly1305 é o melhor dos modos AEAD fornecidos para uso.

### Parâmetros

`ciphertext`
  Precisa estar no formato fornecido por sodium_crypto_aead_xchacha20poly1305_ietf_encrypt() (texto cifrado e tag, concatenados).
`additional_data`
  Dados adicionais e autenticados. São usados ​​na verificação da tag de autenticação anexada ao texto cifrado, mas não são criptografados nem armazenados no texto cifrado.
`nonce`
  Um número que deve ser usado apenas uma vez por mensagem. 24 bytes de comprimento. Este é um limite grande o suficiente para ser gerado aleatoriamente (por exemplo, random_bytes()).
`key`
  Chave de criptografia (256-bit).

### Valor Retornado

Retorna o texto simples em caso de sucesso, ou `false` em caso de falha.

# sodium_crypto_aead_xchacha20poly1305_ietf_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_xchacha20poly1305_ietf_encrypt — (Preferido) Criptografa e autentica com XChaCha20-Poly1305

### Descrição

function sodium_crypto_aead_xchacha20poly1305_ietf_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Criptografa e autentica com XChaCha20-Poly1305 (variante eXtended-nonce).

Geralmente, o XChaCha20-Poly1305 é o melhor dos modos AEAD fornecidos para uso.

### Parâmetros

`message`
  A mensagem de texto simples a ser criptografada.
`additional_data`
  Dados adicionais e autenticados. São usados ​​na verificação da tag de autenticação anexada ao texto cifrado, mas não são criptografados nem armazenados no texto cifrado.
`nonce`
  Um número que deve ser usado apenas uma vez por mensagem. 24 bytes de comprimento. Este é um limite grande o suficiente para ser gerado aleatoriamente (por exemplo, random_bytes()).
`key`
  Chave de criptografia (256-bit).

### Valor Retornado

Retorna o texto cifrado e tag em caso de sucesso, ou `false` em caso de falha.

# sodium_crypto_aead_xchacha20poly1305_ietf_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_xchacha20poly1305_ietf_keygen — Gera uma chave XChaCha20-Poly1305 aleatória

### Descrição

function sodium_crypto_aead_xchacha20poly1305_ietf_keygen(): string

Gera uma chave aleatória para uso com sodium_crypto_aead_xchacha20poly1305_ietf_encrypt() e sodium_crypto_aead_xchacha20poly1305_ietf_decrypt().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma chave 256-bit aleatória.

# sodium_crypto_auth

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_auth — Calcula uma tag para a mensagem

### Descrição

function sodium_crypto_auth(string `$message`, #[\SensitiveParameter]string `$key`): string

A autenticação simétrica de mensagens via sodium_crypto_auth() fornece integridade, mas não confidencialidade.

Ao contrário das assinaturas digitais (por exemplo, sodium_crypto_sign_detached()), qualquer parte capaz de verificar uma mensagem também é capaz de autenticar suas próprias mensagens. (Daí a autenticação simétrica.)

### Parâmetros

`message`
  A mensagem que se pretende autenticar
`key`
  Chave de autenticação

### Valor Retornado

Tag de autenticação.

# sodium_crypto_auth_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_auth_keygen — Gera uma chave aleatória para sodium_crypto_auth

### Descrição

function sodium_crypto_auth_keygen(): string

Gera uma chave para uso com sodium_crypto_auth() e sodium_crypto_auth_verify().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma chave 256-bit aleatória.

# sodium_crypto_auth_verify

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_auth_verify — Verifica se a tag é válida para a mensagem

### Descrição

function sodium_crypto_auth_verify(string `$mac`, string `$message`, #[\SensitiveParameter]string `$key`): bool

Verifique se a tag de autenticação é válida para uma determinada mensagem e chave.

Ao contrário das assinaturas digitais (por exemplo, sodium_crypto_sign_verify_detached()), qualquer parte capaz de verificar uma mensagem também é capaz de autenticar suas próprias mensagens. (Daí a autenticação simétrica.)

### Parâmetros

`mac`
  Etiqueta de autenticação produzida por sodium_crypto_auth()
`message`
  Mensagem
`key`
  Chave de autenticação

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# sodium_crypto_box

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box — Criptografia de chave pública autenticada

### Descrição

function sodium_crypto_box(#[\SensitiveParameter]string `$message`, string `$nonce`, #[\SensitiveParameter]string `$key_pair`): string

Criptografa uma mensagem usando criptografia assimétrica (chave pública).

O algoritmo usado por funções prefixadas com sodium_crypto_box() é Curva Elíptica Diffie-Hellman sobre a curva de Montgomery, Curva25519; geralmente abreviada como X25519.

### Parâmetros

`message`
  A mensagem a ser criptografada.
`nonce`
  Um número que deve ser usado apenas uma vez por mensagem. 24 bytes de comprimento. Este é um limite grande o suficiente para ser gerado aleatoriamente (por exemplo, random_bytes()).
`key_pair`
  Consulte sodium_crypto_box_keypair_from_secretkey_and_publickey(). Isso deve incluir a chave secreta X25519 do remetente e a chave pública X25519 do destinatário.

### Valor Retornado

Retorna a mensagem criptografada (texto cifrado mais tag de autenticação). O texto cifrado será 16 bytes maior que o texto simples e uma string binária bruta. Consulte sodium_bin2base64() para codificação segura para armazenamento.

# sodium_crypto_box_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_keypair — Gera aleatoriamente uma chave secreta e uma chave pública correspondente

### Descrição

function sodium_crypto_box_keypair(): string

Gera uma chave secreta e uma chave pública como uma string.

Para obter a chave secreta desta sequência de chaves unificada, consulte sodium_crypto_box_secretkey(). Para obter a chave pública desta sequência de chaves unificada, consulte sodium_crypto_box_publickey().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Uma sequência contendo a chave secreta X25519 e a chave pública X25519 correspondente.

# sodium_crypto_box_keypair_from_secretkey_and_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_keypair_from_secretkey_and_publickey — Cria uma sequência de pares de chaves unificada a partir de uma chave secreta e uma chave pública

### Descrição

function sodium_crypto_box_keypair_from_secretkey_and_publickey(#[\SensitiveParameter]string `$secret_key`, string `$public_key`): string

Esta função existe para satisfazer os requisitos da API de, por exemplo, crypto_box(). Passe a chave secreta de uma parte e a chave pública da outra, e será obtido um "par de chaves" para a conversa.

### Parâmetros

`secret_key`
  Chave secreta.
`public_key`
  Chave pública.

### Valor Retornado

Par de chaves X25519.

# sodium_crypto_box_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_open — Descriptografia de chave pública autenticada

### Descrição

function sodium_crypto_box_open(string `$ciphertext`, string `$nonce`, #[\SensitiveParameter]string `$key_pair`): string|false

Descriptografa uma mensagem usando criptografia assimétrica (chave pública).

### Parâmetros

`ciphertext`
  A mensagem criptografada para tentar descriptografar.
`nonce`
  Um número que deve ser usado apenas uma vez por mensagem. 24 bytes de comprimento. Este é um limite grande o suficiente para ser gerado aleatoriamente (por exemplo, random_bytes()).
`key_pair`
  Veja sodium_crypto_box_keypair_from_secretkey_and_publickey(). Este parâmetro deve incluir a chave pública do remetente e a chave secreta do destinatário.

### Valor Retornado

Retorna a mensagem de texto simples em caso de sucesso, ou `false` em caso de falha.

# sodium_crypto_box_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_publickey — Extrai a chave pública de um par de chaves crypto_box

### Descrição

function sodium_crypto_box_publickey(#[\SensitiveParameter]string `$key_pair`): string

Dado um par de chaves, busca apenas a chave pública.

### Parâmetros

`key_pair`
  Um par de chaves, como o gerado por sodium_crypto_box_keypair() ou sodium_crypto_box_seed_keypair()

### Valor Retornado

Chave pública X25519.

# sodium_crypto_box_publickey_from_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_publickey_from_secretkey — Calcula a chave pública a partir de uma chave secreta

### Descrição

function sodium_crypto_box_publickey_from_secretkey(#[\SensitiveParameter]string `$secret_key`): string

Dada uma chave secreta, calcula a chave pública correspondente.

Isso só funciona com o tipo de chave destinado ao uso com crypto_box() (que usa a Curva Elíptica Diffie-Hellman sobre a curva de Montgomery, Curve25519; abreviada como X25519), não com crypto_sign() (que usa o Algoritmo de Assinatura Digital Edwards sobre a Curva de Edwards com os parâmetros correspondentes; abreviada como Ed25519).

### Parâmetros

`secret_key`
  Chave secreta X25519

### Valor Retornado

Chave pública X25519.

# sodium_crypto_box_seal

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_seal — Criptografia de chave pública anônima

### Descrição

function sodium_crypto_box_seal(#[\SensitiveParameter]string `$message`, string `$public_key`): string

Criptografa uma mensagem de modo que somente o destinatário possa decifrá-la.

Ao contrário de sodium_crypto_box(), você só precisa saber a chave pública do destinatário para usar sodium_crypto_box_seal(). Uma consequência dessa conveniência, no entanto, é que o texto cifrado não está vinculado a uma chave pública estática e, portanto, não é autenticado. Daí a criptografia de chave pública anônima.

sodium_crypto_box_seal() ainda fornece integridade de texto cifrado. Só não autenticação de identidade do remetente.

Se também for necessária autenticação do remetente, as funções sodium_crypto_sign() são provavelmente o melhor lugar para começar.

### Parâmetros

`message`
  A mensagem a criptografar.
`public_key`
  A chave pública que corresponde à única chave que pode descriptografar a mensagem.

### Valor Retornado

Uma sequência de texto cifrado no formato de (chave pública única, mensagem criptografada, tag de autenticação).

### Exemplos

Exemplo #1 Exemplo de sodium_crypto_box_seal()

    <?php
    $keypair = sodium_crypto_box_keypair();
    $public_key = sodium_crypto_box_publickey($keypair);

    // Texto simples ofuscado para tornar o exemplo mais divertido
    $plaintext_b64 = "V3JpdGluZyBzb2Z0d2FyZSBpbiBQSFAgY2FuIGJlIGEgZGVsaWdodCE=";
    $decoded_plaintext = sodium_base642bin($plaintext_b64, SODIUM_BASE64_VARIANT_ORIGINAL);

    $sealed = sodium_crypto_box_seal($decoded_plaintext, $public_key);
    var_dump(base64_encode($sealed));

    $opened = sodium_crypto_box_seal_open($sealed, $keypair);
    var_dump($opened);
    ?>

O exemplo acima produzirá algo semelhante a:

    string(120) "oRBXXAV4iQBrxlV4A21Bord8Yo/D8ZlrIIGNyaRCcGBfpz0map52I3xq6l+CST+1NSgQkbV+HiYyFjXWiWiaCGupGf+zl4bgWj/A9Adtem7Jt3h3emrMsLw="
    string(41) "Writing software in PHP can be a delight!"

# sodium_crypto_box_seal_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_seal_open — Descriptografia de chave pública anônima

### Descrição

function sodium_crypto_box_seal_open(string `$ciphertext`, #[\SensitiveParameter]string `$key_pair`): string|false

Descriptografa uma mensagem que foi criptografada com sodium_crypto_box_seal()

### Parâmetros

`ciphertext`
  A mensagem criptografada.
`key_pair`
  O par de chaves do destinatário. Deve incluir a chave secreta.

### Valor Retornado

O texto simples em caso de sucesso, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de sodium_crypto_box_seal_open()

    <?php
    // O texto cifrado não é sensível; base64_decode está ok
    $sealed_b64 = "oRBXXAV4iQBrxlV4A21Bord8Yo/D8ZlrIIGNyaRCcGBfpz0map52I3xq6l+CST+1NSgQkbV+HiYyFjXWiWiaCGupGf+zl4bgWj/A9Adtem7Jt3h3emrMsLw=";
    $sealed = base64_decode($sealed_b64);

    // O par de chaves contém um segredo criptográfico; use um decodificador seguro contra ataques de temporização
    $keypair_b64 = "KZkF8wnB7bnC2aXB3lFOqCTc0Z6MllvaQb9ASVG8o2/MsewkuE4u1uaEgTzSakeiYyIW8DGj+02/L3cWIbs9bQ==";
    $keypair = sodium_base642bin($keypair_b64, SODIUM_BASE64_VARIANT_ORIGINAL);

    $opened = sodium_crypto_box_seal_open($sealed, $keypair);
    var_dump($opened);
    ?>

O exemplo acima produzirá algo semelhante a:

    string(41) "Writing software in PHP can be a delight!"

# sodium_crypto_box_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_secretkey — Extrai a chave secreta de um par de chaves crypto_box

### Descrição

function sodium_crypto_box_secretkey(#[\SensitiveParameter]string `$key_pair`): string

Dado um par de chaves, busca apenas a chave secreta.

### Parâmetros

`key_pair`
  Um par de chaves, como o gerado por sodium_crypto_box_keypair() ou sodium_crypto_box_seed_keypair().

### Valor Retornado

Chave secreta X25519.

# sodium_crypto_box_seed_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_seed_keypair — Deriva deterministicamente o par de chaves de uma única chave

### Descrição

function sodium_crypto_box_seed_keypair(#[\SensitiveParameter]string `$seed`): string

Fixa a semente para formar uma chave secreta, deriva a chave pública e retorna as duas como um par de chaves.

As funções `*_seed_keypair` são ideais para gerar um par de chaves a partir de uma senha e um salt. Use o resultado como uma `seed` para gerar as chaves desejadas.

### Parâmetros

`seed`
  Alguma entrada criptográfica. Deve ter 32 bytes.

### Valor Retornado

Par de chaves X25519 (chave secreta e chave pública).

# sodium_crypto_core_ristretto255_add

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_add — Adiciona um elemento

### Descrição

function sodium_crypto_core_ristretto255_add(string `$p`, string `$q`): string

Adiciona um elemento `q` a `p`. Disponível a partir do libsodium 1.0.18.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`p`
  Um elemento.
`q`
  Um elemento.

### Valor Retornado

Retorna uma string de 32 bytes aleatória.

### Exemplos

Exemplo #1 Exemplo de sodium_crypto_core_ristretto255_add()

    <?php

    $foo = sodium_crypto_core_ristretto255_random();
    $bar = sodium_crypto_core_ristretto255_random();

    $value = sodium_crypto_core_ristretto255_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

O exemplo acima produzirá:

    bool(true)

### Veja Também

- sodium_crypto_core_ristretto255_random() - Gera uma chave aleatória
- sodium_crypto_core_ristretto255_sub() - Subtrai um elemento

# sodium_crypto_core_ristretto255_from_hash

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_from_hash — Mapeia um vetor

### Descrição

function sodium_crypto_core_ristretto255_from_hash(string `$s`): string

Mapeia um vetor de 64 bytes `s` a um elemento de grupo. Disponível a partir do libsodium 1.0.18.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`s`
  Um vetor de 64 bytes.

### Valor Retornado

Retorna uma string de 32 bytes aleatória.

### Exemplos

Exemplo #1 Exemplo de sodium_crypto_core_ristretto255_from_hash()

    <?php

    $hashes = sodium_hex2bin(
        '5d1be09e3d0c82fc538112490e35701979d99e06ca3e2b5b54bffe8b4dc772c1' .
        '4d98b696a1bbfb5ca32c436cc61c16563790306c79eaca7705668b47dffe5bb6'
    );
    var_dump(sodium_bin2hex(sodium_crypto_core_ristretto255_from_hash($hashes)));
    ?>

O exemplo acima produzirá:

    string(64) "3066f82a1a747d45120d1740f14358531a8f04bbffe6a819f86dfe50f44a0a46"

### Veja Também

- sodium_hex2bin() - Decodifica uma string binária codificada em hexadecimal
- sodium_bin2hex() - Codifica para hexadecimal
- sodium_crypto_core_ristretto255_from_hash()

# sodium_crypto_core_ristretto255_is_valid_point

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_is_valid_point — Determina se um ponto está na curva ristretto255

### Descrição

function sodium_crypto_core_ristretto255_is_valid_point(string `$s`): bool

Determina se um ponto na curva ristretto255, na forma canônica, está no subgrupo principal e se o ponto não possui uma ordem pequena. Disponível a partir do libsodium 1.0.18.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`s`
  Um ponto de curva elíptica.

### Valor Retornado

Retorna `true` se `s` estiver na curva ristretto255, `false` caso contrário.

### Exemplos

Exemplo #1 Exemplo de sodium_crypto_core_ristretto255_is_valid_point()

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();
    $bar = sodium_crypto_scalarmult_ristretto255_base($foo);

    var_dump(sodium_crypto_core_ristretto255_is_valid_point($bar));
    ?>

O exemplo acima produzirá:

    bool(true)

### Veja Também

- sodium_crypto_core_ristretto255_scalar_random() - Gera uma chave aleatória
- sodium_crypto_scalarmult_ristretto255_base() - Calcula a chave pública a partir de uma chave secreta

# sodium_crypto_core_ristretto255_random

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_random — Gera uma chave aleatória

### Descrição

function sodium_crypto_core_ristretto255_random(): string

Gera uma chave aleatória. Disponível a partir do libsodium 1.0.18.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string de 32 bytes aleatória.

### Exemplos

Exemplo #1 Exemplo de sodium_crypto_core_ristretto255_random()

    <?php

    $foo = sodium_crypto_core_ristretto255_random();
    $bar = sodium_crypto_core_ristretto255_random();

    $value = sodium_crypto_core_ristretto255_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

O exemplo acima produzirá:

    bool(true)

### Veja Também

- sodium_crypto_core_ristretto255_add() - Adiciona um elemento
- sodium_crypto_core_ristretto255_sub() - Subtrai um elemento

# sodium_crypto_core_ristretto255_scalar_add

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_add — Adiciona um valor escalar

### Descrição

function sodium_crypto_core_ristretto255_scalar_add(string `$x`, string `$y`): string

Adiciona um elemento `y` a `x`. Disponível a partir do libsodium 1.0.18.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`x`
  Escalar, representando a coordenada X.
`y`
  Escalar, representando a coordenada Y.

### Valor Retornado

Retorna uma string de 32 bytes aleatória.

### Exemplos

Exemplo #1 Exemplo de sodium_crypto_core_ristretto255_scalar_add()

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();
    $bar = sodium_crypto_core_ristretto255_scalar_random();

    $value = sodium_crypto_core_ristretto255_scalar_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_scalar_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

O exemplo acima produzirá:

    bool(true)

### Veja Também

- sodium_crypto_core_ristretto255_scalar_random() - Gera uma chave aleatória
- sodium_crypto_core_ristretto255_scalar_sub() - Subtrai um valor escalar

# sodium_crypto_core_ristretto255_scalar_complement

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_complement — O propósito de sodium_crypto_core_ristretto255_scalar_complement

### Descrição

function sodium_crypto_core_ristretto255_scalar_complement(string `$s`): string

Disponível a partir do libsodium 1.0.18.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`s`
  Valor escalar.

### Valor Retornado

Retorna uma string de 32 bytes aleatória.

### Veja Também

- sodium_crypto_core_ristretto255_scalar_random() - Gera uma chave aleatória

# sodium_crypto_core_ristretto255_scalar_invert

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_invert — Inverte um valor escalar

### Descrição

function sodium_crypto_core_ristretto255_scalar_invert(string `$s`): string

Inverte um valor escalar. Disponível a partir do libsodium 1.0.18.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`s`
  Valor escalar.

### Valor Retornado

Retorna uma string de 32 bytes aleatória.

### Exemplos

Exemplo #1 Exemplo de sodium_crypto_core_ristretto255_scalar_invert()

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();

    $inverted = sodium_crypto_core_ristretto255_scalar_invert($foo);
    $reInverted = sodium_crypto_core_ristretto255_scalar_invert($inverted);

    var_dump(hash_equals($foo, $reInverted));
    ?>

O exemplo acima produzirá:

    bool(true)

### Veja Também

- sodium_crypto_core_ristretto255_scalar_random() - Gera uma chave aleatória

# sodium_crypto_core_ristretto255_scalar_mul

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_mul — Multiplica um valor escalar

### Descrição

function sodium_crypto_core_ristretto255_scalar_mul(string `$x`, string `$y`): string

Multiplica um valor escalar. Disponível a partir do libsodium 1.0.18.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`x`
  Escalar, representando a coordenada X.
`y`
  Escalar, representando a coordenada Y.

### Valor Retornado

Retorna uma string de 32 bytes aleatória.

### Veja Também

- sodium_crypto_core_ristretto255_scalar_random() - Gera uma chave aleatória

# sodium_crypto_core_ristretto255_scalar_negate

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_negate — Negativa um valor escalar

### Descrição

function sodium_crypto_core_ristretto255_scalar_negate(string `$s`): string

Negativa um valor escalar. Disponível a partir do libsodium 1.0.18.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`s`
  Valor escalar.

### Valor Retornado

Retorna uma string de 32 bytes aleatória.

### Exemplos

Exemplo #1 Exemplo de sodium_crypto_core_ristretto255_scalar_negate()

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();

    $negate = sodium_crypto_core_ristretto255_scalar_negate($foo);
    $reNegate = sodium_crypto_core_ristretto255_scalar_negate($negate);

    var_dump(hash_equals($foo, $reNegate));
    ?>

O exemplo acima produzirá:

    bool(true)

### Veja Também

- sodium_crypto_core_ristretto255_scalar_random() - Gera uma chave aleatória

# sodium_crypto_core_ristretto255_scalar_random

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_random — Gera uma chave aleatória

### Descrição

function sodium_crypto_core_ristretto255_scalar_random(): string

Gera uma chave aleatória. Disponível a partir do libsodium 1.0.18.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string de 32 bytes aleatória.

### Exemplos

Exemplo #1 Exemplo de sodium_crypto_core_ristretto255_scalar_random()

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();
    $bar = sodium_crypto_core_ristretto255_scalar_random();

    $value = sodium_crypto_core_ristretto255_scalar_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_scalar_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

O exemplo acima produzirá:

    bool(true)

### Veja Também

- sodium_crypto_core_ristretto255_scalar_add() - Adiciona um valor escalar
- sodium_crypto_core_ristretto255_scalar_sub() - Subtrai um valor escalar

# sodium_crypto_core_ristretto255_scalar_reduce

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_reduce — Reduz um valor escalar

### Descrição

function sodium_crypto_core_ristretto255_scalar_reduce(string `$s`): string

Reduz um valor escalar. Disponível a partir do libsodium 1.0.18.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`s`
  Valor escalar.

### Valor Retornado

Retorna uma string de 32 bytes aleatória.

### Veja Também

- sodium_crypto_core_ristretto255_scalar_random() - Gera uma chave aleatória

# sodium_crypto_core_ristretto255_scalar_sub

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_sub — Subtrai um valor escalar

### Descrição

function sodium_crypto_core_ristretto255_scalar_sub(string `$x`, string `$y`): string

Subtrai um escalar `y` de `x`. Disponível a partir do libsodium 1.0.18.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`x`
  Escalar, representando a coordenada X.
`y`
  Escalar, representando a coordenada Y.

### Valor Retornado

Retorna uma string de 32 bytes aleatória.

### Exemplos

Exemplo #1 Exemplo de sodium_crypto_core_ristretto255_scalar_sub()

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();
    $bar = sodium_crypto_core_ristretto255_scalar_random();

    $value = sodium_crypto_core_ristretto255_scalar_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_scalar_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

O exemplo acima produzirá:

    bool(true)

### Veja Também

- sodium_crypto_core_ristretto255_scalar_random() - Gera uma chave aleatória
- sodium_crypto_core_ristretto255_scalar_add() - Adiciona um valor escalar

# sodium_crypto_core_ristretto255_sub

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_sub — Subtrai um elemento

### Descrição

function sodium_crypto_core_ristretto255_sub(string `$p`, string `$q`): string

Subtrai um elemento `q` de `p`. Disponível a partir do libsodium 1.0.18.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`p`
  Um elemento.
`q`
  Um elemento.

### Valor Retornado

Retorna uma string de 32 bytes aleatória.

### Exemplos

Exemplo #1 Exemplo de sodium_crypto_core_ristretto255_sub()

    <?php

    $foo = sodium_crypto_core_ristretto255_random();
    $bar = sodium_crypto_core_ristretto255_random();

    $value = sodium_crypto_core_ristretto255_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

O exemplo acima produzirá:

    bool(true)

### Veja Também

- sodium_crypto_core_ristretto255_random() - Gera uma chave aleatória
- sodium_crypto_core_ristretto255_add() - Adiciona um elemento

# sodium_crypto_generichash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash — Obtém um hash da mensagem

### Descrição

function sodium_crypto_generichash(string `$message`, #[\SensitiveParameter]string `$key` = "", int `$length` = `SODIUM_CRYPTO_GENERICHASH_BYTES`): string

Cria hash de uma mensagem com BLAKE2b.

### Parâmetros

`message`
  A mensagem que está sofrendo hash.
`key`
  Chave criptográfica (opcional). Ela tem a mesma função de uma chave HMAC, mas é utilizada como uma seção reservada do estado interno do BLAKE2.
`length`
  Tamanho de saída.

### Valor Retornado

O hash criptográfico como bytes brutos. Se uma saída codificada em hexadecimal for desejada, o resultado pode ser passado para sodium_bin2hex().

# sodium_crypto_generichash_final

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_final — Completa o hash

### Descrição

function sodium_crypto_generichash_final(string `&$state`, int `$length` = `SODIUM_CRYPTO_GENERICHASH_BYTES`): string

O método de finalização para a API generichash de fluxo.

### Parâmetros

`state`
  Estado de hash retornado de sodium_crypto_generichash_init()
`length`
  Comprimento da saída.

### Valor Retornado

Hash criptográfico.

### Exemplos

Exemplo #1 Exemplo de sodium_crypto_generichash_final()

    <?php
    $messages = [random_bytes(32), random_bytes(32), random_bytes(16)];
    $state = sodium_crypto_generichash_init('', 32);
    foreach ($messages as $message) {
        sodium_crypto_generichash_update($state, $message);
    }

    $final = sodium_crypto_generichash_final($state, 32);
    var_dump(sodium_bin2hex($final));

    $allAtOnce = sodium_crypto_generichash(implode('', $messages));
    var_dump(sodium_bin2hex($allAtOnce));
    ?>

O exemplo acima produzirá algo semelhante a:

    string(64) "a2939a9163cb7c796ec28e01028489e72475c136b2697ea59e3e760ab4a8ab20"
    string(64) "a2939a9163cb7c796ec28e01028489e72475c136b2697ea59e3e760ab4a8ab20"

# sodium_crypto_generichash_init

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_init — Inicializa um hash para fluxo

### Descrição

function sodium_crypto_generichash_init(#[\SensitiveParameter]string `$key` = "", int `$length` = `SODIUM_CRYPTO_GENERICHASH_BYTES`): string

O método de inicialização para a API generichash de fluxo.

### Parâmetros

`key`
  A chave generichash.
`length`
  O comprimento de saída esperado da função hash.

### Valor Retornado

Retorna um estado de hash, serializado como uma string binária bruta.

### Exemplos

Exemplo #1 Exemplo de sodium_crypto_generichash_init()

    <?php
    $messages = [random_bytes(32), random_bytes(32), random_bytes(16)];
    $state = sodium_crypto_generichash_init('', 32);
    foreach ($messages as $message) {
        sodium_crypto_generichash_update($state, $message);
    }
    $final = sodium_crypto_generichash_final($state, 32);
    var_dump(sodium_bin2hex($final));
    $allAtOnce = sodium_crypto_generichash(implode('', $messages));
    var_dump(sodium_bin2hex($allAtOnce));
    ?>

O exemplo acima produzirá algo semelhante a:

    string(64) "a2939a9163cb7c796ec28e01028489e72475c136b2697ea59e3e760ab4a8ab20"
    string(64) "a2939a9163cb7c796ec28e01028489e72475c136b2697ea59e3e760ab4a8ab20"

# sodium_crypto_generichash_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_keygen — Gera uma chave generichash aleatória

### Descrição

function sodium_crypto_generichash_keygen(): string

Gera uma chave aleatória para uso com a API generichash.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Uma chave aleatória de 256 bits.

# sodium_crypto_generichash_update

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_update — Adiciona mensagem a um hash

### Descrição

function sodium_crypto_generichash_update(string `&$state`, string `$message`): true

Adiciona uma mensagem ao estado do hash interno.

### Parâmetros

`state`
  O valor de retorno de sodium_crypto_generichash_init().
`message`
  Dados a serem anexados ao estado de hash.

### Valor Retornado

Sempre retorna `true`.

### Exemplos

Exemplo #1 Exemplo de sodium_crypto_generichash_update()

    <?php
    $messages = [random_bytes(32), random_bytes(32), random_bytes(16)];
    $state = sodium_crypto_generichash_init();
    foreach ($messages as $message) {
        sodium_crypto_generichash_update($state, $message);
    }
    $final = sodium_crypto_generichash_final($state);
    var_dump(sodium_bin2hex($final));

    $allAtOnce = sodium_crypto_generichash(implode('', $messages));
    var_dump(sodium_bin2hex($allAtOnce));
    ?>

O exemplo acima produzirá algo semelhante a:

    string(64) "e16e28bbbbcc39d9f5b1cbc33c41f1d217808640103e57a41f24870f79831e04"
    string(64) "e16e28bbbbcc39d9f5b1cbc33c41f1d217808640103e57a41f24870f79831e04"

# sodium_crypto_kdf_derive_from_key

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kdf_derive_from_key — Deriva uma subchave

### Descrição

function sodium_crypto_kdf_derive_from_key(
int `$subkey_length`,
int `$subkey_id`,
string `$context`,
#[\SensitiveParameter]string `$key`
): string

Deriva uma subchave de uma chave raiz e contexto adicional.

Similar a hash_hkdf().

### Parâmetros

`subkey_length`
  Comprimento da chave a ser retornada (em bytes)
`subkey_id`
  Retorna a enésima subchave de uma determinada chave raiz. Útil para busca.
`context`
  Contexto específico da aplicação.
`key`
  A chave raiz da qual a subchave é derivada.

### Valor Retornado

Uma sequência de bytes pseudoaleatórios (binários brutos).

# sodium_crypto_kdf_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kdf_keygen — Gera uma chave raiz aleatória para a interface KDF

### Descrição

function sodium_crypto_kdf_keygen(): string

Gera uma chave aleatória adequada para servir como chave raiz para sodium_crypto_kdf_derive_from_key().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Uma chave aleatória de 256 bits.

# sodium_crypto_kx_client_session_keys

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_client_session_keys — Calcula as chaves de sessão do lado do cliente

### Descrição

function sodium_crypto_kx_client_session_keys(#[\SensitiveParameter]string `$client_key_pair`, string `$server_key`): array

Calcula as chaves de sessão do lado do cliente, usando o método de troca de chaves X25519 + BLAKE2b.

### Parâmetros

`client_key_pair`
  Um par de chaves crypto_kx, como um gerado por sodium_crypto_kx_keypair().
`server_key`
  Uma chave pública crypto_kx.

### Valor Retornado

Um array composto por duas strings. A primeira deve ser usada para receber dados do servidor. A segunda deve ser usada para enviar dados ao servidor.

# sodium_crypto_kx_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_keypair — Cria um novo par de chaves sodium

### Descrição

function sodium_crypto_kx_keypair(): string

Cria um novo par de chaves sodium composto pela chave secreta (32 bytes) seguida pela chave pública (32 bytes). As chaves podem ser recuperadas chamando sodium_crypto_kx_secretkey() e sodium_crypto_kx_publickey(), respectivamente.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o novo par de chaves em caso de sucesso; caso contrário, lança uma exceção.

### Exemplos

Exemplo #1 sodium_crypto_kx_keypair() usage

Cria um novo par de chaves e recupera a chave secreta e a chave pública dele.

    <?php
    $keypair = sodium_crypto_kx_keypair();
    $secret = sodium_crypto_kx_secretkey($keypair);
    $public = sodium_crypto_kx_publickey($keypair);
    printf("secret: %s\npublic: %s", sodium_bin2hex($secret), sodium_bin2hex($public));
    ?>

O exemplo acima produzirá algo semelhante a:

    secret: e7c5c918fdc40762e6000542c0118f4368ce8fd242b0e48c1e17202797a25daf
    public: d1f59fda8652caf40ed1a01d2b6f3802b60846986372cd8fa337b7c12c428b18

# sodium_crypto_kx_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_publickey — Extrai a chave pública de um par de chaves crypto_kx

### Descrição

function sodium_crypto_kx_publickey(#[\SensitiveParameter]string `$key_pair`): string

Extrai a chave pública de um par de chaves crypto_kx.

### Parâmetros

`key_pair`
  Par de chaves X25519, como o gerado por sodium_crypto_kx_keypair().

### Valor Retornado

Chave pública X25519.

# sodium_crypto_kx_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_secretkey — Extrai a chave secreta de um par de chaves crypto_kx

### Descrição

function sodium_crypto_kx_secretkey(#[\SensitiveParameter]string `$key_pair`): string

Extrai a chave secreta de um par de chaves crypto_kx.

### Parâmetros

`key_pair`
  Par de chaves X25519, como o gerado por sodium_crypto_kx_keypair().

### Valor Retornado

Chave secreta X25519.

# sodium_crypto_kx_seed_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_seed_keypair — Descrição

### Descrição

function sodium_crypto_kx_seed_keypair(#[\SensitiveParameter]string `$seed`): string

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`seed`

### Valor Retornado

# sodium_crypto_kx_server_session_keys

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_server_session_keys — Calcula as chaves de sessão do lado do servidor

### Descrição

function sodium_crypto_kx_server_session_keys(#[\SensitiveParameter]string `$server_key_pair`, string `$client_key`): array

Calcula as chaves de sessão do lado do servidor, usando o método de troca de chaves X25519 + BLAKE2b.

### Parâmetros

`server_key_pair`
  Um par de chaves crypto_kx, como um gerado por sodium_crypto_kx_keypair().
`client_key`
  Uma chave pública crypto_kx.

### Valor Retornado

Um array composto por duas strings. A primeira deve ser usada para receber dados do cliente. A segunda deve ser usada para enviar dados ao cliente.

# sodium_crypto_pwhash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash — Deriva uma chave de uma senha, usando Argon2

### Descrição

function sodium_crypto_pwhash(
int `$length`,
#[\SensitiveParameter]string `$password`,
string `$salt`,
int `$opslimit`,
int `$memlimit`,
int `$algo` = `SODIUM_CRYPTO_PWHASH_ALG_DEFAULT`
): string

Esta função fornece acesso de baixo nível à função de derivação de chaves crypto_pwhash do libsodium. A menos que haja um motivo específico para usar esta função, deve-se usar as funções sodium_crypto_pwhash_str() ou password_hash().

Um motivo comum para usar essa função específica é derivar as sementes para chaves criptográficas a partir de uma senha e um salt, e então usar essas sementes para gerar as chaves reais necessárias para algum propósito (por exemplo, sodium_crypto_sign_detached()).

### Parâmetros

`length`
  int; O comprimento do hash da senha a ser gerado, em bytes.
`password`
  string; A senha para a qual será gerado um hash.
`salt`
  Um salt para adicionar à senha antes do hash. O sal deve ser imprevisível, idealmente gerado a partir de uma boa fonte de números aleatórios, como random_bytes(), e ter um comprimento de exatamente `SODIUM_CRYPTO_PWHASH_SALTBYTES` bytes.
`opslimit`
  Representa uma quantidade máxima de cálculos a serem realizados. Aumentar esse número fará com que a função exija mais ciclos de CPU para calcular uma chave. Existem algumas constantes disponíveis para definir o limite de operações para valores apropriados, dependendo do uso pretendido, em ordem de intensidade: `SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE`, `SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE` e `SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE`.
`memlimit`
  A quantidade máxima de RAM que a função utilizará, em bytes. Existem constantes para ajudar você a escolher um valor apropriado, em ordem de tamanho: `SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE`, `SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE` e `SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE`. Normalmente, elas devem ser pareadas com os valores `opslimit` correspondentes.
`algo`
  int Um número que indica o algoritmo de hash a ser usado. Por padrão, `SODIUM_CRYPTO_PWHASH_ALG_DEFAULT` (o algoritmo atualmente recomendado, que pode mudar de uma versão do libsodium para outra), ou explicitamente usando `SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13`, representando o algoritmo Argon2id versão 1.3.

### Valor Retornado

Retorna a chave derivada. O valor de retorno é uma string binária do hash, não uma representação codificada em ASCII, e não contém informações adicionais sobre os parâmetros usados ​​para criar o hash. Portanto, você precisará manter essas informações se for verificar a senha no futuro. Use sodium_crypto_pwhash_str() para evitar a necessidade de fazer tudo isso.

### Exemplos

Exemplo #1 Exemplo de sodium_crypto_pwhash()

    <?php
    // Precisamos manter o salt se quisermos verificar essa senha
    $salt = random_bytes(SODIUM_CRYPTO_PWHASH_SALTBYTES);
    // Usando bin2hex para manter a saída legível
    echo bin2hex(
        sodium_crypto_pwhash(
            16, // == 128 bits
            'password',
            $salt,
            SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
            SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE,
            SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13
        )
    );
    ?>

O exemplo acima produzirá algo semelhante a:

    a18f346ba57992eb7e4ae6abf3fd30ee

# sodium_crypto_pwhash_scryptsalsa208sha256

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_scryptsalsa208sha256 — Deriva uma chave de uma senha, usando scrypt

### Descrição

function sodium_crypto_pwhash_scryptsalsa208sha256(
int `$length`,
#[\SensitiveParameter]string `$password`,
string `$salt`,
int `$opslimit`,
int `$memlimit`
): string

Esta é a contrapartida scrypt para sodium_crypto_pwhash().

Um motivo comum para usar essa função específica é derivar as sementes para chaves criptográficas a partir de uma senha e um salt, e então usar essas sementes para gerar as chaves reais necessárias para algum propósito (por exemplo, sodium_crypto_sign_detached()).

### Parâmetros

`length`
  O comprimento do hash da senha a ser gerado, em bytes.
`password`
  A senha para a qual será gerado um hash.
`salt`
  Um salt para adicionar à senha antes do hash. O salt deve ser imprevisível, idealmente gerado a partir de uma boa fonte de números aleatórios, como random_bytes(), e ter um comprimento mínimo de `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_SALTBYTES` bytes.
`opslimit`
  Representa uma quantidade máxima de cálculos a serem realizados. Aumentar esse número fará com que a função exija mais ciclos de CPU para calcular uma chave. Existem algumas constantes disponíveis para definir o limite de operações para valores apropriados, dependendo do uso pretendido, em ordem de intensidade: `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_INTERACTIVE` e `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_SENSITIVE`.
`memlimit`
  A quantidade máxima de RAM que a função utilizará, em bytes. Existem constantes para ajudar a escolher um valor apropriado, em ordem de tamanho: `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_INTERACTIVE` e `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_SENSITIVE`. Normalmente, elas devem ser pareadas com os valores `opslimit` correspondentes.

### Valor Retornado

Uma string de bytes do comprimento desejado.

# sodium_crypto_pwhash_scryptsalsa208sha256_str

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_scryptsalsa208sha256_str — Obtém um hash codificado em ASCII

### Descrição

function sodium_crypto_pwhash_scryptsalsa208sha256_str(#[\SensitiveParameter]string `$password`, int `$opslimit`, int `$memlimit`): string

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`password`
`opslimit`
`memlimit`

### Valor Retornado

# sodium_crypto_pwhash_scryptsalsa208sha256_str_verify

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_scryptsalsa208sha256_str_verify — Verifica se a senha é uma string de verificação de senha válida

### Descrição

function sodium_crypto_pwhash_scryptsalsa208sha256_str_verify(string `$hash`, #[\SensitiveParameter]string `$password`): bool

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`hash`
`password`

### Valor Retornado

# sodium_crypto_pwhash_str

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_str — Obtém um hash codificado em ASCII

### Descrição

function sodium_crypto_pwhash_str(#[\SensitiveParameter]string `$password`, int `$opslimit`, int `$memlimit`): string

Usa um algoritmo de hash de alta capacidade de CPU e memória, juntamente com um salt gerado aleatoriamente e limites de memória e CPU para gerar um hash codificado em ASCII adequado para armazenamento de senhas.

### Parâmetros

`password`
  string; A senha para a qual será gerado um hash.
`opslimit`
  Representa uma quantidade máxima de cálculos a serem realizados. Aumentar esse número fará com que a função exija mais ciclos de CPU para calcular uma chave. Há constantes disponíveis para definir o limite de operações para valores apropriados, dependendo do uso pretendido, em ordem de intensidade: `SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE`, `SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE` e `SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE`.
`memlimit`
  A quantidade máxima de RAM que a função utilizará, em bytes. Existem constantes para ajudar a escolher um valor apropriado, em ordem de tamanho: `SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE`, `SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE` e `SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE`. Normalmente, eles devem ser pareados com os valores de opslimit correspondentes.

### Valor Retornado

Retorna a senha com hash.

Para produzir o mesmo hash de senha a partir da mesma senha, os mesmos valores para `opslimit` e `memlimit` devem ser usados. Eles são incorporados ao hash gerado, portanto, tudo o que é necessário para verificar o hash está incluído. Isso permite que a função sodium_crypto_pwhash_str_verify() verifique o hash sem precisar de armazenamento separado para os outros parâmetros.

### Exemplos

Exemplo #1 Exemplo de sodium_crypto_pwhash_str()

    <?php
    $password = 'password';
    echo sodium_crypto_pwhash_str(
        $password,
        SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
        SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE
    );

O exemplo acima produzirá algo semelhante a:

    $argon2id$v=19$m=65536,t=2,p=1$oWIfdaXwWwhVmovOBc2NAQ$EbsZ+JnZyyavkafS0hoc4HdaOB0ILWZESAZ7kVGa+Iw

### Notas

> Nota: Os hashes são calculados usando o algoritmo Argon2ID, fornecendo resistência a ataques de GPU e de canal lateral. Ao contrário da função password_hash(), não há parâmetro salt (um salt é gerado automaticamente), e os parâmetros `opslimit` e `memlimit` não são opcionais.

### Veja Também

- sodium_crypto_pwhash_str_verify() - Verifica se uma senha corresponde a um hash
- sodium_crypto_pwhash() - Deriva uma chave de uma senha, usando Argon2
- password_hash() - Cria um hash de senha
- password_verify() - Verifica se uma senha corresponde a um hash
- » Libsodium Argon2 docs

# sodium_crypto_pwhash_str_needs_rehash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_str_needs_rehash — Determina se uma senha deve ou não ter o hash refeito

### Descrição

function sodium_crypto_pwhash_str_needs_rehash(string `$password`, int `$opslimit`, int `$memlimit`): bool

Determina se uma senha deve ou não ter o hash refeito, com base no `opslimit` e `memlimit` do hash atual.

### Parâmetros

`password`
  Hash de senha
`opslimit`
  Opslimit configurado; veja sodium_crypto_pwhash_str()
`memlimit`
  Memlimit configurado; veja sodium_crypto_pwhash_str()

### Valor Retornado

Retorna `true` se o memlimit/opslimit fornecido não corresponder ao que está armazenado no hash. Retorna `false` se corresponderem.

# sodium_crypto_pwhash_str_verify

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_str_verify — Verifica se uma senha corresponde a um hash

### Descrição

function sodium_crypto_pwhash_str_verify(string `$hash`, #[\SensitiveParameter]string `$password`): bool

Verifica se um hash de senha criado usando sodium_crypto_pwhash_str() corresponde a uma senha em texto simples. Observe que os parâmetros estão na ordem inversa aos mesmos parâmetros na função semelhante password_verify().

### Parâmetros

`hash`
  Um hash criado por password_hash().
`password`
  A senha do usuário.

### Valor Retornado

Retorna `true` se a senha e o hash corresponderem, ou `false` caso contrário.

### Notas

> Nota: Os hashes são calculados usando o algoritmo Argon2ID, fornecendo resistência a ataques de GPU e de canal lateral.

### Veja Também

- sodium_crypto_pwhash_str() - Obtém um hash codificado em ASCII
- password_hash() - Cria um hash de senha
- password_verify() - Verifica se uma senha corresponde a um hash

# sodium_crypto_scalarmult

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_scalarmult — Calcula um segredo compartilhado, dada a chave secreta de um usuário e a chave pública de outro usuário.

### Descrição

function sodium_crypto_scalarmult(string `$n`, string `$p`): string

Curva Elíptica Diffie-Hellman. Calcula o escalar n vezes o ponto p, em uma curva elíptica.

### Parâmetros

`n`
  Escalar, que normalmente é uma chave secreta
`p`
  Ponto (coordenada x), que normalmente é uma chave pública

### Valor Retornado

Uma string aleatória de 32 bytes.

# sodium_crypto_scalarmult_base

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_scalarmult_base — Sinônimo de sodium_crypto_box_publickey_from_secretkey()

### Descrição

Esta função é um apelido para: sodium_crypto_box_publickey_from_secretkey().

# sodium_crypto_scalarmult_ristretto255

(PHP 8 >= 8.1.1)

sodium_crypto_scalarmult_ristretto255 — Calcula um segredo compartilhado

### Descrição

function sodium_crypto_scalarmult_ristretto255(string `$n`, string `$p`): string

Calcula o escalar `n` vezes o ponto `p`. Disponível a partir do libsodium 1.0.18.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`n`
  Um escalar, que normalmente é uma chave secreta.
`p`
  Um ponto (coordenada x), que normalmente é uma chave pública.

### Valor Retornado

Retorna uma string de 32 bytes aleatória.

### Veja Também

- sodium_crypto_scalarmult_ristretto255_base() - Calcula a chave pública a partir de uma chave secreta

# sodium_crypto_scalarmult_ristretto255_base

(PHP 8 >= 8.1.1)

sodium_crypto_scalarmult_ristretto255_base — Calcula a chave pública a partir de uma chave secreta

### Descrição

function sodium_crypto_scalarmult_ristretto255_base(string `$n`): string

Dada uma chave secreta, calcula a chave pública correspondente. Disponível a partir do libsodium 1.0.18.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`n`
  Uma chave secreta.

### Valor Retornado

Retorna uma string de 32 bytes aleatória.

### Veja Também

- sodium_crypto_scalarmult_ristretto255() - Calcula um segredo compartilhado

# sodium_crypto_secretbox

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretbox — Criptografia de chave compartilhada autenticada

### Descrição

function sodium_crypto_secretbox(#[\SensitiveParameter]string `$message`, string `$nonce`, #[\SensitiveParameter]string `$key`): string

Criptografa uma mensagem com uma chave simétrica (compartilhada).

### Parâmetros

`message`
  A mensagem de texto simples a ser criptografada.
`nonce`
  Um número que deve ser usado apenas uma vez por mensagem. 24 bytes de comprimento. Este é um limite grande o suficiente para ser gerado aleatoriamente (por exemplo, random_bytes()).
`key`
  Chave de criptografia (256-bit).

### Valor Retornado

Retorna a string criptografada.

### Erros/Exceções

- Se `nonce` tiver um comprimento de bytes diferente de `SODIUM_CRYPTO_SECRETBOX_NONCEBYTES` (24 bytes), uma SodiumException será lançada.
- Se `key` tiver um comprimento de bytes diferente de `SODIUM_CRYPTO_SECRETBOX_KEYBYTES` (32 bytes), uma SodiumException será lançada.
- Lança uma SodiumException em caso de falha.

### Exemplos

Exemplo #1 Exemplo de sodium_crypto_secretbox()

    <?php
    // A chave $key deve ser mantida confidencial
    $key = sodium_crypto_secretbox_keygen();
    // Não reutilize $nonce com a mesma chave
    $nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
    $plaintext = "message to be encrypted";
    $ciphertext = sodium_crypto_secretbox($plaintext, $nonce, $key);

    var_dump(bin2hex($ciphertext));
    // O mesmo nonce e chave são necessários para descriptografar o $ciphertext
    var_dump(sodium_crypto_secretbox_open($ciphertext, $nonce, $key));
    ?>

O exemplo acima produzirá algo semelhante a:

    string(78) "3a1fa3e9f7b72ef8be51d40abf8e296c6899c185d07b18b4c93e7f26aa776d24c50852cd6b1076"
    string(23) "message to be encrypted"

### Veja Também

- sodium_crypto_secretbox_open() - Descriptografia de chave compartilhada autenticada
- sodium_crypto_secretbox_keygen() - Gera chave aleatória para sodium_crypto_secretbox
- random_bytes() - Obtém bytes aleatórios criptograficamente seguros

# sodium_crypto_secretbox_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretbox_keygen — Gera chave aleatória para sodium_crypto_secretbox

### Descrição

function sodium_crypto_secretbox_keygen(): string

Gerar uma chave para uso com sodium_crypto_secretbox() e sodium_crypto_secretbox_open().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a sequência gerada de bytes aleatórios criptograficamente seguros.

### Exemplos

Exemplo #1 Exemplo de sodium_crypto_secretbox_keygen()

    <?php
    $key = sodium_crypto_secretbox_keygen();
    var_dump( sodium_bin2hex( $key ) );
    ?>

O exemplo acima produzirá algo semelhante a:

    string(64) "88bd1dc51ec81984f3ddc5a8f59a3d95b647e2da3e879f1b9ceb0abd89e7286c"

Exemplo #2 Comparando sodium_crypto_secretbox_keygen() com random_bytes()

    <?php
    $key = sodium_crypto_secretbox_keygen();
    $bytes = random_bytes( SODIUM_CRYPTO_SECRETBOX_KEYBYTES );
    var_dump( mb_strlen( $key, '8bit' ) === mb_strlen( $bytes, '8bit' ) );
    ?>

O exemplo acima produzirá:

    bool(true)

### Veja Também

- sodium_bin2hex() - Codifica para hexadecimal
- random_bytes() - Obtém bytes aleatórios criptograficamente seguros

# sodium_crypto_secretbox_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretbox_open — Descriptografia de chave compartilhada autenticada

### Descrição

function sodium_crypto_secretbox_open(string `$ciphertext`, string `$nonce`, #[\SensitiveParameter]string `$key`): string|false

Descriptografa uma mensagem criptografada com uma chave simétrica (compartilhada).

### Parâmetros

`ciphertext`
  Precisa estar no formato fornecido por sodium_crypto_secretbox() (texto cifrado e tag, concatenados).
`nonce`
  Um número que deve ser usado apenas uma vez por mensagem. 24 bytes de comprimento. Este é um limite grande o suficiente para ser gerado aleatoriamente (por exemplo, random_bytes()).
`key`
  Chave de criptografia (256-bit).

### Valor Retornado

A string descriptografada em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

- Se `nonce` tiver um comprimento de bytes diferente de `SODIUM_CRYPTO_SECRETBOX_NONCEBYTES` (24 bytes), uma SodiumException será lançada.
- Se `key` tiver um comprimento de bytes diferente de `SODIUM_CRYPTO_SECRETBOX_KEYBYTES` (32 bytes), uma SodiumException será lançada.

### Exemplos

Exemplo #1 Exemplo de sodium_crypto_secretbox_open()

    <?php
    // A chave $key deve ser mantida confidencial
    $key = random_bytes(SODIUM_CRYPTO_SECRETBOX_KEYBYTES);
    // Não reutilize $nonce com a mesma chave
    $nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
    $ciphertext = sodium_crypto_secretbox('mensagem a ser criptografada', $nonce, $key);

    // O mesmo nonce e chave são necessários para descriptografar o $ciphertext
    $plaintext = sodium_crypto_secretbox_open($ciphertext, $nonce, $key);
    if ($plaintext !== false) {
        echo $plaintext . PHP_EOL;
    }
    ?>

O exemplo acima produzirá:

    mensagem a ser criptografada

### Veja Também

- sodium_crypto_secretbox() - Criptografia de chave compartilhada autenticada
- sodium_crypto_secretbox_keygen() - Gera chave aleatória para sodium_crypto_secretbox
- random_bytes() - Obtém bytes aleatórios criptograficamente seguros

# sodium_crypto_secretstream_xchacha20poly1305_init_pull

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_init_pull — Inicializa um contexto secretstream para descriptografia

### Descrição

function sodium_crypto_secretstream_xchacha20poly1305_init_pull(string `$header`, #[\SensitiveParameter]string `$key`): string

Inicializa um contexto secretstream para descriptografia.

### Parâmetros

`header`
  O cabeçalho do secretstream. Este deve ser um dos valores produzidos por sodium_crypto_secretstream_xchacha20poly1305_init_push().
`key`
  Chave de criptografia (256-bit).

### Valor Retornado

Estado secretstream.

### Exemplos

Exemplo #1 Exemplo de sodium_crypto_secretstream_xchacha20poly1305_init_pull()

    <?php
    function decrypt_file(string $inputFilePath, string $outputFilePath, string $key): void
    {
        $inputFile = fopen($inputFilePath, 'rb');
        $outputFile = fopen($outputFilePath, 'wb');
        $header = fread($inputFile, 24);

        $state = sodium_crypto_secretstream_xchacha20poly1305_init_pull($header, $key);
        $inputFileSize = fstat($inputFile)['size'];

        // Descriptografa o arquivo e grava seu conteúdo no arquivo de saída:
        for ($i = 24; $i < $inputFileSize; $i += 8192) {
            $ctxt_chunk = fread($inputFile, 8192);

            // Não estamos usando $tag, mas em protocolos reais você pode usar isso na criptografia para, por exemplo,
            // acionar uma recodificação ou indicar o fim do arquivo. Então, na descriptografia, você pode afirmar
            // este comportamento.
            [$ptxt_chunk, $tag] = sodium_crypto_secretstream_xchacha20poly1305_pull($state, $ctxt_chunk);
            fwrite($outputFile, $ptxt_chunk);
        }

        sodium_memzero($state);
        fclose($inputFile);
        fclose($outputFile);
    }

    // sodium_crypto_secretstream_xchacha20poly1305_keygen()
    $key = sodium_base642bin('MS0lzb7HC+thY6jY01pkTE/cwsQxnRq0/2L1eL4Hxn8=', SODIUM_BASE64_VARIANT_ORIGINAL);

    $example = sodium_hex2bin('971e33b255f0990ef3931caf761c59136efa77b434832f28ec719e3ff73f5aec38b3bba1574ab5b70a8844d8da36a668e802cfea2c');
    file_put_contents('hello.enc', $example);
    decrypt_file('hello.enc', 'hello.txt.decrypted', $key);
    var_dump(file_get_contents('hello.txt.decrypted'));
    ?>

O exemplo acima produzirá algo semelhante a:

    string(12) "Hello world!"

# sodium_crypto_secretstream_xchacha20poly1305_init_push

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_init_push — Inicializa um contexto secretstream para criptografia

### Descrição

function sodium_crypto_secretstream_xchacha20poly1305_init_push(#[\SensitiveParameter]string `$key`): array

Inicializa um contexto secretstream para criptografia.

### Parâmetros

`key`
  Chave de criptografia. Veja sodium_crypto_secretstream_xchacha20poly1305_keygen().

### Valor Retornado

Um array com dois valores de string:

- O estado do secretstream, necessário para novos avanços
- O cabeçalho secretstream, que precisa ser fornecido ao destinatário para que ele possa extrair dados

### Exemplos

Exemplo #1 Exemplo de sodium_crypto_secretstream_xchacha20poly1305_init_push()

    <?php
    function encrypt_file(string $inputFilePath, string $outputFilePath, string $key): void
    {
        [$state, $header] = sodium_crypto_secretstream_xchacha20poly1305_init_push($key);

        $inputFile = fopen($inputFilePath, 'rb');
        $outputFile = fopen($outputFilePath, 'wb');
        // Escreve o cabeçalho:
        fwrite($outputFile, $header);
        $inputFileSize = fstat($inputFile)['size'];

        // Criptografa o arquivo e grava seu conteúdo no arquivo de saída:
        for ($i = 0; $i < $inputFileSize; $i += 8175) {
            $ptxt_chunk = fread($inputFile, 8175);
            $ctxt_chunk = sodium_crypto_secretstream_xchacha20poly1305_push($state, $ptxt_chunk);
            fwrite($outputFile, $ctxt_chunk);
        }

        sodium_memzero($state);
        fclose($inputFile);
        fclose($outputFile);
    }

    // sodium_crypto_secretstream_xchacha20poly1305_keygen()
    $key = sodium_base642bin('MS0lzb7HC+thY6jY01pkTE/cwsQxnRq0/2L1eL4Hxn8=', SODIUM_BASE64_VARIANT_ORIGINAL);

    file_put_contents('hello.txt', 'Hello world!');
    encrypt_file('hello.txt', 'hello.txt.encrypted', $key);
    var_dump(sodium_bin2hex(file_get_contents('hello.txt.encrypted')));
    ?>

O exemplo acima produzirá algo semelhante a:

    string(106) "971e33b255f0990ef3931caf761c59136efa77b434832f28ec719e3ff73f5aec38b3bba1574ab5b70a8844d8da36a668e802cfea2c"

# sodium_crypto_secretstream_xchacha20poly1305_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_keygen — Gera uma chave secretstream aleatória.

### Descrição

function sodium_crypto_secretstream_xchacha20poly1305_keygen(): string

Gera uma chave secretstream aleatória.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string de bytes aleatórios.

# sodium_crypto_secretstream_xchacha20poly1305_pull

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_pull — Descriptografa um pedaço de dados de um fluxo criptografado

### Descrição

function sodium_crypto_secretstream_xchacha20poly1305_pull(string `&$state`, string `$ciphertext`, string `$additional_data` = ""): array|false

Descriptografa um bloco de dados de um fluxo criptografado.

### Parâmetros

`state`
  Veja sodium_crypto_secretstream_xchacha20poly1305_init_pull() e sodium_crypto_secretstream_xchacha20poly1305_init_push().
`ciphertext`
  O pedaço de texto cifrado a ser descriptografado.
`additional_data`
  Dados adicionais opcionais para incluir na tag de autenticação.

### Valor Retornado

Um array com dois valores:

- string; O pedaço decifrado

- int; Uma tag opcional (se fornecida durante o push). Valores possíveis:

  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE`: a tag mais comum, que não adiciona nenhuma informação sobre a natureza da mensagem.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL`: indica que a mensagem marca o fim do fluxo e apaga a chave secreta usada para criptografar a sequência anterior.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_PUSH`: indica que a mensagem marca o fim de um conjunto de mensagens, mas não o fim do fluxo. Por exemplo, uma string JSON enorme enviada em vários blocos pode usar esta tag para indicar ao aplicativo que a string está completa e pode ser decodificada. Mas o fluxo em si não está fechado, e mais dados podem ser enviados.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_REKEY`: "esquece" a chave usada para criptografar esta mensagem e as anteriores, e deriva uma nova chave secreta.

# sodium_crypto_secretstream_xchacha20poly1305_push

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_push — Criptografa um bloco de dados para que ele possa ser descriptografado com segurança em uma API de fluxo

### Descrição

function sodium_crypto_secretstream_xchacha20poly1305_push(
string `&$state`,
#[\SensitiveParameter]string `$message`,
string `$additional_data` = "",
int `$tag` = `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE`
): string

Criptografa um bloco de dados para que ele possa ser descriptografado com segurança em uma API de fluxo.

### Parâmetros

`state`
  Veja sodium_crypto_secretstream_xchacha20poly1305_init_pull() e sodium_crypto_secretstream_xchacha20poly1305_init_push().
`message`
`additional_data`
`tag`
  Opcional. Pode ser usado para confirmar o comportamento de descriptografia (por exemplo, redigitar ou indicar o bloco final em um fluxo).
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE`: a tag mais comum, que não adiciona nenhuma informação sobre a natureza da mensagem.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL`: indica que a mensagem marca o fim do fluxo e apaga a chave secreta usada para criptografar a sequência anterior.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_PUSH`: indica que a mensagem marca o fim de um conjunto de mensagens, mas não o fim do fluxo. Por exemplo, uma string JSON enorme enviada em vários blocos pode usar esta tag para indicar ao aplicativo que a string está completa e pode ser decodificada. Mas o fluxo em si não está fechado, e mais dados podem ser enviados.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_REKEY`: "esquece" a chave usada para criptografar esta mensagem e as anteriores, e deriva uma nova chave secreta.

### Valor Retornado

Retorna o texto criptografado.

# sodium_crypto_secretstream_xchacha20poly1305_rekey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_rekey — Rotaciona explicitamente a chave no estado secretstream

### Descrição

function sodium_crypto_secretstream_xchacha20poly1305_rekey(string `&$state`): void

Rotaciona explicitamente a chave no estado secretstream. Substitui o valor passado.

### Parâmetros

`state`
  Estado do secretstream.

### Valor Retornado

Nenhum valor é retornado.

# sodium_crypto_shorthash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_shorthash — Calcula um hash curto de uma mensagem e chave

### Descrição

function sodium_crypto_shorthash(string `$message`, #[\SensitiveParameter]string `$key`): string

sodium_crypto_shorthash() envolve uma função hash chamada SipHash-2-4, que é ideal para implementar tabelas hash que não são suscetíveis a ataques de negação de serviço por colisão de hash (Hash-DoS).

SipHash-2-4 não é uma função de hash criptográfica de uso geral.

### Parâmetros

`message`
  A mensagem para hash.
`key`
  A chave de hash.

### Valor Retornado

# sodium_crypto_shorthash_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_shorthash_keygen — Obtém bytes aleatórios para uma chave

### Descrição

function sodium_crypto_shorthash_keygen(): string

Gerar uma chave para uso com sodium_crypto_shorthash().

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# sodium_crypto_sign

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign — Assina uma mensagem

### Descrição

function sodium_crypto_sign(string `$message`, #[\SensitiveParameter]string `$secret_key`): string

Assina uma mensagem com uma chave secreta, que pode ser verificada pela chave pública correspondente. Esta função anexa a assinatura à mensagem. Consulte sodium_crypto_sign_detached() para assinaturas desanexadas.

### Parâmetros

`message`
  Mensagem para assinar.
`secret_key`
  Chave secreta. Veja sodium_crypto_sign_secretkey()

### Valor Retornado

Mensagem assinada (não criptografada).

# sodium_crypto_sign_detached

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_detached — Assina a mensagem

### Descrição

function sodium_crypto_sign_detached(string `$message`, #[\SensitiveParameter]string `$secret_key`): string

Assina uma mensagem com uma chave secreta, que pode ser verificada pela chave pública correspondente. Esta função retorna uma assinatura separada.

### Parâmetros

`message`
  Mensagem para assinar.
`secret_key`
  Chave secreta. Veja sodium_crypto_sign_secretkey().

### Valor Retornado

Assinatura criptográfica.

# sodium_crypto_sign_ed25519_pk_to_curve25519

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_ed25519_pk_to_curve25519 — Converte uma chave pública Ed25519 em uma chave pública Curve25519

### Descrição

function sodium_crypto_sign_ed25519_pk_to_curve25519(string `$public_key`): string

Dada uma chave pública Ed25519, calcula a chave pública X25519 birracionalmente equivalente.

### Parâmetros

`public_key`
  Chave pública adequada para as funções crypto_sign.

### Valor Retornado

Chave pública adequada para as funções crypto_box.

# sodium_crypto_sign_ed25519_sk_to_curve25519

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_ed25519_sk_to_curve25519 — Converte uma chave secreta Ed25519 em uma chave secreta Curve25519

### Descrição

function sodium_crypto_sign_ed25519_sk_to_curve25519(#[\SensitiveParameter]string `$secret_key`): string

Dada uma chave secreta Ed25519, calcula a chave secreta X25519 birracionalmente equivalente.

### Parâmetros

`secret_key`
  Chave secreta adequada para as funções crypto_sign.

### Valor Retornado

Chave secreta adequada para as funções crypto_box.

# sodium_crypto_sign_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_keypair — Gera aleatoriamente uma chave secreta e uma chave pública correspondente

### Descrição

function sodium_crypto_sign_keypair(): string

Gera uma par de chaves Ed25519 aleatório como uma string.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Par de chaves Ed25519.

# sodium_crypto_sign_keypair_from_secretkey_and_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_keypair_from_secretkey_and_publickey — Une uma chave secreta e uma chave pública

### Descrição

function sodium_crypto_sign_keypair_from_secretkey_and_publickey(#[\SensitiveParameter]string `$secret_key`, string `$public_key`): string

Une uma chave secreta e uma chave pública.

### Parâmetros

`secret_key`
  Chave secreta Ed25519
`public_key`
  Chave pública Ed25519

### Valor Retornado

Par de chaves

# sodium_crypto_sign_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_open — Verifica se a mensagem assinada tem uma assinatura válida

### Descrição

function sodium_crypto_sign_open(string `$signed_message`, string `$public_key`): string|false

Verifica a assinatura anexada a uma mensagem e retorna a mensagem

### Parâmetros

`signed_message`
  Uma mensagem assinada com sodium_crypto_sign()
`public_key`
  Uma chave pública Ed25519

### Valor Retornado

Retorna a mensagem original assinada em caso de sucesso, ou `false` em caso de falha.

# sodium_crypto_sign_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_publickey — Extrai a chave pública Ed25519 de um par de chaves

### Descrição

function sodium_crypto_sign_publickey(#[\SensitiveParameter]string `$key_pair`): string

Extrai a chave pública Ed25519 de um par de chaves.

### Parâmetros

`key_pair`
  Par de chaves Ed25519 (veja: sodium_crypto_sign_keypair())

### Valor Retornado

Chave pública Ed25519

# sodium_crypto_sign_publickey_from_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_publickey_from_secretkey — Extrai a chave pública Ed25519 da chave secreta

### Descrição

function sodium_crypto_sign_publickey_from_secretkey(#[\SensitiveParameter]string `$secret_key`): string

Extrai a chave pública Ed25519 da chave secreta.

### Parâmetros

`secret_key`
  Chave secreta Ed25519

### Valor Retornado

Chave pública Ed25519

# sodium_crypto_sign_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_secretkey — Extrai a chave secreta Ed25519 de um par de chaves

### Descrição

function sodium_crypto_sign_secretkey(#[\SensitiveParameter]string `$key_pair`): string

Extrai a chave secreta Ed25519 de um par de chaves.

### Parâmetros

`key_pair`
  Par de chaves Ed25519 (veja: sodium_crypto_sign_keypair())

### Valor Retornado

Chave secreta Ed25519

# sodium_crypto_sign_seed_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_seed_keypair — Deriva deterministicamente o par de chaves de uma única chave

### Descrição

function sodium_crypto_sign_seed_keypair(#[\SensitiveParameter]string `$seed`): string

Fixa a semente para formar uma chave secreta, deriva a chave pública e retorna as duas como um par de chaves.

As funções `*_seed_keypair` são ideais para gerar um par de chaves a partir de uma senha e um salt. Use o resultado como uma `seed` para gerar as chaves desejadas.

### Parâmetros

`seed`
  Alguma entrada criptográfica. Deve ter 32 bytes.

### Valor Retornado

Par de chaves (chave secreta e chave pública)

# sodium_crypto_sign_verify_detached

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_verify_detached — Verifica a assinatura da mensagem

### Descrição

function sodium_crypto_sign_verify_detached(string `$signature`, string `$message`, string `$public_key`): bool

Verifica a assinatura da mensagem

### Parâmetros

`signature`
  A assinatura criptográfica obtida de sodium_crypto_sign_detached()
`message`
  A mensagem sendo verificada
`public_key`
  Chave pública Ed25519

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# sodium_crypto_stream

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_stream — Gera uma sequência determinística de bytes a partir de uma semente

### Descrição

function sodium_crypto_stream(int `$length`, string `$nonce`, #[\SensitiveParameter]string `$key`): string

Gera uma sequência determinística de bytes a partir de uma semente, usando a cifra de fluxo XSalsa20.

### Parâmetros

`length`
  O número de bytes a serem retornados.
`nonce`
  Um número que deve ser usado apenas uma vez por mensagem. 24 bytes de comprimento. Este é um limite grande o suficiente para ser gerado aleatoriamente (por exemplo, random_bytes()).
`key`
  Chave de criptografia (256-bit).

### Valor Retornado

String de bytes pseudoaleatórios.

# sodium_crypto_stream_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_stream_keygen — Gera uma chave sodium_crypto_stream aleatória.

### Descrição

function sodium_crypto_stream_keygen(): string

Gera uma chave para uso com sodium_crypto_stream() e sodium_crypto_stream_xor().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Chave de criptografia (256-bit).

# sodium_crypto_stream_xchacha20

(PHP 8 >= 8.1.0)

sodium_crypto_stream_xchacha20 — Expande a chave e o nonce em um fluxo de chaves de bytes pseudoaleatórios

### Descrição

function sodium_crypto_stream_xchacha20(int `$length`, string `$nonce`, #[\SensitiveParameter]string `$key`): string

Expande `key` e `nonce` em um fluxo de chaves de bytes pseudoaleatórios.

### Parâmetros

`length`
  Número de bytes desejado.
`nonce`
  Nonce de 24 bytes.
`key`
  Chave, possivelmente gerada de sodium_crypto_stream_xchacha20_keygen().

### Valor Retornado

Retorna um fluxo pseudoaleatório que pode ser usado com sodium_crypto_stream_xchacha20_xor().

# sodium_crypto_stream_xchacha20_keygen

(PHP 8 >= 8.1.0)

sodium_crypto_stream_xchacha20_keygen — Retorna uma chave segura aleatória

### Descrição

function sodium_crypto_stream_xchacha20_keygen(): string

Retorna uma chave segura aleatória para uso com sodium_crypto_stream_xchacha20().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma chave 32-byte segura aleatória para uso com sodium_crypto_stream_xchacha20().

# sodium_crypto_stream_xchacha20_xor

(PHP 8 >= 8.1.0)

sodium_crypto_stream_xchacha20_xor — Criptografa uma mensagem usando um nonce e uma chave secreta (sem autenticação)

### Descrição

function sodium_crypto_stream_xchacha20_xor(#[\SensitiveParameter]string `$message`, string `$nonce`, #[\SensitiveParameter]string `$key`): string

Criptografa a mensagem `message` usando um `nonce` e uma chave `key` secreta (sem autenticação).

Cuidado

Esta criptografia não é autenticada e não impede ataques de texto cifrado escolhido. Certifique-se de combinar o texto cifrado com um Código de Autenticação de Mensagem, por exemplo, com a função sodium_crypto_aead_xchacha20poly1305_ietf_encrypt(), ou sodium_crypto_auth().

### Parâmetros

`message`
  A mensagem a criptografar.
`nonce`
  Nonce de 24 bytes.
`key`
  Chave, possivelmente gerada a partir de sodium_crypto_stream_xchacha20_keygen().

### Valor Retornado

Mensagem criptografada.

### Veja Também

- sodium_crypto_stream_xchacha20_xor_ic() - Criptografa uma mensagem usando um nonce e uma chave secreta (sem autenticação)

# sodium_crypto_stream_xchacha20_xor_ic

(PHP 8 >= 8.2.0)

sodium_crypto_stream_xchacha20_xor_ic — Criptografa uma mensagem usando um nonce e uma chave secreta (sem autenticação)

### Descrição

function sodium_crypto_stream_xchacha20_xor_ic(
#[\SensitiveParameter]string `$message`,
string `$nonce`,
int `$counter`,
#[\SensitiveParameter]string `$key`
): string

A função é semelhante a sodium_crypto_stream_xchacha20_xor() mas adiciona a capacidade de definir o valor inicial do contador de blocos como um valor diferente de zero. Isso permite acesso direto a qualquer bloco sem precisar calcular os anteriores.

Cuidado

Esta criptografia não é autenticada e não impede ataques de texto cifrado escolhido. Certifique-se de combinar o texto cifrado com um Código de Autenticação de Mensagem, por exemplo, com a função sodium_crypto_aead_xchacha20poly1305_ietf_encrypt(), ou sodium_crypto_auth().

### Parâmetros

`message`
  A mensagem a criptografar.
`nonce`
  Nonce de 24 bytes.
`counter`
  O valor inicial do contador de blocos.
`key`
  Chave, possivelmente gerada por sodium_crypto_stream_xchacha20_keygen().

### Valor Retornado

Mensagem criptografada, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de sodium_crypto_stream_xchacha20_xor_ic()

    <?php
    $n2 = random_bytes(SODIUM_CRYPTO_STREAM_XCHACHA20_NONCEBYTES);
    $left  = str_repeat("\x01", 64);
    $right = str_repeat("\xfe", 64);

    // Tudo de uma vez só:
    $stream7_unified = sodium_crypto_stream_xchacha20_xor($left . $right, $n2, $key);

    // Parte por parte, com contador inicial:
    $stream7_left  = sodium_crypto_stream_xchacha20_xor_ic($left, $n2, 0, $key);
    $stream7_right = sodium_crypto_stream_xchacha20_xor_ic($right, $n2, 1, $key);
    $stream7_concat = $stream7_left . $stream7_right;

    var_dump(strlen($stream7_concat));
    var_dump($stream7_unified === $stream7_concat);
    ?>

O exemplo acima produzirá algo semelhante a:

    int(128)
    bool(true)

### Veja Também

- sodium_crypto_stream_xchacha20_xor() - Criptografa uma mensagem usando um nonce e uma chave secreta (sem autenticação)

# sodium_crypto_stream_xor

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_stream_xor — Criptografa uma mensagem sem autenticação

### Descrição

function sodium_crypto_stream_xor(#[\SensitiveParameter]string `$message`, string `$nonce`, #[\SensitiveParameter]string `$key`): string

Esta função criptografa uma mensagem com XSalsa20, mas não fornece nenhuma garantia de texto cifrado sobre o texto simples.

### Parâmetros

`message`
  A mensagem para criptografar
`nonce`
  Um número que deve ser usado apenas uma vez por mensagem. 24 bytes de comprimento. Este é um limite grande o suficiente para ser gerado aleatoriamente (por exemplo, random_bytes()).
`key`
  Chave de criptografia (256-bit).

### Valor Retornado

Mensagem criptografada.

# sodium_hex2bin

(PHP 7 >= 7.2.0, PHP 8)

sodium_hex2bin — Decodifica uma string binária codificada em hexadecimal

### Descrição

function sodium_hex2bin(#[\SensitiveParameter]string `$string`, string `$ignore` = ""): string

Decodifica uma string binária codificada em hexadecimal.

Assim como sodium_bin2hex(), sodium_hex2bin() é resistente a ataques de canal lateral, enquanto hex2bin() não.

### Parâmetros

`string`
  Representação hexadecimal dos dados.
`ignore`
  Argumento string opcional para caracteres a serem ignorados.

### Valor Retornado

Retorna a representação binária dos dados da `string` especificada.

# sodium_increment

(PHP 7 >= 7.2.0, PHP 8)

sodium_increment — Incrementa um número grande

### Descrição

function sodium_increment(string `&$string`): void

Trata a string como um inteiro little-endian sem sinal, então aumente-o em 1. Tempo constante.

### Parâmetros

`string`
  String para incrementar.

### Valor Retornado

Nenhum valor é retornado.

# sodium_memcmp

(PHP 7 >= 7.2.0, PHP 8)

sodium_memcmp — Testa para igualdade em tempo constante

### Descrição

function sodium_memcmp(#[\SensitiveParameter]string `$string1`, #[\SensitiveParameter]string `$string2`): int

Compara duas strings em tempo constante.

Na prática, é quase sempre desejado usar hash_equals(), pois fornece a mesma lógica, porém retorna um bool em vez de um int. No entanto, se o valor de retorno de uma comparação estiver sendo usado em um cálculo que é sensível ao tempo e vazamentos de tempo com conversões de bool para int forem uma preocupação, sodium_memcmp() é um substituto ideal.

### Parâmetros

`string1`
  String para comparar
`string2`
  Outra string para comparar

### Valor Retornado

Retorna `0` se ambas as strings forem iguais, `-1` caso contrário.

# sodium_memzero

(PHP 7 >= 7.2.0, PHP 8)

sodium_memzero — Sobrescreve uma string com caracteres NUL

### Descrição

function sodium_memzero(#[\SensitiveParameter]string `&$string`): void

sodium_memzero() zera a string passada por referência.

### Parâmetros

`string`
  String.

### Valor Retornado

Nenhum valor é retornado.

# sodium_pad

(PHP 7 >= 7.2.0, PHP 8)

sodium_pad — Adiciona dados de preenchimento

### Descrição

function sodium_pad(#[\SensitiveParameter]string `$string`, int `$block_size`): string

Preencha uma string à direita até o comprimento desejado. Tempo seguro.

### Parâmetros

`string`
  String não preenchida.
`block_size`
  A string será preenchida até que seja um múltiplo par do tamanho do bloco.

### Valor Retornado

String preenchida.

# sodium_unpad

(PHP 7 >= 7.2.0, PHP 8)

sodium_unpad — Remove dados de preenchimento

### Descrição

function sodium_unpad(#[\SensitiveParameter]string `$string`, int `$block_size`): string

Remove o preenchimento de uma string preenchida. Tempo seguro.

### Parâmetros

`string`
  String preenchida.
`block_size`
  O tamanho do bloco para preenchimento.

### Valor Retornado

String não preenchida.

## Índice

- sodium_add — Soma números grandes
- sodium_base642bin — Decodifica uma string codificada em base64 para binário bruto.
- sodium_bin2base64 — Codifica uma string binária bruta com base64.
- sodium_bin2hex — Codifica para hexadecimal
- sodium_compare — Compara números grandes
- sodium_crypto_aead_aegis128l_decrypt — Verifica e descriptografa uma mensagem com AEGIS-128L
- sodium_crypto_aead_aegis128l_encrypt — Criptografa e autentica uma mensagem com AEGIS-128L
- sodium_crypto_aead_aegis128l_keygen — Gera uma chave AEGIS-128L aleatória
- sodium_crypto_aead_aegis256_decrypt — Verifica e descriptografa uma mensagem com AEGIS-256
- sodium_crypto_aead_aegis256_encrypt — Criptografa e autentica uma mensagem com AEGIS-256
- sodium_crypto_aead_aegis256_keygen — Gera uma chave AEGIS-256 aleatória
- sodium_crypto_aead_aes256gcm_decrypt — Verifica e descriptografa uma mensagem com AES-256-GCM
- sodium_crypto_aead_aes256gcm_encrypt — Criptografa e autentica com AES-256-GCM
- sodium_crypto_aead_aes256gcm_is_available — Verifica se o equipamento suporta AES256-GCM
- sodium_crypto_aead_aes256gcm_keygen — Gera uma chave AES-256-GCM aleatória
- sodium_crypto_aead_chacha20poly1305_decrypt — Verifica e descriptografa com ChaCha20-Poly1305
- sodium_crypto_aead_chacha20poly1305_encrypt — Criptografa e autentica com ChaCha20-Poly1305
- sodium_crypto_aead_chacha20poly1305_ietf_decrypt — Verifica se o texto cifrado inclui uma tag válida
- sodium_crypto_aead_chacha20poly1305_ietf_encrypt — Criptografa uma mensagem
- sodium_crypto_aead_chacha20poly1305_ietf_keygen — Gera uma chave ChaCha20-Poly1305 (IETF) aleatória
- sodium_crypto_aead_chacha20poly1305_keygen — Gera uma chave ChaCha20-Poly1305 aleatória
- sodium_crypto_aead_xchacha20poly1305_ietf_decrypt — (Preferido) Verifica e descriptografa com XChaCha20-Poly1305
- sodium_crypto_aead_xchacha20poly1305_ietf_encrypt — (Preferido) Criptografa e autentica com XChaCha20-Poly1305
- sodium_crypto_aead_xchacha20poly1305_ietf_keygen — Gera uma chave XChaCha20-Poly1305 aleatória
- sodium_crypto_auth — Calcula uma tag para a mensagem
- sodium_crypto_auth_keygen — Gera uma chave aleatória para sodium_crypto_auth
- sodium_crypto_auth_verify — Verifica se a tag é válida para a mensagem
- sodium_crypto_box — Criptografia de chave pública autenticada
- sodium_crypto_box_keypair — Gera aleatoriamente uma chave secreta e uma chave pública correspondente
- sodium_crypto_box_keypair_from_secretkey_and_publickey — Cria uma sequência de pares de chaves unificada a partir de uma chave secreta e uma chave pública
- sodium_crypto_box_open — Descriptografia de chave pública autenticada
- sodium_crypto_box_publickey — Extrai a chave pública de um par de chaves crypto_box
- sodium_crypto_box_publickey_from_secretkey — Calcula a chave pública a partir de uma chave secreta
- sodium_crypto_box_seal — Criptografia de chave pública anônima
- sodium_crypto_box_seal_open — Descriptografia de chave pública anônima
- sodium_crypto_box_secretkey — Extrai a chave secreta de um par de chaves crypto_box
- sodium_crypto_box_seed_keypair — Deriva deterministicamente o par de chaves de uma única chave
- sodium_crypto_core_ristretto255_add — Adiciona um elemento
- sodium_crypto_core_ristretto255_from_hash — Mapeia um vetor
- sodium_crypto_core_ristretto255_is_valid_point — Determina se um ponto está na curva ristretto255
- sodium_crypto_core_ristretto255_random — Gera uma chave aleatória
- sodium_crypto_core_ristretto255_scalar_add — Adiciona um valor escalar
- sodium_crypto_core_ristretto255_scalar_complement — O propósito de sodium_crypto_core_ristretto255_scalar_complement
- sodium_crypto_core_ristretto255_scalar_invert — Inverte um valor escalar
- sodium_crypto_core_ristretto255_scalar_mul — Multiplica um valor escalar
- sodium_crypto_core_ristretto255_scalar_negate — Negativa um valor escalar
- sodium_crypto_core_ristretto255_scalar_random — Gera uma chave aleatória
- sodium_crypto_core_ristretto255_scalar_reduce — Reduz um valor escalar
- sodium_crypto_core_ristretto255_scalar_sub — Subtrai um valor escalar
- sodium_crypto_core_ristretto255_sub — Subtrai um elemento
- sodium_crypto_generichash — Obtém um hash da mensagem
- sodium_crypto_generichash_final — Completa o hash
- sodium_crypto_generichash_init — Inicializa um hash para fluxo
- sodium_crypto_generichash_keygen — Gera uma chave generichash aleatória
- sodium_crypto_generichash_update — Adiciona mensagem a um hash
- sodium_crypto_kdf_derive_from_key — Deriva uma subchave
- sodium_crypto_kdf_keygen — Gera uma chave raiz aleatória para a interface KDF
- sodium_crypto_kx_client_session_keys — Calcula as chaves de sessão do lado do cliente
- sodium_crypto_kx_keypair — Cria um novo par de chaves sodium
- sodium_crypto_kx_publickey — Extrai a chave pública de um par de chaves crypto_kx
- sodium_crypto_kx_secretkey — Extrai a chave secreta de um par de chaves crypto_kx
- sodium_crypto_kx_seed_keypair — Descrição
- sodium_crypto_kx_server_session_keys — Calcula as chaves de sessão do lado do servidor
- sodium_crypto_pwhash — Deriva uma chave de uma senha, usando Argon2
- sodium_crypto_pwhash_scryptsalsa208sha256 — Deriva uma chave de uma senha, usando scrypt
- sodium_crypto_pwhash_scryptsalsa208sha256_str — Obtém um hash codificado em ASCII
- sodium_crypto_pwhash_scryptsalsa208sha256_str_verify — Verifica se a senha é uma string de verificação de senha válida
- sodium_crypto_pwhash_str — Obtém um hash codificado em ASCII
- sodium_crypto_pwhash_str_needs_rehash — Determina se uma senha deve ou não ter o hash refeito
- sodium_crypto_pwhash_str_verify — Verifica se uma senha corresponde a um hash
- sodium_crypto_scalarmult — Calcula um segredo compartilhado, dada a chave secreta de um usuário e a chave pública de outro usuário.
- sodium_crypto_scalarmult_base — Sinônimo de sodium_crypto_box_publickey_from_secretkey
- sodium_crypto_scalarmult_ristretto255 — Calcula um segredo compartilhado
- sodium_crypto_scalarmult_ristretto255_base — Calcula a chave pública a partir de uma chave secreta
- sodium_crypto_secretbox — Criptografia de chave compartilhada autenticada
- sodium_crypto_secretbox_keygen — Gera chave aleatória para sodium_crypto_secretbox
- sodium_crypto_secretbox_open — Descriptografia de chave compartilhada autenticada
- sodium_crypto_secretstream_xchacha20poly1305_init_pull — Inicializa um contexto secretstream para descriptografia
- sodium_crypto_secretstream_xchacha20poly1305_init_push — Inicializa um contexto secretstream para criptografia
- sodium_crypto_secretstream_xchacha20poly1305_keygen — Gera uma chave secretstream aleatória.
- sodium_crypto_secretstream_xchacha20poly1305_pull — Descriptografa um pedaço de dados de um fluxo criptografado
- sodium_crypto_secretstream_xchacha20poly1305_push — Criptografa um bloco de dados para que ele possa ser descriptografado com segurança em uma API de fluxo
- sodium_crypto_secretstream_xchacha20poly1305_rekey — Rotaciona explicitamente a chave no estado secretstream
- sodium_crypto_shorthash — Calcula um hash curto de uma mensagem e chave
- sodium_crypto_shorthash_keygen — Obtém bytes aleatórios para uma chave
- sodium_crypto_sign — Assina uma mensagem
- sodium_crypto_sign_detached — Assina a mensagem
- sodium_crypto_sign_ed25519_pk_to_curve25519 — Converte uma chave pública Ed25519 em uma chave pública Curve25519
- sodium_crypto_sign_ed25519_sk_to_curve25519 — Converte uma chave secreta Ed25519 em uma chave secreta Curve25519
- sodium_crypto_sign_keypair — Gera aleatoriamente uma chave secreta e uma chave pública correspondente
- sodium_crypto_sign_keypair_from_secretkey_and_publickey — Une uma chave secreta e uma chave pública
- sodium_crypto_sign_open — Verifica se a mensagem assinada tem uma assinatura válida
- sodium_crypto_sign_publickey — Extrai a chave pública Ed25519 de um par de chaves
- sodium_crypto_sign_publickey_from_secretkey — Extrai a chave pública Ed25519 da chave secreta
- sodium_crypto_sign_secretkey — Extrai a chave secreta Ed25519 de um par de chaves
- sodium_crypto_sign_seed_keypair — Deriva deterministicamente o par de chaves de uma única chave
- sodium_crypto_sign_verify_detached — Verifica a assinatura da mensagem
- sodium_crypto_stream — Gera uma sequência determinística de bytes a partir de uma semente
- sodium_crypto_stream_keygen — Gera uma chave sodium_crypto_stream aleatória.
- sodium_crypto_stream_xchacha20 — Expande a chave e o nonce em um fluxo de chaves de bytes pseudoaleatórios
- sodium_crypto_stream_xchacha20_keygen — Retorna uma chave segura aleatória
- sodium_crypto_stream_xchacha20_xor — Criptografa uma mensagem usando um nonce e uma chave secreta (sem autenticação)
- sodium_crypto_stream_xchacha20_xor_ic — Criptografa uma mensagem usando um nonce e uma chave secreta (sem autenticação)
- sodium_crypto_stream_xor — Criptografa uma mensagem sem autenticação
- sodium_hex2bin — Decodifica uma string binária codificada em hexadecimal
- sodium_increment — Incrementa um número grande
- sodium_memcmp — Testa para igualdade em tempo constante
- sodium_memzero — Sobrescreve uma string com caracteres NUL
- sodium_pad — Adiciona dados de preenchimento
- sodium_unpad — Remove dados de preenchimento

# A classe SodiumException

(PHP 7 >= 7.2.0, PHP 8)

## Introdução

Exceções lançadas pelas funções da sodium.

## Resumo da classe

class SodiumException extends Exception {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

- Instalação/Configuração
  - Dependências
  - Instalação
- Constantes predefinidas
- Funções da Sodium
  - sodium_add — Soma números grandes
  - sodium_base642bin — Decodifica uma string codificada em base64 para binário bruto.
  - sodium_bin2base64 — Codifica uma string binária bruta com base64.
  - sodium_bin2hex — Codifica para hexadecimal
  - sodium_compare — Compara números grandes
  - sodium_crypto_aead_aegis128l_decrypt — Verifica e descriptografa uma mensagem com AEGIS-128L
  - sodium_crypto_aead_aegis128l_encrypt — Criptografa e autentica uma mensagem com AEGIS-128L
  - sodium_crypto_aead_aegis128l_keygen — Gera uma chave AEGIS-128L aleatória
  - sodium_crypto_aead_aegis256_decrypt — Verifica e descriptografa uma mensagem com AEGIS-256
  - sodium_crypto_aead_aegis256_encrypt — Criptografa e autentica uma mensagem com AEGIS-256
  - sodium_crypto_aead_aegis256_keygen — Gera uma chave AEGIS-256 aleatória
  - sodium_crypto_aead_aes256gcm_decrypt — Verifica e descriptografa uma mensagem com AES-256-GCM
  - sodium_crypto_aead_aes256gcm_encrypt — Criptografa e autentica com AES-256-GCM
  - sodium_crypto_aead_aes256gcm_is_available — Verifica se o equipamento suporta AES256-GCM
  - sodium_crypto_aead_aes256gcm_keygen — Gera uma chave AES-256-GCM aleatória
  - sodium_crypto_aead_chacha20poly1305_decrypt — Verifica e descriptografa com ChaCha20-Poly1305
  - sodium_crypto_aead_chacha20poly1305_encrypt — Criptografa e autentica com ChaCha20-Poly1305
  - sodium_crypto_aead_chacha20poly1305_ietf_decrypt — Verifica se o texto cifrado inclui uma tag válida
  - sodium_crypto_aead_chacha20poly1305_ietf_encrypt — Criptografa uma mensagem
  - sodium_crypto_aead_chacha20poly1305_ietf_keygen — Gera uma chave ChaCha20-Poly1305 (IETF) aleatória
  - sodium_crypto_aead_chacha20poly1305_keygen — Gera uma chave ChaCha20-Poly1305 aleatória
  - sodium_crypto_aead_xchacha20poly1305_ietf_decrypt — (Preferido) Verifica e descriptografa com XChaCha20-Poly1305
  - sodium_crypto_aead_xchacha20poly1305_ietf_encrypt — (Preferido) Criptografa e autentica com XChaCha20-Poly1305
  - sodium_crypto_aead_xchacha20poly1305_ietf_keygen — Gera uma chave XChaCha20-Poly1305 aleatória
  - sodium_crypto_auth — Calcula uma tag para a mensagem
  - sodium_crypto_auth_keygen — Gera uma chave aleatória para sodium_crypto_auth
  - sodium_crypto_auth_verify — Verifica se a tag é válida para a mensagem
  - sodium_crypto_box — Criptografia de chave pública autenticada
  - sodium_crypto_box_keypair — Gera aleatoriamente uma chave secreta e uma chave pública correspondente
  - sodium_crypto_box_keypair_from_secretkey_and_publickey — Cria uma sequência de pares de chaves unificada a partir de uma chave secreta e uma chave pública
  - sodium_crypto_box_open — Descriptografia de chave pública autenticada
  - sodium_crypto_box_publickey — Extrai a chave pública de um par de chaves crypto_box
  - sodium_crypto_box_publickey_from_secretkey — Calcula a chave pública a partir de uma chave secreta
  - sodium_crypto_box_seal — Criptografia de chave pública anônima
  - sodium_crypto_box_seal_open — Descriptografia de chave pública anônima
  - sodium_crypto_box_secretkey — Extrai a chave secreta de um par de chaves crypto_box
  - sodium_crypto_box_seed_keypair — Deriva deterministicamente o par de chaves de uma única chave
  - sodium_crypto_core_ristretto255_add — Adiciona um elemento
  - sodium_crypto_core_ristretto255_from_hash — Mapeia um vetor
  - sodium_crypto_core_ristretto255_is_valid_point — Determina se um ponto está na curva ristretto255
  - sodium_crypto_core_ristretto255_random — Gera uma chave aleatória
  - sodium_crypto_core_ristretto255_scalar_add — Adiciona um valor escalar
  - sodium_crypto_core_ristretto255_scalar_complement — O propósito de sodium_crypto_core_ristretto255_scalar_complement
  - sodium_crypto_core_ristretto255_scalar_invert — Inverte um valor escalar
  - sodium_crypto_core_ristretto255_scalar_mul — Multiplica um valor escalar
  - sodium_crypto_core_ristretto255_scalar_negate — Negativa um valor escalar
  - sodium_crypto_core_ristretto255_scalar_random — Gera uma chave aleatória
  - sodium_crypto_core_ristretto255_scalar_reduce — Reduz um valor escalar
  - sodium_crypto_core_ristretto255_scalar_sub — Subtrai um valor escalar
  - sodium_crypto_core_ristretto255_sub — Subtrai um elemento
  - sodium_crypto_generichash — Obtém um hash da mensagem
  - sodium_crypto_generichash_final — Completa o hash
  - sodium_crypto_generichash_init — Inicializa um hash para fluxo
  - sodium_crypto_generichash_keygen — Gera uma chave generichash aleatória
  - sodium_crypto_generichash_update — Adiciona mensagem a um hash
  - sodium_crypto_kdf_derive_from_key — Deriva uma subchave
  - sodium_crypto_kdf_keygen — Gera uma chave raiz aleatória para a interface KDF
  - sodium_crypto_kx_client_session_keys — Calcula as chaves de sessão do lado do cliente
  - sodium_crypto_kx_keypair — Cria um novo par de chaves sodium
  - sodium_crypto_kx_publickey — Extrai a chave pública de um par de chaves crypto_kx
  - sodium_crypto_kx_secretkey — Extrai a chave secreta de um par de chaves crypto_kx
  - sodium_crypto_kx_seed_keypair — Descrição
  - sodium_crypto_kx_server_session_keys — Calcula as chaves de sessão do lado do servidor
  - sodium_crypto_pwhash — Deriva uma chave de uma senha, usando Argon2
  - sodium_crypto_pwhash_scryptsalsa208sha256 — Deriva uma chave de uma senha, usando scrypt
  - sodium_crypto_pwhash_scryptsalsa208sha256_str — Obtém um hash codificado em ASCII
  - sodium_crypto_pwhash_scryptsalsa208sha256_str_verify — Verifica se a senha é uma string de verificação de senha válida
  - sodium_crypto_pwhash_str — Obtém um hash codificado em ASCII
  - sodium_crypto_pwhash_str_needs_rehash — Determina se uma senha deve ou não ter o hash refeito
  - sodium_crypto_pwhash_str_verify — Verifica se uma senha corresponde a um hash
  - sodium_crypto_scalarmult — Calcula um segredo compartilhado, dada a chave secreta de um usuário e a chave pública de outro usuário.
  - sodium_crypto_scalarmult_base — Sinônimo de sodium_crypto_box_publickey_from_secretkey
  - sodium_crypto_scalarmult_ristretto255 — Calcula um segredo compartilhado
  - sodium_crypto_scalarmult_ristretto255_base — Calcula a chave pública a partir de uma chave secreta
  - sodium_crypto_secretbox — Criptografia de chave compartilhada autenticada
  - sodium_crypto_secretbox_keygen — Gera chave aleatória para sodium_crypto_secretbox
  - sodium_crypto_secretbox_open — Descriptografia de chave compartilhada autenticada
  - sodium_crypto_secretstream_xchacha20poly1305_init_pull — Inicializa um contexto secretstream para descriptografia
  - sodium_crypto_secretstream_xchacha20poly1305_init_push — Inicializa um contexto secretstream para criptografia
  - sodium_crypto_secretstream_xchacha20poly1305_keygen — Gera uma chave secretstream aleatória.
  - sodium_crypto_secretstream_xchacha20poly1305_pull — Descriptografa um pedaço de dados de um fluxo criptografado
  - sodium_crypto_secretstream_xchacha20poly1305_push — Criptografa um bloco de dados para que ele possa ser descriptografado com segurança em uma API de fluxo
  - sodium_crypto_secretstream_xchacha20poly1305_rekey — Rotaciona explicitamente a chave no estado secretstream
  - sodium_crypto_shorthash — Calcula um hash curto de uma mensagem e chave
  - sodium_crypto_shorthash_keygen — Obtém bytes aleatórios para uma chave
  - sodium_crypto_sign — Assina uma mensagem
  - sodium_crypto_sign_detached — Assina a mensagem
  - sodium_crypto_sign_ed25519_pk_to_curve25519 — Converte uma chave pública Ed25519 em uma chave pública Curve25519
  - sodium_crypto_sign_ed25519_sk_to_curve25519 — Converte uma chave secreta Ed25519 em uma chave secreta Curve25519
  - sodium_crypto_sign_keypair — Gera aleatoriamente uma chave secreta e uma chave pública correspondente
  - sodium_crypto_sign_keypair_from_secretkey_and_publickey — Une uma chave secreta e uma chave pública
  - sodium_crypto_sign_open — Verifica se a mensagem assinada tem uma assinatura válida
  - sodium_crypto_sign_publickey — Extrai a chave pública Ed25519 de um par de chaves
  - sodium_crypto_sign_publickey_from_secretkey — Extrai a chave pública Ed25519 da chave secreta
  - sodium_crypto_sign_secretkey — Extrai a chave secreta Ed25519 de um par de chaves
  - sodium_crypto_sign_seed_keypair — Deriva deterministicamente o par de chaves de uma única chave
  - sodium_crypto_sign_verify_detached — Verifica a assinatura da mensagem
  - sodium_crypto_stream — Gera uma sequência determinística de bytes a partir de uma semente
  - sodium_crypto_stream_keygen — Gera uma chave sodium_crypto_stream aleatória.
  - sodium_crypto_stream_xchacha20 — Expande a chave e o nonce em um fluxo de chaves de bytes pseudoaleatórios
  - sodium_crypto_stream_xchacha20_keygen — Retorna uma chave segura aleatória
  - sodium_crypto_stream_xchacha20_xor — Criptografa uma mensagem usando um nonce e uma chave secreta (sem autenticação)
  - sodium_crypto_stream_xchacha20_xor_ic — Criptografa uma mensagem usando um nonce e uma chave secreta (sem autenticação)
  - sodium_crypto_stream_xor — Criptografa uma mensagem sem autenticação
  - sodium_hex2bin — Decodifica uma string binária codificada em hexadecimal
  - sodium_increment — Incrementa um número grande
  - sodium_memcmp — Testa para igualdade em tempo constante
  - sodium_memzero — Sobrescreve uma string com caracteres NUL
  - sodium_pad — Adiciona dados de preenchimento
  - sodium_unpad — Remove dados de preenchimento
- SodiumException — A classe SodiumException

# Xpass

# Introdução

Esta extensão fornece algoritmos de hash de senha usados ​​por distribuições Linux, usando a biblioteca crypt estendida.

Também fornece funções adicionais de libxcrypt ausentes no núcleo do PHP.

# Instalação/Configuração

## Índice

- Dependências
- Instalação via PECL

## Dependências

Esta extensão requer » libxcrypt versão 4.4 ou superior.

## Instalação via PECL

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/xpass.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

A extensão Xpass fornece vários conjuntos de constantes. Métodos de hash (`CRYPT_PREFIX_*`) para o parâmetro 'prefix' de crypt_gensalt(). Códigos de erro (`CRYPT_SALT_*`) retornados por crypt_checksalt(). Algoritmos de senha (`PASSWORD_*`) para o parâmetro 'algo' de password_hash().

Métodos de hash
`CRYPT_PREFIX_STD_DES` (string)
  O método de hash original do Unix V7, baseado na cifra de bloco DES. Como o DES não é custoso em equipamentos modernos, já que existem apenas `4096` salts possíveis e 2**56 frases-senha distintas, que ele trunca para 8 caracteres, é possível descobrir qualquer frase-senha com hash usando este método. Ele só deve ser usado ao oferecer suporte a sistemas operacionais antigos que não suportam nenhum outro algoritmo de geração de hash, devido à fragilidade dos hashes DES.
`CRYPT_PREFIX_EXT_DES` (string)
  Uma extensão do DES tradicional, que elimina o limite de comprimento, aumenta o tamanho do salt e torna o custo de tempo ajustável. Ele se originou com o BSDI BSD/OS e também está disponível pelo menos no NetBSD, OpenBSD e FreeBSD devido ao uso da biblioteca FreeSec de David Burren. É muito melhor que o DES tradicional e o bigcrypt, mas ainda não deve ser usado para novos hashes.
`CRYPT_PREFIX_MD5` (string)
  Um hash baseado no algoritmo MD5, originalmente desenvolvido por Poul-Henning Kamp para o FreeBSD. Suportado na maioria dos Unixes livres e versões mais recentes do Solaris. Não tão fraco quanto os hashes baseados em DES abaixo, mas o MD5 é tão leve em equipamentos modernos que não deve ser usado para novos hashes. O custo de processamento não é ajustável.
`CRYPT_PREFIX_BLOWFISH` (string)
  Um hash baseado na cifra de bloco Blowfish, modificado para ter um agendamento de chaves mais custoso. Originalmente desenvolvido por Niels Provos e David Mazieres para o OpenBSD e também suportado em versões recentes do FreeBSD e NetBSD, no Solaris 10 e mais recentes, e em diversas distribuições GNU/*/Linux.
`CRYPT_PREFIX_SHA256` (string)
  Um hash baseado em SHA-2 com saída de 256 bits, originalmente desenvolvido por Ulrich Drepper para a libc GNU. Suportado no Linux, mas incomum em outros lugares. Aceitável para novos hashes. O parâmetro de custo de processamento padrão é `5000`, o que é muito baixo para equipamentos modernos.
`CRYPT_PREFIX_SHA512` (string)
  Um hash baseado em SHA-2 com saída de 512 bits, originalmente desenvolvido por Ulrich Drepper para a libc GNU. Suportado no Linux, mas incomum em outros lugares. Aceitável para novos hashes. O parâmetro de custo de processamento padrão é `5000`, o que é muito baixo para equipamentos modernos.
`CRYPT_PREFIX_SCRYPT` (string)
  Scrypt é uma função de derivação de chaves baseada em senhas criada por Colin Percival, originalmente para o serviço de backup online Tarsnap. O algoritmo foi projetado especificamente para tornar custosa a execução de ataques de hardware personalizados em larga escala, exigindo grandes quantidades de memória. Em 2016, o algoritmo scrypt foi publicado pela IETF como RFC 7914.
`CRYPT_PREFIX_GOST_YESCRYPT` (string)
  Gost-yescrypt utiliza a saída de yescrypt como uma mensagem de entrada para o HMAC com a função de hash GOST R 34.11-2012 (Streebog) com um resumo de 256 bits. Assim, as propriedades criptográficas de yescrypt são substituídas pelas da função de hash GOST. Este método de hash é útil em aplicações que necessitam de hash de senha moderna, mas que dependem de algoritmos GOST. A função de hash GOST R 34.11-2012 (Streebog) foi publicada pela IETF como RFC 6986. Aceitável para novos hashes, quando necessário.
`CRYPT_PREFIX_YESCRYPT` (string)
  Yescrypt é um esquema de hash de senha escalável desenvolvido pela Solar Designer, baseado no scrypt de Colin Percival. Embora a força do yescrypt contra ataques de adivinhação de senha venha do projeto do seu algoritmo, sua segurança criptográfica é garantida pelo uso de SHA-256 na camada externa. A função de hash SHA-256 foi publicada pelo NIST na FIPS PUB 180-2 (e suas revisões subsequentes, como a FIPS PUB 180-4) e pela IETF como RFC 4634 (e posteriormente RFC 6234). Recomendado para novos hashes.
`CRYPT_PREFIX_SM3CRYPT` (string)
  Um hash baseado na função de hash ShangMi 3 com saída de 256 bits, que usa o mesmo design que sha256crypt e/ou sha512crypt. Compatível com EulerOS, Kylin, openEuler e openKylin, mas não comum em outros sistemas. Aceitável para novos hashes quando necessário. O parâmetro de custo de processamento padrão é 5000, o que é muito baixo para hardware moderno. Disponível a partir da versão 1.2.0 com libcxcrypt >= 4.5.0.
`CRYPT_PREFIX_SM3_YESCRYPT` (string)
  O Sm3-yescrypt usa a saída do yescrypt como mensagem de entrada para o HMAC com a função hash ShangMi 3 com um resumo de 256 bits. Assim, as propriedades criptográficas do yescrypt são substituídas pelas da função hash ShangMi 3. Este método de hash é útil em aplicações que precisam de hash de senha moderno, mas que dependem de algoritmos aprovados pelo Escritório de Administração Estatal de Criptografia Comercial da China (OSCCA). A função hash ShangMi 3 foi publicada na Parte 3: "Funções hash dedicadas" da ISO/IEC 10118-3:2018. Aceitável para novos hashes quando necessário. Disponível a partir da versão 1.2.0 com libcxcrypt >= 4.5.0.

Códigos de erro
`CRYPT_SALT_OK` (int)
  Nenhum erro.
`CRYPT_SALT_INVALID` (int)
  Método de hash desconhecido ou parâmetros inválidos.
`CRYPT_SALT_METHOD_DISABLED` (int)
  O método de hash não pode mais ser usado.
`CRYPT_SALT_METHOD_LEGACY` (int)
  O método de hash não é mais considerado forte o suficiente.
`CRYPT_SALT_TOO_CHEAP` (int)
  Os parâmetros de custo são considerados muito baixos.

Algoritmos de senha
`PASSWORD_SHA512` (string)
  `PASSWORD_SHA512` é usado para criar novos hashes de senha usando o algoritmo `CRYPT_PREFIX_SHA512`.
`PASSWORD_YESCRYPT` (string)
  `PASSWORD_YESCRYPT` é usado para criar novos hashes de senha usando o algoritmo `CRYPT_PREFIX_YESCRYPT`.
`PASSWORD_SM3CRYPT` (string)
  `PASSWORD_SM3CRYPT` é usado para criar novos hashes de senha usando o algoritmo `CRYPT_PREFIX_SM3CRYPT`. Disponível a partir da versão 1.2.0 com libcxcrypt >= 4.5.0.
`PASSWORD_SM3_YESCRYPT` (string)
  `PASSWORD_SM3_YESCRYPT` é usado para criar novos hashes de senha usando o algoritmo `CRYPT_PREFIX_SM3_YESCRYPT`. Disponível a partir da versão 1.2.0 com libcxcrypt >= 4.5.0.

# Funções de Xpass

# crypt_checksalt

(PECL xpass >= 1.1.0)

crypt_checksalt — Valida uma string de configuração de criptografia

### Descrição

function crypt_checksalt(string `$salt`): ?string

Verifica a string de salt em relação à configuração do sistema e informa se o método de hash e os parâmetros especificados são aceitáveis. Destina-se a ser usado para determinar se a frase-senha do usuário deve ser refeita com hash usando o método de hash preferido no momento.

### Parâmetros

`salt`
  String de salt para verificar.

### Valor Retornado

Retorna uma das constantes `CRYPT_SALT_*` como um int.

### Exemplos

Exemplo #1 Um exemplo de crypt_checksalt()

    <?php
    // Gera um salt para um método legado
    $salt = crypt_gensalt(CRYPT_PREFIX_STD_DES);
    // Verifica o salt
    $test = crypt_checksalt($salt);
    var_dump($test === CRYPT_SALT_METHOD_LEGACY);

    // Gera um salt para um método padrão
    $salt = crypt_gensalt();
    // Verifica o salt
    $test = crypt_checksalt($salt);
    var_dump($test === CRYPT_SALT_OK);
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(true)

### Veja Também

- crypt_gensalt() - Compila uma string para uso como argumento salt para crypt

# crypt_gensalt

(PECL xpass >= 1.1.0)

crypt_gensalt — Compila uma string para uso como argumento salt para crypt

### Descrição

function crypt_gensalt(string `$prefix` = `null`, int `$count` = 0): ?string

Compila uma string para uso como argumento salt para crypt().

### Parâmetros

`prefix`
  Método de hash. Uma das constantes `CRYPT_PREFIX_*`. Se `null`, o melhor método de hash disponível será selecionado.
`count`
  Controla o custo de processamento do hash; o intervalo válido e o significado exato da contagem dependem do método de hash, mas números maiores correspondem a hashes mais custosos em termos de tempo de CPU e possivelmente uso de memória. Se a contagem for `0`, um custo padrão baixo será selecionado.

### Valor Retornado

Retorna uma string com a configuração, ou `null` em caso de erro.

### Exemplos

Exemplo #1 Um exemplo de crypt_gensalt()

    <?php
    // Gera o salt
    $salt = crypt_gensalt(CRYPT_PREFIX_BLOWFISH);
    // Faz hash da senha
    $hash = crypt("secret", $salt);
    // Verifica o hash
    $test = hash_equals(crypt("secret", $hash), $hash);
    var_dump($salt, $hash, $test);
    ?>

O exemplo acima produzirá:

    string(29) "$2y$05$GcPykP.Am8C1.dGamdpwW."
    string(60) "$2y$05$GcPykP.Am8C1.dGamdpwW.1RR.7uicWvJPZfJfCEizZHqVWwuaJLm"
    bool(true)

### Veja Também

- crypt_preferred_method() - Obtém o prefixo do método de hash preferido
- crypt() - Hash unidirecional de string
- hash_equals() - Comparação de strings segura para ataque de temporização

# crypt_preferred_method

(PECL xpass >= 1.1.0)

crypt_preferred_method — Obtém o prefixo do método de hash preferido

### Descrição

function crypt_preferred_method(): ?string

Obtém o prefixo do método de hash preferido.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string com o prefixo, ou `null` em caso de erro.

### Exemplos

Exemplo #1 Um exemplo de crypt_preferred_method()

    <?php
    var_dump(crypt_preferred_method());
    ?>

O exemplo acima produzirá:

    string(3) "$y$"

### Veja Também

- crypt_gensalt() - Compila uma string para uso como argumento salt para crypt

## Índice

- crypt_checksalt — Valida uma string de configuração de criptografia
- crypt_gensalt — Compila uma string para uso como argumento salt para crypt
- crypt_preferred_method — Obtém o prefixo do método de hash preferido

- Instalação/Configuração
  - Dependências
  - Instalação via PECL
- Constantes predefinidas
- Funções de Xpass
  - crypt_checksalt — Valida uma string de configuração de criptografia
  - crypt_gensalt — Compila uma string para uso como argumento salt para crypt
  - crypt_preferred_method — Obtém o prefixo do método de hash preferido

- Hash — Estrutura de resumo de mensagens Hash
  - Instalação/Configuração
  - Constantes predefinidas
  - HashContext — The HashContext class
  - Hash Funções
- Mcrypt
  - Instalação/Configuração
  - Constantes predefinidas
  - Cifras de Mcrypt
  - Mcrypt Funções
- Mhash
  - Instalação/Configuração
  - Constantes predefinidas
  - Exemplos
  - Funções da Mhash
- OpenSSL
  - Instalação/Configuração
  - Constantes predefinidas
  - Parâmetros de chave/certificado
  - Verificação de Certificado
  - Funções de OpenSSL
  - OpenSSLCertificate — A classe OpenSSLCertificate
  - OpenSSLCertificateSigningRequest — A classe OpenSSLCertificateSigningRequest
  - OpenSSLAsymmetricKey — A classe OpenSSLAsymmetricKey
- Hash de Senhas
  - Instalação/Configuração
  - Constantes predefinidas
  - Funções da extensão Password Hashing
- Rnp
  - Instalação/Configuração
  - Constantes predefinidas
  - Exemplos
  - Funções de Rnp
  - RnpFFI — A classe RnpFFI
- Sodium
  - Instalação/Configuração
  - Constantes predefinidas
  - Funções da Sodium
  - SodiumException — A classe SodiumException
- Xpass
  - Instalação/Configuração
  - Constantes predefinidas
  - Funções de Xpass

# Extensões de Banco de Dados

# Camadas de Abstração

# Camada de abstração de banco de dados (estilo dbm)

# Introdução

Essas funções constroem a base para acessar bancos de dados estilo Berkeley DB.

Esta é uma camada de abstração geral para vários bancos de dados baseados em arquivos. Como tal, a funcionalidade é limitada a um subconjunto comum de recursos suportados por bancos de dados modernos, como » Oracle Berkeley DB.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução
- Tipos de Recurso

## Dependências

O comportamento de vários aspectos depende da implementação do banco de dados subjacente. Funções como dba_optimize() e dba_sync() farão o que prometem para um banco de dados e não farão nada para outros. Deve-se baixar e instalar manipuladores de dba suportados.

Lista de manipuladores DBA
Manipulador | Notas
--- | ---
`dbm` | Dbm é o tipo mais antigo (original) de bancos de dados estilo Berkeley DB. Deve ser evitado, se possível. Não é oferecido suporte às funções de compatibilidade incorporadas ao DB2 e ao gdbm, porque elas são compatíveis apenas no nível do código-fonte, mas não podem lidar com o formato dbm original.
`ndbm` | Ndbm é um tipo mais novo e mais flexível que dbm. Ele ainda possui a maioria dos limites arbitrários do dbm (portanto, está obsoleto).
`gdbm` | Gdbm é o » gerenciador de banco de dados GNU.
`db2` | DB2 é para » Oracle Berkeley DB 2. Ele é descrito como "um kit de ferramentas programáticas que fornece suporte de banco de dados integrado de alto desempenho para aplicativos autônomos e cliente/servidor".
`db3` | DB3 é para » Oracle Berkeley DB 3.
`db4` | DB4 é para » Oracle Berkeley DB 4 ou 5. Esta opção pode ser usada com BDB 5 a partir do PHP 5.3.3.
`cdb` | CDB é “um pacote rápido, confiável e leve para criar e ler bancos de dados constantes”. É do autor do qmail e pode ser encontrado em » http://cr.yp.to/cdb.html. Como é constante, oferecemos suporte apenas a operações de leitura. Oferecemos suporte à gravação (não à atualização) por meio da biblioteca interna cdb.
`cdb_make` | Oferecemos suporte à criação (não à atualização) de arquivos cdb quando a biblioteca cdb incluída é usada.
`flatfile` | Isto está disponível apenas para compatibilidade com a extensão obsoleta `dbm` e deve ser evitado. No entanto, pode-se usar isso onde os arquivos foram criados neste formato. Isso acontece quando o "configure" não consegue encontrar nenhuma biblioteca externa.
`inifile` | Está disponível para poder modificar arquivos php.ini a partir de scripts PHP. Ao trabalhar com arquivos INI, pode-se passar arrays no formato array(0=>group,1=>value_name) ou strings no formato "[group]value_name" onde "group" é opcional. Como as funções dba_firstkey() e dba_nextkey() retornam representações de string da chave, existe a função dba_key_split() que permite converter as chaves de string em chaves de array sem perder `false`.
`qdbm` | A biblioteca qdbm pode ser baixada em » http://fallabs.com/qdbm/index.html.
`tcadb` | A biblioteca Tokyo Cabinet pode ser baixada em » http://fallabs.com/tokyocabinet/.
`lmdb` | Isso está disponível desde o PHP 7.2.0. A biblioteca de banco de dados mapeado em memória do Lightning pode ser baixada em » https://symas.com/lmdb/.

Ao invocar as funções dba_open() ou dba_popen(), um dos nomes do manipulador deve ser fornecido como argumento. A lista de manipuladores realmente disponíveis é exibida invocando phpinfo() ou dba_handlers().

## Instalação

Usando a opção de configuração --enable-dba=shared, é possível construir um módulo carregável dinâmico para habilitar o PHP para suporte básico de bancos de dados estilo dbm. Deve-se também adicionar suporte para pelo menos um dos seguintes manipuladores, especificando --with-XXXX ou --enable-XXXX na linha de configuração do PHP.

Aviso

Após configurar e compilar o PHP, deve-se executar o seguinte teste na linha de comando: `php run-tests.php ext/dba`. Isso mostra se a combinação de manipuladores funciona. Os mais problemáticos são `dbm` e `ndbm` que entram em conflito com muitas instalações. A razão para isto é que em vários sistemas estas bibliotecas fazem parte de mais de uma outra biblioteca. O teste de configuração evita apenas que sejam configurados manipuladores únicos com defeito, mas não combinações.

Manipuladores DBA suportados
Manipulador | Controles de configuração
--- | ---
`dbm` | Para ativar o suporte para dbm, adicione --with-dbm[=DIR]. Nota: dbm normalmente é um empacotador que geralmente resulta em falhas. Isso significa que só se deve usar dbm se houver certeza de que funciona e que este formato é realmente necessário.
`ndbm` | Para ativar o suporte para ndbm, adicione --with-ndbm[=DIR]. Nota: O ndbm normalmente é um empacotador que geralmente resulta em falhas. Isso significa que só se deve usar ndbm se houver certeza de que funciona e que este formato é realmente necessário.
`gdbm` | Para ativar o suporte para gdbm, adicione --with-gdbm[=DIR].
`db2` | Para ativar o suporte para Oracle Berkeley DB 2, adicione --with-db2[=DIR]. Nota: db2 entra em conflito com db3 e db4.
`db3` | Para ativar o suporte para Oracle Berkeley DB 3, adicione --with-db3[=DIR]. Nota: db3 entra em conflito com db2 e db4.
`db4` | Para ativar o suporte para Oracle Berkeley DB 4 ou 5, adicione --with-db4[=DIR]. Nota: db4 entra em conflito com db2 e db3. Nota: As bibliotecas db com versões 4.1 a 4.1.24 não podem ser usadas em nenhuma versão do PHP. O suporte para BDB 5 foi adicionado no PHP 5.3.3.
`cdb` | Para ativar o suporte para cdb, adicione --with-cdb[=DIR]. Nota: Pode-se omitir DIR para usar a biblioteca cdb incluída que adiciona o manipulador cdb_make que permite a criação de arquivos cdb e permite acessar arquivos cdb na rede usando fluxos do PHP.
`flatfile` | Para ativar o suporte para flatfile, adicione --enable-flatfile. Antes do PHP 5.2.1, o --with-flatfile tinha que ser usado no lugar. Nota: Isto foi adicionado para adicionar compatibilidade com a extensão `dbm` obsoleta. Use esse manipulador somente quando não for possível instalar uma das bibliotecas exigidas pelos outros manipuladores e quando não for possível usar o manipulador cdb incluído.
`inifile` | Para ativar o suporte para `inifile`, adicione --enable-inifile. Antes do PHP 5.2.1, o --with-inifile tinha que ser usado no lugar. Nota: Isto foi adicionado para permitir a leitura e configuração de arquivos .ini no estilo Microsoft (como o arquivo php.ini).
`qdbm` | Para ativar o suporte para qdbm, adicione --with-qdbm[=DIR]. Nota: qdbm entra em conflito com dbm e gdbm. Nota: A biblioteca qdbm pode ser baixada em » http://fallabs.com/qdbm/index.html.
`tcadb` | Para ativar o suporte para Tokyo Cabinet, adicione --with-tcadb[=DIR]. Nota: A bliblioteca Tokyo Cabinet pode ser baixada em » http://fallabs.com/tokyocabinet/.
`lmdb` | Para ativar o suporte para Lightning Memory-Mapped, adicione --with-lmdb[=DIR]. Nota: Isso foi adicionado no PHP 7.2.0. A biblioteca de banco de dados Lightning Memory-Mapped pode ser baixada em » https://symas.com/lmdb/.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de Configuração de DBA
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
dba.default_handler | DBA_DEFAULT | `INI_ALL` |

Aqui está uma breve explicação das diretivas de configuração.

`dba.default_handler` string
  O nome do manipulador padrão

## Tipos de Recurso

Antes do PHP 8.4.0, a maioria das funções DBA retornavam ou operavam sobre recursos (ex.: dba_open() retorna um identificador positivo de conexão DBA requerido pela maior parte das funções DBA).

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`DBA_LMDB_USE_SUB_DIR` (int)
  Opção do Driver LMDB para permitir a criação de um subdiretório para os arquivos do banco de dados. Disponível a partir do PHP 8.2.0.
`DBA_LMDB_NO_SUB_DIR` (int)
  Opção do driver LMDB para não permitir a criação de um subdiretório para os arquivos do banco de dados. Disponível a partir do PHP 8.2.0.

# Exemplos

## Índice

- Uso básico

## Uso básico

Exemplo #1 Exemplos de DBA

    <?php

    $id = dba_open("/tmp/test.db", "n", "db2");

    if (!$id) {
        echo "dba_open falhou\n";
        exit;
    }

    dba_replace("key", "Isto é um exemplo!", $id);

    if (dba_exists("key", $id)) {
        echo dba_fetch("key", $id);
        dba_delete("key", $id);
    }

    dba_close($id);
    ?>

O DBA é binário seguro e não possui limites arbitrários. No entanto, herda todos os limites definidos pela implementação do banco de dados subjacente.

Todos os bancos de dados baseados em arquivo devem fornecer uma maneira de definir o modo de arquivo de um novo banco de dados criado, se isso for possível. O modo de arquivo é comumente passado como o quarto argumento para dba_open() ou dba_popen().

Pode-se acessar todas as entradas de um banco de dados de forma linear usando as funções dba_firstkey() e dba_nextkey(). O banco de dados não pode ser alterado enquanto percorrido.

Exemplo #2 Percorrendo um banco de dados

    <?php

    // ...banco de dados aberto...

    $key = dba_firstkey($id);

    while ($key !== false) {
        if (true) {          // lembre-se da chave para realizar alguma ação mais tarde
            $handle_later[] = $key;
        }
        $key = dba_nextkey($id);
    }

    foreach ($handle_later as $val) {
        dba_delete($val, $id);
    }

    ?>

# A classe Dba\Connection

(PHP 8 >= 8.4.0)

## Introdução

Uma classe totalmente opaca que substitui um recurso `dba` a partir do PHP 8.4.0.

## Resumo da classe

namespace Dba;
final class Connection {
}

# Funções de DBA

# dba_close

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_close — Fecha um banco de dados DBA

### Descrição

function dba_close(Dba\Connection `$dba`): void

dba_close() fecha o banco de dados e libera todos os recursos do identificador de banco de dados especificado.

### Parâmetros

`dba`
  Uma instância de Dba\Connection, retornada por dba_open() ou dba_popen().

### Valor Retornado

Nenhum valor é retornado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | O parâmetro `dba` agora espera uma instância deDba\Connection; anteriormente, um resource `dba` válido era esperado.

### Veja Também

- dba_open() - Abre um banco de dados
- dba_popen() - Abre o banco de dados de forma persistente

# dba_delete

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_delete — Remove uma entrada DBA especificada por chave

### Descrição

function dba_delete(string|array `$key`, Dba\Connection `$dba`): bool

dba_delete() remove do banco de dados a entrada especificada.

### Parâmetros

`key`
  A chave da entrada a ser removida.
`dba`
  Uma instância de Dba\Connection, retornada por dba_open() ou dba_popen().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | O parâmetro `dba` agora espera uma instância deDba\Connection; anteriormente, um resource `dba` válido era esperado.

### Veja Também

- dba_exists() - Verifica existência de uma chave
- dba_fetch() - Busca dados especificados por chave
- dba_insert() - Insere entrada
- dba_replace() - Substitui ou insere uma entrada

# dba_exists

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_exists — Verifica existência de uma chave

### Descrição

function dba_exists(string|array `$key`, Dba\Connection `$dba`): bool

dba_exists() verifica se a chave especificada em `key` existe no banco de dados.

### Parâmetros

`key`
  A chave para a qual a verificação é realizada.
`dba`
  Uma instância de Dba\Connection, retornada por dba_open() ou dba_popen().

### Valor Retornado

Retorna `true` se a chave existir, `false` caso contrário.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | O parâmetro `dba` agora espera uma instância deDba\Connection; anteriormente, um resource `dba` válido era esperado.

### Veja Também

- dba_delete() - Remove uma entrada DBA especificada por chave
- dba_fetch() - Busca dados especificados por chave
- dba_insert() - Insere entrada
- dba_replace() - Substitui ou insere uma entrada

# dba_fetch

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_fetch — Busca dados especificados por chave

### Descrição

function dba_fetch(string|array `$key`, Dba\Connection `$dba`, int `$skip` = 0): string|false

Assinatura sobrecarregada, preterida a partir do PHP 8.3.0:

function dba_fetch(string|array `$key`, int `$skip`, resource `$dba`): string

dba_fetch() busca os dados especificados pela chave em `key` do banco de dados especificado por `dba`.

### Parâmetros

`key`
  A chave pela qual os dados são especificados.

  > Nota: Ao trabalhar com arquivos INI, eta função aceita arrays como chaves onde o índice 0 é o grupo e o índice 1 é o nome do valor. Consulte: dba_key_split().

`dba`
  Uma instância de Dba\Connection, retornada por dba_open() ou dba_popen().
`skip`
  O número de pares chave-valor a ignorar no uso de bancos de dados CDB. Este valor é ignorado para todos os outros bancos de dados que não suportam múltiplas chaves com o mesmo nome.

### Valor Retornado

Retorna a string associada se o par chave/dados for encontrado, `false` caso contrário.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | O parâmetro `dba` agora espera uma instância deDba\Connection; anteriormente, um resource `dba` válido era esperado.
8.3.0 | Chamar dba_fetch() com `dba` no 3º argumento agora foi descontinuado.
8.2.0 | O argumento opcional "skip" de dba_fetch() fica agora no final, alinhado com a semântica das funções de usuário do PHP. A assinatura anterior com sobrecarga ainda é aceita porém desencorajada.

### Veja Também

- dba_exists() - Verifica existência de uma chave
- dba_delete() - Remove uma entrada DBA especificada por chave
- dba_insert() - Insere entrada
- dba_replace() - Substitui ou insere uma entrada
- dba_key_split() - Divide uma chave em representação string para uma representação array

# dba_firstkey

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_firstkey — Busca a primeira chave

### Descrição

function dba_firstkey(Dba\Connection `$dba`): string|false

dba_firstkey() retorna a primeira chave do banco de dados e redefine o ponteiro interno de chaves. Isto permite uma pesquisa linear por todo o banco de dados.

### Parâmetros

`dba`
  Uma instância de Dba\Connection, retornada por dba_open() ou dba_popen().

### Valor Retornado

Retorna a chave em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | O parâmetro `dba` agora espera uma instância deDba\Connection; anteriormente, um resource `dba` válido era esperado.

### Veja Também

- dba_nextkey() - Busca a próxima chave
- dba_key_split() - Divide uma chave em representação string para uma representação array
- Exemplo 2 nos exemplos DBA

# dba_handlers

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

dba_handlers — Lista todos os manipuladores disponíveis

### Descrição

function dba_handlers(bool `$full_info` = `false`): array

dba_handlers() lista todos os manipuladores suportados por esta extensão.

### Parâmetros

`full_info`
  Liga/desliga a exibição de informação completa no resultado.

### Valor Retornado

Retorna um array de manipuladores de bancos de dados. Se `full_info` for definido para `true`, o array será associativo com os nomes dos manipuladores como chaves, e suas informações de versão como valores. Caso contrário, o resultado será um array indexado de nomes de manipuladores.

> Nota: Quando a biblioteca CDB interna estiver em uso, o resultado será `cdb` e `cdb_make`.

### Exemplos

Exemplo #1 Exemplo de dba_handlers()

    <?php

    echo "Manipuladores DBA disponíveis:\n";
    foreach (dba_handlers(true) as $handler_name => $handler_version) {
      // limpa as versões
      $handler_version = str_replace('$', '', $handler_version);
      echo " - $handler_name: $handler_version\n";
    }

    ?>

O exemplo acima produzirá algo semelhante a:

    Manipuladores DBA disponíveis:
     - cdb: 0.75, Revision: 1.3.2.3
     - cdb_make: 0.75, Revision: 1.2.2.4
     - db2: Sleepycat Software: Berkeley DB 2.7.7: (08/20/99)
     - inifile: 1.0, Revision: 1.6.2.3
     - flatfile: 1.0, Revision: 1.5.2.4

# dba_insert

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_insert — Insere entrada

### Descrição

function dba_insert(string|array `$key`, string `$value`, Dba\Connection `$dba`): bool

dba_insert() insere a entrada descrita por `key` e `value` no banco de dados.

### Parâmetros

`key`
  A chave da entrada a ser inserida. Se eta chave já existir no banco de dados, a função falhará. Use dba_replace() se for necessário substituir uma chave existente.
`value`
  O valor a ser inserido.
`dba`
  Uma instância de Dba\Connection, retornada por dba_open() ou dba_popen().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | O parâmetro `dba` agora espera uma instância deDba\Connection; anteriormente, um resource `dba` válido era esperado.

### Veja Também

- dba_exists() - Verifica existência de uma chave
- dba_delete() - Remove uma entrada DBA especificada por chave
- dba_fetch() - Busca dados especificados por chave
- dba_replace() - Substitui ou insere uma entrada

# dba_key_split

(PHP 5, PHP 7, PHP 8)

dba_key_split — Divide uma chave em representação string para uma representação array

### Descrição

function dba_key_split(string|false|null `$key`): array|false

dba_key_split() divide uma chave (representação string) para uma representação array.

### Parâmetros

`key`
  A chave em representação string.

### Valor Retornado

Retorna um array na forma `array(0 => grupo, 1 => nome_valor)`. Esta função retornará `false` se `key` for `null` ou `false`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Passar `null` ou `false` em `key` agora está descontinuado.

### Veja Também

- dba_firstkey() - Busca a primeira chave
- dba_nextkey() - Busca a próxima chave
- dba_fetch() - Busca dados especificados por chave

# dba_list

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

dba_list — Lista todos os arquivos de banco de dados abertos

### Descrição

function dba_list(): array

dba_list() lista todos os arquivos de banco de dados abertos.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array associativo, na forma `id_recurso => nome_arquivo`.

# dba_nextkey

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_nextkey — Busca a próxima chave

### Descrição

function dba_nextkey(Dba\Connection `$dba`): string|false

dba_nextkey() retorna a próxima chave do banco de dados e avança o ponteiro interno de chaves.

### Parâmetros

`dba`
  Uma instância de Dba\Connection, retornada por dba_open() ou dba_popen().

### Valor Retornado

Retorna a chave em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | O parâmetro `dba` agora espera uma instância deDba\Connection; anteriormente, um resource `dba` válido era esperado.

### Veja Também

- dba_firstkey() - Busca a primeira chave
- dba_key_split() - Divide uma chave em representação string para uma representação array
- Exemplo 2 nos exemplos DBA

# dba_open

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_open — Abre um banco de dados

### Descrição

function dba_open(
string `$path`,
string `$mode`,
?string `$handler` = `null`,
int `$permission` = 0644,
int `$map_size` = 0,
?int `$flags` = `null`
): Dba\Connection|false

dba_open() estabelece uma instância de banco de dados para o arquivo especificado em `path` no modo definido por `mode` usando o manipulador informado em `handler`.

### Parâmetros

`path`
  Normalmente um caminho comum no seu sistema de arquivos.
`mode`
  Define os modos: `r` para acesso de leitura, `w` para acesso de leitura/gravação a um baco de dados já existente, `c` para leitura/gravação e criação de banco de dados se ainda não existir, e `n` para criar, truncar e acesso leitura/gravação. O banco de dados é criado modo de árvore binária (BTree), outros modos (como Hash ou Queue) não são suportados. Além disso, pode ser definido o método de trava do banco de dados com o próximo caractere. Use `l` para travar o banco de dados com um arquivo .lck ou `d` para travar o próprio arquivo de banco de dados. É importante que todas as aplicações façam isso de forma consistente. Se a intenção for testar o acesso e não esperar pela trava, pode-se adicionar `t` como terceiro caractere. Quando houver certeza absoluta de que não é necessário travar o banco de dados, pode-se fazê-lo usando `-` em vez de `l` ou `d`. Quando nenhum dos caracteres `d`, `l` ou `-` forem usados, o DBA irá travar o arquivo de banco de dados como faria com `d`.

  > Nota:

  > Só pode haver um gravador para um arquivo de banco de dados. Quando um DBA é usados em um servidor web e mais de uma solicitação requerer operações de gravação, elas só poderão ser feitas uma após a outra. Também não será permitido ler durante a gravação. A extensão DBA usa travas para evitar isso. Veja a tabela a seguir:

  > Travas DBA
  > já aberto | `mode` = "rl" | `mode` = "rlt" | `mode` = "wl" | `mode` = "wlt" | `mode` = "rd" | `mode` = "rdt" | `mode` = "wd" | `mode` = "wdt"
  > --- | --- | --- | --- | --- | --- | --- | --- | ---
  > não aberto | ok | ok | ok | ok | ok | ok | ok | ok
  > `mode` = "rl" | ok | ok | espera | falso | ilegal | ilegal | ilegal | ilegal
  > `mode` = "wl" | espera | falso | espera | falso | ilegal | ilegal | ilegal | ilegal
  > `mode` = "rd" | ilegal | ilegal | ilegal | ilegal | ok | ok | espera | falso
  > `mode` = "wd" | ilegal | ilegal | ilegal | ilegal | espera | falso | espera | falso

  > - ok: a segunda chamada será bem sucedida.
  > - espera: a segunda chamada espera até que dba_close() seja chamada para a primeira.
  > - falso: a segunda chamada retorna falso.
  > - ilegal: não se deve misturar os modificadores `"l"` e `"d"` no parâmetro `mode`.

`handler`
  O nome do manipulador que deve ser usado para acessar o arquivo definido em `path`. São passados ​​todos os parâmetros opcionais fornecidos para dba_open() e pode agir em nome deles. Se `handler` for `null`, o manipulador padrão será invocado.
`permission`
  Parâmetro opcional int que é passado ao driver. Tem o mesmo significado que o parâmetro `permissions` de chmod() (*nix) e o padrão é `0644`. Os drivers `db1`, `db2`, `db3`, `db4`, `dbm`, `gdbm`, `ndbm` e `lmdb` suportam o parâmetro `permission`.
`map_size`
  Parâmetro opcional int que é passado ao driver. Seu valor deve ser um múltiplo do tamanho da página do sistema operacional, ou zero, para usar o tamanho padrão do mapa. Somente o driver `lmdb` aceita o parâmetro `map_size`.
`flags`
  Opções a serem passadas aos drivers de banco de dados. Se for `null`, as opções padrão serão passadas. Atualmente, apenas o driver LMDB suporta as opções `DBA_LMDB_USE_SUB_DIR` e `DBA_LMDB_NO_SUB_DIR`.

### Valor Retornado

Retorna uma instância de Dba\Connection em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

`false` é retornado e um erro de nível `E_WARNING` é emitido quando `handler` for `null` mas não houver manipulador padrão.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Retorna agora uma instância de Dba\Connection; anteriormente, retornava um resource.
8.2.0 | `flags` foi adicionado.
8.2.0 | `handler` agora pode ser nulo.
7.3.14, 7.4.2 | O driver `lmdb` agora suporta o parâmetro adicional `map_size`.

### Veja Também

- dba_popen() - Abre o banco de dados de forma persistente
- dba_close() - Fecha um banco de dados DBA

# dba_optimize

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_optimize — Otimiza o banco de dados

### Descrição

function dba_optimize(Dba\Connection `$dba`): bool

dba_optimize() otimiza o banco de dados subjacente.

### Parâmetros

`dba`
  Uma instância de Dba\Connection, retornada por dba_open() ou dba_popen().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | O parâmetro `dba` agora espera uma instância deDba\Connection; anteriormente, um resource `dba` válido era esperado.

### Veja Também

- dba_sync() - Sincroniza o banco de dados

# dba_popen

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_popen — Abre o banco de dados de forma persistente

### Descrição

function dba_popen(
string `$path`,
string `$mode`,
?string `$handler` = `null`,
int `$permission` = 0644,
int `$map_size` = 0,
?int `$flags` = `null`
): Dba\Connection|false

dba_popen() estabelece uma instância persistente do banco de dados informado em `path` com o modo definido por `mode` usando o manipulador especificado em `handler`.

### Parâmetros

`path`
  Normalmente um caminho comum no seu sistema de arquivos.
`mode`
  Define os modos: `r` para acesso de leitura, `w` para acesso de leitura/gravação a um baco de dados já existente, `c` para leitura/gravação e criação de banco de dados se ainda não existir, e `n` para criar, truncar e acesso leitura/gravação.
`handler`
  O nome do manipulador que deve ser usado para acessar o arquivo definido em `path`. São passados ​​todos os parâmetros opcionais fornecidos para dba_popen() e pode agir em nome deles. Se `handler` for `null`, o manipulador padrão será invocado.
`permission`
  Parâmetro opcional int que é passado ao driver. Tem o mesmo significado que o parâmetro `permissions` de chmod() (*nix) e o padrão é `0644`. Os drivers `db1`, `db2`, `db3`, `db4`, `dbm`, `gdbm`, `ndbm` e `lmdb` suportam o parâmetro `permission`.
`map_size`
  Parâmetro opcional int que é passado ao driver. Seu valor deve ser um múltiplo do tamanho da página do sistema operacional, ou zero, para usar o tamanho padrão do mapa. Somente o driver `lmdb` aceita o parâmetro `map_size`.
`flags`
  Permite passar opções aos drivers de banco de dados. Atualmente, suporte apenas ao driver LMDB com as opções `DBA_LMDB_USE_SUB_DIR` e `DBA_LMDB_NO_SUB_DIR`.

### Valor Retornado

Retorna uma instância de Dba\Connection em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

`false` é retornado e um erro de nível `E_WARNING` é emitido quando `handler` for `null` mas não houver manipulador padrão.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Retorna agora uma instância de Dba\Connection; anteriormente, retornava um resource.
8.2.0 | `flags` foi adicionado.
8.1.0 | `handler` agora pode ser nulo.
7.3.14, 7.4.2 | O driver `lmdb` agora suporta o parâmetro adicional `map_size`.

### Veja Também

- dba_open() - Abre um banco de dados
- dba_close() - Fecha um banco de dados DBA

# dba_replace

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_replace — Substitui ou insere uma entrada

### Descrição

function dba_replace(string|array `$key`, string `$value`, Dba\Connection `$dba`): bool

A função dba_replace() substitui ou insere a entrada descrita com a chave `key` e o valor `value` no banco de dados especificado por `dba`.

### Parâmetros

`key`
  A chave da entrada a ser substituída.
`value`
  O valor a ser substituído.
`dba`
  Uma instância de Dba\Connection, retornada por dba_open() ou dba_popen().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | O parâmetro `dba` agora espera uma instância deDba\Connection; anteriormente, um resource `dba` válido era esperado.

### Veja Também

- dba_exists() - Verifica existência de uma chave
- dba_delete() - Remove uma entrada DBA especificada por chave
- dba_fetch() - Busca dados especificados por chave
- dba_insert() - Insere entrada

# dba_sync

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_sync — Sincroniza o banco de dados

### Descrição

function dba_sync(Dba\Connection `$dba`): bool

A função dba_sync() sincroniza o banco de dados. Isto provavelmente irá disparar uma escrita física no disco, caso suportado.

### Parâmetros

`dba`
  Uma instância de Dba\Connection, retornada por dba_open() ou dba_popen().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | O parâmetro `dba` agora espera uma instância deDba\Connection; anteriormente, um resource `dba` válido era esperado.

### Veja Também

- dba_optimize() - Otimiza o banco de dados

## Índice

- dba_close — Fecha um banco de dados DBA
- dba_delete — Remove uma entrada DBA especificada por chave
- dba_exists — Verifica existência de uma chave
- dba_fetch — Busca dados especificados por chave
- dba_firstkey — Busca a primeira chave
- dba_handlers — Lista todos os manipuladores disponíveis
- dba_insert — Insere entrada
- dba_key_split — Divide uma chave em representação string para uma representação array
- dba_list — Lista todos os arquivos de banco de dados abertos
- dba_nextkey — Busca a próxima chave
- dba_open — Abre um banco de dados
- dba_optimize — Otimiza o banco de dados
- dba_popen — Abre o banco de dados de forma persistente
- dba_replace — Substitui ou insere uma entrada
- dba_sync — Sincroniza o banco de dados

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
  - Tipos de Recurso
- Constantes predefinidas
- Exemplos
  - Uso básico
- Dba\Connection — A classe Dba\Connection
- Funções de DBA
  - dba_close — Fecha um banco de dados DBA
  - dba_delete — Remove uma entrada DBA especificada por chave
  - dba_exists — Verifica existência de uma chave
  - dba_fetch — Busca dados especificados por chave
  - dba_firstkey — Busca a primeira chave
  - dba_handlers — Lista todos os manipuladores disponíveis
  - dba_insert — Insere entrada
  - dba_key_split — Divide uma chave em representação string para uma representação array
  - dba_list — Lista todos os arquivos de banco de dados abertos
  - dba_nextkey — Busca a próxima chave
  - dba_open — Abre um banco de dados
  - dba_optimize — Otimiza o banco de dados
  - dba_popen — Abre o banco de dados de forma persistente
  - dba_replace — Substitui ou insere uma entrada
  - dba_sync — Sincroniza o banco de dados

# ODBC (Unificado)

# Introdução

Em adição ao suporte ODBC normal, as funções de ODBC Unificadas no PHP permitem sejam acessados vários bancos de dados que emprestaram a semântica da API do ODBC para implementer a sua própria API. Ao invés de manter múltiplos drivers de banco de dados que são todos praticamente identicos, estes drivers foram unificados em um único conjunto de funções ODBC.

Os seguintes bancos de dados são suportados pelas funções de OBDC Unificado: » Adabas D, » IBM DB2, » iODBC, » Solid e » Sybase SQL Anywhere.

> Nota: Com a exceção de iODBC, não existe ODBC envolvido ao conectar aos bancos de dados acima. As funções usadas para conversar nativamente com eles apenas compartilham os mesmos nomes e a mesma sintaxe das funções ODBC. Entretanto, compilar o PHP com suporte a iODBC permite usar qualquer dirver compatível com ODBC nas aplicações PHP. Maiores informações sobre iODBC estão disponíveis em » www.iodbc.org com a alternativa unixODBC disponível em » www.unixodbc.org.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução
- Tipos de Recurso

## Dependências

Para acessar qualquer dos bancos de dados suportados, todas as bibliotecas necessárias devem estar instaladas.

## Instalação

--with-adabas[=DIR]

  Inclui suporte a Adabas D. DIR é o diretório base da instalação do Adabas, o padrão é /usr/local.

--with-sapdb[=DIR]

  Inclui suporte a SAP DB. DIR é o diretório base SAP DB, o padrão é /usr/local.

--with-solid[=DIR]

  Inclui o suporte Solid. DIR é o diretório base da instalação Solid, o padrão é /usr/local/solid.

--with-ibm-db2[=DIR]

  Inclui suporte ao IBM DB2. DIR é o diretório base da instalaçação do DB2, o padrão é /home/db2inst1/sqllib.

--with-empress[=DIR]

  Inclui suporte a Empress. DIR é o diretório base da instalação do Empress, o padrão é $EMPRESSPATH. Esta opção suporta apenas o Empress Versão 8.60 e posteriores.

--with-empress-bcs[=DIR]

  Inclui suporte a `"Empress Local Access"`. DIR é o diretório base da instalação do Empress, o padrão é $EMPRESSPATH. Esta opção suporta apenas o Empress Version 8.60 e posteriores.

--with-birdstep[=DIR]

  Inclui suporte Birdstep. DIR é o diretório base da instalação do Birdstep, o padrão é /usr/local/birdstep.

--with-custom-odbc[=DIR]

  Inclui um suporte ODBC definido pelo usuário. DIR é o diretório base da instalação do ODBC, o padrão é /usr/local. Tenha certeza de definir CUSTOM_ODBC_LIBS e ter algum odbc.h nos seus diretórios de inclusão. Ex., você deve definir o seguinte para Sybase SQL Anywhere 5.5.00 no QNX, antes de executar o script "configure":

         CPPFLAGS="-DODBC_QNX -DSQLANY_BUG"
         LDFLAGS=-lunix
         CUSTOM_ODBC_LIBS="-ldblib -lodbc".

--with-iodbc[=DIR]

  Inclui o suporte a iODBC. DIR é o diretório base da instalação do iODBC, o pardrão é /usr/local.

--with-esoob[=DIR]

  Inclui suporte a Easysoft OOB. DIR é o diretório base da instalação OOB, o padrão é /usr/local/easysoft/oob/client.

--with-unixODBC[=DIR]

  Inclui suporte a unixODBC. DIR é o diretório base da instalação unixODBC, o padrão é /usr/local.

--with-openlink[=DIR]

  Inclui suporte a OpenLink ODBC. DIR é o diretório base da instalação do OpenLink, o padrão é /usr/local. Este é o mesmo que iODBC.

--with-dbmaker[=DIR]

  Inclui suporte a DBMaker. DIR é o diretório base da instalação do DBMaker, o padrão é o local da instalação mais recente do DBMaker (algo como /home/dbmaker/3.6).

Usuários do Windows precisam habilitar a php_odbc.dll para usar esta extensão.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de configuração de Unified ODBC
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
odbc.allow_persistent | "1" | `INI_SYSTEM` |
odbc.check_persistent | "1" | `INI_SYSTEM` |
odbc.max_persistent | "-1" | `INI_SYSTEM` |
odbc.max_links | "-1" | `INI_SYSTEM` |
odbc.defaultlrl | "4096" | `INI_ALL` |
odbc.defaultbinmode | "1" | `INI_ALL` |
odbc.default_cursortype | "3" | `INI_ALL` |

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`odbc.default_db` string

  Fonte de dados ODBC que será usada se nenhuma for especificada em odbc_connect() ou odbc_pconnect().

`odbc.default_user` string

  Nome de usuário que será usado se nenhum for especificado em odbc_connect() ou odbc_pconnect().

`odbc.default_pw` string

  Senha que será usada se nenhuma for especificada em odbc_connect() ou odbc_pconnect().

`odbc.allow_persistent` bool

  Define se serão permitidas conexões ODBC persistentes.

`odbc.check_persistent` bool

  Verifica se uma conexão ainda está válida antes de seu reúso.

`odbc.max_persistent` int

  O número máximo de conexões ODBC persistentes por processo.

`odbc.max_links` int

  O número máximo de conexões ODBC por processo, incluindo conexões persistentes.

`odbc.defaultlrl` int

  Manipulação de campos LONG. Especifica o número de bytes retornados às variáveis. Veja odbc_longreadlen() para detalhes.

  Quando um int é usado, o valor é medido em bytes. A notação abreviada, como descrita nesta FAQ, também pode ser usada.
`odbc.defaultbinmode` int

  Manipulação de dados binários. Veja odbc_binmode() para detalhes.

`odbc.default_cursortype` int

  Controla o modelo de cursor ODBC. Valores possíveis são `SQL_CURSOR_FORWARD_ONLY`, `SQL_CURSOR_KEYSET_DRIVEN`, `SQL_CURSOR_DYNAMIC` e `SQL_CURSOR_STATIC` (padrão).

## Tipos de Recurso

Em versões anteriores ao PHP 8.4.0, esta extensão definia dois tipos recurso: uma identificador de conexão ODBC e um identificador de resultado ODBC.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`ODBC_TYPE` (string)
`ODBC_BINMODE_PASSTHRU` (int)
`ODBC_BINMODE_RETURN` (int)
`ODBC_BINMODE_CONVERT` (int)
`SQL_ODBC_CURSORS` (int)
`SQL_CUR_USE_DRIVER` (int)
`SQL_CUR_USE_IF_NEEDED` (int)
`SQL_CUR_USE_ODBC` (int)
`SQL_CONCURRENCY` (int)
`SQL_CONCUR_READ_ONLY` (int)
`SQL_CONCUR_LOCK` (int)
`SQL_CONCUR_ROWVER` (int)
`SQL_CONCUR_VALUES` (int)
`SQL_CURSOR_TYPE` (int)
`SQL_CURSOR_FORWARD_ONLY` (int)
`SQL_CURSOR_KEYSET_DRIVEN` (int)
`SQL_CURSOR_DYNAMIC` (int)
`SQL_CURSOR_STATIC` (int)
`SQL_KEYSET_SIZE` (int)
`SQL_CHAR` (int)
`SQL_VARCHAR` (int)
`SQL_LONGVARCHAR` (int)
`SQL_WCHAR` (int)
  String de caracteres Unicode de comprimento fixo de string.
`SQL_WVARCHAR` (int)
  String com caracteres Unicode de comprimentos variáveis.
`SQL_WLONGVARCHAR` (int)
  Dados de caracteres Unicode de comprimentos variáveis. O comprimento máximo é dependente da fonte de dados.
`SQL_DECIMAL` (int)
`SQL_NUMERIC` (int)
`SQL_BIT` (int)
`SQL_TINYINT` (int)
`SQL_SMALLINT` (int)
`SQL_INTEGER` (int)
`SQL_BIGINT` (int)
`SQL_REAL` (int)
`SQL_FLOAT` (int)
`SQL_DOUBLE` (int)
`SQL_BINARY` (int)
`SQL_VARBINARY` (int)
`SQL_LONGVARBINARY` (int)
`SQL_DATE` (int)
`SQL_TIME` (int)
`SQL_TIMESTAMP` (int)
`SQL_TYPE_DATE` (int)
`SQL_TYPE_TIME` (int)
`SQL_TYPE_TIMESTAMP` (int)
`SQL_BEST_ROWID` (int)
`SQL_ROWVER` (int)
`SQL_SCOPE_CURROW` (int)
`SQL_SCOPE_TRANSACTION` (int)
`SQL_SCOPE_SESSION` (int)
`SQL_NO_NULLS` (int)
`SQL_NULLABLE` (int)
`SQL_INDEX_UNIQUE` (int)
`SQL_INDEX_ALL` (int)
`SQL_ENSURE` (int)
`SQL_QUICK` (int)
`SQL_FETCH_FIRST` (int)
  Retorna a primeira linha do resultado.
`SQL_FETCH_NEXT` (int)
  Retorna a próxima linha do resultado.

# Funções de ODBC

# odbc_autocommit

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_autocommit — Alterna o comportamento da autoconfirmação

### Descrição

function odbc_autocommit(Odbc\Connection `$odbc`, ?bool `$enable` = `null`): int|bool

Alterna o comportamento da autoconfirmação.

Por padrão, a autoconfirmação fica habilitada para uma conexão. Desabilitar a autoconfirmação é equivalente a iniciar uma transação.

### Parâmetros

`odbc`
  O objeto da conexão ODBC. Consulte odbc_connect() para obter detalhes.
`enable`

  Se `enable` for igual a `true`, a autoconfirmação é habilitada, se for igual a `false`, a autoconfirmação é desabilitada. Se for igual a `null`, esta função retorna o status da auto confirmação para a conexão informada em `odbc`.

### Valor Retornado

Com o parâmetro `enable` igual a `null`, esta função retorna o status da autoconfirmação para `odbc`. Um valor diferente de zero é retornado se a autoconfirmação estiver habilitada, 0 se estiver desabilitada ou `false` se um erro ocorrer.

Se `enable` não for nulo, esta função retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `odbc` agora espera uma instância de Odbc\Connection; anteriormente, esperava um resource.
8.3.0 | `enable` agora pode ser nulo.

### Veja Também

- odbc_commit() - Confirma uma transação ODBC
- odbc_rollback() - Reverte uma transação

# odbc_binmode

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_binmode — Manipulação de dados de colunas binárias

### Descrição

function odbc_binmode(Odbc\Result `$statement`, int `$mode`): true

Controla a manipulação de dados de colunas binárias. Os tipos SQL ODBC afetados são `BINARY`, `VARBINARY` e `LONGVARBINARY`. O modo padrão pode ser definido usando a diretiva uodbc.defaultbinmode do php.ini.

Quando dados SQL binários são convertidos em dados de caracteres C (`ODBC_BINMODE_CONVERT`), cada byte (8 bits) dos dados de origem é representado como dois caracteres ASCII. Esses caracteres são a representação de caracteres ASCII do número em sua forma hexadecimal. Por exemplo, um binário `00000001` é convertido em `"01"` e um binário `11111111` é convertido em `"FF"` .

Embora o tratamento das colunas `BINARY` e `VARBINARY` dependa apenas do "binmode", o tratamento das colunas `LONGVARBINARY` também depende do "longreadlen":

Manipulação de LONGVARBINARY
binmode | longreadlen | resultado
--- | --- | ---
`ODBC_BINMODE_PASSTHRU` | 0 | intermediário
`ODBC_BINMODE_RETURN` | 0 | intermediário
`ODBC_BINMODE_CONVERT` | 0 | intermediário
`ODBC_BINMODE_PASSTHRU` | >0 | intermediário
`ODBC_BINMODE_RETURN` | >0 | retorna como está
`ODBC_BINMODE_CONVERT` | >0 | retorna como char

Se odbc_fetch_into() for usada, "intermediário" significa que uma string vazia será retornada para essas colunas. Se odbc_result() for usada, "intermediário" significa que os dados são enviados diretamente ao cliente (ou seja, exibidos).

### Parâmetros

`statement`

  O objeto de resultado ODBC.

`mode`

  Valores possíveis para `mode` são:

  - `ODBC_BINMODE_PASSTHRU`: Intermediário para dados BINARY
  - `ODBC_BINMODE_RETURN`: Retorna como está
  - `ODBC_BINMODE_CONVERT`: Converte para "char" e retorna

  > Nota: A manipulação de colunas de binários longos também é afetada por odbc_longreadlen().

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `statement` agora espera uma instância de Odbc\Result; anteriormente, esperava um resource.

# odbc_close

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_close — Fecha uma conexão ODBC

### Descrição

function odbc_close(Odbc\Connection `$odbc`): void

Fecha a conexão com o servidor de banco de dados.

### Parâmetros

`odbc`
  O objeto da conexão ODBC. Consulte odbc_connect() para obter detalhes.

### Valor Retornado

Nenhum valor é retornado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `odbc` agora espera uma instância de Odbc\Connection; anteriormente, esperava um resource.

### Notas

> Nota:

> Esta função falhará se houver transações abertas nesta conexão. A conexão permanecerá aberta neste caso.

# odbc_close_all

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_close_all — Fecha todas as conexões ODBC

### Descrição

function odbc_close_all(): void

odbc_close_all() fechará todas as conexões aos servidores de banco de dados.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

### Notas

> Nota:

> Esta função falhará se houver transações abertas em uma conexão. Esta conexão permanecerá aberta neste caso.

# odbc_columnprivileges

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_columnprivileges — Lista colunas e privilégios associados para a tabela fornecida

### Descrição

function odbc_columnprivileges(
Odbc\Connection `$odbc`,
?string `$catalog`,
string `$schema`,
string `$table`,
string `$column`
): Odbc\Result|false

Lista colunas e privilégios associados para a tabela fornecida.

### Parâmetros

`odbc`
  O objeto da conexão ODBC. Consulte odbc_connect() para obter detalhes.
`catalog`

  O catálogo ('qualifier' na linguagem ODBC 2).

`schema`

  O esquema ('owner' na linguagem ODBC 2). Este parâmetro aceita os seguintes padrões de pesquisa: `%` para corresponder a zero ou mais caracteres e `_` para corresponder a um único caractere.

`table`

  O nome da tabela. Este parâmetro aceita os seguintes padrões de pesquisa: `%` para corresponder a zero ou mais caracteres e `_` para corresponder a um único caractere.

`column`

  O nome da coluna. Este parâmetro aceita os seguintes padrões de pesquisa: `%` para corresponder a zero ou mais caracteres e `_` para corresponder a um único caractere.

### Valor Retornado

Retorna um objeto de resultado ODBC ou `false` em caso de falha. Este objeto de resultado pode ser usado para buscar uma lista de colunas e privilégios associados.

O conjunto de resultados possui as seguintes colunas:

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `COLUMN_NAME`
- `GRANTOR`
- `GRANTEE`
- `PRIVILEGE`
- `IS_GRANTABLE`

Drivers podem listar colunas adicionais.

O conjunto de resultados é ordenado por `TABLE_CAT`, `TABLE_SCHEM`, `TABLE_NAME`, `COLUMN_NAME` e `PRIVILEGE`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `odbc` agora espera uma instância de Odbc\Connection; anteriormente, esperava um resource.

### Exemplos

Exemplo #1 Listando privilégios para uma coluna

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $privileges = odbc_columnprivileges($conn, 'TutorialDB', 'dbo', 'test', 'id');
    while (($row = odbc_fetch_array($privileges))) {
        print_r($row);
        break; // outras linhas omitidas por questões de brevidade
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [TABLE_CAT] => TutorialDB
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => test
        [COLUMN_NAME] => id
        [GRANTOR] => dbo
        [GRANTEE] => dbo
        [PRIVILEGE] => INSERT
        [IS_GRANTABLE] => YES
    )

# odbc_columns

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_columns — Lista os nomes das colunas nas tabelas especificadas

### Descrição

function odbc_columns(
Odbc\Connection `$odbc`,
?string `$catalog` = `null`,
?string `$schema` = `null`,
?string `$table` = `null`,
?string `$column` = `null`
): Odbc\Result|false

Lista todas as colunas no intervalo solicitado.

### Parâmetros

`odbc`
  O objeto da conexão ODBC. Consulte odbc_connect() para obter detalhes.
`catalog`

  O catálogo ('qualifier' na linguagem ODBC 2).

`schema`

  O esquema ('owner' na linguagem ODBC 2). Este parâmetro aceita os seguintes padrões de pesquisa: `%` para corresponder a zero ou mais caracteres e `_` para corresponder a um único caractere.

`table`

  O nome da tabela. Este parâmetro aceita os seguintes padrões de pesquisa: `%` para corresponder a zero ou mais caracteres e `_` para corresponder a um único caractere.

`column`

  O nome da coluna. Este parâmetro aceita os seguintes padrões de pesquisa: `%` para corresponder a zero ou mais caracteres e `_` para corresponder a um único caractere.

### Valor Retornado

Retorna um objeto de resultado ODBC ou `false` em caso de falha.

O conjunto de resultados possui as seguintes colunas:

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `COLUMN_NAME`
- `DATA_TYPE`
- `TYPE_NAME`
- `COLUMN_SIZE`
- `BUFFER_LENGTH`
- `DECIMAL_DIGITS`
- `NUM_PREC_RADIX`
- `NULLABLE`
- `REMARKS`
- `COLUMN_DEF`
- `SQL_DATA_TYPE`
- `SQL_DATETIME_SUB`
- `CHAR_OCTET_LENGTH`
- `ORDINAL_POSITION`
- `IS_NULLABLE`

Drivers podem listar colunas adicionais.

O conjunto de resultados é ordenado por `TABLE_CAT`, `TABLE_SCHEM`, `TABLE_NAME` e `ORDINAL_POSITION`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `odbc` agora espera uma instância de Odbc\Connection; anteriormente, esperava um resource.
8.0.0 | `schema`, `table` e `column` agora podem ser nulos.

### Exemplos

Exemplo #1 Listando colunas de uma tabela

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $columns = odbc_columns($conn, 'TutorialDB', 'dbo', 'test', '%');
    while (($row = odbc_fetch_array($columns))) {
        print_r($row);
        break; // outras linhas omitidas por questões de brevidade
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [TABLE_CAT] => TutorialDB
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => TEST
        [COLUMN_NAME] => id
        [DATA_TYPE] => 4
        [TYPE_NAME] => int
        [COLUMN_SIZE] => 10
        [BUFFER_LENGTH] => 4
        [DECIMAL_DIGITS] => 0
        [NUM_PREC_RADIX] => 10
        [NULLABLE] => 0
        [REMARKS] =>
        [COLUMN_DEF] =>
        [SQL_DATA_TYPE] => 4
        [SQL_DATETIME_SUB] =>
        [CHAR_OCTET_LENGTH] =>
        [ORDINAL_POSITION] => 1
        [IS_NULLABLE] => NO
    )

### Veja Também

- odbc_columnprivileges() - Lista colunas e privilégios associados para a tabela fornecida
- odbc_procedurecolumns() - Recupera informações sobre parâmetros para procedimentos

# odbc_commit

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_commit — Confirma uma transação ODBC

### Descrição

function odbc_commit(Odbc\Connection `$odbc`): bool

Confirma todas as transações pendentes na conexão.

### Parâmetros

`odbc`
  O objeto da conexão ODBC. Consulte odbc_connect() para obter detalhes.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `odbc` agora espera uma instância de Odbc\Connection; anteriormente, esperava um resource.

# odbc_connect

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_connect — Conecta a uma fonte de dados

### Descrição

function odbc_connect(
string `$dsn`,
?string `$user` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
int `$cursor_option` = `SQL_CUR_USE_DRIVER`
): Odbc\Connection|false

O ID de conexão retornado por essas funções é necessário para outras funções ODBC. Podem existir várias conexões abertas ao mesmo tempo, desde que usem bancos de dados diferentes ou credenciais diferentes.

Com alguns drivers ODBC, a execução de um procedimento armazenado complexo pode falhar com um erro semelhante a: "Não é possível abrir um cursor em um procedimento armazenado que contenha algo diferente de uma única instrução SELECT". Usar SQL_CUR_USE_ODBC pode evitar esse erro. Além disso, alguns drivers não suportam o parâmetro row_number opcional em odbc_fetch_row(). SQL_CUR_USE_ODBC também pode ajudar nesse caso.

### Parâmetros

`dsn`

  O nome da fonte do banco de dados para a conexão. Como alternativa, uma string de conexão sem DSN pode ser usada.

`user`

  O nome de usuário. Este parâmetro é ignorado se `dsn` contiver `uid`. Para conectar sem especificar o parâmetro `user`, use `null`.

`password`

  A senha. Este parâmetro é ignorado se `dsn` contiver `pwd`. Para conectar sem especificar o parâmetro `password`, use `null`.

`cursor_option`

  Este parâmetro define o tipo de cursor a ser usado para esta conexão. Este parâmetro normalmente não é necessário, mas pode ser útil para solucionar problemas com alguns drivers ODBC.

  As seguintes constantes são definidas para o tipo de cursor:

  - SQL_CUR_USE_IF_NEEDED
  - SQL_CUR_USE_ODBC
  - SQL_CUR_USE_DRIVER

### Valor Retornado

Retorna uma conexão ODBC, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Esta função agora retorna uma instância de Odbc\Connection; anteriormente, retornava um resource.
8.4.0 | `user` e `password` agora podem ser nulos e também são opcionais e têm o valor padrão `null`.
8.4.0 | Anteriormente, usar uma string vazia para `password` não incluiria `pwd` na string de conexão gerada para `dsn`. Agora é gerada para uncluir um `pwd` que tem uma string vazia como seu valor. Para restaurar o comportamento anterior, `password` agora pode ser definido para `null`.
8.4.0 | Anteriormente, se `dsn` contivesse `uid` ou `pwd`, os parâmetros `user` e `password` seriam ignorados. Agora, `user` somente é ignorado se `dsn` contiver `uid`, e `password` somente é ignorado se `dsn` contiver `pwd`.

### Exemplos

Exemplo #1 Conexões sem DSN

    <?php
    // Microsoft SQL Server usando o Driver ODBC SQL Native Client 10.0 - permite conexão ao SQL 7, 2000, 2005 e 2008
    $connection = odbc_connect("Driver={SQL Server Native Client 10.0};Server=$server;Database=$database;", $user, $password);

    // Microsoft Access
    $connection = odbc_connect("Driver={Microsoft Access Driver (*.mdb)};Dbq=$mdbFilename", $user, $password);

    // Microsoft Excel
    $excelFile = realpath('C:/ExcelData.xls');
    $excelDir = dirname($excelFile);
    $connection = odbc_connect("Driver={Microsoft Excel Driver (*.xls)};DriverId=790;Dbq=$excelFile;DefaultDir=$excelDir" , '', '');
    ?>

### Veja Também

- Para conexões persistentes: odbc_pconnect() - Abre uma conexão persistente com o banco de dados

# odbc_connection_string_is_quoted

(PHP 8 >= 8.2.0)

odbc_connection_string_is_quoted — Determina se uma string de conexão ODBC está entre chaves

### Descrição

function odbc_connection_string_is_quoted(string `$str`): bool

Determina se uma string está entre chaves adequadamente para um valor de string de conexão ODBC. A cotação da string de conexão ODBC é executada usando chaves, e as chaves finais dentro de uma string devem ser escapadas repetindo-as duas vezes, semelhante ao SQL.

### Parâmetros

`str`

  A string a ser verificada.

### Valor Retornado

`true` se estiver adequadamente entre chaves, `false` se caso contrário.

### Veja Também

- odbc_connection_string_quote() - Envolve entre chaves um valor string de conexão ODBC
- odbc_connection_string_should_quote() - Determina se um valor na string de conexão ODBC deveria ser envolvido por chaves

# odbc_connection_string_quote

(PHP 8 >= 8.2.0)

odbc_connection_string_quote — Envolve entre chaves um valor string de conexão ODBC

### Descrição

function odbc_connection_string_quote(string `$str`): string

Envolve adequadamente um valor para uma string de conexão, de acordo com as regras de ODBC. Ou seja, ele será envolvido por chaves, e quaisquer chaves finais serão escapadas. Isso deve ser feito para quaisquer valores de string de conexão provenientes da entrada do usuário. Não fazer isso pode causar problemas na análise da string de conexão ou pode levar à injeção de valores na string de conexão.

Observe que esta função não verifica se a string já está entre chaves, nem se a string precisa estar. Para esses verificações, use as funções odbc_connection_string_is_quoted() e odbc_connection_string_should_quote(), respectivamente.

### Parâmetros

`str`

  A string a ser envolvida por chaves.

### Valor Retornado

Uma string envolvida por chaves, e adequadamente escapada.

### Exemplos

Exemplo #1 Exemplo de odbc_connection_string_quote()

Este exemplo envolve uma string com chaves e depois insere-a em uma string de conexão. Observe que a string será envolvida com chaves, e a o caractere de chave final no meio da string será escapado.

    <?php
    $value = odbc_connection_string_quote("foo}bar");
    $connection_string = "DSN=PHP;UserValue=$value";
    echo $connection_string;
    ?>

O exemplo acima produzirá algo semelhante a:

    DSN=PHP;UserValue={foo}}bar}

### Veja Também

- odbc_connection_string_is_quoted() - Determina se uma string de conexão ODBC está entre chaves
- odbc_connection_string_should_quote() - Determina se um valor na string de conexão ODBC deveria ser envolvido por chaves

# odbc_connection_string_should_quote

(PHP 8 >= 8.2.0)

odbc_connection_string_should_quote — Determina se um valor na string de conexão ODBC deveria ser envolvido por chaves

### Descrição

function odbc_connection_string_should_quote(string `$str`): bool

Determina se um valor na string de conexão ODBC deveria ser envolvido por chaves; isto é, se ele contém caracteres especiais.

Observe que esta função não verifica se a string já está envolvida entre chaves; uma string já envolvida por chaves conterá caracteres que farão com que esta função retorne true. Deve-se chamar a função odbc_connection_string_is_quoted() para esta verificação.

### Parâmetros

`str`

  A string a ser verificada.

### Valor Retornado

`true` se a string deveria ser envolvida por chaves; `false` caso contrário.

### Veja Também

- odbc_connection_string_quote() - Envolve entre chaves um valor string de conexão ODBC
- odbc_connection_string_is_quoted() - Determina se uma string de conexão ODBC está entre chaves

# odbc_cursor

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_cursor — Obtém o nome do cursor

### Descrição

function odbc_cursor(Odbc\Result `$statement`): string|false

Obtém o nome do cursor para o ID de resultado informado.

### Parâmetros

`statement`

  O objeto de resultado ODBC.

### Valor Retornado

Retorna o nome do cursor, como uma string, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `statement` agora espera uma instância de Odbc\Result; anteriormente, esperava um resource.

# odbc_data_source

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

odbc_data_source — Retorna informações sobre DSNs disponíveis

### Descrição

function odbc_data_source(Odbc\Connection `$odbc`, int `$fetch_type`): array|null|false

Esta função retornará a lista de DSN disponíveis (após chamá-la várias vezes).

### Parâmetros

`odbc`
  O objeto da conexão ODBC. Consulte odbc_connect() para obter detalhes.
`fetch_type`

  O `fetch_type` pode ser um de dois tipos de constantes: `SQL_FETCH_FIRST` ou `SQL_FETCH_NEXT`. Use `SQL_FETCH_FIRST` na primeira vez que esta função for chamada, depois use `SQL_FETCH_NEXT`.

### Valor Retornado

Retorna `false` em caso de erro, um array em caso de sucesso e `null` depois de buscar o último DSN disponível.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `odbc` agora espera uma instância de Odbc\Connection; anteriormente, esperava um resource.

### Exemplos

Exemplo #1 Lista os DSNs disponíveis

    <?php
    $conn = odbc_connect('dsn', 'user', 'pass');
    $dsn_info = odbc_data_source($conn, SQL_FETCH_FIRST);
    while ($dsn_info) {
        print_r($dsn_info);
        $dsn_info = odbc_data_source($conn, SQL_FETCH_NEXT);
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [server] => dsn
        [description] => ODBC Driver 17 for SQL Server
    )
    Array
    (
        [server] => other_dsn
        [description] => Microsoft Access Driver (*.mdb, *.accdb)
    )

# odbc_do

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_do — Sinônimo de odbc_exec()

### Descrição

Esta função é um apelido para: odbc_exec().

# odbc_error

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

odbc_error — Obtém o último código de erro

### Descrição

function odbc_error(?Odbc\Connection `$odbc` = `null`): string

Retorna um estado ODBC de seis dígitos ou uma string vazia se não houver erros.

### Parâmetros

`odbc`
  O objeto da conexão ODBC. Consulte odbc_connect() para obter detalhes.

### Valor Retornado

Se `odbc` for especificado, o último estado dessa conexão será retornado, caso contrário, o último estado de qualquer conexão será retornado.

Esta função retorna um valor significativo somente se a última consulta ODBC falhou (ou seja, odbc_exec() retornou `false`).

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `odbc` agora espera uma instância de Odbc\Connection; anteriormente, esperava um resource.
8.0.0 | `odbc` agora pode ser nulo.

### Veja Também

- odbc_errormsg() - Obtém a última mensagem de erro
- odbc_exec() - Executa diretamente uma instrução SQL

# odbc_errormsg

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

odbc_errormsg — Obtém a última mensagem de erro

### Descrição

function odbc_errormsg(?Odbc\Connection `$odbc` = `null`): string

Retorna uma string contendo a última mensagem de erro ODBC ou uma string vazia se não houve erros.

### Parâmetros

`odbc`
  O objeto da conexão ODBC. Consulte odbc_connect() para obter detalhes.

### Valor Retornado

Se `odbc` for especificado, o último estado dessa conexão será retornado, caso contrário, o último estado de qualquer conexão será retornado.

Esta função retorna um valor significativo somente se a última consulta ODBC falhou (ou seja, odbc_exec() retornou `false`).

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `odbc` agora espera uma instância de Odbc\Connection; anteriormente, esperava um resource.
8.0.0 | `odbc` agora pode ser nulo.

### Veja Também

- odbc_error() - Obtém o último código de erro
- odbc_exec() - Executa diretamente uma instrução SQL

# odbc_exec

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_exec — Executa diretamente uma instrução SQL

### Descrição

function odbc_exec(Odbc\Connection `$odbc`, string `$query`): Odbc\Result|false

Envia uma instrução SQL para o servidor de banco de dados.

### Parâmetros

`odbc`
  O objeto da conexão ODBC. Consulte odbc_connect() para obter detalhes.
`query`

  A instrução SQL.

### Valor Retornado

Retorna um objeto de resultado ODBC se o comando SQL foi executado com sucesso ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `odbc` agora espera uma instância de Odbc\Connection; anteriormente, esperava um resource.
8.4.0 | Esta função agora retorna uma instância de Odbc\Result; anteriormente, retornava um resource.
8.0.0 | O parâmetro `flags` foi removido.

### Veja Também

- odbc_prepare() - Prepara uma instrução para execução
- odbc_execute() - Executa uma instrução preparada

# odbc_execute

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_execute — Executa uma instrução preparada

### Descrição

function odbc_execute(Odbc\Result `$statement`, array `$params` = []): bool

Executa uma instrução preparada com odbc_prepare().

### Parâmetros

`statement`

  O objeto de resultado ODBC obtido de odbc_prepare().

`params`

  Parâmetros em `params` serão substituídos por marcadores na ordem na instrução preparada. Elementos deste array serão convertidos para strings ao chamar esta função.

  Quaisquer parâmetros em `params` que começam e terminam com aspas simples serão considerados como o nome de um arquivo para ler e enviar ao servidor de banco de dados como os dados para o marcador apropriado.

  Se a intenção for armazenar uma string que realmente comece e termine com aspas simples, deve ser adicionado um espaço ou outro caractere que não seja aspas simples no início ou no final do parâmetro, que irá evitar que o parâmetro seja considerado um nome de arquivo. Se esta não for uma opção, deve ser utilizado outro mecanismo para armazenar a string, por exemplo, executando a consulta diretamente com odbc_exec().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Esta função agora retorna uma instância de Odbc\Result; anteriormente, retornava um resource.
8.0.0 | O parâmetro não utilizado `flags` foi removido.

### Exemplos

Exemplo #1 Exemplos de odbc_execute() e odbc_prepare()

No seguinte código, $success apenas será `true` se todos os três parâmetros para myproc forem parâmetros IN:

    <?php
    $a = 1;
    $b = 2;
    $c = 3;
    $stmt    = odbc_prepare($conn, 'CALL myproc(?,?,?)');
    $success = odbc_execute($stmt, array($a, $b, $c));
    ?>

Se for necessário chamar uma instrução preparada usando parâmetros INOUT ou OUT, a solução recomendada é usar uma extensão nativa para o banco de dados (por exemplo, oci8 para Oracle).

### Veja Também

- odbc_prepare() - Prepara uma instrução para execução

# odbc_fetch_array

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

odbc_fetch_array — Obtém uma linha do resultado como um array associativo

### Descrição

function odbc_fetch_array(Odbc\Result `$statement`, ?int `$row` = `null`): array|false

Obtém um array associativo de uma consulta ODBC.

### Parâmetros

`statement`

  O objeto de resultado ODBC de odbc_exec().

`row`

  Opcionalmente, pode-se escolher o número da linha a ser obtida.

### Valor Retornado

Retorna um array que corresponde à linha obtida, ou `false` se não houver mais linhas.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `statement` agora espera uma instância de Odbc\Result; anteriormente, esperava um resource.
8.4.0 | `row` agora pode ser nulo.

### Notas

> Nota: Esta função existe quando compilada com suporte DBMaker, IBM DB2 ou UnixODBC.

### Veja Também

- odbc_fetch_row() - Obtém uma linha
- odbc_fetch_object() - Obtém um conjunto de resultados como um objeto
- odbc_num_rows() - Número de linhas em um resultado

# odbc_fetch_into

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_fetch_into — Busca uma linha de resultado no array

### Descrição

function odbc_fetch_into(Odbc\Result `$statement`, array `&$array`, ?int `$row` = `null`): int|false

Busca uma linha de resultado no array.

### Parâmetros

`statement`

  O objeto de resultado ODBC.

`array`

  O array de resultado que pode ser de qualquer tipo, pois será convertido para o tipo array. O array conterá os valores da coluna começando no índice 0 do array.

`row`

  O número da linha.

### Valor Retornado

Retorna o número da coluna no resultado; `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `statement` agora espera uma instância de Odbc\Result; anteriormente, esperava um resource.
8.4.0 | `row` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo de odbc_fetch_into()

    <?php
    $rc = odbc_fetch_into($res_id, $my_array);
    ?>

ou

    <?php
    $rc = odbc_fetch_into($res_id, $my_array, 2);
    ?>

# odbc_fetch_object

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

odbc_fetch_object — Obtém um conjunto de resultados como um objeto

### Descrição

function odbc_fetch_object(Odbc\Result `$statement`, ?int `$row` = `null`): stdClass|false

Obtém um object a partir de uma consulta ODBC.

### Parâmetros

`statement`

  O objeto de resultado ODBC de odbc_exec().

`row`

  Opcionalmente, pode ser escolhido o número da linha a ser obtida.

### Valor Retornado

Retorna um objeto que corresponde à linha obitida, ou `false` se não houver mais linhas.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `statement` agora espera uma instância de Odbc\Result; anteriormente, esperava um resource.
8.4.0 | `row` agora pode ser nulo.

### Notas

> Nota: Esta função existe quando compilada com suporte DBMaker, IBM DB2 ou UnixODBC.

### Veja Também

- odbc_fetch_row() - Obtém uma linha
- odbc_fetch_array() - Obtém uma linha do resultado como um array associativo
- odbc_num_rows() - Número de linhas em um resultado

# odbc_fetch_row

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_fetch_row — Obtém uma linha

### Descrição

function odbc_fetch_row(Odbc\Result `$statement`, ?int `$row` = `null`): bool

Obtém uma linha de dados que foi retornada pela odbc_do() ou odbc_exec(). Depois de odbc_fetch_row() ser chamada, os campos desta linha podem ser acessados com odbc_result().

### Parâmetros

`statement`

  O objeto de resultado ODBC.

`row`

  Se `row` não for especificado, odbc_fetch_row() irá tentar obter a próxima linha no conjunto de resultados. Chamadas para odbc_fetch_row() com ou sem `row` podem ser misturadas.

  Para caminhar através do conjunto de resultados mais de uma vez, pode-se usar odbc_fetch_row() com `row` 1, e então continuar chamando odbc_fetch_row() sem `row` para ver os resultados. Se um driver não suportar a obtenção de linhas por números, o parâmetro `row` é ignorado.

### Valor Retornado

Retorna `true` se houver uma linha, `false` caso contrário.

### Erros/Exceções

Um `E_WARNING` é emitido quando `row` for menor ou igual a zero.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `statement` agora espera uma instância de Odbc\Result; anteriormente, esperava um resource.
8.4.0 | Um `E_WARNING` agora é emitido quando `row` for menor ou igual a zero.
8.0.0 | `row` agora pode ser nulo.

# odbc_field_len

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_len — Obtém o tamanho (precisão) de um campo

### Descrição

function odbc_field_len(Odbc\Result `$statement`, int `$field`): int|false

Obtém o tamanho do campo referenciado pelo número no identificador de resultado informado.

### Parâmetros

`statement`

  O objeto de resultado ODBC.

`field`

  O número do campo. A numeração dos campos inicia em 0.

### Valor Retornado

Retorna o tamanho do campo, ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `statement` agora espera uma instância de Odbc\Result; anteriormente, esperava um resource.

### Veja Também

- odbc_field_scale() - Obtém a precisão de um campo para obter a precisão de um número de ponto flutuante

# odbc_field_name

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_name — Obtém o nome da coluna

### Descrição

function odbc_field_name(Odbc\Result `$statement`, int `$field`): string|false

Obtém o nome do campo ocupando o número da coluna em um dado objeto de resultado.

### Parâmetros

`statement`

  O objeto de resultado ODBC.

`field`

  O número do campo. A numeração de campos inicia em 1.

### Valor Retornado

Retorna o nome do campo como uma string, ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `statement` agora espera uma instância de Odbc\Result; anteriormente, esperava um resource.

# odbc_field_num

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_num — Retorna o número da coluna

### Descrição

function odbc_field_num(Odbc\Result `$statement`, string `$field`): int|false

Obtém o número da coluna que corresponde ao nome do campo no objeto de resultado informado.

### Parâmetros

`statement`

  O objeto de resultado ODBC.

`field`

  O nome do campo.

### Valor Retornado

Retorna o número do campo como um inteiro, ou `false` em caso de erro. A numeração dos campos inicia em 1.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `statement` agora espera uma instância de Odbc\Result; anteriormente, esperava um resource.

# odbc_field_precision

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_precision — Sinônimo de odbc_field_len()

### Descrição

Esta função é um apelido para: odbc_field_len().

### Veja Também

- odbc_field_scale() - Obtém a precisão de um campo para obter a precisão de números de ponto flutuante

# odbc_field_scale

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_scale — Obtém a precisão de um campo

### Descrição

function odbc_field_scale(Odbc\Result `$statement`, int `$field`): int|false

Obtém a precisão do campo referenciado pelo número em um identificador de resultado informado.

### Parâmetros

`statement`

  O objeto de resultado ODBC.

`field`

  O número do campo. A numeração do campo inicia em 1.

### Valor Retornado

Retorna a precisão do campo como um inteiro, ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `statement` agora espera uma instância de Odbc\Result; anteriormente, esperava um resource.

# odbc_field_type

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_type — Tipo de dados de um campo

### Descrição

function odbc_field_type(Odbc\Result `$statement`, int `$field`): string|false

Obtém o tipo SQL do campo referenciado pelo número em um identificador de resultado informado.

### Parâmetros

`statement`

  O objeto de resultado ODBC.

`field`

  O número do campo. Campos são numerados a partir de 1.

### Valor Retornado

Retorna o tipo do campo como uma string, ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `statement` agora espera uma instância de Odbc\Result; anteriormente, esperava um resource.

# odbc_foreignkeys

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_foreignkeys — Recupera uma lista de chaves estrangeiras

### Descrição

function odbc_foreignkeys(
Odbc\Connection `$odbc`,
?string `$pk_catalog`,
string `$pk_schema`,
string `$pk_table`,
string `$fk_catalog`,
string `$fk_schema`,
string `$fk_table`
): Odbc\Result|false

Recupera uma lista de chaves estrangeiras na tabela especificada ou uma lista de chaves estrangeiras em outras tabelas que se referem à chave primária na tabela especificada.

### Parâmetros

`odbc`
  O objeto da conexão ODBC. Consulte odbc_connect() para obter detalhes.
`pk_catalog`

  O catálogo ('qualifier' na linguagem ODBC 2) da tabela da chave primária.

`pk_schema`

  O esquema ('owner' no jargão do ODBC 2) da tabela da chave primária.

`pk_table`

  A tabela de chave primária.

`fk_catalog`

  O catálogo ('qualifier' na linguagem ODBC 2) da tabela da chave estrangeira.

`fk_schema`

  O esquema ('owner' no jargão do ODBC 2) da tabela da chave estrangeira.

`fk_table`

  A tabela da chave estrangeira.

### Valor Retornado

Retorna um objeto de resultado ODBC ou `false` em caso de falha.

O conjunto de resultados possui as seguintes colunas:

- `PKTABLE_CAT`
- `PKTABLE_SCHEM`
- `PKTABLE_NAME`
- `PKCOLUMN_NAME`
- `FKTABLE_CAT`
- `FKTABLE_SCHEM`
- `FKTABLE_NAME`
- `FKCOLUMN_NAME`
- `KEY_SEQ`
- `UPDATE_RULE`
- `DELETE_RULE`
- `FK_NAME`
- `PK_NAME`
- `DEFERRABILITY`

Drivers podem listar colunas adicionais.

Se as chaves estrangeiras associadas a uma chave primária forem solicitadas, o conjunto de resultados será ordenado por `FKTABLE_CAT`, `FKTABLE_SCHEM`, `FKTABLE_NAME` e `KEY_SEQ`. Se as chaves primárias associadas a uma chave estrangeira forem solicitadas, o conjunto de resultados será ordenado por `PKTABLE_CAT`, `PKTABLE_SCHEM`, `PKTABLE_NAME` e `KEY_SEQ`.

Se `pk_table` contiver um nome de tabela, odbc_foreignkeys() retornará um conjunto de resultados contendo a chave primária da tabela especificada e todas as chaves estrangeiras que se referem a ela.

Se `fk_table` contiver um nome de tabela, odbc_foreignkeys() retornará um conjunto de resultados contendo todas as chaves estrangeiras na tabela especificada e as chaves primárias (em outras tabelas) às quais elas se referem.

Se ambos `pk_table` e `fk_table` contiverem nomes de tabelas, odbc_foreignkeys() retornará as chaves estrangeiras na tabela especificada em `fk_table` que se referem à chave primária da tabela especificada em `pk_table`. Esta deve ser uma chave no máximo.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `odbc` agora espera uma instância de Odbc\Connection; anteriormente, esperava um resource.
8.4.0 | Esta função agora retorna uma instância de Odbc\Result; anteriormente, retornava um resource.

### Veja Também

- odbc_tables() - Obtém a lista de nomes de tabelas armazenadas em uma fonte de dados específica
- odbc_primarykeys() - Obtém as chaves primárias de uma tabela

# odbc_free_result

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_free_result — Libera objetos associados a um resultado

### Descrição

function odbc_free_result(Odbc\Result `$statement`): true

Libera objetos associados com um resultado.

odbc_free_result() somente precisa ser chamado se houver problemas de alto uso de memória na execução do script. Toda a memória do resultado será automaticamente liberada quando o script é terminado.

### Parâmetros

`statement`

  O objeto de resultado ODBC.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `statement` agora espera uma instância de Odbc\Result; anteriormente, esperava um resource.

### Notas

> Nota:

> Se a autoconfirmação estiver desabilitada (veja odbc_autocommit()) e for utilizada a função odbc_free_result() antes de confirmar, todas as transações pendentes serão revertidas.

# odbc_gettypeinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_gettypeinfo — Recupera informações sobre tipos de dados suportados pela fonte de dados

### Descrição

function odbc_gettypeinfo(Odbc\Connection `$odbc`, int `$data_type` = 0): Odbc\Result|false

Recupera informações sobre tipos de dados suportados pela fonte de dados.

### Parâmetros

`odbc`
  O objeto da conexão ODBC. Consulte odbc_connect() para obter detalhes.
`data_type`

  O tipo de dados, que pode ser usado para restringir as informações a um único tipo de dados.

### Valor Retornado

Retorna um objeto de resultado ODBC ou `false` em caso de falha.

O conjunto de resultados possui as seguintes colunas:

- TYPE_NAME
- DATA_TYPE
- PRECISION
- LITERAL_PREFIX
- LITERAL_SUFFIX
- CREATE_PARAMS
- NULLABLE
- CASE_SENSITIVE
- SEARCHABLE
- UNSIGNED_ATTRIBUTE
- MONEY
- AUTO_INCREMENT
- LOCAL_TYPE_NAME
- MINIMUM_SCALE
- MAXIMUM_SCALE

O conjunto de resultados é ordenado por DATA_TYPE e TYPE_NAME.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `odbc` agora espera uma instância de Odbc\Connection; anteriormente, esperava um resource.
8.4.0 | Esta função agora retorna uma instância de Odbc\Result; anteriormente, retornava um resource.

# odbc_longreadlen

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_longreadlen — Manipulação de colunas LONG

### Descrição

function odbc_longreadlen(Odbc\Result `$statement`, int `$length`): true

Controla a manipulação das colunas `LONG`, `LONGVARCHAR` e `LONGVARBINARY`. O comprimento padrão pode ser definido usando a diretiva uodbc.defaultlrl php.ini.

### Parâmetros

`statement`

  O objeto de resultado ODBC.

`length`

  O número de bytes retornado pelo PHP é controlado por este parâmetro. Se for definido como `0`, dados de coluna LONG são passados para o cliente (ou seja, exibidos) quando recuperados com odbc_result().

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `statement` agora espera uma instância de Odbc\Result; anteriormente, esperava um resource.

### Notas

> Nota:

> Manipulação de colunas `LONGVARBINARY` é também afetado por odbc_binmode().

# odbc_next_result

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

odbc_next_result — Verifica se múltiplos resultados estão disponíveis

### Descrição

function odbc_next_result(Odbc\Result `$statement`): bool

Verifica se há mais resultados disponíveis, dessa forma permitindo acesso ao próximo resultado via odbc_fetch_array(), odbc_fetch_row(), odbc_result() etc.

### Parâmetros

`statement`

  O objeto de resultado ODBC.

### Valor Retornado

Retorna `true` se houver mais resultados, `false` caso contrário.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `statement` agora espera uma instância de Odbc\Result; anteriormente, esperava um resource.

### Exemplos

Exemplo #1 odbc_next_result()

    <?php
    $r_Connection = odbc_connect($dsn, $username, $password);

    $s_SQL = <<<END_SQL
    SELECT 'A'
    SELECT 'B'
    SELECT 'C'
    END_SQL;

    $r_Results = odbc_exec($r_Connection, $s_SQL);

    $a_Row1 = odbc_fetch_array($r_Results);
    $a_Row2 = odbc_fetch_array($r_Results);
    echo "Despeja o primeiro conjunto de resultados ";
    var_dump($a_Row1, $a_Row2);

    echo "Obtém o segundo conjunto de resultados ";
    var_dump(odbc_next_result($r_Results));

    $a_Row1 = odbc_fetch_array($r_Results);
    $a_Row2 = odbc_fetch_array($r_Results);
    echo "Despeja o segundo conjunto de resultados ";
    var_dump($a_Row1, $a_Row2);

    echo "Obtém o terceiro conjunto de resultados ";
    var_dump(odbc_next_result($r_Results));

    $a_Row1 = odbc_fetch_array($r_Results);
    $a_Row2 = odbc_fetch_array($r_Results);
    echo "Despeja o terceiro conjunto de resultados ";
    var_dump($a_Row1, $a_Row2);

    echo "Tenta acessar um quarto conjunto de resultados ";
    var_dump(odbc_next_result($r_Results));
    ?>

O exemplo acima produzirá:

    Despeja o primeiro conjunto de resultados array(1) {
        ["A"]=>
        string(1) "A"
    }
    bool(false)
    Obtém o segundo conjunto de resultados bool(true)
    Despeja o segundo conjunto de resultados array(1) {
        ["B"]=>
        string(1) "B"
    }
    bool(false)
    Obtém o terceiro conjunto de resultados bool(true)
    Despeja o terceiro conjunto de resultados array(1) {
        ["C"]=>
        string(1) "C"
    }
    bool(false)
    Tenta acessar um quarto conjunto de resultados bool(false)

# odbc_num_fields

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_num_fields — Número de colunas em um resultado

### Descrição

function odbc_num_fields(Odbc\Result `$statement`): int

Obtém o número de campos (colunas) em um resultado ODBC.

### Parâmetros

`statement`

  O objeto de resultado ODBC retornado pela função odbc_exec().

### Valor Retornado

Retorna o número de campos, ou -1 em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `statement` agora espera uma instância de Odbc\Result; anteriormente, esperava um resource.

# odbc_num_rows

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_num_rows — Número de linhas em um resultado

### Descrição

function odbc_num_rows(Odbc\Result `$statement`): int

Obtém o número de linhas em um resultado ODBC. Para instruções INSERT, UPDATE e DELETE, odbc_num_rows() retorna o número de linhas afetadas. Para SELECT, isto pode ser o número de linhas disponíveis.

### Parâmetros

`statement`

  O objeto de resultado ODBC retornado pela odbc_exec().

### Valor Retornado

Retorna o número de linhas em um resultado ODBC. Esta função retornará -1 em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `statement` agora espera uma instância de Odbc\Result; anteriormente, esperava um resource.

### Notas

> Nota:

> Usar odbc_num_rows() para determinar o número de linhas disponível após um SELECT retornará -1 com muitos drivers.

# odbc_pconnect

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_pconnect — Abre uma conexão persistente com o banco de dados

### Descrição

function odbc_pconnect(
string `$dsn`,
?string `$user` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
int `$cursor_option` = `SQL_CUR_USE_DRIVER`
): Odbc\Connection|false

Abre uma conexão persistente com o banco de dados.

Esta função é muito parecida com odbc_connect(), exceto que a conexão não é realmente fechada quando o script termina. Solicitações futuras para uma conexão com a mesma combinação de `dsn`, `user`, `password` (via odbc_connect() e odbc_pconnect()) pode reutilizar a conexão persistente.

### Parâmetros

Consulte odbc_connect() para detalhes.

### Valor Retornado

Retorna uma conexão ODBC, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Esta função agora retorna uma instância de Odbc\Connection; anteriormente, retornava um resource.
8.4.0 | `user` e `password` agora podem ser nulos e também são opcionais e têm o valor padrão `null`.
8.4.0 | Anteriormente, usar uma string vazia para `password` não incluiria `pwd` na string de conexão gerada para `dsn`. Agora é gerada para uncluir um `pwd` que tem uma string vazia como seu valor. Para restaurar o comportamento anterior, `password` agora pode ser definido para `null`.
8.4.0 | Anteriormente, se `dsn` contivesse `uid` ou `pwd`, os parâmetros `user` e `password` seriam ignorados. Agora, `user` somente é ignorado se `dsn` contiver `uid`, e `password` somente é ignorado se `dsn` contiver `pwd`.

### Notas

> Nota: Conexões persistentes não têm efeito se o PHP for usado como um programa CGI.

### Veja Também

- odbc_connect() - Conecta a uma fonte de dados
- Conexões de banco de dados persistentes

# odbc_prepare

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_prepare — Prepara uma instrução para execução

### Descrição

function odbc_prepare(Odbc\Connection `$odbc`, string `$query`): Odbc\Result|false

Prepara uma instrução para execução. O objeto de resultado ODBC pode ser usado posteriormente para executar a instrução com odbc_execute().

Alguns bancos de dados (como IBM DB2, MS SQL Server, e Oracle) suportam procedimentos armazenados que aceitam parâmetros do tipo IN, INOUT, e OUT como definido pela especificação ODBC. Entretanto, o driver ODBC Unificado atualmente suporta apenas parâmetros do tipo IN em procedimentos armazenados.

### Parâmetros

`odbc`
  O objeto da conexão ODBC. Consulte odbc_connect() para obter detalhes.
`query`

  A instrução da string de consulta que está sendo preparada.

### Valor Retornado

Retorna um objeto de resultado ODBC se a instrução SQL foi preparada com sucesso. Retorna `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `odbc` agora espera uma instância de Odbc\Connection; anteriormente, esperava um resource.
8.4.0 | Esta função agora retorna uma instância de Odbc\Result; anteriormente, retornava um resource.

### Exemplos

Exemplo #1 Exemplos de odbc_execute() e odbc_prepare()

No código a seguir, $success será `true` se todos os três parâmetros em myproc forem parâmetros IN:

    <?php
    $a = 1;
    $b = 2;
    $c = 3;
    $stmt    = odbc_prepare($conn, 'CALL myproc(?,?,?)');
    $success = odbc_execute($stmt, array($a, $b, $c));
    ?>

Se for necessário usar uma instrução preparada usando parâmetros INOUT ou OUT, a alternativa é usar a extensão nativa para o banco de dados (por exemplo, oci8 para Oracle).

### Veja Também

- odbc_execute() - Executa uma instrução preparada

# odbc_primarykeys

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_primarykeys — Obtém as chaves primárias de uma tabela

### Descrição

function odbc_primarykeys(
Odbc\Connection `$odbc`,
?string `$catalog`,
string `$schema`,
string `$table`
): Odbc\Result|false

Retorna um objeto de resultado que pode ser usado para buscar os nomes das colunas que compõem a chave primária de uma tabela.

### Parâmetros

`odbc`
  O objeto da conexão ODBC. Consulte odbc_connect() para obter detalhes.
`catalog`

  O catálogo ('qualifier' na linguagem ODBC 2).

`schema`

  O esquema ('owner' na linguagem ODBC 2).

`table`

### Valor Retornado

Retorna um objeto de resultado ODBC ou `false` em caso de falha.

O conjunto de resultados possui as seguintes colunas:

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `COLUMN_NAME`
- `KEY_SEQ`
- `PK_NAME`

Drivers podem listar colunas adicionais.

O conjunto de resultados é ordenado por `TABLE_CAT`, `TABLE_SCHEM`, `TABLE_NAME` e `KEY_SEQ`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `odbc` agora espera uma instância de Odbc\Connection; anteriormente, esperava um resource.
8.4.0 | Esta função agora retorna uma instância de Odbc\Result; anteriormente, retornava um resource.

### Exemplos

Exemplo #1 Lista as chaves primárias de uma coluna

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $primarykeys = odbc_primarykeys($conn, 'TutorialDB', 'dbo', 'TEST');
    while (($row = odbc_fetch_array($primarykeys))) {
        print_r($row);
        break; // outras linhas omitidas por questões de brevidade
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [TABLE_CAT] => TutorialDB
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => TEST
        [COLUMN_NAME] => id
        [KEY_SEQ] => 1
        [PK_NAME] => PK__TEST__3213E83FE141F843
    )

### Veja Também

- odbc_tables() - Obtém a lista de nomes de tabelas armazenadas em uma fonte de dados específica
- odbc_foreignkeys() - Recupera uma lista de chaves estrangeiras

# odbc_procedurecolumns

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_procedurecolumns — Recupera informações sobre parâmetros para procedimentos

### Descrição

function odbc_procedurecolumns(
Odbc\Connection `$odbc`,
?string `$catalog` = `null`,
?string `$schema` = `null`,
?string `$procedure` = `null`,
?string `$column` = `null`
): Odbc\Result|false

Recupera informações sobre parâmetros para procedimentos.

### Parâmetros

`odbc`
  O objeto da conexão ODBC. Consulte odbc_connect() para obter detalhes.
`catalog`

  O catálogo ('qualifier' na linguagem ODBC 2).

`schema`

  O esquema ('owner' na linguagem ODBC 2). Este parâmetro aceita os seguintes padrões de pesquisa: `%` para corresponder a zero ou mais caracteres e `_` para corresponder a um único caractere.

`procedure`

  O procedimento. Este parâmetro aceita os seguintes padrões de pesquisa: `%` para corresponder a zero ou mais caracteres e `_` para corresponder a um único caractere.

`column`

  A coluna. Este parâmetro aceita os seguintes padrões de pesquisa: `%` para corresponder a zero ou mais caracteres e `_` para corresponder a um único caractere.

### Valor Retornado

Retorna a lista de parâmetros de entrada e saída, bem como as colunas que compõem o conjunto de resultados dos procedimentos especificados. Retorna um objeto de resultado ODBC ou `false` em caso de falha.

O conjunto de resultados possui as seguintes colunas:

- `PROCEDURE_CAT`
- `PROCEDURE_SCHEM`
- `PROCEDURE_NAME`
- `COLUMN_NAME`
- `COLUMN_TYPE`
- `DATA_TYPE`
- `TYPE_NAME`
- `COLUMN_SIZE`
- `BUFFER_LENGTH`
- `DECIMAL_DIGITS`
- `NUM_PREC_RADIX`
- `NULLABLE`
- `REMARKS`
- `COLUMN_DEF`
- `SQL_DATA_TYPE`
- `SQL_DATETIME_SUB`
- `CHAR_OCTET_LENGTH`
- `ORDINAL_POSITION`
- `IS_NULLABLE`

Drivers podem listar colunas adicionais.

O conjunto de resultados é ordenado por `PROCEDURE_CAT`, `PROCEDURE_SCHEM`, `PROCEDURE_NAME` e `COLUMN_TYPE`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `odbc` agora espera uma instância de Odbc\Connection; anteriormente, esperava um resource.
8.4.0 | Esta função agora retorna uma instância de Odbc\Result; anteriormente, retornava um resource.
8.0.0 | Antes desta versão, a função só podia ser chamada com um ou cinco argumentos.

### Exemplos

Exemplo #1 Lista colunas de um procedimento armazenado

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $columns = odbc_procedurecolumns($conn, 'TutorialDB', 'dbo', 'GetEmployeeSalesYTD;1', '%');
    while (($row = odbc_fetch_array($columns))) {
        print_r($row);
        break; // outras linhas omitidas por questões de brevidade
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [PROCEDURE_CAT] => TutorialDB
        [PROCEDURE_SCHEM] => dbo
        [PROCEDURE_NAME] => GetEmployeeSalesYTD;1
        [COLUMN_NAME] => @SalesPerson
        [COLUMN_TYPE] => 1
        [DATA_TYPE] => -9
        [TYPE_NAME] => nvarchar
        [COLUMN_SIZE] => 50
        [BUFFER_LENGTH] => 100
        [DECIMAL_DIGITS] =>
        [NUM_PREC_RADIX] =>
        [NULLABLE] => 1
        [REMARKS] =>
        [COLUMN_DEF] =>
        [SQL_DATA_TYPE] => -9
        [SQL_DATETIME_SUB] =>
        [CHAR_OCTET_LENGTH] => 100
        [ORDINAL_POSITION] => 1
        [IS_NULLABLE] => YES
    )

### Veja Também

- odbc_columns() - Lista os nomes das colunas nas tabelas especificadas

# odbc_procedures

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_procedures — Obtém a lista de procedimentos armazenados em uma fonte de dados específica

### Descrição

function odbc_procedures(
Odbc\Connection `$odbc`,
?string `$catalog` = `null`,
?string `$schema` = `null`,
?string `$procedure` = `null`
): Odbc\Result|false

Lista todos os procedimentos no intervalo solicitado.

### Parâmetros

`odbc`
  O objeto da conexão ODBC. Consulte odbc_connect() para obter detalhes.
`catalog`

  O catálogo ('qualifier' na linguagem ODBC 2).

`schema`

  O esquema ('owner' na linguagem ODBC 2). Este parâmetro aceita os seguintes padrões de pesquisa: `%` para corresponder a zero ou mais caracteres e `_` para corresponder a um único caractere.

`procedure`

  O nome. Este parâmetro aceita os seguintes padrões de pesquisa: `%` para corresponder a zero ou mais caracteres e `_` para corresponder a um único caractere.

### Valor Retornado

Retorna um objeto de resultado ODBC contendo a informação ou `false` em caso de falha.

O conjunto de resultados possui as seguintes colunas:

- `PROCEDURE_CAT`
- `PROCEDURE_SCHEM`
- `PROCEDURE_NAME`
- `NUM_INPUT_PARAMS`
- `NUM_OUTPUT_PARAMS`
- `NUM_RESULT_SETS`
- `REMARKS`
- `PROCEDURE_TYPE`

Drivers podem listar colunas adicionais.

O conjunto de resultados é ordenado por `PROCEDURE_CAT`, `PROCEDURE_SCHEMA` e `PROCEDURE_NAME`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `odbc` agora espera uma instância de Odbc\Connection; anteriormente, esperava um resource.
8.4.0 | Esta função agora retorna uma instância de Odbc\Result; anteriormente, retornava um resource.
8.0.0 | Antes desta versão, a função só podia ser chamada com um ou quatro argumentos.

### Exemplos

Exemplo #1 Lista procedimentos armazenados de um banco de dados

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $procedures = odbc_procedures($conn, $catalog, $schema, '%');
    while (($row = odbc_fetch_array($procedures))) {
        print_r($row);
        break; // outras linhas omitidas por questões de brevidade
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [PROCEDURE_CAT] => TutorialDB
        [PROCEDURE_SCHEM] => dbo
        [PROCEDURE_NAME] => GetEmployeeSalesYTD;1
        [NUM_INPUT_PARAMS] => -1
        [NUM_OUTPUT_PARAMS] => -1
        [NUM_RESULT_SETS] => -1
        [REMARKS] =>
        [PROCEDURE_TYPE] => 2
    )

### Veja Também

- odbc_procedurecolumns() - Recupera informações sobre parâmetros para procedimentos
- odbc_tables() - Obtém a lista de nomes de tabelas armazenadas em uma fonte de dados específica

# odbc_result

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_result — Obtém dados de resultados

### Descrição

function odbc_result(Odbc\Result `$statement`, string|int `$field`): string|bool|null

Obtém dados de resultados.

### Parâmetros

`statement`

  O objeto de resultado ODBC.

`field`

  O nome do campo que está sendo recuperado. Pode ser um inteiro contendo o número da coluna do campo desejado; ou pode ser uma string contendo o nome do campo.

### Valor Retornado

Retorna o conteúdo da string do campo, `false` em caso de erro, `null` para dados NULL ou `true` para dados binários.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `statement` agora espera uma instância de Odbc\Result; anteriormente, esperava um resource.

### Exemplos

A primeira chamada a odbc_result() retorna o valor do terceiro campo no registro atual do resultado da consulta. A segunda chamada à função odbc_result() retorna o valor do campo cujo nome é "val" no registro atual do resultado da consulta. Ocorre um erro se o parâmetro de número de coluna para o campo for menor que um, ou se exceder o número de colunas (ou campos) no registro atual. Da mesma forma, ocorre um erro se um campo tiver um nome que não é um dos nomes de campo da(s) tabela(s) que está(ão) sendo consultada(s).

Exemplo #1 Exemplos de odbc_result()

    <?php
    $item_3   = odbc_result($Query_ID, 3);
    $item_val = odbc_result($Query_ID, "val");
    ?>

### Notas

Índices de campo iniciam em 1. Sobre a forma que dados binários ou de colunas longas são retornados, consulte as funções odbc_binmode() e odbc_longreadlen().

# odbc_result_all

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_result_all — Exibe o resultado como uma tabela HTML

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.1.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
function odbc_result_all(Odbc\Result `$statement`, string `$format` = ""): int|false

Exibe todas as linhas de um objeto de resultado produzido pela função odbc_exec(). O resultado é exibido no formato de tabela HTML. Os dados não são escapados.

Esta função não deve ser usada em ambientes de produção; é destinada para fins de desenvolvimento, para obter um conjunto de resultados renderizado rapidamente.

### Parâmetros

`statement`

  O objeto de resultado ODBC.

`format`

  Formatação adicional da tabela em geral.

### Valor Retornado

Retorna o número de linhas no resultado ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `statement` agora espera uma instância de Odbc\Result; anteriormente, esperava um resource.
8.1.0 | Esta função foi descontinuada.

# odbc_rollback

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_rollback — Reverte uma transação

### Descrição

function odbc_rollback(Odbc\Connection `$odbc`): bool

Reverte todas as instruções pendentes na conexão.

### Parâmetros

`odbc`
  O objeto da conexão ODBC. Consulte odbc_connect() para obter detalhes.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `odbc` agora espera uma instância de Odbc\Connection; anteriormente, esperava um resource.

# odbc_setoption

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_setoption — Ajusta configurações do ODBC

### Descrição

function odbc_setoption(
Odbc\Connection|Odbc\Result `$odbc`,
int `$which`,
int `$option`,
int `$value`
): bool

Esta função permite manipular as opções ODBC para uma determinada conexão ou resultado de consulta. Ela foi escrita para ajudar a encontrar soluções para problemas em drivers ODBC peculiares. Esta função deve ser usada por um programador ODBC que compreenda os efeitos que as diversas opções terão. Será necessária uma boa referência ODBC para explicar todas as diferentes opções e valores que podem ser usados. Diferentes versões de driver oferecem suporte a diferentes opções.

Como os efeitos podem variar dependendo do driver ODBC, o uso desta função em scripts a serem disponibilizados publicamente é fortemente desencorajado. Além disso, algumas opções de ODBC não estão disponíveis para esta função porque devem ser definidas antes de a conexão ser estabelecida ou a consulta ser preparada. No entanto, se em um determinado trabalho ela puder fazer o PHP funcionar de forma seja evitada uma pressão para que seja usado um produto comercial, isso é tudo que realmente importa.

### Parâmetros

`odbc`

  É um ID de conexão ou ID de resultado no qual as configurações serão alteradas. Para SQLSetConnectOption(), este é um ID de conexão. Para SQLSetStmtOption(), este é um ID de resultado.

`which`

  É a função ODBC a ser usada. O valor deve ser 1 para SQLSetConnectOption() e 2 para SQLSetStmtOption().

`option`

  A opção a ser definida.

`value`

  O valor para a opção informada em `option`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `odbc` agora espera uma instância de Odbc\Connection ou de Odbc\Result; anteriormente, esperava um resource.

### Exemplos

Exemplo #1 Exemplos de odbc_setoption()

    <?php
    // 1. Opção 102 de SQLSetConnectOption() é SQL_AUTOCOMMIT.
    //    Valor 1 de SQL_AUTOCOMMIT é SQL_AUTOCOMMIT_ON.
    //    Este exemplo tem o mesmo efeito de
    //    odbc_autocommit($conn, true);

    odbc_setoption($conn, 1, 102, 1);

    // 2. Opção 0 de SQLSetStmtOption() é SQL_QUERY_TIMEOUT.
    //    Este exemplo define que a consulta expira após 30 segundos.

    $result = odbc_prepare($conn, $sql);
    odbc_setoption($result, 2, 0, 30);
    odbc_execute($result);
    ?>

# odbc_specialcolumns

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_specialcolumns — Recupera colunas especiais

### Descrição

function odbc_specialcolumns(
Odbc\Connection `$odbc`,
int `$type`,
?string `$catalog`,
string `$schema`,
string `$table`,
int `$scope`,
int `$nullable`
): Odbc\Result|false

Recupera o conjunto ideal de colunas que identifica exclusivamente uma linha na tabela ou colunas que são atualizadas automaticamente quando qualquer valor na linha é atualizado por uma transação.

### Parâmetros

`odbc`
  O objeto da conexão ODBC. Consulte odbc_connect() para obter detalhes.
`type`
  Quando o argumento de tipo é `SQL_BEST_ROWID`, odbc_specialcolumns() retorna a coluna ou colunas que identificam exclusivamente cada linha na tabela. Quando o argumento de tipo é `SQL_ROWVER`, odbc_specialcolumns() retorna a coluna ou colunas na tabela especificada, se houver, que são atualizadas automaticamente pela fonte de dados quando qualquer valor na linha é atualizado por qualquer transação.
`catalog`

  O catálogo ('qualifier' na linguagem ODBC 2).

`schema`

  O esquema ('owner' na linguagem ODBC 2).

`table`

  A tabela.

`scope`

  O escopo, que ordena o conjunto de resultados. Uma das constantes `SQL_SCOPE_CURROW`, `SQL_SCOPE_TRANSACTION` ou `SQL_SCOPE_SESSION`.

`nullable`

  Determina se colunas especiais que podem ter um valor NULL devem ser retornadas. Uma das constantes `SQL_NO_NULLS` ou `SQL_NULLABLE`.

### Valor Retornado

Retorna um objeto de resultado ODBC ou `false` em caso de falha.

O conjunto de resultados possui as seguintes colunas:

- `SCOPE`
- `COLUMN_NAME`
- `DATA_TYPE`
- `TYPE_NAME`
- `COLUMN_SIZE`
- `BUFFER_LENGTH`
- `DECIMAL_DIGITS`
- `PSEUDO_COLUMN`

Drivers podem listar colunas adicionais.

O conjunto de resultados é ordenado por `SCOPE`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `odbc` agora espera uma instância de Odbc\Connection; anteriormente, esperava um resource.
8.4.0 | Esta função agora retorna uma instância de Odbc\Result; anteriormente, retornava um resource.

### Veja Também

- odbc_tables() - Obtém a lista de nomes de tabelas armazenadas em uma fonte de dados específica

# odbc_statistics

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_statistics — Recupera estatísticas sobre uma tabela

### Descrição

function odbc_statistics(
Odbc\Connection `$odbc`,
?string `$catalog`,
string `$schema`,
string `$table`,
int `$unique`,
int `$accuracy`
): Odbc\Result|false

Obtém estatísticas sobre uma tabela e seus índices.

### Parâmetros

`odbc`
  O objeto da conexão ODBC. Consulte odbc_connect() para obter detalhes.
`catalog`

  O catálogo ('qualifier' na linguagem ODBC 2).

`schema`

  O esquema ('owner' na linguagem ODBC 2).

`table`

  O nome da tabela.

`unique`

  O tipo do índice. Uma das constantes `SQL_INDEX_UNIQUE` ou `SQL_INDEX_ALL`.

`accuracy`

  Uma das constantes `SQL_ENSURE` ou `SQL_QUICK`. Esta última solicita que o driver recupere `CARDINALITY` e `PAGES` somente se eles estiverem prontamente disponíveis no servidor.

### Valor Retornado

Retorna um objeto de resultado ODBC ou `false` em caso de falha.

O conjunto de resultados possui as seguintes colunas:

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `NON_UNIQUE`
- `INDEX_QUALIFIER`
- `INDEX_NAME`
- `TYPE`
- `ORDINAL_POSITION`
- `COLUMN_NAME`
- `ASC_OR_DESC`
- `CARDINALITY`
- `PAGES`
- `FILTER_CONDITION`

Drivers podem listar colunas adicionais.

O conjunto de resultados é ordenado por `NON_UNIQUE`, `TYPE`, `INDEX_QUALIFIER`, `INDEX_NAME` e `ORDINAL_POSITION`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `odbc` agora espera uma instância de Odbc\Connection; anteriormente, esperava um resource.
8.4.0 | Esta função agora retorna uma instância de Odbc\Result; anteriormente, retornava um resource.

### Exemplos

Exemplo #1 Listando estatísticas de uma tabela

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $statistics = odbc_statistics($conn, 'TutorialDB', 'dbo', 'TEST', SQL_INDEX_UNIQUE, SQL_QUICK);
    while (($row = odbc_fetch_array($statistics))) {
        print_r($row);
        break; // outras linhas omitidas por questões de brevidade
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [TABLE_CAT] => TutorialDB
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => TEST
        [NON_UNIQUE] =>
        [INDEX_QUALIFIER] =>
        [INDEX_NAME] =>
        [TYPE] => 0
        [ORDINAL_POSITION] =>
        [COLUMN_NAME] =>
        [ASC_OR_DESC] =>
        [CARDINALITY] => 15
        [PAGES] => 3
        [FILTER_CONDITION] =>
    )

### Veja Também

- odbc_tables() - Obtém a lista de nomes de tabelas armazenadas em uma fonte de dados específica

# odbc_tableprivileges

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_tableprivileges — Lista tabelas e os privilégios associados a cada tabela

### Descrição

function odbc_tableprivileges(
Odbc\Connection `$odbc`,
?string `$catalog`,
string `$schema`,
string `$table`
): Odbc\Result|false

Lista tabelas no intervalo solicitado e os privilégios associados a cada tabela.

### Parâmetros

`odbc`
  O objeto da conexão ODBC. Consulte odbc_connect() para obter detalhes.
`catalog`

  O catálogo ('qualifier' na linguagem ODBC 2).

`schema`

  O esquema ('owner' na linguagem ODBC 2). Este parâmetro aceita os seguintes padrões de pesquisa: `%` para corresponder a zero ou mais caracteres e `_` para corresponder a um único caractere.

`table`

  O nome. Este parâmetro aceita os seguintes padrões de pesquisa: `%` para corresponder a zero ou mais caracteres e `_` para corresponder a um único caractere.

### Valor Retornado

Retorna um objeto de resultado ODBC ou `false` em caso de falha.

O conjunto de resultados possui as seguintes colunas:

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `GRANTOR`
- `GRANTEE`
- `PRIVILEGE`
- `IS_GRANTABLE`

Drivers podem listar colunas adicionais.

O conjunto de resultados é ordenado por `TABLE_CAT`, `TABLE_SCHEM`, `TABLE_NAME`, `PRIVILEGE` e `GRANTEE`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `odbc` agora espera uma instância de Odbc\Connection; anteriormente, esperava um resource.
8.4.0 | Esta função agora retorna uma instância de Odbc\Result; anteriormente, retornava um resource.

### Exemplos

Exemplo #1 Listando privilégios de uma tabela

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $privileges = odbc_tableprivileges($conn, 'SalesOrders', 'dbo', 'Orders');
    while (($row = odbc_fetch_array($privileges))) {
        print_r($row);
        break; // outras linhas omitidas por questões de brevidade
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [TABLE_CAT] => SalesOrders
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => Orders
        [GRANTOR] => dbo
        [GRANTEE] => dbo
        [PRIVILEGE] => DELETE
        [IS_GRANTABLE] => YES
    )

### Veja Também

- odbc_tables() - Obtém a lista de nomes de tabelas armazenadas em uma fonte de dados específica

# odbc_tables

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_tables — Obtém a lista de nomes de tabelas armazenadas em uma fonte de dados específica

### Descrição

function odbc_tables(
Odbc\Connection `$odbc`,
?string `$catalog` = `null`,
?string `$schema` = `null`,
?string `$table` = `null`,
?string `$types` = `null`
): Odbc\Result|false

Lista todas as tabelas no intervalo solicitado.

Para suportar a enumeração de qualificadores, proprietários e tipos de tabela, a seguinte semântica especial para `catalog`, `schema`, `table` e `table_type` estão disponíveis:

- Se `catalog` for um caractere único de porcentagem (%) e `schema` e `table` forem strings vazias, o conjunto de resultados conterá uma lista de qualificadores válidos para a fonte de dados. (Todas as colunas, exceto a coluna TABLE_QUALIFIER, contêm NULLs.)
- Se `schema` for um caractere único de porcentagem (%) e `catalog` e `table` forem strings vazias, então o conjunto de resultados conterá uma lista de proprietários válidos para a fonte de dados. (Todas as colunas, exceto a coluna TABLE_OWNER, contêm NULLs.)
- Se `table_type` for um caractere único de porcentagem (%) e `catalog`, `schema` e `table` forem strings vazias, então o conjunto de resultados contém uma lista de tipos de tabela válidos para a fonte de dados. (Todas as colunas, exceto a coluna TABLE_TYPE, contêm NULLs.)

### Parâmetros

`odbc`
  O objeto da conexão ODBC. Consulte odbc_connect() para obter detalhes.
`catalog`

  O catálogo ('qualifier' na linguagem ODBC 2).

`schema`

  O esquema ('owner' na linguagem ODBC 2). Este parâmetro aceita os seguintes padrões de pesquisa: `%` para corresponder a zero ou mais caracteres e `_` para corresponder a um único caractere.

`table`

  O nome. Este parâmetro aceita os seguintes padrões de pesquisa: `%` para corresponder a zero ou mais caracteres e `_` para corresponder a um único caractere.

`types`

  Se `table_type` não for uma string vazia, este parâmetro deverá conter uma lista de valores separados por vírgula para os tipos de interesse; cada valor pode ser colocado entre aspas simples (`'`) ou sem aspas. Por exemplo, `'TABLE','VIEW'` ou `TABLE, VIEW`. Se a fonte de dados não suportar um tipo de tabela especificado, odbc_tables() não retornará nenhum resultado para esse tipo.

### Valor Retornado

Retorna um objeto de resultado ODBC contendo as informações ou `false` em caso de falha.

O conjunto de resultados possui as seguintes colunas:

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `TABLE_TYPE`
- `REMARKS`

Drivers podem listar colunas adicionais.

O conjunto de resultados é ordenado por `TABLE_TYPE`, `TABLE_CAT`, `TABLE_SCHEM` e `TABLE_NAME`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `odbc` agora espera uma instância de Odbc\Connection; anteriormente, esperava um resource.
8.4.0 | Esta função agora retorna uma instância de Odbc\Result; anteriormente, retornava um resource.
8.0.0 | `schema`, `table` e `types` agora podem ser nulos.

### Exemplos

Exemplo #1 Listando tabelas em um catálogo

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $tables = odbc_tables($conn, 'SalesOrders', 'dbo', '%', 'TABLE');
    while (($row = odbc_fetch_array($tables))) {
        print_r($row);
        break; // outras linhas omitidas por questões de brevidade
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [TABLE_CAT] => SalesOrders
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => Orders
        [TABLE_TYPE] => TABLE
        [REMARKS] =>
    )

### Veja Também

- odbc_tableprivileges() - Lista tabelas e os privilégios associados a cada tabela
- odbc_columns() - Lista os nomes das colunas nas tabelas especificadas
- odbc_specialcolumns() - Recupera colunas especiais
- odbc_statistics() - Recupera estatísticas sobre uma tabela
- odbc_procedures() - Obtém a lista de procedimentos armazenados em uma fonte de dados específica

## Índice

- odbc_autocommit — Alterna o comportamento da autoconfirmação
- odbc_binmode — Manipulação de dados de colunas binárias
- odbc_close — Fecha uma conexão ODBC
- odbc_close_all — Fecha todas as conexões ODBC
- odbc_columnprivileges — Lista colunas e privilégios associados para a tabela fornecida
- odbc_columns — Lista os nomes das colunas nas tabelas especificadas
- odbc_commit — Confirma uma transação ODBC
- odbc_connect — Conecta a uma fonte de dados
- odbc_connection_string_is_quoted — Determina se uma string de conexão ODBC está entre chaves
- odbc_connection_string_quote — Envolve entre chaves um valor string de conexão ODBC
- odbc_connection_string_should_quote — Determina se um valor na string de conexão ODBC deveria ser envolvido por chaves
- odbc_cursor — Obtém o nome do cursor
- odbc_data_source — Retorna informações sobre DSNs disponíveis
- odbc_do — Sinônimo de odbc_exec
- odbc_error — Obtém o último código de erro
- odbc_errormsg — Obtém a última mensagem de erro
- odbc_exec — Executa diretamente uma instrução SQL
- odbc_execute — Executa uma instrução preparada
- odbc_fetch_array — Obtém uma linha do resultado como um array associativo
- odbc_fetch_into — Busca uma linha de resultado no array
- odbc_fetch_object — Obtém um conjunto de resultados como um objeto
- odbc_fetch_row — Obtém uma linha
- odbc_field_len — Obtém o tamanho (precisão) de um campo
- odbc_field_name — Obtém o nome da coluna
- odbc_field_num — Retorna o número da coluna
- odbc_field_precision — Sinônimo de odbc_field_len
- odbc_field_scale — Obtém a precisão de um campo
- odbc_field_type — Tipo de dados de um campo
- odbc_foreignkeys — Recupera uma lista de chaves estrangeiras
- odbc_free_result — Libera objetos associados a um resultado
- odbc_gettypeinfo — Recupera informações sobre tipos de dados suportados pela fonte de dados
- odbc_longreadlen — Manipulação de colunas LONG
- odbc_next_result — Verifica se múltiplos resultados estão disponíveis
- odbc_num_fields — Número de colunas em um resultado
- odbc_num_rows — Número de linhas em um resultado
- odbc_pconnect — Abre uma conexão persistente com o banco de dados
- odbc_prepare — Prepara uma instrução para execução
- odbc_primarykeys — Obtém as chaves primárias de uma tabela
- odbc_procedurecolumns — Recupera informações sobre parâmetros para procedimentos
- odbc_procedures — Obtém a lista de procedimentos armazenados em uma fonte de dados específica
- odbc_result — Obtém dados de resultados
- odbc_result_all — Exibe o resultado como uma tabela HTML
- odbc_rollback — Reverte uma transação
- odbc_setoption — Ajusta configurações do ODBC
- odbc_specialcolumns — Recupera colunas especiais
- odbc_statistics — Recupera estatísticas sobre uma tabela
- odbc_tableprivileges — Lista tabelas e os privilégios associados a cada tabela
- odbc_tables — Obtém a lista de nomes de tabelas armazenadas em uma fonte de dados específica

# A classe Odbc\Connection

(PHP 8 >= 8.4.0)

## Introdução

Uma classe totalmente opaca que substitui um resource `odbc_connection` a partir do PHP 8.4.0.

## Resumo da classe

namespace Odbc;
class Connection {
}

# A classe Odbc\Result

(PHP 8 >= 8.4.0)

## Introdução

Uma classe totalmente opaca que substitui um resource `odbc_result` a partir do PHP 8.4.0.

## Resumo da classe

namespace Odbc;
class Result {
}

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
  - Tipos de Recurso
- Constantes predefinidas
- Funções de ODBC
  - odbc_autocommit — Alterna o comportamento da autoconfirmação
  - odbc_binmode — Manipulação de dados de colunas binárias
  - odbc_close — Fecha uma conexão ODBC
  - odbc_close_all — Fecha todas as conexões ODBC
  - odbc_columnprivileges — Lista colunas e privilégios associados para a tabela fornecida
  - odbc_columns — Lista os nomes das colunas nas tabelas especificadas
  - odbc_commit — Confirma uma transação ODBC
  - odbc_connect — Conecta a uma fonte de dados
  - odbc_connection_string_is_quoted — Determina se uma string de conexão ODBC está entre chaves
  - odbc_connection_string_quote — Envolve entre chaves um valor string de conexão ODBC
  - odbc_connection_string_should_quote — Determina se um valor na string de conexão ODBC deveria ser envolvido por chaves
  - odbc_cursor — Obtém o nome do cursor
  - odbc_data_source — Retorna informações sobre DSNs disponíveis
  - odbc_do — Sinônimo de odbc_exec
  - odbc_error — Obtém o último código de erro
  - odbc_errormsg — Obtém a última mensagem de erro
  - odbc_exec — Executa diretamente uma instrução SQL
  - odbc_execute — Executa uma instrução preparada
  - odbc_fetch_array — Obtém uma linha do resultado como um array associativo
  - odbc_fetch_into — Busca uma linha de resultado no array
  - odbc_fetch_object — Obtém um conjunto de resultados como um objeto
  - odbc_fetch_row — Obtém uma linha
  - odbc_field_len — Obtém o tamanho (precisão) de um campo
  - odbc_field_name — Obtém o nome da coluna
  - odbc_field_num — Retorna o número da coluna
  - odbc_field_precision — Sinônimo de odbc_field_len
  - odbc_field_scale — Obtém a precisão de um campo
  - odbc_field_type — Tipo de dados de um campo
  - odbc_foreignkeys — Recupera uma lista de chaves estrangeiras
  - odbc_free_result — Libera objetos associados a um resultado
  - odbc_gettypeinfo — Recupera informações sobre tipos de dados suportados pela fonte de dados
  - odbc_longreadlen — Manipulação de colunas LONG
  - odbc_next_result — Verifica se múltiplos resultados estão disponíveis
  - odbc_num_fields — Número de colunas em um resultado
  - odbc_num_rows — Número de linhas em um resultado
  - odbc_pconnect — Abre uma conexão persistente com o banco de dados
  - odbc_prepare — Prepara uma instrução para execução
  - odbc_primarykeys — Obtém as chaves primárias de uma tabela
  - odbc_procedurecolumns — Recupera informações sobre parâmetros para procedimentos
  - odbc_procedures — Obtém a lista de procedimentos armazenados em uma fonte de dados específica
  - odbc_result — Obtém dados de resultados
  - odbc_result_all — Exibe o resultado como uma tabela HTML
  - odbc_rollback — Reverte uma transação
  - odbc_setoption — Ajusta configurações do ODBC
  - odbc_specialcolumns — Recupera colunas especiais
  - odbc_statistics — Recupera estatísticas sobre uma tabela
  - odbc_tableprivileges — Lista tabelas e os privilégios associados a cada tabela
  - odbc_tables — Obtém a lista de nomes de tabelas armazenadas em uma fonte de dados específica
- Odbc\Connection — A classe Odbc\Connection
- Odbc\Result — A classe Odbc\Result

# PHP Data Objects

# Introdução

A extensão `PHP Data Objects` (PDO) define uma interface leve e consistente para acessar bancos de dados no PHP. Cada driver de banco de dados que implementa a interface PDO pode expor recursos específicos do banco de dados como funções de extensão comuns. Observe que não é possível executar nenhuma função de banco de dados usando apenas a extensão PDO; um driver PDO de banco de dados deve ser usado para acessar o servidor de banco de dados.

O PDO fornece uma camada de abstração de acesso a dados, o que significa que, independentemente de qual banco de dados estiver sendo usado, as mesmas funções serão usadas para realizar consultas e buscar dados. O PDO não fornece uma abstração de banco de dados; ele não reescreve o SQL nem emula os recursos ausentes. Uma camada de abstração completa deve ser usada se esse recurso for necessário.

O PDO vem com o PHP.

# Instalação/Configuração

## Índice

- Instalação
- Configurações em Execução

## Instalação

Esta extensão está habilitada por padrão. Ela pode ser desabilitada usando a seguinte opção em tempo de compilação: --disable-pdo

Instalando o PDO em sistemas Unix

1. O PDO e o driver PDO_SQLITE estão habilitados por padrão. Pode ser preciso habilitar o driver PDO do banco de dados escolhido; consulte a documentação dos drivers PDO de bancos de dados para saber mais sobre isso.

   > Nota:

   > Ao compilar o PDO como uma extensão compartilhada (não recomendado), todos os drivers PDO devem ser carregados após o próprio PDO.

2. Ao instalar o PDO como um módulo compartilhado, o arquivo php.ini precisa ser atualizado para que a extensão PDO seja carregada automaticamente quando o PHP for executado. Qualquer driver de banco de dados usado também precisará ser habilitado; certifique-se de que eles estejam listados após a linha extension=pdo, pois o PDO deve ser inicializado antes que as extensões específicas do banco de dados possam ser carregadas. Se o PDO e as extensões de banco de dados foram compilados estaticamente, esta etapa pode ser ignorada.

       extension=pdo

Pessoas usuárias do Windows

1. PDO é habilitado por padrão. Selecione os outros arquivos DLL e use a função dl() para carregá-los em tempo de execução ou habilite-os no arquivo php.ini. Por exemplo, isto carrega o driver PDO_SQLITE mas deixa o driver PDO_ODBC comentado:

       ;extension=pdo_odbc
       extension=pdo_sqlite

   Essas DLLs devem existir no diretório de extensões extension_dir do sistema.

> Nota:

> Lembre-se que após fazer alterações no arquivo php.ini, será necessário reiniciar o PHP para que as novas diretivas de configuração entrem em vigor.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de Configuração do PDO
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
pdo.dsn.* |  | Somente php.ini |

Aqui está uma breve explicação das diretivas de configuração.

`pdo.dsn.*` string

  Define sinônimos DSN. Veja PDO::__construct() para uma explicação completa.

# Constantes predefinidas

## Índice

- Modos de Busca

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

## Modos de Busca

Consulte as constantes de cursores para as constantes `PDO::FETCH_ORI_*`.

## Modos de Busca Básicos

Modo de Busca | Resumo
--- | ---
`PDO::FETCH_DEFAULT` | Especifica que o modo de busca padrão deve ser usado.
`PDO::FETCH_ASSOC` | Array indexado somente pelo nome da coluna.
`PDO::FETCH_BOTH` (Padrão) | Array indexado tanto pelo nome quanto pelo número da coluna.
`PDO::FETCH_NAMED` | Variante de `PDO::FETCH_ASSOC` que retém colunas duplicadas.
`PDO::FETCH_NUM` | Array indexado somente pelo número da coluna.
`PDO::FETCH_COLUMN` | Uma única coluna.
`PDO::FETCH_KEY_PAIR` | Pares de chave-valor, indexados pela primeira coluna.
`PDO::FETCH_FUNC` | Usa uma função para criar o valor de retorno. (PDOStatement::fetchAll() somente)
`PDO::FETCH_OBJ` | Objeto anônimo (stdClass).
`PDO::FETCH_CLASS` | Um objeto de uma classe especificada.

## Opções de PDO::FETCH_CLASS

Estes modos são usados para implementar opções ao usar `PDO::FETCH_CLASS`.

Modo de busca | Resumo
--- | ---
`PDO::FETCH_CLASSTYPE` | Usa a primeira coluna como o nome da classe.
`PDO::FETCH_PROPS_LATE` | Chama o construtor antes de definir as propriedades.
`PDO::FETCH_SERIALIZE` | Usa dados serializados do PHP. Descontinuado a partir do PHP 8.1.0.

## Modos de resultado único

Os modos a seguir não podem ser usados com PDOStatement::fetchAll().

Modo de busca | Resumo
--- | ---
`PDO::FETCH_BOUND` | Vincula valores a variáveis especificadas.
`PDO::FETCH_INTO` | Atualiza um objeto existente.
`PDO::FETCH_LAZY` | Busca lenta via PDORow para acessos como array e objetos.

## Sinalizadores de comportamento especiais para PDOStatement::fetchAll()

Os seguintes modos especiais para múltiplos resultados funcionam apenas com PDOStatement::fetchAll() e não funcionam com alguns outros modos de busca. Consulte a documentação completa para obter detalhes.

Modo de busca | Resumo
--- | ---
`PDO::FETCH_GROUP` | Os resultados estão agrupados pela primeira coluna.
`PDO::FETCH_UNIQUE` | Os resultados são indexados (exclusivamente) pela primeira coluna.

## Tratamento de nomes de colunas duplicados

É possível que os resultados contenham várias colunas com o mesmo nome. Por exemplo, ao unir duas tabelas que contêm uma coluna com o mesmo nome.

Como as estruturas do PHP, como arrays e objetos, não suportam múltiplas chaves ou propriedades com o mesmo nome, o array ou objeto retornado conterá apenas 1 dos valores com o mesmo nome.

O valor retornado para um determinado nome duplicado deve ser considerado indefinido.

Para evitar esse problema, nomeie as colunas explicitamente usando um sinônimo. Por exemplo:

    SELECT table1.created_at AS t1_created_at,
           table2.created_at AS t2_created_at
    FROM table1
    JOIN table2 ON table1.table2id = table2.id

Consulte também `PDO::FETCH_NAMED`, `PDO::ATTR_FETCH_TABLE_NAMES` e `PDO::ATTR_FETCH_CATALOG_NAMES`.

## Definindo o modo de busca padrão

É possível definir o modo de busca padrão para todas as consultas usando `PDO::ATTR_DEFAULT_FETCH_MODE` com PDO::__construct() ou PDO::setAttribute().

É possível definir o modo de busca padrão para uma instrução específica usando PDOStatement::setFetchMode(). Isso afeta a reutilização como uma instrução preparada e a iteração (usando `foreach`).

Cuidado

PDOStatement::setAttribute() não pode ser usado para definir o modo de busca padrão. Ele aceita apenas atributos específicos do driver e ignora silenciosamente os atributos que não são reconhecidos.

## PDO::FETCH_DEFAULT (int)

Disponível a partir do PHP 8.0.7.

Este é um valor especial que usa o modo de busca padrão atual para um PDOStatement. É particularmente útil como o valor padrão para parâmetros de método ao estender PDOStatement para uso com `PDO::ATTR_STATEMENT_CLASS`.

Este valor não pode ser usado com `PDO::ATTR_DEFAULT_FETCH_MODE`.

## PDO::FETCH_ASSOC (int)

`PDO::FETCH_ASSOC` retorna um array indexado apenas pelo nome da coluna.

    <?php
    $stmt = $pdo->query("SELECT userid, name, country FROM users");
    $row = $stmt->fetch(\PDO::FETCH_ASSOC);
    print_r($row);

O exemplo acima produzirá:

    Array
    (
        [userid] => 104
        [name] => Chris
        [country] => Ukraine
    )

## PDO::FETCH_BOTH (int)

Este é o modo de busca padrão.

`PDO::FETCH_BOTH` retorna uma matriz indexada tanto pelo número da coluna quanto pelo nome. Isso significa que cada valor retornado é duplicado para cada linha de resultado.

O número da coluna começa em 0 e é determinado pela ordem da coluna de resultado na consulta, não (por exemplo) pela ordem em que as colunas são definidas na tabela.

> Nota: Não é recomendável usar o índice numérico de coluna, pois ele pode mudar quando a consulta for alterada ou quando o esquema da tabela for alterado ao usar `SELECT *`.

> Nota: O número de entradas indexadas por nome pode não corresponder ao número de entradas indexadas por número nos casos em que várias colunas retornadas usam o mesmo nome.

    <?php
    $stmt = $pdo->query("SELECT userid, name, country FROM users");
    $row = $stmt->fetch(\PDO::FETCH_BOTH);
    print_r($row);

O exemplo acima produzirá:

    Array
    (
        [id] => 104,
        [0] => 104,
        [name] => Chris,
        [1] => Chris,
        [country] => Ukraine,
        [2] => Ukraine
    )

## PDO::FETCH_NAMED (int)

`PDO::FETCH_NAMED` retorna resultados no mesmo formato que `PDO::FETCH_ASSOC` exceto que, quando várias colunas usam o mesmo nome, todos os valores são retornados como uma lista.

Para obter mais informações sobre o tratamento de nomes de colunas duplicados e alternativas, consulte a seção tratamento de nomes duplicados acima.

A ordem em que os valores duplicados são retornados deve ser considerada indefinida. Não há como saber de onde cada valor veio.

    <?php
    $stmt = $pdo->query(
        "SELECT users.*, referrer.name
         FROM users
         LEFT JOIN users AS referrer ON users.referred_by = referrer.userid
         WHERE userid = 109"
    );
    $row = $stmt->fetch(\PDO::FETCH_NUM);
    print_r($row);

O exemplo acima produzirá:

    Array
    (
        [userid] => 109
        [name] => Array
            (
                [0] => Toni
                [1] => Chris
            )
        [country] => Germany
        [referred_by] = 104
    )

## PDO::FETCH_NUM (int)

`PDO::FETCH_NUM` retorna um array indexado apenas pelo número da coluna. O número da coluna começa em 0 e é determinado pela ordem da coluna de resultado na consulta, não (por exemplo) pela ordem em que as colunas são definidas na tabela.

> Nota: Não é recomendável usar o índice de coluna numérica, pois ele pode mudar quando a consulta for alterada ou quando o esquema da tabela for alterado ao usar `SELECT *`.

    <?php
    $stmt = $pdo->query("SELECT userid, name, country FROM users");
    $row = $stmt->fetch(\PDO::FETCH_NUM);
    print_r($row);

O exemplo acima produzirá:

    Array
    (
        [0] => 104
        [1] => Chris
        [2] => Ukraine
    )

## PDO::FETCH_COLUMN (int)

`PDO::FETCH_COLUMN` retorna valores de uma única coluna. Use o segundo argumento de PDOStatement::setFetchMode() ou PDOStatement::fetchAll() para especificar qual coluna será retornada.

Se a coluna especificada não existir, será lançado um ValueError.

    <?php
    $stmt = $pdo->query("SELECT name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_COLUMN);
    print_r($row);

    $stmt = $pdo->query("SELECT name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_COLUMN, 1);
    print_r($row);

O exemplo acima produzirá:

    Array
    (
        [0] => Chris
        [1] => Jamie
        [2] => Robin
    )

    Array
    (
        [0] => Ukraine
        [1] => England
        [2] => Germany
    )

## PDO::FETCH_KEY_PAIR (int)

`PDO::FETCH_KEY_PAIR` retorna pares de valores, indexados pela primeira coluna. Os resultados devem conter apenas 2 colunas. Este modo de busca só faz sentido com PDOStatement::fetchAll().

> Nota: Se a primeira coluna não for única, valores serão perdidos. Quais valores serão perdidos devem ser considerados indefinidos.

    <?php
    $stmt = $pdo->query("SELECT name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_KEY_PAIR);
    print_r($row);

O exemplo acima produzirá:

    Array
    (
        [Chris] => Ukraine
        [Jamie] => England
        [Robin] => Germany
    )

## PDO::FETCH_FUNC (int)

Especifique uma função para criar o valor retornado. Este modo só pode ser usado com PDOStatement::fetchAll().

A função recebe os valores como parâmetros. Não há como recuperar o nome da coluna à qual um determinado valor estava associado. É crucial garantir que a ordem das colunas na consulta corresponda à esperada pela função.

> Nota: Os efeitos de `PDO::FETCH_GROUP` e `PDO::FETCH_UNIQUE` são aplicados aos resultados antes da função ser chamada.

    <?php
    function valueCreator($col1, $col2, $col3)
    {
        return [
            'col1' => $col1,
            'col2' => strtoupper($col2),
            'col3' => $col3,
            'customKey' => 'customValue',
        ];
    }

    $stmt = $pdo->query("SELECT userid, name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_FUNC, valueCreator(...));
    print_r($row);

O exemplo acima produzirá:

    Array
    (
        [0] => Array
            (
                [col1] => 104
                [col2] => SAM
                [col3] => Ukraine
                [customKey] => customValue
            )

        [1] => Array
            (
                [col1] => 105
                [col2] => JAMIE
                [col3] => England
                [customKey] => customValue
            )

        [2] => Array
            (
                [col1] => 107
                [col2] => ROBIN
                [col3] => Germany
                [customKey] => customValue
            )

    )

## PDO::FETCH_OBJ (int)

`PDO::FETCH_OBJ` retorna um objeto stdClass.

Consulte também PDOStatement::fetchObject() e `PDO::FETCH_CLASS`.

    <?php
    $stmt = $pdo->query("SELECT userid, name, country FROM users");
    $row = $stmt->fetch(\PDO::FETCH_OBJ);
    print_r($row);

O exemplo acima produzirá:

    stdClass Object
    (
        [userid] => 104
        [name] => Chris
        [country] => Ukraine
    )

## PDO::FETCH_CLASS (int)

Retorna um objeto de uma classe especificada. Para comportamentos adicionais, consulte os sinalizadores de opções: sinalizadores de opções.

Se uma propriedade com o nome de uma coluna retornada não existir, ela será declarada dinamicamente. Esse comportamento foi descontinuado e causará um erro a partir do PHP 9.0.

Consulte também PDOStatement::fetchObject().

    <?php
    class TestEntity
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;

        public function __construct()
        {
            print "Construtor chamado com ". count(func_get_args()) ." argumentos\n";
            print "Propriedades definidas quando o construtor foi chamado? "
                . (isset($this->name) ? 'Sim' : 'Não') . "\n";
        }
    }

    $stmt = $db->query(
        "SELECT userid, name, country, referred_by_userid FROM users"
    );
    $stmt->setFetchMode(PDO::FETCH_CLASS, TestEntity::class);
    $result = $stmt->fetch();
    var_dump($result);

O exemplo acima produzirá algo semelhante a:

    Construtor chamado com 0 argumentoss
    Propriedades definidas quando o construtor foi chamado? Sim
    object(TestEntity)#3 (4) {
      ["userid"]=>
      int(104)
      ["name"]=>
      string(5) "Chris"
      ["country"]=>
      string(7) "Ukraine"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_CLASSTYPE (int)

Este modo de busca só pode ser usado em combinação com `PDO::FETCH_CLASS` (e suas outras opções).

Quando este modo de busca é usado, o PDO usará a primeira coluna retornada como o nome da classe a ser retornada.

Se a classe especificada não for encontrada, um objeto stdClass será retornado, sem aviso ou erro.

    <?php
    class TestEntity
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;

        public function __construct()
        {
            print "Construtor chamado com ". count(func_get_args()) ." argumentos\n";
            print "Propriedades definidas quando o construtor foi chamado? "
                . (isset($this->name) ? 'Sim' : 'Não') . "\n";
        }
    }

    $stmt = $db->query(
        "SELECT 'TestEntity', userid, name, country, referred_by_userid FROM users"
    );
    $stmt->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_CLASSTYPE);
    $result = $stmt->fetch();
    var_dump($result);

O exemplo acima produzirá algo semelhante a:

    Construtor chamado com 0 argumentos
    Propriedades definidas quando o construtor foi chamado? Sim
    object(TestEntity)#3 (4) {
      ["userid"]=>
      int(104)
      ["name"]=>
      string(5) "Chris"
      ["country"]=>
      string(7) "Ukraine"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_PROPS_LATE (int)

Este modo de busca só pode ser usado em combinação com `PDO::FETCH_CLASS` (e suas outras opções).

Quando este modo de busca é usado, o construtor será chamado antes que as propriedades sejam definidas.

    <?php
    class TestEntity
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;

        public function __construct()
        {
            print "Construtor chamado com ". count(func_get_args()) ." argumentos\n";
            print "Propriedades definidas quando o construtor foi chamado? "
                . (isset($this->name) ? 'Sim' : 'Não') . "\n";
        }
    }

    $stmt = $db->query(
        "SELECT userid, name, country, referred_by_userid FROM users"
    );
    $stmt->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_PROPS_LATE, TestEntity::class);
    $result = $stmt->fetch();
    var_dump($result);

O exemplo acima produzirá algo semelhante a:

    Construtor chamado com 0 argumentos
    Propriedades definidas quando o construtor foi chamado? Não
    object(TestEntity)#3 (4) {
      ["userid"]=>
      int(104)
      ["name"]=>
      string(5) "Chris"
      ["country"]=>
      string(7) "Ukraine"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_SERIALIZE (int)

Aviso

Este recurso foi DESCONTINUADO a partir do PHP 8.1.0. O uso deste recurso é fortemente desencorajado.

Este modo de busca só pode ser usado em combinação com `PDO::FETCH_CLASS` (e suas outras opções).

Quando este modo de busca é utilizado, a classe especificada deve ser Serializable.

Cuidado

Este recurso não suporta uma string que contenha um objeto serializado completo (com serialize()).

Cuidado

Este modo de busca não chama o construtor.

    <?php
    class TestEntity implements Serializable
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;

        public function __construct()
        {
            print "Construtor chamado com " . count(func_get_args()) . " argumentos\n";
            print "Propriedades definidas quando o construtor é chamado? "
                . (isset($this->name) ? 'Sim' : 'Não') . "\n";
        }

        public function serialize()
        {
            return join(
                "|",
                [$this->userid, $this->name, $this->country, $this->referred_by_userid]
            );
        }

        public function unserialize(string $data)
        {
            $parts = explode("|", $data);
            $this->userid = (int) $parts[0];
            $this->name = $parts[1];
            $this->country = $parts[2];

            $refId = $parts[3];
            $this->referred_by_userid = ($refId === "" ? null : (int) $refId);
        }
    }

    print "Definindo o registro (construtor chamado manualmente):\n";
    $db->exec(
        "CREATE TABLE serialize (
            sdata TEXT
        )"
    );

    $origObj = new TestEntity();
    $origObj->userid = 200;
    $origObj->name = 'Seri';
    $origObj->country = 'Syria';
    $origObj->referred_by_userid = null;

    $insert = $db->prepare("INSERT INTO serialize (sdata) VALUES (:sdata)");
    $insert->execute(['sdata' => $origObj->serialize()]);

    print "\nRecuperando o resultado:\n";
    $query = "SELECT sdata FROM serialize";
    $stmt = $db->query($query);
    // NOTA: O construtor nunca é chamado!
    $stmt->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_SERIALIZE, TestEntity::class);
    $result = $stmt->fetch();
    var_dump($result);

O exemplo acima produzirá algo semelhante a:

    Deprecated: TestEntity implements the Serializable interface, which is deprecated. Implement __serialize() and __unserialize() instead (or in addition, if support for old PHP versions is necessary) in Standard input code on line 2
    Definindo o registro (construtor chamado manualmente):
    Construtor chamado com 0 argumentos
    Propriedades definidas quando o construtor é chamado? Não

    Recuperando o resultado:
    Deprecated: PDOStatement::setFetchMode(): The PDO::FETCH_SERIALIZE mode is deprecated in Standard input code on line 58

    Deprecated: PDOStatement::fetch(): The PDO::FETCH_SERIALIZE mode is deprecated in Standard input code on line 59
    object(TestEntity)#5 (4) {
      ["userid"]=>
      int(200)
      ["name"]=>
      string(4) "Seri"
      ["country"]=>
      string(5) "Syria"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_BOUND (int)

Este modo de busca não pode ser usado com PDOStatement::fetchAll().

Este modo de busca não retorna um resultado diretamente, mas associa valores a variáveis ​​especificadas com PDOStatement::bindColumn(). O método de busca chamado retorna `true`.

> Nota: Ao usar instruções preparadas, para funcionar corretamente, as variáveis ​​devem ser vinculadas após a execução da consulta.

    <?php
    $query = "SELECT users.userid, users.name, users.country, referrer.name
        FROM users
        LEFT JOIN users AS referrer ON users.referred_by_userid = referrer.userid";
    $stmt = $db->prepare($query);
    $stmt->execute();

    $stmt->bindColumn('userid', $userId);
    $stmt->bindColumn('name', $name);
    $stmt->bindColumn('country', $country);
    // Vincule pela posição da coluna para resolver nomes de coluna duplicados
    // Para evitar que isso cause problemas se a consulta for alterada, use um sinônimo SQL.
    // Por exemplo: referrer.name AS referrer_name
    $stmt->bindColumn(4, $referrerName);

    while ($stmt->fetch(\PDO::FETCH_BOUND)) {
        print join("\t", [$userId, $name, $country, ($referrerName ?? 'NULL')]) . "\n";
    }

O exemplo acima produzirá:

    104	Chris	Ukraine	NULL
    105	Jamie	England	NULL
    107	Robin	Germany	Chris
    108	Sean	Ukraine	NULL
    109	Toni	Germany	NULL
    110	Toni	Germany	NULL

## PDO::FETCH_INTO (int)

Este modo de busca não pode ser usado com PDOStatement::fetchAll().

Este modo de busca atualiza as propriedades do objeto especificado. O objeto é retornado em caso de sucesso.

Se uma propriedade com o nome de uma coluna retornada não existir, ela será declarada dinamicamente. Esse comportamento está obsoleto e causará um erro a partir do PHP 9.0.

Propriedades precisam ser `public` e não podem ser `readonly`.

Cuidado

Não há como alterar o objeto a ser atualizado sem usar PDOStatement::setFetchMode() entre a recuperação de cada registro.

    <?php

    class TestEntity
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;
    }

    $obj = new TestEntity();

    $stmt = $db->query("SELECT userid, name, country, referred_by_userid FROM users");

    $stmt->setFetchMode(\PDO::FETCH_INTO, $obj);
    $result = $stmt->fetch();

    var_dump($result);

O exemplo acima produzirá algo semelhante a:

    object(TestEntity)#3 (4) {
      ["userid"]=>
      int(104)
      ["name"]=>
      string(5) "Chris"
      ["country"]=>
      string(7) "Ukraine"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_LAZY (int)

Este modo de busca não pode ser usado com PDOStatement::fetchAll().

Este modo de busca retorna um objeto PDORow que fornece acesso a valores tanto no formato de array quanto no formato de objeto (ou seja, combina o comportamento de `PDO::FETCH_BOTH` e `PDO::FETCH_OBJ`), recuperados de forma lenta.

Isso pode fornecer acesso eficiente em termos de memória (no lado do PHP) a resultados não armazenados em buffer no servidor de banco de dados. Se o PDO usa buffer no lado do cliente para resultados depende do driver específico do banco de dados usado (e de sua configuração).

Cuidado

PDORow retornará `NULL` sem qualquer erro ou aviso ao acessar propriedades ou chaves que não estejam definidas. Isso pode dificultar a detecção e depuração de erros como erros de digitação ou consultas que não retornam os dados esperados.

Cuidado

O objeto PDORow retornado é atualizado cada vez que um resultado é recuperado.

    <?php
    $stmt = $db->query("SELECT userid, name, country, referred_by_userid FROM users");
    $result = $stmt->fetch(\PDO::FETCH_LAZY);

    print "ID: ". $result[0] ."\n";
    print "Nome: {$result->name}\n";
    print "País: " . $result['country'] ."\n";
    // Retorna NULL. Nenhum aviso ou erro é emitido.
    print "Não existe: " . var_export($result->does_not_exist, true) . "\n";

    $differentResult = $stmt->fetch(\PDO::FETCH_LAZY);
    // O PDORow recuperado anteriormente agora aponta para o resultado recém-recuperado.
    print "ID: ". $result[0] ."\n";

O exemplo acima produzirá:

    ID: 104
    Nome: Chris
    País: Ukraine
    Não existe: NULL
    ID: 105

## PDO::FETCH_GROUP (int)

`PDO::FETCH_GROUP` retorna listas de arrays associativos, indexados por uma coluna (não única). Este modo de busca funciona apenas com PDOStatement::fetchAll().

Quando combinado com `PDO::FETCH_UNIQUE`, ambos os modos usarão a mesma coluna, tornando a combinação desses modos inútil.

Esta busca deve ser combinada com uma das seguintes constantes: `PDO::FETCH_ASSOC`, `PDO::FETCH_BOTH`, `PDO::FETCH_NAMED`, `PDO::FETCH_NUM`, `PDO::FETCH_COLUMN` ou `PDO::FETCH_FUNC`.

Se nenhum modo de busca da lista acima for fornecido, o modo de busca padrão atual para o PDOStatement será usado.

    <?php
    $stmt = $pdo->query("SELECT country, userid, name FROM users");
    $row = $stmt->fetchAll(\PDO::FETCH_GROUP | \PDO::FETCH_ASSOC);
    print_r($row);

O exemplo acima produzirá:

    Array
    (
        [Ukraine] => Array
            (
                [0] => Array
                    (
                        [userid] => 104
                        [name] => Chris
                    )

                [1] => Array
                    (
                        [userid] => 108
                        [name] => Sean
                    )

            )
        [England] => Array
            (
                [0] => Array
                    (
                        [userid] => 105
                        [name] => Jamie
                    )

            )

        [Germany] => Array
            (
                [0] => Array
                    (
                        [userid] => 107
                        [name] => Robin
                    )

                [1] => Array
                    (
                        [userid] => 109
                        [name] => Toni
                    )
            )
    )

No exemplo acima, pode ser observado que a primeira coluna é omitida do array de cada linha, estando disponível apenas como chave. Ela pode ser incluída repetindo a coluna, como no exemplo a seguir:

    <?php
    $stmt = $pdo->query("SELECT country, userid, name, country FROM users");
    $row = $stmt->fetchAll(\PDO::FETCH_GROUP | \PDO::FETCH_ASSOC);
    print_r($row);

O exemplo acima produzirá:

    Array
    (
        [Ukraine] => Array
            (
                [0] => Array
                    (
                        [userid] => 104
                        [name] => Chris
                        [country] => Ukraine
                    )

                [1] => Array
                    (
                        [userid] => 108
                        [name] => Sean
                        [country] => Ukraine
                    )

            )
        [England] => Array
            (
                [0] => Array
                    (
                        [userid] => 105
                        [name] => Jamie
                        [country] => England
                    )

            )

        [Germany] => Array
            (
                [0] => Array
                    (
                        [userid] => 107
                        [name] => Robin
                        [country] => Germany
                    )

                [1] => Array
                    (
                        [userid] => 109
                        [name] => Toni
                        [country] => Germany
                    )
            )
    )

## PDO::FETCH_UNIQUE (int)

`PDO::FETCH_UNIQUE` usa a primeira coluna para indexar registros, retornando 1 registro por valor de índice. Este modo de busca funciona apenas com PDOStatement::fetchAll().

Quando combinado com `PDO::FETCH_GROUP`, ambos os modos usarão a mesma coluna, tornando a combinação desses modos inútil.

Esta busca deve ser combinada com uma das seguintes constantes `PDO::FETCH_ASSOC`, `PDO::FETCH_BOTH`, `PDO::FETCH_NAMED`, `PDO::FETCH_NUM`, `PDO::FETCH_COLUMN` ou `PDO::FETCH_FUNC`.

Se nenhum modo de busca da lista acima for fornecido, o modo de busca padrão atual para o PDOStatement será usado.

Quando usado com uma coluna que se sabe ser única (como o ID do registro), este modo oferece a capacidade de retornar rapidamente resultados indexados por esse valor.

> Nota: Se a primeira coluna não for única, valores serão perdidos. Quais valores serão perdidos devem ser considerados indefinidos.

Cuidado

A filtragem de registros deve ser feita em SQL sempre que possível. O banco de dados usará índices para otimizar esse processo e retornar apenas os registros necessários. Selecionar mais registros do que o necessário do banco de dados pode aumentar significativamente o uso de memória e o tempo de consulta para conjuntos de resultados maiores.

    <?php
    $stmt = $pdo->query("SELECT userid, name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_UNIQUE | \PDO::FETCH_ASSOC);
    print_r($row);

O exemplo acima produzirá:

    Array
    (
        [104] => Array
            (
                [name] => Chris
                [country] => Ukraine
            )

        [105] => Array
            (
                [name] => Jamie
                [country] => England
            )

        [107] => Array
            (
                [name] => Robin
                [country] => Germany
            )

    )

No exemplo acima, pode ser observado que a primeira coluna é omitida do array de cada linha, estando disponível apenas como chave. Ela pode ser incluída repetindo a coluna, como no exemplo a seguir:

    <?php
    $stmt = $pdo->query("SELECT userid, userid, name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_UNIQUE | \PDO::FETCH_ASSOC);
    print_r($row);

O exemplo acima produzirá:

    Array
    (
        [104] => Array
            (
                [userid] => 104
                [name] => Chris
                [country] => Ukraine
            )

        [105] => Array
            (
                [userid] => 105
                [name] => Jamie
                [country] => England
            )

        [107] => Array
            (
                [userid] => 107
                [name] => Robin
                [country] => Germany
            )

    )

## Cursores

Veja também `PDO::ATTR_CURSOR_NAME`.

`PDO::FETCH_ORI_NEXT` (int)
  Busca a próxima linha no conjunto de resultados. Válido apenas para cursores roláveis.
`PDO::FETCH_ORI_PRIOR` (int)
  Busca a linha anterior no conjunto de resultados. Válido apenas para cursores roláveis.
`PDO::FETCH_ORI_FIRST` (int)
  Busca a primeira linha no conjunto de resultados. Válido apenas para cursores roláveis.
`PDO::FETCH_ORI_LAST` (int)
  Busca a última linha no conjunto de resultados. Válido apenas para cursores roláveis.
`PDO::FETCH_ORI_ABS` (int)
  Busca a linha solicitada pelo número da linha do conjunto de resultados. Válida somente para cursores roláveis.
`PDO::FETCH_ORI_REL` (int)
  Busca a linha solicitada pela posição relativa à posição atual do cursor no conjunto de resultados. Válida somente para cursores roláveis.
`PDO::CURSOR_FWDONLY` (int)
  Cria um objeto PDOStatement com um cursor somente para frente. Esta é a escolha de cursor padrão, pois é o padrão mais rápido e comum de acesso a dados em PHP.
`PDO::CURSOR_SCROLL` (int)
  Cria um objeto PDOStatement com um cursor rolável. Passe as constantes `PDO::FETCH_ORI_*` para controlar as linhas buscadas do conjunto de resultados.

## Outras constantes

`PDO::PARAM_BOOL` (int)
  Representa um tipo de dado booleano.
`PDO::PARAM_NULL` (int)
  Representa o tipo de dado SQL NULL.
`PDO::PARAM_INT` (int)
  Representa o tipo de dados SQL INTEGER.
`PDO::PARAM_STR` (int)
  Representa o tipo de dados SQL CHAR, VARCHAR ou outra string.
`PDO::PARAM_STR_NATL` (int)
  Sinaliza que uma string usa o conjunto de caracteres nacional. Disponível a partir do PHP 7.2.0
`PDO::PARAM_STR_CHAR` (int)
  Sinaliza que uma string usa o conjunto de caracteres regular. Disponível a partir do PHP 7.2.0
`PDO::PARAM_LOB` (int)
  Representa o tipo de dados SQL large object.
`PDO::PARAM_STMT` (int)
  Representa um tipo de conjunto de registros. Atualmente não suportado por nenhum driver.
`PDO::PARAM_INPUT_OUTPUT` (int)
  Especifica que o parâmetro é um parâmetro INOUT para um procedimento armazenado. Esse valor deve ser combinado através de OR binário com uma das constantes `PDO::PARAM_*`.
`PDO::ATTR_AUTOCOMMIT` (bool)
  Se esse valor for `false`, o PDO tenta desativar o autocommit para que a conexão inicie uma transação. A partir do PHP 8.4.0, esta constante é tipada como bool; anteriormente, era tipada como int.
`PDO::ATTR_PREFETCH` (int)
  Definir o tamanho da pré-busca permite balancear entre velocidade e uso de memória em uma aplicação. Nem todas as combinações de banco de dados e drivers suportam a definição do tamanho do pré-busca. Um tamanho de pré-busca maior resulta em um aumento de desempenho com o custo de um uso maior de memória. O driver PDO_PGSQL, por sua vez, trata esse atributo como uma opção: a partir do PHP 8.5.0, o valor `0` habilita a busca lenta (linha única); consulte a documentação do driver PDO_PGSQL para obter detalhes.
`PDO::ATTR_TIMEOUT` (int)
  Define o valor de tempo limite em segundos para comunicações com o banco de dados.
`PDO::ATTR_ERRMODE` (int)
  Consulte a seção Erros e tratamento de erros para obter mais informações sobre este atributo.
`PDO::ATTR_SERVER_VERSION` (int)
  Este é um atributo somente leitura; ele retornará informações sobre a versão do servidor de banco de dados ao qual o PDO está conectado.
`PDO::ATTR_CLIENT_VERSION` (int)
  Este é um atributo somente leitura; ele retornará informações sobre a versão das bibliotecas de cliente que o driver PDO está usando.
`PDO::ATTR_SERVER_INFO` (int)
  Este é um atributo somente leitura; ele retornará algumas informações meta sobre o servidor de banco de dados ao qual o PDO está conectado.
`PDO::ATTR_CONNECTION_STATUS` (int)
`PDO::ATTR_CASE` (int)
  Força os nomes das colunas para um caso específico definido pelas constantes `PDO::CASE_*`.
`PDO::ATTR_CURSOR_NAME` (int)
  Obtém ou define o nome a ser usado para um cursor. Mais útil ao usar cursores roláveis e atualizações posicionadas.
`PDO::ATTR_CURSOR` (int)
  Seleciona o tipo de cursor. O PDO atualmente suporta `PDO::CURSOR_FWDONLY` ou `PDO::CURSOR_SCROLL`. A menos que haja necessidade de cursores roláveis, deve-se usar o modo de cursor `PDO::CURSOR_FWDONLY`.
`PDO::ATTR_DRIVER_NAME` (int)
  Retorna o nome do driver.

  Exemplo #1 using `PDO::ATTR_DRIVER_NAME`

      <?php
       if ($db->getAttribute(PDO::ATTR_DRIVER_NAME) == 'mysql') {
         echo "Running on mysql; doing something mysql specific here\n";
       }
       ?>

`PDO::ATTR_ORACLE_NULLS` (int)
  Converte strings vazias em valores SQL NULL em buscas de dados.
`PDO::ATTR_PERSISTENT` (int)
  Solicita uma conexão persistente, em vez de criar uma nova conexão. Consulte Conexões e Gerenciamento de Conexões para obter mais informações sobre este atributo.
`PDO::ATTR_STATEMENT_CLASS` (int)
  Define o nome da classe de que as declarações são retornadas.
`PDO::ATTR_FETCH_CATALOG_NAMES` (int)
  Adiciona o nome do catálogo contenedor a cada nome de coluna retornado no conjunto de resultados. O nome do catálogo e o nome da coluna são separados por um caractere de ponto (.). O suporte deste atributo é no nível do driver; pode não ser suportado pelo driver em uso.
`PDO::ATTR_FETCH_TABLE_NAMES` (int)
  Adiciona o nome da tabela contenedora a cada nome de coluna retornado no conjunto de resultados. O nome da tabela e o nome da coluna são separados por um caractere de ponto (.). O suporte deste atributo é no nível do driver; pode não ser suportado pelo driver em uso.
`PDO::ATTR_STRINGIFY_FETCHES` (int)
  Força todos os valores buscados (exceto `null`) a serem tratados como strings. Valores `null` permanecem inalterados a menos que `PDO::ATTR_ORACLE_NULLS` esteja definida para `PDO::NULL_TO_STRING`.
`PDO::ATTR_MAX_COLUMN_LEN` (int)
  Define o comprimento máximo do nome da coluna.
`PDO::ATTR_DEFAULT_FETCH_MODE` (int)
`PDO::ATTR_EMULATE_PREPARES` (bool)
  Se deve habilitar ou desabilitar a emulação de instruções preparadas. Alguns drivers não suportam instruções preparadas nativas ou têm suporte apenas limitado a elas. Quando definido como `true`, o PDO sempre emula instruções preparadas; quando definido como `false`, ele usa as instruções preparadas nativas do driver. A partir do PHP 8.4.0, esta constante é tipada como bool; anteriormente, era tipada como int.
`PDO::ATTR_DEFAULT_STR_PARAM` (int)
  Define o tipo de parâmetro de string padrão, que pode ser um dos `PDO::PARAM_STR_NATL` e `PDO::PARAM_STR_CHAR`. Disponível a partir do PHP 7.2.0.
`PDO::ERRMODE_SILENT` (int)
  Não gera um erro ou exceção se ocorrer um erro. É esperado que o próprio desenvolvedor verifique explicitamente os erros. Anteriormente ao PHP 8.0.0, este era o modo padrão. Consulte Erros e tratamento de erros para mais informações sobre este atributo.
`PDO::ERRMODE_WARNING` (int)
  Emite uma mensagem PHP `E_WARNING` se ocorrer um erro. Consulte Erros e tratamento de erros para mais informações sobre este atributo.
`PDO::ERRMODE_EXCEPTION` (int)
  Lança uma PDOException se ocorrer um erro. Este é o modo padrão a partir do PHP 8.0.0. Consulte Erros e tratamento de erros para mais informações sobre este atributo.
`PDO::CASE_NATURAL` (int)
  Deixa os nomes das colunas como retornados pelo driver do banco de dados.
`PDO::CASE_LOWER` (int)
  Força os nomes das colunas em minúsculas.
`PDO::CASE_UPPER` (int)
  Força os nomes das colunas em maiúsculas.
`PDO::NULL_NATURAL` (int)
`PDO::NULL_EMPTY_STRING` (int)
`PDO::NULL_TO_STRING` (int)
`PDO::ERR_NONE` (string)
  Corresponde a SQLSTATE `'00000'`, significando que a instrução SQL foi emitida com sucesso sem erros ou avisos. Esta constante é uma conveniência ao verificar PDO::errorCode() ou PDOStatement::errorCode() para determinar se ocorreu um erro. De qualquer forma, isto geralmente é determinado pela verificação do código de retorno do método que gerou a condição de erro.
`PDO::PARAM_EVT_ALLOC` (int)
  Evento de alocação
`PDO::PARAM_EVT_FREE` (int)
  Evento de desalocação
`PDO::PARAM_EVT_EXEC_PRE` (int)
  Evento acionado antes da execução de uma instrução preparada.
`PDO::PARAM_EVT_EXEC_POST` (int)
  Evento acionado após a execução de uma instrução preparada.
`PDO::PARAM_EVT_FETCH_PRE` (int)
  Evento acionado antes de buscar um resultado de um conjunto de resultados.
`PDO::PARAM_EVT_FETCH_POST` (int)
  Evento acionado após buscar um resultado de um conjunto de resultados.
`PDO::PARAM_EVT_NORMALIZE` (int)
  Evento acionado durante o registro de parâmetro vinculado, permitindo ao driver normalizar o nome do parâmetro.
`PDO::SQLITE_DETERMINISTIC` (int)
  Especifica que uma função criada com PDO::sqliteCreateFunction() é determinística, ou seja, ela sempre retorna o mesmo resultado dados os mesmos inputs dentro de uma única instrução SQL. (Disponível a partir do PHP 7.1.4.)

# Conexões e gerenciamento de conexões

As conexões são estabelecidas criando instâncias da classe base PDO. Não importa qual driver você deseja usar; você sempre usa o nome da classe PDO. O construtor aceita parâmetros para especificar a fonte do banco de dados (conhecida como DSN) e opcionalmente para o nome de usuário e senha (se houver).

Exemplo #1 Conectando-se ao MySQL

    <?php
    $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
    ?>

Se houver algum erro de conexão, um objeto `PDOException` será lançado. Você pode capturar a exceção se quiser lidar com a condição de erro, ou pode optar por deixá-la para um manipulador de exceção global do aplicativo que você configurou via set_exception_handler().

Exemplo #2 Tratando erros de conexão

    <?php
    try {
        $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
    } catch (PDOException $e) {
        // tentar reconectar após algum intervalo, por exemplo
    }

Aviso

Assim como qualquer outra exceção, PDOException pode ser capturada explicitamente, via uma instrução `catch`, ou implicitamente através de set_exception_handler(). Caso contrário, o comportamento padrão de converter uma exceção não capturada em um `E_FATAL_ERROR` ocorrerá. O erro fatal conterá uma rastreabilidade que pode vazar detalhes da conexão. Portanto, a opção php.ini `display_errors` deve ser definida como `0` em um servidor de produção.

Após a conexão bem-sucedida com o banco de dados, uma instância da classe PDO é retornada para seu script. A conexão permanece ativa pelo tempo de vida desse objeto PDO. Para fechar a conexão, você precisa destruir o objeto garantindo que todas as referências restantes a ele sejam deletadas - você faz isso atribuindo `null` à variável que mantém o objeto. Se você não fizer isso explicitamente, o PHP fechará automaticamente a conexão quando seu script terminar.

> Nota: Se ainda houver outras referências a esta instância PDO (como de uma instância PDOStatement, ou de outras variáveis referenciando a mesma instância PDO), estas também devem ser removidas (por exemplo, atribuindo `null` à variável que referencia a instância PDOStatement).

Exemplo #3 Fechando uma conexão

    <?php
    $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
    // use a conexão aqui
    $sth = $dbh->query('SELECT * FROM foo');

    // e agora terminamos; feche-a
    $sth = null;
    $dbh = null;
    ?>

Muitas aplicações web se beneficiarão com a realização de conexões persistentes com servidores de banco de dados. As conexões persistentes não são fechadas no final do script, mas são armazenadas em cache e reutilizadas quando outro script solicita uma conexão usando as mesmas credenciais. O cache de conexão persistente permite evitar a sobrecarga de estabelecer uma nova conexão toda vez que um script precisa se comunicar com um banco de dados, resultando em uma aplicação web mais rápida.

Exemplo #4 Conexões persistentes

    <?php
    $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass, array(
        PDO::ATTR_PERSISTENT => true
    ));
    ?>

O valor da opção `PDO::ATTR_PERSISTENT` é convertido para bool (ativar/desativar conexões persistentes), a menos que seja uma string não numérica, caso em que permite usar vários pools de conexões persistentes. Isso é útil se diferentes conexões usam configurações incompatíveis, por exemplo, valores diferentes de `PDO::MYSQL_ATTR_USE_BUFFERED_QUERY`.

> Nota:

> Se desejar usar conexões persistentes, você deve definir `PDO::ATTR_PERSISTENT` no array de opções do driver passadas para o construtor PDO. Se definir este atributo com PDO::setAttribute() após a instanciação do objeto, o driver não usará conexões persistentes.

Aviso

O PDO não realiza nenhuma limpeza de conexões persistentes. Tabelas temporárias, bloqueios, transações e outras alterações de estado podem permanecer do uso anterior da conexão, causando problemas inesperados. Consulte a seção Conexões de Banco de Dados Persistentes para obter mais informações.

> Nota:

> Se estiver usando o driver PDO ODBC e suas bibliotecas ODBC suportarem Pool de Conexões ODBC (unixODBC e Windows são duas que suportam; pode haver mais), então é recomendável que você não use conexões PDO persistentes e, em vez disso, deixe o cache de conexão para a camada de Pool de Conexões ODBC. O Pool de Conexões ODBC é compartilhado com outros módulos no processo; se o PDO for instruído a armazenar em cache a conexão, então essa conexão nunca seria retornada ao pool de conexões ODBC, resultando em conexões adicionais sendo criadas para atender a esses outros módulos.

# Transações e confirmação automática (auto-commit)

Agora que você está conectado via PDO, é necessário entender como o PDO gerencia transações antes de começar a emitir consultas. Se você nunca encontrou transações antes, elas oferecem 4 recursos principais: Atomicidade, Consistência, Isolamento e Durabilidade (ACID). Em termos simples, qualquer trabalho realizado em uma transação, mesmo que seja feito em etapas, é garantido de ser aplicado ao banco de dados com segurança e sem interferência de outras conexões, quando é confirmado. O trabalho transacional também pode ser desfeito automaticamente a seu pedido (desde que você ainda não tenha confirmado), o que facilita o tratamento de erros em seus scripts.

As transações são tipicamente implementadas "salvando" seu lote de alterações para serem aplicadas de uma vez; isso tem o efeito colateral agradável de melhorar drasticamente a eficiência dessas atualizações. Em outras palavras, transações podem tornar seus scripts mais rápidos e potencialmente mais robustos (ainda é necessário usá-los corretamente para obter esse benefício).

Infelizmente, nem todos os bancos de dados suportam transações, então o PDO precisa rodar no que é conhecido como modo "auto-commit" quando você abre a conexão pela primeira vez. O modo auto-commit significa que cada consulta que você executa tem sua própria transação implícita, se o banco de dados suportar, ou nenhuma transação se o banco de dados não suportar transações. Se você precisar de uma transação, você deve usar o método PDO::beginTransaction() para iniciá-la. Se o driver subjacente não suportar transações, uma PDOException será lançada (independentemente das suas configurações de tratamento de erro: essa é sempre uma condição de erro grave). Uma vez que você está em uma transação, você pode usar PDO::commit() ou PDO::rollBack() para finalizá-la, dependendo do sucesso do código que você executou durante a transação.

Aviso

O PDO verifica apenas as capacidades de transação no nível do driver. Se certas condições de tempo de execução significarem que transações estão indisponíveis, PDO::beginTransaction() ainda retornará `true` sem erro se o servidor de banco de dados aceitar a solicitação para iniciar uma transação.

Um exemplo disso seria tentar usar transações em tabelas MyISAM em um banco de dados MySQL.

Aviso

Confirmações Implícitas com Instruções DDL: Alguns bancos de dados emitem automaticamente um `COMMIT` implícito quando uma instrução de Linguagem de Definição de Banco de Dados (DDL), como `DROP TABLE` ou `CREATE TABLE`, é executada dentro de uma transação. Isto significa que quaisquer modificações feitas na mesma transação serão confirmadas automaticamente e não poderão ser revertidas.

`MySQL` e `Oracle` são exemplos de bancos de dados que exibem este comportamento.

Exemplo #1 Exemplo de Confirmação Implícita

    <?php
    $pdo->beginTransaction();
    $pdo->exec("INSERT INTO users (name) VALUES ('Rasmus')");
    $pdo->exec("CREATE TABLE test (id INT PRIMARY KEY)"); // aqui ocorre um COMMIT implícito
    $pdo->rollBack(); // Isto NÃO irá desfazer as instruções INSERT/CREATE no MySQL ou no Oracle
    ?>

Melhores Práticas: Evite executar instruções DDL dentro de transações quando usar banco de dados que têm este comportamento. Se necessário, separe as operações DDL da lógica das transações.

Quando o script termina ou quando uma conexão está prestes a ser fechada, se você tiver uma transação pendente, o PDO automaticamente a reverterá. Esta é uma medida de segurança para ajudar a evitar inconsistências nos casos em que o script termina inesperadamente--se você não confirmou explicitamente a transação, então é assumido que algo deu errado, então o rollback é executado para a segurança de seus dados.

Aviso

O rollback automático só acontece se você iniciar a transação via PDO::beginTransaction(). Se você emitir manualmente uma consulta que inicia uma transação, o PDO não tem como saber sobre isso e assim não pode revertê-la se algo ruim acontecer.

Exemplo #2 Executando um lote em uma transação

No exemplo a seguir, vamos assumir que estamos criando um conjunto de entradas para um novo funcionário, que recebeu um número de ID 23. Além de inserir os dados básicos para essa pessoa, também precisamos registrar seu salário. É bastante simples fazer duas atualizações separadas, mas ao envolvê-las nas chamadas PDO::beginTransaction() e PDO::commit(), estamos garantindo que ninguém mais poderá ver essas alterações até que elas estejam completas. Se algo der errado, o bloco catch reverte todas as alterações feitas desde que a transação foi iniciada e, em seguida, imprime uma mensagem de erro.

    <?php
    try {
      $dbh = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2',
          array(PDO::ATTR_PERSISTENT => true));
      echo "Connected\n";
    } catch (Exception $e) {
      die("Não foi possível conectar: " . $e->getMessage());
    }

    try {
      $dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

      $dbh->beginTransaction();
      $dbh->exec("insert into staff (id, first, last) values (23, 'Joe', 'Bloggs')");
      $dbh->exec("insert into salarychange (id, amount, changedate)
          values (23, 50000, NOW())");
      $dbh->commit();

    } catch (Exception $e) {
      $dbh->rollBack();
      echo "Falha: " . $e->getMessage();
    }
    ?>

Você não está limitado a fazer atualizações em uma transação; você também pode emitir consultas complexas para extrair dados e possivelmente usar essas informações para construir mais atualizações e consultas; enquanto a transação estiver ativa, você tem a garantia de que ninguém mais pode fazer alterações enquanto você está no meio do seu trabalho. Para ler mais sobre transações, consulte a documentação fornecida pelo seu servidor de banco de dados.

# Declarações preparadas e procedimentos armazenados

Muitos dos bancos de dados mais maduros suportam o conceito de declarações preparadas. O que são elas? Elas podem ser consideradas como uma espécie de modelo compilado para o SQL que uma aplicação deseja executar, que pode ser personalizado usando parâmetros variáveis. As declarações preparadas oferecem dois benefícios principais:

- A consulta só precisa ser analisada (ou preparada) uma vez, mas pode ser executada várias vezes com os mesmos ou diferentes parâmetros. Quando a consulta é preparada, o banco de dados irá analisar, compilar e otimizar seu plano para executar a consulta. Para consultas complexas, esse processo pode levar tempo suficiente para diminuir perceptivelmente o desempenho de uma aplicação se houver necessidade de repetir a mesma consulta muitas vezes com diferentes parâmetros. Ao usar uma declaração preparada, a aplicação evita repetir o ciclo de análise/compilação/otimização. Isso significa que declarações preparadas usam menos recursos e, portanto, são mais rápidas.
- Os parâmetros das declarações preparadas não precisam ser citados; o driver lida automaticamente com isso. Se uma aplicação usar exclusivamente declarações preparadas, o desenvolvedor pode ter certeza de que nenhuma injeção de SQL ocorrerá (no entanto, se outras partes da consulta estiverem sendo construídas com entrada não escapada, a injeção de SQL ainda é possível).

As declarações preparadas são tão úteis que são a única funcionalidade que o PDO emula para drivers que não as suportam. Isso garante que uma aplicação poderá usar o mesmo paradigma de acesso a dados, independentemente das capacidades do banco de dados.

Exemplo #1 Inserções repetidas usando declarações preparadas

Este exemplo executa uma consulta INSERT substituindo um `name` e um `value` pelos marcadores de posição nomeados.

    <?php
    $stmt = $dbh->prepare("INSERT INTO REGISTRY (name, value) VALUES (:name, :value)");
    $stmt->bindParam(':name', $name);
    $stmt->bindParam(':value', $value);

    // insere uma linha
    $name = 'one';
    $value = 1;
    $stmt->execute();

    // insere outra linha com valores diferentes
    $name = 'two';
    $value = 2;
    $stmt->execute();
    ?>

Exemplo #2 Inserções repetidas usando declarações preparadas

Este exemplo executa uma consulta INSERT substituindo um `name` e um `value` pelos marcadores de posição posicionais `?`.

    <?php
    $stmt = $dbh->prepare("INSERT INTO REGISTRY (name, value) VALUES (?, ?)");
    $stmt->bindParam(1, $name);
    $stmt->bindParam(2, $value);

    // insere uma linha
    $name = 'one';
    $value = 1;
    $stmt->execute();

    // insere outra linha com valores diferentes
    $name = 'two';
    $value = 2;
    $stmt->execute();
    ?>

Exemplo #3 Buscando dados usando declarações preparadas

Este exemplo busca dados com base em um valor de chave fornecido por um formulário. A entrada do usuário é automaticamente citada, portanto, não há risco de um ataque de injeção de SQL.

    <?php
    $stmt = $dbh->prepare("SELECT * FROM REGISTRY where name = ?");
    $stmt->execute([$_GET['name']]);
    foreach ($stmt as $row) {
      print_r($row);
    }
    ?>

Exemplo #4 Chamando um procedimento armazenado com um parâmetro de saída

Se o driver do banco de dados suportar, uma aplicação também pode vincular parâmetros de saída além de entrada. Os parâmetros de saída são normalmente usados para recuperar valores de procedimentos armazenados. Os parâmetros de saída são um pouco mais complexos de usar do que os parâmetros de entrada, pois um desenvolvedor deve saber o quão grande um determinado parâmetro pode ser quando o vincula. Se o valor for maior do que o tamanho sugerido, um erro será gerado.

    <?php
    $stmt = $dbh->prepare("CALL sp_returns_string(?)");
    $stmt->bindParam(1, $return_value, PDO::PARAM_STR, 4000);

    // chamar o procedimento armazenado
    $stmt->execute();

    print "procedure returned $return_value\n";
    ?>

Exemplo #5 Chamando um procedimento armazenado com um parâmetro de entrada/saída

Os desenvolvedores também podem especificar parâmetros que contêm valores tanto de entrada quanto de saída; a sintaxe é semelhante aos parâmetros de saída. No próximo exemplo, a string 'hello' é passada para o procedimento armazenado e, quando ele retorna, hello é substituído pelo valor de retorno do procedimento.

    <?php
    $stmt = $dbh->prepare("CALL sp_takes_string_returns_string(?)");
    $value = 'hello';
    $stmt->bindParam(1, $value, PDO::PARAM_STR|PDO::PARAM_INPUT_OUTPUT, 4000);

    // chamar o procedimento armazenado
    $stmt->execute();

    print "procedure returned $value\n";
    ?>

Exemplo #6 Uso inválido de marcador de posição

    <?php
    $stmt = $dbh->prepare("SELECT * FROM REGISTRY where name LIKE '%?%'");
    $stmt->execute([$_GET['name']]);

    // o marcador de posição deve ser usado no lugar do valor inteiro
    $stmt = $dbh->prepare("SELECT * FROM REGISTRY where name LIKE ?");
    $stmt->execute(["%$_GET[name]%"]);
    ?>

# Erros e manipulação de erros

O PDO oferece a escolha entre 3 estratégias diferentes de manipulação de erros, para se adequar ao estilo de cada desenvolvedor de aplicações.

- `PDO::ERRMODE_SILENT`

  Antes do PHP 8.0.0, este era o modo padrão. O PDO simplesmente definia o código de erro inspecionado pelos métodos PDO::errorCode() e PDO::errorInfo() tanto nos objetos de instrução quanto no banco de dados; se o erro resultasse de uma chamada no objeto de instrução, invocaria-se o método PDOStatement::errorCode() ou PDOStatement::errorInfo() nesse objeto. Se o erro resultasse de uma chamada no objeto de banco de dados, invocaria-se esses métodos no objeto de banco de dados em vez disso.

- `PDO::ERRMODE_WARNING`

  Além de definir o código de erro, o PDO emitirá uma mensagem de E_WARNING tradicional. Esta configuração é útil durante a depuração/teste, se você apenas quiser ver quais problemas ocorreram sem interromper o fluxo do aplicativo.

- `PDO::ERRMODE_EXCEPTION`

  A partir do PHP 8.0.0, este é o modo padrão. Além de definir o código de erro, o PDO lançará um PDOException e definirá suas propriedades para refletir o código de erro e o informações de erro. Esta configuração também é útil durante a depuração, pois irá efetivamente "explodir" o script no ponto do erro, muito rapidamente apontando um dedo para áreas problemáticas potenciais em seu código (lembre-se: as transações são automaticamente revertidas se a exceção faz com que o script termine).

  O modo de exceção também é útil porque você pode estruturar sua manipulação de erros de forma mais clara do que com avisos no estilo tradicional do PHP e com menos código/aninhamento do que em modo silencioso e explicitamente verificando o valor de retorno de cada chamada de banco de dados.

  Veja Exceções para mais informações sobre Exceções em PHP.

O PDO padroniza o uso de strings de código de erro SQLSTATE SQL-92; individualmente Os drivers do PDO são responsáveis por mapear seus códigos nativos para os códigos SQLSTATE apropriados. O método PDO::errorCode() retorna um único código SQLSTATE. Se você precisar de informações mais específicas sobre um erro, o PDO também oferece um método PDO::errorInfo() que retorna um array contendo o código SQLSTATE, o código de erro específico do driver e o driver string de erro específico.

Exemplo #1 Criar uma instância do PDO e definir o modo de erro

    <?php
    $dsn = 'mysql:dbname=testdb;host=127.0.0.1';
    $user = 'dbuser';
    $password = 'dbpass';

    $dbh = new PDO($dsn, $user, $password);
    $dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

    // Isso fará com que o PDO lance uma PDOException (quando a tabela não existe)
    $dbh->query("SELECT wrongcolumn FROM wrongtable");

O exemplo acima produzirá:

    Fatal error: Uncaught PDOException: SQLSTATE[42S02]: Base table or view not found: 1146 Table 'testdb.wrongtable' doesn't exist in /tmp/pdo_test.php:10
    Stack trace:
    #0 /tmp/pdo_test.php(10): PDO->query('SELECT wrongcol...')
    #1 {main}
      thrown in /tmp/pdo_test.php on line 10

> Nota:

> PDO::__construct() sempre lançará uma PDOException se a conexão falhar independentemente de qual `PDO::ATTR_ERRMODE` estiver atualmente definido.

Exemplo #2 Criar uma instância do PDO e definir o modo de erro a partir do construtor

    <?php
    $dsn = 'mysql:dbname=test;host=127.0.0.1';
    $user = 'googleguy';
    $password = 'googleguy';

    $dbh = new PDO($dsn, $user, $password, array(PDO::ATTR_ERRMODE => PDO::ERRMODE_WARNING));

    // Isso fará com que o PDO lance um erro de nível E_WARNING em vez de uma exceção (quando a tabela não existe)
    $dbh->query("SELECT wrongcolumn FROM wrongtable");

O exemplo acima produzirá:

    Warning: PDO::query(): SQLSTATE[42S02]: Base table or view not found: 1146 Table 'test.wrongtable' doesn't exist in
    /tmp/pdo_test.php on line 9

# Objetos Grandes (LOBs)

Em algum momento da aplicação, pode ser necessário armazenar dados "grandes" em seu banco de dados. Grande geralmente significa "cerca de 4kb ou mais", embora alguns bancos de dados possam lidar facilmente com até 32kb antes que os dados se tornem "grandes". Objetos grandes podem ser de natureza textual ou binária. O PDO permite que se trabalhe com esse tipo de dado grande usando o código de tipo `PDO::PARAM_LOB` nas chamadas a PDOStatement::bindParam() ou PDOStatement::bindColumn(). `PDO::PARAM_LOB` diz ao PDO para mapear os dados como um fluxo, para que seja possível manipulá-los usando a API de Fluxos do PHP.

Exemplo #1 Exibindo uma imagem de um banco de dados

Este exemplo vincula o LOB à variável chamada $lob e depois o envia para o navegador usando fpassthru(). Como o LOB é representado como um fluxo, funções como fgets(), fread() e stream_get_contents() podem ser usadas nele.

    <?php
    $db = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2');
    $stmt = $db->prepare("select contenttype, imagedata from images where id=?");
    $stmt->execute(array($_GET['id']));
    $stmt->bindColumn(1, $type, PDO::PARAM_STR, 256);
    $stmt->bindColumn(2, $lob, PDO::PARAM_LOB);
    $stmt->fetch(PDO::FETCH_BOUND);

    header("Content-Type: $type");
    fpassthru($lob);
    ?>

Exemplo #2 Inserindo uma imagem em um banco de dados

Este exemplo abre um arquivo e passa o identificador do arquivo para o PDO para inserir como um LOB. O PDO fará o melhor possível para obter o conteúdo do arquivo até o banco de dados da maneira mais eficiente possível.

    <?php
    $db = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2');
    $stmt = $db->prepare("insert into images (id, contenttype, imagedata) values (?, ?, ?)");
    $id = get_new_id(); // uma função para alocar um novo ID

    // suponha que estamos executando como parte de um formulário de upload de arquivo
    // Mais informações podem ser encontradas na documentação do PHP

    $fp = fopen($_FILES['file']['tmp_name'], 'rb');

    $stmt->bindParam(1, $id);
    $stmt->bindParam(2, $_FILES['file']['type']);
    $stmt->bindParam(3, $fp, PDO::PARAM_LOB);

    $db->beginTransaction();
    $stmt->execute();
    $db->commit();
    ?>

Exemplo #3 Inserindo uma imagem em um banco de dados: Oracle

O Oracle requer uma sintaxe ligeiramente diferente para inserir um lob de um arquivo. Também é essencial que você execute a inserção sob um transação, caso contrário, seu LOB recém-inserido será comprometido com um comprimento zero como parte do commit implícito que ocorre quando a consulta é executada:

    <?php
    $db = new PDO('oci:', 'scott', 'tiger');
    $stmt = $db->prepare("insert into images (id, contenttype, imagedata) " .
    "VALUES (?, ?, EMPTY_BLOB()) RETURNING imagedata INTO ?");
    $id = get_new_id(); // uma função para alocar um novo ID

    // suponha que estamos executando como parte de um formulário de upload de arquivo
    // Mais informações podem ser encontradas na documentação do PHP

    $fp = fopen($_FILES['file']['tmp_name'], 'rb');

    $stmt->bindParam(1, $id);
    $stmt->bindParam(2, $_FILES['file']['type']);
    $stmt->bindParam(3, $fp, PDO::PARAM_LOB);

    $db->beginTransaction();
    $stmt->execute();
    $db->commit();
    ?>

# A classe PDO

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

## Introdução

Representa uma conexão entre o PHP e um servidor de banco de dados.

## Resumo da classe

class PDO {
/* Constantes */
public const int PARAM_NULL;
public const int PARAM_BOOL = 5;
public const int PARAM_INT = 1;
public const int PARAM_STR = 2;
public const int PARAM_LOB = 3;
public const int PARAM_STMT = 4;
public const int PARAM_INPUT_OUTPUT;
public const int PARAM_STR_NATL;
public const int PARAM_STR_CHAR;
public const int PARAM_EVT_ALLOC;
public const int PARAM_EVT_FREE;
public const int PARAM_EVT_EXEC_PRE;
public const int PARAM_EVT_EXEC_POST;
public const int PARAM_EVT_FETCH_PRE;
public const int PARAM_EVT_FETCH_POST;
public const int PARAM_EVT_NORMALIZE;
public const int FETCH_DEFAULT;
public const int FETCH_LAZY;
public const int FETCH_ASSOC;
public const int FETCH_NUM;
public const int FETCH_BOTH;
public const int FETCH_OBJ;
public const int FETCH_BOUND;
public const int FETCH_COLUMN;
public const int FETCH_CLASS;
public const int FETCH_INTO;
public const int FETCH_FUNC;
public const int FETCH_GROUP;
public const int FETCH_UNIQUE;
public const int FETCH_KEY_PAIR;
public const int FETCH_CLASSTYPE;
public const int FETCH_SERIALIZE;
public const int FETCH_PROPS_LATE;
public const int FETCH_NAMED;
public const int ATTR_AUTOCOMMIT;
public const int ATTR_PREFETCH;
public const int ATTR_TIMEOUT;
public const int ATTR_ERRMODE;
public const int ATTR_SERVER_VERSION;
public const int ATTR_CLIENT_VERSION;
public const int ATTR_SERVER_INFO;
public const int ATTR_CONNECTION_STATUS;
public const int ATTR_CASE;
public const int ATTR_CURSOR_NAME;
public const int ATTR_CURSOR;
public const int ATTR_ORACLE_NULLS;
public const int ATTR_PERSISTENT;
public const int ATTR_STATEMENT_CLASS;
public const int ATTR_FETCH_TABLE_NAMES;
public const int ATTR_FETCH_CATALOG_NAMES;
public const int ATTR_DRIVER_NAME;
public const int ATTR_STRINGIFY_FETCHES;
public const int ATTR_MAX_COLUMN_LEN;
public const int ATTR_EMULATE_PREPARES;
public const int ATTR_DEFAULT_FETCH_MODE;
public const int ATTR_DEFAULT_STR_PARAM;
public const int ERRMODE_SILENT;
public const int ERRMODE_WARNING;
public const int ERRMODE_EXCEPTION;
public const int CASE_NATURAL;
public const int CASE_LOWER;
public const int CASE_UPPER;
public const int NULL_NATURAL;
public const int NULL_EMPTY_STRING;
public const int NULL_TO_STRING;
public const string ERR_NONE;
public const int FETCH_ORI_NEXT;
public const int FETCH_ORI_PRIOR;
public const int FETCH_ORI_FIRST;
public const int FETCH_ORI_LAST;
public const int FETCH_ORI_ABS;
public const int FETCH_ORI_REL;
public const int CURSOR_FWDONLY;
public const int CURSOR_SCROLL;
/* Métodos */
public function __construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function beginTransaction(): bool
public function commit(): bool
public static function connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function errorCode(): ?string
public function errorInfo(): array
public function exec(string `$statement`): int|false
public function getAttribute(int `$attribute`): mixed
public static function getAvailableDrivers(): array
public function inTransaction(): bool
public function lastInsertId(?string `$name` = `null`): string|false
public function prepare(string `$query`, array `$options` = []): PDOStatement|false
public function query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function rollBack(): bool
public function setAttribute(int `$attribute`, mixed `$value`): bool
}

## Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | As constantes de classe agora são tipadas.

# PDO::beginTransaction

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::beginTransaction — Inicia uma transação

### Descrição

public function PDO::beginTransaction(): bool

Desativa o modo de envio automático. Enquanto o modo de envio automático estiver desativado, modificações feitas no banco de dados por meio da instância do objeto PDO não serão enviadas até que você finalize a transação chamando PDO::commit(). Chamar PDO::rollBack() reverterá todas as alterações no banco de dados e retornará a conexão para o modo de envio automático.

Alguns bancos de dados, incluindo o MySQL, emitem automaticamente um COMMIT implícito quando uma instrução de linguagem de definição de banco de dados (DDL) como DROP TABLE ou CREATE TABLE é emitida em uma transação. O COMMIT implícito impedirá que você reverta quaisquer outras alterações dentro do limite da transação.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Lança uma PDOException se já houver uma transação iniciada ou se o driver não suportar transações.

> Nota: Uma exceção será lançada mesmo quando o atributo `PDO::ATTR_ERRMODE` não for `PDO::ERRMODE_EXCEPTION`.

### Exemplos

Exemplo #1 Reverter uma transação

O exemplo a seguir inicia uma transação e emite duas instruções que modificam o banco de dados antes de reverter as alterações. No MySQL, no entanto, a instrução DROP TABLE envia automaticamente a transação de modo que nenhuma das alterações na transação é revertida.

    <?php
    /* Inicia uma transação, desligando o envio automático */
    $dbh->beginTransaction();

    /* Altera esquema e dados do banco */
    $sth = $dbh->exec("DROP TABLE fruit");
    $sth = $dbh->exec("UPDATE dessert
        SET name = 'hamburger'");

    /* Reconhece o engano e desfaz o envio das alterações */
    $dbh->rollBack();

    /* A conexão do banco agora está de volta o modo de envio automático */
    ?>

### Veja Também

- PDO::commit() - Envia uma transação
- PDO::rollBack() - Reverte uma transação
- Transações e envio automático

# PDO::commit

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::commit — Envia uma transação

### Descrição

public function PDO::commit(): bool

Envia uma transação, retornando a conexão com o banco de dados para o modo de envio automático até que a próxima chamada a PDO::beginTransaction() inicie uma nova transação.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Lança uma PDOException se não houver transação ativa.

> Nota: Uma exceção será lançada mesmo quando o atributo `PDO::ATTR_ERRMODE` não for `PDO::ERRMODE_EXCEPTION`.

### Exemplos

Exemplo #1 Enviando uma transação básica

    <?php
    /* Inicia uma transação, desligando o envio automático */
    $dbh->beginTransaction();

    /* Insere múltiplos registros na base do tudo-ou-nada */
    $sql = 'INSERT INTO fruit
        (name, colour, calories)
        VALUES (?, ?, ?)';

    $sth = $dbh->prepare($sql);

    foreach ($fruits as $fruit) {
        $sth->execute(array(
            $fruit->name,
            $fruit->colour,
            $fruit->calories,
        ));
    }

    /* Envia as alterações */
    $dbh->commit();

    /* A conexão do banco agora está de volta o modo de envio automático */
    ?>

Exemplo #2 Enviando uma transação DDL

    <?php
    /* Inicia uma transação, desligando o envio automático */
    $dbh->beginTransaction();

    /* Altera esquema do banco */
    $sth = $dbh->exec("DROP TABLE fruit");

    /* Envia as alterações */
    $dbh->commit();

    /* A conexão do banco agora está de volta o modo de envio automático */
    ?>

> Nota: Nem todos os bancos de dados permitirão que as transações operem em instruções DDL: alguns gerarão erros, enquanto outros (incluindo o MySQL) enviarão automaticamente a transação após a primeira instrução DDL ter sido encontrada.

### Veja Também

- PDO::beginTransaction() - Inicia uma transação
- PDO::rollBack() - Reverte uma transação
- Transações e envio automático

# PDO::connect

(PHP 8 >= 8.4.0)

PDO::connect — Conecta a um banco de dados e retorna uma subclasse PDO para drivers que o suportam

### Descrição

public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static

Cria uma instância de uma subclasse PDO para o banco de dados sendo conectado, se existir, caso contrário retorna uma instância genérica de PDO.

### Parâmetros

`dsn`

  O nome da fonte de dados, ou DSN, que contém a informação requerida para conexão ao banco de dados.

  Em geral, um DSN consiste no nome do driver PDO, seguido por dois-pontos, seguido pela sintaxe de conexão específica do driver PDO. Maiores informações estão disponíveis na documentação específica do driver PDO.

  O parâmetro `dsn` suporta três métodos diferentes para especificar os argumentos requeridos para criação de uma conexão de banco de dados:

  Invocação do driver

    `dsn` contém o DSN completo.

  Invocação de URI

    `dsn` consiste em `uri:` seguido por uma URI que define a localização de um arquivo contendo a string DSN. A URI pode especificar um arquivo local ou uma URL remota.

    `uri:file:///caminho/para/arquivodsn`

  Criação de apelido

    `dsn` consiste em um nome (`name`) que é mapeado para `pdo.dsn.`name`` no php.ini definindo a string DSN.

    > Nota:

    > O apelido deve ser definido no php.ini, e não no .htaccess ou no httpd.conf

`username`

  O nome de usuário para a string DSN. Este parâmetro é opcional para alguns drivers PDO.

`password`

  A senha para a srting DSN. Este parâmetro é opcional para alguns drivers PDO.

`options`

  Um array de chave=>valor de opções de conexão específicas do driver.

### Valor Retornado

Retorna uma instância de uma subclasse PDO para o driver PDO correspondente se existir, ou uma instância genérica de PDO.

### Erros/Exceções

Uma PDOException é lançada se a tentativa de conexão ao banco de dados requisitado falhar, independente de qual `PDO::ATTR_ERRMODE` estiver definido.

### Veja Também

- Pdo\Dblib
- Pdo\Firebird
- Pdo\Mysql
- Pdo\Odbc
- Pdo\Pgsql
- Pdo\Sqlite
- PDO::__construct() - Cria uma instância PDO representando uma conexão a um banco de dados

# PDO::__construct

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::__construct — Cria uma instância PDO representando uma conexão a um banco de dados

### Descrição

public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)

Cria uma instância PDO para representar uma conexão ao banco de dados requisitado.

### Parâmetros

`dsn`

  O nome da fonte de dados, ou DSN, que contém a informação requerida para conexão ao banco de dados.

  Em geral, um DSN consiste no nome do driver PDO, seguido por dois-pontos, seguido pela sintaxe de conexão específica do driver PDO. Maiores informações estão disponíveis na documentação específica do driver PDO.

  O parâmetro `dsn` suporta três métodos diferentes para especificar os argumentos requeridos para criação de uma conexão de banco de dados:

  Invocação do driver

    `dsn` contém o DSN completo.

  Invocação de URI

    `dsn` consiste em `uri:` seguido por uma URI que define a localização de um arquivo contendo a string DSN. A URI pode especificar um arquivo local ou uma URL remota.

    `uri:file:///caminho/para/arquivodsn`

  Criação de apelido

    `dsn` consiste em um nome (`name`) que é mapeado para `pdo.dsn.`name`` no php.ini definindo a string DSN.

    > Nota:

    > O apelido deve ser definido no php.ini, e não no .htaccess ou no httpd.conf

`username`

  O nome de usuário para a string DSN. Este parâmetro é opcional para alguns drivers PDO.

`password`

  A senha para a srting DSN. Este parâmetro é opcional para alguns drivers PDO.

`options`

  Um array de chave=>valor de opções de conexão específicas do driver.

### Erros/Exceções

Uma PDOException é lançada se a tentativa de conexão ao banco de dados requisitado falhar, independente de qual `PDO::ATTR_ERRMODE` estiver definido.

### Exemplos

Exemplo #1 Cria uma instância PDO através de invocação de driver

    <?php

    $dsn = 'mysql:dbname=testdb;host=127.0.0.1';
    $user = 'dbuser';
    $password = 'dbpass';

    $dbh = new PDO($dsn, $user, $password);

    ?>

Exemplo #2 Cria uma instância PDO através de invocação de URI

O exemplo a seguir assume que o arquivo /usr/local/dbconnect existe com permissões de leitura pelo PHP. O arquivo contém o DSN PDO para conexão a um banco de dados DB2 através do driver PDO_ODBC:

    odbc:DSN=SAMPLE;UID=john;PWD=mypass

O script PHP pode então criar uma conexão ao banco de dados simplesmente passando o parâmetro `uri:` e apontando para a URI do arquivo:

    <?php

    $dsn = 'uri:file:///usr/local/dbconnect';
    $user = '';
    $password = '';

    $dbh = new PDO($dsn, $user, $password);

    ?>

Exemplo #3 Cria uma instância PDO usando um apelido

O exemplo a seguir assume que o php.ini contém a seguinte entrada para habilitar uma conexão ao banco de dados MySQL usando somente o apelido `mydb`:

    [PDO]
    pdo.dsn.mydb="mysql:dbname=testdb;host=localhost"

    <?php

    $dsn = 'mydb';
    $user = '';
    $password = '';

    $dbh = new PDO($dsn, $user, $password);

    ?>

# PDO::errorCode

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::errorCode — Busca o SQLSTATE associado com a última operação no identificador do banco de dados

### Descrição

public function PDO::errorCode(): ?string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um SQLSTATE, um identificador alfanumérico de cinco caracteres definido no padrão ANSI SQL-92. Resumidamente, um SQLSTATE consiste em um valor de classe de dois caracteres seguido por um valor de subclasse de três caracteres. Um valor de classe de '01' indica um alerta e é acompanhado por um código de retorno de SQL_SUCCESS_WITH_INFO. Valores de classe diferentes de '01', exceto pela classe 'IM', indicam um erro. A classe 'IM' é específica para alertas e erros que derivam da implementação do próprio PDO (ou talvez do ODBC, se estiver em uso). O valor de subclasse '000' em qualquer classe indica que não há subclasse para aquele SQLSTATE.

PDO::errorCode() somente busca códigos de erro para operações realizadas diretamente no identificador do banco de dados. Se for criado um objeto PDOStatement através de PDO::prepare() ou PDO::query() e for invocado um erro no identificador da instrução, PDO::errorCode() não refletirá esse erro. Deve-se chamar PDOStatement::errorCode() para retornar o código de erro para uma operação realizada em um identificador de instrução em particular.

Retorna `null` se nenhuma operação foi executada no identificador do banco de dados.

### Exemplos

Exemplo #1 Buscando um código SQLSTATE

    <?php
    /* Provoca um erro -- a tabela OSSOS não existe */
    $dbh->exec("INSERT INTO ossos(cranio) VALUES ('lucy')");

    echo "\nPDO::errorCode(): ", $dbh->errorCode();
    ?>

O exemplo acima produzirá:

    PDO::errorCode(): 42S02

### Veja Também

- PDO::errorInfo() - Busca informação de erro estendida associada com a última operação no identificador do banco de dados
- PDOStatement::errorCode() - Busca o SQLSTATE associado com a última operação no objeto da instrução
- PDOStatement::errorInfo() - Busca informação de erro estendida associada com a última operação no identificador da instrução

# PDO::errorInfo

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::errorInfo — Busca informação de erro estendida associada com a última operação no identificador do banco de dados

### Descrição

public function PDO::errorInfo(): array

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

PDO::errorInfo() retorna um array de informações de erro sobre a última operação realizada por este identificador de banco de dados. O array consiste em pelo menos os campos a seguir:

Elemento | Informação
--- | ---
0 | Código de erro SQLSTATE (um identificador alfanumérico de cinco caracteres definido no padrão ANSI SQL).
1 | Código de erro específico do driver.
2 | Mensagem de erro específica do driver.

> Nota:

> Se o código de erro SQLSTATE não estiver definido ou se não houver erro específico do driver, os elementos após o elemento 0 serão definidos para `null`.

PDO::errorInfo() somente busca informação de erro para operações realizadas diretamente no identificador do banco de dados. Se for criado um objeto PDOStatement através de PDO::prepare() ou PDO::query() e for invocado um erro no identificador da instrução, PDO::errorInfo() não refletirá o erro do identificador da instrução. Deve-se chamar PDOStatement::errorInfo() para retornar a informação de erro para uma operação realizada em um identificador de instrução em particular.

### Exemplos

Exemplo #1 Mostrando campos de errorInfo() para uma conexão PDO_ODBC a um banco de dados DB2

    <?php
    /* Provoca um erro -- sintaxe SQL incorreta */
    $stmt = $dbh->prepare('bogus sql');
    if (!$stmt) {
        echo "\nPDO::errorInfo():\n";
        print_r($dbh->errorInfo());
    }
    ?>

O exemplo acima produzirá:

    PDO::errorInfo():
    Array
    (
        [0] => HY000
        [1] => 1
        [2] => near "bogus": syntax error
    )

### Veja Também

- PDO::errorCode() - Busca o SQLSTATE associado com a última operação no identificador do banco de dados
- PDOStatement::errorCode() - Busca o SQLSTATE associado com a última operação no objeto da instrução
- PDOStatement::errorInfo() - Busca informação de erro estendida associada com a última operação no identificador da instrução

# PDO::exec

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::exec — Executa uma instrução SQL e retorna o número de linhas afetadas

### Descrição

public function PDO::exec(string `$statement`): int|false

PDO::exec() executa uma instrução SQL em uma única chamada de função, retornando o número de linhas afetadas pela instrução.

PDO::exec() não retorna resultados de uma instrução SELECT. Para uma instrução SELECT que você só precisa emitir uma vez durante seu programa, considere a emissão de PDO::query(). Para uma instrução que você precisa emitir várias vezes, prepare um objeto PDOStatement com PDO::prepare() e emita a instrução com PDOStatement::execute().

### Parâmetros

`statement`

  A instrução SQL para preparar e executar.

  Os dados dentro da consulta devem ser adequadamente escapados.

### Valor Retornado

PDO::exec() retorna o número de linhas que foram modificadas ou excluídas pela instrução SQL que você emitiu. Se nenhuma linha for afetada, PDO::exec() retorna `0`.

Aviso

Esta função pode retornar o valor booleano `false`, mas também pode retornar um valor não booleano que pode ser avaliado como `false`. Leia a seção sobre Booleanos para mais informações. Use o operador === para testar o valor retornado por esta função.

O exemplo a seguir depende incorretamente do valor de retorno de PDO::exec(), em que uma instrução que afetou 0 linhas resulta em uma chamada para die():

    <?php
    $db->exec() or die(print_r($db->errorInfo(), true)); // incorreto
    ?>

### Erros/Exceções

Emite um erro de nível `E_WARNING` se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_WARNING`.

Lança uma exceção PDOException se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_EXCEPTION`.

### Exemplos

Exemplo #1 Emitindo uma instrução DELETE

Conte o número de linhas excluídas por uma instrução DELETE sem cláusula WHERE.

    <?php
    $dbh = new PDO('odbc:sample', 'db2inst1', 'ibmdb2');

    /* Apaga todas as linhas da tabela FRUIT */
    $count = $dbh->exec("DELETE FROM fruit");

    /* Retorna o número de linhas apagadas */
    print "Apagada(s) $count linha(s).\n";
    ?>

O exemplo acima produzirá:

    Apagada(s) 1 linha(s).

### Veja Também

- PDO::prepare() - Prepara uma instrução para execução e retorna um objeto de instrução
- PDO::query() - Prepara e executa uma instrução SQL sem marcadores
- PDOStatement::execute() - Executa ums instrução preparada

# PDO::getAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDO::getAttribute — Recuperar um atributo da conexão com o banco de dados

### Descrição

public function PDO::getAttribute(int `$attribute`): mixed

Esta função retorna o valor de um atributo da conexão com o banco de dados. Para recuperar atributos de PDOStatement consulte PDOStatement::getAttribute().

Note que algumas combinações de banco de dados e drivers podem não suportar todos os atributos da conexão com o banco de dados.

### Parâmetros

`attribute`

  Uma das constantes `PDO::ATTR_*`. Os atributos genéricos que se aplicam a conexões com o banco de dados são os seguintes:

  - `PDO::ATTR_AUTOCOMMIT`
  - `PDO::ATTR_CASE`
  - `PDO::ATTR_CLIENT_VERSION`
  - `PDO::ATTR_CONNECTION_STATUS`
  - `PDO::ATTR_DRIVER_NAME`
  - `PDO::ATTR_ERRMODE`
  - `PDO::ATTR_ORACLE_NULLS`
  - `PDO::ATTR_PERSISTENT`
  - `PDO::ATTR_PREFETCH`
  - `PDO::ATTR_SERVER_INFO`
  - `PDO::ATTR_SERVER_VERSION`
  - `PDO::ATTR_TIMEOUT`
  Alguns drivers podem fazer uso de atributos específicos adicionais. Note que atributos específicos de drivers não devem ser usados com outros drivers.

### Valor Retornado

Uma chamada com sucesso retornará o valor do atributo PDO solicitado. Uma chamada sem sucesso retornará `null`.

### Erros/Exceções

PDO::getAttribute() pode lançar uma PDOException quando o driver subjacente não suportar o `attribute` requerido.

### Exemplos

Exemplo #1 Recuperando atributos de uma conexão com o banco de dados

    <?php
    $conn = new PDO('odbc:sample', 'db2inst1', 'ibmdb2');
    $attributes = array(
        "AUTOCOMMIT", "ERRMODE", "CASE", "CLIENT_VERSION", "CONNECTION_STATUS",
        "ORACLE_NULLS", "PERSISTENT", "PREFETCH", "SERVER_INFO", "SERVER_VERSION",
        "TIMEOUT"
    );

    foreach ($attributes as $val) {
        echo "PDO::ATTR_$val: ";
        echo $conn->getAttribute(constant("PDO::ATTR_$val")) . "\n";
    }
    ?>

### Veja Também

- PDO::setAttribute() - Define um atributo
- PDOStatement::getAttribute() - Recupera um atributo da instrução
- PDOStatement::setAttribute() - Define um atributo na instrução

# PDO::getAvailableDrivers

# pdo_drivers

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.3)

PDO::getAvailableDrivers -- pdo_drivers — Retorna um array com os drivers PDO disponíveis

### Descrição

public static function PDO::getAvailableDrivers(): array
function pdo_drivers(): array

Esta função retorna todos os drivers PDO disponíveis que podem ser usados no parâmetro `DSN` de PDO::__construct().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

PDO::getAvailableDrivers() retorna um array com os drivers PDO disponíveis. Se nenhum driver estiver disponível então o retorno será um array vazio.

### Exemplos

Exemplo #1 Exemplo de PDO::getAvailableDrivers()

    <?php
    print_r(PDO::getAvailableDrivers());
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => mysql
        [1] => sqlite
    )

# PDO::inTransaction

(PHP 5 >= 5.3.3, Bundled pdo_pgsql, PHP 7, PHP 8)

PDO::inTransaction — Verifica se está dentro de uma transação

### Descrição

public function PDO::inTransaction(): bool

Verifica se uma transação está atualmente ativa no driver. Este método funciona somente para drivers de banco de dados que suportam transações.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se uma transação estiver ativa, e `false` caso contrário.

# PDO::lastInsertId

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::lastInsertId — Retorna o ID da última linha ou valor de sequência inserido

### Descrição

public function PDO::lastInsertId(?string `$name` = `null`): string|false

Retorna o ID da última linha inserida, ou o último valor de um objeto de sequência, dependendo do driver subjacente. Por exemplo, PDO_PGSQL permite que o nome de qualquer objeto de sequência seja especificado para o parâmetro `name`.

> Nota:

> Este método pode não retornar um resultado significativo ou consistente em diferentes drivers PDO, pois o banco de dados subjacente pode nem mesmo suportar a noção de campos ou sequências auto-incrementais.

### Parâmetros

`name`

  Nome do objeto de sequência do qual o ID deve ser retornado.

### Valor Retornado

Se um nome de sequência não foi especificado para o parâmetro `name`, PDO::lastInsertId() retornará uma string representando o ID da última linha que foi inserida no banco de dados.

Se um nome de sequência foi especificado para o parâmetro `name`, PDO::lastInsertId() retornará uma string representando o último valor recuperado do objeto de sequência especificado.

Se o driver PDO não suportar este recurso, PDO::lastInsertId() dispara um SQLSTATE `IM001`.

### Erros/Exceções

Emite um erro de nível `E_WARNING` se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_WARNING`.

Lança uma exceção PDOException se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_EXCEPTION`.

# PDO::prepare

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PHP 8,PECL pdo >= 0.1.0)

PDO::prepare — Prepara uma instrução para execução e retorna um objeto de instrução

### Descrição

public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false

Prepara uma instrução SQL para ser executada pelo método PDOStatement::execute(). O modelo de instrução pode conter zero ou mais marcadores de parâmetros nomeados (:name) ou pontos de interrogação (?) para os quais os valores reais serão substituídos quando a instrução for executada. Os marcadores de parâmetros nomeados e de ponto de interrogação não podem ser usados ​​no mesmo modelo de instrução; apenas um ou outro estilo de parâmetro. Use esses parâmetros para vincular qualquer entrada do usuário, não inclua a entrada do usuário diretamente na consulta.

Deve-se incluir um marcador de parâmetro exclusivo para cada valor que se deseja passar para a instrução ao chamar PDOStatement::execute(). Um marcador de parâmetro nomeado com o mesmo nome não pode ser usado mais de uma vez em uma instrução preparada, a menos que o modo de emulação esteja ativado.

> Nota:

> Os marcadores de parâmetro podem representar apenas um literal de dados completo. Nem parte do literal, nem palavra-chave, nem identificador, nem qualquer parte arbitrária da consulta podem ser vinculadas usando parâmetros. Por exemplo, não se pode vincular múltiplos valores a um único parâmetro na cláusula IN() de uma instrução SQL.

Chamar PDO::prepare() e PDOStatement::execute() para instruções que serão emitidas diversas vezes com valores de parâmetros diferentes otimiza o desempenho da aplicação, permitindo que o driver negocie cache no lado do cliente e/ou do servidor do plano de consulta e metainformações. Além disso, chamar PDO::prepare() e PDOStatement::execute() ajuda a evitar ataques de injeção de SQL, eliminando a necessidade de inserir aspas e escapar manualmente dos parâmetros.

O PDO irá emular instruções preparadas/parâmetros vinculados para drivers que não os suportam nativamente, e também pode reescrever marcadores de parâmetros nomeados ou no estilo ponto de interrogação para algo mais apropriado, se o driver suportar um estilo, mas não o outro.

> Nota: O analisador usado para instruções preparadas emuladas e para reescrever parâmetros nomeados ou no estilo de ponto de interrogação suporta escapes de barra invertida não padrão para aspas simples e duplas. Isso significa que aspas de término imediatamente precedidas por uma barra invertida não são reconhecidas como tal, o que pode resultar na detecção incorreta de parâmetros, fazendo com que a instrução preparada falhe quando for executada. Uma solução alternativa é não usar preparações emuladas para essas consultas SQL e evitar a reescrita de parâmetros usando um estilo de parâmetro que seja suportado nativamente pelo driver.

A partir do PHP 7.4.0, os pontos de interrogação podem ser escapados duplicando-os. Isso significa que a string `??` será traduzida para `?` ao enviar a consulta ao banco de dados.

### Parâmetros

`query`

  Este deve ser um modelo de instrução SQL válido para o servidor de banco de dados de destino.

`options`

  Este array contém um ou mais pares chave=>valor para definir valores de atributos para o objeto PDOStatement que esse método retorna. Normalmente usa-se isso para definir o valor `PDO::ATTR_CURSOR` como `PDO::CURSOR_SCROLL` para solicitar um cursor rolável. Alguns drivers têm opções específicas que podem ser definidas no momento da preparação.

### Valor Retornado

Se o servidor de banco de dados preparar a instrução com sucesso, PDO::prepare() retornará um objeto PDOStatement. Se o servidor de banco de dados não conseguir preparar a instrução com sucesso, PDO::prepare() retornará `false` ou emitirá uma exceção PDOException (dependendo do tratamento de erros).

> Nota:

> Instruções preparadas emuladas não se comunicam com o servidor de banco de dados, portanto PDO::prepare() não verifica a instrução.

### Erros/Exceções

Emite um erro de nível `E_WARNING` se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_WARNING`.

Lança uma exceção PDOException se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_EXCEPTION`.

### Exemplos

Exemplo #1 Modelo de instrução SQL com parâmetros nomeados

    <?php
    /* Executa uma instrução preparada passando um array de valores */
    $sql = 'SELECT name, colour, calories
        FROM fruit
        WHERE calories < :calories AND colour = :colour';
    $sth = $dbh->prepare($sql, [PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY]);
    $sth->execute(['calories' => 150, 'colour' => 'red']);
    $red = $sth->fetchAll();
    /* Chaves de arrays podem ser prefizadas com dois-pontos ":" também (opcional) */
    $sth->execute([':calories' => 175, ':colour' => 'yellow']);
    $yellow = $sth->fetchAll();
    ?>

Exemplo #2 Modelo de instrução SQL com parâmetros de ponto de interrogação

    <?php
    /* Executa uma instrução preparada passando um array de valores */
    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < ? AND colour = ?');
    $sth->execute([150, 'red']);
    $red = $sth->fetchAll();
    $sth->execute([175, 'yellow']);
    $yellow = $sth->fetchAll();
    ?>

Exemplo #3 Modelo de instrução SQL com ponto de interrogação escapado

    <?php
    /* nota: isso só é válido em bancos de dados PostgreSQL */
    $sth = $dbh->prepare('SELECT * FROM issues WHERE tag::jsonb ?? ?');
    $sth->execute(['feature']);
    $featureIssues = $sth->fetchAll();
    $sth->execute(['performance']);
    $performanceIssues = $sth->fetchAll();
    ?>

### Veja Também

- PDO::exec() - Executa uma instrução SQL e retorna o número de linhas afetadas
- PDO::query() - Prepara e executa uma instrução SQL sem marcadores
- PDOStatement::execute() - Executa ums instrução preparada

# PDO::query

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDO::query — Prepara e executa uma instrução SQL sem marcadores

### Descrição

public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false

PDO::query() prepara e executa uma instrução SQL em uma única chamada de função, retornando a instrução como um objeto PDOStatement.

Para uma consulta que precisa ser emitida diversas vezes, obtém-se melhor desempenho se for preparado um objeto PDOStatement usando PDO::prepare() e emitida a instrução com múltiplas chamadas a PDOStatement::execute().

Se não forem buscados todos os dados em um conjunto de resultados antes de emitir a próxima chamada a PDO::query(), a chamada poderá falhar. Deve-se chamar PDOStatement::closeCursor() para liberar os recursos do banco de dados associados ao objeto PDOStatement antes de se emitir a próxima chamada a PDO::query().

> Nota:

> Se a `query` contiver marcadores, a instrução deverá ser preparada e executada separadamente usando os métodos PDO::prepare() e PDOStatement::execute().

### Parâmetros

`query`

  A instrução SQL a ser preparada e executada.

  Se o SQL contiver marcadores, PDO::prepare() e PDOStatement::execute() deverão ser usados. Alternativamente, o SQL pode ser preparado manualmente antes de chamar PDO::query(), com os dados formatados corretamente usando PDO::quote() se o driver suportar.

`fetchMode`

  O modo de busca padrão para o PDOStatement retornado. Deve ser uma das constantes `PDO::FETCH_*`.

  Se este argumento for passado para a função, os argumentos restantes serão tratados como se PDOStatement::setFetchMode() tivesse sido chamado no objeto de instrução resultante. Os argumentos subsequentes variam dependendo do modo de busca selecionado.

### Valor Retornado

Retorna um objeto PDOStatement ou `false` em caso de falha.

### Erros/Exceções

Emite um erro de nível `E_WARNING` se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_WARNING`.

Lança uma exceção PDOException se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_EXCEPTION`.

### Exemplos

Exemplo #1 SQL sem marcadores pode ser executado usando PDO::query()

    <?php
    $sql = 'SELECT name, color, calories FROM fruit ORDER BY name';
    foreach ($conn->query($sql) as $row) {
        print $row['name'] . "\t";
        print $row['color'] . "\t";
        print $row['calories'] . "\n";
    }
    ?>

O exemplo acima produzirá:

    apple   red     150
    banana  yellow  250
    kiwi    brown   75
    lemon   yellow  25
    orange  orange  300
    pear    green   150
    watermelon      pink    90

### Veja Também

- PDO::exec() - Executa uma instrução SQL e retorna o número de linhas afetadas
- PDO::prepare() - Prepara uma instrução para execução e retorna um objeto de instrução
- PDOStatement::execute() - Executa ums instrução preparada

# PDO::quote

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.1)

PDO::quote — Inclui aspas em uma string para uso em uma consulta

### Descrição

public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false

PDO::quote() coloca aspas na string de entrada e escapa caracteres especiais dentro da string de entrada, usando um estilo de aspas (ex.: simples ou duplas) apropriado ao driver subjacente.

Se esta função estiver sendo usada para construir instruções SQL, é fortemente recomendado usar PDO::prepare() para preparar instruções SQL com parâmetros vinculados em vez de usar PDO::quote() para interpolar a entrada do usuário em uma instrução SQL. Instruções preparadas com parâmetros vinculados não são apenas mais portáveis, mais convenientes e imunes à injeção de SQL, mas geralmente são muito mais rápidas de executar do que consultas interpoladas, já que tanto o servidor quanto o cliente podem armazenar em cache uma forma compilada da consulta.

Nem todos os drivers PDO implementam esse método (principalmente PDO_ODBC). Considere usar instruções preparadas.

Cuidado

# Segurança: o conjunto de caracteres padrão

O conjunto de caracteres deve ser definido no nível do servidor ou na própria conexão do banco de dados (dependendo do driver) para afetar o PDO::quote(). Consulte a documentação específica do driver para obter mais informações.

### Parâmetros

`string`

  A string que será envolvida por aspas.

`type`

  Fornece uma dica sobre o tipo de dados para drivers que possuem estilos de cotação alternativos. Por exemplo, `PDO_PARAM_LOB` dirá ao driver para escapar dados binários.

### Valor Retornado

Retorna uma string entre aspas que é teoricamente segura para passar em uma instrução SQL. Retorna `false` se o driver não suportar inserção de aspas dessa forma.

### Exemplos

Exemplo #1 Inserindo aspas em uma string normal

    <?php
    $conn = new PDO('sqlite:/home/lynn/music.sql3');

    /* String simples */
    $string = 'Teste';
    print "String sem aspas: $string\n";
    print "String com aspas: " . $conn->quote($string) . "\n";
    ?>

O exemplo acima produzirá:

    String sem aspas: Teste
    String com aspas: 'Teste'

Exemplo #2 Inserindo aspas em uma string perigosa

    <?php
    $conn = new PDO('sqlite:/home/lynn/music.sql3');

    /* String perigosa */
    $string = 'String \' perversa';
    print "String sem aspas: $string\n";
    print "String com aspas:" . $conn->quote($string) . "\n";
    ?>

O exemplo acima produzirá:

    String sem aspas: String ' perversa
    String com aspas: 'String '' perversa'

Exemplo #3 Inserindo aspas em uma string complexa

    <?php
    $conn = new PDO('sqlite:/home/lynn/music.sql3');

    /* String complexa */
    $string = "St'ri''ng \"com'\"plexa";
    print "String sem aspas: $string\n";
    print "String com aspas: " . $conn->quote($string) . "\n";
    ?>

O exemplo acima produzirá:

    String sem aspas: St'ri''ng "com'"plexa
    String com aspas: 'St''ri''''ng "com''"plexa'

### Veja Também

- PDO::prepare() - Prepara uma instrução para execução e retorna um objeto de instrução
- PDOStatement::execute() - Executa ums instrução preparada

# PDO::rollBack

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::rollBack — Reverte uma transação

### Descrição

public function PDO::rollBack(): bool

Reverte a transação atual, iniciada por PDO::beginTransaction().

Se o banco de dados foi definido para o modo de confirmação automática, esta função restaurará o modo de confirmação automática após a reversão da transação.

Alguns bancos de dados, incluindo MySQL, emitem automaticamente um COMMIT implícito quando uma instrução DDL (linguagem de definição de banco de dados), como DROP TABLE ou CREATE TABLE, é emitida em uma transação. O COMMIT implícito impedirá que quaisquer outras alterações sejam revertidas dentro do limite da transação.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Lança uma exceção PDOException se não houver transação ativa.

> Nota: Uma exceção será lançada mesmo quando o atributo `PDO::ATTR_ERRMODE` não for `PDO::ERRMODE_EXCEPTION`.

### Exemplos

Exemplo #1 Revertendo uma transação

O exemplo a seguir inicia uma transação e emite duas instruções que modificam o banco de dados antes de reverter as alterações. No MySQL, entretanto, a instrução DROP TABLE confirma automaticamente a transação de forma que nenhuma das alterações na transação é revertida.

    <?php
    /* Inicia uma transação, desligando a auto-confirmação */
    $dbh->beginTransaction();

    /* Altera esquema e dados do bando */
    $sth = $dbh->exec("DROP TABLE fruta");
    $sth = $dbh->exec("UPDATE sobremesa
        SET nome = 'hamburger'");

    /* Reconhece o erro e reverte as alterações */
    $dbh->rollBack();

    /* A conexão do banco agora está de volta no modo de auto-confirmação */
    ?>

### Veja Também

- PDO::beginTransaction() - Inicia uma transação
- PDO::commit() - Envia uma transação
- Transações e auto-confirmação

# PDO::setAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::setAttribute — Define um atributo

### Descrição

public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool

Define um atributo no identificador do banco de dados. Alguns atributos genéricos disponíveis estão listados abaixo; alguns drivers podem fazer uso de atributos adicionais específicos do driver. Observe que os atributos específicos do driver não devem ser usados ​​com outros drivers.

`PDO::ATTR_CASE`

  Força os nomes das colunas para uma combinação específica de maiúsculas/minúsculas. Pode ser um dos seguintes valores:

  `PDO::CASE_LOWER`
    Força os nomes das colunas para minúsculas.
  `PDO::CASE_NATURAL`
    Deixa os nomes das colunas como retornados pelo driver do banco de dados.
  `PDO::CASE_UPPER`
    Força os nomes das colunas para maiúsculas.
`PDO::ATTR_ERRMODE`

  Modo de relatório de erros do PDO. Pode ser um dos seguintes valores:

  `PDO::ERRMODE_SILENT`
    Define somente códigos de erro.
  `PDO::ERRMODE_WARNING`
    Emite diagnósticos `E_WARNING`.
  `PDO::ERRMODE_EXCEPTION`
    Lança exceções PDOException.
`PDO::ATTR_ORACLE_NULLS`

  > Nota: Este atributo está disponível em todos os drivers, não somente no Oracle.

  Determina se e como strings `null` e vazias devem ser convertidas. Pode ser um dos seguintes valores:

  `PDO::NULL_NATURAL`
    Nenhuma conversão acontece.
  `PDO::NULL_EMPTY_STRING`
    Strings vazias são convertidas para `null`.
  `PDO::NULL_TO_STRING`
    `null` é convertido para uma string vazia.
`PDO::ATTR_STRINGIFY_FETCHES`

  Controla se os valores buscados (exceto `null`) são convertidos para strings. Aceita um valor do tipo bool: `true` para habilitar e `false` para desabilitar (padrão). Valores `null` permanecem inalterados a menos que `PDO::ATTR_ORACLE_NULLS` esteja definida para `PDO::NULL_TO_STRING`.

`PDO::ATTR_STATEMENT_CLASS`

  Defina a classe de instrução fornecida pelo usuário derivada de PDOStatement. Requer `array(string classname, array(mixed constructor_args))`.

  Cuidado

  Não pode ser usado com instâncias persistentes de PDO.

`PDO::ATTR_TIMEOUT`

  Especifica a duração do tempo limite em segundos. Recebe um valor do tipo int.

  > Nota:

  > Nem todos os drivers suportam esta opção e seu significado pode variar de driver para driver. Por exemplo, o SQLite irá esperar até esse valor de tempo antes de desistir de obter uma trava para escrita, mas outros drivers podem interpretar isso como intervalo de tempo limite de conexão ou de leitura.

`PDO::ATTR_AUTOCOMMIT`

  > Nota: Disponível apenas para drivers OCI, Firebird e MySQL.

  Define se cada instrução deve ser confirmada automaticamente. Recebe um valor do tipo bool: `true` para habilitar e `false` para desabilitar. Por padrão, `true`.

`PDO::ATTR_EMULATE_PREPARES`

  > Nota: Disponível apenas para drivers OCI, Firebird e MySQL.

  Define se a emulação de instruções preparadas será habilitada ou desabilitada. Alguns drivers não oferecem suporte nativo a instruções preparadas ou têm suporte limitado para elas. Se definido como `true` O PDO sempre emulará instruções preparadas, caso contrário, o PDO tentará usar instruções preparadas nativas. Caso o driver não consiga preparar com êxito a instrução atual, o PDO sempre voltará a emular a instrução preparada.

`PDO::MYSQL_ATTR_USE_BUFFERED_QUERY`

  > Nota: Disponível apenas para o driver MySQL.

  Define se consultas com buffer devem ser usadas. Recebe um valor do tipo bool: `true` para habilitar e `false` para desabilitar. Por padrão, `true`.

`PDO::ATTR_DEFAULT_FETCH_MODE`

  Define o modo de busca padrão. Uma descrição dos modos e de como utilizá-los está disponível na documentação do método PDOStatement::fetch().

### Parâmetros

`attribute`

  O atributo a modificar.

`value`

  O valor para o qual o `attribute` será definido, pode requerer um tipo específico dependendo do atributo.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- PDO::getAttribute() - Recuperar um atributo da conexão com o banco de dados
- PDOStatement::getAttribute() - Recupera um atributo da instrução
- PDOStatement::setAttribute() - Define um atributo na instrução

## Índice

- PDO::beginTransaction — Inicia uma transação
- PDO::commit — Envia uma transação
- PDO::connect — Conecta a um banco de dados e retorna uma subclasse PDO para drivers que o suportam
- PDO::__construct — Cria uma instância PDO representando uma conexão a um banco de dados
- PDO::errorCode — Busca o SQLSTATE associado com a última operação no identificador do banco de dados
- PDO::errorInfo — Busca informação de erro estendida associada com a última operação no identificador do banco de dados
- PDO::exec — Executa uma instrução SQL e retorna o número de linhas afetadas
- PDO::getAttribute — Recuperar um atributo da conexão com o banco de dados
- PDO::getAvailableDrivers — Retorna um array com os drivers PDO disponíveis
- PDO::inTransaction — Verifica se está dentro de uma transação
- PDO::lastInsertId — Retorna o ID da última linha ou valor de sequência inserido
- PDO::prepare — Prepara uma instrução para execução e retorna um objeto de instrução
- PDO::query — Prepara e executa uma instrução SQL sem marcadores
- PDO::quote — Inclui aspas em uma string para uso em uma consulta
- PDO::rollBack — Reverte uma transação
- PDO::setAttribute — Define um atributo

# A classe PDOStatement

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.0)

## Introdução

Representa uma instrução preparada e, após a execução da instrução, um conjunto de resultados associado.

## Resumo da classe

class PDOStatement implements IteratorAggregate {
/* Propriedades */
public string $queryString;
/* Métodos */
public function bindColumn(
string|int `$column`,
mixed `&$var`,
int `$type` = `PDO::PARAM_STR`,
int `$maxLength` = 0,
mixed `$driverOptions` = `null`
): bool
public function bindParam(
string|int `$param`,
mixed `&$var`,
int `$type` = `PDO::PARAM_STR`,
int `$maxLength` = 0,
mixed `$driverOptions` = `null`
): bool
public function bindValue(string|int `$param`, mixed `$value`, int `$type` = `PDO::PARAM_STR`): bool
public function closeCursor(): bool
public function columnCount(): int
public function debugDumpParams(): ?bool
public function errorCode(): ?string
public function errorInfo(): array
public function execute(?array `$params` = `null`): bool
public function fetch(int `$mode` = `PDO::FETCH_DEFAULT`, int `$cursorOrientation` = `PDO::FETCH_ORI_NEXT`, int `$cursorOffset` = 0): mixed
public function fetchAll(int `$mode` = PDO::FETCH_DEFAULT): array
public function fetchAll(int `$mode` = PDO::FETCH_COLUMN, int `$column`): array
public function fetchAll(int `$mode` = PDO::FETCH_CLASS, string `$class`, ?array `$constructorArgs`): array
public function fetchAll(int `$mode` = PDO::FETCH_FUNC, callable `$callback`): array
public function fetchColumn(int `$column` = 0): mixed
public function fetchObject(?string `$class` = "stdClass", array `$constructorArgs` = []): object|false
public function getAttribute(int `$name`): mixed
public function getColumnMeta(int `$column`): array|false
public function getIterator(): Iterator
public function nextRowset(): bool
public function rowCount(): int
public function setAttribute(int `$attribute`, mixed `$value`): bool
public function setFetchMode(int `$mode`): true
public function setFetchMode(int `$mode` = PDO::FETCH_COLUMN, int `$colno`): true
public function setFetchMode(int `$mode` = PDO::FETCH_CLASS, string `$class`, ?array `$constructorArgs` = `null`): true
public function setFetchMode(int `$mode` = PDO::FETCH_INTO, object `$object`): true
}

## Propriedades

queryString

  String de consulta usada.

## Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | PDOStatement agora implementa IteratorAggregate em vez de Traversable.

# PDOStatement::bindColumn

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::bindColumn — Vincula uma coluna a uma variável PHP

### Descrição

public function PDOStatement::bindColumn(
string|int `$column`,
mixed `&$var`,
int `$type` = `PDO::PARAM_STR`,
int `$maxLength` = 0,
mixed `$driverOptions` = `null`
): bool

PDOStatement::bindColumn() faz com que uma variável em particular seja vinculada a uma coluna informada, no conjunto de resultados de uma consulta. Cada chamada a PDOStatement::fetch() ou PDOStatement::fetchAll() irá atualizar todas as variáveis que estejam vinculadas a colunas.

> Nota:

> Como as informações sobre a coluna não estão sempre disponíveis ao PDO até que a instrução seja executada, aplicações portáteis devem chamar esta função após PDOStatement::execute().

> Entretanto, para que seja possível vincular uma coluna LOB como um fluxo ao usar o driver PgSQL, aplicações devem chamar este método antes de chamada a PDOStatement::execute(), caso contrário o OID de objeto grande será retornado como um inteiro.

### Parâmetros

`column`

  Número da coluna (índices iniciando em 1) ou nome da coluna no conjunto de resultados. Se o nome da coluna estiver sendo usado, o nome deve ter as maiúsculas/minúsculas correspondentes à coluna, como retornada pelo driver.

`var`

  Nome da variável PHP à qual a coluna será vinculada.

`type`

  Tipo de dado do parâmetro, especificado pelas constantes `PDO::PARAM_*` .

`maxLength`

  Um dica para pré-alocação.

`driverOptions`

  Um ou mais parâmetros opcionais para o driver.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Emite um erro de nível `E_WARNING` se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_WARNING`.

Lança uma exceção PDOException se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_EXCEPTION`.

### Exemplos

Exemplo #1 Vinculando a saída do conjunto de resultados a variáveis PHP

Vincular colunas no conjunto de resultados a variáveis PHP é uma maneira eficaz de fazer com que os dados contidos em cada linha estejam imediatamente disponíveis para a aplicação. O exemplo a seguir demonstra como o PDO permite que se vincule e se recupere colunas com uma variedade de opções e com padrões inteligentes.

    <?php
    $stmt = $dbh->prepare('SELECT name, colour, calories FROM fruit');
    $stmt->execute();

    /* Vincula por número da coluna */
    $stmt->bindColumn(1, $name);
    $stmt->bindColumn(2, $colour);

    /* Vincula por nome da coluna */
    $stmt->bindColumn('calories', $cals);

    while ($stmt->fetch(PDO::FETCH_BOUND)) {
        print $name . "\t" . $colour . "\t" . $cals . "\n";
    }

O exemplo acima produzirá algo semelhante a:

    apple   red     150
    banana  yellow  175
    kiwi    green   75
    orange  orange  150
    mango   red     200
    strawberry      red     25

### Veja Também

- PDOStatement::execute() - Executa ums instrução preparada
- PDOStatement::fetch() - Busca a próxima linha de um resultado
- PDOStatement::fetchAll() - Busca as linhas remanescentes de um conjunto de resultados
- PDOStatement::fetchColumn() - Retorna uma única coluna do próximo registro de um resultado

# PDOStatement::bindParam

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::bindParam — Vincula um parâmetro ao nome de variável especificado

### Descrição

public function PDOStatement::bindParam(
string|int `$param`,
mixed `&$var`,
int `$type` = `PDO::PARAM_STR`,
int `$maxLength` = 0,
mixed `$driverOptions` = `null`
): bool

Vincula uma variável PHP a um marcador nomeado ou de ponto de interrogação correspondente na instrução SQL que foi usada para preparar a instrução. Ao contrário de PDOStatement::bindValue(), a variável é vinculada como uma referência e só será avaliada no momento em que PDOStatement::execute() for chamado.

A maioria dos parâmetros são parâmetros de entrada, ou seja, parâmetros que são usados ​​somente leitura para construir a consulta (mas podem, mesmo assim, ser convertidos de acordo com o `type`). Alguns drivers suportam a invocação de procedimentos armazenados que retornam dados como parâmetros de saída, e alguns também como parâmetros de entrada/saída que tanto enviam dados quanto são atualizados para recebê-los.

### Parâmetros

`param`

  Identificador de parâmetro. Para uma instrução preparada usando marcadores nomeados, este será um nome de parâmetro no formato :name. Para uma instrução preparada usando marcadores de pontos de interrogação, esta será a posição indexada em 1 do parâmetro.

`var`

  Nome da variável PHP a ser vinculada ao parâmetro da instrução SQL.

`type`

  Tipo explícito de dados para o parâmetro usando as constantes `PDO::PARAM_*`. Para retornar um parâmetro INOUT de um procedimento armazenado, deve-se usar o operador binário OR para definir os bits `PDO::PARAM_INPUT_OUTPUT` para o parâmetro `type`.

`maxLength`

  Comprimento do tipo de dados. Para indicar que um parâmetro é um parâmetro OUT de um procedimento armazenado, deve-se definir explicitamente o comprimento. Significativo apenas quando o parâmetro `type` é `PDO::PARAM_INPUT_OUTPUT`.

`driverOptions`

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Emite um erro de nível `E_WARNING` se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_WARNING`.

Lança uma exceção PDOException se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_EXCEPTION`.

### Exemplos

Exemplo #1 Executando uma instrução preparada com marcadores nomeados

    <?php
    /* Executa uma instrução preparada vinculando variáveis ​​PHP */
    $calories = 150;
    $colour = 'red';
    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < :calories AND colour = :colour');
    $sth->bindParam('calories', $calories, PDO::PARAM_INT);
    /* Os nomes podem ser prefixados com dois pontos ":" também (opcional) */
    $sth->bindParam(':colour', $colour, PDO::PARAM_STR);
    $sth->execute();
    ?>

Exemplo #2 Executando uma instrução preparada com marcadores com pontos de interrogação

    <?php
    /* Executa uma instrução preparada vinculando variáveis ​​PHP */
    $calories = 150;
    $colour = 'red';
    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < ? AND colour = ?');
    $sth->bindParam(1, $calories, PDO::PARAM_INT);
    $sth->bindParam(2, $colour, PDO::PARAM_STR);
    $sth->execute();
    ?>

Exemplo #3 Chamando um procedimento armazenado com um parâmetro INOUT

    <?php
    /* Chamando um procedimento armazenado com um parâmetro INOUT */
    $colour = 'red';
    $sth = $dbh->prepare('CALL puree_fruit(?)');
    $sth->bindParam(1, $colour, PDO::PARAM_STR|PDO::PARAM_INPUT_OUTPUT, 12);
    $sth->execute();
    print "Após fazer um purê com a fruta, a cor é: $colour";
    ?>

### Veja Também

- PDO::prepare() - Prepara uma instrução para execução e retorna um objeto de instrução
- PDOStatement::execute() - Executa ums instrução preparada
- PDOStatement::bindValue() - Vincula um valor a um parâmetro

# PDOStatement::bindValue

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.0)

PDOStatement::bindValue — Vincula um valor a um parâmetro

### Descrição

public function PDOStatement::bindValue(string|int `$param`, mixed `$value`, int `$type` = `PDO::PARAM_STR`): bool

Vincula um valor a um marcador, nomeado ou de ponto de interrogação, na instrução SQL que foi usada para preparar a instrução.

### Parâmetros

`param`

  Identificador do parâmetro. Para uma instrução preparada que usa marcadores nomeados, será um nome de parâmetro na forma :name. Para uma instrução preparada que usa marcadores pontos de interrogação, será a posição indexada do parâmetro, iniciando em 1.

`value`

  O valor a ser vinculado ao parâmetro.

`type`

  Tipo de dado explícito para o parâmetro, usando as constantes `PDO::PARAM_*` .

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Emite um erro de nível `E_WARNING` se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_WARNING`.

Lança uma exceção PDOException se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_EXCEPTION`.

### Exemplos

Exemplo #1 Executando uma instrução preparada com marcadores nomeados

    <?php
    /* Executando uma instrução preparada vinculando variáveis do PHP */
    $calories = 150;
    $colour = 'red';
    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < :calories AND colour = :colour');

    /* Define um valor para o parâmetro usando seu nome */
    $sth->bindValue('calories', $calories, PDO::PARAM_INT);
    /* Opcionalmente, os nomes de parâmetros podem ser prefixados com dois pontos ":" */
    $sth->bindValue(':colour', $colour, PDO::PARAM_STR);
    $sth->execute();
    ?>

Exemplo #2 Executando uma instrução preparada com marcadores de ponto de interrogação

    <?php
    /* Executando uma instrução preparada vinculando variáveis do PHP */
    $calories = 150;
    $colour = 'red';
    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < ? AND colour = ?');
    $sth->bindValue(1, $calories, PDO::PARAM_INT);
    $sth->bindValue(2, $colour, PDO::PARAM_STR);
    $sth->execute();
    ?>

### Veja Também

- PDO::prepare() - Prepara uma instrução para execução e retorna um objeto de instrução
- PDOStatement::execute() - Executa ums instrução preparada
- PDOStatement::bindParam() - Vincula um parâmetro ao nome de variável especificado

# PDOStatement::closeCursor

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.9.0)

PDOStatement::closeCursor — Fecha o cursor, permitindo que a instrução seja executada novamente

### Descrição

public function PDOStatement::closeCursor(): bool

PDOStatement::closeCursor() libera a conexão ao servidor de forma que outras instruções SQL possam ser emitidas, mas deixa a instrução em um estado que permite que ela seja executada novamente.

Este método é útil para drivers de banco de dados que não suportam a execução de um objeto PDOStatement quando um object PDOStatement executado anteriormente ainda tem registros não recebidos. Se o driver do banco de dados sofrer desta limitação, o problema pode se manifestar em um erro de "fora-de-sequência".

PDOStatement::closeCursor() é implementado como um método opcional específico do driver (permitindo máxima eficiência), ou como o método PDO genérico se nenhuma função específica do driver estiver instalada. O método PDO genérico é semanticamente o mesmo que escrever o seguinte código no script PHP:

    <?php
    do {
        while ($stmt->fetch())
            ;
        if (!$stmt->nextRowset())
            break;
    } while (true);
    ?>

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Emite um erro de nível `E_WARNING` se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_WARNING`.

Lança uma exceção PDOException se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_EXCEPTION`.

### Exemplos

Exemplo #1 Um exemplo de PDOStatement::closeCursor()

No exemplo a seguire, o objeto PDOStatement $stmt retorna múltiplos registros mas a aplicação busca apenas a primeira linha, deixando o objeto PDOStatement em um estado com linhas não recebidas. Para assegurar que a aplicação irá funcionar com todos os drivers de banco de dados, o autor insere uma chamada a PDOStatement::closeCursor() na variável $stmt antes de executar o objeto PDOStatement $otherStmt.

    <?php
    /* Cria um objeto PDOStatement */
    $stmt = $dbh->prepare('SELECT foo FROM bar');

    /* Cria um segundo objeto PDOStatement */
    $otherStmt = $dbh->prepare('SELECT foobaz FROM foobar');

    /* Executa a primeira instrução */
    $stmt->execute();

    /* Busca somente a primeira linha do resultado */
    $stmt->fetch();

    /* A chamada a closeCursor() pode ser requerida por alguns drivers */
    $stmt->closeCursor();

    /* Agora pode-se executar a segunda instrução */
    $otherStmt->execute();
    ?>

### Veja Também

- PDOStatement::execute() - Executa ums instrução preparada

# PDOStatement::columnCount

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::columnCount — Retorna o número de colunas no conjunto de resultados

### Descrição

public function PDOStatement::columnCount(): int

Use PDOStatement::columnCount() para retornar o número de colunas no conjunto de resultados representado pelo objeto PDOStatement.

Se o objeto PDOStatement foi retornado por PDO::query(), a contagem de colunas estará disponível imediatamente.

Se o objeto PDOStatement foi retornado por PDO::prepare(), uma contagem precisa de colunas não estará disponível até que o método PDOStatement::execute() seja chamado.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número de colunas no conjunto de resultados representado pelo objeto PDOStatement, mesmo se o conjunto de resultados estiver vazio. Se não houver conjunto de resultados, PDOStatement::columnCount() retornará `0`.

### Erros/Exceções

Emite um erro de nível `E_WARNING` se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_WARNING`.

Lança uma exceção PDOException se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_EXCEPTION`.

### Exemplos

Exemplo #1 Contando colunas

Este exemplo demonstra como PDOStatement::columnCount() opera com e sem um conjunto de resultados.

    <?php
    $dbh = new PDO('odbc:sample', 'db2inst1', 'ibmdb2');

    $sth = $dbh->prepare("SELECT name, colour FROM fruit");

    /* Conta o número de colunas no conjunto de resultados (não existente) */
    $colcount = $sth->columnCount();
    print "Antes de execute(), o resultado tem $colcount colunas (deve ser 0)\n";

    $sth->execute();

    /* Conta o número de colunas no conjunto de resultados */
    $colcount = $sth->columnCount();
    print "Depois de execute(), o resultado tem $colcount colunas (devem ser 2)\n";

    ?>

O exemplo acima produzirá:

    Antes de execute(), o resultado tem 0 colunas (deve ser 0)
    Depois de execute(), o resultado tem 2 colunas (devem ser 2)

### Veja Também

- PDO::prepare() - Prepara uma instrução para execução e retorna um objeto de instrução
- PDOStatement::execute() - Executa ums instrução preparada
- PDOStatement::rowCount() - Retorna o número de registros afetados pela última instrução SQL

# PDOStatement::debugDumpParams

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.9.0)

PDOStatement::debugDumpParams — Despeja uma instrução preparada SQL

### Descrição

public function PDOStatement::debugDumpParams(): ?bool

Despeja a informação contida em uma instrução preparada diretamente na saída. Fornece a consulta `SQL` em uso, o número de parâmetros usados (`Params`), a lista de parâmetros com seus nomes de chave ou posição, seus nomes, suas posições na consulta (se for suportado pelo driver PDO, caso contrário será -1), tipo (`param_type`) como um inteiro, e um valor booleano `is_param`.

Esta é uma função de depuração, que despeja os dados diretamente na saída padrão.

Dica

Assim como qualquer coisa que envia seu resultado diretamente para o navegador, as funções de controle de saída podem ser usadas para capturar a saída desta função e salvá-la em uma string, por exemplo.

Esta função somente despejará os parâmetros na instrução no momento do despejo. Parâmetros extras não são armazenados na instrução, e não serão mostrados.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `null`, ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
7.2.0 | PDOStatement::debugDumpParams() agora retorna o SQL enviado ao banco de dados, incluindo a consulta completa, bruta (incluindo os marcadores substituídos por seus valores vinculados). Observe que isto só estará disponível se as instrução preparadas emuladas estiverem habilitadas.

### Exemplos

Exemplo #1 Exemplo de PDOStatement::debugDumpParams() com parâmetros nomeados

    <?php
    /* Executa uma instrução preparada vinculando variáveis PHP */
    $calories = 150;
    $colour = 'red';
    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < :calories AND colour = :colour');
    $sth->bindParam(':calories', $calories, PDO::PARAM_INT);
    $sth->bindValue(':colour', $colour, PDO::PARAM_STR, 12);
    $sth->execute();

    $sth->debugDumpParams();

    ?>

O exemplo acima produzirá:

    SQL: [96] SELECT name, colour, calories
        FROM fruit
        WHERE calories < :calories AND colour = :colour
    Params:  2
    Key: Name: [9] :calories
    paramno=-1
    name=[9] ":calories"
    is_param=1
    param_type=1
    Key: Name: [7] :colour
    paramno=-1
    name=[7] ":colour"
    is_param=1
    param_type=2

Exemplo #2 Exemplo de PDOStatement::debugDumpParams() com parâmetros anônimos

    <?php

    /* Executa uma instrução preparada vinculando variáveis PHP */
    $calories = 150;
    $colour = 'red';
    $name = 'apple';

    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < ? AND colour = ?');
    $sth->bindParam(1, $calories, PDO::PARAM_INT);
    $sth->bindValue(2, $colour, PDO::PARAM_STR);
    $sth->execute();

    $sth->debugDumpParams();

    ?>

O exemplo acima produzirá:

    SQL: [82] SELECT name, colour, calories
        FROM fruit
        WHERE calories < ? AND colour = ?
    Params:  2
    Key: Position #0:
    paramno=0
    name=[0] ""
    is_param=1
    param_type=1
    Key: Position #1:
    paramno=1
    name=[0] ""
    is_param=1
    param_type=2

### Veja Também

- PDO::prepare() - Prepara uma instrução para execução e retorna um objeto de instrução
- PDOStatement::bindParam() - Vincula um parâmetro ao nome de variável especificado
- PDOStatement::bindValue() - Vincula um valor a um parâmetro

# PDOStatement::errorCode

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::errorCode — Busca o SQLSTATE associado com a última operação no objeto da instrução

### Descrição

public function PDOStatement::errorCode(): ?string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Idêntico a PDO::errorCode(), exceto que PDOStatement::errorCode() somente recupera códigos de erro para operações realizadas com objetos PDOStatement.

### Exemplos

Exemplo #1 Recuperando o código SQLSTATE

    <?php
    /* Provoca um erro -- a tabela OSSOS não existe */
    $err = $dbh->prepare('SELECT cranio FROM ossos');
    $err->execute();

    echo "\nPDOStatement::errorCode(): ";
    print $err->errorCode();
    ?>

O exemplo acima produzirá:

    PDOStatement::errorCode(): 42S02

### Veja Também

- PDO::errorCode() - Busca o SQLSTATE associado com a última operação no identificador do banco de dados
- PDO::errorInfo() - Busca informação de erro estendida associada com a última operação no identificador do banco de dados
- PDOStatement::errorInfo() - Busca informação de erro estendida associada com a última operação no identificador da instrução

# PDOStatement::errorInfo

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::errorInfo — Busca informação de erro estendida associada com a última operação no identificador da instrução

### Descrição

public function PDOStatement::errorInfo(): array

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

PDOStatement::errorInfo() retorna um array de informações de erro sobre a última operação realizada por este objeto de instrução. O array consiste de pelo menos os campos a seguir:

Elemento | Informação
--- | ---
0 | Código de erro SQLSTATE (um identificador alfanumérico de cinco caracteres definido no padrão ANSI SQL).
1 | Código de erro específico do driver.
2 | Mensagem de erro específica do driver.

### Exemplos

Exemplo #1 Mostrando campos de errorInfo() para uma conexão PDO_ODBC a um banco de dados DB2

    <?php
    /* Provoca um erro -- a tabela OSSOS não existe */
    $sth = $dbh->prepare('SELECT cranio FROM ossos');
    $sth->execute();

    echo "\nPDOStatement::errorInfo():\n";
    $arr = $sth->errorInfo();
    print_r($arr);
    ?>

O exemplo acima produzirá:

    PDOStatement::errorInfo():
    Array
    (
        [0] => 42S02
        [1] => -204
        [2] => [IBM][CLI Driver][DB2/LINUX] SQL0204N  "LUCY.OSSOS" is an undefined name.  SQLSTATE=42704
    )

### Veja Também

- PDO::errorCode() - Busca o SQLSTATE associado com a última operação no identificador do banco de dados
- PDO::errorInfo() - Busca informação de erro estendida associada com a última operação no identificador do banco de dados
- PDOStatement::errorCode() - Busca o SQLSTATE associado com a última operação no objeto da instrução

# PDOStatement::execute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::execute — Executa ums instrução preparada

### Descrição

public function PDOStatement::execute(?array `$params` = `null`): bool

Executa a instrução preparada. Se a instrução preparada inclui marcadores de parâmetros:

- PDOStatement::bindParam() e/ou PDOStatement::bindValue() devem ser chamadas para vincular variáveis ou valores (respectivamente) aos marcadores de parâmetros. Variáveis vinculadas passam seus valores como entrada e recebem o valor de saída, se houver, de seus marcadores de parâmetros associados

- ou um array de valores de parâmetros, de entrada somente, deve ser passado

### Parâmetros

`params`

  Um array de valores com tantos elementos quantos forem os parâmetros vinculados na instrução SQL sendo executada. Todos os valores são tratados como `PDO::PARAM_STR`.

  Valores múltiplos não podem ser vinculados a um parâmetro único; por exemplo, não é permitido vincular dois valores a um único parâmetro nomeado em uma cláusula IN().

  Vincular mais valores que o especificado não é possível; se existirem mais chaves em `params` que no SQL especificado em PDO::prepare(), a instrução falhará e um erro será emitido.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Emite um erro de nível `E_WARNING` se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_WARNING`.

Lança uma exceção PDOException se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_EXCEPTION`.

### Exemplos

Exemplo #1 Executa uma instrução preparada com variável e valor vinculados

    <?php
    /* Executa uma instrução preparada vinculando uma variável e um valor */
    $calorias = 150;
    $cor = 'ver';
    $sth = $dbh->prepare('SELECT nome, cor, calorias
        FROM frutas
        WHERE calorias < :calorias AND cor LIKE :cor');
    $sth->bindParam('calorias', $calorias, PDO::PARAM_INT);
    /* Nomes podem ser prefixados com dois-pontos ":" também (opcional) */
    $sth->bindValue(':cor', "%$cor%");
    $sth->execute();
    ?>

Exemplo #2 Executa uma instrução preparada com um array de valores nomeados

    <?php
    /* Executa uma instrução preparada passando um array de valores de inserção */
    $calorias = 150;
    $cor = 'vermelha';
    $sth = $dbh->prepare('SELECT nome, cor, calorias
        FROM frutas
        WHERE calorias < :calorias AND cor = :cor');
    $sth->execute(array('calorias' => $calorias, 'cor' => $cor));
    /* Chaves de array podem ser prefixadas com dois-pontos ":" também (opcional) */
    $sth->execute(array(':calorias' => $calorias, ':cor' => $cor));
    ?>

Exemplo #3 Executa uma instrução preparada com um array de valores posicionais

    <?php
    /* Executa uma instrução preparada passando um array de valores de inserção */
    $calorias = 150;
    $cor = 'vermelha';
    $sth = $dbh->prepare('SELECT nome, cor, calorias
        FROM frutas
        WHERE calorias < ? AND cor = ?');
    $sth->execute(array($calorias, $cor));
    ?>

Exemplo #4 Executa uma instrução preparada com variáveis vinculadas a marcadores posicionais

    <?php
    /* Executa uma instrução preparada vinculando variáveis PHP */
    $calorias = 150;
    $cor = 'vermelha';
    $sth = $dbh->prepare('SELECT nome, cor, calorias
        FROM frutas
        WHERE calorias < ? AND cor = ?');
    $sth->bindParam(1, $calorias, PDO::PARAM_INT);
    $sth->bindParam(2, $cor, PDO::PARAM_STR, 12);
    $sth->execute();
    ?>

Exemplo #5 Executa uma instrução preparada usando array para cláusula IN

    <?php
    /* Executa uma instrução preparada usando um array de valores para uma cláusula IN */
    $params = array(1, 21, 63, 171);
    /* Cria uma string para marcadores de parâmetros preenchidas com o número de parâmetros */
    $place_holders = '?' . str_repeat(', ?', count($params) - 1);

    /*
        Isto prepara a instrução com marcadores anônimos suficientes para cada valor
        no array $params. Os valores do array $params são então vinculados aos
        marcadores na instrução preparada quando ele é executada.
        Isto não é a mesma coisa que usar PDOStatement::bindParam() já que isso
        requer uma referência à variável. PDOStatement::execute() apenas vincula
        por valor.
    */
    $sth = $dbh->prepare("SELECT id, nome FROM contatos WHERE id IN ($place_holders)");
    $sth->execute($params);
    ?>

### Notas

> Nota:

> Alguns drivers requerem que o cursor seja fechado antes que a próxima instrução seja executada.

### Veja Também

- PDO::prepare() - Prepara uma instrução para execução e retorna um objeto de instrução
- PDOStatement::bindParam() - Vincula um parâmetro ao nome de variável especificado
- PDOStatement::fetch() - Busca a próxima linha de um resultado
- PDOStatement::fetchAll() - Busca as linhas remanescentes de um conjunto de resultados
- PDOStatement::fetchColumn() - Retorna uma única coluna do próximo registro de um resultado

# PDOStatement::fetch

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::fetch — Busca a próxima linha de um resultado

### Descrição

public function PDOStatement::fetch(int `$mode` = `PDO::FETCH_DEFAULT`, int `$cursorOrientation` = `PDO::FETCH_ORI_NEXT`, int `$cursorOffset` = 0): mixed

Busca uma linha de um resultado associado com um objeto PDOStatement object. O parâmetro `mode` determina como o PDO retorna a linha.

### Parâmetros

`mode`

  Controla como a próxima linha será retornada ao chamador. Este valor precisa ser uma das constantes `PDO::FETCH_*`, padronizado para o valor de `PDO::ATTR_DEFAULT_FETCH_MODE` (cujo padrão é `PDO::FETCH_BOTH`).

  - `PDO::FETCH_ASSOC`: retorna um array indexado pelo nome da coluna como retornada no resultado

  - `PDO::FETCH_BOTH` (padrão): retorna um array indexado tanto por nome de coluna quanto por número de coluna indexado em 0, como retornado no resultado

  - `PDO::FETCH_BOUND`: retorna `true` e atribui os valores das colunas no conjunto de resultados às variáveis PHP às quais eles foram vinculados com o método PDOStatement::bindColumn()

  - `PDO::FETCH_CLASS`: retorna uma nova instância da classe solicitada. O objeto é inicializado mapeando as colunas do conjunto de resultados para propriedades na classe. Isso ocorre antes do construtor ser chamado, permitindo que as propriedades sejam preenchidas independentemente de sua visibilidade ou se estão marcadas como `readonly`. Se uma propriedade não existir na classe, o método mágico __set() será invocado se existir; caso contrário, será criada uma propriedade pública dinâmica. Entretanto, quando `PDO::FETCH_PROPS_LATE` também é fornecido, o construtor é chamado antes de as propriedades serem preenchidas. Se `mode` incluir `PDO::FETCH_CLASSTYPE` (por exemplo, `PDO::FETCH_CLASS | PDO::FETCH_CLASSTYPE`), o nome da classe é determinado a partir do valor da primeira coluna.

  - `PDO::FETCH_INTO`: atualiza uma instância existente da classe solicitada, mapeando as colunas do conjunto de resultados às propriedades nomeadas na classe

  - `PDO::FETCH_LAZY`: combina `PDO::FETCH_BOTH` e `PDO::FETCH_OBJ`, e retorna um objeto PDORow que cria os nomes das propriedades do objeto conforme elas são acessadas.

  - `PDO::FETCH_NAMED`: retorna um array com a mesma forma de `PDO::FETCH_ASSOC`, exceto que se houver múltiplas colunas com o mesmo nome, o valor referenciado pela chave será um array de todos os valores na linha que tiverem esse nome de coluna

  - `PDO::FETCH_NUM`: retorna um array indexado por número de coluna como retornado no conjunto de resultados, iniciando na coluna 0

  - `PDO::FETCH_OBJ`: retorna um objeto anônimo com nomes de propriedades que correspondem ao nomes de colunas retornados no conjunto de resultados

  - `PDO::FETCH_PROPS_LATE`: quando usado com `PDO::FETCH_CLASS`, o construtor da classe é chamado antes que as propriedades sejam atribuídas com os respectivos valores das colunas.

`cursorOrientation`

  Para um objeto PDOStatement representando um cursor navegável, este valor determina que linha será retornada ao chamador. Este valor precisa ser uma das constantes `PDO::FETCH_ORI_*`, sendo o padrão igual a `PDO::FETCH_ORI_NEXT`. Para requisitar um cursor navegável para o objeto PDOStatement, o atributo `PDO::ATTR_CURSOR` precisa ser definido para `PDO::CURSOR_SCROLL` ao preparar a instrução SQL com PDO::prepare().

`cursorOffset`

  Para um objeto PDOStatement representando um cursor navegável para o qual o parâmetro `cursorOrientation` esteja definido para `PDO::FETCH_ORI_ABS`, este valor especifica o número absoluto da linha no conjunto de resultados que deve ser buscada.

  Para um objeto PDOStatement representando um cursor navegável para o qual o parâmetro `cursorOrientation` esteja definido para `PDO::FETCH_ORI_REL`, este valor especifica a linha a ser buscada relativa à posição do cursor antes do método PDOStatement::fetch() ser chamado.

### Valor Retornado

O valor de retorno desta função em caso de sucesso depende do tipo de busca. Em todos os casos, `false` é retornado em caso de falha ou se não houver mais linhas.

### Erros/Exceções

Emite um erro de nível `E_WARNING` se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_WARNING`.

Lança uma exceção PDOException se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_EXCEPTION`.

### Exemplos

Exemplo #1 Buscando linhas usando estilos de busca diferentes

    <?php
    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    /* Exercita estilos de PDOStatement::fetch */
    print "PDO::FETCH_ASSOC: ";
    print "Retorna a próxima linha como um array indexado por nome de coluna\n";
    $result = $sth->fetch(PDO::FETCH_ASSOC);
    print_r($result);
    print "\n";

    print "PDO::FETCH_BOTH: ";
    print "Retorna a próxima linha como um array indexado por nome de coluna e número\n";
    $result = $sth->fetch(PDO::FETCH_BOTH);
    print_r($result);
    print "\n";

    print "PDO::FETCH_LAZY: ";
    print "Retorna a próxima linha como um objeto PDORow com nomes de colunas como propriedades\n";
    $result = $sth->fetch(PDO::FETCH_LAZY);
    print_r($result);
    print "\n";

    print "PDO::FETCH_OBJ: ";
    print "Retorna a próxima linha como um objeto anônimo com nomes de coluna como propriedades\n";
    $result = $sth->fetch(PDO::FETCH_OBJ);
    print $result->name;
    print "\n";
    ?>

O exemplo acima produzirá:

    PDO::FETCH_ASSOC: Retorna a próxima linha como um array indexado por nome de coluna
    Array
    (
        [name] => apple
        [colour] => red
    )

    PDO::FETCH_BOTH: Retorna a próxima linha como um array indexado por nome de coluna e número
    Array
    (
        [name] => banana
        [0] => banana
        [colour] => yellow
        [1] => yellow
    )

    PDO::FETCH_LAZY: Retorna a próxima linha como um objeto PDORow com nomes de colunas como propriedades
    PDORow Object
    (
        [name] => orange
        [colour] => orange
    )

    PDO::FETCH_OBJ: Retorna a próxima linha como um objeto anônimo com nomes de coluna como propriedades
    kiwi

Exemplo #2 Buscando linhas com um cursor navegável

    <?php
    function readDataForwards($dbh) {
        $sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY BET';
        $stmt = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL));
        $stmt->execute();
        while ($row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_NEXT)) {
            $data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
            print $data;
        }
    }
    function readDataBackwards($dbh) {
        $sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY bet';
        $stmt = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL));
        $stmt->execute();
        $row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_LAST);
        do {
            $data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
            print $data;
        } while ($row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_PRIOR));
    }

    print "Lendo para a frente:\n";
    readDataForwards($conn);

    print "Lendo para trás:\n";
    readDataBackwards($conn);
    ?>

O exemplo acima produzirá:

    Reading forwards:
    21    10    5
    16    0     5
    19    20    10

    Reading backwards:
    19    20    10
    16    0     5
    21    10    5

Exemplo #3 Ordem de construção

Quando objetos são buscados através de `PDO::FETCH_CLASS`, as propriedades do objeto são atribuídas primeiro, e depois o construtor da classe é invocado. Entretanto, quando `PDO::FETCH_PROPS_LATE` também for informada, esta ordem é revertida, isto, é, primeiro o construtor é chamado, e depois as propriedades são atribuídas.

    <?php
    class Person
    {
        private $name;

        public function __construct()
        {
            $this->tell();
        }

        public function tell()
        {
            if (isset($this->name)) {
                echo "Eu sou {$this->name}.\n";
            } else {
                echo "Eu não tenho um nome ainda.\n";
            }
        }
    }

    $sth = $dbh->query("SELECT * FROM people");
    $sth->setFetchMode(PDO::FETCH_CLASS, 'Person');
    $person = $sth->fetch();
    $person->tell();
    $sth->setFetchMode(PDO::FETCH_CLASS|PDO::FETCH_PROPS_LATE, 'Person');
    $person = $sth->fetch();
    $person->tell();
    ?>

O exemplo acima produzirá algo semelhante a:

    Eu sou Alice.
    Eu sou Alice.
    Eu não tenho um nome ainda.
    Eu sou Bob.

### Veja Também

- PDO::prepare() - Prepara uma instrução para execução e retorna um objeto de instrução
- PDOStatement::execute() - Executa ums instrução preparada
- PDOStatement::fetchAll() - Busca as linhas remanescentes de um conjunto de resultados
- PDOStatement::fetchColumn() - Retorna uma única coluna do próximo registro de um resultado
- PDOStatement::fetchObject() - Busca o próximo registro e retorna-o como um objeto
- PDOStatement::setFetchMode() - Define o modo de carga de dados para esta instrução

# PDOStatement::fetchAll

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::fetchAll — Busca as linhas remanescentes de um conjunto de resultados

### Descrição

public function PDOStatement::fetchAll(int `$mode` = PDO::FETCH_DEFAULT): array
public function PDOStatement::fetchAll(int `$mode` = PDO::FETCH_COLUMN, int `$column`): array
public function PDOStatement::fetchAll(int `$mode` = PDO::FETCH_CLASS, string `$class`, ?array `$constructorArgs`): array
public function PDOStatement::fetchAll(int `$mode` = PDO::FETCH_FUNC, callable `$callback`): array

### Parâmetros

`mode`

  Controla o conteúdo do array retornado como documentado em PDOStatement::fetch(). O padrão é `PDO::ATTR_DEFAULT_FETCH_MODE` (cujo padrão é `PDO::FETCH_BOTH`).

  Para retornar um array que consiste em todos os valores de uma única coluna do conjunto de resultados, especifique `PDO::FETCH_COLUMN`. Pode-se especificar uma coluna qualquer com o parâmetro `column`.

  Para indexar o array resultante pelo valor de uma determinada coluna (em vez de números consecutivos), coloque o nome desta coluna primeiro na lista de colunas no SQL e use `PDO::FETCH_UNIQUE`. Esta coluna deve conter apenas valores exclusivos ou alguns dados serão perdidos.

  Para agrupar resultados na forma de um array tridimensional indexado por valores de uma coluna especificada, coloque o nome desta coluna primeiro na lista de colunas no SQL e use `PDO::FETCH_GROUP`.

  Para agrupar resultados na forma de um array bidimensional, use a operação OR binária com `PDO::FETCH_GROUP` e `PDO::FETCH_COLUMN`. Os resultados serão agrupados pela primeira coluna, com o valor do elemento do array sendo um array de lista das entradas correspondentes da segunda coluna.

A lista a seguir apresenta parâmetros dinâmicos que dependem do modo de busca. Eles não podem ser usados com parâmetros nomeados.

`column`

  Usado com `PDO::FETCH_COLUMN`. Retorna a coluna indicada com índice iniciando em 0.

`class`

  Usado com `PDO::FETCH_CLASS`. Retorna instâncias da classe especificada, mapeando colunas de cada linha a propriedades nomeadas na classe.

`constructorArgs`

  Argumentos de construtor de classe customizado quando o parâmetro `mode` for `PDO::FETCH_CLASS`.

`callback`

  Usado com `PDO::FETCH_FUNC`. Retorna os resultados da chamada à função especificada, usando cada coluna do registro como parâmetro na chamada.

### Valor Retornado

PDOStatement::fetchAll() retorna um array contendo todas os registros remanescentes no conjunto de resultados O array representa cada registro como um array de valores de coluna ou um objeto com propriedades correspondentes a cada nome de coluna. Um array vazio é retornado se não houver resultados na busca.

Usar este método para burcar conjuntos de resultados grandes resultará em uma alta demanda no sistema e possivelmente em recursos de rede. Ao invés de recuperar todos os dados e manipulá-los no PHP, deve ser considerado usar o servidor de banco de dados para manipular os conjuntos de resultados. Por exemplo, usando as cláusulas WHERE e ORDER BY no SQL para restringir resultados antes de recuperá-los e processá-los com o PHP.

### Erros/Exceções

Emite um erro de nível `E_WARNING` se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_WARNING`.

Lança uma exceção PDOException se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_EXCEPTION`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Este método agora sempre retornará um array, enquanto antes poderia retornar `false` em caso de falha.

### Exemplos

Exemplo #1 Buscando todos os registros remanescentes em um conjunto de resultados

    <?php
    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    /* Busca todos os registros remanescentes em um conjunto de resultados */
    print "Busca todos os registros remanescentes em um conjunto de resultados:\n";
    $result = $sth->fetchAll();
    print_r($result);
    ?>

O exemplo acima produzirá algo semelhante a:

    Busca todos os registros remanescentes em um conjunto de resultados:
    Array
    (
        [0] => Array
            (
                [name] => apple
                [0] => apple
                [colour] => red
                [1] => red
            )

        [1] => Array
            (
                [name] => pear
                [0] => pear
                [colour] => green
                [1] => green
            )

        [2] => Array
            (
                [name] => watermelon
                [0] => watermelon
                [colour] => pink
                [1] => pink
            )

    )

Exemplo #2 Buscando todos os valores de uma única coluna de um resultado

O exemplo a seguir demonstra como retornar todos os valores de uma única coluna de um resultado, mesmo que a instrução SQL em si possa retornar múltiplas colunas por registro.

    <?php
    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    /* Busca todos os valores da primeira coluna */
    $result = $sth->fetchAll(PDO::FETCH_COLUMN, 0);
    var_dump($result);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array(3)
    (
        [0] =>
        string(5) => apple
        [1] =>
        string(4) => pear
        [2] =>
        string(10) => watermelon
    )

Exemplo #3 Agrupando todos os valores por uma única coluna

O exemplo a seguir demonstra como retornar um array associativo agrupado pelos valores da coluna especificada no resultado. O array contém três chaves: valores `apple` e `pear` são retornados como arrays que contêm duas cores diferentes, enquanto `watermelon` é retornado como um array qye contém apenas uma cor.

    <?php
    $insert = $dbh->prepare("INSERT INTO fruit(name, colour) VALUES (?, ?)");
    $insert->execute(array('apple', 'green'));
    $insert->execute(array('pear', 'yellow'));

    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    /* Agrupa valores pela primeira coluna */
    var_dump($sth->fetchAll(PDO::FETCH_COLUMN|PDO::FETCH_GROUP));
    ?>

O exemplo acima produzirá algo semelhante a:

    array(3) {
      ["apple"]=>
      array(2) {
        [0]=>
        string(5) "green"
        [1]=>
        string(3) "red"
      }
      ["pear"]=>
      array(2) {
        [0]=>
        string(5) "green"
        [1]=>
        string(6) "yellow"
      }
      ["watermelon"]=>
      array(1) {
        [0]=>
        string(5) "pink"
      }
    }

Exemplo #4 Instanciando uma classe para cada resultado

O exemplo a seguir demonstra o comportamento do estilo de busca `PDO::FETCH_CLASS`.

    <?php
    class fruit {
        public $name;
        public $colour;
    }

    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    $result = $sth->fetchAll(PDO::FETCH_CLASS, "fruit");
    var_dump($result);
    ?>

O exemplo acima produzirá algo semelhante a:

    array(3) {
      [0]=>
      object(fruit)#1 (2) {
        ["name"]=>
        string(5) "apple"
        ["colour"]=>
        string(5) "green"
      }
      [1]=>
      object(fruit)#2 (2) {
        ["name"]=>
        string(4) "pear"
        ["colour"]=>
        string(6) "yellow"
      }
      [2]=>
      object(fruit)#3 (2) {
        ["name"]=>
        string(10) "watermelon"
        ["colour"]=>
        string(4) "pink"
      }
      [3]=>
      object(fruit)#4 (2) {
        ["name"]=>
        string(5) "apple"
        ["colour"]=>
        string(3) "red"
      }
      [4]=>
      object(fruit)#5 (2) {
        ["name"]=>
        string(4) "pear"
        ["colour"]=>
        string(5) "green"
      }
    }

Exemplo #5 Chamando uma função para cada resultado

O exemplo a seguir demonstra o comportamento do estilo de busca `PDO::FETCH_FUNC`.

    <?php
    function fruit($name, $colour) {
        return "{$name}: {$colour}";
    }

    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    $result = $sth->fetchAll(PDO::FETCH_FUNC, "fruit");
    var_dump($result);
    ?>

O exemplo acima produzirá algo semelhante a:

    array(3) {
      [0]=>
      string(12) "apple: green"
      [1]=>
      string(12) "pear: yellow"
      [2]=>
      string(16) "watermelon: pink"
      [3]=>
      string(10) "apple: red"
      [4]=>
      string(11) "pear: green"
    }

### Veja Também

- PDO::query() - Prepara e executa uma instrução SQL sem marcadores
- PDOStatement::fetch() - Busca a próxima linha de um resultado
- PDOStatement::fetchColumn() - Retorna uma única coluna do próximo registro de um resultado
- PDO::prepare() - Prepara uma instrução para execução e retorna um objeto de instrução
- PDOStatement::setFetchMode() - Define o modo de carga de dados para esta instrução

# PDOStatement::fetchColumn

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.9.0)

PDOStatement::fetchColumn — Retorna uma única coluna do próximo registro de um resultado

### Descrição

public function PDOStatement::fetchColumn(int `$column` = 0): mixed

Retorna uma única coluna do próximo registro de um resultado ou `false` se não houver mais registros.

> Nota:

> PDOStatement::fetchColumn() não deve ser usado para colunas do tipo booleano, já que é impossível distinguir um valor de `false` em relação à inexistência de mais registros a se recuperar. Use PDOStatement::fetch() em seu lugar.

### Parâmetros

`column`

  Número da coluna que se deseja recuperar do registro, com índice iniciando em 0. Se nenhum valor for informado, PDOStatement::fetchColumn() busca a primeira coluna.

### Valor Retornado

PDOStatement::fetchColumn() retorna uma única coluna do próximo registro do resultado ou `false` se não houver mais registros.

Aviso

Não há como retornar outra coluna do mesmo registro se o método PDOStatement::fetchColumn() for usado para recuperar dados.

### Erros/Exceções

Emite um erro de nível `E_WARNING` se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_WARNING`.

Lança uma exceção PDOException se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_EXCEPTION`.

### Exemplos

Exemplo #1 Retorna a primeira coluna do próximo registro

    <?php
    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    print "Busca a primeira coluna da primeira linha do resultado:\n";
    $result = $sth->fetchColumn();
    print "name = $result\n";

    print "Busca a segunda coluna da segunda linha do resultado:\n";
    $result = $sth->fetchColumn(1);
    print "colour = $result\n";
    ?>

O exemplo acima produzirá:

    Busca a primeira coluna da primeira linha do resultado:
    name = lemon
    Busca a segunda coluna da segunda linha do resultado:
    colour = red

### Veja Também

- PDO::query() - Prepara e executa uma instrução SQL sem marcadores
- PDOStatement::fetch() - Busca a próxima linha de um resultado
- PDOStatement::fetchAll() - Busca as linhas remanescentes de um conjunto de resultados
- PDO::prepare() - Prepara uma instrução para execução e retorna um objeto de instrução
- PDOStatement::setFetchMode() - Define o modo de carga de dados para esta instrução

# PDOStatement::fetchObject

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.4)

PDOStatement::fetchObject — Busca o próximo registro e retorna-o como um objeto

### Descrição

public function PDOStatement::fetchObject(?string `$class` = "stdClass", array `$constructorArgs` = []): object|false

Busca o próximo registro e retorna-o como um objeto. Esta função é uma alternativa a PDOStatement::fetch() com estilo `PDO::FETCH_CLASS` ou `PDO::FETCH_OBJ`.

Quando um objeto é buscado, suas propriedades são atribuídas a partir dos respectivos valores de colunas, e depois seu construtor é invocado.

### Parâmetros

`class`

  Nome da classe a ter um objeto criado.

`constructorArgs`

  Elementos deste array são passados para o construtor.

### Valor Retornado

Retorna uma instância da classe solicitada com nomes de propriedades que correspondem aos nomes de colunas ou `false` em caso de falha.

### Erros/Exceções

Emite um erro de nível `E_WARNING` se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_WARNING`.

Lança uma exceção PDOException se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_EXCEPTION`.

### Veja Também

- PDOStatement::fetch() - Busca a próxima linha de um resultado

# PDOStatement::getAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::getAttribute — Recupera um atributo da instrução

### Descrição

public function PDOStatement::getAttribute(int `$name`): mixed

Obtém um atributo da instrução. Atualmente, não existem atributos genéricos mas apenas específicos de drivers:

- `PDO::ATTR_CURSOR_NAME` (específico do Firebird e do ODBC): Obtém o nome do cursor para `UPDATE ... WHERE CURRENT OF`.

Observe que atributos específicos de drivers não podem ser usados com outros drivers.

### Parâmetros

`name`

  O atributo a ser consultado.

### Valor Retornado

Retorna o valor do atributo.

### Veja Também

- PDO::getAttribute() - Recuperar um atributo da conexão com o banco de dados
- PDO::setAttribute() - Define um atributo
- PDOStatement::setAttribute() - Define um atributo na instrução

# PDOStatement::getColumnMeta

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::getColumnMeta — Retorna metadados para uma coluna no resultado

### Descrição

public function PDOStatement::getColumnMeta(int `$column`): array|false

Retorna metadados para uma coluna no resultado, indexada a partir de 0, como um array associativo.

Aviso

Alguns drivers podem não implementar o método PDOStatement::getColumnMeta(), já que ele é opcional. Entretanto, todos os drivers PDO documentados neste manual implementam este método.

### Parâmetros

`column`

  A coluna no resultado, indexada a partir de 0.

### Valor Retornado

Retorna um array associativo contendo os seguintes valores que representam os metadados para uma única coluna:

Metadados de coluna
Nome | Valor
--- | ---
`native_type` | O tipo de dados nativo do PHP usado para representar o valor da coluna.
`driver:decl_type` | O tipo de dados SQL usado para representar o valor da coluna no banco de dados. Se a coluna for resultado de uma função, este valor não será retornado por PDOStatement::getColumnMeta().
`flags` | Quaisquer opções configuradas para esta coluna.
`name` | O nome desta coluna como retornado pelo banco de dados.
`table` | O nome da tabela desta coluna como retornado pelo banco de dados.
`len` | O comprimento desta coluna. Normalmente `-1` para tipos que não sejam números com decimais.
`precision` | A precisão numérica desta coluna. Normalmente `0` para tipos que não sejam números decimais.
`pdo_type` | O tipo desta coluna como representado pelas constantes `PDO::PARAM_*`.

Retorna `false` se a coluna requisitada não existir no resultado ou se não existir resultado.

### Exemplos

Exemplo #1 Recuperando metadados de coluna

O exemplo a seguir mostra o resultado da recuperação de metadados para uma única coluna gerada por uma função (COUNT) em um driver PDO_SQLITE.

    <?php
    $select = $DB->query('SELECT COUNT(*) FROM fruit');
    $meta = $select->getColumnMeta(0);
    var_dump($meta);
    ?>

O exemplo acima produzirá:

    array(6) {
      ["native_type"]=>
      string(7) "integer"
      ["flags"]=>
      array(0) {
      }
      ["name"]=>
      string(8) "COUNT(*)"
      ["len"]=>
      int(-1)
      ["precision"]=>
      int(0)
      ["pdo_type"]=>
      int(2)
    }

### Veja Também

- PDOStatement::columnCount() - Retorna o número de colunas no conjunto de resultados
- PDOStatement::rowCount() - Retorna o número de registros afetados pela última instrução SQL

# PDOStatement::getIterator

(PHP 8)

PDOStatement::getIterator — Obtém o iterador do conjunto de resultados

### Descrição

public function PDOStatement::getIterator(): Iterator

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# PDOStatement::nextRowset

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::nextRowset — Avança para o próximo conjunto de registros em um identificados de instrução com múltiplos conjuntos de registros

### Descrição

public function PDOStatement::nextRowset(): bool

Alguns servidores de bancos de dados suportam procedimentos armazenados que retornam mais de um conjunto de registros (também conhecido como conjunto de resultados). PDOStatement::nextRowset() habilita o acesso ao segundo conjunto de registros, e subsequentes, associados com um objeto PDOStatement. Cada conjunto de registros pode ter um conjunto diferente de colunas em relação ao conjunto anterior.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Buscando múltiplos conjuntos de registros de um procedimento armazenado

O exemplo a seguir mostra como chamar um procedimento armazenado, `MULTIPLE_ROWSETS`, que retorna três conjuntos de registros. É usado um laço do-while para chamar o método PDOStatement::nextRowset() até que ele retorne `false` e termine o laço quando não houver mais conjuntos de registros disponíveis.

    <?php
    $sql = 'CALL multiple_rowsets()';
    $stmt = $conn->query($sql);
    $i = 1;
    do {
        $rowset = $stmt->fetchAll(PDO::FETCH_NUM);
        if ($rowset) {
            printResultSet($rowset, $i);
        }
        $i++;
    } while ($stmt->nextRowset());

    function printResultSet(&$rowset, $i) {
        print "Conjunto de resultados $i:\n";
        foreach ($rowset as $row) {
            foreach ($row as $col) {
                print $col . "\t";
            }
            print "\n";
        }
        print "\n";
    }
    ?>

O exemplo acima produzirá:

    Conjunto de resultados 1:
    apple    red
    banana   yellow

    Conjunto de resultados 2:
    orange   orange    150
    banana   yellow    175

    Conjunto de resultados 3:
    lime     green
    apple    red
    banana   yellow

### Veja Também

- PDOStatement::columnCount() - Retorna o número de colunas no conjunto de resultados
- PDOStatement::execute() - Executa ums instrução preparada
- PDOStatement::getColumnMeta() - Retorna metadados para uma coluna no resultado
- PDO::query() - Prepara e executa uma instrução SQL sem marcadores

# PDOStatement::rowCount

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::rowCount — Retorna o número de registros afetados pela última instrução SQL

### Descrição

public function PDOStatement::rowCount(): int

PDOStatement::rowCount() retorna o número de registros afetados pela última instrução DELETE, INSERT ou UPDATE executada pelo objeto `PDOStatement` correspondente.

Para instruções que produzem conjuntos de resultados, como `SELECT`, o comportamento é indefinido e pode ser diferente para cada driver. Alguns bancos de dados podem retornar o número de registros produzidos por essa instrução (por exemplo, MySQL em modo buffer), mas este comportamento não é garantido para todos os bancos de dados e não deve ser uma fonte confiável para aplicações portáveis.

> Nota:

> Este método retorna "0" (zero) com o driver PostgreSQL ao definir o atributo de instrução `PDO::ATTR_CURSOR` para `PDO::CURSOR_SCROLL`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número de registros.

### Erros/Exceções

Emite um erro de nível `E_WARNING` se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_WARNING`.

Lança uma exceção PDOException se o atributo `PDO::ATTR_ERRMODE` estiver definido como `PDO::ERRMODE_EXCEPTION`.

### Exemplos

Exemplo #1 Retorna o número de registros apagados

PDOStatement::rowCount() retorna o número de registros afetados pelas instruções DELETE, INSERT ou UPDATE.

    <?php
    /* Apaga todos os registros da tabela FRUIT */
    $del = $dbh->prepare('DELETE FROM fruit');
    $del->execute();

    /* Retorna o número de registros apagados */
    print "Número retornado de registros apagados:\n";
    $count = $del->rowCount();
    print "$count registros apagados.\n";
    ?>

O exemplo acima produzirá algo semelhante a:

    Número retornado de registros apagados:
    9 registros apagados.

Exemplo #2 Contando registros retornados por uma instrução SELECT

Para a maioria dos bancos de dados, o método PDOStatement::rowCount() não retorna o número de registros afetados por uma instrução SELECT. Ao invés dele, o método PDO::query() deve ser usado para emitir uma instrução SELECT COUNT(*) com os mesmos predicados da instrução SELECT requerida, e então PDOStatement::fetchColumn() deve ser usado para recuperar o número de registros correspondentes.

    <?php
    $sql = "SELECT COUNT(*) FROM fruit WHERE calories > 100";
    $res = $conn->query($sql);
    $count = $res->fetchColumn();

    print "Há " .  $count . " registros correspondentes.";

O exemplo acima produzirá algo semelhante a:

    Há 2 registros correspondentes.

### Veja Também

- PDOStatement::columnCount() - Retorna o número de colunas no conjunto de resultados
- PDOStatement::fetchColumn() - Retorna uma única coluna do próximo registro de um resultado
- PDO::query() - Prepara e executa uma instrução SQL sem marcadores

# PDOStatement::setAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::setAttribute — Define um atributo na instrução

### Descrição

public function PDOStatement::setAttribute(int `$attribute`, mixed `$value`): bool

Define um atributo na instrução. Atualmente não há atributos genericos definidos, apenas atributos específicos do driver:

- `PDO::ATTR_CURSOR_NAME` (Específico do Firebird e do ODBC): Define o nome do cursor para `UPDATE ... WHERE CURRENT OF`.

Note que atributos específicos de drivers não devem ser usados com outros drivers.

### Parâmetros

`attribute`

  O atibuto a modificar.

`value`

  O valor para definir o `attribute`, pode requerer um tipo específico dependendo do atributo.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- PDO::getAttribute() - Recuperar um atributo da conexão com o banco de dados
- PDO::setAttribute() - Define um atributo
- PDOStatement::getAttribute() - Recupera um atributo da instrução

# PDOStatement::setFetchMode

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::setFetchMode — Define o modo de carga de dados para esta instrução

### Descrição

public function PDOStatement::setFetchMode(int `$mode`): true
public function PDOStatement::setFetchMode(int `$mode` = PDO::FETCH_COLUMN, int `$colno`): true
public function PDOStatement::setFetchMode(int `$mode` = PDO::FETCH_CLASS, string `$class`, ?array `$constructorArgs` = `null`): true
public function PDOStatement::setFetchMode(int `$mode` = PDO::FETCH_INTO, object `$object`): true

### Parâmetros

`mode`

  O modo de carga precisa ser uma das constantes `PDO::FETCH_*`.

`colno`

  Número da coluna.

`class`

  Nome da classe.

`constructorArgs`

  Argumentos do construtor.

`object`

  Objeto.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | O tipo do retorno agora é `true`; anteriormente, era bool.

### Exemplos

Exemplo #1 Definindo um modo de carga

O seguinte exemplo demonstra como o PDOStatement::setFetchMode() altera o modo padrão de carga em um objeto PDOStatement.

    <?php
    $stmt = $dbh->query('SELECT name, colour, calories FROM fruit');
    $stmt->setFetchMode(PDO::FETCH_NUM);
    foreach ($stmt as $row) {
        print $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
    }

O exemplo acima produzirá algo semelhante a:

    apple   red     150
    banana  yellow  250
    orange  orange  300
    kiwi    brown   75
    lemon   yellow  25
    pear    green   150

## Índice

- PDOStatement::bindColumn — Vincula uma coluna a uma variável PHP
- PDOStatement::bindParam — Vincula um parâmetro ao nome de variável especificado
- PDOStatement::bindValue — Vincula um valor a um parâmetro
- PDOStatement::closeCursor — Fecha o cursor, permitindo que a instrução seja executada novamente
- PDOStatement::columnCount — Retorna o número de colunas no conjunto de resultados
- PDOStatement::debugDumpParams — Despeja uma instrução preparada SQL
- PDOStatement::errorCode — Busca o SQLSTATE associado com a última operação no objeto da instrução
- PDOStatement::errorInfo — Busca informação de erro estendida associada com a última operação no identificador da instrução
- PDOStatement::execute — Executa ums instrução preparada
- PDOStatement::fetch — Busca a próxima linha de um resultado
- PDOStatement::fetchAll — Busca as linhas remanescentes de um conjunto de resultados
- PDOStatement::fetchColumn — Retorna uma única coluna do próximo registro de um resultado
- PDOStatement::fetchObject — Busca o próximo registro e retorna-o como um objeto
- PDOStatement::getAttribute — Recupera um atributo da instrução
- PDOStatement::getColumnMeta — Retorna metadados para uma coluna no resultado
- PDOStatement::getIterator — Obtém o iterador do conjunto de resultados
- PDOStatement::nextRowset — Avança para o próximo conjunto de registros em um identificados de instrução com múltiplos conjuntos de registros
- PDOStatement::rowCount — Retorna o número de registros afetados pela última instrução SQL
- PDOStatement::setAttribute — Define um atributo na instrução
- PDOStatement::setFetchMode — Define o modo de carga de dados para esta instrução

# A classe PDORow

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.0)

## Introdução

Representa uma linha de um conjunto de resultados retornado pelo PDOStatement::fetch() chamado com o modo de recuperação `PDO::FETCH_LAZY`.

Objetos desta classe não podem ser instanciados e não são serializáveis.

O objeto PDORow permite acesso aos dados retornados como se tanto o modo `PDO::FETCH_OBJ` quanto o modo `PDO::FETCH_BOTH` fossem usados. Isso significa que os dados retornados podem ser acessados como propriedades de objeto, e como um array indexado tanto pelo nome da coluna quanto pelo número de deslocamento da coluna.

Cuidado

Acesso a uma propriedade indefinida retorna `null` sem emitir um aviso.

## Resumo da classe

final class PDORow {
/* Propriedades */
public string $queryString;
}

## Propriedades

queryString

  String de consulta usada pelo PDOStatement que retornou o objeto PDORow.

## Erros/Exceções

Gera um Error ao tentar escrever ou unset() em qualquer propriedade.

# A classe PDOException

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

## Introdução

Representa um erro levantado pelo PDO. Não se deve lançar uma PDOException de dentro do código do usuário. Veja Exceções para mais informações sobre Exceções em PHP.

## Resumo da classe

class PDOException extends RuntimeException {
/* Propriedades */
protected int|string $code;
public ?array $errorInfo = null;
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Propriedades

errorInfo

  Corresponde a PDO::errorInfo() ou PDOStatement::errorInfo()

code

  Código de erro `SQLSTATE`. Use Exception::getCode() para acessá-lo.

# Drivers do PDO

## Índice

- Driver PDO do CUBRID
- Driver PDO do MS SQL Server
- Pdo\Dblib
- Driver PDO do Firebird
- Pdo\Firebird
- Driver PDO da IBM
- Driver PDO do Informix
- Driver PDO do MySQL
- Pdo\Mysql
- Driver PDO do Microsoft SQL Server
- Driver PDO do Oracle
- Driver PDO do ODBC e do DB2
- Pdo\Odbc
- Driver PDO do PostgreSQL
- Pdo\Pgsql
- Driver PDO do SQLite
- Pdo\Sqlite

Os seguintes drivers atualmente implementam a interface PDO:

Nome do Driver | Bancos de Dados Suportados
--- | ---
PDO_CUBRID | Cubrid
PDO_DBLIB | FreeTDS / Microsoft SQL Server / Sybase
PDO_FIREBIRD | Firebird
PDO_IBM | IBM DB2
PDO_INFORMIX | IBM Informix Dynamic Server
PDO_MYSQL | MySQL 3.x/4.x/5.x/8.x
PDO_OCI | Oracle Call Interface
PDO_ODBC | ODBC v3 (IBM DB2, unixODBC e ODBC win32)
PDO_PGSQL | PostgreSQL
PDO_SQLITE | SQLite 3 e SQLite 2
PDO_SQLSRV | Microsoft SQL Server / SQL Azure

# Driver PDO do CUBRID (PDO_CUBRID)

## Introdução

PDO_CUBRID é um driver que implementa a interface PHP Data Objects (PDO) para permitir acesso do PHP a bancos de dados CUBRID.

> Nota: A versão atual do PDO_CUBRID não suporta conexão persistente agora.

## Instalação

Para construir a extensão PDO_CUBRID, o SGBD CUBRID deve estar instalado no mesmo sistema que o PHP. O PDO_CUBRID é uma extensão » PECL, então siga as instruções em Instalação das extensões PECL para instalar a extensão PDO_CUBRID. Emita o comando configure para apontar para a localização do diretório base do CUBRID da seguinte forma:

       $ ./configure --with-pdo-cubrid=/path/to/CUBRID[,shared]

O comando configure utiliza por padrão o valor da variável de ambiente CUBRID.

Uma DLL para esta extensão PECL não está disponível no momento. Veja também a seção Compilando no Windows. Para informações detalhadas sobre a instalação no Linux e Windows manualmente, leia o arquivo build-guide.html no pacote PECL CUBRID para referência.

## Recursos do PDO_CUBRID

## Cursores Roláveis

PDO_CUBRID suporta cursores roláveis. O tipo de cursor padrão é somente para frente, e você pode usar a opção do driver em PDO::prepare() para mudar o tipo de cursor.

## Timeout

PDO_CUBRID suporta definição de tempo limite de execução de declarações SQL; Você pode usar PDO::setAttribute() para definir o valor do timeout.

## Modo de Autocommit e Transação

PDO_CUBRID suporta tanto o modo de autocommit quanto transações, e o modo de autocommit está habilitado por padrão. Você pode usar PDO::setAttribute() para mudar seu estado.

Se você usar PDO::beginTransaction() para iniciar uma transação, ela desabilitará automaticamente o modo de autocommit e restaurará após PDO::commit() ou PDO::rollBack().

> Nota: Antes de desabilitar o modo de autocommit, qualquer instrução pendente é automaticamente processada.

## Múltiplas Declarações SQL

PDO_CUBRID suporta Múltiplas declarações SQL. declarações SQL são separadas por ponto e vírgula (`;`).

## Informações de Esquema

PDO_CUBRID implementa PDO::cubrid_schema() para obter informações de esquema.

## LOBs

PDO_CUBRID suporta tipo de dado BLOB/CLOB. O LOB no PDO é representado como um fluxo, de forma que LOBs possam ser inseridos através de vinculação a um fluxo, e obtidos pela leitura de um fluxo retornado pelo CUBRID PDO. Por exemplo:

Exemplo #1 Inserir LOBs no CUBRID PDO

    <?php
    $fp = fopen('lob_test.png', 'rb');

    $sql_stmt = "INSERT INTO lob_test(name, content) VALUES('lob_test.png', ?)";

    $stmt = $dbh->prepare($sql_stmt);
    $ret = $stmt->bindParam(1, $fp, PDO::PARAM_LOB);
    $ret = $stmt->execute();
    ?>

Exemplo #2 Buscar LOBs no CUBRID PDO

    <?php
    $sql_stmt = "SELECT content FROM lob_test WHERE name='lob_test.png'";

    $stmt = $dbh->prepare($sql_stmt);
    $stmt->execute();
    $result = $stmt->fetch(PDO::FETCH_NUM);

    header("Content-Type: image/png");
    fpassthru($result[0]);
    ?>

## Meta-dados de Coluna

O PDOStatement::getColumnMeta() no CUBRID PDO retornará um array associativo contendo os seguintes valores:

- type
- name
- table
- def
- precision
- scale
- not_null
- auto_increment
- unique_key
- multiple_key
- primary_key
- foreign_key
- reverse_index
- reverse_unique

## Tipo de Dados de Coleção

PDO_CUBRID suporta tipo de dados SET/MULTISET/SEQUENCE. Se o tipo de dados não for especificado, o padrão será char. Por exemplo:

Exemplo #3 Inserir conjunto no CUBRID PDO com tipo de dado padrão.

    <?php
    $conn_str ="cubrid:dbname=demodb;host=localhost;port=33000";
    $cubrid_pdo = new PDO($conn_str, 'dba', '');

    $cubrid_pdo->exec("DROP TABLE if exists test_tbl");
    $cubrid_pdo->exec("CREATE TABLE test_tbl (col_1 SET(VARCHAR))");

    $sql_stmt_insert = "INSERT INTO test_tbl VALUES (?);";
    $stmt = $cubrid_pdo->prepare($sql_stmt_insert);
    $data = array("abc","def","ghi");
    $ret = $stmt->bindParam(1, $data, PDO::PARAM_NULL);
    $ret = $stmt->execute();
    var_Dump($ret);
    ?>

Exemplo #4 Especificar tipo de dado ao inserir conjunto no CUBRID PDO

    <?php
    $conn_str ="cubrid:dbname=demodb;host=localhost;port=33000";
    $cubrid_pdo = new PDO($conn_str, 'dba', '');

    $cubrid_pdo->exec("DROP TABLE if exists test_tbl");
    $cubrid_pdo->exec("CREATE TABLE test_tbl (col_1 SET(int))");

    $sql_stmt_insert = "INSERT INTO test_tbl VALUES (?);";
    $stmt = $cubrid_pdo->prepare($sql_stmt_insert);
    $data = array(1,2,3,4);
    $ret = $stmt->bindParam(1, $data, 0,0,"int");
    $ret = $stmt->execute();
    var_Dump($ret);
    ?>

Tipos de Dados Vinculados CUBRID para o quinto parâmetro de PDOStatement::bindParam():

- CHAR
- STRING
- NCHAR
- VARNCHAR
- BIT
- VARBIT
- NUMERIC
- NUMBER
- INT
- SHORT
- BIGINT
- MONETARY
- FLOAT
- DOUBLE
- DATE
- TIME
- DATETIME
- TIMESTAMP

## Constantes predefinidas

As constantes abaixo são definidas por este driver e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução. Além disso, estas constantes específicas do driver só devem ser usadas se este driver estiver sendo usado. Usar atributos específicos de um driver com outro driver pode resultar em comportamento inesperado. PDO::getAttribute() pode ser usada para obter o atributo `PDO::ATTR_DRIVER_NAME` para verificar o driver, se o código puder ser executado com vários drivers.

As seguintes constantes podem ser usadas ao definir o atributo do banco de dados. Elas podem ser passadas para PDO::getAttribute() ou PDO::setAttribute().

PDO::CUBRID attribute flags
Constante | Descrição
--- | ---
`PDO::CUBRID_ATTR_ISOLATION_LEVEL` | Nível de isolamento de transação para a conexão do banco de dados.
`PDO::CUBRID_ATTR_LOCK_TIMEOUT` | Tempo limite de transação em segundos.
`PDO::CUBRID_ATTR_MAX_STRING_LENGTH` | Somente leitura. O comprimento máximo da string para bit, varbit, char, varchar, nchar, tipos de dados nchar ao usar a API PDO CUBRID.

As seguintes constantes podem ser usadas ao definir o nível de isolamento da transação. Elas podem ser passadas para PDO::getAttribute() ou retornadas por PDO::setAttribute().

Flags de nível de isolamento do PDO::CUBRID
Constante | Descrição
--- | ---
`PDO::TRAN_COMMIT_CLASS_UNCOMMIT_INSTANCE` | O nível de isolamento mais baixo (1). Uma leitura suja, não repetível ou leitura fantasma pode ocorrer para a tupla e uma leitura não repetível pode ocorrer para a tabela também.
`PDO::TRAN_COMMIT_CLASS_COMMIT_INSTANCE` | Um nível de isolamento relativamente baixo (2). Uma leitura suja não ocorre, mas uma leitura não repetível ou fantasma pode ocorrer.
`PDO::TRAN_REP_CLASS_UNCOMMIT_INSTANCE` | O isolamento padrão do CUBRID (3). Uma leitura suja, não repetível ou leitura fantasma pode ocorrer para a tupla, mas uma leitura repetível é garantida para a tabela.
`PDO::TRAN_REP_CLASS_COMMIT_INSTANCE` | Um nível de isolamento relativamente baixo (4). Uma leitura suja não ocorre, mas uma leitura não repetível ou fantasma pode ocorrer.
`PDO::TRAN_REP_CLASS_REP_INSTANCE` | Um nível de isolamento relativamente alto (5). Uma leitura suja ou não repetível não ocorre, mas uma leitura fantasma pode.
`PDO::TRAN_SERIALIZABLE` | O mais alto nível de isolamento (6). Problemas relacionados à concorrência (por exemplo, leitura suja, leitura não repetível, leitura fantasma, etc.) não ocorrem.

As seguintes constantes podem ser usadas ao obter informações de esquema. Elas podem ser passadas para PDO::cubrid_schema().

PDO::CUBRID schema flags
Constante | Descrição
--- | ---
`PDO::CUBRID_SCH_TABLE` | Obtém o nome e o tipo da tabela no CUBRID.
`PDO::CUBRID_SCH_VIEW` | Obtém o nome e o tipo da visão no CUBRID.
`PDO::CUBRID_SCH_QUERY_SPEC` | Obtém a definição da consulta da visão.
`PDO::CUBRID_SCH_ATTRIBUTE` | Obtém os atributos da coluna da tabela.
`PDO::CUBRID_SCH_TABLE_ATTRIBUTE` | Obtém os atributos da tabela.
`PDO::CUBRID_SCH_METHOD` | Obtém o método de instância. O método de instância é um método chamado por uma instância de classe. É usado com mais frequência do que o método de classe porque a maioria das operações é executada na instância.
`PDO::CUBRID_SCH_TABLE_METHOD` | Obtém o método de classe. O método de classe é um método chamado por um objeto de classe. Geralmente é usado para criar uma nova instância de classe ou inicializá-la. Também é usado para acessar ou atualizar atributos de classe.
`PDO::CUBRID_SCH_METHOD_FILE` | Obtém as informações do arquivo onde o método da tabela está definido.
`PDO::CUBRID_SCH_SUPER_TABLE` | Obtém o nome e o tipo da tabela que herda atributos.
`PDO::CUBRID_SCH_SUB_TABLE` | Obtém o nome e o tipo da tabela que herda atributos desta tabela.
`PDO::CUBRID_SCH_CONSTRAINT` | Obtém as restrições (constraints) da tabela.
`PDO::CUBRID_SCH_TRIGGER` | Obtém os disparadores (triggers) da tabela.
`PDO::CUBRID_SCH_TABLE_PRIVILEGE` | Obtém informações de privilégio da tabela.
`PDO::CUBRID_SCH_COL_PRIVILEGE` | Obtém informações de privilégio da coluna.
`PDO::CUBRID_SCH_DIRECT_SUPER_TABLE` | Obtém a tabela super direta da tabela.
`PDO::CUBRID_SCH_PRIMARY_KEY` | Obtém a chave primária da tabela.
`PDO::CUBRID_SCH_IMPORTED_KEYS` | Obtém chaves importadas da tabela.
`PDO::CUBRID_SCH_EXPORTED_KEYS` | Obtém chaves exportadas da tabela.
`PDO::CUBRID_SCH_CROSS_REFERENCE` | Obtém relação de referência de duas tabelas.

# PDO_CUBRID DSN

(PECL PDO_CUBRID >= 8.3.0.0001)

PDO_CUBRID DSN — Conectando-se a bancos de dados CUBRID

### Descrição

O Nome da Fonte de Dados (DSN) PDO_CUBRID é composto pelos seguintes elementos, delimitados por ponto e vírgula:

DSN prefix

  O prefixo DSN é `cubrid:`.

`host`
  O nome do host no qual o servidor de banco de dados reside.
`port`
  A porta na qual o servidor de banco de dados está em execução.
`dbname`
  O nome do banco de dados.

### Notas

> Nota: Ao estabelecer a conexão com o CUBRID, você deve fornecer nome de usuário e senha, exceto o DSN.

### Exemplos

Exemplo #1 Exemplos de DSN PDO_CUBRID

O exemplo a seguir mostra um DSN PDO_CUBRID para se conectar a um banco de dados CUBRID:

    cubrid:host=localhost;port=33000;dbname=demodb

# PDO::cubrid_schema

(PECL PDO_CUBRID >= 8.3.0.0001)

PDO::cubrid_schema — Obtém as informações do esquema solicitadas

### Descrição

public function PDO::cubrid_schema(int `$schema_type`, string `$table_name` = ?, string `$col_name` = ?): array

Esta função é usada para obter as informações do esquema solicitadas do banco de dados. Deve ser informado o nome da tabela em `table_name`, se for necessário obter informações sobre determinada tabela e o nome da coluna em `col_name`, se a intenção for obter informações sobre determinada coluna (pode ser usado apenas com PDO:: CUBRID_SCH_COL_PRIVILEGE).

O resultado desta função é retornado como um array bidimensional (coluna (array associativo) * linha (array numérico)). As tabelas a seguir mostram os tipos de esquema e a estrutura de colunas do array de resultados a ser retornada com base no tipo de esquema.

Composição de Resultado para Cada Tipo
Esquema | Número da Coluna | Nome da Coluna | Valor
--- | --- | --- | ---
PDO::CUBRID_SCH_TABLE | 1 | NAME |
| 2 | TYPE | 0:system table 1:view 2:table
PDO::CUBRID_SCH_VIEW | 1 | NAME |
| 2 | TYPE | 1:view
PDO::CUBRID_SCH_QUERY_SPEC | 1 | QUERY_SPEC |
PDO::CUBRID_SCH_ATTRIBUTE / PDO::CUBRID_SCH_TABLE_ATTRIBUTE | 1 | ATTR_NAME |
| 2 | DOMAIN |
| 3 | SCALE |
| 4 | PRECISION |
| 5 | INDEXED | 1:indexed
| 6 | NOT NULL | 1:not null
| 7 | SHARED | 1:shared
| 8 | UNIQUE | 1:unique
| 9 | DEFAULT |
| 10 | ATTR_ORDER | base:1
| 11 | CLASS_NAME |
| 12 | SOURCE_CLASS |
| 13 | IS_KEY | 1:key
PDO::CUBRID_SCH_METHOD / PDO::CUBRID_SCH_TABLE_METHOD | 1 | NAME |
| 2 | RET_DOMAIN |
| 3 | ARG_DOMAIN |
PDO::CUBRID_SCH_METHOD_FILE | 1 | METHOD_FILE |
PDO::CUBRID_SCH_SUPER_TABLE / PDO::CUBRID_SCH_DIRECT_SUPER_TABLE / PDO::CUBRID_SCH_SUB_TABLE | 1 | CLASS_NAME |
| 2 | TYPE | 0:system table 1:view 2:table
PDO::CUBRID_SCH_CONSTRAINT | 1 | TYPE | 0:unique 1:index 2:reverse unique 3:reverse index
| 2 | NAME |
| 3 | ATTR_NAME |
| 4 | NUM_PAGES |
| 5 | NUM_KEYS |
| 6 | PRIMARY_KEY | 1:primary key
| 7 | KEY_ORDER | base:1
PDO::CUBRID_SCH_TRIGGER | 1 | NAME |
| 2 | STATUS |
| 3 | EVENT |
| 4 | TARGET_CLASS |
| 5 | TARGET_ATTR |
| 6 | ACTION_TIME |
| 7 | ACTION |
| 8 | PRIORITY |
| 9 | CONDITION_TIME |
| 10 | CONDITION |
PDO::CUBRID_SCH_TABLE_PRIVILEGE / PDO::CUBRID_SCH_COL_PRIVILEGE | 1 | CLASS_NAME / ATTR_NAME |
| 2 | PRIVILEGE |
| 3 | GRANTABLE |
PDO::CUBRID_SCH_PRIMARY_KEY | 1 | CLASS_NAME |
| 2 | ATTR_NAME |
| 3 | KEY_SEQ | base:1
| 4 | KEY_NAME |
PDO::CUBRID_SCH_IMPORTED_KEYS / PDO::CUBRID_SCH_EXPORTED_KEYS / PDO::CUBRID_SCH_CROSS_REFERENCE | 1 | PKTABLE_NAME |
| 2 | PKCOLUMN_NAME |
| 3 | FKTABLE_NAME | base:1
| 4 | FKCOLUMN_NAME |
| 5 | KEY_SEQ | base:1
| 6 | UPDATE_ACTION | 0:cascade 1:restrict 2:no action 3:set null
| 7 | DELETE_ACTION | 0:cascade 1:restrict 2:no action 3:set null
| 8 | FK_NAME |
| 9 | PK_NAME |

### Parâmetros

`schema_type`
  Tipo de esquema a ser conhecido.
`table_name`
  Tabela cujo esquema deseja-se conhecer.
`col_name`
  Coluna cujo esquema deseja-se conhecer.

### Valor Retornado

Array contendo informações do esquema, em caso de sucesso;

FALSE, em caso de falha.

### Exemplos

Exemplo #1 Um exemplo de PDO::cubrid_schema()

Este exemplo mostra como obter a chave primária e as chaves estrangeiras da tabela 'game'.

    <?php
    $pk_list = $dbh->cubrid_schema(PDO::CUBRID_SCH_PRIMARY_KEY, "game");
    print_r($pk_list);

    $fk_list = $dbh->cubrid_schema(PDO::CUBRID_SCH_IMPORTED_KEYS, "game");
    print_r($fk_list);
    ?>

O exemplo acima produzirá:

    Resultado:
    Array
    (
        [0] => Array
            (
                [CLASS_NAME] => game
                [ATTR_NAME] => athlete_code
                [KEY_SEQ] => 3
                [KEY_NAME] => pk_game_host_year_event_code_athlete_code
            )

        [1] => Array
            (
                [CLASS_NAME] => game
                [ATTR_NAME] => event_code
                [KEY_SEQ] => 2
                [KEY_NAME] => pk_game_host_year_event_code_athlete_code
            )

        [2] => Array
            (
                [CLASS_NAME] => game
                [ATTR_NAME] => host_year
                [KEY_SEQ] => 1
                [KEY_NAME] => pk_game_host_year_event_code_athlete_code
            )

    )
    Array
    (
        [0] => Array
            (
                [PKTABLE_NAME] => athlete
                [PKCOLUMN_NAME] => code
                [FKTABLE_NAME] => game
                [FKCOLUMN_NAME] => athlete_code
                [KEY_SEQ] => 1
                [UPDATE_RULE] => 1
                [DELETE_RULE] => 1
                [FK_NAME] => fk_game_athlete_code
                [PK_NAME] => pk_athlete_code
            )

        [1] => Array
            (
                [PKTABLE_NAME] => event
                [PKCOLUMN_NAME] => code
                [FKTABLE_NAME] => game
                [FKCOLUMN_NAME] => event_code
                [KEY_SEQ] => 1
                [UPDATE_RULE] => 1
                [DELETE_RULE] => 1
                [FK_NAME] => fk_game_event_code
                [PK_NAME] => pk_event_code
            )

    )

## Índice

- PDO_CUBRID DSN — Conectando-se a bancos de dados CUBRID
- PDO::cubrid_schema — Obtém as informações do esquema solicitadas

# Driver PDO do Microsoft SQL Server e Sybase (PDO_DBLIB)

## Introdução

PDO_DBLIB é um driver que implementa a interface para Objetos de Dados PHP Data Objects (PDO) para permitir o acesso do PHP aos bancos de dados Microsoft SQL Server e Sybase através da biblioteca FreeTDS.

Esta extensão não está mais disponível no Windows.

No Windows, deve ser usado o SqlSrv, um driver alternativo para MS SQL está disponível na Microsoft: » http://msdn.microsoft.com/en-us/sqlserver/ff657782.aspx .

Caso não seja possível usar o SqlSrv, pode-se usar o driver PDO_ODBC para conectar-se aos bancos de dados Microsoft SQL Server e Sybase, pois o DB-LIB nativo do Windows é antigo, inseguro para threads e não é mais suportado pela Microsoft.

# PDO_DBLIB DSN

(PECL PDO_DBLIB >= 0.9.0)

PDO_DBLIB DSN — Conectando-se aos bancos de dados Microsoft SQL Server e Sybase

### Descrição

O Nome da Fonte de Dados (DSN) PDO_DBLIB é composto pelos seguintes elementos:

Prefixo DSN

  O prefixo DSN é `sybase:` se o PDO_DBLIB foi vinculado às bibliotecas Sybase ct-lib, `mssql:` se o PDO_DBLIB foi vinculado às bibliotecas do Microsoft SQL Server ou `dblib :` se o PDO_DBLIB foi vinculado às bibliotecas FreeTDS.

`host`

  O nome do servidor onde o banco de dados reside. O padrão é 127.0.0.1.

`dbname`

  O nome do banco de dados.

`charset`

  O conjunto de caracteres do cliente.

`appname`

  O nome da aplicação (usado nos processos do sistema). O padrão é "PHP Generic DB-lib" ou "PHP freetds".

`secure`

  Atualmente não utilizado.

### Exemplos

Exemplo #1 Exemplos de DSN PDO_DBLIB

Os exemplos a seguir mostram um DSN PDO_DBLIB para conexão com bancos de dados Microsoft SQL Server e Sybase:

    mssql:host=localhost;dbname=testdb
    sybase:host=localhost;dbname=testdb
    dblib:host=localhost;dbname=testdb

## Índice

- PDO_DBLIB DSN — Conectando-se aos bancos de dados Microsoft SQL Server e Sybase

# A classe Pdo\Dblib

(PHP 8 >= 8.4.0)

## Introdução

Uma subclasse PDO representando uma conexão que usa o driver PDO DBLib.

## Resumo da classe

namespace Pdo;
class Dblib extends PDO {
/* Constantes herdadas */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Constantes */
public const int ATTR_CONNECTION_TIMEOUT;
public const int ATTR_QUERY_TIMEOUT;
public const bool ATTR_STRINGIFY_UNIQUEIDENTIFIER;
public const int ATTR_VERSION;
public const int ATTR_TDS_VERSION;
public const int ATTR_SKIP_EMPTY_ROWSETS;
public const bool ATTR_DATETIME_CONVERT;
/* Métodos herdados */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Constantes predefinidas

`Pdo\Dblib::ATTR_CONNECTION_TIMEOUT`
`Pdo\Dblib::ATTR_QUERY_TIMEOUT`
`Pdo\Dblib::ATTR_STRINGIFY_UNIQUEIDENTIFIER`
  A partir do PHP 8.4.0, esta constante é tipada como bool; anteriormente, era tipada como int.
`Pdo\Dblib::ATTR_VERSION`
`Pdo\Dblib::ATTR_TDS_VERSION`
`Pdo\Dblib::ATTR_SKIP_EMPTY_ROWSETS`
`Pdo\Dblib::ATTR_DATETIME_CONVERT`
  Esse atributo de conexão controla o formato das strings para tipos datetime. Quando definido como `false`, o PDO_DBLIB retornará um tipo datetime como uma string no formato em que o SQL Server o retorna (ou seja, `"2017-10-27 10:22:44"`). Quando `true`, o PDO_DBLIB converterá o tipo datetime em uma string usando um formato definido pelo usuário ou pela localidade, conforme especificado no arquivo locales.conf do FreeTDS. Por padrão, esse atributo é `false`. A partir do PHP 8.4.0, esta constante é tipada como bool; anteriormente, era tipada como int.

# Driver PDO do Firebird (PDO_FIREBIRD)

## Introdução

PDO_FIREBIRD é um driver que implementa a interface aos Objetos de Dados PHP (PDO) para permitir acesso do PHP a bancos de dados Firebird.

## Instalação

Use --with-pdo-firebird[=DIR] para instalar a extensão PDO Firebird, onde o `[=DIR]` opcional é o diretório base de instalação do Firebird.

    $ ./configure --with-pdo-firebird

## Constantes predefinidas

As constantes abaixo são definidas por este driver e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução. Além disso, estas constantes específicas do driver só devem ser usadas se este driver estiver sendo usado. Usar atributos específicos de um driver com outro driver pode resultar em comportamento inesperado. PDO::getAttribute() pode ser usada para obter o atributo `PDO::ATTR_DRIVER_NAME` para verificar o driver, se o código puder ser executado com vários drivers.

`PDO::FB_ATTR_DATE_FORMAT` (int)

  Sinônimo de `Pdo\Firebird::ATTR_DATE_FORMAT`.

`PDO::FB_ATTR_TIME_FORMAT` (int)

  Sinônimo de `Pdo\Firebird::ATTR_TIME_FORMAT`.

`PDO::FB_ATTR_TIMESTAMP_FORMAT` (int)

  Sinônimo de `Pdo\Firebird::ATTR_TIMESTAMP_FORMAT`.

# PDO_FIREBIRD DSN

(PECL PDO_FIREBIRD >= 0.1.0)

PDO_FIREBIRD DSN — Conectando ao banco de dados Firebird

### Descrição

O Nome da Fonte de Dados (DSN) PDO_FIREBIRD é composto pelos seguintes elementos:

DSN prefix

  O prefixo DSN é `firebird:`.

`dbname`

  O nome do banco de dados.

`charset`

  O conjunto de caracteres.

`role`

  O nome da função SQL.

`dialect`

  O dialeto do banco de dados; `1` ou `3`. Se não for especificado, o dialeto será padronizado como `3`. Disponível a partir do PHP 7.4.0.

### Exemplos

Exemplo #1 Exemplo de DSN PDO_FIREBIRD DSN com caminho

O exemplo a seguir mostra um DSN PDO_FIREBIRD para conexão com bancos de dados Firebird:

    firebird:dbname=/caminho/para/DATABASE.FDB

Exemplo #2 Exemplo de DSN PDO_FIREBIRD com porta e caminho

O exemplo a seguir mostra um DSN PDO_FIREBIRD para conexão a um banco de dados Firebird usando nome de servidor, porta e caminho:

    firebird:dbname=servidor/porta:/caminho/para/DATABASE.FDB

Exemplo #3 Exemplo de DSN PDO_FIREBIRD com localhost e caminho para Employee.fdb no sistema Debian

O exemplo a seguir mostra um DSN PDO_FIREBIRD para conexão a um banco de dados Firebird employee.fdb usando localhost:

    firebird:dbname=localhost:/var/lib/firebird/2.5/data/employee.fdb

Exemplo #4 DSN PDO_FIREBIRD para conectar-se a um banco de dados de dialeto 1

O exemplo a seguir mostra um DSN PDO_FIREBIRD para conexão a um banco de dados Firebird teste.fdb que foi criado usando o dialeto 1. Isso só é suportado a partir do PHP 7.4.0.

    firebird:dbname=localhost:/var/lib/firebird/2.5/data/teste.fdb;charset=utf-8;dialect=1

## Índice

- PDO_FIREBIRD DSN — Conectando ao banco de dados Firebird

# A classe Pdo\Firebird

(PHP 8 >= 8.4.0)

## Introdução

Uma subclasse PDO representando uma conexão que usa o driver PDO Firebird.

## Resumo da classe

namespace Pdo;
class Firebird extends PDO {
/* Constantes herdadas */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Constantes */
public const int ATTR_DATE_FORMAT;
public const int ATTR_TIME_FORMAT;
public const int ATTR_TIMESTAMP_FORMAT;
public const int TRANSACTION_ISOLATION_LEVEL;
public const int READ_COMMITTED;
public const int REPEATABLE_READ;
public const int SERIALIZABLE;
public const int WRITABLE_TRANSACTION;
/* Métodos */
public static function getApiVersion(): int
/* Métodos herdados */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Constantes predefinidas

`Pdo\Firebird::ATTR_DATE_FORMAT`
  Define o formato de data.
`Pdo\Firebird::ATTR_TIME_FORMAT`
  Define o formato de horário.
`Pdo\Firebird::ATTR_TIMESTAMP_FORMAT`
  Define o formato de timestamp.
`Pdo\Firebird::TRANSACTION_ISOLATION_LEVEL`
  Atributo para definir o nível de isolamento da transação. Pode ser uma das constantes `Pdo\Firebird::READ_COMMITTED`, `Pdo\Firebird::REPEATABLE_READ` ou `Pdo\Firebird::SERIALIZABLE`.
`Pdo\Firebird::READ_COMMITTED`
  Opção que denota que o nível de isolamento de transação ANSI é de confirmação de leitura. Este é o comportamento padrão.
`Pdo\Firebird::REPEATABLE_READ`
  Opção que denota que o nível de isolamento de transação ANSI é de leitura repetível. Corresponde ao nível de isolamento "snapshot" do Firebird.
`Pdo\Firebird::SERIALIZABLE`
  Opção que denota que o nível de isolamento de transação ANSI é serializável. Corresponde ao nível de isolamento "snapshot table stability" do Firebird.
`Pdo\Firebird::WRITABLE_TRANSACTION`
  Atributo booleano usado para alternar o modo de acesso de transação entre `READ ONLY` e `READ WRITE`. Por padrão é `true`, que indica `READ WRITE`.

# Pdo\Firebird::getApiVersion

(PHP 8 >= 8.4.0)

Pdo\Firebird::getApiVersion — Obtém a versão da API

### Descrição

public static function Pdo\Firebird::getApiVersion(): int

Retorna a versão da API do Firebird como definida pela constante C `FB_API_VER` em ibase.h.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a API do FireBird como um int.

## Índice

- Pdo\Firebird::getApiVersion — Obtém a versão da API

# Driver PDO da IBM (PDO_IBM)

## Introdução

PDO_IBM é um driver que implementa a interface aos Objetos de Dados PHP (PDO) para permitir acesso do PHP a bancos de dados IBM.

## Instalação

Para construir a extensão PDO_IBM, o DB2 Client v9.1 ou posterior deve ser instalado no mesmo sistema que o PHP. O DB2 Client pode ser obtido do » Site de Desenvolvimento de Aplicativos da IBM.

> Nota: Notas

> O DB2 Client v9.1 ou posterior suporta acesso direto aos servidores DB2 para Linux, UNIX e Windows v8 e v9.1.

> O DB2 Client v9.1 também suporta acesso a servidores DB2 UDB para i5 e DB2 UDB para z/OS usando o » produto DB2 Connect adquirido separadamente.

PDO_IBM é uma extensão » PECL, portanto siga as instruções em Instalação das extensões PECL para instalar a extensão PDO_IBM. Execute o comando configure para apontar o caminho dos arquivos de cabeçalho e bibliotecas do DB2 Client, conforme a seguir:

    bash$ ./configure --with-pdo-ibm=/caminho/para/sqllib[,shared]

O comando configure tem como padrão o valor da variável de ambiente DB2DIR.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de Configuração do PDO_IBM
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
pdo_ibm.i5_dbcs_alloc | "0" | `INI_SYSTEM` | Adicionado no PDO_IBM 1.5.0
pdo_ibm.i5_override_ccsid | "0" | `INI_SYSTEM` | Adicionado no PDO_IBM 1.5.0

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`pdo_ibm.i5_dbcs_alloc` int

  Esta opção afeta a estratégia de alocação de buffer interno no IBM i. Por padrão, esta opção é 0. Quando esta opção é definida, os buffers são alocados com um tamanho muito maior, caso o banco de dados se engane sobre o tamanho dos caracteres ao converter entre codificações. Esta opção usa seis vezes mais memória para buffers (para considerar as maiores sequências UTF-8 possíveis), mas pode ser necessária se forem retornados dados truncados.

  - 0 - Buffers de tamanho mínimo são alocados.

  - 1 - Buffers de tamanho maior são alocados.

`pdo_ibm.i5_override_ccsid` int

  O CCSID ASCII a ser usado para conversão de EBCDIC no IBM i. Definir como 1208 usará UTF-8. Por padrão, é 0, que selecionará o CCSID da tarefa ASCII padrão.

  Para saber mais sobre CCSIDs no IBM i, consulte a » documentação da IBM.

# PDO_IBM DSN

(PECL PDO_IBM >= 0.9.0)

PDO_IBM DSN — Conectando-se a bancos de dados IBM

### Descrição

O Nome da Fonte de Dados (DSN) PDO_IBM é baseado no DSN IBM CLI. Os principais componentes do DSN PDO_IBM são:

DSN prefix

  O prefixo DSN é `ibm:`.

DSN

  O DSN pode ser qualquer um dos seguintes:

  - a) Configuração da fonte de dados usando db2cli.ini ou odbc.ini

  - b) Nome do banco de dados catalogado, ou seja, apelido do banco de dados no catálogo do cliente DB2

  - c) String de conexão completa no seguinte formato: `DRIVER={IBM DB2 ODBC DRIVER};DATABASE=`database`;HOSTNAME=`hostname`;PORT=`port`;PROTOCOL=TCPIP;UID=`username`;PWD=`password`;` onde os parâmetros representam os seguintes valores:

    `database`

      O nome do banco de dados.

    `hostname`

      O nome ou endereço do servidor de banco de dados.

    `port`

      A porta TCP/IP na qual o banco de dados está atendendo requisições.

    `username`

      O nome de usuário com o qual será feita a conexão ao banco de dados.

    `password`

      A senha com a qual será feita a conexão ao banco de dados.

### Exemplos

Exemplo #1 Exemplo de DSN PDO_IBM usando db2cli.ini

O exemplo a seguir mostra um DSN PDO_IBM para conexão com um banco de dados DB2 catalogado como DB2_9 em db2cli.ini:

    $db = new PDO("ibm:DSN=DB2_9", "", "");

    [DB2_9]
    Database=db_teste
    Protocol=tcpip
    Hostname=11.22.33.444
    Servicename=56789

Exemplo #2 Exemplo de DSN PDO_IBM usando uma string de conexão

O exemplo a seguir mostra um DSN PDO_IBM para conexão com um banco de dados DB2 denominado `testdb` usando a sintaxe da string de conexão CLI do DB2.

    $db = new PDO("ibm:DRIVER={IBM DB2 ODBC DRIVER};DATABASE=testdb;" .
      "HOSTNAME=11.22.33.444;PORT=56789;PROTOCOL=TCPIP;", "usuario_teste", "senha_teste");

## Índice

- PDO_IBM DSN — Conectando-se a bancos de dados IBM

# Driver PDO do Informix (PDO_INFORMIX)

## Introdução

PDO_INFORMIX é um driver que implementa a interface aos Objetos de Dados PHP (PDO) para permitir acesso do PHP a bancos de dados Informix.

## Instalação

Para construir a extensão PDO_INFORMIX, o Informix Client SDK 2.81 UC1 ou superior deve ser instalado no mesmo sistema que o PHP. O Informix Client SDK está disponível no » site de suporte do IBM Informix.

PDO_INFORMIX é uma extensão » PECL, portanto devem ser seguidas as instruções em Instalação das extensões PECL para instalá-la. Execute o comando configure para apontar o caminho dos arquivos de cabeçalho e bibliotecas do Informix Client SDK, conforme a seguir:

       bash$ ./configure --with-pdo-informix=/caminho/para/SDK[,shared]

O comando configure tem como padrão o valor da variável de ambiente INFORMIXDIR.

## Cursores roláveis

PDO_INFORMIX suporta cursores roláveis; no entanto, eles não estão habilitados por padrão. Para ativar o suporte ao cursor rolável, deve-se definir `ENABLESCROLLABLECURSORS=1` nas configurações de conexão ODBC correspondentes em odbc.ini ou passar a opção `EnableScrollableCursors=1` na string de conexão DSN.

# PDO_INFORMIX DSN

(PECL PDO_INFORMIX >= 0.1.0)

PDO_INFORMIX DSN — Conectando-se a bancos de dados Informix

### Descrição

O Nome da Fonte de Dados (DSN) do PDO_INFORMIX é baseado na string DSN ODBC do Informix. Detalhes sobre como configurar um DSN ODBC do Informix estão disponíveis no » Centro de informações do Informix Dynamic Server. Os principais componentes do DSN PDO_INFORMIX são:

DSN prefix

  O prefixo DSN é `informix:`.

DSN

  O DSN pode ser uma configuração de fonte de dados usando odbc.ini ou uma » string de conexão completa.

### Exemplos

Exemplo #1 Exemplo de DSN PDO_INFORMIX usando odbc.ini

O exemplo a seguir mostra um DSN PDO_INFORMIX para conexão a um banco de dados Informix catalogado como Infdrv33 em odbc.ini:

    $db = new PDO("informix:DSN=Infdrv33", "", "");

    [ODBC Data Sources]
    Infdrv33=INFORMIX 3.3 32-BIT

    [Infdrv33]
    Driver=/opt/informix/csdk_2.81.UC1G2/lib/cli/iclis09b.so
    Description=INFORMIX 3.3 32-BIT
    Database=common_db
    LogonID=usuario_teste
    pwd=senha_teste
    Servername=ids_server
    DB_LOCALE=en_US.819
    OPTIMIZEAUTOCOMMIT=1
    ENABLESCROLLABLECURSORS=1

Exemplo #2 Exemplo de DSN PDO_INFORMIX usando uma string de conexão

O exemplo a seguir mostra um DSN PDO_INFORMIX para conexão a um banco de dados Informix denominado `common_db` usando a sintaxe de string de conexão do Informix.

    $db = new PDO("informix:host=host.domain.com; service=9800;
        database=common_db; server=ids_server; protocol=onsoctcp;
        EnableScrollableCursors=1", "usuario_teste", "senha_teste");

## Índice

- PDO_INFORMIX DSN — Conectando-se a bancos de dados Informix

# Driver PDO do MySQL (PDO_MYSQL)

## Introdução

PDO_MYSQL é um driver que implementa a interface PHP Data Objects (PDO) para habilitar o acesso do PHP aos bancos de dados MySQL.

PDO_MYSQL utiliza as preparações emuladas por padrão.

MySQL 8

Ao executar uma versão de PHP anterior a 7.1.16, ou 7.2.4, defina o plugin padrão de senhas do Servidor MySQL 8 para mysql_native_password ou poderão surgir erros similares a The server requested authentication method unknown to the client [caching_sha2_password] mesmo quando caching_sha2_password não seja usado.

Isto acontece porque o padrão do MySQL 8 é caching_sha2_password, um plugin que não é reconhecido pelas versões antigas do PHP (mysqlnd). Portanto, altere o plugin configurando `default_authentication_plugin=mysql_native_password` no arquivo my.cnf. O plugin caching_sha2_password é totalmente suportado a partir do PHP 7.4.4. Para versões anteriores do PHP, a extensão mysql_xdevapi suporta o plugin.

Aviso

Cuidado: Alguns tipos de tabelas do MySQL (motores de armazenamento) não suportam transações. Ao escrever código para um banco de dados transacional onde o tipo de tabela não suporta transações, o MySQL irá entender que a transação foi inicializada com sucesso. Além disso, qualquer consulta DDL irá, de forma implícita, executar o "commit" para qualquer transação que esteja pendente.

> Nota:

> O driver MySQL não suporta adequadamente a opção `PDO::PARAM_INPUT_OUTPUT` através de PDOStatement::bindParam(); embora tais parâmetros possam ser usados, eles não são atualizados (isto é, a saída real é ignorada).

## Instalação

As distribuições Unix comuns incluem versões binárias do PHP que podem ser instaladas. Embora estas versões binárias são tipicamente compiladas com suporte a extensões MySQL, as bibliotecas das extensões em si podem precisar ser instaladas usando um pacote adicional. Verifique o gerenciador de pacote que vem com a distribuição sendo usada para disponibilidade desse pacote.

Por exemplo, no Ubuntu o pacote `php5-mysql` instala as extensões PHP ext/mysql, ext/mysqli e PDO_MYSQL. No CentOS, o pacote `php-mysql` também instala estas três extensões.

Alternativamente, o usuário pode compilar esta extensão por conta própria. Compilar o PHP direto da fonte permite especificar as extensões a serem utilizadas, assim como as bibliotecas clientes para cada extensão.

Ao compilar, use a opção --with-pdo-mysql[=DIR] para instalar a extensão PDO MySQL, onde o `[=DIR]` opcional é a localização da biblioteca base do MySQL. Mysqlnd é a biblioteca principal. Para detalher sobre a escolha de biblioteca, consulte a seção Escolhendo uma biblioteca MySQL.

Opcionalmente, --with-mysql-sock[=DIR] define a localização do ponteiro do soquete Unix MySQL para todas as extensões MySQL, incluindo a PDO_MYSQL. Se não especificada, as localizações padrão são pesquisadas.

Optionalmente, --with-zlib-dir[=DIR] é usada para definir o caminho da instalação da zlib.

    $ ./configure --with-pdo-mysql --with-mysql-sock=/var/mysql/mysql.sock

O suporte a SSL é habilitado usando as constantes `Pdo\Mysql::ATTR_SSL_*` apropriadas, que é o equivalente a chamar a » função mysql_ssl_set() da API C do MySQL. Além disso, o SSL não pode ser habilitado com PDO::setAttribute() porque a conexão já existirá. Consulte também a documentação do MySQL sobre » conexão ao MySQL com SSL.

## Constantes predefinidas

As constantes abaixo são definidas por este driver e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução. Além disso, estas constantes específicas do driver só devem ser usadas se este driver estiver sendo usado. Usar atributos específicos de um driver com outro driver pode resultar em comportamento inesperado. PDO::getAttribute() pode ser usada para obter o atributo `PDO::ATTR_DRIVER_NAME` para verificar o driver, se o código puder ser executado com vários drivers.

`PDO::MYSQL_ATTR_USE_BUFFERED_QUERY` (int)
  Sinônimo de `Pdo\Mysql::ATTR_USE_BUFFERED_QUERY`.
`PDO::MYSQL_ATTR_LOCAL_INFILE` (int)
  Sinônimo de `Pdo\Mysql::ATTR_LOCAL_INFILE`
`PDO::MYSQL_ATTR_LOCAL_INFILE_DIRECTORY` (int)
  Sinônimo de `Pdo\Mysql::ATTR_LOCAL_INFILE_DIRECTORY`. Disponível a partir do PHP 8.1.0.
`PDO::MYSQL_ATTR_INIT_COMMAND` (int)
  Sinônimo de `Pdo\Mysql::ATTR_INIT_COMMAND`.
`PDO::MYSQL_ATTR_READ_DEFAULT_FILE` (int)
  Sinônimo de `Pdo\Mysql::ATTR_READ_DEFAULT_FILE`.
`PDO::MYSQL_ATTR_READ_DEFAULT_GROUP` (int)
  Sinônimo de `Pdo\Mysql::ATTR_READ_DEFAULT_GROUP`.
`PDO::MYSQL_ATTR_MAX_BUFFER_SIZE` (int)
  Sinônimo de `Pdo\Mysql::ATTR_MAX_BUFFER_SIZE`.
`PDO::MYSQL_ATTR_DIRECT_QUERY` (bool)
  Sinônimo de `PDO::ATTR_EMULATE_PREPARES`. A partir do PHP 8.4.0, esta constante é tipada como bool; anteriormente, era tipada como int.
`PDO::MYSQL_ATTR_FOUND_ROWS` (int)
  Sinônimo de `Pdo\Mysql::ATTR_FOUND_ROWS`.
`PDO::MYSQL_ATTR_IGNORE_SPACE` (int)
  Sinônimo de `Pdo\Mysql::ATTR_IGNORE_SPACE`.
`PDO::MYSQL_ATTR_COMPRESS` (int)
  Sinônimo de `Pdo\Mysql::ATTR_COMPRESS`.
`PDO::MYSQL_ATTR_SERVER_PUBLIC_KEY` (int)
  Sinônimo de `Pdo\Mysql::ATTR_SERVER_PUBLIC_KEY`.
`PDO::MYSQL_ATTR_SSL_CA` (int)
  Sinônimo de `Pdo\Mysql::ATTR_SSL_CA`.
`PDO::MYSQL_ATTR_SSL_CAPATH` (int)
  Sinônimo de `Pdo\Mysql::ATTR_SSL_CAPATH`.
`PDO::MYSQL_ATTR_SSL_CERT` (int)
  Sinônimo de `Pdo\Mysql::ATTR_SSL_CERT`.
`PDO::MYSQL_ATTR_SSL_CIPHER` (int)
  Sinônimo de `Pdo\Mysql::ATTR_SSL_CIPHER`.
`PDO::MYSQL_ATTR_SSL_KEY` (int)
  Sinônimo de `Pdo\Mysql::ATTR_SSL_KEY`.
`PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT` (int)
  Sinônimo de `Pdo\Mysql::ATTR_SSL_VERIFY_SERVER_CERT`. Disponível a partir do PHP 7.0.18 e PHP 7.1.4.
`PDO::MYSQL_ATTR_MULTI_STATEMENTS` (int)
  Sinônimo de `Pdo\Mysql::ATTR_MULTI_STATEMENTS`.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de Configuração do PDO_MYSQL
Nome | Padrão | Modificável
--- | --- | ---
pdo_mysql.default_socket | "/tmp/mysql.sock" | `INI_SYSTEM`
pdo_mysql.debug | NULL | `INI_SYSTEM`

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`pdo_mysql.default_socket` string

  Define um soquete de domínio Unix. Este valor também pode ser definido no momento da compilação se um soquete de domínio puder ser encontrado durante o comando "configure". Esta configuração ini é apenas para sistemas baseados em Unix.

`pdo_mysql.debug` bool

  Habilita a depuração para o PDO_MYSQL. Esta configuração está disponível somente quando o PDO_MYSQL tiver sido compilado com a mysqlnd e em modo de depuração PDO.

# PDO_MYSQL DSN

(PECL PDO_MYSQL >= 0.1.0)

PDO_MYSQL DSN — Conectando a bancos de dados MySQL

### Descrição

O Data Source Name (DSN) do PDO_MYSQL é composto dos seguintes elementos:

Prefixo DSN

  O prefixo DSN é `mysql:`.

`host`

  O nome do servidor onde está o banco de dados.

`port`

  O número da porta onde o servidor do banco de dados está escutando.

`dbname`

  O nome do banco de dados.

`unix_socket`

  O soquete Unix do MySQL (não deve ser usado com `host` ou `port`).

`charset`

  O conjunto de caracteres. Veja a documentação sobre conjunto de caracteres para mais informação.

### Exemplos

Exemplo #1 Exemplos de DSN do PDO_MYSQL

O exemplo a seguir demonstra um DSN do PDO_MYSQL para conexão com banco de dados MySQL:

    mysql:host=localhost;dbname=testdb

Exemplos mais completos:

    mysql:host=localhost;port=3307;dbname=testdb
    mysql:unix_socket=/tmp/mysql.sock;dbname=testdb

### Notas

> Nota: Somente em Unix:

> Quando o nome do servidor é definido como `"localhost"`, a conexão ao servidor é feita através de um soquete de domínio. Se o PDO_MYSQL tiver sido compilado usando libmysqlclient, a localização do soquete é a mesma localização da compilação da libmysqlclient. Se o PDO_MYSQL foi compilado usando mysqlnd, um soquete padrão pode ser definido através da configuração pdo_mysql.default_socket.

## Índice

- PDO_MYSQL DSN — Conectando a bancos de dados MySQL

# A classe Pdo\Mysql

(PHP 8 >= 8.4.0)

## Introdução

Um subclasse PDO representando uma conexão que usa o driver PDO MySQL.

Este driver oferece suporte a um analisador de consulta SQL dedicado para o dialeto MySQL. Ele pode lidar com o seguinte:

- Literais entre aspas simples e duplas com duplicação e barra invertida como mecanismos de escape
- Literais entre acentos graves com duplicação como mecanismo de escape
- Dois travessões, comentários em estilo C e comentários em hash.

## Resumo da classe

class Pdo\Mysql extends PDO {
/* Constantes herdadas */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Constantes */
public const int ATTR_USE_BUFFERED_QUERY;
public const int ATTR_LOCAL_INFILE;
public const int ATTR_LOCAL_INFILE_DIRECTORY;
public const int ATTR_INIT_COMMAND;
public const int ATTR_MAX_BUFFER_SIZE;
public const int ATTR_READ_DEFAULT_FILE;
public const int ATTR_READ_DEFAULT_GROUP;
public const int ATTR_COMPRESS;
public const int ATTR_DIRECT_QUERY;
public const int ATTR_FOUND_ROWS;
public const int ATTR_IGNORE_SPACE;
public const int ATTR_MULTI_STATEMENTS;
public const int ATTR_SERVER_PUBLIC_KEY;
public const int ATTR_SSL_KEY;
public const int ATTR_SSL_CERT;
public const int ATTR_SSL_CA;
public const int ATTR_SSL_CAPATH;
public const int ATTR_SSL_CIPHER;
public const int ATTR_SSL_VERIFY_SERVER_CERT;
/* Métodos */
public function getWarningCount(): int
/* Métodos herdados */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Constantes predefinidas

`Pdo\Mysql::ATTR_USE_BUFFERED_QUERY`
  Por padrão, todas as instruções são executadas em modo buffer. Se este atributo estiver definido como `false` em um objeto Pdo\Mysql, o driver MySQL usará o modo sem buffer.

  Exemplo #1 Configurando o modo sem buffer do MySQL

      <?php
      $pdo = new Pdo\Mysql("mysql:host=localhost;dbname=world", 'my_user', 'my_password');
      $pdo->setAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY, false);

      $unbufferedResult = $pdo->query("SELECT Name FROM City");
      foreach ($unbufferedResult as $row) {
          echo $row['Name'] . PHP_EOL;
      }
      ?>

`Pdo\Mysql::ATTR_LOCAL_INFILE`
  Habilita `LOAD LOCAL INFILE`.

  > Nota: Só pode ser usado no array `driver_options` ao construir um novo identificador de banco de dados.

`Pdo\Mysql::ATTR_LOCAL_INFILE_DIRECTORY`
  Permite restringir o carregamento de LOCAL DATA a arquivos localizados neste diretório designado.

  > Nota: Só pode ser usado no array `driver_options` ao construir um novo identificador de banco de dados.

`Pdo\Mysql::ATTR_INIT_COMMAND`
  Comando a ser executado ao conectar-se ao servidor MySQL. Será reexecutado automaticamente ao reconectar.

  > Nota: Só pode ser usado no array `driver_options` ao construir um novo identificador de banco de dados.

`Pdo\Mysql::ATTR_READ_DEFAULT_FILE`
  Lê as opções do arquivo de opções nomeado em vez de my.cnf.

  > Nota: Esta opção não está disponível se mysqlnd for usado, porque o mysqlnd não lê os arquivos de configuração do mysql.

`Pdo\Mysql::ATTR_READ_DEFAULT_GROUP`
  Lê opções do grupo nomeado de my.cnf ou do arquivo especificado com `Pdo\Mysql::ATTR_READ_DEFAULT_FILE`.

  > Nota: Esta opção não está disponível se mysqlnd for usado, porque o mysqlnd não lê os arquivos de configuração do mysql.

`Pdo\Mysql::ATTR_COMPRESS`
  Ativa a compactação de comunicação de rede.
`Pdo\Mysql::ATTR_DIRECT_QUERY`
  Sinônimo de `PDO::ATTR_EMULATE_PREPARES`.
`Pdo\Mysql::ATTR_FOUND_ROWS`
  Retorna o número de linhas encontradas (correspondidas), não o número de linhas alteradas.

  > Nota: Só pode ser usado no array `driver_options` ao construir um novo identificador de banco de dados.

`Pdo\Mysql::ATTR_IGNORE_SPACE`
  Permite espaços após nomes de funções SQL. Torna todos os nomes de funções SQL palavras reservadas.

  > Nota: Só pode ser usado no array `driver_options` ao construir um novo identificador de banco de dados.

`Pdo\Mysql::ATTR_MAX_BUFFER_SIZE`
  Tamanho máximo do buffer. O padrão é 1 MiB.

  > Nota: Esta constante não é suportada quando compilada no mysqlnd.

`Pdo\Mysql::ATTR_MULTI_STATEMENTS`
  Desativa a execução de múltiplas consultas em PDO::prepare() e PDO::query() quando definido como `false`.

  > Nota: Só pode ser usado no array `driver_options` ao construir um novo identificador de banco de dados.

`Pdo\Mysql::ATTR_SERVER_PUBLIC_KEY`
  Arquivo de chave pública RSA usado com autenticação baseada em SHA-256.

  > Nota: Só pode ser usado no array `driver_options` ao construir um novo identificador de banco de dados.

`Pdo\Mysql::ATTR_SSL_KEY`
  O caminho do arquivo para a chave SSL.

  > Nota: Só pode ser usado no array `driver_options` ao construir um novo identificador de banco de dados.

`Pdo\Mysql::ATTR_SSL_CERT`
  O caminho do arquivo para o certificado SSL.

  > Nota: Só pode ser usado no array `driver_options` ao construir um novo identificador de banco de dados.

`Pdo\Mysql::ATTR_SSL_CA`
  O caminho do arquivo para a autoridade de certificação SSL.

  > Nota: Só pode ser usado no array `driver_options` ao construir um novo identificador de banco de dados.

`Pdo\Mysql::ATTR_SSL_CAPATH`
  O caminho do arquivo para o diretório que contém os certificados CA SSL confiáveis, que são armazenados no formato PEM.

  > Nota: Só pode ser usado no array `driver_options` ao construir um novo identificador de banco de dados.

`Pdo\Mysql::ATTR_SSL_CIPHER`
  Uma lista de uma ou mais cifras permitidas para uso na criptografia SSL, em um formato compreendido pelo OpenSSL. Por exemplo, `DHE-RSA-AES256-SHA:AES128-SHA`.

  > Nota: Só pode ser usado no array `driver_options` ao construir um novo identificador de banco de dados.

`Pdo\Mysql::ATTR_SSL_VERIFY_SERVER_CERT`
  Fornece uma maneira de desabilitar a verificação do certificado SSL do servidor.

  > Nota: Esta opção está disponível apenas com mysqlnd.

  > Nota: Só pode ser usado no array `driver_options` ao construir um novo identificador de banco de dados.

# Pdo\Mysql::getWarningCount

(PHP 8 >= 8.4.0)

Pdo\Mysql::getWarningCount — Retorna o número de alertas da última consulta executada

### Descrição

public function Pdo\Mysql::getWarningCount(): int

Retorna o número de alertas da última consulta executada.

> Nota: Para recuperar mensagens de alerta, o seguinte comando SQL pode ser usado: `SHOW WARNINGS [limit row_count]`, onde "row_count" é o número máximo de mensagens a serem retornadas.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um int representando o número de avisos gerados pela última consulta.

### Exemplos

Exemplo #1 Exemplo de Pdo\Mysql::getWarningCount()

    <?php

    $conn = PDO::connect("mysql:host=localhost;dbname=test;charset=utf8mb4", 'user', 'password');

    $conn->query('SELECT 42/0');
    if ($conn->getWarningCount() > 0) {
        $result = $conn->query("SHOW WARNINGS");
        $row = $result->fetch();
        printf("%s (%d): %s\n", $row[0], $row[1], $row[2]);
    }

    ?>

O exemplo acima produzirá:

    Warning (1365): Division by 0

## Índice

- Pdo\Mysql::getWarningCount — Retorna o número de alertas da última consulta executada

# Driver PDO do Microsoft SQL Server (PDO_SQLSRV)

## Introdução

PDO_SQLSRV é um driver que implementa a interface aos Objetos de Dados PHP (PDO) para permitir acesso do PHP a bancos de dados MS SQL Server (iniciando com o SQL Server 2005) e SQL Azure.

## Instalação

A versão mais recente do driver está disponível aqui: » SQLSRV. O código-fonte do driver está hospedado em um » repositório público.

Para mais informações sobre requisitos do sistema, consulte » Requisitos de Sistema para o SQLSRV.

No Windows, a extensão PDO_SQLSRV é habilitado pela adição dos arquivos DLL apropriados ao diretório de extensões do PHP e da entrada correspondente no arquivo php.ini.

No Linux e no macOS, a extensão PDO_SQLSRV pode ser instalada usando o » PECL. Consulte o » tutorial de instalação para detalhes.

## Constantes predefinidas

As constantes abaixo são definidas por este driver e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução. Além disso, estas constantes específicas do driver só devem ser usadas se este driver estiver sendo usado. Usar atributos específicos de um driver com outro driver pode resultar em comportamento inesperado. PDO::getAttribute() pode ser usada para obter o atributo `PDO::ATTR_DRIVER_NAME` para verificar o driver, se o código puder ser executado com vários drivers.

`PDO::SQLSRV_TXN_READ_UNCOMMITTED` (int)
  Essa constante é um valor aceitável para a chave TransactionIsolation do DSN SQLSRV. Esta constante define o nível de isolamento da transação para a conexão como Read Uncommitted.
`PDO::SQLSRV_TXN_READ_COMMITTED` (int)
  Essa constante é um valor aceitável para a chave TransactionIsolation do DSN SQLSRV. Esta constante define o nível de isolamento da transação para a conexão como Leitura Confirmada.
`PDO::SQLSRV_TXN_REPEATABLE_READ` (int)
  Essa constante é um valor aceitável para a chave TransactionIsolation do DSN SQLSRV. Esta constante define o nível de isolamento da transação para a conexão como Leitura Repetível.
`PDO::SQLSRV_TXN_SNAPSHOT` (int)
  Essa constante é um valor aceitável para a chave TransactionIsolation do DSN SQLSRV. Esta constante define o nível de isolamento da transação para a conexão como Snapshot.
`PDO::SQLSRV_TXN_SERIALIZABLE` (int)
  Essa constante é um valor aceitável para a chave TransactionIsolation do DSN SQLSRV. Esta constante define o nível de isolamento da transação para a conexão como Serializável.
`PDO::SQLSRV_ENCODING_BINARY` (int)
  Especifica que os dados são enviados/recuperados como um fluxo de bytes brutos de/para o servidor sem realizar codificação ou tradução. Essa constante pode ser passada para PDOStatement::setAttribute, PDO::prepare, PDOStatement::bindColumn e PDOStatement::bindParam.
`PDO::SQLSRV_ENCODING_SYSTEM` (int)
  Especifica que os dados são enviados/recuperados de/para o servidor como caracteres de 8 bits, conforme especificado na página de código da localidade do Windows definida no sistema. Quaisquer caracteres multibyte ou caracteres que não sejam mapeados nesta página de códigos serão substituídos por um caractere de ponto de interrogação (?) de byte único. Essa constante pode ser passada para PDOStatement::setAttribute, PDO::setAttribute, PDO::prepare, PDOStatement::bindColumn e PDOStatement::bindParam.
`PDO::SQLSRV_ENCODING_UTF8` (int)
  Especifica que os dados são enviados/recuperados de/para o servidor na codificação UTF-8. Esta é a codificação padrão. Essa constante pode ser passada para PDOStatement::setAttribute, PDO::setAttribute, PDO::prepare, PDOStatement::bindColumn e PDOStatement::bindParam.
`PDO::SQLSRV_ENCODING_DEFAULT` (int)
  Especifica que os dados são enviados/recuperados de/para o servidor de acordo com PDO::SQLSRV_ENCODING_SYSTEM se especificado durante a conexão. A codificação da conexão é usada se especificada em uma instrução de preparação. Essa constante pode ser passada para PDOStatement::setAttribute, PDO::setAttribute, PDO::prepare, PDOStatement::bindColumn e PDOStatement::bindParam.
`PDO::SQLSRV_ATTR_QUERY_TIMEOUT` (int)
  Um número inteiro não negativo que representa o período de tempo limite, em segundos. Zero (0) é o padrão e significa que não há tempo limite. Essa constante pode ser passada para PDOStatement::setAttribute, PDO::setAttribute e PDO::prepare.
`PDO::SQLSRV_ATTR_DIRECT_QUERY` (int)
  Indica que uma instrução deve ser executada diretamente, sem estar preparada. Essa constante pode ser passada para PDO::setAttribute e PDO::prepare. Para obter mais informações, consulte » Execução de instrução direta e preparada.

# PDO_SQLSRV DSN

(PECL pdo_sqlsrv >= 2.0.1)

PDO_SQLSRV DSN — Conectando-se aos bancos de dados MS SQL Server e SQL Azure

### Descrição

O Nome da Fonte de Dados (DSN) PDO_SQLSRV é composto pelos seguintes elementos:

DSN prefix

  O prefixo DSN é `sqlsrv:`.

`APP`
  O nome da aplicação usada no rastreamento.
`ConnectionPooling`
  Especifica se a conexão é atribuída a partir de um grupo de conexões (1 ou `true`) ou não (0 ou `false`).
`Database`
  O nome do banco de dados.
`Encrypt`
  Especifica se a comunicação com o SQL Server é criptografada (1 ou `true`) ou não criptografada (0 ou `false`).
`Failover_Partner`
  Especifica o servidor e a instância do espelho do banco de dados (se habilitado e configurado) a serem usados ​​quando o servidor primário estiver indisponível.
`LoginTimeout`
  Especifica o número de segundos de espera antes de falhar a tentativa de conexão.
`MultipleActiveResultSets`
  Desativa ou ativa explicitamente o suporte para Conjuntos de Resultados Ativos Múltiplos (MARS).
`QuotedId`
  Especifica se devem ser usadas regras SQL-92 para identificadores entre aspas (1 ou `true`) ou regras Transact-SQL legadas (0 ou `false`).
`Server`
  O nome do servidor de banco de dados.
`TraceFile`
  Especifica o caminho do arquivo usado para dados de rastreamento.
`TraceOn`
  Especifica se o rastreamento ODBC está habilitado (1 ou `true`) ou desabilitado (0 ou `false`) para a conexão que está sendo estabelecida.
`TransactionIsolation`
  Especifica o nível de isolamento da transação. Os valores aceitos para esta opção são PDO::SQLSRV_TXN_READ_UNCOMMITTED, PDO::SQLSRV_TXN_READ_COMMITTED, PDO::SQLSRV_TXN_REPEATABLE_READ, PDO::SQLSRV_TXN_SNAPSHOT e PDO::SQLSRV_TXN_SERIALIZABLE.
`TrustServerCertificate`
  Especifica se o cliente deve confiar (1 ou `true`) ou rejeitar (0 ou `false`) um certificado de servidor autoassinado.
`WSID`
  Especifica o nome do computador para rastreamento.

### Exemplos

Exemplo #1 Exemplos de DSN PDO_SQLSRV

O exemplo a seguir mostra como se conectar a um banco de dados MS SQL Server especificado:

    $c = new PDO("sqlsrv:Server=localhost;Database=db_teste", "NomeUsuario", "Senha");

O exemplo a seguir mostra como conectar-se a um banco de dados MS SQL Server em uma porta especificada:

    $c = new PDO("sqlsrv:Server=localhost,1521;Database=db_teste", "NomeUsuario", "Senha");

O exemplo a seguir mostra como se conectar a um banco de dados SQL Azure com ID de servidor 12345abcde. Observe que quando há uma conexão ao SQL Azure com PDO, o nome de usuário será NomeUsuario@12345abcde (NomeUsuario@IdServidor).

    $c = new PDO("sqlsrv:Server=12345abcde.database.windows.net;Database=db_teste", "NomeUsuario@12345abcde", "Senha");

## Índice

- PDO_SQLSRV DSN — Conectando-se aos bancos de dados MS SQL Server e SQL Azure

# Driver PDO do Oracle (PDO_OCI)

## Instalação

Se o banco de dados Oracle estiver na mesma máquina que o PHP, o software de banco de dados já contém as bibliotecas necessárias. Quando o PHP estiver em uma máquina diferente, use as bibliotecas gratuitas » Oracle Instant Client. Para obter detalhes, consulte a seção Requisitos do OCI8.

## PHP 8.4

Esta extensão foi movida para o repositório » PECL e não é mais distribuída com o PHP desde a versão 8.4.0

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/PDO_OCI.

## PHP < 8.4

Use --with-pdo-oci[=DIR] para instalar a extensão PDO Oracle OCI, onde o `[=DIR]` opcional é o diretório base do Oracle. O padrão de `[=DIR]` é a variável de ambiente $ORACLE_HOME.

Use --with-pdo-oci=instantclient,prefix,version para um SDK do Oracle Instant Client, onde o prefixo e a versão são configurados.

    // Usando $ORACLE_HOME
    $ ./configure --with-pdo-oci

    // Usando OIC para Linux com RPMs 10.2.0.3 e prefixo /usr
    $ ./configure --with-pdo-oci=instantclient,/usr,10.2.0.3

## Constantes predefinidas

As constantes abaixo são definidas por este driver e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução. Além disso, estas constantes específicas do driver só devem ser usadas se este driver estiver sendo usado. Usar atributos específicos de um driver com outro driver pode resultar em comportamento inesperado. PDO::getAttribute() pode ser usada para obter o atributo `PDO::ATTR_DRIVER_NAME` para verificar o driver, se o código puder ser executado com vários drivers.

`PDO::OCI_ATTR_ACTION` (int)

  Fornece uma maneira de especificar a ação na sessão do banco de dados.

  Isto existe a partir do PHP 7.2.16 e 7.3.3

`PDO::OCI_ATTR_CLIENT_INFO` (int)

  Fornece uma maneira de especificar as informações do cliente na sessão do banco de dados.

  Isto existe a partir do PHP 7.2.16 e 7.3.3

`PDO::OCI_ATTR_CLIENT_IDENTIFIER` (int)

  Fornece uma maneira de especificar o identificador do cliente na sessão do banco de dados.

  Isto existe a partir do PHP 7.2.16 e 7.3.3

`PDO::OCI_ATTR_MODULE` (int)

  Fornece uma maneira de especificar o módulo na sessão do banco de dados.

  Isto existe a partir do PHP 7.2.16 e 7.3.3

# PDO_OCI DSN

(PECL PDO_OCI >= 0.1.0)

PDO_OCI DSN — Conectando-se a bancos de dados Oracle

### Descrição

O Nome da Fonte de Dados (DSN) PDO_OCI é composto pelos seguintes elementos:

DSN prefix

  O prefixo DSN é `oci:`....

`dbname` (Oracle Instant Client)

  O URI para a conexão do Oracle Instant Client assume o formato `dbname=//hostname:port-number/database`. Se for feita uma conexão um banco de dados definido em tnsnames.ora, apenas o nome do banco de dados deve ser usado: `dbname=database`.

`charset`

  O conjunto de caracteres do lado do cliente para o identificador do ambiente atual.

### Exemplos

Exemplo #1 Exemplos de DSN PDO_OCI

Os exemplos a seguir mostram um DSN PDO_OCI para conexão com bancos de dados Oracle:

    // Conecta a um banco de dados definido em tnsnames.ora
    oci:dbname=mydb

    // Conecta usando o Oracle Instant Client
    oci:dbname=//localhost:1521/mydb

## Índice

- PDO_OCI DSN — Conectando-se a bancos de dados Oracle

# Driver PDO do ODBC e do DB2 (PDO_ODBC)

## Introdução

PDO_ODBC é um driver que implementa a interface aos Objetos de Dados PHP (PDO) para permitir acesso do PHP a bancos de dados através de drivers ODBC ou através da biblioteca IBM DB2 Call Level Interface (DB2 CLI). O PDO_ODBC atualmente suporta três diferentes "sabores" de drivers de banco de dados:

ibm-db2

  Suporta acesso aos servidores IBM DB2 Universal Database, Cloudscape e Apache Derby por meio do cliente DB2 express-C gratuito.

unixODBC

  Suporta acesso a servidores de banco de dados por meio do gerenciador de driver unixODBC e dos próprios drivers ODBC do banco de dados.

generic

  Oferece uma opção de compilação para gerenciadores de driver ODBC que não são explicitamente suportados por PDO_ODBC.

No Windows, php_pdo_odbc.dll deve estar habilitado como extensão no php.ini. Ele está vinculado ao Windows ODBC Driver Manager para que o PHP possa se conectar a qualquer banco de dados catalogado como um DSN de sistema.

## Instalação

PDO_ODBC em sistemas UNIX

1. PDO_ODBC está incluído no código-fonte do PHP. Pode-se compilar a extensão PDO_ODBC como um módulo estático ou compartilhado usando os seguintes comandos configure.

   ibm_db2

         ./configure --with-pdo-odbc=ibm-db2,/opt/IBM/db2/V8.1/

     Para construir o PDO_ODBC com o tipo ibm-db2, é necessário ter os cabeçalhos de desenvolvimento do aplicativo DB2 instalados previamente na mesma máquina em que o PDO_ODBC estiver sendo compilado. Os cabeçalhos de desenvolvimento de aplicativos DB2 são uma opção instalável nos servidores DB2 e também estão disponíveis como parte do DB2 Application Development Client, gratuitamente no » site do IBM developerWorks.

     Se não for informado um local para as bibliotecas e cabeçalhos do DB2 para o comando configure, o PDO_ODBC usará o caminho padrão /home/db2inst1/sqllib.

   unixODBC

         ./configure --with-pdo-odbc=unixODBC,/usr/local

     Se não for informado um local para as bibliotecas e cabeçalhos unixODBC para o comando configure, o PDO_ODBC usará o caminho padrão /usr/local.
   generic

         ./configure --with-pdo-odbc=generic,/usr/local,libname,ldflags,cflags

## Constantes predefinidas

As constantes abaixo são definidas por este driver e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução. Além disso, estas constantes específicas do driver só devem ser usadas se este driver estiver sendo usado. Usar atributos específicos de um driver com outro driver pode resultar em comportamento inesperado. PDO::getAttribute() pode ser usada para obter o atributo `PDO::ATTR_DRIVER_NAME` para verificar o driver, se o código puder ser executado com vários drivers.

`PDO_ODBC_TYPE` (string)

`PDO::ODBC_ATTR_USE_CURSOR_LIBRARY` (int)
  Sinônimo de `Pdo\Odbc::ATTR_USE_CURSOR_LIBRARY`.
`PDO::ODBC_SQL_USE_IF_NEEDED` (int)
  Sinônimo de `Pdo\Odbc::SQL_USE_IF_NEEDED`.
`PDO::ODBC_SQL_USE_DRIVER` (int)
  Sinônimo de `Pdo\Odbc::SQL_USE_DRIVER`.
`PDO::ODBC_SQL_USE_ODBC` (int)
  Sinônimo de `Pdo\Odbc::SQL_USE_ODBC`.
`PDO::ODBC_ATTR_ASSUME_UTF8` (bool)
  Sinônimo de `Pdo\Odbc::ATTR_ASSUME_UTF8`.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de Configuração do PDO_ODBC
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
pdo_odbc.connection_pooling | "strict" | `INI_ALL` |
pdo_odbc.db2_instance_name | NULL | `INI_SYSTEM` | Este recurso descontinuado será certamente removido no futuro.

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`pdo_odbc.connection_pooling` string

  Informa se as conexões ODBC devem ser agrupadas. Pode ser `"strict"`, `"relaxed"` ou `"off"` (igual a `""`). O parâmetro descreve quão rigoroso o gerenciador de conexões deve ser ao comparar parâmetros de conexão com conexões agrupadas existentes. `strict` é o padrão recomendado e resultará no uso de conexões em cache somente quando todos os parâmetros de conexão tiverem correspondência exata. `relaxed` resultará no uso de conexões em cache quando parâmetros de conexão semelhantes forem usados. Isso pode resultar no aumento do uso do cache, correndo o risco de sangrar informações de conexão entre (por exemplo) servidores virtuais.

  Esta configuração só pode ser alterada no arquivo php.ini e afeta todo o processo; quaisquer outros módulos carregados no processo que usem as mesmas bibliotecas ODBC também serão afetados, incluindo a extensão ODBC unificada.

  Aviso

  A correspondência `relaxed` não deve ser usada em um servidor compartilhado, por motivos de segurança.

  Dica

  Esta configuração deve ser mantida na configuração padrão `strict` a menos que exista um bom motivo para alterá-la.

`pdo_odbc.db2_instance_name` string

  Se você o PDO_ODBC for compilado usando o tipo `db2`, esta configuração definirá o valor da variável de ambiente DB2INSTANCE nos sistemas operacionais Linux e UNIX para o nome especificado da instância do DB2. Isso permite que o PDO_ODBC resolva o local das bibliotecas DB2 e estabeleça conexões catalogadas com bancos de dados DB2.

  Esta configuração só pode ser alterada no arquivo php.ini e afeta todo o processo; quaisquer outros módulos carregados no processo que usem as mesmas bibliotecas ODBC também serão afetados, incluindo a extensão ODBC unificada.

  Esta configuração não tem efeito no Windows.

# PDO_ODBC DSN

(PECL PDO_ODBC >= 0.1.0)

PDO_ODBC DSN — Conectando-se a bancos de dados ODBC ou DB2

### Descrição

O Nome da Fonte de Dados (DSN) PDO_ODBC é composto pelos seguintes elementos:

Prefixo DSN

  O prefixo DSN é `odbc:`. Se estiver sendo feita uma conexão a um banco de dados catalogado no gerenciador de driver ODBC ou no catálogo do DB2, pode-se anexar o nome catalogado do banco de dados ao DSN.

DSN

  O nome do banco de dados conforme catalogado no gerenciador de driver ODBC ou no catálogo do DB2. Como alternativa, pode-se fornecer uma string de conexão ODBC completa para conectar-se a um banco de dados, conforme descrito em » http://www.connectionstrings.com/.

`UID`

  O nome do usuário para a conexão. Se for especificado o nome de usuário no DSN, o PDO ignorará o valor do argumento do nome de usuário no construtor do PDO.

`PWD`

  A senha do usuário para a conexão. Se for especificada a senha no DSN, o PDO ignorará o valor do argumento de senha no construtor do PDO.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Ao passar uma string vazia para o argumento de senha no construtor PDO, `pwd` não era incluído na string de conexão criada até agora, mas o comportamento foi alterado para incluí-lo como uma string vazia. Passando `null` para o argumento de senha no construtor PDO resulta no mesmo comportamento de antes.
8.4.0 | Alterado o comportamento para ignorar o argumento do nome de usuário e o argumento da senha no construtor PDO separadamente quando o DSN contém `uid` ou `pwd`. Anteriormente, se incluído apenas `uid` ou `pwd` no DSN, tanto o argumento do nome de usuário quanto o argumento da senha no construtor PDO eram ignorados.

### Exemplos

Exemplo #1 Exemplo de PDO_ODBC DSN (gerenciador de driver ODBC)

O exemplo a seguir mostra um DSN PDO_ODBC para conexão a um banco de dados ODBC catalogado como testdb no gerenciador de driver ODBC:

    odbc:testdb

Exemplo #2 Exemplo de DSN PDO_ODBC (conexão não catalogada do IBM DB2)

O exemplo a seguir mostra um DSN PDO_ODBC para conexão a um banco de dados IBM DB2 denominado `SAMPLE` usando a sintaxe DSN ODBC completa:

    odbc:DRIVER={IBM DB2 ODBC DRIVER};HOSTNAME=localhost;PORT=50000;DATABASE=SAMPLE;PROTOCOL=TCPIP;UID=db2inst1;PWD=ibmdb2;

Exemplo #3 Exemplo de PDO_ODBC DSN (conexão não catalogada do Microsoft Access)

O exemplo a seguir mostra um DSN PDO_ODBC para conexão a um banco de dados Microsoft Access armazenado em `C:\db.mdb` usando a sintaxe DSN ODBC completa:

    odbc:Driver={Microsoft Access Driver (*.mdb)};Dbq=C:\\db.mdb;Uid=Admin

## Índice

- PDO_ODBC DSN — Conectando-se a bancos de dados ODBC ou DB2

# A classe Pdo\Odbc

(PHP 8 >= 8.4.0)

## Introdução

Uma subclasse PDO representando uma conexão que usa o driver PDO ODBC.

## Resumo da classe

namespace Pdo;
class Odbc extends PDO {
/* Constantes herdadas */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Constantes */
public const int ATTR_USE_CURSOR_LIBRARY;
public const int ATTR_ASSUME_UTF8;
public const int SQL_USE_IF_NEEDED;
public const int SQL_USE_DRIVER;
public const int SQL_USE_ODBC;
/* Métodos herdados */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Constantes predefinidas

`Pdo\Odbc::ATTR_USE_CURSOR_LIBRARY`

  Esta opção controla se a biblioteca de cursores ODBC é usada. A biblioteca de cursores ODBC oferece suporte a alguns recursos ODBC avançados (por exemplo, cursores roláveis ​​em bloco), que podem não ser implementados pelo driver. Os seguintes valores são suportados:

  `Pdo\Odbc::SQL_USE_IF_NEEDED`
    Usa a biblioteca de cursores ODBC quando necessário. Este é o padrão.
  `Pdo\Odbc::SQL_USE_DRIVER`
    Nunca usa a biblioteca de cursores ODBC.
  `Pdo\Odbc::SQL_USE_ODBC`
    Sempre usa a biblioteca de cursores ODBC.
`Pdo\Odbc::ATTR_ASSUME_UTF8`
  Somente Windows. Se `true`, os dados de caracteres codificados em UTF-16 (`CHAR`, `VARCHAR` e `LONGVARCHAR`) serão convertidos para UTF-8 ao ler ou gravar dados no banco de dados. Se `false` (o padrão), a conversão da codificação de caracteres pode ser feita pelo driver.

# Driver PDO do PostgreSQL (PDO_PGSQL)

## Introdução

PDO_PGSQL é um driver que implementa a interface PHP Data Objects (PDO) para permitir o acesso do PHP aos bancos de dados PostgreSQL.

## Tipos de Recurso

Esta extensão define um recurso de fluxo retornado por Pdo\Pgsql::lobOpen().

## Instalação

Use --with-pdo-pgsql[=DIR] para instalar a extensão PDO PostgreSQL, onde o opcional `[=DIR]` é o diretório base de instalação do PostgreSQL ou o caminho para pg_config.

    $ ./configure --with-pdo-pgsql

## Constantes predefinidas

As constantes abaixo são definidas por este driver e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução. Além disso, estas constantes específicas do driver só devem ser usadas se este driver estiver sendo usado. Usar atributos específicos de um driver com outro driver pode resultar em comportamento inesperado. PDO::getAttribute() pode ser usada para obter o atributo `PDO::ATTR_DRIVER_NAME` para verificar o driver, se o código puder ser executado com vários drivers.

`PDO::PGSQL_ATTR_DISABLE_PREPARES` (int)
  Sinônimo de `Pdo\Pgsql::ATTR_DISABLE_PREPARES`. A partir do PHP 8.5.0, esta constante está descontinuada.
`PDO::PGSQL_TRANSACTION_IDLE` (int)
  Equivalente a `Pdo\Pgsql::TRANSACTION_IDLE`. A partir do PHP 8.5.0, esta constante está descontinuada, pois não tem efeito.
`PDO::PGSQL_TRANSACTION_ACTIVE` (int)
  Equivalente a `Pdo\Pgsql::TRANSACTION_ACTIVE`. A partir do PHP 8.5.0, esta constante está descontinuada, pois não tem efeito.
`PDO::PGSQL_TRANSACTION_INTRANS` (int)
  Equivalente a `Pdo\Pgsql::TRANSACTION_INTRANS`. A partir do PHP 8.5.0, esta constante está descontinuada, pois não tem efeito.
`PDO::PGSQL_TRANSACTION_INERROR` (int)
  Equivalente a `Pdo\Pgsql::TRANSACTION_INERROR`. A partir do PHP 8.5.0, esta constante está descontinuada, pois não tem efeito.
`PDO::PGSQL_TRANSACTION_UNKNOWN` (int)
  Equivalente a `Pdo\Pgsql::TRANSACTION_UNKNOWN`. A partir do PHP 8.5.0, esta constante está descontinuada, pois não tem efeito.

## Notas gerais

> Nota: As colunas `bytea` são retornadas como recursos de fluxo. Consulte Objetos Grandes (LOBs) para entender como é a leitura destes valores e como vincular dados com `PDO::PARAM_LOB`.

# PDO_PGSQL DSN

(PHP 5 >= 5.1.0, PHP 7, PECL PDO_PGSQL >= 0.1.0)

PDO_PGSQL DSN — Conectando-se a bancos de dados PostgreSQL

### Descrição

O nome da fonte de dados (DSN) PDO_PGSQL é composto pelos seguintes elementos, delimitados por espaços ou ponto e vírgula:

DSN prefix

  O prefixo DSN é `pgsql:`.

`host`

  O nome do host no qual o servidor de banco de dados reside.

`port`

  A porta na qual o servidor de banco de dados está sendo executado.

`dbname`

  O nome do banco de dados.

`user`

  O nome do usuário para a conexão. Se você especificar o nome do usuário no DSN, o PDO ignorará o valor do argumento do nome do usuário no construtor do PDO.

`password`

  A senha do usuário para a conexão. Se você especificar a senha no DSN, o PDO ignorará o valor do argumento de senha no construtor do PDO.

`sslmode`
  O modo SSL. Os valores aceitos são `disable`, `allow`, `prefer`, `require`, `verify-ca` e `verify-full`; seus significados estão listados na » Documentação do PostgreSQL. Muitos serviços hospedados do PostgreSQL requerem uma conexão criptogradada, portanto `require` ou um modo mais estrito é necessário para conexão a eles.

> Nota: Todos os pontos e vírgulas na string DSN são substituídos por espaços, porque o PostgreSQL espera esse formato. Isso implica que pontos e vírgulas em qualquer um dos componentes (por exemplo, `password` ou `dbname`) não são suportados.

### Exemplos

Exemplo #1 Exemplos de DSN PDO_PGSQL

O exemplo a seguir mostra um DSN PDO_PGSQL para conexão a um banco de dados PostgreSQL:

    pgsql:host=localhost;port=5432;dbname=testdb;user=bruce;password=mypass

O exemplo a seguir mostra um DSN PDO_PGSQL para conexão a um banco de dados PostgreSQL via soquete unix /tmp/.s.PGSQL.5432:

    pgsql:host=/tmp;port=5432;dbname=testdb;user=bruce;password=mypass

# PDO::pgsqlCopyFromArray

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyFromArray — Sinônimo de Pdo\Pgsql::copyFromArray()

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.5.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
public function PDO::pgsqlCopyFromArray(
string `$tableName`,
array|Traversable `$rows`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = null
): bool

Este método é um apelido para: Pdo\Pgsql::copyFromArray().

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | O parâmetro `rows` agora aceita um Traversable; anteriormente somente um array era aceito.

# PDO::pgsqlCopyFromFile

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyFromFile — Sinônimo de Pdo\Pgsql::copyFromFile()

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.5.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
public function PDO::pgsqlCopyFromFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = null
): bool

Este método é um apelido para: Pdo\Pgsql::copyFromFile().

# PDO::pgsqlCopyToArray

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyToArray — Sinônimo de Pdo\Pgsql::copyToArray()

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.5.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
public function PDO::pgsqlCopyToArray(
string `$tableName`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = null
): array|false

Este método é um apelido para: Pdo\Pgsql::copyToArray().

# PDO::pgsqlCopyToFile

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyToFile — Sinônimo de Pdo\Pgsql::copyToFile()

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.5.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
public function PDO::pgsqlCopyToFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = null
): bool

Este método é um apelido para: Pdo\Pgsql::copyToFile().

# PDO::pgsqlGetNotify

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

PDO::pgsqlGetNotify — Sinônimo de Pdo\Pgsql::getNotify()

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.5.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
public function PDO::pgsqlGetNotify(int `$fetchMode` = PDO::FETCH_DEFAULT, int `$timeoutMilliseconds` = 0): array|false

Este método é um apelido para: Pdo\Pgsql::getNotify().

# PDO::pgsqlGetPid

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

PDO::pgsqlGetPid — Sinônimo de Pdo\Pgsql::getPid()

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.5.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
public function PDO::pgsqlGetPid(): int

Este método é um apelido para: Pdo\Pgsql::getPid().

# PDO::pgsqlLOBCreate

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL pdo_pgsql >= 1.0.2)

PDO::pgsqlLOBCreate — Sinônimo de Pdo\Pgsql::lobCreate()

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.5.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
public function PDO::pgsqlLOBCreate(): string

Este método é um apelido para: Pdo\Pgsql::lobCreate().

# PDO::pgsqlLOBOpen

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL pdo_pgsql >= 1.0.2)

PDO::pgsqlLOBOpen — Sinônimo de Pdo\Pgsql::lobOpen()

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.5.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
public function PDO::pgsqlLOBOpen(string `$oid`, string `$mode` = "rb"): resource|false

Este método é um apelido para: Pdo\Pgsql::lobOpen().

# PDO::pgsqlLOBUnlink

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL pdo_pgsql >= 1.0.2)

PDO::pgsqlLOBUnlink — Sinônimo de Pdo\Pgsql::lobUnlink()

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.5.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
public function PDO::pgsqlLOBUnlink(string `$oid`): bool

Este método é um apelido para: Pdo\Pgsql::lobUnlink().

## Índice

- PDO_PGSQL DSN — Conectando-se a bancos de dados PostgreSQL
- PDO::pgsqlCopyFromArray — Sinônimo de Pdo\Pgsql::copyFromArray
- PDO::pgsqlCopyFromFile — Sinônimo de Pdo\Pgsql::copyFromFile
- PDO::pgsqlCopyToArray — Sinônimo de Pdo\Pgsql::copyToArray
- PDO::pgsqlCopyToFile — Sinônimo de Pdo\Pgsql::copyToFile
- PDO::pgsqlGetNotify — Sinônimo de Pdo\Pgsql::getNotify
- PDO::pgsqlGetPid — Sinônimo de Pdo\Pgsql::getPid
- PDO::pgsqlLOBCreate — Sinônimo de Pdo\Pgsql::lobCreate
- PDO::pgsqlLOBOpen — Sinônimo de Pdo\Pgsql::lobOpen
- PDO::pgsqlLOBUnlink — Sinônimo de Pdo\Pgsql::lobUnlink

# A classe Pdo\Pgsql

(PHP 8 >= 8.4.0)

## Introdução

Uma subclasse PDO representando uma conexão que usa o driver PDO PostgreSQL.

Este driver oferece suporte a um analisador de consulta SQL dedicado para o dialeto PostgreSQL. Ele pode lidar com o seguinte:

- Literais entre aspas simples e duplas, com duplicação como mecanismo de escape
- Literais de string de “escape” estilo C
- Literais de string entre cifrões
- Comentários com dois traços e estilo C (não aninhados).
- Suporte para `??` como sequência de escape para o operador `?`.

## Resumo da classe

namespace Pdo;
class Pgsql extends PDO {
/* Constantes herdadas */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Constantes */
public const int ATTR_DISABLE_PREPARES;
public const int ATTR_RESULT_MEMORY_SIZE;
public const int TRANSACTION_IDLE;
public const int TRANSACTION_ACTIVE;
public const int TRANSACTION_INTRANS;
public const int TRANSACTION_INERROR;
public const int TRANSACTION_UNKNOWN;
/* Métodos */
public function copyFromArray(
string `$tableName`,
array|Traversable `$rows`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool
public function copyFromFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool
public function copyToArray(
string `$tableName`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): array|false
public function copyToFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool
public function escapeIdentifier(string `$input`): string
public function getNotify(int `$fetchMode` = `PDO::FETCH_DEFAULT`, int `$timeoutMilliseconds` = 0): array|false
public function getPid(): int
public function lobCreate(): string|false
public function lobOpen(string `$oid`, string `$mode` = "rb"): resource|false
public function lobUnlink(string `$oid`): bool
public function setNoticeCallback(?callable `$callback`): void
/* Métodos herdados */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Constantes predefinidas

`Pdo\Pgsql::ATTR_DISABLE_PREPARES`
  Envia a consulta e os parâmetros ao servidor juntos em uma única chamada, evitando a necessidade de criar uma instrução preparada nomeada separadamente. Se a consulta for executada apenas uma vez, isso poderá reduzir a latência, evitando uma viagem de ida e volta desnecessária ao servidor.
`Pdo\Pgsql::ATTR_RESULT_MEMORY_SIZE`
  Retorna a quantidade de memória, em bytes, alocada para a instância especificada do resultado da consulta PDOStatement ou `null` se não existirem resultados antes da consulta ser executada.
`PDO::ATTR_PREFETCH`
  A partir do PHP 8.5.0, definir este atributo como `0` habilita a busca lenta (linha única): as linhas são recuperadas do servidor uma de cada vez à medida que são buscadas, em vez de armazenar em buffer todo o conjunto de resultados na memória antes da primeira chamada a PDOStatement::fetch(). Isso reduz o uso de memória para conjuntos grandes de resultados. Qualquer outro valor mantém o comportamento padrão de buffer. Pode ser definido para cada conexão com PDO::setAttribute(), ou por instrução através das opções de driver PDO::prepare() ou PDO::query().
  Cuidado

  No modo lento, uma conexão pode ter apenas uma instrução ativa por vez. A execução de outra instrução descarta silenciosamente quaisquer linhas não lidas da anterior; nenhum erro é gerado.

`Pdo\Pgsql::TRANSACTION_IDLE`
  Aviso

  Esta constante não tem efeito e foi descontinuada a partir do PHP 8.5.0.

`Pdo\Pgsql::TRANSACTION_ACTIVE`
  Aviso

  Esta constante não tem efeito e foi descontinuada a partir do PHP 8.5.0.

`Pdo\Pgsql::TRANSACTION_INTRANS`
  Aviso

  Esta constante não tem efeito e foi descontinuada a partir do PHP 8.5.0.

`Pdo\Pgsql::TRANSACTION_INERROR`
  Aviso

  Esta constante não tem efeito e foi descontinuada a partir do PHP 8.5.0.

`Pdo\Pgsql::TRANSACTION_UNKNOWN`
  Aviso

  Esta constante não tem efeito e foi descontinuada a partir do PHP 8.5.0.

# Pdo\Pgsql::copyFromArray

(PHP 8 >= 8.4.0)

Pdo\Pgsql::copyFromArray — Copia dados de um array PHP para uma tabela

### Descrição

public function Pdo\Pgsql::copyFromArray(
string `$tableName`,
array|Traversable `$rows`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

Copia dados do array `rows` para a tabela `tableName` usando `separator` como delimitador de campos e uma lista de campos no parâmetro `fields`.

### Parâmetros

`tableName`
  String contendo o nome da tabela.
`rows`
  Um array indexado (ou Traversable) de strings com campos separados por `separator`.
`separator`
  Delimitador usado para separar campos em uma entrada do array `rows`.
`nullAs`
  Como interpretar valores SQL `NULL`.
`fields`
  Lista de campos a serem inseridos.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | `rows` agora aceira um Traversable; anteriormente somente um array era aceito.

### Exemplos

Exemplo #1 Exemplo de Pdo\Pgsql::copyFromArray()

Cada elemento de `rows` é um registro cujos campos são conectados por `separator` (uma tabulação por padrão).

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $db->exec('CREATE TABLE fruits (id int, name text, qty int)');

    $rows = [
        "1\tapple\t10",
        "2\tbanana\t20",
        "3\tcherry\t30",
    ];
    $db->copyFromArray('fruits', $rows);

    foreach ($db->query('SELECT * FROM fruits ORDER BY id') as $row) {
        echo "{$row['id']} {$row['name']} {$row['qty']}\n";
    }
    ?>

O exemplo acima produzirá:

    1 apple 10
    2 banana 20
    3 cherry 30

### Veja Também

- Pdo\Pgsql::copyToArray() - Copia dados da tabela do banco de dados para o array PHP
- Pdo\Pgsql::copyFromFile() - Copia dados do arquivo para a tabela
- Pdo\Pgsql::copyToFile() - Copia dados da tabela para arquivo

# Pdo\Pgsql::copyFromFile

(PHP 8 >= 8.4.0)

Pdo\Pgsql::copyFromFile — Copia dados do arquivo para a tabela

### Descrição

public function Pdo\Pgsql::copyFromFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

Copia dados do arquivo especificado por `filename` na tabela `tableName` usando `separator` como delimitador de campos e lista de campos no parâmetro `fields`.

### Parâmetros

`tableName`
  String contendo o nome da tabela.
`filename`
  Nome do arquivo que contém os dados a serem importados.
`separator`
  Delimitador usado para separar campos em uma entrada do array `rows`.
`nullAs`
  Como interpretar valores SQL `NULL`.
`fields`
  Lista de campos a serem inseridos.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Se `filename` não puder ser aberto para leitura, a falha é reportada através da manipulação do erro da conexão (consulte `PDO::ATTR_ERRMODE`); com `PDO::ERRMODE_EXCEPTION`, uma PDOException é lançada.

### Exemplos

Exemplo #1 Exemplo de Pdo\Pgsql::copyFromFile()

O arquivo tem um registro por linha com campos conectados por `separator` (uma tabulação por padrão).

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $db->exec('CREATE TABLE fruits (id int, name text, qty int)');

    file_put_contents('/tmp/fruits.tsv', "1\tapple\t10\n2\tbanana\t20\n");
    $db->copyFromFile('fruits', '/tmp/fruits.tsv');

    echo $db->query('SELECT count(*) FROM fruits')->fetchColumn(), "\n";
    ?>

O exemplo acima produzirá:

    2

### Veja Também

- Pdo\Pgsql::copyToFile() - Copia dados da tabela para arquivo
- Pdo\Pgsql::copyFromArray() - Copia dados de um array PHP para uma tabela
- Pdo\Pgsql::copyToArray() - Copia dados da tabela do banco de dados para o array PHP

# Pdo\Pgsql::copyToArray

(PHP 8 >= 8.4.0)

Pdo\Pgsql::copyToArray — Copia dados da tabela do banco de dados para o array PHP

### Descrição

public function Pdo\Pgsql::copyToArray(
string `$tableName`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): array|false

Copia dados de `tableName` para um array usando `separator` como delimitador de campos e lista de campos no parâmetro `fields`.

### Parâmetros

`tableName`
  String contendo o nome da tabela.
`separator`
  Delimitador usado para separar campos em uma entrada do array `rows`.
`nullAs`
  Como interpretar valores SQL `NULL`.
`fields`
  Lista de campos a serem exportados.

### Valor Retornado

Retorna um array de linhas, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de Pdo\Pgsql::copyToArray()

Cada elemento retornado é um registro com os campos conectados por `separator` e uma nova linha no final.

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $db->exec('CREATE TABLE fruits (id int, name text, qty int)');
    $db->exec("INSERT INTO fruits VALUES (1, 'apple', 10), (2, 'banana', 20)");

    $rows = $db->copyToArray('fruits');
    var_export($rows);
    ?>

O exemplo acima produzirá:

    array (
      0 => '1	apple	10
    ',
      1 => '2	banana	20
    ',
    )

### Veja Também

- Pdo\Pgsql::copyFromArray() - Copia dados de um array PHP para uma tabela
- Pdo\Pgsql::copyFromFile() - Copia dados do arquivo para a tabela
- Pdo\Pgsql::copyToFile() - Copia dados da tabela para arquivo

# Pdo\Pgsql::copyToFile

(PHP 8 >= 8.4.0)

Pdo\Pgsql::copyToFile — Copia dados da tabela para arquivo

### Descrição

public function Pdo\Pgsql::copyToFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

Copia dados da tabela para o arquivo especificado por `filename` usando `separator` como delimitador de campos e lista de campos no parâmetro `fields`.

### Parâmetros

`tableName`
  String contendo o nome da tabela.
`filename`
  Nome do arquivo para exportar dados.
`separator`
  Delimitador usado para separar campos em uma entrada do array `rows`.
`nullAs`
  Como interpretar valores SQL `NULL`.
`fields`
  Lista de campos a serem exportados.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Se `filename` não puder ser aberto para escrita ou não puder ser gravado, a falha é reportada através da manipulação do erro de conexão (consulte `PDO::ATTR_ERRMODE`); com `PDO::ERRMODE_EXCEPTION` uma PDOException é lançada.

### Exemplos

Exemplo #1 Exemplo de Pdo\Pgsql::copyToFile()

A tabela é gravada em `filename`, um registro por linha com os campos conectados por `separator`.

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $db->exec('CREATE TABLE fruits (id int, name text, qty int)');
    $db->exec("INSERT INTO fruits VALUES (1, 'apple', 10), (2, 'banana', 20)");

    $db->copyToFile('fruits', '/tmp/fruits.tsv');
    echo file_get_contents('/tmp/fruits.tsv');
    ?>

O exemplo acima produzirá:

    1	apple	10
    2	banana	20

### Veja Também

- Pdo\Pgsql::copyFromFile() - Copia dados do arquivo para a tabela
- Pdo\Pgsql::copyFromArray() - Copia dados de um array PHP para uma tabela
- Pdo\Pgsql::copyToArray() - Copia dados da tabela do banco de dados para o array PHP

# Pdo\Pgsql::escapeIdentifier

(PHP 8 >= 8.4.0)

Pdo\Pgsql::escapeIdentifier — Escapa uma string para uso como identificador SQL

### Descrição

public function Pdo\Pgsql::escapeIdentifier(string `$input`): string

Escapa uma string para uso como um identificador SQL, como uma tabela, coluna ou nome de função. Isso é útil quando um identificador fornecido pelo usuário pode conter caracteres especiais que de outra forma não seriam interpretados como parte do identificador pelo analisador SQL ou quando o identificador pode conter caracteres em maiúsculas que precisam ser preservadas.

### Parâmetros

`input`
  Uma string contendo texto a ser escapado.

### Valor Retornado

Uma string contendo os dados escapados.

### Exemplos

Exemplo #1 Exemplo de Pdo\Pgsql::escapeIdentifier()

    <?php
    $pdo = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);

    $unescapedTableName = 'UnescapedTableName';
    $pdo->exec("CREATE TABLE $unescapedTableName ()");

    $escapedTableName = $pdo->escapeIdentifier('EscapedTableName');
    $pdo->exec("CREATE TABLE $escapedTableName ()");

    $statement = $pdo->query(
        "SELECT relname FROM pg_stat_user_tables WHERE relname ilike '%tablename'"
    );

    var_export($statement->fetchAll(PDO::FETCH_COLUMN, 0));

    $tableNameWithSymbols = 'Table-Name-With-Symbols';
    $pdo->exec("CREATE TABLE $tableNameWithSymbols ()");
    ?>

O exemplo acima produzirá algo semelhante a:

    array (
      0 => 'unescapedtablename',
      1 => 'EscapedTableName',
    )
    Fatal error: Uncaught PDOException: SQLSTATE[42601]: Syntax error: 7 ERROR:  syntax error at or near "Table"
    LINE 1: CREATE TABLE Table-Name-With-Symbols ()

### Veja Também

- PDO::quote() - Inclui aspas em uma string para uso em uma consulta

# Pdo\Pgsql::getNotify

(PHP 8 >= 8.4.0)

Pdo\Pgsql::getNotify — Recebe notificação assíncrona

### Descrição

public function Pdo\Pgsql::getNotify(int `$fetchMode` = `PDO::FETCH_DEFAULT`, int `$timeoutMilliseconds` = 0): array|false

Retorna um conjunto de resultados que representa uma notificação assíncrona pendente.

### Parâmetros

`fetchMode`

  O formato como o conjunto de resultados deve ser retornado, uma das seguintes constantes:

  - `PDO::FETCH_DEFAULT`
  - `PDO::FETCH_BOTH`
  - `PDO::FETCH_ASSOC`
  - `PDO::FETCH_NUM`
`timeoutMilliseconds`
  O tempo de espera por uma resposta, em milissegundos.

### Valor Retornado

Se uma notificação estiver pendente, retorna uma única linha, caso contrário retorna `false`. Alinha tem um campo `message` (o nome do canal) e um campo `pid` (o ID do processo do backend que envia a notificação). Se a notificação traz uma carga não vazia, a linha também tem um campo `payload`. Com `PDO::FETCH_NUM`, estes campos estão nos índices `0`, `1` e `2`.

### Erros/Exceções

Uma exceção ValueError será lançada se `fetchMode` não for uma das constantes `PDO::FETCH_*` válidas.

Uma exceção ValueError será lançada se `timeoutMilliseconds` for menor que `0`.

Um `E_WARNING` é gerado quando `timeoutMilliseconds` é maior que o valor que pode estar contido em um inteiro com sinal de 32 bits; nesse caso, será o valor máximo de um inteiro com sinal de 32 bits.

### Exemplos

Exemplo #1 Exemplo de Pdo\Pgsql::getNotify()

Inscreva em um canal com `LISTEN` e então leia a próxima notificação pendente com um tempo limite de um segundo.

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

    $db->exec('LISTEN messages');
    $db->exec("NOTIFY messages, 'hello'");

    $notification = $db->getNotify(PDO::FETCH_ASSOC, 1000);
    var_export($notification);
    ?>

O exemplo acima produzirá algo semelhante a:

    array (
      'message' => 'messages',
      'pid' => 1928,
      'payload' => 'hello',
    )

### Veja Também

- PDO::query() - Prepara e executa uma instrução SQL sem marcadores
- PDOStatement::fetch() - Busca a próxima linha de um resultado
- PDOStatement::fetchAll() - Busca as linhas remanescentes de um conjunto de resultados

# Pdo\Pgsql::getPid

(PHP 8 >= 8.4.0)

Pdo\Pgsql::getPid — Obtém o PID do processo subjacente que trata esta conexão

### Descrição

public function Pdo\Pgsql::getPid(): int

Retorna o PID do processo subjacente que trata esta conexão. Observe que o PID pertence a um processo em execução no host do servidor de banco de dados, não no host local.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o PID como um int.

### Exemplos

Exemplo #1 Exemplo de Pdo\Pgsql::getPid()

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    echo $db->getPid();
    ?>

O exemplo acima produzirá algo semelhante a:

    12345

### Veja Também

- pg_get_pid() - Obtém o ID do processo do backend

# Pdo\Pgsql::lobCreate

(PHP 8 >= 8.4.0)

Pdo\Pgsql::lobCreate — Cria um novo objeto grande

### Descrição

public function Pdo\Pgsql::lobCreate(): string|false

Pdo\Pgsql::lobCreate() cria um objeto grande e retorna o OID que se refere a ele. Ele pode ser aberto para ler ou gravar dados com Pdo\Pgsql::lobOpen().

O OID pode ser armazenado em colunas do tipo OID e usado para fazer referência ao objeto grande, sem fazer com que a linha cresça arbitrariamente. O objeto grande continuará no banco de dados até ser removido chamando Pdo\Pgsql::lobUnlink().

Objetos grandes são complicados de usar. Na verdade, é necessário que Pdo\Pgsql::lobUnlink() seja chamado antes de excluir a última linha que faz referência ao OID em todo o banco de dados; caso contrário, objetos grandes não referenciados permanecerão no servidor indefinidamente. Além disso, objetos grandes não possuem controles de acesso. Uma alternativa é o tipo de coluna bytea, que pode ter até 1 GB de tamanho, e esse tipo de coluna gerencia de forma transparente o armazenamento para obter o tamanho de linha ideal.

> Nota: Esta função e todas as manipulações de objeto grande devem ser chamadas e executadas dentro de uma transação.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o OID do objeto grande recém-criado em caso de sucesso, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de Pdo\Pgsql::lobCreate()

Este exemplo cria um novo objeto grande e copia nele o conteúdo de um arquivo. O OID é então armazenado em uma tabela.

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $db->beginTransaction();
    $oid = $db->lobCreate();
    $stream = $db->lobOpen($oid, 'w');
    $local = fopen($filename, 'rb');
    stream_copy_to_stream($local, $stream);
    $local = null;
    $stream = null;
    $stmt = $db->prepare("INSERT INTO BLOBS (ident, oid) VALUES (?, ?)");
    $stmt->execute([$some_id, $oid]);
    $db->commit();
    ?>

### Veja Também

- Pdo\Pgsql::lobOpen() - Abre um fluxo de objetos grandes existente
- Pdo\Pgsql::lobUnlink() - Exclui o objeto grande
- pg_lo_create() - Cria um objeto grande
- pg_lo_open() - Abra um objeto grande

# Pdo\Pgsql::lobOpen

(PHP 8 >= 8.4.0)

Pdo\Pgsql::lobOpen — Abre um fluxo de objetos grandes existente

### Descrição

public function Pdo\Pgsql::lobOpen(string `$oid`, string `$mode` = "rb"): resource|false

Pdo\Pgsql::lobOpen() abre um fluxo para acessar os dados referenciados por `oid`. Todas as funções usuais do sistema de arquivos, como fread(), fwrite() ou fgets() podem ser usadas para manipular o conteúdo do fluxo.

> Nota: Esta função e todas as manipulações de objeto grande devem ser chamadas e executadas dentro de uma transação.

### Parâmetros

`oid`
  Um identificador de objeto grande.
`mode`
  O modo de acesso. Se `mode` contiver `w` ou `+`, o fluxo é aberto para leitura e escrita; caso contrário é aberto somente-leitura. Um sinalizador `b` (binário) não tem efeito. O padrão `"rb"` abre o fluxo para leitura.

### Valor Retornado

Retorna um recurso de fluxo em caso de sucesso, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de Pdo\Pgsql::lobOpen()

Seguindo o exemplo de Pdo\Pgsql::lobCreate(), este trecho de código recupera o objeto grande do banco de dados e o envia para o navegador.

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $db->beginTransaction();
    $stmt = $db->prepare("SELECT oid FROM BLOBS WHERE ident = ?");
    $stmt->execute([$some_id]);
    $stmt->bindColumn('oid', $oid, PDO::PARAM_STR);
    $stmt->fetch(PDO::FETCH_BOUND);
    $stream = $db->lobOpen($oid, 'r');
    header("Content-type: application/octet-stream");
    fpassthru($stream);
    ?>

### Veja Também

- Pdo\Pgsql::lobCreate() - Cria um novo objeto grande
- Pdo\Pgsql::lobUnlink() - Exclui o objeto grande
- pg_lo_create() - Cria um objeto grande
- pg_lo_open() - Abra um objeto grande

# Pdo\Pgsql::lobUnlink

(PHP 8 >= 8.4.0)

Pdo\Pgsql::lobUnlink — Exclui o objeto grande

### Descrição

public function Pdo\Pgsql::lobUnlink(string `$oid`): bool

Exclui um objeto grande do banco de dados identificado pelo OID.

> Nota: Esta função e todas as manipulações de objeto grande devem ser chamadas e executadas dentro de uma transação.

### Parâmetros

`oid`
  Um identificador de objeto grande.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de Pdo\Pgsql::lobUnlink()

Este exemplo desvincula um objeto grande do banco de dados antes de excluir a linha que o referencia. Ele usa a tabela de blobs dos exemplos de Pdo\Pgsql::lobCreate() e Pdo\Pgsql::lobOpen().

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $db->beginTransaction();
    $db->lobUnlink($oid);
    $stmt = $db->prepare("DELETE FROM BLOBS where ident = ?");
    $stmt->execute([$some_id]);
    $db->commit();
    ?>

### Veja Também

- Pdo\Pgsql::lobCreate() - Cria um novo objeto grande
- Pdo\Pgsql::lobOpen() - Abre um fluxo de objetos grandes existente
- pg_lo_create() - Cria um objeto grande
- pg_lo_open() - Abra um objeto grande

# Pdo\Pgsql::setNoticeCallback

(PHP 8 >= 8.4.0)

Pdo\Pgsql::setNoticeCallback — Define um retorno de chamada para lidar com mensagens de alerta e de aviso geradas pelo back-end

### Descrição

public function Pdo\Pgsql::setNoticeCallback(?callable `$callback`): void

Define um retorno de chamada para lidar com mensagens de aviso e aviso geradas pelo back-end. Isto inclui mensagens emitidas pelo próprio PostgreSQL, bem como aquelas geradas por funções SQL definidas pelo usuário usando `RAISE`. Observe que o recebimento real dessas mensagens depende da configuração de backend `client_min_messages`.

### Parâmetros

`callback`
  Se `null` for passado, o manipulador será redefinido para seu estado padrão.

  Caso contrário, o manipulador será um retorno de chamada com a seguinte assinatura:

  function handler(string `$message`): void
  `message`
    Uma mensagem gerada pelo backend.

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de Pdo\Pgsql::setNoticeCallback()

    <?php
    $pdo = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);

    $pdo->exec('CREATE TABLE parent(id int primary key)');
    $pdo->exec('CREATE TABLE child(id int references parent)');

    $pdo->setNoticeCallback(function ($message) {
        echo $message;
    });

    $pdo->exec('TRUNCATE parent CASCADE');
    ?>

O exemplo acima produzirá algo semelhante a:

    NOTICE:  truncate cascades to table "child"

## Índice

- Pdo\Pgsql::copyFromArray — Copia dados de um array PHP para uma tabela
- Pdo\Pgsql::copyFromFile — Copia dados do arquivo para a tabela
- Pdo\Pgsql::copyToArray — Copia dados da tabela do banco de dados para o array PHP
- Pdo\Pgsql::copyToFile — Copia dados da tabela para arquivo
- Pdo\Pgsql::escapeIdentifier — Escapa uma string para uso como identificador SQL
- Pdo\Pgsql::getNotify — Recebe notificação assíncrona
- Pdo\Pgsql::getPid — Obtém o PID do processo subjacente que trata esta conexão
- Pdo\Pgsql::lobCreate — Cria um novo objeto grande
- Pdo\Pgsql::lobOpen — Abre um fluxo de objetos grandes existente
- Pdo\Pgsql::lobUnlink — Exclui o objeto grande
- Pdo\Pgsql::setNoticeCallback — Define um retorno de chamada para lidar com mensagens de alerta e de aviso geradas pelo back-end

# Driver PDO do SQLite (PDO_SQLITE)

## Introdução

PDO_SQLITE é um driver que implementa a Interface de Objeto de Dados do PHP (PDO) para permitir o acesso a bancos de dados SQLite 3.

> Nota:

> O PDO_SQLITE permite usar strings separadas de fluxos junto com `PDO::PARAM_LOB`.

## Instalação

O driver PDO PDO_SQLITE está habilitado por padrão. Para desabilitá-lo, a opção --without-pdo-sqlite[=DIR] pode ser usada, onde o valor opcional `[=DIR]` é o diretório de instalação do sqlite. A partir do PHP 7.4.0, a » libsqlite ≥ 3.5.0 é necessária. Anteriormente, a libsqlite que vinha com o PHP poderia ser usada e era o padrão se `[=DIR]` fosse omitido.

> Nota: Configuração adicional no Windows a partir do PHP 7.4.0

> Para que esta extensão funcione, existem arquivos DLL que devem estar disponíveis no PATH do sistema Windows. Para saber como fazer isso, veja a FAQ intitulada "Como eu adiciono o meu diretório PHP ao PATH do Windows". Embora copiar arquivos DLL da pasta do PHP para o diretório system do Windows também funcione (porque o diretório system está, por padrão, no PATH do sistema), isso não é recomendado. Esta extensão requer que os seguintes arquivos estejam no PATH: libsqlite3.dll.

# DSN PDO_SQLITE

(No version information available, might only be in Git)

DSN PDO_SQLITE — Conectando a bancos de dados SQLite

### Descrição

O Data Source Name (DSN) PDO_SQLITE é composto pelos seguintes elementos:

Prefixo DSN (SQLite 3)

  O prefixo DSN é `sqlite:`.

  - Para acessar um banco de dados em disco, o caminho absoluto deve ser adicionado ao prefixo DSN.

  - Para criar um banco de dados em memória, `:memory:` deve ser adicionado ao prefixo DSN.

  - Se o DSN consistir apenas no prefixo DSN, um banco de dados temporário será usado e será excluído quando a conexão for encerrada.

### Exemplos

Exemplo #1 Exemplos de DSN PDO_SQLITE

Os exemplos a seguir mostram o DSN PDO_SQLITE para conexão com bancos de dados SQLite:

    sqlite:/caminho/para/o/arquivo/banco.sq3
    sqlite::memory:
    sqlite:

# PDO::sqliteCreateAggregate

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo_sqlite >= 1.0.0)

PDO::sqliteCreateAggregate — Sinônimo de Pdo\Sqlite::createAggregate()

### Descrição

public function PDO::sqliteCreateAggregate(
string `$name`,
callable `$step`,
callable `$finalize`,
int `$numArgs` = -1
): bool

Este método é um apelido para: Pdo\Sqlite::createAggregate().

# PDO::sqliteCreateCollation

(PHP 5 >= 5.3.11, PHP 7, PHP 8)

PDO::sqliteCreateCollation — Sinônimo de Pdo\Sqlite::createCollation()

### Descrição

public function PDO::sqliteCreateCollation(string `$name`, callable `$callback`): bool

Este método é um apelido para: Pdo\Sqlite::createCollation().

# PDO::sqliteCreateFunction

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo_sqlite >= 1.0.0)

PDO::sqliteCreateFunction — Sinônimo de Pdo\Sqlite::createFunction()

### Descrição

public function PDO::sqliteCreateFunction(
string `$function_name`,
callable `$callback`,
int `$num_args` = -1,
int `$flags` = 0
): bool

Este método é um apelido para: Pdo\Sqlite::createFunction().

### Registro de Alterações

Versão | Descrição
--- | ---
7.1.4 | O parâmetro `flags` foi adicionado.

## Índice

- DSN PDO_SQLITE — Conectando a bancos de dados SQLite
- PDO::sqliteCreateAggregate — Sinônimo de Pdo\Sqlite::createAggregate
- PDO::sqliteCreateCollation — Sinônimo de Pdo\Sqlite::createCollation
- PDO::sqliteCreateFunction — Sinônimo de Pdo\Sqlite::createFunction

# A classe Pdo\Sqlite

(PHP 8 >= 8.4.0)

## Introdução

Uma subclasse PDO representando uma conexão que usa o driver PDO SQLite.

Este driver suporta um analisador de consulta SQL dedicado para o dialeto SQLite. Pode lidar com:

- Literais entre aspas simples, duplas, e acentos graves, com a duplicação como mecanismo de escape.
- Identificadores envolvidos por colchetes.
- Comentários com dois hífens ou no estilo C (não aninhados).

## Resumo da classe

class Pdo\Sqlite extends PDO {
/* Constantes herdadas */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Constantes */
public const int DETERMINISTIC;
public const int OPEN_READONLY;
public const int OPEN_READWRITE;
public const int OPEN_CREATE;
public const int ATTR_OPEN_FLAGS;
public const int ATTR_READONLY_STATEMENT;
public const int ATTR_EXTENDED_RESULT_CODES;
/* Métodos */
public function createAggregate(
string `$name`,
callable `$step`,
callable `$finalize`,
int `$numArgs` = -1
): bool
public function createCollation(string `$name`, callable `$callback`): bool
public function createFunction(
string `$function_name`,
callable `$callback`,
int `$num_args` = -1,
int `$flags` = 0
): bool
public function loadExtension(string `$name`): void
public function openBlob(
string `$table`,
string `$column`,
int `$rowid`,
?string `$dbname` = "main",
int `$flags` = `Pdo\Sqlite::OPEN_READONLY`
): resource|false
/* Métodos herdados */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Constantes predefinidas

`Pdo\Sqlite::DETERMINISTIC`
`Pdo\Sqlite::OPEN_READONLY`
`Pdo\Sqlite::OPEN_READWRITE`
`Pdo\Sqlite::OPEN_CREATE`
`Pdo\Sqlite::ATTR_OPEN_FLAGS`
`Pdo\Sqlite::ATTR_READONLY_STATEMENT`
`Pdo\Sqlite::ATTR_EXTENDED_RESULT_CODES`

# Pdo\Sqlite::createAggregate

(PHP 8 >= 8.4.0)

Pdo\Sqlite::createAggregate — Registra uma função de agregação definida pelo usuário para uso em instruções SQL

### Descrição

public function Pdo\Sqlite::createAggregate(
string `$name`,
callable `$step`,
callable `$finalize`,
int `$numArgs` = -1
): bool

Este método é semelhante a Pdo\Sqlite::createFunction() exceto que registra funções que podem ser usadas para calcular um resultado agregado em todas as linhas de uma consulta.

A principal diferença entre este método e Pdo\Sqlite::createFunction() é que duas funções são necessárias para gerenciar a agregação.

Dica

Usando este método é possível substituir funções SQL nativas.

### Parâmetros

`name`
  O nome da função usada nas instruções SQL.
`step`
  Função de retorno de chamada chamada para cada linha do conjunto de resultados. O retorno de chamada deve acumular o resultado e armazená-lo no contexto de agregação.

  Esta função precisa ser definida como:

  function step(
  mixed `$context`,
  int `$rownumber`,
  mixed `$value`,
  mixed `...$values`
  ): mixed
  `context`
    `null` para a primeira linha; nas linhas subsequentes terá o valor que foi retornado anteriormente da função step; deve-se usar isso para manter o estado agregado.
  `rownumber`
    O número da linha atual.
  `value`
    O primeiro argumento passado para o agregado.
  `values`
    Outros argumentos passados ​​para o agregado.
  O valor de retorno desta função será usado como argumento `context` na próxima chamada das funções step ou finalize.
`finalize`
  Função de retorno de chamada para agregar os dados "escalonados" de cada linha. Depois que todas as linhas forem processadas, esta função será chamada, devendo então pegar os dados do contexto de agregação e retornar o resultado. Esta função de retorno de chamada deve retornar um tipo compreendido pelo SQLite (ou seja, tipo escalar).

  Esta função precisa ser definida como:

  function fini(mixed `$context`, int `$rowcount`): mixed
  `context`

    Contém o valor de retorno da última chamada para a função step.

  `rowcount`

    Contém o número de linhas nas quais a agregação foi executada.

  O valor de retorno desta função será usado como valor de retorno da agregação.
`numArgs`
  Dica para o analisador SQLite se a função de retorno de chamada aceita um número predeterminado de argumentos.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de Pdo\Sqlite::createAggregate()

Neste exemplo, criaremos uma função agregada personalizada chamada `max_length` que pode ser usada em consultas SQL.

Neste exemplo, estamos criando uma função agregadora, chamada `max_length`, que calculará o comprimento da string mais longa em uma das colunas da tabela. Para cada linha, a função `max_len_step` é chamada e passa um parâmetro `$context`. O parâmetro context é como qualquer outra variável PHP e pode ser configurado para conter um array ou até mesmo um object. Neste exemplo, estamos usando-o para manter o comprimento máximo que vimos até agora; se $string tiver um comprimento maior que o máximo atual, atualizamos o contexto para manter esse novo comprimento máximo.

Após todas as linhas terem sido processadas, o SQLite chama a função `max_len_finalize` para determinar o resultado agregado. É possível realizar algum tipo de cálculo baseado nos dados em `$context`. Neste exemplo básico o resultado foi calculado à medida que a consulta avançava, para que o valor do contexto pudesse ser retornado diretamente.

    <?php
    $data = [
       'one',
       'two',
       'three',
       'four',
       'five',
       'six',
       'seven',
       'eight',
       'nine',
       'ten',
    ];
    $db = new Pdo\Sqlite('sqlite::memory:');
    $db->exec("CREATE TABLE strings(a)");
    $insert = $db->prepare('INSERT INTO strings VALUES (?)');
    foreach ($data as $str) {
        $insert->execute(array($str));
    }
    $insert = null;

    function max_len_step($context, $row_number, $string)
    {
        if (strlen($string) > $context) {
            $context = strlen($string);
        }
        return $context;
    }

    function max_len_finalize($context, $row_count)
    {
        return $context === null ? 0 : $context;
    }

    $db->createAggregate('max_len', 'max_len_step', 'max_len_finalize');

    var_dump($db->query('SELECT max_len(a) from strings')->fetchAll());

    ?>

Dica

NÃO é recomendado que se armazene uma cópia dos valores no contexto e depois processe-os no final, pois faria com que o SQLite usasse muita memória para processar a consulta - basta pensar em quanta memória seria necessárias se um milhão de linhas fossem armazenadas na memória, cada uma contendo uma string de 32 bytes de comprimento.

### Veja Também

- Pdo\Sqlite::createFunction() - Registra uma função definida pelo usuário para uso em instruções SQL
- Pdo\Sqlite::createCollation() - Registra uma função definida pelo usuário para uso como função de agrupamento em instruções SQL
- sqlite_create_function()
- sqlite_create_aggregate()

# Pdo\Sqlite::createCollation

(PHP 8 >= 8.4.0)

Pdo\Sqlite::createCollation — Registra uma função definida pelo usuário para uso como função de agrupamento em instruções SQL

### Descrição

public function Pdo\Sqlite::createCollation(string `$name`, callable `$callback`): bool

Este método é semelhante a Pdo\Sqlite::createFunction() exceto que ele registra funções que são usadas para agrupar strings.

### Parâmetros

`name`
  Nome da função de agrupamento SQL a ser criada ou redefinida.
`callback`
  Função de retorno de chamada que define o comportamento de um agrupamento. Ele deve aceitar duas strings e retornar `-1`, `0` ou `1` se a primeira string for classificada antes, ordenada de forma idêntica ou ordenada depois da segunda string, respectivamente. Uma função interna que se comporta assim é strcmp().

  Esta função precisa ser definida como:

  function collation(string `$string1`, string `$string2`): int

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de Pdo\Sqlite::createCollation()

    <?php
    $db = new Pdo\Sqlite('sqlite::memory:');
    $db->exec("CREATE TABLE test (col1 string)");
    $db->exec("INSERT INTO test VALUES ('a1')");
    $db->exec("INSERT INTO test VALUES ('a10')");
    $db->exec("INSERT INTO test VALUES ('a2')");

    $db->sqliteCreateCollation('NATURAL_CMP', 'strnatcmp');
    foreach ($db->query("SELECT col1 FROM test ORDER BY col1") as $row) {
        echo $row['col1'] . "\n";
    }
    echo "\n";
    foreach ($db->query("SELECT col1 FROM test ORDER BY col1 COLLATE NATURAL_CMP") as $row) {
        echo $row['col1'] . "\n";
    }
    ?>

O exemplo acima produzirá:

    a1
    a10
    a2

    a1
    a2
    a10

### Veja Também

- Pdo\Sqlite::createFunction() - Registra uma função definida pelo usuário para uso em instruções SQL
- Pdo\Sqlite::createAggregate() - Registra uma função de agregação definida pelo usuário para uso em instruções SQL
- sqlite_create_function()
- sqlite_create_aggregate()

# Pdo\Sqlite::createFunction

(PHP 8 >= 8.4.0)

Pdo\Sqlite::createFunction — Registra uma função definida pelo usuário para uso em instruções SQL

### Descrição

public function Pdo\Sqlite::createFunction(
string `$function_name`,
callable `$callback`,
int `$num_args` = -1,
int `$flags` = 0
): bool

Este método permite que a função PHP seja registrada no SQLite como uma função definida pelo usuário, para que possa ser chamada em consultas SQL. A função definida pode ser usada em qualquer consulta SQL que permita chamadas de função, por exemplo `SELECT`, `UPDATE` ou gatilhos.

Dica

Usando este método é possível substituir funções SQL nativas.

### Parâmetros

`function_name`
  O nome da função usada nas instruções SQL.
`callback`
  Função de retorno de chamada para lidar com a função SQL definida.

  > Nota: As funções de retorno de chamada devem retornar um tipo compreendido pelo SQLite (ou seja, tipo escalar).

  Esta função precisa ser definida como:

  function callback(mixed `$value`, mixed `...$values`): mixed
  `value`

    O primeiro argumento passado para a função SQL.

  `values`

    Argumentos adicionais passados ​​para a função SQL.

`num_args`
  O número de argumentos que a função SQL utiliza. Se este parâmetro for `-1`, a função SQL poderá receber qualquer número de argumentos.
`flags`
  Uma máscara de bits de opções. Atualmente, apenas `Pdo\Sqlite::DETERMINISTIC` é suportada, o que especifica que a função sempre retorna o mesmo resultado dadas as mesmas entradas em uma única instrução SQL.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de Pdo\Sqlite::createFunction()

Neste exemplo, temos uma função que calcula a soma SHA256 de uma string e depois a inverte. Quando a instrução SQL é executada, ela retorna o valor do nome do arquivo transformado pela nossa função. Os dados retornados em $rows contêm o resultado processado.

A beleza desta técnica é que não há necessidade de processar o resultado usando um laço `foreach` após a consulta.

    <?php
    function sha256_and_reverse($string)
    {
        return strrev(hash('sha256', $string));
    }

    $db = new Pdo\Sqlite('sqlite::sqlitedb');
    $db->createFunction('sha256rev', 'sha256_and_reverse', 1);
    $rows = $db->query('SELECT sha256rev(filename) FROM files')->fetchAll();
    ?>

### Veja Também

- Pdo\Sqlite::createAggregate() - Registra uma função de agregação definida pelo usuário para uso em instruções SQL
- Pdo\Sqlite::createCollation() - Registra uma função definida pelo usuário para uso como função de agrupamento em instruções SQL
- sqlite_create_function()
- sqlite_create_aggregate()

# Pdo\Sqlite::loadExtension

(PHP 8 >= 8.4.0)

Pdo\Sqlite::loadExtension — Carrega extensão

### Descrição

public function Pdo\Sqlite::loadExtension(string `$name`): void
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Descrição.

### Parâmetros

`name`
  Descrição.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

Erros `E_*`, e/ou exceções Exception.

### Exemplos

Exemplo #1 Exemplo de Pdo\Sqlite::loadExtension()

Descrição.

    <?php
    echo "Exemplo de código";
    ?>

O exemplo acima produzirá:

    Code example

### Notas

> Nota: Notas.

### Veja Também

- ClassName::otherMethodName()
- some_function()

# Pdo\Sqlite::openBlob

(PHP 8 >= 8.4.0)

Pdo\Sqlite::openBlob — Abre Blob

### Descrição

public function Pdo\Sqlite::openBlob(
string `$table`,
string `$column`,
int `$rowid`,
?string `$dbname` = "main",
int `$flags` = `Pdo\Sqlite::OPEN_READONLY`
): resource|false
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Descrição.

### Parâmetros

`table`
  Descrição.
`column`
  Descrição.
`rowid`
  Descrição.
`dbname`
  Descrição.
`flags`
  Uma das constantes `Pdo\Sqlite::OPEN_*`.

### Valor Retornado

Descrição.

### Erros/Exceções

Erros `E_*`, e/ou exceções Exception.

### Exemplos

Exemplo #1 Exemplo de Pdo\Sqlite::openBlob()

Descrição.

    <?php
    echo "Code example";
    ?>

O exemplo acima produzirá:

    Code example

### Notas

> Nota: Notas.

### Veja Também

- ClassName::otherMethodName()
- some_function()

## Índice

- Pdo\Sqlite::createAggregate — Registra uma função de agregação definida pelo usuário para uso em instruções SQL
- Pdo\Sqlite::createCollation — Registra uma função definida pelo usuário para uso como função de agrupamento em instruções SQL
- Pdo\Sqlite::createFunction — Registra uma função definida pelo usuário para uso em instruções SQL
- Pdo\Sqlite::loadExtension — Carrega extensão
- Pdo\Sqlite::openBlob — Abre Blob

- Instalação/Configuração
  - Instalação
  - Configurações em Execução
- Constantes predefinidas
  - Modos de Busca
- Conexões e gerenciamento de conexões
- Transações e confirmação automática (auto-commit)
- Declarações preparadas e procedimentos armazenados
- Erros e manipulação de erros
- Objetos Grandes (LOBs)
- PDO — A classe PDO
  - PDO::beginTransaction — Inicia uma transação
  - PDO::commit — Envia uma transação
  - PDO::connect — Conecta a um banco de dados e retorna uma subclasse PDO para drivers que o suportam
  - PDO::__construct — Cria uma instância PDO representando uma conexão a um banco de dados
  - PDO::errorCode — Busca o SQLSTATE associado com a última operação no identificador do banco de dados
  - PDO::errorInfo — Busca informação de erro estendida associada com a última operação no identificador do banco de dados
  - PDO::exec — Executa uma instrução SQL e retorna o número de linhas afetadas
  - PDO::getAttribute — Recuperar um atributo da conexão com o banco de dados
  - PDO::getAvailableDrivers — Retorna um array com os drivers PDO disponíveis
  - PDO::inTransaction — Verifica se está dentro de uma transação
  - PDO::lastInsertId — Retorna o ID da última linha ou valor de sequência inserido
  - PDO::prepare — Prepara uma instrução para execução e retorna um objeto de instrução
  - PDO::query — Prepara e executa uma instrução SQL sem marcadores
  - PDO::quote — Inclui aspas em uma string para uso em uma consulta
  - PDO::rollBack — Reverte uma transação
  - PDO::setAttribute — Define um atributo
- PDOStatement — A classe PDOStatement
  - PDOStatement::bindColumn — Vincula uma coluna a uma variável PHP
  - PDOStatement::bindParam — Vincula um parâmetro ao nome de variável especificado
  - PDOStatement::bindValue — Vincula um valor a um parâmetro
  - PDOStatement::closeCursor — Fecha o cursor, permitindo que a instrução seja executada novamente
  - PDOStatement::columnCount — Retorna o número de colunas no conjunto de resultados
  - PDOStatement::debugDumpParams — Despeja uma instrução preparada SQL
  - PDOStatement::errorCode — Busca o SQLSTATE associado com a última operação no objeto da instrução
  - PDOStatement::errorInfo — Busca informação de erro estendida associada com a última operação no identificador da instrução
  - PDOStatement::execute — Executa ums instrução preparada
  - PDOStatement::fetch — Busca a próxima linha de um resultado
  - PDOStatement::fetchAll — Busca as linhas remanescentes de um conjunto de resultados
  - PDOStatement::fetchColumn — Retorna uma única coluna do próximo registro de um resultado
  - PDOStatement::fetchObject — Busca o próximo registro e retorna-o como um objeto
  - PDOStatement::getAttribute — Recupera um atributo da instrução
  - PDOStatement::getColumnMeta — Retorna metadados para uma coluna no resultado
  - PDOStatement::getIterator — Obtém o iterador do conjunto de resultados
  - PDOStatement::nextRowset — Avança para o próximo conjunto de registros em um identificados de instrução com múltiplos conjuntos de registros
  - PDOStatement::rowCount — Retorna o número de registros afetados pela última instrução SQL
  - PDOStatement::setAttribute — Define um atributo na instrução
  - PDOStatement::setFetchMode — Define o modo de carga de dados para esta instrução
- PDORow — A classe PDORow
- PDOException — A classe PDOException
- Drivers do PDO
  - Driver PDO do CUBRID — Driver PDO do CUBRID (PDO_CUBRID)
  - Driver PDO do MS SQL Server — Driver PDO do Microsoft SQL Server e Sybase (PDO_DBLIB)
  - Pdo\Dblib — A classe Pdo\Dblib
  - Driver PDO do Firebird — Driver PDO do Firebird (PDO_FIREBIRD)
  - Pdo\Firebird — A classe Pdo\Firebird
  - Driver PDO da IBM — Driver PDO da IBM (PDO_IBM)
  - Driver PDO do Informix — Driver PDO do Informix (PDO_INFORMIX)
  - Driver PDO do MySQL — Driver PDO do MySQL (PDO_MYSQL)
  - Pdo\Mysql — A classe Pdo\Mysql
  - Driver PDO do Microsoft SQL Server — Driver PDO do Microsoft SQL Server (PDO_SQLSRV)
  - Driver PDO do Oracle — Driver PDO do Oracle (PDO_OCI)
  - Driver PDO do ODBC e do DB2 — Driver PDO do ODBC e do DB2 (PDO_ODBC)
  - Pdo\Odbc — A classe Pdo\Odbc
  - Driver PDO do PostgreSQL — Driver PDO do PostgreSQL (PDO_PGSQL)
  - Pdo\Pgsql — A classe Pdo\Pgsql
  - Driver PDO do SQLite — Driver PDO do SQLite (PDO_SQLITE)
  - Pdo\Sqlite — A classe Pdo\Sqlite

- DBA — Camada de abstração de banco de dados (estilo dbm)
  - Instalação/Configuração
  - Constantes predefinidas
  - Exemplos
  - Dba\Connection — A classe Dba\Connection
  - Funções de DBA
- ODBC — ODBC (Unificado)
  - Instalação/Configuração
  - Constantes predefinidas
  - Funções de ODBC
  - Odbc\Connection — A classe Odbc\Connection
  - Odbc\Result — A classe Odbc\Result
- PDO — PHP Data Objects
  - Instalação/Configuração
  - Constantes predefinidas
  - Conexões e gerenciamento de conexões
  - Transações e confirmação automática (auto-commit)
  - Declarações preparadas e procedimentos armazenados
  - Erros e manipulação de erros
  - Objetos Grandes (LOBs)
  - PDO — A classe PDO
  - PDOStatement — A classe PDOStatement
  - PDORow — A classe PDORow
  - PDOException — A classe PDOException
  - Drivers do PDO

# Extensões de Banco de Dados Específicas de Terceiros

# CUBRID

# Introdução

Essas funções permitem acessar servidores de banco de dados CUBRID. Mais informações sobre o CUBRID podem ser encontradas em » CUBRID.

A documentação do CUBRID pode ser encontrada na » Documentação do CUBRID.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução
- Tipos de Recurso

## Dependências

Para ter essas funções disponíveis, deve-se instalar o CUBRID e compilar a biblioteca PHP CUBRID com suporte ao CUBRID.

## Instalação

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/cubrid.

Uma DLL para esta extensão PECL não está disponível no momento. Veja também a seção Compilando no Windows.

Para obter informações sobre instalação manual em sistemas Linux e Windows, leia o arquivo build-guide.html incluído no pacote.

## Configurações em Execução

Não há configuração em tempo de execução.

## Tipos de Recurso

Existem quatro tipos de recursos usados no CUBRID. O primeiro é o identificador da conexão de banco de dados, o segundo é o recurso que contém o resultado de uma consulta e os dois últimos são um recurso que contém os resultados da consulta de tipos de dados BLOB ou CLOB.

## Identificador de conexão

Um identificador de conexão retornado por cubrid_connect(), cubrid_connect_with_url(), cubrid_pconnect() e cubrid_pconnect_with_url().

## Identificador de requisição

Um identificador de requisição retornado por cubrid_prepare() e cubrid_execute().

## Identificador LOB

Um identificador LOB retornado por cubrid_lob_get().

## Identificador LOB2

Um identificador LOB retornado por cubrid_lob2_new() ou obtido do conjunto de resultados.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

As constantes a seguir podem ser usadas ao executar a instrução SQL. Eles podem ser passados para cubrid_prepare() e cubrid_execute().

Opções de execução SQL CUBRID
Constante | Descrição
--- | ---
`CUBRID_INCLUDE_OID` | Determina se deseja obter o OID durante a execução da consulta.
`CUBRID_ASYNC` | Executa a consulta em modo assíncrono.
`CUBRID_EXEC_QUERY_ALL` | Executa a consulta em modo síncrono. Esta opção deve ser definida ao executar múltiplas instruções SQL.

As constantes a seguir podem ser usadas ao buscar os resultados para especificar o comportamento de busca. Eles podem ser passados para cubrid_fetch() e cubrid_fetch_array().

Opções de busca CUBRID
Constante | Descrição
--- | ---
`CUBRID_NUM` | Obtém o resultado da consulta como um array numérico (padrão 0).
`CUBRID_ASSOC` | Obtém o resultado da consulta como um array associativo.
`CUBRID_BOTH` | Obtém o resultado da consulta como arrays numéricos e associativos (valor padrão).
`CUBRID_OBJECT` | Obtém o resultado da consulta como um objeto.
`CUBRID_LOB` | A constante CUBRID_LOB pode ser usada quando a intenção é operar o objeto lob. Pode ser passado para cubrid_fetch(), cubrid_fetch_row(), cubrid_fetch_array(), cubrid_fetch_assoc() e cubrid_fetch_object().

As constantes a seguir podem ser usadas ao posicionar o cursor nos resultados da consulta. Eles podem ser passados ou retornados por cubrid_move_cursor().

Opções de posição do cursor CUBRID
Constante | Descrição
--- | ---
`CUBRID_CURSOR_FIRST` | Move o cursor atual para a primeira posição no resultado.
`CUBRID_CURSOR_CURRENT` | Move o cursor atual como valor padrão se a origem não for especificada.
`CUBRID_CURSOR_LAST` | Move o cursor atual para a última posição no resultado.
`CUBRID_CURSOR_SUCCESS` | Valor retornado da função cubrid_move_cursor() em caso de sucesso. Esta opção foi removida da versão 8.4.1.
`CUBRID_NO_MORE_DATA` | Valor retornado da função cubrid_move_cursor() em caso de falha. Esta opção foi removida da versão 8.4.1.
`CUBRID_CURSOR_ERROR` | Valor retornado da função cubrid_move_cursor() em caso de falha. Esta opção foi removida da versão 8.4.1.

As constantes a seguir podem ser usadas ao definir o modo de confirmação automática para a conexão do banco de dados. Eles podem ser passados para cubrid_set_autocommit() ou retornados por cubrid_get_autocommit().

Opções do modo de confirmação automática CUBRID
Constante | Descrição
--- | ---
`CUBRID_AUTOCOMMIT_TRUE` | Ativa o modo de confirmação automática.
`CUBRID_AUTOCOMMIT_FALSE` | Desativa o modo de confirmação automática.

As constantes a seguir podem ser usadas ao definir o parâmetro do banco de dados. Eles podem ser passados para cubrid_set_db_parameter().

Opções de parâmetro CUBRID
Constante | Descrição
--- | ---
`CUBRID_PARAM_ISOLATION_LEVEL` | Nível de isolamento da transação para a conexão do banco de dados.
`CUBRID_PARAM_LOCK_TIMEOUT` | Tempo limite da transação em segundos.

As constantes a seguir podem ser usadas ao definir o nível de isolamento da transação. Eles podem ser passados para cubrid_set_db_parameter() ou retornado por cubrid_get_db_parameter().

Opções de nível de isolamento CUBRID
Constante | Descrição
--- | ---
`TRAN_COMMIT_CLASS_UNCOMMIT_INSTANCE` | O nível de isolamento mais baixo (1). Uma leitura suja, não repetível ou fantasma pode ocorrer para a tupla e uma leitura não repetível também pode ocorrer para a tabela.
`TRAN_COMMIT_CLASS_COMMIT_INSTANCE` | Um nível de isolamento relativamente baixo (2). Uma leitura suja não ocorre, mas pode ocorrer uma leitura não repetível ou fantasma.
`TRAN_REP_CLASS_UNCOMMIT_INSTANCE` | O isolamento padrão do CUBRID (3). Uma leitura suja, não repetível ou fantasma pode ocorrer para a tupla, mas a leitura repetível é garantida para a tabela.
`TRAN_REP_CLASS_COMMIT_INSTANCE` | Um nível de isolamento relativamente baixo (4). Uma leitura suja não ocorre, mas uma leitura não repetível ou fantasma pode ocorrer.
`TRAN_REP_CLASS_REP_INSTANCE` | Um nível de isolamento relativamente alto (5). Uma leitura suja ou não repetível não ocorre, mas uma leitura fantasma pode ocorrer.
`TRAN_SERIALIZABLE` | O nível de isolamento mais alto (6). Problemas relativos à simultaneidade (por exemplo, leitura suja, leitura não repetível, leitura fantasma, etc.) não ocorrem.

As constantes a seguir podem ser usadas ao obter informações de esquema. Elas podem ser passados para cubrid_schema().

Opções de esquema CUBRID
Constante | Descrição
--- | ---
`CUBRID_SCH_CLASS` | Obtém nome e tipo de tabela em CUBRID.
`CUBRID_SCH_VCLASS` | Obtém nome e tipo de visualização no CUBRID.
`CUBRID_SCH_QUERY_SPEC` | Obtém a definição de consulta da visualização.
`CUBRID_SCH_ATTRIBUTE` | Obtém os atributos da coluna da tabela.
`CUBRID_SCH_CLASS_ATTRIBUTE` | Obtém os atributos da tabela.
`CUBRID_SCH_METHOD` | Obtém o método da instância. O método de instância é um método chamado por uma instância de classe. É usado com mais frequência que o método de classe porque a maioria das operações são executadas na instância.
`CUBRID_SCH_CLASS_METHOD` | Obtém o método da classe. O método de classe é um método chamado por um objeto de classe. Geralmente é usado para criar uma nova instância de classe ou para inicializá-la. Também é usado para acessar ou atualizar atributos de classe.
`CUBRID_SCH_METHOD_FILE` | Obtém as informações do arquivo onde está definido o método da tabela.
`CUBRID_SCH_SUPERCLASS` | Obtém o nome e o tipo da tabela da qual a tabela herda atributos.
`CUBRID_SCH_SUBCLASS` | Obtém o nome e o tipo da tabela que herda os atributos desta tabela.
`CUBRID_SCH_CONSTRAINT` | Obtém as restrições da tabela.
`CUBRID_SCH_TRIGGER` | Obtém os gatilhos da tabela.
`CUBRID_SCH_CLASS_PRIVILEGE` | Obtém as informações de privilégio da tabela.
`CUBRID_SCH_ATTR_PRIVILEGE` | Obtém as informações de privilégio da coluna.
`CUBRID_SCH_DIRECT_SUPER_CLASS` | Obtém a supertabela direta da tabela.
`CUBRID_SCH_PRIMARY_KEY` | Obtém a chave primária da tabela.
`CUBRID_SCH_IMPORTED_KEYS` | Obtém chaves importadas da tabela.
`CUBRID_SCH_EXPORTED_KEYS` | Obtém chaves exportadas da tabela.
`CUBRID_SCH_CROSS_REFERENCE` | Obtém relacionamento de referência de duas tabelas.

As constantes a seguir podem ser usadas ao relatar erros. Elas podem ser retornadas de cubrid_error_code_facility().

Códigos de erro do CUBRID
Constante | Descrição
--- | ---
`CUBRID_FACILITY_DBMS` | O erro ocorreu no DBMS (Sistema de Gerenciamento de Banco de Dados) do CUBRID.
`CUBRID_FACILITY_CAS` | O erro ocorreu no CAS (Servidor Comum de Aplicações) do CUBRID.
`CUBRID_FACILITY_CCI` | O erro ocorreu no CCI (Interface do Cliente em C) do CUBRID.
`CUBRID_FACILITY_CLIENT` | O erro ocorreu no cliente PHP do CUBRID.

# Exemplos

A seguir está um exemplo simples que estabelece uma conexão entre o PHP e o CUBRID. Esta seção cobrirá os recursos mais básicos e notáveis. O código a seguir é necessário para conectar-se ao banco de dados CUBRID, o que significa que o CUBRID Server e o CUBRID Broker devem estar em execução.

O exemplo abaixo usa o banco de dados demodb como exemplo. Por padrão, ele é criado durante a instalação. Certifique-se de que ele foi criado.

Exemplo #1 Exemplo de recuperação de dados

    <html>
        <head>
        <meta http-equiv="content-type" content="text/html; charset=euc-kr">
        </head>
        <body>
        <center>
        <table border=2>
        <?php
            /**
             * Define informações do servidor para conexão CUBRID. host_ip é o endereço
             * IP onde o CUBRID Broker está instalado (localhost neste
             * exemplo), e host_port é o número da porta do CUBRID Broker.
             * O número da porta é o padrão fornecido durante a instalação.
             * Para obter detalhes, consulte o "Guia do Administrador".
             */
            $host_ip = "localhost";
            $host_port = 33000;
            $db_name = "demodb";
            /**
             * Conecta ao servidor CUBRID. Não faz a conexão real, mas
             * apenas retém as informações da conexão. A razão para não fazer
             * a conexão real é para lidar com transações com mais eficiência
             * na arquitetura de 3 camadas.
             */
            $cubrid_con = @cubrid_connect($host_ip, $host_port, $db_name);

            if (!$cubrid_con) {
                echo "Erro de conexão com banco de dados";
                exit;
            }
        ?>
        <?php
            $sql = "select sports, count(players) as players from event group by sports";
            /**
             * Solicita ao CUBRID Server os resultados da instrução SQL.
             * Agora faz a conexão real com o CUBRID Server.
             */
            $result = cubrid_execute($cubrid_con, $sql);

            if ($result) {
                /**
                 * Obtém os nomes das colunas do conjunto de resultados criado pela consulta SQL.
                 */
                $columns = cubrid_column_names($result);
                /**
                 * Obtém o número de colunas no conjunto de resultados criado pela consulta SQL.
                 */
                $num_fields = cubrid_num_cols($result);
                /**
                 * Lista os nomes das colunas do conjunto de resultados na tela.
                 */
                echo "<tr>";

                while (list($key, $colname) = each($columns)) {
                    echo "<td align=center>$colname</td>";
                }

                echo "</tr>";

                /**
                 * Obtém os resultados do conjunto de resultados.
                 */
                while ($row = cubrid_fetch($result)) {
                    echo "<tr>";

                    for ($i = 0; $i < $num_fields; $i++) {
                        echo "<td align=center>";
                        echo $row[$i];
                        echo "</td>";
                    }

                    echo "</tr>";
                }
            }
            /**
             * O módulo PHP no CUBRID é executado em uma arquitetura de 3 camadas. Mesmo ao
             * chamar SELECT para processamento da transação, ela é processada como parte
             * da transação. Portanto, a transação precisa ser revertida
             * chamando-se commit ou rollback mesmo que SELECT tenha sido chamado, para obter um desempenho
             * suave.
             */
            cubrid_commit($cubrid_con);
            cubrid_disconnect($cubrid_con);
        ?>
        </body>
        </html>

Exemplo #2 Exemplo de inserção de dados

    <html>
        <head>
        <meta http-equiv="content-type" content="text/html; charset=euc- kr">
        </head>
        <body>
        <center>
        <table border=2>
        <?php
            /**
             * host_ip é o endereço IP onde o CUBRID Broker está instalado
             * host_port é o número da porta do CUBRID Broker
             * db_name é o nome do banco de dados CUBRID
             */
            $host_ip = "localhost";
            $host_port = 33000;
            $db_name = "demodb";
            $cubrid_con = @cubrid_connect($host_ip, $host_port, $db_name);

            if (!$cubrid_con) {
                echo "Erro de conexão com banco de dados";
                exit;
            }
        ?>
        <?php
            $sql = "insert into olympic (host_year,host_nation,host_city,"
                . "opening_date,closing_date) values (2008, 'China', 'Beijing',"
                . "to_date('08-08-2008','mm-dd- yyyy'),to_date('08-24-2008','mm-dd-yyyy')) ;";
            $result = cubrid_execute($cubrid_con, $sql);
            if ($result) {
                /**
                 * Tratado com sucesso, então confirma.
                 */
                cubrid_commit($cubrid_con);
                echo "Inserido com sucesso";
            } else {
                /**
                 * Ocorreu um erro, então a mensagem de erro é exibida e a reversão é chamada.
                 */
                echo cubrid_error_msg();
                cubrid_rollback($cubrid_con);
            }
            cubrid_disconnect($cubrid_con);
        ?>
        </body>
        </html>

# Funções de CUBRID

# cubrid_bind

(PECL CUBRID >= 8.3.0)

cubrid_bind — Vincula variáveis a instruções preparadas como parâmetros

### Descrição

function cubrid_bind(
resource `$req_identifier`,
int `$bind_index`,
mixed `$bind_value`,
string `$bind_value_type` = ?
): bool

A função cubrid_bind() é usada para vincular valores a marcadores nomeados ou de ponto de interrogação na instrução SQL passada a cubrid_prepare(). Se `bind_value_type` não for informado, string será o tipo padrão.

> Nota: Se o tipo de dado a ser vinculado for BLOB/CLOB, o CUBRID tentará mapear o dado como um fluxo do PHP. Se o tipo real do valor não for um fluxo, o CUBRID o converterá para string e o usará como caminho completo e nome do arquino no sistema de arquivos do cliente. Se o tipo de dado a ser vinculado explicitamente for ENUM, o argumento `bind_value` deve ser o elemento da enumeração que estará no formato de string. No ambiente compartilhado CUBRID, o `bind_value_type` precisa ser incluído na função cubrid_bind().

A tabela a seguir mostra os tipos de valores substitutos.

Tipos de dados vinculados CUBRID
Suporte | Tipo Vinculado | Tipo SQL Correspondente
--- | --- | ---
Suportado | STRING | CHAR, VARCHAR
| NCHAR | NCHAR, NVARCHAR
| BIT | BIT, VARBIT
| NUMERIC ou NUMBER | SHORT, INT, NUMERIC
| FLOAT | FLOAT
| DOUBLE | DOUBLE
| TIME | TIME
| DATE | DATE
| TIMESTAMP | TIMESTAMP
| OBJECT | OBJECT
| ENUM | ENUM
| BLOB | BLOB
| CLOB | CLOB
| NULL | NULL
Não Suportado | SET | SET
| MULTISET | MULTISET
| SEQUENCE | SEQUENCE

### Parâmetros

`req_identifier`
  Identificador de requisição como um resultado de cubrid_prepare().
`bind_index`
  Localização dos parâmetros de vinculação. Inicia com 1.
`bind_value`
  Valor real para vinculação.
`bind_value_type`
  Um tipo de valor a vincular. Omitido por padrão. Assim, o sistema usa string internamente por padrão. No entanto, é necessário especificar o tipo exato do valor como um argumento quando ele for NCHAR, BIT, ou BLOB/CLOB.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.1 | Adicionado suporte aos tipos de dados BLOB/CLOB.

### Exemplos

Exemplo #1 Exemplo de cubrid_bind()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $result = cubrid_execute($conn, "SELECT code FROM event WHERE sports='Basketball' and gender='M'");
    $row = cubrid_fetch_array($result, CUBRID_ASSOC);
    $event_code = $row["code"];

    cubrid_close_request($result);

    $game_req = cubrid_prepare($conn, "SELECT athlete_code FROM game WHERE host_year=1992 and event_code=? and nation_code='USA'");
    cubrid_bind($game_req, 1, $event_code, "number");
    cubrid_execute($game_req);

    printf("--- Time dos Sonhos (Time de basquete olímpico masculino dos Estados Unidos de 1992) ---\n");
    while ($athlete_code = cubrid_fetch_array($game_req, CUBRID_NUM)) {
        $athlete_req = cubrid_prepare($conn, "SELECT name FROM athlete WHERE code=? AND nation_code='USA' AND event='Basketball' AND gender='M'");
        cubrid_bind($athlete_req, 1, $athlete_code[0], "number");
        cubrid_execute($athlete_req);
        $row = cubrid_fetch_assoc($athlete_req);
        printf("%s\n", $row["name"]);
    }

    cubrid_close_request($game_req);
    cubrid_close_request($athlete_req);

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    --- Time dos Sonhos (Time de basquete olímpico masculino dos Estados Unidos de 1992) ---
    Stockton John
    Robinson David
    Pippen Scottie
    Mullin C.
    Malone Karl
    Laettner C.
    Jordan Michael
    Johnson Earvin
    Ewing Patrick
    Drexler Clyde
    Bird Larry
    Barkley Charles

Exemplo #2 Exemplo de cubrid_bind() com CLOB

    <?php
    $con = cubrid_connect("localhost", 33000, "demodb", "dba", "");
    if ($con) {
        cubrid_execute($con,"DROP TABLE if exists php_cubrid_lob_test");
        cubrid_execute($con,"CREATE TABLE php_cubrid_lob_test (doc_content CLOB)");
        $sql = "INSERT INTO php_cubrid_lob_test(doc_content) VALUES(?)";
        $req = cubrid_prepare($con, $sql);

        $fp = fopen("book.txt", "rb");

        cubrid_bind($req, 1, $fp, "clob");
        cubrid_execute($req);
    }
    ?>

Exemplo #3 Exemplo de cubrid_bind() com BLOB

    <?php
    $con = cubrid_connect("localhost", 33000, "demodb", "dba", "");
    if ($con) {
        cubrid_execute($con,"DROP TABLE if exists php_cubrid_lob_test");
        cubrid_execute($con,"CREATE TABLE php_cubrid_lob_test (image BLOB)");
        $sql = "INSERT INTO php_cubrid_lob_test(image) VALUES(?)";
        $req = cubrid_prepare($con, $sql);

        cubrid_bind($req, 1, "cubrid_logo.png", "blob");
        cubrid_execute($req);
    }
    ?>

### Veja Também

- cubrid_execute() - Executa uma instrução preparada SQL
- cubrid_prepare() - Prepara uma instrução SQL para execução

# cubrid_close_prepare

(PECL CUBRID >= 8.3.0)

cubrid_close_prepare — Fecha o identificador de requisição

### Descrição

function cubrid_close_prepare(resource `$req_identifier`): bool

A função cubrid_close_prepare() fecha o identificador de requisição informado no parâmetro `req_identifier` e libera a região de memória relacionada a ele. É um sinônimo para a função cubrid_close_request().

### Parâmetros

`req_identifier`
  Identificador da requisição.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de cubrid_close_prepare()

    <?php
    $con = cubrid_connect ("localhost", 33000, "demodb", "dba", "");
    if ($con) {
       echo "conectado com sucesso";
       $req = cubrid_execute ( $con, "select * from members",
                               CUBRID_INCLUDE_OID | CUBRID_ASYNC);
       if ($req) {
          while ( list ($id, $name) = cubrid_fetch ($req) ){
             echo $id;
             echo $name;
          }
          cubrid_close_prepare($req); // ou pode ser usado cubrid_close_request($req)
       }
       cubrid_disconnect($con);
    }
    ?>

### Veja Também

- cubrid_close_request() - Fecha o identificador de requisição

# cubrid_close_request

(PECL CUBRID >= 8.3.0)

cubrid_close_request — Fecha o identificador de requisição

### Descrição

function cubrid_close_request(resource `$req_identifier`): bool

A função cubrid_close_request() fecha o identificador de requisição informado no parâmetro `req_identifier` e libera a região de memória relacionada a ele. É um sinônimo para a função cubrid_close_prepare().

### Parâmetros

`req_identifier`
  Identificador da requisição.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de cubrid_close_request()

    <?php
    $con = cubrid_connect ("localhost", 33000, "demodb", "dba", "");
    if ($con) {
       echo "conectado com sucesso";
       $req = cubrid_execute ( $con, "select * from members",
                               CUBRID_INCLUDE_OID | CUBRID_ASYNC);
       if ($req) {
          while ( list ($id, $name) = cubrid_fetch ($req) ){
             echo $id;
             echo $name;
          }
          cubrid_close_request($req); // ou pode ser usado cubrid_close_prepare($req)
       }
       cubrid_disconnect($con);
    }
    ?>

### Veja Também

- cubrid_close_prepare() - Fecha o identificador de requisição

# cubrid_col_get

(PECL CUBRID >= 8.3.0)

cubrid_col_get — Obtém conteúdo de coluna tipo coleção usando OID

### Descrição

function cubrid_col_get(resource `$conn_identifier`, string `$oid`, string `$attr_name`): array

A função cubrid_col_get() é usada para obter conteúdo dos elementos do atributo tipo coleção (conjunto, multi-conjunto, sequência), como um array.

### Parâmetros

`conn_identifier`
  Identificador da conexão.
`oid`
  OID da instância a ser lida.
`attr_name`
  Nome do atributo a ser lido da instância.

### Valor Retornado

Array (numérico, iniciando em 0) contendo os elementos solicitados em caso de sucesso.

`false` (para distinguir entre um erro e uma situação em que o atributo tem uma coleção vazia ou NULL, em caso de erro, uma mensagem de alerta é mostrada; neste caso o erro pode ser verificado usando a função cubrid_error_code()), em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_col_get()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    $size = cubrid_col_size($conn, $oid, "b");
    var_dump($size);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    int(3)

# cubrid_col_size

(PECL CUBRID >= 8.3.0)

cubrid_col_size — Obtém o número de elementos de coluna tipo coleção usando OID

### Descrição

function cubrid_col_size(resource `$conn_identifier`, string `$oid`, string `$attr_name`): int

A função cubrid_col_size() é usada para obter o número de elementos em um atributo tipo coleção (conjunto, multi-conjunto, sequência).

### Parâmetros

`conn_identifier`
  Identificador de conexão.
`oid`
  OID da instância a ser lida.
`attr_name`
  Nome do atributo a ser lido da instância.

### Valor Retornado

Número de elementos em caso de sucesso, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.1 | Alteração no valor de retorno: em caso de falha, retorna false e não -1.

### Exemplos

Exemplo #1 Exemplo de cubrid_col_size()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    $size = cubrid_col_size($conn, $oid, "b");
    var_dump($size);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    int(3)

# cubrid_column_names

(PECL CUBRID >= 8.3.0)

cubrid_column_names — Obtém nomes de colunas no resultado

### Descrição

function cubrid_column_names(resource `$req_identifier`): array

A função cubrid_column_names() é usada para obter os nomes das colunas do resultado da consulta usando o identificador de requisição informado em `req_identifier`.

### Parâmetros

`req_identifier`
  Identificador de requisição.

### Valor Retornado

Array de strings contendo os nomes de colunas em caso de sucesso, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_column_names()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $column_names = cubrid_column_names($result);
    $column_types = cubrid_column_types($result);

    printf("%-30s %-30s %-15s\n", "Nomes das Colunas", "Tipos das Colunas", "Comp. Máx. das Colunas");
    for($i = 0, $size = count($column_names); $i < $size; $i++) {
        $column_len = cubrid_field_len($result, $i);
        printf("%-30s %-30s %-15s\n", $column_names[$i], $column_types[$i], $column_len);
    }

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    Nomes das Colunas              Tipos das Colunas              Comp. Máx. das Colunas
    host_year                      integer                        11
    event_code                     integer                        11
    athlete_code                   integer                        11
    stadium_code                   integer                        11
    nation_code                    char                           3
    medal                          char                           1
    game_date                      date                           10

### Veja Também

- cubrid_prepare() - Prepara uma instrução SQL para execução
- cubrid_execute() - Executa uma instrução preparada SQL
- cubrid_column_types() - Obtém tipos de colunas no resultado

# cubrid_column_types

(PECL CUBRID >= 8.3.0)

cubrid_column_types — Obtém tipos de colunas no resultado

### Descrição

function cubrid_column_types(resource `$req_identifier`): array

A função cubrid_column_types() obtém tipos de colunas dos resultados da consulta usando o identificador de requisição informado em `req_identifier`.

### Parâmetros

`req_identifier`
  Identificador de requisição.

### Valor Retornado

Array de strings contendo os tipos de colunas em caso de sucesso, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_column_types()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $column_names = cubrid_column_names($result);
    $column_types = cubrid_column_types($result);

    printf("%-30s %-30s %-15s\n", "Nomes das Colunas", "Tipos das Colunas", "Comp. Máx. das Colunas");
    for($i = 0, $size = count($column_names); $i < $size; $i++) {
        $column_len = cubrid_field_len($result, $i);
        printf("%-30s %-30s %-15s\n", $column_names[$i], $column_types[$i], $column_len);
    }

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    Nomes das Colunas              Tipos das Colunas              Comp. Máx. das Colunas
    host_year                      integer                        11
    event_code                     integer                        11
    athlete_code                   integer                        11
    stadium_code                   integer                        11
    nation_code                    char                           3
    medal                          char                           1
    game_date                      date                           10

### Veja Também

- cubrid_column_names() - Obtém nomes de colunas no resultado
- cubrid_prepare() - Prepara uma instrução SQL para execução
- cubrid_execute() - Executa uma instrução preparada SQL

# cubrid_commit

(PECL CUBRID >= 8.3.0)

cubrid_commit — Confirma uma transação

### Descrição

function cubrid_commit(resource `$conn_identifier`): bool

A função cubrid_commit() é usada para executar a confirmação na transação apontada por `conn_identifier`, atualmente em progresso. A conexão ao servidor é fechada depois que a função cubrid_commit() é chamada; No entanto, o identificador da conexão continuará válido.

No CUBRID PHP, o modo de auto-confirmação é desligado por padrão para gerenciamento de transação. Pode ser definido pela função cubrid_set_autocommit(). O status pode ser obtido pela função cubrid_get_autocommit(). Antes do início de uma transação, lembre-se de desligar o modo de auto-confirmação.

### Parâmetros

`conn_identifier`
  Identificador da conexão.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_commit()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE publishers");

    $sql = <<<EOD
    CREATE TABLE publishers(
    pub_id CHAR(3),
    pub_name VARCHAR(20),
    city VARCHAR(15),
    state CHAR(2),
    country VARCHAR(15)
    )
    EOD;
    cubrid_set_autocommit($conn,false);
    if (!cubrid_execute($conn, $sql)) {
        printf("Módulo do erro: %d\nCódigo do erro: %d\nMensagem de erro: %s\n", cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

        cubrid_disconnect($conn);
        exit;
    }

    $req = cubrid_prepare($conn, "INSERT INTO publishers VALUES(?, ?, ?, ?, ?)");

    $id_list = array("P01", "P02", "P03", "P04");
    $name_list = array("Abatis Publishers", "Core Dump Books", "Schadenfreude Press", "Tenterhooks Press");
    $city_list = array("New York", "San Francisco", "Hamburg", "Berkeley");
    $state_list = array("NY", "CA", NULL, "CA");
    $country_list = array("USA", "USA", "Germany", "USA");

    for ($i = 0, $size = count($id_list); $i < $size; $i++) {
        cubrid_bind($req, 1, $id_list[$i]);
        cubrid_bind($req, 2, $name_list[$i]);
        cubrid_bind($req, 3, $city_list[$i]);
        cubrid_bind($req, 4, $state_list[$i]);
        cubrid_bind($req, 5, $country_list[$i]);

        if (!($ret = cubrid_execute($req))) {
            break;
        }
    }

    if (!$ret) {
        cubrid_rollback($conn);
    } else {
        cubrid_commit($conn);

        $req = cubrid_execute($conn, "SELECT * FROM publishers");
        while ($result = cubrid_fetch_assoc($req)) {
            printf("%-3s %-20s %-15s %-3s %-15s\n",
                $result["pub_id"], $result["pub_name"], $result["city"], $result["state"], $result["country"]);
        }
    }

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    P01 Abatis Publishers    New York        NY  USA
    P02 Core Dump Books      San Francisco   CA  USA
    P03 Schadenfreude Press  Hamburg             Germany
    P04 Tenterhooks Press    Berkeley        CA  USA

### Veja Também

- cubrid_rollback() - Reverte uma transação
- cubrid_get_autocommit() - Obtém o modo de auto-confirmação da conexão
- cubrid_set_autocommit() - Define o modo de auto-confirmação da conexão

# cubrid_connect

(PECL CUBRID >= 8.3.1)

cubrid_connect — Abre uma conexão a um servidor CUBRID

### Descrição

function cubrid_connect(
string `$host`,
int `$port`,
string `$dbname`,
string `$userid` = ?,
string `$passwd` = ?,
bool `$new_link` = `false`
): resource

A função cubrid_connect() é usada para estabelecer o ambiente para conexão ao servidor usando o endereço do servidor, número da porta, nome do banco de dados, nome de usuário e senha. Se o nome de usuário e a senha não forem informados, a conexão "PUBLIC" será realizada por padrão.

### Parâmetros

`host`
  Nome de servidor ou endereço IP do servidor CUBRID CAS.
`port`
  Número da porta do servidor CUBRID CAS (BROKER_PORT configurado em $CUBRID/conf/cubrid_broker.conf).
`dbname`
  Nome do banco de dados.
`userid`
  Nome de usuário do banco de dados. Se não for informado, o valor padrão será “público”.
`passwd`
  Senha do usuário. Se não for informado, o valor padrão será "".
`new_link`
  Se uma segunda chamada for feita a cubrid_connect() com os mesmos argumentos, nenhuma nova conexão será estabelecida, mas em vez disso, o identificador da conexão já aberta será retornado. O parâmetro `new_link` modifica este comportamento e faz com que cubrid_connect() sempre abra uma nova conexão, mesmo que cubrid_connect() tenha sido chamada antes com os mesmos parâmetros.

### Valor Retornado

Identificador da conexão em caso de sucesso, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_connect()

    <?php
    printf("%-34s %s\n", "Versão do CUBRID PHP:", cubrid_version());

    printf("\n");

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    if (!$conn) {
        die('Erro de conexão ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-34s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-34s %s\n", "Informação do Servidor:", $server_info);
    printf("%-34s %s\n", "Informação do Cliente:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-34s %s\n", "Conjunto de caracteres do CUBRID:", $charset);

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    Versão do CUBRID PHP:              9.1.0.0001

    PARAM_ISOLATION_LEVEL              3
    LOCK_TIMEOUT                       -1
    MAX_STRING_LENGTH                  1073741823
    PARAM_AUTO_COMMIT                  1

    Informação do Servidor:            9.1.0.0212
    Informação do Cliente:             9.1.0

    Conjunto de caracteres do CUBRID:  iso8859-1

### Veja Também

- cubrid_pconnect() - Abre uma conexão persistente a um servidor CUBRID
- cubrid_connect_with_url() - Prepara o ambiente para conexão ao servidor CUBRID
- cubrid_pconnect_with_url() - Abre uma conexão persistente com o servidor CUBRID
- cubrid_disconnect() - Fecha uma conexão ao banco de dados
- cubrid_close() - Fecha conexão CUBRID

# cubrid_connect_with_url

(PECL CUBRID >= 8.3.1)

cubrid_connect_with_url — Prepara o ambiente para conexão ao servidor CUBRID

### Descrição

function cubrid_connect_with_url(
string `$conn_url`,
string `$userid` = ?,
string `$passwd` = ?,
bool `$new_link` = `false`
): resource

A função cubrid_connect_with_url() é usada para estabelecer o ambiente para conexão ao servidor usando informação passada por um argumento URL no formato string. Se o recurso HA estiver habilitado no CUBRID, é necessário especificar a informação de conexão do servidor reserva, que é usado em caso de falha, na string do argumento de URL desta função. Se o usuário e a senha não forem informados, a conexão "PUBLIC" será realizada por padrão.

<url> ::= CUBRID:<host>:<db_name>:<db_user>:<db_password>:[?<properties>]

<properties> ::= <property> [&<property>]

<properties> ::= alhosts=<alternative_hosts>[ &rctime=<time>]

<properties> ::= login_timeout=<milli_sec>

<properties> ::= query_timeout=<milli_sec>

<properties> ::= disconnect_on_query_timeout=true|false

<alternative_hosts> ::= <standby_broker1_host>:<port> [,<standby_broker2_host>:<port>]

<host> := HOSTNAME | IP_ADDR

<time> := SECOND

<milli_sec> := MILLI SECOND

- host : Nome do servidor ou endereço IP do banco de dados mestre
- db_name : Nome do banco de dados
- db_user : Nome de usuário do banco de dados
- db_password : Senha de usuário do banco de dados
- alhosts : Especifica as informações do mediador do servidor reserva, que são usadas em caso de falha quando for impossível conectar-se ao servidor ativo. Pode-se especificar vários mediadores para casos de falha e a tentativa de conexão ao mediadores é realizada na ordem listada em "alhosts"
- rctime : Um intervalo entre as tentativas de conexão ao mediador ativo no qual ocorreu a falha. Após ocorrer uma falha, o sistema se conecta ao mediador especificado por "althosts", encerra a transação e, em seguida, tenta se conectar ao mediador ativo do banco de dados mestre a cada "rctime". O valor padrão é 600 segundos.
- login_timeout : Tempo limite (unidade: milissegundos) para se registrar no banco de dados. O padrão é 0, que significa infinito.
- query_timeout : Tempo limite (unidade: milissegundos) para requisição de consulta. Quando o limite é atingido, é enviada uma mensagem ao servidor para cancelar a consulta requisitada. O valor de retorno vai depender da configuração disconnect_on_query_timeout; embora a mensagem para cancelar a requisição seja enviada ao servidor, a requisição poderá ser bem sucedida.
- disconnect_on_query_timeout : Configura um valor para retornar imediatamente um erro de função sendo executada após o tempo limite. O padrão é "false".

> Nota: `?` e `:` são usados como identificadores na URL de conexão do PHP e não podem ser incluídos na senha. O exemplo a seguir é uma senha inválida para URL de conexão por conter "`?:`". $url = "CUBRID:localhost:33000:tdb:dba:12?:?login_timeout=100"; Senhas que contêm `?` ou `:` podem ser passadas como parâmetro separado. $url = "CUBRID:localhost:33000:tbd:::?login_timeout=100"; $conn = cubrid_connect_with_url($url, "dba", "12?"); Se o usuário ou a senha estiverem vazios, o caractere "`:`" não pode ser omitido, veja este exemplo: $url = "CUBRID:localhost:33000:demodb:::";

### Parâmetros

`conn_url`
  Uma string contendo informação de conexão ao servidor.
`userid`
  Nome de usuário para o banco de dados.
`passwd`
  Senha do usuário.
`new_link`
  Se uma segunda chamada for feita a cubrid_connect_with_url() com os mesmos argumentos, nenhuma nova conexão será estabelecida, mas em vez disso, o identificador da conexão já aberta será retornado. O parâmetro `new_link` modifica este comportamento e faz com que cubrid_connect_with_url() sempre abra uma nova conexão, mesmo que cubrid_connect_with_url() tenha sido chamada antes com os mesmos parâmetros.

### Valor Retornado

Identificador da conexão em caso de sucesso, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_connect_with_url() e URL sem propriedades

    <?php
    $conn_url = "CUBRID:localhost:33000:demodb:dba::";
    $con = cubrid_connect_with_url($conn_url);

    if ($con) {
        echo "conectado com sucesso";
        cubrid_execute($con, "create table person(id int,name char(16))");
        $req =cubrid_execute($con, "insert into person values(1,'James')");

        if ($req) {
            cubrid_close_request($req);
            cubrid_commit($con);
        } else {
            cubrid_rollback($con);
        }
        cubrid_disconnect($con);
    }
    ?>

Exemplo #2 Exemplo de cubrid_connect_with_url() e URL com propriedades

    <?php
    $conn_url = "CUBRID:127.0.0.1:33000:demodb:dba::?login_timeout=100";
    $con = cubrid_connect_with_url ($conn_url);

    if ($con) {
        echo "conectado com sucesso";
        cubrid_execute($con, "create table person(id int,name char(16))");
        $req =cubrid_execute($con, "insert into person values(1,'James')");

        if ($req) {
            cubrid_close_request($req);
            cubrid_commit($con);
        } else {
            cubrid_rollback($con);
        }
        cubrid_disconnect($con);
    }
    ?>

### Veja Também

- cubrid_connect() - Abre uma conexão a um servidor CUBRID
- cubrid_pconnect() - Abre uma conexão persistente a um servidor CUBRID
- cubrid_pconnect_with_url() - Abre uma conexão persistente com o servidor CUBRID
- cubrid_disconnect() - Fecha uma conexão ao banco de dados
- cubrid_close() - Fecha conexão CUBRID

# cubrid_current_oid

(PECL CUBRID >= 8.3.0)

cubrid_current_oid — Obtém o OID da posição atual do cursor

### Descrição

function cubrid_current_oid(resource `$req_identifier`): string

A função cubrid_current_oid() é usada para obter o OID da posição atual do cursor no resultado da consulta. Para usar cubrid_current_oid(), a consulta executada precisa ser atualizável e a opção `CUBRID_INCLUDE_OID` incluída durante sua execução.

### Parâmetros

`req_identifier`
  Identificador de requisição.

### Valor Retornado

OID da posição atual do cursor em caso de sucesso, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_current_oid()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $req = cubrid_execute($conn, "SELECT * FROM code", CUBRID_INCLUDE_OID);
    $oid = cubrid_current_oid($req);
    $res = cubrid_get($conn, $oid);

    print_r($res);

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    Array
    (
        [s_name] => X
        [f_name] => Mixed
    )

### Veja Também

- cubrid_execute() - Executa uma instrução preparada SQL

# cubrid_disconnect

(PECL CUBRID >= 8.3.0)

cubrid_disconnect — Fecha uma conexão ao banco de dados

### Descrição

function cubrid_disconnect(resource `$conn_identifier` = ?): bool

A função cubrid_disconnect() fecha o identificador da conexão e desconecta do servidor. Se algum identificador de requisição não estiver fechado neste ponto, ele será fechado. É similar à função compatível do MySQL CUBRID cubrid_close().

### Parâmetros

`conn_identifier`
  Identificador da conexão.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_disconnect()

    <?php
    $con = cubrid_connect ("localhost", 33000, "demodb");
    if ($con) {
        echo "conectado com sucesso";

        $req = cubrid_execute( $con, "create table person(id int,name char(10))");
        if ($req) {
            cubrid_close_request($req);
            cubrid_commit($con);
        } else {
            cubrid_rollback($con);
        }

        $req = cubrid_execute( $con, "insert into person values(1,'James')");
        if ($req) {
            cubrid_close_request($req);
            cubrid_commit($con);
        } else {
            cubrid_rollback($con);
        }
        cubrid_disconnect($con);
    }
    ?>

### Veja Também

- cubrid_close() - Fecha conexão CUBRID
- cubrid_connect() - Abre uma conexão a um servidor CUBRID
- cubrid_connect_with_url() - Prepara o ambiente para conexão ao servidor CUBRID

# cubrid_drop

(PECL CUBRID >= 8.3.0)

cubrid_drop — Remove uma instância usando OID

### Descrição

function cubrid_drop(resource `$conn_identifier`, string `$oid`): bool

A função cubrid_drop() é usada para remover uma instância do banco de dados usando o `oid` da instância.

### Parâmetros

`conn_identifier`
  Identificador da conexão.
`oid`
  OID da instância a ser removida.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_drop()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    printf("--- Antes da Remoção: ---\n");
    $attr = cubrid_get($conn, $oid);
    var_dump($attr);

    if (cubrid_drop($conn, $oid)) {
        cubrid_commit($conn);
    } else {
        cubrid_rollback($conn);
    }

    cubrid_close_request($req);

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    printf("\n--- Depois da Remoção: ---\n");
    $attr = cubrid_get($conn, $oid);
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    --- Antes da Remoção: ---
    array(4) {
      ["a"]=>
      string(1) "1"
      ["b"]=>
      array(3) {
        [0]=>
        string(1) "1"
        [1]=>
        string(1) "2"
        [2]=>
        string(1) "3"
      }
      ["c"]=>
      array(4) {
        [0]=>
        string(2) "11"
        [1]=>
        string(2) "22"
        [2]=>
        string(2) "33"
        [3]=>
        string(3) "333"
      }
      ["d"]=>
      string(10) "a         "
    }

    --- Depois da Remoção: ---
    array(4) {
      ["a"]=>
      string(1) "2"
      ["b"]=>
      array(3) {
        [0]=>
        string(1) "4"
        [1]=>
        string(1) "5"
        [2]=>
        string(1) "7"
      }
      ["c"]=>
      array(4) {
        [0]=>
        string(2) "44"
        [1]=>
        string(2) "55"
        [2]=>
        string(2) "66"
        [3]=>
        string(3) "666"
      }
      ["d"]=>
      string(10) "b         "
    }

### Veja Também

- cubrid_is_instance() - Verifica se a instância apontada pelo OID existe

# cubrid_error_code

(PECL CUBRID >= 8.3.0)

cubrid_error_code — Obtém código de erro para a chamada de função mais recente

### Descrição

function cubrid_error_code(): int

A função cubrid_error_code() é usada para obter o código do erro ocorrido durante a execução da API. Normalmente, obtém-se o código de erro quando a API retorna FALSE.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Código do erro ocorrido ou `0` (zero) se nenhum erro ocorreu.

### Exemplos

Exemplo #1 Exemplo de cubrid_error_code()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_prepare($conn , "SELECT * FROM code WHERE s_name=?");

    $req = @cubrid_execute($req);
    if (!$req) {
        printf("Módulo do erro: %d\nCódigo do erro: %d\nMensagem de erro: %s\n",
            cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

        cubrid_disconnect($conn);
        exit;
    }
    ?>

O exemplo acima produzirá:

    Módulo do erro: 4
    Código do erro: -30015
    Mensagem de erro: Some parameter not binded

### Veja Também

- cubrid_error_code_facility() - Obtém o código do módulo do erro
- cubrid_error_msg() - Obtém mensagem de erro da chamada de função mais recente

# cubrid_error_code_facility

(PECL CUBRID >= 8.3.0)

cubrid_error_code_facility — Obtém o código do módulo do erro

### Descrição

function cubrid_error_code_facility(): int

A função cubrid_error_code_facility() é usada para obter o código do módulo (camada onde o erro ocorreu) do código do erro ocorrido durante execução da API. Normalmente, pode-se obter o código de erro quando a API retorna FALSE.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Código do módulo onde ocorreu o erro: `CUBRID_FACILITY_DBMS`, `CUBRID_FACILITY_CAS`, `CUBRID_FACILITY_CCI` ou `CUBRID_FACILITY_CLIENT`.

### Exemplos

Exemplo #1 Exemplo de cubrid_error_code_facility()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = @cubrid_execute($conn, "SELECT * FROM unknown");
    if (!$req) {
        printf("Módulo do erro: %d\nCódigo do erro: %d\nMensagem de erro: %s\n",
            cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

        cubrid_disconnect($conn);
        exit;
    }
    ?>

O exemplo acima produzirá:

    Módulo do erro: 1
    Código do erro: -493
    Mensagem de erro: Syntax: In line 1, column 15 before END OF STATEMENT
    Syntax error: unexpected 'unknown'

### Veja Também

- cubrid_error_code() - Obtém código de erro para a chamada de função mais recente
- cubrid_error_msg() - Obtém mensagem de erro da chamada de função mais recente

# cubrid_error_msg

(PECL CUBRID >= 8.3.0)

cubrid_error_msg — Obtém mensagem de erro da chamada de função mais recente

### Descrição

function cubrid_error_msg(): string

A função cubrid_error_msg() é usada para obter a mensagem de erro ocorrida durante execução da API CUBRID. Normalmente, a mensagem de erro é obtida quando a API retorna FALSE.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Mensagem do erro ocorrido.

### Exemplos

Exemplo #1 Exemplo de cubrid_error_msg()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    if (!@cubrid_schema($conn, 100000)) {
        printf("Módulo do erro: %d\nCódigo do erro: %d\nMensagem de erro: %s\n",
            cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

        cubrid_disconnect($conn);
        exit;
    }
    ?>

O exemplo acima produzirá:

    Módulo do erro: 2
    Código do erro: -10015
    Mensagem de erro: Invalid T_CCI_SCH_TYPE value

### Veja Também

- cubrid_error_code() - Obtém código de erro para a chamada de função mais recente
- cubrid_error_code_facility() - Obtém o código do módulo do erro

# cubrid_execute

(PECL CUBRID >= 8.3.0)

cubrid_execute — Executa uma instrução preparada SQL

### Descrição

function cubrid_execute(resource `$conn_identifier`, string `$sql`, int `$option` = 0): resource
function cubrid_execute(resource `$request_identifier`, int `$option` = 0): bool

A função cubrid_execute() é usada para executar a instrução SQL fornecida. Ela executa a consulta usando `conn_identifier` e a instrução SQL, e então retorna o identificador de requisição criado. É usada para execução simples de consulta, onde a vinculação de parâmetros não é necessária. Além disso, a função cubrid_execute() é usada para executar a instrução preparada por meio de cubrid_prepare() e cubrid_bind(). Neste momento, é necessário especificar argumentos de `request_identifier` e `option`.

O parâmetro `option` é usado para determinar se o OID deve ser obtido após a execução da consulta e se a consulta deve ser executada em modo síncrono ou assíncrono. `CUBRID_INCLUDE_OID` e `CUBRID_ASYNC` (ou `CUBRID_EXEC_QUERY_ALL` se a intenção for executar múltiplas instruções SQL) podem ser especificadas usando um operador OR bit a bit. Se não for especificado, nenhuma delas será selecionada. Se a opção `CUBRID_EXEC_QUERY_ALL` estiver definida, um modo síncrono (sync_mode) será usado para recuperar os resultados da consulta e, nesses casos, as seguintes regras serão aplicadas:

- O valor de retorno é o resultado da primeira consulta.
- Se ocorrer um erro em alguma consulta, a execução será processada como uma falha.
- Em uma consulta composta por q1 q2 q3, se ocorrer um erro em q2 após q1 ter sucesso na execução, o resultado de q1 permanecerá válido. Ou seja, as execuções de consulta anteriores bem-sucedidas não são revertidas quando ocorre um erro.
- Se uma consulta for executada com sucesso, o resultado da segunda consulta pode ser obtido usando cubrid_next_result().

Se o primeiro argumento for `request_identifier` para executar a função cubrid_prepare(), pode-se especificar uma opção, apenas `CUBRID_ASYNC`.

### Parâmetros

`conn_identifier`
  Identificador da conexão.
`sql`
  Instrução SQL a ser executada.
`option`
  Opção de execução da consulta: `CUBRID_INCLUDE_OID`, `CUBRID_ASYNC` ou `CUBRID_EXEC_QUERY_ALL`.
`request_identifier`
  Identificador de cubrid_prepare().

### Valor Retornado

Identificador da requisição, em caso de sucesso e quando o primeiro parâmetro for conn_identifier; `true`, em caso de sucesso e quando o primeiro parâmetro for request_identifier, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Adicionada a nova opção `CUBRID_EXEC_QUERY_ALL`.

### Exemplos

Exemplo #1 Exemplo de cubrid_execute()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $result = cubrid_execute($conn, "SELECT code FROM event WHERE name='100m Butterfly' and gender='M'", CUBRID_ASYNC);
    $row = cubrid_fetch_array($result, CUBRID_ASSOC);
    $event_code = $row["code"];

    cubrid_close_request($result);

    $history_req = cubrid_prepare($conn, "SELECT * FROM history WHERE event_code=?");
    cubrid_bind($history_req, 1, $event_code, "number");
    cubrid_execute($history_req);

    printf("%-20s %-9s %-10s %-5s\n", "Atleta", "Ano", "Pontos", "Unidade");
    while ($row = cubrid_fetch_array($history_req, CUBRID_ASSOC)) {
        printf("%-20s %-9s %-10s %-5s\n",
            $row["athlete"], $row["host_year"], $row["score"], $row["unit"]);
    }

    cubrid_close_request($history_req);

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    Atleta               Ano       Pontos     Unidade
    Phelps Michael       2004      51.25      time

### Veja Também

- cubrid_prepare() - Prepara uma instrução SQL para execução
- cubrid_bind() - Vincula variáveis a instruções preparadas como parâmetros
- cubrid_next_result() - Obtém o resultado da próxima consulta quando múltiplas instruções SQL estão sendo executadas
- cubrid_close_request() - Fecha o identificador de requisição
- cubrid_commit() - Confirma uma transação
- cubrid_rollback() - Reverte uma transação

# cubrid_fetch

(PECL CUBRID >= 8.3.0)

cubrid_fetch — Busca a próxima linha do conjunto de resultados

### Descrição

function cubrid_fetch(resource `$result`, int `$type` = CUBRID_BOTH): mixed

A função cubrid_fetch() é usada para obter uma única linha do resultado da consulta. O cursor é movido automaticamente para a linha seguinte após a obtenção do resultado.

### Parâmetros

`result`
  `result` vem de uma chamada a cubrid_execute()
`type`
  Tipo de array do resultado buscado: CUBRID_NUM, CUBRID_ASSOC, CUBRID_BOTH ou CUBRID_OBJECT. Se for necessário operar em um objeto LOB, pode-se usar CUBRID_LOB.

### Valor Retornado

Array de resultados ou objeto em caso de sucesso.

`false`, quando não houver mais linhas; NULL em caso de falha.

O resultado pode ser recebido como um array ou como um objeto e pode-se decidir que tipo de dados será usado configurando-se o parâmetro `type`. O parâmetro `type` pode ser definido para um dos seguintes valores:

- CUBRID_NUM : array numérico (iniciando em 0)
- CUBRID_ASSOC : array associativo
- CUBRID_BOTH : array numérico e associativo (padrão)
- CUBRID_OBJECT : objeto que tem o nome de atributo como o nome da coluna do resultado da consulta

Quando o argumento `type` for omitido, o resultado será recebido usando a opção CUBRID_BOTH como padrão. Quando a intenção for receber o resultado como um objeto, o nome da coluna do resultado precisa seguir as regras de nomes de identificadores do PHP. Por exemplo, um nome de coluna "count(*)" não pode ser recebido como um objeto.

### Exemplos

Exemplo #1 Exemplo de cubrid_fetch()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT * FROM stadium WHERE nation_code='GRE' AND seats > 10000");

    printf("%-40s %-10s %-9s %-20s\n", "nome", "área", "assentos", "endereço");
    while ($row = cubrid_fetch($req)) {
        printf("%-40s %-10s %-9s %-20s\n",
            $row["name"], $row["area"], $row["seats"], $row["address"]);
    }

    // se for desejado operar em objeto LOB, pode-se usar cubrid_fetch($req, CUBRID_LOB)

    cubrid_close_request($req);

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    nome                                     área       assentos  endereço
    Panathinaiko Stadium                     86300.00   50000     Athens, Greece
    Olympic Stadium                          54700.00   13000     Athens, Greece
    Olympic Indoor Hall                      34100.00   18800     Athens, Greece
    Olympic Hall                             52400.00   21000     Athens, Greece
    Olympic Aquatic Centre                   42500.00   11500     Athens, Greece
    Markopoulo Olympic Equestrian Centre     64000.00   15000     Markopoulo, Athens, Greece
    Faliro Coastal Zone Olympic Complex      34650.00   12171     Faliro, Athens, Greece
    Athens Olympic Stadium                   120400.00  71030     Maroussi, Athens, Greece
    Ano Liossia                              34000.00   12000     Ano Liosia, Athens, Greece

### Veja Também

- cubrid_execute() - Executa uma instrução preparada SQL
- cubrid_fetch_array() - Busca uma linha de resultado como um array associativo, numérico ou ambos
- cubrid_fetch_row() - Retorna um array numérico com os valores da linha atual
- cubrid_fetch_assoc() - Retorna o array associativo que corresponde à linha buscada
- cubrid_fetch_object() - Busca a próxima linha e retorna-a como um objeto

# cubrid_free_result

(PECL CUBRID >= 8.3.0)

cubrid_free_result — Libera a memória ocupada pelos dados do resultado

### Descrição

function cubrid_free_result(resource `$req_identifier`): bool

Esta função libera a memória ocupada pelos dados do resultado. Ela retorna `true` em caso de sucesso ou `false` em caso de falha. Observe que ela só pode liberar o buffer de busca do cliente, e se a intenção for liberar toda a memória, use a função cubrid_close_request().

### Parâmetros

`req_identifier`
  Identificador da requisição.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_free_result()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $req = cubrid_execute($conn, "SELECT * FROM history WHERE host_year=2004 ORDER BY event_code");
    $row = cubrid_fetch_assoc($req);
    var_dump($row);

    cubrid_free_result($req);
    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    array(5) {
      ["event_code"]=>
      string(5) "20005"
      ["athlete"]=>
      string(12) "Hayes Joanna"
      ["host_year"]=>
      string(4) "2004"
      ["score"]=>
      string(5) "12.37"
      ["unit"]=>
      string(4) "time"
    }

# cubrid_get

(PECL CUBRID >= 8.3.0)

cubrid_get — Obtém um atributo usando OID

### Descrição

function cubrid_get(resource `$conn_identifier`, string `$oid`, mixed `$attr` = ?): mixed

A função cubrid_get() é usada para obter o atributo da instância do `oid` informado. Pode-se obter um atributo único usando o tipo de dados string para o argumento `attr`, ou vários atributos usando o tipo de dados array para o argumento `attr`.

### Parâmetros

`conn_identifier`
  Identificador da conexão.
`oid`
  OID da instância a ser lida.
`attr`
  Nome do atributo a ser lido.

### Valor Retornado

Conteúdo do atributo solicitado, quando o processo for bem-sucedido; Quando `attr` for definido com o tipo de dados string, o resultado será retornado como uma string; quando `attr` for definido com tipo de dados array (array numérico com base 0), o resultado será retornado em um array associativo. Quando `attr` for omitido, todos os atributos serão recebidos em forma de array.

`false` em caso de falha ou quando o resultado for NULL. (Se um erro ocorrer, para distinguir entre string vazia e NULL, uma mensagem de alerta é mostrada. Pode-se verificar o erro com a função cubrid_error_code().)

### Exemplos

Exemplo #1 Exemplo de cubrid_get()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_get($conn, $oid, "b");
    var_dump($attr);

    $attr = cubrid_get($conn, $oid);
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    string(9) "{1, 2, 3}"
    array(4) {
      ["a"]=>
      string(1) "1"
      ["b"]=>
      array(3) {
        [0]=>
        string(1) "1"
        [1]=>
        string(1) "2"
        [2]=>
        string(1) "3"
      }
      ["c"]=>
      array(4) {
        [0]=>
        string(2) "11"
        [1]=>
        string(2) "22"
        [2]=>
        string(2) "33"
        [3]=>
        string(3) "333"
      }
      ["d"]=>
      string(10) "a         "
    }

### Veja Também

- cubrid_put() - Atualiza uma coluna usando OID

# cubrid_get_autocommit

(PECL CUBRID >= 8.4.0)

cubrid_get_autocommit — Obtém o modo de auto-confirmação da conexão

### Descrição

function cubrid_get_autocommit(resource `$conn_identifier`): bool

A função cubrid_get_autocommit() é usada para obter o status do modo de auto-confirmação da conexão ao banco de dados CUBRID.

Para o CUBRID 8.4.0, o modo de auto-confirmação é desabilitado por padrão para o gerenciamento de transações.

Para o CUBRID 8.4.1, o modo de auto-confirmação é habilitado por padrão para o gerenciamento de transações.

### Parâmetros

`conn_identifier`
  Identificador da conexão.

### Valor Retornado

`true`, quando a auto-confirmação estiver ativada.

`false`, quando a auto-confirmação estiver desativada.

`null` em caso de erro.

### Veja Também

- cubrid_set_autocommit() - Define o modo de auto-confirmação da conexão
- cubrid_commit() - Confirma uma transação

# cubrid_get_charset

(PECL CUBRID >= 8.3.0)

cubrid_get_charset — Retorna o conjunto de caracteres da conexão CUBRID atual

### Descrição

function cubrid_get_charset(resource `$conn_identifier`): string

Esta função retorna o conjunto de caracteres da conexão CUBRID atual e é similar à função compatível do MySQL CUBRID cubrid_client_encoding().

### Parâmetros

`conn_identifier`
  A conexão CUBRID.

### Valor Retornado

Uma string que representa o conjunto de caracteres da conexão CUBRID em caso de sucesso, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_get_charset()

    <?php

    $con = cubrid_connect("localhost", 33000, "demodb");
    if (!$con)
    {
        die('Não foi possível conectar.');
    }

    printf("Conjunto de caracteres atual do CUBRID: %s\n", cubrid_get_charset($con));

    ?>

O exemplo acima produzirá:

    Conjunto de caracteres atual do CUBRID: iso8859-1

### Veja Também

- cubrid_client_encoding() - Retorna o conjunto de caracteres de conexão CUBRID atual

# cubrid_get_class_name

(PECL CUBRID >= 8.3.0)

cubrid_get_class_name — Obtém o nome da classe usando OID

### Descrição

function cubrid_get_class_name(resource `$conn_identifier`, string `$oid`): string

A função cubrid_get_class_name() é usada para obter o nome da classe pelo `oid`. Não funciona ao selecionar dados das tabelas de sistema, por exemplo, db_class.

### Parâmetros

`conn_identifier`
  Identificador da conexão.
`oid`
  OID da instância da qual se busca o nome da classe.

### Valor Retornado

Nome da classe em caso de sucesso, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_get_class_name()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $req = cubrid_execute($conn, "SELECT * FROM code", CUBRID_INCLUDE_OID);
    $oid = cubrid_current_oid($req);
    $class_name = cubrid_get_class_name($conn, $oid);

    print_r($class_name);

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    code

### Veja Também

- cubrid_is_instance() - Verifica se a instância apontada pelo OID existe
- cubrid_drop() - Remove uma instância usando OID

# cubrid_get_client_info

(PECL CUBRID >= 8.3.0)

cubrid_get_client_info — Retorna a versão da biblioteca cliente

### Descrição

function cubrid_get_client_info(): string

Esta função retorna uma string que representa a versão da biblioteca cliente.

### Parâmetros

### Valor Retornado

Uma string que representa a versão da biblioteca cliente em caso de sucesso, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_get_client_info()

    <?php
    printf("%-30s %s\n", "Versão do CUBRID PHP:", cubrid_version());

    printf("\n");

    $conn = cubrid_connect("localhost", 33088, "demodb");

    if (!$conn) {
        die('Erro de conexão ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-30s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-30s %s\n", "Informação do servidor:", $server_info);
    printf("%-30s %s\n", "Informação do cliente:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-30s %s\n", "Conjunto de caracteres CUBRID:", $charset);

    cubrid_disconnect($conn);

    ?>

O exemplo acima produzirá:

    Versão do CUBRID PHP:          9.1.0.0001

    PARAM_ISOLATION_LEVEL          3
    LOCK_TIMEOUT                   -1
    MAX_STRING_LENGTH              1073741823
    PARAM_AUTO_COMMIT              1

    Informação do servidor:        9.1.0.0212
    Informação do cliente:         9.1.0

    Conjunto de caracteres CUBRID: iso8859-1

# cubrid_get_db_parameter

(PECL CUBRID >= 8.3.0)

cubrid_get_db_parameter — Retorna os parâmetros do banco de dados CUBRID

### Descrição

function cubrid_get_db_parameter(resource `$conn_identifier`): array

Esta função retorna os parâmetros do banco de dados CUBRID, ou `false` em caso de falha. Retorna um array associativo com os valores para os seguintes parâmetros:

- `PARAM_ISOLATION_LEVEL`
- `PARAM_LOCK_TIMEOUT`
- `PARAM_MAX_STRING_LENGTH`
- `PARAM_AUTO_COMMIT`

Parâmetros do banco de dados
Parâmetro | Descrição
--- | ---
PARAM_ISOLATION_LEVEL | O nível de isolamento da transação.
LOCK_TIMEOUT | O CUBRID fornece o recurso de tempo limite de trava, que define o tempo de espera (em segundos) para a trava até que a configuração de trava da transação seja permitida. O valor padrão para o parâmetro lock_timeout_in_secs é -1, que significa que a aplicação cliente irá esperar indefinidamente até que a trava da transação seja permitida.
PARAM_AUTO_COMMIT | No CUBRID PHP, o modo de auto-confirmação é desabilitado por padrão para gerenciamento de transação. Pode ser definido pela função cubrid_set_autocommit().

A tabela a seguir mostra os níveis de isolamento de 1 a 6. Consiste no esquema da tabela (linha) e no nível de isolamento:

Níveis de Isolamento Suportados pelo CUBRID
Nome | Descrição
--- | ---
SERIALIZÁVEL (6) | Neste nível de isolamento, problemas relacionados a concorrência (ex.: leituras "sujas", leituras não repetíveis, leituras fantasmas, etc.) não ocorrem.
CLASSE DE LEITURA REPETÍVEL com INSTÂNCIAS DE LEITURA REPETÍVEIS (5) | Uma transação T2 não pode atualizar o esquema da tabela A enquanto a transação T1 está visualizando a tabela A. A transação T1 poderá experimentar leitura fantasma para o registro R que foi inserido por outra transação T2 enquanto estiver repetidamente recuperando um registro específico.
CLASSE DE LEITURA REPETÍVEL com INSTÂNCIAS DE LEITURA CONFIRMADAS (ou ESTABILIDADE DE CURSOR) (4) | Uma transação T2 não pode atualizar o esquema da tabela A enquanto a transação T1 está visualizando a tabela A. A transação T1 poderá experimentar leitura de R (leitura não repetível) que foi atualizado e confirmado por outras transação T1 enquanto estiver repetidamente recuperando o registro R.
CLASSE DE LEITURA REPETÍVEL com INSTÂNCIAS DE LEITURA NÃO CONFIRMADAS (3) | Nível padrão de isolamento. Uma transação T2 não pode atualizar o esquema da tabela A enquanto a transação T1 estiver visualizando a tabela A. A transação poderá experimentar leitura de R' (leitura "suja") para o registro que foi atualizado mas não confirmado pela transação T2.
CLASSE DE LEITURA CONFIRMADA com INSTÂNCIAS DE LEITURA CONFIRMADA (2) | A transação T1 poderá experimentar leitura de A' (leitura não repetível) para a tabela que foi atualizada e confirmada pela transação T2 enquanto estiver visualizando a tabela A repetidamente. A transação T1 poderá experimentar leitura de R' (leitura não repetível) para o registro que foi atualizado e confirmado pela transação T2 enquanto estiver recuperando o registro R repetidamente.
CLASSE DE LEITURA CONFIRMADA com INSTÂNCIAS DE LEITURA NÃO CONFIRMADA (1) | A transação T1 poderá experimentar leitura de A' (leitura não repetível) para a tabela que foi atualizada e confirmada pela transação T2 enquanto estiver repetidamente visualizando a tabela A. A transação T1 poderá experimentar leitura de R' (leitura "suja") para o registro que foi atualizado mas não confirmado pela transação T2.

### Parâmetros

`conn_identifier`
  A conexão CUBRID. Se o identificador da conexão não for especificado, a última conexão aberta por cubrid_connect() será usada.

### Valor Retornado

Um array associativo com parâmetros do banco de dados CUBRID em caso de sucesso, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Alterados LOCK_TIMEOUT para PARAM_LOCK_TIMEOUT, e MAX_STRING_LENGTH para PARAM_MAX_STRING_LENGTH no resultado.

### Exemplos

Exemplo #1 Exemplo de cubrid_get_db_parameter()

    <?php
    printf("%-33s %s\n", "Versão do CUBRID PHP:", cubrid_version());

    printf("\n");

    $conn = cubrid_connect("localhost", 33088, "demodb");

    if (!$conn) {
        die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-33s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-33s %s\n", "Informação do servidor:", $server_info);
    printf("%-33s %s\n", "Informação do cliente:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-33s %s\n", "Conjunto de caracteres do CUBRID:", $charset);

    cubrid_disconnect($conn);

    ?>

O exemplo acima produzirá:

    Versão do CUBRID PHP:             9.1.0.0001

    PARAM_ISOLATION_LEVEL             3
    LOCK_TIMEOUT                      -1
    MAX_STRING_LENGTH                 1073741823
    PARAM_AUTO_COMMIT                 1

    Informação do servidor:           9.1.0.0212
    Informação do cliente:            9.1.0

    Conjunto de caracteres do CUBRID: iso8859-1

### Veja Também

- cubrid_set_db_parameter() - Define os parâmetros do banco de dados CUBRID
- cubrid_get_autocommit() - Obtém o modo de auto-confirmação da conexão

# cubrid_get_query_timeout

(PECL CUBRID >= 8.4.1)

cubrid_get_query_timeout — Obtém o tempo limite de consulta para a requisição

### Descrição

function cubrid_get_query_timeout(resource `$req_identifier`): int

A função cubrid_get_query_timeout() é usada para obter o tempo limite de consulta da requisição.

### Parâmetros

`req_identifier`
  Identificador da requisição.

### Valor Retornado

Retorna o limite de tempo de consulta em milissegundos da requisição atual em caso de sucesso, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_get_query_timeout()

    <?php

    $host = "localhost";
    $port = 33000;
    $db = "demodb";

    $conn =
    cubrid_connect_with_url("CUBRID:$host:$port:$db:::?login_timeout=50000&query_timeout=5000&disconnect_on_query_timeout=yes");

    $req = cubrid_prepare($conn, "SELECT * FROM code");

    $timeout = cubrid_get_query_timeout($req);
    var_dump($timeout);

    cubrid_set_query_timeout($req, 1000);
    $timeout = cubrid_get_query_timeout($req);
    var_dump($timeout);

    cubrid_close($conn);
    ?>

O exemplo acima produzirá:

    int(5000)
    int(1000)

### Veja Também

- cubrid_set_query_timeout() - Define o tempo limite de execução de consulta

# cubrid_get_server_info

(PECL CUBRID >= 8.3.0)

cubrid_get_server_info — Retorna a versão do servidor CUBRID

### Descrição

function cubrid_get_server_info(resource `$conn_identifier`): string

Esta função retorna uma string que representa a versão do servidor CUBRID.

### Parâmetros

`conn_identifier`
  A conexão CUBRID.

### Valor Retornado

Uma string que representa a versão do servidor CUBRID em caso de sucesso, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_get_server_info()

    <?php
    printf("%-30s %s\n", "Versão do CUBRID PHP:", cubrid_version());

    printf("\n");

    $conn = cubrid_connect("localhost", 33088, "demodb");

    if (!$conn) {
        die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-30s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-30s %s\n", "Informação do servidor:", $server_info);
    printf("%-30s %s\n", "Informação do cliente:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-30s %s\n", "Conj. caracteres CUBRID:", $charset);

    cubrid_disconnect($conn);

    ?>

O exemplo acima produzirá:

    Versão do CUBRID PHP:          9.1.0.0001

    PARAM_ISOLATION_LEVEL          3
    LOCK_TIMEOUT                   -1
    MAX_STRING_LENGTH              1073741823
    PARAM_AUTO_COMMIT              1

    Informação do servidor:        9.1.0.0212
    Informação do cliente:         9.1.0

    Conj. caracteres CUBRID:       iso8859-1

# cubrid_insert_id

(PECL CUBRID >= 8.3.0)

cubrid_insert_id — Retorna o ID gerado pela última coluna `AUTO_INCREMENT` atualizada

### Descrição

function cubrid_insert_id(resource `$conn_identifier` = ?): string

A função cubrid_insert_id() recupera o ID gerado para a coluna AUTO_INCREMENT atualizada pela consulta INSERT anterior. Retorna 0 se a consulta anterior não gerou novas linhas ou FALSE em caso de falha.

> Nota: O CUBRID suporta AUTO_INCREMENT para mais de uma coluna na tabela. Na maioria dos casos, haverá uma única coluna AUTO_INCREMENT em uma tabela. Se houver múltiplas colunas AUTO_INCREMENT, esta função não deve ser usada mesmo se ela retornar um valor.

### Parâmetros

`conn_identifier`
  O identificador de conexão previamente obtido através de uma chamada a cubrid_connect().

### Valor Retornado

Uma string representando o ID gerado para uma coluna AUTO_INCREMENT pela consulta anterior, em caso de sucesso.

0, se a consulta anterior não gerou novas linhas.

`false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Alterado o valor de retorno, de array para string; Removido o primeiro parâmetro class_name.

### Exemplos

Exemplo #1 Exemplo de cubrid_insert_id()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    @cubrid_execute($conn, "DROP TABLE cubrid_test");
    cubrid_execute($conn, "CREATE TABLE cubrid_test (d int AUTO_INCREMENT(1, 2), t varchar)");

    for ($i = 0; $i < 10; $i++) {
        cubrid_execute($conn, "INSERT INTO cubrid_test(t) VALUES('cubrid_test')");
    }

    $id = cubrid_insert_id();
    var_dump($id);

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    string(2) "19"

# cubrid_is_instance

(PECL CUBRID >= 8.3.0)

cubrid_is_instance — Verifica se a instância apontada pelo OID existe

### Descrição

function cubrid_is_instance(resource `$conn_identifier`, string `$oid`): int

A função cubrid_is_instance() é usada para verificar se a instância apontada pelo `oid` existe ou não.

### Parâmetros

`conn_identifier`
  Identificador da conexão.
`oid`
  OID da instância que terá a existência verificada.

### Valor Retornado

1, se a instância existir;

0, se a instância não existir;

-1, em caso de erro.

### Exemplos

Exemplo #1 Exemplo de cubrid_is_instance()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $sql = <<<EOD
    SELECT host_year, medal, game_date
    FROM game
    WHERE athlete_code IN
        (SELECT code FROM athlete WHERE name='Thorpe Ian');
    EOD;

    $req = cubrid_execute($conn, $sql, CUBRID_INCLUDE_OID);
    $oid = cubrid_current_oid($req);

    $res = cubrid_is_instance($conn, $oid);
    if ($res == 1) {
        echo "Instância apontada por $oid existe.\n";
    } else if ($res == 0){
        echo "Instância apontada por $oid não existe.\n";
    } else {
        echo "erro\n";
    }

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    Instância apontada por @0|0|0 não existe.

### Veja Também

- cubrid_drop() - Remove uma instância usando OID
- cubrid_get_class_name() - Obtém o nome da classe usando OID

# cubrid_lob_close

(PECL CUBRID >= 8.3.1)

cubrid_lob_close — Fecha os dados BLOB/CLOB

### Descrição

function cubrid_lob_close(array `$lob_identifier_array`): bool

A função cubrid_lob_close() é usada para fechar todos os BLOBs/CLOBs retornados por cubrid_lob_get().

### Parâmetros

`lob_identifier_array`
  Array identificador de LOB retornado por cubrid_lob_get().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_lob_close()

    <?php
    $conn = cubrid_connect ("localhost", 33000, "demodb", "dba");

    cubrid_execute($conn,"DROP TABLE if exists doc");
    cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
    cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

    $lobs = cubrid_lob_get($conn, "SELECT doc_content FROM doc WHERE id=5");
    echo "Tamanho do documento: ".cubrid_lob_size($lobs[0])." bytes";
    cubrid_lob_export($conn, $lobs[0], "doc_5.txt");
    cubrid_lob_close($lobs);
    cubrid_disconnect($conn);
    ?>

### Veja Também

- cubrid_lob_get() - Obtém dados BLOB/CLOB
- cubrid_lob_size() - Obtém o tamanho dos dados BLOB/CLOB
- cubrid_lob_export() - Exporta dados BLOB/CLOB para um arquivo
- cubrid_lob_send() - Lê dados BLOB/CLOB e envia direto ao navegador

# cubrid_lob_export

(PECL CUBRID >= 8.3.1)

cubrid_lob_export — Exporta dados BLOB/CLOB para um arquivo

### Descrição

function cubrid_lob_export(resource `$conn_identifier`, resource `$lob_identifier`, string `$path_name`): bool

A função cubrid_lob_export() é usada para obter dados BLOB/CLOB do banco de dados CUBRID e gravar seu conteúdo para um arquivo. Para usar esta função, é necessário antes usar cubrid_lob_get() para obter informação BLOB/CLOB do CUBRID.

### Parâmetros

`conn_identifier`
  Identificador de conexão.
`lob_identifier`
  Identificador LOB.
`path_name`
  Caminho do arquivo.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo do cubrid_lob_export()

    <?php
    $conn = cubrid_connect ("localhost", 33000, "demodb", "dba");

    cubrid_execute($conn,"DROP TABLE if exists doc");
    cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
    cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

    $lobs = cubrid_lob_get($conn, "SELECT doc_content FROM doc WHERE id=5");
    echo "Tamanho do documento: ".cubrid_lob_size($lobs[0])." bytes";
    cubrid_lob_export($conn, $lobs[0], "doc_5.txt");
    cubrid_lob_close($lobs);
    cubrid_disconnect($conn);
    ?>

### Veja Também

- cubrid_lob_get() - Obtém dados BLOB/CLOB
- cubrid_lob_close() - Fecha os dados BLOB/CLOB
- cubrid_lob_size() - Obtém o tamanho dos dados BLOB/CLOB
- cubrid_lob_send() - Lê dados BLOB/CLOB e envia direto ao navegador

# cubrid_lob_get

(PECL CUBRID >= 8.3.1)

cubrid_lob_get — Obtém dados BLOB/CLOB

### Descrição

function cubrid_lob_get(resource `$conn_identifier`, string `$sql`): array

A função cubrid_lob_get() é usada para obter metainformações de BLOB/CLOB do banco de dados CUBRID. O CUBRID obtém dados BLOB/CLOB executando a instrução SQL e retornando todos os LOBs como um array de recursos. Certifique-se que o SQL recupere somente uma coluna e que seu tipo de dados seja BLOB ou CLOB.

Lembre-se de usar cubrid_lob_close() para liberar os LOBs da memória se eles não forem mais necessários.

### Parâmetros

`conn_identifier`
  Identificador da conexão.
`sql`
  Instrução SQL a ser executada.

### Valor Retornado

Retorna uma array de recursos LOB em caso de sucesso, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_lob_get()

    <?php
    $conn = cubrid_connect ("localhost", 33000, "demodb", "dba");

    cubrid_execute($conn,"DROP TABLE if exists doc");
    cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
    cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

    $lobs = cubrid_lob_get($conn, "SELECT doc_content FROM doc WHERE id=5");
    echo "Tamanho do documento: ".cubrid_lob_size($lobs[0])." bytes";
    cubrid_lob_export($conn, $lobs[0], "doc_5.txt");
    cubrid_lob_close($lobs);
    cubrid_disconnect($conn);
    ?>

### Veja Também

- cubrid_lob_close() - Fecha os dados BLOB/CLOB
- cubrid_lob_size() - Obtém o tamanho dos dados BLOB/CLOB
- cubrid_lob_export() - Exporta dados BLOB/CLOB para um arquivo
- cubrid_lob_send() - Lê dados BLOB/CLOB e envia direto ao navegador

# cubrid_lob_send

(PECL CUBRID >= 8.3.1)

cubrid_lob_send — Lê dados BLOB/CLOB e envia direto ao navegador

### Descrição

function cubrid_lob_send(resource `$conn_identifier`, resource `$lob_identifier`): bool

cubrid_lob_send() lê dados BLOB/CLOB e envia-o direto ao navegador. Para usar esta função é necessário usar primeiro cubrid_lob_get() para obter informação do BLOB/CLOB do CUBRID.

### Parâmetros

`conn_identifier`
  Identificador da conexão.
`lob_identifier`
  Identificador do LOB.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_lob_send()

    <?php
    $conn = cubrid_connect ("localhost", 33000, "demodb", "dba");

    cubrid_execute($conn,"DROP TABLE if exists doc");
    cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
    cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

    $lobs = cubrid_lob_get($conn, "SELECT doc_content FROM doc WHERE id=5");

    cubrid_lob_send($conn, $lobs[0]);
    cubrid_lob_close($lobs);
    cubrid_disconnect($conn);
    ?>

### Veja Também

- cubrid_lob_get() - Obtém dados BLOB/CLOB
- cubrid_lob_close() - Fecha os dados BLOB/CLOB
- cubrid_lob_size() - Obtém o tamanho dos dados BLOB/CLOB
- cubrid_lob_export() - Exporta dados BLOB/CLOB para um arquivo

# cubrid_lob_size

(PECL CUBRID >= 8.3.1)

cubrid_lob_size — Obtém o tamanho dos dados BLOB/CLOB

### Descrição

function cubrid_lob_size(resource `$lob_identifier`): string

cubrid_lob_size() é usada para obter o tamanho dos dados BLOB/CLOB.

### Parâmetros

`lob_identifier`
  Identificador do LOB.

### Valor Retornado

Uma string representando o tamanho dos dados LOB em caso de sucesso, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Alterado o tipo de valor de retorno, de int para string.

### Exemplos

Exemplo #1 Exemplo de cubrid_lob_size()

    <?php
    $lobs = cubrid_lob_get($con, "SELECT doc_content FROM doc WHERE doc_id=5");
    echo "Tamanho do documento:".cubrid_lob_size($lobs[0]);
    cubrid_lob_export($conn, $lobs[0], "doc_5.txt");
    cubrid_lob_close($lobs);
    ?>

### Veja Também

- cubrid_lob_get() - Obtém dados BLOB/CLOB
- cubrid_lob_close() - Fecha os dados BLOB/CLOB
- cubrid_lob_export() - Exporta dados BLOB/CLOB para um arquivo
- cubrid_lob_send() - Lê dados BLOB/CLOB e envia direto ao navegador

# cubrid_lob2_bind

(PECL CUBRID >= 8.4.1)

cubrid_lob2_bind — Vincula um objeto LOB ou uma string como objeto LOB a uma instrução preparada como parâmetros

### Descrição

function cubrid_lob2_bind(
resource `$req_identifier`,
int `$bind_index`,
mixed `$bind_value`,
string `$bind_value_type` = ?
): bool

A função cubrid_lob2_bind() é usada para vincular dados BLOB/CLOB a um marcador correspondente de ponto de interrogação na instrução SQL passada à função cubrid_prepare(). Se o parâmetro `bind_value_type` não for informado, a string será "BLOB" por padrão. Porém se a função cubrid_lob2_new() for usada antes, o parâmetro `bind_value_type` será consistente com o parâmetro `type` na função cubrid_lob2_new() como o padrão.

### Parâmetros

`req_identifier`
  Identificador de requisição como resultado de cubrid_prepare().
`bind_index`
  Localização dos parâmetros de vinculação. Inicia em 1.
`bind_value`
  Valor real para vinculação.
`bind_value_type`
  Precisa ser "BLOB" ou "CLOB" e não diferencia maiúsculas de minúsculas. Se não informado, o padrão é "BLOB".

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_lob2_bind()

    <?php
    // Tabela: test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES (?, ?)");

    cubrid_bind($req,1, 3);

    $lob = cubrid_lob2_new($conn, 'CLOB');
    cubrid_lob2_bind($req, 2, $lob);

    cubrid_execute($req);

    cubrid_bind($req, 1, 4);

    cubrid_lob2_bind($req, 2, 'CUBRID LOB2 TEST', 'CLOB');

    cubrid_execute($req);

    cubrid_disconnect($conn);
    ?>

### Veja Também

- cubrid_lob2_new() - Cria um objeto LOB
- cubrid_lob2_close() - Fecha objeto LOB

# cubrid_lob2_close

(PECL CUBRID >= 8.4.1)

cubrid_lob2_close — Fecha objeto LOB

### Descrição

function cubrid_lob2_close(resource `$lob_identifier`): bool

A função cubrid_lob2_close() é usada para fechar o objeto LOB retornado por cubrid_lob2_new() ou obtido do conjunto de resultados.

### Parâmetros

`lob_identifier`
  Identificador do LOB como resultado da função cubrid_lob2_new() ou obtido do conjunto de resultados.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- cubrid_lob2_new() - Cria um objeto LOB

# cubrid_lob2_export

(PECL CUBRID >= 8.4.1)

cubrid_lob2_export — Exporta o objeto LOB para um arquivo

### Descrição

function cubrid_lob2_export(resource `$lob_identifier`, string `$file_name`): bool

A função cubrid_lob2_export() é usada para gravar o conteúdo dos dados BLOB/CLOB em um arquivo. Para usar esta função, é necessário usar cubrid_lob2_new() ou buscar primeiro um objeto LOB do banco de dados CUBRID. Se o arquivo já existir, a operação falhará. Esta função não influenciará a posição do cursor do objeto LOB. Ela opera em todo o objeto lob.

### Parâmetros

`lob_identifier`
  Identificador LOB como um resultado de cubrid_lob2_new() ou obtido do conjunto de resultados.
`filename`
  Nome do arquivo no qual os dados BLOB/CLOB serão armazenados. Também suporta o caminho do arquivo.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_lob2_export()

    <?php
    // Tabela: test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists doc");
    cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
    cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

    $req = cubrid_prepare($conn, "select * from doc");

    cubrid_execute($req);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);

    $row = cubrid_fetch($req, CUBRID_NUM | CUBRID_LOB);

    cubrid_lob2_export($row[1], "doc_3.txt");

    cubrid_lob2_close($row[1]);
    cubrid_disconnect($conn);
    ?>

### Veja Também

- cubrid_lob2_new() - Cria um objeto LOB
- cubrid_lob2_close() - Fecha objeto LOB
- cubrid_lob2_import() - Importa dados BLOB/CLOB de um arquivo
- cubrid_lob2_bind() - Vincula um objeto LOB ou uma string como objeto LOB a uma instrução preparada como parâmetros

# cubrid_lob2_import

(PECL CUBRID >= 8.4.1)

cubrid_lob2_import — Importa dados BLOB/CLOB de um arquivo

### Descrição

function cubrid_lob2_import(resource `$lob_identifier`, string `$file_name`): bool

A função cubrid_lob2_import() é usada para obter o conteúdo dos dados BLOB/CLOB de um arquivo. Para usar esta função, é necessário primeiro usar a função cubrid_lob2_new() ou buscar um objeto LOB do banco de dados CUBRID. Se o arquivo não existir, a operação falhará. Esta função não influenciará a posição do cursor do objeto LOB. Ela opera em todo o objeto LOB.

### Parâmetros

`lob_identifier`
  Identificador LOB como um resultado de cubrid_lob2_new() ou obtido do conjunto de resultados.
`filename`
  Nome do arquivo do qual os dados BLOB/CLOB serão importados. Também suporta o caminho do arquivo.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_lob2_export()

    <?php

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES (?, ?)");
    cubrid_bind($req, 1, 1);

    $lob = cubrid_lob2_new($conn, "clob");
    cubrid_lob2_import($lob, "doc_1.txt");
    cubrid_lob2_bind($req, 2, $lob, 'CLOB'); // ou cubrid_lob2_bind($req, 2, $lob);

    cubrid_execute($req);

    cubrid_lob2_close($lob);
    cubrid_disconnect($conn);
    ?>

### Veja Também

- cubrid_lob2_new() - Cria um objeto LOB
- cubrid_lob2_close() - Fecha objeto LOB
- cubrid_lob2_export() - Exporta o objeto LOB para um arquivo
- cubrid_lob2_bind() - Vincula um objeto LOB ou uma string como objeto LOB a uma instrução preparada como parâmetros

# cubrid_lob2_new

(PECL CUBRID >= 8.4.1)

cubrid_lob2_new — Cria um objeto LOB

### Descrição

function cubrid_lob2_new(resource `$conn_identifier` = ?, string `$type` = "BLOB"): resource

A função cubrid_lob2_new() é usada para criar um objeto LOB (BLOB e CLOB). Esta função deve ser usada antes de vincular um objeto LOB.

### Parâmetros

`conn_identifier`
  Identificador da conexão. Se não for especificado, a última conexão aberta por cubrid_connect() ou cubrid_connect_with_url() será usada.
`type`
  Pode ser "BLOB" ou "CLOB", sem distinção entre maiúsculas e minúsculas. O padrão é "BLOB".

### Valor Retornado

Identificador LOB em caso de sucesso, ou `false` em caso de falha.

### Veja Também

- cubrid_lob2_close() - Fecha objeto LOB

# cubrid_lob2_read

(PECL CUBRID >= 8.4.1)

cubrid_lob2_read — Lê bytes de dados BLOB/CLOB

### Descrição

function cubrid_lob2_read(resource `$lob_identifier`, int `$len`): string

A função cubrid_lob2_read() lê o número de bytes especificados em `len` dos dados LOB e retorna os bytes lidos.

### Parâmetros

`lob_identifier`
  Identificador LOB como um resultado de cubrid_lob2_new() ou obtido do conjunto de resultados.
`len`
  Comprimento de buffer a ser lido dos dados do LOB.

### Valor Retornado

Retorna o conteúdo como uma string, `false` quando não houver mais dados ou `null` em caso de falha.

### Exemplos

Exemplo #1 Exemplo 1 de cubrid_lob2_read()

    <?php
    // test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "public", "");

    $req = cubrid_execute($conn, "select * from test_lob");

    $row = cubrid_fetch_row($req, CUBRID_LOB);

    print "A posição agora é " . cubrid_lob2_tell($row[1]) . "\n";

    cubrid_lob2_seek($row[1], 10, CUBRID_CURSOR_FIRST);

    print "\nPosição após mover para frente é " . cubrid_lob2_tell($row[1]) . "\n";

    $data = cubrid_lob2_read($row[1], 12);

    print "\nPosição após a leitura é " . cubrid_lob2_tell($row[1]) . "\n";

    print $data . "\n";

    cubrid_lob2_seek($row[1], 5, CUBRID_CURSOR_CURRENT);

    print "\nPosição após mover novamente é " . cubrid_lob2_tell($row[1]) . "\n";

    $data = cubrid_lob2_read($row[1], 20);
    print $data . "\n";

    cubrid_disconnect($conn);
    ?>

Exemplo #2 Exemplo 2 de cubrid_lob2_read()

    <?php
    // test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    $req = cubrid_execute($conn, "select * from test_lob");

    $row = cubrid_fetch_row($req, CUBRID_LOB);

    while (true) {
        if ($data = cubrid_lob2_read($row[1], 1024)) {
            print $data . "\n";
        }
        elseif ($data === false) {
            print "Não há mais dados\n";
            break;
        }
        else {
            print "Houve algum erro\n";
            break;
        }
    }

    cubrid_disconnect($conn);
    ?>

### Veja Também

- cubrid_lob2_write() - Escreve em um objeto LOB
- cubrid_lob2_seek() - Move o cursor de um objeto LOB
- cubrid_lob2_seek64() - Move o cursor de um objeto LOB
- cubrid_lob2_tell() - Informa a posição do cursor do objeto LOB
- cubrid_lob2_tell64() - Informa a posição do cursor do objeto LOB
- cubrid_lob2_size() - Obtém o tamanho do objeto LOB
- cubrid_lob2_size64() - Obtém o tamanho do objeto LOB

# cubrid_lob2_seek

(PECL CUBRID >= 8.4.1)

cubrid_lob2_seek — Move o cursor de um objeto LOB

### Descrição

function cubrid_lob2_seek(resource `$lob_identifier`, int `$offset`, int `$origin` = CUBRID_CURSOR_CURRENT): bool

A função cubrid_lob2_seek() é usada para mover a posição do cursor de um objeto LOB pelo valor definido no argumento `offset`, para a direção definida no argumento `origin`.

Para definir o argumento `origin`, pode-se usar `CUBRID_CURSOR_FIRST` para definir a posição do cursor avançando o número de unidades definidas por `offset` desde o primeiro início. Neste caso, `offset` precisa ser um valor positivo.

Se for usado `CUBRID_CURSOR_CURRENT` para `origin`, pode-se avançar ou retroceder e `offset` pode ser positivo ou negativo.

Se for usado `CUBRID_CURSOR_LAST` para `origin`, pode-se mover o número de unidades definido por `offset` para trás a partir do final do objeto LOB e `offset` pode ser somente positivo.

### Parâmetros

`lob_identifier`
  Identificador LOB como um resultado de cubrid_lob2_new() ou obtido do conjunto de resultados.
`offset`
  Número de unidades para mover o cursor.
`origin`
  Este parâmetro pode ter as seguintes constantes como valores: CUBRID_CURSOR_FIRST: move para frente desde o primeiro início. CUBRID_CURSOR_CURRENT: move para frente ou para trás desde a posição atual. CUBRID_CURSOR_LAST: move para trás desde o final do objeto LOB.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_lob2_seek()

    <?php
    // test_lob (id INT, contents CLOB)
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");
    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES(2, ?)");

    $lob = cubrid_lob2_new($conn, 'CLOB');
    $len = cubrid_lob2_write($lob, "Hello world");

    cubrid_lob2_seek($lob, 0, CUBRID_CURSOR_LAST);
    cubrid_lob2_write($lob, "beautiful");

    cubrid_lob2_seek($lob, 15, CUBRID_CURSOR_FIRST);
    $data = cubrid_lob2_read($lob, 5);

    echo $data."\n";

    cubrid_lob2_bind($req, 1, $lob);
    cubrid_execute($req);

    cubrid_disconnect($conn);
    ?>

### Veja Também

- cubrid_lob2_read() - Lê bytes de dados BLOB/CLOB
- cubrid_lob2_write() - Escreve em um objeto LOB
- cubrid_lob2_seek64() - Move o cursor de um objeto LOB
- cubrid_lob2_tell() - Informa a posição do cursor do objeto LOB
- cubrid_lob2_tell64() - Informa a posição do cursor do objeto LOB
- cubrid_lob2_size() - Obtém o tamanho do objeto LOB
- cubrid_lob2_size64() - Obtém o tamanho do objeto LOB

# cubrid_lob2_seek64

(PECL CUBRID >= 8.4.1)

cubrid_lob2_seek64 — Move o cursor de um objeto LOB

### Descrição

function cubrid_lob2_seek64(resource `$lob_identifier`, string `$offset`, int `$origin` = CUBRID_CURSOR_CURRENT): bool

A função cubrid_lob2_seek64() é usada para mover a posição do cursor de um objeto LOB pelo valor definido no argumento `offset`, na direção definida no argumento `origin`. Se `offset` for maior que o máximo número inteiro, pode-se usar esta função.

Para definir o argumento `origin`, pode-se usar `CUBRID_CURSOR_FIRST` para definir a posição do cursor avançando o número de unidades definidas por `offset` desde o primeiro início. Neste caso, `offset` precisa ser um valor positivo.

Se for usado `CUBRID_CURSOR_CURRENT` para `origin`, pode-se avançar ou retroceder e `offset` pode ser positivo ou negativo.

Se for usado `CUBRID_CURSOR_LAST` para `origin`, pode-se mover o número de unidades definido por `offset` para trás a partir do final do objeto LOB e `offset` pode ser somente positivo.

> Nota: Se esta função for usada para mover a posição do cursor do objeto LOB, deve-se passar `offset` como uma string.

### Parâmetros

`lob_identifier`
  Identificador LOB como um resultado de cubrid_lob2_new() ou obtido do conjunto de resultados.
`offset`
  Número de unidades para mover o cursor.
`origin`
  Este parâmetro pode ter as seguintes constantes como valores: CUBRID_CURSOR_FIRST: move para frente desde o primeiro início. CUBRID_CURSOR_CURRENT: move para frente ou para trás desde a posição atual. CUBRID_CURSOR_LAST: move para trás desde o final do objeto LOB.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_lob2_seek64()

    <?php
    // test_lob (id INT, contents CLOB)
    // Comprimento de dados de doc_1.txt deve ser maior que 20101029056306120215.

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES (?, ?)");
    cubrid_bind($req, 1, 1);

    $lob = cubrid_lob2_new($conn, "clob");
    cubrid_lob2_import($lob, "doc_1.txt");
    cubrid_lob2_bind($req, 2, $lob, 'CLOB'); // ou cubrid_lob2_bind($req, 2, $lob);

    cubrid_execute($req);

    cubrid_lob2_close($lob);

    $req = cubrid_execute($conn, "select * from test_lob");
    $row = cubrid_fetch_row($req, CUBRID_LOB);
    $lob = $row[1];

    cubrid_lob2_seek64($lob, "20101029056306120215", CUBRID_CURSOR_FIRST);
    $data = cubrid_lob2_read($lob, 20);
    echo $data."\n";
    cubrid_disconnect($conn);
    ?>

### Veja Também

- cubrid_lob2_read() - Lê bytes de dados BLOB/CLOB
- cubrid_lob2_write() - Escreve em um objeto LOB
- cubrid_lob2_seek() - Move o cursor de um objeto LOB
- cubrid_lob2_tell() - Informa a posição do cursor do objeto LOB
- cubrid_lob2_tell64() - Informa a posição do cursor do objeto LOB
- cubrid_lob2_size() - Obtém o tamanho do objeto LOB
- cubrid_lob2_size64() - Obtém o tamanho do objeto LOB

# cubrid_lob2_size

(PECL CUBRID >= 8.4.1)

cubrid_lob2_size — Obtém o tamanho do objeto LOB

### Descrição

function cubrid_lob2_size(resource `$lob_identifier`): int

A função cubrid_lob2_size() é usada para obter o tamanho do objeto LOB.

### Parâmetros

`lob_identifier`
  Identificador LOB como um resultado de cubrid_lob2_new() ou obtido do conjunto de resultados.

### Valor Retornado

Retorna o tamanho do objeto LOB em caso de sucesso, ou `false` em caso de falha.

### Veja Também

- cubrid_lob2_read() - Lê bytes de dados BLOB/CLOB
- cubrid_lob2_write() - Escreve em um objeto LOB
- cubrid_lob2_seek() - Move o cursor de um objeto LOB
- cubrid_lob2_seek64() - Move o cursor de um objeto LOB
- cubrid_lob2_tell() - Informa a posição do cursor do objeto LOB
- cubrid_lob2_tell64() - Informa a posição do cursor do objeto LOB
- cubrid_lob2_size64() - Obtém o tamanho do objeto LOB

# cubrid_lob2_size64

(PECL CUBRID >= 8.4.1)

cubrid_lob2_size64 — Obtém o tamanho do objeto LOB

### Descrição

function cubrid_lob2_size64(resource `$lob_identifier`): string

A função cubrid_lob2_size64() é usada para obter o tamanho do objeto LOB. Se o tamanho de um objeto LOB for maior que o máximo número inteiro, pode-se usar esta função e ela retornará o tamanho como uma string.

### Parâmetros

`lob_identifier`
  Identificador LOB como um resultado de cubrid_lob2_new() ou obtido do conjunto de resultados.

### Valor Retornado

Retorna o tamanho do objeto LOB como uma string em caso de sucesso, ou `false` em caso de falha.

### Veja Também

- cubrid_lob2_read() - Lê bytes de dados BLOB/CLOB
- cubrid_lob2_write() - Escreve em um objeto LOB
- cubrid_lob2_seek() - Move o cursor de um objeto LOB
- cubrid_lob2_seek64() - Move o cursor de um objeto LOB
- cubrid_lob2_tell() - Informa a posição do cursor do objeto LOB
- cubrid_lob2_tell64() - Informa a posição do cursor do objeto LOB
- cubrid_lob2_size() - Obtém o tamanho do objeto LOB

# cubrid_lob2_tell

(PECL CUBRID >= 8.4.1)

cubrid_lob2_tell — Informa a posição do cursor do objeto LOB

### Descrição

function cubrid_lob2_tell(resource `$lob_identifier`): int

A função cubrid_lob2_tell() é usada para informar a posição do cursor do objeto LOB.

### Parâmetros

`lob_identifier`
  Identificador LOB como um resultado de cubrid_lob2_new() ou obtido do conjunto de resultados.

### Valor Retornado

Retorna a posição do cursor do objeto LOB em caso de sucesso, ou `false` em caso de falha.

### Veja Também

- cubrid_lob2_read() - Lê bytes de dados BLOB/CLOB
- cubrid_lob2_write() - Escreve em um objeto LOB
- cubrid_lob2_seek() - Move o cursor de um objeto LOB
- cubrid_lob2_seek64() - Move o cursor de um objeto LOB
- cubrid_lob2_tell64() - Informa a posição do cursor do objeto LOB
- cubrid_lob2_size() - Obtém o tamanho do objeto LOB
- cubrid_lob2_size64() - Obtém o tamanho do objeto LOB

# cubrid_lob2_tell64

(PECL CUBRID >= 8.4.1)

cubrid_lob2_tell64 — Informa a posição do cursor do objeto LOB

### Descrição

function cubrid_lob2_tell64(resource `$lob_identifier`): string

A função cubrid_lob2_tell64() é usada para informar a posição do cursor do objeto LOB. Se o tamanho de um objeto LOB for maior que o máximo número inteiro, pode-se usar esta função e ela retornará a posição como uma string.

### Parâmetros

`lob_identifier`
  Identificador LOB como um resultado de cubrid_lob2_new() ou obtido do conjunto de resultados.

### Valor Retornado

Retorna a posição do cursor do objeto LOB como uma string em caso de sucesso, ou `false` em caso de falha.

### Veja Também

- cubrid_lob2_read() - Lê bytes de dados BLOB/CLOB
- cubrid_lob2_write() - Escreve em um objeto LOB
- cubrid_lob2_seek() - Move o cursor de um objeto LOB
- cubrid_lob2_seek64() - Move o cursor de um objeto LOB
- cubrid_lob2_tell() - Informa a posição do cursor do objeto LOB
- cubrid_lob2_size() - Obtém o tamanho do objeto LOB
- cubrid_lob2_size64() - Obtém o tamanho do objeto LOB

# cubrid_lob2_write

(PECL CUBRID >= 8.4.1)

cubrid_lob2_write — Escreve em um objeto LOB

### Descrição

function cubrid_lob2_write(resource `$lob_identifier`, string `$buf`): bool

A função cubrid_lob2_write() lê dados de `buf` e armazena-os no objeto LOB. Observe que por enquanto esta função consegue apenas adicionar caracteres.

### Parâmetros

`lob_identifier`
  Identificador LOB como um resultado de cubrid_lob2_new() ou obtido do conjunto de resultados.
`buf`
  Dados que serão escritos no objeto LOB.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo 1 de cubrid_lob2_write()

    <?php
    // test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES(2, ?)");

    $lob = cubrid_lob2_new($conn, 'CLOB');
    $len = cubrid_lob2_write($lob, "Olá mundo");

    cubrid_lob2_bind($req, 1, $lob);
    cubrid_execute($req);

    cubrid_disconnect($conn);
    ?>

Exemplo #2 Exemplo 2 de cubrid_lob2_write()

    <?php
    // test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES(1, ?)");
    $lob1 = cubrid_lob2_new($conn, 'CLOB');
    $len = cubrid_lob2_write($lob1, "cubrid php driver");
    cubrid_lob2_bind($req, 1, $lob1);
    cubrid_execute($req);

    $req = cubrid_execute($conn, "select * from test_lob");

    $row = cubrid_fetch_row($req, CUBRID_LOB);
    $lob2 = $row[1];
    cubrid_lob2_seek($lob2, 0, CUBRID_CURSOR_LAST);

    $pos = cubrid_lob2_tell($lob2);
    print "pos antes da escrita: $pos\n";

    cubrid_lob2_write($lob2, "Olá mundo");

    $pos = cubrid_lob2_tell($lob2);
    print "pos após a escrita: $pos\n";

    cubrid_disconnect($conn);
    ?>

### Veja Também

- cubrid_lob2_read() - Lê bytes de dados BLOB/CLOB
- cubrid_lob2_seek() - Move o cursor de um objeto LOB
- cubrid_lob2_seek64() - Move o cursor de um objeto LOB
- cubrid_lob2_tell() - Informa a posição do cursor do objeto LOB
- cubrid_lob2_tell64() - Informa a posição do cursor do objeto LOB
- cubrid_lob2_size() - Obtém o tamanho do objeto LOB
- cubrid_lob2_size64() - Obtém o tamanho do objeto LOB

# cubrid_lock_read

(PECL CUBRID >= 8.3.0)

cubrid_lock_read — Define uma trava de leitura em um OID informado

### Descrição

function cubrid_lock_read(resource `$conn_identifier`, string `$oid`): bool

A função cubrid_lock_read() é usada para inserir uma trava de leitura na instância apontada pelo `oid` informado.

### Parâmetros

`conn_identifier`
  Identificador da conexão.
`oid`
  OID da instância na qual será inserida a trava de leitura.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_lock_read()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    cubrid_lock_read($conn, $oid);

    $attr = cubrid_get($conn, $oid, "b");
    var_dump($attr);

    $attr = cubrid_get($conn, $oid);
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    string(9) "{1, 2, 3}"
    array(4) {
      ["a"]=>
      string(1) "1"
      ["b"]=>
      array(3) {
        [0]=>
        string(1) "1"
        [1]=>
        string(1) "2"
        [2]=>
        string(1) "3"
      }
      ["c"]=>
      array(4) {
        [0]=>
        string(2) "11"
        [1]=>
        string(2) "22"
        [2]=>
        string(2) "33"
        [3]=>
        string(3) "333"
      }
      ["d"]=>
      string(10) "a         "
    }

### Veja Também

- cubrid_lock_write() - Define uma trava de escrita em um OID informado

# cubrid_lock_write

(PECL CUBRID >= 8.3.0)

cubrid_lock_write — Define uma trava de escrita em um OID informado

### Descrição

function cubrid_lock_write(resource `$conn_identifier`, string `$oid`): bool

A função cubrid_lock_write() é usada para inserir uma trava de escrita na instância apontada pelo `oid` informado.

### Parâmetros

`conn_identifier`
  Identificador da conexão.
`oid`
  OID da instância na qual será inserida a trava de escrita.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_lock_write()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    cubrid_lock_write($conn, $oid);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_put($conn, $oid, "b", array(2, 4, 8));

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    array(3) {
      [0]=>
      string(1) "2"
      [1]=>
      string(1) "4"
      [2]=>
      string(1) "8"
    }

### Veja Também

- cubrid_lock_read() - Define uma trava de leitura em um OID informado

# cubrid_move_cursor

(PECL CUBRID >= 8.3.0)

cubrid_move_cursor — Move o cursor no resultado

### Descrição

function cubrid_move_cursor(resource `$req_identifier`, int `$offset`, int `$origin` = CUBRID_CURSOR_CURRENT): bool

A função cubrid_move_cursor() é usada para mover a posição atual do cursor de `req_identifier` pelo valor definido no argumento `offset`, na direção definida no argumento `origin`. Para definir o argumento `origin`, pode-se usar `CUBRID_CURSOR_FIRST` para a primeira parte do resultado, `CUBRID_CURSOR_CURRENT` para a posição atual do resultado ou `CUBRID_CURSOR_LAST` para a última parte do resultado. Se o argumento `origin` não for explicitamente designado, a função usará `CUBRID_CURSOR_CURRENT` como seu valor padrão.

Se o valor da faixa de movimento do cursor ultrapassar o limite válido, o cursor será movido para a próxima posição após a faixa válida para o cursor. Por exemplo, se a intenção for mover 20 unidades no resultado com tamanho de 10, o cursor será movido para a 11ª posição e retornará `CUBRID_NO_MORE_DATA`.

### Parâmetros

`req_identifier`
  Identificador da requisição.
`offset`
  Número de unidades que se deseja mover o cursor.
`origin`
  Posição a partir da qual se deseja mover o cursor: `CUBRID_CURSOR_FIRST`, `CUBRID_CURSOR_CURRENT` ou `CUBRID_CURSOR_LAST`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_move_cursor()

    <?php
    $conn = cubrid_connect("127.0.0.1", 33000, "demodb", "dba");

    $req = cubrid_execute($conn, "SELECT * FROM code");
    cubrid_move_cursor($req, 1, CUBRID_CURSOR_LAST);

    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_CURRENT);
    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    array(2) {
      [0]=>
      string(1) "G"
      [1]=>
      string(4) "Gold"
    }
    array(2) {
      [0]=>
      string(1) "X"
      [1]=>
      string(5) "Mixed"
    }
    array(2) {
      [0]=>
      string(1) "M"
      [1]=>
      string(3) "Man"
    }

### Veja Também

- cubrid_execute() - Executa uma instrução preparada SQL

# cubrid_next_result

(PECL CUBRID >= 8.4.0)

cubrid_next_result — Obtém o resultado da próxima consulta quando múltiplas instruções SQL estão sendo executadas

### Descrição

function cubrid_next_result(resource `$result`): bool

A função cubrid_next_result() é usada para obter os resultados da próxima consulta se múltiplas instruções SQL estiverem em execução e a opção `CUBRID_EXEC_QUERY_ALL` tiver sido definida por cubrid_execute().

### Parâmetros

`result`
  `result` vem de uma chamada a cubrid_execute()

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_next_result()

    <?php
    $conn = cubrid_connect("127.0.0.1", 33000, "demodb", "dba");

    $sql_stmt = "SELECT * FROM code; SELECT * FROM history WHERE host_year=2004 AND event_code=20281";
    $res = cubrid_execute($conn, $sql_stmt, CUBRID_EXEC_QUERY_ALL);

    get_result_info($res);
    cubrid_next_result($res);
    get_result_info($res);

    function get_result_info($req)
    {
        printf("\n------------ get_result_info --------------------\n");

        $row_num = cubrid_num_rows($req);
        $col_num = cubrid_num_cols($req);

        $column_name_list = cubrid_column_names($req);
        $column_type_list = cubrid_column_types($req);

        $column_last_name = cubrid_field_name($req, $col_num - 1);
        $column_last_table = cubrid_field_table($req, $col_num - 1);

        $column_last_type = cubrid_field_type($req, $col_num - 1);
        $column_last_len = cubrid_field_len($req, $col_num - 1);

        $column_1_flags = cubrid_field_flags($req, 1);

        printf("%-30s %d\n", "Contagem de linhas:", $row_num);
        printf("%-30s %d\n", "Contagem de colunas:", $col_num);
        printf("\n");

        printf("%-30s %-30s %-15s\n", "Nomes das Colunas", "Tipos das Colunas", "Comprimentos das Colunas");
        printf("--------------------------------------------------------------------------------------\n");

        $size = count($column_name_list);
        for($i = 0; $i < $size; $i++) {
            $column_len = cubrid_field_len($req, $i);
            printf("%-30s %-30s %-15s\n", $column_name_list[$i], $column_type_list[$i], $column_len);
        }
        printf("\n\n");

        printf("%-30s %s\n", "Nome da última coluna:", $column_last_name);
        printf("%-30s %s\n", "Tabela da última coluna:", $column_last_table);
        printf("%-30s %s\n", "Tipo da última coluna:", $column_last_type);
        printf("%-30s %d\n", "Comprimento da última coluna:", $column_last_len);
        printf("%-30s %s\n", "Opções da segunda coluna:", $column_1_flags);

        printf("\n\n");
    }
    ?>

O exemplo acima produzirá:

    ------------ get_result_info --------------------
    Contagem de linhas:            6
    Contagem de colunas:           2

    Nomes das Colunas              Tipos das Colunas              Comprimentos das Colunas
    --------------------------------------------------------------------------------------
    s_name                         char                           1
    f_name                         varchar                        6

    Nome da última coluna:         f_name
    Tabela da última coluna:       code
    Tipo da última coluna:         varchar
    Comprimento da última coluna:  6
    Opções da segunda coluna:

    ------------ get_result_info --------------------
    Contagem de linhas:            4
    Contagem de colunas:           5

    Nomes das Colunas              Tipos das Colunas              Comprimentos das Colunas
    --------------------------------------------------------------------------------------
    event_code                     integer                        11
    athlete                        varchar                        40
    host_year                      integer                        11
    score                          varchar                        10
    unit                           varchar                        5

    Nome da última coluna:         unit
    Tabela da última coluna:       history
    Tipo da última coluna:         varchar
    Comprimento da última coluna:  5
    Opções da segunda coluna:      not_null primary_key unique_key

### Veja Também

- cubrid_execute() - Executa uma instrução preparada SQL

# cubrid_num_cols

(PECL CUBRID >= 8.3.0)

cubrid_num_cols — Retorna o número de colunas no resultado

### Descrição

function cubrid_num_cols(resource `$result`): int

A função cubrid_num_cols() é usada para obter o número de colunas do resultado da consulta. Somente pode ser usada quando a consulta executada for uma instrução `SELECT`.

### Parâmetros

`result`
  Resultado.

### Valor Retornado

Número de colunas em caso de sucesso.

`false`, se a instrução SQL não for SELECT.

### Exemplos

Exemplo #1 Exemplo de cubrid_num_cols()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $req = cubrid_execute($conn, "SELECT * FROM code");

    $row_num = cubrid_num_rows($req);
    $col_num = cubrid_num_cols($req);

    printf("Número de linhas: %d\nNúmero de colunas: %d\n", $row_num, $col_num);

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    Número de linhas: 6
    Número de colunas: 2

### Veja Também

- cubrid_execute() - Executa uma instrução preparada SQL
- cubrid_num_rows() - Obtém o número de linhas no resultado

# cubrid_num_rows

(PECL CUBRID >= 8.3.0)

cubrid_num_rows — Obtém o número de linhas no resultado

### Descrição

function cubrid_num_rows(resource `$result`): int

A função cubrid_num_rows() é usada para obter o número de linhas do resultado da consulta. Pode ser usada para instruções `SELECT`. Para instruções `INSERT`, `UPDATE`, ou `DELETE`, use a função cubrid_affected_rows().

Nota: a função cubrid_num_rows() somente pode ser usada para consulta síncrona; retorna 0 quando usada para consulta assíncrona.

### Parâmetros

`result`
  `result` vem de uma chamada a cubrid_execute(), cubrid_query() ou cubrid_prepare()

### Valor Retornado

Número de linhas em caso de sucesso.

0 quando a consulta for feita em modo assíncrono.

-1, se a instrução SQL não for SELECT.

`false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_num_rows()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $req = cubrid_execute($conn, "SELECT * FROM code");

    $row_num = cubrid_num_rows($req);
    $col_num = cubrid_num_cols($req);

    printf("Número de linhas: %d\nNúmero de colunas: %d\n", $row_num, $col_num);

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    Número de linhas: 6
    Número de colunas: 2

### Veja Também

- cubrid_execute() - Executa uma instrução preparada SQL
- cubrid_num_cols() - Retorna o número de colunas no resultado
- cubrid_affected_rows() - Retorna o número de linhas afetadas pela última instrução SQL

# cubrid_pconnect

(PECL CUBRID >= 8.3.1)

cubrid_pconnect — Abre uma conexão persistente a um servidor CUBRID

### Descrição

function cubrid_pconnect(
string `$host`,
int `$port`,
string `$dbname`,
string `$userid` = ?,
string `$passwd` = ?
): resource

Estabelece uma conexão persistente a um servidor CUBRID.

cubrid_pconnect() funciona de forma muito similar a cubrid_connect() com duas diferenças principais.

Primeiro, ao conectar, a função tentará primeiro encontrar uma conexão (persistente) já aberta com o mesmo servidor, porta, nome do banco de dados e ID do usuário. Se for encontrada, um identificador será retornado em vez de abrir uma nova conexão.

Segundo, a conexão com o servidor SQL não será encerrada quando a execução do script terminar. Em vez disso, a conexão permanecerá aberta para uso futuro (cubrid_close() ou cubrid_disconnect() não fecharão conexões estabelecidas por cubrid_pconnect()).

Este tipo de conexão é, portanto, denominada 'persistente'.

### Parâmetros

`host`
  Nome de servidor ou endereço IP do servidor CUBRID CAS.
`port`
  Número da porta do servidor CUBRID CAS (BROKER_PORT configurado em $CUBRID/conf/cubrid_broker.conf).
`dbname`
  Nome do banco de dados.
`userid`
  Nome de usuário do banco de dados.
`passwd`
  Senha do usuário.

### Valor Retornado

Identificador da conexão em caso de sucesso, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_pconnect()

    <?php
    printf("%-34s %s\n", "Versão do CUBRID PHP:", cubrid_version());

    printf("\n");

    $conn = cubrid_pconnect("localhost", 33000, "demodb", "dba");

    if (!$conn) {
        die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-34s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-34s %s\n", "Informação do Servidor:", $server_info);
    printf("%-34s %s\n", "Informação do Cliente:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-34s %s\n", "Conjunto de caracteres do CUBRID:", $charset);

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    Versão do CUBRID PHP:              9.1.0.0001

    PARAM_ISOLATION_LEVEL              3
    LOCK_TIMEOUT                       -1
    MAX_STRING_LENGTH                  1073741823
    PARAM_AUTO_COMMIT                  1

    Informação do Servidor:            9.1.0.0212
    Informação do Cliente:             9.1.0

    Conjunto de caracteres do CUBRID:  iso8859-1

### Veja Também

- cubrid_connect() - Abre uma conexão a um servidor CUBRID
- cubrid_connect_with_url() - Prepara o ambiente para conexão ao servidor CUBRID
- cubrid_pconnect_with_url() - Abre uma conexão persistente com o servidor CUBRID
- cubrid_disconnect() - Fecha uma conexão ao banco de dados
- cubrid_close() - Fecha conexão CUBRID

# cubrid_pconnect_with_url

(PECL CUBRID >= 8.3.1)

cubrid_pconnect_with_url — Abre uma conexão persistente com o servidor CUBRID

### Descrição

function cubrid_pconnect_with_url(string `$conn_url`, string `$userid` = ?, string `$passwd` = ?): resource

Estabelece uma conexão persistente com um servidor CUBRID.

cubrid_pconnect_with_url() funciona de forma muito similar a cubrid_connect_with_url() com duas diferenças principais.

Primeiro, ao conectar, a função tentará primeiro encontrar uma conexão (persistente) já aberta com o mesmo servidor, porta, nome do banco de dados e ID do usuário. Se for encontrada, um identificador será retornado em vez de abrir uma nova conexão.

Segundo, a conexão com o servidor SQL não será encerrada quando a execução do script terminar. Em vez disso, a conexão permanecerá aberta para uso futuro (cubrid_close() ou cubrid_disconnect() não fecharão conexões estabelecidas por cubrid_pconnect_with_url()).

Este tipo de conexão é, portanto, denominada 'persistente'.

<url> ::= CUBRID:<host>:<db_name>:<db_user>:<db_password>:[?<properties>]

<properties> ::= <property> [&<property>]

<properties> ::= alhosts=<alternative_hosts>[ &rctime=<time>]

<properties> ::= login_timeout=<milli_sec>

<properties> ::= query_timeout=<milli_sec>

<properties> ::= disconnect_on_query_timeout=true|false

<alternative_hosts> ::= <standby_broker1_host>:<port> [,<standby_broker2_host>:<port>]

<host> := HOSTNAME | IP_ADDR

<time> := SECOND

<milli_sec> := MILLI SECOND

- host : Nome do servidor ou endereço IP do banco de dados mestre
- db_name : Nome do banco de dados
- db_user : Nome de usuário do banco de dados
- db_password : Senha de usuário do banco de dados
- alhosts : Especifica as informações do mediador do servidor reserva, que são usadas em caso de falha quando for impossível conectar-se ao servidor ativo. Pode-se especificar vários mediadores para casos de falha e a tentativa de conexão ao mediadores é realizada na ordem listada em "alhosts"
- rctime : Um intervalo entre as tentativas de conexão ao mediador ativo no qual ocorreu a falha. Após ocorrer uma falha, o sistema se conecta ao mediador especificado por "althosts", encerra a transação e, em seguida, tenta se conectar ao mediador ativo do banco de dados mestre a cada "rctime". O valor padrão é 600 segundos.
- login_timeout : Tempo limite (unidade: milissegundos) para se registrar no banco de dados. O padrão é 0, que significa infinito.
- query_timeout : Tempo limite (unidade: milissegundos) para requisição de consulta. Quando o limite é atingido, é enviada uma mensagem para cancelamento de requisição da consulta transferida ao servidor. O valor de retorno vai depender da configuração disconnect_on_query_timeout; embora a mensagem para cancelar a requisição seja enviada ao servidor, a requisição poderá ser bem sucedida.
- disconnect_on_query_timeout : Configura um valor para retornar imediatamente um erro de função sendo executada após o tempo limite. O padrão é "false".

> Nota: `?` e `:` são usados como identificadores na URL de conexão do PHP e não podem ser incluídos na senha. O exemplo a seguir é uma senha inválida para URL de conexão por conter "`?:`". $url = "CUBRID:localhost:33000:tdb:dba:12?:?login_timeout=100"; Senhas que contêm `?` ou `:` podem ser passadas como parâmetro separado. $url = "CUBRID:localhost:33000:tbd:::?login_timeout=100"; $conn = cubrid_pconnect_with_url ($url, "dba", "12?"); Se o usuário ou a senha estiverem vazios, o caractere "`:`" não pode ser omitido, veja este exemplo: $url = "CUBRID:localhost:33000:demodb:::";

### Parâmetros

`conn_url`
  Uma string contendo informação de conexão ao servidor.
`userid`
  Nome de usuário para o banco de dados.
`passwd`
  Senha do usuário.

### Valor Retornado

Identificador da conexão em caso de sucesso, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_pconnect_with_url() e URL sem propriedades

    <?php
    $conn_url = "CUBRID:127.0.0.1:33000:demodb:dba::";
    $con = cubrid_pconnect_with_url ($conn_url);

    if ($con) {
        echo "conectado com sucesso";
        cubrid_execute($con, "create table person(id int,name char(16))");
        $req =cubrid_execute($con, "insert into person values(1,'James')");

        if ($req) {
            cubrid_close_request ($req);
            cubrid_commit ($con);
        } else {
            cubrid_rollback ($con);
        }
        cubrid_disconnect ($con);
    }
    ?>

Exemplo #2 Exemplo de cubrid_pconnect_with_url() e URL com propriedades

    <?php
    $conn_url = "CUBRID:127.0.0.1:33000:demodb:dba::?althost=10.34.63.132:33088&rctime=100";
    $con = cubrid_pconnect_with_url ($conn_url);

    if ($con) {
        echo "conectado com sucesso";
        $req =cubrid_execute($con, "insert into person values(1,'James')");

        if ($req) {
            cubrid_close_request ($req);
            cubrid_commit ($con);
        } else {
            cubrid_rollback ($con);
        }
        cubrid_disconnect ($con);
    }
    ?>

### Veja Também

- cubrid_connect() - Abre uma conexão a um servidor CUBRID
- cubrid_connect_with_url() - Prepara o ambiente para conexão ao servidor CUBRID
- cubrid_pconnect() - Abre uma conexão persistente a um servidor CUBRID
- cubrid_disconnect() - Fecha uma conexão ao banco de dados
- cubrid_close() - Fecha conexão CUBRID

# cubrid_prepare

(PECL CUBRID >= 8.3.0)

cubrid_prepare — Prepara uma instrução SQL para execução

### Descrição

function cubrid_prepare(resource `$conn_identifier`, string `$prepare_stmt`, int `$option` = 0): resource

A função cubrid_prepare() compila uma instrução SQL para um determinado identificador de conexão e retorna um identificador que representa a instrução pré-compilada.

Uma instrução preparada pode ser executada várias vezes, o que é eficiente para execução repetida ou para processar dados massivos. Apenas uma única instrução pode ser usada, e um parâmetro pode ser marcado com um ponto de interrogação (`?`) no local apropriado da instrução SQL. Adicione um parâmetro ao vincular um valor na cláusula `VALUES` de uma instrução `INSERT` ou na cláusula `WHERE`. Observe que um valor só pode ser vinculado a um parâmetro usando a função cubrid_bind().

### Parâmetros

`conn_identifier`
  Identificador da conexão.
`prepare_stmt`
  Instrução de preparação.
`option`
  Opção de retorno de OID: `CUBRID_INCLUDE_OID`.

### Valor Retornado

Identificador da requisição em caso de sucesso, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_prepare()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $sql = <<<EOD
    SELECT g.event_code, e.name
    FROM game g
    JOIN event e ON g.event_code=e.code
    WHERE host_year = ? AND event_code NOT IN (SELECT event_code FROM game WHERE host_year=?) GROUP BY event_code;
    EOD;

    $req = cubrid_prepare($conn, $sql);

    cubrid_bind($req, 1, 2004);
    cubrid_bind($req, 2, 2000);
    cubrid_execute($req);

    $row_num = cubrid_num_rows($req);
    printf("Existem %d eventos que ocorrem nas Olimpíadas de 2004 mas não ocorrem em 2000. Por exemplo:\n\n", $row_num);

    printf("%-15s %s\n", "Cód. do evento", "Nome do evento");
    printf("------------------------------\n");

    $row = cubrid_fetch_assoc($req);
    printf("%-15d %s\n", $row["event_code"], $row["name"]);
    $row = cubrid_fetch_assoc($req);
    printf("%-15d %s\n", $row["event_code"], $row["name"]);

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    Existem 27 eventos que ocorrem nas Olimpíadas de 2004 mas não ocorrem em 2000. Por exemplo:

    Cód. do evento  Nome do evento
    ------------------------------
    20063           +91kg
    20070           64kg

### Veja Também

- cubrid_execute() - Executa uma instrução preparada SQL
- cubrid_bind() - Vincula variáveis a instruções preparadas como parâmetros

# cubrid_put

(PECL CUBRID >= 8.3.0)

cubrid_put — Atualiza uma coluna usando OID

### Descrição

function cubrid_put(
resource `$conn_identifier`,
string `$oid`,
string `$attr` = ?,
mixed `$value`
): bool

A função cubrid_put() é usada para atualizar um atributo da instância do `oid` informado.

Pode-se atualizar um único atributo usando o tipo de dados string para definir `attr`. Nesse caso, pode-se usar dados do tipo inteiro, ponto flutuante ou string para o argumento `value`. Para atualizar vários números de atributos, pode-se desconsiderar o argumento `attr` e definir o argumento `value` com o tipo de dados de array associativo.

### Parâmetros

`conn_identifier`
  Identificador da conexão.
`oid`
  OID da instância a ser atualizada.
`attr`
  Nome do atributo a ser atualizado.
`value`
  Novo valor a ser atribuído ao atributo.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_put()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_put($conn, $oid, "b", array(2, 4, 8));

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    array(3) {
      [0]=>
      string(1) "2"
      [1]=>
      string(1) "4"
      [2]=>
      string(1) "8"
    }

### Veja Também

- cubrid_get() - Obtém um atributo usando OID
- cubrid_set_add() - Insere um único elemento a uma coluna tipo conjunto usando OID
- cubrid_set_drop() - Remove um elemento da coluna tipo conjunto usando OID
- cubrid_seq_insert() - Insere um elemento em uma coluna tipo sequência usando OID
- cubrid_seq_drop() - Remove um elemento de coluna tipo sequência usando OID
- cubrid_seq_put() - Atualiza o valor do elemento de coluna tipo sequência usando OID

# cubrid_rollback

(PECL CUBRID >= 8.3.0)

cubrid_rollback — Reverte uma transação

### Descrição

function cubrid_rollback(resource `$conn_identifier`): bool

A função cubrid_rollback() executa uma reversão na transação apontada por `conn_identifier`, atualmente em progresso.

A conexão ao servidor é fechada após a chamada a cubrid_rollback(). O identificador da conexão, no entanto, ainda será válido.

### Parâmetros

`conn_identifier`
  Identificador da conexão.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_rollback()

    <?php
    $conn = cubrid_connect("127.0.0.1", 33000, "demodb", "dba");
    cubrid_set_autocommit($conn,false);

    @cubrid_execute($conn, "DROP TABLE publishers");

    $sql = <<<EOD
    CREATE TABLE publishers(
    pub_id CHAR(3),
    pub_name VARCHAR(20),
    city VARCHAR(15),
    state CHAR(2),
    country VARCHAR(15)
    )
    EOD;

    if (!cubrid_execute($conn, $sql)) {
        printf("Módulo do erro: %d\nCódigo do erro: %d\nMensagem de erro: %s\n", cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

        cubrid_disconnect($conn);
        exit;
    }

    $req = cubrid_prepare($conn, "INSERT INTO publishers VALUES(?, ?, ?, ?, ?)");

    $id_list = array("P01", "P02", "P03", "P04");
    $name_list = array("Abatis Publishers", "Core Dump Books", "Schadenfreude Press", "Tenterhooks Press");
    $city_list = array("New York", "San Francisco", "Hamburg", "Berkeley");
    $state_list = array("NY", "CA", NULL, "CA");
    $country_list = array("USA", "USA", "Germany", "USA");

    for ($i = 0, $size = count($id_list); $i < $size; $i++) {
        cubrid_bind($req, 1, $id_list[$i]);
        cubrid_bind($req, 2, $name_list[$i]);
        cubrid_bind($req, 3, $city_list[$i]);
        cubrid_bind($req, 4, $state_list[$i]);
        cubrid_bind($req, 5, $country_list[$i]);

        if (!($ret = cubrid_execute($req))) {
            break;
        }
    }

    if (!$ret) {
        cubrid_rollback($conn);
    } else {
        cubrid_commit($conn);

        $req = cubrid_execute($conn, "SELECT * FROM publishers");
        while ($result = cubrid_fetch_assoc($req)) {
            printf("%-3s %-20s %-15s %-3s %-15s\n",
                $result["pub_id"], $result["pub_name"], $result["city"], $result["state"], $result["country"]);
        }
    }

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    P01 Abatis Publishers    New York        NY  USA
    P02 Core Dump Books      San Francisco   CA  USA
    P03 Schadenfreude Press  Hamburg             Germany
    P04 Tenterhooks Press    Berkeley        CA  USA

### Veja Também

- cubrid_commit() - Confirma uma transação
- cubrid_disconnect() - Fecha uma conexão ao banco de dados

# cubrid_schema

(PECL CUBRID >= 8.3.0)

cubrid_schema — Obtém informação do esquema solicitado

### Descrição

function cubrid_schema(
resource `$conn_identifier`,
int `$schema_type`,
string `$class_name` = ?,
string `$attr_name` = ?
): array

A função cubrid_schema() é usada para obter as informações do esquema solicitadas do banco de dados. Para obter informações sobre uma classe específica, `class_name` deve ser definido, para obter informações sobre um atributo específico (pode ser usada apenas com `CUBRID_SCH_ATTR_PRIVILEGE`), `attr_name` deve ser definido.

O resultado da função cubrid_schema() é retornado como um array bidimensional (coluna (array associativo) * linha (array numérico)). As tabelas a seguir mostram os tipos de esquema e a estrutura da coluna do array de resultados a ser retornada com base no tipo de esquema.

Composição do resultado de cada tipo
Esquema | Número da Coluna | Nome da Coluna | Valor
--- | --- | --- | ---
CUBRID_SCH_CLASS | 1 | NAME |
| 2 | TYPE | 0:classe de sistema 1:classe virtual 2:classe
CUBRID_SCH_VCLASS | 1 | NAME |
| 2 | TYPE | 1:classe virtual
CUBRID_SCH_QUERY_SPEC | 1 | QUERY_SPEC |
CUBRID_SCH_ATTRIBUTE / CUBRID_SCH_CLASS_ATTRIBUTE | 1 | ATTR_NAME |
| 2 | DOMAIN |
| 3 | SCALE |
| 4 | PRECISION |
| 5 | INDEXED | 1:indexado
| 6 | NOT NULL | 1:não nulo
| 7 | SHARED | 1:compartilhado
| 8 | UNIQUE | 1:exclusivo
| 9 | DEFAULT |
| 10 | ATTR_ORDER | base:1
| 11 | CLASS_NAME |
| 12 | SOURCE_CLASS |
| 13 | IS_KEY | 1:chave
CUBRID_SCH_METHOD / CUBRID_SCH_CLASS_METHOD | 1 | NAME |
| 2 | RET_DOMAIN |
| 3 | ARG_DOMAIN |
CUBRID_SCH_METHOD_FILE | 1 | METHOD_FILE |
CUBRID_SCH_SUPERCLASS / CUBRID_SCH_DIRECT_SUPER_CLASS / CUBRID_SCH_SUBCLASS | 1 | CLASS_NAME |
| 2 | TYPE | 0:classe de sistema 1:classe virtual 2:classe
CUBRID_SCH_CONSTRAINT | 1 | TYPE | 0:exclusivo 1:índice 2:exclusivo reverso 3:índice reverso
| 2 | NAME |
| 3 | ATTR_NAME |
| 4 | NUM_PAGES |
| 5 | NUM_KEYS |
| 6 | PRIMARY_KEY | 1:chave primária
| 7 | KEY_ORDER | base:1
CUBRID_SCH_TRIGGER | 1 | NAME |
| 2 | STATUS |
| 3 | EVENT |
| 4 | TARGET_CLASS |
| 5 | TARGET_ATTR |
| 6 | ACTION_TIME |
| 7 | ACTION |
| 8 | PRIORITY |
| 9 | CONDITION_TIME |
| 10 | CONDITION |
CUBRID_SCH_CLASS_PRIVILEGE / CUBRID_SCH_ATTR_PRIVILEGE | 1 | CLASS_NAME / ATTR_NAME |
| 2 | PRIVILEGE |
| 3 | GRANTABLE |
CUBRID_SCH_PRIMARY_KEY | 1 | CLASS_NAME |
| 2 | ATTR_NAME |
| 3 | KEY_SEQ | base:1
| 4 | KEY_NAME |
CUBRID_SCH_IMPORTED_KEYS / CUBRID_SCH_EXPORTED_KEYS / CUBRID_SCH_CROSS_REFERENCE | 1 | PKTABLE_NAME |
| 2 | PKCOLUMN_NAME |
| 3 | FKTABLE_NAME | base:1
| 4 | FKCOLUMN_NAME |
| 5 | KEY_SEQ | base:1
| 6 | UPDATE_ACTION | 0:cascata 1:restrição 2:sem ação 3:definir como nulo
| 7 | DELETE_ACTION | 0:cascata 1:restrição 2:sem ação 3:definir como nulo
| 8 | FK_NAME |
| 9 | PK_NAME |

### Parâmetros

`conn_identifier`
  Identificador da conexão.
`schema_type`
  Dados do esquema que precisam ser conhecidos.
`class_name`
  Classe da qual deseja-se conhecer o esquema.
`attr_name`
  Atributo do qual deseja-se conhecer o esquema.

### Valor Retornado

Array contendo a informação do esquema em caso de sucesso, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.1 | Alterado valor de retorno: quando houver falha, retorna false e não -1.

### Exemplos

Exemplo #1 Exemplo de cubrid_schema()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    printf("\n--- Chave Primária ---\n");
    $pk = cubrid_schema($conn, CUBRID_SCH_PRIMARY_KEY, "game");
    var_dump($pk);

    printf("\n--- Chaves Estrangeiras ---\n");
    $fk = cubrid_schema($conn, CUBRID_SCH_IMPORTED_KEYS, "game");
    var_dump($fk);

    printf("\n--- Atributo da Coluna ---\n");
    $attr = cubrid_schema($conn, CUBRID_SCH_ATTRIBUTE, "stadium", "area");
    var_dump($attr);

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    --- Chave Primária ---
    array(3) {
      [0]=>
      array(4) {
        ["CLASS_NAME"]=>
        string(4) "game"
        ["ATTR_NAME"]=>
        string(12) "athlete_code"
        ["KEY_SEQ"]=>
        string(1) "3"
        ["KEY_NAME"]=>
        string(41) "pk_game_host_year_event_code_athlete_code"
      }
      [1]=>
      array(4) {
        ["CLASS_NAME"]=>
        string(4) "game"
        ["ATTR_NAME"]=>
        string(10) "event_code"
        ["KEY_SEQ"]=>
        string(1) "2"
        ["KEY_NAME"]=>
        string(41) "pk_game_host_year_event_code_athlete_code"
      }
      [2]=>
      array(4) {
        ["CLASS_NAME"]=>
        string(4) "game"
        ["ATTR_NAME"]=>
        string(9) "host_year"
        ["KEY_SEQ"]=>
        string(1) "1"
        ["KEY_NAME"]=>
        string(41) "pk_game_host_year_event_code_athlete_code"
      }
    }

    --- Chaves Estrangeiras ---
    array(2) {
      [0]=>
      array(9) {
        ["PKTABLE_NAME"]=>
        string(7) "athlete"
        ["PKCOLUMN_NAME"]=>
        string(4) "code"
        ["FKTABLE_NAME"]=>
        string(4) "game"
        ["FKCOLUMN_NAME"]=>
        string(12) "athlete_code"
        ["KEY_SEQ"]=>
        string(1) "1"
        ["UPDATE_RULE"]=>
        string(1) "1"
        ["DELETE_RULE"]=>
        string(1) "1"
        ["FK_NAME"]=>
        string(20) "fk_game_athlete_code"
        ["PK_NAME"]=>
        string(15) "pk_athlete_code"
      }
      [1]=>
      array(9) {
        ["PKTABLE_NAME"]=>
        string(5) "event"
        ["PKCOLUMN_NAME"]=>
        string(4) "code"
        ["FKTABLE_NAME"]=>
        string(4) "game"
        ["FKCOLUMN_NAME"]=>
        string(10) "event_code"
        ["KEY_SEQ"]=>
        string(1) "1"
        ["UPDATE_RULE"]=>
        string(1) "1"
        ["DELETE_RULE"]=>
        string(1) "1"
        ["FK_NAME"]=>
        string(18) "fk_game_event_code"
        ["PK_NAME"]=>
        string(13) "pk_event_code"
      }
    }

    --- Atributo da Coluna ---
    array(1) {
      [0]=>
      array(13) {
        ["ATTR_NAME"]=>
        string(4) "area"
        ["DOMAIN"]=>
        string(1) "7"
        ["SCALE"]=>
        string(1) "2"
        ["PRECISION"]=>
        string(2) "10"
        ["INDEXED"]=>
        string(1) "0"
        ["NON_NULL"]=>
        string(1) "0"
        ["SHARED"]=>
        string(1) "0"
        ["UNIQUE"]=>
        string(1) "0"
        ["DEFAULT"]=>
        NULL
        ["ATTR_ORDER"]=>
        string(1) "4"
        ["CLASS_NAME"]=>
        string(7) "stadium"
        ["SOURCE_CLASS"]=>
        string(7) "stadium"
        ["IS_KEY"]=>
        string(1) "0"
      }
    }

# cubrid_seq_drop

(PECL CUBRID >= 8.3.0)

cubrid_seq_drop — Remove um elemento de coluna tipo sequência usando OID

### Descrição

function cubrid_seq_drop(
resource `$conn_identifier`,
string `$oid`,
string `$attr_name`,
int `$index`
): bool

A função cubrid_seq_drop() é usada para remover um elemento específico, do atributo tipo sequência informado, do banco de dados.

### Parâmetros

`conn_identifier`
  Identificador da conexão.
`oid`
  OID da instância a ser trabalhada.
`attr_name`
  Nome do atributo do qual elemento deve ser removido.
`index`
  Índice do elemento a ser removido (inicia em 1).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_seq_drop()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c sequence(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_seq_drop($conn, $oid, "c", 4);

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    array(4) {
      [0]=>
      string(2) "11"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
      [3]=>
      string(3) "333"
    }
    array(3) {
      [0]=>
      string(2) "11"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
    }

### Veja Também

- cubrid_seq_insert() - Insere um elemento em uma coluna tipo sequência usando OID
- cubrid_seq_put() - Atualiza o valor do elemento de coluna tipo sequência usando OID

# cubrid_seq_insert

(PECL CUBRID >= 8.3.0)

cubrid_seq_insert — Insere um elemento em uma coluna tipo sequência usando OID

### Descrição

function cubrid_seq_insert(
resource `$conn_identifier`,
string `$oid`,
string `$attr_name`,
int `$index`,
string `$seq_element`
): bool

A função cubrid_seq_insert() é usada para inserir um elemento em um atributo tipo sequência na posição especificada.

### Parâmetros

`conn_identifier`
  Identificador da conexão.
`oid`
  OID da instância a ser trabalhada.
`attr_name`
  Nome do atributo ao qual a instância deve ser inserida.
`index`
  Posição do elemento na qual o elemento deve ser inserido (inicia em 1).
`seq_element`
  Conteúdo do elemento a ser inserido.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_seq_insert()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c sequence(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_seq_insert($conn, $oid, "c", 5, "44");

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    array(4) {
      [0]=>
      string(2) "11"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
      [3]=>
      string(3) "333"
    }
    array(5) {
      [0]=>
      string(2) "11"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
      [3]=>
      string(3) "333"
      [4]=>
      string(2) "44"
    }

### Veja Também

- cubrid_seq_drop() - Remove um elemento de coluna tipo sequência usando OID
- cubrid_seq_put() - Atualiza o valor do elemento de coluna tipo sequência usando OID

# cubrid_seq_put

(PECL CUBRID >= 8.3.0)

cubrid_seq_put — Atualiza o valor do elemento de coluna tipo sequência usando OID

### Descrição

function cubrid_seq_put(
resource `$conn_identifier`,
string `$oid`,
string `$attr_name`,
int `$index`,
string `$seq_element`
): bool

A função cubrid_seq_put() é usada para atualizar o conteúdo do elemento específico em um atributo tipo sequência usando OID.

### Parâmetros

`conn_identifier`
  Identificador da conexão.
`oid`
  OID da instância a ser trabalhada.
`attr_name`
  Nome do atributo do qual um elemento será atualizado.
`index`
  Índice (iniciando em 1) do elemento a ser atualizado.
`seq_element`
  Novo conteúdo para a atualização.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_seq_put()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c sequence(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_seq_put($conn, $oid, "c", 1, "111");

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    array(4) {
      [0]=>
      string(2) "11"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
      [3]=>
      string(3) "333"
    }
    array(4) {
      [0]=>
      string(3) "111"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
      [3]=>
      string(3) "333"
    }

### Veja Também

- cubrid_seq_drop() - Remove um elemento de coluna tipo sequência usando OID
- cubrid_seq_insert() - Insere um elemento em uma coluna tipo sequência usando OID

# cubrid_set_add

(PECL CUBRID >= 8.3.0)

cubrid_set_add — Insere um único elemento a uma coluna tipo conjunto usando OID

### Descrição

function cubrid_set_add(
resource `$conn_identifier`,
string `$oid`,
string `$attr_name`,
string `$set_element`
): bool

A função cubrid_set_add() é usada para inserir um único elemento a um atributo tipo conjunto (conjunto, multi-conjunto, sequência) informado.

### Parâmetros

`conn_identifier`
  Identificador da conexão.
`oid`
  OID da instância a ser trabalhada.
`attr_name`
  Nome do atributo no qual o elemento será inserido.
`set_element`
  Conteúdo do elemento a ser inserido.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_set_add()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_set_add($conn, $oid, "b", "4");

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    array(4) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
      [3]=>
      string(1) "4"
    }

### Veja Também

- cubrid_seq_drop() - Remove um elemento de coluna tipo sequência usando OID

# cubrid_set_autocommit

(PECL CUBRID >= 8.4.0)

cubrid_set_autocommit — Define o modo de auto-confirmação da conexão

### Descrição

function cubrid_set_autocommit(resource `$conn_identifier`, bool `$mode`): bool

A função cubrid_set_autocommit() é usada para definir o modo de auto-confirmação do banco de dados CUBRID da conexão atual.

No CUBRID PHP, o modo de auto-confirmação é desligado por padrão para gerenciamento de transações. Quando o modo de auto-confirmação é ligado, qualquer trabalho pendente é automaticamente confirmado.

### Parâmetros

`conn_identifier`
  Identificador da conexão.
`mode`
  Modo de auto-confirmação. As seguintes constantes podem ser usadas:
  - `CUBRID_AUTOCOMMIT_FALSE`
  - `CUBRID_AUTOCOMMIT_TRUE`

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- cubrid_get_autocommit() - Obtém o modo de auto-confirmação da conexão
- cubrid_commit() - Confirma uma transação

# cubrid_set_db_parameter

(PECL CUBRID >= 8.4.0)

cubrid_set_db_parameter — Define os parâmetros do banco de dados CUBRID

### Descrição

function cubrid_set_db_parameter(resource `$conn_identifier`, int `$param_type`, int `$param_value`): bool

A função cubrid_set_db_parameter() é usada para definir os parâmetros do banco de dados CUBRID. Ela pode definir os seguintes parâmetros:

- `PARAM_ISOLATION_LEVEL`
- `PARAM_LOCK_TIMEOUT`

> Nota: O modo de auto-confirmação pode ser definido usando-se cubrid_set_autocommit().

### Parâmetros

`conn_identifier`
  O indentificador de conexão CUBRID. Se não for especificado, a última conexão aberta por cubrid_connect() será usada.
`param_type`
  Tipo do parâmetro do banco de dados.
`param_value`
  Nível de isolamento (1 a 6) ou tempo limite de trava (em segundos).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_get_db_parameter()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $params = cubrid_get_db_parameter($conn);
    var_dump($params);

    cubrid_set_autocommit($conn, CUBRID_AUTOCOMMIT_TRUE);
    cubrid_set_db_parameter($conn, CUBRID_PARAM_ISOLATION_LEVEL, 2);

    $params_new = cubrid_get_db_parameter($conn);
    var_dump($params_new);

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    array(4) {
      ["PARAM_ISOLATION_LEVEL"]=>
      int(3)
      ["PARAM_LOCK_TIMEOUT"]=>
      int(-1)
      ["PARAM_MAX_STRING_LENGTH"]=>
      int(1073741823)
      ["PARAM_AUTO_COMMIT"]=>
      int(0)
    }
    array(4) {
      ["PARAM_ISOLATION_LEVEL"]=>
      int(2)
      ["PARAM_LOCK_TIMEOUT"]=>
      int(-1)
      ["PARAM_MAX_STRING_LENGTH"]=>
      int(1073741823)
      ["PARAM_AUTO_COMMIT"]=>
      int(1)
    }

### Veja Também

- cubrid_get_db_parameter() - Retorna os parâmetros do banco de dados CUBRID
- cubrid_set_autocommit() - Define o modo de auto-confirmação da conexão

# cubrid_set_drop

(PECL CUBRID >= 8.3.0)

cubrid_set_drop — Remove um elemento da coluna tipo conjunto usando OID

### Descrição

function cubrid_set_drop(
resource `$conn_identifier`,
string `$oid`,
string `$attr_name`,
string `$set_element`
): bool

A função cubrid_set_drop() é usada para remover um elemento específico de um atributo tipo conjunto (conjunto, multi-conjunto) do banco de dados.

### Parâmetros

`conn_identifier`
  Identificador da conexão.
`oid`
  OID da instância a ser trabalhada.
`attr_name`
  Nome do atributo a ter o elemento removido.
`set_element`
  Conteúdo do elemento a ser removido.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_set_drop()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_set_drop($conn, $oid, "b", "1");

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    array(2) {
      [0]=>
      string(1) "2"
      [1]=>
      string(1) "3"
    }

### Veja Também

- cubrid_set_add() - Insere um único elemento a uma coluna tipo conjunto usando OID

# cubrid_set_query_timeout

(PECL CUBRID >= 8.4.1)

cubrid_set_query_timeout — Define o tempo limite de execução de consulta

### Descrição

function cubrid_set_query_timeout(resource `$req_identifier`, int `$timeout`): bool

A função cubrid_set_query_timeout() é usada para definir o tempo limite de execução de consulta.

### Parâmetros

`req_identifier`
  Identificador da requisição.
`timeout`
  Tempo limite em milissegundos.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- cubrid_get_query_timeout() - Obtém o tempo limite de consulta para a requisição

# cubrid_version

(PECL CUBRID >= 8.3.0)

cubrid_version — Obtém a versão do módulo do CUBRID PHP

### Descrição

function cubrid_version(): string

A função cubrid_version() é usada para obter a versão do módulo do CUBRID PHP.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Informação de versão (ex.: "8.3.1.0001").

### Exemplos

Exemplo #1 Exemplo de cubrid_version()

    <?php
    printf("%-30s %s\n", "Versão do CUBRID PHP:", cubrid_version());

    printf("\n");

    $conn = cubrid_connect("localhost", 33088, "demodb", "dba");

    if (!$conn) {
        die('Erro de conexão ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-30s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-30s %s\n", "Informação do Servidor:", $server_info);
    printf("%-30s %s\n", "Informação do Cliente:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-30s %s\n", "Conjunto de Caracteres do CUBRID:", $charset);

    cubrid_disconnect($conn);

    ?>

O exemplo acima produzirá:

    Versão do CUBRID PHP:          9.1.0.0001

    PARAM_ISOLATION_LEVEL          3
    LOCK_TIMEOUT                   -1
    MAX_STRING_LENGTH              1073741823
    PARAM_AUTO_COMMIT              1

    Informação do Servidor:        9.1.0.0212
    Informação do Cliente:         9.1.0

    Conj. de Caracteres do CUBRID: iso8859-1

### Veja Também

- cubrid_error_code() - Obtém código de erro para a chamada de função mais recente
- cubrid_error_code_facility() - Obtém o código do módulo do erro

## Índice

- cubrid_bind — Vincula variáveis a instruções preparadas como parâmetros
- cubrid_close_prepare — Fecha o identificador de requisição
- cubrid_close_request — Fecha o identificador de requisição
- cubrid_col_get — Obtém conteúdo de coluna tipo coleção usando OID
- cubrid_col_size — Obtém o número de elementos de coluna tipo coleção usando OID
- cubrid_column_names — Obtém nomes de colunas no resultado
- cubrid_column_types — Obtém tipos de colunas no resultado
- cubrid_commit — Confirma uma transação
- cubrid_connect — Abre uma conexão a um servidor CUBRID
- cubrid_connect_with_url — Prepara o ambiente para conexão ao servidor CUBRID
- cubrid_current_oid — Obtém o OID da posição atual do cursor
- cubrid_disconnect — Fecha uma conexão ao banco de dados
- cubrid_drop — Remove uma instância usando OID
- cubrid_error_code — Obtém código de erro para a chamada de função mais recente
- cubrid_error_code_facility — Obtém o código do módulo do erro
- cubrid_error_msg — Obtém mensagem de erro da chamada de função mais recente
- cubrid_execute — Executa uma instrução preparada SQL
- cubrid_fetch — Busca a próxima linha do conjunto de resultados
- cubrid_free_result — Libera a memória ocupada pelos dados do resultado
- cubrid_get — Obtém um atributo usando OID
- cubrid_get_autocommit — Obtém o modo de auto-confirmação da conexão
- cubrid_get_charset — Retorna o conjunto de caracteres da conexão CUBRID atual
- cubrid_get_class_name — Obtém o nome da classe usando OID
- cubrid_get_client_info — Retorna a versão da biblioteca cliente
- cubrid_get_db_parameter — Retorna os parâmetros do banco de dados CUBRID
- cubrid_get_query_timeout — Obtém o tempo limite de consulta para a requisição
- cubrid_get_server_info — Retorna a versão do servidor CUBRID
- cubrid_insert_id — Retorna o ID gerado pela última coluna AUTO_INCREMENT atualizada
- cubrid_is_instance — Verifica se a instância apontada pelo OID existe
- cubrid_lob_close — Fecha os dados BLOB/CLOB
- cubrid_lob_export — Exporta dados BLOB/CLOB para um arquivo
- cubrid_lob_get — Obtém dados BLOB/CLOB
- cubrid_lob_send — Lê dados BLOB/CLOB e envia direto ao navegador
- cubrid_lob_size — Obtém o tamanho dos dados BLOB/CLOB
- cubrid_lob2_bind — Vincula um objeto LOB ou uma string como objeto LOB a uma instrução preparada como parâmetros
- cubrid_lob2_close — Fecha objeto LOB
- cubrid_lob2_export — Exporta o objeto LOB para um arquivo
- cubrid_lob2_import — Importa dados BLOB/CLOB de um arquivo
- cubrid_lob2_new — Cria um objeto LOB
- cubrid_lob2_read — Lê bytes de dados BLOB/CLOB
- cubrid_lob2_seek — Move o cursor de um objeto LOB
- cubrid_lob2_seek64 — Move o cursor de um objeto LOB
- cubrid_lob2_size — Obtém o tamanho do objeto LOB
- cubrid_lob2_size64 — Obtém o tamanho do objeto LOB
- cubrid_lob2_tell — Informa a posição do cursor do objeto LOB
- cubrid_lob2_tell64 — Informa a posição do cursor do objeto LOB
- cubrid_lob2_write — Escreve em um objeto LOB
- cubrid_lock_read — Define uma trava de leitura em um OID informado
- cubrid_lock_write — Define uma trava de escrita em um OID informado
- cubrid_move_cursor — Move o cursor no resultado
- cubrid_next_result — Obtém o resultado da próxima consulta quando múltiplas instruções SQL estão sendo executadas
- cubrid_num_cols — Retorna o número de colunas no resultado
- cubrid_num_rows — Obtém o número de linhas no resultado
- cubrid_pconnect — Abre uma conexão persistente a um servidor CUBRID
- cubrid_pconnect_with_url — Abre uma conexão persistente com o servidor CUBRID
- cubrid_prepare — Prepara uma instrução SQL para execução
- cubrid_put — Atualiza uma coluna usando OID
- cubrid_rollback — Reverte uma transação
- cubrid_schema — Obtém informação do esquema solicitado
- cubrid_seq_drop — Remove um elemento de coluna tipo sequência usando OID
- cubrid_seq_insert — Insere um elemento em uma coluna tipo sequência usando OID
- cubrid_seq_put — Atualiza o valor do elemento de coluna tipo sequência usando OID
- cubrid_set_add — Insere um único elemento a uma coluna tipo conjunto usando OID
- cubrid_set_autocommit — Define o modo de auto-confirmação da conexão
- cubrid_set_db_parameter — Define os parâmetros do banco de dados CUBRID
- cubrid_set_drop — Remove um elemento da coluna tipo conjunto usando OID
- cubrid_set_query_timeout — Define o tempo limite de execução de consulta
- cubrid_version — Obtém a versão do módulo do CUBRID PHP

# Funções de compatibilidade CUBRID MySQL

# cubrid_affected_rows

(PECL CUBRID >= 8.3.0)

cubrid_affected_rows — Retorna o número de linhas afetadas pela última instrução SQL

### Descrição

function cubrid_affected_rows(resource `$conn_identifier` = ?): int
function cubrid_affected_rows(resource `$req_identifier` = ?): int

A função cubrid_affected_rows() é usada para obter o número de linhas afetadas pela instrução SQL (INSERT, DELETE, UPDATE).

### Parâmetros

`conn_identifier`
  A conexão CUBRID. Se o identificador da conexão não for especificado, será assumido a última conexão aberta por cubrid_connect().
`req_identifier`
  O identificador de requisição pode ser retornado de cubrid_prepare() ou cubrid_execute(). Se o identificador da requisição não for especificado, será assumido o último identificador requisitado por cubrid_prepare() ou cubrid_execute().

### Valor Retornado

Número de linhas afetadas pela instrução SQL em caso de sucesso.

-1, quando a instrução SQL não for INSERT, DELETE ou UPDATE.

`false`, quando o identificador da requisição não for especificado e não houver última requisição.

### Exemplos

Exemplo #1 Exemplo de cubrid_affected_rows()

    <?php
    $conn = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
    cubrid_execute($conn, "DROP TABLE IF EXISTS cubrid_test");
    cubrid_execute($conn, "CREATE TABLE cubrid_test (d varchar)");
    $sql_stmt = "INSERT INTO cubrid_test(d) VALUES('php-test')";
    $req = cubrid_prepare($conn, $sql_stmt);

    for ($i = 0; $i < 10; $i++) {
        cubrid_execute($req);
    }
    cubrid_commit($conn);

    $req = cubrid_execute($conn, "DELETE FROM cubrid_test WHERE d='php-test'", CUBRID_ASYNC);
    var_dump(cubrid_affected_rows());
    var_dump(cubrid_affected_rows($conn));
    var_dump(cubrid_affected_rows($req));

    cubrid_disconnect($conn);

    print "pronto!";
    ?>

O exemplo acima produzirá:

    int(10)
    int(10)
    int(10)
    pronto!

### Veja Também

- cubrid_execute() - Executa uma instrução preparada SQL

# cubrid_client_encoding

(PECL CUBRID >= 8.3.1)

cubrid_client_encoding — Retorna o conjunto de caracteres de conexão CUBRID atual

### Descrição

function cubrid_client_encoding(resource `$conn_identifier` = ?): string

Esta função retorna o conjunto de caracteres de conexão CUBRID atual e é semelhante à função CUBRID cubrid_get_charset().

### Parâmetros

`conn_identifier`
  A conexão CUBRID. Se o identificador da conexão não for especificado, será assumido a última conexão aberta por cubrid_connect().

### Valor Retornado

Uma string que representa o conjunto de caracteres da conexão CUBRID em caso de sucesso.

`false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_client_encoding()

    <?php

    $con = cubrid_connect("localhost", 33000, "demodb");
    if (!$con)
    {
        die('Não foi possível conectar.');
    }

    printf("Conjunto de caracteres atual do CUBRID: %s\n", cubrid_client_encoding($con));

    ?>

O exemplo acima produzirá:

    Conjunto de caracteres atual do CUBRID: iso8859-1

### Veja Também

- cubrid_get_charset() - Retorna o conjunto de caracteres da conexão CUBRID atual

# cubrid_close

(PECL CUBRID >= 8.3.1)

cubrid_close — Fecha conexão CUBRID

### Descrição

function cubrid_close(resource `$conn_identifier` = ?): bool

A função cubrid_close() finaliza a transação atualmente em processo, fecha o identificador de conexão e desconecta do servidor. Se houver algum identificador de requisição ainda não fechado neste momento, ele será fechado. É semelhante à função CUBRID cubrid_disconnect().

### Parâmetros

`conn_identifier`
  O identificador de conexão CUBRID. Se o identificador da conexão não for especificado, será assumida a última conexão aberta por cubrid_connect().

### Valor Retornado

`true` em caso de sucesso.

`false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_close()

    <?php
    $con = cubrid_connect ("localhost", 33000, "demodb");
    if ($con) {
       echo "conectado com sucesso";
       $req = cubrid_execute ( $con, "insert into person values(1,'James')");
       if ($req) {
          cubrid_close_request ($req);
          cubrid_commit ($con);
       } else {
          cubrid_rollback ($con);
       }
       cubrid_close ($con);
    }
    ?>

### Veja Também

- cubrid_disconnect() - Fecha uma conexão ao banco de dados
- cubrid_connect() - Abre uma conexão a um servidor CUBRID
- cubrid_connect_with_url() - Prepara o ambiente para conexão ao servidor CUBRID

# cubrid_data_seek

(PECL CUBRID >= 8.3.0)

cubrid_data_seek — Move o ponteiro de linha interno do resultado CUBRID

### Descrição

function cubrid_data_seek(resource `$result`, int `$row_number`): bool

Esta função executa a movimentação do ponteiro de linha interno do resultado CUBRID (associado ao identificador de resultado especificado) para apontar a um número de linha específico. Existem funções, como cubrid_fetch_assoc(), que usam o valor armazenado do número da linha atual.

### Parâmetros

`result`
  O resultado.
`row_number`
  Este é o número da linha desejada do novo ponteiro de resultado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_data_seek()

    <?php
    $conn = cubrid_connect("127.0.0.1", 33000, "demodb");

    $req = cubrid_execute($conn, "SELECT * FROM code");
    cubrid_data_seek($req, 0);

    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_data_seek($req, 2);
    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_data_seek($req, 4);
    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    array(2) {
      [0]=>
      string(1) "X"
      [1]=>
      string(5) "Mixed"
    }
    array(2) {
      [0]=>
      string(1) "M"
      [1]=>
      string(3) "Man"
    }
    array(2) {
      [0]=>
      string(1) "S"
      [1]=>
      string(6) "Silver"
    }

# cubrid_db_name

(PECL CUBRID >= 8.3.1)

cubrid_db_name — Obtém o nome do banco de dados dos resultados de cubrid_list_dbs

### Descrição

function cubrid_db_name(array `$result`, int `$index`): string

Recupera o nome do banco de dados a partir de uma chamada a cubrid_list_dbs().

### Parâmetros

`result`
  O ponteiro de resultado de uma chamada a cubrid_list_dbs().
`index`
  O índice no conjunto de resultados.

### Valor Retornado

Retorna o nome do banco de dados em caso de sucesso e `false` em caso de falha. Se `false` for retornado, use cubrid_error() para determinar a natureza do erro.

### Exemplos

Exemplo #1 Exemplo de cubrid_db_name()

    <?php
    error_reporting(E_ALL);

    $conn = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
    $db_list = cubrid_list_dbs($conn);

    $i = 0;
    $cnt = count($db_list);
    while ($i < $cnt) {
        echo cubrid_db_name($db_list, $i) . "\n";
        $i++;
    }
    ?>

O exemplo acima produzirá:

    demodb

### Veja Também

- cubrid_list_dbs() - Retorna um array com a lista de todos os bancos de dados CUBRID existentes

# cubrid_errno

(PECL CUBRID >= 8.3.1)

cubrid_errno — Retorna o valor numérico da mensagem de erro da operação CUBRID anterior

### Descrição

function cubrid_errno(resource `$conn_identifier` = ?): int

Retorna o número do erro da última função CUBRID.

A função cubrid_errno() é usada para obter o código do erro ocorrido durante a execução da API. Normalmente, ela obtém o código de erro quando a API retorna um valor falso.

### Parâmetros

`conn_identifier`
  O identificador de conexão CUBRID. Se o identificador da conexão não for especificado, será assumida a última conexão aberta por cubrid_connect().

### Valor Retornado

Retorna o número do erro da última função CUBRID ou `0` (zero) se nenhum erro tiver ocorrido.

### Exemplos

Exemplo #1 Exemplo de cubrid_errno()

    <?php
    $con = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
    $req = cubrid_execute($con, "select id, name from person");
    if ($req) {
        while (list ($id, $name) = cubrid_fetch($req))
        echo $id, $name;
    } else {
        echo "Código de Erro: ", cubrid_errno($con);
        echo " Mensagem de Erro: ", cubrid_error($con);
    }
    ?>

O exemplo acima produzirá:

    Código de Erro: -493 Mensagem de Erro: Syntax: Unknown class "person". select id, [name] from person

### Veja Também

- cubrid_error() - Obtém a mensagem de erro
- cubrid_error_code() - Obtém código de erro para a chamada de função mais recente
- cubrid_error_msg() - Obtém mensagem de erro da chamada de função mais recente

# cubrid_error

(PECL CUBRID >= 8.3.1)

cubrid_error — Obtém a mensagem de erro

### Descrição

function cubrid_error(resource `$connection` = ?): string

A função cubrid_error() é usada para obter a mensagem de erro que ocorreu durante o uso da API CUBRID. Normalmente, recebe uma mensagem de erro quando a API retorna um valor falso.

### Parâmetros

`connection`
  A conexão CUBRID.

### Valor Retornado

Mensagem do erro ocorrido.

### Exemplos

Exemplo #1 Exemplo de cubrid_error()

    <?php
    $con = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
    $req = cubrid_execute($con, "select id, name from person");
    if ($req) {
        while (list ($id, $name) = cubrid_fetch($req))
        echo $id, $name;
    } else {
        echo "Código de Erro: ", cubrid_errno($con);
        echo " Mensagem de Erro: ", cubrid_error($con);
    }
    ?>

O exemplo acima produzirá:

    Código de Erro: -493 Mensagem de Erro: Syntax: Unknown class "person". select id, [name] from person

### Veja Também

- cubrid_errno() - Retorna o valor numérico da mensagem de erro da operação CUBRID anterior
- cubrid_error_code() - Obtém código de erro para a chamada de função mais recente
- cubrid_error_msg() - Obtém mensagem de erro da chamada de função mais recente

# cubrid_fetch_array

(PECL CUBRID >=8.3.0)

cubrid_fetch_array — Busca uma linha de resultado como um array associativo, numérico ou ambos

### Descrição

function cubrid_fetch_array(resource `$result`, int `$type` = CUBRID_BOTH): array

A função cubrid_fetch_array() é usada para obter uma única linha do resultado da consulta e retorna um array. O cursor move-se automaticamente para a próxima linha após a obtenção do resultado.

### Parâmetros

`result`
  `Result` vem de uma chamada a cubrid_execute()
`type`
  Tipo de array do resultado obtido: CUBRID_NUM, CUBRID_ASSOC, CUBRID_BOTH. Se for necessário operar o objeto LOB, pode-se usar CUBRID_LOB.

### Valor Retornado

Retorna um array de strings que corresponde à linha buscada em caso de sucesso..

`false`, quando não houver mais linhas; NULL, em caso de falha.

O tipo de array retornado depende de como o tipo é definido. Ao usar CUBRID_BOTH (padrão), será obtido um array com índices associativos e numéricos e será possível decidir qual tipo de dados será usado definindo o argumento `type`. A variável `type` pode ser definida com um dos seguintes valores:

- CUBRID_NUM : Array numérico (baseado em 0)
- CUBRID_ASSOC : Array associativo
- CUBRID_BOTH : Array numérico e associativo (padrão)

### Exemplos

Exemplo #1 Exemplo de cubrid_fetch_array()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT name,area,seats,address FROM stadium WHERE nation_code='GRE' AND seats > 10000");

    printf("%-40s %-10s %-9s %-20s\n", "Nome", "Área", "Assentos", "Endereço");
    while ($row = cubrid_fetch_array($req, CUBRID_NUM)) {
        printf("%-40s %-10s %-9s %-20s\n", $row[0], $row[1], $row[2], $row[3]);
    }

    // se for desejado operar um objeto LOB, pode-se usar cubrid_fetch_array($req, CUBRID_NUM | CUBRID_LOB)

    cubrid_close_request($req);

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    Nome                                     Área       Assentos  Endereço
    Panathinaiko Stadium                     86300.00   50000     Athens, Greece
    Olympic Stadium                          54700.00   13000     Athens, Greece
    Olympic Indoor Hall                      34100.00   18800     Athens, Greece
    Olympic Hall                             52400.00   21000     Athens, Greece
    Olympic Aquatic Centre                   42500.00   11500     Athens, Greece
    Markopoulo Olympic Equestrian Centre     64000.00   15000     Markopoulo, Athens, Greece
    Faliro Coastal Zone Olympic Complex      34650.00   12171     Faliro, Athens, Greece
    Athens Olympic Stadium                   120400.00  71030     Maroussi, Athens, Greece
    Ano Liossia                              34000.00   12000     Ano Liosia, Athens, Greece

### Veja Também

- cubrid_execute() - Executa uma instrução preparada SQL
- cubrid_fetch() - Busca a próxima linha do conjunto de resultados
- cubrid_fetch_row() - Retorna um array numérico com os valores da linha atual
- cubrid_fetch_assoc() - Retorna o array associativo que corresponde à linha buscada
- cubrid_fetch_object() - Busca a próxima linha e retorna-a como um objeto

# cubrid_fetch_assoc

(PECL CUBRID >= 8.3.0)

cubrid_fetch_assoc — Retorna o array associativo que corresponde à linha buscada

### Descrição

function cubrid_fetch_assoc(resource `$result`, int `$type` = ?): array

Esta função retorna o array associativo que corresponde à linha buscada e então move o ponteiro de dados interno para frente ou retorna FALSE quando o final é alcançado.

### Parâmetros

`result`
  `result` vem de uma chamada a cubrid_execute()
`type`
  O tipo só pode ser CUBRID_LOB, este parâmetro será utilizado somente quando for necessário operar o objeto LOB.

### Valor Retornado

Array associativo em caso de sucesso.

`false` quando não houver mais linhas; NULL em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_fetch_assoc()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT name,area,seats,address FROM stadium WHERE nation_code='GRE' AND seats > 10000");

    printf("%-40s %-10s %-9s %-20s\n", "Nome", "Área", "Assentos", "Endereço");
    while ($row = cubrid_fetch_assoc($req)) {
        printf("%-40s %-10s %-9s %-20s\n",
            $row["name"], $row["area"], $row["seats"], $row["address"]);
    }

    // se for desejado operar um objeto LOB, pode-se usar cubrid_fetch_assoc($req, CUBRID_LOB)

    cubrid_close_request($req);

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    Nome                                     Área       Assentos  Endereço
    Panathinaiko Stadium                     86300.00   50000     Athens, Greece
    Olympic Stadium                          54700.00   13000     Athens, Greece
    Olympic Indoor Hall                      34100.00   18800     Athens, Greece
    Olympic Hall                             52400.00   21000     Athens, Greece
    Olympic Aquatic Centre                   42500.00   11500     Athens, Greece
    Markopoulo Olympic Equestrian Centre     64000.00   15000     Markopoulo, Athens, Greece
    Faliro Coastal Zone Olympic Complex      34650.00   12171     Faliro, Athens, Greece
    Athens Olympic Stadium                   120400.00  71030     Maroussi, Athens, Greece
    Ano Liossia                              34000.00   12000     Ano Liosia, Athens, Greece

### Veja Também

- cubrid_execute() - Executa uma instrução preparada SQL
- cubrid_fetch() - Busca a próxima linha do conjunto de resultados
- cubrid_fetch_row() - Retorna um array numérico com os valores da linha atual
- cubrid_fetch_array() - Busca uma linha de resultado como um array associativo, numérico ou ambos
- cubrid_fetch_object() - Busca a próxima linha e retorna-a como um objeto

# cubrid_fetch_field

(PECL CUBRID >= 8.3.1)

cubrid_fetch_field — Obtém informações da coluna de um resultado e retorna como um objeto

### Descrição

function cubrid_fetch_field(resource `$result`, int `$field_offset` = 0): object

Esta função retorna um objeto com certas propriedades da coluna específica. As propriedades do objeto são:

`name`
  nome da coluna
`table`
  nome da tabela à qual a coluna pertence
`def`
  valor padrão da coluna
`max_length`
  comprimento máximo da coluna
`not_null`
  1 se a coluna não puder ser NULL
`primary_key`
  1 se a coluna for uma chave primária
`unique_key`
  1 se a coluna for uma chave exclusiva
`multiple_key`
  1 se a coluna for uma chave não exclusiva
`numeric`
  1 se a coluna for numérica
`blob`
  1 se a coluna for um BLOB
`type`
  o tipo da coluna
`unsigned`
  1 se a coluna for sem sinal
`zerofill`
  1 se a coluna for preenchida com zeros

### Parâmetros

`result`
  `result` vem de uma chamada a cubrid_execute()
`field_offset`
  O deslocamento numérico do campo. Se não especificado, o próximo campo (que ainda não tiver sido obtido por esta função) será recuperado. O `field_offset` inicia em 0.

### Valor Retornado

Objeto com certas propriedades da coluna específica em caso de sucesso.

`false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_fetch_field()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT event_code,athlete_code,nation_code,game_date FROM game WHERE host_year=1988 and event_code=20001;");

    var_dump(cubrid_fetch_row($req));

    cubrid_field_seek($req, 1);
    $field = cubrid_fetch_field($req);

    printf("\n--- Propriedades do Campo ---\n");
    printf("%-30s %s\n", "nome:", $field->name);
    printf("%-30s %s\n", "tabela:", $field->table);
    printf("%-30s \"%s\"\n", "valor padrão:", $field->def);
    printf("%-30s %d\n", "comprimento máximo:", $field->max_length);
    printf("%-30s %d\n", "não nulo:", $field->not_null);
    printf("%-30s %d\n", "chave primária:", $field->primary_key);
    printf("%-30s %d\n", "chave exclusiva:", $field->unique_key);
    printf("%-30s %d\n", "chave múltipla:", $field->multiple_key);
    printf("%-30s %d\n", "numérico:", $field->numeric);
    printf("%-30s %d\n", "blob:", $field->blob);
    printf("%-30s %s\n", "tipo:", $field->type);
    printf("%-30s %d\n", "sem sinal:", $field->unsigned);
    printf("%-30s %d\n", "preenchido com zero:", $field->zerofill);

    cubrid_close_request($req);

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    array(4) {
      [0]=>
      string(5) "20001"
      [1]=>
      string(5) "16681"
      [2]=>
      string(3) "KOR"
      [3]=>
      string(9) "1988-9-30"
    }

    --- Propriedades do Campo ---
    nome:                          athlete_code
    tabela:                        game
    valor padrão:                  ""
    comprimento máximo:            0
    não nulo:                      1
    chave primária:                1
    chave exclusiva:               1
    chave múltipla:                0
    numérico:                      1
    blob:                          0
    tipo:                          integer
    sem sinal:                     0
    preenchido com zero:           0

# cubrid_fetch_lengths

(PECL CUBRID >= 8.3.0)

cubrid_fetch_lengths — Retorna um array com os comprimentos dos valores de cada campo da linha atual

### Descrição

function cubrid_fetch_lengths(resource `$result`): array

Esta função retorna um array numérico com os comprimentos dos valores de cada campo da linha atual do conjunto de resultados ou retorna FALSE em caso de falha.

> Nota: Se o tipo de dados do campo for BLOB/CLOB, seu comprimento deve ser obtido usando cubrid_lob_size().

### Parâmetros

`result`
  `result` vem de uma chamada a cubrid_execute()

### Valor Retornado

Um array numérico em caso de sucesso.

`false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_fetch_lengths()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $row = cubrid_fetch_row($result);
    print_r($row);

    $lens = cubrid_fetch_lengths($result);
    print_r($lens);

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    Array
    (
        [0] => 2004
        [1] => 20085
        [2] => 15118
        [3] => 30134
        [4] => AUS
        [5] => G
        [6] => 2004-8-20
    )
    Array
    (
        [0] => 4
        [1] => 5
        [2] => 5
        [3] => 5
        [4] => 3
        [5] => 1
        [6] => 10
    )

# cubrid_fetch_object

(PECL CUBRID >= 8.3.0)

cubrid_fetch_object — Busca a próxima linha e retorna-a como um objeto

### Descrição

function cubrid_fetch_object(
resource `$result`,
string `$class_name` = ?,
array `$params` = ?,
int `$type` = ?
): object

Esta função retorna um objeto com os nomes das colunas do conjunto de resultados como propriedades. Os valores dessas propriedades são extraídos da linha atual do resultado.

### Parâmetros

`result`
  `result` vem de uma chamada a cubrid_execute()
`class_name`
  O nome da classe a ser instanciada. Se não for especificado, é retornado um objeto stdClass (stdClass é a classe vazia genérica do PHP usada ao converter outros tipos para objetos).
`params`
  Um array opcional de parâmetros a serem passados ​​ao construtor para objetos `class_name`.
`type`
  O tipo só pode ser CUBRID_LOB, este parâmetro será utilizado somente quando for necessário operar o objeto LOB.

### Valor Retornado

Um objeto em caso de sucesso.

`false`, quando não houver mais linhas; NULL em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_fetch_object()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $res = cubrid_execute($conn, "SELECT * FROM code");

    var_dump(cubrid_fetch_object($res));

    // se for desejado operar em objeto LOB, pode-se usar cubrid_fetch_object($res, CUBRID_LOB)

    class demodb_code {
        public $s_name = null;
        public $f_name = null;

        public function toString() {
            var_dump($this);
        }
    }

    var_dump(cubrid_fetch_object($res, "demodb_code"));

    // se for desejado operar em objeto LOB, pode-se usar cubrid_fetch_object($res, "demodb_code", CUBRID_LOB)

    class demodb_code_construct extends demodb_code {
        public function __construct($s, $f) {
            $this->s_name = $s;
            $this->f_name = $f;
        }
    }

    var_dump(cubrid_fetch_object($res, 'demodb_code_construct', array('s_name', 'f_name')));

    // se for desejado operar em objeto LOB, pode-se usar cubrid_fetch_object($res, 'demodb_code_construct', array('s_name', 'f_name'), CUBRID_LOB)

    var_dump(cubrid_fetch_object($res));

    cubrid_close_request($res);
    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    object(stdClass)#1 (2) {
      ["s_name"]=>
      string(1) "X"
      ["f_name"]=>
      string(5) "Mixed"
    }
    object(demodb_code)#1 (2) {
      ["s_name"]=>
      string(1) "W"
      ["f_name"]=>
      string(5) "Woman"
    }
    object(demodb_code_construct)#1 (2) {
      ["s_name"]=>
      string(6) "s_name"
      ["f_name"]=>
      string(6) "f_name"
    }
    object(stdClass)#1 (2) {
      ["s_name"]=>
      string(1) "B"
      ["f_name"]=>
      string(6) "Bronze"
    }

### Veja Também

- cubrid_execute() - Executa uma instrução preparada SQL
- cubrid_fetch() - Busca a próxima linha do conjunto de resultados
- cubrid_fetch_array() - Busca uma linha de resultado como um array associativo, numérico ou ambos
- cubrid_fetch_assoc() - Retorna o array associativo que corresponde à linha buscada
- cubrid_fetch_row() - Retorna um array numérico com os valores da linha atual

# cubrid_fetch_row

(PECL CUBRID >= 8.3.0)

cubrid_fetch_row — Retorna um array numérico com os valores da linha atual

### Descrição

function cubrid_fetch_row(resource `$result`, int `$type` = ?): array

Esta função retorna um array numérico com os valores da linha atual do conjunto de resultados, começando em 0, e move o ponteiro de dados interno para frente.

### Parâmetros

`result`
  `result` vem de uma chamada a cubrid_execute()
`type`
  O tipo só pode ser CUBRID_LOB, este parâmetro será usado somente quando for necessário operar no objeto LOB.

### Valor Retornado

Um array numérico em caso de sucesso.

`false`, quando não houver mais linhas; NULL em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_fetch_row()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT name,area,seats,address FROM stadium WHERE nation_code='GRE' AND seats > 10000");

    printf("%-40s %-10s %-9s %-20s\n", "Nome", "Área", "Assentos", "Endereço");
    while ($row = cubrid_fetch_row($req)) {
        printf("%-40s %-10s %-9s %-20s\n", $row[0], $row[1], $row[2], $row[3]);
    }

    // se for desejado operar em objeto LOB, pode-se usar cubrid_fetch_row($req, CUBRID_LOB)

    cubrid_close_request($req);

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    Nome                                     Área       Assentos  Endereço
    Panathinaiko Stadium                     86300.00   50000     Athens, Greece
    Olympic Stadium                          54700.00   13000     Athens, Greece
    Olympic Indoor Hall                      34100.00   18800     Athens, Greece
    Olympic Hall                             52400.00   21000     Athens, Greece
    Olympic Aquatic Centre                   42500.00   11500     Athens, Greece
    Markopoulo Olympic Equestrian Centre     64000.00   15000     Markopoulo, Athens, Greece
    Faliro Coastal Zone Olympic Complex      34650.00   12171     Faliro, Athens, Greece
    Athens Olympic Stadium                   120400.00  71030     Maroussi, Athens, Greece
    Ano Liossia                              34000.00   12000     Ano Liosia, Athens, Greece

### Veja Também

- cubrid_execute() - Executa uma instrução preparada SQL
- cubrid_fetch() - Busca a próxima linha do conjunto de resultados
- cubrid_fetch_array() - Busca uma linha de resultado como um array associativo, numérico ou ambos
- cubrid_fetch_assoc() - Retorna o array associativo que corresponde à linha buscada
- cubrid_fetch_object() - Busca a próxima linha e retorna-a como um objeto

# cubrid_field_flags

(PECL CUBRID >= 8.3.0)

cubrid_field_flags — Retorna uma string com as opções do campo informado pela posição

### Descrição

function cubrid_field_flags(resource `$result`, int `$field_offset`): string

Esta função retorna uma string com as opções do campo informado por sua posição, separados por espaço. Pode-se dividir o valor retornado usando explode(). As opções podem ser: `not_null`, `primary_key`, `unique_key`, `foreign_key`, `auto_increment`, `shared`, `reverse_index`, `reverse_unique` e `timestamp`.

### Parâmetros

`result`
  `result` vem de uma chamada a cubrid_execute()
`field_offset`
  A posição numérica do campo. O `field_offset` começa em 0. Se `field_offset` não existir, um erro de nível `E_WARNING` será emitido.

### Valor Retornado

Uma string com opções em caso de sucesso.

`false` caso o valor de field_offset seja inválido.

-1 se a instrução SQL não for SELECT.

### Exemplos

Exemplo #1 Exemplo de cubrid_field_flags()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $col_num = cubrid_num_cols($result);

    printf("%-30s %s\n", "Nome do Campos", "Opções do Campo");
    for($i = 0; $i < $col_num; $i++) {
        printf("%-30s %s\n", cubrid_field_name($result, $i), cubrid_field_flags($result, $i));
    }

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    Nome do Campos                 Opções do Campo
    host_year                      not_null primary_key unique_key
    event_code                     not_null primary_key unique_key foreign_key
    athlete_code                   not_null primary_key unique_key foreign_key
    stadium_code                   not_null
    nation_code
    medal
    game_date

# cubrid_field_len

(PECL CUBRID >= 8.3.0)

cubrid_field_len — Obtém o comprimento máximo do campo especificado

### Descrição

function cubrid_field_len(resource `$result`, int `$field_offset`): int

Esta função retorna o comprimento máximo do campo especificado em caso de sucesso ou retorna FALSE em caso de falha.

### Parâmetros

`result`
  `result` vem de uma chamada a cubrid_execute()
`field_offset`
  A posição numérica do campo. O `field_offset` começa em 0. Se `field_offset` não existir, um erro de nível `E_WARNING` será emitido.

### Valor Retornado

O comprimento máximo em caso de sucesso.

`false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_field_len()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $column_names = cubrid_column_names($result);
    $column_types = cubrid_column_types($result);

    printf("%-30s %-30s %-15s\n", "Nomes das Colunas", "Tipos das Colunas", "Comprimento Máximo das Colunas");
    for($i = 0, $size = count($column_names); $i < $size; $i++) {
        $column_len = cubrid_field_len($result, $i);
        printf("%-30s %-30s %-15s\n", $column_names[$i], $column_types[$i], $column_len);
    }

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    Nomes das Colunas              Tipos das Colunas              Comprimento Máximo das Colunas
    host_year                      integer                        11
    event_code                     integer                        11
    athlete_code                   integer                        11
    stadium_code                   integer                        11
    nation_code                    char                           3
    medal                          char                           1
    game_date                      date                           10

# cubrid_field_name

(PECL CUBRID >= 8.3.0)

cubrid_field_name — Retorna o nome do índice do campo especificado

### Descrição

function cubrid_field_name(resource `$result`, int `$field_offset`): string

Esta função retorna o nome do índice do campo especificado em caso de sucesso ou retorna FALSE em caso de falha.

### Parâmetros

`result`
  `result` vem de uma chamada a cubrid_execute()
`field_offset`
  A posição numérica do campo. O `field_offset` começa em 0. Se `field_offset` não existir, um erro de nível `E_WARNING` será emitido.

### Valor Retornado

Nome do campo no índice especificado em caso de sucesso.

`false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_field_name()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $col_num = cubrid_num_cols($result);

    printf("%-30s %s\n", "Nome do Campo", "Opções do Campo");
    for($i = 0; $i < $col_num; $i++) {
        printf("%-30s %s\n", cubrid_field_name($result, $i), cubrid_field_flags($result, $i));
    }

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    Nome do Campo                  Opções do Campo
    host_year                      not_null primary_key unique_key
    event_code                     not_null primary_key unique_key foreign_key
    athlete_code                   not_null primary_key unique_key foreign_key
    stadium_code                   not_null
    nation_code
    medal
    game_date

# cubrid_field_seek

(PECL CUBRID >= 8.3.0)

cubrid_field_seek — Move o cursor do conjunto de resultados para a posição de campo especificada

### Descrição

function cubrid_field_seek(resource `$result`, int `$field_offset` = 0): bool

Esta função move o cursor do conjunto de resultados para o campo na posição especificada. Este deslocamento é usado pela função cubrid_fetch_field() se ela não incluir uma posição de campo. Retorna TRUE em caso de sucesso ou FALSE em caso de falha.

### Parâmetros

`result`
  `result` vem de uma chamada a cubrid_execute()
`field_offset`
  A posição numérica do campo. O `field_offset` começa em 0. Se `field_offset` não existir, um erro de nível `E_WARNING` será emitido.

### Valor Retornado

`true` em caso de sucesso.

`false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_field_seek()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT event_code,athlete_code,nation_code,game_date FROM game WHERE host_year=1988 and event_code=20001;");

    var_dump(cubrid_fetch_row($req));

    cubrid_field_seek($req, 1);
    $field = cubrid_fetch_field($req);

    printf("\n--- Propriedades do Campo ---\n");
    printf("%-30s %s\n", "nome:", $field->name);
    printf("%-30s %s\n", "tabela:", $field->table);
    printf("%-30s \"%s\"\n", "valor padrão:", $field->def);
    printf("%-30s %d\n", "comprimento máximo:", $field->max_length);
    printf("%-30s %d\n", "não nulo:", $field->not_null);
    printf("%-30s %d\n", "chave exclusiva:", $field->unique_key);
    printf("%-30s %d\n", "chave múltipla:", $field->multiple_key);
    printf("%-30s %d\n", "numérico:", $field->numeric);
    printf("%-30s %s\n", "tipo:", $field->type);

    cubrid_close_request($req);

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    array(4) {
      [0]=>
      string(5) "20001"
      [1]=>
      string(5) "16132"
      [2]=>
      string(3) "KOR"
      [3]=>
      string(9) "1988-09-30"
    }

    --- Propriedades do Campo ---
    nome:                          athlete_code
    tabela:                        game
    valor padrão:                  ""
    comprimento máximo:            0
    não nulo:                      1
    chave exclusiva:               1
    chave múltipla:                0
    numérico:                      1
    tipo:                          integer

# cubrid_field_table

(PECL CUBRID >= 8.3.0)

cubrid_field_table — Retorna o nome da tabela do campo especificado

### Descrição

function cubrid_field_table(resource `$result`, int `$field_offset`): string

Esta função retorna o nome da tabela do campo especificado. Isso é útil ao usar consultas de seleções grandes com JOINS.

### Parâmetros

`result`
  `result` vem de uma chamada a cubrid_execute()
`field_offset`
  A posição numérica do campo. O `field_offset` começa em 0. Se `field_offset` não existir, um erro de nível `E_WARNING` será emitido.

### Valor Retornado

Nome da tabela do campo especificado, em caso de sucesso.

`false` em caso de field_offset com valor inválido.

-1 se a instrução SQL não for SELECT.

### Exemplos

Exemplo #1 Exemplo de cubrid_field_table()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM code");

    $col_num = cubrid_num_cols($result);

    printf("%-16s %-15s %s\n", "Tabela do Campo", "Nome do Campo", "Tipo do Campo");
    for($i = 0; $i < $col_num; $i++) {
        printf("%-16s %-15s %s\n",
            cubrid_field_table($result, $i), cubrid_field_name($result, $i), cubrid_field_type($result, $i));
    }

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    Tabela do Campo  Nome do Campo   Tipo do Campo
    code             s_name          char
    code             f_name          varchar

# cubrid_field_type

(PECL CUBRID >= 8.3.0)

cubrid_field_type — Retorna o tipo da coluna correspondente ao campo da posição informada

### Descrição

function cubrid_field_type(resource `$result`, int `$field_offset`): string

Esta função retorna o tipo da coluna correspondente ao campo da posição informada. O tipo de campo retornado pode ser um dos seguintes: "int", "real", "string", etc.

### Parâmetros

`result`
  `result` vem de uma chamada a cubrid_execute()
`field_offset`
  A posição numérica do campo. O `field_offset` começa em 0. Se `field_offset` não existir, um erro de nível `E_WARNING` será emitido.

### Valor Retornado

Tipo da coluna em caso de sucesso.

`false` quando o valor de field_offset for inválido.

-1 se a instrução SQL não for SELECT.

### Exemplos

Exemplo #1 Exemplo de cubrid_field_type()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM code");

    $col_num = cubrid_num_cols($result);

    printf("%-16s %-15s %s\n", "Tabela do Campo", "Nome do Campo", "Tipo do Campo");
    for($i = 0; $i < $col_num; $i++) {
        printf("%-16s %-15s %s\n",
            cubrid_field_table($result, $i), cubrid_field_name($result, $i), cubrid_field_type($result, $i));
    }

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    Tabela do Campo  Nome do Campo   Tipo do Campo
    code             s_name          char
    code             f_name          varchar

# cubrid_list_dbs

(PECL CUBRID >= 8.3.0)

cubrid_list_dbs — Retorna um array com a lista de todos os bancos de dados CUBRID existentes

### Descrição

function cubrid_list_dbs(resource `$conn_identifier` = ?): array

Esta função retorna um array com a lista de todos os bancos de dados CUBRID existentes.

### Parâmetros

`conn_identifier`
  A conexão CUBRID.

### Valor Retornado

Um array numérico com todos os bancos de dados CUBRID existentes em caso de sucesso.

`false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_list_dbs()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $db_list = cubrid_list_dbs($conn);
    var_dump($db_list);

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    array(1) {
      [0]=>
      string(6) "demodb"
    }

# cubrid_num_fields

(PECL CUBRID >= 8.3.0)

cubrid_num_fields — Retorna o número de colunas no conjunto de resultados

### Descrição

function cubrid_num_fields(resource `$result`): int

Esta função retorna o número de colunas no conjunto de resultados em caso de sucesso ou FALSE em caso de falha.

### Parâmetros

`result`
  `result` vem de uma chamada a cubrid_execute(), cubrid_query() e cubrid_prepare()

### Valor Retornado

Número de colunas em caso de sucesso.

-1 se a instrução SQL não for SELECT.

`false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_num_fields()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $req = cubrid_execute($conn, "SELECT * FROM code");

    $row_num = cubrid_num_rows($req);
    $col_num = cubrid_num_fields($req);

    printf("Número de linhas: %d\nNúmero de colunas: %d\n", $row_num, $col_num);

    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    Número de linhas: 6
    Número de colunas: 2

# cubrid_ping

(PECL CUBRID >= 8.3.1)

cubrid_ping — Verifica atividade em uma conexão ao servidor ou reconecta se não houver conexão

### Descrição

function cubrid_ping(resource `$conn_identifier` = ?): bool

Verifica se a conexão ao servidor está ativa ou não.

### Parâmetros

`conn_identifier`
  O identificador de conexão CUBRID. Se o identificador da conexão não for especificado, será assumida a última conexão aberta por cubrid_connect().

### Valor Retornado

Retorna `true` se a conexão ao servidor CUBRID estiver ativa, caso contrário retorna `false`.

### Exemplos

Exemplo #1 Exemplo de cubrid_ping()

    <?php
    set_time_limit(0);

    $conn = cubrid_connect('localhost', 33000, 'demodb');

    /* Assumindo que esta consulta irá levar muito tempo */
    $sql = "select * from athlete";
    $result = cubrid_query($sql);
    if (!$result) {
        echo 'Consulta #1 falhou, saindo.';
        exit;
    }

    /* Certificando que a conexão ainda está ativa, caso contrário, tenta reconectar */
    if (!cubrid_ping($conn)) {
        echo 'Conexão perdida, saindo após consulta #1';
        exit;
    }
    cubrid_free_result($result);

    /* Então a conexão ainda está ativa, executando mais uma consulta */
    $sql2 = "select * from code";
    $result2 = cubrid_query($sql2);
    ?>

# cubrid_query

(PECL CUBRID >= 8.3.1)

cubrid_query — Envia uma consulta CUBRID

### Descrição

function cubrid_query(string `$query`, resource `$conn_identifier` = ?): resource

cubrid_query() envia uma consulta única (consultas múltiplas não são suportadas) para o banco de dados atualmente ativo no servidor que está associado ao `conn_identifier` especificado.

### Parâmetros

`query`
  Uma consulta SQL Dados na consulta devem estar adequadamente escapados.
`conn_identifier`
  A conexão CUBRID. Se o identificador de conexão não for especificado, a última conexão aberta por cubrid_connect() será usada.

### Valor Retornado

Para SELECT, SHOW, DESCRIBE, EXPLAIN e outras instruções que retornam um conjunto de resultados, cubrid_query() retorna um resource em caso de sucesso ou `false` em caso de erro.

Para outros tipos de instruções SQL como INSERT, UPDATE, DELETE, DROP, etc., cubrid_query() retorna `true` em caso de sucesso ou `false` em caso de erro.

O recurso de resultado retornado deve ser passado para cubrid_fetch_array() e outras funções para lidar com tabelas de resultados, para acessar os dados retornados.

Use cubrid_num_rows() para descobrir quantas linhas foram retornadas para uma instrução SELECT ou cubrid_affected_rows() para descobrir quantas linhas foram afetadas por uma instrução DELETE, INSERT, REPLACE ou UPDATE.

cubrid_query() também falhará e retornará `false` se o usuário não tiver permissão para acessar as tabelas referenciadas pela consulta.

### Exemplos

Exemplo #1 Consulta Inválida

A consulta a seguir é sintaticamente inválida, portanto cubrid_query() falhará e retornará `false`.

    <?php
    $conn = cubrid_connect('localhost', 33000, 'demodb');

    $result = cubrid_query('SELECT * WHERE 1=1');
    if (!$result) {
        die('Consulta inválida: ' . cubrid_error());
    }

    ?>

Exemplo #2 Consulta Válida

A consulta a seguir é válida, portanto cubrid_query() retornará um resource.

    <?php
    // Isso pode ser fornecido por um usuário, por exemplo
    $firstname = 'fred';
    $lastname  = 'fox';

    $conn = cubrid_connect('localhost', 33000, 'demodb');

    cubrid_execute($conn,"DROP TABLE if exists friends");
    cubrid_execute($conn,"create table friends(firstname varchar,lastname varchar,address char(24),age int)");
    cubrid_execute($conn,"insert into friends values('fred','fox','home-1','20')");
    cubrid_execute($conn,"insert into friends values('blue','cat','home-2','21')");
    // Formula a consulta
    // Esta é a melhor maneira de realizar uma consulta SQL
    // Para mais exemplos, consulte cubrid_real_escape_string()
    $query = sprintf("SELECT firstname, lastname, address, age FROM friends WHERE firstname='%s' AND lastname='%s'",
    cubrid_real_escape_string($firstname),
    cubrid_real_escape_string($lastname));

    // Executa a consulta
    $result = cubrid_query($query);

    // Verifica o resultado
    // Isso mostra a consulta real enviada ao CUBRID e o erro. Útil para depuração.
    if (!$result) {
        $message  = 'Consulta inválida: ' . cubrid_error() . "\n";
        $message .= 'Consulta completa: ' . $query;
        die($message);
    }

    // Usa o resultado
    // A tentativa de mostrar $result diretamente não permitirá acesso às informações do recurso
    // Uma das funções de resultado cubrid deve ser usada
    // Consulte também cubrid_result(), cubrid_fetch_array(), cubrid_fetch_row(), etc.
    while ($row = cubrid_fetch_assoc($result)) {
        echo $row['firstname'];
        echo $row['lastname'];
        echo $row['address'];
        echo $row['age'];
    }

    // Libera os recursos associados ao conjunto de resultados
    // Isso é feito automaticamente no final do script
    cubrid_free_result($result);
    ?>

### Veja Também

- cubrid_connect() - Abre uma conexão a um servidor CUBRID
- cubrid_error() - Obtém a mensagem de erro
- cubrid_real_escape_string() - Escapa caracteres especiais em uma string para uso em uma instrução SQL
- cubrid_result() - Retorna o valor de um campo específico em uma linha específica
- cubrid_fetch_assoc() - Retorna o array associativo que corresponde à linha buscada
- cubrid_unbuffered_query() - Execute uma consulta sem buscar os resultados para a memória

# cubrid_real_escape_string

(PECL CUBRID >= 8.3.0)

cubrid_real_escape_string — Escapa caracteres especiais em uma string para uso em uma instrução SQL

### Descrição

function cubrid_real_escape_string(string `$unescaped_string`, resource `$conn_identifier` = ?): string

Esta função retorna a versão escapada da string fornecida. Irá escapar os seguintes caracteres: `'`. Em geral, aspas simples são usadas para delimitar sequências de caracteres. Aspas duplas também podem ser usadas dependendo do valor de ansi_quotes, que é um parâmetro relacionado à instrução SQL. Se o valor ansi_quotes for definido como "no", a string entre aspas duplas será tratada como string de caracteres, não como um identificador. O valor padrão é "yes". Se a intenção for incluir aspas simples como parte de uma string de caracteres, insira duas aspas simples seguidas.

### Parâmetros

`unescaped_string`
  A string a ser escapada.
`conn_identifier`
  A conexão CUBRID connection. Se o identificador de conexão não for especificado, a última conexão aberta por cubrid_connect() será usada.

### Valor Retornado

Versão escapada da string fornecida em caso de sucesso.

`false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_real_escape_string()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $unescaped_str = ' !"#$%&\'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~';
    $escaped_str = cubrid_real_escape_string($unescaped_str);

    $len = strlen($unescaped_str);

    @cubrid_execute($conn, "DROP TABLE cubrid_test");
    cubrid_execute($conn, "CREATE TABLE cubrid_test (t char($len))");
    cubrid_execute($conn, "INSERT INTO cubrid_test (t) VALUES('$escaped_str')");

    $req = cubrid_execute($conn, "SELECT * FROM cubrid_test");
    $row = cubrid_fetch_assoc($req);

    var_dump($row);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    array(1) {
      ["t"]=>
      string(95) " !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~"
    }

# cubrid_result

(PECL CUBRID >= 8.3.0)

cubrid_result — Retorna o valor de um campo específico em uma linha específica

### Descrição

function cubrid_result(resource `$result`, int `$row`, mixed `$field` = 0): string

Esta função retorna o valor de um campo específico em uma linha específica de um conjunto de resultados.

### Parâmetros

`result`
  `result` vem de uma chamada a cubrid_execute()
`row`
  O número da linha do resultado que está sendo recuperado. Os números das linhas começam em 0.
`field`
  `field` deve conter o nome ou posição do campo que está sendo recuperado. Pode ser a posição do campo, o nome do campo, ou a tabela do campo - ponto - nome do campo (nome_tabela.nome_campo). Se o nome da coluna tiver sido apelidada na instrução ('select foo as bar from...'), use o apelido no lugar do nome da coluna. Se não definido, o primeiro campo será recuperado.

### Valor Retornado

Valor de um campo específico, em caso de sucesso (NULL se o valor for nulo).

`false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_result()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $req = cubrid_execute($conn, "SELECT * FROM code");

    $result = cubrid_result($req, 0);
    var_dump($result);

    $result = cubrid_result($req, 0, 1);
    var_dump($result);

    $result = cubrid_result($req, 5, "f_name");
    var_dump($result);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

O exemplo acima produzirá:

    string(1) "X"
    string(5) "Mixed"
    string(4) "Gold"

# cubrid_unbuffered_query

(PECL CUBRID >= 8.3.0)

cubrid_unbuffered_query — Execute uma consulta sem buscar os resultados para a memória

### Descrição

function cubrid_unbuffered_query(string `$query`, resource `$conn_identifier` = ?): resource

Esta função executa uma consulta sem esperar que todos os resultados da consulta tenham sido concluídos. Ela retornará quando os resultados estiverem sendo gerados.

### Parâmetros

`query`
  Uma consulta SQL.
`conn_identifier`
  A conexão CUBRID connection. Se o identificador de conexão não for especificado, a última conexão aberta por cubrid_connect() será usada.

### Valor Retornado

Para instruções SELECT, SHOW, DESCRIBE ou EXPLAIN, retorna um recurso de identificador de requisição em caso de sucesso.

Para outros tipos de instrução SQL como UPDATE, DELETE, DROP, etc., retorna `true` em caso de sucesso.

`false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_unbuffered_query()

    <?php
        $link = cubrid_connect("localhost", 30000, "demodb", "dba", "");
        if (!$link)
        {
            die('Não foi possível conectar.');
        }
        $query = "select * from code";
        $result = cubrid_unbuffered_query($query, $link);

        while ($row = cubrid_fetch($result))
        {
            var_dump($row);
        }

        cubrid_close_request($result);
        cubrid_disconnect($link);
    ?>

### Notas

> Nota: Os benefícios de cubrid_unbuffered_query() vêm com um custo: cubrid_num_rows() e cubrid_data_seek() não podem ser usadas em um conjunto de resultados retornado por cubrid_unbuffered_query().

## Índice

- cubrid_affected_rows — Retorna o número de linhas afetadas pela última instrução SQL
- cubrid_client_encoding — Retorna o conjunto de caracteres de conexão CUBRID atual
- cubrid_close — Fecha conexão CUBRID
- cubrid_data_seek — Move o ponteiro de linha interno do resultado CUBRID
- cubrid_db_name — Obtém o nome do banco de dados dos resultados de cubrid_list_dbs
- cubrid_errno — Retorna o valor numérico da mensagem de erro da operação CUBRID anterior
- cubrid_error — Obtém a mensagem de erro
- cubrid_fetch_array — Busca uma linha de resultado como um array associativo, numérico ou ambos
- cubrid_fetch_assoc — Retorna o array associativo que corresponde à linha buscada
- cubrid_fetch_field — Obtém informações da coluna de um resultado e retorna como um objeto
- cubrid_fetch_lengths — Retorna um array com os comprimentos dos valores de cada campo da linha atual
- cubrid_fetch_object — Busca a próxima linha e retorna-a como um objeto
- cubrid_fetch_row — Retorna um array numérico com os valores da linha atual
- cubrid_field_flags — Retorna uma string com as opções do campo informado pela posição
- cubrid_field_len — Obtém o comprimento máximo do campo especificado
- cubrid_field_name — Retorna o nome do índice do campo especificado
- cubrid_field_seek — Move o cursor do conjunto de resultados para a posição de campo especificada
- cubrid_field_table — Retorna o nome da tabela do campo especificado
- cubrid_field_type — Retorna o tipo da coluna correspondente ao campo da posição informada
- cubrid_list_dbs — Retorna um array com a lista de todos os bancos de dados CUBRID existentes
- cubrid_num_fields — Retorna o número de colunas no conjunto de resultados
- cubrid_ping — Verifica atividade em uma conexão ao servidor ou reconecta se não houver conexão
- cubrid_query — Envia uma consulta CUBRID
- cubrid_real_escape_string — Escapa caracteres especiais em uma string para uso em uma instrução SQL
- cubrid_result — Retorna o valor de um campo específico em uma linha específica
- cubrid_unbuffered_query — Execute uma consulta sem buscar os resultados para a memória

# Funções e sinônimos obsoletos do CUBRID

# cubrid_load_from_glo

(PECL CUBRID >= 8.3.0)

cubrid_load_from_glo — Lê dados de uma instância GLO e grava-os em um arquivo

### Descrição

function cubrid_load_from_glo(resource `$conn_identifier`, string `$oid`, string `$file_name`): int

A função cubrid_load_from_glo() é usada para ler dados de uma instância GLO e gravá-los em um arquivo designado.

### Parâmetros

`conn_identifier`
  Identificador da conexão.
`oid`
  OID da instância GLO de onde os dados serão lidos.
`file_name`
  Nome do arquivo onde os dados serão gravados.

### Valor Retornado

`true` em caso de sucesso.

`false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_load_from_glo()

    <?php
    $req = cubrid_execute($con, "select image from person where id=1");
    if ($req) {
        list($oid) = cubrid_fetch($req);
        cubrid_close_request($req);
        $res = cubrid_load_from_glo($con, $oid, "output.jpg");
        if ($res) {
            echo "imagem alterada com sucesso";
        }
    }
    ?>

### Notas

> Nota: Para compatibilidade com versões anteriores, o seguinte apelido descontinuado pode ser usado: cubrid_load_from_glo()

> Nota: Esta função foi removida no CUBRID 3.1.

### Veja Também

- cubrid_new_glo() - Cria uma instância GLO
- cubrid_save_to_glo() - Grava o arquivo solicitado em uma instância GLO
- cubrid_send_glo() - Lê dados de uma instância GLO e envia-os à saída padrão

# cubrid_new_glo

(PECL CUBRID >= 8.3.0)

cubrid_new_glo — Cria uma instância GLO

### Descrição

function cubrid_new_glo(resource `$conn_identifier`, string `$class_name`, string `$file_name`): string

A função cubrid_new_glo() é usada para criar uma instância GLO na classe solicitada (classe GLO). A instância criada é do tipo LO e é gravada no arquivo informado em `file_name`.

### Parâmetros

`conn_identifier`
  Identificador da conexão.
`class_name`
  Nome da classe onde a instância GLO será criada.
`file_name`
  Nome do arquivo que onde será gravada a nova instância de GLO.

### Valor Retornado

OID da instância criada em caso de sucesso.

`false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_new_glo()

    <?php
    $oid = cubrid_new_glo($con, "glo", "input.jpg");
    if ($oid){
        // o tipo da coluna "image" é "object"
        $req = cubrid_execute($con, "insert into person(image) values($oid)");
        if ($req) {
            echo "imagem inserida com sucesso";
            cubrid_close_request($req);
            cubrid_commit($con);
        }
    }
    ?>

### Notas

> Nota: Para compatibilidade com versões anteriores, o seguinte apelido descontinuado pode ser usado: cubrid_new_glo()

> Nota: Esta função foi removida no CUBRID 3.1.

### Veja Também

- cubrid_save_to_glo() - Grava o arquivo solicitado em uma instância GLO
- cubrid_load_from_glo() - Lê dados de uma instância GLO e grava-os em um arquivo
- cubrid_send_glo() - Lê dados de uma instância GLO e envia-os à saída padrão

# cubrid_save_to_glo

(PECL CUBRID >= 8.3.0)

cubrid_save_to_glo — Grava o arquivo solicitado em uma instância GLO

### Descrição

function cubrid_save_to_glo(resource `$conn_identifier`, string `$oid`, string `$file_name`): int

A função cubrid_save_to_glo() é usada para salvar o arquivo solicitado em uma instância GLO.

### Parâmetros

`conn_identifier`
  Identificador da conexão.
`oid`
  OID da instância GLO de onde o arquivo será gravado.
`file_name`
  O nome do arquivo a ser gravado.

### Valor Retornado

`true` em caso de sucesso.

`false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_save_to_glo()

    <?php
    $req = cubrid_execute($con, "select image from person where id=1");
    if ($req) {
        list($oid) = cubrid_fetch($req);
        cubrid_close_request($req);
        $res = cubrid_save_to_glo($con, $oid, "input.jpg");
        if ($res) {
            echo "imagem alterada com sucesso";
        }
    }
    ?>

### Notas

> Nota: Para compatibilidade com versões anteriores, o seguinte apelido descontinuado pode ser usado: cubrid_save_to_glo()

> Nota: Esta função foi removida no CUBRID 3.1.

### Veja Também

- cubrid_new_glo() - Cria uma instância GLO
- cubrid_load_from_glo() - Lê dados de uma instância GLO e grava-os em um arquivo
- cubrid_send_glo() - Lê dados de uma instância GLO e envia-os à saída padrão

# cubrid_send_glo

(PECL CUBRID >= 8.3.0)

cubrid_send_glo — Lê dados de uma instância GLO e envia-os à saída padrão

### Descrição

function cubrid_send_glo(resource `$conn_identifier`, string `$oid`): int

A função cubrid_send_glo() é usada para ler dados de uma instância GLO e enviá-los à saída padrão do PHP.

### Parâmetros

`conn_identifier`
  Identificador da conexão.
`oid`
  OID da instância GLO de onde os dados serão lidos.

### Valor Retornado

`true` em caso de sucesso.

`false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de cubrid_send_glo()

    <?php
    $req = cubrid_execute($con, "select image from person where id =1");
    if ($req) {
        list ($oid) = cubrid_fetch($req);
        cubrid_close_request($req);
        header("Content-type: image/jpeg");
        cubrid_send_glo($con, $oid);
    }
    ?>

### Notas

> Nota: Para compatibilidade com versões anteriores, o seguinte apelido descontinuado pode ser usado: cubrid_send_glo()

> Nota: Esta função foi removida no CUBRID 3.1.

### Veja Também

- cubrid_new_glo() - Cria uma instância GLO
- cubrid_save_to_glo() - Grava o arquivo solicitado em uma instância GLO
- cubrid_load_from_glo() - Lê dados de uma instância GLO e grava-os em um arquivo

## Índice

- cubrid_load_from_glo — Lê dados de uma instância GLO e grava-os em um arquivo
- cubrid_new_glo — Cria uma instância GLO
- cubrid_save_to_glo — Grava o arquivo solicitado em uma instância GLO
- cubrid_send_glo — Lê dados de uma instância GLO e envia-os à saída padrão

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
  - Tipos de Recurso
- Constantes predefinidas
- Exemplos
- Funções de CUBRID
  - cubrid_bind — Vincula variáveis a instruções preparadas como parâmetros
  - cubrid_close_prepare — Fecha o identificador de requisição
  - cubrid_close_request — Fecha o identificador de requisição
  - cubrid_col_get — Obtém conteúdo de coluna tipo coleção usando OID
  - cubrid_col_size — Obtém o número de elementos de coluna tipo coleção usando OID
  - cubrid_column_names — Obtém nomes de colunas no resultado
  - cubrid_column_types — Obtém tipos de colunas no resultado
  - cubrid_commit — Confirma uma transação
  - cubrid_connect — Abre uma conexão a um servidor CUBRID
  - cubrid_connect_with_url — Prepara o ambiente para conexão ao servidor CUBRID
  - cubrid_current_oid — Obtém o OID da posição atual do cursor
  - cubrid_disconnect — Fecha uma conexão ao banco de dados
  - cubrid_drop — Remove uma instância usando OID
  - cubrid_error_code — Obtém código de erro para a chamada de função mais recente
  - cubrid_error_code_facility — Obtém o código do módulo do erro
  - cubrid_error_msg — Obtém mensagem de erro da chamada de função mais recente
  - cubrid_execute — Executa uma instrução preparada SQL
  - cubrid_fetch — Busca a próxima linha do conjunto de resultados
  - cubrid_free_result — Libera a memória ocupada pelos dados do resultado
  - cubrid_get — Obtém um atributo usando OID
  - cubrid_get_autocommit — Obtém o modo de auto-confirmação da conexão
  - cubrid_get_charset — Retorna o conjunto de caracteres da conexão CUBRID atual
  - cubrid_get_class_name — Obtém o nome da classe usando OID
  - cubrid_get_client_info — Retorna a versão da biblioteca cliente
  - cubrid_get_db_parameter — Retorna os parâmetros do banco de dados CUBRID
  - cubrid_get_query_timeout — Obtém o tempo limite de consulta para a requisição
  - cubrid_get_server_info — Retorna a versão do servidor CUBRID
  - cubrid_insert_id — Retorna o ID gerado pela última coluna AUTO_INCREMENT atualizada
  - cubrid_is_instance — Verifica se a instância apontada pelo OID existe
  - cubrid_lob_close — Fecha os dados BLOB/CLOB
  - cubrid_lob_export — Exporta dados BLOB/CLOB para um arquivo
  - cubrid_lob_get — Obtém dados BLOB/CLOB
  - cubrid_lob_send — Lê dados BLOB/CLOB e envia direto ao navegador
  - cubrid_lob_size — Obtém o tamanho dos dados BLOB/CLOB
  - cubrid_lob2_bind — Vincula um objeto LOB ou uma string como objeto LOB a uma instrução preparada como parâmetros
  - cubrid_lob2_close — Fecha objeto LOB
  - cubrid_lob2_export — Exporta o objeto LOB para um arquivo
  - cubrid_lob2_import — Importa dados BLOB/CLOB de um arquivo
  - cubrid_lob2_new — Cria um objeto LOB
  - cubrid_lob2_read — Lê bytes de dados BLOB/CLOB
  - cubrid_lob2_seek — Move o cursor de um objeto LOB
  - cubrid_lob2_seek64 — Move o cursor de um objeto LOB
  - cubrid_lob2_size — Obtém o tamanho do objeto LOB
  - cubrid_lob2_size64 — Obtém o tamanho do objeto LOB
  - cubrid_lob2_tell — Informa a posição do cursor do objeto LOB
  - cubrid_lob2_tell64 — Informa a posição do cursor do objeto LOB
  - cubrid_lob2_write — Escreve em um objeto LOB
  - cubrid_lock_read — Define uma trava de leitura em um OID informado
  - cubrid_lock_write — Define uma trava de escrita em um OID informado
  - cubrid_move_cursor — Move o cursor no resultado
  - cubrid_next_result — Obtém o resultado da próxima consulta quando múltiplas instruções SQL estão sendo executadas
  - cubrid_num_cols — Retorna o número de colunas no resultado
  - cubrid_num_rows — Obtém o número de linhas no resultado
  - cubrid_pconnect — Abre uma conexão persistente a um servidor CUBRID
  - cubrid_pconnect_with_url — Abre uma conexão persistente com o servidor CUBRID
  - cubrid_prepare — Prepara uma instrução SQL para execução
  - cubrid_put — Atualiza uma coluna usando OID
  - cubrid_rollback — Reverte uma transação
  - cubrid_schema — Obtém informação do esquema solicitado
  - cubrid_seq_drop — Remove um elemento de coluna tipo sequência usando OID
  - cubrid_seq_insert — Insere um elemento em uma coluna tipo sequência usando OID
  - cubrid_seq_put — Atualiza o valor do elemento de coluna tipo sequência usando OID
  - cubrid_set_add — Insere um único elemento a uma coluna tipo conjunto usando OID
  - cubrid_set_autocommit — Define o modo de auto-confirmação da conexão
  - cubrid_set_db_parameter — Define os parâmetros do banco de dados CUBRID
  - cubrid_set_drop — Remove um elemento da coluna tipo conjunto usando OID
  - cubrid_set_query_timeout — Define o tempo limite de execução de consulta
  - cubrid_version — Obtém a versão do módulo do CUBRID PHP
- Funções de compatibilidade CUBRID MySQL
  - cubrid_affected_rows — Retorna o número de linhas afetadas pela última instrução SQL
  - cubrid_client_encoding — Retorna o conjunto de caracteres de conexão CUBRID atual
  - cubrid_close — Fecha conexão CUBRID
  - cubrid_data_seek — Move o ponteiro de linha interno do resultado CUBRID
  - cubrid_db_name — Obtém o nome do banco de dados dos resultados de cubrid_list_dbs
  - cubrid_errno — Retorna o valor numérico da mensagem de erro da operação CUBRID anterior
  - cubrid_error — Obtém a mensagem de erro
  - cubrid_fetch_array — Busca uma linha de resultado como um array associativo, numérico ou ambos
  - cubrid_fetch_assoc — Retorna o array associativo que corresponde à linha buscada
  - cubrid_fetch_field — Obtém informações da coluna de um resultado e retorna como um objeto
  - cubrid_fetch_lengths — Retorna um array com os comprimentos dos valores de cada campo da linha atual
  - cubrid_fetch_object — Busca a próxima linha e retorna-a como um objeto
  - cubrid_fetch_row — Retorna um array numérico com os valores da linha atual
  - cubrid_field_flags — Retorna uma string com as opções do campo informado pela posição
  - cubrid_field_len — Obtém o comprimento máximo do campo especificado
  - cubrid_field_name — Retorna o nome do índice do campo especificado
  - cubrid_field_seek — Move o cursor do conjunto de resultados para a posição de campo especificada
  - cubrid_field_table — Retorna o nome da tabela do campo especificado
  - cubrid_field_type — Retorna o tipo da coluna correspondente ao campo da posição informada
  - cubrid_list_dbs — Retorna um array com a lista de todos os bancos de dados CUBRID existentes
  - cubrid_num_fields — Retorna o número de colunas no conjunto de resultados
  - cubrid_ping — Verifica atividade em uma conexão ao servidor ou reconecta se não houver conexão
  - cubrid_query — Envia uma consulta CUBRID
  - cubrid_real_escape_string — Escapa caracteres especiais em uma string para uso em uma instrução SQL
  - cubrid_result — Retorna o valor de um campo específico em uma linha específica
  - cubrid_unbuffered_query — Execute uma consulta sem buscar os resultados para a memória
- Funções e sinônimos obsoletos do CUBRID
  - cubrid_load_from_glo — Lê dados de uma instância GLO e grava-os em um arquivo
  - cubrid_new_glo — Cria uma instância GLO
  - cubrid_save_to_glo — Grava o arquivo solicitado em uma instância GLO
  - cubrid_send_glo — Lê dados de uma instância GLO e envia-os à saída padrão

# dBase

# Introdução

> Nota:

> Esta extensão foi movida para o repositório » PECL e não é mais distribuída com o PHP desde a versão 5.3.0.

Essas funções permitem acessar registros armazenados em bancos de dados no formato dBase (dbf).

Aviso

Não é recomendado usar arquivos dBase como banco de dados de produção. Use o » SQLite ou escolha qualquer servidor SQL real; » MySQL ou » Postgres são escolhas comuns com o PHP. O suporte ao dBase está aqui para permitir importação e exportação de dados de e para seu banco de dados da web, porque o formato de arquivo é comumente entendido por planilhas e organizadores do Windows.

Cuidado

A partir do dBase 7.0.0, os bancos de dados são bloqueados automaticamente via flock(). Não havia suporte para bloqueio anteriormente, portanto, dois processos simultâneos de servidor web modificando o mesmo arquivo dBase provavelmente teriam arruinado um banco de dados. Isso pode acontecer mesmo com o dBase 7.0.0+ em sistemas que implementam os bloqueios no nível do processo com SAPIs multithread.

Os arquivos dBase são arquivos sequenciais simples de registros de comprimento fixo. Os registros são anexados ao final do arquivo e os registros excluídos são mantidos até a chamada a dbase_pack().

Somente arquivos dbf de nível 3 (dBASE III+) a 5 (dBASE V) são suportados. Os tipos de campos dBase disponíveis são:

Tipos de campos disponíveis
Campo | Tipo dBase | Formato | Informações adicionais
--- | --- | --- | ---
`M` | Memo | n/a | Este tipo não é suportado pelo PHP, tal campo será ignorado
`D` | Date | `YYYYMMDD` | O comprimento do campo é limitado a 8
`T` | DateTime | `YYYYMMDDhhmmss.uuu` | (FoxPro) Nenhuma verificação de validade é feita. Disponível a partir do dBase 7.0.0.
`N` | Number | Um número | Deve-se declarar um comprimento e uma precisão (o número de dígitos após o separador de decimais).
`F` | Float | Um número float | Igual a `N`.
`C` | String | Uma string | Deve-se declarar um comprimento. Ao recuperar dados, a string será preenchida à direita com espaços para caber no comprimento declarado. Strings muito longas serão truncadas silenciosamente ao armazenar dados.
`L` | Boolean | `T` ou `Y` para `true`, `F` ou `N` para `false`, `?` para não inicializado. | A partir do dBase 7.0.0, retornado como um bool (`true` ou `false`), ou `null` para campos não inicializados. Anteriormente, retornado como int (`1` ou `0`).

> Nota:

> A partir do dBase 7.0.0, campos anuláveis são suportados para bancos de dados `DBASE_TYPE_FOXPRO`. Se um campo for anulável, passar `null` definirá o respectivo sinalizador e, na recuperação posterior, o valor do campo será `null`.

> Nota:

> Não há suporte para índices ou campos memo.

# Instalação/Configuração

## Índice

- Instalação
- Tipos de Recurso

## Instalação

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/dbase.

## Tipos de Recurso

A partir do dbase 7.0.0, o tipo de recurso `dbase` é definido e é retornado pelas funções dbase_open() e dbase_create().

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`DBASE_VERSION` (string)
  A versão da extensão. (Disponível a partir do dbase 7.0.0)
`DBASE_RDONLY` (int)
  Abre o banco de dados somente para leitura. Usada com dbase_open(). (Disponível a partir do dbase 7.0.0)
`DBASE_RDWR` (int)
  Abre o banco de dados para leitura e escrita. Usada com dbase_open(). (Disponível a partir do dbase 7.0.0)
`DBASE_TYPE_DBASE` (int)
  Cria o banco de dados no estilo dBASE. Usada com dbase_create(). (Disponível a partir do dbase 7.0.0)
`DBASE_TYPE_FOXPRO` (int)
  Cria o banco de dados no estilo FoxPro. Usada com dbase_create(). (Disponível a partir do dbase 7.0.0)

# Funções da dBase

## Exemplos

Muitos exemplos nesta referência requerem um banco de dados dBase. Nós iremos usar /tmp/test.dbf que irá ser criado no exemplo da dbase_create().

# dbase_add_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_add_record — Adiciona um registro a um banco de dados

### Descrição

function dbase_add_record(resource `$database`, array `$data`): bool

Adiciona os dados fornecidos ao banco de dados.

### Parâmetros

`database`

  O recurso de banco de dados, retornado por dbase_open() ou dbase_create().

`data`

  Um array indexado de dados. O número de itens deve ser igual ao número de campos no banco de dados, caso contrário dbase_add_record() irá falhar.

  > Nota:

  > Se o valor de retorno de dbase_get_record() estiver sendo usado para este parâmetro, deve-se redefinir a chave de nome `deleted`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL dbase 7.0.0 | `database` agora é do tipo resource ao invés do tipo int.

### Exemplos

Exemplo #1 Inserindo um registro num banco de dados dBase

    <?php

    // abre em modo leitura/escrita
    $db = dbase_open('/tmp/test.dbf', 2);

    if ($db) {
      dbase_add_record($db, array(
          date('Ymd'),
          'Maxim Topolov',
          '23',
          'max@example.com',
          'T'));
      dbase_close($db);
    }

    ?>

### Veja Também

- dbase_delete_record() - Exclui um registro do banco de dados
- dbase_replace_record() - Substitui um registro em um banco de dados

# dbase_close

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_close — Fecha um banco de dados

### Descrição

function dbase_close(resource `$database`): bool

Fecha o recurso de banco de dados indicado.

### Parâmetros

`database`

  O recurso de banco de dados, retornado por dbase_open() ou dbase_create().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL dbase 7.0.0 | `database` agora é do tipo resource ao invés do tipo int.

### Exemplos

Exemplo #1 Fechando um banco de dados dBase

    <?php

    // abre em modo leitura/escrita
    $db = dbase_open('/tmp/test.dbf', 0);

    if ($db) {
      // lê alguns dados ..

      dbase_close($db);
    }

    ?>

### Veja Também

- dbase_open() - Abre um banco de dados
- dbase_create() - Cria um banco de dados

# dbase_create

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_create — Cria um banco de dados

### Descrição

function dbase_create(string `$path`, array `$fields`, int `$type` = DBASE_TYPE_DBASE): resource

dbase_create() cria um banco de dados com a definição informada. Se o arquivo já existir, ele não será truncado. dbase_pack() pode ser chamado para forçar o truncamento.

> Nota: Esta função é afetada por open_basedir.

### Parâmetros

`path`

  O caminho do banco de dados. Pode ser um caminho relativo ou absoluto para o arquivo onde o dBase irá armazenar os dados.

`fields`

  Um array de arrays, cada array descrevendo o formato de um campo no banco de dados. Cada campo consiste de um nome, um caractere indicando o tipo do campo, e opcionalmente, um tamanho, uma precisão e uma opção anulável. Os tipos de campos suportados estão listados na seção de introdução

  > Nota:

  > O nome dos campos são limitados em tamanho e não podem exceder 10 caracteres.

`type`

  O tipo de banco de dados a ser criado. Pode ser `DBASE_TYPE_DBASE` ou `DBASE_TYPE_FOXPRO`.

### Valor Retornado

Retorna um recurso de banco de dados se for criado com sucesso, ou `false` se houver um erro.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL dbase 7.0.0 | O parâmetro `type` foi adicionado.
PECL dbase 7.0.0 | O valor de retorno agora é do tipo resource ao invés de um int.

### Exemplos

Exemplo #1 Criando um arquivo de banco de dados dBase

    <?php

    // database "definition"
    $def = array(
      array("date",     "D"),
      array("name",     "C",  50),
      array("age",      "N",   3, 0),
      array("email",    "C", 128),
      array("ismember", "L")
    );

    // criação
    if (!dbase_create('/tmp/test.dbf', $def)) {
      echo "Erro, não foi possível criar o banco de dados\n";
    }

    ?>

### Veja Também

- dbase_open() - Abre um banco de dados
- dbase_close() - Fecha um banco de dados

# dbase_delete_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_delete_record — Exclui um registro do banco de dados

### Descrição

function dbase_delete_record(resource `$database`, int `$number`): bool

Marca o registro indicado para ser excluído do banco de dados.

> Nota:

> Para realmente remover o registro do banco de dados, deve-se também utilizar dbase_pack().

### Parâmetros

`database`

  Recurso do banco de dados, retornado por dbase_open() ou dbase_create().

`number`

  Um inteiro que vai de 1 até o número de registros no banco de dados (como retornado por dbase_numrecords()).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL dbase 7.0.0 | `database` agora é do tipo resource ao invés de int.

### Veja Também

- dbase_add_record() - Adiciona um registro a um banco de dados
- dbase_replace_record() - Substitui um registro em um banco de dados

# dbase_get_header_info

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_get_header_info — Obtém as informações do cabeçalho do banco de dados

### Descrição

function dbase_get_header_info(resource `$database`): array

Retorna informações sobre a estrutura de colunas do recurso de banco de dados indicado.

### Parâmetros

`database`

  O recurso do banco de dados, retornado por dbase_open() ou dbase_create().

### Valor Retornado

Um array indexado com uma entrada para cada coluna no banco de dados. O índice começa em 0.

Cada elemento do array contém um array associativo com informações da coluna, como descrito aqui:

name
  O nome da coluna
type
  O nome legível do tipo de coluna dbase (ex.: date, boolean, etc.) Os tipos de campos suportados estão listados na seção de introdução.
length
  O número de bytes que esta coluna pode guardar
precision
  O número de dígitos da precisão decimal da coluna
format
  Um especificador de formato printf() sugerido para a coluna
offset
  O índice em byte da coluna a partir do início da linha

Se as informações do cabeçalho do banco de dados não puderem ser lidas, é retornado `false`.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL dbase 7.0.0 | `database` agora é do tipo resource ao invés de int.

### Exemplos

Exemplo #1 Mostrando informações do banco de dados de um arquivo dBase

    <?php
    // caminho para o arquivo dbase
    $db_path = "/tmp/test.dbf";

    // Abre o arquivo dbase
    $dbh = dbase_open($db_path, 0)
      or die("Erro! Não foi possível abrir o arquivo de banco de dados dbase '$db_path'.");

    // Obtém informação de coluna
    $column_info = dbase_get_header_info($dbh);

    // Mostra a informação
    print_r($column_info);
    ?>

# dbase_get_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_get_record — Obtém um registro do banco de dados como um array indexado

### Descrição

function dbase_get_record(resource `$database`, int `$number`): array

Obtém um registro do banco de dados como um array indexado.

### Parâmetros

`database`

  O recurso do banco de dados, retornado por dbase_open() ou dbase_create().

`number`

  O índice do registro entre `1` e `dbase_numrecords($dbase_identifier)`.

### Valor Retornado

Um array indexado com o registro. Este array também irá incluir uma chave chamada `deleted` a qual é definida como 1 se o registro foi marcado para exclusão (veja dbase_delete_record()).

Cada campo é convertido para o tipo PHP apropriado, exceto:

- Datas são mantidas como strings.
- Valores DateTime são convertidos em strings.
- Números inteiros fora do intervalo `PHP_INT_MIN`..`PHP_INT_MAX` são retornados como strings.
- Antes do dbase 7.0.0, os booleanos (`L`) eram convertidos em `1` ou `0`.

Em caso de erro, dbase_get_record() irá retornar `false`.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL dbase 7.0.0 | `database` agora é do tipo resource ao invés de int.

### Veja Também

- dbase_get_record_with_names() - Obtém um registro do banco de dados como um array associativo.

# dbase_get_record_with_names

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_get_record_with_names — Obtém um registro do banco de dados como um array associativo.

### Descrição

function dbase_get_record_with_names(resource `$database`, int `$number`): array

Obtém um registro do banco de dados como um array associativo.

### Parâmetros

`database`

  Recurso de banco de dados, retornado por dbase_open() ou dbase_create().

`number`

  O índice do registro entre `1` e `dbase_numrecords($dbase_identifier)`.

### Valor Retornado

Um array associativo com o registro. Isto também irá incluir uma chave chamada `deleted` a qual é definida como 1 se o registro foi marcado para exclusão (veja dbase_delete_record()). Portanto, não é possível obter o valor de um campo com nome `deleted` com esta função.

Cada campo é convertido para o tipo PHP apropriado, exceto:

- Datas são mantidas como strings.
- Valores DateTime são convertidos em strings.
- Números inteiros fora do intervalo `PHP_INT_MIN`..`PHP_INT_MAX` são retornados como strings.
- Antes do dbase 7.0.0, os booleanos (`L`) eram convertidos em `1` ou `0`.

Em caso de erro, dbase_get_record_with_names() irá retornar `false`.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL dbase 7.0.0 | `database` agora é do tipo resource ao invés de int.

### Exemplos

Exemplo #1 Listando todos os membros registrados no banco de dados

    <?php
    // open in read-only mode
    $db = dbase_open('/tmp/test.dbf', 0);

    if ($db) {
      $record_numbers = dbase_numrecords($db);
      for ($i = 1; $i <= $record_numbers; $i++) {
          $row = dbase_get_record_with_names($db, $i);
          if ($row['ismember'] == 1) {
              echo "Member #$i: " . trim($row['name']) . "\n";
          }
      }
    }
    ?>

### Veja Também

- dbase_get_record() - Obtém um registro do banco de dados como um array indexado

# dbase_numfields

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_numfields — Obtém o número de campos em um banco de dados

### Descrição

function dbase_numfields(resource `$database`): int

Obtém o número de campos(colunas) no banco de dados especificados.

> Nota:

> Números de campo estão entre 0 e `dbase_numfields($db)-1`, enquanto que números de registro estão entre 1 e `dbase_numrecords($db)`.

### Parâmetros

`database`

  O recurso de banco de dados, retornado por dbase_open() ou dbase_create().

### Valor Retornado

O números de campos em um banco de dados, ou `false` se acontecer um erro.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL dbase 7.0.0 | `database` agora é do tipo resource ao invés de int.

### Exemplos

Exemplo #1 Exemplo dbase_numfields()

    <?php

    $rec = dbase_get_record($db, $recno);
    $nf  = dbase_numfields($db);
    for ($i = 0; $i < $nf; $i++) {
      echo $rec[$i], "\n";
    }

    ?>

### Veja Também

- dbase_numrecords() - Obtém o número de registros em um banco de dados

# dbase_numrecords

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_numrecords — Obtém o número de registros em um banco de dados

### Descrição

function dbase_numrecords(resource `$database`): int

Obtém o número de registros (linhas) no banco de dados especificado.

> Nota:

> Resgistros marcados para remoção também são contados.

> Nota:

> Número de registros estão entre 1 e `dbase_numrecords($db)`, enquanto que números de campo estão entre 0 e `dbase_numfields($db)-1`.

### Parâmetros

`database`

  O recurso de banco de dados, retornado por dbase_open() ou dbase_create().

### Valor Retornado

O número de registros no banco de dados, ou `false` se ocorrer um erro.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL dbase 7.0.0 | `database` agora é do tipo resource ao invés de int.

### Exemplos

Exemplo #1 Lendo todos os registros de um banco de dados

    <?php

    // abre somente leitura
    $db = dbase_open('/tmp/test.dbf', 0);

    if ($db) {
      $record_numbers = dbase_numrecords($db);
      for ($i = 1; $i <= $record_numbers; $i++) {
          $record = dbase_get_record($db, $i);
          if (!$record['deleted']) {
              // faz algo com o registro
          } else {
              // faz algo com o registro deletado ou ignora
          }
      }
    }

    ?>

### Veja Também

- dbase_numfields() - Obtém o número de campos em um banco de dados

# dbase_open

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_open — Abre um banco de dados

### Descrição

function dbase_open(string `$path`, int `$mode`): resource|false

dbase_open() abre um banco de dados dBase com o modo de acesso informado.

> Nota: Esta função é afetada por open_basedir.

### Parâmetros

`path`

  O caminho do banco de dados. Pode ser um caminho relativo ou absoluto para o arquivo onde o dBase irá armazenar os dados.

`mode`

  Um inteiro que corresponda à chamada de sistema open() (tipicamente 0 significa somente-leitura, 1 apenas para escrita e 2 significa leitura e escrita).

  > Nota:

  > Não é possível abrir um banco de dados dBase em modo somente para escrita já que a função irá falhar ao ler os cabeçalhos com informações e por isso não se pode usar 1 como o parâmetro `mode`.

  A partir do dbase 7.0.0 pode-se usar `DBASE_RDONLY` e `DBASE_RDWR`, respectivamente, para especificar o parâmetro `mode`.

### Valor Retornado

Retorna um recurso de banco de dados em caso de sucesso, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL dbase 7.0.0 | O valor de retorno agora é do tipo resource ao invés de int.

### Exemplos

Exemplo #1 Abrindo um banco de dados dBase

    <?php

    // abre em modo somente leitura
    $db = dbase_open('/tmp/test.dbf', 0);

    if ($db) {
      // lê alguns dados ..

      dbase_close($db);
    }

    ?>

### Veja Também

- dbase_create() - Cria um banco de dados
- dbase_close() - Fecha um banco de dados

# dbase_pack

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_pack — Comprime um banco de dados

### Descrição

function dbase_pack(resource `$database`): bool

Comprime o banco de dados especificado, apagando permanentemente todos os registros marcados para remoção usando dbase_delete_record(). Note que o arquivo será truncado após empacotamento bem sucedido (ao contrário do comando PACK do dBASE III).

### Parâmetros

`database`

  O recurso de banco de dados, retornado por dbase_open() ou dbase_create().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL dbase 7.0.0 | `database` é agora do tipo resource ao invés de int.

### Exemplos

Exemplo #1 Limpando um banco de dados dBase

    <?php

    // abre somente-leitura
    $db = dbase_open('/tmp/test.dbf', 2);

    if ($db) {
      $record_numbers = dbase_numrecords($db);
      for ($i = 1; $i <= $record_numbers; $i++) {
          dbase_delete_record($db, $i);
      }
      // expurga os dados marcados para remoção
      dbase_pack($db);
    }

    ?>

### Veja Também

- dbase_delete_record() - Exclui um registro do banco de dados

# dbase_replace_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_replace_record — Substitui um registro em um banco de dados

### Descrição

function dbase_replace_record(resource `$database`, array `$data`, int `$number`): bool

Substitui o registro no banco de dados com os dados indicados.

### Parâmetros

`database`

  O recurso de banco de dados, retornado por dbase_open() ou dbase_create().

`data`

  Um array indexado de dados. O número deve ser igual ao número de campos no banco de dados, caso contrário dbase_replace_record() irá falhar.

  > Nota:

  > Se o valor de retorno de dbase_get_record() for usado para este parâmetro, lembre-se de redefinir a chave de nome `deleted`.

`number`

  Um inteiro que vai de 1 até o número de registros no banco de dados (como retornado por dbase_numrecords()).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL dbase 7.0.0 | `database` agora é do tipo resource ao invés de int.

### Exemplos

Exemplo #1 Atualizando um registro no banco de dados

    <?php

    // abre somente leitura
    $db = dbase_open('/tmp/test.dbf', 2);

    if ($db) {
      // obtém o registro antigo
      $row = dbase_get_record_with_names($db, 1);

      // remove a entrada 'deletada'
      unset($row['deleted']);

      // Atualiza o campo 'date' com a dada atual
      $row['date'] = date('Ymd');

      // converte o registro para um array indexado
      $row = array_values($row);

      // Substitui o registro
      dbase_replace_record($db, $row, 1);
      dbase_close($db);
    }

    ?>

### Notas

> Nota:

> Campos booleanos resultam em um elemento do tipo int (`0` ou `1`) quando obtidos através de dbase_get_record() ou dbase_get_record_with_names(). Se fores escritos de volta, resulta no valor tornando-se `0`, portanto deve-se ter cuidado para ajustar os valores adequadamente.

### Veja Também

- dbase_add_record() - Adiciona um registro a um banco de dados
- dbase_delete_record() - Exclui um registro do banco de dados

## Índice

- dbase_add_record — Adiciona um registro a um banco de dados
- dbase_close — Fecha um banco de dados
- dbase_create — Cria um banco de dados
- dbase_delete_record — Exclui um registro do banco de dados
- dbase_get_header_info — Obtém as informações do cabeçalho do banco de dados
- dbase_get_record — Obtém um registro do banco de dados como um array indexado
- dbase_get_record_with_names — Obtém um registro do banco de dados como um array associativo.
- dbase_numfields — Obtém o número de campos em um banco de dados
- dbase_numrecords — Obtém o número de registros em um banco de dados
- dbase_open — Abre um banco de dados
- dbase_pack — Comprime um banco de dados
- dbase_replace_record — Substitui um registro em um banco de dados

- Instalação/Configuração
  - Instalação
  - Tipos de Recurso
- Constantes predefinidas
- Funções da dBase
  - dbase_add_record — Adiciona um registro a um banco de dados
  - dbase_close — Fecha um banco de dados
  - dbase_create — Cria um banco de dados
  - dbase_delete_record — Exclui um registro do banco de dados
  - dbase_get_header_info — Obtém as informações do cabeçalho do banco de dados
  - dbase_get_record — Obtém um registro do banco de dados como um array indexado
  - dbase_get_record_with_names — Obtém um registro do banco de dados como um array associativo.
  - dbase_numfields — Obtém o número de campos em um banco de dados
  - dbase_numrecords — Obtém o número de registros em um banco de dados
  - dbase_open — Abre um banco de dados
  - dbase_pack — Comprime um banco de dados
  - dbase_replace_record — Substitui um registro em um banco de dados

# Firebird/InterBase

# Introdução

Aviso

Esta extensão é considerada sem manutenção e abandonada. No entanto, o código-fonte desta extensão ainda está disponível no GIT do PECL aqui: » https://github.com/php/pecl-database-interbase.

Firebird é um banco de dados relacional que oferece muitos recursos ISO SQL-2003 que é executado em Linux, Windows, e uma variedade de plataformas Unix. Firebird oferece excelente concorrência, alto desempenho, e um poderoso suporte de linguagem para procedimentos armazenados e gatilhos. Ele vem sendo usada em sistemas de produção sob uma variedades de nomes desde 1981.

InterBase é o nome da variante de código fechado deste RDBMS que foi desenvolvido pela Embarcadero/Inprise. Mais informação sobre InterBase está disponível em » http://www.embarcadero.com/products/interbase.

Firebird é um projeto (fundação) comercialmente independente de programadores C++, conselheiros técnicos e apoiadores desenvolvendo e melhorando um sistema de gerenciamento de banco de dados relacional multi-plataforma baseado no código fonte liberado pela Inprise Corp (agora conhecida como Embarcadero) sob a Licença Pública InterBase v.1.0 em 25 Julho, 2000. Mais informação sobre Firebird está disponível em » http://www.firebirdsql.org/.

> Nota: Esta extensão foi movida para o repositório » PECL e não é mais distribuída com o PHP desde a versão 7.4.0 Esta extensão suporta InterBase versões 6 e superiores e Firebird versão 2.0 e superiores.

# Instalação/Configuração

## Índice

- Instalação
- Configurações em Execução

## Instalação

Esta extensão foi movida para o repositório » PECL e não é mais distribuída com o PHP desde a versão 7.4.0

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://github.com/FirebirdSQL/php-firebird.

Para ativar o suporte Firebird/InterBase, configure o PHP com --with-interbase[=DIR], onde DIR é o diretório base da instalação do Firebird/InterBase, cujo padrão é /usr.

> Nota: Nota para os usuários de Win32/Win64
> Para que esta extensão funcione, existem arquivos DLL que devem estar disponíveis no PATH do sistema Windows. Para saber como fazer isso, veja a FAQ intitulada "Como eu adiciono o meu diretório PHP ao PATH do Windows". Embora copiar arquivos DLL da pasta do PHP para o diretório system do Windows também funcione (porque o diretório system está, por padrão, no PATH do sistema), isso não é recomendado. Esta extensão requer que os seguintes arquivos estejam no PATH: fbclient.dll,gds32.dll

> Caso o servidor do banco de dados Firebird/InterBase esteja na mesma máquina onde o PHP esta sendo executado, esta DLL já estará disponível e fbclient.dll,gds32.dll (gds32.dll é gerada pelo instalador para aplicações legado) estarão na variável PATH.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de configuração InterBase
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
ibase.allow_persistent | "1" | `INI_SYSTEM` |
ibase.max_persistent | "-1" | `INI_SYSTEM` |
ibase.max_links | "-1" | `INI_SYSTEM` |
ibase.default_db | NULL | `INI_SYSTEM` |
ibase.default_user | NULL | `INI_ALL` |
ibase.default_password | NULL | `INI_ALL` |
ibase.default_charset | NULL | `INI_ALL` |
ibase.timestampformat | "%Y-%m-%d %H:%M:%S" | `INI_ALL` |
ibase.dateformat | "%Y-%m-%d" | `INI_ALL` |
ibase.timeformat | "%H:%M:%S" | `INI_ALL` |

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`ibase.allow_persistent` bool
  Define se as conexões persistentes serão permitidas para Firebird/InterBase.
`ibase.max_persistent` int
  O número máximo de conexões persistentes Firebird/InterBase por processo. Novas conexões criadas com ibase_pconnect() serão não-persistentes se este número for excedido.
`ibase.max_links` int
  O número máximo de conexões Firebird/InterBase por, incluindo conexões persistentes.
`ibase.default_db` string
  O banco padrão a se conectar quando ibase_[p]connect() for chamada sem especificar um nome de banco. Se este valor estiver definido e o modo seguro do SQL estiver habilitado, nenhuma outra conexão além desta a este banco será permitida.
`ibase.default_user` string
  O nome de usuário a ser usado ao conectar ao banco se nenhum nome for especificado.
`ibase.default_password` string
  A senha a ser usada ao conectar ao banco se nenhuma for especificada.
`ibase.default_charset` string
  O conjunto de caratcteres a ser usado na conexão ao banco se nenhum for especificado.
`ibase.timestampformat` string
`ibase.dateformat` string
`ibase.timeformat` string
  Estas diretivas são usadas para definir os formatos de data e horário no retorno de conjunto de resultados, ou ao vincular argumentos a parâmetros de data e horário.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

As seguinte constantes podem ser passadas para ibase_trans() para especificar o funcionamento da transação.

Opções da transação Firebird/InterBase
Constante | Descrição
--- | ---
IBASE_DEFAULT | Serão usadas as definições padrão para a transação. Este padrão é determinado pela biblioteca do cliente, a qual define-o como IBASE_WRITE|IBASE_CONCURRENCY|IBASE_WAIT na maioria dos casos.
IBASE_READ | Começa uma transação apenas para leitura.
IBASE_WRITE | Começa uma transação de leitura e escrita.
IBASE_CONSISTENCY | Começa uma transação com o nível de isolação definido como 'consistency', o qual indica que a transação não pode ler de tabelas que estão sendo modificadas por outras transações concorrentes.
IBASE_CONCURRENCY | Começa uma transação com o nível de isolação definido como 'concurrency' (ou 'snapshot'), o qual indica que a transação tem acesso a todas as tabelas, mas não pode ver as modificações que foram gravadas por outras transações após a transação ter começado.
IBASE_COMMITTED | Começa uma transação com o nível de isolação definido como 'read committed'. Esta opção deve ser combinada com `IBASE_REC_VERSION` ou `IBASE_REC_NO_VERSION`. Este nível de isolação permite acesso para as modifcações salvas após o início da transação. Se `IBASE_REC_NO_VERSION` for especificada, apenas a última versão de uma linha pode ser lida. Se `IBASE_REC_VERSION` for especificada, uma linha pode ser lida mesmo quando exista uma modificação pendente em uma transação concorrente.
IBASE_WAIT | Indica que uma transação deve esperar e tentar novamente quando acontecer um conflito.
IBASE_NOWAIT | Indica que a transação deve falhar imediatamente quando acontecer um conflito.

As seguintes constantes podem ser passadas para ibase_fetch_row(), ibase_fetch_assoc() ou ibase_fetch_object() para especificar o comportamento da recepção de dados.

Opções para obter do Firebird/InterBase
Constante | Descrição
--- | ---
IBASE_FETCH_BLOBS | Também disponível como `IBASE_TEXT` para compatibilidade com versões anteriores. Faz com que o conteúdo de campos BLOB serão recebidos em linha, ao invés de serem retornados como identificadores BLOB.
IBASE_FETCH_ARRAYS | Faz com que os arrays sejam retornados diretamente. Caso contrário, são retornados identificadores de array. Identificadores de array somente podem ser usados como argumentos para operações INSERT, já que não estão disponíveis atualmente funções para manipular identificadores de array.
IBASE_UNIXTIME | Faz com que campos de data e horário não sejam retornados como strings, mas como timestamps Unix (o número de segundos desde a Época Unix, que é 1-Jan-1970 0:00 UTC). Pode ser problemático se usado com datas antes de 1970 em alguns sistemas.

As seguintes constantes são usadas para passar requisições e opções para as funções da API de serviços (ibase_server_info(), ibase_db_info(), ibase_backup(), ibase_restore() e ibase_maintain_db()). Por favor veja o manual do Firebird/InterBase para o significado destas opções.

`IBASE_BKP_IGNORE_CHECKSUMS`
  Opções para ibase_backup()
`IBASE_BKP_IGNORE_LIMBO`
  Opções para ibase_backup()
`IBASE_BKP_METADATA_ONLY`
  Opções para ibase_backup()
`IBASE_BKP_NO_GARBAGE_COLLECT`
  Opções para ibase_backup()
`IBASE_BKP_OLD_DESCRIPTIONS`
  Opções para ibase_backup()
`IBASE_BKP_NON_TRANSPORTABLE`
  Opções para ibase_backup()
`IBASE_BKP_CONVERT`
  Opções para ibase_backup()
`IBASE_RES_DEACTIVATE_IDX`
  Opções para ibase_restore()
`IBASE_RES_NO_SHADOW`
  Opções para ibase_restore()
`IBASE_RES_NO_VALIDITY`
  Opções para ibase_restore()
`IBASE_RES_ONE_AT_A_TIME`
  Opções para ibase_restore()
`IBASE_RES_REPLACE`
`IBASE_RES_CREATE`
  Opções para ibase_restore()
`IBASE_RES_USE_ALL_SPACE`
  Opções para ibase_restore()
`IBASE_PRP_PAGE_BUFFERS`
`IBASE_PRP_SWEEP_INTERVAL`
`IBASE_PRP_SHUTDOWN_DB`
`IBASE_PRP_DENY_NEW_TRANSACTIONS`
`IBASE_PRP_DENY_NEW_ATTACHMENTS`
`IBASE_PRP_RESERVE_SPACE`
`IBASE_PRP_RES_USE_FULL`
`IBASE_PRP_RES`
`IBASE_PRP_WRITE_MODE`
`IBASE_PRP_WM_ASYNC`
`IBASE_PRP_WM_SYNC`
`IBASE_PRP_ACCESS_MODE`
`IBASE_PRP_AM_READONLY`
`IBASE_PRP_AM_READWRITE`
`IBASE_PRP_SET_SQL_DIALECT`
`IBASE_PRP_ACTIVATE`
`IBASE_PRP_DB_ONLINE`
`IBASE_RPR_CHECK_DB`
`IBASE_RPR_IGNORE_CHECKSUM`
`IBASE_RPR_KILL_SHADOWS`
`IBASE_RPR_MEND_DB`
`IBASE_RPR_VALIDATE_DB`
`IBASE_RPR_FULL`
`IBASE_RPR_SWEEP_DB`
  Opções para ibase_maintain_db()
`IBASE_STS_DATA_PAGES`
`IBASE_STS_DB_LOG`
`IBASE_STS_HDR_PAGES`
`IBASE_STS_IDX_PAGES`
`IBASE_STS_SYS_RELATIONS`
  Opções para ibase_db_info()
`IBASE_SVC_SERVER_VERSION`
  Opções para ibase_server_info()
`IBASE_SVC_IMPLEMENTATION`
  Opções para ibase_server_info()
`IBASE_SVC_GET_ENV`
  Opções para ibase_server_info()
`IBASE_SVC_GET_ENV_LOCK`
`IBASE_SVC_GET_ENV_MSG`
`IBASE_SVC_USER_DBPATH`
`IBASE_SVC_SVR_DB_INFO`
`IBASE_SVC_GET_USERS`
  Opções para ibase_server_info()

# Funções para Firebird/InterBase

# fbird_add_user

(PHP 5, PHP 7 < 7.4.0)

fbird_add_user — Sinônimo de ibase_add_user()

### Descrição

Esta função é um apelido para: ibase_add_user().

### Veja Também

- fbird_modify_user() - Sinônimo de ibase_modify_user
- fbird_delete_user() - Sinônimo de ibase_delete_user

# fbird_affected_rows

(PHP 5, PHP 7 < 7.4.0)

fbird_affected_rows — Sinônimo de ibase_affected_rows()

### Descrição

Esta função é um apelido para: ibase_affected_rows().

### Veja Também

- fbird_query() - Sinônimo de ibase_query
- fbird_execute() - Sinônimo de ibase_execute

# fbird_backup

(PHP 5, PHP 7 < 7.4.0)

fbird_backup — Sinônimo de ibase_backup()

### Descrição

Esta função é um apelido para: ibase_backup().

# fbird_blob_add

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_add — Sinônimo de ibase_blob_add()

### Descrição

Esta função é um apelido para: ibase_blob_add().

### Veja Também

- fbird_blob_cancel() - Cancela a criação de blob
- fbird_blob_close() - Sinônimo de ibase_blob_close
- fbird_blob_create() - Sinônimo de ibase_blob_create
- fbird_blob_import() - Sinônimo de ibase_blob_import

# fbird_blob_cancel

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_cancel — Cancela a criação de blob

### Descrição

function fbird_blob_cancel(resource `$blob_handle`): bool

Esta função descartará um BLOB se ele ainda não foi fechado por fbird_blob_close().

### Parâmetros

`blob_handle`
  Um identificador de BLOB aberto com fbird_blob_create().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- fbird_blob_close() - Sinônimo de ibase_blob_close
- fbird_blob_create() - Sinônimo de ibase_blob_create
- fbird_blob_import() - Sinônimo de ibase_blob_import

# fbird_blob_close

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_close — Sinônimo de ibase_blob_close()

### Descrição

Esta função é um apelido para: ibase_blob_close().

### Veja Também

- fbird_blob_create() - Sinônimo de ibase_blob_create
- fbird_blob_cancel() - Cancela a criação de blob
- fbird_blob_open() - Sinônimo de ibase_blob_open
- fbird_blob_import() - Sinônimo de ibase_blob_import

# fbird_blob_create

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_create — Sinônimo de ibase_blob_create()

### Descrição

Esta função é um apelido para: ibase_blob_create().

### Veja Também

- fbird_blob_add() - Sinônimo de ibase_blob_add
- fbird_blob_cancel() - Cancela a criação de blob
- fbird_blob_close() - Sinônimo de ibase_blob_close
- fbird_blob_import() - Sinônimo de ibase_blob_import

# fbird_blob_echo

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_echo — Sinônimo de ibase_blob_echo()

### Descrição

Esta função é um apelido para: ibase_blob_echo().

### Veja Também

- fbird_blob_open() - Sinônimo de ibase_blob_open
- fbird_blob_close() - Sinônimo de ibase_blob_close
- fbird_blob_get() - Sinônimo de ibase_blob_get

# fbird_blob_get

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_get — Sinônimo de ibase_blob_get()

### Descrição

Esta função é um apelido para: ibase_blob_get().

### Veja Também

- fbird_blob_open() - Sinônimo de ibase_blob_open
- fbird_blob_close() - Sinônimo de ibase_blob_close
- fbird_blob_echo() - Sinônimo de ibase_blob_echo

# fbird_blob_import

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_import — Sinônimo de ibase_blob_import()

### Descrição

Esta função é um apelido para: ibase_blob_import().

### Veja Também

- fbird_blob_add() - Sinônimo de ibase_blob_add
- fbird_blob_cancel() - Cancela a criação de blob
- fbird_blob_close() - Sinônimo de ibase_blob_close
- fbird_blob_create() - Sinônimo de ibase_blob_create

# fbird_blob_info

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_info — Sinônimo de ibase_blob_info()

### Descrição

Esta função é um apelido para: ibase_blob_info().

# fbird_blob_open

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_open — Sinônimo de ibase_blob_open()

### Descrição

Esta função é um apelido para: ibase_blob_open().

### Veja Também

- fbird_blob_close() - Sinônimo de ibase_blob_close
- fbird_blob_echo() - Sinônimo de ibase_blob_echo
- fbird_blob_get() - Sinônimo de ibase_blob_get

# fbird_close

(PHP 5, PHP 7 < 7.4.0)

fbird_close — Sinônimo de ibase_close()

### Descrição

Esta função é um apelido para: ibase_close().

### Veja Também

- fbird_connect() - Sinônimo de ibase_connect
- fbird_pconnect() - Sinônimo de ibase_pconnect

# fbird_commit

(PHP 5, PHP 7 < 7.4.0)

fbird_commit — Sinônimo de ibase_commit()

### Descrição

Esta função é um apelido para: ibase_commit().

# fbird_commit_ret

(PHP 5, PHP 7 < 7.4.0)

fbird_commit_ret — Sinônimo de ibase_commit_ret()

### Descrição

Esta função é um apelido para: ibase_commit_ret().

# fbird_connect

(PHP 5, PHP 7 < 7.4.0)

fbird_connect — Sinônimo de ibase_connect()

### Descrição

Esta função é um apelido para: ibase_connect().

### Veja Também

- fbird_pconnect() - Sinônimo de ibase_pconnect
- fbird_close() - Sinônimo de ibase_close

# fbird_db_info

(PHP 5, PHP 7 < 7.4.0)

fbird_db_info — Sinônimo de ibase_db_info()

### Descrição

Esta função é um apelido para: ibase_db_info().

# fbird_delete_user

(PHP 5, PHP 7 < 7.4.0)

fbird_delete_user — Sinônimo de ibase_delete_user()

### Descrição

Esta função é um apelido para: ibase_delete_user().

### Veja Também

- fbird_add_user() - Sinônimo de ibase_add_user
- fbird_modify_user() - Sinônimo de ibase_modify_user

# fbird_drop_db

(PHP 5, PHP 7 < 7.4.0)

fbird_drop_db — Sinônimo de ibase_drop_db()

### Descrição

Esta função é um apelido para: ibase_drop_db().

### Veja Também

- fbird_connect() - Sinônimo de ibase_connect
- fbird_pconnect() - Sinônimo de ibase_pconnect

# fbird_errcode

(PHP 5, PHP 7 < 7.4.0)

fbird_errcode — Sinônimo de ibase_errcode()

### Descrição

Esta função é um apelido para: ibase_errcode().

### Veja Também

- fbird_errmsg() - Sinônimo de ibase_errmsg

# fbird_errmsg

(PHP 5, PHP 7 < 7.4.0)

fbird_errmsg — Sinônimo de ibase_errmsg()

### Descrição

Esta função é um apelido para: ibase_errmsg().

### Veja Também

- fbird_errcode() - Sinônimo de ibase_errcode

# fbird_execute

(PHP 5, PHP 7 < 7.4.0)

fbird_execute — Sinônimo de ibase_execute()

### Descrição

Esta função é um apelido para: ibase_execute().

### Veja Também

- fbird_query() - Sinônimo de ibase_query

# fbird_fetch_assoc

(PHP 5, PHP 7 < 7.4.0)

fbird_fetch_assoc — Sinônimo de ibase_fetch_assoc()

### Descrição

Esta função é um apelido para: ibase_fetch_assoc().

### Veja Também

- fbird_fetch_row() - Sinônimo de ibase_fetch_row
- fbird_fetch_object() - Sinônimo de ibase_fetch_object

# fbird_fetch_object

(PHP 5, PHP 7 < 7.4.0)

fbird_fetch_object — Sinônimo de ibase_fetch_object()

### Descrição

Esta função é um apelido para: ibase_fetch_object().

### Veja Também

- fbird_fetch_row() - Sinônimo de ibase_fetch_row
- fbird_fetch_assoc() - Sinônimo de ibase_fetch_assoc

# fbird_fetch_row

(PHP 5, PHP 7 < 7.4.0)

fbird_fetch_row — Sinônimo de ibase_fetch_row()

### Descrição

Esta função é um apelido para: ibase_fetch_row().

### Veja Também

- fbird_fetch_assoc() - Sinônimo de ibase_fetch_assoc
- fbird_fetch_object() - Sinônimo de ibase_fetch_object

# fbird_field_info

(PHP 5, PHP 7 < 7.4.0)

fbird_field_info — Sinônimo de ibase_field_info()

### Descrição

Esta função é um apelido para: ibase_field_info().

### Veja Também

- fbird_num_fields() - Sinônimo de ibase_num_fields

# fbird_free_event_handler

(PHP 5, PHP 7 < 7.4.0)

fbird_free_event_handler — Sinônimo de ibase_free_event_handler()

### Descrição

Esta função é um apelido para: ibase_free_event_handler().

### Veja Também

- fbird_set_event_handler() - Sinônimo de ibase_set_event_handler

# fbird_free_query

(PHP 5, PHP 7 < 7.4.0)

fbird_free_query — Sinônimo de ibase_free_query()

### Descrição

Esta função é um apelido para: ibase_free_query().

# fbird_free_result

(PHP 5, PHP 7 < 7.4.0)

fbird_free_result — Sinônimo de ibase_free_result()

### Descrição

Esta função é um apelido para: ibase_free_result().

# fbird_gen_id

(PHP 5, PHP 7 < 7.4.0)

fbird_gen_id — Sinônimo de ibase_gen_id()

### Descrição

Esta função é um apelido para: ibase_gen_id().

# fbird_maintain_db

(PHP 5, PHP 7 < 7.4.0)

fbird_maintain_db — Sinônimo de ibase_maintain_db()

### Descrição

Esta função é um apelido para: ibase_maintain_db().

# fbird_modify_user

(PHP 5, PHP 7 < 7.4.0)

fbird_modify_user — Sinônimo de ibase_modify_user()

### Descrição

Esta função é um apelido para: ibase_modify_user().

### Veja Também

- fbird_add_user() - Sinônimo de ibase_add_user
- fbird_delete_user() - Sinônimo de ibase_delete_user

# fbird_name_result

(PHP 5, PHP 7 < 7.4.0)

fbird_name_result — Sinônimo de ibase_name_result()

### Descrição

Esta função é um apelido para: ibase_name_result().

### Veja Também

- fbird_prepare() - Sinônimo de ibase_prepare
- fbird_execute() - Sinônimo de ibase_execute

# fbird_num_fields

(PHP 5, PHP 7 < 7.4.0)

fbird_num_fields — Sinônimo de ibase_num_fields()

### Descrição

Esta função é um apelido para: ibase_num_fields().

### Veja Também

- fbird_field_info() - Sinônimo de ibase_field_info

# fbird_num_params

(PHP 5, PHP 7 < 7.4.0)

fbird_num_params — Sinônimo de ibase_num_params()

### Descrição

Esta função é um apelido para: ibase_num_params().

### Veja Também

- fbird_prepare() - Sinônimo de ibase_prepare
- fbird_param_info() - Sinônimo de ibase_param_info

# fbird_param_info

(PHP 5, PHP 7 < 7.4.0)

fbird_param_info — Sinônimo de ibase_param_info()

### Descrição

Esta função é um apelido para: ibase_param_info().

### Veja Também

- fbird_field_info() - Sinônimo de ibase_field_info
- fbird_num_params() - Sinônimo de ibase_num_params

# fbird_pconnect

(PHP 5, PHP 7 < 7.4.0)

fbird_pconnect — Sinônimo de ibase_pconnect()

### Descrição

Esta função é um apelido para: ibase_pconnect().

### Veja Também

- fbird_close() - Sinônimo de ibase_close
- fbird_connect() - Sinônimo de ibase_connect

# fbird_prepare

(PHP 5, PHP 7 < 7.4.0)

fbird_prepare — Sinônimo de ibase_prepare()

### Descrição

Esta função é um apelido para: ibase_prepare().

# fbird_query

(PHP 5, PHP 7 < 7.4.0)

fbird_query — Sinônimo de ibase_query()

### Descrição

Esta função é um apelido para: ibase_query().

### Veja Também

- fbird_errmsg() - Sinônimo de ibase_errmsg
- fbird_fetch_row() - Sinônimo de ibase_fetch_row
- fbird_fetch_object() - Sinônimo de ibase_fetch_object
- fbird_free_result() - Sinônimo de ibase_free_result

# fbird_restore

(PHP 5, PHP 7 < 7.4.0)

fbird_restore — Sinônimo de ibase_restore()

### Descrição

Esta função é um apelido para: ibase_restore().

# fbird_rollback

(PHP 5, PHP 7 < 7.4.0)

fbird_rollback — Sinônimo de ibase_rollback()

### Descrição

Esta função é um apelido para: ibase_rollback().

# fbird_rollback_ret

(PHP 5, PHP 7 < 7.4.0)

fbird_rollback_ret — Sinônimo de ibase_rollback_ret()

### Descrição

Esta função é um apelido para: ibase_rollback_ret().

# fbird_server_info

(PHP 5, PHP 7 < 7.4.0)

fbird_server_info — Sinônimo de ibase_server_info()

### Descrição

Esta função é um apelido para: ibase_server_info().

# fbird_service_attach

(PHP 5, PHP 7 < 7.4.0)

fbird_service_attach — Sinônimo de ibase_service_attach()

### Descrição

Esta função é um apelido para: ibase_service_attach().

# fbird_service_detach

(PHP 5, PHP 7 < 7.4.0)

fbird_service_detach — Sinônimo de ibase_service_detach()

### Descrição

Esta função é um apelido para: ibase_service_detach().

# fbird_set_event_handler

(PHP 5, PHP 7 < 7.4.0)

fbird_set_event_handler — Sinônimo de ibase_set_event_handler()

### Descrição

Esta função é um apelido para: ibase_set_event_handler().

### Veja Também

- fbird_free_event_handler() - Sinônimo de ibase_free_event_handler
- fbird_wait_event() - Sinônimo de ibase_wait_event

# fbird_trans

(PHP 5, PHP 7 < 7.4.0)

fbird_trans — Sinônimo de ibase_trans()

### Descrição

Esta função é um apelido para: ibase_trans().

# fbird_wait_event

(PHP 5, PHP 7 < 7.4.0)

fbird_wait_event — Sinônimo de ibase_wait_event()

### Descrição

Esta função é um apelido para: ibase_wait_event().

### Veja Também

- fbird_set_event_handler() - Sinônimo de ibase_set_event_handler
- fbird_free_event_handler() - Sinônimo de ibase_free_event_handler

# ibase_add_user

(PHP 5, PHP 7 < 7.4.0)

ibase_add_user — Adiciona um usuário a um banco de dados seguro

### Descrição

function ibase_add_user(
resource `$service_handle`,
string `$user_name`,
string `$password`,
string `$first_name` = ?,
string `$middle_name` = ?,
string `$last_name` = ?
): bool

### Parâmetros

`service_handle`
  O manipulador no serviço do servidor de banco de dados.
`user_name`
  O login do novo usuário do banco de dados.
`password`
  A senha do novo usuário.
`first_name`
  O primeiro nome do novo usuário.
`middle_name`
  O nome do meio do novo usuário.
`last_name`
  O último nome do novo usuário.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ibase_modify_user() - Modifica um usuário para um banco de dados seguro
- ibase_delete_user() - Exclui um usuário de um banco de dados seguro

# ibase_affected_rows

(PHP 5, PHP 7 < 7.4.0)

ibase_affected_rows — Retorna o número de linhas que foram afetados pela consulta anterior

### Descrição

function ibase_affected_rows(resource `$link_identifier` = ?): int

Esta função retorna o número de registros que foram afetados pela consulta anterior (INSERT, UPDATE ou DELETE) que foi executada de dentro do contexto da transação especificada.

### Parâmetros

`link_identifier`
  Um contexto de transação. Se `link_identifier` é um resource de conexão, a transação padrão é usada.

### Valor Retornado

Retorna o número de linhas como um inteiro.

### Veja Também

- ibase_query() - Executa uma consulta em um banco de dados InterBase
- ibase_execute() - Executa uma consulta preparada anteriormente

# ibase_backup

(PHP 5, PHP 7 < 7.4.0)

ibase_backup — Inicia uma tarefa de backup no gerenciador de serviços e retorna imediatamente

### Descrição

function ibase_backup(
resource `$service_handle`,
string `$source_db`,
string `$dest_file`,
int `$options` = 0,
bool `$verbose` = `false`
): mixed

Esta função passa os argumentos para o servidor de banco de dados (remoto). Lá, ele inicia um novo processo de backup. Portanto, nenhuma resposta será obtida.

### Parâmetros

`service_handle`
  Uma conexão aberta anteriormente com o servidor de banco de dados.
`source_db`
  O caminho absoluto do arquivo para o banco de dados no servidor de banco de dados. Pode-se também usar um apelido de banco de dados.
`dest_file`
  O caminho para o arquivo de backup no servidor de banco de dados.
`options`

  Opções adicionais para passar ao servidor de banco de dados para backup. O parâmetro `options` pode ser uma combinação das seguintes constantes: `IBASE_BKP_IGNORE_CHECKSUMS`, `IBASE_BKP_IGNORE_LIMBO`, `IBASE_BKP_METADATA_ONLY`, `IBASE_BKP_NO_GARBAGE_COLLECT`, `IBASE_BKP_OLD_DESCRIPTIONS`, `IBASE_BKP_NON_TRANSPORTABLE` ou `IBASE_BKP_CONVERT`. Leia a seção sobre Constantes predefinidas para mais informações.

`verbose`
  Como o processo de backup é feito no servidor de banco de dados, a saída não poderá ser obtida. Este argumento é inútil.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

Como o processo de backup é feito no servidor (remoto), esta função apenas passa os argumentos para ele. Embora os argumentos sejam legais, não será obtido `false`.

### Exemplos

Exemplo #1 Exemplo de ibase_backup()

    <?php

    // Conecta-se ao servidor de banco de dados por endereço IP e porta
    $service = ibase_service_attach ('10.1.11.200/3050', 'sysdba', 'masterkey');

    // Inicia o processo de backup no servidor de banco de dados
    // Faz backup do banco de dados de funcionários usando o caminho completo para /srv/backup/employees.fbk
    // Não usa nenhum argumento especial
    ibase_backup($service, '/srv/firebird/employees.fdb', '/srv/backup/employees.fbk');

    // Libera a conexão
    ibase_service_detach ($service);
    ?>

Exemplo #2 Exemplo de ibase_backup() com argumentos

    <?php

    // Conecta-se ao servidor de banco de dados por nome e porta padrão
    $service = ibase_service_attach ('fb-server.contoso.local', 'sysdba', 'masterkey');

    // Inicia o processo de backup no servidor de banco de dados
    // Faz backup do banco de dados de funcionários usando o apelido /srv/backup/employees.fbk.
    // Faz backup somente dos metadados. Não cria um backup transportável.
    ibase_backup($service, 'employees.fdb', '/srv/backup/employees.fbk', IBASE_BKP_METADATA_ONLY | IBASE_BKP_NON_TRANSPORTABLE);

    // Libera a conexão
    ibase_service_detach ($service);
    ?>

### Veja Também

- ibase_restore() - Inicia uma tarefa de restauração no gerenciador de serviços e retorna imediatamente

# ibase_blob_add

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_add — Adiciona dados em um blob recém criado

### Descrição

function ibase_blob_add(resource `$blob_handle`, string `$data`): void

ibase_blob_add() adiciona dados em um blob criado com ibase_blob_create().

### Parâmetros

`blob_handle`
  Um manipulador blob aberto com ibase_blob_create().
`data`
  A informação a ser adicionada.

### Valor Retornado

Nenhum valor é retornado.

### Veja Também

- ibase_blob_cancel() - Cancela a criação de blob
- ibase_blob_close() - Fecha blob
- ibase_blob_create() - Cria um novo blob para adicionar dados
- ibase_blob_import() - Cria um blob, copia um arquivo para ele e o fecha

# ibase_blob_cancel

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_cancel — Cancela a criação de blob

### Descrição

function ibase_blob_cancel(resource `$blob_handle`): bool

Esta função descartará um BLOB se ele ainda não tiver sido fechado por ibase_blob_close().

### Parâmetros

`blob_handle`
  Um identificador BLOB aberto com ibase_blob_create().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ibase_blob_close() - Fecha blob
- ibase_blob_create() - Cria um novo blob para adicionar dados
- ibase_blob_import() - Cria um blob, copia um arquivo para ele e o fecha

# ibase_blob_close

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_close — Fecha blob

### Descrição

function ibase_blob_close(resource `$blob_handle`): mixed

Esta função fecha um BLOB que foi aberto para leitura por ibase_blob_open() ou foi aberto para escrita por ibase_blob_create().

### Parâmetros

`blob_handle`
  Um identificador de BLOB aberto com ibase_blob_create() ou ibase_blob_open().

### Valor Retornado

Se o BLOB estava sendo lido, esta função retorna `true` em caso de sucesso, se o BLOB estava sendo escrito, esta função retorna uma string contendo o id do BLOB que foi atribuído a ele pelo banco de dados. Em caso de falha, esta função retorna `false`.

### Veja Também

- ibase_blob_cancel() - Cancela a criação de blob
- ibase_blob_open() - Abre um blob para obter partes de dados

# ibase_blob_create

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_create — Cria um novo blob para adicionar dados

### Descrição

function ibase_blob_create(resource `$link_identifier` = `null`): resource|false

ibase_blob_create() cria um novo BLOB para preencher com dados.

### Parâmetros

`link_identifier`
  Um identificador de conexão do InterBase. Se omitido, a última conexão aberta é assumida.

### Valor Retornado

Retorna um identificador BLOB para uso posterior com ibase_blob_add() ou `false` em caso de falha.

### Veja Também

- ibase_blob_add() - Adiciona dados em um blob recém criado
- ibase_blob_cancel() - Cancela a criação de blob
- ibase_blob_close() - Fecha blob
- ibase_blob_import() - Cria um blob, copia um arquivo para ele e o fecha

# ibase_blob_echo

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_echo — Envia o conteúdo do blob para o navegador

### Descrição

function ibase_blob_echo(string `$blob_id`): bool
function ibase_blob_echo(resource `$link_identifier`, string `$blob_id`): bool

Esta função abre um BLOB para leitura e envia seu conteúdo diretamente para a saída padrão (o navegador, na maioria dos casos).

### Parâmetros

`link_identifier`
  Um identificador de conexão do InterBase. Se omitido, a última conexão aberta é assumida.
`blob_id`

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ibase_blob_open() - Abre um blob para obter partes de dados
- ibase_blob_close() - Fecha blob
- ibase_blob_get() - Retorna uma quantidade especificada de bytes de dados de um blob aberto

# ibase_blob_get

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_get — Retorna uma quantidade especificada de bytes de dados de um blob aberto

### Descrição

function ibase_blob_get(resource `$blob_handle`, int `$len`): string

Esta função retorna a quantidade `len` de bytes de um BLOB que foi aberto para leitura com ibase_blob_open().

> Nota: Não é possível ler de um BLOB que não foi aberto para escrita por ibase_blob_create().

### Parâmetros

`blob_handle`
  Um manipulador de BLOB aberto com ibase_blob_open().
`len`
  Tamanho da informação retornada.

### Valor Retornado

Retorna no máximo `len` bytes de um BLOB, ou `false` em falha.

### Exemplos

Exemplo #1 Exemplo da ibase_blob_get()

    <?php
    $result    = ibase_query("SELECT blob_value FROM table");
    $data      = ibase_fetch_object($result);
    $blob_data = ibase_blob_info($data->BLOB_VALUE);
    $blob_hndl = ibase_blob_open($data->BLOB_VALUE);
    echo         ibase_blob_get($blob_hndl, $blob_data[0]);
    ?>

Enquanto este exemplo não faz muito mais do que um 'ibase_blob_echo($data->BLOB_VALUE)' faria, ele mostra a você como obter a informação em uma $variavel para você poder manipular como quiser.

### Veja Também

- ibase_blob_open() - Abre um blob para obter partes de dados
- ibase_blob_close() - Fecha blob
- ibase_blob_echo() - Envia o conteúdo do blob para o navegador

# ibase_blob_import

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_import — Cria um blob, copia um arquivo para ele e o fecha

### Descrição

function ibase_blob_import(resource `$link_identifier`, resource `$file_handle`): string
function ibase_blob_import(resource `$file_handle`): string

Este função cria um BLOB, lê um arquivo inteiro para dentro dele, fecha, e retorna o id do BLOB.

### Parâmetros

`link_identifier`
  Um link identificador InterBase. Se omitido, o último link aberto é usado.
`file_handle`
  O manipulador de arquivo é um manipulador retornado por fopen().

### Valor Retornado

Retorna o id do BLOB em sucesso, ou `false` em erro.

### Exemplos

Exemplo #1 Exemplo da ibase_blob_import()

    <?php
    $dbh = ibase_connect($host, $username, $password);
    $filename = '/tmp/bar';

    $fd = fopen($filename, 'r');
    if ($fd) {

        $blob = ibase_blob_import($dbh, $fd);
        fclose($fd);

        if (!is_string($blob)) {
            // falha na importação
        } else {
            $query = "INSERT INTO foo (name, data) VALUES ('$filename', ?)";
            $prepared = ibase_prepare($dbh, $query);
            if (!ibase_execute($prepared, $blob)) {
                // falha na inserção do registro
            }
        }
    } else {
        // não foi possível abrir o arquivo de dados
    }
    ?>

### Veja Também

- ibase_blob_add() - Adiciona dados em um blob recém criado
- ibase_blob_cancel() - Cancela a criação de blob
- ibase_blob_close() - Fecha blob
- ibase_blob_create() - Cria um novo blob para adicionar dados

# ibase_blob_info

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_info — Retorna o tamanho do blob e outras informações úteis

### Descrição

function ibase_blob_info(resource `$link_identifier`, string `$blob_id`): array
function ibase_blob_info(string `$blob_id`): array

Retorna o tamanho do BLOB e outras informações úteis.

### Parâmetros

`link_identifier`
  Um identificador de conexão InterBase. Se omitido, a última conexão aberta é usada.
`blob_id`
  Um identificador de BLOB.

### Valor Retornado

Retorna um array contendo informações sobre um BLOB. A informação retornada consiste no tamanho do BLOB, o número de seguimentos que ele contém, o tamanho do maior segmento e quando é um BLOB de fluxo ou um BLOB segmentado.

# ibase_blob_open

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_open — Abre um blob para obter partes de dados

### Descrição

function ibase_blob_open(resource `$link_identifier`, string `$blob_id`): resource|false
function ibase_blob_open(string `$blob_id`): resource|false

Abre um BLOB existente para leitura.

### Parâmetros

`link_identifier`
  Um link identificador InterBase. Se omitido, o último link aberto é usado.
`blob_id`
  Um id de BLOB.

### Valor Retornado

Retorna um manipulador de BLOB para uso posterior com ibase_blob_get() ou `false` em caso de falha.

### Veja Também

- ibase_blob_close() - Fecha blob
- ibase_blob_echo() - Envia o conteúdo do blob para o navegador
- ibase_blob_get() - Retorna uma quantidade especificada de bytes de dados de um blob aberto

# ibase_close

(PHP 5, PHP 7 < 7.4.0)

ibase_close — Fecha uma conexão com um banco de dados InterBase

### Descrição

function ibase_close(resource `$connection_id` = `null`): bool

Fecha a conexão para um banco de dados InterBase que está associado a um ID retornado de ibase_connect(). A transação padrão na conexão é confirmada, outras transações são revertidas.

### Parâmetros

`connection_id`
  Um identificador de conexão InterBase retornado de ibase_connect(). Se omitido, a última conexão aberta é assumida.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ibase_connect() - Abre uma conexão com um banco de dados
- ibase_pconnect() - Abre uma conexão persistente com um banco de dados InterBase

# ibase_commit

(PHP 5, PHP 7 < 7.4.0)

ibase_commit — Confirma uma transação

### Descrição

function ibase_commit(resource `$link_or_trans_identifier` = `null`): bool

Confirma uma transação.

### Parâmetros

`link_or_trans_identifier`
  Se chamada sem um argumento, esta função confirma a transação padrão da conexão padrão. Se o argumento for um identificador de conexão, a transação padrão da conexão correspondente será confirmada. Se o argumento for um identificador de transação, a transação correspondente será confirmada.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# ibase_commit_ret

(PHP 5, PHP 7 < 7.4.0)

ibase_commit_ret — Confirma uma transação sem fechá-la

### Descrição

function ibase_commit_ret(resource `$link_or_trans_identifier` = `null`): bool

Confirma uma transação sem fechá-la.

### Parâmetros

`link_or_trans_identifier`
  Se chamada sem um argumento, esta função confirma a transação padrão da conexão padrão. Se o argumento for um identificador de conexão, a transação padrão da conexão correspondente será confirmada. Se o argumento for um identificador de transação, a transação correspondente será confirmada. O contexto da transação será retido, então as instruções executadas de dentro desta transação não serão invalidadas.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# ibase_connect

(PHP 5, PHP 7 < 7.4.0)

ibase_connect — Abre uma conexão com um banco de dados

### Descrição

function ibase_connect(
string `$database` = ?,
string `$username` = ?,
string `$password` = ?,
string `$charset` = ?,
int `$buffers` = ?,
int `$dialect` = ?,
string `$role` = ?,
int `$sync` = ?
): resource

Estabelece uma conexão com um banco de dados Firebird/InterBase.

No caso de uma segunda chamada a ibase_connect() com os mesmos argumntos, não será criada uma nova conexão, mas ao invés, será retornado o identificador da conexão já aberta. A conexão com o servidor será fechada assim que terminar a execução do script, a menos que seja fechada explicitamente pela chamada de ibase_close().

### Parâmetros

`database`
  O argumento `database` deve ser um caminho válido para o arquivo do banco de dados no servidor no qual ele reside. Se o servidor não for local, ele deve ser prefixado com 'hostname:' (TCP/IP), 'hostname/port:' (TCP/IP com servidor interbase em porta TCP customizada), '//hostname/' (NetBEUI), dependendo do protocolo de conexão usado.
`username`
  O nome de usuário. Pode ser definido com a diretiva `ibase.default_user` do php.ini
`password`
  A senha para `username`. Pode ser definida com a diretiva `ibase.default_password` do php.ini.
`charset`
  `charset` é o conjunto de caracteres padrão para o banco de dados.
`buffers`
  `buffers` é o número de buffers do banco de dados a serem alocados para o cache do lado do servidor. Se 0 ou omitido, o servidor escolhe o seu próprio padrão.
`dialect`
  `dialect` define o dialeto SQL padrão para qualquer comand executado na conexão, e o padrão é o mais alto suportado pelas bibliotecas do cliente.
`role`
  Funcional apenas com InterBase 5 e superior.
`sync`

### Valor Retornado

Retorna um identificador de conexão Firebird/InterBase em caso de sucesso, ou `false` em caso de erro.

### Erros/Exceções

Se você tiver um erro parecido com "Arithmetic exception, numeric overflow, or string truncation. Cannot transliterate character between character sets" (isto ocorre quando você tenta usar algum caractere com acento) ao usar esta função e depois de ibase_query(), deve-se definir o conjunto de caracteres (isto é, ISO8859_1 ou o conjunto de caracteres atual).

### Exemplos

Exemplo #1 Exemplo de ibase_connect()

    <?php
    $host = 'localhost:/path/to/your.gdb';

    $dbh = ibase_connect($host, $username, $password);
    $stmt = 'SELECT * FROM tblname';
    $sth = ibase_query($dbh, $stmt);
    while ($row = ibase_fetch_object($sth)) {
        echo $row->email, "\n";
    }
    ibase_free_result($sth);
    ibase_close($dbh);
    ?>

### Veja Também

- ibase_pconnect() - Abre uma conexão persistente com um banco de dados InterBase
- ibase_close() - Fecha uma conexão com um banco de dados InterBase

# ibase_db_info

(PHP 5, PHP 7 < 7.4.0)

ibase_db_info — Solicita estatísticas sobre um banco de dados

### Descrição

function ibase_db_info(
resource `$service_handle`,
string `$db`,
int `$action`,
int `$argument` = 0
): string
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

# ibase_delete_user

(PHP 5, PHP 7 < 7.4.0)

ibase_delete_user — Exclui um usuário de um banco de dados seguro

### Descrição

function ibase_delete_user(resource `$service_handle`, string `$user_name`): bool

### Parâmetros

`service_handle`
  O manipulador no serviço do servidor do banco de dados.
`user_name`
  O login do usuário que deseja-se remover do banco de dados.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ibase_add_user() - Adiciona um usuário a um banco de dados seguro
- ibase_modify_user() - Modifica um usuário para um banco de dados seguro

# ibase_drop_db

(PHP 5, PHP 7 < 7.4.0)

ibase_drop_db — Exclui um banco de dados

### Descrição

function ibase_drop_db(resource `$connection` = `null`): bool

Esta função exclui um banco de dados que foi aberto por ibase_connect() ou ibase_pconnect(). O banco de dados é fechado e excluído do servidor.

### Parâmetros

`connection`
  Um identificador de conexão do InterBase. Se omitido, a última conexão aberta é assumida.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ibase_connect() - Abre uma conexão com um banco de dados
- ibase_pconnect() - Abre uma conexão persistente com um banco de dados InterBase

# ibase_errcode

(PHP 5, PHP 7 < 7.4.0)

ibase_errcode — Retorna um código de erro

### Descrição

function ibase_errcode(): int

Retorna o código de erro que resultou da chamada mais recente da função InterBase.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o código de erro como um inteiro ou `false` se nenhum erro ocorreu.

### Veja Também

- ibase_errmsg() - Retorna mensagens de erro

# ibase_errmsg

(PHP 5, PHP 7 < 7.4.0)

ibase_errmsg — Retorna mensagens de erro

### Descrição

function ibase_errmsg(): string

Retorna a mensagem de erro resultante da chamada mais recente da função InterBase.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a mensagem de erro como uma string, ou `false` se nenhum erro ocorreu.

### Veja Também

- ibase_errcode() - Retorna um código de erro

# ibase_execute

(PHP 5, PHP 7 < 7.4.0)

ibase_execute — Executa uma consulta preparada anteriormente

### Descrição

function ibase_execute(resource `$query`, mixed `...$values`): resource

Executa uma consulta preparada por ibase_prepare().

Isto é muito mais efetivo do que usar ibase_query() se você estiver repetindo o mesmo tipo de consulta muitas vezes apenas mudando alguns parâmetros.

### Parâmetros

`query`
  Uma consulta do InterBase preparada por ibase_prepare().
`values`

### Valor Retornado

Se houver um erro na consulta, retorna `false`. Se for bem sucedida e tiver um conjunto de resultados (possivelmente vazio, como em uma consulta SELECT), retorna um identificador de resultado. Se a consulta for bem sucedida e não houver resultados, retorna `true`.

> Nota: Esta função retorna o número de linhas afetadas pela consulta (se > 0 e aplicável ao tipo de declaração). A consulta que tenha sido bem sucedida mas não afete nenhuma linha(ex.: um UPDATE de um registro que não exista) irá retornar `true`.

### Exemplos

Exemplo #1 Exemplo de ibase_execute()

    <?php

    $dbh = ibase_connect($host, $username, $password);

    $updates = array(
        1 => 'Eric',
        5 => 'Filip',
        7 => 'Larry'
    );

    $query = ibase_prepare($dbh, "UPDATE FOO SET BAR = ? WHERE BAZ = ?");

    foreach ($updates as $baz => $bar) {
        ibase_execute($query, $bar, $baz);
    }

    ?>

### Veja Também

- ibase_query() - Executa uma consulta em um banco de dados InterBase

# ibase_fetch_assoc

(PHP 5, PHP 7 < 7.4.0)

ibase_fetch_assoc — Obtém uma linha de resultado de uma consulta como um array associativo

### Descrição

function ibase_fetch_assoc(resource `$result`, int `$fetch_flag` = 0): array

Obtém uma linha de resultado de uma consulta como um array associativo.

ibase_fetch_assoc() busca uma linha de dados do resultado do parâmetro `result`. Se duas ou mais colunas do resultado tiverem os mesmos nomes de campo, a última coluna terá precedência. Para acessar as outras colunas com o mesmo nome, é necessário acessar o resultado com índices numéricos usando ibase_fetch_row() ou usar nomes de apelidos na consulta.

### Parâmetros

`result`
  O identificador de resultado.
`fetch_flag`
  `fetch_flag` é uma combinação das constantes `IBASE_TEXT` e `IBASE_UNIXTIME` através de operação OR binária. Passar `IBASE_TEXT` fará com que esta função retorne conteúdos BLOB em vez de IDs BLOB. Passar `IBASE_UNIXTIME` fará com que esta função retorne valores de data/horário como timestamp Unix em vez de strings formatadas.

### Valor Retornado

Retorna um array associativo que corresponde à linha buscada. Chamadas subsequentes retornarão a próxima linha no conjunto de resultados, ou `false` se não houver mais linhas.

### Veja Também

- ibase_fetch_row() - Busca uma linha de um banco de dados InterBase
- ibase_fetch_object() - Obtém um objeto de um banco de dados InterBase

# ibase_fetch_object

(PHP 5, PHP 7 < 7.4.0)

ibase_fetch_object — Obtém um objeto de um banco de dados InterBase

### Descrição

function ibase_fetch_object(resource `$result_id`, int `$fetch_flag` = 0): object

Busca uma linha como um pseudoobjeto de um identificador de resultado fornecido.

Chamadas subsequentes para ibase_fetch_object() retornam a próxima linha no conjunto de resultados.

### Parâmetros

`result_id`
  Um identificador de resultado do InterBase obtido por ibase_query() ou ibase_execute().
`fetch_flag`
  `fetch_flag` é uma combinação das constantes `IBASE_TEXT` e `IBASE_UNIXTIME` através de operação OR binária. Passar `IBASE_TEXT` fará com que esta função retorne conteúdos BLOB em vez de IDs BLOB. Passar `IBASE_UNIXTIME` fará com que esta função retorne valores de data/horário como timestamp Unix em vez de strings formatadas.

### Valor Retornado

Retorna um objeto com as informações da próxima linha, ou `false` se não houver mais linhas.

### Exemplos

Exemplo #1 Exemplo de ibase_fetch_object()

    <?php
    $dbh = ibase_connect($host, $username, $password);
    $stmt = 'SELECT * FROM tblname';
    $sth = ibase_query($dbh, $stmt);
    while ($row = ibase_fetch_object($sth)) {
        echo $row->email . "\n";
    }
    ibase_close($dbh);
    ?>

### Veja Também

- ibase_fetch_row() - Busca uma linha de um banco de dados InterBase
- ibase_fetch_assoc() - Obtém uma linha de resultado de uma consulta como um array associativo

# ibase_fetch_row

(PHP 5, PHP 7 < 7.4.0)

ibase_fetch_row — Busca uma linha de um banco de dados InterBase

### Descrição

function ibase_fetch_row(resource `$result_identifier`, int `$fetch_flag` = 0): array

ibase_fetch_row() busca uma linha de dados do conjunto de resultados fornecido.

Chamadas subsequentes para ibase_fetch_row() retornam a próxima linha no conjunto de resultados, ou `false` se não houver mais linhas.

### Parâmetros

`result_identifier`
  Um identificador de resultado do InterBase.
`fetch_flag`
  `fetch_flag` é uma combinação das constantes `IBASE_TEXT` e `IBASE_UNIXTIME` através de operação OR binária. Passar `IBASE_TEXT` fará com que esta função retorne conteúdos BLOB em vez de IDs BLOB. Passar `IBASE_UNIXTIME` fará com que esta função retorne valores de data/horário como timestamp Unix em vez de strings formatadas.

### Valor Retornado

Retorna um array que corresponde à linha buscada, ou `false` se não houver mais linhas. Cada coluna de resultado é armazenada em um deslocamento de array, começando no deslocamento 0.

### Veja Também

- ibase_fetch_assoc() - Obtém uma linha de resultado de uma consulta como um array associativo
- ibase_fetch_object() - Obtém um objeto de um banco de dados InterBase

# ibase_field_info

(PHP 5, PHP 7 < 7.4.0)

ibase_field_info — Obtém informação sobre um campo

### Descrição

function ibase_field_info(resource `$result`, int `$field_number`): array

Retorna um array com informações sobre um campo após uma consulta SELECT ter sido executada.

### Parâmetros

`result`
  Um identificador de resultado do InterBase.
`field_number`
  Índice do campo.

### Valor Retornado

Retorna um array com as seguintes chaves: `name`, `alias`, `relation`, `length` e `type`.

### Exemplos

Exemplo #1 Exemplo da ibase_field_info()

    <?php
        $rs = ibase_query("SELECT * FROM tablename");
        $coln = ibase_num_fields($rs);
        for ($i = 0; $i < $coln; $i++) {
            $col_info = ibase_field_info($rs, $i);
            echo "name: ". $col_info['name']. "\n";
            echo "alias: ". $col_info['alias']. "\n";
            echo "relation: ". $col_info['relation']. "\n";
            echo "length: ". $col_info['length']. "\n";
            echo "type: ". $col_info['type']. "\n";
        }
    ?>

### Veja Também

- ibase_num_fields() - Obtém o número de campos em um conjunto de resultados

# ibase_free_event_handler

(PHP 5, PHP 7 < 7.4.0)

ibase_free_event_handler — Cancela um manipulador de eventos registrado

### Descrição

function ibase_free_event_handler(resource `$event`): bool

Esta função faz com que o manipulador de eventos registrado especificado por `event` seja cancelado. A função de callback não será mais chamada para os eventos que estava registrada para manipular.

### Parâmetros

`event`
  Um resource de evento criado com ibase_set_event_handler().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ibase_set_event_handler() - Registra uma função de retorno a ser chamada quando eventos são postados

# ibase_free_query

(PHP 5, PHP 7 < 7.4.0)

ibase_free_query — Libera a memória alocada para uma consulta preparada

### Descrição

function ibase_free_query(resource `$query`): bool

Libera uma query preparada.

### Parâmetros

`query`
  Uma query preparada com ibase_prepare().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# ibase_free_result

(PHP 5, PHP 7 < 7.4.0)

ibase_free_result — Libera um conjunto de resultados

### Descrição

function ibase_free_result(resource `$result_identifier`): bool

Libera um conjunto de resultado.

### Parâmetros

`result_identifier`
  Um conjunto de resultado criado pela ibase_query() ou ibase_execute().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# ibase_gen_id

(PHP 5, PHP 7 < 7.4.0)

ibase_gen_id — Incrementa o gerador nomeado e retorna seu novo valor

### Descrição

function ibase_gen_id(string `$generator`, int `$increment` = 1, resource `$link_identifier` = `null`): mixed
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Valor Retornado

Retorna o novo valor do gerador como inteiro ou como string se o valor for muito grande.

# ibase_maintain_db

(PHP 5, PHP 7 < 7.4.0)

ibase_maintain_db — Executa um comando de manutenção no servidor de banco de dados

### Descrição

function ibase_maintain_db(
resource `$service_handle`,
string `$db`,
int `$action`,
int `$argument` = 0
): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# ibase_modify_user

(PHP 5, PHP 7 < 7.4.0)

ibase_modify_user — Modifica um usuário para um banco de dados seguro

### Descrição

function ibase_modify_user(
resource `$service_handle`,
string `$user_name`,
string `$password`,
string `$first_name` = ?,
string `$middle_name` = ?,
string `$last_name` = ?
): bool

### Parâmetros

`service_handle`
  O manipulador no serviço do servidor de banco de dados.
`user_name`
  O login do usuário do banco de dados a modificar.
`password`
  A nova senha do usuário.
`first_name`
  O novo primeiro nome do usuário.
`middle_name`
  O novo nome do meio do usuário.
`last_name`
  O novo último nome do usuário.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ibase_add_user() - Adiciona um usuário a um banco de dados seguro
- ibase_delete_user() - Exclui um usuário de um banco de dados seguro

# ibase_name_result

(PHP 5, PHP 7 < 7.4.0)

ibase_name_result — Define um nome para um conjunto de resultados

### Descrição

function ibase_name_result(resource `$result`, string `$name`): bool

Esta função define um nome para um conjunto de resultados. Este nome pode ser usado posteriormente em comandos UPDATE|DELETE ... WHERE CURRENT OF `name`.

### Parâmetros

`result`
  Um conjunto de resultado do InterBase.
`name`
  O nome a ser atribuído.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo da ibase_name_result()

    <?php
    $result = ibase_query("SELECT field1,field2 FROM table FOR UPDATE");
    ibase_name_result($result, "my_cursor");

    $updateqry = ibase_prepare("UPDATE table SET field2 = ? WHERE CURRENT OF my_cursor");

    for ($i = 0; ibase_fetch_row($result); ++$i) {
        ibase_execute($updateqry, $i);
    }
    ?>

### Veja Também

- ibase_prepare() - Prepara uma consulta para ligação de parâmetros e execução posteriores
- ibase_execute() - Executa uma consulta preparada anteriormente

# ibase_num_fields

(PHP 5, PHP 7 < 7.4.0)

ibase_num_fields — Obtém o número de campos em um conjunto de resultados

### Descrição

function ibase_num_fields(resource `$result_id`): int

Obtém o número de campos em um conjunto de resultados.

### Parâmetros

`result_id`
  Um identificador de resultado InterBase.

### Valor Retornado

Retorna o número de campos como um inteiro.

### Exemplos

Exemplo #1 Exemplo da ibase_num_fields()

    <?php
        $rs = ibase_query("SELECT * FROM tablename");
        $coln = ibase_num_fields($rs);
        for ($i = 0; $i < $coln; $i++) {
            $col_info = ibase_field_info($rs, $i);
            echo "name: " . $col_info['name'] . "\n";
            echo "alias: " . $col_info['alias'] . "\n";
            echo "relation: " . $col_info['relation'] . "\n";
            echo "length: " . $col_info['length'] . "\n";
            echo "type: " . $col_info['type'] . "\n";
        }
    ?>

### Veja Também

- ibase_field_info() - Obtém informação sobre um campo

# ibase_num_params

(PHP 5, PHP 7 < 7.4.0)

ibase_num_params — Retorna o número de parâmetros em uma consulta preparada

### Descrição

function ibase_num_params(resource `$query`): int

Esta função retorna o número de parâmetros em uma consulta preparada especificada `query`. Este é o numero de argumentos que devem estar presentes quando usar a função ibase_execute().

### Parâmetros

`query`
  O manipulador da query preparada.

### Valor Retornado

Retorna o número de parâmetros como um inteiro.

### Veja Também

- ibase_prepare() - Prepara uma consulta para ligação de parâmetros e execução posteriores
- ibase_param_info() - Retorna informação sobre um parâmetro em uma consulta preparada

# ibase_param_info

(PHP 5, PHP 7 < 7.4.0)

ibase_param_info — Retorna informação sobre um parâmetro em uma consulta preparada

### Descrição

function ibase_param_info(resource `$query`, int `$param_number`): array

Retorna um array com informações sobre um parâmetro após a consulta ter sido preparada.

### Parâmetros

`query`
  Um manipulador de query preparada do InterBase.
`param_number`
  O índice do parâmetro.

### Valor Retornado

Retorna um array com as seguintes chaves: `name`, `alias`, `relation`, `length` e `type`.

### Veja Também

- ibase_field_info() - Obtém informação sobre um campo
- ibase_num_params() - Retorna o número de parâmetros em uma consulta preparada

# ibase_pconnect

(PHP 5, PHP 7 < 7.4.0)

ibase_pconnect — Abre uma conexão persistente com um banco de dados InterBase

### Descrição

function ibase_pconnect(
string `$database` = ?,
string `$username` = ?,
string `$password` = ?,
string `$charset` = ?,
int `$buffers` = ?,
int `$dialect` = ?,
string `$role` = ?,
int `$sync` = ?
): resource

Abre uma conexão persistente com um banco de dados InterBase.

ibase_pconnect() age muito como ibase_connect() com duas diferenças principais.

Primeiro, ao conectar, a função tentará primeiro encontrar uma conexão (persistente) que já esteja aberta com os mesmos parâmetros. Se um for encontrada, um identificador para ela será retornado em vez de abrir uma nova conexão.

Segundo, a conexão com o servidor InterBase não será fechada quando a execução do script terminar. Em vez disso, ela permanecerá aberta para uso futuro (ibase_close() não fechará conexões estabelecidas por ibase_pconnect()). Este tipo de conexão é portanto chamada de 'persistente'.

### Parâmetros

`database`
  O argumento `database` tem que ser um caminho válido para o arquivo de banco de dados no servidor em que ele reside. Se o servidor não for local, ele deve ser prefixado com 'hostname:' (TCP/IP), '//hostname/' (NetBEUI) ou 'hostname@' (IPX/SPX), dependendo do protocolo de conexão usado.
`username`
  O nome do usuário. Pode ser definido com a diretiva `ibase.default_user` php.ini.
`password`
  A senha para `username`. Pode ser definida com a `ibase.default_password` php.ini diretiva.
`charset`
  `charset` é o conjunto de caracteres padrão para o banco de dados.
`buffers`
  `buffers` é o número de buffers de banco de dados a alocar para o cache do lado do servidor. Se 0 ou omitido, o servidor escolhe seu próprio padrão.
`dialect`
  `dialect` seleciona o dialeto SQL padrão para qualquer declaração executada dentro de uma conexão, e ele assume como padrão o mais alto suportado pelas bibliotecas do cliente. Funcional apenas com o InterBase 6 e superior.
`role`
  Funcional apenas com InterBase 5 e superior.
`sync`

### Valor Retornado

Retorna um identificador de conexão do InterBase em caso de sucesso, ou `false` em caso de erro.

### Veja Também

- ibase_close() - Fecha uma conexão com um banco de dados InterBase
- ibase_connect() - Abre uma conexão com um banco de dados

# ibase_prepare

(PHP 5, PHP 7 < 7.4.0)

ibase_prepare — Prepara uma consulta para ligação de parâmetros e execução posteriores

### Descrição

function ibase_prepare(string `$query`): resource
function ibase_prepare(resource `$link_identifier`, string `$query`): resource
function ibase_prepare(resource `$link_identifier`, string `$trans`, string `$query`): resource

Prepara uma consulta para ligação de parâmetros e execução posteriores (via ibase_execute()).

### Parâmetros

`query`
  Uma consulta InterBase.
`link_identifier`
  Um identificador de conexão InterBase retornado por ibase_connect(). Se omitido, o identificador da última conexão aberta será utilizado.
`trans`
  Um manipulador de transação InterBase com a qual a consulta deve ser associada. Se omitido, a transação padrão da conexão será utilizada.

### Valor Retornado

Retorna o manipulador da consulta preparada, ou `false` em caso de erro.

# ibase_query

(PHP 5, PHP 7 < 7.4.0)

ibase_query — Executa uma consulta em um banco de dados InterBase

### Descrição

function ibase_query(resource `$link_identifier` = ?, string `$query`, int `$bind_args` = ?): resource

Executa uma consulta em um banco de dados InterBase.

### Parâmetros

`link_identifier`
  Um identificador de conexão InterBase. Se omitido, o da última conexão será utilizado.
`query`
  Uma consulta do InterBase.
`bind_args`

### Valor Retornado

Se houver um erro na consulta, retorna `false`. Se ela for bem sucedida e houver um conjunto de resultados (possivelmente vazio), como o retornado por uma consulta SELECT, retorna um identificador de resultado. Se a consulta for bem sucedida e não houver resultado, retorna `true`.

> Nota: No PHP 5.0.0 e posterior, esta função irá retornar o número de linhas afetadas pela consulta para INSERT, UPDATE e DELETE. Para manter a compatibilidade com versões anteriores, irá retornar `true` para estas consultas se ela for bem sucedida sem afetar nenhuma linha.

### Erros/Exceções

Se você tiver um erro como "arithmetic exception, numeric overflow, or string truncation. Cannot transliterate character between character sets" (isto acontece quando você tenta usar alguns caracteres com acentos) ao usar esta função e depois de ibase_query(), deve-se definir o conjunto de caracteres (isto é, ISO8859_1 ou o conjunto de caracteres atual).

### Exemplos

Exemplo #1 Exemplo de ibase_query()

    <?php

    $host = 'localhost:/path/to/your.gdb';

    $dbh = ibase_connect($host, $username, $password);
    $stmt = 'SELECT * FROM tblname';

    $sth = ibase_query($dbh, $stmt) or die(ibase_errmsg());

    ?>

### Veja Também

- ibase_errmsg() - Retorna mensagens de erro
- ibase_fetch_row() - Busca uma linha de um banco de dados InterBase
- ibase_fetch_object() - Obtém um objeto de um banco de dados InterBase
- ibase_free_result() - Libera um conjunto de resultados

# ibase_restore

(PHP 5, PHP 7 < 7.4.0)

ibase_restore — Inicia uma tarefa de restauração no gerenciador de serviços e retorna imediatamente

### Descrição

function ibase_restore(
resource `$service_handle`,
string `$source_file`,
string `$dest_db`,
int `$options` = 0,
bool `$verbose` = `false`
): mixed

Esta função passa os argumentos para o servidor de banco de dados (remoto). Lá, ele inicia um novo processo de restauração. Portanto, você não obterá nenhuma resposta.

### Parâmetros

`service_handle`
  Uma conexão aberta anteriormente com o servidor de banco de dados.
`source_file`
  O caminho absoluto no servidor onde o arquivo de backup está localizado.
`dest_db`
  O caminho para criar o novo banco de dados no servidor. Pode-se também usar o apelido do banco de dados.
`options`

  Opções adicionais para passar ao servidor de banco de dados para restauração. O parâmetro `options` pode ser uma combinação das seguintes constantes: `IBASE_RES_DEACTIVATE_IDX`, `IBASE_RES_NO_SHADOW`, `IBASE_RES_NO_VALIDITY`, `IBASE_RES_ONE_AT_A_TIME`, `IBASE_RES_REPLACE`, `IBASE_RES_CREATE`, `IBASE_RES_USE_ALL_SPACE`, `IBASE_PRP_PAGE_BUFFERS`, `IBASE_PRP_SWEEP_INTERVAL` e `IBASE_RES_CREATE`. Leia a seção sobre Constantes predefinidas para mais informações.

`verbose`
  Como o processo de restauração é feito no servidor de banco de dados, não há como obter sua saída. Este argumento é inútil.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

Como o processo de restauração é feito no servidor (remoto), esta função apenas passa os argumentos para ele. Embora os argumentos sejam legais, não será obtido `false`.

### Exemplos

Exemplo #1 Exemplo de ibase_restore()

    <?php

    // Conecta-se ao servidor de banco de dados por endereço IP e porta
    $service = ibase_service_attach ('10.1.11.200/3050', 'sysdba', 'masterkey');

    // Inicia o processo de restauração no servidor de banco de dados
    // Restaura o backup 'employees' para o novo banco de dados 'emps.fdb'
    // Não usa nenhum argumento especial
    ibase_restore($service, '/srv/backup/employees.fbk', '/srv/firebird/emps.fdb');

    // Libera a conexão
    ibase_service_detach ($service);
    ?>

Exemplo #2 Exemplo de ibase_restore() com argumentos

    <?php

    // Conecta-se ao servidor de banco de dados por nome e porta padrão
    $service = ibase_service_attach ('fb-server.contoso.local', 'sysdba', 'masterkey');

    // Inicia o processo de restauração no servidor de banco de dados
    // Restaurar o banco de dados 'employees' usando o apelido.
    // Restaura sem índices. Substitui banco de dados existente.
    ibase_restore($service, '/srv/backup/employees.fbk', 'employees.fdb', IBASE_RES_DEACTIVATE_IDX | IBASE_RES_REPLACE);

    // Libera a conexão
    ibase_service_detach ($service);
    ?>

### Veja Também

- ibase_backup() - Inicia uma tarefa de backup no gerenciador de serviços e retorna imediatamente

# ibase_rollback

(PHP 5, PHP 7 < 7.4.0)

ibase_rollback — Reverte uma transação

### Descrição

function ibase_rollback(resource `$link_or_trans_identifier` = `null`): bool

Reverte uma transação.

### Parâmetros

`link_or_trans_identifier`
  Se chamada sem um argumento, esta função reverte a transação padrão da conexão padrão. Se o argumento for um identificador de conexão, a transação padrão da conexão correspondente será revertida. Se o argumento for um identificador de transação, a transação correspondente será revertida.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# ibase_rollback_ret

(PHP 5, PHP 7 < 7.4.0)

ibase_rollback_ret — Reverte uma transação sem fechá-la

### Descrição

function ibase_rollback_ret(resource `$link_or_trans_identifier` = `null`): bool

Reverte uma transação sem fechá-la.

### Parâmetros

`link_or_trans_identifier`
  Se chamada sem um argumento, esta função reverte a transação padrão da conexão padrão. Se o argumento for um identificador de conexão, a transação padrão da conexão correspondente será revertida. Se o argumento for um identificador de transação, a transação correspondente será revertida. O contexto da transação será retido, então as instruções executadas de dentro desta transação não serão invalidadas.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# ibase_server_info

(PHP 5, PHP 7 < 7.4.0)

ibase_server_info — Solicita informações sobre um servidor de banco de dados

### Descrição

function ibase_server_info(resource `$service_handle`, int `$action`): string

### Parâmetros

`service_handle`
  Uma conexão criada anteriormente com o servidor de banco de dados.
`action`
  Uma constante válida.

### Valor Retornado

Retorna tipos mistos dependendo do contexto.

### Exemplos

Exemplo #1 Exemplo de ibase_service_attach()

    <?php
        // Conecta-se ao servidor Firebird remoto
        if (($service = ibase_service_attach('10.1.1.254/3050', 'sysdba', 'masterkey')) != FALSE) {

            // Conectado com sucesso.

            // Exibe a informação
            echo "Versão do servidor: " . ibase_server_info($service, IBASE_SVC_SERVER_VERSION) . "\n";
            echo "Implementação do servidor: " . ibase_server_info($service, IBASE_SVC_IMPLEMENTATION) . "\n";
            echo "Usuários do servidor: " . print_r(ibase_server_info($service, IBASE_SVC_GET_USERS), true) . "\n";
            echo "Diretório do servidor: " . ibase_server_info($service, IBASE_SVC_GET_ENV) . "\n";
            echo "Caminho de travas do servidor: " . ibase_server_info($service, IBASE_SVC_GET_ENV_LOCK) . "\n";
            echo "Caminho de bibliotecas do servidor: " . ibase_server_info($service, IBASE_SVC_GET_ENV_MSG) . "\n";
            echo "Caminho do banco de dados do usuário: " . ibase_server_info($service, IBASE_SVC_USER_DBPATH) . "\n";
            echo "Conexões estabelecidas: " . print_r(ibase_server_info($service, IBASE_SVC_SVR_DB_INFO),true) . "\n";

            // Desconecta do servidor
            ibase_service_detach($service);

        }
        else {
            // Exibe mensagem em caso de erro
            $conn_error = ibase_errmsg();
            die($conn_error);
        }
    ?>

O exemplo acima produzirá:

    Versão do servidor: LI-V3.0.4.33054 Firebird 3.0
    Implementação do servidor: Firebird/Linux/AMD/Intel/x64
    Usuários do servidor: Array
    (
        [0] => Array
            (
                [user_name] => SYSDBA
                [first_name] => Sql
                [middle_name] => Server
                [last_name] => Administrator
                [user_id] => 0
                [group_id] => 0
            )

    )

    Diretório do servidor: /etc/firebird/
    Caminho de travas do servidor: /tmp/firebird/
    Caminho de bibliotecas do servidor: /usr/lib64/firebird/lib/
    Caminho do banco de dados do usuário: /var/lib/firebird/secdb/security3.fdb
    Conexões estabelecidas: Array
    (
        [attachments] => 3
        [databases] => 2
        [0] => /srv/firebird/poss.fdb
        [1] => /srv/firebird/employees.fdb
    )

# ibase_service_attach

(PHP 5, PHP 7 < 7.4.0)

ibase_service_attach — Conecta ao gerenciador de serviços

### Descrição

function ibase_service_attach(string `$host`, string `$dba_username`, string `$dba_password`): resource|false

### Parâmetros

`host`
  O nome ou endereço IP do host do banco de dados. Você pode definir a porta adicionando '/' e o número da porta. Se nenhuma porta for especificada, a porta 3050 será usada.
`dba_username`
  O nome de qualquer usuário válido.
`dba_password`
  A senha do usuário.

### Valor Retornado

Retorna um identificador de conexão Interbase/Firebird em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de ibase_service_attach()

    <?php
        // Conecta-se ao servidor Firebird remoto por endereço IP
        if (($service = ibase_service_attach('10.1.1.199', 'sysdba', 'masterkey')) != FALSE) {

            // Conectado com sucesso.
            // Obtém versão do servidor (algo como 'LI-V3.0.4.33054 Firebird 3.0')
            $server_version  = ibase_server_info($service, IBASE_SVC_SERVER_VERSION);

            // Busca a implementação do servidor (algo como 'Firebird/Linux/AMD/Intel/x64')
            $server_implementation = ibase_server_info($service, IBASE_SVC_IMPLEMENTATION);

            // Desconecta do servidor
            ibase_service_detach($service);

            // Exibe a informação
            echo "Versão do servidor: " . $server_version . "<br/>";
            echo "Implementação do servidor: " . $server_implementation;
        }
        else {
            // Exibe mensagem em caso de erro
            $conn_error = ibase_errmsg();
            die($conn_error);
        }

    ?>

Exemplo #2 Exemplo de ibase_service_attach() usando a sintaxe `hostname/port`

    <?php
        // Conecta-se ao servidor Firebird remoto pelo nome. Usa a porta 3050.
        if (($service = ibase_service_attach('FB-SRV-01.contoso.local/3050', 'sysdba', 'masterkey')) != FALSE) {

            // Conectado com sucesso.
            // Obtém versão do servidor (algo como 'LI-V3.0.4.33054 Firebird 3.0')
            $server_version  = ibase_server_info($service, IBASE_SVC_SERVER_VERSION);

            // Busca a implementação do servidor (algo como 'Firebird/Linux/AMD/Intel/x64')
            $server_implementation = ibase_server_info($service, IBASE_SVC_IMPLEMENTATION);

            // Desconecta do servidor
            ibase_service_detach($service);

            // Exibe a informação
            echo "Versão do servidor: " . $server_version . "<br/>";
            echo "Implementação do servidor: " . $server_implementation;
        }
        else {
            // Exibe mensagem em caso de erro
            $conn_error = ibase_errmsg();
            die($conn_error);
        }

    ?>

### Veja Também

- ibase_service_detach() - Desconecta do gerenciador de serviços

# ibase_service_detach

(PHP 5, PHP 7 < 7.4.0)

ibase_service_detach — Desconecta do gerenciador de serviços

### Descrição

function ibase_service_detach(resource `$service_handle`): bool

### Parâmetros

`service_handle`
  Uma conexão criada anteriormente com o servidor de banco de dados.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de ibase_service_detach()

    <?php
        // Conecta ao servidor Firebird remoto pelo endereço IP
        if (($service = ibase_service_attach('10.1.1.199', 'sysdba', 'masterkey')) != FALSE) {

            // Conectado com sucesso.
            // Obtém versão do servidor (algo como 'LI-V3.0.4.33054 Firebird 3.0')
            $server_version  = ibase_server_info($service, IBASE_SVC_SERVER_VERSION);

            // Busca a implementação do servidor (algo como 'Firebird/Linux/AMD/Intel/x64')
            $server_implementation = ibase_server_info($service, IBASE_SVC_IMPLEMENTATION);

            // Desconecta do servidor
            if(ibase_service_detach($service) == FALSE) {
                echo "Erro ao desconectar do serviço.";
            }
            else {
                echo "Desconectado do serviço com sucesso.";
            }

        }
        else {
            // Exibe mensagem em caso de erro
            $conn_error = ibase_errmsg();
            die($conn_error);
        }

    ?>

# ibase_set_event_handler

(PHP 5, PHP 7 < 7.4.0)

ibase_set_event_handler — Registra uma função de retorno a ser chamada quando eventos são postados

### Descrição

function ibase_set_event_handler(callable `$event_handler`, string `$event_name`, string `...$even_names`): resource
function ibase_set_event_handler(
resource `$connection`,
callable `$event_handler`,
string `$event_name`,
string `...$event_names`
): resource

Esta função registra uma função de usuário PHP como manipulador de eventos para os eventos especificados.

### Parâmetros

`event_handler`
  A função de retorno é chamada com o nome do evento e o recurso de conexão como argumentos sempre que um dos eventos especificados é publicado pelo banco de dados. A função de retorno deve retornar `false` se o manipulador de eventos deve ser cancelado. Qualquer outro valor de retorno é ignorado. Esta função aceita até 15 argumentos de eventos.
`event_name`
  Um nome de evento.
`event_names`
  No máximo 15 eventos permitidos.

### Valor Retornado

O valor de retorno é um recurso de evento. Este recurso pode ser usado para liberar o manipulador de eventos usando ibase_free_event_handler().

### Exemplos

Exemplo #1 Exemplo de ibase_set_event_handler()

    <?php

    function event_handler($event_name, $link)
    {
        if ($event_name == "NEW ORDER") {
            // processa novo pedido
            ibase_query($link, "UPDATE orders SET status='handled'");
        } else if ($event_name == "DB_SHUTDOWN") {
            // libera manipulador de eventos
            return false;
        }
    }

    ibase_set_event_handler($link, "event_handler", "NEW_ORDER", "DB_SHUTDOWN");
    ?>

### Veja Também

- ibase_free_event_handler() - Cancela um manipulador de eventos registrado
- ibase_wait_event() - Espera por um evento ser postado pelo banco de dados

# ibase_trans

(PHP 5, PHP 7 < 7.4.0)

ibase_trans — Inicia uma transação

### Descrição

function ibase_trans(int `$trans_args` = ?, resource `$link_identifier` = ?): resource
function ibase_trans(resource `$link_identifier` = ?): resource

Inicia uma transação.

> Nota: A primeira chamada para ibase_trans() não retornará a transação padrão de uma conexão. Todas as transações iniciadas por ibase_trans() serão revertidas no final do script se não foram confirmadas ou revertidas por ibase_commit() ou ibase_rollback().

> Nota: Esta função aceitará múltiplos argumentos `trans_args` e `link_identifier`. Isso permite transações em múltiplas conexões de banco de dados, que são confirmadas usando um algoritmo de confirmação de 2 fases. Isso significa pode-se confiar nas atualizações para ter sucesso em todos os bancos de dados ou falhar em todos os bancos de dados. Isso NÃO significa que podem ser usadas tabelas de diferentes bancos de dados na mesma consulta! Se forem usadas transações em vários bancos de dados, deve-se especificar tanto o `link_id` quanto o `transaction_id` em chamadas para ibase_query() e ibase_prepare().

### Parâmetros

`trans_args`
  `trans_args` pode ser uma combinação das constantes `IBASE_READ`, `IBASE_WRITE`, `IBASE_COMMITTED`, `IBASE_CONSISTENCY`, `IBASE_CONCURRENCY`, `IBASE_REC_VERSION`, `IBASE_REC_NO_VERSION`, `IBASE_WAIT` e `IBASE_NOWAIT`.
`link_identifier`
  Um identificador de ligação do InterBase. Se omitido, a última ligação aberta é assumida.

### Valor Retornado

Retorna um identificador de transação ou `false` em caso de erro.

# ibase_wait_event

(PHP 5, PHP 7 < 7.4.0)

ibase_wait_event — Espera por um evento ser postado pelo banco de dados

### Descrição

function ibase_wait_event(string `$event_name`, string `...$event_names`): string
function ibase_wait_event(resource `$connection`, string `$event_name`, string `...$event_names`): string

Esta função suspende a execução do script até que um dos dos eventos especificados seja postado pelo banco de dados. O nome do evento que foi postado é retornado. Esta função aceita até 15 argumentos de eventos.

### Parâmetros

`event_name`
  O nome do evento.
`event_names`

### Valor Retornado

Retorna o nome do evento que foi postado.

### Veja Também

- ibase_set_event_handler() - Registra uma função de retorno a ser chamada quando eventos são postados
- ibase_free_event_handler() - Cancela um manipulador de eventos registrado

## Índice

- fbird_add_user — Sinônimo de ibase_add_user
- fbird_affected_rows — Sinônimo de ibase_affected_rows
- fbird_backup — Sinônimo de ibase_backup
- fbird_blob_add — Sinônimo de ibase_blob_add
- fbird_blob_cancel — Cancela a criação de blob
- fbird_blob_close — Sinônimo de ibase_blob_close
- fbird_blob_create — Sinônimo de ibase_blob_create
- fbird_blob_echo — Sinônimo de ibase_blob_echo
- fbird_blob_get — Sinônimo de ibase_blob_get
- fbird_blob_import — Sinônimo de ibase_blob_import
- fbird_blob_info — Sinônimo de ibase_blob_info
- fbird_blob_open — Sinônimo de ibase_blob_open
- fbird_close — Sinônimo de ibase_close
- fbird_commit — Sinônimo de ibase_commit
- fbird_commit_ret — Sinônimo de ibase_commit_ret
- fbird_connect — Sinônimo de ibase_connect
- fbird_db_info — Sinônimo de ibase_db_info
- fbird_delete_user — Sinônimo de ibase_delete_user
- fbird_drop_db — Sinônimo de ibase_drop_db
- fbird_errcode — Sinônimo de ibase_errcode
- fbird_errmsg — Sinônimo de ibase_errmsg
- fbird_execute — Sinônimo de ibase_execute
- fbird_fetch_assoc — Sinônimo de ibase_fetch_assoc
- fbird_fetch_object — Sinônimo de ibase_fetch_object
- fbird_fetch_row — Sinônimo de ibase_fetch_row
- fbird_field_info — Sinônimo de ibase_field_info
- fbird_free_event_handler — Sinônimo de ibase_free_event_handler
- fbird_free_query — Sinônimo de ibase_free_query
- fbird_free_result — Sinônimo de ibase_free_result
- fbird_gen_id — Sinônimo de ibase_gen_id
- fbird_maintain_db — Sinônimo de ibase_maintain_db
- fbird_modify_user — Sinônimo de ibase_modify_user
- fbird_name_result — Sinônimo de ibase_name_result
- fbird_num_fields — Sinônimo de ibase_num_fields
- fbird_num_params — Sinônimo de ibase_num_params
- fbird_param_info — Sinônimo de ibase_param_info
- fbird_pconnect — Sinônimo de ibase_pconnect
- fbird_prepare — Sinônimo de ibase_prepare
- fbird_query — Sinônimo de ibase_query
- fbird_restore — Sinônimo de ibase_restore
- fbird_rollback — Sinônimo de ibase_rollback
- fbird_rollback_ret — Sinônimo de ibase_rollback_ret
- fbird_server_info — Sinônimo de ibase_server_info
- fbird_service_attach — Sinônimo de ibase_service_attach
- fbird_service_detach — Sinônimo de ibase_service_detach
- fbird_set_event_handler — Sinônimo de ibase_set_event_handler
- fbird_trans — Sinônimo de ibase_trans
- fbird_wait_event — Sinônimo de ibase_wait_event
- ibase_add_user — Adiciona um usuário a um banco de dados seguro
- ibase_affected_rows — Retorna o número de linhas que foram afetados pela consulta anterior
- ibase_backup — Inicia uma tarefa de backup no gerenciador de serviços e retorna imediatamente
- ibase_blob_add — Adiciona dados em um blob recém criado
- ibase_blob_cancel — Cancela a criação de blob
- ibase_blob_close — Fecha blob
- ibase_blob_create — Cria um novo blob para adicionar dados
- ibase_blob_echo — Envia o conteúdo do blob para o navegador
- ibase_blob_get — Retorna uma quantidade especificada de bytes de dados de um blob aberto
- ibase_blob_import — Cria um blob, copia um arquivo para ele e o fecha
- ibase_blob_info — Retorna o tamanho do blob e outras informações úteis
- ibase_blob_open — Abre um blob para obter partes de dados
- ibase_close — Fecha uma conexão com um banco de dados InterBase
- ibase_commit — Confirma uma transação
- ibase_commit_ret — Confirma uma transação sem fechá-la
- ibase_connect — Abre uma conexão com um banco de dados
- ibase_db_info — Solicita estatísticas sobre um banco de dados
- ibase_delete_user — Exclui um usuário de um banco de dados seguro
- ibase_drop_db — Exclui um banco de dados
- ibase_errcode — Retorna um código de erro
- ibase_errmsg — Retorna mensagens de erro
- ibase_execute — Executa uma consulta preparada anteriormente
- ibase_fetch_assoc — Obtém uma linha de resultado de uma consulta como um array associativo
- ibase_fetch_object — Obtém um objeto de um banco de dados InterBase
- ibase_fetch_row — Busca uma linha de um banco de dados InterBase
- ibase_field_info — Obtém informação sobre um campo
- ibase_free_event_handler — Cancela um manipulador de eventos registrado
- ibase_free_query — Libera a memória alocada para uma consulta preparada
- ibase_free_result — Libera um conjunto de resultados
- ibase_gen_id — Incrementa o gerador nomeado e retorna seu novo valor
- ibase_maintain_db — Executa um comando de manutenção no servidor de banco de dados
- ibase_modify_user — Modifica um usuário para um banco de dados seguro
- ibase_name_result — Define um nome para um conjunto de resultados
- ibase_num_fields — Obtém o número de campos em um conjunto de resultados
- ibase_num_params — Retorna o número de parâmetros em uma consulta preparada
- ibase_param_info — Retorna informação sobre um parâmetro em uma consulta preparada
- ibase_pconnect — Abre uma conexão persistente com um banco de dados InterBase
- ibase_prepare — Prepara uma consulta para ligação de parâmetros e execução posteriores
- ibase_query — Executa uma consulta em um banco de dados InterBase
- ibase_restore — Inicia uma tarefa de restauração no gerenciador de serviços e retorna imediatamente
- ibase_rollback — Reverte uma transação
- ibase_rollback_ret — Reverte uma transação sem fechá-la
- ibase_server_info — Solicita informações sobre um servidor de banco de dados
- ibase_service_attach — Conecta ao gerenciador de serviços
- ibase_service_detach — Desconecta do gerenciador de serviços
- ibase_set_event_handler — Registra uma função de retorno a ser chamada quando eventos são postados
- ibase_trans — Inicia uma transação
- ibase_wait_event — Espera por um evento ser postado pelo banco de dados

- Instalação/Configuração
  - Instalação
  - Configurações em Execução
- Constantes predefinidas
- Funções para Firebird/InterBase
  - fbird_add_user — Sinônimo de ibase_add_user
  - fbird_affected_rows — Sinônimo de ibase_affected_rows
  - fbird_backup — Sinônimo de ibase_backup
  - fbird_blob_add — Sinônimo de ibase_blob_add
  - fbird_blob_cancel — Cancela a criação de blob
  - fbird_blob_close — Sinônimo de ibase_blob_close
  - fbird_blob_create — Sinônimo de ibase_blob_create
  - fbird_blob_echo — Sinônimo de ibase_blob_echo
  - fbird_blob_get — Sinônimo de ibase_blob_get
  - fbird_blob_import — Sinônimo de ibase_blob_import
  - fbird_blob_info — Sinônimo de ibase_blob_info
  - fbird_blob_open — Sinônimo de ibase_blob_open
  - fbird_close — Sinônimo de ibase_close
  - fbird_commit — Sinônimo de ibase_commit
  - fbird_commit_ret — Sinônimo de ibase_commit_ret
  - fbird_connect — Sinônimo de ibase_connect
  - fbird_db_info — Sinônimo de ibase_db_info
  - fbird_delete_user — Sinônimo de ibase_delete_user
  - fbird_drop_db — Sinônimo de ibase_drop_db
  - fbird_errcode — Sinônimo de ibase_errcode
  - fbird_errmsg — Sinônimo de ibase_errmsg
  - fbird_execute — Sinônimo de ibase_execute
  - fbird_fetch_assoc — Sinônimo de ibase_fetch_assoc
  - fbird_fetch_object — Sinônimo de ibase_fetch_object
  - fbird_fetch_row — Sinônimo de ibase_fetch_row
  - fbird_field_info — Sinônimo de ibase_field_info
  - fbird_free_event_handler — Sinônimo de ibase_free_event_handler
  - fbird_free_query — Sinônimo de ibase_free_query
  - fbird_free_result — Sinônimo de ibase_free_result
  - fbird_gen_id — Sinônimo de ibase_gen_id
  - fbird_maintain_db — Sinônimo de ibase_maintain_db
  - fbird_modify_user — Sinônimo de ibase_modify_user
  - fbird_name_result — Sinônimo de ibase_name_result
  - fbird_num_fields — Sinônimo de ibase_num_fields
  - fbird_num_params — Sinônimo de ibase_num_params
  - fbird_param_info — Sinônimo de ibase_param_info
  - fbird_pconnect — Sinônimo de ibase_pconnect
  - fbird_prepare — Sinônimo de ibase_prepare
  - fbird_query — Sinônimo de ibase_query
  - fbird_restore — Sinônimo de ibase_restore
  - fbird_rollback — Sinônimo de ibase_rollback
  - fbird_rollback_ret — Sinônimo de ibase_rollback_ret
  - fbird_server_info — Sinônimo de ibase_server_info
  - fbird_service_attach — Sinônimo de ibase_service_attach
  - fbird_service_detach — Sinônimo de ibase_service_detach
  - fbird_set_event_handler — Sinônimo de ibase_set_event_handler
  - fbird_trans — Sinônimo de ibase_trans
  - fbird_wait_event — Sinônimo de ibase_wait_event
  - ibase_add_user — Adiciona um usuário a um banco de dados seguro
  - ibase_affected_rows — Retorna o número de linhas que foram afetados pela consulta anterior
  - ibase_backup — Inicia uma tarefa de backup no gerenciador de serviços e retorna imediatamente
  - ibase_blob_add — Adiciona dados em um blob recém criado
  - ibase_blob_cancel — Cancela a criação de blob
  - ibase_blob_close — Fecha blob
  - ibase_blob_create — Cria um novo blob para adicionar dados
  - ibase_blob_echo — Envia o conteúdo do blob para o navegador
  - ibase_blob_get — Retorna uma quantidade especificada de bytes de dados de um blob aberto
  - ibase_blob_import — Cria um blob, copia um arquivo para ele e o fecha
  - ibase_blob_info — Retorna o tamanho do blob e outras informações úteis
  - ibase_blob_open — Abre um blob para obter partes de dados
  - ibase_close — Fecha uma conexão com um banco de dados InterBase
  - ibase_commit — Confirma uma transação
  - ibase_commit_ret — Confirma uma transação sem fechá-la
  - ibase_connect — Abre uma conexão com um banco de dados
  - ibase_db_info — Solicita estatísticas sobre um banco de dados
  - ibase_delete_user — Exclui um usuário de um banco de dados seguro
  - ibase_drop_db — Exclui um banco de dados
  - ibase_errcode — Retorna um código de erro
  - ibase_errmsg — Retorna mensagens de erro
  - ibase_execute — Executa uma consulta preparada anteriormente
  - ibase_fetch_assoc — Obtém uma linha de resultado de uma consulta como um array associativo
  - ibase_fetch_object — Obtém um objeto de um banco de dados InterBase
  - ibase_fetch_row — Busca uma linha de um banco de dados InterBase
  - ibase_field_info — Obtém informação sobre um campo
  - ibase_free_event_handler — Cancela um manipulador de eventos registrado
  - ibase_free_query — Libera a memória alocada para uma consulta preparada
  - ibase_free_result — Libera um conjunto de resultados
  - ibase_gen_id — Incrementa o gerador nomeado e retorna seu novo valor
  - ibase_maintain_db — Executa um comando de manutenção no servidor de banco de dados
  - ibase_modify_user — Modifica um usuário para um banco de dados seguro
  - ibase_name_result — Define um nome para um conjunto de resultados
  - ibase_num_fields — Obtém o número de campos em um conjunto de resultados
  - ibase_num_params — Retorna o número de parâmetros em uma consulta preparada
  - ibase_param_info — Retorna informação sobre um parâmetro em uma consulta preparada
  - ibase_pconnect — Abre uma conexão persistente com um banco de dados InterBase
  - ibase_prepare — Prepara uma consulta para ligação de parâmetros e execução posteriores
  - ibase_query — Executa uma consulta em um banco de dados InterBase
  - ibase_restore — Inicia uma tarefa de restauração no gerenciador de serviços e retorna imediatamente
  - ibase_rollback — Reverte uma transação
  - ibase_rollback_ret — Reverte uma transação sem fechá-la
  - ibase_server_info — Solicita informações sobre um servidor de banco de dados
  - ibase_service_attach — Conecta ao gerenciador de serviços
  - ibase_service_detach — Desconecta do gerenciador de serviços
  - ibase_set_event_handler — Registra uma função de retorno a ser chamada quando eventos são postados
  - ibase_trans — Inicia uma transação
  - ibase_wait_event — Espera por um evento ser postado pelo banco de dados

# IBM DB2, Cloudscape e Apache Derby

# Introdução

Essas funções permitem que sejam acessados os bancos de dados IBM DB2 Universal Database, IBM Cloudscape e Apache Derby usando a DB2 Call Level Interface (DB2 CLI).

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução
- Tipos de Recurso

## Dependências

Para conectar ao IBM DB2 Universal Database para Linux, UNIX e Windows, ou IBM Cloudscape, ou Apache Derby, deve-se instalar um cliente IBM DB2 Universal Database no mesmo computador em que o PHP está sendo executado. A extensão foi desenvolvida e testada com o DB2 Versão 8.2.

Para conectar ao IBM DB2 Universal Database para z/OS ou iSeries, também é necessário o IBM DB2 Connect ou o software de gateway DRDA equivalente.

## Requisitos no Linux ou Unix

O usuário que invoca o executável PHP ou SAPI deve especificar a instância do DB2 antes de acessar essas funções. Pode-se definir o nome da instância do DB2 em php.ini usando a opção de configuração `ibm_db2.instance_name` ou pode-se obter o perfil da instância do DB2 antes de invocar o executável PHP.

Se foi criada uma instância do DB2 chamada `db2inst1` em /home/db2inst1/, por exemplo, você pode adicionar a seguinte linha ao php.ini:

    ibm_db2.instance_name=db2inst1

Se não for definida esta opção em php.ini, deve-se emitir o comando a seguir para modificar as variáveis ​​de ambiente para habilitar o acesso ao DB2:

    bash$ source /home/db2inst1/sqllib/db2profile

Para ativar o servidor Web habilitado para PHP para acessar essas funções, deve-se definir a opção de configuração `ibm_db2.instance_name` no php.ini ou obter o ambiente da instância DB2 no script de inicialização do servidor Web (normalmente /etc/init.d/httpd ou /etc/init.d/apache).

## Instalação

Para construir a extensão ibm_db2, os arquivos de cabeçalho de desenvolvimento de aplicativos do DB2 e bibliotecas devem ser instalados no sistema. O DB2 não os instala por padrão, então pode ser necessário retornar ao instalador do DB2 e adicionar esta opção. O DB2 Application Development Client inclui os arquivos de cabeçalho e está disponível gratuitamente para download no » site de suporte do IBM DB2 Universal Database.

Se os arquivos de cabeçalho e bibliotecas de desenvolvimento de aplicativos DB2 forem adicionados a um sistema operacional Linux ou Unix no qual o DB2 já estava instalado, o comando db2iupdt -e deve ser emitido para atualizar as ligações simbólicas para os arquivos de cabeçalho e bibliotecas nas instâncias do DB2.

ibm_db2 é uma extensão » PECL, portanto siga as instruções em Instalação das extensões PECL para instalar a extensão ibm_db2 para PHP. Emita o comando configure para apontar o local dos arquivos de cabeçalho e bibliotecas do DB2 da seguinte forma:

    bash$ ./configure --with-IBM_DB2=/path/to/DB2

O padrão para o comando configure é /opt/IBM/db2/V8.1.

> Nota: Nota para usuários do IIS
> Se o driver ibm_db2 estiver sendo usado com o Microsoft Internet Information Server (IIS), pode ser necessário fazer o seguinte:

> - Instale o DB2 com segurança estendida do sistema operacional.
> - Adicione o caminho do binário do PHP à variável de ambiente do sistema PATH (padrão C:\php\).
> - Crie outra variável de ambiente do sistema igual ao caminho onde o arquivo PHP.INI está localizado (ex.: PHPRC = C:\php\).
> - Adicione o IUSR_COMPUTERNAME ao grupo DB2USERS.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de Configuração de ibm_db2
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
ibm_db2.binmode | "1" | `INI_ALL` |
ibm_db2.i5_all_pconnect | "0" | `INI_SYSTEM` | Disponível a partir do ibm_db2 1.6.5.
ibm_db2.i5_allow_commit | "0" | `INI_SYSTEM` | Disponível a partir do ibm_db2 1.4.9.
ibm_db2.i5_blank_userid | "0" | `INI_SYSTEM` | Disponível a partir do ibm_db2 1.9.7.
ibm_db2.i5_char_trim | "0" | `INI_SYSTEM` | Disponível a partir do ibm_db2 2.1.0.
ibm_db2.i5_dbcs_alloc | "0" | `INI_SYSTEM` | Disponível a partir do ibm_db2 1.5.0.
ibm_db2.i5_guard_profile | "0" | `INI_SYSTEM` | Disponível a partir do ibm_db2 1.9.7.
ibm_db2.i5_ignore_userid | "0" | `INI_SYSTEM` | Disponível a partir do ibm_db2 1.8.0.
ibm_db2.i5_job_sort | "0" | `INI_SYSTEM` | Disponível a partir do ibm_db2 1.8.4.
ibm_db2.i5_log_verbose | "0" | `INI_SYSTEM` | Disponível a partir do ibm_db2 1.9.7.
ibm_db2.i5_max_pconnect | "0" | `INI_SYSTEM` | Disponível a partir do ibm_db2 1.9.7.
ibm_db2.i5_override_ccsid | "0" | `INI_SYSTEM` | Disponível a partir do ibm_db2 1.9.7.
ibm_db2.i5_servermode_subsystem | NULL | `INI_SYSTEM` | Disponível a partir do ibm_db2 1.9.7.
ibm_db2.i5_sys_naming | "0" | `INI_SYSTEM` | Disponível a partir do ibm_db2 1.9.7.
ibm_db2.instance_name | NULL | `INI_SYSTEM` | Disponível a partir do ibm_db2 1.0.2.

Aqui está uma breve explicação das diretivas de configuração.

`ibm_db2.binmode` int

  Esta opção controla o modo usado para converter de e para dados binários no aplicativo PHP.

  - 1 (DB2_BINARY)
  - 2 (DB2_CONVERT)
  - 3 (DB2_PASSTHRU)
`ibm_db2.i5_all_pconnect` int

  Esta opção força todas as conexões a serem persistentes no IBM i. Basicamente, todas as chamadas db2_connect() se tornam transparentemente chamadas db2_pconnect(). Por padrão, esta opção é `0`. Esta opção é fornecida como uma conveniência para casos em que as conexões persistentes são mais rápidas. Ela não deve ser usada em novas aplicações.

  - 0 - Conexões persistentes e não persistentes podem ser feitas.
  - 1 - Todas as conexões são persistentes.
`ibm_db2.i5_allow_commit` int

  Esta opção controla o modo de isolamento de transação usado. Por padrão, esta opção é `0`, então o controle de comprometimento não é usado. Esta opção pode ser substituída ao conectar se a chave de array `i5_commit` estiver definida no array de opções de conexão passada para db2_connect() ou db2_pconnect().

  - 0 - o controle de confirmação não é usado
  - 1 - leitura não cofirmada, leituras sujas são possíveis.
  - 2 - leitura confirmada, leituras sujas não são possíveis.
  - 3 - leituras repetíveis, leituras sujas e leituras não repetíveis não são possíveis
  - 4 - leituras serializáveis, sujas, não repetíveis e fantasmas não são possíveis
`ibm_db2.i5_blank_userid` int

  Esta opção controla se um ID de usuário em branco deve ser permitido no IBM i. Por padrão, esta opção é `0`. Ao contrário de `ibm_db2.i5_ignore_userid`, esta opção não força todos os IDs de usuário a ficarem vazios ou altera o comportamento do trabalho, mas simplesmente permite que um ID de usuário vazio seja passado, para conectar-se ao Db2 como o usuário atual.

  - 0 - Não permite que um ID de usuário em branco seja passado.
  - 1 - Permite que um ID de usuário em branco seja passado.
`ibm_db2.i5_char_trim` int

  Esta opção controla se o fim das strings são aparadas no IBM i. Como muitas tabelas usam tamanhos de coluna fixos preenchidos com espaços, isso é fornecido como uma conveniência. Por padrão, esta opção é `0`.

  - 0 - As colunas não são aparadas.
  - 1 - Espaços no final das colunas de caracteres retornadas são removidos.
`ibm_db2.i5_dbcs_alloc` int

  Esta opção afeta a estratégia de alocação de buffer interno no IBM i. Por padrão, esta opção é `0`. Quando esta opção é definida, os buffers são alocados com um tamanho muito maior, caso o banco de dados subestime o tamanho de uma string ao converter entre codificações. Esta opção usa seis vezes mais memória para buffers (para contabilizar as maiores sequências UTF-8 possíveis), mas pode ser necessária se dados truncados forem retornados.

  - 0 - Buffers de tamanho mínimo são alocados.
  - 1 - Buffers de tamanho maior são alocados.
`ibm_db2.i5_guard_profile` int

  Esta opção verifica se o perfil do usuário do banco de dados foi alternado ao conectar-se a uma conexão de banco de dados persistente no IBM i e, se sim, desconecta-se do banco de dados. Por padrão, esta opção é definida como `0`.

  - 0 - Não verifica trocas de perfil.
  - 1 - Verifica se há trocas de perfil e desconecta se houver.
`ibm_db2.i5_log_verbose` int

  Esta opção define se mensagens de diagnóstico SQL como avisos e erros são sempre enviadas para o log de erros do PHP no IBM i. Normalmente, apenas uma breve mensagem sobre falha é enviada (como "statement execute failed") para o log de erros do PHP, pois esta opção é definida como `0` por padrão. Observe que pode-se e deve-se chamar, por exemplo, db2_stmt_errormsg() manualmente como parte da verificação se as funções falharem.

  - 0 - Registra somente mensagens breves.
  - 1 - Registra mensagens de diagnóstico SQL, além das mensagens breves.
`ibm_db2.i5_ignore_userid` int

  Esta opção ignora o ID do usuário ao conectar-se ao banco de dados quando em execução no IBM i, e executa a funcionalidade SQL/CLI dentro do trabalho PHP, em vez de um trabalho separado. Por padrão, esta opção é `0`. Quando habilitada, ela não usa mais um trabalho de servidor de banco de dados separado, e sempre usa o perfil de usuário atual para o banco de dados, ignorando o nome de usuário e a senha passados ​​para db2_connect() e db2_pconnect().

  - 0 - Usa as credenciais especificadas e usa uma tarefa de servidor SQL/CLI.
  - 1 - Sempre usa credenciais em branco e executa SQL/CLI na tarefa do PHP.
`ibm_db2.i5_job_sort` int

  Controla a opção de classificação de trabalho no IBM i. Por padrão, esta opção é `0`. Isso corresponde ao atributo IBM i SQL/CLI `SQL_ATTR_CONN_SORT_SEQUENCE`.

  - 0 - Usa a opção de classificação `*HEX`, classificando por bytes.
  - 1 - Usa a sequência de classificação de tarefas definida para a tarefa PHP.
  - 2 - Usa a sequência de classificação de trabalho definida para a tarefa do banco de dados.
`ibm_db2.i5_max_pconnect` int
  Isso afetará quantas vezes uma conexão persistente pode ser reutilizada ao executar no IBM i. Por padrão, isso é definido como `0`, o que significa que uma conexão persistente sempre pode ser reutilizada. Esta opção pode ajudar a contornar problemas em um tarefa de banco de dados de longa execução (por exemplo, se um procedimento estiver vazando memória), mas obviamente não é uma correção de longo prazo.
`ibm_db2.i5_override_ccsid` int
  O CCSID PASE a ser usado para conversões de caracteres de EBCDIC no IBM i. Por padrão, este é `0`, que selecionará o CCSID do trabalho PASE padrão, que vem das configurações de localidade PASE. Por exemplo, definir isso como `1208` usará UTF-8. Isso só deve ser modificado se o CCSID da tarefa PASE não for o CCSID esperado e a localidade não puder ser modificada. Para saber mais sobre CCSIDs no IBM i, consulte a » documentação IBM. Para saber como as localidades no IBM i PASE são mapeadas para CCSIDs, consulte a » documentação IBM.
`ibm_db2.i5_sys_naming` int

  Esta opção controla o modo de nomenclatura ao conectar-se a um sistema IBM i. Por padrão, esta opção é `0`. O modo de nomenclatura afeta como os nomes são resolvidos e a sintaxe permitida para nomes. Quando definido como `0`, isso usa pontos para qualificar nomes e usa a biblioteca padrão ou ID do usuário para resolver nomes. Quando definido como `1`, isso usa barras para qualificar nomes e usa a lista de bibliotecas de tarefas para resolver nomes.

  - 0 - Uusa o modo de nomenclatura SQL ("ESQUEMA.TABELA").
  - 1 - Usa o modo de nomenclatura do sistema ("BIBLIOTECA/ARQUIVO").
  Para saber mais sobre modos de nomenclatura no IBM i, consulte a » documentação da IBM.
`ibm_db2.i5_servermode-subsystem` string
  Esta opção altera em qual subsistema as tarefas do servidor de banco de dados são executadas no IBM i. Por padrão, esta opção é `null`, portanto as tarefas serão executadas no subsistema padrão para tarefas QSQSRVR.
`ibm_db2.instance_name` string

  Em sistemas operacionais Linux e UNIX, esta opção define o nome da instância a ser usada para conexões de banco de dados catalogadas. Por padrão, esta opção é `null`. Se esta opção for definida, seu valor substitui a configuração da variável de ambiente DB2INSTANCE.

  Esta opção é ignorada em sistemas operacionais Windows.

## Tipos de Recurso

A extensão ibm_db2 retorna recursos de conexão, recursos de instrução e recursos de conjunto de resultados.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`DB2_BINARY` (int)
  Especifica que os dados binários devem ser retornados como estão. Este é o modo padrão.
`DB2_CONVERT` (int)
  Especifica que os dados binários devem ser convertidos em uma codificação hexadecimal e retornados como uma string ASCII.
`DB2_PASSTHRU` (int)
  Especifica que os dados binários devem ser convertidos em um valor `null`.
`DB2_SCROLLABLE` (int)
  Especifica um cursor rolável para um recurso de instrução. Este modo permite acesso aleatório a linhas em um conjunto de resultados, mas atualmente é suportado apenas por IBM DB2 Universal Database.
`DB2_FORWARD_ONLY` (int)
  Especifica um cursor somente para frente para um recurso de instrução. Este é o tipo de cursor padrão e é suportado em todos os servidores de banco de dados.
`DB2_PARAM_IN` (int)
  Especifica que a variável PHP deve ser vinculada como um parâmetro IN para um procedimento armazenado.
`DB2_PARAM_OUT` (int)
  Especifica que a variável PHP deve ser vinculada como um parâmetro OUT para um procedimento armazenado.
`DB2_PARAM_INOUT` (int)
  Especifica que a variável PHP deve ser vinculada como um parâmetro INOUT para um procedimento armazenado.
`DB2_PARAM_FILE` (int)
  Especifica que a coluna deve ser vinculada diretamente a um arquivo para entrada.
`DB2_AUTOCOMMIT_ON` (int)
  Especifica que a autoconfirmação deve ser ativada.
`DB2_AUTOCOMMIT_OFF` (int)
  Especifica que a autoconfirmação deve ser desativada.
`DB2_DOUBLE` (int)
  Especifica que a variável deve ser vinculada como um tipo de dados DOUBLE, FLOAT ou REAL.
`DB2_LONG` (int)
  Especifica que a variável deve ser vinculada como um tipo de dados SMALLINT, INTEGER ou BIGINT.
`DB2_CHAR` (int)
  Especifica que a variável deve ser vinculada como um tipo de dado CHAR ou VARCHAR.
`DB2_CASE_NATURAL` (int)
  Especifica que os nomes das colunas serão retornados em suas maiúsculas e minúsculas naturais.
`DB2_CASE_LOWER` (int)
  Especifica que os nomes das colunas serão retornados em letras minúsculas.
`DB2_CASE_UPPER` (int)
  Especifica que os nomes das colunas serão retornados em letras maiúsculas.
`DB2_DEFERRED_PREPARE_ON` (int)
  Especifica que a preparação adiada deve ser ativada para o recurso de instrução especificado.
`DB2_DEFERRED_PREPARE_OFF` (int)
  Especifica que a preparação adiada deve ser desativada para o recurso de instrução especificado.

# Funções de IBM DB2

# db2_autocommit

(PECL ibm_db2 >= 1.0.0)

db2_autocommit — Retorna ou define o estado AUTOCOMMIT para uma conexão de banco de dados

### Descrição

function db2_autocommit(resource `$connection`, int `$value` = ?): int|bool

Define ou obtém o comportamento AUTOCOMMIT do recurso de conexão especificado.

### Parâmetros

`connection`
  Uma variável de recurso de conexão de banco de dados válida, conforme retornada de db2_connect() ou db2_pconnect().
`value`

  Uma das seguintes constantes:

  `DB2_AUTOCOMMIT_OFF`
    Desativa o AUTOCOMMIT.
  `DB2_AUTOCOMMIT_ON`
    Ativa o AUTOCOMMIT.

### Valor Retornado

Quando db2_autocommit() recebe apenas o parâmetro `connection`, ele retorna o estado atual de AUTOCOMMIT para a conexão solicitada como um valor inteiro. Um valor de `DB2_AUTOCOMMIT_OFF` indica que AUTOCOMMIT está desligado, enquanto um valor de `DB2_AUTOCOMMIT_ON` indica que AUTOCOMMIT está ligado.

Quando db2_autocommit() recebe o parâmetro `connection` e o parâmetro `autocommit`, ele tenta definir o estado AUTOCOMMIT da conexão solicitada para o estado correspondente. Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Recuperando o valor AUTOCOMMIT para uma conexão

No exemplo a seguir, uma conexão que foi criada com AUTOCOMMIT desativado é testada com a função db2_autocommit().

    <?php
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF);
    $conn = db2_connect($database, $user, $password, $options);
    $ac = db2_autocommit($conn);
    if ($ac == DB2_AUTOCOMMIT_OFF) {
        print "$ac -- AUTOCOMMIT está desativado.";
    } else {
        print "$ac -- AUTOCOMMIT está ativado.";
    }
    ?>

O exemplo acima produzirá:

    0 -- AUTOCOMMIT está desativado.

Exemplo #2 Definindo o valor AUTOCOMMIT para uma conexão

No exemplo a seguir, uma conexão que foi inicialmente criada com AUTOCOMMIT desativado tem seu comportamento alterado para ativar AUTOCOMMIT.

    <?php
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF);
    $conn = db2_connect($database, $user, $password, $options);

    // Ativa o AUTOCOMMIT
    $rc = db2_autocommit($conn, DB2_AUTOCOMMIT_ON);
    if ($rc) {
        print "Ativação do AUTOCOMMIT bem sucedida.\n";
    }

    // Verifica o estado do AUTOCOMMIT
    $ac = db2_autocommit($conn);
    if ($ac == DB2_AUTOCOMMIT_OFF) {
        print "$ac -- AUTOCOMMIT está desativado.";
    } else {
        print "$ac -- AUTOCOMMIT está ativado.";
    }
    ?>

O exemplo acima produzirá:

    Ativação do AUTOCOMMIT bem sucedida.
    1 -- AUTOCOMMIT está ativado.

### Veja Também

- db2_connect() - Retorna uma conexão com um banco de dados
- db2_pconnect() - Retorna uma conexão persistente a um banco de dados

# db2_bind_param

(PECL ibm_db2 >= 1.0.0)

db2_bind_param — Vincula uma variável PHP a um parâmetro de instrução SQL

### Descrição

function db2_bind_param(
resource `$stmt`,
int `$parameter_number`,
string `$variable_name`,
int `$parameter_type` = `DB2_PARAM_IN`,
int `$data_type` = 0,
int `$precision` = -1,
int `$scale` = 0
): bool

Vincula uma variável PHP a um parâmetro de instrução SQL em um recurso de instrução retornado por db2_prepare(). Esta função fornece mais controle sobre o tipo de parâmetro, tipo de dados, precisão e escala para o parâmetro do que simplesmente passar a variável como parte do array de entrada opcional para db2_execute().

### Parâmetros

`stmt`
  Uma instrução preparada retornada de db2_prepare().
`parameter_number`
  Especifica a posição, indexada a partir de 1, do parâmetro na instrução preparada.
`variable_name`
  Uma string especificando o nome da variável PHP a ser vinculada ao parâmetro especificado por `parameter_number`.
`parameter_type`
  Uma constante especificando se a variável PHP deve ser vinculada ao parâmetro SQL como um parâmetro de entrada (`DB2_PARAM_IN`), um parâmetro de saída (`DB2_PARAM_OUT`) ou como um parâmetro que aceita entrada e retorna saída (`DB2_PARAM_INOUT`). Para evitar sobrecarga de memória, pode-se também especificar `DB2_PARAM_FILE` para vincular a variável PHP ao nome de um arquivo que contém dados de objeto grande (BLOB, CLOB ou DBCLOB).
`data_type`
  Uma constante especificando o tipo de dados SQL como o qual a variável PHP deverá ser vinculada: uma das constantes `DB2_BINARY`, `DB2_CHAR`, `DB2_DOUBLE` ou `DB2_LONG`.
`precision`
  Especifica a precisão com a qual a variável deve ser vinculada ao banco de dados. Este parâmetro também pode ser usado para recuperar valores de saída XML de procedimentos armazenados. Um valor não negativo especifica o tamanho máximo dos dados XML que serão recuperados do banco de dados. Se este parâmetro não for usado, um padrão de 1 MB será assumido para recuperar o valor de saída XML do procedimento armazenado.
`scale`
  Especifica a escala com a qual a variável deve ser vinculada ao banco de dados.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Vinculando variáveis ​​PHP a uma instrução preparada

A instrução SQL no exemplo a seguir usa dois parâmetros de entrada na cláusula WHERE. Chamamos db2_bind_param() para vincular duas variáveis ​​PHP aos parâmetros SQL correspondentes. Observe que as variáveis ​​PHP não precisam ser declaradas ou atribuídas antes da chamada a db2_bind_param(); no exemplo, `$lower_limit` recebe um valor antes da chamada a db2_bind_param(), mas `$upper_limit` recebe um valor após a chamada a db2_bind_param(). As variáveis ​​devem ser vinculadas e, para parâmetros que aceitam entrada, devem ter qualquer valor atribuído, antes de chamar db2_execute().

    <?php

    $sql = 'SELECT name, breed, weight FROM animals
        WHERE weight > ? AND weight < ?';
    $conn = db2_connect($database, $user, $password);
    $stmt = db2_prepare($conn, $sql);

    // É possível declarar a variável antes de chamar db2_bind_param()
    $lower_limit = 1;

    db2_bind_param($stmt, 1, "lower_limit", DB2_PARAM_IN);
    db2_bind_param($stmt, 2, "upper_limit", DB2_PARAM_IN);

    // Também é possível declarar a variável após chamar db2_bind_param()
    $upper_limit = 15.0;

    if (db2_execute($stmt)) {
        while ($row = db2_fetch_array($stmt)) {
            print "{$row[0]}, {$row[1]}, {$row[2]}\n";
        }
    }
    ?>

O exemplo acima produzirá:

    Pook, cat, 3.2
    Rickety Ride, goat, 9.7
    Peaches, dog, 12.3

Exemplo #2 Chamando procedimentos armazenados com parâmetros IN e OUT

O procedimento armazenado match_animal no exemplo a seguir aceita três parâmetros diferentes:

1. um parâmetro de entrada (IN) que aceita o nome do primeiro animal como entrada
2. um parâmetro de entrada-saída (INOUT) que aceita o nome do segundo animal como entrada e retorna a string `TRUE` se um animal no banco de dados corresponder a ele
3. um parâmetro de saída (OUT) que retorna a soma do peso dos dois animais identificados

Além disso, o procedimento armazenado retorna um conjunto de resultados consistindo de animais listados em ordem alfabética começando no animal correspondente ao valor de entrada do primeiro parâmetro e terminando no animal correspondente ao valor de entrada do segundo parâmetro.

    <?php

    $sql = 'CALL match_animal(?, ?, ?)';
    $conn = db2_connect($database, $user, $password);
    $stmt = db2_prepare($conn, $sql);

    $name = "Peaches";
    $second_name = "Rickety Ride";
    $weight = 0;

    db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
    db2_bind_param($stmt, 2, "second_name", DB2_PARAM_INOUT);
    db2_bind_param($stmt, 3, "weight", DB2_PARAM_OUT);

    print "Valores dos parâmetros vinculados _antes_ de CALL:\n";
    print "  1: {$name} 2: {$second_name} 3: {$weight}\n\n";

    if (db2_execute($stmt)) {
        print "Valores dos parâmetros vinculados _after_ CALL:\n";
        print "  1: {$name} 2: {$second_name} 3: {$weight}\n\n";

        print "Resultados:\n";
        while ($row = db2_fetch_array($stmt)) {
            print "  {$row[0]}, {$row[1]}, {$row[2]}\n";
        }
    }
    ?>

O exemplo acima produzirá:

    Valores dos parâmetros vinculados _antes_ de CALL:
      1: Peaches 2: Rickety Ride 3: 0

    Valores dos parâmetros vinculados _depois_ de CALL:
      1: Peaches 2: TRUE 3: 22

    Resultados:
      Peaches, dog, 12.3
      Pook, cat, 3.2
      Rickety Ride, goat, 9.7

Exemplo #3 Inserindo um objeto binário grande (BLOB) diretamente de um arquivo

Os dados para objetos grandes são normalmente armazenados em arquivos, como documentos XML ou arquivos de áudio. Em vez de ler um arquivo inteiro em uma variável PHP e, em seguida, vincular essa variável PHP a uma instrução SQL, é possível evitar sobrecarga de memória vinculando o arquivo diretamente ao parâmetro de entrada da instrução SQL. O exemplo a seguir demonstra como vincular um arquivo diretamente a uma coluna BLOB.

    <?php
    $stmt = db2_prepare($conn, "INSERT INTO animal_pictures(picture) VALUES (?)");

    $picture = "/opt/albums/spook/grooming.jpg";
    $rc = db2_bind_param($stmt, 1, "picture", DB2_PARAM_FILE);
    $rc = db2_execute($stmt);
    ?>

### Veja Também

- db2_execute() - Executa uma instrução SQL preparada
- db2_prepare() - Prepara uma instrução SQL para ser executada

# db2_client_info

(PECL ibm_db2 >= 1.1.1)

db2_client_info — Retorna um objeto com propriedades que descrevem o cliente do banco de dados DB2

### Descrição

function db2_client_info(resource `$connection`): stdClass|false

Esta função retorna um objeto com propriedades somente leitura que retornam informações sobre o cliente do banco de dados DB2. A tabela a seguir lista as propriedades do cliente DB2:

DB2 client properties
Nome da propriedade | Tipo de retorno | Descrição
--- | --- | ---
APPL_CODEPAGE | int | A página de código da aplicação.
CONN_CODEPAGE | int | A página de código para a conexão atual.
DATA_SOURCE_NAME | string | O nome da fonte de dados (DSN) usado para criar a conexão atual com o banco de dados.
DRIVER_NAME | string | O nome da biblioteca que implementa a especificação DB2 Call Level Interface (CLI).
DRIVER_ODBC_VER | string | A versão do ODBC que o cliente DB2 suporta. Isso retorna uma string "MM.mm" onde MM é a versão principal e mm é a versão secundária. O cliente DB2 sempre retorna "03.51".
DRIVER_VER | string | A versão do cliente, na forma de uma string "MM.mm.uuuu" onde MM é a versão principal, mm é a versão secundária, e uuuu é a atualização. Por exemplo, "08.02.0001" representa versão principal 8, versão secundária 2, atualização 1.
ODBC_SQL_CONFORMANCE | string | O nível de gramática ODBC SQL suportado pelo cliente: MINIMUM Suporta a gramática mínima do ODBC SQL. CORE Suporta a gramática básica do ODBC SQL. EXTENDED Suporta gramática ODBC SQL estendida.
ODBC_VER | string | A versão do ODBC que o gerenciador de driver ODBC suporta. Isso retorna uma string "MM.mm.rrrr" onde MM é a versão principal, mm é a versão secundária e rrrr é o lançamento. O cliente DB2 sempre retorna "03.01.0000".

### Parâmetros

`connection`
  Especifica uma conexão de cliente DB2 ativa.

### Valor Retornado

Retorna um objeto em uma chamada bem-sucedida, ou `false` em caso de falha

### Exemplos

Exemplo #1 Um exemplo de db2_client_info()

Para recuperar informações sobre o cliente, deve ser passado um recurso de conexão de banco de dados válido para db2_client_info().

    <?php
    $conn = db2_connect( 'SAMPLE', 'db2inst1', 'ibmdb2' );
    $client = db2_client_info( $conn );

    if ($client) {
        echo "DRIVER_NAME: ";           var_dump( $client->DRIVER_NAME );
        echo "DRIVER_VER: ";            var_dump( $client->DRIVER_VER );
        echo "DATA_SOURCE_NAME: ";      var_dump( $client->DATA_SOURCE_NAME );
        echo "DRIVER_ODBC_VER: ";       var_dump( $client->DRIVER_ODBC_VER );
        echo "ODBC_VER: ";              var_dump( $client->ODBC_VER );
        echo "ODBC_SQL_CONFORMANCE: ";  var_dump( $client->ODBC_SQL_CONFORMANCE );
        echo "APPL_CODEPAGE: ";         var_dump( $client->APPL_CODEPAGE );
        echo "CONN_CODEPAGE: ";         var_dump( $client->CONN_CODEPAGE );
    }
    else {
        echo "Erro ao recuperar informações do cliente.
         Talvez sua conexão com o banco de dados seja inválida.";
    }
    db2_close($conn);

    ?>

O exemplo acima produzirá:

    DRIVER_NAME: string(8) "libdb2.a"
    DRIVER_VER: string(10) "08.02.0001"
    DATA_SOURCE_NAME: string(6) "SAMPLE"
    DRIVER_ODBC_VER: string(5) "03.51"
    ODBC_VER: string(10) "03.01.0000"
    ODBC_SQL_CONFORMANCE: string(8) "EXTENDED"
    APPL_CODEPAGE: int(819)
    CONN_CODEPAGE: int(819)

### Veja Também

- db2_server_info() - Retorna um objeto com propriedades que descrevem o servidor de banco de dados DB2

# db2_close

(PECL ibm_db2 >= 1.0.0)

db2_close — Fecha uma conexão de banco de dados

### Descrição

function db2_close(resource `$connection`): bool

Esta função fecha uma conexão de cliente DB2 criada com db2_connect() e retorna os recursos correspondentes para o servidor de banco de dados.

Se houver tentativa de fechar uma conexão de cliente DB2 persistente criada com db2_pconnect(), a solicitação de fechamento será ignorada e a conexão de cliente DB2 persistente permanecerá disponível para o próximo chamador.

### Parâmetros

`connection`
  Especifica uma conexão de cliente DB2 ativa.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Fechando uma conexão

O exemplo a seguir demonstra uma tentativa bem-sucedida de fechar uma conexão com um banco de dados IBM DB2, Cloudscape ou Apache Derby.

    <?php
    $conn = db2_connect('SAMPLE', 'db2inst1', 'ibmdb2');
    $rc = db2_close($conn);
    if ($rc) {
        echo "A conexão foi fechada com sucesso.";
    }
    ?>

O exemplo acima produzirá:

    A conexão foi fechada com sucesso.

### Veja Também

- db2_connect() - Retorna uma conexão com um banco de dados
- db2_pclose() - Fecha uma conexão persistente a um banco de dados
- db2_pconnect() - Retorna uma conexão persistente a um banco de dados

# db2_column_privileges

(PECL ibm_db2 >= 1.0.0)

db2_column_privileges — Retorna um conjunto de resultados listando as colunas e privilégios associados para uma tabela

### Descrição

function db2_column_privileges(
resource `$connection`,
?string `$qualifier` = `null`,
?string `$schema` = `null`,
?string `$table_name` = `null`,
?string `$column_name` = `null`
): resource

Retorna um conjunto de resultados listando as colunas e privilégios associados para uma tabela.

### Parâmetros

`connection`
  Uma conexão válida com um banco de dados IBM DB2, Cloudscape ou Apache Derby.
`qualifier`
  Um qualificador para bancos de dados DB2 em execução em servidores OS/390 ou z/OS. Para outros bancos de dados, passe `null` ou uma string vazia.
`schema`
  O esquema que contém as tabelas. Para corresponder a todos os esquemas, passe `null` ou uma string vazia.
`table_name`
  O nome da tabela ou view. Para corresponder a todas as tabelas no banco de dados, passe `null` ou uma string vazia.
`column_name`
  O nome da coluna. Para corresponder a todas as colunas na tabela, passe `null` ou uma string vazia.

### Valor Retornado

Retorna um recurso de instrução com um conjunto de resultados contendo linhas descrevendo os privilégios de coluna para colunas que correspondem aos parâmetros especificados. As linhas são compostas das seguintes colunas:

Nome da coluna | Descrição
--- | ---
TABLE_CAT | Nome do catálogo. O valor é NULL se esta tabela não tiver catálogos.
TABLE_SCHEM | Nome do esquema.
TABLE_NAME | Nome da tabela ou visualização.
COLUMN_NAME | Nome da coluna.
GRANTOR | ID de autorização do usuário que concedeu o privilégio.
GRANTEE | ID de autorização do usuário a quem o privilégio foi concedido.
PRIVILEGE | O privilégio da coluna.
IS_GRANTABLE | Se o beneficiário tem permissão para conceder esse privilégio a outros usuários.

### Veja Também

- db2_columns() - Retorna um conjunto de resultados listando as colunas e metadados associados para uma tabela
- db2_foreign_keys() - Retorna um conjunto de resultados listando as chaves estrangeiras para uma tabela
- db2_primary_keys() - Retorna um conjunto de resultados listando as chaves primárias para uma tabela
- db2_procedure_columns() - Retorna um conjunto de resultados listando os parâmetros do procedimento armazenado
- db2_procedures() - Retorna um conjunto de resultados listando os procedimentos armazenados registrados em um banco de dados
- db2_special_columns() - Retorna um conjunto de resultados listando as colunas de identificador de linha exclusivo para uma tabela
- db2_statistics() - Retorna um conjunto de resultados listando o índice e as estatísticas de uma tabela
- db2_table_privileges() - Retorna um conjunto de resultados listando as tabelas e privilégios associados em um banco de dados
- db2_tables() - Retorna um conjunto de resultados listando as tabelas e metadados associados em um banco de dados

# db2_columns

(PECL ibm_db2 >= 1.0.0)

db2_columns — Retorna um conjunto de resultados listando as colunas e metadados associados para uma tabela

### Descrição

function db2_columns(
resource `$connection`,
?string `$qualifier` = `null`,
?string `$schema` = `null`,
?string `$table_name` = `null`,
?string `$column_name` = `null`
): resource

Retorna um conjunto de resultados listando as colunas e metadados associados para uma tabela.

### Parâmetros

`connection`
  Uma conexão válida com um banco de dados IBM DB2, Cloudscape ou Apache Derby.
`qualifier`
  Um qualificador para bancos de dados DB2 em execução em servidores OS/390 ou z/OS. Para outros bancos de dados, passe `null` ou uma string vazia.
`schema`
  O esquema que contém as tabelas. Para corresponder a todos os esquemas, passe `'%'`.
`table_name`
  O nome da tabela ou view. Para corresponder a todas as tabelas no banco de dados, passe `null` ou uma string vazia.
`column_name`
  O nome da coluna. Para corresponder a todas as colunas na tabela, passe `null` ou uma string vazia.

### Valor Retornado

Retorna um recurso de instrução com um conjunto de resultados contendo linhas descrevendo as colunas que correspondem aos parâmetros especificados. As linhas são compostas pelas seguintes colunas:

Nome da coluna | Descrição
--- | ---
TABLE_CAT | Nome do catálogo. O valor é NULL se esta tabela não tiver catálogos.
TABLE_SCHEM | Nome do esquema.
TABLE_NAME | Nome da tabela ou visualização.
COLUMN_NAME | Nome da coluna.
DATA_TYPE | O tipo de dados SQL para a coluna representada como um valor inteiro.
TYPE_NAME | Uma string que representa o tipo de dados da coluna.
COLUMN_SIZE | Um valor inteiro que representa o tamanho da coluna.
BUFFER_LENGTH | Número máximo de bytes necessários para armazenar dados desta coluna.
DECIMAL_DIGITS | A escala da coluna, ou `null` onde a escala não é aplicável.
NUM_PREC_RADIX | Um valor inteiro de `10` (representando um tipo de dado numérico exato), `2` (representando um tipo de dado numérico aproximado) ou `null` (representando um tipo de dado para o qual radix não é aplicável).
NULLABLE | Um valor inteiro que representa se a coluna é anulável ou não.
REMARKS | Descrição da coluna.
COLUMN_DEF | Valor padrão para a coluna.
SQL_DATA_TYPE | Um valor inteiro que representa o tamanho da coluna.
SQL_DATETIME_SUB | Retorna um valor inteiro que representa um código de subtipo de data e hora, ou `null` para tipos de dados SQL aos quais isso não se aplica.
CHAR_OCTET_LENGTH | Comprimento máximo em octetos para uma coluna de tipo de dados de caractere, que corresponde a COLUMN_SIZE para dados de conjunto de caracteres de byte único ou `null` para tipos de dados não caracteres.
ORDINAL_POSITION | A posição, indexada a partir de 1, da coluna na tabela.
IS_NULLABLE | Uma string onde 'YES' significa que a coluna é anulável e 'NO' significa que a coluna não é anulável.

### Veja Também

- db2_column_privileges() - Retorna um conjunto de resultados listando as colunas e privilégios associados para uma tabela
- db2_foreign_keys() - Retorna um conjunto de resultados listando as chaves estrangeiras para uma tabela
- db2_primary_keys() - Retorna um conjunto de resultados listando as chaves primárias para uma tabela
- db2_procedure_columns() - Retorna um conjunto de resultados listando os parâmetros do procedimento armazenado
- db2_procedures() - Retorna um conjunto de resultados listando os procedimentos armazenados registrados em um banco de dados
- db2_special_columns() - Retorna um conjunto de resultados listando as colunas de identificador de linha exclusivo para uma tabela
- db2_statistics() - Retorna um conjunto de resultados listando o índice e as estatísticas de uma tabela
- db2_table_privileges() - Retorna um conjunto de resultados listando as tabelas e privilégios associados em um banco de dados
- db2_tables() - Retorna um conjunto de resultados listando as tabelas e metadados associados em um banco de dados

# db2_commit

(PECL ibm_db2 >= 1.0.0)

db2_commit — Confirma uma transação

### Descrição

function db2_commit(resource `$connection`): bool

Confirma uma transação em andamento no recurso de conexão especificado e inicia uma nova transação. Os aplicativos PHP normalmente usam o modo AUTOCOMMIT por padrão, então db2_commit() não é necessário, a menos que AUTOCOMMIT tenha sido desativado para o recurso de conexão.

### Parâmetros

`connection`
  Uma variável de recurso de conexão de banco de dados válida, conforme retornada de db2_connect() ou db2_pconnect().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- db2_autocommit() - Retorna ou define o estado AUTOCOMMIT para uma conexão de banco de dados
- db2_rollback() - Reverte uma transação

# db2_conn_error

(PECL ibm_db2 >= 1.0.0)

db2_conn_error — Retorna uma string contendo o SQLSTATE retornado pela última tentativa de conexão

### Descrição

function db2_conn_error(?resource `$connection` = `null`): string

db2_conn_error() retorna um valor SQLSTATE representando o motivo da falha da última tentativa de conexão com um banco de dados. Como db2_connect() retorna `false` no caso de uma falha na tentativa de conexão, não se passa nenhum parâmetro para db2_conn_error() para recuperar o valor SQLSTATE.

Se, no entanto, a conexão foi bem-sucedida, mas se torna inválida ao longo do tempo, pode ser passado o parâmetro `connection` para recuperar o valor SQLSTATE para uma conexão específica.

Para saber o que o valor SQLSTATE significa, pode ser emitido o seguinte comando em um prompt do Processador de Linha de Comando do DB2: `db2 '? `sqlstate-value`'`. Também pode ser chamada a função db2_conn_errormsg() para recuperar uma mensagem de erro explícita e o valor SQLCODE associado.

### Parâmetros

`connection`
  Um recurso de conexão associado a uma conexão que inicialmente foi bem-sucedida, mas que com o tempo se tornou inválida.

### Valor Retornado

Retorna o valor SQLSTATE resultante de uma tentativa de conexão com falha. Retorna uma string vazia se não houver erro associado à última tentativa de conexão.

### Exemplos

Exemplo #1 Recuperando um valor SQLSTATE para uma tentativa de conexão com falha

O exemplo a seguir demonstra como retornar um valor SQLSTATE após passar deliberadamente parâmetros inválidos para db2_connect().

    <?php
    $conn = db2_connect('nome_invalido', 'usuario_invalido', 'senha_invalida');
    if (!$conn) {
        print "Valor SQLSTATE: " . db2_conn_error();
    }
    ?>

O exemplo acima produzirá:

    Valor SQLSTATE: 08001

### Veja Também

- db2_conn_errormsg() - Retorna a última mensagem de erro de conexão e o valor SQLCODE
- db2_connect() - Retorna uma conexão com um banco de dados
- db2_stmt_error() - Retorna uma string contendo o SQLSTATE retornado por uma instrução SQL
- db2_stmt_errormsg() - Retorna uma string contendo a última mensagem de erro da instrução SQL

# db2_conn_errormsg

(PECL ibm_db2 >= 1.0.0)

db2_conn_errormsg — Retorna a última mensagem de erro de conexão e o valor SQLCODE

### Descrição

function db2_conn_errormsg(?resource `$connection` = `null`): string

db2_conn_errormsg() retorna uma mensagem de erro e um valor SQLCODE representando o motivo da falha da última tentativa de conexão com o banco de dados. Como db2_connect() retorna `false` no caso de uma falha na tentativa de conexão, não deve ser passado nenhum parâmetro para db2_conn_errormsg() para recuperar a mensagem de erro associada e o valor SQLCODE.

Se, no entanto, a conexão foi bem-sucedida, mas se torna inválida ao longo do tempo, pode ser passado o parâmetro `connection` para recuperar a mensagem de erro associada e o valor SQLCODE para uma conexão específica.

### Parâmetros

`connection`
  Um recurso de conexão associado a uma conexão que inicialmente foi bem-sucedida, mas que com o tempo se tornou inválida.

### Valor Retornado

Retorna uma string contendo a mensagem de erro e o valor SQLCODE resultante de uma tentativa de conexão com falha. Se não houver erro associado à última tentativa de conexão, db2_conn_errormsg() retornará uma string vazia.

### Exemplos

Exemplo #1 Recuperando a mensagem de erro retornada por uma tentativa de conexão com falha

O exemplo a seguir demonstra como retornar uma mensagem de erro e valor SQLCODE após passar deliberadamente parâmetros inválidos para db2_connect().

    <?php
    $conn = db2_connect('nome_invalido', 'usuario_invalido', 'senha_invalida');
    if (!$conn) {
        print db2_conn_errormsg();
    }
    ?>

O exemplo acima produzirá:

    [IBM][CLI Driver] SQL1013N  The database alias name
    or database name "NOME_INVALIDO" could not be found.  SQLSTATE=42705
     SQLCODE=-1013

### Veja Também

- db2_conn_error() - Retorna uma string contendo o SQLSTATE retornado pela última tentativa de conexão
- db2_connect() - Retorna uma conexão com um banco de dados
- db2_stmt_error() - Retorna uma string contendo o SQLSTATE retornado por uma instrução SQL
- db2_stmt_errormsg() - Retorna uma string contendo a última mensagem de erro da instrução SQL

# db2_connect

(PECL ibm_db2 >= 1.0.0)

db2_connect — Retorna uma conexão com um banco de dados

### Descrição

function db2_connect(
string `$database`,
?string `$username`,
?string `$password`,
array `$options` = []
): resource|false

Cria uma nova conexão com um banco de dados IBM DB2 Universal Database, IBM Cloudscape ou Apache Derby.

### Parâmetros

`database`
  Para uma conexão catalogada com um banco de dados, `database` representa o apelido do banco de dados no catálogo do cliente DB2.

  Para uma conexão não catalogada com um banco de dados, `database` representa uma string de conexão completa no seguinte formato:

      DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=username;PWD=password;

  > Nota:

  > Ao conectar-se ao Db2 no IBM i, o sistema subjacente chama » SQLDriverConnect, que aceita apenas DSN, UID e PWD para a » string de conexão. Assim:

  >     DSN=database;UID=username;PWD=password;

  onde os parâmetros representam os seguintes valores:
  `database`
    O nome do banco de dados.
  `hostname`
    O nome do host ou endereço IP do servidor de banco de dados.
  `port`
    A porta TCP/IP na qual o banco de dados está escutando solicitações.
  `username`
    O nome de usuário com o qual a conexão ao banco de dados é realizada.
  `password`
    A senha com a qual a conexão ao banco de dados é realizada.
`username`
  O nome de usuário com o qual a conexão ao banco de dados é realizada. Para conexões não catalogadas, deve ser passado um valor `null` ou uma string vazia.
`password`
  A senha com a qual a conexão ao banco de dados é realizada. Para conexões não catalogadas, deve ser passado um valor `null` ou uma string vazia.
`options`

  Um array associativo de opções de conexão que afetam o comportamento da conexão, onde chaves válidas do array incluem:

  `autocommit`
    Passar o valor `DB2_AUTOCOMMIT_ON` ativa a autoconfirmação para este identificador de conexão. Passar o valor `DB2_AUTOCOMMIT_OFF` desativa a autoconfirmação para este identificador de conexão.
  `DB2_ATTR_CASE`
    Passar o valor `DB2_CASE_NATURAL` especifica que os nomes das colunas são retornados em maiúsculas e minúsculas. Passar o valor `DB2_CASE_LOWER` especifica que os nomes das colunas são retornados em letras minúsculas. Passar o valor `DB2_CASE_UPPER` especifica que os nomes das colunas são retornados em letras maiúsculas.
  `CURSOR`
    Passar o valor `DB2_FORWARD_ONLY` especifica um cursor somente de avanço para um recurso de instrução. Este é o tipo de cursor padrão e é suportado em todos os servidores de banco de dados. Passar o valor `DB2_SCROLLABLE` especifica um cursor rolável para um recurso de instrução. Este modo permite acesso aleatório a linhas em um conjunto de resultados, mas atualmente é suportado apenas pelo IBM DB2 Universal Database.

  A nova opção a seguir está disponível no ibm_db2 versão 1.7.0 e posteriores.

  `trustedcontext`
    Passar o valor DB2_TRUSTED_CONTEXT_ENABLE ativa o contexto confiável para este identificador de conexão. Este parâmetro não pode ser definido usando db2_set_option(). Esta chave funciona somente se o banco de dados estiver catalogado (mesmo se o banco de dados for local), ou se você especificar o DSN completo ao criar a conexão. Para catalogar o banco de dados, use os seguintes comandos:

        db2 catalog tcpip node loopback remote <SERVERNAME> server <SERVICENAME>
        db2 catalog database <LOCALDBNAME> as <REMOTEDBNAME> at node loopback
        db2 "update dbm cfg using svcename <SERVICENAME>"
        db2set DB2COMM=TCPIP

  As seguintes novas opções do i5/OS estão disponíveis no ibm_db2 versão 1.5.1 e posteriores.

  `i5_lib`
    Um valor de caractere que indica a biblioteca padrão que será usada para resolver referências de arquivo não qualificadas. Isso não é válido se a conexão estiver usando o modo de nomenclatura do sistema.
  `i5_naming`
    O valor `DB2_I5_NAMING_ON` ativa o modo de nomeação do sistema DB2 UDB CLI iSeries. Os arquivos são qualificados usando o delimitador de barra (/). Os arquivos não qualificados são resolvidos usando a lista de bibliotecas para o trabalho. O valor `DB2_I5_NAMING_OFF` desativa o modo de nomeação padrão do DB2 UDB CLI, que é a nomeação SQL. Os arquivos são qualificados usando o delimitador de ponto (.). Arquivos não qualificados são resolvidos usando a biblioteca padrão ou o ID do usuário atual.
  `i5_commit`

    O atributo `i5_commit` deve ser definido antes de db2_connect(). Se o valor for alterado após a conexão ter sido estabelecida, e a conexão for para uma fonte de dados remota, a alteração não terá efeito até a próxima db2_connect() bem-sucedida para o identificador de conexão.

    > Nota: A configuração php.ini `ibm_db2.i5_allow_commit`==0 ou `DB2_I5_TXN_NO_COMMIT` é o padrão, mas pode ser substituída pela opção `i5_commit`.

    `DB2_I5_TXN_NO_COMMIT` - O controle de confirmação não é usado. `DB2_I5_TXN_READ_UNCOMMITTED` - Leituras sujas, leituras não repetíveis e fantasmas são possíveis. `DB2_I5_TXN_READ_COMMITTED` - Leituras sujas não são possíveis. Leituras não repetíveis e fantasmas são possíveis. `DB2_I5_TXN_REPEATABLE_READ` - Leituras sujas e leituras não repetíveis não são possíveis. Fantasmas são possíveis. `DB2_I5_TXN_SERIALIZABLE` - As transações são serializáveis. Leituras sujas, leituras não repetíveis e fantasmas não são possíveis.
  `i5_query_optimize`
    `DB2_FIRST_IO` Todas as consultas são otimizadas com o objetivo de retornar a primeira página de saída o mais rápido possível. Este objetivo funciona bem quando a saída é controlada por um usuário que tem mais probabilidade de cancelar a consulta após visualizar a primeira página de dados de saída. Consultas codificadas com uma cláusula OPTIMIZE FOR nnn ROWS honram o objetivo especificado pela cláusula. `DB2_ALL_IO` Todas as consultas são otimizadas com o objetivo de executar a consulta inteira até a conclusão no menor tempo decorrido. Esta é uma boa opção quando a saída de uma consulta está sendo gravada em um arquivo ou relatório, ou a interface está enfileirando os dados de saída. Consultas codificadas com uma cláusula OPTIMIZE FOR nnn ROWS honram o objetivo especificado pela cláusula. Este é o padrão.
  `i5_dbcs_alloc`
    O valor `DB2_I5_DBCS_ALLOC_ON` ativa o esquema de alocação DB2 6X para o crescimento do tamanho da coluna de tradução DBCS. O valor `DB2_I5_DBCS_ALLOC_OFF` desativa o esquema de alocação DB2 6X para o crescimento do tamanho da coluna de tradução DBCS. Nota: a configuração php.ini `ibm_db2.i5_dbcs_alloc`==0 ou `DB2_I5_DBCS_ALLOC_OFF` é o padrão, mas pode ser substituída pela opção `i5_dbcs_alloc`.
  `i5_date_fmt`
    `DB2_I5_FMT_ISO` - O formato de data da Organização Internacional para Padronização (ISO) aaaa-mm-dd é usado. Este é o padrão. `DB2_I5_FMT_USA` - O formato de data dos Estados Unidos mm/dd/aaaa é usado. `DB2_I5_FMT_EUR` - O formato de data europeu dd.mm.aaaa é usado. `DB2_I5_FMT_JIS` - O formato de data do Padrão Industrial Japonês aaaa-mm-dd é usado. `DB2_I5_FMT_MDY` - O formato de data mm/dd/aaaa é usado. `DB2_I5_FMT_DMY` - O formato de data dd/mm/aaaa é usado. `DB2_I5_FMT_YMD` - O formato de data aa/mm/dd é usado. `DB2_I5_FMT_JUL` - O formato de data juliano aa/ddd é usado. `DB2_I5_FMT_JOB` - O padrão da tarefa é usado.
  `i5_date_sep`
    `DB2_I5_SEP_SLASH` - Uma barra ( / ) é usada como separador de data. Este é o padrão. `DB2_I5_SEP_DASH` - Um traço ( - ) é usado como separador de data. `DB2_I5_SEP_PERIOD` - Um ponto ( . ) é usado como separador de data. `DB2_I5_SEP_COMMA` - Uma vírgula ( , ) é usada como separador de data. `DB2_I5_SEP_BLANK` - Um espaço em branco é usado como separador de data. `DB2_I5_SEP_JOB` - O padrão da tarefa é usado.
  `i5_time_fmt`
    `DB2_I5_FMT_ISO` - O formato de horário da Organização Internacional para Padronização (ISO) hh.mm.ss é usado. Este é o padrão. `DB2_I5_FMT_USA` - O formato de horário dos Estados Unidos hh:mmxx é usado, onde xx é AM ou PM. `DB2_I5_FMT_EUR` - O formato de horário europeu hh.mm.ss é usado. `DB2_I5_FMT_JIS` - O formato de horário do Padrão Industrial Japonês hh:mm:ss é usado. `DB2_I5_FMT_HMS` - O formato hh:mm:ss é usado.
  `i5_time_sep`
    `DB2_I5_SEP_COLON` - Dois pontos ( : ) são usados ​​como separador de horário. Este é o padrão. `DB2_I5_SEP_PERIOD` - Um ponto ( . ) é usado como separador de horário. `DB2_I5_SEP_COMMA` - Uma vírgula ( , ) é usada como separador de horário. `DB2_I5_SEP_BLANK` - Um espaço em branco é usado como separador de horário. `DB2_I5_SEP_JOB` - O padrão da tarefa é usado.
  `i5_decimal_sep`
    `DB2_I5_SEP_PERIOD` - Um ponto ( . ) é usado como separador decimal. Este é o padrão. `DB2_I5_SEP_COMMA` - Uma vírgula ( , ) é usada como separador decimal. `DB2_I5_SEP_JOB` - O padrão da tarefa é usado.

  A seguinte nova opção do i5/OS está disponível no ibm_db2 versão 1.8.0 e posteriores.

  `i5_libl`
    Um valor de caractere que indica a lista de bibliotecas que será usada para resolver referências de arquivo não qualificadas. Especifique os elementos da lista de bibliotecas separados por espaços em branco 'i5_libl'=>"MINHA_BIBLIOTECA SUA_BIBLIOTECA QUALQUER_BIBLIOTECA".

    > Nota: `i5_libl` chama qsys2/qcmdexc('cmd',cmdlen), que está disponível somente no i5/OS V5R4 e posteriores.

### Valor Retornado

Retorna um recurso de identificador de conexão se a tentativa de conexão for bem-sucedida. Se a tentativa de conexão falhar, db2_connect() retorna `false`.

### Exemplos

Exemplo #1 Criando uma conexão catalogada

As conexões catalogadas exigem que você tenha catalogado previamente o banco de dados de destino por meio do Processador de Linha de Comando (CLP) do DB2 ou do Assistente de Configuração do DB2.

    <?php
    $database = 'SAMPLE';
    $user = 'db2inst1';
    $password = 'ibmdb2';

    $conn = db2_connect($database, $user, $password);

    if ($conn) {
        echo "Conexão bem-sucedida.";
        db2_close($conn);
    }
    else {
        echo "Falha na conexão.";
    }
    ?>

O exemplo acima produzirá:

    Conexão bem-sucedida.

Exemplo #2 Criando uma conexão não catalogada

Uma conexão não catalogada permite que conexão dinâmica a um banco de dados.

    <?php
    $database = 'SAMPLE';
    $user = 'db2inst1';
    $password = 'ibmdb2';
    $hostname = 'localhost';
    $port = 50000;

    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;" .
      "HOSTNAME=$hostname;PORT=$port;PROTOCOL=TCPIP;UID=$user;PWD=$password;";
    $conn = db2_connect($conn_string, '', '');

    if ($conn) {
        echo "Conexão bem-sucedida.";
        db2_close($conn);
    }
    else {
        echo "Falha na conexão.";
    }
    ?>

O exemplo acima produzirá:

    Conexão bem-sucedida.

Exemplo #3 Criando uma conexão com autoconfirmação desativado por padrão

Passar um array de opções para db2_connect() permite modificação do comportamento padrão do identificador de conexão.

    <?php
    $database = 'SAMPLE';
    $user = 'db2inst1';
    $password = 'ibmdb2';
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF);

    $conn = db2_connect($database, $user, $password, $options);

    if ($conn) {
        echo "Conexão bem-sucedida.\n";
        if (db2_autocommit($conn)) {
             echo "A autoconfirmação está ativada.\n";
        }
        else {
             echo "A autoconfirmação está desativada.\n";
        }
        db2_close($conn);
    }
    else {
        echo "Falha na conexão.";
    }
    ?>

O exemplo acima produzirá:

    Conexão bem-sucedida.
    A autoconfirmação está desativada.

Exemplo #4 Melhor desempenho do i5/OS

Para obter o melhor desempenho para uma aplicação PHP i5/OS ibm_db2 1.5.1, use o host, o ID do usuário e a senha padrão para db2_connect().

    <?php
      $library = "ADC";
      $i5 = db2_connect("", "", "", array("i5_lib"=>"qsys2"));
      $result = db2_exec($i5,
           "select * from systables where table_schema = '$library'");
      while ($row = db2_fetch_both($result)) {
         echo $row['TABLE_NAME']."</br>";
      }
      db2_close($i5);
    ?>

O exemplo acima produzirá:

    ANIMALS
    NAMES
    PICTURES

Exemplo #5 Usando contexto confiável

O exemplo a seguir mostra como habilitar o contexto confiável, alternar usuários e obter o ID do usuário atual.

    <?php

    $database = "SAMPLE";
    $hostname = "localhost";
    $port = 50000;
    $authID = "db2inst1";
    $auth_pass = "ibmdb2";

    $tc_user = "tcuser";
    $tc_pass = "tcpassword";

    $dsn = "DATABASE=$database;HOSTNAME=$hostname;PORT=$port;
      PROTOCOL=TCPIP;UID=$authID;PWD=$auth_pass;";
    $options = array ("trustedcontext" => DB2_TRUSTED_CONTEXT_ENABLE);

    $tc_conn = db2_connect($dsn, "", "", $options);
    if($tc_conn) {
        echo "Conexão confiável explícita bem-sucedida.\n";

        if(db2_get_option($tc_conn, "trustedcontext")) {
            $userBefore = db2_get_option($tc_conn, "trusted_user");

            // Faz algo como usuário 1.

            // Trocando para usuário confiável.
            $parameters = array("trusted_user" => $tc_user,
              "trusted_password" => $tcuser_pass);
            $res = db2_set_option ($tc_conn, $parameters, 1);

            $userAfter = db2_get_option($tc_conn, "trusted_user");
            // Faz algo mais como usuário confiável.

            if($userBefore != $userAfter) {
                echo "O usuário foi trocado." . "\n";
            }
        }

        db2_close($tc_conn);
    }
    else {
        echo "Conexão confiável explícita falhou.\n";
    }
    ?>

O exemplo acima produzirá:

    Conexão confiável explícita bem-sucedida.
    O usuário foi trocado.

### Veja Também

- db2_close() - Fecha uma conexão de banco de dados
- db2_pconnect() - Retorna uma conexão persistente a um banco de dados

# db2_cursor_type

(PECL ibm_db2 >= 1.0.0)

db2_cursor_type — Retorna o tipo de cursor usado por um recurso de instrução

### Descrição

function db2_cursor_type(resource `$stmt`): int

Retorna o tipo de cursor usado por um recurso de instrução. Use isso para determinar se está sendo usado um cursor somente para avanço ou um cursor rolável.

### Parâmetros

`stmt`
  Um recurso de instrução válido.

### Valor Retornado

Retorna `DB2_FORWARD_ONLY` se o recurso de instrução usar um cursor somente para avanço ou `DB2_SCROLLABLE` se o recurso de instrução usar um cursor rolável.

### Veja Também

- db2_prepare() - Prepara uma instrução SQL para ser executada

# db2_escape_string

(PECL ibm_db2 >= 1.6.0)

db2_escape_string — Usado para escapar certos caracteres

### Descrição

function db2_escape_string(string `$string_literal`): string

Adiciona barras invertidas aos caracteres especiais no argumento da string.

### Parâmetros

`string_literal`
  A string que contém caracteres especiais que precisam ser modificados. Os caracteres que são precedidos por uma barra invertida são `\x00`, `\n`, `\r`, `\`, `'`, `"` e `\x1a`.

### Valor Retornado

Retorna `string_literal` com os caracteres especiais observados acima precedidos por barras invertidas.

### Exemplos

Exemplo #1 Um exemplo de db2_escape_string()

Resultado do uso da função db2_escape_string()

    <?php

    $conn = db2_connect($database, $user, $password);

    if ($conn) {
        $str[0] = "Todos os caracteres: \x00 , \n , \r , \ , ' , \" , \x1a .";
        $str[1] = "Barra invertida (\). Aspas simples ('). Aspas duplas (\")";
        $str[2] = "O caractere NULL \0 também precisa ser escapado";
        $str[3] = "Caracteres interessantes: \x1a , \x00 .";
        $str[4] = "Nada para escapar";
        $str[5] = 200676;
        $str[6] = "";

        foreach( $str as $string ) {
            echo "db2_escape_string: " . db2_escape_string($string). "\n";
        }
    }
    ?>

O exemplo acima produzirá:

    db2_escape_string: Todos os caracteres: \0 , \n , \r , \\ , \' , \" , \Z .
    db2_escape_string: Barra invertida (\\). Aspas simples (\'). Aspas duplas (\")
    db2_escape_string: O caractere NULL \0 também precisa ser escapado
    db2_escape_string: Caracteres interessantes: \Z , \0 .
    db2_escape_string: Nada para escapar
    db2_escape_string: 200676
    db2_escape_string:

### Veja Também

- db2_prepare() - Prepara uma instrução SQL para ser executada

# db2_exec

(PECL ibm_db2 >= 1.0.0)

db2_exec — Executa uma instrução SQL diretamente

### Descrição

function db2_exec(resource `$connection`, string `$statement`, array `$options` = []): resource|false

Executa uma instrução SQL diretamente.

Se for planejado interpolar variáveis ​​PHP na instrução SQL, é necessário ter ciência que esta é uma das exposições de segurança mais comuns. Deve ser considerado chamar db2_prepare() para preparar uma instrução SQL com marcadores de parâmetro para valores de entrada. Na sequência pode ser chamada a função db2_execute() para passar os valores de entrada e evitar ataques de injeção de SQL.

Se a intenção for emitir repetidamente a mesma instrução SQL com diferentes parâmetros, podem ser chamadas as funções db2_prepare() e db2_execute() para permitir que o servidor de banco de dados reutilize o plano e aumente a eficiência do acesso ao banco de dados.

### Parâmetros

`connection`
  Uma variável de recurso de conexão de banco de dados válida, conforme retornada de db2_connect() ou db2_pconnect().
`statement`
  Uma instrução SQL. A instrução não pode conter nenhum marcador de parâmetro.
`options`
  Um array associativo contendo opções de instrução. Este parâmetro pode ser usado para solicitar um cursor rolável em servidores de banco de dados que suportam esta funcionalidade. Para uma descrição das opções de instrução válidas, consulte db2_set_option().

### Valor Retornado

Retorna um recurso de instrução se a instrução SQL foi emitida com sucesso, ou `false` se o banco de dados falhou ao executar a instrução SQL.

### Exemplos

Exemplo #1 Criando uma tabela com db2_exec()

O exemplo a seguir usa db2_exec() para emitir um conjunto de instruções DDL no processo de criação de uma tabela.

    <?php
    $conn = db2_connect($database, $user, $password);

    // Cria a tabela de teste
    $create = 'CREATE TABLE animals (id INTEGER, breed VARCHAR(32),
        name CHAR(16), weight DECIMAL(7,2))';
    $result = db2_exec($conn, $create);
    if ($result) {
        print "A tabela foi criada com sucesso.\n";
    }

    // Preenche a tabela de teste
    $animals = array(
        array(0, 'cat', 'Pook', 3.2),
        array(1, 'dog', 'Peaches', 12.3),
        array(2, 'horse', 'Smarty', 350.0),
        array(3, 'gold fish', 'Bubbles', 0.1),
        array(4, 'budgerigar', 'Gizmo', 0.2),
        array(5, 'goat', 'Rickety Ride', 9.7),
        array(6, 'llama', 'Sweater', 150)
    );

    foreach ($animals as $animal) {
        $rc = db2_exec($conn, "INSERT INTO animals (id, breed, name, weight)
          VALUES ({$animal[0]}, '{$animal[1]}', '{$animal[2]}', {$animal[3]})");
        if ($rc) {
            print "Insert... ";
        }
    }
    ?>

O exemplo acima produzirá:

    A tabela foi criada com sucesso.
    Insert... Insert... Insert... Insert... Insert... Insert... Insert...

Exemplo #2 Executando uma instrução SELECT com um cursor rolável

O exemplo a seguir demonstra como solicitar um cursor rolável para uma instrução SQL emitida por db2_exec().

    <?php
    $conn = db2_connect($database, $user, $password);
    $sql = "SELECT name FROM animals
        WHERE weight < 10.0
        ORDER BY name";
    if ($conn) {
        require_once 'prepare.inc';
        $stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
        while ($row = db2_fetch_array($stmt)) {
            print "$row[0]\n";
        }
    }
    ?>

O exemplo acima produzirá:

    Bubbles
    Gizmo
    Pook
    Rickety Ride

Exemplo #3 Retornando dados XML como um SQL ResultSet

O exemplo a seguir demonstra como trabalhar com documentos armazenados em uma coluna XML usando o banco de dados SAMPLE. Usando um pouco de SQL/XML bem simples, este exemplo retorna alguns dos nós em um documento XML em um formato SQL ResultSet com o qual a maioria dos usuários está familiarizada.

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = 'SELECT * FROM XMLTABLE(
        XMLNAMESPACES (DEFAULT \'http://posample.org\'),
        \'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
        COLUMNS
        "CID" VARCHAR (50) PATH \'@Cid\',
        "NAME" VARCHAR (50) PATH \'name\',
        "PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
        ) AS T
        WHERE NAME = \'Kathy Smith\'
        ';
    $stmt = db2_exec($conn, $query);

    while($row = db2_fetch_object($stmt)){
        printf("$row->CID     $row->NAME     $row->PHONE\n");
    }
    db2_close($conn);

    ?>

O exemplo acima produzirá:

    1000     Kathy Smith     416-555-1358
    1001     Kathy Smith     905-555-7258

Exemplo #4 Executando um "JOIN" com dados XML

O exemplo a seguir funciona com documentos armazenados em 2 colunas XML diferentes no banco de dados SAMPLE. Ele cria 2 tabelas temporárias dos documentos XML de 2 colunas diferentes e retorna um SQL ResultSet com informações sobre o status de envio para o cliente.

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = '
        SELECT A.CID, A.NAME, A.PHONE, C.PONUM, C.STATUS
        FROM
        XMLTABLE(
        XMLNAMESPACES (DEFAULT \'http://posample.org\'),
        \'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
        COLUMNS
        "CID" BIGINT PATH \'@Cid\',
        "NAME" VARCHAR (50) PATH \'name\',
        "PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
        ) as A,
        PURCHASEORDER AS B,
        XMLTABLE (
        XMLNAMESPACES (DEFAULT \'http://posample.org\'),
        \'db2-fn:xmlcolumn("PURCHASEORDER.PORDER")/PurchaseOrder\'
        COLUMNS
        "PONUM"  BIGINT PATH \'@PoNum\',
        "STATUS" VARCHAR (50) PATH \'@Status\'
        ) as C
        WHERE A.CID = B.CUSTID AND
        B.POID = C.PONUM AND
        A.NAME = \'Kathy Smith\'
    ';

    $stmt = db2_exec($conn, $query);

    while($row = db2_fetch_object($stmt)){
        printf("$row->CID     $row->NAME     $row->PHONE     $row->PONUM     $row->STATUS\n");
    }

    db2_close($conn);

    ?>

O exemplo acima produzirá:

    1001     Kathy Smith     905-555-7258     5002     Shipped

Exemplo #5 Retornando dados SQL como parte de um documento XML maior

O exemplo a seguir funciona com uma parte dos documentos PRODUCT.DESCRIPTION no banco de dados SAMPLE. Ele cria um documento XML contendo descrição do produto (dados XML) e informações de preço (dados SQL).

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = '
    SELECT
    XMLSERIALIZE(
    XMLQUERY(\'
        declare boundary-space strip;
        declare default element namespace "http://posample.org";
        <promoList> {
        for $prod in $doc/product
        where $prod/description/price < 10.00
        order by $prod/description/price ascending
        return(
            <promoitem> {
            $prod,
            <startdate> {$start} </startdate>,
            <enddate> {$end} </enddate>,
            <promoprice> {$promo} </promoprice>
            } </promoitem>
        )
        } </promoList>
    \' passing by ref DESCRIPTION AS "doc",
    PROMOSTART as "start",
    PROMOEND as "end",
    PROMOPRICE as "promo"
    RETURNING SEQUENCE)
    AS CLOB (32000))
    AS NEW_PRODUCT_INFO
    FROM PRODUCT
    WHERE PID = \'100-100-01\'
    ';

    $stmt = db2_exec($conn, $query);

    while($row = db2_fetch_array($stmt)){
        printf("$row[0]\n");
    }
    db2_close($conn);

    ?>

O exemplo acima produzirá:

    <promoList xmlns="http://posample.org">
        <promoitem>
        <product pid="100-100-01">
            <description>
                <name>Snow Shovel, Basic 22 inch</name>
                <details>Basic Snow Shovel, 22 inches wide, straight handle with D-Grip</details>
                <price>9.99</price>
                <weight>1 kg</weight>
            </description>
        </product>
        <startdate>2004-11-19</startdate>
        <enddate>2004-12-19</enddate>
        <promoprice>7.25</promoprice>
        </promoitem>
    </promoList>

### Veja Também

- db2_execute() - Executa uma instrução SQL preparada
- db2_prepare() - Prepara uma instrução SQL para ser executada

# db2_execute

(PECL ibm_db2 >= 1.0.0)

db2_execute — Executa uma instrução SQL preparada

### Descrição

function db2_execute(resource `$stmt`, array `$parameters` = []): bool

db2_execute() executa uma instrução SQL que foi preparada por db2_prepare().

Se a instrução SQL retornar um conjunto de resultados, por exemplo, uma instrução SELECT ou uma CALL para um procedimento armazenado que retorna um ou mais conjuntos de resultados, pode ser recuperada uma linha como um array a partir do recurso `stmt` usando db2_fetch_assoc(), db2_fetch_both() ou db2_fetch_array(). Como alternativa, pode ser usada a função db2_fetch_row() para mover o ponteiro do conjunto de resultados para a próxima linha e buscar uma coluna por vez dessa linha com db2_result().

Consulte db2_prepare() para uma breve discussão sobre as vantagens de usar db2_prepare() e db2_execute() em vez de db2_exec().

### Parâmetros

`stmt`
  Uma instrução preparada retornada de db2_prepare().
`parameters`
  Um array de parâmetros de entrada que correspondem a quaisquer marcadores de parâmetros contidos na instrução preparada.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Preparando e executando uma instrução SQL com marcadores de parâmetros

O exemplo a seguir prepara uma instrução INSERT que aceita quatro marcadores de parâmetros e, em seguida, itera sobre um array de arrays contendo os valores de entrada a serem passados ​​para db2_execute().

    <?php
    $pet = array(0, 'cat', 'Pook', 3.2);

    $insert = 'INSERT INTO animals (id, breed, name, weight)
        VALUES (?, ?, ?, ?)';

    $stmt = db2_prepare($conn, $insert);
    if ($stmt) {
        $result = db2_execute($stmt, $pet);
        if ($result) {
            print "Novo animal de estimação adicionado com sucesso.";
        }
    }
    ?>

O exemplo acima produzirá:

    Novo animal de estimação adicionado com sucesso.

Exemplo #2 Chamando um procedimento armazenado com um parâmetro OUT

O exemplo a seguir prepara uma instrução CALL que aceita um marcador de parâmetro representando um parâmetro OUT, vincula a variável PHP `$my_pets` ao parâmetro usando db2_bind_param(), então emite db2_execute() para executar a instrução CALL. Após a CHAMADA para o procedimento armazenado ter sido feita, o valor de `$num_pets` muda para refletir o valor retornado pelo procedimento armazenado para aquele parâmetro OUT.

    <?php
    $num_pets = 0;
    $res = db2_prepare($conn, "CALL count_my_pets(?)");
    $rc = db2_bind_param($res, 1, "num_pets", DB2_PARAM_OUT);
    $rc = db2_execute($res);
    print "I have $num_pets pets!";
    ?>

O exemplo acima produzirá:

    I have 7 pets!

Exemplo #3 Retornando dados XML como um ResultSet SQL

O exemplo a seguir demonstra como trabalhar com documentos armazenados em uma coluna XML usando o banco de dados SAMPLE. Usando um pouco de SQL/XML bem simples, este exemplo retorna alguns dos nós em um documento XML em um formato SQL ResultSet com o qual a maioria dos usuários está familiarizada.

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = 'SELECT * FROM XMLTABLE(
        XMLNAMESPACES (DEFAULT \'http://posample.org\'),
        \'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
        COLUMNS
        "CID" VARCHAR (50) PATH \'@Cid\',
        "NAME" VARCHAR (50) PATH \'name\',
        "PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
        ) AS T
        WHERE NAME = ?
        ';

    $stmt = db2_prepare($conn, $query);

    $name = 'Kathy Smith';

    if ($stmt) {
        db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
        db2_execute($stmt);

        while($row = db2_fetch_object($stmt)){
        printf("$row->CID     $row->NAME     $row->PHONE\n");
        }
    }
    db2_close($conn);

    ?>

O exemplo acima produzirá:

    1000     Kathy Smith     416-555-1358
    1001     Kathy Smith     905-555-7258

Exemplo #4 Executando um "JOIN" com dados XML

O exemplo a seguir funciona com documentos armazenados em 2 colunas XML diferentes no banco de dados SAMPLE. Ele cria 2 tabelas temporárias dos documentos XML de 2 colunas diferentes e retorna um SQL ResultSet com informações sobre o status de envio para o cliente.

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = '
    SELECT A.CID, A.NAME, A.PHONE, C.PONUM, C.STATUS
    FROM
    XMLTABLE(
    XMLNAMESPACES (DEFAULT \'http://posample.org\'),
    \'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
    COLUMNS
    "CID" BIGINT PATH \'@Cid\',
    "NAME" VARCHAR (50) PATH \'name\',
    "PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
    ) as A,
    PURCHASEORDER AS B,
    XMLTABLE (
    XMLNAMESPACES (DEFAULT \'http://posample.org\'),
    \'db2-fn:xmlcolumn("PURCHASEORDER.PORDER")/PurchaseOrder\'
    COLUMNS
    "PONUM"  BIGINT PATH \'@PoNum\',
    "STATUS" VARCHAR (50) PATH \'@Status\'
    ) as C
    WHERE A.CID = B.CUSTID AND
        B.POID = C.PONUM AND
        A.NAME = ?
    ';

    $stmt = db2_prepare($conn, $query);

    $name = 'Kathy Smith';

    if ($stmt) {
        db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
        db2_execute($stmt);

        while($row = db2_fetch_object($stmt)){
        printf("$row->CID     $row->NAME     $row->PHONE     $row->PONUM     $row->STATUS\n");
        }
    }

    db2_close($conn);

    ?>

O exemplo acima produzirá:

    1001     Kathy Smith     905-555-7258     5002     Shipped

Exemplo #5 Retornando dados SQL como parte de um documento XML maior

O exemplo a seguir funciona com uma parte dos documentos PRODUCT.DESCRIPTION no banco de dados SAMPLE. Ele cria um documento XML contendo descrição do produto (dados XML) e informações de preço (dados SQL).

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = '
    SELECT
    XMLSERIALIZE(
    XMLQUERY(\'
        declare boundary-space strip;
        declare default element namespace "http://posample.org";
        <promoList> {
        for $prod in $doc/product
        where $prod/description/price < 10.00
        order by $prod/description/price ascending
        return(
            <promoitem> {
            $prod,
            <startdate> {$start} </startdate>,
            <enddate> {$end} </enddate>,
            <promoprice> {$promo} </promoprice>
                } </promoitem>
        )
        } </promoList>
    \' passing by ref DESCRIPTION AS "doc",
    PROMOSTART as "start",
    PROMOEND as "end",
    PROMOPRICE as "promo"
    RETURNING SEQUENCE)
    AS CLOB (32000))
    AS NEW_PRODUCT_INFO
    FROM PRODUCT
    WHERE PID = ?
    ';

    $stmt = db2_prepare($conn, $query);

    $pid = "100-100-01";

    if ($stmt) {
        db2_bind_param($stmt, 1, "pid", DB2_PARAM_IN);
        db2_execute($stmt);

        while($row = db2_fetch_array($stmt)){
        printf("$row[0]\n");
        }
    }

    db2_close($conn);

    ?>

O exemplo acima produzirá:

    <promoList xmlns="http://posample.org">
        <promoitem>
        <product pid="100-100-01">
            <description>
                <name>Snow Shovel, Basic 22 inch</name>
                <details>Basic Snow Shovel, 22 inches wide, straight handle with D-Grip</details>
                <price>9.99</price>
                <weight>1 kg</weight>
            </description>
        </product>
        <startdate>2004-11-19</startdate>
        <enddate>2004-12-19</enddate>
        <promoprice>7.25</promoprice>
        </promoitem>
    </promoList>

### Veja Também

- db2_exec() - Executa uma instrução SQL diretamente
- db2_fetch_array() - Retorna um array, indexado pela posição da coluna, representando uma linha em um conjunto de resultados
- db2_fetch_assoc() - Retorna um array, indexado pelo nome da coluna, representando uma linha em um conjunto de resultados
- db2_fetch_both() - Retorna um array, indexado pelo nome da coluna e pela posição, representando uma linha em um conjunto de resultados
- db2_fetch_row() - Define o ponteiro do conjunto de resultados para a próxima linha ou linha solicitada
- db2_prepare() - Prepara uma instrução SQL para ser executada
- db2_result() - Retorna uma única coluna de uma linha no conjunto de resultados

# db2_fetch_array

(PECL ibm_db2 >= 1.0.1)

db2_fetch_array — Retorna um array, indexado pela posição da coluna, representando uma linha em um conjunto de resultados

### Descrição

function db2_fetch_array(resource `$stmt`, int `$row_number` = -1): array|false

Retorna um array, indexado pela posição da coluna, representando uma linha em um conjunto de resultados. As colunas são indexadas a partir de 0.

### Parâmetros

`stmt`
  Um recurso `stmt` válido contendo um conjunto de resultados.
`row_number`
  Solicita uma linha específica indexada em 1 do conjunto de resultados. Passar este parâmetro resulta em um aviso do PHP se o conjunto de resultados usar um cursor somente de avanço.

### Valor Retornado

Retorna um array indexado em 0 com valores de coluna indexados pela posição da coluna representando a próxima linha ou a linha solicitada no conjunto de resultados. Retorna `false` se não houver linhas restantes no conjunto de resultados, ou se a linha solicitada por `row_number` não existir no conjunto de resultados.

### Exemplos

Exemplo #1 Iterando por um cursor somente de avanço

Se db2_fetch_array() for chamada sem um número de linha específico, ela recuperará automaticamente a próxima linha no conjunto de resultados.

    <?php

    $sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
    $stmt = db2_prepare($conn, $sql);
    $result = db2_execute($stmt);

    while ($row = db2_fetch_array($stmt)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row[0], $row[1], $row[2], $row[3]);
    }
    ?>

O exemplo acima produzirá:

    0     Pook             cat                                    3.20
    5     Rickety Ride     goat                                   9.70
    2     Smarty           horse                                350.00

Exemplo #2 Recuperando linhas específicas com db2_fetch_array() a partir de um cursor rolável

Se o conjunto de resultados usar um cursor rolável, db2_fetch_array() pode ser chamada com um número de linha específico. O exemplo a seguir recupera todas as outras linhas no conjunto de resultados, começando com a segunda linha.

    <?php

    $sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
    $result = db2_exec($stmt, $sql, array('cursor' => DB2_SCROLLABLE));

    $i=2;
    while ($row = db2_fetch_array($result, $i)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row[0], $row[1], $row[2], $row[3]);
        $i = $i + 2;
    }
    ?>

O exemplo acima produzirá:

    0     Pook             cat                                    3.20
    5     Rickety Ride     goat                                   9.70
    2     Smarty           horse                                350.00

### Veja Também

- db2_fetch_assoc() - Retorna um array, indexado pelo nome da coluna, representando uma linha em um conjunto de resultados
- db2_fetch_both() - Retorna um array, indexado pelo nome da coluna e pela posição, representando uma linha em um conjunto de resultados
- db2_fetch_object() - Retorna um objeto com propriedades que representam colunas na linha buscada
- db2_fetch_row() - Define o ponteiro do conjunto de resultados para a próxima linha ou linha solicitada
- db2_result() - Retorna uma única coluna de uma linha no conjunto de resultados

# db2_fetch_assoc

(PECL ibm_db2 >= 1.0.0)

db2_fetch_assoc — Retorna um array, indexado pelo nome da coluna, representando uma linha em um conjunto de resultados

### Descrição

function db2_fetch_assoc(resource `$stmt`, int `$row_number` = -1): array|false

Retorna um array, indexado pelo nome da coluna, representando uma linha em um conjunto de resultados.

### Parâmetros

`stmt`
  Um recurso `stmt` válido contendo um conjunto de resultados.
`row_number`
  Solicita uma linha específica indexada em 1 do conjunto de resultados. Passar este parâmetro resulta em um aviso do PHP se o conjunto de resultados usar um cursor somente de avanço.

### Valor Retornado

Retorna um array associativo com valores de coluna indexados pelo nome da coluna representando a próxima linha ou a linha solicitada no conjunto de resultados. Retorna `false` se não houver linhas restantes no conjunto de resultados, ou se a linha solicitada por `row_number` não existir no conjunto de resultados.

### Exemplos

Exemplo #1 Iterando por um cursor somente de avanço

Se db2_fetch_assoc() for chamada sem um número de linha específico, ela recuperará automaticamente a próxima linha no conjunto de resultados.

    <?php

    $sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
    $stmt = db2_prepare($conn, $sql);
    $result = db2_execute($stmt);

    while ($row = db2_fetch_assoc($stmt)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row['ID'], $row['NAME'], $row['BREED'], $row['WEIGHT']);
    }
    ?>

O exemplo acima produzirá:

    0     Pook             cat                                    3.20
    5     Rickety Ride     goat                                   9.70
    2     Smarty           horse                                350.00

Exemplo #2 Recuperando linhas específicas com db2_fetch_assoc() a partir de um cursor rolável

Se o conjunto de resultados usar um cursor rolável, db2_fetch_assoc() pode ser chamada com um número de linha específico. O exemplo a seguir recupera todas as outras linhas no conjunto de resultados, começando com a segunda linha.

    <?php

    $sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
    $result = db2_exec($stmt, $sql, array('cursor' => DB2_SCROLLABLE));

    $i=2;
    while ($row = db2_fetch_assoc($result, $i)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row['ID'], $row['NAME'], $row['BREED'], $row['WEIGHT']);
        $i = $i + 2;
    }
    ?>

O exemplo acima produzirá:

    0     Pook             cat                                    3.20
    5     Rickety Ride     goat                                   9.70
    2     Smarty           horse                                350.00

### Veja Também

- db2_fetch_array() - Retorna um array, indexado pela posição da coluna, representando uma linha em um conjunto de resultados
- db2_fetch_both() - Retorna um array, indexado pelo nome da coluna e pela posição, representando uma linha em um conjunto de resultados
- db2_fetch_object() - Retorna um objeto com propriedades que representam colunas na linha buscada
- db2_fetch_row() - Define o ponteiro do conjunto de resultados para a próxima linha ou linha solicitada
- db2_result() - Retorna uma única coluna de uma linha no conjunto de resultados

# db2_fetch_both

(PECL ibm_db2 >= 1.0.0)

db2_fetch_both — Retorna um array, indexado pelo nome da coluna e pela posição, representando uma linha em um conjunto de resultados

### Descrição

function db2_fetch_both(resource `$stmt`, int `$row_number` = -1): array|false

Retorna um array, indexado pelo nome da coluna e pela posição, representando uma linha em um conjunto de resultados. Observe que a linha retornada por db2_fetch_both() requer mais memória do que os arrays de índice único retornados por db2_fetch_assoc() ou db2_fetch_array().

### Parâmetros

`stmt`
  Um recurso `stmt` válido contendo um conjunto de resultados.
`row_number`
  Solicita uma linha específica indexada em 1 do conjunto de resultados. Passar este parâmetro resulta em um aviso do PHP se o conjunto de resultados usar um cursor somente de avanço.

### Valor Retornado

Retorna um array associativo com valores de coluna indexados pelo nome da coluna e pelo número da coluna indexada em 0. O array representa a próxima linha ou a linha solicitada no conjunto de resultados. Retorna `false` se não houver linhas restantes no conjunto de resultados, ou se a linha solicitada por `row_number` não existir no conjunto de resultados.

### Exemplos

Exemplo #1 Iterando por um cursor somente de avanço

Se db2_fetch_both() for chamada sem um número de linha específico, ela recupera automaticamente a próxima linha no conjunto de resultados. O exemplo a seguir acessa colunas no array retornado pelo nome da coluna e pelo índice numérico.

    <?php

    $sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
    $stmt = db2_prepare($conn, $sql);
    $result = db2_execute($stmt);

    while ($row = db2_fetch_both($stmt)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row['ID'], $row[0], $row['BREED'], $row[3]);
    }
    ?>

O exemplo acima produzirá:

    0     Pook             cat                                    3.20
    5     Rickety Ride     goat                                   9.70
    2     Smarty           horse                                350.00

Exemplo #2 Recuperando linhas específicas com db2_fetch_both() a partir de um cursor rolável

Se o conjunto de resultados usar um cursor rolável, db2_fetch_both() pode ser chamada com um número de linha específico. O exemplo a seguir recupera todas as outras linhas no conjunto de resultados, começando com a segunda linha.

    <?php

    $sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
    $result = db2_exec($stmt, $sql, array('cursor' => DB2_SCROLLABLE));

    $i=2;
    while ($row = db2_fetch_both($result, $i)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row[0], $row['NAME'], $row[2], $row['WEIGHT']);
        $i = $i + 2;
    }
    ?>

O exemplo acima produzirá:

    0     Pook             cat                                    3.20
    5     Rickety Ride     goat                                   9.70
    2     Smarty           horse                                350.00

### Veja Também

- db2_fetch_array() - Retorna um array, indexado pela posição da coluna, representando uma linha em um conjunto de resultados
- db2_fetch_assoc() - Retorna um array, indexado pelo nome da coluna, representando uma linha em um conjunto de resultados
- db2_fetch_object() - Retorna um objeto com propriedades que representam colunas na linha buscada
- db2_fetch_row() - Define o ponteiro do conjunto de resultados para a próxima linha ou linha solicitada
- db2_result() - Retorna uma única coluna de uma linha no conjunto de resultados

# db2_fetch_object

(PECL ibm_db2 >= 1.0.0)

db2_fetch_object — Retorna um objeto com propriedades que representam colunas na linha buscada

### Descrição

function db2_fetch_object(resource `$stmt`, int `$row_number` = -1): stdClass|false

Retorna um objeto no qual cada propriedade representa uma coluna retornada na linha obtida de um conjunto de resultados.

### Parâmetros

`stmt`
  Um recurso `stmt` válido contendo um conjunto de resultados.
`row_number`
  Solicita uma linha específica indexada em 1 do conjunto de resultados. Passar este parâmetro resulta em um aviso do PHP se o conjunto de resultados usar um cursor somente de avanço.

### Valor Retornado

Retorna um objeto que representa uma única linha no conjunto de resultados. As propriedades do objeto mapeiam para os nomes das colunas no conjunto de resultados.

Os servidores de banco de dados IBM DB2, Cloudscape e Apache Derby normalmente convertem os nomes das colunas para letras maiúsculas, portanto as propriedades do objeto também serão em maiúsculas.

Se a instrução SELECT chamar uma função escalar para modificar o valor de uma coluna, os servidores de banco de dados retornarão o número da coluna como o nome da coluna no conjunto de resultados. Se a preferência for por nome de coluna e propriedade de objeto mais descritivos, pode ser usada a cláusula AS para atribuir um nome à coluna no conjunto de resultados.

Retorna `false` se nenhuma linha foi recuperada.

### Exemplos

Exemplo #1 Um exemplo de db2_fetch_object()

O exemplo a seguir emite uma instrução SELECT com uma função escalar, RTRIM, que remove espaços em branco do final da coluna. Em vez de criar um objeto com as propriedades "BREED" e "2", usamos a cláusula AS na instrução SELECT para atribuir o nome "name" à coluna modificada. O servidor de banco de dados converte os nomes das colunas para letras maiúsculas, resultando em um objeto com as propriedades "BREED" e "NAME".

    <?php
    $conn = db2_connect($database, $user, $password);

    $sql = "SELECT breed, RTRIM(name) AS name
        FROM animals
        WHERE id = ?";

    if ($conn) {
        $stmt = db2_prepare($conn, $sql);
        db2_execute($stmt, array(0));

        while ($pet = db2_fetch_object($stmt)) {
            echo "Come here, {$pet->NAME}, my little {$pet->BREED}!";
        }
        db2_close($conn);
    }
    ?>

O exemplo acima produzirá:

    Come here, Pook, my little cat!

### Veja Também

- db2_fetch_array() - Retorna um array, indexado pela posição da coluna, representando uma linha em um conjunto de resultados
- db2_fetch_assoc() - Retorna um array, indexado pelo nome da coluna, representando uma linha em um conjunto de resultados
- db2_fetch_both() - Retorna um array, indexado pelo nome da coluna e pela posição, representando uma linha em um conjunto de resultados
- db2_fetch_row() - Define o ponteiro do conjunto de resultados para a próxima linha ou linha solicitada
- db2_result() - Retorna uma única coluna de uma linha no conjunto de resultados

# db2_fetch_row

(PECL ibm_db2 >= 1.0.0)

db2_fetch_row — Define o ponteiro do conjunto de resultados para a próxima linha ou linha solicitada

### Descrição

function db2_fetch_row(resource `$stmt`, int `$row_number` = -1): bool

Use db2_fetch_row() para iterar por um conjunto de resultados ou para apontar para uma linha específica em um conjunto de resultados se você solicitou um cursor rolável.

Para recuperar campos individuais do conjunto de resultados, chame a função db2_result().

Em vez de chamar db2_fetch_row() e db2_result(), a maioria das aplicações chamará db2_fetch_assoc(), db2_fetch_both(), ou db2_fetch_array() para avançar o ponteiro do conjunto de resultados e retornar uma linha completa como um array.

### Parâmetros

`stmt`
  Um recurso `stmt` válido.
`row_number`
  Com cursores roláveis, pode ser solicitado um número de linha específico no conjunto de resultados. A numeração de linhas é indexada em 1.

### Valor Retornado

Retorna `true` se a linha solicitada existir no conjunto de resultados. Retorna `false` se a linha solicitada não existir no conjunto de resultados.

### Exemplos

Exemplo #1 Iterando por um conjunto de resultados

O exemplo a seguir demonstra como iterar por um conjunto de resultados com db2_fetch_row() e recuperar colunas do conjunto de resultados com db2_result().

    <?php
    $sql = 'SELECT name, breed FROM animals WHERE weight < ?';
    $stmt = db2_prepare($conn, $sql);
    db2_execute($stmt, array(10));
    while (db2_fetch_row($stmt)) {
        $name = db2_result($stmt, 0);
        $breed = db2_result($stmt, 1);
        print "$name $breed";
    }
    ?>

O exemplo acima produzirá:

    cat Pook
    gold fish Bubbles
    budgerigar Gizmo
    goat Rickety Ride

Exemplo #2 Alternativas i5/OS recomendadas para db2_fetch_row/db2_result

No i5/OS, é recomendado que seja usada a função db2_fetch_both(), db2_fetch_array() ou db2_fetch_object() em vez de db2_fetch_row()/db2_result(). Em geral, db2_fetch_row()/db2_result() têm mais problemas com vários tipos de coluna na tradução de `EBCDIC` para `ASCII`, incluindo possível truncamento em aplicações `DBCS`. Pode-se perceber também que o desempenho de db2_fetch_both(), db2_fetch_array() e db2_fetch_object() é superior a db2_fetch_row()/db2_result().

    <?php
      $conn = db2_connect("","","");
      $sql = 'SELECT SPECIFIC_SCHEMA, SPECIFIC_NAME, ROUTINE_SCHEMA, ROUTINE_NAME, ROUTINE_TYPE, ROUTINE_CREATED, ROUTINE_BODY, IN_PARMS, OUT_PARMS, INOUT_PARMS, PARAMETER_STYLE, EXTERNAL_NAME, EXTERNAL_LANGUAGE FROM QSYS2.SYSROUTINES FETCH FIRST 2 ROWS ONLY';
      $stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
      while ($row = db2_fetch_both($stmt)){
        echo "<br>db2_fetch_both {$row['SPECIFIC_NAME']} {$row['ROUTINE_CREATED']} {$row[5]}";
      }
      $stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
      while ($row = db2_fetch_array($stmt)){
        echo "<br>db2_fetch_array {$row[1]}  {$row[5]}";
      }
      $stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
      while ($row = db2_fetch_object($stmt)){
        echo "<br>db2_fetch_object {$row->SPECIFIC_NAME} {$row->ROUTINE_CREATED}";
      }
      db2_close($conn);
    ?>

O exemplo acima produzirá:

    db2_fetch_both MATCH_ANIMAL 2006-08-25-17.10.23.775000 2006-08-25-17.10.23.775000
    db2_fetch_both MULTIRESULTS 2006-10-17-10.11.05.308000 2006-10-17-10.11.05.308000
    db2_fetch_array MATCH_ANIMAL 2006-08-25-17.10.23.775000
    db2_fetch_array MULTIRESULTS 2006-10-17-10.11.05.308000
    db2_fetch_object MATCH_ANIMAL 2006-08-25-17.10.23.775000
    db2_fetch_object MULTIRESULTS 2006-10-17-10.11.05.308000

### Veja Também

- db2_fetch_array() - Retorna um array, indexado pela posição da coluna, representando uma linha em um conjunto de resultados
- db2_fetch_assoc() - Retorna um array, indexado pelo nome da coluna, representando uma linha em um conjunto de resultados
- db2_fetch_both() - Retorna um array, indexado pelo nome da coluna e pela posição, representando uma linha em um conjunto de resultados
- db2_fetch_object() - Retorna um objeto com propriedades que representam colunas na linha buscada
- db2_result() - Retorna uma única coluna de uma linha no conjunto de resultados

# db2_field_display_size

(PECL ibm_db2 >= 1.0.0)

db2_field_display_size — Retorna o número máximo de bytes necessários para exibir uma coluna

### Descrição

function db2_field_display_size(resource `$stmt`, int|string `$column`): int|false

Retorna o número máximo de bytes necessários para exibir uma coluna em um conjunto de resultados.

### Parâmetros

`stmt`
  Especifica um recurso de instrução contendo um conjunto de resultados.
`column`
  Especifica a coluna no conjunto de resultados. Isso pode ser um inteiro representando a posição indexada 0 da coluna, ou uma string contendo o nome da coluna.

### Valor Retornado

Retorna um valor inteiro com o número máximo de bytes necessários para exibir a coluna especificada. Se a coluna não existir no conjunto de resultados, db2_field_display_size() retornará `false`.

### Veja Também

- db2_field_name() - Retorna o nome da coluna no conjunto de resultados
- db2_field_num() - Retorna a posição da coluna nomeada em um conjunto de resultados
- db2_field_precision() - Retorna a precisão da coluna indicada em um conjunto de resultados
- db2_field_scale() - Retorna a escala da coluna indicada em um conjunto de resultados
- db2_field_type() - Retorna o tipo de dados da coluna indicada em um conjunto de resultados
- db2_field_width() - Retorna a largura do valor atual da coluna indicada em um conjunto de resultados

# db2_field_name

(PECL ibm_db2 >= 1.0.0)

db2_field_name — Retorna o nome da coluna no conjunto de resultados

### Descrição

function db2_field_name(resource `$stmt`, int|string `$column`): string|false

Retorna o nome da coluna especificada no conjunto de resultados.

### Parâmetros

`stmt`
  Especifica um recurso de instrução contendo um conjunto de resultados.
`column`
  Especifica a coluna no conjunto de resultados. Isso pode ser um inteiro representando a posição indexada 0 da coluna, ou uma string contendo o nome da coluna.

### Valor Retornado

Retorna uma string contendo o nome da coluna especificada. Se a coluna especificada não existir no conjunto de resultados, db2_field_name() retornará `false`.

### Veja Também

- db2_field_display_size() - Retorna o número máximo de bytes necessários para exibir uma coluna
- db2_field_num() - Retorna a posição da coluna nomeada em um conjunto de resultados
- db2_field_precision() - Retorna a precisão da coluna indicada em um conjunto de resultados
- db2_field_scale() - Retorna a escala da coluna indicada em um conjunto de resultados
- db2_field_type() - Retorna o tipo de dados da coluna indicada em um conjunto de resultados
- db2_field_width() - Retorna a largura do valor atual da coluna indicada em um conjunto de resultados

# db2_field_num

(PECL ibm_db2 >= 1.0.0)

db2_field_num — Retorna a posição da coluna nomeada em um conjunto de resultados

### Descrição

function db2_field_num(resource `$stmt`, int|string `$column`): int|false

Retorna a posição da coluna nomeada em um conjunto de resultados.

### Parâmetros

`stmt`
  Especifica um recurso de instrução contendo um conjunto de resultados.
`column`
  Especifica a coluna no conjunto de resultados. Isso pode ser um inteiro representando a posição indexada 0 da coluna, ou uma string contendo o nome da coluna.

### Valor Retornado

Retorna um inteiro contendo a posição indexada 0 da coluna nomeada em o conjunto de resultados. Se a coluna especificada não existir no conjunto de resultados, db2_field_num() retornará `false`.

### Veja Também

- db2_field_display_size() - Retorna o número máximo de bytes necessários para exibir uma coluna
- db2_field_name() - Retorna o nome da coluna no conjunto de resultados
- db2_field_precision() - Retorna a precisão da coluna indicada em um conjunto de resultados
- db2_field_scale() - Retorna a escala da coluna indicada em um conjunto de resultados
- db2_field_type() - Retorna o tipo de dados da coluna indicada em um conjunto de resultados
- db2_field_width() - Retorna a largura do valor atual da coluna indicada em um conjunto de resultados

# db2_field_precision

(PECL ibm_db2 >= 1.0.0)

db2_field_precision — Retorna a precisão da coluna indicada em um conjunto de resultados

### Descrição

function db2_field_precision(resource `$stmt`, int|string `$column`): int|false

Retorna a precisão da coluna indicada em um conjunto de resultados.

### Parâmetros

`stmt`
  Especifica um recurso de instrução contendo um conjunto de resultados.
`column`
  Especifica a coluna no conjunto de resultados. Isso pode ser um inteiro representando a posição indexada 0 da coluna, ou uma string contendo o nome da coluna.

### Valor Retornado

Retorna um inteiro contendo a precisão da coluna especificada. Se a coluna especificada não existir no conjunto de resultados, db2_field_precision() retornará `false`.

### Veja Também

- db2_field_display_size() - Retorna o número máximo de bytes necessários para exibir uma coluna
- db2_field_name() - Retorna o nome da coluna no conjunto de resultados
- db2_field_num() - Retorna a posição da coluna nomeada em um conjunto de resultados
- db2_field_scale() - Retorna a escala da coluna indicada em um conjunto de resultados
- db2_field_type() - Retorna o tipo de dados da coluna indicada em um conjunto de resultados
- db2_field_width() - Retorna a largura do valor atual da coluna indicada em um conjunto de resultados

# db2_field_scale

(PECL ibm_db2 >= 1.0.0)

db2_field_scale — Retorna a escala da coluna indicada em um conjunto de resultados

### Descrição

function db2_field_scale(resource `$stmt`, int|string `$column`): int|false

Retorna a escala da coluna indicada em um conjunto de resultados.

### Parâmetros

`stmt`
  Especifica um recurso de instrução contendo um conjunto de resultados.
`column`
  Especifica a coluna no conjunto de resultados. Isso pode ser um inteiro representando a posição indexada 0 da coluna, ou uma string contendo o nome da coluna.

### Valor Retornado

Retorna um inteiro contendo a escala da coluna especificada. Se a coluna especificada não existir no conjunto de resultados, db2_field_scale() retornará `false`.

### Veja Também

- db2_field_display_size() - Retorna o número máximo de bytes necessários para exibir uma coluna
- db2_field_name() - Retorna o nome da coluna no conjunto de resultados
- db2_field_num() - Retorna a posição da coluna nomeada em um conjunto de resultados
- db2_field_precision() - Retorna a precisão da coluna indicada em um conjunto de resultados
- db2_field_type() - Retorna o tipo de dados da coluna indicada em um conjunto de resultados
- db2_field_width() - Retorna a largura do valor atual da coluna indicada em um conjunto de resultados

# db2_field_type

(PECL ibm_db2 >= 1.0.0)

db2_field_type — Retorna o tipo de dados da coluna indicada em um conjunto de resultados

### Descrição

function db2_field_type(resource `$stmt`, int|string `$column`): string|false

Retorna o tipo de dados da coluna indicada em um conjunto de resultados.

### Parâmetros

`stmt`
  Especifica um recurso de instrução contendo um conjunto de resultados.
`column`
  Especifica a coluna no conjunto de resultados. Isso pode ser um inteiro representando a posição indexada 0 da coluna, ou uma string contendo o nome da coluna.

### Valor Retornado

Retorna uma string contendo o tipo de dado definido da coluna especificada. Se a coluna especificada não existir no conjunto de resultados, db2_field_type() retorna `false`.

### Veja Também

- db2_field_display_size() - Retorna o número máximo de bytes necessários para exibir uma coluna
- db2_field_name() - Retorna o nome da coluna no conjunto de resultados
- db2_field_num() - Retorna a posição da coluna nomeada em um conjunto de resultados
- db2_field_precision() - Retorna a precisão da coluna indicada em um conjunto de resultados
- db2_field_scale() - Retorna a escala da coluna indicada em um conjunto de resultados
- db2_field_width() - Retorna a largura do valor atual da coluna indicada em um conjunto de resultados

# db2_field_width

(PECL ibm_db2 >= 1.0.0)

db2_field_width — Retorna a largura do valor atual da coluna indicada em um conjunto de resultados

### Descrição

function db2_field_width(resource `$stmt`, int|string `$column`): int|false

Retorna a largura do valor atual da coluna indicada em um conjunto de resultados. Esta é a largura máxima da coluna para um tipo de dados de comprimento fixo, ou a largura real da coluna para um tipo de dados de comprimento variável.

### Parâmetros

`stmt`
  Especifica um recurso de instrução contendo um conjunto de resultados.
`column`
  Especifica a coluna no conjunto de resultados. Isso pode ser um inteiro representando a posição indexada 0 da coluna, ou uma string contendo o nome da coluna.

### Valor Retornado

Retorna um inteiro contendo a largura do caractere especificado ou coluna de tipo de dado binário em um conjunto de resultados. Se a coluna especificada não existir no conjunto de resultados, db2_field_width() retornará `false`.

### Veja Também

- db2_field_display_size() - Retorna o número máximo de bytes necessários para exibir uma coluna
- db2_field_name() - Retorna o nome da coluna no conjunto de resultados
- db2_field_num() - Retorna a posição da coluna nomeada em um conjunto de resultados
- db2_field_precision() - Retorna a precisão da coluna indicada em um conjunto de resultados
- db2_field_scale() - Retorna a escala da coluna indicada em um conjunto de resultados
- db2_field_type() - Retorna o tipo de dados da coluna indicada em um conjunto de resultados

# db2_foreign_keys

(PECL ibm_db2 >= 1.0.0)

db2_foreign_keys — Retorna um conjunto de resultados listando as chaves estrangeiras para uma tabela

### Descrição

function db2_foreign_keys(
resource `$connection`,
?string `$qualifier`,
?string `$schema`,
string `$table_name`
): resource

Retorna um conjunto de resultados listando as chaves estrangeiras para uma tabela.

### Parâmetros

`connection`
  Uma conexão válida com um banco de dados IBM DB2, Cloudscape ou Apache Derby.
`qualifier`
  Um qualificador para bancos de dados DB2 em execução em servidores OS/390 ou z/OS. Para outros bancos de dados, passe `null` ou uma string vazia.
`schema`
  O esquema que contém as tabelas. Se `schema` for `null`, db2_foreign_keys() corresponde ao esquema para a conexão atual.
`table_name`
  O nome da tabela.

### Valor Retornado

Retorna um recurso de instrução com um conjunto de resultados contendo linhas descrevendo as chaves estrangeiras para a tabela especificada. O conjunto de resultados é composto das seguintes colunas:

Nome da coluna | Descrição
--- | ---
PKTABLE_CAT | Nome do catálogo para a tabela que contém a chave primária. O valor é NULL se esta tabela não tiver catálogos.
PKTABLE_SCHEM | Nome do esquema da tabela que contém a chave primária.
PKTABLE_NAME | Nome da tabela que contém a chave primária.
PKCOLUMN_NAME | Nome da coluna que contém a chave primária.
FKTABLE_CAT | Nome do catálogo para a tabela que contém a chave estrangeira. O valor é NULL se esta tabela não tiver catálogos.
FKTABLE_SCHEM | Nome do esquema da tabela que contém a chave estrangeira.
FKTABLE_NAME | Nome da tabela que contém a chave estrangeira.
FKCOLUMN_NAME | Nome da coluna que contém a chave estrangeira.
KEY_SEQ | Posição indexada em 1 da coluna na chave.
UPDATE_RULE | Valor inteiro representando a ação aplicada à chave estrangeira quando a operação SQL é UPDATE.
DELETE_RULE | Valor inteiro que representa a ação aplicada à chave estrangeira quando a operação SQL é DELETE.
FK_NAME | O nome da chave estrangeira.
PK_NAME | O nome da chave primária.
DEFERRABILITY | Um valor inteiro que representa se a diferibilidade da chave estrangeira é SQL_INITIALLY_DEFERRED, SQL_INITIALLY_IMMEDIATE ou SQL_NOT_DEFERRABLE.

### Veja Também

- db2_column_privileges() - Retorna um conjunto de resultados listando as colunas e privilégios associados para uma tabela
- db2_columns() - Retorna um conjunto de resultados listando as colunas e metadados associados para uma tabela
- db2_primary_keys() - Retorna um conjunto de resultados listando as chaves primárias para uma tabela
- db2_procedure_columns() - Retorna um conjunto de resultados listando os parâmetros do procedimento armazenado
- db2_procedures() - Retorna um conjunto de resultados listando os procedimentos armazenados registrados em um banco de dados
- db2_special_columns() - Retorna um conjunto de resultados listando as colunas de identificador de linha exclusivo para uma tabela
- db2_statistics() - Retorna um conjunto de resultados listando o índice e as estatísticas de uma tabela
- db2_table_privileges() - Retorna um conjunto de resultados listando as tabelas e privilégios associados em um banco de dados
- db2_tables() - Retorna um conjunto de resultados listando as tabelas e metadados associados em um banco de dados

# db2_free_result

(PECL ibm_db2 >= 1.0.0)

db2_free_result — Libera recursos associados a um conjunto de resultados

### Descrição

function db2_free_result(resource `$stmt`): bool

Libera os recursos do sistema e do banco de dados que estão associados a um conjunto de resultados. Esses recursos são liberados implicitamente quando um script termina, mas db2_free_result() pode ser chamada para liberar explicitamente os recursos do conjunto de resultados antes do fim do script.

### Parâmetros

`stmt`
  Um recurso de instrução válido.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- db2_free_stmt() - Libera recursos associados ao recurso de instrução indicado

# db2_free_stmt

(PECL ibm_db2 >= 1.0.0)

db2_free_stmt — Libera recursos associados ao recurso de instrução indicado

### Descrição

function db2_free_stmt(resource `$stmt`): bool

Libera os recursos do sistema e do banco de dados que estão associados a um recurso de instrução. Esses recursos são liberados implicitamente quando um script termina, mas você pode chamar db2_free_stmt() para liberar explicitamente os recursos de instrução antes do fim do script.

### Parâmetros

`stmt`
  Um recurso de instrução válido.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- db2_free_result() - Libera recursos associados a um conjunto de resultados

# db2_get_option

(PECL ibm_db2 >= 1.6.0)

db2_get_option — Recupera um valor de opção para um recurso de instrução ou um recurso de conexão

### Descrição

function db2_get_option(resource `$resource`, string `$option`): string|false

Recupera o valor de uma opção especificada para um recurso de instrução ou um recurso de conexão.

### Parâmetros

`resource`
  Um recurso de instrução válido conforme retornado de db2_prepare() ou um recurso de conexão válido conforme retornado por db2_connect() ou db2_pconnect().
`option`

  Uma instrução válida ou opções de conexão. As seguintes novas opções estão disponíveis a partir do ibm_db2 versão 1.6.0. Elas fornecem informações úteis de rastreamento que podem ser definidas durante a execução com db2_get_option().

  > Nota: Versões anteriores do ibm_db2 não oferecem suporte a essas novas opções. Quando o valor em cada opção está sendo definido, alguns servidores podem não lidar com todo o comprimento fornecido e podem truncar o valor. Para garantir que os dados especificados em cada opção sejam convertidos corretamente quando transmitidos para um sistema host, use apenas os caracteres de A a Z, de 0 a 9 e o sublinhado (_) ou ponto (.).

  `userid`

    `SQL_ATTR_INFO_USERID` - Um ponteiro para uma string terminada em nulo usada para identificar o ID do usuário cliente enviado ao servidor de banco de dados host ao usar o DB2 Connect.

    > Nota: Os servidores DB2 para z/OS e OS/390 suportam até 16 caracteres. Este ID do usuário não deve ser confundido com o ID do usuário de autenticação, ele é para propósitos de identificação apenas e não é usado para nenhuma autorização.

  `acctstr`

    `SQL_ATTR_INFO_ACCTSTR` - Um ponteiro para uma string terminada em nulo usada para identificar a sequência de contabilidade do cliente enviada ao servidor de banco de dados host ao usar o DB2 Connect.

    > Nota: Os servidores DB2 para z/OS e OS/390 suportam até 200 caracteres.

  `applname`

    `SQL_ATTR_INFO_APPLNAME` - Um ponteiro para uma string terminada em nulo usada para identificar o nome do aplicativo cliente enviado ao servidor de banco de dados host ao usar o DB2 Connect.

    > Nota: Os servidores DB2 para z/OS e OS/390 suportam até 32 caracteres.

  `wrkstnname`

    `SQL_ATTR_INFO_WRKSTNNAME` - Um ponteiro para uma string terminada em nulo usada para identificar o nome da estação de trabalho do cliente enviado para o servidor de banco de dados host ao usar o DB2 Connect.

    > Nota: Os servidores DB2 para z/OS e OS/390 suportam até 18 caracteres.

A tabela a seguir especifica quais opções são compatíveis com os tipos de recursos disponíveis:

Matriz Recurso-Parâmetro
Chave | Valor | Tipo de recurso
--- | --- | ---
|  | Conexão | Instrução | Conjunto de Resultados
userid | `SQL_ATTR_INFO_USERID` | X | X | -
acctstr | `SQL_ATTR_INFO_ACCTSTR` | X | X | -
applname | `SQL_ATTR_INFO_APPLNAME` | X | X | -
wrkstnname | `SQL_ATTR_INFO_WRKSTNNAME` | X | X | -

### Valor Retornado

Retorna a configuração atual do atributo de conexão fornecido em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Definindo e recuperando parâmetros por meio de um recurso de conexão

    <?php
    /* Parâmetros de conexão do banco de dados */
    $database = 'SAMPLE';
    $user     = 'db2inst1';
    $password = 'ibmdb2';

    /* Obtém Recurso de Conexão */
    $conn = db2_connect($database, $user, $password);

    echo "Atributos do cliente passados ​​pela string de conexão:\n";

    /* Cria o array associativo de opções com pares de chave-valor válidos */
    /* Atribui os atributos por meio da string de conexão */
    /* Acessa as opções especificadas */
    $options1 = array('userid' => 'db2inst1');
    $conn1 = db2_connect($database, $user, $password, $options1);
    $val = db2_get_option($conn1, 'userid');
    echo $val . "\n";

    $options2 = array('acctstr' => 'account');
    $conn2 = db2_connect($database, $user, $password, $options2);
    $val = db2_get_option($conn2, 'acctstr');
    echo $val . "\n";

    $options3 = array('applname' => 'myapp');
    $conn3 = db2_connect($database, $user, $password, $options3);
    $val = db2_get_option($conn3, 'applname');
    echo $val . "\n";

    $options4 = array('wrkstnname' => 'workstation');
    $conn4 = db2_connect($database, $user, $password, $options4);
    $val = db2_get_option($conn4, 'wrkstnname');
    echo $val . "\n";

    echo "Atributos do cliente transmitidos após a conexão:\n";

    /* Cria o array associativo de opções com pares de chave-valor válidos */
    /* Atribui os atributos depois que a conexão é feita */
    /* Acessa as opções especificadas */
    $options5 = array('userid' => 'db2inst1');
    $conn5 = db2_connect($database, $user, $password);
    $rc = db2_set_option($conn5, $options5, 1);
    $val = db2_get_option($conn5, 'userid');
    echo $val . "\n";

    $options6 = array('acctstr' => 'account');
    $conn6 = db2_connect($database, $user, $password);
    $rc = db2_set_option($conn6, $options6, 1);
    $val = db2_get_option($conn6, 'acctstr');
    echo $val . "\n";

    $options7 = array('applname' => 'myapp');
    $conn7 = db2_connect($database, $user, $password);
    $rc = db2_set_option($conn7, $options7, 1);
    $val = db2_get_option($conn7, 'applname');
    echo $val . "\n";

    $options8 = array('wrkstnname' => 'workstation');
    $conn8 = db2_connect($database, $user, $password);
    $rc = db2_set_option($conn8, $options8, 1);
    $val = db2_get_option($conn8, 'wrkstnname');
    echo $val . "\n";
    ?>

O exemplo acima produzirá:

    Atributos do cliente passados ​​pela string de conexão:
    db2inst1
    account
    myapp
    workstation
    Atributos do cliente transmitidos após a conexão:
    db2inst1
    account
    myapp
    workstation

### Veja Também

- db2_connect() - Retorna uma conexão com um banco de dados
- db2_cursor_type() - Retorna o tipo de cursor usado por um recurso de instrução
- db2_exec() - Executa uma instrução SQL diretamente
- db2_set_option() - Define opções para recursos de conexão ou instrução
- db2_pconnect() - Retorna uma conexão persistente a um banco de dados
- db2_prepare() - Prepara uma instrução SQL para ser executada

# db2_last_insert_id

(PECL ibm_db2 >= 1.7.1)

db2_last_insert_id — Retorna o ID gerado automaticamente da última consulta de inserção que foi executada com sucesso nesta conexão

### Descrição

function db2_last_insert_id(resource `$resource`): ?string

Retorna o ID gerado automaticamente da última consulta de inserção que foi executada com sucesso nesta conexão.

O resultado desta função não é afetado por nenhuma das seguintes instruções:

- Uma instrução INSERT de linha única com uma cláusula VALUES para uma tabela sem uma coluna de identidade.
- Uma instrução INSERT de várias linhas com uma cláusula VALUES.
- Uma instrução INSERT com uma seleção completa.
- Uma instrução ROLLBACK TO SAVEPOINT.

### Parâmetros

`resource`
  Um recurso de conexão válido conforme retornado de db2_connect() ou db2_pconnect(). O valor deste parâmetro não pode ser um recurso de instrução ou recurso de conjunto de resultados.

### Valor Retornado

Retorna o ID gerado automaticamente da última consulta de inserção que foi executada com sucesso nesta conexão.

### Exemplos

Exemplo #1 Um exemplo de db2_last_insert_id()

O exemplo a seguir mostra como retornar o ID gerado automaticamente da última consulta de inserção que foi executada com sucesso nesta conexão.

    <?php

    $database = "SAMPLE";
    $user = "db2inst1";
    $password = "ibmdb2";

    $conn = db2_connect($database, $user, $password);
    if($conn) {
        $createTable = "CREATE TABLE lastInsertID
          (id integer GENERATED BY DEFAULT AS IDENTITY, name varchar(20))";
        $insertTable = "INSERT INTO lastInsertID (name) VALUES ('Temp Name')";

        $stmt = @db2_exec($conn, $createTable);

        /* Verificando se há uma única linha inserida. */
        $stmt = db2_exec($conn, $insertTable);
        $ret =  db2_last_insert_id($conn);
        if($ret) {
            echo "O último ID de inserção é: " . $ret . "\n";
        } else {
            echo "Nenhum último ID de inserção.\n";
        }

        db2_close($conn);
    }
    else {
        echo "Falha na conexão.";
    }
    ?>

O exemplo acima produzirá:

    O último ID de inserção é: 1

# db2_lob_read

(PECL ibm_db2 >= 1.6.0)

db2_lob_read — Obtém um tamanho definido pelo usuário de arquivos LOB com cada invocação

### Descrição

function db2_lob_read(resource `$stmt`, int `$colnum`, int `$length`): string|false

Use db2_lob_read() para iterar por uma coluna especificada de um conjunto de resultados e recuperar um tamanho definido pelo usuário de dados LOB.

### Parâmetros

`stmt`
  Um recurso `stmt` válido contendo dados LOB.
`colnum`
  Um número de coluna válido no conjunto de resultados do recurso `stmt`.
`length`
  O tamanho dos dados LOB a serem recuperados do recurso `stmt`.

### Valor Retornado

Retorna a quantidade de dados que o usuário especifica. Retorna `false` se os dados não puderem ser recuperados.

### Exemplos

Exemplo #1 Iterando por diferentes tipos de dados

    <?php

    /* Parâmetros de conexão do banco de dados */
    $db = 'SAMPLE';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Obtém recurso de conexão */
    $conn = db2_connect($db,$username,$password);

    if ($conn) {
        $drop = 'DROP TABLE clob_stream';
        $result = @db2_exec( $conn, $drop );

        $create = 'CREATE TABLE clob_stream (id INTEGER, my_clob CLOB)';
        $result = db2_exec( $conn, $create );

        $variable = "";
        $stmt = db2_prepare($conn, "INSERT INTO clob_stream (id,my_clob) VALUES (1, ?)");
        $variable = "THIS IS A CLOB TEST. THIS IS A CLOB TEST.";
        db2_bind_param($stmt, 1, "variable", DB2_PARAM_IN);
        db2_execute($stmt);

        $sql = "SELECT id,my_clob FROM clob_stream";
        $result = db2_prepare($conn, $sql);
        db2_execute($result);
        db2_fetch_row($result);
        $i = 0;
        /* Lê dados LOB */
        while ($data = db2_lob_read($result, 2, 6)) {
            echo "Loop $i: $data\n";
            $i = $i + 1;
        }

        $drop = 'DROP TABLE blob_stream';
        $result = @db2_exec( $conn, $drop );

        $create = 'CREATE TABLE blob_stream (id INTEGER, my_blob CLOB)';
        $result = db2_exec( $conn, $create );

        $variable = "";
        $stmt = db2_prepare($conn, "INSERT INTO blob_stream (id,my_blob) VALUES (1, ?)");
        $variable = "THIS IS A BLOB TEST. THIS IS A BLOB TEST.";
        db2_bind_param($stmt, 1, "variable", DB2_PARAM_IN);
        db2_execute($stmt);

        $sql = "SELECT id,my_blob FROM blob_stream";
        $result = db2_prepare($conn, $sql);
        db2_execute($result);
        db2_fetch_row($result);
        $i = 0;
        /* Lê dados LOB */
        while ($data = db2_lob_read($result, 2, 6)) {
            echo "Loop $i: $data\n";
            $i = $i + 1;
        }
    } else {
        echo 'sem conexão: ' . db2_conn_errormsg();
    }

    ?>

O exemplo acima produzirá:

    Loop 0: THIS I
    Loop 1: S A CL
    Loop 2: OB TES
    Loop 3: T. THI
    Loop 4: S IS A
    Loop 5:  CLOB
    Loop 6: TEST.
    Loop 0: THIS I
    Loop 1: S A BL
    Loop 2: OB TES
    Loop 3: T. THI
    Loop 4: S IS A
    Loop 5:  BLOB
    Loop 6: TEST.

### Veja Também

- db2_bind_param() - Vincula uma variável PHP a um parâmetro de instrução SQL
- db2_exec() - Executa uma instrução SQL diretamente
- db2_execute() - Executa uma instrução SQL preparada
- db2_fetch_row() - Define o ponteiro do conjunto de resultados para a próxima linha ou linha solicitada
- db2_prepare() - Prepara uma instrução SQL para ser executada
- db2_result() - Retorna uma única coluna de uma linha no conjunto de resultados

# db2_next_result

(PECL ibm_db2 >= 1.0.0)

db2_next_result — Solicita o próximo conjunto de resultados de um procedimento armazenado

### Descrição

function db2_next_result(resource `$stmt`): resource|false

Um procedimento armazenado pode retornar zero ou mais conjuntos de resultados. Enquanto se manipula o primeiro conjunto de resultados exatamente da mesma forma que seriam manipulado os resultados retornados por uma instrução SELECT simples, para buscar o segundo conjunto de resultados e os subsequentes de um procedimento armazenado, deve-se chamar a função db2_next_result() e retornar o resultado para uma variável PHP com nome exclusivo.

### Parâmetros

`stmt`
  Uma instrução preparada retornada de db2_exec() ou db2_execute().

### Valor Retornado

Retorna um novo recurso de instrução contendo o próximo conjunto de resultados se o procedimento armazenado retornou outro conjunto de resultados. Retorna `false` se o procedimento armazenado não retornou outro conjunto de resultados.

### Exemplos

Exemplo #1 Chamando um procedimento armazenado que retorna vários conjuntos de resultados

No exemplo a seguir, é chamado um procedimento armazenado que retorna três conjuntos de resultados. O primeiro conjunto de resultados é buscado diretamente do mesmo recurso de instrução no qual a instrução CALL é invocada, enquanto o segundo e o terceiro conjuntos de resultados são buscados de recursos de instrução retornados de nossas chamadas para a função db2_next_result().

    <?php
    $conn = db2_connect($database, $user, $password);

    if ($conn) {
      $stmt = db2_exec($conn, 'CALL multiResults()');

      print "Buscando o primeiro conjunto de resultados\n";
      while ($row = db2_fetch_array($stmt)) {
        var_dump($row);
      }

      print "\nBuscando o segundo conjunto de resultados\n";
      $res = db2_next_result($stmt);
      if ($res) {
        while ($row = db2_fetch_array($res)) {
          var_dump($row);
        }
      }

      print "\nBuscando o terceiro conjunto de resultados\n";
      $res2 = db2_next_result($stmt);
      if ($res2) {
        while ($row = db2_fetch_array($res2)) {
          var_dump($row);
        }
      }

      db2_close($conn);
    }
    ?>

O exemplo acima produzirá:

    Buscando o primeiro conjunto de resultados
    array(2) {
      [0]=>
      string(16) "Bubbles         "
      [1]=>
      int(3)
    }
    array(2) {
      [0]=>
      string(16) "Gizmo           "
      [1]=>
      int(4)
    }

    Buscando o segundo conjunto de resultados
    array(4) {
      [0]=>
      string(16) "Sweater         "
      [1]=>
      int(6)
      [2]=>
      string(5) "llama"
      [3]=>
      string(6) "150.00"
    }
    array(4) {
      [0]=>
      string(16) "Smarty          "
      [1]=>
      int(2)
      [2]=>
      string(5) "horse"
      [3]=>
      string(6) "350.00"
    }

    Buscando o terceiro conjunto de resultados
    array(1) {
      [0]=>
      string(16) "Bubbles         "
    }
    array(1) {
      [0]=>
      string(16) "Gizmo           "
    }

# db2_num_fields

(PECL ibm_db2 >= 1.0.0)

db2_num_fields — Retorna o número de campos contidos em um conjunto de resultados

### Descrição

function db2_num_fields(resource `$stmt`): int|false

Retorna o número de campos contidos em um conjunto de resultados. Isso é mais útil para lidar com os conjuntos de resultados retornados por consultas geradas dinamicamente, ou para conjuntos de resultados retornados por procedimentos armazenados, onde a aplicação não pode de outra forma saber como recuperar e usar os resultados.

### Parâmetros

`stmt`
  Um recurso de instrução válido contendo um conjunto de resultados.

### Valor Retornado

Retorna um valor inteiro representando o número de campos no conjunto de resultados associado ao recurso de instrução especificado. Retorna `false` se o recurso de instrução não for um valor de entrada válido.

### Exemplos

Exemplo #1 Recuperando o número de campos em um conjunto de resultados

O exemplo a seguir demonstra como recuperar o número de campos retornados em um conjunto de resultados.

    <?php

    $sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
    $stmt = db2_prepare($conn, $sql);
    db2_execute($stmt, $sql);
    $columns = db2_num_fields($stmt);

    echo "Há {$columns} colunas no conjunto de resultados.";
    ?>

O exemplo acima produzirá:

    Há 4 colunas no conjunto de resultados.

### Veja Também

- db2_execute() - Executa uma instrução SQL preparada
- db2_field_display_size() - Retorna o número máximo de bytes necessários para exibir uma coluna
- db2_field_name() - Retorna o nome da coluna no conjunto de resultados
- db2_field_num() - Retorna a posição da coluna nomeada em um conjunto de resultados
- db2_field_precision() - Retorna a precisão da coluna indicada em um conjunto de resultados
- db2_field_scale() - Retorna a escala da coluna indicada em um conjunto de resultados
- db2_field_type() - Retorna o tipo de dados da coluna indicada em um conjunto de resultados
- db2_field_width() - Retorna a largura do valor atual da coluna indicada em um conjunto de resultados

# db2_num_rows

(PECL ibm_db2 >= 1.0.0)

db2_num_rows — Retorna o número de linhas afetadas por uma instrução SQL

### Descrição

function db2_num_rows(resource `$stmt`): int|false

Retorna o número de linhas excluídas, inseridas ou atualizadas por uma instrução SQL.

Para determinar o número de linhas que serão retornadas por uma instrução SELECT, emita SELECT COUNT(*) com os mesmos predicados que a instrução SELECT pretendida e recupere o valor.

Se a lógica da aplicação verifica o número de linhas retornadas por uma instrução SELECT e ramifica se o número de linhas for 0, considere modificar a aplicação para tentar retornar a primeira linha com uma das funções db2_fetch_assoc(), db2_fetch_both(), db2_fetch_array() ou db2_fetch_row(), e ramificar se a função retornar `false`.

> Nota: Se for emitida uma instrução SELECT usando um cursor rolável, db2_num_rows() retornará o número de linhas retornadas pela instrução SELECT. No entanto, a sobrecarga associada a cursores roláveis degrada significativamente o desempenho da aplicação. Portanto, se esta for a única razão pela qual estão sendo usados cursores roláveis, deve-se usar um cursor somente de avanço e chamar SELECT COUNT(*) ou confiar no valor de retorno bool das funções de busca para obter a funcionalidade equivalente com desempenho muito melhor.

### Parâmetros

`stmt`
  Um recurso `stmt` válido contendo um conjunto de resultados.

### Valor Retornado

Retorna o número de linhas afetadas pela última instrução SQL emitida pelo identificador de instrução especificado, ou `false` em caso de falha

# db2_pclose

(PECL ibm_db2 >= 1.8.0)

db2_pclose — Fecha uma conexão persistente a um banco de dados

### Descrição

function db2_pclose(resource `$connection`): bool

Esta função fecha uma conexão de cliente DB2 criada com db2_pconnect() e retorna os recursos correspondentes para o servidor de banco de dados.

> Nota: Esta função só está disponível no i5/OS em resposta a solicitações de administração do sistema i5/OS.

Se houver uma conexão de cliente DB2 persistente criada com db2_pconnect(), esta função pode ser usada para fechar a conexão. Para evitar penalidades substanciais no desempenho da conexão, esta função deve ser usada apenas em casos raros quando a conexão persistente parar de responder ou não for necessária por um longo período de tempo.

### Parâmetros

`connection`
  Especifica uma conexão de cliente DB2 ativa.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Fechando uma conexão persistente

O exemplo a seguir demonstra uma tentativa bem-sucedida de fechar uma conexão com um banco de dados IBM DB2 i5/OS.

    <?php
    $conn = db2_pconnect('', '', '');
    $rc = db2_pclose($conn);
    if ($rc) {
        echo "A conexão foi encerrada com sucesso.";
    }
    ?>

O exemplo acima produzirá:

    A conexão foi encerrada com sucesso.

### Veja Também

- db2_close() - Fecha uma conexão de banco de dados
- db2_pconnect() - Retorna uma conexão persistente a um banco de dados

# db2_pconnect

(PECL ibm_db2 >= 1.0.0)

db2_pconnect — Retorna uma conexão persistente a um banco de dados

### Descrição

function db2_pconnect(
string `$database`,
?string `$username`,
?string `$password`,
array `$options` = []
): resource|false

Retorna uma conexão persistente com um banco de dados IBM DB2 Universal Database, IBM Cloudscape ou Apache Derby.

Para mais informações sobre conexões persistentes, consulte Conexões Persistentes com o Banco de Dados.

Chamar db2_close() em uma conexão persistente sempre retorna `true`, mas a conexão do cliente DB2 subjacente permanece aberta e aguardando para atender a próxima solicitação db2_pconnect() correspondente.

Usuários executando a versão 1.9.0 ou posterior do ibm_db2 devem estar cientes de que a extensão executará uma reversão de transação em conexões persistentes no fim de uma solicitação, encerrando assim a transação. Isso impede que o bloco de transação seja transferido para a próxima solicitação que usa essa conexão se a execução do script terminar antes do bloco de transação.

### Parâmetros

`database`
  Para uma conexão catalogada com um banco de dados, `database` representa o apelido do banco de dados no catálogo do cliente DB2.

  Para uma conexão não catalogada com um banco de dados, `database` representa uma string de conexão completa no seguinte formato:

      DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=username;PWD=password;

  > Nota:

  > Ao conectar-se ao Db2 no IBM i, o sistema subjacente chama » SQLDriverConnect, que aceita apenas DSN, UID e PWD para a » string de conexão. Assim:

  >     DSN=database;UID=username;PWD=password;

  onde os parâmetros representam os seguintes valores:
  `database`
    O nome do banco de dados.
  `hostname`
    O nome do host ou endereço IP do servidor de banco de dados.
  `port`
    A porta TCP/IP na qual o banco de dados está escutando solicitações.
  `username`
    O nome de usuário com o qual a conexão ao banco de dados é realizada.
  `password`
    A senha com a qual a conexão ao banco de dados é realizada.
`username`
  O nome de usuário com o qual a conexão ao banco de dados é realizada.
`password`
  A senha com a qual a conexão ao banco de dados é realizada.
`options`

  Um array associativo de opções de conexão que afetam o comportamento da conexão, onde chaves válidas do array incluem:

  `autocommit`
    Passar o valor `DB2_AUTOCOMMIT_ON` ativa a autoconfirmação para este identificador de conexão. Passar o valor `DB2_AUTOCOMMIT_OFF` desativa a autoconfirmação para este identificador de conexão.
  `DB2_ATTR_CASE`
    Passar o valor `DB2_CASE_NATURAL` especifica que os nomes das colunas são retornados em maiúsculas e minúsculas. Passar o valor `DB2_CASE_LOWER` especifica que os nomes das colunas são retornados em letras minúsculas. Passar o valor `DB2_CASE_UPPER` especifica que os nomes das colunas são retornados em letras maiúsculas.
  `CURSOR`
    Passar o valor `DB2_FORWARD_ONLY` especifica um cursor somente de avanço para um recurso de instrução. Este é o tipo de cursor padrão e é suportado em todos os servidores de banco de dados. Passar o valor `DB2_SCROLLABLE` especifica um cursor rolável para um recurso de instrução. Este modo permite acesso aleatório a linhas em um conjunto de resultados, mas atualmente é suportado apenas pelo IBM DB2 Universal Database.

  A nova opção a seguir está disponível no ibm_db2 versão 1.7.0 e posteriores.

  `trustedcontext`
    Passar o valor DB2_TRUSTED_CONTEXT_ENABLE ativa o contexto confiável para este identificador de conexão. Este parâmetro não pode ser definido usando db2_set_option(). Esta chave funciona somente se o banco de dados estiver catalogado (mesmo se o banco de dados for local), ou se você especificar o DSN completo ao criar a conexão. Para catalogar o banco de dados, use os seguintes comandos:

        db2 catalog tcpip node loopback remote <SERVERNAME> server <SERVICENAME>
        db2 catalog database <LOCALDBNAME> as <REMOTEDBNAME> at node loopback
        db2 "update dbm cfg using svcename <SERVICENAME>"
        db2set DB2COMM=TCPIP

  As seguintes novas opções do i5/OS estão disponíveis no ibm_db2 versão 1.5.1 e posteriores.

  Dica

  Atributos de conexão conflitantes usados ​​em conjunto com conexões persistentes podem produzir resultados indeterminados no i5/OS. Políticas de site devem ser estabelecidas para todos os aplicativos que usam cada perfil de usuário de conexão persistente. O DB2_AUTOCOMMIT_ON padrão é sugerido ao usar conexões persistentes.

  `i5_lib`
    Um valor de caractere que indica a biblioteca padrão que será usada para resolver referências de arquivo não qualificadas. Isso não é válido se a conexão estiver usando o modo de nomenclatura do sistema.
  `i5_naming`
    O valor `DB2_I5_NAMING_ON` ativa o modo de nomeação do sistema DB2 UDB CLI iSeries. Os arquivos são qualificados usando o delimitador de barra (/). Os arquivos não qualificados são resolvidos usando a lista de bibliotecas para o trabalho. O valor `DB2_I5_NAMING_OFF` desativa o modo de nomeação padrão do DB2 UDB CLI, que é a nomeação SQL. Os arquivos são qualificados usando o delimitador de ponto (.). Arquivos não qualificados são resolvidos usando a biblioteca padrão ou o ID do usuário atual.
  `i5_commit`

    O atributo `i5_commit` deve ser definido antes de db2_pconnect(). Se o valor for alterado após a conexão ter sido estabelecida, e a conexão for para uma fonte de dados remota, a alteração não terá efeito até a próxima db2_pconnect() bem-sucedida para o identificador de conexão.

    > Nota: A configuração php.ini `ibm_db2.i5_allow_commit`==0 ou `DB2_I5_TXN_NO_COMMIT` é o padrão, mas pode ser substituída pela opção `i5_commit`.

    `DB2_I5_TXN_NO_COMMIT` - O controle de confirmação não é usado. `DB2_I5_TXN_READ_UNCOMMITTED` - Leituras sujas, leituras não repetíveis e fantasmas são possíveis. `DB2_I5_TXN_READ_COMMITTED` - Leituras sujas não são possíveis. Leituras não repetíveis e fantasmas são possíveis. `DB2_I5_TXN_REPEATABLE_READ` - Leituras sujas e leituras não repetíveis não são possíveis. Fantasmas são possíveis. `DB2_I5_TXN_SERIALIZABLE` - As transações são serializáveis. Leituras sujas, leituras não repetíveis e fantasmas não são possíveis.
  `i5_query_optimize`
    `DB2_FIRST_IO` Todas as consultas são otimizadas com o objetivo de retornar a primeira página de saída o mais rápido possível. Este objetivo funciona bem quando a saída é controlada por um usuário que tem mais probabilidade de cancelar a consulta após visualizar a primeira página de dados de saída. Consultas codificadas com uma cláusula OPTIMIZE FOR nnn ROWS honram o objetivo especificado pela cláusula. `DB2_ALL_IO` Todas as consultas são otimizadas com o objetivo de executar a consulta inteira até a conclusão no menor tempo decorrido. Esta é uma boa opção quando a saída de uma consulta está sendo gravada em um arquivo ou relatório, ou a interface está enfileirando os dados de saída. Consultas codificadas com uma cláusula OPTIMIZE FOR nnn ROWS honram o objetivo especificado pela cláusula. Este é o padrão.
  `i5_dbcs_alloc`
    O valor `DB2_I5_DBCS_ALLOC_ON` ativa o esquema de alocação DB2 6X para o crescimento do tamanho da coluna de tradução DBCS.

    O valor `DB2_I5_DBCS_ALLOC_OFF` desativa o esquema de alocação DB2 6X para o crescimento do tamanho da coluna de tradução DBCS.

    > Nota: A configuração php.ini `ibm_db2.i5_dbcs_alloc`==0 ou `DB2_I5_DBCS_ALLOC_OFF` é o padrão, mas pode ser substituída pela opção `i5_dbcs_alloc`.

  `i5_date_fmt`
    `DB2_I5_FMT_ISO` - O formato de data da Organização Internacional para Padronização (ISO) aaaa-mm-dd é usado. Este é o padrão. `DB2_I5_FMT_USA` - O formato de data dos Estados Unidos mm/dd/aaaa é usado. `DB2_I5_FMT_EUR` - O formato de data europeu dd.mm.aaaa é usado. `DB2_I5_FMT_JIS` - O formato de data do Padrão Industrial Japonês aaaa-mm-dd é usado. `DB2_I5_FMT_MDY` - O formato de data mm/dd/aaaa é usado. `DB2_I5_FMT_DMY` - O formato de data dd/mm/aaaa é usado. `DB2_I5_FMT_YMD` - O formato de data aa/mm/dd é usado. `DB2_I5_FMT_JUL` - O formato de data juliano aa/ddd é usado. `DB2_I5_FMT_JOB` - O padrão da tarefa é usado.
  `i5_date_sep`
    `DB2_I5_SEP_SLASH` - Uma barra ( / ) é usada como separador de data. Este é o padrão. `DB2_I5_SEP_DASH` - Um traço ( - ) é usado como separador de data. `DB2_I5_SEP_PERIOD` - Um ponto ( . ) é usado como separador de data. `DB2_I5_SEP_COMMA` - Uma vírgula ( , ) é usada como separador de data. `DB2_I5_SEP_BLANK` - Um espaço em branco é usado como separador de data. `DB2_I5_SEP_JOB` - O padrão da tarefa é usado.
  `i5_time_fmt`
    `DB2_I5_FMT_ISO` - O formato de horário da Organização Internacional para Padronização (ISO) hh.mm.ss é usado. Este é o padrão. `DB2_I5_FMT_USA` - O formato de horário dos Estados Unidos hh:mmxx é usado, onde xx é AM ou PM. `DB2_I5_FMT_EUR` - O formato de horário europeu hh.mm.ss é usado. `DB2_I5_FMT_JIS` - O formato de horário do Padrão Industrial Japonês hh:mm:ss é usado. `DB2_I5_FMT_HMS` - O formato hh:mm:ss é usado.
  `i5_time_sep`
    `DB2_I5_SEP_COLON` - Dois pontos ( : ) são usados ​​como separador de horário. Este é o padrão. `DB2_I5_SEP_PERIOD` - Um ponto ( . ) é usado como separador de horário. `DB2_I5_SEP_COMMA` - Uma vírgula ( , ) é usada como separador de horário. `DB2_I5_SEP_BLANK` - Um espaço em branco é usado como separador de horário. `DB2_I5_SEP_JOB` - O padrão da tarefa é usado.
  `i5_decimal_sep`
    `DB2_I5_SEP_PERIOD` - Um ponto ( . ) é usado como separador decimal. Este é o padrão. `DB2_I5_SEP_COMMA` - Uma vírgula ( , ) é usada como separador decimal. `DB2_I5_SEP_JOB` - O padrão da tarefa é usado.

  A seguinte nova opção do i5/OS está disponível no ibm_db2 versão 1.8.0 e posteriores.

  `i5_libl`

    Um valor de caractere que indica a lista de bibliotecas que será usada para resolver referências de arquivo não qualificadas. Especifique os elementos da lista de bibliotecas separados por espaços em branco 'i5_libl'=>"MINHA_BIBLIOTECA SUA_BIBLIOTECA QUALQUER_BIBLIOTECA".

    > Nota: i5_libl chama qsys2/qcmdexc('cmd',cmdlen), que está disponível somente no i5/OS V5R4 e posteriores.

### Valor Retornado

Retorna um recurso de identificador de conexão se a tentativa de conexão for bem-sucedida. db2_pconnect() tenta reutilizar um recurso de conexão existente que corresponda exatamente aos parâmetros `database`, `username` e `password`. Se a tentativa de conexão falhar, db2_pconnect() retornará `false`.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL ibm_db2 1.9.0 | Transações ativas dentro de uma conexão persistente serão revertidas no final de cada solicitação.
PECL ibm_db2 1.8.0 | A opção `i5_libl` está disponível para usuários do i5/OS.
PECL ibm_db2 1.7.0 | A opção `trustedcontext` está disponível.
PECL ibm_db2 1.5.1 | As opções `i5_lib`, `i5_naming`, `i5_commit`, `i5_query_optimize`, `i5_dbcs_alloc`, `i5_date_fmt`, `i5_date_sep`, `i5_time_fmt`, `i5_time_sep` e `i5_decimal_sep` estão disponíveis para usuários do i5/OS.

### Exemplos

Exemplo #1 Um exemplo de db2_pconnect()

No exemplo a seguir, a primeira chamada para db2_pconnect() retorna um novo recurso de conexão persistente. A segunda chamada para db2_pconnect() retorna um recurso de conexão persistente que simplesmente reutiliza o primeiro recurso.

    <?php
    $database = 'SAMPLE';
    $user = 'db2inst1';
    $password = 'ibmdb2';

    $pconn = db2_pconnect($database, $user, $password);

    if ($pconn) {
        echo "Conexão persistente bem-sucedida.";
    }
    else {
        echo "Falha na conexão persistente.";
    }

    $pconn2 = db2_pconnect($database, $user, $password);
    if ($pconn) {
        echo "Second Conexão persistente bem-sucedida.";
    }
    else {
        echo "A segunda conexão persistente falhou.";
    }
    ?>

O exemplo acima produzirá:

    Conexão persistente bem-sucedida.
    A segunda conexão persistente falhou.

Exemplo #2 Usando contexto confiável

O exemplo a seguir mostra como habilitar o contexto confiável, alternar usuários e obter o ID do usuário atual.

    <?php

    $database = "SAMPLE";
    $hostname = "localhost";
    $port = 50000;
    $authID = "db2inst1";
    $auth_pass = "ibmdb2";

    $tc_user = "tcuser";
    $tc_pass = "tcpassword";

    $dsn = "DATABASE=$database;HOSTNAME=$hostname;PORT=$port;
      PROTOCOL=TCPIP;UID=$authID;PWD=$auth_pass;";
    $options = array ("trustedcontext" => DB2_TRUSTED_CONTEXT_ENABLE);

    $tc_conn = db2_pconnect($dsn, "", "", $options);
    if($tc_conn) {
        echo "Conexão confiável explícita bem-sucedida.\n";

        if(db2_get_option($tc_conn, "trustedcontext")) {
            $userBefore = db2_get_option($tc_conn, "trusted_user");

            // Faz algo como usuário 1.

            // Trocando para usuário confiável.
            $parameters = array("trusted_user" => $tc_user,
              "trusted_password" => $tcuser_pass);
            $res = db2_set_option ($tc_conn, $parameters, 1);

            $userAfter = db2_get_option($tc_conn, "trusted_user");
            // Faz algo mais como usuário confiável.

            if($userBefore != $userAfter) {
                echo "O usuário foi trocado." . "\n";
            }
        }

        db2_close($tc_conn);
    }
    else {
        echo "Falha na conexão confiável explícita.\n";
    }
    ?>

O exemplo acima produzirá:

    Conexão confiável explícita bem-sucedida.
    O usuário foi trocado.

### Veja Também

- db2_connect() - Retorna uma conexão com um banco de dados

# db2_prepare

(PECL ibm_db2 >= 1.0.0)

db2_prepare — Prepara uma instrução SQL para ser executada

### Descrição

function db2_prepare(resource `$connection`, string `$statement`, array `$options` = []): resource|false

db2_prepare() cria uma instrução SQL preparada que pode incluir 0 ou mais marcadores de parâmetros (caracteres `?`) representando parâmetros para entrada, saída ou entrada/saída. Pode-se passar parâmetros para a instrução preparada usando db2_bind_param(), ou apenas para valores de entrada, como um array passado para db2_execute().

Existem três vantagens principais em usar instruções preparadas em uma aplicação:

- Desempenho: quando uma instrução é preparada, o servidor de banco de dados cria um plano de acesso otimizado para recuperar dados com essa instrução. Subsequentemente, emitir a instrução preparada com db2_execute() permite que as instruções reutilizem esse plano de acesso e evita a sobrecarga de criar dinamicamente um novo plano de acesso para cada instrução emitida.
- Segurança: quando uma instrução é preparada, podem ser incluídos marcadores de parâmetros para valores de entrada. Quando uma instrução preparada é executada com valores de entrada para marcadores, o servidor de banco de dados verifica cada valor de entrada para garantir que o tipo corresponda à definição da coluna ou definição do parâmetro.
- Funcionalidade avançada: Os marcadores de parâmetros não apenas permitem que sejam passados valores de entrada para instruções SQL preparadas, eles também permitem que sejam recuperados parâmetros OUT e INOUT de procedimentos armazenados usando db2_bind_param().

### Parâmetros

`connection`
  Uma variável de recurso de conexão de banco de dados válida, conforme retornada de db2_connect() ou db2_pconnect().
`statement`
  Uma instrução SQL, contendo opcionalmente um ou mais marcadores de parâmetros.
`options`
  Um array associativo contendo opções de instrução. Você pode usar este parâmetro para solicitar um cursor rolável em servidores de banco de dados que suportam esta funcionalidade. Para uma descrição das opções de instrução válidas, consulte db2_set_option().

### Valor Retornado

Retorna um recurso de instrução se a instrução SQL foi analisada com sucesso e preparada pelo servidor de banco de dados. Retorna `false` se o servidor de banco de dados retornou um erro. Pode-se determinar qual erro foi retornado chamando db2_stmt_error() ou db2_stmt_errormsg().

### Exemplos

Exemplo #1 Preparando e executando uma instrução SQL com marcadores de parâmetros

O exemplo a seguir prepara uma instrução INSERT que aceita quatro marcadores de parâmetros e, em seguida, itera sobre um array de arrays contendo os valores de entrada a serem passados ​​para db2_execute().

    <?php
    $animals = array(
        array(0, 'cat', 'Pook', 3.2),
        array(1, 'dog', 'Peaches', 12.3),
        array(2, 'horse', 'Smarty', 350.0),
    );

    $insert = 'INSERT INTO animals (id, breed, name, weight)
        VALUES (?, ?, ?, ?)';
    $stmt = db2_prepare($conn, $insert);
    if ($stmt) {
        foreach ($animals as $animal) {
            $result = db2_execute($stmt, $animal);
        }
    }
    ?>

### Veja Também

- db2_bind_param() - Vincula uma variável PHP a um parâmetro de instrução SQL
- db2_execute() - Executa uma instrução SQL preparada
- db2_stmt_error() - Retorna uma string contendo o SQLSTATE retornado por uma instrução SQL
- db2_stmt_errormsg() - Retorna uma string contendo a última mensagem de erro da instrução SQL

# db2_primary_keys

(PECL ibm_db2 >= 1.0.0)

db2_primary_keys — Retorna um conjunto de resultados listando as chaves primárias para uma tabela

### Descrição

function db2_primary_keys(
resource `$connection`,
?string `$qualifier`,
?string `$schema`,
string `$table_name`
): resource

Retorna um conjunto de resultados listando as chaves primárias para uma tabela.

### Parâmetros

`connection`
  Uma conexão válida com um banco de dados IBM DB2, Cloudscape ou Apache Derby.
`qualifier`
  Um qualificador para bancos de dados DB2 em execução em servidores OS/390 ou z/OS. Para outros bancos de dados, passe `null` ou uma string vazia.
`schema`
  O esquema que contém as tabelas. Se `schema` for `null`, db2_primary_keys() corresponde ao esquema para a conexão atual.
`table_name`
  O nome da tabela.

### Valor Retornado

Retorna um recurso de instrução com um conjunto de resultados contendo linhas descrevendo as chaves primárias para a tabela especificada. O conjunto de resultados é composto das seguintes colunas:

Nome da coluna | Descrição
--- | ---
TABLE_CAT | Nome do catálogo para a tabela que contém a chave primária. O valor é NULL se esta tabela não tiver catálogos.
TABLE_SCHEM | Nome do esquema da tabela que contém a chave primária.
TABLE_NAME | Nome da tabela que contém a chave primária.
COLUMN_NAME | Nome da coluna que contém a chave primária.
KEY_SEQ | Posição indexada em 1 da coluna na chave.
PK_NAME | O nome da chave primária.

### Veja Também

- db2_column_privileges() - Retorna um conjunto de resultados listando as colunas e privilégios associados para uma tabela
- db2_columns() - Retorna um conjunto de resultados listando as colunas e metadados associados para uma tabela
- db2_foreign_keys() - Retorna um conjunto de resultados listando as chaves estrangeiras para uma tabela
- db2_procedure_columns() - Retorna um conjunto de resultados listando os parâmetros do procedimento armazenado
- db2_procedures() - Retorna um conjunto de resultados listando os procedimentos armazenados registrados em um banco de dados
- db2_special_columns() - Retorna um conjunto de resultados listando as colunas de identificador de linha exclusivo para uma tabela
- db2_statistics() - Retorna um conjunto de resultados listando o índice e as estatísticas de uma tabela
- db2_table_privileges() - Retorna um conjunto de resultados listando as tabelas e privilégios associados em um banco de dados
- db2_tables() - Retorna um conjunto de resultados listando as tabelas e metadados associados em um banco de dados

# db2_procedure_columns

(PECL ibm_db2 >= 1.0.0)

db2_procedure_columns — Retorna um conjunto de resultados listando os parâmetros do procedimento armazenado

### Descrição

function db2_procedure_columns(
resource `$connection`,
?string `$qualifier`,
string `$schema`,
string `$procedure`,
?string `$parameter`
): resource

Retorna um conjunto de resultados listando os parâmetros para um ou mais procedimentos armazenados.

### Parâmetros

`connection`
  Uma conexão válida com um banco de dados IBM DB2, Cloudscape ou Apache Derby.
`qualifier`
  Um qualificador para bancos de dados DB2 em execução em servidores OS/390 ou z/OS. Para outros bancos de dados, passe `null` ou uma string vazia.
`schema`
  O esquema que contém os procedimentos. Este parâmetro aceita um padrão de pesquisa contendo `_` e `%` como curingas.
`procedure`
  O nome do procedimento. Este parâmetro aceita um padrão de pesquisa contendo `_` e `%` como curingas.
`parameter`
  O nome do parâmetro. Este parâmetro aceita um padrão de pesquisa contendo `_` e `%` como curingas. Se este parâmetro for `null`, todos os parâmetros para os procedimentos armazenados especificados serão retornados.

### Valor Retornado

Retorna um recurso de instrução com um conjunto de resultados contendo linhas descrevendo os parâmetros para os procedimentos armazenados que correspondem aos parâmetros especificados. As linhas são compostas das seguintes colunas:

Nome da coluna | Descrição
--- | ---
PROCEDURE_CAT | O catálogo que contém o procedimento. O valor é `null` se esta tabela não tiver catálogos.
PROCEDURE_SCHEM | Nome do esquema que contém o procedimento armazenado.
PROCEDURE_NAME | Nome do procedimento.
COLUMN_NAME | Nome do parâmetro.
COLUMN_TYPE | Um valor inteiro que representa o tipo do parâmetro:
Valor de retorno | Tipo de parâmetro
--- | ---
1 (SQL_PARAM_INPUT) | Parâmetro de entrada (IN).
2 (SQL_PARAM_INPUT_OUTPUT) | Parâmetro de entrada/saída (INOUT).
3 (SQL_PARAM_OUTPUT) | Parâmetro de saída (OUT).
DATA_TYPE | O tipo de dados SQL para o parâmetro representado como um valor inteiro.
TYPE_NAME | Uma string que representa o tipo de dados do parâmetro.
COLUMN_SIZE | Um valor inteiro que representa o tamanho do parâmetro.
BUFFER_LENGTH | Número máximo de bytes necessários para armazenar dados para este parâmetro.
DECIMAL_DIGITS | A escala do parâmetro, ou `null` onde a escala não é aplicável.
NUM_PREC_RADIX | Um valor inteiro de `10` (representando um tipo de dado numérico exato), `2` (representando um tipo de dado numérico aproximado) ou `null` (representando um tipo de dado para o qual radix não é aplicável).
NULLABLE | Um valor inteiro que representa se o parâmetro é anulável ou não.
REMARKS | Descrição do parâmetro.
COLUMN_DEF | Valor padrão para o parâmetro.
SQL_DATA_TYPE | Um valor inteiro que representa o tamanho do parâmetro.
SQL_DATETIME_SUB | Retorna um valor inteiro que representa um código de subtipo de data e hora, ou `null` para tipos de dados SQL aos quais isso não se aplica.
CHAR_OCTET_LENGTH | Comprimento máximo em octetos para um parâmetro de tipo de dados de caractere, que corresponde a COLUMN_SIZE para dados de conjunto de caracteres de byte único ou `null` para tipos de dados que não são caracteres.
ORDINAL_POSITION | A posição indexada em 1 do parâmetro na instrução CALL.
IS_NULLABLE | Um valor de string onde 'YES' significa que o parâmetro aceita ou retorna `null` valores e 'NO' significa que o parâmetro não aceita ou retorna `null` valores.

### Veja Também

- db2_column_privileges() - Retorna um conjunto de resultados listando as colunas e privilégios associados para uma tabela
- db2_columns() - Retorna um conjunto de resultados listando as colunas e metadados associados para uma tabela
- db2_foreign_keys() - Retorna um conjunto de resultados listando as chaves estrangeiras para uma tabela
- db2_primary_keys() - Retorna um conjunto de resultados listando as chaves primárias para uma tabela
- db2_procedures() - Retorna um conjunto de resultados listando os procedimentos armazenados registrados em um banco de dados
- db2_special_columns() - Retorna um conjunto de resultados listando as colunas de identificador de linha exclusivo para uma tabela
- db2_statistics() - Retorna um conjunto de resultados listando o índice e as estatísticas de uma tabela
- db2_table_privileges() - Retorna um conjunto de resultados listando as tabelas e privilégios associados em um banco de dados
- db2_tables() - Retorna um conjunto de resultados listando as tabelas e metadados associados em um banco de dados

# db2_procedures

(PECL ibm_db2 >= 1.0.0)

db2_procedures — Retorna um conjunto de resultados listando os procedimentos armazenados registrados em um banco de dados

### Descrição

function db2_procedures(
resource `$connection`,
?string `$qualifier`,
string `$schema`,
string `$procedure`
): resource

Retorna um conjunto de resultados listando os procedimentos armazenados registrados em um banco de dados.

### Parâmetros

`connection`
  Uma conexão válida com um banco de dados IBM DB2, Cloudscape ou Apache Derby.
`qualifier`
  Um qualificador para bancos de dados DB2 em execução em servidores OS/390 ou z/OS. Para outros bancos de dados, passe `null` ou uma string vazia.
`schema`
  O esquema que contém os procedimentos. Este parâmetro aceita um padrão de pesquisa contendo `_` e `%` como curingas.
`procedure`
  O nome do procedimento. Este parâmetro aceita um padrão de pesquisa contendo `_` e `%` como curingas.

### Valor Retornado

Retorna um recurso de declaração com um conjunto de resultados contendo linhas descrevendo os procedimentos armazenados que correspondem aos parâmetros especificados. As linhas são compostas pelas seguintes colunas:

Nome da coluna | Descrição
--- | ---
PROCEDURE_CAT | O catálogo que contém o procedimento. O valor é `null` se esta tabela não tiver catálogos.
PROCEDURE_SCHEM | Nome do esquema que contém o procedimento armazenado.
PROCEDURE_NAME | Nome do procedimento.
NUM_INPUT_PARAMS | Número de parâmetros de entrada (IN) para o procedimento armazenado.
NUM_OUTPUT_PARAMS | Número de parâmetros de saída (OUT) para o procedimento armazenado.
NUM_RESULT_SETS | Número de conjuntos de resultados retornados pelo procedimento armazenado.
REMARKS | Algum comentário sobre o procedimento armazenado.
PROCEDURE_TYPE | Sempre retorna `1`, indicando que o procedimento armazenado não retorna um valor.

### Veja Também

- db2_column_privileges() - Retorna um conjunto de resultados listando as colunas e privilégios associados para uma tabela
- db2_columns() - Retorna um conjunto de resultados listando as colunas e metadados associados para uma tabela
- db2_foreign_keys() - Retorna um conjunto de resultados listando as chaves estrangeiras para uma tabela
- db2_primary_keys() - Retorna um conjunto de resultados listando as chaves primárias para uma tabela
- db2_procedure_columns() - Retorna um conjunto de resultados listando os parâmetros do procedimento armazenado
- db2_special_columns() - Retorna um conjunto de resultados listando as colunas de identificador de linha exclusivo para uma tabela
- db2_statistics() - Retorna um conjunto de resultados listando o índice e as estatísticas de uma tabela
- db2_table_privileges() - Retorna um conjunto de resultados listando as tabelas e privilégios associados em um banco de dados
- db2_tables() - Retorna um conjunto de resultados listando as tabelas e metadados associados em um banco de dados

# db2_result

(PECL ibm_db2 >= 1.0.0)

db2_result — Retorna uma única coluna de uma linha no conjunto de resultados

### Descrição

function db2_result(resource `$stmt`, int|string `$column`): ?mixed

Use db2_result() para retornar o valor de uma coluna especificada na linha atual de um conjunto de resultados. Deve-se chamar db2_fetch_row() antes de chamar db2_result() para definir o local do ponteiro do conjunto de resultados.

### Parâmetros

`stmt`
  Um recurso `stmt` válido.
`column`
  Um inteiro que mapeia para o campo indexado em 0 no conjunto de resultados ou uma string correspondente ao nome da coluna.

### Valor Retornado

Retorna o valor do campo solicitado se o campo existir no conjunto de resultados. Retorna `null` se o campo não existir e emite um aviso.

### Exemplos

Exemplo #1 Um exemplo de db2_result()

O exemplo a seguir demonstra como iterar por um conjunto de resultados com db2_fetch_row() e recuperar colunas do conjunto de resultados com db2_result().

    <?php
    $sql = 'SELECT name, breed FROM animals WHERE weight < ?';
    $stmt = db2_prepare($conn, $sql);
    db2_execute($stmt, array(10));
    while (db2_fetch_row($stmt)) {
        $name = db2_result($stmt, 0);
        $breed = db2_result($stmt, 'BREED');
        print "$name $breed";
    }
    ?>

O exemplo acima produzirá:

    cat Pook
    gold fish Bubbles
    budgerigar Gizmo
    goat Rickety Ride

### Veja Também

- db2_fetch_array() - Retorna um array, indexado pela posição da coluna, representando uma linha em um conjunto de resultados
- db2_fetch_assoc() - Retorna um array, indexado pelo nome da coluna, representando uma linha em um conjunto de resultados
- db2_fetch_both() - Retorna um array, indexado pelo nome da coluna e pela posição, representando uma linha em um conjunto de resultados
- db2_fetch_object() - Retorna um objeto com propriedades que representam colunas na linha buscada
- db2_fetch_row() - Define o ponteiro do conjunto de resultados para a próxima linha ou linha solicitada

# db2_rollback

(PECL ibm_db2 >= 1.0.0)

db2_rollback — Reverte uma transação

### Descrição

function db2_rollback(resource `$connection`): bool

Reverte uma transação em andamento no recurso de conexão especificado e inicia uma nova transação. As aplicações PHP normalmente usam o modo AUTOCOMMIT por padrão, então db2_rollback() normalmente não tem efeito, a menos que AUTOCOMMIT tenha sido desativado para o recurso de conexão.

### Parâmetros

`connection`
  Uma variável de recurso de conexão de banco de dados válida, conforme retornada de db2_connect() ou db2_pconnect().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Revertendo uma instrução DELETE

No exemplo a seguir, contamos o número de linhas em uma tabela, desligamos o modo AUTOCOMMIT em uma conexão de banco de dados, excluímos todas as linhas na tabela e retornamos a contagem de `0` para provar que as linhas foram removidas. Em seguida, emitimos db2_rollback() e retornamos a contagem atualizada de linhas na tabela para mostrar que o número é o mesmo de antes de emitirmos a instrução DELETE. O retorno ao estado original da tabela demonstra que a reversão da transação foi bem-sucedida.

    <?php
    $conn = db2_connect($database, $user, $password);

    if ($conn) {
        $stmt = db2_exec($conn, "SELECT count(*) FROM animals");
        $res = db2_fetch_array( $stmt );
        echo $res[0] . "\n";

        // Desliga AUTOCOMMIT
        db2_autocommit($conn, DB2_AUTOCOMMIT_OFF);

        // Exclui todas as linhas de ANIMAIS
        db2_exec($conn, "DELETE FROM animals");

        $stmt = db2_exec($conn, "SELECT count(*) FROM animals");
        $res = db2_fetch_array( $stmt );
        echo $res[0] . "\n";

        // Reverte a instrução DELETE
        db2_rollback( $conn );

        $stmt = db2_exec( $conn, "SELECT count(*) FROM animals" );
        $res = db2_fetch_array( $stmt );
        echo $res[0] . "\n";
        db2_close($conn);
    }
    ?>

O exemplo acima produzirá:

    7
    0
    7

### Veja Também

- db2_autocommit() - Retorna ou define o estado AUTOCOMMIT para uma conexão de banco de dados
- db2_commit() - Confirma uma transação

# db2_server_info

(PECL ibm_db2 >= 1.1.1)

db2_server_info — Retorna um objeto com propriedades que descrevem o servidor de banco de dados DB2

### Descrição

function db2_server_info(resource `$connection`): stdClass|false

Esta função retorna um objeto com propriedades somente leitura que retornam informações sobre o servidor de banco de dados IBM DB2, Cloudscape ou Apache Derby. A tabela a seguir lista as propriedades do servidor de banco de dados:

Database server properties
Nome da propriedade | Tipo de retorno | Descrição
--- | --- | ---
DBMS_NAME | string | O nome do servidor de banco de dados conectado. Para servidores DB2, esta é uma combinação de `DB2` seguido pelo sistema operacional no qual o servidor de banco de dados está sendo executado.
DBMS_VER | string | A versão do servidor de banco de dados, na forma de uma string "MM.mm.uuuu" onde MM é a versão principal, mm é a versão secundária, e uuuu é a atualização. Por exemplo, "08.02.0001" representa a versão principal 8, versão secundária 2, atualização 1.
DB_CODEPAGE | int | A página de código do banco de dados conectado.
DB_NAME | string | O nome do banco de dados conectado.
DFT_ISOLATION | string | O nível de isolamento de transação padrão suportado pelo servidor: UR Leitura não confirmada: as alterações são imediatamente visíveis por todas as transações simultâneas. CS Estabilidade do cursor: uma linha lida por uma transação pode ser alterada e confirmada por uma segunda transação simultânea. RS Estabilidade de leitura: uma transação pode adicionar ou remover linhas que correspondem a uma condição de pesquisa ou uma transação pendente. RR Leitura repetível: dados afetados por transações pendentes não estão disponíveis para outras transações. NC Sem confirmação: quaisquer alterações são visíveis no final de uma operação bem-sucedida. Confirmações e reversões explícitas não são permitidos.
IDENTIFIER_QUOTE_CHAR | string | O caractere usado para delimitar um identificador.
INST_NAME | string | A instância no servidor de banco de dados que contém o banco de dados.
ISOLATION_OPTION | array | Um array das opções de isolamento suportadas pelo servidor de banco de dados. As opções de isolamento são descritas na propriedade DFT_ISOLATION.
KEYWORDS | array | Um array de palavras-chave reservadas pelo servidor de banco de dados.
LIKE_ESCAPE_CLAUSE | bool | `true` se o servidor de banco de dados suportar o uso dos caracteres curinga `%` e `_`. `false` se o servidor de banco de dados não suportar esses caracteres curinga.
MAX_COL_NAME_LEN | int | Comprimento máximo de um nome de coluna suportado pelo servidor de banco de dados, expresso em bytes.
MAX_IDENTIFIER_LEN | int | Comprimento máximo de um identificador SQL suportado pelo servidor de banco de dados, expresso em caracteres.
MAX_INDEX_SIZE | int | Tamanho máximo de colunas combinadas em um índice suportado pelo servidor de banco de dados, expresso em bytes.
MAX_PROC_NAME_LEN | int | Comprimento máximo de um nome de procedimento suportado pelo servidor de banco de dados, expresso em bytes.
MAX_ROW_SIZE | int | Comprimento máximo de uma linha em uma tabela base suportada pelo servidor de banco de dados, expresso em bytes.
MAX_SCHEMA_NAME_LEN | int | Comprimento máximo de um nome de esquema suportado pelo servidor de banco de dados, expresso em bytes.
MAX_STATEMENT_LEN | int | Comprimento máximo de uma instrução SQL suportada pelo servidor de banco de dados, expresso em bytes.
MAX_TABLE_NAME_LEN | int | Comprimento máximo de um nome de tabela suportado pelo servidor de banco de dados, expresso em bytes.
NON_NULLABLE_COLUMNS | bool | `true` se o servidor de banco de dados suportar colunas que podem ser definidas como NOT NULL, `false` se o servidor de banco de dados não suportar colunas definidas como NOT NULL.
PROCEDURES | bool | `true` se o servidor de banco de dados suportar o uso da instrução CALL para chamar procedimentos armazenados, `false` se o servidor de banco de dados não suportar a instrução CALL.
SPECIAL_CHARS | string | Uma string contendo todos os caracteres, exceto a-Z, 0-9 e sublinhado, que podem ser usados ​​em um nome de identificador.
SQL_CONFORMANCE | string | O nível de conformidade com a especificação ANSI/ISO SQL-92 oferecido pelo servidor de banco de dados: ENTRY Conformidade com SQL-92 de nível básico. FIPS127 Conformidade transitória com FIPS-127-2. FULL Conformidade total com SQL-92. INTERMEDIATE Conformidade com SQL-92 de nível intermediário.

### Parâmetros

`connection`
  Especifica uma conexão de cliente DB2 ativa.

### Valor Retornado

Retorna um objeto em uma chamada bem-sucedida, ou `false` em caso de falha

### Exemplos

Exemplo #1 Um exemplo de db2_server_info()

Para recuperar informações sobre o servidor, deve-se passar um recurso de conexão de banco de dados válido para db2_server_info().

    <?php

    $conn = db2_connect('sample', 'db2inst1', 'ibmdb2');

    $server = db2_server_info( $conn );

    if ($server) {
        echo "DBMS_NAME: ";                 var_dump( $server->DBMS_NAME );
        echo "DBMS_VER: ";                  var_dump( $server->DBMS_VER );
        echo "DB_CODEPAGE: ";               var_dump( $server->DB_CODEPAGE );
        echo "DB_NAME: ";                   var_dump( $server->DB_NAME );
        echo "INST_NAME: ";                 var_dump( $server->INST_NAME );
        echo "SPECIAL_CHARS: ";             var_dump( $server->SPECIAL_CHARS );
        echo "KEYWORDS: ";                  var_dump( sizeof($server->KEYWORDS) );
        echo "DFT_ISOLATION: ";             var_dump( $server->DFT_ISOLATION );
        echo "ISOLATION_OPTION: ";
        $il = '';
        foreach( $server->ISOLATION_OPTION as $opt )
        {
           $il .= $opt." ";
        }
        var_dump( $il );
        echo "SQL_CONFORMANCE: ";           var_dump( $server->SQL_CONFORMANCE );
        echo "PROCEDURES: ";                var_dump( $server->PROCEDURES );
        echo "IDENTIFIER_QUOTE_CHAR: ";     var_dump( $server->IDENTIFIER_QUOTE_CHAR );
        echo "LIKE_ESCAPE_CLAUSE: ";        var_dump( $server->LIKE_ESCAPE_CLAUSE );
        echo "MAX_COL_NAME_LEN: ";          var_dump( $server->MAX_COL_NAME_LEN );
        echo "MAX_ROW_SIZE: ";              var_dump( $server->MAX_ROW_SIZE );
        echo "MAX_IDENTIFIER_LEN: ";        var_dump( $server->MAX_IDENTIFIER_LEN );
        echo "MAX_INDEX_SIZE: ";            var_dump( $server->MAX_INDEX_SIZE );
        echo "MAX_PROC_NAME_LEN: ";         var_dump( $server->MAX_PROC_NAME_LEN );
        echo "MAX_SCHEMA_NAME_LEN: ";       var_dump( $server->MAX_SCHEMA_NAME_LEN );
        echo "MAX_STATEMENT_LEN: ";         var_dump( $server->MAX_STATEMENT_LEN );
        echo "MAX_TABLE_NAME_LEN: ";        var_dump( $server->MAX_TABLE_NAME_LEN );
        echo "NON_NULLABLE_COLUMNS: ";      var_dump( $server->NON_NULLABLE_COLUMNS );

        db2_close($conn);
    }
    ?>

O exemplo acima produzirá:

    DBMS_NAME: string(9) "DB2/LINUX"
    DBMS_VER: string(10) "08.02.0000"
    DB_CODEPAGE: int(1208)
    DB_NAME: string(6) "SAMPLE"
    INST_NAME: string(8) "db2inst1"
    SPECIAL_CHARS: string(2) "@#"
    KEYWORDS: int(179)
    DFT_ISOLATION: string(2) "CS"
    ISOLATION_OPTION: string(12) "UR CS RS RR "
    SQL_CONFORMANCE: string(7) "FIPS127"
    PROCEDURES: bool(true)
    IDENTIFIER_QUOTE_CHAR: string(1) """
    LIKE_ESCAPE_CLAUSE: bool(true)
    MAX_COL_NAME_LEN: int(30)
    MAX_ROW_SIZE: int(32677)
    MAX_IDENTIFIER_LEN: int(18)
    MAX_INDEX_SIZE: int(1024)
    MAX_PROC_NAME_LEN: int(128)
    MAX_SCHEMA_NAME_LEN: int(30)
    MAX_STATEMENT_LEN: int(2097152)
    MAX_TABLE_NAME_LEN: int(128)
    NON_NULLABLE_COLUMNS: bool(true)

### Veja Também

- db2_client_info() - Retorna um objeto com propriedades que descrevem o cliente do banco de dados DB2

# db2_set_option

(PECL ibm_db2 >= 1.0.0)

db2_set_option — Define opções para recursos de conexão ou instrução

### Descrição

function db2_set_option(resource `$resource`, array `$options`, int `$type`): bool

Define opções para recursos de conexão ou instrução. Não é possível definir opções para recursos de conjunto de resultados.

### Parâmetros

`resource`
  Um recurso de instrução válido conforme retornado por db2_prepare() ou um recurso de conexão válido conforme retornado por db2_connect() ou db2_pconnect().
`options`

  Um array associativo contendo opções de instrução ou conexão válidas. Este parâmetro pode ser usado para alterar valores de autoconfirmação, tipos de cursor (rolável ou de avanço) e para especificar a forma dos nomes de coluna (minúsculas, maiúsculas ou natural) que aparecerão em um conjunto de resultados.

  `autocommit`
    Passar `DB2_AUTOCOMMIT_ON` ativa a autoconfirmação para o recurso de conexão especificado. Passar `DB2_AUTOCOMMIT_OFF` desativa a autoconfirmação para o recurso de conexão especificado.
  `cursor`
    Passar `DB2_FORWARD_ONLY` especifica um cursor somente de avanço para um recurso de instrução. Este é o tipo de cursor padrão e é suportado por todos os servidores de banco de dados. Passar `DB2_SCROLLABLE` especifica um cursor rolável para um recurso de instrução. Cursores roláveis permitem que linhas de conjunto de resultados sejam acessadas em ordem não sequencial, mas são suportados apenas por bancos de dados IBM DB2 Universal Database.
  `binmode`
    Passar `DB2_BINARY` especifica que dados binários serão retornados como estiverem. Este é o modo padrão. Isto é o equivalente a definir `ibm_db2.binmode=1` no php.ini. Passar `DB2_CONVERT` especifica que dados binários serão convertidos para codificação hexadecimal, e serão retornados como tal. Isso é o equivalente a definir `ibm_db2.binmode=2` no php.ini. Passar `DB2_PASSTHRU` especifica que dados binários serão convertidos para `null`. Isso é o equivalente a definir `ibm_db2.binmode=3` no php.ini.
  `db2_attr_case`
    Passar `DB2_CASE_LOWER` especifica que nomes de colunas do conjunto de resultados são retornados em minúsculas. Passar `DB2_CASE_UPPER` especifica que nomes de colunas do conjunto de resultados são retornados em maiúsculas. Passar `DB2_CASE_NATURAL` especifica que nomes de colunas do conjunto de resultados são retornados de forma natural.
  `deferred_prepare`
    Passar `DB2_DEFERRED_PREPARE_ON` ativa a preparação adiada para o recurso de instrução especificado. Passar `DB2_DEFERRED_PREPARE_OFF` desativa o preparação adiada para o recurso de instrução especificado.

  As seguintes novas opções do i5/OS estão disponíveis no ibm_db2 versão 1.5.1 e posteriores. Essas opções se aplicam somente ao executar PHP e ibm_db2 nativamente em sistemas i5.

  `i5_fetch_only`
    `DB2_I5_FETCH_ON` - Os cursores são somente leitura e não podem ser usados ​​para atualizações ou exclusões posicionadas. Este é o padrão, a menos que o ambiente `SQL_ATTR_FOR_FETCH_ONLY` tenha sido definido como `SQL_FALSE`. `DB2_I5_FETCH_OFF` - Os cursores podem ser usados para atualizações e exclusões posicionadas.

  A nova opção a seguir está disponível no ibm_db2 versão 1.8.0 e posteriores.

  `rowcount`
    `DB2_ROWCOUNT_PREFETCH_ON` - O cliente pode solicitar a contagem completa de linhas antes da busca, o que significa que db2_num_rows() retorna o número de linhas selecionadas mesmo quando um cursor `ROLLFORWARD_ONLY` é usado. `DB2_ROWCOUNT_PREFETCH_OFF` - O cliente não pode solicitar a contagem completa de linhas antes da busca.

  As seguintes novas opções estão disponíveis no ibm_db2 versão 1.7.0 e posteriores.

  `trusted_user`
    Para alternar o usuário para um usuário confiável, passe o ID (string) do usuário confiável como o valor desta chave. Esta opção pode ser definida somente em um recurso de conexão. Para usar esta opção, o contexto confiável deve estar habilitado no recurso de conexão.
  `trusted_password`
    A senha (string) que corresponde ao usuário especificado pela chave trusted_user.

  As seguintes novas opções estão disponíveis no ibm_db2 versão 1.6.0 e posteriores. Essas opções fornecem informações úteis de rastreamento que podem ser acessadas durante a execução com db2_get_option().

  > Nota: Quando o valor em cada opção está sendo definido, alguns servidores podem não lidar com o todo o comprimento fornecido e podem truncar o valor. Para garantir que os dados especificados em cada opção sejam convertidos corretamente quando transmitidos para um sistema host, use apenas os caracteres de A a Z, 0 a 9 e o sublinhado (_) ou ponto (.).

  `userid`

    `SQL_ATTR_INFO_USERID` - Um ponteiro para uma string terminada em nulo usada para identificar o ID do usuário cliente enviado ao servidor de banco de dados host ao usar o DB2 Connect.

    > Nota: Os servidores DB2 para z/OS e OS/390 suportam até 16 caracteres. Este ID de usuário não deve ser confundido com o ID do usuário de autenticação, ele serve para identificação apenas e não é usado para nenhuma autorização.

  `acctstr`

    `SQL_ATTR_INFO_ACCTSTR` - Um ponteiro para uma string terminada em nulo usada para identificar a string de contabilidade do cliente enviada ao servidor de banco de dados host ao usar o DB2 Connect.

    > Nota: Os servidores DB2 para z/OS e OS/390 suportam até 200 caracteres.

  `applname`

    `SQL_ATTR_INFO_APPLNAME` - Um ponteiro para uma string terminada em nulo usada para identificar o nome do aplicativo cliente enviado ao servidor de banco de dados host ao usar o DB2 Connect.

    > Nota: Os servidores DB2 para z/OS e OS/390 suportam até 32 caracteres.

  `wrkstnname`

    `SQL_ATTR_INFO_WRKSTNNAME` - Um ponteiro para uma string terminada em nulo usada para identificar o nome da estação de trabalho cliente enviado ao servidor de banco de dados host ao usar o DB2 Connect.

    > Nota: Os servidores DB2 para z/OS e OS/390 suportam até 18 caracteres.

`type`
  Um valor inteiro que especifica o tipo de recurso que foi passado para a função. O tipo de recurso e este valor devem corresponder. Passar `1` como o valor especifica que um recurso de conexão foi passado para a função. Passar qualquer inteiro diferente de `1` como o valor especifica que um recurso de instrução foi passado para a função.

A tabela a seguir especifica quais opções são compatíveis com os tipos de recursos disponíveis:

Matriz de Parâmetros-Recursos
Chave | Valor | Tipo de Recurso
--- | --- | ---
|  | Conexão | Instrução | Conjunto de Resultados
autocommit | `DB2_AUTOCOMMIT_ON` | X | - | -
autocommit | `DB2_AUTOCOMMIT_OFF` | X | - | -
cursor | `DB2_SCROLLABLE` | - | X | -
cursor | `DB2_FORWARD_ONLY` | - | X | -
binmode | `DB2_BINARY` | X | X | -
binmode | `DB2_CONVERT` | X | X | -
binmode | `DB2_PASSTHRU` | X | X | -
db2_attr_case | `DB2_CASE_LOWER` | X | X | -
db2_attr_case | `DB2_CASE_UPPER` | X | X | -
db2_attr_case | `DB2_CASE_NATURAL` | X | X | -
deferred_prepare | `DB2_DEFERRED_PREPARE_ON` | - | X | -
deferred_prepare | `DB2_DEFERRED_PREPARE_OFF` | - | X | -
i5_fetch_only | `DB2_I5_FETCH_ON` | - | X | -
i5_fetch_only | `DB2_I5_FETCH_OFF` | - | X | -
rowcount | `DB2_ROWCOUNT_PREFETCH_ON` | - | X | -
rowcount | `DB2_ROWCOUNT_PREFETCH_OFF` | - | X | -
trusted_user | `<USER NAME> (String)` | X | - | -
trusted_password | `<PASSWORD> (String)` | X | - | -
userid | `SQL_ATTR_INFO_USERID` | X | X | -
acctstr | `SQL_ATTR_INFO_ACCTSTR` | X | X | -
applname | `SQL_ATTR_INFO_APPLNAME` | X | X | -
wrkstnname | `SQL_ATTR_INFO_WRKSTNNAME` | X | X | -

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Definindo um parâmetro com um recurso de conexão

    <?php
    /* Parâmetros de conexão do banco de dados */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* String de conexão */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Obtém recurso de conexão */
    $conn = db2_connect($conn_string, '', '');

    /* Cria o array associativo de opções com pares válidos de chave-valor */
    $options = array('autocommit' => DB2_AUTOCOMMIT_ON);

    /* Chama a função usando o recurso correto, o array de opções e os valores de tipo */
    $result = db2_set_option($conn, $options, 1);

    /* Verifica se todas as opções foram definidas corretamente */
    if($result)
    {
     echo 'Opções definidas com sucesso';
    }
    else
    {
     echo 'Não foi possível definir as opções';
    }
    ?>

O exemplo acima produzirá:

    Opções definidas com sucesso

Exemplo #2 Definindo vários parâmetros com um recurso de conexão

    <?php
    /* Parâmetros de conexão do banco de dados */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* String de conexão */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Obtém recurso de conexão */
    $conn = db2_connect($conn_string, '', '');

    /* Cria o array associativo de opções com pares válidos de chave-valor */
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
                       'binmode' => DB2_PASSTHRU,
                 'db2_attr_case' => DB2_CASE_UPPER,
                        'cursor' => DB2_SCROLLABLE);

    /* Chama a função usando o recurso correto, o array de opções e os valores de tipo */
    $result = db2_set_option($conn, $options, 1);

    /* Verifica se todas as opções foram definidas corretamente */
    if($result)
    {
     echo 'Opções definidas com sucesso';
    }
    else
    {
     echo 'Não foi possível definir as opções';
    }
    ?>

O exemplo acima produzirá:

    Opções definidas com sucesso

Exemplo #3 Definindo vários parâmetros com uma chave inválida

    <?php
    /* Parâmetros de conexão do banco de dados */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* String de conexão */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Obtém recurso de conexão */
    $conn = db2_connect($conn_string, '', '');

    /* Cria o array associativo de opções com pares válidos de chave-valor */
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
                'MY_INVALID_KEY' => DB2_PASSTHRU,
                 'db2_attr_case' => DB2_CASE_UPPER,
                        'cursor' => DB2_SCROLLABLE);

    /* Chama a função usando o recurso correto, o array de opções e os valores de tipo */
    $result = db2_set_option($conn, $options, 1);

    /* Verifica se todas as opções foram definidas corretamente */
    if($result)
    {
     echo 'Opções definidas com sucesso';
    }
    else
    {
     echo 'Não foi possível definir as opções';
    }
    ?>

O exemplo acima produzirá:

    Não foi possível definir as opções

Exemplo #4 Definindo vários parâmetros com um valor inválido

    <?php
    /* Parâmetros de conexão do banco de dados */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* String de conexão */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Obtém recurso de conexão */
    $conn = db2_connect($conn_string, '', '');

    /* Cria o array associativo de opções com pares válidos de chave-valor */
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
                       'binmode' => 'INVALID_VALUE',
                 'db2_attr_case' => DB2_CASE_UPPER,
                        'cursor' => DB2_SCROLLABLE);

    /* Chama a função usando o recurso correto, o array de opções e os valores de tipo */
    $result = db2_set_option($conn, $options, 1);

    /* Verifica se todas as opções foram definidas corretamente */
    if($result)
    {
     echo 'Opções definidas com sucesso';
    }
    else
    {
     echo 'Não foi possível definir as opções';
    }
    ?>

O exemplo acima produzirá:

    Não foi possível definir as opções

Exemplo #5 Definindo vários parâmetros com um recurso de conexão e o tipo errado

    <?php
    /* Parâmetros de conexão do banco de dados */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* String de conexão */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Obtém recurso de conexão */
    $conn = db2_connect($conn_string, '', '');

    /* Cria o array associativo de opções com pares válidos de chave-valor */
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
                       'binmode' => DB2_PASSTHRU,
                 'db2_attr_case' => DB2_CASE_UPPER,
                        'cursor' => DB2_SCROLLABLE);

    /* Chama a função usando o recurso correto, o array de opções e o valor de tipo errado */
    $result = db2_set_option($conn, $options, 2);

    /* Verifica se todas as opções foram definidas corretamente */
    if($result)
    {
     echo 'Opções definidas com sucesso';
    }
    else
    {
     echo 'Não foi possível definir as opções';
    }
    ?>

O exemplo acima produzirá:

    Não foi possível definir as opções

Exemplo #6 Definindo vários parâmetros com o recurso errado

    <?php
    /* Parâmetros de conexão do banco de dados */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* String de conexão */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Obtém recurso de conexão */
    $conn = db2_connect($conn_string, '', '');

    /* Cria o array associativo de opções com pares válidos de chave-valor */
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
                       'binmode' => DB2_PASSTHRU,
                 'db2_attr_case' => DB2_CASE_UPPER,
                        'cursor' => DB2_SCROLLABLE);

    $stmt = db2_prepare($conn, 'SELECT * FROM EMPLOYEE');

    /* Chama a função usando o recurso errado, o array de opções correto e os valores de tipo */
    $result = db2_set_option($stmt, $options, 1);

    /* Verifica se todas as opções foram definidas corretamente */
    if($result)
    {
     echo 'Opções definidas com sucesso';
    }
    else
    {
     echo 'Não foi possível definir as opções';
    }
    ?>

O exemplo acima produzirá:

    Não foi possível definir as opções

Exemplo #7 Juntando tudo

    <?php
    /* Parâmetros de conexão do banco de dados */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* String de conexão */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Obtém recurso de conexão */
    $conn = db2_connect($conn_string, '', '');

    /* Cria o array associativo de opções com pares válidos de chave-valor */
    $options = array('db2_attr_case' => DB2_CASE_LOWER,
                           'cursor' => DB2_SCROLLABLE);

    $stmt = db2_prepare($conn, 'SELECT * FROM EMPLOYEE WHERE EMPNO = ? OR EMPNO = ?');

    /* Chama a função usando o recurso correto, o array de opções e os valores de tipo */
    $option_result = db2_set_option($stmt, $options, 2);
    $result = db2_execute($stmt, array('000130', '000140'));

    /* Obtém a linha 2 antes da linha 1, pois o cursor é rolável */
    print_r(db2_fetch_assoc($stmt, 2));
    print '<br /><br />';
    print_r(db2_fetch_assoc($stmt, 1));

    ?>

O exemplo acima produzirá:

    Array
    (
       [empno] => 000140
       [firstnme] => HEATHER
       [midinit] => A
       [lastname] => NICHOLLS
       [workdept] => C01
       [phoneno] => 1793
       [hiredate] => 1976-12-15
       [job] => ANALYST
       [edlevel] => 18
       [sex] => F
       [birthdate] => 1946-01-19
       [salary] => 28420.00
       [bonus] => 600.00
       [comm] => 2274.00
    )

    Array
    (
       [empno] => 000130
       [firstnme] => DELORES
       [midinit] => M
       [lastname] => QUINTANA
       [workdept] => C01
       [phoneno] => 4578
       [hiredate] => 1971-07-28
       [job] => ANALYST
       [edlevel] => 16
       [sex] => F
       [birthdate] => 1925-09-15
       [salary] => 23800.00
       [bonus] => 500.00
       [comm] => 1904.00
    )

Exemplo #8 Os cursores do i5/OS são somente leitura

    <?php
     $conn = db2_connect("", "", "", array("i5_lib"=>"nobody"));
     $stmt = db2_prepare($conn, 'select * from names where first = ?');
     $name = "first2";
     db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
     $options = array("i5_fetch_only"=>DB2_I5_FETCH_ON);
     db2_set_option($stmt,$options,0);
     if (db2_execute($stmt)) {
       while ($row = db2_fetch_array($stmt)) {
         echo "{$row[0]} {$row[1]}";
       }
     }
    ?>

O exemplo acima produzirá:

    first2 last2

### Veja Também

- db2_connect() - Retorna uma conexão com um banco de dados
- db2_pconnect() - Retorna uma conexão persistente a um banco de dados
- db2_exec() - Executa uma instrução SQL diretamente
- db2_prepare() - Prepara uma instrução SQL para ser executada
- db2_cursor_type() - Retorna o tipo de cursor usado por um recurso de instrução

# db2_special_columns

(PECL ibm_db2 >= 1.0.0)

db2_special_columns — Retorna um conjunto de resultados listando as colunas de identificador de linha exclusivo para uma tabela

### Descrição

function db2_special_columns(
resource `$connection`,
?string `$qualifier`,
string `$schema`,
string `$table_name`,
int `$scope`
): resource

Retorna um conjunto de resultados listando as colunas de identificador de linha exclusivo para uma tabela.

### Parâmetros

`connection`
  Uma conexão válida com um banco de dados IBM DB2, Cloudscape ou Apache Derby.
`qualifier`
  Um qualificador para bancos de dados DB2 em execução em servidores OS/390 ou z/OS. Para outros bancos de dados, passe `null` ou uma string vazia.
`schema`
  O esquema que contém as tabelas.
`table_name`
  O nome da tabela.
`scope`

  Valor inteiro representando a duração mínima para a qual o identificador de linha exclusivo é válido. Este pode ser um dos seguintes valores:

  Valor inteiro | Constante SQL | Descrição
  --- | --- | ---
  0 | SQL_SCOPE_CURROW | O identificador de linha é válido somente enquanto o cursor estiver posicionado na linha.
  1 | SQL_SCOPE_TRANSACTION | O identificador de linha é válido durante a transação.
  2 | SQL_SCOPE_SESSION | O identificador de linha é válido durante a conexão.

### Valor Retornado

Retorna um recurso de declaração com um conjunto de resultados contendo linhas com informações de identificador de linha exclusivas para uma tabela. As linhas são compostas das seguintes colunas:

Nome da coluna | Descrição
--- | ---
SCOPE |
Valor inteiro | Constante SQL | Descrição
--- | --- | ---
0 | SQL_SCOPE_CURROW | O identificador de linha é válido somente enquanto o cursor estiver posicionado na linha.
1 | SQL_SCOPE_TRANSACTION | O identificador de linha é válido durante a transação.
2 | SQL_SCOPE_SESSION | O identificador de linha é válido durante a conexão.
COLUMN_NAME | Nome da coluna exclusiva.
DATA_TYPE | Tipo de dados SQL para a coluna.
TYPE_NAME | Representação de string do tipo de dados SQL para a coluna.
COLUMN_SIZE | Um valor inteiro que representa o tamanho da coluna.
BUFFER_LENGTH | Número máximo de bytes necessários para armazenar dados desta coluna.
DECIMAL_DIGITS | A escala da coluna, ou `null` onde a escala não é aplicável.
NUM_PREC_RADIX | Um valor inteiro de `10` (representando um tipo de dado numérico exato), `2` (representando um tipo de dado numérico aproximado) ou `null` (representando um tipo de dado para o qual radix não é aplicável).
PSEUDO_COLUMN | Sempre retorna 1.

### Veja Também

- db2_column_privileges() - Retorna um conjunto de resultados listando as colunas e privilégios associados para uma tabela
- db2_columns() - Retorna um conjunto de resultados listando as colunas e metadados associados para uma tabela
- db2_foreign_keys() - Retorna um conjunto de resultados listando as chaves estrangeiras para uma tabela
- db2_primary_keys() - Retorna um conjunto de resultados listando as chaves primárias para uma tabela
- db2_procedure_columns() - Retorna um conjunto de resultados listando os parâmetros do procedimento armazenado
- db2_procedures() - Retorna um conjunto de resultados listando os procedimentos armazenados registrados em um banco de dados
- db2_statistics() - Retorna um conjunto de resultados listando o índice e as estatísticas de uma tabela
- db2_table_privileges() - Retorna um conjunto de resultados listando as tabelas e privilégios associados em um banco de dados
- db2_tables() - Retorna um conjunto de resultados listando as tabelas e metadados associados em um banco de dados

# db2_statistics

(PECL ibm_db2 >= 1.0.0)

db2_statistics — Retorna um conjunto de resultados listando o índice e as estatísticas de uma tabela

### Descrição

function db2_statistics(
resource `$connection`,
?string `$qualifier`,
?string `$schema`,
string `$table_name`,
bool `$unique`
): resource

Retorna um conjunto de resultados listando o índice e as estatísticas de uma tabela.

### Parâmetros

`connection`
  Uma conexão válida com um banco de dados IBM DB2, Cloudscape ou Apache Derby.
`qualifier`
  Um qualificador para bancos de dados DB2 em execução em servidores OS/390 ou z/OS. Para outros bancos de dados, passe `null` ou uma string vazia.
`schema`
  O esquema que contém a tabela de destino. Se este parâmetro for `null`, as estatísticas e índices são retornados para o esquema do usuário atual.
`table_name`
  O nome da tabela.
`unique`
  Quando `unique` é `true`, as informações para todos os índices na tabela são retornadas. Caso contrário, apenas as informações para índices exclusivos na tabela são retornadas.

### Valor Retornado

Retorna um recurso de instrução com um conjunto de resultados contendo linhas descrevendo as estatísticas e índices para as tabelas base que correspondem aos parâmetros especificados. As linhas são compostas das seguintes colunas:

Nome da coluna | Descrição
--- | ---
TABLE_CAT | O catálogo que contém a tabela. O valor é `null` se esta tabela não tiver catálogos.
TABLE_SCHEM | Nome do esquema que contém a tabela.
TABLE_NAME | Nome da tabela.
NON_UNIQUE | Um valor inteiro que representa se o índice proíbe valores únicos ou se a linha representa estatísticas na própria tabela:
Valor de retorno | Tipo de parâmetro
--- | ---
0 (SQL_FALSE) | O índice permite valores duplicados.
1 (SQL_TRUE) | Os valores do índice devem ser exclusivos.
`null` | Esta linha contém informações estatísticas da própria tabela.
INDEX_QUALIFIER | Um valor de string representando o qualificador que teria que ser anexado a INDEX_NAME para qualificar completamente o índice.
INDEX_NAME | Uma string que representa o nome do índice.
TYPE | Um valor inteiro que representa o tipo de informação contida nesta linha do conjunto de resultados:
Valor de retorno | Tipo de parâmetro
--- | ---
0 (SQL_TABLE_STAT) | A linha contém estatísticas sobre a própria tabela.
1 (SQL_INDEX_CLUSTERED) | A linha contém informações sobre um índice clusterizado.
2 (SQL_INDEX_HASH) | A linha contém informações sobre um índice com hash.
3 (SQL_INDEX_OTHER) | A linha contém informações sobre um tipo de índice que não é agrupado nem hash.
ORDINAL_POSITION | A posição indexada em 1 da coluna no índice. `null` se a linha contiver informações estatísticas sobre a própria tabela.
COLUMN_NAME | O nome da coluna no índice. `null` se a linha contiver informações estatísticas sobre a própria tabela.
ASC_OR_DESC | `A` se a coluna estiver classificada em ordem crescente, `D` se a coluna estiver classificada em ordem decrescente, `null` se a linha contiver informações estatísticas sobre a tabela em si.
CARDINALITY | Se a linha contiver informações sobre um índice, esta coluna conterá um valor inteiro representando o número de valores exclusivos no índice. Se a linha contiver informações sobre a tabela em si, esta coluna conterá um valor inteiro representando o número de linhas na tabela.
PAGES | Se a linha contiver informações sobre um índice, esta coluna conterá um valor inteiro representando o número de páginas usadas para armazenar o índice. Se a linha contiver informações sobre a tabela em si, esta coluna conterá um valor inteiro representando o número de páginas usadas para armazenar a tabela.
FILTER_CONDITION | Sempre retorna `null`.

### Veja Também

- db2_column_privileges() - Retorna um conjunto de resultados listando as colunas e privilégios associados para uma tabela
- db2_columns() - Retorna um conjunto de resultados listando as colunas e metadados associados para uma tabela
- db2_foreign_keys() - Retorna um conjunto de resultados listando as chaves estrangeiras para uma tabela
- db2_primary_keys() - Retorna um conjunto de resultados listando as chaves primárias para uma tabela
- db2_procedure_columns() - Retorna um conjunto de resultados listando os parâmetros do procedimento armazenado
- db2_procedures() - Retorna um conjunto de resultados listando os procedimentos armazenados registrados em um banco de dados
- db2_special_columns() - Retorna um conjunto de resultados listando as colunas de identificador de linha exclusivo para uma tabela
- db2_table_privileges() - Retorna um conjunto de resultados listando as tabelas e privilégios associados em um banco de dados
- db2_tables() - Retorna um conjunto de resultados listando as tabelas e metadados associados em um banco de dados

# db2_stmt_error

(PECL ibm_db2 >= 1.0.0)

db2_stmt_error — Retorna uma string contendo o SQLSTATE retornado por uma instrução SQL

### Descrição

function db2_stmt_error(?resource `$stmt` = `null`): string

Retorna uma string contendo o valor SQLSTATE retornado por uma instrução SQL.

Se não for passado um recurso de instrução como um argumento para db2_stmt_error(), o driver retornará o valor SQLSTATE associado à última tentativa de retornar um recurso de instrução, por exemplo, de db2_prepare() ou db2_exec().

Para saber o que o valor SQLSTATE significa, pode ser emitido o seguinte comando em um prompt do Processador de Linha de Comando do DB2: `db2 '? `sqlstate-value`'`. Pode também ser chamada a função db2_stmt_errormsg() para recuperar uma mensagem de erro explícita e o valor SQLCODE associado.

### Parâmetros

`stmt`
  Um recurso de instrução válido.

### Valor Retornado

Retorna uma string contendo um valor SQLSTATE.

### Veja Também

- db2_conn_error() - Retorna uma string contendo o SQLSTATE retornado pela última tentativa de conexão
- db2_conn_errormsg() - Retorna a última mensagem de erro de conexão e o valor SQLCODE
- db2_stmt_errormsg() - Retorna uma string contendo a última mensagem de erro da instrução SQL

# db2_stmt_errormsg

(PECL ibm_db2 >= 1.0.0)

db2_stmt_errormsg — Retorna uma string contendo a última mensagem de erro da instrução SQL

### Descrição

function db2_stmt_errormsg(?resource `$stmt` = `null`): string

Retorna uma string contendo a última mensagem de erro da instrução SQL.

Se não for passado um recurso de instrução como um argumento para db2_stmt_errormsg(), o driver retornará a mensagem de erro associada à última tentativa de retornar um recurso de instrução, por exemplo, de db2_prepare() ou db2_exec().

### Parâmetros

`stmt`
  Um recurso de instrução válido.

### Valor Retornado

Retorna uma string contendo a mensagem de erro e o valor SQLCODE para o último erro que ocorreu ao emitir uma instrução SQL.

### Veja Também

- db2_conn_error() - Retorna uma string contendo o SQLSTATE retornado pela última tentativa de conexão
- db2_conn_errormsg() - Retorna a última mensagem de erro de conexão e o valor SQLCODE
- db2_stmt_error() - Retorna uma string contendo o SQLSTATE retornado por uma instrução SQL

# db2_table_privileges

(PECL ibm_db2 >= 1.0.0)

db2_table_privileges — Retorna um conjunto de resultados listando as tabelas e privilégios associados em um banco de dados

### Descrição

function db2_table_privileges(
resource `$connection`,
?string `$qualifier` = `null`,
?string `$schema` = `null`,
?string `$table_name` = `null`
): resource

Retorna um conjunto de resultados listando as tabelas e privilégios associados em um banco de dados.

### Parâmetros

`connection`
  Uma conexão válida com um banco de dados IBM DB2, Cloudscape ou Apache Derby.
`qualifier`
  Um qualificador para bancos de dados DB2 em execução em servidores OS/390 ou z/OS. Para outros bancos de dados, passe `null` ou uma string vazia.
`schema`
  O esquema que contém as tabelas. Este parâmetro aceita um padrão de pesquisa contendo `_` e `%` como curingas.
`table_name`
  O nome da tabela. Este parâmetro aceita um padrão de pesquisa contendo `_` e `%` como curingas.

### Valor Retornado

Retorna um recurso de declaração com um conjunto de resultados contendo linhas descrevendo os privilégios para as tabelas que correspondem aos parâmetros especificados. As linhas são compostas das seguintes colunas:

Nome da coluna | Descrição
--- | ---
TABLE_CAT | O catálogo que contém a tabela. O valor é `null` se esta tabela não tiver catálogos.
TABLE_SCHEM | Nome do esquema que contém a tabela.
TABLE_NAME | Nome da tabela.
GRANTOR | ID de autorização do usuário que concedeu o privilégio.
GRANTEE | ID de autorização do usuário a quem o privilégio foi concedido.
PRIVILEGE | O privilégio que foi concedido. Pode ser um dos seguintes: ALTER, CONTROL, DELETE, INDEX, INSERT, REFERENCES, SELECT ou UPDATE.
IS_GRANTABLE | Um valor de string de "YES" ou "NO" indicando se o beneficiário pode conceder o privilégio a outros usuários.

### Veja Também

- db2_column_privileges() - Retorna um conjunto de resultados listando as colunas e privilégios associados para uma tabela
- db2_columns() - Retorna um conjunto de resultados listando as colunas e metadados associados para uma tabela
- db2_foreign_keys() - Retorna um conjunto de resultados listando as chaves estrangeiras para uma tabela
- db2_primary_keys() - Retorna um conjunto de resultados listando as chaves primárias para uma tabela
- db2_procedure_columns() - Retorna um conjunto de resultados listando os parâmetros do procedimento armazenado
- db2_procedures() - Retorna um conjunto de resultados listando os procedimentos armazenados registrados em um banco de dados
- db2_special_columns() - Retorna um conjunto de resultados listando as colunas de identificador de linha exclusivo para uma tabela
- db2_statistics() - Retorna um conjunto de resultados listando o índice e as estatísticas de uma tabela
- db2_tables() - Retorna um conjunto de resultados listando as tabelas e metadados associados em um banco de dados

# db2_tables

(PECL ibm_db2 >= 1.0.0)

db2_tables — Retorna um conjunto de resultados listando as tabelas e metadados associados em um banco de dados

### Descrição

function db2_tables(
resource `$connection`,
?string `$qualifier` = `null`,
?string `$schema` = `null`,
?string `$table_name` = `null`,
?string `$table_type` = `null`
): resource

Retorna um conjunto de resultados listando as tabelas e metadados associados em um banco de dados.

### Parâmetros

`connection`
  Uma conexão válida com um banco de dados IBM DB2, Cloudscape ou Apache Derby.
`qualifier`
  Um qualificador para bancos de dados DB2 em execução em servidores OS/390 ou z/OS. Para outros bancos de dados, passe `null` ou uma string vazia.
`schema`
  O esquema que contém as tabelas. Este parâmetro aceita um padrão de pesquisa contendo `_` e `%` como curingas.
`table_name`
  O nome da tabela. Este parâmetro aceita um padrão de pesquisa contendo `_` e `%` como curingas.
`table_type`
  Uma lista de identificadores de tipo de tabela delimitados por vírgulas. Para corresponder a todos os tipos de tabela, passe `null` ou uma string vazia. Identificadores de tipo de tabela válidos incluem: ALIAS, HIERARCHY TABLE, INOPERATIVE VIEW, NICKNAME, MATERIALIZED QUERY TABLE, SYSTEM TABLE, TABLE, TYPED TABLE, TYPED VIEW, e VIEW.

### Valor Retornado

Retorna um recurso de instrução com um conjunto de resultados contendo linhas descrevendo as tabelas que correspondem aos parâmetros especificados. As linhas são compostas pelas seguintes colunas:

Nome da coluna | Descrição
--- | ---
TABLE_CAT | O catálogo que contém a tabela. O valor é `null` se esta tabela não tiver catálogos.
TABLE_SCHEM | Nome do esquema que contém a tabela.
TABLE_NAME | Nome da tabela.
TABLE_TYPE | Identificador do tipo para a tabela.
REMARKS | Descrição da tabela.

### Veja Também

- db2_column_privileges() - Retorna um conjunto de resultados listando as colunas e privilégios associados para uma tabela
- db2_columns() - Retorna um conjunto de resultados listando as colunas e metadados associados para uma tabela
- db2_foreign_keys() - Retorna um conjunto de resultados listando as chaves estrangeiras para uma tabela
- db2_primary_keys() - Retorna um conjunto de resultados listando as chaves primárias para uma tabela
- db2_procedure_columns() - Retorna um conjunto de resultados listando os parâmetros do procedimento armazenado
- db2_procedures() - Retorna um conjunto de resultados listando os procedimentos armazenados registrados em um banco de dados
- db2_special_columns() - Retorna um conjunto de resultados listando as colunas de identificador de linha exclusivo para uma tabela
- db2_statistics() - Retorna um conjunto de resultados listando o índice e as estatísticas de uma tabela
- db2_table_privileges() - Retorna um conjunto de resultados listando as tabelas e privilégios associados em um banco de dados

## Índice

- db2_autocommit — Retorna ou define o estado AUTOCOMMIT para uma conexão de banco de dados
- db2_bind_param — Vincula uma variável PHP a um parâmetro de instrução SQL
- db2_client_info — Retorna um objeto com propriedades que descrevem o cliente do banco de dados DB2
- db2_close — Fecha uma conexão de banco de dados
- db2_column_privileges — Retorna um conjunto de resultados listando as colunas e privilégios associados para uma tabela
- db2_columns — Retorna um conjunto de resultados listando as colunas e metadados associados para uma tabela
- db2_commit — Confirma uma transação
- db2_conn_error — Retorna uma string contendo o SQLSTATE retornado pela última tentativa de conexão
- db2_conn_errormsg — Retorna a última mensagem de erro de conexão e o valor SQLCODE
- db2_connect — Retorna uma conexão com um banco de dados
- db2_cursor_type — Retorna o tipo de cursor usado por um recurso de instrução
- db2_escape_string — Usado para escapar certos caracteres
- db2_exec — Executa uma instrução SQL diretamente
- db2_execute — Executa uma instrução SQL preparada
- db2_fetch_array — Retorna um array, indexado pela posição da coluna, representando uma linha em um conjunto de resultados
- db2_fetch_assoc — Retorna um array, indexado pelo nome da coluna, representando uma linha em um conjunto de resultados
- db2_fetch_both — Retorna um array, indexado pelo nome da coluna e pela posição, representando uma linha em um conjunto de resultados
- db2_fetch_object — Retorna um objeto com propriedades que representam colunas na linha buscada
- db2_fetch_row — Define o ponteiro do conjunto de resultados para a próxima linha ou linha solicitada
- db2_field_display_size — Retorna o número máximo de bytes necessários para exibir uma coluna
- db2_field_name — Retorna o nome da coluna no conjunto de resultados
- db2_field_num — Retorna a posição da coluna nomeada em um conjunto de resultados
- db2_field_precision — Retorna a precisão da coluna indicada em um conjunto de resultados
- db2_field_scale — Retorna a escala da coluna indicada em um conjunto de resultados
- db2_field_type — Retorna o tipo de dados da coluna indicada em um conjunto de resultados
- db2_field_width — Retorna a largura do valor atual da coluna indicada em um conjunto de resultados
- db2_foreign_keys — Retorna um conjunto de resultados listando as chaves estrangeiras para uma tabela
- db2_free_result — Libera recursos associados a um conjunto de resultados
- db2_free_stmt — Libera recursos associados ao recurso de instrução indicado
- db2_get_option — Recupera um valor de opção para um recurso de instrução ou um recurso de conexão
- db2_last_insert_id — Retorna o ID gerado automaticamente da última consulta de inserção que foi executada com sucesso nesta conexão
- db2_lob_read — Obtém um tamanho definido pelo usuário de arquivos LOB com cada invocação
- db2_next_result — Solicita o próximo conjunto de resultados de um procedimento armazenado
- db2_num_fields — Retorna o número de campos contidos em um conjunto de resultados
- db2_num_rows — Retorna o número de linhas afetadas por uma instrução SQL
- db2_pclose — Fecha uma conexão persistente a um banco de dados
- db2_pconnect — Retorna uma conexão persistente a um banco de dados
- db2_prepare — Prepara uma instrução SQL para ser executada
- db2_primary_keys — Retorna um conjunto de resultados listando as chaves primárias para uma tabela
- db2_procedure_columns — Retorna um conjunto de resultados listando os parâmetros do procedimento armazenado
- db2_procedures — Retorna um conjunto de resultados listando os procedimentos armazenados registrados em um banco de dados
- db2_result — Retorna uma única coluna de uma linha no conjunto de resultados
- db2_rollback — Reverte uma transação
- db2_server_info — Retorna um objeto com propriedades que descrevem o servidor de banco de dados DB2
- db2_set_option — Define opções para recursos de conexão ou instrução
- db2_special_columns — Retorna um conjunto de resultados listando as colunas de identificador de linha exclusivo para uma tabela
- db2_statistics — Retorna um conjunto de resultados listando o índice e as estatísticas de uma tabela
- db2_stmt_error — Retorna uma string contendo o SQLSTATE retornado por uma instrução SQL
- db2_stmt_errormsg — Retorna uma string contendo a última mensagem de erro da instrução SQL
- db2_table_privileges — Retorna um conjunto de resultados listando as tabelas e privilégios associados em um banco de dados
- db2_tables — Retorna um conjunto de resultados listando as tabelas e metadados associados em um banco de dados

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
  - Tipos de Recurso
- Constantes predefinidas
- Funções de IBM DB2
  - db2_autocommit — Retorna ou define o estado AUTOCOMMIT para uma conexão de banco de dados
  - db2_bind_param — Vincula uma variável PHP a um parâmetro de instrução SQL
  - db2_client_info — Retorna um objeto com propriedades que descrevem o cliente do banco de dados DB2
  - db2_close — Fecha uma conexão de banco de dados
  - db2_column_privileges — Retorna um conjunto de resultados listando as colunas e privilégios associados para uma tabela
  - db2_columns — Retorna um conjunto de resultados listando as colunas e metadados associados para uma tabela
  - db2_commit — Confirma uma transação
  - db2_conn_error — Retorna uma string contendo o SQLSTATE retornado pela última tentativa de conexão
  - db2_conn_errormsg — Retorna a última mensagem de erro de conexão e o valor SQLCODE
  - db2_connect — Retorna uma conexão com um banco de dados
  - db2_cursor_type — Retorna o tipo de cursor usado por um recurso de instrução
  - db2_escape_string — Usado para escapar certos caracteres
  - db2_exec — Executa uma instrução SQL diretamente
  - db2_execute — Executa uma instrução SQL preparada
  - db2_fetch_array — Retorna um array, indexado pela posição da coluna, representando uma linha em um conjunto de resultados
  - db2_fetch_assoc — Retorna um array, indexado pelo nome da coluna, representando uma linha em um conjunto de resultados
  - db2_fetch_both — Retorna um array, indexado pelo nome da coluna e pela posição, representando uma linha em um conjunto de resultados
  - db2_fetch_object — Retorna um objeto com propriedades que representam colunas na linha buscada
  - db2_fetch_row — Define o ponteiro do conjunto de resultados para a próxima linha ou linha solicitada
  - db2_field_display_size — Retorna o número máximo de bytes necessários para exibir uma coluna
  - db2_field_name — Retorna o nome da coluna no conjunto de resultados
  - db2_field_num — Retorna a posição da coluna nomeada em um conjunto de resultados
  - db2_field_precision — Retorna a precisão da coluna indicada em um conjunto de resultados
  - db2_field_scale — Retorna a escala da coluna indicada em um conjunto de resultados
  - db2_field_type — Retorna o tipo de dados da coluna indicada em um conjunto de resultados
  - db2_field_width — Retorna a largura do valor atual da coluna indicada em um conjunto de resultados
  - db2_foreign_keys — Retorna um conjunto de resultados listando as chaves estrangeiras para uma tabela
  - db2_free_result — Libera recursos associados a um conjunto de resultados
  - db2_free_stmt — Libera recursos associados ao recurso de instrução indicado
  - db2_get_option — Recupera um valor de opção para um recurso de instrução ou um recurso de conexão
  - db2_last_insert_id — Retorna o ID gerado automaticamente da última consulta de inserção que foi executada com sucesso nesta conexão
  - db2_lob_read — Obtém um tamanho definido pelo usuário de arquivos LOB com cada invocação
  - db2_next_result — Solicita o próximo conjunto de resultados de um procedimento armazenado
  - db2_num_fields — Retorna o número de campos contidos em um conjunto de resultados
  - db2_num_rows — Retorna o número de linhas afetadas por uma instrução SQL
  - db2_pclose — Fecha uma conexão persistente a um banco de dados
  - db2_pconnect — Retorna uma conexão persistente a um banco de dados
  - db2_prepare — Prepara uma instrução SQL para ser executada
  - db2_primary_keys — Retorna um conjunto de resultados listando as chaves primárias para uma tabela
  - db2_procedure_columns — Retorna um conjunto de resultados listando os parâmetros do procedimento armazenado
  - db2_procedures — Retorna um conjunto de resultados listando os procedimentos armazenados registrados em um banco de dados
  - db2_result — Retorna uma única coluna de uma linha no conjunto de resultados
  - db2_rollback — Reverte uma transação
  - db2_server_info — Retorna um objeto com propriedades que descrevem o servidor de banco de dados DB2
  - db2_set_option — Define opções para recursos de conexão ou instrução
  - db2_special_columns — Retorna um conjunto de resultados listando as colunas de identificador de linha exclusivo para uma tabela
  - db2_statistics — Retorna um conjunto de resultados listando o índice e as estatísticas de uma tabela
  - db2_stmt_error — Retorna uma string contendo o SQLSTATE retornado por uma instrução SQL
  - db2_stmt_errormsg — Retorna uma string contendo a última mensagem de erro da instrução SQL
  - db2_table_privileges — Retorna um conjunto de resultados listando as tabelas e privilégios associados em um banco de dados
  - db2_tables — Retorna um conjunto de resultados listando as tabelas e metadados associados em um banco de dados

# Extensão MongoDB

Esta extensão é desenvolvida sobre as bibliotecas » libmongoc e » libbson. Ela fornece uma API mínima para a funcionalidade principal do driver: comandos, consultas, gravações, gerenciamento de conexão e serialização BSON.

As bibliotecas Userland PHP que dependem desta extensão podem fornecer APIs de nível superior, como construtores de consultas, métodos auxiliares de comandos individuais e GridFS. Os desenvolvedores de aplicações devem considerar o uso desta extensão em conjunto com a » biblioteca MongoDB PHP, que implementa as mesmas APIs de nível superior encontradas nos drivers MongoDB para outras linguagens. Esta separação de preocupações permite que a extensão se concentre em características essenciais para as quais uma implementação de extensão é fundamental para o desempenho.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução

## Dependências

A partir da versão 1.21.0, a extensão requer PHP 8.1 ou superior. Versões anteriores da extensão permitem compatibilidade com versões mais antigas do PHP.

A extensão requer » libbson e » libmongoc e usará versões agrupadas de ambas as bibliotecas por padrão. Bibliotecas de sistema também podem ser usadas, conforme discutido na documentação de instalação manual.

A extensão, via libmongoc, depende opcionalmente de uma biblioteca TLS (por exemplo, OpenSSL) e irá utilizá-la se disponível. Se o processo de construção não conseguir encontrar uma biblioteca TLS, os usuários devem verificar se o pacote de desenvolvimento apropriado (por exemplo, `libssl-dev`) e » pkg-config estão ambos instalados. O processo para detectar e configurar bibliotecas TLS é discutido com mais detalhes na documentação da instalação manual.

» Cyrus SASL é uma dependência opcional para suportar a autenticação Kerberos e será usada se disponível.

> Nota: Devido a possíveis problemas na representação de números inteiros de 64 bits em plataformas de 32 bits, os usuários são aconselhados a usar ambientes de 64 bits. Ao usar uma plataforma de 32 bits, esteja ciente de que qualquer inteiro de 64 bits lido do banco de dados será retornado como uma instância MongoDB\BSON\Int64 em vez de um tipo inteiro PHP.

## Instalação

## Instalando a extensão MongoDB PHP com PIE

> Nota: PHP Installer for Extensions (PIE) é uma nova ferramenta que tornará o PECL obsoleto. É recomendado usar o PIE para instalar extensões. Descubra mais em » https://github.com/php/pie

Para instalar a extensão MongoDB usando PIE, execute o seguinte comando:

    pie install mongodb/mongodb-extension

## Instalando a extensão MongoDB PHP com PECL

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/mongodb

Usuários de Linux, Unix e macOS podem executar o seguinte comando para instalar a extensão:

    $ sudo pecl install mongodb

Em sistemas com múltiplas versões de PHP instaladas (por exemplo, macOS padrão, Homebrew, » XAMPP), cada versão do PHP terá seu próprio comando pecl e arquivo php.ini. Além disso, cada ambiente PHP (por exemplo, CLI, web) podem usar arquivos php.ini separados.

A partir da versão de extensão 1.17.0, o PECL solicitará várias opções de `configure`. Para instalar a extensão com opções padrão em um script não interativo, a entrada de string vazia pode ser canalizada para `pecl install` usando o comando `yes`:

    $ yes '' | sudo pecl install mongodb

Uma lista completa de opções `configure` suportadas pode ser encontrada no arquivo `package.xml` incluído no pacote PECL. Para instalar a extensão com opções `configure` específicas em um script não interativo, a opção `--configureoptions` para `pecl install` pode ser usada:

    $ sudo pecl install --configureoptions='with-mongodb-system-libs="yes" enable-mongodb-developer-flags="no"' mongodb

Por padrão, a instalação da extensão via PECL usará versões agrupadas de » libbson, » libmongoc e » libmongocrypt e tentará configurá-los automaticamente.

> Nota: Se o processo de construção não conseguir encontrar uma biblioteca SSL, verifique se os pacotes de desenvolvimento (por exemplo, `libssl-dev`) e » pkg-config estão ambos instalados. Se isso não resolver o problema, considere usar o processo de instalação manual.

Finalmente, adicione a seguinte linha ao arquivo php.ini para cada ambiente que precisará usar a extensão:

    extension=mongodb.so

## Instalando a extensão MongoDB PHP no macOS com Homebrew

» Homebrew 1.5.0 descontinuou o » Homebrew/php tap e fórmulas removidas para extensões PHP individuais. A partir de agora, os usuários do macOS são aconselhados a instalar a fórmula » php e seguir a fórmula padrão Instruções de instalação do PECL usando o comando pecl fornecido pela instalação do Homebrew PHP.

Alternativamente, o » shivammathur/extensions fornece fórmulas para extensões PHP individuais. Por exemplo, para instalar uma extensão para PHP 8.4, execute:

    $ brew install shivammathur/extensions/mongodb@8.4

Observe que apenas a versão mais recente da extensão está disponível no brew.

> Nota: Instale as dependências necessárias
> Para garantir que o suporte SSL possa ser configurado corretamente, certifique-se de que os pacotes `openssl` e `pkgconf` estejam instalados. Se qualquer um desses estiver faltando, a extensão será compilada com Secure Transport, o que pode levar a problemas de compatibilidade.

## Instalando a extensão MongoDB PHP no Windows

Os binários pré-compilados são anexados às » versões do Github do projeto. Os arquivos são publicados para várias combinações de versão PHP, segurança de thread (TS ou NTS) e arquitetura (x86 ou x64). Determinar o arquivo correto para o ambiente PHP e extrair o arquivo php_mongodb.dll para o diretório de extensão ("ext" por padrão).

Adicione a seguinte linha ao arquivo php.ini para cada ambiente que precisará usar a extensão:

    extension=php_mongodb.dll

A falha ao selecionar o binário correto resultará em um erro ao tentar carregar a DLL de extensão em tempo de execução:

    PHP Warning:  PHP Startup: Unable to load dynamic library 'mongodb'

Certifique-se de que a DLL baixada corresponda às seguintes propriedades de tempo de execução do PHP:

- Versão do PHP (`PHP_VERSION`)
- Segurança de thread (`PHP_ZTS`)
- Arquitetura (`PHP_INT_SIZE`)

Além das constantes mencionadas acima, essas propriedades também podem ser inferidas de phpinfo(). Se um sistema tiver vários runtimes de execução PHP instalados, verifique novamente se a saída phpinfo() é para o ambiente correto.

> Nota: Dependências adicionais de DLL para usuários do Windows
> Para que esta extensão funcione, existem arquivos DLL que devem estar disponíveis no PATH do sistema Windows. Para saber como fazer isso, veja a FAQ intitulada "Como eu adiciono o meu diretório PHP ao PATH do Windows". Embora copiar arquivos DLL da pasta do PHP para o diretório system do Windows também funcione (porque o diretório system está, por padrão, no PATH do sistema), isso não é recomendado. Esta extensão requer que os seguintes arquivos estejam no PATH: libsasl.dll

## Construindo o driver MongoDB PHP a partir do código-fonte

Para desenvolvedores e usuários interessados nas correções de bugs mais recentes, a extensão pode ser compilada a partir do código-fonte mais recente no » Github. Execute os seguintes comandos para clonar e construir o projeto:

    $ git clone https://github.com/mongodb/mongo-php-driver.git
    $ cd mongo-php-driver
    $ git submodule update --init
    $ phpize
    $ ./configure
    $ make all
    $ sudo make install

Em sistemas com múltiplas versões de PHP instaladas (por exemplo, macOS padrão, Homebrew, » XAMPP), cada versão do PHP terá seu próprio comando phpize e arquivo php.ini. Além disso, cada ambiente PHP (por exemplo, CLI, web) pode usar um arquivo php.ini separado.

Por padrão, a extensão usará versões agrupadas de » libbson, » libmongoc e » libmongocrypt e tentar configurá-los automaticamente. Se essas bibliotecas já estiverem instaladas como bibliotecas de sistema, a extensão poderá utilizá-las especificando `--with-mongodb-system-libs=yes` como uma opção para `configure`.

Para obter uma lista completa de opções de `configure`, execute configure --help.

Ao usar versões empacotadas de libmongoc e libmongocrypt, a extensão também tentará selecionar uma biblioteca SSL de acordo com a opção `--with-mongodb-ssl` `configure`. A partir da versão de extensão 1.17.0, o OpenSSL é sempre preferido por padrão. Anteriormente, o Secure Transport era o padrão no macOS e o OpenSSL era o padrão em todas as outras plataformas.

> Nota: Se o processo de construção não conseguir encontrar uma biblioteca SSL, verifique se os pacotes de desenvolvimento (por exemplo, `libssl-dev`) e » pkg-config estão ambos instalados. Ao usar o Homebrew no macOS, é comum que um sistema tenha várias versões do OpenSSL instaladas. Para garantir que a versão desejada do OpenSSL seja selecionada, a variável de ambiente `PKG_CONFIG_PATH` pode ser usada para controlar o caminho de pesquisa para `pkg-config`.

A etapa final de compilação, make install, reportará onde mongodb.so foi instalado, semelhante a:

    Installing shared extensions:     /usr/lib/php/extensions/debug-non-zts-20220829/

Certifique-se de que a opção extension_dir no php.ini aponta para o diretório onde mongodb.so foi instalado. A opção pode ser consultada executando:

    $ php -i | grep extension_dir
      extension_dir => /usr/lib/php/extensions/debug-non-zts-20220829 =>
                       /usr/lib/php/extensions/debug-non-zts-20220829

Se os diretórios forem diferentes, altere extension_dir no php.ini ou mova manualmente mongodb.so para o diretório correto.

Finalmente, adicione a seguinte linha ao arquivo php.ini para cada ambiente que precisará usar a extensão:

    extension=mongodb.so

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de Configuração de mongodb
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
mongodb.debug | "" | `INI_ALL` |

Aqui está uma breve explicação das diretivas de configuração.

`mongodb.debug` string
  Esta opção pode ser usada para ativar ou desativar o log de depuração em nível de rastreamento na extensão (e libmongoc). Especifique uma string vazia, `"0"`, `"off"`, `"no"` ou `"false"` para desabilitar o log. Especifique `"stderr"` ou `"stdout"` para registrar em `stderr` ou `stdout`, respectivamente. Especifique `"1"`, `"on"`, `"yes"` ou `"true"` para logar em um novo arquivo temporário dentro do diretório temporário padrão do sistema (ou seja, sys_get_temp_dir()). Especifique qualquer outra sequência para logar em um novo arquivo temporário nesse diretório. Se o diretório não puder ser usado, o diretório temporário do sistema padrão será usado.

  > Nota: Observe que o log de depuração pode conter informações confidenciais, como credenciais do servidor MongoDB e documentos completos gravados ou lidos no servidor. Revise todos os registros de depuração antes de compartilhá-los com outras pessoas.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`MONGODB_VERSION` (string)
  Número da versão do estilo x.y.z da extensão
`MONGODB_STABILITY` (string)
  Estabilidade atual (alpha/beta/stable)

# Tutoriais

## Índice

- Usando a Biblioteca do PHP para o MongoDB (PHPLIB)
- Monitoramento de Desempenho de Aplicação (APM)

Nesta seção podem ser encontrados vários tutoriais sobre como usar o driver MongoDB para PHP.

## Usando a Biblioteca do PHP para o MongoDB (PHPLIB)

Após a configuração inicial da extensão, continuaremos explicando como começar a usar a biblioteca correspondente no nível do usuário para escrever nosso primeiro projeto.

## Instalando a Biblioteca do PHP com o Composer

A última coisa que ainda precisamos instalar para começar a usar o aplicativo em si é a biblioteca PHP.

A biblioteca precisa ser instalada com o » Composer, um gerenciador de pacotes para PHP. Instruções para instalar o Composer em diversas plataformas podem ser encontradas em seu site.

Instale a biblioteca executando:

    $ composer require mongodb/mongodb

O resultado será algo como:

    ./composer.json has been created
    Loading composer repositories with package information
    Updating dependencies (including require-dev)
      - Installing mongodb/mongodb (1.0.0)
        Downloading: 100%

    Writing lock file
    Generating autoload files

O Composer criará vários arquivos: `composer.json`, `composer.lock` e um diretório `vendor` que conterá a biblioteca e quaisquer outras dependências do seu projeto pode exigir.

## Usando a Biblioteca do PHP

Além de gerenciar suas dependências, o Composer também fornecerá um carregador automático (para as classes dessas dependências). Certifique-se de que ele esteja incluído no início do seu script ou no código de inicialização da sua aplicação:

    <?php
    // Este caminho deve apontar para o carregador automático do Composer
    require 'vendor/autoload.php';

Com isto feito, agora você pode usar qualquer funcionalidade descrita na » documentação da biblioteca.

Se você usou drivers MongoDB em outras linguagens, a API da biblioteca deverá parecer familiar. Ele contém uma classe » Client para conexão com o MongoDB, uma classe » Database para operações em nível de banco de dados (por exemplo, comandos, gerenciamento de coleção) e uma classe » Collection para operações em nível de coleção (por exemplo, métodos » CRUD, gerenciamento de índice).

Por exemplo, é assim que você insere um documento na coleção beers do banco de dados demo:

    <?php
    require 'vendor/autoload.php'; // inclui o auto-carregador do Composer

    $client = new MongoDB\Client("mongodb://localhost:27017");
    $collection = $client->demo->beers;

    $result = $collection->insertOne( [ 'name' => 'Hinterland', 'brewery' => 'BrewDog' ] );

    echo "Inserido com ID do Objeto '{$result->getInsertedId()}'";
    ?>

Como o documento inserido não continha um campo `_id`, a extensão irá gerar um MongoDB\BSON\ObjectId para o servidor usar como `_id`. Este valor também é disponibilizado ao chamador por meio do objeto de resultado retornado pelo método `insertOne`.

Após a inserção, você pode consultar os dados que acabou de inserir. Para isso, você usa o método `find`, que retorna um cursor iterável:

    <?php
    require 'vendor/autoload.php'; // inclui o auto-carregador do Composer

    $client = new MongoDB\Client("mongodb://localhost:27017");
    $collection = $client->demo->beers;

    $result = $collection->find( [ 'name' => 'Hinterland', 'brewery' => 'BrewDog' ] );

    foreach ($result as $entry) {
        echo $entry['_id'], ': ', $entry['name'], "\n";
    }
    ?>

Embora possa não ser aparente nos exemplos, os documentos e arrays do BSON são desserializados como classes especiais na biblioteca por padrão. Essas classes estendem ArrayObject para usabilidade e implementam as interfaces MongoDB\BSON\Serializable e MongoDB\BSON\Unserializable da extensão para garantir que os valores preservem seu tipo quando serializados de volta para BSON. Isso evita uma ressalva na extensão `mongo` legada, onde arrays podem se transformar em documentos e vice-versa. Consulte a especificação Dados Persistentes para obter mais informações sobre como os valores são convertidos entre PHP e BSON.

## Monitoramento de Desempenho de Aplicação (APM)

A extensão contém uma API de assinante de evento, que permite que as aplicações monitorem comandos e atividades internas pertencentes à » Especificação de Descoberta e Monitoramento de Servidor. Este tutorial demonstrará o monitoramento de comandos usando A interface MongoDB\Driver\Monitoring\CommandSubscriber.

A interface MongoDB\Driver\Monitoring\CommandSubscriber define três métodos: `commandStarted`, `commandSucceeded` e `commandFailed`. Cada um desses três métodos aceita um único argumento `event` de uma classe específica para o respectivo evento. Por exemplo, o argumento `$event` de `commandSucceeded` é um objeto MongoDB\Driver\Monitoring\CommandSucceededEvent.

Neste tutorial implementaremos um assinante que cria uma lista de todos os perfis de consulta e o tempo médio gasto para fazê-lo.

## Preparando a Classe do Assinante

Começamos com a estrutura para nosso assinante:

    <?php

    class QueryTimeCollector implements \MongoDB\Driver\Monitoring\CommandSubscriber
    {
        public function commandStarted( \MongoDB\Driver\Monitoring\CommandStartedEvent $event ): void
        {
        }

        public function commandSucceeded( \MongoDB\Driver\Monitoring\CommandSucceededEvent $event ): void
        {
        }

        public function commandFailed( \MongoDB\Driver\Monitoring\CommandFailedEvent $event ): void
        {
        }
    }

    ?>

## Registrando o Assinante

Depois que um objeto assinante é instanciado, ele precisa ser registrado no sistema de monitoramento das extensões. Isso é feito chamando MongoDB\Driver\Monitoring\addSubscriber() ou MongoDB\Driver\Manager::addSubscriber() para registrar o assinante globalmente ou com um gerenciador específico, respectivamente.

    <?php

    \MongoDB\Driver\Monitoring\addSubscriber( new QueryTimeCollector() );

    ?>

## Implementando a Lógica

Com o objeto registrado, só falta implementar a lógica na classe do assinante. Para correlacionar os dois eventos que compõem um comando executado com sucesso (commandStarted e commandSucceeded), cada objeto de evento expõe um campo `requestId`.

Para registrar o tempo médio por formato de consulta, começaremos verificando um comando `find` no evento commandStarted. Adicionaremos então um item à propriedade `pendingCommands` indexado por seu `requestId` e com seu valor representando o formato da consulta.

Se recebermos um evento commandSucceeded correspondente com o mesmo `requestId`, adicionamos a duração do evento (de `durationMicros`) ao tempo total e incrementamos a contagem da operação.

Se um evento commandFailed correspondente for encontrado, apenas removemos a entrada da propriedade `pendingCommands`.

    <?php

    class QueryTimeCollector implements \MongoDB\Driver\Monitoring\CommandSubscriber
    {
        private $pendingCommands = [];
        private $queryShapeStats = [];

        /* Cria um formato de consulta a partir do argumento do filtro. No momento, ele leva
         * em consideração apenas os campos de nível superior */
        private function createQueryShape( array $filter )
        {
            return json_encode( array_keys( $filter ) );
        }

        public function commandStarted( \MongoDB\Driver\Monitoring\CommandStartedEvent $event ): void
        {
            if ( 'find' === $event->getCommandName() )
            {
                $queryShape = $this->createQueryShape( (array) $event->getCommand()->filter );
                $this->pendingCommands[$event->getRequestId()] = $queryShape;
            }
        }

        public function commandSucceeded( \MongoDB\Driver\Monitoring\CommandSucceededEvent $event ): void
        {
            $requestId = $event->getRequestId();
            if ( array_key_exists( $requestId, $this->pendingCommands ) )
            {
                $this->queryShapeStats[$this->pendingCommands[$requestId]]['count']++;
                $this->queryShapeStats[$this->pendingCommands[$requestId]]['duration'] += $event->getDurationMicros();
                unset( $this->pendingCommands[$requestId] );
            }
        }

        public function commandFailed( \MongoDB\Driver\Monitoring\CommandFailedEvent $event ): void
        {
            if ( array_key_exists( $event->getRequestId(), $this->pendingCommands ) )
            {
                unset( $this->pendingCommands[$event->getRequestId()] );
            }
        }

        public function __destruct()
        {
            foreach( $this->queryShapeStats as $shape => $stats )
            {
                echo "Formato: ", $shape, " (", $stats['count'], ")\n  ",
                    $stats['duration'] / $stats['count'], "µs\n\n";
            }
        }
    }

    $m = new \MongoDB\Driver\Manager( 'mongodb://localhost:27016' );

    /* Adiciona o assinante */
    \MongoDB\Driver\Monitoring\addSubscriber( new QueryTimeCollector() );

    /* Realiza um número de consultas */
    $query = new \MongoDB\Driver\Query( [
        'region_slug' => 'scotland-highlands', 'age' => [ '$gte' => 20 ]
    ] );
    $cursor = $m->executeQuery( 'dramio.whisky', $query );

    $query = new \MongoDB\Driver\Query( [
        'region_slug' => 'scotland-lowlands', 'age' => [ '$gte' => 15 ]
    ] );
    $cursor = $m->executeQuery( 'dramio.whisky', $query );

    $query = new \MongoDB\Driver\Query( [ 'region_slug' => 'scotland-lowlands' ] );
    $cursor = $m->executeQuery( 'dramio.whisky', $query );

    ?>

# Explica a arquitetura do driver e recursos especiais

## Índice

- Arquitetura
- Conexões
- Dados Persistentes

## Visão geral da arquitetura

Este artigo explica como todos os diferentes componentes do driver PHP se encaixam, desde as bibliotecas básicas do sistema, passando pela extensão, até as bibliotecas PHP superiores.

No topo desta pilha está uma » biblioteca PHP, que é distribuída como um » Pacote Composer. Esta biblioteca fornece uma API consistente com outros » drivers do MongoDB e implementa várias » especificações de drivers cruzados. Embora a extensão possa ser usada diretamente, a biblioteca tem sobrecarga mínima e deve ser uma dependência comum para a maioria das aplicações criadas com MongoDB.

Abaixo dessa biblioteca está uma extensão PHP, que é distribuída através de » PECL. A extensão forma a ligação entre o PHP e nossas bibliotecas de sistema (» libmongoc, » libbson e » libmongocrypt). Sua API pública fornece apenas as funcionalidades mais essenciais:

- Gerenciamento de conexões
- Codificação e decodificação BSON
- Serialização de documentos de objetos (para suportar bibliotecas ODM)
- Executar comandos, consultas e operações de gravação
- Manipulação de cursores para resultados de comandos e consultas

Código-fonte do driver e projetos JIRA
Projeto | GitHub | JIRA
--- | --- | ---
Biblioteca PHP | » mongodb/mongo-php-library | » PHPLIB
Extensão PHP | » mongodb/mongo-php-driver | » PHPC

## Manipulação de conexão e persistência

> Nota: Em plataformas Unix, a extensão é sensível a scripts que usam a chamada de sistema fork() sem chamar também exec(). Os usuários são aconselhados a não reusar instâncias de MongoDB\Driver\Manager em um processo filho bifurcado.

## Persistência de conexão e topologia (versão PHP desde 1.2.0)

Todas as versões da extensão desde 1.2.0 persistem o objeto cliente » libmongoc no processo de trabalho do PHP, o que permite reutilizar conexões de banco de dados, autenticação de estados, e informações de topologia em diversas solicitações.

Quando MongoDB\Driver\Manager::__construct() é invocado, um hash é criado a partir de seus argumentos (ou seja, string URI e opções de array). A extensão tentará encontrar um objeto cliente » libmongoc anteriormente persistente para esse hash. Se um cliente existente não puder ser encontrado para o hash, um novo cliente será criado e persistido para uso futuro. Este comportamento pode ser desabilitado através da opção do driver `"disableClientPersistence"`.

Cada cliente contém suas próprias conexões de banco de dados e uma visão da topologia do servidor (por exemplo, standalone, replica set, shard cluster). Ao persistir o cliente entre solicitações PHP, a extensão é capaz de reutilizar conexões de banco de dados estabelecidas e eliminar a necessidade de » descobrir a topologia do servidor em cada solicitação.

Considere o seguinte exemplo:

    <?php

    $managers = [
        new MongoDB\Driver\Manager('mongodb://127.0.0.1'),
        new MongoDB\Driver\Manager('mongodb://127.0.0.1'),
        new MongoDB\Driver\Manager('mongodb://127.0.0.1:27017'),
        new MongoDB\Driver\Manager('mongodb://rs1.example.com,rs2.example.com/', ['replicaSet' => 'myReplicaSet']),
    ];

    foreach ($managers as $manager) {
        $manager->executeCommand('test', new MongoDB\Driver\Command(['ping' => 1]));
    }

    ?>

Os dois primeiros objetos Manager compartilharão o mesmo cliente » libmongoc, pois seus argumentos construtores são idênticos. O terceiro e o quarto objetos usarão cada um seu próprio cliente. No total, três clientes serão criados e o worker PHP que executa este script abrirá duas conexões para `127.0.0.1` e uma conexão para cada um de `rs1.example.com` e `rs2.example.com`. Se a extensão descobrir membros adicionais do conjunto de réplicas após emitir comandos `hello`, ela também abrirá conexões adicionais com esses servidores.

Se o mesmo worker executar o script novamente em uma segunda solicitação, os três clientes serão reutilizados e nenhuma nova conexão será feita. Dependendo de há quanto tempo a solicitação anterior foi atendida, a extensão pode precisar emitir comandos `hello` adicionais para atualizar sua visualização das topologias.

## Persistência de socket (versões PHP anteriores a 1.2.0)

Versões da extensão anteriores a 1.2.0 utilizam a API de Fluxos do PHP para conexões de banco de dados, usando uma API dentro de » libmongoc para designar manipuladores personalizados para comunicação de socket; entretanto, um novo cliente libmongoc é criado para cada MongoDB\Driver\Manager. Como resultado, a extensão persiste em conexões de banco de dados individuais, mas não no estado de autenticação ou nas informações de topologia. Isso significa que a extensão precisa emitir comandos no início de cada solicitação para autenticar e » descobrir a topologia do servidor.

As conexões de banco de dados são persistidas por um hash derivado do host do servidor, da porta e da string URI usada para construir o MongoDB\Driver\Manager. As opções de array do construtor n ão estão incluídas neste hash.

> Nota: Versões da extensão >= 1.1.8 e < 1.2.0 não persiste sockets para conexões SSL. Consulte » PHPC-720 para obter informações adicionais.

Apesar de suas deficiências com conexões SSL persistentes e informações de topologia, esta versão da extensão suporta todas as opções de contexto SSL, uma vez que usa a API de Fluxos do PHP.

## Serialização e desserialização de variáveis PHP no MongoDB

Este documento discute como estruturas compostas (ou seja, documentos, arrays e objetos) são convertidas entre valores BSON e PHP.

## Serialização para BSON

## Arrays

Se um array for um array compactado - ou seja, um array vazio ou as chaves começam em 0 e são sequenciais sem lacunas: array BSON.

Se o array não estiver compactado - ou seja, tiver chaves associativas (string), as chaves não começam em 0 ou quando há lacunas:: objeto BSON

Um documento de nível superior (raiz), sempre serializa como um documento BSON.

## Exemplos

Estes são serializados como um array BSON:

    [ 8, 5, 2, 3 ] => [ 8, 5, 2, 3 ]
    [ 0 => 4, 1 => 9 ] => [ 4, 9 ]

Estes são serializados como um documento BSON:

    [ 0 => 1, 2 => 8, 3 => 12 ] => { "0" : 1, "2" : 8, "3" : 12 }
    [ "foo" => 42 ] => { "foo" : 42 }
    [ 1 => 9, 0 => 10 ] => { "1" : 9, "0" : 10 }

Observe que os cinco exemplos são extraídos de um documento completo e representam apenas um valor dentro de um documento.

## Objetos

Se um objeto for da classe stdClass, serialize como um documento BSON.

Se um objeto for de uma classe suportada que implementa MongoDB\BSON\Type, use a lógica de serialização BSON para esse tipo específico. Instâncias MongoDB\BSON\Type, excluindo MongoDB\BSON\Serializable, só podem ser serializadas como um valor de campo de documento. Tentar serializar tal objeto como um documento raiz lançará uma exceção MongoDB\Driver\Exception\UnexpectedValueException

Se um objeto for de uma classe desconhecida que implementa a interface MongoDB\BSON\Type, lance uma exceção MongoDB\Driver\Exception\UnexpectedValueException

Se um objeto for de qualquer outra classe, sem implementar nenhuma interface especial, serialize como um documento BSON. Mantenha apenas propriedades públicas e ignore propriedades protegidas e privadas.

Se um objeto for de uma classe que implementa a interface MongoDB\BSON\Serializable, chame MongoDB\BSON\Serializable::bsonSerialize() e use o array retornado ou stdClass para serializar como um documento ou array BSON. O tipo BSON será determinado pelo seguinte:

1. Os documentos raiz devem ser serializados como um documento BSON.
2. Os objetos MongoDB\BSON\Persistable devem ser serializados como um documento BSON.
3. Se MongoDB\BSON\Serializable::bsonSerialize() retornar um array compactado, serialize como um array BSON.
4. Se MongoDB\BSON\Serializable::bsonSerialize() retornar um array não compactado ou stdClass, serialize como um documento BSON.
5. Se MongoDB\BSON\Serializable::bsonSerialize() não retornou um array ou stdClass, lance uma exceção MongoDB\Driver\Exception\UnexpectedValueException.

Se um objeto for de uma classe que implementa a interface MongoDB\BSON\Persistable (o que implica MongoDB\BSON\Serializable), obtenha as propriedades de maneira semelhante à parágrafos anteriores, mas também adicione uma propriedade adicional __pclass como um valor binário, com subtipo `0x80` e dados contendo o nome completo da classe do objeto que está sendo serializado.

A propriedade __pclass é adicionada ao array ou objeto retornado por MongoDB\BSON\Serializable::bsonSerialize(), o que significa que ela substituirá qualquer chave/propriedade __pclass no valor de retorno MongoDB\BSON\Serializable::bsonSerialize(). Se você quiser evitar esse comportamento e definir seu próprio valor __pclass, você não deve implementar MongoDB\BSON\Persistable e, em vez disso, deve implementar MongoDB\BSON\Serializable diretamente.

## Exemplos

    <?php

    class stdClass
    {
        public $foo = 42;
    } // => {"foo": 42}

    class MyClass
    {
        public $foo = 42;
        protected $prot = 'wine';
        private $fpr = 'cheese';
    } // => {"foo": 42}

    class AnotherClass1 implements MongoDB\BSON\Serializable
    {
        public $foo = 42;
        protected $prot = 'wine';
        private $fpr = 'cheese';

        public function bsonSerialize(): array
        {
            return ['foo' => $this->foo, 'prot' => $this->prot];
        }
    } // => {"foo": 42, "prot": "wine"}

    class AnotherClass2 implements MongoDB\BSON\Serializable
    {
        public $foo = 42;

        public function bsonSerialize(): self
        {
            return $this;
        }
    } // => MongoDB\Driver\Exception\UnexpectedValueException("bsonSerialize() did not return an array or stdClass")

    class AnotherClass3 implements MongoDB\BSON\Serializable
    {
        private $elements = ['foo', 'bar'];

        public function bsonSerialize(): array
        {
            return $this->elements;
        }
    } // => {"0": "foo", "1": "bar"}

    /**
     * Aninhando Classes Serializáveis
     */

    class AnotherClass4 implements MongoDB\BSON\Serializable
    {
        private $elements = [0 => 'foo', 2 => 'bar'];

        public function bsonSerialize(): array
        {
            return $this->elements;
        }
    } // => {"0": "foo", "2": "bar"}

    class ContainerClass1 implements MongoDB\BSON\Serializable
    {
        public $things;

        public function __construct()
        {
            $this->things = new AnotherClass4();
        }

        function bsonSerialize(): array
        {
            return ['things' => $this->things];
        }
    } // => {"things": {"0": "foo", "2": "bar"}}

    class AnotherClass5 implements MongoDB\BSON\Serializable
    {
        private $elements = [0 => 'foo', 2 => 'bar'];

        public function bsonSerialize(): array
        {
            return array_values($this->elements);
        }
    } // => {"0": "foo", "1": "bar"} como uma classe raiz
      //    ["foo", "bar"] como um valor aninhado

    class ContainerClass2 implements MongoDB\BSON\Serializable
    {
        public $things;

        public function __construct()
        {
            $this->things = new AnotherClass5();
        }

        public function bsonSerialize(): array
        {
            return ['things' => $this->things];
        }
    } // => {"things": ["foo", "bar"]}

    class AnotherClass6 implements MongoDB\BSON\Serializable
    {
        private $elements = ['foo', 'bar'];

        function bsonSerialize(): object
        {
            return (object) $this->elements;
        }
    } // => {"0": "foo", "1": "bar"}

    class ContainerClass3 implements MongoDB\BSON\Serializable
    {
        public $things;

        public function __construct()
        {
            $this->things = new AnotherClass6();
        }

        public function bsonSerialize(): array
        {
            return ['things' => $this->things];
        }
    } // => {"things": {"0": "foo", "1": "bar"}}

    class UpperClass implements MongoDB\BSON\Persistable
    {
        public $foo = 42;
        protected $prot = 'wine';
        private $fpr = 'cheese';

        private $data;

        public function bsonUnserialize(array $data): void
        {
            $this->data = $data;
        }

        public function bsonSerialize(): array
        {
            return ['foo' => $this->foo, 'prot' => $this->prot];
        }
    } // => {"foo": 42, "prot": "wine", "__pclass": {"$type": "80", "$binary": "VXBwZXJDbGFzcw=="}}

    ?>

## Desserialização do BSON

Aviso

Os documentos BSON tecnicamente podem conter chaves duplicadas porque os documentos são armazenados como uma lista de pares chave-valor; no entanto, as aplicações devem evitar a geração de documentos com chaves duplicadas, pois o comportamento do servidor e do driver pode ser indefinido. Como os objetos e arrays do PHP não podem ter chaves duplicadas, os dados também podem ser perdidos ao decodificar um documento BSON com chaves duplicadas.

A extensão `mongo` herdada desserializou documentos BSON e arrays como arrays PHP. Embora arrays PHP sejam c onvenientes para trabalhar, esse comportamento era problemático porque diferentes tipos de BSON poderiam desserializar para o mesmo valor PHP (por exemplo, `{"0": "foo"}` e `["foo"]`) e torna impossível inferir o tipo BSON original. Por padrão, a extensão `mongodb` aborda essa preocupação garantindo que arrays e documentos BSON sejam convertidos em arrays e objetos PHP, respectivamente.

Para tipos compostos, existem três tipos de dados:

root
  refere-se ao documento BSON de nível superior apenas
document
  refere-se a documentos BSON incorporados apenas
array
  refere-se a um array BSON

Além dos três tipos de coletivos, também é possível configurar campos específicos em seu documento para mapear os tipos de dados mencionados abaixo. Como exemplo, o seguinte mapa de tipos permite a você mapear cada documento incorporado dentro de um array `"addresses"` para uma classe Address e cada `"city"` dentro desses documentos de endereço incorporados para uma classe City:

    [
        'fieldPaths' => [
            'addresses.$' => 'MyProject\Address',
            'addresses.$.city' => 'MyProject\City',
        ],
    ]

Cada um desses três tipos de dados, bem como os mapeamentos específicos de campo, podem ser mapeados em diferentes tipos de PHP. Os possíveis valores de mapeamento são:

não definido ou NULL (padrão)

  - Um array BSON será desserializado como um array PHP.
  - Um documento BSON (raiz ou incorporado) sem uma propriedade __pclass [1]

    Uma propriedade __pclass só é considerada existente se existir uma propriedade com esse nome, e for um valor Binário, e o subtipo do valor Binário for 0x80. Se alguma dessas três condições não for atendida, a propriedade __pclass não existe e deverá ser tratada como qualquer outra propriedade normal.

    torna-se um objeto PHP stdClass, com cada chave de documento BSON definida como uma propriedade pública stdClass.
  - Um documento BSON (raiz ou incorporado) com uma propriedade __pclass [1] torna-se um objeto PHP com o nome da classe conforme definido pela propriedade __pclass. Se a classe nomeada implementar a interface MongoDB\BSON\Persistable, então as propriedades do documento BSON, incluindo a propriedade __pclass, serão enviadas como um array associativo para a função MongoDB\BSON\Unserializable::bsonUnserialize() para inicializar as propriedades do objeto. Se a classe nomeada não existir ou não implementar a interface MongoDB\BSON\Persistable, stdClass será usada e cada chave de documento BSON (incluindo __pclass) será definido como uma propriedade pública stdClass. A funcionalidade __pclass depende da propriedade fazer parte de um documento MongoDB recuperado. Se você usar uma projeção ao consultar documentos, será necessário incluir o campo __pclass na projeção para esta funcionalidade trabalhar.
`"array"`
  Transforma um array BSON ou documento BSON em um array PHP. Não haverá tratamento especial para uma propriedade __pclass [1], mas ela poderá ser definida como um elemento no array retornado se estiver presente no documento BSON.
`"object"` ou `"stdClass"`
  Transforma um array BSON ou documento BSON em um objeto stdClass. Não haverá tratamento especial para uma propriedade __pclass [1], mas ela poderá ser definida como uma propriedade pública no objeto retornado se estiver presente no documento BSON.
`"bson"`
  Transforma um array BSON em um MongoDB\BSON\PackedArray e um documento BSON em um MongoDB\BSON\Document, independentemente de o documento BSON ter uma propriedade __pclass [1].

  > Nota: O valor `bson` está disponível apenas para os três tipos de raiz, não nos mapeamentos específicos do campo.

qualquer outra string
  Define o nome da classe como um array BSON ou o objeto BSON deve ser desserializado. Para objetos BSON que incluem propriedades __pclass, essa classe terá prioridade. Se a classe nomeada não existir, não for concreta (ou seja, for abstrata ou uma interface) ou não implementar MongoDB\BSON\Unserializable então uma exceção MongoDB\Driver\Exception\InvalidArgumentException é lançada. Se o objeto BSON tiver uma propriedade __pclass e essa classe existir e implementar MongoDB\BSON\Persistable ela substituirá a classe fornecida no mapa de tipos. As propriedades do documento BSON, incluindo a propriedade __pclass se existir, serão enviadas como um array associativo para a função MongoDB\BSON\Unserializable::bsonUnserialize() para inicializar as propriedades do objeto.

## TypeMaps

TypeMaps podem ser definidos através do método MongoDB\Driver\Cursor::setTypeMap() em um objeto MongoDB\Driver\Cursor ou do argumento `$typeMap` de MongoDB\BSON\toPHP(), MongoDB\BSON\Document::toPHP() e MongoDB\BSON\PackedArray::toPHP(). Cada uma das três classes (root, document e array) pode ser definida individualmente, além dos tipos específicos de campo.

Se o valor no mapa for NULL, significa o mesmo que o valor padrão para esse item.

## Exemplos

Esses exemplos usam as seguintes classes:

MyClass
  que não implementa nenhuma interface
YourClass
  que implementa MongoDB\BSON\Unserializable
OurClass
  que implementa MongoDB\BSON\Persistable
TheirClass
  que estende OurClass

O método MongoDB\BSON\Unserializable::bsonUnserialize() de YourClass, OurClass, TheirClass itera sobre o array e define as propriedades sem modificações. Ele também define a propriedade `$unserialized` como `true`:

    <?php

    function bsonUnserialize( array $map )
    {
        foreach ( $map as $k => $value )
        {
            $this->$k = $value;
        }
        $this->unserialized = true;
    }

    /* typemap: [] (all defaults) */
    { "foo": "yes", "bar" : false }
      -> stdClass { $foo => 'yes', $bar => false }

    { "foo": "no", "array" : [ 5, 6 ] }
      -> stdClass { $foo => 'no', $array => [ 5, 6 ] }

    { "foo": "no", "obj" : { "embedded" : 3.14 } }
      -> stdClass { $foo => 'no', $obj => stdClass { $embedded => 3.14 } }

    { "foo": "yes", "__pclass": "MyClass" }
      -> stdClass { $foo => 'yes', $__pclass => 'MyClass' }

    { "foo": "yes", "__pclass": { "$type" : "80", "$binary" : "MyClass" } }
      -> stdClass { $foo => 'yes', $__pclass => Binary(0x80, 'MyClass') }

    { "foo": "yes", "__pclass": { "$type" : "80", "$binary" : "YourClass") }
      -> stdClass { $foo => 'yes', $__pclass => Binary(0x80, 'YourClass') }

    { "foo": "yes", "__pclass": { "$type" : "80", "$binary" : "OurClass") }
      -> OurClass { $foo => 'yes', $__pclass => Binary(0x80, 'OurClass'), $unserialized => true }

    { "foo": "yes", "__pclass": { "$type" : "44", "$binary" : "YourClass") }
      -> stdClass { $foo => 'yes', $__pclass => Binary(0x44, 'YourClass') }

    /* typemap: [ "root" => "MissingClass" ] */
    { "foo": "yes" }
      -> MongoDB\Driver\Exception\InvalidArgumentException("MissingClass does not exist")

    /* typemap: [ "root" => "MyClass" ] */
    { "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MyClass" } }
      -> MongoDB\Driver\Exception\InvalidArgumentException("MyClass does not implement Unserializable interface")

    /* typemap: [ "root" => "MongoDB\BSON\Unserializable" ] */
    { "foo": "yes" }
      -> MongoDB\Driver\Exception\InvalidArgumentException("Unserializable is not a concrete class")

    /* typemap: [ "root" => "YourClass" ] */
    { "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MongoDB\BSON\Unserializable" } }
      -> YourClass { $foo => "yes", $__pclass => Binary(0x80, "MongoDB\BSON\Unserializable"), $unserialized => true }

    /* typemap: [ "root" => "YourClass" ] */
    { "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MyClass" } }
      -> YourClass { $foo => "yes", $__pclass => Binary(0x80, "MyClass"), $unserialized => true }

    /* typemap: [ "root" => "YourClass" ] */
    { "foo": "yes", "__pclass" : { "$type": "80", "$binary": "OurClass" } }
      -> OurClass { $foo => "yes", $__pclass => Binary(0x80, "OurClass"), $unserialized => true }

    /* typemap: [ "root" => "YourClass" ] */
    { "foo": "yes", "__pclass" : { "$type": "80", "$binary": "TheirClass" } }
      -> TheirClass { $foo => "yes", $__pclass => Binary(0x80, "TheirClass"), $unserialized => true }

    /* typemap: [ "root" => "OurClass" ] */
    { foo: "yes", "__pclass" : { "$type": "80", "$binary": "TheirClass" } }
      -> TheirClass { $foo => "yes", $__pclass => Binary(0x80, "TheirClass"), $unserialized => true }

    /* typemap: [ 'root' => 'YourClass' ] */
    { foo: "yes", "__pclass" : { "$type": "80", "$binary": "YourClass" } }
      -> YourClass { $foo => 'yes', $__pclass => Binary(0x80, 'YourClass'), $unserialized => true }

    /* typemap: [ 'root' => 'array', 'document' => 'array' ] */
    { "foo": "yes", "bar" : false }
      -> [ "foo" => "yes", "bar" => false ]

    { "foo": "no", "array" : [ 5, 6 ] }
      -> [ "foo" => "no", "array" => [ 5, 6 ] ]

    { "foo": "no", "obj" : { "embedded" : 3.14 } }
      -> [ "foo" => "no", "obj" => [ "embedded => 3.14 ] ]

    { "foo": "yes", "__pclass": "MyClass" }
      -> [ "foo" => "yes", "__pclass" => "MyClass" ]

    { "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MyClass" } }
      -> [ "foo" => "yes", "__pclass" => Binary(0x80, "MyClass") ]

    { "foo": "yes", "__pclass" : { "$type": "80", "$binary": "OurClass" } }
      -> [ "foo" => "yes", "__pclass" => Binary(0x80, "OurClass") ]

    /* typemap: [ 'root' => 'object', 'document' => 'object' ] */
    { "foo": "yes", "__pclass": { "$type": "80", "$binary": "MyClass" } }
      -> stdClass { $foo => "yes", "__pclass" => Binary(0x80, "MyClass") }

# Segurança

## Índice

- Ataques de Injeção de Requisição
- Ataques de injeção de script

## Ataques de Injeção de Requisição

Se você estiver passando parâmetros `$_GET` (ou `$_POST`) para suas consultas, certifique-se de que eles sejam convertidos em strings primeiro. Os usuários podem inserir arrays associativos em solicitações GET e POST, que podem se tornar consultas indesejadas.

Um exemplo bastante inócuo: suponha que você esteja procurando informações de um usuário com a solicitação http://www.example.com?username=bob. Sua aplicação cria a consulta `$q = new \MongoDB\Driver\Query( [ 'username' => $_GET['username'] ])`.

Alguém poderia subverter isso obtendo http://www.example.com?username[$ne]=foo, que o PHP transformará magicamente em um array associativo, transformando sua consulta em `$q = new \MongoDB\Driver\Query( [ 'username' => [ '$ne' => 'foo' ] ] )`, que retornará todos os usuários não nomeados "foo" (todos os seus usuários, provavelmente).

Este é um ataque bastante fácil de se defender: certifique-se de que os parâmetros $_GET e $_POST sejam do tipo que você espera antes de enviá-los ao banco de dados. O PHP tem a função filter_var() para ajudar nisso.

Observe que esse tipo de ataque pode ser usado com qualquer interação de banco de dados que localize um documento, incluindo atualizações, inclusões, exclusões e comandos findAndModify.

Consulte » a documentação principal para obter mais informações sobre problemas semelhantes à injeção de SQL com o MongoDB.

## Ataques de injeção de script

Se você estiver usando JavaScript, certifique-se de que quaisquer variáveis que cruzem o limite PHP para JavaScript sejam passadas no campo `scope` do MongoDB\BSON\Javascript, e não interpoladas em string JavaScript. Isso pode surgir ao usar cláusulas `$where` em consultas, mapReduce e comandos de grupo, e em qualquer outro momento em que você passar JavaScript para o banco de dados.

Por exemplo, suponha que temos algum JavaScript para cumprimentar um usuário nos logs do banco de dados. Nós poderíamos fazer:

    <?php
    $m = new MongoDB\Driver\Manager;

    // Não faça isso!!!
    $username = $_GET['field'];

    $cmd = new \MongoDB\Driver\Command( [
        'eval' => "print('Olá, $username!');"
    ] );

    $r = $m->executeCommand( 'dramio', $cmd );
    ?>

No entanto, e se um usuário mal intencionado passar algum JavaScript?

    <?php
    $m = new MongoDB\Driver\Manager;

    // Não faça isso!!!
    $username = $_GET['field'];
    // $username é definido como "'); db.users.drop(); print('"

    $cmd = new \MongoDB\Driver\Command( [
        'eval' => "print('Olá, $username!');"
    ] );

    $r = $m->executeCommand( 'dramio', $cmd );
    ?>

Agora o MongoDB executa a string JavaScript `"print('Olá, '); db.users.drop(); print('!');"`. Este ataque é fácil de evitar: use `args` para passar variáveis de PHP para JavaScript:

    <?php
    $m = new MongoDB\Driver\Manager;

    $_GET['field'] = 'derick';
    $args = [ $_GET['field'] ];

    $cmd = new \MongoDB\Driver\Command( [
        'eval' => "function greet(username) { print('Olá, ' + username + '!'); }",
        'args' => $args,
    ] );

    $r = $m->executeCommand( 'dramio', $cmd );
    ?>

Isto adiciona um argumento ao escopo JavaScript, que é usado como argumento para a função `greet`. Agora, se alguém tentar enviar código malicioso, o MongoDB imprimirá inofensivamente `Olá, '); db.dropDatabase(); print('!`.

O uso de argumentos ajuda a evitar que entradas maliciosas sejam executadas pelo banco de dados. Porém, você deve garantir que seu código não vire e execute a entrada de qualquer maneira! Em primeiro lugar, é melhor evitar executar qualquer JavaScript no servidor.

É altamente recomendável evitar a » cláusula $where nas consultas, pois ela afeta significativamente o desempenho. Sempre que possível, use operadores de consulta normais ou o » Estrutura de agregação.

Como alternativa ao » MapReduce, que usa JavaScript, considere usar o » Estrutura de agregação. Ao contrário do Map/Reduce, ele usa uma linguagem idiomática para construir consultas, sem ter que escrever e usar a abordagem JavaScript mais lenta que o Map/Reduce requer.

O » comando eval foi descontinuado desde o MongoDB 3.0 e também deve ser evitado.

# Classes da Extensão MongoDB

## Índice

- MongoDB\Driver\Manager
- MongoDB\Driver\Command
- MongoDB\Driver\Query
- MongoDB\Driver\BulkWrite
- MongoDB\Driver\BulkWriteCommand
- MongoDB\Driver\Session
- MongoDB\Driver\ClientEncryption
- MongoDB\Driver\ServerApi
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\ReadPreference
- MongoDB\Driver\ReadConcern
- MongoDB\Driver\Cursor
- MongoDB\Driver\CursorId
- MongoDB\Driver\CursorInterface
- MongoDB\Driver\Server
- MongoDB\Driver\ServerDescription
- MongoDB\Driver\TopologyDescription
- MongoDB\Driver\WriteConcernError
- MongoDB\Driver\WriteError
- MongoDB\Driver\WriteResult
- MongoDB\Driver\BulkWriteCommandResult

# A classe MongoDB\Driver\Manager

(mongodb >=1.0.0)

## Introdução

A classe MongoDB\Driver\Manager é o principal ponto de entrada para a extensão. É responsável por manter conexões com o MongoDB (seja ele servidor independente, conjunto de réplicas ou cluster fragmentado).

Nenhuma conexão com o MongoDB é feita ao instanciar a classe. Isso significa que o objeto MongoDB\Driver\Manager sempre pode ser construído, mesmo que um ou mais servidores MongoDB estejam inativos.

Qualquer escrita ou consulta pode lançar exceções de conexão, pois as conexões são criadas lentamente. Um servidor MongoDB também pode ficar indisponível durante a vida útil do script. Portanto, é importante que todas as ações no objeto Manager sejam agrupadas em instruções try/catch.

## Resumo da classe

final class MongoDB\Driver\Manager {
/* Métodos */
final public function addSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void
final public function __construct(?string `$uri` = `null`, ?array `$uriOptions` = `null`, ?array `$driverOptions` = `null`)
final public function createClientEncryption(array `$options`): MongoDB\Driver\ClientEncryption
final public function executeBulkWrite(string `$namespace`, MongoDB\Driver\BulkWrite `$bulk`, ?array `$options` = `null`): MongoDB\Driver\WriteResult
final public function executeBulkWriteCommand(MongoDB\Driver\BulkWriteCommand `$bulk`, ?array `$options` = `null`): MongoDB\Driver\BulkWriteCommandResult
final public function executeCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeQuery(string `$namespace`, MongoDB\Driver\Query `$query`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeReadCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeReadWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function getEncryptedFieldsMap(): array|object|null
final public function getReadConcern(): MongoDB\Driver\ReadConcern
final public function getReadPreference(): MongoDB\Driver\ReadPreference
final public function getServers(): array
final public function getWriteConcern(): MongoDB\Driver\WriteConcern
final public function removeSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void
final public function selectServer(?MongoDB\Driver\ReadPreference `$readPreference` = `null`): MongoDB\Driver\Server
final public function startSession(?array `$options` = `null`): MongoDB\Driver\Session
}

## Exemplos

Exemplo #1 Exemplo básico de MongoDB\Driver\Manager::__construct()

A função var_dump() executada em um objeto MongoDB\Driver\Manager irá mostrar vários detalhes sobre o gerenciador do driver que não são normalmente expostas. Isso pode ser útil para depurar como o driver visualiza a configuração do MongoDB e quais opções são usadas.

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    var_dump($manager);

    ?>

O exemplo acima produzirá algo semelhante a:

    object(MongoDB\Driver\Manager)#1 (2) {
      ["uri"]=>
      string(26) "mongodb://127.0.0.1:27017/"
      ["cluster"]=>
      array(0) {
      }
    }

# MongoDB\Driver\Manager::addSubscriber

(mongodb >=1.10.0)

MongoDB\Driver\Manager::addSubscriber — Inscreve um assinante de evento de monitoramento com este gerenciador

### Descrição

final public function MongoDB\Driver\Manager::addSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void

Inscreve um assinante de evento de monitoramento neste gerenciador. O assinante será notificado de todos os eventos deste gerenciador.

> Nota: Se o `subscriber` já estiver inscrito neste gerenciador, esta função não fará nada. Se o `subscriber` também estiver inscrito globalmente, ele ainda será notificado apenas uma vez sobre cada evento deste gerenciador.

### Parâmetros

`subscriber` (MongoDB\Driver\Monitoring\Subscriber)
  Um assinante de evento de monitoramento para increver-se neste gerenciador.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma MongoDB\Driver\Exception\InvalidArgumentException se `subscriber` for um MongoDB\Driver\Monitoring\LogSubscriber, já que registradores só podem ser inscritos globalmente.

### Veja Também

- MongoDB\Driver\Manager::removeSubscriber() - Cancela o registro de um assinante de evento de monitoramento com este gerenciador
- MongoDB\Driver\Monitoring\Subscriber
- MongoDB\Driver\Monitoring\CommandSubscriber
- MongoDB\Driver\Monitoring\addSubscriber() - Registra um assinante de evento de monitoramento globalmente
- Monitoramento de Desempenho de Aplicação (APM)

# MongoDB\Driver\Manager::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Manager::__construct — Cria um novo gerenciador MongoDB

### Descrição

final public function MongoDB\Driver\Manager::__construct(?string `$uri` = `null`, ?array `$uriOptions` = `null`, ?array `$driverOptions` = `null`)

Constrói um novo objeto MongoDB\Driver\Manager com as opções especificadas.

> Nota: De acordo com a » Especificação de descoberta e monitoramento de servidor, esse construtor não executa E/S. As conexões serão inicializadas sob demanda, quando a primeira operação for executada.

> Nota: Ao especificar qualquer opção de URI SSL ou TLS por meio da string de conexão ou do parâmetro `uriOptions`, a extensão habilitará implicitamente o TLS para suas conexões. Para evitar isso, a opção `tls` deve ser desabilitada explicitamente ou nenhuma opção de TLS deve ser especificada.

> Nota: Em plataformas Unix, a extensão é sensível a scripts que usam a chamada de sistema fork() sem chamar também exec(). Os usuários são aconselhados a não reusar instâncias de MongoDB\Driver\Manager em um processo filho bifurcado.

### Parâmetros

`uri`
  Uma URI de conexão » mongodb://:

      mongodb://[usuário:senha@]servidor1[:porta1][,servidor2[:porta2],...[,servidorN[:portaN]]][/[BD_autenticacao_padrão][?opções]]

  O padrão é `"mongodb://127.0.0.1:27017"` se não especificado. Para obter detalhes sobre as opções de URI suportadas, consulte » Opções de string de conexão no manual do MongoDB. » Opções de pool de conexões não são suportadas, pois a extensão não implementa pools de conexões. O `uri` é um URL, portanto, quaisquer caracteres especiais em seus componentes precisam ser codificados em URL de acordo com a » RFC 3986. Isto é particularmente relevante para o nome de usuário e a senha, que muitas vezes podem incluir caracteres especiais como `@`, `:` ou `%`. Ao conectar através de um soquete de domínio Unix, o caminho do soquete pode conter caracteres especiais, como barras, e deve ser codificado. A função rawurlencode() pode ser usada para codificar partes constituintes do URI. O componente `defaultAuthDb` pode ser usado para especificar o nome do banco de dados associado às credenciais do usuário; entretanto, a opção de URI `authSource` terá prioridade se especificada. Se nem `defaultAuthDb` nem `authSource` forem especificados, o banco de dados `admin` será usado por padrão. O componente `defaultAuthDb` não tem efeito na ausência de credenciais do usuário.
`uriOptions`
  » Opções de string de conexão adicionais, que substituirão quaisquer opções com o mesmo nome no parâmetro `uri`.

  Opções de URI
  Opção | Tipo | Descrição
  --- | --- | ---
  appname | string | O MongoDB 3.4+ tem a capacidade de anotar conexões com metadados fornecidos pelo cliente conectado. Esses metadados são incluídos nos registros do servidor ao estabelecer uma conexão e também incluídos nos registros de consultas lentas quando a perfilagem do banco de dados está habilitada. Esta opção pode ser usada para especificar um nome de aplicação, que será incluído nos metadados. O valor não pode exceder 128 caracteres.
  authMechanism | string | O mecanismo de autenticação que o MongoDB usará para autenticar a conexão. Para obter detalhes adicionais e uma lista de valores suportados, consulte » Opções de autenticação no manual do MongoDB.
  authMechanismProperties | array | Propriedades do mecanismo de autenticação selecionado. Para obter detalhes adicionais e uma lista de propriedades suportadas, consulte a » Especificação de autenticação do driver. Nota: Quando não especificada na string URI, esta opção é expressa como um array de pares chave/valor. As chaves e valores neste array devem ser strings.
  authSource | string | O nome do banco de dados associado às credenciais do usuário. O padrão é o componente de banco de dados do URI de conexão ou o banco de dados `admin` se ambos não forem especificados. Para mecanismos de autenticação que delegam o armazenamento de credenciais a outros serviços (por exemplo, GSSAPI), deve ser `"$external"`.
  compressors | string | Uma lista priorizada e delimitada por vírgulas de compressores que o cliente deseja usar. As mensagens só serão compactadas se o cliente e o servidor compartilharem algum compressor em comum, e o compressor usado em cada direção dependerá da configuração individual do servidor ou driver. Consulte a » Especificação de compactação do driver para obter mais informações.
  connectTimeoutMS | int | O tempo em milissegundos para tentar uma conexão antes de atingir o tempo limite. O padrão é 10000 milissegundos.
  directConnection | bool | Esta opção pode ser usada para controlar o comportamento de descoberta do conjunto de réplicas quando apenas um único servidor é fornecido na string de conexão. Por padrão, fornecer um único membro na string de conexão estabelecerá uma conexão direta ou descobrirá membros adicionais dependendo se a opção de URI `"replicaSet"` estiver omitida ou presente, respectivamente. Especifique `false` para forçar a ocorrência da descoberta (se `"replicaSet"` for omitido) ou especifique `true` para forçar uma conexão direta (se `"replicaSet"` estiver presente).
  enableOverloadRetargeting | bool | Quando definido para `true`, força a seleção do servidor após um `SystemOverloadedError`. O padrão é `false`.
  heartbeatFrequencyMS | int | Especifica o intervalo em milissegundos entre as verificações do driver da topologia MongoDB, contado do final da verificação anterior até o início da próxima. O padrão é 60000 milissegundos. Pela » Especificação de descoberta e monitoramento de servidor, esse valor não pode ser inferior a 500 milissegundos.
  journal | bool | Corresponde ao parâmetro `journal` da preocupação de gravação padrão. Se for igual a `true`, as gravações exigirão o reconhecimento do MongoDB de que a operação foi gravada no diário. Para obter detalhes, consulte MongoDB\Driver\WriteConcern.
  loadBalanced | bool | Especifica se o driver está se conectando a um cluster MongoDB por meio de um balanceador de carga. Se for igual a `true`, o driver só pode se conectar a um único servidor (especificado pela string de conexão ou pela pesquisa SRV), a opção de URI `"directConnection"` não pode ser `true`, e a opção `"replicaSet"` do URI deve ser omitida. O padrão é `false`.
  localThresholdMS | int | O tamanho em milissegundos da janela de latência para selecionar entre várias instâncias adequadas do MongoDB ao resolver uma preferência de leitura. O padrão é 15 milissegundos.
  maxAdaptiveRetries | int | Esta opção pode ser usada para alterar o número máximo de novas tentativas quando um `SystemOverloadedError` ocorre. Precisa ser um inteiro positivo; o padrão é `2`.
  maxStalenessSeconds | int | Corresponde ao `"maxStalenessSeconds"` da preferência de leitura. Especifica, em segundos, o quão inativo um secundário pode ficar antes que o cliente pare de usá-lo para operações de leitura. Por padrão, não há inatividade máxima e os clientes não considerarão o atraso do secundário ao escolher para onde direcionar uma operação de leitura. Para obter detalhes, consulte MongoDB\Driver\ReadPreference. Se especificada, a inatividade máxima deve ser um número inteiro com sinal de 32 bits maior ou igual a `MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS` (ou seja, 90 segundos).
  password | string | A senha do usuário que está sendo autenticado. Esta opção é útil se a senha contiver caracteres especiais, que de outra forma precisariam ser codificados em URL para o URI de conexão.
  readConcernLevel | string | Corresponde ao parâmetro `level` da preocupação de leitura. Especifica o nível de isolamento de leitura. Para obter detalhes, consulte MongoDB\Driver\ReadConcern.
  readPreference | string | Corresponde ao parâmetro `mode` da preferência de leitura. O padrão é `"primary"`. Para obter detalhes, consulte MongoDB\Driver\ReadPreference.
  readPreferenceTags | array | Corresponde ao parâmetro `tagSets` da preferência de leitura. Os conjuntos de etiquetas permitem direcionar operações de leitura para membros específicos de um conjunto de réplicas. Para obter detalhes, consulte MongoDB\Driver\ReadPreference. Nota: Quando não especificada na string URI, esta opção é expressa como um array consistente com o formato esperado por MongoDB\Driver\ReadPreference::__construct().
  replicaSet | string | Especifica o nome do conjunto de réplicas.
  retryReads | bool | Especifica se o driver deve ou não repetir automaticamente determinadas operações de leitura que falham devido a erros transitórios de rede ou eleições de conjunto de réplicas. Esta funcionalidade requer o MongoDB 3.6+. O padrão é `true`. Consulte a » Especificação de leituras repetíveis para mais informações.
  retryWrites | bool | Especifica se o driver deve ou não repetir automaticamente determinadas operações de gravação que falham devido a erros transitórios de rede ou eleições de conjunto de réplicas. Esta funcionalidade requer o MongoDB 3.6+. O padrão é `true`. Consulte » Gravações Repetíveis no manual do MongoDB para obter mais informações.
  serverSelectionTimeoutMS | int | Especifica quanto tempo, em milissegundos, deve-se bloquear para seleção de servidor antes de lançar uma exceção. O padrão é 30000 milissegundos.
  serverSelectionTryOnce | bool | Quando `true`, instrui o driver a verificar a implantação do MongoDB exatamente uma vez após a falha na seleção do servidor e, em seguida, selecionar um servidor ou gerar um erro. Quando `false`, o driver bloqueia e procura um servidor até o valor `"serverSelectionTimeoutMS"`. O padrão é `true`.
  socketCheckIntervalMS | int | Se um soquete não tiver sido usado recentemente, o driver precisará verificá-lo através do comando `hello` antes de usá-lo para qualquer operação. O padrão é 5000 milissegundos.
  socketTimeoutMS | int | O tempo em milissegundos para tentar enviar ou receber em um soquete antes de atingir o tempo limite. O padrão é 300000 milissegundos (ou seja, cinco minutos).
  srvMaxHosts | int | O número máximo de resultados de SRV a serem selecionados aleatoriamente ao preencher inicialmente a lista de valores iniciais ou, durante a sondagem de SRV, ao incluir novos servidores na topologia. O padrão é `0` (ou seja, sem máximo).
  srvServiceName | string | O nome do serviço a ser usado para consulta de SRV na descoberta inicial da lista de valores iniciais de DNS e na sondagem de SRV. O padrão é `"mongodb"`.
  tls | bool | Inicia a conexão com TLS/SSL se for igual a `true`. O padrão é `false`.
  tlsAllowInvalidCertificates | bool | Especifica se o driver deve ou não apresentar erro quando o certificado TLS do servidor for inválido. O padrão é `false`. Aviso Desabilitar a validação de certificado cria uma vulnerabilidade.
  tlsAllowInvalidHostnames | bool | Especifica se o driver deve ou não apresentar erro quando há uma incompatibilidade entre o nome do host do servidor e o nome do host especificado pelo certificado TLS. O padrão é `false`. Aviso Desabilitar a validação de certificado cria uma vulnerabilidade. Permitir nomes de servidores inválidos pode expor o driver a um » ataque MITM.
  tlsCAFile | string | Caminho para arquivo com uma única autoridade de certificação ou um pacote de autoridades de certificação a ser considerado confiável ao fazer uma conexão TLS. O armazenamento de certificados do sistema será usado por padrão.
  tlsCertificateKeyFile | string | Caminho para o arquivo de certificado do cliente ou arquivo de chave privada do cliente; caso ambos sejam necessários, os arquivos deverão ser concatenados.
  tlsCertificateKeyFilePassword | string | Senha para descriptografar a chave privada do cliente (ou seja, opção de URI `"tlsCertificateKeyFile"`) a ser usada para conexões TLS.
  tlsDisableCertificateRevocationCheck | bool | Se `true`, o driver não tentará verificar o status de revogação do certificado (por exemplo, OCSP, CRL). O padrão é `false`.
  tlsDisableOCSPEndpointCheck | bool | Se `true`, o driver não tentará contactar um ponto de extremidade de um respondedor OCSP, se necessário (ou seja, uma resposta OCSP não é grampeada). O padrão é `false`.
  tlsInsecure | bool | Relaxa as restrições de TLS tanto quanto possível. Especificar `true` para esta opção tem o mesmo efeito que especificar `true` para as opções de URI `"tlsAllowInvalidCertificates"` e `"tlsAllowInvalidHostnames"`. O padrão é `false`. Aviso Desabilitar a validação de certificado cria uma vulnerabilidade. Permitir nomes de servidores inválidos pode expor o driver a um » ataque MITM.
  username | string | O nome do usuário que está sendo autenticado. Esta opção é útil se o nome de usuário contiver caracteres especiais, que de outra forma precisariam ser codificados em URL para o URI de conexão.
  w | int|string | Corresponde ao parâmetro `w` da preocupação de gravação padrão. Para obter detalhes, consulte MongoDB\Driver\WriteConcern.
  wTimeoutMS | int|string | Corresponde ao parâmetro `wtimeout` da preocupação de gravação padrão. Especifica um limite de tempo, em milissegundos, para a preocupação de gravação. Para obter detalhes, consulte MongoDB\Driver\WriteConcern. Se especificado, `wTimeoutMS` deve ser um número inteiro de 32 bits sem sinal maior ou igual a zero.
  zlibCompressionLevel | int | Especifica o nível de compactação a ser usado para o compressor zlib. Esta opção não tem efeito se `zlib` não estiver incluído na opção URI `"compressors"`. Consulte a » Especificação de Compactação de Driver para obter mais informações.

`driverOptions`

  Opções do Driver
  Opção | Tipo | Descrição
  --- | --- | ---
  autoEncryption | array | Fornece opções para ativar a criptografia automática em nível de campo do lado do cliente. A lista de opções está descrita na tabela abaixo. Nota: A criptografia automática é um recurso exclusivo da versão Enterprise que se aplica apenas a operações em uma coleção. A criptografia automática não é suportada para operações em um banco de dados ou visualização, e as operações que não são ignoradas resultarão em erro (consulte » libmongocrypt: lista de permissões de criptografia automática). Para ignorar a criptografia automática para todas as operações, `bypassAutoEncryption` deve ser definido como `true`. A criptografia automática exige que o usuário autenticado tenha a ação de privilégio » listCollections. A criptografia/descriptografia explícita e a descriptografia automática são um recurso da versão Community. O driver ainda pode descriptografar automaticamente quando `bypassAutoEncryption` for igual a `true`.
  ca_dir | string | Caminho para um diretório de certificado com hash correto. O armazenamento de certificados do sistema será usado por padrão.
  crl_file | string | Caminho para um arquivo de lista de certificados revogados.
  disableClientPersistence | bool | Se `true`, este gerenciador usará um novo cliente libmongoc, que não será persistido ou compartilhado com outros objetos do gerenciador. Quando este objeto de gerenciador for liberado, seu cliente será destruído e todas as conexões serão fechadas. O padrão é `false`. Nota: Geralmente, desabilitar a persistência do cliente não é recomendado.
  driver | array | Permite que uma biblioteca de nível superior anexe seus próprios metadados ao "handshake" com o servidor. Por padrão, a extensão envia seu próprio nome, versão e plataforma (ou seja, versão PHP) nesta comunicação inicial. Strings podem ser especificadas para as chaves `"name"`, `"version"` e `"platform"` deste array e serão anexadas ao respectivos campos no documento de "handshake". Nota: As informações de "handshake" são limitadas a 512 bytes. A extensão truncará os dados do "handshake" para caber nesta sequência de 512 bytes. Bibliotecas de nível superior são encorajadas a manter seus próprios metadados concisos.
  serverApi | MongoDB\Driver\ServerApi | Esta opção é usada para declarar uma versão da API do servidor para o gerenciador. Se omitida, nenhuma versão da API será declarada.

  Opções suportadas pela criptografia automática através da opção `autoEncryption` do driver:

  Opções para criptografia automática
  Opção | Tipo | Descrição
  --- | --- | ---
  keyVaultClient | MongoDB\Driver\Manager | O Manager usado para rotear consultas de chave de dados para um cluster MongoDB separado. Por padrão, o Manager e o cluster atuais são usados.
  keyVaultNamespace | string | Um namespace totalmente qualificado (por exemplo, `"nomeDoBancoDados.nomeDaColecao"`) denotando a coleção que contém todas as chaves de dados usadas para criptografia e descriptografia. Esta opção é obrigatória.
  kmsProviders | array | Um documento contendo a configuração de um ou mais provedores KMS, que são usados para criptografar chaves de dados. Os provedores compatíveis incluem `"aws"`, `"azure"`, `"gcp"`, `"kmip"` e `"local"` e pelo menos um deve ser especificado. Se um documento vazio for especificado para `"aws"`, `"azure"`, ou `"gcp"`, o driver tentará configurar o provedor usando » Credenciais Automáticas. O formato para `"aws"` é o seguinte:
      aws: {
          accessKeyId: <string>,
          secretAccessKey: <string>,
          sessionToken: <string opcional>
      }
  O formato para `"azure"` é o seguinte:
      azure: {
          tenantId: <string>,
          clientId: <string>,
          clientSecret: <string>,
          identityPlatformEndpoint: <string opcional> // O padrão é "login.microsoftonline.com"
      }
  O formato para `"gcp"` é o seguinte:
      gcp: {
          email: <string>,
          privateKey: <string base64>|<MongoDB\BSON\Binary>,
          endpoint: <string opcional> // O padrão é "oauth2.googleapis.com"
      }
  O formato para `"kmip"` é o seguinte:
      kmip: {
          endpoint: <string>
      }
  O formato para `"local"` é o seguinte:
      local: {
          // Chave mestra de 96 bytes usada para criptografar/descriptografar chaves de dados
          key: <string base64>|<MongoDB\BSON\Binary>
      }
  tlsOptions | array | Um documento contendo a configuração TLS para um ou mais provedores KMS. Os provedores suportados incluem `"aws"`, `"azure"`, `"gcp"` e `"kmip"`. Todos os provedores suportam as seguintes opções:
      <provider>: {
          tlsCaFile: <string opcional>,
          tlsCertificateKeyFile: <string opcional>,
          tlsCertificateKeyFilePassword: <string opcional>,
          tlsDisableOCSPEndpointCheck: <booleano opcional>
      }
  schemaMap | array|object | Mapa de espaços de nomes de coleção para um esquema JSON local. Isso é usado para configurar a criptografia automática. Consulte » Regras de criptografia automática no manual do MongoDB para obter mais informações. É um erro especificar uma coleção em `schemaMap` e em `encryptedFieldsMap` ao mesmo tempo. Nota: Fornecer um `schemaMap` oferece mais segurança do que confiar em esquemas JSON obtidos do servidor. Ele protege contra um servidor malicioso que anuncia um esquema JSON falso, que poderia induzir o cliente a enviar dados não criptografados que deveriam estar criptografados. Nota: Os esquemas fornecidos no `schemaMap` aplicam-se apenas à configuração da criptografia automática para criptografia do lado do cliente. Outras regras de validação no esquema JSON não serão aplicadas pelo driver e resultarão em erro.
  bypassAutoEncryption | bool | Se `true`, `mongocryptd` não será executado automaticamente. Isso é usado para desativar a criptografia automática. O padrão é `false`.
  bypassQueryAnalysis | bool | Se `true`, a análise automática dos comandos enviados será desativada e o `mongocryptd` não será executado automaticamente. Isso permite o caso de uso de criptografia explícita para consultar campos indexados sem exigir a biblioteca `crypt_shared` licenciada pela versão Enterprise ou o processo `mongocryptd`. O padrão é `false`.
  encryptedFieldsMap | array|object | Mapa de espaçoes de nomes de coleção para um documento `encryptedFields`. Isso é usado para configurar a criptografia consultável. Consulte » Criptografia de campo e consultabilidade no manual do MongoDB para obter mais informações. É um erro especificar uma coleção em `encryptedFieldsMap` e em `schemaMap` ao mesmo tempo. Nota: Fornecer um `encryptedFieldsMap` fornece mais segurança do que confiar em um `encryptedFields` obtido do servidor. Ele protege contra um servidor malicioso que anuncia um `encryptedFields` falso.
  extraOptions | array | As `extraOptions` estão relacionadas ao processo `mongocryptd`. As seguintes opções são suportadas: `mongocryptdURI` (string): URI para conectar-se a um processo `mongocryptd` existente. O padrão é `"mongodb://localhost:27020"`. `mongocryptdBypassSpawn` (bool): Se `true`, evita que o driver execute o `mongocryptd`. O padrão é `false`. `mongocryptdSpawnPath` (string): Caminho absoluto para procurar o binário `mongocryptd`. O padrão é uma string vazia e consulta os caminhos do sistema. `mongocryptdSpawnArgs` (array): Array de argumentos de string para passar para `mongocryptd` durante a execução. O padrão é `["--idleShutdownTimeoutSecs=60"]`. `cryptSharedLibPath` (string): Caminho absoluto para a biblioteca compartilhada `crypt_shared`. O padrão é uma string vazia e consulta os caminhos do sistema. `cryptSharedLibRequired` (bool): Se `true`, exige que o driver carregue `crypt_shared`. O padrão é `false`. Consulte a » Especificação de criptografia do lado do cliente para obter mais informações.

  > Nota: A criptografia automática é um recurso exclusivo da versão "enterprise" que se aplica apenas a operações em uma coleção. A criptografia automática não é suportada para operações em um banco de dados ou visualização, e as operações que não são ignoradas resultarão em erro. Para ignorar a criptografia automática para todas as operações, defina `bypassAutoEncryption=true` em `autoEncryption`. Para obter mais informações sobre operações permitidas, consulte » Especificação de criptografia do lado do cliente.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\RuntimeException se o formato de `uri` for inválido

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | A opção de URI `"canonicalizeHostname"` foi removida. Em vez disso, use a propriedade `"CANONICALIZE_HOST_NAME"` da opção de URI `"authMechanismProperties"`. A opção de URI `"gssapiServiceName"` foi removida. Em vez disso, use a propriedade `"SERVICE_NAME"` da opção de URI `"authMechanismProperties"`. A opção de URI `"safe"` foi removida. Use as opções de URI `"w"` e `"wTimeoutMS"`. A opção de URI `"ssl"` foi removida. Em vez disso, use a opção de URI `"tls"`. A opção de driver `"allow_invalid_hostname"` foi removida. Em vez disso, use a opção de URI `"tlsAllowInvalidHostnames"`. A opção de driver `"ca_file"` foi removida. Em vez disso, use a opção de URI `"tlsCAFile"`. A opção de driver `"context"` foi removida. Todas as opções de contexto foram descontinuadas em favor das diversas opções de URI relacionadas ao TLS. A opção de driver `"pem_file"` foi removida. Em vez disso, use a opção de URI `"tlsCertificateKeyFile"`. A opção de driver `"pem_pwd"` foi removida. Em vez disso, use a opção de URI `"tlsCertificateKeyFilePassword"`. A opção de driver `"weak_cert_validation"` foi removida. Em vez disso, use a opção de URI `"tlsAllowInvalidCertificates"`.
PECL mongodb 1.16.0 | O provedor AWS KMS para criptografia do lado do cliente agora aceita uma opção `"sessionToken"`, que pode ser usada para autenticação com credenciais temporárias da AWS. Adicionada a opção `"tlsDisableOCSPEndpointCheck"` para o campo `"tlsOptions"` da opção `"autoEncryption"` do driver. Se um documento vazio for especificado para o provedor KMS `"azure"` ou `"gcp"`, o driver tentará configurar o provedor usando » Credenciais Automáticas.
PECL mongodb 1.15.0 | Se um documento vazio for especificado para o provedor KMS `"aws"`, o driver tentará configurar o provedor usando » Credenciais Automáticas.
PECL mongodb 1.14.0 | Adicionadas as opções de criptografia automática `"bypassQueryAnalysis"` e `"encryptedFieldsMap"`. Opções adicionais pertencentes a `crypt_shared` agora são suportadas na opção de criptografia automática `"extraOptions"`.
PECL mongodb 1.13.0 | Adicionadas as opções de URI `"srvMaxHosts"` e `"srvServiceName"`.
PECL mongodb 1.12.0 | KMIP agora é suportado como um provedor KMS para criptografia do lado do cliente e pode ser configurado no campo `"kmsProviders"` da opção de driver `"autoEncryption"`. Além disso, as opções de TLS para provedores KMS agora podem ser configuradas no campo `"tlsOptions"` da opção do driver `"autoEncryption"`.
PECL mongodb 1.11.0 | Adicionada a opção de URI `"loadBalanced"`.
PECL mongodb 1.10.0 | Adicionada a opção de driver `"disableClientPersistence"`. Azure e GCP agora são suportados como provedores KMS para criptografia do lado do cliente e podem ser configurados no campo `"kmsProviders"` da opção de driver `"autoEncryption"`. Strings codificadas em Base64 agora são aceitas como uma alternativa ao MongoDB\BSON\Binary para opções dentro de `"kmsProviders"`.
PECL mongodb 1.8.0 | Adicionadas as opções de URI `"directConnection"`, `"tlsDisableCertificateRevocationCheck"` e `"tlsDisableOCSPEndpointCheck"`. Adicionada a opção de driver `"driver"`.
PECL mongodb 1.7.0 | Adicionada a opção de driver `"autoEncryption"`. Especificar qualquer opção SSL ou TLS por meio do parâmetro `driverOptions` agora ativará implicitamente o TLS, como é feito para as opções de URI correspondentes.
PECL mongodb 1.6.0 | Adicionadas as opções de URI `"retryReads"`, `"tls"`, `"tlsAllowInvalidCertificates"`, `"tlsAllowInvalidHostnames"`, `"tlsCAFile"`, `"tlsCertificateKeyFile"`, `"tlsCertificateKeyFilePassword"` e `"tlsInsecure"`. A opção de URI `"retryWrites"` tem como padrão `true`. Especificar qualquer opção de URI SSL ou TLS por meio da string de conexão ou do parâmetro `uriOptions` agora ativará implicitamente o TLS, a menos que `ssl` ou `tls` seja `false`. O TLS não está implicitamente habilitado para nenhuma opção no parâmetro `driverOptions`, que permanece inalterado em relação às versões anteriores.
PECL mongodb 1.5.0 | `"wtimeoutMS"` agora é sempre validado e aplicado à preocupação de gravação. Anteriormente, a opção era ignorada se `"w"` fosse <= 1, pois o tempo limite só se aplica à replicação.
PECL mongodb 1.4.0 | Adicionadas as opções de URI `"compressors"`, `"retryWrites"` e `"zlibCompressionLevel"`.
PECL mongodb 1.3.0 | O parâmetro `uriOptions` agora aceita as opções `"authMechanism"` e `"authMechanismProperties"`. Anteriormente, estas opções eram suportadas somente no parâmetro `uri`.
PECL mongodb 1.2.0 | O padrão para o parâmetro `uri` passa a ser `"mongodb://127.0.0.1/"`. A porta padrão permanece `27017`. Adicionada a opção de URI `"appname"`. Adicionadas as opções de driver `"allow_invalid_hostname"`, `"ca_file"`, `"ca_dir"`, `"clr_file"`, `"pem_file"`, `"pem_pwd"` e `"weak_cert_validation"`. A API de Fluxos do PHP não é mais usada para comunicação de soquete. A opção de URI `"connectTimeoutMS"` agora tem como padrão 10 segundos em vez de default_socket_timeout nas versões anteriores. Além disso, a extensão não suporta mais todas as opções de contexto SSL através da opção de driver `"context"`.
PECL mongodb 1.1.0 | O parâmetro `uri` passa a ser opcional com o padrão de `"mongodb://localhost:27017/"`.

### Exemplos

Exemplo #1 Exemplos básicos de MongoDB\Driver\Manager::__construct()

Conexão a um nó independente do MongoDB:

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://example.com:27017");

    ?>

Conectando-se ao nó independente do MongoDB por meio de um soquete de domínio Unix. O caminho do soquete pode incluir caracteres especiais como barras e deve ser codificado com rawurlencode().

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://" . rawurlencode("/tmp/mongodb-27017.sock"));

    ?>

Conectando-se a um conjunto de réplicas:

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

    ?>

Conectando-se a um cluster fragmentado (ou seja, uma ou mais instâncias do mongos):

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://mongos1.example.com,mongos2.example.com/");

    ?>

Conectando-se ao MongoDB com credenciais de autenticação para um usuário e banco de dados específicos:

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://meuUsuario:minhaSenha@example.com/?authSource=nomeBancoDeDados");

    ?>

Conectando-se ao MongoDB com credenciais de autenticação para um usuário e banco de dados específicos, onde o nome de usuário ou senha inclui caracteres especiais (por exemplo, `@`, `:`, `%`). No exemplo a seguir, a string de senha `myp@ss:w%rd` foi escapada manualmente; entretanto, rawurlencode() também pode ser usado para escapar componentes URI que podem conter caracteres especiais.

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://meuUsuario:myp%40ss%3Aw%25rd@example.com/?authSource=nomeBancoDeDados");

    ?>

Conectando-se ao MongoDB com autenticação X509:

    <?php

    $manager = new MongoDB\Driver\Manager(
        "mongodb://example.com/?ssl=true&authMechanism=MONGODB-X509",
        [],
        [
            "pem_file" => "/caminho/para/cliente.pem",
        ]
    );
    ?>

### Veja Também

- Manipulação de conexão e persistência
- » Formato de string de conexão MongoDB

# MongoDB\Driver\Manager::createClientEncryption

(mongodb >=1.7.0)

MongoDB\Driver\Manager::createClientEncryption — Cria um novo objeto ClientEncryption

### Descrição

final public function MongoDB\Driver\Manager::createClientEncryption(array `$options`): MongoDB\Driver\ClientEncryption

Constrói um novo objeto MongoDB\Driver\ClientEncryption com as opções especificadas.

### Parâmetros

`options`

  Opções
  Opção | Tipo | Descrição
  --- | --- | ---
  keyVaultClient | MongoDB\Driver\Manager | O Manager usado para rotear consultas de chave de dados para um cluster MongoDB separado. Por padrão, o Manager e o cluster atuais são usados.
  keyVaultNamespace | string | Um namespace totalmente qualificado (por exemplo, `"nomeDoBancoDados.nomeDaColecao"`) denotando a coleção que contém todas as chaves de dados usadas para criptografia e descriptografia. Esta opção é obrigatória.
  kmsProviders | array | Um documento contendo a configuração de um ou mais provedores KMS, que são usados para criptografar chaves de dados. Os provedores compatíveis incluem `"aws"`, `"azure"`, `"gcp"`, `"kmip"` e `"local"` e pelo menos um deve ser especificado. Se um documento vazio for especificado para `"aws"`, `"azure"`, ou `"gcp"`, o driver tentará configurar o provedor usando » Credenciais Automáticas. O formato para `"aws"` é o seguinte:
      aws: {
          accessKeyId: <string>,
          secretAccessKey: <string>,
          sessionToken: <string opcional>
      }
  O formato para `"azure"` é o seguinte:
      azure: {
          tenantId: <string>,
          clientId: <string>,
          clientSecret: <string>,
          identityPlatformEndpoint: <string opcional> // O padrão é "login.microsoftonline.com"
      }
  O formato para `"gcp"` é o seguinte:
      gcp: {
          email: <string>,
          privateKey: <string base64>|<MongoDB\BSON\Binary>,
          endpoint: <string opcional> // O padrão é "oauth2.googleapis.com"
      }
  O formato para `"kmip"` é o seguinte:
      kmip: {
          endpoint: <string>
      }
  O formato para `"local"` é o seguinte:
      local: {
          // Chave mestra de 96 bytes usada para criptografar/descriptografar chaves de dados
          key: <string base64>|<MongoDB\BSON\Binary>
      }
  tlsOptions | array | Um documento contendo a configuração TLS para um ou mais provedores KMS. Os provedores suportados incluem `"aws"`, `"azure"`, `"gcp"` e `"kmip"`. Todos os provedores suportam as seguintes opções:
      <provider>: {
          tlsCaFile: <string opcional>,
          tlsCertificateKeyFile: <string opcional>,
          tlsCertificateKeyFilePassword: <string opcional>,
          tlsDisableOCSPEndpointCheck: <booleano opcional>
      }

### Valor Retornado

Retorna uma nova instância de MongoDB\Driver\ClientEncryption.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança MongoDB\Driver\Exception\RuntimeException se a extensão foi compilada sem suporte libmongocrypt

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.16.0 | O provedor AWS KMS para criptografia do lado do cliente agora aceita uma opção `"sessionToken"`, que pode ser usada para autenticação com credenciais temporárias da AWS. Adicionado `"tlsDisableOCSPEndpointCheck"` à opção `"tlsOptions"`. Se um documento vazio for especificado para o provedor KMS `"azure"` ou `"gcp"`, o driver tentará configurar o provedor usando » Credenciais Automáticas.
PECL mongodb 1.15.0 | Se um documento vazio for especificado para o provedor KMS `"aws"`, o driver tentará configurar o provedor usando » Credenciais Automáticas.
PECL mongodb 1.12.0 | O KMIP agora é suportado como um provedor KMS para criptografia do lado do cliente e pode ser configurado na opção `"kmsProviders"`. Adicionada a opção `"tlsOptions"`.
PECL mongodb 1.10.0 | O Azure e o GCP agora são suportados como provedores KMS para criptografia do lado do cliente e podem ser configurados na opção `"kmsProviders"`. Strings codificadas em Base64 agora são aceitas como uma alternativa ao MongoDB\BSON\Binary para opções dentro de `"kmsProviders"`.

### Veja Também

- MongoDB\Driver\ClientEncryption::__construct() - Cria um novo objeto ClientEncryption
- » Criptografia explícita (manual) em nível de campo do lado do cliente no manual do MongoDB

# MongoDB\Driver\Manager::executeBulkWrite

(mongodb >=1.0.0)

MongoDB\Driver\Manager::executeBulkWrite — Executa uma ou mais operações de escrita

### Descrição

final public function MongoDB\Driver\Manager::executeBulkWrite(string `$namespace`, MongoDB\Driver\BulkWrite `$bulk`, ?array `$options` = `null`): MongoDB\Driver\WriteResult

Executa uma ou mais operações de escrita no servidor primário.

Um MongoDB\Driver\BulkWrite pode ser construído com uma ou mais operações de escrita de vários tipos (por exemplo, atualizações, exclusões e inserções). O driver tentará enviar operações do mesmo tipo ao servidor no menor número possível de solicitações para otimizar viagens de ida e volta.

O valor padrão para a opção `"writeConcern"` será inferido de uma transação ativa (indicada pela opção `"session"`), seguida pelo URI de conexão.

### Parâmetros

`namespace` (string)
  Um namespace totalmente qualificado (por exemplo, `"nomeDoBancoDados.nomeDaColecao"`).
`bulk` (MongoDB\Driver\BulkWrite)
  As gravações a serem executadas.
`options`

  Opções
  Opção | Tipo | Descrição
  --- | --- | ---
  session | MongoDB\Driver\Session | Uma sessão para associar à operação.
  writeConcern | MongoDB\Driver\WriteConcern | Um write concern a ser aplicado à operação.

### Valor Retornado

Retorna MongoDB\Driver\WriteResult em caso de sucesso.

### Erros/Exceções

- Lança MongoDB\Driver\Exception\InvalidArgumentException se `bulk` não contiver operações de escrita.
- Lança MongoDB\Driver\Exception\InvalidArgumentException se `bulk` já tiver sido executado. Objetos MongoDB\Driver\BulkWrite não podem ser executados múltiplas vezes.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException se a opção `"session"` for usada em combinação com uma preocupação de escrita não confirmada.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\ConnectionException se a conexão com o servidor falhar (por outros motivos além da autenticação).
- Lança uma exceção MongoDB\Driver\Exception\AuthenticationException se a autenticação for necessária e falhar.
- Lança uma exceção MongoDB\Driver\Exception\BulkWriteException em caso de qualquer falha de escrita (por exemplo, erro de escrita, falha ao aplicar uma preocupação de escrita).
- Lança MongoDB\Driver\Exception\RuntimeException no caso de outros erros.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | O parâmetro `options` não aceita mais uma instância de MongoDB\Driver\WriteConcern.
PECL mongodb 1.21.0 | Passar um objeto MongoDB\Driver\WriteConcern como `options` foi descontinuado e será removido na versão 2.0.
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException será lançado se a opção `"session"` for usada em combinação com uma preocupação de gravação não reconhecida.
PECL mongodb 1.4.0 | O terceiro parâmetro agora é um array `options`. Para compatibilidade com versões anteriores, este parâmetro ainda aceitará um objeto MongoDB\Driver\WriteConcern.
PECL mongodb 1.3.0 | MongoDB\Driver\Exception\InvalidArgumentException agora é lançada se `bulk` não contiver nenhuma operação de escrita. Anteriormente, uma MongoDB\Driver\Exception\BulkWriteException era lançada.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\Manager::executeBulkWrite()

    <?php

    $bulk = new MongoDB\Driver\BulkWrite();

    $bulk->insert(['_id' => 1, 'x' => 1]);
    $bulk->insert(['_id' => 2, 'x' => 2]);

    $bulk->update(['x' => 2], ['$set' => ['x' => 1]], ['multi' => false, 'upsert' => false]);
    $bulk->update(['x' => 3], ['$set' => ['x' => 3]], ['multi' => false, 'upsert' => true]);
    $bulk->update(['_id' => 3], ['$set' => ['x' => 3]], ['multi' => false, 'upsert' => true]);

    $bulk->insert(['_id' => 4, 'x' => 2]);

    $bulk->delete(['x' => 1], ['limit' => 1]);

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $writeConcern = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY, 100);
    $result = $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);

    printf("Inserido(s) %d documento(s)\n", $result->getInsertedCount());
    printf("Correspondido(s) %d documento(s)\n", $result->getMatchedCount());
    printf("Atualizado(s) %d documento(s)\n", $result->getModifiedCount());
    printf("Atualizado(s)/Inserido(s) %d documento(s)\n", $result->getUpsertedCount());
    printf("Excluído(s) %d documento(s)\n", $result->getDeletedCount());

    foreach ($result->getUpsertedIds() as $index => $id) {
        printf('upsertedId[%d]: ', $index);
        var_dump($id);
    }

    /* Se a preocupação de escrita não puder ser atendida */
    if ($writeConcernError = $result->getWriteConcernError()) {
        printf("%s (%d): %s\n", $writeConcernError->getMessage(), $writeConcernError->getCode(), var_export($writeConcernError->getInfo(), true));
    }

    /* Se uma escrita não pôde acontecer */
    foreach ($result->getWriteErrors() as $writeError) {
        printf("Operation#%d: %s (%d)\n", $writeError->getIndex(), $writeError->getMessage(), $writeError->getCode());
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Inserido(s) 3 documento(s)
    Correspondido(s) 1 documento(s)
    Atualizado(s) 1 documento(s)
    Atualizado(s)/Inserido(s) 2 documento(s)
    Excluído(s) 1 documento(s)
    upsertedId[3]: object(MongoDB\BSON\ObjectId)#5 (1) {
      ["oid"]=>
      string(24) "54d3adc3ce7a792f4d703756"
    }
    upsertedId[4]: int(3)

### Veja Também

- MongoDB\Driver\BulkWrite
- MongoDB\Driver\WriteResult
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\Server::executeBulkWrite() - Executa uma ou mais operações de gravação neste servidor

# MongoDB\Driver\Manager::executeBulkWriteCommand

(mongodb >=2.1.0)

MongoDB\Driver\Manager::executeBulkWriteCommand — Executa operações de gravação usando o comando bulkWrite

### Descrição

final public function MongoDB\Driver\Manager::executeBulkWriteCommand(MongoDB\Driver\BulkWriteCommand `$bulk`, ?array `$options` = `null`): MongoDB\Driver\BulkWriteCommandResult

Executa uma ou mais operações de gravação no servidor primário usando o comando » bulkWrite introduzido no MongoDB 8.0.

Um MongoDB\Driver\BulkWriteCommand pode ser construído com uma ou mais operações de gravação de tipos variados (por exemplo, inserções, atualizações e exclusões). Cada operação de gravação pode ter como alvo uma coleção diferente.

O valor padrão para a opção `"writeConcern"` será inferido a partir de uma transação ativa (indicada pela opção `"session"`), seguida pelo URI de conexão.

### Parâmetros

`bulk` (MongoDB\Driver\BulkWriteCommand)
  O comando de gravações a ser executado.
`options`

  Opções
  Opção | Tipo | Descrição
  --- | --- | ---
  session | MongoDB\Driver\Session | Uma sessão para associar à operação.
  writeConcern | MongoDB\Driver\WriteConcern | Um write concern a ser aplicado à operação.

### Valor Retornado

Retorna MongoDB\Driver\BulkWriteCommandResult em caso de sucesso.

### Erros/Exceções

- Lança MongoDB\Driver\Exception\InvalidArgumentException se `bulk` não contiver nenhuma operação de gravação.
- Lança MongoDB\Driver\Exception\InvalidArgumentException se `bulk` já tiver sido executado. Objetos MongoDB\Driver\BulkWriteCommand não podem ser executados várias vezes.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException se a opção `"session"` for usada em combinação com uma preocupação de escrita não confirmada.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\ConnectionException se a conexão com o servidor falhar (por outros motivos além da autenticação).
- Lança uma exceção MongoDB\Driver\Exception\AuthenticationException se a autenticação for necessária e falhar.
- Lança uma exceção MongoDB\Driver\Exception\BulkWriteCommandException em caso de qualquer falha de escrita (por exemplo, falha no comando, erro de escrita ou de preocupação de escrita)
- Lança MongoDB\Driver\Exception\RuntimeException em outros erros.

### Exemplos

Exemplo #1 Operações de gravação mistas

Operações de gravação mistas (ou seja, inserções, atualizações e exclusões) serão enviadas para o servidor usando um único comando » bulkWrite.

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    // Exclui documentos de ambas as coleções
    $bulk->deleteMany('db.coll_one', []);
    $bulk->deleteMany('db.coll_two', []);

    // Insere documentos em duas coleções
    $bulk->insertOne('db.coll_one', ['_id' => 1]);
    $bulk->insertOne('db.coll_two', ['_id' => 2]);
    $bulk->insertOne('db.coll_two', ['_id' => 3]);

    // Atualiza um documento em "coll_one"
    $bulk->updateOne('db.coll_one', ['_id' => 1], ['$set' => ['x' => 1]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    printf("Inserido(s) %d documento(s)\n", $result->getInsertedCount());
    printf("Atualizado(s) %d documento(s)\n", $result->getModifiedCount());

    ?>

O exemplo acima produzirá:

    Inserido(s) 3 documento(s)
    Atualizado(s) 1 documento(s)

Exemplo #2 Operações de gravação ordenadas causando um erro

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 2]);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 3]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        $result = $e->getPartialResult();

        var_dump($e->getWriteErrors());
    }

    printf("Inserido(s) %d documento(s)\n", $result->getInsertedCount());

    ?>

O exemplo acima produzirá algo semelhante a:

    array(1) {
      [3]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(3)
        ["info"]=>
        object(stdClass)#6 (0) {
        }
      }
    }
    Inserido(s) 2 documento(s)

### Veja Também

- MongoDB\Driver\BulkWriteCommand
- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\Server::executeBulkWriteCommand() - Executa operações de gravação neste servidor usando o comando bulkWrite

# MongoDB\Driver\Manager::executeCommand

(mongodb >=1.0.0)

MongoDB\Driver\Manager::executeCommand — Executa um comando de banco de dados

### Descrição

final public function MongoDB\Driver\Manager::executeCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Seleciona um servidor de acordo com a opção `"readPreference"` e executa o comando nesse servidor.

Este método não aplica nenhuma lógica especial ao comando. Os valores padrão para as opções `"readPreference"`, `"readConcern"` e `"writeConcern"` serão inferidos de uma transação ativa (indicada pelo opção `"session"`). Se não houver nenhuma transação ativa, uma preferência de leitura primária será usada para seleção do servidor.

Os valores padrão não serão inferidos do URI de conexão. Os usuários são, portanto, incentivados a usar métodos de comando específicos de leitura e/ou gravação, se possível.

### Parâmetros

`db` (string)
  O nome do banco de dados no qual executar o comando.
`command` (MongoDB\Driver\Command)
  O comando a ser executado.
`options`

  Opções
  Opção | Tipo | Descrição
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Um read concern a ser aplicado à operação. Esta opção está disponível no MongoDB 3.2+ e resultará em uma exceção em tempo de execução se for especificada para uma versão de servidor mais antiga.
  readPreference | MongoDB\Driver\ReadPreference | Uma preferência de leitura a ser usada para selecionar um servidor para a operação.
  session | MongoDB\Driver\Session | Uma sessão para associar à operação.
  writeConcern | MongoDB\Driver\WriteConcern | Um write concern a ser aplicado à operação.

  Aviso

  Se uma `"session"` que tem uma transação em andamento estiver sendo usada, uma opção `"readConcern"` ou `"writeConcern"` não pode ser especificada. Isso resultará em uma exceção MongoDB\Driver\Exception\InvalidArgumentException sendo lançada. Em vez disso, essas duas opções devem ser definidas ao criar a transação com MongoDB\Driver\Session::startTransaction().

### Valor Retornado

Retorna MongoDB\Driver\Cursor em caso de sucesso.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException se a opção `"session"` for usada com uma transação associada em combinação com uma opção `"readConcern"` ou `"writeConcern"`.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException se a opção `"session"` for usada em combinação com uma preocupação de escrita não confirmada.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\ConnectionException se a conexão com o servidor falhar (por outros motivos além da autenticação).
- Lança uma exceção MongoDB\Driver\Exception\AuthenticationException se a autenticação for necessária e falhar.
- Lança MongoDB\Driver\Exception\RuntimeException em outros erros (por exemplo, comando inválido, emissão de um comando de gravação para um secundário).

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | O parâmetro `options` não aceita mais uma instância de MongoDB\Driver\ReadPreference.
PECL mongodb 1.21.0 | Passar um objeto MongoDB\Driver\ReadPreference como `options` foi descontinuado e será removido na versão 2.0.
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException será lançado se a opção `"session"` for usada em combinação com uma preocupação de gravação não reconhecida.
PECL mongodb 1.4.0 | O terceiro parâmetro agora é um array `options`. Para compatibilidade com versões anteriores, este parâmetro ainda aceitará um objeto MongoDB\Driver\ReadPreference.

### Exemplos

Exemplo #1 MongoDB\Driver\Manager::executeCommand() com um comando retornando um único documento de resultado

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $command = new MongoDB\Driver\Command(['ping' => 1]);

    try {
        $cursor = $manager->executeCommand('admin', $command);
    } catch(MongoDB\Driver\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }

    /* O comando ping retorna um único documento de resultado, portanto precisamos acessar
     * o primeiro resultado no cursor. */
    $response = $cursor->toArray()[0];

    var_dump($response);

    ?>

O exemplo acima produzirá:

    array(1) {
      ["ok"]=>
      float(1)
    }

Exemplo #2 MongoDB\Driver\Manager::executeCommand() com um comando retornando um cursor

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1, 'y' => 'foo']);
    $bulk->insert(['x' => 2, 'y' => 'bar']);
    $bulk->insert(['x' => 3, 'y' => 'bar']);
    $manager->executeBulkWrite('db.collection', $bulk);

    $command = new MongoDB\Driver\Command([
        'aggregate' => 'collection',
        'pipeline' => [
            ['$group' => ['_id' => '$y', 'sum' => ['$sum' => '$x']]],
        ],
        'cursor' => new stdClass,
    ]);
    $cursor = $manager->executeCommand('db', $command);

    /* O comando agregado pode opcionalmente retornar seus resultados em um cursor em vez de
     * em um único documento de resultados. Nesse caso, podemos iterar diretamente no cursor
     * para acessar esses resultados. */
    foreach ($cursor as $document) {
        var_dump($document);
    }

    ?>

O exemplo acima produzirá:

    object(stdClass)#6 (2) {
      ["_id"]=>
      string(3) "bar"
      ["sum"]=>
      int(10)
    }
    object(stdClass)#7 (2) {
      ["_id"]=>
      string(3) "foo"
      ["sum"]=>
      int(2)
    }

Exemplo #3 Limitando o tempo de execução de um comando

O tempo de execução de um comando pode ser limitado especificando um valor para `"maxTimeMS"` no documento MongoDB\Driver\Command. Observe que esse limite de tempo é aplicado no lado do servidor e não leva em consideração a latência da rede. Consulte » Encerrar Operações em Execução no manual do MongoDB para obter mais informações.

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');

    $command = new MongoDB\Driver\Command([
        'count' => 'collection',
        'query' => ['x' => ['$gt' => 1]],
        'maxTimeMS' => 1000,
    ]);

    $cursor = $manager->executeCommand('db', $command);

    var_dump($cursor->toArray()[0]);

    ?>

Se o comando não for concluído após um segundo de tempo de execução no servidor, um MongoDB\Driver\Exception\ExecutionTimeoutException será lançado.

### Notas

> Nota: Se um `readPreference` secundário for usado, é responsabilidade do chamador garantir que o `command` possa ser executado em um secundário. Nenhuma validação é feita pelo driver.

> Nota: Este método não usa como padrão a preferência de leitura do URI de conexão do MongoDB. As aplicações que precisam desse comportamento devem considerar o uso de MongoDB\Driver\Manager::executeReadCommand().

### Veja Também

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Manager::executeReadCommand() - Executa um comando de banco de dados que faz leitura
- MongoDB\Driver\Manager::executeReadWriteCommand() - Executa um comando de banco de dados que lê e grava
- MongoDB\Driver\Manager::executeWriteCommand() - Executa um comando de banco de dados que escreve
- MongoDB\Driver\Server::executeCommand() - Executa um comando de banco de dados neste servidor

# MongoDB\Driver\Manager::executeQuery

(mongodb >=1.0.0)

MongoDB\Driver\Manager::executeQuery — Executa uma consulta ao banco de dados

### Descrição

final public function MongoDB\Driver\Manager::executeQuery(string `$namespace`, MongoDB\Driver\Query `$query`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Seleciona um servidor de acordo com a opção `"readPreference"` e executa a consulta nesse servidor.

Os valores padrão para a opção `"readPreference"` e para a opção `"readConcern"` da consulta serão inferidos de uma transação ativa (indicada pela opção `"session"`), seguidos pelo URI de conexão.

### Parâmetros

`namespace` (string)
  Um namespace totalmente qualificado (por exemplo, `"nomeDoBancoDados.nomeDaColecao"`).
`query` (MongoDB\Driver\Query)
  A consulta a ser executada.
`options`

  Opções
  Opção | Tipo | Descrição
  --- | --- | ---
  readPreference | MongoDB\Driver\ReadPreference | Uma preferência de leitura a ser usada para selecionar um servidor para a operação.
  session | MongoDB\Driver\Session | Uma sessão para associar à operação.

### Valor Retornado

Retorna MongoDB\Driver\Cursor em caso de sucesso.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\ConnectionException se a conexão com o servidor falhar (por outros motivos além da autenticação).
- Lança uma exceção MongoDB\Driver\Exception\AuthenticationException se a autenticação for necessária e falhar.
- Lança uma MongoDB\Driver\Exception\RuntimeException em outros erros (ex.: operadores inválidos de consulta).

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | O parâmetro `options` não aceita mais uma instância de MongoDB\Driver\ReadPreference.
PECL mongodb 1.21.0 | Passar um objeto MongoDB\Driver\ReadPreference como `options` foi descontinuado e será removido na versão 2.0.
PECL mongodb 1.4.0 | O terceiro parâmetro agora é um array `options`. Para compatibilidade com versões anteriores, este parâmetro ainda aceitará um objeto MongoDB\Driver\ReadPreference.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\Manager::executeQuery()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->insert(['x' => 2]);
    $bulk->insert(['x' => 3]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $filter = ['x' => ['$gt' => 1]];
    $options = [
        'projection' => ['_id' => 0],
        'sort' => ['x' => -1],
    ];

    $query = new MongoDB\Driver\Query($filter, $options);
    $cursor = $manager->executeQuery('db.collection', $query);

    foreach ($cursor as $document) {
        var_dump($document);
    }

    ?>

O exemplo acima produzirá:

    object(stdClass)#6 (1) {
      ["x"]=>
      int(3)
    }
    object(stdClass)#7 (1) {
      ["x"]=>
      int(2)
    }

Exemplo #2 Limitando o tempo de execução de uma consulta

A opção `"maxTimeMS"` da classeMongoDB\Driver\Query pode ser usada para limitar o tempo de execução de uma consulta. Observe que esse limite de tempo é aplicado no lado do servidor e não leva em consideração a latência da rede. Consulte » Encerrar Operações em Execução no manual do MongoDB para obter mais informações.

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');

    $filter = ['x' => ['$gt' => 1]];
    $options = [
        'maxTimeMS' => 1000,
    ];

    $query = new MongoDB\Driver\Query($filter, $options);
    $cursor = $manager->executeQuery('db.collection', $query);

    foreach ($cursor as $document) {
        var_dump($document);
    }

    ?>

Se a consulta não for concluída após um segundo de tempo de execução no servidor, uma MongoDB\Driver\Exception\ExecutionTimeoutException será lançada.

### Veja Também

- MongoDB\Driver\Cursor
- MongoDB\Driver\Query
- MongoDB\Driver\ReadPreference
- MongoDB\Driver\Server::executeQuery() - Executa uma consulta de banco de dados neste servidor

# MongoDB\Driver\Manager::executeReadCommand

(mongodb >=1.4.0)

MongoDB\Driver\Manager::executeReadCommand — Executa um comando de banco de dados que faz leitura

### Descrição

final public function MongoDB\Driver\Manager::executeReadCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Seleciona um servidor de acordo com a opção `"readPreference"` e executa o comando nesse servidor.

Este método aplicará uma lógica específica para comandos de leitura (por exemplo, » distinct). Os valores padrão para as opções `"readPreference"` e `"readConcern"` serão inferidos de uma transação ativa (indicada pela opção `"session"`), seguido pelo URI de conexão.

### Parâmetros

`db` (string)
  O nome do banco de dados no qual executar o comando.
`command` (MongoDB\Driver\Command)
  O comando a ser executado.
`options`

  Opções
  Opção | Tipo | Descrição
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Um read concern a ser aplicado à operação. Esta opção está disponível no MongoDB 3.2+ e resultará em uma exceção em tempo de execução se for especificada para uma versão de servidor mais antiga.
  readPreference | MongoDB\Driver\ReadPreference | Uma preferência de leitura a ser usada para selecionar um servidor para a operação.
  session | MongoDB\Driver\Session | Uma sessão para associar à operação.

  Aviso

  Se uma `"session"` que tem uma transação em andamento estiver sendo usada, uma opção `"readConcern"` ou `"writeConcern"` não pode ser especificada. Isso resultará em uma exceção MongoDB\Driver\Exception\InvalidArgumentException sendo lançada. Em vez disso, essas duas opções devem ser definidas ao criar a transação com MongoDB\Driver\Session::startTransaction().

### Valor Retornado

Retorna MongoDB\Driver\Cursor em caso de sucesso.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException se a opção `"session"` for usada com uma transação associada em combinação com uma opção `"readConcern"` ou `"writeConcern"`.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\ConnectionException se a conexão com o servidor falhar (por outros motivos além da autenticação).
- Lança uma exceção MongoDB\Driver\Exception\AuthenticationException se a autenticação for necessária e falhar.
- Lança uma MongoDB\Driver\Exception\RuntimeException em outros erros (ex.: comando inválido).

### Veja Também

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Manager::executeCommand() - Executa um comando de banco de dados
- MongoDB\Driver\Manager::executeReadWriteCommand() - Executa um comando de banco de dados que lê e grava
- MongoDB\Driver\Manager::executeWriteCommand() - Executa um comando de banco de dados que escreve
- MongoDB\Driver\Server::executeReadCommand() - Executa um comando de banco de dados que lê neste servidor

# MongoDB\Driver\Manager::executeReadWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Manager::executeReadWriteCommand — Executa um comando de banco de dados que lê e grava

### Descrição

final public function MongoDB\Driver\Manager::executeReadWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Executa o comando no servidor primário.

Este método aplicará lógica específica para comandos de leitura e gravação (por exemplo, » aggregate). Os valores padrão para as opções `"readConcern"` e `"writeConcern"` serão inferidos de uma transação ativa (indicada pela opção `"session"`), seguido pelo URI de conexão.

### Parâmetros

`db` (string)
  O nome do banco de dados no qual executar o comando.
`command` (MongoDB\Driver\Command)
  O comando a ser executado.
`options`

  Opções
  Opção | Tipo | Descrição
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Um read concern a ser aplicado à operação. Esta opção está disponível no MongoDB 3.2+ e resultará em uma exceção em tempo de execução se for especificada para uma versão de servidor mais antiga.
  session | MongoDB\Driver\Session | Uma sessão para associar à operação.
  writeConcern | MongoDB\Driver\WriteConcern | Um write concern a ser aplicado à operação.

  Aviso

  Se uma `"session"` que tem uma transação em andamento estiver sendo usada, uma opção `"readConcern"` ou `"writeConcern"` não pode ser especificada. Isso resultará em uma exceção MongoDB\Driver\Exception\InvalidArgumentException sendo lançada. Em vez disso, essas duas opções devem ser definidas ao criar a transação com MongoDB\Driver\Session::startTransaction().

### Valor Retornado

Retorna MongoDB\Driver\Cursor em caso de sucesso.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException se a opção `"session"` for usada com uma transação associada em combinação com uma opção `"readConcern"` ou `"writeConcern"`.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException se a opção `"session"` for usada em combinação com uma preocupação de escrita não confirmada.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\ConnectionException se a conexão com o servidor falhar (por outros motivos além da autenticação).
- Lança uma exceção MongoDB\Driver\Exception\AuthenticationException se a autenticação for necessária e falhar.
- Lança uma MongoDB\Driver\Exception\RuntimeException em outros erros (ex.: comando inválido).

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException será lançada se a opção `"session"` for usada em combinação com uma preocupação de gravação não reconhecida.

### Veja Também

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Manager::executeCommand() - Executa um comando de banco de dados
- MongoDB\Driver\Manager::executeReadCommand() - Executa um comando de banco de dados que faz leitura
- MongoDB\Driver\Manager::executeWriteCommand() - Executa um comando de banco de dados que escreve
- MongoDB\Driver\Server::executeReadWriteCommand() - Executa um comando de banco de dados que lê e grava neste servidor

# MongoDB\Driver\Manager::executeWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Manager::executeWriteCommand — Executa um comando de banco de dados que escreve

### Descrição

final public function MongoDB\Driver\Manager::executeWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Executa o comando no servidor primário.

Este método aplicará lógica específica para comandos que escrevem (por exemplo, » drop). O valor padrão para a opção `"writeConcern"` será inferido de uma transação ativa (indicada pela opção `"session"`), seguido pelo URI de conexão.

> Nota: Este método não se destina a ser usado para executar » insert, » update ou » delete. Os usuários são incentivados a usar MongoDB\Driver\Manager::executeBulkWrite() para essas operações.

### Parâmetros

`db` (string)
  O nome do banco de dados no qual executar o comando.
`command` (MongoDB\Driver\Command)
  O comando a ser executado.
`options`

  Opções
  Opção | Tipo | Descrição
  --- | --- | ---
  session | MongoDB\Driver\Session | Uma sessão para associar à operação.
  writeConcern | MongoDB\Driver\WriteConcern | Um write concern a ser aplicado à operação.

  Aviso

  Se uma `"session"` que tem uma transação em andamento estiver sendo usada, uma opção `"readConcern"` ou `"writeConcern"` não pode ser especificada. Isso resultará em uma exceção MongoDB\Driver\Exception\InvalidArgumentException sendo lançada. Em vez disso, essas duas opções devem ser definidas ao criar a transação com MongoDB\Driver\Session::startTransaction().

### Valor Retornado

Retorna MongoDB\Driver\Cursor em caso de sucesso.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException se a opção `"session"` for usada com uma transação associada em combinação com uma opção `"readConcern"` ou `"writeConcern"`.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException se a opção `"session"` for usada em combinação com uma preocupação de escrita não confirmada.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\ConnectionException se a conexão com o servidor falhar (por outros motivos além da autenticação).
- Lança uma exceção MongoDB\Driver\Exception\AuthenticationException se a autenticação for necessária e falhar.
- Lança uma MongoDB\Driver\Exception\RuntimeException em outros erros (ex.: comando inválido).

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException será lançada se a opção `"session"` for usada em combinação com uma preocupação de gravação não reconhecida.

### Veja Também

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Manager::executeCommand() - Executa um comando de banco de dados
- MongoDB\Driver\Manager::executeReadCommand() - Executa um comando de banco de dados que faz leitura
- MongoDB\Driver\Manager::executeReadWriteCommand() - Executa um comando de banco de dados que lê e grava
- MongoDB\Driver\Server::executeWriteCommand() - Executa um comando de banco de dados que grava neste servidor

# MongoDB\Driver\Manager::getEncryptedFieldsMap

(mongodb >=1.14.0)

MongoDB\Driver\Manager::getEncryptedFieldsMap — Retorna a opção de mapa de campos critografados da criptografia automática para o gerenciador

### Descrição

final public function MongoDB\Driver\Manager::getEncryptedFieldsMap(): array|object|null

Retorna a opção de criptografia automática `encryptedFieldsMap` para o gerenciador, se especificado.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

A opção de criptografia automática `encryptedFieldsMap` para o gerenciador ou `null` se não foi especificado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Manager::__construct() - Cria um novo gerenciador MongoDB

# MongoDB\Driver\Manager::getReadConcern

(mongodb >=1.1.0)

MongoDB\Driver\Manager::getReadConcern — Retorna a preocupação de leitura para o gerenciador

### Descrição

final public function MongoDB\Driver\Manager::getReadConcern(): MongoDB\Driver\ReadConcern

Retorna o MongoDB\Driver\ReadConcern para o gerenciador, que é derivado de suas opções de URI. Esta é a preocupação de leitura padrão para consultas e comandos executados no gerenciador.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O MongoDB\Driver\ReadConcern para o gerenciador.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\Manager::getReadConcern()

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    var_dump($manager->getReadConcern());

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017/?readConcernLevel=local');
    var_dump($manager->getReadConcern());

    ?>

O exemplo acima produzirá algo semelhante a:

    object(MongoDB\Driver\ReadConcern)#2 (0) {
    }
    object(MongoDB\Driver\ReadConcern)#1 (1) {
      ["level"]=>
      string(5) "local"
    }

### Veja Também

- MongoDB\Driver\ReadConcern
- MongoDB\Driver\Manager::__construct() - Cria um novo gerenciador MongoDB

# MongoDB\Driver\Manager::getReadPreference

(mongodb >=1.0.0)

MongoDB\Driver\Manager::getReadPreference — Retorna a preferência de leitura para o gerenciador

### Descrição

final public function MongoDB\Driver\Manager::getReadPreference(): MongoDB\Driver\ReadPreference

Retorna o MongoDB\Driver\ReadPreference para o gerenciador, que é derivado de suas opções de URI. Esta é a preferência de leitura padrão para consultas e comandos executados no gerenciador.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O MongoDB\Driver\ReadPreference para o gerenciador.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\Manager::getReadPreference()

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    var_dump($manager->getReadPreference());

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017/?readPreference=secondaryPreferred&readPreferenceTags=dc:ny,rack:1&readPreferenceTags=dc:ny&readPreferenceTags=');
    var_dump($manager->getReadPreference());

    ?>

O exemplo acima produzirá algo semelhante a:

    object(MongoDB\Driver\ReadPreference)#2 (1) {
      ["mode"]=>
      string(7) "primary"
    }
    object(MongoDB\Driver\ReadPreference)#1 (2) {
      ["mode"]=>
      string(18) "secondaryPreferred"
      ["tags"]=>
      array(3) {
        [0]=>
        object(stdClass)#3 (2) {
          ["dc"]=>
          string(2) "ny"
          ["rack"]=>
          string(1) "1"
        }
        [1]=>
        object(stdClass)#4 (1) {
          ["dc"]=>
          string(2) "ny"
        }
        [2]=>
        object(stdClass)#5 (0) {
        }
      }
    }

### Veja Também

- MongoDB\Driver\ReadPreference
- MongoDB\Driver\Manager::__construct() - Cria um novo gerenciador MongoDB

# MongoDB\Driver\Manager::getServers

(mongodb >=1.0.0)

MongoDB\Driver\Manager::getServers — Retorna os servidores aos quais este gerenciador está conectado

### Descrição

final public function MongoDB\Driver\Manager::getServers(): array

Retorna um array de instâncias MongoDB\Driver\Server às quais este gerenciador está conectado.

> Nota: Como o driver se conecta ao banco de dados lentamente, este método pode retornar um array vazio se for chamado antes de executar uma operação no MongoDB\Driver\Manager.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array de instâncias MongoDB\Driver\Server às quais este gerenciador está conectado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\Manager::getServers()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    /* O driver se conecta ao servidor de banco de dados lentamente, então Manager::getServers()
     * pode retornar inicialmente um array vazio. */
    var_dump($manager->getServers());

    $command = new MongoDB\Driver\Command(['ping' => 1]);
    $manager->executeCommand('db', $command);

    var_dump($manager->getServers());

    ?>

O exemplo acima produzirá algo semelhante a:

    array(0) {
    }
    array(1) {
      [0]=>
      object(MongoDB\Driver\Server)#3 (10) {
        ["host"]=>
        string(9) "localhost"
        ["port"]=>
        int(27017)
        ["type"]=>
        int(1)
        ["is_primary"]=>
        bool(false)
        ["is_secondary"]=>
        bool(false)
        ["is_arbiter"]=>
        bool(false)
        ["is_hidden"]=>
        bool(false)
        ["is_passive"]=>
        bool(false)
        ["last_hello_response"]=>
        array(8) {
          ["isWritablePrimary"]=>
          bool(true)
          ["maxBsonObjectSize"]=>
          int(16777216)
          ["maxMessageSizeBytes"]=>
          int(48000000)
          ["maxWriteBatchSize"]=>
          int(1000)
          ["localTime"]=>
          object(MongoDB\BSON\UTCDateTime)#4 (1) {
            ["milliseconds"]=>
            int(1447267964517)
          }
          ["maxWireVersion"]=>
          int(3)
          ["minWireVersion"]=>
          int(0)
          ["ok"]=>
          float(1)
        }
        ["round_trip_time"]=>
        int(554)
      }
    }

### Veja Também

- MongoDB\Driver\Server
- MongoDB\Driver\Manager::selectServer() - Seleciona um servidor que corresponde a uma preferência de leitura

# MongoDB\Driver\Manager::getWriteConcern

(mongodb >=1.0.0)

MongoDB\Driver\Manager::getWriteConcern — Retorna a procupação de gravação para o gerenciador

### Descrição

final public function MongoDB\Driver\Manager::getWriteConcern(): MongoDB\Driver\WriteConcern

Retorna o MongoDB\Driver\WriteConcern para o gerenciador, que é derivado de suas opções de URI. Esta é a preocupação de gravação padrão para gravações e comandos executados no gerenciador.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O MongoDB\Driver\WriteConcern para o gerenciador.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\Manager::getWriteConcern()

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    var_dump($manager->getWriteConcern());

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017/?w=majority&wtimeoutMS=2000');
    var_dump($manager->getWriteConcern());

    ?>

O exemplo acima produzirá algo semelhante a:

    object(MongoDB\Driver\WriteConcern)#2 (0) {
    }
    object(MongoDB\Driver\WriteConcern)#1 (2) {
      ["w"]=>
      string(8) "majority"
      ["wtimeout"]=>
      int(2000)
    }

### Veja Também

- MongoDB\Driver\WriteConcern
- MongoDB\Driver\Manager::__construct() - Cria um novo gerenciador MongoDB

# MongoDB\Driver\Manager::removeSubscriber

(mongodb >=1.10.0)

MongoDB\Driver\Manager::removeSubscriber — Cancela o registro de um assinante de evento de monitoramento com este gerenciador

### Descrição

final public function MongoDB\Driver\Manager::removeSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void

Cancela o registro de um assinante de evento de monitoramento com este gerenciador.

> Nota: Se o `subscriber` ainda não estiver registrado neste gerenciador, esta função não fará nenhuma ação.

### Parâmetros

`subscriber` (MongoDB\Driver\Monitoring\Subscriber)
  Um assinante do evento de monitoramento para cancelar o registro neste gerenciador.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Manager::addSubscriber() - Inscreve um assinante de evento de monitoramento com este gerenciador
- MongoDB\Driver\Monitoring\Subscriber
- MongoDB\Driver\Monitoring\CommandSubscriber
- MongoDB\Driver\Monitoring\removeSubscriber() - Cancela o registro de um assinante de evento de monitoramento globalmente
- Monitoramento de Desempenho de Aplicação (APM)

# MongoDB\Driver\Manager::selectServer

(mongodb >=1.0.0)

MongoDB\Driver\Manager::selectServer — Seleciona um servidor que corresponde a uma preferência de leitura

### Descrição

final public function MongoDB\Driver\Manager::selectServer(?MongoDB\Driver\ReadPreference `$readPreference` = `null`): MongoDB\Driver\Server

Seleciona um MongoDB\Driver\Server correspondente à preferência de leitura informada em `readPreference`. Se `readPreference` for `null` ou omitido, o servidor primário será selecionado por padrão. Isto pode ser usado para pré-selecionar um servidor para realizar a verificação de versão antes de executar uma operação.

> Nota: Ao contrário do MongoDB\Driver\Manager::getServers(), este método inicializará as conexões do banco de dados e realizará a descoberta do servidor, se necessário. Consulte a » Especificação de seleção de servidor para obter informações adicionais.

### Parâmetros

`readPreference` (MongoDB\Driver\ReadPreference)
  A preferência de leitura a ser usada para selecionar um servidor. Se `null` ou omitido, o servidor primário será selecionado por padrão.

### Valor Retornado

Retorna um MongoDB\Driver\Server que corresponde à preferência de leitura.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\ConnectionException se a conexão com o servidor falhar (por outros motivos além da autenticação).
- Lança uma exceção MongoDB\Driver\Exception\AuthenticationException se a autenticação for necessária e falhar.
- Lança MongoDB\Driver\Exception\RuntimeException se um servidor que corresponda à preferência de leitura não puder ser encontrado.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.11.0 | O `readPreference` agora é opcional. Se `null` ou omitido, o servidor primário será selecionado por padrão.

### Veja Também

- MongoDB\Driver\Server
- MongoDB\Driver\Manager::getServers() - Retorna os servidores aos quais este gerenciador está conectado
- » Especificação de seleção de servidor

# MongoDB\Driver\Manager::startSession

(mongodb >=1.4.0)

MongoDB\Driver\Manager::startSession — Inicia uma nova sessão de cliente para uso com este cliente

### Descrição

final public function MongoDB\Driver\Manager::startSession(?array `$options` = `null`): MongoDB\Driver\Session

Cria um objeto MongoDB\Driver\Session para as opções fornecidas. A sessão pode então ser especificada ao executar comandos, consultas e operações de gravação.

> Nota: Um MongoDB\Driver\Session só pode ser usado com o MongoDB\Driver\Manager a partir do qual foi criado.

### Parâmetros

`options`

  Opções
  Opção | Tipo | Descrição | Default
  --- | --- | --- | ---
  causalConsistency | bool | Configura a consistência causal em uma sessão. Se `true`, cada operação na sessão será ordenada causalmente após a operação anterior de leitura ou gravação. Se definido como `false`, desativa a consistência causal. Consulte » Consistência Causal no manual do MongoDB para obter mais informações. | `true`
  defaultTransactionOptions | array | Opções padrão a serem aplicadas a transações recém-criadas. Estas opções são utilizadas a menos que sejam substituídas quando uma transação é iniciada com valores diferentes para cada opção.
  Opções
  Opção | Tipo | Descrição
  --- | --- | ---
  maxCommitTimeMS | integer | A quantidade máxima de tempo em milissegundos para permitir que um único comando `commitTransaction` seja executado. Se especificada, `maxCommitTimeMS` deve ser um inteiro de 32 bits com sinal com valor maior ou igual a zero.
  readConcern | MongoDB\Driver\ReadConcern | Um read concern a ser aplicado à operação. Esta opção está disponível no MongoDB 3.2+ e resultará em uma exceção em tempo de execução se for especificada para uma versão de servidor mais antiga.
  readPreference | MongoDB\Driver\ReadPreference | Uma preferência de leitura a ser usada para selecionar um servidor para a operação.
  writeConcern | MongoDB\Driver\WriteConcern | Um write concern a ser aplicado à operação.
  Esta opção está disponível no MongoDB 4.0+. | `[]`
  snapshot | bool | Configure leituras de instantâneos em uma sessão. Se `true`, um timestamp será obtido da primeira operação de leitura suportada na sessão (ou seja, `find`, `aggregate` ou `distinct` não fragmentado). As operações de leitura subsequentes dentro da sessão utilizarão um nível de preocupação de leitura `"snapshot"` (instantâneo) para ler os dados confirmados pela maioria daquele timestamp. Se definido como `false`, desativa leituras de instantâneos. As leituras de instantâneo requerem MongoDB 5.0+ e não podem ser usadas com consistência causal, transações ou operações de gravação. Se `"snapshot"` for `true`, `"causalConsistency"` será padronizado como `false`. Consulte » Preocupação de Leitura "snapshot" no manual do MongoDB para obter mais informações. | `false`

### Valor Retornado

Retorna um MongoDB\Driver\Session.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança MongoDB\Driver\Exception\InvalidArgumentException se as opções `"causalConsistency"` e `"snapshot"` forem ambas `true`.
- Lança MongoDB\Driver\Exception\RuntimeException se a sessão não puder ser criada (ex.: libmongoc não suporta criptografia).

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.11.0 | A opção `"snapshot"` foi adicionada.
PECL mongodb 1.6.0 | A opção `"maxCommitTimeMS"` foi adicionada a `"defaultTransactionOptions"`.
PECL mongodb 1.5.0 | A opção `"defaultTransactionOptions"` foi adicionada.

### Veja Também

- MongoDB\Driver\Session
- » Consistência Causal no manual do MongoDB

## Índice

- MongoDB\Driver\Manager::addSubscriber — Inscreve um assinante de evento de monitoramento com este gerenciador
- MongoDB\Driver\Manager::__construct — Cria um novo gerenciador MongoDB
- MongoDB\Driver\Manager::createClientEncryption — Cria um novo objeto ClientEncryption
- MongoDB\Driver\Manager::executeBulkWrite — Executa uma ou mais operações de escrita
- MongoDB\Driver\Manager::executeBulkWriteCommand — Executa operações de gravação usando o comando bulkWrite
- MongoDB\Driver\Manager::executeCommand — Executa um comando de banco de dados
- MongoDB\Driver\Manager::executeQuery — Executa uma consulta ao banco de dados
- MongoDB\Driver\Manager::executeReadCommand — Executa um comando de banco de dados que faz leitura
- MongoDB\Driver\Manager::executeReadWriteCommand — Executa um comando de banco de dados que lê e grava
- MongoDB\Driver\Manager::executeWriteCommand — Executa um comando de banco de dados que escreve
- MongoDB\Driver\Manager::getEncryptedFieldsMap — Retorna a opção de mapa de campos critografados da criptografia automática para o gerenciador
- MongoDB\Driver\Manager::getReadConcern — Retorna a preocupação de leitura para o gerenciador
- MongoDB\Driver\Manager::getReadPreference — Retorna a preferência de leitura para o gerenciador
- MongoDB\Driver\Manager::getServers — Retorna os servidores aos quais este gerenciador está conectado
- MongoDB\Driver\Manager::getWriteConcern — Retorna a procupação de gravação para o gerenciador
- MongoDB\Driver\Manager::removeSubscriber — Cancela o registro de um assinante de evento de monitoramento com este gerenciador
- MongoDB\Driver\Manager::selectServer — Seleciona um servidor que corresponde a uma preferência de leitura
- MongoDB\Driver\Manager::startSession — Inicia uma nova sessão de cliente para uso com este cliente

# A classe MongoDB\Driver\Command

(mongodb >=1.0.0)

## Introdução

A classe MongoDB\Driver\Command é um objeto de valor que representa um comando de banco de dados.

Para fornecer Auxílios de Comando, o objeto MongoDB\Driver\Command deve ser composto.

## Resumo da classe

final class MongoDB\Driver\Command {
/* Métodos */
final public function __construct(array|object `$document`, ?array `$commandOptions` = `null`)
}

## Exemplos

Exemplo #1 Compondo o objeto MongoDB\Driver\Command para fornecer um auxílio na criação de coleções

    <?php
    class CreateCollection {
        protected $cmd = array();

        function __construct($collectionName) {
            $this->cmd["create"] = (string) $collectionName;
        }
        function setCappedCollection($maxBytes, $maxDocuments = false) {
            $this->cmd["capped"] = true;
            $this->cmd["size"]   = (int) $maxBytes;

            if ($maxDocuments) {
                $this->cmd["max"] = (int) $maxDocuments;
            }
        }
        function usePowerOf2Sizes($bool) {
            if ($bool) {
                $this->cmd["flags"] = 1;
            } else {
                $this->cmd["flags"] = 0;
            }
        }
        function setFlags($flags) {
            $this->cmd["flags"] = (int) $flags;
        }
        function getCommand() {
            return new MongoDB\Driver\Command($this->cmd);
        }
        function getCollectionName() {
            return $this->cmd["create"];
        }
    }

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    $createCollection = new CreateCollection("cappedCollection");
    $createCollection->setCappedCollection(64 * 1024);

    try {
        $command = $createCollection->getCommand();
        $cursor = $manager->executeCommand("databaseName", $command);
        $response = $cursor->toArray()[0];
        var_dump($response);

        $collstats = ["collstats" => $createCollection->getCollectionName()];
        $cursor = $manager->executeCommand("databaseName", new MongoDB\Driver\Command($collstats));
        $response = $cursor->toArray()[0];
        var_dump($response);
    } catch(MongoDB\Driver\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }

    ?>

O exemplo acima produzirá:

    object(MongoDB\Driver\Command)#3 (1) {
      ["command"]=>
      array(3) {
        ["create"]=>
        string(16) "cappedCollection"
        ["capped"]=>
        bool(true)
        ["size"]=>
        int(65536)
      }
    }
    array(1) {
      ["ok"]=>
      float(1)
    }
    array(16) {
      ["ns"]=>
      string(29) "databaseName.cappedCollection"
      ["count"]=>
      int(0)
      ["size"]=>
      int(0)
      ["numExtents"]=>
      int(1)
      ["storageSize"]=>
      int(65536)
      ["nindexes"]=>
      int(1)
      ["lastExtentSize"]=>
      float(65536)
      ["paddingFactor"]=>
      float(1)
      ["paddingFactorNote"]=>
      string(101) "paddingFactor is unused and unmaintained in 2.8. It remains hard coded to 1.0 for compatibility only."
      ["userFlags"]=>
      int(0)
      ["capped"]=>
      bool(true)
      ["max"]=>
      int(9223372036854775807)
      ["maxSize"]=>
      int(65536)
      ["totalIndexSize"]=>
      int(8176)
      ["indexSizes"]=>
      object(stdClass)#4 (1) {
        ["_id_"]=>
        int(8176)
      }
      ["ok"]=>
      float(1)
    }

# MongoDB\Driver\Command::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Command::__construct — Cria um novo comando

### Descrição

final public function MongoDB\Driver\Command::__construct(array|object `$document`, ?array `$commandOptions` = `null`)

Constrói um novo MongoDB\Driver\Command, que é um objeto de valor imutável que representa um comando do banco de dados. O comando pode então ser executado com MongoDB\Driver\Manager::executeCommand().

O documento completo do comando, que inclui o nome do comando e suas opções, deve ser expressado no parâmetro `document`. O parâmetro `commandOptions` só é usado para especificar opções relacionadas à execução do comando e ao MongoDB\Driver\Cursor resultante.

### Parâmetros

`document`
  O documento completo do comando, que será enviado ao servidor.
`commandOptions`

  > Nota: Não use este parâmetro para especificar opções descritas na referência do comando no manual do MongoDB. Este parâmetro só deve ser usado para as opções explicitamente listadas abaixo.

  Opções de comando
  Opção | Tipo | Descrição
  --- | --- | ---
  maxAwaitTimeMS | int | Um inteiro positivo definindo o tempo limite em milissegundos para o servidor bloquear uma operação "getMore" se nenhum dado estiver disponível. Esta opção deve ser usada somente em conjunto com comandos que retornam um cursor adaptável (ex.: » Fluxos de Alteração).

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.4.0 | Adicionado um segundo argumento `commandOptions`, que suporta a opção `"maxAwaitTimeMS"`.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\Command::__construct()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $command = new MongoDB\Driver\Command(array("buildinfo" => 1));

    try {
        $cursor = $manager->executeCommand("admin", $command);
        $response = $cursor->toArray()[0];
    } catch(MongoDB\Driver\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }
    var_dump($response);

    ?>

O exemplo acima produzirá algo semelhante a:

    array(13) {
      ["version"]=>
      string(14) "2.8.0-rc2-pre-"
      ["gitVersion"]=>
      string(62) "b743d7158f7642f4da6b7eac8320374b3b88dc2e modules: subscription"
      ["OpenSSLVersion"]=>
      string(25) "OpenSSL 1.0.1f 6 Jan 2014"
      ["sysInfo"]=>
      string(104) "Linux infant 3.16.0-24-generic #32-Ubuntu SMP Tue Oct 28 13:07:32 UTC 2014 x86_64 BOOST_LIB_VERSION=1_49"
      ["loaderFlags"]=>
      string(91) "-fPIC -pthread -Wl,-z,now -rdynamic -Wl,-Bsymbolic-functions -Wl,-z,relro -Wl,-z,now -Wl,-E"
      ["compilerFlags"]=>
      string(301) "-Wnon-virtual-dtor -Woverloaded-virtual -std=c++11 -fPIC -fno-strict-aliasing -ggdb -pthread -Wall -Wsign-compare -Wno-unknown-pragmas -Winvalid-pch -pipe -Werror -O3 -Wno-unused-local-typedefs -Wno-unused-function -Wno-deprecated-declarations -Wno-unused-but-set-variable -fno-builtin-memcmp -std=c99"
      ["allocator"]=>
      string(8) "tcmalloc"
      ["versionArray"]=>
      array(4) {
        [0]=>
        int(2)
        [1]=>
        int(8)
        [2]=>
        int(0)
        [3]=>
        int(-8)
      }
      ["javascriptEngine"]=>
      string(2) "V8"
      ["bits"]=>
      int(64)
      ["debug"]=>
      bool(false)
      ["maxBsonObjectSize"]=>
      int(16777216)
      ["ok"]=>
      float(1)
    }

Exemplo #2 Exemplo de MongoDB\Driver\Command::__construct()

Comandos também podem aceitar opções, como parte da estrutura normal que é criada para enviar ao servidor. Por exemplo, a opção `maxTimeMS` pode ser passada com a maioria dos comandos para restringir a quantidade de tempo em que um comando pode ficar em execução no servidor.

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $command = new MongoDB\Driver\Command(
        array(
            "distinct" => "beer",
            "key" => "beer_name",
            "maxTimeMS" => 10,
        )
    );

    try {
        $cursor = $manager->executeCommand("beerdb", $command);
        $response = $cursor->toArray()[0];
    } catch(MongoDB\Driver\Exception\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }
    var_dump($response);

    ?>

O exemplo acima produzirá algo semelhante a:

operation exceeded time limit

### Veja Também

- MongoDB\Driver\Manager::executeCommand() - Executa um comando de banco de dados
- MongoDB\Driver\Cursor

## Índice

- MongoDB\Driver\Command::__construct — Cria um novo comando

# A classe MongoDB\Driver\Query

(mongodb >=1.0.0)

## Introdução

A classe MongoDB\Driver\Query é um objeto de valor que representa uma consulta ao banco de dados.

## Resumo da classe

final class MongoDB\Driver\Query {
/* Métodos */
final public function __construct(array|object `$filter`, ?array `$queryOptions` = `null`)
}

# MongoDB\Driver\Query::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Query::__construct — Constrói uma nova consulta

### Descrição

final public function MongoDB\Driver\Query::__construct(array|object `$filter`, ?array `$queryOptions` = `null`)

Constrói um novo MongoDB\Driver\Query, que é um objeto de valor imutável que representa uma consulta ao banco de dados. A consulta pode então ser executada com MongoDB\Driver\Manager::executeQuery().

### Parâmetros

`filter` (array|object)
  O » predicado de consulta. Um predicado vazio corresponderá a todos os documentos da coleção.

  > Nota: Ao avaliar os critérios de consulta, o MongoDB compara os tipos e valores de acordo com suas próprias » regras de comparação para tipos BSON, que diferem das regras de comparação e do malabarismo de tipos do PHP. Ao corresponder a um tipo especial de BSON, os critérios de consulta devem usar a respectiva classe BSON (por exemplo, use MongoDB\BSON\ObjectId para corresponder a um » ObjectId).

`queryOptions`

  queryOptions
  Opção | Tipo | Descrição
  --- | --- | ---
  allowDiskUse | bool | Permite que o MongoDB use arquivos de disco temporários para armazenar dados que excedem o limite de memória do sistema de 100 megabytes durante o processamento de uma operação bloqueante de classificação.
  allowPartialResults | bool | Para consultas em uma coleção de fragmentos, retorna resultados parciais do "mongos" se alguns fragmentos não estiverem disponíveis, em vez de lançar um erro. Se não especificada, a opção obsoleta `"partial"` será usada.
  awaitData | bool | Use em conjunto com a opção `"tailable"` para bloquear temporariamente uma operação getMore no cursor se estiver no final dos dados, em vez de não retornar nenhum dado. Após um período de tempo limite, a consulta retorna normalmente.
  batchSize | int | O número de documentos a serem devolvidos no primeiro lote. O padrão é 101. Um tamanho de lote 0 significa que o cursor será estabelecido, mas nenhum documento será retornado no primeiro lote. Nas versões do MongoDB anteriores à 3.2, onde as consultas usam o protocolo de ligação legado OP_QUERY, um tamanho de lote de 1 fechará o cursor, independentemente do número de documentos correspondidos.
  collation | array|object | » Collation permite que os usuários especifiquem regras específicas do idioma para comparação de strings, como regras para maiúsculas e minúsculas e acentos. Ao especificar a collation, o campo `"locale"` é obrigatório; todos os outros campos de collation são opcionais. Para obter descrições dos campos, veja o » Documento de Collation. Se a collation não for especificada, mas a coleção tiver uma collation padrão, a operação usará a collation especificada para a coleção. Se nenhuma collation for especificada para a coleção ou para a operação, o MongoDB usará a comparação binária simples usada em versões anteriores para comparações de strings. Esta opção está disponível no MongoDB 3.4+ e resultará em uma exceção em tempo de execução se for especificada para uma versão de servidor mais antiga.
  comment | mixed | Um comentário arbitrário para ajudar a rastrear a operação por meio do perfilador do banco de dados, da saída currentOp e dos logs. O comentário pode ser qualquer tipo BSON válido para MongoDB 4.4+. Versões anteriores do servidor suportam apenas valores de string. Se não especificada, o modificador obsoleto `"$comment"` será utilizado.
  exhaust | bool | Transmite os dados a todo vapor em vários pacotes "more", supondo que o cliente lerá completamente todos os dados consultados. Mais rápido quando se está extraindo muitos dados e sabe-se que a intenção é extrair tudo. Nota: o cliente não tem permissão para não ler todos os dados, a menos que feche a conexão. Esta opção não é suportada pelo comando "find" no MongoDB 3.2+ e forçará o driver a usar a versão herdada do protocolo de ligação (ou seja, OP_QUERY).
  explain | bool | Se `true`, o MongoDB\Driver\Cursor retornado conterá um único documento que descreve o processo e os índices usados ​​para retornar a consulta. Se não especificada, o modificador obsoleto `"$explain"` será utilizado. Esta opção não é suportada pelo comando "find" no MongoDB 3.2+ e só será respeitada ao usar a versão herdada do protocolo wire (ou seja, OP_QUERY). O comando » explain deve ser usado no MongoDB 3.0+.
  hint | string|array|object | Especificação do índice. Especifique o nome do índice como uma string ou o padrão de chave do índice. Se especificado, o sistema de consulta considerará apenas os planos usando o índice sugerido. Se não especificada, a opção obsoleta `"hint"` será utilizada.
  let | array|object | Mapa de nomes e valores de parâmetros. Os valores devem ser expressões constantes ou fechadas que não fazem referência a campos do documento. Os parâmetros podem então ser acessados como variáveis em um contexto de expressão agregada (por exemplo, `$$var`). Esta opção está disponível no MongoDB 5.0+ e resultará em uma exceção em tempo de execução se for especificada para uma versão de servidor mais antiga.
  limit | int | O número máximo de documentos a serem devolvidos. Se não for especificado, o padrão será sem limite. Um limite de 0 é equivalente a não definir limite.
  max | array|object | O limite superior exclusivo para um índice específico. Se não especificada, o modificador obsoleto `"$max"` será utilizado.
  maxAwaitTimeMS | int | Inteiro positivo que indica o limite de tempo em milissegundos para o servidor bloquear uma operação "getMore" se nenhum dado estiver disponível. Esta opção só deve ser usada em conjunto com as opções `"tailable"` e `"awaitData"`.
  maxTimeMS | int | O limite de tempo cumulativo em milissegundos para operações de processamento no cursor. O MongoDB aborta a operação o mais cedo possível após o ponto de interrupção. Se não especificada, o modificador obsoleto `"$maxTimeMS"` será utilizado.
  min | array|object | O limite inferior (inclusive) para um índice específico. Se não especificada, o modificador obsoleto `"$min"` será utilizado.
  noCursorTimeout | bool | Impede que o servidor expire os cursores ociosos após um período de inatividade (10 minutos).
  projection | array|object | A » especificação de projeção para determinar quais campos devem ser incluídos nos documentos retornados. Se a funcionalidade ODM estiver sendo usada para desserializar documentos como sua classe PHP original, deve-se incluir o campo __pclass na projeção. Isso é necessário para que a desserialização funcione e, sem ela, a extensão retornará (por padrão) um objeto stdClass no lugar.
  readConcern | MongoDB\Driver\ReadConcern | Uma preocupação de leitura a ser aplicada à operação. Por padrão, a preocupação de leitura do URI de conexão do MongoDB será usada. Esta opção está disponível no MongoDB 3.2+ e resultará em uma exceção no momento da execução se especificada para uma versão mais antiga do servidor.
  returnKey | bool | Se `true`, retornará apenas as chaves de índice nos documentos resultantes. O valor padrão é `false`. Se `true` e o comando "find" não usar um índice, os documentos retornados estarão vazios. Se não especificada, o modificador obsoleto `"$returnKey"` será utilizado.
  showRecordId | bool | Determina se o identificador de registro para cada documento deve ser retornado. Se `true`, adiciona um campo `"$recordId"` de nível superior aos documentos retornados. Se não especificada, o modificador obsoleto `"$showDiskLoc"` será utilizado.
  singleBatch | bool | Determina se o cursor deve ser fechado após o primeiro lote. O padrão é `false`.
  skip | int | Número de documentos a serem ignorados. O padrão é 0.
  sort | array|object | A especificação de classificação para a ordenação dos resultados. Se não especificada, o modificador obsoleto `"$orderby"` será utilizado.
  tailable | bool | Retorna um cursor adaptável para uma coleção limitada.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | A opção `"partial"` foi removida. Em vez disso, use a opção `"allowPartialResults"`. A opção `"maxScan"` foi removida. O suporte para esta opção foi removido no MongoDB 4.2. A opção `"modifiers"` foi removida. Esta opção era usada para modificadores de consulta legados, que estão todos descontinuados. A opção `"oplogReplay"` foi removida. Ela é ignorada no MongoDB 4.4 e versões mais recentes. A opção `"snapshot"` foi removida. O suporte para esta opção foi removido no MongoDB 4.0. Um valor negativo para a opção `"limit"` não implica mais em `true` para a opção `"singleBatch"`. Para receber apenas um único lote de resultados, combine um valor positivo `"limit"` com a opção `"singleBatch"`.
PECL mongodb 1.14.0 | Adicionada a opção `"let"` A opção `"comment"` agora aceita qualquer tipo.
PECL mongodb 1.8.0 | Adicionada a opção `"allowDiskUse"`. A opção `"oplogReplay"` tornou-se obsoleta.
PECL mongodb 1.5.0 | As opções `"maxScan"` e `"snapshot"` tornaram-se obsoletas.
PECL mongodb 1.3.0 | Adicionada a opção `"maxAwaitTimeMS"`.
PECL mongodb 1.2.0 | Adicionadas as opções `"allowPartialResults"`, `"collation"`, `"comment"`, `"hint"`, `"max"`, `"maxScan"`, `"maxTimeMS"`, `"min"`, `"returnKey"`, `"showRecordId"` e `"snapshot"`. A opção `"partial"` foi renomeada para `"allowPartialResults"`. Para compatibilidade com versões anteriores, `"partial"` ainda será lida se `"allowPartialResults"` não for especificada. Removida a opção legada `"secondaryOk"`, que está obsoleta. Para consultas usando o protocolo de conexão legado OP_QUERY, o driver definirá o bit `secondaryOk` conforme necessário, de acordo com a » Especificação de Seleção de Servidor.
PECL mongodb 1.1.0 | Adicionada a opção `"readConcern"`.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\Query::__construct()

    <?php
    /* Seleciona apenas os documentos de autoria de "bjori" com pelo menos 100 visualizações */
    $filter = [
        'author' => 'bjori',
        'views' => [
            '$gte' => 100,
        ],
    ];

    $options = [
        /* Retorna somente os campos a seguir nos documentos correspondentes */
        'projection' => [
            'title' => 1,
            'article' => 1,
        ],
        /* Retorna os documentos na ordem descendente de visualizações */
        'sort' => [
            'views' => -1
        ],
    ];

    $query = new MongoDB\Driver\Query($filter, $options);

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $readPreference = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY);
    $cursor = $manager->executeQuery('databaseName.collectionName', $query, ['readPreference' => $readPreference]);

    foreach($cursor as $document) {
        var_dump($document);
    }

    ?>

### Veja Também

- MongoDB\Driver\Manager::executeQuery() - Executa uma consulta ao banco de dados
- MongoDB\Driver\Cursor

## Índice

- MongoDB\Driver\Query::__construct — Constrói uma nova consulta

# A classe MongoDB\Driver\BulkWrite

(mongodb >=1.0.0)

## Introdução

A classe MongoDB\Driver\BulkWrite coleta uma ou mais operações de gravação que devem ser enviadas ao servidor. Depois de adicionar qualquer número de operações de inserção, atualização e exclusão, a coleção pode ser executada via MongoDB\Driver\Manager::executeBulkWrite().

As operações de gravação podem ser ordenadas (padrão) ou não ordenadas. As operações de gravação ordenadas são enviadas ao servidor, na ordem fornecida, para execução serial. Se uma gravação falhar, todas as operações restantes serão abortadas. As operações não ordenadas são enviadas ao servidor em uma ordem arbitrária, onde podem ser executadas em paralelo. Quaisquer erros que ocorram são relatados após todas as operações terem sido tentadas.

## Resumo da classe

final class MongoDB\Driver\BulkWrite implements Countable {
/* Métodos */
public function __construct(?array `$options` = `null`)
public function count(): int
public function delete(array|object `$filter`, ?array `$deleteOptions` = `null`): void
public function insert(array|object `$document`): mixed
public function update(array|object `$filter`, array|object `$newObj`, ?array `$updateOptions` = `null`): void
}

## Exemplos

Exemplo #1 As operações de gravação mistas são agrupadas por tipo

Operações de gravação mistas (ou seja, inserções, atualizações e exclusões) serão agrupados em comandos de gravação para serem enviados sequencialmente ao servidor.

    <?php

    $bulk = new MongoDB\Driver\BulkWrite(['ordered' => true]);
    $bulk->insert(['_id' => 1, 'x' => 1]);
    $bulk->insert(['_id' => 2, 'x' => 2]);
    $bulk->update(['x' => 2], ['$set' => ['x' => 1]]);
    $bulk->insert(['_id' => 3, 'x' => 3]);
    $bulk->delete(['x' => 1]);

    ?>

Resultará na execução de quatro comandos de gravação (ou seja, ida e volta). Como as operações são ordenadas, a terceira inserção não pode ser enviada até que a atualização anterior seja executada.

Exemplo #2 Operações de gravação ordenadas causando um erro

    <?php

    $bulk = new MongoDB\Driver\BulkWrite(['ordered' => true]);
    $bulk->delete([]);
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 2]);
    $bulk->insert(['_id' => 3, 'hello' => 'world']);
    $bulk->update(['_id' => 3], ['$set' => ['hello' => 'earth']]);
    $bulk->insert(['_id' => 4, 'hello' => 'pluto']);
    $bulk->update(['_id' => 4], ['$set' => ['hello' => 'moon']]);
    $bulk->insert(['_id' => 3]);
    $bulk->insert(['_id' => 4]);
    $bulk->insert(['_id' => 5]);

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $writeConcern = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY, 1000);

    try {
        $result = $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch (MongoDB\Driver\Exception\BulkWriteException $e) {
        $result = $e->getWriteResult();

        // Verifica se a preocupação de gravação não pôde ser atendida
        if ($writeConcernError = $result->getWriteConcernError()) {
            printf("%s (%d): %s\n",
                $writeConcernError->getMessage(),
                $writeConcernError->getCode(),
                var_export($writeConcernError->getInfo(), true)
            );
        }

        // Verifica se alguma operação de gravação não foi concluída
        foreach ($result->getWriteErrors() as $writeError) {
            printf("Operação#%d: %s (%d)\n",
                $writeError->getIndex(),
                $writeError->getMessage(),
                $writeError->getCode()
            );
        }
    } catch (MongoDB\Driver\Exception\Exception $e) {
        printf("Outro erro: %s\n", $e->getMessage());
        exit;
    }

    printf("Inseridos %d documentos\n", $result->getInsertedCount());
    printf("Atualizados %d documentos\n", $result->getModifiedCount());

    ?>

O exemplo acima produzirá:

    Operação#7: E11000 duplicate key error index: db.collection.$_id_ dup key: { : 3 } (11000)
    Inseridos 4 documentos
    Atualizados 2 documentos

Se a preocupação de gravação não pudesse ser atendida, o exemplo acima geraria algo como:

    waiting for replication timed out (64): array (
      'wtimeout' => true,
    )
    Operação#7: E11000 duplicate key error index: databaseName.collectionName.$_id_ dup key: { : 3 } (11000)
    Inseridos 4 documentos
    Atualizados 2 documentos

Se for executado o exemplo acima, mas permitindo gravações não ordenadas:

    <?php

    $bulk = new MongoDB\Driver\BulkWrite(['ordered' => false]);
    /* ... */

    ?>

O exemplo acima produzirá:

    Operação#7: E11000 duplicate key error index: db.collection.$_id_ dup key: { : 3 } (11000)
    Operação#8: E11000 duplicate key error index: db.collection.$_id_ dup key: { : 4 } (11000)
    Inseridos 5 documentos
    Atualizados 2 documentos

## Veja Também

- MongoDB\Driver\Manager::executeBulkWrite()
- MongoDB\Driver\WriteResult
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\WriteConcernError
- MongoDB\Driver\WriteError

# MongoDB\Driver\BulkWrite::__construct

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::__construct — Cria um novo BulkWrite

### Descrição

public function MongoDB\Driver\BulkWrite::__construct(?array `$options` = `null`)

Constrói um novo MongoDB\Driver\BulkWrite, que é um objeto mutável para o qual uma ou mais operações de escrita podem ser adicionadas. As escritas podem então ser executadas com MongoDB\Driver\Manager::executeBulkWrite().

### Parâmetros

`options` (array)

  Opções
  Opção | Tipo | Descrição | Padrão
  --- | --- | --- | ---
  bypassDocumentValidation | bool | Se for igual a `true`, permite operações de inserção e atualização para contornar validação no nível de documento. Esta opção está disponível no MongoDB 3.2+ e é ignorada em versões mais antigas do servidor, que não suportam validação no nível de documento. | `false`
  comment | mixed | Um comentário arbitrário para ajudar a rastrear a operação por meio da perfilagem do banco de dados, da saída da operação atual e de registros. Esta opção está disponível no MongoDB 4.4+ e resultará em uma exceção em tempo de execução se especificada para uma versão mais antiga do servidor.
  let | array|object | Mapa de nomes e valores de parâmetros. Os valores devem ser expressões constantes ou fechadas que não fazem referência a campos do documento. Os parâmetros podem então ser acessados como variáveis em um contexto de expressão agregada (por exemplo, `$$var`). Esta opção está disponível no MongoDB 5.0+ e resultará em uma exceção em tempo de execução se for especificada para uma versão de servidor mais antiga.
  ordered | bool | As operações ordenadas (`true`) são executadas serialmente no servidor MongoDB, enquanto as operações não ordenadas (`false`) são enviadas ao servidor em uma ordem arbitrária e podem ser executadas em paralelo. | `true`

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.14.0 | Opções `"comment"` e `"let"` adicionadas.
PECL mongodb 1.1.0 | Opção `"bypassDocumentValidation"` adicionada.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\BulkWrite::__construct()

    <?php

    $bulk = new MongoDB\Driver\BulkWrite(['ordered' => true]);
    $bulk->delete([]);
    $bulk->insert(['_id' => 1, 'x' => 1]);
    $bulk->insert(['_id' => 2, 'x' => 2]);
    $bulk->update(
        ['x' => 2],
        ['$set' => ['x' => 1]],
        ['limit' => 1, 'upsert' => false]
    );
    $bulk->delete(['x' => 1], ['limit' => 1]);
    $bulk->update(
        ['_id' => 3],
        ['$set' => ['x' => 3]],
        ['limit' => 1, 'upsert' => true]
    );

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $writeConcern = new MongoDB\Driver\WriteConcern(1);

    try {
        $result = $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch (MongoDB\Driver\Exception\BulkWriteException $e) {
        $result = $e->getWriteResult();

        // Verifica se a preocupação de escrita não pôde ser atendida
        if ($writeConcernError = $result->getWriteConcernError()) {
            printf("%s (%d): %s\n",
                $writeConcernError->getMessage(),
                $writeConcernError->getCode(),
                var_export($writeConcernError->getInfo(), true)
            );
        }

        // Verifica se alguma operação de escrita não foi concluída
        foreach ($result->getWriteErrors() as $writeError) {
            printf("Operação#%d: %s (%d)\n",
                $writeError->getIndex(),
                $writeError->getMessage(),
                $writeError->getCode()
            );
        }
    } catch (MongoDB\Driver\Exception\Exception $e) {
        printf("Outro erro: %s\n", $e->getMessage());
        exit;
    }

    printf("Inserido(s) %d documento(s)\n", $result->getInsertedCount());
    printf("Atualizado(s) %d documento(s)\n", $result->getModifiedCount());
    printf("Atualizado(s)/Inserido(s) %d documento(s)\n", $result->getUpsertedCount());
    printf("Removido(s) %d documento(s)\n", $result->getDeletedCount());

    ?>

O exemplo acima produzirá:

    Inserido(s) 2 documento(s)
    Atualizado(s) 1 documento(s)
    Atualizado(s)/Inserido(s) 1 documento(s)
    Removido(s) 1 documento(s)

### Veja Também

- MongoDB\Driver\Manager::executeBulkWrite() - Executa uma ou mais operações de escrita
- MongoDB\Driver\WriteResult

# MongoDB\Driver\BulkWrite::count

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::count — Conta o número de operações de escrita em massa

### Descrição

public function MongoDB\Driver\BulkWrite::count(): int

Retorna o número de operações de escrita adicionadas ao objeto MongoDB\Driver\BulkWrite.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número de operações de escrita adicionadas ao objeto MongoDB\Driver\BulkWrite.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.2.0 | Retorna o número de operações de escrita adicionadas ao objeto MongoDB\Driver\BulkWrite. Versões anteriores retornavam o número esperado de viagens de ida e volta de cliente para servidor necessárias para executar todas as operações de escrita.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\BulkWrite::count()

    <?php

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1, 'x' => 1]);
    $bulk->insert(['_id' => 2, 'x' => 2]);
    $bulk->update(['x' => 2], ['$set' => ['x' => 1]]);
    $bulk->delete(['x' => 1]);

    var_dump(count($bulk));

    ?>

O exemplo acima produzirá:

    int(4)

# MongoDB\Driver\BulkWrite::delete

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::delete — Adiciona uma operação de remoção ao objeto de escrita em massa

### Descrição

public function MongoDB\Driver\BulkWrite::delete(array|object `$filter`, ?array `$deleteOptions` = `null`): void

Adiciona uma operação de remoção ao MongoDB\Driver\BulkWrite.

### Parâmetros

`filter` (array|object)
  O » predicado de consulta. Um predicado vazio corresponderá a todos os documentos da coleção.

  > Nota: Ao avaliar os critérios de consulta, o MongoDB compara os tipos e valores de acordo com suas próprias » regras de comparação para tipos BSON, que diferem das regras de comparação e do malabarismo de tipos do PHP. Ao corresponder a um tipo especial de BSON, os critérios de consulta devem usar a respectiva classe BSON (por exemplo, use MongoDB\BSON\ObjectId para corresponder a um » ObjectId).

`deleteOptions`

  deleteOptions
  Opção | Tipo | Descrição | Padrão
  --- | --- | --- | ---
  collation | array|object | » Collation permite que os usuários especifiquem regras específicas do idioma para comparação de strings, como regras para maiúsculas e minúsculas e acentos. Ao especificar a collation, o campo `"locale"` é obrigatório; todos os outros campos de collation são opcionais. Para obter descrições dos campos, veja o » Documento de Collation. Se a collation não for especificada, mas a coleção tiver uma collation padrão, a operação usará a collation especificada para a coleção. Se nenhuma collation for especificada para a coleção ou para a operação, o MongoDB usará a comparação binária simples usada em versões anteriores para comparações de strings. Esta opção está disponível no MongoDB 3.4+ e resultará em uma exceção em tempo de execução se for especificada para uma versão de servidor mais antiga.
  hint | string|array|object | Especificação do índice. Especifique o nome do índice como uma string ou o padrão de chave do índice. Se especificado, o sistema de consulta considerará apenas os planos usando o índice sugerido. Esta opção está disponível no MongoDB 4.4+ e resultará em uma exceção em tempo de execução se especificada para uma versão mais antiga do servidor.
  limit | bool | Exclui todos os documentos correspondentes (`false`) ou apenas o primeiro documento correspondente (`true`) | `false`

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.8.0 | Opção `"hint"` adicionada.
PECL mongodb 1.2.0 | Opção `"collation"` adicionada.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\BulkWrite::delete()

    <?php

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->delete(['x' => 1], ['limit' => 1]);
    $bulk->delete(['x' => 2], ['limit' => 0]);

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $result = $manager->executeBulkWrite('db.collection', $bulk);

    ?>

### Veja Também

- MongoDB\Driver\Manager::executeBulkWrite() - Executa uma ou mais operações de escrita
- MongoDB\Driver\WriteResult

# MongoDB\Driver\BulkWrite::insert

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::insert — Adiciona uma operação de inserção ao objeto de escrita em massa

### Descrição

public function MongoDB\Driver\BulkWrite::insert(array|object `$document`): mixed

Adiciona uma operação de inserção ao MongoDB\Driver\BulkWrite.

### Parâmetros

`document` (array|object)
  Um documento a ser inserido.

### Valor Retornado

Retorna o `_id` do documento inserido. Se o documento informado em `document` não tinha um `_id`, o objeto MongoDB\BSON\ObjectId gerado para a inserção será retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.3.0 | O `_id` do documento inserido é sempre retornado. Anteriormente, o método somente retornava um valor se um objeto MongoDB\BSON\ObjectId fosse gerado.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\BulkWrite::insert()

    <?php

    $bulk = new MongoDB\Driver\BulkWrite;

    $doc1 = ['x' => 1];
    $doc2 = ['_id' => 'custom-id', 'x' => 2];
    $doc3 = ['_id' => new MongoDB\BSON\ObjectId('0123456789abcdef01234567'), 'x' => 3];

    $id1 = $bulk->insert($doc1);
    $id2 = $bulk->insert($doc2);
    $id3 = $bulk->insert($doc3);

    var_dump($id1, $id2, $id3);

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $result = $manager->executeBulkWrite('db.collection', $bulk);

    ?>

O exemplo acima produzirá algo semelhante a:

    object(MongoDB\BSON\ObjectId)#3 (1) {
      ["oid"]=>
      string(24) "67f58058d1a0aa2fd80d55d0"
    }
    string(9) "custom-id"
    object(MongoDB\BSON\ObjectId)#4 (1) {
      ["oid"]=>
      string(24) "0123456789abcdef01234567"
    }

### Veja Também

- MongoDB\Driver\Manager::executeBulkWrite() - Executa uma ou mais operações de escrita
- MongoDB\Driver\WriteResult
- MongoDB\BSON\ObjectId
- MongoDB\BSON\Persistable

# MongoDB\Driver\BulkWrite::update

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::update — Adiciona uma operação de atualização ao objeto de escrita em massa

### Descrição

public function MongoDB\Driver\BulkWrite::update(array|object `$filter`, array|object `$newObj`, ?array `$updateOptions` = `null`): void

Adiciona uma operação de atualização ao MongoDB\Driver\BulkWrite.

### Parâmetros

`filter` (array|object)
  O » predicado de consulta. Um predicado vazio corresponderá a todos os documentos da coleção.

  > Nota: Ao avaliar os critérios de consulta, o MongoDB compara os tipos e valores de acordo com suas próprias » regras de comparação para tipos BSON, que diferem das regras de comparação e do malabarismo de tipos do PHP. Ao corresponder a um tipo especial de BSON, os critérios de consulta devem usar a respectiva classe BSON (por exemplo, use MongoDB\BSON\ObjectId para corresponder a um » ObjectId).

`newObj` (array|object)
  Um documento contendo operadores de atualização (ex.: `$set`), um documento para substituição (ou seja, somente expressões `campo:valor`), ou um » pipeline de agregação.
`updateOptions`

  updateOptions
  Opção | Tipo | Descrição | Padrão
  --- | --- | --- | ---
  arrayFilters | array | Um array de documentos de filtro que determina quais elementos do array serão modificados para uma operação de atualização em um campo do array. Consulte » Especificar arrayFilters para operações de atualização de array no manual do MongoDB para obter mais informações. Esta opção está disponível no MongoDB 3.6+ e resultará em uma exceção em tempo de execução se especificada para uma versão mais antiga do servidor.
  collation | array|object | » Collation permite que os usuários especifiquem regras específicas do idioma para comparação de strings, como regras para maiúsculas e minúsculas e acentos. Ao especificar a collation, o campo `"locale"` é obrigatório; todos os outros campos de collation são opcionais. Para obter descrições dos campos, veja o » Documento de Collation. Se a collation não for especificada, mas a coleção tiver uma collation padrão, a operação usará a collation especificada para a coleção. Se nenhuma collation for especificada para a coleção ou para a operação, o MongoDB usará a comparação binária simples usada em versões anteriores para comparações de strings. Esta opção está disponível no MongoDB 3.4+ e resultará em uma exceção em tempo de execução se for especificada para uma versão de servidor mais antiga.
  hint | string|array|object | Especificação do índice. Especifique o nome do índice como uma string ou o padrão de chave do índice. Se especificado, o sistema de consulta considerará apenas os planos usando o índice sugerido. Esta opção está disponível no MongoDB 4.2+ e resultará em uma exceção em tempo de execução se especificada para uma versão mais antiga do servidor.
  multi | bool | Atualiza apenas o primeiro documento correspondente se for igual a `false`, ou todos os documentos correspondentes se for igual a `true`. Esta opção não pode ser `true` se `newObj` for um documento de substituição. | `false`
  sort | array|object | Especifica que documento a operação atualiza se a consulta corresponder a múltiplos documentos. O primeiro documento correspondente à ordenação será atualizado. Esta opção não pode ser usada se `"multi"` for `true`. Esta opção está disponível no MongoDB 8.0+ e resultará em uma exceção no momento da execução se especificada para uma versão antiga do servidor.
  upsert | bool | Se o parâmetro `filter` não corresponder a um documento existente, insere um único documento. O documento será criado a partir de `newObj` se for um documento de substituição (ou seja, sem operadores de atualização); caso contrário, os operadores em `newObj` serão aplicados a `filter` para criar o novo documento. | `false`

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.21.0 | Adicionada a opção `"sort"`.
PECL mongodb 1.7.0 | Opção `"hint"` adicionada.
PECL mongodb 1.6.0 | O parâmetro `newObj` agora aceita um pipeline de agregação. Este recurso requer MongoDB 4.2+ e resultará em uma exceção em tempo de execução se especificado para uma versão de servidor mais antiga.
PECL mongodb 1.5.0 | Usar a opção `"arrayFilters"` resultará em uma exceção em tempo de execução se não for suportada pelo servidor. Anteriormente, nenhuma exceção seria lançada e a opção poderia ser ignorada.
PECL mongodb 1.4.0 | Opção `"arrayFilters"` adicionada.
PECL mongodb 1.2.0 | Opção `"collation"` adicionada.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\BulkWrite::update()

    <?php

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->update(
        ['x' => 2],
        ['$set' => ['y' => 3]],
        ['multi' => false, 'upsert' => false]
    );

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $result = $manager->executeBulkWrite('db.collection', $bulk);

    ?>

### Veja Também

- MongoDB\Driver\Manager::executeBulkWrite() - Executa uma ou mais operações de escrita
- MongoDB\Driver\WriteResult

## Índice

- MongoDB\Driver\BulkWrite::__construct — Cria um novo BulkWrite
- MongoDB\Driver\BulkWrite::count — Conta o número de operações de escrita em massa
- MongoDB\Driver\BulkWrite::delete — Adiciona uma operação de remoção ao objeto de escrita em massa
- MongoDB\Driver\BulkWrite::insert — Adiciona uma operação de inserção ao objeto de escrita em massa
- MongoDB\Driver\BulkWrite::update — Adiciona uma operação de atualização ao objeto de escrita em massa

# A classe MongoDB\Driver\BulkWriteCommand

(mongodb >=2.1.0)

## Introdução

MongoDB\Driver\BulkWriteCommand coleta uma ou mais operações de gravação que devem ser enviadas ao servidor usando o comando » bulkWrite introduzido no MongoDB 8.0. Após adicionar qualquer número de operações de inserção, atualização e exclusão, o comando pode ser executado via MongoDB\Driver\Manager::executeBulkWriteCommand().

Ao contrário de MongoDB\Driver\BulkWrite, onde todas as operações de gravação devem ter como alvo a mesma coleção, cada operação de gravação dentro de MongoDB\Driver\BulkWriteCommand pode ter como alvo uma coleção diferente.

As operações de gravação podem ser ordenadas (padrão) ou não ordenadas. As operações de gravação ordenadas são enviadas ao servidor, na ordem fornecida, para execução em série. Se uma gravação falhar, as operações restantes serão abortadas. As operações não ordenadas são enviadas ao servidor em uma ordem arbitrária onde podem ser executadas em paralelo. Quaisquer erros que ocorram são reportados após todas as operações terem sido tentadas.

## Resumo da classe

final class MongoDB\Driver\BulkWriteCommand implements Countable {
/* Métodos */
public function __construct(?array `$options` = `null`)
public function count(): int
public function deleteMany(string `$namespace`, array|object `$filter`, ?array `$options` = `null`): void
public function deleteOne(string `$namespace`, array|object `$filter`, ?array `$options` = `null`): void
public function insertOne(string `$namespace`, array|object `$document`): mixed
public function replaceOne(
string `$namespace`,
array|object `$filter`,
array|object `$replacement`,
?array `$options` = `null`
): void
public function updateMany(
string `$namespace`,
array|object `$filter`,
array|object `$update`,
?array `$options` = `null`
): void
public function updateOne(
string `$namespace`,
array|object `$filter`,
array|object `$update`,
?array `$options` = `null`
): void
}

## Exemplos

Exemplo #1 Operações de gravação mistas

Operações de gravação mistas (ou seja, inserções, atualizações e exclusões) serão enviadas para o servidor usando um único comando » bulkWrite.

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    // Exclui documentos de ambas as coleções
    $bulk->deleteMany('db.coll_one', []);
    $bulk->deleteMany('db.coll_two', []);

    // Insere documentos em duas coleções
    $bulk->insertOne('db.coll_one', ['_id' => 1]);
    $bulk->insertOne('db.coll_two', ['_id' => 2]);
    $bulk->insertOne('db.coll_two', ['_id' => 3]);

    // Atualiza um documento em "coll_one"
    $bulk->updateOne('db.coll_one', ['_id' => 1], ['$set' => ['x' => 1]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    printf("Inserido(s) %d documento(s)\n", $result->getInsertedCount());
    printf("Atualizado(s) %d documento(s)\n", $result->getModifiedCount());

    ?>

O exemplo acima produzirá:

    Inserido(s) 3 documento(s)
    Atualizado(s) 1 documento(s)

Exemplo #2 Operações de gravação ordenadas causando um erro

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 2]);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 3]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        $result = $e->getPartialResult();

        var_dump($e->getWriteErrors());
    }

    printf("Inserido(s) %d documento(s)\n", $result->getInsertedCount());

    ?>

O exemplo acima produzirá algo semelhante a:

    array(1) {
      [3]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(3)
        ["info"]=>
        object(stdClass)#6 (0) {
        }
      }
    }
    Inserido(s) 2 documento(s)

## Veja Também

- MongoDB\Driver\Manager::executeBulkWriteCommand()
- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\Driver\Exception\BulkWriteCommandException
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\WriteConcernError
- MongoDB\Driver\WriteError

# MongoDB\Driver\BulkWriteCommand::__construct

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::__construct — Cria um novo BulkWriteCommand

### Descrição

public function MongoDB\Driver\BulkWriteCommand::__construct(?array `$options` = `null`)

Cria um novo MongoDB\Driver\BulkWriteCommand, que pode ser usado para executar diversas operações de inserção, atualização e exclusão em várias coleções em uma única solicitação usando o comando » bulkWrite introduzido no MongoDB 8.0. Isso difere de MongoDB\Driver\BulkWrite, que é suportado por todas as versões do servidor, mas limitado a uma única coleção.

Após todas as operações de gravação terem sido adicionadas, este objeto pode ser executado com MongoDB\Driver\Manager::executeBulkWriteCommand().

### Parâmetros

`options` (array)

  Opções
  Opção | Tipo | Descrição | Padrão
  --- | --- | --- | ---
  bypassDocumentValidation | bool | Se `true`, permite que operações de inserção e atualização contornem a validação em nível de documento. | `false`
  comment | mixed | Um comentário arbitrário para ajudar a rastrear a operação por meio do profiler do banco de dados, da saída currentOp e dos registros.
  let | array|object | Mapa de nomes e valores de parâmetros. Os valores devem ser expressões constantes ou fechadas que não fazem referência a campos do documento. Os parâmetros podem então ser acessados como variáveis em um contexto de expressão agregada (por exemplo, `$$var`). Esta opção está disponível no MongoDB 5.0+ e resultará em uma exceção em tempo de execução se for especificada para uma versão de servidor mais antiga.
  ordered | bool | Se as operações nesta gravação em massa devem ser executadas na ordem em que foram especificadas. Se `false`, as gravações continuarão a ser executadas se uma gravação individual falhar. Se `true`, as gravações deixarão de ser executadas se uma gravação individual falhar. | `true`
  verboseResults | bool | Se os resultados detalhados de cada operação bem-sucedida devem ser incluídos no MongoDB\Driver\BulkWriteCommandResult retornado. | `false`

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\BulkWriteCommand::__construct()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    // Exclui documentos de ambas as coleções
    $bulk->deleteMany('db.coll_one', []);
    $bulk->deleteMany('db.coll_two', []);

    // Insere documentos em duas coleções
    $bulk->insertOne('db.coll_one', ['_id' => 1]);
    $bulk->insertOne('db.coll_two', ['_id' => 2]);
    $bulk->insertOne('db.coll_two', ['_id' => 3]);

    // Atualiza um documento em "coll_one"
    $bulk->updateOne('db.coll_one', ['_id' => 1], ['$set' => ['x' => 1]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    printf("Inserido(s) %d documento(s)\n", $result->getInsertedCount());
    printf("Atualizado(s) %d documento(s)\n", $result->getModifiedCount());

    ?>

O exemplo acima produzirá:

    Inserido(s) 3 documento(s)
    Atualizado(s) 1 documento(s)

### Veja Também

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Executa operações de gravação usando o comando bulkWrite
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::count

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::count — Conta o número de operações de gravação no BulkWriteCommand

### Descrição

public function MongoDB\Driver\BulkWriteCommand::count(): int

Retorna o número de operações de gravação adicionadas ao objeto MongoDB\Driver\BulkWriteCommand.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número de operações de gravação adicionadas ao objeto MongoDB\Driver\BulkWriteCommand.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\BulkWriteCommand::count()

    <?php

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['_id' => 1, 'x' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 2, 'x' => 2]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['x' => 1]]);
    $bulk->deleteMany('db.coll', ['x' => 1]);

    var_dump(count($bulk));

    ?>

O exemplo acima produzirá:

    int(4)

# MongoDB\Driver\BulkWriteCommand::deleteMany

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::deleteMany — Adiciona uma operação deleteMany

### Descrição

public function MongoDB\Driver\BulkWriteCommand::deleteMany(string `$namespace`, array|object `$filter`, ?array `$options` = `null`): void

Adicione uma operação deleteMany ao MongoDB\Driver\BulkWriteCommand. Todos os documentos que correspondem a `filter` na coleção identificada por `namespace` serão excluídos.

### Parâmetros

`namespace` (string)
  Um namespace totalmente qualificado (por exemplo, `"nomeDoBancoDados.nomeDaColecao"`).
`filter` (array|object)
  O » predicado de consulta. Um predicado vazio corresponderá a todos os documentos da coleção.

  > Nota: Ao avaliar os critérios de consulta, o MongoDB compara os tipos e valores de acordo com suas próprias » regras de comparação para tipos BSON, que diferem das regras de comparação e do malabarismo de tipos do PHP. Ao corresponder a um tipo especial de BSON, os critérios de consulta devem usar a respectiva classe BSON (por exemplo, use MongoDB\BSON\ObjectId para corresponder a um » ObjectId).

`options`

  Opções
  Opção | Tipo | Descrição | Padrão
  --- | --- | --- | ---
  collation | array|object | » Collation permite que os usuários especifiquem regras específicas do idioma para comparação de strings, como regras para maiúsculas e minúsculas e acentos. Ao especificar a collation, o campo `"locale"` é obrigatório; todos os outros campos de collation são opcionais. Para obter descrições dos campos, veja o » Documento de Collation. Se a collation não for especificada, mas a coleção tiver uma collation padrão, a operação usará a collation especificada para a coleção. Se nenhuma collation for especificada para a coleção ou para a operação, o MongoDB usará a comparação binária simples usada em versões anteriores para comparações de strings. Esta opção está disponível no MongoDB 3.4+ e resultará em uma exceção em tempo de execução se for especificada para uma versão de servidor mais antiga.
  hint | string|array|object | Especificação de índice. Especifique o nome do índice como uma string ou o padrão de chave do índice. Se especificado, o sistema de consulta considerará apenas planos que utilizem o índice sugerido.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\BulkWriteCommand::deleteMany()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->deleteMany('db.coll', ['x' => ['$gt' => 1]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### Veja Também

- MongoDB\Driver\BulkWriteCommand::deleteOne() - Adiciona uma operação deleteOne
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Executa operações de gravação usando o comando bulkWrite
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::deleteOne

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::deleteOne — Adiciona uma operação deleteOne

### Descrição

public function MongoDB\Driver\BulkWriteCommand::deleteOne(string `$namespace`, array|object `$filter`, ?array `$options` = `null`): void

Adiciona uma operação deleteOne ao MongoDB\Driver\BulkWriteCommand. O primeiro documento correspondente a `filter` na coleção identificada por `namespace` será excluído.

### Parâmetros

`namespace` (string)
  Um namespace totalmente qualificado (por exemplo, `"nomeDoBancoDados.nomeDaColecao"`).
`filter` (array|object)
  O » predicado de consulta. Um predicado vazio corresponderá a todos os documentos da coleção.

  > Nota: Ao avaliar os critérios de consulta, o MongoDB compara os tipos e valores de acordo com suas próprias » regras de comparação para tipos BSON, que diferem das regras de comparação e do malabarismo de tipos do PHP. Ao corresponder a um tipo especial de BSON, os critérios de consulta devem usar a respectiva classe BSON (por exemplo, use MongoDB\BSON\ObjectId para corresponder a um » ObjectId).

`options`

  Opções
  Opção | Tipo | Descrição | Padrão
  --- | --- | --- | ---
  collation | array|object | » Collation permite que os usuários especifiquem regras específicas do idioma para comparação de strings, como regras para maiúsculas e minúsculas e acentos. Ao especificar a collation, o campo `"locale"` é obrigatório; todos os outros campos de collation são opcionais. Para obter descrições dos campos, veja o » Documento de Collation. Se a collation não for especificada, mas a coleção tiver uma collation padrão, a operação usará a collation especificada para a coleção. Se nenhuma collation for especificada para a coleção ou para a operação, o MongoDB usará a comparação binária simples usada em versões anteriores para comparações de strings. Esta opção está disponível no MongoDB 3.4+ e resultará em uma exceção em tempo de execução se for especificada para uma versão de servidor mais antiga.
  hint | string|array|object | Especificação de índice. Especifique o nome do índice como uma string ou o padrão de chave do índice. Se especificado, o sistema de consulta considerará apenas planos que utilizem o índice sugerido.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\BulkWriteCommand::deleteOne()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->deleteOne('db.coll', ['x' => 1]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### Veja Também

- MongoDB\Driver\BulkWriteCommand::deleteMany() - Adiciona uma operação deleteMany
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Executa operações de gravação usando o comando bulkWrite
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::insertOne

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::insertOne — Adiciona uma operação insertOne

### Descrição

public function MongoDB\Driver\BulkWriteCommand::insertOne(string `$namespace`, array|object `$document`): mixed

Adiciona uma operação insertOne ao MongoDB\Driver\BulkWriteCommand. O documento será inserido na coleção identificada por `namespace`.

### Parâmetros

`namespace` (string)
  Um namespace totalmente qualificado (por exemplo, `"nomeDoBancoDados.nomeDaColecao"`).
`document` (array|object)
  Um documento para inserir.

### Valor Retornado

Retorna o `_id` do documento inserido. Se o `document` não tiver um `_id`, o MongoDB\BSON\ObjectId gerado para a inserção será retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\BulkWriteCommand::insertOne()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    $doc1 = ['x' => 1];
    $doc2 = ['_id' => 'custom-id', 'x' => 2];
    $doc3 = ['_id' => new MongoDB\BSON\ObjectId('0123456789abcdef01234567'), 'x' => 3];

    $id1 = $bulk->insertOne('db.coll', $doc1);
    $id2 = $bulk->insertOne('db.coll', $doc2);
    $id3 = $bulk->insertOne('db.coll', $doc3);

    var_dump($id1, $id2, $id3);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

O exemplo acima produzirá algo semelhante a:

    object(MongoDB\BSON\ObjectId)#3 (1) {
      ["oid"]=>
      string(24) "67f58058d1a0aa2fd80d55d0"
    }
    string(9) "custom-id"
    object(MongoDB\BSON\ObjectId)#4 (1) {
      ["oid"]=>
      string(24) "0123456789abcdef01234567"
    }

### Veja Também

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Executa operações de gravação usando o comando bulkWrite
- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\BSON\ObjectId

# MongoDB\Driver\BulkWriteCommand::replaceOne

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::replaceOne — Adiciona uma operação replaceOne

### Descrição

public function MongoDB\Driver\BulkWriteCommand::replaceOne(
string `$namespace`,
array|object `$filter`,
array|object `$replacement`,
?array `$options` = `null`
): void

Adiciona uma operação replaceOne ao MongoDB\Driver\BulkWriteCommand. O primeiro documento correspondente a `filter` na coleção identificada por `namespace` será substituído.

### Parâmetros

`namespace` (string)
  Um namespace totalmente qualificado (por exemplo, `"nomeDoBancoDados.nomeDaColecao"`).
`filter` (array|object)
  O » predicado de consulta. Um predicado vazio corresponderá a todos os documentos da coleção.

  > Nota: Ao avaliar os critérios de consulta, o MongoDB compara os tipos e valores de acordo com suas próprias » regras de comparação para tipos BSON, que diferem das regras de comparação e do malabarismo de tipos do PHP. Ao corresponder a um tipo especial de BSON, os critérios de consulta devem usar a respectiva classe BSON (por exemplo, use MongoDB\BSON\ObjectId para corresponder a um » ObjectId).

`replacement` (array|object)
  Um documento de substituição.
`options`

  Opções
  Opção | Tipo | Descrição | Padrão
  --- | --- | --- | ---
  collation | array|object | » Collation permite que os usuários especifiquem regras específicas do idioma para comparação de strings, como regras para maiúsculas e minúsculas e acentos. Ao especificar a collation, o campo `"locale"` é obrigatório; todos os outros campos de collation são opcionais. Para obter descrições dos campos, veja o » Documento de Collation. Se a collation não for especificada, mas a coleção tiver uma collation padrão, a operação usará a collation especificada para a coleção. Se nenhuma collation for especificada para a coleção ou para a operação, o MongoDB usará a comparação binária simples usada em versões anteriores para comparações de strings. Esta opção está disponível no MongoDB 3.4+ e resultará em uma exceção em tempo de execução se for especificada para uma versão de servidor mais antiga.
  hint | string|array|object | Especificação de índice. Especifique o nome do índice como uma string ou o padrão de chave do índice. Se especificado, o sistema de consulta considerará apenas planos que utilizem o índice sugerido.
  sort | array|object | Especifica qual documento a operação substitui se a consulta corresponder a vários documentos. O primeiro documento correspondido pela ordem de classificação será substituído.
  upsert | bool | Se `filter` não corresponder a um documento existente, insira um único documento. O documento será criado a partir de `replacement`. | `false`

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\BulkWriteCommand::replaceOne()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->replaceOne('db.coll', ['x' => 1], ['x' => 1, 'y' => 2]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### Veja Também

- MongoDB\Driver\BulkWriteCommand::updateOne() - Adiciona uma operação updateOne
- MongoDB\Driver\BulkWriteCommand::updateMany() - Adiciona uma operação updateMany
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Executa operações de gravação usando o comando bulkWrite
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::updateMany

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::updateMany — Adiciona uma operação updateMany

### Descrição

public function MongoDB\Driver\BulkWriteCommand::updateMany(
string `$namespace`,
array|object `$filter`,
array|object `$update`,
?array `$options` = `null`
): void

Adiciona uma operação updateMany ao MongoDB\Driver\BulkWriteCommand. Todos os documentos que correspondem a `filter` na coleção identificada por `namespace` serão atualizados.

### Parâmetros

`namespace` (string)
  Um namespace totalmente qualificado (por exemplo, `"nomeDoBancoDados.nomeDaColecao"`).
`filter` (array|object)
  O » predicado de consulta. Um predicado vazio corresponderá a todos os documentos da coleção.

  > Nota: Ao avaliar os critérios de consulta, o MongoDB compara os tipos e valores de acordo com suas próprias » regras de comparação para tipos BSON, que diferem das regras de comparação e do malabarismo de tipos do PHP. Ao corresponder a um tipo especial de BSON, os critérios de consulta devem usar a respectiva classe BSON (por exemplo, use MongoDB\BSON\ObjectId para corresponder a um » ObjectId).

`update` (array|object)
  Um documento contendo operadores de atualização (por exemplo, `$set`) ou um » pipeline de agregação.
`options`

  Opções
  Opção | Tipo | Descrição | Padrão
  --- | --- | --- | ---
  arrayFilters | array | Um conjunto de documentos de filtro que determina quais elementos do conjunto devem ser modificados para uma operação de atualização em um campo do conjunto. Consulte » Especificar Filtros de Conjunto para Operações de Atualização de Conjunto no manual do MongoDB para obter mais informações.
  collation | array|object | » Collation permite que os usuários especifiquem regras específicas do idioma para comparação de strings, como regras para maiúsculas e minúsculas e acentos. Ao especificar a collation, o campo `"locale"` é obrigatório; todos os outros campos de collation são opcionais. Para obter descrições dos campos, veja o » Documento de Collation. Se a collation não for especificada, mas a coleção tiver uma collation padrão, a operação usará a collation especificada para a coleção. Se nenhuma collation for especificada para a coleção ou para a operação, o MongoDB usará a comparação binária simples usada em versões anteriores para comparações de strings. Esta opção está disponível no MongoDB 3.4+ e resultará em uma exceção em tempo de execução se for especificada para uma versão de servidor mais antiga.
  hint | string|array|object | Especificação de índice. Especifique o nome do índice como uma string ou o padrão de chave do índice. Se especificado, o sistema de consulta considerará apenas planos que utilizem o índice sugerido.
  upsert | bool | Se `filter` não corresponder a um documento existente, insira um único documento. O documento será criado aplicando operadores em `update` a quaisquer valores de campo em `filter`. | `false`

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\BulkWriteCommand::updateMany()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->updateMany('db.coll', ['x' => ['$gt' => 1]], ['$set' => ['y' => 2]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### Veja Também

- MongoDB\Driver\BulkWriteCommand::replaceOne() - Adiciona uma operação replaceOne
- MongoDB\Driver\BulkWriteCommand::updateMany()
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Executa operações de gravação usando o comando bulkWrite
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::updateOne

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::updateOne — Adiciona uma operação updateOne

### Descrição

public function MongoDB\Driver\BulkWriteCommand::updateOne(
string `$namespace`,
array|object `$filter`,
array|object `$update`,
?array `$options` = `null`
): void

Adiciona uma operação updateOne ao MongoDB\Driver\BulkWriteCommand. O primeiro documento correspondente a `filter` na coleção identificada por `namespace` será atualizado.

### Parâmetros

`namespace` (string)
  Um namespace totalmente qualificado (por exemplo, `"nomeDoBancoDados.nomeDaColecao"`).
`filter` (array|object)
  O » predicado de consulta. Um predicado vazio corresponderá a todos os documentos da coleção.

  > Nota: Ao avaliar os critérios de consulta, o MongoDB compara os tipos e valores de acordo com suas próprias » regras de comparação para tipos BSON, que diferem das regras de comparação e do malabarismo de tipos do PHP. Ao corresponder a um tipo especial de BSON, os critérios de consulta devem usar a respectiva classe BSON (por exemplo, use MongoDB\BSON\ObjectId para corresponder a um » ObjectId).

`update` (array|object)
  Um documento contendo operadores de atualização (por exemplo, `$set`) ou um » pipeline de agregação.
`options`

  Opções
  Opção | Tipo | Descrição | Padrão
  --- | --- | --- | ---
  arrayFilters | array | Um conjunto de documentos de filtro que determina quais elementos do conjunto devem ser modificados para uma operação de atualização em um campo do conjunto. Consulte » Especificar Filtros de Conjunto para Operações de Atualização de Conjunto no manual do MongoDB para obter mais informações.
  collation | array|object | » Collation permite que os usuários especifiquem regras específicas do idioma para comparação de strings, como regras para maiúsculas e minúsculas e acentos. Ao especificar a collation, o campo `"locale"` é obrigatório; todos os outros campos de collation são opcionais. Para obter descrições dos campos, veja o » Documento de Collation. Se a collation não for especificada, mas a coleção tiver uma collation padrão, a operação usará a collation especificada para a coleção. Se nenhuma collation for especificada para a coleção ou para a operação, o MongoDB usará a comparação binária simples usada em versões anteriores para comparações de strings. Esta opção está disponível no MongoDB 3.4+ e resultará em uma exceção em tempo de execução se for especificada para uma versão de servidor mais antiga.
  hint | string|array|object | Especificação de índice. Especifique o nome do índice como uma string ou o padrão de chave do índice. Se especificado, o sistema de consulta considerará apenas planos que utilizem o índice sugerido.
  sort | array|object | Especifica qual documento a operação atualiza se a consulta corresponder a vários documentos. O primeiro documento correspondido pela ordem de classificação será atualizado.
  upsert | bool | Se `filter` não corresponder a um documento existente, insira um único documento. O documento será criado aplicando operadores em `update` a quaisquer valores de campo em `filter`. | `false`

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\BulkWriteCommand::updateOne()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 2]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### Veja Também

- MongoDB\Driver\BulkWriteCommand::replaceOne() - Adiciona uma operação replaceOne
- MongoDB\Driver\BulkWriteCommand::updateMany() - Adiciona uma operação updateMany
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Executa operações de gravação usando o comando bulkWrite
- MongoDB\Driver\BulkWriteCommandResult

## Índice

- MongoDB\Driver\BulkWriteCommand::__construct — Cria um novo BulkWriteCommand
- MongoDB\Driver\BulkWriteCommand::count — Conta o número de operações de gravação no BulkWriteCommand
- MongoDB\Driver\BulkWriteCommand::deleteMany — Adiciona uma operação deleteMany
- MongoDB\Driver\BulkWriteCommand::deleteOne — Adiciona uma operação deleteOne
- MongoDB\Driver\BulkWriteCommand::insertOne — Adiciona uma operação insertOne
- MongoDB\Driver\BulkWriteCommand::replaceOne — Adiciona uma operação replaceOne
- MongoDB\Driver\BulkWriteCommand::updateMany — Adiciona uma operação updateMany
- MongoDB\Driver\BulkWriteCommand::updateOne — Adiciona uma operação updateOne

# A classe MongoDB\Driver\Session

(mongodb >=1.4.0)

## Introdução

A classe MongoDB\Driver\Session representa uma sessão do cliente e é retornada por MongoDB\Driver\Manager::startSession(). Comandos, consultas e operações de gravação podem então ser associados à sessão.

## Resumo da classe

final class MongoDB\Driver\Session {
/* Constantes */
const string TRANSACTION_NONE = none;
const string TRANSACTION_STARTING = starting;
const string TRANSACTION_IN_PROGRESS = in_progress;
const string TRANSACTION_COMMITTED = committed;
const string TRANSACTION_ABORTED = aborted;
/* Métodos */
final public function abortTransaction(): void
final public function advanceClusterTime(array|object `$clusterTime`): void
final public function advanceOperationTime(MongoDB\BSON\TimestampInterface `$operationTime`): void
final public function commitTransaction(): void
final private function __construct()
final public function endSession(): void
final public function getClusterTime(): ?object
final public function getLogicalSessionId(): object
final public function getOperationTime(): ?MongoDB\BSON\Timestamp
final public function getServer(): ?MongoDB\Driver\Server
final public function getTransactionOptions(): ?array
final public function getTransactionState(): string
final public function isDirty(): bool
final public function isInTransaction(): bool
final public function startTransaction(?array `$options` = `null`): void
}

## Constantes predefinidas

`MongoDB\Driver\Session::TRANSACTION_NONE`
  Não há nenhuma transação em andamento.
`MongoDB\Driver\Session::TRANSACTION_STARTING`
  Uma transação foi iniciada, mas nenhuma operação foi enviada ao servidor.
`MongoDB\Driver\Session::TRANSACTION_IN_PROGRESS`
  Uma transação está em andamento.
`MongoDB\Driver\Session::TRANSACTION_COMMITTED`
  A transação foi confirmada.
`MongoDB\Driver\Session::TRANSACTION_ABORTED`
  A transação foi abortada.

# MongoDB\Driver\Session::abortTransaction

(mongodb >=1.5.0)

MongoDB\Driver\Session::abortTransaction — Aborta uma transação

### Descrição

final public function MongoDB\Driver\Session::abortTransaction(): void

Encerra a transação de vários documentos e reverte quaisquer alterações de dados feitas pelas operações da transação. Ou seja, a transação termina sem salvar nenhuma das alterações feitas pelas operações da transação.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma MongoDB\Driver\Exception\RuntimeException se a transação não puder ser abortada (por exemplo, uma transação não foi iniciada).

### Veja Também

- MongoDB\Driver\Manager::startSession() - Inicia uma nova sessão de cliente para uso com este cliente
- MongoDB\Driver\Session::commitTransaction() - Confirma uma transação
- MongoDB\Driver\Session::startTransaction() - Inicia uma transação

# MongoDB\Driver\Session::advanceClusterTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::advanceClusterTime — Avança o tempo do cluster para esta sessão

### Descrição

final public function MongoDB\Driver\Session::advanceClusterTime(array|object `$clusterTime`): void

Avança o tempo do cluster para esta sessão. Se o tempo do cluster for menor ou igual ao tempo atual do cluster da sessão, esta função não terá ação.

Ao usar este método em conjunto com MongoDB\Driver\Session::advanceOperationTime() para copiar o cluster e os tempos de operação de outra sessão, é garantido que as operações nesta sessão serão causalmente consistentes com a última operação na outra sessão.

### Parâmetros

`clusterTime`
  O horário do cluster é um documento que contém um timestamp lógico e uma assinatura do servidor. Normalmente, esse valor será obtido chamando MongoDB\Driver\Session::getClusterTime() em outro objeto de sessão.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Session::advanceOperationTime() - Avança o tempo de operação desta sessão
- MongoDB\Driver\Session::getClusterTime() - Retorna o tempo do cluster para esta sessão

# MongoDB\Driver\Session::advanceOperationTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::advanceOperationTime — Avança o tempo de operação desta sessão

### Descrição

final public function MongoDB\Driver\Session::advanceOperationTime(MongoDB\BSON\TimestampInterface `$operationTime`): void

Avança o tempo de operação desta sessão. Se o tempo de operação for menor ou igual ao tempo de operação atual da sessão, esta função não terá ação.

Ao usar este método em conjunto com MongoDB\Driver\Session::advanceClusterTime() para copiar os tempos de operação e cluster de outra sessão, é garantido que as operações nesta sessão sejam causalmente consistentes com a última operação na outra sessão.

### Parâmetros

`operationTime`
  O tempo de operação é um timestamp lógico. Normalmente, esse valor será obtido chamando MongoDB\Driver\Session::getOperationTime() em outro objeto de sessão.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Session::advanceClusterTime() - Avança o tempo do cluster para esta sessão
- MongoDB\Driver\Session::getClusterTime() - Retorna o tempo do cluster para esta sessão

# MongoDB\Driver\Session::commitTransaction

(mongodb >=1.5.0)

MongoDB\Driver\Session::commitTransaction — Confirma uma transação

### Descrição

final public function MongoDB\Driver\Session::commitTransaction(): void

Salva as alterações feitas pelas operações na transação multidocumento e finaliza a transação. Até a confirmação, nenhuma das alterações de dados feitas dentro da transação será visível fora da transação.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma MongoDB\Driver\Exception\CommandException se o servidor não conseguiu confirmar a transação (por exemplo, devido a conflitos, problemas de rede). Caso o MongoDB\Driver\Exception\CommandException::getResultDocument() da exceção tenha um elemento `"errorLabels"` e este array contenha um valor `"TransientTransactionError"` ou `"UnknownTransactionCommitResult"`, é seguro tentar novamente a transação inteira. Em versões mais recentes da extensão, MongoDB\Driver\Exception\RuntimeException::hasErrorLabel() deve ser usado para testar esta situação.
- Lança uma MongoDB\Driver\Exception\RuntimeException se a transação não puder ser confirmada (por exemplo, uma transação não foi iniciada).

### Veja Também

- MongoDB\Driver\Manager::startSession() - Inicia uma nova sessão de cliente para uso com este cliente
- MongoDB\Driver\Session::abortTransaction() - Aborta uma transação
- MongoDB\Driver\Session::startTransaction() - Inicia uma transação
- MongoDB\Driver\Exception\RuntimeException::hasErrorLabel() - Retorna se um rótulo de erro está associado a uma exceção

# MongoDB\Driver\Session::__construct

(mongodb >=1.4.0)

MongoDB\Driver\Session::__construct — Cria uma nova sessão (não utilizada)

### Descrição

final private function MongoDB\Driver\Session::__construct()

Os objetos MongoDB\Driver\Session são retornados por MongoDB\Driver\Manager::startSession() e não podem ser construídos diretamente.

### Parâmetros

Esta função não possui parâmetros.

### Veja Também

- MongoDB\Driver\Manager::startSession() - Inicia uma nova sessão de cliente para uso com este cliente

# MongoDB\Driver\Session::endSession

(mongodb >=1.5.0)

MongoDB\Driver\Session::endSession — Termina uma sessão

### Descrição

final public function MongoDB\Driver\Session::endSession(): void

Este método fecha uma sessão existente. Se uma transação foi associada a esta sessão, a transação será abortada. Após chamar esse método, as aplicações não deverão invocar outros métodos na sessão.

> Nota: As sessões também são encerradas durante a coleta de lixo. Não deveria ser necessário chamar esse método em circunstâncias normais.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Manager::startSession() - Inicia uma nova sessão de cliente para uso com este cliente
- MongoDB\Driver\Session::abortTransaction() - Aborta uma transação
- MongoDB\Driver\Session::commitTransaction() - Confirma uma transação
- MongoDB\Driver\Session::startTransaction() - Inicia uma transação

# MongoDB\Driver\Session::getClusterTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::getClusterTime — Retorna o tempo do cluster para esta sessão

### Descrição

final public function MongoDB\Driver\Session::getClusterTime(): ?object

Retorna o tempo do cluster para esta sessão. Se a sessão não tiver sido usada para nenhuma operação e MongoDB\Driver\Session::advanceClusterTime() não tiver sido chamado, o tempo do cluster será `null`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o tempo do cluster para esta sessão, ou `null` se a sessão não tiver tempo de cluster.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Session::advanceClusterTime() - Avança o tempo do cluster para esta sessão

# MongoDB\Driver\Session::getLogicalSessionId

(mongodb >=1.4.0)

MongoDB\Driver\Session::getLogicalSessionId — Retorna o ID da sessão lógica desta sessão

### Descrição

final public function MongoDB\Driver\Session::getLogicalSessionId(): object

Retorna o ID da sessão lógica desta sessão, que pode ser usado para identificar as operações desta sessão no servidor.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ID da sessão lógica desta sessão.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Session::getOperationTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::getOperationTime — Retorna o tempo de operação desta sessão

### Descrição

final public function MongoDB\Driver\Session::getOperationTime(): ?MongoDB\BSON\Timestamp

Retorna o tempo de operação desta sessão. Se a sessão não tiver sido usada para nenhuma operação e MongoDB\Driver\Session::advanceOperationTime() não tiver sido chamado, o tempo de operação será `null`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o tempo de operação desta sessão, ou `null` se a sessão não tiver tempo de operação.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Session::advanceOperationTime() - Avança o tempo de operação desta sessão

# MongoDB\Driver\Session::getServer

(mongodb >=1.6.0)

MongoDB\Driver\Session::getServer — Retorna o servidor ao qual esta sessão está fixada

### Descrição

final public function MongoDB\Driver\Session::getServer(): ?MongoDB\Driver\Server

Retorna o MongoDB\Driver\Server ao qual esta sessão está fixada. Se a sessão não estiver fixada a um servidor, `null` será retornado.

A fixação de sessão é usada principalmente para transações fragmentadas, pois todos os comandos dentro de uma transação fragmentada devem ser enviados para a mesma instância do mongos. Este método destina-se a ser usado por bibliotecas construídas sobre a extensão para permitir o uso de um servidor fixado em vez de invocar a seleção do servidor.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o MongoDB\Driver\Server ao qual esta sessão está fixada ou `null` se a sessão não estiver fixada em nenhum servidor.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Session::getTransactionOptions

(mongodb >=1.7.0)

MongoDB\Driver\Session::getTransactionOptions — Retorna opções para a transação atualmente em execução

### Descrição

final public function MongoDB\Driver\Session::getTransactionOptions(): ?array

Retorna opções para a transação atualmente em execução.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array contendo opções de transação atuais, ou `null` se nenhuma transação estiver em execução.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Session::getTransactionState() - Retorna o estado atual da transação para esta sessão

# MongoDB\Driver\Session::getTransactionState

(mongodb >=1.7.0)

MongoDB\Driver\Session::getTransactionState — Retorna o estado atual da transação para esta sessão

### Descrição

final public function MongoDB\Driver\Session::getTransactionState(): string

Retorna o estado da transação para esta sessão.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o estado atual da transação para esta sessão.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Session::isInTransaction() - Retorna se uma transação com vários documentos está em andamento
- MongoDB\Driver\Session::getTransactionOptions() - Retorna opções para a transação atualmente em execução

# MongoDB\Driver\Session::isDirty

(mongodb >=1.13.0)

MongoDB\Driver\Session::isDirty — Retorna se a sessão foi marcada como suja

### Descrição

final public function MongoDB\Driver\Session::isDirty(): bool

Retorna se a sessão foi marcada como suja (ou seja, foi usada com um comando que encontrou um erro de rede).

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna se a sessão foi marcada como suja.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Session::isInTransaction

(mongodb >=1.6.0)

MongoDB\Driver\Session::isInTransaction — Retorna se uma transação com vários documentos está em andamento

### Descrição

final public function MongoDB\Driver\Session::isInTransaction(): bool

Retorna se uma transação de vários documentos está em andamento para esta sessão. Uma transação é considerada “em andamento” se tiver sido iniciada, mas não tiver sido confirmada ou abortada.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se uma transação estiver em andamento para esta sessão ou `false` caso contrário.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Session::getTransactionState() - Retorna o estado atual da transação para esta sessão

# MongoDB\Driver\Session::startTransaction

(mongodb >=1.5.0)

MongoDB\Driver\Session::startTransaction — Inicia uma transação

### Descrição

final public function MongoDB\Driver\Session::startTransaction(?array `$options` = `null`): void

Inicia uma transação de vários documentos associada à sessão. A qualquer momento, pode-se ter no máximo uma transação aberta por sessão. Após iniciar uma transação, o objeto de sessão deve ser passado para cada operação através da opção `"session"` (por exemplo, MongoDB\Driver\Manager::executeBulkWrite()) para associar aquela operação com a transação.

As transações podem ser confirmadas por meio de MongoDB\Driver\Session::commitTransaction() e abortadas com MongoDB\Driver\Session::abortTransaction(). As transações também são abortadas automaticamente quando a sessão é fechada pela coleta de lixo ou chamando explicitamente MongoDB\Driver\Session::endSession().

### Parâmetros

`options`
  As opções podem ser passadas como argumento para este método. Cada elemento neste array de opções substitui a opção correspondente da opção `"defaultTransactionOptions"`, se definida ao iniciar a sessão com MongoDB\Driver\Manager::startSession().

  Opções
  Opção | Tipo | Descrição
  --- | --- | ---
  maxCommitTimeMS | integer | A quantidade máxima de tempo em milissegundos para permitir que um único comando `commitTransaction` seja executado. Se especificada, `maxCommitTimeMS` deve ser um inteiro de 32 bits com sinal com valor maior ou igual a zero.
  readConcern | MongoDB\Driver\ReadConcern | Um read concern a ser aplicado à operação. Esta opção está disponível no MongoDB 3.2+ e resultará em uma exceção em tempo de execução se for especificada para uma versão de servidor mais antiga.
  readPreference | MongoDB\Driver\ReadPreference | Uma preferência de leitura a ser usada para selecionar um servidor para a operação.
  writeConcern | MongoDB\Driver\WriteConcern | Um write concern a ser aplicado à operação.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma MongoDB\Driver\Exception\CommandException se a transação não pôde ser iniciada devido a um problema no servidor (por exemplo, um bloqueio não pôde ser obtido).
- Lança uma MongoDB\Driver\Exception\RuntimeException se a transação não puder ser iniciada (por exemplo, uma transação já foi iniciada).

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.6.0 | A opção `"maxCommitTimeMS"` foi adicionada.

### Veja Também

- MongoDB\Driver\Manager::startSession() - Inicia uma nova sessão de cliente para uso com este cliente
- MongoDB\Driver\Session::commitTransaction() - Confirma uma transação
- MongoDB\Driver\Session::abortTransaction() - Aborta uma transação

## Índice

- MongoDB\Driver\Session::abortTransaction — Aborta uma transação
- MongoDB\Driver\Session::advanceClusterTime — Avança o tempo do cluster para esta sessão
- MongoDB\Driver\Session::advanceOperationTime — Avança o tempo de operação desta sessão
- MongoDB\Driver\Session::commitTransaction — Confirma uma transação
- MongoDB\Driver\Session::__construct — Cria uma nova sessão (não utilizada)
- MongoDB\Driver\Session::endSession — Termina uma sessão
- MongoDB\Driver\Session::getClusterTime — Retorna o tempo do cluster para esta sessão
- MongoDB\Driver\Session::getLogicalSessionId — Retorna o ID da sessão lógica desta sessão
- MongoDB\Driver\Session::getOperationTime — Retorna o tempo de operação desta sessão
- MongoDB\Driver\Session::getServer — Retorna o servidor ao qual esta sessão está fixada
- MongoDB\Driver\Session::getTransactionOptions — Retorna opções para a transação atualmente em execução
- MongoDB\Driver\Session::getTransactionState — Retorna o estado atual da transação para esta sessão
- MongoDB\Driver\Session::isDirty — Retorna se a sessão foi marcada como suja
- MongoDB\Driver\Session::isInTransaction — Retorna se uma transação com vários documentos está em andamento
- MongoDB\Driver\Session::startTransaction — Inicia uma transação

# A classe MongoDB\Driver\ClientEncryption

(mongodb >=1.7.0)

## Introdução

A classe MongoDB\Driver\ClientEncryption lida com a criação de chaves de dados para criptografia no lado do cliente e também com criptografia e descriptografia manuais de valores.

## Resumo da classe

final class MongoDB\Driver\ClientEncryption {
/* Constantes */
const string AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC = AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic;
const string AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM = AEAD_AES_256_CBC_HMAC_SHA_512-Random;
const string ALGORITHM_INDEXED = Indexed;
const string ALGORITHM_UNINDEXED = Unindexed;
const string ALGORITHM_RANGE = Range;
const string QUERY_TYPE_EQUALITY = equality;
const string QUERY_TYPE_RANGE = range;
/* Métodos */
final public function addKeyAltName(MongoDB\BSON\Binary `$keyId`, string `$keyAltName`): ?object
final public function __construct(array `$options`)
final public function createDataKey(string `$kmsProvider`, ?array `$options` = `null`): MongoDB\BSON\Binary
final public function decrypt(MongoDB\BSON\Binary `$value`): mixed
final public function deleteKey(MongoDB\BSON\Binary `$keyId`): object
final public function encrypt(mixed `$value`, ?array `$options` = `null`): MongoDB\BSON\Binary
final public function encryptExpression(array|object `$expr`, ?array `$options` = `null`): object
final public function getKey(MongoDB\BSON\Binary `$keyId`): ?object
final public function getKeyByAltName(string `$keyAltName`): ?object
final public function getKeys(): MongoDB\Driver\Cursor
final public function removeKeyAltName(MongoDB\BSON\Binary `$keyId`, string `$keyAltName`): ?object
final public function rewrapManyDataKey(array|object `$filter`, ?array `$options` = `null`): object
}

## Constantes predefinidas

`MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC`
  Especifica um algoritmo para » criptografia determinística, que é adequado para consultas.
`MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM`
  Especifica um algoritmo para » criptografia aleatorizada
`MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED`
  Especifica um algoritmo para uma carga criptografada e indexada, que pode ser usada com criptografia consultável. Para inserir ou consultado com uma carga criptografada e indexada, a classe MongoDB\Driver\Manager precisa ser configurada com a opção `"autoEncryption"` do driver. A opção de autocriptografia `"bypassQueryAnalysis"` pode ser `true`. A opção de autocriptografia `"bypassAutoEncryption"` precisa ser `false`.
`MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED`
  Especifica um algoritmo para uma carga criptografada e não indexada.
`MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`
  Especifica um algoritmo para uma carga criptografada por intervalo, que pode ser usada com criptgrafia consultável. Para consultar com uma carga criptografada por intervalo, a classe MongoDB\Driver\Manager precisa ser configurada com a opção de driver `"autoEncryption"`. A opção de criptografia automática `"bypassQueryAnalysis"` pode ser `true`. A opção de criptografia automática `"bypassAutoEncryption"` deve ser `false`.

  > Nota: A extensão ainda não oferece suporte a consultas de intervalo para tipos de campo Decimal128 BSON.

`MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY`
  Especifica um tipo de consulta de igualdade, que é usada em conjunto com `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED`.
`MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE`
  Especifica um tipo de consulta de intervalo, que é usada em conjunto com `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`.

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Removidas as constantes `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW` e `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE_PREVIEW`.
PECL mongodb 1.20.0 | Adicionadas `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE` e `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE`. Descontinuadas `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW` e `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE_PREVIEW`.
PECL mongodb 1.16.0 | Adicionadas `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW` e `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE_PREVIEW`.
PECL mongodb 1.14.0 | Adicionadas `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED`, `MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED`, e `MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY`.

## Veja Também

- MongoDB\Driver\Manager::createClientEncryption()

# MongoDB\Driver\ClientEncryption::addKeyAltName

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::addKeyAltName — Adiciona um nome alternativo a um documento de chave

### Descrição

final public function MongoDB\Driver\ClientEncryption::addKeyAltName(MongoDB\BSON\Binary `$keyId`, string `$keyAltName`): ?object

Adiciona `keyAltName` ao conjunto de nomes alternativos para o documento da chave com o UUID `keyId` fornecido.

### Parâmetros

`keyId`
  Uma instância MongoDB\BSON\Binary com subtipo 4 (UUID) identificando o documento da chave.
`keyAltName`
  Nome alternativo a ser adicionado ao documento da chave.

### Valor Retornado

Retorna a versão anterior do documento da chave ou `null` se nenhum documento corresponder.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\ConnectionException se a conexão com o servidor falhar (por outros motivos além da autenticação).
- Lança uma exceção MongoDB\Driver\Exception\AuthenticationException se a autenticação for necessária e falhar.
- Lança uma MongoDB\Driver\Exception\RuntimeException em outros erros.

### Veja Também

- MongoDB\Driver\ClientEncryption::getKeyByAltName() - Obtém um de documento chave com um nome alternativo
- MongoDB\Driver\ClientEncryption::removeKeyAltName() - Remove um nome alternativo de um documento de chave

# MongoDB\Driver\ClientEncryption::__construct

(mongodb >=1.14.0)

MongoDB\Driver\ClientEncryption::__construct — Cria um novo objeto ClientEncryption

### Descrição

final public function MongoDB\Driver\ClientEncryption::__construct(array `$options`)

Constrói um novo objeto MongoDB\Driver\ClientEncryption com as opções especificadas.

### Parâmetros

`options`

  Opções
  Opção | Tipo | Descrição
  --- | --- | ---
  keyVaultClient | MongoDB\Driver\Manager | O gerenciador usado para rotear consultas de chave de dados. Esta opção é obrigatória (diferentemente de MongoDB\Driver\Manager::createClientEncryption()).
  keyVaultNamespace | string | Um namespace totalmente qualificado (por exemplo, `"nomeDoBancoDados.nomeDaColecao"`) denotando a coleção que contém todas as chaves de dados usadas para criptografia e descriptografia. Esta opção é obrigatória.
  kmsProviders | array | Um documento contendo a configuração de um ou mais provedores KMS, que são usados para criptografar chaves de dados. Os provedores compatíveis incluem `"aws"`, `"azure"`, `"gcp"`, `"kmip"` e `"local"` e pelo menos um deve ser especificado. Se um documento vazio for especificado para `"aws"`, `"azure"`, ou `"gcp"`, o driver tentará configurar o provedor usando » Credenciais Automáticas. O formato para `"aws"` é o seguinte:
      aws: {
          accessKeyId: <string>,
          secretAccessKey: <string>,
          sessionToken: <string opcional>
      }
  O formato para `"azure"` é o seguinte:
      azure: {
          tenantId: <string>,
          clientId: <string>,
          clientSecret: <string>,
          identityPlatformEndpoint: <string opcional> // O padrão é "login.microsoftonline.com"
      }
  O formato para `"gcp"` é o seguinte:
      gcp: {
          email: <string>,
          privateKey: <string base64>|<MongoDB\BSON\Binary>,
          endpoint: <string opcional> // O padrão é "oauth2.googleapis.com"
      }
  O formato para `"kmip"` é o seguinte:
      kmip: {
          endpoint: <string>
      }
  O formato para `"local"` é o seguinte:
      local: {
          // Chave mestra de 96 bytes usada para criptografar/descriptografar chaves de dados
          key: <string base64>|<MongoDB\BSON\Binary>
      }
  tlsOptions | array | Um documento contendo a configuração TLS para um ou mais provedores KMS. Os provedores suportados incluem `"aws"`, `"azure"`, `"gcp"` e `"kmip"`. Todos os provedores suportam as seguintes opções:
      <provider>: {
          tlsCaFile: <string opcional>,
          tlsCertificateKeyFile: <string opcional>,
          tlsCertificateKeyFilePassword: <string opcional>,
          tlsDisableOCSPEndpointCheck: <booleano opcional>
      }

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança MongoDB\Driver\Exception\RuntimeException se a extensão foi compilada sem suporte libmongocrypt

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.16.0 | O provedor AWS KMS para criptografia do lado do cliente agora aceita uma opção `"sessionToken"`, que pode ser usada para autenticação com credenciais temporárias da AWS. Adicionado `"tlsDisableOCSPEndpointCheck"` à opção `"tlsOptions"`. Se um documento vazio for especificado para o provedor KMS `"azure"` ou `"gcp"`, o driver tentará configurar o provedor usando » Credenciais Automáticas.
PECL mongodb 1.15.0 | Se um documento vazio for especificado para o provedor KMS `"aws"`, o driver tentará configurar o provedor usando » Credenciais Automáticas.

### Veja Também

- MongoDB\Driver\Manager::createClientEncryption() - Cria um novo objeto ClientEncryption
- » Criptografia explícita (manual) em nível de campo do lado do cliente no manual do MongoDB

# MongoDB\Driver\ClientEncryption::createDataKey

(mongodb >=1.7.0)

MongoDB\Driver\ClientEncryption::createDataKey — Cria um documento de chave

### Descrição

final public function MongoDB\Driver\ClientEncryption::createDataKey(string `$kmsProvider`, ?array `$options` = `null`): MongoDB\BSON\Binary

Cria um novo documento de chave e insere-o na coleção do cofre de chaves.

### Parâmetros

`kmsProvider`
  O provedor KMS (por exemplo, `"local"`, `"aws"`) que será usado para criptografar a nova chave de dados.
`options`

  Opções de chave de dados
  Opção | Tipo | Descrição
  --- | --- | ---
  masterKey | array | O documento masterKey identifica uma chave específica do KMS usada para criptografar a nova chave de dados. Esta opção é obrigatória, a menos que `kmsProvider` seja `"local"`.
  Opções do provedor `"aws"`
  Opção | Tipo | Descrição
  --- | --- | ---
  region | string | Obrigatória.
  key | string | Obrigatória. O Nome de Recurso da Amazon (ARN) para a chave mestra do cliente (CMK) da AWS.
  endpoint | string | Opcional. Um identificador de servidor alternativo para o qual enviar requisições KMS. Pode incluir o número da porta.
  Opções do provedor `"azure"`
  Opção | Tipo | Descrição
  --- | --- | ---
  keyVaultEndpoint | string | Obrigatória. Servidor com porta opcional (por exemplo, "example.vault.azure.net").
  keyName | string | Obrigatória.
  keyVersion | string | Opcional. Uma versão específica da chave nomeada. O padrão é usar a versão primária da chave.
  Opções do provedor `"gcp"`
  Opção | Tipo | Descrição
  --- | --- | ---
  projectId | string | Obrigatória.
  location | string | Obrigatória.
  keyRing | string | Obrigatória.
  keyName | string | Obrigatória.
  keyVersion | string | Opcional. Uma versão específica da chave nomeada. O padrão é usar a versão primária da chave.
  endpoint | string | Opcional. Servidor com porta opcional. O padrão é "cloudkms.googleapis.com".
  Opções do provedor `"kmip"`
  Opção | Tipo | Descrição
  --- | --- | ---
  keyId | string | Opcional. Identificador único para um objeto gerenciado de dados secretos KMIP de 96 bytes. Se não especificado, o driver cria um objeto gerenciado de dados secretos KMIP aleatório de 96 bytes.
  endpoint | string | Opcional. Servidor com porta opcional.
  delegated | bool | Opcional. Se verdadeira, esta chave deve ser descriptografada pelo servidor KMIP.
  keyAltNames | array | Uma lista opcional de nomes alternativos de string usados ​​para fazer referência a uma chave. Se uma chave for criada com nomes alternativos, a criptografia poderá referir-se à chave pelo nome alternativo exclusivo em vez de por `_id`.
  keyMaterial | MongoDB\BSON\Binary | Um valor opcional de 96 bytes para usar como material de chave personalizado para a chave de dados que está sendo criada. Se keyMaterial for fornecido, o material de chave personalizado será usado para criptografar e descriptografar dados. Caso contrário, o material de chave para a nova chave de dados é gerado a partir de um dispositivo aleatório criptograficamente seguro.

### Valor Retornado

Retorna o identificador da nova chave como um objeto MongoDB\BSON\Binary com subtipo 4 (UUID).

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\ConnectionException se a conexão com o servidor falhar (por outros motivos além da autenticação).
- Lança uma exceção MongoDB\Driver\Exception\AuthenticationException se a autenticação for necessária e falhar.
- Lança MongoDB\Driver\Exception\RuntimeException em outros erros.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.20.0 | Adicionada a opção `"delegated"` à opções masterKey do provedor KMIP.
PECL mongodb 1.15.0 | Adicionada a opção `"keyMaterial"`.
PECL mongodb 1.10.0 | O Azure e o GCP agora têm suporte como provedores KMS para criptografia do lado do cliente.

# MongoDB\Driver\ClientEncryption::decrypt

(mongodb >=1.7.0)

MongoDB\Driver\ClientEncryption::decrypt — Descriptografa um valor

### Descrição

final public function MongoDB\Driver\ClientEncryption::decrypt(MongoDB\BSON\Binary `$value`): mixed

Descriptografa o valor.

### Parâmetros

`value`
  Uma instância MongoDB\BSON\Binary com subtipo 6 contendo o valor criptografado.

### Valor Retornado

Retorna o valor descriptografado conforme foi passado para MongoDB\Driver\ClientEncryption::encrypt().

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança MongoDB\Driver\Exception\EncryptionException se ocorrer um erro ao descriptografar o valor

### Veja Também

- MongoDB\Driver\ClientEncryption::encrypt() - Criptografa um valor

# MongoDB\Driver\ClientEncryption::deleteKey

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::deleteKey — Exclui um documento de chave

### Descrição

final public function MongoDB\Driver\ClientEncryption::deleteKey(MongoDB\BSON\Binary `$keyId`): object

Remove o documento de chave com o UUID `keyId` fornecido da coleção de cofres de chaves.

### Parâmetros

`keyId`
  Uma instância MongoDB\BSON\Binary com subtipo 4 (UUID) identificando o documento chave.

### Valor Retornado

Retorna o resultado da operação interna `deleteOne` na coleção de cofres de chaves.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\ConnectionException se a conexão com o servidor falhar (por outros motivos além da autenticação).
- Lança uma exceção MongoDB\Driver\Exception\AuthenticationException se a autenticação for necessária e falhar.
- Lança MongoDB\Driver\Exception\RuntimeException em outros erros.

# MongoDB\Driver\ClientEncryption::encrypt

(mongodb >=1.7.0)

MongoDB\Driver\ClientEncryption::encrypt — Criptografa um valor

### Descrição

final public function MongoDB\Driver\ClientEncryption::encrypt(mixed `$value`, ?array `$options` = `null`): MongoDB\BSON\Binary

Criptografa o valor.

### Parâmetros

`value`
  O valor a ser criptografado. Qualquer valor que possa ser inserido no MongoDB pode ser criptografado usando este método.
`options`

  Opções de criptografia
  Opção | Tipo | Descrição
  --- | --- | ---
  algorithm | string | O algoritmo de criptografia a ser usado. Esta opção é obrigatória. Especifique uma das seguintes constantes ClientEncryption: `MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC` `MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM` `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` `MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED` `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`
  contentionFactor | int | O fator de contenção para avaliar consultas com cargas indexadas e criptografadas. Esta opção só se aplica e só pode ser especificada quando `algorithm` for `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` ou `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`.
  keyAltName | string | Identifica um documento de coleção de cofres de chaves por `keyAltName`. Esta opção é mutuamente exclusiva com `keyId` e exatamente uma é necessária.
  keyId | MongoDB\BSON\Binary | Identifica uma chave de dados por `_id`. O valor é um UUID (subtipo binário 4). Esta opção é mutuamente exclusiva com `keyAltName` e exatamente uma é necessária.
  queryType | string | O tipo de consulta para avaliar consultas com cargas indexadas e criptografadas. Especifique uma das seguintes constantes ClientEncryption: `MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY` `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE` Esta opção só se aplica e só pode ser especificada quando `algorithm` for `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` ou `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`.
  rangeOpts | array | Opções de índice para um campo de criptografia consultável compatível com consultas "range". As opções abaixo devem corresponder aos valores definidos nos `encryptedFields` da coleção de destino. Para tipos de campo double e decimal128 BSON, `min`, `max` e `precision` devem ser todos definidos ou nenhum definido.
  Opções de índice de intervalo
  Opção | Tipo | Descrição
  --- | --- | ---
  min | mixed | Obrigatória se `precision` for definida. O valor BSON mínimo do intervalo.
  max | mixed | Obrigatória se `precision` for definida. O valor BSON máximo do intervalo.
  sparsity | int | Opcional. Inteiro de 64 bits positivo.
  precision | int | Opcional. Inteiro positivo de 32 bits que especifica a precisão a ser usada para criptografia explícita. Só pode ser definida para tipos de campo double ou decimal128 BSON.
  trimFactor | int | Opcional. Inteiro positivo de 32 bits.

### Valor Retornado

Retorna o valor criptografado como objeto MongoDB\BSON\Binary com subtipo 6.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança MongoDB\Driver\Exception\EncryptionException se ocorrer um erro ao criptografar o valor

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.20.0 | Adicionada a opção de intervalo `"trimFactor"`. A opção de intervalo `"sparsity"` agora é opcional.
PECL mongodb 1.16.0 | Adicionada a opção `"rangeOpts"`.
PECL mongodb 1.14.0 | Adicionadas as opções `"contentionFactor"` e `"queryType"`.

### Veja Também

- MongoDB\Driver\ClientEncryption::decrypt() - Descriptografa um valor
- MongoDB\Driver\ClientEncryption::encryptExpression() - Criptografa uma expressão de correspondência ou de agregação

# MongoDB\Driver\ClientEncryption::encryptExpression

(mongodb >=1.16.0)

MongoDB\Driver\ClientEncryption::encryptExpression — Criptografa uma expressão de correspondência ou de agregação

### Descrição

final public function MongoDB\Driver\ClientEncryption::encryptExpression(array|object `$expr`, ?array `$options` = `null`): object

Criptografa uma expressão de correspondência ou de agregação para consultar um índice de intervalo.

Para consultar com uma carga criptografada por intervalo, o MongoDB\Driver\Manager deve ser configurado com a opção de driver `"autoEncryption"`. A opção de criptografia automática `"bypassQueryAnalysis"` pode ser `true`. A opção de criptografia automática `"bypassAutoEncryption"` deve ser `false`.

> Nota: A extensão ainda não oferece suporte a consultas de intervalo para tipos de campo Decimal128 BSON.

### Parâmetros

`expr`
  A expressão de correspondência ou agregação a ser criptografada. As expressões devem usar pelo menos um dos operadores `$gt`, `$gte`, `$lt` ou `$lte`. Um operador `$and` de nível superior é necessário, mesmo que apenas um único operador de comparação seja usado. Um exemplo de expressão de correspondência suportada (aplica-se a consultas e ao estágio de agregação `$match`) é o seguinte:

      [
          '$and' => [
              [ '<field>' => [ '$gt'  => '<value1>' ] ],
              [ '<field>' => [ '$lte' => '<value2>' ] ],
          ],
      ]

  Um exemplo de expressão de agregação suportada é o seguinte:

      [
          '$and' => [
              [ '$gte' => [ '<fieldPath>', '<value1>' ] ],
              [ '$lt'  => [ '<fieldPath>', '<value2>' ] ],
          ],
      ]

`options`

  Opções de criptografia
  Opção | Tipo | Descrição
  --- | --- | ---
  algorithm | string | O algoritmo de criptografia a ser usado. Esta opção é obrigatória. Especifique uma das seguintes constantes ClientEncryption: `MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC` `MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM` `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` `MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED` `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`
  contentionFactor | int | O fator de contenção para avaliar consultas com cargas indexadas e criptografadas. Esta opção só se aplica e só pode ser especificada quando `algorithm` for `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` ou `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`.
  keyAltName | string | Identifica um documento de coleção de cofres de chaves por `keyAltName`. Esta opção é mutuamente exclusiva com `keyId` e exatamente uma é necessária.
  keyId | MongoDB\BSON\Binary | Identifica uma chave de dados por `_id`. O valor é um UUID (subtipo binário 4). Esta opção é mutuamente exclusiva com `keyAltName` e exatamente uma é necessária.
  queryType | string | O tipo de consulta para avaliar consultas com cargas indexadas e criptografadas. Especifique uma das seguintes constantes ClientEncryption: `MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY` `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE` Esta opção só se aplica e só pode ser especificada quando `algorithm` for `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` ou `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`.
  rangeOpts | array | Opções de índice para um campo de criptografia consultável compatível com consultas "range". As opções abaixo devem corresponder aos valores definidos nos `encryptedFields` da coleção de destino. Para tipos de campo double e decimal128 BSON, `min`, `max` e `precision` devem ser todos definidos ou nenhum definido.
  Opções de índice de intervalo
  Opção | Tipo | Descrição
  --- | --- | ---
  min | mixed | Obrigatória se `precision` for definida. O valor BSON mínimo do intervalo.
  max | mixed | Obrigatória se `precision` for definida. O valor BSON máximo do intervalo.
  sparsity | int | Opcional. Inteiro de 64 bits positivo.
  precision | int | Opcional. Inteiro positivo de 32 bits que especifica a precisão a ser usada para criptografia explícita. Só pode ser definida para tipos de campo double ou decimal128 BSON.
  trimFactor | int | Opcional. Inteiro positivo de 32 bits.

### Valor Retornado

Retorna a expressão criptografada como um objeto.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança MongoDB\Driver\Exception\EncryptionException se ocorrer um erro ao criptografar a expressão

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.20.0 | Adiciona a opção de intervalo `"trimFactor"` A opção de intervalo `"sparsity"` agora é opcional.

### Veja Também

- MongoDB\Driver\Manager::__construct() - Cria um novo gerenciador MongoDB
- MongoDB\Driver\ClientEncryption::encrypt() - Criptografa um valor

# MongoDB\Driver\ClientEncryption::getKey

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::getKey — Obtém um documento de chave

### Descrição

final public function MongoDB\Driver\ClientEncryption::getKey(MongoDB\BSON\Binary `$keyId`): ?object

Encontra um único documento de chave na coleção do cofre de chaves com o UUID `keyId` fornecido.

### Parâmetros

`keyId`
  Uma instância MongoDB\BSON\Binary com subtipo 4 (UUID) identificando o documento de chave.

### Valor Retornado

Retorna o documento de chave ou `null` se nenhum documento corresponder.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\ConnectionException se a conexão com o servidor falhar (por outros motivos além da autenticação).
- Lança uma exceção MongoDB\Driver\Exception\AuthenticationException se a autenticação for necessária e falhar.
- Lança MongoDB\Driver\Exception\RuntimeException em outros erros.

# MongoDB\Driver\ClientEncryption::getKeyByAltName

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::getKeyByAltName — Obtém um de documento chave com um nome alternativo

### Descrição

final public function MongoDB\Driver\ClientEncryption::getKeyByAltName(string `$keyAltName`): ?object

Encontra um único documento de chave na coleção do cofre de chaves com o nome alternativo fornecido em `keyAltName`.

### Parâmetros

`keyAltName`
  Nome alternativo para o documento de chave.

### Valor Retornado

Retorna o documento de chave ou `null` se nenhum documento corresponder.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\ConnectionException se a conexão com o servidor falhar (por outros motivos além da autenticação).
- Lança uma exceção MongoDB\Driver\Exception\AuthenticationException se a autenticação for necessária e falhar.
- Lança MongoDB\Driver\Exception\RuntimeException em outros erros.

### Veja Também

- MongoDB\Driver\ClientEncryption::addKeyAltName() - Adiciona um nome alternativo a um documento de chave
- MongoDB\Driver\ClientEncryption::removeKeyAltName() - Remove um nome alternativo de um documento de chave

# MongoDB\Driver\ClientEncryption::getKeys

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::getKeys — Obtém todos os documentos de chave

### Descrição

final public function MongoDB\Driver\ClientEncryption::getKeys(): MongoDB\Driver\Cursor

Encontra todos os documentos de chave na coleção do cofre de chaves.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna MongoDB\Driver\Cursor em caso de sucesso.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\ConnectionException se a conexão com o servidor falhar (por outros motivos além da autenticação).
- Lança uma exceção MongoDB\Driver\Exception\AuthenticationException se a autenticação for necessária e falhar.
- Lança MongoDB\Driver\Exception\RuntimeException em outros erros.

# MongoDB\Driver\ClientEncryption::removeKeyAltName

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::removeKeyAltName — Remove um nome alternativo de um documento de chave

### Descrição

final public function MongoDB\Driver\ClientEncryption::removeKeyAltName(MongoDB\BSON\Binary `$keyId`, string `$keyAltName`): ?object

Remove `keyAltName` do conjunto de nomes alternativos para o documento de chave com o UUID `keyId` fornecido.

### Parâmetros

`keyId`
  Uma instância MongoDB\BSON\Binary com subtipo 4 (UUID) identificando o documento de chave.
`keyAltName`
  Nome alternativo a ser removido do documento de chave.

### Valor Retornado

Retorna a versão anterior do documento de chave ou `null` se nenhum documento corresponder.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\ConnectionException se a conexão com o servidor falhar (por outros motivos além da autenticação).
- Lança uma exceção MongoDB\Driver\Exception\AuthenticationException se a autenticação for necessária e falhar.
- Lança MongoDB\Driver\Exception\RuntimeException em outros erros.

### Veja Também

- MongoDB\Driver\ClientEncryption::addKeyAltName() - Adiciona um nome alternativo a um documento de chave
- MongoDB\Driver\ClientEncryption::getKeyByAltName() - Obtém um de documento chave com um nome alternativo

# MongoDB\Driver\ClientEncryption::rewrapManyDataKey

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::rewrapManyDataKey — Reencapsula chaves de dados

### Descrição

final public function MongoDB\Driver\ClientEncryption::rewrapManyDataKey(array|object `$filter`, ?array `$options` = `null`): object

Reencapsula (ou seja, descriptografa e criptografa novamente) zero ou mais chaves de dados na coleção de cofres de chaves que correspondem ao filtro fornecido no parâmetro `filter`.

Se a opção `"provider"` não for especificada, as chaves de dados correspondentes serão reencapsuladas com seu provedor KMS atual. Caso contrário, as chaves de dados correspondentes serão criptografadas novamente de acordo com as opções `"provider"` e `"masterKey"` especificadas.

### Parâmetros

`filter` (array|object)
  O » predicado de consulta. Um predicado vazio corresponderá a todos os documentos da coleção.

  > Nota: Ao avaliar os critérios de consulta, o MongoDB compara os tipos e valores de acordo com suas próprias » regras de comparação para tipos BSON, que diferem das regras de comparação e do malabarismo de tipos do PHP. Ao corresponder a um tipo especial de BSON, os critérios de consulta devem usar a respectiva classe BSON (por exemplo, use MongoDB\BSON\ObjectId para corresponder a um » ObjectId).

`options`

  Opções de RewrapManyDataKey
  Opção | Tipo | Descrição
  --- | --- | ---
  provider | string | O provedor KMS (por exemplo, `"local"`, `"aws"`) que será usado para criptografar novamente as chaves de dados correspondentes. Se um provedor KMS não for especificado, as chaves de dados correspondentes serão criptografadas novamente com seu provedor KMS atual.
  masterKey | array | A masterKey identifica uma chave específica do KMS usada para criptografar a nova chave de dados. Esta opção não deve ser especificada sem a opção `"provider"`. Esta opção é necessária se `"provider"` for especificada e não `"local"`.
  Opções do provedor `"aws"`
  Opção | Tipo | Descrição
  --- | --- | ---
  region | string | Obrigatória.
  key | string | Obrigatória. O Nome de Recurso da Amazon (ARN) para a chave mestra do cliente (CMK) da AWS.
  endpoint | string | Opcional. Um identificador de servidor alternativo para o qual enviar requisições KMS. Pode incluir o número da porta.
  Opções do provedor `"azure"`
  Opção | Tipo | Descrição
  --- | --- | ---
  keyVaultEndpoint | string | Obrigatória. Servidor com porta opcional (por exemplo, "example.vault.azure.net").
  keyName | string | Obrigatória.
  keyVersion | string | Opcional. Uma versão específica da chave nomeada. O padrão é usar a versão primária da chave.
  Opções do provedor `"gcp"`
  Opção | Tipo | Descrição
  --- | --- | ---
  projectId | string | Obrigatória.
  location | string | Obrigatória.
  keyRing | string | Obrigatória.
  keyName | string | Obrigatória.
  keyVersion | string | Opcional. Uma versão específica da chave nomeada. O padrão é usar a versão primária da chave.
  endpoint | string | Opcional. Servidor com porta opcional. O padrão é "cloudkms.googleapis.com".
  Opções do provedor `"kmip"`
  Opção | Tipo | Descrição
  --- | --- | ---
  keyId | string | Opcional. Identificador único para um objeto gerenciado de dados secretos KMIP de 96 bytes. Se não especificado, o driver cria um objeto gerenciado de dados secretos KMIP aleatório de 96 bytes.
  endpoint | string | Opcional. Servidor com porta opcional.
  delegated | bool | Opcional. Se verdadeira, esta chave deve ser descriptografada pelo servidor KMIP.

### Valor Retornado

Retorna um objeto, que terá uma propriedade opcional `bulkWriteResult` contendo o resultado da operação interna `bulkWrite` como um objeto. Se nenhuma chave de dados corresponder ao filtro ou a gravação não for reconhecida, a propriedade `bulkWriteResult` será `null`.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\ConnectionException se a conexão com o servidor falhar (por outros motivos além da autenticação).
- Lança uma exceção MongoDB\Driver\Exception\AuthenticationException se a autenticação for necessária e falhar.
- Lança MongoDB\Driver\Exception\EncryptionException se ocorrer um erro ao descriptografar ou criptografar novamente uma chave de dados.
- Lança MongoDB\Driver\Exception\RuntimeException em outros erros.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.20.0 | Adicionada a opção `"delegated"` às opções masterKey do provedor KMIP.

## Índice

- MongoDB\Driver\ClientEncryption::addKeyAltName — Adiciona um nome alternativo a um documento de chave
- MongoDB\Driver\ClientEncryption::__construct — Cria um novo objeto ClientEncryption
- MongoDB\Driver\ClientEncryption::createDataKey — Cria um documento de chave
- MongoDB\Driver\ClientEncryption::decrypt — Descriptografa um valor
- MongoDB\Driver\ClientEncryption::deleteKey — Exclui um documento de chave
- MongoDB\Driver\ClientEncryption::encrypt — Criptografa um valor
- MongoDB\Driver\ClientEncryption::encryptExpression — Criptografa uma expressão de correspondência ou de agregação
- MongoDB\Driver\ClientEncryption::getKey — Obtém um documento de chave
- MongoDB\Driver\ClientEncryption::getKeyByAltName — Obtém um de documento chave com um nome alternativo
- MongoDB\Driver\ClientEncryption::getKeys — Obtém todos os documentos de chave
- MongoDB\Driver\ClientEncryption::removeKeyAltName — Remove um nome alternativo de um documento de chave
- MongoDB\Driver\ClientEncryption::rewrapManyDataKey — Reencapsula chaves de dados

# A classe MongoDB\Driver\ServerApi

(mongodb >=1.10.0)

## Introdução

## Resumo da classe

final class MongoDB\Driver\ServerApi implements MongoDB\BSON\Serializable, Serializable {
/* Constantes */
const string MongoDB\Driver\ServerAPI::V1 = "1";
/* Métodos */
final public function bsonSerialize(): stdClass
final public function __construct(string `$version`, ?bool `$strict` = `null`, ?bool `$deprecationErrors` = `null`)
}

## Constantes predefinidas

`MongoDB\Driver\ServerApi::V1`
  API do Servidor versão 1.

## Exemplos

Exemplo #1 Declara uma versão da API em um gerenciador

    <?php

    use MongoDB\Driver\Manager;
    use MongoDB\Driver\ServerApi;

    $v1 = new ServerApi(ServerApi::v1);
    $manager = new Manager('mongodb://localhost:27017', [], ['serverApi' => $v1]);

    $command = new MongoDB\Driver\Command(['buildInfo' => 1]);

    try {
        $cursor = $manager->executeCommand('admin', $command);
    } catch(MongoDB\Driver\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }

    /* O comando buildInfo retorna um único documento de resultado, portanto é necessário acessar
     * o primeiro resultado no cursor. */
    $buildInfo = $cursor->toArray()[0];

    echo $buildInfo->version, "\n";

    ?>

O exemplo acima produzirá:

    4.9.0-alpha7-49-gb968ca0

Exemplo #2 Declara uma versão estrita da API em um gerenciador

O exemplo a seguir define o sinalizador `strict`, que informa ao servidor para rejeitar qualquer comando que não faça parte da versão declarada da API. Isso resulta em um erro ao executar o comando buildInfo.

    <?php

    use MongoDB\Driver\Manager;
    use MongoDB\Driver\ServerApi;

    $v1 = new ServerApi(ServerApi::v1, true);
    $manager = new Manager('mongodb://localhost:27017', [], ['serverApi' => $v1]);

    $command = new MongoDB\Driver\Command(['buildInfo' => 1]);

    try {
        $cursor = $manager->executeCommand('admin', $command);
    } catch(MongoDB\Driver\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }

    /* O comando buildInfo retorna um único documento de resultado, portanto é necessário acessar
     * o primeiro resultado no cursor. */
    $buildInfo = $cursor->toArray()[0];

    echo $buildInfo->version, "\n";

    ?>

O exemplo acima produzirá:

    Provided apiStrict:true, but the command buildInfo is not in API Version 1

# MongoDB\Driver\ServerApi::bsonSerialize

(mongodb >=1.10.0)

MongoDB\Driver\ServerApi::bsonSerialize — Retorna um objeto para serialização BSON

### Descrição

final public function MongoDB\Driver\ServerApi::bsonSerialize(): stdClass

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um objeto para serializar o ServerApi como BSON.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\BSON\Serializable::bsonSerialize() - Fornece um array ou documento para serializar como BSON

# MongoDB\Driver\ServerApi::__construct

(mongodb >=1.10.0)

MongoDB\Driver\ServerApi::__construct — Cria uma nova instância de ServerApi

### Descrição

final public function MongoDB\Driver\ServerApi::__construct(string `$version`, ?bool `$strict` = `null`, ?bool `$deprecationErrors` = `null`)

Cria uma nova instância MongoDB\Driver\ServerApi usada para declarar uma versão da API ao criar um MongoDB\Driver\Manager.

### Parâmetros

`version`
  Uma versão da API do servidor. Versões de API suportadas são fornecidas como constantes em MongoDB\Driver\ServerApi. A única versão da API suportada é `MongoDB\Driver\ServerApi::V1`.
`strict`
  Se o parâmetro `strict` estiver definido como `true`, o servidor gerará um erro para qualquer comando que não faça parte da versão da API especificada. Se nenhum valor for fornecido, o valor padrão do servidor (`false`) será usado.
`deprecationErrors`
  Se o parâmetro `deprecationErrors` estiver definido como `true`, o servidor gerará um erro ao usar um comando que está obsoleto na versão da API especificada. Se nenhum valor for fornecido, o valor padrão do servidor (`false`) será usado.

## Índice

- MongoDB\Driver\ServerApi::bsonSerialize — Retorna um objeto para serialização BSON
- MongoDB\Driver\ServerApi::__construct — Cria uma nova instância de ServerApi

# A classe MongoDB\Driver\WriteConcern

(mongodb >=1.0.0)

## Introdução

MongoDB\Driver\WriteConcern descreve o nível de confirmação solicitado do MongoDB para operações de gravação em um `mongod` independente ou em conjuntos de réplicas ou em clusters fragmentados. Em clusters fragmentados, as instâncias `mongos` passarão a preocupação de gravação para os fragmentos.

## Resumo da classe

final class MongoDB\Driver\WriteConcern implements MongoDB\BSON\Serializable, Serializable {
/* Constantes */
const string MAJORITY = "majority";
/* Propriedades */
public readonly string|int|null $w;
public readonly ?bool $j;
public readonly int $wtimeout;
/* Métodos */
final public function bsonSerialize(): stdClass
final public function __construct(string|int `$w`, ?int `$wtimeout` = `null`, ?bool `$journal` = `null`)
final public function getJournal(): ?bool
final public function getW(): string|int|null
final public function getWtimeout(): int
final public function isDefault(): bool
}

## Propriedades

w
  O valor de garantia de gravação (número inteiro de nós, a string `"majority"`, ou um nome de tag de garantia de gravação personalizado), ou `null` se não estiver definido.
j
  Se as operações de escrita devem ser confirmadas no diário antes de serem reconhecidas, ou `null` se não especificado.
wtimeout
  O tempo limite em milissegundos para aguardar o reconhecimento da solicitação de gravação. Um valor de `0` significa aguardar indefinidamente.

## Constantes predefinidas

`MongoDB\Driver\WriteConcern::MAJORITY`
  Maioria de todos os membros do conjunto; árbitros, membros sem direito a voto, membros passivos, membros ocultos e membros atrasados ​​estão todos incluídos na definição de preocupação de escrita majoritária.

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.3.0 | Adicionadas propriedades públicas readonly.
PECL mongodb 1.7.0 | Implementa Serializable.
PECL mongodb 1.2.0 | Implementa MongoDB\BSON\Serializable.

# MongoDB\Driver\WriteConcern::bsonSerialize

(mongodb >=1.2.0)

MongoDB\Driver\WriteConcern::bsonSerialize — Retorna um objeto para serialização BSON

### Descrição

final public function MongoDB\Driver\WriteConcern::bsonSerialize(): stdClass

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um objeto para serializar WriteConcern como BSON.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 MongoDB\Driver\WriteConcern::bsonSerialize() com preocupação de gravação "majority"

    <?php

    $wc = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY);
    var_dump($wc->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($wc)->toRelaxedExtendedJSON();

    ?>

O exemplo acima produzirá algo semelhante a:

    object(stdClass)#2 (1) {
      ["w"]=>
      string(8) "majority"
    }

    { "w" : "majority" }

Exemplo #2 MongoDB\Driver\WriteConcern::bsonSerialize() com "wtimeout" e "journal"

    <?php

    $wc = new MongoDB\Driver\WriteConcern(2, 1000, true);
    var_dump($wc->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($wc)->toRelaxedExtendedJSON();

    ?>

O exemplo acima produzirá algo semelhante a:

    object(stdClass)#2 (3) {
      ["w"]=>
      int(2)
      ["j"]=>
      bool(true)
      ["wtimeout"]=>
      int(1000)
    }

    { "w" : 2, "j" : true, "wtimeout" : 1000 }

### Veja Também

- MongoDB\BSON\Serializable::bsonSerialize() - Fornece um array ou documento para serializar como BSON
- » Referência de Preocupação de Gravação

# MongoDB\Driver\WriteConcern::__construct

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::__construct — Cria uma nova preocupação de gravação

### Descrição

final public function MongoDB\Driver\WriteConcern::__construct(string|int `$w`, ?int `$wtimeout` = `null`, ?bool `$journal` = `null`)

Constrói um novo MongoDB\Driver\WriteConcern, que é um objeto de valor imutável.

### Parâmetros

`w`

  Preocupação de gravação
  Valor | Descrição
  --- | ---
  1 | Solicita o reconhecimento de que a operação de gravação foi propagada para o `mongod` independente ou para o primário em um conjunto de réplicas. Esta é a preocupação de gravação padrão do MongoDB.
  0 | Não solicita confirmação da operação de gravação. No entanto, isso pode retornar informações sobre exceções de soquete e erros de rede para a aplicação.
  <inteiro maior que 1> | Números maiores que 1 são válidos apenas para conjuntos de réplicas solicitarem confirmação de um número especificado de membros, incluindo o primário.
  `MongoDB\Driver\WriteConcern::MAJORITY` | Solicita o reconhecimento de que as operações de gravação foram propagadas para a maioria dos nós de votação, incluindo o primário, e foram gravadas no diário em disco para esses nós. Antes do MongoDB 3.0, isso se referia à maioria dos membros do conjunto de réplicas (não apenas aos nós de votação).
  string | Um valor de string é interpretado como um conjunto de tags. Solicita a confirmação de que as operações de gravação foram propagadas para um membro do conjunto de réplicas com a etiqueta especificada.

`wtimeout`
  Quanto tempo esperar (em milissegundos) pelos secundários antes de falhar. `wtimeout` faz com que as operações de gravação retornem com um erro (WriteConcernError) após o limite especificado, mesmo que a preocupação de gravação necessária acabe sendo bem-sucedida. Quando essas operações de gravação retornam, o MongoDB não desfaz as modificações de dados bem-sucedidas realizadas antes que a preocupação de gravação excedesse o limite de tempo `wtimeout`. Se especificado, `wtimeout` deve ser um número inteiro de 64 bits, com sinal, maior ou igual a zero.

  Tempo limite de preocupação de gravação
  Valor | Descrição
  --- | ---
  0 | Bloqueia indefinidamente. Este é o padrão.
  <inteiro maior que 0> | Milissegundos para esperar até retornar.

`journal`
  Espera até que o mongod aplique a gravação no diário.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma MongoDB\Driver\Exception\InvalidArgumentException se `w` for inválido ou `wtimeout` for negativo ou maior que os limites de um número inteiro de 32 bits com sinal.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.7.0 | O parâmetro `wTimeout` agora aceita valores de 64 bits.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\WriteConcern::__construct()

    <?php

    /* Solicita confirmação de gravação da maioria dos nós do conjunto de réplicas */
    $wc = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY, 500);

    /* Solicita confirmação de gravação de um nó configurado com a etiqueta "MultipleDC" */
    $wc = new MongoDB\Driver\WriteConcern("MultipleDC", 500);

    ?>

### Veja Também

- » Referência de Preocupação de Gravação

# MongoDB\Driver\WriteConcern::getJournal

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::getJournal — Retorna a opção "journal" do WriteConcern

### Descrição

final public function MongoDB\Driver\WriteConcern::getJournal(): ?bool

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a opção "journal" do WriteConcern.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\WriteConcern::getJournal()

    <?php

    $wc = new MongoDB\Driver\WriteConcern(1);
    var_dump($wc->getJournal());

    $wc = new MongoDB\Driver\WriteConcern(1, 0, true);
    var_dump($wc->getJournal());

    $wc = new MongoDB\Driver\WriteConcern(1, 0, false);
    var_dump($wc->getJournal());

    ?>

O exemplo acima produzirá:

    NULL
    bool(true)
    bool(false)

### Veja Também

- » Referência de Preocupação de Gravação

# MongoDB\Driver\WriteConcern::getW

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::getW — Retorna a opção "w" do WriteConcern

### Descrição

final public function MongoDB\Driver\WriteConcern::getW(): string|int|null

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a opção "w" do WriteConcern.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\WriteConcern::getW()

    <?php

    $wc = new MongoDB\Driver\WriteConcern(1);
    var_dump($wc->getW());

    $wc = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY);
    var_dump($wc->getW());

    ?>

O exemplo acima produzirá:

    int(1)
    string(8) "majority"

### Veja Também

- » Referência de Preocupação de Gravação

# MongoDB\Driver\WriteConcern::getWtimeout

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::getWtimeout — Retorna a opção "wtimeout" do WriteConcern

### Descrição

final public function MongoDB\Driver\WriteConcern::getWtimeout(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a opção "wtimeout" do WriteConcern.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.7.0 | Em sistemas de 32 bits, este método sempre truncará o valor `wTimeout` se exceder o intervalo de 32 bits. Nesse caso, um alerta será emitido.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\WriteConcern::getWtimeout()

    <?php

    $wc = new MongoDB\Driver\WriteConcern(1);
    var_dump($wc->getWtimeout());

    $wc = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY, 3000);
    var_dump($wc->getWtimeout());

    ?>

O exemplo acima produzirá:

    int(0)
    int(3000)

### Veja Também

- » Referência de Preocupação de Gravação

# MongoDB\Driver\WriteConcern::isDefault

(mongodb >=1.3.0)

MongoDB\Driver\WriteConcern::isDefault — Verifica se esta é a preocupação de gravação padrão

### Descrição

final public function MongoDB\Driver\WriteConcern::isDefault(): bool

Retorna se esta é a preocupação de gravação padrão (ou seja, nenhuma opção é especificada). Este método destina-se principalmente a ser usado em conjunto com MongoDB\Driver\Manager::getWriteConcern() para determinar se o gerenciador foi construído sem nenhuma opção de preocupação de gravação.

O driver não incluirá uma preocupação de gravação padrão em suas operações de gravação (por exemplo, MongoDB\Driver\Manager::executeBulkWrite()) para permitir que o servidor aplique seu próprio padrão, que pode ter sido » modificado. Bibliotecas que acessam a preocupação de gravação do gerenciador para incluí-la em seus próprios comandos de gravação devem usar esse método para garantir que as preocupações de gravação padrão não sejam definidas.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se esta for a preocupação de gravação padrão ou `false` caso contrário.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\WriteConcern::isDefault()

    <?php

    $wc = new MongoDB\Driver\WriteConcern(1);
    var_dump($wc->isDefault());

    $manager = new MongoDB\Driver\Manager('mongodb://127.0.0.1/?w=majority');
    $wc = $manager->getWriteConcern();
    var_dump($wc->isDefault());

    $manager = new MongoDB\Driver\Manager('mongodb://127.0.0.1/');
    $wc = $manager->getWriteConcern();
    var_dump($wc->isDefault());

    ?>

O exemplo acima produzirá:

    bool(false)
    bool(false)
    bool(true)

### Veja Também

- MongoDB\Driver\Manager::getWriteConcern() - Retorna a procupação de gravação para o gerenciador
- » Modificar preocupação de gravação padrão no manual do MongoDB
- » Referência de Preocupação de Gravação

## Índice

- MongoDB\Driver\WriteConcern::bsonSerialize — Retorna um objeto para serialização BSON
- MongoDB\Driver\WriteConcern::__construct — Cria uma nova preocupação de gravação
- MongoDB\Driver\WriteConcern::getJournal — Retorna a opção "journal" do WriteConcern
- MongoDB\Driver\WriteConcern::getW — Retorna a opção "w" do WriteConcern
- MongoDB\Driver\WriteConcern::getWtimeout — Retorna a opção "wtimeout" do WriteConcern
- MongoDB\Driver\WriteConcern::isDefault — Verifica se esta é a preocupação de gravação padrão

# A classe MongoDB\Driver\ReadPreference

(mongodb >=1.0.0)

## Introdução

## Resumo da classe

final class MongoDB\Driver\ReadPreference implements MongoDB\BSON\Serializable, Serializable {
/* Propriedades */
public readonly string $mode;
public readonly ?array $tags;
public readonly int $maxStalenessSeconds;
public readonly ?object $hedge;
/* Constantes */
const string PRIMARY = primary;
const string PRIMARY_PREFERRED = primaryPreferred;
const string SECONDARY = secondary;
const string SECONDARY_PREFERRED = secondaryPreferred;
const string NEAREST = nearest;
const int NO_MAX_STALENESS = -1;
const int SMALLEST_MAX_STALENESS_SECONDS = 90;
/* Métodos */
final public function bsonSerialize(): stdClass
final public function __construct(string `$mode`, ?array `$tagSets` = `null`, ?array `$options` = `null`)
final public function getHedge(): ?object
final public function getMaxStalenessSeconds(): int
final public function getMode(): int
final public function getModeString(): string
final public function getTagSets(): array
}

## Propriedades

mode
  O modo de preferência de leitura como uma string (por exemplo, `"primary"`, `"secondary"`).
tags
  A lista de conjuntos de tags usada pela preferência de leitura, ou `null` se nenhum conjunto de tags foi especificado.
maxStalenessSeconds
  O tempo máximo de defasagem em segundos para leituras, ou `MongoDB\Driver\ReadPreference::NO_MAX_STALENESS` se nenhum tempo máximo de defasagem foi especificado.
hedge
  Um documento que especifica as opções de hedge para a preferência de leitura, ou `null` se nenhuma opção de hedge foi especificada.
  Aviso

  Esta propriedade foi descontinuada, pois as leituras protegidas estão obsoletas no MongoDB 8.0.

## Constantes predefinidas

`MongoDB\Driver\ReadPreference::PRIMARY`
  Todas as operações são lidas do conjunto de réplicas primário atual. Esta é a preferência de leitura padrão do MongoDB.
`MongoDB\Driver\ReadPreference::PRIMARY_PREFERRED`
  Na maioria das situações, as operações são lidas a partir dos membros primários, mas se não estiver disponível, as operações são lidas a partir dos membros secundários.
`MongoDB\Driver\ReadPreference::SECONDARY`
  Todas as operações são lidas nos membros secundários do conjunto de réplicas.
`MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED`
  Na maioria das situações, as operações são lidas a partir de membros secundários, mas se nenhum membro secundário estiver disponível, as operações são lidas a partir do primário.
`MongoDB\Driver\ReadPreference::NEAREST`
  Operações lidas do membro do conjunto de réplicas com a menor latência de rede, independentemente do tipo do membro.
`MongoDB\Driver\ReadPreference::NO_MAX_STALENESS`
  O valor padrão para a opção `"maxStalenessSeconds"` é não especificar nenhum limite de inatividade máxima, o que significa que o driver não considerará o atraso de um secundário ao escolher para onde direcionar uma operação de leitura.
`MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS`
  O valor mínimo para a opção `"maxStalenessSeconds"` é 90 segundos. O driver estima a inatividade dos secundários verificando periodicamente a data de gravação mais recente de cada membro do conjunto de réplicas. Como essas verificações são pouco frequentes, a estimativa de inatividade é grosseira. Assim, o driver não pode impor um valor máximo de inatividade inferior a 90 segundos.

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.3.0 | Adicionadas propriedades públicas readonly.
PECL mongodb 2.0.0 | Removidas as constantes `MongoDB\Driver\ReadPreference::RP_PRIMARY`, `MongoDB\Driver\ReadPreference::RP_PRIMARY_PREFERRED`, `MongoDB\Driver\ReadPreference::RP_SECONDARY`, `MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED` e `MongoDB\Driver\ReadPreference::RP_NEAREST`. O método getMode() também foi removido.
PECL mongodb 1.20.0 | As constantes `MongoDB\Driver\ReadPreference::RP_PRIMARY`, `MongoDB\Driver\ReadPreference::RP_PRIMARY_PREFERRED`, `MongoDB\Driver\ReadPreference::RP_SECONDARY`, `MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED`, e `MongoDB\Driver\ReadPreference::RP_NEAREST` foram descontinuadas.
PECL mongodb 1.7.0 | As constantes `MongoDB\Driver\ReadPreference::PRIMARY`, `MongoDB\Driver\ReadPreference::PRIMARY_PREFERRED`, `MongoDB\Driver\ReadPreference::SECONDARY`, `MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED`, e `MongoDB\Driver\ReadPreference::NEAREST` foram adicionadas. Implementa Serializable.
PECL mongodb 1.2.0 | As constantes `MongoDB\Driver\ReadPreference::NO_MAX_STALENESS` e `MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS` foram adicionadas. Implementa MongoDB\BSON\Serializable.

# MongoDB\Driver\ReadPreference::bsonSerialize

(mongodb >=1.2.0)

MongoDB\Driver\ReadPreference::bsonSerialize — Retorna um objeto para serialização BSON

### Descrição

final public function MongoDB\Driver\ReadPreference::bsonSerialize(): stdClass

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um objeto para serializar ReadPreference como BSON.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 MongoDB\Driver\ReadPreference::bsonSerialize() com preferência de leitura primária

    <?php

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY);
    var_dump($rp->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($rp)->toRelaxedExtendedJSON();

    ?>

O exemplo acima produzirá algo semelhante a:

    object(stdClass)#2 (1) {
      ["mode"]=>
      string(7) "primary"
    }

    { "mode" : "primary" }

Exemplo #2 MongoDB\Driver\ReadPreference::bsonSerialize() com preferência de leitura secundária e conjuntos de tags

    <?php

    $rp = new MongoDB\Driver\ReadPreference(
        MongoDB\Driver\ReadPreference::SECONDARY,
        [
            ['dc' => 'ny'],
            ['dc' => 'sf', 'use' => 'reporting'],
            []
        ]
    );
    var_dump($rp->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($rp)->toRelaxedExtendedJSON();

    ?>

O exemplo acima produzirá algo semelhante a:

    object(stdClass)#2 (2) {
      ["mode"]=>
      string(9) "secondary"
      ["tags"]=>
      array(3) {
        [0]=>
        object(stdClass)#1 (1) {
          ["dc"]=>
          string(2) "ny"
        }
        [1]=>
        object(stdClass)#5 (2) {
          ["dc"]=>
          string(2) "sf"
          ["use"]=>
          string(9) "reporting"
        }
        [2]=>
        object(stdClass)#4 (0) {
        }
      }
    }

    { "mode" : "secondary", "tags" : [ { "dc" : "ny" }, { "dc" : "sf", "use" : "reporting" }, {  } ] }

Exemplo #3 MongoDB\Driver\ReadPreference::bsonSerialize() com preferência de leitura secundária e ociosidade máxima

    <?php

    $rp = new MongoDB\Driver\ReadPreference(
        MongoDB\Driver\ReadPreference::SECONDARY,
        null,
        ['maxStalenessSeconds' => 120]
    );
    var_dump($rp->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($rp)->toRelaxedExtendedJSON();

    ?>

O exemplo acima produzirá algo semelhante a:

    object(stdClass)#2 (2) {
      ["mode"]=>
      string(9) "secondary"
      ["maxStalenessSeconds"]=>
      int(120)
    }

    { "mode" : "secondary", "maxStalenessSeconds" : 120 }

### Veja Também

- MongoDB\BSON\Serializable::bsonSerialize() - Fornece um array ou documento para serializar como BSON
- » Referência de Preferência de Leitura

# MongoDB\Driver\ReadPreference::__construct

(mongodb >=1.0.0)

MongoDB\Driver\ReadPreference::__construct — Cria uma nova preferência de leitura

### Descrição

final public function MongoDB\Driver\ReadPreference::__construct(string `$mode`, ?array `$tagSets` = `null`, ?array `$options` = `null`)

Constrói um novo MongoDB\Driver\ReadPreference, que é um objeto de valor imutável.

### Parâmetros

`mode`

  Modo de preferência de leitura
  Valor | Descrição
  --- | ---
  `"primary"` | Todas as operações são lidas do conjunto de réplicas primário atual. Esta é a preferência de leitura padrão do MongoDB.
  `"primaryPreferred"` | Na maioria das situações, as operações são lidas a partir dos membros primários, mas se não estiver disponível, as operações são lidas a partir dos membros secundários.
  `"secondary"` | Todas as operações são lidas nos membros secundários do conjunto de réplicas.
  `"secondaryPreferred"` | Na maioria das situações, as operações são lidas a partir de membros secundários, mas se nenhum membro secundário estiver disponível, as operações são lidas a partir do primário.
  `"nearest"` | Operações lidas do membro do conjunto de réplicas com a menor latência de rede, independentemente do tipo do membro.

`tagSets`
  Os conjuntos de tags permitem direcionar operações de leitura para membros específicos de um conjunto de réplicas. Este parâmetro deve ser um array de arrays associativos, cada um contendo zero ou mais pares chave/valor. Ao selecionar um servidor para uma operação de leitura, o driver tenta selecionar um nó que tenha todas as tags em um conjunto (ou seja, o array associativo de pares chave/valor). Se a seleção falhar, o driver tentará conjuntos subsequentes. Um conjunto de tags vazio (`array()`) corresponderá a qualquer nó e pode ser usado como substituto. Tags não são compatíveis com o modo `"primary"` e, em geral, só se aplicam ao selecionar um membro secundário de um conjunto para uma operação de leitura. No entanto, o modo `"nearest"`, quando combinado com um conjunto de tags, seleciona o membro correspondente com a menor latência de rede. Este membro pode ser um primário ou um secundário.
`options`

  Opções
  Opção | Tipo | Descrição
  --- | --- | ---
  hedge | object|array | Especifica se devem ser usadas » leituras protegidas, que são suportadas pelo MongoDB 4.4+ para consultas fragmentadas. As leituras protegidas do servidor estão disponíveis para todas as preferências de leitura não primárias e são habilitadas por padrão ao usar o modo `"nearest"`. Esta opção permite ativar explicitamente leituras protegidas pelo servidor para preferências de leitura não primárias, especificando `['enabled' => true]` ou desabilitando explicitamente leituras protegidas pelo servidor para a preferência de leitura `"nearest"` especificando `['enabled' => false]`.
  maxStalenessSeconds | int | Especifica um atraso máximo de replicação, ou "inatividade", para leituras de secundários. Quando a inatividade estimada de um secundário excede esse valor, o driver deixa de usá-lo para operações de leitura. Se especificada, a inatividade máxima deve ser um número inteiro de 32 bits com sinal, maior ou igual a `MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS`. O padrão é `MongoDB\Driver\ReadPreference::NO_MAX_STALENESS`, o que significa que o driver não considerará o atraso de um secundário ao escolher para onde direcionar uma operação de leitura. Esta opção não é compatível com o modo `"primary"`. A especificação de uma inatividade máxima também exige que todas as instâncias do MongoDB na implantação usem o MongoDB 3.4+. Uma exceção será lançada no momento da execução se alguma instância do MongoDB na implantação for de uma versão de servidor mais antiga.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma MongoDB\Driver\Exception\InvalidArgumentException se `mode` for inválido.
- Lança uma MongoDB\Driver\Exception\InvalidArgumentException se `tagSets` for fornecido para uma preferência de leitura primária ou estiver malformado (ou seja, não é uma array de zero ou mais documentos).
- Lança uma MongoDB\Driver\Exception\InvalidArgumentException se a opção `"maxStalenessSeconds"` for fornecida para uma preferência de leitura primária ou estiver fora do intervalo.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | PAssar um int para o argumento `mode` não é mais suportado.
PECL mongodb 1.20.0 | Passar um int no parâmetro `mode` foi DESCONTINUADO.
PECL mongodb 1.8.0 | Adcionada a opção `"hedge"`.
PECL mongodb 1.3.0 | O parâmetro `mode` agora aceita um valor de string, que é consistente com a opção URI `"readPreference"` para MongoDB\Driver\Manager::__construct().
PECL mongodb 1.2.0 | Adicionado um terceiro parâmetro `options`, que suporta a opção `"maxStalenessSeconds"`.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\ReadPreference::__construct()

    <?php

    /* Prefere um nó secundário, mas volta para um nó primário. */
    var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED));

    /* Prefere um nó na central de dados de Nova Iorque com a latência mais baixa. */
    var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::NEAREST, [['dc' => 'ny']]));

    /* Exige um nó secundário cujo atraso de replicação esteja dentro de dois minutos do primário */
    var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, ['maxStalenessSeconds' => 120]));

    /* Habilita explicitamente leituras protegidas pelo servidor */
    var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, ['hedge' => ['enabled' => true]]));

    ?>

O exemplo acima produzirá:

    object(MongoDB\Driver\ReadPreference)#1 (1) {
      ["mode"]=>
      string(18) "secondaryPreferred"
    }
    object(MongoDB\Driver\ReadPreference)#1 (2) {
      ["mode"]=>
      string(7) "nearest"
      ["tags"]=>
      array(1) {
        [0]=>
        object(stdClass)#2 (1) {
          ["dc"]=>
          string(2) "ny"
        }
      }
    }
    object(MongoDB\Driver\ReadPreference)#1 (2) {
      ["mode"]=>
      string(9) "secondary"
      ["maxStalenessSeconds"]=>
      int(120)
    }
    object(MongoDB\Driver\ReadPreference)#1 (2) {
      ["mode"]=>
      string(9) "secondary"
      ["hedge"]=>
      object(stdClass)#1 (1) {
        ["enabled"]=>
        bool(true)
      }
    }

### Veja Também

- » Referência de Preferência de Leitura

# MongoDB\Driver\ReadPreference::getHedge

(mongodb >=1.8.0)

MongoDB\Driver\ReadPreference::getHedge — Retorna a opção "hedge" do ReadPreference

### Descrição

final public function MongoDB\Driver\ReadPreference::getHedge(): ?object

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a opção "hedge" do ReadPreference.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- » Referência de Preferência de Leitura

# MongoDB\Driver\ReadPreference::getMaxStalenessSeconds

(mongodb >=1.2.0)

MongoDB\Driver\ReadPreference::getMaxStalenessSeconds — Retorna a opção "maxStalenessSeconds" do ReadPreference

### Descrição

final public function MongoDB\Driver\ReadPreference::getMaxStalenessSeconds(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a opção "maxStalenessSeconds" do ReadPreference. Se nenhuma inatividade máxima tiver sido especificada, `MongoDB\Driver\ReadPreference::NO_MAX_STALENESS` será retornada.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\ReadPreference::getMaxStalenessSeconds()

    <?php

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY);
    var_dump($rp->getMaxStalenessSeconds());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, [
        'maxStalenessSeconds' => MongoDB\Driver\ReadPreference::NO_MAX_STALENESS,
    ]);
    var_dump($rp->getMaxStalenessSeconds());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, [
        'maxStalenessSeconds' => MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS,
    ]);
    var_dump($rp->getMaxStalenessSeconds());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, [
        'maxStalenessSeconds' => 1000,
    ]);
    var_dump($rp->getMaxStalenessSeconds());

    ?>

O exemplo acima produzirá:

    int(-1)
    int(-1)
    int(90)
    int(1000)

### Veja Também

- » Referência de Preferência de Leitura

# MongoDB\Driver\ReadPreference::getMode

(mongodb >=1.0.0)

MongoDB\Driver\ReadPreference::getMode — Retorna a opção "mode" do ReadPreference

Aviso

Esta função tornou-se PRETERIDA a partir da versão de extensão 1.20.0 e foi removida na 2.0. As aplicações devem usar MongoDB\Driver\ReadPreference::getModeString() em seu lugar.

### Descrição

final public function MongoDB\Driver\ReadPreference::getMode(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a opção "mode" do ReadPreference.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Este método foi removido.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\ReadPreference::getMode()

    <?php

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY);
    var_dump($rp->getMode());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY_PREFERRED);
    var_dump($rp->getMode());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY);
    var_dump($rp->getMode());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED);
    var_dump($rp->getMode());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::NEAREST);
    var_dump($rp->getMode());

    ?>

O exemplo acima produzirá:

    int(1)
    int(5)
    int(2)
    int(6)
    int(10)

### Veja Também

- MongoDB\Driver\ReadPreference::getModeString() - Retorna a opção "mode" do ReadPreference
- » Referência de Preferência de Leitura

# MongoDB\Driver\ReadPreference::getModeString

(mongodb >=1.7.0)

MongoDB\Driver\ReadPreference::getModeString — Retorna a opção "mode" do ReadPreference

### Descrição

final public function MongoDB\Driver\ReadPreference::getModeString(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a opção "mode" do ReadPreference como uma string.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\ReadPreference::getModeString()

    <?php

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY);
    var_dump($rp->getModeString());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY_PREFERRED);
    var_dump($rp->getModeString());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY);
    var_dump($rp->getModeString());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED);
    var_dump($rp->getModeString());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::NEAREST);
    var_dump($rp->getModeString());

    ?>

O exemplo acima produzirá:

    string(7) "primary"
    string(16) "primaryPreferred"
    string(9) "secondary"
    string(18) "secondaryPreferred"
    string(7) "nearest"

### Veja Também

- MongoDB\Driver\ReadPreference::getMode() - Retorna a opção "mode" do ReadPreference
- » Referência de Preferência de Leitura

# MongoDB\Driver\ReadPreference::getTagSets

(mongodb >=1.0.0)

MongoDB\Driver\ReadPreference::getTagSets — Retorna a opção "tagSets" do ReadPreference

### Descrição

final public function MongoDB\Driver\ReadPreference::getTagSets(): array

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a opção "tagSets" do ReadPreference.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\ReadPreference::getTagSets()

    <?php

    $mode = MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED;

    /* Nulo ou array vazio denotam nenhuma preferência de conjunto de tags. */
    $rp = new MongoDB\Driver\ReadPreference($mode, null);
    var_dump($rp->getTagSets());

    $rp = new MongoDB\Driver\ReadPreference($mode, []);
    var_dump($rp->getTagSets());

    /* Prefere um nó em Nova Iorque, mas volta para qualquer nó disponível. */
    $rp = new MongoDB\Driver\ReadPreference($mode, [['dc' => 'ny']]);
    var_dump($rp->getTagSets());

    /* Prefere um nó em Nova Iorque, seguido por um nó em São Francisco que seja
       rotulado para uso de relatórios e, finalmente, retorna a qualquer nó disponível. */
    $rp = new MongoDB\Driver\ReadPreference($mode, [
      ['dc' => 'ny'],
      ['dc' => 'sf', 'use' => 'reporting'],
      [],
    ]);
    var_dump($rp->getTagSets());

    ?>

O exemplo acima produzirá:

    array(0) {
    }
    array(0) {
    }
    array(2) {
      [0]=>
      array(1) {
        ["dc"]=>
        string(2) "ny"
      }
      [1]=>
      array(0) {
      }
    }
    array(3) {
      [0]=>
      array(1) {
        ["dc"]=>
        string(2) "ny"
      }
      [1]=>
      array(2) {
        ["dc"]=>
        string(2) "sf"
        ["use"]=>
        string(9) "reporting"
      }
      [2]=>
      array(0) {
      }
    }

### Veja Também

- » Referência de Preferência de Leitura

## Índice

- MongoDB\Driver\ReadPreference::bsonSerialize — Retorna um objeto para serialização BSON
- MongoDB\Driver\ReadPreference::__construct — Cria uma nova preferência de leitura
- MongoDB\Driver\ReadPreference::getHedge — Retorna a opção "hedge" do ReadPreference
- MongoDB\Driver\ReadPreference::getMaxStalenessSeconds — Retorna a opção "maxStalenessSeconds" do ReadPreference
- MongoDB\Driver\ReadPreference::getMode — Retorna a opção "mode" do ReadPreference
- MongoDB\Driver\ReadPreference::getModeString — Retorna a opção "mode" do ReadPreference
- MongoDB\Driver\ReadPreference::getTagSets — Retorna a opção "tagSets" do ReadPreference

# A classe MongoDB\Driver\ReadConcern

(mongodb >=1.1.0)

## Introdução

A classe MongoDB\Driver\ReadConcern controla o nível de isolamento para operações de leitura em conjuntos de réplicas e fragmentos de conjuntos de réplicas. Esta opção requer o MongoDB 3.2 ou posterior.

## Resumo da classe

final class MongoDB\Driver\ReadConcern implements MongoDB\BSON\Serializable, Serializable {
/* Propriedades */
public readonly ?string $level;
/* Constantes */
const string AVAILABLE = "available";
const string LINEARIZABLE = "linearizable";
const string LOCAL = "local";
const string MAJORITY = "majority";
const string SNAPSHOT = "snapshot";
/* Métodos */
final public function bsonSerialize(): stdClass
final public function __construct(?string `$level` = `null`)
final public function getLevel(): ?string
final public function isDefault(): bool
}

## Propriedades

level
  O nível de preocupação de leitura. `null` se nenhum nível foi especificado.

## Constantes predefinidas

`MongoDB\Driver\ReadConcern::AVAILABLE`
  Padrão para leitura de secundários quando `afterClusterTime` e `level` não são especificados. A consulta retorna os dados mais recentes da instância. Não fornece nenhuma garantia de que os dados foram gravados na maioria dos membros do conjunto de réplicas (ou seja, podem ser revertidos). Para coleções não fragmentadas (incluindo coleções em uma implantação autônoma ou uma implantação de conjunto de réplicas), as preocupações de leitura `"local"` e `"available"` se comportam de forma idêntica. Para um cluster fragmentado, a preocupação de leitura `"available"` fornece maior tolerância para partições, uma vez que não espera por garantias de consistência. No entanto, uma consulta com preocupação de leitura `"available"` pode retornar documentos órfãos se o fragmento estiver passando por migrações de blocos desde a preocupação de leitura `"available"`, ao contrário da preocupação de leitura `"local"`, que não entra em contato com o servidor primário do fragmento nem com os servidores de configuração para obter metadados atualizados.
`MongoDB\Driver\ReadConcern::LINEARIZABLE`
  A consulta retorna dados que refletem todas as gravações bem-sucedidas emitidas com uma preocupação de gravação de `"majority"` e reconhecida antes do início da operação de leitura. Para conjuntos de réplicas executados com `writeConcernMajorityJournalDefault` igual a `true`, a preocupação de leitura linearizável retorna dados que nunca serão revertidos. Com `writeConcernMajorityJournalDefault` igual a `false`, o MongoDB não esperará que as gravações `w: "majority"` sejam duráveis ​​antes de reconhecê-las. Como tal, as operações de gravação `"majority"` poderiam possivelmente ser revertidas no caso de perda de um membro do conjunto de réplicas. Pode-se especificar a preocupação de leitura linearizável apenas para operações de leitura no primário. As garantias de preocupação de leitura linearizáveis ​​só se aplicam se as operações de leitura especificarem um filtro de consulta que identifique exclusivamente um único documento.
  Dica

  Sempre use `maxTimeMS` com preocupação de leitura linearizável caso a maioria dos membros que contêm dados estejam indisponíveis. `maxTimeMS` garante que a operação não seja bloqueada indefinidamente e, em vez disso, garante que a operação retorne um erro se a preocupação de leitura não puder ser atendida.

  A preocupação de leitura linearizável requer MongoDB 3.4.
`MongoDB\Driver\ReadConcern::LOCAL`
  Padrão para leituras em relação ao primário se `level` não for especificado e para leituras em relação a secundários se `level` não for especificado, mas `afterClusterTime` for especificado. A consulta retorna os dados mais recentes da instância. Não fornece nenhuma garantia de que os dados foram gravados na maioria dos membros do conjunto de réplicas (ou seja, podem ser revertidos).
`MongoDB\Driver\ReadConcern::MAJORITY`
  A consulta retorna os dados mais recentes da instância reconhecidos como tendo sido gravados para a maioria dos membros do conjunto de réplicas. Para usar o nível de preocupação de leitura de `"majority"`, os conjuntos de réplicas devem usar o mecanismo de armazenamento WiredTiger e o protocolo de escolha versão 1.
`MongoDB\Driver\ReadConcern::SNAPSHOT`
  A preocupação de leitura `"snapshot"` está disponível para transações multi-documentos e, a partir do MongoDB 5.0, certas operações de leitura fora das transações multi-documentos. Se a transação não fizer parte de uma sessão causalmente consistente, após a confirmação da transação com preocupação de gravação `"majority"`, é garantido que as operações de transação tenham lido um instantâneo de dados confirmados pela maioria. Se a transação fizer parte de uma sessão causalmente consistente, após a confirmação da transação com preocupação de gravação `"majority"`, é garantido que as operações de transação tenham lido um instantâneo de dados confirmados pela maioria que fornece consistência causal com a operação imediatamente anterior ao início da transação. Fora das transações multi-documentos, a preocupação de leitura `"snapshot"` está disponíveis nos primários e secundários para as seguintes operações de leitura: `find`, `aggregate` e `distinct` (em coleções não fragmentadas). Todos os outros comandos de leitura proíbem `"snapshot"`.

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.3.0 | Adicionadas propriedades públicas readonly.
PECL mongodb 1.11.0 | Adicionada a constante `MongoDB\Driver\ReadConcern::SNAPSHOT`.
PECL mongodb 1.7.0 | Implementa Serializable.
PECL mongodb 1.4.0 | Adicionada a constante `MongoDB\Driver\ReadConcern::AVAILABLE`.
PECL mongodb 1.2.0 | Adicionada a constante `MongoDB\Driver\ReadConcern::LINEARIZABLE`. Implementa MongoDB\BSON\Serializable.

## Veja Também

- » Referência de Preocupação de Leitura

# MongoDB\Driver\ReadConcern::bsonSerialize

(mongodb >=1.2.0)

MongoDB\Driver\ReadConcern::bsonSerialize — Retorna um objeto para serialização BSON

### Descrição

final public function MongoDB\Driver\ReadConcern::bsonSerialize(): stdClass

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um objeto para serializar o ReadConcern como BSON.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 MongoDB\Driver\ReadConcern::bsonSerialize() com preocupação de leitura vazia

    <?php

    $rc = new MongoDB\Driver\ReadConcern;
    var_dump($rc->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($rc)->toRelaxedExtendedJSON();

    ?>

O exemplo acima produzirá algo semelhante a:

    object(stdClass)#2 (0) {
    }

    { }

Exemplo #2 MongoDB\Driver\ReadConcern::bsonSerialize() com preocupação de leitura local

    <?php

    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::LOCAL);
    var_dump($rc->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($rc)->toRelaxedExtendedJSON();

    ?>

O exemplo acima produzirá algo semelhante a:

    object(stdClass)#2 (1) {
      ["level"]=>
      string(5) "local"
    }

    { "level" : "local" }

### Veja Também

- MongoDB\BSON\Serializable::bsonSerialize() - Fornece um array ou documento para serializar como BSON
- » Referência de Preocupação de Leitura

# MongoDB\Driver\ReadConcern::__construct

(mongodb >=1.0.0)

MongoDB\Driver\ReadConcern::__construct — Cria uma nova preocupação de leitura

### Descrição

final public function MongoDB\Driver\ReadConcern::__construct(?string `$level` = `null`)

Constrói um novo MongoDB\Driver\ReadConcern, que é um objeto de valor imutável.

### Parâmetros

`level`
  O » nível de preocupação de leitura. As constantes de classe podem ser usadas, mas o valor não está limitado a elas.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\ReadConcern::__construct()

    <?php

    /* Nível de isolamento de leitura não especificado (usa o comportamento padrão do servidor) */
    $rc = new MongoDB\Driver\ReadConcern();

    /* Solicitar isolamento de leitura de um único nó do conjunto de réplicas */
    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::LOCAL);

    /* Solicitar isolamento de leitura da maioria dos nós do conjunto de réplicas */
    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::MAJORITY);

    ?>

### Veja Também

- » Referência de Preocupação de Leitura

# MongoDB\Driver\ReadConcern::getLevel

(mongodb >=1.0.0)

MongoDB\Driver\ReadConcern::getLevel — Retorna o nível da preocupação de leitura

### Descrição

final public function MongoDB\Driver\ReadConcern::getLevel(): ?string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a opção "level" do ReadConcern.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\ReadConcern::getLevel()

    <?php

    $rc = new MongoDB\Driver\ReadConcern();
    var_dump($rc->getLevel());

    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::LOCAL);
    var_dump($rc->getLevel());

    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::MAJORITY);
    var_dump($rc->getLevel());

    ?>

O exemplo acima produzirá:

    NULL
    string(5) "local"
    string(8) "majority"

### Veja Também

- » Referência de Preocupação de Leitura

# MongoDB\Driver\ReadConcern::isDefault

(mongodb >=1.3.0)

MongoDB\Driver\ReadConcern::isDefault — Verifica se esta é a preocupação de leitura padrão

### Descrição

final public function MongoDB\Driver\ReadConcern::isDefault(): bool

Retorna se esta é a preocupação de leitura padrão (ou seja, nenhuma opção é especificada). Este método destina-se principalmente a ser usado em conjunto com MongoDB\Driver\Manager::getReadConcern() para determinar se o gerenciador foi construído sem nenhuma opção de preocupação de leitura.

O driver não incluirá uma preocupação de leitura padrão em suas operações de leitura (por exemplo, MongoDB\Driver\Manager::executeQuery()) para permitir que o servidor aplique seu próprio padrão. Bibliotecas que acessam a preocupação de leitura do gerenciador para incluí-la em seus próprios comandos de leitura devem usar esse método para garantir que as preocupações de leitura padrão não sejam definidas.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se esta for a preocupação de leitura padrão ou `false` caso contrário.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\ReadConcern::isDefault()

    <?php

    $rc = new MongoDB\Driver\ReadConcern(null);
    var_dump($rc->isDefault());

    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::MAJORITY);
    var_dump($rc->isDefault());

    $manager = new MongoDB\Driver\Manager('mongodb://127.0.0.1/?readConcernLevel=majority');
    $rc = $manager->getReadConcern();
    var_dump($rc->isDefault());

    $manager = new MongoDB\Driver\Manager('mongodb://127.0.0.1/');
    $rc = $manager->getReadConcern();
    var_dump($rc->isDefault());

    ?>

O exemplo acima produzirá:

    bool(true)
    bool(false)
    bool(false)
    bool(true)

### Veja Também

- MongoDB\Driver\Manager::getReadConcern() - Retorna a preocupação de leitura para o gerenciador
- » Referência de Preocupação de Leitura

## Índice

- MongoDB\Driver\ReadConcern::bsonSerialize — Retorna um objeto para serialização BSON
- MongoDB\Driver\ReadConcern::__construct — Cria uma nova preocupação de leitura
- MongoDB\Driver\ReadConcern::getLevel — Retorna o nível da preocupação de leitura
- MongoDB\Driver\ReadConcern::isDefault — Verifica se esta é a preocupação de leitura padrão

# A classe MongoDB\Driver\Cursor

(mongodb >=1.0.0)

## Introdução

A classe MongoDB\Driver\Cursor encapsula os resultados de um comando ou consulta MongoDB e podem ser retornados por MongoDB\Driver\Manager::executeCommand() ou MongoDB\Driver\Manager::executeQuery(), respectivamente.

## Resumo da classe

final class MongoDB\Driver\Cursor implements MongoDB\Driver\CursorInterface {
/* Métodos */
final private function __construct()
public function current(): array|object|null
final public function getId(): MongoDB\BSON\Int64
final public function getServer(): MongoDB\Driver\Server
final public function isDead(): bool
public function key(): int
public function next(): void
public function rewind(): void
final public function setTypeMap(array `$typemap`): void
final public function toArray(): array
public function valid(): bool
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.9.0 | Implementa Iterator.
PECL mongodb 1.6.0 | Implementa MongoDB\Driver\CursorInterface, que estende Traversable.

## Exemplos

Exemplo #1 Lendo um conjunto de resultados

MongoDB\Driver\Manager::executeCommand() e MongoDB\Driver\Manager::executeQuery() ambos retornam seus resultados como um objeto MongoDB\Driver\Cursor. Este objeto pode ser usado para iterar sobre conjunto de resultados do comando ou consulta.

Como MongoDB\Driver\Cursor implementa a interface Traversable, pode-se simplesmente iterar pelo conjunto de resultados com `foreach`.

    <?php

    $manager = new MongoDB\Driver\Manager();

    /* Insere alguns documentos para que a consulta retorne informação */
    $bulkWrite = new MongoDB\Driver\BulkWrite;
    $bulkWrite->insert(['name' => 'Ceres', 'size' => 946, 'distance' => 2.766]);
    $bulkWrite->insert(['name' => 'Vesta', 'size' => 525, 'distance' => 2.362]);
    $manager->executeBulkWrite("test.asteroids", $bulkWrite);

    /* Consulta todos os itens na coleção */
    $query = new MongoDB\Driver\Query( [] );

    /* Consulta a coleção "asteroids" do banco de dados "test" */
    $cursor = $manager->executeQuery("test.asteroids", $query);

    /* $cursor agora contém um objeto que envolve o conjunto de resultados. Pode-se
     * usar foreach() para iterar por todo o resultado */
    foreach($cursor as $document) {
        print_r($document);
    }

    ?>

O exemplo acima produzirá algo semelhante a:

    stdClass Object
    (
        [_id] => MongoDB\BSON\ObjectId Object
            (
                [oid] => 5a4cff2f122d3321565d8cc2
            )

        [name] => Ceres
        [size] => 946
        [distance] => 2.766
    )
    stdClass Object
    (
        [_id] => MongoDB\BSON\ObjectId Object
            (
                [oid] => 5a4cff2f122d3321565d8cc3
            )

        [name] => Vesta
        [size] => 525
        [distance] => 2.362
    )

Exemplo #2 Lendo um conjunto de resultados com um cursor adaptável

» Cursores adaptáveis são um tipo especial de cursor no MongoDB que permite ao cliente ler alguns resultados e então esperar até que mais documentos fiquem disponíveis. Esses cursores são usado principalmente com » Coleções Limitadas e » Fluxos de Alterações.

Enquanto os cursores normais podem ser iterados com `foreach`, esse método não irá funcionar com cursores adaptáveis. Quando `foreach` é usado com um cursor adaptável, a repetição irá terminar quando alcançar o final do conjunto de resultados inicial. A tentativa de continuar a iteração no cursor com um segundo `foreach` lançaria uma exceção, já que o PHP tentaria retroceder o cursor. De forma similar aos objetos de resultados em outros drivers de bancos de dados, os cursores no MongoDB suportam apenas iteração para a frente, ou seja, eles não podem ser retrocedidos.

Para ler continuamente a partir de um cursor adaptável, o objeto Cursor deve ser encapsulado com um IteratorIterator. Isso permite que a aplicação controle diretamente a iteração do cursor, evite retroceder inadvertidamente o cursor e decida quando esperar por novos resultados ou interromper totalmente a iteração.

Para demonstrar um cursor adaptável em ação, serão utilizados dois scripts: um "produtor" e um "consumidor". O script produtor criará uma nova coleção limitada usando o comando » create e procederá à inserção de um novo documento nessa coleção a cada segundo.

    <?php

    $manager = new MongoDB\Driver\Manager;

    $manager->executeCommand('test', new MongoDB\Driver\Command([
        'create' => 'asteroids',
        'capped' => true,
        'size' => 1048576,
    ]));

    while (true) {
        $bulkWrite = new MongoDB\Driver\BulkWrite;
        $bulkWrite->insert(['createdAt' => new MongoDB\BSON\UTCDateTime]);
        $manager->executeBulkWrite('test.asteroids', $bulkWrite);

        sleep(1);
    }

    ?>

Com o script produtor ainda em execução, um segundo script consumidor pode ser executado para ler os documentos inseridos usando um cursor adaptável, indicado pelas opções `tailable` e `awaitData` para o método MongoDB\Driver\Query::__construct().

    <?php

    $manager = new MongoDB\Driver\Manager;

    $query = new MongoDB\Driver\Query([], [
        'tailable' => true,
        'awaitData' => true,
    ]);

    $cursor = $manager->executeQuery('test.asteroids', $query);

    $iterator = new IteratorIterator($cursor);

    $iterator->rewind();

    while (true) {
        if ($iterator->valid()) {
            $document = $iterator->current();
            printf("Documento consumido criado em: %s\n", $document->createdAt);
        }

        $iterator->next();
    }

    ?>

O script consumidor começará mostrando rapidamente todos os documentos disponíveis na coleção limitada (como se `foreach` tivesse sido usado); entretanto, ele não terminará ao atingir o final do conjunto de resultados inicial. Como o cursor pode ser seguido, chamar IteratorIterator::next() bloqueará e aguardará resultados adicionais. IteratorIterator::valid() também é usado para verificar se realmente há dados disponíveis para leitura em cada etapa.

> Nota: Este exemplo usa a opção de consulta `awaitData` para instruir o servidor a bloquear por um curto período (por exemplo, um segundo) no final do conjunto de resultados antes de retornar uma resposta ao driver. Isso é usado para evitar que o driver faça uma sondagem agressiva no servidor quando não houver resultados disponíveis. A opção `maxAwaitTimeMS` pode ser usada em conjunto com `tailable` e `awaitData` para especificar a quantidade de tempo que o servidor deve bloquear quando atingir o final do o conjunto de resultados.

## Erros/Exceções

Ao iterar sobre o objeto cursor, os dados BSON são convertidos em variáveis ​ ​PHP. Esta iteração pode causar as seguintes exceções:

- Lança uma MongoDB\Driver\Exception\InvalidArgumentException se uma classe no mapa de tipos não puder ser instanciada ou não implementar MongoDB\BSON\Unserializable.
- Lança uma exceção MongoDB\Driver\Exception\UnexpectedValueException se a entrada não contiver exatamente um documento BSON. Os possíveis motivos incluem, mas não estão limitados a, BSON inválido, dados extras (depois de ler um documento BSON) ou um erro inesperado da » libbson.

# MongoDB\Driver\Cursor::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::__construct — Cria um novo cursor (não utilizado)

### Descrição

final private function MongoDB\Driver\Cursor::__construct()

Objetos MongoDB\Driver\Cursor são retornados como o o resultado de consultas ou comandos executados e não podem ser construídos diretamente.

### Parâmetros

Esta função não possui parâmetros.

### Veja Também

- MongoDB\Driver\Manager::executeCommand() - Executa um comando de banco de dados
- MongoDB\Driver\Manager::executeQuery() - Executa uma consulta ao banco de dados
- MongoDB\Driver\Server::executeCommand() - Executa um comando de banco de dados neste servidor
- MongoDB\Driver\Server::executeQuery() - Executa uma consulta de banco de dados neste servidor

# MongoDB\Driver\Cursor::current

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::current — Retorna o elemento atual

### Descrição

public function MongoDB\Driver\Cursor::current(): array|object|null

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o documento de resultado atual como um array ou objeto, dependendo do mapa de tipo do cursor. Se a iteração não tiver iniciado ou se a posição atual não for válida, retorna `null`.

### Veja Também

- Iterator::current() - Retorna o elemento atual

# MongoDB\Driver\Cursor::getId

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::getId — Retorna o ID para este cursor

### Descrição

final public function MongoDB\Driver\Cursor::getId(): MongoDB\BSON\Int64

Retorna o ID para este cursor, que identifica de forma única o cursor no servidor.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ID para este cursor. O ID será retornado como um objeto MongoDB\BSON\Int64.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | O tipo de retorno foi alterado para MongoDB\BSON\Int64. O parâmetro `asInt64` foi removido.
PECL mongodb 1.20.0 | O retorno de um MongoDB\Driver\CursorId foi descontinuado. Adicionado o parâmetro `asInt64` para facilitar a migração para versões futuras. Se `asInt64` for `true`, o ID será retornado como um MongoDB\BSON\Int64.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\Cursor::getId()

    <?php

    /* Neste exemplo, são inseridos vários documentos na coleção e especificado
     * um batchSize menor para garantir que o primeiro lote contenha apenas um subconjunto dos
     * resultados e que o cursor permaneça aberto no servidor. */
    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $query = new MongoDB\Driver\Query([], ['batchSize' => 2]);

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->insert(['x' => 2]);
    $bulk->insert(['x' => 3]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $cursor = $manager->executeQuery('db.collection', $query);
    var_dump($cursor->getId(true));

    ?>

O exemplo acima produzirá algo semelhante a:

    object(MongoDB\BSON\Int64)#5 (1) {
      ["integer"]=>
      string(11) "94810124093"
    }

### Veja Também

- MongoDB\BSON\Int64

# MongoDB\Driver\Cursor::getServer

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::getServer — Retorna o servidor associado a este cursor

### Descrição

final public function MongoDB\Driver\Cursor::getServer(): MongoDB\Driver\Server

Retorna o MongoDB\Driver\Server associado a este cursor. Este é o servidor que executou a MongoDB\Driver\Query ou o MongoDB\Driver\Command.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o MongoDB\Driver\Server associado a este cursor.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\Cursor::getServer()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $query = new MongoDB\Driver\Query([]);

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $cursor = $manager->executeQuery('db.collection', $query);
    var_dump($cursor->getServer());

    ?>

O exemplo acima produzirá algo semelhante a:

    object(MongoDB\Driver\Server)#5 (10) {
      ["host"]=>
      string(9) "localhost"
      ["port"]=>
      int(27017)
      ["type"]=>
      int(1)
      ["is_primary"]=>
      bool(false)
      ["is_secondary"]=>
      bool(false)
      ["is_arbiter"]=>
      bool(false)
      ["is_hidden"]=>
      bool(false)
      ["is_passive"]=>
      bool(false)
      ["last_hello_response"]=>
      array(8) {
        ["isWritablePrimary"]=>
        bool(true)
        ["maxBsonObjectSize"]=>
        int(16777216)
        ["maxMessageSizeBytes"]=>
        int(48000000)
        ["maxWriteBatchSize"]=>
        int(1000)
        ["localTime"]=>
        object(MongoDB\BSON\UTCDateTime)#6 (1) {
          ["milliseconds"]=>
          int(1446505367907)
        }
        ["maxWireVersion"]=>
        int(3)
        ["minWireVersion"]=>
        int(0)
        ["ok"]=>
        float(1)
      }
      ["round_trip_time"]=>
      int(584)
    }

### Veja Também

- MongoDB\Driver\Server

# MongoDB\Driver\Cursor::isDead

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::isDead — Verifica se o cursor está esgotado ou pode ter resultados adicionais

### Descrição

final public function MongoDB\Driver\Cursor::isDead(): bool

Verifica se definitivamente não há resultados adicionais disponíveis no cursor. Este método é semelhante ao método » cursor.isExhausted() no shell do MongoDB e é útil principalmente ao iterar » cursores adaptáveis.

Um cursor não tem resultados adicionais e é considerado "morto" quando uma das seguintes opções for verdadeira:

- O lote atual foi totalmente iterado e o ID do cursor é zero (ou seja, um » getMore não pode ser emitido).
- Foi encontrado um erro ao iterar o cursor.
- O cursor atingiu o limite configurado.

Por padrão, nem sempre é possível determinar se um cursor possui resultados adicionais. Os casos em que um cursor pode ter mais dados disponíveis são os seguintes:

- Existem documentos adicionais no lote atual, que são armazenados em buffer no lado do cliente. A iteração irá buscar um documento do buffer local.
- Não há documentos adicionais no lote atual (ou seja, buffer local), mas o ID do cursor é diferente de zero. A iteração solicitará mais documentos do servidor por meio de uma operação » getMore, que pode ou não retornar resultados adicionais e/ou indicar que o cursor foi fechado no servidor retornando zero para seu ID.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se definitivamente não houver resultados adicionais disponíveis no cursor e `false` caso contrário.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\Cursor::isDead()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $query = new MongoDB\Driver\Query([]);

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->insert(['x' => 2]);
    $bulk->insert(['x' => 3]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $cursor = $manager->executeQuery('db.collection', $query);

    $iterator = new IteratorIterator($cursor);

    $iterator->rewind();
    var_dump($cursor->isDead());

    $iterator->next();
    var_dump($cursor->isDead());

    $iterator->next();
    var_dump($cursor->isDead());

    $iterator->next();
    var_dump($cursor->isDead());

    ?>

O exemplo acima produzirá:

    bool(false)
    bool(false)
    bool(false)
    bool(true)

### Veja Também

- » Cursores Adaptáveis no manual do MongoDB
- » cursor.isExhausted() no manual do MongoDB

# MongoDB\Driver\Cursor::key

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::key — Retorna o índice do resultado atual dentro do cursor

### Descrição

public function MongoDB\Driver\Cursor::key(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O índice numérico do resultado atual dentro do cursor.

### Veja Também

- Iterator::key() - Retorna a chave do elemento atual

# MongoDB\Driver\Cursor::next

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::next — Avança o cursor para o próximo resultado

### Descrição

public function MongoDB\Driver\Cursor::next(): void

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Move a posição atual para o próximo elemento no cursor.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\ConnectionException se a conexão com o servidor falhar (por outros motivos além da autenticação).
- Lança uma exceção MongoDB\Driver\Exception\AuthenticationException se a autenticação for necessária e falhar.

### Veja Também

- Iterator::next() - Move para o próximo elemento

# MongoDB\Driver\Cursor::rewind

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::rewind — Retrocede o cursor para o primeiro resultado

### Descrição

public function MongoDB\Driver\Cursor::rewind(): void

Se o cursor tiver avançado além da sua primeira posição, não poderá mais ser retrocedido.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

`null`.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\ConnectionException se a conexão com o servidor falhar (por outros motivos além da autenticação).
- Lança uma exceção MongoDB\Driver\Exception\AuthenticationException se a autenticação for necessária e falhar.
- Lança uma MongoDB\Driver\Exception\LogicException se este método for chamado depois que o cursor avançou além de sua primeira posição.

### Veja Também

- Iterator::rewind() - Retrocede o Iterator para o primeiro elemento

# MongoDB\Driver\Cursor::setTypeMap

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::setTypeMap — Define um mapa de tipos a ser usado para desserialização BSON

### Descrição

final public function MongoDB\Driver\Cursor::setTypeMap(array `$typemap`): void

Define a configuração do mapa de tipos a ser usada ao desserializar os resultados do BSON em valores PHP.

### Parâmetros

`typeMap` (array)
  Configuração de mapeamento de tipos.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

Ao iterar sobre o cursor, as seguintes exceções também podem ser lançadas devido a uma configuração incorreta do mapa de tipo:

- Lança uma MongoDB\Driver\Exception\InvalidArgumentException se uma classe no mapa de tipos não puder ser instanciada ou não implementar a interface MongoDB\BSON\Unserializable.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\Cursor::setTypeMap()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    $bulk = new MongoDB\Driver\BulkWrite;
    $id = $bulk->insert(['x' => 1]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $query = new MongoDB\Driver\Query(['_id' => $id]);
    $cursor = $manager->executeQuery('db.collection', $query);
    $cursor->setTypeMap(['root' => 'array']);

    foreach ($cursor as $document) {
        var_dump($document);
    }

    ?>

O exemplo acima produzirá algo semelhante a:

    array(2) {
      ["_id"]=>
      object(MongoDB\BSON\ObjectId)#6 (1) {
        ["oid"]=>
        string(24) "56424fb76118fd3267180741"
      }
      ["x"]=>
      int(1)
    }

### Veja Também

- Dados Persistentes

# MongoDB\Driver\Cursor::toArray

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::toArray — Retorna um array contendo todos os resultados deste cursor

### Descrição

final public function MongoDB\Driver\Cursor::toArray(): array

Itera o cursor e retorna seus resultados em um array. A função MongoDB\Driver\Cursor::setTypeMap() pode ser usada para controlar como os documentos são desserializados em valores PHP.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array contendo todos os resultados deste cursor.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\Cursor::toArray()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->insert(['x' => 2]);
    $bulk->insert(['x' => 3]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $query = new MongoDB\Driver\Query([]);
    $cursor = $manager->executeQuery('db.collection', $query);

    var_dump($cursor->toArray());

    ?>

O exemplo acima produzirá algo semelhante a:

    array(3) {
      [0]=>
      object(stdClass)#6 (2) {
        ["_id"]=>
        object(MongoDB\BSON\ObjectId)#5 (1) {
          ["oid"]=>
          string(24) "564259a96118fd40b41bcf61"
        }
        ["x"]=>
        int(1)
      }
      [1]=>
      object(stdClass)#8 (2) {
        ["_id"]=>
        object(MongoDB\BSON\ObjectId)#7 (1) {
          ["oid"]=>
          string(24) "564259a96118fd40b41bcf62"
        }
        ["x"]=>
        int(2)
      }
      [2]=>
      object(stdClass)#10 (2) {
        ["_id"]=>
        object(MongoDB\BSON\ObjectId)#9 (1) {
          ["oid"]=>
          string(24) "564259a96118fd40b41bcf63"
        }
        ["x"]=>
        int(3)
      }
    }

### Veja Também

- MongoDB\Driver\Cursor::setTypeMap() - Define um mapa de tipos a ser usado para desserialização BSON

# MongoDB\Driver\Cursor::valid

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::valid — Verifica se a posição atual no cursor é válida

### Descrição

public function MongoDB\Driver\Cursor::valid(): bool

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

`true` se a posição atual do cursor for válida, `false` caso contrário.

### Veja Também

- Iterator::valid() - Verifica se a posição atual é válida

## Índice

- MongoDB\Driver\Cursor::__construct — Cria um novo cursor (não utilizado)
- MongoDB\Driver\Cursor::current — Retorna o elemento atual
- MongoDB\Driver\Cursor::getId — Retorna o ID para este cursor
- MongoDB\Driver\Cursor::getServer — Retorna o servidor associado a este cursor
- MongoDB\Driver\Cursor::isDead — Verifica se o cursor está esgotado ou pode ter resultados adicionais
- MongoDB\Driver\Cursor::key — Retorna o índice do resultado atual dentro do cursor
- MongoDB\Driver\Cursor::next — Avança o cursor para o próximo resultado
- MongoDB\Driver\Cursor::rewind — Retrocede o cursor para o primeiro resultado
- MongoDB\Driver\Cursor::setTypeMap — Define um mapa de tipos a ser usado para desserialização BSON
- MongoDB\Driver\Cursor::toArray — Retorna um array contendo todos os resultados deste cursor
- MongoDB\Driver\Cursor::valid — Verifica se a posição atual no cursor é válida

# A classe MongoDB\Driver\CursorId

(mongodb >=1.0.0)

## Introdução

A classe MongoDB\Driver\CursorID é um objeto de valor que representa um ID de cursor. Instâncias desta classe são retornadas por MongoDB\Driver\Cursor::getId().

Aviso

Esta classe foi DESCONTINUADA a partir da versão de extensão 1.20.0 e foi removida na versão 2.0. As aplicações devem atualizar seu uso de MongoDB\Driver\Cursor::getId() para retornar um MongoDB\BSON\Int64 no lugar.

## Resumo da classe

final class MongoDB\Driver\CursorId implements Serializable, Stringable {
/* Métodos */
final private function __construct()
final public function __toString(): string
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Esta classe foi removida.
PECL mongodb 1.20.0 | Esta classe foi descontinuada e será removida na versão 2.0.
PECL mongodb 1.12.0 | Implementa Stringable para o PHP 8.0+.
PECL mongodb 1.7.0 | Implementa Serializable.

# MongoDB\Driver\CursorId::__construct

(mongodb >=1.0.0)

MongoDB\Driver\CursorId::__construct — Constrói um novo ID de cursor (não utilizado)

### Descrição

final private function MongoDB\Driver\CursorId::__construct()

Objetos MongoDB\Driver\CursorId são retornados pela função MongoDB\Driver\Cursor::getId() e não podem ser construídos diretamente.

### Parâmetros

Esta função não possui parâmetros.

### Veja Também

- MongoDB\Driver\Cursor::getId() - Retorna o ID para este cursor

# MongoDB\Driver\CursorId::__toString

(mongodb >=1.0.0)

MongoDB\Driver\CursorId::__toString — Representação string do ID de cursor

### Descrição

final public function MongoDB\Driver\CursorId::__toString(): string

Retorna a representação em string do ID de cursor.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a representação em string do ID de cursor.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\CursorId::__toString()

    <?php

    /* Neste exemplo, são inseridos vários documentos na coleção e especificado
     * um batchSize menor para garantir que o primeiro lote contenha apenas um subconjunto dos
     * resultados e que o cursor permaneça aberto no servidor. */
    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $query = new MongoDB\Driver\Query([], ['batchSize' => 2]);

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->insert(['x' => 2]);
    $bulk->insert(['x' => 3]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $cursor = $manager->executeQuery('db.collection', $query);
    var_dump((string) $cursor->getId());

    ?>

O exemplo acima produzirá algo semelhante a:

    string(11) "98061641158"

### Veja Também

- MongoDB\Driver\Cursor::getId() - Retorna o ID para este cursor

## Índice

- MongoDB\Driver\CursorId::__construct — Constrói um novo ID de cursor (não utilizado)
- MongoDB\Driver\CursorId::__toString — Representação string do ID de cursor

# A interface MongoDB\Driver\CursorInterface

(mongodb >=1.6.0)

## Introdução

Esta interface é implementada por MongoDB\Driver\Cursor para ser usada como um tipo de parâmetro, de retorno ou de propriedade em classes do usuário.

## Resumo da classe

class MongoDB\Driver\CursorInterface implements Iterator {
/* Métodos */
abstract public function getId(): MongoDB\BSON\Int64
abstract public function getServer(): MongoDB\Driver\Server
abstract public function isDead(): bool
abstract public function setTypeMap(array `$typemap`): void
abstract public function toArray(): array
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Esta interface agora estende Iterator. Tipos de retorno anteriormente declarados como temporários agora devem ser cumpridos.
mongodb 1.15.0 no PECL | Os tipos de retorno para métodos são declarados como provisórios no PHP 8.0 e mais recentes, disparando avisos de descontinuação no código que implementa essa interface sem declarar os tipos de retorno apropriados. O atributo `#[ReturnTypeWillChange]` pode ser adicionado para silenciar o aviso de descontinuação.

# MongoDB\Driver\CursorInterface::getId

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::getId — Retorna o ID deste cursor

### Descrição

abstract public function MongoDB\Driver\CursorInterface::getId(): MongoDB\BSON\Int64

Retorna o ID deste cursor, que identifica o cursor de forma única no servidor.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ID deste cursor.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.20.0 | Adicionado MongoDB\BSON\Int64 ao tipo de retorno provisório para este método. MongoDB\Driver\CursorId será removido do tipo de retorno na versão 2.0.

### Veja Também

- MongoDB\Driver\Cursor::getId() - Retorna o ID para este cursor
- MongoDB\Driver\CursorId
- MongoDB\BSON\Int64

# MongoDB\Driver\CursorInterface::getServer

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::getServer — Retorna o servidor associado a este cursor

### Descrição

abstract public function MongoDB\Driver\CursorInterface::getServer(): MongoDB\Driver\Server

Retorna o MongoDB\Driver\Server associado a este cursor. Este é o servidor que executou a MongoDB\Driver\Query ou o MongoDB\Driver\Command.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o MongoDB\Driver\Server associado a este cursor.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Cursor::getServer() - Retorna o servidor associado a este cursor
- MongoDB\Driver\Server

# MongoDB\Driver\CursorInterface::isDead

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::isDead — Verifica se o cursor pode ter resultados adicionais

### Descrição

abstract public function MongoDB\Driver\CursorInterface::isDead(): bool

Verifica se o cursor pode ter resultados adicionais disponíveis para leitura. Um cursor está inicialmente "vivo", mas pode ficar "morto" por qualquer um dos seguintes motivos:

- O avanço de um cursor não-adaptável não retornou um documento
- O cursor encontrou um erro
- O cursor leu seu último lote até a conclusão
- O cursor atingiu seu limite configurado

Isso é útil principalmente com cursores adaptáveis.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se não houver resultados adicionais disponíveis ou `false` caso contrário.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Cursor::isDead() - Verifica se o cursor está esgotado ou pode ter resultados adicionais

# MongoDB\Driver\CursorInterface::setTypeMap

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::setTypeMap — Define um mapa de tipos a ser usado para desserialização BSON

### Descrição

abstract public function MongoDB\Driver\CursorInterface::setTypeMap(array `$typemap`): void

Define a configuração do mapa de tipos a ser usada ao desserializar os resultados do BSON em valores PHP.

### Parâmetros

`typeMap` (array)
  Configuração de mapeamento de tipos.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Cursor::setTypeMap() - Define um mapa de tipos a ser usado para desserialização BSON
- Dados Persistentes

# MongoDB\Driver\CursorInterface::toArray

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::toArray — Retorna um array contendo todos os resultados deste cursor

### Descrição

abstract public function MongoDB\Driver\CursorInterface::toArray(): array

Itera o cursor e retorna seus resultados em um array. A função MongoDB\Driver\CursorInterface::setTypeMap() pode ser usada para controlar como os documentos serão desserializados em valores PHP.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array contendo todos os resultados deste cursor.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Cursor::toArray() - Retorna um array contendo todos os resultados deste cursor
- MongoDB\Driver\CursorInterface::setTypeMap() - Define um mapa de tipos a ser usado para desserialização BSON

## Índice

- MongoDB\Driver\CursorInterface::getId — Retorna o ID deste cursor
- MongoDB\Driver\CursorInterface::getServer — Retorna o servidor associado a este cursor
- MongoDB\Driver\CursorInterface::isDead — Verifica se o cursor pode ter resultados adicionais
- MongoDB\Driver\CursorInterface::setTypeMap — Define um mapa de tipos a ser usado para desserialização BSON
- MongoDB\Driver\CursorInterface::toArray — Retorna um array contendo todos os resultados deste cursor

# A classe MongoDB\Driver\Server

(mongodb >=1.0.0)

## Introdução

## Resumo da classe

final class MongoDB\Driver\Server {
/* Constantes */
const int TYPE_UNKNOWN = 0;
const int TYPE_STANDALONE = 1;
const int TYPE_MONGOS = 2;
const int TYPE_POSSIBLE_PRIMARY = 3;
const int TYPE_RS_PRIMARY = 4;
const int TYPE_RS_SECONDARY = 5;
const int TYPE_RS_ARBITER = 6;
const int TYPE_RS_OTHER = 7;
const int TYPE_RS_GHOST = 8;
const int TYPE_LOAD_BALANCER = 9;
/* Métodos */
final private function __construct()
final public function executeBulkWrite(string `$namespace`, MongoDB\Driver\BulkWrite `$bulk`, ?array `$options` = `null`): MongoDB\Driver\WriteResult
final public function executeBulkWriteCommand(MongoDB\Driver\BulkWriteCommand `$bulk`, ?array `$options` = `null`): MongoDB\Driver\BulkWriteCommandResult
final public function executeCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeQuery(string `$namespace`, MongoDB\Driver\Query `$query`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeReadCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeReadWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function getHost(): string
final public function getInfo(): array
final public function getLatency(): ?integer
final public function getPort(): int
final public function getServerDescription(): MongoDB\Driver\ServerDescription
final public function getTags(): array
final public function getType(): int
final public function isArbiter(): bool
final public function isHidden(): bool
final public function isPassive(): bool
final public function isPrimary(): bool
final public function isSecondary(): bool
}

## Constantes predefinidas

`MongoDB\Driver\Server::TYPE_UNKNOWN`
  Tipo de servidor desconhecido, retornada por MongoDB\Driver\Server::getType().
`MongoDB\Driver\Server::TYPE_STANDALONE`
  Tipo de servidor autônomo, retornada por MongoDB\Driver\Server::getType().
`MongoDB\Driver\Server::TYPE_MONGOS`
  Tipo de servidor Mongos, retornada por MongoDB\Driver\Server::getType().
`MongoDB\Driver\Server::TYPE_POSSIBLE_PRIMARY`
  Tipo de servidor conjunto de réplicas, possivelmente primário, retornada por MongoDB\Driver\Server::getType(). Um servidor pode ser identificado como um possível primário se ainda não tiver sido verificado, mas outro membro do conjunto de réplicas pensa que é o primário.
`MongoDB\Driver\Server::TYPE_RS_PRIMARY`
  Tipo de servidor conjunto de réplicas primário, retornada por MongoDB\Driver\Server::getType().
`MongoDB\Driver\Server::TYPE_RS_SECONDARY`
  Tipo de servidor conjunto de réplicas secundário, retornada por MongoDB\Driver\Server::getType().
`MongoDB\Driver\Server::TYPE_RS_ARBITER`
  Tipo de servidor conjunto de réplicas árbitro, retornada por MongoDB\Driver\Server::getType().
`MongoDB\Driver\Server::TYPE_RS_OTHER`
  Tipo de servidor conjunto de réplicas outros, retornada por MongoDB\Driver\Server::getType(). Esses servidores podem estar ocultos, inicializando ou recuperando. Eles não podem ser consultados, mas suas listas de hosts são úteis para descobrir a configuração atual do conjunto de réplicas.
`MongoDB\Driver\Server::TYPE_RS_GHOST`
  Tipo de servidor conjunto de réplicas fantasma, retornada por MongoDB\Driver\Server::getType(). Os servidores podem ser identificados como tal em pelo menos três situações: brevemente durante a inicialização do servidor; em um conjunto de réplicas não inicializado; ou quando o servidor é evitado (ou seja, removido da configuração do conjunto de réplicas). Eles não podem ser consultados, nem sua lista de hosts pode ser usada para descobrir a configuração atual do conjunto de réplicas; entretanto, o cliente pode monitorar este servidor na esperança de que ele faça a transição para um estado mais útil.
`MongoDB\Driver\Server::TYPE_LOAD_BALANCER`
  Tipo de servidor balanceador de carga, retornada por MongoDB\Driver\Server::getType().

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.11.0 | A constante `MongoDB\Driver\Server::TYPE_LOAD_BALANCER` foi adicionada.

# MongoDB\Driver\Server::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Server::__construct — Cria um novo servidor (não utilizado)

### Descrição

final private function MongoDB\Driver\Server::__construct()

Os objetos MongoDB\Driver\Server são criados internamente pelo MongoDB\Driver\Manager quando uma conexão com o banco de dados é estabelecida e podem ser retornados por MongoDB\Driver\Manager::getServers() e MongoDB\Driver\Manager::selectServer().

### Parâmetros

Esta função não possui parâmetros.

### Veja Também

- MongoDB\Driver\Manager::getServers() - Retorna os servidores aos quais este gerenciador está conectado
- MongoDB\Driver\Manager::selectServer() - Seleciona um servidor que corresponde a uma preferência de leitura

# MongoDB\Driver\Server::executeBulkWrite

(mongodb >=1.0.0)

MongoDB\Driver\Server::executeBulkWrite — Executa uma ou mais operações de gravação neste servidor

### Descrição

final public function MongoDB\Driver\Server::executeBulkWrite(string `$namespace`, MongoDB\Driver\BulkWrite `$bulk`, ?array `$options` = `null`): MongoDB\Driver\WriteResult

Executa uma ou mais operações de gravação neste servidor.

Um MongoDB\Driver\BulkWrite pode ser construído com uma ou mais operações de gravação de vários tipos (por exemplo, atualizações, exclusões e inserções). O driver tentará enviar operações do mesmo tipo ao servidor no menor número possível de solicitações para otimizar viagens de ida e volta.

O valor padrão para a opção `"writeConcern"` será inferido de uma transação ativa (indicada pela opção `"session"`), seguida pelo URI de conexão.

### Parâmetros

`namespace` (string)
  Um namespace totalmente qualificado (por exemplo, `"nomeDoBancoDados.nomeDaColecao"`).
`bulk` (MongoDB\Driver\BulkWrite)
  As gravações a serem executadas.
`options`

  Opções
  Opção | Tipo | Descrição
  --- | --- | ---
  session | MongoDB\Driver\Session | Uma sessão para associar à operação.
  writeConcern | MongoDB\Driver\WriteConcern | Um write concern a ser aplicado à operação.

### Valor Retornado

Retorna MongoDB\Driver\WriteResult em caso de sucesso.

### Erros/Exceções

- Lança uma MongoDB\Driver\Exception\InvalidArgumentException se `bulk` não contiver nenhuma operação de gravação.
- Lança uma MongoDB\Driver\Exception\InvalidArgumentException se `bulk` já tiver sido executado. Os objetos MongoDB\Driver\BulkWrite não podem ser executados várias vezes.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException se a opção `"session"` for usada em combinação com uma preocupação de escrita não confirmada.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\ConnectionException se a conexão com o servidor falhar (por outros motivos além da autenticação).
- Lança uma exceção MongoDB\Driver\Exception\AuthenticationException se a autenticação for necessária e falhar.
- Lança uma exceção MongoDB\Driver\Exception\BulkWriteException em caso de qualquer falha de escrita (por exemplo, erro de escrita, falha ao aplicar uma preocupação de escrita).
- Lança um MongoDB\Driver\Exception\RuntimeException em outros erros.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | O parâmetro `options` não aceita mais uma instância de MongoDB\Driver\WriteConcern.
PECL mongodb 1.21.0 | Passar um objeto MongoDB\Driver\WriteConcern como `options` foi descontinuado e será removido na versão 2.0.
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException será lançada se a opção `"session"` for usada em combinação com uma preocupação de gravação não reconhecida.
PECL mongodb 1.4.0 | O terceiro parâmetro agora é um array `options`. Para compatibilidade com versões anteriores, esse parâmetro ainda aceitará um objeto MongoDB\Driver\WriteConcern.
PECL mongodb 1.3.0 | MongoDB\Driver\Exception\InvalidArgumentException agora é lançada se `bulk` não contiver nenhuma operação de gravação. Anteriormente, uma MongoDB\Driver\Exception\BulkWriteException era lançada.

### Notas

> Nota: É responsabilidade do invocador garantir que o servidor seja capaz de executar a operação de escrita. Por exemplo, executar uma operação de escrita em um servidor secundário (excluindo seu banco de dados "local") falhará.

### Veja Também

- MongoDB\Driver\BulkWrite
- MongoDB\Driver\WriteResult
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\Manager::executeBulkWrite() - Executa uma ou mais operações de escrita

# MongoDB\Driver\Server::executeBulkWriteCommand

(mongodb >=2.1.0)

MongoDB\Driver\Server::executeBulkWriteCommand — Executa operações de gravação neste servidor usando o comando bulkWrite

### Descrição

final public function MongoDB\Driver\Server::executeBulkWriteCommand(MongoDB\Driver\BulkWriteCommand `$bulk`, ?array `$options` = `null`): MongoDB\Driver\BulkWriteCommandResult

Executa uma ou mais operações de gravação neste servidor usando o comando » bulkWrite introduzido no MongoDB 8.0.

Um MongoDB\Driver\BulkWriteCommand pode ser construído com uma ou mais operações de gravação de tipos variados (por exemplo, inserções, atualizações e exclusões). Cada operação de gravação pode ter como alvo uma coleção diferente.

O valor padrão para a opção `"writeConcern"` será inferido a partir de uma transação ativa (indicada pela opção `"session"`), seguida pelo URI de conexão.

### Parâmetros

`bulk` (MongoDB\Driver\BulkWriteCommand)
  O comando de gravações a ser executado.
`options`

  Opções
  Opção | Tipo | Descrição
  --- | --- | ---
  session | MongoDB\Driver\Session | Uma sessão para associar à operação.
  writeConcern | MongoDB\Driver\WriteConcern | Um write concern a ser aplicado à operação.

### Valor Retornado

Retorna MongoDB\Driver\BulkWriteCommandResult em caso de sucesso.

### Erros/Exceções

- Lança MongoDB\Driver\Exception\InvalidArgumentException se `bulk` não contiver nenhuma operação de gravação.
- Lança MongoDB\Driver\Exception\InvalidArgumentException se `bulk` já tiver sido executado. Objetos MongoDB\Driver\BulkWriteCommand não podem ser executados várias vezes.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException se a opção `"session"` for usada em combinação com uma preocupação de escrita não confirmada.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\ConnectionException se a conexão com o servidor falhar (por outros motivos além da autenticação).
- Lança uma exceção MongoDB\Driver\Exception\AuthenticationException se a autenticação for necessária e falhar.
- Lança uma exceção MongoDB\Driver\Exception\BulkWriteCommandException em caso de qualquer falha de escrita (por exemplo, falha no comando, erro de escrita ou de preocupação de escrita)
- Lança MongoDB\Driver\Exception\RuntimeException em outros erros.

### Veja Também

- MongoDB\Driver\BulkWriteCommand
- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Executa operações de gravação usando o comando bulkWrite

# MongoDB\Driver\Server::executeCommand

(mongodb >=1.0.0)

MongoDB\Driver\Server::executeCommand — Executa um comando de banco de dados neste servidor

### Descrição

final public function MongoDB\Driver\Server::executeCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Executa o comando neste servidor.

Este método não aplica nenhuma lógica especial ao comando. Os valores padrão para as opções `"readPreference"`, `"readConcern"` e `"writeConcern"` serão inferidos de uma transação ativa (indicada pela opção `"session"`). Se não houver nenhuma transação ativa, uma preferência de leitura primária será usada para seleção do servidor.

Os valores padrão não serão inferidos do URI de conexão. Os usuários são, portanto, incentivados a usar métodos de comando específicos de leitura e/ou gravação, se possível.

> Nota: A opção `"readPreference"` não controla o servidor ao qual o driver emite a operação; ela sempre será executada neste objeto servidor. Em vez disso, ela pode ser usada ao emitir a operação para um servidor secundário (de uma conexão de conjunto de réplicas, não autônomas) ou nós mongo para garantir que o driver defina o protocolo de conexão de acordo ou adicione a preferência de leitura à operação, respectivamente.

### Parâmetros

`db` (string)
  O nome do banco de dados no qual executar o comando.
`command` (MongoDB\Driver\Command)
  O comando a ser executado.
`options`

  Opções
  Opção | Tipo | Descrição
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Um read concern a ser aplicado à operação. Esta opção está disponível no MongoDB 3.2+ e resultará em uma exceção em tempo de execução se for especificada para uma versão de servidor mais antiga.
  readPreference | MongoDB\Driver\ReadPreference | Uma preferência de leitura a ser usada para selecionar um servidor para a operação.
  session | MongoDB\Driver\Session | Uma sessão para associar à operação.
  writeConcern | MongoDB\Driver\WriteConcern | Um write concern a ser aplicado à operação.

  Aviso

  Se uma `"session"` que tem uma transação em andamento estiver sendo usada, uma opção `"readConcern"` ou `"writeConcern"` não pode ser especificada. Isso resultará em uma exceção MongoDB\Driver\Exception\InvalidArgumentException sendo lançada. Em vez disso, essas duas opções devem ser definidas ao criar a transação com MongoDB\Driver\Session::startTransaction().

### Valor Retornado

Retorna MongoDB\Driver\Cursor em caso de sucesso.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException se a opção `"session"` for usada com uma transação associada em combinação com uma opção `"readConcern"` ou `"writeConcern"`.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException se a opção `"session"` for usada em combinação com uma preocupação de escrita não confirmada.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\ConnectionException se a conexão com o servidor falhar (por outros motivos além da autenticação).
- Lança uma exceção MongoDB\Driver\Exception\AuthenticationException se a autenticação for necessária e falhar.
- Lança uma MongoDB\Driver\Exception\RuntimeException em outros erros (por exemplo, comando inválido, emissão de um comando de gravação para um secundário).

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | O parâmetro `options` não aceita mais uma instância de MongoDB\Driver\ReadPreference.
PECL mongodb 1.21.0 | Passar um objeto MongoDB\Driver\ReadPreference como `options` foi descontinuado e será removido na versão 2.0.
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException será lançada se a opção `"session"` for usada em combinação com uma preocupação de gravação não reconhecida.
PECL mongodb 1.4.0 | O terceiro parâmetro agora é um array `options`. Para compatibilidade com versões anteriores, esse parâmetro ainda aceitará um objeto MongoDB\Driver\ReadPreference.

### Notas

> Nota: É responsabilidade do invocador garantir que o servidor seja capaz de executar a operação de escrita. Por exemplo, executar uma operação de escrita em um servidor secundário (excluindo seu banco de dados "local") falhará.

### Veja Também

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Server::executeReadCommand() - Executa um comando de banco de dados que lê neste servidor
- MongoDB\Driver\Server::executeReadWriteCommand() - Executa um comando de banco de dados que lê e grava neste servidor
- MongoDB\Driver\Server::executeWriteCommand() - Executa um comando de banco de dados que grava neste servidor
- MongoDB\Driver\Manager::executeCommand() - Executa um comando de banco de dados

# MongoDB\Driver\Server::executeQuery

(mongodb >=1.0.0)

MongoDB\Driver\Server::executeQuery — Executa uma consulta de banco de dados neste servidor

### Descrição

final public function MongoDB\Driver\Server::executeQuery(string `$namespace`, MongoDB\Driver\Query `$query`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Executa a consulta neste servidor.

Os valores padrão para a opção `"readPreference"` e para a opção `"readConcern"` da consulta serão inferidos de uma transação ativa (indicada pela opção `"session"`), seguida pelo URI de conexão.

> Nota: A opção `"readPreference"` não controla o servidor ao qual o driver emite a operação; ela sempre será executada neste objeto servidor. Em vez disso, ela pode ser usada ao emitir a operação para um servidor secundário (de uma conexão de conjunto de réplicas, não autônomas) ou nós mongo para garantir que o driver defina o protocolo de conexão de acordo ou adicione a preferência de leitura à operação, respectivamente.

### Parâmetros

`namespace` (string)
  Um namespace totalmente qualificado (por exemplo, `"nomeDoBancoDados.nomeDaColecao"`).
`query` (MongoDB\Driver\Query)
  A consulta a ser executada.
`options`

  Opções
  Opção | Tipo | Descrição
  --- | --- | ---
  readPreference | MongoDB\Driver\ReadPreference | Uma preferência de leitura a ser usada para selecionar um servidor para a operação.
  session | MongoDB\Driver\Session | Uma sessão para associar à operação.

### Valor Retornado

Retorna MongoDB\Driver\Cursor em caso de sucesso.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\ConnectionException se a conexão com o servidor falhar (por outros motivos além da autenticação).
- Lança uma exceção MongoDB\Driver\Exception\AuthenticationException se a autenticação for necessária e falhar.
- Lança uma MongoDB\Driver\Exception\RuntimeException em outros erros (por exemplo, operadores de consulta inválidos).

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | O parâmetro `options` não aceita mais uma instância de MongoDB\Driver\ReadPreference.
PECL mongodb 1.21.0 | Passar um objeto MongoDB\Driver\ReadPreference como `options` foi descontinuado e será removido na versão 2.0.
PECL mongodb 1.4.0 | O terceiro parâmetro agora é um array `options`. Para compatibilidade com versões anteriores, esse parâmetro ainda aceitará um objeto MongoDB\Driver\ReadPreference.

### Veja Também

- MongoDB\Driver\Cursor
- MongoDB\Driver\Query
- MongoDB\Driver\ReadPreference
- MongoDB\Driver\Manager::executeQuery() - Executa uma consulta ao banco de dados

# MongoDB\Driver\Server::executeReadCommand

(mongodb >=1.4.0)

MongoDB\Driver\Server::executeReadCommand — Executa um comando de banco de dados que lê neste servidor

### Descrição

final public function MongoDB\Driver\Server::executeReadCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Executa o comando neste servidor, independentemente da opção `"readPreference"`.

Este método aplicará uma lógica específica para comandos de leitura (por exemplo, » distinct). Os valores padrão para as opções `"readPreference"` e `"readConcern"` serão inferidos de uma transação ativa (indicada pela opção `"session"`), seguida pelo URI de conexão.

> Nota: A opção `"readPreference"` não controla o servidor ao qual o driver emite a operação; ela sempre será executada neste objeto servidor. Em vez disso, ela pode ser usada ao emitir a operação para um servidor secundário (de uma conexão de conjunto de réplicas, não autônomas) ou nós mongo para garantir que o driver defina o protocolo de conexão de acordo ou adicione a preferência de leitura à operação, respectivamente.

### Parâmetros

`db` (string)
  O nome do banco de dados no qual executar o comando.
`command` (MongoDB\Driver\Command)
  O comando a ser executado.
`options`

  Opções
  Opção | Tipo | Descrição
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Um read concern a ser aplicado à operação. Esta opção está disponível no MongoDB 3.2+ e resultará em uma exceção em tempo de execução se for especificada para uma versão de servidor mais antiga.
  readPreference | MongoDB\Driver\ReadPreference | Uma preferência de leitura a ser usada para selecionar um servidor para a operação.
  session | MongoDB\Driver\Session | Uma sessão para associar à operação.

  Aviso

  Se uma `"session"` que tem uma transação em andamento estiver sendo usada, uma opção `"readConcern"` ou `"writeConcern"` não pode ser especificada. Isso resultará em uma exceção MongoDB\Driver\Exception\InvalidArgumentException sendo lançada. Em vez disso, essas duas opções devem ser definidas ao criar a transação com MongoDB\Driver\Session::startTransaction().

### Valor Retornado

Retorna MongoDB\Driver\Cursor em caso de sucesso.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException se a opção `"session"` for usada com uma transação associada em combinação com uma opção `"readConcern"` ou `"writeConcern"`.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\ConnectionException se a conexão com o servidor falhar (por outros motivos além da autenticação).
- Lança uma exceção MongoDB\Driver\Exception\AuthenticationException se a autenticação for necessária e falhar.
- Lança uma MongoDB\Driver\Exception\RuntimeException em outros erros (por exemplo, comando inválido).

### Veja Também

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Server::executeCommand() - Executa um comando de banco de dados neste servidor
- MongoDB\Driver\Server::executeReadWriteCommand() - Executa um comando de banco de dados que lê e grava neste servidor
- MongoDB\Driver\Server::executeWriteCommand() - Executa um comando de banco de dados que grava neste servidor
- MongoDB\Driver\Manager::executeReadCommand() - Executa um comando de banco de dados que faz leitura

# MongoDB\Driver\Server::executeReadWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Server::executeReadWriteCommand — Executa um comando de banco de dados que lê e grava neste servidor

### Descrição

final public function MongoDB\Driver\Server::executeReadWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Executa o comando neste servidor.

Este método aplicará lógica específica para comandos de leitura e gravação (por exemplo, » aggregate). Os valores padrão para as opções `"readConcern"` e `"writeConcern"` serão inferidos de uma transação ativa (indicada pela opção `"session"`), seguida pelo URI de conexão.

### Parâmetros

`db` (string)
  O nome do banco de dados no qual executar o comando.
`command` (MongoDB\Driver\Command)
  O comando a ser executado.
`options`

  Opções
  Opção | Tipo | Descrição
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Um read concern a ser aplicado à operação. Esta opção está disponível no MongoDB 3.2+ e resultará em uma exceção em tempo de execução se for especificada para uma versão de servidor mais antiga.
  session | MongoDB\Driver\Session | Uma sessão para associar à operação.
  writeConcern | MongoDB\Driver\WriteConcern | Um write concern a ser aplicado à operação.

  Aviso

  Se uma `"session"` que tem uma transação em andamento estiver sendo usada, uma opção `"readConcern"` ou `"writeConcern"` não pode ser especificada. Isso resultará em uma exceção MongoDB\Driver\Exception\InvalidArgumentException sendo lançada. Em vez disso, essas duas opções devem ser definidas ao criar a transação com MongoDB\Driver\Session::startTransaction().

### Valor Retornado

Retorna MongoDB\Driver\Cursor em caso de sucesso.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException se a opção `"session"` for usada com uma transação associada em combinação com uma opção `"readConcern"` ou `"writeConcern"`.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException se a opção `"session"` for usada em combinação com uma preocupação de escrita não confirmada.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\ConnectionException se a conexão com o servidor falhar (por outros motivos além da autenticação).
- Lança uma exceção MongoDB\Driver\Exception\AuthenticationException se a autenticação for necessária e falhar.
- Lança uma MongoDB\Driver\Exception\RuntimeException em outros erros (por exemplo, comando inválido).

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException será lançada se a opção `"session"` for usada em combinação com uma preocupação de gravação não reconhecida.

### Notas

> Nota: É responsabilidade do invocador garantir que o servidor seja capaz de executar a operação de escrita. Por exemplo, executar uma operação de escrita em um servidor secundário (excluindo seu banco de dados "local") falhará.

### Veja Também

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Server::executeCommand() - Executa um comando de banco de dados neste servidor
- MongoDB\Driver\Server::executeReadCommand() - Executa um comando de banco de dados que lê neste servidor
- MongoDB\Driver\Server::executeWriteCommand() - Executa um comando de banco de dados que grava neste servidor
- MongoDB\Driver\Manager::executeReadWriteCommand() - Executa um comando de banco de dados que lê e grava

# MongoDB\Driver\Server::executeWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Server::executeWriteCommand — Executa um comando de banco de dados que grava neste servidor

### Descrição

final public function MongoDB\Driver\Server::executeWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Executa o comando neste servidor.

Este método aplicará lógica específica para comandos que escrevem (por exemplo, » drop). O valor padrão para a opção `"writeConcern"` será inferido de uma transação ativa (indicada pela opção `"session"`), seguida pelo URI de conexão.

> Nota: Este método não se destina a ser usado para executar comandos » insert, » update ou » delete. Os usuários são incentivados a usar MongoDB\Driver\Server::executeBulkWrite() para essas operações.

### Parâmetros

`db` (string)
  O nome do banco de dados no qual executar o comando.
`command` (MongoDB\Driver\Command)
  O comando a ser executado.
`options`

  Opções
  Opção | Tipo | Descrição
  --- | --- | ---
  session | MongoDB\Driver\Session | Uma sessão para associar à operação.
  writeConcern | MongoDB\Driver\WriteConcern | Um write concern a ser aplicado à operação.

  Aviso

  Se uma `"session"` que tem uma transação em andamento estiver sendo usada, uma opção `"readConcern"` ou `"writeConcern"` não pode ser especificada. Isso resultará em uma exceção MongoDB\Driver\Exception\InvalidArgumentException sendo lançada. Em vez disso, essas duas opções devem ser definidas ao criar a transação com MongoDB\Driver\Session::startTransaction().

### Valor Retornado

Retorna MongoDB\Driver\Cursor em caso de sucesso.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException se a opção `"session"` for usada com uma transação associada em combinação com uma opção `"readConcern"` ou `"writeConcern"`.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException se a opção `"session"` for usada em combinação com uma preocupação de escrita não confirmada.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\ConnectionException se a conexão com o servidor falhar (por outros motivos além da autenticação).
- Lança uma exceção MongoDB\Driver\Exception\AuthenticationException se a autenticação for necessária e falhar.
- Lança uma MongoDB\Driver\Exception\RuntimeException em outros erros (por exemplo, comando inválido).

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException será lançada se a opção `"session"` for usada em combinação com uma preocupação de gravação não reconhecida.

### Notas

> Nota: É responsabilidade do invocador garantir que o servidor seja capaz de executar a operação de escrita. Por exemplo, executar uma operação de escrita em um servidor secundário (excluindo seu banco de dados "local") falhará.

### Veja Também

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Server::executeCommand() - Executa um comando de banco de dados neste servidor
- MongoDB\Driver\Server::executeReadCommand() - Executa um comando de banco de dados que lê neste servidor
- MongoDB\Driver\Server::executeReadWriteCommand() - Executa um comando de banco de dados que lê e grava neste servidor
- MongoDB\Driver\Manager::executeWriteCommand() - Executa um comando de banco de dados que escreve

# MongoDB\Driver\Server::getHost

(mongodb >=1.0.0)

MongoDB\Driver\Server::getHost — Retorna o nome do host deste servidor

### Descrição

final public function MongoDB\Driver\Server::getHost(): string

Retorna o nome do host deste servidor.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o nome do host deste servidor.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\Server::getHost()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017/");
    $server = $manager->selectServer();

    var_dump($server->getHost());

    ?>

O exemplo acima produzirá:

    string(9) "localhost"

### Veja Também

- MongoDB\Driver\Server::getInfo() - Retorna um array de informações que descrevem este servidor
- MongoDB\Driver\ServerDescription::getHost() - Retorna o nome do host deste servidor

# MongoDB\Driver\Server::getInfo

(mongodb >=1.0.0)

MongoDB\Driver\Server::getInfo — Retorna um array de informações que descrevem este servidor

### Descrição

final public function MongoDB\Driver\Server::getInfo(): array

Retorna um array de informações que descrevem o servidor. Esse array é derivado da resposta do comando » hello mais recente obtida por meio de » monitoramento do servidor.

> Nota: Quando o driver estiver conectado a um balanceador de carga, esse método retornará a resposta do comando » hello enviada pelo servidor de apoio no handshake de conexão inicial. Isso contrasta com outros métodos (por exemplo, MongoDB\Driver\Server::getType()), que retornarão informações sobre o próprio balanceador de carga.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array de informações que descrevem este servidor.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\Server::getInfo()

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017/');

    $rp = new MongoDB\Driver\ReadPreference('primary');
    $server = $manager->selectServer($rp);

    var_dump($server->getInfo());

    ?>

O exemplo acima produzirá algo semelhante a:

    array(23) {
      ["helloOk"]=>
      bool(true)
      ["topologyVersion"]=>
      array(2) {
        ["processId"]=>
        object(MongoDB\BSON\ObjectId)#4 (1) {
          ["oid"]=>
          string(24) "617b6d696a3a89d2f77e6df0"
        }
        ["counter"]=>
        int(6)
      }
      ["hosts"]=>
      array(1) {
        [0]=>
        string(15) "localhost:27017"
      }
      ["setName"]=>
      string(3) "rs0"
      ["setVersion"]=>
      int(1)
      ["ismaster"]=>
      bool(true)
      ["secondary"]=>
      bool(false)
      ["primary"]=>
      string(15) "localhost:27017"
      ["me"]=>
      string(15) "localhost:27017"
      ["electionId"]=>
      object(MongoDB\BSON\ObjectId)#5 (1) {
        ["oid"]=>
        string(24) "7fffffff0000000000000001"
      }
      ["lastWrite"]=>
      array(4) {
        ["opTime"]=>
        array(2) {
          ["ts"]=>
          object(MongoDB\BSON\Timestamp)#6 (2) {
            ["increment"]=>
            string(1) "1"
            ["timestamp"]=>
            string(10) "1635478989"
          }
          ["t"]=>
          int(1)
        }
        ["lastWriteDate"]=>
        object(MongoDB\BSON\UTCDateTime)#7 (1) {
          ["milliseconds"]=>
          string(13) "1635478989000"
        }
        ["majorityOpTime"]=>
        array(2) {
          ["ts"]=>
          object(MongoDB\BSON\Timestamp)#8 (2) {
            ["increment"]=>
            string(1) "1"
            ["timestamp"]=>
            string(10) "1635478989"
          }
          ["t"]=>
          int(1)
        }
        ["majorityWriteDate"]=>
        object(MongoDB\BSON\UTCDateTime)#9 (1) {
          ["milliseconds"]=>
          string(13) "1635478989000"
        }
      }
      ["maxBsonObjectSize"]=>
      int(16777216)
      ["maxMessageSizeBytes"]=>
      int(48000000)
      ["maxWriteBatchSize"]=>
      int(100000)
      ["localTime"]=>
      object(MongoDB\BSON\UTCDateTime)#10 (1) {
        ["milliseconds"]=>
        string(13) "1635478992136"
      }
      ["logicalSessionTimeoutMinutes"]=>
      int(30)
      ["connectionId"]=>
      int(3)
      ["minWireVersion"]=>
      int(0)
      ["maxWireVersion"]=>
      int(13)
      ["readOnly"]=>
      bool(false)
      ["ok"]=>
      float(1)
      ["$clusterTime"]=>
      array(2) {
        ["clusterTime"]=>
        object(MongoDB\BSON\Timestamp)#11 (2) {
          ["increment"]=>
          string(1) "1"
          ["timestamp"]=>
          string(10) "1635478989"
        }
        ["signature"]=>
        array(2) {
          ["hash"]=>
          object(MongoDB\BSON\Binary)#12 (2) {
            ["data"]=>
            string(20) ""
            ["type"]=>
            int(0)
          }
          ["keyId"]=>
          int(0)
        }
      }
      ["operationTime"]=>
      object(MongoDB\BSON\Timestamp)#13 (2) {
        ["increment"]=>
        string(1) "1"
        ["timestamp"]=>
        string(10) "1635478989"
      }
    }

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.11.0 | Quando o driver está conectado a um balanceador de carga, esse método retorna a resposta do comando `hello` enviada pelo servidor de apoio no handshake de conexão inicial.

### Veja Também

- MongoDB\Driver\ServerDescription::getHelloResponse() - Retorna a resposta "hello" mais recente do servidor
- Comando » hello no manual do MongoDB
- » Especificação de descoberta e monitoramento de servidor

# MongoDB\Driver\Server::getLatency

(mongodb >=1.0.0)

MongoDB\Driver\Server::getLatency — Retorna a latência deste servidor em milissegundos

### Descrição

final public function MongoDB\Driver\Server::getLatency(): ?integer

Retorna a latência deste servidor em milissegundos. Este é o » tempo de ida e volta de um comando `hello` medido pelo cliente .

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a latência deste servidor em milissegundos ou `null` se nenhuma latência tiver sido medida (por exemplo, o cliente está conectado a um balanceador de carga).

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.11.0 | Este método retornará `null` se nenhuma latência tiver sido medida. Nas versões anteriores, um número inteiro sempre era retornado e um valor não definido poderia ser relatado como `-1`.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\Server::getLatency()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017/");
    $server = $manager->selectServer();

    var_dump($server->getLatency());

    ?>

O exemplo acima produzirá algo semelhante a:

    int(592)

### Veja Também

- MongoDB\Driver\Server::getInfo() - Retorna um array de informações que descrevem este servidor
- MongoDB\Driver\ServerDescription::getRoundTripTime() - Retorna o tempo de ida e volta do servidor em milissegundos
- » Especificação de descoberta e monitoramento de servidor

# MongoDB\Driver\Server::getPort

(mongodb >=1.0.0)

MongoDB\Driver\Server::getPort — Retorna a porta na qual este servidor está escutando

### Descrição

final public function MongoDB\Driver\Server::getPort(): int

Retorna a porta na qual este servidor está escutando.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a porta na qual este servidor está escutando.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\Server::getPort()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017/");
    $server = $manager->selectServer();

    var_dump($server->getPort());

    ?>

O exemplo acima produzirá:

    int(27017)

### Veja Também

- MongoDB\Driver\Server::getInfo() - Retorna um array de informações que descrevem este servidor
- MongoDB\Driver\ServerDescription::getPort() - Retorna a porta na qual este servidor está escutando

# MongoDB\Driver\Server::getServerDescription

(mongodb >=1.13.0)

MongoDB\Driver\Server::getServerDescription — Retorna uma descrição para este servidor

### Descrição

final public function MongoDB\Driver\Server::getServerDescription(): MongoDB\Driver\ServerDescription

Retorna um MongoDB\Driver\ServerDescription para este servidor. Este é um objeto de valor imutável que descreverá o servidor no momento em que este método for chamado.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um MongoDB\Driver\ServerDescription para este servidor.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Server::getTags

(mongodb >=1.0.0)

MongoDB\Driver\Server::getTags — Retorna um array de tags que descrevem este servidor em um conjunto de réplicas

### Descrição

final public function MongoDB\Driver\Server::getTags(): array

Retorna um array de » tags usadas para descrever este servidor em um conjunto de réplicas. O array conterá zero ou mais pares de chave e valor string.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array de tags usadas para descrever este servidor em um conjunto de réplicas.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Server::getInfo() - Retorna um array de informações que descrevem este servidor

# MongoDB\Driver\Server::getType

(mongodb >=1.0.0)

MongoDB\Driver\Server::getType — Retorna um número inteiro denotando o tipo deste servidor

### Descrição

final public function MongoDB\Driver\Server::getType(): int

Retorna um int denotando o tipo deste servidor. O valor será correlacionado com uma constante MongoDB\Driver\Server.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um int denotando o tipo deste servidor.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Server::getInfo() - Retorna um array de informações que descrevem este servidor
- MongoDB\Driver\ServerDescription::getType() - Retorna uma string denotando o tipo deste servidor

# MongoDB\Driver\Server::isArbiter

(mongodb >=1.0.0)

MongoDB\Driver\Server::isArbiter — Verifica se este servidor é um membro árbitro de um conjunto de réplicas

### Descrição

final public function MongoDB\Driver\Server::isArbiter(): bool

Retorna se este servidor é um » membro árbitro de um conjunto de réplicas.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se este servidor for um membro árbitro de um conjunto de réplicas ou `false` caso contrário.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Server::getInfo() - Retorna um array de informações que descrevem este servidor

# MongoDB\Driver\Server::isHidden

(mongodb >=1.0.0)

MongoDB\Driver\Server::isHidden — Verifica se este servidor é um membro oculto de um conjunto de réplicas

### Descrição

final public function MongoDB\Driver\Server::isHidden(): bool

Retorna se este servidor é um » membro oculto de um conjunto de réplicas.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se este servidor for um membro oculto de um conjunto de réplicas ou `false` caso contrário.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Server::getInfo() - Retorna um array de informações que descrevem este servidor

# MongoDB\Driver\Server::isPassive

(mongodb >=1.0.0)

MongoDB\Driver\Server::isPassive — Verifica se este servidor é um membro passivo de um conjunto de réplicas

### Descrição

final public function MongoDB\Driver\Server::isPassive(): bool

Retorna se este servidor é um » membro passivo de um conjunto de réplicas (ou seja, sua prioridade é `0` ).

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se este servidor for um membro passivo de um conjunto de réplicas ou `false` caso contrário.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Server::getInfo() - Retorna um array de informações que descrevem este servidor

# MongoDB\Driver\Server::isPrimary

(mongodb >=1.0.0)

MongoDB\Driver\Server::isPrimary — Verifica se este servidor é um membro primário de um conjunto de réplicas

### Descrição

final public function MongoDB\Driver\Server::isPrimary(): bool

Retorna se este servidor é um » membro primário de um conjunto de réplicas.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se este servidor for um membro primário de um conjunto de réplicas ou `false` caso contrário.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Server::getInfo() - Retorna um array de informações que descrevem este servidor

# MongoDB\Driver\Server::isSecondary

(mongodb >=1.0.0)

MongoDB\Driver\Server::isSecondary — Verifica se este servidor é um membro secundário de um conjunto de réplicas

### Descrição

final public function MongoDB\Driver\Server::isSecondary(): bool

Retorna se este servidor é um » membro secundário de um conjunto de réplicas.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se este servidor for um membro secundário de um conjunto de réplicas ou `false` caso contrário.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Server::getInfo() - Retorna um array de informações que descrevem este servidor

## Índice

- MongoDB\Driver\Server::__construct — Cria um novo servidor (não utilizado)
- MongoDB\Driver\Server::executeBulkWrite — Executa uma ou mais operações de gravação neste servidor
- MongoDB\Driver\Server::executeBulkWriteCommand — Executa operações de gravação neste servidor usando o comando bulkWrite
- MongoDB\Driver\Server::executeCommand — Executa um comando de banco de dados neste servidor
- MongoDB\Driver\Server::executeQuery — Executa uma consulta de banco de dados neste servidor
- MongoDB\Driver\Server::executeReadCommand — Executa um comando de banco de dados que lê neste servidor
- MongoDB\Driver\Server::executeReadWriteCommand — Executa um comando de banco de dados que lê e grava neste servidor
- MongoDB\Driver\Server::executeWriteCommand — Executa um comando de banco de dados que grava neste servidor
- MongoDB\Driver\Server::getHost — Retorna o nome do host deste servidor
- MongoDB\Driver\Server::getInfo — Retorna um array de informações que descrevem este servidor
- MongoDB\Driver\Server::getLatency — Retorna a latência deste servidor em milissegundos
- MongoDB\Driver\Server::getPort — Retorna a porta na qual este servidor está escutando
- MongoDB\Driver\Server::getServerDescription — Retorna uma descrição para este servidor
- MongoDB\Driver\Server::getTags — Retorna um array de tags que descrevem este servidor em um conjunto de réplicas
- MongoDB\Driver\Server::getType — Retorna um número inteiro denotando o tipo deste servidor
- MongoDB\Driver\Server::isArbiter — Verifica se este servidor é um membro árbitro de um conjunto de réplicas
- MongoDB\Driver\Server::isHidden — Verifica se este servidor é um membro oculto de um conjunto de réplicas
- MongoDB\Driver\Server::isPassive — Verifica se este servidor é um membro passivo de um conjunto de réplicas
- MongoDB\Driver\Server::isPrimary — Verifica se este servidor é um membro primário de um conjunto de réplicas
- MongoDB\Driver\Server::isSecondary — Verifica se este servidor é um membro secundário de um conjunto de réplicas

# A classe MongoDB\Driver\ServerDescription

(mongodb >=1.13.0)

## Introdução

A classe MongoDB\Driver\ServerDescription é um objeto de valor que representa um servidor ao qual o driver está conectado. Instâncias desta classe são retornadas pelos métodos MongoDB\Driver\Server::getServerDescription() e MongoDB\Driver\Monitoring\ServerChangedEvent.

## Resumo da classe

final class MongoDB\Driver\ServerDescription {
/* Constantes */
const string TYPE_UNKNOWN = "Unknown";
const string TYPE_STANDALONE = "Standalone";
const string TYPE_MONGOS = "Mongos";
const string TYPE_POSSIBLE_PRIMARY = "PossiblePrimary";
const string TYPE_RS_PRIMARY = "RSPrimary";
const string TYPE_RS_SECONDARY = "RSSecondary";
const string TYPE_RS_ARBITER = "RSArbiter";
const string TYPE_RS_OTHER = "RSOther";
const string TYPE_RS_GHOST = "RSGhost";
const string TYPE_LOAD_BALANCER = "LoadBalancer";
/* Métodos */
final public function getHelloResponse(): array
final public function getHost(): string
final public function getLastUpdateTime(): int
final public function getPort(): int
final public function getRoundTripTime(): ?int
final public function getType(): string
}

## Constantes predefinidas

`MongoDB\Driver\ServerDescription::TYPE_UNKNOWN`
  Tipo de servidor desconhecido, retornada por MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_STANDALONE`
  Tipo de servidor autônomo, retornada por MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_MONGOS`
  Tipo de servidor Mongos, retornada por MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_POSSIBLE_PRIMARY`
  Tipo de servidor conjunto de réplicas, possivelmente primário, retornada por MongoDB\Driver\ServerDescription::getType(). Um servidor pode ser identificado como um possível primário se ainda não tiver sido verificado, mas outra memória do conjunto de réplicas pensa que é o primário.
`MongoDB\Driver\ServerDescription::TYPE_RS_PRIMARY`
  Tipo de servidor conjunto de réplicas primário, retornada por MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_RS_SECONDARY`
  Tipo de servidor conjunto de réplicas secundário, retornada por MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_RS_ARBITER`
  Tipo de servidor conjunto de réplicas árbitro, retornada por MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_RS_OTHER`
  Tipo de servidor conjunto de réplicas outros, retornada por MongoDB\Driver\ServerDescription::getType(). Esses servidores podem estar ocultos, inicializando ou recuperando. Eles não podem ser consultados, mas suas listas de hosts são úteis para descobrir a configuração atual do conjunto de réplicas.
`MongoDB\Driver\ServerDescription::TYPE_RS_GHOST`
  Tipo de servidor conjunto de réplicas fantasma, retornada por MongoDB\Driver\ServerDescription::getType(). Os servidores podem ser identificados como tal em pelo menos três situações: brevemente durante a inicialização do servidor; em um conjunto de réplicas não inicializado; ou quando o servidor é evitado (ou seja, removido da configuração do conjunto de réplicas). Eles não podem ser consultados, nem sua lista de hosts pode ser usada para descobrir a configuração atual do conjunto de réplicas; entretanto, o cliente pode monitorar este servidor na esperança de que ele faça a transição para um estado mais útil.
`MongoDB\Driver\ServerDescription::TYPE_LOAD_BALANCER`
  Tipo de servidor balanceador de carga, retornada por MongoDB\Driver\ServerDescription::getType().

# MongoDB\Driver\ServerDescription::getHelloResponse

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getHelloResponse — Retorna a resposta "hello" mais recente do servidor

### Descrição

final public function MongoDB\Driver\ServerDescription::getHelloResponse(): array

Retorna um array de informações que descrevem o servidor. Este array é derivado da resposta mais recento ao comando » hello (no momento em que MongoDB\Driver\ServerDescription foi construído) obtida através do » monitoramento do servidor.

> Nota: Quando o driver estiver conectado a um balanceador de carga, esse método retornará um array vazio, pois os balanceadores de carga não são monitorados. Isso contrasta com MongoDB\Driver\Server::getInfo(), que retornaria a resposta do comando » hello do servidor de apoio no handshake de conexão inicial.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array de informações que descrevem o servidor.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Server::getInfo() - Retorna um array de informações que descrevem este servidor
- Comando » hello no manual do MongoDB
- » Especificação de descoberta e monitoramento de servidor

# MongoDB\Driver\ServerDescription::getHost

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getHost — Retorna o nome do host deste servidor

### Descrição

final public function MongoDB\Driver\ServerDescription::getHost(): string

Retorna o nome do host deste servidor.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o nome do host deste servidor.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Server::getHost() - Retorna o nome do host deste servidor

# MongoDB\Driver\ServerDescription::getLastUpdateTime

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getLastUpdateTime — Retorna o horário da última atualização do servidor em microssegundos

### Descrição

final public function MongoDB\Driver\ServerDescription::getLastUpdateTime(): int

Retorna o horário da última atualização do servidor em microssegundos.

> Nota: O valor retornado é um timestamp monotônico, que começa em um ponto arbitrário. Como tal, só é adequado comparar com outros valores de retorno de MongoDB\Driver\ServerDescription::getLastUpdateTime().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o horário da última atualização do servidor em microssegundos.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\ServerDescription::getPort

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getPort — Retorna a porta na qual este servidor está escutando

### Descrição

final public function MongoDB\Driver\ServerDescription::getPort(): int

Retorna a porta na qual este servidor está escutando.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a porta na qual este servidor está escutando.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Server::getPort() - Retorna a porta na qual este servidor está escutando

# MongoDB\Driver\ServerDescription::getRoundTripTime

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getRoundTripTime — Retorna o tempo de ida e volta do servidor em milissegundos

### Descrição

final public function MongoDB\Driver\ServerDescription::getRoundTripTime(): ?int

Retorna o tempo de ida e volta do servidor em milissegundos. Esta é a medida do cliente sobre a duração de um comando » hello.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o tempo de ida e volta do servidor em milissegundos.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Server::getLatency() - Retorna a latência deste servidor em milissegundos

# MongoDB\Driver\ServerDescription::getType

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getType — Retorna uma string denotando o tipo deste servidor

### Descrição

final public function MongoDB\Driver\ServerDescription::getType(): string

Retorna uma string denotando o tipo deste servidor. O valor será correlacionado com uma constante MongoDB\Driver\ServerDescription.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string denotando o tipo deste servidor.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Server::getType() - Retorna um número inteiro denotando o tipo deste servidor

## Índice

- MongoDB\Driver\ServerDescription::getHelloResponse — Retorna a resposta "hello" mais recente do servidor
- MongoDB\Driver\ServerDescription::getHost — Retorna o nome do host deste servidor
- MongoDB\Driver\ServerDescription::getLastUpdateTime — Retorna o horário da última atualização do servidor em microssegundos
- MongoDB\Driver\ServerDescription::getPort — Retorna a porta na qual este servidor está escutando
- MongoDB\Driver\ServerDescription::getRoundTripTime — Retorna o tempo de ida e volta do servidor em milissegundos
- MongoDB\Driver\ServerDescription::getType — Retorna uma string denotando o tipo deste servidor

# A classe MongoDB\Driver\TopologyDescription

(mongodb >=1.13.0)

## Introdução

A classe MongoDB\Driver\TopologyDescription é um objeto de valor que representa uma topologia à qual o driver está conectado. As instâncias desta classe são retornadas pelos métodos MongoDB\Driver\Monitoring\TopologyChangedEvent.

## Resumo da classe

final class MongoDB\Driver\TopologyDescription {
/* Constantes */
const string TYPE_UNKNOWN = "Unknown";
const string TYPE_SINGLE = "Single";
const string TYPE_SHARDED = "Sharded";
const string TYPE_REPLICA_SET_NO_PRIMARY = "ReplicaSetNoPrimary";
const string TYPE_REPLICA_SET_WITH_PRIMARY = "ReplicaSetWithPrimary";
const string TYPE_LOAD_BALANCED = "LoadBalanced";
/* Métodos */
final public function getServers(): array
final public function getType(): string
final public function hasReadableServer(?MongoDB\Driver\ReadPreference `$readPreference` = `null`): bool
final public function hasWritableServer(): bool
}

## Constantes predefinidas

`MongoDB\Driver\TopologyDescription::TYPE_UNKNOWN`
  Tipo de topologia desconhecido, retornada por MongoDB\Driver\TopologyDescription::getType().
`MongoDB\Driver\TopologyDescription::TYPE_SINGLE`
  Servidor único (ou seja, conexão direta), retornada por MongoDB\Driver\TopologyDescription::getType().
`MongoDB\Driver\TopologyDescription::TYPE_SHARDED`
  Cluster fragmentado, retornada por MongoDB\Driver\TopologyDescription::getType().
`MongoDB\Driver\TopologyDescription::TYPE_REPLICA_SET_NO_PRIMARY`
  Conjunto de réplicas sem servidor primário, retornada por MongoDB\Driver\TopologyDescription::getType().
`MongoDB\Driver\TopologyDescription::TYPE_REPLICA_SET_WITH_PRIMARY`
  Conjunto de réplicas com um servidor primário, retornada por MongoDB\Driver\TopologyDescription::getType().
`MongoDB\Driver\TopologyDescription::TYPE_LOAD_BALANCED`
  Topologia com balanceamento de carga, retornada por MongoDB\Driver\TopologyDescription::getType().

# MongoDB\Driver\TopologyDescription::getServers

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::getServers — Retorna os servidores na topologia

### Descrição

final public function MongoDB\Driver\TopologyDescription::getServers(): array

Retorna um array de objetos MongoDB\Driver\ServerDescription correspondentes aos servidores conhecidos na topologia.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array de objetos MongoDB\Driver\ServerDescription correspondentes aos servidores conhecidos na topologia.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\TopologyDescription::getType

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::getType — Retorna uma string denotando o tipo desta topologia

### Descrição

final public function MongoDB\Driver\TopologyDescription::getType(): string

Retorna uma string denotando o tipo desta topologia. O valor será correlacionado com uma constante MongoDB\Driver\TopologyDescription.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string denotando o tipo desta topologia.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\TopologyDescription::hasReadableServer

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::hasReadableServer — Retorna se a topologia possui um servidor para leitura

### Descrição

final public function MongoDB\Driver\TopologyDescription::hasReadableServer(?MongoDB\Driver\ReadPreference `$readPreference` = `null`): bool

Retorna se a topologia possui um servidor para leitura ou, se `readPreference` for especificado, um servidor que corresponda à preferência de leitura especificada.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna se a topologia possui um servidor para leitura ou, se `readPreference` for especificado, um servidor que corresponda à preferência de leitura especificada.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\TopologyDescription::hasWritableServer

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::hasWritableServer — Retorna se a topologia possui um servidor para gravação

### Descrição

final public function MongoDB\Driver\TopologyDescription::hasWritableServer(): bool

Retorna se a topologia possui um servidor para gravação.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna se a topologia possui um servidor para gravação.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

## Índice

- MongoDB\Driver\TopologyDescription::getServers — Retorna os servidores na topologia
- MongoDB\Driver\TopologyDescription::getType — Retorna uma string denotando o tipo desta topologia
- MongoDB\Driver\TopologyDescription::hasReadableServer — Retorna se a topologia possui um servidor para leitura
- MongoDB\Driver\TopologyDescription::hasWritableServer — Retorna se a topologia possui um servidor para gravação

# A classe MongoDB\Driver\WriteConcernError

(mongodb >=1.0.0)

## Introdução

A classe MongoDB\Driver\WriteConcernError encapsula informações sobre um erro de preocupação de gravação e pode ser retornada por MongoDB\Driver\WriteResult::getWriteConcernError().

## Resumo da classe

final class MongoDB\Driver\WriteConcernError {
/* Propriedades */
public readonly string $message;
public readonly int $code;
public readonly ?object $info;
/* Métodos */
final public function getCode(): int
final public function getInfo(): ?object
final public function getMessage(): string
}

## Propriedades

message
  The error message.
code
  The error code.
info
  Additional information for the error, or `null` if not available.

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.3.0 | Adicionadas propriedades públicas readonly.

# MongoDB\Driver\WriteConcernError::getCode

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcernError::getCode — Retorna o código de erro do WriteConcernError

### Descrição

final public function MongoDB\Driver\WriteConcernError::getCode(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o código de erro do WriteConcernError.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\WriteConcernError::getCode()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(2, 1);

    try {
        $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteConcernError()->getCode());
    }

    ?>

O exemplo acima produzirá algo semelhante a:

    int(64)

### Veja Também

- » Referência de Preocupação de Gravação

# MongoDB\Driver\WriteConcernError::getInfo

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcernError::getInfo — Retorna documento de metadados para WriteConcernError

### Descrição

final public function MongoDB\Driver\WriteConcernError::getInfo(): ?object

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o documento de metadados para WriteConcernError ou `null` se nenhum metadado estiver disponível.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\WriteConcernError::getInfo()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(2, 1);

    try {
        $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteConcernError()->getInfo());
    }

    ?>

O exemplo acima produzirá algo semelhante a:

    object(stdClass)#1 (1) {
      ["wtimeout"]=>
      bool(true)
    }

### Veja Também

- » Referência de Preocupação de Gravação

# MongoDB\Driver\WriteConcernError::getMessage

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcernError::getMessage — Retorna a mensagem de erro do WriteConcernError

### Descrição

final public function MongoDB\Driver\WriteConcernError::getMessage(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a mensagem de erro do WriteConcernError.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\WriteConcernError::getMessage()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(2, 1);

    try {
        $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteConcernError()->getMessage());
    }

    ?>

O exemplo acima produzirá algo semelhante a:

    string(33) "waiting for replication timed out"

### Veja Também

- » Referência de Preocupação de Gravação

## Índice

- MongoDB\Driver\WriteConcernError::getCode — Retorna o código de erro do WriteConcernError
- MongoDB\Driver\WriteConcernError::getInfo — Retorna documento de metadados para WriteConcernError
- MongoDB\Driver\WriteConcernError::getMessage — Retorna a mensagem de erro do WriteConcernError

# A classe MongoDB\Driver\WriteError

(mongodb >=1.0.0)

## Introdução

A classe MongoDB\Driver\WriteError encapsula informações sobre um erro de gravação e pode ser retornada como um elemento de array de MongoDB\Driver\WriteResult::getWriteErrors().

## Resumo da classe

final class MongoDB\Driver\WriteError {
/* Propriedades */
public readonly string $message;
public readonly int $code;
public readonly int $index;
public readonly ?object $info;
/* Métodos */
final public function getCode(): int
final public function getIndex(): int
final public function getInfo(): ?object
final public function getMessage(): string
}

## Propriedades

message
  A mensagem de erro.
code
  O código de erro.
index
  O índice da operação de gravação dentro do MongoDB\Driver\BulkWrite que causou o erro.
info
  Informações adicionais sobre o erro, ou `null` se não disponíveis.

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.3.0 | Adicionadas propriedades públicas readonly.

# MongoDB\Driver\WriteError::getCode

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getCode — Retorna o código de erro do WriteError

### Descrição

final public function MongoDB\Driver\WriteError::getCode(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o código de erro do WriteError.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\WriteError::getCode()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 1]);

    try {
        $manager->executeBulkWrite('db.collection', $bulk);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteErrors()[0]->getCode());
    }

    ?>

O exemplo acima produzirá algo semelhante a:

    int(11000)

# MongoDB\Driver\WriteError::getIndex

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getIndex — Retorna o índice da operação de gravação correspondente a este WriteError

### Descrição

final public function MongoDB\Driver\WriteError::getIndex(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o índice da operação de gravação (de MongoDB\Driver\BulkWrite) correspondente a este WriteError.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\WriteError::getIndex()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 1]);

    try {
        $manager->executeBulkWrite('db.collection', $bulk);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteErrors()[0]->getIndex());
    }

    ?>

O exemplo acima produzirá algo semelhante a:

    int(1)

### Veja Também

- MongoDB\Driver\BulkWrite

# MongoDB\Driver\WriteError::getInfo

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getInfo — Retorna documento de metadados para WriteError

### Descrição

final public function MongoDB\Driver\WriteError::getInfo(): ?object

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o documento de metadados para WriteError ou `null` se nenhum metadado estiver disponível.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\WriteError::getMessage

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getMessage — Retorna a mensagem de erro do WriteError

### Descrição

final public function MongoDB\Driver\WriteError::getMessage(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a mensagem de erro do WriteError.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\WriteError::getMessage()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 1]);

    try {
        $manager->executeBulkWrite('db.collection', $bulk);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteErrors()[0]->getMessage());
    }

    ?>

O exemplo acima produzirá algo semelhante a:

    string(70) "E11000 duplicate key error index: db.collection.$_id_ dup key: { : 1 }"

## Índice

- MongoDB\Driver\WriteError::getCode — Retorna o código de erro do WriteError
- MongoDB\Driver\WriteError::getIndex — Retorna o índice da operação de gravação correspondente a este WriteError
- MongoDB\Driver\WriteError::getInfo — Retorna documento de metadados para WriteError
- MongoDB\Driver\WriteError::getMessage — Retorna a mensagem de erro do WriteError

# A classe MongoDB\Driver\WriteResult

(mongodb >=1.0.0)

## Introdução

A classe MongoDB\Driver\WriteResult encapsula informações sobre um MongoDB\Driver\BulkWrite executado e pode ser retornada por MongoDB\Driver\Manager::executeBulkWrite().

## Resumo da classe

final class MongoDB\Driver\WriteResult {
/* Propriedades */
public readonly ?int $insertedCount;
public readonly ?int $matchedCount;
public readonly ?int $modifiedCount;
public readonly ?int $deletedCount;
public readonly ?int $upsertedCount;
public readonly MongoDB\Driver\Server $server;
public readonly array $upsertedIds;
public readonly array $writeErrors;
public readonly ?MongoDB\Driver\WriteConcernError $writeConcernError;
public readonly ?MongoDB\Driver\WriteConcern $writeConcern;
public readonly array $errorReplies;
/* Métodos */
final public function getDeletedCount(): int
final public function getInsertedCount(): int
final public function getMatchedCount(): int
final public function getModifiedCount(): int
final public function getServer(): MongoDB\Driver\Server
final public function getUpsertedCount(): int
final public function getUpsertedIds(): array
final public function getWriteConcernError(): ?MongoDB\Driver\WriteConcernError
final public function getWriteErrors(): array
final public function isAcknowledged(): bool
}

## Propriedades

insertedCount
  O número de documentos inseridos (excluindo upserts), ou `null` se o responsável pela gravação não solicitou confirmação.
matchedCount
  O número de documentos correspondentes às operações de atualização e substituição, ou `null` se a entidade responsável pela gravação não solicitou confirmação.
modifiedCount
  O número de documentos modificados por operações de atualização e substituição, ou `null` se a entidade gravadora não solicitou confirmação ou se o servidor não reportou esta informação.
deletedCount
  O número de documentos excluídos, ou `null` se a entidade responsável pela gravação não solicitou confirmação.
upsertedCount
  O número de documentos inseridos ou `null` se a entidade responsável pela gravação não solicitou confirmação.
server
  O servidor que executou a gravação em massa.
upsertedIds
  Um array de valores `_id` para documentos inseridos e atualizados (upsert). As chaves do array corresponderão ao índice da operação de gravação de MongoDB\Driver\BulkWrite.
writeErrors
  Um array de MongoDB\Driver\WriteErrors para quaisquer erros de gravação que ocorreram durante a execução.
writeConcernError
  O erro MongoDB\Driver\WriteConcernError que ocorreu, ou `null` se nenhum erro de write concern ocorreu.
writeConcern
  O MongoDB\Driver\WriteConcern usado para a gravação em massa, ou `null` se não estiver disponível.
errorReplies
  Um array de documentos de resposta de erro do servidor.

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.3.0 | Adicionadas propriedades públicas readonly.

# MongoDB\Driver\WriteResult::getDeletedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getDeletedCount — Retorna o número de documentos excluídos

### Descrição

final public function MongoDB\Driver\WriteResult::getDeletedCount(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número de documentos excluídos.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\LogicException se a escrita não foi reconhecida.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Este método agora lança uma exceção quando chamado para uma escrita não reconhecida em vez de retornar `null`.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\WriteResult::getDeletedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getDeletedCount());

    ?>

O exemplo acima produzirá:

    int(1)

### Veja Também

- MongoDB\Driver\WriteResult::isAcknowledged() - Retorna se a gravação foi reconhecida

# MongoDB\Driver\WriteResult::getInsertedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getInsertedCount — Retorna o número de documentos inseridos (excluindo inserções de atualização)

### Descrição

final public function MongoDB\Driver\WriteResult::getInsertedCount(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número de documentos inseridos (excluindo inserções de atualização).

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\LogicException se a escrita não foi reconhecida.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Este método agora lança uma exceção quando chamado para uma escrita não reconhecida em vez de retornar `null`.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\WriteResult::getInsertedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getInsertedCount());

    ?>

O exemplo acima produzirá:

    int(1)

### Veja Também

- MongoDB\Driver\WriteResult::isAcknowledged() - Retorna se a gravação foi reconhecida

# MongoDB\Driver\WriteResult::getMatchedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getMatchedCount — Retorna o número de documentos selecionados para atualização

### Descrição

final public function MongoDB\Driver\WriteResult::getMatchedCount(): int

Se a operação de atualização não resultar em nenhuma alteração no documento (por exemplo, definir o valor de um campo para seu valor atual), a contagem correspondida poderá ser maior que o valor retornado por MongoDB\Driver\WriteResult::getModifiedCount().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número de documentos selecionados para atualização.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\LogicException se a escrita não foi reconhecida.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Este método agora lança uma exceção quando chamado para uma escrita não reconhecida em vez de retornar `null`.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\WriteResult::getMatchedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getMatchedCount());

    ?>

O exemplo acima produzirá:

    int(1)

### Veja Também

- MongoDB\Driver\WriteResult::getModifiedCount() - Retorna o número de documentos existentes atualizados
- MongoDB\Driver\WriteResult::isAcknowledged() - Retorna se a gravação foi reconhecida

# MongoDB\Driver\WriteResult::getModifiedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getModifiedCount — Retorna o número de documentos existentes atualizados

### Descrição

final public function MongoDB\Driver\WriteResult::getModifiedCount(): int

Se a operação de atualização não resultar em nenhuma alteração no documento (por exemplo, definir o valor de um campo para seu valor atual), a contagem modificada poderá ser menor que o valor retornado por MongoDB\Driver\WriteResult::getMatchedCount().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número de documentos existentes atualizados.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\LogicException se a escrita não foi reconhecida.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Este método agora lança uma exceção quando chamado para uma escrita não reconhecida em vez de retornar `null`.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\WriteResult::getModifiedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getModifiedCount());

    ?>

O exemplo acima produzirá:

    int(1)

### Veja Também

- MongoDB\Driver\WriteResult::getMatchedCount() - Retorna o número de documentos selecionados para atualização
- MongoDB\Driver\WriteResult::isAcknowledged() - Retorna se a gravação foi reconhecida

# MongoDB\Driver\WriteResult::getServer

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getServer — Retorna o servidor associado a este resultado de gravação

### Descrição

final public function MongoDB\Driver\WriteResult::getServer(): MongoDB\Driver\Server

Retorna o MongoDB\Driver\Server associado a este resultado de gravação. Este é o servidor que executou o MongoDB\Driver\BulkWrite.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o MongoDB\Driver\Server associado a este resultado de gravação.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\WriteResult::getServer()

    <?php

    $manager = new MongoDB\Driver\Manager;
    $server = $manager->selectServer();

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $result = $server->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getServer() == $server);

    ?>

O exemplo acima produzirá:

    bool(true)

### Veja Também

- MongoDB\Driver\Server

# MongoDB\Driver\WriteResult::getUpsertedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getUpsertedCount — Retorna o número de documentos inseridos por uma inserção de atualização

### Descrição

final public function MongoDB\Driver\WriteResult::getUpsertedCount(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número de documentos inseridos por uma inserção de atualização.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\LogicException se a escrita não foi reconhecida.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Este método agora lança uma exceção quando chamado para uma escrita não reconhecida em vez de retornar `null`.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\WriteResult::getUpsertedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getUpsertedCount());

    ?>

O exemplo acima produzirá:

    int(2)

### Veja Também

- MongoDB\Driver\WriteResult::getUpsertedIds() - Retorna um array de identificadores para documentos inseridos por atualização
- MongoDB\Driver\WriteResult::isAcknowledged() - Retorna se a gravação foi reconhecida

# MongoDB\Driver\WriteResult::getUpsertedIds

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getUpsertedIds — Retorna um array de identificadores para documentos inseridos por atualização

### Descrição

final public function MongoDB\Driver\WriteResult::getUpsertedIds(): array

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array de identificadores (ou seja, valores de campo `"_id"`) para documentos inseridos por atualização. As chaves do array corresponderão ao índice da operação de gravação (de MongoDB\Driver\BulkWrite) responsável pela inserção de atualização.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\WriteResult::getUpsertedIds()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getUpsertedIds());

    ?>

O exemplo acima produzirá algo semelhante a:

    array(2) {
      [2]=>
      object(MongoDB\BSON\ObjectId)#4 (1) {
        ["oid"]=>
        string(24) "580e62a224f2302f191b880b"
      }
      [3]=>
      object(MongoDB\BSON\ObjectId)#5 (1) {
        ["oid"]=>
        string(24) "580e62a224f2302f191b880c"
      }
    }

### Veja Também

- MongoDB\Driver\WriteResult::getUpsertedCount() - Retorna o número de documentos inseridos por uma inserção de atualização
- MongoDB\Driver\WriteResult::isAcknowledged() - Retorna se a gravação foi reconhecida

# MongoDB\Driver\WriteResult::getWriteConcernError

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getWriteConcernError — Retorna qualquer erro de gravação ocorrido

### Descrição

final public function MongoDB\Driver\WriteResult::getWriteConcernError(): ?MongoDB\Driver\WriteConcernError

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um MongoDB\Driver\WriteConcernError se um erro de preocupação de gravação foi encontrado durante a operação de gravação ou `null` caso contrário.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\WriteResult::getWriteConcernError()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(2, 1);

    try {
        $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteConcernError());
    }

    ?>

O exemplo acima produzirá algo semelhante a:

    object(MongoDB\Driver\WriteConcernError)#6 (3) {
      ["message"]=>
      string(33) "waiting for replication timed out"
      ["code"]=>
      int(64)
      ["info"]=>
      object(stdClass)#7 (1) {
        ["wtimeout"]=>
        bool(true)
      }
    }

### Veja Também

- MongoDB\Driver\WriteConcern
- » Referência de Preocupação de Gravação

# MongoDB\Driver\WriteResult::getWriteErrors

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getWriteErrors — Retorna quaisquer erros de gravação ocorridos

### Descrição

final public function MongoDB\Driver\WriteResult::getWriteErrors(): array

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array de objetos MongoDB\Driver\WriteError para quaisquer erros de gravação encontrados durante a operação de gravação. O array estará vazio se não tiverem ocorrido erros de gravação.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 MongoDB\Driver\WriteResult::getWriteErrors() com um único erro

    <?php

    $manager = new MongoDB\Driver\Manager;

    /* Por padrão, as operações de gravação em massa são executadas em série e de forma ordenada,
     * e a execução será interrompida após o primeiro erro.
     */
    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 2]);
    $bulk->insert(['_id' => 2]);
    $bulk->insert(['_id' => 3]);
    $bulk->insert(['_id' => 4]);
    $bulk->insert(['_id' => 4]);

    try {
        $result = $manager->executeBulkWrite('db.collection', $bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteErrors());
    }

    ?>

O exemplo acima produzirá algo semelhante a:

    array(1) {
      [0]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(81) "E11000 duplicate key error collection: db.collection index: _id_ dup key: { : 2 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(2)
        ["info"]=>
        NULL
      }
    }

Exemplo #2 MongoDB\Driver\WriteResult::getWriteErrors() com múltiplos erros

    <?php

    $manager = new MongoDB\Driver\Manager;

    /* A opção "ordered" pode ser usada para permitir que operações de gravação
     * em massa continuem em execução após o primeiro erro ser encontrado.
     */
    $bulk = new MongoDB\Driver\BulkWrite(['ordered' => false]);
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 2]);
    $bulk->insert(['_id' => 2]);
    $bulk->insert(['_id' => 3]);
    $bulk->insert(['_id' => 4]);
    $bulk->insert(['_id' => 4]);

    try {
        $result = $manager->executeBulkWrite('db.collection', $bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteErrors());
    }

    ?>

O exemplo acima produzirá algo semelhante a:

    array(2) {
      [0]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(81) "E11000 duplicate key error collection: db.collection index: _id_ dup key: { : 2 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(2)
        ["info"]=>
        NULL
      }
      [1]=>
      object(MongoDB\Driver\WriteError)#6 (4) {
        ["message"]=>
        string(81) "E11000 duplicate key error collection: db.collection index: _id_ dup key: { : 4 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(5)
        ["info"]=>
        NULL
      }
    }

### Veja Também

- MongoDB\Driver\WriteError

# MongoDB\Driver\WriteResult::isAcknowledged

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::isAcknowledged — Retorna se a gravação foi reconhecida

### Descrição

final public function MongoDB\Driver\WriteResult::isAcknowledged(): bool

Se a gravação for confirmada, outros campos de contagem estarão disponíveis no objeto MongoDB\Driver\WriteResult.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se a gravação foi reconhecida ou `false` caso contrário.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 MongoDB\Driver\WriteResult::isAcknowledged() com preocupação de gravação reconhecida

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->isAcknowledged());

    ?>

O exemplo acima produzirá:

    bool(true)

Exemplo #2 MongoDB\Driver\WriteResult::isAcknowledged() com preocupação de gravação não reconhecida

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(0);

    $result = $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);

    var_dump($result->isAcknowledged());

    ?>

O exemplo acima produzirá:

    bool(false)

### Veja Também

- MongoDB\Driver\WriteConcern
- » Referência de Preocupação de Gravação

## Índice

- MongoDB\Driver\WriteResult::getDeletedCount — Retorna o número de documentos excluídos
- MongoDB\Driver\WriteResult::getInsertedCount — Retorna o número de documentos inseridos (excluindo inserções de atualização)
- MongoDB\Driver\WriteResult::getMatchedCount — Retorna o número de documentos selecionados para atualização
- MongoDB\Driver\WriteResult::getModifiedCount — Retorna o número de documentos existentes atualizados
- MongoDB\Driver\WriteResult::getServer — Retorna o servidor associado a este resultado de gravação
- MongoDB\Driver\WriteResult::getUpsertedCount — Retorna o número de documentos inseridos por uma inserção de atualização
- MongoDB\Driver\WriteResult::getUpsertedIds — Retorna um array de identificadores para documentos inseridos por atualização
- MongoDB\Driver\WriteResult::getWriteConcernError — Retorna qualquer erro de gravação ocorrido
- MongoDB\Driver\WriteResult::getWriteErrors — Retorna quaisquer erros de gravação ocorridos
- MongoDB\Driver\WriteResult::isAcknowledged — Retorna se a gravação foi reconhecida

# A classe MongoDB\Driver\BulkWriteCommandResult

(mongodb >=2.1.0)

## Introdução

A classe MongoDB\Driver\BulkWriteCommandResult encapsula informações sobre um MongoDB\Driver\BulkWriteCommand executado e é retornada por MongoDB\Driver\Manager::executeBulkWriteCommand().

## Resumo da classe

final class MongoDB\Driver\BulkWriteCommandResult {
/* Métodos */
final public function getDeletedCount(): int
final public function getDeleteResults(): ?MongoDB\BSON\Document
final public function getInsertedCount(): int
final public function getInsertResults(): ?MongoDB\BSON\Document
final public function getMatchedCount(): int
final public function getModifiedCount(): int
final public function getUpdateResults(): ?MongoDB\BSON\Document
final public function getUpsertedCount(): int
final public function isAcknowledged(): bool
}

# MongoDB\Driver\BulkWriteCommandResult::getDeletedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getDeletedCount — Retorna o número de documentos excluídos

### Descrição

final public function MongoDB\Driver\BulkWriteCommandResult::getDeletedCount(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número total de documentos excluídos por todas as operações.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\LogicException se a escrita não foi reconhecida.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\BulkWriteCommandResult::getDeletedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getDeletedCount());

    ?>

O exemplo acima produzirá:

    int(3)

### Veja Também

- MongoDB\Driver\BulkWriteCommandResult::getDeleteResults() - Retorna resultados detalhados para exclusões bem-sucedidas
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Retorna se a gravação foi reconhecida

# MongoDB\Driver\BulkWriteCommandResult::getDeleteResults

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getDeleteResults — Retorna resultados detalhados para exclusões bem-sucedidas

### Descrição

final public function MongoDB\Driver\BulkWriteCommandResult::getDeleteResults(): ?MongoDB\BSON\Document

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um documento contendo o resultado de cada operação de exclusão bem-sucedida, ou `null` se resultados detalhados não foram solicitados. As chaves do documento corresponderão ao índice da operação de gravação de MongoDB\Driver\BulkWriteCommand.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\LogicException se a escrita não foi reconhecida.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\BulkWriteCommandResult::getDeleteResults()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand(['verboseResults' => true]);
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getDeleteResults()->toPHP());

    ?>

O exemplo acima produzirá algo semelhante a:

    object(stdClass)#7 (1) {
      ["4"]=>
      object(stdClass)#6 (1) {
        ["deletedCount"]=>
        object(MongoDB\BSON\Int64)#5 (1) {
          ["integer"]=>
          string(1) "3"
        }
      }
    }

### Veja Também

- MongoDB\Driver\BulkWriteCommandResult::getDeletedCount() - Retorna o número de documentos excluídos
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Retorna se a gravação foi reconhecida

# MongoDB\Driver\BulkWriteCommandResult::getInsertedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getInsertedCount — Retorna o número de documentos inseridos

### Descrição

final public function MongoDB\Driver\BulkWriteCommandResult::getInsertedCount(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número total de documentos inseridos (excluindo upserts) por todas as operações.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\LogicException se a escrita não foi reconhecida.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\BulkWriteCommandResult::getInsertedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getInsertedCount());

    ?>

O exemplo acima produzirá:

    int(1)

### Veja Também

- MongoDB\Driver\BulkWriteCommandResult::getInsertResults() - Retorna resultados detalhados para inserções bem-sucedidas
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Retorna se a gravação foi reconhecida

# MongoDB\Driver\BulkWriteCommandResult::getInsertResults

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getInsertResults — Retorna resultados detalhados para inserções bem-sucedidas

### Descrição

final public function MongoDB\Driver\BulkWriteCommandResult::getInsertResults(): ?MongoDB\BSON\Document

Como os campos `_id` para documentos inseridos são gerados pela extensão, o valor de `insertedId` em cada resultado corresponderá ao valor de retorno de MongoDB\Driver\BulkWriteCommand::insertOne() para a operação de inserção correspondente.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um documento contendo o resultado de cada operação de inserção bem-sucedida ou `null` se resultados detalhados não foram solicitados. As chaves do documento corresponderão ao índice da operação de gravação de MongoDB\Driver\BulkWriteCommand.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\LogicException se a escrita não foi reconhecida.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\BulkWriteCommandResult::getInsertResults()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand(['verboseResults' => true]);

    $generatedId = $bulk->insertOne('db.coll', ['x' => 1]);

    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($generatedId);

    var_dump($result->getInsertResults()->toPHP());

    ?>

O exemplo acima produzirá algo semelhante a:

    object(MongoDB\BSON\ObjectId)#3 (1) {
      ["oid"]=>
      string(24) "67f7ee69783dcce702097b41"
    }
    object(stdClass)#8 (1) {
      ["0"]=>
      object(stdClass)#7 (1) {
        ["insertedId"]=>
        object(MongoDB\BSON\ObjectId)#6 (1) {
          ["oid"]=>
          string(24) "67f7ee69783dcce702097b41"
        }
      }
    }

### Veja Também

- MongoDB\Driver\BulkWriteCommandResult::getInsertedCount() - Retorna o número de documentos inseridos
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Retorna se a gravação foi reconhecida
- MongoDB\Driver\BulkWriteCommand::insertOne() - Adiciona uma operação insertOne

# MongoDB\Driver\BulkWriteCommandResult::getMatchedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getMatchedCount — Retorna o número de documentos selecionados para atualização

### Descrição

final public function MongoDB\Driver\BulkWriteCommandResult::getMatchedCount(): int

Se a operação de atualização não resultar em nenhuma alteração no documento (por exemplo, definindo o valor de um campo para seu valor atual), a contagem correspondente poderá ser maior que o valor retornado por MongoDB\Driver\BulkWriteCommandResult::getModifiedCount().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número total de documentos selecionados para atualização por todas as operações.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\LogicException se a escrita não foi reconhecida.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\BulkWriteCommandResult::getMatchedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getMatchedCount());

    ?>

O exemplo acima produzirá:

    int(1)

### Veja Também

- MongoDB\Driver\BulkWriteCommandResult::getModifiedCount() - Retorna o número de documentos existentes atualizados
- MongoDB\Driver\BulkWriteCommandResult::getUpdateResults() - Retorna resultados detalhados para atualizações bem-sucedidas
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Retorna se a gravação foi reconhecida

# MongoDB\Driver\BulkWriteCommandResult::getModifiedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getModifiedCount — Retorna o número de documentos existentes atualizados

### Descrição

final public function MongoDB\Driver\BulkWriteCommandResult::getModifiedCount(): int

Se a operação de atualização não resultar em nenhuma alteração no documento (por exemplo, definindo o valor de um campo para seu valor atual), a contagem modificada poderá ser menor que o valor retornado por MongoDB\Driver\BulkWriteCommandResult::getMatchedCount().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número total de documentos existentes atualizados por todas as operações.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\LogicException se a escrita não foi reconhecida.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\BulkWriteCommandResult::getModifiedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getModifiedCount());

    ?>

O exemplo acima produzirá:

    int(1)

### Veja Também

- MongoDB\Driver\BulkWriteCommandResult::getMatchedCount() - Retorna o número de documentos selecionados para atualização
- MongoDB\Driver\BulkWriteCommandResult::getUpdateResults() - Retorna resultados detalhados para atualizações bem-sucedidas
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Retorna se a gravação foi reconhecida

# MongoDB\Driver\BulkWriteCommandResult::getUpdateResults

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getUpdateResults — Retorna resultados detalhados para atualizações bem-sucedidas

### Descrição

final public function MongoDB\Driver\BulkWriteCommandResult::getUpdateResults(): ?MongoDB\BSON\Document

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um documento contendo o resultado de cada operação de atualização bem-sucedida ou `null` se resultados detalhados não foram solicitados. As chaves do documento corresponderão ao índice da operação de gravação de MongoDB\Driver\BulkWriteCommand.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\LogicException se a escrita não foi reconhecida.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\BulkWriteCommandResult::getUpdateResults()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand(['verboseResults' => true]);
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getUpdateResults()->toPHP());

    ?>

O exemplo acima produzirá algo semelhante a:

    object(stdClass)#16 (3) {
      ["1"]=>
      object(stdClass)#7 (2) {
        ["matchedCount"]=>
        object(MongoDB\BSON\Int64)#5 (1) {
          ["integer"]=>
          string(1) "1"
        }
        ["modifiedCount"]=>
        object(MongoDB\BSON\Int64)#6 (1) {
          ["integer"]=>
          string(1) "1"
        }
      }
      ["2"]=>
      object(stdClass)#11 (3) {
        ["matchedCount"]=>
        object(MongoDB\BSON\Int64)#8 (1) {
          ["integer"]=>
          string(1) "1"
        }
        ["modifiedCount"]=>
        object(MongoDB\BSON\Int64)#9 (1) {
          ["integer"]=>
          string(1) "0"
        }
        ["upsertedId"]=>
        object(MongoDB\BSON\ObjectId)#10 (1) {
          ["oid"]=>
          string(24) "67f7eb9b1f198bbcb880d575"
        }
      }
      ["3"]=>
      object(stdClass)#15 (3) {
        ["matchedCount"]=>
        object(MongoDB\BSON\Int64)#12 (1) {
          ["integer"]=>
          string(1) "1"
        }
        ["modifiedCount"]=>
        object(MongoDB\BSON\Int64)#13 (1) {
          ["integer"]=>
          string(1) "0"
        }
        ["upsertedId"]=>
        object(MongoDB\BSON\ObjectId)#14 (1) {
          ["oid"]=>
          string(24) "67f7eb9b1f198bbcb880d576"
        }
      }
    }

### Veja Também

- MongoDB\Driver\BulkWriteCommandResult::getMatchedCount() - Retorna o número de documentos selecionados para atualização
- MongoDB\Driver\BulkWriteCommandResult::getModifiedCount() - Retorna o número de documentos existentes atualizados
- MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount() - Retorna o número de documentos inseridos ou atualizados
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Retorna se a gravação foi reconhecida

# MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount — Retorna o número de documentos inseridos ou atualizados

### Descrição

final public function MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número total de documentos inseridos ou atualizados por todas as operações.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma exceção MongoDB\Driver\Exception\LogicException se a escrita não foi reconhecida.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getUpsertedCount());

    ?>

O exemplo acima produzirá:

    int(2)

### Veja Também

- MongoDB\Driver\BulkWriteCommandResult::getUpdateResults() - Retorna resultados detalhados para atualizações bem-sucedidas
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Retorna se a gravação foi reconhecida

# MongoDB\Driver\BulkWriteCommandResult::isAcknowledged

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::isAcknowledged — Retorna se a gravação foi reconhecida

### Descrição

final public function MongoDB\Driver\BulkWriteCommandResult::isAcknowledged(): bool

Se a gravação for confirmada, outros campos estarão disponíveis no objeto MongoDB\Driver\BulkWriteCommandResult.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se a gravação foi confirmada e `false` caso contrário.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() com preocupação de gravação reconhecida

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->isAcknowledged());

    ?>

O exemplo acima produzirá:

    bool(true)

Exemplo #2 MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() com preocupação de gravação não reconhecida

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand(['ordered' => false]);
    $bulk->insertOne('db.coll', ['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(0);

    $result = $manager->executeBulkWriteCommand($bulk, ['writeConcern' => $writeConcern]);

    var_dump($result->isAcknowledged());

    ?>

O exemplo acima produzirá:

    bool(false)

### Veja Também

- MongoDB\Driver\WriteConcern
- » Referência de Preocupação de Gravação

## Índice

- MongoDB\Driver\BulkWriteCommandResult::getDeletedCount — Retorna o número de documentos excluídos
- MongoDB\Driver\BulkWriteCommandResult::getDeleteResults — Retorna resultados detalhados para exclusões bem-sucedidas
- MongoDB\Driver\BulkWriteCommandResult::getInsertedCount — Retorna o número de documentos inseridos
- MongoDB\Driver\BulkWriteCommandResult::getInsertResults — Retorna resultados detalhados para inserções bem-sucedidas
- MongoDB\Driver\BulkWriteCommandResult::getMatchedCount — Retorna o número de documentos selecionados para atualização
- MongoDB\Driver\BulkWriteCommandResult::getModifiedCount — Retorna o número de documentos existentes atualizados
- MongoDB\Driver\BulkWriteCommandResult::getUpdateResults — Retorna resultados detalhados para atualizações bem-sucedidas
- MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount — Retorna o número de documentos inseridos ou atualizados
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged — Retorna se a gravação foi reconhecida

# Classes e Funções BSON do MongoDB

## Índice

- Funções
- MongoDB\BSON\Document
- MongoDB\BSON\PackedArray
- MongoDB\BSON\Iterator
- MongoDB\BSON\Binary
- MongoDB\BSON\VectorType
- MongoDB\BSON\Decimal128
- MongoDB\BSON\Javascript
- MongoDB\BSON\MaxKey
- MongoDB\BSON\MinKey
- MongoDB\BSON\ObjectId
- MongoDB\BSON\Regex
- MongoDB\BSON\Timestamp
- MongoDB\BSON\UTCDateTime
- MongoDB\BSON\Type
- MongoDB\BSON\Persistable
- MongoDB\BSON\Serializable
- MongoDB\BSON\Unserializable
- MongoDB\BSON\BinaryInterface
- MongoDB\BSON\Decimal128Interface
- MongoDB\BSON\JavascriptInterface
- MongoDB\BSON\MaxKeyInterface
- MongoDB\BSON\MinKeyInterface
- MongoDB\BSON\ObjectIdInterface
- MongoDB\BSON\RegexInterface
- MongoDB\BSON\TimestampInterface
- MongoDB\BSON\UTCDateTimeInterface
- MongoDB\BSON\DBPointer
- MongoDB\BSON\Int64
- MongoDB\BSON\Symbol
- MongoDB\BSON\Undefined

# Funções

# MongoDB\BSON\fromJSON

(mongodb >=1.0.0)

MongoDB\BSON\fromJSON — Retorna a representação BSON de um valor JSON

Aviso

Esta função foi DESCONTINUADA a partir da versão 1.20.0 da extensão, e foi removida na 2.0. As aplicações devem usar MongoDB\BSON\Document::fromJSON() em seu lugar.

### Descrição

function MongoDB\BSON\fromJSON(string `$json`): string

Converte uma string » JSON estendida para sua representação BSON.

### Parâmetros

`json` (string)
  Valor JSON a ser convertido.

### Valor Retornado

O documento BSON serializado como uma string binária.

### Erros/Exceções

- Lança uma MongoDB\Driver\Exception\UnexpectedValueException se o valor JSON não puder ser convertido para BSON (ex.: devido a erro de sintaxe).

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Esta função foi removida.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\fromJSON()

    <?php

    $json = '{ "_id": { "$oid": "563143b280d2387c91807965" } }';
    $bson = MongoDB\BSON\fromJSON($json);
    $value = MongoDB\BSON\toPHP($bson);
    var_dump($value);

    ?>

O exemplo acima produzirá:

    object(stdClass)#2 (1) {
      ["_id"]=>
      object(MongoDB\BSON\ObjectId)#1 (1) {
        ["oid"]=>
        string(24) "563143b280d2387c91807965"
      }
    }

### Veja Também

- MongoDB\BSON\Document::fromJSON() - Constrói uma nova instância de documento a partir de uma string JSON
- MongoDB\BSON\toJSON() - Retorna a representação JSON Estendida Legada de um valor BSON
- » JSON Estendido do MongoDB
- » BSON do MongoDB

# MongoDB\BSON\fromPHP

(mongodb >=1.0.0)

MongoDB\BSON\fromPHP — Retorna a representação BSON de um valor PHP

Aviso

Esta função foi DESCONTINUADA a partir da versão 1.20.0 da extensão, e foi removida na 2.0. As aplicações devem usar MongoDB\BSON\Document::fromPHP() em seu lugar.

### Descrição

function MongoDB\BSON\fromPHP(array|object `$value`): string

Serializa um array ou objeto (ex.: documento) para sua representação » BSON. A string binária retornada irá descrever um documento BSON.

### Parâmetros

`value` (array|object)
  O valor PHP a ser serializado.

### Valor Retornado

O documento BSON serializado como uma string binária.

### Erros/Exceções

- Lança uma MongoDB\Driver\Exception\UnexpectedValueException se o valor PHP não puder ser convertido para BSON. Possíveis motivos incluem, por exemplo, encontrar uma instância inesperada de MongoDB\BSON\Type ou falha do método MongoDB\BSON\Serializable::bsonSerialize() em retornar um array ou uma stdClass.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Esta função foi removida.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\fromPHP()

    <?php

    $bson = MongoDB\BSON\fromPHP(['foo' => 1]);
    echo bin2hex($bson), "\n";

    ?>

O exemplo acima produzirá:

    0e00000010666f6f000100000000

### Veja Também

- MongoDB\BSON\Document::fromPHP() - Constrói uma nova instância de documento a partir de dados PHP
- MongoDB\BSON\toPHP() - Retorna a representação PHP de um valor BSON
- » BSON do MongoDB
- Dados Persistentes

# MongoDB\BSON\toCanonicalExtendedJSON

(mongodb >=1.3.0)

MongoDB\BSON\toCanonicalExtendedJSON — Retorna a representação JSON Estendida Canônica de um valor BSON

Aviso

Esta função foi DESCONTINUADA a partir da versão 1.20.0 da extensão, e foi removida na 2.0. As aplicações devem usar MongoDB\BSON\Document::toCanonicalExtendedJSON() em seu lugar.

### Descrição

function MongoDB\BSON\toCanonicalExtendedJSON(string `$bson`): string

Converte uma string BSON em sua representação » JSON Estendida Canônica. O formato canônico prefere a fidelidade de tipo em detrimento do resultado conciso e é mais adequado para produzir resultado que possa ser convertido de volta para BSON sem qualquer perda de informação de tipo (por exemplo, os tipos numéricos permanecerão diferenciados).

### Parâmetros

`bson` (string)
  Valor BSON a ser convertido.

### Valor Retornado

O valor JSON convertido.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\UnexpectedValueException se a entrada não contiver exatamente um documento BSON. Os possíveis motivos incluem, mas não estão limitados a, BSON inválido, dados extras (depois de ler um documento BSON) ou um erro inesperado da » libbson.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Esta função foi removida.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\toCanonicalExtendedJSON()

    <?php

    $documents = [
        [ 'null' => null ],
        [ 'boolean' => true ],
        [ 'string' => 'foo' ],
        [ 'int32' => 123 ],
        [ 'int64' => 4294967295 ],
        [ 'double' => 1.0, ],
        [ 'nan' => NAN ],
        [ 'pos_inf' => INF ],
        [ 'neg_inf' => -INF ],
        [ 'array' => [ 'foo', 'bar' ]],
        [ 'document' => [ 'foo' => 'bar' ]],
        [ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
        [ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
        [ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
        [ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
        [ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
        [ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
        [ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
        [ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
        [ 'minkey' => new MongoDB\BSON\MinKey ],
        [ 'maxkey' => new MongoDB\BSON\MaxKey ],
    ];

    foreach ($documents as $document) {
        $bson = MongoDB\BSON\fromPHP($document);
        echo MongoDB\BSON\toCanonicalExtendedJSON($bson), "\n";
    }

    ?>

O exemplo acima produzirá:

    { "null" : null }
    { "boolean" : true }
    { "string" : "foo" }
    { "int32" : { "$numberInt" : "123" } }
    { "int64" : { "$numberLong" : "4294967295"} }
    { "double" : { "$numberDouble" : "1.0" } }
    { "nan" : { "$numberDouble" : "NaN" } }
    { "pos_inf" : { "$numberDouble" : "Infinity" } }
    { "neg_inf" : { "$numberDouble" : "-Infinity" } }
    { "array" : [ "foo", "bar" ] }
    { "document" : { "foo" : "bar" } }
    { "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
    { "dec128" : { "$numberDecimal" : "1234.5678" } }
    { "binary" : { "$binary" : { "base64": "Zm9v", "subType" : "00" } } }
    { "date" : { "$date" : { "$numberLong" : "1445990400000" } } }
    { "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
    { "regex" : { "$regularExpression" : { "pattern" : "pattern", "options" : "i" } } }
    { "code" : { "$code" : "function() { return 1; }" } }
    { "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : { "$numberInt" : "1" } } } }
    { "minkey" : { "$minKey" : 1 } }
    { "maxkey" : { "$maxKey" : 1 } }

### Veja Também

- MongoDB\BSON\Document::fromJSON() - Constrói uma nova instância de documento a partir de uma string JSON
- MongoDB\BSON\Document::toCanonicalExtendedJSON() - Retorna a representação JSON estendida canônica do documento BSON
- MongoDB\BSON\fromJSON() - Retorna a representação BSON de um valor JSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Retorna a representação JSON Estendida Relaxada de um valor BSON
- » Especificação do JSON Estendido
- » BSON do MongoDB

# MongoDB\BSON\toJSON

(mongodb >=1.0.0)

MongoDB\BSON\toJSON — Retorna a representação JSON Estendida Legada de um valor BSON

Aviso

Esta função foi DESCONTINUADA a partir da versão 1.20.0 da extensão, e foi removida na 2.0. As aplicações devem usar MongoDB\BSON\Document::toCanonicalExtendedJSON() ou MongoDB\BSON\Document::toRelaxedExtendedJSON() em seu lugar.

### Descrição

function MongoDB\BSON\toJSON(string `$bson`): string

Converte uma string BSON na sua representação » JSON Estendida Legada

> Nota: Existem vários formatos JSON para representar BSON. Esta função implementa o "modo estrito" definido em » JSON Estendido MongoDB, que foi substituído pelos formatos canônicos e relaxados definidos na » Especificação JSON estendida e implementada por MongoDB\BSON\toCanonicalExtendedJSON() e MongoDB\BSON\toRelaxedExtendedJSON(), respectivamente.

Aviso

» JSON não suporta `NAN` e `INF` e o formato JSON Estendido Legado do MongoDB não define uma representação alternativa para estes valores (» libbson irá produzir literais `nan` e `inf`, que podem não ser interpretados como JSON válido). Ao trabalhar com BSON que possa conter números não finitos, devem ser usados os métodos MongoDB\BSON\toCanonicalExtendedJSON() ou MongoDB\BSON\toRelaxedExtendedJSON().

### Parâmetros

`bson` (string)
  Valor BSON a ser convertido.

### Valor Retornado

O valor JSON convertido.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\UnexpectedValueException se a entrada não contiver exatamente um documento BSON. Os possíveis motivos incluem, mas não estão limitados a, BSON inválido, dados extras (depois de ler um documento BSON) ou um erro inesperado da » libbson.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Esta função foi removida.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\toJSON()

    <?php

    $documents = [
        [ 'null' => null ],
        [ 'boolean' => true ],
        [ 'string' => 'foo' ],
        [ 'int32' => 123 ],
        [ 'int64' => 4294967295 ],
        [ 'double' => 1.0, ],
        [ 'nan' => NAN ],
        [ 'pos_inf' => INF ],
        [ 'neg_inf' => -INF ],
        [ 'array' => [ 'foo', 'bar' ]],
        [ 'document' => [ 'foo' => 'bar' ]],
        [ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
        [ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
        [ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
        [ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
        [ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
        [ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
        [ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
        [ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
        [ 'minkey' => new MongoDB\BSON\MinKey ],
        [ 'maxkey' => new MongoDB\BSON\MaxKey ],
    ];

    foreach ($documents as $document) {
        $bson = MongoDB\BSON\fromPHP($document);
        echo MongoDB\BSON\toJSON($bson), "\n";
    }

    ?>

O exemplo acima produzirá:

    { "null" : null }
    { "boolean" : true }
    { "string" : "foo" }
    { "int32" : 123 }
    { "int64" : 4294967295 }
    { "double" : 1.0 }
    { "nan" : nan }
    { "pos_inf" : inf }
    { "neg_inf" : -inf }
    { "array" : [ "foo", "bar" ] }
    { "document" : { "foo" : "bar" } }
    { "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
    { "dec128" : { "$numberDecimal" : "1234.5678" } }
    { "binary" : { "$binary" : "Zm9v", "$type" : "00" } }
    { "date" : { "$date" : 1445990400000 } }
    { "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
    { "regex" : { "$regex" : "pattern", "$options" : "i" } }
    { "code" : { "$code" : "function() { return 1; }" } }
    { "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : 1 } } }
    { "minkey" : { "$minKey" : 1 } }
    { "maxkey" : { "$maxKey" : 1 } }

### Veja Também

- MongoDB\BSON\fromJSON() - Retorna a representação BSON de um valor JSON
- MongoDB\BSON\toCanonicalExtendedJSON() - Retorna a representação JSON Estendida Canônica de um valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Retorna a representação JSON Estendida Relaxada de um valor BSON
- » JSON Estendido do MongoDB
- » BSON do MongoDB

# MongoDB\BSON\toPHP

(mongodb >=1.0.0)

MongoDB\BSON\toPHP — Retorna a representação PHP de um valor BSON

Aviso

Esta função foi DESCONTINUADA a partir da versão 1.20.0 da extensão, e foi removida na 2.0. As aplicações devem usar MongoDB\BSON\Document::toPHP() em seu lugar.

### Descrição

function MongoDB\BSON\toPHP(string `$bson`, array `$typeMap` = array()): array|object

Desserializa um documento BSON (ou seja, string binária) para sua representação PHP. O parâmetro `typeMap` pode ser usado para controlar os tipos PHP usados ​​para converter arrays e documentos BSON (raiz e incorporados).

Aviso

Os documentos BSON tecnicamente podem conter chaves duplicadas porque os documentos são armazenados como uma lista de pares chave-valor; no entanto, as aplicações devem evitar a geração de documentos com chaves duplicadas, pois o comportamento do servidor e do driver pode ser indefinido. Como os objetos e arrays do PHP não podem ter chaves duplicadas, os dados também podem ser perdidos ao decodificar um documento BSON com chaves duplicadas.

### Parâmetros

`bson` (string)
  Valor BSON a ser desserializado.
`typeMap` (array)
  Configuração de mapeamento de tipos.

### Valor Retornado

O valor PHP desserializado.

### Erros/Exceções

- Lança uma MongoDB\Driver\Exception\InvalidArgumentException se uma classe no mapa de tipos não puder ser instanciada ou não implementar MongoDB\BSON\Unserializable.
- Lança uma exceção MongoDB\Driver\Exception\UnexpectedValueException se a entrada não contiver exatamente um documento BSON. Os possíveis motivos incluem, mas não estão limitados a, BSON inválido, dados extras (depois de ler um documento BSON) ou um erro inesperado da » libbson.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Esta função foi removida.
PECL mongodb 1.4.0 | Se a entrada contiver um tipo BSON obsoleto e sem suporte, a extensão não registrará mais um aviso no registro de depuração, mas criará um objeto que representa esse tipo.
PECL mongodb 1.3.2 | MongoDB\Driver\Exception\UnexpectedValueException não será mais lançada se a entrada contiver um tipo BSON obsoleto e sem suporte. Esses tipos serão ignorados (como eram nas versões anteriores a 1.3.0), embora a extensão agora grave um alerta no registro de depuração (consulte: mongodb.debug).
PECL mongodb 1.3.0 | MongoDB\Driver\Exception\UnexpectedValueException será lançada se a entrada contiver um tipo BSON obsoleto e não suportado. Anteriormente, esses tipos eram ignorados.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\toPHP()

    <?php

    $bson = hex2bin('0e00000010666f6f000100000000');
    $value = MongoDB\BSON\toPHP($bson);
    var_dump($value);

    ?>

O exemplo acima produzirá:

    object(stdClass)#1 (1) {
      ["foo"]=>
      int(1)
    }

### Veja Também

- MongoDB\BSON\Document::toPHP() - Retorna a representação PHP do documento BSON
- MongoDB\BSON\fromPHP() - Retorna a representação BSON de um valor PHP
- » BSON do MongoDB
- Dados Persistentes

# MongoDB\BSON\toRelaxedExtendedJSON

(mongodb >=1.3.0)

MongoDB\BSON\toRelaxedExtendedJSON — Retorna a representação JSON Estendida Relaxada de um valor BSON

Aviso

Esta função foi DESCONTINUADA a partir da versão 1.20.0 da extensão, e foi removida na 2.0. As aplicações devem usar MongoDB\BSON\Document::toRelaxedExtendedJSON() em seu lugar.

### Descrição

function MongoDB\BSON\toRelaxedExtendedJSON(string `$bson`): string

Converte uma string BSON em sua representação » JSON Estendida Relaxada. O formato relaxado prefere o uso de primitivos do tipo JSON em detrimento da fidelidade do tipo e é mais adequado para produzir resultados que podem ser facilmente consumidos por APIs da web e por humanos.

### Parâmetros

`bson` (string)
  Valor BSON a ser convertido.

### Valor Retornado

O valor JSON convertido.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\UnexpectedValueException se a entrada não contiver exatamente um documento BSON. Os possíveis motivos incluem, mas não estão limitados a, BSON inválido, dados extras (depois de ler um documento BSON) ou um erro inesperado da » libbson.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Esta função foi removida.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\toRelaxedExtendedJSON()

    <?php

    $documents = [
        [ 'null' => null ],
        [ 'boolean' => true ],
        [ 'string' => 'foo' ],
        [ 'int32' => 123 ],
        [ 'int64' => 4294967295 ],
        [ 'double' => 1.0, ],
        [ 'nan' => NAN ],
        [ 'pos_inf' => INF ],
        [ 'neg_inf' => -INF ],
        [ 'array' => [ 'foo', 'bar' ]],
        [ 'document' => [ 'foo' => 'bar' ]],
        [ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
        [ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
        [ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
        [ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
        [ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
        [ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
        [ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
        [ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
        [ 'minkey' => new MongoDB\BSON\MinKey ],
        [ 'maxkey' => new MongoDB\BSON\MaxKey ],
    ];

    foreach ($documents as $document) {
        $bson = MongoDB\BSON\fromPHP($document);
        echo MongoDB\BSON\toRelaxedExtendedJSON($bson), "\n";
    }

    ?>

O exemplo acima produzirá:

    { "null" : null }
    { "boolean" : true }
    { "string" : "foo" }
    { "int32" : 123 }
    { "int64" : 4294967295 }
    { "double" : 1.0 }
    { "nan" : { "$numberDouble" : "NaN" } }
    { "pos_inf" : { "$numberDouble" : "Infinity" } }
    { "neg_inf" : { "$numberDouble" : "-Infinity" } }
    { "array" : [ "foo", "bar" ] }
    { "document" : { "foo" : "bar" } }
    { "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
    { "dec128" : { "$numberDecimal" : "1234.5678" } }
    { "binary" : { "$binary" : { "base64": "Zm9v", "subType" : "00" } } }
    { "date" : { "$date" : "2015-10-28T00:00:00Z" } }
    { "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
    { "regex" : { "$regularExpression" : { "pattern" : "pattern", "options" : "i" } } }
    { "code" : { "$code" : "function() { return 1; }" } }
    { "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : 1 } } }
    { "minkey" : { "$minKey" : 1 } }
    { "maxkey" : { "$maxKey" : 1 } }

### Veja Também

- MongoDB\BSON\Document::fromJSON() - Constrói uma nova instância de documento a partir de uma string JSON
- MongoDB\BSON\Document::toRelaxedExtendedJSON() - Retorna a representação JSON Estentida Relaxada do documento BSON
- MongoDB\BSON\fromJSON() - Retorna a representação BSON de um valor JSON
- MongoDB\BSON\toCanonicalExtendedJSON() - Retorna a representação JSON Estendida Canônica de um valor BSON
- » JSON Estendido
- » BSON do MongoDB

## Índice

- MongoDB\BSON\fromJSON — Retorna a representação BSON de um valor JSON
- MongoDB\BSON\fromPHP — Retorna a representação BSON de um valor PHP
- MongoDB\BSON\toCanonicalExtendedJSON — Retorna a representação JSON Estendida Canônica de um valor BSON
- MongoDB\BSON\toJSON — Retorna a representação JSON Estendida Legada de um valor BSON
- MongoDB\BSON\toPHP — Retorna a representação PHP de um valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON — Retorna a representação JSON Estendida Relaxada de um valor BSON

# A classe MongoDB\BSON\Document

(mongodb >=1.16.0)

## Introdução

Representa um documento BSON. Esta classe é usada ao ler dados como BSON bruto e não pode ser modificada.

## Resumo da classe

final class MongoDB\BSON\Document implements MongoDB\BSON\Type, ArrayAccess, IteratorAggregate {
/* Métodos */
final private function __construct()
final static public function fromBSON(string `$bson`): MongoDB\BSON\Document
final static public function fromJSON(string `$json`): MongoDB\BSON\Document
final static public function fromPHP(object|array `$value`): MongoDB\BSON\Document
final public function get(string `$key`): mixed
final public function getIterator(): MongoDB\BSON\Iterator
final public function has(string `$key`): bool
final public function offsetExists(mixed `$key`): bool
final public function offsetGet(mixed `$key`): mixed
final public function offsetSet(mixed `$key`, mixed `$value`): void
final public function offsetUnset(mixed `$key`): void
final public function toCanonicalExtendedJSON(): string
final public function toPHP(?array `$typeMap` = `null`): array|object
final public function toRelaxedExtendedJSON(): string
final public function __toString(): string
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Esta classe não implementa mais a interface Serializable.
PECL mongodb 1.17.0 | Implementa MongoDB\BSON\Type.

# MongoDB\BSON\Document::__construct

(mongodb >=1.16.0)

MongoDB\BSON\Document::__construct — Constrói um novo documento BSON (não utilizado)

### Descrição

final private function MongoDB\BSON\Document::__construct()

Objetos MongoDB\BSON\Document são criados através de métodos estáticos de fabricação e não podem ser instanciados diretamente.

### Parâmetros

Esta função não possui parâmetros.

### Veja Também

- MongoDB\BSON\Document::fromPHP() - Constrói uma nova instância de documento a partir de dados PHP
- MongoDB\BSON\Document::fromBSON() - Constrói uma nova instância de documento a partir de uma string BSON
- MongoDB\BSON\Document::fromJSON() - Constrói uma nova instância de documento a partir de uma string JSON
- » Tipos BSON

# MongoDB\BSON\Document::fromBSON

(mongodb >=1.16.0)

MongoDB\BSON\Document::fromBSON — Constrói uma nova instância de documento a partir de uma string BSON

### Descrição

final static public function MongoDB\BSON\Document::fromBSON(string `$bson`): MongoDB\BSON\Document

### Parâmetros

`bson` (string)
  Uma string contendo um documento no formato BSON.

### Valor Retornado

Retorna uma nova instância de MongoDB\BSON\Document.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança MongoDB\Driver\Exception\UnexpectedValueException se `bson` for uma string BSON inválida ou se contiver mais de um documento.

### Veja Também

- MongoDB\BSON\Document::fromPHP() - Constrói uma nova instância de documento a partir de dados PHP
- MongoDB\BSON\Document::fromJSON() - Constrói uma nova instância de documento a partir de uma string JSON
- » Tipos BSON

# MongoDB\BSON\Document::fromJSON

(mongodb >=1.16.0)

MongoDB\BSON\Document::fromJSON — Constrói uma nova instância de documento a partir de uma string JSON

### Descrição

final static public function MongoDB\BSON\Document::fromJSON(string `$json`): MongoDB\BSON\Document

Converte uma string » JSON estendida na sua representação BSON.

### Parâmetros

`json` (string)
  Valor JSON a ser convertido.

### Valor Retornado

Retorna uma nova instância de MongoDB\BSON\Document.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança MongoDB\Driver\Exception\UnexpectedValueException se o valor JSON não puder ser convertido para um documento BSON (por exemplo, devido a um erro de sintaxe).

### Veja Também

- MongoDB\BSON\Document::fromPHP() - Constrói uma nova instância de documento a partir de dados PHP
- MongoDB\BSON\Document::fromBSON() - Constrói uma nova instância de documento a partir de uma string BSON
- » JSON Estendido do MongoDB
- » Tipos BSON

# MongoDB\BSON\Document::fromPHP

(mongodb >=1.16.0)

MongoDB\BSON\Document::fromPHP — Constrói uma nova instância de documento a partir de dados PHP

### Descrição

final static public function MongoDB\BSON\Document::fromPHP(object|array `$value`): MongoDB\BSON\Document

### Parâmetros

`value` (object|array)
  Um objeto ou array do PHP contendo o documento. Ao passar um array com chaves numéricas, os valores numéricos são convertidos para strings e usados como chaves do documento.

### Valor Retornado

Retorna uma nova instância de MongoDB\BSON\Document.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\BSON\Document::fromBSON() - Constrói uma nova instância de documento a partir de uma string BSON
- MongoDB\BSON\Document::fromJSON() - Constrói uma nova instância de documento a partir de uma string JSON
- » Tipos BSON

# MongoDB\BSON\Document::get

(mongodb >=1.16.0)

MongoDB\BSON\Document::get — Retorna o valor de uma chave no documento

### Descrição

final public function MongoDB\BSON\Document::get(string `$key`): mixed

### Parâmetros

`key` (string)
  A chave a ser recuperada do documento.

### Valor Retornado

Retorna o valor associado com a chave informada. Se a chave não estiver presente no documento, uma exceção é lançada.

> Nota: Ao encontrar um valor codificado como inteiro de 64 bits no documento BSON, o valor de retorno deste método será uma instância de MongoDB\BSON\Int64.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma MongoDB\Driver\Exception\RuntimeException se a chave não estiver presente no documento.

### Veja Também

- MongoDB\BSON\Document::has() - Informa se uma chave está presente no documento
- » Tipos BSON

# MongoDB\BSON\Document::getIterator

(mongodb >=1.16.0)

MongoDB\BSON\Document::getIterator — Retorna um iterador para o documento BSON

### Descrição

final public function MongoDB\BSON\Document::getIterator(): MongoDB\BSON\Iterator

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma instância de MongoDB\BSON\Iterator que pode ser usada para iterar sobre todas as chaves do documento.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma MongoDB\Driver\Exception\UnexpectedValueException se o iterador BSON não puder ser inicializado.

### Veja Também

- » Tipos BSON

# MongoDB\BSON\Document::has

(mongodb >=1.16.0)

MongoDB\BSON\Document::has — Informa se uma chave está presente no documento

### Descrição

final public function MongoDB\BSON\Document::has(string `$key`): bool

### Parâmetros

`key` (string)
  A chave a ser procurada no documento.

### Valor Retornado

Retorna `true` se a chave estiver presente no documento ou `false` caso contrário.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\BSON\Document::get() - Retorna o valor de uma chave no documento
- » Tipos BSON

# MongoDB\BSON\Document::offsetExists

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetExists — Informa se uma chave está presente no documento

### Descrição

final public function MongoDB\BSON\Document::offsetExists(mixed `$key`): bool

### Parâmetros

`key`
  A chave a ser procurada no documento.

### Valor Retornado

Retorna `true` se a chave estiver presente no documento ou `false` caso contrário.

### Veja Também

- ArrayAccess::offsetExists() - Verifica se uma posição existe
- MongoDB\BSON\Document::has() - Informa se uma chave está presente no documento

# MongoDB\BSON\Document::offsetGet

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetGet — Retorna o valor de uma chave no documento

### Descrição

final public function MongoDB\BSON\Document::offsetGet(mixed `$key`): mixed

### Parâmetros

`key`
  A chave a ser recuperada do documento.

### Valor Retornado

Retorna o valor associado com a chave informada. Se a chave não estiver presente no documento, uma exceção é lançada.

> Nota: Ao encontrar um valor codificado como inteiro de 64 bits no documento BSON, o valor de retorno deste método será uma instância de MongoDB\BSON\Int64.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma MongoDB\Driver\Exception\RuntimeException se a chave não estiver presente no documento.

### Veja Também

- ArrayAccess::offsetGet() - Posição a ser obtida
- MongoDB\BSON\Document::get() - Retorna o valor de uma chave no documento

# MongoDB\BSON\Document::offsetSet

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetSet — Implementação de ArrayAccess

### Descrição

final public function MongoDB\BSON\Document::offsetSet(mixed `$key`, mixed `$value`): void

Define o valor na chave especificada `key` para `value`.

### Parâmetros

`key`
  O índice da chave sendo definida.
`value`
  O novo valor para a chave `key`.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Sempre lança uma MongoDB\Driver\Exception\LogicException.

# MongoDB\BSON\Document::offsetUnset

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetUnset — Implementação de ArrayAccess

### Descrição

final public function MongoDB\BSON\Document::offsetUnset(mixed `$key`): void

Remove a definição do valor no índice especificado.

### Parâmetros

`key`
  O índice que será removido.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Sempre lança uma MongoDB\Driver\Exception\LogicException.

# MongoDB\BSON\Document::toCanonicalExtendedJSON

(mongodb >=1.16.0)

MongoDB\BSON\Document::toCanonicalExtendedJSON — Retorna a representação JSON estendida canônica do documento BSON

### Descrição

final public function MongoDB\BSON\Document::toCanonicalExtendedJSON(): string

Converte o documento BSON para sua representação » JSON Estendida Canônica O formato canônico prefere a fidelidade de tipo em detrimento da saída concisa e é mais adequado para produzir saída que pode ser convertida de volta para BSON sem qualquer perda de informação de tipo (por exemplo, os tipos numéricos permanecerão diferenciados).

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string contendo a representação » JSON Canônica Estendida do documento BSON.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\Document::toCanonicalExtendedJSON()

    <?php

    $documents = [
        [ 'null' => null ],
        [ 'boolean' => true ],
        [ 'string' => 'foo' ],
        [ 'int32' => 123 ],
        [ 'int64' => 4294967295 ],
        [ 'double' => 1.0 ],
        [ 'nan' => NAN ],
        [ 'pos_inf' => INF ],
        [ 'neg_inf' => -INF ],
        [ 'array' => [ 'foo', 'bar' ]],
        [ 'document' => [ 'foo' => 'bar' ]],
        [ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
        [ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
        [ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
        [ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
        [ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
        [ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
        [ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
        [ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
        [ 'minkey' => new MongoDB\BSON\MinKey ],
        [ 'maxkey' => new MongoDB\BSON\MaxKey ],
    ];

    foreach ($documents as $document) {
        $bson = MongoDB\BSON\Document::fromPHP($document);
        echo $bson->toCanonicalExtendedJSON(), "\n";
    }

    ?>

O exemplo acima produzirá:

    { "null" : null }
    { "boolean" : true }
    { "string" : "foo" }
    { "int32" : { "$numberInt" : "123" } }
    { "int64" : { "$numberLong" : "4294967295"} }
    { "double" : { "$numberDouble" : "1.0" } }
    { "nan" : { "$numberDouble" : "NaN" } }
    { "pos_inf" : { "$numberDouble" : "Infinity" } }
    { "neg_inf" : { "$numberDouble" : "-Infinity" } }
    { "array" : [ "foo", "bar" ] }
    { "document" : { "foo" : "bar" } }
    { "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
    { "dec128" : { "$numberDecimal" : "1234.5678" } }
    { "binary" : { "$binary" : { "base64": "Zm9v", "subType" : "00" } } }
    { "date" : { "$date" : { "$numberLong" : "1445990400000" } } }
    { "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
    { "regex" : { "$regularExpression" : { "pattern" : "pattern", "options" : "i" } } }
    { "code" : { "$code" : "function() { return 1; }" } }
    { "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : { "$numberInt" : "1" } } } }
    { "minkey" : { "$minKey" : 1 } }
    { "maxkey" : { "$maxKey" : 1 } }

### Veja Também

- MongoDB\BSON\Document::fromJSON() - Constrói uma nova instância de documento a partir de uma string JSON
- MongoDB\BSON\Document::toRelaxedExtendedJSON() - Retorna a representação JSON Estentida Relaxada do documento BSON
- MongoDB\BSON\toCanonicalExtendedJSON() - Retorna a representação JSON Estendida Canônica de um valor BSON
- » Especificação de JSON Estendido
- » Tipos BSON

# MongoDB\BSON\Document::toPHP

(mongodb >=1.16.0)

MongoDB\BSON\Document::toPHP — Retorna a representação PHP do documento BSON

### Descrição

final public function MongoDB\BSON\Document::toPHP(?array `$typeMap` = `null`): array|object

Desserializa o documento BSON para sua representação em PHP. O parâmetro `typeMap` pode ser usado para controlar os tipos PHP usados para converter arrays e documentos BSON (tanto nativos quanto integrados).

Aviso

Os documentos BSON tecnicamente podem conter chaves duplicadas porque os documentos são armazenados como uma lista de pares chave-valor; no entanto, as aplicações devem evitar a geração de documentos com chaves duplicadas, pois o comportamento do servidor e do driver pode ser indefinido. Como os objetos e arrays do PHP não podem ter chaves duplicadas, os dados também podem ser perdidos ao decodificar um documento BSON com chaves duplicadas.

### Parâmetros

`typeMap` (array)
  Configuração de mapeamento de tipos.

### Valor Retornado

O valor decodificado em PHP.

> Nota: Ao encontrar um valor codificado como inteiro de 64 bits no documento BSON, o valor de retorno deste método será uma instância de MongoDB\BSON\Int64.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException se uma classe no mapa de tipos não puder ser instanciada ou não implementar a interface MongoDB\BSON\Unserializable.

### Veja Também

- MongoDB\BSON\toPHP() - Retorna a representação PHP de um valor BSON
- » Tipos BSON

# MongoDB\BSON\Document::toRelaxedExtendedJSON

(mongodb >=1.16.0)

MongoDB\BSON\Document::toRelaxedExtendedJSON — Retorna a representação JSON Estentida Relaxada do documento BSON

### Descrição

final public function MongoDB\BSON\Document::toRelaxedExtendedJSON(): string

Converte o documento BSON para sua representação » JSON Estentida Relaxada O formato relaxado prefere o uso de primitivos do tipo JSON em detrimento da fidelidade de tipo e é mais adequado para produzir resultados que podem ser facilmente consumidos por APIs da web e humanos.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string contendo a representação » JSON Estendida Relaxada do documento BSON.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\Document::toRelaxedExtendedJSON()

    <?php

    $documents = [
        [ 'null' => null ],
        [ 'boolean' => true ],
        [ 'string' => 'foo' ],
        [ 'int32' => 123 ],
        [ 'int64' => 4294967295 ],
        [ 'double' => 1.0 ],
        [ 'nan' => NAN ],
        [ 'pos_inf' => INF ],
        [ 'neg_inf' => -INF ],
        [ 'array' => [ 'foo', 'bar' ]],
        [ 'document' => [ 'foo' => 'bar' ]],
        [ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
        [ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
        [ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
        [ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
        [ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
        [ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
        [ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
        [ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
        [ 'minkey' => new MongoDB\BSON\MinKey ],
        [ 'maxkey' => new MongoDB\BSON\MaxKey ],
    ];

    foreach ($documents as $document) {
        $bson = MongoDB\BSON\Document::fromPHP($document);
        echo $bson->toRelaxedExtendedJSON(), "\n";
    }

    ?>

O exemplo acima produzirá:

    { "null" : null }
    { "boolean" : true }
    { "string" : "foo" }
    { "int32" : 123 }
    { "int64" : 4294967295 }
    { "double" : 1.0 }
    { "nan" : { "$numberDouble" : "NaN" } }
    { "pos_inf" : { "$numberDouble" : "Infinity" } }
    { "neg_inf" : { "$numberDouble" : "-Infinity" } }
    { "array" : [ "foo", "bar" ] }
    { "document" : { "foo" : "bar" } }
    { "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
    { "dec128" : { "$numberDecimal" : "1234.5678" } }
    { "binary" : { "$binary" : { "base64": "Zm9v", "subType" : "00" } } }
    { "date" : { "$date" : "2015-10-28T00:00:00Z" } }
    { "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
    { "regex" : { "$regularExpression" : { "pattern" : "pattern", "options" : "i" } } }
    { "code" : { "$code" : "function() { return 1; }" } }
    { "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : 1 } } }
    { "minkey" : { "$minKey" : 1 } }
    { "maxkey" : { "$maxKey" : 1 } }

### Veja Também

- MongoDB\BSON\Document::fromJSON() - Constrói uma nova instância de documento a partir de uma string JSON
- MongoDB\BSON\Document::toCanonicalExtendedJSON() - Retorna a representação JSON estendida canônica do documento BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Retorna a representação JSON Estendida Relaxada de um valor BSON
- » Especificação JSON Estendida
- » Tipos BSON

# MongoDB\BSON\Document::__toString

(mongodb >=1.16.0)

MongoDB\BSON\Document::__toString — Retorna a representação em string deste documento BSON

### Descrição

final public function MongoDB\BSON\Document::__toString(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a representação em string deste documento como BSON.

### Veja Também

- » Tipos BSON

## Índice

- MongoDB\BSON\Document::__construct — Constrói um novo documento BSON (não utilizado)
- MongoDB\BSON\Document::fromBSON — Constrói uma nova instância de documento a partir de uma string BSON
- MongoDB\BSON\Document::fromJSON — Constrói uma nova instância de documento a partir de uma string JSON
- MongoDB\BSON\Document::fromPHP — Constrói uma nova instância de documento a partir de dados PHP
- MongoDB\BSON\Document::get — Retorna o valor de uma chave no documento
- MongoDB\BSON\Document::getIterator — Retorna um iterador para o documento BSON
- MongoDB\BSON\Document::has — Informa se uma chave está presente no documento
- MongoDB\BSON\Document::offsetExists — Informa se uma chave está presente no documento
- MongoDB\BSON\Document::offsetGet — Retorna o valor de uma chave no documento
- MongoDB\BSON\Document::offsetSet — Implementação de ArrayAccess
- MongoDB\BSON\Document::offsetUnset — Implementação de ArrayAccess
- MongoDB\BSON\Document::toCanonicalExtendedJSON — Retorna a representação JSON estendida canônica do documento BSON
- MongoDB\BSON\Document::toPHP — Retorna a representação PHP do documento BSON
- MongoDB\BSON\Document::toRelaxedExtendedJSON — Retorna a representação JSON Estentida Relaxada do documento BSON
- MongoDB\BSON\Document::__toString — Retorna a representação em string deste documento BSON

# A classe MongoDB\BSON\PackedArray

(mongodb >=1.16.0)

## Introdução

Representa um array BSON. Esta classe é usada ao ler dados como BSON bruto e não pode ser modificada.

## Resumo da classe

final class MongoDB\BSON\PackedArray implements MongoDB\BSON\Type, ArrayAccess, IteratorAggregate {
/* Métodos */
final private function __construct()
final static public function fromJSON(string `$json`): MongoDB\BSON\PackedArray
final static public function fromPHP(array `$value`): MongoDB\BSON\PackedArray
final public function get(int `$key`): mixed
final public function getIterator(): MongoDB\BSON\Iterator
final public function has(int `$index`): bool
final public function offsetExists(mixed `$key`): bool
final public function offsetGet(mixed `$key`): mixed
final public function offsetSet(mixed `$key`, mixed `$value`): void
final public function offsetUnset(mixed `$key`): void
final public function toCanonicalExtendedJSON(): string
final public function toPHP(?array `$typeMap` = `null`): array|object
final public function toRelaxedExtendedJSON(): string
final public function __toString(): string
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Esta classe não implementa mais a interface Serializable.
PECL mongodb 1.17.0 | Implementa MongoDB\BSON\Type.
PECL mongodb 1.17.0 | MongoDB\BSON\PackedArray não pode ser serializado em contextos onde um documento BSON é esperado. Nas versões anteriores, o array BSON teria sido convertido em um documento.

# MongoDB\BSON\PackedArray::__construct

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::__construct — Constrói um novo array BSON (não utilizado)

### Descrição

final private function MongoDB\BSON\PackedArray::__construct()

Objetos MongoDB\BSON\PackedArray são criados através de métodos estáticos de fabricação e não podem ser instanciados diretamente.

### Parâmetros

Esta função não possui parâmetros.

### Veja Também

- MongoDB\BSON\PackedArray::fromPHP() - Constrói uma nova instância de array BSON a partir de dados PHP
- » Tipos BSON

# MongoDB\BSON\PackedArray::fromJSON

(mongodb >=1.20.0)

MongoDB\BSON\PackedArray::fromJSON — Constrói uma nova instância de array BSON a partir de uma string JSON

### Descrição

final static public function MongoDB\BSON\PackedArray::fromJSON(string `$json`): MongoDB\BSON\PackedArray

Converte uma string em » JSON estendido para sua representação BSON.

### Parâmetros

`json` (string)
  Valor JSON a ser convertido.

### Valor Retornado

Retorna uma nova instância de MongoDB\BSON\PackedArray.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma MongoDB\Driver\Exception\UnexpectedValueException se o valor JSON não puder ser convertido para um array BSON (ex: devido a um erro de sintaxe).

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\PackedArray::fromJSON()

    <?php

    $json = '[ "foo", { "$numberInt" : "123" }, { "$numberLong" : "4294967295" }, { "$oid" : "56315a7c6118fd1b920270b1" } ]';
    $packedArray = MongoDB\BSON\PackedArray::fromJSON($json);
    var_dump($packedArray);

    ?>

O exemplo acima produzirá:

    object(MongoDB\BSON\PackedArray)#1 (2) {
      ["data"]=>
      string(68) "MQAAAAIwAAQAAABmb28AEDEAewAAABIyAP////8AAAAABzMAVjFafGEY/RuSAnCxAA=="
      ["value"]=>
      array(4) {
        [0]=>
        string(3) "foo"
        [1]=>
        int(123)
        [2]=>
        int(4294967295)
        [3]=>
        object(MongoDB\BSON\ObjectId)#2 (1) {
          ["oid"]=>
          string(24) "56315a7c6118fd1b920270b1"
        }
      }
    }

### Veja Também

- MongoDB\BSON\PackedArray::fromPHP() - Constrói uma nova instância de array BSON a partir de dados PHP
- » JSON Estendido do MongoDB
- » Tipos BSON

# MongoDB\BSON\PackedArray::fromPHP

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::fromPHP — Constrói uma nova instância de array BSON a partir de dados PHP

### Descrição

final static public function MongoDB\BSON\PackedArray::fromPHP(array `$value`): MongoDB\BSON\PackedArray

### Parâmetros

`value` (array)
  O array PHP a ser convertido para um array BSON. O array precisa ser uma lista (isto é, ter chaves sequenciais numéricas iniciando com `0`).

### Valor Retornado

Retonar uma nova instância de MongoDB\BSON\PackedArray.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma MongoDB\Driver\Exception\InvalidArgumentException se o array informado não for uma lista (isto é, se não tiver chaves sequenciais numéricas iniciando com `0`).

### Veja Também

- » Tipos BSON

# MongoDB\BSON\PackedArray::get

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::get — Retorna o valor de um índice do array

### Descrição

final public function MongoDB\BSON\PackedArray::get(int `$key`): mixed

### Parâmetros

`key` (int)
  O índice a ser obtido do array.

### Valor Retornado

Retorna o valor associado com o índice informado. Se o índice não estiver presente no array, uma exceção é lançada.

> Nota: Ao encontrar um valor codificado como inteiro de 64 bits no array BSON, o valor deste método será uma instância de MongoDB\BSON\Int64.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma MongoDB\Driver\Exception\RuntimeException se o índice não estiver presente no array.

### Veja Também

- MongoDB\BSON\PackedArray::has() - Informa se um índice está presente no array
- » Tipos BSON

# MongoDB\BSON\PackedArray::getIterator

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::getIterator — Retorna um iterador para o array BSON

### Descrição

final public function MongoDB\BSON\PackedArray::getIterator(): MongoDB\BSON\Iterator

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma instância de MongoDB\BSON\Iterator que pode ser usada para iterar sobre todos os índices no array.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma MongoDB\Driver\Exception\UnexpectedValueException se o iterador BSON não puder ser inicializado.

### Veja Também

- » Tipos BSON

# MongoDB\BSON\PackedArray::has

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::has — Informa se um índice está presente no array

### Descrição

final public function MongoDB\BSON\PackedArray::has(int `$index`): bool

### Parâmetros

`index` (int)
  O índice a ser procurado no array.

### Valor Retornado

Retorna `true` se o índice estiver presente no array ou `false` caso contrário.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\BSON\PackedArray::get() - Retorna o valor de um índice do array
- » Tipos BSON

# MongoDB\BSON\PackedArray::offsetExists

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetExists — Informa se um índice está presente no array

### Descrição

final public function MongoDB\BSON\PackedArray::offsetExists(mixed `$key`): bool

### Parâmetros

`key`
  O índice a ser procurado no array.

### Valor Retornado

Retorna `true` se o índice estiver presente no array ou `false` caso contrário.

### Veja Também

- ArrayAccess::offsetExists() - Verifica se uma posição existe
- MongoDB\BSON\PackedArray::has() - Informa se um índice está presente no array

# MongoDB\BSON\PackedArray::offsetGet

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetGet — Retorna o valor de um índice do array

### Descrição

final public function MongoDB\BSON\PackedArray::offsetGet(mixed `$key`): mixed

### Parâmetros

`key`
  O índice a ser obtido do array. Somente int é suportado.

### Valor Retornado

Retorna o valor associado com o índice informado. Se o índice não estiver presente no array, uma exceção é lançada.

> Nota: Ao encontrar um valor codificado como inteiro de 64 bits no array BSON, o valor deste método será uma instância de MongoDB\BSON\Int64.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma MongoDB\Driver\Exception\RuntimeException se o índice não estiver presente no array.

### Veja Também

- ArrayAccess::offsetGet() - Posição a ser obtida
- MongoDB\BSON\PackedArray::get() - Retorna o valor de um índice do array

# MongoDB\BSON\PackedArray::offsetSet

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetSet — Implementação de ArrayAccess

### Descrição

final public function MongoDB\BSON\PackedArray::offsetSet(mixed `$key`, mixed `$value`): void

Define o valor na chave especificada em `key` para `value`.

### Parâmetros

`key`
  O índice a ser definido.
`value`
  O novo valor para `key`.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Sempre lança uma MongoDB\Driver\Exception\LogicException.

# MongoDB\BSON\PackedArray::offsetUnset

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetUnset — Implementação de ArrayAccess

### Descrição

final public function MongoDB\BSON\PackedArray::offsetUnset(mixed `$key`): void

Remove a definição do valor no índice especificado.

### Parâmetros

`key`
  O índice que será removido.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Sempre lança uma MongoDB\Driver\Exception\LogicException.

# MongoDB\BSON\PackedArray::toCanonicalExtendedJSON

(mongodb >=1.20.0)

MongoDB\BSON\PackedArray::toCanonicalExtendedJSON — Retorna a representação JSON Estendida Canônica do array BSON

### Descrição

final public function MongoDB\BSON\PackedArray::toCanonicalExtendedJSON(): string

Converte o array BSON em sua representação » JSON Estendida Canônica. O formato canônico prefere a fidelidade de tipo em detrimento da saída concisa e é mais adequado para produzir saída que pode ser convertida de volta para BSON sem qualquer perda de informação de tipo (por exemplo, os tipos numéricos permanecerão diferenciados).

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string contendo a representação » JSON Estendida Canônica do array BSON.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\PackedArray::toCanonicalExtendedJSON()

    <?php

    $array = [
        'foo',
        123,
        4294967295,
        new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1'),
    ];

    $packedArray = MongoDB\BSON\PackedArray::fromPHP($array);
    echo $packedArray->toCanonicalExtendedJSON(), "\n";

    ?>

O exemplo acima produzirá:

    [ "foo", { "$numberInt" : "123" }, { "$numberLong" : "4294967295" }, { "$oid" : "56315a7c6118fd1b920270b1" } ]

### Veja Também

- MongoDB\BSON\PackedArray::fromJSON() - Constrói uma nova instância de array BSON a partir de uma string JSON
- MongoDB\BSON\PackedArray::toRelaxedExtendedJSON() - Retorna a representação JSON estendida relaxada do array BSON
- MongoDB\BSON\toCanonicalExtendedJSON() - Retorna a representação JSON Estendida Canônica de um valor BSON
- » Especificação JSON Estendido
- » Tipos BSON

# MongoDB\BSON\PackedArray::toPHP

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::toPHP — Retorna a representação PHP do array BSON

### Descrição

final public function MongoDB\BSON\PackedArray::toPHP(?array `$typeMap` = `null`): array|object

### Parâmetros

`typeMap` (array)
  Configuração de mapeamento de tipos.

### Valor Retornado

O valor PHP decodificado.

> Nota: Ao encontrar um valor codificado como inteiro de 64 bits no array BSON, o valor deste método será uma instância de MongoDB\BSON\Int64.

### Erros/Exceções

- Lança uma MongoDB\Driver\Exception\InvalidArgumentException se uma classe no mapa de tipos não puder ser instanciada ou não implementar MongoDB\BSON\Unserializable.

### Veja Também

- MongoDB\BSON\toPHP() - Retorna a representação PHP de um valor BSON
- » Tipos BSON

# MongoDB\BSON\PackedArray::toRelaxedExtendedJSON

(mongodb >=1.20.0)

MongoDB\BSON\PackedArray::toRelaxedExtendedJSON — Retorna a representação JSON estendida relaxada do array BSON

### Descrição

final public function MongoDB\BSON\PackedArray::toRelaxedExtendedJSON(): string

Converte o array BSON em sua representação » JSON estendida relaxada. O formato relaxado prefere o uso de primitivos do tipo JSON em detrimento da fidelidade do tipo e é mais adequado para produzir resultados que podem ser facilmente consumidos por APIs da web e humanos.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string contendo a representação » JSON estendida relaxada do array BSON.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\PackedArray::toRelaxedExtendedJSON()

    <?php

    $array = [
        'foo',
        123,
        4294967295,
        new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1'),
    ];

    $packedArray = MongoDB\BSON\PackedArray::fromPHP($array);
    echo $packedArray->toRelaxedExtendedJSON(), "\n";

    ?>

O exemplo acima produzirá:

    [ "foo", 123, 4294967295, { "$oid" : "56315a7c6118fd1b920270b1" } ]

### Veja Também

- MongoDB\BSON\PackedArray::fromJSON() - Constrói uma nova instância de array BSON a partir de uma string JSON
- MongoDB\BSON\PackedArray::toCanonicalExtendedJSON() - Retorna a representação JSON Estendida Canônica do array BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Retorna a representação JSON Estendida Relaxada de um valor BSON
- » Especificação JSON Estendido
- » Tipos BSON

# MongoDB\BSON\PackedArray::__toString

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::__toString — Retorna a representação em string deste array BSON

### Descrição

final public function MongoDB\BSON\PackedArray::__toString(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a representação em string deste array BSON.

### Veja Também

- » Tipos BSON

## Índice

- MongoDB\BSON\PackedArray::__construct — Constrói um novo array BSON (não utilizado)
- MongoDB\BSON\PackedArray::fromJSON — Constrói uma nova instância de array BSON a partir de uma string JSON
- MongoDB\BSON\PackedArray::fromPHP — Constrói uma nova instância de array BSON a partir de dados PHP
- MongoDB\BSON\PackedArray::get — Retorna o valor de um índice do array
- MongoDB\BSON\PackedArray::getIterator — Retorna um iterador para o array BSON
- MongoDB\BSON\PackedArray::has — Informa se um índice está presente no array
- MongoDB\BSON\PackedArray::offsetExists — Informa se um índice está presente no array
- MongoDB\BSON\PackedArray::offsetGet — Retorna o valor de um índice do array
- MongoDB\BSON\PackedArray::offsetSet — Implementação de ArrayAccess
- MongoDB\BSON\PackedArray::offsetUnset — Implementação de ArrayAccess
- MongoDB\BSON\PackedArray::toCanonicalExtendedJSON — Retorna a representação JSON Estendida Canônica do array BSON
- MongoDB\BSON\PackedArray::toPHP — Retorna a representação PHP do array BSON
- MongoDB\BSON\PackedArray::toRelaxedExtendedJSON — Retorna a representação JSON estendida relaxada do array BSON
- MongoDB\BSON\PackedArray::__toString — Retorna a representação em string deste array BSON

# A classe MongoDB\BSON\Iterator

(mongodb >=1.16.0)

## Introdução

Iterador usado para iterar sobre um documento ou array BSON.

## Resumo da classe

final class MongoDB\BSON\Iterator implements Iterator {
/* Métodos */
final private function __construct()
public function current(): mixed
public function key(): string|int
public function next(): void
public function rewind(): void
public function valid(): bool
}

# MongoDB\BSON\Iterator::__construct

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::__construct — Constrói um novo iterador BSON (não utilizado)

### Descrição

final private function MongoDB\BSON\Iterator::__construct()

Objetos MongoDB\BSON\Iterator são criados nas chamadas a MongoDB\BSON\Document::getIterator() ou MongoDB\BSON\PackedArray::getIterator() e não podem ser instanciados diretamente.

### Parâmetros

Esta função não possui parâmetros.

### Veja Também

- MongoDB\BSON\Document::getIterator() - Retorna um iterador para o documento BSON
- MongoDB\BSON\PackedArray::getIterator() - Retorna um iterador para o array BSON
- » Tipos BSON

# MongoDB\BSON\Iterator::current

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::current — Retorna o elemento atual

### Descrição

public function MongoDB\BSON\Iterator::current(): mixed

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o valor do documento atual.

> Nota: Ao encontrar um valor codificado um inteiro de 64 bits na estrutura BSON, o valor de retorno deste métodos será uma instância MongoDB\BSON\Int64.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma MongoDB\Driver\Exception\LogicException se o iterador não for válido.

### Veja Também

- Iterator::current() - Retorna o elemento atual

# MongoDB\BSON\Iterator::key

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::key — Retorna a chave do elemento atual

### Descrição

public function MongoDB\BSON\Iterator::key(): string|int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a chave do elemento atual. Ao iterar sobre um documento BSON, a chave sempre será uma string. Ao iterar sobre um array BSON, a chave será um int.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma MongoDB\Driver\Exception\LogicException se o iterador não for válido.

### Veja Também

- Iterator::key() - Retorna a chave do elemento atual

# MongoDB\BSON\Iterator::next

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::next — Avança o iterador para o próximo elemento

### Descrição

public function MongoDB\BSON\Iterator::next(): void

### Parâmetros

Esta função não possui parâmetros.

### Veja Também

- Iterator::next() - Move para o próximo elemento

# MongoDB\BSON\Iterator::rewind

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::rewind — Retrocede o iterador para o primeiro elemento

### Descrição

public function MongoDB\BSON\Iterator::rewind(): void

### Parâmetros

Esta função não possui parâmetros.

### Veja Também

- Iterator::rewind() - Retrocede o Iterator para o primeiro elemento

# MongoDB\BSON\Iterator::valid

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::valid — Verifica se a posição atual é válida

### Descrição

public function MongoDB\BSON\Iterator::valid(): bool

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se a posição atual do iterador for válida, `false` caso contrário.

### Veja Também

- Iterator::valid() - Verifica se a posição atual é válida

## Índice

- MongoDB\BSON\Iterator::__construct — Constrói um novo iterador BSON (não utilizado)
- MongoDB\BSON\Iterator::current — Retorna o elemento atual
- MongoDB\BSON\Iterator::key — Retorna a chave do elemento atual
- MongoDB\BSON\Iterator::next — Avança o iterador para o próximo elemento
- MongoDB\BSON\Iterator::rewind — Retrocede o iterador para o primeiro elemento
- MongoDB\BSON\Iterator::valid — Verifica se a posição atual é válida

# A classe MongoDB\BSON\Binary

(mongodb >=1.0.0)

## Introdução

Tipo BSON para dados binários (ou seja, array de bytes). Os valores binários também possuem um subtipo, que é usado para indicar que tipo de dados está no array de bytes. Os subtipos de zero a 127 são predefinidos ou reservados. Os subtipos de 128 a 255 são definidos pelo usuário.

## Resumo da classe

final class MongoDB\BSON\Binary implements MongoDB\BSON\BinaryInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Constantes */
const int TYPE_GENERIC = 0;
const int TYPE_FUNCTION = 1;
const int TYPE_OLD_BINARY = 2;
const int TYPE_OLD_UUID = 3;
const int TYPE_UUID = 4;
const int TYPE_MD5 = 5;
const int TYPE_ENCRYPTED = 6;
const int TYPE_COLUMN = 7;
const int TYPE_SENSITIVE = 8;
const int TYPE_VECTOR = 9;
const int TYPE_USER_DEFINED = 128;
/* Métodos */
final public function __construct(string `$data`, int `$type` = MongoDB\BSON\Binary::TYPE_GENERIC)
final public static function fromVector(array `$vector`, MongoDB\BSON\VectorType `$vectorType`): MongoDB\BSON\Binary
final public function getData(): string
final public function getType(): int
final public function getVectorType(): MongoDB\BSON\VectorType
final public function jsonSerialize(): mixed
final public function toArray(): array
final public function __toString(): string
}

## Constantes predefinidas

`MongoDB\BSON\Binary::TYPE_GENERIC`
  Dados binários genéricos.
`MongoDB\BSON\Binary::TYPE_FUNCTION`
  Função.
`MongoDB\BSON\Binary::TYPE_OLD_BINARY`
  Dados binários genéricos (preterido em favor de `MongoDB\BSON\Binary::TYPE_GENERIC`).
`MongoDB\BSON\Binary::TYPE_OLD_UUID`
  Identificador único universal (preterido em favor de `MongoDB\BSON\Binary::TYPE_UUID`). Ao usar este tipo, os dados binários precisam ter 16 bytes de comprimento. Historicamente, outros drivers codificaram valores com este tipo com base em suas convenções de linguagem (ex.: variações little endian / big endian), o que o torna não portável. A extensão PHP não aplica nenhuma manipulação especial para codificar ou decodificar dados com este tipo.
`MongoDB\BSON\Binary::TYPE_UUID`
  Identificador único universal. Ao usar este tipo, os dados do binário devem ter 16 bytes de comprimento e codificados de acordo com a » RFC 4122.
`MongoDB\BSON\Binary::TYPE_MD5`
  Hash MD5. Ao usar este tipo, os dados do binário devem ter 16 bytes de comprimento.
`MongoDB\BSON\Binary::TYPE_ENCRYPTED`
  Valor criptografado. Este subtipo é usado para criptografia do lado do cliente.
`MongoDB\BSON\Binary::TYPE_COLUMN`
  Dados da coluna. Este subtipo é usado para coleções de séries temporais.
`MongoDB\BSON\Binary::TYPE_SENSITIVE`
  Dados confidenciais. Este subtipo é usado para dados confidenciais que devem ser excluídos do registro do servidor quando possível.
`MongoDB\BSON\Binary::TYPE_VECTOR`
  Dados do vetor. Este subtipo é usado para armazenar dados de vetor de forma eficiente para uso nas pesquisas de vetor do MongoDB.
`MongoDB\BSON\Binary::TYPE_USER_DEFINED`
  Tipo definido pelo usuário. Enquanto os tipos entre 0 e 127 são predefinidos ou reservados, os tipos entre 128 e 255 são definidos pelo usuário e podem ser usados ​​para qualquer coisa.

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.2.0 | Adicionada a constante `MongoDB\BSON\Binary::TYPE_VECTOR` e também as funções MongoDB\BSON\Binary::fromVector(), MongoDB\BSON\Binary::getVectorType() e MongoDB\BSON\Binary::toArray().
PECL mongodb 2.0.0 | Esta classe não implementa mais a interface Serializable.
PECL mongodb 1.17.0 | Adicionada a constante `MongoDB\BSON\Binary::TYPE_SENSITIVE`.
PECL mongodb 1.12.0 | Implementada a interface Stringable para PHP 8.0+. Adicionada a constante `MongoDB\BSON\Binary::TYPE_COLUMN`.
PECL mongodb 1.7.0 | Adicionada a constante `MongoDB\BSON\Binary::TYPE_ENCRYPTED`.
PECL mongodb 1.3.0 | Implementada a interface MongoDB\BSON\BinaryInterface.
PECL mongodb 1.2.0 | Implementadas as interfaces Serializable e JsonSerializable.

# MongoDB\BSON\Binary::__construct

(mongodb >=1.0.0)

MongoDB\BSON\Binary::__construct — Constrói um novo Binary

### Descrição

final public function MongoDB\BSON\Binary::__construct(string `$data`, int `$type` = MongoDB\BSON\Binary::TYPE_GENERIC)

### Parâmetros

`data` (string)
  Dados binários.
`type` (int)
  Inteiro de 8 bits sem sinal denotando o tipo de dados. O padrão é `MongoDB\BSON\Binary::TYPE_GENERIC` se não especificado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança MongoDB\Driver\Exception\InvalidArgumentException se `type` não for um inteiro de 8 bits sem sinal.
- Lança MongoDB\Driver\Exception\InvalidArgumentException se `type` for `MongoDB\BSON\Binary::TYPE_UUID` ou `MongoDB\BSON\Binary::TYPE_OLD_UUID` e `data` não tiver exatamente 16 bytes.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.15.0 | O padrão para o parâmetro `type` é `MongoDB\BSON\Binary::TYPE_GENERIC` se não for especificado.
PECL mongodb 1.3.0 | MongoDB\Driver\Exception\InvalidArgumentException é lançada se `type` for `MongoDB\BSON\Binary::TYPE_UUID` ou `MongoDB\BSON\Binary::TYPE_OLD_UUID` e `data` não tiver exatamente 16 bytes.
PECL mongodb 1.1.3 | MongoDB\Driver\Exception\InvalidArgumentException é lançada se `type` não for um inteiro de 8 bits sem sinal.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\Binary::__construct()

    <?php

    $binary = new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC);
    var_dump($binary);

    ?>

O exemplo acima produzirá:

    object(MongoDB\BSON\Binary)#1 (2) {
      ["data"]=>
      string(3) "foo"
      ["type"]=>
      int(0)
    }

### Veja Também

- » Tipos BSON

# MongoDB\BSON\Binary::fromVector

(mongodb >=2.2.0)

MongoDB\BSON\Binary::fromVector — Cria um novo binário com subtipo `MongoDB\BSON\Binary::SUBTYPE_VECTOR` a partir de um array e do tipo de vetor

### Descrição

final public static function MongoDB\BSON\Binary::fromVector(array `$vector`, MongoDB\BSON\VectorType `$vectorType`): MongoDB\BSON\Binary

### Parâmetros

`vector` (array)

  Um array de valores representando os dados do vetor. O tipo de cada valor precisa corresponder ao tipo indicado pelo parâmetro `vectorType`:

  - para `MongoDB\BSON\VectorType::Float32`, cada valor precisa ser um float
  - para `MongoDB\BSON\VectorType::Int8`, cada valor precisa ser um int de 8 bits, ou seja, de `-127` a `128`
  - para `MongoDB\BSON\VectorType::PackedBit`, cada valor precisa ser um bool ou um int de 1 bit, ou seja `0` ou `1`
`vectorType` (MongoDB\BSON\VectorType)
  O tipo de dados do vetor.

### Valor Retornado

Retorna um novo binário com subtipo `MongoDB\BSON\Binary::SUBTYPE_VECTOR`.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\BSON\Binary::toArray() - Retorna o vetor como um array para um binário com subtipo MongoDB\BSON\Binary::SUBTYPE_VECTOR
- MongoDB\BSON\Binary::getVectorType() - Retorna o tipo de dados de um binário com o subtipo do vetor
- MongoDB\BSON\VectorType
- » Tipos BSON

# MongoDB\BSON\Binary::getData

(mongodb >=1.0.0)

MongoDB\BSON\Binary::getData — Retorna os dados de Binary

### Descrição

final public function MongoDB\BSON\Binary::getData(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna os dados de Binary.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\Binary::getData()

    <?php

    $binary = new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC);
    var_dump($binary->getData());

    ?>

O exemplo acima produzirá:

    string(3) "foo"

### Veja Também

- » Tipos BSON

# MongoDB\BSON\Binary::getType

(mongodb >=1.0.0)

MongoDB\BSON\Binary::getType — Retorna o tipo de Binary

### Descrição

final public function MongoDB\BSON\Binary::getType(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o tipo de Binary.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\Binary::getType()

    <?php

    $binary = new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC);
    var_dump($binary->getType());

    ?>

O exemplo acima produzirá:

    int(0)

### Veja Também

- » Tipos BSON

# MongoDB\BSON\Binary::getVectorType

(mongodb >=2.2.0)

MongoDB\BSON\Binary::getVectorType — Retorna o tipo de dados de um binário com o subtipo do vetor

### Descrição

final public function MongoDB\BSON\Binary::getVectorType(): MongoDB\BSON\VectorType

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o tipo de dados do vetor binário.

### Erros/Exceções

- Lança um MongoDB\Driver\Exception\LogicException se o subtipo não for `MongoDB\BSON\Binary::SUBTYPE_VECTOR`.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- » Tipos BSON
- MongoDB\BSON\VectorType

# MongoDB\BSON\Binary::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Binary::jsonSerialize — Retorna uma representação que pode ser convertida para JSON

### Descrição

final public function MongoDB\BSON\Binary::jsonSerialize(): mixed

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna dados que podem ser serializados por json_encode() para produzir uma representação JSON estendida de MongoDB\BSON\Binary.

> Nota: A saída é consistente com a função MongoDB\BSON\toJSON(), que usa o formato JSON estendido legado específico do driver. Isso não corresponde necessariamente às representações JSON estendidas » relaxadas ou » canônicas usadas por MongoDB\BSON\toRelaxedExtendedJSON() e MongoDB\BSON\toCanonicalExtendedJSON(), respectivamente.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- JsonSerializable::jsonSerialize() - Especifica os dados que devem ser serializados para JSON
- json_encode() - Retorna a representação JSON de um valor
- MongoDB\BSON\toCanonicalExtendedJSON() - Retorna a representação JSON Estendida Canônica de um valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Retorna a representação JSON Estendida Relaxada de um valor BSON
- » JSON Estendida do MongoDB

# MongoDB\BSON\Binary::toArray

(mongodb >=2.2.0)

MongoDB\BSON\Binary::toArray — Retorna o vetor como um array para um binário com subtipo `MongoDB\BSON\Binary::SUBTYPE_VECTOR`

### Descrição

final public function MongoDB\BSON\Binary::toArray(): array

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array contendo os dados do vetor.

### Erros/Exceções

- Lança um MongoDB\Driver\Exception\LogicException se o subtipo não for `MongoDB\BSON\Binary::SUBTYPE_VECTOR`.
- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\BSON\Binary::fromVector() - Cria um novo binário com subtipo MongoDB\BSON\Binary::SUBTYPE_VECTOR a partir de um array e do tipo de vetor
- » Tipos BSON

# MongoDB\BSON\Binary::__toString

(mongodb >=1.2.0)

MongoDB\BSON\Binary::__toString — Retorna string representando os dados de Binary

### Descrição

final public function MongoDB\BSON\Binary::__toString(): string

Este método é um apelido para: MongoDB\BSON\Binary::getData().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna string representando os dados de Binary.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\Binary::__toString()

    <?php

    var_dump((string) new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC));

    ?>

O exemplo acima produzirá:

    string(3) "foo"

### Veja Também

- MongoDB\BSON\Binary::getData() - Retorna os dados de Binary
- » Tipos BSON

## Índice

- MongoDB\BSON\Binary::__construct — Constrói um novo Binary
- MongoDB\BSON\Binary::fromVector — Cria um novo binário com subtipo MongoDB\BSON\Binary::SUBTYPE_VECTOR a partir de um array e do tipo de vetor
- MongoDB\BSON\Binary::getData — Retorna os dados de Binary
- MongoDB\BSON\Binary::getType — Retorna o tipo de Binary
- MongoDB\BSON\Binary::getVectorType — Retorna o tipo de dados de um binário com o subtipo do vetor
- MongoDB\BSON\Binary::jsonSerialize — Retorna uma representação que pode ser convertida para JSON
- MongoDB\BSON\Binary::toArray — Retorna o vetor como um array para um binário com subtipo MongoDB\BSON\Binary::SUBTYPE_VECTOR
- MongoDB\BSON\Binary::__toString — Retorna string representando os dados de Binary

# A enumeração MongoDB\BSON\VectorType

(mongodb >=2.2.0)

## Introdução

A enumeração MongoDB\BSON\VectorType é usada para especificar o tipo de dados de vetor armazenados em um MongoDB\BSON\Binary com o subtipo `MongoDB\BSON\Binary::TYPE_VECTOR`.

## Resumo da enumeração

enum MongoDB\BSON\VectorType
{
case Float32 ; // Cada elemento no vetor é um valor em ponto flutuante de 32 bits.
case Int8 ; // Cada elemento no vetor é um valor inteiro de 8 bits.
case PackedBit ; // Cada elemento no vetor é um valor de 1 bit. Ao criar vetores deste tipo, pode-se passar valores do tipo bool ou do tipo int com 1 bit, ou seja, `0` ou `1`.
}

# A classe MongoDB\BSON\Decimal128

(mongodb >=1.2.0)

## Introdução

Tipo BSON para o » formato de ponto flutuante Decimal128, que suporta números com até 34 dígitos decimais (ou seja, dígitos significativos) e um intervalo de expoentes de -6143 a +6144.

Ao contrário do tipo BSON "double" (ou seja, float em PHP), que armazena apenas uma aproximação dos valores decimais, o tipo de dados decimal armazena o valor exato. Por exemplo, `MongoDB\BSON\Decimal128('9.99')` tem um valor preciso de 9.99, onde um "double" 9.99 teria um valor aproximado de 9.990000000000002131628….

> Nota: MongoDB\BSON\Decimal128 só é compatível com o MongoDB 3.4+. Tentar usar o tipo BSON com uma versão anterior do MongoDB resultará em erro.

## Resumo da classe

final class MongoDB\BSON\Decimal128 implements MongoDB\BSON\Decimal128Interface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Métodos */
final public function __construct(string `$value`)
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Esta classe não implementa mais a interface Serializable.
PECL mongodb 1.12.0 | Implementa Stringable para PHP 8.0+.
PECL mongodb 1.3.0 | Implementa MongoDB\BSON\Decimal128Interface.
PECL mongodb 1.2.0 | Implementa Serializable e JsonSerializable.

# MongoDB\BSON\Decimal128::__construct

(mongodb >=1.2.0)

MongoDB\BSON\Decimal128::__construct — Constrói um novo Decimal128

### Descrição

final public function MongoDB\BSON\Decimal128::__construct(string `$value`)

> Nota: MongoDB\BSON\Decimal128 só é compatível com o MongoDB 3.4+. Tentar usar o tipo BSON com uma versão anterior do MongoDB resultará em erro.

### Parâmetros

`value` (string)
  Uma string decimal.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança MongoDB\Driver\Exception\InvalidArgumentException se `value` não for uma string decimal válida.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\Decimal128::__construct()

    <?php

    var_dump(new MongoDB\BSON\Decimal128(1234.5678));
    var_dump(new MongoDB\BSON\Decimal128(NAN));
    var_dump(new MongoDB\BSON\Decimal128(INF));

    ?>

O exemplo acima produzirá algo semelhante a:

    object(MongoDB\BSON\Decimal128)#1 (1) {
      ["dec"]=>
      string(9) "1234.5678"
    }
    object(MongoDB\BSON\Decimal128)#1 (1) {
      ["dec"]=>
      string(3) "NaN"
    }
    object(MongoDB\BSON\Decimal128)#1 (1) {
      ["dec"]=>
      string(8) "Infinity"
    }

### Veja Também

- » Formato em ponto flutuante Decimal128
- » Tipos BSON

# MongoDB\BSON\Decimal128::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Decimal128::jsonSerialize — Retorna uma representação que pode ser convertida para JSON

### Descrição

final public function MongoDB\BSON\Decimal128::jsonSerialize(): mixed

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna dados que podem ser serializados por json_encode() para produzir uma representação JSON estendida de MongoDB\BSON\Decimal128.

> Nota: A saída é consistente com a função MongoDB\BSON\toJSON(), que usa o formato JSON estendido legado específico do driver. Isso não corresponde necessariamente às representações JSON estendidas » relaxadas ou » canônicas usadas por MongoDB\BSON\toRelaxedExtendedJSON() e MongoDB\BSON\toCanonicalExtendedJSON(), respectivamente.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- JsonSerializable::jsonSerialize() - Especifica os dados que devem ser serializados para JSON
- json_encode() - Retorna a representação JSON de um valor
- MongoDB\BSON\toCanonicalExtendedJSON() - Retorna a representação JSON Estendida Canônica de um valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Retorna a representação JSON Estendida Relaxada de um valor BSON
- » JSON Estendido do MongoDB

# MongoDB\BSON\Decimal128::__toString

(mongodb >=1.2.0)

MongoDB\BSON\Decimal128::__toString — Retorna a representação em string deste Decimal128

### Descrição

final public function MongoDB\BSON\Decimal128::__toString(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a representação em string deste Decimal128.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\Decimal128::__toString()

    <?php

    var_dump((string) new MongoDB\BSON\Decimal128(1234.5678));
    var_dump((string) new MongoDB\BSON\Decimal128(NAN));
    var_dump((string) new MongoDB\BSON\Decimal128(INF));

    ?>

O exemplo acima produzirá algo semelhante a:

    string(9) "1234.5678"
    string(3) "NaN"
    string(8) "Infinity"

### Veja Também

- » Formato em ponto flutuante Decimal128
- » Tipos BSON

## Índice

- MongoDB\BSON\Decimal128::__construct — Constrói um novo Decimal128
- MongoDB\BSON\Decimal128::jsonSerialize — Retorna uma representação que pode ser convertida para JSON
- MongoDB\BSON\Decimal128::__toString — Retorna a representação em string deste Decimal128

# A classe MongoDB\BSON\Javascript

(mongodb >=1.0.0)

## Introdução

Tipo BSON para código Javascript. Um documento de escopo opcional pode ser especificado para mapear identificadores para valores e definir o escopo no qual o código deve ser avaliado pelo servidor.

> Nota: Este tipo BSON é usado principalmente ao executar comandos de banco de dados que usam uma função Javascript como parâmetro, como » mapReduce.

## Resumo da classe

final class MongoDB\BSON\Javascript implements MongoDB\BSON\JavascriptInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Métodos */
final public function __construct(string `$code`, array|object|null `$scope` = `null`)
final public function getCode(): string
final public function getScope(): ?object
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Esta classe não implementa mais a interface Serializable.
PECL mongodb 1.12.0 | Implementa Stringable para PHP 8.0+.
PECL mongodb 1.3.0 | Implementa MongoDB\BSON\JavascriptInterface.
PECL mongodb 1.2.0 | Implementa Serializable e JsonSerializable.

# MongoDB\BSON\Javascript::__construct

(mongodb >=1.0.0)

MongoDB\BSON\Javascript::__construct — Constrói um novo Javascript

### Descrição

final public function MongoDB\BSON\Javascript::__construct(string `$code`, array|object|null `$scope` = `null`)

### Parâmetros

`code` (string)
  Código Javascript.
`scope` (array|object)
  Código Javascript.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma MongoDB\Driver\Exception\InvalidArgumentException se `code` contiver bytes nulos.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.2.0 | MongoDB\Driver\Exception\InvalidArgumentException é lançada se `code` contiver bytes nulos. Anteriormente, valores seriam truncados no primeiro byte nulo.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\Javascript::__construct()

    <?php

    $code = new MongoDB\BSON\Javascript('function() { return 1; }');
    var_dump($code);

    $codews = new MongoDB\BSON\Javascript('function() { return foo; }', ['foo' => 'bar']);
    var_dump($codews);

    ?>

O exemplo acima produzirá:

    object(MongoDB\BSON\Javascript)#1 (2) {
      ["javascript"]=>
      string(24) "function() { return 1; }"
      ["scope"]=>
      object(stdClass)#2 (0) {
      }
    }
    object(MongoDB\BSON\Javascript)#2 (2) {
      ["javascript"]=>
      string(26) "function() { return foo; }"
      ["scope"]=>
      object(stdClass)#1 (1) {
        ["foo"]=>
        string(3) "bar"
      }
    }

### Veja Também

- » Tipos BSON

# MongoDB\BSON\Javascript::getCode

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::getCode — Retorna o código do Javascript

### Descrição

final public function MongoDB\BSON\Javascript::getCode(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o código do Javascript.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\Javascript::getCode()

    <?php

    $js = new MongoDB\BSON\Javascript('function foo(bar) { return bar; }');
    var_dump($js->getCode());

    ?>

O exemplo acima produzirá:

    string(33) "function foo(bar) { return bar; }"

### Veja Também

- » Tipos BSON

# MongoDB\BSON\Javascript::getScope

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::getScope — Retorna o documento de escopo do Javascript

### Descrição

final public function MongoDB\BSON\Javascript::getScope(): ?object

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o documento de escopo do Javascript ou `null` se não houver escopo.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\Javascript::getScope()

    <?php

    $js = new MongoDB\BSON\Javascript('function foo(bar) { return bar; }');
    var_dump($js->getScope());

    $js = new MongoDB\BSON\Javascript('function foo() { return foo; }', ['foo' => 42]);
    var_dump($js->getScope());

    ?>

O exemplo acima produzirá:

    NULL
    object(stdClass)#1 (1) {
      ["foo"]=>
      int(42)
    }

### Veja Também

- » Tipos BSON

# MongoDB\BSON\Javascript::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::jsonSerialize — Retorna uma representação que pode ser convertida para JSON

### Descrição

final public function MongoDB\BSON\Javascript::jsonSerialize(): mixed

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna dados que podem ser serializados por json_encode() para produzir uma representação JSON estendida de MongoDB\BSON\Javascript.

> Nota: A saída é consistente com a função MongoDB\BSON\toJSON(), que usa o formato JSON estendido legado específico do driver. Isso não corresponde necessariamente às representações JSON estendidas » relaxadas ou » canônicas usadas por MongoDB\BSON\toRelaxedExtendedJSON() e MongoDB\BSON\toCanonicalExtendedJSON(), respectivamente.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- JsonSerializable::jsonSerialize() - Especifica os dados que devem ser serializados para JSON
- json_encode() - Retorna a representação JSON de um valor
- MongoDB\BSON\toCanonicalExtendedJSON() - Retorna a representação JSON Estendida Canônica de um valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Retorna a representação JSON Estendida Relaxada de um valor BSON
- » JSON Estendido do MongoDB

# MongoDB\BSON\Javascript::__toString

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::__toString — Retorna o código do Javascript

### Descrição

final public function MongoDB\BSON\Javascript::__toString(): string

Este método é um apelido para: MongoDB\BSON\Javascript::getCode().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o código do Javascript.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\Javascript::__toString()

    <?php

    var_dump((string) new MongoDB\BSON\Javascript('function foo(bar) { return bar; }'));

    ?>

O exemplo acima produzirá:

    string(33) "function foo(bar) { return bar; }"

### Veja Também

- MongoDB\BSON\Javascript::getCode() - Retorna o código do Javascript
- » Tipos BSON

## Índice

- MongoDB\BSON\Javascript::__construct — Constrói um novo Javascript
- MongoDB\BSON\Javascript::getCode — Retorna o código do Javascript
- MongoDB\BSON\Javascript::getScope — Retorna o documento de escopo do Javascript
- MongoDB\BSON\Javascript::jsonSerialize — Retorna uma representação que pode ser convertida para JSON
- MongoDB\BSON\Javascript::__toString — Retorna o código do Javascript

# A classe MongoDB\BSON\MaxKey

(mongodb >=1.0.0)

## Introdução

Tipo BSON especial que compara valores superiores a todos os outros valores de elemento BSON possíveis.

> Nota: Este é um tipo interno do MongoDB usado para indexação e fragmentação.

## Resumo da classe

final class MongoDB\BSON\MaxKey implements MongoDB\BSON\MaxKeyInterface, MongoDB\BSON\Type, JsonSerializable {
/* Métodos */
final public function __construct()
final public function jsonSerialize(): mixed
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Esta classe não implementa mais a interface Serializable.
PECL mongodb 1.3.0 | Implementa MongoDB\BSON\MaxKeyInterface.
PECL mongodb 1.2.0 | Implementa Serializable e JsonSerializable.

# MongoDB\BSON\MaxKey::__construct

(mongodb >=1.0.0)

MongoDB\BSON\MaxKey::__construct — Constrói um novo MaxKey

### Descrição

final public function MongoDB\BSON\MaxKey::__construct()

### Parâmetros

Esta função não possui parâmetros.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\MaxKey::__construct()

    <?php

    var_dump(new MongoDB\BSON\MaxKey());

    ?>

O exemplo acima produzirá:

    object(MongoDB\BSON\MaxKey)#1 (0) {
    }

### Veja Também

- » Tipos BSON

# MongoDB\BSON\MaxKey::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\MaxKey::jsonSerialize — Retorna uma representação que pode ser convertida para JSON

### Descrição

final public function MongoDB\BSON\MaxKey::jsonSerialize(): mixed

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna dados que podem ser serializados por json_encode() para produzir uma representação JSON estendida de MongoDB\BSON\MaxKey.

> Nota: A saída é consistente com a função MongoDB\BSON\toJSON(), que usa o formato JSON estendido legado específico do driver. Isso não corresponde necessariamente às representações JSON estendidas » relaxadas ou » canônicas usadas por MongoDB\BSON\toRelaxedExtendedJSON() e MongoDB\BSON\toCanonicalExtendedJSON(), respectivamente.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- JsonSerializable::jsonSerialize() - Especifica os dados que devem ser serializados para JSON
- json_encode() - Retorna a representação JSON de um valor
- MongoDB\BSON\toCanonicalExtendedJSON() - Retorna a representação JSON Estendida Canônica de um valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Retorna a representação JSON Estendida Relaxada de um valor BSON
- » JSON Estendido do MongoDB

## Índice

- MongoDB\BSON\MaxKey::__construct — Constrói um novo MaxKey
- MongoDB\BSON\MaxKey::jsonSerialize — Retorna uma representação que pode ser convertida para JSON

# A classe MongoDB\BSON\MinKey

(mongodb >=1.0.0)

## Introdução

Tipo BSON especial que compara valores inferiores a todos os outros valores de elemento BSON possíveis.

> Nota: Este é um tipo interno do MongoDB usado para indexação e fragmentação.

## Resumo da classe

final class MongoDB\BSON\MinKey implements MongoDB\BSON\MinKeyInterface, MongoDB\BSON\Type, JsonSerializable {
/* Métodos */
final public function __construct()
final public function jsonSerialize(): mixed
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Esta classe não implementa mais a interface Serializable.
PECL mongodb 1.3.0 | Implementa MongoDB\BSON\MinKeyInterface.
PECL mongodb 1.2.0 | Implementa Serializable e JsonSerializable.

# MongoDB\BSON\MinKey::__construct

(mongodb >=1.0.0)

MongoDB\BSON\MinKey::__construct — Constrói um novo MinKey

### Descrição

final public function MongoDB\BSON\MinKey::__construct()

### Parâmetros

Esta função não possui parâmetros.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\MinKey::__construct()

    <?php

    var_dump(new MongoDB\BSON\MinKey());

    ?>

O exemplo acima produzirá:

    object(MongoDB\BSON\MinKey)#1 (0) {
    }

### Veja Também

- » Tipos BSON

# MongoDB\BSON\MinKey::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\MinKey::jsonSerialize — Retorna uma representação que pode ser convertida para JSON

### Descrição

final public function MongoDB\BSON\MinKey::jsonSerialize(): mixed

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna dados que podem ser serializados por json_encode() para produzir uma representação JSON estendida de MongoDB\BSON\MinKey.

> Nota: A saída é consistente com a função MongoDB\BSON\toJSON(), que usa o formato JSON estendido legado específico do driver. Isso não corresponde necessariamente às representações JSON estendidas » relaxadas ou » canônicas usadas por MongoDB\BSON\toRelaxedExtendedJSON() e MongoDB\BSON\toCanonicalExtendedJSON(), respectivamente.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- JsonSerializable::jsonSerialize() - Especifica os dados que devem ser serializados para JSON
- json_encode() - Retorna a representação JSON de um valor
- MongoDB\BSON\toCanonicalExtendedJSON() - Retorna a representação JSON Estendida Canônica de um valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Retorna a representação JSON Estendida Relaxada de um valor BSON
- » JSON Estendido do MongoDB

## Índice

- MongoDB\BSON\MinKey::__construct — Constrói um novo MinKey
- MongoDB\BSON\MinKey::jsonSerialize — Retorna uma representação que pode ser convertida para JSON

# A classe MongoDB\BSON\ObjectId

(mongodb >=1.0.0)

## Introdução

Tipo BSON para um » ObjectId. O valor consiste em 12 bytes, onde os primeiros quatro bytes são um timestamp que reflete a criação do ObjectId. Especificamente, o valor consiste em:

- um valor de 4 bytes que representa os segundos desde a época Unix,
- um número aleatório de 5 bytes único para um equipamento e um processo, e
- um contador de 3 bytes, começando com um valor aleatório.

No MongoDB, cada documento armazenado em uma coleção requer um campo `_id` exclusivo que atua como chave primária. Se um documento inserido omitir o campo `_id`, a extensão gera automaticamente um ObjectId para o campo `_id`.

Usar ObjectIds para o campo `_id` fornece os seguintes benefícios adicionais:

- O horário de criação do ObjectId pode ser acessado usando o método MongoDB\BSON\ObjectId::getTimestamp().
- A classificação em um campo `_id` que armazena valores ObjectId é aproximadamente equivalente à classificação por horário de criação.

## Resumo da classe

final class MongoDB\BSON\ObjectId implements MongoDB\BSON\ObjectIdInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Métodos */
final public function __construct(?string `$id` = `null`)
final public function getTimestamp(): int
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Esta classe não implementa mais a interface Serializable.
PECL mongodb 1.12.0 | Implementa Stringable para PHP 8.0+.
PECL mongodb 1.3.0 | Renomeado de `MongoDB\BSON\ObjectID` para `MongoDB\BSON\ObjectId`. Implementa MongoDB\BSON\ObjectIdInterface.
PECL mongodb 1.2.0 | Implementa Serializable e JsonSerializable.

# MongoDB\BSON\ObjectId::__construct

(mongodb >=1.0.0)

MongoDB\BSON\ObjectId::__construct — Constrói um novo ObjectId

### Descrição

final public function MongoDB\BSON\ObjectId::__construct(?string `$id` = `null`)

### Parâmetros

`id` (string)
  Uma string hexadecimal de 24 caracteres Se não informada, a extensão irá gerar um ObjectId.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma MongoDB\Driver\Exception\InvalidArgumentException se `id` não for uma string hexadecimal de 24 caracteres.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\ObjectId::__construct()

    <?php

    var_dump(new MongoDB\BSON\ObjectId());

    var_dump(new MongoDB\BSON\ObjectId('000000000000000000000001'));

    ?>

O exemplo acima produzirá algo semelhante a:

    object(MongoDB\BSON\ObjectId)#1 (1) {
      ["oid"]=>
      string(24) "56732d3dda14d81214634921"
    }
    object(MongoDB\BSON\ObjectId)#1 (1) {
      ["oid"]=>
      string(24) "000000000000000000000001"
    }

### Veja Também

- » Referência sobre ObjectId
- » Tipos BSON: ObjectId

# MongoDB\BSON\ObjectId::getTimestamp

(mongodb >=1.2.0)

MongoDB\BSON\ObjectId::getTimestamp — Retorna o componente timestamp deste ObjectId

### Descrição

final public function MongoDB\BSON\ObjectId::getTimestamp(): int

O componente timestamp de um ObjectId são seus 32 bits mais significativos, o que denota o número de segundos desde a época Unix. Este valor é lido como um número inteiro sem sinal de 32 bits com ordem de bytes big-endian.

> Nota: Como o tipo inteiro do PHP possui sinal, alguns valores retornados por este método podem aparecer como números inteiros negativos em plataformas de 32 bits. O formatador `"%u"` de sprintf() pode ser usado para obter uma representação em string do valor decimal sem sinal.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o componente timestamp deste ObjectId.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\ObjectId::getTimestamp()

    <?php

    var_dump((new MongoDB\BSON\ObjectId())->getTimestamp());

    var_dump((new MongoDB\BSON\ObjectId('0000002a0000000000000000'))->getTimestamp());

    ?>

O exemplo acima produzirá algo semelhante a:

    integer(1484854719)
    integer(42)

### Veja Também

- » Referência sobre ObjectId
- » Tipos BSON: ObjectId

# MongoDB\BSON\ObjectId::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\ObjectId::jsonSerialize — Retorna uma representação que pode ser convertida para JSON

### Descrição

final public function MongoDB\BSON\ObjectId::jsonSerialize(): mixed

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna dados que podem ser serializados por json_encode() para produzir uma representação JSON estendida de MongoDB\BSON\ObjectId.

> Nota: A saída é consistente com a função MongoDB\BSON\toJSON(), que usa o formato JSON estendido legado específico do driver. Isso não corresponde necessariamente às representações JSON estendidas » relaxadas ou » canônicas usadas por MongoDB\BSON\toRelaxedExtendedJSON() e MongoDB\BSON\toCanonicalExtendedJSON(), respectivamente.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- JsonSerializable::jsonSerialize() - Especifica os dados que devem ser serializados para JSON
- json_encode() - Retorna a representação JSON de um valor
- MongoDB\BSON\toCanonicalExtendedJSON() - Retorna a representação JSON Estendida Canônica de um valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Retorna a representação JSON Estendida Relaxada de um valor BSON
- » JSON Estendido do MongoDB

# MongoDB\BSON\ObjectId::__toString

(mongodb >=1.0.0)

MongoDB\BSON\ObjectId::__toString — Retorna a representação hexidecimal deste ObjectId

### Descrição

final public function MongoDB\BSON\ObjectId::__toString(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a representação hexidecimal deste ObjectId.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\ObjectId::__toString()

    <?php

    var_dump((string) new MongoDB\BSON\ObjectId());
    var_dump((string) new MongoDB\BSON\ObjectId('000000000000000000000001'));

    ?>

O exemplo acima produzirá algo semelhante a:

    string(24) "56731b49da14d8747d701211"
    string(24) "000000000000000000000001"

### Veja Também

- » Referência sobre ObjectId
- » Tipos BSON: ObjectId

## Índice

- MongoDB\BSON\ObjectId::__construct — Constrói um novo ObjectId
- MongoDB\BSON\ObjectId::getTimestamp — Retorna o componente timestamp deste ObjectId
- MongoDB\BSON\ObjectId::jsonSerialize — Retorna uma representação que pode ser convertida para JSON
- MongoDB\BSON\ObjectId::__toString — Retorna a representação hexidecimal deste ObjectId

# A classe MongoDB\BSON\Regex

(mongodb >=1.0.0)

## Introdução

Tipo BSON para um padrão de expressão regular e » opções adicionais.

> Nota: Este tipo BSON é usado principalmente ao consultar o banco de dados. Alternativamente, o operador de consulta » $regex pode ser usado.

## Resumo da classe

final class MongoDB\BSON\Regex implements MongoDB\BSON\RegexInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Métodos */
final public function __construct(string `$pattern`, string `$flags` = "")
final public function getFlags(): string
final public function getPattern(): string
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Esta classe não implementa mais a interface Serializable.
PECL mongodb 1.12.0 | Implementa Stringable para PHP 8.0+.
PECL mongodb 1.3.0 | Implementa MongoDB\BSON\RegexInterface.
PECL mongodb 1.2.0 | Implementa Serializable e JsonSerializable.

# MongoDB\BSON\Regex::__construct

(mongodb >=1.0.0)

MongoDB\BSON\Regex::__construct — Constrói um novo Regex

### Descrição

final public function MongoDB\BSON\Regex::__construct(string `$pattern`, string `$flags` = "")

### Parâmetros

`pattern` (string)
  A expressão regular.

  > Nota: A expressão não deve ser envolvida por caracteres delimitadores.

`flags` (string)
  As » opções de expressões regulares. Caracteres neste argumento serão ordenados alfabeticamente.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma MongoDB\Driver\Exception\InvalidArgumentException se `pattern` ou `flags` contiverem bytes nulos.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.2.0 | O argumento `flags` é opcional e seu padrão é uma string vazia. Caracteres no argumento `flags` serão ordenados alfabeticamente quando um Regex for construído. Anteriormente, os caracteres seriam armazenados na ordem em que fossem informados. MongoDB\Driver\Exception\InvalidArgumentException é lançada se `pattern` ou `flags` contiverem bytes nulos. Anteriormente, valores seriam truncados no primeiro byte nulo.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\Regex::__construct()

    <?php

    $regex = new MongoDB\BSON\Regex('^foo', 'i');
    var_dump($regex);

    ?>

O exemplo acima produzirá:

    object(MongoDB\BSON\Regex)#1 (2) {
      ["pattern"]=>
      string(4) "^foo"
      ["flags"]=>
      string(1) "i"
    }

### Veja Também

- » Tipos BSON
- » Opções suportadas para expressões regulares

# MongoDB\BSON\Regex::getFlags

(mongodb >=1.0.0)

MongoDB\BSON\Regex::getFlags — Retorna as opções de Regex

### Descrição

final public function MongoDB\BSON\Regex::getFlags(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna as opções de Regex.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\Regex::getFlags()

    <?php

    $regex = new MongoDB\BSON\Regex('regex', 'i');
    var_dump($regex->getFlags());

    ?>

O exemplo acima produzirá algo semelhante a:

    string(1) "i"

### Veja Também

- » Tipos BSON
- » Opções suportadas para expressões regulares

# MongoDB\BSON\Regex::getPattern

(mongodb >=1.0.0)

MongoDB\BSON\Regex::getPattern — Retorna a expressão regular de Regex

### Descrição

final public function MongoDB\BSON\Regex::getPattern(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a expressão regular de Regex.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\Regex::getPattern()

    <?php

    $regex = new MongoDB\BSON\Regex('regex', 'i');
    var_dump($regex->getPattern());

    ?>

O exemplo acima produzirá algo semelhante a:

    string(5) "regex"

### Veja Também

- » Tipos BSON

# MongoDB\BSON\Regex::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Regex::jsonSerialize — Retorna uma representação que pode ser convertida para JSON

### Descrição

final public function MongoDB\BSON\Regex::jsonSerialize(): mixed

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna dados que podem ser serializados por json_encode() para produzir uma representação JSON estendida de MongoDB\BSON\Regex.

> Nota: A saída é consistente com a função MongoDB\BSON\toJSON(), que usa o formato JSON estendido legado específico do driver. Isso não corresponde necessariamente às representações JSON estendidas » relaxadas ou » canônicas usadas por MongoDB\BSON\toRelaxedExtendedJSON() e MongoDB\BSON\toCanonicalExtendedJSON(), respectivamente.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- JsonSerializable::jsonSerialize() - Especifica os dados que devem ser serializados para JSON
- json_encode() - Retorna a representação JSON de um valor
- MongoDB\BSON\toCanonicalExtendedJSON() - Retorna a representação JSON Estendida Canônica de um valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Retorna a representação JSON Estendida Relaxada de um valor BSON
- » JSON Estendido do MongoDB

# MongoDB\BSON\Regex::__toString

(mongodb >=1.0.0)

MongoDB\BSON\Regex::__toString — Retorna a representação em string deste Regex

### Descrição

final public function MongoDB\BSON\Regex::__toString(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a representação em string deste Regex.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\Regex::__toString()

    <?php

    $regex = new MongoDB\BSON\Regex('regex', 'i');
    var_dump((string) $regex);

    ?>

O exemplo acima produzirá:

    string(8) "/regex/i"

### Veja Também

- » Tipos BSON

## Índice

- MongoDB\BSON\Regex::__construct — Constrói um novo Regex
- MongoDB\BSON\Regex::getFlags — Retorna as opções de Regex
- MongoDB\BSON\Regex::getPattern — Retorna a expressão regular de Regex
- MongoDB\BSON\Regex::jsonSerialize — Retorna uma representação que pode ser convertida para JSON
- MongoDB\BSON\Regex::__toString — Retorna a representação em string deste Regex

# A classe MongoDB\BSON\Timestamp

(mongodb >=1.0.0)

## Introdução

Representa um » timestamp BSON. O valor consiste em um timestamp de 4 bytes (ou seja, segundos desde a época) e um incremento de 4 bytes.

> Nota: Este é um tipo interno do MongoDB usado para replicação e fragmentação. Não se destina ao armazenamento geral de datas (MongoDB\BSON\UTCDateTime deve ser usado em seu lugar).

## Resumo da classe

final class MongoDB\BSON\Timestamp implements MongoDB\BSON\TimestampInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Métodos */
final public function __construct(int `$increment`, int `$timestamp`)
final public function getIncrement(): int
final public function getTimestamp(): int
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Esta classe não implementa mais a interface Serializable.
PECL mongodb 1.12.0 | Implementa Stringable para PHP 8.0+.
PECL mongodb 1.3.0 | Implementa MongoDB\BSON\TimestampInterface.
PECL mongodb 1.2.0 | Implementa Serializable e JsonSerializable.

# MongoDB\BSON\Timestamp::__construct

(mongodb >=1.0.0)

MongoDB\BSON\Timestamp::__construct — Constrói um novo Timestamp

### Descrição

final public function MongoDB\BSON\Timestamp::__construct(int `$increment`, int `$timestamp`)

### Parâmetros

`increment` (int)
  Inteiro de 32 bits denotando o ordinal de incremento para operações dentro de um determninado segundo.
`timestamp` (int)
  Inteiro de 32 bits denotando os segundos desde a época Unix.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\Timestamp::__construct()

    <?php

    $timestamp = new MongoDB\BSON\Timestamp(1234, 5678);

    ?>

O exemplo acima produzirá:

    object(MongoDB\BSON\Timestamp)#1 (2) {
      ["increment"]=>
      int(1234)
      ["timestamp"]=>
      int(5678)
    }

### Veja Também

- » Tipos BSON: Timestamps

# MongoDB\BSON\Timestamp::getIncrement

(mongodb >=1.3.0)

MongoDB\BSON\Timestamp::getIncrement — Retorna o componente de incremento deste Timestamp

### Descrição

final public function MongoDB\BSON\Timestamp::getIncrement(): int

O componente de incremento de um Timestamp são seus 32 bits menos significativos, o que denota o ordinal de incremento para operações dentro de um determinado segundo. Este valor é lido como um número inteiro sem sinal de 32 bits com ordem de bytes big-endian.

> Nota: Como o tipo inteiro do PHP possui sinal, alguns valores retornados por este método podem aparecer como números inteiros negativos em plataformas de 32 bits. O formatador `"%u"` de sprintf() pode ser usado para obter uma representação em string do valor decimal sem sinal.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o componente de incremento deste Timestamp.

Aviso

Em sistemas de 32 bits, este método pode retornar um número negativo. Embora as partes de incremento e timestamp do tipo Timestamp do BSON consistam em dois valores sem sinal de 32 bits, o PHP não pode representá-los em plataformas de 32 bits.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- » Tipos BSON: Timestamps

# MongoDB\BSON\Timestamp::getTimestamp

(mongodb >=1.3.0)

MongoDB\BSON\Timestamp::getTimestamp — Retorna o componente de timestamp deste Timestamp

### Descrição

final public function MongoDB\BSON\Timestamp::getTimestamp(): int

O componente de timestamp de um Timestamp são seus 32 bits mais significativos, o que denota o número de segundos desde a época Unix. Este valor é lido como um número inteiro sem sinal de 32 bits com ordem de bytes big-endian.

> Nota: Como o tipo inteiro do PHP possui sinal, alguns valores retornados por este método podem aparecer como números inteiros negativos em plataformas de 32 bits. O formatador `"%u"` de sprintf() pode ser usado para obter uma representação em string do valor decimal sem sinal.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o componente de timestamp deste Timestamp.

Aviso

Em sistemas de 32 bits, este método pode retornar um número negativo. Embora as partes de incremento e timestamp do tipo Timestamp do BSON consistam em dois valores sem sinal de 32 bits, o PHP não pode representá-los em plataformas de 32 bits.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- » Tipos BSON: Timestamps

# MongoDB\BSON\Timestamp::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Timestamp::jsonSerialize — Retorna uma representação que pode ser convertida para JSON

### Descrição

final public function MongoDB\BSON\Timestamp::jsonSerialize(): mixed

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna dados que podem ser serializados por json_encode() para produzir uma representação JSON estendida de MongoDB\BSON\Timestamp.

> Nota: A saída é consistente com a função MongoDB\BSON\toJSON(), que usa o formato JSON estendido legado específico do driver. Isso não corresponde necessariamente às representações JSON estendidas » relaxadas ou » canônicas usadas por MongoDB\BSON\toRelaxedExtendedJSON() e MongoDB\BSON\toCanonicalExtendedJSON(), respectivamente.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- JsonSerializable::jsonSerialize() - Especifica os dados que devem ser serializados para JSON
- json_encode() - Retorna a representação JSON de um valor
- MongoDB\BSON\toCanonicalExtendedJSON() - Retorna a representação JSON Estendida Canônica de um valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Retorna a representação JSON Estendida Relaxada de um valor BSON
- » JSON Estendido do MongoDB

# MongoDB\BSON\Timestamp::__toString

(mongodb >=1.0.0)

MongoDB\BSON\Timestamp::__toString — Retorna a representação em string deste Timestamp

### Descrição

final public function MongoDB\BSON\Timestamp::__toString(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a representação em string deste Timestamp.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\Timestamp::__toString()

    <?php

    $timestamp = new MongoDB\BSON\Timestamp(1234, 5678);
    var_dump((string) $timestamp);

    ?>

O exemplo acima produzirá algo semelhante a:

    string(11) "[1234:5678]"

### Veja Também

- » Tipos BSON: Timestamps

## Índice

- MongoDB\BSON\Timestamp::__construct — Constrói um novo Timestamp
- MongoDB\BSON\Timestamp::getIncrement — Retorna o componente de incremento deste Timestamp
- MongoDB\BSON\Timestamp::getTimestamp — Retorna o componente de timestamp deste Timestamp
- MongoDB\BSON\Timestamp::jsonSerialize — Retorna uma representação que pode ser convertida para JSON
- MongoDB\BSON\Timestamp::__toString — Retorna a representação em string deste Timestamp

# A classe MongoDB\BSON\UTCDateTime

(mongodb >=1.0.0)

## Introdução

Representa uma » data BSON. O valor é um número inteiro de 64 bits que representa o número de milissegundos desde a época Unix (1º de janeiro de 1970). Valores negativos representam datas anteriores a 1970.

## Resumo da classe

final class MongoDB\BSON\UTCDateTime implements MongoDB\BSON\UTCDateTimeInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Métodos */
final public function __construct(int|MongoDB\BSON\Int64|DateTimeInterface|null `$milliseconds` = `null`)
final public function jsonSerialize(): mixed
final public function toDateTime(): DateTime
final public function toDateTimeImmutable(): DateTimeImmutable
final public function __toString(): string
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Esta classe não implementa mais a interface Serializable.
PECL mongodb 1.12.0 | Implementa Stringable para PHP 8.0+.
PECL mongodb 1.3.0 | Implementa MongoDB\BSON\UTCDateTimeInterface.
PECL mongodb 1.2.0 | Implementa Serializable e JsonSerializable.

# MongoDB\BSON\UTCDateTime::__construct

(mongodb >=1.0.0)

MongoDB\BSON\UTCDateTime::__construct — Constrói um novo UTCDateTime

### Descrição

final public function MongoDB\BSON\UTCDateTime::__construct(int|MongoDB\BSON\Int64|DateTimeInterface|null `$milliseconds` = `null`)

### Parâmetros

`milliseconds` (int|MongoDB\BSON\Int64|DateTimeInterface|null)
  Número de milissegundos desde a época Unix (1º de janeiro de 1970). Valores negativos representam datas anteriores a 1970. Este valor pode ser fornecido como um int de 64 bits. Para compatibilidade com sistemas de 32 bits, este parâmetro também pode ser fornecido como um MongoDB\BSON\Int64. Se o argumento for um DateTimeInterface, o número de milissegundos desde a época Unix será derivado desse valor. Se este argumento for `null`, o horário atual será usado por padrão.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | O parâmetro `milliseconds` não aceita mais um argumento string ou float.
PECL mongodb 1.20.0 | O parâmetro `milliseconds` agora aceita um objeto MongoDB\BSON\Int64 (para compatibilidade com plataformas de 32 bits). Especificar um string ou um float foi descontinuado.
PECL mongodb 1.2.0 | O argumento `milliseconds` é opcional e o padrão é `null` (ou seja, horário atual). O argumento também aceita um DateTimeInterface, que pode ser usado para derivar o número de milissegundos desde a época Unix. Anteriormente, apenas os tipos int, float e string eram aceitos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\UTCDateTime::__construct()

    <?php

    var_dump(new MongoDB\BSON\UTCDateTime);

    var_dump(new MongoDB\BSON\UTCDateTime(new DateTime));

    var_dump(new MongoDB\BSON\UTCDateTime(1416445411987));

    ?>

O exemplo acima produzirá algo semelhante a:

    object(MongoDB\BSON\UTCDateTime)#1 (1) {
      ["milliseconds"]=>
      string(13) "1484852905560"
    }
    object(MongoDB\BSON\UTCDateTime)#1 (1) {
      ["milliseconds"]=>
      string(13) "1484852905560"
    }
    object(MongoDB\BSON\UTCDateTime)#1 (1) {
      ["milliseconds"]=>
      string(13) "1416445411987"
    }

### Veja Também

- » Tipos BSON: Data

# MongoDB\BSON\UTCDateTime::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\UTCDateTime::jsonSerialize — Retorna uma representação que pode ser convertida para JSON

### Descrição

final public function MongoDB\BSON\UTCDateTime::jsonSerialize(): mixed

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna dados que podem ser serializados por json_encode() para produzir uma representação JSON estendida de MongoDB\BSON\UTCDateTime.

> Nota: A saída é consistente com a função MongoDB\BSON\toJSON(), que usa o formato JSON estendido legado específico do driver. Isso não corresponde necessariamente às representações JSON estendidas » relaxadas ou » canônicas usadas por MongoDB\BSON\toRelaxedExtendedJSON() e MongoDB\BSON\toCanonicalExtendedJSON(), respectivamente.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- JsonSerializable::jsonSerialize() - Especifica os dados que devem ser serializados para JSON
- json_encode() - Retorna a representação JSON de um valor
- MongoDB\BSON\toCanonicalExtendedJSON() - Retorna a representação JSON Estendida Canônica de um valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Retorna a representação JSON Estendida Relaxada de um valor BSON
- » JSON Estendido do MongoDB

# MongoDB\BSON\UTCDateTime::toDateTime

(mongodb >=1.0.0)

MongoDB\BSON\UTCDateTime::toDateTime — Retorna a representação em DateTime deste UTCDateTime

### Descrição

final public function MongoDB\BSON\UTCDateTime::toDateTime(): DateTime

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a representação em DateTime deste UTCDateTime. O DateTime retornado usará o fuso horário UTC.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\UTCDatetime::toDateTime()

    <?php

    $utcdatetime = new MongoDB\BSON\UTCDateTime(1416445411987);
    $datetime = $utcdatetime->toDateTime();
    var_dump($datetime->format('r'));
    var_dump($datetime->format('U.u'));
    var_dump($datetime->getTimezone());

    ?>

O exemplo acima produzirá algo semelhante a:

    string(31) "Thu, 20 Nov 2014 01:03:31 +0000"
    string(17) "1416445411.987000"
    object(DateTimeZone)#3 (2) {
      ["timezone_type"]=>
      int(1)
      ["timezone"]=>
      string(6) "+00:00"
    }

### Veja Também

- MongoDB\BSON\UTCDateTime::toDateTimeImmutable() - Retorna a representação em DateTimeImmutable deste UTCDateTime
- » Tipos BSON: Data

# MongoDB\BSON\UTCDateTime::toDateTimeImmutable

(mongodb >=1.20.0)

MongoDB\BSON\UTCDateTime::toDateTimeImmutable — Retorna a representação em DateTimeImmutable deste UTCDateTime

### Descrição

final public function MongoDB\BSON\UTCDateTime::toDateTimeImmutable(): DateTimeImmutable

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a representação em DateTimeImmutable deste UTCDateTime. O DateTimeImmutable retornado usará o fuso horário UTC.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\UTCDatetime::toDateTimeImmutable()

    <?php

    $utcdatetime = new MongoDB\BSON\UTCDateTime(1416445411987);
    $datetime = $utcdatetime->toDateTimeImmutable();
    var_dump($datetime->format('r'));
    var_dump($datetime->format('U.u'));
    var_dump($datetime->getTimezone());

    ?>

O exemplo acima produzirá algo semelhante a:

    string(31) "Thu, 20 Nov 2014 01:03:31 +0000"
    string(17) "1416445411.987000"
    object(DateTimeZone)#3 (2) {
      ["timezone_type"]=>
      int(1)
      ["timezone"]=>
      string(6) "+00:00"
    }

### Veja Também

- MongoDB\BSON\UTCDateTime::toDateTime() - Retorna a representação em DateTime deste UTCDateTime
- » Tipos BSON: Data

# MongoDB\BSON\UTCDateTime::__toString

(mongodb >=1.0.0)

MongoDB\BSON\UTCDateTime::__toString — Retorna a representação em string deste UTCDateTime

### Descrição

final public function MongoDB\BSON\UTCDateTime::__toString(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a representação em string deste UTCDateTime.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\UTCDateTime::__toString()

    <?php

    $utcdatetime = new MongoDB\BSON\UTCDateTime(1416445411987);
    var_dump((string) $utcdatetime);

    ?>

O exemplo acima produzirá:

    string(13) "1416445411987"

### Veja Também

- » Tipos BSON: Data

## Índice

- MongoDB\BSON\UTCDateTime::__construct — Constrói um novo UTCDateTime
- MongoDB\BSON\UTCDateTime::jsonSerialize — Retorna uma representação que pode ser convertida para JSON
- MongoDB\BSON\UTCDateTime::toDateTime — Retorna a representação em DateTime deste UTCDateTime
- MongoDB\BSON\UTCDateTime::toDateTimeImmutable — Retorna a representação em DateTimeImmutable deste UTCDateTime
- MongoDB\BSON\UTCDateTime::__toString — Retorna a representação em string deste UTCDateTime

# A interface MongoDB\BSON\Type

(mongodb >=1.0.0)

## Introdução

Interface base abstrata que não deve ser implementada diretamente.

## Resumo da Interface

class MongoDB\BSON\Type {
}

Esta interface não tem métodos. Seu único propósito é ser a interface base para todas as classes do tipo BSON.

# A interface MongoDB\BSON\Persistable

(mongodb >=1.0.0)

## Introdução

As classes podem implementar esta interface para aproveitar o comportamento automático do ODM (mapeamento de documento de objeto) na extensão. Durante a serialização, a extensão injetará uma propriedade __pclass contendo o nome da classe PHP nos dados retornados por MongoDB\BSON\Serializable::bsonSerialize(). Durante a desserialização, a mesma propriedade __pclass será então usada para inferir a classe PHP (independente de qualquer configuração de type map) a ser construída antes de MongoDB\BSON\Unserializable::bsonUnserialize() ser invocada. Consulte Dados Persistentes para obter informações adicionais.

> Nota: Mesmo que MongoDB\BSON\Serializable::bsonSerialize() retorne um array sequencial, a injeção da propriedade __pclass fará com que o objeto seja serializado como um documento BSON.

## Resumo da Interface

class MongoDB\BSON\Persistable implements MongoDB\BSON\Unserializable, MongoDB\BSON\Serializable {
/* Métodos */
abstract public function bsonSerialize(): array|stdClass|MongoDB\BSON\Document
/* Métodos herdados */
abstract public function MongoDB\BSON\Serializable::bsonSerialize(): array|stdClass|MongoDB\BSON\Document|MongoDB\BSON\PackedArray
abstract public function MongoDB\BSON\Unserializable::bsonUnserialize(array `$data`): void
}

# MongoDB\BSON\Persistable::bsonSerialize

(mongodb >=1.0.0)

MongoDB\BSON\Persistable::bsonSerialize — Fornece um array ou documento para serializar como BSON

### Descrição

abstract public function MongoDB\BSON\Persistable::bsonSerialize(): array|stdClass|MongoDB\BSON\Document

Chamado durante a serialização do objeto para BSON. O método precisa retornar um array, uma stdClass ou um MongoDB\BSON\Document.

O valor de retorno sempre será serializado como um documento BSON. O documento serializado irá incluir um campo contendo o nome da classe do objeto. Por esta razão, não é possível retornar uma instância de MongoDB\BSON\PackedArray neste método.

Usuários são encorajados a incluir uma propriedade _id (ex.: um MongoDB\BSON\ObjectId inicializado no construtor) ao retornar dados para um documento nativo BSON. Na ausência se uma propriedade _id, a extensão ou servidor irá gerar um MongoDB\BSON\ObjectId para operações de inserção ou atualização, respectivamente.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array, uma stdClass ou um MongoDB\BSON\Document a ser serializado como um documento BSON.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Os tipos de retorno anteriormente declarados como temporários agora devem ser cumpridos.
PECL mongodb 1.17.0 | Este método agora também pode retornar instâncias de MongoDB\BSON\Document além de um array e uma stdClass.

### Veja Também

- MongoDB\BSON\Serializable::bsonSerialize() - Fornece um array ou documento para serializar como BSON
- MongoDB\BSON\Unserializable::bsonUnserialize() - Constrói o objeto a partir de um array ou documento BSON
- MongoDB\BSON\Persistable
- Dados Persistentes

## Índice

- MongoDB\BSON\Persistable::bsonSerialize — Fornece um array ou documento para serializar como BSON

# A interface MongoDB\BSON\Serializable

(mongodb >=1.0.0)

## Introdução

As classes que implementam esta interface podem retornar dados para serem serializados como um array ou documento BSON no lugar das propriedades públicas do objeto.

## Resumo da Interface

class MongoDB\BSON\Serializable implements MongoDB\BSON\Type {
/* Métodos */
abstract public function bsonSerialize(): array|stdClass|MongoDB\BSON\Document|MongoDB\BSON\PackedArray
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Os tipos de retorno anteriormente declarados como temporários agora devem ser cumpridos.
mongodb 1.15.0 no PECL | Os tipos de retorno para métodos são declarados como provisórios no PHP 8.0 e mais recentes, disparando avisos de descontinuação no código que implementa essa interface sem declarar os tipos de retorno apropriados. O atributo `#[ReturnTypeWillChange]` pode ser adicionado para silenciar o aviso de descontinuação.

# MongoDB\BSON\Serializable::bsonSerialize

(mongodb >=1.0.0)

MongoDB\BSON\Serializable::bsonSerialize — Fornece um array ou documento para serializar como BSON

### Descrição

abstract public function MongoDB\BSON\Serializable::bsonSerialize(): array|stdClass|MongoDB\BSON\Document|MongoDB\BSON\PackedArray

Chamado durante a serialização do objeto para BSON. O método precisa retornar um array, uma stdClass, um MongoDB\BSON\Document ou um MongoDB\BSON\PackedArray.

Documentos raiz (ex.: um MongoDB\BSON\Serializable passado para MongoDB\BSON\Document::fromPHP()) sempre serão serializados como um documento BSON. Para valores de campos, arrays associativos e instâncias de stdClass serão serializados como um documento BSON e arrays sequenciais (isto é, índices numéricos sequenciais iniciando em `0`) serão serializados como um array BSON.

Usuários são encorajados a incluir uma propriedade _id (ex.: um MongoDB\BSON\ObjectId inicializado no construtor) ao retornar dados para um documento nativo BSON. Na ausência de uma propriedade _id, a extensão ou servidor irá gerar um MongoDB\BSON\ObjectId para operações de inserção ou atualização, respectivamente.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array, uma stdClass, um MongoDB\BSON\Document, ou um MongoDB\BSON\PackedArray para ser serializado como um array ou documento BSON.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Os tipos de retorno anteriormente declarados como temporários agora devem ser cumpridos.
PECL mongodb 1.17.0 | O tipo de retorno foi alterado de array|object. Em vez de object, o tipo de retorno agora especifica stdClass. As classes que implementam esta interface devem ser alteradas para não declararem mais um tipo de retorno object. Como o tipo de retorno é provisório, um aviso de descontinuação é emitido no PHP 8.1 e mais recentes. Além das alterações acima, a extensão agora também suporta o retorno de instâncias de MongoDB\BSON\Document e MongoDB\BSON\PackedArray. Observe que quaisquer instâncias de MongoDB\BSON\PackedArray retornadas são convertidas silenciosamente em objetos quando armazenadas como documentos raiz. Eles são armazenados como arrays quando usados ​​como um valor de campo incorporado.

### Exemplos

Exemplo #1 MongoDB\BSON\Serializable::bsonSerialize() retornando um array associativo para documento raiz

    <?php

    class MyDocument implements MongoDB\BSON\Serializable
    {
        private $id;

        function __construct()
        {
            $this->id = new MongoDB\BSON\ObjectId;
        }

        function bsonSerialize(): array
        {
            return ['_id' => $this->id, 'foo' => 'bar'];
        }
    }

    echo MongoDB\BSON\Document::fromPHP(new MyDocument)->toRelaxedExtendedJSON(), "\n";

    ?>

O exemplo acima produzirá algo semelhante a:

    { "_id" : { "$oid" : "56cccdcada14d8755a58c591" }, "foo" : "bar" }

Exemplo #2 MongoDB\BSON\Serializable::bsonSerialize() retornando um array sequencial para documento raiz

    <?php

    class MyArray implements MongoDB\BSON\Serializable
    {
        function bsonSerialize(): array
        {
            return [1, 2, 3];
        }
    }

    echo MongoDB\BSON\Document::fromPHP(new MyArray)->toRelaxedExtendedJSON(), "\n";

    ?>

O exemplo acima produzirá:

    { "0" : 1, "1" : 2, "2" : 3 }

Exemplo #3 MongoDB\BSON\Serializable::bsonSerialize() retornando um array associativo para campo de documento

    <?php

    class MyDocument implements MongoDB\BSON\Serializable
    {
        function bsonSerialize(): array
        {
            return ['foo' => 'bar'];
        }
    }

    $value = ['document' => new MyDocument];

    echo MongoDB\BSON\Document::fromPHP($value)->toRelaxedExtendedJSON(), "\n";

    ?>

O exemplo acima produzirá:

    { "document" : { "foo" : "bar" } }

Exemplo #4 MongoDB\BSON\Serializable::bsonSerialize() retornando um array sequencial para campo de documento

    <?php

    class MyArray implements MongoDB\BSON\Serializable
    {
        function bsonSerialize(): array
        {
            return [1, 2, 3];
        }
    }

    $value = ['array' => new MyArray];

    echo MongoDB\BSON\Document::fromPHP($value)->toRelaxedExtendedJSON(), "\n";

    ?>

O exemplo acima produzirá:

    { "array" : [ 1, 2, 3 ] }

### Veja Também

- MongoDB\BSON\Unserializable::bsonUnserialize() - Constrói o objeto a partir de um array ou documento BSON
- MongoDB\BSON\Persistable
- Dados Persistentes

## Índice

- MongoDB\BSON\Serializable::bsonSerialize — Fornece um array ou documento para serializar como BSON

# A interface MongoDB\BSON\Unserializable

(mongodb >=1.0.0)

## Introdução

As classes que implementam esta interface podem ser especificadas em um mapa de tipos para desserializar arrays e documentos BSON (nativos e incorporados).

## Resumo da Interface

class MongoDB\BSON\Unserializable {
/* Métodos */
abstract public function bsonUnserialize(array `$data`): void
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Os tipos de retorno anteriormente declarados como temporários agora devem ser cumpridos.
mongodb 1.15.0 no PECL | Os tipos de retorno para métodos são declarados como provisórios no PHP 8.0 e mais recentes, disparando avisos de descontinuação no código que implementa essa interface sem declarar os tipos de retorno apropriados. O atributo `#[ReturnTypeWillChange]` pode ser adicionado para silenciar o aviso de descontinuação.

# MongoDB\BSON\Unserializable::bsonUnserialize

(mongodb >=1.0.0)

MongoDB\BSON\Unserializable::bsonUnserialize — Constrói o objeto a partir de um array ou documento BSON

### Descrição

abstract public function MongoDB\BSON\Unserializable::bsonUnserialize(array `$data`): void

Chamado durante a desserialização do objeto a partir do BSON. As propriedades do array ou documento BSON serão passadas ao método como um array.

Lembre-se de considerar uma propriedade _id ao manipular dados a partir de um documento BSON.

> Nota: Este método atua como o construtor do objeto. O método __construct() não será chamado após este método.

### Parâmetros

`data` (array)
  Propriedades dentro do array ou documento BSON.

### Valor Retornado

O valor de retorno deste método é ignorado.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Os tipos de retorno anteriormente declarados como temporários agora devem ser cumpridos.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\Unserializable::bsonUnserialize()

    <?php

    class MyDocument implements MongoDB\BSON\Unserializable
    {
        private $data = [];

        function bsonUnserialize(array $data): void
        {
            $this->data = $data;
        }
    }

    $bson = MongoDB\BSON\Document::fromJSON('{ "foo": "bar" }');

    var_dump($bson->toPHP(['root' => 'MyDocument']));

    ?>

O exemplo acima produzirá:

    object(MyDocument)#1 (1) {
      ["data":"MyDocument":private]=>
      array(1) {
        ["foo"]=>
        string(3) "bar"
      }
    }

### Veja Também

- MongoDB\BSON\Serializable::bsonSerialize() - Fornece um array ou documento para serializar como BSON
- MongoDB\BSON\Persistable
- Dados Persistentes

## Índice

- MongoDB\BSON\Unserializable::bsonUnserialize — Constrói o objeto a partir de um array ou documento BSON

# A interface MongoDB\BSON\BinaryInterface

(mongodb >=1.3.0)

## Introdução

Esta interface é implementada por MongoDB\BSON\Binary para ser usada como um parâmetro, um retorno, ou um tipo de propriedade em classes do usuário.

## Resumo da classe

class MongoDB\BSON\BinaryInterface {
/* Métodos */
abstract public function getData(): string
abstract public function getType(): int
abstract public function __toString(): string
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Os tipos de retorno anteriormente declarados como temporários agora devem ser cumpridos.
mongodb 1.15.0 no PECL | Os tipos de retorno para métodos são declarados como provisórios no PHP 8.0 e mais recentes, disparando avisos de descontinuação no código que implementa essa interface sem declarar os tipos de retorno apropriados. O atributo `#[ReturnTypeWillChange]` pode ser adicionado para silenciar o aviso de descontinuação.

# MongoDB\BSON\BinaryInterface::getData

(mongodb >=1.3.0)

MongoDB\BSON\BinaryInterface::getData — Retorna os dados da BinaryInterface

### Descrição

abstract public function MongoDB\BSON\BinaryInterface::getData(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna os dados da BinaryInterface.

### Veja Também

- MongoDB\BSON\Binary::getData() - Retorna os dados de Binary

# MongoDB\BSON\BinaryInterface::getType

(mongodb >=1.3.0)

MongoDB\BSON\BinaryInterface::getType — Retorna o tipo da BinaryInterface

### Descrição

abstract public function MongoDB\BSON\BinaryInterface::getType(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o tipo da BinaryInterface.

### Veja Também

- MongoDB\BSON\Binary::getType() - Retorna o tipo de Binary

# MongoDB\BSON\BinaryInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\BinaryInterface::__toString — Retorna os dados da BinaryInterface

### Descrição

abstract public function MongoDB\BSON\BinaryInterface::__toString(): string

Este método é um apelido para: MongoDB\BSON\BinaryInterface::getData().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna os dados da BinaryInterface.

### Veja Também

- MongoDB\BSON\BinaryInterface::getData() - Retorna os dados da BinaryInterface
- MongoDB\BSON\Binary::__toString() - Retorna string representando os dados de Binary

## Índice

- MongoDB\BSON\BinaryInterface::getData — Retorna os dados da BinaryInterface
- MongoDB\BSON\BinaryInterface::getType — Retorna o tipo da BinaryInterface
- MongoDB\BSON\BinaryInterface::__toString — Retorna os dados da BinaryInterface

# A interface MongoDB\BSON\Decimal128Interface

(mongodb >=1.3.0)

## Introdução

Esta interface é implementada por MongoDB\BSON\Decimal128 para ser usada como um parâmetro, um retorno, ou um tipo de propriedade em classes do usuário.

## Resumo da classe

class MongoDB\BSON\Decimal128Interface {
/* Métodos */
abstract public function __toString(): string
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Os tipos de retorno anteriormente declarados como temporários agora devem ser cumpridos.
mongodb 1.15.0 no PECL | Os tipos de retorno para métodos são declarados como provisórios no PHP 8.0 e mais recentes, disparando avisos de descontinuação no código que implementa essa interface sem declarar os tipos de retorno apropriados. O atributo `#[ReturnTypeWillChange]` pode ser adicionado para silenciar o aviso de descontinuação.

# MongoDB\BSON\Decimal128Interface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\Decimal128Interface::__toString — Retorna a representação em string deste Decimal128Interface

### Descrição

abstract public function MongoDB\BSON\Decimal128Interface::__toString(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a representação em string deste Decimal128Interface.

### Veja Também

- MongoDB\BSON\Decimal128::__toString() - Retorna a representação em string deste Decimal128

## Índice

- MongoDB\BSON\Decimal128Interface::__toString — Retorna a representação em string deste Decimal128Interface

# A interface MongoDB\BSON\JavascriptInterface

(mongodb >=1.3.0)

## Introdução

Esta interface é implementada por MongoDB\BSON\Javascript para ser usada como um parâmetro, um retorno, ou um tipo de propriedade em classes do usuário.

## Resumo da classe

class MongoDB\BSON\JavascriptInterface {
/* Métodos */
abstract public function getCode(): string
abstract public function getScope(): ?object
abstract public function __toString(): string
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Os tipos de retorno anteriormente declarados como temporários agora devem ser cumpridos.
mongodb 1.15.0 no PECL | Os tipos de retorno para métodos são declarados como provisórios no PHP 8.0 e mais recentes, disparando avisos de descontinuação no código que implementa essa interface sem declarar os tipos de retorno apropriados. O atributo `#[ReturnTypeWillChange]` pode ser adicionado para silenciar o aviso de descontinuação.

# MongoDB\BSON\JavascriptInterface::getCode

(mongodb >=1.3.0)

MongoDB\BSON\JavascriptInterface::getCode — Retorna o código da JavascriptInterface

### Descrição

abstract public function MongoDB\BSON\JavascriptInterface::getCode(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o código da JavascriptInterface.

### Veja Também

- MongoDB\BSON\Javascript::getCode() - Retorna o código do Javascript

# MongoDB\BSON\JavascriptInterface::getScope

(mongodb >=1.3.0)

MongoDB\BSON\JavascriptInterface::getScope — Retorna o documento de escopo da JavascriptInterface

### Descrição

abstract public function MongoDB\BSON\JavascriptInterface::getScope(): ?object

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o documento de escopo da JavascriptInterface.

### Veja Também

- MongoDB\BSON\Javascript::getScope() - Retorna o documento de escopo do Javascript

# MongoDB\BSON\JavascriptInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\JavascriptInterface::__toString — Retorna o código da JavascriptInterface

### Descrição

abstract public function MongoDB\BSON\JavascriptInterface::__toString(): string

Este método é um apelido para: MongoDB\BSON\JavascriptInterface::getCode().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o código da JavascriptInterface.

### Veja Também

- MongoDB\BSON\JavascriptInterface::getCode() - Retorna o código da JavascriptInterface
- MongoDB\BSON\Javascript::__toString() - Retorna o código do Javascript

## Índice

- MongoDB\BSON\JavascriptInterface::getCode — Retorna o código da JavascriptInterface
- MongoDB\BSON\JavascriptInterface::getScope — Retorna o documento de escopo da JavascriptInterface
- MongoDB\BSON\JavascriptInterface::__toString — Retorna o código da JavascriptInterface

# A interface MongoDB\BSON\MaxKeyInterface

(mongodb >=1.3.0)

## Introdução

Esta interface é implementada por MongoDB\BSON\MaxKey para ser usada como um parâmetro, um retorno, ou um tipo de propriedade em classes do usuário.

## Resumo da classe

class MongoDB\BSON\MaxKeyInterface {
}

Esta interface não tem métodos.

# A interface MongoDB\BSON\MinKeyInterface

(mongodb >=1.3.0)

## Introdução

Esta interface é implementada por MongoDB\BSON\MinKey para ser usada como um parâmetro, um retorno, ou um tipo de propriedade em classes do usuário.

## Resumo da classe

class MongoDB\BSON\MinKeyInterface {
}

Esta interface não tem métodos.

# A interface MongoDB\BSON\ObjectIdInterface

(mongodb >=1.3.0)

## Introdução

Esta interface é implementada por MongoDB\BSON\ObjectId para ser usada como um parâmetro, um retorno, ou um tipo de propriedade em classes do usuário.

## Resumo da classe

class MongoDB\BSON\ObjectIdInterface {
/* Métodos */
abstract public function getTimestamp(): int
abstract public function __toString(): string
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Os tipos de retorno anteriormente declarados como temporários agora devem ser cumpridos.
mongodb 1.15.0 no PECL | Os tipos de retorno para métodos são declarados como provisórios no PHP 8.0 e mais recentes, disparando avisos de descontinuação no código que implementa essa interface sem declarar os tipos de retorno apropriados. O atributo `#[ReturnTypeWillChange]` pode ser adicionado para silenciar o aviso de descontinuação.

# MongoDB\BSON\ObjectIdInterface::getTimestamp

(mongodb >=1.3.0)

MongoDB\BSON\ObjectIdInterface::getTimestamp — etorna o componente timestamp deste ObjectIdInterface

### Descrição

abstract public function MongoDB\BSON\ObjectIdInterface::getTimestamp(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

etorna o componente timestamp deste ObjectIdInterface.

### Veja Também

- MongoDB\BSON\ObjectId::getTimestamp() - Retorna o componente timestamp deste ObjectId

# MongoDB\BSON\ObjectIdInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\ObjectIdInterface::__toString — Retorna a representação hexidecimal deste ObjectIdInterface

### Descrição

abstract public function MongoDB\BSON\ObjectIdInterface::__toString(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a representação hexidecimal deste ObjectIdInterface.

### Veja Também

- MongoDB\BSON\ObjectId::__toString() - Retorna a representação hexidecimal deste ObjectId

## Índice

- MongoDB\BSON\ObjectIdInterface::getTimestamp — etorna o componente timestamp deste ObjectIdInterface
- MongoDB\BSON\ObjectIdInterface::__toString — Retorna a representação hexidecimal deste ObjectIdInterface

# A interface MongoDB\BSON\RegexInterface

(mongodb >=1.3.0)

## Introdução

Esta interface é implementada por MongoDB\BSON\Regex para ser usada como um parâmetro, um retorno, ou um tipo de propriedade em classes do usuário.

## Resumo da classe

class MongoDB\BSON\RegexInterface {
/* Métodos */
abstract public function getFlags(): string
abstract public function getPattern(): string
abstract public function __toString(): string
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Os tipos de retorno anteriormente declarados como temporários agora devem ser cumpridos.
mongodb 1.15.0 no PECL | Os tipos de retorno para métodos são declarados como provisórios no PHP 8.0 e mais recentes, disparando avisos de descontinuação no código que implementa essa interface sem declarar os tipos de retorno apropriados. O atributo `#[ReturnTypeWillChange]` pode ser adicionado para silenciar o aviso de descontinuação.

# MongoDB\BSON\RegexInterface::getFlags

(mongodb >=1.3.0)

MongoDB\BSON\RegexInterface::getFlags — Retorna as opções de RegexInterface

### Descrição

abstract public function MongoDB\BSON\RegexInterface::getFlags(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna as opções de RegexInterface.

### Veja Também

- MongoDB\BSON\Regex::getFlags() - Retorna as opções de Regex

# MongoDB\BSON\RegexInterface::getPattern

(mongodb >=1.3.0)

MongoDB\BSON\RegexInterface::getPattern — Retorna a expressão regular de RegexInterface

### Descrição

abstract public function MongoDB\BSON\RegexInterface::getPattern(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a expressão regular de RegexInterface.

### Veja Também

- MongoDB\BSON\Regex::getPattern() - Retorna a expressão regular de Regex

# MongoDB\BSON\RegexInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\RegexInterface::__toString — Retorna a representação em string deste RegexInterface

### Descrição

abstract public function MongoDB\BSON\RegexInterface::__toString(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a representação em string deste RegexInterface.

### Veja Também

- MongoDB\BSON\Regex::__toString() - Retorna a representação em string deste Regex

## Índice

- MongoDB\BSON\RegexInterface::getFlags — Retorna as opções de RegexInterface
- MongoDB\BSON\RegexInterface::getPattern — Retorna a expressão regular de RegexInterface
- MongoDB\BSON\RegexInterface::__toString — Retorna a representação em string deste RegexInterface

# A interface MongoDB\BSON\TimestampInterface

(mongodb >=1.3.0)

## Introdução

Esta interface é implementada por MongoDB\BSON\Timestamp para ser usada como um parâmetro, um retorno, ou um tipo de propriedade em classes do usuário.

## Resumo da classe

class MongoDB\BSON\TimestampInterface {
/* Métodos */
abstract public function getIncrement(): int
abstract public function getTimestamp(): int
abstract public function __toString(): string
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Os tipos de retorno anteriormente declarados como temporários agora devem ser cumpridos.
mongodb 1.15.0 no PECL | Os tipos de retorno para métodos são declarados como provisórios no PHP 8.0 e mais recentes, disparando avisos de descontinuação no código que implementa essa interface sem declarar os tipos de retorno apropriados. O atributo `#[ReturnTypeWillChange]` pode ser adicionado para silenciar o aviso de descontinuação.

# MongoDB\BSON\TimestampInterface::getIncrement

(mongodb >=1.3.0)

MongoDB\BSON\TimestampInterface::getIncrement — Retorna o componente de incremento deste TimestampInterface

### Descrição

abstract public function MongoDB\BSON\TimestampInterface::getIncrement(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o componente de incremento deste TimestampInterface.

Aviso

Em sistemas de 32 bits, este método pode retornar um número negativo. Embora as partes de incremento e timestamp do tipo Timestamp do BSON consistam em dois valores sem sinal de 32 bits, o PHP não pode representá-los em plataformas de 32 bits.

### Veja Também

- MongoDB\BSON\Timestamp::getIncrement() - Retorna o componente de incremento deste Timestamp

# MongoDB\BSON\TimestampInterface::getTimestamp

(mongodb >=1.3.0)

MongoDB\BSON\TimestampInterface::getTimestamp — Retorna o componente de timestamp deste TimestampInterface

### Descrição

abstract public function MongoDB\BSON\TimestampInterface::getTimestamp(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o componente de timestamp deste TimestampInterface.

Aviso

Em sistemas de 32 bits, este método pode retornar um número negativo. Embora as partes de incremento e timestamp do tipo Timestamp do BSON consistam em dois valores sem sinal de 32 bits, o PHP não pode representá-los em plataformas de 32 bits.

### Veja Também

- MongoDB\BSON\Timestamp::getTimestamp() - Retorna o componente de timestamp deste Timestamp

# MongoDB\BSON\TimestampInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\TimestampInterface::__toString — Retorna a representação em string deste TimestampInterface

### Descrição

abstract public function MongoDB\BSON\TimestampInterface::__toString(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a representação em string deste TimestampInterface.

### Veja Também

- MongoDB\BSON\Timestamp::__toString() - Retorna a representação em string deste Timestamp

## Índice

- MongoDB\BSON\TimestampInterface::getIncrement — Retorna o componente de incremento deste TimestampInterface
- MongoDB\BSON\TimestampInterface::getTimestamp — Retorna o componente de timestamp deste TimestampInterface
- MongoDB\BSON\TimestampInterface::__toString — Retorna a representação em string deste TimestampInterface

# A interface MongoDB\BSON\UTCDateTimeInterface

(mongodb >=1.3.0)

## Introdução

Esta interface é implementada por MongoDB\BSON\UTCDateTime para ser usada como um parâmetro, um retorno, ou um tipo de propriedade em classes do usuário.

## Resumo da classe

class MongoDB\BSON\UTCDateTimeInterface {
/* Métodos */
abstract public function toDateTime(): DateTime
abstract public function toDateTimeImmutable(): DateTimeImmutable
abstract public function __toString(): string
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Os tipos de retorno anteriormente declarados como temporários agora devem ser cumpridos.
mongodb 1.15.0 no PECL | Os tipos de retorno para métodos são declarados como provisórios no PHP 8.0 e mais recentes, disparando avisos de descontinuação no código que implementa essa interface sem declarar os tipos de retorno apropriados. O atributo `#[ReturnTypeWillChange]` pode ser adicionado para silenciar o aviso de descontinuação.

# MongoDB\BSON\UTCDateTimeInterface::toDateTime

(mongodb >=1.3.0)

MongoDB\BSON\UTCDateTimeInterface::toDateTime — Retorna a representação em DateTime deste UTCDateTimeInterface

### Descrição

abstract public function MongoDB\BSON\UTCDateTimeInterface::toDateTime(): DateTime

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a representação em DateTime deste UTCDateTimeInterface. O DateTime retornado deve usar o fuso horário UTC.

### Veja Também

- MongoDB\BSON\UTCDateTime::toDateTime() - Retorna a representação em DateTime deste UTCDateTime

# MongoDB\BSON\UTCDateTimeInterface::toDateTimeImmutable

(mongodb >=2.0.0)

MongoDB\BSON\UTCDateTimeInterface::toDateTimeImmutable — Retorna a representação DateTimeImmutable desta UTCDateTimeInterface

### Descrição

abstract public function MongoDB\BSON\UTCDateTimeInterface::toDateTimeImmutable(): DateTimeImmutable

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a representação DateTimeImmutable desta UTCDateTimeInterface. O DateTimeImmutable retornado usará o fuso horário UTC.

### Veja Também

- MongoDB\BSON\UTCDateTime::toDateTimeImmutable() - Retorna a representação em DateTimeImmutable deste UTCDateTime

# MongoDB\BSON\UTCDateTimeInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\UTCDateTimeInterface::__toString — Retorna a representação em string deste UTCDateTimeInterface

### Descrição

abstract public function MongoDB\BSON\UTCDateTimeInterface::__toString(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a representação em string deste UTCDateTimeInterface.

### Veja Também

- MongoDB\BSON\UTCDateTime::__toString() - Retorna a representação em string deste UTCDateTime

## Índice

- MongoDB\BSON\UTCDateTimeInterface::toDateTime — Retorna a representação em DateTime deste UTCDateTimeInterface
- MongoDB\BSON\UTCDateTimeInterface::toDateTimeImmutable — Retorna a representação DateTimeImmutable desta UTCDateTimeInterface
- MongoDB\BSON\UTCDateTimeInterface::__toString — Retorna a representação em string deste UTCDateTimeInterface

# A classe MongoDB\BSON\DBPointer

(mongodb >=1.4.0)

## Introdução

Tipo BSON para o tipo "DBPointer". Este tipo BSON está preterido e esta classe não pode ser instanciada. Ele será criado a partir de um tipo BSON DBPointer durante a conversão de BSON para PHP e também pode ser convertida de volta para BSON durante o armazenamento de documentos no banco de dados.

## Resumo da classe

final class MongoDB\BSON\DBPointer implements MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Métodos */
final private function __construct()
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Esta classe não implementa mais a interface Serializable.
PECL mongodb 1.12.0 | Implementa Stringable para PHP 8.0+.

# MongoDB\BSON\DBPointer::__construct

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::__construct — Constrói um novo DBPointer (não utilizado)

### Descrição

final private function MongoDB\BSON\DBPointer::__construct()

Objetos MongoDB\BSON\DBPointer são criados através da conversão de um tipo BSON preterido e não podem ser construídos diretamente.

### Parâmetros

Esta função não possui parâmetros.

### Veja Também

- » Tipos BSON

# MongoDB\BSON\DBPointer::jsonSerialize

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::jsonSerialize — Retorna uma representação que pode ser convertida para JSON

### Descrição

final public function MongoDB\BSON\DBPointer::jsonSerialize(): mixed

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna dados que podem ser serializados por json_encode() para produzir uma representação JSON estendida de MongoDB\BSON\DBPointer.

> Nota: A saída é consistente com a função MongoDB\BSON\toJSON(), que usa o formato JSON estendido legado específico do driver. Isso não corresponde necessariamente às representações JSON estendidas » relaxadas ou » canônicas usadas por MongoDB\BSON\toRelaxedExtendedJSON() e MongoDB\BSON\toCanonicalExtendedJSON(), respectivamente.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- JsonSerializable::jsonSerialize() - Especifica os dados que devem ser serializados para JSON
- json_encode() - Retorna a representação JSON de um valor
- MongoDB\BSON\toCanonicalExtendedJSON() - Retorna a representação JSON Estendida Canônica de um valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Retorna a representação JSON Estendida Relaxada de um valor BSON
- » JSON Estendido do MongoDB

# MongoDB\BSON\DBPointer::__toString

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::__toString — Retorna uma string vazia

### Descrição

final public function MongoDB\BSON\DBPointer::__toString(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string vazia.

### Veja Também

- » Tipos BSON

## Índice

- MongoDB\BSON\DBPointer::__construct — Constrói um novo DBPointer (não utilizado)
- MongoDB\BSON\DBPointer::jsonSerialize — Retorna uma representação que pode ser convertida para JSON
- MongoDB\BSON\DBPointer::__toString — Retorna uma string vazia

# A classe MongoDB\BSON\Int64

(mongodb >=1.5.0)

## Introdução

Tipo BSON para um número inteiro de 64 bits. Ao decodificar dados BSON para PHP, esta classe é usada quando um número inteiro de 64 bits não pode ser representado como um número inteiro PHP em plataformas de 32 bits. Esses objetos suportam operadores sobrecarregados aritméticos, binários e comparativos.

Ao trabalhar com dados BSON brutos através das classes MongoDB\BSON\Document, MongoDB\BSON\PackedArray e MongoDB\BSON\Iterator, qualquer número inteiro de 64 bits será retornado como uma instância desta classe, independentemente da plataforma e se o valor pode ser representado como um número inteiro PHP. Isso garante que os valores possam ser percorridos sem alterar o tipo.

Durante a codificação BSON, os objetos desta classe serão convertidos novamente para um tipo inteiro de 64 bits, mesmo se o valor couber em um número inteiro de 32 bits. Isso permite armazenar valores como inteiros de 64 bits explicitamente no BSON.

## Resumo da classe

final class MongoDB\BSON\Int64 implements MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Métodos */
final public function __construct(int|string `$value`)
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Esta classe não implementa mais a interface Serializable.
PECL mongodb 1.16.0 | A classe agora pode ser instanciada em todas as plataformas. Adicionado suporte para operadores sobrecarregados aritméticos, binários e comparativos.
PECL mongodb 1.12.0 | Implementa Stringable para PHP 8.0+.

# MongoDB\BSON\Int64::__construct

(mongodb >=1.5.0)

MongoDB\BSON\Int64::__construct — Constrói um novo Int64

### Descrição

final public function MongoDB\BSON\Int64::__construct(int|string `$value`)

Cria uma nova instância de MongoDB\BSON\Int64 para o valor inteiro informado.

### Parâmetros

`value` (int|string)
  O valor a ser atribuído à instância Int64. Este valor pode ser fornecido como um int ou string, sendo o último necessário em plataformas de 32 bits para representar valores de 64 bits.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.16.0 | Este método foi tornado público para oferecer suporte à criação de instâncias Int64 ao trabalhar com BSON bruto.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.
- Lança uma MongoDB\Driver\Exception\InvalidArgumentException se a string `value` não puder ser interpretada como um inteiro de 64 bits.

### Veja Também

- » Tipos BSON

# MongoDB\BSON\Int64::jsonSerialize

(mongodb >=1.5.0)

MongoDB\BSON\Int64::jsonSerialize — Retorna uma representação que pode ser convertida para JSON

### Descrição

final public function MongoDB\BSON\Int64::jsonSerialize(): mixed

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna dados que podem ser serializados por json_encode() para produzir uma representação JSON estendida de MongoDB\BSON\Int64.

> Nota: O resultado é consistente com a função MongoDB\BSON\toCanonicalExtendedJSON(), que usa o formato JSON estendido » canônico. Isso difere de outras classes BSON, que usam o formato JSON estendido herdado específico do driver (MongoDB\BSON\toJSON()), para garantir que o valor inteiro de 64 bits seja representado corretamente em plataformas 32 bits.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- JsonSerializable::jsonSerialize() - Especifica os dados que devem ser serializados para JSON
- json_encode() - Retorna a representação JSON de um valor
- MongoDB\BSON\toCanonicalExtendedJSON() - Retorna a representação JSON Estendida Canônica de um valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Retorna a representação JSON Estendida Relaxada de um valor BSON
- » JSON Estendido do MongoDB

# MongoDB\BSON\Int64::__toString

(mongodb >=1.5.0)

MongoDB\BSON\Int64::__toString — Retorna a representação em string deste Int64

### Descrição

final public function MongoDB\BSON\Int64::__toString(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a representação em string deste Int64.

### Exemplos

Exemplo #1 Exemplo de MongoDB\BSON\Int64::__toString()

    <?php

    $int64 = new MongoDB\BSON\Int64('9223372036854775807');

    var_dump((string) $int64);

    ?>

O exemplo acima produzirá algo semelhante a:

    string(19) "9223372036854775807"

### Veja Também

- » Tipos BSON

## Índice

- MongoDB\BSON\Int64::__construct — Constrói um novo Int64
- MongoDB\BSON\Int64::jsonSerialize — Retorna uma representação que pode ser convertida para JSON
- MongoDB\BSON\Int64::__toString — Retorna a representação em string deste Int64

# A classe MongoDB\BSON\Symbol

(mongodb >=1.4.0)

## Introdução

Tipo BSON para o tipo "Símbolo". Este tipo BSON está preterido e esta classe não pode ser instanciada. Ele será criado a partir de um tipo de símbolo BSON durante a conversão de BSON para PHP e também pode ser convertido novamente em BSON durante o armazenamento de documentos no banco de dados.

## Resumo da classe

final class MongoDB\BSON\Symbol implements MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Métodos */
final private function __construct()
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Esta classe não implementa mais a interface Serializable.
PECL mongodb 1.12.0 | Implementa Stringable para PHP 8.0+.

# MongoDB\BSON\Symbol::__construct

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::__construct — Constrói um novo Symbol (não utilizado)

### Descrição

final private function MongoDB\BSON\Symbol::__construct()

Objetos MongoDB\BSON\Symbol são criados através de conversão de um tipo descontinuado do BSON e não podem ser construídos diretamente.

### Parâmetros

Esta função não possui parâmetros.

### Veja Também

- » Tipos BSON

# MongoDB\BSON\Symbol::jsonSerialize

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::jsonSerialize — Retorna uma representação que pode ser convertida para JSON

### Descrição

final public function MongoDB\BSON\Symbol::jsonSerialize(): mixed

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna dados que podem ser serializados por json_encode() para produzir uma representação JSON estendida de MongoDB\BSON\Symbol.

> Nota: A saída é consistente com a função MongoDB\BSON\toJSON(), que usa o formato JSON estendido legado específico do driver. Isso não corresponde necessariamente às representações JSON estendidas » relaxadas ou » canônicas usadas por MongoDB\BSON\toRelaxedExtendedJSON() e MongoDB\BSON\toCanonicalExtendedJSON(), respectivamente.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- JsonSerializable::jsonSerialize() - Especifica os dados que devem ser serializados para JSON
- json_encode() - Retorna a representação JSON de um valor
- MongoDB\BSON\toCanonicalExtendedJSON() - Retorna a representação JSON Estendida Canônica de um valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Retorna a representação JSON Estendida Relaxada de um valor BSON
- » JSON Estendido do MongoDB

# MongoDB\BSON\Symbol::__toString

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::__toString — Retorna o Symbol como uma string

### Descrição

final public function MongoDB\BSON\Symbol::__toString(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a representação em string deste Symbol.

### Veja Também

- » Tipos BSON

## Índice

- MongoDB\BSON\Symbol::__construct — Constrói um novo Symbol (não utilizado)
- MongoDB\BSON\Symbol::jsonSerialize — Retorna uma representação que pode ser convertida para JSON
- MongoDB\BSON\Symbol::__toString — Retorna o Symbol como uma string

# A classe MongoDB\BSON\Undefined

(mongodb >=1.4.0)

## Introdução

Tipo BSON para o tipo "Undefined". Este tipo BSON está preterido e esta classe não pode ser instanciada. Ele será criado a partir de um tipo indefinido BSON durante a conversão de BSON para PHP e também pode ser convertido novamente em BSON durante o armazenamento de documentos no banco de dados.

## Resumo da classe

final class MongoDB\BSON\Undefined implements MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Métodos */
final private function __construct()
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Esta classe não implementa mais a interface Serializable.
PECL mongodb 1.12.0 | Implementa Stringable para PHP 8.0+.

# MongoDB\BSON\Undefined::__construct

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::__construct — Constrói um novo Undefined (não utilizado)

### Descrição

final private function MongoDB\BSON\Undefined::__construct()

Objetos MongoDB\BSON\Undefined são criados através de conversão de um tipo descontinuado do BSON e não podem ser construídos diretamente.

### Parâmetros

Esta função não possui parâmetros.

### Veja Também

- » Tipos BSON

# MongoDB\BSON\Undefined::jsonSerialize

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::jsonSerialize — Retorna uma representação que pode ser convertida para JSON

### Descrição

final public function MongoDB\BSON\Undefined::jsonSerialize(): mixed

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna dados que podem ser serializados por json_encode() para produzir uma representação JSON estendida de MongoDB\BSON\Undefined.

> Nota: A saída é consistente com a função MongoDB\BSON\toJSON(), que usa o formato JSON estendido legado específico do driver. Isso não corresponde necessariamente às representações JSON estendidas » relaxadas ou » canônicas usadas por MongoDB\BSON\toRelaxedExtendedJSON() e MongoDB\BSON\toCanonicalExtendedJSON(), respectivamente.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- JsonSerializable::jsonSerialize() - Especifica os dados que devem ser serializados para JSON
- json_encode() - Retorna a representação JSON de um valor
- MongoDB\BSON\toCanonicalExtendedJSON() - Retorna a representação JSON Estendida Canônica de um valor BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Retorna a representação JSON Estendida Relaxada de um valor BSON
- » JSON Estendido do MongoDB

# MongoDB\BSON\Undefined::__toString

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::__toString — Retorna uma string vazia

### Descrição

final public function MongoDB\BSON\Undefined::__toString(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string vazia.

### Veja Também

- » Tipos BSON

## Índice

- MongoDB\BSON\Undefined::__construct — Constrói um novo Undefined (não utilizado)
- MongoDB\BSON\Undefined::jsonSerialize — Retorna uma representação que pode ser convertida para JSON
- MongoDB\BSON\Undefined::__toString — Retorna uma string vazia

# Classes de monitoramento e funções assinantes

## Índice

- Funções
- MongoDB\Driver\Monitoring\CommandFailedEvent
- MongoDB\Driver\Monitoring\CommandStartedEvent
- MongoDB\Driver\Monitoring\CommandSucceededEvent
- MongoDB\Driver\Monitoring\ServerChangedEvent
- MongoDB\Driver\Monitoring\ServerClosedEvent
- MongoDB\Driver\Monitoring\ServerOpeningEvent
- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent
- MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent
- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent
- MongoDB\Driver\Monitoring\TopologyChangedEvent
- MongoDB\Driver\Monitoring\TopologyClosedEvent
- MongoDB\Driver\Monitoring\TopologyOpeningEvent
- MongoDB\Driver\Monitoring\CommandSubscriber
- MongoDB\Driver\Monitoring\LogSubscriber
- MongoDB\Driver\Monitoring\SDAMSubscriber
- MongoDB\Driver\Monitoring\Subscriber

# Funções

# MongoDB\Driver\Monitoring\addSubscriber

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\addSubscriber — Registra um assinante de evento de monitoramento globalmente

### Descrição

function MongoDB\Driver\Monitoring\addSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void

Registra um assinante de evento de monitoramento globalmente. O assinante será notificado de todos os eventos da extensão para qualquer Maanger.

> Nota: Se o `subscriber` já estiver registrado globalmente, esta função não fará nenhuma ação. Se o `subscriber` também estiver registrado com um ou mais Managers, ele ainda será notificado apenas uma vez sobre cada evento para cada Manager.

### Parâmetros

`subscriber` (MongoDB\Driver\Monitoring\Subscriber)
  Um assinante de evento de monitoramento para registrar globalmente.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Monitoring\removeSubscriber() - Cancela o registro de um assinante de evento de monitoramento globalmente
- MongoDB\Driver\Monitoring\Subscriber
- MongoDB\Driver\Monitoring\CommandSubscriber
- MongoDB\Driver\Manager::addSubscriber() - Inscreve um assinante de evento de monitoramento com este gerenciador
- Monitoramento de Desempenho de Aplicação (APM)

# MongoDB\Driver\Monitoring\removeSubscriber

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\removeSubscriber — Cancela o registro de um assinante de evento de monitoramento globalmente

### Descrição

function MongoDB\Driver\Monitoring\removeSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void

Cancela o registro de um assinante de evento de monitoramento globalmente.

> Nota: Se o `subscriber` já não estiver registrado globalmente, esta função não fará nenhuma ação.

### Parâmetros

`subscriber` (MongoDB\Driver\Monitoring\Subscriber)
  Um assinante de evento de monitoramento para cancelar o registro globalmente.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Monitoring\addSubscriber() - Registra um assinante de evento de monitoramento globalmente
- MongoDB\Driver\Monitoring\Subscriber
- MongoDB\Driver\Monitoring\CommandSubscriber
- MongoDB\Driver\Manager::removeSubscriber() - Cancela o registro de um assinante de evento de monitoramento com este gerenciador
- Monitoramento de Desempenho de Aplicação (APM)

## Índice

- MongoDB\Driver\Monitoring\addSubscriber — Registra um assinante de evento de monitoramento globalmente
- MongoDB\Driver\Monitoring\removeSubscriber — Cancela o registro de um assinante de evento de monitoramento globalmente

# A classe MongoDB\Driver\Monitoring\CommandFailedEvent

(mongodb >=1.3.0)

## Introdução

A classe MongoDB\Driver\Monitoring\CommandFailedEvent encapsula informação sobre um comando falhado.

## Resumo da classe

final class MongoDB\Driver\Monitoring\CommandFailedEvent {
/* Propriedades */
public readonly string $host;
public readonly int $port;
public readonly string $commandName;
public readonly string $databaseName;
public readonly int $duration;
public readonly Exception $error;
public readonly object $reply;
public readonly string $operationId;
public readonly string $requestId;
public readonly ?MongoDB\BSON\ObjectId $serviceId;
public readonly ?int $serverConnectionId;
/* Métodos */
final public function getCommandName(): string
final public function getDatabaseName(): string
final public function getDurationMicros(): int
final public function getError(): Exception
final public function getHost(): string
final public function getOperationId(): string
final public function getPort(): int
final public function getReply(): object
final public function getRequestId(): string
final public function getServer(): MongoDB\Driver\Server
final public function getServerConnectionId(): ?int
final public function getServiceId(): ?MongoDB\BSON\ObjectId
}

## Propriedades

host
  O nome do host do servidor que executou o comando.
port
  A porta do servidor que executou o comando.
commandName
  O nome do comando.
databaseName
  O nome do banco de dados.
duration
  A duração do comando em microssegundos. A duração é um valor calculado que inclui o tempo para enviar a mensagem e receber a resposta do servidor.
error
  A exceção que foi lançada quando o comando falhou.
reply
  O documento de resposta de falha retornado pelo servidor.
operationId
  O ID da operação. Ele pode ser usado para vincular eventos, como gravações em lote, que podem disparar vários comandos.
requestId
  O ID da solicitação. Isso pode ser usado para associar este MongoDB\Driver\Monitoring\CommandFailedEvent a um evento correspondente MongoDB\Driver\Monitoring\CommandStartedEvent.
serviceId
  O ID do serviço, ou `null` se o servidor não o suportar (ou seja, não estiver usando o modo de balanceamento de carga).
serverConnectionId
  O ID de conexão do servidor, ou `null` se não estiver disponível.

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.3.0 | Adicionadas propriedades públicas readonly. A propriedade duration substitui o método getDurationMicros().

# MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName — Retorna o nome do comando

### Descrição

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName(): string

Retorna o nome do comando (ex: `"find"`, `"aggregate"`).

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o nome do comando.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- Monitoramento de Desempenho de Aplicação (APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName

(mongodb >=1.19.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName — Retorna o banco de dados no qual o comando foi executado

### Descrição

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o banco de dados no qual o comando foi executado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- Monitoramento de Desempenho de Aplicação (APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros — Retorna a duração do comando em microssegundos

### Descrição

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros(): int

A duração do comando é um valor calculado que inclui o tempo para enviar a mensagem e receber a resposta do servidor.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a duração do comando em microssegundos.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- Monitoramento de Desempenho de Aplicação (APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getError

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getError — Retorna a exceção associada ao comando com falha

### Descrição

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getError(): Exception

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a Exception associada ao comando com falha.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- Monitoramento de Desempenho de Aplicação (APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getHost

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getHost — Retorna o nome do servidor para o comando

### Descrição

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getHost(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o nome do servidor no qual o comando foi executado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId — Retorna o ID da operação do comando

### Descrição

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId(): string

O ID da operação é gerado pela extensão e pode ser usado para vincular eventos, como operações de gravação em massa, que podem ter sido divididas em vários comandos no nível do protocolo.

> Nota: Como vários comandos podem compartilhar o mesmo ID de operação, não é confiável usar esse valor para associar objetos de evento entre si. O ID da solicitação retornado por MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId() deve ser usado nesse caso.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ID da operação do comando.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId() - Retorna o ID da operação do comando
- MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId() - Retorna o ID da solicitação do comando
- Monitoramento de Desempenho de Aplicação (APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getPort

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getPort — Retorna a porta do servidor para o comando

### Descrição

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getPort(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a porta do servidor em que o comando foi executado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Monitoring\CommandFailedEvent::getReply

(mongodb >=1.5.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getReply — Retorna o documento de resposta do comando

### Descrição

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getReply(): object

O documento de resposta será convertido de BSON para PHP usando as regras padrão de desserialização (por exemplo, documentos BSON serão convertidos para stdClass).

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o documento de resposta do comando como um objeto stdClass.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- Monitoramento de Desempenho de Aplicação (APM)
- Dados Persistentes

# MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId — Retorna o ID da solicitação do comando

### Descrição

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId(): string

O ID da solicitação é gerado pela extensão e pode ser usado para associar este MongoDB\Driver\Monitoring\CommandFailedEvent a um MongoDB\Driver\Monitoring\CommandStartedEvent anterior.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ID da solicitação do comando.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId() - Retorna o ID da solicitação do comando
- Monitoramento de Desempenho de Aplicação (APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getServer

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getServer — Retorna o servidor no qual o comando foi executado

Aviso

Este método foi DESCONTINUADO a partir da versão de extensão 1.20.0 e foi removido na versão 2.0. As aplicações devem usar MongoDB\Driver\Monitoring\CommandFailedEvent::getHost() e MongoDB\Driver\Monitoring\CommandFailedEvent::getPort() em seu lugar.

### Descrição

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getServer(): MongoDB\Driver\Server

Retorna o MongoDB\Driver\Server no qual o comando foi executado.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o MongoDB\Driver\Server no qual o comando foi executado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Este método foi removido.

### Veja Também

- MongoDB\Driver\Monitoring\CommandStartedEvent::getServer() - Retorna o servidor no qual o comando foi executado
- Monitoramento de Desempenho de Aplicação (APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId

(mongodb >=1.14.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId — Retorna o ID de conexão do servidor para o comando

### Descrição

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId(): ?int

Retorna o ID de conexão do servidor para o comando. O ID de conexão do servidor é distinto do servidor (ou seja, MongoDB\Driver\Monitoring\CommandFailedEvent::getServer()) e é retornado no campo "connectionId" de uma resposta de comando `hello` do MongoDB 4.2+.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ID de conexão do servidor ou `null` se não estiver disponível.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId

(mongodb >=1.11.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId — Retorna o ID de serviço do balanceador de carga para o comando

### Descrição

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId(): ?MongoDB\BSON\ObjectId

Quando o driver está conectado a um cluster MongoDB por meio de um balanceador de carga, o ID do serviço corresponde ao campo `serviceId` na resposta do comando `hello`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ID do serviço do balanceador de carga ou `null` se o driver não estiver conectado a um balanceador de carga.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

## Índice

- MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName — Retorna o nome do comando
- MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName — Retorna o banco de dados no qual o comando foi executado
- MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros — Retorna a duração do comando em microssegundos
- MongoDB\Driver\Monitoring\CommandFailedEvent::getError — Retorna a exceção associada ao comando com falha
- MongoDB\Driver\Monitoring\CommandFailedEvent::getHost — Retorna o nome do servidor para o comando
- MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId — Retorna o ID da operação do comando
- MongoDB\Driver\Monitoring\CommandFailedEvent::getPort — Retorna a porta do servidor para o comando
- MongoDB\Driver\Monitoring\CommandFailedEvent::getReply — Retorna o documento de resposta do comando
- MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId — Retorna o ID da solicitação do comando
- MongoDB\Driver\Monitoring\CommandFailedEvent::getServer — Retorna o servidor no qual o comando foi executado
- MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId — Retorna o ID de conexão do servidor para o comando
- MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId — Retorna o ID de serviço do balanceador de carga para o comando

# A classe MongoDB\Driver\Monitoring\CommandStartedEvent

(mongodb >=1.3.0)

## Introdução

A classe MongoDB\Driver\Monitoring\CommandStartedEvent encapsula informação sobre um comando iniciado.

## Resumo da classe

final class MongoDB\Driver\Monitoring\CommandStartedEvent {
/* Propriedades */
public readonly string $host;
public readonly int $port;
public readonly string $commandName;
public readonly string $databaseName;
public readonly object $command;
public readonly string $operationId;
public readonly string $requestId;
public readonly ?MongoDB\BSON\ObjectId $serviceId;
public readonly ?int $serverConnectionId;
/* Métodos */
final public function getCommand(): object
final public function getCommandName(): string
final public function getDatabaseName(): string
final public function getHost(): string
final public function getOperationId(): string
final public function getPort(): int
final public function getRequestId(): string
final public function getServer(): MongoDB\Driver\Server
final public function getServerConnectionId(): ?int
final public function getServiceId(): ?MongoDB\BSON\ObjectId
}

## Propriedades

host
  O nome do host do servidor que executou o comando.
port
  A porta do servidor que executou o comando.
commandName
  O nome do comando.
databaseName
  O nome do banco de dados.
command
  O documento de comando.
operationId
  O ID da operação. Ele pode ser usado para vincular eventos, como gravações em lote, que podem disparar vários comandos.
requestId
  O ID da solicitação. Ele pode ser usado para associar este MongoDB\Driver\Monitoring\CommandStartedEvent a um evento correspondente MongoDB\Driver\Monitoring\CommandSucceededEvent ou MongoDB\Driver\Monitoring\CommandFailedEvent.
serviceId
  O ID do serviço, ou `null` se o servidor não o suportar (ou seja, não estiver usando o modo de balanceamento de carga).
serverConnectionId
  O ID de conexão do servidor, ou `null` se não estiver disponível.

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.3.0 | Adicionadas propriedades públicas readonly.

# MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand — Retorna o documento de comando

### Descrição

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand(): object

O documento de resposta será convertido de BSON para PHP usando as regras padrão de desserialização (por exemplo, documentos BSON serão convertidos para stdClass).

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o documento de comando como um objeto stdClass.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- Monitoramento de Desempenho de Aplicação (APM)
- Dados Persistentes

# MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName — Retorna o nome do comando

### Descrição

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName(): string

Retorna o nome do comando (ex.: `"find"`, `"aggregate"`).

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o nome do comando.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- Monitoramento de Desempenho de Aplicação (APM)

# MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName — Retorna o banco de dados no qual o comando foi executado

### Descrição

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o banco de dados no qual o comando foi executado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- Monitoramento de Desempenho de Aplicação (APM)

# MongoDB\Driver\Monitoring\CommandStartedEvent::getHost

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getHost — Retorna o nome do servidor para o comando

### Descrição

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getHost(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o nome do servidor no qual o comando foi executado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId — Retorna o ID da operação do comando

### Descrição

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId(): string

O ID da operação é gerado pela extensão e pode ser usado para vincular eventos, como operações de gravação em massa, que podem ter sido divididas em vários comandos no nível do protocolo.

> Nota: Como vários comandos podem compartilhar o mesmo ID de operação, não é confiável usar esse valor para associar objetos de evento entre si. O ID da solicitação retornado por MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId() deve ser usado nesse caso.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ID da operação do comando.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId() - Retorna o ID da operação do comando
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId() - Retorna o ID da operação do comando
- MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId() - Retorna o ID da solicitação do comando
- Monitoramento de Desempenho de Aplicação (APM)

# MongoDB\Driver\Monitoring\CommandStartedEvent::getPort

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getPort — Retorna a porta do servidor para o comando

### Descrição

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getPort(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a porta do servidor em que o comando foi executado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId — Retorna o ID da solicitação do comando

### Descrição

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId(): string

O ID da solicitação é gerado pela extensão e pode ser usado para associar este MongoDB\Driver\Monitoring\CommandStartedEvent a um MongoDB\Driver\Monitoring\CommandFailedEvent ou MongoDB\Driver\Monitoring\CommandSucceededEvent posterior.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ID da solicitação do comando.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId() - Retorna o ID da solicitação do comando
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId() - Retorna o ID da solicitação do comando
- Monitoramento de Desempenho de Aplicação (APM)

# MongoDB\Driver\Monitoring\CommandStartedEvent::getServer

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getServer — Retorna o servidor no qual o comando foi executado

Aviso

Este método foi DESCONTINUADO a partir da versão de extensão 1.20.0 e foi removido na versão 2.0. As aplicações devem usar MongoDB\Driver\Monitoring\CommandStartedEvent::getHost() e MongoDB\Driver\Monitoring\CommandStartedEvent::getPort() em seu lugar.

### Descrição

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getServer(): MongoDB\Driver\Server

Retorna o MongoDB\Driver\Server no qual o comando foi executado.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o MongoDB\Driver\Server no qual o comando foi executado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Este método foi removido.

### Veja Também

- MongoDB\Driver\Monitoring\CommandFailedEvent::getServer() - Retorna o servidor no qual o comando foi executado
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer() - Retorna o servidor no qual o comando foi executado
- Monitoramento de Desempenho de Aplicação (APM)

# MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId

(mongodb >=1.14.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId — Retorna o ID de conexão do servidor para o comando

### Descrição

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId(): ?int

Retorna o ID de conexão do servidor para o comando. O ID de conexão do servidor é distinto do servidor (ou seja, MongoDB\Driver\Monitoring\CommandStartedEvent::getServer()) e é retornado no campo "connectionId" de uma resposta de comando `hello` do MongoDB 4.2+.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ID de conexão do servidor ou `null` se não estiver disponível.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId

(mongodb >=1.11.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId — Retorna o ID de serviço do balanceador de carga para o comando

### Descrição

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId(): ?MongoDB\BSON\ObjectId

Quando o driver está conectado a um cluster MongoDB por meio de um balanceador de carga, o ID do serviço corresponde ao campo `serviceId` na resposta do comando `hello`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ID do serviço do balanceador de carga ou `null` se o driver não estiver conectado a um balanceador de carga.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

## Índice

- MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand — Retorna o documento de comando
- MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName — Retorna o nome do comando
- MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName — Retorna o banco de dados no qual o comando foi executado
- MongoDB\Driver\Monitoring\CommandStartedEvent::getHost — Retorna o nome do servidor para o comando
- MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId — Retorna o ID da operação do comando
- MongoDB\Driver\Monitoring\CommandStartedEvent::getPort — Retorna a porta do servidor para o comando
- MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId — Retorna o ID da solicitação do comando
- MongoDB\Driver\Monitoring\CommandStartedEvent::getServer — Retorna o servidor no qual o comando foi executado
- MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId — Retorna o ID de conexão do servidor para o comando
- MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId — Retorna o ID de serviço do balanceador de carga para o comando

# A classe MongoDB\Driver\Monitoring\CommandSucceededEvent

(mongodb >=1.3.0)

## Introdução

A classe MongoDB\Driver\Monitoring\CommandSucceededEvent encapsula informação sobre um comando bem-sucedido.

## Resumo da classe

final class MongoDB\Driver\Monitoring\CommandSucceededEvent {
/* Propriedades */
public readonly string $host;
public readonly int $port;
public readonly string $commandName;
public readonly string $databaseName;
public readonly int $duration;
public readonly object $reply;
public readonly string $operationId;
public readonly string $requestId;
public readonly ?MongoDB\BSON\ObjectId $serviceId;
public readonly ?int $serverConnectionId;
/* Métodos */
final public function getCommandName(): string
final public function getDatabaseName(): string
final public function getDurationMicros(): int
final public function getHost(): string
final public function getOperationId(): string
final public function getPort(): int
final public function getReply(): object
final public function getRequestId(): string
final public function getServer(): MongoDB\Driver\Server
final public function getServerConnectionId(): ?int
final public function getServiceId(): ?MongoDB\BSON\ObjectId
}

## Propriedades

host
  O nome do host do servidor que executou o comando.
port
  A porta do servidor que executou o comando.
commandName
  O nome do comando.
databaseName
  O nome do banco de dados.
duration
  A duração do comando em microssegundos. A duração é um valor calculado que inclui o tempo para enviar a mensagem e receber a resposta do servidor.
reply
  O documento de resposta retornado pelo servidor.
operationId
  O ID da operação. Ele pode ser usado para vincular eventos, como gravações em lote, que podem disparar vários comandos.
requestId
  O ID da solicitação. Isso pode ser usado para associar este MongoDB\Driver\Monitoring\CommandSucceededEvent a um MongoDB\Driver\Monitoring\CommandStartedEvent correspondente.
serviceId
  O ID do serviço, ou `null` se o servidor não o suportar (ou seja, não estiver usando o modo de balanceamento de carga).
serverConnectionId
  O ID de conexão do servidor, ou `null` se não estiver disponível.

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.3.0 | Adicionadas propriedades públicas readonly. A propriedade duration substitui o método getDurationMicros().

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName — Retorna o nome do comando

### Descrição

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName(): string

Retorna o nome do comando (ex.: `"find"`, `"aggregate"`).

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o nome do comando.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- Monitoramento de Desempenho de Aplicação (APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName

(mongodb >=1.19.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName — Retorna o banco de dados no qual o comando foi executado

### Descrição

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o banco de dados no qual o comando foi executado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- Monitoramento de Desempenho de Aplicação (APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros — Retorna a duração do comando em microssegundos

### Descrição

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros(): int

A duração do comando é um valor calculado que inclui o tempo para enviar a mensagem e receber a resposta do servidor.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a duração do comando em microssegundos.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- Monitoramento de Desempenho de Aplicação (APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost — Retorna o nome do servidor para o comando

### Descrição

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o nome do servidor no qual o comando foi executado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId — Retorna o ID da operação do comando

### Descrição

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId(): string

O ID da operação é gerado pela extensão e pode ser usado para vincular eventos, como operações de gravação em massa, que podem ter sido divididas em vários comandos no nível do protocolo.

> Nota: Como vários comandos podem compartilhar o mesmo ID de operação, não é confiável usar esse valor para associar objetos de evento entre si. O ID da solicitação retornado por MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId() deve ser usado nesse caso.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ID da operação do comando.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId() - Retorna o ID da operação do comando
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId() - Retorna o ID da solicitação do comando
- Monitoramento de Desempenho de Aplicação (APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort — Retorna a porta do servidor para o comando

### Descrição

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a porta do servidor em que o comando foi executado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply — Retorna o documento de resposta do comando

### Descrição

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply(): object

O documento de resposta será convertido de BSON para PHP usando as regras padrão de desserialização (por exemplo, documentos BSON serão convertidos para stdClass).

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o documento de resposta do comando como um objeto stdClass.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- Monitoramento de Desempenho de Aplicação (APM)
- Dados Persistentes

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId — Retorna o ID da solicitação do comando

### Descrição

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId(): string

O ID da solicitação é gerado pela extensão e pode ser usado para associar este MongoDB\Driver\Monitoring\CommandSucceededEvent a um MongoDB\Driver\Monitoring\CommandStartedEvent anterior.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ID da solicitação do comando.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId() - Retorna o ID da solicitação do comando
- Monitoramento de Desempenho de Aplicação (APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer — Retorna o servidor no qual o comando foi executado

Aviso

Este método foi DESCONTINUADO a partir da versão de extensão 1.20.0 e foi removido na versão 2.0. As aplicações devem usar MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost() e MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort() em seu lugar.

### Descrição

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer(): MongoDB\Driver\Server

Retorna o MongoDB\Driver\Server no qual o comando foi executado.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o MongoDB\Driver\Server no qual o comando foi executado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Este método foi removido.

### Veja Também

- MongoDB\Driver\Monitoring\CommandStartedEvent::getServer() - Retorna o servidor no qual o comando foi executado
- MongoDB\Driver\Cursor::getServer() - Retorna o servidor associado a este cursor
- MongoDB\Driver\WriteResult::getServer() - Retorna o servidor associado a este resultado de gravação
- Monitoramento de Desempenho de Aplicação (APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId

(mongodb >=1.14.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId — Retorna o ID de conexão do servidor para o comando

### Descrição

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId(): ?int

Retorna o ID de conexão do servidor para o comando. O ID de conexão do servidor é distinto do servidor (ou seja, MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer()) e é retornado no campo "connectionId" de uma resposta de comando `hello` do MongoDB 4.2+.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ID de conexão do servidor ou `null` se não estiver disponível.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId

(mongodb >=1.11.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId — Retorna o ID de serviço do balanceador de carga para o comando

### Descrição

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId(): ?MongoDB\BSON\ObjectId

Quando o driver está conectado a um cluster MongoDB por meio de um balanceador de carga, o ID do serviço corresponde ao campo `serviceId` na resposta do comando `hello`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ID do serviço do balanceador de carga ou `null` se o driver não estiver conectado a um balanceador de carga.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

## Índice

- MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName — Retorna o nome do comando
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName — Retorna o banco de dados no qual o comando foi executado
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros — Retorna a duração do comando em microssegundos
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost — Retorna o nome do servidor para o comando
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId — Retorna o ID da operação do comando
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort — Retorna a porta do servidor para o comando
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply — Retorna o documento de resposta do comando
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId — Retorna o ID da solicitação do comando
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer — Retorna o servidor no qual o comando foi executado
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId — Retorna o ID de conexão do servidor para o comando
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId — Retorna o ID de serviço do balanceador de carga para o comando

# A classe MongoDB\Driver\Monitoring\ServerChangedEvent

(mongodb >=1.13.0)

## Introdução

A classe MongoDB\Driver\Monitoring\ServerChangedEvent encapsula informações sobre uma descrição de servidor alterada. Por exemplo, a mudança do tipo de servidor de secundário para primário faria com que a descrição do servidor mudasse.

## Resumo da classe

final class MongoDB\Driver\Monitoring\ServerChangedEvent {
/* Propriedades */
public readonly string $host;
public readonly int $port;
public readonly MongoDB\BSON\ObjectId $topologyId;
public readonly MongoDB\Driver\ServerDescription $newDescription;
public readonly MongoDB\Driver\ServerDescription $previousDescription;
/* Métodos */
final public function getHost(): string
final public function getNewDescription(): MongoDB\Driver\ServerDescription
final public function getPort(): int
final public function getPreviousDescription(): MongoDB\Driver\ServerDescription
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Propriedades

host
  O nome do host do servidor.
port
  A porta do servidor.
topologyId
  O ID da topologia.
newDescription
  A nova descrição do servidor.
previousDescription
  A descrição anterior do servidor.

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.3.0 | Adicionadas propriedades públicas readonly.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getHost — Retorna o nome do host do servidor

### Descrição

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getHost(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o nome do host do servidor.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription — Retorna a nova descrição do servidor

### Descrição

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription(): MongoDB\Driver\ServerDescription

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o novo MongoDB\Driver\ServerDescription para o servidor.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getPort — Retorna a porta na qual este servidor está escutando

### Descrição

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getPort(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a porta na qual este servidor está escutando.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription — Retorna a descrição anterior do servidor

### Descrição

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription(): MongoDB\Driver\ServerDescription

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o MongoDB\Driver\ServerDescription anterior para o servidor.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId — Retorna o ID da topologia associada a este servidor

### Descrição

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ID da topologia.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

## Índice

- MongoDB\Driver\Monitoring\ServerChangedEvent::getHost — Retorna o nome do host do servidor
- MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription — Retorna a nova descrição do servidor
- MongoDB\Driver\Monitoring\ServerChangedEvent::getPort — Retorna a porta na qual este servidor está escutando
- MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription — Retorna a descrição anterior do servidor
- MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId — Retorna o ID da topologia associada a este servidor

# A classe MongoDB\Driver\Monitoring\ServerClosedEvent

(mongodb >=1.13.0)

## Introdução

A classe MongoDB\Driver\Monitoring\ServerClosedEvent encapsula informações sobre um servidor fechado. Isto corresponde a um servidor existente sendo removido da topologia.

## Resumo da classe

final class MongoDB\Driver\Monitoring\ServerClosedEvent {
/* Propriedades */
public readonly string $host;
public readonly int $port;
public readonly MongoDB\BSON\ObjectId $topologyId;
/* Métodos */
final public function getHost(): string
final public function getPort(): int
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Propriedades

host
  O nome de host do servidor.
port
  A porta do servidor.
topologyId
  O ID da topologia.

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.3.0 | Adicionadas propriedades públicas readonly.

# MongoDB\Driver\Monitoring\ServerClosedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerClosedEvent::getHost — Retorna o nome do host do servidor

### Descrição

final public function MongoDB\Driver\Monitoring\ServerClosedEvent::getHost(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o nome do host do servidor.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Monitoring\ServerClosedEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerClosedEvent::getPort — Retorna a porta na qual este servidor está escutando

### Descrição

final public function MongoDB\Driver\Monitoring\ServerClosedEvent::getPort(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a porta na qual este servidor está escutando.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId — Retorna o ID da topologia associada a este servidor

### Descrição

final public function MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ID da topologia.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

## Índice

- MongoDB\Driver\Monitoring\ServerClosedEvent::getHost — Retorna o nome do host do servidor
- MongoDB\Driver\Monitoring\ServerClosedEvent::getPort — Retorna a porta na qual este servidor está escutando
- MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId — Retorna o ID da topologia associada a este servidor

# A classe MongoDB\Driver\Monitoring\ServerOpeningEvent

(mongodb >=1.13.0)

## Introdução

A classe MongoDB\Driver\Monitoring\ServerOpeningEvent encapsula informações sobre um servidor aberto. Isso corresponde a um novo servidor sendo adicionado à topologia.

## Resumo da classe

final class MongoDB\Driver\Monitoring\ServerOpeningEvent {
/* Propriedades */
public readonly string $host;
public readonly int $port;
public readonly MongoDB\BSON\ObjectId $topologyId;
/* Métodos */
final public function getHost(): string
final public function getPort(): int
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Propriedades

host
  O nome de host do servidor.
port
  A porta do servidor.
topologyId
  O ID da topologia.

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.3.0 | Adicionadas propriedades públicas readonly.

# MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost — Retorna o nome do host do servidor

### Descrição

final public function MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o nome do host do servidor.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort — Retorna a porta na qual este servidor está escutando

### Descrição

final public function MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a porta na qual este servidor está escutando.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId — Retorna o ID da topologia associada a este servidor

### Descrição

final public function MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ID da topologia.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

## Índice

- MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost — Retorna o nome do host do servidor
- MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort — Retorna a porta na qual este servidor está escutando
- MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId — Retorna o ID da topologia associada a este servidor

# A classe MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent

(mongodb >=1.13.0)

## Introdução

A classe MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent encapsula informação sobre uma pulsação falhada do servidor (ou seja, o comando » hello emitido através do » monitoramento do servidor).

## Resumo da classe

final class MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent {
/* Propriedades */
public readonly string $host;
public readonly int $port;
public readonly bool $awaited;
public readonly int $duration;
public readonly Exception $error;
/* Métodos */
final public function getDurationMicros(): int
final public function getError(): Exception
final public function getHost(): string
final public function getPort(): int
final public function isAwaited(): bool
}

## Propriedades

host
  O nome de host do servidor.
port
  A porta do servidor.
awaited
  Se o heartbeat usou um protocolo de streaming. A extensão não usa o protocolo de streaming para monitoramento, portanto, este método sempre retornará `false`.
duration
  A duração do pulso em microssegundos. A duração é um valor calculado que inclui o tempo para enviar a mensagem e receber a resposta do servidor.
error
  A exceção que foi lançada quando o pulso falhou.

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.3.0 | Adicionadas propriedades públicas readonly. A propriedade duration substitui o método getDurationMicros().

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros — Retorna a duração da pulsação cardíaco em microssegundos

### Descrição

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros(): int

A duração da pulsação é um valor calculado que inclui o tempo para enviar a mensagem e receber a resposta do servidor.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a duração da pulsação cardíaco em microssegundos.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError — Retorna a exceção associada à pulsação com falha

### Descrição

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError(): Exception

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a Exception associada à pulsação com falha.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost — Retorna o nome do host do servidor

### Descrição

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o nome do host do servidor.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort — Retorna a porta na qual este servidor está escutando

### Descrição

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a porta na qual este servidor está escutando.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited — Retorna se a pulsação usou um protocolo de fluxo

### Descrição

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited(): bool

Retorna se a pulsação usou um protocolo de fluxo. A extensão não usa o protocolo de fluxo para monitoramento, portanto esse método sempre retornará `false`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `false`.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

## Índice

- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros — Retorna a duração da pulsação cardíaco em microssegundos
- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError — Retorna a exceção associada à pulsação com falha
- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost — Retorna o nome do host do servidor
- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort — Retorna a porta na qual este servidor está escutando
- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited — Retorna se a pulsação usou um protocolo de fluxo

# A classe MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent

(mongodb >=1.13.0)

## Introdução

A classe MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent encapsula informação sobre uma pulsação iniciada do servidor (ou seja, o comando » hello emitido através do » monitoramento do servidor).

## Resumo da classe

final class MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent {
/* Propriedades */
public readonly string $host;
public readonly int $port;
public readonly bool $awaited;
/* Métodos */
final public function getHost(): string
final public function getPort(): int
final public function isAwaited(): bool
}

## Propriedades

host
  O nome de host do servidor.
port
  A porta do servidor.
awaited
  Se o heartbeat usou um protocolo de streaming. A extensão não usa o protocolo de streaming para monitoramento, portanto, este método sempre retornará `false`.

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.3.0 | Adicionadas propriedades públicas readonly.

# MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost — Retorna o nome do host do servidor

### Descrição

final public function MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o nome do host do servidor.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort — Retorna a porta na qual este servidor está escutando

### Descrição

final public function MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a porta na qual este servidor está escutando.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited — Retorna se a pulsação usou um protocolo de fluxo

### Descrição

final public function MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited(): bool

Retorna se a pulsação usou um protocolo de fluxo. A extensão não usa o protocolo de fluxo para monitoramento, portanto esse método sempre retornará `false`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `false`.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

## Índice

- MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost — Retorna o nome do host do servidor
- MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort — Retorna a porta na qual este servidor está escutando
- MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited — Retorna se a pulsação usou um protocolo de fluxo

# A classe MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent

(mongodb >=1.13.0)

## Introdução

A classe MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent encapsula informação sobre uma pulsação bem sucedida do servidor (ou seja, o comando » hello emitido através do » monitoramento do servidor).

## Resumo da classe

final class MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent {
/* Propriedades */
public readonly string $host;
public readonly int $port;
public readonly bool $awaited;
public readonly int $duration;
public readonly object $reply;
/* Métodos */
final public function getDurationMicros(): int
final public function getHost(): string
final public function getPort(): int
final public function getReply(): object
final public function isAwaited(): bool
}

## Propriedades

host
  O nome do host do servidor.
port
  A porta do servidor.
awaited
  Se o heartbeat usou um protocolo de streaming. A extensão não usa o protocolo de streaming para monitoramento, portanto, este método sempre retornará `false`.
duration
  A duração do heartbeat em microssegundos. A duração é um valor calculado que inclui o tempo para enviar a mensagem e receber a resposta do servidor.
reply
  O documento de resposta retornado pelo servidor.

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.3.0 | Adicionadas propriedades públicas readonly. A propriedade duration substitui o método getDurationMicros().

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros — Retorna a duração da pulsação cardíaco em microssegundos

### Descrição

final public function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros(): int

A duração da pulsação é um valor calculado que inclui o tempo para enviar a mensagem e receber a resposta do servidor.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a duração da pulsação cardíaco em microssegundos.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost — Retorna o nome do host do servidor

### Descrição

final public function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost(): string

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o nome do host do servidor.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort — Retorna a porta na qual este servidor está escutando

### Descrição

final public function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort(): int

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a porta na qual este servidor está escutando.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply — Retorna o documento de resposta da pulsação

### Descrição

final public function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply(): object

O documento de resposta será convertido de BSON para PHP usando as regras padrão de desserialização (por exemplo, documentos BSON serão convertidos para stdClass).

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o documento de resposta de pulsação como um objeto stdClass.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- Monitoramento de Desempenho de Aplicação (APM)
- Dados Persistentes

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited — Retorna se a pulsação usou um protocolo de fluxo

### Descrição

final public function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited(): bool

Retorna se a pulsação usou um protocolo de fluxo. A extensão não usa o protocolo de fluxo para monitoramento, portanto esse método sempre retornará `false`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `false`.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

## Índice

- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros — Retorna a duração da pulsação cardíaco em microssegundos
- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost — Retorna o nome do host do servidor
- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort — Retorna a porta na qual este servidor está escutando
- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply — Retorna o documento de resposta da pulsação
- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited — Retorna se a pulsação usou um protocolo de fluxo

# A classe MongoDB\Driver\Monitoring\TopologyChangedEvent

(mongodb >=1.13.0)

## Introdução

A classe MongoDB\Driver\Monitoring\TopologyChangedEvent encapsula informações sobre uma descrição de topologia alterada. Por exemplo, uma topologia que descobrisse um novo conjunto de réplicas primário causaria uma alteração na descrição da topologia.

## Resumo da classe

final class MongoDB\Driver\Monitoring\TopologyChangedEvent {
/* Propriedades */
public readonly MongoDB\BSON\ObjectId $topologyId;
public readonly MongoDB\Driver\TopologyDescription $newDescription;
public readonly MongoDB\Driver\TopologyDescription $previousDescription;
/* Métodos */
final public function getNewDescription(): MongoDB\Driver\TopologyDescription
final public function getPreviousDescription(): MongoDB\Driver\TopologyDescription
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Propriedades

topologyId
  O ID da topologia.
newDescription
  A nova descrição da topologia.
previousDescription
  A antiga descrição da topologia.

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.3.0 | Adicionadas propriedades públicas readonly.

# MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription — Retorna a nova descrição da topologia

### Descrição

final public function MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription(): MongoDB\Driver\TopologyDescription

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o novo MongoDB\Driver\TopologyDescription para a topologia.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription — Retorna a descrição anterior da topologia

### Descrição

final public function MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription(): MongoDB\Driver\TopologyDescription

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o MongoDB\Driver\TopologyDescription anterior para a topologia.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

# MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId — Retorna o ID da topologia

### Descrição

final public function MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ID da topologia.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

## Índice

- MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription — Retorna a nova descrição da topologia
- MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription — Retorna a descrição anterior da topologia
- MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId — Retorna o ID da topologia

# A classe MongoDB\Driver\Monitoring\TopologyClosedEvent

(mongodb >=1.13.0)

## Introdução

A classe MongoDB\Driver\Monitoring\TopologyClosedEvent encapsula informações sobre uma topologia fechada.

> Nota: Devido ao comportamento de manipulação de conexão e persistência do driver, este evento só pode ser observado quando um MongoDB\Driver\Manager é criado com a opção `"disableClientPersistence"` do driver e liberada antes do encerramento da solicitação (RSHUTDOWN).

## Resumo da classe

final class MongoDB\Driver\Monitoring\TopologyClosedEvent {
/* Propriedades */
public readonly MongoDB\BSON\ObjectId $topologyId;
/* Métodos */
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Propriedades

topologyId
  O ID da topologia.

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.3.0 | Adicionadas propriedades públicas readonly.

# MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId — Retorna o ID da topologia

### Descrição

final public function MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ID da topologia.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

## Índice

- MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId — Retorna o ID da topologia

# A classe MongoDB\Driver\Monitoring\TopologyOpeningEvent

(mongodb >=1.13.0)

## Introdução

A classe MongoDB\Driver\Monitoring\TopologyOpeningEvent encapsula informações sobre uma topologia aberta.

> Nota: Devido ao comportamento de manipulação de conexão e persistência do driver, este evento pode não ser observado se um MongoDB\Driver\Manager usar um cliente » libmongoc persistido anteriormente.

## Resumo da classe

final class MongoDB\Driver\Monitoring\TopologyOpeningEvent {
/* Propriedades */
public readonly MongoDB\BSON\ObjectId $topologyId;
/* Métodos */
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Propriedades

topologyId
  O ID da topologia.

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.3.0 | Adicionadas propriedades públicas readonly.

# MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId — Retorna o ID da topologia

### Descrição

final public function MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ID da topologia.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

## Índice

- MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId — Retorna o ID da topologia

# A interface MongoDB\Driver\Monitoring\CommandSubscriber

(mongodb >=1.3.0)

## Introdução

Classes podem implementar este interface para registrar um assinante de evento que será notificado em cada evento de comando iniciado, bem-sucedido ou falhado. Monitoramento de Desempenho de Aplicação (APM) para informações adicionais.

## Resumo da Interface

class MongoDB\Driver\Monitoring\CommandSubscriber implements MongoDB\Driver\Monitoring\Subscriber {
/* Métodos */
abstract public function commandFailed(MongoDB\Driver\Monitoring\CommandFailedEvent `$event`): void
abstract public function commandStarted(MongoDB\Driver\Monitoring\CommandStartedEvent `$event`): void
abstract public function commandSucceeded(MongoDB\Driver\Monitoring\CommandSucceededEvent `$event`): void
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Os tipos de retorno anteriormente declarados como temporários agora devem ser cumpridos.
mongodb 1.15.0 no PECL | Os tipos de retorno para métodos são declarados como provisórios no PHP 8.0 e mais recentes, disparando avisos de descontinuação no código que implementa essa interface sem declarar os tipos de retorno apropriados. O atributo `#[ReturnTypeWillChange]` pode ser adicionado para silenciar o aviso de descontinuação.

# MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed — Método de notificação para um comando falhado

### Descrição

abstract public function MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed(MongoDB\Driver\Monitoring\CommandFailedEvent `$event`): void

Se o assinante estiver registrado, esse método será chamado quando um comando falhar.

### Parâmetros

`event` (MongoDB\Driver\Monitoring\CommandFailedEvent)
  Um objeto de evento que encapsula informações sobre o comando com falha.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Monitoring\CommandFailedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registra um assinante de evento de monitoramento globalmente
- MongoDB\Driver\Manager::addSubscriber() - Inscreve um assinante de evento de monitoramento com este gerenciador
- Monitoramento de Desempenho de Aplicação (APM)

# MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted — Método de notificação para um comando iniciado

### Descrição

abstract public function MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted(MongoDB\Driver\Monitoring\CommandStartedEvent `$event`): void

Se o assinante estiver registrado, este método será chamado quando um comando for enviado ao servidor.

### Parâmetros

`event` (MongoDB\Driver\Monitoring\CommandStartedEvent)
  Um objeto de evento que encapsula informações sobre o comando iniciado.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Monitoring\CommandStartedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registra um assinante de evento de monitoramento globalmente
- MongoDB\Driver\Manager::addSubscriber() - Inscreve um assinante de evento de monitoramento com este gerenciador
- Monitoramento de Desempenho de Aplicação (APM)

# MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded — Método de notificação para um comando bem-sucedido

### Descrição

abstract public function MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded(MongoDB\Driver\Monitoring\CommandSucceededEvent `$event`): void

Se o assinante estiver registrado, esse método será chamado quando um comando for bem-sucedido.

### Parâmetros

`event` (MongoDB\Driver\Monitoring\CommandSucceededEvent)
  Um objeto de evento que encapsula informações sobre o comando bem-sucedido.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Monitoring\CommandSucceededEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registra um assinante de evento de monitoramento globalmente
- MongoDB\Driver\Manager::addSubscriber() - Inscreve um assinante de evento de monitoramento com este gerenciador
- Monitoramento de Desempenho de Aplicação (APM)

## Índice

- MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed — Método de notificação para um comando falhado
- MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted — Método de notificação para um comando iniciado
- MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded — Método de notificação para um comando bem-sucedido

# A interface MongoDB\Driver\Monitoring\LogSubscriber

(mongodb >=1.17.0)

## Introdução

As classes que implementam esta interface podem ser registradas como assinantes e receber mensagens de registro da extensão. Isso é semelhante ao registro de depuração baseado em fluxo (ou seja, mongodb.debug), exceto que as mensagens de registro em nível de rastreio não são recebidas.

Assim como acontece com o registro baseado em fluxo, só é possível inscrever um criador de regsitros globalmente usando MongoDB\Driver\Monitoring\addSubscriber(). A extensão não é capaz de distinguir mensagens de regsitros para objetos MongoDB\Driver\Manager individuais.

## Resumo da Interface

class MongoDB\Driver\Monitoring\LogSubscriber implements MongoDB\Driver\Monitoring\Subscriber {
/* Constantes */
const int LEVEL_ERROR = 0;
const int LEVEL_CRITICAL = 1;
const int LEVEL_WARNING = 2;
const int LEVEL_MESSAGE = 3;
const int LEVEL_INFO = 4;
const int LEVEL_DEBUG = 5;
/* Métodos */
abstract public function log(int `$level`, string `$domain`, string `$message`): void
}

## Constantes predefinidas

`MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_ERROR`
  Nível de registro de erros. Uma condição de erro que a extensão não consegue relatar por meio de sua API. Este é o nível de registro mais severo na extensão.
`MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_CRITICAL`
  Nível de registro crítico. Uma condição de erro com gravidade um pouco menor. Esta constante existe para consistência com libmongoc; no entanto, é improvável que a extensão o utilize na prática.
`MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_WARNING`
  Nível de registro de alerta. Indica uma situação em que pode ocorrer comportamento indesejável da aplicação.
`MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_MESSAGE`
  Nível de registro de mensagens ou avisos. Indica um evento incomum, mas não problemático.
`MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_INFO`
  Nível de registro de informações. Informações de alto nível sobre o comportamento normal do driver.
`MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_DEBUG`
  Nível de registro de depuração. Informações detalhadas que podem ser úteis ao depurar uma aplicação.

# MongoDB\Driver\Monitoring\LogSubscriber::log

(mongodb >=1.17.0)

MongoDB\Driver\Monitoring\LogSubscriber::log — Método de notificação para uma mensagem de registro

### Descrição

abstract public function MongoDB\Driver\Monitoring\LogSubscriber::log(int `$level`, string `$domain`, string `$message`): void

Se o assinante estiver registrado, esse método será chamado para cada mensagem registrada.

### Parâmetros

`level`
  O nível de severidade. Este será uma das constantes de interface.
`domain`
  O nome do componente do driver que emitiu a mensagem de registro.
`message`
  A mensagem de registro.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Monitoring\addSubscriber() - Registra um assinante de evento de monitoramento globalmente

## Índice

- MongoDB\Driver\Monitoring\LogSubscriber::log — Método de notificação para uma mensagem de registro

# A interface MongoDB\Driver\Monitoring\SDAMSubscriber

(mongodb >=1.13.0)

## Introdução

As classes podem implementar esta interface para registrar um assinante de evento que é notificado sobre vários eventos SDAM. Consulte as especificações de » Descoberta e Monitoramento de Servidores e » Monitoramento de SDAM para obter informações adicionais.

## Resumo da Interface

class MongoDB\Driver\Monitoring\SDAMSubscriber implements MongoDB\Driver\Monitoring\Subscriber {
/* Métodos */
abstract public function serverChanged(MongoDB\Driver\Monitoring\ServerChangedEvent `$event`): void
abstract public function serverClosed(MongoDB\Driver\Monitoring\ServerClosedEvent `$event`): void
abstract public function serverHeartbeatFailed(MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent `$event`): void
abstract public function serverHeartbeatStarted(MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent `$event`): void
abstract public function serverHeartbeatSucceeded(MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent `$event`): void
abstract public function serverOpening(MongoDB\Driver\Monitoring\ServerOpeningEvent `$event`): void
abstract public function topologyChanged(MongoDB\Driver\Monitoring\TopologyChangedEvent `$event`): void
abstract public function topologyClosed(MongoDB\Driver\Monitoring\TopologyClosedEvent `$event`): void
abstract public function topologyOpening(MongoDB\Driver\Monitoring\TopologyOpeningEvent `$event`): void
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Os tipos de retorno anteriormente declarados como temporários agora devem ser cumpridos.
mongodb 1.15.0 no PECL | Os tipos de retorno para métodos são declarados como provisórios no PHP 8.0 e mais recentes, disparando avisos de descontinuação no código que implementa essa interface sem declarar os tipos de retorno apropriados. O atributo `#[ReturnTypeWillChange]` pode ser adicionado para silenciar o aviso de descontinuação.

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged — Método de notificação para uma alteração na descrição do servidor

### Descrição

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged(MongoDB\Driver\Monitoring\ServerChangedEvent `$event`): void

Se o assinante estiver registrado, esse método será chamado quando a descrição do servidor for alterada. Por exemplo, a mudança do tipo de servidor de secundário para primário faria com que a descrição do servidor mudasse.

### Parâmetros

`event` (MongoDB\Driver\Monitoring\ServerChangedEvent)
  Um objeto de evento que encapsula informações sobre a descrição alterada do servidor.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Monitoring\ServerChangedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registra um assinante de evento de monitoramento globalmente
- MongoDB\Driver\Manager::addSubscriber() - Inscreve um assinante de evento de monitoramento com este gerenciador

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed — Método de notificação para fechamendo de um servidor

### Descrição

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed(MongoDB\Driver\Monitoring\ServerClosedEvent `$event`): void

Se o assinante estiver registrado, esse método será chamado quando um servidor existente for removido da topologia.

### Parâmetros

`event` (MongoDB\Driver\Monitoring\ServerClosedEvent)
  Um objeto de evento que encapsula informações sobre o servidor fechado.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Monitoring\ServerClosedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registra um assinante de evento de monitoramento globalmente
- MongoDB\Driver\Manager::addSubscriber() - Inscreve um assinante de evento de monitoramento com este gerenciador

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed — Método de notificação para uma pulsação do servidor com falha

### Descrição

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed(MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent `$event`): void

Se o assinante estiver registrado, este método será chamado quando uma pulsação de servidor (ou seja, o comando » hello emitido através do » monitoramento do servidor) falha.

### Parâmetros

`event` (MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent)
  Um objeto de evento que encapsula informações sobre a pulsação do servidor com falha.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registra um assinante de evento de monitoramento globalmente
- MongoDB\Driver\Manager::addSubscriber() - Inscreve um assinante de evento de monitoramento com este gerenciador

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted — Método de notificação para uma pulsação de servidor iniciada

### Descrição

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted(MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent `$event`): void

Se o assinante estiver registrado, este método será chamado quando uma pulsação de servidor (ou seja, o comando » hello emitido através do » monitoramento do servidor) é enviada ao servidor.

### Parâmetros

`event` (MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent)
  Um objeto de evento que encapsula informações sobre a pulsação do servidor iniciada.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registra um assinante de evento de monitoramento globalmente
- MongoDB\Driver\Manager::addSubscriber() - Inscreve um assinante de evento de monitoramento com este gerenciador

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded — Método de notificação para uma pulsação do servidor bem-sucedida

### Descrição

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded(MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent `$event`): void

Se o assinante estiver registrado, este método será chamado quando uma pulsação de servidor (ou seja, o comando » hello emitido através do » monitoramento do servidor) for bem sucedida.

### Parâmetros

`event` (MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent)
  Um objeto de evento que encapsula informações sobre a pulsação do servidor bem-sucedida.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registra um assinante de evento de monitoramento globalmente
- MongoDB\Driver\Manager::addSubscriber() - Inscreve um assinante de evento de monitoramento com este gerenciador

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening — Método de notificação para abertura de um servidor

### Descrição

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening(MongoDB\Driver\Monitoring\ServerOpeningEvent `$event`): void

Se o assinante estiver registrado, este método será chamado quando um novo servidor for adicionado à topologia.

### Parâmetros

`event` (MongoDB\Driver\Monitoring\ServerOpeningEvent)
  Um objeto de evento que encapsula informações sobre o servidor aberto.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Monitoring\ServerOpeningEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registra um assinante de evento de monitoramento globalmente
- MongoDB\Driver\Manager::addSubscriber() - Inscreve um assinante de evento de monitoramento com este gerenciador

# MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged — Método de notificação para uma alteração na descrição da topologia

### Descrição

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged(MongoDB\Driver\Monitoring\TopologyChangedEvent `$event`): void

Se o assinante estiver cadastrado, este método será chamado quando a descrição da topologia for alterada. Por exemplo, uma topologia que descobrisse um novo conjunto de réplicas primário causaria uma alteração na descrição da topologia.

### Parâmetros

`event` (MongoDB\Driver\Monitoring\TopologyChangedEvent)
  Um objeto de evento que encapsula informações sobre a descrição da topologia alterada.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Monitoring\TopologyChangedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registra um assinante de evento de monitoramento globalmente
- MongoDB\Driver\Manager::addSubscriber() - Inscreve um assinante de evento de monitoramento com este gerenciador

# MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed — Método de notificação para fechamento de topologia

### Descrição

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed(MongoDB\Driver\Monitoring\TopologyClosedEvent `$event`): void

Se o assinante estiver cadastrado, este método será chamado quando a topologia for fechada.

> Nota: Devido ao comportamento de manipulação de conexão e persistência do driver, este evento só pode ser observado quando um MongoDB\Driver\Manager é criado com a opção `"disableClientPersistence"` do driver e liberada antes do encerramento da solicitação (RSHUTDOWN).

### Parâmetros

`event` (MongoDB\Driver\Monitoring\TopologyClosedEvent)
  Um objeto de evento que encapsula informações sobre a topologia fechada.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Monitoring\TopologyClosedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registra um assinante de evento de monitoramento globalmente
- MongoDB\Driver\Manager::addSubscriber() - Inscreve um assinante de evento de monitoramento com este gerenciador

# MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening — Método de notificação para abrertura de topologia

### Descrição

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening(MongoDB\Driver\Monitoring\TopologyOpeningEvent `$event`): void

Se o assinante estiver cadastrado, este método será chamado quando a topologia for aberta.

> Nota: Devido ao comportamento de manipulação de conexão e persistência do driver, este evento pode não ser observado se um MongoDB\Driver\Manager usar um cliente » libmongoc persistido anteriormente.

### Parâmetros

`event` (MongoDB\Driver\Monitoring\TopologyOpeningEvent)
  Um objeto de evento que encapsula informações sobre a topologia aberta.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

- Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

### Veja Também

- MongoDB\Driver\Monitoring\TopologyOpeningEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registra um assinante de evento de monitoramento globalmente
- MongoDB\Driver\Manager::addSubscriber() - Inscreve um assinante de evento de monitoramento com este gerenciador

## Índice

- MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged — Método de notificação para uma alteração na descrição do servidor
- MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed — Método de notificação para fechamendo de um servidor
- MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed — Método de notificação para uma pulsação do servidor com falha
- MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted — Método de notificação para uma pulsação de servidor iniciada
- MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded — Método de notificação para uma pulsação do servidor bem-sucedida
- MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening — Método de notificação para abertura de um servidor
- MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged — Método de notificação para uma alteração na descrição da topologia
- MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed — Método de notificação para fechamento de topologia
- MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening — Método de notificação para abrertura de topologia

# A interface MongoDB\Driver\Monitoring\Subscriber

(mongodb >=1.3.0)

## Introdução

Interface base para assinantes de eventos. É usada como um tipo de parâmetro nas funções MongoDB\Driver\Monitoring\addSubscriber() e MongoDB\Driver\Monitoring\removeSubscriber() e não deve ser implementada diretamente.

## Resumo da Interface

class MongoDB\Driver\Monitoring\Subscriber {
}

Esta interface não possui métodos. Seu único propósito é ser a interface base para todos os assinantes de evento.

# Classes de exceção

## Índice

- MongoDB\Driver\Exception\AuthenticationException
- MongoDB\Driver\Exception\BulkWriteException
- MongoDB\Driver\Exception\BulkWriteCommandException
- MongoDB\Driver\Exception\CommandException
- MongoDB\Driver\Exception\ConnectionException
- MongoDB\Driver\Exception\ConnectionTimeoutException
- MongoDB\Driver\Exception\EncryptionException
- MongoDB\Driver\Exception\Exception
- MongoDB\Driver\Exception\ExecutionTimeoutException
- MongoDB\Driver\Exception\InvalidArgumentException
- MongoDB\Driver\Exception\LogicException
- MongoDB\Driver\Exception\RuntimeException
- MongoDB\Driver\Exception\ServerException
- MongoDB\Driver\Exception\SSLConnectionException
- MongoDB\Driver\Exception\UnexpectedValueException
- MongoDB\Driver\Exception\WriteException
- Árvore de Classes

# A classe MongoDB\Driver\Exception\AuthenticationException

(mongodb >= 1.0.0)

## Introdução

Lançada quando o driver não consegue se autenticar no servidor.

## Resumo da classe

class MongoDB\Driver\Exception\AuthenticationException extends MongoDB\Driver\Exception\ConnectionException implements MongoDB\Driver\Exception\Exception {
/* Propriedades herdadas */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# A classe MongoDB\Driver\Exception\BulkWriteException

(mongodb >= 1.0.0)

## Introdução

Lançada quando uma operação de gravação em massa falha.

## Resumo da classe

class MongoDB\Driver\Exception\BulkWriteException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* Propriedades */
public readonly MongoDB\Driver\WriteResult $writeResult;
/* Propriedades herdadas */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
final public function getWriteResult(): MongoDB\Driver\WriteResult
/* Métodos herdados */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Propriedades

writeResult
  O objeto MongoDB\Driver\WriteResult associado com a operação de escrita falhada.

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.3.0 | A propriedade writeResult agora é public readonly.
PECL mongodb 2.0.0 | Esta classe agora estende MongoDB\Driver\Exception\ServerException em vez de MongoDB\Driver\Exception\WriteException.

# MongoDB\Driver\Exception\BulkWriteException::getWriteResult

(mongodb >= 1.0.0)

MongoDB\Driver\Exception\BulkWriteException::getWriteResult — Retorna o WriteResult para a operação de escrita com falha

### Descrição

final public function MongoDB\Driver\Exception\BulkWriteException::getWriteResult(): MongoDB\Driver\WriteResult

Retorna o MongoDB\Driver\WriteResult para a operação de escrita com falha. Os métodos MongoDB\Driver\WriteResult::getWriteErrors() e MongoDB\Driver\WriteResult::getWriteConcernError() podem ser usados ​​para obter mais detalhes sobre a falha.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O MongoDB\Driver\WriteResult para a operação de escrita com falha.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\Exception\BulkWriteException::getWriteResult()

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost');
    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 1]);

    try {
        $manager->executeBulkWrite('db.collection', $bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteException $e) {
        $writeResult = $e->getWriteResult();

        if ($writeConcernError = $writeResult->getWriteConcernError()) {
            var_dump($writeConcernError);
        }

        if ($writeErrors = $writeResult->getWriteErrors()) {
            var_dump($writeErrors);
        }
    }

    ?>

O exemplo acima produzirá algo semelhante a:

    array(1) {
      [0]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(70) "E11000 duplicate key error index: db.collection.$_id_ dup key: { : 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(1)
        ["info"]=>
        NULL
      }
    }

### Veja Também

- MongoDB\Driver\WriteResult
- MongoDB\Driver\Manager::executeBulkWrite() - Executa uma ou mais operações de escrita

## Índice

- MongoDB\Driver\Exception\BulkWriteException::getWriteResult — Retorna o WriteResult para a operação de escrita com falha

# A classe MongoDB\Driver\Exception\BulkWriteCommandException

(mongodb >=2.1.0)

## Introdução

Exceção gerada devido à falha na execução de um MongoDB\Driver\BulkWriteCommand. Os métodos desta classe fornecem mais detalhes do erro ocorrido, incluindo a resposta do erro e resultados parciais da gravação em massa.

## Resumo da classe

class MongoDB\Driver\Exception\BulkWriteCommandException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* Propriedades */
private ?MongoDB\BSON\Document $errorReply;
private ?MongoDB\Driver\BulkWriteCommandResult $partialResult;
private array $writeConcernErrors;
private array $writeErrors;
/* Propriedades herdadas */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
final public function getErrorReply(): ?MongoDB\BSON\Document
final public function getPartialResult(): ?MongoDB\Driver\BulkWriteCommandResult
final public function getWriteConcernErrors(): array
final public function getWriteErrors(): array
/* Métodos herdados */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Propriedades

errorReply
  Qualquer erro de nível superior que ocorreu ao tentar se comunicar com o servidor ou executar a gravação em massa. Este valor pode ser `null` se a exceção foi gerada devido a erros ocorridos em gravações individuais.
partialResult
  Um MongoDB\Driver\BulkWriteCommandResult relatando o resultado de quaisquer operações bem-sucedidas que foram executadas antes do erro ser encontrado. Este valor pode ser `null` se não for possível determinar que pelo menos uma gravação foi realizada com sucesso (e reconhecida).
writeConcernErrors
  Um array de quaisquer MongoDB\Driver\WriteConcernError que ocorreram durante a execução da gravação em massa. Esta lista pode ter vários itens se mais de um comando de servidor foi necessário para executar a gravação em massa.
writeErrors
  Um array de quaisquer MongoDB\Driver\WriteErrors que ocorreram durante a execução de operações de gravação individuais. As chaves do array corresponderão ao índice da operação de gravação de MongoDB\Driver\BulkWriteCommand. Este mapa conterá no máximo uma entrada se a gravação em massa tiver sido ordenada.

# MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply

(mongodb >=2.1.0)

MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply — Retorna qualquer erro de comando de nível superior

### Descrição

final public function MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply(): ?MongoDB\BSON\Document

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna qualquer erro de nível superior que ocorreu ao tentar se comunicar com o servidor ou executar a gravação em massa. Este valor pode ser `null` se a exceção foi gerada devido a erros ocorridos em gravações individuais.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply()

    <?php

    $manager = new MongoDB\Driver\Manager;

    // Este exemplo usa configureFailPoint para simular um erro de comando de nível superior
    $manager->executeCommand('admin', new MongoDB\Driver\Command([
        'configureFailPoint' => 'failCommand',
        'mode' => ['times' => 1],
        'data' => [
            'failCommands' => ['bulkWrite'],
            'errorCode' => 8, /* UnknownError */
        ],
    ]));

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        var_dump($e->getErrorReply()?->toPHP());
    }

    ?>

O exemplo acima produzirá algo semelhante a:

    object(stdClass)#12 (6) {
      ["ok"]=>
      float(0)
      ["errmsg"]=>
      string(43) "Failing command via 'failCommand' failpoint"
      ["code"]=>
      int(8)
      ["codeName"]=>
      string(12) "UnknownError"
      ["$clusterTime"]=>
      object(stdClass)#10 (2) {
        ["clusterTime"]=>
        object(MongoDB\BSON\Timestamp)#6 (2) {
          ["increment"]=>
          string(1) "7"
          ["timestamp"]=>
          string(10) "1744319389"
        }
        ["signature"]=>
        object(stdClass)#9 (2) {
          ["hash"]=>
          object(MongoDB\BSON\Binary)#7 (2) {
            ["data"]=>
            string(20) ""
            ["type"]=>
            int(0)
          }
          ["keyId"]=>
          object(MongoDB\BSON\Int64)#8 (1) {
            ["integer"]=>
            string(1) "0"
          }
        }
      }
      ["operationTime"]=>
      object(MongoDB\BSON\Timestamp)#11 (2) {
        ["increment"]=>
        string(1) "7"
        ["timestamp"]=>
        string(10) "1744319389"
      }
    }

### Veja Também

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Executa operações de gravação usando o comando bulkWrite

# MongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult

(mongodb >=2.1.0)

MongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult — Retorna o resultado de qualquer operação de gravação bem-sucedida

### Descrição

final public function MongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult(): ?MongoDB\Driver\BulkWriteCommandResult

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um MongoDB\Driver\BulkWriteCommandResult relatando o resultado de quaisquer operações bem-sucedidas que foram executadas antes do erro ser encontrado. O valor de retorno será `null` se não for possível determinar que pelo menos uma gravação foi realizada com sucesso (e reconhecida).

### Exemplos

Exemplo #1 Resultado parcial se pelo menos uma gravação for bem-sucedida

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 1]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        $result = $e->getPartialResult();
    }

    var_dump($result?->getInsertedCount());

    ?>

O exemplo acima produzirá:

    int(1)

Exemplo #2 Nenhum resultado parcial se nenhuma gravação for bem-sucedida

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $manager->executeBulkWriteCommand($bulk);

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['_id' => 1]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        $result = $e->getPartialResult();
    }

    var_dump($result?->getInsertedCount());

    ?>

O exemplo acima produzirá:

    NULL

### Veja Também

- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Executa operações de gravação usando o comando bulkWrite

# MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors

(mongodb >=2.1.0)

MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors — Retorna quaisquer erros de preocupação de gravação

### Descrição

final public function MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors(): array

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array de quaisquer MongoDB\Driver\WriteConcernError que ocorreram durante a execução da gravação em massa. Esta lista pode ter vários itens se mais de um comando de servidor foi necessário para executar a gravação em massa.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(50);

    try {
        $result = $manager->executeBulkWriteCommand($bulk, ['writeConcern' => $writeConcern]);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        var_dump($e->getWriteConcernErrors());
    }

    ?>

O exemplo acima produzirá algo semelhante a:

    array(1) {
      [0]=>
      object(MongoDB\Driver\WriteConcernError)#6 (3) {
        ["message"]=>
        string(29) "Not enough data-bearing nodes"
        ["code"]=>
        int(100)
        ["info"]=>
        object(stdClass)#8 (1) {
          ["writeConcern"]=>
          object(stdClass)#7 (3) {
            ["w"]=>
            int(50)
            ["wtimeout"]=>
            int(0)
            ["provenance"]=>
            string(14) "clientSupplied"
          }
        }
      }
    }

### Veja Também

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Executa operações de gravação usando o comando bulkWrite
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\WriteConcernError

# MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors

(mongodb >=2.1.0)

MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors — Retorna quaisquer erros de gravação

### Descrição

final public function MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors(): array

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array de quaisquer MongoDB\Driver\WriteErrors que ocorreram durante a execução de operações de gravação individuais. As chaves do array corresponderão ao índice da operação de gravação de MongoDB\Driver\BulkWriteCommand. Este mapa conterá no máximo uma entrada se a gravação em massa tiver sido ordenada.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand(['ordered' => false]);
    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 1]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        var_dump($e->getWriteErrors());
    }

    ?>

O exemplo acima produzirá algo semelhante a:

    array(2) {
      [2]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(2)
        ["info"]=>
        object(stdClass)#6 (0) {
        }
      }
      [3]=>
      object(MongoDB\Driver\WriteError)#7 (4) {
        ["message"]=>
        string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(3)
        ["info"]=>
        object(stdClass)#8 (0) {
        }
      }
    }

### Veja Também

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Executa operações de gravação usando o comando bulkWrite
- MongoDB\Driver\WriteError

## Índice

- MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply — Retorna qualquer erro de comando de nível superior
- MongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult — Retorna o resultado de qualquer operação de gravação bem-sucedida
- MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors — Retorna quaisquer erros de preocupação de gravação
- MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors — Retorna quaisquer erros de gravação

# A classe MongoDB\Driver\Exception\CommandException

(mongodb >= 1.5.0)

## Introdução

Lançada quando um comando falha.

## Resumo da classe

class MongoDB\Driver\Exception\CommandException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* Propriedades */
public readonly object $resultDocument;
/* Propriedades herdadas */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
final public function getResultDocument(): object
/* Métodos herdados */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Propriedades

resultDocument
  O documento de resultado associado ao comando com falha.

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.3.0 | A propriedade resultDocument agora é public readonly.

# MongoDB\Driver\Exception\CommandException::getResultDocument

(mongodb >= 1.5.0)

MongoDB\Driver\Exception\CommandException::getResultDocument — Retorna o documento de resultado do comando com falha

### Descrição

final public function MongoDB\Driver\Exception\CommandException::getResultDocument(): object

Retorna o documento de resultado do comando com falha.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O documento de resultado do comando com falha.

### Veja Também

- MongoDB\Driver\Manager::executeCommand() - Executa um comando de banco de dados

## Índice

- MongoDB\Driver\Exception\CommandException::getResultDocument — Retorna o documento de resultado do comando com falha

# A classe MongoDB\Driver\Exception\ConnectionException

(mongodb >= 1.0.0)

## Introdução

Classe base para exceções lançadas quando o driver não consegue estabelecer uma conexão com o banco de dados.

## Resumo da classe

class MongoDB\Driver\Exception\ConnectionException extends MongoDB\Driver\Exception\RuntimeException implements MongoDB\Driver\Exception\Exception {
/* Propriedades herdadas */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# A classe MongoDB\Driver\Exception\ConnectionTimeoutException

(mongodb >= 1.0.0)

## Introdução

Lançada quando o driver não consegue estabelecer uma conexão com o banco de dados dentro de um limite de tempo especificado (connectTimeoutMS) ou a seleção do servidor falha (serverSelectionTimeoutMS).

## Resumo da classe

final class MongoDB\Driver\Exception\ConnectionTimeoutException extends MongoDB\Driver\Exception\ConnectionException implements MongoDB\Driver\Exception\Exception {
/* Propriedades herdadas */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# A classe MongoDB\Driver\Exception\EncryptionException

(mongodb >= 1.7.0)

## Introdução

Classe base para exceções lançadas durante a criptografia do lado do cliente.

## Resumo da classe

class MongoDB\Driver\Exception\EncryptionException extends MongoDB\Driver\Exception\RuntimeException implements MongoDB\Driver\Exception\Exception {
/* Propriedades herdadas */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# A interface MongoDB\Driver\Exception\Exception

(mongodb >= 1.0.0)

## Introdução

Interface comum para todas as exceções de extensão. Esta interface também é usada pela biblioteca e pode ser usada para identificar quaisquer exceções originadas do driver MongoDB PHP (ou seja, extensão e biblioteca).

## Resumo da classe

class MongoDB\Driver\Exception\Exception {
}

# A classe MongoDB\Driver\Exception\ExecutionTimeoutException

(mongodb >= 1.0.0)

## Introdução

Lançada quando uma consulta ou comando não é concluído dentro de um limite de tempo especificado (por exemplo, » maxTimeMS).

## Resumo da classe

final class MongoDB\Driver\Exception\ExecutionTimeoutException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* Propriedades herdadas */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.5.0 | Esta classe agora estende a classe MongoDB\Driver\Exception\ServerException ao invés da classe MongoDB\Driver\Exception\RuntimeException.

# A classe MongoDB\Driver\Exception\InvalidArgumentException

(mongodb >= 1.0.0)

## Introdução

Lançada quando um método de driver recebe argumentos inválidos (por exemplo, tipos de opções inválidos).

## Resumo da classe

class MongoDB\Driver\Exception\InvalidArgumentException extends InvalidArgumentException implements MongoDB\Driver\Exception\Exception {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# A classe MongoDB\Driver\Exception\LogicException

(mongodb >= 1.0.0)

## Introdução

Lançada quando o driver é usado incorretamente (por exemplo, retrocedendo um cursor).

## Resumo da classe

class MongoDB\Driver\Exception\LogicException extends LogicException implements MongoDB\Driver\Exception\Exception {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# A classe MongoDB\Driver\Exception\RuntimeException

(mongodb >= 1.0.0)

## Introdução

Lançada quando o driver encontra um erro no momento da execução (por exemplo, erro interno de » libmongoc).

## Resumo da classe

class MongoDB\Driver\Exception\RuntimeException extends RuntimeException implements MongoDB\Driver\Exception\Exception {
/* Propriedades */
protected ?array $errorLabels;
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
final public function hasErrorLabel(string `$errorLabel`): bool
/* Métodos herdados */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Propriedades

errorLabels
  Contém um array de rótulos de erro que acompanham uma exceção. Por exemplo, rótulos de erro podem ser usados ​​para detectar se uma transação pode ser repetida com segurança se o rótulo `TransientTransactionError` estiver presente. A existência de um rótulo de erro específico deve ser testada com o método MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(), em vez de interpretar a propriedade `errorLabels` manualmente.

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 1.6.0 | O método MongoDB\Driver\Exception\RuntimeException::hasErrorLabel() e a propriedade MongoDB\Driver\Exception\RuntimeException::errorLabels foram adicionados.

# MongoDB\Driver\Exception\RuntimeException::hasErrorLabel

(mongodb >= 1.6.0)

MongoDB\Driver\Exception\RuntimeException::hasErrorLabel — Retorna se um rótulo de erro está associado a uma exceção

### Descrição

final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool

Retorna se `errorLabel` foi definido para esta exceção. Os rótulos de erro são definidos pelo servidor ou pela extensão para indicar situações específicas que podem ser tratadas por uma aplicação. Uma situação comum pode ser determinar se é necessário repetir com segurança uma transação que falhou devido a um erro transitório (por exemplo, erro de rede, conflito de transação). Exemplos de rótulos de erro são `TransientTransactionError` e `UnknownTransactionCommitResult`.

### Parâmetros

`errorLabel`
  O nome do `errorLabel` a ser testado.

### Valor Retornado

Se o `errorLabel` fornecido está associado a esta exceção.

### Veja Também

- MongoDB\Driver\Session::commitTransaction() - Confirma uma transação
- » Documentação do MongoDB sobre transações

## Índice

- MongoDB\Driver\Exception\RuntimeException::hasErrorLabel — Retorna se um rótulo de erro está associado a uma exceção

# A classe MongoDB\Driver\Exception\ServerException

(mongodb >= 1.5.0)

## Introdução

Classe base para exceções lançadas pelo servidor. O código desta exceção e suas subclasses corresponderão ao código de erro original do servidor.

## Resumo da classe

class MongoDB\Driver\Exception\ServerException extends MongoDB\Driver\Exception\RuntimeException implements MongoDB\Driver\Exception\Exception {
/* Propriedades herdadas */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# A classe MongoDB\Driver\Exception\SSLConnectionException

(mongodb >= 1.0.0)

Aviso

Esta classe de exceção foi DESCONTINUADA a partir da versão de extensão 1.5.0 e foi removida na versão 2.0. Esta exceção nunca foi lançada pela extensão. As aplicações devem usar MongoDB\Driver\Exception\ConnectionException em seu lugar.

## Introdução

Lançada quando o driver não consegue estabelecer uma conexão SSL com o servidor.

## Resumo da classe

final class MongoDB\Driver\Exception\SSLConnectionException extends MongoDB\Driver\Exception\ConnectionException implements MongoDB\Driver\Exception\Exception {
/* Propriedades herdadas */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# A classe MongoDB\Driver\Exception\UnexpectedValueException

(mongodb >= 1.0.0)

## Introdução

Lançada quando o driver encontra um valor inesperado (por exemplo, durante a serialização ou desserialização do BSON).

## Resumo da classe

class MongoDB\Driver\Exception\UnexpectedValueException extends UnexpectedValueException implements MongoDB\Driver\Exception\Exception {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# A classe MongoDB\Driver\Exception\WriteException

(mongodb >= 1.0.0)

Aviso

Esta classe de exceção foi DESCONTINUADA a partir da versão de extensão 1.20.0 e foi removida na versão 2.0. Esta exceção nunca foi lançada diretamente pela extensão. As aplicações devem usar MongoDB\Driver\Exception\BulkWriteException em seu lugar.

## Introdução

Classe base para exceções lançadas por uma operação de gravação com falha. A exceção encapsula um objeto MongoDB\Driver\WriteResult.

## Resumo da classe

abstract class MongoDB\Driver\Exception\WriteException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* Propriedades */
protected MongoDB\Driver\WriteResult $writeResult;
/* Propriedades herdadas */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
final public function getWriteResult(): MongoDB\Driver\WriteResult
/* Métodos herdados */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Propriedades

writeResult
  O MongoDB\Driver\WriteResult associado à operação de gravação com falha.

## Registro de Alterações

Versão | Descrição
--- | ---
PECL mongodb 2.0.0 | Esta classe foi removida.
PECL mongodb 1.20.0 | Esta classe foi descontinuada e será removida na versão 2.0.
PECL mongodb 1.5.0 | Esta classe agora estende a classe MongoDB\Driver\Exception\ServerException ao invés da MongoDB\Driver\Exception\RuntimeException.

# MongoDB\Driver\Exception\WriteException::getWriteResult

(mongodb >= 1.0.0)

MongoDB\Driver\Exception\WriteException::getWriteResult — Retorna o WriteResult da operação de gravação com falha

### Descrição

final public function MongoDB\Driver\Exception\WriteException::getWriteResult(): MongoDB\Driver\WriteResult

Retorna o MongoDB\Driver\WriteResult para a operação de gravação com falha. Os métodos MongoDB\Driver\WriteResult::getWriteErrors() e MongoDB\Driver\WriteResult::getWriteConcernError() podem ser usados ​​para obter mais detalhes sobre a falha.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O MongoDB\Driver\WriteResult para a operação de gravação com falha.

### Exemplos

Exemplo #1 Exemplo de MongoDB\Driver\Exception\WriteException::getWriteResult()

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost');
    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 1]);

    try {
        $manager->executeBulkWrite('db.collection', $bulk);
    } catch (MongoDB\Driver\Exception\WriteException $e) {
        $writeResult = $e->getWriteResult();

        if ($writeConcernError = $writeResult->getWriteConcernError()) {
            var_dump($writeConcernError);
        }

        if ($writeErrors = $writeResult->getWriteErrors()) {
            var_dump($writeErrors);
        }
    }

    ?>

O exemplo acima produzirá algo semelhante a:

    array(1) {
      [0]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(70) "E11000 duplicate key error index: db.collection.$_id_ dup key: { : 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(1)
        ["info"]=>
        NULL
      }
    }

### Veja Também

- MongoDB\Driver\WriteResult
- MongoDB\Driver\Manager::executeBulkWrite() - Executa uma ou mais operações de escrita

## Índice

- MongoDB\Driver\Exception\WriteException::getWriteResult — Retorna o WriteResult da operação de gravação com falha

# Árvore de Classes de Exceção do MongoDB

A hierarquia de classes para exceções do MongoDB é modelada a partir das Exceções SPL. As classes base estendem sua contraparte SPL e todas as classes de exceção na extensão implementam a interface MongoDB\Driver\Exception\Exception.

- MongoDB\Driver\Exception\LogicException (extends LogicException)
- MongoDB\Driver\Exception\InvalidArgumentException (extends InvalidArgumentException)
- MongoDB\Driver\Exception\UnexpectedValueException (extends UnexpectedValueException)
- MongoDB\Driver\Exception\RuntimeException (extends RuntimeException)
  - MongoDB\Driver\Exception\ConnectionException
    - MongoDB\Driver\Exception\AuthenticationException
    - MongoDB\Driver\Exception\ConnectionTimeoutException
    - MongoDB\Driver\Exception\SSLConnectionException (descontinuada)
  - MongoDB\Driver\Exception\EncryptionException
  - MongoDB\Driver\Exception\ServerException
    - MongoDB\Driver\Exception\BulkWriteCommandException
    - MongoDB\Driver\Exception\CommandException
    - MongoDB\Driver\Exception\ExecutionTimeoutException
    - MongoDB\Driver\Exception\WriteException (descontinuada)
      - MongoDB\Driver\Exception\BulkWriteException

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
- Constantes predefinidas
- Tutoriais
  - Usando a Biblioteca do PHP para o MongoDB (PHPLIB)
  - Monitoramento de Desempenho de Aplicação (APM)
- Arquitetura do driver e componentes internos — Explica a arquitetura do driver e recursos especiais
  - Arquitetura — Visão geral da arquitetura
  - Conexões — Manipulação de conexão e persistência
  - Dados Persistentes — Serialização e desserialização de variáveis PHP no MongoDB
- Segurança
  - Ataques de Injeção de Requisição
  - Ataques de injeção de script
- MongoDB\Driver — Classes da Extensão MongoDB
  - MongoDB\Driver\Manager — A classe MongoDB\Driver\Manager
  - MongoDB\Driver\Command — A classe MongoDB\Driver\Command
  - MongoDB\Driver\Query — A classe MongoDB\Driver\Query
  - MongoDB\Driver\BulkWrite — A classe MongoDB\Driver\BulkWrite
  - MongoDB\Driver\BulkWriteCommand — A classe MongoDB\Driver\BulkWriteCommand
  - MongoDB\Driver\Session — A classe MongoDB\Driver\Session
  - MongoDB\Driver\ClientEncryption — A classe MongoDB\Driver\ClientEncryption
  - MongoDB\Driver\ServerApi — A classe MongoDB\Driver\ServerApi
  - MongoDB\Driver\WriteConcern — A classe MongoDB\Driver\WriteConcern
  - MongoDB\Driver\ReadPreference — A classe MongoDB\Driver\ReadPreference
  - MongoDB\Driver\ReadConcern — A classe MongoDB\Driver\ReadConcern
  - MongoDB\Driver\Cursor — A classe MongoDB\Driver\Cursor
  - MongoDB\Driver\CursorId — A classe MongoDB\Driver\CursorId
  - MongoDB\Driver\CursorInterface — A interface MongoDB\Driver\CursorInterface
  - MongoDB\Driver\Server — A classe MongoDB\Driver\Server
  - MongoDB\Driver\ServerDescription — A classe MongoDB\Driver\ServerDescription
  - MongoDB\Driver\TopologyDescription — A classe MongoDB\Driver\TopologyDescription
  - MongoDB\Driver\WriteConcernError — A classe MongoDB\Driver\WriteConcernError
  - MongoDB\Driver\WriteError — A classe MongoDB\Driver\WriteError
  - MongoDB\Driver\WriteResult — A classe MongoDB\Driver\WriteResult
  - MongoDB\Driver\BulkWriteCommandResult — A classe MongoDB\Driver\BulkWriteCommandResult
- MongoDB\BSON — Classes e Funções BSON do MongoDB
  - Funções
  - MongoDB\BSON\Document — A classe MongoDB\BSON\Document
  - MongoDB\BSON\PackedArray — A classe MongoDB\BSON\PackedArray
  - MongoDB\BSON\Iterator — A classe MongoDB\BSON\Iterator
  - MongoDB\BSON\Binary — A classe MongoDB\BSON\Binary
  - MongoDB\BSON\VectorType — A enumeração MongoDB\BSON\VectorType
  - MongoDB\BSON\Decimal128 — A classe MongoDB\BSON\Decimal128
  - MongoDB\BSON\Javascript — A classe MongoDB\BSON\Javascript
  - MongoDB\BSON\MaxKey — A classe MongoDB\BSON\MaxKey
  - MongoDB\BSON\MinKey — A classe MongoDB\BSON\MinKey
  - MongoDB\BSON\ObjectId — A classe MongoDB\BSON\ObjectId
  - MongoDB\BSON\Regex — A classe MongoDB\BSON\Regex
  - MongoDB\BSON\Timestamp — A classe MongoDB\BSON\Timestamp
  - MongoDB\BSON\UTCDateTime — A classe MongoDB\BSON\UTCDateTime
  - MongoDB\BSON\Type — A interface MongoDB\BSON\Type
  - MongoDB\BSON\Persistable — A interface MongoDB\BSON\Persistable
  - MongoDB\BSON\Serializable — A interface MongoDB\BSON\Serializable
  - MongoDB\BSON\Unserializable — A interface MongoDB\BSON\Unserializable
  - MongoDB\BSON\BinaryInterface — A interface MongoDB\BSON\BinaryInterface
  - MongoDB\BSON\Decimal128Interface — A interface MongoDB\BSON\Decimal128Interface
  - MongoDB\BSON\JavascriptInterface — A interface MongoDB\BSON\JavascriptInterface
  - MongoDB\BSON\MaxKeyInterface — A interface MongoDB\BSON\MaxKeyInterface
  - MongoDB\BSON\MinKeyInterface — A interface MongoDB\BSON\MinKeyInterface
  - MongoDB\BSON\ObjectIdInterface — A interface MongoDB\BSON\ObjectIdInterface
  - MongoDB\BSON\RegexInterface — A interface MongoDB\BSON\RegexInterface
  - MongoDB\BSON\TimestampInterface — A interface MongoDB\BSON\TimestampInterface
  - MongoDB\BSON\UTCDateTimeInterface — A interface MongoDB\BSON\UTCDateTimeInterface
  - MongoDB\BSON\DBPointer — A classe MongoDB\BSON\DBPointer
  - MongoDB\BSON\Int64 — A classe MongoDB\BSON\Int64
  - MongoDB\BSON\Symbol — A classe MongoDB\BSON\Symbol
  - MongoDB\BSON\Undefined — A classe MongoDB\BSON\Undefined
- MongoDB\Driver\Monitoring — Classes de monitoramento e funções assinantes
  - Funções
  - MongoDB\Driver\Monitoring\CommandFailedEvent — A classe MongoDB\Driver\Monitoring\CommandFailedEvent
  - MongoDB\Driver\Monitoring\CommandStartedEvent — A classe MongoDB\Driver\Monitoring\CommandStartedEvent
  - MongoDB\Driver\Monitoring\CommandSucceededEvent — A classe MongoDB\Driver\Monitoring\CommandSucceededEvent
  - MongoDB\Driver\Monitoring\ServerChangedEvent — A classe MongoDB\Driver\Monitoring\ServerChangedEvent
  - MongoDB\Driver\Monitoring\ServerClosedEvent — A classe MongoDB\Driver\Monitoring\ServerClosedEvent
  - MongoDB\Driver\Monitoring\ServerOpeningEvent — A classe MongoDB\Driver\Monitoring\ServerOpeningEvent
  - MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent — A classe MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent
  - MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent — A classe MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent
  - MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent — A classe MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent
  - MongoDB\Driver\Monitoring\TopologyChangedEvent — A classe MongoDB\Driver\Monitoring\TopologyChangedEvent
  - MongoDB\Driver\Monitoring\TopologyClosedEvent — A classe MongoDB\Driver\Monitoring\TopologyClosedEvent
  - MongoDB\Driver\Monitoring\TopologyOpeningEvent — A classe MongoDB\Driver\Monitoring\TopologyOpeningEvent
  - MongoDB\Driver\Monitoring\CommandSubscriber — A interface MongoDB\Driver\Monitoring\CommandSubscriber
  - MongoDB\Driver\Monitoring\LogSubscriber — A interface MongoDB\Driver\Monitoring\LogSubscriber
  - MongoDB\Driver\Monitoring\SDAMSubscriber — A interface MongoDB\Driver\Monitoring\SDAMSubscriber
  - MongoDB\Driver\Monitoring\Subscriber — A interface MongoDB\Driver\Monitoring\Subscriber
- MongoDB\Driver\Exception — Classes de exceção
  - MongoDB\Driver\Exception\AuthenticationException — A classe MongoDB\Driver\Exception\AuthenticationException
  - MongoDB\Driver\Exception\BulkWriteException — A classe MongoDB\Driver\Exception\BulkWriteException
  - MongoDB\Driver\Exception\BulkWriteCommandException — A classe MongoDB\Driver\Exception\BulkWriteCommandException
  - MongoDB\Driver\Exception\CommandException — A classe MongoDB\Driver\Exception\CommandException
  - MongoDB\Driver\Exception\ConnectionException — A classe MongoDB\Driver\Exception\ConnectionException
  - MongoDB\Driver\Exception\ConnectionTimeoutException — A classe MongoDB\Driver\Exception\ConnectionTimeoutException
  - MongoDB\Driver\Exception\EncryptionException — A classe MongoDB\Driver\Exception\EncryptionException
  - MongoDB\Driver\Exception\Exception — A interface MongoDB\Driver\Exception\Exception
  - MongoDB\Driver\Exception\ExecutionTimeoutException — A classe MongoDB\Driver\Exception\ExecutionTimeoutException
  - MongoDB\Driver\Exception\InvalidArgumentException — A classe MongoDB\Driver\Exception\InvalidArgumentException
  - MongoDB\Driver\Exception\LogicException — A classe MongoDB\Driver\Exception\LogicException
  - MongoDB\Driver\Exception\RuntimeException — A classe MongoDB\Driver\Exception\RuntimeException
  - MongoDB\Driver\Exception\ServerException — A classe MongoDB\Driver\Exception\ServerException
  - MongoDB\Driver\Exception\SSLConnectionException — A classe MongoDB\Driver\Exception\SSLConnectionException
  - MongoDB\Driver\Exception\UnexpectedValueException — A classe MongoDB\Driver\Exception\UnexpectedValueException
  - MongoDB\Driver\Exception\WriteException — A classe MongoDB\Driver\Exception\WriteException
  - Árvore de Classes — Árvore de Classes de Exceção do MongoDB

# Drivers e Plugins MySQL

PHP oferece vários drivers e plugins MySQL para acessar e lidar com o MySQL.

As diferenças e a funcionalidade das extensões MySQL estão descritas na visão geral desta seção.

As extensões listadas suportam o protocolo MySQL. Exemplos de servidores de banco de dados compatíveis são » MariaDB Server, » MySQL Server, » Percona Server for MySQL e » TiDB.

# Visão geral dos drivers PHP para MySQL

# Introdução

Existem muitas APIs de PHP para acessar bancos de dados MySQL. Os usuários podem escolher entre as extesões mysqli ou PDO_MySQL.

Este guia explica a terminologia usada para descrever cada API, informação sobre a escolha de qual API a ser usada, e também informação para ajudar a escolher qual biblioteca MySQL a ser usada com a API.

# Visão geral de terminologia

Esta seção fornece uma introdução às opções disponíveis ao desenvolver aplicações PHP que precisem interagir com um banco de dados MySQL.

O que é uma API?

Uma Interface de Programação para Aplicações, ou API, define as classes, métodos, funções e variáveis que a aplicação precisará chamar para que consiga efetuar a tarefa desejada. No caso de aplicações PHP que precisem comunicar com banco de dados, as APIs necessárias são normalmente expostas através de extensões do PHP.

APIs podem ser procedurais ou orientadas a objeto. Com uma API procedural, pode-se chamar funções para realizar tarefas, e com uma API orientada a objeto, pode-se instanciar classes e então chamar métodos nos objetos resultantes. Entre as duas opções, a última é a interface recomendada, já que é mais moderna e leva a um código mais organizado.

Ao escrever aplicações PHP que precisam se conectar ao servidor MySQL, existem várias opções de API disponíveis. Este documento discute o que está disponível e como selecionar a melhor solução para cada aplicação.

O que é um conector?

Na documentação MySQL, o termo conector se refere a uma parte do software que permite à aplicação se conectar ao servidor de banco de dados MySQL. O MySQL fornece conectores para uma variedade de linguagens, incluindo o PHP.

Se uma aplicação PHP precisa se comunicar com um servidor de banco de dados será necessário escrever código PHP para realizar tais atividades como conexão ao banco de dados, consultas ao banco e outras funções relacionadas. Software é requerido para fornecer a API que a aplicação PHP irá utilizar, e também para lidar com a comunicação entre a aplicação e o servidor de banco de dados, possivelmente usando outras bibliotecas intermediárias quando necessário. Este software é conhecimento genericamente como conector, já que ele permite à aplicação se conectar ao servidor de banco de dados.

O que é um Driver?

Um driver é uma parte do software projetada para se comunicar com um tipo específico de servidor de banco de dados. O driver também pode chamar uma biblioteca, tal como a Bliblioteca Cliente MySQL ou o Driver Nativo MySQL. Estas bibliotecas implementam o protocolo de baixo nível usado para comunicação com o servidor de dados MySQL.

Para exemplificar, a camada de abstração de banco da dados PDO - Objetos de Dados PHP pode usar um dos vários drivers específicos para banco de dados. Um dos drivers disponíveis é o driver PDO MYSQL, que permite fazer interface com o servidor MySQL.

Algumas vezes os termos conector e driver são usados de maneira intercambiável, e isto pode ser confuso. Na documentação relacionada com o MySQL o termo driver é reservado para o software que fornece a parte específica de banco de dados de um pacote de conector.

O que é uma Extensão?

Na documentação PHP, encontramos um outro termo - extensão. O código PHP consiste de um núcleo, com extensões opcionais à funcionalidade do núcleo. A extensão do PHP relacionada com o MySQL, `mysqli`, é implementada usando o framework de extensão PHP.

Uma extensão tipicamente expõe uma API para o programador PHP, para permitir que suas instalações possam ser usadas programaticamente. Entretanto, algumas extensões que usam o framework de extensão PHP não expõem uma API ao programador PHP.

A extensão do driver de PDO MySQL, por exemplo, não expõe uma API ao programador PHP, mas fornece uma interface à camada PDO acima dela.

Os termos API e extensão não podem ser considerados com o mesmo significado, já que uma extensão não necessáriamente expões uma API ao programador.

# Escolhendo uma API

O PHP oferece diferentes APIs para conexão ao MySQL. Pode-se ver abaixo as APIs fornecidas pelas extensões mysqli e PDO. Cada porção de código cria uma conexão a um servidor MySQL sendo executado em "example.com" usando o usuário "user" e a senha "password". E uma consulta é executada para cumprimentar o usuário.

Exemplo #1 Comparando as APIs do MySQL

    <?php
    // mysqli
    $mysqli = new mysqli("example.com", "user", "password", "database");
    $result = $mysqli->query("SELECT 'Olá, prezado usuário MySQL!' AS _message FROM DUAL");
    $row = $result->fetch_assoc();
    echo htmlentities($row['_message']);

    // PDO
    $pdo = new PDO('mysql:host=example.com;dbname=database', 'user', 'password');
    $statement = $pdo->query("SELECT 'Olá, prezado usuário MySQL!' AS _message FROM DUAL");
    $row = $statement->fetch(PDO::FETCH_ASSOC);
    echo htmlentities($row['_message']);

Exemplo #2 Comparando instruções preparadas

    <?php
    // mysqli
    $mysqli = new mysqli("example.com", "user", "password", "database");
    $statement = $mysqli->prepare("SELECT District FROM City WHERE Name=?");
    $statement->execute(["Amersfoort"]);
    $result = $statement->get_result();
    $row = $result->fetch_assoc();
    echo htmlentities($row['District']);

    // PDO
    $pdo = new PDO('mysql:host=example.com;dbname=database', 'user', 'password');
    $statement = $pdo->prepare("SELECT District FROM City WHERE Name=?");
    $statement->execute(["Amersfoort"]);
    $row = $statement->fetch(PDO::FETCH_ASSOC);
    echo htmlentities($row['District']);

Comparação de características

O desempenho geral de ambas as extensões é considerada aproximadamente a mesma, embora o desempenho da extensão contribui somente para uma fração do tempo total de uma requisição web do PHP. Frequentemente, o impacto é tão baixo quanto 0,1%.

| ext/mysqli | PDO_MySQL
--- | --- | ---
Versão em que foi introduzida no PHP | 5.0 | 5.1
Incluída no PHP 7.x e 8.x | Sim | Sim
Estado do desenvolvimento | Ativo | Ativo
Ciclo de vida | Ativo | Ativo
Recomendado para novos projetos | Sim | Sim
Interface POO | Sim | Sim
Interface Procedural | Sim | Não
API suporta consultas sem bloqueio assíncronas com mysqlnd | Sim | Não
Conexões persistentes | Sim | Sim
API suporta conjuntos de caracteres | Sim | Sim
API suporta Instruções Preparadas no lado do servidor | Sim | Sim
API suporta Instruções Preparadas no lado do cliente | Não | Sim
API suporta Procedimentos Armazenados | Sim | Sim
API suporta Múltiplas Instruções | Sim | A maioria
API suporta Transações | Sim | Sim
Transações podem ser controladas com SQL | Sim | Sim
Supporta toda a funcionalidade do MySQL 5.1+ | Sim | A maioria

# Escolhendo uma biblioteca

As extensões mysqli e PDO_MySQL são encapsuladores leves de uma biblioteca cliente em C. As extensões podem tanto usar a biblioteca mysqlnd quanto a biblioteca `libmysqlclient`. Escolher uma biblioteca é uma decisão a ser tomada na compilação.

A biblioteca mysqlnd é parte da distribuição PHP. Ela oferece recursos como conexões preguiçosas e cache de consultas, que não estão disponíveis com a libmysqlclient, portanto usar a biblioteca mysqlnd interna é altamente recomendado. Consulte a documentação mysqlnd para detalhes adicionais e uma lista de recursos e funcionalidade que ela oferece.

Exemplo #1 Comandos de configuração para usar mysqlnd ou libmysqlclient

    // Recomendado, compilar com mysqlnd
    $ ./configure --with-mysqli=mysqlnd --with-pdo-mysql=mysqlnd

    // Alternativamente recomendado, compilar com mysqlnd
    $ ./configure --with-mysqli --with-pdo-mysql

    // Não recomendado, compila com libmysqlclient
    $ ./configure --with-mysqli=/path/to/mysql_config --with-pdo-mysql=/path/to/mysql_config

Comparação de recursos de bibliotecas

É recomendado usar a biblioteca mysqlnd ao invés da biblioteca Cliente-Servidor do MySQL (libmysqlclient). Ambas são suportadas e estão constantemente sendo melhoradas.

| Driver nativo MySQL (mysqlnd) | Biblioteca cliente-servidor MySQL (`libmysqlclient`)
--- | --- | ---
Faz parte da distribuição PHP | Sim | Não
Versão do PHP em que foi introduzida | 5.3.0 | N/A
Licença | Licença PHP 3.01 | Dupla Licença
Estado de desenvolvimento | Ativo | Ativo
Ciclo de vida | Nenhum final anunciado | Nenhum final anunciado
Padrão de compilação (para todas as extensões MySQL) | Sim | Não
Suporte a protocolo de compressão | Sim | Sim
Suporte a SSL | Sim | Sim
Suporte a tubos nomeados | Sim | Sim
Consultas sem bloqueio assíncronas | Sim | Não
Estatísticas de desempenho | Sim | Não
LOAD LOCAL INFILE respeita a diretiva open_basedir | Sim | Não
Usa o sistema de gerenciamento de memória nativo do PHP (ex: segue os limites de memória do PHP) | Sim | Não
Retorna coluna numérica como dupla precisão (COM_QUERY) | Sim | Não
Retorna coluna numérica como string (COM_QUERY) | Sim | Sim
API tipo plugin | Sim | Limitada
Reconexão automática | Não | Opcional

# Conceitos

## Índice

- Consultas com buffer e sem buffer
- Conjuntos de caracteres

Esses conceitos são específicos dos drivers MySQL para PHP.

## Consultas com buffer e sem buffer

As consultas usam o modo de buffer por padrão. Isso significa que os resultados da consulta são imediatamente transferidos do servidor MySQL para o PHP e então mantidos na memória do processo PHP. Isso permite operações adicionais, como contar o número de linhas e mover (buscar) o ponteiro do resultado atual. Também permite emitir consultas adicionais na mesma conexão enquanto trabalha no conjunto de resultados. A desvantagem do modo buffer é que conjuntos de resultados maiores podem exigir bastante memória. A memória será mantida ocupada até que todas as referências ao conjunto de resultados sejam desativadas ou o conjunto de resultados seja explicitamente liberado, o que acontecerá automaticamente durante o término da solicitação, o mais tardar. A terminologia "armazenar resultado" também é usada para o modo buffer, pois todo o conjunto de resultados é armazenado de uma só vez.

> Nota: Ao usar a libmysqlclient como biblioteca, o limite de memória do PHP não contará a memória usada para conjuntos de resultados, a menos que os dados sejam buscados em variáveis ​​PHP. Com o mysqlnd a memória contabilizada incluirá o conjunto completo de resultados.

Consultas MySQL sem buffer executam a consulta e aguardam que os dados do servidor MySQL sejam buscados. Isso usa menos memória do lado do PHP, mas pode aumentar a carga no servidor. A menos que o conjunto completo de resultados tenha sido obtido do servidor, nenhuma consulta adicional poderá ser enviada pela mesma conexão. Consultas sem buffer também podem ser chamadas de "resultado de uso". Depois que todas as linhas do conjunto de resultados forem buscadas, o conjunto de resultados desaparecerá e não poderá ser iterado novamente.

Seguindo essas características, consultas sem buffer devem ser utilizadas apenas quando se espera um grande conjunto de resultados que será processado sequencialmente. As consultas sem buffer contêm uma série de armadilhas que tornam mais difícil seu uso, por exemplo, o número de linhas no conjunto de resultados é desconhecido até que a última linha seja obtida. Consultas em buffer são a maneira mais fácil e flexível de processar conjuntos de resultados.

Como as consultas em buffer são o padrão, os exemplos abaixo demonstrarão como executar consultas sem buffer com cada API.

Exemplo #1 Exemplo de consulta sem buffer: mysqli

    <?php
    $mysqli  = new mysqli("localhost", "my_user", "my_password", "world");
    $unbufferedResult = $mysqli->query("SELECT Name FROM City", MYSQLI_USE_RESULT);

    foreach ($unbufferedResult as $row) {
        echo $row['Name'] . PHP_EOL;
    }
    ?>

Exemplo #2 Exemplo de consulta sem buffer: pdo_mysql

    <?php
    $pdo = new PDO("mysql:host=localhost;dbname=world", 'my_user', 'my_password');
    $pdo->setAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY, false);

    $unbufferedResult = $pdo->query("SELECT Name FROM City");
    foreach ($unbufferedResult as $row) {
        echo $row['Name'] . PHP_EOL;
    }
    ?>

## Conjuntos de caracteres

Idealmente, um conjunto de caracteres adequado será definido no nível do servidor, e isso é descrito na seção » Configuração do conjunto de caracteres do manual do servidor MySQL. Alternativamente, cada API MySQL oferece um método para definir o conjunto de caracteres em tempo de execução.

Cuidado

# O conjunto de caracteres e escape de caracteres

O conjunto de caracteres deve ser entendido e definido, pois afeta todas as ações e inclui implicações de segurança. Por exemplo, o mecanismo de escape (por exemplo, mysqli_real_escape_string() para mysqli e PDO::quote() para PDO_MySQL) irá aderir a esta configuração. É importante perceber que essas funções não usarão o conjunto de caracteres definido com uma consulta, portanto, por exemplo, o seguinte não terá efeito sobre elas:

Exemplo #1 Problemas ao definir o conjunto de caracteres com SQL

    <?php

    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    // Não afetará $mysqli->real_escape_string();
    $mysqli->query("SET NAMES utf8mb4");

    // Não afetará $mysqli->real_escape_string();
    $mysqli->query("SET CHARACTER SET utf8mb4");

    // Mas isto afetará $mysqli->real_escape_string();
    $mysqli->set_charset('utf8mb4');

    // Porém, isto NÃO irá afetá-la (UTF-8 vs utf8mb4) -- não use hífens aqui
    $mysqli->set_charset('UTF-8');
    ?>

Abaixo estão exemplos que demonstram como alterar adequadamente o conjunto de caracteres em tempo de execução usando cada API.

> Nota: Possível confusão UTF-8
> Como os nomes dos conjuntos de caracteres no MySQL não contêm hífens, a string "utf8" é válida no MySQL para definir o conjunto de caracteres como UTF-8 (codificação Unicode UTF-8 de até 3 bytes). A string "UTF-8" não é válida, pois o uso de "UTF-8" não alterará o conjunto de caracteres e gerará um erro.

Exemplo #2 Exemplo de definição do conjunto de caracteres: mysqli

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    echo 'Conjunto de caracteres inicial: ' . $mysqli->character_set_name() . "\n";

    if (!$mysqli->set_charset('utf8mb4')) {
        printf("Erro ao carregar o conjunto de caracteres utf8mb4: %s\n", $mysqli->error);
        exit;
    }

    echo 'Seu conjunto de caracteres atual é: ' . $mysqli->character_set_name() . "\n";
    ?>

Exemplo #3 Exemplo de definição do conjunto de caracteres: pdo_mysql

    <?php
    $pdo = new PDO("mysql:host=localhost;dbname=world;charset=utf8mb4", 'my_user', 'my_pass');
    ?>

- Visão geral de terminologia
- Escolhendo uma API
- Escolhendo uma biblioteca
- Conceitos
  - Consultas com buffer e sem buffer
  - Conjuntos de caracteres

# Extensão MySQL Melhorada

# Introdução

A extensão `mysqli` permite a você acessar a funcionalidade provida pelo MySQL 4.1 e posterior. Maiores informações sobre o servidor de banco de dados MySQL podem ser encontradas em » http://www.mysql.com/

Uma visão geral de software disponível para usar MySQL através do PHP pode ser encontrada em Visão Geral

Documentação para o MySQL pode ser encontrada em » http://dev.mysql.com/doc/.

Partes desta documentação foram incluídas do manual do MySQL com a permissão de Oracle Corporation.

Os exemplos usam tanto o banco de dados » world quanto o banco de dados » sakila, que estão disponíveis livremente.

# Visão Geral

Esta seção fornece uma introdução às opções disponíveis ao desenvolver um aplicativo PHP que precisa interagir com um banco de dados MySQL.

O que é uma API?

Uma interface de programação de aplicativos, ou API, define as classes, métodos, funções e variáveis que seu aplicativo precisará chamar para executar a tarefa desejada. No caso de aplicativos PHP que precisam se comunicar com bancos de dados, as APIs necessárias geralmente são expostas por meio de extensões PHP.

As APIs podem ser processuais ou orientadas a objetos. Com uma API procedural, você chama funções para realizar tarefas, com a API orientada a objetos você instancia classes e então chama métodos nos objetos resultantes. Das duas, a última costuma ser a interface preferida, pois é mais moderna e leva a um código mais organizado.

Ao escrever aplicativos PHP que precisam se conectar ao servidor MySQL, existem várias opções de API disponíveis. Este documento discute o que está disponível e como selecionar a melhor solução para sua aplicação.

O que é um Conector?

Na documentação do MySQL, o termo conector refere-se a um software que permite que seu aplicativo se conecte ao servidor de banco de dados MySQL. MySQL fornece conectores para uma variedade de linguagens, incluindo PHP.

Se seu aplicativo PHP precisar se comunicar com um servidor de banco de dados, você precisará escrever código PHP para executar atividades como conectar-se ao servidor de banco de dados, consultar o banco de dados e outras funções relacionadas ao banco de dados. O software é necessário para fornecer a API que seu aplicativo PHP usará e também para lidar com a comunicação entre seu aplicativo e o servidor de banco de dados, possivelmente usando outras bibliotecas intermediárias quando necessário. Este software é conhecido genericamente como conector, pois permite que sua aplicação se connect a um servidor de banco de dados.

O que é um Driver?

Um driver é um software projetado para se comunicar com um tipo específico de servidor de banco de dados. O driver também pode chamar uma biblioteca, como a MySQL Client Library ou o MySQL Native Driver. Essas bibliotecas implementam o protocolo de baixo nível usado para se comunicar com o servidor de banco de dados MySQL.

A título de exemplo, a camada de abstração do banco de dados PHP Data Objects (PDO) pode usar um dos vários drivers específicos do banco de dados. Um dos drivers disponíveis é o driver PDO MYSQL, que permite a interface com o servidor MySQL.

Às vezes, as pessoas usam os termos conector e driver de forma intercambiável, o que pode ser confuso. Na documentação relacionada ao MySQL, o termo driver é reservado para software que fornece a parte específica do banco de dados de um pacote de conector.

O que é uma Extensão?

Na documentação do PHP, você encontrará outro termo - extension. O código PHP consiste em um núcleo, com extensões opcionais para a funcionalidade principal. As extensões relacionadas ao MySQL do PHP, como a extensão mysqli e a extensão do driver PDO MySQL, são implementadas usando a estrutura de extensão do PHP.

Uma extensão normalmente expõe uma API ao programador PHP, para permitir que suas facilidades sejam usadas programaticamente. No entanto, algumas extensões que usam a estrutura de extensão PHP não expõem uma API ao programador PHP.

A extensão do driver PDO MySQL, por exemplo, não expõe uma API ao programador PHP, mas fornece uma interface para a camada PDO acima dela.

Os termos API e extensão não devem significar a mesma coisa, pois uma extensão pode não necessariamente expor uma API ao programador.

Quais são as principais ofertas de API do PHP para usar o MySQL?

Existem duas opções principais de API ao considerar a conexão com um servidor de banco de dados MySQL:

- Extensão mysqli do PHP

- Objetos de Dados PHP (PDO)

Cada um tem suas próprias vantagens e desvantagens. A discussão a seguir visa fornecer uma breve introdução aos principais aspectos de cada API.

O que é a extensão mysqli do PHP?

A extensão `mysqli`, ou como às vezes é conhecida, a extensão improved do MySQL, foi desenvolvida para aproveitar os novos recursos encontrados nos sistemas MySQL versões 4.1.3 e mais recentes. A extensão `mysqli` está incluída nas versões 5 e posteriores do PHP.

A extensão `mysqli` tem vários benefícios, sendo os principais aprimoramentos sobre a extensão `mysql`:

- Interface orientada a objetos

- Suporte para Declarações Preparadas

- Suporte para várias declarações

- Suporte para transações

- Recursos de depuração aprimorados

Assim como a interface orientada a objetos, a extensão também fornece uma interface processual.

A extensão `mysqli` é construída usando a e strutura de extensão PHP, seu código fonte está localizado no diretório ext/mysqli.

Para obter mais informações sobre a extensão `mysqli`, consulte MySQLi.

O que é PDO?

PHP Data Objects, ou PDO, é uma camada de abstração de banco de dados especificamente para aplicativos PHP. O PDO fornece uma API consistente para seu aplicativo PHP, independentemente do tipo de servidor de banco de dados ao qual seu aplicativo se conectará. Em teoria, se você estiver usando a API PDO, você pode mudar o servidor de banco de dados que você usou, digamos Firebird para MySQL, e só precisa fazer pequenas alterações em seu código PHP.

Outros exemplos de camadas de abstração de banco de dados incluem JDBC para aplicativos Java e DBI para Perl.

Embora o PDO tenha suas vantagens, como uma API limpa, simples e portátil, sua principal desvantagem é que ele não permite que você use todos os recursos avançados disponíveis nas versões mais recentes do servidor MySQL. Por exemplo, PDO não permite que você use o suporte do MySQL para Multiple Statements.

PDO é implementado usando o framework de extensão PHP, seu código fonte está localizado no diretório ext/pdo.

Para mais informações sobre PDO, consulte o PDO.

O que é o driver PDO MYSQL?

O driver PDO MYSQL não é uma API como tal, pelo menos da perspectiva do programador PHP. Na verdade, o driver PDO MYSQL fica na camada abaixo do próprio PDO e fornece funcionalidade específica do MySQL. O programador ainda chama a API PDO, mas o PDO usa o driver PDO MYSQL para realizar a comunicação com o servidor MySQL.

O driver PDO MYSQL é um dos vários drivers PDO disponíveis. Outros drivers PDO disponíveis incluem aqueles para os servidores de banco de dados Firebird e PostgreSQL.

O driver PDO MYSQL é implementado usando a estrutura de extensão PHP. Seu código-fonte está localizado no diretório ext/pdo_mysql. Ele não expõe uma API ao programador PHP.

Para obter mais informações sobre o driver PDO MYSQL, consulte Driver PDO do MySQL.

O que é o driver nativo MySQL do PHP?

Para se comunicar com o servidor de banco de dados MySQL, `mysqli` e o driver PDO MYSQL usam uma biblioteca de baixo nível que implementa o protocolo necessário. No passado, a única biblioteca disponível era a MySQL Client Library, também conhecida como `libmysqlclient`.

No entanto, a interface apresentada pelo `libmysqlclient` não foi otimizada para comunicação com aplicativos PHP, pois `libmysqlclient` foi originalmente projetado com aplicativos C em mente. Por esta razão, o MySQL Native Driver, `mysqlnd`, foi desenvolvido como uma alternativa ao `libmysqlclient` para aplicações PHP.

Tanto a extensão `mysqli` quanto o driver PDO MySQL podem ser configurados individualmente para usar `libmysqlclient`ou `mysqlnd`. Como o `mysqlnd` foi projetado especificamente para ser utilizado no sistema PHP, ele possui vários aprimoramentos de memória e velocidade em relação ao `libmysqlclient`. Você é fortemente encorajado a aproveitar essas melhorias.

O MySQL Native Driver é implementado usando a estrutura de extensão PHP. O código-fonte está localizado em ext/mysqlnd. Ele não expõe uma API ao programador PHP.

Comparação de recursos

A tabela a seguir compara a funcionalidade dos principais métodos de conexão ao MySQL a partir do PHP:

Comparação das opções da API do MySQL para PHP
| Extensão mysqli do PHP | PDO (usando PDO MySQL Driver e MySQL Native Driver)
--- | --- | ---
Versão do PHP introduzida | 5.0 | 5.0
Status de desenvolvimento do MySQL | Desenvolvimento ativo | Desenvolvimento ativo
API suporta conjuntos de caracteres | Sim | Sim
A API oferece suporte a instruções preparadas do lado do servidor | Sim | Sim
A API oferece suporte a declarações preparadas do lado do cliente | Não | Sim
API suporta procedimentos armazenados | Sim | Sim
A API oferece suporte a várias instruções | Sim | A maioria
Suporta todas as funcionalidades do MySQL 4.1+ | Sim | A maioria

# Guia de início rápido

## Índice

- Interface dupla, procedural e orientada a objetos
- Conexões
- Executando instruções
- Instruções Preparadas
- Procedimentos Armazenados
- Instruções Múltiplas
- Suporte da API para transações
- Metadados

Este guia de início rápido irá ajudar nas escolhas e no ganho de familiaridade com a API de MySQL do PHP.

Este início rápido dá uma visão geral da extensão mysqli. Exemplos de código são disponibilizados para todos os macro aspectos da API. Conceitos de banco de dados são explicados no grau necessário para apresentar os conceitos específicos do MySQL.

Requisito: Uma familiaridade com a linguagem de programação PHP, com a linguagem SQL, e conhecimento básico do servidor MySQL.

## Interface dupla, procedural e orientada a objetos

A extensão mysqli possibilita uma dupla interface. Ela suporta o paradigma de programação procedural e orientada a objetos.

Usuários que estão migrando da extensão antiga mysql podem preferir a interface procedural. Esta interface é similar àquela da extensão antiga mysql. Em muitos casos, os nomes das funções diferem apenas pelo prefixo. Algumas funções mysqli levam um manipulador de conexão como seu primeiro argumento, enquanto as funções análogas na antiga interface mysql levam este manipulador como o último argumento, opcional.

Exemplo #1 Migração fácil da antiga extensão mysql

    <?php
    $mysqli = mysqli_connect("example.com", "user", "password", "database");
    $result = mysqli_query($mysqli, "SELECT 'Por favor não use a extensão mysql descontinuada para novos desenvolvimentos. ' AS _msg FROM DUAL");
    $row = mysqli_fetch_assoc($result);
    echo $row['_msg'];

    $mysql = mysql_connect("example.com", "user", "password");
    mysql_select_db("test");
    $result = mysql_query("SELECT 'Use a extensão mysqli em seu lugar.' AS _msg FROM DUAL", $mysql);
    $row = mysql_fetch_assoc($result);
    echo $row['_msg'];

O exemplo acima produzirá:

    Por favor não use a extensão mysql descontinuada para novos desenvolvimentos. Use a extensão mysqli em seu lugar.

A interface orientada a objetos

Em adição à clássica interface procedural, usuários podem escolher usar a interface orientada a objetos. A documentação está organizada utilizando a interface orientada a objetos. Ela mostra funções agrupadas por propósito, tornando a iniciação mais fácil. A seção de referência dá exemplos para ambas as variantes de sintaxe.

Não há diferenças significativas de desempenho entre as duas interfaces. Usuários podem basear suas escolhas em preferências pessoais.

Exemplo #2 Interface orientada a objeto e procedural

    <?php

    $mysqli = mysqli_connect("example.com", "user", "password", "database");

    $result = mysqli_query($mysqli, "SELECT 'Um mundo cheio de ' AS _msg FROM DUAL");
    $row = mysqli_fetch_assoc($result);
    echo $row['_msg'];

    $mysqli = new mysqli("example.com", "user", "password", "database");

    $result = $mysqli->query("SELECT 'escolhas para agradar a todos.' AS _msg FROM DUAL");
    $row = $result->fetch_assoc();
    echo $row['_msg'];

O exemplo acima produzirá:

    Um mundo cheio de escolhas para agradar a todos.

A interface orientada a objetos é usada neste guia porque a seção de referência está organizada dessa forma.

Misturando estilos

É possível trocar de estilos a qualquer momento. Misturar ambos os estilos não é recomendado por questões de clareza e estilo de código.

Exemplo #3 Estilo de código ruim

    <?php

    $mysqli = new mysqli("example.com", "user", "password", "database");

    $result = mysqli_query($mysqli, "SELECT 'Estilo possível, porém, ruim.' AS _msg FROM DUAL");

    if ($row = $result->fetch_assoc()) {
        echo $row['_msg'];
    }

O exemplo acima produzirá:

    Estilo possível, porém, ruim.

Veja também

- mysqli::__construct()
- mysqli::query()
- mysqli_result::fetch_assoc()
- $mysqli::connect_errno
- $mysqli::connect_error
- $mysqli::errno
- $mysqli::error
- Resumo das Funções da Extensão MySQLi

## Conexões

O servidor MySQL suporta o uso de diferentes camadas de transporte para conexões. Conexões usam TCP/IP, sockets de domínio Unix ou pipes nomeados do Windows.

O nome de servidor `localhost` tem um significado especial. Ele é vinculado ao uso de sockets de domínio Unix. Para abrir uma conexão TCP/IP ao servidor local, `127.0.0.1` deve ser usado ao invés do nome `localhost`.

Exemplo #1 Significado especial de localhost

    <?php

    $mysqli = new mysqli("localhost", "user", "password", "database");

    echo $mysqli->host_info . "\n";

    $mysqli = new mysqli("127.0.0.1", "user", "password", "database", 3306);

    echo $mysqli->host_info . "\n";

O exemplo acima produzirá:

    Localhost via UNIX socket
    127.0.0.1 via TCP/IP

Padrão dos parâmetros de conexão

Dependendo da função de conexão usada, alguns parâmetros podem ser omitidos. Se um parâmetro não for fornecido, a extensão tenta usar os valores padrões definidos no arquivo de configuração do PHP.

Exemplo #2 Padrões de configuração

    mysqli.default_host=192.168.2.27
    mysqli.default_user=root
    mysqli.default_pw=""
    mysqli.default_port=3306
    mysqli.default_socket=/tmp/mysql.sock

Os valores dos parâmetros resultantes são então passados à biblioteca cliente que é usada pela extensão. Se a biblioteca cliente detecta parâmetros vazios ou indefinidos, ela pode usar seus próprios valores padrão internos.

Padrões de conexão internos da biblioteca

Se o valor do servidor for indefinido ou vazio, a biblioteca cliente irá considerar uma conexão socket Unix em `localhost`. Se o socket for indefinido ou vazio, e uma conexão socket Unix for solicitada, é feita tentativa de conexão ao socket padrão em `/tmp/mysql.sock`.

Em sistemas Windows, o nome de servidor '`.`' é interpretado pela biblioteca cliente como uma tentativa de se abrir uma conexão baseada em pipe nomeado do Windows. Neste caso, o parâmetro socket é interpretado como o nome do pipe. Se não informado ou vazio, o socket (nome do pipe) será igual ao padrão `\\.\pipe\MySQL`.

Se a conexão a ser estabelecida não for baseada em socket de domínio Unix nem em pipe nomeado Windows, e o parâmetro da porta estiver indefinido, a biblioteca usará o valor padrão de porta `3306`.

A biblioteca mysqlnd e a Biblioteca Cliente MySQL (libmysqlclient) implementam a mesma lógica para determinar os padrões.

Opções de conexão

Opções de conexão estão disponíveis para, por exemplo, definir comando de inicialização que são executados na conexão, ou para requisitar uso de um conjunto de caracteres específico. Opções de conexão devem ser definidas antes que uma conexão seja estabelecida.

Para definir uma opção de conexão, a operação de conexão deve ser realizada em três passos: criar um manipulador de conexão com mysqli_init() ou mysqli::__construct(), definir as opções necessárias usando mysqli::options(), e estabelecer a conexão à rede com mysqli::real_connect().

Agrupamento de conexão

A extensão mysqli suporta conexões persistentes de banco de dados, que são um tipo especial de conexões agrupadas. Por padrão, cada conexão ao banco aberta por um script é explicitamente fechada pelo usuário durante a execução ou liberada automaticamente ao final do script. Com uma conexão permanente isso não acontece. Ao invés disso, ela é colocada em um grupo para reúso posterior, se uma conexão ao mesmo servidor, usando o mesmo usuário, senha, socket, porta e banco de dados padrão, for aberta. O reúso economiza tempo e reduz a sobrecarga de conexão.

Cada processo do PHP usa seu próprio agrupamento de conexões mysqli. Dependendo do modelo de implantação do servidor web, um processo PHP pode servir a uma ou múltiplas requisições. Portanto, uma conexão agrupada pode ser usada por um ou mais scripts subsequentemente.

Conexão persistente

Se uma conexão persistente sem uso para uma certa combinação de servidor, usuário, senha, socket, porta e banco padrão não puder ser encontrada no agrupamento, a extensão mysqli abre uma nova conexão. O uso de conexões persistentes pode ser habilitado e desabilitado usando a diretiva mysqli.allow_persistent do PHP. O número total de conexões abertas por um script pode ser limitado com mysqli.max_links. O número máximo de conexões persistentes por processo PHP pode ser restringido com mysqli.max_persistent. Favor observar que o servidor web pode gerar muitos processos PHP.

Uma queixa comum sobre conexões permanentes é que seus estados não são redefinidos antes do reúso. Por exemplo, transações abertas e não terminadas não são automaticamente desfeitas. Além disso, mudanças de autorização, que aconteceram no intervalo entre a inserção da conexão no agrupamento e seu reúso, não terão efeito. Isto pode ser visto como um efeito colateral indesejado. De outro modo, o nome `persistent`e pode ser entendido como uma promessa de que o estado da conexão irá persistir..

A extensão mysqli suporta ambas as interpretações de conexão persistente: persistência do estado, e redefinição do estado, antes do reúso. O padrão é redefinição. Antes que uma conexão persistente seja reutilizada, a extensão mysqli chama mysqli::change_user() implicitamente para redefinir o estado. A conexão persistente aparece ao usuário como se tivesse acabado de ser aberta. Nenhum artefato de usos anteriores é visível.

A chamada a mysqli::change_user() é uma operação custosa. Para melhor desempenho, usuários podem querer recompilar a extensão com a opção `MYSQLI_NO_CHANGE_USER_ON_PCONNECT` definida.

É deixado ao usuário a escolha entre comportamento seguro e melhor desempenho. Ambos são objetivos de otimização válidos. Para facilidade de uso, o comportamento seguro foi escolhido como padrão com o prejuízo do desempenho.

Veja também

- mysqli::__construct()
- mysqli_init()
- mysqli::options()
- mysqli::real_connect()
- mysqli::change_user()
- $mysqli::host_info
- Opções de Configuração MySQLi
- Conexões Persistentes de Banco de Dados

## Executando instruções

Instruções podem ser executadas com mysqli::query(), mysqli::real_query() e mysqli::multi_query(). A função mysqli::query() é a mais comum, e combina a instrução em execução com uma busca em buffer de seu conjunto de resultados, se houver, em uma chamada. Chamar mysqli::query() é idêntico a chamar mysqli::real_query() seguido de mysqli::store_result().

Exemplo #1 Executando consultas

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");

Conjunto de resultados com buffer

Depois da execução da instrução, os resultados podem ser recebidos de uma vez ou lidos linha a linha do servidor. O buffer do conjunto de resultados do lado do cliente permite ao servidor liberar recursos associados com os resultados da instrução da forma mais antecipada possível. Em geral, clientes são consumidores lentos dos resultados. Portanto, é recomendado usar conjuntos de resultados com buffer. mysqli::query() combina buffer de execução de instrução e de conjunto de resultados.

As aplicações PHP podem navegar livremente através de resultados em buffer. A navegação é rápida porque os conjuntos de resultados são mantidos na memória do cliente. Tenha em mente que muitas vezes é mais fácil escalar por cliente do que escalar por servidor.

Exemplo #2 Navegando através de resultados em buffer

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");
    $mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

    $result = $mysqli->query("SELECT id FROM test ORDER BY id ASC");

    echo "Ordem reversa...\n";
    for ($row_no = $result->num_rows - 1; $row_no >= 0; $row_no--) {
        $result->data_seek($row_no);
        $row = $result->fetch_assoc();
        echo " id = " . $row['id'] . "\n";
    }

    echo "Ordem do conjunto de resultados...\n";
    foreach ($result as $row) {
        echo " id = " . $row['id'] . "\n";
    }

O exemplo acima produzirá:

    Ordem reversa...
     id = 3
     id = 2
     id = 1
    Ordem do conjunto de resultados...
     id = 1
     id = 2
     id = 3

Conjuntos de resultado sem buffer

Se a memória do cliente é um recurso escasso e liberar recursos do servidor tão cedo quanto possível para manter a carga baixa não seja necessário, resultados sem buffer podem ser usados. Navegar por resultados sem buffer não é possível enquanto os dados não tenham sido completamente lidos.

Exemplo #3 Navegando através de resultados sem buffer

    <?php

    $mysqli->real_query("SELECT id FROM test ORDER BY id ASC");
    $result = $mysqli->use_result();

    echo "Ordem do conjunto de resultados...\n";
    foreach ($result as $row) {
        echo " id = " . $row['id'] . "\n";
    }

Tipos de dados dos valores do conjunto de resultados

As funções mysqli::query(), mysqli::real_query() e mysqli::multi_query() são usadas para executar instruções não preparadas. No nível do protocolo cliente-servidor do MySQL, o comando `COM_QUERY` e o protocolo de texto são usados para execução de instrução. Com o protocolo de texto, o servidor MySQL converte todos os dados de um resultado em strings antes do envio. Esta conversão é feita independente do tipo de dados da coluna do resultado SQL. As bibliotecas do cliente mysql recebem todos os valores de colunas como strings. Nenhuma conversão adicional do lado do cliente é feita para retornar as colunas a seus tipos nativos. Ao invés disso, todos os valores são fornecidos como strings PHP.

Exemplo #4 Protocolo de texto retorna strings por padrão

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label CHAR(1))");
    $mysqli->query("INSERT INTO test(id, label) VALUES (1, 'a')");

    $result = $mysqli->query("SELECT id, label FROM test WHERE id = 1");
    $row = $result->fetch_assoc();

    printf("id = %s (%s)\n", $row['id'], gettype($row['id']));
    printf("label = %s (%s)\n", $row['label'], gettype($row['label']));

O exemplo acima produzirá:

    id = 1 (string)
    label = a (string)

É possível converter colunas de inteiros e floats de volta para números PHP configurando a opção de conexão `MYSQLI_OPT_INT_AND_FLOAT_NATIVE`, se a biblioteca mysqlnd estiver sendo usada. Se configurada, a biblioteca mysqlnd irá verificar os tipos de coluna nos metadados do conjunto de resultados e converter colunas SQL para números PHP, se a faixa de valores do tipo de dado PHP permitir. Desta forma, por exemplo, colunas INT do SQL são retornadas como inteiros.

Exemplo #5 Tipos de dados nativos com mysqlnd e opção de conexão

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = new mysqli();
    $mysqli->options(MYSQLI_OPT_INT_AND_FLOAT_NATIVE, 1);
    $mysqli->real_connect("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label CHAR(1))");
    $mysqli->query("INSERT INTO test(id, label) VALUES (1, 'a')");

    $result = $mysqli->query("SELECT id, label FROM test WHERE id = 1");
    $row = $result->fetch_assoc();

    printf("id = %s (%s)\n", $row['id'], gettype($row['id']));
    printf("label = %s (%s)\n", $row['label'], gettype($row['label']));

O exemplo acima produzirá:

    id = 1 (integer)
    label = a (string)

Veja também

- mysqli::__construct()
- mysqli::options()
- mysqli::real_connect()
- mysqli::query()
- mysqli::multi_query()
- mysqli::use_result()
- mysqli::store_result()

## Instruções Preparadas

O banco de dados MySQL suporta instruções preparadas. Uma instrução preparada ou uma instrução parametrizada é usada para executar o mesmo comando repetidamente com alta eficiência e proteger contra injeções SQL.

Fluxo básico

A execução de uma instrução preparada consiste em dois estágios: preparação e execução. No estágio de preparação um modelo de instrução é enviado ao servidor de banco de dados. O servidor realiza uma verificação de sintaxe e inicializa os recursos internos para uso posterior.

O servidor MySQL suporta o uso de reservas de espaço posicionais anônimas com ponto de interrogação (`?`).

A preparação é seguida pela execução. Durante a execução o cliente vincula valores aos parâmetros e envia-os ao servidor. O servidor executa a instrução com os valores vinculados usando os recursos internos criados anteriormente.

Exemplo #1 Instrução preparada

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    /* Instrução não preparada */
    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label TEXT)");

    /* Instrução preparada, estágio 1: prepara */
    $stmt = $mysqli->prepare("INSERT INTO test(id, label) VALUES (?, ?)");

    /* Instrução preparada, estágio 2: vincula e executa */
    $id = 1;
    $label = 'PHP';
    $stmt->bind_param("is", $id, $label); // "is" significa que $id está vinculada como um inteiro e $label como uma string

    $stmt->execute();

Execução repetida

Uma instrução preparada pode ser executada repetidas vezes. Em cada execução o valor atual da variável vinculada é avaliado e enviado ao servidor. A instrução não é analisada novamente. O modelo de instrução não é mais transferido ao servidor.

Exemplo #2 INSERT preparado uma vez, executado múltiplas vezes

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    /* Instrução não preparada */
    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label TEXT)");

    /* Instrução preparada, estágio 1: prepara */
    $stmt = $mysqli->prepare("INSERT INTO test(id, label) VALUES (?, ?)");

    /* Instrução preparada, estágio 2: vincula e executa */
    $stmt->bind_param("is", $id, $label); // "is" significa que $id está vinculada como um inteiro e $label como uma string

    $data = [
        1 => 'PHP',
        2 => 'Java',
        3 => 'C++'
    ];
    foreach ($data as $id => $label) {
        $stmt->execute();
    }

    $result = $mysqli->query('SELECT id, label FROM test');
    var_dump($result->fetch_all(MYSQLI_ASSOC));

O exemplo acima produzirá:

    array(3) {
      [0]=>
      array(2) {
        ["id"]=>
        string(1) "1"
        ["label"]=>
        string(3) "PHP"
      }
      [1]=>
      array(2) {
        ["id"]=>
        string(1) "2"
        ["label"]=>
        string(4) "Java"
      }
      [2]=>
      array(2) {
        ["id"]=>
        string(1) "3"
        ["label"]=>
        string(3) "C++"
      }
    }

Cada instrução preparada ocupa recursos do servidor. Instruções devem ser fechadas explicitamente logo após o uso. Se não for fechada explicitamente, a instrução será fechada quando o manipulador da instrução for liberado pelo PHP.

Usar uma instrução preparada não é sempre a maneira mais eficiente de executar um comando. Uma instrução preparada executada apenas uma vez causa mais idas e voltas entre cliente e servidor do que uma não preparada. Este é o motivo pelo qual o `SELECT` não é executado como uma instrução preparada no exemplo acima.

Além disso, considere o uso da sintaxe SQL multi-INSERT do MySQL para inserção de dados. Para o exemplo, multi-INSERT requer menos idas e voltas entre o servidor e o cliente do que a instrução preparada mostrada acima.

Exemplo #3 Menos idas e voltas usando o multi-INSERT do SQL

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");

    $values = [1, 2, 3, 4];

    $stmt = $mysqli->prepare("INSERT INTO test(id) VALUES (?), (?), (?), (?)");
    $stmt->bind_param('iiii', ...$values);
    $stmt->execute();

Tipos de dados dos valores do conjunto de resultados

O Protocolo Cliente-Servidor do MySQL define um protocolo de transferência de dados diferente entre instruções preparadas e não preparadas. Instruções preparadas usam o chamado protocolo binário. O servidor MySQL envia os dados do conjunto de resultado como eles realmente são, em formato binário. Os resultados não são serializados em strings antes do envio. Bibliotecas cliente recebem os dados binários e tentam converter os valores para os tipos de dados apropriados do PHP. Por exemplo, resultados de uma coluna `INT` do SQL serão fornecidos como variáveis do tipo inteiro do PHP.

Exemplo #4 Tipos nativos de dados

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    /* Instrução não preparada */
    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label TEXT)");
    $mysqli->query("INSERT INTO test(id, label) VALUES (1, 'PHP')");

    $stmt = $mysqli->prepare("SELECT id, label FROM test WHERE id = 1");
    $stmt->execute();
    $result = $stmt->get_result();
    $row = $result->fetch_assoc();

    printf("id = %s (%s)\n", $row['id'], gettype($row['id']));
    printf("label = %s (%s)\n", $row['label'], gettype($row['label']));

O exemplo acima produzirá:

    id = 1 (integer)
    label = PHP (string)

Este comportamento difere das instruções não preparadas. Por padrão, instruções não preparadas retornam todos os resultados como strings. Este padrão pode ser alterado com o uso de uma opção de conexão. Se a opção de conexão for usada, não haverá diferenças.

Recebendo resultados usando variáveis vinculadas

Resultados de instruções preparadas podem ser recebidos por vinculação a variáveis de saída, ou por requisição de um objeto mysqli_result.

Variáveis de saída devem ser vinculadas depois da execução da instrução. Uma variável deve ser vinculada a cada coluna do conjunto de resultados da instrução.

Exemplo #5 Vinculação de variável de saída

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    /* Instrução não preparada */
    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label TEXT)");
    $mysqli->query("INSERT INTO test(id, label) VALUES (1, 'PHP')");

    $stmt = $mysqli->prepare("SELECT id, label FROM test WHERE id = 1");
    $stmt->execute();

    $stmt->bind_result($out_id, $out_label);

    while ($stmt->fetch()) {
        printf("id = %s (%s), label = %s (%s)\n", $out_id, gettype($out_id), $out_label, gettype($out_label));
    }

O exemplo acima produzirá:

    id = 1 (integer), label = PHP (string)

Instruções preparadas retornam conjuntos de resultados sem buffer por padrão. Os resultados da instrução não são implicitamente recebidos e transformados do servidor para o cliente para buffer do lado do cliente. O conjunto de resultados consome recursos do servidor até que todos os resultados tenham sido recebidos pelo cliente. Por isso é recomendado consumir os resultados em tempo hábil. Se um cliente falha em receber todos os resultados, ou fecha a instrução antes de ter recebido todos os resultados, os dados têm que ser recebidos implicitamente pela `mysqli`.

Também é possível fazer buffer dos resultados de uma instrução preparada usando mysqli_stmt::store_result().

Recebendo resultados usando a interface mysqli_result

Ao invés de usar resultados vinculados, eles podem também ser recebidos através da interface mysqli_result. mysqli_stmt::get_result() retorna um conjunto de resultados em buffer.

Exemplo #6 Usando mysqli_result para receber resultados

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    /* Instrução não preparada */
    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label TEXT)");
    $mysqli->query("INSERT INTO test(id, label) VALUES (1, 'PHP')");

    $stmt = $mysqli->prepare("SELECT id, label FROM test WHERE id = 1");
    $stmt->execute();

    $result = $stmt->get_result();

    var_dump($result->fetch_all(MYSQLI_ASSOC));

O exemplo acima produzirá:

    array(1) {
      [0]=>
      array(2) {
        ["id"]=>
        int(1)
        ["label"]=>
        string(3) "PHP"
      }
    }

Usar a interface mysqli_result oferece benefícios adicionais de flexibilidade de navegação pelos resultados no lado do cliente.

Exemplo #7 Conjunto de resultados com buffer para leitura flexível

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    /* Instrução não preparada */
    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label TEXT)");
    $mysqli->query("INSERT INTO test(id, label) VALUES (1, 'PHP'), (2, 'Java'), (3, 'C++')");

    $stmt = $mysqli->prepare("SELECT id, label FROM test");
    $stmt->execute();

    $result = $stmt->get_result();

    for ($row_no = $result->num_rows - 1; $row_no >= 0; $row_no--) {
        $result->data_seek($row_no);
        var_dump($result->fetch_assoc());
    }

O exemplo acima produzirá:

    array(2) {
      ["id"]=>
      int(3)
      ["label"]=>
      string(3) "C++"
    }
    array(2) {
      ["id"]=>
      int(2)
      ["label"]=>
      string(4) "Java"
    }
    array(2) {
      ["id"]=>
      int(1)
      ["label"]=>
      string(3) "PHP"
    }

Escape e injeção SQL

Variáveis vinculadas são enviadas ao servidor separadas da consulta e, portanto, não podem interferir nela. O servidor usa estes valores diretamente no ponto de execução, depois que o modelo de instrução é analisado. Parâmetros vinculados não precisam ser escapados já que nunca são substituídos na string da consulta diretamente. Uma dica deve ser fornecida ao servidor sobre o tipo da variável vinculada, para criar a conversão apropriada. Consulte a página da função mysqli_stmt::bind_param() para mais informações.

Tal separação algumas vezes é considerada como o único recurso de segurança para evitar injeção SQL, mas o mesmo grau de segurança pode ser conseguido com instruções não preparadas, se todos os valores forem formatados corretamente. Deve ser observado que a formatação correta não é o mesmo que escapar e envolve mais lógica que um simples escape. Sendo assim, instruções preparadas são simplesmente uma abordagem mais conveniente e com menos propensão a erros a este aspecto de segurança de banco de dados.

Emulação de instrução preparada no lado do cliente

A API não inclui emulação para instrução preparada no lado do cliente.

Veja também

- mysqli::__construct()
- mysqli::query()
- mysqli::prepare()
- mysqli_stmt::prepare()
- mysqli_stmt::execute()
- mysqli_stmt::bind_param()
- mysqli_stmt::bind_result()

## Procedimentos Armazenados

O banco de dados MySQL suporta procedimentos armazenados. Um procedimento armazenado é uma sub-rotina armazenada no catálogo do banco de dados. Aplicações podem chamar e executar o procedimento. A declaração `CALL` da linguagem SQL é usada para executar um procedimento armazenado.

Parâmetro

Procedimentos armazenados podem ter parâmetros `IN`, `INOUT` e `OUT`, dependendo da versão do MySQL. A interface mysqli não tem nenhuma ciência especial dos diferentes tipos de parâmetros.

Parâmetro IN

Parâmetros de entrada são providos pela declaração `CALL`. Certifique-se que os valores são corretamente escapados.

Exemplo #1 Chamando um procedimento armazenado

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");

    $mysqli->query("DROP PROCEDURE IF EXISTS p");
    $mysqli->query("CREATE PROCEDURE p(IN id_val INT) BEGIN INSERT INTO test(id) VALUES(id_val); END;");

    $mysqli->query("CALL p(1)");

    $result = $mysqli->query("SELECT id FROM test");

    var_dump($result->fetch_assoc());

O exemplo acima produzirá:

    array(1) {
      ["id"]=>
      string(1) "1"
    }

Parâmetros INOUT/OUT

Os valores dos parâmetros `INOUT`/`OUT` são acessados com o uso de variáveis de sessão.

Exemplo #2 Uso de variáveis de sessão

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP PROCEDURE IF EXISTS p");
    $mysqli->query('CREATE PROCEDURE p(OUT msg VARCHAR(50)) BEGIN SELECT "Hi!" INTO msg; END;');

    $mysqli->query("SET @msg = ''");
    $mysqli->query("CALL p(@msg)");

    $result = $mysqli->query("SELECT @msg as _p_out");

    $row = $result->fetch_assoc();
    echo $row['_p_out'];

O exemplo acima produzirá:

    Hi!

Desenvolvedores de aplicações e de frameworks podem ser capazes de fornecer uma API mais conveniente que use uma mistura de variáveis de sessão e inspeção de catálogos de banco de dados. Entretanto, deve ser observado o possível impacto em desempenho de uma solução customizada baseada em inspeção de catálogo.

Lidando com conjuntos de resultados

Procedimentos armazenados podem retornar conjuntos de resultados. Resultados retornados de um procedimento armazenado não podem ser recebidos corretamente usando mysqli::query(). A função mysqli::query() combina execução de instrução e recebimento do primeiro conjunto de dados em um conjunto de resultados com buffer, se houver. Porém, haverá conjuntos adicionais de resultados que estarão ocultos para o usuário, o que fará com que mysqli::query() falhe no retorno dos dados esperados.

Conjuntos de resultados retornados de um procedimento armazenado são recebidos usando-se mysqli::real_query() ou mysqli::multi_query(). Ambas as funções permitem receber qualquer número de conjuntos retornados pela instrução, como `CALL`. Falha no recebimento de todos os conjuntos retornados pelo procedimento armazenado causa um erro.

Exemplo #3 Recebendo resultados de procedimentos armazenados

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");
    $mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

    $mysqli->query("DROP PROCEDURE IF EXISTS p");
    $mysqli->query('CREATE PROCEDURE p() READS SQL DATA BEGIN SELECT id FROM test; SELECT id + 1 FROM test; END;');

    $mysqli->multi_query("CALL p()");

    do {
        if ($result = $mysqli->store_result()) {
            printf("---\n");
            var_dump($result->fetch_all());
            $result->free();
        }
    } while ($mysqli->next_result());

O exemplo acima produzirá:

    ---
    array(3) {
      [0]=>
      array(1) {
        [0]=>
        string(1) "1"
      }
      [1]=>
      array(1) {
        [0]=>
        string(1) "2"
      }
      [2]=>
      array(1) {
        [0]=>
        string(1) "3"
      }
    }
    ---
    array(3) {
      [0]=>
      array(1) {
        [0]=>
        string(1) "2"
      }
      [1]=>
      array(1) {
        [0]=>
        string(1) "3"
      }
      [2]=>
      array(1) {
        [0]=>
        string(1) "4"
      }
    }

Uso de procedimentos armazenados

Nenhuma manipulação especial é necessária ao usar a interface de procedimentos armazenados para receber resultados do mesmo procedimento como no exemplo acima. As interfaces para procedimentos armazenados e não armazenados são similares. Deve ser observado que pode haver versões do servidor MYSQL que não suportem preparação da instrução `CALL` da linguagem SQL.

Exemplo #4 Procedimentos Armazenados e Instruções Preparadas

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");
    $mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

    $mysqli->query("DROP PROCEDURE IF EXISTS p");
    $mysqli->query('CREATE PROCEDURE p() READS SQL DATA BEGIN SELECT id FROM test; SELECT id + 1 FROM test; END;');

    $stmt = $mysqli->prepare("CALL p()");

    $stmt->execute();

    do {
        if ($result = $stmt->get_result()) {
            printf("---\n");
            var_dump($result->fetch_all());
            $result->free();
        }
    } while ($stmt->next_result());

O exemplo acima produzirá:

    ---
    array(3) {
      [0]=>
      array(1) {
        [0]=>
        int(1)
      }
      [1]=>
      array(1) {
        [0]=>
        int(2)
      }
      [2]=>
      array(1) {
        [0]=>
        int(3)
      }
    }
    ---
    array(3) {
      [0]=>
      array(1) {
        [0]=>
        int(2)
      }
      [1]=>
      array(1) {
        [0]=>
        int(3)
      }
      [2]=>
      array(1) {
        [0]=>
        int(4)
      }
    }

Obviamente, o uso da API 'bind' para recebimento de dados também é suportado.

Exemplo #5 Procedimentos Armazenados e Instruções Preparadas usando a API bind

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");
    $mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

    $mysqli->query("DROP PROCEDURE IF EXISTS p");
    $mysqli->query('CREATE PROCEDURE p() READS SQL DATA BEGIN SELECT id FROM test; SELECT id + 1 FROM test; END;');

    $stmt = $mysqli->prepare("CALL p()");

    $stmt->execute();

    do {
        if ($stmt->store_result()) {
            $stmt->bind_result($id_out);
            while ($stmt->fetch()) {
                echo "id = $id_out\n";
            }
        }
    } while ($stmt->next_result());

O exemplo acima produzirá:

    id = 1
    id = 2
    id = 3
    id = 2
    id = 3
    id = 4

Veja também

- mysqli::query()
- mysqli::multi_query()
- mysqli::next_result()
- mysqli::more_results()

## Instruções Múltiplas

O MySQL opcionalmente permite múltiplas instruções em uma só string, mas isso requer uma manipulação especial.

Instruções ou consultas múltiplas devem ser executadas com mysqli::multi_query(). As instruções individuais da string são separadas por ponto-e-vírgula. Assim, todos os conjuntos de resultados retornados pelas instruções executadas precisam ser recebidas.

O servidor MySQL permite instruções que retornam dados e instruções que não retornam, em uma só instrução múltipla.

Exemplo #1 Instruções Múltiplas

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");

    $sql = "SELECT COUNT(*) AS _num FROM test;
            INSERT INTO test(id) VALUES (1);
            SELECT COUNT(*) AS _num FROM test; ";

    $mysqli->multi_query($sql);

    do {
        if ($result = $mysqli->store_result()) {
            var_dump($result->fetch_all(MYSQLI_ASSOC));
            $result->free();
        }
    } while ($mysqli->next_result());

O exemplo acima produzirá:

    array(1) {
      [0]=>
      array(1) {
        ["_num"]=>
        string(1) "0"
      }
    }
    array(1) {
      [0]=>
      array(1) {
        ["_num"]=>
        string(1) "1"
      }
    }

Considerações de Segurança

As funções da API mysqli::query() e mysqli::real_query() não definem uma opção de conexão necessária para ativar consultas múltiplas no servidor. Uma chamada extra da API é usada para instruções múltiplas para reduzir o estrago de ataques de injeção SQL acidentais. Um atacante pode tentar adicionar instruções como '`; DROP DATABASE mysql`' ou '`; SELECT SLEEP(999)`'. Se o atacante obtiver sucesso na adição de SQL ao string da instrução mas mysqli::multi_query() não for usada, o servidor não irá executar a instrução SQL maliciosa que foi injetada.

Exemplo #2 Injeção SQL

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");
    $result = $mysqli->query("SELECT 1; DROP TABLE mysql.user");
    ?>

O exemplo acima produzirá:

    PHP Fatal error:  Uncaught mysqli_sql_exception: You have an error in your SQL syntax;
    check the manual that corresponds to your MySQL server version for the right syntax to
    use near 'DROP TABLE mysql.user' at line 1

Instruções preparadas

O uso de instruções múltiplas com instruções preparadas não é suportado.

Veja também

- mysqli::query()
- mysqli::multi_query()
- mysqli::next_result()
- mysqli::more_results()

## Suporte da API para transações

O servidor MySQL suporta transações dependendo do tipo de motor de armazenamento usado. Desde o MySQL 5.5, InnoDB é o motor padrão de armazenamento. InnoDB tem suporte completo a transações ACID.

Transações podem ser controladas usando-se chamadas por SQL ou pela API. É recomentado usar as chamadas via API para habilitar e desabilitar o modo `autocommit` e para enviar ou desfazer transações.

Exemplo #1 Configurando o modo `autocommit` com SQL e através da API

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    /* Recomendado: usando API para controlar configurações de transações */
    $mysqli->autocommit(false);

    /* Não será monitorado ou reconhecido pela replicação ou pelo plugin de balanceamento de carga */
    $mysqli->query('SET AUTOCOMMIT = 0');

Pacotes de recursos opcionais, como plugins de replicação e de balanceamento de carga, podem facilmente monitorar chamadas da API. O plugin de replicação oferece balanceamento de carga com suporte a transação, se as transações forem controladas por chamadas da API. Balanceamento de carga com suporte a transação não estará disponível se instruções SQL forem usadas para configurar o modo `autocommit`, para enviar ou para desfazer transações.

Exemplo #2 Enviando e desfazendo transações

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");
    $mysqli->autocommit(false); //desliga o modo de envio automático

    $mysqli->query("INSERT INTO test(id) VALUES (1)");
    $mysqli->rollback(); //desfaz a inserção acima

    $mysqli->query("INSERT INTO test(id) VALUES (2)");
    $mysqli->commit(); //envia (confirma) a inserção acima

Observe que o servidor MySQL não consegue desfazer qualquer instrução. Algumas instruções causam um envio implícito.

Veja também

- mysqli::autocommit()
- mysqli::begin_transaction()
- mysqli::commit()
- mysqli::rollback()

## Metadados

Um conjunto de resultados MySQL contém metadados. Os metadados descrevem as colunas encontradas no resultado. Todos os metadados enviados pelo MySQL podem ser acessados através da interface `mysqli`. A extensão não altera, ou algumas vezes praticamente não altera, a informação que recebe. As diferenças entre as versões do servidor MySQL não estão alinhadas.

Metadados são acessados através da interface mysqli_result.

Exemplo #1 Acessando metadados do conjunto de resultados

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $result = $mysqli->query("SELECT 1 AS _one, 'Hello' AS _two FROM DUAL");
    var_dump($result->fetch_fields());

O exemplo acima produzirá:

    array(2) {
      [0]=>
      object(stdClass)#3 (13) {
        ["name"]=>
        string(4) "_one"
        ["orgname"]=>
        string(0) ""
        ["table"]=>
        string(0) ""
        ["orgtable"]=>
        string(0) ""
        ["def"]=>
        string(0) ""
        ["db"]=>
        string(0) ""
        ["catalog"]=>
        string(3) "def"
        ["max_length"]=>
        int(1)
        ["length"]=>
        int(1)
        ["charsetnr"]=>
        int(63)
        ["flags"]=>
        int(32897)
        ["type"]=>
        int(8)
        ["decimals"]=>
        int(0)
      }
      [1]=>
      object(stdClass)#4 (13) {
        ["name"]=>
        string(4) "_two"
        ["orgname"]=>
        string(0) ""
        ["table"]=>
        string(0) ""
        ["orgtable"]=>
        string(0) ""
        ["def"]=>
        string(0) ""
        ["db"]=>
        string(0) ""
        ["catalog"]=>
        string(3) "def"
        ["max_length"]=>
        int(5)
        ["length"]=>
        int(5)
        ["charsetnr"]=>
        int(8)
        ["flags"]=>
        int(1)
        ["type"]=>
        int(253)
        ["decimals"]=>
        int(31)
      }
    }

Instruções preparadas

Metadados de conjuntos de resultados criados por instruções preparadas são acessados da mesma forma. Um manipulador mysqli_result adequado é retornado pelo método mysqli_stmt::result_metadata().

Exemplo #2 Metadados de instruções preparadas

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $stmt = $mysqli->prepare("SELECT 1 AS _one, 'Hello' AS _two FROM DUAL");
    $stmt->execute();
    $result = $stmt->result_metadata();
    var_dump($result->fetch_fields());

Veja também

- mysqli::query()
- mysqli_result::fetch_fields()

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução

## Dependências

Para ter esta funções disponíveis, deve-se compilar o PHP com suporte para a extensão mysqli.

MySQL 8

Ao executar o PHP em versão anterior a 7.1.16, ou PHP 7.2 anterior a 7.2.4, defina o plugin padrão de senha do Servidor MySQL 8 para mysql_native_password ou surgirão erros parecidos com The server requested authentication method unknown to the client [caching_sha2_password] mesmo quando caching_sha2_password não for usado.

Isto acontece porque o padrão do MySQL 8 é caching_sha2_password, um plugin que não é reconhecido pelas versões anteriores do PHP (mysqlnd). Para resolver, altere para a configuração `default_authentication_plugin=mysql_native_password` no arquivo my.cnf. O plugin caching_sha2_password é totalmente suportado a partir do PHP 7.4.4. Para versões anteriores do PHP, a extensão mysql_xdevapi suporta o plugin.

## Instalação

A extensão `mysqli` foi introduzida com o PHP versão 5.0.0. O MySQL Native Driver foi incluído no PHP na versão 5.3.0.

## Instalação no Linux

As distribuições comuns do Unix incluem versões binárias do PHP que podem ser instaladas. Embora estas versões binárias sejam tipicamente construídas com suporte às extensões MySQL, as próprias bibliotecas das extensões podem precisar de pacote adicional para instalação. Verifique o gerenciador de pacote que vem com sua distribuição escolhida para disponibilidade.

Por exemplo, no Ubuntu o pacote `php5-mysql` instala as extensões do PHP ext/mysql, ext/mysqli e pdo_mysql. No CentOS, o pacote `php-mysql` também instala estas três extensões PHP.

Alternativamente, pode-se compilar esta extensão. Construir o PHP a partir do código-fonte permite que se especifique as extensões MySQL que se deseja usar, bem como pode-se escolher a biblioteca cliente para cada extensão.

O MySQL Native Driver é a opção de biblioteca cliente recomendada, pois resulta em melhor desempenho e dá acesso a recursos não disponíveis ao usar a Biblioteca Cliente MySQL. Consulte a página O que é o Driver Nativo do MySQL? para uma visão breve das vantagens do Driver Nativo MySQL.

`/path/to/mysql_config` representa a localização do programa `mysql_config` que vem com o Servidor MySQL.

Matriz de suporte ao mysqli em tempo de compilação
Versão do PHP | Padrão | Opções de Configuração: mysqlnd | Opções de Configuração: `libmysqlclient` | Registro de Alterações
--- | --- | --- | --- | ---
5.4.x e acima | mysqlnd | --with-mysqli | --with-mysqli=/path/to/mysql_config | mysqlnd é o padrão
5.3.x | libmysqlclient | --with-mysqli=mysqlnd | --with-mysqli=/path/to/mysql_config | mysqlnd é suportada
5.0.x, 5.1.x, 5.2.x | libmysqlclient | Não Disponível | --with-mysqli=/path/to/mysql_config | mysqlnd não é suportada

Observe que é possível misturar livremente extensões MySQL e bibliotecas cliente. Por exemplo, é possível habilitar a extensão MySQL para usar a biblioteca cliente MySQL (libmysqlclient), enquanto configura a extensão `mysqli` para usar o driver nativo MySQL. No entanto, todas as permutações de extensão e biblioteca cliente são possíveis.

## Instalação em Sistemas Windows

No Windows, a DLL php_mysqli.dll deve ser habilitada no php.ini.

Como em qualquer habilitação de extensão PHP (como php_mysqli.dll), a diretiva PHP extension_dir seve ser definida para o diretório onde as extensões do PHP estão localizadas. Consulte também as Instruções de Instalação Manual no Windows. Um exemplo de valor para `extension_dir` é c:\php\ext.

> Nota:

> Se ao iniciar o servidor web um erro parecido com este ocorrer: `"Unable to load dynamic library './php_mysqli.dll'"`, é porque php_mysqli.dll não pôde ser encontrada no sistema.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de configuração do MySQLi
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
mysqli.allow_local_infile | "0" | `INI_SYSTEM` | Antes do PHP 7.2.16 e 7.3.3 o padrão era "1".
mysqli.local_infile_directory |  | `INI_SYSTEM` | Disponível desde o PHP 8.1.0.
mysqli.allow_persistent | "1" | `INI_SYSTEM` |
mysqli.max_persistent | "-1" | `INI_SYSTEM` |
mysqli.max_links | "-1" | `INI_SYSTEM` |
mysqli.default_port | "3306" | `INI_ALL` |
mysqli.default_socket | NULL | `INI_ALL` |
mysqli.default_host | NULL | `INI_ALL` |
mysqli.default_user | NULL | `INI_ALL` |
mysqli.default_pw | NULL | `INI_ALL` |
mysqli.reconnect | "0" | `INI_SYSTEM` | Removido no PHP 8.2.0
mysqli.rollback_on_cached_plink | "0" | `INI_SYSTEM` |

Para maiores detalhes e definições das constantes INI_* acima, veja o capítulo sobre mudanças de configuração.

Aqui está uma breve explicação das diretivas de configuração.

`mysqli.allow_local_infile` bool

  Permite acessar, direto do PHP, arquivos locais com comandos LOAD DATA

`mysqli.local_infile_directory` string

  Permite restringir o carregamento de LOCAL DATA para arquivos localizados neste diretório.

`mysqli.allow_persistent` bool

  Habilita a possibilidade de criar conexões persistentes usando mysqli_connect().

`mysqli.max_persistent` int

  Número máximo de conexões simultâneas que podem ser estabelecidas. Definir como 0 para ilimitadas.

`mysqli.max_links` int

  O número máximo de conexões MySQL por processo.

`mysqli.default_port` int

  O número da porta TCP padrão para usar ao conectar ao servidor de banco de dados se não for especificada outra porta. Se não for especificado um padrão, então a porta será obtida da variável de ambiênte `MYSQL_TCP_PORT`, a entrada `mysql-tcp` em /etc/services ou a constante em tempo de compilação `MYSQL_PORT`, nesta ordem. Em Win32 será usada apenas a constante `MYSQL_PORT`.

`mysqli.default_socket` string

  O nome padrão do socket para usar ao conectar com um servidor de banco de dados local, se não for especificado outro nome de socket.

`mysqli.default_host` string

  O servidor padrão para usar ao conectar com o servidor de banco de dados se não for especificado um servidor. Não se aplica em

`mysqli.default_user` string

  O nome de usuário padrão para usar ao conectar com o servidor de banco de dados. Não se aplica em

`mysqli.default_pw` string

  A senha padrão para usar ao conectar ao servidor de banco de dados se não for especificado outra senha. Não se aplica em

`mysqli.reconnect` int

  Reconectar automaticamente ao perder a conexão.

  > Nota: Esta configuração do php.ini é ignorada pelo driver mysqlnd, e foi removida no PHP 8.2.0.

`mysqli.rollback_on_cached_plink` bool

  Se essa opção for ativada, o fechamento de uma conexão persistente fará o rollback de todas as transações pendentes dessa conexão antes que ela seja colocada de volta no pool de conexão persistente. Caso contrário, as transações pendentes serão revertidas apenas quando a conexão for reutilizada ou quando for realmente fechada.

Usuários não podem modificar `MYSQL_OPT_READ_TIMEOUT` via chamada de API ou configuração em tempo de execução. Note que se fosse possível haveria diferenças entre como a `libmysqlclient` e os fluxos iriam interpretar o valor de `MYSQL_OPT_READ_TIMEOUT`.

# A extensão mysqli e conexões persistentes

A ideia por trás das conexões persistentes é que uma conexão entre um processo cliente e um banco de dados pode ser reutilizada por um processo cliente, em vez de ser criada e destruída várias vezes. Isso reduz a sobrecarga de criar novas conexões sempre que uma é necessária, pois as conexões não utilizadas são armazenadas em cache e estão prontas para serem reutilizadas.

Ao contrário da extensão mysql, mysqli não fornece uma função separada para abrir conexões persistentes. Para abrir uma conexão persistente, você deve preceder `p:` ao nome do host ao conectar.

O problema com conexões persistentes é que elas podem ser deixadas em estados imprevisíveis pelos clientes. Por exemplo, um bloqueio de tabela pode ser ativado antes que um cliente seja encerrado inesperadamente. Um novo processo cliente reutilizando essa conexão persistente obterá a conexão como está. Qualquer limpeza precisaria ser feita pelo novo processo cliente antes que ele pudesse fazer bom uso da conexão ] persistente, aumentando a carga do programador.

A conexão persistente da extensão `mysqli`, no entanto, fornece código de manipulação de limpeza integrado. A limpeza realizada pelo `mysqli` inclui:

- Reverter transações ativas

- Fechar e descartar tabelas temporárias

- Desbloquear tabelas

- Redefinir variáveis de sessão

- Fechar declarações preparadas (sempre acontece com PHP)

- Fechar manipulador

- Liberar bloqueios adquiridos com GET_LOCK()

Isso garante que as conexões persistentes estejam em um estado limpo ao retornar do pool de conexões, antes que o processo do cliente as use.

A extensão `mysqli` faz essa limpeza chamando automaticamente a função C-API `mysql_change_user()`.

O recurso de limpeza automática tem vantagens e desvantagens. A vantagem é que o programador não precisa mais se preocupar em adicionar código de limpeza, pois ele é chamado automaticamente. No entanto, a desvantagem é que o código pode ser um pouco mais lento, pois o código para executar a limpeza precisa ser executado sempre que uma conexão é retornada do pool de conexões.

É possível desligar o código de limpeza automática, compilando o PHP com `MYSQLI_NO_CHANGE_USER_ON_PCONNECT` definido.

> Nota:

> A extensão `mysqli` suporta conexões persistentes ao usar MySQL Native Driver ou MySQL Client Library.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`MYSQLI_READ_DEFAULT_GROUP` (int)

  Lê opções do grupo nomeado em my.cnf ou no arquivo especificado com `MYSQLI_READ_DEFAULT_FILE`.

`MYSQLI_READ_DEFAULT_FILE` (int)

  Lê opções do arquivo de opções informado ao invés de my.cnf.

`MYSQLI_OPT_CAN_HANDLE_EXPIRED_PASSWORDS` (int)
  Indica ao servidor que o cliente consegue lidar com o modo "caixa de areia" para senhas expiradas. Pode ser usada com mysqli_options().
`MYSQLI_OPT_LOAD_DATA_LOCAL_DIR` (int)
  Se habilitada, esta opção especifica o diretório a partid do qual o carregamento de dados `LOCAL` no lado do cliente é permitido em instruções `LOAD DATA LOCAL`.
`MYSQLI_OPT_CONNECT_TIMEOUT` (int)

  Limite de tempo de conexão em segundos.

`MYSQLI_OPT_READ_TIMEOUT` (int)

  Limite de tempo do resultado da execução do comando, em segundos. Disponível a partir do PHP 7.2.0.

`MYSQLI_OPT_LOCAL_INFILE` (int)

  Habilita o comando `LOAD LOCAL INFILE`.

`MYSQLI_OPT_INT_AND_FLOAT_NATIVE` (int)

  Converte colunas de inteiros e floats de volta para números PHP. Válido apenas para mysqlnd.

`MYSQLI_OPT_NET_CMD_BUFFER_SIZE` (int)

  O tamanho do buffer interno de comando/rede. Válido apenas para mysqlnd.

`MYSQLI_OPT_NET_READ_BUFFER_SIZE` (int)

  Máximo tamanho de porção de leitura em bytes ao ler o corpo de um pacote de comando MySQL. Válido apenas para mysqlnd.

`MYSQLI_OPT_SSL_VERIFY_SERVER_CERT` (int)

`MYSQLI_INIT_COMMAND` (int)

  Comando a executar ao se conectar ao servidor MySQL. Será automaticamente re-executado na reconexão.

`MYSQLI_CLIENT_CAN_HANDLE_EXPIRED_PASSWORDS` (int)
  Indica ao servidor que o cliente consegue lidaro com o modo "caixa de areia" para senhas expiradas. Pode ser usada com mysqli_real_connect().
`MYSQLI_CLIENT_FOUND_ROWS` (int)
  Retorna o número de linhas correspondentes, e não o número de linhas afetadas.
`MYSQLI_CLIENT_SSL_VERIFY_SERVER_CERT` (int)
  Verifica o certificado do servidor.
`MYSQLI_CLIENT_SSL` (int)

  Usa SSL (protocolo criptografado). Esta opção não deve ser definida por aplicações; ela é definida internamente na biblioteca cliente MySQL.

`MYSQLI_CLIENT_COMPRESS` (int)

  Usa protocolo de compressão.

`MYSQLI_CLIENT_INTERACTIVE` (int)

  Permite `interactive_timeout` segundos (ao invés de `wait_timeout` segundos) de inatividade antes de fechar a conexão. A variável `wait_timeout` da sessão do cliente será definida para o valor da variável `interactive_timeout` da sessão.

`MYSQLI_CLIENT_IGNORE_SPACE` (int)

  Permite espaços depois de nomes de função. Considera todos os nomes de função como palavras reservadas.

`MYSQLI_CLIENT_NO_SCHEMA` (int)

  Não permite a sintaxe `db_name.tbl_name.col_name`.

`MYSQLI_CLIENT_MULTI_QUERIES`

  Permite múltiplas consultas separadas por ponto-e-vírgula em uma única chamada a mysqli_query().

`MYSQLI_STORE_RESULT` (int)

  Para uso em conjuntos de resultados com buffer. Tem o valor de `0`.

`MYSQLI_STORE_RESULT_COPY_DATA` (int)
  A partir do PHP 8.1, esta constante não tem mais efeito. Antes do PHP 8.1, esta constante é usada para copiar resultados do buffer interno do `mysqlnd` para as variáveis PHP buscadas. Por padrão, o `mysqlnd` usará uma lógica de referência para evitar de copiar e duplicar os resultados mantidos em memória. Para certos resultados, por exemplo para conjuntos com muitas linhas pequenas, o método de cópia pode reduzir o uso total de memória porque as variáveis do PHP que mantêm o resultado podem ser liberadas mais cedo. Disponível somente com `mysqlnd`. Descontinuada a partir do PHP 8.4.0.
`MYSQLI_USE_RESULT` (int)

  Para uso em conjuntos de resultados sem buffer. Tem o valor de `1`.

`MYSQLI_ASSOC` (int)

  Colunas são retornadas no array com os nomes dos campos nas chaves.

`MYSQLI_NUM` (int)

  Colunas são retornadas no array com índices enumerados.

`MYSQLI_BOTH` (int)

  Colunas são retornadas no array com índice tanto numérico quanto com nomes dos campos.

`MYSQLI_NOT_NULL_FLAG` (int)

  Indica que um campo é definido como `NOT NULL`.

`MYSQLI_PRI_KEY_FLAG` (int)

  O campo é parte de um índice primário.

`MYSQLI_UNIQUE_KEY_FLAG` (int)

  O campo é parte de um índice exclusivo.

`MYSQLI_MULTIPLE_KEY_FLAG` (int)

  O campo é parte de um índice.

`MYSQLI_BLOB_FLAG` (int)

  O campo é definido como `BLOB`.

`MYSQLI_UNSIGNED_FLAG` (int)

  O campo é definido como `UNSIGNED`.

`MYSQLI_ZEROFILL_FLAG` (int)

  O campo é definido como `ZEROFILL`.

`MYSQLI_AUTO_INCREMENT_FLAG` (int)

  O campo é definido como `AUTO_INCREMENT`.

`MYSQLI_TIMESTAMP_FLAG` (int)

  O campo é definido como `TIMESTAMP`.

`MYSQLI_SET_FLAG` (int)

  O campo é definido como `SET`.

`MYSQLI_NUM_FLAG` (int)

  O campo é definido como `NUMERIC`.

`MYSQLI_PART_KEY_FLAG` (int)

  O campo é parte de um multi-índice.

`MYSQLI_GROUP_FLAG` (int)

  O campo é parte de `GROUP BY`.

`MYSQLI_NO_DEFAULT_VALUE_FLAG` (int)
  Uma coluna não tem cláusula `DEFAULT` em sua definição. Isto não se aplica a colunas `NULL` ou `AUTO_INCREMENT` porque tais colunas têm um valor padrão de `NULL` e um valor padrão implícito, respectivamente.
`MYSQLI_TYPE_DECIMAL` (int)

  O campo é definido como `DECIMAL`.

`MYSQLI_TYPE_NEWDECIMAL` (int)

  Campo de precisão matemática `DECIMAL` ou `NUMERIC`.

`MYSQLI_TYPE_BIT` (int)

  O campo é definido como `BIT`.

`MYSQLI_TYPE_TINY` (int)

  O campo é definido como `TINYINT`.

`MYSQLI_TYPE_SHORT` (int)

  O campo é definido como `SMALLINT`.

`MYSQLI_TYPE_LONG` (int)

  O campo é definido como `INT`.

`MYSQLI_TYPE_FLOAT` (int)

  O campo é definido como `FLOAT`.

`MYSQLI_TYPE_DOUBLE` (int)

  O campo é definido como `DOUBLE`.

`MYSQLI_TYPE_NULL` (int)

  O campo é definido como `DEFAULT NULL`.

`MYSQLI_TYPE_TIMESTAMP` (int)

  O campo é definido como `TIMESTAMP`.

`MYSQLI_TYPE_LONGLONG` (int)

  O campo é definido como `BIGINT`.

`MYSQLI_TYPE_INT24` (int)

  O campo é definido como `MEDIUMINT`.

`MYSQLI_TYPE_DATE` (int)

  O campo é definido como `DATE`.

`MYSQLI_TYPE_TIME` (int)

  O campo é definido como `TIME`.

`MYSQLI_TYPE_DATETIME` (int)

  O campo é definido como `DATETIME`.

`MYSQLI_TYPE_YEAR` (int)

  O campo é definido como `YEAR`.

`MYSQLI_TYPE_NEWDATE` (int)

  O campo é definido como `DATE`.

`MYSQLI_TYPE_INTERVAL` (int)

  Sinônimo de `MYSQLI_TYPE_ENUM`. Removida a partir do PHP 8.4.0.

`MYSQLI_TYPE_ENUM` (int)

  O campo é definido como `ENUM`.

`MYSQLI_TYPE_SET` (int)

  O campo é definido como `SET`.

`MYSQLI_TYPE_TINY_BLOB` (int)

  O campo é definido como `TINYBLOB`.

`MYSQLI_TYPE_MEDIUM_BLOB` (int)

  O campo é definido como `MEDIUMBLOB`.

`MYSQLI_TYPE_LONG_BLOB` (int)

  O campo é definido como `LONGBLOB`.

`MYSQLI_TYPE_BLOB` (int)

  O campo é definido como `BLOB`.

`MYSQLI_TYPE_VAR_STRING` (int)

  O campo é definido como `VARCHAR`.

`MYSQLI_TYPE_STRING` (int)

  O campo é definido como `CHAR` ou `BINARY`.

`MYSQLI_TYPE_CHAR` (int)

  O campo é definido como `TINYINT`. Para `CHAR`, veja `MYSQLI_TYPE_STRING`.

`MYSQLI_TYPE_GEOMETRY` (int)

  O campo é definido como `GEOMETRY`

`MYSQLI_TYPE_JSON` (int)

  O campo é definido como `JSON`. Válido apenas para mysqlnd e MySQL 5.7.8 ou acima.

`MYSQLI_TYPE_VECTOR` (int)

  O campo é definido como `VECTOR`.

`MYSQLI_NEED_DATA`

  Há mais dados disponíveis para vincular a variáveis.

`MYSQLI_ENUM_FLAG` (int)

  O campo é definido como `ENUM`.

`MYSQLI_BINARY_FLAG` (int)

  O campo é definido como `BINARY`.

`MYSQLI_CURSOR_TYPE_FOR_UPDATE` (int)

  Removida a partir do PHP 8.4.0.

`MYSQLI_CURSOR_TYPE_NO_CURSOR` (int)

`MYSQLI_CURSOR_TYPE_READ_ONLY` (int)

`MYSQLI_CURSOR_TYPE_SCROLLABLE` (int)

  Removida a partir do PHP 8.4.0.

`MYSQLI_STMT_ATTR_CURSOR_TYPE` (int)

`MYSQLI_STMT_ATTR_PREFETCH_ROWS` (int)

  Removida a partir do PHP 8.4.0.

`MYSQLI_STMT_ATTR_UPDATE_MAX_LENGTH` (int)

`MYSQLI_SET_CHARSET_NAME` (int)

`MYSQLI_REPORT_INDEX` (int)

  Reporta se nenhum índice ou um índice ruim foi usado em uma consulta.

`MYSQLI_REPORT_ERROR` (int)

  Reporta erros de chamadas a funções mysqli.

`MYSQLI_REPORT_STRICT` (int)

  Lança uma exceção `mysqli_sql_exception` para erros ao invés de gerar alertas.

`MYSQLI_REPORT_ALL` (int)

  Define todas as opções ligadas (reportar tudo).

`MYSQLI_REPORT_OFF` (int)

  Desliga a reportagem de erros.

`MYSQLI_DEBUG_TRACE_ENABLED` (int)

  É definido para 1 se a funcionalidade mysqli_debug() estiver habilitada.

`MYSQLI_SERVER_PUBLIC_KEY` (int)

`MYSQLI_REFRESH_GRANT` (int)

  Atualiza a tabela de permissões. Descontinuada a partir do PHP 8.4.0.

`MYSQLI_REFRESH_LOG` (int)

  Descarrega os registros, como na execução da declaração SQL `FLUSH LOGS`. Descontinuada a partir do PHP 8.4.0.

`MYSQLI_REFRESH_TABLES` (int)

  Descarrega o cache de tabelas, como na execução da declaração SQL `FLUSH TABLES`. Descontinuada a partir do PHP 8.4.0.

`MYSQLI_REFRESH_HOSTS` (int)

  Descarrega o cache de servidores, como na execução da declaração SQL `FLUSH HOSTS`. Descontinuada a partir do PHP 8.4.0.

`MYSQLI_REFRESH_REPLICA` (int)

  Apelido da constante `MYSQLI_REFRESH_SLAVE`. Disponível a partir do PHP 8.1.0. Descontinuada a partir do PHP 8.4.0.

`MYSQLI_REFRESH_STATUS` (int)

  Redefine as variáveis de estado, como na execução da declaração SQL `FLUSH STATUS`. Descontinuada a partir do PHP 8.4.0.

`MYSQLI_REFRESH_THREADS` (int)

  Descarrega o cache de threads. Descontinuada a partir do PHP 8.4.0.

`MYSQLI_REFRESH_SLAVE` (int)

  Em um servidor de replicação escravo: redefine a informação do servidor principal, e reinicia o escravo. É como executar a declaração SQL `RESET SLAVE`. Descontinuada a partir do PHP 8.4.0.

`MYSQLI_REFRESH_MASTER` (int)

  Em um servidor de replicação principal: remove os arquivos de registro binários listados no índice de registro binário, e trunca o arquivo de índice. É como executar a declaração SQL `RESET MASTER`. Descontinuada a partir do PHP 8.4.0.

`MYSQLI_REFRESH_BACKUP_LOG` (int)
  Fecha e reabre os arquivos de registro reservas. Descontinuada a partir do PHP 8.4.0.
`MYSQLI_TRANS_COR_AND_CHAIN` (int)

  Adiciona "AND CHAIN" a mysqli_commit() ou mysqli_rollback().

`MYSQLI_TRANS_COR_AND_NO_CHAIN` (int)

  Adiciona "AND NO CHAIN" a mysqli_commit() ou mysqli_rollback().

`MYSQLI_TRANS_COR_RELEASE` (int)

  Adiciona "RELEASE" a mysqli_commit() ou mysqli_rollback().

`MYSQLI_TRANS_COR_NO_RELEASE` (int)

  Adiciona "NO RELEASE" a mysqli_commit() ou mysqli_rollback().

`MYSQLI_TRANS_START_READ_ONLY` (int)

  Inicia a transação como em "START TRANSACTION READ ONLY" com mysqli_begin_transaction().

`MYSQLI_TRANS_START_READ_WRITE` (int)

  Inicia a transação como em "START TRANSACTION READ WRITE" com mysqli_begin_transaction().

`MYSQLI_TRANS_START_WITH_CONSISTENT_SNAPSHOT` (int)

  Inicia a transação como em "START TRANSACTION WITH CONSISTENT SNAPSHOT".

`MYSQLI_CLIENT_SSL_DONT_VERIFY_SERVER_CERT` (int)

  Requer MySQL 5.6.5 e acima.

`MYSQLI_IS_MARIADB` (bool)

  Informa se a extensão mysqli foi construída com uma biblioteca cliente MariaDB. Disponível a partir do PHP 8.1.2.

`MYSQLI_ASYNC` (int)
  A consulta é realizada de forma assíncrona e nenhum resultado é retornado imediatamente. Disponível somente com `mysqlnd`.
`MYSQLI_ON_UPDATE_NOW_FLAG` (int)
  Se um campo for atualizado é obtido o valor do horário atual.

# Notas

Algumas notas de implementação:

1. Foi adicionado suporte para `MYSQL_TYPE_GEOMETRY` à extensão MySQLi no PHP 5.3.

2. Observe que existem diferentes implementações internas em `libmysqlclient` e `mysqlnd` para lidar com colunas do tipo `MYSQL_TYPE_GEOMETRY`. De um modo geral, o `mysqlnd` irá alocar significativamente menos memória. Por exemplo, se houver uma coluna `POINT` em um conjunto de resultados, `libmysqlclient` pode pré-alocar até 4 GB de RAM, embora sejam necessários menos de 50 bytes para manter uma coluna `POINT` na memória. A alocação de memória é muito menor, menos de 50 bytes, se estiver usando `mysqlnd`.

# Resumo da Função de Extensão do MySQLi

Resumo dos métodos mysqli
Classe mysqli
Interface POO | Interface Procedural | Apelido (não use) | Descrição
--- | --- | --- | ---
Propriedades
$mysqli::affected_rows | mysqli_affected_rows() | N/A | Obtém o número de linhas afetadas em uma operação MySQL anterior
$mysqli::client_info | mysqli_get_client_info() | N/A | Retorna a versão do cliente MySQL como uma string
$mysqli::client_version | mysqli_get_client_version() | N/A | Retorna as informações da versão do cliente MySQL como um número inteiro
$mysqli::connect_errno | mysqli_connect_errno() | N/A | Retorna o código de erro da última chamada de conexão
$mysqli::connect_error | mysqli_connect_error() | N/A | Retorna uma descrição de string do último erro de conexão
$mysqli::errno | mysqli_errno() | N/A | Retorna o código de erro da chamada de função mais recente
$mysqli::error | mysqli_error() | N/A | Retorna uma descrição de string do último erro
$mysqli::field_count | mysqli_field_count() | N/A | Retorna o número de colunas da consulta mais recente
$mysqli::host_info | mysqli_get_host_info() | N/A | Retorna uma string representando o tipo de conexão usada
$mysqli::protocol_version | mysqli_get_proto_info() | N/A | Retorna a versão do protocolo MySQL usado
$mysqli::server_info | mysqli_get_server_info() | N/A | Retorna a versão do servidor MySQL
$mysqli::server_version | mysqli_get_server_version() | N/A | Retorna a versão do servidor MySQL como um inteiro
$mysqli::info | mysqli_info() | N/A | Recupera informações sobre a consulta executada mais recentemente
$mysqli::insert_id | mysqli_insert_id() | N/A | Retorna o id gerado automaticamente usado na última consulta
$mysqli::sqlstate | mysqli_sqlstate() | N/A | Retorna o erro SQLSTATE da operação MySQL anterior
$mysqli::warning_count | mysqli_warning_count() | N/A | Retorna o número de avisos da última consulta para o link fornecido
Métodos
mysqli::autocommit() | mysqli_autocommit() | N/A | Ativa ou desativa modificações de banco de dados de confirmação automática
mysqli::change_user() | mysqli_change_user() | N/A | Altera o usuário da conexão de banco de dados especificada
mysqli::character_set_name() | mysqli_character_set_name() | N/A | Retorna o conjunto de caracteres padrão para a conexão do banco de dados
mysqli::close() | mysqli_close() | N/A | Fecha uma conexão de banco de dados aberta anteriormente
mysqli::commit() | mysqli_commit() | N/A | Confirma a transação atual
mysqli::__construct() | mysqli_connect() | N/A | Abra uma nova conexão com o servidor MySQL [Nota: método estático (ou seja, classe)]
mysqli::debug() | mysqli_debug() | N/A | Executa operações de depuração
mysqli::dump_debug_info() | mysqli_dump_debug_info() | N/A | Despejar informações de depuração no log
mysqli::get_charset() | mysqli_get_charset() | N/A | Retorna um objeto de conjunto de caracteres
mysqli::get_connection_stats() | mysqli_get_connection_stats() | N/A | Retorna estatísticas de conexão do cliente. Disponível apenas com o mysqlnd.
mysqli::get_client_info() | mysqli_get_client_info() | N/A | Retorna a versão do cliente MySQL como uma string
N/A | mysqli_get_client_stats() | N/A | Retorna as estatísticas do cliente por processo. Disponível apenas com o mysqlnd.
mysqli::get_server_info() | mysqli_get_server_info() | N/A | Retorna uma string representando a versão do servidor MySQL ao qual a extensão MySQLi está conectada
mysqli::get_warnings() | mysqli_get_warnings() | N/A | NÃO DOCUMENTADO
mysqli::init() | mysqli_init() | N/A | Inicializa o MySQLi e retorna um objeto para uso com mysqli_real_connect.
mysqli::kill() | mysqli_kill() | N/A | Pede ao servidor para matar um encadeamento do MySQL
mysqli::more_results() | mysqli_more_results() | N/A | Verifica se há mais resultados de consulta de uma consulta múltipla
mysqli::multi_query() | mysqli_multi_query() | N/A | Executa uma consulta no banco de dados
mysqli::next_result() | mysqli_next_result() | N/A | Prepara o próximo resultado da multi_query
mysqli::options() | mysqli_options() | mysqli_set_opt() | Define opções
mysqli::ping() | mysqli_ping() | N/A | Faz ping em uma conexão de servidor ou tenta reconectar se a conexão cair
mysqli::prepare() | mysqli_prepare() | N/A | Prepara uma instrução SQL para execução
mysqli::query() | mysqli_query() | N/A | Executa uma consulta no banco de dados
mysqli::real_connect() | mysqli_real_connect() | N/A | Abre uma conexão com um servidor mysql
mysqli::real_escape_string(), mysqli::escape_string() | mysqli_real_escape_string() | mysqli_escape_string() | Escapa caracteres especiais em uma string para uso em uma instrução SQL, levando em consideração o conjunto de caracteres atual da conexão
mysqli::real_query() | mysqli_real_query() | N/A | Executa uma consulta SQL
mysqli::refresh() | mysqli_refresh() | N/A | Libera tabelas ou caches ou redefine as informações do servidor de replicação
mysqli::rollback() | mysqli_rollback() | N/A | Reverte a transação atual
mysqli::select_db() | mysqli_select_db() | N/A | Seleciona o banco de dados padrão para consultas de banco de dados
mysqli::set_charset() | mysqli_set_charset() | N/A | Define o conjunto de caracteres do cliente padrão
mysqli::ssl_set() | mysqli_ssl_set() | N/A | Usado para estabelecer conexões seguras usando SSL
mysqli::stat() | mysqli_stat() | N/A | Obtém o status atual do sistema
mysqli::stmt_init() | mysqli_stmt_init() | N/A | Inicializa uma instrução e retorna um objeto para uso com mysqli_stmt_prepare
mysqli::store_result() | mysqli_store_result() | N/A | Transfere um conjunto de resultados da última consulta
mysqli::thread_id() | mysqli_thread_id() | N/A | Retorna o ID do thread para a conexão atual
mysqli::thread_safe() | mysqli_thread_safe() | N/A | Retorna se a segurança de thread é dada ou não
mysqli::use_result() | mysqli_use_result() | N/A | Inicia uma recuperação de conjunto de resultados

Resumo dos métodos mysqli_stmt
MySQL_STMT
Interface POO | Interface Procedural | Apelido (não use) | Descrição
--- | --- | --- | ---
Propriedades
$mysqli_stmt::affected_rows | mysqli_stmt_affected_rows() | N/A | Retorna o número total de linhas alteradas, excluídas ou inseridas pela última instrução executada
$mysqli_stmt::errno | mysqli_stmt_errno() | N/A | Retorna o código de erro para a chamada de instrução mais recente
$mysqli_stmt::error | mysqli_stmt_error() | N/A | Retorna uma descrição de string para o último erro de instrução
$mysqli_stmt::field_count | mysqli_stmt_field_count() | N/A | Retorna o número do campo na instrução fornecida - não documentado
$mysqli_stmt::insert_id | mysqli_stmt_insert_id() | N/A | Obtenha o ID gerado da operação INSERT anterior
$mysqli_stmt::num_rows | mysqli_stmt_num_rows() | N/A | Retorna o número de linhas no conjunto de resultados de instruções
$mysqli_stmt::param_count | mysqli_stmt_param_count() | N/A | Retorna o número do parâmetro para a instrução fornecida
$mysqli_stmt::sqlstate | mysqli_stmt_sqlstate() | N/A | Retorna o erro SQLSTATE da operação de instrução anterior
Métodos
mysqli_stmt::attr_get() | mysqli_stmt_attr_get() | N/A | Usado para obter o valor atual de um atributo de instrução
mysqli_stmt::attr_set() | mysqli_stmt_attr_set() | N/A | Usado para modificar o comportamento de uma instrução preparada
mysqli_stmt::bind_param() | mysqli_stmt_bind_param() | N/A | Vincula variáveis a uma instrução preparada como parâmetros
mysqli_stmt::bind_result() | mysqli_stmt_bind_result() | N/A | Vincula variáveis a uma instrução preparada para armazenamento de resultados
mysqli_stmt::close() | mysqli_stmt_close() | N/A | Fecha uma instrução preparada
mysqli_stmt::data_seek() | mysqli_stmt_data_seek() | N/A | Aponta para uma linha arbitrária no conjunto de resultados da instrução
mysqli_stmt::execute() | mysqli_stmt_execute() | mysqli_execute() | Executa uma consulta preparada
mysqli_stmt::fetch() | mysqli_stmt_fetch() | N/A | Busca resultados de uma instrução preparada nas variáveis vinculadas
mysqli_stmt::free_result() | mysqli_stmt_free_result() | N/A | Libera a memória de resultado armazenada para o identificador de instrução fornecido
mysqli_stmt::get_result() | mysqli_stmt_get_result() | N/A | Obtém um conjunto de resultados de uma instrução preparada. Disponível apenas com o mysqlnd.
mysqli_stmt::get_warnings() | mysqli_stmt_get_warnings() | N/A | NÃO DOCUMENTADO
mysqli_stmt::more_results() | mysqli_stmt_more_results() | N/A | Verifica se há mais resultados de consulta de uma consulta múltipla
mysqli_stmt::next_result() | mysqli_stmt_next_result() | N/A | Lê o próximo resultado de uma consulta múltipla
mysqli_stmt::num_rows() | mysqli_stmt_num_rows() | N/A | Veja também a propriedade $mysqli_stmt::num_rows
mysqli_stmt::prepare() | mysqli_stmt_prepare() | N/A | Prepara uma instrução SQL para execução
mysqli_stmt::reset() | mysqli_stmt_reset() | N/A | Redefine uma instrução preparada
mysqli_stmt::result_metadata() | mysqli_stmt_result_metadata() | N/A | Retorna os metadados do conjunto de resultados de uma instrução preparada
mysqli_stmt::send_long_data() | mysqli_stmt_send_long_data() | N/A | Envia dados em blocos
mysqli_stmt::store_result() | mysqli_stmt_store_result() | N/A | Transfere um conjunto de resultados de uma instrução preparada

Resumo dos métodos mysqli_result
mysqli_result
Interface POO | Interface Procedural | Apelido (não use) | Descrição
--- | --- | --- | ---
Propriedades
$mysqli_result::current_field | mysqli_field_tell() | N/A | Obtém o deslocamento de campo atual de um ponteiro de resultado
$mysqli_result::field_count | mysqli_num_fields() | N/A | Obtém o número de campos em um resultado
$mysqli_result::lengths | mysqli_fetch_lengths() | N/A | Retorna os comprimentos das colunas da linha atual no conjunto de resultados
$mysqli_result::num_rows | mysqli_num_rows() | N/A | Obtém o número de linhas em um resultado
Methods
mysqli_result::data_seek() | mysqli_data_seek() | N/A | Ajusta o ponteiro de resultado para uma linha arbitrária no resultado
mysqli_result::fetch_all() | mysqli_fetch_all() | N/A | Busca todas as linhas de resultado e retorna o conjunto de resultados como um array associativo, um array numérico ou ambos. Disponível apenas com o mysqlnd.
mysqli_result::fetch_array() | mysqli_fetch_array() | N/A | Busca uma linha de resultado como um array associativo, um array numérico ou ambos
mysqli_result::fetch_assoc() | mysqli_fetch_assoc() | N/A | Busca uma linha de resultado como um array associativo
mysqli_result::fetch_column() | mysqli_fetch_column() | N/A | Busca uma única coluna da próxima linha de um conjunto de resultados
mysqli_result::fetch_field_direct() | mysqli_fetch_field_direct() | N/A | Busca metadados para um único campo
mysqli_result::fetch_field() | mysqli_fetch_field() | N/A | Retorna o próximo campo no conjunto de resultados
mysqli_result::fetch_fields() | mysqli_fetch_fields() | N/A | Retorna um array de objetos que representam os campos em um conjunto de resultados
mysqli_result::fetch_object() | mysqli_fetch_object() | N/A | Retorna a linha atual de um conjunto de resultados como um objeto
mysqli_result::fetch_row() | mysqli_fetch_row() | N/A | Obtém uma linha de resultado como um array enumerado
mysqli_result::field_seek() | mysqli_field_seek() | N/A | Define ponteiro de resultado para um deslocamento de campo especificado
mysqli_result::free(), mysqli_result::close, mysqli_result::free_result | mysqli_free_result() | N/A | Libera a memória associada a um resultado

Resumo dos métodos mysqli_driver
MySQL_Driver
Interface POO | Interface Procedural | Apelido (não use) | Descrição
--- | --- | --- | ---
Propriedades
$mysqli_driver::mysqli_report | mysqli_report() | N/A | Define o modo de relatório de erros do mysqli
Métodos
mysqli_driver::embedded_server_end() | mysqli_embedded_server_end() | N/A | NÃO DOCUMENTADO
mysqli_driver::embedded_server_start() | mysqli_embedded_server_start() | N/A | NÃO DOCUMENTADO

> Nota:

> As funções apelido são fornecidas apenas para fins de compatibilidade com versões anteriores. Não os use em novos projetos.

# A classe mysqli

(PHP 5, PHP 7, PHP 8)

## Introdução

Representa uma conexão entre o PHP e um banco de dados MySQL.

## Resumo da classe

class mysqli {
/* Propriedades */
public readonly int|string $affected_rows;
public readonly string $client_info;
public readonly int $client_version;
public readonly int $connect_errno;
public readonly ?string $connect_error;
public readonly int $errno;
public readonly string $error;
public readonly array $error_list;
public readonly int $field_count;
public readonly string $host_info;
public readonly ?string $info;
public readonly int|string $insert_id;
public readonly string $server_info;
public readonly int $server_version;
public readonly string $sqlstate;
public readonly int $protocol_version;
public readonly int $thread_id;
public readonly int $warning_count;
/* Métodos */
public function __construct(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
)
public function autocommit(bool `$enable`): bool
public function begin_transaction(int `$flags` = 0, ?string `$name` = `null`): bool
public function change_user(string `$username`, #[\SensitiveParameter]string `$password`, ?string `$database`): bool
public function character_set_name(): string
public function close(): true
public function commit(int `$flags` = 0, ?string `$name` = `null`): bool
public function connect(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
): bool
public function debug(string `$options`): true
public function dump_debug_info(): bool
public function execute_query(string `$query`, ?array `$params` = `null`): mysqli_result|bool
public function get_charset(): ?object
#[\Deprecated]
public function get_client_info(): string
public function get_connection_stats(): array
public function get_server_info(): string
public function get_warnings(): mysqli_warning|false
#[\Deprecated]
public function init(): ?bool
#[\Deprecated]
public function kill(int `$process_id`): bool
public function more_results(): bool
public function multi_query(string `$query`): bool
public function next_result(): bool
public function options(int `$option`, string|int `$value`): bool
#[\Deprecated]
public function ping(): bool
public static function poll(
?array `&$read`,
?array `&$error`,
array `&$reject`,
int `$seconds`,
int `$microseconds` = 0
): int|false
public function prepare(string `$query`): mysqli_stmt|false
public function query(string `$query`, int `$result_mode` = MYSQLI_STORE_RESULT): mysqli_result|bool
public function real_connect(
?string `$hostname` = null,
?string `$username` = null,
#[\SensitiveParameter]?string `$password` = null,
?string `$database` = null,
?int `$port` = null,
?string `$socket` = null,
int `$flags` = 0
): bool
public function real_escape_string(string `$string`): string
public function real_query(string `$query`): bool
public function reap_async_query(): mysqli_result|bool
#[\Deprecated]
public function refresh(int `$flags`): bool
public function release_savepoint(string `$name`): bool
public function rollback(int `$flags` = 0, ?string `$name` = null): bool
public function savepoint(string `$name`): bool
public function select_db(string `$database`): bool
public function set_charset(string `$charset`): bool
public function ssl_set(
?string `$key`,
?string `$certificate`,
?string `$ca_certificate`,
?string `$ca_path`,
?string `$cipher_algos`
): true
public function stat(): string|false
public function stmt_init(): mysqli_stmt|false
public function store_result(int `$mode` = 0): mysqli_result|false
public function thread_safe(): bool
public function use_result(): mysqli_result|false
}

# mysqli::$affected_rows

# mysqli_affected_rows

(PHP 5, PHP 7, PHP 8)

mysqli::$affected_rows -- mysqli_affected_rows — Retorna o número de linhas afetadas pela operação MySQL anterior

### Descrição

Estilo orientado a objetos

int|string $mysqli->affected_rows;

Estilo procedural

function mysqli_affected_rows(mysqli `$mysql`): int|string

Retorna o número de linhas afetadas pelo último comando `INSERT`, `UPDATE`, `REPLACE` ou `DELETE`. Funciona como mysqli_num_rows() para consultas `SELECT`.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()

### Valor Retornado

Um inteiro maior do que zero indica o número de linhas afetadas ou obtidas. Zero indica que nenhum registro foi atualizado por uma declaração `UPDATE`, nenhuma linha correspondeu à claúsula `WHERE` na consulta ou que nenhuma consulta foi executada ainda. `-1` indica que a consulta retornou um erro ou que mysqli_affected_rows() foi chamada para uma consulta `SELECT` sem buffer.

> Nota:

> Se o número de linhas afetadas for maior do que o maior valor inteiro (`PHP_INT_MAX`), o número de linhas afetadas será retornado como uma string.

### Exemplos

Exemplo #1 Exemplo de $mysqli->affected_rows

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Insert rows */
    $mysqli->query("CREATE TABLE Language SELECT * from CountryLanguage");
    printf("Affected rows (INSERT): %d\n", $mysqli->affected_rows);

    $mysqli->query("ALTER TABLE Language ADD Status int default 0");

    /* update rows */
    $mysqli->query("UPDATE Language SET Status=1 WHERE Percentage > 50");
    printf("Affected rows (UPDATE): %d\n", $mysqli->affected_rows);

    /* delete rows */
    $mysqli->query("DELETE FROM Language WHERE Percentage < 50");
    printf("Affected rows (DELETE): %d\n", $mysqli->affected_rows);

    /* select all rows */
    $result = $mysqli->query("SELECT CountryCode FROM Language");
    printf("Affected rows (SELECT): %d\n", $mysqli->affected_rows);

    /* Delete table Language */
    $mysqli->query("DROP TABLE Language");

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Insert rows */
    mysqli_query($link, "CREATE TABLE Language SELECT * from CountryLanguage");
    printf("Affected rows (INSERT): %d\n", mysqli_affected_rows($link));

    mysqli_query($link, "ALTER TABLE Language ADD Status int default 0");

    /* update rows */
    mysqli_query($link, "UPDATE Language SET Status=1 WHERE Percentage > 50");
    printf("Affected rows (UPDATE): %d\n", mysqli_affected_rows($link));

    /* delete rows */
    mysqli_query($link, "DELETE FROM Language WHERE Percentage < 50");
    printf("Affected rows (DELETE): %d\n", mysqli_affected_rows($link));

    /* select all rows */
    $result = mysqli_query($link, "SELECT CountryCode FROM Language");
    printf("Affected rows (SELECT): %d\n", mysqli_affected_rows($link));

    /* Delete table Language */
    mysqli_query($link, "DROP TABLE Language");

Os exemplos acima produzirão:

    Affected rows (INSERT): 984
    Affected rows (UPDATE): 168
    Affected rows (DELETE): 815
    Affected rows (SELECT): 169

### Veja Também

- mysqli_num_rows() - Obtém o número de linhas no resultado
- mysqli_info() - Recupera informação sobre a recente consulta executada

# mysqli::autocommit

# mysqli_autocommit

(PHP 5, PHP 7, PHP 8)

mysqli::autocommit -- mysqli_autocommit — Ativa ou desativa a gravação automática das modificações no banco de dados

### Descrição

Estilo orientado a objetos

public function mysqli::autocommit(bool `$enable`): bool

Estilo procedural

function mysqli_autocommit(mysqli `$mysql`, bool `$enable`): bool

Ativa ou desativa o modo de gravação automática nas consultas para a conexão do banco de dados.

Para determinar o estado atual da gravação automática use o comando SQL `SELECT @@autocommit`.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()
`enable`

  Habilitar ou não a gravação automática.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Exemplos

Exemplo #1 Exemplo de mysqli::autocommit()

Estilo orientado a objetos

    <?php

    /* Solicita ao mysqli que dispare uma exceção se um erro ocorrer */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* O motor da tabela tem que suportar transações */
    $mysqli->query("CREATE TABLE IF NOT EXISTS language (
        Code text NOT NULL,
        Speakers int(11) NOT NULL
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");

    /* Desliga a gravação automática */
    $mysqli->autocommit(false);

    $result = $mysqli->query("SELECT @@autocommit");
    $row = $result->fetch_row();
    printf("Gravação automática = %s\n", $row[0]);

    try {
        /* Prepara a declaração de inserção */
        $stmt = $mysqli->prepare('INSERT INTO language(Code, Speakers) VALUES (?,?)');
        $stmt->bind_param('ss', $language_code, $native_speakers);

        /* Insere alguns valores */
        $language_code = 'DE';
        $native_speakers = 50_123_456;
        $stmt->execute();
        $language_code = 'FR';
        $native_speakers = 40_546_321;
        $stmt->execute();

        /* Grava os dados no banco. Isto não liga a gravação automática */
        $mysqli->commit();
        print "2 linhas gravadas no banco de dados\n";

        $result = $mysqli->query("SELECT @@autocommit");
        $row = $result->fetch_row();
        printf("Gravação automática = %s\n", $row[0]);

        /* Tenta inserir mais valores */
        $language_code = 'PL';
        $native_speakers = 30_555_444;
        $stmt->execute();
        $language_code = 'DK';
        $native_speakers = 5_222_444;
        $stmt->execute();

        /* Ligar a gravação automática irá disparar uma gravação */
        $mysqli->autocommit(true);

        print "2 linhas gravadas no banco de dados\n";
    } catch (mysqli_sql_exception $exception) {
        $mysqli->rollback();

        throw $exception;
    }

Estilo procedural

    <?php

    /* Solicita ao mysqli que dispare uma exceção se um erro ocorrer */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* O motor da tabela tem que suportar transações */
    mysqli_query($mysqli, "CREATE TABLE IF NOT EXISTS language (
        Code text NOT NULL,
        Speakers int(11) NOT NULL
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");

    /* Desliga a gravação automática */
    mysqli_autocommit($mysqli, false);

    $result = mysqli_query($mysqli, "SELECT @@autocommit");
    $row = mysqli_fetch_row($result);
    printf("Gravação automática = %s\n", $row[0]);

    try {
        /* Prepara a declaração de inserção */
        $stmt = mysqli_prepare($mysqli, 'INSERT INTO language(Code, Speakers) VALUES (?,?)');
        mysqli_stmt_bind_param($stmt, 'ss', $language_code, $native_speakers);

        /* Insere alguns valores */
        $language_code = 'DE';
        $native_speakers = 50_123_456;
        mysqli_stmt_execute($stmt);
        $language_code = 'FR';
        $native_speakers = 40_546_321;
        mysqli_stmt_execute($stmt);

        /* Grava os dados no banco. Isto não liga a gravação automática */
        mysqli_commit($mysqli);
        print "2 linhas gravadas no banco de dados\n";

        $result = mysqli_query($mysqli, "SELECT @@autocommit");
        $row = mysqli_fetch_row($result);
        printf("Gravação automática = %s\n", $row[0]);

        /* Tenta inserir mais valores */
        $language_code = 'PL';
        $native_speakers = 30_555_444;
        mysqli_stmt_execute($stmt);
        $language_code = 'DK';
        $native_speakers = 5_222_444;
        mysqli_stmt_execute($stmt);

        /* Ligar a gravação automática irá disparar uma gravação */
        mysqli_autocommit($mysqli, true);

        print "2 linhas gravadas no banco de dados\n";
    } catch (mysqli_sql_exception $exception) {
        mysqli_rollback($mysqli);

        throw $exception;
    }

Os exemplos acima produzirão:

    Gravação automática = 0
    2 linhas gravadas no banco de dados
    Gravação automática = 0
    2 linhas gravadas no banco de dados
    Gravação automática = 0
    2 linhas gravadas no banco de dados
    Gravação automática = 0
    2 linhas gravadas no banco de dados

### Notas

> Nota:

> Esta função não funciona com tipos de tabelas não transacionais (como MyISAM ou ISAM).

### Veja Também

- mysqli_begin_transaction() - Inicia uma transação
- mysqli_commit() - Grava a transação atual
- mysqli_rollback() - Reverte a transação atual

# mysqli::begin_transaction

# mysqli_begin_transaction

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

mysqli::begin_transaction -- mysqli_begin_transaction — Inicia uma transação

### Descrição

Estilo orientado a objetos

public function mysqli::begin_transaction(int `$flags` = 0, ?string `$name` = `null`): bool

Estilo procedural:

function mysqli_begin_transaction(mysqli `$mysql`, int `$flags` = 0, ?string `$name` = `null`): bool

Inicia uma transação. Requer o mecanismo InnoDB (é ativado por padrão). Para detalhes adicionais sobre como as transações do MySQL funcionam, consulte » http://dev.mysql.com/doc/mysql/en/commit.html.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()
`flags`

  As flags válidas são:

  - `MYSQLI_TRANS_START_READ_ONLY`: Inicia a transação como "START TRANSACTION READ ONLY". Requer MySQL 5.6 e superior.

  - `MYSQLI_TRANS_START_READ_WRITE`: Inicia a transação como "START TRANSACTION READ WRITE". Requer MySQL 5.6 e superior.

  - `MYSQLI_TRANS_START_WITH_CONSISTENT_SNAPSHOT`: Inicia a transação como "START TRANSACTION WITH CONSISTENT SNAPSHOT".

`name`

  Nome do ponto de salvamento para a transação.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `name` agora é anulável.

### Exemplos

Exemplo #1 Exemplo de mysqli::begin_transaction()

Estilo orientado a objetos

    <?php

    /* Diga ao mysqli para lançar uma exceção se ocorrer um erro */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* O mecanismo de tabela deve suportar transações */
    $mysqli->query("CREATE TABLE IF NOT EXISTS language (
        Code text NOT NULL,
        Speakers int(11) NOT NULL
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");

    /* Inicia transação */
    $mysqli->begin_transaction();

    try {
        /* Insira alguns valores */
        $mysqli->query("INSERT INTO language(Code, Speakers) VALUES ('DE', 42000123)");

        /* Tente inserir valores inválidos */
        $language_code = 'FR';
        $native_speakers = 'Unknown';
        $stmt = $mysqli->prepare('INSERT INTO language(Code, Speakers) VALUES (?,?)');
        $stmt->bind_param('ss', $language_code, $native_speakers);
        $stmt->execute();

        /* Se o código atingir esse ponto sem erros, confirme os dados no banco de dados */
        $mysqli->commit();
    } catch (mysqli_sql_exception $exception) {
        $mysqli->rollback();

        throw $exception;
    }

Estilo procedural

    <?php

    /* Diga ao mysqli para lançar uma exceção se ocorrer um erro */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* O mecanismo de tabela deve suportar transações */
    mysqli_query($mysqli, "CREATE TABLE IF NOT EXISTS language (
        Code text NOT NULL,
        Speakers int(11) NOT NULL
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");

    /* Inicia transação */
    mysqli_begin_transaction($mysqli);

    try {
        /* Insira alguns valores */
        mysqli_query($mysqli, "INSERT INTO language(Code, Speakers) VALUES ('DE', 42000123)");

        /* Tente inserir valores inválidos */
        $language_code = 'FR';
        $native_speakers = 'Unknown';
        $stmt = mysqli_prepare($mysqli, 'INSERT INTO language(Code, Speakers) VALUES (?,?)');
        mysqli_stmt_bind_param($stmt, 'ss', $language_code, $native_speakers);
        mysqli_stmt_execute($stmt);

        /* Se o código atingir esse ponto sem erros, confirme os dados no banco de dados */
        mysqli_commit($mysqli);
    } catch (mysqli_sql_exception $exception) {
        mysqli_rollback($mysqli);

        throw $exception;
    }

### Notas

> Nota:

> Esta função não funciona com tipos de tabelas não transacionais (como MyISAM ou ISAM).

### Veja Também

- mysqli_autocommit() - Ativa ou desativa a gravação automática das modificações no banco de dados
- mysqli_commit() - Grava a transação atual
- mysqli_rollback() - Reverte a transação atual

# mysqli::change_user

# mysqli_change_user

(PHP 5, PHP 7, PHP 8)

mysqli::change_user -- mysqli_change_user — Altera o usuário da conexão com o banco de dados

### Descrição

Estilo orientado a objetos

public function mysqli::change_user(string `$username`, #[\SensitiveParameter]string `$password`, ?string `$database`): bool

Estilo procedural

function mysqli_change_user(
mysqli `$mysql`,
string `$username`,
#[\SensitiveParameter]string `$password`,
?string `$database`
): bool

Tenta conexão ao banco de dados especificado usando as credenciais fornecidas.

Em comparação ao método mysqli::connect(), este método não não fechará a conexão atual se a nova conexão não puder ser aberta.

Para conseguir mudar usuários com sucesso, os parâmetors `username` e `password` fornecidos devem ser válidos e este usuário deve ter permissões suficientes para acessar o banco de dados desejado. Se por qualquer motivo a autorização falhar, a autenticação do usuário atual irá permanecer.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()
`username`

  O nome do usuário MySQL.

`password`

  A senha MySQL.

`database`

  O nome do banco de dados. Se `null` ou uma string vazia forem passados, a conexão ao servidor será aberta sem banco de dados padrão.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Exemplos

Exemplo #1 Redefinindo a sessão da conexão

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "meu_usuario", "minha_senha", "teste");

    $mysqli->query("SET @a:=1");

    $mysqli->change_user("meu_usuario", "minha_senha", "mundo");

    $result = $mysqli->query("SELECT DATABASE()");
    $row = $result->fetch_row();
    printf("Banco de dados padrão: %s\n", $row[0]);

    $result = $mysqli->query("SELECT @a");
    $row = $result->fetch_row();
    if ($row[0] === null) {
        printf("Valor da variável 'a' é NULL\n");
    }

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "meu_usuario", "minha_senha", "teste");

    mysqli_query($link, "SET @a:=1");

    mysqli_change_user($link, "meu_usuario", "minha_senha", "mundo");

    $result = mysqli_query($link, "SELECT DATABASE()");
    $row = mysqli_fetch_row($result);
    printf("Banco de dados padrão: %s\n", $row[0]);

    $result = mysqli_query($link, "SELECT @a");
    $row = mysqli_fetch_row($result);
    if ($row[0] === null) {
        printf("Valor da variável 'a' é NULL\n");
    }

Os exemplos acima produzirão:

    Banco de dados padrão: mundo
    Valor da variável 'a' é NULL

Exemplo #2 Se `database` for `null` a conexão é aberta sem selecionar nenhum banco de dados padrão

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "meu_usuario", "minha_senha", "teste");

    $mysqli->change_user("meu_usuario", "minha_senha", null);

    $result = $mysqli->query("SELECT DATABASE()");
    $row = $result->fetch_row();
    printf("Banco de dados padrão: %s\n", $row[0]);

Os exemplos acima produzirão:

    Banco de dados padrão:

### Notas

> Nota:

> Usar este comando sempre irá fazer com que a conexão atual se comporte como se fosse uma conexão totalmente nova, não importando se a operação foi completada com sucesso. Esta reinicialização inclui realizar uma reversão de dados em quaisquer transações ativas, fechando todas as tabelas temporárias e destravando todas as tabelas travadas.

### Veja Também

- mysqli_connect() - Sinônimo de mysqli::__construct
- mysqli_select_db() - Seleciona o banco de dados padrão para consultas de banco de dados

# mysqli::character_set_name

# mysqli_character_set_name

(PHP 5, PHP 7, PHP 8)

mysqli::character_set_name -- mysqli_character_set_name — Retorna o conjunto de caracteres atual da conexão com o banco de dados

### Descrição

Estilo orientado a objetos

public function mysqli::character_set_name(): string

Estilo procedural

function mysqli_character_set_name(mysqli `$mysql`): string

Retorna o conjunto de caracteres atual da conexão com o banco de dados.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()

### Valor Retornado

O conjunto de caracteres atual da conexão

### Exemplos

Exemplo #1 Exemplo de mysqli::character_set_name()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "meu_usuario", "minha_senha", "mundo");

    /* Define o conjunto padrão de caracteres */
    $mysqli->set_charset('utf8mb4');

    /* Mostra o conjunto atual de caracteres */
    $charset = $mysqli->character_set_name();
    printf("Conjunto atual de caracteres é %s\n", $charset);

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "meu_usuario", "minha_senha", "mundo");

    /* Define o conjunto padrão de caracteres */
    mysqli_set_charset($mysqli, 'utf8mb4');

    /* Mostra o conjunto atual de caracteres */
    $charset = mysqli_character_set_name($mysqli);
    printf("Conjunto atual de caracteres é %s\n", $charset);

Os exemplos acima produzirão:

    Conjunto atual de caracteres é utf8mb4

### Veja Também

- mysqli_set_charset() - Define o conjunto de caracteres do cliente
- mysqli_real_escape_string() - Escape caracteres especiais em uma string para uso em uma instrução SQL, levando em consideração o conjunto de caracteres atual da conexão

# mysqli::close

# mysqli_close

(PHP 5, PHP 7, PHP 8)

mysqli::close -- mysqli_close — Fecha uma conexão ao banco de dados previamente aberta

### Descrição

Estilo orientado a objetos

public function mysqli::close(): true

Estilo procedural

function mysqli_close(mysqli `$mysql`): true

Fecha uma conexão ao banco de dados previamente aberta.

Conexões MySQL não persistentes e conjuntos de resultados são automaticamente fechados quando seus objetos são destruídos. Fechar as conexões e liberar os conjuntos de resultados explicitamente é opcional. Entretanto, é uma boa prática fechar a conexão assim que o script termina de executar todas as suas operações de banco de dados, se ele ainda tiver muito processamento a realizar depois de obter os resultados.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Esta função sempre retorna `true`. Anteriormente retornava `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de mysqli::close()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "meu_usuario", "minha_senha", "mundo");

    $result = $mysqli->query("SELECT Nome, CodigoPais FROM Cidade ORDER BY ID LIMIT 3");

    /* Fecha a conexão assim que não for mais necessária */
    $mysqli->close();

    foreach ($result as $row) {
        /* Processando os dados obtidos do banco */
    }

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "meu_usuario", "minha_senha", "mundo");

    $result = mysqli_query($mysqli, "SELECT Nome, CodigoPais FROM Cidade ORDER BY ID LIMIT 3");

    /* Fecha a conexão assim que não for mais necessária */
    mysqli_close($mysqli);

    foreach ($result as $row) {
        /* Processando os dados obtidos do banco */
    }

### Notas

> Nota:

> mysqli_close() não fechará conexões persistentes. Para detalhes adicionais, consulte a página do manual sobre conexões persistentes.

### Veja Também

- mysqli::__construct() - Abre uma nova conexão com o servidor MySQL
- mysqli_init() - Inicializa o MySQLi e retorna um objeto a ser utilizado com mysqli_real_connect()
- mysqli_real_connect() - Abre uma conexão a um servidor MySQL
- mysqli_free_result() - Libera memória associada a um resultado

# mysqli::commit

# mysqli_commit

(PHP 5, PHP 7, PHP 8)

mysqli::commit -- mysqli_commit — Grava a transação atual

### Descrição

Estilo orientado a objetos

public function mysqli::commit(int `$flags` = 0, ?string `$name` = `null`): bool

Estilo procedural

function mysqli_commit(mysqli `$mysql`, int `$flags` = 0, ?string `$name` = `null`): bool

Grava a transação atual para a conexão do banco de dados.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()
`flags`

  Uma máscara de bits de constantes `MYSQLI_TRANS_COR_*`.

`name`

  Se fornecido, `COMMIT/*name*/` é executado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `name` agora pode ser nulo.

### Exemplos

Consulto o exemplo de mysqli::begin_transaction().

### Notas

> Nota:

> Esta função não funciona com tipos de tabelas não transacionais (como MyISAM ou ISAM).

### Veja Também

- mysqli_autocommit() - Ativa ou desativa a gravação automática das modificações no banco de dados
- mysqli_begin_transaction() - Inicia uma transação
- mysqli_rollback() - Reverte a transação atual
- mysqli_savepoint() - Define um ponto de salvamento de transação nomeado

# mysqli::$connect_errno

# mysqli_connect_errno

(PHP 5, PHP 7, PHP 8)

mysqli::$connect_errno -- mysqli_connect_errno — Retorna o código de erro da última chamada de conexão

### Descrição

Estilo orientado a objetos

int $mysqli->connect_errno;

Estilo procedural

function mysqli_connect_errno(): int

Retorna o código de erro da última tentativa de conexão.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um código de erro para a última tentativa de conexão, se tiver falhado. Zero significa que nenhum erro ocorreu.

Retorna o último código de erro da conexão independente da instância na qual o método for chamado.

### Exemplos

Exemplo #1 Exemplo de $mysqli->connect_errno

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_OFF);
    /* @ é usado para suprimir avisos */
    $mysqli = @new mysqli('localhost', 'usuario_falso', 'senha_errada', 'nao_existe');
    if ($mysqli->connect_errno) {
        /* Use seu método preferido de registro de erro aqui */
        error_log('Erro de conexão: ' . $mysqli->connect_errno);
    }

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_OFF);
    /* @ é usado para suprimir avisos */
    $link = @mysqli_connect('localhost', 'usuario_falso', 'senha_errada', 'nao_existe');
    if (!$link) {
        /* Use seu método preferido de registro de erro aqui */
        error_log('Erro de conexão: ' . mysqli_connect_errno());
    }

### Veja Também

- mysqli_connect() - Sinônimo de mysqli::__construct
- mysqli_connect_error() - Retorna uma descrição do último erro de conexão
- mysqli_errno() - Retorna o código de erro para a chamada de função mais recente
- mysqli_error() - Retorna uma string descrevendo o último erro
- mysqli_sqlstate() - Retorna o erro SQLSTATE da operação MySQL anterior

# mysqli::$connect_error

# mysqli_connect_error

(PHP 5, PHP 7, PHP 8)

mysqli::$connect_error -- mysqli_connect_error — Retorna uma descrição do último erro de conexão

### Descrição

Estilo orientado a objetos

?string $mysqli->connect_error;

Estilo procedural

function mysqli_connect_error(): ?string

Retorna a mensagem de erro da última tentativa de conexão.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Uma string que descreve o erro. `null` é retornado se nenhum erro tiver ocorrido.

Retorna o último erro da conexão independente da instância na qual o método for chamado.

### Exemplos

Exemplo #1 Exemplo de $mysqli->connect_error

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_OFF);
    /* @ é usado para suprimir avisos */
    $mysqli = @new mysqli('localhost', 'usuario_falso', 'senha_errada', 'nao_existe');
    if ($mysqli->connect_error) {
        /* Use seu método preferido de registro de erro aqui */
        error_log('Erro de conexão: ' . $mysqli->connect_error);
    }

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_OFF);
    /* @ é usado para suprimir avisos */
    $link = @mysqli_connect('localhost', 'usuario_falso', 'senha_errada', 'nao_existe');
    if (!$link) {
        /* Use seu método preferido de registro de erro aqui */
        error_log('Erro de conexão: ' . mysqli_connect_error());
    }

### Veja Também

- mysqli_connect() - Sinônimo de mysqli::__construct
- mysqli_connect_errno() - Retorna o código de erro da última chamada de conexão
- mysqli_errno() - Retorna o código de erro para a chamada de função mais recente
- mysqli_error() - Retorna uma string descrevendo o último erro
- mysqli_sqlstate() - Retorna o erro SQLSTATE da operação MySQL anterior

# mysqli::__construct

# mysqli::connect

# mysqli_connect

(PHP 5, PHP 7, PHP 8)

mysqli::__construct -- mysqli::connect -- mysqli_connect — Abre uma nova conexão com o servidor MySQL

### Descrição

Estilo orientado a objetos

public function mysqli::__construct(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
)
public function mysqli::connect(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
): bool

Estilo procedural

function mysqli_connect(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
): mysqli|false

Abre uma conexão com o servidor MySQL.

### Parâmetros

`hostname`

  Pode ser um nome de host ou um endereço IP. Ao passar `null`, o valor é recuperado de mysqli.default_host. Quando possível, serão usados pipes em vez do protocolo TCP/IP. O protocolo TCP/IP é usado se um nome de host e um número de porta forem fornecidos juntos, por ex. `localhost:3308`.

  Prefixar o host com `p:` abre uma conexão persistente. mysqli_change_user() é chamado automaticamente em conexões abertas a partir do pool de conexões.

`username`

  O nome de usuário do MySQL ou `null` para assumir o nome de usuário com base na opção ini mysqli.default_user.

`password`

  A senha do MySQL ou `null` para assumir a senha com base na opção ini mysqli.default_pw.

`database`

  O banco de dados padrão a ser utilizado ao realizar consultas ou `null`.

`port`

  O número da porta para tentar conectar ao servidor MySQL ou `null` para assumir a porta com base na opção ini mysqli.default_port.

`socket`

  O socket ou pipe nomeado que deve ser usado ou `null` para assumir o socket com base na opção ini mysqli.default_socket.

  > Nota:

  > A especificação do parâmetro `socket` não determinará explicitamente o tipo de conexão a ser usada ao conectar-se ao servidor MySQL. A maneira com a qual a conexão é feita com o banco de dados MySQL é determinada pelo parâmetro `hostname`.

### Valor Retornado

mysqli::__construct() sempre retorna um objeto que representa a conexão a um servidor MySQL, independente se teve sucesso ou não.

mysqli_connect() retorna um objeto que representa a conexão com um servidor MySQL, ou `false` em caso de falha.

mysqli::connect() retorna `true` em caso de sucesso ou `false` em caso de falha. Antes do PHP 8.1.0, ele retornava `null` em caso de sucesso.

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Agora, o método mysqli::connect() retorna `true` em vez de `null` em caso de sucesso.
7.4.0 | Todos os parâmetros podem ser null.

### Exemplos

Exemplo #1 Exemplo de mysqli::__construct()

Estilo orientado a objetos

    <?php

    /* O relatório de erros para mysqli deve ser ativado antes de tentar fazer uma conexão */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'my_db');

    /* Defina o conjunto de caracteres desejado após estabelecer uma conexão */
    $mysqli->set_charset('utf8mb4');

    printf("Success... %s\n", $mysqli->host_info);

Estilo procedural

    <?php

    /* O relatório de erros para mysqli deve ser ativado antes de tentar fazer uma conexão */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = mysqli_connect('localhost', 'my_user', 'my_password', 'my_db');

    /* Defina o conjunto de caracteres desejado após estabelecer uma conexão */
    mysqli_set_charset($mysqli, 'utf8mb4');

    printf("Sucesso... %s\n", mysqli_get_host_info($mysqli));

Os exemplos acima produzirão algo semelhante a:

    Sucesso... localhost via TCP/IP

Exemplo #2 Estendendo a classe mysqli

    <?php

    class FooMysqli extends mysqli {
        public function __construct($host, $user, $pass, $db, $port, $socket, $charset) {
            mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
            parent::__construct($host, $user, $pass, $db, $port, $socket);
            $this->set_charset($charset);
        }
    }

    $db = new FooMysqli('localhost', 'my_user', 'my_password', 'my_db', 3306, null, 'utf8mb4');

Exemplo #3 Tratamento manual de erros

Se o relatório de erros estiver desabilitado, o desenvolvedor é responsável por verificar e tratar as falhas

Estilo orientado a objetos

    <?php

    error_reporting(0);
    mysqli_report(MYSQLI_REPORT_OFF);
    $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'my_db');
    if ($mysqli->connect_errno) {
        throw new RuntimeException('mysqli connection error: ' . $mysqli->connect_error);
    }

    /* Defina o conjunto de caracteres desejado após estabelecer uma conexão */
    $mysqli->set_charset('utf8mb4');
    if ($mysqli->errno) {
        throw new RuntimeException('mysqli error: ' . $mysqli->error);
    }

Estilo procedural

    <?php

    error_reporting(0);
    mysqli_report(MYSQLI_REPORT_OFF);
    $mysqli = mysqli_connect('localhost', 'my_user', 'my_password', 'my_db');
    if (mysqli_connect_errno()) {
        throw new RuntimeException('mysqli connection error: ' . mysqli_connect_error());
    }

    /* Defina o conjunto de caracteres desejado após estabelecer uma conexão */
    mysqli_set_charset($mysqli, 'utf8mb4');
    if (mysqli_errno($mysqli)) {
        throw new RuntimeException('mysqli error: ' . mysqli_error($mysqli));
    }

### Notas

> Nota: O MySQLnd sempre assume o conjunto de caracteres padrão do servidor. Este conjunto de caracteres é enviado durante a criação/autenticação da conexão e será usado pelo mysqlnd.A libmysqlclient usa o conjunto de caracteres padrão definido no arquivo my.cnf ou definido por uma chamada explícita a mysqli_options() antes de chamar mysqli_real_connect(), mas depois de chamar mysqli_init().

> Nota:

> Estilo orientado a objetos apenas: Se a conexão falhar, um objeto ainda será retornado. Para verificar se a conexão falhou, use a função mysqli_connect_error() ou a propriedade mysqli->connect_error como nos exemplos anteriores.

> Nota:

> Se for necessário definir opções, como o tempo limite de conexão, mysqli_real_connect() deve ser usado.

> Nota:

> Chamar o construtor sem parâmetros é o mesmo que chamar mysqli_init().

> Nota:

> O erro "Can't create TCP/IP socket (10106)" geralmente significa que a diretiva de configuração variables_order não contém o caractere `E`. No Windows, se o ambiente não for copiado, a variável de ambiente `SYSTEMROOT` não estará disponível e o PHP terá problemas para carregar o Winsock.

### Veja Também

- mysqli_real_connect() - Abre uma conexão a um servidor MySQL
- mysqli_options() - Define opções
- mysqli_connect_errno() - Retorna o código de erro da última chamada de conexão
- mysqli_connect_error() - Retorna uma descrição do último erro de conexão
- mysqli_close() - Fecha uma conexão ao banco de dados previamente aberta

# mysqli::debug

# mysqli_debug

(PHP 5, PHP 7, PHP 8)

mysqli::debug -- mysqli_debug — Realiza operações de depuração

### Descrição

Estilo orientado a objetos

public function mysqli::debug(string `$options`): true

Estilo procedural

function mysqli_debug(string `$options`): true

Realiza operações de depuração usando a biblioteca Fred Fish.

### Parâmetros

`options`

  Uma string representando a operação de depuração a ser executada

  A string de opções de depuração é uma sequência de campos separados por dois pontos (:) desta maneira: ``

      <campo_1>:<campo_2>:<campo_N>

  Cada campo consiste de um caractere de opção mandatório seguido por uma `,` opcional e uma lista de modificadores: separados por vírgula: `opção[,modificador,modificador,...,modificador]`

  Caracteres de Opção Reconhecidos
  Caractere de `options` | Descrição
  --- | ---
  O | `MYSQLND_DEBUG_FLUSH`
  A/a | `MYSQLND_DEBUG_APPEND`
  F | `MYSQLND_DEBUG_DUMP_FILE`
  i | `MYSQLND_DEBUG_DUMP_PID`
  L | `MYSQLND_DEBUG_DUMP_LINE`
  m | `MYSQLND_DEBUG_TRACE_MEMORY_CALLS`
  n | `MYSQLND_DEBUG_DUMP_LEVEL`
  o | saída para arquivo
  T | `MYSQLND_DEBUG_DUMP_TIME`
  t | `MYSQLND_DEBUG_DUMP_TRACE`
  x | `MYSQLND_DEBUG_PROFILE_CALLS`

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Esta função agora sempre retorna `true`. Anteriormente retornava `false` em caso de falha.

### Exemplos

Exemplo #1 Gerando um Arquivo de Rastreamento

    <?php

    /* Cria um arquivo de rastreamento em '/tmp/client.trace' na máquina local (do cliente): */
    mysqli_debug("d:t:o,/tmp/client.trace");

    ?>

### Notas

> Nota:

> Para usar a função mysqli_debug() deve-se compilar a biblioteca do cliente MySQL com suporte a depuração.

### Veja Também

- mysqli_dump_debug_info() - Descarrega informação de debug no log
- mysqli_report() - Sinônimo de mysqli_driver->report_mode

# mysqli::dump_debug_info

# mysqli_dump_debug_info

(PHP 5, PHP 7, PHP 8)

mysqli::dump_debug_info -- mysqli_dump_debug_info — Descarrega informação de debug no log

### Descrição

Estilo orientado a objetos

public function mysqli::dump_debug_info(): bool

Estilo procedural

function mysqli_dump_debug_info(mysqli `$mysql`): bool

Esta função é projetada para ser executada por um usuário com privilégio SUPER e é usada para descarregar informações de depuração no log, para o servidor MySQL, relacionadas à conexão.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- mysqli_debug() - Realiza operações de depuração

# mysqli->errno

# mysqli_errno

(PHP 5, PHP 7, PHP 8)

mysqli->errno -- mysqli_errno — Retorna o código de erro para a chamada de função mais recente

### Descrição

Estilo orientado a objetos

int $mysqli->errno;

Estilo procedural

function mysqli_errno(mysqli `$mysql`): int

Retorna o último código de erro para a chamada de função MySQLi mais recente que pode ter sucesso ou falhar.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()

### Valor Retornado

Um valor de código de erro para a última chamada, se ela falhou. Zero significa que nenhum erro ocorreu.

### Exemplos

Exemplo #1 Exemplo de $mysqli->errno

Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* check connection */
    if ($mysqli->connect_errno) {
        printf("Conexão falhou: %s\n", $mysqli->connect_error);
        exit();
    }

    if (!$mysqli->query("SET a=1")) {
        printf("Errorcode: %d\n", $mysqli->errno);
    }

    /* close connection */
    $mysqli->close();
    ?>

Estilo procedural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    if (!mysqli_query($link, "SET a=1")) {
        printf("Errorcode: %d\n", mysqli_errno($link));
    }

    /* close connection */
    mysqli_close($link);
    ?>

Os exemplos acima produzirão:

    Errorcode: 1193

### Veja Também

- mysqli_connect_errno() - Retorna o código de erro da última chamada de conexão
- mysqli_connect_error() - Retorna uma descrição do último erro de conexão
- mysqli_error() - Retorna uma string descrevendo o último erro
- mysqli_sqlstate() - Retorna o erro SQLSTATE da operação MySQL anterior

# mysqli->error

# mysqli_error

(PHP 5, PHP 7, PHP 8)

mysqli->error -- mysqli_error — Retorna uma string descrevendo o último erro

### Descrição

Estilo orientado a objetos

string $mysqli->error;

Estilo procedural

function mysqli_error(mysqli `$mysql`): string

Retorna a última mensagem de erro da chamada de função MySQLi mais recente que possa ter sucesso ou falhar.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()

### Valor Retornado

Uma string que descreve o erro. Uma string vazia se não houve erro.

### Exemplos

Exemplo #1 Exemplo de $mysqli->error

Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* check connection */
    if ($mysqli->connect_errno) {
        printf("Conexão falhou: %s\n", $mysqli->connect_error);
        exit();
    }

    if (!$mysqli->query("SET a=1")) {
        printf("Error message: %s\n", $mysqli->error);
    }

    /* close connection */
    $mysqli->close();
    ?>

Estilo procedural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    if (!mysqli_query($link, "SET a=1")) {
        printf("Error message: %s\n", mysqli_error($link));
    }

    /* close connection */
    mysqli_close($link);
    ?>

Os exemplos acima produzirão:

    Error message: Unknown system variable 'a'

### Veja Também

- mysqli_connect_errno() - Retorna o código de erro da última chamada de conexão
- mysqli_connect_error() - Retorna uma descrição do último erro de conexão
- mysqli_errno() - Retorna o código de erro para a chamada de função mais recente
- mysqli_sqlstate() - Retorna o erro SQLSTATE da operação MySQL anterior

# mysqli::$error_list

# mysqli_error_list

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

mysqli::$error_list -- mysqli_error_list — Retorna uma lista de erros do último comando executado

### Descrição

Estilo orientado a objetos

array $mysqli->error_list;

Estilo procedural

function mysqli_error_list(mysqli `$mysql`): array

Retorna um array de erros para a chamada de função MySQLi mais recente que pode ser bem-sucedida ou falhar.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()

### Valor Retornado

Uma lista de erros, cada um como um array associativo contendo errno, error e sqlstate.

### Exemplos

Exemplo #1 Exemplo de $mysqli->error_list

Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "nobody", "");

    /* verifica a conexão */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    if (!$mysqli->query("SET a=1")) {
        print_r($mysqli->error_list);
    }

    /* fecha a conexão */
    $mysqli->close();
    ?>

Estilo procedural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* verifica a conexão */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    if (!mysqli_query($link, "SET a=1")) {
        print_r(mysqli_error_list($link));
    }

    /* fecha a conexão */
    mysqli_close($link);
    ?>

Os exemplos acima produzirão:

    Array
    (
        [0] => Array
            (
                [errno] => 1193
                [sqlstate] => HY000
                [error] => Unknown system variable 'a'
            )

    )

### Veja Também

- mysqli_connect_errno() - Retorna o código de erro da última chamada de conexão
- mysqli_connect_error() - Retorna uma descrição do último erro de conexão
- mysqli_error() - Retorna uma string descrevendo o último erro
- mysqli_sqlstate() - Retorna o erro SQLSTATE da operação MySQL anterior

# mysqli::execute_query

# mysqli_execute_query

(PHP 8 >= 8.2.0)

mysqli::execute_query -- mysqli_execute_query — Prepara, vincula parâmetros e executa a instrução SQL

### Descrição

Estilo orientado a objetos

public function mysqli::execute_query(string `$query`, ?array `$params` = `null`): mysqli_result|bool

Estilo procedural

function mysqli_execute_query(mysqli `$mysql`, string `$query`, ?array `$params` = `null`): mysqli_result|bool

Prepara a consulta SQL, associa parâmetros e a executa. O método mysqli::execute_query() é um atalho para mysqli::prepare(), mysqli_stmt::bind_param(), mysqli_stmt::execute() e mysqli_stmt::get_result().

O modelo de instrução pode conter zero ou mais marcadores de parâmetro de ponto de interrogação (`?`) também chamados de espaços reservados. Os valores dos parâmetros devem ser fornecidos como um array usando o parâmetro `params`.

Uma instrução preparada é criada, mas nunca é exposta fora da função. É impossível acessar as propriedades da instrução como faria com o objeto mysqli_stmt. Devido a essa limitação, as informações de status são copiadas para o objeto mysqli e estão disponíveis usando seus métodos, por exemplo mysqli_affected_rows() ou mysqli_error().

> Nota:

> No caso em que uma instrução é passada para mysqli_execute_query() que é maior que `max_allowed_packet` do servidor, os códigos de erro retornados são diferentes dependendo do sistema operacional. O comportamento é o seguinte:

> - No Linux retorna um código de erro de 1153. A mensagem de erro significa que o pacote é maior que `max_allowed_packet` bytes.

> - No Windows retorna um código de erro 2006. Essa mensagem de erro significa que o servidor foi desativado.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()
`query`

  A consulta, como uma string. Deve consistir em uma única instrução SQL.

  A instrução SQL pode conter zero ou mais marcadores de parâmetro representados por caracteres de ponto de interrogação (`?`) nas posições apropriadas.

  > Nota:

  > Os marcadores são válidos apenas em determinados locais nas instruções SQL. Por exemplo, eles são permitidos na lista `VALUES()` de uma instrução `INSERT` (para especificar valores de coluna para uma linha) ou em uma comparação com uma coluna em uma cláusula `WHERE` para especificar um valor de comparação. No entanto, eles não são permitidos para identificadores (como nomes de tabelas ou colunas).

`params`

  Um array opcional com tantos elementos quantos forem os parâmetros vinculados na instrução SQL que está sendo executada. Cada valor é tratado como uma string.

### Valor Retornado

Retorna `false` em caso de falha. Para consultas bem-sucedidas que produzem um conjunto de resultados, como `SELECT, SHOW, DESCRIBE` ou `EXPLAIN`, retorna um objeto mysqli_result. Para outras consultas bem-sucedidas, retorna `true`.

### Exemplos

Exemplo #1 Exemplo de mysqli::execute_query()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world');

    $query = 'SELECT Name, District FROM City WHERE CountryCode=? ORDER BY Name LIMIT 5';
    $result = $mysqli->execute_query($query, ['DEU']);
    foreach ($result as $row) {
        printf("%s (%s)\n", $row["Name"], $row["District"]);
    }

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = 'SELECT Name, District FROM City WHERE CountryCode=? ORDER BY Name LIMIT 5';
    $result = mysqli_execute_query($link, $query, ['DEU']);
    foreach ($result as $row) {
        printf("%s (%s)\n", $row["Name"], $row["District"]);
    }

Os exemplos acima produzirão algo semelhante a:

    Aachen (Nordrhein-Westfalen)
    Augsburg (Baijeri)
    Bergisch Gladbach (Nordrhein-Westfalen)
    Berlin (Berliini)
    Bielefeld (Nordrhein-Westfalen)

### Veja Também

- mysqli_prepare() - Prepara uma instrução SQL para execução
- mysqli_stmt_execute() - Executa uma instrução preparada
- mysqli_stmt_bind_param() - Liga variáveis a uma declaração preparada como parâmetros
- mysqli_stmt_get_result() - Obtém um resultado de uma instrução preparada como um objeto mysqli_result

# mysqli::$field_count

# mysqli_field_count

(PHP 5, PHP 7, PHP 8)

mysqli::$field_count -- mysqli_field_count — Retorna o número de campos para a consulta mais recente

### Descrição

Estilo orientado a objetos

int $mysqli->field_count;

Estilo procedural

function mysqli_field_count(mysqli `$mysql`): int

Retorna o número de campos para a consulta mais recente na conexão representada pelo parâmetro `mysql`. Esta função pode ser útil quando a função mysqli_store_result() é usada para determinar se a consulta deveria ou não ter produzido um conjunto não vazio de resultados sem conhecer a natureza da consulta.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()

### Valor Retornado

Um inteiro representando o número de campos em um conjunto de resultados.

### Exemplos

Exemplo #1 Exemplo de $mysqli->field_count

Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "meu_usuario", "minha_senha", "teste");

    $mysqli->query( "DROP TABLE IF EXISTS amigos");
    $mysqli->query( "CREATE TABLE amigos (id int, nome varchar(20))");

    $mysqli->query( "INSERT INTO amigos VALUES (1,'Luiz'), (2, 'Ricardo')");

    $mysqli->real_query("SELECT * FROM amigos");

    if ($mysqli->field_count) {
        /* esta foi uma consulta de select/show ou describe */
        $result = $mysqli->store_result();

        /* processa o conjunto de resultados */
        $row = $result->fetch_row();

        /* libera o conjunto de resultados */
        $result->close();
    }

    /* fecha a conexão */
    $mysqli->close();
    ?>

Estilo procedural

    <?php
    $link = mysqli_connect("localhost", "meu_usuario", "minha_senha", "teste");

    mysqli_query($link, "DROP TABLE IF EXISTS amigos");
    mysqli_query($link, "CREATE TABLE amigos (id int, nome varchar(20))");

    mysqli_query($link, "INSERT INTO amigos VALUES (1,'Luiz'), (2, 'Ricardo')");

    mysqli_real_query($link, "SELECT * FROM amigos");

    if (mysqli_field_count($link)) {
        /* esta foi uma consulta de select/show ou describe */
        $result = mysqli_store_result($link);

        /* processa o conjunto de resultados */
        $row = mysqli_fetch_row($result);

        /* libera o conjunto de resultados */
        mysqli_free_result($result);
    }

    /* fecha a conexão */
    mysqli_close($link);
    ?>

# mysqli::get_charset

# mysqli_get_charset

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

mysqli::get_charset -- mysqli_get_charset — Retorna um objeto de conjunto de caracteres

### Descrição

Estilo orientado a objetos

public function mysqli::get_charset(): ?object

Estilo procedural

function mysqli_get_charset(mysqli `$mysql`): ?object

Retorna um objeto de conjunto de caracteres fornecendo várias propriedades do conjunto de caracteres ativo atual.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()

### Valor Retornado

A função retorna um objeto de conjunto de caracteres com as seguintes propriedades:

`charset`

  Nome do conjunto de caracteres

`collation`

  Nome do agrupamento

`dir`

  Diretório do qual a descrição do conjunto de caracteres foi obtida ou "" para conjuntos de caracteres integrados

`min_length`

  Comprimento mínimo de caracteres em bytes

`max_length`

  Comprimento máximo de caracteres em bytes

`number`

  Número interno do conjunto de caracteres

`state`

  A partir do PHP 8.2.0, é sempre `1`

### Exemplos

Exemplo #1 Exemplo de mysqli::get_charset()

Estilo orientado a objetos

    <?php
      $db = mysqli_init();
      $db->real_connect("localhost","root","","test");
      $db->set_charset('latin1');
      var_dump($db->get_charset());
    ?>

Estilo procedural

    <?php
      $db = mysqli_init();
      mysqli_real_connect($db, "localhost","root","","test");
      mysqli_set_charset($db, 'latin1');
      var_dump(mysqli_get_charset($db));
    ?>

Os exemplos acima produzirão:

    object(stdClass)#2 (7) {
      ["charset"]=>
      string(6) "latin1"
      ["collation"]=>
      string(17) "latin1_swedish_ci"
      ["dir"]=>
      string(0) ""
      ["min_length"]=>
      int(1)
      ["max_length"]=>
      int(1)
      ["number"]=>
      int(8)
      ["state"]=>
      int(1)
    }

### Veja Também

- mysqli_character_set_name() - Retorna o conjunto de caracteres atual da conexão com o banco de dados
- mysqli_set_charset() - Define o conjunto de caracteres do cliente

# mysqli::$client_info

# mysqli::get_client_info

# mysqli_get_client_info

(PHP 5, PHP 7, PHP 8)

mysqli::$client_info -- mysqli::get_client_info -- mysqli_get_client_info — Obtém informação do cliente MySQL

### Descrição

Estilo orientado a objetos

string $mysqli->client_info;
#[\Deprecated]
public function mysqli::get_client_info(): string

Estilo procedural

function mysqli_get_client_info(?mysqli `$mysql` = null): string

Retorna uma string que representa a versão de biblioteca do cliente MySQL.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Uma string que representa a versão da biblioteca do cliente MySQL.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Chamar mysqli_get_client_info() com o argumento `mysql` foi descontinuado. Esta função nunca requereu um parâmetro, mas incorretamente permitia este parâmetro opcional.
8.1.0 | O método orientado a objeto mysqli::get_client_info() foi descontinuado.

### Exemplos

Exemplo #1 mysqli_get_client_info

    <?php

    /* Não é necessária uma conexão para determinar
       a versão da biblioteca do cliente mysql */

    printf("Client library version: %s\n", mysqli_get_client_info());
    ?>

### Veja Também

- mysqli_get_client_version() - Retorna a versão do cliente MySQL como um inteiro
- mysqli_get_server_info() - Retorna a versão do servidor MySQL
- mysqli_get_server_version() - Retorna a versão do servidor MySQL como um inteiro

# mysqli::$client_version

# mysqli_get_client_version

(PHP 5, PHP 7, PHP 8)

mysqli::$client_version -- mysqli_get_client_version — Retorna a versão do cliente MySQL como um inteiro

### Descrição

Estilo orientado a objetos

int $mysqli->client_version;

Estilo procedural

function mysqli_get_client_version(): int

Retorna a versão do cliente como um inteiro.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um número que representa a versão da biblioteca de cliente MySQL no formato: `versão_principal*10000 + versão_menor *100 + sub_versão`. Por exemplo, 4.1.0 é retornado como 40100.

Isto é útil para determinar rapidamente a versão da biblioteca de cliente para saber se alguma funcionalidade existe.

### Exemplos

Exemplo #1 mysqli_get_client_version

    <?php

    /* Não é necessária uma conexão para determinar
       a versão da biblioteca do cliente mysql */

    printf("Client library version: %d\n", mysqli_get_client_version());
    ?>

### Veja Também

- mysqli_get_client_info() - Obtém informação do cliente MySQL
- mysqli_get_server_info() - Retorna a versão do servidor MySQL
- mysqli_get_server_version() - Retorna a versão do servidor MySQL como um inteiro

# mysqli::get_connection_stats

# mysqli_get_connection_stats

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli::get_connection_stats -- mysqli_get_connection_stats — Retorna estatísticas sobre a conexão do cliente

### Descrição

Estilo orientado a objetos

public function mysqli::get_connection_stats(): array

Estilo procedural

function mysqli_get_connection_stats(mysqli `$mysql`): array

Retorna estatísticas sobre a conexão do cliente.

> Nota:

> Disponível apenas com o mysqlnd.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()

### Valor Retornado

Retorna um array com estatísticas de conexão.

### Exemplos

Exemplo #1 Exemplo de mysqli_get_connection_stats()

    <?php
    $link = mysqli_connect();
    print_r(mysqli_get_connection_stats($link));
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [bytes_sent] => 43
        [bytes_received] => 80
        [packets_sent] => 1
        [packets_received] => 2
        [protocol_overhead_in] => 8
        [protocol_overhead_out] => 4
        [bytes_received_ok_packet] => 11
        [bytes_received_eof_packet] => 0
        [bytes_received_rset_header_packet] => 0
        [bytes_received_rset_field_meta_packet] => 0
        [bytes_received_rset_row_packet] => 0
        [bytes_received_prepare_response_packet] => 0
        [bytes_received_change_user_packet] => 0
        [packets_sent_command] => 0
        [packets_received_ok] => 1
        [packets_received_eof] => 0
        [packets_received_rset_header] => 0
        [packets_received_rset_field_meta] => 0
        [packets_received_rset_row] => 0
        [packets_received_prepare_response] => 0
        [packets_received_change_user] => 0
        [result_set_queries] => 0
        [non_result_set_queries] => 0
        [no_index_used] => 0
        [bad_index_used] => 0
        [slow_queries] => 0
        [buffered_sets] => 0
        [unbuffered_sets] => 0
        [ps_buffered_sets] => 0
        [ps_unbuffered_sets] => 0
        [flushed_normal_sets] => 0
        [flushed_ps_sets] => 0
        [ps_prepared_never_executed] => 0
        [ps_prepared_once_executed] => 0
        [rows_fetched_from_server_normal] => 0
        [rows_fetched_from_server_ps] => 0
        [rows_buffered_from_client_normal] => 0
        [rows_buffered_from_client_ps] => 0
        [rows_fetched_from_client_normal_buffered] => 0
        [rows_fetched_from_client_normal_unbuffered] => 0
        [rows_fetched_from_client_ps_buffered] => 0
        [rows_fetched_from_client_ps_unbuffered] => 0
        [rows_fetched_from_client_ps_cursor] => 0
        [rows_skipped_normal] => 0
        [rows_skipped_ps] => 0
        [copy_on_write_saved] => 0
        [copy_on_write_performed] => 0
        [command_buffer_too_small] => 0
        [connect_success] => 1
        [connect_failure] => 0
        [connection_reused] => 0
        [reconnect] => 0
        [pconnect_success] => 0
        [active_connections] => 1
        [active_persistent_connections] => 0
        [explicit_close] => 0
        [implicit_close] => 0
        [disconnect_close] => 0
        [in_middle_of_command_close] => 0
        [explicit_free_result] => 0
        [implicit_free_result] => 0
        [explicit_stmt_close] => 0
        [implicit_stmt_close] => 0
        [mem_emalloc_count] => 0
        [mem_emalloc_ammount] => 0
        [mem_ecalloc_count] => 0
        [mem_ecalloc_ammount] => 0
        [mem_erealloc_count] => 0
        [mem_erealloc_ammount] => 0
        [mem_efree_count] => 0
        [mem_malloc_count] => 0
        [mem_malloc_ammount] => 0
        [mem_calloc_count] => 0
        [mem_calloc_ammount] => 0
        [mem_realloc_count] => 0
        [mem_realloc_ammount] => 0
        [mem_free_count] => 0
        [proto_text_fetched_null] => 0
        [proto_text_fetched_bit] => 0
        [proto_text_fetched_tinyint] => 0
        [proto_text_fetched_short] => 0
        [proto_text_fetched_int24] => 0
        [proto_text_fetched_int] => 0
        [proto_text_fetched_bigint] => 0
        [proto_text_fetched_decimal] => 0
        [proto_text_fetched_float] => 0
        [proto_text_fetched_double] => 0
        [proto_text_fetched_date] => 0
        [proto_text_fetched_year] => 0
        [proto_text_fetched_time] => 0
        [proto_text_fetched_datetime] => 0
        [proto_text_fetched_timestamp] => 0
        [proto_text_fetched_string] => 0
        [proto_text_fetched_blob] => 0
        [proto_text_fetched_enum] => 0
        [proto_text_fetched_set] => 0
        [proto_text_fetched_geometry] => 0
        [proto_text_fetched_other] => 0
        [proto_binary_fetched_null] => 0
        [proto_binary_fetched_bit] => 0
        [proto_binary_fetched_tinyint] => 0
        [proto_binary_fetched_short] => 0
        [proto_binary_fetched_int24] => 0
        [proto_binary_fetched_int] => 0
        [proto_binary_fetched_bigint] => 0
        [proto_binary_fetched_decimal] => 0
        [proto_binary_fetched_float] => 0
        [proto_binary_fetched_double] => 0
        [proto_binary_fetched_date] => 0
        [proto_binary_fetched_year] => 0
        [proto_binary_fetched_time] => 0
        [proto_binary_fetched_datetime] => 0
        [proto_binary_fetched_timestamp] => 0
        [proto_binary_fetched_string] => 0
        [proto_binary_fetched_blob] => 0
        [proto_binary_fetched_enum] => 0
        [proto_binary_fetched_set] => 0
        [proto_binary_fetched_geometry] => 0
        [proto_binary_fetched_other] => 0
    )

### Veja Também

- Stats description

# mysqli::$host_info

# mysqli_get_host_info

(PHP 5, PHP 7, PHP 8)

mysqli::$host_info -- mysqli_get_host_info — Retorna uma string representando o tipo de conexão utilizada

### Descrição

Estilo orientado a objetos

string $mysqli->host_info;

Estilo procedural

function mysqli_get_host_info(mysqli `$mysql`): string

Retorna uma string descrevendo a conexão representada pelo parâmetro `mysql` (incluindo o nome de host servidor).

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()

### Valor Retornado

Uma string de caracteres representando o nome de host do servidor e o tipo de conexão.

### Exemplos

Exemplo #1 Exemplo de $mysqli->host_info

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* mostra informação do host */
    printf("Host info: %s\n", $mysqli->host_info);

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* mostra informação do host */
    printf("Host info: %s\n", mysqli_get_host_info($link));

Os exemplos acima produzirão:

    Host info: Localhost via UNIX socket

### Veja Também

- mysqli_get_proto_info() - Retorna a versão do protocolo MySQL usada

# mysqli::$protocol_version

# mysqli_get_proto_info

(PHP 5, PHP 7, PHP 8)

mysqli::$protocol_version -- mysqli_get_proto_info — Retorna a versão do protocolo MySQL usada

### Descrição

Estilo orientado a objetos

int $mysqli->protocol_version;

Estilo procedural

function mysqli_get_proto_info(mysqli `$mysql`): int

Retorna um inteiro representando a versão do protocolo MySQL usada pela conexão representada pelo parâmetro `mysql`.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()

### Valor Retornado

Retorna um inteiro representando a versão do protocolo.

### Exemplos

Exemplo #1 Exemplo de $mysqli->protocol_version

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password");

    /* mostra a versão do protocolo */
    printf("Versão do protocolo: %d\n", $mysqli->protocol_version);

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password");

    /* mostra a versão do protocolo */
    printf("Versão do protocolo: %d\n", mysqli_get_proto_info($link));

Os exemplos acima produzirão:

    Versão do protocolo: 10

### Veja Também

- mysqli_get_host_info() - Retorna uma string representando o tipo de conexão utilizada

# mysqli::$server_info

# mysqli::get_server_info

# mysqli_get_server_info

(PHP 5, PHP 7, PHP 8)

mysqli::$server_info -- mysqli::get_server_info -- mysqli_get_server_info — Retorna a versão do servidor MySQL

### Descrição

Estilo orientado a objetos

string $mysqli->server_info;
public function mysqli::get_server_info(): string

Estilo procedural

function mysqli_get_server_info(mysqli `$mysql`): string

Retorna uma string representando a versão do servidor MySQL ao qual a extensão MySQLi está conectada.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()

### Valor Retornado

Uma string de caracteres representando a versão do servidor.

### Exemplos

Exemplo #1 Exemplo de $mysqli->server_info

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password");

    /* print server version */
    printf("Server version: %s\n", $mysqli->server_info);

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password");

    /* print server version */
    printf("Server version: %s\n", mysqli_get_server_info($link));

Os exemplos acima produzirão algo semelhante a:

    Server version: 8.0.21

### Veja Também

- mysqli_get_client_info() - Obtém informação do cliente MySQL
- mysqli_get_client_version() - Retorna a versão do cliente MySQL como um inteiro
- mysqli_get_server_version() - Retorna a versão do servidor MySQL como um inteiro

# mysqli::$server_version

# mysqli_get_server_version

(PHP 5, PHP 7, PHP 8)

mysqli::$server_version -- mysqli_get_server_version — Retorna a versão do servidor MySQL como um inteiro

### Descrição

Estilo orientado a objetos

int $mysqli->server_version;

Estilo procedural

function mysqli_get_server_version(mysqli `$mysql`): int

A função mysqli_get_server_version() retorna a versão do servidor ao qual se está conectado (representado pelo parâmetro `mysql`) como um inteiro.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()

### Valor Retornado

Um inteiro representando a versão do servidor.

A forma deste número de versão é `versão_principal * 10000 + versão_menor * 100 + sub_versão` (ex. a versão 4.1.0 é 40100).

### Exemplos

Exemplo #1 Exemplo de $mysqli->server_version

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password");

    /* print server version */
    printf("Server version: %d\n", $mysqli->server_version);

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password");

    /* print server version */
    printf("Server version: %d\n", mysqli_get_server_version($link));

Os exemplos acima produzirão algo semelhante a:

    Server version: 80021

### Veja Também

- mysqli_get_client_info() - Obtém informação do cliente MySQL
- mysqli_get_client_version() - Retorna a versão do cliente MySQL como um inteiro
- mysqli_get_server_info() - Retorna a versão do servidor MySQL

# mysqli::get_warnings

# mysqli_get_warnings

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

mysqli::get_warnings -- mysqli_get_warnings — Obtém o resultado de SHOW WARNINGS

### Descrição

Estilo orientado a objetos

public function mysqli::get_warnings(): mysqli_warning|false

Estilo procedural

function mysqli_get_warnings(mysqli `$mysql`): mysqli_warning|false

Retorna uma lista vinculada individualmente composta por mysqli_warning ou `false` se não houver alertas. Cada objeto na lista corresponde a uma única linha do resultado de `SHOW WARNINGS`. Chamar mysqli_warning::next() irá recarregar o objeto com os valores da próxima linha.

> Nota: Para recuperar mensagens de alerta, é recomendado usar o comando SQL `SHOW WARNINGS [limit row_count]` em vez desta função.

Aviso

A lista vinculada não pode ser retrocedida ou recuperada novamente.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()

### Valor Retornado

Retorna uma lista vinculada individualmente composta por mysqli_warning ou `false` se não houver alertas.

### Exemplos

Exemplo #1 Percorrendo a lista vinculada para buscar todos os alertas

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $mysqli->query("SELECT 1/0, CAST('NULL' AS UNSIGNED)");

    if ($mysqli->warning_count > 0) {
        $warning = $mysqli->get_warnings();
        if ($warning !== false) {
            do {
                printf("Número do erro: %s\n", $warning->errno);
                printf("Mensagem: %s\n", $warning->message);
            } while ($warning->next());
        }
    }

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "user", "password", "test");

    mysqli_query($link, "SELECT 1/0, CAST('NULL' AS UNSIGNED)");

    if (mysqli_warning_count($link) > 0) {
        $warning = mysqli_get_warnings($link);
        if ($warning !== false) {
            do {
                printf("Número do erro: %s\n", $warning->errno);
                printf("Mensagem: %s\n", $warning->message);
            } while ($warning->next());
        }
    }

Os exemplos acima produzirão:

    Número do erro: 1365
    Mensagem: Division by 0
    Número do erro: 1292
    Mensagem: Truncated incorrect INTEGER value: 'NULL'

# mysqli::$info

# mysqli_info

(PHP 5, PHP 7, PHP 8)

mysqli::$info -- mysqli_info — Recupera informação sobre a recente consulta executada

### Descrição

Estilo orientado a objetos

?string $mysqli->info;

Estilo procedural

function mysqli_info(mysqli `$mysql`): ?string

A função mysqli_info() retorna uma string contendo informação sobre a última consulta executada. A natureza desta string é fornecida abaixo:

Possíveis valores de retorno de mysqli_info
Tipo de consulta | Exemplo da string de resultado
--- | ---
INSERT INTO...SELECT... | Records: 100 Duplicates: 0 Warnings: 0
INSERT INTO...VALUES (...),(...),(...) | Records: 3 Duplicates: 0 Warnings: 0
LOAD DATA INFILE ... | Records: 1 Deleted: 0 Skipped: 0 Warnings: 0
ALTER TABLE ... | Records: 3 Duplicates: 0 Warnings: 0
UPDATE ... | Rows matched: 40 Changed: 40 Warnings: 0

> Nota:

> Consultas que não se encaixam em um dos formatos acima não são suportadas. Nesta situação, mysqli_info() irá retornar uma string vazia.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()

### Valor Retornado

Uma string de caracteres representando informação adicional sobre a mais recente consulta executada.

### Exemplos

Exemplo #1 Exemplo de $mysqli->info

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $mysqli->query("CREATE TEMPORARY TABLE t1 LIKE City");

    /* INSERT INTO ... SELECT */
    $mysqli->query("INSERT INTO t1 SELECT * FROM City ORDER BY ID LIMIT 150");
    printf("%s\n", $mysqli->info);

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    mysqli_query($link, "CREATE TEMPORARY TABLE t1 LIKE City");

    /* INSERT INTO ... SELECT */
    mysqli_query($link, "INSERT INTO t1 SELECT * FROM City ORDER BY ID LIMIT 150");
    printf("%s\n", mysqli_info($link));

Os exemplos acima produzirão:

    Records: 150  Duplicates: 0  Warnings: 0

### Veja Também

- mysqli_affected_rows() - Retorna o número de linhas afetadas pela operação MySQL anterior
- mysqli_warning_count() - Retorna o número de alertas gerados pela consulta mais recente
- mysqli_num_rows() - Obtém o número de linhas no resultado

# mysqli::init

# mysqli_init

(PHP 5, PHP 7, PHP 8)

mysqli::init -- mysqli_init — Inicializa o MySQLi e retorna um objeto a ser utilizado com mysqli_real_connect()

### Descrição

Estilo orientado a objetos

#[\Deprecated]
public function mysqli::init(): ?bool

Estilo procedural

function mysqli_init(): mysqli|false

Aloca ou inicializa um objeto MYSQL adequado para as funções mysqli_options() e mysqli_real_connect().

> Nota:

> Chamadas subsequentes a quaisquer funções mysqli (exceto mysqli_options() e mysqli_ssl_set()) irão falhar até que mysqli_real_connect() seja chamada.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

mysqli::init() retorna `null` em caso de sucesso, ou `false` em caso de falha. mysqli_init() retorna um objeto em caso de sucesso, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O método mysqli::init() com estilo orientado a objeto foi descontinuado. Substitua as chamadas a parent::init() por parent::__construct().

### Exemplos

Consulte mysqli_real_connect().

### Veja Também

- mysqli_options() - Define opções
- mysqli_close() - Fecha uma conexão ao banco de dados previamente aberta
- mysqli_real_connect() - Abre uma conexão a um servidor MySQL
- mysqli_connect() - Sinônimo de mysqli::__construct

# mysqli::$insert_id

# mysqli_insert_id

(PHP 5, PHP 7, PHP 8)

mysqli::$insert_id -- mysqli_insert_id — Retorna o valor gerado para uma coluna AUTO_INCREMENT pela última consulta

### Descrição

Estilo orientado a objetos

int|string $mysqli->insert_id;

Estilo procedural

function mysqli_insert_id(mysqli `$mysql`): int|string

Retorna o ID gerado por uma consulta `INSERT` ou `UPDATE` em uma tabela que tenha o atributo `AUTO_INCREMENT`. No caso de uma declaração `INSERT` de múltiplas linhas, ela retorna o primeiro valor gerado automaticamente que foi inserido com sucesso.

Realizar uma declaração `INSERT` ou `UPDATE` usando a função MYSQL `LAST_INSERT_ID()` também irá modificar o valor retornado por mysqli_insert_id(). Se `LAST_INSERT_ID(expr)` foi usado para gerar o valor de `AUTO_INCREMENT`, ela retorna o valor da última `expr` no lugar do valor `AUTO_INCREMENT` gerado.

Retorna `0` se a declaração anterior não modificou um valor `AUTO_INCREMENT`. mysqli_insert_id() deve ser chamada imediatamente após a declaração que gerou o valor.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()

### Valor Retornado

O valor do campo `AUTO_INCREMENT` que foi atualizado pela consulta anterior. Retorna zero se não houve consulta anterior na conexão ou se a consulta não atualizou um valor `AUTO_INCREMENT`.

Apenas declarações emitidas com a conexão atual afetam o valor de retorno. O valor não é afetado por declarações emitidas usando outras conexões ou clientes.

> Nota:

> Se o número é maior que o máximo valor de um inteiro, ele será retornado como uma string.

### Exemplos

Exemplo #1 Exemplo de $mysqli->insert_id

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $mysqli->query("CREATE TABLE myCity LIKE City");

    $query = "INSERT INTO myCity VALUES (NULL, 'Stuttgart', 'DEU', 'Stuttgart', 617000)";
    $mysqli->query($query);

    printf("Novo registro tem ID %d.\n", $mysqli->insert_id);

    /* deleta a tabela */
    $mysqli->query("DROP TABLE myCity");

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    mysqli_query($link, "CREATE TABLE myCity LIKE City");

    $query = "INSERT INTO myCity VALUES (NULL, 'Stuttgart', 'DEU', 'Stuttgart', 617000)";
    mysqli_query($link, $query);

    printf("Novo registro tem ID %d.\n", mysqli_insert_id($link));

    /* deleta a tabela */
    mysqli_query($link, "DROP TABLE myCity");

Os exemplos acima produzirão:

    Novo registro tem ID 1.

# mysqli::kill

# mysqli_kill

(PHP 5, PHP 7, PHP 8)

mysqli::kill -- mysqli_kill — Solicita ao servidor o encerramento de um thread do MySQL

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.4.0. O uso desta função é fortemente desencorajado.

### Descrição

Estilo orientado a objetos

#[\Deprecated]
public function mysqli::kill(int `$process_id`): bool

Estilo procedural

#[\Deprecated]
function mysqli_kill(mysqli `$mysql`, int `$process_id`): bool

Esta função é usada para solicitar ao servidor o encerramento de uma thread do MySQL especificada pelo parâmetro `process_id`. Este valor deve ser recuperado chamando a função mysqli_thread_id().

Para encerrar a execução de uma consulta, você deve usar o comando SQL `KILL QUERY processid`.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | O método mysqli::kill() e a função mysqli_kill() foram descontinuados. No lugar deles, deve ser usado o comando SQL `KILL`.

### Exemplos

Exemplo #1 Exemplo de mysqli::kill()

Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* verifica conexão */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    /* determina o identificador da thread */
    $thread_id = $mysqli->thread_id;

    /* Encerra a conexão */
    $mysqli->kill($thread_id);

    /* Isto deve gerar um erro */
    if (!$mysqli->query("CREATE TABLE myCity LIKE City")) {
        printf("Error: %s\n", $mysqli->error);
        exit;
    }

    /* fecha a conexão */
    $mysqli->close();
    ?>

Estilo procedural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* verifica conexão */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    /* determina o identificador da thread */
    $thread_id = mysqli_thread_id($link);

    /* Encerra a conexão */
    mysqli_kill($link, $thread_id);

    /* Isto deve gerar um erro */
    if (!mysqli_query($link, "CREATE TABLE myCity LIKE City")) {
        printf("Error: %s\n", mysqli_error($link));
        exit;
    }

    /* fecha a conexão */
    mysqli_close($link);
    ?>

Os exemplos acima produzirão:

    Error: MySQL server has gone away

### Veja Também

- mysqli_thread_id() - Retorna o ID da thread para a conexão atual

# mysqli::more_results

# mysqli_more_results

(PHP 5, PHP 7, PHP 8)

mysqli::more_results -- mysqli_more_results — Verifica se há mais algum resultado de uma consulta múltipla

### Descrição

Estilo orientado a objetos

public function mysqli::more_results(): bool

Estilo procedural

function mysqli_more_results(mysqli `$mysql`): bool

Indica se um ou mais conjuntos de resultados estão disponíveis de uma chamada anterior a mysqli_multi_query().

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()

### Valor Retornado

Retorna `true` se um ou mais conjuntos de resultados (incluindo erros) estão disponíveis de uma chamada anterior a mysqli_multi_query(), caso contrário `false`.

### Exemplos

Consulte mysqli_multi_query().

### Veja Também

- mysqli_multi_query() - Executa uma ou mais consultas no banco de dados
- mysqli_next_result() - Prepara o próximo resultado de multi_query
- mysqli_store_result() - Transfere um conjunto de resultados da última consulta
- mysqli_use_result() - Iniciar uma recuperação de conjunto de resultados

# mysqli::multi_query

# mysqli_multi_query

(PHP 5, PHP 7, PHP 8)

mysqli::multi_query -- mysqli_multi_query — Executa uma ou mais consultas no banco de dados

### Descrição

Estilo orientado a objetos

public function mysqli::multi_query(string `$query`): bool

Estilo procedural

function mysqli_multi_query(mysqli `$mysql`, string `$query`): bool

Executa uma ou múltiplas consultas que são concatenadas com ponto-e-vírgula.

Aviso

# Alerta de segurança: injeção de SQL

Se a consulta contiver qualquer entrada de variável, instruções preparadas parametrizadas devem ser usadas. Alternativamente, os dados devem ser formatados corretamente e todas as strings devem ser escapadas usando a função mysqli_real_escape_string().

Consultas são enviadas em uma chamada única ao banco de dados e processadas sequencialmente. mysqli_multi_query() espera pela finalização da primeira consulta antes de retornar o controle ao PHP. Enquanto isso, o servidor MySQL continuará processando as consultas remanescentes de forma assíncrona e disponibilizará os resultados para busca.

É recomendado usar do-while para processar consultas múltiplas. A conexão estará ocupada enquanto todas as consultas tiverem concluído e seus resultados enviados ao PHP. Nenhuma outra declaração pode ser emitida na mesma conexão até que todas as consultas sejam processadas. Para proceder à consulta seguinte, use mysqli_next_result(). Se a consulta seguinte ainda não estiver pronta, mysqli esperará pela resposta do servidor MySQL. Para verificar se há mais resultados, use mysqli_more_results().

Para consultas que produzem um conjnto de resultados, como em `SELECT, SHOW, DESCRIBE` ou `EXPLAIN`, mysqli_use_result() ou mysqli_store_result() podem ser usadas para recuperar o conjunto. Para consultas que não produzem um conjunto de resultados, as mesmas funções podem ser usadas para recuperar informação como o número de linhas afetadas.

Dica

Executar declarações `CALL` para procedimentos armazenados pode produzir múltiplos conjuntos de resultados. Se o procedimento armazenado contiver declarações `SELECT`, os conjuntos são retornados na ordem em que são produzidos enquanto o procedimento é executado. Em geral, a função que chama não sabe quantos conjuntos de resultados um procedimento irá retornar e deve estar preparada para recuperar múltiplos conjuntos. O resultado final do procedimento é um resultado de estado que não inclui nenhum conjunto. O estado indica se o procedimento teve sucesso ou se ocorreu um erro.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()
`query`

  Uma string contendo as consultas que serão executadas. Consultas múltiplas devem ser separadas por ponto-e-vírgula (;).

### Valor Retornado

Retorna `false` se a primeira consulta falhar. Para recuperar erros subsequentes de outras consultas, deve-se chamar mysqli_next_result() primeiro.

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Exemplos

Exemplo #1 Exemplo de mysqli::multi_query()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT CURRENT_USER();";
    $query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

    /* executa as consultas múltiplas */
    $mysqli->multi_query($query);
    do {
        /* armazena o conjunto de resultados no PHP */
        if ($result = $mysqli->store_result()) {
            while ($row = $result->fetch_row()) {
                printf("%s\n", $row[0]);
            }
        }
        /* divisor de impressão */
        if ($mysqli->more_results()) {
            printf("-----------------\n");
        }
    } while ($mysqli->next_result());

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT CURRENT_USER();";
    $query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

    /* executa as consultas múltiplas */
    mysqli_multi_query($link, $query);
    do {
        /* armazena o conjunto de resultados no PHP */
        if ($result = mysqli_store_result($link)) {
            while ($row = mysqli_fetch_row($result)) {
                printf("%s\n", $row[0]);
            }
        }
        /* divisor de impressão */
        if (mysqli_more_results($link)) {
            printf("-----------------\n");
        }
    } while (mysqli_next_result($link));

Os exemplos acima produzirão algo semelhante a:

    my_user@localhost
    -----------------
    Amersfoort
    Maastricht
    Dordrecht
    Leiden
    Haarlemmermeer

### Veja Também

- mysqli_query() - Executa uma consulta no banco de dados
- mysqli_use_result() - Iniciar uma recuperação de conjunto de resultados
- mysqli_store_result() - Transfere um conjunto de resultados da última consulta
- mysqli_next_result() - Prepara o próximo resultado de multi_query
- mysqli_more_results() - Verifica se há mais algum resultado de uma consulta múltipla

# mysqli::next_result

# mysqli_next_result

(PHP 5, PHP 7, PHP 8)

mysqli::next_result -- mysqli_next_result — Prepara o próximo resultado de multi_query

### Descrição

Estilo orientado a objetos

public function mysqli::next_result(): bool

Estilo procedural

function mysqli_next_result(mysqli `$mysql`): bool

Prepara o próximo conjunto de resultado de uma chamada anterior a mysqli_multi_query() que pode ser recuperado por mysqli_store_result() ou mysqli_use_result().

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha. Também retorna `false` se a declaração seguinte resultou em erro, diferentemente de mysqli_more_results().

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Exemplos

Consulte mysqli_multi_query().

### Veja Também

- mysqli_multi_query() - Executa uma ou mais consultas no banco de dados
- mysqli_more_results() - Verifica se há mais algum resultado de uma consulta múltipla
- mysqli_store_result() - Transfere um conjunto de resultados da última consulta
- mysqli_use_result() - Iniciar uma recuperação de conjunto de resultados

# mysqli::options

# mysqli_options

(PHP 5, PHP 7, PHP 8)

mysqli::options -- mysqli_options — Define opções

### Descrição

Estilo orientado a objetos

public function mysqli::options(int `$option`, string|int `$value`): bool

Estilo procedural

function mysqli_options(mysqli `$mysql`, int `$option`, string|int `$value`): bool

Usado para definir opções extras de conexão e afetar o comportamento de uma conexão.

Esta função pode ser chamada várias vezes para definir várias opções.

mysqli_options() deve ser chamado depois de mysqli_init() e antes de mysqli_real_connect().

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()
`option`

  A opção que você deseja definir. Pode ser um dos seguintes valores:

  Valid options
  Name | Description
  --- | ---
  `MYSQLI_OPT_CONNECT_TIMEOUT` | Tempo limite de conexão em segundos
  `MYSQLI_OPT_READ_TIMEOUT` | Tempo limite do resultado da execução do comando em segundos. Disponível a partir do PHP 7.2.0.
  `MYSQLI_OPT_LOCAL_INFILE` | Ativar/desativar o uso de `LOAD LOCAL INFILE`
  `MYSQLI_OPT_LOAD_DATA_LOCAL_DIR` | Diretório a ser usado para `LOAD DATA LOCAL INFILE`.
  `MYSQLI_INIT_COMMAND` | Comando para executar depois ao conectar ao servidor MySQL
  `MYSQLI_SET_CHARSET_NAME` | O conjunto de caracteres a ser definido como padrão..
  `MYSQLI_READ_DEFAULT_FILE` | Lê as opções do arquivo de opções nomeadas em vez de my.cnf Não suportado por mysqlnd.
  `MYSQLI_READ_DEFAULT_GROUP` | Leia as opções do grupo nomeado de my.cnf ou o arquivo especificado com `MYSQL_READ_DEFAULT_FILE`. Não suportado pelo mysqlnd.
  `MYSQLI_SERVER_PUBLIC_KEY` | Arquivo de chave pública RSA usado com a autenticação baseada em SHA-256.
  `MYSQLI_OPT_NET_CMD_BUFFER_SIZE` | O tamanho do buffer interno de comando/rede. Válido apenas para mysqlnd.
  `MYSQLI_OPT_NET_READ_BUFFER_SIZE` | Tamanho máximo do bloco de leitura em bytes ao ler o corpo de um pacote de comando do MySQL. Válido apenas para mysqlnd.
  `MYSQLI_OPT_INT_AND_FLOAT_NATIVE` | Converte colunas de números inteiros e pontos flutuantes de volta para números PHP ao usar instruções não preparadas. Válido apenas para mysqlnd.
  `MYSQLI_OPT_SSL_VERIFY_SERVER_CERT` | Informa se o certificado do servidor deve ser verificado.
  `MYSQLI_OPT_CAN_HANDLE_EXPIRED_PASSWORDS` | Informa se o cliente deve aceitar senhas expiradas.
  `1` | Informa se deve ser usada compressão na comunicação de rede.

`value`

  O valor da opção.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Exemplos

Veja mysqli_real_connect().

### Notas

> Nota: O MySQLnd sempre assume o conjunto de caracteres padrão do servidor. Este conjunto de caracteres é enviado durante a criação/autenticação da conexão e será usado pelo mysqlnd.A libmysqlclient usa o conjunto de caracteres padrão definido no arquivo my.cnf ou definido por uma chamada explícita a mysqli_options() antes de chamar mysqli_real_connect(), mas depois de chamar mysqli_init().

### Veja Também

- mysqli_init() - Inicializa o MySQLi e retorna um objeto a ser utilizado com mysqli_real_connect()
- mysqli_real_connect() - Abre uma conexão a um servidor MySQL

# mysqli::ping

# mysqli_ping

(PHP 5, PHP 7, PHP 8)

mysqli::ping -- mysqli_ping — Faz ping em uma conexão de servidor ou tenta reconectar se a conexão cair

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.4.0. O uso desta função é fortemente desencorajado.

### Descrição

Estilo orientado a objetos

#[\Deprecated]
public function mysqli::ping(): bool

Estilo procedural

#[\Deprecated]
function mysqli_ping(mysqli `$mysql`): bool

Verifica se a conexão com o servidor está funcionando. Se ele estiver inativo e a opção global mysqli.reconnect estiver habilitada, uma reconexão automática será tentada.

> Nota: A configuração mysqli.reconnect do php.ini é ignorada pelo driver mysqlnd, então a reconexão automática nunca é tentada.

Esta função pode ser utilizada por clientes que ficam muito tempo ociosos, para verificar se o servidor encerrou a conexão e reconectar se necessário.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | O método mysqli::ping() e a função mysqli_ping() foram descontinuados. O recurso de `reconnect` (reconexão) não está disponível a partir do PHP 8.2.0, tornando esta função obsoleta.

### Exemplos

Exemplo #1 Exemplo de mysqli::ping()

Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "meu_usuario", "minha_senha", "mundo");

    /* verifica a conexão */
    if ($mysqli->connect_errno) {
        printf("Falha na conexão: %s\n", $mysqli->connect_error);
        exit();
    }

    /* verifica se o servidor está ativo */
    if ($mysqli->ping()) {
        printf ("Nossa conexão está ok!\n");
    } else {
        printf ("Erro: %s\n", $mysqli->error);
    }

    /* encerra a conexão */
    $mysqli->close();
    ?>

Estilo procedural

    <?php
    $link = mysqli_connect("localhost", "meu_usuario", "minha_senha", "mundo");

    /* verifica a conexão */
    if (mysqli_connect_errno()) {
        printf("Falha na conexão: %s\n", mysqli_connect_error());
        exit();
    }

    /* verifica se o servidor está ativo */
    if (mysqli_ping($link)) {
        printf ("Nossa conexão está ok!\n");
    } else {
        printf ("Erro: %s\n", mysqli_error($link));
    }

    /* encerra a conexão */
    mysqli_close($link);
    ?>

Os exemplos acima produzirão:

    Nossa conexão está ok!

# mysqli::poll

# mysqli_poll

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli::poll -- mysqli_poll — Sondagem de conexões

### Descrição

Estilo orientado a objetos

public static function mysqli::poll(
?array `&$read`,
?array `&$error`,
array `&$reject`,
int `$seconds`,
int `$microseconds` = 0
): int|false

Estilo procedural

function mysqli_poll(
?array `&$read`,
?array `&$error`,
array `&$reject`,
int `$seconds`,
int `$microseconds` = 0
): int|false

Faz sondagem de conexões. Este método pode ser usado como static.

> Nota:

> Disponível apenas com o mysqlnd.

### Parâmetros

`read`

  Lista de conexões a verificar por resultados marcantes que possam ser lidos.

`error`

  Lista de conexões nas quais um erro ocorreu, por exemplo, falha na consulta ou conexão perdida.

`reject`

  Lista de conexões rejeitadas porque nenhuma consulta assícrona foi executada para que a função pudesse sondar os resultados.

`seconds`

  Número máximo de segundos a esperar, deve ser não negativo.

`microseconds`

  Número máximo de microssegundos a esperar, deve ser não negativo.

### Valor Retornado

Retorna o número de conexões prontas em caso de sucesso, `false` caso contrário.

### Erros/Exceções

Uma exceção ValueError é lançada quando nem o parâmetro `read` nem o parâmetro `error` são passados.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Agora lança uma exceção ValueError quando nem o parâmetro `read` nem o parâmetro `error` são passados.

### Exemplos

Exemplo #1 Um exemplo de mysqli_poll()

    <?php
    $link1 = mysqli_connect();
    $link1->query("SELECT 'test'", MYSQLI_ASYNC);
    $all_links = array($link1);
    $processed = 0;
    do {
        $links = $errors = $reject = array();
        foreach ($all_links as $link) {
            $links[] = $errors[] = $reject[] = $link;
        }
        if (!mysqli_poll($links, $errors, $reject, 1)) {
            continue;
        }
        foreach ($links as $link) {
            if ($result = $link->reap_async_query()) {
                print_r($result->fetch_row());
                if (is_object($result))
                    mysqli_free_result($result);
            } else die(sprintf("MySQLi Error: %s", mysqli_error($link)));
            $processed++;
        }
    } while ($processed < count($all_links));
    ?>

O exemplo acima produzirá:

    Array
    (
        [0] => test
    )

### Veja Também

- mysqli_query() - Executa uma consulta no banco de dados
- mysqli_reap_async_query() - Obtenha o resultado da consulta assíncrona

# mysqli::prepare

# mysqli_prepare

(PHP 5, PHP 7, PHP 8)

mysqli::prepare -- mysqli_prepare — Prepara uma instrução SQL para execução

### Descrição

Estilo orientado a objetos

public function mysqli::prepare(string `$query`): mysqli_stmt|false

Estilo procedural

function mysqli_prepare(mysqli `$mysql`, string `$query`): mysqli_stmt|false

Prepara a consulta SQL e retorna um identificador de instrução a ser usado para outras operações na instrução. A consulta deve consistir em uma única instrução SQL.

O modelo de instrução pode conter zero ou mais marcadores de parâmetro de ponto de interrogação (`?`) também chamados de espaços reservados. Os marcadores de parâmetro devem ser vinculados às variáveis do aplicativo usando mysqli_stmt_bind_param() antes de executar a instrução.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()
`query`

  A consulta, como uma string. Deve consistir em uma única instrução SQL.

  A instrução SQL pode conter zero ou mais marcadores de parâmetro representados por caracteres de ponto de interrogação (`?`) nas posições apropriadas.

  > Nota:

  > Os marcadores são válidos apenas em determinados locais nas instruções SQL. Por exemplo, eles são permitidos na lista `VALUES()` de uma instrução `INSERT` (para especificar valores de coluna para uma linha) ou em uma comparação com uma coluna em uma cláusula `WHERE` para especificar um valor de comparação. No entanto, eles não são permitidos para identificadores (como nomes de tabelas ou colunas).

### Valor Retornado

mysqli_prepare() retorna um objeto de instrução ou `false` se ocorreu um erro.

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Exemplos

Exemplo #1 Exemplo de mysqli::prepare()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $city = "Amersfoort";

    /* criar uma declaração preparada */
    $stmt = $mysqli->prepare("SELECT District FROM City WHERE Name=?");

    /* parâmetros de ligação para marcadores */
    $stmt->bind_param("s", $city);

    /* executar consulta */
    $stmt->execute();

    /* vincular variáveis de resultado */
    $stmt->bind_result($district);

    /* buscar valor */
    $stmt->fetch();

    printf("%s está no distrito %s\n", $city, $district);

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $city = "Amersfoort";

    /* criar uma declaração preparada */
    $stmt = mysqli_prepare($link, "SELECT District FROM City WHERE Name=?");

    /* parâmetros de ligação para marcadores */
    mysqli_stmt_bind_param($stmt, "s", $city);

    /* executar consulta */
    mysqli_stmt_execute($stmt);

    /* vincular variáveis de resultado */
    mysqli_stmt_bind_result($stmt, $district);

    /* buscar valor */
    mysqli_stmt_fetch($stmt);

    printf("%s está no distrito %s\n", $city, $district);

Os exemplos acima produzirão:

    Amersfoort está no distrito de Utrecht

### Veja Também

- mysqli_stmt_execute() - Executa uma instrução preparada
- mysqli_stmt_fetch() - Recebe resultados de uma instrução preparada nas variáveis vinculadas
- mysqli_stmt_bind_param() - Liga variáveis a uma declaração preparada como parâmetros
- mysqli_stmt_bind_result() - Liga variáveis a uma declaração preparada para armazenamento de resultado
- mysqli_stmt_get_result() - Obtém um resultado de uma instrução preparada como um objeto mysqli_result
- mysqli_stmt_close() - Fecha uma instrução preparada

# mysqli::query

# mysqli_query

(PHP 5, PHP 7, PHP 8)

mysqli::query -- mysqli_query — Executa uma consulta no banco de dados

### Descrição

Estilo orientado a objetos

public function mysqli::query(string `$query`, int `$result_mode` = `MYSQLI_STORE_RESULT`): mysqli_result|bool

Estilo procedural

function mysqli_query(mysqli `$mysql`, string `$query`, int `$result_mode` = `MYSQLI_STORE_RESULT`): mysqli_result|bool

Executa uma `query` no banco de dados.

Aviso

# Alerta de segurança: injeção de SQL

Se a consulta contiver qualquer entrada de variável, instruções preparadas parametrizadas devem ser usadas. Alternativamente, os dados devem ser formatados corretamente e todas as strings devem ser escapadas usando a função mysqli_real_escape_string().

Para consultas não-DML (não INSERT, UPDATE ou DELETE), esta função é semelhante a chamar mysqli_real_query() seguido por mysqli_use_result() ou mysqli_store_result().

> Nota:

> No caso em que uma instrução é passada para mysqli_query() que é maior que `max_allowed_packet` do servidor, os códigos de erro retornados são diferentes dependendo se você está usando MySQL Native Driver (`mysqlnd`)ou MySQL Client Library (`libmysqlclient`). O comportamento é o seguinte:

> - `mysqlnd` no Linux retorna um código de erro de 1153. A mensagem de erro significa que recebi um pacote maior que `max_allowed_packet` bytes.

> - `mysqlnd` no Windows retorna um código de erro 2006. Esta mensagem de erro significa que o server has gone away.

> - `libmysqlclient` em todas as plataformas retorna um código de erro 2006. Essa mensagem de erro significa que o servidor foi desativado.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()
`query`

  A string de consulta.

`result_mode`

  O modo de resultado pode ser uma das 3 constantes que indicam como o resultado será retornado do servidor MySQL.

  `MYSQLI_STORE_RESULT` (padrão) - retorna um objeto mysqli_resultcom conjunto de resultados em buffer.

  `MYSQLI_USE_RESULT` - retorna um objeto mysqli_result com conjunto de resultados sem buffer. Enquanto houver registros pendentes esperando para serem buscados, a linha de conexão estará ocupada e todas as chamadas subseqüentes retornarão o erro `Commands out of sync`. Para evitar o erro, todos os registros devem ser buscados no servidor ou o conjunto de resultados deve ser descartado chamando mysqli_free_result().

  `MYSQLI_ASYNC` (disponível com mysqlnd) - a consulta é executada de forma assíncrona e nenhum conjunto de resultados é retornado imediatamente. mysqli_poll() é então usado para obter resultados de tais consultas. Usado em combinação com a constante `MYSQLI_STORE_RESULT` ou `MYSQLI_USE_RESULT`.

### Valor Retornado

Retorna `false` em caso de falha. Para consultas bem-sucedidas que produzem um conjunto de resultados, como `SELECT, SHOW, DESCRIBE` ou `EXPLAIN`, mysqli_query() retornará um objeto mysqli_result. Para outras consultas bem-sucedidas, mysqli_query() retornará `true`.

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Exemplos

Exemplo #1 Exemplo de mysqli::query()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Criar tabela não retorna um conjunto de resultados */
    $mysqli->query("CREATE TEMPORARY TABLE myCity LIKE City");
    printf("Tabela myCity criada com sucesso.\n");

    /* Consultas selecionadas retornam um conjunto de resultados */
    $result = $mysqli->query("SELECT Name FROM City LIMIT 10");
    printf("Select retornou %d linhas.\n", $result->num_rows);

    /* Se tivermos que recuperar uma grande quantidade de dados, usamos MYSQLI_USE_RESULT */
    $result = $mysqli->query("SELECT * FROM City", MYSQLI_USE_RESULT);

    /* Observe que não podemos executar nenhuma função que interaja com o
    servidor até que todos os registros tenham sido totalmente recuperados ou o resultado
    conjunto foi fechado. Todas as chamadas retornarão um erro 'fora de sincronia' */
    $mysqli->query("SET @a:='isso não vai funcionar'");

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Criar tabela não retorna um conjunto de resultados */
    mysqli_query($link, "CREATE TEMPORARY TABLE myCity LIKE City");
    printf("Tabela myCity criada com sucesso.\n");

    /* Consultas de seleção retornam um conjunto de resultados */
    $result = mysqli_query($link, "SELECT Name FROM City LIMIT 10");
    printf("Select retornou %d linhas.\n", mysqli_num_rows($result));

    /* Se tivermos que recuperar uma grande quantidade de dados, usamos MYSQLI_USE_RESULT */
    $result = mysqli_query($link, "SELECT * FROM City", MYSQLI_USE_RESULT);

    /* Observe que não podemos executar nenhuma função que interaja com o
    servidor até que todos os registros tenham sido totalmente recuperados ou o resultado
    conjunto foi fechado. Todas as chamadas retornarão um erro 'fora de sincronia' */
    mysqli_query($link, "SET @a:='isso não vai funcionar'");

Os exemplos acima produzirão algo semelhante a:

    Tabela myCity criada com sucesso.
    Select retornou 10 linhas.

    Fatal error: Uncaught mysqli_sql_exception: Commands out of sync; you can't run this command now in...

### Veja Também

- mysqli_execute_query() - Prepara, vincula parâmetros e executa a instrução SQL
- mysqli_real_query() - Executa uma consulta SQL
- mysqli_multi_query() - Executa uma ou mais consultas no banco de dados
- mysqli_prepare() - Prepara uma instrução SQL para execução
- mysqli_free_result() - Libera memória associada a um resultado

# mysqli::real_connect

# mysqli_real_connect

(PHP 5, PHP 7, PHP 8)

mysqli::real_connect -- mysqli_real_connect — Abre uma conexão a um servidor MySQL

### Descrição

Estilo orientado a objetos

public function mysqli::real_connect(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`,
int `$flags` = 0
): bool

Estilo procedural

function mysqli_real_connect(
mysqli `$mysql`,
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`,
int `$flags` = 0
): bool

Abre uma conexão a um servidor de banco de dados MySQL com várias opções de conexão.

Esta função difere de mysqli_connect():

- mysqli_real_connect() precisa de um objeto válido que deve ser criado por mysqli_init().

- Existe um parâmetro `flags`.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()
`hostname`

  Pode ser um nome de host ou um endereço IP. Ao passar `null`, o valor é recuperado de mysqli.default_host. Quando possível, serão usados pipes em vez do protocolo TCP/IP. O protocolo TCP/IP é usado se um nome de host e um número de porta forem fornecidos juntos, por ex. `localhost:3308`.

`username`

  O nome de usuário do MySQL, ou `null` para assumir o nome de usuário com base na opção ini mysqli.default_user.

`password`

  A senha do MySQL, ou `null` para assumir a senha com base na opção ini mysqli.default_pw.

`database`

  O banco de dados padrão a ser usado ao realizar consultas ou `null`.

`port`

  O número da porta para tentar conectar ao servidor MySQL ou `null` para assumir a porta com base na opção mysqli.default_port.

`socket`

  O socket ou pipe nomeado que deve ser usado ou `null` para assumir o socket com base na opção ini mysqli.default_socket.

  > Nota:

  > A especificação do parâmetro `socket` não determinará explicitamente o tipo de conexão a ser usada ao conectar-se ao servidor MySQL. A forma como a conexão é feita com o banco de dados MySQL é determinada pelo parâmetro `hostname`.

`flags`

  Com o parâmetro `flags`, pode-se definir diferentes opções de conexão:

  Opções suportadas
  Nome | Descrição
  --- | ---
  `MYSQLI_CLIENT_COMPRESS` | Usa protocolo de compressão
  `MYSQLI_CLIENT_FOUND_ROWS` | Retorna o número de linhas correspondentes, não o número de linhas afetadas
  `MYSQLI_CLIENT_IGNORE_SPACE` | Permite espaços após os nomes das funções. Faz com que todos os nomes de funções sejam palavras reservadas.
  `MYSQLI_CLIENT_INTERACTIVE` | Permite segundos de `interactive_timeout` (em vez de segundos de `wait_timeout`) de inatividade antes de fechar a conexão
  `MYSQLI_CLIENT_SSL` | Usa SSL (criptografia)
  `MYSQLI_CLIENT_SSL_DONT_VERIFY_SERVER_CERT` | Como `MYSQLI_CLIENT_SSL`, mas desabilita a validação do certificado SSL fornecido. Isso é apenas para instalações usando o driver nativo do MySQL e MySQL 5.6 ou posterior.

  > Nota:

  > Por motivos de segurança, a opção `MULTI_STATEMENT` não é suportado no PHP. Se for desejado executar várias consultas, use a função mysqli_multi_query().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Registro de Alterações

Versão | Descrição
--- | ---
7.4.0 | Todos os parâmetros agora são anuláveis.

### Exemplos

Exemplo #1 Exemplo de mysqli::real_connect()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_init();

    $mysqli->options(MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0');
    $mysqli->options(MYSQLI_OPT_CONNECT_TIMEOUT, 5);

    $mysqli->real_connect('localhost', 'my_user', 'my_password', 'my_db', null, null, MYSQLI_CLIENT_COMPRESS|MYSQLI_CLIENT_FOUND_ROWS);

    echo 'Sucesso... ' . $mysqli->host_info . "\n";

Estilo orientado a objetos ao estender a classe mysqli

    <?php

    class foo_mysqli extends mysqli {
        public function __construct($host, $user, $pass, $db)
        {
            parent::__construct();

            parent::options(MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0');
            parent::options(MYSQLI_OPT_CONNECT_TIMEOUT, 5);

            parent::real_connect($host, $user, $pass, $db, null, null, MYSQLI_CLIENT_COMPRESS|MYSQLI_CLIENT_FOUND_ROWS);
        }
    }

    $db = new foo_mysqli('localhost', 'my_user', 'my_password', 'my_db');

    echo 'Sucesso... ' . $db->host_info . "\n";

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_init();

    mysqli_options($link, MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0');
    mysqli_options($link, MYSQLI_OPT_CONNECT_TIMEOUT, 5);

    mysqli_real_connect($link, 'localhost', 'my_user', 'my_password', 'my_db', null, null, MYSQLI_CLIENT_COMPRESS|MYSQLI_CLIENT_FOUND_ROWS);

    echo 'Sucesso... ' . mysqli_get_host_info($link) . "\n";

Os exemplos acima produzirão:

    Sucesso... MySQL host info: localhost via TCP/IP

### Notas

> Nota: O MySQLnd sempre assume o conjunto de caracteres padrão do servidor. Este conjunto de caracteres é enviado durante a criação/autenticação da conexão e será usado pelo mysqlnd.A libmysqlclient usa o conjunto de caracteres padrão definido no arquivo my.cnf ou definido por uma chamada explícita a mysqli_options() antes de chamar mysqli_real_connect(), mas depois de chamar mysqli_init().

### Veja Também

- mysqli_connect() - Sinônimo de mysqli::__construct
- mysqli_init() - Inicializa o MySQLi e retorna um objeto a ser utilizado com mysqli_real_connect()
- mysqli_options() - Define opções
- mysqli_ssl_set() - Usado para estabelecer conexões seguras usando SSL
- mysqli_close() - Fecha uma conexão ao banco de dados previamente aberta

# mysqli::real_escape_string

# mysqli_real_escape_string

(PHP 5, PHP 7, PHP 8)

mysqli::real_escape_string -- mysqli_real_escape_string — Escape caracteres especiais em uma string para uso em uma instrução SQL, levando em consideração o conjunto de caracteres atual da conexão

### Descrição

Estilo orientado a objetos

public function mysqli::real_escape_string(string `$string`): string

Estilo procedural

function mysqli_real_escape_string(mysqli `$mysql`, string `$string`): string

Esta função é usada para criar uma string SQL legal que você pode usar em uma instrução SQL. A string fornecida é codificada para produzir uma string SQL com escape, levando em consideração o conjunto de caracteres atual da conexão.

Cuidado

# Segurança: o conjunto de caracteres padrão

O conjunto de caracteres deve ser definido no nível do servidor ou com a função API mysqli_set_charset() para que afete mysqli_real_escape_string(). Consulte a seção de conceitos sobre conjuntos de caracteres para obter mais informações.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()
`string`

  A string a ser escapada.

  Os caracteres codificados são `NUL (ASCII 0)`, `\n`, `\r`, `\`, `'`, `"`, e ``CTRL`+`Z``.

### Valor Retornado

Retorna uma string com escape.

### Exemplos

Exemplo #1 Exemplo de mysqli::real_escape_string()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $city = "'s-Hertogenbosch";

    /* esta consulta com escape $city funcionará */
    $query = sprintf("SELECT CountryCode FROM City WHERE name='%s'",
    $mysqli->real_escape_string($city));
    $result = $mysqli->query($query);
    printf("Select retornou %d linhas.\n", $result->num_rows);

    /* esta consulta falhará, porque não escapamos de $city */
    $query = sprintf("SELECT CountryCode FROM City WHERE name='%s'", $city);
    $result = $mysqli->query($query);

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $city = "'s-Hertogenbosch";

    /* esta consulta com escape $city funcionará */
    $query = sprintf("SELECT CountryCode FROM City WHERE name='%s'",
    mysqli_real_escape_string($mysqli, $city));
    $result = mysqli_query($mysqli, $query);
    printf("Select retornou %d linhas.\n", mysqli_num_rows($result));

    /* esta consulta falhará, porque não escapamos de $city*/
    $query = sprintf("SELECT CountryCode FROM City WHERE name='%s'", $city);
    $result = mysqli_query($mysqli, $query);

Os exemplos acima produzirão algo semelhante a:

    Select retornou 1 linhas.

    Fatal error: Uncaught mysqli_sql_exception: You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 's-Hertogenbosch'' at line 1 in...

### Veja Também

- mysqli_set_charset() - Define o conjunto de caracteres do cliente

# mysqli::real_query

# mysqli_real_query

(PHP 5, PHP 7, PHP 8)

mysqli::real_query -- mysqli_real_query — Executa uma consulta SQL

### Descrição

Estilo orientado a objetos

public function mysqli::real_query(string `$query`): bool

Estilo procedural

function mysqli_real_query(mysqli `$mysql`, string `$query`): bool

Executa uma única consulta no banco de dados cujo resultado pode ser recuperado ou armazenado usando as funções mysqli_store_result() ou mysqli_use_result().

Aviso

# Alerta de segurança: injeção de SQL

Se a consulta contiver qualquer entrada de variável, instruções preparadas parametrizadas devem ser usadas. Alternativamente, os dados devem ser formatados corretamente e todas as strings devem ser escapadas usando a função mysqli_real_escape_string().

Para determinar se uma determinada consulta deve retornar um conjunto de resultados ou não, consulte mysqli_field_count().

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()
`query`

  A string de consulta.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Veja Também

- mysqli_query() - Executa uma consulta no banco de dados
- mysqli_store_result() - Transfere um conjunto de resultados da última consulta
- mysqli_use_result() - Iniciar uma recuperação de conjunto de resultados

# mysqli::reap_async_query

# mysqli_reap_async_query

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli::reap_async_query -- mysqli_reap_async_query — Obtenha o resultado da consulta assíncrona

### Descrição

Estilo orientado a objetos

public function mysqli::reap_async_query(): mysqli_result|bool

Estilo procedural

function mysqli_reap_async_query(mysqli `$mysql`): mysqli_result|bool

Obtenha o resultado da consulta assíncrona.

> Nota:

> Disponível apenas com o mysqlnd.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()

### Valor Retornado

Retorna `false` em caso de falha. Para consultas bem-sucedidas que produzem um conjunto de resultados, como `SELECT, SHOW, DESCRIBE` ou `EXPLAIN`, mysqli_reap_async_query() retornará um objeto mysqli_result. Para outras consultas bem-sucedidas, mysqli_reap_async_query() retornará `true`.

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Veja Também

- mysqli_poll() - Sondagem de conexões

# mysqli::refresh

# mysqli_refresh

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli::refresh -- mysqli_refresh — Atualiza

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.4.0. O uso desta função é fortemente desencorajado.

### Descrição

Estilo orientado a objetos

#[\Deprecated]
public function mysqli::refresh(int `$flags`): bool

Estilo procedural

#[\Deprecated]
function mysqli_refresh(mysqli `$mysql`, int `$flags`): bool

Libera tabelas ou caches ou redefine as informações do servidor de replicação.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()
`flags`

  As opções para atualizar, usando as constantes MYSQLI_REFRESH_* conforme documentado na documentação das MySQLi constantes.

  Veja também a documentação oficial do » MySQL Refresh.

### Valor Retornado

`true` se a atualização foi bem-sucedida, caso contrário, `false`

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | O método mysqli::refresh() e a função mysqli_refresh() foram descontinuados. No lugar deles, use o comando SQL `FLUSH`.

### Veja Também

- mysqli_poll() - Sondagem de conexões

# mysqli::release_savepoint

# mysqli_release_savepoint

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

mysqli::release_savepoint -- mysqli_release_savepoint — Remove o ponto de salvamento nomeado do conjunto de pontos de salvamento da transação atual

### Descrição

Estilo orientado a objetos

public function mysqli::release_savepoint(string `$name`): bool

Estilo procedural:

function mysqli_release_savepoint(mysqli `$mysql`, string `$name`): bool

Esta função é idêntica à execução de `$mysqli->query("RELEASE SAVEPOINT `$name`");`. Esta função não aciona commit ou rollback.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()
`name`

  O identificador do ponto de salvamento.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- mysqli_savepoint() - Define um ponto de salvamento de transação nomeado

# mysqli::rollback

# mysqli_rollback

(PHP 5, PHP 7, PHP 8)

mysqli::rollback -- mysqli_rollback — Reverte a transação atual

### Descrição

Estilo orientado a objetos

public function mysqli::rollback(int `$flags` = 0, ?string `$name` = `null`): bool

Estilo procedural

function mysqli_rollback(mysqli `$mysql`, int `$flags` = 0, ?string `$name` = `null`): bool

Reverte a transação atual para o banco de dados.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()
`flags`

  Uma máscara de bits das constantes `MYSQLI_TRANS_COR_*`.

`name`

  Se fornecido, então `ROLLBACK/*name*/` é executado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `name` agora é anulável.

### Exemplos

Veja o exemplo mysqli::begin_transaction().

### Notas

> Nota:

> Esta função não funciona com tipos de tabelas não transacionais (como MyISAM ou ISAM).

### Veja Também

- mysqli_begin_transaction() - Inicia uma transação
- mysqli_commit() - Grava a transação atual
- mysqli_autocommit() - Ativa ou desativa a gravação automática das modificações no banco de dados
- mysqli_release_savepoint() - Remove o ponto de salvamento nomeado do conjunto de pontos de salvamento da transação atual

# mysqli::savepoint

# mysqli_savepoint

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

mysqli::savepoint -- mysqli_savepoint — Define um ponto de salvamento de transação nomeado

### Descrição

Estilo orientado a objetos

public function mysqli::savepoint(string `$name`): bool

Estilo procedural:

function mysqli_savepoint(mysqli `$mysql`, string `$name`): bool

Esta função é idêntica à execução de `$mysqli->query("SAVEPOINT `$name`");`

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()
`name`

  O identificador do ponto de salvamento.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- mysqli_release_savepoint() - Remove o ponto de salvamento nomeado do conjunto de pontos de salvamento da transação atual

# mysqli::select_db

# mysqli_select_db

(PHP 5, PHP 7, PHP 8)

mysqli::select_db -- mysqli_select_db — Seleciona o banco de dados padrão para consultas de banco de dados

### Descrição

Estilo orientado a objetos

public function mysqli::select_db(string `$database`): bool

Estilo procedural

function mysqli_select_db(mysqli `$mysql`, string `$database`): bool

Seleciona o banco de dados padrão a ser usado ao executar consultas na conexão do banco de dados.

> Nota:

> Esta função deve ser usada apenas para alterar o banco de dados padrão para a conexão. Você pode selecionar o banco de dados padrão com o 4º parâmetro em mysqli_connect().

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()
`database`

  O nome do banco de dados.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Exemplos

Exemplo #1 Exemplo de mysqli::select_db()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    /* obtem o nome do banco de dados padrão atual */
    $result = $mysqli->query("SELECT DATABASE()");
    $row = $result->fetch_row();
    printf("O banco de dados padrão é %s.\n", $row[0]);

    /* altere o banco de dados padrão para "mundo" */
    $mysqli->select_db("world");

    /* obtem o nome do banco de dados padrão atual */
    $result = $mysqli->query("SELECT DATABASE()");
    $row = $result->fetch_row();
    printf("O banco de dados padrão é %s.\n", $row[0]);

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "test");

    /* obter o nome do banco de dados padrão atual */
    $result = mysqli_query($link, "SELECT DATABASE()");
    $row = mysqli_fetch_row($result);
    printf("O banco de dados padrão és %s.\n", $row[0]);

    /* altere o banco de dados padrão para "mundo" */
    mysqli_select_db($link, "world");

    /* obtem o nome do banco de dados padrão atual */
    $result = mysqli_query($link, "SELECT DATABASE()");
    $row = mysqli_fetch_row($result);
    printf("O banco de dados padrão é %s.\n", $row[0]);

Os exemplos acima produzirão:

    O banco de dados padrão é test.
    O banco de dados padrão é world.

### Veja Também

- mysqli_connect() - Sinônimo de mysqli::__construct
- mysqli_real_connect() - Abre uma conexão a um servidor MySQL

# mysqli::set_charset

# mysqli_set_charset

(PHP 5 >= 5.0.5, PHP 7, PHP 8)

mysqli::set_charset -- mysqli_set_charset — Define o conjunto de caracteres do cliente

### Descrição

Estilo orientado a objetos

public function mysqli::set_charset(string `$charset`): bool

Estilo procedural

function mysqli_set_charset(mysqli `$mysql`, string `$charset`): bool

Define o conjunto de caracteres a ser usado ao enviar dados de e para o servidor de banco de dados.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()
`charset`

  O conjunto de caracteres desejado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Exemplos

Exemplo #1 Exemplo de mysqli::set_charset()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    printf("Conjunto de caracteres inicial: %s\n", $mysqli->character_set_name());

    /* alterar conjunto de caracteres para utf8mb4 */
    $mysqli->set_charset("utf8mb4");

    printf("Conjunto de caracteres atual: %s\n", $mysqli->character_set_name());

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect('localhost', 'my_user', 'my_password', 'test');

    printf("Conjunto de caracteres inicial: %s\n", mysqli_character_set_name($link));

    /* alterar conjunto de caracteres para utf8mb4 */
    mysqli_set_charset($link, "utf8mb4");

    printf("Conjunto de caracteres atual: %s\n", mysqli_character_set_name($link));

Os exemplos acima produzirão algo semelhante a:

    Conjunto de caracteres inicial: latin1
    Conjunto de caracteres atual: utf8mb4

### Notas

> Nota:

> Esta é a maneira preferida de alterar o conjunto de caracteres. Usar mysqli_query() para configurá-lo (como `SET NAMES utf8`) não é recomendado. Consulte a seção de conceitos do conjunto de caracteres do MySQL para obter mais informações.

### Veja Também

- mysqli_character_set_name() - Retorna o conjunto de caracteres atual da conexão com o banco de dados
- mysqli_real_escape_string() - Escape caracteres especiais em uma string para uso em uma instrução SQL, levando em consideração o conjunto de caracteres atual da conexão
- Conceitos do conjunto de caracteres do MySQL
- » Lista de conjuntos de caracteres que o MySQL suporta

# mysqli::$sqlstate

# mysqli_sqlstate

(PHP 5, PHP 7, PHP 8)

mysqli::$sqlstate -- mysqli_sqlstate — Retorna o erro SQLSTATE da operação MySQL anterior

### Descrição

Estilo orientado a objetos

string $mysqli->sqlstate;

Estilo procedural

function mysqli_sqlstate(mysqli `$mysql`): string

Retorna uma string contendo o código de erro SQLSTATE para o último erro. O código de erro consiste em cinco caracteres. `'00000'` significa nenhum erro. Os valores são especificados por ANSI SQL e ODBC. Para obter uma lista de valores possíveis, consulte » http://dev.mysql.com/doc/mysql/en/error-handling.html.

> Nota:

> Observe que nem todos os erros do MySQL ainda estão mapeados para SQLSTATE. O valor `HY000` (erro geral) é usado para erros não mapeados.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()

### Valor Retornado

Retorna uma string contendo o código de erro SQLSTATE para o último erro. O código de erro consiste em cinco caracteres. `'00000'` significa nenhum erro.

### Exemplos

Exemplo #1 Exemplo de $mysqli->sqlstate

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Table City já existe, então devemos receber um erro */
    try {
        $mysqli->query("CREATE TABLE City (ID INT, Name VARCHAR(30))");
    } catch (mysqli_sql_exception) {
        printf("Erro - SQLSTATE %s.\n", $mysqli->sqlstate);
    }

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Table City já existe, então devemos receber um erro */
    try {
        mysqli_query($link, "CREATE TABLE City (ID INT, Name VARCHAR(30))");
    } catch (mysqli_sql_exception) {
        printf("Erro - SQLSTATE %s.\n", mysqli_sqlstate($link));
    }

Os exemplos acima produzirão:

    Erro - SQLSTATE 42S01.

### Veja Também

- mysqli_errno() - Retorna o código de erro para a chamada de função mais recente
- mysqli_error() - Retorna uma string descrevendo o último erro

# mysqli::ssl_set

# mysqli_ssl_set

(PHP 5, PHP 7, PHP 8)

mysqli::ssl_set -- mysqli_ssl_set — Usado para estabelecer conexões seguras usando SSL

### Descrição

Estilo orientado a objetos

public function mysqli::ssl_set(
?string `$key`,
?string `$certificate`,
?string `$ca_certificate`,
?string `$ca_path`,
?string `$cipher_algos`
): true

Estilo procedural

function mysqli_ssl_set(
mysqli `$mysql`,
?string `$key`,
?string `$certificate`,
?string `$ca_certificate`,
?string `$ca_path`,
?string `$cipher_algos`
): true

Usado para estabelecer conexões seguras usando SSL. Deve ser chamado antes de mysqli_real_connect(). Esta função não faz nada, a menos que o suporte OpenSSL esteja ativado.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()
`key`

  O nome do caminho para o arquivo de chave.

`certificate`

  O nome do caminho para o arquivo de certificado.

`ca_certificate`

  O nome do caminho para o arquivo de autoridade de certificação.

`ca_path`

  O nome do caminho para um diretório que contém certificados SSL CA confiáveis no formato PEM.

`cipher_algos`

  Uma lista de cifras permitidas a serem usadas para criptografia SSL.

### Valor Retornado

Sempre retorna `true`. Se a configuração do SSL estiver incorreta, mysqli_real_connect() retornará um erro quando você tentar se conectar.

### Veja Também

- mysqli_options() - Define opções
- mysqli_real_connect() - Abre uma conexão a um servidor MySQL

# mysqli::stat

# mysqli_stat

(PHP 5, PHP 7, PHP 8)

mysqli::stat -- mysqli_stat — Obtém o status atual do sistema

### Descrição

Estilo orientado a objetos

public function mysqli::stat(): string|false

Estilo procedural

function mysqli_stat(mysqli `$mysql`): string|false

mysqli_stat() retorna uma string contendo informações semelhantes àquelas fornecidas pelo comando 'mysqladmin status'. Isso inclui o tempo de atividade em segundos e o número de threads em execução, perguntas, recarregamentos e tabelas abertas.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()

### Valor Retornado

Uma string que descreve o status do servidor. `false` se ocorreu um erro.

### Exemplos

Exemplo #1 Exemplo de mysqli::stat()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    printf ("Status do sistema: %s\n", $mysqli->stat());

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    printf("System status: %s\n", mysqli_stat($link));

Os exemplos acima produzirão:

    Status do sistema: Uptime: 272  Threads: 1  Questions: 5340  Slow queries: 0
    Opens: 13  Flush tables: 1  Open tables: 0  Queries per second avg: 19.632
    Memory in use: 8496K  Max memory used: 8560K

### Veja Também

- mysqli_get_server_info() - Retorna a versão do servidor MySQL

# mysqli::stmt_init

# mysqli_stmt_init

(PHP 5, PHP 7, PHP 8)

mysqli::stmt_init -- mysqli_stmt_init — Inicializa uma instrução e retorna um objeto para uso com mysqli_stmt_prepare

### Descrição

Estilo orientado a objetos

public function mysqli::stmt_init(): mysqli_stmt|false

Estilo procedural

function mysqli_stmt_init(mysqli `$mysql`): mysqli_stmt|false

Aloca e inicializa um objeto de instrução adequado para mysqli_stmt_prepare().

> Nota:

> Qualquer chamada subseqüente para qualquer função mysqli_stmt falhará até que mysqli_stmt_prepare() seja chamado.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()

### Valor Retornado

Retorna um objeto.

### Veja Também

- mysqli_stmt_prepare() - Prepara uma declaração SQL para execução

# mysqli::store_result

# mysqli_store_result

(PHP 5, PHP 7, PHP 8)

mysqli::store_result -- mysqli_store_result — Transfere um conjunto de resultados da última consulta

### Descrição

Estilo orientado a objetos

public function mysqli::store_result(int `$mode` = 0): mysqli_result|false

Estilo procedural

function mysqli_store_result(mysqli `$mysql`, int `$mode` = 0): mysqli_result|false

Transfere o conjunto de resultados da última consulta na conexão do banco de dados representada pelo parâmetro `mysql` para ser usado com a função mysqli_data_seek().

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()
`mode`

  A opção que você deseja definir. A partir do PHP 8.1, este parâmetro não tem efeito. Pode ser um dos seguintes valores:

  Valid options
  Nome | Descrição
  --- | ---
  `MYSQLI_STORE_RESULT_COPY_DATA` | Copia os resultados do buffer mysqlnd interno nas variáveis PHP buscadas. Por padrão, o mysqlnd usará uma lógica de referência para evitar copiar e duplicar os resultados mantidos na memória. Para certos conjuntos de resultados, por exemplo, conjuntos de resultados com muitas linhas pequenas, a abordagem de cópia pode reduzir o uso geral de memória porque as variáveis PHP que contêm resultados podem ser liberadas mais cedo (disponível apenas com mysqlnd)

### Valor Retornado

Retorna um objeto de resultado armazenado em buffer ou `false` se ocorreu um erro.

> Nota:

> mysqli_store_result() retorna `false` caso a consulta não retorne um conjunto de resultados (se a consulta for, por exemplo, uma instrução INSERT). Esta função também retorna `false` se a leitura do conjunto de resultados falhou. Você pode verificar se houve um erro verificando se mysqli_error() não retorna uma string vazia, se mysqli_errno() retorna um valor diferente de zero ou se mysqli_field_count() retorna um valor diferente de zero. Além disso, a possível razão para esta função retornar `false` após uma chamada bem-sucedida para mysqli_query() pode ser um conjunto de resultados muito grande (a memória para ele não pode ser alocada). Se mysqli_field_count() retornar um valor diferente de zero, a instrução deve ter produzido um conjunto de resultados não vazio.

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Passar o parâmetro `mode` foi descontinuado. O parâmetro já não tem efeito a partir do PHP 8.1.0.

### Exemplos

Veja mysqli_multi_query().

### Notas

> Nota:

> Embora seja sempre uma boa prática liberar a memória usada pelo resultado de uma consulta usando a função mysqli_free_result(), ao transferir grandes conjuntos de resultados usando mysqli_store_result() isso se torna particularmente importante.

### Veja Também

- mysqli_real_query() - Executa uma consulta SQL
- mysqli_use_result() - Iniciar uma recuperação de conjunto de resultados

# mysqli::$thread_id

# mysqli_thread_id

(PHP 5, PHP 7, PHP 8)

mysqli::$thread_id -- mysqli_thread_id — Retorna o ID da thread para a conexão atual

### Descrição

Estilo orientado a objetos

int $mysqli->thread_id;

Estilo procedural

function mysqli_thread_id(mysqli `$mysql`): int

A função mysqli_thread_id() retorna o ID da thread para a conexão atual que pode então ser eliminada usando a função mysqli_kill(). Se a conexão for perdida e você reconectar com mysqli_ping(), o ID do thread será diferente. Portanto, o ID do thread deve ser obtido somente quando necessário.

> Nota:

> O ID do encadeamento é atribuído conexão por conexão. Portanto, se a conexão for interrompida e restabelecida, um novo ID de thread será atribuído.

> Para eliminar uma consulta em execução, pode ser usado o comando SQL `KILL QUERY id_processo`.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()

### Valor Retornado

Retorna o ID do thread para a conexão atual.

### Exemplos

Exemplo #1 Exemplo de $mysqli->thread_id

Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* verifique a conexão */
    if (mysqli_connect_errno()) {
        printf("Falha na conexão: %s\n", mysqli_connect_error());
        exit();
    }

    /* determine nosso id de thread */
    $thread_id = $mysqli->thread_id;

    /* Matar conexão */
    $mysqli->kill($thread_id);

    /* Isso deve produzir um erro */
    if (!$mysqli->query("CREATE TABLE myCity LIKE City")) {
        printf("Erro: %s\n", $mysqli->error);
        exit;
    }

    /* fecha a conexão */
    $mysqli->close();
    ?>

Estilo procedural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* verifique a conexão*/
    if (mysqli_connect_errno()) {
        printf("Falha na conexão: %s\n", mysqli_connect_error());
        exit();
    }

    /* determine nosso id de thread */
    $thread_id = mysqli_thread_id($link);

    /* Matar conexão */
    mysqli_kill($link, $thread_id);

    /* Isso deve produzir um erro */
    if (!mysqli_query($link, "CREATE TABLE myCity LIKE City")) {
        printf("Erro: %s\n", mysqli_error($link));
        exit;
    }

    /* fecha a conexão */
    mysqli_close($link);
    ?>

Os exemplos acima produzirão:

    Erro: MySQL server has gone away

### Veja Também

- mysqli_kill() - Solicita ao servidor o encerramento de um thread do MySQL

# mysqli::thread_safe

# mysqli_thread_safe

(PHP 5, PHP 7, PHP 8)

mysqli::thread_safe -- mysqli_thread_safe — Retorna se a segurança de thread é dada ou não

### Descrição

Estilo orientado a objetos

public function mysqli::thread_safe(): bool

Estilo procedural

function mysqli_thread_safe(): bool

Informa se a biblioteca cliente é compilada como thread-safe.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

`true` se a biblioteca cliente for thread-safe, caso contrário, `false`.

# mysqli::use_result

# mysqli_use_result

(PHP 5, PHP 7, PHP 8)

mysqli::use_result -- mysqli_use_result — Iniciar uma recuperação de conjunto de resultados

### Descrição

Estilo orientado a objetos

public function mysqli::use_result(): mysqli_result|false

Estilo procedural

function mysqli_use_result(mysqli `$mysql`): mysqli_result|false

Usado para iniciar a recuperação de um conjunto de resultados da última consulta executada usando a função mysqli_real_query() na conexão com o banco de dados.

Esta ou a função mysqli_store_result() deve ser chamada antes que os resultados de uma consulta possam ser recuperados, e uma ou outra deve ser chamada para evitar que a próxima consulta nessa conexão com o banco de dados falhe.

> Nota:

> A função mysqli_use_result() não transfere todo o conjunto de resultados do banco de dados e, portanto, não pode ser usada funções como mysqli_data_seek() para mover para uma linha específica dentro do conjunto. Para usar esta funcionalidade, o conjunto de resultados deve ser armazenado usando mysqli_store_result(). Não se deve usar mysqli_use_result() se for feito muito processamento no lado do cliente, pois isso irá sobrecarregar o servidor e evitar que outras threads atualizem quaisquer tabelas das quais os dados estão sendo buscados.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um objeto de resultado sem buffer ou `false` se ocorreu um erro.

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Exemplos

Exemplo #1 Exemplo de mysqli::use_result()

Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* verifique a conexão */
    if (mysqli_connect_errno()) {
        printf("Falha na conexão: %s\n", mysqli_connect_error());
        exit();
    }

    $query  = "SELECT CURRENT_USER();";
    $query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

    /* executar várias consultas */
    if ($mysqli->multi_query($query)) {
        do {
            /* armazenar primeiro conjunto de resultados */
            if ($result = $mysqli->use_result()) {
                while ($row = $result->fetch_row()) {
                    printf("%s\n", $row[0]);
                }
                $result->close();
            }
            /* divisor de impressão */
            if ($mysqli->more_results()) {
                printf("-----------------\n");
            }
        } while ($mysqli->next_result());
    }

    /* fecha a conexão */
    $mysqli->close();
    ?>

Estilo procedural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* verifique a conexão */
    if (mysqli_connect_errno()) {
        printf("Falha na conexão: %s\n", mysqli_connect_error());
        exit();
    }

    $query  = "SELECT CURRENT_USER();";
    $query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

    /* executar várias consultas */
    if (mysqli_multi_query($link, $query)) {
        do {
            /* armazenar primeiro conjunto de resultados */
            if ($result = mysqli_use_result($link)) {
                while ($row = mysqli_fetch_row($result)) {
                    printf("%s\n", $row[0]);
                }
                mysqli_free_result($result);
            }
            /* divisor de impressão */
            if (mysqli_more_results($link)) {
                printf("-----------------\n");
            }
        } while (mysqli_next_result($link));
    }

    /* fecha a conexão */
    mysqli_close($link);
    ?>

Os exemplos acima produzirão:

    my_user@localhost
    -----------------
    Amersfoort
    Maastricht
    Dordrecht
    Leiden
    Haarlemmermeer

### Veja Também

- mysqli_real_query() - Executa uma consulta SQL
- mysqli_store_result() - Transfere um conjunto de resultados da última consulta

# mysqli::$warning_count

# mysqli_warning_count

(PHP 5, PHP 7, PHP 8)

mysqli::$warning_count -- mysqli_warning_count — Retorna o número de alertas gerados pela consulta mais recente

### Descrição

Estilo orientado a objetos

int $mysqli->warning_count;

Estilo procedural

function mysqli_warning_count(mysqli `$mysql`): int

Retorna o número de alertas gerados pela consulta mais recente.

> Nota: Para recuperar mensagens de alerta, o comando SQL a seguir pode ser usado: `SHOW WARNINGS [limit row_count]`.

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()

### Valor Retornado

Número de avisos ou zero se não houver avisos.

### Exemplos

Exemplo #1 Exemplo de $mysqli->warning_count

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $mysqli->query("SELECT 42/0");

    if ($mysqli->warning_count > 0) {
        $result = $mysqli->query("SHOW WARNINGS");
        $row = $result->fetch_row();
        printf("%s (%d): %s\n", $row[0], $row[1], $row[2]);
    }

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    mysqli_query($link, "SELECT 42/0");

    if (mysqli_warning_count($link) > 0) {
        $result = mysqli_query($link, "SHOW WARNINGS");
        $row = mysqli_fetch_row($result);
        printf("%s (%d): %s\n", $row[0], $row[1], $row[2]);
    }

Os exemplos acima produzirão:

    Warning (1365): Division by 0

### Veja Também

- mysqli_errno() - Retorna o código de erro para a chamada de função mais recente
- mysqli_error() - Retorna uma string descrevendo o último erro
- mysqli_sqlstate() - Retorna o erro SQLSTATE da operação MySQL anterior

## Índice

- mysqli::$affected_rows — Retorna o número de linhas afetadas pela operação MySQL anterior
- mysqli::autocommit — Ativa ou desativa a gravação automática das modificações no banco de dados
- mysqli::begin_transaction — Inicia uma transação
- mysqli::change_user — Altera o usuário da conexão com o banco de dados
- mysqli::character_set_name — Retorna o conjunto de caracteres atual da conexão com o banco de dados
- mysqli::close — Fecha uma conexão ao banco de dados previamente aberta
- mysqli::commit — Grava a transação atual
- mysqli::$connect_errno — Retorna o código de erro da última chamada de conexão
- mysqli::$connect_error — Retorna uma descrição do último erro de conexão
- mysqli::__construct — Abre uma nova conexão com o servidor MySQL
- mysqli::debug — Realiza operações de depuração
- mysqli::dump_debug_info — Descarrega informação de debug no log
- mysqli->errno — Retorna o código de erro para a chamada de função mais recente
- mysqli->error — Retorna uma string descrevendo o último erro
- mysqli::$error_list — Retorna uma lista de erros do último comando executado
- mysqli::execute_query — Prepara, vincula parâmetros e executa a instrução SQL
- mysqli::$field_count — Retorna o número de campos para a consulta mais recente
- mysqli::get_charset — Retorna um objeto de conjunto de caracteres
- mysqli::$client_info — Obtém informação do cliente MySQL
- mysqli::$client_version — Retorna a versão do cliente MySQL como um inteiro
- mysqli::get_connection_stats — Retorna estatísticas sobre a conexão do cliente
- mysqli::$host_info — Retorna uma string representando o tipo de conexão utilizada
- mysqli::$protocol_version — Retorna a versão do protocolo MySQL usada
- mysqli::$server_info — Retorna a versão do servidor MySQL
- mysqli::$server_version — Retorna a versão do servidor MySQL como um inteiro
- mysqli::get_warnings — Obtém o resultado de SHOW WARNINGS
- mysqli::$info — Recupera informação sobre a recente consulta executada
- mysqli::init — Inicializa o MySQLi e retorna um objeto a ser utilizado com mysqli_real_connect()
- mysqli::$insert_id — Retorna o valor gerado para uma coluna AUTO_INCREMENT pela última consulta
- mysqli::kill — Solicita ao servidor o encerramento de um thread do MySQL
- mysqli::more_results — Verifica se há mais algum resultado de uma consulta múltipla
- mysqli::multi_query — Executa uma ou mais consultas no banco de dados
- mysqli::next_result — Prepara o próximo resultado de multi_query
- mysqli::options — Define opções
- mysqli::ping — Faz ping em uma conexão de servidor ou tenta reconectar se a conexão cair
- mysqli::poll — Sondagem de conexões
- mysqli::prepare — Prepara uma instrução SQL para execução
- mysqli::query — Executa uma consulta no banco de dados
- mysqli::real_connect — Abre uma conexão a um servidor MySQL
- mysqli::real_escape_string — Escape caracteres especiais em uma string para uso em uma instrução SQL, levando em consideração o conjunto de caracteres atual da conexão
- mysqli::real_query — Executa uma consulta SQL
- mysqli::reap_async_query — Obtenha o resultado da consulta assíncrona
- mysqli::refresh — Atualiza
- mysqli::release_savepoint — Remove o ponto de salvamento nomeado do conjunto de pontos de salvamento da transação atual
- mysqli::rollback — Reverte a transação atual
- mysqli::savepoint — Define um ponto de salvamento de transação nomeado
- mysqli::select_db — Seleciona o banco de dados padrão para consultas de banco de dados
- mysqli::set_charset — Define o conjunto de caracteres do cliente
- mysqli::$sqlstate — Retorna o erro SQLSTATE da operação MySQL anterior
- mysqli::ssl_set — Usado para estabelecer conexões seguras usando SSL
- mysqli::stat — Obtém o status atual do sistema
- mysqli::stmt_init — Inicializa uma instrução e retorna um objeto para uso com mysqli_stmt_prepare
- mysqli::store_result — Transfere um conjunto de resultados da última consulta
- mysqli::$thread_id — Retorna o ID da thread para a conexão atual
- mysqli::thread_safe — Retorna se a segurança de thread é dada ou não
- mysqli::use_result — Iniciar uma recuperação de conjunto de resultados
- mysqli::$warning_count — Retorna o número de alertas gerados pela consulta mais recente

# A classe mysqli_stmt

(PHP 5, PHP 7, PHP 8)

## Introdução

Representa uma declaração preparada.

## Resumo da classe

class mysqli_stmt {
/* Propriedades */
public readonly int|string $affected_rows;
public readonly int|string $insert_id;
public readonly int|string $num_rows;
public readonly int $param_count;
public readonly int $field_count;
public readonly int $errno;
public readonly string $error;
public readonly array $error_list;
public readonly string $sqlstate;
public int $id;
/* Métodos */
public function __construct(mysqli `$mysql`, ?string `$query` = `null`)
public function attr_get(int `$attribute`): int
public function attr_set(int `$attribute`, int `$value`): bool
public function bind_param(string `$types`, mixed `&$var`, mixed `&...$vars`): bool
public function bind_result(mixed `&$var`, mixed `&...$vars`): bool
public function close(): true
public function data_seek(int `$offset`): void
public function execute(?array `$params` = `null`): bool
public function fetch(): ?bool
public function free_result(): void
public function get_result(): mysqli_result|false
public function get_warnings(): mysqli_warning|false
public function more_results(): bool
public function next_result(): bool
public function num_rows(): int|string
public function prepare(string `$query`): bool
public function reset(): bool
public function result_metadata(): mysqli_result|false
public function send_long_data(int `$param_num`, string `$data`): bool
public function store_result(): bool
}

## Propriedades

id

  Armazena o ID da declaração.

# mysqli_stmt::$affected_rows

# mysqli_stmt_affected_rows

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$affected_rows -- mysqli_stmt_affected_rows — Retorna o número total de linhas modificadas, apagadas, inseridas ou correspondidas pela última instrução executada

### Descrição

Estilo orientado a objetos

int|string $mysqli_stmt->affected_rows;

Estilo procedural

function mysqli_stmt_affected_rows(mysqli_stmt `$statement`): int|string

Retorna o número de linhas afetadas por consultas `INSERT`, `UPDATE` ou `DELETE`. Funciona como mysqli_stmt_num_rows() para instruções `SELECT`.

### Parâmetros

`statement`
  Somente no estilo procedural: Um objeto mysqli_stmt retornado por mysqli_stmt_init().

### Valor Retornado

Um inteiro maior que zero indica o número de linhas afetadas ou recebidas. Zero indica que nenhum registro foi atualizado para uma instrução `UPDATE`, nenhuma linha correspondeu à cláusula `WHERE` na consulta ou que nenhuma consulta foi executada. `-1` indica que a consulta retornou um erro ou que, para uma consulta `SELECT`, mysqli_stmt_affected_rows() foi chamada antes de mysqli_stmt_store_result().

> Nota:

> Se o número de linhas afetadas for maior que o máximo valor inteiro do PHP, o número de linhas afetadas será retornado como uma string.

### Exemplos

Exemplo #1 Exemplo de mysqli_stmt_affected_rows()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* cria tabela temporária */
    $mysqli->query("CREATE TEMPORARY TABLE myCountry LIKE Country");

    $query = "INSERT INTO myCountry SELECT * FROM Country WHERE Code LIKE ?";

    /* prepara a instrução */
    $stmt = $mysqli->prepare($query);

    /* Vincula variável para o espaço reservado */
    $code = 'A%';
    $stmt->bind_param("s", $code);

    /* executa a instrução */
    $stmt->execute();

    printf("Linhas inseridas: %d\n", $stmt->affected_rows);

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* cria tabela temporária */
    mysqli_query($link, "CREATE TEMPORARY TABLE myCountry LIKE Country");

    $query = "INSERT INTO myCountry SELECT * FROM Country WHERE Code LIKE ?";

    /* prepara a instrução */
    $stmt = mysqli_prepare($link, $query);

    /* Vincula variável para o espaço reservado */
    $code = 'A%';
    mysqli_stmt_bind_param($stmt, "s", $code);

    /* executa a instrução */
    mysqli_stmt_execute($stmt);

    printf("Linhas inseridas: %d\n", mysqli_stmt_affected_rows($stmt));

Os exemplos acima produzirão:

    Linhas inseridas: 17

### Veja Também

- mysqli_stmt_num_rows() - Retorna o número de linhas recebidas pelo servidor
- mysqli_stmt_store_result() - Armazena um conjunto de resultados em um buffer interno

# mysqli_stmt::attr_get

# mysqli_stmt_attr_get

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::attr_get -- mysqli_stmt_attr_get — Usado para obter o valor atual de um atributo de instrução

### Descrição

Estilo orientado a objetos

public function mysqli_stmt::attr_get(int `$attribute`): int

Estilo procedural

function mysqli_stmt_attr_get(mysqli_stmt `$statement`, int `$attribute`): int

Obtém o valor atual de um atributo de instrução.

### Parâmetros

`statement`
  Somente no estilo procedural: Um objeto mysqli_stmt retornado por mysqli_stmt_init().
`attribute`

  O atributo que se deseja obter.

### Valor Retornado

Retorna o valor do atributo.

# mysqli_stmt::attr_set

# mysqli_stmt_attr_set

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::attr_set -- mysqli_stmt_attr_set — Usado para modificar o comportamento de uma instrução preparada

### Descrição

Estilo orientado a objetos

public function mysqli_stmt::attr_set(int `$attribute`, int `$value`): bool

Estilo procedural

function mysqli_stmt_attr_set(mysqli_stmt `$statement`, int `$attribute`, int `$value`): bool

Usada para modificar o comportamento de uma instrução preparada. Esta função pode ser chamada múltiplas vezes para definir vários atributos.

### Parâmetros

`statement`
  Somente no estilo procedural: Um objeto mysqli_stmt retornado por mysqli_stmt_init().
`attribute`

  O atributo que se deseja definir. Pode ser um dos seguintes valores:

  Valores de atributos
  Caractere | Descrição
  --- | ---
  MYSQLI_STMT_ATTR_UPDATE_MAX_LENGTH | Definir para `true` faz com que mysqli_stmt_store_result() atualize o valor do metadado `MYSQL_FIELD->max_length`.
  MYSQLI_STMT_ATTR_CURSOR_TYPE | Tipo de cursor a ser aberto para a instrução quando mysqli_stmt_execute() for chamada. `value` pode ser `MYSQLI_CURSOR_TYPE_NO_CURSOR` (o padrão) ou `MYSQLI_CURSOR_TYPE_READ_ONLY`.
  MYSQLI_STMT_ATTR_PREFETCH_ROWS | Número de linhas a receber do servidor de cada vez ao usar um cursor. `value` pode estar na faixa de 1 até o máximo valor de um inteiro longo sem sinal. O padrão é 1. Removida a partir do PHP 8.4.0.

  Se a opção `MYSQLI_STMT_ATTR_CURSOR_TYPE` for usada com `MYSQLI_CURSOR_TYPE_READ_ONLY`, um cursor é aberto para a instrução quando mysqli_stmt_execute() é chamada. Se já houver um cursor aberto de uma chamada anterior de mysqli_stmt_execute(), o cursor é fechado antes que um novo seja aberto. mysqli_stmt_reset() também fecha qualquer cursor aberto antes de preparar a instrução para re-execução. mysqli_stmt_free_result() fecha qualquer cursor aberto.

  Se for aberto um cursor para uma instrução preparada, a função mysqli_stmt_store_result() é desnecessária.

`value`

  O valor a designar para o atributo.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Veja Também

- » Conector/MySQL mysql_stmt_attr_set()

# mysqli_stmt::bind_param

# mysqli_stmt_bind_param

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::bind_param -- mysqli_stmt_bind_param — Liga variáveis a uma declaração preparada como parâmetros

### Descrição

Estilo orientado a objetos

public function mysqli_stmt::bind_param(string `$types`, mixed `&$var`, mixed `&...$vars`): bool

Estilo procedural

function mysqli_stmt_bind_param(
mysqli_stmt `$statement`,
string `$types`,
mixed `&$var`,
mixed `&...$vars`
): bool

Liga variáveis para os marcadores de parâmetros na declaração SQL preparada por mysqli_prepare() ou mysqli_stmt_prepare().

> Nota:

> Se o tamanho de dados de um variável exceder o tamanho de pacote máximo permitido (max_allowed_packet), deve-se especificar `b` em `types` e usar mysqli_stmt_send_long_data() para enviar os dados em pacotes.

> Nota:

> Deve-se ter cuidado ao usar mysqli_stmt_bind_param() em conjunto com call_user_func_array(). Note que mysqli_stmt_bind_param() requer que os parâmetros sejam passados por referência, enquanto que call_user_func_array() pode aceitar como parâmetro uma lista de variáveis que podem representar referências ou valores.

### Parâmetros

`statement`
  Somente no estilo procedural: Um objeto mysqli_stmt retornado por mysqli_stmt_init().
`types`

  Uma string que contém um ou mais caracteres que especificam os tipos para as variáveis correspondentes ligadas:

  Caracteres de especificação de tipo
  Caractere | Descrição
  --- | ---
  i | variável correspondente tem tipo int
  d | variável correspondente tem tipo float
  s | variável correspondente tem tipo string
  b | variável correspondente é um blob e será enviada em pacotes

`var`
`vars`

  O número de variáveis e o comprimento da string que o parâmetro `types` deve corresponder aos parâmetros na declaração.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Exemplos

Exemplo #1 Exemplo de mysqli_stmt::bind_param()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world');

    $stmt = $mysqli->prepare("INSERT INTO CountryLanguage VALUES (?, ?, ?, ?)");
    $stmt->bind_param('sssd', $code, $language, $official, $percent);

    $code = 'DEU';
    $language = 'Bavarian';
    $official = "F";
    $percent = 11.2;

    $stmt->execute();

    printf("%d linha inserida.\n", $stmt->affected_rows);

    /* Limpa tabela CountryLanguage */
    $mysqli->query("DELETE FROM CountryLanguage WHERE Language='Bavarian'");
    printf("%d linha apagada.\n", $mysqli->affected_rows);

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world');

    $stmt = mysqli_prepare($link, "INSERT INTO CountryLanguage VALUES (?, ?, ?, ?)");
    mysqli_stmt_bind_param($stmt, 'sssd', $code, $language, $official, $percent);

    $code = 'DEU';
    $language = 'Bavarian';
    $official = "F";
    $percent = 11.2;

    mysqli_stmt_execute($stmt);

    printf("%d linha inserida.\n", mysqli_stmt_affected_rows($stmt));

    /* Limpa tabela CountryLanguage */
    mysqli_query($link, "DELETE FROM CountryLanguage WHERE Language='Bavarian'");
    printf("%d linha apagada.\n", mysqli_affected_rows($link));

Os exemplos acima produzirão:

    1 linha inserida.
    1 linha apagada.

Exemplo #2 Usando `...` para fornecer argumentos

O operador `...` pode ser usado para fornecer uma lista de argumentos de comprimento variável, como por exemplo em uma cláusula `WHERE IN`.

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world');

    $stmt = $mysqli->prepare("SELECT Language FROM CountryLanguage WHERE CountryCode IN (?, ?)");
    /* Usando ... para fornecer argumentos */
    $stmt->bind_param('ss', ...['DEU', 'POL']);
    $stmt->execute();
    $stmt->store_result();

    printf("%d linhas encontradas.\n", $stmt->num_rows());

Os exemplos acima produzirão:

    10 linhas encontradas.

### Veja Também

- mysqli_stmt_bind_result() - Liga variáveis a uma declaração preparada para armazenamento de resultado
- mysqli_stmt_execute() - Executa uma instrução preparada
- mysqli_stmt_fetch() - Recebe resultados de uma instrução preparada nas variáveis vinculadas
- mysqli_prepare() - Prepara uma instrução SQL para execução
- mysqli_stmt_send_long_data() - Envia dados em blocos
- mysqli_stmt_errno() - Retorna o código de erro para a chamada de instrução mais recente
- mysqli_stmt_error() - Retorna uma descrição em string para o último erro de instrução

# mysqli_stmt::bind_result

# mysqli_stmt_bind_result

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::bind_result -- mysqli_stmt_bind_result — Liga variáveis a uma declaração preparada para armazenamento de resultado

### Descrição

Estilo orientado a objetos

public function mysqli_stmt::bind_result(mixed `&$var`, mixed `&...$vars`): bool

Estilo procedural

function mysqli_stmt_bind_result(mysqli_stmt `$statement`, mixed `&$var`, mixed `&...$vars`): bool

Liga colunas no conjunto de resultados a variáveis.

Quando mysqli_stmt_fetch() é chamada para obter dados, o protocolo cliente/servidor MySQL coloca os dados das colunas ligadas nas variáveis expecificadas `var`/`vars`.

Uma coluna pode ser ligada ou religada a qualquer tempo, mesmo depois que um conjunto de resultados tenha sido parcialmente recebido. A nova ligação tem efeito na próxima vez que mysqli_stmt_fetch() for chamada.

> Nota:

> Todas as colunas precisam ser ligadas depois da chamada a mysqli_stmt_execute() e antes da chamada a mysqli_stmt_fetch().

> Nota:

> Dependendo dos tipos das colunas, variáveis ligadas podem silenciosamente ser alteradas para O tipo PHP correspondente.

Dica

Esta função é útil para resultados simples. Para receber conjuntos de resultados iteráveis, ou obter cada linha como um array ou objeto, use a função mysqli_stmt_get_result().

### Parâmetros

`statement`
  Somente no estilo procedural: Um objeto mysqli_stmt retornado por mysqli_stmt_init().
`var`

  A primeira variável a ser ligada.

`vars`

  Mais variáveis a serem ligadas.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* prepara a declaração */
    $stmt = $mysqli->prepare("SELECT Code, Name FROM Country ORDER BY Name LIMIT 5");
    $stmt->execute();

    /* liga as variáveis à declaração preparada */
    $stmt->bind_result($col1, $col2);

    /* obtém os valores */
    while ($stmt->fetch()) {
        printf("%s %s\n", $col1, $col2);
    }

Exemplo #2 Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* prepara a declaração */
    $stmt = mysqli_prepare($link, "SELECT Code, Name FROM Country ORDER BY Name LIMIT 5");
    mysqli_stmt_execute($stmt);

    /* liga as variáveis à declaração preparada */
    mysqli_stmt_bind_result($stmt, $col1, $col2);

    /* obtém os valores */
    while (mysqli_stmt_fetch($stmt)) {
        printf("%s %s\n", $col1, $col2);
    }

Os exemplos acima produzirão algo semelhante a:

    AFG Afghanistan
    ALB Albania
    DZA Algeria
    ASM American Samoa
    AND Andorra

### Veja Também

- mysqli_stmt_get_result() - Obtém um resultado de uma instrução preparada como um objeto mysqli_result
- mysqli_stmt_bind_param() - Liga variáveis a uma declaração preparada como parâmetros
- mysqli_stmt_execute() - Executa uma instrução preparada
- mysqli_stmt_fetch() - Recebe resultados de uma instrução preparada nas variáveis vinculadas
- mysqli_prepare() - Prepara uma instrução SQL para execução
- mysqli_stmt_prepare() - Prepara uma declaração SQL para execução

# mysqli_stmt::close

# mysqli_stmt_close

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::close -- mysqli_stmt_close — Fecha uma instrução preparada

### Descrição

Estilo orientado a objetos

public function mysqli_stmt::close(): true

Estilo procedural

function mysqli_stmt_close(mysqli_stmt `$statement`): true

Fecha uma instrução preparada. mysqli_stmt_close() também desaloca da memória o manipulador da instrução. Se a instrução atual tem resultados pendentes ou não lidos, esta função as cancela de forma que a próxima consulta possa ser executada.

### Parâmetros

`statement`
  Somente no estilo procedural: Um objeto mysqli_stmt retornado por mysqli_stmt_init().

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Esta função agora sempre retorna `true`. Anteriormente retornava `false` em caso de falha.

### Veja Também

- mysqli_prepare() - Prepara uma instrução SQL para execução

# mysqli_stmt::__construct

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::__construct — Constrói um novo objeto mysqli_stmt

### Descrição

public function mysqli_stmt::__construct(mysqli `$mysql`, ?string `$query` = `null`)

Este método constrói um novo objeto mysqli_stmt.

### Parâmetros

`link`

  Om objeto mysqli válido.

`query`

  A consulta, como uma string. Se este parâmetro for `null`, o construtor se comporta de forma idêntica a mysqli_stmt_init(), caso contrário se comporta como mysqli_prepare().

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `query` agora pode ser nulo.

### Veja Também

- mysqli_prepare() - Prepara uma instrução SQL para execução
- mysqli_stmt_init() - Inicializa uma instrução e retorna um objeto para uso com mysqli_stmt_prepare

# mysqli_stmt::data_seek

# mysqli_stmt_data_seek

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::data_seek -- mysqli_stmt_data_seek — Ajusta o ponteiro de resultado para uma linha arbitrária no resultado com buffer

### Descrição

Estilo orientado a objetos

public function mysqli_stmt::data_seek(int `$offset`): void

Estilo procedural

function mysqli_stmt_data_seek(mysqli_stmt `$statement`, int `$offset`): void

Esta função move o ponteiro do conjunto de resultados com buffer para uma linha arbitrária especificada pelo parâmetro `offset`.

Esta função funciona somente com o conjunto de resultados interno com buffer. mysqli_stmt_store_result() precisa ser chamada antes de mysqli_stmt_data_seek().

### Parâmetros

`statement`
  Somente no estilo procedural: Um objeto mysqli_stmt retornado por mysqli_stmt_init().
`offset`

  Precisa ser entre zero e o número total de linhas menos um (0.. mysqli_stmt_num_rows() - 1).

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name";
    $stmt = $mysqli->prepare($query);
    $stmt->execute();

    $stmt->bind_result($name, $code);

    $stmt->store_result();

    /* aponta para a linha núm. 400 */
    $stmt->data_seek(399);

    $stmt->fetch();

    printf("City: %s  Countrycode: %s\n", $name, $code);

Exemplo #2 Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name";
    $stmt = mysqli_prepare($link, $query);

    mysqli_stmt_execute($stmt);

    mysqli_stmt_bind_result($stmt, $name, $code);

    mysqli_stmt_store_result($stmt);

    /* aponta para a linha núm. 400 */
    mysqli_stmt_data_seek($stmt, 399);

    mysqli_stmt_fetch($stmt);

    printf("City: %s  Countrycode: %s\n", $name, $code);

Os exemplos acima produzirão:

    City: Benin City  Countrycode: NGA

### Veja Também

- mysqli_prepare() - Prepara uma instrução SQL para execução
- mysqli_stmt_store_result() - Armazena um conjunto de resultados em um buffer interno
- mysqli_stmt_num_rows() - Retorna o número de linhas recebidas pelo servidor
- mysqli_data_seek() - Ajusta o ponteiro do resultado para uma linha arbitrária no resultado

# mysqli_stmt::$errno

# mysqli_stmt_errno

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$errno -- mysqli_stmt_errno — Retorna o código de erro para a chamada de instrução mais recente

### Descrição

Estilo orientado a objetos

int $mysqli_stmt->errno;

Estilo procedural

function mysqli_stmt_errno(mysqli_stmt `$statement`): int

Retorna o código de erro para a função de instrução mais recentemente chamada, que possa ter sucesso ou falhar.

### Parâmetros

`statement`
  Somente no estilo procedural: Um objeto mysqli_stmt retornado por mysqli_stmt_init().

### Valor Retornado

Um valor de código de erro. Zero significa que não houve erro.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php
    /* Abre uma conexão */
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verifica a conexão */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    $mysqli->query("CREATE TABLE myCountry LIKE Country");
    $mysqli->query("INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = $mysqli->prepare($query)) {

        /* apaga a tabela */
        $mysqli->query("DROP TABLE myCountry");

        /* executa a instrução */
        $stmt->execute();

        printf("Erro: %d.\n", $stmt->errno);

        /* fecha a instrução */
        $stmt->close();
    }

    /* fecha a conexão */
    $mysqli->close();
    ?>

Exemplo #2 Estilo procedural

    <?php
    /* Abre uma conexão */
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verifica a conexão */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
    mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = mysqli_prepare($link, $query)) {

        /* apaga a tabela */
        mysqli_query($link, "DROP TABLE myCountry");

        /* executa a instrução */
        mysqli_stmt_execute($stmt);

        printf("Erro: %d.\n", mysqli_stmt_errno($stmt));

        /* fecha a instrução */
        mysqli_stmt_close($stmt);
    }

    /* close connection */
    mysqli_close($link);
    ?>

Os exemplos acima produzirão:

    Erro: 1146.

### Veja Também

- mysqli_stmt_error() - Retorna uma descrição em string para o último erro de instrução
- mysqli_stmt_sqlstate() - Retorna o erro SQLSTATE da operação da instrução anterior

# mysqli_stmt::$error

# mysqli_stmt_error

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$error -- mysqli_stmt_error — Retorna uma descrição em string para o último erro de instrução

### Descrição

Estilo orientado a objetos

string $mysqli_stmt->error;

Estilo procedural

function mysqli_stmt_error(mysqli_stmt `$statement`): string

Retorna uma string contendo a mensagem de erro para a função de instrução mais recentemente chamada, que possa ter sucesso ou falhar.

### Parâmetros

`statement`
  Somente no estilo procedural: Um objeto mysqli_stmt retornado por mysqli_stmt_init().

### Valor Retornado

Uma string que descreve o erro. Uma string vazia se nenhum erro ocorreu.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php
    /* Abre uma conexão */
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verifica a conexão */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    $mysqli->query("CREATE TABLE myCountry LIKE Country");
    $mysqli->query("INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = $mysqli->prepare($query)) {

        /* apaga a tabela */
        $mysqli->query("DROP TABLE myCountry");

        /* executa a instrução */
        $stmt->execute();

        printf("Erro: %s.\n", $stmt->error);

        /* fecha a instrução */
        $stmt->close();
    }

    /* fecha a conexão */
    $mysqli->close();
    ?>

Exemplo #2 Estilo procedural

    <?php
    /* Abre uma conexão */
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verifica a conexão */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
    mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = mysqli_prepare($link, $query)) {

        /* apaga a tabela */
        mysqli_query($link, "DROP TABLE myCountry");

        /* executa a instrução */
        mysqli_stmt_execute($stmt);

        printf("Erro: %s.\n", mysqli_stmt_error($stmt));

        /* fecha a instrução */
        mysqli_stmt_close($stmt);
    }

    /* fecha a conexão */
    mysqli_close($link);
    ?>

Os exemplos acima produzirão:

    Erro: Table 'world.myCountry' doesn't exist.

### Veja Também

- mysqli_stmt_errno() - Retorna o código de erro para a chamada de instrução mais recente
- mysqli_stmt_sqlstate() - Retorna o erro SQLSTATE da operação da instrução anterior

# mysqli_stmt::$error_list

# mysqli_stmt_error_list

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

mysqli_stmt::$error_list -- mysqli_stmt_error_list — Retorna uma lista de erros da última instrução executada

### Descrição

Estilo orientado a objetos

array $mysqli_stmt->error_list;

Estilo procedural

function mysqli_stmt_error_list(mysqli_stmt `$statement`): array

Retorna um array de erros para a função de instrução mais recente que possa ter sucesso ou falhar.

### Parâmetros

`statement`
  Somente no estilo procedural: Um objeto mysqli_stmt retornado por mysqli_stmt_init().

### Valor Retornado

Uma lista de erros, cada um como um array associativo contendo o número do erro (errno), o erro (error) e o estado SQL (sqlstate).

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php
    /* Abre uma conexão */
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verifica a conexão */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    $mysqli->query("CREATE TABLE myCountry LIKE Country");
    $mysqli->query("INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = $mysqli->prepare($query)) {

        /* apaga a tabela */
        $mysqli->query("DROP TABLE myCountry");

        /* executa a instrução */
        $stmt->execute();

        echo "Erro:\n";
        print_r($stmt->error_list);

        /* fecha a instrução */
        $stmt->close();
    }

    /* fecha a conexão */
    $mysqli->close();
    ?>

Exemplo #2 Estilo procedural

    <?php
    /* Abre uma conexão */
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verifica a conexão */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
    mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = mysqli_prepare($link, $query)) {

        /* apaga a tabela */
        mysqli_query($link, "DROP TABLE myCountry");

        /* executa a instrução */
        mysqli_stmt_execute($stmt);

        echo "Erro:\n";
        print_r(mysqli_stmt_error_list($stmt));

        /* fecha a instrução */
        mysqli_stmt_close($stmt);
    }

    /* fecha a conexão */
    mysqli_close($link);
    ?>

Os exemplos acima produzirão:

    Erro:
    Array
    (
        [0] => Array
            (
                [errno] => 1146
                [sqlstate] => 42S02
                [error] => Table 'world.myCountry' doesn't exist
            )

    )

### Veja Também

- mysqli_stmt_error() - Retorna uma descrição em string para o último erro de instrução
- mysqli_stmt_errno() - Retorna o código de erro para a chamada de instrução mais recente
- mysqli_stmt_sqlstate() - Retorna o erro SQLSTATE da operação da instrução anterior

# mysqli_stmt::execute

# mysqli_stmt_execute

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::execute -- mysqli_stmt_execute — Executa uma instrução preparada

### Descrição

Estilo orientado a objetos

public function mysqli_stmt::execute(?array `$params` = `null`): bool

Estilo procedural

function mysqli_stmt_execute(mysqli_stmt `$statement`, ?array `$params` = `null`): bool

Executa uma instrução previamente preparada. A instrução precisa ser preparada com sucesso antes da execução, usando a função mysqli_prepare() ou a função mysqli_stmt_prepare(), ou ainda passando o segundo argumento para o método mysqli_stmt::__construct().

Se a instrução for `UPDATE`, `DELETE` ou `INSERT`, o número total de linhas afetadas pode ser determinado usando-se a função mysqli_stmt_affected_rows(). Se a consulta retorna um resultado, ele pode ser recebido pela função mysqli_stmt_get_result() ou linha por linha diretamente da instrução usando a função mysqli_stmt_fetch().

### Parâmetros

`statement`
  Somente no estilo procedural: Um objeto mysqli_stmt retornado por mysqli_stmt_init().
`params`

  Um array opcional listando tantos elementos quantos forem os parâmetros vinculados na instrução SQL sendo executada. Cada valor é tratado como uma string.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro optional `params` foi adicionado.

### Exemplos

Exemplo #1 Executa a instrução preparada com variáveis vinculadas

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $mysqli->query("CREATE TEMPORARY TABLE myCity LIKE City");

    /* Prepara uma instrução de inserção */
    $stmt = $mysqli->prepare("INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)");

    /* Vincula variáveis aos parâmetros */
    $stmt->bind_param("sss", $val1, $val2, $val3);

    $val1 = 'Stuttgart';
    $val2 = 'DEU';
    $val3 = 'Baden-Wuerttemberg';

    /* Executa a instrução */
    $stmt->execute();

    $val1 = 'Bordeaux';
    $val2 = 'FRA';
    $val3 = 'Aquitaine';

    /* Executa a instrução */
    $stmt->execute();

    /* Recebe todas as linhas da tabela myCity */
    $query = "SELECT Name, CountryCode, District FROM myCity";
    $result = $mysqli->query($query);
    while ($row = $result->fetch_row()) {
        printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
    }

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    mysqli_query($link, "CREATE TEMPORARY TABLE myCity LIKE City");

    /* Prepara uma instrução de inserção */
    $stmt = mysqli_prepare($link, "INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)");

    /* Vincula variáveis aos parâmetros */
    mysqli_stmt_bind_param($stmt, "sss", $val1, $val2, $val3);

    $val1 = 'Stuttgart';
    $val2 = 'DEU';
    $val3 = 'Baden-Wuerttemberg';

    /* Executa a instrução */
    mysqli_stmt_execute($stmt);

    $val1 = 'Bordeaux';
    $val2 = 'FRA';
    $val3 = 'Aquitaine';

    /* Executa a instrução */
    mysqli_stmt_execute($stmt);

    /* Recebe todas as linhas da tabela myCity */
    $query = "SELECT Name, CountryCode, District FROM myCity";
    $result = mysqli_query($link, $query);
    while ($row = mysqli_fetch_row($result)) {
        printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
    }

Os exemplos acima produzirão:

    Stuttgart (DEU,Baden-Wuerttemberg)
    Bordeaux (FRA,Aquitaine)

Exemplo #2 Executa uma isntrução preparada com um array de valores

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world');

    $mysqli->query('CREATE TEMPORARY TABLE myCity LIKE City');

    /* Prepara uma instrução de inserção */
    $stmt = $mysqli->prepare('INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)');

    /* Executa a instrução */
    $stmt->execute(['Stuttgart', 'DEU', 'Baden-Wuerttemberg']);

    /* Recebe todas as linhas da tabela myCity */
    $query = 'SELECT Name, CountryCode, District FROM myCity';
    $result = $mysqli->query($query);
    while ($row = $result->fetch_row()) {
        printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
    }

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world');

    mysqli_query($link, 'CREATE TEMPORARY TABLE myCity LIKE City');

    /* Prepara uma instrução de inserção */
    $stmt = mysqli_prepare($link, 'INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)');

    /* Executa a instrução */
    mysqli_stmt_execute($stmt, ['Stuttgart', 'DEU', 'Baden-Wuerttemberg']);

    /* Recebe todas as linhas da tabela myCity */
    $query = 'SELECT Name, CountryCode, District FROM myCity';
    $result = mysqli_query($link, $query);
    while ($row = mysqli_fetch_row($result)) {
        printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
    }

Os exemplos acima produzirão:

    Stuttgart (DEU,Baden-Wuerttemberg)

### Veja Também

- mysqli_execute_query() - Prepara, vincula parâmetros e executa a instrução SQL
- mysqli_prepare() - Prepara uma instrução SQL para execução
- mysqli_stmt_bind_param() - Liga variáveis a uma declaração preparada como parâmetros
- mysqli_stmt_get_result() - Obtém um resultado de uma instrução preparada como um objeto mysqli_result

# mysqli_stmt::fetch

# mysqli_stmt_fetch

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::fetch -- mysqli_stmt_fetch — Recebe resultados de uma instrução preparada nas variáveis vinculadas

### Descrição

Estilo orientado a objetos

public function mysqli_stmt::fetch(): ?bool

Estilo procedural

function mysqli_stmt_fetch(mysqli_stmt `$statement`): ?bool

Recebe o resultado de uma instrução preparada nas variáveis vinculadas por mysqli_stmt_bind_result().

> Nota:

> Observe que todas as colunas precisam estar vinculadas pela aplicação antes de chamar a função mysqli_stmt_fetch().

> Nota:

> Os dados são transferidos sem buffer quando não se chama a função mysqli_stmt_store_result(), o que pode reduzir o desempenho (mas reduz o consumo de memória).

### Parâmetros

`statement`
  Somente no estilo procedural: Um objeto mysqli_stmt retornado por mysqli_stmt_init().

### Valor Retornado

Valor Retornado
Valor | Descrição
--- | ---
`true` | Sucesso. Dados foram recebidos
`false` | Error occurred
`null` | Não há mais linhas/dados ou ocorreu um truncamento de dados

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* verifica a conexão */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 150,5";

    if ($stmt = $mysqli->prepare($query)) {

        /* executa a instrução */
        $stmt->execute();

        /* vincula as variáveis do resultado */
        $stmt->bind_result($name, $code);

        /* recebe os valores */
        while ($stmt->fetch()) {
            printf ("%s (%s)\n", $name, $code);
        }

        /* fecha a instrução */
        $stmt->close();
    }

    /* fecha a conexão */
    $mysqli->close();
    ?>

Exemplo #2 Estilo procedural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* verifica a conexão */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 150,5";

    if ($stmt = mysqli_prepare($link, $query)) {

        /* executa a instrução */
        mysqli_stmt_execute($stmt);

        /* vincula as variáveis do resultado */
        mysqli_stmt_bind_result($stmt, $name, $code);

        /* recebe os valores */
        while (mysqli_stmt_fetch($stmt)) {
            printf ("%s (%s)\n", $name, $code);
        }

        /* fecha a instrução */
        mysqli_stmt_close($stmt);
    }

    /* fecha a conexão */
    mysqli_close($link);
    ?>

Os exemplos acima produzirão:

    Rockford (USA)
    Tallahassee (USA)
    Salinas (USA)
    Santa Clarita (USA)
    Springfield (USA)

### Veja Também

- mysqli_prepare() - Prepara uma instrução SQL para execução
- mysqli_stmt_errno() - Retorna o código de erro para a chamada de instrução mais recente
- mysqli_stmt_error() - Retorna uma descrição em string para o último erro de instrução
- mysqli_stmt_bind_result() - Liga variáveis a uma declaração preparada para armazenamento de resultado

# mysqli_stmt::$field_count

# mysqli_stmt_field_count

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$field_count -- mysqli_stmt_field_count — Retorna o número de colunas na instrução informada

### Descrição

Estilo orientado a objetos

int $mysqli_stmt->field_count;

Estilo procedural

function mysqli_stmt_field_count(mysqli_stmt `$statement`): int

Retorna o número de colunas na instrução preparada.

### Parâmetros

`statement`
  Somente no estilo procedural: Um objeto mysqli_stmt retornado por mysqli_stmt_init().

### Valor Retornado

Retorna um inteiro que representa o número de colunas.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $code = 'FR';

    $stmt = $mysqli->prepare("SELECT Name FROM Country WHERE Code=?");
    $stmt->bind_param('s', $code);
    $stmt->execute();
    $row = $stmt->get_result()->fetch_row();
    for ($i = 0; $i < $stmt->field_count; $i++) {
        printf("Valor da coluna número %d é %s", $i, $row[$i]);
    }

Exemplo #2 Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $code = 'FR';

    $stmt = mysqli_prepare($mysqli, "SELECT Name FROM Country WHERE Code=?");
    mysqli_stmt_bind_param($stmt, 's', $code);
    mysqli_stmt_execute($stmt);
    $result = mysqli_stmt_get_result($stmt);
    $row = mysqli_fetch_row($result);
    for ($i = 0; $i < mysqli_stmt_field_count($stmt); $i++) {
        printf("Valor da coluna número %d é %s", $i, $row[$i]);
    }

Os exemplos acima produzirão algo semelhante a:

    Valor da coluna número 0 é France

### Veja Também

- mysqli_stmt_num_rows() - Retorna o número de linhas recebidas pelo servidor

# mysqli_stmt::free_result

# mysqli_stmt_free_result

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::free_result -- mysqli_stmt_free_result — Libera memória do resultado armazenado para o manipulador de instrução informado

### Descrição

Estilo orientado a objetos

public function mysqli_stmt::free_result(): void

Estilo procedural

function mysqli_stmt_free_result(mysqli_stmt `$statement`): void

Libera a memória do resultado associado à instrução, que foi alocada por mysqli_stmt_store_result().

### Parâmetros

`statement`
  Somente no estilo procedural: Um objeto mysqli_stmt retornado por mysqli_stmt_init().

### Valor Retornado

Nenhum valor é retornado.

### Veja Também

- mysqli_stmt_store_result() - Armazena um conjunto de resultados em um buffer interno

# mysqli_stmt::get_result

# mysqli_stmt_get_result

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_stmt::get_result -- mysqli_stmt_get_result — Obtém um resultado de uma instrução preparada como um objeto mysqli_result

### Descrição

Estilo orientado a objetos

public function mysqli_stmt::get_result(): mysqli_result|false

Estilo procedural

function mysqli_stmt_get_result(mysqli_stmt `$statement`): mysqli_result|false

Recebe um resultado de uma instrução preparada como um objeto mysqli_result. Os dados serão transportados do servidor MySQL para o PHP. Este método deve ser chamado somente para consultas que produzem um conjunto de resultados.

> Nota:

> Disponível apenas com o mysqlnd.

> Nota:

> Esta função não pode ser usada junto com a função mysqli_stmt_store_result(). Ambas estas funções recebem o conjunto completo de resultados do servidor MySQL.

### Parâmetros

`statement`
  Somente no estilo procedural: Um objeto mysqli_stmt retornado por mysqli_stmt_init().

### Valor Retornado

Retorna `false` em caso de falha. Para consultas bem sucedidas que produzem um resultado, como `SELECT, SHOW, DESCRIBE` ou `EXPLAIN`, mysqli_stmt_get_result() retornará um objeto mysqli_result. Para outras consultas bem sucedidas, mysqli_stmt_get_result() retornará `false`. A função mysqli_stmt_errno() pode ser usada para distinguir entre os dois motivos para `false`; devido a um problema de software, antes do PHP 7.4.13, mysqli_errno() tinha de ser usada para este propósito.

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, Population, Continent FROM Country WHERE Continent=? ORDER BY Name LIMIT 1";

    $stmt = $mysqli->prepare($query);
    $stmt->bind_param("s", $continent);

    $continentList = array('Europe', 'Africa', 'Asia', 'North America');

    foreach ($continentList as $continent) {
        $stmt->execute();
        $result = $stmt->get_result();
        while ($row = $result->fetch_array(MYSQLI_NUM)) {
            foreach ($row as $r) {
                print "$r ";
            }
            print "\n";
        }
    }

Exemplo #2 Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, Population, Continent FROM Country WHERE Continent=? ORDER BY Name LIMIT 1";

    $stmt = mysqli_prepare($link, $query);
    mysqli_stmt_bind_param($stmt, "s", $continent);

    $continentList= array('Europe', 'Africa', 'Asia', 'North America');

    foreach ($continentList as $continent) {
        mysqli_stmt_execute($stmt);
        $result = mysqli_stmt_get_result($stmt);
        while ($row = mysqli_fetch_array($result, MYSQLI_NUM)) {
            foreach ($row as $r) {
                print "$r ";
            }
            print "\n";
        }
    }

Os exemplos acima produzirão algo semelhante a:

    Albania 3401200 Europe
    Algeria 31471000 Africa
    Afghanistan 22720000 Asia
    Anguilla 8000 North America

### Veja Também

- mysqli_prepare() - Prepara uma instrução SQL para execução
- mysqli_stmt_result_metadata() - Retorna os metadados de resultado de uma instrução preparada
- mysqli_stmt_fetch() - Recebe resultados de uma instrução preparada nas variáveis vinculadas
- mysqli_fetch_array() - Recebe a próxima linha de resultado como array associativo, numérico, ou ambos
- mysqli_stmt_store_result() - Armazena um conjunto de resultados em um buffer interno

# mysqli_stmt::get_warnings

# mysqli_stmt_get_warnings

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

mysqli_stmt::get_warnings -- mysqli_stmt_get_warnings — Obtém o resultado de SHOW WARNINGS

### Descrição

Estilo orientado a objetos

public function mysqli_stmt::get_warnings(): mysqli_warning|false

Estilo procedural

function mysqli_stmt_get_warnings(mysqli_stmt `$statement`): mysqli_warning|false
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

# mysqli_stmt::$insert_id

# mysqli_stmt_insert_id

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$insert_id -- mysqli_stmt_insert_id — Obtém o ID gerado pela operação INSERT anterior

### Descrição

Estilo orientado a objetos

int|string $mysqli_stmt->insert_id;

Estilo procedural

function mysqli_stmt_insert_id(mysqli_stmt `$statement`): int|string
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

# mysqli_stmt::more_results

# mysqli_stmt_more_results

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_stmt::more_results -- mysqli_stmt_more_results — Verifica se há mais resultados de uma consulta múltipla

### Descrição

Estilo orientado a objetos

public function mysqli_stmt::more_results(): bool

Estilo procedural:

function mysqli_stmt_more_results(mysqli_stmt `$statement`): bool

Verifica se há mais resultados de uma consulta múltipla.

> Nota:

> Disponível apenas com o mysqlnd.

### Parâmetros

`statement`
  Somente no estilo procedural: Um objeto mysqli_stmt retornado por mysqli_stmt_init().

### Valor Retornado

Retorna `true` se houver mais resultados, caso contrário retorna `false`.

### Veja Também

- mysqli_stmt::next_result() - Lê o próximo resultado de uma consulta múltipla
- mysqli::multi_query() - Executa uma ou mais consultas no banco de dados

# mysqli_stmt::next_result

# mysqli_stmt_next_result

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_stmt::next_result -- mysqli_stmt_next_result — Lê o próximo resultado de uma consulta múltipla

### Descrição

Estilo orientado a objetos

public function mysqli_stmt::next_result(): bool

Estilo procedural:

function mysqli_stmt_next_result(mysqli_stmt `$statement`): bool

Lê o próximo resultado de uma consulta múltipla.

> Nota:

> Antes do PHP 8.1.0, disponível somente com mysqlnd.

### Parâmetros

`statement`
  Somente no estilo procedural: Um objeto mysqli_stmt retornado por mysqli_stmt_init().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Agora também disponível com a biblioteca libmysqlclient.

### Veja Também

- mysqli_stmt::more_results() - Verifica se há mais resultados de uma consulta múltipla
- mysqli::multi_query() - Executa uma ou mais consultas no banco de dados

# mysqli_stmt::$num_rows

# mysqli_stmt::num_rows

# mysqli_stmt_num_rows

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$num_rows -- mysqli_stmt::num_rows -- mysqli_stmt_num_rows — Retorna o número de linhas recebidas pelo servidor

### Descrição

Estilo orientado a objetos

int|string $mysqli_stmt->num_rows;
public function mysqli_stmt::num_rows(): int|string

Estilo procedural

function mysqli_stmt_num_rows(mysqli_stmt `$statement`): int|string

Retorna o número de linhas em buffer na instrução. Esta função somente funcionará depois que mysqli_stmt_store_result() for chamara para fazer buffer do conjunto inteiro de resultados no manipulador da instrução.

Esta função retorna `0` a menos que todas as linhas tenham sido recebidas do servidor.

### Parâmetros

`statement`
  Somente no estilo procedural: Um objeto mysqli_stmt retornado por mysqli_stmt_init().

### Valor Retornado

Um int que representa o número de linhas em buffer. Retorna `0` em modo sem buffer a menos que todas as linhas tenham sido recebidas do servidor.

> Nota: Se o número de linhas for maior que `PHP_INT_MAX`, o número será retornado como uma string.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20";
    $stmt = $mysqli->prepare($query);
    $stmt->execute();

    /* armazena o resultado em um buffer interno */
    $stmt->store_result();

    printf("Número de linhas: %d.\n", $stmt->num_rows);

Exemplo #2 Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20";
    $stmt = mysqli_prepare($link, $query);
    mysqli_stmt_execute($stmt);

    /* armazena o resultado em um buffer interno */
    mysqli_stmt_store_result($stmt);

    printf("Número de linhas: %d.\n", mysqli_stmt_num_rows($stmt));

Os exemplos acima produzirão:

    Número de linhas: 20.

### Veja Também

- mysqli_stmt_store_result() - Armazena um conjunto de resultados em um buffer interno
- mysqli_stmt_affected_rows() - Retorna o número total de linhas modificadas, apagadas, inseridas ou correspondidas pela última instrução executada
- mysqli_prepare() - Prepara uma instrução SQL para execução

# mysqli_stmt::$param_count

# mysqli_stmt_param_count

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$param_count -- mysqli_stmt_param_count — Retorna o número de parâmetros para uma instrução fornecida

### Descrição

Estilo orientado a objetos

int $mysqli_stmt->param_count;

Estilo procedural

function mysqli_stmt_param_count(mysqli_stmt `$statement`): int

Retorna o número de marcadores de parâmetros presentes na instrução preparada.

### Parâmetros

`statement`
  Somente no estilo procedural: Um objeto mysqli_stmt retornado por mysqli_stmt_init().

### Valor Retornado

Retorna um inteiro que representa o número de parâmetros.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* verifica a conexão */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    if ($stmt = $mysqli->prepare("SELECT Name FROM Country WHERE Name=? OR Code=?")) {

        $marker = $stmt->param_count;
        printf("Instrução tem %d marcadores.\n", $marker);

        /* fecha a instrução */
        $stmt->close();
    }

    /* fecha a conexão */
    $mysqli->close();
    ?>

Exemplo #2 Estilo procedural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* verifica a conexão */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    if ($stmt = mysqli_prepare($link, "SELECT Name FROM Country WHERE Name=? OR Code=?")) {

        $marker = mysqli_stmt_param_count($stmt);
        printf("Instrução tem %d marcadores.\n", $marker);

        /* fecha a instrução */
        mysqli_stmt_close($stmt);
    }

    /* fecha a conexão */
    mysqli_close($link);
    ?>

Os exemplos acima produzirão:

    Instrução tem 2 marcadores.

### Veja Também

- mysqli_prepare() - Prepara uma instrução SQL para execução

# mysqli_stmt::prepare

# mysqli_stmt_prepare

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::prepare -- mysqli_stmt_prepare — Prepara uma declaração SQL para execução

### Descrição

Estilo orientado a objetos

public function mysqli_stmt::prepare(string `$query`): bool

Estilo procedural

function mysqli_stmt_prepare(mysqli_stmt `$statement`, string `$query`): bool

Prepara uma declaração para execução. A consulta deve consistir de uma única declaração SQL.

O modelo de declaração pode conter zero ou mais marcadores de parâmetro que são os pontos de interrogação (`?`), também chamados de espaços reservados. Os marcadores de parâmetros devem ser ligados às variáveis da aplicação usando mysqli_stmt_bind_param() antes da execução da declaração.

> Nota:

> No caso de uma declaração passada a mysqli_stmt_prepare() ser mais longa que o parâmetro `max_allowed_packet` do servidor, os códigos de erro retornados serão diferentes dependendo se está sendo utilizando o driver nativo MySQL (`mysqlnd`) ou a biblioteca cliente do MySQL (`libmysqlclient`). O comportamento é o seguinte:

> - `mysqlnd` no Linux retorna o código de erro 1153. A mensagem de erro diz got a packet bigger than (recebido pacote maior que) `max_allowed_packet` bytes.

> - `mysqlnd` no Windos retorna o código de erro 2006. Esta mensagem de erro diz server has gone away (servidor se foi).

> - `libmysqlclient` em todas as plataformas a retorna o código de erro 2006. Esta mensagem de erro diz server has gone away (servidor se foi).

### Parâmetros

`statement`
  Somente no estilo procedural: Um objeto mysqli_stmt retornado por mysqli_stmt_init().
`query`

  A consulta, como uma string. Deve consistir de uma única declaração SQL.

  A declaração SQL pode conter zero ou mais marcadores de parâmetros representados por caracteres de ponto de interrogação (`?`) nas posições apropriadas.

  > Nota:

  > Os marcadores são permitidos somente em alguns lugares das declarações SQL. Por exemplo, eles são permitidos na lista `VALUES()` de Uma declaração `INSERT` (para especificar valores de colunas para uma linha), ou em uma comparação com uma coluna em uma cláusula `WHERE` para especificar um valor de comparação. Entretanto, não são permitidos para identificadores (como tabelas ou nomes de colunas).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Exemplos

Exemplo #1 Exemplo de mysqli_stmt::prepare()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $city = "Amersfoort";

    /* cria uma declaração preparada */
    $stmt = $mysqli->stmt_init();
    $stmt->prepare("SELECT District FROM City WHERE Name=?");

    /* liga parâmetros para os marcadores */
    $stmt->bind_param("s", $city);

    /* executa a consulta */
    $stmt->execute();

    /* liga o resultado à variável */
    $stmt->bind_result($district);

    /* obtém o valor */
    $stmt->fetch();

    printf("%s está no distrito %s\n", $city, $district);

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $city = "Amersfoort";

    /* cria uma declaração preparada */
    $stmt = mysqli_stmt_init($link);
    mysqli_stmt_prepare($stmt, "SELECT District FROM City WHERE Name=?");

    /* liga parâmetros para os marcadores */
    mysqli_stmt_bind_param($stmt, "s", $city);

    /* executa a consulta */
    mysqli_stmt_execute($stmt);

    /* liga o resultado à variável */
    mysqli_stmt_bind_result($stmt, $district);

    /* obtém o valor */
    mysqli_stmt_fetch($stmt);

    printf("%s está no distrito %s\n", $city, $district);

Os exemplos acima produzirão:

    Amersfoort está no distrito Utrecht

### Veja Também

- mysqli_stmt_init() - Inicializa uma instrução e retorna um objeto para uso com mysqli_stmt_prepare
- mysqli_stmt_execute() - Executa uma instrução preparada
- mysqli_stmt_fetch() - Recebe resultados de uma instrução preparada nas variáveis vinculadas
- mysqli_stmt_bind_param() - Liga variáveis a uma declaração preparada como parâmetros
- mysqli_stmt_bind_result() - Liga variáveis a uma declaração preparada para armazenamento de resultado
- mysqli_stmt_get_result() - Obtém um resultado de uma instrução preparada como um objeto mysqli_result
- mysqli_stmt_close() - Fecha uma instrução preparada

# mysqli_stmt::reset

# mysqli_stmt_reset

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::reset -- mysqli_stmt_reset — Redefine uma instrução preparada

### Descrição

Estilo orientado a objetos

public function mysqli_stmt::reset(): bool

Estilo procedural

function mysqli_stmt_reset(mysqli_stmt `$statement`): bool

Redefine uma instrução preparada no cliente e no servidor para um estado pós-preparação.

A função redefine a instrução no servidor, os dados enviados por mysqli_stmt_send_long_data(), os resultados sem buffer e os erros atuais. Ela não limpa vinculações de variáveis ou resultados armazenados. Resultados armazenados serão limpos ao executar a instrução preparada (ou ao fechá-la).

Para preparar uma instrução com outra consulta, utilize a função mysqli_stmt_prepare().

### Parâmetros

`statement`
  Somente no estilo procedural: Um objeto mysqli_stmt retornado por mysqli_stmt_init().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- mysqli_prepare() - Prepara uma instrução SQL para execução

# mysqli_stmt::result_metadata

# mysqli_stmt_result_metadata

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::result_metadata -- mysqli_stmt_result_metadata — Retorna os metadados de resultado de uma instrução preparada

### Descrição

Estilo orientado a objetos

public function mysqli_stmt::result_metadata(): mysqli_result|false

Estilo procedural

function mysqli_stmt_result_metadata(mysqli_stmt `$statement`): mysqli_result|false

Se uma instrução passada a mysqli_prepare() for do tipo que produz um conjunto de resultados, mysqli_stmt_result_metadata() retornará o objeto de resultado que pode ser usado para processar a meta informação como o número total de campos e informações individual dos campos.

Esta função retorna um objeto vazio mysqli_result que pode ser usado para acessar informações de metadados da instrução preparada sem precisar buscar as linhas de dados reais. Não é necessário usar esta função ao usar mysqli_stmt_get_result() para recuperar todo o conjunto de resultados de uma instrução preparada como um objeto de resultado.

> Nota:

> Este objeto de conjunto de resultados pode ser passado como argumento apenas para as funções baseadas em campo que processam metadados de resultados, como:

> - mysqli_num_fields()

> - mysqli_fetch_field()

> - mysqli_fetch_field_direct()

> - mysqli_fetch_fields()

> - mysqli_field_count()

> - mysqli_field_seek()

> - mysqli_field_tell()

> - mysqli_free_result()

> Nota: O conjunto de resultados retornado por mysqli_stmt_result_metadata() contém apenas metadados. Não contém nenhum resultado de linha. As linhas são obtidas chamando mysqli_stmt_get_result() no identificador da instrução ou com mysqli_stmt_fetch().

### Parâmetros

`statement`
  Somente no estilo procedural: Um objeto mysqli_stmt retornado por mysqli_stmt_init().

### Valor Retornado

Retorna um objeto de resultado ou `false` se um erro ocorrer. Se a instrução não produzir um conjunto de resultados, `false` também será retornado.

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    $mysqli->query("DROP TABLE IF EXISTS friends");
    $mysqli->query("CREATE TABLE friends (id int, name varchar(20))");

    $mysqli->query("INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");

    $stmt = $mysqli->prepare("SELECT id, name FROM friends");
    $stmt->execute();

    /* obtém o resultado de metadados */
    $result = $stmt->result_metadata();

    /* obtém informação do campo a partir do resultado de metadados */
    $field = $result->fetch_field();

    printf("Nome do campo: %s\n", $field->name);
    ?>

Exemplo #2 Estilo procedural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "test");

    mysqli_query($link, "DROP TABLE IF EXISTS friends");
    mysqli_query($link, "CREATE TABLE friends (id int, name varchar(20))");

    mysqli_query($link, "INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");

    $stmt = mysqli_prepare($link, "SELECT id, name FROM friends");
    mysqli_stmt_execute($stmt);

    /* obtém o resultado de metadados */
    $result = mysqli_stmt_result_metadata($stmt);

    /* obtém informação do campo a partir do resultado de metadados */
    $field = mysqli_fetch_field($result);

    printf("Nome do campo: %s\n", $field->name);
    ?>

### Veja Também

- mysqli_prepare() - Prepara uma instrução SQL para execução
- mysqli_free_result() - Libera memória associada a um resultado
- mysqli_stmt_get_result() - Obtém um resultado de uma instrução preparada como um objeto mysqli_result

# mysqli_stmt::send_long_data

# mysqli_stmt_send_long_data

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::send_long_data -- mysqli_stmt_send_long_data — Envia dados em blocos

### Descrição

Estilo orientado a objetos

public function mysqli_stmt::send_long_data(int `$param_num`, string `$data`): bool

Estilo procedural

function mysqli_stmt_send_long_data(mysqli_stmt `$statement`, int `$param_num`, string `$data`): bool

Permite enviar dados de parâmetros ao servidor em pedaços (ou blocos), por exemplo, se o tamanho de um BLOB exceder o tamanho de `max_allowed_packet`. Esta função pode ser chamada múltiplas vezes para enviar as partes de um valor de dados binários ou de caracteres para uma coluna, que precisa ser do tipo TEXT ou BLOB.

### Parâmetros

`statement`
  Somente no estilo procedural: Um objeto mysqli_stmt retornado por mysqli_stmt_init().
`param_num`

  Indica a qual parâmetro os dados serão associados. Parêmetros são numerados a partir de 0.

`data`

  Uma string contendo os dados que devem ser enviados.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php
    $stmt = $mysqli->prepare("INSERT INTO messages (message) VALUES (?)");
    $null = NULL;
    $stmt->bind_param("b", $null);
    $fp = fopen("messages.txt", "r");
    while (!feof($fp)) {
        $stmt->send_long_data(0, fread($fp, 8192));
    }
    fclose($fp);
    $stmt->execute();
    ?>

### Veja Também

- mysqli_prepare() - Prepara uma instrução SQL para execução
- mysqli_stmt_bind_param() - Liga variáveis a uma declaração preparada como parâmetros

# mysqli_stmt::$sqlstate

# mysqli_stmt_sqlstate

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$sqlstate -- mysqli_stmt_sqlstate — Retorna o erro SQLSTATE da operação da instrução anterior

### Descrição

Estilo orientado a objetos

string $mysqli_stmt->sqlstate;

Estilo procedural

function mysqli_stmt_sqlstate(mysqli_stmt `$statement`): string

Retorna uma string contento o código de erro SQLSTATE para a função de instrução preparada mais recentemente chamada, que possa ter sucesso ou falhar. O código de erro consiste de cinco caracteres. `'00000'` significa que não houve erro. Os valores são especificados pela ANSI SQL e pela ODBC. Para uma lista de valores possíveis, consulte » http://dev.mysql.com/doc/mysql/en/error-handling.html.

### Parâmetros

`statement`
  Somente no estilo procedural: Um objeto mysqli_stmt retornado por mysqli_stmt_init().

### Valor Retornado

Retorna uma string contendo o código de erro SQLSTATE para o último erro. O código de erro consiste de cinco caracteres. `'00000'` significa que não houve erro.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php
    /* abre uma conexão */
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* verifica a conexão */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    $mysqli->query("CREATE TABLE myCountry LIKE Country");
    $mysqli->query("INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = $mysqli->prepare($query)) {

        /* apaga a tabela */
        $mysqli->query("DROP TABLE myCountry");

        /* executa a instrução */
        $stmt->execute();

        printf("Erro: %s.\n", $stmt->sqlstate);

        /* fecha a instrução */
        $stmt->close();
    }

    /* fecha a conexão */
    $mysqli->close();
    ?>

Exemplo #2 Estilo procedural

    <?php
    /* abre uma conexão */
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* verifica a conexão */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
    mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = mysqli_prepare($link, $query)) {

        /* apaga a tabela */
        mysqli_query($link, "DROP TABLE myCountry");

        /* executa a instrução */
        mysqli_stmt_execute($stmt);

        printf("Error: %s.\n", mysqli_stmt_sqlstate($stmt));

        /* fecha a instrução */
        mysqli_stmt_close($stmt);
    }

    /* fecha a conexão */
    mysqli_close($link);
    ?>

Os exemplos acima produzirão:

    Erro: 42S02.

### Notas

> Nota:

> Observe que nem todos os erros do MySQL são mapeados para erros SQLSTATE. O valor `HY000` (erro geral) é usado para erros não mapeados.

### Veja Também

- mysqli_stmt_errno() - Retorna o código de erro para a chamada de instrução mais recente
- mysqli_stmt_error() - Retorna uma descrição em string para o último erro de instrução

# mysqli_stmt::store_result

# mysqli_stmt_store_result

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::store_result -- mysqli_stmt_store_result — Armazena um conjunto de resultados em um buffer interno

### Descrição

Estilo orientado a objetos

public function mysqli_stmt::store_result(): bool

Estilo procedural

function mysqli_stmt_store_result(mysqli_stmt `$statement`): bool

Esta função deve ser chamada, para consultas que produzem com sucesso um conjunto de resultados (ex.: `SELECT, SHOW, DESCRIBE, EXPLAIN`), seomente se o resultado completo precisa ser mantido em buffer no PHP. Cada chamada subsequente a mysqli_stmt_fetch() retornará dados em buffer.

> Nota:

> É desnecessário chamar mysqli_stmt_store_result() para outras conultas, mas se isto for feito, não irá causar dano ou qualquer perda notável de desempenho em qualquer caso. Pode-se detectar se a consulta produziu resultado verificando se a função mysqli_stmt_result_metadata() retorna `false`.

### Parâmetros

`statement`
  Somente no estilo procedural: Um objeto mysqli_stmt retornado por mysqli_stmt_init().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20";
    $stmt = $mysqli->prepare($query);
    $stmt->execute();

    /* armazena o resultado em um buffer interno */
    $stmt->store_result();

    printf("Número de linhas: %d.\n", $stmt->num_rows);

Exemplo #2 Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20";
    $stmt = mysqli_prepare($link, $query);
    mysqli_stmt_execute($stmt);

    /* armazena o resultado em um buffer interno */
    mysqli_stmt_store_result($stmt);

    printf("Número de linhas: %d.\n", mysqli_stmt_num_rows($stmt));

Os exemplos acima produzirão:

    Número de linhas: 20.

### Veja Também

- mysqli_prepare() - Prepara uma instrução SQL para execução
- mysqli_stmt_result_metadata() - Retorna os metadados de resultado de uma instrução preparada
- mysqli_stmt_fetch() - Recebe resultados de uma instrução preparada nas variáveis vinculadas

## Índice

- mysqli_stmt::$affected_rows — Retorna o número total de linhas modificadas, apagadas, inseridas ou correspondidas pela última instrução executada
- mysqli_stmt::attr_get — Usado para obter o valor atual de um atributo de instrução
- mysqli_stmt::attr_set — Usado para modificar o comportamento de uma instrução preparada
- mysqli_stmt::bind_param — Liga variáveis a uma declaração preparada como parâmetros
- mysqli_stmt::bind_result — Liga variáveis a uma declaração preparada para armazenamento de resultado
- mysqli_stmt::close — Fecha uma instrução preparada
- mysqli_stmt::__construct — Constrói um novo objeto mysqli_stmt
- mysqli_stmt::data_seek — Ajusta o ponteiro de resultado para uma linha arbitrária no resultado com buffer
- mysqli_stmt::$errno — Retorna o código de erro para a chamada de instrução mais recente
- mysqli_stmt::$error — Retorna uma descrição em string para o último erro de instrução
- mysqli_stmt::$error_list — Retorna uma lista de erros da última instrução executada
- mysqli_stmt::execute — Executa uma instrução preparada
- mysqli_stmt::fetch — Recebe resultados de uma instrução preparada nas variáveis vinculadas
- mysqli_stmt::$field_count — Retorna o número de colunas na instrução informada
- mysqli_stmt::free_result — Libera memória do resultado armazenado para o manipulador de instrução informado
- mysqli_stmt::get_result — Obtém um resultado de uma instrução preparada como um objeto mysqli_result
- mysqli_stmt::get_warnings — Obtém o resultado de SHOW WARNINGS
- mysqli_stmt::$insert_id — Obtém o ID gerado pela operação INSERT anterior
- mysqli_stmt::more_results — Verifica se há mais resultados de uma consulta múltipla
- mysqli_stmt::next_result — Lê o próximo resultado de uma consulta múltipla
- mysqli_stmt::$num_rows — Retorna o número de linhas recebidas pelo servidor
- mysqli_stmt::$param_count — Retorna o número de parâmetros para uma instrução fornecida
- mysqli_stmt::prepare — Prepara uma declaração SQL para execução
- mysqli_stmt::reset — Redefine uma instrução preparada
- mysqli_stmt::result_metadata — Retorna os metadados de resultado de uma instrução preparada
- mysqli_stmt::send_long_data — Envia dados em blocos
- mysqli_stmt::$sqlstate — Retorna o erro SQLSTATE da operação da instrução anterior
- mysqli_stmt::store_result — Armazena um conjunto de resultados em um buffer interno

# A classe mysqli_result

(PHP 5, PHP 7, PHP 8)

## Introdução

Representa o conjunto de resultados da consulta feita ao banco de dados.

## Resumo da classe

class mysqli_result implements IteratorAggregate {
/* Propriedades */
public readonly int $current_field;
public readonly int $field_count;
public readonly ?array $lengths;
public readonly int|string $num_rows;
public int $type;
/* Métodos */
public function __construct(mysqli `$mysql`, int `$result_mode` = `MYSQLI_STORE_RESULT`)
public function data_seek(int `$offset`): bool
public function fetch_all(int `$mode` = `MYSQLI_NUM`): array
public function fetch_array(int `$mode` = `MYSQLI_BOTH`): array|null|false
public function fetch_assoc(): array|null|false
public function fetch_column(int `$column` = 0): null|int|float|string|false
public function fetch_field(): object|false
public function fetch_field_direct(int `$index`): object|false
public function fetch_fields(): array
public function fetch_object(string `$class` = "stdClass", array `$constructor_args` = []): object|null|false
public function fetch_row(): array|null|false
public function field_seek(int `$index`): true
public function free(): void
public function close(): void
public function free_result(): void
public function getIterator(): Iterator
}

## Propriedades

type

  Armazena informação se o o resultado é com ou sem buffer, como um int (`MYSQLI_STORE_RESULT` ou `MYSQLI_USE_RESULT`, respectivamente).

## Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | mysqli_result agora implementa IteratorAggregate. Anteriormente, Traversable era implementado.

# mysqli_result::__construct

(PHP 5, PHP 7, PHP 8)

mysqli_result::__construct — Constrói um objeto mysqli_result

### Descrição

public function mysqli_result::__construct(mysqli `$mysql`, int `$result_mode` = `MYSQLI_STORE_RESULT`)

Este método constrói um novo objeto mysqli_result.

Pode ser usado para criar o objeto mysqli_result após a chamada à função mysqli_real_query() ou mysqli_multi_query(). Construir o objeto manualmente é equivalente a chamar a função mysqli_store_result() ou mysqli_use_result().

### Parâmetros

`mysql`
  Somente no estilo procedural: Um objeto mysqli retornado por mysqli_connect() ou mysqli_init()
`result_mode`

  O modo de resultado pode ser uma de 2 constantes que indicam como o resultado será retornado do servidor MySQL.

  `MYSQLI_STORE_RESULT` (padrão) - cria um objeto mysqli_result com resultado em buffer.

  `MYSQLI_USE_RESULT` - cria um objetomysqli_result com resultado sem buffer. Enquanto houver registros pendentes esperando ser recebidos, a linha de conexão estará ocupada e todas as chamadas subsequentes retornarão o erro `Commands out of sync` (comandos fora de sincronismo). Para evitar o erro, todos os registros devem ser recebidos do servidor ou o resultado deve ser descartado através da função mysqli_free_result(). A conexão precisa permanecer aberta para que as linhas sejam recebidas.

### Erros/Exceções

Se o relatório de erros da extensão mysqli estiver habilitado (`MYSQLI_REPORT_ERROR`) e a operação solicitada falhar, um aviso será gerado. Se, além disso, o modo for definido como `MYSQLI_REPORT_STRICT`, uma exceção mysqli_sql_exception será lançada em vez do aviso.

### Exemplos

Exemplo #1 Criação de um objeto mysqli_result

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Consultas SELECT retornam um resultado */
    $mysqli->real_query("SELECT Name FROM City LIMIT 10");

    $result = new mysqli_result($mysqli);
    printf("SELECT retornou %d linhas.\n", $result->num_rows);

Os exemplos acima produzirão algo semelhante a:

    SELECT retornou 10 linhas.

### Veja Também

- mysqli_multi_query() - Executa uma ou mais consultas no banco de dados
- mysqli_real_query() - Executa uma consulta SQL
- mysqli_store_result() - Transfere um conjunto de resultados da última consulta
- mysqli_use_result() - Iniciar uma recuperação de conjunto de resultados

# mysqli_result::$current_field

# mysqli_field_tell

(PHP 5, PHP 7, PHP 8)

mysqli_result::$current_field -- mysqli_field_tell — Obtém o deslocamento atual de campo de um ponteiro de resultado

### Descrição

Estilo orientado a objetos

int $mysqli_result->current_field;

Estilo procedural

function mysqli_field_tell(mysqli_result `$result`): int

Retorna a posição do cursor de campo usado na última chamada a mysqli_fetch_field(). Este valor pode ser usado como um argumento para mysqli_field_seek().

### Parâmetros

`result`
  Somente no estilo procedural: Um objeto mysqli_result retornado por mysqli_query(), mysqli_store_result(), mysqli_use_result() ou mysqli_stmt_get_result().

### Valor Retornado

Retorna o deslocamento atual do cursor de campos.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* verifica a conexão */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = $mysqli->query($query)) {

        /* Obtém informação de campo para todas as colunas */
        while ($finfo = $result->fetch_field()) {

            /* obtém o deslocamento do ponteiro de campos */
            $currentfield = $result->current_field;

            printf("Column %d:\n", $currentfield);
            printf("Name:     %s\n", $finfo->name);
            printf("Table:    %s\n", $finfo->table);
            printf("max. Len: %d\n", $finfo->max_length);
            printf("Flags:    %d\n", $finfo->flags);
            printf("Type:     %d\n\n", $finfo->type);
        }
        $result->close();
    }

    /* fecha a conexão */
    $mysqli->close();
    ?>

Exemplo #2 Estilo procedural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* verifica a conexão */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = mysqli_query($link, $query)) {

        /* Obtém informação de campo para todas as colunas */
        while ($finfo = mysqli_fetch_field($result)) {

            /* obtém o deslocamento do ponteiro de campos */
            $currentfield = mysqli_field_tell($result);

            printf("Column %d:\n", $currentfield);
            printf("Name:     %s\n", $finfo->name);
            printf("Table:    %s\n", $finfo->table);
            printf("max. Len: %d\n", $finfo->max_length);
            printf("Flags:    %d\n", $finfo->flags);
            printf("Type:     %d\n\n", $finfo->type);
        }
        mysqli_free_result($result);
    }

    /* fecha a conexão */
    mysqli_close($link);
    ?>

Os exemplos acima produzirão:

    Column 1:
    Name:     Name
    Table:    Country
    max. Len: 11
    Flags:    1
    Type:     254

    Column 2:
    Name:     SurfaceArea
    Table:    Country
    max. Len: 10
    Flags:    32769
    Type:     4

### Veja Também

- mysqli_fetch_field() - Retorna o próximo campo no conjunto de resultados
- mysqli_field_seek() - Move o ponteiro do resultado para um campo especificado

# mysqli_result::data_seek

# mysqli_data_seek

(PHP 5, PHP 7, PHP 8)

mysqli_result::data_seek -- mysqli_data_seek — Ajusta o ponteiro do resultado para uma linha arbitrária no resultado

### Descrição

Estilo orientado a objetos

public function mysqli_result::data_seek(int `$offset`): bool

Estilo procedural

function mysqli_data_seek(mysqli_result `$result`, int `$offset`): bool

A função mysqli_data_seek() move o ponteiro para uma posição arbritrária especificada pelo parâmetro `offset` no conjunto de resultados.

### Parâmetros

`result`
  Somente no estilo procedural: Um objeto mysqli_result retornado por mysqli_query(), mysqli_store_result(), mysqli_use_result() ou mysqli_stmt_get_result().
`offset`

  O deslocamento de linha. deve estar entre zero e o número total de linhas menos uma (0..mysqli_num_rows() - 1).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de mysqli::data_seek()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name";
    $result = $mysqli->query($query);

    /* Vai até a linha 401 */
    $result->data_seek(400);

    /* Recebe uma única linha */
    $row = $result->fetch_row();

    printf("Cidade: %s  Código do país: %s\n", $row[0], $row[1]);

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name";

    $result = mysqli_query($link, $query);

    /* Vai até a linha 401 */
    mysqli_data_seek($result, 400);

    /* Recebe uma única linha */
    $row = mysqli_fetch_row($result);

    printf ("Cidade: %s  Código do país: %s\n", $row[0], $row[1]);

Os exemplos acima produzirão:

    Cidade: Benin City  Código do país: NGA

Exemplo #2 Ajustando o ponteiro de resultado na iteração

Esta função pode ser útil quando iterar sobre o conjunto de resultados para impor uma ordem customizada ou para retroceder o conjunto de resultados ao iterar múltiplas vezes.

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 15,4";
    $result = $mysqli->query($query);

    /* Itera o conjunto de resultados na ordem inversa */
    for ($row_no = $result->num_rows - 1; $row_no >= 0; $row_no--) {
        $result->data_seek($row_no);

        /* Recebe uma linha */
        $row = $result->fetch_row();

        printf("Cidade: %s  Código do país: %s\n", $row[0], $row[1]);
    }

    /* Redefine o ponteiro para o início do conjunto de resultados */
    $result->data_seek(0);

    print "\n";

    /* Itera o mesmo conjunto novamente */
    while ($row = $result->fetch_row()) {
        printf("Cidade: %s  Código do país: %s\n", $row[0], $row[1]);
    }

Os exemplos acima produzirão:

    Cidade: Acmbaro  Código do país: MEX
    Cidade: Abuja  Código do país: NGA
    Cidade: Abu Dhabi  Código do país: ARE
    Cidade: Abottabad  Código do país: PAK

    Cidade: Abottabad  Código do país: PAK
    Cidade: Abu Dhabi  Código do país: ARE
    Cidade: Abuja  Código do país: NGA
    Cidade: Acmbaro  Código do país: MEX

### Notas

> Nota:

> Esta função somente pode ser usada com resultados em buffer obtidos do uso das funções mysqli_store_result(), mysqli_query() ou mysqli_stmt_get_result().

### Veja Também

- mysqli_store_result() - Transfere um conjunto de resultados da última consulta
- mysqli_fetch_row() - Obtém a próxima linha de um resultado como um array enumerado
- mysqli_fetch_array() - Recebe a próxima linha de resultado como array associativo, numérico, ou ambos
- mysqli_fetch_assoc() - Obtém a próxima linha do conjunto de resultados como um array associativo
- mysqli_fetch_object() - Recebe a próxima linha de um resultado como um objeto
- mysqli_query() - Executa uma consulta no banco de dados
- mysqli_num_rows() - Obtém o número de linhas no resultado

# mysqli_result::fetch_all

# mysqli_fetch_all

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_result::fetch_all -- mysqli_fetch_all — Recebe todas as linhas de resultado como array associativo, numérico, ou ambos

### Descrição

Estilo orientado a objetos

public function mysqli_result::fetch_all(int `$mode` = `MYSQLI_NUM`): array

Estilo procedural

function mysqli_fetch_all(mysqli_result `$result`, int `$mode` = `MYSQLI_NUM`): array

Retorna um array bidimensional com todas as linhas do resultado como um array associativo, numérico, ou ambos.

> Nota:

> Antes do PHP 8.1.0, disponível somente com mysqlnd.

### Parâmetros

`result`
  Somente no estilo procedural: Um objeto mysqli_result retornado por mysqli_query(), mysqli_store_result(), mysqli_use_result() ou mysqli_stmt_get_result().
`mode`

  Este parâmetro opcional é uma constante que indica que tipo de array deve ser produzido a partir dos dados da linha atual. Os valores possíveis para este parâmetro são as constantes `MYSQLI_ASSOC`, `MYSQLI_NUM` ou `MYSQLI_BOTH`.

### Valor Retornado

Retorna um array de arrays associativos ou numéricos com as linhas do resultado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Agora também disponível com a biblioteca libmysqlclient.

### Exemplos

Exemplo #1 Exemplo de mysqli_result::fetch_all()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $result = $mysqli->query("SELECT Name, CountryCode FROM City ORDER BY ID LIMIT 3");

    $rows = $result->fetch_all(MYSQLI_ASSOC);
    foreach ($rows as $row) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $result = mysqli_query($mysqli, "SELECT Name, CountryCode FROM City ORDER BY ID LIMIT 3");

    $rows = mysqli_fetch_all($result, MYSQLI_ASSOC);
    foreach ($rows as $row) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

Os exemplos acima produzirão:

    Kabul (AFG)
    Qandahar (AFG)
    Herat (AFG)

### Veja Também

- mysqli_fetch_array() - Recebe a próxima linha de resultado como array associativo, numérico, ou ambos
- mysqli_fetch_column() - Recebe uma única coluna da próxima linha de um resultado
- mysqli_query() - Executa uma consulta no banco de dados

# mysqli_result::fetch_array

# mysqli_fetch_array

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_array -- mysqli_fetch_array — Recebe a próxima linha de resultado como array associativo, numérico, ou ambos

### Descrição

Estilo orientado a objetos

public function mysqli_result::fetch_array(int `$mode` = `MYSQLI_BOTH`): array|null|false

Estilo procedural

function mysqli_fetch_array(mysqli_result `$result`, int `$mode` = `MYSQLI_BOTH`): array|null|false

Recebe uma linha de dados do conjunto de resultados e retorna-a como um array. Cada chamada subsequente a esta função retornará a linha seguinte dentro do conjunto de resultados, ou `null` se não houver mais linhas.

Além de armazenar os dados nos índices numéricos do array resultante, esta função também pode armazenar os dados em índices associativos usando os nomes dos campos do conjunto de resultados como chaves.

Se duas ou mais colunas do resultado tiverem o mesmo nome, a última coluna terá precedência e irá sobrescrever os dados anteriores. Para acessar múltiplas colunas com o mesmo nome, deve ser usada a versão da linha indexada numericamente.

> Nota: Os nomes de campos retornados por esta função diferenciam maiúsculas e minúsculas.

> Nota: Esta função define campos NULL como o valor `null` do PHP.

### Parâmetros

`result`
  Somente no estilo procedural: Um objeto mysqli_result retornado por mysqli_query(), mysqli_store_result(), mysqli_use_result() ou mysqli_stmt_get_result().
`mode`

  O segundo argumento é uma constante que indica qual tipo de array deve ser produzido a partir dos dados da linha atual. Os valores possíveis para este parâmetro são as constantes `MYSQLI_ASSOC`, `MYSQLI_NUM` ou `MYSQLI_BOTH`.

  Ao usar a constante `MYSQLI_ASSOC`, esta função irá se comportar de modo idêntico à função mysqli_fetch_assoc(), enquanto `MYSQLI_NUM` irá se comportar de modo idêntico à função mysqli_fetch_row(). A opção final `MYSQLI_BOTH` irá criar um único array com os atributos de ambas.

### Valor Retornado

Retorna um array que representa a linha recebida, `null` se não houver mais linhas no resultado, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de mysqli_result::fetch_array()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID LIMIT 3";
    $result = $mysqli->query($query);

    /* array com índice numérico */
    $row = $result->fetch_array(MYSQLI_NUM);
    printf("%s (%s)\n", $row[0], $row[1]);

    /* array associativo */
    $row = $result->fetch_array(MYSQLI_ASSOC);
    printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);

    /* array com índice numérico e associativo */
    $row = $result->fetch_array(MYSQLI_BOTH);
    printf("%s (%s)\n", $row[0], $row["CountryCode"]);

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER by ID LIMIT 3";
    $result = mysqli_query($mysqli, $query);

    /* array com índice numérico */
    $row = mysqli_fetch_array($result, MYSQLI_NUM);
    printf("%s (%s)\n", $row[0], $row[1]);

    /* array associativo */
    $row = mysqli_fetch_array($result, MYSQLI_ASSOC);
    printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);

    /* array com índice numérico e associativo */
    $row = mysqli_fetch_array($result, MYSQLI_BOTH);
    printf("%s (%s)\n", $row[0], $row["CountryCode"]);

Os exemplos acima produzirão algo semelhante a:

    Kabul (AFG)
    Qandahar (AFG)
    Herat (AFG)

### Veja Também

- mysqli_fetch_assoc() - Obtém a próxima linha do conjunto de resultados como um array associativo
- mysqli_fetch_column() - Recebe uma única coluna da próxima linha de um resultado
- mysqli_fetch_row() - Obtém a próxima linha de um resultado como um array enumerado
- mysqli_fetch_object() - Recebe a próxima linha de um resultado como um objeto
- mysqli_query() - Executa uma consulta no banco de dados
- mysqli_data_seek() - Ajusta o ponteiro do resultado para uma linha arbitrária no resultado

# mysqli_result::fetch_assoc

# mysqli_fetch_assoc

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_assoc -- mysqli_fetch_assoc — Obtém a próxima linha do conjunto de resultados como um array associativo

### Descrição

Estilo orientado a objetos

public function mysqli_result::fetch_assoc(): array|null|false

Estilo procedural

function mysqli_fetch_assoc(mysqli_result `$result`): array|null|false

Obtém uma linha de dados do conjunto de resultados e retorna-o como um array associativo. Cada chamada subsequente desta função retornará a linha seguinte do conjunto de resultados, ou `null` se não houver mais linhas.

Se duas ou mais colunas do resultado tiverem o mesmo nome, a última coluna terá precedência e irá sobrescrever qualquer dado anterior. Para acessar múltiplas colunas com o mesmo nome, mysqli_fetch_row() pode ser usada para obter o array indexado numericamente, ou apelidos podem ser usados na lista de seleção da consulta SQL para dar nomes diferentes às colunas.

> Nota: Os nomes de campos retornados por esta função diferenciam maiúsculas e minúsculas.

> Nota: Esta função define campos NULL como o valor `null` do PHP.

### Parâmetros

`result`
  Somente no estilo procedural: Um objeto mysqli_result retornado por mysqli_query(), mysqli_store_result(), mysqli_use_result() ou mysqli_stmt_get_result().

### Valor Retornado

Retorna um array associativo que representa a linha obtida, onde cada chave no array representa o nome de uma das colunas do conjunto de resultados; `null` se não houver mais linhas no conjunto de resultados, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de mysqli_result::fetch_assoc()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = $mysqli->query($query);

    /* obtém o array associativo */
    while ($row = $result->fetch_assoc()) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = mysqli_query($mysqli, $query);

    /* obtém o array associativo */
    while ($row = mysqli_fetch_assoc($result)) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

Os exemplos acima produzirão algo semelhante a:

    Pueblo (USA)
    Arvada (USA)
    Cape Coral (USA)
    Green Bay (USA)
    Santa Clara (USA)

Exemplo #2 Comparação de mysqli_result iterator e uso de mysqli_result::fetch_assoc()

mysqli_result pode ser iterada usando-se `foreach`. O conjunto de resultados será iterado sempre a partir da primeira linha, independente da posição atual do ponteiro.

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = 'SELECT Name, CountryCode FROM City ORDER BY ID DESC';

    // Usando iterardores
    $result = $mysqli->query($query);
    foreach ($result as $row) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

    echo "\n==================\n";

    // Não usando iteradores
    $result = $mysqli->query($query);
    while ($row = $result->fetch_assoc()) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

O exemplo acima produzirá algo semelhante a:

    Pueblo (USA)
    Arvada (USA)
    Cape Coral (USA)
    Green Bay (USA)
    Santa Clara (USA)

    ==================
    Pueblo (USA)
    Arvada (USA)
    Cape Coral (USA)
    Green Bay (USA)
    Santa Clara (USA)

### Veja Também

- mysqli_fetch_array() - Recebe a próxima linha de resultado como array associativo, numérico, ou ambos
- mysqli_fetch_column() - Recebe uma única coluna da próxima linha de um resultado
- mysqli_fetch_row() - Obtém a próxima linha de um resultado como um array enumerado
- mysqli_fetch_object() - Recebe a próxima linha de um resultado como um objeto
- mysqli_query() - Executa uma consulta no banco de dados
- mysqli_data_seek() - Ajusta o ponteiro do resultado para uma linha arbitrária no resultado

# mysqli_result::fetch_column

# mysqli_fetch_column

(PHP 8 >= 8.1.0)

mysqli_result::fetch_column -- mysqli_fetch_column — Recebe uma única coluna da próxima linha de um resultado

### Descrição

Estilo orientado a objetos

public function mysqli_result::fetch_column(int `$column` = 0): null|int|float|string|false

Estilo procedural

function mysqli_fetch_column(mysqli_result `$result`, int `$column` = 0): null|int|float|string|false

Recebe uma linha de dados do resultado e retorna a coluna indexada a partir de 0. Cada chamada subsequente desta função retornará o valor da linha seguinte dentro do conjunto de resultados, ou `false` se não houver mais linhas.

> Nota: Esta função define campos NULL como o valor `null` do PHP.

### Parâmetros

`result`
  Somente no estilo procedural: Um objeto mysqli_result retornado por mysqli_query(), mysqli_store_result(), mysqli_use_result() ou mysqli_stmt_get_result().
`column`

  Número da coluna que se deseja receber da linha, sendo que a primeira é indexada em 0. Se nenhum valor for fornecido, a primeira coluna será retornada.

### Valor Retornado

Retorna uma única coluna da próxima linha de um conjunto de resultados ou `false` se não houver mais linhas.

Aviso

Não há como retornar outra coluna da mesma linha se esta função for usada para obter dados.

### Exemplos

Exemplo #1 Exemplo de mysqli_result::fetch_column()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT CountryCode, Name FROM City ORDER BY ID DESC LIMIT 5";

    $result = $mysqli->query($query);

    /* recebe um único valor da segunda coluna */
    while ($Name = $result->fetch_column(1)) {
        printf("%s\n", $Name);
    }

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT CountryCode, Name FROM City ORDER BY ID DESC LIMIT 5";

    $result = mysqli_query($mysqli, $query);

    /* recebe um único valor da segunda coluna */
    while ($Name = mysqli_fetch_column($result, 1)) {
        printf("%s\n", $Name);
    }

Os exemplos acima produzirão algo semelhante a:

    Rafah
    Nablus
    Jabaliya
    Hebron
    Khan Yunis

### Veja Também

- mysqli_fetch_all() - Recebe todas as linhas de resultado como array associativo, numérico, ou ambos
- mysqli_fetch_array() - Recebe a próxima linha de resultado como array associativo, numérico, ou ambos
- mysqli_fetch_assoc() - Obtém a próxima linha do conjunto de resultados como um array associativo
- mysqli_fetch_object() - Recebe a próxima linha de um resultado como um objeto
- mysqli_fetch_row() - Obtém a próxima linha de um resultado como um array enumerado
- mysqli_data_seek() - Ajusta o ponteiro do resultado para uma linha arbitrária no resultado

# mysqli_result::fetch_field

# mysqli_fetch_field

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_field -- mysqli_fetch_field — Retorna o próximo campo no conjunto de resultados

### Descrição

Estilo orientado a objetos

public function mysqli_result::fetch_field(): object|false

Estilo procedural

function mysqli_fetch_field(mysqli_result `$result`): object|false

Retorna a definição de uma coluna de um conjunto de resultados como um objeto. Utilize esta função repetidamente para obter informação sobre todas as colunas no conjunto de resultados.

### Parâmetros

`result`
  Somente no estilo procedural: Um objeto mysqli_result retornado por mysqli_query(), mysqli_store_result(), mysqli_use_result() ou mysqli_stmt_get_result().

### Valor Retornado

Retorna um objeto que contém informações sobre a definição do campo ou `false` se nenhuma informação de campos estiver disponível.

Propriedades dos objetos
Propriedade | Descrição
--- | ---
name | O nome da coluna
orgname | O nome original da coluna se foi especificado um apelido
table | O nome da tabela à qual o campo pertence (se não calculado)
orgtable | Nome da tabela original se foi especificado um apelido
def | Não utilizado. Sempre uma string vazia
db | O nome do banco de dados
catalog | Não utilizado. Sempre `"def"`
max_length | A largura máxima do campo para o conjunto de resultados. A partir do PHP 8.1, este valor é sempre `0`.
length | O comprimento do campo em bytes. Para colunas de strings, o valor do comprimento varia conforme o conjunto de caracteres. Por exemplo, se o conjunto de caracteres for `latin1`, um conjunto de um byte, o valor de comprimento para uma consulta `SELECT 'abc'` será 3. Se o conjunto for `utf8mb4`, um conjunto multi-bytes onde os caracteres podem ter até 4 bytes, o valor de comprimento será 12.
charsetnr | O número do conjunto de caracteres do campo.
flags | Um inteiro representando bits de opções para o campo.
type | O tipo de dados usado para este campo
decimals | O número de decimais para campos numéricos, e a precisão em segundos fracionários para campos temporais.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* verifica a conexão */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = $mysqli->query($query)) {

        /* Obtém informação do campo para todos os campos */
        while ($finfo = $result->fetch_field()) {

            printf("Name:     %s\n", $finfo->name);
            printf("Table:    %s\n", $finfo->table);
            printf("max. Len: %d\n", $finfo->max_length);
            printf("Flags:    %d\n", $finfo->flags);
            printf("Type:     %d\n\n", $finfo->type);
        }
        $result->close();
    }

    /* fecha a conexão */
    $mysqli->close();
    ?>

Exemplo #2 Estilo procedural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* verifica a conexão */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = mysqli_query($link, $query)) {

        /* Obtém informação do campo para todos os campos */
        while ($finfo = mysqli_fetch_field($result)) {

            printf("Name:     %s\n", $finfo->name);
            printf("Table:    %s\n", $finfo->table);
            printf("max. Len: %d\n", $finfo->max_length);
            printf("Flags:    %d\n", $finfo->flags);
            printf("Type:     %d\n\n", $finfo->type);
        }
        mysqli_free_result($result);
    }

    /* fecha a conexão */
    mysqli_close($link);
    ?>

Os exemplos acima produzirão:

    Name:     Name
    Table:    Country
    max. Len: 11
    Flags:    1
    Type:     254

    Name:     SurfaceArea
    Table:    Country
    max. Len: 10
    Flags:    32769
    Type:     4

### Veja Também

- mysqli_num_fields() - Obtém o número de campos no conjunto de resultados
- mysqli_fetch_field_direct() - Recebe metadados para um único campo
- mysqli_fetch_fields() - Retorna um array de objetos representando os campos em um conjunto de resultados
- mysqli_field_seek() - Move o ponteiro do resultado para um campo especificado

# mysqli_result::fetch_field_direct

# mysqli_fetch_field_direct

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_field_direct -- mysqli_fetch_field_direct — Recebe metadados para um único campo

### Descrição

Estilo orientado a objetos

public function mysqli_result::fetch_field_direct(int `$index`): object|false

Estilo procedural

function mysqli_fetch_field_direct(mysqli_result `$result`, int `$index`): object|false

Retorna um objeto que contém informação de definição de campo a partir do conjunto de resultados especificado.

### Parâmetros

`result`
  Somente no estilo procedural: Um objeto mysqli_result retornado por mysqli_query(), mysqli_store_result(), mysqli_use_result() ou mysqli_stmt_get_result().
`index`

  O número do campo. Este valor deve estar na faixa de `0` a `número de campos - 1`.

### Valor Retornado

Retorna um objeto que contém informação de definição de campo ou `false` se nenhuma informação de campo para o valor especificado em `index` estiver disponível.

Propriedades dos objetos
Propriedade | Descrição
--- | ---
name | O nome da coluna
orgname | O nome original da coluna se foi especificado um apelido
table | O nome da tabela à qual o campo pertence (se não calculado)
orgtable | Nome da tabela original se foi especificado um apelido
def | Não utilizado. Sempre uma string vazia
db | O nome do banco de dados
catalog | Não utilizado. Sempre `"def"`
max_length | A largura máxima do campo para o conjunto de resultados. A partir do PHP 8.1, este valor é sempre `0`.
length | O comprimento do campo em bytes. Para colunas de strings, o valor do comprimento varia conforme o conjunto de caracteres. Por exemplo, se o conjunto de caracteres for `latin1`, um conjunto de um byte, o valor de comprimento para uma consulta `SELECT 'abc'` será 3. Se o conjunto for `utf8mb4`, um conjunto multi-bytes onde os caracteres podem ter até 4 bytes, o valor de comprimento será 12.
charsetnr | O número do conjunto de caracteres do campo.
flags | Um inteiro representando bits de opções para o campo.
type | O tipo de dados usado para este campo
decimals | O número de decimais para campos numéricos, e a precisão em segundos fracionários para campos temporais.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* verifica a conexão */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Name LIMIT 5";

    if ($result = $mysqli->query($query)) {

        /* Obtém informação de campo para a coluna 'SurfaceArea' */
        $finfo = $result->fetch_field_direct(1);

        printf("Name:     %s\n", $finfo->name);
        printf("Table:    %s\n", $finfo->table);
        printf("max. Len: %d\n", $finfo->max_length);
        printf("Flags:    %d\n", $finfo->flags);
        printf("Type:     %d\n", $finfo->type);

        $result->close();
    }

    /* fecha a conexão */
    $mysqli->close();
    ?>

Exemplo #2 Estilo procedural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* verifica a conexão */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Name LIMIT 5";

    if ($result = mysqli_query($link, $query)) {

        /* Obtém informação de campo para a coluna 'SurfaceArea' */
        $finfo = mysqli_fetch_field_direct($result, 1);

        printf("Name:     %s\n", $finfo->name);
        printf("Table:    %s\n", $finfo->table);
        printf("max. Len: %d\n", $finfo->max_length);
        printf("Flags:    %d\n", $finfo->flags);
        printf("Type:     %d\n", $finfo->type);

        mysqli_free_result($result);
    }

    /* fecha a conexão */
    mysqli_close($link);
    ?>

Os exemplos acima produzirão:

    Name:     SurfaceArea
    Table:    Country
    max. Len: 10
    Flags:    32769
    Type:     4

### Veja Também

- mysqli_num_fields() - Obtém o número de campos no conjunto de resultados
- mysqli_fetch_field() - Retorna o próximo campo no conjunto de resultados
- mysqli_fetch_fields() - Retorna um array de objetos representando os campos em um conjunto de resultados

# mysqli_result::fetch_fields

# mysqli_fetch_fields

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_fields -- mysqli_fetch_fields — Retorna um array de objetos representando os campos em um conjunto de resultados

### Descrição

Estilo orientado a objetos

public function mysqli_result::fetch_fields(): array

Estilo procedural

function mysqli_fetch_fields(mysqli_result `$result`): array

Esta função serve para o mesmo propósito que a função mysqli_fetch_field() com uma simples diferença, ao invés de retornar um objeto de cada vez para cada campo, as colunas são retornadas como um array de objetos.

### Parâmetros

`result`
  Somente no estilo procedural: Um objeto mysqli_result retornado por mysqli_query(), mysqli_store_result(), mysqli_use_result() ou mysqli_stmt_get_result().

### Valor Retornado

Retorna um array de objetos contendo informações de definições de campo.

Propriedades dos objetos
Propriedade | Descrição
--- | ---
name | O nome da coluna
orgname | O nome original da coluna se foi especificado um apelido
table | O nome da tabela à qual o campo pertence (se não calculado)
orgtable | Nome da tabela original se foi especificado um apelido
def | Não utilizado. Sempre uma string vazia
db | O nome do banco de dados
catalog | Não utilizado. Sempre `"def"`
max_length | A largura máxima do campo para o conjunto de resultados. A partir do PHP 8.1, este valor é sempre `0`.
length | O comprimento do campo em bytes. Para colunas de strings, o valor do comprimento varia conforme o conjunto de caracteres. Por exemplo, se o conjunto de caracteres for `latin1`, um conjunto de um byte, o valor de comprimento para uma consulta `SELECT 'abc'` será 3. Se o conjunto for `utf8mb4`, um conjunto multi-bytes onde os caracteres podem ter até 4 bytes, o valor de comprimento será 12.
charsetnr | O número do conjunto de caracteres do campo.
flags | Um inteiro representando bits de opções para o campo.
type | O tipo de dados usado para este campo
decimals | O número de decimais para campos numéricos, e a precisão em segundos fracionários para campos temporais.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("127.0.0.1", "root", "foofoo", "sakila");

    /*verifica a conexão */
    if ($mysqli->connect_errno) {
        printf("Conexão falhou: %s\n", $mysqli->connect_error);
        exit();
    }

    foreach (array('latin1', 'utf8') as $charset) {

        // Define o conjunto de caracteres, para mostrar seu impacto em alguns valores (ex.: comprimento em bytes)
        $mysqli->set_charset($charset);

        $query = "SELECT actor_id, last_name from actor ORDER BY actor_id";

        echo "======================\n";
        echo "Conjunto de Caracteres: $charset\n";
        echo "======================\n";

        if ($result = $mysqli->query($query)) {

            /* Obtém informação de campo para todas as colunas */
            $finfo = $result->fetch_fields();

            foreach ($finfo as $val) {
                printf("Nome:        %s\n",   $val->name);
                printf("Tabela:      %s\n",   $val->table);
                printf("Comp. máx:   %d\n",   $val->max_length);
                printf("Comprimento: %d\n",   $val->length);
                printf("Id conj. carac: %d\n",   $val->charsetnr);
                printf("Opções:      %d\n",   $val->flags);
                printf("Tipo:        %d\n\n", $val->type);
            }
            $result->free();
        }
    }
    $mysqli->close();
    ?>

Exemplo #2 Estilo procedural

    <?php
    $link = mysqli_connect("127.0.0.1", "my_user", "my_password", "sakila");

    /*verifica a conexão */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    foreach (array('latin1', 'utf8') as $charset) {

        // Define o conjunto de caracteres, para mostrar seu impacto em alguns valores (ex.: comprimento em bytes)
        mysqli_set_charset($link, $charset);

        $query = "SELECT actor_id, last_name from actor ORDER BY actor_id";

        echo "======================\n";
        echo "Conjunto de Caracteres: $charset\n";
        echo "======================\n";

        if ($result = mysqli_query($link, $query)) {

            /* Obtém informação de campo para todas as colunas */
            $finfo = mysqli_fetch_fields($result);

            foreach ($finfo as $val) {
                printf("Nome:        %s\n",   $val->name);
                printf("Tabela:      %s\n",   $val->table);
                printf("Comp. máx:   %d\n",   $val->max_length);
                printf("Comprimento: %d\n",   $val->length);
                printf("Id conj. carac: %d\n",   $val->charsetnr);
                printf("Opções:      %d\n",   $val->flags);
                printf("Tipo:        %d\n\n", $val->type);
            }
            mysqli_free_result($result);
        }
    }

    mysqli_close($link);
    ?>

Os exemplos acima produzirão:

    ======================
    Conjunto de Caracteres: latin1
    ======================
    Nome:        actor_id
    Tabela:      actor
    Comp. máx:   3
    Comprimento: 5
    Id conj. carac: 63
    Opções:      49699
    Tipo:        2

    Nome:        last_name
    Tabela:      actor
    Comp. máx:   12
    Comprimento: 45
    Id conj. carac: 8
    Opções:      20489
    Tipo:        253

    ======================
    Conjunto de Caracteres: utf8
    ======================
    Nome:        actor_id
    Tabela:      actor
    Comp. máx:   3
    Comprimento: 5
    Id conj. carac: 63
    Opções:      49699
    Tipo:        2

    Nome:        last_name
    Tabela:      actor
    Comp. máx:   12
    Comprimento: 135
    Id conj. carac: 33
    Opções:      20489

### Veja Também

- mysqli_num_fields() - Obtém o número de campos no conjunto de resultados
- mysqli_fetch_field_direct() - Recebe metadados para um único campo
- mysqli_fetch_field() - Retorna o próximo campo no conjunto de resultados

# mysqli_result::fetch_object

# mysqli_fetch_object

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_object -- mysqli_fetch_object — Recebe a próxima linha de um resultado como um objeto

### Descrição

Estilo orientado a objetos

public function mysqli_result::fetch_object(string `$class` = "stdClass", array `$constructor_args` = []): object|null|false

Estilo procedural

function mysqli_fetch_object(mysqli_result `$result`, string `$class` = "stdClass", array `$constructor_args` = []): object|null|false

Recebe uma linha de dados do resultado e retorna-a como um objeto, onde cada propriedade representa o nome da coluna do resultado. Cada chamada subsequente a esta função retornará a linha seguinte dentro do conjunto de resultados, ou `null` se não houver mais linhas.

Se duas ou mais colunas do resultado tiverem o mesmo nome, a última coluna terá precedência e irá sobrescrever os dados anteriores. Para acessar múltiplas colunas com o mesmo nome, mysqli_fetch_row() pode ser usada para receber o array indexado numericamente, ou apelidos podem ser usados na lista de seleção da consulta SQL para dar nomes diferentes às colunas.

> Nota: Esta função define as propriedades do objeto antes de chamar o construtor do objeto.

> Nota: Os nomes de campos retornados por esta função diferenciam maiúsculas e minúsculas.

> Nota: Esta função define campos NULL como o valor `null` do PHP.

### Parâmetros

`result`
  Somente no estilo procedural: Um objeto mysqli_result retornado por mysqli_query(), mysqli_store_result(), mysqli_use_result() ou mysqli_stmt_get_result().
`class`

  O nome da classe a instanciar, definir propriedades e retornar. Se não especificada, um objeto stdClass é retornado.

`constructor_args`

  Um array opcional de parâmetros para passar ao construtor de objetos da classe definida em `class`.

### Valor Retornado

Retorna um objeto que representa a linha recebida, onde cada propriedade representa o nome da coluna do resultado, `null` se não houver mais colunas no resultado, ou `false` em caso de falha.

### Erros/Exceções

Um exceção ValueError é lançada quando o parâmetro `constructor_args` é não vazio com a classe não possuindo construtor.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Agora lança uma exceção ValueError quando o parâmetro `constructor_args` é não vazio com a classe não possuindo construtor; anteriormente uma Exception era lançada.
8.0.0 | `constructor_args` agora aceita `[]` para construtores sem parâmetros; anteriormente, uma exceção era lançada.

### Exemplos

Exemplo #1 Exemplo de mysqli_result::fetch_object()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = $mysqli->query($query);

    while ($obj = $result->fetch_object()) {
        printf("%s (%s)\n", $obj->Name, $obj->CountryCode);
    }

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = mysqli_query($link, $query);

    while ($obj = mysqli_fetch_object($result)) {
        printf("%s (%s)\n", $obj->Name, $obj->CountryCode);
    }

Os exemplos acima produzirão algo semelhante a:

    Pueblo (USA)
    Arvada (USA)
    Cape Coral (USA)
    Green Bay (USA)
    Santa Clara (USA)

### Veja Também

- mysqli_fetch_array() - Recebe a próxima linha de resultado como array associativo, numérico, ou ambos
- mysqli_fetch_assoc() - Obtém a próxima linha do conjunto de resultados como um array associativo
- mysqli_fetch_column() - Recebe uma única coluna da próxima linha de um resultado
- mysqli_fetch_row() - Obtém a próxima linha de um resultado como um array enumerado
- mysqli_query() - Executa uma consulta no banco de dados
- mysqli_data_seek() - Ajusta o ponteiro do resultado para uma linha arbitrária no resultado

# mysqli_result::fetch_row

# mysqli_fetch_row

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_row -- mysqli_fetch_row — Obtém a próxima linha de um resultado como um array enumerado

### Descrição

Estilo orientado a objetos

public function mysqli_result::fetch_row(): array|null|false

Estilo procedural

function mysqli_fetch_row(mysqli_result `$result`): array|null|false

Obtém uma linha de dados do conjunto de resultado e retorna-o como um array enumerado, onde cada coluna é armazenada em um deslocamento do array iniciando de 0 (zero). Cada chamada subsequente a esta função retornará a próxima linha no conjunto de resultados, ou `null` se não houver mais linhas.

> Nota: Esta função define campos NULL como o valor `null` do PHP.

### Parâmetros

`result`
  Somente no estilo procedural: Um objeto mysqli_result retornado por mysqli_query(), mysqli_store_result(), mysqli_use_result() ou mysqli_stmt_get_result().

### Valor Retornado

Retorna um array representando a linha obtida, `null` se não houver mais linhas no conjunto de resultados, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de mysqli_result::fetch_row()

Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = $mysqli->query($query);

    /* obtém array de objetos */
    while ($row = $result->fetch_row()) {
        printf("%s (%s)\n", $row[0], $row[1]);
    }

Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = mysqli_query($mysqli, $query);

    /* obtém array de objetos */
    while ($row = mysqli_fetch_row($result)) {
        printf("%s (%s)\n", $row[0], $row[1]);
    }

Os exemplos acima produzirão algo semelhante a:

    Pueblo (USA)
    Arvada (USA)
    Cape Coral (USA)
    Green Bay (USA)
    Santa Clara (USA)

### Veja Também

- mysqli_fetch_array() - Recebe a próxima linha de resultado como array associativo, numérico, ou ambos
- mysqli_fetch_assoc() - Obtém a próxima linha do conjunto de resultados como um array associativo
- mysqli_fetch_column() - Recebe uma única coluna da próxima linha de um resultado
- mysqli_fetch_object() - Recebe a próxima linha de um resultado como um objeto
- mysqli_query() - Executa uma consulta no banco de dados
- mysqli_data_seek() - Ajusta o ponteiro do resultado para uma linha arbitrária no resultado

# mysqli_result::$field_count

# mysqli_num_fields

(PHP 5, PHP 7, PHP 8)

mysqli_result::$field_count -- mysqli_num_fields — Obtém o número de campos no conjunto de resultados

### Descrição

Estilo orientado a objetos

int $mysqli_result->field_count;

Estilo procedural

function mysqli_num_fields(mysqli_result `$result`): int

Obtém o número de campos no conjunto de resultados.

### Parâmetros

`result`
  Somente no estilo procedural: Um objeto mysqli_result retornado por mysqli_query(), mysqli_store_result(), mysqli_use_result() ou mysqli_stmt_get_result().

### Valor Retornado

Um valor do tipo int que representa o número de campos.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $result = $mysqli->query("SELECT Name, CountryCode, District, Population FROM City ORDER BY ID LIMIT 1");

    /* Obtém o número de campos do resultado */
    $field_cnt = $result->field_count;

    printf("O conjunto de resultados tem %d campos.\n", $field_cnt);

Exemplo #2 Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $result = mysqli_query($link, "SELECT Name, CountryCode, District, Population FROM City ORDER BY ID LIMIT 1");

    /* Obtém o número de campos do resultado */
    $field_cnt = mysqli_num_fields($result);

    printf("O conjunto de resultados tem %d campos.\n", $field_cnt);

Os exemplos acima produzirão:

    O conjunto de resultados tem 4 campos.

### Veja Também

- mysqli_fetch_field() - Retorna o próximo campo no conjunto de resultados

# mysqli_result::field_seek

# mysqli_field_seek

(PHP 5, PHP 7, PHP 8)

mysqli_result::field_seek -- mysqli_field_seek — Move o ponteiro do resultado para um campo especificado

### Descrição

Estilo orientado a objetos

public function mysqli_result::field_seek(int `$index`): true

Estilo procedural

function mysqli_field_seek(mysqli_result `$result`, int `$index`): true

Define o cursor de campo para o índice especificado. A próxima chamada a mysqli_fetch_field() retornará a definição de campo da coluna associada com este índice.

> Nota:

> Para mover o ponteiro para o início de uma linha, passe um índice de valor zero.

### Parâmetros

`result`
  Somente no estilo procedural: Um objeto mysqli_result retornado por mysqli_query(), mysqli_store_result(), mysqli_use_result() ou mysqli_stmt_get_result().
`index`

  O número do campo. Este valor precisa estar num intervalo de `0` a `número de campos - 1`.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Esta função agora sempre retorna `true`. Anteriormente retornava `false` em caso de falha.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* verifica a conexão */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = $mysqli->query($query)) {

        /* Obtém informação de campo para a 2ª coluna */
        $result->field_seek(1);
        $finfo = $result->fetch_field();

        printf("Name:     %s\n", $finfo->name);
        printf("Table:    %s\n", $finfo->table);
        printf("max. Len: %d\n", $finfo->max_length);
        printf("Flags:    %d\n", $finfo->flags);
        printf("Type:     %d\n\n", $finfo->type);

        $result->close();
    }

    /* fecha a conexão */
    $mysqli->close();
    ?>

Exemplo #2 Estilo procedural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* verifica a conexão */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = mysqli_query($link, $query)) {

        /* Obtém informação de campo para a 2ª coluna */
        mysqli_field_seek($result, 1);
        $finfo = mysqli_fetch_field($result);

        printf("Name:     %s\n", $finfo->name);
        printf("Table:    %s\n", $finfo->table);
        printf("max. Len: %d\n", $finfo->max_length);
        printf("Flags:    %d\n", $finfo->flags);
        printf("Type:     %d\n\n", $finfo->type);

        mysqli_free_result($result);
    }

    /* fecha a conexão */
    mysqli_close($link);
    ?>

Os exemplos acima produzirão:

    Name:     SurfaceArea
    Table:    Country
    max. Len: 10
    Flags:    32769
    Type:     4

### Veja Também

- mysqli_fetch_field() - Retorna o próximo campo no conjunto de resultados

# mysqli_result::free

# mysqli_result::close

# mysqli_result::free_result

# mysqli_free_result

(PHP 5, PHP 7, PHP 8)

mysqli_result::free -- mysqli_result::close -- mysqli_result::free_result -- mysqli_free_result — Libera memória associada a um resultado

### Descrição

Estilo orientado a objetos

public function mysqli_result::free(): void
public function mysqli_result::close(): void
public function mysqli_result::free_result(): void

Estilo procedural

function mysqli_free_result(mysqli_result `$result`): void

Libera a memória associada ao resultado.

### Parâmetros

`result`
  Somente no estilo procedural: Um objeto mysqli_result retornado por mysqli_query(), mysqli_store_result(), mysqli_use_result() ou mysqli_stmt_get_result().

### Valor Retornado

Nenhum valor é retornado.

### Veja Também

- mysqli_query() - Executa uma consulta no banco de dados
- mysqli_stmt_get_result() - Obtém um resultado de uma instrução preparada como um objeto mysqli_result
- mysqli_store_result() - Transfere um conjunto de resultados da última consulta
- mysqli_use_result() - Iniciar uma recuperação de conjunto de resultados

# mysqli_result::getIterator

(PHP 8)

mysqli_result::getIterator — Obtém um iterador externo

### Descrição

public function mysqli_result::getIterator(): Iterator

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# mysqli_result::$lengths

# mysqli_fetch_lengths

(PHP 5, PHP 7, PHP 8)

mysqli_result::$lengths -- mysqli_fetch_lengths — Retorna os comprimentos das colunas da linha atual do resultado

### Descrição

Estilo orientado a objetos

?array $mysqli_result->lengths;

Estilo procedural

function mysqli_fetch_lengths(mysqli_result `$result`): array|false

A função mysqli_fetch_lengths() retorna um array que contém os comprimentos de cada coluna da linha atual dentro do conjunto de resultados.

### Parâmetros

`result`
  Somente no estilo procedural: Um objeto mysqli_result retornado por mysqli_query(), mysqli_store_result(), mysqli_use_result() ou mysqli_stmt_get_result().

### Valor Retornado

Um array de números inteiros que representam o tamanho de cada coluna (não incluindo caracteres nulos de terminação). `false` se ocorrer um erro.

mysqli_fetch_lengths() é válida apenas para a linha atual do resultado. Retorna `false` se for chamada antes de se chamar mysqli_fetch_row, mysqli_fetch_array, mysqli_fetch_object ou após ter recebido todas as linhas do resultado.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* verifica a conexão */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT * from Country ORDER BY Code LIMIT 1";

    if ($result = $mysqli->query($query)) {

        $row = $result->fetch_row();

        /* mostra os comprimentos das colunas */
        foreach ($result->lengths as $i => $val) {
            printf("Campo %2d tem comprimento %2d\n", $i+1, $val);
        }
        $result->close();
    }

    /* fecha a conexão */
    $mysqli->close();
    ?>

Exemplo #2 Estilo procedural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* verifica a conexão */
    if (mysqli_connect_errno()) {
        printf("Conexão falhou: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT * from Country ORDER BY Code LIMIT 1";

    if ($result = mysqli_query($link, $query)) {

        $row = mysqli_fetch_row($result);

        /* mostra os comprimentos das colunas */
        foreach (mysqli_fetch_lengths($result) as $i => $val) {
            printf("Campo %2d tem comprimento %2d\n", $i+1, $val);
        }
        mysqli_free_result($result);
    }

    /* fecha a conexão */
    mysqli_close($link);
    ?>

Os exemplos acima produzirão:

    Campo  1 tem comprimento  3
    Campo  2 tem comprimento  5
    Campo  3 tem comprimento 13
    Campo  4 tem comprimento  9
    Campo  5 tem comprimento  6
    Campo  6 tem comprimento  1
    Campo  7 tem comprimento  6
    Campo  8 tem comprimento  4
    Campo  9 tem comprimento  6
    Campo 10 tem comprimento  6
    Campo 11 tem comprimento  5
    Campo 12 tem comprimento 44
    Campo 13 tem comprimento  7
    Campo 14 tem comprimento  3
    Campo 15 tem comprimento  2

# mysqli_result::$num_rows

# mysqli_num_rows

(PHP 5, PHP 7, PHP 8)

mysqli_result::$num_rows -- mysqli_num_rows — Obtém o número de linhas no resultado

### Descrição

Estilo orientado a objetos

int|string $mysqli_result->num_rows;

Estilo procedural

function mysqli_num_rows(mysqli_result `$result`): int|string

Retorna o número de linhas no resultado.

O comportamento de mysqli_num_rows() depende se estão sendo usados resultados com buffer ou sem buffer. A função retorna `0` para resultado sem buffer a menos que todas as linhas já tiverem sido recebidas do servidor.

### Parâmetros

`result`
  Somente no estilo procedural: Um objeto mysqli_result retornado por mysqli_query(), mysqli_store_result(), mysqli_use_result() ou mysqli_stmt_get_result().

### Valor Retornado

Um int que representa o número de linhas recebidas. Retorna `0` em modo sem buffer a menos que todas as linhas tenham sido recebidas do servidor.

> Nota: Se o número de linhas for maior que `PHP_INT_MAX`, o número será retornado como uma string.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $result = $mysqli->query("SELECT Code, Name FROM Country ORDER BY Name");

    /* Obtém o número de linhas no resultado */
    $row_cnt = $result->num_rows;

    printf("Resultado contém %d linhas.\n", $row_cnt);

Exemplo #2 Estilo procedural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $result = mysqli_query($link, "SELECT Code, Name FROM Country ORDER BY Name");

    /* Obtém o número de linhas no resultado */
    $row_cnt = mysqli_num_rows($result);

    printf("Resultado contém %d linhas.\n", $row_cnt);

Os exemplos acima produzirão:

    Resultado contém 239 linhas.

### Notas

> Nota:

> Em contraste à função mysqli_stmt_num_rows(), esta função não tem uma variante de método orientado a objetos. No estilo de linguagem orientada a objetos, use __get().

### Veja Também

- mysqli_affected_rows() - Retorna o número de linhas afetadas pela operação MySQL anterior
- mysqli_store_result() - Transfere um conjunto de resultados da última consulta
- mysqli_use_result() - Iniciar uma recuperação de conjunto de resultados
- mysqli_query() - Executa uma consulta no banco de dados
- mysqli_stmt_num_rows() - Retorna o número de linhas recebidas pelo servidor

## Índice

- mysqli_result::__construct — Constrói um objeto mysqli_result
- mysqli_result::$current_field — Obtém o deslocamento atual de campo de um ponteiro de resultado
- mysqli_result::data_seek — Ajusta o ponteiro do resultado para uma linha arbitrária no resultado
- mysqli_result::fetch_all — Recebe todas as linhas de resultado como array associativo, numérico, ou ambos
- mysqli_result::fetch_array — Recebe a próxima linha de resultado como array associativo, numérico, ou ambos
- mysqli_result::fetch_assoc — Obtém a próxima linha do conjunto de resultados como um array associativo
- mysqli_result::fetch_column — Recebe uma única coluna da próxima linha de um resultado
- mysqli_result::fetch_field — Retorna o próximo campo no conjunto de resultados
- mysqli_result::fetch_field_direct — Recebe metadados para um único campo
- mysqli_result::fetch_fields — Retorna um array de objetos representando os campos em um conjunto de resultados
- mysqli_result::fetch_object — Recebe a próxima linha de um resultado como um objeto
- mysqli_result::fetch_row — Obtém a próxima linha de um resultado como um array enumerado
- mysqli_result::$field_count — Obtém o número de campos no conjunto de resultados
- mysqli_result::field_seek — Move o ponteiro do resultado para um campo especificado
- mysqli_result::free — Libera memória associada a um resultado
- mysqli_result::getIterator — Obtém um iterador externo
- mysqli_result::$lengths — Retorna os comprimentos das colunas da linha atual do resultado
- mysqli_result::$num_rows — Obtém o número de linhas no resultado

# A classe mysqli_driver

(PHP 5, PHP 7, PHP 8)

## Introdução

A classe mysqli_driver é uma instância do padrão monostate, ou seja, existe apenas um driver que pode ser acessado por meio de uma quantidade arbitrária de instâncias mysqli_driver.

## Resumo da classe

final class mysqli_driver {
/* Propriedades */
public readonly string $client_info;
public readonly int $client_version;
public readonly int $driver_version;
public int $report_mode;
}

## Propriedades

client_info

  A versão do cabeçalho da API do cliente

client_version

  A versão do cliente

driver_version

  A versão do driver MySQLi

  Aviso

  Esta propriedade foi descontinuada a partir do PHP 8.1.0. Confiar nesta propriedade é altamente desencorajado.

embedded

  Se o suporte MySQLi Embedded está ativado

  Aviso

  Esta propriedade foi removida a partir do PHP 8.0.0.

reconnect

  Permitir ou impedir a reconexão (consulte a diretiva mysqli.reconnect INI)

  Aviso

  Esta propriedade foi removida juntamente com a diretiva INI mysqli.reconnect a partir do PHP 8.2.0.

report_mode

  Defina como `MYSQLI_REPORT_OFF`, `MYSQLI_REPORT_ALL` ou qualquer combinação de `MYSQLI_REPORT_STRICT` (lança exceções para erros), `MYSQLI_REPORT_ERROR` (reporta erros) e `MYSQLI_REPORT_INDEX` (erros relacionados a índices). Veja também mysqli_report().

## Registro de Alterações

Versão | Descrição
--- | ---
8.2.0 | mysqli_driver::$reconnect foi removido.
8.1.0 | mysqli_driver::$driver_version foi descontinuada.
8.0.0 | mysqli_driver::$embedded foi removido.
7.4.0 | mysqli_driver::embedded_server_start() e mysqli_driver:embedded_server_end() foram removidos.

# mysqli_driver::embedded_server_end

# mysqli_embedded_server_end

(PHP 5 >= 5.1.0, PHP 7 < 7.4.0)

mysqli_driver::embedded_server_end -- mysqli_embedded_server_end — Para o servidor incorporado

Aviso

Esta função foi REMOVIDA a partir do PHP 7.4.0.

### Descrição

Estilo orientado a objetos

public function mysqli_driver::embedded_server_end(): void

Estilo procedural

function mysqli_embedded_server_end(): void
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

# mysqli_driver::embedded_server_start

# mysqli_embedded_server_start

(PHP 5 >= 5.1.0, PHP 7 < 7.4.0)

mysqli_driver::embedded_server_start -- mysqli_embedded_server_start — Inicializa e dispara o servidor incorporado

Aviso

Esta função foi REMOVIDA a partir do PHP 7.4.0.

### Descrição

Estilo orientado a objetos

public function mysqli_driver::embedded_server_start(int `$start`, array `$arguments`, array `$groups`): bool

Estilo procedural

function mysqli_embedded_server_start(int `$start`, array `$arguments`, array `$groups`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

# mysqli_driver::$report_mode

# mysqli_report

(PHP 5, PHP 7, PHP 8)

mysqli_driver::$report_mode -- mysqli_report — Define o modo de relatório de erros do mysqli

### Descrição

Estilo orientado a objetos

int $mysqli_driver->report_mode;

Estilo procedural

function mysqli_report(int `$flags`): true

Dependendo das flags, ele define o modo de relatório de erros do mysqli como exceção, aviso ou nenhum. Quando definido como `MYSQLI_REPORT_ALL` ou `MYSQLI_REPORT_INDEX`, ele também informará sobre as consultas que não usam um índice (ou usam um índice incorreto).

A partir do PHP 8.1.0, a configuração padrão é `MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT`. Anteriormente, era `MYSQLI_REPORT_OFF`.

### Parâmetros

`flags`

  Flags suportadas
  Nome | Descrição
  --- | ---
  `MYSQLI_REPORT_OFF` | Desativa os relatórios
  `MYSQLI_REPORT_ERROR` | Relatar erros de chamadas de função mysqli
  `MYSQLI_REPORT_STRICT` | Lance mysqli_sql_exception para erros em vez de avisos
  `MYSQLI_REPORT_INDEX` | Informa se nenhum índice ou índice inválido foi usado em uma consulta
  `MYSQLI_REPORT_ALL` | Define todas as opções (relatar tudo)

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O valor padrão agora é `MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT`. Anteriormente, era `MYSQLI_REPORT_OFF`.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php

    /* ativar relatórios */
    $driver = new mysqli_driver();
    $driver->report_mode = MYSQLI_REPORT_ALL;

    try {
        /* se a conexão falhar, um mysqli_sql_exception será lançado */
        $mysqli = new mysqli("localhost", "my_user", "my_password", "my_db");

        /* esta consulta deve relatar um erro */
        $result = $mysqli->query("SELECT Name FROM Nonexistingtable WHERE population > 50000");

        /* esta consulta deve relatar um índice ruim se a população da coluna não tiver um índice */
        $result = $mysqli->query("SELECT Name FROM City WHERE population > 50000");
    } catch (mysqli_sql_exception $e) {
        error_log($e->__toString());
    }

Exemplo #2 Estilo procedural

    <?php

    /* ativar relatórios */
    mysqli_report(MYSQLI_REPORT_ALL);

    try {
        /* se a conexão falhar, um mysqli_sql_exception será lançado */
        $link = mysqli_connect("localhost", "my_user", "my_password", "my_db");

        /* esta consulta deve relatar um erro */
        $result = mysqli_query($link, "SELECT Name FROM Nonexistingtable WHERE population > 50000");

        /* esta consulta deve relatar um índice ruim se a população da coluna não tiver um índice */
        $result = mysqli_query($link, "SELECT Name FROM City WHERE population > 50000");
    } catch (mysqli_sql_exception $e) {
        error_log($e->__toString());
    }

Exemplo #3 Relatório de erros, exceto erros de índice ruim

    <?php

    /* ativar relatórios */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    try {
        /* se a conexão falhar, um mysqli_sql_exception será lançado */
        $mysqli = new mysqli("localhost", "my_user", "my_password", "my_db");

        /* esta consulta deve relatar um erro */
        $result = $mysqli->query("SELECT Name FROM Nonexistingtable WHERE population > 50000");

        /* isso NÃO relatará nenhum erro, mesmo que o índice não esteja disponível */
        $result = $mysqli->query("SELECT Name FROM City WHERE population > 50000");
    } catch (mysqli_sql_exception $e) {
        error_log($e->__toString());
    }

### Veja Também

- mysqli_sql_exception
- set_exception_handler() - Define uma função de manipulação de exceção definida pelo usuário
- error_reporting() - Define quais erros do PHP são relatados

## Índice

- mysqli_driver::embedded_server_end — Para o servidor incorporado
- mysqli_driver::embedded_server_start — Inicializa e dispara o servidor incorporado
- mysqli_driver::$report_mode — Define o modo de relatório de erros do mysqli

# A classe mysqli_warning

(PHP 5, PHP 7, PHP 8)

## Introdução

Representa um aviso do MySQL.

## Resumo da classe

final class mysqli_warning {
/* Propriedades */
public string $message;
public string $sqlstate;
public int $errno;
/* Métodos */
private function __construct()
public function next(): bool
}

## Propriedades

message

  string da Mensagem

sqlstate

  Estado SQL

errno

  Número do erro

# mysqli_warning::__construct

(PHP 5, PHP 7, PHP 8)

mysqli_warning::__construct — Construtor privado para proibir instanciação direta

### Descrição

private function mysqli_warning::__construct()

### Parâmetros

Esta função não possui parâmetros.

# mysqli_warning::next

(PHP 5, PHP 7, PHP 8)

mysqli_warning::next — Busca o próximo aviso

### Descrição

public function mysqli_warning::next(): bool

Altere as informações de aviso para o próximo aviso, se possível.

Depois que o aviso for definido para o próximo aviso, novos valores de propriedades `message`, `sqlstate` e `errno` de mysqli_warning estarão disponíveis.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se o próximo aviso foi obtido com sucesso. Se não houver mais avisos, retornará `false`

## Índice

- mysqli_warning::__construct — Construtor privado para proibir instanciação direta
- mysqli_warning::next — Busca o próximo aviso

# A classe mysqli_sql_exception

(PHP 5, PHP 7, PHP 8)

## Introdução

A classe de manipulação de exceção mysqli.

## Resumo da classe

final class mysqli_sql_exception extends RuntimeException {
/* Propriedades */
protected string $sqlstate = "00000";
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
public function getSqlState(): string
/* Métodos herdados */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Propriedades

sqlstate

  O estado sql com o erro.

# mysqli_sql_exception::getSqlState

(PHP 8 >= 8.1.2)

mysqli_sql_exception::getSqlState — Retorna o código de erro SQLSTATE

### Descrição

public function mysqli_sql_exception::getSqlState(): string

Retorna uma string contendo o código de erro SQLSTATE para o último erro. O código de erro consiste em cinco caracteres. Os valores são especificados por ANSI SQL e ODBC. Para obter uma lista de valores possíveis, consulte » http://dev.mysql.com/doc/mysql/en/error-handling.html.

> Nota:

> Observe que nem todos os erros do MySQL ainda estão mapeados para SQLSTATE. O valor `HY000` (erro geral) é usado para erros não mapeados.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string contendo o código de erro SQLSTATE para o último erro. O código de erro consiste em cinco caracteres.

## Índice

- mysqli_sql_exception::getSqlState — Retorna o código de erro SQLSTATE

# Apelidos e Funções descontinuadas da Mysqli

# mysqli_connect

(PHP 5, PHP 7, PHP 8)

mysqli_connect — Sinônimo de mysqli::__construct()

### Descrição

Esta função é um apelido para: mysqli::__construct()

> Nota:

> Se o modo de exceção mysqli não estiver habilitado e uma conexão falhar, então mysqli_connect() retornará `false` ao invés de um objeto. A função mysqli_connect_error() pode ser usada para buscar o erro de conexão.

# mysqli::escape_string

# mysqli_escape_string

(PHP 5, PHP 7, PHP 8)

mysqli::escape_string -- mysqli_escape_string — Sinônimo de mysqli_real_escape_string()

### Descrição

Esta função é um apelido para: mysqli_real_escape_string().

# mysqli_execute

(PHP 5, PHP 7, PHP 8)

mysqli_execute — Sinônimo de mysqli_stmt_execute()

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.5.0. O uso desta função é fortemente desencorajado.

### Descrição

Esta função é um apelido para: mysqli_stmt_execute().

### Veja Também

- mysqli_stmt_execute() - Executa uma instrução preparada

# mysqli_get_client_stats

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_get_client_stats — Retorna as estatísticas do cliente por processo

### Descrição

function mysqli_get_client_stats(): array

Retorna as estatísticas do cliente por processo.

> Nota:

> Disponível apenas com o mysqlnd.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array com estatísticas do cliente.

### Exemplos

Exemplo #1 Exemplo de mysqli_get_client_stats()

    <?php
    $link = mysqli_connect();
    print_r(mysqli_get_client_stats());
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [bytes_sent] => 43
        [bytes_received] => 80
        [packets_sent] => 1
        [packets_received] => 2
        [protocol_overhead_in] => 8
        [protocol_overhead_out] => 4
        [bytes_received_ok_packet] => 11
        [bytes_received_eof_packet] => 0
        [bytes_received_rset_header_packet] => 0
        [bytes_received_rset_field_meta_packet] => 0
        [bytes_received_rset_row_packet] => 0
        [bytes_received_prepare_response_packet] => 0
        [bytes_received_change_user_packet] => 0
        [packets_sent_command] => 0
        [packets_received_ok] => 1
        [packets_received_eof] => 0
        [packets_received_rset_header] => 0
        [packets_received_rset_field_meta] => 0
        [packets_received_rset_row] => 0
        [packets_received_prepare_response] => 0
        [packets_received_change_user] => 0
        [result_set_queries] => 0
        [non_result_set_queries] => 0
        [no_index_used] => 0
        [bad_index_used] => 0
        [slow_queries] => 0
        [buffered_sets] => 0
        [unbuffered_sets] => 0
        [ps_buffered_sets] => 0
        [ps_unbuffered_sets] => 0
        [flushed_normal_sets] => 0
        [flushed_ps_sets] => 0
        [ps_prepared_never_executed] => 0
        [ps_prepared_once_executed] => 0
        [rows_fetched_from_server_normal] => 0
        [rows_fetched_from_server_ps] => 0
        [rows_buffered_from_client_normal] => 0
        [rows_buffered_from_client_ps] => 0
        [rows_fetched_from_client_normal_buffered] => 0
        [rows_fetched_from_client_normal_unbuffered] => 0
        [rows_fetched_from_client_ps_buffered] => 0
        [rows_fetched_from_client_ps_unbuffered] => 0
        [rows_fetched_from_client_ps_cursor] => 0
        [rows_skipped_normal] => 0
        [rows_skipped_ps] => 0
        [copy_on_write_saved] => 0
        [copy_on_write_performed] => 0
        [command_buffer_too_small] => 0
        [connect_success] => 1
        [connect_failure] => 0
        [connection_reused] => 0
        [reconnect] => 0
        [pconnect_success] => 0
        [active_connections] => 1
        [active_persistent_connections] => 0
        [explicit_close] => 0
        [implicit_close] => 0
        [disconnect_close] => 0
        [in_middle_of_command_close] => 0
        [explicit_free_result] => 0
        [implicit_free_result] => 0
        [explicit_stmt_close] => 0
        [implicit_stmt_close] => 0
        [mem_emalloc_count] => 0
        [mem_emalloc_ammount] => 0
        [mem_ecalloc_count] => 0
        [mem_ecalloc_ammount] => 0
        [mem_erealloc_count] => 0
        [mem_erealloc_ammount] => 0
        [mem_efree_count] => 0
        [mem_malloc_count] => 0
        [mem_malloc_ammount] => 0
        [mem_calloc_count] => 0
        [mem_calloc_ammount] => 0
        [mem_realloc_count] => 0
        [mem_realloc_ammount] => 0
        [mem_free_count] => 0
        [proto_text_fetched_null] => 0
        [proto_text_fetched_bit] => 0
        [proto_text_fetched_tinyint] => 0
        [proto_text_fetched_short] => 0
        [proto_text_fetched_int24] => 0
        [proto_text_fetched_int] => 0
        [proto_text_fetched_bigint] => 0
        [proto_text_fetched_decimal] => 0
        [proto_text_fetched_float] => 0
        [proto_text_fetched_double] => 0
        [proto_text_fetched_date] => 0
        [proto_text_fetched_year] => 0
        [proto_text_fetched_time] => 0
        [proto_text_fetched_datetime] => 0
        [proto_text_fetched_timestamp] => 0
        [proto_text_fetched_string] => 0
        [proto_text_fetched_blob] => 0
        [proto_text_fetched_enum] => 0
        [proto_text_fetched_set] => 0
        [proto_text_fetched_geometry] => 0
        [proto_text_fetched_other] => 0
        [proto_binary_fetched_null] => 0
        [proto_binary_fetched_bit] => 0
        [proto_binary_fetched_tinyint] => 0
        [proto_binary_fetched_short] => 0
        [proto_binary_fetched_int24] => 0
        [proto_binary_fetched_int] => 0
        [proto_binary_fetched_bigint] => 0
        [proto_binary_fetched_decimal] => 0
        [proto_binary_fetched_float] => 0
        [proto_binary_fetched_double] => 0
        [proto_binary_fetched_date] => 0
        [proto_binary_fetched_year] => 0
        [proto_binary_fetched_time] => 0
        [proto_binary_fetched_datetime] => 0
        [proto_binary_fetched_timestamp] => 0
        [proto_binary_fetched_string] => 0
        [proto_binary_fetched_blob] => 0
        [proto_binary_fetched_enum] => 0
        [proto_binary_fetched_set] => 0
        [proto_binary_fetched_geometry] => 0
        [proto_binary_fetched_other] => 0
    )

### Veja Também

- Descrição das estatísticas

# mysqli_get_links_stats

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

mysqli_get_links_stats — Retorna informações sobre links abertos e em cache

### Descrição

function mysqli_get_links_stats(): array

mysqli_get_links_stats() retorna informações sobre links MySQL abertos e em cache.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

mysqli_get_links_stats() retorna um array associativo com três elementos, digitados da seguinte forma:

`total`

  Um int que indica o número total de links abertos em qualquer estado.

`active_plinks`

  Um int representando o número de conexões persistentes ativas.

`cached_plinks`

  Um int representando o número de conexões persistentes inativas.

# mysqli_report

(PHP 5, PHP 7, PHP 8)

mysqli_report — Sinônimo de mysqli_driver->report_mode

### Descrição

Esta função é um apelido para: mysqli_driver->report_mode

# mysqli::set_opt

# mysqli_set_opt

(PHP 5, PHP 7, PHP 8)

mysqli::set_opt -- mysqli_set_opt — Sinônimo de mysqli_options()

### Descrição

Esta função é um apelido para: mysqli_options().

## Índice

- mysqli_connect — Sinônimo de mysqli::__construct
- mysqli::escape_string — Sinônimo de mysqli_real_escape_string
- mysqli_execute — Sinônimo de mysqli_stmt_execute
- mysqli_get_client_stats — Retorna as estatísticas do cliente por processo
- mysqli_get_links_stats — Retorna informações sobre links abertos e em cache
- mysqli_report — Sinônimo de mysqli_driver->report_mode
- mysqli::set_opt — Sinônimo de mysqli_options

# Registro de Alterações

As alterações a seguir foram feitas em classes/funções/métodos desta extensão.

Version | Function | Description
--- | --- | ---
8.4.0 | mysqli::kill | O método mysqli::kill e a função mysqli_kill foram descontinuados. No lugar deles, deve ser usado o comando SQL KILL.
| mysqli::ping | O método mysqli::ping e a função mysqli_ping foram descontinuados. O recurso de reconnect (reconexão) não está disponível a partir do PHP 8.2.0, tornando esta função obsoleta.
| mysqli::refresh | O método mysqli::refresh e a função mysqli_refresh foram descontinuados. No lugar deles, use o comando SQL FLUSH.
| mysqli::store_result | Passar o parâmetro mode foi descontinuado. O parâmetro já não tem efeito a partir do PHP 8.1.0.
8.3.0 | mysqli_result::fetch_object | Agora lança uma exceção ValueError quando o parâmetro constructor_args é não vazio com a classe não possuindo construtor; anteriormente uma Exception era lançada.
| mysqli::poll | Agora lança uma exceção ValueError quando nem o parâmetro read nem o parâmetro error são passados.
8.1.0 | mysqli_driver::$report_mode | O valor padrão agora é MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT. Anteriormente, era MYSQLI_REPORT_OFF.
| mysqli_result::fetch_all | Agora também disponível com a biblioteca libmysqlclient.
| mysqli_stmt::execute | O parâmetro optional params foi adicionado.
| mysqli_stmt::next_result | Agora também disponível com a biblioteca libmysqlclient.
| mysqli::__construct | Agora, o método mysqli::connect retorna true em vez de null em caso de sucesso.
| mysqli::$client_info | Chamar mysqli_get_client_info com o argumento mysql foi descontinuado. Esta função nunca requereu um parâmetro, mas incorretamente permitia este parâmetro opcional.
| mysqli::$client_info | O método orientado a objeto mysqli::get_client_info foi descontinuado.
| mysqli::init | O método mysqli::init com estilo orientado a objeto foi descontinuado. Substitua as chamadas a parent::init por parent::__construct.
8.0.0 | mysqli_result::fetch_object | constructor_args agora aceita [] para construtores sem parâmetros; anteriormente, uma exceção era lançada.
| mysqli_result::field_seek | Esta função agora sempre retorna true. Anteriormente retornava false em caso de falha.
| mysqli_stmt::close | Esta função agora sempre retorna true. Anteriormente retornava false em caso de falha.
| mysqli_stmt::__construct | query agora pode ser nulo.
| mysqli::begin_transaction | name agora é anulável.
| mysqli::close | Esta função sempre retorna true. Anteriormente retornava false em caso de falha.
| mysqli::commit | name agora pode ser nulo.
| mysqli::debug | Esta função agora sempre retorna true. Anteriormente retornava false em caso de falha.
| mysqli::rollback | name agora é anulável.
7.4.0 | mysqli::__construct | Todos os parâmetros podem ser null.
| mysqli::real_connect | Todos os parâmetros agora são anuláveis.

- Visão Geral
- Guia de início rápido
  - Interface dupla, procedural e orientada a objetos
  - Conexões
  - Executando instruções
  - Instruções Preparadas
  - Procedimentos Armazenados
  - Instruções Múltiplas
  - Suporte da API para transações
  - Metadados
- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
- A extensão mysqli e conexões persistentes
- Constantes predefinidas
- Notas
- Resumo da Função de Extensão do MySQLi
- mysqli — A classe mysqli
  - mysqli::$affected_rows — Retorna o número de linhas afetadas pela operação MySQL anterior
  - mysqli::autocommit — Ativa ou desativa a gravação automática das modificações no banco de dados
  - mysqli::begin_transaction — Inicia uma transação
  - mysqli::change_user — Altera o usuário da conexão com o banco de dados
  - mysqli::character_set_name — Retorna o conjunto de caracteres atual da conexão com o banco de dados
  - mysqli::close — Fecha uma conexão ao banco de dados previamente aberta
  - mysqli::commit — Grava a transação atual
  - mysqli::$connect_errno — Retorna o código de erro da última chamada de conexão
  - mysqli::$connect_error — Retorna uma descrição do último erro de conexão
  - mysqli::__construct — Abre uma nova conexão com o servidor MySQL
  - mysqli::debug — Realiza operações de depuração
  - mysqli::dump_debug_info — Descarrega informação de debug no log
  - mysqli->errno — Retorna o código de erro para a chamada de função mais recente
  - mysqli->error — Retorna uma string descrevendo o último erro
  - mysqli::$error_list — Retorna uma lista de erros do último comando executado
  - mysqli::execute_query — Prepara, vincula parâmetros e executa a instrução SQL
  - mysqli::$field_count — Retorna o número de campos para a consulta mais recente
  - mysqli::get_charset — Retorna um objeto de conjunto de caracteres
  - mysqli::$client_info — Obtém informação do cliente MySQL
  - mysqli::$client_version — Retorna a versão do cliente MySQL como um inteiro
  - mysqli::get_connection_stats — Retorna estatísticas sobre a conexão do cliente
  - mysqli::$host_info — Retorna uma string representando o tipo de conexão utilizada
  - mysqli::$protocol_version — Retorna a versão do protocolo MySQL usada
  - mysqli::$server_info — Retorna a versão do servidor MySQL
  - mysqli::$server_version — Retorna a versão do servidor MySQL como um inteiro
  - mysqli::get_warnings — Obtém o resultado de SHOW WARNINGS
  - mysqli::$info — Recupera informação sobre a recente consulta executada
  - mysqli::init — Inicializa o MySQLi e retorna um objeto a ser utilizado com mysqli_real_connect()
  - mysqli::$insert_id — Retorna o valor gerado para uma coluna AUTO_INCREMENT pela última consulta
  - mysqli::kill — Solicita ao servidor o encerramento de um thread do MySQL
  - mysqli::more_results — Verifica se há mais algum resultado de uma consulta múltipla
  - mysqli::multi_query — Executa uma ou mais consultas no banco de dados
  - mysqli::next_result — Prepara o próximo resultado de multi_query
  - mysqli::options — Define opções
  - mysqli::ping — Faz ping em uma conexão de servidor ou tenta reconectar se a conexão cair
  - mysqli::poll — Sondagem de conexões
  - mysqli::prepare — Prepara uma instrução SQL para execução
  - mysqli::query — Executa uma consulta no banco de dados
  - mysqli::real_connect — Abre uma conexão a um servidor MySQL
  - mysqli::real_escape_string — Escape caracteres especiais em uma string para uso em uma instrução SQL, levando em consideração o conjunto de caracteres atual da conexão
  - mysqli::real_query — Executa uma consulta SQL
  - mysqli::reap_async_query — Obtenha o resultado da consulta assíncrona
  - mysqli::refresh — Atualiza
  - mysqli::release_savepoint — Remove o ponto de salvamento nomeado do conjunto de pontos de salvamento da transação atual
  - mysqli::rollback — Reverte a transação atual
  - mysqli::savepoint — Define um ponto de salvamento de transação nomeado
  - mysqli::select_db — Seleciona o banco de dados padrão para consultas de banco de dados
  - mysqli::set_charset — Define o conjunto de caracteres do cliente
  - mysqli::$sqlstate — Retorna o erro SQLSTATE da operação MySQL anterior
  - mysqli::ssl_set — Usado para estabelecer conexões seguras usando SSL
  - mysqli::stat — Obtém o status atual do sistema
  - mysqli::stmt_init — Inicializa uma instrução e retorna um objeto para uso com mysqli_stmt_prepare
  - mysqli::store_result — Transfere um conjunto de resultados da última consulta
  - mysqli::$thread_id — Retorna o ID da thread para a conexão atual
  - mysqli::thread_safe — Retorna se a segurança de thread é dada ou não
  - mysqli::use_result — Iniciar uma recuperação de conjunto de resultados
  - mysqli::$warning_count — Retorna o número de alertas gerados pela consulta mais recente
- mysqli_stmt — A classe mysqli_stmt
  - mysqli_stmt::$affected_rows — Retorna o número total de linhas modificadas, apagadas, inseridas ou correspondidas pela última instrução executada
  - mysqli_stmt::attr_get — Usado para obter o valor atual de um atributo de instrução
  - mysqli_stmt::attr_set — Usado para modificar o comportamento de uma instrução preparada
  - mysqli_stmt::bind_param — Liga variáveis a uma declaração preparada como parâmetros
  - mysqli_stmt::bind_result — Liga variáveis a uma declaração preparada para armazenamento de resultado
  - mysqli_stmt::close — Fecha uma instrução preparada
  - mysqli_stmt::__construct — Constrói um novo objeto mysqli_stmt
  - mysqli_stmt::data_seek — Ajusta o ponteiro de resultado para uma linha arbitrária no resultado com buffer
  - mysqli_stmt::$errno — Retorna o código de erro para a chamada de instrução mais recente
  - mysqli_stmt::$error — Retorna uma descrição em string para o último erro de instrução
  - mysqli_stmt::$error_list — Retorna uma lista de erros da última instrução executada
  - mysqli_stmt::execute — Executa uma instrução preparada
  - mysqli_stmt::fetch — Recebe resultados de uma instrução preparada nas variáveis vinculadas
  - mysqli_stmt::$field_count — Retorna o número de colunas na instrução informada
  - mysqli_stmt::free_result — Libera memória do resultado armazenado para o manipulador de instrução informado
  - mysqli_stmt::get_result — Obtém um resultado de uma instrução preparada como um objeto mysqli_result
  - mysqli_stmt::get_warnings — Obtém o resultado de SHOW WARNINGS
  - mysqli_stmt::$insert_id — Obtém o ID gerado pela operação INSERT anterior
  - mysqli_stmt::more_results — Verifica se há mais resultados de uma consulta múltipla
  - mysqli_stmt::next_result — Lê o próximo resultado de uma consulta múltipla
  - mysqli_stmt::$num_rows — Retorna o número de linhas recebidas pelo servidor
  - mysqli_stmt::$param_count — Retorna o número de parâmetros para uma instrução fornecida
  - mysqli_stmt::prepare — Prepara uma declaração SQL para execução
  - mysqli_stmt::reset — Redefine uma instrução preparada
  - mysqli_stmt::result_metadata — Retorna os metadados de resultado de uma instrução preparada
  - mysqli_stmt::send_long_data — Envia dados em blocos
  - mysqli_stmt::$sqlstate — Retorna o erro SQLSTATE da operação da instrução anterior
  - mysqli_stmt::store_result — Armazena um conjunto de resultados em um buffer interno
- mysqli_result — A classe mysqli_result
  - mysqli_result::__construct — Constrói um objeto mysqli_result
  - mysqli_result::$current_field — Obtém o deslocamento atual de campo de um ponteiro de resultado
  - mysqli_result::data_seek — Ajusta o ponteiro do resultado para uma linha arbitrária no resultado
  - mysqli_result::fetch_all — Recebe todas as linhas de resultado como array associativo, numérico, ou ambos
  - mysqli_result::fetch_array — Recebe a próxima linha de resultado como array associativo, numérico, ou ambos
  - mysqli_result::fetch_assoc — Obtém a próxima linha do conjunto de resultados como um array associativo
  - mysqli_result::fetch_column — Recebe uma única coluna da próxima linha de um resultado
  - mysqli_result::fetch_field — Retorna o próximo campo no conjunto de resultados
  - mysqli_result::fetch_field_direct — Recebe metadados para um único campo
  - mysqli_result::fetch_fields — Retorna um array de objetos representando os campos em um conjunto de resultados
  - mysqli_result::fetch_object — Recebe a próxima linha de um resultado como um objeto
  - mysqli_result::fetch_row — Obtém a próxima linha de um resultado como um array enumerado
  - mysqli_result::$field_count — Obtém o número de campos no conjunto de resultados
  - mysqli_result::field_seek — Move o ponteiro do resultado para um campo especificado
  - mysqli_result::free — Libera memória associada a um resultado
  - mysqli_result::getIterator — Obtém um iterador externo
  - mysqli_result::$lengths — Retorna os comprimentos das colunas da linha atual do resultado
  - mysqli_result::$num_rows — Obtém o número de linhas no resultado
- mysqli_driver — A classe mysqli_driver
  - mysqli_driver::embedded_server_end — Para o servidor incorporado
  - mysqli_driver::embedded_server_start — Inicializa e dispara o servidor incorporado
  - mysqli_driver::$report_mode — Define o modo de relatório de erros do mysqli
- mysqli_warning — A classe mysqli_warning
  - mysqli_warning::__construct — Construtor privado para proibir instanciação direta
  - mysqli_warning::next — Busca o próximo aviso
- mysqli_sql_exception — A classe mysqli_sql_exception
  - mysqli_sql_exception::getSqlState — Retorna o código de erro SQLSTATE
- Apelidos e Funções descontinuadas da Mysqli
  - mysqli_connect — Sinônimo de mysqli::__construct
  - mysqli::escape_string — Sinônimo de mysqli_real_escape_string
  - mysqli_execute — Sinônimo de mysqli_stmt_execute
  - mysqli_get_client_stats — Retorna as estatísticas do cliente por processo
  - mysqli_get_links_stats — Retorna informações sobre links abertos e em cache
  - mysqli_report — Sinônimo de mysqli_driver->report_mode
  - mysqli::set_opt — Sinônimo de mysqli_options
- Registro de Alterações

# Mysql_xdevapi

# Introdução

Esta extensão fornece acesso ao MySQL Document Store através da X DevAPI. A X DevAPI é uma API comum fornecida por múltiplos conectores MySQL que permitem acesso fácil a tabelas relacionais assim como a coleções de documentos, que são representadas em JSON, a partir de uma API com operações em estilo CRUD.

A X DevAPI usa do protocolo X, o protocolo cliente-servidor de nova geração do servidor MySQL 8.0.

Para informação geral sobre o MySQL Document Store, favor se referir ao capítulo » MySQL Document Store no manual do MySQL.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução
- Construindo / Compilando a Partir da Fonte

## Dependências

Esta extensão requer um Servidor MySQL 8+ com o plugin X habilitado (padrão).

Bibliotecas que são pré-requisitos para esta extensão: Boost (1.53.0 ou superior), OpenSSL e Protobuf.

## Instalação

Esta extensão » PECL não é distribuída com o PHP.

Um procedimento de exemplo de instalação no Ubuntu 18.04 com PHP 7.2:

    // Dependências
    $ apt install build-essential libprotobuf-dev libboost-dev openssl protobuf-compiler liblz4-tool zstd

    // PHP com as extensões desejadas; php7.2-dev é requerido para compilação
    $ apt install php7.2-cli php7.2-dev php7.2-mysql php7.2-pdo php7.2-xml

    // Compila a extensão
    $ pecl install mysql_xdevapi

O comando `pecl install` não habilita as extensões PHP (por padrão) e as habilitações de extensões podem ser feitas de várias formas. Um outro exemplo do PHP 7.2 no Ubuntu 18.04:

    // Cria o seu próprio arquivo ini
    $ echo "extension=mysql_xdevapi.so" > /etc/php/7.2/mods-available/mysql_xdevapi.ini

    // Usa o comando 'phpenmod' (nota: específico para Debian/Ubuntu)
    $ phpenmod -v 7.2 -s ALL mysql_xdevapi

    // Uma alternativa ao 'phpenmod' é criar uma ligação simbólica manualmente
    // $ ln -s /etc/php/7.2/mods-available/mysql_xdevapi.ini /etc/php/7.2/cli/conf.d/20-mysql_xdevapi.ini

    // Vejamos agora que extensões do MySQL estão habilitadas
    $ php -m |grep mysql

    mysql_xdevapi
    mysqli
    mysqlnd
    pdo_mysql

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/mysql_xdevapi.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de Configuração de mysql_xdevapi
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
xmysqlnd.collect_memory_statistics | 0 | `INI_SYSTEM` |
xmysqlnd.collect_statistics | 1 | `INI_ALL` |
xmysqlnd.debug |  | `INI_SYSTEM` |
xmysqlnd.mempool_default_size | 16000 | `INI_ALL` |
xmysqlnd.net_read_timeout | 31536000 | `INI_SYSTEM` |
xmysqlnd.trace_alloc |  | `INI_SYSTEM` |

Aqui está uma breve explicação das diretivas de configuração.

`xmysqlnd.collect_memory_statistics` int

`xmysqlnd.collect_statistics` int

`xmysqlnd.debug` string

`xmysqlnd.mempool_default_size` int

`xmysqlnd.net_read_timeout` int

`xmysqlnd.trace_alloc` string

## Construindo / Compilando a Partir da Fonte

Considerations for compiling this extension from source.

- O nome da extensão é 'mysql_xdevapi', portanto use `--enable-mysql-xdevapi`.

- Boost: requerido, opcionalmente use a opção de configuração --with-boost=DIR ou defina a variável de ambiente MYSQL_XDEVAPI_BOOST_ROOT. Somente os arquivos de cabeçalho Boost são necessários, não os binários.

- Google Protocol Buffers (protobuf): requerido, opcionalmente use a opção de configuração --with-protobuf=DIR ou defina a variável de ambiente MYSQL_XDEVAPI_PROTOBUF_ROOT.

  Opcionamente, use `make protobufs` para gerar arquivos protobuf (*.pb.cc/.h), e `make clean-protobufs` para remover os arquivos protobuf gerados.

  Nota do protobuf específica para Windows: dependendo do ambiente, a biblioteca estática com um DLL multi-thread pode ser necessária. Para preparar, use as seguintes opções: -Dprotobuf_MSVC_STATIC_RUNTIME=OFF -Dprotobuf_BUILD_SHARED_LIBS=OFF

- Google Protocol Buffers / compilador de protocolo (protoc): requerido, deve-se garantir que o 'protoc' apropriado esteja disponível na variável de ambiente PATH durante a construção. É especialmente importante porque os scripts em lote do Windows PHP SDK podem sobrescrever o ambiente.

- Bison: requerido, e disponível a partir do PATH.

  Nota do bison específica para o Windows: recomenda-se fortemente o uso do bison fornecido com o SDK do PHP escolhido, ou pode resultar em um erro similar a "zend_globals_macros.h(39): error C2375: 'zendparse': redefinition; different linkage Zend/zend_language_parser.h(214): note: see declaration of 'zendparse'". Além disso, os scripts em lote do Windows PHP SDK podem sobrescrever o ambiente.

- Notas específicas para Windows: Para preparar o ambiente, consulte a documentação de compilação oficial do Windows para » o SDK atual.

  Recomenda-se usar a barra invertida '\\' ao invés da barra normal '/' para todos os caminhos.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`MYSQLX_CLIENT_SSL` (int)
`MYSQLX_TYPE_DECIMAL` (int)
`MYSQLX_TYPE_TINY` (int)
`MYSQLX_TYPE_SHORT` (int)
`MYSQLX_TYPE_SMALLINT` (int)
`MYSQLX_TYPE_MEDIUMINT` (int)
`MYSQLX_TYPE_INT` (int)
`MYSQLX_TYPE_BIGINT` (int)
`MYSQLX_TYPE_LONG` (int)
`MYSQLX_TYPE_FLOAT` (int)
`MYSQLX_TYPE_DOUBLE` (int)
`MYSQLX_TYPE_NULL` (int)
`MYSQLX_TYPE_TIMESTAMP` (int)
`MYSQLX_TYPE_LONGLONG` (int)
`MYSQLX_TYPE_INT24` (int)
`MYSQLX_TYPE_DATE` (int)
`MYSQLX_TYPE_TIME` (int)
`MYSQLX_TYPE_DATETIME` (int)
`MYSQLX_TYPE_YEAR` (int)
`MYSQLX_TYPE_NEWDATE` (int)
`MYSQLX_TYPE_ENUM` (int)
`MYSQLX_TYPE_SET` (int)
`MYSQLX_TYPE_TINY_BLOB` (int)
`MYSQLX_TYPE_MEDIUM_BLOB` (int)
`MYSQLX_TYPE_LONG_BLOB` (int)
`MYSQLX_TYPE_BLOB` (int)
`MYSQLX_TYPE_VAR_STRING` (int)
`MYSQLX_TYPE_STRING` (int)
`MYSQLX_TYPE_CHAR` (int)
`MYSQLX_TYPE_BYTES` (int)
`MYSQLX_TYPE_INTERVAL` (int)
`MYSQLX_TYPE_GEOMETRY` (int)
`MYSQLX_TYPE_JSON` (int)
`MYSQLX_TYPE_NEWDECIMAL` (int)
`MYSQLX_TYPE_BIT` (int)
`MYSQLX_LOCK_DEFAULT` (int)
`MYSQLX_LOCK_NOWAIT` (int)
`MYSQLX_LOCK_SKIP_LOCKED` (int)

# Registro de Alterações

As alterações a seguir foram feitas em classes/funções/métodos desta extensão.

### Registro Geral Alterações para a extensão ext/mysql_xdevapi

Este registro de alterações referencia a extensão ext/mysql_xdevapi.

### Alterações globais da ext/mysql_xdevapi

Versão | Descrição
--- | ---
8.0.28 | Removido suporte a TLSv1 e TLSv1.1. Os valores "TLSv1", "TLSv1.0", e "TLSv1.1" agora são considerados inválidos para o atributo de conexão "tls-versions".
8.0.26 | Suporte a TLSv1 e TLSv1.1 foi descontinuado.

# Exemplos

O ponto de entrada central para a X DevAPI é a função mysql_xdevapi\getSession(), que recebe uma URI para um servidor MySQL 8.0 e retorna um objeto mysql_xdevapi\Session.

Exemplo #1 Conectando a um Servidor MySQL

    <?php
    try {
        $session = mysql_xdevapi\getSession("mysqlx://usuario:senha@servidor");
    } catch(Exception $e) {
        die("Não foi possível estabelecer conexão: " . $e->getMessage());
    }

    // ... use $session
    ?>

A sessão fornece acesso completo à API. Para uma nova instalação do Servidor MySQL, o primeiro passo é criar um esquema com uma coleção para armazenar dados:

Exemplo #2 Criando um Esquema e uma Coleção no Servidor MySQL

    <?php
    $schema = $session->createSchema("teste");
    $collection = $schema->createCollection("exemplo");
    ?>

Ao armazenar dados, normalmente json_encode() é usada para codificar os dados em JSON, que assim podem ser armazenados em uma coleção.

O exemplo a seguir armazena dados na coleção criada anteriormente, e depois recupera partes dela novamente.

Exemplo #3 Armazenando e Recuperando Dados

    <?php
    $marco = [
      "nome" => "Marco",
      "idade"  => 19,
      "emprego"  => "Programador"
    ];
    $mike = [
      "nome" => "Mike",
      "idade"  => 39,
      "emprego"  => "Gerente"
    ];

    $schema = $session->getSchema("teste");
    $collection = $schema->getCollection("exemplo");

    $collection->add($marco, $mike)->execute();

    var_dump($collection->find("nome = 'Mike'")->execute()->fetchOne());
    ?>

O exemplo acima produzirá algo semelhante a:

    array(4) {
      ["_id"]=>
      string(28) "00005ad66aaf0000000000000003"
      ["idade"]=>
      int(39)
      ["emprego"]=>
      string(7) "Gerente"
      ["nome"]=>
      string(4) "Mike"
    }

O exemplo demonstra que o Servidor MySQL adiciona um campo extra de nome `_id`, que serve como chave primária para o documento.

O exemplo também demonstra que os dados recuperados são ordenados alfabeticamente, Esta ordem específica vem do armazenamento binário eficiente dentro do servidor MySQL, mas isso nem sempre é confiável. Refira-se à documentação do tipo de dados JSON do MySQL para detalhes.

Opcionalmente, use os iteradores do PHP para buscar múltiplos documentos:

Exemplo #4 Buscando e Iterando sobre Múltiplos Documentos

    <?php
    $result = $collection->find()->execute();
    foreach ($result as $doc) {
      echo "{$doc["nome"]} é um {$doc["emprego"]}.\n";
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Marco é um Programador.
    Mike é um Gerente.

# Funções de Mysql_xdevapi

# expression

(No version information available, might only be in Git)

expression — Vincula as variáveis de instrução preparada como parâmetros

### Descrição

function mysql_xdevapi\expression(string `$expression`): object

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`expression`

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Expression()

    <?php
    $expression = mysql_xdevapi\Expression("[idade,emprego]");

    $res  = $coll->find("idade > 30")->fields($expression)->limit(3)->execute();
    $data = $res->fetchAll();

    print_r($data);
    ?>

O exemplo acima produzirá algo semelhante a:

    <?php

# getSession

(No version information available, might only be in Git)

getSession — Conecta a um servidor MySQL

### Descrição

function mysql_xdevapi\getSession(string `$uri`): mysql_xdevapi\Session

Conecta a um servidor MySQL.

### Parâmetros

`uri`

  A URI para o servidor MySQL server, como `mysqlx://user:password@host`.

  Formato da URI:

  `scheme://[user[:[password]]@]target[:port][?attribute1=value1&attribute2=value2...`

  - `scheme`: requerido, o protocolo de conexão

    Na mysql_xdevapi é sempre 'mysqlx' (para o Protocolo X)

  - `user`: opcional, a conta de usuário do MySQL para autenticação

  - `password`: opcional, a senha do usuário do MySQL para autenticação

  - `target`: requerido, a instância do servidor à qual a conexão se refere:

    * Conexão TCP (nome de servidor, endereço IPv4 ou endereço IPv6)

    * Caminho do soquete Unix (caminho de arquivo local)

    * Pipe nomeado do Windows (caminho de arquivo local)

  - `port`: opcional, porta de rede do servidor MySQL.

    Por padrão a porta do Protocolo X é 33060

  - `?attribute=value`: este elemento é opcional e especifica um dicionário de dados que contém diferentes opções, incluindo:

    - O atributo `auth` (mecanismo de autenticação) relacionado a conexões criptografadas. Para informação adicional, consulte » Opções de Comando para Conexões Criptografadas. Os seguintes valores de 'auth' são suportados: `plain`, `mysql41`, `external` e `sha256_mem`.

    - O atributo `connect-timeout` afeta a conexão e não as operações subsequentes. É definido por conexão, seja em servidor único ou em múltiplos servidores.

      Passar um número inteiro positivo define o tempo limite da conexão em segundos, passar 0 (zero) desabilita o tempo limite (infinito). Não definir o tempo limite de conexão usa o valor padrão de 10.

      Relacionado, as variáveis ​​de ambiente MYSQLX_CONNECTION_TIMEOUT (tempo limite em segundos) e MYSQLX_TEST_CONNECTION_TIMEOUT (usadas durante a execução de testes) podem ser definidas e usadas em vez do tempo limite de conexão na URI. A opção de URI de tempo limite de conexão tem precedência sobre essas variáveis ​​de ambiente.

    - O atributo opcional `compression` aceita estes valores: `preferred` (o cliente negocia com o servidor para encontrar um algoritmo suportado; a conexão é descompactada se um algoritmo mutuamente suportado não for encontrado), `required` (como "preferred", mas a conexão é terminada se um algoritmo mutuamente suportado não for encontrado), ou `disabled` (conexão é descompactada). O padrão é `preferred`.

      Esta opção foi adicionada na versão 8.0.20.

    - O atributo opcional `compression-algorithms` define os algortimos de compressão desejados (e sua ordem preferida de uso): `zstd_stream` (sinônimo: zstd), `lz4_message` (sinônimo: lz4), ou `deflate_stream` (sinônimos: deflate ou zlib). Por padrão, a ordem usada (dependendo da disponibilidade do sistema) é lz4_message, zstd_stream e depois deflate_stream. Por exemplo, passar compression-algorithms=[lz4,zstd_stream] usa lz4 se estiver disponível, caso contrário, zstd_stream é usado. Se ambos estiverem indisponíveis, o comportamento dependerá do valor da compactação, por exemplo, se compression=required então falhará com um erro.

      Esta opção foi adicionada na versão 8.0.22.

  Exemplo #1 Exemplos de URI

      mysqlx://foobar
      mysqlx://root@localhost?socket=%2Ftmp%2Fmysqld.sock%2F
      mysqlx://foo:bar@localhost:33060
      mysqlx://foo:bar@localhost:33160?ssl-mode=disabled
      mysqlx://foo:bar@localhost:33260?ssl-mode=required
      mysqlx://foo:bar@localhost:33360?ssl-mode=required&auth=mysql41
      mysqlx://foo:bar@(/path/to/socket)
      mysqlx://foo:bar@(/path/to/socket)?auth=sha256_mem
      mysqlx://foo:bar@[localhost:33060, 127.0.0.1:33061]
      mysqlx://foobar?ssl-ca=(/path/to/ca.pem)&ssl-crl=(/path/to/crl.pem)
      mysqlx://foo:bar@[localhost:33060, 127.0.0.1:33061]?ssl-mode=disabled
      mysqlx://foo:bar@localhost:33160/?connect-timeout=0
      mysqlx://foo:bar@localhost:33160/?connect-timeout=10&compression=required
      mysqlx://foo:bar@localhost:33160/?connect-timeout=10&compression=required&compression-algorithms=[lz4,zstd_stream]

  Para informações relacionadas, consulte a documentação sobre » Conectando com uma String de URI do Shell do MySQL.

### Valor Retornado

Um objeto Session.

### Erros/Exceções

Uma falha de conexão lança uma Exception.

### Exemplos

Exemplo #2 Exemplo de mysql_xdevapi\getSession()

    <?php
    try {
        $session = mysql_xdevapi\getSession("mysqlx://user:password@host");
    } catch(Exception $e) {
        die("A conexão não pode ser estabelecida: " . $e->getMessage());
    }

    $schemas = $session->getSchemas();
    print_r($schemas);

    $mysql_version = $session->getServerVersion();
    print_r($mysql_version);

    var_dump($collection->find("name = 'Alfred'")->execute()->fetchOne());
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => mysql_xdevapi\Schema Object
            (
                [name] => helloworld
            )
        [1] => mysql_xdevapi\Schema Object
            (
                [name] => information_schema
            )
        [2] => mysql_xdevapi\Schema Object
            (
                [name] => mysql
            )
        [3] => mysql_xdevapi\Schema Object
            (
                [name] => performance_schema
            )
        [4] => mysql_xdevapi\Schema Object
            (
                [name] => sys
            )
    )

    80012

    array(4) {
      ["_id"]=>
      string(28) "00005ad66abf0001000400000003"
      ["age"]=>
      int(42)
      ["job"]=>
      string(7) "Butler"
      ["name"]=>
      string(4) "Alfred"
    }

## Índice

- expression — Vincula as variáveis de instrução preparada como parâmetros
- getSession — Conecta a um servidor MySQL

# Interface BaseResult

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

## Resumo da classe

class mysql_xdevapi\BaseResult {
/* Métodos */
abstract public function getWarnings(): array
abstract public function getWarningsCount(): int
}

# BaseResult::getWarnings

(No version information available, might only be in Git)

BaseResult::getWarnings — Buscar alertas da última operação

### Descrição

abstract public function mysql_xdevapi\BaseResult::getWarnings(): array

Busca alertas gerados pela última operação do servidor MySQL.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array de objetos Warning da última operação. Cada objeto define uma mensagem ('message') de erro, um nível ('level') de erro e um código ('code') de erro. Um array vazio será retornado se nenhum erro estiver presente.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\RowResult::getWarnings()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();
    $warnings = $res->getWarnings();

    print_r($warnings);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
        [1] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
    )

# BaseResult::getWarningsCount

(No version information available, might only be in Git)

BaseResult::getWarningsCount — Busca contagem de alertas da última operação

### Descrição

abstract public function mysql_xdevapi\BaseResult::getWarningsCount(): int

Retorna o número de alertas gerados pela última operação. Especificamente, esses alertas são gerados pelo servidor MySQL.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O número de alertas da última operação.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\RowResult::getWarningsCount()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS foo")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();

    echo $res->getWarningsCount();
    ?>

O exemplo acima produzirá algo semelhante a:

    2

## Índice

- BaseResult::getWarnings — Buscar alertas da última operação
- BaseResult::getWarningsCount — Busca contagem de alertas da última operação

# Classe Client

(No version information available, might only be in Git)

## Introdução

Fornece acesso ao pool de conexões.

## Resumo da classe

class mysql_xdevapi\Client {
/* Métodos */
public function close(): bool
public function getSession(): mysql_xdevapi\Session
}

# mysql_xdevapi\Client::close

(No version information available, might only be in Git)

mysql_xdevapi\Client::close — Fecha o cliente

### Descrição

public function mysql_xdevapi\Client::close(): bool

Fecha todas as conexões de cliente com o servidor.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

`true` se as conexões forem fechadas.

# Client::__construct

(No version information available, might only be in Git)

Client::__construct — Construtor de Client

### Descrição

private function mysql_xdevapi\Client::__construct()

Constrói um objeto Client.

### Parâmetros

Esta função não possui parâmetros.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Client::__construct()

    <?php
    $pooling_options = '{
      "enabled": true,
        "maxSize": 10,
        "maxIdleTime": 3600,
        "queueTimeOut": 1000
    }';
    $client = mysql_xdevapi\getClient($connection_uri, $pooling_options);
    $session = $client->getSession();

# Client::getClient

(No version information available, might only be in Git)

Client::getClient — Obtém a sessão do cliente

### Descrição

public function mysql_xdevapi\Client::getSession(): mysql_xdevapi\Session

Obtém a sessão associada com o cliente.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um objeto Session.

## Índice

- mysql_xdevapi\Client::close — Fecha o cliente
- Client::__construct — Construtor de Client
- Client::getClient — Obtém a sessão do cliente

# Classe Collection

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

## Resumo da classe

class mysql_xdevapi\Collection implements mysql_xdevapi\SchemaObject {
/* Propriedades */
public $name;
/* Métodos */
public function add(mixed `$document`): mysql_xdevapi\CollectionAdd
public function addOrReplaceOne(string `$id`, string `$doc`): mysql_xdevapi\Result
public function count(): int
public function createIndex(string `$index_name`, string `$index_desc_json`): void
public function dropIndex(string `$index_name`): bool
public function existsInDatabase(): bool
public function find(string `$search_condition` = ?): mysql_xdevapi\CollectionFind
public function getName(): string
public function getOne(string `$id`): Document
public function getSchema(): Schema Object
public function getSession(): Session
public function modify(string `$search_condition`): mysql_xdevapi\CollectionModify
public function remove(string `$search_condition`): mysql_xdevapi\CollectionRemove
public function removeOne(string `$id`): mysql_xdevapi\Result
public function replaceOne(string `$id`, string `$doc`): mysql_xdevapi\Result
}

## Propriedades

name

# Collection::add

(No version information available, might only be in Git)

Collection::add — Adiciona um documento na coleção

### Descrição

public function mysql_xdevapi\Collection::add(mixed `$document`): mysql_xdevapi\CollectionAdd

Dispara a inserção do(s) documento(s) informado(s) na coleção, múltiplas variantes deste método são suportadas. As opções incluem:

1. Adiciona um único documento como uma string JSON.

2. Adiciona um único documento como um array no formato: `[ 'field' => 'value', 'field2' => 'value2' ... ]`

3. Uma combinação de ambos, múltiplos documentos podem ser adicionados na mesma operação.

### Parâmetros

`document`

  Um ou múltiplos documentos, pode ser um JSON ou um array de campos com seus valores associados. Não pode ser um array vazio.

  O servidor MySQL gera automaticamente um valor único de `_id` para cada documento (recomendado), embora também possa ser adicionado manualmente. Este valor precisa ser único, caso contrário a operação de adição falhará.

### Valor Retornado

Um objeto CollectionAdd. Use execute() para retornar um Result que possa ser usado para consultar o número de itens afetados, o número de alertas gerados pela operação, ou para buscar uma lista de IDs gerados para os documentos inseridos.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Collection::add()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    // Adiciona dois documentos
    $collection->add('{"name": "Fred",  "age": 21, "job": "Construction"}')->execute();
    $collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

    // Adiciona dois documentos usando um único objeto JSON
    $result = $collection->add(
      '{"name": "Bernie",
        "jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
        "hobbies": ["Sports","Making cupcakes"]}',
      '{"name": "Jane",
        "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
        "hobbies": ["Walking","Making pies"]}')->execute();

    // Busca uma lista de IDs gerados pelo último add()
    $ids = $result->getGeneratedIds();
    print_r($ids);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => 00005b6b53610000000000000056
        [1] => 00005b6b53610000000000000057
    )

### Notas

> Nota:

> Um _id único é gerado pelo MySQL Server 8.0 ou superior, como demonstrado no exemplo. O campo _id precisa ser definido manualmente se o MySQL Server 5.7 estiver sendo usado.

# Collection::addOrReplaceOne

(No version information available, might only be in Git)

Collection::addOrReplaceOne — Adiciona ou substitui um documento na coleção

### Descrição

public function mysql_xdevapi\Collection::addOrReplaceOne(string `$id`, string `$doc`): mysql_xdevapi\Result

Adiciona um novo documento, ou substitui um documento se ele já existir.

Aqui estão vários cenários para este método:

- Se nem o id nem qualquer valor único de chave conflitar com algum documento na coleção, o documento é adicionado.

- Se o id não corresponder a nenhum documento mas uma ou mais valores únicos de chave conflitarem com um documento na coleção, um erro é emitido.

- Se o id corresponder a um documento existente e não houver chaves únicas definidas para a coleção, o documento é substituído.

- Se o id corresponder a um documento existente e, todas as chaves únicas no documento substituto corresponderem ao mesmo documento ou não conflitarem com nenhum outro documento na coleção, o documento é substituído.

- Se o id corresponder a um documento existente e uma ou mais chaves únicas corresponderem a um documento diferente na coleção, um erro é emitido.

### Parâmetros

`id`

  Este é o id de filtro. Se este id ou qualquer outro campo que tiver um índice único já existir na coleção, o documento correspondente será atualizado.

  Por padrão, este id é gerado automaticamente pelo servidor MySQL quando o registro é adicionado e é referenciado como um campo com o nome '_id'.

`doc`

  Este é o documento a ser inserido ou substituído, que é uma string JSON.

### Valor Retornado

Um objeto Result.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Collection::addOrReplaceOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    // Usando add()
    $result = $collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

    // Usando addOrReplaceOne()
    // Nota: aqui está sendo passado um valor conhecido de _id
    $result = $collection->addOrReplaceOne('00005b6b53610000000000000056', '{"name": "Fred",  "age": 21, "job": "Construction"}');

    ?>

# Collection::__construct

(No version information available, might only be in Git)

Collection::__construct — Construtor de Collection

### Descrição

private function mysql_xdevapi\Collection::__construct()

Constrói um objeto Collection.

### Parâmetros

Esta função não possui parâmetros.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Collection::getOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection->add('{"name": "Alfred", "age": 42, "job": "Butler"}')->execute();

    // Um _id único é gerado pelo servidor MySQL (por padrão, e recomendado)
    // Aqui os ids gerados são recuperados; somente um neste exemplo, $ids[0]
    $ids        = $result->getGeneratedIds();
    $alfreds_id = $ids[0];

    // ...

    print_r($alfreds_id);
    print_r($collection->getOne($alfreds_id));
    ?>

O exemplo acima produzirá algo semelhante a:

    00005b6b536100000000000000b1

    Array
    (
        [_id] => 00005b6b536100000000000000b1
        [age] => 42
        [job] => Butler
        [name] => Alfred
    )

# Collection::count

(No version information available, might only be in Git)

Collection::count — Obtém a contagem de documentos

### Descrição

public function mysql_xdevapi\Collection::count(): int

Esta funcionalidade é similar à operação SQL `SELECT COUNT(*)` no servidor MySQL para o esquema e coleção atuais. Em outras palavras, ela conta o número de documentos na coleção.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O número de documentos na coleção.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Collection::count()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    $result = $collection
      ->add(
      '{"name": "Bernie",
        "jobs": [
          {"title":"Cat Herder","Salary":42000},
          {"title":"Father","Salary":0}
        ],
        "hobbies": ["Sports","Making cupcakes"]}',
      '{"name": "Jane",
        "jobs": [
          {"title":"Scientist","Salary":18000},
          {"title":"Mother","Salary":0}
        ],
        "hobbies": ["Walking","Making pies"]}')
      ->execute();

    var_dump($collection->count());
    ?>

O exemplo acima produzirá:

    int(2)

# Collection::createIndex

(No version information available, might only be in Git)

Collection::createIndex — Cria índice na coleção

### Descrição

public function mysql_xdevapi\Collection::createIndex(string `$index_name`, string `$index_desc_json`): void

Cria um índice na coleção.

Uma exceção é lançada se um índice com o mesmo nome já existir, ou se a definição do índice não estiver formada corretamente.

### Parâmetros

`index_name`

  O nome do índice a ser criado. O nome precisa ser válido da mesma forma que os nomes aceitos pela consulta SQL `CREATE INDEX`.

`index_desc_json`

  Definição do índice a ser criado. Contém um array de objetos IndexField, e cada objeto descreve um único documento membro para incluir no índice e uma string opcional para o tipo de índice, que pode ser INDEX (padrão) ou SPATIAL.

  Uma descrição de um único IndexField consiste nos campos a seguir:

  - `field`: string, o caminho completo para o documento membro ou campo a ser indexado.

  - `type`: string, um dos tipos de coluna suportados pelo SQL para mapear o campo. Para tipos numéricos, a palavra-chave opcional UNSIGNED pode ser incluída na sequência. Para o tipo TEXT, o comprimento a considerar para a indexação pode ser incluído.

  - `required`: booleano, (opcional) TRUE se for necessário que o campo exista no documento. O padrão é `false`, exceto para `GEOJSON` onde o padrão é `true`.

  - `options`: inteiro, (opcional) opções especiais para uso durante a decodificação de dados `GEOJSON`.

  - `srid`: inteiro, (opcional) valor srid para uso durante a decodificação de dados `GEOJSON`.

  É um erro incluir outros campos não descritos acima em documentos IndexDefinition ou IndexField.

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Collection::createIndex()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    // Criando um índice de texto
    $collection->createIndex(
      'myindex1',
      '{"fields": [{
        "field": "$.name",
        "type": "TEXT(25)",
        "required": true}],
        "unique": false}'
    );

    // Um índice espacial
    $collection->createIndex(
      'myindex2',
      '{"fields": [{
        "field": "$.home",
        "type": "GEOJSON",
        "required": true}],
        "type": "SPATIAL"}'
    );

    // Índice com múltiplos campos
    $collection->createIndex(
      'myindex3',
      '{"fields": [
        {
          "field": "$.name",
          "type": "TEXT(20)",
          "required": true
        },
        {
          "field": "$.age",
          "type": "INTEGER"
        },
        {
          "field": "$.job",
          "type": "TEXT(30)",
          "required": false
        }
      ],
      "unique": true
      }'
    );

# Collection::dropIndex

(No version information available, might only be in Git)

Collection::dropIndex — Remove um índice da coleção

### Descrição

public function mysql_xdevapi\Collection::dropIndex(string `$index_name`): bool

Remove um índice da coleção.

Esta operação não gera um erro se o índice não existir, mas neste caso é retornado `false`.

### Parâmetros

`index_name`

  Nome do índice da coleção a ser removido.

### Valor Retornado

`true` se a operação DROP INDEX for bem sucedida, caso contrário `false`.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Collection::dropIndex()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    // ...

    $collection = $schema->getCollection("people");

    $collection->createIndex(
      'myindex',
      '{"fields": [{"field": "$.name", "type": "TEXT(25)", "required": true}], "unique": false}'
    );

    // ...

    if ($collection->dropIndex('myindex')) {
        echo "Um índice de nome 'myindex' foi encontrado e removido.";
    }
    ?>

O exemplo acima produzirá:

    Um índice de nome 'myindex' foi encontrado e removido.

# Collection::existsInDatabase

(No version information available, might only be in Git)

Collection::existsInDatabase — Verifica se uma coleção existe no banco de dados

### Descrição

public function mysql_xdevapi\Collection::existsInDatabase(): bool

Verifica se o objeto Collection se refere a uma coleção no banco de dados (esquema).

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se a coleção existir no banco de dados, `false` se não existir.

Uma tabela definida com duas colunas (doc e _id) é considerada uma coleção, e uma terceira coluna _json_schema a partir do MySQL 8.0.21. Inserir uma coluna adicional significa que existsInDatabase() não mais a verá como uma coleção.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Collection::existsInDatabase()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    // ...

    $collection = $schema->getCollection("people");

    // ...

    if (!$collection->existsInDatabase()) {
        echo "A coleção não existe mais no banco de dados addressbook. O que aconteceu?";
    }
    ?>

# Collection::find

(No version information available, might only be in Git)

Collection::find — Pesquisa por um documento

### Descrição

public function mysql_xdevapi\Collection::find(string `$search_condition` = ?): mysql_xdevapi\CollectionFind

Pesquisa uma coleção do banco de dados por um documento ou conjunto de documentos. Os documentos encontrados são retornados como um objeto CollectionFind que servirá para modificação ou para busca de resultados.

### Parâmetros

`search_condition`

  Embora seja opcional, normalmente uma condição é definida para limitar os resultados a um subconjunto de documentos.

  Múltiplos elementos podem fazer parte da condição e a sintaxe suporta vinculação de parâmetros. A expressão usada como condição de pesquisa precisa ser uma expressão SQL válida. Se nenhuma condição de pesquisa for informada (campo vazio), será assumida a expressão find('true').

### Valor Retornado

Um objeto CollectionFind para verificar a operação, ou buscar os documentos encontrados.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Collection::find()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $collection->add('{"name": "Alfred",     "age": 18, "job": "Butler"}')->execute();
    $collection->add('{"name": "Bob",        "age": 19, "job": "Swimmer"}')->execute();
    $collection->add('{"name": "Fred",       "age": 20, "job": "Construction"}')->execute();
    $collection->add('{"name": "Wilma",      "age": 21, "job": "Teacher"}')->execute();
    $collection->add('{"name": "Suki",       "age": 22, "job": "Teacher"}')->execute();

    $find   = $collection->find('job LIKE :job AND age > :age');
    $result = $find
      ->bind(['job' => 'Teacher', 'age' => 20])
      ->sort('age DESC')
      ->limit(2)
      ->execute();

    print_r($result->fetchAll());
    ?>

O exemplo acima produzirá:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b536100000000000000a8
                [age] => 22
                [job] => Teacher
                [name] => Suki
            )
        [1] => Array
            (
                [_id] => 00005b6b536100000000000000a7
                [age] => 21
                [job] => Teacher
                [name] => Wilma
            )
    )

# Collection::getName

(No version information available, might only be in Git)

Collection::getName — Obtém o nome da coleção

### Descrição

public function mysql_xdevapi\Collection::getName(): string

Recupera o nome da coleção.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O nome da coleção, como uma string.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Collection::getName()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    // ...

    var_dump($collection->getName());
    ?>

O exemplo acima produzirá algo semelhante a:

    string(6) "people"

# Collection::getOne

(No version information available, might only be in Git)

Collection::getOne — Obtém um documento

### Descrição

public function mysql_xdevapi\Collection::getOne(string `$id`): Document

Busca um documento da coleção.

É um atalho para: `Collection.find("_id = :id").bind("id", id).execute().fetchOne();`

### Parâmetros

`id`

  O _id do documento na coleção.

### Valor Retornado

O objeto Collection, ou `null` se o _id não corresponder a um documento.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Collection::getOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection->add('{"name": "Alfred", "age": 42, "job": "Butler"}')->execute();

    // Um _id único é gerado pelo servidor MySQL (por padrão, e recomendado)
    // Isto recupera os ids gerados; somente um neste exemplo, $ids[0]
    $ids        = $result->getGeneratedIds();
    $alfreds_id = $ids[0];

    // ...

    print_r($alfreds_id);
    print_r($collection->getOne($alfreds_id));
    ?>

O exemplo acima produzirá algo semelhante a:

    00005b6b536100000000000000b1

    Array
    (
        [_id] => 00005b6b536100000000000000b1
        [age] => 42
        [job] => Butler
        [name] => Alfred
    )

# Collection::getSchema

(No version information available, might only be in Git)

Collection::getSchema — Obtém o objeto de esquema

### Descrição

public function mysql_xdevapi\Collection::getSchema(): Schema Object

Recupera o objeto de esquema que contém a coleção.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O objeto de esquema em caso de sucesso, ou `null` se o objeto não puder ser recuperado para a coleção informada.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Collection::getSchema()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    var_dump($collection->getSchema());
    ?>

O exemplo acima produzirá algo semelhante a:

    object(mysql_xdevapi\Schema)#9 (1) {
      ["name"]=>
      string(11) "addressbook"
    }

# Collection::getSession

(No version information available, might only be in Git)

Collection::getSession — Obtém o objeto de sessão

### Descrição

public function mysql_xdevapi\Collection::getSession(): Session

Obtém um novo objeto Session do objeto Collection.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um objeto Session.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Collection::getSession()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    // ...

    $newsession = $collection->getSession();

    var_dump($session);
    var_dump($newsession);
    ?>

O exemplo acima produzirá algo semelhante a:

    object(mysql_xdevapi\Session)#1 (0) {
    }
    object(mysql_xdevapi\Session)#4 (0) {
    }

# Collection::modify

(No version information available, might only be in Git)

Collection::modify — Modifica documentos da coleção

### Descrição

public function mysql_xdevapi\Collection::modify(string `$search_condition`): mysql_xdevapi\CollectionModify

Modifica os documentos de uma coleção que se encaixam em condições específicas de pesquisa. Múltiplas operações são permitidas e a vinculação de parâmetros é suportada.

### Parâmetros

`search_condition`

  Precisa ser uma expressão SQL válida usada para corresponder aos documentos que serão modificados. Esta expressão pode ser tão simples como `true`, que corresponde a todos os documentos, ou pode conter funções e operações como `'CAST(_id AS SIGNED) >= 10'`, `'age MOD 2 = 0 OR age MOD 3 = 0'` ou `'_id IN ["2","5","7","10"]'`.

### Valor Retornado

Se a operação não for executada, a função retornará um objeto Modify que pode ser usado para inserir operações adicionais de modificação.

Se a operação de modificação for executada, o objeto retornado conterá o resultado da operação.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Collection::modify()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $collection->add('{"name": "Bob",    "age": 19, "job": "Painter"}')->execute();

    // Adiciona dois novos 'jobs' para todos os 'Painters': 'Artist' e 'Crafter'
    $collection
      ->modify("job in ('Butler', 'Painter')")
      ->arrayAppend('job', 'Artist')
      ->arrayAppend('job', 'Crafter')
      ->execute();

    // Remove o campo 'beer' de todos os documentos com a idade (age) menor que 21
    $collection
      ->modify('age < 21')
      ->unset(['beer'])
      ->execute();
    ?>

# Collection::remove

(No version information available, might only be in Git)

Collection::remove — Remove documentos da coleção

### Descrição

public function mysql_xdevapi\Collection::remove(string `$search_condition`): mysql_xdevapi\CollectionRemove

Remove documentos de uma coleção que se encaixam em condições específicas de pesquisa. Múltiplas operações são permitidas e a vinculação de parâmetros é suportada.

### Parâmetros

`search_condition`

  Precisa ser uma expressão SQL válida usada para corresponder aos documentos que serão modificados. Esta expressão pode ser tão simples como `true`, que corresponde a todos os documentos, ou pode conter funções e operações como `'CAST(_id AS SIGNED) >= 10'`, `'age MOD 2 = 0 OR age MOD 3 = 0'` ou `'_id IN ["2","5","7","10"]'`.

### Valor Retornado

Se a operação não for executada, a função retornará um objeto Remove que pode ser usado para inserir operações de remoção adicionais.

Se a operação de remoção for executada, o objeto retornado conterá o resultado da operação.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Collection::remove()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $collection->add('{"name": "Bob",    "age": 19, "job": "Painter"}')->execute();

    // Remove todos os 'painters'
    $collection
      ->remove("job in ('Painter')")
      ->execute();

    // Remove o 'butler' mais antigo (maior 'age')
    $collection
      ->remove("job in ('Butler')")
      ->sort('age desc')
      ->limit(1)
      ->execute();

    // Remove o registro com maior 'age'
    $collection
      ->remove('true')
      ->sort('age desc')
      ->limit(1)
      ->execute();
    ?>

# Collection::removeOne

(No version information available, might only be in Git)

Collection::removeOne — Remove um documento da coleção

### Descrição

public function mysql_xdevapi\Collection::removeOne(string `$id`): mysql_xdevapi\Result

Remove da coleção o documento com o ID correspondente. É um atalho para `Collection.remove("_id = :id").bind("id", id).execute()`.

### Parâmetros

`id`

  O ID do documento da coleção a ser removido. Tipicamente é o _id gerado pelo servidor MySQL quando o registro foi inserido.

### Valor Retornado

Um objeto Result que pode ser usado para consultar o número de itens afetados ou o número de alertas gerados pela operação.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Collection::removeOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();

    // Normalmente o _id é conhecido por outros meios,
    // mas para este exemplo vamos buscar o id gerado e usá-lo
    $ids       = $result->getGeneratedIds();
    $alfred_id = $ids[0];

    $result = $collection->removeOne($alfred_id);

    if(!$result->getAffectedItemsCount()) {
        echo "Alfred com id $alfred_id não foi removido.";
    } else {
        echo "Tchau, Alfred, pode levar o _id $alfred_id com você.";
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Tchau, Alfred, pode levar o _id 00005b6b536100000000000000cb com você.

# Collection::replaceOne

(No version information available, might only be in Git)

Collection::replaceOne — Substitui um documento na coleção

### Descrição

public function mysql_xdevapi\Collection::replaceOne(string `$id`, string `$doc`): mysql_xdevapi\Result

Atualiza (ou substitui) o documento identificado pelo ID, se existir.

### Parâmetros

`id`

  ID do documento para substituir ou atualizar. Tipicamente é o _id que foi gerado pelo servidor MySQL quando o registro foi inserido.

`doc`

  Documento da coleção para atualizar ou substituir o documento que corresponde ao parâmetro id.

  Este documento pode ser um objeto de documento ou uma string JSON válida descrevendo o novo documento.

### Valor Retornado

Um objeto Result que pode ser usado para consultar o número de itens afetados e o número de alertas gerados pela operação.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Collection::replaceOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();

    // Normalmente o _id é conhecido por outros meios,
    // mas para este exemplo vamos buscar o id gerado e usá-lo
    $ids       = $result->getGeneratedIds();
    $alfred_id = $ids[0];

    // ...

    $alfred = $collection->getOne($alfred_id);
    $alfred['age'] = 81;
    $alfred['job'] = 'Guru';

    $collection->replaceOne($alfred_id, $alfred);

    ?>

## Índice

- Collection::add — Adiciona um documento na coleção
- Collection::addOrReplaceOne — Adiciona ou substitui um documento na coleção
- Collection::__construct — Construtor de Collection
- Collection::count — Obtém a contagem de documentos
- Collection::createIndex — Cria índice na coleção
- Collection::dropIndex — Remove um índice da coleção
- Collection::existsInDatabase — Verifica se uma coleção existe no banco de dados
- Collection::find — Pesquisa por um documento
- Collection::getName — Obtém o nome da coleção
- Collection::getOne — Obtém um documento
- Collection::getSchema — Obtém o objeto de esquema
- Collection::getSession — Obtém o objeto de sessão
- Collection::modify — Modifica documentos da coleção
- Collection::remove — Remove documentos da coleção
- Collection::removeOne — Remove um documento da coleção
- Collection::replaceOne — Substitui um documento na coleção

# Classe CollectionAdd

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

## Resumo da classe

class mysql_xdevapi\CollectionAdd implements mysql_xdevapi\Executable {
/* Métodos */
public function execute(): mysql_xdevapi\Result
}

# CollectionAdd::__construct

(No version information available, might only be in Git)

CollectionAdd::__construct — Construtor de CollectionAdd

### Descrição

private function mysql_xdevapi\CollectionAdd::__construct()

Use para adicionar um documento à coleção; chamado a partir de um objeto Collection.

### Parâmetros

Esta função não possui parâmetros.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CollectionAdd::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    // Adiciona dois documentos
    $collection
      ->add('{"name": "Fred",  "age": 21, "job": "Construction"}')
      ->execute();

    $collection
      ->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')
      ->execute();

    // Adiciona dois documentos usando um único objeto JSON
    $result = $collection
      ->add(
        '{"name": "Bernie",
          "jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
          "hobbies": ["Sports","Making cupcakes"]}',
        '{"name": "Jane",
          "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
          "hobbies": ["Walking","Making pies"]}')
      ->execute();

    // Busca uma lista de IDs gerados pelo último add()
    $ids = $result->getGeneratedIds();
    print_r($ids);

    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => 00005b6b53610000000000000056
        [1] => 00005b6b53610000000000000057
    )

### Notas

> Nota:

> Um _id único é gerado pelo MySQL Server 8.0 ou superior, como demonstrado no exemplo. O campo _id precisa ser definido manualmente se o MySQL Server 5.7 estiver sendo usado.

# CollectionAdd::execute

(No version information available, might only be in Git)

CollectionAdd::execute — Executa a instrução

### Descrição

public function mysql_xdevapi\CollectionAdd::execute(): mysql_xdevapi\Result

O método de execução é requerido para enviar a requisição de operação CRUD ao servidor MySQL.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um objeto Result que pode ser usado para verificar o status da operação, como o número de linhas afetadas.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CollectionAdd::execute()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    // Adiciona dois documentos
    $collection
      ->add('{"name": "Fred",  "age": 21, "job": "Construction"}')
      ->execute();

    $collection
      ->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')
      ->execute();

    // Adiciona dois documentos usando um único objeto JSON
    $result = $collection
      ->add(
        '{"name": "Bernie",
          "jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
          "hobbies": ["Sports","Making cupcakes"]}',
        '{"name": "Jane",
          "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
          "hobbies": ["Walking","Making pies"]}')
      ->execute();

    // Busca uma lista de IDs gerados no último add()
    $ids = $result->getGeneratedIds();
    print_r($ids);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => 00005b6b53610000000000000056
        [1] => 00005b6b53610000000000000057
    )

## Índice

- CollectionAdd::__construct — Construtor de CollectionAdd
- CollectionAdd::execute — Executa a instrução

# Classe CollectionFind

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

## Resumo da classe

class mysql_xdevapi\CollectionFind implements mysql_xdevapi\Executable, mysql_xdevapi\CrudOperationBindable, mysql_xdevapi\CrudOperationLimitable, mysql_xdevapi\CrudOperationSortable {
/* Métodos */
public function bind(array `$placeholder_values`): mysql_xdevapi\CollectionFind
public function execute(): mysql_xdevapi\DocResult
public function fields(string `$projection`): mysql_xdevapi\CollectionFind
public function groupBy(string `$sort_expr`): mysql_xdevapi\CollectionFind
public function having(string `$sort_expr`): mysql_xdevapi\CollectionFind
public function limit(int `$rows`): mysql_xdevapi\CollectionFind
public function lockExclusive(int `$lock_waiting_option` = ?): mysql_xdevapi\CollectionFind
public function lockShared(int `$lock_waiting_option` = ?): mysql_xdevapi\CollectionFind
public function offset(int `$position`): mysql_xdevapi\CollectionFind
public function sort(string `$sort_expr`): mysql_xdevapi\CollectionFind
}

# CollectionFind::bind

(No version information available, might only be in Git)

CollectionFind::bind — Vincula valor a marcador na consulta

### Descrição

public function mysql_xdevapi\CollectionFind::bind(array `$placeholder_values`): mysql_xdevapi\CollectionFind

Permite ao usuário vincular um parâmetro ao marcador na condição de pesquisa da operação de busca. O marcador tem a forma de :NOME onde ':' é um prefixo comum que precisa sempre existir antes de qualquer NOME, o nome real do marcador. A função de vinculação aceita uma lista de marcadores se múltiplas entidades precisarem ser substituídas na condição de pesquisa.

### Parâmetros

`placeholder_values`

  Valores a substituir na condição de pesquisa; múltiplos valores são permitidos e são passados como um array onde "NOME_MARCADOR => VALOR_MARCADOR".

### Valor Retornado

Um objeto CollectionFind, ou encadeado com execute() para retornar um objeto Result.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CollectionFind::bind()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");
    $result = $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->execute();

    var_dump($result->fetchAll());
    ?>

O exemplo acima produzirá algo semelhante a:

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000cf"
        ["age"]=>
        int(18)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(6) "Alfred"
      }
    }

# CollectionFind::__construct

(No version information available, might only be in Git)

CollectionFind::__construct — Construtor de CollectionFind

### Descrição

private function mysql_xdevapi\CollectionFind::__construct()

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Exemplos

Exemplo #1 Exemplo de CollectionFind

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");
    $result = $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->execute();

    var_dump($result->fetchAll());
    ?>

O exemplo acima produzirá algo semelhante a:

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000cf"
        ["age"]=>
        int(18)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(6) "Alfred"
      }
    }

# CollectionFind::execute

(No version information available, might only be in Git)

CollectionFind::execute — Executa a instrução

### Descrição

public function mysql_xdevapi\CollectionFind::execute(): mysql_xdevapi\DocResult

Executa a operação de busca; esta funcionalidade permite encadeamento de métodos.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um objeto mysql_xdevapi\DocResult que pode ser usado para buscar resultados ou para consultar o status da operação.

### Exemplos

Exemplo #1 Exemplo de CollectionFind

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->execute();

    var_dump($result->fetchAll());
    ?>

O exemplo acima produzirá algo semelhante a:

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000cf"
        ["age"]=>
        int(18)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(6) "Alfred"
      }
    }

# CollectionFind::fields

(No version information available, might only be in Git)

CollectionFind::fields — Define filtro de campo de documento

### Descrição

public function mysql_xdevapi\CollectionFind::fields(string `$projection`): mysql_xdevapi\CollectionFind

Define as colunas para a consulta retornar. Se não definidas, todas as colunas são usadas.

### Parâmetros

`projection`

  Pode ser uma única string ou um array de strings identificando as colunas a serem retornadas para cada documento que corresponder à condição de pesquisa.

### Valor Retornado

Um objeto CollectionFind que pode ser usado para processamento adicional.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CollectionFind::fields()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->fields('name')
      ->execute();

    var_dump($result->fetchAll());
    ?>

O exemplo acima produzirá algo semelhante a:

    array(1) {
      [0]=>
      array(1) {
        ["name"]=>
        string(6) "Alfred"
      }
    }

# CollectionFind::groupBy

(No version information available, might only be in Git)

CollectionFind::groupBy — Define critérios de agrupamento

### Descrição

public function mysql_xdevapi\CollectionFind::groupBy(string `$sort_expr`): mysql_xdevapi\CollectionFind

Esta função pode ser usada para agrupar o conjunto de resultados por uma ou mais colunas. É frequentemente usado com funções de agragação como `COUNT`, `MAX`, `MIN`, `SUM` etc.

### Parâmetros

`sort_expr`

  A coluna ou colunas que serão usadas para a operação de agrupamento, pode ser uma string única ou um array de strings, uma para cada coluna.

### Valor Retornado

Um objeto CollectionFind que pode ser usado para processamento adicional.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CollectionFind::groupBy()

    <?php

    // Assumindo que $coll é um objeto Collection válido

    // Extrai todos os documentos da coleção e agrupa os resultados pelo campo 'nome'
    $res = $coll->find()->groupBy('nome')->execute();

    ?>

# CollectionFind::having

(No version information available, might only be in Git)

CollectionFind::having — Define condição para funções de agregação

### Descrição

public function mysql_xdevapi\CollectionFind::having(string `$sort_expr`): mysql_xdevapi\CollectionFind

Esta função pode ser usada depois da operação 'field' para fazer uma seleção nos documentos a extrair.

### Parâmetros

`sort_expr`

  Precisa ser uma expressão SQL válida, o uso de funções de agregação é permitido.

### Valor Retornado

Objeto CollectionFind que pode ser usado para processamento adicional.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CollectionFind::having()

    <?php

    // Assumindo que $coll é um objeto Collection válido

    // Encontra todos os documentos para os quais a 'idade' é maior que 40,
    // Somente as colunas 'nome' e 'idade' são retornadas no objeto Result
    $res = $coll->find()->fields(['nome','idade'])->having('idade > 40')->execute();

    ?>

# CollectionFind::limit

(No version information available, might only be in Git)

CollectionFind::limit — Limita o número de documentos retornados

### Descrição

public function mysql_xdevapi\CollectionFind::limit(int `$rows`): mysql_xdevapi\CollectionFind

Define o número máximo de documentos a retornar.

### Parâmetros

`rows`

  Número máximo de documentos.

### Valor Retornado

Um objeto CollectionFind que pode ser usado para processamento adicional; pode ser encadeado com o método execute() para retornar um objeto DocResult.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CollectionFind::limit()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");
    $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();
    $create
      ->add('{"name": "Reginald", "age": 42, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->limit(1)
      ->execute();

    var_dump($result->fetchAll());
    ?>

O exemplo acima produzirá algo semelhante a:

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000f3"
        ["age"]=>
        int(42)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(8) "Reginald"
      }
    }

# CollectionFind::lockExclusive

(No version information available, might only be in Git)

CollectionFind::lockExclusive — Executa a operação com EXCLUSIVE LOCK

### Descrição

public function mysql_xdevapi\CollectionFind::lockExclusive(int `$lock_waiting_option` = ?): mysql_xdevapi\CollectionFind

Trava o documento de forma exclusiva. Enquanto o documento estiver travado, outras transações não podem atualizá-lo, use `SELECT ... LOCK IN SHARE MODE`, ou leia os dados em certos níveis de isolamento de transação. Leituras consistentes ignoram qualquer trava definida em registros que existem na visualização de leitura.

Para evitar problemas de concorrência, faz sentido usar esta função com o método mysql_xdevapi\Collection::modify() Essencialmente, esta função usa travas de registros para serializar acesso a eles.

### Parâmetros

`lock_waiting_option`

  Parâmetro opcional de espera. Por padrão é `MYSQLX_LOCK_DEFAULT`. Valores válidos são estas constantes:

  - `MYSQLX_LOCK_DEFAULT`

  - `MYSQLX_LOCK_NOWAIT`

  - `MYSQLX_LOCK_SKIP_LOCKED`

### Valor Retornado

Retorna um objeto CollectionFind que pode ser usado para processamento adicional.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CollectionFind::lockExclusive()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $session->startTransaction();

    $result = $collection
      ->find("age > 50")
      ->lockExclusive()
      ->execute();

    // ... faz uma operação com o objeto

    // Completa a transação e destrava o documento
    $session->commit();
    ?>

# CollectionFind::lockShared

(No version information available, might only be in Git)

CollectionFind::lockShared — Executa a operação com SHARED LOCK

### Descrição

public function mysql_xdevapi\CollectionFind::lockShared(int `$lock_waiting_option` = ?): mysql_xdevapi\CollectionFind

Permite compartilhar os documentos entre múltiplas transações que estão travando em modo compartilhado.

Outras sessões podem ler as linhas, mas não podem modificá-las até que a transação seja efetivamente executada.

Se quaisquer destas linhas tiverem sido alteradas por outra transação que não tenha sido efetivamente executada, a consulta irá esperar até que a transação tenha terminado para ser capaz de usar os valores mais recentes.

### Parâmetros

`lock_waiting_option`

  Parâmetro opcional de espera. Por padrão é `MYSQLX_LOCK_DEFAULT`. Valores válidos são estas constantes:

  - `MYSQLX_LOCK_DEFAULT`

  - `MYSQLX_LOCK_NOWAIT`

  - `MYSQLX_LOCK_SKIP_LOCKED`

### Valor Retornado

Um objeto CollectionFind que pode ser usado para processamento adicional.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CollectionFind::lockShared()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $session->startTransaction();

    $result = $collection
      ->find("age > 50")
      ->lockShared()
      ->execute();

    // ... lê o objeto em modo compartilhado

    // Completa a transação e destrava o documento
    $session->commit();
    ?>

# CollectionFind::offset

(No version information available, might only be in Git)

CollectionFind::offset — Pula um número de elementos a serem retornados

### Descrição

public function mysql_xdevapi\CollectionFind::offset(int `$position`): mysql_xdevapi\CollectionFind

Pula (desloca) este número de elementos que de outra forma seriam retornados pela operação de pesquisa. Use com o método limit().

Definir um deslocamento maior que o tamanho do conjunto de resultados resulta em um conjunto vazio.

### Parâmetros

`position`

  Número de elementos a pular para a operação limit().

### Valor Retornado

Um objeto CollectionFind que pode ser usado para processamento adicional.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CollectionFind::offset()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");
    $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();
    $create
      ->add('{"name": "Reginald", "age": 42, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find()
      ->sort('age asc')
      ->offset(1)
      ->limit(1)
      ->execute();

    var_dump($result->fetchAll());
    ?>

O exemplo acima produzirá algo semelhante a:

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000f3"
        ["age"]=>
        int(42)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(8) "Reginald"
      }
    }

# CollectionFind::sort

(No version information available, might only be in Git)

CollectionFind::sort — Define os critérios de ordenação

### Descrição

public function mysql_xdevapi\CollectionFind::sort(string `$sort_expr`): mysql_xdevapi\CollectionFind

Ordena o conjunto de resultados pelo campo selecionado no argumento sort_expr. As ordens suportadas são ASC (ascendente) ou DESC (descendente). Esta operação é equivalente à 'ORDER BY' do SQL e segue o mesmo conjunto de regras.

### Parâmetros

`sort_expr`

  Uma ou mais expressões podem ser fornecidas. A avaliação é da esquerda para a direita, e as expressões são separadas por vírgula.

### Valor Retornado

Um objeto CollectionFind que pode ser usado para executar o comando, ou para inserir operações adicionais.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CollectionFind::sort()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");
    $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();
    $create
      ->add('{"name": "Reginald", "age": 42, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find()
      ->sort('job desc', 'age asc')
      ->execute();

    var_dump($result->fetchAll());
    ?>

O exemplo acima produzirá algo semelhante a:

    array(2) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b53610000000000000106"
        ["age"]=>
        int(18)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(6) "Alfred"
      }
      [1]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b53610000000000000107"
        ["age"]=>
        int(42)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(8) "Reginald"
      }
    }

## Índice

- CollectionFind::bind — Vincula valor a marcador na consulta
- CollectionFind::__construct — Construtor de CollectionFind
- CollectionFind::execute — Executa a instrução
- CollectionFind::fields — Define filtro de campo de documento
- CollectionFind::groupBy — Define critérios de agrupamento
- CollectionFind::having — Define condição para funções de agregação
- CollectionFind::limit — Limita o número de documentos retornados
- CollectionFind::lockExclusive — Executa a operação com EXCLUSIVE LOCK
- CollectionFind::lockShared — Executa a operação com SHARED LOCK
- CollectionFind::offset — Pula um número de elementos a serem retornados
- CollectionFind::sort — Define os critérios de ordenação

# Classe CollectionModify

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

## Resumo da classe

class mysql_xdevapi\CollectionModify implements mysql_xdevapi\Executable, mysql_xdevapi\CrudOperationBindable, mysql_xdevapi\CrudOperationLimitable, mysql_xdevapi\CrudOperationSkippable, mysql_xdevapi\CrudOperationSortable {
/* Métodos */
public function arrayAppend(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify
public function arrayInsert(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify
public function bind(array `$placeholder_values`): mysql_xdevapi\CollectionModify
public function execute(): mysql_xdevapi\Result
public function limit(int `$rows`): mysql_xdevapi\CollectionModify
public function patch(string `$document`): mysql_xdevapi\CollectionModify
public function replace(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify
public function set(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify
public function skip(int `$position`): mysql_xdevapi\CollectionModify
public function sort(string `$sort_expr`): mysql_xdevapi\CollectionModify
public function unset(array `$fields`): mysql_xdevapi\CollectionModify
}

# CollectionModify::arrayAppend

(No version information available, might only be in Git)

CollectionModify::arrayAppend — Anexa elemento a um array de campos

### Descrição

public function mysql_xdevapi\CollectionModify::arrayAppend(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify

Adiciona um elemento a um array de campos do documento, já que múltiplos documentos de um campo são representados como um array. Diferentemente de arrayInsert(), arrayAppend() sempre anexa o novo elemento ao final do array, enquanto que arrayInsert() pode definir a localização.

### Parâmetros

`collection_field`

  O identificador do campo onde o novo elemento é inserido.

`expression_or_literal`

  O novo elemento a inserir no final do array de campos do documento.

### Valor Retornado

Um objeto CollectionModify que pode ser usado para executar o comando, ou para operações adicionais.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CollectionModify::arrayAppend()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name in ('Bernie', 'Jane')")
      ->arrayAppend('traits', 'Happy')
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b5361000000000000010c
                [name] => Bernie
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Brother
                        [2] => Human
                        [3] => Happy
                    )
            )
    )

# CollectionModify::arrayInsert

(No version information available, might only be in Git)

CollectionModify::arrayInsert — Insere elemento em um array de campos

### Descrição

public function mysql_xdevapi\CollectionModify::arrayInsert(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify

Adiciona um elemento a um campo do documento, já que múltiplos documentos de um campo são representados como um array. Diferentemente de mysql_xdevapi\CollectionModify::arrayAppend() este método permite especificar onde o novo elemento é inserido definindo que item o precede, enquanto que mysql_xdevapi\CollectionModify::arrayAppend() sempre anexa o novo elemento no final do array.

### Parâmetros

`collection_field`

  Identifica o item no array após o qual o novo elemento será inserido. O formato deste parâmetro é `FIELD_NAME[ INDEX ]` onde FIELD_NAME é o nome do campo do documento ao qual o elemento será adicionado, e INDEX é o índice do elemento dentro do campo.

  O campo INDEX inicia em zero, portanto o primeiro item do array tem um índice de 0.

`expression_or_literal`

  O novo elemento a inserir após FIELD_NAME[ INDEX ]

### Valor Retornado

Um objeto CollectionModify que pode ser usado para executar o comando, ou para inserir operações adicionais.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CollectionModify::arrayInsert()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name in ('Bernie', 'Jane')")
      ->arrayInsert('traits[1]', 'Happy')
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b5361000000000000010d
                [name] => Bernie
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Happy
                        [2] => Brother
                        [3] => Human
                    )
            )
    )

# CollectionModify::bind

(No version information available, might only be in Git)

CollectionModify::bind — Vincula valor ao marcador da consulta

### Descrição

public function mysql_xdevapi\CollectionModify::bind(array `$placeholder_values`): mysql_xdevapi\CollectionModify

Vincula um parâmetro ao marcador na condição de pesquisa da operação de modificação.

O marcador tem a forma :NOME onde ':' é um prefixo comum que deve sempre existir antes de qualquer NOME de marcador. O método de vinculação aceita uma lista de marcadores se múltiplas entidades tiverem que ser substituídas na condição de pesquisa da operação de modificação.

### Parâmetros

`placeholder_values`

  Valores de marcadores para substituir na condição de pesquisa. Valores múltiplos são permitidos e devem ser passados como um array de mapeamentos NOME_DO_MARCADOR=>VALOR_DO_MARCADOR.

### Valor Retornado

Um objeto CollectionModify que pode ser usado para executar o comando, ou para inserir operações adicionais.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CollectionModify::bind()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name = :name")
      ->bind(['name' => 'Bernie'])
      ->arrayAppend('traits', 'Happy')
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b53610000000000000110
                [name] => Bernie
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Brother
                        [2] => Human
                        [3] => Happy
                    )
            )
    )

# CollectionModify::__construct

(No version information available, might only be in Git)

CollectionModify::__construct — Construtor de CollectionModify

### Descrição

private function mysql_xdevapi\CollectionModify::__construct()

Modifica (atualiza) uma coleção e é instanciada pelo método mysql_xdevapi\Collection::modify().

### Parâmetros

Esta função não possui parâmetros.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CollectionModify::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name in ('Bernie', 'Jane')")
      ->arrayAppend('traits', 'Happy')
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b5361000000000000010c
                [name] => Bernie
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Brother
                        [2] => Human
                        [3] => Happy
                    )
            )
    )

# CollectionModify::execute

(No version information available, might only be in Git)

CollectionModify::execute — Executa operação de modificação

### Descrição

public function mysql_xdevapi\CollectionModify::execute(): mysql_xdevapi\Result

O método de execução é requerido para enviar a requisição de operação CRUD ao servidor MySQL.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um objeto Result que pode ser usado para verificar o status da operação, como o número de linhas afetadas.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CollectionModify::execute()

    <?php

    /* ... */

    ?>

# CollectionModify::limit

(No version information available, might only be in Git)

CollectionModify::limit — Limita o número de documentos modificados

### Descrição

public function mysql_xdevapi\CollectionModify::limit(int `$rows`): mysql_xdevapi\CollectionModify

Limita o número de documentos modificados por esta operação. Opcionalmente pode ser combinada com skip() para definir um valor de deslocamento.

### Parâmetros

`rows`

  O número máximo de documentos a modificar.

### Valor Retornado

Um objeto CollectionModify.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CollectionModify::limit()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $collection->add('{"name": "Fred",  "age": 21, "job": "Construction"}')->execute();
    $collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();
    $collection->add('{"name": "Betty", "age": 24, "job": "Teacher"}')->execute();

    $collection
      ->modify("job = :job")
      ->bind(['job' => 'Teacher'])
      ->set('job', 'Principal')
      ->limit(1)
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b53610000000000000118
                [age] => 21
                [job] => Construction
                [name] => Fred
            )
        [1] => Array
            (
                [_id] => 00005b6b53610000000000000119
                [age] => 23
                [job] => Principal
                [name] => Wilma
            )
        [2] => Array
            (
                [_id] => 00005b6b5361000000000000011a
                [age] => 24
                [job] => Teacher
                [name] => Betty
            )
    )

# CollectionModify::patch

(No version information available, might only be in Git)

CollectionModify::patch — Corrige documento

### Descrição

public function mysql_xdevapi\CollectionModify::patch(string `$document`): mysql_xdevapi\CollectionModify

Aplica um objeto de correção a um ou mais documentos, podendo atualizar várias propriedades do documento.

### Parâmetros

`document`

  Um documento com as propriedades a serem aplicadas aos documentos correspondentes.

### Valor Retornado

Um objeto CollectionModify.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CollectionModify::patch()

    <?php

    $res = $coll->modify('"Programmatore" IN job')->patch('{"Hobby" : "Programmare"}')->execute();

    ?>

# CollectionModify::replace

(No version information available, might only be in Git)

CollectionModify::replace — Substitui campo de documento

### Descrição

public function mysql_xdevapi\CollectionModify::replace(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify

Substitui (atualiza) um valor de campo fornecido com um novo.

### Parâmetros

`collection_field`

  O caminho do documento do item a definir.

`expression_or_literal`

  O valor a ser definido no atributo especificado.

### Valor Retornado

Um objeto CollectionModify.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CollectionModify::replace()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name = :name")
      ->bind(['name' => 'Bernie'])
      ->replace("name", "Bern")
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b5361000000000000011b
                [name] => Bern
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Brother
                        [2] => Human
                    )
            )
    )

# CollectionModify::set

(No version information available, might only be in Git)

CollectionModify::set — Define atributo de documento

### Descrição

public function mysql_xdevapi\CollectionModify::set(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify

Define ou atualiza atributos em documentos de uma coleção.

### Parâmetros

`collection_field`

  O caminho (nome) do documento do item a ser definido.

`expression_or_literal`

  O valor para o qual será definido.

### Valor Retornado

Um objeto CollectionModify.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CollectionModify::set()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name = :name")
      ->bind(['name' => 'Bernie'])
      ->set("name", "Bern")
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b53610000000000000111
                [name] => Bern
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Brother
                        [2] => Human
                    )
            )
    )

# CollectionModify::skip

(No version information available, might only be in Git)

CollectionModify::skip — Pula elementos

### Descrição

public function mysql_xdevapi\CollectionModify::skip(int `$position`): mysql_xdevapi\CollectionModify

Pula os primeiros N elementos que seriam de outra forma retornados por uma operação de pesquisa. Se o número de elementos pulados for maior que o tamanho do conjunto de resultados, a operação de pesquisa retorna um conjunto vazio.

### Parâmetros

`position`

  Número de elementos a pular.

### Valor Retornado

Um objeto CollectionModify para uso em processamento adicional.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CollectionModify::skip()

    <?php

    $coll->modify('age > :age')->sort('age desc')->unset(['age'])->bind(['age' => 20])->limit(4)->skip(1)->execute();

    ?>

# CollectionModify::sort

(No version information available, might only be in Git)

CollectionModify::sort — Define os critérios de ordenação

### Descrição

public function mysql_xdevapi\CollectionModify::sort(string `$sort_expr`): mysql_xdevapi\CollectionModify

Ordena o conjunto de resultados pelo campo selecionado no argumento sort_expr. As ordens permitidas são ASC (ascendente) ou DESC (descendente). Esta operação é equivalente à 'ORDER BY' do SQL e segue o mesmo conjunto de regras.

### Parâmetros

`sort_expr`

  Uma ou mais expressões podem ser informadas. A avaliação é da esquerda para a direita e cada expressão precisa ser separada por uma vírgula.

### Valor Retornado

Objeto CollectionModify que pode ser usado para processamentos adicionais.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CollectionModify::sort()

    <?php

    $res = $coll->modify('true')->sort('name desc', 'age asc')->limit(4)->set('Married', 'NO')->execute();

    ?>

# CollectionModify::unset

(No version information available, might only be in Git)

CollectionModify::unset — Remove o valor de campos do documento

### Descrição

public function mysql_xdevapi\CollectionModify::unset(array `$fields`): mysql_xdevapi\CollectionModify

Remove atributos de documentos em uma coleção.

### Parâmetros

`fields`

  Os atributos a remover dos documentos em uma coleção.

### Valor Retornado

Objeto CollectionModify que pode ser usado para processamento adicional.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CollectionModify::unset()

    <?php

    $res = $coll->modify('job like :job_name')->unset(["age", "name"])->bind(['job_name' => 'Plumber'])->execute();

    ?>

## Índice

- CollectionModify::arrayAppend — Anexa elemento a um array de campos
- CollectionModify::arrayInsert — Insere elemento em um array de campos
- CollectionModify::bind — Vincula valor ao marcador da consulta
- CollectionModify::__construct — Construtor de CollectionModify
- CollectionModify::execute — Executa operação de modificação
- CollectionModify::limit — Limita o número de documentos modificados
- CollectionModify::patch — Corrige documento
- CollectionModify::replace — Substitui campo de documento
- CollectionModify::set — Define atributo de documento
- CollectionModify::skip — Pula elementos
- CollectionModify::sort — Define os critérios de ordenação
- CollectionModify::unset — Remove o valor de campos do documento

# Classe CollectionRemove

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

## Resumo da classe

class mysql_xdevapi\CollectionRemove implements mysql_xdevapi\Executable, mysql_xdevapi\CrudOperationBindable, mysql_xdevapi\CrudOperationLimitable, mysql_xdevapi\CrudOperationSortable {
/* Métodos */
public function bind(array `$placeholder_values`): mysql_xdevapi\CollectionRemove
public function execute(): mysql_xdevapi\Result
public function limit(int `$rows`): mysql_xdevapi\CollectionRemove
public function sort(string `$sort_expr`): mysql_xdevapi\CollectionRemove
}

# CollectionRemove::bind

(No version information available, might only be in Git)

CollectionRemove::bind — Vincula valor ao marcador

### Descrição

public function mysql_xdevapi\CollectionRemove::bind(array `$placeholder_values`): mysql_xdevapi\CollectionRemove

Vincula um parâmetro ao marcador na condição de pesquisa da operação de remoção.

O marcador tem a forma :NOME onde ':' é um prefixo comum que deve sempre existir antes de qualquer NOME de marcador. O método de vinculação aceita uma lista de marcadores se múltiplas entidades tiverem que ser substituídas na condição de pesquisa da operação de remoção.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`placeholder_values`

  Valores de marcadores para substituir na condição de pesquisa. Valores múltiplos são permitidos e devem ser passados como um array de mapeamentos NOME_DO_MARCADOR=>VALOR_DO_MARCADOR.

### Valor Retornado

Um objeto CollectionRemove que pode ser usado para executar o comando, ou para inserir operações adicionais.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CollectionRemove::bind()

    <?php

    $res = $coll->remove('age > :age_from and age < :age_to')->bind(['age_from' => 20, 'age_to' => 50])->limit(7)->execute();

    ?>

# CollectionRemove::__construct

(No version information available, might only be in Git)

CollectionRemove::__construct — Construtor de CollectionRemove

### Descrição

private function mysql_xdevapi\CollectionRemove::__construct()

Remove documentos de coleções e é instanciado pelo método mysql_xdevapi\Collection::remove().

### Parâmetros

Esta função não possui parâmetros.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Collection::remove()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $collection->add('{"name": "Bob",    "age": 19, "job": "Painter"}')->execute();

    // Remove todos os 'Painters'
    $collection
      ->remove("job in ('Painter')")
      ->execute();

    // Remove o 'Butler' com maior 'age'
    $collection
      ->remove("job in ('Butler')")
      ->sort('age desc')
      ->limit(1)
      ->execute();

    // Remove registro com maior 'age'
    $collection
      ->remove('true')
      ->sort('age desc')
      ->limit(1)
      ->execute();
    ?>

# CollectionRemove::execute

(No version information available, might only be in Git)

CollectionRemove::execute — Executa operação de remoção

### Descrição

public function mysql_xdevapi\CollectionRemove::execute(): mysql_xdevapi\Result

O método de execução precisa ser chamado para disparar o envio da requisição de operação CRUD do cliente para o servidor MySQL.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Objeto Result.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CollectionRemove::execute()

    <?php

    $res = $coll->remove('true')->sort('age desc')->limit(2)->execute();

    ?>

# CollectionRemove::limit

(No version information available, might only be in Git)

CollectionRemove::limit — Limita o número de documentos a remover

### Descrição

public function mysql_xdevapi\CollectionRemove::limit(int `$rows`): mysql_xdevapi\CollectionRemove

Define o número máximo de documentos a remover.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`rows`

  O número máximo de documentos a remover.

### Valor Retornado

Retorna um objeto CollectionRemove que pode ser usado para executar o comando, ou para inserir operações adicionais.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CollectionRemove::limit()

    <?php

    $res = $coll->remove('job in (\'Barista\', \'Programmatore\', \'Ballerino\', \'Programmatrice\')')->limit(5)->sort(['age desc', 'name asc'])->execute();

    ?>

# CollectionRemove::sort

(No version information available, might only be in Git)

CollectionRemove::sort — Define os critérios de ordenação

### Descrição

public function mysql_xdevapi\CollectionRemove::sort(string `$sort_expr`): mysql_xdevapi\CollectionRemove

Ordena o conjunto de resultados pelo campo selecionado no argumento sort_expr. As ordens permitidas são ASC (ascendente) ou DESC (descendente). Esta operação é equivalente à 'ORDER BY' do SQL e segue o mesmo conjunto de regras.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`sort_expr`

  Uma ou mais expressões podem ser informadas. A avaliação é da esquerda para a direita e cada expressão precisa ser separada por uma vírgula.

### Valor Retornado

Um objeto CollectionRemove que pode ser usado para executar o comando, ou para processamentos adicionais.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CollectionRemove::sort()

    <?php

    $res = $coll->remove('true')->sort('age desc')->limit(2)->execute();

    ?>

## Índice

- CollectionRemove::bind — Vincula valor ao marcador
- CollectionRemove::__construct — Construtor de CollectionRemove
- CollectionRemove::execute — Executa operação de remoção
- CollectionRemove::limit — Limita o número de documentos a remover
- CollectionRemove::sort — Define os critérios de ordenação

# Classe ColumnResult

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

## Resumo da classe

class mysql_xdevapi\ColumnResult {
/* Métodos */
public function getCharacterSetName(): string
public function getCollationName(): string
public function getColumnLabel(): string
public function getColumnName(): string
public function getFractionalDigits(): int
public function getLength(): int
public function getSchemaName(): string
public function getTableLabel(): string
public function getTableName(): string
public function getType(): int
public function isNumberSigned(): int
public function isPadded(): int
}

# ColumnResult::__construct

(No version information available, might only be in Git)

ColumnResult::__construct — Construtor de ColumnResult

### Descrição

private function mysql_xdevapi\ColumnResult::__construct()

Recupera os metadados de coluna, como seu conjunto de caracteres; é instanciado pelo método mysql_xdevapi\RowResult::getColumns().

### Parâmetros

Esta função não possui parâmetros.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\ColumnResult::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS nonsense")->execute();
    $session->sql("CREATE DATABASE nonsense")->execute();
    $session->sql("CREATE TABLE nonsense.numbers (hello int, world float unsigned)")->execute();
    $session->sql("INSERT INTO  nonsense.numbers values (42, 42)")->execute();

    $schema = $session->getSchema("nonsense");
    $table  = $schema->getTable("numbers");

    $result1 = $table->select('hello','world')->execute();

    // Retorna um array de objetos ColumnResult
    $columns = $result1->getColumns();

    foreach ($columns as $column) {
        echo "\nColuna de nome " , $column->getColumnLabel();
        echo " é do tipo "       , $column->getType();
        echo " e é ", ($column->isNumberSigned() === 0) ? "sem sinal." : "com sinal.";
    }

    // Alternativamente
    $result2 = $session->sql("SELECT * FROM nonsense.numbers")->execute();

    // Retorna um array de objetos FieldMetadata
    print_r($result2->getColumns());

O exemplo acima produzirá algo semelhante a:

    Coluna de nome hello é do tipo 19 e é com sinal.
    Coluna de nome world é do tipo 4 e é sem sinal.

    Array
    (
        [0] => mysql_xdevapi\FieldMetadata Object
            (
                [type] => 1
                [type_name] => SINT
                [name] => hello
                [original_name] => hello
                [table] => numbers
                [original_table] => numbers
                [schema] => nonsense
                [catalog] => def
                [collation] => 0
                [fractional_digits] => 0
                [length] => 11
                [flags] => 0
                [content_type] => 0
            )
        [1] => mysql_xdevapi\FieldMetadata Object
            (
                [type] => 6
                [type_name] => FLOAT
                [name] => world
                [original_name] => world
                [table] => numbers
                [original_table] => numbers
                [schema] => nonsense
                [catalog] => def
                [collation] => 0
                [fractional_digits] => 31
                [length] => 12
                [flags] => 1
                [content_type] => 0
            )
    )

# ColumnResult::getCharacterSetName

(No version information available, might only be in Git)

ColumnResult::getCharacterSetName — Obtém o conjunto de caracteres

### Descrição

public function mysql_xdevapi\ColumnResult::getCharacterSetName(): string

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\ColumnResult::getCharacterSetName()

    <?php

    /* ... */

    ?>

# ColumnResult::getCollationName

(No version information available, might only be in Git)

ColumnResult::getCollationName — Obtém o nome da colação

### Descrição

public function mysql_xdevapi\ColumnResult::getCollationName(): string

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\ColumnResult::getCollationName()

    <?php

    /* ... */

    ?>

# ColumnResult::getColumnLabel

(No version information available, might only be in Git)

ColumnResult::getColumnLabel — Obtém o label da coluna

### Descrição

public function mysql_xdevapi\ColumnResult::getColumnLabel(): string

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\ColumnResult::getColumnLabel()

    <?php

    /* ... */

    ?>

# ColumnResult::getColumnName

(No version information available, might only be in Git)

ColumnResult::getColumnName — Obtém o nome da coluna

### Descrição

public function mysql_xdevapi\ColumnResult::getColumnName(): string

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\ColumnResult::getColumnName()

    <?php

    /* ... */

    ?>

# ColumnResult::getFractionalDigits

(No version information available, might only be in Git)

ColumnResult::getFractionalDigits — Obtém o comprimento dos dígitos fracionários

### Descrição

public function mysql_xdevapi\ColumnResult::getFractionalDigits(): int

Busca o número de dígitos fracionários para a coluna.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\ColumnResult::getFractionalDigits()

    <?php

    /* ... */

    ?>

# ColumnResult::getLength

(No version information available, might only be in Git)

ColumnResult::getLength — Obtém o comprimento do campo da coluna

### Descrição

public function mysql_xdevapi\ColumnResult::getLength(): int

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\ColumnResult::getLength()

    <?php

    /* ... */

    ?>

# ColumnResult::getSchemaName

(No version information available, might only be in Git)

ColumnResult::getSchemaName — Obtám o nome do esquema

### Descrição

public function mysql_xdevapi\ColumnResult::getSchemaName(): string

Obtám o nome do esquema onde a coluna é armazenada.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\ColumnResult::getSchemaName()

    <?php

    /* ... */

    ?>

# ColumnResult::getTableLabel

(No version information available, might only be in Git)

ColumnResult::getTableLabel — Obtém o label da tabela

### Descrição

public function mysql_xdevapi\ColumnResult::getTableLabel(): string

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\ColumnResult::getTableLabel()

    <?php

    /* ... */

    ?>

# ColumnResult::getTableName

(No version information available, might only be in Git)

ColumnResult::getTableName — Obtém o nome da tabela

### Descrição

public function mysql_xdevapi\ColumnResult::getTableName(): string

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nome da tabela para a coluna.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\ColumnResult::getTableName()

    <?php

    /* ... */

    ?>

# ColumnResult::getType

(No version information available, might only be in Git)

ColumnResult::getType — Obtém o tipo de coluna

### Descrição

public function mysql_xdevapi\ColumnResult::getType(): int

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\ColumnResult::getType()

    <?php

    /* ... */

    ?>

# ColumnResult::isNumberSigned

(No version information available, might only be in Git)

ColumnResult::isNumberSigned — Verifica se é do tipo com sinal

### Descrição

public function mysql_xdevapi\ColumnResult::isNumberSigned(): int

Recupera informação da coluna e é instanciado pelo método mysql_xdevapi\RowResult::getColumns().

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

`true` se a coluna informada tem um tipo com sinal.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\ColumnResult::isNumberSigned()

    <?php

    /* ... */

    ?>

# ColumnResult::isPadded

(No version information available, might only be in Git)

ColumnResult::isPadded — Verifica se é preenchida à esquerda

### Descrição

public function mysql_xdevapi\ColumnResult::isPadded(): int

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

`true` se a coluna informada é preenchida à esquerda.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\ColumnResult::isPadded()

    <?php

    /* ... */

    ?>

## Índice

- ColumnResult::__construct — Construtor de ColumnResult
- ColumnResult::getCharacterSetName — Obtém o conjunto de caracteres
- ColumnResult::getCollationName — Obtém o nome da colação
- ColumnResult::getColumnLabel — Obtém o label da coluna
- ColumnResult::getColumnName — Obtém o nome da coluna
- ColumnResult::getFractionalDigits — Obtém o comprimento dos dígitos fracionários
- ColumnResult::getLength — Obtém o comprimento do campo da coluna
- ColumnResult::getSchemaName — Obtám o nome do esquema
- ColumnResult::getTableLabel — Obtém o label da tabela
- ColumnResult::getTableName — Obtém o nome da tabela
- ColumnResult::getType — Obtém o tipo de coluna
- ColumnResult::isNumberSigned — Verifica se é do tipo com sinal
- ColumnResult::isPadded — Verifica se é preenchida à esquerda

# Interface CrudOperationBindable

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

## Resumo da classe

class mysql_xdevapi\CrudOperationBindable {
/* Métodos */
abstract public function bind(array `$placeholder_values`): mysql_xdevapi\CrudOperationBindable
}

# CrudOperationBindable::bind

(No version information available, might only be in Git)

CrudOperationBindable::bind — Vincula valor ao marcador

### Descrição

abstract public function mysql_xdevapi\CrudOperationBindable::bind(array `$placeholder_values`): mysql_xdevapi\CrudOperationBindable

Vincula um valor a um marcador específico.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`placeholder_values`

  Os nomes dos marcadores e os valores a vincular.

### Valor Retornado

Um objeto CrudOperationBindable.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CrudOperationBindable::bind()

    <?php

    $res = $coll->modify('name like :name')->arrayInsert('job[0]', 'Calciatore')->bind(['name' => 'ENTITY'])->execute();
    $res = $table->delete()->orderby('age desc')->where('age < 20 and age > 12 and name != :name')->bind(['name' => 'Tierney'])->limit(2)->execute();

    ?>

## Índice

- CrudOperationBindable::bind — Vincula valor ao marcador

# Interface CrudOperationLimitable

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

## Resumo da classe

class mysql_xdevapi\CrudOperationLimitable {
/* Métodos */
abstract public function limit(int `$rows`): mysql_xdevapi\CrudOperationLimitable
}

# CrudOperationLimitable::limit

(No version information available, might only be in Git)

CrudOperationLimitable::limit — Define o limite do resultado

### Descrição

abstract public function mysql_xdevapi\CrudOperationLimitable::limit(int `$rows`): mysql_xdevapi\CrudOperationLimitable

Define o número máximo de registros ou documentos a retornar.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`rows`

  O número máximo de registros ou documentos.

### Valor Retornado

Um objeto CrudOperationLimitable.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CrudOperationLimitable::limit()

    <?php

    $res = $coll->find()->fields(['name as n','age as a','job as j'])->groupBy('j')->limit(11)->execute();
    $res = $table->update()->set('age',69)->where('age > 15 and age < 22')->limit(4)->orderby(['age asc','name desc'])->execute();

    ?>

## Índice

- CrudOperationLimitable::limit — Define o limite do resultado

# Interface CrudOperationSkippable

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

## Resumo da classe

class mysql_xdevapi\CrudOperationSkippable {
/* Métodos */
abstract public function skip(int `$skip`): mysql_xdevapi\CrudOperationSkippable
}

# CrudOperationSkippable::skip

(No version information available, might only be in Git)

CrudOperationSkippable::skip — Número de operações a pular

### Descrição

abstract public function mysql_xdevapi\CrudOperationSkippable::skip(int `$skip`): mysql_xdevapi\CrudOperationSkippable

Pula este número de registros na operação retornada.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`skip`

  Número de elementos a pular.

### Valor Retornado

Um objeto CrudOperationSkippable.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CrudOperationSkippable::skip()

    <?php

    $res = $coll->find('job like \'Programmatore\'')->limit(1)->skip(3)->sort('age asc')->execute();

    ?>

## Índice

- CrudOperationSkippable::skip — Número de operações a pular

# Interface CrudOperationSortable

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

## Resumo da classe

class mysql_xdevapi\CrudOperationSortable {
/* Métodos */
abstract public function sort(string `$sort_expr`): mysql_xdevapi\CrudOperationSortable
}

# CrudOperationSortable::sort

(No version information available, might only be in Git)

CrudOperationSortable::sort — Ordena resultados

### Descrição

abstract public function mysql_xdevapi\CrudOperationSortable::sort(string `$sort_expr`): mysql_xdevapi\CrudOperationSortable

Ordena o conjunto de resultados pelo campo selecionado no argumento sort_expr. As ordens permitidas são ASC (ascendente) ou DESC (descendente). Esta operação é equivalente à 'ORDER BY' do SQL e segue o mesmo conjunto de regras.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`sort_expr`

  Uma ou mais expressões podem ser informadas. A avaliação é da esquerda para a direita e cada expressão precisa ser separada por uma vírgula.

### Valor Retornado

Um objeto CrudOperationSortable.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\CrudOperationSortable::sort()

    <?php

    $res = $coll->find('job like \'Cavia\'')->sort('age desc', '_id desc')->execute();

    ?>

## Índice

- CrudOperationSortable::sort — Ordena resultados

# Interface DatabaseObject

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

## Resumo da classe

class mysql_xdevapi\DatabaseObject {
/* Métodos */
abstract public function existsInDatabase(): bool
abstract public function getName(): string
abstract public function getSession(): mysql_xdevapi\Session
}

# DatabaseObject::existsInDatabase

(No version information available, might only be in Git)

DatabaseObject::existsInDatabase — Verifica se um objeto existe em um banco de dados

### Descrição

abstract public function mysql_xdevapi\DatabaseObject::existsInDatabase(): bool

Verifica se o objeto se refere a um que exista no banco de dados.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se o objeto existe no banco de dados ou `false` se não existe.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\DatabaseObject::existsInDatabase()

    <?php

    $existInDb = $dbObj->existsInDatabase();

    ?>

# DatabaseObject::getName

(No version information available, might only be in Git)

DatabaseObject::getName — Obtém o nome do objeto

### Descrição

abstract public function mysql_xdevapi\DatabaseObject::getName(): string

Busca o nome deste objeto de banco de dados.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O nome deste objeto de banco de dados.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\DatabaseObject::getName()

    <?php

    $dbObjName = $dbObj->getName();

    ?>

# DatabaseObject::getSession

(No version information available, might only be in Git)

DatabaseObject::getSession — Obtém o nome da sessão

### Descrição

abstract public function mysql_xdevapi\DatabaseObject::getSession(): mysql_xdevapi\Session

Busca a sessão associada ao objeto de banco de dados.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O objeto Session.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\DatabaseObject::getSession()

    <?php

    $session = $dbObj->getSession();

    ?>

## Índice

- DatabaseObject::existsInDatabase — Verifica se um objeto existe em um banco de dados
- DatabaseObject::getName — Obtém o nome do objeto
- DatabaseObject::getSession — Obtém o nome da sessão

# Classe DocResult

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

## Resumo da classe

class mysql_xdevapi\DocResult implements mysql_xdevapi\BaseResult, Traversable {
/* Métodos */
public function fetchAll(): array
public function fetchOne(): array
public function getWarnings(): Array
public function getWarningsCount(): int
}

# DocResult::__construct

(No version information available, might only be in Git)

DocResult::__construct — Construtor de DocResult

### Descrição

private function mysql_xdevapi\DocResult::__construct()

Busca os resultados de documentos e alertas, e é instanciado por CollectionFind.

### Parâmetros

Esta função não possui parâmetros.

### Exemplos

Exemplo #1 Um exemplo de DocResult

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

    // ...

    $collection = $schema->getCollection("people");

    // Gera um objeto DocResult
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->limit(1)
      ->execute();

    var_dump($result->fetchAll());
    ?>

O exemplo acima produzirá algo semelhante a:

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000f3"
        ["age"]=>
        int(42)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(8) "Reginald"
      }
    }

# DocResult::fetchAll

(No version information available, might only be in Git)

DocResult::fetchAll — Obtém todas as linhas

### Descrição

public function mysql_xdevapi\DocResult::fetchAll(): array

Busca todos os resultados de um conjunto.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array numérico com todos os resultados da consulta; cada resultado é um array associativo. Um array vazio é retornado se nenhuma linha estiver presente.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\DocResult::fetchAll()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

    // ...

    $collection = $schema->getCollection("people");

    // Gera um objeto DocResult
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->execute();

    var_dump($result->fetchAll());
    ?>

O exemplo acima produzirá algo semelhante a:

    array(2) {

      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b53610000000000000123"
        ["age"]=>
        int(42)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(8) "Reginald"
      }

      [1]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b53610000000000000122"
        ["age"]=>
        int(18)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(6) "Alfred"
      }

    }

# DocResult::fetchOne

(No version information available, might only be in Git)

DocResult::fetchOne — Obtém uma linha

### Descrição

public function mysql_xdevapi\DocResult::fetchOne(): array

Busca um resultado de um conjunto de resultados.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O resultado, como um array associativo ou `null` se nenhum resultado estiver presente.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\DocResult::fetchOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

    // ...

    $collection = $schema->getCollection("people");

    // Gera um objeto DocResult
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->execute();

    var_dump($result->fetchOne());
    ?>

O exemplo acima produzirá algo semelhante a:

    array(4) {
      ["_id"]=>
      string(28) "00005b6b53610000000000000125"
      ["age"]=>
      int(42)
      ["job"]=>
      string(6) "Butler"
      ["name"]=>
      string(8) "Reginald"
    }

# DocResult::getWarnings

(No version information available, might only be in Git)

DocResult::getWarnings — Obtém alertas da última operação

### Descrição

public function mysql_xdevapi\DocResult::getWarnings(): Array

Busca alertas gerados pela última operação do servidor MySQL.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array contendo objetos Warning da última operação. Cada objeto define uma mensagem de erro ('message'), um nível de erro ('level') e um código de erro ('code'). Um array vazio é retornado se nenhum erro tiver ocorrido.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\DocResult::getWarnings()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

    // ...

    $collection = $schema->getCollection("people");

    // Gera um objeto DocResult
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->execute();

    if (!$result->getWarningsCount()) {
        echo "Ocorreu um erro:\n";
        print_r($result->getWarnings());
        exit;
    }

    var_dump($result->fetchOne());
    ?>

O exemplo acima produzirá algo semelhante a:

    Ocorreu um erro:

    Array
    (
        [0] => mysql_xdevapi\Warning Object
            (
                [message] => Algo de errado
                [level] => 2
                [code] => 1365
            )
        [1] => mysql_xdevapi\Warning Object
            (
                [message] => Algo de errado
                [level] => 2
                [code] => 1365
            )
    )

# DocResult::getWarningsCount

(No version information available, might only be in Git)

DocResult::getWarningsCount — Obtém a contagem de alertas da última operação

### Descrição

public function mysql_xdevapi\DocResult::getWarningsCount(): int

Retorna o número de alertas gerados pela última operação. Especificamente, estes alertas são gerados pelo servidor MySQL.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O número de alertas gerados pela última operação.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\DocResult::getWarningsCount()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

    // ...

    $collection = $schema->getCollection("people");

    // Gera um objeto DocResult
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->execute();

    if (!$result->getWarningsCount()) {
        echo "Ocorreu um erro:\n";
        print_r($result->getWarnings());
        exit;
    }

    var_dump($result->fetchOne());
    ?>

O exemplo acima produzirá algo semelhante a:

    array(4) {
      ["_id"]=>
      string(28) "00005b6b53610000000000000135"
      ["age"]=>
      int(42)
      ["job"]=>
      string(6) "Butler"
      ["name"]=>
      string(8) "Reginald"
    }

## Índice

- DocResult::__construct — Construtor de DocResult
- DocResult::fetchAll — Obtém todas as linhas
- DocResult::fetchOne — Obtém uma linha
- DocResult::getWarnings — Obtém alertas da última operação
- DocResult::getWarningsCount — Obtém a contagem de alertas da última operação

# Classe Exception

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

## Resumo da classe

class mysql_xdevapi\Exception extends RuntimeException implements Throwable {
}

# Interface Executable

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

## Resumo da classe

class mysql_xdevapi\Executable {
/* Métodos */
abstract public function execute(): mysql_xdevapi\Result
}

# Executable::execute

(No version information available, might only be in Git)

Executable::execute — Executa instrução

### Descrição

abstract public function mysql_xdevapi\Executable::execute(): mysql_xdevapi\Result

Executa a instrução a partir de uma operação de coleção ou uma consulta de tabela; esta funcionalidade permite encadeamento de métodos.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um dos objetos Result, tal como Result ou SqlStatementResult.

### Exemplos

Exemplo #1 Exemplos de execute()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $result_sql = $session->sql("CREATE DATABASE addressbook")->execute();

    var_dump($result_sql);

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("humans");

    $result_collection = $collection->add(
      '{"name": "Jane",
        "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
        "hobbies": ["Walking","Making pies"]}');

    $result_collection_executed = $result_collection->execute();

    var_dump($result_collection);
    var_dump($result_collection_executed);
    ?>

O exemplo acima produzirá algo semelhante a:

    object(mysql_xdevapi\SqlStatementResult)#3 (0) {
    }

    object(mysql_xdevapi\CollectionAdd)#5 (0) {
    }

    object(mysql_xdevapi\Result)#7 (0) {
    }

## Índice

- Executable::execute — Executa instrução

# Classe ExecutionStatus

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

## Resumo da classe

class mysql_xdevapi\ExecutionStatus {
/* Propriedades */
public $affectedItems;
public $matchedItems;
public $foundItems;
public $lastInsertId;
public $lastDocumentId;
/* Constructor */
private function __construct()
}

## Propriedades

affectedItems

matchedItems

foundItems

lastInsertId

lastDocumentId

# ExecutionStatus::__construct

(No version information available, might only be in Git)

ExecutionStatus::__construct — Construtor de ExecutionStatus

### Descrição

private function mysql_xdevapi\ExecutionStatus::__construct()

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\ExecutionStatus::__construct()

    <?php

    /* ... */

    ?>

## Índice

- ExecutionStatus::__construct — Construtor de ExecutionStatus

# Classe Expression

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

## Resumo da classe

class mysql_xdevapi\Expression {
/* Propriedades */
public $name;
/* Constructor */
public function __construct(string `$expression`)
}

## Propriedades

name

# Expression::__construct

(No version information available, might only be in Git)

Expression::__construct — Construtor de Expression

### Descrição

public function mysql_xdevapi\Expression::__construct(string `$expression`)

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`expression`

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Expression::__construct()

    <?php

    /* ... */

    ?>

## Índice

- Expression::__construct — Construtor de Expression

# Classe Result

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

## Resumo da classe

class mysql_xdevapi\Result implements mysql_xdevapi\BaseResult, Traversable {
/* Métodos */
public function getAffectedItemsCount(): int
public function getAutoIncrementValue(): int
public function getGeneratedIds(): array
public function getWarnings(): array
public function getWarningsCount(): int
}

# Result::__construct

(No version information available, might only be in Git)

Result::__construct — Construtor de Result

### Descrição

private function mysql_xdevapi\Result::__construct()

Um objeto que recupera IDs geradas, valores de AUTO_INCREMENT e alertas para um conjuntos de resultados.

### Parâmetros

Esta função não possui parâmetros.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Result::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("
      CREATE TABLE addressbook.names
        (id INT NOT NULL AUTO_INCREMENT, name VARCHAR(30), age INT, PRIMARY KEY (id))
      ")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->insert("name", "age")->values(["Suzanne", 31],["Julie", 43])->execute();
    $result = $table->insert("name", "age")->values(["Suki", 34])->execute();

    $ai = $result->getAutoIncrementValue();
    var_dump($ai);
    ?>

O exemplo acima produzirá:

    int(3)

# Result::getAffectedItemsCount

(No version information available, might only be in Git)

Result::getAffectedItemsCount — Obtém contagem de linhas afetadas

### Descrição

public function mysql_xdevapi\Result::getAffectedItemsCount(): int

Obtém o número de linhas afetadas pela operação anterior.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O número (como um inteiro) de linhas afetadas.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Result::getAffectedItemsCount()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    $result = $collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

    var_dump( $res->getAffectedItemsCount() );
    ?>

O exemplo acima produzirá:

    int(1)

# Result::getAutoIncrementValue

(No version information available, might only be in Git)

Result::getAutoIncrementValue — Obtém valor de incremento automático

### Descrição

public function mysql_xdevapi\Result::getAutoIncrementValue(): int

Obtém o último valor de AUTO_INCREMENT (último id de inserção).

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O último valor de AUTO_INCREMENT.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Result::getAutoIncrementValue()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("
      CREATE TABLE addressbook.names
        (id INT NOT NULL AUTO_INCREMENT, name VARCHAR(30), age INT, PRIMARY KEY (id))
      ")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->insert("name", "age")->values(["Suzanne", 31],["Julie", 43])->execute();
    $result = $table->insert("name", "age")->values(["Suki", 34])->execute();

    $ai = $result->getAutoIncrementValue();
    var_dump($ai);
    ?>

O exemplo acima produzirá:

    int(3)

# Result::getGeneratedIds

(No version information available, might only be in Git)

Result::getGeneratedIds — Obtém os IDs gerados

### Descrição

public function mysql_xdevapi\Result::getGeneratedIds(): array

Busca os valores de _id gerados na última operação. O campo de _id único é gerado pelo servidor MySQL.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array de IDs gerados na última operação, ou um array vazio se não houve nenhum.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Result::getGeneratedIds()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    $result = $collection->add(
      '{"name": "Bernie",
        "jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
        "hobbies": ["Sports","Making cupcakes"]}',
      '{"name": "Jane",
        "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
        "hobbies": ["Walking","Making pies"]}')->execute();

    $ids = $result->getGeneratedIds();
    var_dump($ids);
    ?>

O exemplo acima produzirá algo semelhante a:

    array(2) {
      [0]=>
      string(28) "00005b6b53610000000000000064"
      [1]=>
      string(28) "00005b6b53610000000000000065"
    }

# Result::getWarnings

(No version information available, might only be in Git)

Result::getWarnings — Obtém alertas da última operação

### Descrição

public function mysql_xdevapi\Result::getWarnings(): array

Recupera alertas da última operação de Result.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array com objetos Warning da última operação. Cada objeto define uma mensagem de erro (chave 'message'), um nível de erro (chave 'level') e um código de erro (chave 'code'). Um array vazio é retornado se nenhum erro estiver presente.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\RowResult::getWarnings()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();
    $warnings = $res->getWarnings();

    print_r($warnings);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
        [1] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
    )

# Result::getWarningsCount

(No version information available, might only be in Git)

Result::getWarningsCount — Obtém contagem de alertas da última operação

### Descrição

public function mysql_xdevapi\Result::getWarningsCount(): int

Obtém o número de alertas da última operação Result.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O número de alertas gerados pela última operação.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\RowResult::getWarningsCount()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS foo")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();

    echo $res->getWarningsCount();
    ?>

O exemplo acima produzirá algo semelhante a:

    2

## Índice

- Result::__construct — Construtor de Result
- Result::getAffectedItemsCount — Obtém contagem de linhas afetadas
- Result::getAutoIncrementValue — Obtém valor de incremento automático
- Result::getGeneratedIds — Obtém os IDs gerados
- Result::getWarnings — Obtém alertas da última operação
- Result::getWarningsCount — Obtém contagem de alertas da última operação

# Classe RowResult

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

## Resumo da classe

class mysql_xdevapi\RowResult implements mysql_xdevapi\BaseResult, Traversable {
/* Métodos */
public function fetchAll(): array
public function fetchOne(): array
public function getColumnsCount(): int
public function getColumnNames(): array
public function getColumns(): array
public function getWarnings(): array
public function getWarningsCount(): int
}

# RowResult::__construct

(No version information available, might only be in Git)

RowResult::__construct — Construtor de RowResult

### Descrição

private function mysql_xdevapi\RowResult::__construct()

Representa o conjunto de resultados obtido a partir de consulta ao banco de dados.

### Parâmetros

Esta função não possui parâmetros.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\RowResult::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $row = $table->select('name', 'age')->where('age > 18')->execute()->fetchAll();

    print_r($row);

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 33
            )
    )

# RowResult::fetchAll

(No version information available, might only be in Git)

RowResult::fetchAll — Obtém todas as linhas do resultado

### Descrição

public function mysql_xdevapi\RowResult::fetchAll(): array

Busca todas as linhas do conjunto de resultados.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array numérico com todos os resultados da consulta; cada resultado é um array associativo. Um array vazio é retornado se nenhuma linha estiver presente.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\RowResult::fetchAll()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $row = $table->select('name', 'age')->execute()->fetchAll();

    print_r($row);

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 33
            )
    )

# RowResult::fetchOne

(No version information available, might only be in Git)

RowResult::fetchOne — Obtém linha do resultado

### Descrição

public function mysql_xdevapi\RowResult::fetchOne(): array

Busca um resultado do conjunto de resultados.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O resultado, como um array associativo ou `null` se nenhum resultado estiver presente.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\RowResult::fetchOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $row = $table->select('name', 'age')->where('age < 40')->execute()->fetchOne();

    print_r($row);

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [name] => Sam
        [age] => 33
    )

# RowResult::getColumnsCount

(No version information available, might only be in Git)

RowResult::getColumnsCount — Obtém a contagem de colunas

### Descrição

public function mysql_xdevapi\RowResult::getColumnsCount(): int

Recupera a contagem de colunas presentes no conjunto de resultados.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O número de colunas; 0 se não houver nenhuma.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.14 | Método renomeado de getColumnCount() para getColumnsCount().

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\RowResult::getColumnsCount()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE addressbook")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $sql = $session->sql("SELECT * from addressbook.names")->execute();

    echo $sql->getColumnsCount();

O exemplo acima produzirá algo semelhante a:

    2

# RowResult::getColumnNames

(No version information available, might only be in Git)

RowResult::getColumnNames — Obtém o nome de todas as colunas

### Descrição

public function mysql_xdevapi\RowResult::getColumnNames(): array

Recupera os nomes das colunas presentes no conjunto de resultados.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array numérico de nomes de colunas da tabela, ou um array vazio se o conjunto de resultados estiver vazio.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\RowResult::getColumnNames()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE addressbook")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $sql = $session->sql("SELECT * from addressbook.names")->execute();

    $colnames = $sql->getColumnNames();

    print_r($colnames);

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => name
        [1] => age
    )

# RowResult::getColumns

(No version information available, might only be in Git)

RowResult::getColumns — Obtém metadados de coluna

### Descrição

public function mysql_xdevapi\RowResult::getColumns(): array

Recupera metadados das colunas presentes no conjunto de resultados.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array de objetos FieldMetadata representando as colunas no resultado, ou um array vazio se o conjunto de resultados estiver vazio.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\RowResult::getColumns()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE addressbook")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $sql = $session->sql("SELECT * from addressbook.names")->execute();

    $cols = $sql->getColumns();

    print_r($cols);

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => mysql_xdevapi\FieldMetadata Object
            (
                [type] => 7
                [type_name] => BYTES
                [name] => name
                [original_name] => name
                [table] => names
                [original_table] => names
                [schema] => addressbook
                [catalog] => def
                [collation] => 255
                [fractional_digits] => 0
                [length] => 65535
                [flags] => 0
                [content_type] => 0
            )
        [1] => mysql_xdevapi\FieldMetadata Object
            (
                [type] => 1
                [type_name] => SINT
                [name] => age
                [original_name] => age
                [table] => names
                [original_table] => names
                [schema] => addressbook
                [catalog] => def
                [collation] => 0
                [fractional_digits] => 0
                [length] => 11
                [flags] => 0
                [content_type] => 0
            )
    )

# RowResult::getWarnings

(No version information available, might only be in Git)

RowResult::getWarnings — Obtém os alertas da última operação

### Descrição

public function mysql_xdevapi\RowResult::getWarnings(): array

Recupera os alertas da última operação de RowResult.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array de objetos Warning da última operação. Cada objeto define uma mensagem de erro (chave 'message'), um nível de erro (chave 'level') e um código de erro (chave 'code'). Um array vazio é retornado se nenhum erro estiver presente.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\RowResult::getWarnings()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();
    $warnings = $res->getWarnings();

    print_r($warnings);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
        [1] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
    )

# RowResult::getWarningsCount

(No version information available, might only be in Git)

RowResult::getWarningsCount — Obtém a contagem de alertas da última operação

### Descrição

public function mysql_xdevapi\RowResult::getWarningsCount(): int

Recupera o número de alertas da última operação de RowResult.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O número de alertas gerados pela última operação.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\RowResult::getWarningsCount()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS foo")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();

    echo $res->getWarningsCount();
    ?>

O exemplo acima produzirá algo semelhante a:

    2

## Índice

- RowResult::__construct — Construtor de RowResult
- RowResult::fetchAll — Obtém todas as linhas do resultado
- RowResult::fetchOne — Obtém linha do resultado
- RowResult::getColumnsCount — Obtém a contagem de colunas
- RowResult::getColumnNames — Obtém o nome de todas as colunas
- RowResult::getColumns — Obtém metadados de coluna
- RowResult::getWarnings — Obtém os alertas da última operação
- RowResult::getWarningsCount — Obtém a contagem de alertas da última operação

# Classe Schema

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

## Resumo da classe

class mysql_xdevapi\Schema implements mysql_xdevapi\DatabaseObject {
/* Propriedades */
public $name;
/* Métodos */
public function createCollection(string `$name`, string `$validate` = ?): mysql_xdevapi\Collection
public function dropCollection(string `$collection_name`): bool
public function existsInDatabase(): bool
public function getCollection(string `$name`): mysql_xdevapi\Collection
public function getCollectionAsTable(string `$name`): mysql_xdevapi\Table
public function getCollections(): array
public function getName(): string
public function getSession(): mysql_xdevapi\Session
public function getTable(string `$name`): mysql_xdevapi\Table
public function getTables(): array
}

## Propriedades

name

# Schema::__construct

(No version information available, might only be in Git)

Schema::__construct — Construtor de Schema

### Descrição

private function mysql_xdevapi\Schema::__construct()

O objeto Schema fornece acesso completo ao esquema (banco de dados).

### Parâmetros

Esta função não possui parâmetros.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Schema::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS food")->execute();
    $session->sql("CREATE DATABASE food")->execute();
    $session->sql("CREATE TABLE food.fruit(name text, rating text)")->execute();

    $schema = $session->getSchema("food");
    $schema->createCollection("trees");

    print_r($schema->gettables());
    print_r($schema->getcollections());

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [fruit] => mysql_xdevapi\Table Object
            (
                [name] => fruit
            )
    )
    Array
    (
        [trees] => mysql_xdevapi\Collection Object
            (
                [name] => trees
            )
    )

# Schema::createCollection

(No version information available, might only be in Git)

Schema::createCollection — Adiciona coleção ao esquema

### Descrição

public function mysql_xdevapi\Schema::createCollection(string `$name`, string `$validate` = ?): mysql_xdevapi\Collection

Cria uma coleção dentro do esquema.

### Parâmetros

`name`

  Nome da coleção.

`validate`

  Definição de validação, como um objeto JSON.

### Valor Retornado

O objeto Collection.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.20 | Adicionado o parâmetro opcional de validação.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Schema::createCollection()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS food")->execute();
    $session->sql("CREATE DATABASE food")->execute();
    $session->sql("CREATE TABLE food.fruit(name text, rating text)")->execute();

    $schema = $session->getSchema("food");
    $schema->createCollection("trees");

    print_r($schema->gettables());
    print_r($schema->getcollections());

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [fruit] => mysql_xdevapi\Table Object
            (
                [name] => fruit
            )
    )
    Array
    (
        [trees] => mysql_xdevapi\Collection Object
            (
                [name] => trees
            )
    )

Exemplo #2 Exemplo de mysql_xdevapi\Schema::createCollection()

    <?php
     $collection = $schema->createCollection("minha_coleção", '{
        "validation": {
            "level": "strict",
            "schema": {
                "id": "http://json-schema.org/geo",
                "description": "Uma coordenada geográfica",
                "type": "object",
                "properties": {
                    "latitude": {
                        "type": "number"
                    },
                    "longitude": {
                        "type": "number"
                    }
                },
                "required": ["latitude", "longitude"]
            }
        }
    }');
    // Irá funcionar
    $collection->add('{"latitude": 10, "longitude": 20}')->execute();

    // Irá falhar, tipos inválidos (não são números)
    $collection->add('{"latitude": "lat", "longitude": "long"}')->execute();

# Schema::dropCollection

(No version information available, might only be in Git)

Schema::dropCollection — Remove coleção do esquema

### Descrição

public function mysql_xdevapi\Schema::dropCollection(string `$collection_name`): bool

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`collection_name`

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Schema::dropCollection()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS food")->execute();
    $session->sql("CREATE DATABASE food")->execute();
    $session->sql("CREATE TABLE food.fruit(name text, rating text)")->execute();

    $schema = $session->getSchema("food");

    $schema->createCollection("trees");
    $schema->dropCollection("trees");
    $schema->createCollection("buildings");

    print_r($schema->gettables());
    print_r($schema->getcollections());

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [fruit] => mysql_xdevapi\Table Object
            (
                [name] => fruit
            )
    )
    Array
    (
        [buildings] => mysql_xdevapi\Collection Object
            (
                [name] => buildings
            )
    )

# Schema::existsInDatabase

(No version information available, might only be in Git)

Schema::existsInDatabase — Verifica se existe no banco de dados

### Descrição

public function mysql_xdevapi\Schema::existsInDatabase(): bool

Verifica se o objeto atual (esquema, tabela, coleção ou visualização) existe no objeto Schema.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

`true` se o esquema, tabela, coleção ou visualização ainda existirem no banco de dados, senão `false`.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Schema::existsInDatabase()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS food")->execute();
    $session->sql("CREATE DATABASE food")->execute();
    $session->sql("CREATE TABLE food.fruit(name text, rating text)")->execute();

    $schema = $session->getSchema("food");
    $schema->createCollection("trees");

    // ...

    $trees = $schema->getCollection("trees");

    // ...

    // Esta coleção ainda existe no banco de dados (esquema)?
    if ($trees->existsInDatabase()) {
        echo "Sim, a coleção 'trees' ainda está presente.";
    }

O exemplo acima produzirá algo semelhante a:

    Sim, a coleção 'trees' ainda está presente.

# Schema::getCollection

(No version information available, might only be in Git)

Schema::getCollection — Obtém coleção do esquema

### Descrição

public function mysql_xdevapi\Schema::getCollection(string `$name`): mysql_xdevapi\Collection

Obtém uma coleção do esquema.

### Parâmetros

`name`

  Nome da coleção a ser obtida.

### Valor Retornado

O objeto Collection para a coleção selecionada.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Schema::getCollection()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS food")->execute();
    $session->sql("CREATE DATABASE food")->execute();

    $schema = $session->getSchema("food");
    $schema->createCollection("trees");

    // ...

    $trees = $schema->getCollection("trees");

    var_dump($trees);

O exemplo acima produzirá algo semelhante a:

    object(mysql_xdevapi\Collection)#3 (1) {
      ["name"]=>
      string(5) "trees"
    }

# Schema::getCollectionAsTable

(No version information available, might only be in Git)

Schema::getCollectionAsTable — Obtém uma coleção como um objeto Table

### Descrição

public function mysql_xdevapi\Schema::getCollectionAsTable(string `$name`): mysql_xdevapi\Table

Obtém uma coleção, porém como objeto Table ao invés de objeto Collection.

### Parâmetros

`name`

  Nome da coleção a ser instanciada como objeto Table.

### Valor Retornado

Um objeto mysql_xdevapi\Table para a coleção.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Schema::getCollectionAsTable()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema  = $session->getSchema("addressbook");
    $collect = $schema->createCollection("people");
    $collect->add('{"name": "Fred",  "age": 21, "job": "Construction"}')->execute();
    $collect->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

    $table      = $schema->getCollectionAsTable("people");
    $collection = $schema->getCollection("people");

    var_dump($table);
    var_dump($collection);

O exemplo acima produzirá algo semelhante a:

    object(mysql_xdevapi\Table)#4 (1) {
      ["name"]=>
      string(6) "people"
    }

    object(mysql_xdevapi\Collection)#5 (1) {
      ["name"]=>
      string(6) "people"
    }

# Schema::getCollections

(No version information available, might only be in Git)

Schema::getCollections — Obtém todas as coleções do esquema

### Descrição

public function mysql_xdevapi\Schema::getCollections(): array

Busca uma lista de coleções deste esquema.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Array de todas as coleções neste esquema, onde cada elemento tem o valor de um objeto Collection com o nome da coleção como chave.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Schema::getCollections()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema  = $session->getSchema("addressbook");
    $collect = $schema->createCollection("people");
    $collect->add('{"name": "Fred",  "age": 21, "job": "Construction"}')->execute();
    $collect->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

    $collections = $schema->getCollections();
    var_dump($collections);
    ?>

O exemplo acima produzirá algo semelhante a:

    array(1) {
      ["people"]=>
      object(mysql_xdevapi\Collection)#4 (1) {
        ["name"]=>
        string(6) "people"
      }
    }

# Schema::getName

(No version information available, might only be in Git)

Schema::getName — Obtém o nome do esquema

### Descrição

public function mysql_xdevapi\Schema::getName(): string

Obtém o nome do esquema.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O nome do esquema conectado ao objeto Schema, como uma string.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Schema::getName()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema  = $session->getSchema("addressbook");

    // ...

    var_dump($schema->getName());
    ?>

O exemplo acima produzirá algo semelhante a:

    string(11) "addressbook"

# Schema::getSession

(No version information available, might only be in Git)

Schema::getSession — Obtém a sessão do esquema

### Descrição

public function mysql_xdevapi\Schema::getSession(): mysql_xdevapi\Session

Obtém um novo objeto Session a partir do objeto Schema.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um objeto Session.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Schema::getSession()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema  = $session->getSchema("addressbook");

    // ...

    $newsession = $schema->getSession();

    var_dump($session);
    var_dump($newsession);
    ?>

O exemplo acima produzirá algo semelhante a:

    object(mysql_xdevapi\Session)#1 (0) {
    }

    object(mysql_xdevapi\Session)#3 (0) {
    }

# Schema::getTable

(No version information available, might only be in Git)

Schema::getTable — Obtém tabela do esquema

### Descrição

public function mysql_xdevapi\Schema::getTable(string `$name`): mysql_xdevapi\Table

Busca um objeto Table para a tabela informada do esquema.

### Parâmetros

`name`

  Nome da tabela.

### Valor Retornado

Um objeto Table.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Schema::getTable()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $row = $table->select('name', 'age')->execute()->fetchAll();

    print_r($row);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 33
            )
    )

# Schema::getTables

(No version information available, might only be in Git)

Schema::getTables — Obtém tabelas do esquema

### Descrição

public function mysql_xdevapi\Schema::getTables(): array

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Array de todas as tabelas do esquema, onde cada elemento tem um objeto Table como valor e o nome da tabela como chave.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Schema::getTables()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $session->sql("CREATE TABLE addressbook.cities(name text, population int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('Portland', 639863), ('Seattle', 704352)")->execute();

    $schema = $session->getSchema("addressbook");
    $tables = $schema->getTables();

    var_dump($tables);
    ?>

O exemplo acima produzirá algo semelhante a:

    array(2) {
      ["cities"]=>
      object(mysql_xdevapi\Table)#3 (1) {
        ["name"]=>
        string(6) "cities"
      }

      ["names"]=>
      object(mysql_xdevapi\Table)#4 (1) {
        ["name"]=>
        string(5) "names"
      }
    }

## Índice

- Schema::__construct — Construtor de Schema
- Schema::createCollection — Adiciona coleção ao esquema
- Schema::dropCollection — Remove coleção do esquema
- Schema::existsInDatabase — Verifica se existe no banco de dados
- Schema::getCollection — Obtém coleção do esquema
- Schema::getCollectionAsTable — Obtém uma coleção como um objeto Table
- Schema::getCollections — Obtém todas as coleções do esquema
- Schema::getName — Obtém o nome do esquema
- Schema::getSession — Obtém a sessão do esquema
- Schema::getTable — Obtém tabela do esquema
- Schema::getTables — Obtém tabelas do esquema

# Interface SchemaObject

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

## Resumo da classe

class mysql_xdevapi\SchemaObject implements mysql_xdevapi\DatabaseObject {
/* Métodos */
abstract function getSchema(): mysql_xdevapi\Schema
}

# SchemaObject::getSchema

(No version information available, might only be in Git)

SchemaObject::getSchema — Obtém o objeto do esquema

### Descrição

abstract function mysql_xdevapi\SchemaObject::getSchema(): mysql_xdevapi\Schema

Usado por outros objetos para recuperar um objeto de esquema.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O objeto Schema atual.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Session::getSchema()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $schema  = $session->getSchema("addressbook");

    print_r($schema);

O exemplo acima produzirá algo semelhante a:

    mysql_xdevapi\Schema Object
    (
        [name] => addressbook
    )

## Índice

- SchemaObject::getSchema — Obtém o objeto do esquema

# Classe Session

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

## Resumo da classe

class mysql_xdevapi\Session {
/* Métodos */
public function close(): bool
public function commit(): Object
public function createSchema(string `$schema_name`): mysql_xdevapi\Schema
public function dropSchema(string `$schema_name`): bool
public function generateUUID(): string
public function getDefaultSchema(): ?mysql_xdevapi\Schema
public function getSchema(string `$schema_name`): mysql_xdevapi\Schema
public function getSchemas(): array
public function getServerVersion(): int
public function listClients(): array
public function quoteName(string `$name`): string
public function releaseSavepoint(string `$name`): void
public function rollback(): void
public function rollbackTo(string `$name`): void
public function setSavepoint(string `$name` = ?): string
public function sql(string `$query`): mysql_xdevapi\SqlStatement
public function startTransaction(): void
}

# Session::close

(No version information available, might only be in Git)

Session::close — Fecha sessão

### Descrição

public function mysql_xdevapi\Session::close(): bool

Fecha a sessão com o servidor.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

`true` se a sessão for fechada.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Session::close()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $session->close();

# Session::commit

(PHP 4 >= 4.4.0, PHP 5, PHP 7, PHP 8)

Session::commit — Confirma a transação

### Descrição

public function mysql_xdevapi\Session::commit(): Object

Confirma a transação.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um objeto SqlStatementResult.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Session::commit()

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("friends");

    $session->startTransaction();

    $collection->add('{"John":42, "Sam":33}')->execute();
    $savepoint = $session->setSavepoint();

    $session->commit();
    $session->close();

# Session::__construct

(No version information available, might only be in Git)

Session::__construct — Construtor de Description

### Descrição

private function mysql_xdevapi\Session::__construct()

Um objeto Session, iniciado por getSession().

### Parâmetros

Esta função não possui parâmetros.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Session::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->close();
    ?>

# Session::createSchema

(No version information available, might only be in Git)

Session::createSchema — Cria novo esquema

### Descrição

public function mysql_xdevapi\Session::createSchema(string `$schema_name`): mysql_xdevapi\Schema

Cria um novo esquema.

### Parâmetros

`schema_name`

  Nome do esquema a ser criado.

### Valor Retornado

Um objeto Schema em caso de sucesso e emite uma exceção em caso de falha.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Session::createSchema()

    <?php
    $uri  = 'mysqlx://happyuser:password@127.0.0.1:33060/';
    $sess = mysql_xdevapi\getSession($uri);

    try {

        if ($schema = $sess->createSchema('fruit')) {
            echo "Info: Eu criei um esquema de nome 'fruit'\n";
        }

    } catch (Exception $e) {

       echo $e->getMessage();

    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Info: Eu criei um esquema de nome 'fruit'

# Session::dropSchema

(No version information available, might only be in Git)

Session::dropSchema — Remove um esquema

### Descrição

public function mysql_xdevapi\Session::dropSchema(string `$schema_name`): bool

Remove um esquema (banco de dados).

### Parâmetros

`schema_name`

  Nome do esquema a remover.

### Valor Retornado

`true` se o esquema for removido ou `false` se ele não exisitir ou não puder ser removido.

Um erro de nível `E_WARNING` é gerado se o esquema não existir.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Session::dropSchema()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->dropSchema("addressbook");

    $session->close();
    ?>

# Session::generateUUID

(No version information available, might only be in Git)

Session::generateUUID — Obtém novo UUID

### Descrição

public function mysql_xdevapi\Session::generateUUID(): string

Gera um Identificador Único Universal (UUID) de acordo com a » RFC 4122.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O UUID; uma string com comprimento de 32 bytes.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Session::generateUuid()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $uuid = $session->generateUuid();

    var_dump($uuid);

O exemplo acima produzirá algo semelhante a:

    string(32) "484B18AC7980F8D4FE84613CDA5EE84B"

# Session::getDefaultSchema

(No version information available, might only be in Git)

Session::getDefaultSchema — Obtém o nome de esquema padrão

### Descrição

public function mysql_xdevapi\Session::getDefaultSchema(): ?mysql_xdevapi\Schema

Recupera o esquema padrão que é tipicamente definido na URI de conexão.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Esquema padrão definido pela conexão ou `null` se nenhum foi definido.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Session::getSchema()

    <?php
    $uri = "mysqlx://testuser:testpasswd@localhost:33160/testx?ssl-mode=disabled";
    $session = mysql_xdevapi\getSession($uri);

    $schema = $session->getDefaultSchema();
    echo $schema->getName();
    ?>

O exemplo acima produzirá:

    testx

# Session::getSchema

(No version information available, might only be in Git)

Session::getSchema — Obtém um novo objeto de esquema

### Descrição

public function mysql_xdevapi\Session::getSchema(string `$schema_name`): mysql_xdevapi\Schema

Um novo objeto Schema para o nome de esquema informado.

### Parâmetros

`schema_name`

  Nome do esquema (banco de dados) para buscar um objeto Schema.

### Valor Retornado

Um objeto Schema.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Session::getSchema()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $schema  = $session->getSchema("addressbook");

    print_r($schema);

O exemplo acima produzirá algo semelhante a:

    mysql_xdevapi\Schema Object
    (
        [name] => addressbook
    )

# Session::getSchemas

(No version information available, might only be in Git)

Session::getSchemas — Obtém os esquemas

### Descrição

public function mysql_xdevapi\Session::getSchemas(): array

Obtém os objetos de esquema para todos os esquemas disponíveis para a sessão.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array contendo objetos que representam todos os esquemas disponíveis para a sessão.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Session::getSchemas()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $schemas  = $session->getSchemas();

    print_r($schemas);

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => mysql_xdevapi\Schema Object
            (
                [name] => addressbook
            )
        [1] => mysql_xdevapi\Schema Object
            (
                [name] => information_schema
            )
        ...

# Session::getServerVersion

(No version information available, might only be in Git)

Session::getServerVersion — Obtém a versão do servidor

### Descrição

public function mysql_xdevapi\Session::getServerVersion(): int

Recupera a versão do servidor MySQL para a sessão.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

A versão do servidor MySQL para a sessão, como um inteiro tipo "80012".

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Session::getServerVersion()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $version = $session->getServerVersion();

    var_dump($version);

O exemplo acima produzirá algo semelhante a:

    int(80012)

# Session::listClients

(No version information available, might only be in Git)

Session::listClients — Obtém a lista de clientes

### Descrição

public function mysql_xdevapi\Session::listClients(): array

Obtém uma lista de conexões de clientes ao servidor MySQL da sessão.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array contendo os clientes atualmente registrados. Os elementos do array são "client_id", "user", "host", e "sql_session".

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Session::listClients()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $ids = $session->listClients();

    var_dump($ids);
    ?>

O exemplo acima produzirá algo semelhante a:

    array(1) {
      [0]=>
      array(4) {
        ["client_id"]=>
        int(61)
        ["user"]=>
        string(4) "root"
        ["host"]=>
        string(9) "localhost"
        ["sql_session"]=>
        int(72)
      }
    }

# Session::quoteName

(No version information available, might only be in Git)

Session::quoteName — Adiciona escape

### Descrição

public function mysql_xdevapi\Session::quoteName(string `$name`): string

Uma função para escapar nomes e identificadores SQL. Escapa o identificador fornecido de acordo com as configurações da conexão atual. Esta função de escape não deve ser usada para escapar valores.

### Parâmetros

`name`

  A string a ser escapada.

### Valor Retornado

A string escapada.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Session::quoteName()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $first = "MySQL's test";
    var_dump($first);
    var_dump($session->quoteName($first));

    $second = 'Another `test` "like" `this`';
    var_dump($second);
    var_dump($session->quoteName($second));
    ?>

O exemplo acima produzirá algo semelhante a:

    string(12) "MySQL's test"
    string(14) "`MySQL's test`"

    string(28) "Another `test` "like" `this`"
    string(34) "`Another ``test`` "like" ``this```"

# Session::releaseSavepoint

(No version information available, might only be in Git)

Session::releaseSavepoint — Libera o ponto de gravação definido

### Descrição

public function mysql_xdevapi\Session::releaseSavepoint(string `$name`): void

Libera um ponto de gravação previamente definido.

### Parâmetros

`name`

  Nome do ponto de gravação a liberar.

### Valor Retornado

Um objeto SqlStatementResult.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Session::releaseSavepoint()

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("friends");

    $session->startTransaction();
    $collection->add( '{"test1":1, "test2":2}' )->execute();

    $savepoint = $session->setSavepoint();

    $collection->add( '{"test3":3, "test4":4}' )->execute();

    $session->releaseSavepoint($savepoint);
    $session->rollback();
    ?>

# Session::rollback

(No version information available, might only be in Git)

Session::rollback — Reverte a transação

### Descrição

public function mysql_xdevapi\Session::rollback(): void

Reverte a transação.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um objeto SqlStatementResult.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Session::rollback()

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("names");

    $session->startTransaction();
    $collection->add( '{"test1":1, "test2":2}' )->execute();

    $savepoint = $session->setSavepoint();

    $collection->add( '{"test3":3, "test4":4}' )->execute();

    $session->releaseSavepoint($savepoint);
    $session->rollback();
    ?>

# Session::rollbackTo

(No version information available, might only be in Git)

Session::rollbackTo — Reverte a transação para um ponto de gravação

### Descrição

public function mysql_xdevapi\Session::rollbackTo(string `$name`): void

Reverte a transação para o ponto de gravação.

### Parâmetros

`name`

  Nome do ponto de gravação para o qual a reversão ocorrerá; insensível a maiúsculas/minúsculas.

### Valor Retornado

Um objeto SqlStatementResult.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Session::rollbackTo()

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("names");

    $session->startTransaction();
    $collection->add( '{"test1":1, "test2":2}' )->execute();

    $savepoint1 = $session->setSavepoint();

    $collection->add( '{"test3":3, "test4":4}' )->execute();

    $savepoint2 = $session->setSavepoint();

    $session->rollbackTo($savepoint1);
    ?>

# Session::setSavepoint

(No version information available, might only be in Git)

Session::setSavepoint — Cria ponto de gravação

### Descrição

public function mysql_xdevapi\Session::setSavepoint(string `$name` = ?): string

Cria um novo ponto de gravação para a transação.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`name`

  O nome do ponto de gravação. O nome é gerado automaticamente se o parâmetro `name` opcional não for definido, como 'SAVEPOINT1', 'SAVEPOINT2' e assim por diante.

### Valor Retornado

O nome do ponto de gravação.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Session::setSavepoint()

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("names");

    $session->startTransaction();
    $collection->add( '{"test1":1, "test2":2}' )->execute();

    $savepoint = $session->setSavepoint();

    $collection->add( '{"test3":3, "test4":4}' )->execute();

    $session->releaseSavepoint($savepoint);
    $session->rollback();
    ?>

# Session::sql

(No version information available, might only be in Git)

Session::sql — Cria consulta SQL

### Descrição

public function mysql_xdevapi\Session::sql(string `$query`): mysql_xdevapi\SqlStatement

Cria uma instrução SQL nativa. Marcadores são suportados usando a sintaxe nativa "?". Use o método `execute` para executar a instrução SQL.

### Parâmetros

`query`

  Instrução SQL a executar.

### Valor Retornado

Um objeto SqlStatement.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Session::sql()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("CREATE DATABASE addressbook")->execute();
    ?>

# Session::startTransaction

(No version information available, might only be in Git)

Session::startTransaction — Inicia transação

### Descrição

public function mysql_xdevapi\Session::startTransaction(): void

Inicia uma nova transação.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um objeto SqlStatementResult.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Session::startTransaction()

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("friends");

    $session->startTransaction();
    $collection->add( '{"test1":1, "test2":2}' )->execute();

    $savepoint = $session->setSavepoint();

    $collection->add( '{"test3":3, "test4":4}' )->execute();

    $session->releaseSavepoint($savepoint);
    $session->rollback();
    ?>

## Índice

- Session::close — Fecha sessão
- Session::commit — Confirma a transação
- Session::__construct — Construtor de Description
- Session::createSchema — Cria novo esquema
- Session::dropSchema — Remove um esquema
- Session::generateUUID — Obtém novo UUID
- Session::getDefaultSchema — Obtém o nome de esquema padrão
- Session::getSchema — Obtém um novo objeto de esquema
- Session::getSchemas — Obtém os esquemas
- Session::getServerVersion — Obtém a versão do servidor
- Session::listClients — Obtém a lista de clientes
- Session::quoteName — Adiciona escape
- Session::releaseSavepoint — Libera o ponto de gravação definido
- Session::rollback — Reverte a transação
- Session::rollbackTo — Reverte a transação para um ponto de gravação
- Session::setSavepoint — Cria ponto de gravação
- Session::sql — Cria consulta SQL
- Session::startTransaction — Inicia transação

# Classe SqlStatement

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

## Resumo da classe

class mysql_xdevapi\SqlStatement {
/* Constantes */
const int EXECUTE_ASYNC = 1;
const int BUFFERED = 2;
/* Propriedades */
public $statement;
/* Métodos */
public function bind(string `$param`): mysql_xdevapi\SqlStatement
public function execute(): mysql_xdevapi\Result
public function getNextResult(): mysql_xdevapi\Result
public function getResult(): mysql_xdevapi\Result
public function hasMoreResults(): bool
}

## Propriedades

statement

## Constantes predefinidas

`mysql_xdevapi\SqlStatement::EXECUTE_ASYNC`

`mysql_xdevapi\SqlStatement::BUFFERED`

# SqlStatement::bind

(No version information available, might only be in Git)

SqlStatement::bind — Vincula parâmetros da instrução

### Descrição

public function mysql_xdevapi\SqlStatement::bind(string `$param`): mysql_xdevapi\SqlStatement

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`param`

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\SqlStatement::bind()

    <?php

    /* ... */

    ?>

# SqlStatement::__construct

(No version information available, might only be in Git)

SqlStatement::__construct — Construtor de Description

### Descrição

private function mysql_xdevapi\SqlStatement::__construct()

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\SqlStatement::__construct()

    <?php

    /* ... */

    ?>

# SqlStatement::execute

(No version information available, might only be in Git)

SqlStatement::execute — Executa a operação

### Descrição

public function mysql_xdevapi\SqlStatement::execute(): mysql_xdevapi\Result

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\SqlStatement::execute()

    <?php

    /* ... */

    ?>

# SqlStatement::getNextResult

(No version information available, might only be in Git)

SqlStatement::getNextResult — Obtém o próximo resultado

### Descrição

public function mysql_xdevapi\SqlStatement::getNextResult(): mysql_xdevapi\Result

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\SqlStatement::getNextResult()

    <?php

    /* ... */

    ?>

# SqlStatement::getResult

(No version information available, might only be in Git)

SqlStatement::getResult — Obtém resultado

### Descrição

public function mysql_xdevapi\SqlStatement::getResult(): mysql_xdevapi\Result

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\SqlStatement::getResult()

    <?php

    /* ... */

    ?>

# SqlStatement::hasMoreResults

(No version information available, might only be in Git)

SqlStatement::hasMoreResults — Verifica por mais resultados

### Descrição

public function mysql_xdevapi\SqlStatement::hasMoreResults(): bool

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

`true` se o conjunto de resultados tiver mais objetos a serem buscados.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\SqlStatement::hasMoreResults()

    <?php

    /* ... */

    ?>

## Índice

- SqlStatement::bind — Vincula parâmetros da instrução
- SqlStatement::__construct — Construtor de Description
- SqlStatement::execute — Executa a operação
- SqlStatement::getNextResult — Obtém o próximo resultado
- SqlStatement::getResult — Obtém resultado
- SqlStatement::hasMoreResults — Verifica por mais resultados

# Classe SqlStatementResult

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

## Resumo da classe

class mysql_xdevapi\SqlStatementResult implements mysql_xdevapi\BaseResult, Traversable {
/* Métodos */
public function fetchAll(): array
public function fetchOne(): array
public function getAffectedItemsCount(): int
public function getColumnsCount(): int
public function getColumnNames(): array
public function getColumns(): Array
public function getGeneratedIds(): array
public function getLastInsertId(): String
public function getWarnings(): array
public function getWarningCounts(): int
public function hasData(): bool
public function nextResult(): mysql_xdevapi\Result
}

# SqlStatementResult::__construct

(No version information available, might only be in Git)

SqlStatementResult::__construct — Construtor de SqlStatementResult

### Descrição

private function mysql_xdevapi\SqlStatementResult::__construct()

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\SqlStatementResult::__construct()

    <?php

    /* ... */

    ?>

# SqlStatementResult::fetchAll

(No version information available, might only be in Git)

SqlStatementResult::fetchAll — Obtém todas as linhas do resultado

### Descrição

public function mysql_xdevapi\SqlStatementResult::fetchAll(): array

Busca todas as linhas do conjunto de resultados.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array numérico com todos os resultados da consulta; cada resultado é um array associativo. Um array vazio é retornado se nenhuma linha estiver presente.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\SqlStatementResult::fetchAll()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS dbtest")->execute();
    $session->sql("CREATE DATABASE dbtest")->execute();
    $session->sql("CREATE TABLE dbtest.workers(name text, age int, job text)")->execute();
    $session->sql("INSERT INTO dbtest.workers values ('John', 42, 'bricklayer'), ('Sam', 33, 'carpenter')")->execute();

    $schema = $session->getSchema("dbtest");
    $table  = $schema->getTable("workers");

    $rows = $session->sql("SELECT * FROM dbtest.workers")->execute()->fetchAll();

    print_r($rows);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 33
            )
    )

# SqlStatementResult::fetchOne

(No version information available, might only be in Git)

SqlStatementResult::fetchOne — Obtém uma única linha

### Descrição

public function mysql_xdevapi\SqlStatementResult::fetchOne(): array

Busca uma linha do conjunto de resultados.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O resultado, como um array associativo. Caso não haja resultado, será retornado null.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\SqlStatementResult::fetchOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS dbtest")->execute();
    $session->sql("CREATE DATABASE dbtest")->execute();
    $session->sql("CREATE TABLE dbtest.workers(name text, age int, job text)")->execute();
    $session->sql("INSERT INTO dbtest.workers values ('John', 42, 'bricklayer'), ('Sam', 33, 'carpenter')")->execute();

    $schema = $session->getSchema("dbtest");
    $table  = $schema->getTable("workers");

    $rows = $session->sql("SELECT * FROM dbtest.workers")->execute()->fetchOne();

    print_r($rows);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [name] => John
        [age] => 42
        [job] => bricklayer
    )

# SqlStatementResult::getAffectedItemsCount

(No version information available, might only be in Git)

SqlStatementResult::getAffectedItemsCount — Obtém a contagem de linhas afetadas

### Descrição

public function mysql_xdevapi\SqlStatementResult::getAffectedItemsCount(): int

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\SqlStatementResult::getAffectedItemsCount()

    <?php

    /* ... */

    ?>

# SqlStatementResult::getColumnsCount

(No version information available, might only be in Git)

SqlStatementResult::getColumnsCount — Obtém a contagem de colunas

### Descrição

public function mysql_xdevapi\SqlStatementResult::getColumnsCount(): int

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O número de colunas; 0 se não houver nenhuma.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.14 | Método renomeado de getColumnCount() para getColumnsCount().

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\SqlStatementResult::getColumnsCount()

    <?php

    /* ... */

    ?>

# SqlStatementResult::getColumnNames

(No version information available, might only be in Git)

SqlStatementResult::getColumnNames — Obtém nomes de colunas

### Descrição

public function mysql_xdevapi\SqlStatementResult::getColumnNames(): array

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\SqlStatementResult::getColumnNames()

    <?php

    /* ... */

    ?>

# SqlStatementResult::getColumns

(No version information available, might only be in Git)

SqlStatementResult::getColumns — Obtém colunas

### Descrição

public function mysql_xdevapi\SqlStatementResult::getColumns(): Array

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\SqlStatementResult::getColumns()

    <?php

    /* ... */

    ?>

# SqlStatementResult::getGeneratedIds

(No version information available, might only be in Git)

SqlStatementResult::getGeneratedIds — Obtém IDs gerados

### Descrição

public function mysql_xdevapi\SqlStatementResult::getGeneratedIds(): array

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array de IDs gerados na última operação, ou um array vazio se não houver nenhum.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\SqlStatementResult::getGeneratedIds()

    <?php

    /* ... */

    ?>

# SqlStatementResult::getLastInsertId

(No version information available, might only be in Git)

SqlStatementResult::getLastInsertId — Obtém o ID da última inserção

### Descrição

public function mysql_xdevapi\SqlStatementResult::getLastInsertId(): String

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O ID para a última operação de inserção.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\SqlStatementResult::getLastInsertId()

    <?php

    /* ... */

    ?>

# SqlStatementResult::getWarnings

(No version information available, might only be in Git)

SqlStatementResult::getWarnings — Obtém alertas da última operação

### Descrição

public function mysql_xdevapi\SqlStatementResult::getWarnings(): array

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array de objetos Warning da última operação. Cada objeto define uma mensagem de erro ('message'), nível de erro ('level') e código de erro ('code'). Um array vazio é retornado se nenhum erro estiver presente.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\SqlStatementResult::getWarnings()

    <?php

    /* ... */

    ?>

# SqlStatementResult::getWarningsCount

(No version information available, might only be in Git)

SqlStatementResult::getWarningsCount — Obtém contagem de alertas da última operação

### Descrição

public function mysql_xdevapi\SqlStatementResult::getWarningCounts(): int

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O número de alertas emitidos durante a última operação CRUD.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\SqlStatementResult::getWarningsCount()

    <?php

    /* ... */

    ?>

# SqlStatementResult::hasData

(No version information available, might only be in Git)

SqlStatementResult::hasData — Verifica se o resultado tem dados

### Descrição

public function mysql_xdevapi\SqlStatementResult::hasData(): bool

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

`true` se o conjunto de resultado tiver dados.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\SqlStatementResult::hasData()

    <?php

    /* ... */

    ?>

# SqlStatementResult::nextResult

(No version information available, might only be in Git)

SqlStatementResult::nextResult — Obtém o próximo resultado

### Descrição

public function mysql_xdevapi\SqlStatementResult::nextResult(): mysql_xdevapi\Result

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O próximo objeto Result da conjunto de resultados.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\SqlStatementResult::nextResult()

    <?php

    /* ... */

    ?>

## Índice

- SqlStatementResult::__construct — Construtor de SqlStatementResult
- SqlStatementResult::fetchAll — Obtém todas as linhas do resultado
- SqlStatementResult::fetchOne — Obtém uma única linha
- SqlStatementResult::getAffectedItemsCount — Obtém a contagem de linhas afetadas
- SqlStatementResult::getColumnsCount — Obtém a contagem de colunas
- SqlStatementResult::getColumnNames — Obtém nomes de colunas
- SqlStatementResult::getColumns — Obtém colunas
- SqlStatementResult::getGeneratedIds — Obtém IDs gerados
- SqlStatementResult::getLastInsertId — Obtém o ID da última inserção
- SqlStatementResult::getWarnings — Obtém alertas da última operação
- SqlStatementResult::getWarningsCount — Obtém contagem de alertas da última operação
- SqlStatementResult::hasData — Verifica se o resultado tem dados
- SqlStatementResult::nextResult — Obtém o próximo resultado

# Classe Statement

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

## Resumo da classe

class mysql_xdevapi\Statement {
/* Constantes */
const int EXECUTE_ASYNC = 1;
const int BUFFERED = 2;
/* Métodos */
public function getNextResult(): mysql_xdevapi\Result
public function getResult(): mysql_xdevapi\Result
public function hasMoreResults(): bool
}

## Constantes predefinidas

`mysql_xdevapi\Statement::EXECUTE_ASYNC`

`mysql_xdevapi\Statement::BUFFERED`

# Statement::__construct

(No version information available, might only be in Git)

Statement::__construct — Construtor de Statement

### Descrição

private function mysql_xdevapi\Statement::__construct()

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Statement::__construct()

    <?php

    /* ... */

    ?>

# Statement::getNextResult

(No version information available, might only be in Git)

Statement::getNextResult — Obtém o próximo resultado

### Descrição

public function mysql_xdevapi\Statement::getNextResult(): mysql_xdevapi\Result

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Statement::getNextResult()

    <?php

    /* ... */

    ?>

# Statement::getResult

(No version information available, might only be in Git)

Statement::getResult — Obtém resultado

### Descrição

public function mysql_xdevapi\Statement::getResult(): mysql_xdevapi\Result

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Statement::getResult()

    <?php

    /* ... */

    ?>

# Statement::hasMoreResults

(No version information available, might only be in Git)

Statement::hasMoreResults — Verifica se há mais resultados

### Descrição

public function mysql_xdevapi\Statement::hasMoreResults(): bool

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Statement::hasMoreResults()

    <?php

    /* ... */

    ?>

## Índice

- Statement::__construct — Construtor de Statement
- Statement::getNextResult — Obtém o próximo resultado
- Statement::getResult — Obtém resultado
- Statement::hasMoreResults — Verifica se há mais resultados

# Classe Table

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

Fornece acesso à tabela através das instruções INSERT/SELECT/UPDATE/DELETE.

## Resumo da classe

class mysql_xdevapi\Table implements mysql_xdevapi\SchemaObject {
/* Propriedades */
public $name;
/* Métodos */
public function count(): int
public function delete(): mysql_xdevapi\TableDelete
public function existsInDatabase(): bool
public function getName(): string
public function getSchema(): mysql_xdevapi\Schema
public function getSession(): mysql_xdevapi\Session
public function insert(mixed `$columns`, mixed `...$more_columns`): mysql_xdevapi\TableInsert
public function isView(): bool
public function select(mixed `$columns`, mixed `...$more_columns`): mysql_xdevapi\TableSelect
public function update(): mysql_xdevapi\TableUpdate
}

## Propriedades

name

# Table::__construct

(No version information available, might only be in Git)

Table::__construct — Construtor de Table

### Descrição

private function mysql_xdevapi\Table::__construct()

Constrói um objeto de tabela.

### Parâmetros

Esta função não possui parâmetros.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Table::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");
    ?>

# Table::count

(No version information available, might only be in Git)

Table::count — Obtém contagem de linhas

### Descrição

public function mysql_xdevapi\Table::count(): int

Busca o número de linhas na tabela.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O número total de linhas na tabela.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Table::count()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    var_dump($table->count());
    ?>

O exemplo acima produzirá:

    int(2)

# Table::delete

(No version information available, might only be in Git)

Table::delete — Deleta linhas da tabela

### Descrição

public function mysql_xdevapi\Table::delete(): mysql_xdevapi\TableDelete

Deleta linhas da tabela.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um objeto TableDelete; use o método execute() para executar a instrução de deleção.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Table::delete()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()->where("name = :name")->orderby("age DESC")->limit(1)->bind(['name' => 'John'])->execute();
    ?>

# Table::existsInDatabase

(No version information available, might only be in Git)

Table::existsInDatabase — Verifica se uma tabela existe no banco de dados

### Descrição

public function mysql_xdevapi\Table::existsInDatabase(): bool

Verifica se esta tabela existe no banco de dados.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se a tabela existir no banco de dados, ou `false` se não existir.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Table::existsInDatabase()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    if ($table->existsInDatabase()) {
      echo "Sim, esta tabela ainda existe no esquema da sessão.";
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Sim, esta tabela ainda existe no esquema da sessão.

# Table::getName

(No version information available, might only be in Git)

Table::getName — Obtém nome da tabela

### Descrição

public function mysql_xdevapi\Table::getName(): string

Retorna o nome deste objeto de banco de dados.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O nome deste objeto de banco de dados.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Table::getName()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    var_dump($table->getName());
    ?>

O exemplo acima produzirá algo semelhante a:

    string(5) "names"

# Table::getSchema

(No version information available, might only be in Git)

Table::getSchema — Obtém esquema da tabela

### Descrição

public function mysql_xdevapi\Table::getSchema(): mysql_xdevapi\Schema

Busca o esquema associado com a tabela.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um objeto Schema.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Table::getSchema()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    var_dump($table->getSchema());
    ?>

O exemplo acima produzirá algo semelhante a:

    object(mysql_xdevapi\Schema)#9 (1) {
      ["name"]=>
      string(11) "addressbook"
    }

# Table::getSession

(No version information available, might only be in Git)

Table::getSession — Obtém a sessão da tabela

### Descrição

public function mysql_xdevapi\Table::getSession(): mysql_xdevapi\Session

Obtém a sessão associada com a tabela.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um objeto Session.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Table::getSession()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    var_dump($table->getSession());
    ?>

O exemplo acima produzirá algo semelhante a:

    object(mysql_xdevapi\Session)#9 (0) {
    }

# Table::insert

(No version information available, might only be in Git)

Table::insert — Insere linhas na tabela

### Descrição

public function mysql_xdevapi\Table::insert(mixed `$columns`, mixed `...$more_columns`): mysql_xdevapi\TableInsert

Insere linhas na tabela.

### Parâmetros

`columns`

  As colunas para inserir os dados. Pode ser um array com um ou mais valores, ou uma string.

`more_columns`

  Definições de colunas adicionais.

### Valor Retornado

Um objeto TableInsert; use o método execute() para executar a instrução de inserção.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Table::insert()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table ->insert("name", "age")
      ->values(["Suzanne", 31],["Julie", 43])
      ->execute();
    ?>

# Table::isView

(No version information available, might only be in Git)

Table::isView — Verifica se a tabela é uma visualização

### Descrição

public function mysql_xdevapi\Table::isView(): bool

Determina se o objeto subjacente é ou não uma visualização.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

`true` se o objeto subjacente for uma visualização, caso contrário `false`.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Table::isView()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    if ($table->isView()) {
        echo "Isto é uma visualização.";
    } else {
        echo "Isto não é uma visualização.";
    }
    ?>

O exemplo acima produzirá:

    Isto não é uma visualização.

# Table::select

(No version information available, might only be in Git)

Table::select — Seleciona linhas da tabela

### Descrição

public function mysql_xdevapi\Table::select(mixed `$columns`, mixed `...$more_columns`): mysql_xdevapi\TableSelect

Busca dados de uma tabela.

### Parâmetros

`columns`

  As colunas das quais os dados serão selecionados. Pode ser um array com um ou mais valores, ou uma string.

`more_columns`

  Definições de colunas adicionais.

### Valor Retornado

Um objeto TableSelect; use o método execute() para executar a seleção e retornar um objeto RowResult.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Table::count()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $row = $table->select('name', 'age')->execute()->fetchAll();

    print_r($row);

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 33
            )
    )

# Table::update

(No version information available, might only be in Git)

Table::update — Atualiza linhas na tabela

### Descrição

public function mysql_xdevapi\Table::update(): mysql_xdevapi\TableUpdate

Atualiza linhas na tabela.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um objeto TableUpdate; use o método execute() para executar a instrução de atualização.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Table::update()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->update()->set('age',34)->where('name = "Sam"')->limit(1)->execute();
    ?>

## Índice

- Table::__construct — Construtor de Table
- Table::count — Obtém contagem de linhas
- Table::delete — Deleta linhas da tabela
- Table::existsInDatabase — Verifica se uma tabela existe no banco de dados
- Table::getName — Obtém nome da tabela
- Table::getSchema — Obtém esquema da tabela
- Table::getSession — Obtém a sessão da tabela
- Table::insert — Insere linhas na tabela
- Table::isView — Verifica se a tabela é uma visualização
- Table::select — Seleciona linhas da tabela
- Table::update — Atualiza linhas na tabela

# Classe TableDelete

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

Uma instrução para operações de deleção em uma tabela.

## Resumo da classe

class mysql_xdevapi\TableDelete implements mysql_xdevapi\Executable {
/* Métodos */
public function bind(array `$placeholder_values`): mysql_xdevapi\TableDelete
public function execute(): mysql_xdevapi\Result
public function limit(int `$rows`): mysql_xdevapi\TableDelete
public function orderby(string `$orderby_expr`): mysql_xdevapi\TableDelete
public function where(string `$where_expr`): mysql_xdevapi\TableDelete
}

# TableDelete::bind

(No version information available, might only be in Git)

TableDelete::bind — Vincula parâmetros na instrução de deleção

### Descrição

public function mysql_xdevapi\TableDelete::bind(array `$placeholder_values`): mysql_xdevapi\TableDelete

Vincula um valor a um marcador específico.

### Parâmetros

`placeholder_values`

  O nome do marcador e o valor a vincular.

### Valor Retornado

Um objeto TableDelete.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\TableDelete::bind()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("name = :name")
      ->bind(['name' => 'John'])
      ->orderby("age DESC")
      ->limit(1)
      ->execute();

    ?>

# TableDelete::__construct

(No version information available, might only be in Git)

TableDelete::__construct — Construtor de TableDelete

### Descrição

private function mysql_xdevapi\TableDelete::__construct()

Iniciado pelo uso do método delete().

### Parâmetros

Esta função não possui parâmetros.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\TableDelete::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("name = :name")
      ->bind(['name' => 'John'])
      ->orderby("age DESC")
      ->limit(1)
      ->execute();

    ?>

# TableDelete::execute

(No version information available, might only be in Git)

TableDelete::execute — Executa a instrução de deleção

### Descrição

public function mysql_xdevapi\TableDelete::execute(): mysql_xdevapi\Result

Executa a instrução de deleção.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um objeto Result.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\TableDelete::execute()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("name = :name")
      ->bind(['name' => 'John'])
      ->orderby("age DESC")
      ->limit(1)
      ->execute();

    ?>

# TableDelete::limit

(No version information available, might only be in Git)

TableDelete::limit — Limita as linhas deletadas

### Descrição

public function mysql_xdevapi\TableDelete::limit(int `$rows`): mysql_xdevapi\TableDelete

Define o número máximo de registros ou documentos a deletar.

### Parâmetros

`rows`

  O número máximo de registros ou documentos a deletar.

### Valor Retornado

Objeto TableDelete.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\TableDelete::limit()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("name = :name")
      ->bind(['name' => 'John'])
      ->orderby("age DESC")
      ->limit(1)
      ->execute();

    ?>

# TableDelete::orderby

(No version information available, might only be in Git)

TableDelete::orderby — Define os critérios de ordenação na deleção

### Descrição

public function mysql_xdevapi\TableDelete::orderby(string `$orderby_expr`): mysql_xdevapi\TableDelete

Define as opções de ordenação para um conjunto de resultados.

### Parâmetros

`orderby_expr`

  A definição de ordenação.

### Valor Retornado

Um objeto TableDelete.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\TableDelete::orderBy()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("age = :age")
      ->bind(['age' => 42])
      ->orderby("name DESC")
      ->limit(1)
      ->execute();

    ?>

# TableDelete::where

(No version information available, might only be in Git)

TableDelete::where — Define condição de pesquisa na deleção

### Descrição

public function mysql_xdevapi\TableDelete::where(string `$where_expr`): mysql_xdevapi\TableDelete

Define a condição de pesquisa para filtrar.

### Parâmetros

`where_expr`

  Define a condição de pesquisa para filtrar documentos ou registros.

### Valor Retornado

Objeto TableDelete.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\TableDelete::where()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("id = :id")
      ->bind(['id' => 42])
      ->limit(1)
      ->execute();

    ?>

## Índice

- TableDelete::bind — Vincula parâmetros na instrução de deleção
- TableDelete::__construct — Construtor de TableDelete
- TableDelete::execute — Executa a instrução de deleção
- TableDelete::limit — Limita as linhas deletadas
- TableDelete::orderby — Define os critérios de ordenação na deleção
- TableDelete::where — Define condição de pesquisa na deleção

# Classe TableInsert

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

Uma instrução para operações de inserção em uma tabela.

## Resumo da classe

class mysql_xdevapi\TableInsert implements mysql_xdevapi\Executable {
/* Métodos */
public function execute(): mysql_xdevapi\Result
public function values(array `$row_values`): mysql_xdevapi\TableInsert
}

# TableInsert::__construct

(No version information available, might only be in Git)

TableInsert::__construct — Construtor de TableInsert

### Descrição

private function mysql_xdevapi\TableInsert::__construct()

Iniciado pelo uso do método insert().

### Parâmetros

Esta função não possui parâmetros.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\TableInsert::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table
      ->insert("name", "age")
      ->values(["Suzanne", 31],["Julie", 43])
      ->execute();
    ?>

# TableInsert::execute

(No version information available, might only be in Git)

TableInsert::execute — Executa instrução de inserção

### Descrição

public function mysql_xdevapi\TableInsert::execute(): mysql_xdevapi\Result

Executa a instrução.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um objeto Result.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\TableInsert::execute()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table
      ->insert("name", "age")
      ->values(["Suzanne", 31],["Julie", 43])
      ->execute();
    ?>

# TableInsert::values

(No version information available, might only be in Git)

TableInsert::values — Adiciona valores para inserção

### Descrição

public function mysql_xdevapi\TableInsert::values(array `$row_values`): mysql_xdevapi\TableInsert

Define os valores para inserção.

### Parâmetros

`row_values`

  Valores (como array) de colunas para inserção.

### Valor Retornado

Um objeto TableInsert.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\TableInsert::values()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table
      ->insert("name", "age")
      ->values(["Suzanne", 31],["Julie", 43])
      ->execute();
    ?>

## Índice

- TableInsert::__construct — Construtor de TableInsert
- TableInsert::execute — Executa instrução de inserção
- TableInsert::values — Adiciona valores para inserção

# Classe TableSelect

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

Uma instrução para operações de recuperação de registros em uma tabela.

## Resumo da classe

class mysql_xdevapi\TableSelect implements mysql_xdevapi\Executable {
/* Métodos */
public function bind(array `$placeholder_values`): mysql_xdevapi\TableSelect
public function execute(): mysql_xdevapi\RowResult
public function groupBy(mixed `$sort_expr`): mysql_xdevapi\TableSelect
public function having(string `$sort_expr`): mysql_xdevapi\TableSelect
public function limit(int `$rows`): mysql_xdevapi\TableSelect
public function lockExclusive(int `$lock_waiting_option` = ?): mysql_xdevapi\TableSelect
public function lockShared(int `$lock_waiting_option` = ?): mysql_xdevapi\TableSelect
public function offset(int `$position`): mysql_xdevapi\TableSelect
public function orderby(mixed `$sort_expr`, mixed `...$sort_exprs`): mysql_xdevapi\TableSelect
public function where(string `$where_expr`): mysql_xdevapi\TableSelect
}

# TableSelect::bind

(No version information available, might only be in Git)

TableSelect::bind — Vincula parâmetros de consulta de seleção

### Descrição

public function mysql_xdevapi\TableSelect::bind(array `$placeholder_values`): mysql_xdevapi\TableSelect

Vincula um valor a um marcador específico.

### Parâmetros

`placeholder_values`

  O nome do marcador, e o valor a vincular.

### Valor Retornado

Um objeto TableSelect.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\TableSelect::bind()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name','age')
      ->where('name like :name and age > :age')
      ->bind(['name' => 'John', 'age' => 42])
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::__construct

(No version information available, might only be in Git)

TableSelect::__construct — Construtor TableSelect

### Descrição

private function mysql_xdevapi\TableSelect::__construct()

Um objeto retornado pelo método select(); use execute() para executar a consulta.

### Parâmetros

Esta função não possui parâmetros.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\TableSelect::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name','age')
      ->where('name like :name and age > :age')
      ->bind(['name' => 'John', 'age' => 42])
      ->orderBy('age desc')
      ->execute();

    $row = $result->fetchAll();
    print_r($row);

    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::execute

(No version information available, might only be in Git)

TableSelect::execute — Executa instrução de seleção

### Descrição

public function mysql_xdevapi\TableSelect::execute(): mysql_xdevapi\RowResult

Executa a instrução de seleção encadeando-a com o método execute().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um objeto RowResult.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\TableSelect::execute()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name','age')
      ->where('name like :name and age > :age')
      ->bind(['name' => 'John', 'age' => 42])
      ->orderBy('age desc')
      ->execute();

    $row = $result->fetchAll();
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::groupBy

(No version information available, might only be in Git)

TableSelect::groupBy — Define critérios de agrupamento de seleção

### Descrição

public function mysql_xdevapi\TableSelect::groupBy(mixed `$sort_expr`): mysql_xdevapi\TableSelect

Define critérios de agrupamento para o conjunto de resultados.

### Parâmetros

`sort_expr`

  Os critérios de agrupamento.

### Valor Retornado

Um objeto TableSelect.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\TableSelect::groupBy()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 42)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('Suki', 31)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('count(*) as count', 'age')
      ->groupBy('age')->orderBy('age asc')
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Array
            (
                [count] => 1
                [age] => 31
            )
        [1] => Array
            (
                [count] => 2
                [age] => 42
            )
    )

# TableSelect::having

(No version information available, might only be in Git)

TableSelect::having — Definir condição para função de agregação na seleção

### Descrição

public function mysql_xdevapi\TableSelect::having(string `$sort_expr`): mysql_xdevapi\TableSelect

Define uma condição para registros a serem considerados nas operações de funções de agregação.

### Parâmetros

`sort_expr`

  Uma condição nas funções de agregação usadas nos critérios de agrupamento.

### Valor Retornado

Um objeto TableSelect.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\TableSelect::having()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 42)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('Suki', 31)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('count(*) as count', 'age')
      ->groupBy('age')->orderBy('age asc')
      ->having('count > 1')
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Array
            (
                [count] => 2
                [age] => 42
            )
    )

# TableSelect::limit

(No version information available, might only be in Git)

TableSelect::limit — Limita as linhas selecionadas

### Descrição

public function mysql_xdevapi\TableSelect::limit(int `$rows`): mysql_xdevapi\TableSelect

Define o número máximo de registros ou documentos a retornar.

### Parâmetros

`rows`

  O número máximo de registros ou documentos.

### Valor Retornado

Um objeto TableSelect.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\TableSelect::limit()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name', 'age')
      ->limit(1)
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::lockExclusive

(No version information available, might only be in Git)

TableSelect::lockExclusive — Executa EXCLUSIVE LOCK

### Descrição

public function mysql_xdevapi\TableSelect::lockExclusive(int `$lock_waiting_option` = ?): mysql_xdevapi\TableSelect

Executa uma operação de leitura com EXCLUSIVE LOCK. Somente uma trava pode estar ativa no mesmo momento.

### Parâmetros

`lock_waiting_option`

  Espera opcional cujo padrão é `MYSQLX_LOCK_DEFAULT`. Valores válidos são:

  - `MYSQLX_LOCK_DEFAULT`

  - `MYSQLX_LOCK_NOWAIT`

  - `MYSQLX_LOCK_SKIP_LOCKED`

### Valor Retornado

Objeto TableSelect.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\TableSelect::lockExclusive()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $session->startTransaction();

    $result = $table->select('name', 'age')
      ->lockExclusive(MYSQLX_LOCK_NOWAIT)
      ->execute();

    $session->commit();

    $row = $result->fetchAll();
    print_r($row);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 42
            )
    )

# TableSelect::lockShared

(No version information available, might only be in Git)

TableSelect::lockShared — Executa SHARED LOCK

### Descrição

public function mysql_xdevapi\TableSelect::lockShared(int `$lock_waiting_option` = ?): mysql_xdevapi\TableSelect

Executa uma operação de leitura com SHARED LOCK. Somente uma trava pode estar ativa no mesmo momento.

### Parâmetros

`lock_waiting_option`

  Espera opcional cujo padrão é `MYSQLX_LOCK_DEFAULT`. Valores válidos são:

  - `MYSQLX_LOCK_DEFAULT`

  - `MYSQLX_LOCK_NOWAIT`

  - `MYSQLX_LOCK_SKIP_LOCKED`

### Valor Retornado

Um objeto TableSelect.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\TableSelect::lockShared()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $session->startTransaction();

    $result = $table->select('name', 'age')
      ->lockShared(MYSQLX_LOCK_NOWAIT)
      ->execute();

    $session->commit();

    $row = $result->fetchAll();
    print_r($row);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 42
            )
    )

# TableSelect::offset

(No version information available, might only be in Git)

TableSelect::offset — Define o deslocamento limite

### Descrição

public function mysql_xdevapi\TableSelect::offset(int `$position`): mysql_xdevapi\TableSelect

Pula o número informado de linhas no resultado.

### Parâmetros

`position`

  O deslocamento limite.

### Valor Retornado

Um objeto TableSelect.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\TableSelect::offset()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 42)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name', 'age')
      ->limit(1)
      ->offset(1)
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Array
            (
                [name] => Sam
                [age] => 42
            )
    )

# TableSelect::orderby

(No version information available, might only be in Git)

TableSelect::orderby — Define critérios de ordenamento na seleção

### Descrição

public function mysql_xdevapi\TableSelect::orderby(mixed `$sort_expr`, mixed `...$sort_exprs`): mysql_xdevapi\TableSelect

Define a ordem por critérios.

### Parâmetros

`sort_expr`

  As expressões que definem a ordenação por critério. Pode ser um array com uma ou mais expressões ou uma string.

`sort_exprs`

  Parâmetros sort_expr adicionais.

### Valor Retornado

A TableSelect object.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\TableSelect::orderBy()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name', 'age')
      ->orderBy('name desc')
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Array
            (
                [name] => Sam
                [age] => 42
            )
        [1] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::where

(No version information available, might only be in Git)

TableSelect::where — Define condição de pesquisa na seleção

### Descrição

public function mysql_xdevapi\TableSelect::where(string `$where_expr`): mysql_xdevapi\TableSelect

Define condição de pesquisa para filtrar.

### Parâmetros

`where_expr`

  Define a condição de pesquisa para filtrar documentos ou registros.

### Valor Retornado

Um objeto TableSelect.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\TableSelect::where()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name','age')
      ->where('name like :name and age > :age')
      ->bind(['name' => 'John', 'age' => 42])
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

## Índice

- TableSelect::bind — Vincula parâmetros de consulta de seleção
- TableSelect::__construct — Construtor TableSelect
- TableSelect::execute — Executa instrução de seleção
- TableSelect::groupBy — Define critérios de agrupamento de seleção
- TableSelect::having — Definir condição para função de agregação na seleção
- TableSelect::limit — Limita as linhas selecionadas
- TableSelect::lockExclusive — Executa EXCLUSIVE LOCK
- TableSelect::lockShared — Executa SHARED LOCK
- TableSelect::offset — Define o deslocamento limite
- TableSelect::orderby — Define critérios de ordenamento na seleção
- TableSelect::where — Define condição de pesquisa na seleção

# TableUpdate class

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

Uma instrução para operações de atualização de registros em uma tabela.

## Resumo da classe

class mysql_xdevapi\TableUpdate implements mysql_xdevapi\Executable {
/* Métodos */
public function bind(array `$placeholder_values`): mysql_xdevapi\TableUpdate
public function execute(): mysql_xdevapi\TableUpdate
public function limit(int `$rows`): mysql_xdevapi\TableUpdate
public function orderby(mixed `$orderby_expr`, mixed `...$orderby_exprs`): mysql_xdevapi\TableUpdate
public function set(string `$table_field`, string `$expression_or_literal`): mysql_xdevapi\TableUpdate
public function where(string `$where_expr`): mysql_xdevapi\TableUpdate
}

# TableUpdate::bind

(No version information available, might only be in Git)

TableUpdate::bind — Vincula parâmetros de consulta de atualização

### Descrição

public function mysql_xdevapi\TableUpdate::bind(array `$placeholder_values`): mysql_xdevapi\TableUpdate

Vincula um valor a um marcador específico.

### Parâmetros

`placeholder_values`

  O nome do marcador e o valor a vincular, definidos como um array JSON.

### Valor Retornado

Um objeto TableUpdate.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\TableUpdate::bind()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->update()
      ->set('status', 'admin')
      ->where('name = :name and age > :age')
      ->bind(['name' => 'Bernie', 'age' => 2000])
      ->execute();

    ?>

# TableUpdate::__construct

(No version information available, might only be in Git)

TableUpdate::__construct — Construtor de TableUpdate

### Descrição

private function mysql_xdevapi\TableUpdate::__construct()

Iniciado pelo uso do método update().

### Parâmetros

Esta função não possui parâmetros.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\TableUpdate::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();

    ?>

# TableUpdate::execute

(No version information available, might only be in Git)

TableUpdate::execute — Executa instrução de atualização

### Descrição

public function mysql_xdevapi\TableUpdate::execute(): mysql_xdevapi\TableUpdate

Executa a instrução de atualização.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um objeto TableUpdate.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\TableUpdate::execute()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();

    ?>

# TableUpdate::limit

(No version information available, might only be in Git)

TableUpdate::limit — Limita contagem de atualização de linhas

### Descrição

public function mysql_xdevapi\TableUpdate::limit(int `$rows`): mysql_xdevapi\TableUpdate

Define o número máximo de registros ou documentos atualizados.

### Parâmetros

`rows`

  O número máximo de registros ou documentos a atualizar.

### Valor Retornado

Um objeto TableUpdate.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\TableUpdate::limit()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();

    ?>

# TableUpdate::orderby

(No version information available, might only be in Git)

TableUpdate::orderby — Define critérios de ordenação

### Descrição

public function mysql_xdevapi\TableUpdate::orderby(mixed `$orderby_expr`, mixed `...$orderby_exprs`): mysql_xdevapi\TableUpdate

Define os critérios de ordenação.

### Parâmetros

`orderby_expr`

  As expressões que definem a ordenação por critério. Pode ser um array com uma ou mais expressões ou uma string.

`orderby_exprs`

  Parâmetros sort_expr adicionais.

### Valor Retornado

Um objeto TableUpdate.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\TableUpdate::orderby()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();
    ?>

# TableUpdate::set

(No version information available, might only be in Git)

TableUpdate::set — Adiciona campo a ser atualizado

### Descrição

public function mysql_xdevapi\TableUpdate::set(string `$table_field`, string `$expression_or_literal`): mysql_xdevapi\TableUpdate

Atualiza valor da coluna nos registros em uma tabela.

### Parâmetros

`table_field`

  O nome da coluna a ser atualizada.

`expression_or_literal`

  O valor a ser definido na coluna especificada.

### Valor Retornado

Um objeto TableUpdate.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\TableUpdate::set()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();

    ?>

# TableUpdate::where

(No version information available, might only be in Git)

TableUpdate::where — Define filtro de pesquisa

### Descrição

public function mysql_xdevapi\TableUpdate::where(string `$where_expr`): mysql_xdevapi\TableUpdate

Define a condição de pesquisa para filtrar.

### Parâmetros

`where_expr`

  A condição de pesquisa para filtrar documentos ou registros.

### Valor Retornado

Um objeto TableUpdate.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\TableUpdate::where()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();

    ?>

## Índice

- TableUpdate::bind — Vincula parâmetros de consulta de atualização
- TableUpdate::__construct — Construtor de TableUpdate
- TableUpdate::execute — Executa instrução de atualização
- TableUpdate::limit — Limita contagem de atualização de linhas
- TableUpdate::orderby — Define critérios de ordenação
- TableUpdate::set — Adiciona campo a ser atualizado
- TableUpdate::where — Define filtro de pesquisa

# Classe Warning

(PECL mysql-xdevapi >= 8.0.11)

## Introdução

## Resumo da classe

class mysql_xdevapi\Warning {
/* Propriedades */
public $message;
public $level;
public $code;
/* Constructor */
private function __construct()
}

## Propriedades

message

level

code

# Warning::__construct

(No version information available, might only be in Git)

Warning::__construct — Construtor de Warning

### Descrição

private function mysql_xdevapi\Warning::__construct()

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Exemplos

Exemplo #1 Exemplo de mysql_xdevapi\Warning::__construct()

    <?php

    /* ... */

    ?>

## Índice

- Warning::__construct — Construtor de Warning

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
  - Construindo / Compilando a Partir da Fonte
- Constantes predefinidas
- Registro de Alterações
- Exemplos
- Funções de Mysql_xdevapi
  - expression — Vincula as variáveis de instrução preparada como parâmetros
  - getSession — Conecta a um servidor MySQL
- mysql_xdevapi\BaseResult — Interface BaseResult
  - BaseResult::getWarnings — Buscar alertas da última operação
  - BaseResult::getWarningsCount — Busca contagem de alertas da última operação
- mysql_xdevapi\Client — Classe Client
  - mysql_xdevapi\Client::close — Fecha o cliente
  - Client::__construct — Construtor de Client
  - Client::getClient — Obtém a sessão do cliente
- mysql_xdevapi\Collection — Classe Collection
  - Collection::add — Adiciona um documento na coleção
  - Collection::addOrReplaceOne — Adiciona ou substitui um documento na coleção
  - Collection::__construct — Construtor de Collection
  - Collection::count — Obtém a contagem de documentos
  - Collection::createIndex — Cria índice na coleção
  - Collection::dropIndex — Remove um índice da coleção
  - Collection::existsInDatabase — Verifica se uma coleção existe no banco de dados
  - Collection::find — Pesquisa por um documento
  - Collection::getName — Obtém o nome da coleção
  - Collection::getOne — Obtém um documento
  - Collection::getSchema — Obtém o objeto de esquema
  - Collection::getSession — Obtém o objeto de sessão
  - Collection::modify — Modifica documentos da coleção
  - Collection::remove — Remove documentos da coleção
  - Collection::removeOne — Remove um documento da coleção
  - Collection::replaceOne — Substitui um documento na coleção
- mysql_xdevapi\CollectionAdd — Classe CollectionAdd
  - CollectionAdd::__construct — Construtor de CollectionAdd
  - CollectionAdd::execute — Executa a instrução
- mysql_xdevapi\CollectionFind — Classe CollectionFind
  - CollectionFind::bind — Vincula valor a marcador na consulta
  - CollectionFind::__construct — Construtor de CollectionFind
  - CollectionFind::execute — Executa a instrução
  - CollectionFind::fields — Define filtro de campo de documento
  - CollectionFind::groupBy — Define critérios de agrupamento
  - CollectionFind::having — Define condição para funções de agregação
  - CollectionFind::limit — Limita o número de documentos retornados
  - CollectionFind::lockExclusive — Executa a operação com EXCLUSIVE LOCK
  - CollectionFind::lockShared — Executa a operação com SHARED LOCK
  - CollectionFind::offset — Pula um número de elementos a serem retornados
  - CollectionFind::sort — Define os critérios de ordenação
- mysql_xdevapi\CollectionModify — Classe CollectionModify
  - CollectionModify::arrayAppend — Anexa elemento a um array de campos
  - CollectionModify::arrayInsert — Insere elemento em um array de campos
  - CollectionModify::bind — Vincula valor ao marcador da consulta
  - CollectionModify::__construct — Construtor de CollectionModify
  - CollectionModify::execute — Executa operação de modificação
  - CollectionModify::limit — Limita o número de documentos modificados
  - CollectionModify::patch — Corrige documento
  - CollectionModify::replace — Substitui campo de documento
  - CollectionModify::set — Define atributo de documento
  - CollectionModify::skip — Pula elementos
  - CollectionModify::sort — Define os critérios de ordenação
  - CollectionModify::unset — Remove o valor de campos do documento
- mysql_xdevapi\CollectionRemove — Classe CollectionRemove
  - CollectionRemove::bind — Vincula valor ao marcador
  - CollectionRemove::__construct — Construtor de CollectionRemove
  - CollectionRemove::execute — Executa operação de remoção
  - CollectionRemove::limit — Limita o número de documentos a remover
  - CollectionRemove::sort — Define os critérios de ordenação
- mysql_xdevapi\ColumnResult — Classe ColumnResult
  - ColumnResult::__construct — Construtor de ColumnResult
  - ColumnResult::getCharacterSetName — Obtém o conjunto de caracteres
  - ColumnResult::getCollationName — Obtém o nome da colação
  - ColumnResult::getColumnLabel — Obtém o label da coluna
  - ColumnResult::getColumnName — Obtém o nome da coluna
  - ColumnResult::getFractionalDigits — Obtém o comprimento dos dígitos fracionários
  - ColumnResult::getLength — Obtém o comprimento do campo da coluna
  - ColumnResult::getSchemaName — Obtám o nome do esquema
  - ColumnResult::getTableLabel — Obtém o label da tabela
  - ColumnResult::getTableName — Obtém o nome da tabela
  - ColumnResult::getType — Obtém o tipo de coluna
  - ColumnResult::isNumberSigned — Verifica se é do tipo com sinal
  - ColumnResult::isPadded — Verifica se é preenchida à esquerda
- mysql_xdevapi\CrudOperationBindable — Interface CrudOperationBindable
  - CrudOperationBindable::bind — Vincula valor ao marcador
- mysql_xdevapi\CrudOperationLimitable — Interface CrudOperationLimitable
  - CrudOperationLimitable::limit — Define o limite do resultado
- mysql_xdevapi\CrudOperationSkippable — Interface CrudOperationSkippable
  - CrudOperationSkippable::skip — Número de operações a pular
- mysql_xdevapi\CrudOperationSortable — Interface CrudOperationSortable
  - CrudOperationSortable::sort — Ordena resultados
- mysql_xdevapi\DatabaseObject — Interface DatabaseObject
  - DatabaseObject::existsInDatabase — Verifica se um objeto existe em um banco de dados
  - DatabaseObject::getName — Obtém o nome do objeto
  - DatabaseObject::getSession — Obtém o nome da sessão
- mysql_xdevapi\DocResult — Classe DocResult
  - DocResult::__construct — Construtor de DocResult
  - DocResult::fetchAll — Obtém todas as linhas
  - DocResult::fetchOne — Obtém uma linha
  - DocResult::getWarnings — Obtém alertas da última operação
  - DocResult::getWarningsCount — Obtém a contagem de alertas da última operação
- mysql_xdevapi\Exception — Classe Exception
- mysql_xdevapi\Executable — Interface Executable
  - Executable::execute — Executa instrução
- mysql_xdevapi\ExecutionStatus — Classe ExecutionStatus
  - ExecutionStatus::__construct — Construtor de ExecutionStatus
- mysql_xdevapi\Expression — Classe Expression
  - Expression::__construct — Construtor de Expression
- mysql_xdevapi\Result — Classe Result
  - Result::__construct — Construtor de Result
  - Result::getAffectedItemsCount — Obtém contagem de linhas afetadas
  - Result::getAutoIncrementValue — Obtém valor de incremento automático
  - Result::getGeneratedIds — Obtém os IDs gerados
  - Result::getWarnings — Obtém alertas da última operação
  - Result::getWarningsCount — Obtém contagem de alertas da última operação
- mysql_xdevapi\RowResult — Classe RowResult
  - RowResult::__construct — Construtor de RowResult
  - RowResult::fetchAll — Obtém todas as linhas do resultado
  - RowResult::fetchOne — Obtém linha do resultado
  - RowResult::getColumnsCount — Obtém a contagem de colunas
  - RowResult::getColumnNames — Obtém o nome de todas as colunas
  - RowResult::getColumns — Obtém metadados de coluna
  - RowResult::getWarnings — Obtém os alertas da última operação
  - RowResult::getWarningsCount — Obtém a contagem de alertas da última operação
- mysql_xdevapi\Schema — Classe Schema
  - Schema::__construct — Construtor de Schema
  - Schema::createCollection — Adiciona coleção ao esquema
  - Schema::dropCollection — Remove coleção do esquema
  - Schema::existsInDatabase — Verifica se existe no banco de dados
  - Schema::getCollection — Obtém coleção do esquema
  - Schema::getCollectionAsTable — Obtém uma coleção como um objeto Table
  - Schema::getCollections — Obtém todas as coleções do esquema
  - Schema::getName — Obtém o nome do esquema
  - Schema::getSession — Obtém a sessão do esquema
  - Schema::getTable — Obtém tabela do esquema
  - Schema::getTables — Obtém tabelas do esquema
- mysql_xdevapi\SchemaObject — Interface SchemaObject
  - SchemaObject::getSchema — Obtém o objeto do esquema
- mysql_xdevapi\Session — Classe Session
  - Session::close — Fecha sessão
  - Session::commit — Confirma a transação
  - Session::__construct — Construtor de Description
  - Session::createSchema — Cria novo esquema
  - Session::dropSchema — Remove um esquema
  - Session::generateUUID — Obtém novo UUID
  - Session::getDefaultSchema — Obtém o nome de esquema padrão
  - Session::getSchema — Obtém um novo objeto de esquema
  - Session::getSchemas — Obtém os esquemas
  - Session::getServerVersion — Obtém a versão do servidor
  - Session::listClients — Obtém a lista de clientes
  - Session::quoteName — Adiciona escape
  - Session::releaseSavepoint — Libera o ponto de gravação definido
  - Session::rollback — Reverte a transação
  - Session::rollbackTo — Reverte a transação para um ponto de gravação
  - Session::setSavepoint — Cria ponto de gravação
  - Session::sql — Cria consulta SQL
  - Session::startTransaction — Inicia transação
- mysql_xdevapi\SqlStatement — Classe SqlStatement
  - SqlStatement::bind — Vincula parâmetros da instrução
  - SqlStatement::__construct — Construtor de Description
  - SqlStatement::execute — Executa a operação
  - SqlStatement::getNextResult — Obtém o próximo resultado
  - SqlStatement::getResult — Obtém resultado
  - SqlStatement::hasMoreResults — Verifica por mais resultados
- mysql_xdevapi\SqlStatementResult — Classe SqlStatementResult
  - SqlStatementResult::__construct — Construtor de SqlStatementResult
  - SqlStatementResult::fetchAll — Obtém todas as linhas do resultado
  - SqlStatementResult::fetchOne — Obtém uma única linha
  - SqlStatementResult::getAffectedItemsCount — Obtém a contagem de linhas afetadas
  - SqlStatementResult::getColumnsCount — Obtém a contagem de colunas
  - SqlStatementResult::getColumnNames — Obtém nomes de colunas
  - SqlStatementResult::getColumns — Obtém colunas
  - SqlStatementResult::getGeneratedIds — Obtém IDs gerados
  - SqlStatementResult::getLastInsertId — Obtém o ID da última inserção
  - SqlStatementResult::getWarnings — Obtém alertas da última operação
  - SqlStatementResult::getWarningsCount — Obtém contagem de alertas da última operação
  - SqlStatementResult::hasData — Verifica se o resultado tem dados
  - SqlStatementResult::nextResult — Obtém o próximo resultado
- mysql_xdevapi\Statement — Classe Statement
  - Statement::__construct — Construtor de Statement
  - Statement::getNextResult — Obtém o próximo resultado
  - Statement::getResult — Obtém resultado
  - Statement::hasMoreResults — Verifica se há mais resultados
- mysql_xdevapi\Table — Classe Table
  - Table::__construct — Construtor de Table
  - Table::count — Obtém contagem de linhas
  - Table::delete — Deleta linhas da tabela
  - Table::existsInDatabase — Verifica se uma tabela existe no banco de dados
  - Table::getName — Obtém nome da tabela
  - Table::getSchema — Obtém esquema da tabela
  - Table::getSession — Obtém a sessão da tabela
  - Table::insert — Insere linhas na tabela
  - Table::isView — Verifica se a tabela é uma visualização
  - Table::select — Seleciona linhas da tabela
  - Table::update — Atualiza linhas na tabela
- mysql_xdevapi\TableDelete — Classe TableDelete
  - TableDelete::bind — Vincula parâmetros na instrução de deleção
  - TableDelete::__construct — Construtor de TableDelete
  - TableDelete::execute — Executa a instrução de deleção
  - TableDelete::limit — Limita as linhas deletadas
  - TableDelete::orderby — Define os critérios de ordenação na deleção
  - TableDelete::where — Define condição de pesquisa na deleção
- mysql_xdevapi\TableInsert — Classe TableInsert
  - TableInsert::__construct — Construtor de TableInsert
  - TableInsert::execute — Executa instrução de inserção
  - TableInsert::values — Adiciona valores para inserção
- mysql_xdevapi\TableSelect — Classe TableSelect
  - TableSelect::bind — Vincula parâmetros de consulta de seleção
  - TableSelect::__construct — Construtor TableSelect
  - TableSelect::execute — Executa instrução de seleção
  - TableSelect::groupBy — Define critérios de agrupamento de seleção
  - TableSelect::having — Definir condição para função de agregação na seleção
  - TableSelect::limit — Limita as linhas selecionadas
  - TableSelect::lockExclusive — Executa EXCLUSIVE LOCK
  - TableSelect::lockShared — Executa SHARED LOCK
  - TableSelect::offset — Define o deslocamento limite
  - TableSelect::orderby — Define critérios de ordenamento na seleção
  - TableSelect::where — Define condição de pesquisa na seleção
- mysql_xdevapi\TableUpdate — TableUpdate class
  - TableUpdate::bind — Vincula parâmetros de consulta de atualização
  - TableUpdate::__construct — Construtor de TableUpdate
  - TableUpdate::execute — Executa instrução de atualização
  - TableUpdate::limit — Limita contagem de atualização de linhas
  - TableUpdate::orderby — Define critérios de ordenação
  - TableUpdate::set — Adiciona campo a ser atualizado
  - TableUpdate::where — Define filtro de pesquisa
- mysql_xdevapi\Warning — Classe Warning
  - Warning::__construct — Construtor de Warning

# API Original MySQL

# Introdução

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida a partir do PHP 7.0.0. No lugar dela, tanto a extensão mysqli quanto a extensão PDO_MySQL devem ser usadas. Consulte também a Visão Geral da API MySQL para ajuda adicional na escolha de uma API MySQL.

Estas funções permitem acessar servidores de banco de dados MySQL. Mais informação sobre o MySQL podem ser encontradas em » http://www.mysql.com/.

Documentação para o MySQL pode ser encontrada em » http://dev.mysql.com/doc/.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução
- Tipos de Recurso

## Dependências

Para ter estas funções disponíveis, você deve compilar o PHP com suporte ao MySQL.

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

## Instalação

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

Para compilar, simplesmente use a opção de configuração --with-mysql[=DIR] onde o parâmetro opcional `[DIR]` aponta para o diretório onde o MySQL está instalado.

Embora esta esta extensão MySQL seja compatível com o MySQL 4.1.0 e posterior, ela não suporta a funcionalidade extra que estas versões fornecem. Para isto, use a extensão MySQLi.

Se você quiser instalar a extensão mysql junto com a extensão mysqli você deve usar a mesma biblioteca de cliente para evitar quaisquer conflitos.

## Instalação em Sistemas Linux

Nota: `[DIR]` é o caminho para os arquivos da biblioteca de cliente MySQL (cabeçalhos e bibliotecas), que podem ser obtidos do site do » MySQL.

Matriz de suporte em tempo de compilação da ext/mysql
Versão do PHP | Padrão | Opções de Configuração: mysqlnd | Opções de Configuração: `libmysqlclient` | Registro de Alterações
--- | --- | --- | --- | ---
4.x.x | libmysqlclient | Não Disponível | --without-mysql para desabilitar | MySQL habilitado por padrão, bibliotecas de clientes MySQL vêm embutidas
5.0.x, 5.1.x, 5.2.x | libmysqlclient | Não Disponível | --with-mysql=[DIR] | O MySQL não é mais habilitado por padrão, e as bibliotecas de clientes MySQL não vêm mais embutidas
5.3.x | libmysqlclient | --with-mysql=mysqlnd | --with-mysql=[DIR] | mysqlnd agora está disponível
5.4.x | mysqlnd | --with-mysql | --with-mysql=[DIR] | mysqlnd agora é o padrão

## Instalação em Sistemas Windows

## PHP 5.0.x, 5.1.x, 5.2.x

O MySQL não é mais habilitado por padrão, então a DLL php_mysql.dll deve estar habilitada dentro do php.ini. Além disso, o PHP precisa de acesso à biblioteca de cliente MySQL. Um arquivo chamado libmysql.dll é incluído na distribuição PHP do Windows, e para que o PHP possa conversar com o MySQL este arquivo precisa estar disponível no PATH dos sistemas Windows. Veja a pergunta entitulada "Como adicionar meu diretório PHP ao PATH do Windows" para informações sobre como fazer isso. Embora copiar o arquivo libmysql.dll para o diretório de sistema do Windows também funcione (porque o diretório de sistema está por padrão no PATH do sistema), isto não é recomendado.

Assim como ao habilitar qualquer extensão PHP (como php_mysql.dll), a diretiva PHP extension_dir deve apontar para o diretório onde as extensões PHP estão localizadas. Veja também as Instruções para Instalação Manual no Windows. Um exemplo de valor para extension_dir no PHP 5 é `c:\php\ext`

> Nota: Se ao iniciar o servidor web um erro similar ao seguinte ocorrer: `"Unable to load dynamic library './php_mysql.dll'"`, é porque o arquivo php_mysql.dll e/ou libmysql.dll não pode ser encontrado pelo sistema.

## PHP 5.3.0+

O Driver Nativo MySQL está habilitado por padrão. Inclui php_mysql.dll, mas libmysql.dll não é mais necessário ou usado.

## Notas de Instalação do MySQL

Aviso

Falhas e problemas de inicialização do PHP podem ocorrer ao carregar esta extensão em conjunto com a extensão recode. Veja a extensão recode para maiores informações.

> Nota: Se for necessário usar conjuntos de caracteres diferentes de latin (padrão), deve-se instalar uma libmysqlclient externa (não incluída) com o suporte ao conjunto de caracteres compilado.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de configuração do MySQL
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
mysql.allow_local_infile | "1" | `INI_SYSTEM` |
mysql.allow_persistent | "1" | `INI_SYSTEM` |
mysql.max_persistent | "-1" | `INI_SYSTEM` |
mysql.max_links | "-1" | `INI_SYSTEM` |
mysql.trace_mode | "0" | `INI_ALL` |
mysql.default_port | NULL | `INI_ALL` |
mysql.default_socket | NULL | `INI_ALL` |
mysql.default_host | NULL | `INI_ALL` |
mysql.default_user | NULL | `INI_ALL` |
mysql.default_password | NULL | `INI_ALL` |
mysql.connect_timeout | "60" | `INI_ALL` |

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`mysql.allow_local_infile` int
  Permite acessar, da perspectiva do PHP, arquivos locais com declarações LOAD DATA
`mysql.allow_persistent` bool
  Se deve-se permitir conexões persistentes para MySQL.
`mysql.max_persistent` int
  O número máximo de conexões persistentes com o MySQL por processo.
`mysql.max_links` int
  O número máximo de conexões com o MYSQL por processo, incluindo conexões persistentes.
`mysql.trace_mode` bool
  Modo de rastreamento. Quando `mysql.trace_mode` está ativado, alertas para pesquisas em tabelas/índices, conjuntos de resultados não liberados, e erros de SQL serão exibidos.
`mysql.default_port` string
  O número padrão da porta TCP a usar quando conectar com o servidor do banco de dados se nenhuma outra porta for especificada. Se nenhum padrão for especificado, a porta será obtida da variável de ambiente MYSQL_TCP_PORT, da entrada `mysql-tcp` em /etc/services ou da constante da compilação `MYSQL_PORT`, nesta ordem. Windows irá usar somente a constante `MYSQL_PORT`.
`mysql.default_socket` string
  O nome padrão do socket para usar quando conectar com um servidor de banco de dados local se outro nome de socket não for especificado.
`mysql.default_host` string
  O servidor padrão para usar quando conectar com um servidor de banco de dados se outro servidor não for encontrado. Não se aplica em modo seguro do SQL.
`mysql.default_user` string
  O nome padrão de usuário para conectar ao servidor de banco de dados se outro nome não for especificado. Não se aplica em modo seguro do SQL.
`mysql.default_password` string
  A senha padrão para usar ao conectar ao servidor de banco de dados se outra senha não for especificada. Não se aplica em modo seguro do SQL.
`mysql.connect_timeout` int
  Limite de tempo da conexão em segundos. No Linux este limite é também usado para a espera da primeira resposta do servidor.

## Tipos de Recurso

Existem dois tipos de recursos usados no módulo MySQL. O primeiro é o identificador de conexão com o banco de dados, e o segundo é o recurso que guarda o resultado de uma consulta.

# Registro de Alterações

As alterações a seguir foram feitas em classes/funções/métodos desta extensão.

### Registro Geral de Modificações para a extensão ext/mysql

Este registro de modificações referencia a extensão ext/mysql.

### Modificações ext/mysql globais

Uma lista de modificações à extensão ext/mysql está apresentada a seguir.

Versão | Descrição
--- | ---
7.0.0 | Esta extensão foi removida do PHP. Para detalhes, consulte Escolhendo uma API.

### Modificações a funções existentes

A lista a seguir é uma compilação de entradas de modificações das funções ext/mysql.

Version | Function | Description
--- | --- | ---

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

É possível especificar opções de cliente adicionais para as funções mysql_connect() e mysql_pconnect(). As seguintes constantes estão definidas:

Constantes do cliente MySQL
Constante | Descrição
--- | ---
`MYSQL_CLIENT_COMPRESS` | Usar protocolo de compressão
`MYSQL_CLIENT_IGNORE_SPACE` | Permitir espaços após nomes de funções
`MYSQL_CLIENT_INTERACTIVE` | Permitir interactive_timeout segundos (ao invés de wait_timeout) de inatividade antes de fechar a conexão.
`MYSQL_CLIENT_SSL` | Usar criptografia SSL. Esta opçõa está disponível somente com a versão 4.x ou posterior da biblioteca cliente MySQL. A versão 3.23.x é incluída com o PHP 4 e com binários Windows do PHP 5.

A função mysql_fetch_array() usa uma constante para os diferentes tipos de arrays de resultados. As constantes a seguir estão definidas:

Constantes de busca MySQL
Constante | Descrição
--- | ---
`MYSQL_ASSOC` | Colunas são retornadas no array contendo o nome do campo como as chaves do array.
`MYSQL_BOTH` | Colunas são retornadas no array contendo chaves numéricas e chaves com o nome do campo.
`MYSQL_NUM` | Colunas são retornadas no array contendo chaves numéricas para os campos. A chave inicia em 0 para o primeiro campo do resultado.

# Exemplos

## Índice

- Exemplo de uso da extensão MySQL

## Exemplo de uso da extensão MySQL

Este exemplo simples mostra como conectar, executar uma consulta, mostrar as linhas do resultado e disconectar de um banco de dados MySQL.

Exemplo #1 Exemplo de uso da extensão MySQL

    <?php
    // Conectando e selecionando o banco de dados
    $link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password')
        or die('Não foi possível conectar: ' . mysql_error());
    echo 'Conectado com sucesso';
    mysql_select_db('my_database') or die('Não foi possível selecionar o banco de dados');

    // Realizado a consulta SQL
    $query = 'SELECT * FROM my_table';
    $result = mysql_query($query) or die('A consulta falhou: ' . mysql_error());

    // Exebindo os resultados em HTML
    echo "<table>\n";
    while ($line = mysql_fetch_array($result, MYSQL_ASSOC)) {
        echo "\t<tr>\n";
        foreach ($line as $col_value) {
            echo "\t\t<td>$col_value</td>\n";
        }
        echo "\t</tr>\n";
    }
    echo "</table>\n";

    // Libera o conjunto de resultados
    mysql_free_result($result);

    // Fecha a conexão
    mysql_close($link);
    ?>

# Funções da MySQL

## Notas

> Nota: A maioria das funções MySQL aceitam `link_identifier` como o último parâmetro opcional. Se este não for dados, a última conexão aberta é usada. Se não existir, é tentado estabelecer uma conexão com os valores padrão definidos no php.ini. Se não for possível, a função retornará `false`.

# mysql_affected_rows

(PHP 4, PHP 5)

mysql_affected_rows — Obtém o número de linhas afetadas na operação anterior do MySQL

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_affected_rows()
- PDOStatement::rowCount()

### Descrição

function mysql_affected_rows(resource `$link_identifier` = NULL): int

Obtém o número de linhas afetadas pelo último INSERT, UPDATE, REPLACE ou DELETE associado ao `link_identifier`.

### Parâmetros

`link_identifier`
  A conexão MySQL. Se o identificador da conexão não for especificado, a última conexão aberta por mysql_connect() será usada. Se não houver uma conexão anterior, haverá uma tentativa de criar uma como se mysql_connect() tivesse sido chamada sem argumentos. Se nenhuma conexão for encontrada ou estabelecida, um erro de nível `E_WARNING` será gerado.

### Valor Retornado

Retorna o número de linas afetadas em caso de sucesso, e -1 se a última consulta falhou.

Se a última consulta foi um DELETE sem a claúsula WHERE, todos os registros terão sido excluídos da tabela mas esta função irá retornar zero em versões do MySQL anteriores a 4.1.2.

Ao usar UPDATE, o MySQL não irá atualizar colunas aonde o novo valor é o mesmo que o valor anterior. Isto cria a possibilidade de que mysql_affected_rows() possa não ser igual ao número de linhas encontradas, apenas o número de linhas que literalmente foram afetadas pela consulta.

O comando REPLACE primeiro exclui o registro com a mesma chave primária e então insere o novo registro. Esta função retorna o número de registros excluídos mais o número de registros inseridos.

No caso de consultas "INSERT ... ON DUPLICATE KEY UPDATE", o valor retornado será `1` se um insert foi executado, ou `2` para um update de uma linha existente.

### Exemplos

Exemplo #1 Exemplo mysql_affected_rows()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Não foi possível conectar: ' . mysql_error());
    }
    mysql_select_db('mydb');

    /* isso deve retornar os números corretos de registros excluídos */
    mysql_query('DELETE FROM mytable WHERE id < 10');
    printf("Registro excluídos: %d\n", mysql_affected_rows());

    /* com uma cláusula where que nunca é verdadeira, ela deve retornar 0 */
    mysql_query('DELETE FROM mytable WHERE 0');
    printf("Registro excluídos: %d\n", mysql_affected_rows());
    ?>

O exemplo acima produzirá algo semelhante a:

    Registro excluídos: 10
    Registro excluídos: 0

Exemplo #2 Exemplo de mysql_affected_rows() usando transações

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Não foi possível conectar: ' . mysql_error());
    }
    mysql_select_db('mydb');

    /* Atualiza registros */
    mysql_query("UPDATE mytable SET used=1 WHERE id < 10");
    printf ("Registros atualizados: %d\n", mysql_affected_rows());
    mysql_query("COMMIT");
    ?>

O exemplo acima produzirá algo semelhante a:

    Registros atualizados: 10

### Notas

> Nota: Transações
> Se você estiver usando transações, você deve utilizar mysql_affected_rows() depois da sua consulta INSERT, UPDATE, ou DELETE, não depois de COMMIT.

> Nota: Comandos SELECT
> Para obter o número de linhas retornados por um SELECT, é possível usar mysql_num_rows().

> Nota: Chaves estrangeiras em cascata
> mysql_affected_rows() não conta linhas afetadas implicitamente pelo uso de ON DELETE CASCADE e/ou ON UPDATE CASCADE em chaves estrangeiras.

### Veja Também

- mysql_num_rows() - Obtém o número de linhas em um resultado
- mysql_info() - Obtém informação sobre a consulta mais recente

# mysql_client_encoding

(PHP 4 >= 4.3.0, PHP 5)

mysql_client_encoding — Retorna o nome do conjunto de caracteres

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_character_set_name()

### Descrição

function mysql_client_encoding(resource `$link_identifier` = NULL): string

Obtém a variável `character_set` do MySQL.

### Parâmetros

`link_identifier`
  A conexão MySQL. Se o identificador da conexão não for especificado, a última conexão aberta por mysql_connect() será usada. Se não houver uma conexão anterior, haverá uma tentativa de criar uma como se mysql_connect() tivesse sido chamada sem argumentos. Se nenhuma conexão for encontrada ou estabelecida, um erro de nível `E_WARNING` será gerado.

### Valor Retornado

Retorna o nome do conjunto de caracteres padrão para a conexão atual.

### Exemplos

Exemplo #1 Exemplo de mysql_client_encoding()

    <?php
    $link    = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    $charset = mysql_client_encoding($link);

    echo "O conjunto de caracteres atual é: $charset\n";
    ?>

O exemplo acima produzirá algo semelhante a:

    O conjunto de caracteres atual é: latin1

### Veja Também

- mysql_set_charset() - Define o conjunto de caracteres do cliente
- mysql_real_escape_string() - Escapa os caracteres especiais em uma string para uso em uma instrução SQL

# mysql_close

(PHP 4, PHP 5)

mysql_close — Fecha a conexão MySQL

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_close()
- PDO: Atribuir o valor `null` ao objeto PDO

### Descrição

function mysql_close(resource `$link_identifier` = NULL): bool

mysql_close() fecha a conexão não persistente ao servidor MySQL que está associado ao identificador de conexão especificado. Se `link_identifier` não for especificado, a última conexão aberta é usada.

Conexões MySQL não persistentes abertas e conjuntos de resultados são automaticamente destruídos quando um script PHP termina sua execução. Portanto, embora seja opcional fechar conexões abertas e liberar conjuntos de resultados, isso é recomendado. Isso retornará imediatamente os recursos usados ao PHP e MySQL, o que pode melhorar o desempenho. Para obter informações relacionadas, consulte a página liberando recursos.

### Parâmetros

`link_identifier`
  A conexão MySQL. Se o identificador da conexão não for especificado, a última conexão aberta por mysql_connect() será usada. Se nenhuma conexão for encontrada ou estabelecida, um erro de nível `E_WARNING` será gerado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo mysql_close()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Não foi possível conectar: ' . mysql_error());
    }
    echo 'Conectado com sucesso';
    mysql_close($link);
    ?>

O exemplo acima produzirá:

    Conectado com sucesso

### Notas

> Nota: mysql_close() não irá fechar conexões persistentes criadas por mysql_pconnect(). Para detalhes adicionais, consulte a seção sobre conexões persistentes.

### Veja Também

- mysql_connect() - Abre uma conexão a um servidor MySQL
- mysql_free_result() - Libera memória usada pelo resultado

# mysql_connect

(PHP 4, PHP 5)

mysql_connect — Abre uma conexão a um servidor MySQL

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_connect()
- PDO::__construct()

### Descrição

function mysql_connect(
string `$server` = ini_get("mysql.default_host"),
string `$username` = ini_get("mysql.default_user"),
string `$password` = ini_get("mysql.default_password"),
bool `$new_link` = `false`,
int `$client_flags` = 0
): resource|false

Abre ou reutiliza uma conexão a um servidor MySQL.

### Parâmetros

`server`
  O servidor MySQL. Também pode incluir um número de porta, por exemplo, "servidor:porta" ou um caminho para um soquete local, por exemplo ":/caminho/para/socquete" para o servidor local. Se a diretiva do PHP mysql.default_host não estiver definida (padrão), o valor padrão é 'localhost:3306'. No modo seguro do SQL, este parâmetro é ignorado e o valor 'localhost:3306' é sempre usado.
`username`
  O nome de usuário. O valor padrão é definido pela diretiva mysql.default_user. No modo seguro do SQL, este parâmetro é ignorado e o nome do usuário proprietário do processo do servidor é usado.
`password`
  A senha. O valor padrão é definido pela diretiva mysql.default_password. No modo seguro do SQL, este parâmetro é ignorado e uma senha vazia é usada.
`new_link`
  Se uma segunda chamada for feita a mysql_connect() com os mesmos argumentos, não é estabelecida uma nova conexão, mas ao invés disso, o identificador da conexão que já estiver aberta será retornado. O parâmetro `new_link` modifica este comportamento e faz com que mysql_connect() sempre abra uma nova conexão, mesmo se mysql_connect() tiver sido chamada antes com os mesmos parâmetros. No modo seguro do SQL, este parâmetro é ignorado.
`client_flags`
  O parâmetro `client_flags` pode ser uma combinação das seguintes constantes: 128 (habilita uso de `LOAD DATA LOCAL`), `MYSQL_CLIENT_SSL`, `MYSQL_CLIENT_COMPRESS`, `MYSQL_CLIENT_IGNORE_SPACE` ou `MYSQL_CLIENT_INTERACTIVE`. Leia a seção sobre Constantes do cliente MySQL para mais informações. No modo seguro do SQL, este parâmetro é ignorado.

### Valor Retornado

Retorna um identificador de conexão MySQL em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de mysql_connect()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Não foi possível conectar: ' . mysql_error());
    }
    echo 'Conexão bem sucedida';
    mysql_close($link);
    ?>

Exemplo #2 Exemplo de mysql_connect() usando a a sintaxe `servidor:porta`

    <?php
    // Conexão a example.com na porta 3307
    $link = mysql_connect('example.com:3307', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Não foi possível conectar: ' . mysql_error());
    }
    echo 'Conexão bem sucedida';
    mysql_close($link);

    // Conexão com servidor local na porta 3307
    $link = mysql_connect('127.0.0.1:3307', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Não foi possível conectar: ' . mysql_error());
    }
    echo 'Conexão bem sucedida';
    mysql_close($link);
    ?>

Exemplo #3 Exemplo de mysql_connect() usando a sintaxe ":/caminho/para/soquete"

    <?php
    // Conexão ao servidor local e soquete, ex.: /tmp/mysql.sock

    // Variação 1: omitindo localhost
    $link = mysql_connect('/tmp/mysql', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Não foi possível conectar: ' . mysql_error());
    }
    echo 'Conexão bem sucedida';
    mysql_close($link);

    // Variação 2: com localhost
    $link = mysql_connect('localhost:/tmp/mysql.sock', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Não foi possível conectar: ' . mysql_error());
    }
    echo 'Conexão bem sucedida';
    mysql_close($link);
    ?>

### Notas

> Nota: Em qualquer lugar que for especificado "localhost" ou "localhost:porta" como servidor, a biblioteca cliente do MySQL irá sobrescrever isso e tentar se conectar a um soquete local (pipe nomeado no Windows). Se for desejado usar TCP/IP, deve-se usar "127.0.0.1" ao invés de "localhost". Se a biblioteca cliente do MySQL tentar se conectar com o soquete local errado, o caminho correto deve ser definido como mysql.default_host no php.ini e o campo do servidor deve ser deixado em branco.

> Nota: A conexão com o servidor será fechada assim que a execução do script terminar, a menos que tenha sido fechada anteriormente chamando-se mysql_close() explicitamente.

> Nota: O erro "Can't create TCP/IP socket (10106)" normalmente significa que a diretiva de configuração variables_order não contém o caractere `E`. No Windows, se o ambiente não for copiado, a variável de ambiente `SYSTEMROOT` não estará disponível e o PHP terá problemas para carregar o Winsock.

### Veja Também

- mysql_pconnect() - Abre uma conexão persistente a um servidor MySQL
- mysql_close() - Fecha a conexão MySQL

# mysql_create_db

(PHP 4, PHP 5)

mysql_create_db — Cria um banco de dados MySQL

Aviso

Esta função foi descontinuada a partir do PHP 4.3.0 e ela e a extensão MySQL original foram removidas a partir do PHP 7.0.0. Em vez disso, use as extensões MySQLi ou PDO_MySQL, que são desenvolvidas ativamente. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_query()
- PDO::query()

### Descrição

function mysql_create_db(string `$database_name`, resource `$link_identifier` = NULL): bool

mysql_create_db() tenta criar um novo banco de dados no servidor associado com o identificador de conexão especificado.

### Parâmetros

`database_name`
  O nome do banco de dados a ser criado.
`link_identifier`
  A conexão MySQL. Se o identificador da conexão não for especificado, a última conexão aberta por mysql_connect() será usada. Se não houver uma conexão anterior, haverá uma tentativa de criar uma como se mysql_connect() tivesse sido chamada sem argumentos. Se nenhuma conexão for encontrada ou estabelecida, um erro de nível `E_WARNING` será gerado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo alternativo de mysql_create_db()

A função mysql_create_db() foi descontinuada. É preferível usar a função mysql_query() para executar o comando `CREATE DATABASE`.

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Não foi possível conectar: ' . mysql_error());
    }

    $sql = 'CREATE DATABASE my_db';
    if (mysql_query($sql, $link)) {
        echo "Banco de dados my_db criado com sucesso\n";
    } else {
        echo 'Erro ao criar banco de dados: ' . mysql_error() . "\n";
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Banco de dados my_db criado com sucesso

### Notas

> Nota: Para compatibilidade com versões anteriores, o seguinte apelido descontinuado pode ser usado: mysql_createdb()

> Nota: Esta função não estará disponível se a extensão MySQL foi compilada com a versão MySQL 4.x da biblioteca de cliente.

### Veja Também

- mysql_query() - Envia uma consulta MySQL
- mysql_select_db() - Seleciona um banco de dados MySQL

# mysql_data_seek

(PHP 4, PHP 5)

mysql_data_seek — Move o ponteiro interno do resultado

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_data_seek()
- `PDO::FETCH_ORI_ABS`

### Descrição

function mysql_data_seek(resource `$result`, int `$row_number`): bool

mysql_data_seek() move o ponteiro interno da linha de um resultado MySQL associado ao identificador de resultado informado para o número da linha especificada. A próxima chamada a uma função MySQL que retorna resultado, como mysql_fetch_assoc(), irá retornar esta linha.

`row_number` começa em 0. O `row_number` deve ser um valor no intervalo de 0 a mysql_num_rows() - 1. Entretanto, se o conjunto de resultados for vazio (mysql_num_rows() == 0), uma busca para 0 irá falhar com um `E_WARNING` e mysql_data_seek() iá retornar `false`.

### Parâmetros

`result`
  O resource do resultado que está sendo avaliado. Este resultado vem de uma chamada a mysql_query().
`row_number`
  O número de linha desejado para o ponteiro de resultado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo mysql_data_seek()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Não foi possível conectar: ' . mysql_error());
    }
    $db_selected = mysql_select_db('sample_db');
    if (!$db_selected) {
        die('Não foi possível selecionar o banco de dados: ' . mysql_error());
    }
    $query = 'SELECT last_name, first_name FROM friends';
    $result = mysql_query($query);
    if (!$result) {
        die('A consulta falhou: ' . mysql_error());
    }
    /* Busca linhas na ordem inversa */
    for ($i = mysql_num_rows($result) - 1; $i >= 0; $i--) {
        if (!mysql_data_seek($result, $i)) {
            echo "Não foi possível apontar para a linha $i: " . mysql_error() . "\n";
            continue;
        }

        if (!($row = mysql_fetch_assoc($result))) {
            continue;
        }

        echo $row['last_name'] . ' ' . $row['first_name'] . "<br />\n";
    }

    mysql_free_result($result);
    ?>

### Notas

> Nota: A função mysql_data_seek() pode ser usada apenas em conjunto com a função mysql_query(), não com mysql_unbuffered_query().

### Veja Também

- mysql_query() - Envia uma consulta MySQL
- mysql_num_rows() - Obtém o número de linhas em um resultado
- mysql_fetch_row() - Obtém uma linha como um array numérico
- mysql_fetch_assoc() - Obtém uma linha do resultado como um array associativo
- mysql_fetch_array() - Obtém uma linha de resultado como um array associativo, numérico, ou ambos
- mysql_fetch_object() - Obtém o resultado de uma linha como um objeto

# mysql_db_name

(PHP 4, PHP 5)

mysql_db_name — Obtém o nome do banco de dados a partir da chamada à mysql_list_dbs()

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- Query: `SELECT DATABASE()`

### Descrição

function mysql_db_name(resource `$result`, int `$row`, mixed `$field` = NULL): string

Obtém o nome do banco de dados a partir de uma chamada à mysql_list_dbs().

### Parâmetros

`result`
  O ponteiro de resultado de uma chamada à mysql_list_dbs().
`row`
  O índice dentro do conjunto de resultados.
`field`
  O nome do campo.

### Valor Retornado

Retorna o nome do banco de dados em caso de sucesso, e `false` em caso de falha. Se for retornado `false`, utilize mysql_error() para determinar a natureza do erro.

### Exemplos

Exemplo #1 Exemplo mysql_db_name()

    <?php
    error_reporting(E_ALL);

    $link = mysql_connect('dbhost', 'username', 'password');
    $db_list = mysql_list_dbs($link);

    $i = 0;
    $cnt = mysql_num_rows($db_list);
    while ($i < $cnt) {
        echo mysql_db_name($db_list, $i) . "\n";
        $i++;
    }
    ?>

### Notas

> Nota: Para compatibilidade com versões anteriores, o seguinte apelido descontinuado pode ser usado: mysql_dbname()

### Veja Também

- mysql_list_dbs() - Lista os bancos de dados disponíveis em um servidor MySQL
- mysql_tablename() - Obtém o nome da tabela do campo

# mysql_db_query

(PHP 4, PHP 5)

mysql_db_query — Seleciona um banco de dados e executa uma consulta nele

Aviso

Esta função foi descontinuada a partir do PHP 5.3.0 e ela e a extensão MySQL original foram removidas a partir do PHP 7.0.0. Em vez disso, use as extensões MySQLi ou PDO_MySQL, que são desenvolvidas ativamente. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_select_db() e depois a consulta
- PDO::__construct()

### Descrição

function mysql_db_query(string `$database`, string `$query`, resource `$link_identifier` = NULL): resource|bool

mysql_db_query() seleciona um banco de dados e executa uma consulta nele.

### Parâmetros

`database`
  O nome do banco de dados que será selecionado.
`query`
  A consulta MySQL. Os dados dentro da consulta devem estar adequadamente escapados.
`link_identifier`
  A conexão MySQL. Se o identificador da conexão não for especificado, a última conexão aberta por mysql_connect() será usada. Se não houver uma conexão anterior, haverá uma tentativa de criar uma como se mysql_connect() tivesse sido chamada sem argumentos. Se nenhuma conexão for encontrada ou estabelecida, um erro de nível `E_WARNING` será gerado.

### Valor Retornado

Retorna um recurso de resultado MySQL com o resultado da consulta, ou `false` em caso de erro. A função também retorna `true`/`false` para consultas `INSERT`/`UPDATE`/`DELETE` para indicar sucesso/falha.

### Exemplos

Exemplo #1 Exemplo alternativo de mysql_db_query()

    <?php

    if (!$link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password')) {
        echo 'Não foi possível conectar ao mysql';
        exit;
    }

    if (!mysql_select_db('mysql_dbname', $link)) {
        echo 'Não foi possível selecionar o banco de dados';
        exit;
    }

    $sql    = 'SELECT foo FROM bar WHERE id = 42';
    $result = mysql_query($sql, $link);

    if (!$result) {
        echo "Erro do banco de dados, não foi possível consultar o banco de dados\n";
        echo 'Erro MySQL: ' . mysql_error();
        exit;
    }

    while ($row = mysql_fetch_assoc($result)) {
        echo $row['foo'];
    }

    mysql_free_result($result);

    ?>

### Notas

> Nota: Deve-se ter atenção pois esta função NÃO muda de volta para o banco de dados que estava conectado anteriormente. Em outras palavras, esta função não pode ser usada executar temporariamente uma consulta SQL em outro banco de dados, o retorno ao banco anterior deve ser feito manualmente. É fortemente recomendado usar a sintaxe `bancodedados.tabela` nas consultas SQL ou mysql_select_db() ao invés desta função.

### Veja Também

- mysql_query() - Envia uma consulta MySQL
- mysql_select_db() - Seleciona um banco de dados MySQL

# mysql_drop_db

(PHP 4, PHP 5)

mysql_drop_db — Drop (exclui) um banco de dados MySQL

Aviso

Esta função foi descontinuada a partir do PHP 4.3.0 e ela e a extensão MySQL original foram removidas a partir do PHP 7.0.0. Em vez disso, use as extensões MySQLi ou PDO_MySQL, que são desenvolvidas ativamente. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- Executa um query `DROP DATABASE`

### Descrição

function mysql_drop_db(string `$database_name`, resource `$link_identifier` = NULL): bool

mysql_drop_db() tenta executar um drop (remover) todo um banco de dados do servidor associado ao identificador de conexão especificado. Esta função foi descontinuada, é preferível usar mysql_query() para realilar um comando `DROP DATABASE`.

### Parâmetros

`database_name`
  O nome do banco de dados que será excluído.
`link_identifier`
  A conexão MySQL. Se o identificador da conexão não for especificado, a última conexão aberta por mysql_connect() será usada. Se não houver uma conexão anterior, haverá uma tentativa de criar uma como se mysql_connect() tivesse sido chamada sem argumentos. Se nenhuma conexão for encontrada ou estabelecida, um erro de nível `E_WARNING` será gerado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo alternativo de mysql_drop_db()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Não foi possível conectar: ' . mysql_error());
    }

    $sql = 'DROP DATABASE my_db';
    if (mysql_query($sql, $link)) {
        echo "Banco de dados my_db foi excluído com sucesso\n";
    } else {
        echo 'Erro ao excluir o banco de dados: ' . mysql_error() . "\n";
    }
    ?>

### Notas

Aviso

Esta função não estará disponível se a extensão MySQL foi compilada com a versão da biblioteca de cliente MySQL 4.x.

> Nota: Para compatibilidade com versões anteriores, o seguinte apelido descontinuado pode ser usado: mysql_dropdb()

### Veja Também

- mysql_query() - Envia uma consulta MySQL

# mysql_errno

(PHP 4, PHP 5)

mysql_errno — Retorna o valor numérico da mensagem de erro da operação MySQL anterior

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_errno()
- PDO::errorCode()

### Descrição

function mysql_errno(resource `$link_identifier` = NULL): int

Retorna o número do erro da última função MySQL.

Erros vindos do banco de dados MySQL não geram mais avisos. Ao invés disso, use mysql_errno() para obter o código do erro. Note que esta função retorna o código apenas da função MySQL mais recentemente usada (não incluindo mysql_error() e mysql_errno()), assim se você quiser usá-la, tenha certeza de verificar o valor antes de executar outra função MySQL.

### Parâmetros

`link_identifier`
  A conexão MySQL. Se o identificador da conexão não for especificado, a última conexão aberta por mysql_connect() será usada. Se não houver uma conexão anterior, haverá uma tentativa de criar uma como se mysql_connect() tivesse sido chamada sem argumentos. Se nenhuma conexão for encontrada ou estabelecida, um erro de nível `E_WARNING` será gerado.

### Valor Retornado

Retorna o número de erro da última função MySQL, ou `0` (zero) se não houve erro.

### Exemplos

Exemplo #1 Exemplo mysql_errno()

    <?php
    $link = mysql_connect("localhost", "mysql_user", "mysql_password");

    if (!mysql_select_db("nonexistentdb", $link)) {
        echo mysql_errno($link) . ": " . mysql_error($link). "\n";
    }

    mysql_select_db("kossu", $link);
    if (!mysql_query("SELECT * FROM nonexistenttable", $link)) {
        echo mysql_errno($link) . ": " . mysql_error($link) . "\n";
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    1049: Unknown database 'nonexistentdb'
    1146: Table 'kossu.nonexistenttable' doesn't exist

### Veja Também

- mysql_error() - Retorna o texto da mensagem de erro da operação MySQL anterior
- » códigos de erro MySQL

# mysql_error

(PHP 4, PHP 5)

mysql_error — Retorna o texto da mensagem de erro da operação MySQL anterior

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_error()
- PDO::errorInfo()

### Descrição

function mysql_error(resource `$link_identifier` = NULL): string

Retorna o texto do último erro de funções MySQL. Erros vindos do banco de dados MySQL não geram mais avisos. Ao invés, use mysql_error() para obter o texto do erro. Note que esta função apenas retorna o texto do erro da função MySQL mais recentemente executada (não incluindo mysql_error() e mysql_errno()), assim se você quiser usa-la, tenha certeza de obter o valor antes de utilizar outra função MySQL.

### Parâmetros

`link_identifier`
  A conexão MySQL. Se o identificador da conexão não for especificado, a última conexão aberta por mysql_connect() será usada. Se não houver uma conexão anterior, haverá uma tentativa de criar uma como se mysql_connect() tivesse sido chamada sem argumentos. Se nenhuma conexão for encontrada ou estabelecida, um erro de nível `E_WARNING` será gerado.

### Valor Retornado

Retorna o texto do erro da ultima função MySQL, ou `''` (uma string vazia) se não houve erro.

### Exemplos

Exemplo #1 Exemplo mysql_error()

    <?php
    $link = mysql_connect("localhost", "mysql_user", "mysql_password");

    mysql_select_db("nonexistentdb", $link);
    echo mysql_errno($link) . ": " . mysql_error($link). "\n";

    mysql_select_db("kossu", $link);
    mysql_query("SELECT * FROM nonexistenttable", $link);
    echo mysql_errno($link) . ": " . mysql_error($link) . "\n";
    ?>

O exemplo acima produzirá algo semelhante a:

    1049: Unknown database 'nonexistentdb'
    1146: Table 'kossu.nonexistenttable' doesn't exist

### Veja Também

- mysql_errno() - Retorna o valor numérico da mensagem de erro da operação MySQL anterior
- » códigos de erro MySQL

# mysql_escape_string

(PHP 4 >= 4.0.3, PHP 5)

mysql_escape_string — Escapa uma string para usá-la em uma função mysql_query

Aviso

Esta função foi descontinuada a partir do PHP 4.3.0 e ela e a extensão MySQL original foram removidas a partir do PHP 7.0.0. Em vez disso, use as extensões MySQLi ou PDO_MySQL, que são desenvolvidas ativamente. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_escape_string()
- PDO::quote()

### Descrição

function mysql_escape_string(string `$unescaped_string`): string

Esta função escapará a string `unescaped_string`, de modo que seja seguro usá-la em uma função mysql_query(). Esta função foi descontinuada.

Esta função é idêntica à mysql_real_escape_string() exceto que mysql_real_escape_string() recebe um manipulador de conexão e escapa a string de acordo com o conjunto de caracteres atual. mysql_escape_string() não recebe um manipulador de conexão e não respeita a configuração atual do conjunto de caracteres.

### Parâmetros

`unescaped_string`
  A string que deve ser escapada.

### Valor Retornado

Retorna a string escapada.

### Exemplos

Exemplo #1 Exemplo de mysql_escape_string()

    <?php
    $item = "Zak's Laptop";
    $escaped_item = mysql_escape_string($item);
    printf("String escapada: %s\n", $escaped_item);
    ?>

O exemplo acima produzirá:

    String escapada: Zak\'s Laptop

### Notas

> Nota: mysql_escape_string() não escapa `%` e `_`.

### Veja Também

- mysql_real_escape_string() - Escapa os caracteres especiais em uma string para uso em uma instrução SQL

# mysql_fetch_array

(PHP 4, PHP 5)

mysql_fetch_array — Obtém uma linha de resultado como um array associativo, numérico, ou ambos

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_fetch_array()
- PDOStatement::fetch()

### Descrição

function mysql_fetch_array(resource `$result`, int `$result_type` = MYSQL_BOTH): array

Retorna um array que corresponde à linha obtida e move adiante o ponteiro interno dos dados.

### Parâmetros

`result`
  O resource do resultado que está sendo avaliado. Este resultado vem de uma chamada a mysql_query().
`result_type`
  O tipo de array que deve ser obtido. É uma constante e aceita os seguintes valores: `MYSQL_ASSOC`, `MYSQL_NUM` e `MYSQL_BOTH`.

### Valor Retornado

Retorna um array que corresponde à linha obtida ou `false` se não houver mais linhas. O tipo da array retornado depende de como `result_type` estiver definido. Usando `MYSQL_BOTH` (padrão), será obtido um array com ambos os índices, numérico e associativo. Usando `MYSQL_ASSOC`, somente índices associativos serão obtidos (da mesma forma que mysql_fetch_assoc() funciona), e usando `MYSQL_NUM`, somente os índices numéricos (como mysql_fetch_row() funciona).

Se duas ou mais colunas do resultado tiverem os mesmos nomes de campos, a última coluna terá precedência. Para acessar a(s) outra(s) coluna(s) de mesmo nome, o índice numérico da coluna deve ser usado ou um apelido para a coluna deve ser especificado. Para colunas com apelidos, o conteúdo não poderá ser acessado com o nome original da coluna.

### Exemplos

Exemplo #1 Consulta com nomes de campos duplicados usando apelidos

    SELECT table1.field AS foo, table2.field AS bar FROM table1, table2

Exemplo #2 mysql_fetch_array() com `MYSQL_NUM`

    <?php
    mysql_connect("localhost", "mysql_user", "mysql_password") or
        die("Não foi possível conectar: " . mysql_error());
    mysql_select_db("mydb");

    $result = mysql_query("SELECT id, name FROM mytable");

    while ($row = mysql_fetch_array($result, MYSQL_NUM)) {
        printf("ID: %s  Nome: %s", $row[0], $row[1]);
    }

    mysql_free_result($result);
    ?>

Exemplo #3 mysql_fetch_array() com `MYSQL_ASSOC`

    <?php
    mysql_connect("localhost", "mysql_user", "mysql_password") or
        die("Não foi possível conectar: " . mysql_error());
    mysql_select_db("mydb");

    $result = mysql_query("SELECT id, name FROM mytable");

    while ($row = mysql_fetch_array($result, MYSQL_ASSOC)) {
        printf("ID: %s  Nome: %s", $row["id"], $row["name"]);
    }

    mysql_free_result($result);
    ?>

Exemplo #4 mysql_fetch_array() com `MYSQL_BOTH`

    <?php
    mysql_connect("localhost", "mysql_user", "mysql_password") or
        die("Não foi possível conectar: " . mysql_error());
    mysql_select_db("mydb");

    $result = mysql_query("SELECT id, name FROM mytable");

    while ($row = mysql_fetch_array($result, MYSQL_BOTH)) {
        printf ("ID: %s  Nome: %s", $row[0], $row["name"]);
    }

    mysql_free_result($result);
    ?>

### Notas

> Nota: Desempenho
> É importante observar que mysql_fetch_array() não é significativamente mais lento do que mysql_fetch_row(), enquanto que a primeira fornece um valor agregado significativo.

> Nota: Os nomes de campos retornados por esta função diferenciam maiúsculas e minúsculas.

> Nota: Esta função define campos NULL como o valor `null` do PHP.

### Veja Também

- mysql_fetch_row() - Obtém uma linha como um array numérico
- mysql_fetch_assoc() - Obtém uma linha do resultado como um array associativo
- mysql_data_seek() - Move o ponteiro interno do resultado
- mysql_query() - Envia uma consulta MySQL

# mysql_fetch_assoc

(PHP 4 >= 4.0.3, PHP 5)

mysql_fetch_assoc — Obtém uma linha do resultado como um array associativo

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_fetch_assoc()
- PDOStatement::fetch() com `mode` como `PDO::FETCH_ASSOC`

### Descrição

function mysql_fetch_assoc(resource `$result`): array

Retorna um array associativo que corresponde a linha obtida e move o ponteiro interno dos dados adiante. mysql_fetch_assoc() é equivalente a utilizar mysql_fetch_array() com MYSQL_ASSOC para o segunto parâmetro, que é opcional. Ela apenas retorna um array associativo.

### Parâmetros

`result`
  O resource do resultado que está sendo avaliado. Este resultado vem de uma chamada a mysql_query().

### Valor Retornado

Retorna um array associativo de strings que corresponde à linha obtida, ou `false` se não houver mais linhas.

Se duas ou mais colunas do resultado tiverem o mesmo nome de campo, a ultima coluna terá precedencia. Para acessar as outras colunas com o mesmo nome, é necessário acessar os outros resultados usando índices numéricos com mysql_fetch_row() ou adicionar apelidos. Veja o exemplo em mysql_fetch_array() para uma descrição sobre apelidos.

### Exemplos

Exemplo #1 Um exemplo expandido de mysql_fetch_assoc()

    <?php

    $conn = mysql_connect("localhost", "mysql_user", "mysql_password");

    if (!$conn) {
        echo "Não foi possível conectar ao DB: " . mysql_error();
        exit;
    }

    if (!mysql_select_db("mydbname")) {
        echo "Não foi possível selecionar mydbname: " . mysql_error();
        exit;
    }

    $sql = "SELECT id as userid, fullname, userstatus
            FROM   sometable
            WHERE  userstatus = 1";

    $result = mysql_query($sql);

    if (!$result) {
        echo "Não foi possível executar a consulta ($sql) no DB: " . mysql_error();
        exit;
    }

    if (mysql_num_rows($result) == 0) {
        echo "Nenhuma linha encontrada, nada para exibir, saindo...";
        exit;
    }

    // Enquanto uma linha de dados existir, coloque essa linha em $row como um array associativo
    // Observação: Se for esperada apenas uma linha, não é necessário usar um loop
    // Observação: Se for colocado extract($row); dentro do loop a seguir, serão
    // criados $userid, $fullname e $userstatus
    while ($row = mysql_fetch_assoc($result)) {
        echo $row["userid"];
        echo $row["fullname"];
        echo $row["userstatus"];
    }

    mysql_free_result($result);

    ?>

### Notas

> Nota: Performance
> Uma coisa importante para notar é que usar mysql_fetch_assoc() não é significativamente mais lento do que usar mysql_fetch_row(), enquanto provê um valor agregado significante.

> Nota: Os nomes de campos retornados por esta função diferenciam maiúsculas e minúsculas.

> Nota: Esta função define campos NULL como o valor `null` do PHP.

### Veja Também

- mysql_fetch_row() - Obtém uma linha como um array numérico
- mysql_fetch_array() - Obtém uma linha de resultado como um array associativo, numérico, ou ambos
- mysql_data_seek() - Move o ponteiro interno do resultado
- mysql_query() - Envia uma consulta MySQL
- mysql_error() - Retorna o texto da mensagem de erro da operação MySQL anterior

# mysql_fetch_field

(PHP 4, PHP 5)

mysql_fetch_field — Obtém informações de coluna de um resultado e retorna como um objeto

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_fetch_field()
- PDOStatement::getColumnMeta()

### Descrição

function mysql_fetch_field(resource `$result`, int `$field_offset` = 0): object

Retorna um objeto contendo informações sobre campo. Esta função pode ser usada para obter informações sobre campos no resultado de consulta informado.

### Parâmetros

`result`
  O resource do resultado que está sendo avaliado. Este resultado vem de uma chamada a mysql_query().
`field_offset`
  O índice numérico do campo. Se o índice não for especificado, o próximo campo que ainda não tenha sido obtido por esta função é recuperado. `field_offset` inicia em `0`.

### Valor Retornado

Retorna um object contendo informação sobre o campo. As propriedades do objeto são:

- name - nome da coluna
- table - a tabela à qual o objeto pertence, que é o nome do apelido se um estiver definido
- max_length - comprimento máximo da coluna
- not_null - 1 se a coluna não puder ser `null`
- primary_key - 1 se a coluna for uma chave primária
- unique_key - 1 se a coluna for uma chave exclusiva
- multiple_key - 1 se a coluna for uma chave não-exclusiva
- numeric - 1 se a coluna for numérica
- blob - 1 se a coluna for um BLOB
- type - o tipo da coluna
- unsigned - 1 se a coluna for sem sinal
- zerofill - 1 se a coluna for prenchida com zero

### Exemplos

Exemplo #1 Exemplo de mysql_fetch_field()

    <?php
    $conn = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$conn) {
        die('Não foi possível conectar: ' . mysql_error());
    }
    mysql_select_db('database');
    $result = mysql_query('select * from table');
    if (!$result) {
        die('A consulta falhou: ' . mysql_error());
    }
    /* Obtém as informações da coluna */
    $i = 0;
    while ($i < mysql_num_fields($result)) {
        echo "Informação para a coluna $i:<br />\n";
        $meta = mysql_fetch_field($result, $i);
        if (!$meta) {
            echo "Sem informação disponível<br />\n";
        }
        echo "<pre>
    blob:         $meta->blob
    max_length:   $meta->max_length
    multiple_key: $meta->multiple_key
    name:         $meta->name
    not_null:     $meta->not_null
    numeric:      $meta->numeric
    primary_key:  $meta->primary_key
    table:        $meta->table
    type:         $meta->type
    unique_key:   $meta->unique_key
    unsigned:     $meta->unsigned
    zerofill:     $meta->zerofill
    </pre>";
        $i++;
    }
    mysql_free_result($result);
    ?>

### Notas

> Nota: Os nomes de campos retornados por esta função diferenciam maiúsculas e minúsculas.

> Nota: Se campos ou nomes de tabelas forem apelidados na consulta SQL, o nome do apelido será retornado. O nome original pode ser recuperado, por exemplo, usando mysqli_result::fetch_field().

### Veja Também

- mysql_field_seek() - Define o ponteiro do resultado para o índice de campo especificado

# mysql_fetch_lengths

(PHP 4, PHP 5)

mysql_fetch_lengths — Obtém o tamanho de cada saída de um resultado

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_fetch_lengths()
- PDOStatement::getColumnMeta()

### Descrição

function mysql_fetch_lengths(resource `$result`): array|false

Retorna um array que corresponde aos tamanhos de cada campo na ultima linha obtida pelo MySQL.

mysql_fetch_lengths() guarda o tamanho de cada coluna do resultado na última linha retornada por mysql_fetch_row(), mysql_fetch_assoc(), mysql_fetch_array(), e mysql_fetch_object() em um array, começando no índice 0.

### Parâmetros

`result`
  O resource do resultado que está sendo avaliado. Este resultado vem de uma chamada a mysql_query().

### Valor Retornado

Um array de tamanhos em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo mysql_fetch_lengths()

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
        echo 'Não foi possível executar a consulta: ' . mysql_error();
        exit;
    }
    $row     = mysql_fetch_assoc($result);
    $lengths = mysql_fetch_lengths($result);

    print_r($row);
    print_r($lengths);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [id] => 42
        [email] => user@example.com
    )
    Array
    (
        [0] => 2
        [1] => 16
    )

### Veja Também

- mysql_field_len() - Retorna o tamanho do campo especificado
- mysql_fetch_row() - Obtém uma linha como um array numérico
- strlen() - Retorna o tamanho de uma string

# mysql_fetch_object

(PHP 4, PHP 5)

mysql_fetch_object — Obtém o resultado de uma linha como um objeto

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_fetch_object()
- PDOStatement::fetch() com `mode` como `PDO::FETCH_OBJ`

### Descrição

function mysql_fetch_object(resource `$result`, string `$class_name` = ?, array `$params` = ?): object

Retorna um objeto com propriedades que correspondem a linha obtida e move o ponteiro interno dos dados adiante.

### Parâmetros

`result`
  O resource do resultado que está sendo avaliado. Este resultado vem de uma chamada a mysql_query().
`class_name`
  O nome de classe para instanciar, definir as propriedades e retornar. Se não for especificado, um objeto stdClass é retornado.
`params`
  Um array opcional de parâmetros para passar para o construtor do objeto `class_name`.

### Valor Retornado

Retorna um object com propriedades strings que correspondem a linha obtida, ou `false` se não houverem mais linhas.

### Exemplos

Exemplo #1 Exemplo mysql_fetch_object()

    <?php
    mysql_connect("hostname", "user", "password");
    mysql_select_db("mydb");
    $result = mysql_query("select * from mytable");
    while ($row = mysql_fetch_object($result)) {
        echo $row->user_id;
        echo $row->fullname;
    }
    mysql_free_result($result);
    ?>

Exemplo #2 Exemplo mysql_fetch_object()

    <?php
    class foo {
        public $name;
    }

    mysql_connect("hostname", "user", "password");
    mysql_select_db("mydb");

    $result = mysql_query("select name from mytable limit 1");
    $obj = mysql_fetch_object($result, 'foo');
    var_dump($obj);
    ?>

### Notas

> Nota: Performance
> Em termos de velocidade, a função é idêntica à mysql_fetch_array(), e quase tão rápida quanto mysql_fetch_row() (a diferença é insignificante).

> Nota: mysql_fetch_object() é similar a mysql_fetch_array(), com uma diferença - um objeto é retornado, ao invés de um array. Indiretamente, isto significa que você pode acessar os dados apenas pelo nome dos campos, e não por seus índices (números são ilegais como nomes de propriedades).

> Nota: Os nomes de campos retornados por esta função diferenciam maiúsculas e minúsculas.

> Nota: Esta função define campos NULL como o valor `null` do PHP.

### Veja Também

- mysql_fetch_array() - Obtém uma linha de resultado como um array associativo, numérico, ou ambos
- mysql_fetch_assoc() - Obtém uma linha do resultado como um array associativo
- mysql_fetch_row() - Obtém uma linha como um array numérico
- mysql_data_seek() - Move o ponteiro interno do resultado
- mysql_query() - Envia uma consulta MySQL

# mysql_fetch_row

(PHP 4, PHP 5)

mysql_fetch_row — Obtém uma linha como um array numérico

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_fetch_row()
- PDOStatement::fetch() com `mode` como `PDO::FETCH_NUM`

### Descrição

function mysql_fetch_row(resource `$result`): array

Retorna um array numérico que corresponde a linha obtida e move o ponteiro interno dos dados adiante.

### Parâmetros

`result`
  O resource do resultado que está sendo avaliado. Este resultado vem de uma chamada a mysql_query().

### Valor Retornado

Retorna um array numérico de strings que corresponde linha obtida, ou `false` se não houverem mais linhas.

mysql_fetch_row() obtém uma linha de dados do resultado associado ao identificador do resultado especificado. A linha é retornada como um array. Cada coluna do resultado é armazenado em um índice do array, começando no índice 0.

### Exemplos

Exemplo #1 Obtendo uma linha com mysql_fetch_row()

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
        echo 'Não foi possível executar a consulta: ' . mysql_error();
        exit;
    }
    $row = mysql_fetch_row($result);

    echo $row[0]; // 42
    echo $row[1]; // o valor do campo email
    ?>

### Notas

> Nota: Esta função define campos NULL como o valor `null` do PHP.

### Veja Também

- mysql_fetch_array() - Obtém uma linha de resultado como um array associativo, numérico, ou ambos
- mysql_fetch_assoc() - Obtém uma linha do resultado como um array associativo
- mysql_fetch_object() - Obtém o resultado de uma linha como um objeto
- mysql_data_seek() - Move o ponteiro interno do resultado
- mysql_fetch_lengths() - Obtém o tamanho de cada saída de um resultado
- mysql_result() - Retorna dados do resultado

# mysql_field_flags

(PHP 4, PHP 5)

mysql_field_flags — Obtém as opções associadas ao campo especificado em um resultado

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_fetch_field_direct() [opções]
- PDOStatement::getColumnMeta() [opções]

### Descrição

function mysql_field_flags(resource `$result`, int `$field_offset`): string|false

mysql_field_flags() retorna as opções do campo especificado. As opções são mostradas como uma única palavra por opção separada por um único espaço, de forma a permitir a divisão do valor retornado com o uso da função explode().

### Parâmetros

`result`
  O resource do resultado que está sendo avaliado. Este resultado vem de uma chamada a mysql_query().
`field_offset`
  O deslocamento numérico do campo. `field_offset` começa em `0`. Se `field_offset` não existir, um erro de nível `E_WARNING` também será emitido.

### Valor Retornado

Retorna uma string com as opções associadas ao resultado ou `false` em caso de falha.

As seguintes opções são reportadas, se a versão do MySQL for atual o suficiente para suportá-las: `"not_null"`, `"primary_key"`, `"unique_key"`, `"multiple_key"`, `"blob"`, `"unsigned"`, `"zerofill"`, `"binary"`, `"enum"`, `"auto_increment"` e `"timestamp"`.

### Exemplos

Exemplo #1 Um exemplo de mysql_field_flags()

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
        echo 'Não foi possível executar a consulta: ' . mysql_error();
        exit;
    }
    $flags = mysql_field_flags($result, 0);

    echo $flags;
    print_r(explode(' ', $flags));
    ?>

O exemplo acima produzirá algo semelhante a:

    not_null primary_key auto_increment
    Array
    (
        [0] => not_null
        [1] => primary_key
        [2] => auto_increment
    )

### Notas

> Nota: Para compatibilidade com versões anteriores, o seguinte apelido descontinuado pode ser usado: mysql_fieldflags()

### Veja Também

- mysql_field_type() - Obtém o tipo do campo especificado em um resultado
- mysql_field_len() - Retorna o tamanho do campo especificado

# mysql_field_len

(PHP 4, PHP 5)

mysql_field_len — Retorna o tamanho do campo especificado

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_fetch_field_direct() [length]
- PDOStatement::getColumnMeta() [len]

### Descrição

function mysql_field_len(resource `$result`, int `$field_offset`): int|false

mysql_field_len() retorna o tamanho do campo especificado.

### Parâmetros

`result`
  O resource do resultado que está sendo avaliado. Este resultado vem de uma chamada a mysql_query().
`field_offset`
  O deslocamento numérico do campo. `field_offset` começa em `0`. Se `field_offset` não existir, um erro de nível `E_WARNING` também será emitido.

### Valor Retornado

O tamanho do campo especificado em sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de mysql_field_len()

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
        echo 'Não foi possível executar a consulta: ' . mysql_error();
        exit;
    }

    // Obtendo o comprimento do campo 'id' como especificado no
    // esquema do banco de dados.
    $length = mysql_field_len($result, 0);
    echo $length;
    ?>

### Notas

> Nota: Para compatibilidade com versões anteriores, o seguinte apelido descontinuado pode ser usado: mysql_fieldlen()

### Veja Também

- mysql_fetch_lengths() - Obtém o tamanho de cada saída de um resultado
- strlen() - Retorna o tamanho de uma string

# mysql_field_name

(PHP 4, PHP 5)

mysql_field_name — Obtém o nome do campo especificado em um resultado

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_fetch_field_direct() [name] ou [orgname]
- PDOStatement::getColumnMeta() [name]

### Descrição

function mysql_field_name(resource `$result`, int `$field_offset`): string|false

mysql_field_name() retorna o nome do campo do índice especificado.

### Parâmetros

`result`
  O resource do resultado que está sendo avaliado. Este resultado vem de uma chamada a mysql_query().
`field_offset`
  O deslocamento numérico do campo. `field_offset` começa em `0`. Se `field_offset` não existir, um erro de nível `E_WARNING` também será emitido.

### Valor Retornado

O nome do campo do índice especificado emj caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo mysql_field_name()

    <?php
    /* A tabela users consiste em três campos:
     *   user_id
     *   username
     *   password.
     */
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Não foi possível conectar ao servidor MySQL: ' . mysql_error());
    }
    $dbname = 'mydb';
    $db_selected = mysql_select_db($dbname, $link);
    if (!$db_selected) {
        die("Não foi possível selecionar $dbname: " . mysql_error());
    }
    $res = mysql_query('select * from users', $link);

    echo mysql_field_name($res, 0) . "\n";
    echo mysql_field_name($res, 2);
    ?>

O exemplo acima produzirá:

    user_id
    password

### Notas

> Nota: Os nomes de campos retornados por esta função diferenciam maiúsculas e minúsculas.

> Nota: Para compatibilidade com versões anteriores, o seguinte apelido descontinuado pode ser usado: mysql_fieldname()

### Veja Também

- mysql_field_type() - Obtém o tipo do campo especificado em um resultado
- mysql_field_len() - Retorna o tamanho do campo especificado

# mysql_field_seek

(PHP 4, PHP 5)

mysql_field_seek — Define o ponteiro do resultado para o índice de campo especificado

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_field_seek()
- PDOStatement::fetch() usando os parâmetros `cursor_orientation` e `offset`

### Descrição

function mysql_field_seek(resource `$result`, int `$field_offset`): bool

Move para o índice do campo especificado. Se a próxima chamada a mysql_fetch_field() não incluir um índice, o índice de campo especificado em mysql_field_seek() será retornado.

### Parâmetros

`result`
  O resource do resultado que está sendo avaliado. Este resultado vem de uma chamada a mysql_query().
`field_offset`
  O deslocamento numérico do campo. `field_offset` começa em `0`. Se `field_offset` não existir, um erro de nível `E_WARNING` também será emitido.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- mysql_fetch_field() - Obtém informações de coluna de um resultado e retorna como um objeto

# mysql_field_table

(PHP 4, PHP 5)

mysql_field_table — Obtém o nome da tabela na qual o campo especificado esta

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_fetch_field_direct() [table] ou [orgtable]
- PDOStatement::getColumnMeta() [table]

### Descrição

function mysql_field_table(resource `$result`, int `$field_offset`): string

Retorna o nome da tabela na qual o campo especificado está.

### Parâmetros

`result`
  O resource do resultado que está sendo avaliado. Este resultado vem de uma chamada a mysql_query().
`field_offset`
  O deslocamento numérico do campo. `field_offset` começa em `0`. Se `field_offset` não existir, um erro de nível `E_WARNING` também será emitido.

### Valor Retornado

O nome da tabela em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de mysql_field_table()

    <?php

    $query = "SELECT account.*, country.* FROM account, country WHERE country.name = 'Portugal' AND account.country_id = country.id";

    // obtém resultado do banco de dados
    $result = mysql_query($query);

    // Lista o nome da tabela e depois o nome do campo
    for ($i = 0; $i < mysql_num_fields($result); ++$i) {
        $table = mysql_field_table($result, $i);
        $field = mysql_field_name($result, $i);

        echo  "$table: $field\n";
    }

    ?>

### Notas

> Nota: Para compatibilidade com versões anteriores, o seguinte apelido descontinuado pode ser usado: mysql_fieldtable()

### Veja Também

- mysql_list_tables() - Lista as tabelas em um banco de dados MySQL

# mysql_field_type

(PHP 4, PHP 5)

mysql_field_type — Obtém o tipo do campo especificado em um resultado

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_fetch_field_direct() [type]
- PDOStatement::getColumnMeta() [driver:decl_type] ou [pdo_type]

### Descrição

function mysql_field_type(resource `$result`, int `$field_offset`): string

mysql_field_type() é similar a função mysql_field_name(). Os argumentos são idênticos, mas é o tipo do campo que é retornado.

### Parâmetros

`result`
  O resource do resultado que está sendo avaliado. Este resultado vem de uma chamada a mysql_query().
`field_offset`
  O deslocamento numérico do campo. `field_offset` começa em `0`. Se `field_offset` não existir, um erro de nível `E_WARNING` também será emitido.

### Valor Retornado

O tipo de campo retornado será um de `"int"`, `"real"`, `"string"`, `"blob"` e outros como detalhado na » documentação do MySQL.

### Exemplos

Exemplo #1 Exemplo de mysql_field_type()

    <?php
    mysql_connect("localhost", "mysql_username", "mysql_password");
    mysql_select_db("mysql");
    $result = mysql_query("SELECT * FROM func");
    $fields = mysql_num_fields($result);
    $rows   = mysql_num_rows($result);
    $table  = mysql_field_table($result, 0);
    echo "Sua tabela '" . $table . "' tem " . $fields . " campos e " . $rows . " registro(s)\n";
    echo "A tabela tem os seguintes campos:\n";
    for ($i=0; $i < $fields; $i++) {
        $type  = mysql_field_type($result, $i);
        $name  = mysql_field_name($result, $i);
        $len   = mysql_field_len($result, $i);
        $flags = mysql_field_flags($result, $i);
        echo $type . " " . $name . " " . $len . " " . $flags . "\n";
    }
    mysql_free_result($result);
    mysql_close();
    ?>

O exemplo acima produzirá algo semelhante a:

    Sua tabela 'func' tem 4 campos e 1 registro(s)
    A tabela tem os seguintes campos:
    string name 64 not_null primary_key binary
    int ret 1 not_null
    string dl 128 not_null
    string type 9 not_null enum

### Notas

> Nota: Para compatibilidade com versões anteriores, o seguinte apelido descontinuado pode ser usado: mysql_fieldtype()

### Veja Também

- mysql_field_name() - Obtém o nome do campo especificado em um resultado
- mysql_field_len() - Retorna o tamanho do campo especificado

# mysql_free_result

(PHP 4, PHP 5)

mysql_free_result — Libera memória usada pelo resultado

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_free_result()
- Atribuir o valor `null` ao objeto PDO ou PDOStatement::closeCursor()

### Descrição

function mysql_free_result(resource `$result`): bool

mysql_free_result() liberará toda a memória associada ao identificador de resultado `result`.

mysql_free_result() apenas precisa ser chamada se houver preocupação sobre a quantidade de memória usada em consultas que retornam grandes conjuntos de resultados. Toda a memória associada ao resultado é liberada automaticamente no final da execução do script.

### Parâmetros

`result`
  O resource do resultado que está sendo avaliado. Este resultado vem de uma chamada a mysql_query().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

Se for usado algo que não seja um recurso para o parâmetro `result`, um erro de nível E_WARNING será emitido. É importante observar que mysql_query() somente retorna um resource para consultas SELECT, SHOW, EXPLAIN e DESCRIBE.

### Exemplos

Exemplo #1 Um exemplo de mysql_free_result()

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
        echo 'Não foi possível executar a consulta: ' . mysql_error();
        exit;
    }
    /* Usa o resultado assumindo que não vamos precisar mais dele depois */
    $row = mysql_fetch_assoc($result);

    /* Agora a memória do resultado é liberada e a execução do script continua */
    mysql_free_result($result);

    echo $row['id'];
    echo $row['email'];
    ?>

### Notas

> Nota: Para compatibilidade com versões anteriores, o seguinte apelido descontinuado pode ser usado: mysql_freeresult()

### Veja Também

- mysql_query() - Envia uma consulta MySQL
- is_resource() - Verifica se uma variável é um recurso

# mysql_get_client_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_client_info — Obtém informações do cliente MySQL

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_get_client_info()
- PDO::getAttribute() com `attribute` como `PDO::ATTR_CLIENT_VERSION`

### Descrição

function mysql_get_client_info(): string

mysql_get_client_info() retorna uma string que representa a versão da biblioteca do cliente.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

A versão do cliente MySQL.

### Exemplos

Exemplo #1 Exemplo mysql_get_client_info()

    <?php
    printf("MySQL client info: %s\n", mysql_get_client_info());
    ?>

O exemplo acima produzirá algo semelhante a:

    MySQL client info: 3.23.39

### Veja Também

- mysql_get_host_info() - Obtém informações do servidor MySQL
- mysql_get_proto_info() - Obtém informações do protocolo MySQL
- mysql_get_server_info() - Obtém informações do servidor MySQL

# mysql_get_host_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_host_info — Obtém informações do servidor MySQL

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_get_host_info()
- PDO::getAttribute() com `attribute` como `PDO::ATTR_CONNECTION_STATUS`

### Descrição

function mysql_get_host_info(resource `$link_identifier` = NULL): string|false

Descreve o tipo de conexão em uso para a conexão, incluindo o nome do servidor.

### Parâmetros

`link_identifier`
  A conexão MySQL. Se o identificador da conexão não for especificado, a última conexão aberta por mysql_connect() será usada. Se não houver uma conexão anterior, haverá uma tentativa de criar uma como se mysql_connect() tivesse sido chamada sem argumentos. Se nenhuma conexão for encontrada ou estabelecida, um erro de nível `E_WARNING` será gerado.

### Valor Retornado

Retorna uma string descrevendo o tipo da conexão MySQL em uso para a conexão ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo mysql_get_host_info()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Não foi possível conectar: ' . mysql_error());
    }
    printf("MySQL host info: %s\n", mysql_get_host_info());
    ?>

O exemplo acima produzirá algo semelhante a:

    MySQL host info: Localhost via UNIX socket

### Veja Também

- mysql_get_client_info() - Obtém informações do cliente MySQL
- mysql_get_proto_info() - Obtém informações do protocolo MySQL
- mysql_get_server_info() - Obtém informações do servidor MySQL

# mysql_get_proto_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_proto_info — Obtém informações do protocolo MySQL

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_get_proto_info()

### Descrição

function mysql_get_proto_info(resource `$link_identifier` = NULL): int|false

Obtém o protocolo MySQL.

### Parâmetros

`link_identifier`
  A conexão MySQL. Se o identificador da conexão não for especificado, a última conexão aberta por mysql_connect() será usada. Se não houver uma conexão anterior, haverá uma tentativa de criar uma como se mysql_connect() tivesse sido chamada sem argumentos. Se nenhuma conexão for encontrada ou estabelecida, um erro de nível `E_WARNING` será gerado.

### Valor Retornado

Retorna o protocolo MySQL em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo mysql_get_proto_info()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Não foi possível conectar: ' . mysql_error());
    }
    printf("MySQL protocol version: %s\n", mysql_get_proto_info());
    ?>

O exemplo acima produzirá algo semelhante a:

    MySQL protocol version: 10

### Veja Também

- mysql_get_client_info() - Obtém informações do cliente MySQL
- mysql_get_host_info() - Obtém informações do servidor MySQL
- mysql_get_server_info() - Obtém informações do servidor MySQL

# mysql_get_server_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_server_info — Obtém informações do servidor MySQL

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_get_server_info()
- PDO::getAttribute() com `attribute` como `PDO::ATTR_SERVER_VERSION`

### Descrição

function mysql_get_server_info(resource `$link_identifier` = NULL): string|false

Obtém a versão do servidor MySQL.

### Parâmetros

`link_identifier`
  A conexão MySQL. Se o identificador da conexão não for especificado, a última conexão aberta por mysql_connect() será usada. Se não houver uma conexão anterior, haverá uma tentativa de criar uma como se mysql_connect() tivesse sido chamada sem argumentos. Se nenhuma conexão for encontrada ou estabelecida, um erro de nível `E_WARNING` será gerado.

### Valor Retornado

Retorna a versão do servidor MySQL em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo mysql_get_server_info()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Não foi possível conectar: ' . mysql_error());
    }
    printf("Versão do servidor MySQL: %s\n", mysql_get_server_info());
    ?>

O exemplo acima produzirá algo semelhante a:

    Versão do servidor MySQL: 4.0.1-alpha

### Veja Também

- mysql_get_client_info() - Obtém informações do cliente MySQL
- mysql_get_host_info() - Obtém informações do servidor MySQL
- mysql_get_proto_info() - Obtém informações do protocolo MySQL
- phpversion() - Obtém a versão atual do PHP

# mysql_info

(PHP 4 >= 4.3.0, PHP 5)

mysql_info — Obtém informação sobre a consulta mais recente

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_info()

### Descrição

function mysql_info(resource `$link_identifier` = NULL): string

Retorna informação detalhada sobre a última consulta.

### Parâmetros

`link_identifier`
  A conexão MySQL. Se o identificador da conexão não for especificado, a última conexão aberta por mysql_connect() será usada. Se não houver uma conexão anterior, haverá uma tentativa de criar uma como se mysql_connect() tivesse sido chamada sem argumentos. Se nenhuma conexão for encontrada ou estabelecida, um erro de nível `E_WARNING` será gerado.

### Valor Retornado

Retorna informação sobre o comando em caso de sucesso, ou `false` em caso de falha. Confira o exemplo abaixo para ver quais comandos disponibilizam a informação e qual pode ser o valor retornado. Comandos que não estão listados irão retornar `false`.

### Exemplos

Exemplo #1 Comandos MySQL relevantes

Comandos que retornam valores de string. Os números são apenas para proposito de ilustração; seus valores irão corresponder à consulta.

    INSERT INTO ... SELECT ...
    String format: Records: 23 Duplicates: 0 Warnings: 0
    INSERT INTO ... VALUES (...),(...),(...)...
    String format: Records: 37 Duplicates: 0 Warnings: 0
    LOAD DATA INFILE ...
    String format: Records: 42 Deleted: 0 Skipped: 0 Warnings: 0
    ALTER TABLE
    String format: Records: 60 Duplicates: 0 Warnings: 0
    UPDATE
    String format: Rows matched: 65 Changed: 65 Warnings: 0

### Notas

> Nota: mysql_info() retornará um valor diferente de `false` para comandos INSERT ... VALUES apenas se múltiplas listas de valores forem especificadas no comando.

### Veja Também

- mysql_affected_rows() - Obtém o número de linhas afetadas na operação anterior do MySQL
- mysql_insert_id() - Obtém o ID gerado pela operação INSERT anterior
- mysql_stat() - Obtém o status atual do sistema

# mysql_insert_id

(PHP 4, PHP 5)

mysql_insert_id — Obtém o ID gerado pela operação INSERT anterior

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_insert_id()
- PDO::lastInsertId()

### Descrição

function mysql_insert_id(resource `$link_identifier` = NULL): int

Obtém o ID gerado para uma coluna AUTO_INCREMENT pela consulta anterior (normalmente INSERT).

### Parâmetros

`link_identifier`
  A conexão MySQL. Se o identificador da conexão não for especificado, a última conexão aberta por mysql_connect() será usada. Se não houver uma conexão anterior, haverá uma tentativa de criar uma como se mysql_connect() tivesse sido chamada sem argumentos. Se nenhuma conexão for encontrada ou estabelecida, um erro de nível `E_WARNING` será gerado.

### Valor Retornado

O ID gerado para uma coluna AUTO_INCREMENT pela consulta anterior em caso de sucesso, `0` se a consulta anterior não gerou um valor AUTO_INCREMENT, ou `false` se não foi estabelecido conexão com o MySQL.

### Exemplos

Exemplo #1 Exemplo mysql_insert_id()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Não foi possível conectar: ' . mysql_error());
    }
    mysql_select_db('mydb');

    mysql_query("INSERT INTO mytable (product) values ('kossu')");
    printf("Last inserted record has id %d\n", mysql_insert_id());
    ?>

### Notas

Cuidado

mysql_insert_id() irá converter o tipo de retorno da API nativa em C do MySQL `mysql_insert_id()` para um tipo `long` (chamado int no PHP). Se a sua coluna AUTO_INCREMENT for uma coluna do tipo BIGINT (64 bits), a conversão pode resultar em um valor incorreto. Ao invés disto, use a função LAST_INSERT_ID() interna do MySQL em uma consulta SQL. Para mais informações sobre valores máximos de inteiros do PHP, visite a documentação integer.

> Nota: Devido mysql_insert_id() agir sobre a última consulta realizada, tenha certeza de chamar mysql_insert_id() imediatamente após a consulta que gerou o valor.

> Nota: O valor da função SQL do MySQL `LAST_INSERT_ID()` sempre contém o valor AUTO_INCREMENT mais recentemente gerado e não é reiniciado entre as consultas.

### Veja Também

- mysql_query() - Envia uma consulta MySQL
- mysql_info() - Obtém informação sobre a consulta mais recente

# mysql_list_dbs

(PHP 4, PHP 5)

mysql_list_dbs — Lista os bancos de dados disponíveis em um servidor MySQL

Aviso

Esta função foi descontinuada a partir do PHP 5.4.0 e ela e a extensão MySQL original foram removidas a partir do PHP 7.0.0. Em vez disso, use as extensões MySQLi ou PDO_MySQL, que são desenvolvidas ativamente. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- SQL Query: `SHOW DATABASES`

### Descrição

function mysql_list_dbs(resource `$link_identifier` = NULL): resource

Retorna um ponteiro de resultado contendo os bancos de dados disponíveis atualmente no servidor MySQL.

### Parâmetros

`link_identifier`
  A conexão MySQL. Se o identificador da conexão não for especificado, a última conexão aberta por mysql_connect() será usada. Se não houver uma conexão anterior, haverá uma tentativa de criar uma como se mysql_connect() tivesse sido chamada sem argumentos. Se nenhuma conexão for encontrada ou estabelecida, um erro de nível `E_WARNING` será gerado.

### Valor Retornado

Retorna um ponteiro de resultado resource em caso de sucesso, ou `false` em caso de falha. Use a função mysql_tablename() para lidar com este ponteiro de resultado, ou qualquer função para tabelas com resultados, como mysql_fetch_array().

### Exemplos

Exemplo #1 Exemplo mysql_list_dbs()

    <?php
    // Uso sem mysql_list_dbs()
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    $res = mysql_query("SHOW DATABASES");

    while ($row = mysql_fetch_assoc($res)) {
        echo $row['Database'] . "\n";
    }

    // Descontinuado a partir do PHP 5.4.0
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    $db_list = mysql_list_dbs($link);

    while ($row = mysql_fetch_object($db_list)) {
         echo $row->Database . "\n";
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    database1
    database2
    database3

### Notas

> Nota: Para compatibilidade com versões anteriores, o seguinte apelido descontinuado pode ser usado: mysql_listdbs()

### Veja Também

- mysql_db_name() - Obtém o nome do banco de dados a partir da chamada à mysql_list_dbs
- mysql_select_db() - Seleciona um banco de dados MySQL

# mysql_list_fields

(PHP 4, PHP 5)

mysql_list_fields — Lista os campos de uma tabela MySQL

Aviso

Esta função foi descontinuada a partir do PHP 5.4.0 e ela e a extensão MySQL original foram removidas a partir do PHP 7.0.0. Em vez disso, use as extensões MySQLi ou PDO_MySQL, que são desenvolvidas ativamente. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- Consulta SQL: `SHOW COLUMNS FROM sometable`

### Descrição

function mysql_list_fields(string `$database_name`, string `$table_name`, resource `$link_identifier` = NULL): resource

Obtém informações sobre a tabela informada.

Esta função foi descontinuada. É preferrível usar mysql_query() para realizar uma consulta SQL `SHOW COLUMNS FROM table [LIKE 'name']`.

### Parâmetros

`database_name`
  O nome do banco de dados que está sendo consultado.
`table_name`
  O nome da tabela que esta sendo consultada.
`link_identifier`
  A conexão MySQL. Se o identificador da conexão não for especificado, a última conexão aberta por mysql_connect() será usada. Se não houver uma conexão anterior, haverá uma tentativa de criar uma como se mysql_connect() tivesse sido chamada sem argumentos. Se nenhuma conexão for encontrada ou estabelecida, um erro de nível `E_WARNING` será gerado.

### Valor Retornado

Um ponteiro de recurso resource em caso de sucesso, ou `false` em caso de falha.

O ponteiro de resultado pode ser usado com mysql_field_flags(), mysql_field_len(), mysql_field_name() e mysql_field_type().

### Exemplos

Exemplo #1 Alternativa para a função descontinuada mysql_list_fields()

    <?php
    $result = mysql_query("SHOW COLUMNS FROM sometable");
    if (!$result) {
        echo 'Não foi possível executar a consulta: ' . mysql_error();
        exit;
    }
    if (mysql_num_rows($result) > 0) {
        while ($row = mysql_fetch_assoc($result)) {
            print_r($row);
        }
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [Field] => id
        [Type] => int(7)
        [Null] =>
        [Key] => PRI
        [Default] =>
        [Extra] => auto_increment
    )
    Array
    (
        [Field] => email
        [Type] => varchar(100)
        [Null] =>
        [Key] =>
        [Default] =>
        [Extra] =>
    )

### Notas

> Nota: Para compatibilidade com versões anteriores, o seguinte apelido descontinuado pode ser usado: mysql_listfields()

### Veja Também

- mysql_field_flags() - Obtém as opções associadas ao campo especificado em um resultado
- mysql_info() - Obtém informação sobre a consulta mais recente

# mysql_list_processes

(PHP 4 >= 4.3.0, PHP 5)

mysql_list_processes — Lista os processos MySQL

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_thread_id()

### Descrição

function mysql_list_processes(resource `$link_identifier` = NULL): resource|false

Obtém as threads atuais do servidor MySQL.

### Parâmetros

`link_identifier`
  A conexão MySQL. Se o identificador da conexão não for especificado, a última conexão aberta por mysql_connect() será usada. Se não houver uma conexão anterior, haverá uma tentativa de criar uma como se mysql_connect() tivesse sido chamada sem argumentos. Se nenhuma conexão for encontrada ou estabelecida, um erro de nível `E_WARNING` será gerado.

### Valor Retornado

Um ponteiro de resultado resource em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo mysql_list_processes()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');

    $result = mysql_list_processes($link);
    while ($row = mysql_fetch_assoc($result)){
        printf("%s %s %s %s %s\n", $row["Id"], $row["Host"], $row["db"],
            $row["Command"], $row["Time"]);
    }
    mysql_free_result($result);
    ?>

O exemplo acima produzirá algo semelhante a:

    1 localhost test Processlist 0
    4 localhost mysql sleep 5

### Veja Também

- mysql_thread_id() - Retorna o ID da thread atual
- mysql_stat() - Obtém o status atual do sistema

# mysql_list_tables

(PHP 4, PHP 5)

mysql_list_tables — Lista as tabelas em um banco de dados MySQL

Aviso

Esta função foi descontinuada a partir do PHP 4.3.0 e ela e a extensão MySQL original foram removidas a partir do PHP 7.0.0. Em vez disso, use as extensões MySQLi ou PDO_MySQL, que são desenvolvidas ativamente. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- SQL Query: `SHOW TABLES FROM dbname`

### Descrição

function mysql_list_tables(string `$database`, resource `$link_identifier` = NULL): resource|false

Obtém uma lista de nomes de tabelas de um banco de dados MySQL.

Esta função foi preterida em favor de mysql_query() para emitir uma instrução SQL `SHOW TABLES [FROM db_name] [LIKE 'pattern']` em seu lugar.

### Parâmetros

`database`
  O nome do banco de dados
`link_identifier`
  A conexão MySQL. Se o identificador da conexão não for especificado, a última conexão aberta por mysql_connect() será usada. Se não houver uma conexão anterior, haverá uma tentativa de criar uma como se mysql_connect() tivesse sido chamada sem argumentos. Se nenhuma conexão for encontrada ou estabelecida, um erro de nível `E_WARNING` será gerado.

### Valor Retornado

Um ponteiro de resultado do tipo resource em caso de sucesso ou `false` em caso de falha.

A função mysql_tablename() deve ser usada para navegar pelo ponteiro de resultados, ou qualquer função para tabelas de resultados, como mysql_fetch_array().

### Exemplos

Exemplo #1 Exemplo alternativo de mysql_list_tables()

    <?php
    $dbname = 'mysql_dbname';

    if (!mysql_connect('mysql_host', 'mysql_user', 'mysql_password')) {
        echo 'Não foi possível conectar ao MySQL';
        exit;
    }

    $sql = "SHOW TABLES FROM $dbname";
    $result = mysql_query($sql);

    if (!$result) {
        echo "Erro de BD, não foi possível listar as tabelas\n";
        echo 'Erro do MySQL: ' . mysql_error();
        exit;
    }

    while ($row = mysql_fetch_row($result)) {
        echo "Tabela: {$row[0]}\n";
    }

    mysql_free_result($result);
    ?>

### Notas

> Nota: Para compatibilidade com versões anteriores, o seguinte apelido descontinuado pode ser usado: mysql_listtables()

### Veja Também

- mysql_list_dbs() - Lista os bancos de dados disponíveis em um servidor MySQL
- mysql_tablename() - Obtém o nome da tabela do campo

# mysql_num_fields

(PHP 4, PHP 5)

mysql_num_fields — Obtém o numero de campos em um resultado

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_num_fields()
- PDOStatement::columnCount()

### Descrição

function mysql_num_fields(resource `$result`): int|false

Obtém o numero de campos de uma consulta.

### Parâmetros

`result`
  O resource do resultado que está sendo avaliado. Este resultado vem de uma chamada a mysql_query().

### Valor Retornado

Retorna o numero de campos em um conjunto de resultados resource em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de mysql_num_fields()

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
        echo 'Não foi possível executar a consulta: ' . mysql_error();
        exit;
    }

    /* retorna 2 porque id,email === dois campos */
    echo mysql_num_fields($result);
    ?>

### Notas

> Nota: Para compatibilidade com versões anteriores, o seguinte apelido descontinuado pode ser usado: mysql_numfields()

### Veja Também

- mysql_select_db() - Seleciona um banco de dados MySQL
- mysql_query() - Envia uma consulta MySQL
- mysql_fetch_field() - Obtém informações de coluna de um resultado e retorna como um objeto
- mysql_num_rows() - Obtém o número de linhas em um resultado

# mysql_num_rows

(PHP 4, PHP 5)

mysql_num_rows — Obtém o número de linhas em um resultado

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_num_rows()
- mysqli_stmt_num_rows()
- PDOStatement::rowCount()

### Descrição

function mysql_num_rows(resource `$result`): int|false

Obtém o numero de linhas de um conjunto de resultados. Este comando é valido apenas para comandos como SELECT ou SHOW que realmente retornam um conjunto de resultados. Para obter o numero de linhas afetadas por uma consulta INSERT, UPDATE, REPLACE ou DELETE, use mysql_affected_rows().

### Parâmetros

`result`
  O resource do resultado que está sendo avaliado. Este resultado vem de uma chamada a mysql_query().

### Valor Retornado

O numero de linhas em um conjunto de resultados em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo mysql_num_rows()

    <?php

    $link = mysql_connect("localhost", "mysql_user", "mysql_password");
    mysql_select_db("database", $link);

    $result = mysql_query("SELECT * FROM table1", $link);
    $num_rows = mysql_num_rows($result);

    echo "$num_rows Rows\n";

    ?>

### Notas

> Nota: Se você usar mysql_unbuffered_query(), mysql_num_rows() não irá retornar o valor correto até que todas as linhas no conjunto de resultado tenham sido obtidas.

> Nota: Para compatibilidade com versões anteriores, o seguinte apelido descontinuado pode ser usado: mysql_numrows()

### Veja Também

- mysql_affected_rows() - Obtém o número de linhas afetadas na operação anterior do MySQL
- mysql_connect() - Abre uma conexão a um servidor MySQL
- mysql_data_seek() - Move o ponteiro interno do resultado
- mysql_select_db() - Seleciona um banco de dados MySQL
- mysql_query() - Envia uma consulta MySQL

# mysql_pconnect

(PHP 4, PHP 5)

mysql_pconnect — Abre uma conexão persistente a um servidor MySQL

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_connect() com `p:` host prefix
- PDO::__construct() com `PDO::ATTR_PERSISTENT` como uma opção de driver

### Descrição

function mysql_pconnect(
string `$server` = ini_get("mysql.default_host"),
string `$username` = ini_get("mysql.default_user"),
string `$password` = ini_get("mysql.default_password"),
int `$client_flags` = 0
): resource

Estabelece uma conexão persistente com o servidor MySQL.

mysql_pconnect() funciona muito parecido com mysql_connect() com duas diferenças principais.

Primeiro, ao conectar,a função irá primeiro tentar encontrar uma conexão (persistente) que já esteja aberta com o mesmo servidor, nome de usuário e senha. Se for encontrada, um identificador para ela será retornado ao invés de ser aberta uma nova conexão.

Segundo, a conexão ao servidor SQL não será fechada quando a execução do script terminar. Ao invés disso, a conexão permanecerá aberta para uso futuro (mysql_close() não irá fechar conexões estabelecidas por mysql_pconnect()).

Este tipo de conexão portanto é chamado de 'persistente'.

### Parâmetros

`server`
  O servidor MySQL. Também pode incluir um numero de porta, por exemplo, "servidor:porta" ou um caminho para um soquete local, por exemplo, ":/caminho/para/soquete" para o servidor local. Se a diretiva do PHP mysql.default_host não estiver definida (padrão), o valor padrão será 'localhost:3306'
`username`
  O nome de usuário. O Valor padrão é o nome do usuário proprietário do processo no servidor.
`password`
  A senha. O valor padrão é uma senha vazia.
`client_flags`
  O parâmetro `client_flags` pode ser uma combinação das seguintes constantes: 128 (habilita uso de `LOAD DATA LOCAL`), `MYSQL_CLIENT_SSL`, `MYSQL_CLIENT_COMPRESS`, `MYSQL_CLIENT_IGNORE_SPACE` ou `MYSQL_CLIENT_INTERACTIVE`.

### Valor Retornado

Retorna um identificador de conexão persistente MySQL em caso de sucesso, ou `false` em caso de falha.

### Notas

> Nota: Note que este tipo de conexão funciona somente se a versão de módulo do PHP estiver sendo usada. Consulte a seção sobre Conexões Persistentes com Banco de Dados para mais informações.

Aviso

Usar conexões persistentes pode requerer alguns ajustes nas configurações do Apache e do MySQL para assegurar que o número máximo de conexões permitidas pelo MySQL não seja excedido.

### Veja Também

- mysql_connect() - Abre uma conexão a um servidor MySQL
- Conexões Persistentes com Banco de Dados

# mysql_ping

(PHP 4 >= 4.3.0, PHP 5)

mysql_ping — Pinga uma conexão com o servidor ou reconecta se não houver conexão

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_ping()

### Descrição

function mysql_ping(resource `$link_identifier` = NULL): bool

Confere se a conexão com o servidor está funcionando ou não. Se ela tiver caído, tenta realizar uma conexão automática. Esta função pode ser usada em scripts que permanecem inativos por um longo tempo, para verificar se o servidor fechou ou não a conexão e reconectar se necessário.

> Nota: A reconexão automática está desabilitada por padrão em versões do Mysql >= 5.0.3.

### Parâmetros

`link_identifier`
  A conexão MySQL. Se o identificador da conexão não for especificado, a última conexão aberta por mysql_connect() será usada. Se não houver uma conexão anterior, haverá uma tentativa de criar uma como se mysql_connect() tivesse sido chamada sem argumentos. Se nenhuma conexão for encontrada ou estabelecida, um erro de nível `E_WARNING` será gerado.

### Valor Retornado

Retorna `true` se a conexão com o servidor MySQL estiver funcionando, caso contrário retorna `false`.

### Exemplos

Exemplo #1 Exemplo mysql_ping()

    <?php
    set_time_limit(0);

    $conn = mysql_connect('localhost', 'usuario', 'senha');
    $db   = mysql_select_db('mydb');

    /* Supondo que esta consulta levará muito tempo */
    $result = mysql_query($sql);
    if (!$result) {
        echo 'Consulta #1 falhou, saindo.';
        exit;
    }

    /* Certifique-se de que a conexão ainda esteja ativa; caso contrário, tente reconectar */
    if (!mysql_ping($conn)) {
        echo 'Conexão perdida, saindo após consulta #1';
        exit;
    }
    mysql_free_result($result);

    /* Então a conexão ainda está ativa, vamos executar outra consulta */
    $result2 = mysql_query($sql2);
    ?>

### Veja Também

- mysql_thread_id() - Retorna o ID da thread atual
- mysql_list_processes() - Lista os processos MySQL

# mysql_query

(PHP 4, PHP 5)

mysql_query — Envia uma consulta MySQL

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_query()
- PDO::query()

### Descrição

function mysql_query(string `$query`, resource `$link_identifier` = NULL): mixed

mysql_query() envia uma única consulta (consultas múltiplas não são suportadas) ao banco de dados atualmente ativo no servidor associado ao `link_identifier` especificado.

### Parâmetros

`query`
  A consulta SQL. A consulta não deve terminar com um ponto e vírgula. Os dados dentro da consulta devem ser adequadamente escapados.
`link_identifier`
  A conexão MySQL. Se o identificador da conexão não for especificado, a última conexão aberta por mysql_connect() será usada. Se não houver uma conexão anterior, haverá uma tentativa de criar uma como se mysql_connect() tivesse sido chamada sem argumentos. Se nenhuma conexão for encontrada ou estabelecida, um erro de nível `E_WARNING` será gerado.

### Valor Retornado

Para comandos SELECT, SHOW, DESCRIBE, EXPLAIN e outras instruções que retornam resultados, mysql_query() retorna um resource em caso de sucesso ou `false` em caso de erro.

Para outros tipos de instruções SQL, UPDATE, DELETE, DROP, etc, mysql_query() retorna `true` em caso de sucesso ou `false` em caso de erro.

O recurso de resultado retornado pode ser passado para mysql_fetch_array() e para outras funções para lidar com tabelas de resultados e para acessar os dados retornados.

Use mysql_num_rows() para obter quantas linhas foram retornadas para uma instrução SELECT ou mysql_affected_rows() para obter quantas linhas foram afetadas por uma instrução DELETE, INSERT, REPLACE ou UPDATE.

mysql_query() também falhará e retornará `false` se o usuário não tiver permissões para acessar a(s) tabela(s) referenciada(s) pela consulta.

### Exemplos

Exemplo #1 Consulta Inválida

A seguinte consulta é sintaticamente inválida, assim mysql_query() falha e retorna `false`.

    <?php
    $result = mysql_query('SELECT * WHERE 1=1');
    if (!$result) {
        die('Consulta inválida: ' . mysql_error());
    }

    ?>

Exemplo #2 Consulta Válida

A seguinte consulta é válida, assim mysql_query() retorna um resource.

    <?php
    // Isto poderia ser fornecido pelo usuário, por exemplo
    $firstname = 'fred';
    $lastname  = 'fox';

    // Formula a Consulta
    // Esta é a melhor forma de realizar uma consulta SQL
    // Para mais exemplo, consulte mysql_real_escape_string()
    $query = sprintf("SELECT firstname, lastname, address, age FROM friends
        WHERE firstname='%s' AND lastname='%s'",
        mysql_real_escape_string($firstname),
        mysql_real_escape_string($lastname));

    // Realiza a Consulta
    $result = mysql_query($query);

    // Verifica o resultado
    // Isto mostra a consulta real enviada ao MySQL, e o erro. Útil para depuração.
    if (!$result) {
        $message  = 'Consulta inválida: ' . mysql_error() . "\n";
        $message .= 'Consulta completa: ' . $query;
        die($message);
    }

    // Usa o resultado
    // Tentar mostrar $result não permitirá acesso à informação no recurso
    // Uma das funções de resultados da extensão mysql precisa ser usada
    // Consulte também mysql_result(), mysql_fetch_array(), mysql_fetch_row(), etc.
    while ($row = mysql_fetch_assoc($result)) {
        echo $row['firstname'];
        echo $row['lastname'];
        echo $row['address'];
        echo $row['age'];
    }

    // Libera os recursos associados com o conjunto de resultados
    // Isto é feito automaticamente no final do script
    mysql_free_result($result);
    ?>

### Veja Também

- mysql_connect() - Abre uma conexão a um servidor MySQL
- mysql_error() - Retorna o texto da mensagem de erro da operação MySQL anterior
- mysql_real_escape_string() - Escapa os caracteres especiais em uma string para uso em uma instrução SQL
- mysql_result() - Retorna dados do resultado
- mysql_fetch_assoc() - Obtém uma linha do resultado como um array associativo
- mysql_unbuffered_query() - Envia uma consulta SQL ao MySQL sem buscar e armazenar em buffer as linhas de resultados

# mysql_real_escape_string

(PHP 4 >= 4.3.0, PHP 5)

mysql_real_escape_string — Escapa os caracteres especiais em uma string para uso em uma instrução SQL

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_real_escape_string()
- PDO::quote()

### Descrição

function mysql_real_escape_string(string `$unescaped_string`, resource `$link_identifier` = NULL): string

Escapa caracteres especiais do parâmetro `unescaped_string`, levando em conta o conjunto de caracteres atual da conexão, de forma que seja seguro inseri-la na função mysql_query(). Se forem inseridos dados binários, esta função precisa ser usada.

mysql_real_escape_string() chama a função mysql_real_escape_string da biblioteca do MySQL, que prefixa com barras invertidas os seguintes caracteres: `\x00`, `\n`, `\r`, `\`, `'`, `"` e `\x1a`.

Esta função precisa sempre ser usada (com poucas exceções) para tornar os dados seguros antes de enviá-los em uma consulta ao MySQL.

Cuidado

# Segurança: o conjunto de caracteres padrão

O conjunto de caracteres precisa ser definido no nível do servidor ou com a função mysql_set_charset() da API para que afete a função mysql_real_escape_string(). Consulte a seção de conceitos sobre conjuntos de caracteres para mais informação.

### Parâmetros

`unescaped_string`
  A string a ser escapada.
`link_identifier`
  A conexão MySQL. Se o identificador da conexão não for especificado, a última conexão aberta por mysql_connect() será usada. Se não houver uma conexão anterior, haverá uma tentativa de criar uma como se mysql_connect() tivesse sido chamada sem argumentos. Se nenhuma conexão for encontrada ou estabelecida, um erro de nível `E_WARNING` será gerado.

### Valor Retornado

Retorna a string escapada ou `false` em caso de erro.

### Erros/Exceções

Executar esta função sem uma conexão MySQL presente emitirá um erro de nível `E_WARNING`. Esta função deve ser executada somente com uma conexão MySQL válida presente.

### Exemplos

Exemplo #1 Exemplo de mysql_real_escape_string()

    <?php
    // Connect
    $link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password')
        OR die(mysql_error());

    // Query
    $query = sprintf("SELECT * FROM users WHERE user='%s' AND password='%s'",
                mysql_real_escape_string($user),
                mysql_real_escape_string($password));
    ?>

Exemplo #2 mysql_real_escape_string() requer um exemplo de conexão

Este exemplo demonstra o que acontece se uma conexão MySQL não estiver presente ao chamar esta função.

    <?php
    // Ainda não foi feita conexão ao MySQL

    $lastname  = "O'Reilly";
    $_lastname = mysql_real_escape_string($lastname);

    $query = "SELECT * FROM actors WHERE last_name = '$_lastname'";

    var_dump($_lastname);
    var_dump($query);
    ?>

O exemplo acima produzirá algo semelhante a:

    Warning: mysql_real_escape_string(): No such file or directory in /this/test/script.php on line 5
    Warning: mysql_real_escape_string(): A link to the server could not be established in /this/test/script.php on line 5

    bool(false)
    string(41) "SELECT * FROM actors WHERE last_name = ''"

Exemplo #3 Um exemplo de Ataque de Injeção SQL

    <?php
    // Não verificamos $_POST['password'], ela pode conter qualquer coisa que o usuário quiser! Por exemplo:
    $_POST['username'] = 'aidan';
    $_POST['password'] = "' OR ''='";

    // Consulta o banco de dados para verificar se existe algum usuário correspondente
    $query = "SELECT * FROM users WHERE user='{$_POST['username']}' AND password='{$_POST['password']}'";
    mysql_query($query);

    // Isto significa que a consulta enviada ao MySQL seria:
    echo $query;
    ?>

A consulta enviada ao MySQL:

    SELECT * FROM users WHERE user='aidan' AND password='' OR ''=''

Isto permitiria que qualquer pessoa fizesse login sem uma senha válida.

### Notas

> Nota: Uma conexão MySQL é requerida antes que mysql_real_escape_string() seja usada, caso contrário um erro de nível `E_WARNING` será gerado e `false` é retornado. Se `link_identifier` não estiver definido, a últimoa conexão MySQL será usada.

> Nota: Se esta função não for usada para escapar dados, a consulta ficará vulnerável a Ataques de Injeção SQL.

> Nota: mysql_real_escape_string() não escapa `%` e `_`. Estes caracteres são coringas no MySQL se combinados com `LIKE`, `GRANT` ou `REVOKE`.

### Veja Também

- mysql_set_charset() - Define o conjunto de caracteres do cliente
- mysql_client_encoding() - Retorna o nome do conjunto de caracteres

# mysql_result

(PHP 4, PHP 5)

mysql_result — Retorna dados do resultado

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_data_seek() em conjunto com mysqli_field_seek() e mysqli_fetch_field()
- PDOStatement::fetchColumn()

### Descrição

function mysql_result(resource `$result`, int `$row`, mixed `$field` = 0): string

Retorna o conteúdo de uma célula do resultado MySQL.

Ao trabalhar com conjuntos grandes de resultados, deve ser considerado o uso de uma das funções que retornam uma linha inteira (especificadas abaixo). Como estas funções retornam o conteúdo de múltiplas células em uma chamada de função, elas são MUITO mais rápidas que mysql_result(). Observe também que especificar um índice numérico para o argumento de campo (field) é muito mais rápido que especificar um argumento com nome de campo ou nome_tabela.nome_de_campo.

### Parâmetros

`result`
  O resource do resultado que está sendo avaliado. Este resultado vem de uma chamada a mysql_query().
`row`
  O número da linha do resultado que está sendo recuperado. Os números das linhas começam em `0`.
`field`
  O nome ou posição do campo que está sendo recuperado. Pode ser a posição do campo, o nome do campo ou o nome da tabela mais um ponto mais o nome do campo (nome_tabela.nome_campo). Se o nome da coluna tiver sido apelidado ('select foo as bar from...'), o apelido deve ser usado no lugar do nome da coluna. Se indefinido, o primeiro campo será recuperado.

### Valor Retornado

O conteúdo de uma célula de um conjunto de resultado MySQL em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de mysql_result()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Não foi possível conectar: ' . mysql_error());
    }
    if (!mysql_select_db('database_name')) {
        die('Não foi possível selecionar o banco de dados: ' . mysql_error());
    }
    $result = mysql_query('SELECT name FROM work.employee');
    if (!$result) {
        die('Não foi possível consultar:' . mysql_error());
    }
    echo mysql_result($result, 2); // mostra o nome do terceiro empregado (employee)

    mysql_close($link);
    ?>

### Notas

> Nota: Chamadas a mysql_result() não devem ser misturadas com chamadas a outras funções que lidam com o conjunto de resultados.

### Veja Também

- mysql_fetch_row() - Obtém uma linha como um array numérico
- mysql_fetch_array() - Obtém uma linha de resultado como um array associativo, numérico, ou ambos
- mysql_fetch_assoc() - Obtém uma linha do resultado como um array associativo
- mysql_fetch_object() - Obtém o resultado de uma linha como um objeto

# mysql_select_db

(PHP 4, PHP 5)

mysql_select_db — Seleciona um banco de dados MySQL

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_select_db()
- PDO::__construct() (parte da dsn)

### Descrição

function mysql_select_db(string `$database_name`, resource `$link_identifier` = NULL): bool

Define o banco de dados ativo atual no servidor associado ao identificador de conexão especificado. Cada chamada subsequente a mysql_query() será feita no banco de dados ativo.

### Parâmetros

`database_name`
  O nome do banco de dados que será selecionado.
`link_identifier`
  A conexão MySQL. Se o identificador da conexão não for especificado, a última conexão aberta por mysql_connect() será usada. Se não houver uma conexão anterior, haverá uma tentativa de criar uma como se mysql_connect() tivesse sido chamada sem argumentos. Se nenhuma conexão for encontrada ou estabelecida, um erro de nível `E_WARNING` será gerado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de mysql_select_db()

    <?php

    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Não conectado : ' . mysql_error());
    }

    // faz de 'foo' o banco de dados atual
    $db_selected = mysql_select_db('foo', $link);
    if (!$db_selected) {
        die ('Não foi possível usar foo : ' . mysql_error());
    }
    ?>

### Notas

> Nota: Para compatibilidade com versões anteriores, o seguinte apelido descontinuado pode ser usado: mysql_selectdb()

### Veja Também

- mysql_connect() - Abre uma conexão a um servidor MySQL
- mysql_pconnect() - Abre uma conexão persistente a um servidor MySQL
- mysql_query() - Envia uma consulta MySQL

# mysql_set_charset

(PHP 5 >= 5.2.3)

mysql_set_charset — Define o conjunto de caracteres do cliente

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_set_charset()
- PDO: Adicionar `charset` à string de conexão, por exemplo `charset=utf8`

### Descrição

function mysql_set_charset(string `$charset`, resource `$link_identifier` = NULL): bool

Define o conjunto de caracteres padrão para a conexão atual.

### Parâmetros

`charset`
  Um nome válido de conjunto de caracteres.
`link_identifier`
  A conexão MySQL. Se o identificador da conexão não for especificado, a última conexão aberta por mysql_connect() será usada. Se não houver uma conexão anterior, haverá uma tentativa de criar uma como se mysql_connect() tivesse sido chamada sem argumentos. Se nenhuma conexão for encontrada ou estabelecida, um erro de nível `E_WARNING` será gerado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Notas

> Nota: Esta função requer o MySQL 5.0.7 ou mais recente.

> Nota: Esta é a maneira preferida de alterar o conjunto de caracteres. Usar mysql_query() para configurá-lo (como em `SET NAMES utf8`) não é recomendado. Consulte a seção conceitos do conjunto de caracteres MySQL para obter mais informações.

### Veja Também

- Configurando conjuntos de caracteres no MySQL
- » Lista de conjuntos de caracteres suportados pelo MySQL
- mysql_client_encoding() - Retorna o nome do conjunto de caracteres

# mysql_stat

(PHP 4 >= 4.3.0, PHP 5)

mysql_stat — Obtém o status atual do sistema

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_stat()
- PDO::getAttribute() com `attribute` igual a `PDO::ATTR_SERVER_INFO`

### Descrição

function mysql_stat(resource `$link_identifier` = NULL): string

mysql_stat() retorna o status atual do servidor.

### Parâmetros

`link_identifier`
  A conexão MySQL. Se o identificador da conexão não for especificado, a última conexão aberta por mysql_connect() será usada. Se não houver uma conexão anterior, haverá uma tentativa de criar uma como se mysql_connect() tivesse sido chamada sem argumentos. Se nenhuma conexão for encontrada ou estabelecida, um erro de nível `E_WARNING` será gerado.

### Valor Retornado

Retorna uma string com o status de tempo de atividade, threads, consultas, tabelas abertas, tabelas de liberação e consultas por segundo. Para obter uma lista completa de outras variáveis ​​de status, deve ser usado o comando SQL `SHOW STATUS`. Se `link_identifier` for inválido, `null` é retornado.

### Exemplos

Exemplo #1 Exemplo de mysql_stat()

    <?php
    $link   = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    $status = explode('  ', mysql_stat($link));
    print_r($status);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Uptime: 5380
        [1] => Threads: 2
        [2] => Questions: 1321299
        [3] => Slow queries: 0
        [4] => Opens: 26
        [5] => Flush tables: 1
        [6] => Open tables: 17
        [7] => Queries per second avg: 245.595
    )

Exemplo #2 Exemplo alternativo a mysql_stat()

    <?php
    $link   = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    $result = mysql_query('SHOW STATUS', $link);
    while ($row = mysql_fetch_assoc($result)) {
        echo $row['Variable_name'] . ' = ' . $row['Value'] . "\n";
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    back_log = 50
    basedir = /usr/local/
    bdb_cache_size = 8388600
    bdb_log_buffer_size = 32768
    bdb_home = /var/db/mysql/
    bdb_max_lock = 10000
    bdb_logdir =
    bdb_shared_data = OFF
    bdb_tmpdir = /var/tmp/
    ...

### Veja Também

- mysql_get_server_info() - Obtém informações do servidor MySQL
- mysql_list_processes() - Lista os processos MySQL

# mysql_tablename

(PHP 4, PHP 5)

mysql_tablename — Obtém o nome da tabela do campo

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- Consulta SQL: `SHOW TABLES`

### Descrição

function mysql_tablename(resource `$result`, int `$i`): string|false

Recupera o nome da tabela a partir de um resultado informado em `result`.

Esta função foi descontinuada. É preferível usar mysql_query() para emitir uma instrução SQL `SHOW TABLES [FROM db_name] [LIKE 'pattern']` em seu lugar.

### Parâmetros

`result`
  Um ponteiro de resultados do tipo resource que é retornado por mysql_list_tables().
`i`
  O índice como um número inteiro (número da linha/tabela)

### Valor Retornado

O nome da tabela em caso de sucesso ou `false` em caso de falha.

Use a função mysql_tablename() para percorrer este ponteiro de resultado, ou qualquer função para tabelas de resultados, como mysql_fetch_array().

### Exemplos

Exemplo #1 Exemplo de mysql_tablename()

    <?php
    mysql_connect("localhost", "mysql_user", "mysql_password");
    $result = mysql_list_tables("mydb");
    $num_rows = mysql_num_rows($result);
    for ($i = 0; $i < $num_rows; $i++) {
        echo "Tabela: ", mysql_tablename($result, $i), "\n";
    }

    mysql_free_result($result);
    ?>

### Notas

> Nota: A função mysql_num_rows() pode ser usada para determinar o número de tabelas no ponteiro de resultados.

### Veja Também

- mysql_list_tables() - Lista as tabelas em um banco de dados MySQL
- mysql_field_table() - Obtém o nome da tabela na qual o campo especificado esta
- mysql_db_name() - Obtém o nome do banco de dados a partir da chamada à mysql_list_dbs

# mysql_thread_id

(PHP 4 >= 4.3.0, PHP 5)

mysql_thread_id — Retorna o ID da thread atual

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_thread_id()

### Descrição

function mysql_thread_id(resource `$link_identifier` = NULL): int|false

Recupera o ID da thread atual. Se a conexão for perdida e uma reconexão com mysql_ping() for executada, o ID da thread será alterado. Isso significa que é melhor recuperar o ID da thread apenas quando necessário.

### Parâmetros

`link_identifier`
  A conexão MySQL. Se o identificador da conexão não for especificado, a última conexão aberta por mysql_connect() será usada. Se não houver uma conexão anterior, haverá uma tentativa de criar uma como se mysql_connect() tivesse sido chamada sem argumentos. Se nenhuma conexão for encontrada ou estabelecida, um erro de nível `E_WARNING` será gerado.

### Valor Retornado

O ID da thread em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de mysql_thread_id()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    $thread_id = mysql_thread_id($link);
    if ($thread_id){
        printf("ID da thread atual é %d\n", $thread_id);
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    ID da thread atual é 73

### Veja Também

- mysql_ping() - Pinga uma conexão com o servidor ou reconecta se não houver conexão
- mysql_list_processes() - Lista os processos MySQL

# mysql_unbuffered_query

(PHP 4 >= 4.0.6, PHP 5)

mysql_unbuffered_query — Envia uma consulta SQL ao MySQL sem buscar e armazenar em buffer as linhas de resultados

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- Consulte: Consultas com e sem buffer

### Descrição

function mysql_unbuffered_query(string `$query`, resource `$link_identifier` = NULL): resource

mysql_unbuffered_query() envia a consulta SQL `query` para o MySQL sem buscar e armazenar automaticamente as linhas de resultados como mysql_query() faz. Isso economiza uma quantidade considerável de memória com consultas SQL que produzem grandes conjuntos de resultados, e o conjunto de resultados já pode ser processado imediatamente após a primeira linha ter sido recuperada, pois não será necessário esperar até que a consulta SQL completa seja executada. Para usar mysql_unbuffered_query() enquanto múltiplas conexões de banco de dados estão abertas, o parâmetro opcional `link_identifier` deve ser especificado para identificar qual conexão deve ser usada.

### Parâmetros

`query`
  A consulta SQL a ser executada. Dados dentro da consulta devem ser adequadamente escapados.
`link_identifier`
  A conexão MySQL. Se o identificador da conexão não for especificado, a última conexão aberta por mysql_connect() será usada. Se não houver uma conexão anterior, haverá uma tentativa de criar uma como se mysql_connect() tivesse sido chamada sem argumentos. Se nenhuma conexão for encontrada ou estabelecida, um erro de nível `E_WARNING` será gerado.

### Valor Retornado

Para instruções SELECT, SHOW, DESCRIBE ou EXPLAIN, mysql_unbuffered_query() retorna um resource em caso de sucesso, ou `false` em caso de erro.

Para outros tipos de instruções SQL, UPDATE, DELETE, DROP, etc., mysql_unbuffered_query() retorna `true` em caso de sucesso ou `false` em caso de erro.

### Notas

> Nota: Os benefícios de mysql_unbuffered_query() têm um custo: mysql_num_rows() e mysql_data_seek() não podem ser usadas em um conjunto de resultados retornado de mysql_unbuffered_query() , até que todas as linhas sejam buscadas. Também é necessário buscar todas as linhas de resultados de uma consulta SQL sem buffer antes de enviar uma nova consulta SQL ao MySQL, usando o mesmo `link_identifier`.

### Veja Também

- mysql_query() - Envia uma consulta MySQL

## Índice

- mysql_affected_rows — Obtém o número de linhas afetadas na operação anterior do MySQL
- mysql_client_encoding — Retorna o nome do conjunto de caracteres
- mysql_close — Fecha a conexão MySQL
- mysql_connect — Abre uma conexão a um servidor MySQL
- mysql_create_db — Cria um banco de dados MySQL
- mysql_data_seek — Move o ponteiro interno do resultado
- mysql_db_name — Obtém o nome do banco de dados a partir da chamada à mysql_list_dbs
- mysql_db_query — Seleciona um banco de dados e executa uma consulta nele
- mysql_drop_db — Drop (exclui) um banco de dados MySQL
- mysql_errno — Retorna o valor numérico da mensagem de erro da operação MySQL anterior
- mysql_error — Retorna o texto da mensagem de erro da operação MySQL anterior
- mysql_escape_string — Escapa uma string para usá-la em uma função mysql_query
- mysql_fetch_array — Obtém uma linha de resultado como um array associativo, numérico, ou ambos
- mysql_fetch_assoc — Obtém uma linha do resultado como um array associativo
- mysql_fetch_field — Obtém informações de coluna de um resultado e retorna como um objeto
- mysql_fetch_lengths — Obtém o tamanho de cada saída de um resultado
- mysql_fetch_object — Obtém o resultado de uma linha como um objeto
- mysql_fetch_row — Obtém uma linha como um array numérico
- mysql_field_flags — Obtém as opções associadas ao campo especificado em um resultado
- mysql_field_len — Retorna o tamanho do campo especificado
- mysql_field_name — Obtém o nome do campo especificado em um resultado
- mysql_field_seek — Define o ponteiro do resultado para o índice de campo especificado
- mysql_field_table — Obtém o nome da tabela na qual o campo especificado esta
- mysql_field_type — Obtém o tipo do campo especificado em um resultado
- mysql_free_result — Libera memória usada pelo resultado
- mysql_get_client_info — Obtém informações do cliente MySQL
- mysql_get_host_info — Obtém informações do servidor MySQL
- mysql_get_proto_info — Obtém informações do protocolo MySQL
- mysql_get_server_info — Obtém informações do servidor MySQL
- mysql_info — Obtém informação sobre a consulta mais recente
- mysql_insert_id — Obtém o ID gerado pela operação INSERT anterior
- mysql_list_dbs — Lista os bancos de dados disponíveis em um servidor MySQL
- mysql_list_fields — Lista os campos de uma tabela MySQL
- mysql_list_processes — Lista os processos MySQL
- mysql_list_tables — Lista as tabelas em um banco de dados MySQL
- mysql_num_fields — Obtém o numero de campos em um resultado
- mysql_num_rows — Obtém o número de linhas em um resultado
- mysql_pconnect — Abre uma conexão persistente a um servidor MySQL
- mysql_ping — Pinga uma conexão com o servidor ou reconecta se não houver conexão
- mysql_query — Envia uma consulta MySQL
- mysql_real_escape_string — Escapa os caracteres especiais em uma string para uso em uma instrução SQL
- mysql_result — Retorna dados do resultado
- mysql_select_db — Seleciona um banco de dados MySQL
- mysql_set_charset — Define o conjunto de caracteres do cliente
- mysql_stat — Obtém o status atual do sistema
- mysql_tablename — Obtém o nome da tabela do campo
- mysql_thread_id — Retorna o ID da thread atual
- mysql_unbuffered_query — Envia uma consulta SQL ao MySQL sem buscar e armazenar em buffer as linhas de resultados

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
  - Tipos de Recurso
- Registro de Alterações
- Constantes predefinidas
- Exemplos
  - Exemplo de uso da extensão MySQL
- Funções da MySQL
  - mysql_affected_rows — Obtém o número de linhas afetadas na operação anterior do MySQL
  - mysql_client_encoding — Retorna o nome do conjunto de caracteres
  - mysql_close — Fecha a conexão MySQL
  - mysql_connect — Abre uma conexão a um servidor MySQL
  - mysql_create_db — Cria um banco de dados MySQL
  - mysql_data_seek — Move o ponteiro interno do resultado
  - mysql_db_name — Obtém o nome do banco de dados a partir da chamada à mysql_list_dbs
  - mysql_db_query — Seleciona um banco de dados e executa uma consulta nele
  - mysql_drop_db — Drop (exclui) um banco de dados MySQL
  - mysql_errno — Retorna o valor numérico da mensagem de erro da operação MySQL anterior
  - mysql_error — Retorna o texto da mensagem de erro da operação MySQL anterior
  - mysql_escape_string — Escapa uma string para usá-la em uma função mysql_query
  - mysql_fetch_array — Obtém uma linha de resultado como um array associativo, numérico, ou ambos
  - mysql_fetch_assoc — Obtém uma linha do resultado como um array associativo
  - mysql_fetch_field — Obtém informações de coluna de um resultado e retorna como um objeto
  - mysql_fetch_lengths — Obtém o tamanho de cada saída de um resultado
  - mysql_fetch_object — Obtém o resultado de uma linha como um objeto
  - mysql_fetch_row — Obtém uma linha como um array numérico
  - mysql_field_flags — Obtém as opções associadas ao campo especificado em um resultado
  - mysql_field_len — Retorna o tamanho do campo especificado
  - mysql_field_name — Obtém o nome do campo especificado em um resultado
  - mysql_field_seek — Define o ponteiro do resultado para o índice de campo especificado
  - mysql_field_table — Obtém o nome da tabela na qual o campo especificado esta
  - mysql_field_type — Obtém o tipo do campo especificado em um resultado
  - mysql_free_result — Libera memória usada pelo resultado
  - mysql_get_client_info — Obtém informações do cliente MySQL
  - mysql_get_host_info — Obtém informações do servidor MySQL
  - mysql_get_proto_info — Obtém informações do protocolo MySQL
  - mysql_get_server_info — Obtém informações do servidor MySQL
  - mysql_info — Obtém informação sobre a consulta mais recente
  - mysql_insert_id — Obtém o ID gerado pela operação INSERT anterior
  - mysql_list_dbs — Lista os bancos de dados disponíveis em um servidor MySQL
  - mysql_list_fields — Lista os campos de uma tabela MySQL
  - mysql_list_processes — Lista os processos MySQL
  - mysql_list_tables — Lista as tabelas em um banco de dados MySQL
  - mysql_num_fields — Obtém o numero de campos em um resultado
  - mysql_num_rows — Obtém o número de linhas em um resultado
  - mysql_pconnect — Abre uma conexão persistente a um servidor MySQL
  - mysql_ping — Pinga uma conexão com o servidor ou reconecta se não houver conexão
  - mysql_query — Envia uma consulta MySQL
  - mysql_real_escape_string — Escapa os caracteres especiais em uma string para uso em uma instrução SQL
  - mysql_result — Retorna dados do resultado
  - mysql_select_db — Seleciona um banco de dados MySQL
  - mysql_set_charset — Define o conjunto de caracteres do cliente
  - mysql_stat — Obtém o status atual do sistema
  - mysql_tablename — Obtém o nome da tabela do campo
  - mysql_thread_id — Retorna o ID da thread atual
  - mysql_unbuffered_query — Envia uma consulta SQL ao MySQL sem buscar e armazenar em buffer as linhas de resultados

# Driver Nativo MySQL

# Introdução

O Driver Nativo MySQL é um substituto para a biblioteca cliente MySQL (libmysqlclient). Driver Nativo MySQL faz parte das fontes oficiais do PHP a partir do PHP 5.3.0.

As extensões de banco de dados MySQL, `mysqli` e PDO MYSQL se comunicam com o servidor MySQL. No passado, isso era feito pela extensão usando os serviços fornecidos pela Biblioteca Cliente MySQL. As extensões foram compiladas na Biblioteca Cliente MySQL para usar seu protocolo cliente-servidor.

Com o Driver Nativo MySQL agora existe uma alternativa, pois as extensões do banco de dados MySQL podem ser compiladas para usar o Driver Nativo MySQL em vez da Biblioteca Cliente MySQL.

O Driver Nativo MySQL é escrito em C como uma extensão do PHP.

# Visão Geral

O que o mysqlnd não é

Embora o Driver Nativo MySQL seja escrito como uma extensão PHP, é importante observar que ele não fornece uma nova API para o programador PHP. As APIs do programador para conectividade de banco de dados MySQL são fornecidas pela extensão MySQL, `mysqli` e PDO MYSQL. Essas extensões agora podem usar os serviços do Driver Nativo MySQL para se comunicar com o servidor MySQL. Portanto, não se deve pensar no Driver Nativo MySQL como uma API.

Por que usá-lo?

A utilização do Driver Nativo MySQL oferece uma série de vantagens em relação à utilização da Biblioteca Cliente MySQL.

A antiga biblioteca cliente MySQL foi escrita pela MySQL AB (agora Oracle Corporation) e, portanto, foi lançada sob a licença MySQL. Isso acabou fazendo com que o suporte ao MySQL fosse desativado por padrão no PHP. Porém, o Driver Nativo MySQL foi desenvolvido como parte do projeto PHP, sendo portanto liberado sob a licença PHP. Isso elimina problemas de licenciamento que foram problemáticos no passado.

Além disso, no passado, era necessário construir as extensões de banco de dados MySQL com uma cópia da biblioteca cliente MySQL. Isso normalmente significava que era necessário ter o MySQL instalado em uma máquina onde o código-fonte PHP estivesse sendo compilado. Além disso, quando o aplicativo PHP estava em execução, as extensões do banco de dados MySQL chamavam o arquivo da biblioteca do cliente MySQL em tempo de execução, portanto, o arquivo precisava estar instalado no sistema. Com o Driver Nativo MySQL isso não acontece mais, pois está incluído como parte da distribuição padrão. Portanto, não é mais necessário o MySQL instalado para construir o PHP ou executar aplicações de banco de dados PHP.

Como o Driver Nativo MySQL é escrito como uma extensão do PHP, ele está fortemente acoplado ao funcionamento do PHP. Isso leva a ganhos de eficiência, principalmente no que diz respeito ao uso de memória, já que o driver utiliza o sistema de gerenciamento de memória PHP. Ele também suporta o limite de memória do PHP. Usar o Driver Nativo MySQL leva a um desempenho comparável ou melhor do que usar a Biblioteca Cliente MySQL, garantindo sempre o uso mais eficiente da memória. Um exemplo de eficiência de memória é o fato de que ao utilizar a Biblioteca Cliente MySQL, cada linha é armazenada na memória duas vezes, enquanto no Driver Nativo MySQL cada linha é armazenada apenas uma vez na memória.

> Nota: Reportando o uso da memória
> Como o Driver Nativo MySQL utiliza o sistema de gerenciamento de memória PHP, seu uso de memória pode ser rastreado com memory_get_usage(). Isso não é possível com a libmysqlclient porque ela usa a função C malloc().

Special features

O Driver Nativo MySQL também fornece alguns recursos especiais não disponíveis quando as extensões de banco de dados MySQL utilizam a Biblioteca Cliente MySQL. Esses recursos especiais estão listados abaixo:

- Conexões persistentes melhoradas
- A função especial mysqli_fetch_all()
- Chamadas para estatísticas de desempenho: mysqli_get_client_stats(), mysqli_get_connection_stats()

O recurso de estatísticas de desempenho pode ser muito útil na identificação de gargalos de desempenho.

O Driver Nativo MySQL também permite conexões persistentes quando utilizado com a extensão `mysqli`.

Suporte a SSL

Driver Nativo MySQL suporta SSL.

Suporte a Protocolo com Compressão

Driver Nativo MySQL suporta o protocolo cliente-servidor com compressão. A extensão `ext/mysqli`, se configurada para usar Driver Nativo MySQL, também pode tomar vantagem deste recurso. Observe que `PDO_MYSQL` NÃO suporta compressão quando usada junto com mysqlnd.

Suporte a Tubos Nomeados

Tubos nomeados podem ser usado para conexão em ambientes Windows.

# Instalação

Instalação em Unix

Para usar o Driver Nativo MySQL, o PHP precisa ser construído especificando que as extensões do banco de dados MySQL são compiladas com suporte ao MySQL Native Driver. Isso é feito através de opções de configuração antes de compilar o código-fonte do PHP.

Por exemplo, para construir a extensão MySQL, `mysqli` e PDO MYSQL utilizando o Driver Nativo MySQL, seria dado o seguinte comando:

    ./configure --with-mysql=mysqlnd \
    --with-mysqli=mysqlnd \
    --with-pdo-mysql=mysqlnd \
    [other options]

Instalação no Windows

Nas distribuições oficiais do PHP para Windows, o Driver Nativo MySQL está habilitado por padrão, portanto, nenhuma configuração adicional é necessária para usá-lo. Todas as extensões de banco de dados MySQL usarão o Driver Nativo MySQL neste caso.

Suporte ao plug-in de autenticação SHA-256

O Driver Nativo MySQL requer que a funcionalidade OpenSSL do PHP esteja carregada e habilitada para conexão ao MySQL através de contas que utilizam o Plugin de Autenticação MySQL SHA-256. Por exemplo, o PHP pode ser configurado usando:

    ./configure --with-mysql=mysqlnd \
    --with-mysqli=mysqlnd \
    --with-pdo-mysql=mysqlnd \
    --with-openssl
    [other options]

No Autotools, o suporte SSL estendido no `mysqlnd` é habilitado implicitamente ao construir junto com a extensão `openssl` usando a opção de configuração --with-openssl. Ao compilar sem a extensão `openssl`, a opção de configuração --with-mysqlnd-ssl pode ser usada para ativar explicitamente o suporte SSL estendido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | A opção de configuração --with-mysqlnd-ssl do Autotools foi adicionada para ativar explicitamente o suporte SSL estendido ao compilar sem a extensão `openssl`.

# Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de configuração do Driver Nativo MySQL
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
mysqlnd.collect_statistics | "1" | `INI_SYSTEM` |
mysqlnd.collect_memory_statistics | "0" | `INI_SYSTEM` |
mysqlnd.debug | "" | `INI_SYSTEM` |
mysqlnd.log_mask | 0 | `INI_ALL` |
mysqlnd.mempool_default_size | 16000 | `INI_ALL` |
mysqlnd.net_read_timeout | "86400" | `INI_ALL` | Antes do PHP 7.2.0 o padrão era "31536000" e a mutabilidade era `INI_SYSTEM`
mysqlnd.net_cmd_buffer_size | "4096" | `INI_SYSTEM` |
mysqlnd.net_read_buffer_size | "32768" | `INI_SYSTEM` |
mysqlnd.sha256_server_public_key | "" | `INI_PERDIR` |
mysqlnd.trace_alloc | "" | `INI_SYSTEM` |
mysqlnd.fetch_data_copy | 0 | `INI_ALL` | Removida a partir do PHP 8.1.0

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`mysqlnd.collect_statistics` bool
  Permite a coleta de várias estatísticas de clientes que podem ser acessadas através de mysqli_get_client_stats() e mysqli_get_connection_stats() e também são mostradas na seção `mysqlnd` da saída da função phpinfo(). Esta configuração ativa todas as estatísticas do Driver Nativo MySQL exceto aquelas relacionadas ao gerenciamento de memória.
`mysqlnd.collect_memory_statistics` bool
  Permite a coleta de várias estatísticas de clientes que podem ser acessadas através de mysqli_get_client_stats() e mysqli_get_connection_stats() e também são mostradas na seção `mysqlnd` da saída da função phpinfo(). Esta definição de configuração ativa as estatísticas de gerenciamento de memória dentro do conjunto geral de estatísticas do Driver Nativo MySQL.
`mysqlnd.debug` string
  Grava a comunicação de todas as extenões que usam `mysqlnd` para o arquivo de registro especificado. O formato da diretiva é `mysqlnd.debug = "opção1[,parâmetro_opção1][:opção2[,parâmetro_opção2]]"`. As opções para a string de formato são as seguintes:
  - A[,arquivo] - Acrescenta saída de rastreamento ao arquivo especificado. Também garante que os dados sejam gravados após cada gravação. Isso é feito fechando e reabrindo o arquivo de rastreamento (isso é lento). Isso ajuda a garantir um arquivo de registro completo caso o aplicativo falhe.
  - a[,arquivo] - Acrescenta saída de rastreamento ao arquivo especificado.
  - d - Ativa a saída de macros DBUG_<N> para o estado atual. Pode ser seguido por uma lista de palavras-chave que seleciona a saída apenas para as macros DBUG com essa palavra-chave. Uma lista vazia de palavras-chave implica em saída para todas as macros.
  - f[,funções] - Limita as ações do depurador à lista de funções especificada. Uma lista vazia de funções implica em que todas as funções são selecionadas.
  - F - Marca cada linha de saída do depurador com o nome do arquivo de origem que contém a macro que causa a saída.
  - i - Marca cada linha de saída do depurador com o PID do processo atual.
  - L - Marca cada linha de saída do depurador com o nome do número da linha do arquivo de origem da macro que causa a saída.
  - n - Marca cada linha de saída do depurador com a profundidade de aninhamento da função atual.
  - o[,arquivo] - Similar a a[,arquivo] mas sobrescreve o arquivo antigo, e não anexa.
  - O[,arquivo] - Similar a A[,arquivo] mas sobrescreve o arquivo antigo, e não anexa.
  - t[,N] - Ativa o rastreamento de fluxo de controle de função. A profundidade máxima de aninhamento é especificada por N e o padrão é 200.
  - x - Este opção ativa a criação de perfil de código.
  - m - Rastreia chamadas relacionadas à alocação e desalocação de memória.
  Example:

      d:t:x:O,/tmp/mysqlnd.trace

  > Nota: Este recurso está disponível apenas com uma compilação de depuração do PHP.

`mysqlnd.log_mask` int
  Define quais consultas serão registradas. O padrão é 0, que desativa o registro. Defina usando um número inteiro e não com constantes PHP. Por exemplo, um valor de 48 (16 + 32) registrará consultas lentas que usam 'nenhum índice bom' (SERVER_QUERY_NO_GOOD_INDEX_USED = 16) ou nenhum índice (SERVER_QUERY_NO_INDEX_USED = 32). Um valor de 2.043 (1 + 2 + 8 + ... + 1.024) registrará todos os tipos de consulta lenta. Os tipos são os seguintes: SERVER_STATUS_IN_TRANS=1, SERVER_STATUS_AUTOCOMMIT=2, SERVER_MORE_RESULTS_EXISTS=8, SERVER_QUERY_NO_GOOD_INDEX_USED=16, SERVER_QUERY_NO_INDEX_USED=32, SERVER_STATUS_CURSOR_EXISTS=64, SERVER_STATUS_LAST_ROW_SENT=128, SERVER_STATUS_DB_DROPPED=256, SERVER_STATUS_NO_BACKSLASH_ESCAPES=512 e SERVER_QUERY_WAS_SLOW=1024.
`mysqlnd.mempool_default_size` int
  Tamanho padrão do pool de memória mysqlnd, que é usado pelos conjuntos de resultados.
`mysqlnd.net_read_timeout` int
  `mysqlnd` e a Biblioteca Cliente MySQL, `libmysqlclient` usam APIs de rede diferentes. `mysqlnd` usa fluxos PHP, enquanto `libmysqlclient` usa seus próprio encapsulador em torno das chamadas de rede de nível operacional. O PHP, por padrão, define um tempo limite de leitura de 60s para fluxos. Isso é definido via php.ini, `default_socket_timeout`. Esse padrão se aplica a todos os fluxos que não definem nenhum outro valor de tempo limite. `mysqlnd` não define nenhum outro valor e, portanto, conexões de consultas de longa execução podem ser desconectadas após `default_socket_timeout` segundos, resultando em uma mensagem de erro 2006 - MySQL Server has gone away. A biblioteca cliente MySQL define um tempo limite padrão de 24 * 3600 segundos (1 dia) e espera que outros tempos limite ocorram, como tempos limites de TCP/IP. `mysqlnd` agora usa o mesmo tempo limite muito longo. O valor é configurável através de uma nova configuração php.ini: `mysqlnd.net_read_timeout`. `mysqlnd.net_read_timeout` é usado por qualquer extensão (`ext/mysql`, `ext/mysqli`, `PDO_MySQL`) que usa `mysqlnd`. `mysqlnd` diz aos fluxos PHP para usar `mysqlnd.net_read_timeout`. Favor observar que pode haver diferenças sutis entre `MYSQL_OPT_READ_TIMEOUT` da Biblioteca Cliente MySQL e fluxos PHP, por exemplo `MYSQL_OPT_READ_TIMEOUT` está documentado para funcionar apenas para conexões TCP/IP e, antes do MySQL 5.1.2, apenas para Windows. Os fluxos PHP podem não ter essa limitação. Por favor, verifique a documentação dos fluxos, em caso de dúvida.
`mysqlnd.net_cmd_buffer_size` int
  `mysqlnd` aloca um buffer interno de comando/rede de `mysqlnd.net_cmd_buffer_size` (no php.ini) bytes para cada conexão. Se um comando do protocolo MySQL cliente-servidor, por exemplo, `COM_QUERY` (consulta normal), não couber no buffer, `mysqlnd` aumentará o buffer ao tamanho necessário para enviar o comando. Sempre que o buffer for estendido para uma conexão, `command_buffer_too_small` será incrementado em um. Se `mysqlnd` tiver que aumentar o buffer além do tamanho inicial de `mysqlnd.net_cmd_buffer_size` bytes para quase todas as conexões, você deve considerar aumentar o tamanho padrão para evitar realocações. O tamanho do buffer padrão é 4.096 bytes, que é o menor valor possível. O valor também pode ser definido usando `mysqli_options(link, MYSQLI_OPT_NET_CMD_BUFFER_SIZE, size)`.
`mysqlnd.net_read_buffer_size` int
  Tamanho máximo do bloco de leitura em bytes ao ler o corpo de um pacote de comando MySQL. O protocolo cliente-servidor MySQL encapsula todos os seus comandos em pacotes. Os pacotes consistem em um pequeno cabeçalho e um corpo com a carga útil real. O tamanho do corpo está codificado no cabeçalho. `mysqlnd` lê o corpo em pedaços de `MIN(header.size, mysqlnd.net_read_buffer_size)` bytes. Se o corpo de um pacote for maior que `mysqlnd.net_read_buffer_size` bytes, `mysqlnd` terá que chamar `read()` múltiplas vezes. O valor também pode ser definido usando `mysqli_options(link, MYSQLI_OPT_NET_READ_BUFFER_SIZE, size)`.
`mysqlnd.sha256_server_public_key` string
  Relacionado ao plug-in de autenticação SHA-256. Arquivo com a chave RSA pública do servidor MySQL. Os clientes podem omitir a configuração de uma chave RSA pública, especificar a chave através desta configuração do PHP ou definir a chave em tempo de execução usando mysqli_options(). Se nenhum arquivo de chave RSA pública for fornecido pelo cliente, a chave será trocada como parte do procedimento de autenticação padrão do plug-in de autenticação SHA-256.
`mysqlnd.trace_alloc` string
`mysqlnd.fetch_data_copy` int
  Impõe cópia de conjuntos de resultados dos buffers internos do conjunto de resultados em variáveis ​​PHP em vez de usar a referência padrão e a lógica de cópia na gravação. Por favor, veja as notas de implementação de gerenciamento de memória para mais detalhes. Copiar conjuntos de resultados em vez de fazer referência a variáveis ​​PHP permite liberar a memória ocupada pelas variáveis ​​PHP anteriormente. Dependendo do código da API do usuário, das consultas reais do banco de dados e do tamanho de seus conjuntos de resultados, isso pode reduzir o consumo de memória do mysqlnd. Não defina se estiver usando PDO_MySQL. PDO_MySQL ainda não foi atualizado para suportar o novo modo de busca.

  > Nota: Removido a partir do PHP 8.1.0

# Incompatibilidades

O Driver Nativo MySQL é na maioria dos casos compatível com a Biblioteca Cliente MySQL (`libmysql`). Esta seção documenta incompatibilidades entre estas bibliotecas.

- Valores do tipo de dados `bit` são retornados como strings binárias (por exemplo, "\0" ou "\x1F") com `libmysql` e como strings decimais (por exemplo, "0" ou "31 ") com `mysqlnd`. Se for desejado que o código seja compatível com ambas as bibliotecas, então os campos de bits devem ser sempre retornados como números do MySQL com uma consulta como esta: `SELECT bit + 0 FROM table`.

# Conexões Persistentes

Usando Conexões Persistentes

Se `mysqli` for usada com `mysqlnd`, quando uma conexão persistente for criada ela gera uma chamada `COM_CHANGE_USER` (`mysql_change_user()`) no servidor. Isto assegura que a re-autenticação da conexão aconteça.

Como existe uma certa sobrecarga com a chamada `COM_CHANGE_USER`, é possível desligar isto em tempo de compilação. O reúso de uma conexão persistente irá gerar uma chamada `COM_PING` (`mysql_ping`) para simplesmente testar se a conexão é reutilizável.

A geração de `COM_CHANGE_USER` pode ser desligada com a opção de compilação `MYSQLI_NO_CHANGE_USER_ON_PCONNECT`. Por exemplo:

    shell# CFLAGS="-DMYSQLI_NO_CHANGE_USER_ON_PCONNECT" ./configure --with-mysql=/usr/local/mysql/ --with-mysqli=/usr/local/mysql/bin/mysql_config --with-pdo-mysql=/usr/local/mysql/bin/mysql_config --enable-debug && make clean && make -j6

Ou alternativamente:

    shell# export CFLAGS="-DMYSQLI_NO_CHANGE_USER_ON_PCONNECT"
    shell# configure --whatever-option
    shell# make clean
    shell# make

Observe que somente `mysqli` sobre `mysqlnd` usa `COM_CHANGE_USER`. Outras compinações de extensão-driver usam `COM_PING` no uso inicial de uma conexão persistente.

# Estatísticas

O Driver Nativo MySQL contém suporte para coleta de estatísticas sobre a comunicação entre o cliente e o servidor. As estatísticas recolhidas são de dois tipos principais:

- Estatísticas de cliente
- Estatísticas de conexão

Ao usar a extensão mysqli, essas estatísticas poderão ser obtidas através de duas chamadas de API:

- mysqli_get_client_stats()
- mysqli_get_connection_stats()

> Nota: As estatísticas são agregadas entre todas as extensões que utilizam o Driver Nativo MySQL. Por exemplo, se a extensão mysqli e o driver PDO MySQL estiverem ambos configurados para usar MySQLnd, as chamadas de função de mysqli e chamadas de métodos do PDO afetarão as estatísticas. Não há como saber o quanto uma determinada chamada de API de qualquer extensão que tenha sido compilada contra o Driver Nativo MySQL tenha impactado uma determinada estatística.

## Obtendo estatísticas

Estatísticas do cliente podem ser obtidas chamando a função mysqli_get_client_stats()

Estatísticas de conexão podem ser obtidas chamando a função mysqli_get_connection_stats().

Ambas as funções retornam um array associativo, onde o nome da estatística é a chave para o dado estatístico correspondente.

## Estatísticas do Driver Nativo MySQL

A maior parte das estatíticas são associadas a uma conexão mas algumas são associadas ao processo, e neste caso isto será mencionado no texto.

As seguintes estatísticas são produzidas pelo Driver Nativo MySQL:

Estatísticas Relacionadas à Rede
`bytes_sent`
  Número de bytes enviados do PHP para o servidor MySQL.
`bytes_received`
  Número de bytes recebidos do servidor MySQL.
`packets_sent`
  Número de pacotes enviados pelo protocolo Cliente Servidor do MySQL.
`packets_received`
  Número de pacotes recebidos pelo protocolo Cliente Servidor do MySQL.
`protocol_overhead_in`
  Sobrecarga do protocolo Cliente Servidor do MySQL em bytes para o tráfego de entrada. Atualmente apenas o Cabeçalho do Pacote (4 bytes) é considerado como sobrecarga. `protocol_overhead_in = packets_received * 4`
`protocol_overhead_out`
  Sobrecarga do protocolo Cliente Servidor do MySQL em bytes para o tráfego de saída. Atualmente apenas o Cabeçalho do Pacote (4 bytes) é considerado como sobrecarga. `protocol_overhead_out = packets_received * 4`
`bytes_received_ok_packet`
  Tamanho total em bytes de pacotes OK recebidos pelo protocolo Cliente Servidor do MySQL. Pacotes OK podem conter uma mensagem de status. O comprimento da mensagem de status pode variar e portanto o tamanho de um pacote OK não é fixo.

  > Nota: O tamanho total em bytes inclui o tamanho do pacote de cabeçalho. (4 bytes, consulte sobre sobrecarga do protocolo)

`packets_received_ok`
  Número de pacotes OK recebidos pelo protocolo Cliente Servidor do MySQL.
`bytes_received_eof_packet`
  Tamanho total em bytes de pacotes EOF recebidos pelo protocolo Cliente Servidor do MySQL. EOF pode variar em tamanho dependendo da versão do servidor. Além disso, EOF pode transportar uma mensagem de erro.

  > Nota: O tamanho total em bytes inclui o tamanho do pacote de cabeçalho. (4 bytes, consulte sobre sobrecarga do protocolo)

`packets_received_eof`
  Número de pacotes EOF recebidos pelo protocolo Cliente Servidor do MySQL. Como acontece com outras estatísticas de pacotes, o número de pacotes será incrementado mesmo se o PHP não receber o pacote esperado mas, por exemplo, receber uma mensagem de erro.
`bytes_received_rset_header_packet`
  Tamanho total em bytes dos pacotes de cabeçalho do conjunto de resultados recebido pelo protocolo Cliente Servidor do MySQL. O tamanho dos pacotes varia dependendo da carga (`LOAD LOCAL INFILE`, `INSERT`, `UPDATE`, `SELECT`, mensagem de erro).

  > Nota: O tamanho total em bytes inclui o tamanho do pacote de cabeçalho. (4 bytes, consulte sobre sobrecarga do protocolo)

`packets_received_rset_header`
  Número de pacotes de cabeçalho de conjunto de resultados recebidos pelo protocolo Cliente Servidor do MySQL.
`bytes_received_rset_field_meta_packet`
  Tamanho total em bytes de pacotes de metadados (informação de campo) de conjunto de resultados recebidos pelo protocolo Cliente Servidor do MySQL. É evidente que o tamanho varia com os campos no conjunto de resultados. O pacotes também pode transportar um pacote de erro ou de EOF em caso de COM_LIST_FIELDS.

  > Nota: O tamanho total em bytes inclui o tamanho do pacote de cabeçalho. (4 bytes, consulte sobre sobrecarga do protocolo)

`packets_received_rset_field_meta`
  Número de pacotesde metadados (informação de campo) de conjunto de resultados recebidos pelo protocolo Cliente Servidor do MySQL.
`bytes_received_rset_row_packet`
  Tamanho total em bytes dos pacotes de dados de registros do conjunto de resultados recebidos pelo protocolo Cliente Servidor do MySQL. O pacote também pode transportar uma mensagem de erro ou de EOF. Pode-se computar o número de pacotes de erro e de EOF subtraindo-se `rows_fetched_from_server_normal` e `rows_fetched_from_server_ps` de `bytes_received_rset_row_packet`.

  > Nota: O tamanho total em bytes inclui o tamanho do pacote de cabeçalho. (4 bytes, consulte sobre sobrecarga do protocolo)

`packets_received_rset_row`
  Número de pacotes de dados de registros do conjunto de resultados recebidos pelo protocolo Cliente Servidor do MySQL.
`bytes_received_prepare_response_packet`
  Tamanho total em bytes dos pacotes de Inicialização OK para Instruções Preparadas (pacotes de inicialização de instrução preparada) recebidos pelo protocolo Cliente Servidor do MySQL. O pacote também pode transportar um erro. O tamanho do pacote depende da versão MySQL.

  > Nota: O tamanho total em bytes inclui o tamanho do pacote de cabeçalho. (4 bytes, consulte sobre sobrecarga do protocolo)

`packets_received_prepare_response`
  Número de pacotes de inicialização de instruções preparadas recebidos pelo protocolo Cliente Servidor do MySQL.
`bytes_received_change_user_packet`
  Tamanho total em bytes de pacotes COM_CHANGE_USER recebidos pelo protocolo Cliente Servidor do MySQL. O pacote também pode transportar um erro ou um EOF.

  > Nota: O tamanho total em bytes inclui o tamanho do pacote de cabeçalho. (4 bytes, consulte sobre sobrecarga do protocolo)

`packets_received_change_user`
  Número de pacotes COM_CHANGE_USER recebidos pelo protocolo Cliente Servidor do MySQL.
`packets_sent_command`
  Número de comandos do protocolo Cliente Servidor do MySQL enviados pelo PHP ao MySQL. Não há como saber quais foram os comandos específicos e quantos deles foram enviados.
`bytes_received_real_data_normal`
  Número de bytes dos dados reais buscados pelo cliente PHP vindos do `mysqlnd` usando o protocolo de texto. Este é o tamanho dos dados reais contidos nos conjuntos de resultados que não se originaram de instruções preparadas e que foram buscados pelo cliente PHP. Observe que embora um conjunto de resultados completo possa ter sido puxado do MySQL pelo `mysqlnd`, esta estatística apenas conta dados reais puxados a partir do `mysqlnd` pelo cliente PHP.

  A seguir é apresentado um exemplo de sequência de código que irá incrementar o valor:

      $mysqli = new mysqli();
      $res = $mysqli->query("SELECT 'abc'");
      $res->fetch_assoc();
      $res->close();

  Cada operação de busca irá incrementar o valor.

  Entretanto, a estatística não será incrementada se o conjunto de resultados estiver sujeito a buffer no lado do cliente mas não for buscado, como no exemplo a seguir:

      $mysqli = new mysqli();
      $res = $mysqli->query("SELECT 'abc'");
      $res->close();

`bytes_received_real_data_ps`
  Número de bytes dos dados reais buscados pelo cliente PHP vindos do `mysqlnd` usando o protocolo de instruções preparadas. Este é o tamanho dos dados reais contidos nos conjuntos de resultados que se originaram de instruções preparadas e que foram buscados pelo cliente PHP. O valor não será incrementado se o conjunto de resultados não for subsequentemente lido pelo cliente PHP. Observe que embora um conjunto de resultados completo possa ter sido puxado do MySQL pelo `mysqlnd`, esta estatística apenas conta dados reais puxados a partir do `mysqlnd` pelo cliente PHP. Consulte também `bytes_received_real_data_normal`.

Estatísticas Relacionadas ao Conjunto de Resultados
`result_set_queries`
  Número de consultas que geraram um conjunto de resultados. Exemplos de consultas que geram um conjunto de resultados: `SELECT`, `SHOW`. A estatística não será incrementada se ocorrer um erro ao ler o pacote de cabeçalho do conjunto de resultados.

  > Nota: Esta estatística pode ser usada como uma medição indireta do número de consultas que o PHP enviou ao MySQL. Isto pode ajudar a identificar um cliente que causa uma carga alta no banco de dados.

`non_result_set_queries`
  Número de consultas que não geraram um conjunto de resultados. Exemplos de consultas que não geram um conjunto de resultados: `INSERT`, `UPDATE`, `LOAD DATA`. A estatística não será incrementada se ocorrer um erro ao ler o pacote de cabeçalho do conjunto de resultados.

  > Nota: Esta estatística pode ser usada como uma medição indireta do número de consultas que o PHP enviou ao MySQL. Isto pode ajudar a identificar um cliente que causa uma carga alta no banco de dados.

`no_index_used`
  Número de consultas que geraram um conjunto de resultados mas não usaram um índice. (Consulte também a opção de início do mysqld `--log-queries-not-using-indexes`).

  > Nota: Essas consultas podem ser reportadas através de uma exceção com `mysqli_report(MYSQLI_REPORT_INDEX);`. É possível reportá-las também através de um alerta com `mysqli_report(MYSQLI_REPORT_INDEX ^ MYSQLI_REPORT_STRICT);`.

`bad_index_used`
  Número de consultas que geraram um conjunto de resultados e não usaram um índice bom. (Consulte também a opção de início do mysqld `--log-slow-queries`).

  > Nota: Essas consultas podem ser reportadas através de uma exceção com `mysqli_report(MYSQLI_REPORT_INDEX);`. É possível reportá-las também através de um alerta com `mysqli_report(MYSQLI_REPORT_INDEX ^ MYSQLI_REPORT_STRICT);`.

`slow_queries`
  Instruções SQL que levaram mais de `long_query_time` segundos para execução e requereram que pelo menos `min_examined_row_limit` registros fossem examinados.
  Cuidado

  Não reportada através de mysqli_report().

`buffered_sets`
  Número de conjuntos de resultados em buffer retornados por consultas normais (isto é, não por via de instrução preparada).

  Exemplos de chamadas API que armazenarão conjuntos de resultados em buffer no cliente: mysqli_query(), mysqli_store_result(), mysqli_stmt_get_result()

`unbuffered_sets`
  Número de conjuntos de resultados sem buffer retornados por consultas normais (isto é, não por via de instrução preparada).

  Exemplos de chamadas API que não armazenarão conjuntos de resultados em buffer no cliente: mysqli_use_result()

`ps_buffered_sets`
  Número de conjuntos de resultados em buffer retornados por instruções preparadas.

  Exemplos de chamadas API que armazenarão conjuntos de resultados em buffer no cliente: mysqli_stmt_store_result()

`ps_unbuffered_sets`
  Número de conjuntos de resultados sem buffer retornados por instruções preparadas. Por padrão, instruções preparadas não são armazenadas em buffer, portanto a maioria das instruções preparadas será considerada nesta estatísitica.
`flushed_normal_sets`
  Número de conjuntos de resultados retornados por consultas normais (isto é, não por via de instrução preparada) com dados não lidos que foram silenciosamente descarregados.

  > Nota: Os descarregamento ocorre somente com conjuntos de resultados sem buffer. Conjuntos de resultados sem buffer devem ser buscados integralmente antes que uma nova consulta possa ser executada na conexão, caso contrário o MySQL lançará um erro. Se a aplicação não buscar todos os registros de um conjunto de resultados sem buffer, o mysqlnd não busca implicitamente o conjunto de resultados para limpar a linha de dados. Consulta também `rows_skipped_normal`, `rows_skipped_ps`.

  > Algumas causas possíveis para um descarregamento implícito:

  > - Aplicação cliente com falhas
  > - Cliente parou de ler depois de ter encontrado o que estava procurando mas fez o MySQL calcular mais registros que o necessário
  > - Aplicação cliente parou inesperadamente

`flushed_ps_sets`
  Número de conjuntos de resultados de instruções preparadas com dados não lidos que foram silenciosamente descarregados.

  > Nota: Os descarregamento ocorre somente com conjuntos de resultados sem buffer. Conjuntos de resultados sem buffer devem ser buscados integralmente antes que uma nova consulta possa ser executada na conexão, caso contrário o MySQL lançará um erro. Se a aplicação não buscar todos os registros de um conjunto de resultados sem buffer, o mysqlnd não busca implicitamente o conjunto de resultados para limpar a linha de dados. Consulta também `rows_skipped_normal`, `rows_skipped_ps`.

  > Algumas causas possíveis para um descarregamento implícito:

  > - Aplicação cliente com falhas
  > - Cliente parou de ler depois de ter encontrado o que estava procurando mas fez o MySQL calcular mais registros que o necessário
  > - Aplicação cliente parou inesperadamente

`ps_prepared_never_executed`
  Número de intruções preparadas mas nunca executadas.
`ps_prepared_once_executed`
  Número de intruções preparadas executadas apenas uma vez.
`rows_fetched_from_server_normal`
`rows_fetched_from_server_ps`
  Número total de registros do conjunto de resultados buscados do servidor. Isto inclui os registros que não foram lidos pelo cliente mas foram buscados implicitamente devido a conjuntos de resultados sem buffer descarregados. Consulte também `packets_received_rset_row`.
`rows_buffered_from_client_normal`
  Número total de registros em buffer originários de uma consulta normal. Este é o número de registros que foram buscados do MySQL e armazenados em buffer no cliente.

  Exemplos de consultas que irão armazenar resultados em buffer:

  - mysqli_query()
  - mysqli_store_result()
`rows_buffered_from_client_ps`
  O mesmo que `rows_buffered_from_client_normal`, porém para instruções preparadas.
`rows_fetched_from_client_normal_buffered`
  Número total de registros buscados pelo cliente a partir de um conjunto de resultados em buffer criado por uma consulta normal.
`rows_fetched_from_client_ps_buffered`
  Número total de registros buscados pelo cliente a partir de um conjunto de resultados em buffer criado por uma instrução preparada.
`rows_fetched_from_client_normal_unbuffered`
  Número total de registros buscados pelo cliente a partir de um conjunto de resultados sem buffer criado por uma consulta normal.
`rows_fetched_from_client_ps_unbuffered`
  Número total de registros buscados pelo cliente a partir de um conjunto de resultados sem buffer criado por uma instrução preparada.
`rows_fetched_from_client_ps_cursor`
  Número total de registros buscados pelo cliente a partir de um cursor criado por uma instrução preparada.
`rows_skipped_normal`
`rows_skipped_ps`
  Reservada para uso futuro (atualmente não suportada).
`copy_on_write_saved`
`copy_on_write_performed`
  Esta é uma estatística cujo escopo está no nível de processo. Com o mysqlnd, variáveis retornadas pelas extensões apontam para os buffers de resultados da rede interna do mysqlnd. Se os dados não foram modificados, os dados buscados são mantidos apenas uma vez na memória. Entretanto, qualquer modificação nos dados irá requerer que o mysqlnd realize uma operação de cópia-na-escrita.
`explicit_free_result`
`implicit_free_result`
  Esta é uma estatística cujo escopo está no nível de conexão e de processo. Número total de conjuntos de resultados liberados.
`proto_text_fetched_null`
  Número total de colunas do tipo `MYSQL_TYPE_NULL` buscadas por uma consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_null`
  Número total de colunas do tipo `MYSQL_TYPE_NULL` buscadas por uma instrução preparada (protocolo binário MySQL).
`proto_text_fetched_bit`
  Número total de colunas do tipo `MYSQL_TYPE_BIT` buscadas por uma consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_bit`
  Número total de colunas do tipo `MYSQL_TYPE_BIT` buscadas por uma instrução preparada (protocolo binário MySQL).
`proto_text_fetched_tinyint`
  Número total de colunas do tipo `MYSQL_TYPE_TINY` buscadas por uma consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_tinyint`
  Número total de colunas do tipo `MYSQL_TYPE_TINY` buscadas por uma instrução preparada (protocolo binário MySQL).
`proto_text_fetched_short`
  Número total de colunas do tipo `MYSQL_TYPE_SHORT` buscadas por uma consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_short`
  Número total de colunas do tipo `MYSQL_TYPE_SHORT` buscadas por uma instrução preparada (protocolo binário MySQL).
`proto_text_fetched_int24`
  Número total de colunas do tipo `MYSQL_TYPE_INT24` buscadas por uma consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_int24`
  Número total de colunas do tipo `MYSQL_TYPE_INT24` buscadas por uma instrução preparada (protocolo binário MySQL).
`proto_text_fetched_int`
  Número total de colunas do tipo `MYSQL_TYPE_LONG` buscadas por uma consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_int`
  Número total de colunas do tipo `MYSQL_TYPE_LONG` buscadas por uma instrução preparada (protocolo binário MySQL).
`proto_text_fetched_bigint`
  Número total de colunas do tipo `MYSQL_TYPE_LONGLONG` buscadas por uma consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_bigint`
  Número total de colunas do tipo `MYSQL_TYPE_LONGLONG` buscadas por uma instrução preparada (protocolo binário MySQL).
`proto_text_fetched_decimal`
  Número total de colunas dos tipos `MYSQL_TYPE_DECIMAL` ou `MYSQL_TYPE_NEWDECIMAL` buscadas por uma consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_decimal`
  Número total de colunas dos tipos `MYSQL_TYPE_DECIMAL` ou `MYSQL_TYPE_NEWDECIMAL` buscadas por uma instrução preparada (protocolo binário MySQL).
`proto_text_fetched_float`
  Número total de colunas do tipo `MYSQL_TYPE_FLOAT` buscadas por uma consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_float`
  Número total de colunas do tipo `MYSQL_TYPE_FLOAT` buscadas por uma instrução preparada (protocolo binário MySQL).
`proto_text_fetched_double`
  Número total de colunas do tipo `MYSQL_TYPE_DOUBLE` buscadas por uma consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_double`
  Número total de colunas do tipo `MYSQL_TYPE_DOUBLE` buscadas por uma instrução preparada (protocolo binário MySQL).
`proto_text_fetched_date`
  Número total de colunas do tipo `MYSQL_TYPE_DATE` ou `MYSQL_TYPE_NEWDATE` buscadas por uma consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_date`
  Número total de colunas do tipo `MYSQL_TYPE_DATE` ou `MYSQL_TYPE_NEWDATE` buscadas por uma instrução preparada (protocolo binário MySQL).
`proto_text_fetched_year`
  Número total de colunas do tipo `MYSQL_TYPE_YEAR` buscadas por uma consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_year`
  Número total de colunas do tipo `MYSQL_TYPE_YEAR` buscadas por uma instrução preparada (protocolo binário MySQL).
`proto_text_fetched_time`
  Número total de colunas do tipo `MYSQL_TYPE_TIME` buscadas por uma consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_time`
  Número total de colunas do tipo `MYSQL_TYPE_TIME` buscadas por uma instrução preparada (protocolo binário MySQL).
`proto_text_fetched_datetime`
  Número total de colunas do tipo `MYSQL_TYPE_DATETIME` buscadas por uma consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_datetime`
  Número total de colunas do tipo `MYSQL_TYPE_DATETIME` buscadas por uma instrução preparada (protocolo binário MySQL).
`proto_text_fetched_timestamp`
  Número total de colunas do tipo `MYSQL_TYPE_TIMESTAMP` buscadas por uma consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_timestamp`
  Número total de colunas do tipo `MYSQL_TYPE_TIMESTAMP` buscadas por uma instrução preparada (protocolo binário MySQL).
`proto_text_fetched_string`
  Número total de colunas dos tipos `MYSQL_TYPE_STRING`, `MYSQL_TYPE_VARSTRING` ou `MYSQL_TYPE_VARCHAR` buscadas por uma consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_string`
  Número total de colunas dos tipos `MYSQL_TYPE_STRING`, `MYSQL_TYPE_VARSTRING` ou `MYSQL_TYPE_VARCHAR` buscadas por uma instrução preparada (protocolo binário MySQL).
`proto_text_fetched_blob`
  Número total de colunas dos tipos `MYSQL_TYPE_TINY_BLOB`, `MYSQL_TYPE_MEDIUM_BLOB`, `MYSQL_TYPE_LONG_BLOB` ou `MYSQL_TYPE_BLOB` buscadas por uma consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_blob`
  Número total de colunas dos tipos `MYSQL_TYPE_TINY_BLOB`, `MYSQL_TYPE_MEDIUM_BLOB`, `MYSQL_TYPE_LONG_BLOB` ou `MYSQL_TYPE_BLOB` buscadas por uma instrução preparada (protocolo binário MySQL).
`proto_text_fetched_enum`
  Número total de colunas do tipo `MYSQL_TYPE_ENUM` buscadas por uma consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_enum`
  Número total de colunas do tipo `MYSQL_TYPE_ENUM` buscadas por uma instrução preparada (protocolo binário MySQL).
`proto_text_fetched_set`
  Número total de colunas do tipo `MYSQL_TYPE_SET` buscadas por uma consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_set`
  Número total de colunas do tipo `MYSQL_TYPE_SET` buscadas por uma instrução preparada (protocolo binário MySQL).
`proto_text_fetched_geometry`
  Número total de colunas do tipo `MYSQL_TYPE_GEOMETRY` buscadas por uma consulta normal (protocolo de texto MySQL).
`proto_binary_fetched_geometry`
  Número total de colunas do tipo `MYSQL_TYPE_GEOMETRY` buscadas por uma instrução preparada (protocolo binário MySQL).
`proto_text_fetched_other`
  Número total de colunas dos tipos `MYSQL_TYPE_*` não listadas previamente e buscadas por uma consulta normal (protocolo de texto MySQL).

  > Nota: Em teoria, deveria ser sempre `0`.

`proto_binary_fetched_other`
  Número total de colunas dos tipos `MYSQL_TYPE_*` não listadas previamente e buscadas por uma instrução preparada (protocolo binário MySQL).

  > Nota: Em teoria, deveria ser sempre `0`.

Estatísticas Relacionadas a Conexões
`connect_success`
  Número total de tentativas bem sucedidas de conexões.

  > Nota: `connect_success` contém a soma de tentativas bem sucedidas de conexões persistentes e não persistentes. Portanto, o número de tentativas bem sucedidas de conexões não persistentes é `connect_success - pconnect_success`.

`pconnect_success`
  Número total de tentativas bem sucedidas de conexões persistentes.
`connect_failure`
  Número total de tentativas falhadas de conexões.
`reconnect`
  Esta é uma estatística cujo escopo está no nível de processo.
`active_connections`
  Esta é uma estatística cujo escopo está no nível de processo. Número total de conexões ativas, persistentes e não persistentes.

  > Nota: Número total de conexões ativas não persistentes é `active_connections - active_persistent_connections`.

`active_persistent_connections`
  Esta é uma estatística cujo escopo está no nível de processo. Número total de conexões ativas persistentes.
`explicit_close`
  Número total de conexões fechadas explicitamente.

  Exemplo #1 Exemplos de trechos de código que causam um fechamento explícito

  -     $link = new mysqli(/* ... */);
        $link->close(/* ... */);

  -     $link = new mysqli(/* ... */);
        $link->connect(/* ... */);

`implicit_close`
  Número total de conexões fechadas implicitamente.

  Exemplo #2 Exemplos de trechos de código que causam um fechamento implícito

  -     $link = new mysqli(/* ... */);
        $link->real_connect(/* ... */);

  - `unset($link)`
  - Conexão persistente: conexão em fila foi criada com real_connect e podem haver opções desconhecidas definidas - fecha implicitamente para evitar o retorno de uma conexão com opções desconhecidas
  - Conexão persistente: ping/change_user falha e a extensão mysqli fecha a conexão
  - Fim de execução de script: fecha conexões que não foram fechadas pelo usuário
`disconnect_close`
  Falhas de conexão indicadas pela chamada API C `mysql_real_connect` durante uma tentativa de se estabalecer uma conexão.
`in_middle_of_command_close`
  Esta é uma estatística cujo escopo está no nível de processo. Uma conexão foi fechada no meio de uma execução de comando (conjuntos de resultados não buscados, após enviar uma consulta e antes de receber uma resposta, durante a busca de dados, enquanto dados são transferidos com LOAD DATA).
  Aviso

  A menos que consultas assíncronas sejam usadas, isto só deve acontecer se a aplicação PHP terminar inesperadamente e o PHP fechar a conexão automaticamente.

`init_command_executed_count`
  Número total de execuções do comando init. Por exemplo: `mysqli_options(MYSQLI_INIT_COMMAND , $value)`. O número total de execuções bem sucedidas é `init_command_executed_count - init_command_failed_count`.
`init_command_failed_count`
  Número total de comandos init falhados.

Estatísticas Relacionadas aos Comandos `COM_*`
`com_quit`
`com_init_db`
`com_query`
`com_field_list`
`com_create_db`
`com_drop_db`
`com_refresh`
`com_shutdown`
`com_statistics`
`com_process_info`
`com_connect`
`com_process_kill`
`com_debug`
`com_ping`
`com_time`
`com_delayed_insert`
`com_change_user`
`com_binlog_dump`
`com_table_dump`
`com_connect_out`
`com_register_slave`
`com_stmt_prepare`
`com_stmt_execute`
`com_stmt_send_long_data`
`com_stmt_close`
`com_stmt_reset`
`com_stmt_set_option`
`com_stmt_fetch`
`com_daemon`
  Número total de tentativas de envio de um certo comando `COM_*` do PHP para o MySQL. As estatísticas são incrementadas após verificação da linha de dados e imediatamente antes do envio do pacote correspondente do protocolo Cliente Servidor do MySQL.
  Cuidado

  Se o MySQLnd falhar ao enviar o pacote pela rede, a estatística não será decrementada. Em caso de falha, o MySQLnd emite um alerta do PHP Error while sending %s packet. PID=%d.

  Exemplo #3 Exemplos de uso

  - Verificar se o PHP envia certos comandos ao MySQL, por exemplo, verificar se o cliente envia `COM_PROCESS_KILL`
  - Calcular o número médio de execuções de instruções preparadas comparando `COM_EXECUTE` com `COM_PREPARE`
  - Verificar se o PHP executou alguma instrução SQL não preparada observando se `COM_QUERY` é igual a zero
  - Identificar scripts PHP que executam um número excessivo de instruções SQL, verificando `COM_QUERY` e `COM_EXECUTE`

Estatísticas Miscelâneas
`explicit_stmt_close`
`implicit_stmt_close`
  Esta é uma estatística cujo escopo está no nível de processo. Número total de instruções preparadas fechadas.

  > Nota: Uma instrução preparada é sempre fechada explicitamente. O único momento em que ela é fechaada implicitamente é quando sua preparação falha.

`mem_emalloc_count`
`mem_emalloc_ammount`
`mem_ecalloc_count`
`mem_ecalloc_ammount`
`mem_realloc_count`
`mem_realloc_ammount`
`mem_efree_count`
`mem_malloc_count`
`mem_malloc_ammount`
`mem_calloc_count`
`mem_calloc_ammount`
`mem_ealloc_count`
`mem_ealloc_ammount`
`mem_free_count`
  Esta é uma estatística cujo escopo está no nível de processo. Chamadas de gerenciamento de memória.
`command_buffer_too_small`
  Número de extensões de buffer de comandos de rede ao enviar comandos do PHP para o MySQL. MySQLnd aloca um buffer interno de comando/rede de mysqlnd.net_cmd_buffer_size bytes para cada conexão. Se um comando do protocolo Cliente Servidor do MySQL, por exemplo `COM_QUERY` (consulta normal), não couber no buffer, o MySQLnd aumentará o buffer para o tamanho necessário para envio do comando. Sempre que o buffer for estendido para uma conexão, `command_buffer_too_small` será incrementada em uma unidade. Se o MySQLnd tiver que aumentar o buffer para além do seu tamanho inicial de mysqlnd.net_cmd_buffer_size bytes para quase todas as conexões, deve ser considerado aumento do tamanho padrão para evitar realocações.
`connection_reused`
  O número total de vezes em que uma conexão persistente foi reutilizada.

# Notas

Esta seção fornece uma coleção de notas miscelâneas sobre o uso do Driver Nativo MySQL.

- Usar `mysqlnd`significa usar fluxos PHP para conectividades subjacente. Para `mysqlnd`, a documentação de fluxos do PHP (Fluxos) deve ser consultada sobre detalhes como configurações de limites de tempo, e não a documentação para a Biblioteca Cliente do MySQL.

# Gerenciamento de Memória

Introdução

O Driver Nativo MySQL gerencia memória diferente da Biblioteca Cliente MySQL. As bibliotecas diferem na forma como a memória é alocada e liberada, como a memória é alocada em pedaços durante a leitura dos resultados do MySQL, quais opções de depuração e desenvolvimento existem e como os resultados lidos do MySQL são vinculados às variáveis ​​de usuário do PHP.

As notas a seguir pretendem ser uma introdução e um resumo aos usuários interessados ​​em compreender o Driver Nativo MySQL em nível de código C.

Funções de gerenciamento de memória usadas

Toda a alocação e desalocação de memória é feita usando as funções de gerenciamento de memória do PHP. Portanto, o consumo de memória do mysqlnd pode ser rastreado usando chamadas de API PHP, como memory_get_usage(). Como a memória é alocada e liberada usando o gerenciamento de memória do PHP, as alterações podem não se tornar imediatamente visíveis no nível do sistema operacional. O gerenciamento de memória do PHP atua como um proxy que pode atrasar a liberação de memória para o sistema. Devido a isso, é difícil comparar o uso de memória do Driver Nativo MySQL e da Biblioteca Cliente MySQL. A Biblioteca Cliente MySQL está usando as chamadas de gerenciamento de memória do sistema operacional diretamente, portanto, os efeitos podem ser observados imediatamente no nível do sistema operacional.

Qualquer limite de memória imposto pelo PHP também afeta o Driver Nativo MySQL. Isso pode causar erros de falta de memória ao buscar conjuntos de resultados grandes que excedem o tamanho da memória restante disponibilizada pelo PHP. Como a Biblioteca Cliente MySQL não usa funções de gerenciamento de memória PHP, ela não está em conformidade com nenhum limite de memória PHP definido. Se estiver usando a Biblioteca Cliente MySQL, dependendo do modelo de implantação, o consumo de memória do processo PHP pode crescer além do limite de memória do PHP. Mas também os scripts PHP podem processar conjuntos de resultados maiores, pois partes da memória alocada para armazenar os conjuntos de resultados estão além do controle do mecanismo PHP.

As funções de gerenciamento de memória do PHP são invocadas pelo Driver Nativo MySQL através de um encapsulador leve. Entre outros, o encapsulador facilita a depuração.

Lidando com conjuntos de resultados

Os vários servidores MySQL e as diversas APIs do cliente diferenciam entre conjuntos de resultados com buffer e sem buffer. Conjuntos de resultados sem buffer são transferidos linha por linha do MySQL para o cliente à medida que o cliente itera sobre os resultados. Os resultados armazenados em buffer são buscados integralmente pela biblioteca cliente antes de serem repassados ​​ao cliente.

O Driver Nativo MySQL está utilizando fluxos PHP para a comunicação da rede com o Servidor MySQL. Os resultados enviados pelo MySQL são buscados dos buffers da rede de fluxos do PHP para o buffer de resultados do mysqlnd. O buffer resultante é composto de zvals. Numa segunda etapa os resultados são disponibilizados para o script PHP. Esta transferência final do buffer de resultados para variáveis ​​PHP impacta o consumo de memória e é principalmente perceptível ao usar conjuntos de resultados armazenados em buffer.

Por padrão o Driver Nativo MySQL tenta evitar armazenar resultados em buffer duas vezes na memória. Os resultados são mantidos apenas uma vez nos buffers de resultados internos e seus zvals. Quando os resultados são buscados em variáveis ​​PHP pelo script PHP, as variáveis ​​farão referência aos buffers de resultados internos. Os resultados da consulta ao banco de dados não são copiados e mantidos na memória apenas uma vez. Caso o usuário modifique o conteúdo de uma variável que contém os resultados do banco de dados, uma cópia na gravação deverá ser executada para evitar a alteração do buffer de resultados interno referenciado. O conteúdo do buffer não deve ser modificado porque o usuário pode decidir ler o conjunto de resultados uma segunda vez. O mecanismo de cópia na gravação é implementado usando uma lista de gerenciamento de referência adicional e o uso de contadores de referência zval padrão. A cópia na gravação também deve ser feita se o usuário ler um conjunto de resultados em variáveis ​​PHP e liberar um conjunto de resultados antes que as variáveis ​​sejam desdefinidas.

De modo geral, esse padrão funciona bem para scripts que leem um conjunto de resultados uma vez e não modificam variáveis ​​que contêm resultados. Sua principal desvantagem é a sobrecarga de memória causada pelo gerenciamento de referência adicional que vem principalmente do fato de que as variáveis ​​do usuário que contêm resultados não podem ser totalmente liberadas até que o gerenciamento de referência do mysqlnd pare de referenciá-las. O Driver Nativo MySQL remove a referência às variáveis ​​do usuário quando o conjunto de resultados é liberado ou uma cópia na gravação é executada. Um observador verá o consumo total de memória crescer até que o conjunto de resultados seja liberado. Use as estatísticas para verificar se um script libera conjuntos de resultados explicitamente ou se o driver faz liberações implícitas e, portanto, a memória é usada por um tempo maior que o necessário. As estatísticas também ajudam a ver quantas operações de cópia na gravação ocorreram.

Um script PHP lendo muitas linhas pequenas de um conjunto de resultados em buffer usando um trecho de código igual ou equivalente a `while ($row = $res->fetch_assoc()) { ... }` pode otimizar o consumo de memória solicitando cópias em vez de referências. Embora solicitar cópias signifique manter os resultados duas vezes na memória, isso permite que o PHP libere a cópia contida em `$row` à medida que o conjunto de resultados está sendo iterado e antes de liberar o próprio conjunto de resultados. Em um servidor carregado, a otimização do uso máximo de memória pode ajudar a melhorar o desempenho geral do sistema, embora para um script individual a abordagem de cópia possa ser mais lenta devido a alocações adicionais e operações de cópia de memória.

Monitoramento e depuração

Existem diversas formas de rastrear o uso de memória do Driver Nativo MySQL. Se o objetivo é obter uma visão geral rápida de alto nível ou verificar a eficiência da memória dos scripts PHP, então verifique as estatísticas coletadas pela biblioteca. As estatísticas permitem, por exemplo, capturar instruções SQL que geram mais resultados do que são processados ​​por um script PHP.

O log de rastreamento debug pode ser configurado para registrar chamadas de gerenciamento de memória. Isso ajuda a ver quando a memória está alocada ou liberada. No entanto, o tamanho dos blocos de memória solicitados pode não estar listado.

Algumas versões recentes do Driver Nativo MySQL apresentam a emulação de situações aleatórias de falta de memória. Este recurso deve ser usado apenas pelos desenvolvedores C da biblioteca ou pelos autores do plugin do mysqlnd. Por favor, pesquise no código-fonte as configurações correspondentes do PHP e mais detalhes. O recurso é considerado privado e pode ser modificado a qualquer momento sem aviso prévio.

# API do plugin do Driver Nativo MySQL

## Índice

- Uma comparação de plugins mysqlnd com Proxy MySQL
- Obtendo a API do plugin mysqlnd
- Arquitetura do Plugin do Driver Nativo MySQL
- A API do plugin mysqlnd
- Começando a construir um plugin mysqlnd

A API de plugin do Driver Nativo MySQL é um recurso do Driver Nativo MySQL, ou `mysqlnd`. Os plugins `Mysqlnd` operam na camada entre os aplicativos PHP e o servidor MySQL. Isso é comparável ao Proxy MySQL. O Proxy MySQL opera em uma camada entre qualquer aplicativo cliente MySQL, por exemplo, um aplicativo PHP e o servidor MySQL. Os plugins `Mysqlnd` podem realizar tarefas típicas do Proxy MySQL, como balanceamento de carga, monitoramento e otimizações de desempenho. Devido à arquitetura e localização diferentes, os plugins `mysqlnd` não apresentam algumas das desvantagens do Proxy MySQL. Por exemplo, com plugins, não há um ponto único de falha, nenhum servidor proxy dedicado para se implantar e nenhuma nova linguagem de programação para aprender (Lua).

Um plugin `mysqlnd` pode ser pensado como uma extensão do `mysqlnd`. Plugins podem interceptar a maioria das funções do `mysqlnd`. As funções `mysqlnd` são chamadas pelas extensões PHP MySQL como `ext/mysql`, `ext/mysqli` e `PDO_MYSQL`. Como resultado, é possível para um plugin `mysqlnd` interceptar todas as chamadas feitas para essas extensões a partir da aplicação cliente.

Chamadas internas de função `mysqlnd` também podem ser interceptadas ou substituídas. Não há restrições na manipulação de tabelas de funções internas do `mysqlnd`. É possível configurar as coisas para que quando certas funções `mysqlnd` sejam chamadas pelas extensões que usam `mysqlnd`, a chamada seja direcionada para a função apropriada no plugin `mysqlnd`. A capacidade de manipular tabelas de funções internas do `mysqlnd` desta forma permite máxima flexibilidade para plugins.

Plugins `Mysqlnd` são na verdade extensões PHP, escritas em C, que usam a API do plugin `mysqlnd` (que está embutida no Driver Nativo MySQL, `mysqlnd`) . Os plugins podem ser 100% transparentes para aplicações PHP. Nenhuma alteração na aplicação é necessária porque os plugins operam em uma camada diferente. O plugin `mysqlnd` pode ser pensado como operando em uma camada abaixo do `mysqlnd`.

A lista a seguir representa algumas aplicações possíveis de plugins `mysqlnd`.

- Balanceamento de Carga
  - Divisão de leitura/gravação. Um exemplo disso é a extensão PECL/mysqlnd_ms (Master Slave). Esta extensão divide consultas de leitura/gravação para uma configuração de replicação.
  - Failover
  - Round-Robin, menos carregado
- Monitoramento
  - Registro de Consultas
  - Análise de Consultas
  - Auditoria de Consultas. Um exemplo disso é a extensão PECL/mysqlnd_sip (Proteção Contra Injeção SQL). Esta extensão inspeciona consultas e executa apenas aquelas permitidas de acordo com um conjunto de regras.
- Desempenho
  - Cache. Um exemplo disso é a extensão PECL/mysqlnd_qc (Cache de Consultas).
  - Redução de velocidade
  - Fragmentação. Um exemplo disso é a extensão PECL/mysqlnd_mc (Multi Conexão). Esta extensão tentará dividir uma instrução SELECT em n partes, usando SELECT ... LIMIT part_1, SELECT LIMIT part_n. Ele envia as consultas para servidores MySQL distintos e mescla o resultado no cliente.

Plugins Disponíveis do Driver Nativo MySQL

Existem vários plug-ins do mysqlnd já disponíveis. Esses incluem:

- PECL/mysqlnd_mc - plugin Multi Conexão.
- PECL/mysqlnd_ms - plugin Master Slave.
- PECL/mysqlnd_qc - plugin Query Cache.
- PECL/mysqlnd_pscache - plugin de Cache de Manipulador de Instruções Preparadas.
- PECL/mysqlnd_sip - plugin de Proteção Contra Injeção SQL.
- PECL/mysqlnd_uh - plugin de Manipulador de Usuário.

## Uma comparação de plugins mysqlnd com Proxy MySQL

Plugins `Mysqlnd` e Proxy MySQL são tecnologias diferentes que usam abordagens diferentes. Ambas são ferramentas válidas para resolver uma variedade de tarefas comuns, como balanceamento de carga, monitoramento e melhorias de desempenho. Uma diferença importante é que o Proxy MySQL funciona com todos os clientes MySQL, enquanto os plugins `mysqlnd` são específicos para aplicações PHP.

Como uma extensão PHP, um plugin `mysqlnd` é instalado no servidor de aplicativos PHP, junto com o restante do PHP. O Proxy MySQL pode ser executado no servidor de aplicativos PHP ou pode ser instalado em uma máquina dedicada para lidar com vários servidores de aplicações PHP.

A implantação do Proxy MySQL no servidor de aplicativos tem duas vantagens:

1. Nenhum ponto único de falha
2. Fácil de escalonar horizontalmente (escalonar por cliente)

O proxy MySQL (e os plugins `mysqlnd`) podem resolver facilmente problemas que de outra forma exigiriam alterações em aplicações existentes.

No entanto, o Proxy MySQL tem algumas desvantagens:

- Proxy MySQL é um novo componente e uma nova tecnologia para dominar e implantar.
- O Proxy MySQL requer conhecimento da linguagem de script Lua.

O proxy MySQL pode ser customizado com programação C e Lua. Lua é a linguagem de script preferida do Proxy MySQL. Para a maioria dos especialistas em PHP, Lua é uma nova linguagem para se aprender. Um plugin `mysqlnd` pode ser escrito em C. Também é possível escrever plugins em PHP usando » PECL/mysqlnd_uh.

O proxy MySQL é executado como um daemon - um processo em segundo plano. O proxy MySQL pode recuperar decisões anteriores, pois todo o estado pode ser retido. Entretanto, um plugin `mysqlnd` está vinculado ao ciclo de vida baseado em solicitações do PHP. O Proxy MySQL também pode compartilhar resultados computados únicos entre vários servidores de aplicativos. Um plugin `mysqlnd` precisaria armazenar dados em um meio persistente para poder fazer isso. Outro daemon precisaria ser usado para essa finalidade, como o Memcache. Isso dá ao Proxy MySQL uma vantagem neste caso.

O proxy MySQL funciona sobre o protocolo de fio. Com o Proxy MySQL é necessário analisar e fazer engenharia reversa do protocolo MySQL Client Server. As ações são limitadas àquelas que podem ser alcançadas através da manipulação do protocolo de comunicação. Se o protocolo de fio for alterado (o que acontece muito raramente), os scripts do proxy MySQL também precisarão ser alterados.

Os plugins `Mysqlnd` funcionam sobre a API C, que espelha o cliente `libmysqlclient`. Esta API C é basicamente um encapsulador em torno do protocolo clienten-servidor MySQL, ou protocolo de fio, como às vezes é chamado. Pode-se interceptar todas as chamadas da API C. O PHP faz uso da API C, portanto pode-se conectar todas as chamadas PHP, sem a necessidade de programar no nível do protocolo de fio.

`Mysqlnd` implementa o protocolo de fio. Os plugins podem, portanto, analisar, fazer engenharia reversa, manipular e até mesmo substituir o protocolo de comunicação. No entanto, isso geralmente não é necessário.

Como os plugins permitem criar implementações que utilizam dois níveis (API C e protocolo de fio), eles têm maior flexibilidade que o Proxy MySQL. Se um plugin `mysqlnd` for implementado usando a API C, quaisquer alterações subsequentes no protocolo de fio não requerem alterações no próprio plugin.

## Obtendo a API do plugin mysqlnd

A API do plugin `mysqlnd` é simplesmente parte da extensão PHP do Driver Nativo MySQL, `ext/mysqlnd`. O desenvolvimento da API do plugin `mysqlnd` começou em dezembro de 2009. Ele é desenvolvido como parte do repositório de código-fonte PHP e, como tal, está disponível ao público via Git ou por meio de downloads de snapshots de código-fonte.

Os desenvolvedores do plugin podem determinar a versão do `mysqlnd` acessando `MYSQLND_VERSION`, que é uma string no formato mysqlnd 8.3.17 ou por meio de `MYSQLND_VERSION_ID`, que é um número inteiro como 50007. Os desenvolvedores podem calcular o número da versão da seguinte maneira:

Tabela de cálculo de MYSQLND_VERSION_ID
Versão (parte) | Exemplo
--- | ---
Maior*10000 | 5*10000 = 50000
Menor*100 | 0*100 = 0
Correção | 7 = 7
MYSQLND_VERSION_ID | 50007

Durante o desenvolvimento, os desenvolvedores devem consultar o número da versão do `mysqlnd` para compatibilidade e testes de versão, já que diversas iterações do `mysqlnd` podem ocorrer durante o tempo de vida de uma ramificação de desenvolvimento PHP com um único número de versão PHP.

## Arquitetura do Plugin do Driver Nativo MySQL

Esta seção fornece uma visão geral da arquitetura do plugin `mysqlnd`.

Visão Geral do Driver Nativo MySQL

Antes de desenvolver plugins `mysqlnd`, é útil saber um pouco de como o próprio `mysqlnd` é organizado. `Mysqlnd` consiste nos seguintes módulos:

O organograma mysqlnd, por módulo
Estatísticas de Módulos | mysqlnd_statistics.c
--- | ---
Conexão | mysqlnd.c
Conjunto de resultados | mysqlnd_result.c
Metadados do conjunto de resultados | mysqlnd_result_meta.c
Declaração | mysqlnd_ps.c
Rede | mysqlnd_net.c
Protocolo de fio | mysqlnd_wireprotocol.c

Paradigma de C Orientado a Objetos

No nível do código, `mysqlnd` usa um padrão C para implementar orientação a objetos.

Em C você usa uma `struct` para representar um objeto. Os membros da estrutura representam propriedades do objeto. Membros da estrutura que apontam para funções representam métodos.

Ao contrário de outras linguagens como C++ ou Java, não existem regras fixas sobre herança no paradigma do C orientado a objetos. No entanto, existem algumas convenções que precisam ser seguidas e que serão discutidas posteriormente.

O Ciclo de Vida do PHP

Ao considerar o ciclo de vida do PHP, existem dois ciclos básicos:

- Ciclo de inicialização e desligamento do mecanismo PHP
- Ciclo de requisição

Quando o mecanismo PHP for iniciado ele chamará a função de inicialização do módulo (MINIT) de cada extensão registrada. Isso permite que cada módulo configure variáveis ​​e aloque recursos que existirão durante a vida útil do processo do mecanismo PHP. Quando o mecanismo PHP for desligado, ele chamará a função de desligamento do módulo (MSHUTDOWN) de cada extensão.

Durante a vida útil do mecanismo PHP, ele receberá diversas solicitações. Cada solicitação constitui outro ciclo de vida. Em cada solicitação, o mecanismo PHP chamará a função de inicialização de solicitação de cada extensão. A extensão pode executar qualquer configuração de variável e alocação de recursos necessária para o processamento de solicitações. À medida que o ciclo de solicitação termina, o mecanismo chama a função de desligamento de solicitação (RSHUTDOWN) de cada extensão para que ela possa realizar qualquer limpeza necessária.

Como um plugin funciona

Um plugin `mysqlnd` funciona interceptando chamadas feitas para `mysqlnd` por extensões que usam `mysqlnd`. Isto é conseguido obtendo a tabela de funções `mysqlnd`, fazendo backup dela e substituindo-a por uma tabela de funções customizada, que chama as funções do plugin conforme necessário.

O código a seguir mostra como a tabela de funções `mysqlnd` é substituída:

    /* um lugar para armazenar a tabela de funções original */
    struct st_mysqlnd_conn_methods org_methods;

    void minit_register_hooks(TSRMLS_D) {
      /* tabela de funções ativas */
      struct st_mysqlnd_conn_methods * current_methods
        = mysqlnd_conn_get_methods();

      /* tabela de funções original de backup */
      memcpy(&org_methods, current_methods,
        sizeof(struct st_mysqlnd_conn_methods);

      /* instala novos métodos */
      current_methods->query = MYSQLND_METHOD(my_conn_class, query);
    }

As manipulações da tabela de funções de conexão devem ser feitas durante a inicialização do módulo (MINIT). A tabela de funções é um recurso global compartilhado. Em um ambiente multithread, com construção de TSRM, a manipulação de um recurso global compartilhado durante o processamento da solicitação quase certamente resultará em conflitos.

> Nota: Não use nenhuma lógica de tamanho fixo ao manipular a tabela de funções `mysqlnd`: novos métodos podem ser adicionados ao final da tabela de funções. A tabela de funções pode mudar a qualquer momento no futuro.

Chamando métodos da classe pai

Se for feito backup das entradas originais da tabela de funções, ainda será possível chamar as entradas originais da tabela de funções - os métodos pai.

Em alguns casos, como em `Connection::stmt_init()`, é vital chamar o método pai antes de qualquer outra atividade no método derivado.

    MYSQLND_METHOD(my_conn_class, query)(MYSQLND *conn,
      const char *query, unsigned int query_len TSRMLS_DC) {

      php_printf("my_conn_class::query(query = %s)\n", query);

      query = "SELECT 'query rewritten' FROM DUAL";
      query_len = strlen(query);

      return org_methods.query(conn, query, query_len); /* retorna com chamada ao método pai */
    }

Estendendo propriedades

Um objeto `mysqlnd` é representado por uma estrutura C. Não é possível adicionar um membro a uma estrutura C em tempo de execução. Usuários de objetos `mysqlnd` não podem simplesmente adicionar propriedades aos objetos.

Dados arbitrários (propriedades) podem ser adicionados a um objeto `mysqlnd` usando uma função apropriada da família `mysqlnd_plugin_get_plugin_<object>_data()`. Ao alocar um objeto, `mysqlnd` reserva espaço no final do objeto para conter um ponteiro `void *` para dados arbitrários. `mysqlnd` reserva espaço para um ponteiro `void *` por plugin.

A tabela a seguir mostra como calcular a posição do ponteiro para um plugin específico:

Cálculo de ponteiro para mysqlnd
Endereço de memória | Conteúdo
--- | ---
0 | Início da estrutura C do objeto mysqlnd
n | Final da estrutura C do objeto mysqlnd
n + (m x sizeof(void*)) | void* para dados do objeto do m-ésimo plugin

Se for planejada uma sub-classe de qualquer dos construtores de objeto `mysqlnd`, que é permitido, deve-se ter isto em mente!

O código a seguir mostra extensão de propriedades:

    /* qualquer dado que se queira associar */
    typedef struct my_conn_properties {
      unsigned long query_counter;
    } MY_CONN_PROPERTIES;

    /* id do plugin */
    unsigned int my_plugin_id;

    void minit_register_hooks(TSRMLS_D) {
      /* obtém ID único para o plugin */
      my_plugin_id = mysqlnd_plugin_register();
      /* recorte - consulte Estendendo Conexão: métodos */
    }

    static MY_CONN_PROPERTIES** get_conn_properties(const MYSQLND *conn TSRMLS_DC) {
      MY_CONN_PROPERTIES** props;
      props = (MY_CONN_PROPERTIES**)mysqlnd_plugin_get_plugin_connection_data(
        conn, my_plugin_id);
      if (!props || !(*props)) {
        *props = mnd_pecalloc(1, sizeof(MY_CONN_PROPERTIES), conn->persistent);
        (*props)->query_counter = 0;
      }
      return props;
    }

O desenvolvedor do plugin é responsável pelo gerenciamento de memória dos dados do plugin.

O uso do alocador de memória `mysqlnd` é recomendado para dados do plugin. Essas funções são nomeadas usando a convenção: `mnd_*loc()`. O alocador `mysqlnd` possui alguns recursos úteis, como a capacidade de usar um alocador de depuração em uma compilação sem depuração.

Quando e como usar uma sub-classe
| Quando usar uma sub-classe? | Cada instância tem sua própria tabela de funções privadas? | Como usar uma sub-classe
--- | --- | --- | ---
Conexão (MYSQLND) | MINIT | Não | mysqlnd_conn_get_methods()
Conjunto de resultados (MYSQLND_RES) | MINIT ou depois | Sim | mysqlnd_result_get_methods() ou manipulação de tabela de funções de métodos de objeto
Metadados do conjunto de resultados (MYSQLND_RES_METADATA) | MINIT | Não | mysqlnd_result_metadata_get_methods()
Instrução (MYSQLND_STMT) | MINIT | Não | mysqlnd_stmt_get_methods()
Rede (MYSQLND_NET) | MINIT ou depois | Sim | mysqlnd_net_get_methods() ou manipulação de tabela de funções de métodos de objeto
Protocolo de fio (MYSQLND_PROTOCOL) | MINIT ou depois | Sim | mysqlnd_protocol_get_methods() ou manipulação de tabela de funções de métodos de objeto

Não se deve manipular tabelas de funções em nenhum momento posterior ao MINIT se isso não for permitido de acordo com a tabela acima.

Algumas classes contêm um ponteiro para a tabela de funções do método. Todas as instâncias dessa classe compartilharão a mesma tabela de funções. Para evitar o caos, especialmente em ambientes com threads, tais tabelas de funções só devem ser manipuladas durante o MINIT.

Outras classes usam cópias de uma tabela de funções compartilhada globalmente. A cópia da tabela de funções de classe é criada junto com o objeto. Cada objeto usa sua própria tabela de funções. Isso dá duas opções: pode-se manipular a tabela de funções padrão de um objeto no MINIT, e também pode-se refinar os métodos de um objeto sem afetar outras instâncias da mesma classe.

A vantagem da abordagem de tabela de funções compartilhadas é o desempenho. Não há necessidade de copiar uma tabela de funções para cada objeto.

Estado do construtor
Tipo | Alocação, construção, redefinição | Pode ser modificada? | Chamadora
--- | --- | --- | ---
Conexão (MYSQLND) | mysqlnd_init() | Não | mysqlnd_connect()
Conjunto de resultados (MYSQLND_RES) | Alocação: Connection::result_init() Redefinida e reinicializada durante: Result::use_result() Result::store_result | Sim, mas deve-se chamar o método pai! | Connection::list_fields() Statement::get_result() Statement::prepare() (Somente metadados) Statement::resultMetaData()
Metadados do conjunto de resultados (MYSQLND_RES_METADATA) | Connection::result_meta_init() | Sim, mas deve-se chamar o método pai! | Result::read_result_metadata()
Instrução (MYSQLND_STMT) | Connection::stmt_init() | Sim, mas deve-se chamar o método pai! | Connection::stmt_init()
Rede (MYSQLND_NET) | mysqlnd_net_init() | Não | Connection::init()
Protocolo de fio (MYSQLND_PROTOCOL) | mysqlnd_protocol_init() | Não | Connection::init()

É altamente recomendável que não se substitua totalmente um construtor. Os construtores realizam alocações de memória. As alocações de memória são vitais para a API do plugin `mysqlnd` e para a lógica do objeto `mysqlnd`. Se não houver preocupação com avisos e houver insistência em conectar os construtores, deve-se pelo menos chamar o construtor pai antes de fazer qualquer coisa no construtor.

Independentemente de todos os avisos, pode ser útil criar sub-classes de construtores. Os construtores são o lugar perfeito para modificar as tabelas de funções de objetos com tabelas de objetos não compartilhados, como Conjunto de Resultados, Rede, Protocolo de Fio.

Estado do destruidor
Tipo | Método derivado deve chamar o pai? | Destruidor
--- | --- | ---
Conexão | sim, após execução do método | free_contents(), end_psession()
Conjunto de resultados | sim, após execução do método | free_result()
Metadados do conjunto de resultados | sim, após execução do método | free()
Instrução | sim, após execução do método | dtor(), free_stmt_content()
Rede | sim, após execução do método | free()
Protocolo de fio | sim, após execução do método | free()

Os destruidores são o local apropriado para liberar propriedades, `mysqlnd_plugin_get_plugin_<object>_data()`.

Os destruidores listados podem não ser equivalentes ao método `mysqlnd` real que libera o próprio objeto. No entanto, eles são o melhor lugar possível para se conectar e liberar os dados do plugin. Tal como acontece com os construtores, pode-se substituir totalmente os métodos, mas isso não é recomendado. Se vários métodos estiverem listados na tabela acima, será necessário conectar todos os métodos listados e liberar os dados do plugin em qualquer método chamado primeiro pelo `mysqlnd`.

O método recomendado para plugins é simplesmente conectar os métodos, liberar memória e chamar a implementação pai imediatamente após isso.

## A API do plugin mysqlnd

A seguir está uma lista de funções fornecidas na API do plugin `mysqlnd`:

- mysqlnd_plugin_register()
- mysqlnd_plugin_count()
- mysqlnd_plugin_get_plugin_connection_data()
- mysqlnd_plugin_get_plugin_result_data()
- mysqlnd_plugin_get_plugin_stmt_data()
- mysqlnd_plugin_get_plugin_net_data()
- mysqlnd_plugin_get_plugin_protocol_data()
- mysqlnd_conn_get_methods()
- mysqlnd_result_get_methods()
- mysqlnd_result_meta_get_methods()
- mysqlnd_stmt_get_methods()
- mysqlnd_net_get_methods()
- mysqlnd_protocol_get_methods()

Não existe uma definição formal do que é um plugin e como funciona um mecanismo de plugin.

Os componentes frequentemente encontrados em mecanismos de plugins são:

- Um gerenciador de plugin
- Uma API de plugin
- Serviços (ou módulos) de aplicação
- APIs de serviço (ou APIs de módulo) de aplicação

O conceito do plugin `mysqlnd` emprega esses recursos e, adicionalmente, desfruta de uma arquitetura aberta.

Sem Restrições

Um plugin tem acesso total ao funcionamento interno do `mysqlnd`. Não há limites ou restrições de segurança. Tudo pode ser sobrescrito para implementar algoritmos amigáveis ​​ou hostis. É recomendado que se implante apenas plugins de uma fonte confiável.

Conforme discutido anteriormente, os plugins podem usar ponteiros livremente. Esses ponteiros não são restritos de forma alguma e podem apontar para dados de outro plugin. A aritmética de deslocamento simples pode ser usada para ler os dados de outro plugin.

É recomendado que se escreva plugins cooperativos e que sempre se chame o método pai. Os plugins devem sempre cooperar com o próprio `mysqlnd`.

Questões: um exemplo de encadeamento e cooperação
Extensão | Ponteiro mysqlnd.query() | pilha de chamadas se estiver chamando o pai
--- | --- | ---
ext/mysqlnd | mysqlnd.query() | mysqlnd.query
ext/mysqlnd_cache | mysqlnd_cache.query() | mysqlnd_cache.query() mysqlnd.query
ext/mysqlnd_monitor | mysqlnd_monitor.query() | mysqlnd_monitor.query() mysqlnd_cache.query() mysqlnd.query

Neste cenário, um cache (`ext/mysqlnd_cache`) e um plugin de monitor (`ext/mysqlnd_monitor`) são carregados. Ambas são sub-classes de `Connection::query()`. O registro do plugin acontece em `MINIT` usando a lógica mostrada anteriormente. O PHP chama extensões em ordem alfabética por padrão. Os plugins não reconhecem uns aos outros e não definem dependências de extensão.

Por padrão, os plugins chamam a implementação pai do método de consulta em sua versão derivada do método.

Recapitulação da Extensão PHP

Esta é uma recapitulação do que acontece ao usar um plugin de exemplo, `ext/mysqlnd_plugin`, que expõe a API do plugin C `mysqlnd` ao PHP:

- Qualquer aplicação PHP MySQL tenta estabelecer uma conexão com 192.168.2.29
- A aplicação PHP usará `ext/mysql`, `ext/mysqli` ou `PDO_MYSQL`. Todas as três extensões PHP MySQL usam `mysqlnd` para estabelecer a conexão com 192.168.2.29.
- `Mysqlnd` chama seu método de conexão, que agora é uma sub-classe de `ext/mysqlnd_plugin`.
- `ext/mysqlnd_plugin` chama o gancho do espaço de usuário `proxy::connect()` registrado pelo usuário.
- O gancho do espaço de usuário altera o IP do host de conexão de 192.168.2.29 para 127.0.0.1 e retorna a conexão estabelecida por `parent::connect()`.
- `ext/mysqlnd_plugin` executa o equivalente a `parent::connect(127.0.0.1)` chamando o método `mysqlnd` original para estabelecer uma conexão.
- `ext/mysqlnd` estabelece uma conexão e retorna ao `ext/mysqlnd_plugin`. `ext/mysqlnd_plugin` também retorna.
- Qualquer que seja a extensão PHP MySQL utilizada pela aplicação, ela recebe uma conexão com 127.0.0.1. A própria extensão PHP MySQL retorna ao aplicativo PHP. E o ciclo se fecha.

## Começando a construir um plugin mysqlnd

É importante lembrar que um plugin `mysqlnd` é em si uma extensão PHP.

O código a seguir mostra a estrutura básica da função MINIT que será usada no plugin `mysqlnd` típico:

    /* my_php_mysqlnd_plugin.c */

     static PHP_MINIT_FUNCTION(mysqlnd_plugin) {
      /* globais, entradas ini, recursos, classes */

      /* registra o plugin mysqlnd */
      mysqlnd_plugin_id = mysqlnd_plugin_register();

      conn_m = mysqlnd_get_conn_methods();
      memcpy(org_conn_m, conn_m,
        sizeof(struct st_mysqlnd_conn_methods));

      conn_m->query = MYSQLND_METHOD(mysqlnd_plugin_conn, query);
      conn_m->connect = MYSQLND_METHOD(mysqlnd_plugin_conn, connect);
     }

    /* my_mysqlnd_plugin.c */

     enum_func_status MYSQLND_METHOD(mysqlnd_plugin_conn, query)(/* ... */) {
      /* ... */
     }
     enum_func_status MYSQLND_METHOD(mysqlnd_plugin_conn, connect)(/* ... */) {
      /* ... */
     }

Análise de tarefa: do C ao espaço do usuário

    class proxy extends mysqlnd_plugin_connection {
      public function connect($host, ...) { .. }
    }
    mysqlnd_plugin_set_conn_proxy(new proxy());

Processo:

1. PHP: usuário registra chamada do plugin
2. PHP: usuário chama qualquer API PHP MySQL para se conectar ao MySQL
3. C: ext/*mysql* chama o método de mysqlnd
4. C: mysqlnd chega em ext/mysqlnd_plugin

5. C: ext/mysqlnd_plugin

   1. Chama a função de retorno no espaço de usuário
   2. Ou o método original de `mysqlnd`, se a função de retorno no espaço de usuário não estiver definida

Deve-se fazer o seguinte:

1. Escrever uma classe "mysqlnd_plugin_connection" em C
2. Aceitar e registrar um objeto proxy através de "mysqlnd_plugin_set_conn_proxy()"
3. Chamar métodos proxy do espaço do usuário a partir do C (otimização - zend_interfaces.h)

Os métodos de objeto do espaço do usuário podem ser chamados usando `call_user_function()` ou pode-se operar em um nível mais próximo do Motor Zend e usar `zend_call_method()`.

Otimização: chamando métrodos a partir do C usando zend_call_method

O trecho de código a seguir mostra o protótipo da função `zend_call_method`, obtido de zend_interfaces.h.

     ZEND_API zval* zend_call_method(
      zval **object_pp, zend_class_entry *obj_ce,
      zend_function **fn_proxy, char *function_name,
      int function_name_len, zval **retval_ptr_ptr,
      int param_count, zval* arg1, zval* arg2 TSRMLS_DC
    );

A API Zend suporta apenas dois argumentos. Pode ser necessário mais, por exemplo:

     enum_func_status (*func_mysqlnd_conn__connect)(
      MYSQLND *conn, const char *host,
      const char * user, const char * passwd,
      unsigned int passwd_len, const char * db,
      unsigned int db_len, unsigned int port,
      const char * socket, unsigned int mysql_flags TSRMLS_DC
    );

Para contornar esse problema é necessário fazer uma cópia de `zend_call_method()` e adicionar um recurso para parâmetros adicionais. Pode-se fazer isso criando um conjunto de macros `MY_ZEND_CALL_METHOD_WRAPPER`.

Chamando o espaço de usuário do PHP

Este trecho de código mostra o método otimizado para chamar uma função de espaço do usuário a partir do C:

    /* my_mysqlnd_plugin.c */

    MYSQLND_METHOD(my_conn_class,connect)(
      MYSQLND *conn, const char *host /* ... */ TSRMLS_DC) {
      enum_func_status ret = FAIL;
      zval * global_user_conn_proxy = fetch_userspace_proxy();
      if (global_user_conn_proxy) {
        /* chama o proxy de espaço de usuário */
        ret = MY_ZEND_CALL_METHOD_WRAPPER(global_user_conn_proxy, host, /*...*/);
      } else {
        /* ou o método mysqlnd original = não faz nada, é transparente */
        ret = org_methods.connect(conn, host, user, passwd,
              passwd_len, db, db_len, port,
              socket, mysql_flags TSRMLS_CC);
      }
      return ret;
    }

Chamando o espaço de usuário: argumentos simples

    /* my_mysqlnd_plugin.c */

     MYSQLND_METHOD(my_conn_class,connect)(
      /* ... */, const char *host, /* ...*/) {
      /* ... */
      if (global_user_conn_proxy) {
        /* ... */
        zval* zv_host;
        MAKE_STD_ZVAL(zv_host);
        ZVAL_STRING(zv_host, host, 1);
        MY_ZEND_CALL_METHOD_WRAPPER(global_user_conn_proxy, zv_retval, zv_host /*, ...*/);
        zval_ptr_dtor(&zv_host);
        /* ... */
      }
      /* ... */
    }

Chamando o espaço de usuário: estruturas como argumentos

    /* my_mysqlnd_plugin.c */

    MYSQLND_METHOD(my_conn_class, connect)(
      MYSQLND *conn, /* ...*/) {
      /* ... */
      if (global_user_conn_proxy) {
        /* ... */
        zval* zv_conn;
        ZEND_REGISTER_RESOURCE(zv_conn, (void *)conn, le_mysqlnd_plugin_conn);
        MY_ZEND_CALL_METHOD_WRAPPER(global_user_conn_proxy, zv_retval, zv_conn, zv_host /*, ...*/);
        zval_ptr_dtor(&zv_conn);
        /* ... */
      }
      /* ... */
    }

O primeiro argumento de muitos métodos `mysqlnd` é um "objeto" C. Por exemplo, o primeiro argumento do método connect() é um ponteiro para `MYSQLND`. A estrutura MYSQLND representa um objeto de conexão `mysqlnd`.

O ponteiro do objeto de conexão `mysqlnd` pode ser comparado a um identificador de arquivo de E/S padrão. Como um arquivo de E/S padrão, um objeto de conexão `mysqlnd` deve ser vinculado ao espaço do usuário usando o tipo de variável de recurso PHP.

Do C para o espaço de usuário e vice-versa

     class proxy extends mysqlnd_plugin_connection {
      public function connect($conn, $host, ...) {
        /* "pre" gancho */
        printf("Conectando-se ao servidor = '%s'\n", $host);
        debug_print_backtrace();
        return parent::connect($conn);
      }

      public function query($conn, $query) {
        /* "pós" gancho */
        $ret = parent::query($conn, $query);
        printf("Consulta = '%s'\n", $query);
        return $ret;
      }
    }
    mysqlnd_plugin_set_conn_proxy(new proxy());

Os usuários de PHP devem ser capazes de chamar a implementação pai de um método substituído.

Como resultado de se criar sub-classes, é possível refinar apenas métodos selecionados e pode-se optar por ter ganchos "pré" ou "pós".

Classe integrada: mysqlnd_plugin_connection::connect()

    /*  my_mysqlnd_plugin_classes.c */

     PHP_METHOD("mysqlnd_plugin_connection", connect) {
      /* ... simplificada! ... */
      zval* mysqlnd_rsrc;
      MYSQLND* conn;
      char* host; int host_len;
      if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "rs",
        &mysqlnd_rsrc, &host, &host_len) == FAILURE) {
        RETURN_NULL();
      }
      ZEND_FETCH_RESOURCE(conn, MYSQLND* conn, &mysqlnd_rsrc, -1,
        "Mysqlnd Connection", le_mysqlnd_plugin_conn);
      if (PASS == org_methods.connect(conn, host, /* simplificado! */ TSRMLS_CC))
        RETVAL_TRUE;
      else
        RETVAL_FALSE;
    }

- Visão Geral
- Instalação
- Configurações em Execução
- Incompatibilidades
- Conexões Persistentes
- Estatísticas
- Notas
- Gerenciamento de Memória
- API do plugin do Driver Nativo MySQL
  - Uma comparação de plugins mysqlnd com Proxy MySQL
  - Obtendo a API do plugin mysqlnd
  - Arquitetura do Plugin do Driver Nativo MySQL
  - A API do plugin mysqlnd
  - Começando a construir um plugin mysqlnd

- Visão geral dos drivers PHP para MySQL
  - Visão geral de terminologia
  - Escolhendo uma API
  - Escolhendo uma biblioteca
  - Conceitos
- MySQLi — Extensão MySQL Melhorada
  - Visão Geral
  - Guia de início rápido
  - Instalação/Configuração
  - A extensão mysqli e conexões persistentes
  - Constantes predefinidas
  - Notas
  - Resumo da Função de Extensão do MySQLi
  - mysqli — A classe mysqli
  - mysqli_stmt — A classe mysqli_stmt
  - mysqli_result — A classe mysqli_result
  - mysqli_driver — A classe mysqli_driver
  - mysqli_warning — A classe mysqli_warning
  - mysqli_sql_exception — A classe mysqli_sql_exception
  - Apelidos e Funções descontinuadas da Mysqli
  - Registro de Alterações
- Mysql_xdevapi
  - Instalação/Configuração
  - Constantes predefinidas
  - Registro de Alterações
  - Exemplos
  - Funções de Mysql_xdevapi
  - mysql_xdevapi\BaseResult — Interface BaseResult
  - mysql_xdevapi\Client — Classe Client
  - mysql_xdevapi\Collection — Classe Collection
  - mysql_xdevapi\CollectionAdd — Classe CollectionAdd
  - mysql_xdevapi\CollectionFind — Classe CollectionFind
  - mysql_xdevapi\CollectionModify — Classe CollectionModify
  - mysql_xdevapi\CollectionRemove — Classe CollectionRemove
  - mysql_xdevapi\ColumnResult — Classe ColumnResult
  - mysql_xdevapi\CrudOperationBindable — Interface CrudOperationBindable
  - mysql_xdevapi\CrudOperationLimitable — Interface CrudOperationLimitable
  - mysql_xdevapi\CrudOperationSkippable — Interface CrudOperationSkippable
  - mysql_xdevapi\CrudOperationSortable — Interface CrudOperationSortable
  - mysql_xdevapi\DatabaseObject — Interface DatabaseObject
  - mysql_xdevapi\DocResult — Classe DocResult
  - mysql_xdevapi\Exception — Classe Exception
  - mysql_xdevapi\Executable — Interface Executable
  - mysql_xdevapi\ExecutionStatus — Classe ExecutionStatus
  - mysql_xdevapi\Expression — Classe Expression
  - mysql_xdevapi\Result — Classe Result
  - mysql_xdevapi\RowResult — Classe RowResult
  - mysql_xdevapi\Schema — Classe Schema
  - mysql_xdevapi\SchemaObject — Interface SchemaObject
  - mysql_xdevapi\Session — Classe Session
  - mysql_xdevapi\SqlStatement — Classe SqlStatement
  - mysql_xdevapi\SqlStatementResult — Classe SqlStatementResult
  - mysql_xdevapi\Statement — Classe Statement
  - mysql_xdevapi\Table — Classe Table
  - mysql_xdevapi\TableDelete — Classe TableDelete
  - mysql_xdevapi\TableInsert — Classe TableInsert
  - mysql_xdevapi\TableSelect — Classe TableSelect
  - mysql_xdevapi\TableUpdate — TableUpdate class
  - mysql_xdevapi\Warning — Classe Warning
- MySQL (Original) — API Original MySQL
  - Instalação/Configuração
  - Registro de Alterações
  - Constantes predefinidas
  - Exemplos
  - Funções da MySQL
- Mysqlnd — Driver Nativo MySQL
  - Visão Geral
  - Instalação
  - Configurações em Execução
  - Incompatibilidades
  - Conexões Persistentes
  - Estatísticas
  - Notas
  - Gerenciamento de Memória
  - API do plugin do Driver Nativo MySQL

# Oracle OCI8

# Introdução

Aviso

Esta extensão foi DESAGREGADA a partir do PHP 8.4.0.

Essas funções permitem acessar bancos de dados Oracle. Suportam instruções SQL e PL/SQL. Recursos básicos incluem o controle de transações, vínculo de variáveis PHP em placeholders Oracle, além do suporte aos tipos de objetos grandes (LOB) e coleções. O recursos de escalabilidade da Oracle, como o Database Resident Connection Pooling (DRCP) e resultados em cache também são suportados.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Testando
- Configurações em Execução

## Dependências

OCI8 3.0 é incluído com o PHP 8. Também está disponível em » PECL. Para o PHP 7, use OCI8 2.2 de » PECL. OCI8 requer Oracle 10g ou bibliotecas de cliente Oracle mais recentes.

Se o banco de dados Oracle estiver na mesma máquina que o PHP, o software do banco de dados já conterá os arquivos de biblioteca e de cabeçalho necessários. Quando o PHP estiver um uma máquina diferente, use as bibliotecas » Oracle Instant Client gratuitas.

Para usar o Oracle Instant Client, instale o arquivo ZIP, pacote RPM ou pacote DMG do Oracle Instant Client `Basic` ou `Basic Light`. Ao compilar o OCI8 a partir do código-fonte, instale também o `SDK` do Instant Client.

Deve-se executar o PHP com mesma versão ou uma mais recente das bibliotecas Oracle com as quais o OCI8 foi compilado.

> Nota:

> A interoperabilidade de rede cliente-servidor padrão da Oracle permite conexões entre diferentes versões do Oracle Client e do Oracle Database. Para configurações certificadas, consulte o Doc ID 207303.1 do suporte da Oracle. Em resumo, as versões Oracle Client 19, 18 e 12.2 podem se conectar ao Oracle Database 11.2 ou superior. O Oracle Client 12.1 pode se conectar ao Oracle Database 10.2 ou superior. O Oracle Client 11.2 pode se conectar ao Oracle Database 9.2 ou superior.

> Nota:

> O suporte completo ao recurso OCI8 está disponível apenas ao usar as versões mais recentes das bibliotecas cliente e do banco de dados Oracle.

## Instalação

## Configurando o PHP com o OCI8

Consulte a seção anterior sobre requisitos antes de configurar o OCI8.

Antes de inicializar o servidor web, o OCI8 tipicamente requer várias variáveis de ambiente Oracle (veja abaixo) para localizar bibliotecas, apontar para arquivos de configuração e definir algumas propriedades básicas como o conjunto de caracteres utilizado pelas bibliotecas Oracle. As variáveis devem ser definidas antes que qualquer processo PHP inicie.

O binário PHP deve ter sido construído com a mesma versão principal, ou mais recente, das bibliotecas Oracle com as quais foi configurado. Por exemplo, se o OCI8 estiver utilizando as bibliotecas Oracle versão 19, o PHP também deve ser construído e executado com as bibliotecas Oracle 19. Aplicações PHP podem se conectar a outras versões de banco de dados Oracle, já que a Oracle tem compatibilidade cliente-servidor com versões diferentes.

## Instalando OCI8 com PECL Usando o Comando pecl

A extensão OCI8 pode ser adicionada a uma instalação PHP existente usando o repositório » PECL.

- Se estiver por trás de um firewall, defina o proxy PEAR, por exemplo:

      pear config-set http_proxy http://my-proxy.example.com:80/

- Execute

      pecl install oci8

  Para o PHP 7, use `pecl install oci8-2.2.0`

- Quando solicitado, entre o valor de `$ORACLE_HOME` ou `instantclient,/caminho/para/biblioteca/instant/client`.

  Nota: Não use nomes de variáveis como `$ORACLE_HOME` ou `$HOME` porque o `pecl` não irá interpretá-las. Em vez disso, informa um caminho expandido, por exemplo `/opt/oracle/product/19c/dbhome_1` ou `instantclient,/Users/myname/Downloads/instantclient_19_8`.

- Se ocorrer um erro do tipo `oci8_dtrace_gen.h: No such file or directory`, significa que o PHP foi compilado com Rastreamento Dinâmico DTrace habilitado. Instale usando:

      $ export PHP_DTRACE=yes
      $ pecl install oci8

- Edite o arquivo php.ini e adicione a linha:

      extension=oci8.so

  Certifique-se que a diretiva extension_dir do php.ini esteja definida para o diretório onde o arquivo oci8.so tenha sido instalado.

## Instalando OCI8 com PECL Usando phpize

Para instalar o OCI8 em uma instalação PHP existente quando o comando `pecl` não estiver disponível, baixe manualmente o pacote OCI8 » PECL, ex.: oci8-3.0.0.tgz.

- Extraia o pacote:

      tar -zxf oci8-3.0.0.tgz
      cd oci8-3.0.0

- Prepare o pacote:

      phpize

- Configure o pacote, usando `$ORACLE_HOME` ou Instant Client

      ./configure -with-oci8=shared,$ORACLE_HOME

  ou

      ./configure -with-oci8=shared,instantclient,/caminho/para/biblioteca/instant/client

- Instale o pacote:

      make install

- Se ocorrer um erro do tipo `oci8_dtrace_gen.h: No such file or directory`, significa que o PHP foi compilado com Rastreamento Dinâmico DTrace habilitado. Execute novamente os comandos `configure` e `make` depois de definir esta variável de ambiente:

      $ export PHP_DTRACE=yes

- Edite o arquivo php.ini e adicione a linha:

      extension=oci8.so

  Certifique-se que a diretiva extension_dir do php.ini esteja definida para o diretório onde o arquivo oci8.so tenha sido instalado.

## Instalando o OCI8 como uma Extensão Compartilhada ao Compilar o PHP

Se o PHP está sendo compilado a partir do código-fonte, a opção de configuração `shared` pode ser usada para construir o OCI8 como uma biblioteca compartilhada que pode ser carregada dinamicamente no PHP. Construir uma extensão compartilhada permite que o OCI8 seja atualizado facilmente sem impactar o restante do PHP.

Configure o OCI8 usando uma das opções de configuração a seguir.

- Se as bibliotecas gratuitas do » Oracle Instant Client estiverem sendo usadas, execute:

      ./configure --with-oci8=shared,instantclient,/caminho/para/biblioteca/instant/client

  Se a Instant Client 12.2 (ou anterior) tiver sido instalada a partir de arquivos ZIP, certifique-se de criar as ligações simbólicas da biblioteca primeiro, por exemplo `ln -s libclntsh.so.12.1 libclntsh.so`.

  Se estiver sendo usada uma instalação baseada em RPM da Oracle Instant Client, a linha de configuração será parecida com:

      ./configure --with-oci8=shared,instantclient,/usr/lib/oracle/<version>/client/lib

  Por exemplo, --with-oci8=shared,instantclient,/usr/lib/oracle/19.9/client/lib

- Se um banco de dados Oracle ou uma instalação completa do Oracle Client estiverem sendo usados, execute:

      ./configure --with-oci8=shared,$ORACLE_HOME

  Certifique-se que o usuário sob o qual o servidor web esteja sendo executado (`nobody`, `www`) tenha acesso às bibliotecas, arquivos de inicialização e tnsnames.ora (se usado) no diretório `$ORACLE_HOME`. Com o Oracle 10gR2, pode ser necessário executar o utilitário $ORACLE_HOME/install/changePerm.sh para conceder acesso ao diretório.

Depois da configuração, siga o procedimento usual de compilação do PHP, ex.: make install. A biblioteca da extensão compartilhada OCI8 oci8.so será criada. Pode ser necessário movê-la manualmente para o diretório das extensões PHP, especificado pela opção extension_dir no arquivo php.ini.

Para completar a instalação do OCI8, edite o php.ini e adicione a linha:

    extension=oci8.so

## Instalando o OCI8 como um Extensão Compilada Estaticamente ao Compilar o PHP

Se o PHP estiver sendo compilado a partir do código-fonte, pode-se configurá-lo para incluir o OCI8 como uma extensão estática usando uma das seguintes opções de configuração.

- Se o Oracle Instant Client estiver sendo utilizado, execute:

      ./configure --with-oci8=instantclient,/caminho/para/biblioteca/instant/client

- Se um banco de dados Oracle ou uma instalação completa do Oracle Client estiverem sendo usados, execute:

      ./configure --with-oci8=$ORACLE_HOME

Depois da configuração, siga o procedimento usual de compilação do PHP, ex.: make install. Após a compilação bem sucedida, não é necessário incluir oci8.so ao php.ini. Nenhum passo adicional de compilação é requerido.

## Instalando o OCI8 no Windows

A extensão OCI8 pode ser adicionada a uma instalação PHP existente usando as DLLs do repositório » PECL ou as bibliotecas no diretório `ext` da instalação do PHP.

Com as bibliotecas Oracle 12c (ou mais recentes), ative uma das linhas `extension=php_oci8_12c.dll`, `extension=php_oci8_11g.dll` ou `extension=php_oci8.dll` do php.ini. Apenas uma dessas DLLs pode ser habilitada de cada vez. DLLs com versões maiores podem conter mais funcionalidades. Pode ser que nem todas as DLLs estejas disponíveis para todas as versões do PHP. Certifique-se que extension_dir esteja definido para o diretório contendo as DLLs de extensões do PHP.

Se o Instant Client estiver sendo utilizado, defina a variável de ambiente do sistema PATH para o diretório da biblioteca Oracle.

## Configurando o Ambiente Oracle

Antes de usar esta extensão, certifique-se que as variáveis de ambiente Oracle estajam adequadamente definidas para o usuário sob o qual o servidor web esteja sendo executado. Se o servidor web estiver sendo automaticamente iniciado quando o sistema é ligado, garanta que o ambiente em tempo de inicialização também esteja configurado corretamente.

> Nota:

> Não defina as variáveis de ambiente Oracle usando putenv() em um script PHP porque as bilbiotecas Oracle podem estar carregadas e inicializadas antes que o script seja executado. Variáveis definidas com putenv() podem causar conflitos, travamentos ou comportamento imprevisível. Algumas funções podem funcionar mas outras podem dar erros sutis. As variáveis devem ser definidas antes que o servidor web seja iniciado.

No Linux Red Hat e variantes, exporte as variáveis no final do arquivo /etc/sysconfig/httpd. Outros sistemas com Apache 2 pode usar um script envvars no diretório bin do Apache. Uma terceira opção, a diretiva `SetEnv` do Apache no arquivo httpd.conf, pode funcionar em alguns sistemas mas é sabido que isto é insuficiente em outros.

Para verificar que as variáveis de ambiente estão definidas corretamente, use phpinfo() e verifique se a seção Environment (não a Apache Environment) contém as variáveis esperadas.

As variáveis que devem ser necessárias estão incluídas na tabela a seguir. Consulte a documentação da Oracle para mais informação sobre todas as variáveis disponíveis.

Variáveis de Ambiente Oracle Comuns
Nome | Propósito
--- | ---
ORACLE_HOME | Contém o diretório da instalação completa do Banco de dados Oracle. Não defina esta variável ao usar o Oracle Instant Client pois é desnecessário e pode causar problemas de instalação.
ORACLE_SID | Contém o nome do banco de dados na máquina local ao qual a ser conectado. Não há necessidade de definir esta variável se o Oracle Instant Client estiver sendo usado, ou passe sempre o parâmetro de conexão para a função oci_connect().
LD_LIBRARY_PATH | Defina esta variável (ou sua equivalente dependendo da plataforma, como `LIBPATH` ou `SHLIB_PATH`) para a localização das bibliotecas Oracle libraries, por exemplo $ORACLE_HOME/lib ou /usr/lib/oracle/18.5/client/lib. Note que com arquivos ZIP do Instant Client no Linux é mais confiável usar ldconfig, consulte as instruções de instalação do Instant Client. Com o Instant Client 19 (ou posterior) em arquivos RPM, `ldconfig` é executado automaticamente. Alguns usuários utilizam `LD_PRELOAD` no lugar de `LD_LIBRARY_PATH`.
NLS_LANG | Esta é a variável primária para definir o conjunto de caracteres e informação de globalização usados pelas bibliotecas Oracle.
ORA_SDTZ | Define o fuso horário da sessão Oracle.
TNS_ADMIN | Contém o diretório onde os arquivos de configuração do Oracle Net Services como tnsnames.ora e sqlnet.ora são mantidos. Não é necessária se a string de conexão da função oci_connect() usa a sintexe de nomes Easy Connect como `localhost/XE`. Não é necessária se os arquivos de configuração de rede estiverem em uma das localizações padrões como /usr/lib/oracle/VERSION/client/lib/network/admin, $ORACLE_HOME/network/admin ou /etc.

Variáveis de ambiente utilizadas com menor frequência incluem `TWO_TASK`, `ORA_TZFILE` e as várias configuração de globalização Oracle como as variáveis `NLS*` e `ORA_NLS_*`.

## Solução de Problemas

O problema mais comum na instalação do OCI8 é não ter o ambiente Oracle definido corretamente. Isto tipicamente aparece como um problema ao usar oci_connect() ou oci_pconnect(). O erro pode ser gerado pelo PHP, como Call to undefined function oci_connect(), ou pelo Oracle, como ORA-12705, ou até um travamento do Apache. Verifique se os arquivos de registro do Apache contêm erros de inicialização e consulte as seções acima para resolver este problema.

Enquanto erros de rede como ORA-12154 ou ORA-12514 indicam um problema de nome ou configuração de rede Oracle, a causa raiz pode ser o ambiente PHP incorretamente configurado e a incapacidade das bibliotecas Oracle em localizar o arquivo de configuração tnsnames.ora.

No Windows, múltiplas versões do Oracle instaladas em uma máquina pode facilmente gerar conflitos de bilbiotecas a menos que se tenha cuidado garantindo que o PHP usa apenas a versão correta do Oracle.

Um utilitário para examinar que bibliotecas estão sendo procuradas e carregadas pode ajudar a resolver problemas de bibliotecas ausentes ou conflitantes, particularmente no Windows.

> Nota: Se o servidor web não iniciar ou travar na inicialização

> Verifique que o Apache foi construído com a biblioteca pthread:

>     # ldd /www/apache/bin/httpd
>       libpthread.so.0 => /lib/libpthread.so.0 (0x4001c000)
>       libm.so.6 => /lib/libm.so.6 (0x4002f000)
>       libcrypt.so.1 => /lib/libcrypt.so.1 (0x4004c000)
>       libdl.so.2 => /lib/libdl.so.2 (0x4007a000)
>       libc.so.6 => /lib/libc.so.6 (0x4007e000)
>       /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)

> Se libpthread não estiver listada, reinstale o Apache:

>     # cd /usr/src/apache_1.3.xx
>     # make clean
>     # LIBS=-lpthread ./config.status
>     # make
>     # make install

> Note que em alguns sistemas como UnixWare, o nome é libthread em vez de libpthread. PHP e Apache devem ser configurados com EXTRA_LIBS=-lthread.

## Testando

A suíte de testes do OCI8 está em ext/oci8/tests. Depois que os testes do OCI8 forem executados, este diretório também conterá registros de falhas.

Antes de executar testes do PHP, edite o arquivo details.inc e defina $user, $password e a string de conexão $dbase. A suíte de testes do OCI8 foi desenvolvida usando a conta `SYSTEM`. Alguns testes falharão se o usuário de teste não tiver as permissões equivalentes.

Se o Oracle Database Resident Connection Pooling estiver sendo testado, defina $test_drcp para `true` e garanta que a string de conexão use um servidor DRCP apropriado.

Uma alternativa para a edição de details.inc é definir variáveis de ambiente, por exemplo:

        $ export PHP_OCI8_TEST_USER=system
        $ export PHP_OCI8_TEST_PASS=oracle
        $ export PHP_OCI8_TEST_DB=localhost/XE
        $ export PHP_OCI8_TEST_DRCP=FALSE

Observe que em alguns shells essas variáveis ​​não são propagadas corretamente para o processo PHP e os testes falharão na conexão se este método for usado.

A seguir, defina qualquer ambiente necessário para o banco de dados Oracle. Se o PHP estiver sendo executado nas mesmas máquinas do Oracle Database, pode-se executar:

        $ . /usr/local/bin/oraenv

Com o Oracle 11gR2 XE, execute:

        $ . /u01/app/oracle/product/11.2.0/xe/bin/oracle_env.sh

Alguns shells exigem que php.ini tenham `E` no parâmetro variables_order, por exemplo:

        variables_order = "EGPCS"

Execute todos os testes PHP com:

        $ cd your_php_src_directory
        $ make test

ou execute somente os testes OCI8 com

        $ cd your_php_src_directory
        $ make test TESTS=ext/oci8

Quando os testes forem concluídos, revise quaisquer falhas de teste. Em sistemas lentos, alguns testes podem demorar mais que o tempo limite padrão em run-tests.php. Para corrigir isso, defina a variável de ambiente `TEST_TIMEOUT` para um número maior de segundos.

Em máquinas rápidas com um banco de dados local configurado para carga leve (por exemplo, Oracle 11gR2 XE) alguns testes podem falhar com erros ORA-12516 ou ORA-12520. Para evitar isso, aumente o parâmetro `PROCESSES` do banco de dados usando as seguintes etapas:

Conecte-se como o proprietário do software Oracle:

        $ su - oracle

Defina o ambiente Oracle necessário com oracle_env.sh ou oraenv, como descrito acima.

Inicie a ferramente de linha de comando SQL*Plus e aumente `PROCESSES`

        $ sqlplus / as sysdba
        SQL> alter system set processes=100 scope=spfile

Reinicie o banco de dados:

        SQL> startup force

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de Configuração da OCI8
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
oci8.connection_class | "" | `INI_ALL` |
oci8.default_prefetch | "100" | `INI_SYSTEM` |
oci8.events | Off | `INI_SYSTEM` |
oci8.max_persistent | "-1" | `INI_SYSTEM` |
oci8.old_oci_close_semantics | Off | `INI_SYSTEM` | Descontinuado a partir do PHP 8.1.0.
oci8.persistent_timeout | "-1" | `INI_SYSTEM` |
oci8.ping_interval | "60" | `INI_SYSTEM` |
oci8.prefetch_lob_size | "0" | `INI_SYSTEM` | Disponível desde o PECL OCI8 3.2.
oci8.privileged_connect | Off | `INI_SYSTEM` |
oci8.statement_cache_size | "20" | `INI_SYSTEM` |

Aqui está uma breve explicação das diretivas de configuração.

`oci8.connection_class` string

  Este texto definido pelo usuário deve sempre ser definido ao usar o Oracle Database Resident Connection Pooling (DRCP). Ele permite o subparticionamento do pool de conexões DRCP, permitindo que conexões persistentes OCI8 de uma aplicação reutilizem sessões de banco de dados de um script PHP anterior, proporcionando melhor escalabilidade. Quando uma aplicação usa um processo de pool de banco de dados usado anteriormente com uma classe de conexão diferente, as configurações da sessão, como por exemplo o formato de data padrão do Oracle, são redefinidas. Isso evita o compartilhamento acidental de informações entre diferentes aplicações.

  Este valor pode ser definido no momento da execução com a função ini_set() antes da conexão.

  Para usar o DRCP, o OCI8 deve estar vinculado às bibliotecas Oracle 11g (ou posterior) e o banco de dados deve ser Oracle 11g (ou posterior). O pool de conexões DRCP deve ser habilitado no banco de dados, `oci8.connection_class` deve ser definido com a mesma string para todos os servidores web que executam a mesma aplicação e a string de conexão OCI8 deve especificar o uso de um servidor em pool. A aplicação deve usar conexões persistentes.

`oci8.default_prefetch` int

  Esta opção define o número padrão de linhas extras que serão buscadas e armazenadas em cache automaticamente sempre que for feita uma solicitação de baixo nível de dados do banco de dados. Definir um valor `0` desativa a pré-busca.

  O valor de pré-busca não altera o número de linhas que funções como oci_fetch_array() retornam ao usuário; a pré-busca e o armazenamento em cache de linhas são tratados internamente no OCI8.

  O valor pode ser definido por instrução com oci_set_prefetch() antes da execução da instrução.

  Ao usar o Oracle Database 12c (ou posterior), o valor de pré-busca definido pelo PHP pode ser substituído pelo arquivo de configuração `oraaccess.xml` do cliente Oracle. Consulte a documentação da Oracle para obter mais detalhes.

  > Nota: Uma pré-busca maior pode resultar em melhor desempenho, ao custo de um aumento no uso de memória. Para consultas que retornam grandes quantidades de dados, o benefício de desempenho pode ser significativo.

`oci8.events` bool

  Usar `On` permite que o PHP seja notificado de eventos de Notificação Rápida de Aplicação (FAN) do banco de dados.

  Sem FAN, quando uma instância de banco de dados ou nó de máquina falha inesperadamente, as aplicações PHP podem ser bloqueadas aguardando uma resposta do banco de dados até que o tempo limite do TCP expire. Com eventos FAN, as aplicações PHP são rapidamente notificadas sobre falhas que afetam suas conexões de banco de dados estabelecidas. A extensão OCI8 limpará conexões inutilizáveis ​​no cache de conexões persistentes.

  Ao usar `On`, o banco de dados também precisa ser configurado para postar eventos FAN.

  O suporte FAN estará disponível quando o OCI8 estiver vinculado com bibliotecas Oracle 10gR2 (ou posterior) e conectado a banco de dados Oracle 10gR2 (ou posterior).

`oci8.max_persistent` int

  O número máximo de conexões OCI8 persistentes por processo PHP. Definir esta opção como -1 significa que não há limite.

`oci8.old_oci_close_semantics` bool

  Esta opção controla o comportamento de oci_close(). Ativá-lo significa que oci_close() não fará nada; a conexão não será fechada até o final do script. Isto é apenas para compatibilidade com versões anteriores. Se for necessário habilitar esta configuração, é fortemente recomendado o ajuste das chamadas a oci_close() na aplicação em vez de habilitar esta opção.

`oci8.persistent_timeout` int

  O número máximo de segundos que um processo PHP pode manter aberta uma conexão persistente ociosa. Definir esta opção como -1 significa que conexões persistentes ociosas serão retidas até que o processo PHP termine ou que a conexão seja explicitamente fechada com oci_close().

  > Nota: No PHP, a expiração de recursos ociosos não é baseada em alarme. Ocorre quando o PHP termina o processamento de um script e verifica o timestamp da última utilização dos recursos. Portanto, existe um paradoxo de que conexões ociosas só podem ser fechadas quando há alguma atividade (embora não necessariamente relacionada ao OCI8) no processo PHP. Se houver mais de um processo PHP, cada um deverá ser ativado individualmente para acionar a expiração de seus recursos ociosos. A introdução do Database Resident Connection Pooling (DRCP) no Oracle 11g resolve os problemas de memória e recursos que `oci8.max_persistent` e `oci8.persistent_timeout` anteriormente tentaram superar.

`oci8.ping_interval` int

  O número de segundos que devem passar antes de emitir um ping durante oci_pconnect(). Um ping garante que a conexão com o banco de dados seja válida. Quando definido como 0, as conexões persistentes serão executadas sempre que oci_pconnect() for chamada. Para desativar completamente os pings, defina esta opção como -1.

  > Nota: Desabilitar pings permite que oci_pconnect() opere com a maior eficiência, mas o PHP pode não ser capaz de detectar conexões inutilizáveis, como as causadas por queda de rede, ou se o banco de dados Oracle caiu desde que o PHP foi conectado, até que a conexão seja usada posteriormente no script. Consulte a documentação de oci_pconnect() para obter mais informações.

`oci8.prefetch_lob_size` int

  Este é um parâmetro de ajuste que afeta o buffer interno de dados LOB. Aumentar esse valor pode melhorar o desempenho da busca de LOBs menores, reduzindo as viagens de ida e volta entre o PHP e o banco de dados. O uso da memória mudará.

  O valor afeta LOBs retornados como instâncias OCILob e também aqueles retornados usando `OCI_RETURN_LOBS`.

  O valor pode ser definido por instrução com oci_set_prefetch_lob() antes da execução da instrução.

  > Nota: Use com Oracle Database 12.2 ou posterior.

`oci8.privileged_connect` bool

  Esta opção permite que as conexões usem as credenciais externas privilegiadas `OCI_SYSOPER` ou `OCI_SYSDBA`.

  > Nota: Definir isso como `On` pode permitir que scripts em servidores web executados com os privilégios de usuário do sistema operacional apropriados se conectem como usuários privilegiados do banco de dados sem exigir uma senha do banco de dados. Isso pode ser um risco à segurança.

`oci8.statement_cache_size` int

  Esta opção permite o cache de instruções e especifica quantas instruções devem ser armazenadas em cache. Para desabilitar o cache de instruções basta definir esta opção como 0.

  O cache de instruções elimina a necessidade de transmitir o texto da instrução ao banco de dados e elimina a necessidade de transmitir quaisquer metadados sobre a instrução de volta ao PHP. Isto pode melhorar significativamente o desempenho geral do sistema em aplicações que reutilizam instruções durante o tempo de vida de uma conexão. Alguns "cursores" extras de banco de dados podem ser ser mantidas abertas sob a suposição de que as instruçõs serão reutilizadas.

  Configure esse valor para o tamanho do conjunto de instruções de trabalho usado pela aplicação. Definir um valor muito pequeno pode fazer com que as instruções sejam liberadas do cache antes de serem reutilizadas.

  Esta opção é mais útil com conexões persistentes.

  Ao usar o Oracle Database 12c (ou posterior), esse valor pode ser substituído e ajustado automaticamente pelo arquivo `oraaccess.xml` do cliente Oracle. Consulte a documentação da Oracle para obter mais detalhes.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

Modos de função e métodos do OCI8
Constante | Descrição
--- | ---
`OCI_ASSOC` | Utilizado com oci_fetch_all() e oci_fetch_array() para obter os resultados em um array associativo.
`OCI_BOTH` | Utilizado com oci_fetch_all() e oci_fetch_array() para obter os resultados em um array com índices associativos e numéricos.
`OCI_COMMIT_ON_SUCCESS` | Modo de execução de instruções com oci_execute(). Automaticamente efetiva as alterações (commit) caso a instrução execute.
`OCI_CRED_EXT` | Utilizado com oci_connect() para ativar a autenticação Oracles' External ou do sistema operacional.
`OCI_DEFAULT` | Veja `OCI_NO_AUTO_COMMIT`.
`OCI_DESCRIBE_ONLY` | Modo de execução de instruções para oci_execute(). Utilize esse modo se deseja metadados como os nomes de colunas mas não deseja trazer as linhas da consulta.
`OCI_EXACT_FETCH` | Obsoleto. Modo de execução de instruções. Utilizado quando a aplicação conheça previamente quantas linhas serão lidas. Este modo desliga o prefetching a partir do Oracle release 8. O cursor é cancelado depois da quantidade deseja de linhas é lida o que pode resultar em uma menor quantidade de recursos consumidos no lado do servidor.
`OCI_FETCHSTATEMENT_BY_COLUMN` | Modo padrão do oci_fetch_all().
`OCI_FETCHSTATEMENT_BY_ROW` | Modo alternativo do oci_fetch_all().
`OCI_LOB_BUFFER_FREE` | Utilizado com OCILob::flush para liberar os buffers associados.
`OCI_NO_AUTO_COMMIT` | Modo de execução de instruções para oci_execute(). A instrução não é efetivada automaticamente nesse modo (modo sem commit). Para a legibilidade de em código, utilize esse valor ao invés da constante antiga equivalente `OCI_DEFAULT`.
`OCI_NUM` | Utilizado com oci_fetch_all() e oci_fetch_array() para obter os resultados em um array enumerado.
`OCI_RETURN_LOBS` | Utilizado com oci_fetch_array() para obter o dado do LOB ao invés do descritor.
`OCI_RETURN_NULLS` | Utilizado com oci_fetch_array() para obter elementos vazios de array se o item da linha for `null`.
`OCI_SEEK_CUR` | Utilizado com OCILob::seek para configurar a posição de leitura.
`OCI_SEEK_END` | Utilizado com OCILob::seek para configurar a posição de leitura.
`OCI_SEEK_SET` | Utilizado com OCILob::seek para configurar a posição de leitura.
`OCI_SYSDATE` | Obsoleto.
`OCI_SYSDBA` | Utilizad com oci_connect() para conectar com o privilégio SYSDBA. A configuração php.ini oci8.privileged_connect precisa estar ativada.
`OCI_SYSOPER` | Utilizado com oci_connect() para conectar com o privilégio SYSOPER. A configuração php.ini oci8.privileged_connect precisa estar ativada.
`OCI_TEMP_BLOB` | Utilizada com OCILob::writeTemporary para indicar que um BLOB temporário deve ser criado.
`OCI_TEMP_CLOB` | Utilizado com OCILob::writeTemporary para indicar que um CLOB temporário deve ser criado.

Tipos Bind e Define para do OCI8
Constante | Descrição
--- | ---
`OCI_B_BFILE` | Utilizado com oci_bind_by_name() quando associando (binding) BFILEs.
`OCI_B_BIN` | Utilizado com oci_bind_by_name() para associar (bind) valores RAW.
`OCI_B_BLOB` | Utilizado com oci_bind_by_name() quando associando (binding) BLOBs.
`OCI_B_BOL` | Utilizado com oci_bind_by_name() para associar (bind) uma variável PL/SQL booleana.
`OCI_B_CFILEE` | Utilizado com oci_bind_by_name() quando associando (binding) CFILEs.
`OCI_B_CLOB` | Utilizado com oci_bind_by_name() quando associando (binding) CLOBs.
`OCI_B_CURSOR` | Utilizado com oci_bind_by_name() quando associando (binding) cursores, anteriormente alocados com oci_new_descriptor().
`OCI_B_INT` | Utilizado com oci_bind_array_by_name() para associar (bind) arrays de INTEGER.
`OCI_B_NTY` | Utilizado com oci_bind_by_name() quando associando (binding) tipos nomeados.
`OCI_B_NUM` | Utilizado com oci_bind_array_by_name() para associar (bind) arrays de NUMBER.
`OCI_B_ROWID` | Utilizado com oci_bind_by_name() quando associando (binding) ROWIDs.
`SQLT_AFC` | Utilizado com oci_bind_array_by_name() para associar (bind) arrays de CHAR.
`SQLT_AVC` | Utilizado com oci_bind_array_by_name() para associar (bind) arrays de VARCHAR2.
`SQLT_BDOUBLE` | Não suportado.
`SQLT_BFILEE` | O mesmo que `OCI_B_BFILE`.
`SQLT_BFLOAT` | Não suportado.
`SQLT_BIN` | O mesmo que `OCI_B_BIN`.
`SQLT_BLOB` | O mesmo que `OCI_B_BLOB`.
`SQLT_BOL` | O mesmo que `OCI_B_BOL`.
`SQLT_CFILEE` | O mesmo que `OCI_B_CFILEE`.
`SQLT_CHR` | Utilizado com oci_bind_array_by_name() para associar (bind) arrays de VARCHAR2. Também utilizado com oci_bind_by_name().
`SQLT_CLOB` | O mesmo que `OCI_B_CLOB`.
`SQLT_FLT` | Utilizado com oci_bind_array_by_name() para associar (bind) arrays de FLOAT.
`SQLT_INT` | O mesmo que `OCI_B_INT`.
`SQLT_LBI` | Utilizado com oci_bind_by_name() para associar (bind) valores LONG RAW.
`SQLT_LNG` | Utilizado com oci_bind_by_name() para associar (bind) valores LONG.
`SQLT_LVC` | Utilizado com oci_bind_array_by_name() para associar (bind) arrays de LONG VARCHAR.
`SQLT_NTY` | O mesmo que `OCI_B_NTY`.
`SQLT_NUM` | O mesmo que `OCI_B_NUM`.
`SQLT_ODT` | Utilizado com oci_bind_array_by_name() para associar (bind) arrays de LONG.
`SQLT_RDD` | O mesmo que `OCI_B_ROWID`.
`SQLT_RSET` | O mesmo que `OCI_B_CURSOR`.
`SQLT_STR` | Utilizado com oci_bind_array_by_name() para associar (bind) arrays de STRING.
`SQLT_UIN` | Não suportado.
`SQLT_VCS` | Utilizado com oci_bind_array_by_name() para associar (bind) arrays de VARCHAR.

Tipos de descritores do OCI8
Constante | Descrição
--- | ---
`OCI_DTYPE_FILE` | Esse indicador faz oci_new_descriptor() inicializar um descritor FILE.
`OCI_DTYPE_LOB` | Esse indicador faz oci_new_descriptor() inicializar um descritor LOB.
`OCI_DTYPE_ROWID` | Esse indicador faz oci_new_descriptor() inicializar um descritor ROWID.
`OCI_D_FILE` | O mesmo que `OCI_DTYPE_FILE`.
`OCI_D_LOB` | O mesmo que `OCI_DTYPE_LOB`.
`OCI_D_ROWID` | O mesmo que `OCI_DTYPE_ROWID`.

Constantes | Descrição
--- | ---
Constantes do OCI8 Transparent Application Failover (TAF)
`OCI_FO_ABORT` (int) | Failover falhou e não há opção para tentar novamente.
`OCI_FO_BEGIN` (int) | Failover detectou uma conexão perdida e está iniciando.
`OCI_FO_END` (int) | Failover completou com sucesso.
`OCI_FO_ERROR` (int) | Failover não teve sucesso mas ele dará a oportunidade ao manipulador de erro e retornará `OCI_FO_RETRY` ao failover de repetição.
`OCI_FO_NONE` (int) | O usuário solicitou um tipo failover.
`OCI_FO_REAUTH` (int) | Um usuário Oracle foir re-autenticado.
`OCI_FO_RETRY` (int) | O failover deverá ser tentado novamente pelo Oracle. No caso de um erro na tentativa falhando para uma nova conexão, TAF será capaz de reiniciar o failover. Tipicamente a aplicação deve dormir antes de retornar `OCI_FO_RETRY`.
`OCI_FO_SELECT` (int) | O usuário também solicitou um failover SELECT. Ele permite aos usuários com cursores abertos continuar obtendo dados depois de um failover.
`OCI_FO_SESSION` (int) | O usuário solicitou apenas failover de sessão. Por exemplo, se uma conexão de usuário é perdida, então uma nova sessão é automaticamente criada para o usuário a partir do backup. Esse tipo de failover não tenta recuperar SELECTs.
`OCI_FO_TXNAL` (int) | O usuário solicitou um failover de transação.

# Exemplos

Estes exemplos utilizam o usuário `HR`, que faz parte do esquema de exemplo "Human Resources" fornecido com o banco de dados Oracle. A conta precisa ser desbloqueada e a senha redefinida antes de ser usada.

Os exemplos se conectam ao banco de dados `XE` na máquina local. Modifique a string de conexão para o banco de dados local antes de executar os exemplos.

Exemplo #1 Consulta básica

Este exemplo mostra consulta e resultados. Declaração no OCI8 usam passos na sequência preparação-execução-recebimento.

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Prepara a declaração
    $stid = oci_parse($conn, 'SELECT * FROM departments');
    if (!$stid) {
        $e = oci_error($conn);
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Executa a lógica da consulta
    $r = oci_execute($stid);
    if (!$r) {
        $e = oci_error($stid);
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Recebe os resultados da consulta
    print "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        print "<tr>\n";
        foreach ($row as $item) {
            print "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;") . "</td>\n";
        }
        print "</tr>\n";
    }
    print "</table>\n";

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #2 Inserindo com variáveis vinculadas

Vincular variáveis melhora o desempenho por permitir o reúso de contextos de execução e de caches. Vinculação de variáveis melhoram a segurança pois impedem alguns tipos de problemas de Injeção SQL.

    <?php

    // Antes de executar, cria a tabela:
    //   CREATE TABLE MYTABLE (mid NUMBER, myd VARCHAR2(20));

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'INSERT INTO MYTABLE (mid, myd) VALUES(:myid, :mydata)');

    $id = 60;
    $data = 'Alguns dados';

    oci_bind_by_name($stid, ':myid', $id);
    oci_bind_by_name($stid, ':mydata', $data);

    $r = oci_execute($stid);  // executa e envia

    if ($r) {
        print "Uma linha inserida";
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #3 Vinculando em cláusula WHERE de uma consulta

Este exemplo mostra uma simples vinculação de valor escalar.

    <?php

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $sql = 'SELECT last_name FROM employees WHERE department_id = :didbv ORDER BY last_name';
    $stid = oci_parse($conn, $sql);
    $didbv = 60;
    oci_bind_by_name($stid, ':didbv', $didbv);
    oci_execute($stid);
    while (($row = oci_fetch_array($stid, OCI_ASSOC)) != false) {
        echo $row['LAST_NAME'] ."<br>\n";
    }

    // Saída:
    //    Austin
    //    Ernst
    //    Hunold
    //    Lorentz
    //    Pataballa

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #4 Inserindo e recebendo um CLOB

Para grande quantidade de dados, use os tipos objeto binário longo (BLOB) ou objeto caractere longo (CLOB). Este exemplo usa CLOB.

    <?php

    // Antes de executar, cria a tabela:
    //     CREATE TABLE MYTABLE (mykey NUMBER, myclob CLOB);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $mykey = 12343;  // chave arbitrária para este exemplo;

    $sql = "INSERT INTO mytable (mykey, myclob)
            VALUES (:mykey, EMPTY_CLOB())
            RETURNING myclob INTO :myclob";

    $stid = oci_parse($conn, $sql);
    $clob = oci_new_descriptor($conn, OCI_D_LOB);
    oci_bind_by_name($stid, ":mykey", $mykey, 5);
    oci_bind_by_name($stid, ":myclob", $clob, -1, OCI_B_CLOB);
    oci_execute($stid, OCI_NO_AUTO_COMMIT);
    $clob->save("Uma string muito longa");

    oci_commit($conn);

    // Recebendo dados CLOB

    $query = 'SELECT myclob FROM mytable WHERE mykey = :mykey';

    $stid = oci_parse ($conn, $query);
    oci_bind_by_name($stid, ":mykey", $mykey, 5);
    oci_execute($stid);

    print '<table border="1">';
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_LOBS)) {
        print '<tr><td>'.$row['MYCLOB'].'</td></tr>';
        // Em uma repetição, liberar a variável grande antes do 2º recebimento reduz o pico de uso de memória do PHP
        unset($row);
    }
    print '</table>';

    ?>

Exemplo #5 Usando uma função armazenada PL/SQL

Deve-se vincular uma variável para o valor de retorno e opcionalmente para quaisquer argumentos de função PL/SQL.

    <?php

    /*
      Antes de executar o programa PHP, crie uma função armazenada no
      SQL*Plus ou SQL Developer:

      CREATE OR REPLACE FUNCTION myfunc(p IN NUMBER) RETURN NUMBER AS
      BEGIN
          RETURN p * 3;
      END;

    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $p = 8;

    $stid = oci_parse($conn, 'begin :r := myfunc(:p); end;');
    oci_bind_by_name($stid, ':p', $p);
    oci_bind_by_name($stid, ':r', $r, 40);

    oci_execute($stid);

    print "$r\n";   // mostra 24

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #6 Usando um procedimento armazenado PL/SQL

Com procedimentos armazenados, deve-se vincular variáveis, para quaisquer argumentos.

    <?php

    /*
      Antes de executar o programa PHP, crie um procedimento armazenado no
      SQL*Plus ou SQL Developer:

      CREATE OR REPLACE PROCEDURE myproc(p1 IN NUMBER, p2 OUT NUMBER) AS
      BEGIN
          p2 := p1 * 2;
      END;

    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $p1 = 8;

    $stid = oci_parse($conn, 'begin myproc(:p1, :p2); end;');
    oci_bind_by_name($stid, ':p1', $p1);
    oci_bind_by_name($stid, ':p2', $p2, 40);

    oci_execute($stid);

    print "$p2\n";   // mostra 16

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #7 Chamando uma função PL/SQL que retorna um `REF CURSOR`

Cada valor retornado da consulta é um `REF CURSOR` que permite o recebimento a partir dele.

    <?php
    /*
      Crie a função armazenada PL/SQL desta forma:

      CREATE OR REPLACE FUNCTION myfunc(p1 IN NUMBER) RETURN SYS_REFCURSOR AS
          rc SYS_REFCURSOR;
      BEGIN
          OPEN rc FOR SELECT city FROM locations WHERE ROWNUM < p1;
          RETURN rc;
      END;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'SELECT myfunc(5) AS mfrc FROM dual');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while (($row = oci_fetch_array($stid, OCI_ASSOC))) {
        echo "<tr>\n";
        $rc = $row['MFRC'];
        oci_execute($rc);  // o valor da coluna retornado da consulta é um cursor 'ref'
        while (($rc_row = oci_fetch_array($rc, OCI_ASSOC))) {
            echo "    <td>" . $rc_row['CITY'] . "</td>\n";
        }
        oci_free_statement($rc);
        echo "</tr>\n";
    }
    echo "</table>\n";

    // Saída:
    //   Beijing
    //   Bern
    //   Bombay
    //   Geneva

    oci_free_statement($stid);
    oci_close($conn);

    ?>

# Manipulação e conjunto de conexões do OCI8

## Funções de conexão

A extensão OCI8 fornece três funções diferentes para conexão com o Oracle. A função de conexão padrão é oci_connect(). Ela cria uma conexão a um banco de dados Oracle e retorna um recurso usado pelas chamadas subsequentes ao banco de dados.

Conectar-se a um servidor Oracle é uma operação razoavelmente custosa em termos de tempo que leva para ser concluída. A função oci_pconnect() usa um cache persistente de conexões que pode ser reutilizado em diferentes solicitações de script. Isso significa que a sobrecarga de conexão normalmente ocorrerá apenas uma vez por processo PHP (ou processo filho do Apache).

Se a aplicação se conectar ao Oracle usando um conjunto diferente de credenciais de banco de dados para cada usuário da web, o cache persistente empregado por oci_pconnect() se tornará menos útil à medida que o número de usuários simultâneos aumentar, a ponto de poder começar a afetar adversamente o desempenho geral do servidor Oracle devido à manutenção de muitas conexões inativas. Se a aplicação estiver estruturada desta forma, é recomendado ajustá-lo usando as configurações oci8.max_persistent e oci8.persistent_timeout (elas darão controle sobre o tamanho e o tempo de vida do cache de conexão persistente), ou usar o Oracle Database Resident Connection Pooling (no Oracle Database 11g ou posterior) ou usar oci_connect() em vez disso.

Tanto oci_connect() quanto oci_pconnect() empregam um cache de conexão; se múltiplas chamadas a oci_connect() usarem os mesmos parâmetros em um determinado script, a segunda chamada e as subsequentes retornarão o identificador de conexão existente. O cache usado por oci_connect() é limpo no final da execução do script ou quando o identificador de conexão é explicitamente fechado. A função oci_pconnect() tem comportamento semelhante, embora seu cache seja mantido separadamente e sobreviva entre requisições HTTP.

Esse recurso de cache significa que os dois identificadores não são isolados transacionalmente (eles são, na verdade, o mesmo identificador de conexão, portanto não há nenhum tipo de isolamento). Se o aplicativo precisar de duas conexões separadas e isoladas transacionalmente, use oci_new_connect().

O cache oci_pconnect() é limpo e quaisquer conexões de banco de dados são fechadas quando o processo PHP termina, portanto, o uso eficaz de conexões persistentes requer que o PHP seja um módulo Apache ou usado com FPM, ou similar. Conexões persistentes não terão nenhum benefício sobre oci_connect() quando o PHP for usado com CGI ou através da linha de comando.

A função oci_new_connect() sempre cria uma nova conexão com o servidor Oracle, independentemente de outras conexões que já possam existir. Aplicações web de alto tráfego devem evitar o uso de oci_new_connect(), especialmente nas seções mais movimentadas da aplicação.

Conexões persistentes podem ser fechadas pelo usuário, permitindo maior controle sobre o uso dos recursos da conexão. Conexões persistentes agora também serão fechadas automaticamente quando não houver nenhuma variável PHP fazendo referência a elas, como no final do escopo de uma função de usuário PHP. Isso reverterá qualquer transação não confirmada. Essas alterações nas conexões persistentes fazem com que elas se comportem de maneira semelhante às conexões não persistentes, simplificando a interface, permitindo maior consistência e previsibilidade da aplicação. Use oci8.old_oci_close_semantics definido como On para manter o comportamento histórico.

O restabelecimento automático de conexões persistentes PHP após o reaparecimento de um processo Apache ou FPM significa que os gatilhos `LOGON` do Oracle Database são recomendados apenas para definir atributos de sessão e não para solicitações de conexão de usuário por aplicação.

## Conjunto de conexões DRCP

O PHP suporta Oracle Database Resident Connection Pooling (DRCP). O DRCP permite um uso mais eficiente da memória da máquina de banco de dados e oferece alta escalabilidade. Nenhuma, ou apenas uma mínima, alteração na aplicação é necessária para usar o DRCP.

O DRCP é adequado para aplicações que se conectam usando poucos esquemas de banco de dados e mantêm conexões de abertas por um curto período de tempo. Outras aplicações devem usar os processos de servidor de banco de dados `Dedicated` (dedicados) padrão da Oracle ou usar servidores `Shared` (compartilhados).

O DRCP beneficia todas as três funções de conexão, mas oferece a maior escalabilidade quando as conexões são criadas com oci_pconnect().

Para que o DRCP esteja disponível no OCI8, as bibliotecas cliente Oracle usadas pelo PHP e a versão do banco de dados Oracle devem ser 11g ou superior.

A documentação sobre DRCP é encontrada em vários manuais da Oracle. Por exemplo, consulte » Configuring Database Resident Connection Pooling (em inglês) na documentação do Oracle para obter informações de uso. Um » artigo técnico do DRCP (em inglês) contém informações básicas sobre o DRCP.

Para usar o DRCP, instale a extensão OCI8 e as bibliotecas Oracle 11g (ou posterior) e siga estas etapas:

- Como administrador de banco de dados privilegiado, use um programa como o SQL*Plus para iniciar o conjunto de conexões no banco de dados:

          SQL> execute dbms_connection_pool.start_pool;

- Opcionalmente, use `dbms_connection_pool.alter_param()` para definir as configurações de DRCP. As configurações atuais do conjunto podem ser consultadas na visualização `DBA_CPOOL_INFO`.

- Atualize as cadeias de conexão usadas. Para aplicativos PHP que atualmente se conectam usando um nome de conexão de rede como `MYDB`:

          $c = oci_pconnect("meu_usuario", "minha_senha", "MYDB");

  modifique o arquivo tnsnames.ora e adicione uma cláusula `(SERVER=POOLED)`, por exemplo:

          MYDB = (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp) (HOST=meuhost.dom.com)
                 (PORT=1521))(CONNECT_DATA=(SERVICE_NAME=vendas)
                 (SERVER=POOLED)))

  Alternativamente, modifique a sintaxe do Easy Connect no PHP e adicione `:POOLED` após o nome do serviço:

          $c = oci_pconnect("meu_usuario", "minha_senha", "meuhost.dom.com:1521/vendas:POOLED");

- Edite o php.ini e escolha um nome de classe de conexão. Este nome indica uma divisão lógica do conjunto de conexões e pode ser usado para isolar o conjunto para aplicações separadas. Quaisquer aplicações PHP com o mesmo nome de usuário e valor de classe de conexão poderão compartilhar conexões no conjunto, proporcionando maior escalabilidade.

          oci8.connection_class = "MY_APPLICATION_NAME"

- Execute a aplicação, conectando-se ao banco de dados 11g (ou posterior).

> Nota:

> Aplicações que usam bibliotecas Oracle Client 10g que exigem o desempenho de conexões persistentes podem reduzir a quantidade de memória do servidor de banco de dados necessária usando servidores Oracle `Shared` (anteriormente conhecidos como Multi Threaded Servers). Consulte a documentação da Oracle para obter informações.

> Nota:

> A alteração de senha em conexões DRCP falhará com o erro ORA-56609: Usage not supported with DRCP (uso não suportado com DRCP). Esta é uma restrição documentada do Oracle Database 11g.

# Suporte à Notificação Rápida de Aplicação (FAN) do OCI8

O suporte ao FAN oferece recuperação rápida de falhas de conexão, um recurso de alta disponibilidade do banco de dados Oracle. Isso permite que scripts PHP OCI8 sejam notificados quando uma máquina de banco de dados ou instância de banco de dados ficar indisponível. Sem o FAN, o OCI8 pode travar até que ocorra um tempo limite de TCP e um erro seja retornado, o que pode levar vários minutos. A ativação do FAN no OCI8 pode permitir que as aplicações detectem erros e se reconectem a uma instância de banco de dados disponível sem que o usuário da web perceba uma interrupção.

O suporte ao FAN está disponível quando as bibliotecas cliente Oracle com as quais o PHP se vincula e o banco de dados Oracle são da versão 10gR2 ou posterior.

O FAN beneficia os usuários da tecnologia de cluster (RAC) da Oracle porque as conexões com as instâncias de banco de dados sobreviventes podem ser feitas imediatamente. Os usuários do Data Guard da Oracle com um mediador verão os eventos FAN gerados quando o banco de dados de reserva ficar online. Os bancos de dados autônomos enviarão eventos FAN quando o banco de dados for reiniciado.

Para conexões ativas, quando uma máquina ou instância de banco de dados ficar indisponível, um erro de falha de conexão será retornado pela função da extensão OCI8 que está sendo chamada no momento. Em uma reconexão subsequente do script PHP, será estabelecida uma conexão com uma instância de banco de dados sobrevivente. A extensão OCI8 também limpa de forma transparente quaisquer conexões ociosas afetadas por uma falha de máquina ou de instância de banco de dados, para que as chamadas de conexão do PHP estabeleçam uma nova conexão sem que o script esteja ciente de qualquer interrupção do serviço.

Quando oci8.events for igual a `On`, a sugestão é definir oci8.ping_interval para -1 para desabilitar o ping, já que habilitar eventos FAN fornece um gerenciamento proativo de conexões ociosas que se tornaram inválidas por uma interrupção de serviço.

Para ativar o suporte FAN no PHP OCI8, compile o PHP OCI8 com bibliotecas Oracle 10gR2 ou posteriores e siga estas etapas:

- Como administrador de banco de dados privilegiado, use um programa como o SQL*Plus para permitir que o serviço de banco de dados poste eventos FAN, por exemplo:

          SQL> execute dbms_service.modify_service(
                         SERVICE_NAME        => 'sales',
                         AQ_HA_NOTIFICATIONS => TRUE);

- Edite o php.ini e adicione

          oci8.events = On

- Se a aplicação ainda não lidar com condições de erro OCI8, modifique-a para detectar falhas e tomar as medidas apropriadas. Isso pode incluir a reconexão e a reexecução de instruções.
- Execute a aplicação conectando-se ao Oracle Database 10gR2 ou posterior.

# Suporte ao OCI8 Transparent Application Failover (TAF)

TAF é um recurso do Oracle Database que fornece alta disponibilidade. Ele permite que apliações PHP OCI8 se reconectem automaticamente a um banco de dados pré-configurado quando a conectividade do banco de dados falha devido a uma falha na instância ou na rede.

Em um sistema Oracle Database configurado, o TAF ocorre quando a aplicação PHP detecta que a instância do banco de dados está inativa ou inacessível. Ele estabelece uma conexão com outro nó em uma configuração Oracle » RAC, em um banco de dados hot standby ou na própria instância de banco de dados. Consulte o » Guia do programador da Interface de Chamada Oracle para obter mais informações sobre o OCI TAF.

Um retorno de chamada de aplicação pode ser registrado com oci_register_taf_callback(). Durante a recuperação da falha, o processamento normal da aplicação é interrompido e o retorno de chamada registrado é invocado. O retorno de chamada notifica a aplicação sobre os eventos de falha. Se a recuperação for bem-sucedida, o processamento normal será retomado. Se a recuperação abortar, quaisquer operações de banco de dados seguintes na aplicação falharão devido à falta de conexão disponível.

Quando uma conexão se recupera para um outro banco de dados, o retorno de chamada pode redefinir qualquer estado de conexão necessário, por exemplo, reproduzindo quaisquer comandos ALTER SESSION necessários se o serviço de banco de dados não tiver -failover_restore ativado.

Um retorno de chamada de aplicação pode ser removido chamando oci_unregister_taf_callback().

## Configurando o Transparent Application Failover

O TAF pode ser configurado no lado do PHP OCI8 ou na configuração do banco de dados. Se ambos estiverem configurados, as configurações do lado do banco de dados terão precedência.

Configure o TAF no PHP OCI8 (no lado do cliente) incluindo o parâmetro FAILOVER_MODE na parte CONNECT_DATA de um descritor de conexão. Consulte Configurando o Transparent Application Failover no » Guia do Administrador de Serviços de Rede do Oracle Database para obter mais informações sobre a configuração do lado do cliente do TAF.

Um exemplo de tnsnames.ora para configurar o TAF para reconexão à mesma instância do banco de dados:

        ORCL =
          (DESCRIPTION =
            (ADDRESS = (PROTOCOL = TCP)(HOST = 127.0.0.1)(PORT = 1521))
            (CONNECT_DATA =
              (SERVICE_NAME = orclpdb1)
              (FAILOVER_MODE =
                (TYPE = SELECT)
                (METHOD = BASIC)
                (RETRIES = 20)
                (DELAY = 15))))

Como alternativa, configure o TAF no lado do banco de dados modificando o serviço de destino com » srvctl (para RAC) ou o procedimento empacotado » DBMS_SERVICE.MODIFY_SERVICE (para bancos de dados de instância única).

## Usando Chamada de Retorno TAF no OCI8

Uma chamada de retorno TAF é uma função de aplicação que pode ser registrada para ser chamada durante a recuperação de falha. Ela é chamada diversas vezes ao restabelecer a conexão da aplicação.

A chamada de retorno ocorre primeiro quando uma perda de conexão é detectada. Isso permite que a aplicação atue de acordo com o atraso futuro da recuperação. Se a recuperação for bem-sucedida, a chamada de retorno será invocada depois que a conexão for restabelecida e utilizável. Neste momento, a aplicação pode ressincronizar as configurações da sessão e executar ações como informar ao usuário que ocorreu uma recuperação. Se ela não for bem-sucedida, ocorrerá uma chamada de retorno para informar à aplicação que a recuperação não ocorreu e que a conexão está inutilizável.

A interface de uma função de retorno TAF definida pelo usuário é a seguinte:

function userCallbackFn(resource `$connection`, int `$event`, int `$type`): int

`connection`

  A conexão Oracle na qual a chamada de retorno TAF foi registrada por meio de oci_register_taf_callback(). A conexão não é válida até que a recuperação seja concluída com êxito.

`event`

  O evento de recuperação indica o status atual da recuperação.

  - `OCI_FO_BEGIN` indica que a recuperação detectou uma conexão perdida e a recuperação está iniciando.

  - `OCI_FO_END` indica conclusão de recuperação com sucesso.

  - `OCI_FO_ABORT` indica que a recuperação não foi bem-sucedida e que não há opção de uma nova tentativa.

  - `OCI_FO_ERROR` também indica que a recuperação não foi bem-sucedida mas dá à aplicação a oportunidade de lidar com o erro e retornar OCI_FO_RETRY para tentar a recuperação novamente.

  - `OCI_FO_REAUTH` indica que um usuário Oracle foi re-autenticado.

`type`

  O tipo da recuperação. Isto permite que a função de retorno saiba que tipo de recuperação a aplicação solicitou. Os valores usuais são os seguintes:

  - `OCI_FO_SESSION` indica que o usuário solicitou recuperação apenas de sessão. Por exemplo, se uma conexão de usuário é perdida, uma nova sessão é automaticamente criada para o usuário no backup. Este tipo de recuparação não tenta recuperar SELECTs.

  - `OCI_FO_SELECT` indica que o usuário também solicitou recuperação SELECT. Isto permite que usuários com cursores abertos continuem buscando dados após a falha.

`return value`

  - `0` indica que os passos de recuperação devem continuar normalmente.

  - `OCI_FO_RETRY` indica que a recuperação deve ser tentada novamente pelo Oracle. No caso de um erro durante a recuperação para uma nova conexão, o TAF poderá tentar novamente a recuperação. Normalmente, o código da aplicação deve ficar inativo por um tempo antes de retornar OCI_FO_RETRY.

Exemplo #1 Registrando uma chamada de retorno TAF

    <?php

    // Define chamda de retorno no espaço de usuário
    class MyClass {
        public static $retry_count;
        public static function TAFCallback($conn, $event, $type)
        {
            switch ($event) {
                case OCI_FO_BEGIN:
                    printf(" Recuperando ... Por favor aguarde\n");
                    printf(" Tipo de recuperação é %s \n",
                           (($type==OCI_FO_SESSION) ? "SESSION"
                            :(($type==OCI_FO_SELECT) ? "SELECT" : "DESCONHECIDA!")));
                    self::$retry_count = 0;
                    break;
                case OCI_FO_ABORT:
                    // A aplicação não pode continuar usando o banco de dados
                    printf(" Recuperação abortada. Recuperação não irá ocorrer.\n");
                    break;
                case OCI_FO_END:
                    // Recuperação conclui com sucesso. Informa usuários que uma recuperação aconteceu.
                    printf(" Recuperação concluída ... retomando os serviços\n");
                    break;
                case OCI_FO_REAUTH:
                    printf(" Recuperando usuário ... retomando os serviços\n");
                    // Reproduz qualquer comando ALTER SESSION associados com esta conexão
                    // por exemplo, oci_parse($conn, ‘ALTER SESSION …’) ;
                    break;
                case OCI_FO_ERROR:
                    // Para de tentar se já foram feitas 20 tentativas.
                    if (self::$retry_count >= 20)
                        return 0;
                    printf(" Erro de recuperação recebido. Aguardando...\n");
                    sleep(10);
                    self::$retry_count++;
                    return OCI_FO_RETRY; // tenta a recuperação novamente
                    break;
                default:
                    printf("Evento de recuperação desconhecido: %d.\n", $event);
                    break;
            }
            return 0;
        }
    }

    $fn_name = 'MyClass::TAFCallback';

    $conn = oci_connect('hr', 'welcome', 'orcl');
    $sysconn = oci_connect('system', 'oracle', 'orcl');

    // Usa uma conexão privilegiada para construir uma instrução SQL que iniciará a recuperação
    $sql = <<< 'END'
    select unique 'alter system disconnect session '''||sid||','||serial#||''''
    from v$session_connect_info
    where sid = sys_context('USERENV', 'SID')
    END;

    $s = oci_parse($conn, $sql);
    oci_execute($s);
    $r = oci_fetch_array($s);
    $disconnectssql = $r[0];

    oci_register_taf_callback($conn, $fn_name); // Registra TAFCallback para Oracle TAF

    print "Analisando a consulta do usuário\n";
    $sql = "select systimestamp from dual";
    $stmt = oci_parse($conn, $sql);

    // Por exemplo, se ocorrer uma perda de conexão neste ponto, oci_execute() detectará
    // a perda e a recuperação será iniciada. Durante a recuperação, oci_execute() invocará
    // a função de retorno de chamada do TAF diversas vezes. Se a recuperação for bem-sucedida,
    // uma nova conexão será criada de forma transparente e oci_execute() continuará
    // normalmente. As configurações da sessão de conexão podem ser redefinidas na função de
    // retorno de chamada TAF. Se a recuperação for abortada, oci_execute() retornará um erro
    // porque uma conexão válida não está disponível.

    // Desconecta o usuário, o que inicia a recuperação
    print "Desconectando o usuário\n";
    $discsql = oci_parse($sysconn, $disconnectssql);
    oci_execute($discsql);

    print "Executando a consulta do usuário\n";
    $e = oci_execute($stmt);
    if (!$e) {
        $m = oci_error($stmt);
        trigger_error("Não foi possível executar a instrução: ". $m['message'], E_USER_ERROR);
    }
    $row = oci_fetch_array($stmt);
    print $row[0] . "\n";

    // executa outras instruções SQL com a nova conexão, se ainda for válida
    // $stmt = oci_parse($conn,  . . .);

    ?>

## Veja Também

- oci_register_taf_callback()
- oci_unregister_taf_callback()

# OCI8 e Rastreamento dinâmico DTrace

O OCI8 2.0 introduziu sondas DTrace estáticas que podem ser usadas ​​em sistemas operacionais compatíveis com o DTrace. Consulte Rastreamento Dinâmico DTrace para obter uma visão geral do PHP e do DTrace.

## Instalando OCI8 com suporte a DTrace

Para habilitar o suporte a DTrace no PHP OCI8, o OCI8 deve ser compilado como uma extensão compartilhada após a definição de `PHP_DTRACE`.

    $ export PHP_DTRACE=yes
    $ pecl install oci8

Edite o php.ini, defina extension_dir para o diretório que contém o oci8.so criado e também habilite a extensão adicionando:

    extension=oci8.so

Se o PHP OCI8 for instalado a partir do PECL usando phpize e configure (ao invés de pecl), ainda será necessário definir `PHP_DTRACE=yes`. Isto acontece porque a opção `--enable-dtrace` será ignorada pelo script configure limitado de um pacote PECL.

Consulte Instalação de extensões PECL para intruções gerais de instalação via PECL.

## Sondas Estáticas DTrace no PHP OCI8

As seguintes sondas estáticas estão disponíveis no PHP OCI8
Nome da Sonda | Descrição da Sonda | Argumentos da Sonda
--- | --- | ---
`oci8-connect-entry` | Iniciada por oci_connect(), oci_pconnect() e oci_new_connect(). É ativada antes da conexão ao banco de dados ser estabelecida. | char *username, char *dbname, char *charset, long session_mode, int persistent, int exclusive
`oci8-connect-return` | É ativada no final da conexão. | void *connection
`oci8-check-connection` | É ativada se um erro Oracle possa ter tornado a conexão inválida. | void *connection, char *client_id, int is_open, long errcode, unsigned long server_status
`oci8-sqltext` | É ativada quando oci_parse() é executada. | void *connection, char *client_id, void *statement, char *sql
`oci8-connection-close` | É ativada quando a conexão ao banco de dados é completamente destruída. | void *connection
`oci8-error` | É ativada se um erro Oracle ocorrer. | int status, long errcode
`oci8-execute-mode` | É ativada na função oci_execute() para mostrar o modo de execução. | void *connection, char *client_id, void *statement, unsigned int mode

Estas sondas são úteis para rastrear scripts OCI8.

As variáveis connection e statement são ponteiros para estruturas internas usados para rastrear conexões e instruções executadas do PHP.

A variável client_id é o valor definido por oci_set_client_identifier().

O núcleo do PHP também tem sondas estáticas. Consulte Sondas Estáticas DTrace no Núcleo do PHP.

Sondas DTrace Internas de Depuração no OCI8
Nome da Sonda
`oci8-connect-expiry`
`oci8-connect-lookup`
`oci8-connect-p-dtor-close`
`oci8-connect-p-dtor-release`
`oci8-connect-type`
`oci8-sesspool-create`
`oci8-sesspool-stats`
`oci8-sesspool-type`

Estas sondas são úteis para mantenedores do OCI8. Consulte o código-fonte para argumentos e para ver quando elas serão ativadas.

## Listando Sondas Estáticas DTrace no PHP OCI8

Para listar sondas disponíveis, inicie um processo PHP e depois execute:

    # dtrace -l

O resultado será similar a:

       ID   PROVIDER            MODULE                          FUNCTION NAME
       [ . . . ]
       17 phpoci22116           oci8.so   php_oci_dtrace_check_connection oci8-check-connection
       18 phpoci22116           oci8.so                php_oci_do_connect oci8-connect-entry
       19 phpoci22116           oci8.so         php_oci_persistent_helper oci8-connect-expiry
       20 phpoci22116           oci8.so             php_oci_do_connect_ex oci8-connect-lookup
       21 phpoci22116           oci8.so  php_oci_pconnection_list_np_dtor oci8-connect-p-dtor-close
       22 phpoci22116           oci8.so  php_oci_pconnection_list_np_dtor oci8-connect-p-dtor-release
       23 phpoci22116           oci8.so                php_oci_do_connect oci8-connect-return
       24 phpoci22116           oci8.so             php_oci_do_connect_ex oci8-connect-type
       25 phpoci22116           oci8.so          php_oci_connection_close oci8-connection-close
       26 phpoci22116           oci8.so                     php_oci_error oci8-error
       27 phpoci22116           oci8.so         php_oci_statement_execute oci8-execute-mode
       28 phpoci22116           oci8.so              php_oci_create_spool oci8-sesspool-create
       29 phpoci22116           oci8.so            php_oci_create_session oci8-sesspool-stats
       30 phpoci22116           oci8.so            php_oci_create_session oci8-sesspool-type
       31 phpoci22116           oci8.so          php_oci_statement_create oci8-sqltext

Os valores da coluna PROVIDER consistem no prefixo `phpoci` e o ID fo processo PHP atual.

A coluna FUNCTION refere-se aos nomes de função da implementação C interna do PHP onde cada provedor está localizado.

Se um processo PHP não estiver em execução, nenhuma sonda PHP será exibida.

## Exemplo de DTrace com PHP OCI8

Este exemplo mostra o básico da linguagem de script D do DTrace.

Exemplo #1 user_oci8_probes.d para rastrear todas as Sondas Estáticas PHP OCI8 em nível de usuário com DTrace

    #!/usr/sbin/dtrace -Zs

    #pragma D option quiet

    php*:::oci8-connect-entry
    {
        printf("%lld: PHP connect-entry\n", walltimestamp);
        printf("  credentials=\"%s@%s\"\n", arg0 ? copyinstr(arg0) : "", arg1 ? copyinstr(arg1) : "");
        printf("  charset=\"%s\"\n", arg2 ? copyinstr(arg2) : "");
        printf("  session_mode=%ld\n", (long)arg3);
        printf("  persistent=%d\n", (int)arg4);
        printf("  exclusive=%d\n", (int)arg5);
    }

    php*:::oci8-connect-return
    {
        printf("%lld: PHP oci8-connect-return\n", walltimestamp);
        printf("  connection=0x%p\n", (void *)arg0);
    }

    php*:::oci8-connection-close
    {
        printf("%lld: PHP oci8-connect-close\n", walltimestamp);
        printf("  connection=0x%p\n", (void *)arg0);
    }

    php*:::oci8-error
    {
        printf("%lld: PHP oci8-error\n", walltimestamp);
        printf("  status=%d\n", (int)arg0);
        printf("  errcode=%ld\n", (long)arg1);
    }

    php*:::oci8-check-connection
    {
        printf("%lld: PHP oci8-check-connection\n", walltimestamp);
        printf("  connection=0x%p\n", (void *)arg0);
        printf("  client_id=\"%s\"\n", arg1 ? copyinstr(arg1) : "");
        printf("  is_open=%d\n", arg2);
        printf("  errcode=%ld\n", (long)arg3);
        printf("  server_status=%lu\n", (unsigned long)arg4);
    }

    php*:::oci8-sqltext
    {
        printf("%lld: PHP oci8-sqltext\n", walltimestamp);
        printf("  connection=0x%p\n", (void *)arg0);
        printf("  client_id=\"%s\"\n", arg1 ? copyinstr(arg1) : "");
        printf("  statement=0x%p\n", (void *)arg2);
        printf("  sql=\"%s\"\n", arg3 ? copyinstr(arg3) : "");
    }

    php*:::oci8-execute-mode
    {
        printf("%lld: PHP oci8-execute-mode\n", walltimestamp);
        printf("  connection=0x%p\n", (void *)arg0);
        printf("  client_id=\"%s\"\n", arg1 ? copyinstr(arg1) : "");
        printf("  statement=0x%p\n", (void *)arg2);
        printf("  mode=0x%x\n", arg3);
    }

Este script usa a opção `-Z` para dtrace, permitindo que ele seja executado quando não houver processo PHP em execução. Se esta opção fosse omitida, o script terminaria imediatamente quando nenhum executável do PHP estivesse em execução porque ele sabe que nenhuma das sondas a serem monitoradas existiriam.

Em máquinas com múltiplas CPUs, a ordem das sondas pode não parecer sequencial. Isto depende de qual CPU está processando as sondas, e como os threads migram através dos CPUs. Exibir o horário de cada sonda ajuda a reduzir a confusão.

O script rastreia todos os pontos de sondas estáticas do PHP OCI8 em nível de usuário, durante toda a execução do script PHP. Execute o script D:

    # ./user_oci8_probes.d

Execute uma aplicação ou um script PHP. O script D de monitoramento exeubirá os argumentos de cada sonda assim que ativada. Por exemplo, um simples script PHP que consulta uma tabela pode produzir o seguinte resultado de rastreamento:

    1381794982092854582: PHP connect-entry
      credentials="hr@localhost/pdborcl"
      charset=""
      session_mode=0
      persistent=0
      exclusive=0
    1381794982183158766: PHP oci8-connect-return
      connection=0x7f4a7907bfb8
    1381794982183594576: PHP oci8-sqltext
      connection=0x7f4a7907bfb8
      client_id="Chris"
      statement=0x7f4a7907c2a0
      sql="select * from employees"
    1381794982183783706: PHP oci8-execute-mode
      connection=0x7f4a7907bfb8
      client_id="Chris"
      statement=0x7f4a7907c2a0
      mode=0x20
    1381794982444344390: PHP oci8-connect-close
      connection=0x7f4a7907bfb8

Quando o monitoramento estiver concluído, o script D pode ser encerrado com um ``CTRL`+`C``.

## Veja Também

- Rastreamento Dinâmico DTrace

# Tipos de dados suportados

O driver oferece suporte aos seguintes tipos ao vincular parâmetros usando a função oci_bind_by_name():
Tipo | Mapeamento
--- | ---
`SQLT_NTY` | Mapeia um tipo de coleção nativo de um objeto de coleção PHP, como aqueles criados por oci_new_collection().
`SQLT_BFILEE` | Mapeia um descritor nativo, como aqueles criados por oci_new_descriptor().
`SQLT_CFILEE` | Mapeia um descritor nativo, como aqueles criados por oci_new_descriptor().
`SQLT_CLOB` | Mapeia um descritor nativo, como aqueles criados por oci_new_descriptor().
`SQLT_BLOB` | Mapeia um descritor nativo, como aqueles criados por oci_new_descriptor().
`SQLT_RDD` | Mapeia um descritor nativo, como aqueles criados por oci_new_descriptor().
`SQLT_NUM` | Converte o parâmetro PHP em um tipo longo 'C' e vincula a esse valor.
`SQLT_RSET` | Mapeia um identificador de instrução nativo, como aqueles criados por oci_parse() ou aqueles recuperados de outras consultas do OCI.
`SQLT_BOL` | Vincula o parâmetro PHP a um BOOLEAN PL/SQL.
`SQLT_CHR` e qualquer outro tipo | Converte o parâmetro PHP em um tipo string e vincula como uma string.

Os seguintes tipos são suportados ao recuperar colunas de um conjunto de resultados:
Tipo | Mapeamento
--- | ---
`SQLT_RSET` | Cria um recurso de instrução OCI para representar o cursor.
`SQLT_RDD` | Cria um objeto ROWID.
`SQLT_BLOB` | Cria um objeto LOB.
`SQLT_CLOB` | Cria um objeto LOB.
`SQLT_BFILE` | Cria um objeto LOB.
`SQLT_LNG` | Vinculado como SQLT_CHR, retornado como uma string.
`SQLT_LBI` | Vinculado como `SQLT_BIN`, retornado como uma string.
Qualquer outro tipo | Vinculado como `SQLT_CHR`, retornado como uma string.

# Funções OCI8

# oci_bind_array_by_name

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL OCI8 >= 1.2.0)

oci_bind_array_by_name — Vincula um array PHP a um parâmetro de array Oracle PL/SQL

### Descrição

function oci_bind_array_by_name(
resource `$statement`,
string `$param`,
array `&$var`,
int `$max_array_length`,
int `$max_item_length` = -1,
int `$type` = `SQLT_AFC`
): bool

Vincula o array PHP `var` ao marcador Oracle `param`, que aponta para um array Oracle PL/SQL. Se ele será usado para entrada ou saída será determinado no momento da execução.

### Parâmetros

`statement`

  Um identificador de instrução OCI válido.

`param`

  O marcador Oracle.

`var`

  Um array.

`max_array_length`

  Define o comprimento máximo para arrays de entrada e de resultados.

`max_item_length`

  Define o comprimento máximo para itens de array. Se não for especificado ou for igual a -1, oci_bind_array_by_name() encontrará o elemento mais longo no array de entrada e o usará como o comprimento máximo.

`type`

  Deve ser usado para definir o tipo de itens de array PL/SQL. Veja a lista de tipos disponíveis abaixo:

  - `SQLT_NUM` - para arrays de NUMBER.

  - `SQLT_INT` - para arrays de INTEGER (Nota: INTEGER na verdade é um sinônimo de NUMBER(38) mas o tipo `SQLT_NUM` não funcionará neste caso embora sejam sinônimos).

  - `SQLT_FLT` - para arrays de FLOAT.

  - `SQLT_AFC` - para arrays de CHAR.

  - `SQLT_CHR` - para arrays de VARCHAR2.

  - `SQLT_VCS` - para arrays de VARCHAR.

  - `SQLT_AVC` - para arrays de CHARZ.

  - `SQLT_STR` - para arrays de STRING.

  - `SQLT_LVC` - para arrays de LONG VARCHAR.

  - `SQLT_ODT` - para arrays de DATE.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de oci_bind_array_by_name()

    <?php

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $create = "CREATE TABLE bind_example(name VARCHAR(20))";
    $stid = oci_parse($conn, $create);
    oci_execute($stid);

    $create_pkg = "
    CREATE OR REPLACE PACKAGE ARRAYBINDPKG1 AS
      TYPE ARRTYPE IS TABLE OF VARCHAR(20) INDEX BY BINARY_INTEGER;
      PROCEDURE iobind(c1 IN OUT ARRTYPE);
    END ARRAYBINDPKG1;";
    $stid = oci_parse($conn, $create_pkg);
    oci_execute($stid);

    $create_pkg_body = "
    CREATE OR REPLACE PACKAGE BODY ARRAYBINDPKG1 AS
      CURSOR CUR IS SELECT name FROM bind_example;
      PROCEDURE iobind(c1 IN OUT ARRTYPE) IS
        BEGIN
        -- Inserção em massa
        FORALL i IN INDICES OF c1
          INSERT INTO bind_example VALUES (c1(i));

        -- Busca e reverte
        IF NOT CUR%ISOPEN THEN
          OPEN CUR;
        END IF;
        FOR i IN REVERSE 1..5 LOOP
          FETCH CUR INTO c1(i);
          IF CUR%NOTFOUND THEN
            CLOSE CUR;
            EXIT;
          END IF;
        END LOOP;
      END iobind;
    END ARRAYBINDPKG1;";
    $stid = oci_parse($conn, $create_pkg_body);
    oci_execute($stid);

    $stid = oci_parse($conn, "BEGIN arraybindpkg1.iobind(:c1); END;");
    $array = array("one", "two", "three", "four", "five");
    oci_bind_array_by_name($stid, ":c1", $array, 5, -1, SQLT_CHR);
    oci_execute($stid);

    var_dump($array);

    ?>

# oci_bind_by_name

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_bind_by_name — Vincula uma variável PHP a um marcador Oracle

### Descrição

function oci_bind_by_name(
resource `$statement`,
string `$param`,
mixed `&$var`,
int `$max_length` = -1,
int `$type` = 0
): bool

Vincula uma variável PHP `var` ao marcador de variável vinculada do Oracle `param`. A vinculação é importante para o desempenho do banco de dados Oracle e também é uma forma de evitar problemas de segurança de injeção de SQL.

A vinculação permite que o banco de dados reutilize o contexto da instrução e armazena em cache execuções anteriores da instrução, mesmo que outro usuário ou processo a tenha executado originalmente. A vinculação reduz as preocupações com injeção de SQL porque os dados associados a uma variável vinculada nunca são tratados como parte da instrução SQL. Ela não precisa de escape.

Variáveis ​​PHP que foram vinculadas podem ser alteradas e a declaração reexecutada sem a necessidade de analisar novamente a declaração ou revincular.

No Oracle, as variáveis de vinculação são comumente divididas em vinculações `IN` para valores que são passados ​​para o banco de dados, e vinculações `OUT` para valores que são retornados ao PHP. Uma variável de vinculação pode ser tanto `IN` quanto `OUT`. O fato de uma variável de vinculação ser usada para entrada ou saída é determinado em tempo de execução.

É necessário especificar `max_length` ao usar uma vinculação `OUT` para que o PHP aloque memória suficiente para armazenar o valor retornado.

Para vinculações `IN`, é recomendado definir o comprimento `max_length` se a instrução for reexecutada várias vezes com valores diferentes para a variável PHP. Caso contrário, o Oracle pode truncar os dados para o comprimento do valor inicial da variável PHP. Se não for conhecido o comprimento máximo, deve ser chamada novamente a função oci_bind_by_name() com o tamanho de dados atual antes de cada chamada oci_execute(). Vincular um comprimento desnecessariamente grande trará um impacto na memória do processo no banco de dados.

Uma chamada de vinculação informa ao Oracle de qual endereço de memória os dados serão lidos. Para vinculações `IN`, esse endereço precisa conter dados válidos quando oci_execute() for chamada. Isso significa que a variável vinculada deve permanecer no escopo até a execução. Se isso não acontecer, resultados inesperados ou erros como "ORA-01460: unimplemented or unreasonable conversion requested" (solicitada conversão não implementada não razoável) podem ocorrer. Para vinculações `OUT`, um dos sintomas é quando nenhum valor é definido na variável PHP.

Para uma instrução que é executada repetidamente, valores vinculados que nunca mudam podem reduzir a capacidade do otimizador Oracle em escolher o melhor plano de execução de instrução. Instruções de execução longa que raramente são reexecutadas podem não se beneficiar da vinculação. No entanto, em ambos os casos a vinculação pode ser mais segura do que juntar strings em uma instrução SQL, pois isso pode ser um risco de segurança se o texto não filtrado do usuário for concatenado.

### Parâmetros

`statement`

  Um identificador de instrução OCI8 válido.

`param`

  O marcador de variável vinculada prefixado com dois pontos usado na instrução. Os dois pontos são opcionais em `param`. O Oracle não usa pontos de interrogação para marcadores.

`var`

  A variável PHP a ser associada a `param`.

`max_length`

  Define o comprimento máximo para os dados. Se for definido como -1, esta função usará o comprimento atual de `var` para definir o comprimento máximo. Neste caso, o `var` deve existir e conter dados quando oci_bind_by_name() for chamada.

`type`

  O tipo de dados como o Oracle tratará os dados. O `type` padrão usado é `SQLT_CHR`. O Oracle converterá os dados entre este tipo e a coluna do banco de dados (ou tipo de variável PL/SQL), quando possível.

  Se for necessário vincular um tipo de dado abstrato (LOB/ROWID/BFILE), ele deve ser alocado primeiro usando a função oci_new_descriptor(). O parâmetro `length` não é usado para tipos de dados abstratos e deve ser definido como -1.

  Os valores possíveis para `type` são:

  - `SQLT_BFILEE` ou `OCI_B_BFILE` - para BFILEs;

  - `SQLT_CFILEE` ou `OCI_B_CFILEE` - para CFILEs;

  - `SQLT_CLOB` ou `OCI_B_CLOB` - para CLOBs;

  - `SQLT_BLOB` ou `OCI_B_BLOB` - para BLOBs;

  - `SQLT_RDD` ou `OCI_B_ROWID` - para ROWIDs;

  - `SQLT_NTY` ou `OCI_B_NTY` - para tipos de dados nomeados;

  - `SQLT_INT` ou `OCI_B_INT` - para inteiros;

  - `SQLT_CHR` - para VARCHARs;

  - `SQLT_BIN` ou `OCI_B_BIN` - para colunas RAW;

  - `SQLT_LNG` - para colunas LONG;

  - `SQLT_LBI` - para colunas LONG RAW;

  - `SQLT_RSET` - para cursores criados com oci_new_cursor();

  - `SQLT_BOL` ou `OCI_B_BOL` - para BOOLEANs PL/SQL (Requer Oracle Database 12c)

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Inserindo dados com oci_bind_by_name()

    <?php

    // Crie a tabela com:
    //   CREATE TABLE mytab (id NUMBER, text VARCHAR2(40));

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn,"INSERT INTO mytab (id, text) VALUES(:id_bv, :text_bv)");

    $id = 1;
    $text = "Dados a inserir     ";
    oci_bind_by_name($stid, ":id_bv", $id);
    oci_bind_by_name($stid, ":text_bv", $text);
    oci_execute($stid);

    // A tabela agora contém: 1, 'Dados a inserir     '

    ?>

Exemplo #2 Vinculando uma vez para múltiplas execuções

    <?php

    // Crie a tabela com:
    //   CREATE TABLE mytab (id NUMBER);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $a = array(1,3,5,7,11);  // dados a inserir

    $stid = oci_parse($conn, 'INSERT INTO mytab (id) VALUES (:bv)');
    oci_bind_by_name($stid, ':bv', $v, 20);
    foreach ($a as $v) {
        $r = oci_execute($stid, OCI_DEFAULT);  // não confirma automaticamente
    }
    oci_commit($conn); // confirma tudo de uma vez

    // A tabela contém cinco linhas: 1, 3, 5, 7, 11

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #3 Vinculando com um laço `foreach`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $sql = 'SELECT * FROM departments WHERE department_name = :dname AND location_id = :loc';
    $stid = oci_parse($conn, $sql);

    $ba = array(':dname' => 'IT Support', ':loc' => 1700);

    foreach ($ba as $key => $val) {

        // oci_bind_by_name($stid, $key, $val) não funciona
        // porque ela vincula cada marcado à mesma localização: $val
        // em vez disso, use a localização real dos dados: $ba[$key]
        oci_bind_by_name($stid, $key, $ba[$key]);
    }

    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS);
    foreach ($row as $item) {
        print $item."<br>\n";
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #4 Vinculando em uma cláusula WHERE

    <?php

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $sql = 'SELECT last_name FROM employees WHERE department_id = :didbv ORDER BY last_name';
    $stid = oci_parse($conn, $sql);
    $didbv = 60;
    oci_bind_by_name($stid, ':didbv', $didbv);
    oci_execute($stid);
    while (($row = oci_fetch_array($stid, OCI_ASSOC)) != false) {
        echo $row['LAST_NAME'] ."<br>\n";
    }

    // O resultado é
    //    Austin
    //    Ernst
    //    Hunold
    //    Lorentz
    //    Pataballa

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #5 Vinculando com uma cláusula LIKE

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    // Encontre todas as cidades que começam com 'South'
    $stid = oci_parse($conn, "SELECT city FROM locations WHERE city LIKE :bv");
    $city = 'South%';  // '%' é um coringa no SQL
    oci_bind_by_name($stid, ":bv", $city);
    oci_execute($stid);
    oci_fetch_all($stid, $res);

    foreach ($res['CITY'] as $c) {
        print $c . "<br>\n";
    }
    // O resultado é
    //   South Brunswick
    //   South San Francisco
    //   Southlake

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #6 Vinculando com REGEXP_LIKE

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    // Encontre todas as cidades que contenham 'ing'
    $stid = oci_parse($conn, "SELECT city FROM locations WHERE REGEXP_LIKE(city, :bv)");
    $city = '.*ing.*';
    oci_bind_by_name($stid, ":bv", $city);
    oci_execute($stid);
    oci_fetch_all($stid, $res);

    foreach ($res['CITY'] as $c) {
        print $c . "<br>\n";
    }
    // O resultado é
    //   Beijing
    //   Singapore

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Para um número pequeno e fixo de condições de cláusula IN, use variáveis vinculadas individuais. Valores desconhecidos no momento da execução podem ser definidos como NULL. Isso permite que uma única instrução seja usada por todos os usuários do aplicativo, maximizando a eficiência do cache do Oracle DB.

Exemplo #7 Vinculando vários valores em uma cláusula IN

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $sql = 'SELECT last_name FROM employees WHERE employee_id in (:e1, :e2, :e3)';
    $stid = oci_parse($conn, $sql);
    $mye1 = 103;
    $mye2 = 104;
    $mye3 = NULL; // finja que não nos foi dado esse valor
    oci_bind_by_name($stid, ':e1', $mye1);
    oci_bind_by_name($stid, ':e2', $mye2);
    oci_bind_by_name($stid, ':e3', $mye3);
    oci_execute($stid);
    oci_fetch_all($stid, $res);
    foreach ($res['LAST_NAME'] as $name) {
        print $name ."<br>\n";
    }

    // O resultado é
    //   Ernst
    //   Hunold

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #8 Vinculando um ROWID retornado por uma consulta

    <?php

    // Crie a tabela com:
    //   CREATE TABLE mytab (id NUMBER, salary NUMBER, name VARCHAR2(40));
    //   INSERT INTO mytab (id, salary, name) VALUES (1, 100, 'Chris');
    //   COMMIT;

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT ROWID, name FROM mytab WHERE id = :id_bv FOR UPDATE');
    $id = 1;
    oci_bind_by_name($stid, ':id_bv', $id);
    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS);
    $rid = $row['ROWID'];
    $name = $row['NAME'];

    // Altera nome para maiúsculas e salva as alterações
    $name = strtoupper($name);
    $stid = oci_parse($conn, 'UPDATE mytab SET name = :n_bv WHERE ROWID = :r_bv');
    oci_bind_by_name($stid, ':n_bv', $name);
    oci_bind_by_name($stid, ':r_bv', $rid, -1, OCI_B_ROWID);
    oci_execute($stid);

    // A tabela agora contém 1, 100, CHRIS

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #9 Vinculando um ROWID em INSERT

    <?php

    // Este exemplo insere um id e um nome e, em seguida, atualiza o salário
    // Crie a tabela com:
    //   CREATE TABLE mytab (id NUMBER, salary NUMBER, name VARCHAR2(40));
    //
    // Baseado no exemplo ROWID original de thies at thieso dot net (980221)

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $sql = "INSERT INTO mytab (id, name) VALUES(:id_bv, :name_bv)
            RETURNING ROWID INTO :rid";

    $ins_stid = oci_parse($conn, $sql);

    $rowid = oci_new_descriptor($conn, OCI_D_ROWID);
    oci_bind_by_name($ins_stid, ":id_bv",   $id,    10);
    oci_bind_by_name($ins_stid, ":name_bv", $name,  32);
    oci_bind_by_name($ins_stid, ":rid",     $rowid, -1, OCI_B_ROWID);

    $sql = "UPDATE mytab SET salary = :salary WHERE ROWID = :rid";
    $upd_stid = oci_parse($conn, $sql);
    oci_bind_by_name($upd_stid, ":rid", $rowid, -1, OCI_B_ROWID);
    oci_bind_by_name($upd_stid, ":salary", $salary,   32);

    // ids e nomes para inserir
    $data = array(1111 => "Larry",
                  2222 => "Bill",
                  3333 => "Jim");

    // Salário de cada pessoa
    $salary = 10000;

    // Insere e atualiza imediatamente cada linha
    foreach ($data as $id => $name) {
        oci_execute($ins_stid);
        oci_execute($upd_stid);
    }

    $rowid->free();
    oci_free_statement($upd_stid);
    oci_free_statement($ins_stid);

    // Mostra as novas linhas
    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid);
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        var_dump($row);
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #10 Vinculação para uma função armazenada PL/SQL

    <?php

    //  Antes de executar o programa PHP, crie uma função armazenada em
    //  SQL*Plus ou SQL Developer:
    //
    //  CREATE OR REPLACE FUNCTION myfunc(p IN NUMBER) RETURN NUMBER AS
    //  BEGIN
    //      RETURN p * 3;
    //  END;

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $p = 8;

    $stid = oci_parse($conn, 'begin :r := myfunc(:p); end;');
    oci_bind_by_name($stid, ':p', $p);

    // O valor de retorno é uma vinculação OUT. O tipo padrão
    // será um tipo string, então vincular um comprimento 40
    // significa que no máximo 40 dígitos serão retornados.
    oci_bind_by_name($stid, ':r', $r, 40);

    oci_execute($stid);

    print "$r\n";   // prints 24

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #11 Vinculando parâmetros para um procedimento armazenado PL/SQL

    <?php

    //  Antes de executar o programa PHP, crie um procedimento armazenado em
    //  SQL*Plus ou SQL Developer:
    //
    //  CREATE OR REPLACE PROCEDURE myproc(p1 IN NUMBER, p2 OUT NUMBER) AS
    //  BEGIN
    //      p2 := p1 * 2;
    //  END;

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $p1 = 8;

    $stid = oci_parse($conn, 'begin myproc(:p1, :p2); end;');
    oci_bind_by_name($stid, ':p1', $p1);

    // O segundo parâmetro do procedimento é uma vinculação OUT. O tipo padrão
    // será um tipo string, então vincular um comprimento 40 significa que no máximo 40
    // dígitos serão retornados.
    oci_bind_by_name($stid, ':p2', $p2, 40);

    oci_execute($stid);

    print "$p2\n";   // exibe 16

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #12 Vinculando uma coluna CLOB

    <?php

    // Antes de executar, crie a tabela:
    //     CREATE TABLE mytab (mykey NUMBER, myclob CLOB);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $mykey = 12343;  // chave arbitrária para este exemplo;

    $sql = "INSERT INTO mytab (mykey, myclob)
            VALUES (:mykey, EMPTY_CLOB())
            RETURNING myclob INTO :myclob";

    $stid = oci_parse($conn, $sql);
    $clob = oci_new_descriptor($conn, OCI_D_LOB);
    oci_bind_by_name($stid, ":mykey", $mykey, 5);
    oci_bind_by_name($stid, ":myclob", $clob, -1, OCI_B_CLOB);
    oci_execute($stid, OCI_DEFAULT);
    $clob->save("A very long string");

    oci_commit($conn);

    // Obtendo dados CLOB

    $query = 'SELECT myclob FROM mytab WHERE mykey = :mykey';

    $stid = oci_parse ($conn, $query);
    oci_bind_by_name($stid, ":mykey", $mykey, 5);
    oci_execute($stid);

    print '<table border="1">';
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_LOBS)) {
        print '<tr><td>'.$row['MYCLOB'].'</td></tr>';
        // Em um laço, liberar a variável grande antes da segunda busca reduz o pico de uso de memória do PHP
        unset($row);
    }
    print '</table>';

    ?>

Exemplo #13 Vinculando um BOOLEAN PL/SQL

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $plsql =
      "begin
        :output1 := true;
        :output2 := false;
       end;";

    $s = oci_parse($c, $plsql);
    oci_bind_by_name($s, ':output1', $output1, -1, OCI_B_BOL);
    oci_bind_by_name($s, ':output2', $output2, -1, OCI_B_BOL);
    oci_execute($s);
    var_dump($output1);  // true
    var_dump($output2);  // false

    ?>

### Notas

Aviso

Não use addslashes() e oci_bind_by_name() simultaneamente, pois nenhum escape é necessário. Qualquer escape aplicado magicamente será gravado no banco de dados porque oci_bind_by_name() insere dados literalmente e não remove asaps ou caracteres de escape.

> Nota:

> Se uma string for vinculada a uma coluna `CHAR` em uma cláusula `WHERE`, lembre-se de que o Oracle usa semântica de comparação com preenchimento em branco para colunas `CHAR`. A variável PHP deve ser preenchida com preenchimento em branco para a mesma largura da coluna para que a cláusula `WHERE` seja bem-sucedida.

> Nota:

> O argumento `var` do PHP é uma referência. Algumas formas de laços não funcionam como esperado:

>     <?php
>     foreach ($myarray as $key => $value)  {
>         oci_bind_by_name($stid, $key, $value);
>     }
>     ?>

> Isso vincula cada chave à localização de $value, então todas as variáveis vinculadas acabam apontando para o valor da última iteração do laço. Em vez disso, use o seguinte:

>     <?php
>     foreach ($myarray as $key => $value) {
>         oci_bind_by_name($stid, $key, $myarray[$key]);
>     }
>     ?>

### Veja Também

- oci_bind_array_by_name() - Vincula um array PHP a um parâmetro de array Oracle PL/SQL
- oci_parse() - Prepara uma instrução Oracle para execução

# oci_cancel

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_cancel — Cancela a leitura do cursor

### Descrição

function oci_cancel(resource `$statement`): bool

Invalida um cursor, liberando todos os recursos associados e cancelando a capacidade de leitura dele.

### Parâmetros

`statement`

  Uma instrução OCI.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# oci_client_version

(PHP 5 >= 5.3.7, PHP 7, PHP 8, PECL OCI8 >= 1.4.6)

oci_client_version — Retorna a versão da biblioteca do cliente Oracle

### Descrição

function oci_client_version(): string

Retorna uma string contendo o número da versão da biblioteca cliente Oracle C à qual o PHP está vinculado.

### Parâmetros

Nenhum

### Valor Retornado

Retorna o número da versão como uma string.

### Exemplos

Exemplo #1 Exemplo de oci_client_version()

    <?php
        echo "Versão do cliente: " . oci_client_version(); // Versão do cliente: 19.9.0.0.0
    ?>

### Notas

> Nota:

> As bibliotecas Oracle anteriores a 10gR2 não têm a funcionalidade subjacente para obter o número da versão da biblioteca cliente. A string "Unknown" será retornada neste caso.

### Veja Também

- oci_server_version() - Retorna a versão do banco de dados Oracle

# oci_close

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_close — Fecha uma conexão Oracle

### Descrição

function oci_close(resource `$connection`): ?bool

Remove a definição da conexão `connection`. A conexão do banco de dados subjacente é fechada se nenhum outro recurso a estiver usando e se ela foi criada com oci_connect() ou oci_new_connect().

É recomendável fechar conexões que não são mais necessárias porque isso torna os recursos do banco de dados disponíveis para outros usuários.

### Parâmetros

`connection`

  Um identificador de conexão Oracle retornado por oci_connect(), oci_pconnect(), ou oci_new_connect().

### Valor Retornado

Retorna `null` quando oci8.old_oci_close_semantics está habilitado, ou `true` caso contrário.

### Exemplos

Exemplo #1 Fechando uma conexão

Os recursos associados a uma conexão devem ser fechados para garantir que a conexão do banco de dados subjacente seja encerrada corretamente e os recursos do banco de dados sejam liberados.

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM departments');
    $r = oci_execute($stid);
    oci_fetch_all($stid, $res);
    var_dump($res);

    // Libera o identificador da instrução ao fechar a conexão
    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #2 As conexões de banco de dados não são fechadas até que todas as referências sejam fechadas

A contagem de referência interna de um identificador de conexão deve ser zero antes que a conexão subjacente ao banco de dados seja fechada.

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM departments');  // isto aumenta a contagem de referência de $conn
    oci_execute($stid);
    oci_fetch_all($stid, $res);
    var_dump($res);

    oci_close($conn);

    // $conn não é mais utilizável no script, mas a conexão do banco de dados
    // subjacente ainda é mantida aberta até que $stid seja liberado.
    var_dump($conn);  // exibe NULL

    // Enquanto o PHP dorme, consultar a visualização Oracle V$SESSION em uma
    // janela de terminal mostrará que o usuário do banco de dados ainda está conectado.
    sleep(10);

    // Quando $stid é liberado, a conexão com o banco de dados é fisicamente fechada
    oci_free_statement($stid);

    // Enquanto o PHP dorme, consultar a visualização Oracle V$SESSION em uma
    // janela de terminal mostrará que o usuário do banco de dados foi desconectado.
    sleep(10);

    ?>

Exemplo #3 Fechando uma conexão aberta mais de uma vez

Quando as credenciais do banco de dados são reutilizadas, ambas as conexões devem ser fechadas antes que a conexão do banco de dados subjacente seja fechada.

    <?php

    $conn1 = oci_connect('hr', 'welcome', 'localhost/XE');

    // Usar as mesmas credenciais reutiliza a mesma conexão de banco de dados subjacente
    // Quaisquer alterações não confirmadas feitas em $conn1 serão visíveis em $conn2
    $conn2 = oci_connect('hr', 'welcome', 'localhost/XE');

    // Enquanto o PHP dorme, consultar a visualização Oracle V$SESSION em uma
    // janela de terminal mostrará que apenas um usuário do banco de dados está conectado.
    sleep(10);

    oci_close($conn1); // não fecha a conexão do banco de dados subjacente
    var_dump($conn1);  // exibe NULL porque a variável $conn1 não é mais utilizável
    var_dump($conn2);  // exibe que $conn2 ainda é um recurso de conexão válido

    ?>

Exemplo #4 As conexões são fechadas quando as variáveis ​​saem do escopo

Quando todas as variáveis ​​que referenciam uma conexão saem do escopo e são liberadas pelo PHP, ocorre uma reversão (se necessário) e a conexão subjacente ao banco de dados é fechada.

    <?php

    function myfunc() {
        $conn = oci_connect('hr', 'hrpwd', 'localhost/XE');
        if (!$conn) {
            $e = oci_error();
            trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
        }

        $stid = oci_parse($conn, 'UPDATE mytab SET id = 100');
        oci_execute($stid, OCI_NO_AUTO_COMMIT);
        return "Concluído";
    }

    $r = myfunc();
    // Neste ponto, ocorreu uma reversão e a conexão com o banco de dados subjacente foi liberada.

    print $r;  // exibe o valor de retorno da função "Concluído"

    ?>

### Notas

> Nota:

> Variáveis ​​que têm uma dependência no identificador de conexão, como identificadores de declaração retornados por oci_parse(), também devem ser liberadas antes que a conexão do banco de dados subjacente seja fechada.

> Nota:

> A função oci_close() não fecha as conexões de banco de dados subjacentes criadas com oci_pconnect().

### Veja Também

- oci_connect() - Conecta-se a um banco de dados Oracle
- oci_free_statement() - Libera todos os recursos associados à instrução ou cursor

# oci_commit

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_commit — Confirma a transação de banco de dados pendente

### Descrição

function oci_commit(resource `$connection`): bool

Confirma a transação pendente para a conexção Oracle informada em `connection`. Uma confirmação encerra a transação atual e torna permanentes todas as alterações. Ela libera todos os bloqueios mantidos.

Uma transação começa quando a primeira instrução SQL que altera os dados é executada com oci_execute() usando o sinalizador `OCI_NO_AUTO_COMMIT`. Outras alterações de dados feitas por outras instruções se tornam parte da mesma transação. As alterações de dados feitas em uma transação são temporárias até que a transação seja confirmada ou revertida. Outros usuários do banco de dados não verão as alterações até que sejam confirmadas.

Ao inserir ou atualizar dados, é recomendado usar transações para consistência de dados relacionais e por motivos de desempenho.

### Parâmetros

`connection`

  Um identificador de conexão Oracle, retornado por oci_connect(), oci_pconnect() ou oci_new_connect().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de oci_commit()

    <?php

    // Inserindo em várias tabelas, revertendo as alterações se ocorrer um erro

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, "INSERT INTO mysalary (id, name) VALUES (1, 'Chris')");

    // O sinalizador OCI_NO_AUTO_COMMIT informa ao Oracle para não confirmar o INSERT imediatamente
    $r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
    if (!$r) {
        $e = oci_error($stid);
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'INSERT INTO myschedule (startday) VALUES (12)');
    $r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
    if (!$r) {
        $e = oci_error($stid);
        oci_rollback($conn);  // reverte alterações em ambas as tabelas
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    // Confirma as alterações em ambas as tabelas
    $r = oci_commit($conn);
    if (!$r) {
        $e = oci_error($conn);
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    ?>

### Notas

> Nota:

> As transações são automaticamente revertidas quando você fecha a conexão, ou quando o script termina, o que ocorrer primeiro. Você precisa chamar explicitamente oci_commit() para confirmar a transação.

> Qualquer chamada para oci_execute() que use o modo `OCI_COMMIT_ON_SUCCESS` explicitamente ou por padrão confirmará qualquer transação anterior não confirmada.

> Qualquer instrução Oracle DDL como `CREATE` ou `DROP` confirmará automaticamente qualquer transação não confirmada.

### Veja Também

- oci_execute() - Executa uma instrução
- oci_rollback() - Reverte a transação pendente do banco de dados

# oci_connect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_connect — Conecta-se a um banco de dados Oracle

### Descrição

function oci_connect(
string `$username`,
string `$password`,
?string `$connection_string` = `null`,
string `$encoding` = "",
int `$session_mode` = `OCI_DEFAULT`
): resource|false

Retorna um identificador de conexão necessário para a maioria das outras operações OCI8.

Para melhor desempenho, a maioria das aplicações deve usar conexões persistentes com oci_pconnect() em vez de oci_connect(). Consulte Manipulação de Conexões para obter informações gerais sobre gerenciamento de conexões e pool de conexões.

A segunda chamada e as subsequentes a oci_connect() com os mesmos parâmetros retornarão o identificador de conexão retornado da primeira chamada. Isso significa que as transações em um identificador também estão nos outros identificadores, pois usam a mesma conexão de banco de dados subjacente. Se dois identificadores precisarem ser isolados transacionalmente um do outro, use oci_new_connect().

### Parâmetros

`username`

  O nome de usuário do Oracle.

`password`

  A senha para `username`.

`connection_string`
  Contém a `instância do Oracle` à qual se conectar. Pode ser uma » string Easy Connect ou um Connect Name do arquivo tnsnames.ora ou o nome de uma instância local do Oracle. Se não especificado ou `null`, o PHP usará variáveis de ambiente como `TWO_TASK` (no Linux) ou `LOCAL` (no Windows) e `ORACLE_SID` para determinar a `instância do Oracle` à qual se conectar. Para usar o método de nomenclatura Easy Connect, o PHP precisa ter sido compilado com as bibliotecas Oracle Client 10g ou superiores. A string Easy Connect para o Oracle 10g tem o formato: [//]nome_do_servidor[:porta][/nome_do_servico]. A partir do Oracle 11g a sintaxe é: [//]nome_do_servidor[:porta][/nome_do_servico][:tipo_de_servidor][/nome_da_instancia]. Outras opções foram introduzidas com o Oracle 19c, incluindo as configurações de timeout e keep-alive. Consulte a documentação do Oracle. Os nomes dos serviços podem ser encontrados executando o utilitário Oracle `lsnrctl status` na máquina do servidor de banco de dados. O arquivo tnsnames.ora pode estar no caminho de pesquisa Oracle Net, que inclui /seu/caminho/para/instantclient/network/admin, $ORACLE_HOME/network/admin e /etc. Como alternativa, defina `TNS_ADMIN` para que $TNS_ADMIN/tnsnames.ora possa ser lido. Certifique-se de que o servidor web tem acesso de leitura ao arquivo.
`encoding`
  Determina o conjunto de caracteres usado pelas bibliotecas Oracle Client. O conjunto de caracteres não precisa corresponder ao conjunto de caracteres usado pelo banco de dados. Se não corresponderem, o Oracle fará o possível para converter os dados de e para o conjunto de caracteres do banco de dados. Dependendo dos conjuntos de caracteres, isso pode não fornecer resultados utilizáveis. A conversão também adiciona alguma sobrecarga de tempo. Se não for especificado, as bibliotecas Oracle Client determinam um conjunto de caracteres a partir da variável de ambiente `NLS_LANG`. Passar este parâmetro pode reduzir o tempo necessário para conectar.
`session_mode`
  Este parâmetro está disponível a partir do PHP 5 (PECL OCI8 1.1) e aceita os seguintes valores: `OCI_DEFAULT`, `OCI_SYSOPER` e `OCI_SYSDBA`. Se `OCI_SYSOPER` ou `OCI_SYSDBA` forem especificadas, esta função tentará estabelecer uma conexão privilegiada usando credenciais externas. Conexões privilegiadas estão desabilitadas por padrão. Para habilitá-las é preciso configurar oci8.privileged_connect para `On`. O PHP 5.3 (PECL OCI8 1.3.4) introduziu o valor de modo `OCI_CRED_EXT`. Ele informa ao Oracle para usar autenticação External ou OS, que deve ser configurada no banco de dados. A flag `OCI_CRED_EXT` só pode ser usada com o usuário "/" e uma senha vazia. oci8.privileged_connect pode ser `On` ou `Off`. `OCI_CRED_EXT` pode ser combinado com os modos `OCI_SYSOPER` ou `OCI_SYSDBA`. `OCI_CRED_EXT` não é suportado no Windows por razões de segurança.

### Valor Retornado

Retorna um identificador de conexão ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | `connection_string` agora é anulável.

### Exemplos

Exemplo #1 oci_connect() básico usando sintaxe Easy Connect

    <?php

    // Conecta-se ao serviço XE (ou seja, banco de dados) na máquina "localhost"
    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Exemplo #2 oci_connect() básico usando um nome de conexão de rede

    <?php

    // Conecta-se ao banco de dados MYDB descrito no arquivo tnsnames.ora,
    // Um exemplo de entrada tnsnames.ora para MYDB poderia ser:
    //   MYDB =
    //     (DESCRIPTION =
    //       (ADDRESS = (PROTOCOL = TCP)(HOST = mymachine.oracle.com)(PORT = 1521))
    //       (CONNECT_DATA =
    //         (SERVER = DEDICATED)
    //         (SERVICE_NAME = XE)
    //       )
    //     )

    $conn = oci_connect('hr', 'welcome', 'MYDB');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Exemplo #3 oci_connect() com um conjunto de caracteres explícito

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE', 'AL32UTF8');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Exemplo #4 Usando múltiplas chamadas a oci_connect()

    <?php

    $c1 = oci_connect("hr", "welcome", 'localhost/XE');
    $c2 = oci_connect("hr", "welcome", 'localhost/XE');

    // Tanto $c1 quanto $c2 mostram o mesmo ID de recurso PHP, o que significa que eles usam a
    // mesma conexão de banco de dados subjacente
    echo "c1 é $c1<br>\n";
    echo "c2 é $c2<br>\n";

    function create_table($conn)
    {
        $stmt = oci_parse($conn, "create table hallo (test varchar2(64))");
        oci_execute($stmt);
        echo "Tabela criada<br>\n";
    }

    function drop_table($conn)
    {
        $stmt = oci_parse($conn, "drop table hallo");
        oci_execute($stmt);
        echo "Tabela excluída<br>\n";
    }

    function insert_data($connname, $conn)
    {
        $stmt = oci_parse($conn, "insert into hallo
                  values(to_char(sysdate,'DD-MON-YY HH24:MI:SS'))");
        oci_execute($stmt, OCI_DEFAULT);
        echo "$connname inserida linha sem confirmação<br>\n";
    }

    function rollback($connname, $conn)
    {
        oci_rollback($conn);
        echo "$connname revertendo<br>\n";
    }

    function select_data($connname, $conn)
    {
        $stmt = oci_parse($conn, "select * from hallo");
        oci_execute($stmt, OCI_DEFAULT);
        echo "$connname ----selecionando<br>\n";
        while (oci_fetch($stmt)) {
            echo "    " . oci_result($stmt, "TEST") . "<br>\n";
        }
        echo "$connname ----feito<br>\n";
    }

    create_table($c1);

    insert_data('c1', $c1);   // Insere uma linha usando c1
    sleep(2);                 // Espera para mostrar um horário diferente para a 2ª linha
    insert_data('c2', $c2);   // Insere uma linha usando c2

    select_data('c1', $c1);   // Os resultados de ambas as inserções são retornados
    select_data('c2', $c2);   // Os resultados de ambas as inserções são retornados

    rollback('c1', $c1);      // Reverte usando c1

    select_data('c1', $c1);   // Ambas as inserções foram revertidas
    select_data('c2', $c2);

    drop_table($c1);

    // Fechar uma das conexões torna a variável PHP inutilizável, mas
    // a outra pode ser usada
    oci_close($c1);
    echo "c1 é $c1<br>\n";
    echo "c2 é $c2<br>\n";

    // O resultado é:
    //    c1 é Resource id #5
    //    c2 é Resource id #5
    //    Tabela criada
    //    c1 inseriu linha sem confirmar
    //    c2 inseriu linha sem confirmar
    //    c1 ----selecionando
    //        09-DEC-09 12:14:43
    //        09-DEC-09 12:14:45
    //    c1 ----feito
    //    c2 ----selecionando
    //        09-DEC-09 12:14:43
    //        09-DEC-09 12:14:45
    //    c2 ----feito
    //    c1 revertendo
    //    c1 ----selecionando
    //    c1 ----feito
    //    c2 ----selecionando
    //    c2 ----feito
    //    Tabela excluída
    //    c1 é
    //    c2 é Resource id #5

    ?>

### Notas

> Nota:

> Uma extensão OCI8 instalada ou configurada incorretamente frequentemente se manifestará como um problema ou erro de conexão. Consulte Instalando/Configurando para obter informações sobre solução de problemas.

### Veja Também

- oci_pconnect() - Conecta-se a um banco de dados Oracle usando uma conexão persistente
- oci_new_connect() - Conecta-se ao servidor Oracle usando uma conexão exclusiva
- oci_close() - Fecha uma conexão Oracle

# oci_define_by_name

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_define_by_name — Associa uma variável PHP a uma coluna para buscas de consulta

### Descrição

function oci_define_by_name(
resource `$statement`,
string `$column`,
mixed `&$var`,
int `$type` = 0
): bool

Associa uma variável PHP a uma coluna para buscas de consulta usando oci_fetch().

A chamada oci_define_by_name() deve ocorrer antes de executar oci_execute().

### Parâmetros

`statement`
  Um identificador de declaração OCI8 válida criada por oci_parse() e executada por oci_execute() ou um identificador de declaração `REF CURSOR`.
`column`

  O nome da coluna usada na consulta.

  Use letras maiúsculas para os nomes de colunas padrão do Oracle, que não diferenciam maiúsculas de minúsculas. Use a forma exata do nome da coluna para nomes de colunas que diferenciam maiúsculas de minúsculas.

`var`

  A variável PHP que conterá o valor da coluna retornada.

`type`

  O tipo de dado a ser retornado. Geralmente não é necessário. Observe que conversões de dados no estilo Oracle não são realizadas. Por exemplo, `SQLT_INT` será ignorado e o tipo de dado retornado ainda será `SQLT_CHR`.

  Opcionalmente, podem ser usada a função oci_new_descriptor() para alocar descritores LOB/ROWID/BFILE.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de oci_define_by_name()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
    $stid = oci_parse($conn, $sql);

    // As definições DEVEM ser feitas antes da execução
    oci_define_by_name($stid, 'LOCATION_ID', $locid);
    oci_define_by_name($stid, 'CITY', $city);

    oci_execute($stid);

    // Cada busca preenche as variáveis ​​definidas anteriormente com os dados da próxima linha
    while (oci_fetch($stid)) {
        echo "location_id $locid é $city<br>\n";
    }

    // Resultado:
    //   location_id 1000 é Roma
    //   location_id 1100 é Venice

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #2 oci_define_by_name() com nomes de colunas que diferenciam maiúsculas de minúsculas

    <?php

    /*
      Antes de executar, crie a tabela com um nome de coluna que diferencie maiúsculas de minúsculas:
        CREATE TABLE mytab (id NUMBER, "MyDescription" VARCHAR2(30));
        INSERT INTO mytab (id, "MyDescription") values (1, 'Iced Coffee');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM mytab');

    // Use letras maiúsculas para nomes de colunas que não diferenciam maiúsculas de minúsculas
    oci_define_by_name($stid, 'ID', $id);

    // Use a caixa exata para nomes de colunas que diferenciam maiúsculas de minúsculas
    oci_define_by_name($stid, 'MyDescription', $mydesc);

    oci_execute($stid);

    while (oci_fetch($stid)) {
        echo "id $id é $mydesc<br>\n";
    }

    // Resultado:
    //   id 1 é Iced Coffee

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #3 oci_define_by_name() com colunas LOB

    <?php

    /*
      Antes de executar, crie a tabela:
        CREATE TABLE mytab (id NUMBER, fruit CLOB);
        INSERT INTO mytab (id, fruit) values (1, 'apple');
        INSERT INTO mytab (id, fruit) values (2, 'orange');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM mytab');

    // As definições DEVEM ser feitas antes da execução
    oci_define_by_name($stid, 'ID', $id);
    oci_define_by_name($stid, 'FRUIT', $fruit);  // $fruit will become a LOB descriptor

    oci_execute($stid);

    while (oci_fetch($stid)) {
        echo $id . " é " . $fruit->load(100) . "<br>\n";
    }

    // Resultado:
    //   1 é apple
    //   2 é orange

    $fruit->free();
    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #4 oci_define_by_name() com um tipo explícito

    <?php

    /*
      Antes de executar, crie a tabela:
        CREATE TABLE mytab (id NUMBER, fruit CLOB);
        INSERT INTO mytab (id, fruit) values (1, 'apple');
        INSERT INTO mytab (id, fruit) values (2, 'orange');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM mytab');

    // As definições DEVEM ser feitas antes da execução
    oci_define_by_name($stid, 'ID', $id);

    $fruit = oci_new_descriptor($conn, OCI_D_LOB);
    oci_define_by_name($stid, 'FRUIT', $fruit, OCI_D_CLOB);

    oci_execute($stid);

    while (oci_fetch($stid)) {
        echo $id . " é " . $fruit->load(100) . "<br>\n";
    }

    // Resultado:
    //   1 é apple
    //   2 é orange

    $fruit->free();
    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Veja Também

- oci_fetch() - Busca a próxima linha de uma consulta em buffers internos
- oci_new_descriptor() - Inicializa um novo descritor LOB ou FILE vazio

# oci_error

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_error — Retorna o último erro encontrado

### Descrição

function oci_error(?resource `$connection_or_statement` = `null`): array|false

Retorna o último erro encontrado.

A função deve ser chamada imediatamente após a ocorrência de um erro. Os erros são limpos por uma instrução bem-sucedida.

### Parâmetros

`connection_or_statement`

  Para a maioria dos erros, `connection_or_statement` é o identificador de recurso que foi passado para a chamada de função com falha. Para erros de conexão com oci_connect(), oci_new_connect() ou oci_pconnect() `null` deve se passado.

### Valor Retornado

Se nenhum erro for encontrado, oci_error() retornará `false`. Caso contrário, oci_error() retornará as informações do erro como um array associativo.

Descrição do array de oci_error()
Chave do array | Tipo | Descrição
--- | --- | ---
`code` | int | O número de erro do Oracle.
`message` | string | O texto de erro do Oracle.
`offset` | int | A posição do byte de um erro na instrução SQL. Se não houver nenhuma instrução, o valor será `0`.
`sqltext` | string | O texto da instrução SQL. Se não houver instrução, será uma string vazia.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | `connection_or_statement` agora é anulável.

### Exemplos

Exemplo #1 Exibindo a mensagem de erro do Oracle após um erro de conexão

    <?php
    $conn = oci_connect("hr", "welcome", "localhost/XE");
    if (!$conn) {
        $e = oci_error();   // Para erros oci_connect não informe um identificador
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }
    ?>

Exemplo #2 Exibindo a mensagem de erro do Oracle após um erro de análise

    <?php
    $stid = oci_parse($conn, "select ' from dual");  // observe aspas incompatíveis
    if (!$stid) {
        $e = oci_error($conn);  // Para erros oci_parse passe o identificador de conexão
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }
    ?>

Exemplo #3 Exibindo a mensagem de erro do Oracle, a instrução problemática e a posição do problema de um erro de execução

    <?php
    $stid = oci_parse($conn, "select does_not_exist from dual");
    $r = oci_execute($stid);
    if (!$r) {
        $e = oci_error($stid);  // Para erros oci_execute passe o identificador de instrução
        print htmlentities($e['message']);
        print "\n<pre>\n";
        print htmlentities($e['sqltext']);
        printf("\n%".($e['offset']+1)."s", "^");
        print  "\n</pre>\n";
    }
    ?>

# oci_execute

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_execute — Executa uma instrução

### Descrição

function oci_execute(resource `$statement`, int `$mode` = `OCI_COMMIT_ON_SUCCESS`): bool

Executa a instrução do parâmetro `statement` anteriormente retornada por oci_parse().

Após a execução, instruções como `INSERT` terão os dados confirmados no banco de dados por padrão. Para instruções como `SELECT`, a execução executa a lógica da consulta. Os resultados da consulta podem ser posteriormente obtidos em PHP com funções como oci_fetch_array().

Cada instrução analisada pode ser executada várias vezes, economizando o custo de nova análise. Isso é comumente usado para instruções `INSERT` quando os dados são vinculados com oci_bind_by_name().

### Parâmetros

`statement`

  Um identificador de instrução OCI válido.

`mode`

  Um segundo parâmetro opcional pode ser uma das seguintes constantes:

  Modos de execução
  Constante | Descrição
  --- | ---
  `OCI_COMMIT_ON_SUCCESS` | Confirma automaticamente todas as alterações pendentes para esta conexão quando a instrução for bem-sucedida. Este é o padrão.
  `OCI_DESCRIBE_ONLY` | Disponibiliza metadados de consulta para funções como oci_field_name(), mas não cria um conjunto de resultados. Qualquer chamada de busca subsequente, como oci_fetch_array(), falhará.
  `OCI_NO_AUTO_COMMIT` | Não confirma alterações automaticamente.

  O uso do modo `OCI_NO_AUTO_COMMIT` inicia ou continua uma transação. As transações são revertidas automaticamente quando a conexão é fechada ou quando o script termina. Explicitamente, chame oci_commit() para confirmar uma transação, ou oci_rollback() para abortá-la.

  Ao inserir ou atualizar dados, o uso de transações é recomendado para consistência de dados relacionais e por questões de desempenho.

  Se o modo `OCI_NO_AUTO_COMMIT` for usado para qualquer instrução, incluindo consultas, e oci_commit() ou oci_rollback() não for chamada posteriormente, o OCI8 executará uma reversão no final do script, mesmo que nenhum dado tenha sido alterado. Para evitar uma reversão desnecessária, muitos scripts não usam o modo `OCI_NO_AUTO_COMMIT` para consultas ou PL/SQL. Tenha cuidado para garantir a consistência transacional apropriada para a aplicação ao usar oci_execute() com modos diferentes no mesmo script.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 oci_execute() para consultas

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Exemplo #2 Exemplod de oci_execute() sem especificar um modo

    <?php

    // Antes de executar, crie a tabela:
    //   CREATE TABLE MYTABLE (col1 NUMBER);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (123)');

    oci_execute($stid); // A linha é confirmada e fica imediatamente visível para outros usuários

    ?>

Exemplo #3 Exemplo de oci_execute() com `OCI_NO_AUTO_COMMIT`

    <?php

    // Antes de executar, crie a tabela:
    //   CREATE TABLE MYTABLE (col1 NUMBER);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (:bv)');
    oci_bind_by_name($stid, ':bv', $i, 10);
    for ($i = 1; $i <= 5; ++$i) {
        oci_execute($stid, OCI_NO_AUTO_COMMIT);
    }
    oci_commit($conn);  // confirma todos os novos valores: 1, 2, 3, 4, 5

    ?>

Exemplo #4 Exemplo de oci_execute() com diferentes modos de confirmação

    <?php

    // Antes de executar, crie a tabela:
    //   CREATE TABLE MYTABLE (col1 NUMBER);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (123)');
    oci_execute($stid, OCI_NO_AUTO_COMMIT);  // dados não confirmados

    $stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (456)');
    oci_execute($stid);  // confirma tanto 123 quanto 456

    ?>

Exemplo #5 Exemplo de oci_execute() com `OCI_DESCRIBE_ONLY`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'SELECT * FROM locations');
    oci_execute($s, OCI_DESCRIBE_ONLY);
    for ($i = 1; $i <= oci_num_fields($stid); ++$i) {
        echo oci_field_name($stid, $i) . "<br>\n";
    }

    ?>

### Notas

> Nota:

> As transações são revertidas automaticamente quando as conexões são fechadas ou quando o script termina, o que ocorrer primeiro. Explicitamente chame oci_commit() para confirmar uma transação.

> Qualquer chamada para oci_execute() que utilize o modo `OCI_COMMIT_ON_SUCCESS` explicitamente ou por padrão confirmará qualquer transação anterior não confirmada.

> Qualquer instrução DDL do Oracle, como `CREATE` ou `DROP`, confirmará automaticamente qualquer transação não confirmada.

> Nota:

> Como a função oci_execute() geralmente envia a instrução para o banco de dados, oci_execute() pode identificar alguns erros de sintaxe de instrução que a função oci_parse() (local e mais leve) não consegue.

### Veja Também

- oci_parse() - Prepara uma instrução Oracle para execução

# oci_fetch

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch — Busca a próxima linha de uma consulta em buffers internos

### Descrição

function oci_fetch(resource `$statement`): bool

Busca a próxima linha de uma consulta em buffers internos acessíveis com oci_result() ou usando variáveis previamente definidas com oci_define_by_name().

Consulte oci_fetch_array() para obter informações gerais sobre como buscar dados.

### Parâmetros

`statement`
  Um identificador de declaração OCI8 válida criada por oci_parse() e executada por oci_execute() ou um identificador de declaração `REF CURSOR`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` se não houver mais linhas em `statement`.

### Exemplos

Exemplo #1 oci_fetch() com variáveis definidas

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
    $stid = oci_parse($conn, $sql);

    // As definições DEVEM ser feitas antes da execução
    oci_define_by_name($stid, 'LOCATION_ID', $locid);
    oci_define_by_name($stid, 'CITY', $city);

    oci_execute($stid);

    // Cada busca preenche as variáveis ​​definidas anteriormente com os dados da próxima linha
    while (oci_fetch($stid)) {
        echo "Localização ID $locid é $city<br>\n";
    }

    // Exibe:
    //   Localização ID 1000 é Roma
    //   Localização ID 1100 é Venice

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #2 oci_fetch() com oci_result()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    while (oci_fetch($stid)) {
        echo oci_result($stid, 'LOCATION_ID') . " é ";
        echo oci_result($stid, 'CITY') . "<br>\n";
    }

    // Exibe:
    //   1000 é Roma
    //   1100 é Venice

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Notas

> Nota:

> Esta função não retornará linhas de conjuntos de resultados implícitos do Oracle Database. Use oci_fetch_array() em vez disso.

### Veja Também

- oci_define_by_name() - Associa uma variável PHP a uma coluna para buscas de consulta
- oci_fetch_all() - Busca várias linhas de uma consulta em um array bidimensional
- oci_fetch_array() - Retorna a próxima linha de uma consulta como um array associativo ou numérico
- oci_fetch_assoc() - Retorna a próxima linha de uma consulta como um array associativo
- oci_fetch_object() - Retorna a próxima linha de uma consulta como um objeto
- oci_fetch_row() - Retorna a próxima linha de uma consulta como um array numérico
- oci_result() - Retorna o valor do campo da linha recuperada

# oci_fetch_all

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_all — Busca várias linhas de uma consulta em um array bidimensional

### Descrição

function oci_fetch_all(
resource `$statement`,
array `&$output`,
int `$offset` = 0,
int `$limit` = -1,
int `$flags` = OCI_FETCHSTATEMENT_BY_COLUMN | OCI_ASSOC
): int

Busca várias linhas de uma consulta em um array bidimensional. Por padrão, todas as linhas são retornadas.

Esta função pode ser chamada apenas uma vez para cada consulta executada com oci_execute().

### Parâmetros

`statement`
  Um identificador de declaração OCI8 válida criada por oci_parse() e executada por oci_execute() ou um identificador de declaração `REF CURSOR`.
`output`

  A variável para conter as linhas retornadas.

  As colunas LOB são retornadas como strings, onde o Oracle suporta conversão.

  Veja oci_fetch_array() para mais informações sobre como dados e tipos são obtidos.

`offset`

  O número de linhas iniciais a serem descartadas ao buscar o resultado. O valor padrão é 0, então a primeira linha em diante é retornada.

`limit`

  O número de linhas a serem retornadas. O padrão é -1, o que significa que retorna todas as linhas a partir de `offset` + 1.

`flags`

  O parâmetro `flags` indica a estrutura do array e se arrays associativos devem ser usados.

  Modos de estrutura de array de oci_fetch_all()
  Constante | Descrição
  --- | ---
  `OCI_FETCHSTATEMENT_BY_ROW` | O array externo conterá um sub-array por linha de consulta.
  `OCI_FETCHSTATEMENT_BY_COLUMN` | O array externo conterá um sub-array por coluna de consulta. Este é o padrão.

  Os arrays podem ser indexados por título de coluna ou numericamente. Apenas um modo de indexação será retornado.

  oci_fetch_all() Array Index Modes
  Constante | Descrição
  --- | ---
  `OCI_NUM` | Índices numéricos são usados ​​para cada array de coluna.
  `OCI_ASSOC` | Índices associativos são usados para cada array de coluna. Este é o padrão.

  Use o operador de adição "+" para escolher uma combinação de estrutura de array e modos de índice.

  Os nomes de colunas padrão do Oracle não diferenciam maiúsculas de minúsculas e terão chaves de array em letras maiúsculas. Os nomes de colunas que diferenciam maiúsculas de minúsculas terão chaves de array usando a capitalização exata da coluna. Use var_dump() em `output` para verificar a capitalização apropriada a ser usada em cada consulta.

  Consultas que tenham mais de uma coluna com o mesmo nome devem usar apelidos de coluna. Caso contrário, apenas uma das colunas aparecerá em um array associativo.

### Valor Retornado

Retorna o número de linhas em `output`, que pode ser 0 ou mais.

### Exemplos

Exemplo #1 Exemplo de oci_fetch_all()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT POSTAL_CODE, CITY FROM locations WHERE ROWNUM < 3');
    oci_execute($stid);

    $nrows = oci_fetch_all($stid, $res);

    echo "$nrows linhas buscadas<br>\n";
    var_dump($res);

    // O resultado será:
    //    2 linhas buscadas
    //    array(2) {
    //      ["POSTAL_CODE"]=>
    //      array(2) {
    //        [0]=>
    //        string(6) "00989x"
    //        [1]=>
    //        string(6) "10934x"
    //      }
    //      ["CITY"]=>
    //      array(2) {
    //        [0]=>
    //        string(4) "Roma"
    //        [1]=>
    //        string(6) "Venice"
    //      }
    //    }

    // Tabelando os resultados
    echo "<table border='1'>\n";
    foreach ($res as $col) {
        echo "<tr>\n";
        foreach ($col as $item) {
            echo "    <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #2 Exemplo de oci_fetch_all() com `OCI_FETCHSTATEMENT_BY_ROW`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT POSTAL_CODE, CITY FROM locations WHERE ROWNUM < 3');
    oci_execute($stid);

    $nrows = oci_fetch_all($stid, $res, null, null, OCI_FETCHSTATEMENT_BY_ROW);

    echo "$nrows linhas buscadas<br>\n";
    var_dump($res);

    // O resultado será:
    //    2 linhas buscadas
    //    array(2) {
    //      [0]=>
    //      array(2) {
    //        ["POSTAL_CODE"]=>
    //        string(6) "00989x"
    //        ["CITY"]=>
    //        string(4) "Roma"
    //      }
    //      [1]=>
    //      array(2) {
    //        ["POSTAL_CODE"]=>
    //        string(6) "10934x"
    //        ["CITY"]=>
    //        string(6) "Venice"
    //      }
    //    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #3 oci_fetch_all() com `OCI_NUM`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT POSTAL_CODE, CITY FROM locations WHERE ROWNUM < 3');
    oci_execute($stid);

    $nrows = oci_fetch_all($stid, $res, null, null, OCI_FETCHSTATEMENT_BY_ROW + OCI_NUM);

    echo "$nrows linhas buscadas<br>\n";
    var_dump($res);

    // O resultado será:
    //    2 linhas buscadas
    //    array(2) {
    //      [0]=>
    //      array(2) {
    //        [0]=>
    //        string(6) "00989x"
    //        [1]=>
    //        string(4) "Roma"
    //      }
    //      [1]=>
    //      array(2) {
    //        [0]=>
    //        string(6) "10934x"
    //        [1]=>
    //        string(6) "Venice"
    //      }
    //    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Notas

> Nota:

> Usar `offset` é muito ineficiente. Todas as linhas a serem ignoradas são incluídas no conjunto de resultados que é retornado do banco de dados para o PHP. Elas são então descartadas. É mais eficiente usar SQL para restringir o deslocamento e o intervalo de linhas na consulta. Veja oci_fetch_array() para um exemplo.

> Nota:

> Consultas que retornam um grande número de linhas podem ser mais eficientes em termos de memória se uma função de busca de linha única como oci_fetch_array() for usada.

> Nota: Para consultas que retornam um grande número de linhas, o desempenho pode ser melhorado significativamente aumentando oci8.default_prefetch ou usando oci_set_prefetch().

> Nota:

> Esta função não retornará linhas do Conjuntos de Resultados Implícitos do Oracle Database 12c. Use oci_fetch_array() em vez disso.

### Veja Também

- oci_fetch() - Busca a próxima linha de uma consulta em buffers internos
- oci_fetch_array() - Retorna a próxima linha de uma consulta como um array associativo ou numérico
- oci_fetch_assoc() - Retorna a próxima linha de uma consulta como um array associativo
- oci_fetch_object() - Retorna a próxima linha de uma consulta como um objeto
- oci_fetch_row() - Retorna a próxima linha de uma consulta como um array numérico
- oci_set_prefetch() - Define o número de linhas a serem pré-buscadas pelas consultas

# oci_fetch_array

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_array — Retorna a próxima linha de uma consulta como um array associativo ou numérico

### Descrição

function oci_fetch_array(resource `$statement`, int `$mode` = OCI_BOTH | OCI_RETURN_NULLS): array|false

Retorna um array contendo a próxima linha do conjunto de resultados de uma consulta. Cada entrada do array corresponde a uma coluna da linha. Esta função é normalmente chamada em um laço até retornar `false`, indicando que não existem mais linhas.

Se `statement` corresponder a um bloco PL/SQL retornando Conjuntos de Resultados Implícitos do Banco de Dados Oracle, as linhas de todos os conjuntos serão buscadas consecutivamente. Se `statement` for retornado por oci_get_implicit_resultset(), somente o subconjunto de linhas de uma consulta filha será retornado.

Para obter detalhes sobre o mapeamento dos tipos de dados realizado pela extensão OCI8, consulte os tipos de dados suportados pelo driver.

### Parâmetros

`statement`
  Um identificador de declaração OCI8 válida criada por oci_parse() e executada por oci_execute() ou um identificador de declaração `REF CURSOR`.

  Também pode ser um identificador de instrução retornado por oci_get_implicit_resultset().

`mode`

  Um segundo parâmetro opcional pode ser qualquer combinação das seguintes constantes:

  Modos de oci_fetch_array()
  Constante | Descrição
  --- | ---
  `OCI_BOTH` | Retorna um array com índices associativos e numéricos. É o mesmo que `OCI_ASSOC` + `OCI_NUM` e é o comportamento padrão.
  `OCI_ASSOC` | Retorna um array associativa.
  `OCI_NUM` | Retorna um array numérico.
  `OCI_RETURN_NULLS` | Cria elementos para campos `null`. Os valores do elemento serão um PHP `null`.
  `OCI_RETURN_LOBS` | Retorna o conteúdo dos LOBs em vez dos descritores de LOB.

  O `mode` padrão é `OCI_BOTH`.

  Use o operador de adição "+" para especificar mais de um modo por vez.

### Valor Retornado

Retorna um array com índices associativos e/ou numéricos. Se não houver mais linhas em `statement`, `false` será retornado.

Por padrão, as colunas `LOB` são retornadas como descritores LOB.

As colunas `DATE` são retornadas como strings no formato de data atual. O formato padrão pode ser alterado com variáveis ​​de ambiente Oracle, como `NLS_LANG` ou por um comando `ALTER SESSION SET NLS_DATE_FORMAT` executado anteriormente.

Os nomes de colunas padrão do Oracle, que não diferenciam maiúsculas de minúsculas, terão índices associativos em letras maiúsculas no array de resultados. Os nomes de colunas que diferenciam maiúsculas de minúsculas terão índices de array usando a mesma capitalização da coluna. Use var_dump() no array de resultados para verificar a capitalização apropriada a ser usada para cada consulta.

O nome da tabela não está incluído no índice do array. Se a consulta contiver duas colunas diferentes com o mesmo nome, use `OCI_NUM` ou adicione um apelido de coluna à consulta para garantir a exclusividade do nome, veja o exemplo nº 7. Caso contrário, apenas uma coluna será retornada via PHP.

### Exemplos

Exemplo #1 oci_fetch_array() com `OCI_BOTH`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT department_id, department_name FROM departments');
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_BOTH)) != false) {
        // Usa os nomes das colunas em letras maiúsculas para os índices do array associativo
        echo $row[0] . " e " . $row['DEPARTMENT_ID']   . " são a mesma coisa<br>\n";
        echo $row[1] . " e " . $row['DEPARTMENT_NAME'] . " são a mesma coisa<br>\n";
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #2 oci_fetch_array() com `OCI_NUM`

    <?php

    /*
      Antes de executar, crie a tabela:
          CREATE TABLE mytab (id NUMBER, description CLOB);
          INSERT INTO mytab (id, description) values (1, 'Uma string muito longa');
          COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, description FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_NUM)) != false) {
        echo $row[0] . "<br>\n";
        echo $row[1]->read(10) . "<br>\n"; // isso produzirá os primeiros 10 bytes de DESCRIPTION
    }

    // O resultado é:
    //    1
    //    Uma string

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #3 oci_fetch_array() com `OCI_ASSOC`

    <?php

    /*
      Antes de executar, crie a tabela:
          CREATE TABLE mytab (id NUMBER, description CLOB);
          INSERT INTO mytab (id, description) values (1, 'Uma string muito longa');
          COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, description FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_ASSOC)) != false) {
        echo $row['ID'] . "<br>\n";
        echo $row['DESCRIPTION']->read(10) . "<br>\n"; // isso produzirá os primeiros 10 bytes de DESCRIPTION
    }

    // O resultado será:
    //    1
    //    Uma string

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #4 oci_fetch_array() com `OCI_RETURN_NULLS`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT 1, null FROM dual');
    oci_execute($stid);
    while (($row = oci_fetch_array ($stid, OCI_ASSOC)) != false) { // Ignora NULLs
        var_dump($row);
    }

    /*
    O código acima exibe:
      array(1) {
        [1]=>
        string(1) "1"
      }
    */

    $stid = oci_parse($conn, 'SELECT 1, null FROM dual');
    oci_execute($stid);
    while (($row = oci_fetch_array ($stid, OCI_ASSOC+OCI_RETURN_NULLS)) != false) { // Busca NULLs
        var_dump($row);
    }

    /*
    O código acima exibe:
      array(2) {
        [1]=>
        string(1) "1"
        ["NULL"]=>
        NULL
      }
    */

    ?>

Exemplo #5 oci_fetch_array() com `OCI_RETURN_LOBS`

    <?php

    /*
      Antes de executar, crie a tabela:
          CREATE TABLE mytab (id NUMBER, description CLOB);
          INSERT INTO mytab (id, description) values (1, 'Uma string muito longa');
          COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, description FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_LOBS)) != false) {
        echo $row['ID'] . "<br>\n";
        echo $row['DESCRIPTION'] . "<br>\n"; // contém todo o campo DESCRIPTION
        // Em um laço, liberar a variável grande antes da segunda busca reduz o pico de uso de memória do PHP
        unset($row);
    }

    // O resultado será:
    //    1
    //    Uma string muito longa

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #6 oci_fetch_array() com nomes de colunas sensíveis a maiúsculas/minúsculas

    <?php

    /*
       Antes de executar, crie a tabela:
          CREATE TABLE mytab ("Name" VARCHAR2(20), city VARCHAR2(20));
          INSERT INTO mytab ("Name", city) values ('Chris', 'Melbourne');
          COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'select * from mytab');
    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS);

    // Como 'Name' foi criada como uma coluna que diferencia maiúsculas de minúsculas, a mesma
    // capitalização é usada para o índice do array. Entretanto, 'CITY' em maiúsculas precisa ser
    // usada para o índice da coluna que não diferencia maiúsculas de minúsculas
    print $row['Name'] . "<br>\n";   //  exibe Chris
    print $row['CITY'] . "<br>\n";   //  exibe Melbourne

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #7 oci_fetch_array() com colunas que possuem nomes duplicados

    <?php

    /*
      Antes de executar, crie as tabelas:
          CREATE TABLE mycity (id NUMBER, name VARCHAR2(20));
          INSERT INTO mycity (id, name) values (1, 'Melbourne');
          CREATE TABLE mycountry (id NUMBER, name VARCHAR2(20));
          INSERT INTO mycountry (id, name) values (1, 'Australia');
          COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'SELECT mycity.name, mycountry.name
            FROM mycity, mycountry
            WHERE mycity.id = mycountry.id';
    $stid = oci_parse($conn, $sql);
    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC);
    var_dump($row);

    // A saída contém apenas uma entrada "NAME":
    //    array(1) {
    //      ["NAME"]=>
    //      string(9) "Australia"
    //    }

    // Para consultar um nome de coluna repetido, use um apelido de coluna SQL como "AS ctnm":
    $sql = 'SELECT mycity.name AS ctnm, mycountry.name
            FROM mycity, mycountry
            WHERE mycity.id = mycountry.id';
    $stid = oci_parse($conn, $sql);
    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC);
    var_dump($row);

    // A saída agora contém ambas as colunas selecionadas:
    //    array(2) {
    //      ["CTNM"]=>
    //      string(9) "Melbourne"
    //      ["NAME"]=>
    //      string(9) "Australia"
    //    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #8 oci_fetch_array() com colunas `DATE`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Defina o formato de data para esta conexão.
    // Por motivos de desempenho, considere alterar o formato
    // em um gatilho ou com variáveis ​​de ambiente
    $stid = oci_parse($conn, "ALTER SESSION SET NLS_DATE_FORMAT = 'YYYY-MM-DD'");
    oci_execute($stid);

    $stid = oci_parse($conn, 'SELECT hire_date FROM employees WHERE employee_id = 188');
    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC);
    echo $row['HIRE_DATE'] . "<br>\n";  // exibe 1997-06-14

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #9 oci_fetch_array() com `REF CURSOR`

    <?php
    /*
      Crie o procedimento armazenado PL/SQL como:

      CREATE OR REPLACE PROCEDURE myproc(p1 OUT SYS_REFCURSOR) AS
      BEGIN
        OPEN p1 FOR SELECT * FROM all_objects WHERE ROWNUM < 5000;
      END;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'BEGIN myproc(:rc); END;');
    $refcur = oci_new_cursor($conn);
    oci_bind_by_name($stid, ':rc', $refcur, -1, OCI_B_CURSOR);
    oci_execute($stid);

    // Executa o REF CURSOR retornado e busca nele como um identificador de instrução
    oci_execute($refcur);
    echo "<table border='1'>\n";
    while (($row = oci_fetch_array($refcur, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($refcur);
    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #10 Paginação com oci_fetch_array() usando uma consulta tipo `LIMIT`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Encontra a versão do banco de dados
    preg_match('/Release ([0-9]+)\./', oci_server_version($conn), $matches);
    $oracleversion = $matches[1];

    // Esta é a consulta a ser "paginada"
    $sql = 'SELECT city, postal_code FROM locations ORDER BY city';

    if ($oracleversion >= 12) {
        // Utilize a sintaxe Oracle 12c OFFSET / FETCH NEXT
        $sql = $sql . ' OFFSET :offset ROWS FETCH NEXT :numrows ROWS ONLY';
    } else {
        // Versões mais antigas do Oracle precisam de uma consulta aninhada selecionando um subconjunto
        // de $sql. Ou, se a instrução SQL for conhecida no momento do desenvolvimento,
        // considere usar uma função row_number() em vez desta
        // solução aninhada. Em ambientes de produção, tome cuidado para
        // evitar problemas de injeção de SQL com concatenação.
        $sql = "SELECT * FROM (SELECT a.*, ROWNUM AS my_rnum
                               FROM ($sql) a
                               WHERE ROWNUM <= :offset + :numrows)
                WHERE my_rnum > :offset";
    }

    $offset  = 0;  // pula esta quantidade de linhas
    $numrows = 5;  // retorna 5 linhas
    $stid = oci_parse($conn, $sql);
    oci_bind_by_name($stid, ':numrows', $numrows);
    oci_bind_by_name($stid, ':offset', $offset);
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_ASSOC + OCI_RETURN_NULLS)) != false) {
        echo $row['CITY'] . " " . $row['POSTAL_CODE'] . "<br>\n";
    }

    // O resultado será:
    //    Beijing 190518
    //    Bern 3095
    //    Bombay 490231
    //    Geneva 1730
    //    Hiroshima 6823

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #11 oci_fetch_array() com conjuntos de resultados implícitos do Oracle Database

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Requer OCI8 2.0 (ou posterior) e Oracle Database 12c (ou posterior)
    // Veja também oci_get_implicit_resultset()
    $sql = 'DECLARE
               c1 SYS_REFCURSOR;
            BEGIN
               OPEN c1 FOR SELECT city, postal_code FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
               OPEN c1 FOR SELECT country_id FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
            END;';

    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    // Nota: oci_fetch_all e oci_fetch() não podem ser usados ​​desta maneira
    echo "<table>\n";
    while (($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "  <td>".($item!==null?htmlentities($item, ENT_QUOTES|ENT_SUBSTITUTE):"&nbsp;")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    // O resultado será:
    //    Beijing 190518
    //    Bern    3095
    //    Bombay  490231
    //    CN
    //    CH
    //    IN

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Notas

> Nota:

> Os índices de array associativo precisam estar em letras maiúsculas para colunas padrão do Oracle que foram criadas com nomes que não diferenciam maiúsculas de minúsculas.

> Nota: Para consultas que retornam um grande número de linhas, o desempenho pode ser melhorado significativamente aumentando oci8.default_prefetch ou usando oci_set_prefetch().

> Nota:

> A função oci_fetch_array() é insignificantemente mais lenta que oci_fetch_assoc() ou oci_fetch_row(), mas é mais flexível.

### Veja Também

- oci_fetch() - Busca a próxima linha de uma consulta em buffers internos
- oci_fetch_all() - Busca várias linhas de uma consulta em um array bidimensional
- oci_fetch_assoc() - Retorna a próxima linha de uma consulta como um array associativo
- oci_fetch_object() - Retorna a próxima linha de uma consulta como um objeto
- oci_fetch_row() - Retorna a próxima linha de uma consulta como um array numérico
- oci_set_prefetch() - Define o número de linhas a serem pré-buscadas pelas consultas

# oci_fetch_assoc

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_assoc — Retorna a próxima linha de uma consulta como um array associativo

### Descrição

function oci_fetch_assoc(resource `$statement`): array|false

Retorna um array associativo contendo a próxima linha do conjunto de resultados de uma consulta. Cada entrada do array corresponde a uma coluna da linha. Esta função é normalmente chamada em um laço até retornar `false`, indicando que não existem mais linhas.

Chamar oci_fetch_assoc() é idêntico a chamar oci_fetch_array() com `OCI_ASSOC` + `OCI_RETURN_NULLS`.

### Parâmetros

`statement`
  Um identificador de declaração OCI8 válida criada por oci_parse() e executada por oci_execute() ou um identificador de declaração `REF CURSOR`.

### Valor Retornado

Retorna um array associativo. Se não houver mais linhas na `statement`, então `false` é retornado.

### Exemplos

Exemplo #1 Exemplo de oci_fetch_assoc()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT department_id, department_name FROM departments');
    oci_execute($stid);

    while (($row = oci_fetch_assoc($stid)) != false) {
        echo $row['DEPARTMENT_ID'] . " " . $row['DEPARTMENT_NAME'] . "<br>\n";
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Notas

> Nota:

> Veja oci_fetch_array() para mais exemplos de busca de linhas.

### Veja Também

- oci_fetch() - Busca a próxima linha de uma consulta em buffers internos
- oci_fetch_all() - Busca várias linhas de uma consulta em um array bidimensional
- oci_fetch_array() - Retorna a próxima linha de uma consulta como um array associativo ou numérico
- oci_fetch_object() - Retorna a próxima linha de uma consulta como um objeto
- oci_fetch_row() - Retorna a próxima linha de uma consulta como um array numérico

# oci_fetch_object

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_object — Retorna a próxima linha de uma consulta como um objeto

### Descrição

function oci_fetch_object(resource `$statement`, int `$mode` = OCI_ASSOC | OCI_RETURN_NULLS): stdClass|false

Retorna um objeto contendo a próxima linha do conjunto de resultados de uma consulta. Cada atributo do objeto corresponde a uma coluna da linha. Esta função normalmente é chamada em um laço até retornar `false`, indicando que não existem mais linhas.

Para obter detalhes sobre o mapeamento dos tipos de dados realizado pela extensão OCI8, consulte os tipos de dados suportados pelo driver.

### Parâmetros

`statement`
  Um identificador de declaração OCI8 válida criada por oci_parse() e executada por oci_execute() ou um identificador de declaração `REF CURSOR`.

### Valor Retornado

Retorna um objeto. Cada atributo do objeto corresponde a uma coluna da linha. Se não houver mais linhas em `statement`, então `false` será retornado.

Quaisquer colunas `LOB` são retornadas como descritores LOB.

As colunas `DATE` são retornadas como strings no formato de data atual. O formato padrão pode ser alterado com variáveis ​​de ambiente Oracle, como `NLS_LANG` ou por um comando `ALTER SESSION SET NLS_DATE_FORMAT` executado anteriormente.

Os nomes de colunas padrão do Oracle, que não diferenciam maiúsculas de minúsculas, terão nomes de atributos em letras maiúsculas. Os nomes de colunas que diferenciam maiúsculas de minúsculas terão nomes de atributos usando a mesma capitalização de coluna. Use var_dump() no objeto de resultado para verificar a capitalização apropriada para acesso ao atributo.

Os valores dos atributos serão `null` para quaisquer campos de dados `NULL`.

### Exemplos

Exemplo #1 Exemplo de oci_fetch_object()

    <?php

    /*
      Antes de executar, crie a tabela:
        CREATE TABLE mytab (id NUMBER, description VARCHAR2(30));
        INSERT INTO mytab (id, description) values (1, 'Fish and Chips');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, description FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_object($stid)) != false) {
        // Use nomes de atributos em letras maiúsculas para cada coluna padrão do Oracle
        echo $row->ID . "<br>\n";
        echo $row->DESCRIPTION . "<br>\n";
    }

    // O resultado é:
    //    1
    //    Fish and Chips

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #2 oci_fetch_object() com nomes de colunas que diferenciam maiúsculas de minúsculas

    <?php

    /*
      Antes de executar, crie a tabela com um nome de coluna que diferencie maiúsculas de minúsculas:
        CREATE TABLE mytab (id NUMBER, "MyDescription" VARCHAR2(30));
        INSERT INTO mytab (id, "MyDescription") values (1, 'Iced Coffee');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, "MyDescription" FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_object($stid)) != false) {
        // Use nomes de atributos em letras maiúsculas para cada coluna padrão do Oracle
        echo $row->ID . "<br>\n";
        // Use a capitalização exata para o nome da coluna que diferencia maiúsculas de minúsculas
        echo $row->MyDescription . "<br>\n";
    }

    // Resultado:
    //    1
    //    Iced Coffee

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #3 oci_fetch_object() com LOBs

    <?php

    /*
      Antes de executar, crie a tabela:
        CREATE TABLE mytab (id NUMBER, description CLOB);
        INSERT INTO mytab (id, description) values (1, 'A very long string');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, description FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_object($stid)) != false) {
        echo $row->ID . "<br>\n";
        // O código a seguir produzirá os primeiros 11 bytes de DESCRIPTION
        echo $row->DESCRIPTION->read(11) . "<br>\n";
    }

    // O resultado é:
    //    1
    //    A very long

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Veja Também

- oci_fetch() - Busca a próxima linha de uma consulta em buffers internos
- oci_fetch_all() - Busca várias linhas de uma consulta em um array bidimensional
- oci_fetch_assoc() - Retorna a próxima linha de uma consulta como um array associativo
- oci_fetch_array() - Retorna a próxima linha de uma consulta como um array associativo ou numérico
- oci_fetch_row() - Retorna a próxima linha de uma consulta como um array numérico

# oci_fetch_row

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_row — Retorna a próxima linha de uma consulta como um array numérico

### Descrição

function oci_fetch_row(resource `$statement`): array|false

Retorna um array indexado numericamente contendo a próxima linha do conjunto de resultados de uma consulta. Cada entrada do array corresponde a uma coluna da linha. Esta função é normalmente chamada em um laço até retornar `false`, indicando que não existem mais linhas.

Chamar oci_fetch_row() é idêntico a chamar oci_fetch_array() com `OCI_NUM` + `OCI_RETURN_NULLS`.

### Parâmetros

`statement`
  Um identificador de declaração OCI8 válida criada por oci_parse() e executada por oci_execute() ou um identificador de declaração `REF CURSOR`.

### Valor Retornado

Retorna um array indexado numericamente. Se não houver mais linhas em `statement`, então `false` é retornado.

### Exemplos

Exemplo #1 Exemplo de oci_fetch_row()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT department_id, department_name FROM departments');
    oci_execute($stid);

    while (($row = oci_fetch_row($stid)) != false) {
        echo $row[0] . " " . $row[1] . "<br>\n";
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Notas

> Nota:

> Veja oci_fetch_array() para mais exemplos de busca de linhas.

### Veja Também

- oci_fetch() - Busca a próxima linha de uma consulta em buffers internos
- oci_fetch_all() - Busca várias linhas de uma consulta em um array bidimensional
- oci_fetch_array() - Retorna a próxima linha de uma consulta como um array associativo ou numérico
- oci_fetch_assoc() - Retorna a próxima linha de uma consulta como um array associativo
- oci_fetch_object() - Retorna a próxima linha de uma consulta como um objeto

# oci_field_is_null

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_is_null — Verifica se um campo na linha atualmente buscada é `null`

### Descrição

function oci_field_is_null(resource `$statement`, string|int `$column`): bool

Verifica se a `column` fornecida na linha atual de `statement` é `null`.

### Parâmetros

`statement`

  Um identificador de instrução OCI válido.

`column`

  Pode ser o índice do campo (baseado em 1) ou o nome.

### Valor Retornado

Retorna `true` se `column` for `null`, `false` caso contrário.

### Exemplos

Exemplo #1 Exemplo de oci_field_name()

    <?php

    // Crie a tabela com:
    //   CREATE TABLE mytab (c1 NUMBER);
    //   INSERT INTO mytab VALUES (1);
    //   INSERT INTO mytab VALUES (NULL);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_RETURN_NULLS)) != false) {
        $ncols = oci_num_fields($stid);
        for ($col = 1; $col <= $ncols; $col++) {
            var_dump(oci_field_is_null($stid, $col));
        }
    }

    // Resultado:
    //    bool(false)
    //    bool(true)

    oci_free_statement($stid);
    oci_close($conn);

    ?>

# oci_field_name

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_name — Retorna o nome de um campo da instrução

### Descrição

function oci_field_name(resource `$statement`, string|int `$column`): string|false

Retorna o nome da coluna informada em `column`.

### Parâmetros

`statement`

  Um identificador de instrução OCI válido.

`column`

  Pode ser o índice do campo (baseado em 1) ou o nome.

### Valor Retornado

Retorna o nome como uma string, ou `false` em caso de falha

### Exemplos

Exemplo #1 Exemplo de oci_field_name()

    <?php

    // Crie a tabela com:
    //   CREATE TABLE mytab (number_col NUMBER, varchar2_col varchar2(1),
    //                       clob_col CLOB, date_col DATE);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // Use OCI_DESCRIBE_ONLY se não estiver buscando linhas

    echo "<table border=\"1\">\n";
    echo "<tr>";
    echo "<th>Nome</th>";
    echo "<th>Tipo</th>";
    echo "<th>Comprimento</th>";
    echo "</tr>\n";

    $ncols = oci_num_fields($stid);

    for ($i = 1; $i <= $ncols; $i++) {
        $column_name  = oci_field_name($stid, $i);
        $column_type  = oci_field_type($stid, $i);

        echo "<tr>";
        echo "<td>$column_name</td>";
        echo "<td>$column_type</td>";
        echo "</tr>\n";
    }

    echo "</table>\n";

    // Resultado:
    //    Nome           Tipo
    //    NUMBER_COL    NUMBER
    //    VARCHAR2_COL  VARCHAR2
    //    CLOB_COL      CLOB
    //    DATE_COL      DATE

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Veja Também

- oci_num_fields() - Retorna o número de colunas de resultados em uma instrução
- oci_field_type() - Retorna o nome do tipo de dados de um campo
- oci_field_size() - Retorna o tamanho do campo

# oci_field_precision

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_precision — Informa a precisão de um campo

### Descrição

function oci_field_precision(resource `$statement`, string|int `$column`): int|false

Retorna a precisão de `column`.

Para colunas FLOAT, a precisão é diferente de zero e a escala é -127. Se a precisão for 0, a coluna é NUMBER. Caso contrário, é NUMBER(precisão, escala).

### Parâmetros

`statement`

  Um identificador de instrução OCI válido.

`column`

  Pode ser o índice do campo (baseado em 1) ou o nome.

### Valor Retornado

Retorna a precisão como um inteiro, ou `false` em caso de falha

### Exemplos

Exemplo #1 Exemplo de oci_field_precision()

    <?php

    // Crie a tabela com:
    //   CREATE TABLE mytab (c1 NUMBER, c2 FLOAT, c3 NUMBER(4), c4 NUMBER(5,3));

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // Use OCI_DESCRIBE_ONLY se não estiver buscando linhas

    $ncols = oci_num_fields($stid);
    for ($i = 1; $i <= $ncols; $i++) {
        echo oci_field_name($stid, $i) . " "
            . oci_field_precision($stid, $i) . " "
            . oci_field_scale($stid, $i) . "<br>\n";
    }

    // Resultado:
    //   C1    0 -127
    //   C2  126 -127
    //   C3    4    0
    //   C4    5    3

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Veja Também

- oci_field_scale() - Informa a escala do campo
- oci_field_type() - Retorna o nome do tipo de dados de um campo

# oci_field_scale

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_scale — Informa a escala do campo

### Descrição

function oci_field_scale(resource `$statement`, string|int `$column`): int|false

Retorna a escala da coluna com índice `column`.

Para colunas FLOAT, a precisão é diferente de zero e a escala é -127. Se a precisão for 0, a coluna é NUMBER. Caso contrário, é NUMBER(precisão, escala).

### Parâmetros

`statement`

  Um identificador de instrução OCI válido.

`column`

  Pode ser o índice do campo (baseado em 1) ou o nome.

### Valor Retornado

Retorna a escala como um inteiro, ou `false` em caso de falha

### Exemplos

Exemplo #1 Exemplo de oci_field_scale()

    <?php

    // Crie a tabela com:
    //   CREATE TABLE mytab (c1 NUMBER, c2 FLOAT, c3 NUMBER(4), c4 NUMBER(5,3));

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // Use OCI_DESCRIBE_ONLY se não estiver buscando linhas

    $ncols = oci_num_fields($stid);
    for ($i = 1; $i <= $ncols; $i++) {
        echo oci_field_name($stid, $i) . " "
            . oci_field_precision($stid, $i) . " "
            . oci_field_scale($stid, $i) . "<br>\n";
    }

    // Resultado:
    //   C1    0 -127
    //   C2  126 -127
    //   C3    4    0
    //   C4    5    3

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Veja Também

- oci_field_precision() - Informa a precisão de um campo
- oci_field_type() - Retorna o nome do tipo de dados de um campo

# oci_field_size

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_size — Retorna o tamanho do campo

### Descrição

function oci_field_size(resource `$statement`, string|int `$column`): int|false

Retorna o tamanho da coluna informada em `column`.

### Parâmetros

`statement`

  Um identificador de instrução OCI válido.

`column`

  Pode ser o índice do campo (baseado em 1) ou o nome.

### Valor Retornado

Retorna o tamanho de `column` em bytes, ou `false` em caso de falha

### Exemplos

Exemplo #1 Exemplo de oci_field_size()

    <?php

    // Crie a tabela com:
    //   CREATE TABLE mytab (number_col NUMBER, varchar2_col varchar2(1),
    //                       clob_col CLOB, date_col DATE);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // Use OCI_DESCRIBE_ONLY se não estiver buscando linhas

    echo "<table border=\"1\">\n";
    echo "<tr>";
    echo "<th>Nome</th>";
    echo "<th>Tipo</th>";
    echo "<th>Comprimento</th>";
    echo "</tr>\n";

    $ncols = oci_num_fields($stid);

    for ($i = 1; $i <= $ncols; $i++) {
        $column_name  = oci_field_name($stid, $i);
        $column_type  = oci_field_type($stid, $i);
        $column_size  = oci_field_size($stid, $i);

        echo "<tr>";
        echo "<td>$column_name</td>";
        echo "<td>$column_type</td>";
        echo "<td>$column_size</td>";
        echo "</tr>\n";
    }

    echo "</table>\n";

    // Resultado:
    //    Nome           Tipo       Comprimento
    //    NUMBER_COL    NUMBER        22
    //    VARCHAR2_COL  VARCHAR2       1
    //    CLOB_COL      CLOB        4000
    //    DATE_COL      DATE           7

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Veja Também

- oci_num_fields() - Retorna o número de colunas de resultados em uma instrução
- oci_field_name() - Retorna o nome de um campo da instrução

# oci_field_type

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_type — Retorna o nome do tipo de dados de um campo

### Descrição

function oci_field_type(resource `$statement`, string|int `$column`): string|int|false

Retorna o nome do tipo de dados de um campo.

### Parâmetros

`statement`

  Um identificador de instrução OCI válido.

`column`

  Pode ser o índice do campo (baseado em 1) ou o nome.

### Valor Retornado

Retorna o tipo de dados do campo como string ou int, ou `false` em caso de falha

### Exemplos

Exemplo #1 Exemplo de oci_field_type()

    <?php

    // Crie a tabela com:
    //   CREATE TABLE mytab (number_col NUMBER, varchar2_col varchar2(1),
    //                       clob_col CLOB, date_col DATE);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // Use OCI_DESCRIBE_ONLY se não estiver buscando linhas

    echo "<table border=\"1\">\n";
    echo "<tr>";
    echo "<th>Nome</th>";
    echo "<th>Tipo</th>";
    echo "<th>Comprimento</th>";
    echo "</tr>\n";

    $ncols = oci_num_fields($stid);

    for ($i = 1; $i <= $ncols; $i++) {
        $column_name  = oci_field_name($stid, $i);
        $column_type  = oci_field_type($stid, $i);
        $column_size  = oci_field_size($stid, $i);

        echo "<tr>";
        echo "<td>$column_name</td>";
        echo "<td>$column_type</td>";
        echo "<td>$column_size</td>";
        echo "</tr>\n";
    }

    echo "</table>\n";

    // Resultado:
    //    Nome           Tipo       Comprimento
    //    NUMBER_COL    NUMBER        22
    //    VARCHAR2_COL  VARCHAR2       1
    //    CLOB_COL      CLOB        4000
    //    DATE_COL      DATE           7

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Veja Também

- oci_num_fields() - Retorna o número de colunas de resultados em uma instrução
- oci_field_name() - Retorna o nome de um campo da instrução
- oci_field_size() - Retorna o tamanho do campo

# oci_field_type_raw

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_type_raw — Informa o tipo bruto de dados do Oracle de um campo

### Descrição

function oci_field_type_raw(resource `$statement`, string|int `$column`): int|false

Retorna o tipo bruto de dados "SQLT" do Oracle da coluna informada em `column`.

Se for necessário obter o nome do tipo de um campo, use oci_field_type().

### Parâmetros

`statement`

  Um identificador de instrução OCI válido.

`column`

  Pode ser o índice do campo (baseado em 1) ou o nome.

### Valor Retornado

Retorna o tipo de dados brutos do Oracle como um número, ou `false` em caso de falha

### Exemplos

Exemplo #1 Exemplo de oci_field_type_raw()

    <?php

    // Crie a tabela com:
    //   CREATE TABLE mytab (number_col NUMBER, varchar2_col varchar2(1), clob_col CLOB, date_col DATE);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'select * from mytab');
    oci_execute($stid, OCI_DESCRIBE_ONLY);  // Use OCI_DESCRIBE_ONLY se não estiver buscando linhas
    $n = oci_num_fields($stid);
    for ($i = 1; $i <= $n; ++$i) {
        echo oci_field_name($stid, $i) . " é do tipo bruto: " . oci_field_type_raw($stid, $i) . "<br>\n";
    }

    // Resultado:
    //    NUMBER_COL é do tipo bruto: 2
    //    VARCHAR2_COL é do tipo bruto: 1
    //    CLOB_COL é do tipo bruto: 112
    //    DATE_COL é do tipo bruto: 12

    oci_free_statement($stid);
    oci_close($conn);

    ?>

# oci_free_descriptor

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_free_descriptor — Libera um descritor

### Descrição

function oci_free_descriptor(OCILob `$lob`): bool

Libera um descritor alocado por oci_new_descriptor().

### Parâmetros

`lob`

  Descritor alocado por oci_new_descriptor().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Notas

> Nota:

> Esta função é comumente usada como um método OCILOB::free.

### Veja Também

- OCILOB::free

# oci_free_statement

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_free_statement — Libera todos os recursos associados à instrução ou cursor

### Descrição

function oci_free_statement(resource `$statement`): bool

Libera recursos associados ao cursor ou à instrução do Oracle, que foram recebidos como resultado de oci_parse() ou obtidos do Oracle.

### Parâmetros

`statement`

  Um identificador de instrução OCI válido.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# oci_get_implicit_resultset

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL OCI8 >= 2.0.0)

oci_get_implicit_resultset — Retorna o próximo recurso de instrução filho de um recurso de instrução pai que possui conjuntos de resultados implícitos do Oracle Database

### Descrição

function oci_get_implicit_resultset(resource `$statement`): resource|false

Usado para buscar conjuntos consecutivos de resultados de consulta após a execução de um bloco Oracle PL/SQL armazenado ou anônimo, onde esse bloco retorna resultados de consulta com a função PL/SQL DBMS_SQL.RETURN_RESULT do Oracle Database 12 (ou posterior). Isso permite que blocos PL/SQL retornem facilmente resultados de consulta.

A instrução filha pode ser usada com qualquer uma das funções de busca do OCI8: oci_fetch(), oci_fetch_all(), oci_fetch_array(), oci_fetch_object(), oci_fetch_assoc() ou oci_fetch_row().

As instruções filhas herdam o valor de pré-busca da instrução pai, ou podem ser definidas explicitamente com oci_set_prefetch().

### Parâmetros

`statement`

  Um identificador de instrução OCI8 válido criado por oci_parse() e executado por oci_execute(). O identificador da instrução pode ou não estar associado a uma instrução SQL que retorna Conjuntos de Resultados Implícitos.

### Valor Retornado

Retorna um identificador de instrução para a próxima instrução filha disponível em `statement`. Retorna `false` quando as instruções filhas não existem ou todas as instruções filhas foram retornadas por chamadas anteriores para oci_get_implicit_resultset().

### Exemplos

Exemplo #1 Buscando conjuntos de resultados implícitos em um laço

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'DECLARE
                c1 SYS_REFCURSOR;
            BEGIN
               OPEN c1 FOR SELECT city, postal_code FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
               OPEN c1 FOR SELECT country_id FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
            END;';

    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    while (($stid_c = oci_get_implicit_resultset($stid))) {
        echo "<h2>Novo conjunto de resultados implícitos:</h2>\n";
        echo "<table>\n";
        while (($row = oci_fetch_array($stid_c, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
            echo "<tr>\n";
            foreach ($row as $item) {
                echo "  <td>".($item!==null?htmlentities($item, ENT_QUOTES|ENT_SUBSTITUTE):"&nbsp;")."</td>\n";
            }
            echo "</tr>\n";
        }
        echo "</table>\n";
    }

    // Resultado:
    //    Novo conjunto de resultados implícitos:
    //     Beijing 190518
    //     Bern    3095
    //     Bombay  490231
    //    Novo conjunto de resultados implícitos:
    //     CN
    //     CH
    //     IN

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #2 Obtendo identificadores de instruções filhas individualmente

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'DECLARE
                c1 SYS_REFCURSOR;
            BEGIN
               OPEN c1 FOR SELECT city, postal_code FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
               OPEN c1 FOR SELECT country_id FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
            END;';

    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    $stid_1 = oci_get_implicit_resultset($stid);
    $stid_2 = oci_get_implicit_resultset($stid);

    $row = oci_fetch_array($stid_1, OCI_ASSOC+OCI_RETURN_NULLS);
    var_dump($row);
    $row = oci_fetch_array($stid_2, OCI_ASSOC+OCI_RETURN_NULLS);
    var_dump($row);
    $row = oci_fetch_array($stid_1, OCI_ASSOC+OCI_RETURN_NULLS);
    var_dump($row);
    $row = oci_fetch_array($stid_2, OCI_ASSOC+OCI_RETURN_NULLS);
    var_dump($row);

    // Resultado:
    //    array(2) {
    //      ["CITY"]=>
    //      string(7) "Beijing"
    //      ["POSTAL_CODE"]=>
    //      string(6) "190518"
    //    }
    //    array(1) {
    //      ["COUNTRY_ID"]=>
    //      string(2) "CN"
    //    }
    //    array(2) {
    //      ["CITY"]=>
    //      string(4) "Bern"
    //      ["POSTAL_CODE"]=>
    //      string(4) "3095"
    //    }
    //    array(1) {
    //      ["COUNTRY_ID"]=>
    //      string(2) "CH"
    //    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #3 Definindo explicitamente a contagem de pré-busca

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'DECLARE
                c1 SYS_REFCURSOR;
            BEGIN
               OPEN c1 FOR SELECT city, postal_code FROM locations ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
            END;';

    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    $stid_c = oci_get_implicit_resultset($stid);
    oci_set_prefetch($stid_c, 200);   // Defina a pré-busca antes de buscar na instrução filho
    echo "<table>\n";
    while (($row = oci_fetch_array($stid_c, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "  <td>".($item!==null?htmlentities($item, ENT_QUOTES|ENT_SUBSTITUTE):"&nbsp;")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #4 Exemplo de conjunto de resultados implícitos sem usar oci_get_implicit_resultset()

Todos os resultados de todas as consultas são retornados consecutivamente.

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'DECLARE
                c1 SYS_REFCURSOR;
            BEGIN
               OPEN c1 FOR SELECT city, postal_code FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
               OPEN c1 FOR SELECT country_id FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
            END;';

    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    // Nota: oci_fetch_all e oci_fetch() não podem ser usados ​​desta maneira
    echo "<table>\n";
    while (($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "  <td>".($item!==null?htmlentities($item, ENT_QUOTES|ENT_SUBSTITUTE):"&nbsp;")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    // Resultado:
    //    Beijing 190518
    //    Bern 3095
    //    Bombay 490231
    //    CN
    //    CH
    //    IN

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Notas

> Nota: Para consultas que retornam um grande número de linhas, o desempenho pode ser melhorado significativamente aumentando oci8.default_prefetch ou usando oci_set_prefetch().

# oci_lob_copy

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_lob_copy — Copia objeto grande

### Descrição

function oci_lob_copy(OCILob `$to`, OCILob `$from`, ?int `$length` = `null`): bool

Copia um objeto grande ou parte de um objeto grande para outro objeto grande. Os dados antigos do LOB destinatário serão substituídos.

Se for necessário copiar uma parte específica de um LOB para uma posição específica de um LOB, use OCILob::seek() para mover ponteiros internos do LOB.

### Parâmetros

`to`

  O LOB de destino.

`from`

  O LOB copiado.

`length`

  Indica o comprimento dos dados a serem copiados.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | `length` agora é anulável.

### Notas

> Nota:

> A classe OCILob era chamada OCI-Lob antes do PHP 8 e PECL OCI8 3.0.0.

# oci_lob_is_equal

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_lob_is_equal — Compara dois localizadores LOB/FILE para igualdade

### Descrição

function oci_lob_is_equal(OCILob `$lob1`, OCILob `$lob2`): bool

Compara dois localizadores LOB/FILE.

### Parâmetros

`lob1`

  Um identificador LOB.

`lob2`

  Um identificador LOB.

### Valor Retornado

Retorna `true` se esses objetos forem iguais, `false` caso contrário.

### Notas

> Nota:

> A classe OCILob era chamada OCI-Lob antes do PHP 8 e PECL OCI8 3.0.0.

# oci_new_collection

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_collection — Aloca novo objeto de coleção

### Descrição

function oci_new_collection(resource `$connection`, string `$type_name`, ?string `$schema` = `null`): OCICollection|false

Aloca um novo objeto de coleção.

### Parâmetros

`connection`

  Um identificador de conexão Oracle, retornado por oci_connect() ou oci_pconnect().

`type_name`

  Deve ser um tipo nomeado válido (em letras maiúsculas).

`schema`

  Deve apontar para o esquema onde o tipo nomeado foi criado. O nome do usuário atual é usado quando `null` é passado.

### Valor Retornado

Retorna um novo objeto OCICollection ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | `schema` agora é anulável.

### Notas

> Nota:

> A classe OCICollection era chamada de OCI-Collection antes do PHP 8 e do OCI8 3.0.0.

# oci_new_connect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_connect — Conecta-se ao servidor Oracle usando uma conexão exclusiva

### Descrição

function oci_new_connect(
string `$username`,
string `$password`,
?string `$connection_string` = `null`,
string `$encoding` = "",
int `$session_mode` = `OCI_DEFAULT`
): resource|false

Estabelece uma nova conexão com um servidor Oracle e efetua logon.

Ao contrário de oci_connect() e oci_pconnect(), oci_new_connect() não armazena conexões em cache e sempre retornará um identificador de conexão recém-aberto. Isso é útil se sua aplicação precisar de isolamento transacional entre dois conjuntos de consultas.

### Parâmetros

`username`

  O nome de usuário do Oracle.

`password`

  A senha para `username`.

`connection_string`
  Contém a `instância do Oracle` à qual se conectar. Pode ser uma » string Easy Connect ou um Connect Name do arquivo tnsnames.ora ou o nome de uma instância local do Oracle. Se não especificado ou `null`, o PHP usará variáveis de ambiente como `TWO_TASK` (no Linux) ou `LOCAL` (no Windows) e `ORACLE_SID` para determinar a `instância do Oracle` à qual se conectar. Para usar o método de nomenclatura Easy Connect, o PHP precisa ter sido compilado com as bibliotecas Oracle Client 10g ou superiores. A string Easy Connect para o Oracle 10g tem o formato: [//]nome_do_servidor[:porta][/nome_do_servico]. A partir do Oracle 11g a sintaxe é: [//]nome_do_servidor[:porta][/nome_do_servico][:tipo_de_servidor][/nome_da_instancia]. Outras opções foram introduzidas com o Oracle 19c, incluindo as configurações de timeout e keep-alive. Consulte a documentação do Oracle. Os nomes dos serviços podem ser encontrados executando o utilitário Oracle `lsnrctl status` na máquina do servidor de banco de dados. O arquivo tnsnames.ora pode estar no caminho de pesquisa Oracle Net, que inclui /seu/caminho/para/instantclient/network/admin, $ORACLE_HOME/network/admin e /etc. Como alternativa, defina `TNS_ADMIN` para que $TNS_ADMIN/tnsnames.ora possa ser lido. Certifique-se de que o servidor web tem acesso de leitura ao arquivo.
`encoding`
  Determina o conjunto de caracteres usado pelas bibliotecas Oracle Client. O conjunto de caracteres não precisa corresponder ao conjunto de caracteres usado pelo banco de dados. Se não corresponderem, o Oracle fará o possível para converter os dados de e para o conjunto de caracteres do banco de dados. Dependendo dos conjuntos de caracteres, isso pode não fornecer resultados utilizáveis. A conversão também adiciona alguma sobrecarga de tempo. Se não for especificado, as bibliotecas Oracle Client determinam um conjunto de caracteres a partir da variável de ambiente `NLS_LANG`. Passar este parâmetro pode reduzir o tempo necessário para conectar.
`session_mode`
  Este parâmetro está disponível a partir do PHP 5 (PECL OCI8 1.1) e aceita os seguintes valores: `OCI_DEFAULT`, `OCI_SYSOPER` e `OCI_SYSDBA`. Se `OCI_SYSOPER` ou `OCI_SYSDBA` forem especificadas, esta função tentará estabelecer uma conexão privilegiada usando credenciais externas. Conexões privilegiadas estão desabilitadas por padrão. Para habilitá-las é preciso configurar oci8.privileged_connect para `On`. O PHP 5.3 (PECL OCI8 1.3.4) introduziu o valor de modo `OCI_CRED_EXT`. Ele informa ao Oracle para usar autenticação External ou OS, que deve ser configurada no banco de dados. A flag `OCI_CRED_EXT` só pode ser usada com o usuário "/" e uma senha vazia. oci8.privileged_connect pode ser `On` ou `Off`. `OCI_CRED_EXT` pode ser combinado com os modos `OCI_SYSOPER` ou `OCI_SYSDBA`. `OCI_CRED_EXT` não é suportado no Windows por razões de segurança.

### Valor Retornado

Retorna um identificador de conexão ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | `connection_string` agora é anulável.

### Exemplos

A seguir demonstramos como conexões podem ser separaradas.

Exemplo #1 Exemplo de oci_new_connect()

    <?php

    // crie a tabela mytab (mycol number);

    function query($name, $c)
    {
        echo "Consultando $name\n";
        $s = oci_parse($c, "select * from mytab");
        oci_execute($s, OCI_NO_AUTO_COMMIT);
        $row = oci_fetch_array($s, OCI_ASSOC);
        if (!$row) {
            echo "Nenhuma linha\n";
        } else {
            do {
                foreach ($row as $item)
                    echo $item . " ";
                echo "\n";
            } while (($row = oci_fetch_array($s, OCI_ASSOC)) != false);
        }
    }

    $c1 = oci_connect("hr", "welcome", "localhost/orcl");
    $c2 = oci_new_connect("hr", "welcome", "localhost/orcl");

    $s = oci_parse($c1, "insert into mytab values(1234)");
    oci_execute($s, OCI_NO_AUTO_COMMIT);

    query("conexão básica", $c1);
    query("conexão nova", $c2);
    oci_commit($c1);
    query("conexão nova após confirmação", $c2);

    // Resultado:
    //   Consultando conexão básica
    //   1234
    //   Consultando conexão nova
    //   "Nenhuma linha
    //   Consultando conexão nova após confirmação
    //   1234

    ?>

Consulte oci_connect() para mais exemplos de uso dos parâmetros.

### Veja Também

- oci_connect() - Conecta-se a um banco de dados Oracle
- oci_pconnect() - Conecta-se a um banco de dados Oracle usando uma conexão persistente

# oci_new_cursor

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_cursor — Aloca e retorna um novo cursor (identificador de instrução)

### Descrição

function oci_new_cursor(resource `$connection`): resource|false

Aloca um novo identificador de instrução na conexão especificada.

### Parâmetros

`connection`

  Um identificador de conexão Oracle, retornado por oci_connect() ou oci_pconnect().

### Valor Retornado

Retorna um novo identificador de instrução ou `false` em caso de erro.

### Exemplos

Exemplo #1 Vinculando um CURSOR REF em uma chamada de procedimento armazenado Oracle

    <?php

    // Pré-criação:
    //   create or replace procedure myproc(myrc out sys_refcursor) as
    //   begin
    //     open myrc for select first_name from employees;
    //   end;

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $curs = oci_new_cursor($conn);
    $stid = oci_parse($conn, "begin myproc(:cursbv); end;");
    oci_bind_by_name($stid, ":cursbv", $curs, -1, OCI_B_CURSOR);
    oci_execute($stid);

    oci_execute($curs);  // Execute o CURSOR REF como um ID de instrução normal
    while (($row = oci_fetch_array($curs, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
        echo $row['FIRST_NAME'] . "<br />\n";
    }

    oci_free_statement($stid);
    oci_free_statement($curs);
    oci_close($conn);

    ?>

# oci_new_descriptor

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_descriptor — Inicializa um novo descritor LOB ou FILE vazio

### Descrição

function oci_new_descriptor(resource `$connection`, int `$type` = `OCI_DTYPE_LOB`): ?OCILob

Aloca recursos para conter descritor ou localizador LOB.

### Parâmetros

`connection`

  Um identificador de conexão Oracle, retornado por oci_connect() ou oci_pconnect().

`type`

  Os valores válidos para `type` são: `OCI_DTYPE_FILE`, `OCI_DTYPE_LOB` e `OCI_DTYPE_ROWID`.

### Valor Retornado

Retorna um novo descritor LOB ou FILE em caso de sucesso, ou `null` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de oci_new_descriptor()

    <?php
    /* Este script foi projetado para ser chamado a partir de um formulário HTML.
     * Ele espera que $user, $password, $table, $where e $commitsize
     * sejam passados a partir ​​do formulário. O script então exclui
     * as linhas selecionadas usando o ROWID e realiza a confirmação após cada
     * conjunto de linhas $commitsize. (Use com cuidado, não há reversão)
     */
    $conn = oci_connect($user, $password);
    $stmt = oci_parse($conn, "select rowid from $table $where");
    $rowid = oci_new_descriptor($conn, OCI_D_ROWID);
    oci_define_by_name($stmt, "ROWID", $rowid);
    oci_execute($stmt);
    while (oci_fetch($stmt)) {
        $nrows = oci_num_rows($stmt);
        $delete = oci_parse($conn, "delete from $table where ROWID = :rid");
        oci_bind_by_name($delete, ":rid", $rowid, -1, OCI_B_ROWID);
        oci_execute($delete);
        echo "$nrows\n";
        if (($nrows % $commitsize) == 0) {
            oci_commit($conn);
        }
    }
    $nrows = oci_num_rows($stmt);
    echo "$nrows excluídas...\n";
    oci_free_statement($stmt);
    oci_close($conn);
    ?>

    <?php
        /* Este script demonstra o upload de arquivos para colunas LOB
         * O campo de formulário usado neste exemplo se parece com este:
         * <form action="upload.php" method="post" enctype="multipart/form-data">
         * <input type="file" name="lob_upload" />
         * ...
         */
      if (!isset($lob_upload) || $lob_upload == 'none'){
    ?>
    <form action="upload.php" method="post" enctype="multipart/form-data">
    Upload file: <input type="file" name="lob_upload" /><br />
    <input type="submit" value="Upload" /> - <input type="reset" value="Reset" />
    </form>
    <?php
      } else {

         // $lob_upload contém o nome do arquivo temporário carregado

         // veja também a seção de recursos sobre upload de arquivos,
         // se for necessário usar uploads seguros

         $conn = oci_connect($user, $password);
         $lob = oci_new_descriptor($conn, OCI_D_LOB);
         $stmt = oci_parse($conn, "insert into $table (id, the_blob)
                   values(my_seq.NEXTVAL, EMPTY_BLOB()) returning the_blob into :the_blob");
         oci_bind_by_name($stmt, ':the_blob', $lob, -1, OCI_B_BLOB);
         oci_execute($stmt, OCI_DEFAULT);
         if ($lob->savefile($lob_upload)){
            oci_commit($conn);
            echo "Blob enviado com sucesso\n";
         }else{
            echo "Não foi possível enviar o Blob\n";
         }
         $lob->free();
         oci_free_statement($stmt);
         oci_close($conn);
      }
    ?>

Exemplo #2 Exemplo de oci_new_descriptor()

    <?php
    /* Chamando procedimentos armazenados PL/SQL que contêm clobs como parâmetros
     * de entrada.
     * Exemplo de assinatura de procedimento armazenado PL/SQL:
     *
     * PROCEDURE save_data
     *   Nome do Argumento              Tipo                    In/Out Padrão?
     *   ------------------------------ ----------------------- ------ --------
     *   KEY                            NUMBER(38)              IN
     *   DATA                           CLOB                    IN
     *
     */

    $conn = oci_connect($user, $password);
    $stmt = oci_parse($conn, "begin save_data(:key, :data); end;");
    $clob = oci_new_descriptor($conn, OCI_D_LOB);
    oci_bind_by_name($stmt, ':key', $key);
    oci_bind_by_name($stmt, ':data', $clob, -1, OCI_B_CLOB);
    $clob->write($data);
    oci_execute($stmt, OCI_DEFAULT);
    oci_commit($conn);
    $clob->free();
    oci_free_statement($stmt);
    ?>

### Veja Também

- oci_bind_by_name() - Vincula uma variável PHP a um marcador Oracle

# oci_num_fields

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_num_fields — Retorna o número de colunas de resultados em uma instrução

### Descrição

function oci_num_fields(resource `$statement`): int

Obtém o número de colunas na instrução fornecida em `statement`.

### Parâmetros

`statement`

  Um identificador de instrução OCI válido.

### Valor Retornado

Retorna o número de colunas como um int.

### Exemplos

Exemplo #1 Exemplo de oci_num_fields()

    <?php

    // Crie a tabela com:
    //   CREATE TABLE mytab (id NUMBER, quantity NUMBER);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // Use OCI_DESCRIBE_ONLY se não estiver buscando linhas

    $ncols = oci_num_fields($stid);
    for ($i = 1; $i <= $ncols; $i++) {
        echo oci_field_name($stid, $i) . " " . oci_field_type($stid, $i) . "<br>\n";
    }

    // Resultado:
    //    ID NUMBER
    //    QUANTITY NUMBER

    oci_free_statement($stid);
    oci_close($conn);

    ?>

# oci_num_rows

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_num_rows — Retorna o número de linhas afetadas durante a execução da instrução

### Descrição

function oci_num_rows(resource `$statement`): int|false

Obtém o número de linhas afetadas durante a execução da instrução.

### Parâmetros

`statement`

  Um identificador de instrução OCI válido.

### Valor Retornado

Retorna o número de linhas afetadas como um inteiro, ou `false` em caso de falha

### Exemplos

Exemplo #1 Exemplo de oci_num_rows()

    <?php

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "create table emp2 as select * from employees");
    oci_execute($stid);
    echo oci_num_rows($stid) . " linhas inseridas.<br />\n";
    oci_free_statement($stid);

    $stid = oci_parse($conn, "delete from emp2");
    oci_execute($stid, OCI_DEFAULT);
    echo oci_num_rows($stid) . " linhas excluídas.<br />\n";
    oci_commit($conn);
    oci_free_statement($stid);

    $stid = oci_parse($conn, "drop table emp2");
    oci_execute($stid);
    oci_free_statement($stid);

    oci_close($conn);

    ?>

### Notas

> Nota:

> Esta função não retorna o número de linhas selecionadas! Para instruções SELECT, esta função retornará o número de linhas que foram buscadas no buffer com as funções oci_fetch*().

# oci_parse

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_parse — Prepara uma instrução Oracle para execução

### Descrição

function oci_parse(resource `$connection`, string `$sql`): resource|false

Prepara `sql` usando `connection` e retorna o identificador da instrução, que pode ser usado com oci_bind_by_name(), oci_execute() e outras funções.

Identificadores de instrução podem ser liberados com oci_free_statement() ou definindo a variável como `null`.

### Parâmetros

`connection`

  Um identificador de conexão Oracle, retornado por oci_connect(), oci_pconnect() ou oci_new_connect().

`sql`

  A instrução SQL ou PL/SQL.

  Instruções SQL não devem terminar com um ponto e vírgula (";"). Instruções PL/SQL devem terminar com um ponto e vírgula (";").

### Valor Retornado

Retorna um identificador de instrução em caso de sucesso, ou `false` em caso de erro.

### Exemplos

Exemplo #1 Exemplo de oci_parse() para instruções SQL

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    // Analisa a instrução. Observe que não há ponto e vírgula final na instrução SQL
    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Exemplo #2 Exemplo de oci_parse() para instruções PL/SQL

    <?php

    /*
      Antes de executar o programa PHP, crie um procedimento armazenado no
      SQL*Plus ou SQL Developer:

      CREATE OR REPLACE PROCEDURE myproc(p1 IN NUMBER, p2 OUT NUMBER) AS
      BEGIN
          p2 := p1 * 2;
      END;

    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $p1 = 8;

    // Ao analisar programas PL/SQL, deve haver um ponto e vírgula final na string
    $stid = oci_parse($conn, 'begin myproc(:p1, :p2); end;');
    oci_bind_by_name($stid, ':p1', $p1);
    oci_bind_by_name($stid, ':p2', $p2, 40);

    oci_execute($stid);

    print "$p2\n";   // exibe 16

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Notas

> Nota:

> Esta função não valida o `sql`. A única forma de descobrir se `sql` é uma instrução SQL ou PL/SQL válida é executando-a.

### Veja Também

- oci_execute() - Executa uma instrução
- oci_free_statement() - Libera todos os recursos associados à instrução ou cursor

# oci_password_change

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_password_change — Altera a senha do usuário do Oracle

### Descrição

function oci_password_change(
resource `$connection`,
string `$username`,
string `$old_password`,
string `$new_password`
): bool
function oci_password_change(
string `$database_name`,
string `$username`,
string `$old_password`,
string `$new_password`
): resource

Altera a senha do usuário `username`.

A função oci_password_change() é mais útil para scripts de linha de comando PHP, ou quando conexões não persistentes são usadas em toda a aplicação PHP.

### Parâmetros

`connection`

  Um identificador de conexão Oracle, retornado por oci_connect() ou oci_pconnect().

`username`

  O nome de usuário do Oracle.

`old_password`

  A senha antiga.

`new_password`

  A nova senha a ser definida.

`database_name`

  O nome do banco de dados.

### Valor Retornado

Quando `database_name` é fornecido, oci_password_change() retorna `true` em caso de sucesso, ou `false` em caso de falha. Quando `connection` é fornecido, oci_password_change() retorna o recurso de conexão em caso de sucesso, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de oci_password_change() alterando a senha de um usuário já conectado

    <?php

    $dbase      = 'localhost/orcl';
    $user       = 'cj';
    $current_pw = 'welcome';
    $new_pw     = 'geelong';

    $c = oci_pconnect($user, $current_pw, $dbase);
    oci_password_change($c, $user, $current_pw, $new_pw);
    echo "A nova senha é : " . $new_pw . "\n";

    ?>

Exemplo #2 Exemplo de oci_password_change() conectando e alterando a senha em uma só etapa

    <?php

    $dbase      = 'localhost/orcl';
    $user       = 'cj';
    $current_pw = 'welcome';
    $new_pw     = 'geelong';

    $c = oci_pconnect($user, $current_pw, $dbase);
    if (!$c) {
        $m = oci_error();
        if ($m['code'] == 28001) { // "ORA-28001: the password has expired"
            // Faz login e redefine a senha ao mesmo tempo
            $c = oci_password_change($dbase, $user, $current_pw, $new_pw);
            if ($c) {
                echo "A nova senha é : " . $new_pw . "\n";
            }
        }
    }

    if (!$c) {  // O erro original não era 28001, ou a alteração de senha falhou
        $m = oci_error();
        trigger_error('Não foi possível conectar ao banco de dados: '. $m['message'], E_USER_ERROR);
    }

    // Usando a conexão $c
    // ...

    ?>

### Notas

> Nota:

> A alteração da senha com esta função ou diretamente no Oracle deve ser feita com cuidado. Isso porque as aplicações PHP podem continuar a reutilizar conexões persistentes com sucesso autenticando-se com a senha antiga. A prática recomendada é reiniciar todos os servidores web sempre que a senha do usuário for alterada.

> Nota:

> Ao atualizar as bibliotecas do cliente Oracle ou o banco de dados de uma versão anterior à 11.2.0.3 para a versão 11.2.0.3 ou superior, oci_password_change() pode gerar o erro "ORA-1017: invalid username/password", a menos que as versões do cliente e do servidor sejam atualizadas ao mesmo tempo.

> Nota:

> A segunda sintaxe oci_password_change() está disponível desde a versão 1.1 do OCI8.

# oci_pconnect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_pconnect — Conecta-se a um banco de dados Oracle usando uma conexão persistente

### Descrição

function oci_pconnect(
string `$username`,
string `$password`,
?string `$connection_string` = `null`,
string `$encoding` = "",
int `$session_mode` = `OCI_DEFAULT`
): resource|false

Cria uma conexão persistente com um servidor Oracle e efetua logon.

Conexões persistentes são armazenadas em cache e reutilizadas entre solicitações, resultando em redução de sobrecarga a cada carregamento de página; uma aplicação PHP típica terá uma única conexão persistente aberta em um servidor Oracle por processo filho do Apache (ou processo PHP FPM). Consulte a seção Manipulação de Conexões e Pool de Conexões do OCI8 para obter mais informações.

### Parâmetros

`username`

  O nome de usuário do Oracle.

`password`

  A senha para `username`.

`connection_string`
  Contém a `instância do Oracle` à qual se conectar. Pode ser uma » string Easy Connect ou um Connect Name do arquivo tnsnames.ora ou o nome de uma instância local do Oracle. Se não especificado ou `null`, o PHP usará variáveis de ambiente como `TWO_TASK` (no Linux) ou `LOCAL` (no Windows) e `ORACLE_SID` para determinar a `instância do Oracle` à qual se conectar. Para usar o método de nomenclatura Easy Connect, o PHP precisa ter sido compilado com as bibliotecas Oracle Client 10g ou superiores. A string Easy Connect para o Oracle 10g tem o formato: [//]nome_do_servidor[:porta][/nome_do_servico]. A partir do Oracle 11g a sintaxe é: [//]nome_do_servidor[:porta][/nome_do_servico][:tipo_de_servidor][/nome_da_instancia]. Outras opções foram introduzidas com o Oracle 19c, incluindo as configurações de timeout e keep-alive. Consulte a documentação do Oracle. Os nomes dos serviços podem ser encontrados executando o utilitário Oracle `lsnrctl status` na máquina do servidor de banco de dados. O arquivo tnsnames.ora pode estar no caminho de pesquisa Oracle Net, que inclui /seu/caminho/para/instantclient/network/admin, $ORACLE_HOME/network/admin e /etc. Como alternativa, defina `TNS_ADMIN` para que $TNS_ADMIN/tnsnames.ora possa ser lido. Certifique-se de que o servidor web tem acesso de leitura ao arquivo.
`encoding`
  Determina o conjunto de caracteres usado pelas bibliotecas Oracle Client. O conjunto de caracteres não precisa corresponder ao conjunto de caracteres usado pelo banco de dados. Se não corresponderem, o Oracle fará o possível para converter os dados de e para o conjunto de caracteres do banco de dados. Dependendo dos conjuntos de caracteres, isso pode não fornecer resultados utilizáveis. A conversão também adiciona alguma sobrecarga de tempo. Se não for especificado, as bibliotecas Oracle Client determinam um conjunto de caracteres a partir da variável de ambiente `NLS_LANG`. Passar este parâmetro pode reduzir o tempo necessário para conectar.
`session_mode`
  Este parâmetro está disponível a partir do PHP 5 (PECL OCI8 1.1) e aceita os seguintes valores: `OCI_DEFAULT`, `OCI_SYSOPER` e `OCI_SYSDBA`. Se `OCI_SYSOPER` ou `OCI_SYSDBA` forem especificadas, esta função tentará estabelecer uma conexão privilegiada usando credenciais externas. Conexões privilegiadas estão desabilitadas por padrão. Para habilitá-las é preciso configurar oci8.privileged_connect para `On`. O PHP 5.3 (PECL OCI8 1.3.4) introduziu o valor de modo `OCI_CRED_EXT`. Ele informa ao Oracle para usar autenticação External ou OS, que deve ser configurada no banco de dados. A flag `OCI_CRED_EXT` só pode ser usada com o usuário "/" e uma senha vazia. oci8.privileged_connect pode ser `On` ou `Off`. `OCI_CRED_EXT` pode ser combinado com os modos `OCI_SYSOPER` ou `OCI_SYSDBA`. `OCI_CRED_EXT` não é suportado no Windows por razões de segurança.

### Valor Retornado

Retorna um identificador de conexão ou `false` em caso de erro.

### Exemplos

Exemplo #1 Exemplo básico de oci_pconnect() usando a sintaxe Easy Connect

    <?php

    // Conecta-se ao serviço XE (ou seja, banco de dados) na máquina "localhost"
    $conn = oci_pconnect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Consulte oci_connect() para mais exemplos de uso de parâmetros.

### Notas

> Nota: O tempo de vida e o número máximo de conexões Oracle persistentes por processo PHP podem ser ajustados definindo os seguintes valores de configuração: oci8.persistent_timeout, oci8.ping_interval e oci8.max_persistent.

### Veja Também

- oci_connect() - Conecta-se a um banco de dados Oracle
- oci_new_connect() - Conecta-se ao servidor Oracle usando uma conexão exclusiva

# oci_register_taf_callback

(PHP 7.0 >= 7.0.21, PHP 8, PHP 7 >= 7.1.7, PHP 8, PECL OCI8 >= 2.1.7)

oci_register_taf_callback — Registra uma função de retorno definida pelo usuário para o TAF do Oracle Database

### Descrição

function oci_register_taf_callback(resource `$connection`, ?callable `$callback`): bool

Registra uma função de retorno definida pelo usuário para a conexão `connection`. Se a conexão de `connection` falhar devido a uma falha de instância ou de rede, a função de retorno registrada será invocada várias vezes durante o failover. Consulte Suporte para Failover Transparente de Aplicativos (TAF) OCI8 para obter informações.

Quando oci_register_taf_callback() é chamada várias vezes, cada registro substitui o anterior.

Use oci_unregister_taf_callback() para cancelar explicitamente o registro de uma função de retorno definida pelo usuário.

O registro de função de retorno do TAF NÃO será salvo em conexões persistentes, portanto, a função de retorno precisa ser registrada novamente para uma nova conexão persistente.

### Parâmetros

`connection`

  Um identificador de conexão Oracle.

`callback`

  Uma função de retorno definida pelo usuário para registro no Oracle TAF. Pode ser uma string com o nome da função ou um Closure (função anônima).

  A interface de uma função de retorno definida pelo usuário do TAF é a seguinte:

  function userCallbackFn(resource `$connection`, int `$event`, int `$type`): int

  Veja a descrição do parâmetro e um exemplo na página Suporte ao Failover Transparente de Aplicativos (TAF) do OCI8.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- oci_unregister_taf_callback() - Cancelar o registro de uma função de retorno definida pelo usuário para o TAF do Oracle Database

# oci_result

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_result — Retorna o valor do campo da linha recuperada

### Descrição

function oci_result(resource `$statement`, string|int `$column`): mixed

Retorna os dados da coluna informada em `column` na linha atual, obtidos por oci_fetch().

Para obter detalhes sobre o mapeamento dos tipos de dados realizado pela extensão OCI8, consulte os tipos de dados suportados pelo driver.

### Parâmetros

`statement`

`column`

  Pode ser usado o número da coluna (base 1) ou o nome da coluna. A caixa do nome da coluna deve ser a mesma que os metadados do Oracle descrevem a coluna, que é maiúscula para colunas criadas sem distinção entre maiúsculas e minúsculas.

### Valor Retornado

Retorna tudo como strings, exceto tipos abstratos (ROWIDs, LOBs e FILEs). Retorna `false` em caso de erro.

### Exemplos

Exemplo #1 oci_fetch() com oci_result()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    while (oci_fetch($stid)) {
        echo oci_result($stid, 'LOCATION_ID') . " é ";
        echo oci_result($stid, 'CITY') . "<br>\n";
    }

    // Exibe:
    //   1000 é Roma
    //   1100 é Venice

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Veja Também

- oci_fetch_array() - Retorna a próxima linha de uma consulta como um array associativo ou numérico
- oci_fetch_assoc() - Retorna a próxima linha de uma consulta como um array associativo
- oci_fetch_object() - Retorna a próxima linha de uma consulta como um objeto
- oci_fetch_row() - Retorna a próxima linha de uma consulta como um array numérico
- oci_fetch_all() - Busca várias linhas de uma consulta em um array bidimensional

# oci_rollback

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_rollback — Reverte a transação pendente do banco de dados

### Descrição

function oci_rollback(resource `$connection`): bool

Reverte todas as alterações não confirmadas para a conexão do Oracle definida em `connection` e encerra a transação. Libera todos os bloqueios mantidos. Todos os `SAVEPOINTS` do Oracle são apagados.

Uma transação começa quando a primeira instrução SQL que altera os dados é executada com oci_execute() usando a opção `OCI_NO_AUTO_COMMIT`. Outras alterações nos dados feitas por outras instruções tornam-se parte da mesma transação. As alterações nos dados feitas em uma transação são temporárias até que a transação seja confirmada ou revertida. Outros usuários do banco de dados não verão as alterações até que sejam confirmadas.

Ao inserir ou atualizar dados, é recomendado o uso de transações para consistência de dados relacionais e por questões de desempenho.

### Parâmetros

`connection`

  Um identificador de conexão Oracle, retornado por oci_connect(), oci_pconnect() ou oci_new_connect().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de oci_rollback()

    <?php

    // Insere em várias tabelas, revertendo as alterações se ocorrer um erro

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, "INSERT INTO mysalary (id, name) VALUES (1, 'Chris')");

    // O sinalizador OCI_NO_AUTO_COMMIT informa ao Oracle para não confirmar o INSERT imediatamente
    $r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
    if (!$r) {
        $e = oci_error($stid);
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'INSERT INTO myschedule (startday) VALUES (12)');
    $r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
    if (!$r) {
        $e = oci_error($stid);
        oci_rollback($conn);  // reverte alterações em ambas as tabelas
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    // Confirma as alterações em ambas as tabelas
    $r = oci_commit($conn);
    if (!r) {
        $e = oci_error($conn);
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    ?>

Exemplo #2 Exemplo de reversão para um `SAVEPOINT`

    <?php
    $stid = oci_parse($conn, 'UPDATE mytab SET id = 1111');
    oci_execute($stid, OCI_NO_AUTO_COMMIT);

    // Cria o ponto de salvamento
    $stid = oci_parse($conn, 'SAVEPOINT mysavepoint');
    oci_execute($stid, OCI_NO_AUTO_COMMIT);

    $stid = oci_parse($conn, 'UPDATE mytab SET id = 2222');
    oci_execute($stid, OCI_NO_AUTO_COMMIT);

    // Usa uma instrução SQL explícita para retornar ao ponto de salvamento
    $stid = oci_parse($conn, 'ROLLBACK TO SAVEPOINT mysavepoint');
    oci_execute($stid, OCI_NO_AUTO_COMMIT);

    oci_commit($conn);  // mytab agora tem o ID de 1111
    ?>

### Notas

> Nota:

> As transações são revertidas automaticamente quando a conexão é fechada ou quando o script termina, o que ocorrer primeiro. Deve ser chamada explicitamente a função oci_commit() para confirmar a transação.

> Qualquer chamada a oci_execute() que utilize o modo `OCI_COMMIT_ON_SUCCESS` explicitamente ou por padrão confirmará qualquer transação anterior não confirmada.

> Qualquer instrução DDL do Oracle, como `CREATE` ou `DROP`, confirmará automaticamente qualquer transação não confirmada.

### Veja Também

- oci_commit() - Confirma a transação de banco de dados pendente
- oci_execute() - Executa uma instrução

# oci_server_version

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_server_version — Retorna a versão do banco de dados Oracle

### Descrição

function oci_server_version(resource `$connection`): string|false

Retorna uma string com a versão do Oracle Database e as opções disponíveis.

### Parâmetros

`connection`

### Valor Retornado

Retorna as informações da versão como uma string ou `false` em caso de erro.

### Exemplos

Exemplo #1 Exemplo de oci_server_version()

    <?php

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    echo "Versão do Servidor: " . oci_server_version($conn);

    // Exibe:
    // Versão do Servidor: Oracle Database 11g Enterprise Edition Release 11.2.0.1.0 - 64bit Production
    // With the Partitioning, OLAP, Data Mining and Real Application Testing option

    oci_close($conn);

    ?>

### Veja Também

- oci_client_version() - Retorna a versão da biblioteca do cliente Oracle

# oci_set_action

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_action — Define o nome da ação

### Descrição

function oci_set_action(resource `$connection`, string `$action`): bool

Define o nome da ação para o rastreamento do Oracle.

O nome da ação é registrado no banco de dados quando ocorre a próxima 'viagem de ida e volta' do PHP para o banco de dados, normalmente quando uma instrução SQL é executada.

O nome da ação pode ser consultado posteriormente em visualizações de administração do banco de dados, como `V$SESSION`. Ele pode ser usado para rastreamento e monitoramento, como com `V$SQLAREA` e `DBMS_MONITOR.SERV_MOD_ACT_STAT_ENABLE`.

O valor pode ser retido em conexões persistentes.

### Parâmetros

`connection`
  Um identificador de conexão Oracle, retornado por oci_connect(), oci_pconnect() ou oci_new_connect().
`action`

  String escolhida pelo usuário com até 32 bytes de comprimento.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Definindo a ação

    <?php

    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    // Grava a ação
    oci_set_action($c, 'Friend Lookup');

    // Código que causa uma viagem de ida e volta, por exemplo, uma consulta:
    $s = oci_parse($c, 'select * from dual');
    oci_execute($s);
    oci_fetch_all($s, $res);

    sleep(30);

    ?>

    // Enquanto o script estiver em execução, o administrador poderá visualizar as ações
    // sendo executadas:

    sqlplus system/welcome
    SQL> select action from v$session;

### Notas

> Nota: Requisitos de versão do Oracle
> Esta função estará disponível quando o PHP for compilado com as bibliotecas do Oracle Database a partir da versão 10g em diante.

Dica

# Desempenho

Com versões anteriores do OCI8 ou do Oracle Database, as informações do cliente podem ser definidas usando o pacote Oracle `DBMS_APPLICATION_INFO`. Isso é menos eficiente do que usar oci_set_client_info().

Cuidado

# Pegadinha da Viagem de Ida e Volta

Algumas, mas não todas as funções do OCI8, causam viagens de ida e volta. Viagens de ida e volta ao banco de dados podem não ocorrer com consultas quando o cache de resultados estiver habilitado.

### Veja Também

- oci_set_module_name() - Define o nome do módulo
- oci_set_client_info() - Define as informações do cliente
- oci_set_client_identifier() - Define o identificador do cliente
- oci_set_db_operation() - Define a operação do banco de dados

# oci_set_call_timeout

(PHP 7.2 >= 7.2.14, PHP 8, PHP 7 >= 7.3.1, PHP 8, PECL OCI8 >= 2.2.0)

oci_set_call_timeout — Sets a millisecond timeout for database calls

### Descrição

function oci_set_call_timeout(resource `$connection`, int `$timeout`): bool

Define um tempo limite máximo que uma viagem de ida e volta ao banco de dados usando esta conexão pode levar.

Cada operação OCI8 pode fazer zero ou mais chamadas à biblioteca cliente da Oracle. Essas chamadas internas podem, então, fazer zero ou mais viagens de ida e volta ao banco de dados Oracle. Se qualquer uma dessas viagens de ida e volta levar mais de `time_out` milissegundos, a operação será cancelada e um erro será retornado ao aplicativo.

O valor `time_out` se aplica a cada viagem de ida e volta individualmente, não à soma de todas as viagens de ida e volta. O tempo gasto no processamento em PHP OCI8 antes ou depois da conclusão de cada viagem de ida e volta não é contabilizado.

Quando uma chamada é interrompida, a Oracle tentará limpar a conexão para reutilização. Esta operação pode ser executada por outro período de `time_out`. Dependendo do resultado da limpeza, a conexão pode ou não ser reutilizável.

Quando conexões persistentes são usadas, o valor de tempo limite será mantido em todas as solicitações PHP.

A função oci_set_call_timeout() está disponível quando o OCI8 usa bibliotecas de cliente Oracle 18 (ou posterior).

### Parâmetros

`connection`
  Um identificador de conexão Oracle, retornado por oci_connect(), oci_pconnect() ou oci_new_connect().
`timeout`

  O tempo máximo em milissegundos que qualquer viagem de ida e volta entre PHP e Oracle Database pode levar.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Definindo o tempo limite

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    oci_set_call_timeout($conn, 5000);

    ?>

# oci_set_client_identifier

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_client_identifier — Define o identificador do cliente

### Descrição

function oci_set_client_identifier(resource `$connection`, string `$client_id`): bool

Define o identificador de cliente usado por vários componentes de banco de dados para identificar usuários de aplicações leves que se autenticam como o mesmo usuário de banco de dados.

O identificador do cliente é registrado no banco de dados quando ocorre a próxima 'viagem de ida e volta' do PHP para o banco de dados, normalmente quando uma instrução SQL é executada.

O identificador pode ser consultado posteriormente, por exemplo, com `SELECT SYS_CONTEXT('USERENV','CLIENT_IDENTIFIER') FROM DUAL`. Visualizações de administração de banco de dados, como `V$SESSION`, também conterão o valor. Ele pode ser usado com `DBMS_MONITOR.CLIENT_ID_TRACE_ENABLE` para rastreamento e também para auditoria.

O valor pode ser retido em solicitações de página que usam a mesma conexão persistente.

### Parâmetros

`connection`
  Um identificador de conexão Oracle, retornado por oci_connect(), oci_pconnect() ou oci_new_connect().
`client_id`

  String escolhida pelo usuário com até 64 bytes de comprimento.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Definindo o identificador do cliente para o usuário da aplicação

    <?php

    // Encontra o nome de login do usuário do aplicativo
    session_start();
    $un = my_validate_session($_SESSION['username']);
    $c = oci_connect('myschema', 'welcome', 'localhost/XE');

    // Informa ao Oracle quem é esse usuário
    oci_set_client_identifier($c, $un);

    // A próxima viagem de ida e volta ao banco de dados trará o identificador
    $s = oci_parse($c, 'select mydata from mytable');
    oci_execute($s);

    // ...

    ?>

### Notas

Cuidado

# Pegadinha da Viagem de Ida e Volta

Algumas, mas não todas as funções do OCI8, causam viagens de ida e volta. Viagens de ida e volta ao banco de dados podem não ocorrer com consultas quando o cache de resultados estiver habilitado.

### Veja Também

- oci_set_module_name() - Define o nome do módulo
- oci_set_action() - Define o nome da ação
- oci_set_client_info() - Define as informações do cliente
- oci_set_db_operation() - Define a operação do banco de dados

# oci_set_client_info

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_client_info — Define as informações do cliente

### Descrição

function oci_set_client_info(resource `$connection`, string `$client_info`): bool

Define as informações do cliente para rastreamento do Oracle.

As informações do cliente são registradas no banco de dados quando ocorre a próxima 'viagem de ida e volta' do PHP para o banco de dados, normalmente quando uma instrução SQL é executada.

As informações do cliente podem ser posteriormente consultadas em visualizações de administração do banco de dados, como `V$SESSION`.

O valor pode ser retido em conexões persistentes.

### Parâmetros

`connection`
  Um identificador de conexão Oracle, retornado por oci_connect(), oci_pconnect() ou oci_new_connect().
`client_info`

  String escolhida pelo usuário com até 64 bytes de comprimento.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Definindo as informações do cliente

    <?php

    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    // Registra as informações do cliente
    oci_set_client_info($c, 'Minha Aplicação Versão 2');

    // Código que causa uma viagem de ida e volta, por exemplo, uma consulta:
    $s = oci_parse($c, 'select * from dual');
    oci_execute($s);
    oci_fetch_all($s, $res);

    sleep(30);

    ?>

    // Enquanto o script estiver em execução, o administrador poderá visualizar as informações
    // do cliente:

    sqlplus system/welcome
    SQL> select client_info from v$session;

### Notas

> Nota: Requisitos de versão do Oracle
> Esta função estará disponível quando o PHP for compilado com as bibliotecas do Oracle Database a partir da versão 10g em diante.

Dica

# Desempenho

Com versões anteriores do OCI8 ou do Oracle Database, as informações do cliente podem ser definidas usando o pacote Oracle `DBMS_APPLICATION_INFO`. Isso é menos eficiente do que usar oci_set_client_info().

Cuidado

# Pegadinha da Viagem de Ida e Volta

Algumas, mas não todas as funções do OCI8, causam viagens de ida e volta. Viagens de ida e volta ao banco de dados podem não ocorrer com consultas quando o cache de resultados estiver habilitado.

### Veja Também

- oci_set_module_name() - Define o nome do módulo
- oci_set_action() - Define o nome da ação
- oci_set_client_identifier() - Define o identificador do cliente
- oci_set_db_operation() - Define a operação do banco de dados

# oci_set_db_operation

(PHP 7 >= 7.2.14, PHP 8, PHP 7 >= 7.3.1, PHP 8, PECL OCI8 >= 2.2.0)

oci_set_db_operation — Define a operação do banco de dados

### Descrição

function oci_set_db_operation(resource `$connection`, string `$action`): bool

Define o DBOP para rastreamento Oracle.

O nome da operação do banco de dados é registrado no banco de dados quando ocorre a próxima 'viagem de ida e volta' do PHP para o banco de dados, normalmente quando uma instrução SQL é executada.

A operação do banco de dados pode ser consultada posteriormente a partir de visualizações de administração do banco de dados, como `V$SQL_MONITOR`.

A função oci_set_db_operation() está disponível quando o OCI8 utiliza bibliotecas de cliente Oracle 12 (ou posterior) e o Oracle Database 12 (ou posterior).

### Parâmetros

`connection`
  Um identificador de conexão Oracle, retornado por oci_connect(), oci_pconnect() ou oci_new_connect().
`action`

  String escolhida pelo usuário.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Definindo o DBOP

    <?php

    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    // Registra a operação
    oci_set_db_operation($c, 'main query');

    // Código que causa uma viagem de ida e volta, por exemplo, uma consulta:
    $s = oci_parse($c, 'select * from dual');
    oci_execute($s);
    oci_fetch_all($s, $res);

    sleep(30);

    ?>

    // Enquanto o script estiver em execução, o administrador poderá visualizar as operações do banco de dados
    // sendo realizadas:

    sqlplus system/welcome
    SQL> select dbop_name from v$sql_monitor;

### Notas

Cuidado

# Pegadinha da Viagem de Ida e Volta

Algumas, mas não todas as funções do OCI8, causam viagens de ida e volta. Viagens de ida e volta ao banco de dados podem não ocorrer com consultas quando o cache de resultados estiver habilitado.

### Veja Também

- oci_set_action() - Define o nome da ação
- oci_set_module_name() - Define o nome do módulo
- oci_set_client_info() - Define as informações do cliente
- oci_set_client_identifier() - Define o identificador do cliente

# oci_set_edition

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_edition — Define a edição do banco de dados

### Descrição

function oci_set_edition(string `$edition`): bool

Define a "edição" do banco de dados dos objetos a serem usados ​​por conexões subsequentes.

As edições Oracle permitem que versões simultâneas de aplicações sejam executadas usando o mesmo esquema e nomes de objetos. Isso é útil para atualizar sistemas ativos.

Chame oci_set_edition() antes de chamar oci_connect(), oci_pconnect() ou oci_new_connect().

Se uma edição definida que não seja válida no banco de dados, a conexão falhará mesmo que oci_set_edition() retorne sucesso.

Ao usar conexões persistentes, se uma conexão com a configuração de edição solicitada já existir, ela será reutilizada. Caso contrário, uma conexão persistente diferente será criada.

### Parâmetros

`edition`

  Nome da edição do Oracle Database criada anteriormente com o comando SQL "`CREATE EDITION`".

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Dois scripts podem usar versões diferentes de myfunc() ao mesmo tempo

    <?php

    // Arquivo 1

    echo "Versão 1 da aplicação\n";

    oci_set_edition('ORA$BASE');
    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    $s = oci_parse($c, "begin :r := myfunc(); end;");
    oci_bind_by_name($s, ":r", $r, 20);
    oci_execute($s);
    echo "O resultado é $r\n";

    ?>

    <?php

    // Arquivo 2

    echo "Versão 2 da aplicação\n";

    oci_set_edition('E1');
    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    $s = oci_parse($c, "begin :r := myfunc(); end;");
    oci_bind_by_name($s, ":r", $r, 20);
    oci_execute($s);
    echo "O resultado é $r\n";

    ?>

### Notas

> Nota: Requisito de versão Oracle

> Esta função está disponível a partir do Oracle 11gR2.

Cuidado

# Conexões persistentes

Para evitar inconsistências e erros inesperados, não utilize ALTER SESSION SET EDITION para alterar a edição em conexões persistentes.

Cuidado

# Pool de conexões DRCP

Para evitar inconsistências e erros inesperados ao usar edições e DRCP com o Oracle 11.2.0.1, mantenha uma correspondência um-para-um entre o oci8.connection_class e o nome da edição usada pelas aplicações. Cada servidor em pool de uma determinada classe de conexão deve ser usado apenas com uma edição. Essa restrição foi removida com o Oracle 11.2.0.2.

# oci_set_module_name

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_module_name — Define o nome do módulo

### Descrição

function oci_set_module_name(resource `$connection`, string `$name`): bool

Define o nome do módulo para rastreamento do Oracle.

O nome do módulo é registrado no banco de dados quando ocorre a próxima 'viagem de ida e volta' do PHP para o banco de dados, normalmente quando uma instrução SQL é executada.

O nome pode ser posteriormente consultado em visualizações de administração de banco de dados, como `V$SESSION`. Ele pode ser usado para rastreamento e monitoramento, como com `V$SQLAREA` e `DBMS_MONITOR.SERV_MOD_ACT_STAT_ENABLE`.

O valor pode ser retido em conexões persistentes.

### Parâmetros

`connection`
  Um identificador de conexão Oracle, retornado por oci_connect(), oci_pconnect() ou oci_new_connect().
`name`

  string escolhida pelo usuário com até 48 bytes de comprimento.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Definindo o nome do módulo

    <?php

    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    // Registra o módulo
    oci_set_module_name($c, 'Home Page');

    // Código que causa uma viagem de ida e volta, por exemplo, uma consulta:
    $s = oci_parse($c, 'select * from dual');
    oci_execute($s);
    oci_fetch_all($s, $res);

    sleep(30);
    ?>

    // Enquanto o script estiver em execução, o administrador poderá ver os
    // módulos em uso:

    sqlplus system/welcome
    SQL> select module from v$session;

### Notas

> Nota: Requisitos de versão do Oracle
> Esta função estará disponível quando o PHP for compilado com as bibliotecas do Oracle Database a partir da versão 10g em diante.

Dica

# Desempenho

Com versões anteriores do OCI8 ou do Oracle Database, as informações do cliente podem ser definidas usando o pacote Oracle `DBMS_APPLICATION_INFO`. Isso é menos eficiente do que usar oci_set_client_info().

Cuidado

# Pegadinha da Viagem de Ida e Volta

Algumas, mas não todas as funções do OCI8, causam viagens de ida e volta. Viagens de ida e volta ao banco de dados podem não ocorrer com consultas quando o cache de resultados estiver habilitado.

### Veja Também

- oci_set_action() - Define o nome da ação
- oci_set_client_info() - Define as informações do cliente
- oci_set_client_identifier() - Define o identificador do cliente
- oci_set_db_operation() - Define a operação do banco de dados

# oci_set_prefetch

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_set_prefetch — Define o número de linhas a serem pré-buscadas pelas consultas

### Descrição

function oci_set_prefetch(resource `$statement`, int `$rows`): bool

Define o número de linhas a serem armazenadas em buffer pelas bibliotecas do Oracle Client após uma chamada de consulta bem-sucedida a oci_execute() e para cada solicitação de busca interna subsequente ao banco de dados. Para consultas que retornam um grande número de linhas, o desempenho pode ser significativamente melhorado aumentando a contagem de pré-busca acima do valor padrão oci8.default_prefetch.

A pré-busca é a maneira eficiente da Oracle de retornar mais de uma linha de dados do banco de dados em cada solicitação de rede. Isso pode resultar em melhor utilização da rede e da CPU. O buffer de linhas é interno ao OCI8 e o comportamento das funções de busca do OCI8 permanece inalterado, independentemente da contagem de pré-busca. Por exemplo, oci_fetch_row() sempre retornará uma linha. O buffer de pré-busca é por instrução e não é usado por instruções reexecutadas ou por outras conexões.

Chame oci_set_prefetch() antes de chamar oci_execute().

Uma meta de ajuste é definir o valor de pré-busca para um tamanho razoável para a rede e o banco de dados manipularem. Para consultas que retornam um número muito grande de linhas, a eficiência geral do sistema pode ser melhor se as linhas forem recuperadas do banco de dados em vários blocos (ou seja, definir o valor de pré-busca menor que o número de linhas). Isso permite que o banco de dados manipule as instruções de outros usuários enquanto o script PHP está processando o conjunto atual de linhas.

A pré-busca de consultas foi introduzida no Oracle 8i. REF CURSOR A pré-busca de CURSOR REF foi introduzida no Oracle 11gR2 e ocorre quando o PHP é vinculado às bibliotecas do cliente Oracle 11gR2 (ou posterior). A pré-busca de cursor aninhado foi introduzida no Oracle 11gR2 e requer que tanto as bibliotecas do cliente Oracle quanto o banco de dados sejam da versão 11gR2 ou superior.

A pré-busca não é suportada quando consultas contêm colunas LONG ou LOB. O valor da pré-busca é ignorado e buscas de linha única serão usadas em todas as situações em que a pré-busca não for suportada.

Ao utilizar o Oracle Database 12c, o valor de pré-busca definido pelo PHP pode ser substituído pelo arquivo de configuração `oraaccess.xml` do cliente da Oracle. Consulte a documentação da Oracle para obter mais detalhes.

### Parâmetros

`statement`
  Um identificador de declaração OCI8 válida criada por oci_parse() e executada por oci_execute() ou um identificador de declaração `REF CURSOR`.
`rows`

  O número de linhas a serem pré-buscadas, >= 0

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Alterando o valor de pré-busca padrão para uma consulta

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'SELECT * FROM myverybigtable');
    oci_set_prefetch($stid, 300);  // Defina antes de chamar oci_execute()
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemplo #2 Alterando a pré-busca padrão para uma busca de CURSOR REF

    <?php
    /*
      Crie o procedimento armazenado PL/SQL como:

      CREATE OR REPLACE PROCEDURE myproc(p1 OUT SYS_REFCURSOR) AS
      BEGIN
        OPEN p1 FOR SELECT * FROM all_objects WHERE ROWNUM < 5000;
      END;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'BEGIN myproc(:rc); END;');
    $refcur = oci_new_cursor($conn);
    oci_bind_by_name($stid, ':rc', $refcur, -1, OCI_B_CURSOR);
    oci_execute($stid);

    // Altera a pré-busca antes de executar o cursor.
    // A pré-busca do REF CURSOR funciona quando o PHP está vinculado a bibliotecas de cliente Oracle 11gR2 ou posterior
    oci_set_prefetch($refcur, 200);
    oci_execute($refcur);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($refcur, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($refcur);
    oci_free_statement($stid);
    oci_close($conn);

    ?>

Se o PHP OCI8 buscar um CURSOR REF e, em seguida, passar o CURSOR REF de volta para um segundo procedimento PL/SQL para processamento posterior, defina a contagem de pré-busca do CURSOR REF como `0` para evitar que linhas sejam "perdidas" do conjunto de resultados. O valor da pré-busca é o número de linhas extras buscadas em cada solicitação interna do OCI8 para o banco de dados, portanto, defini-lo como `0` significa apenas buscar uma linha por vez.

Exemplo #3 Definindo o valor de pré-busca ao passar um CURSOR REF de volta para o Oracle

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/orcl');

    // Obtém o CURSOR REF
    $stid = oci_parse($conn, 'BEGIN myproc(:rc_out); END;');
    $refcur = oci_new_cursor($conn);
    oci_bind_by_name($stid, ':rc_out', $refcur, -1, OCI_B_CURSOR);
    oci_execute($stid);

    // Exibe duas linhas, mas não pré-busca nenhuma linha extra, caso contrário
    // essas linhas extras não seriam passadas de volta para myproc_use_rc().
    oci_set_prefetch($refcur, 0);
    oci_execute($refcur);
    $row = oci_fetch_array($refcur);
    var_dump($row);
    $row = oci_fetch_array($refcur);
    var_dump($row);

    // Passa o CURSOR REF para myproc_use_rc() para realizar mais processamento de dados
    // com o conjunto de resultados
    $stid = oci_parse($conn, 'begin myproc_use_rc(:rc_in); end;');
    oci_bind_by_name($stid, ':rc_in', $refcur, -1, OCI_B_CURSOR);
    oci_execute($stid);

    ?>

### Veja Também

- Opção INI oci8.default_prefetch

# oci_set_prefetch_lob

(PHP 8.2, PECL OCI8 >= 3.2)

oci_set_prefetch_lob — Define a quantidade de dados pré-buscados para cada CLOB ou BLOB

### Descrição

function oci_set_prefetch_lob(resource `$statement`, int `$prefetch_lob_size`): bool

Define o tamanho do buffer interno usado para buscar cada valor CLOB ou BLOB quando a implementação obtém o localizador interno de LOB do Oracle do banco de dados após uma chamada de consulta bem-sucedida para oci_execute() e para cada solicitação de busca interna subsequente ao banco de dados. Aumentar este valor pode melhorar o desempenho da busca de LOBs menores, reduzindo as viagens de ida e volta entre o PHP e o banco de dados. O uso de memória será alterado.

O valor afeta LOBs retornados como instâncias OCILob e também aqueles retornados usando `OCI_RETURN_LOBS`.

Chame oci_set_prefetch_lob() antes de chamar oci_execute(). Se não for chamado, o valor de oci8.prefetch_lob_size será usado.

O valor de pré-busca LOB só deve ser definido com o Oracle Database 12.2 ou posterior.

### Parâmetros

`statement`
  Um identificador de declaração OCI8 válida criada por oci_parse() e executada por oci_execute() ou um identificador de declaração `REF CURSOR`.
`prefetch_lob_size`

  O número de bytes de cada LOB a ser pré-buscado, >= 0

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Alterando o valor de pré-busca LOB para uma consulta

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'SELECT myclob FROM mytable');
    oci_set_prefetch_lob($stid, 100000);  // Defina antes de chamar oci_execute()
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS+OCI_RETURN_LOBS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Veja Também

- Opção INI oci8.prefetch_lob_size

# oci_statement_type

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_statement_type — Retorna o tipo de uma instrução

### Descrição

function oci_statement_type(resource `$statement`): string|false

Retorna uma palavra-chave que identifica o tipo da instrução do OCI8 informada em `statement`.

### Parâmetros

`statement`

  Um identificador de instrução OCI8 válido de oci_parse().

### Valor Retornado

Retorna o tipo da instrução informada em `statement` como uma das seguintes strings.

Tipo de instrução
String de retorno | Notas
--- | ---
`ALTER` |
`BEGIN` |
`CALL` |
`CREATE` |
`DECLARE` |
`DELETE` |
`DROP` |
`INSERT` |
`SELECT` |
`UPDATE` |
`UNKNOWN` |

Retorna `false` em caso de erro.

### Exemplos

Exemplo #1 Exemplo de oci_statement_type()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'DELETE FROM departments WHERE department_id = 130;');
    if (oci_statement_type($stid) == "DELETE") {
        trigger_error('You are not allowed to delete from this table', E_USER_ERROR);
    }
    else {
        oci_execute($stid);  // exclui a linha
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

# oci_unregister_taf_callback

(PHP 7.0 >= 7.0.23, PHP 8, PHP 7 >= 7.1.9, PHP 8, PECL OCI8 >= 2.1.7)

oci_unregister_taf_callback — Cancelar o registro de uma função de retorno definida pelo usuário para o TAF do Oracle Database

### Descrição

function oci_unregister_taf_callback(resource `$connection`): bool

Cancela o registro da função de retorno definida pelo usuário registrada em `connection` por oci_register_taf_callback(). Consulte Suporte a Failover Transparente de Aplicativos (TAF) OCI8 para obter mais informações.

### Parâmetros

`connection`

  Um identificador de conexão Oracle.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- oci_register_taf_callback() - Registra uma função de retorno definida pelo usuário para o TAF do Oracle Database

## Índice

- oci_bind_array_by_name — Vincula um array PHP a um parâmetro de array Oracle PL/SQL
- oci_bind_by_name — Vincula uma variável PHP a um marcador Oracle
- oci_cancel — Cancela a leitura do cursor
- oci_client_version — Retorna a versão da biblioteca do cliente Oracle
- oci_close — Fecha uma conexão Oracle
- oci_commit — Confirma a transação de banco de dados pendente
- oci_connect — Conecta-se a um banco de dados Oracle
- oci_define_by_name — Associa uma variável PHP a uma coluna para buscas de consulta
- oci_error — Retorna o último erro encontrado
- oci_execute — Executa uma instrução
- oci_fetch — Busca a próxima linha de uma consulta em buffers internos
- oci_fetch_all — Busca várias linhas de uma consulta em um array bidimensional
- oci_fetch_array — Retorna a próxima linha de uma consulta como um array associativo ou numérico
- oci_fetch_assoc — Retorna a próxima linha de uma consulta como um array associativo
- oci_fetch_object — Retorna a próxima linha de uma consulta como um objeto
- oci_fetch_row — Retorna a próxima linha de uma consulta como um array numérico
- oci_field_is_null — Verifica se um campo na linha atualmente buscada é null
- oci_field_name — Retorna o nome de um campo da instrução
- oci_field_precision — Informa a precisão de um campo
- oci_field_scale — Informa a escala do campo
- oci_field_size — Retorna o tamanho do campo
- oci_field_type — Retorna o nome do tipo de dados de um campo
- oci_field_type_raw — Informa o tipo bruto de dados do Oracle de um campo
- oci_free_descriptor — Libera um descritor
- oci_free_statement — Libera todos os recursos associados à instrução ou cursor
- oci_get_implicit_resultset — Retorna o próximo recurso de instrução filho de um recurso de instrução pai que possui conjuntos de resultados implícitos do Oracle Database
- oci_lob_copy — Copia objeto grande
- oci_lob_is_equal — Compara dois localizadores LOB/FILE para igualdade
- oci_new_collection — Aloca novo objeto de coleção
- oci_new_connect — Conecta-se ao servidor Oracle usando uma conexão exclusiva
- oci_new_cursor — Aloca e retorna um novo cursor (identificador de instrução)
- oci_new_descriptor — Inicializa um novo descritor LOB ou FILE vazio
- oci_num_fields — Retorna o número de colunas de resultados em uma instrução
- oci_num_rows — Retorna o número de linhas afetadas durante a execução da instrução
- oci_parse — Prepara uma instrução Oracle para execução
- oci_password_change — Altera a senha do usuário do Oracle
- oci_pconnect — Conecta-se a um banco de dados Oracle usando uma conexão persistente
- oci_register_taf_callback — Registra uma função de retorno definida pelo usuário para o TAF do Oracle Database
- oci_result — Retorna o valor do campo da linha recuperada
- oci_rollback — Reverte a transação pendente do banco de dados
- oci_server_version — Retorna a versão do banco de dados Oracle
- oci_set_action — Define o nome da ação
- oci_set_call_timeout — Sets a millisecond timeout for database calls
- oci_set_client_identifier — Define o identificador do cliente
- oci_set_client_info — Define as informações do cliente
- oci_set_db_operation — Define a operação do banco de dados
- oci_set_edition — Define a edição do banco de dados
- oci_set_module_name — Define o nome do módulo
- oci_set_prefetch — Define o número de linhas a serem pré-buscadas pelas consultas
- oci_set_prefetch_lob — Define a quantidade de dados pré-buscados para cada CLOB ou BLOB
- oci_statement_type — Retorna o tipo de uma instrução
- oci_unregister_taf_callback — Cancelar o registro de uma função de retorno definida pelo usuário para o TAF do Oracle Database

# The OCICollection class

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

## Introdução

Funcionalidade OCI8 Collection.

> Nota:

> A classe OCI-Collection foi renomeada para OCICollection no PHP 8 e OCI8 3.0.0 para adequação aos padrões de nomes do PHP.

## Resumo da classe

class OCICollection {
/* Métodos */
public function append(string `$value`): bool
public function assign(OCICollection `$from`): bool
public function assignElem(int `$index`, string `$value`): bool
public function free(): bool
public function getElem(int `$index`): string|float|null|false
public function max(): int|false
public function size(): int|false
public function trim(int `$num`): bool
}

# OCICollection::append

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::append — Adiciona elemento à coleção

### Descrição

public function OCICollection::append(string `$value`): bool

Acrescenta elemento ao final da coleção.

### Parâmetros

`value`

  O valor a ser adicionado à coleção.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Collection foi renomeada para OCICollection para se alinhar aos padrões de nomenclatura PHP.

### Veja Também

- OCICollection::assign

# OCICollection::assign

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::assign — Atribui um valor de outra coleção existente a esta coleção

### Descrição

public function OCICollection::assign(OCICollection `$from`): bool

Atribui um valor à coleção de outra coleção previamente criada. Ambas as coleções devem ser criadas com oci_new_collection() antes de serem usadas.

### Parâmetros

`from`

  Uma instância de OCICollection.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Collection foi renomeada para OCICollection para se alinhar aos padrões de nomenclatura PHP.

### Veja Também

- OCICollection::append

# OCICollection::assignElem

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::assignElem — Atribui um valor ao elemento da coleção

### Descrição

public function OCICollection::assignElem(int `$index`, string `$value`): bool

Atribui um valor ao elemento com índice `index`.

### Parâmetros

`index`

  O índice do elemento. O primeiro índice é 0.

`value`

  Pode ser uma string ou um número.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Collection foi renomeada para OCICollection para se alinhar aos padrões de nomenclatura PHP.

### Veja Também

- OCICollection::getElem

# OCICollection::free

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::free — Libera os recursos associados ao objeto de coleção

### Descrição

public function OCICollection::free(): bool

Libera os recursos associados ao objeto de coleção.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Collection foi renomeada para OCICollection para se alinhar aos padrões de nomenclatura PHP.

### Veja Também

- oci_new_collection

# OCICollection::getElem

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::getElem — Retorna o valor do elemento

### Descrição

public function OCICollection::getElem(int `$index`): string|float|null|false

Retorna o valor do elemento com o índice `index` (base 0).

### Parâmetros

`index`

  O índice do elemento. O primeiro índice é 0.

### Valor Retornado

Retorna `false` se tal elemento não existir; `null` se o elemento for `null` string se o elemento for uma coluna de um tipo de dado string ou número se o elemento for campo numérico.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Collection foi renomeada para OCICollection para se alinhar aos padrões de nomenclatura PHP.

### Veja Também

- OCICollection::assignElem

# OCICollection::max

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::max — Retorna o número máximo de elementos na coleção

### Descrição

public function OCICollection::max(): int|false

Retorna o número máximo de elementos na coleção.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número máximo como um inteiro ou `false` em caso de erros.

Se o valor retornado for 0, o número de elementos não será limitado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Collection foi renomeada para OCICollection para se alinhar aos padrões de nomenclatura PHP.

### Veja Também

- OCICollection::size

# OCICollection::size

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::size — Retorna o tamanho da coleção

### Descrição

public function OCICollection::size(): int|false

Retorna o tamanho da coleção.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número de elementos na coleção ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Collection foi renomeada para OCICollection para se alinhar aos padrões de nomenclatura PHP.

### Veja Também

- OCICollection::max

# OCICollection::trim

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::trim — Corta elementos do final da coleção

### Descrição

public function OCICollection::trim(int `$num`): bool

Corta `num` elementos do final da coleção.

### Parâmetros

`num`

  O número de elementos a serem cortados.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Collection foi renomeada para OCICollection para se alinhar aos padrões de nomenclatura PHP.

### Veja Também

- OCICollection::size

## Índice

- OCICollection::append — Adiciona elemento à coleção
- OCICollection::assign — Atribui um valor de outra coleção existente a esta coleção
- OCICollection::assignElem — Atribui um valor ao elemento da coleção
- OCICollection::free — Libera os recursos associados ao objeto de coleção
- OCICollection::getElem — Retorna o valor do elemento
- OCICollection::max — Retorna o número máximo de elementos na coleção
- OCICollection::size — Retorna o tamanho da coleção
- OCICollection::trim — Corta elementos do final da coleção

# A classe OCILob

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

## Introdução

Funcionalidade OCI8 LOB para objetos binários (BLOB) e caracteres (CLOB) grandes.

> Nota:

> A classe OCI-Lob foi renomeada para OCILob no PHP 8 e PECL OCI8 3.0.0 para adequação ao padrão de nomes do PHP.

## Resumo da classe

class OCILob {
/* Métodos */
public function append(OCILob `$from`): bool
public function close(): bool
public function eof(): bool
public function erase(?int `$offset` = `null`, ?int `$length` = `null`): int|false
public function export(string `$filename`, ?int `$offset` = `null`, ?int `$length` = `null`): bool
public function flush(int `$flag` = 0): bool
public function free(): bool
public function getBuffering(): bool
public function import(string `$filename`): bool
public function load(): string|false
public function read(int `$length`): string|false
public function rewind(): bool
public function save(string `$data`, int `$offset` = 0): bool
public function seek(int `$offset`, int `$whence` = `OCI_SEEK_SET`): bool
public function setBuffering(bool `$mode`): bool
public function size(): int|false
public function tell(): int|false
public function truncate(int `$length` = 0): bool
public function write(string `$data`, ?int `$length` = `null`): int|false
public function writeTemporary(string `$data`, int `$type` = `OCI_TEMP_CLOB`): bool
}

# OCILob::append

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::append — Acrescenta dados do objeto grande a outro objeto grande

### Descrição

public function OCILob::append(OCILob `$from`): bool

Acrescenta dados do objeto grande ao final de outro objeto grande.

Escrever no objeto grande com este método falhará se o buffer foi habilitado anteriormente. Deve-se desabilitar o buffer antes de anexar. Pode ser necessário liberar os buffers com OCILob::flush antes de desabilitar o buffer.

### Parâmetros

`from`

  O LOB copiado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Lob foi renomeada para OCILob para se alinhar aos padrões de nomenclatura PHP.

### Veja Também

- OCILob::flush
- OCILob::setBuffering
- OCILob::getBuffering

# OCILob::close

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::close — Fecha o descritor LOB

### Descrição

public function OCILob::close(): bool

Fecha o descritor de LOB ou de arquivo. Esta função deve ser usada somente com OCILob::writeTemporary.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Lob foi renomeada para OCILob para se alinhar aos padrões de nomenclatura PHP.

### Veja Também

- OCILob::writeTemporary

# OCILob::eof

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::eof — Testa o fim de arquivo no descritor de um objeto grande

### Descrição

public function OCILob::eof(): bool

Informa se o ponteiro interno do objeto grande está no final do LOB.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se o ponteiro interno do objeto grande estiver no final do LOB. Caso contrário, retorna `false`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Lob foi renomeada para OCILob para se alinhar aos padrões de nomenclatura PHP.

### Notas

> Nota:

> Esta função retornará um erro Oracle se OCILob::setBuffering estiver habilitado no LOB.

### Veja Também

- OCILob::size

# OCILob::erase

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::erase — Apaga uma parte especificada dos dados internos do LOB

### Descrição

public function OCILob::erase(?int `$offset` = `null`, ?int `$length` = `null`): int|false

Apaga uma porção especificada dos dados internos do LOB começando em uma posição especificada em `offset`. Se chamado sem parâmetros, ele apaga todos os dados LOB.

Para BLOBs, apagar significa que o valor LOB existente é sobrescrito com bytes zero. Para CLOBs, o valor LOB existente é sobrescrito com espaços.

### Parâmetros

`offset`

`length`

### Valor Retornado

Retorna o número real de caracteres/bytes apagados ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | `offset` e `length` agora são anuláveis.
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Lob foi renomeada para OCILob para se alinhar aos padrões de nomenclatura PHP.

### Veja Também

- OCILob::truncate

# OCILob::export

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::export — Exporta o conteúdo do LOB para um arquivo

### Descrição

public function OCILob::export(string `$filename`, ?int `$offset` = `null`, ?int `$length` = `null`): bool

Exporta o conteúdo do LOB para um arquivo.

### Parâmetros

`filename`

  Caminho para o arquivo.

`offset`

  Indica de onde a exportação deve começar.

`length`

  Indica o comprimento dos dados a serem exportados.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | `offset` e `length` agora são anuláveis.
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Lob foi renomeada para OCILob para se alinhar aos padrões de nomenclatura PHP.

### Veja Também

- OCILob::import

# OCILob::flush

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::flush — Libera/grava o buffer do LOB no servidor

### Descrição

public function OCILob::flush(int `$flag` = 0): bool

OCILob::flush() realmente grava dados no servidor.

### Parâmetros

`flag`

  Por padrão, os recursos não são liberados, mas usando o sinalizador `OCI_LOB_BUFFER_FREE` isso pode ser feito explicitamente. Deve-se ter certeza do que se está fazendo - a próxima operação de leitura/gravação para a mesma parte do LOB envolverá uma viagem de ida e volta para o servidor e inicializará novos recursos de buffer. É recomendado usar o sinalizador `OCI_LOB_BUFFER_FREE` somente quando não haverá mais trabalho com o LOB.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

Retorna `false` se o buffer não foi habilitado ou ocorreu um erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Lob foi renomeada para OCILob para se alinhar aos padrões de nomenclatura PHP.

### Veja Também

- OCILob::getBuffering
- OCILob::setBuffering

# OCILob::free

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::free — Libera recursos associados ao descritor do LOB

### Descrição

public function OCILob::free(): bool

Libera recursos associados ao descritor, previamente alocados com oci_new_descriptor().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Lob foi renomeada para OCILob para se alinhar aos padrões de nomenclatura PHP.

# OCILob::getBuffering

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::getBuffering — Retorna o estado atual de buffer para o objeto grande

### Descrição

public function OCILob::getBuffering(): bool

Informa se o buffer para o objeto grande está ativado ou desativado.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `false` se o buffer para o objeto grande estiver desativado e `true` se o buffer for usado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Lob foi renomeada para OCILob para se alinhar aos padrões de nomenclatura PHP.

### Veja Também

- OCILob::setBuffering

# OCILob::import

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::import — Importa dados de arquivo para o LOB

### Descrição

public function OCILob::import(string `$filename`): bool

Grava dados do arquivo em `filename` na posição atual do objeto grande.

### Parâmetros

`filename`

  Caminho para o arquivo.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Lob foi renomeada para OCILob para se alinhar aos padrões de nomenclatura PHP.

### Veja Também

- OCILob::export
- OCILob::write

# OCILob::load

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::load — Retorna o conteúdo de um objeto grande

### Descrição

public function OCILob::load(): string|false

Retorna o conteúdo do objeto grande. Como a execução do script é encerrada quando o limite de memória definido em memory_limit é atingido, garanta que o LOB não exceda esse limite. Na maioria dos casos, é recomendado usar OCILob::read em vez disso.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o conteúdo do objeto, ou `false` em caso de erros.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Lob foi renomeada para OCILob para se alinhar aos padrões de nomenclatura PHP.

### Veja Também

- OCILob::read

# OCILob::read

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::read — Lê parte do objeto grande

### Descrição

public function OCILob::read(int `$length`): string|false

Lê o número de bytes (BLOB) ou caracteres (CLOB) especificado em `length` a partir da posição atual do ponteiro interno do LOB.

A leitura para quando `length` bytes foram lidos para um BLOB, quando `length` caracteres foram lidos para um CLOB, ou quando o fim do objeto grande é alcançado. O ponteiro interno do objeto grande será deslocado na quantidade de bytes/caracteres lidos.

### Parâmetros

`length`

  O comprimento dos dados a serem lidos, em bytes (BLOB) ou caracteres (CLOB). Valores grandes serão arredondados para 1 MB.

### Valor Retornado

Retorna o conteúdo como uma string, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Lob foi renomeada para OCILob para se alinhar aos padrões de nomenclatura PHP.

### Veja Também

- OCILob::load
- OCILob::write

# OCILob::rewind

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::rewind — Move o ponteiro interno para o início do objeto grande

### Descrição

public function OCILob::rewind(): bool

Define o ponteiro interno para o início do objeto grande.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Lob foi renomeada para OCILob para se alinhar aos padrões de nomenclatura PHP.

### Veja Também

- OCILob::seek
- OCILob::tell

# OCILob::save

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::save — Salva dados no objeto grande

### Descrição

public function OCILob::save(string `$data`, int `$offset` = 0): bool

Salva os dados informados em `data` no objeto grande.

### Parâmetros

`data`

  Os dados a serem salvos.

`offset`

  Pode ser usado para indicar a posição de início no objeto grande.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Lob foi renomeada para OCILob para se alinhar aos padrões de nomenclatura PHP.

### Veja Também

- OCILob::write
- OCILob::import

# OCILob::saveFile

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::saveFile — Sinônimo de OCILob::import()

### Descrição

Esta função é um apelido para: OCILob::import().

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Lob foi renomeada para OCILob para se alinhar aos padrões de nomenclatura PHP.

# OCILob::seek

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::seek — Define o ponteiro interno do objeto grande

### Descrição

public function OCILob::seek(int `$offset`, int `$whence` = `OCI_SEEK_SET`): bool

Define o ponteiro interno do objeto grande.

### Parâmetros

`offset`

  Indica a quantidade de bytes, na qual o ponteiro interno deve ser movido a partir da posição apontada por `whence`.

`whence`

  Pode ser um dos seguintes:

  - `OCI_SEEK_SET` - define a posição igual a `offset`
  - `OCI_SEEK_CUR` - adiciona `offset` bytes à posição atual
  - `OCI_SEEK_END` - adiciona `offset` bytes ao final do objeto grande (use valor negativo para mover para uma posição antes do fim do objeto grande)

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Lob foi renomeada para OCILob para se alinhar aos padrões de nomenclatura PHP.

### Veja Também

- OCILob::rewind
- OCILob::tell
- OCILob::eof

# OCILob::setBuffering

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::setBuffering — Altera o estado atual do buffer para o objeto grande

### Descrição

public function OCILob::setBuffering(bool `$mode`): bool

Define o buffer para o objeto grande, dependendo do valor do modo informado no parâmetro `mode`.

O uso desta função pode fornecer melhorias de desempenho ao armazenar em buffer pequenas leituras e gravações de LOBs, reduzindo o número de viagens de ida e volta da rede e versões de LOB. OCILob::flush() deve ser usado para liberar buffers, quando tiver terminado o trabalho com o objeto grande.

### Parâmetros

`mode`

  `true` para ligado e `false` para desligado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha. Chamadas repetidas para este método com o mesmo sinalizador retornarão `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Lob foi renomeada para OCILob para se alinhar aos padrões de nomenclatura PHP.

### Veja Também

- OCILob::getBuffering

# OCILob::size

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::size — Retorna o tamanho do objeto grande

### Descrição

public function OCILob::size(): int|false

Obtém o tamanho do objeto grande.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o comprimento do valor do objeto grande ou `false` em caso de falha. Objetos vazios têm comprimento zero.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Lob foi renomeada para OCILob para se alinhar aos padrões de nomenclatura PHP.

# OCILob::tell

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::tell — Retorna a posição atual do ponteiro interno do objeto grande

### Descrição

public function OCILob::tell(): int|false

Obtém a posição atual do ponteiro interno de um LOB.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a posição atual do ponteiro interno de um LOB ou `false` se um erro ocorreu.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Lob foi renomeada para OCILob para se alinhar aos padrões de nomenclatura PHP.

### Veja Também

- OCILob::rewind
- OCILob::size
- OCILob::eof

# OCILob::truncate

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::truncate — Trunca objeto grande

### Descrição

public function OCILob::truncate(int `$length` = 0): bool

Trunca o LOB.

### Parâmetros

`length`

  Se fornecido, este método truncará o LOB para `length` bytes. Caso contrário, ele irá limpar completamente o LOB.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Lob foi renomeada para OCILob para se alinhar aos padrões de nomenclatura PHP.

### Veja Também

- OCILob::erase

# OCILob::write

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::write — Grava dados no objeto grande

### Descrição

public function OCILob::write(string `$data`, ?int `$length` = `null`): int|false

Grava dados do parâmetro `data` na posição atual do ponteiro interno do LOB.

### Parâmetros

`data`

  Os dados a serem gravados no LOB.

`length`

  Se este parâmetro for um inteiro, a escrita será interrompida após `length` bytes terem sido escritos ou o fim de `data` for atingido, o que ocorrer primeiro.

### Valor Retornado

Retorna o número de bytes gravados ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | `length` agora é anulável.
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Lob foi renomeada para OCILob para se alinhar aos padrões de nomenclatura PHP.

### Veja Também

- OCILob::read

# OCILob::writeTemporary

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::writeTemporary — Grava um objeto grande temporário

### Descrição

public function OCILob::writeTemporary(string `$data`, int `$type` = `OCI_TEMP_CLOB`): bool

Cria um objeto grande temporário e grava os dados do parâmetro `data` nele.

Deve ser usado OCILob::close quando o trabalho com esse objeto tiver terminado.

### Parâmetros

`data`

  Os dados a serem gravados.

`type`

  Pode ser um dos seguintes:

  - `OCI_TEMP_BLOB` é utilizado para criar BLOBs temporários
  - `OCI_TEMP_CLOB` é utilizado para criar CLOBs temporários

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Lob foi renomeada para OCILob para conformidade com padrões do PHP.

### Veja Também

- OCILob::close

# OCILob::writeToFile

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::writeToFile — Sinônimo de OCILob::export()

### Descrição

Esta função é um apelido para: OCILob::export().

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0, PECL OCI8 3.0.0 | `offset` e `length` agora são anuláveis.
8.0.0, PECL OCI8 3.0.0 | A classe OCI-Lob foi renomeada para OCILob para se alinhar aos padrões de nomenclatura PHP.

## Índice

- OCILob::append — Acrescenta dados do objeto grande a outro objeto grande
- OCILob::close — Fecha o descritor LOB
- OCILob::eof — Testa o fim de arquivo no descritor de um objeto grande
- OCILob::erase — Apaga uma parte especificada dos dados internos do LOB
- OCILob::export — Exporta o conteúdo do LOB para um arquivo
- OCILob::flush — Libera/grava o buffer do LOB no servidor
- OCILob::free — Libera recursos associados ao descritor do LOB
- OCILob::getBuffering — Retorna o estado atual de buffer para o objeto grande
- OCILob::import — Importa dados de arquivo para o LOB
- OCILob::load — Retorna o conteúdo de um objeto grande
- OCILob::read — Lê parte do objeto grande
- OCILob::rewind — Move o ponteiro interno para o início do objeto grande
- OCILob::save — Salva dados no objeto grande
- OCILob::saveFile — Sinônimo de OCILob::import
- OCILob::seek — Define o ponteiro interno do objeto grande
- OCILob::setBuffering — Altera o estado atual do buffer para o objeto grande
- OCILob::size — Retorna o tamanho do objeto grande
- OCILob::tell — Retorna a posição atual do ponteiro interno do objeto grande
- OCILob::truncate — Trunca objeto grande
- OCILob::write — Grava dados no objeto grande
- OCILob::writeTemporary — Grava um objeto grande temporário
- OCILob::writeToFile — Sinônimo de OCILob::export

# Funções e sinônimos e obsoletos do OCI8

# oci_internal_debug

(PHP 5, PHP 7, PECL OCI8 >= 1.1.0, PECL OCI8 <= 2.2.0)

oci_internal_debug — Habilita ou desabilita a saíde interna de depuração

### Descrição

function oci_internal_debug(bool `$onoff`): void

Habilita ou desabilita a saíde interna de depuração.

### Parâmetros

`onoff`

  Defina para `false` para desligar a saída de depuração ou `true` para ligá-la.

### Valor Retornado

Nenhum valor é retornado.

### Notas

> Nota:

> Esta função foi removida no PHP 8 e PECL OCI8 3.0.

# ocibindbyname

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocibindbyname — Sinônimo de oci_bind_by_name()

### Descrição

Sinônimo de oci_bind_by_name()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocicancel

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicancel — Sinônimo de oci_cancel()

### Descrição

Sinônimo de oci_cancel()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocicloselob

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PECL OCI8 1.0)

ocicloselob — Sinônimo de OCILob::close()

### Descrição

Sinônimo de OCILob::close()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocicollappend

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollappend — Sinônimo de OCICollection::append()

### Descrição

Sinônimo de OCICollection::append()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocicollassign

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PECL OCI8 >= 1.0.0)

ocicollassign — Sinônimo de OCICollection::assign()

### Descrição

Sinônimo de OCICollection::assign()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocicollassignelem

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollassignelem — Sinônimo de OCICollection::assignElem()

### Descrição

Sinônimo de OCICollection::assignElem()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocicollgetelem

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollgetelem — Sinônimo de OCICollection::getElem()

### Descrição

Sinônimo de OCICollection::getElem()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocicollmax

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollmax — Sinônimo de OCICollection::max()

### Descrição

Sinônimo de OCICollection::max()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocicollsize

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollsize — Sinônimo de OCICollection::size()

### Descrição

Sinônimo de OCICollection::size()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocicolltrim

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolltrim — Sinônimo de OCICollection::trim()

### Descrição

Sinônimo de OCICollection::trim()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocicolumnisnull

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnisnull — Sinônimo de oci_field_is_null()

### Descrição

Sinônimo de oci_field_is_null()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocicolumnname

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnname — Sinônimo de oci_field_name()

### Descrição

Sinônimo de oci_field_name()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocicolumnprecision

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnprecision — Sinônimo de oci_field_precision()

### Descrição

Sinônimo de oci_field_precision()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocicolumnscale

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnscale — Sinônimo de oci_field_scale()

### Descrição

Sinônimo de oci_field_scale()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocicolumnsize

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnsize — Sinônimo de oci_field_size()

### Descrição

Sinônimo de oci_field_size()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocicolumntype

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumntype — Sinônimo de oci_field_type()

### Descrição

Sinônimo de oci_field_type()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocicolumntyperaw

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumntyperaw — Sinônimo de oci_field_type_raw()

### Descrição

Sinônimo de oci_field_type_raw()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocicommit

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicommit — Sinônimo de oci_commit()

### Descrição

Sinônimo de oci_commit()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocidefinebyname

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocidefinebyname — Sinônimo de oci_define_by_name()

### Descrição

Sinônimo de oci_define_by_name()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocierror

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocierror — Sinônimo de oci_error()

### Descrição

Sinônimo de oci_error()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ociexecute

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociexecute — Sinônimo de oci_execute()

### Descrição

Sinônimo de oci_execute()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocifetch

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifetch — Sinônimo de oci_fetch()

### Descrição

Sinônimo de oci_fetch()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocifetchinto

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifetchinto — Variante obsoleta de oci_fetch_array(), oci_fetch_object(), oci_fetch_assoc() e oci_fetch_row()

### Descrição

Variante obsoleta de oci_fetch_array(), oci_fetch_object(), oci_fetch_assoc() e oci_fetch_row()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocifetchstatement

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifetchstatement — Sinônimo de oci_fetch_all()

### Descrição

Sinônimo de oci_fetch_all()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocifreecollection

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreecollection — Sinônimo de OCICollection::free()

### Descrição

Sinônimo de OCICollection::free()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocifreecursor

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreecursor — Sinônimo de oci_free_statement()

### Descrição

Sinônimo de oci_free_statement()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocifreedesc

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreedesc — Sinônimo de OCILob::free()

### Descrição

Sinônimo de OCILob::free()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocifreestatement

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreestatement — Sinônimo de oci_free_statement()

### Descrição

Sinônimo de oci_free_statement()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ociinternaldebug

(PHP 4, PHP 5, PHP 7, PECL OCI8 >= 1.0.0, PECL OCI8 <= 2.2.0)

ociinternaldebug — Sinônimo de oci_internal_debug()

### Descrição

Sinônimo de oci_internal_debug()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ociloadlob

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociloadlob — Sinônimo de OCILob::load()

### Descrição

Sinônimo de OCILob::load()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocilogoff

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocilogoff — Sinônimo de oci_close()

### Descrição

Sinônimo de oci_close()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocilogon

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocilogon — Sinônimo de oci_connect()

### Descrição

Sinônimo de oci_connect()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocinewcollection

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinewcollection — Sinônimo de oci_new_collection()

### Descrição

Sinônimo de oci_new_collection()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocinewcursor

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinewcursor — Sinônimo de oci_new_cursor()

### Descrição

Sinônimo de oci_new_cursor()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocinewdescriptor

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinewdescriptor — Sinônimo de oci_new_descriptor()

### Descrição

Sinônimo de oci_new_descriptor()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocinlogon

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinlogon — Sinônimo de oci_new_connect()

### Descrição

Sinônimo de oci_new_connect()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocinumcols

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinumcols — Sinônimo de oci_num_fields()

### Descrição

Sinônimo de oci_num_fields()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ociparse

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociparse — Sinônimo de oci_parse()

### Descrição

Sinônimo de oci_parse()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ociplogon

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociplogon — Sinônimo de oci_pconnect()

### Descrição

Sinônimo de oci_pconnect()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ociresult

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociresult — Sinônimo de oci_result()

### Descrição

Sinônimo de oci_result()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocirollback

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocirollback — Sinônimo de oci_rollback()

### Descrição

Sinônimo de oci_rollback()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocirowcount

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocirowcount — Sinônimo de oci_num_rows()

### Descrição

Sinônimo de oci_num_rows()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocisavelob

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocisavelob — Sinônimo de OCILob::save()

### Descrição

Sinônimo de OCILob::save()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocisavelobfile

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocisavelobfile — Sinônimo de OCILob::import()

### Descrição

Sinônimo de OCILob::import()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ociserverversion

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociserverversion — Sinônimo de oci_server_version()

### Descrição

Sinônimo de oci_server_version()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocisetprefetch

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocisetprefetch — Sinônimo de oci_set_prefetch()

### Descrição

Sinônimo de oci_set_prefetch()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ocistatementtype

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocistatementtype — Sinônimo de oci_statement_type()

### Descrição

Sinônimo de oci_statement_type()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ociwritelobtofile

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociwritelobtofile — Sinônimo de OCILob::export()

### Descrição

Sinônimo de OCILob::export()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

# ociwritetemporarylob

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PECL OCI8 1.0)

ociwritetemporarylob — Sinônimo de OCILob::writeTemporary()

### Descrição

Sinônimo de OCILob::writeTemporary()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 5.4.0. O uso deste apelido é fortemente desencorajado.

## Índice

- oci_internal_debug — Habilita ou desabilita a saíde interna de depuração
- ocibindbyname — Sinônimo de oci_bind_by_name
- ocicancel — Sinônimo de oci_cancel
- ocicloselob — Sinônimo de OCILob::close
- ocicollappend — Sinônimo de OCICollection::append
- ocicollassign — Sinônimo de OCICollection::assign
- ocicollassignelem — Sinônimo de OCICollection::assignElem
- ocicollgetelem — Sinônimo de OCICollection::getElem
- ocicollmax — Sinônimo de OCICollection::max
- ocicollsize — Sinônimo de OCICollection::size
- ocicolltrim — Sinônimo de OCICollection::trim
- ocicolumnisnull — Sinônimo de oci_field_is_null
- ocicolumnname — Sinônimo de oci_field_name
- ocicolumnprecision — Sinônimo de oci_field_precision
- ocicolumnscale — Sinônimo de oci_field_scale
- ocicolumnsize — Sinônimo de oci_field_size
- ocicolumntype — Sinônimo de oci_field_type
- ocicolumntyperaw — Sinônimo de oci_field_type_raw
- ocicommit — Sinônimo de oci_commit
- ocidefinebyname — Sinônimo de oci_define_by_name
- ocierror — Sinônimo de oci_error
- ociexecute — Sinônimo de oci_execute
- ocifetch — Sinônimo de oci_fetch
- ocifetchinto — Variante obsoleta de oci_fetch_array, oci_fetch_object, oci_fetch_assoc e oci_fetch_row
- ocifetchstatement — Sinônimo de oci_fetch_all
- ocifreecollection — Sinônimo de OCICollection::free
- ocifreecursor — Sinônimo de oci_free_statement
- ocifreedesc — Sinônimo de OCILob::free
- ocifreestatement — Sinônimo de oci_free_statement
- ociinternaldebug — Sinônimo de oci_internal_debug
- ociloadlob — Sinônimo de OCILob::load
- ocilogoff — Sinônimo de oci_close
- ocilogon — Sinônimo de oci_connect
- ocinewcollection — Sinônimo de oci_new_collection
- ocinewcursor — Sinônimo de oci_new_cursor
- ocinewdescriptor — Sinônimo de oci_new_descriptor
- ocinlogon — Sinônimo de oci_new_connect
- ocinumcols — Sinônimo de oci_num_fields
- ociparse — Sinônimo de oci_parse
- ociplogon — Sinônimo de oci_pconnect
- ociresult — Sinônimo de oci_result
- ocirollback — Sinônimo de oci_rollback
- ocirowcount — Sinônimo de oci_num_rows
- ocisavelob — Sinônimo de OCILob::save
- ocisavelobfile — Sinônimo de OCILob::import
- ociserverversion — Sinônimo de oci_server_version
- ocisetprefetch — Sinônimo de oci_set_prefetch
- ocistatementtype — Sinônimo de oci_statement_type
- ociwritelobtofile — Sinônimo de OCILob::export
- ociwritetemporarylob — Sinônimo de OCILob::writeTemporary

- Instalação/Configuração
  - Dependências
  - Instalação
  - Testando
  - Configurações em Execução
- Constantes predefinidas
- Exemplos
- Manipulação e conjunto de conexões do OCI8
- Suporte à Notificação Rápida de Aplicação (FAN) do OCI8
- Suporte ao OCI8 Transparent Application Failover (TAF)
- OCI8 e Rastreamento dinâmico DTrace
- Tipos de dados suportados
- Funções OCI8
  - oci_bind_array_by_name — Vincula um array PHP a um parâmetro de array Oracle PL/SQL
  - oci_bind_by_name — Vincula uma variável PHP a um marcador Oracle
  - oci_cancel — Cancela a leitura do cursor
  - oci_client_version — Retorna a versão da biblioteca do cliente Oracle
  - oci_close — Fecha uma conexão Oracle
  - oci_commit — Confirma a transação de banco de dados pendente
  - oci_connect — Conecta-se a um banco de dados Oracle
  - oci_define_by_name — Associa uma variável PHP a uma coluna para buscas de consulta
  - oci_error — Retorna o último erro encontrado
  - oci_execute — Executa uma instrução
  - oci_fetch — Busca a próxima linha de uma consulta em buffers internos
  - oci_fetch_all — Busca várias linhas de uma consulta em um array bidimensional
  - oci_fetch_array — Retorna a próxima linha de uma consulta como um array associativo ou numérico
  - oci_fetch_assoc — Retorna a próxima linha de uma consulta como um array associativo
  - oci_fetch_object — Retorna a próxima linha de uma consulta como um objeto
  - oci_fetch_row — Retorna a próxima linha de uma consulta como um array numérico
  - oci_field_is_null — Verifica se um campo na linha atualmente buscada é null
  - oci_field_name — Retorna o nome de um campo da instrução
  - oci_field_precision — Informa a precisão de um campo
  - oci_field_scale — Informa a escala do campo
  - oci_field_size — Retorna o tamanho do campo
  - oci_field_type — Retorna o nome do tipo de dados de um campo
  - oci_field_type_raw — Informa o tipo bruto de dados do Oracle de um campo
  - oci_free_descriptor — Libera um descritor
  - oci_free_statement — Libera todos os recursos associados à instrução ou cursor
  - oci_get_implicit_resultset — Retorna o próximo recurso de instrução filho de um recurso de instrução pai que possui conjuntos de resultados implícitos do Oracle Database
  - oci_lob_copy — Copia objeto grande
  - oci_lob_is_equal — Compara dois localizadores LOB/FILE para igualdade
  - oci_new_collection — Aloca novo objeto de coleção
  - oci_new_connect — Conecta-se ao servidor Oracle usando uma conexão exclusiva
  - oci_new_cursor — Aloca e retorna um novo cursor (identificador de instrução)
  - oci_new_descriptor — Inicializa um novo descritor LOB ou FILE vazio
  - oci_num_fields — Retorna o número de colunas de resultados em uma instrução
  - oci_num_rows — Retorna o número de linhas afetadas durante a execução da instrução
  - oci_parse — Prepara uma instrução Oracle para execução
  - oci_password_change — Altera a senha do usuário do Oracle
  - oci_pconnect — Conecta-se a um banco de dados Oracle usando uma conexão persistente
  - oci_register_taf_callback — Registra uma função de retorno definida pelo usuário para o TAF do Oracle Database
  - oci_result — Retorna o valor do campo da linha recuperada
  - oci_rollback — Reverte a transação pendente do banco de dados
  - oci_server_version — Retorna a versão do banco de dados Oracle
  - oci_set_action — Define o nome da ação
  - oci_set_call_timeout — Sets a millisecond timeout for database calls
  - oci_set_client_identifier — Define o identificador do cliente
  - oci_set_client_info — Define as informações do cliente
  - oci_set_db_operation — Define a operação do banco de dados
  - oci_set_edition — Define a edição do banco de dados
  - oci_set_module_name — Define o nome do módulo
  - oci_set_prefetch — Define o número de linhas a serem pré-buscadas pelas consultas
  - oci_set_prefetch_lob — Define a quantidade de dados pré-buscados para cada CLOB ou BLOB
  - oci_statement_type — Retorna o tipo de uma instrução
  - oci_unregister_taf_callback — Cancelar o registro de uma função de retorno definida pelo usuário para o TAF do Oracle Database
- OCICollection — The OCICollection class
  - OCICollection::append — Adiciona elemento à coleção
  - OCICollection::assign — Atribui um valor de outra coleção existente a esta coleção
  - OCICollection::assignElem — Atribui um valor ao elemento da coleção
  - OCICollection::free — Libera os recursos associados ao objeto de coleção
  - OCICollection::getElem — Retorna o valor do elemento
  - OCICollection::max — Retorna o número máximo de elementos na coleção
  - OCICollection::size — Retorna o tamanho da coleção
  - OCICollection::trim — Corta elementos do final da coleção
- OCILob — A classe OCILob
  - OCILob::append — Acrescenta dados do objeto grande a outro objeto grande
  - OCILob::close — Fecha o descritor LOB
  - OCILob::eof — Testa o fim de arquivo no descritor de um objeto grande
  - OCILob::erase — Apaga uma parte especificada dos dados internos do LOB
  - OCILob::export — Exporta o conteúdo do LOB para um arquivo
  - OCILob::flush — Libera/grava o buffer do LOB no servidor
  - OCILob::free — Libera recursos associados ao descritor do LOB
  - OCILob::getBuffering — Retorna o estado atual de buffer para o objeto grande
  - OCILob::import — Importa dados de arquivo para o LOB
  - OCILob::load — Retorna o conteúdo de um objeto grande
  - OCILob::read — Lê parte do objeto grande
  - OCILob::rewind — Move o ponteiro interno para o início do objeto grande
  - OCILob::save — Salva dados no objeto grande
  - OCILob::saveFile — Sinônimo de OCILob::import
  - OCILob::seek — Define o ponteiro interno do objeto grande
  - OCILob::setBuffering — Altera o estado atual do buffer para o objeto grande
  - OCILob::size — Retorna o tamanho do objeto grande
  - OCILob::tell — Retorna a posição atual do ponteiro interno do objeto grande
  - OCILob::truncate — Trunca objeto grande
  - OCILob::write — Grava dados no objeto grande
  - OCILob::writeTemporary — Grava um objeto grande temporário
  - OCILob::writeToFile — Sinônimo de OCILob::export
- Funções e sinônimos e obsoletos do OCI8
  - oci_internal_debug — Habilita ou desabilita a saíde interna de depuração
  - ocibindbyname — Sinônimo de oci_bind_by_name
  - ocicancel — Sinônimo de oci_cancel
  - ocicloselob — Sinônimo de OCILob::close
  - ocicollappend — Sinônimo de OCICollection::append
  - ocicollassign — Sinônimo de OCICollection::assign
  - ocicollassignelem — Sinônimo de OCICollection::assignElem
  - ocicollgetelem — Sinônimo de OCICollection::getElem
  - ocicollmax — Sinônimo de OCICollection::max
  - ocicollsize — Sinônimo de OCICollection::size
  - ocicolltrim — Sinônimo de OCICollection::trim
  - ocicolumnisnull — Sinônimo de oci_field_is_null
  - ocicolumnname — Sinônimo de oci_field_name
  - ocicolumnprecision — Sinônimo de oci_field_precision
  - ocicolumnscale — Sinônimo de oci_field_scale
  - ocicolumnsize — Sinônimo de oci_field_size
  - ocicolumntype — Sinônimo de oci_field_type
  - ocicolumntyperaw — Sinônimo de oci_field_type_raw
  - ocicommit — Sinônimo de oci_commit
  - ocidefinebyname — Sinônimo de oci_define_by_name
  - ocierror — Sinônimo de oci_error
  - ociexecute — Sinônimo de oci_execute
  - ocifetch — Sinônimo de oci_fetch
  - ocifetchinto — Variante obsoleta de oci_fetch_array, oci_fetch_object, oci_fetch_assoc e oci_fetch_row
  - ocifetchstatement — Sinônimo de oci_fetch_all
  - ocifreecollection — Sinônimo de OCICollection::free
  - ocifreecursor — Sinônimo de oci_free_statement
  - ocifreedesc — Sinônimo de OCILob::free
  - ocifreestatement — Sinônimo de oci_free_statement
  - ociinternaldebug — Sinônimo de oci_internal_debug
  - ociloadlob — Sinônimo de OCILob::load
  - ocilogoff — Sinônimo de oci_close
  - ocilogon — Sinônimo de oci_connect
  - ocinewcollection — Sinônimo de oci_new_collection
  - ocinewcursor — Sinônimo de oci_new_cursor
  - ocinewdescriptor — Sinônimo de oci_new_descriptor
  - ocinlogon — Sinônimo de oci_new_connect
  - ocinumcols — Sinônimo de oci_num_fields
  - ociparse — Sinônimo de oci_parse
  - ociplogon — Sinônimo de oci_pconnect
  - ociresult — Sinônimo de oci_result
  - ocirollback — Sinônimo de oci_rollback
  - ocirowcount — Sinônimo de oci_num_rows
  - ocisavelob — Sinônimo de OCILob::save
  - ocisavelobfile — Sinônimo de OCILob::import
  - ociserverversion — Sinônimo de oci_server_version
  - ocisetprefetch — Sinônimo de oci_set_prefetch
  - ocistatementtype — Sinônimo de oci_statement_type
  - ociwritelobtofile — Sinônimo de OCILob::export
  - ociwritetemporarylob — Sinônimo de OCILob::writeTemporary

# PostgreSQL

# Introdução

O banco de dados PostgreSQL é um produto de código aberto e disponível gratuitamente. O Postgres, desenvolvido originalmente no Departamento de Ciência da Computação da Universidade da Califórnia em Berkeley, foi pioneiro em muitos dos conceitos objeto-relacionais que agora estão disponíveis em alguns bancos de dados comerciais. Fornece suporte à linguagem SQL92/SQL99, transações, integridade referencial, procedimentos armazenados e extensibilidade de tipos. O PostgreSQL é um descendente de código aberto do original desenvolvido em Berkeley.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução
- Tipos de Recurso

## Dependências

Para usar usar as funções para PostgreSQL, é necessária a libpq (a biblioteca cliente C do PostgreSQL). A partir do PHP 8.0.0, libpq 9.1 ou posterior é requerida. A partir do PHP 8.4.0, libpq 10.0 ou posterior é requerida. PostgreSQL suporta vários tipos de codificação de caracteres incluindo a codificação multibyte. Informação sobre a versão atual mais detalhes sobre PostgreSQL estão disponíveis em » http://www.postgresql.org/ e na » Documentação do PostgreSQL.

## Instalação

Para ativar o suporte ao PostgreSQL, --with-pgsql[=DIR] é necessário ao compilar o PHP. `DIR` é o diretório base de instalação do PostgreSQL, o padrão é /usr/local/pgsql. Se o módulo de objeto compartilhado estiver disponível, o módulo PostgreSQL poderá ser carregado usando a diretiva extension no php.ini ou função dl().

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de configuração PostgreSQL
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
pgsql.allow_persistent | "1" | `INI_SYSTEM` |
pgsql.max_persistent | "-1" | `INI_SYSTEM` |
pgsql.max_links | "-1" | `INI_SYSTEM` |
pgsql.auto_reset_persistent | "0" | `INI_SYSTEM` |
pgsql.ignore_notice | "0" | `INI_ALL` |
pgsql.log_notice | "0" | `INI_ALL` |

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`pgsql.allow_persistent` bool

  Define se serão permitidas conexões Postgres persistentes.

`pgsql.max_persistent` int

  O número máximo de conexões Postgres persistentes por processo.

`pgsql.max_links` int

  O número máximo de conexões Postgres por processo, incluindo conexões persistentes.

`pgsql.auto_reset_persistent` int

  Detecta conexões persistentes quebradas com pg_pconnect(). Precisa de um pequeno oberhead.

`pgsql.ignore_notice` int

  Define se as notas do processo interno do PostgreSQL devem ser ignoradas.

`pgsql.log_notice` int

  Define se as mensagens e notas do processo interno do PostgreSQL serão registradas. A diretiva do PHP pgsql.ignore_notice deve estar em "Off" para que as mensagens sejam registradas.

## Tipos de Recurso

Antes do PHP 8.1.0, havia dois tipos de recurso usados no módulo PostgreSQL. O primeiro é o identificador de conexão com o banco de dados, o segundo um recurso que guarda o resultado de uma consulta.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`PGSQL_LIBPQ_VERSION` (string)
  Versão curta da libpq, contendo apenas números e pontos.
`PGSQL_LIBPQ_VERSION_STR` (string)
  Antes do PHP 8.0.0, a versão longa da libpq que incluía informação de compilação. A partir do PHP 8.0.0, o valor é idêntico a `PGSQL_LIBPQ_VERSION`, e usar `PGSQL_LIBPQ_VERSION_STR` foi descontinuado.
`PGSQL_ASSOC` (int)
  Usada em pg_fetch_array(). Retorna um array associativo contendo nomes dos campos e valores.
`PGSQL_NUM` (int)
  Usada em pg_fetch_array(). Retorna um array com índice numérico contendo números dos campos e valores.
`PGSQL_BOTH` (int)
  Usada em pg_fetch_array(). Retorna um array dos valores do campos com índice numérico (por número do campo) e associativo (por nome do campo).
`PGSQL_CONNECT_FORCE_NEW` (int)
  Usado em pg_connect() para forçar a criação de nova conexão, ao invés de reutilizar uma conexão idêntica existente.
`PGSQL_CONNECT_ASYNC` (int)
  Passada para pg_connect() para criar uma conexão assíncrona.
`PGSQL_CONNECTION_AUTH_OK` (int)
`PGSQL_CONNECTION_AWAITING_RESPONSE` (int)
`PGSQL_CONNECTION_BAD` (int)
  Retornado pela pg_connection_status() indicando que a conexão com o banco de dados está em um estado inválido.
`PGSQL_CONNECTION_MADE` (int)
`PGSQL_CONNECTION_OK` (int)
  Retornado pela pg_connection_status() indicando que a conexão com o banco de dados está em um estado válido.
`PGSQL_CONNECTION_SETENV` (int)
`PGSQL_CONNECTION_SSL_STARTUP` (int)
`PGSQL_CONNECTION_STARTED` (int)
`PGSQL_SEEK_SET` (int)
  Passada para pg_lo_seek(). Operação de pesquisa deve iniciar a partir do início do objeto.
`PGSQL_SEEK_CUR` (int)
  Passada para pg_lo_seek(). Operação de pesquisa deve iniciar a partir da posição atual.
`PGSQL_SEEK_END` (int)
  Passada para pg_lo_seek(). Operação de pesquisa deve iniciar a partir do final do objeto.
`PGSQL_EMPTY_QUERY` (int)
  Retornado pela pg_result_status(). A string enviada para o servidor estava vazia.
`PGSQL_COMMAND_OK` (int)
  Retornado pela pg_result_status(). Conclusão bem sucedida de um comando que não retornou dados.
`PGSQL_TUPLES_OK` (int)
  Retornado pela pg_result_status().Conclusão bem sucedida de um retornando dados (como um `SELECT` ou `SHOW`).
`PGSQL_TUPLES_CHUNK` (int)
  Retornada por pg_result_status(). Indica o término bem sucedido de um comando que retorna dados em modo fragmentado. Retornada para instruções `SELECT` quando pg_set_chunked_rows_size() está definida. O conjunto de resultados é dividido em múltiplos fragmentos, cada um contendo um número predefinido de linhas. Disponível a partir do PHP 8.4.0 e libpq 17.
`PGSQL_COPY_OUT` (int)
  Retornado pela pg_result_status(). Transferência de dados "Copy Out" (do servidor) iniciada.
`PGSQL_COPY_IN` (int)
  Retornado pela pg_result_status(). Transferência de dados "Copy In" (para o servidor) iniciada.
`PGSQL_BAD_RESPONSE` (int)
  Retornado pela pg_result_status(). A resposta do servidor não foi entendida.
`PGSQL_NONFATAL_ERROR` (int)
  Retornado pela pg_result_status(). Um erro não fatal (uma nota ou alerta) ocorreu.
`PGSQL_FATAL_ERROR` (int)
  Retornado pela pg_result_status(). Um erro fatal ocorreu.
`PGSQL_TRANSACTION_IDLE` (int)
  Retornado pela pg_transaction_status(). Conexão está atualmente ociosa, não em uma transação.
`PGSQL_TRANSACTION_ACTIVE` (int)
  Retornado pela pg_transaction_status(). Um comando está em progresso na conexão. Uma consulta foi enviada pela conexão e ainda não foi concluída.
`PGSQL_TRANSACTION_INTRANS` (int)
  Retornado pela pg_transaction_status(). A conexão está ociosa, em um bloco de transação.
`PGSQL_TRANSACTION_INERROR` (int)
  Retornado pela pg_transaction_status(). A conexão está ociosa, em um bloco de transação com falha.
`PGSQL_TRANSACTION_UNKNOWN` (int)
  Retornado pela pg_transaction_status(). A conexão está ruim.
`PGSQL_DIAG_SEVERITY` (int)
  Passada para pg_result_error_field(). A severidade; os conteúdos dos campos são `ERROR`, `FATAL` ou `PANIC` (em uma mensagem de erro); ou `WARNING`, `NOTICE`, `DEBUG`, `INFO` ou `LOG` (em uma nota), ou uma tradução de um desses. Sempre presente.
`PGSQL_DIAG_SQLSTATE` (int)
  Passada para pg_result_error_field(). O código SQLSTATE do erro. O código SQLSTATE identifica o tipo do erro ocorrido; ele pode ser usado por aplicações front-end para executar operações específicas (como manipulação de erro) em resposta a um erro particular do banco de dados. Esta campo não muda com a localidade, e está sempre presente.
`PGSQL_DIAG_MESSAGE_PRIMARY` (int)
  Passada para pg_result_error_field(). A mensagem de erro legível primária (tipicamente uma linha). Sempre presente.
`PGSQL_DIAG_MESSAGE_DETAIL` (int)
  Passada para pg_result_error_field(). Detalhe: uma mensagem de erro secundária trazendo mais detalhes sobre o problema. Pode conter múltiplas linhas.
`PGSQL_DIAG_MESSAGE_HINT` (int)
  Passada para pg_result_error_field(). Dica: um sugestão opcional sobre o que fazer em relação ao problema. Tem a intenção de ser diferente da mensagem detalhada de forma a oferecer conselhos (potencialmente inapropriados) ao invés de fatos concretos. Pode conter múltiplas linhas.
`PGSQL_DIAG_STATEMENT_POSITION` (int)
  Passada para pg_result_error_field(). Uma string contendo um inteiro decimal indicando uma posição de cursor de erro como um índice da string da declaração original. O primeiro caractere tem índice 1, e as posições são medidas em caracteres, não em bytes.
`PGSQL_DIAG_INTERNAL_POSITION` (int)
  Passada para pg_result_error_field(). Esta é definida da mesma forma que o campo `PG_DIAG_STATEMENT_POSITION`, mas ela é usado quando a posição do cursor refere-se a um comando gerado internamente ao invés do enviado pelo cliente. O campo `PG_DIAG_INTERNAL_QUERY` irá sempre aparecer quando este campo aparecer.
`PGSQL_DIAG_INTERNAL_QUERY` (int)
  Passada para pg_result_error_field(). O texto do comando gerado internamente que falhou. Poderá ser, por exemplo, uma consulta SQL emitida por uma função PL/pgSQL.
`PGSQL_DIAG_CONTEXT` (int)
  Passada para pg_result_error_field(). Um indicador de contexto no qual o erro ocorreu. Atualmente isto inclui um restreamento de pilha de chamadas de funções de linguagem procedural ativas e consultas geradas internamente. O rastreamento é uma entrada por linha, a mais recente primeiro.
`PGSQL_DIAG_SOURCE_FILE` (int)
  Passada para pg_result_error_field(). O nome do arquivo da localização do código-fonte PostgreSQL onde o erro foi reportado.
`PGSQL_DIAG_SOURCE_LINE` (int)
  Passada para pg_result_error_field(). O número da linha da localização do código-fonte PostgreSQL onde o erro foi reportado.
`PGSQL_DIAG_SOURCE_FUNCTION` (int)
  Passada para pg_result_error_field(). O nome da função do código-fonte PostgreSQL que reportou o erro.
`PGSQL_DIAG_SCHEMA_NAME` (int)
  Disponível desde o PHP 7.3.0.
`PGSQL_DIAG_TABLE_NAME` (int)
  Disponível desde o PHP 7.3.0.
`PGSQL_DIAG_COLUMN_NAME` (int)
  Disponível desde o PHP 7.3.0.
`PGSQL_DIAG_DATATYPE_NAME` (int)
  Disponível desde o PHP 7.3.0.
`PGSQL_DIAG_CONSTRAINT_NAME` (int)
  Disponível desde o PHP 7.3.0.
`PGSQL_ERRORS_TERSE` (int)
  Passada para pg_set_error_verbosity(). Especifica que a mensagem retornada inclui severidade, texto primário e posição somente; normalmente em uma única linha.
`PGSQL_ERRORS_DEFAULT` (int)
  Passada para pg_set_error_verbosity(). O modo padrão produz mensagens que incluem as informações do campo acima mais algum detalhe, dica, ou campos de contexto (estes podem ter múltiplas linhas).
`PGSQL_ERRORS_VERBOSE` (int)
  Passada para pg_set_error_verbosity(). Este modo prolixo inclui todos os campos disponíveis.
`PGSQL_ERRORS_SQLSTATE` (int)
  Passada para pg_set_error_verbosity(). Inclui apenas a severidade de erro e o código de erro `SQLSTATE`. Se não houver código de erro disponível, a saída é similar ao modo `PGSQL_ERRORS_TERSE`. Antes do PostgreSQL 11.1, a saída era sempre a mesma do modo `PGSQL_ERRORS_TERSE`.
`PGSQL_NOTICE_LAST` (int)
  Usado por pg_last_notice(). Disponível desde o PHP 7.1.0.
`PGSQL_NOTICE_ALL` (int)
  Usado por pg_last_notice(). Disponível desde o PHP 7.1.0.
`PGSQL_NOTICE_CLEAR` (int)
  Usado por pg_last_notice(). Disponível desde o PHP 7.1.0.
`PGSQL_STATUS_LONG` (int)
  Passada para pg_result_status(). Indica que é desejando um código de resultado numérico.
`PGSQL_STATUS_STRING` (int)
  Passada para pg_result_status(). Indica que é desejado um resultado textual.
`PGSQL_CONV_IGNORE_DEFAULT` (int)
  Passada para pg_convert(). Ignora valores padrão na tabela durante a conversão.
`PGSQL_CONV_FORCE_NULL` (int)
  Passada para pg_convert(). Usa `NULL` da SQL no lugar de uma string vazia.
`PGSQL_CONV_IGNORE_NOT_NULL` (int)
  Passada para pg_convert(). Ignora conversão de `null` em colunas SQL `NOT NULL`.
`PGSQL_DML_NO_CONV` (int)
  Passada para pg_insert(), pg_select(), pg_update() e pg_delete(). Todos os parâmetros passados como são. Escape manual é requeriso se os parâmentros contiverem dados fornecidos pelo usuário. Use pg_escape_string() para isto.
`PGSQL_DML_EXEC` (int)
  Passada para pg_insert(), pg_select(), pg_update() e pg_delete(). Executa consulta através dessas funções.
`PGSQL_DML_ASYNC` (int)
  Passada para pg_insert(), pg_select(), pg_update() e pg_delete(). Executa consulta assíncrona através dessas funções.
`PGSQL_DML_STRING` (int)
  Passada para pg_insert(), pg_select(), pg_update() e pg_delete(). Retorna a string da consulta executada.
`PGSQL_DML_ESCAPE` (int)
  Passada para pg_insert(), pg_select(), pg_update() e pg_delete(). Escapa todos os parâmetros ao invés de chamar pg_convert() internamente. Esta opção omite pesquisa por metadados. A consulta pode ser tão rápida quanto pg_query() e pg_send_query().
`PGSQL_POLLING_FAILED` (int)
  Retornada por pg_connect_poll() para indicar que a tentativa de conexão falhou.
`PGSQL_POLLING_READING` (int)
  Retornada por pg_connect_poll() para indicar que a conexão está esperando que o socket PostgreSQL possa ser lido.
`PGSQL_POLLING_WRITING` (int)
  Retornada por pg_connect_poll() para indicar que a conexão está esperando que o socket PostgreSQL possa ser escrito.
`PGSQL_POLLING_OK` (int)
  Retornada por pg_connect_poll() para indicar que a conexão está pronta para uso.
`PGSQL_POLLING_ACTIVE` (int)
  Retornada por pg_connect_poll() para indicar que a conexão está atualmente ativa.
`PGSQL_DIAG_SEVERITY_NONLOCALIZED` (int)
  A severidade; os conteúdos dos campos são ERROR, FATAL ou PANIC (em uma mensagem de erro); ou WARNING, NOTICE, DEBUG, INFO, ou LOG (em uma nota). Isto é idêntico ao campo PG_DIAG_SEVERITY exceto que o conteúdo nunca é traduzido. Está presente somente em versões 9.6 e posteriores / PHP 7.3.0 e posteriores.
`PGSQL_SHOW_CONTEXT_NEVER` (int)
  Para ser usada com pg_set_error_context_visibility(), o contexto nunca é mostrado. Disponível a partir do PHP 8.3.0.
`PGSQL_SHOW_CONTEXT_ERRORS` (int)
  Para ser usada com pg_set_error_context_visibility(), os campos do contexto são incluídos apenas nas mensagens de erro. Este é o comportamento padrão. Disponível a partir do PHP 8.3.0.
`PGSQL_SHOW_CONTEXT_ALWAYS` (int)
  Para ser usada com pg_set_error_context_visibility(), os campos do contexto são incluídos nas mensagens de erro, notas e alertas. Disponível a partir do PHP 8.3.0.
`PGSQL_TRACE_SUPPRESS_TIMESTAMPS` (int)
  Para ser usada com pg_trace(), o timestamp não é incluído nas mensagens de rastreamento. Disponível a partir do PHP 8.4.20.
`PGSQL_TRACE_REGRESS_MODE` (int)
  Para ser usada com pg_trace(), campos como OIDs são incluídos nas mensagens de rastreamento. Disponível a partir do PHP 8.3.0.

# Exemplos

## Índice

- Uso básico
- Basic usage

## Uso básico

Este exemplo simples mostra como conectar, executar uma consulta, mostrar linhas de resultados e desconectar de um banco de dados PostgreSQL.

Exemplo #1 Exemplo geral da extensão PostgreSQL

    <?php

    // Connectando, selectionando o banco
    $dbconn = pg_connect("host=localhost dbname=publishing user=www password=foo")
        or die('Não foi possível conectar: ' . pg_last_error());

    // Executando consulta SQL
    $query = 'SELECT * FROM authors';
    $result = pg_query($dbconn, $query) or die('A consulta falhou: ' . pg_last_error());

    // Exibindo resultados em HTML
    echo "<table>\n";
    while ($line = pg_fetch_array($result, null, PGSQL_ASSOC)) {
        echo "\t<tr>\n";
        foreach ($line as $col_value) {
            echo "\t\t<td>$col_value</td>\n";
        }
        echo "\t</tr>\n";
    }
    echo "</table>\n";

    // Liberando o conjunto de resultados
    pg_free_result($result);

    // Fechando a conexão
    pg_close($dbconn);

    ?>

## Basic usage

Estes exemplos contêm funções definidas pelo usuário similares às funções legadas do MySQL.

Exemplo #1 Exemplo de funções definidas pelo usuário no PostgreSQL

    <?php
    // Este função deve ser necessária, já que o a conexão PostgreSQL vincula o banco de dados.
    function pg_list_dbs($db)
    {
        assert(is_resource($db));
        $query = '
    SELECT
     d.datname as "Name",
     u.usename as "Owner",
     pg_encoding_to_char(d.encoding) as "Encoding"
    FROM
     pg_database d LEFT JOIN pg_user u ON d.datdba = u.usesysid
    ORDER BY 1;
    ';
        return pg_query($db, $query);
    }

    // Lista tabelas.
    function pg_list_tables($db)
    {
        assert(is_resource($db));
        $query = "
    SELECT
     c.relname as \"Name\",
     CASE c.relkind WHEN 'r' THEN 'table' WHEN 'v' THEN 'view' WHEN 'i' THEN 'index' WHEN 'S' THEN 'sequence' WHEN 's' THEN 'special' END as \"Type\",
      u.usename as \"Owner\"
    FROM
     pg_class c LEFT JOIN pg_user u ON c.relowner = u.usesysid
    WHERE
     c.relkind IN ('r','v','S','')
     AND c.relname !~ '^pg_'
    ORDER BY 1;
    ";
        return pg_query($db, $query);
    }

    // Veja também pg_meta_data(). Ela retorna definições de campo em um array.
    function pg_list_fields($db, $table)
    {
        assert(is_resource($db));
        $query = "
    SELECT
     a.attname,
     format_type(a.atttypid, a.atttypmod),
     a.attnotnull,
     a.atthasdef,
     a.attnum
    FROM
     pg_class c,
     pg_attribute a
    WHERE
     c.relname = '".$table."'
     AND a.attnum > 0 AND a.attrelid = c.oid
    ORDER BY a.attnum;
    ";
        return pg_query($db, $query);
    }
    ?>

# Funções PostgreSQL

## Notas

> Nota:

> Nem todas as funções são suportadas por todas as compilações. Isso vai depender da versão da libpq (A interface cliente em C para PostgreSQL) e como esta foi compilada. Se há alguma função ausente, é porque a libpq não suporta a característica exigida por esta função.

> Nota:

> A maioria das funções do PostgreSQL aceita `connection` como o primeiro parâmetro opcional. Se ele não é fornecido, a última conexão aberta é usada. Se não existir, a função retorna `false`.

> Nota:

> PostgreSQL automaticamente converte todos identificadores (e.g. nomes de tabela/coluna) para minúsculo na criação do objeto e na query. Para força o uso misto de maiúsculo ou minúsculo, você precisa usar escape no identificador usando aspas dupla ("").

> Nota:

> PostgreSQL não tem comandos especiais para obter informação do esquema do banco de dados (ex.: todas as tabelas do banco atual). Em vez disso, há um schema padrão chamado `information_schema` contendo visualizações do sistema com todas as informações necessárias, em um formulário facilmente consultável. Veja a » Documentação do PostgreSQL para maiores detalhes.

# pg_affected_rows

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_affected_rows — Retorna o número de registros afetados (tuplas)

### Descrição

function pg_affected_rows(PgSql\Result `$result`): int

pg_affected_rows() retorna o número de tuplas (instâncias/registros/linhas) afetadas pelas consultas `INSERT`, `UPDATE` e `DELETE`.

O servidor também retorna o número de selecionadas.

> Nota:

> Esta função costumava ser chamada de pg_cmdtuples().

### Parâmetros

`result`
  Uma instância de PgSql\Result, retornada por pg_query(), pg_query_params() ou pg_execute() (entre outras).

### Valor Retornado

O número de linhas afetadas pela consulta. Se nenhuma tupla for afetada, retornará `0`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `result` agora espera uma instância de PgSql\Result; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_affected_rows()

    <?php
    $result = pg_query($conn, "INSERT INTO authors VALUES ('Orwell', 2002, 'Animal Farm')");

    $cmdtuples = pg_affected_rows($result);

    echo $cmdtuples . " tuplas são afetadas.\n";
    ?>

O exemplo acima produzirá:

    1  tuplas são afetadas.

### Veja Também

- pg_query() - Executa uma consulta
- pg_query_params() - Envia um comando ao servidor e aguarda o resultado, com a capacidade de passar parâmetros separadamente do texto do comando SQL
- pg_execute() - Envia uma solicitação para executar uma instrução preparada com determinados parâmetros e aguarda o resultado
- pg_num_rows() - Retorna o número de linhas em um resultado

# pg_cancel_query

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_cancel_query — Cancela uma consulta assíncrona

### Descrição

function pg_cancel_query(PgSql\Connection `$connection`): bool

pg_cancel_query() cancela uma consulta assíncrona enviada com pg_send_query(), pg_send_query_params() ou pg_send_execute(). Você não pode cancelar uma consulta executada usando pg_query().

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_cancel_query()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Não foi possível conectar");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from authors; select count(*) from authors;");
      }

      $res1 = pg_get_result($dbconn);
      echo "Primeira chamada para pg_get_result(): $res1\n";
      $rows1 = pg_num_rows($res1);
      echo "$res1 tem $rows1 registros\n\n";

      // Cancela a consulta atualmente em execução. Será a segunda consulta se ainda
      // estiver em execução.
      pg_cancel_query($dbconn);
    ?>

O exemplo acima produzirá:

    Primeira chamada para pg_get_result(): Resource id #3
    Resource id #3 tem 3 registros

### Veja Também

- pg_send_query() - Envia consulta assíncrona
- pg_connection_busy() - Obtém se conexão está ocupada ou não

# pg_change_password

(PHP 8 >= 8.4.0)

pg_change_password — Altera a senha de um usuário do PostgreSQL

### Descrição

function pg_change_password(PgSql\Connection `$connection`, string `$user`, string `$password`): bool

pg_change_password() altera a senha de um usuário do PostgreSQL. Esta função utiliza a função `PQchangePassword` da libpq, que lida com a criptografia de senhas automaticamente com base nas configurações do servidor.

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.
`user`
  O nome do usuário do PostgreSQL cuja senha deve ser alterada.
`password`
  A nova senha.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- pg_connect() - Abre uma conexão PostgreSQL

# pg_client_encoding

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_client_encoding — Obtém a codificação do cliente

### Descrição

function pg_client_encoding(?PgSql\Connection `$connection` = `null`): string

PostgreSQL suporta conversão automática de conjuntos de caracteres entre servidor e cliente para determinados conjuntos de caracteres. pg_client_encoding() retorna a codificação do cliente como uma string. A string retornada será um dos identificadores de codificação padrão do PostgreSQL.

> Nota:

> Se a libpq for compilada sem suporte à codificação multibyte, pg_client_encoding() sempre retornará `SQL_ASCII`. A codificação suportada depende da versão do PostgreSQL. Consulte as codificações suportadas na documentação do PostgreSQL.

> A função costumava ser chamada de pg_clientencoding().

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` for `null`, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

### Valor Retornado

A codificação do cliente.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.
8.0.0 | `connection` agora é anulável.

### Exemplos

Exemplo #1 Exemplo de pg_client_encoding()

    <?php
    // Suponha que $conn seja uma conexão com um banco de dados ISO-8859-1
    $encoding = pg_client_encoding($conn);

    echo "A codificação do cliente é: ", $encoding, "\n";
    ?>

O exemplo acima produzirá:

    A codificação do cliente é: ISO-8859-1

### Veja Também

- pg_set_client_encoding() - Define a codificação do cliente

# pg_close

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_close — Fecha uma conexão PostgreSQL

### Descrição

function pg_close(?PgSql\Connection `$connection` = `null`): true

pg_close() fecha a conexão não persistente com um banco de dados PostgreSQL associado à instância de `connection` fornecida.

> Nota:

> Usar pg_close() geralmente não é necessário, pois conexões abertas não persistentes são fechadas automaticamente no final do script.

Se houver uma instância PgSql\Lob aberta na conexão, não feche a conexão antes de fechar todas as instâncias PgSql\Lob.

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` for `null`, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.2.0 | O tipo do retorno agora é `true`; anteriormente, era bool.
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.
8.0.0 | `connection` agora é anulável.

### Exemplos

Exemplo #1 Exemplo de pg_close()

    <?php
    $dbconn = pg_connect("host=localhost port=5432 dbname=mary")
       or die("Não foi possível conectar");
    echo "Conectado com sucesso";
    pg_close($dbconn);
    ?>

O exemplo acima produzirá:

    Conectado com sucesso

### Veja Também

- pg_connect() - Abre uma conexão PostgreSQL

# pg_connect

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_connect — Abre uma conexão PostgreSQL

### Descrição

function pg_connect(string `$connection_string`, int `$flags` = 0): PgSql\Connection|false

pg_connect() abre uma conexão com um banco de dados PostgreSQL especificado pelo `connection_string`.

Se uma segunda chamada for feita para pg_connect() com o mesmo `connection_string` de uma conexão existente, a conexão existente será retornada a menos que você passe `PGSQL_CONNECT_FORCE_NEW` como `flags`.

A sintaxe antiga com múltiplos parâmetros $conn = pg_connect("host", "port", "options", "tty", "dbname") foi descontinuada.

### Parâmetros

`connection_string`

  O `connection_string` pode estar vazio para usar todos os parâmetros padrão ou pode conter uma ou mais configurações de parâmetro separadas por espaços em branco. Cada configuração de parâmetro está no formato `palavra-chave = valor`. Os espaços ao redor do sinal de igual são opcionais. Para escrever um valor vazio ou contendo espaços, coloque-o entre aspas simples, por exemplo, `palavra-chave = 'um valor'`. Aspas simples e barras invertidas dentro do valor devem ser escapadas com uma barra invertida, ou seja, \' e \\.

  As palavras-chave de parâmetro atualmente reconhecidas são: `host`, `hostaddr`, `port`, `dbname` (o padrão é o valor de `user`), `user`, `password`, `connect_timeout`, `options`, `tty` (ignorado), `sslmode`, `requiressl` (descontinuado em favor de `sslmode`) e `service`. Quais desses argumentos existem depende da sua versão do PostgreSQL.

  O parâmetro `options` pode ser usado para definir parâmetros de linha de comando a serem invocados pelo servidor.

`flags`

  Se `PGSQL_CONNECT_FORCE_NEW` for passado, então uma nova conexão será criada, mesmo que `connection_string` seja idêntico a uma conexão existente.

  Se `PGSQL_CONNECT_ASYNC` for fornecido, então a conexão será estabelecida de forma assíncrona. O estado da conexão pode então ser verificado via pg_connect_poll() ou pg_connection_status().

### Valor Retornado

Retorna uma instância PgSql\Connection em caso de sucesso, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Retorna uma instância PgSql\Connection agora; anteriormente, um resource era retornado.

### Exemplos

Exemplo #1 Usando pg_connect()

    <?php
    $dbconn = pg_connect("dbname=mary");
    //conecta-se a um banco de dados chamado "mary"

    $dbconn2 = pg_connect("host=localhost port=5432 dbname=mary");
    //conecta-se a um banco de dados chamado "mary" em "localhost" na porta "5432"

    $dbconn3 = pg_connect("host=sheep port=5432 dbname=mary user=lamb password=foo");
    ///conecta-se a um banco de dados chamado "mary" no host "sheep" com um usuário e senha

    $conn_string = "host=sheep port=5432 dbname=test user=lamb password=bar";
    $dbconn4 = pg_connect($conn_string);
    //conecta-se a um banco de dados chamado "test" no host "sheep" com um usuário e senha

    $dbconn5 = pg_connect("host=localhost options='--client_encoding=UTF8'");
    //conecta-se a um banco de dados em "localhost" e define o parâmetro da linha de comando que informa que a codificação está em UTF-8
    ?>

### Veja Também

- pg_pconnect() - Abre uma conexão PostgreSQL persistente
- pg_close() - Fecha uma conexão PostgreSQL
- pg_host() - Retorna o nome do host associado à conexão
- pg_port() - Retorne o número da porta associada à conexão
- pg_tty() - Retorna o nome TTY associado à conexão
- pg_options() - Obtém as opções associadas à conexão
- pg_dbname() - Obtém o nome do banco de dados

# pg_connect_poll

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_connect_poll — Pesquisa o status de uma tentativa de conexão PostgreSQL assíncrona em andamento

### Descrição

function pg_connect_poll(PgSql\Connection `$connection`): int

pg_connect_poll() pesquisa o status de uma conexão PostgreSQL criada chamando pg_connect() com a opção `PGSQL_CONNECT_ASYNC`.

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.

### Valor Retornado

Retorna `PGSQL_POLLING_FAILED`, `PGSQL_POLLING_READING`, `PGSQL_POLLING_WRITING`, `PGSQL_POLLING_OK`, ou `PGSQL_POLLING_ACTIVE`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

# pg_connection_busy

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_connection_busy — Obtém se conexão está ocupada ou não

### Descrição

function pg_connection_busy(PgSql\Connection `$connection`): bool

pg_connection_busy() determina se uma conexão está ocupada ou não. Se estiver ocupada, uma consulta anterior ainda está em execução. Se pg_get_result() for usado na conexão, ela será bloqueada.

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.

### Valor Retornado

Retorna `true` se a conexão estiver ocupada, `false` caso contrário.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_connection_busy()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Não foi possível conectar");
      $bs = pg_connection_busy($dbconn);
      if ($bs) {
          echo 'conexão está ocupada';
      } else {
         echo 'conexão não está ocupada';
      }
    ?>

### Veja Também

- pg_connection_status() - Obtém o status da conexão
- pg_get_result() - Obtém o resultado da consulta assíncrona

# pg_connection_reset

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_connection_reset — Redefine conexão (reconecta)

### Descrição

function pg_connection_reset(PgSql\Connection `$connection`): bool

pg_connection_reset() redefine a conexão. É útil para recuperação de erros.

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_connection_reset()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Não foi possível conectar");
      $dbconn2 = pg_connection_reset($dbconn);
      if ($dbconn2) {
          echo "redefinição bem-sucedida\n";
      } else {
          echo "falha na redefinição\n";
      }
    ?>

### Veja Também

- pg_connect() - Abre uma conexão PostgreSQL
- pg_pconnect() - Abre uma conexão PostgreSQL persistente
- pg_connection_status() - Obtém o status da conexão

# pg_connection_status

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_connection_status — Obtém o status da conexão

### Descrição

function pg_connection_status(PgSql\Connection `$connection`): int

pg_connection_status() retorna o status da `connection` especificada.

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.

### Valor Retornado

`PGSQL_CONNECTION_OK` ou `PGSQL_CONNECTION_BAD`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_connection_status()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Não foi possível conectar");
      $stat = pg_connection_status($dbconn);
      if ($stat === PGSQL_CONNECTION_OK) {
          echo 'Status da conexão ok';
      } else {
          echo 'Status da conexão ruim';
      }
    ?>

### Veja Também

- pg_connection_busy() - Obtém se conexão está ocupada ou não

# pg_consume_input

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_consume_input — Lê a entrada na conexão

### Descrição

function pg_consume_input(PgSql\Connection `$connection`): bool

pg_consume_input() consome qualquer entrada aguardando para ser lida no servidor de banco de dados.

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.

### Valor Retornado

`true` se nenhum erro ocorreu ou `false` se houve um erro. Observe que `true` não indica necessariamente que a entrada estava aguardando para ser lida.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

# pg_convert

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_convert — Converte valores de array associativo em formas adequadas para instruções SQL

### Descrição

function pg_convert(
PgSql\Connection `$connection`,
string `$table_name`,
array `$values`,
int `$flags` = 0
): array|false

pg_convert() verifica e converte os valores em `values` em valores adequados para uso em uma instrução SQL. A pré-condição para pg_convert() é a existência de uma tabela `table_name` que tenha pelo menos tantas colunas quanto `values` tem elementos. Os nomes dos campos em `table_name` devem corresponder aos índices em `values` e os tipos de dados correspondentes devem ser compatíveis. Retorna um array com os valores convertidos em caso de sucesso, `false` caso contrário.

> Nota:

> Os valores booleanos são aceitos e convertidos em booleanos do PostgreSQL. Representações de string de valores booleanos também são suportadas. `null` é convertido para PostgreSQL NULL.

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.
`table_name`

  Nome da tabela na qual converter tipos.

`values`

  Dados a serem convertidos.

`flags`

  Qualquer número de `PGSQL_CONV_IGNORE_DEFAULT`, `PGSQL_CONV_FORCE_NULL` ou `PGSQL_CONV_IGNORE_NOT_NULL`, combinado.

### Valor Retornado

Um array de valores convertidos, ou `false` em caso de falha.

### Erros/Exceções

Um ValueError ou TypeError é lançado quando o valor ou tipo de campo não corresponde corretamente ao tipo do PostgreSQL.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Agora lança um erro ValueError ou TypeError quando o valor ou tipo de campo não corresponde corretamente ao tipo do PostgreSQL; anteriormente um `E_WARNING` era emitido.
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_convert()

    <?php
      $dbconn = pg_connect('dbname=foo');

      $tmp = array(
          'author' => 'Joe Thackery',
          'year' => 2005,
          'title' => 'My Life, by Joe Thackery'
      );

      $vals = pg_convert($dbconn, 'authors', $tmp);
    ?>

### Veja Também

- pg_meta_data() - Obtém metadados para tabela
- pg_insert() - Insere array na tabela
- pg_select() - Seleciona registros
- pg_update() - Atualiza tabela
- pg_delete() - Exclui registros

# pg_copy_from

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_copy_from — Insere registros em uma tabela a partir de um array

### Descrição

function pg_copy_from(
PgSql\Connection `$connection`,
string `$table_name`,
array|Traversable `$rows`,
string `$separator` = "\t",
string `$null_as` = "\\\\N"
): bool

pg_copy_from() insere registros em uma tabela a partir de `rows`. Ele emite um comando SQL `COPY FROM` internamente para inserir registros.

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.
`table_name`

  Nome da tabela na qual copiar as `rows`.

`rows`

  Dados do tipo iterable a serem copiados em `table_name`. Cada valor em `rows` se torna uma linha em `table_name`. Cada valor em `rows` deve ser uma string delimitada dos valores a serem inseridos em cada campo. Os valores devem ser finalizados com avanço de linha.

`separator`

  O token que separa os valores de cada campo em cada elemento de `rows`. O padrão é `\t`.

`null_as`

  Como os valores SQL `NULL` são representados nas `rows`. O padrão é `\\N` (`"\\\\N"`).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | `rows` agora é do tipo iterable. Anteriormente era do tipo array.
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_copy_from()

    <?php
       $db = pg_connect("dbname=publisher") or die("Não foi possível conectar");

       $rows = pg_copy_to($db, $table_name);

       pg_query($db, "DELETE FROM $table_name");

       pg_copy_from($db, $table_name, $rows);
    ?>

### Veja Também

- pg_copy_to() - Copia uma tabela para um array

# pg_copy_to

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_copy_to — Copia uma tabela para um array

### Descrição

function pg_copy_to(
PgSql\Connection `$connection`,
string `$table_name`,
string `$separator` = "\t",
string `$null_as` = "\\\\N"
): array|false

pg_copy_to() copia uma tabela para um array. Ele emite o comando SQL `COPY TO` internamente para recuperar registros.

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.
`table_name`

  Nome da tabela da qual copiar os dados em `rows`.

`separator`

  O token que separa os valores de cada campo em cada elemento de `rows`. O padrão é `\t`.

`null_as`

  Como os valores SQL `NULL` são representados nas `rows`. O padrão é `\\N` (`"\\\\N"`).

### Valor Retornado

Um array com um elemento para cada linha de dados `COPY`, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_copy_to()

    <?php
       $db = pg_connect("dbname=publisher") or die("Não foi possível conectar");

       $rows = pg_copy_to($db, $table_name);

       pg_query($db, "DELETE FROM $table_name");

       pg_copy_from($db, $table_name, $rows);
    ?>

### Veja Também

- pg_copy_from() - Insere registros em uma tabela a partir de um array

# pg_dbname

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_dbname — Obtém o nome do banco de dados

### Descrição

function pg_dbname(?PgSql\Connection `$connection` = `null`): string

pg_dbname() retorna o nome do banco de dados da instância de `connection` do PostgreSQL fornecida.

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` for `null`, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

### Valor Retornado

Uma string contendo o nome do banco de dados ao qual a `connection` está.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.
8.0.0 | `connection` agora é anulável.

### Exemplos

Exemplo #1 Exemplo de pg_dbname()

    <?php
      error_reporting(E_ALL);

      pg_connect("host=localhost port=5432 dbname=mary");
      echo pg_dbname(); // mary
    ?>

# pg_delete

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_delete — Exclui registros

### Descrição

function pg_delete(
PgSql\Connection `$connection`,
string `$table_name`,
array `$conditions`,
int `$flags` = `PGSQL_DML_EXEC`
): string|bool

pg_delete() exclui registros de uma tabela especificada pelas chaves e valores em `conditions`.

Se `flags` for especificado, pg_convert() será aplicado às `conditions` com as opções especificadas.

Por padrão, pg_delete() passa valores brutos. Os valores devem ser escapados ou a opção `PGSQL_DML_ESCAPE` deve ser especificado em `flags`. `PGSQL_DML_ESCAPE` cita e escapa parâmetros/identificadores. Portanto, os nomes de tabelas/colunas diferenciam maiúsculas de minúsculas.

Observe que nem o escape nem a consulta preparada podem proteger consultas LIKE, JSON, Array, Regex, etc. Esses parâmetros devem ser tratados de acordo com seus contextos. ou seja, escapar/validar valores.

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.
`table_name`

  Nome da tabela da qual as linhas serão excluídas.

`conditions`

  Um array cujas chaves são nomes de campos na tabela `table_name` e cujos valores são os valores dos campos que devem ser excluídos.

`flags`

  Qualquer número de `PGSQL_CONV_FORCE_NULL`, `PGSQL_DML_NO_CONV`, `PGSQL_DML_ESCAPE`, `PGSQL_DML_EXEC`, `PGSQL_DML_ASYNC` ou `PGSQL_DML_STRING` combinado. Se `PGSQL_DML_STRING` fizer parte de `flags` então a string de consulta é retornada. Quando `PGSQL_DML_NO_CONV` ou `PGSQL_DML_ESCAPE` está definido, ele não chama pg_convert() internamente.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha. Retorna string se `PGSQL_DML_STRING` for passado através de `flags`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_delete()

    <?php
      $db = pg_connect('dbname=foo');
      // Isso é um tanto seguro, já que todos os valores têm escape.
      // No entanto, o PostgreSQL suporta JSON/Array. Eles não são
      // seguros nem por escape nem por consulta preparada.
      $res = pg_delete($db, 'post_log', $_POST, PG_DML_ESCAPE);
      if ($res) {
          echo "Dados POST foram excluídos: $res\n";
      } else {
          echo "O usuário deve ter enviado entradas erradas\n";
      }
    ?>

### Veja Também

- pg_convert() - Converte valores de array associativo em formas adequadas para instruções SQL

# pg_end_copy

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_end_copy — Sincroniza com back-end do PostgreSQL

### Descrição

function pg_end_copy(?PgSql\Connection `$connection` = `null`): bool

pg_end_copy() sincroniza o frontend do PostgreSQL (geralmente um processo de servidor web) com o servidor PostgreSQL após fazer uma operação de cópia executada por pg_put_line(). pg_end_copy() deve ser emitido, caso contrário o servidor PostgreSQL pode ficar fora de sincronia com o frontend e reportar um erro.

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` for `null`, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.
8.0.0 | `connection` agora é anulável.

### Exemplos

Exemplo #1 Exemplo de pg_end_copy()

    <?php
      $conn = pg_pconnect("dbname=foo");
      pg_query($conn, "create table bar (a int4, b char(16), d float8)");
      pg_query($conn, "copy bar from stdin");
      pg_put_line($conn, "3\thello world\t4.5\n");
      pg_put_line($conn, "4\tgoodbye world\t7.11\n");
      pg_put_line($conn, "\\.\n");
      pg_end_copy($conn);
    ?>

### Veja Também

- pg_put_line() - Envia uma string terminada em NULL para o backend do PostgreSQL

# pg_escape_bytea

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_escape_bytea — Escapa uma string para inserção em um campo bytea

### Descrição

function pg_escape_bytea(PgSql\Connection `$connection` = ?, string `$string`): string

pg_escape_bytea() escapa string para o tipo de dados bytea. Ele retorna uma string com escape.

> Nota:

> Quando seleciona-se um tipo bytea com `SELECT`, o PostgreSQL retorna valores de bytes octais prefixados com '\' (por exemplo, \032). Os usuários devem converter de volta para o formato binário manualmente.

> Esta função requer PostgreSQL 7.2 ou posterior. Com PostgreSQL 7.2.0 e 7.2.1, os valores bytea devem ser convertidos quando você ativa o suporte multibyte. ou seja, `INSERT INTO test_table (image) VALUES ('$image_escaped'::bytea);` PostgreSQL 7.2.2 ou posterior não precisa de conversão. A exceção é quando a codificação de caracteres do cliente e do backend não corresponde e pode haver erro de fluxo de vários bytes. O usuário deve então converter para bytea para evitar esse erro.

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` não for especificado, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

`string`

  Uma string contendo texto ou dados binários a serem inseridos em uma coluna bytea.

### Valor Retornado

Uma string contendo o dado escapado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_escape_bytea()

    <?php
      // Conecta ao banco de dados
      $dbconn = pg_connect('dbname=foo');

      // Lê em um arquivo binário
      $data = file_get_contents('image1.jpg');

      // Escapa o dado binário
      $escaped = pg_escape_bytea($data);

      // Insere-o no banco de dados
      pg_query("INSERT INTO gallery (name, data) VALUES ('Pine trees', '{$escaped}')");
    ?>

### Veja Também

- pg_unescape_bytea() - Desfaz escape binário para tipo bytea
- pg_escape_string() - Escapa uma string para consulta

# pg_escape_identifier

(PHP 5 >= 5.4.4, PHP 7, PHP 8)

pg_escape_identifier — Escapa um identificador para inserção em um campo de texto

### Descrição

function pg_escape_identifier(PgSql\Connection `$connection` = ?, string `$string`): string|false

pg_escape_identifier() escapa um identificador (por exemplo, tabela, nomes de campos) para consultar o banco de dados. Ele retorna uma string identificadora de escape para o servidor PostgreSQL. pg_escape_identifier() adiciona aspas duplas antes e depois dos dados. Os usuários não devem adicionar aspas duplas. O uso desta função é recomendado para parâmetros identificadores em consulta. Para literais SQL (ou seja, parâmetros exceto bytea), pg_escape_literal() ou pg_escape_string() devem ser usados. Para campos do tipo bytea, pg_escape_bytea() deve ser usado no lugar.

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` não for especificado, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

`string`

  Uma string contendo texto a ser escapado.

### Valor Retornado

Uma string contendo os dados escapados ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_escape_identifier()

    <?php
      // Conecta ao banco de dados
      $dbconn = pg_connect('dbname=foo');

      // Escapa os dados do nome da tabela
      $escaped = pg_escape_identifier($table_name);

      // Seleciona linhas de $table_name
      pg_query("SELECT * FROM {$escaped};");
    ?>

### Veja Também

- pg_escape_literal() - Escapa um literal para inserção em um campo de texto
- pg_escape_bytea() - Escapa uma string para inserção em um campo bytea
- pg_escape_string() - Escapa uma string para consulta

# pg_escape_literal

(PHP 5 >= 5.4.4, PHP 7, PHP 8)

pg_escape_literal — Escapa um literal para inserção em um campo de texto

### Descrição

function pg_escape_literal(PgSql\Connection `$connection` = ?, string `$string`): string|false

pg_escape_literal() escapa um literal para consultar o banco de dados PostgreSQL. Ele retorna um literal de escape no formato PostgreSQL. pg_escape_literal() adiciona aspas antes e depois dos dados. Os usuários não devem adicionar aspas. O uso desta função é recomendado em vez de pg_escape_string(). Se o tipo da coluna for bytea, pg_escape_bytea() deverá ser usado no lugar. Para identificadores de escape (por exemplo, tabelas, nomes de campos), pg_escape_identifier() deve ser usado.

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` não for especificado, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

`string`

  Uma string contendo texto a ser escapado.

### Valor Retornado

Uma string contendo os dados escapados ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_escape_literal()

    <?php
      // Conecta ao banco de dados
      $dbconn = pg_connect('dbname=foo');

      // Lê um arquivo de texto (contendo apóstrofos e barras invertidas)
      $data = file_get_contents('letter.txt');

      // Escapa dos dados de texto
      $escaped = pg_escape_literal($data);

      // Insere-o no banco de dados. Observe que não há aspas em torno de {$escaped}
      pg_query("INSERT INTO correspondence (name, data) VALUES ('My letter', {$escaped})");
    ?>

### Veja Também

- pg_escape_identifier() - Escapa um identificador para inserção em um campo de texto
- pg_escape_bytea() - Escapa uma string para inserção em um campo bytea
- pg_escape_string() - Escapa uma string para consulta

# pg_escape_string

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_escape_string — Escapa uma string para consulta

### Descrição

function pg_escape_string(PgSql\Connection `$connection` = ?, string `$string`): string

pg_escape_string() escapa uma string para consultar o banco de dados. Ele retorna uma string de escape no formato PostgreSQL sem aspas. pg_escape_literal() é a forma preferida de escapar dos parâmetros SQL para PostgreSQL. addslashes() não deve ser usado com PostgreSQL. Se o tipo da coluna for bytea, pg_escape_bytea() deverá ser usado no lugar. pg_escape_identifier() deve ser usado para escape de identificadores (por exemplo, nomes de tabelas, nomes de campos)

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` não for especificado, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

`string`

  Uma string contendo texto a ser escapado.

### Valor Retornado

Uma string contendo os dados escapados.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_escape_string()

    <?php
      // Conecta ao banco de dados
      $dbconn = pg_connect('dbname=foo');

      // Lê em um arquivo de texto (contendo apóstrofos e barras invertidas)
      $data = file_get_contents('letter.txt');

      // Escape dos dados de texto
      $escaped = pg_escape_string($data);

      // Insira-o no banco de dados
      pg_query("INSERT INTO correspondence (name, data) VALUES ('My letter', '{$escaped}')");
    ?>

### Veja Também

- pg_escape_bytea() - Escapa uma string para inserção em um campo bytea

# pg_execute

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_execute — Envia uma solicitação para executar uma instrução preparada com determinados parâmetros e aguarda o resultado

### Descrição

function pg_execute(PgSql\Connection `$connection` = ?, string `$statement_name`, array `$params`): PgSql\Result|false

Envia uma solicitação para executar uma instrução preparada com determinados parâmetros e aguarda o resultado.

pg_execute() é como pg_query_params(), mas o comando a ser executado é especificado nomeando uma instrução previamente preparada, em vez de fornecer uma string de consulta. Este recurso permite que comandos que serão usados repetidamente sejam analisados e planejados apenas uma vez, em vez de cada vez que forem executados. A declaração deve ter sido preparada anteriormente na sessão atual.

Os parâmetros são idênticos a pg_query_params(), exceto que o nome de uma instrução preparada é fornecido em vez de uma string de consulta.

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` não for especificado, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

`statement_name`

  O nome da instrução preparada a ser executada. se "" for especificado, a instrução sem nome será executada. O nome deve ter sido preparado previamente usando pg_prepare(), pg_send_prepare() ou um comando SQL `PREPARE`.

`params`

  Um array de valores de parâmetros para substituir os espaços reservados $1, $2, etc. na string de consulta preparada original. O número de elementos no array deve corresponder ao número de espaços reservados.

  Aviso

  Os elementos são convertidos em strings chamando esta função.

### Valor Retornado

Uma instância PgSql\Result em caso de sucesso, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Agora retorna uma instância de PgSql\Result; anteriormente, um resource era retornado.
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Usando pg_execute()

    <?php
    // Conecta com um banco de dados chamado "mary"
    $dbconn = pg_connect("dbname=mary");

    // Prepara a consulta para execução
    $result = pg_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name = $1');

    // Executa a consulta preparada. Observe que não é necessário escapar a
    // string "Joe's Widgets" de forma alguma
    $result = pg_execute($dbconn, "my_query", array("Joe's Widgets"));

    // Execute a mesma consulta preparada, desta vez com um parâmetro diferente
    $result = pg_execute($dbconn, "my_query", array("Clothes Clothes Clothes"));

    ?>

### Veja Também

- pg_prepare() - Envia uma solicitação ao servidor para criar uma instrução preparada com os parâmetros fornecidos e aguarda a conclusão
- pg_send_prepare() - Envia uma solicitação para criar uma instrução preparada com os parâmetros fornecidos, sem esperar pela conclusão
- pg_query_params() - Envia um comando ao servidor e aguarda o resultado, com a capacidade de passar parâmetros separadamente do texto do comando SQL

# pg_fetch_all

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_fetch_all — Busca todas as linhas de um resultado como um array

### Descrição

function pg_fetch_all(PgSql\Result `$result`, int `$mode` = `PGSQL_ASSOC`): array

pg_fetch_all() retorna um array que contém todas as linhas (registros) na instância PgSql\Result.

> Nota: Esta função define campos NULL como o valor `null` do PHP.

### Parâmetros

`result`
  Uma instância de PgSql\Result, retornada por pg_query(), pg_query_params() ou pg_execute() (entre outras).
`mode`
  Um parâmetro opcional que controla como o array retornado será indexado. `mode` é uma constante e pode assumir os seguintes valores: `PGSQL_ASSOC`, `PGSQL_NUM` e `PGSQL_BOTH`. Usando `PGSQL_NUM`, a função retornará um array com índices numéricos, usando `PGSQL_ASSOC` ela retornará apenas índices associativos enquanto `PGSQL_BOTH` retornará índices numéricos e associativos.

### Valor Retornado

Um array com todas as linhas no resultado. Cada linha é um array de valores de campo indexados pelo nome do campo.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `result` agora espera uma instância de PgSql\Result; anteriormente, um resource era esperado.
8.0.0 | pg_fetch_all() agora retornará um array em vez de `false` para conjuntos de resultados com zero linhas.
7.1.0 | O parâmetro `mode` foi adicionado.

### Exemplos

Exemplo #1 PostgreSQL busca tudo

    <?php
    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
        echo "Ocorreu um erro.\n";
        exit;
    }

    $result = pg_query($conn, "SELECT * FROM authors");
    if (!$result) {
        echo "Ocorreu um erro.\n";
        exit;
    }

    $arr = pg_fetch_all($result);

    print_r($arr);

    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Array
            (
                [id] => 1
                [name] => Fred
            )

        [1] => Array
            (
                [id] => 2
                [name] => Bob
            )

    )

### Veja Também

- pg_fetch_row() - Obtém uma linha como um array enumerado
- pg_fetch_array() - Busca uma linha como um array
- pg_fetch_object() - Busca uma linha como um objeto
- pg_fetch_result() - Retorna valores de uma instância de resultado

# pg_fetch_all_columns

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_fetch_all_columns — Busca todas as linhas em uma determinada coluna de resultado como um array

### Descrição

function pg_fetch_all_columns(PgSql\Result `$result`, int `$field` = 0): array

pg_fetch_all_columns() retorna um array que contém todas as linhas (registros) em uma determinada coluna da instância PgSql\Result.

> Nota: Esta função define campos NULL como o valor `null` do PHP.

### Parâmetros

`result`
  Uma instância de PgSql\Result, retornada por pg_query(), pg_query_params() ou pg_execute() (entre outras).
`field`

  Número da coluna. O padrão é a primeira coluna se não for especificado.

### Valor Retornado

Um array com todos os valores na coluna de resultados.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `result` agora espera uma instância de PgSql\Result; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_fetch_all_columns()

    <?php
    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Ocorreu um erro.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT title, name, address FROM authors");
    if (!$result) {
      echo "Ocorreu um erro.\n";
      exit;
    }

    // Obtém um array de todos os nomes de autores
    $arr = pg_fetch_all_columns($result, 1);

    var_dump($arr);

    ?>

### Veja Também

- pg_fetch_all() - Busca todas as linhas de um resultado como um array

# pg_fetch_array

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_fetch_array — Busca uma linha como um array

### Descrição

function pg_fetch_array(PgSql\Result `$result`, ?int `$row` = `null`, int `$mode` = `PGSQL_BOTH`): array|false

pg_fetch_array() retorna um array que corresponde à linha buscada (registro).

pg_fetch_array() é uma versão estendida de pg_fetch_row(). Além de armazenar os dados nos índices numéricos (número do campo) no array de resultados, também pode armazenar os dados usando índices associativos (nome do campo). Ele armazena ambos os índices por padrão.

> Nota: Esta função define campos NULL como o valor `null` do PHP.

pg_fetch_array() NÃO é significativamente mais lento do que usar pg_fetch_row() e é significativamente mais fácil de usar.

### Parâmetros

`result`
  Uma instância de PgSql\Result, retornada por pg_query(), pg_query_params() ou pg_execute() (entre outras).
`row`

  Número da linha no resultado a ser buscado. As linhas são numeradas de 0 para cima. Se omitido ou `null`, a próxima linha será buscada.

`mode`
  Um parâmetro opcional que controla como o array retornado será indexado. `mode` é uma constante e pode assumir os seguintes valores: `PGSQL_ASSOC`, `PGSQL_NUM` e `PGSQL_BOTH`. Usando `PGSQL_NUM`, a função retornará um array com índices numéricos, usando `PGSQL_ASSOC` ela retornará apenas índices associativos enquanto `PGSQL_BOTH` retornará índices numéricos e associativos.

### Valor Retornado

Um array indexado numericamente (começando com 0) ou associativamente (indexado pelo nome do campo), ou ambos. Cada valor no array é representado como uma string. Os valores `NULL` do banco de dados são retornados como `null`.

`false` é retornado se `row` exceder o número de linhas no conjunto, não houver mais linhas ou em qualquer outro erro. Buscar o resultado de uma consulta diferente de SELECT também retornará `false`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `result` agora espera uma instância de PgSql\Result; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_fetch_array()

    <?php

    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Ocorreu um erro.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT author, email FROM authors");
    if (!$result) {
      echo "Ocorreu um erro.\n";
      exit;
    }

    $arr = pg_fetch_array($result, 0, PGSQL_NUM);
    echo $arr[0] . " <- Row 1 Author\n";
    echo $arr[1] . " <- Row 1 E-mail\n";

    // O parâmetro linha é opcional; NULL pode ser passado em vez disso,
    // para passar um result_type. Chamadas sucessivas para pg_fetch_array
    // retornarão a próxima linha.
    $arr = pg_fetch_array($result, NULL, PGSQL_ASSOC);
    echo $arr["author"] . " <- Row 2 Author\n";
    echo $arr["email"] . " <- Row 2 E-mail\n";

    $arr = pg_fetch_array($result);
    echo $arr["author"] . " <- Row 3 Author\n";
    echo $arr[1] . " <- Row 3 E-mail\n";

    ?>

### Veja Também

- pg_fetch_row() - Obtém uma linha como um array enumerado
- pg_fetch_object() - Busca uma linha como um objeto
- pg_fetch_result() - Retorna valores de uma instância de resultado

# pg_fetch_assoc

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_fetch_assoc — Busca uma linha como um array associativo

### Descrição

function pg_fetch_assoc(PgSql\Result `$result`, ?int `$row` = `null`): array|false

pg_fetch_assoc() retorna um array associativo que corresponde à linha buscada (registros).

pg_fetch_assoc() é equivalente a chamar pg_fetch_array() com `PGSQL_ASSOC` como o terceiro parâmetro opcional. Ele retorna apenas um array associativo. Se você precisar dos índices numéricos, use pg_fetch_row().

> Nota: Esta função define campos NULL como o valor `null` do PHP.

pg_fetch_assoc() NÃO é significativamente mais lento do que usar pg_fetch_row() e é significativamente mais fácil de usar.

### Parâmetros

`result`
  Uma instância de PgSql\Result, retornada por pg_query(), pg_query_params() ou pg_execute() (entre outras).
`row`

  Número da linha no resultado a ser buscado. As linhas são numeradas de 0 para cima. Se omitido ou `null`, a próxima linha será buscada.

### Valor Retornado

Um array indexado associativamente (por nome de campo). Cada valor no array é representado como uma string. Os valores `NULL` do banco de dados são retornados como `null`.

`false` é retornado se `row` exceder o número de linhas no conjunto, não houver mais linhas ou em qualquer outro erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `result` agora espera uma instância de PgSql\Result; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_fetch_assoc()

    <?php
    $conn = pg_connect("dbname=publisher");
    if (!$conn) {
      echo "Ocorreu um erro.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT id, author, email FROM authors");
    if (!$result) {
      echo "Ocorreu um erro.\n";
      exit;
    }

    while ($row = pg_fetch_assoc($result)) {
      echo $row['id'];
      echo $row['author'];
      echo $row['email'];
    }
    ?>

### Veja Também

- pg_fetch_row() - Obtém uma linha como um array enumerado
- pg_fetch_array() - Busca uma linha como um array
- pg_fetch_object() - Busca uma linha como um objeto
- pg_fetch_result() - Retorna valores de uma instância de resultado

# pg_fetch_object

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_fetch_object — Busca uma linha como um objeto

### Descrição

function pg_fetch_object(
PgSql\Result `$result`,
?int `$row` = `null`,
string `$class` = "stdClass",
array `$constructor_args` = []
): object|false

pg_fetch_object() retorna um objeto com propriedades que correspondem aos nomes dos campos da linha buscada. Opcionalmente, ele pode instanciar um objeto de uma classe específica e passar parâmetros para o construtor dessa classe.

> Nota: Esta função define campos NULL como o valor `null` do PHP.

Em termos de velocidade, a função é idêntica à pg_fetch_array() e quase tão rápida quanto pg_fetch_row() (a diferença é insignificante).

### Parâmetros

`result`
  Uma instância de PgSql\Result, retornada por pg_query(), pg_query_params() ou pg_execute() (entre outras).
`row`

  Número da linha no resultado a ser buscado. As linhas são numeradas de 0 para cima. Se omitido ou `null`, a próxima linha será buscada.

`class`

  O nome da classe a ser instanciada, definir as propriedades e retornar. Se não for especificado, um objeto stdClass será retornado.

`constructor_args`

  Um array opcional de parâmetros a serem passados ao construtor para objetos `class`.

### Valor Retornado

Um object com um atributo para cada nome de campo no resultado. Os valores `NULL` do banco de dados são retornados como `null`.

`false` é retornado se `row` exceder o número de linhas no conjunto, não houver mais linhas ou em qualquer outro erro.

### Erros/Exceções

Um ValueError é lançado quando o `constructor_args` não está vazio e a classe não possui construtor.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Agora lança uma exceção ValueError quando o `constructor_args` não está vazio e a classe não possui construtor; anteriormente uma Exception era lançada.
8.1.0 | O parâmetro `result` agora espera uma instância de PgSql\Result; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_fetch_object()

    <?php

    $database = "store";

    $db_conn = pg_connect("host=localhost port=5432 dbname=$database");
    if (!$db_conn) {
      echo "Falha ao conectar ao banco de dados postgres $database\n";
      exit;
    }

    $qu = pg_query($db_conn, "SELECT * FROM books ORDER BY author");

    while ($data = pg_fetch_object($qu)) {
      echo $data->author . " (";
      echo $data->year . "): ";
      echo $data->title . "<br />";
    }

    pg_free_result($qu);
    pg_close($db_conn);

    ?>

### Veja Também

- pg_query() - Executa uma consulta
- pg_fetch_array() - Busca uma linha como um array
- pg_fetch_assoc() - Busca uma linha como um array associativo
- pg_fetch_row() - Obtém uma linha como um array enumerado
- pg_fetch_result() - Retorna valores de uma instância de resultado

# pg_fetch_result

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_fetch_result — Retorna valores de uma instância de resultado

### Descrição

function pg_fetch_result(PgSql\Result `$result`, string|false|null `$row`, mixed `$field`): string|false|null
function pg_fetch_result(PgSql\Result `$result`, mixed `$field`): string|false|null

pg_fetch_result() retorna o valor de uma determinada linha e campo (coluna) em uma instância PgSql\Result.

> Nota:

> Esta função costumava ser chamada de pg_result().

### Parâmetros

`result`
  Uma instância de PgSql\Result, retornada por pg_query(), pg_query_params() ou pg_execute() (entre outras).
`row`

  Número da linha no resultado a ser buscado. As linhas são numeradas de 0 para cima. Se omitido, a próxima linha será buscada.

`field`

  Uma string representando o nome do campo (coluna) a ser buscado, caso contrário, um int representando o número do campo a ser buscado. Os campos são numerados de 0 para cima.

### Valor Retornado

Booleano é retornado como "t" ou "f". Todos os outros tipos, incluindo arrays, são retornados como strings formatadas da mesma maneira padrão do PostgreSQL que você veria no programa psql. Os valores `NULL` do banco de dados são retornados como `null`.

`false` é retornado se `row` exceder o número de linhas no conjunto ou em qualquer outro erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | `row` agora é anulável.
8.1.0 | O parâmetro `result` agora espera uma instância de PgSql\Result; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_fetch_result()

    <?php
    $db = pg_connect("dbname=users user=me");

    $res = pg_query($db, "SELECT 1 UNION ALL SELECT 2");

    $val = pg_fetch_result($res, 1, 0);

    echo "O primeiro campo da segunda linha é: ", $val, "\n";
    ?>

O exemplo acima produzirá:

    O primeiro campo da segunda linha é: 2

### Veja Também

- pg_query() - Executa uma consulta
- pg_fetch_array() - Busca uma linha como um array

# pg_fetch_row

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_fetch_row — Obtém uma linha como um array enumerado

### Descrição

function pg_fetch_row(PgSql\Result `$result`, ?int `$row` = `null`, int `$mode` = `PGSQL_NUM`): array|false

pg_fetch_row() busca uma linha de dados do resultado associado à instância `result` especificada.

> Nota: Esta função define campos NULL como o valor `null` do PHP.

### Parâmetros

`result`
  Uma instância de PgSql\Result, retornada por pg_query(), pg_query_params() ou pg_execute() (entre outras).
`row`

  Número da linha no resultado a ser buscado. As linhas são numeradas de 0 para cima. Se omitido ou `null`, a próxima linha será buscada.

`mode`
  Um parâmetro opcional que controla como o array retornado será indexado. `mode` é uma constante e pode assumir os seguintes valores: `PGSQL_ASSOC`, `PGSQL_NUM` e `PGSQL_BOTH`. Usando `PGSQL_NUM`, a função retornará um array com índices numéricos, usando `PGSQL_ASSOC` ela retornará apenas índices associativos enquanto `PGSQL_BOTH` retornará índices numéricos e associativos.

### Valor Retornado

Um array, indexado de 0 para cima, com cada valor representado como uma string. Os valores `NULL` do banco de dados são retornados como `null`.

`false` é retornado se `row` exceder o número de linhas no conjunto, não houver mais linhas ou em qualquer outro erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `result` agora espera uma instância de PgSql\Result; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_fetch_row()

    <?php

    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Ocorreu um erro.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT author, email FROM authors");
    if (!$result) {
      echo "Ocorreu um erro.\n";
      exit;
    }

    while ($row = pg_fetch_row($result)) {
      echo "Autor: $row[0]  E-mail: $row[1]";
      echo "<br />\n";
    }

    ?>

### Veja Também

- pg_query() - Executa uma consulta
- pg_fetch_array() - Busca uma linha como um array
- pg_fetch_object() - Busca uma linha como um objeto
- pg_fetch_result() - Retorna valores de uma instância de resultado

# pg_field_is_null

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_is_null — Testa se um campo é SQL `NULL`

### Descrição

function pg_field_is_null(PgSql\Result `$result`, string|false|null `$row`, mixed `$field`): int
function pg_field_is_null(PgSql\Result `$result`, mixed `$field`): int

pg_field_is_null() testa se um campo em uma instância PgSql\Result é SQL `NULL` ou não.

> Nota:

> Esta função costumava ser chamada de pg_fieldisnull().

### Parâmetros

`result`
  Uma instância de PgSql\Result, retornada por pg_query(), pg_query_params() ou pg_execute() (entre outras).
`row`

  Número da linha no resultado a ser buscado. As linhas são numeradas de 0 para cima. Se omitido, a linha atual será buscada.

`field`

  Número do campo (começando em 0) como um int ou o nome do campo como uma string.

### Valor Retornado

Retorna `1` se o campo na linha fornecida for SQL `NULL`, `0` se não for. `false` é retornado se a linha estiver fora do intervalo ou em caso de qualquer outro erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | `row` agora é anulável.
8.1.0 | O parâmetro `result` agora espera uma instância de PgSql\Result; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_field_is_null()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die ("Não foi possível conectar");
      $res = pg_query($dbconn, "select * from authors where author = 'Orwell'");
      if ($res) {
          if (pg_field_is_null($res, 0, "year") == 1) {
              echo "O valor do campo year é nulo.\n";
          }
          if (pg_field_is_null($res, 0, "year") == 0) {
              echo "O valor do campo year não é nulo.\n";
        }
     }
    ?>

# pg_field_name

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_name — Retorna o nome de um campo

### Descrição

function pg_field_name(PgSql\Result `$result`, int `$field`): string

pg_field_name() retorna o nome do campo que ocupa o `field` fornecido na instância de `result` fornecida. A numeração dos campos começa em 0.

> Nota:

> Esta função costumava ser chamada de pg_fieldname().

### Parâmetros

`result`
  Uma instância de PgSql\Result, retornada por pg_query(), pg_query_params() ou pg_execute() (entre outras).
`field`

  Número do campo, começando em 0.

### Valor Retornado

O nome do campo.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `result` agora espera uma instância de PgSql\Result; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Obtendo informações sobre os campos

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Não foi possível conectar");

      $res = pg_query($dbconn, "select * from authors where author = 'Orwell'");
      $i = pg_num_fields($res);
      for ($j = 0; $j < $i; $j++) {
          echo "coluna $j\n";
          $fieldname = pg_field_name($res, $j);
          echo "nome da coluna: $fieldname\n";
          echo "tamanho impresso: " . pg_field_prtlen($res, $fieldname) . " characters\n";
          echo "tamanho de armazenamento: " . pg_field_size($res, $j) . " bytes\n";
          echo "tipo de campo: " . pg_field_type($res, $j) . " \n\n";
      }
    ?>

O exemplo acima produzirá:

    coluna 0
    nome da coluna: author
    tamanho impresso: 6 characters
    tamanho de armazenamento: -1 bytes
    tipo de campo: varchar

    coluna 1
    nome da coluna: year
    tamanho impresso: 4 characters
    tamanho de armazenamento: 2 bytes
    tipo de campo: int2

    coluna 2
    nome da coluna: title
    tamanho impresso: 24 characters
    tamanho de armazenamento: -1 bytes
    tipo de campo: varchar

### Veja Também

- pg_field_num() - Retorna o número do campo para o campo nomeado

# pg_field_num

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_num — Retorna o número do campo para o campo nomeado

### Descrição

function pg_field_num(PgSql\Result `$result`, string `$field`): int

pg_field_num() retornará o número do campo que corresponde ao `field` na instância de `result` fornecida.

> Nota:

> Esta função costumava ser chamada de pg_fieldnum().

### Parâmetros

`result`
  Uma instância de PgSql\Result, retornada por pg_query(), pg_query_params() ou pg_execute() (entre outras).
`field`

  O nome do campo. O nome fornecido é tratado como um identificador em um comando SQL, ou seja, é colocado em minúscula, a menos que esteja entre aspas duplas.

### Valor Retornado

O número do campo (numerado de 0) ou -1 em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `result` agora espera uma instância de PgSql\Result; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Obtendo informações sobre os campos

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Não foi possível conectar");

      $res = pg_query($dbconn, "select author, year, title from authors where author = 'Orwell'");

      echo "A coluna 'title' é o campo número: ", pg_field_num($res, 'title');
    ?>

O exemplo acima produzirá:

    A coluna 'title' é o campo número: 2

### Veja Também

- pg_field_name() - Retorna o nome de um campo

# pg_field_prtlen

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_prtlen — Retorna o comprimento impresso

### Descrição

function pg_field_prtlen(PgSql\Result `$result`, string|false|null `$row`, mixed `$field_name_or_number`): int
function pg_field_prtlen(PgSql\Result `$result`, mixed `$field_name_or_number`): int

pg_field_prtlen() retorna o comprimento real impresso (número de caracteres) de um valor específico em um `result` do PostgreSQL. A numeração das linhas começa em 0. Esta função retornará `false` em caso de erro.

`field_name_or_number` pode ser passado como um int ou como uma string. Se for passado como int, o PHP o reconhece como o número do campo, caso contrário, como o nome do campo.

Veja o exemplo dado na página pg_field_name().

> Nota:

> Esta função costumava ser chamada de pg_fieldprtlen().

### Parâmetros

`result`
  Uma instância de PgSql\Result, retornada por pg_query(), pg_query_params() ou pg_execute() (entre outras).
`row`

  Número da linha no resultado. As linhas são numeradas de 0 para cima. Se omitido, a linha atual será buscada.

### Valor Retornado

O comprimento impresso do campo.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | `row` agora é anulável.
8.1.0 | O parâmetro `result` agora espera uma instância de PgSql\Result; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Obtendo informações sobre campos

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Could not connect");

      $res = pg_query($dbconn, "select * from authors where author = 'Orwell'");
      $i = pg_num_fields($res);
      for ($j = 0; $j < $i; $j++) {
          echo "column $j\n";
          $fieldname = pg_field_name($res, $j);
          echo "fieldname: $fieldname\n";
          echo "printed length: " . pg_field_prtlen($res, $fieldname) . " characters\n";
          echo "storage length: " . pg_field_size($res, $j) . " bytes\n";
          echo "field type: " . pg_field_type($res, $j) . " \n\n";
      }
    ?>

O exemplo acima produzirá:

    column 0
    fieldname: author
    printed length: 6 characters
    storage length: -1 bytes
    field type: varchar

    column 1
    fieldname: year
    printed length: 4 characters
    storage length: 2 bytes
    field type: int2

    column 2
    fieldname: title
    printed length: 24 characters
    storage length: -1 bytes
    field type: varchar

### Veja Também

- pg_field_size() - Retorna o tamanho de armazenamento interno do campo nomeado

# pg_field_size

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_size — Retorna o tamanho de armazenamento interno do campo nomeado

### Descrição

function pg_field_size(PgSql\Result `$result`, int `$field`): int

pg_field_size() retorna o tamanho do armazenamento interno (em bytes) do número do campo no `result` do PostgreSQL fornecido.

> Nota:

> Esta função costumava ser chamada de pg_fieldsize().

### Parâmetros

`result`
  Uma instância de PgSql\Result, retornada por pg_query(), pg_query_params() ou pg_execute() (entre outras).
`field`

  Número do campo, começando em 0.

### Valor Retornado

O tamanho do armazenamento do campo interno (em bytes). -1 indica um campo de comprimento variável.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `result` agora espera uma instância de PgSql\Result; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Obtendo informações sobre campos

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Não foi possível conectar");

      $res = pg_query($dbconn, "select * from authors where author = 'Orwell'");
      $i = pg_num_fields($res);
      for ($j = 0; $j < $i; $j++) {
          echo "coluna $j\n";
          $fieldname = pg_field_name($res, $j);
          echo "nome do campo: $fieldname\n";
          echo "comprimento impresso: " . pg_field_prtlen($res, $fieldname) . " caracteres\n";
          echo "comprimento de armazenamento: " . pg_field_size($res, $j) . " bytes\n";
          echo "tipo do campo: " . pg_field_type($res, $j) . " \n\n";
      }
    ?>

O exemplo acima produzirá:

    coluna 0
    nome do campo: author
    comprimento impresso: 6 caracteres
    comprimento de armazenamento: -1 bytes
    tipo do campo: varchar

    coluna 1
    nome do campo: year
    comprimento impresso: 4 caracteres
    comprimento de armazenamento: 2 bytes
    tipo do campo: int2

    coluna 2
    nome do campo: title
    comprimento impresso: 24 caracteres
    comprimento de armazenamento: -1 bytes
    tipo do campo: varchar

### Veja Também

- pg_field_prtlen() - Retorna o comprimento impresso
- pg_field_type() - Retorna o nome do tipo para o número do campo correspondente

# pg_field_table

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

pg_field_table — Retorna o nome ou oid do campo da tabela

### Descrição

function pg_field_table(PgSql\Result `$result`, int `$field`, bool `$oid_only` = `false`): string|int|false

pg_field_table() retorna o nome da tabela à qual o campo pertence, ou o oid da tabela se `oid_only` for `true`.

### Parâmetros

`result`
  Uma instância de PgSql\Result, retornada por pg_query(), pg_query_params() ou pg_execute() (entre outras).
`field`

  Número do campo, começando em 0.

`oid_only`

  Por padrão, o nome da tabela à qual o campo pertence é retornado, mas se `oid_only` estiver definido como `true`, então o oid será retornado.

### Valor Retornado

Em caso de sucesso, o nome da tabela de campos ou oid, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `result` agora espera uma instância de PgSql\Result; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Obtendo informações da tabela sobre um campo

    <?php
    $dbconn = pg_connect("dbname=publisher") or die("Não foi possível conectar");

    $res = pg_query($dbconn, "SELECT bar FROM foo");

    echo pg_field_table($res, 0);
    echo pg_field_table($res, 0, true);

    $res = pg_query($dbconn, "SELECT version()");
    var_dump(pg_field_table($res, 0));
    ?>

O exemplo acima produzirá algo semelhante a:

    foo
    14379580

    bool(false)

### Notas

> Nota:

> Retornar o oid é muito mais rápido do que retornar o nome da tabela porque buscar o nome da tabela requer uma consulta à tabela do sistema do banco de dados.

### Veja Também

- pg_field_name() - Retorna o nome de um campo
- pg_field_type() - Retorna o nome do tipo para o número do campo correspondente

# pg_field_type

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_type — Retorna o nome do tipo para o número do campo correspondente

### Descrição

function pg_field_type(PgSql\Result `$result`, int `$field`): string

pg_field_type() retorna uma string contendo o nome do tipo base do `field` na instância de `result` fornecida.

> Nota:

> Se o campo usar um domínio PostgreSQL (em vez de um tipo básico), será retornado o nome do tipo subjacente do domínio, e não o nome do próprio domínio.

> Nota:

> Esta função costumava ser chamada de pg_fieldtype().

### Parâmetros

`result`
  Uma instância de PgSql\Result, retornada por pg_query(), pg_query_params() ou pg_execute() (entre outras).
`field`

  Número do campo, começando em 0.

### Valor Retornado

Uma string contendo o nome base do tipo do campo.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `result` agora espera uma instância de PgSql\Result; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Obtendo informações sobre campos

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Não foi possível conectar");

      // Suponha que 'título' seja um tipo varchar
      $res = pg_query($dbconn, "select title from authors where author = 'Orwell'");

      echo "Tipo de campo: ", pg_field_type($res, 0);
    ?>

O exemplo acima produzirá:

    Tipo de campo: varchar

### Veja Também

- pg_field_prtlen() - Retorna o comprimento impresso
- pg_field_name() - Retorna o nome de um campo
- pg_field_type_oid() - Retorna o ID do tipo (OID) para o número do campo correspondente

# pg_field_type_oid

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_field_type_oid — Retorna o ID do tipo (OID) para o número do campo correspondente

### Descrição

function pg_field_type_oid(PgSql\Result `$result`, int `$field`): string|int

pg_field_type_oid() retorna um número inteiro contendo o OID do tipo base do `field` fornecido na instância de `result` fornecida.

Você pode obter mais informações sobre o tipo de campo consultando a tabela de sistema `pg_type` do PostgreSQL usando o OID obtido com esta função. A função format_type() do PostgreSQL converterá um tipo OID em um nome de tipo padrão SQL.

> Nota:

> Se o campo usar um domínio PostgreSQL (em vez de um tipo básico), será retornado o OID do tipo subjacente do domínio, e não o OID do próprio domínio.

### Parâmetros

`result`
  Uma instância de PgSql\Result, retornada por pg_query(), pg_query_params() ou pg_execute() (entre outras).
`field`

  Número do campo, começando em 0.

### Valor Retornado

O OID do tipo base do campo.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `result` agora espera uma instância de PgSql\Result; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Obtendo informações sobre campos

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Não foi possível conectar");

      // Suponha que 'title' seja um tipo varchar
      $res = pg_query($dbconn, "select title from authors where author = 'Orwell'");

      echo "Campo title de tipo OID: ", pg_field_type_oid($res, 0);
    ?>

O exemplo acima produzirá:

    Campo title de tipo OID: 1043

### Veja Também

- pg_field_type() - Retorna o nome do tipo para o número do campo correspondente
- pg_field_prtlen() - Retorna o comprimento impresso
- pg_field_name() - Retorna o nome de um campo

# pg_flush

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_flush — Libera dados de consulta de saída na conexão

### Descrição

function pg_flush(PgSql\Connection `$connection`): int|bool

pg_flush() libera quaisquer dados de consulta de saída aguardando para serem enviados na conexão.

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.

### Valor Retornado

Retorna `true` se a liberação foi bem-sucedida ou nenhum dado estava esperando para ser liberado, `0` se parte dos dados pendentes foi liberada, mas restam mais ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

# pg_free_result

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_free_result — Libera memória de resultados

### Descrição

function pg_free_result(PgSql\Result `$result`): bool

pg_free_result() libera a memória e os dados associados à instância PgSql\Result especificada.

Esta função só precisa ser chamada se o consumo de memória durante a execução do script for um problema. Caso contrário, toda a memória de resultados será liberada automaticamente quando o script terminar.

> Nota:

> Esta função costumava ser chamada de pg_freeresult().

### Parâmetros

`result`
  Uma instância de PgSql\Result, retornada por pg_query(), pg_query_params() ou pg_execute() (entre outras).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `result` agora espera uma instância de PgSql\Result; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_free_result()

    <?php
    $db = pg_connect("dbname=users user=me");

    $res = pg_query($db, "SELECT 1 UNION ALL SELECT 2");

    $val = pg_fetch_result($res, 1, 0);

    echo "O primeiro campo da segunda linha é: ", $val, "\n";

    pg_free_result($res);
    ?>

O exemplo acima produzirá:

    O primeiro campo da segunda linha é: 2

### Veja Também

- pg_query() - Executa uma consulta
- pg_query_params() - Envia um comando ao servidor e aguarda o resultado, com a capacidade de passar parâmetros separadamente do texto do comando SQL
- pg_execute() - Envia uma solicitação para executar uma instrução preparada com determinados parâmetros e aguarda o resultado
- pg_result_memory_size() - Retorna a quantidade de memória alocada para um resultado de consulta

# pg_get_notify

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_get_notify — Obtém mensagem SQL NOTIFY

### Descrição

function pg_get_notify(PgSql\Connection `$connection`, int `$mode` = `PGSQL_ASSOC`): array|false

pg_get_notify() obtém notificações geradas por um comando SQL `NOTIFY`. Para receber notificações, o comando SQL `LISTEN` deve ser emitido.

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.
`mode`
  Um parâmetro opcional que controla como o array retornado será indexado. `mode` é uma constante e pode assumir os seguintes valores: `PGSQL_ASSOC`, `PGSQL_NUM` e `PGSQL_BOTH`. Usando `PGSQL_NUM`, a função retornará um array com índices numéricos, usando `PGSQL_ASSOC` ela retornará apenas índices associativos enquanto `PGSQL_BOTH` retornará índices numéricos e associativos.

### Valor Retornado

Um array contendo o nome da mensagem `NOTIFY` e o PID de backend. Se for compatível com o servidor, o array também conterá a versão do servidor e a carga útil. Caso contrário, se nenhum `NOTIFY` estiver aguardando, então `false` é retornado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Mensagem NOTIFY do PostgreSQL

    <?php
    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Um erro ocorreu.\n";
      exit;
    }

    // Ouve a mensagem 'author_updated' de outros processos
    pg_query($conn, 'LISTEN author_updated;');
    $notify = pg_get_notify($conn);
    if (!$notify) {
      echo "Sem mensagens\n";
    } else {
      print_r($notify);
    }
    ?>

### Veja Também

- pg_get_pid() - Obtém o ID do processo do backend

# pg_get_pid

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_get_pid — Obtém o ID do processo do backend

### Descrição

function pg_get_pid(PgSql\Connection `$connection`): int

pg_get_pid() obtém o PID do backend (processo do servidor de banco de dados). O PID é útil para determinar se uma mensagem `NOTIFY` recebida via pg_get_notify() é enviada de outro processo ou não.

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.

### Valor Retornado

O ID do processo do banco de dados backend.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 PID de backend do PostgreSQL

    <?php
    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Ocorreu um erro.\n";
      exit;
    }

    // PID do processo de backend. Use PID com pg_get_notify()
    $pid = pg_get_pid($conn);
    ?>

### Veja Também

- pg_get_notify() - Obtém mensagem SQL NOTIFY

# pg_get_result

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_get_result — Obtém o resultado da consulta assíncrona

### Descrição

function pg_get_result(PgSql\Connection `$connection`): PgSql\Result|false

pg_get_result() obtém uma instância de PgSql\Result de uma consulta assíncrona executada por pg_send_query(), pg_send_query_params() ou pg_send_execute().

pg_send_query() e outras funções de consulta assíncrona podem enviar múltiplas consultas para um servidor PostgreSQL e pg_get_result() é usado para obter os resultados de cada consulta, um por um.

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.

### Valor Retornado

Uma instância PgSql\Result ou `false` se não houver mais resultados disponíveis.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Agora retorna uma instância de PgSql\Result; anteriormente, um resource era retornado.
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_get_result()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Não foi possível conectar");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from authors; select count(*) from authors;");
      }

      $res1 = pg_get_result($dbconn);
      echo "Primeira chamada para pg_get_result(): $res1\n";
      $rows1 = pg_num_rows($res1);
      echo "$res1 has $rows1 records\n\n";

      $res2 = pg_get_result($dbconn);
      echo "Segunda chamada para pg_get_result(): $res2\n";
      $rows2 = pg_num_rows($res2);
      echo "$res2 has $rows2 records\n";
    ?>

O exemplo acima produzirá:

    Primeira chamada para pg_get_result(): Resource id #3
    Resource id #3 has 3 records

    Segunda chamada para pg_get_result(): Resource id #4
    Resource id #4 has 1 records

### Veja Também

- pg_send_query() - Envia consulta assíncrona

# pg_host

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_host — Retorna o nome do host associado à conexão

### Descrição

function pg_host(?PgSql\Connection `$connection` = `null`): string

pg_host() retorna o nome do host da instância de `connection` do PostgreSQL à qual está conectada.

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` for `null`, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

### Valor Retornado

Uma string contendo o nome do host ao qual a `connection` está, ou uma string vazia em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.
8.0.0 | `connection` agora é anulável.

### Exemplos

Exemplo #1 Exemplo de pg_host()

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
       print "Conectado com sucesso a: " . pg_host($pgsql_conn) . "<br/>\n";
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

### Veja Também

- pg_connect() - Abre uma conexão PostgreSQL
- pg_pconnect() - Abre uma conexão PostgreSQL persistente

# pg_insert

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_insert — Insere array na tabela

### Descrição

function pg_insert(
PgSql\Connection `$connection`,
string `$table_name`,
array `$values`,
int `$flags` = `PGSQL_DML_EXEC`
): PgSql\Result|string|bool

pg_insert() insere os valores de `values` na tabela especificada por `table_name`.

Se `flags` for especificado, pg_convert() será aplicado aos `values` com as opções (flags) especificadas.

Por padrão, pg_insert() passa valores brutos. Os valores devem ser escapados ou a opção `PGSQL_DML_ESCAPE` deve ser especificado em `flags`. `PGSQL_DML_ESCAPE` cita e escapa parâmetros/identificadores. Portanto, os nomes de tabelas/colunas diferenciam maiúsculas de minúsculas.

Observe que nem o escape nem a consulta preparada podem proteger consultas LIKE, JSON, Array, Regex, etc. Esses parâmetros devem ser tratados de acordo com seus contextos. ou seja, escapar/validar valores.

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.
`table_name`

  Nome da tabela na qual inserir linhas. A tabela `table_name` deve ter pelo menos tantas colunas quanto `values` tem elementos.

`values`

  Um array cujas chaves são nomes de campos na tabela `table_name`, e cujos valores são os valores dos campos que serão inseridos.

`flags`

  Qualquer número de `PGSQL_CONV_OPTS`, `PGSQL_DML_NO_CONV`, `PGSQL_DML_ESCAPE`, `PGSQL_DML_EXEC`, `PGSQL_DML_ASYNC` ou `PGSQL_DML_STRING` combinados. Se `PGSQL_DML_STRING` fizer parte dos `flags` então a string de consulta será retornada. Quando `PGSQL_DML_NO_CONV` ou `PGSQL_DML_ESCAPE` está definido, ele não chama pg_convert() internamente.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.. Ou retorna um string em caso de sucesso se `PGSQL_DML_STRING` for passado via `flags`.

### Erros/Exceções

Um ValueError é lançado quando a tabela especificada é inválida.

Um ValueError ou TypeError é lançado quando o valor ou tipo de campo não corresponde corretamente ao tipo do PostgreSQL.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Agora lança um erro ValueError quando a tabela especificada é inválida; anteriormente um `E_WARNING` era emitido.
8.3.0 | Agora lança um erro ValueError ou TypeError quando o valor ou tipo de campo não corresponde corretamente ao tipo do PostgreSQL; anteriormente um `E_WARNING` era emitido.
8.1.0 | Agora retorna uma instância de PgSql\Result; anteriormente, um resource era retornado.
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_insert()

    <?php
      $dbconn = pg_connect('dbname=foo');
      // Isso é um tanto seguro, já que todos os valores têm escape.
      // No entanto, o PostgreSQL suporta JSON/Array. Estes não são
      // seguros nem por escape nem por consulta preparada.
      $res = pg_insert($dbconn, 'post_log', $_POST, PGSQL_DML_ESCAPE);
      if ($res) {
          echo "Os dados POST foram registrados com sucesso\n";
      } else {
          echo "Usuário deve ter enviado entradas erradas\n";
      }
    ?>

### Veja Também

- pg_convert() - Converte valores de array associativo em formas adequadas para instruções SQL

# pg_jit

(PHP 8 >= 8.4.0)

pg_jit — Retorna as informações JIT do servidor

### Descrição

function pg_jit(?PgSql\Connection `$connection` = `null`): array

pg_jit() retorna um array com as informações de compilação JIT (Just-In-Time) do servidor PostgreSQL.

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` for `null`, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

### Valor Retornado

Retorna um array contendo as informações JIT do servidor.

### Veja Também

- pg_version() - Retorna um array com versão do cliente, protocolo e servidor (quando disponível)

# pg_last_error

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_last_error — Obtém a última string da mensagem de erro de uma conexão

### Descrição

function pg_last_error(?PgSql\Connection `$connection` = `null`): string

pg_last_error() retorna a última mensagem de erro para uma determinada `connection`.

As mensagens de erro podem ser substituídas por chamadas de função internas do PostgreSQL (libpq). Pode não retornar uma mensagem de erro apropriada se ocorrerem vários erros dentro de uma função do módulo PostgreSQL.

Use pg_result_error(), pg_result_error_field(), pg_result_status() e pg_connection_status() para melhor tratamento de erros.

> Nota:

> Esta função costumava ser chamada de pg_errormessage().

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` for `null`, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

### Valor Retornado

Uma string contendo a última mensagem de erro na `connection` fornecida.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.
8.0.0 | `connection` agora é anulável.

### Exemplos

Exemplo #1 Exemplo de pg_last_error()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Não foi possível conectar");

      // Consulta que falha
      $res = pg_query($dbconn, "select * from doesnotexist");

      echo pg_last_error($dbconn);
    ?>

### Veja Também

- pg_result_error() - Obtém mensagem de erro associada ao resultado
- pg_result_error_field() - Retorna um campo individual de um relatório de erros

# pg_last_notice

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

pg_last_notice — Retorna a última mensagem de aviso do servidor PostgreSQL

### Descrição

function pg_last_notice(PgSql\Connection `$connection`, int `$mode` = `PGSQL_NOTICE_LAST`): array|string|bool

pg_last_notice() retorna a última mensagem de aviso do servidor PostgreSQL na especificada `connection`. O servidor PostgreSQL envia mensagens de aviso em vários casos, por exemplo ao criar uma coluna `SERIAL` em uma tabela.

Com pg_last_notice(), você pode evitar a emissão de consultas inúteis verificando se o aviso está ou não relacionado à sua transação.

O rastreamento de mensagens de aviso pode ser definido como opcional definindo 1 para `pgsql.ignore_notice` no php.ini.

O registro de mensagens de aviso pode ser definido como opcional definindo 0 para `pgsql.log_notice` no php.ini. A menos que `pgsql.ignore_notice` esteja definido como 0, a mensagem de aviso não pode ser registrada.

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.
`mode`

  Um dos `PGSQL_NOTICE_LAST` (para retornar o último aviso), `PGSQL_NOTICE_ALL` (para retornar todos os avisos) ou `PGSQL_NOTICE_CLEAR` (para limpar avisos).

### Valor Retornado

Uma string contendo o último aviso na `connection` fornecida com `PGSQL_NOTICE_LAST`, um array com `PGSQL_NOTICE_ALL`, um bool com `PGSQL_NOTICE_CLEAR`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.
7.1.0 | O parâmetro `mode` foi adicionado.

### Exemplos

Exemplo #1 Exemplo de pg_last_notice()

    <?php
      $pgsql_conn = pg_connect("dbname=mark host=localhost");

      $res = pg_query("CREATE TABLE test (id SERIAL)");

      $notice = pg_last_notice($pgsql_conn);

      echo $notice;
    ?>

O exemplo acima produzirá:

    CREATE TABLE will create implicit sequence "test_id_seq" for "serial" column "test.id"

### Veja Também

- pg_query() - Executa uma consulta
- pg_last_error() - Obtém a última string da mensagem de erro de uma conexão

# pg_last_oid

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_last_oid — Retorna o OID da última linha

### Descrição

function pg_last_oid(PgSql\Result `$result`): string|int|false

pg_last_oid() é usado para recuperar o OID atribuído a uma linha inserida.

O campo OID tornou-se um campo opcional no PostgreSQL 7.2 e não estará presente por padrão no PostgreSQL 8.1. Quando o campo OID não está presente em uma tabela, o programador deve usar pg_result_status() para verificar se a inserção foi bem-sucedida.

Para obter o valor de um campo `SERIAL` em uma linha inserida, é necessário utilizar a função `CURRVAL` do PostgreSQL, nomeando a sequência cujo último valor é requerido. Se o nome da sequência for desconhecido, a função `pg_get_serial_sequence` do PostgreSQL 8.0 é necessária.

O PostgreSQL 8.1 possui uma função `LASTVAL` que retorna o valor da sequência usada mais recentemente na sessão. Isso evita a necessidade de nomear completamente a sequência, tabela ou coluna.

> Nota:

> Esta função costumava ser chamada de pg_getlastoid().

### Parâmetros

`result`
  Uma instância de PgSql\Result, retornada por pg_query(), pg_query_params() ou pg_execute() (entre outras).

### Valor Retornado

Um int ou string contendo o OID atribuído à linha inserida mais recentemente na `connection` especificada, ou `false` por erro ou nenhum OID disponível.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `result` agora espera uma instância de PgSql\Result; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_last_oid()

    <?php
      // Conecta ao banco de dados
      pg_connect("dbname=mark host=localhost");

      // Cria uma tabela de exemplo
      pg_query("CREATE TABLE test (a INTEGER) WITH OIDS");

      // Insira alguns dados nela
      $res = pg_query("INSERT INTO test VALUES (1)");

      $oid = pg_last_oid($res);
    ?>

### Veja Também

- pg_query() - Executa uma consulta
- pg_result_status() - Obtém o status do resultado da consulta

# pg_lo_close

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_close — Fecha um objeto grande

### Descrição

function pg_lo_close(PgSql\Lob `$lob`): bool

pg_lo_close() fecha um objeto grande.

Para usar a interface de objeto grande, é necessário incluí-la em um bloco de transação.

> Nota:

> Esta função costumava ser chamada de pg_loclose().

### Parâmetros

`lob`
  Uma instância de PgSql\Lob, retornada por pg_lo_open().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `lob` agora espera uma instância de PgSql\Lob; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_lo_close()

    <?php
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $oid = pg_lo_create($database);
       echo "$oid\n";
       $handle = pg_lo_open($database, $oid, "w");
       echo "$handle\n";
       pg_lo_write($handle, "large object data");
       pg_lo_close($handle);
       pg_query($database, "commit");
    ?>

### Veja Também

- pg_lo_open() - Abra um objeto grande
- pg_lo_create() - Cria um objeto grande
- pg_lo_import() - Importa um objeto grande do arquivo

# pg_lo_create

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_create — Cria um objeto grande

### Descrição

function pg_lo_create(PgSql\Connection `$connection` = ?, mixed `$object_id` = ?): int
function pg_lo_create(mixed `$object_id`): int

pg_lo_create() cria um objeto grande e retorna o OID do objeto grande. Os modos de acesso do PostgreSQL `INV_READ` e `INV_WRITE` não são suportados, o objeto é criado sempre com acesso de leitura e gravação.

Para usar a interface de objeto grande, é necessário incluí-la em um bloco de transação.

Em vez de usar a interface de objeto grande (que não tem controles de acesso e é complicada de usar), experimente o tipo de coluna bytea e pg_escape_bytea() do PostgreSQL.

> Nota:

> Esta função costumava ser chamada de pg_locreate().

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` não for especificado, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

`object_id`

  Se um `object_id` for fornecido, a função tentará criar um objeto grande com este id, caso contrário, um id de objeto livre será atribuído pelo servidor.

### Valor Retornado

Um objeto grande OID, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_lo_create()

    <?php
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $oid = pg_lo_create($database);
       echo "$oid\n";
       $handle = pg_lo_open($database, $oid, "w");
       echo "$handle\n";
       pg_lo_write($handle, "large object data");
       pg_lo_close($handle);
       pg_query($database, "commit");
    ?>

# pg_lo_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_export — Exporta um objeto grande para arquivo

### Descrição

function pg_lo_export(PgSql\Connection `$connection` = ?, int `$oid`, string `$filename`): bool

pg_lo_export() pega um objeto grande em um banco de dados PostgreSQL e salva seu conteúdo em um arquivo no sistema de arquivos local.

Para usar a interface de objeto grande, é necessário incluí-la em um bloco de transação.

> Nota:

> Esta função costumava ser chamada de pg_loexport().

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` não for especificado, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

`oid`

  O OID do objeto grande no banco de dados.

`filename`

  O caminho completo e o nome do arquivo no qual gravar o objeto grande no sistema de arquivos do cliente.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_lo_export()

    <?php
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $oid = pg_lo_create($database);
       $handle = pg_lo_open($database, $oid, "w");
       pg_lo_write($handle, "large object data");
       pg_lo_close($handle);
       pg_lo_export($database, $oid, '/tmp/lob.dat');
       pg_query($database, "commit");
    ?>

### Veja Também

- pg_lo_import() - Importa um objeto grande do arquivo

# pg_lo_import

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_import — Importa um objeto grande do arquivo

### Descrição

function pg_lo_import(PgSql\Connection `$connection` = ?, string `$filename`, int|string `$oid` = ?): int|string|false

pg_lo_import() cria um novo objeto grande no banco de dados usando um arquivo no sistema de arquivos como fonte de dados.

Para usar a interface de objeto grande, é necessário incluí-la em um bloco de transação.

> Nota:

> Esta função costumava ser chamada de pg_loimport().

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` não for especificado, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

`filename`

  O caminho completo e o nome do arquivo no sistema de arquivos do cliente a partir do qual serão lidos os dados do objeto grande.

`oid`

  Se um `oid` for fornecido, a função tentará criar um objeto grande com este id, caso contrário, um id de objeto livre será atribuído pelo servidor. O parâmetro depende da funcionalidade que apareceu pela primeira vez no PostgreSQL 8.1.

### Valor Retornado

O OID do objeto grande recém-criado, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_lo_import()

    <?php
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $oid = pg_lo_import($database, '/tmp/lob.dat');
       pg_query($database, "commit");
    ?>

### Veja Também

- pg_lo_export() - Exporta um objeto grande para arquivo
- pg_lo_open() - Abra um objeto grande

# pg_lo_open

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_open — Abra um objeto grande

### Descrição

function pg_lo_open(PgSql\Connection `$connection`, int `$oid`, string `$mode`): PgSql\Lob|false

pg_lo_open() abre um objeto grande no banco de dados e retorna uma instância PgSql\Lob para que possa ser manipulado.

Aviso

Não feche a conexão com o banco de dados antes de fechar a instância PgSql\Lob.

Para usar a interface de objeto grande, é necessário incluí-la em um bloco de transação.

> Nota:

> Esta função costumava ser chamada de pg_loopen().

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` não for especificado, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

`oid`

  O OID do objeto grande no banco de dados.

`mode`

  Pode ser "r" para somente leitura, "w" para somente gravação ou "rw" para leitura e gravação.

### Valor Retornado

Uma instância PgSql\Lob, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Retorna uma instância PgSql\Lob agora; anteriormente, um resource era retornado.
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_lo_open()

    <?php
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $oid = pg_lo_create($database);
       echo "$oid\n";
       $handle = pg_lo_open($database, $oid, "w");
       echo "$handle\n";
       pg_lo_write($handle, "large object data");
       pg_lo_close($handle);
       pg_query($database, "commit");
    ?>

### Veja Também

- pg_lo_close() - Fecha um objeto grande
- pg_lo_create() - Cria um objeto grande

# pg_lo_read

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_read — Lê um objeto grande

### Descrição

function pg_lo_read(PgSql\Lob `$lob`, int `$length` = 8192): string|false

pg_lo_read() lê no máximo `length` bytes de um objeto grande e o retorna como uma string.

Para usar a interface de objeto grande, é necessário incluí-la em um bloco de transação.

> Nota:

> Esta função costumava ser chamada de pg_loread().

### Parâmetros

`lob`
  Uma instância de PgSql\Lob, retornada por pg_lo_open().
`length`

  Um número máximo opcional de bytes a serem retornados.

### Valor Retornado

Uma string contendo bytes de `length` do objeto grande, ou `false` por erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `lob` agora espera uma instância de PgSql\Lob; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_lo_read()

    <?php
       $doc_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $doc_oid, "r");
       $data = pg_lo_read($handle, 50000);
       pg_query($database, "commit");
       echo $data;
    ?>

### Veja Também

- pg_lo_read_all() - Lê um objeto grande inteiro e envia direto para o navegador

# pg_lo_read_all

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_read_all — Lê um objeto grande inteiro e envia direto para o navegador

### Descrição

function pg_lo_read_all(PgSql\Lob `$lob`): int

pg_lo_read_all() lê um objeto grande e o passa direto para o navegador após enviar todos os cabeçalhos pendentes. Destinado principalmente ao envio de dados binários como imagens ou som.

Para usar a interface de objeto grande, é necessário incluí-la em um bloco de transação.

> Nota:

> Esta função costumava ser chamada de pg_loreadall().

### Parâmetros

`lob`
  Uma instância de PgSql\Lob, retornada por pg_lo_open().

### Valor Retornado

Número de bytes lidos.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `lob` agora espera uma instância de PgSql\Lob; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_lo_read_all()

    <?php
       header('Content-type: image/jpeg');
       $image_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $image_oid, "r");
       pg_lo_read_all($handle);
       pg_query($database, "commit");
    ?>

### Veja Também

- pg_lo_read() - Lê um objeto grande

# pg_lo_seek

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_seek — Aponta para posição dentro de um objeto grande

### Descrição

function pg_lo_seek(PgSql\Lob `$lob`, int `$offset`, int `$whence` = `SEEK_CUR`): bool

pg_lo_seek() seeks a position within an PgSql\Lob instance.

Para usar a interface de objeto grande, é necessário incluí-la em um bloco de transação.

### Parâmetros

`lob`
  Uma instância de PgSql\Lob, retornada por pg_lo_open().
`offset`

  A posição em bytes para apontar.

`whence`

  Uma das constantes `PGSQL_SEEK_SET` (aponta a partir do início do objeto), `PGSQL_SEEK_CUR` (aponta a partir da posição atual) ou `PGSQL_SEEK_END` (aponta a partir do final do objeto).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `lob` agora espera uma instância de PgSql\Lob; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_lo_seek()

    <?php
       $doc_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $doc_oid, "r");
       // Ignora os primeiros 50.000 bytes
       pg_lo_seek($handle, 50000, PGSQL_SEEK_SET);
       // Lê os próximos 10.000 bytes
       $data = pg_lo_read($handle, 10000);
       pg_query($database, "commit");
       echo $data;
    ?>

### Veja Também

- pg_lo_tell() - Retorna a posição de busca atual a de um objeto grande

# pg_lo_tell

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_tell — Retorna a posição de busca atual a de um objeto grande

### Descrição

function pg_lo_tell(PgSql\Lob `$lob`): int

pg_lo_tell() retorna a posição atual (deslocamento do início) de um objeto grande.

Para usar a interface de objeto grande, é necessário incluí-la em um bloco de transação.

### Parâmetros

`lob`
  Uma instância de PgSql\Lob, retornada por pg_lo_open().

### Valor Retornado

O deslocamento de busca atual (em número de bytes) desde o início do objeto grande. Se houver um erro, o valor de retorno será negativo.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `lob` agora espera uma instância de PgSql\Lob; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_lo_tell()

    <?php
       $doc_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $doc_oid, "r");
       // Ignora os primeiros 50.000 bytes
       pg_lo_seek($handle, 50000, PGSQL_SEEK_SET);
       // Vê o quão longe nós pulamos
       $offset = pg_lo_tell($handle);
       echo "A posição de busca é: $offset";
       pg_query($database, "commit");
    ?>

O exemplo acima produzirá:

    A posição de busca é: 50000

### Veja Também

- pg_lo_seek() - Aponta para posição dentro de um objeto grande

# pg_lo_truncate

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_lo_truncate — Trunca um objeto grande

### Descrição

function pg_lo_truncate(PgSql\Lob `$lob`, int `$size`): bool

pg_lo_truncate() truncates an PgSql\Lob instance.

Para usar a interface de objeto grande, é necessário incluí-la em um bloco de transação.

### Parâmetros

`lob`
  Uma instância de PgSql\Lob, retornada por pg_lo_open().
`size`

  O número de bytes a serem truncados.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `lob` agora espera uma instância de PgSql\Lob; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_lo_truncate()

    <?php
       $doc_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $doc_oid, "r");
       // Trunca para 0
       pg_lo_truncate($handle, 0);
       pg_query($database, "commit");
       echo $data;
    ?>

### Veja Também

- pg_lo_tell() - Retorna a posição de busca atual a de um objeto grande

# pg_lo_unlink

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_unlink — Exclui um objeto grande

### Descrição

function pg_lo_unlink(PgSql\Connection `$connection`, int `$oid`): bool

pg_lo_unlink() exclui um objeto grande com o `oid`. Retorna `true` em caso de sucesso ou `false` em caso de falha.

Para usar a interface de objeto grande, é necessário incluí-la em um bloco de transação.

> Nota:

> Esta função costumava ser chamada de pg_lounlink().

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` não for especificado, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

`oid`

  O OID do objeto grande no banco de dados.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_lo_unlink()

    <?php
       // OID do objeto grande a ser excluído
       $doc_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       pg_lo_unlink($database, $doc_oid);
       pg_query($database, "commit");
    ?>

### Veja Também

- pg_lo_create() - Cria um objeto grande
- pg_lo_import() - Importa um objeto grande do arquivo

# pg_lo_write

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_write — Escreve em um objeto grande

### Descrição

function pg_lo_write(PgSql\Lob `$lob`, string `$data`, ?int `$length` = `null`): int|false

pg_lo_write() grava dados em um objeto grande na posição de busca atual.

Para usar a interface de objeto grande, é necessário incluí-la em um bloco de transação.

> Nota:

> Esta função costumava ser chamada de pg_lowrite().

### Parâmetros

`lob`
  Uma instância de PgSql\Lob, retornada por pg_lo_open().
`data`

  Os dados a serem gravados no objeto grande. Se `length` for um int e for menor que o comprimento de `data`, apenas os bytes de `length` serão gravados.

`length`

  Um número máximo opcional de bytes a serem gravados. Deve ser maior que zero e não maior que o comprimento dos `data`. O padrão é o comprimento dos `data`.

### Valor Retornado

O número de bytes gravados no objeto grande, ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `lob` agora espera uma instância de PgSql\Lob; anteriormente, um resource era esperado.
8.0.0 | `length` agora é anulável.

### Exemplos

Exemplo #1 Exemplo de pg_lo_write()

    <?php
       $doc_oid = 189762345;
       $data = "Isto irá substituir o início do objeto grande.";
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $doc_oid, "w");
       $data = pg_lo_write($handle, $data);
       pg_query($database, "commit");
    ?>

### Veja Também

- pg_lo_create() - Cria um objeto grande
- pg_lo_open() - Abra um objeto grande

# pg_meta_data

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_meta_data — Obtém metadados para tabela

### Descrição

function pg_meta_data(PgSql\Connection `$connection`, string `$table_name`, bool `$extended` = `false`): array|false

pg_meta_data() retorna a definição de tabela para `table_name` como um array.

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.
`table_name`

  O nome da tabela.

`extended`

  Opção para retornar metadados estendidos. O padrão é `false`.

### Valor Retornado

Um array da definição da tabela, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Obtendo metadados da tabela

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Não foi possível conectar");

      $meta = pg_meta_data($dbconn, 'authors');
      if (is_array($meta)) {
          echo '<pre>';
          var_dump($meta);
          echo '</pre>';
      }
    ?>

O exemplo acima produzirá:

    array(3) {
    ["author"]=>
    array(5) {
      ["num"]=>
      int(1)
      ["type"]=>
      string(7) "varchar"
      ["len"]=>
      int(-1)
      ["not null"]=>
      bool(false)
      ["has default"]=>
      bool(false)
    }
    ["year"]=>
    array(5) {
      ["num"]=>
      int(2)
      ["type"]=>
      string(4) "int2"
      ["len"]=>
      int(2)
      ["not null"]=>
      bool(false)
      ["has default"]=>
      bool(false)
    }
    ["title"]=>
    array(5) {
      ["num"]=>
      int(3)
      ["type"]=>
      string(7) "varchar"
      ["len"]=>
      int(-1)
      ["not null"]=>
      bool(false)
      ["has default"]=>
      bool(false)
    }
    }

### Veja Também

- pg_convert() - Converte valores de array associativo em formas adequadas para instruções SQL

# pg_num_fields

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_num_fields — Retorna o número de campos em um resultado

### Descrição

function pg_num_fields(PgSql\Result `$result`): int

pg_num_fields() retorna o número de campos (colunas) na instância PgSql\Result.

> Nota:

> Esta função costumava ser chamada de pg_numfields().

### Parâmetros

`result`
  Uma instância de PgSql\Result, retornada por pg_query(), pg_query_params() ou pg_execute() (entre outras).

### Valor Retornado

O número de campos (colunas) no resultado. Em caso de erro, -1 é retornado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `result` agora espera uma instância de PgSql\Result; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_num_fields()

    <?php
    $result = pg_query($conn, "SELECT 1, 2");

    $num = pg_num_fields($result);

    echo $num . " campo(s) retornado(s).\n";
    ?>

O exemplo acima produzirá:

    2 campo(s) retornado(s).

### Veja Também

- pg_num_rows() - Retorna o número de linhas em um resultado
- pg_affected_rows() - Retorna o número de registros afetados (tuplas)

# pg_num_rows

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_num_rows — Retorna o número de linhas em um resultado

### Descrição

function pg_num_rows(PgSql\Result `$result`): int

pg_num_rows() retornará o número de linhas em uma instância PgSql\Result.

> Nota:

> Esta função costumava ser chamada de pg_numrows().

### Parâmetros

`result`
  Uma instância de PgSql\Result, retornada por pg_query(), pg_query_params() ou pg_execute() (entre outras).

### Valor Retornado

O número de linhas no resultado. Em caso de erro, `-1` é retornado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `result` agora espera uma instância de PgSql\Result; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_num_rows()

    <?php
    $result = pg_query($conn, "SELECT 1");

    $rows = pg_num_rows($result);

    echo $rows . " linha(s) retornada(s).\n";
    ?>

O exemplo acima produzirá:

    1 linha(s) retornada(s).

### Veja Também

- pg_num_fields() - Retorna o número de campos em um resultado
- pg_affected_rows() - Retorna o número de registros afetados (tuplas)

# pg_options

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_options — Obtém as opções associadas à conexão

### Descrição

function pg_options(?PgSql\Connection `$connection` = `null`): string

pg_options() retornará uma string contendo as opções especificadas na instância de `connection` do PostgreSQL fornecida.

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` for `null`, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

### Valor Retornado

Uma string contendo as opções de `connection`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.
8.0.0 | `connection` agora é anulável.

### Exemplos

Exemplo #1 Exemplo de pg_options()

    <?php
       $pgsql_conn = pg_connect("dbname=mark host=localhost");
       echo pg_options($pgsql_conn);
    ?>

### Veja Também

- pg_connect() - Abre uma conexão PostgreSQL

# pg_parameter_status

(PHP 5, PHP 7, PHP 8)

pg_parameter_status — Procura uma configuração de parâmetro atual do servidor

### Descrição

function pg_parameter_status(PgSql\Connection `$connection` = ?, string `$name`): string|false

Procura uma configuração de parâmetro atual do servidor.

Certos valores de parâmetros são reportados automaticamente pelo servidor na inicialização da conexão ou sempre que seus valores mudam. pg_parameter_status() pode ser usado para interrogar essas configurações. Ele retorna o valor atual de um parâmetro, se conhecido, ou `false` se o parâmetro não for conhecido.

Os parâmetros relatados pelo servidor incluem `server_version`, `server_encoding`, `client_encoding`, `is_superuser`, `session_authorization`, `DateStyle`, `TimeZone` e `integer_datetimes`. Observe que `server_version`, `server_encoding` e `integer_datetimes` não podem ser alterados após a inicialização do PostgreSQL.

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` não for especificado, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

`name`

  Os possíveis valores de `name` incluem `server_version`, `server_encoding`, `client_encoding`, `is_superuser`, `session_authorization`, `DateStyle`, `TimeZone` e `integer_datetimes`. Observe que esse valor diferencia maiúsculas de minúsculas.

### Valor Retornado

Uma string contendo o valor do parâmetro, `false` em caso de falha ou `name` inválido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_parameter_status()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Não foi possível conectar");

      echo "Codificação de servidor: ", pg_parameter_status($dbconn, "server_encoding");
    ?>

O exemplo acima produzirá:

    Codificação de servidor: SQL_ASCII

# pg_pconnect

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_pconnect — Abre uma conexão PostgreSQL persistente

### Descrição

function pg_pconnect(string `$connection_string`, int `$flags` = 0): PgSql\Connection|false

pg_pconnect() abre uma conexão com um banco de dados PostgreSQL. Ele retorna uma instância PgSql\Connection que é necessária para outras funções do PostgreSQL.

Se uma segunda chamada for feita para pg_pconnect() com o mesmo `connection_string` de uma conexão existente, a conexão existente será retornada a menos que você passe `PGSQL_CONNECT_FORCE_NEW` como `flags`.

Para ativar a conexão persistente, a diretiva pgsql.allow_persistent no php.ini deve ser definida como `"On"` (que é o padrão). O número máximo de conexões persistentes pode ser definido com a diretiva pgsql.max_persistent no php.ini (o padrão é `-1` para nenhum limite). O número total de conexões pode ser definido com a diretiva pgsql.max_links no php.ini.

pg_close() não irá fechar conexões persistentes geradas por pg_pconnect().

### Parâmetros

`connection_string`

  O `connection_string` pode estar vazio para usar todos os parâmetros padrão ou pode conter uma ou mais configurações de parâmetro separadas por espaços em branco. Cada configuração de parâmetro está no formato `palavra-chave = valor`. Os espaços ao redor do sinal de igual são opcionais. Para escrever um valor vazio ou contendo espaços, coloque-o entre aspas simples, por exemplo, `palavra-chave = 'um valor'`. Aspas simples e barras invertidas dentro do valor devem ser escapadas com uma barra invertida, ou seja, `\'` e `\\`.

  As palavras-chave de parâmetro atualmente reconhecidas são: `host`, `hostaddr`, `port`, `dbname`, `user`, `password`, `connect_timeout`, `options`, `tty` (ignorada), `sslmode`, `requiressl` (descontinuada em favor de `sslmode`), e `service`. Quais desses argumentos existem depende da sua versão do PostgreSQL.

`flags`

  Se `PGSQL_CONNECT_FORCE_NEW` for passado, então uma nova conexão será criada, mesmo que `connection_string` seja idêntico a uma conexão existente.

### Valor Retornado

Retorna uma instância PgSql\Connection em caso de sucesso, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Retorna uma instância PgSql\Connection agora; anteriormente, um resource era retornado.

### Exemplos

Exemplo #1 Usando pg_pconnect()

    <?php
    // Conecta a um banco de dados chamado "mary"
    $dbconn = pg_pconnect("dbname=mary");

    // Conecta a um banco de dados chamado "mary" em "localhost" na porta "5432"
    $dbconn2 = pg_pconnect("host=localhost port=5432 dbname=mary");

    // Conecta a um banco de dados chamado "mary" no host "sheep" com usuário e senha
    $dbconn3 = pg_pconnect("host=sheep port=5432 dbname=mary user=lamb password=foo");

    //Conecta a um banco de dados chamado "test" no host "sheep" com usuário e senha
    $conn_string = "host=sheep port=5432 dbname=test user=lamb password=bar";
    $dbconn4 = pg_pconnect($conn_string);
    ?>

### Veja Também

- pg_connect() - Abre uma conexão PostgreSQL
- Conexões de banco de dados persistentes

# pg_ping

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_ping — Ping em conexão com banco de dados

### Descrição

function pg_ping(?PgSql\Connection `$connection` = `null`): bool

pg_ping() executa ping em uma conexão de banco de dados e tenta reconectá-la se ela estiver interrompida.

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` for `null`, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.
8.0.0 | `connection` é anulável agora.

### Exemplos

Exemplo #1 Exemplo de pg_ping()

    <?php
    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Ocorreu um erro.\n";
      exit;
    }

    if (!pg_ping($conn))
      die("A conexão está quebrada\n");
    ?>

### Veja Também

- pg_connection_status() - Obtém o status da conexão
- pg_connection_reset() - Redefine conexão (reconecta)

# pg_port

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_port — Retorne o número da porta associada à conexão

### Descrição

function pg_port(?PgSql\Connection `$connection` = `null`): string

pg_port() retorna o número da porta à qual a instância de `connection` do PostgreSQL está conectada.

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` for `null`, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

### Valor Retornado

Uma string contendo o número da porta do servidor de banco de dados ao qual a `connection` está, ou uma string vazia em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.
8.0.0 | `connection` agora é anulável.

### Exemplos

Exemplo #1 Exemplo de pg_port()

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
       print "Conectado com sucesso à porta: " . pg_port($pgsql_conn) . "<br/>\n";
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

# pg_prepare

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_prepare — Envia uma solicitação ao servidor para criar uma instrução preparada com os parâmetros fornecidos e aguarda a conclusão

### Descrição

function pg_prepare(PgSql\Connection `$connection` = ?, string `$statement_name`, string `$query`): PgSql\Result|false

pg_prepare() cria uma instrução preparada para execução posterior com pg_execute() ou pg_send_execute(). Este recurso permite que comandos que serão usados repetidamente sejam analisados e planejados apenas uma vez, em vez de cada vez que forem executados.

A função cria uma instrução preparada chamada `statement_name` a partir da string `query`, que deve conter um único comando SQL. `statement_name` pode ser `""` para criar uma instrução sem nome, caso em que qualquer instrução sem nome pré-existente é automaticamente substituída; caso contrário, será um erro se o nome da instrução já estiver definido na sessão atual. Se algum parâmetro for usado, ele será referido na `query` como `$1`, `$2` etc.

Instruções preparadas para uso com pg_prepare() também podem ser criadas executando instruções SQL `PREPARE`. (Mas pg_prepare() é mais flexível, pois não requer que os tipos de parâmetros sejam pré-especificados.) Além disso, embora não exista uma função PHP para excluir uma instrução preparada, a declaração SQL `DEALLOCATE` pode ser usada para esse propósito.

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` não for especificado, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

`statement_name`

  O nome para dar a declaração preparada. Deve ser exclusivo por conexão. Se `""` for especificado, uma instrução sem nome será criada, substituindo qualquer instrução sem nome definida anteriormente.

`query`

  A instrução SQL parametrizada. Deve conter apenas uma única instrução (múltiplas instruções separadas por ponto e vírgula não são permitidas). Se algum parâmetro for usado, ele será chamado de `$1`, `$2` etc.

### Valor Retornado

Uma instância PgSql\Result em caso de sucesso, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Agora retorna uma instância de PgSql\Result; anteriormente, um resource era retornado.
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Usando pg_prepare()

    <?php

    // Conecta a um banco de dados chamado "mary"
    $dbconn = pg_connect("dbname=mary");

    // Prepara uma consulta para execução
    $result = pg_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name = $1');

    // Executa a consulta preparada. Observe que não é necessário escapar
    // a string "Joe's Widgets" de forma alguma
    $result = pg_execute($dbconn, "my_query", array("Joe's Widgets"));

    // Executa a mesma consulta preparada, desta vez com um parâmetro diferente
    $result = pg_execute($dbconn, "my_query", array("Clothes Clothes Clothes"));

    ?>

### Veja Também

- pg_execute() - Envia uma solicitação para executar uma instrução preparada com determinados parâmetros e aguarda o resultado
- pg_send_execute() - Envia uma solicitação para executar uma instrução preparada com determinados parâmetros, sem esperar pelo(s) resultado(s)

# pg_put_copy_data

(PHP 8 >= 8.4.0)

pg_put_copy_data — Envia dados para o servidor durante uma operação COPY

### Descrição

function pg_put_copy_data(PgSql\Connection `$connection`, string `$cmd`): int

Envia dados para o servidor durante uma operação de `COPY FROM STDIN` Um comando `COPY` deve ter sido emitido via pg_query() antes de chamar esta função.

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.
`cmd`
  Os dados a serem enviados para o servidor. Uma nova linha final é adicionada automaticamente se não estiver presente. Os dados devem ser formatados de acordo com o formato do comando `COPY`.

### Valor Retornado

Retorna `1` em caso de sucesso, `0` se os dados não puderem ser enfileirados (somente no modo não bloqueante) ou `-1` em caso de erro.

### Veja Também

- pg_put_copy_end() - Sinaliza a conclusão de uma operação COPY para o servidor
- pg_query() - Executa uma consulta

# pg_put_copy_end

(PHP 8 >= 8.4.0)

pg_put_copy_end — Sinaliza a conclusão de uma operação COPY para o servidor

### Descrição

function pg_put_copy_end(PgSql\Connection `$connection`, ?string `$error` = `null`): int

Envia uma indicação de fim de dados para o servidor durante uma operação de `COPY FROM STDIN`.

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.
`error`
  Se não for `null`, a operação `COPY` será forçada a falhar com a mensagem de erro fornecida.

### Valor Retornado

Retorna `1` em caso de sucesso, `0` se os dados não puderem ser enfileirados (somente no modo não bloqueante) ou `-1` em caso de erro.

### Veja Também

- pg_put_copy_data() - Envia dados para o servidor durante uma operação COPY
- pg_query() - Executa uma consulta

# pg_put_line

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_put_line — Envia uma string terminada em NULL para o backend do PostgreSQL

### Descrição

function pg_put_line(PgSql\Connection `$connection` = ?, string `$query`): bool

pg_put_line() envia uma string terminada em NULL para o servidor backend do PostgreSQL. Isto é necessário em conjunto com o comando `COPY FROM` do PostgreSQL.

`COPY` é uma interface de carregamento de dados de alta velocidade suportada pelo PostgreSQL. Os dados são transmitidos sem serem analisados e em uma única transação.

Uma alternativa ao uso de comandos pg_put_line() brutos é usar pg_copy_from(). Esta é uma interface muito mais simples.

> Nota:

> A aplicação deve enviar explicitamente os dois caracteres "\." na última linha para indicar ao backend que terminou de enviar seus dados, antes de emitir pg_end_copy().

Aviso

O uso de pg_put_line() faz com que a maioria das operações de objetos grandes, incluindo pg_lo_read() e pg_lo_tell(), falhem posteriormente. Você pode usar pg_copy_from() e pg_copy_to() no lugar.

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` não for especificado, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

`query`

  Uma linha de texto a ser enviada diretamente para o backend do PostgreSQL. Um terminador `NULL` é adicionado automaticamente.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_put_line()

    <?php
      $conn = pg_pconnect("dbname=foo");
      pg_query($conn, "create table bar (a int4, b char(16), d float8)");
      pg_query($conn, "copy bar from stdin");
      pg_put_line($conn, "3\thello world\t4.5\n");
      pg_put_line($conn, "4\tgoodbye world\t7.11\n");
      pg_put_line($conn, "\\.\n");
      pg_end_copy($conn);
    ?>

### Veja Também

- pg_end_copy() - Sincroniza com back-end do PostgreSQL

# pg_query

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_query — Executa uma consulta

### Descrição

function pg_query(PgSql\Connection `$connection` = ?, string `$query`): PgSql\Result|false

pg_query() executa a `query` na `connection` do banco de dados especificado. pg_query_params() deve ser preferido na maioria dos casos.

Se ocorrer um erro e `false` for retornado, os detalhes do erro poderão ser recuperados usando a função pg_last_error() se a conexão for válida.

> Nota: Embora `connection` possa ser omitido, isso não é recomendado, pois pode ser a causa de erros difíceis de encontrar em scripts.

> Nota:

> Esta função costumava ser chamada de pg_exec(). pg_exec() ainda está disponível por motivos de compatibilidade, mas os usuários são incentivados a usar o nome mais recente.

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` não for especificado, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

`query`

  A instrução ou instruções SQL a serem executadas. Quando múltiplas instruções são passadas para a função, elas são automaticamente executadas como uma transação, a menos que haja comandos BEGIN/COMMIT explícitos incluídos na string de consulta. No entanto, não é recomendado usar múltiplas transações em uma chamada de função.

  Aviso

  A interpolação de strings de dados fornecidos pelo usuário é extremamente perigosa e provavelmente levará a vulnerabilidades de injeção de SQL. Na maioria dos casos, pg_query_params() deve ser preferido, passando valores fornecidos pelo usuário como parâmetros em vez de substituí-los na string de consulta.

  Quaisquer dados fornecidos pelo usuário substituídos diretamente em uma string de consulta devem ser escapados corretamente.

### Valor Retornado

Uma instância PgSql\Result em caso de sucesso, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Agora retorna uma instância de PgSql\Result; anteriormente, um resource era retornado.
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_query()

    <?php

    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Ocorreu um erro.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT author, email FROM authors");
    if (!$result) {
      echo "Ocorreu um erro.\n";
      exit;
    }

    while ($row = pg_fetch_row($result)) {
      echo "Autor: $row[0]  E-mail: $row[1]";
      echo "<br />\n";
    }

    ?>

Exemplo #2 Usando pg_query() com múltiplas instruções

    <?php

    $conn = pg_pconnect("dbname=publisher");

    // essas instruções serão executadas como uma transação

    $query = "UPDATE authors SET author=UPPER(author) WHERE id=1;";
    $query .= "UPDATE authors SET author=LOWER(author) WHERE id=2;";
    $query .= "UPDATE authors SET author=NULL WHERE id=3;";

    pg_query($conn, $query);

    ?>

### Veja Também

- pg_connect() - Abre uma conexão PostgreSQL
- pg_pconnect() - Abre uma conexão PostgreSQL persistente
- pg_fetch_array() - Busca uma linha como um array
- pg_fetch_object() - Busca uma linha como um objeto
- pg_num_rows() - Retorna o número de linhas em um resultado
- pg_affected_rows() - Retorna o número de registros afetados (tuplas)

# pg_query_params

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_query_params — Envia um comando ao servidor e aguarda o resultado, com a capacidade de passar parâmetros separadamente do texto do comando SQL

### Descrição

function pg_query_params(PgSql\Connection `$connection` = ?, string `$query`, array `$params`): PgSql\Result|false

Envia um comando ao servidor e aguarda o resultado, podendo passar parâmetros separadamente do texto do comando SQL.

pg_query_params() é como pg_query(), mas oferece funcionalidade adicional: os valores dos parâmetros podem ser especificados separadamente da string de comando propriamente dita.

Se parâmetros forem usados, eles serão referidos na string `query` como $1, $2, etc. O mesmo parâmetro pode aparecer mais de uma vez na `query`; o mesmo valor será usado nesse caso. `params` especifica os valores reais dos parâmetros. Um valor `null` neste array significa que o parâmetro correspondente é SQL `NULL`.

A principal vantagem de pg_query_params() sobre pg_query() é que os valores dos parâmetros podem ser separados da string `query`, evitando assim a necessidade de tarefas tediosas e propensas a erros de escape. Ao contrário de pg_query(), pg_query_params() permite no máximo um comando SQL na string fornecida. (Pode haver ponto-e-vírgula, mas não mais do que um comando não vazio.)

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` não for especificado, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

`query`

  A instrução SQL parametrizada. Deve conter apenas uma única instrução. (múltiplas instruções separadas por ponto e vírgula não são permitidas.) Se algum parâmetro for usado, ele será chamado de $1, $2, etc.

  Os valores fornecidos pelo usuário devem sempre ser passados como parâmetros, não interpolados na string de consulta, onde formam possíveis vetores de ataque de injeção de SQL e introduzem bugs ao manipular dados contendo aspas. Se por algum motivo você não puder usar um parâmetro, certifique-se de que os valores interpolados foram escapados corretamente.

`params`

  Um array de valores de parâmetros para substituir os espaços reservados $1, $2, etc. na string de consult original preparada. O número de elementos no array deve corresponder ao número de espaços reservados.

  Valores destinados a campos `bytea` não são suportados como parâmetros. Use pg_escape_bytea() ou use as funções de objetos grandes.

### Valor Retornado

Uma instância PgSql\Result em caso de sucesso, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Agora retorna uma instância de PgSql\Result; anteriormente, um resource era retornado.
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Usando pg_query_params()

    <?php
    // Conecta a um banco de dados chamado "mary"
    $dbconn = pg_connect("dbname=mary");

    // Encontre todas as lojas chamadas Joe's Widgets. Observe que não é necessário
    // escapar "Joe's Widgets"
    $result = pg_query_params($dbconn, 'SELECT * FROM shops WHERE name = $1', array("Joe's Widgets"));

    // Compara com apenas o uso de pg_query
    $str = pg_escape_string("Joe's Widgets");
    $result = pg_query($dbconn, "SELECT * FROM shops WHERE name = '{$str}'");

    ?>

### Veja Também

- pg_query() - Executa uma consulta

# pg_result_error

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_result_error — Obtém mensagem de erro associada ao resultado

### Descrição

function pg_result_error(PgSql\Result `$result`): string|false

pg_result_error() retorna qualquer mensagem de erro associada à instância de `result`. Portanto, o usuário tem mais chances de receber a mensagem de erro correta do que com pg_last_error().

A função pg_result_error_field() pode fornecer muito mais detalhes sobre erros de resultados do que pg_result_error().

Porque pg_query() retorna `false` se a consulta falhar, você deverá usar pg_send_query() e pg_get_result() para obter o identificador do resultado.

### Parâmetros

`result`
  Uma instância de PgSql\Result, retornada por pg_query(), pg_query_params() ou pg_execute() (entre outras).

### Valor Retornado

Retorna uma string. Retorna uma string vazia se não houver erro. Se houver um erro associado ao parâmetro `result`, retorna `false`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `result` agora espera uma instância de PgSql\Result; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_result_error()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Não foi possível conectar");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from doesnotexist;");
      }

      $res1 = pg_get_result($dbconn);
      echo pg_result_error($res1);
    ?>

### Veja Também

- pg_result_error_field() - Retorna um campo individual de um relatório de erros
- pg_query() - Executa uma consulta
- pg_send_query() - Envia consulta assíncrona
- pg_get_result() - Obtém o resultado da consulta assíncrona
- pg_last_error() - Obtém a última string da mensagem de erro de uma conexão
- pg_last_notice() - Retorna a última mensagem de aviso do servidor PostgreSQL

# pg_result_error_field

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_result_error_field — Retorna um campo individual de um relatório de erros

### Descrição

function pg_result_error_field(PgSql\Result `$result`, int `$field_code`): string|false|null

pg_result_error_field() retorna um dos campos de mensagem de erro detalhados associados à instância de `result`. O campo de erro é especificado pelo `field_code`.

Porque pg_query() e pg_query_params() retornam `false` se a consulta falhar, você deverá usar pg_send_query() e pg_get_result() para obter o identificador do resultado.

Se você precisar obter informações adicionais sobre erros de consultas pg_query() com falha, use pg_set_error_verbosity() e pg_last_error() e então analise o resultado.

### Parâmetros

`result`
  Uma instância de PgSql\Result, retornada por pg_query(), pg_query_params() ou pg_execute() (entre outras).
`field_code`

  Os possíveis valores de `field_code` são: `PGSQL_DIAG_SEVERITY`, `PGSQL_DIAG_SQLSTATE`, `PGSQL_DIAG_MESSAGE_PRIMARY`, `PGSQL_DIAG_MESSAGE_DETAIL`, `PGSQL_DIAG_MESSAGE_HINT`, `PGSQL_DIAG_STATEMENT_POSITION`, `PGSQL_DIAG_INTERNAL_POSITION`, `PGSQL_DIAG_INTERNAL_QUERY`, `PGSQL_DIAG_CONTEXT`, `PGSQL_DIAG_SOURCE_FILE`, `PGSQL_DIAG_SOURCE_LINE` ou `PGSQL_DIAG_SOURCE_FUNCTION`.

### Valor Retornado

Uma string contendo o conteúdo do campo de erro, `null` se o campo não existir ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `result` agora espera uma instância de PgSql\Result; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_result_error_field()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Não foi possível conectar");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from doesnotexist;");
      }

      $res1 = pg_get_result($dbconn);
      echo pg_result_error_field($res1, PGSQL_DIAG_SQLSTATE);
    ?>

### Veja Também

- pg_result_error() - Obtém mensagem de erro associada ao resultado

# pg_result_memory_size

(PHP 8 >= 8.4.0)

pg_result_memory_size — Retorna a quantidade de memória alocada para um resultado de consulta

### Descrição

function pg_result_memory_size(PgSql\Result `$result`): int

Retorna a quantidade de memória, em bytes, alocada para a instância do resultado de consulta PgSql\Result. Este valor é a mesma quantidade que seria liberada por pg_free_result().

### Parâmetros

`result`
  Uma instância de PgSql\Result, retornada por pg_query(), pg_query_params() ou pg_execute() (entre outras).

### Valor Retornado

Retorna a quantidade de memória em bytes.

### Exemplos

Exemplo #1 Exemplo de pg_result_memory_size()

    <?php
    $db = pg_connect("dbname=users user=me");

    $res = pg_query($db, 'SELECT 1');

    $size = pg_result_memory_size($res);

    var_dump($size);
    ?>

O exemplo acima produzirá algo semelhante a:

    int(3288)

### Veja Também

- pg_free_result() - Libera memória de resultados

# pg_result_seek

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_result_seek — Define deslocamento interno de linha na instância de resultado

### Descrição

function pg_result_seek(PgSql\Result `$result`, int `$row`): bool

pg_result_seek() define o deslocamento interno da linha na instância do `result`.

### Parâmetros

`result`
  Uma instância de PgSql\Result, retornada por pg_query(), pg_query_params() ou pg_execute() (entre outras).
`row`

  Linha para mover o deslocamento interno na instância PgSql\Result. As linhas são numeradas começando do zero.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `result` agora espera uma instância de PgSql\Result; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_result_seek()

    <?php

    // Conecta ao banco de dados
    $conn = pg_pconnect("dbname=publisher");

    // Executa a consulta
    $result = pg_query($conn, "SELECT author, email FROM authors");

    // Busca a 3ª linha (assumindo que existem 3 linhas)
    pg_result_seek($result, 2);

    // Busca a 3ª linha
    $row = pg_fetch_row($result);

    ?>

### Veja Também

- pg_fetch_row() - Obtém uma linha como um array enumerado
- pg_fetch_assoc() - Busca uma linha como um array associativo
- pg_fetch_array() - Busca uma linha como um array
- pg_fetch_object() - Busca uma linha como um objeto
- pg_fetch_result() - Retorna valores de uma instância de resultado

# pg_result_status

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_result_status — Obtém o status do resultado da consulta

### Descrição

function pg_result_status(PgSql\Result `$result`, int `$mode` = `PGSQL_STATUS_LONG`): string|int

pg_result_status() retorna o status da instância PgSql\Result ou a tag de conclusão do comando PostgreSQL associada ao resultado.

### Parâmetros

`result`
  Uma instância de PgSql\Result, retornada por pg_query(), pg_query_params() ou pg_execute() (entre outras).
`mode`

  Pode ser a constante `PGSQL_STATUS_LONG` para retornar o status numérico de `result` ou a constante `PGSQL_STATUS_STRING` para retornar a etiqueta de comando de `result`. Se não for especificado, `PGSQL_STATUS_LONG` é o padrão.

### Valor Retornado

Os possíveis valores de retorno são `PGSQL_EMPTY_QUERY`, `PGSQL_COMMAND_OK`, `PGSQL_TUPLES_OK`, `PGSQL_TUPLES_CHUNK`, `PGSQL_COPY_OUT`, `PGSQL_COPY_IN`, `PGSQL_BAD_RESPONSE`, `PGSQL_NONFATAL_ERROR` e `PGSQL_FATAL_ERROR` se `PGSQL_STATUS_LONG` for especificado. Caso contrário, uma string contendo a etiqueta de comando do PostgreSQL será retornada.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `result` agora espera uma instância de PgSql\Result; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_result_status()

    <?php

    // Conecta ao banco de dados
    $conn = pg_pconnect("dbname=publisher");

    // Executa um COPY
    $result = pg_query($conn, "COPY authors FROM STDIN;");

    // Obtém o status do resultado
    $status = pg_result_status($result);

    // Determina o status
    if ($status == PGSQL_COPY_IN)
       echo "A cópia começou.";
    else
       echo "Falha na cópia.";

    ?>

O exemplo acima produzirá:

    A cópia começou.

### Veja Também

- pg_connection_status() - Obtém o status da conexão

# pg_select

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_select — Seleciona registros

### Descrição

function pg_select(
PgSql\Connection `$connection`,
string `$table_name`,
array `$conditions` = [],
int `$flags` = `PGSQL_DML_EXEC`,
int `$mode` = `PGSQL_ASSOC`
): array|string|false

pg_select() seleciona registros especificados por `conditions` que tem `field=>value`. Para uma consulta bem-sucedida, ele retorna um array contendo todos os registros e campos que correspondem à condição especificada por `conditions`.

Se `flags` estiver definido, pg_convert() será aplicado às `conditions` com as opções (flags) especificadas.

Se `mode` for definido, o valor de retorno estará na forma de um array com `PGSQL_NUM`, um array associativo com `PGSQL_ASSOC` (padrão) ou ambos com `PGSQL_BOTH`.

Por padrão, pg_select() passa valores brutos. Os valores devem ter escape ou a opção PGSQL_DML_ESCAPE deve ser especificada. PGSQL_DML_ESCAPE cita e escapa parâmetros/identificadores. Portanto, os nomes de tabelas/colunas tornaram-se sensíveis a maiúsculas e minúsculas.

Observe que nem o escape nem a consulta preparada podem proteger a consulta LIKE, JSON, Array, Regex, etc. Esses parâmetros devem ser tratados de acordo com seus contextos. ou seja, escapar/validar valores.

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.
`table_name`

  Nome da tabela da qual selecionar linhas.

`conditions`

  Um array cujas chaves são nomes de campos na tabela `table_name` e cujos valores são as condições que uma linha deve atender para ser recuperada. A partir do PHP 8.4.0, quando um array vazio for fornecido, nenhuma condição será aplicada. Anteriormente, a função falhava com um argumento `conditions` vazio.

`flags`

  Qualquer número de `PGSQL_CONV_FORCE_NULL`, `PGSQL_DML_NO_CONV`, `PGSQL_DML_ESCAPE`, `PGSQL_DML_EXEC`, `PGSQL_DML_ASYNC` ou `PGSQL_DML_STRING` combinado. Se `PGSQL_DML_STRING` fizer parte dos `flags` então a string de consulta será retornada. Quando `PGSQL_DML_NO_CONV` ou `PGSQL_DML_ESCAPE` está definido, ele não chama pg_convert() internamente.

`mode`

  Qualquer número de `PGSQL_ASSOC`, `PGSQL_NUM` ou `PGSQL_BOTH` Se `PGSQL_ASSOC` for definido o valor de retorno será um array associativo, com `PGSQL_NUM` o valor de retorno será um array , e com `PGSQL_BOTH` o valor de retorno será um array associativo e indexado numericamente.

### Valor Retornado

Retorna string se `PGSQL_DML_STRING` for passado via `flags`, caso contrário, retorna um array em caso de sucesso, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `conditions` agora é opcional.
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.
7.1.0 | O parâmetro `mode` foi adicionado.

### Exemplos

Exemplo #1 Exemplo de pg_select()

    <?php
      $db = pg_connect('dbname=foo');
      // Isso é um tanto seguro, já que todos os valores têm escape.
      // No entanto, o PostgreSQL suporta JSON/Array. Estes não são
      // seguros nem por escape nem por consulta preparada.
      $rec = pg_select($db, 'post_log', $_POST, PG_DML_ESCAPE);
      if ($rec) {
          echo "Registros selecionados\n";
          var_dump($rec);
      } else {
          echo "Usuário deve ter enviado entradas erradas\n";
      }
    ?>

### Veja Também

- pg_convert() - Converte valores de array associativo em formas adequadas para instruções SQL

# pg_send_execute

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_send_execute — Envia uma solicitação para executar uma instrução preparada com determinados parâmetros, sem esperar pelo(s) resultado(s)

### Descrição

function pg_send_execute(PgSql\Connection `$connection`, string `$statement_name`, array `$params`): int|bool

Envia uma solicitação para executar uma instrução preparada com determinados parâmetros, sem esperar pelo(s) resultado(s).

Isto é semelhante a pg_send_query_params(), mas o comando a ser executado é especificado nomeando uma instrução previamente preparada, em vez de fornecer uma string de consulta. Os parâmetros da função são tratados de forma idêntica a pg_execute(). Assim como pg_execute(), não funcionará em versões anteriores à 7.4 do PostgreSQL.

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.
`statement_name`

  O nome da instrução preparada a ser executada. Se "" for especificado, a instrução sem nome será executada. O nome deve ter sido preparado previamente usando pg_prepare(), pg_send_prepare() ou um comando SQL `PREPARE`.

`params`

  Um array de valores de parâmetros para substituir os espaços reservados $1, $2, etc. na string de consulta preparada original. O número de elementos no array deve corresponder ao número de espaços reservados.

### Valor Retornado

Retorna `true` em caso de sucesso, `false` ou `0` em caso de falha. Use pg_get_result() para determinar o resultado da consulta.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Usando pg_send_execute()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Não foi possível conectar");

      // Preparar uma consulta para execução
      if (!pg_connection_busy($dbconn)) {
        pg_send_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name = $1');
        $res1 = pg_get_result($dbconn);
      }

      // Execute a consulta preparada. Observe que não é necessário escapar
      // a string "Joe's Widgets" de nenhuma forma
      if (!pg_connection_busy($dbconn)) {
        pg_send_execute($dbconn, "my_query", array("Joe's Widgets"));
        $res2 = pg_get_result($dbconn);
      }

      // Execute a mesma consulta preparada, desta vez com um parâmetro diferente
      if (!pg_connection_busy($dbconn)) {
        pg_send_execute($dbconn, "my_query", array("Clothes Clothes Clothes"));
        $res3 = pg_get_result($dbconn);
      }

    ?>

### Veja Também

- pg_prepare() - Envia uma solicitação ao servidor para criar uma instrução preparada com os parâmetros fornecidos e aguarda a conclusão
- pg_send_prepare() - Envia uma solicitação para criar uma instrução preparada com os parâmetros fornecidos, sem esperar pela conclusão
- pg_execute() - Envia uma solicitação para executar uma instrução preparada com determinados parâmetros e aguarda o resultado

# pg_send_prepare

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_send_prepare — Envia uma solicitação para criar uma instrução preparada com os parâmetros fornecidos, sem esperar pela conclusão

### Descrição

function pg_send_prepare(PgSql\Connection `$connection`, string `$statement_name`, string `$query`): int|bool

Envia uma solicitação para criar uma instrução preparada com os parâmetros fornecidos, sem aguardar a conclusão.

Esta é uma versão assíncrona de pg_prepare(): ela retorna `true` se conseguiu despachar a solicitação e `false` se não. Após uma chamada bem-sucedida, chame pg_get_result() para determinar se o servidor criou com êxito a instrução preparada. Os parâmetros da função são tratados de forma idêntica a pg_prepare(). Assim como pg_prepare(), não funcionará em versões anteriores à 7.4 do PostgreSQL.

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.
`statement_name`

  O nome para dar a declaração preparada. Deve ser exclusivo por conexão. Se "" for especificado, uma instrução sem nome será criada, substituindo qualquer instrução sem nome definida anteriormente.

`query`

  A instrução SQL parametrizada. Deve conter apenas uma única instrução. (múltiplas instruções separadas por ponto e vírgula não são permitidas.) Se algum parâmetro for usado, ele será chamado de $1, $2, etc.

### Valor Retornado

Retorna `true` em caso de sucesso, `false` ou `0` em caso de falha. Use pg_get_result() para determinar o resultado da consulta.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Usando pg_send_prepare()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Não foi possível conectar");

      // Prepara uma consulta para execução
      if (!pg_connection_busy($dbconn)) {
        pg_send_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name = $1');
        $res1 = pg_get_result($dbconn);
      }

      // Executa a consulta preparada. Observe que não é necessário escapar
      // a string "Joe's Widgets" de qualquer forma
      if (!pg_connection_busy($dbconn)) {
        pg_send_execute($dbconn, "my_query", array("Joe's Widgets"));
        $res2 = pg_get_result($dbconn);
      }

      // Executa a mesma consulta preparada, desta vez com um parâmetro diferente
      if (!pg_connection_busy($dbconn)) {
        pg_send_execute($dbconn, "my_query", array("Clothes Clothes Clothes"));
        $res3 = pg_get_result($dbconn);
      }

    ?>

### Veja Também

- pg_connect() - Abre uma conexão PostgreSQL
- pg_pconnect() - Abre uma conexão PostgreSQL persistente
- pg_execute() - Envia uma solicitação para executar uma instrução preparada com determinados parâmetros e aguarda o resultado
- pg_send_execute() - Envia uma solicitação para executar uma instrução preparada com determinados parâmetros, sem esperar pelo(s) resultado(s)
- pg_send_query_params() - Envia um comando e parâmetros separados para o servidor sem esperar pelo(s) resultado(s)

# pg_send_query

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_send_query — Envia consulta assíncrona

### Descrição

function pg_send_query(PgSql\Connection `$connection`, string `$query`): int|bool

pg_send_query() envia uma consulta ou consultas de forma assíncrona para a `connection`. Ao contrário de pg_query(), ele pode enviar múltiplas consultas de uma vez ao PostgreSQL e obter os resultados um por um usando pg_get_result().

A execução do script não é bloqueada enquanto as consultas estão em execução. Use pg_connection_busy() para verificar se a conexão está ocupada (ou seja, a consulta está em execução). As consultas podem ser canceladas usando pg_cancel_query().

Embora o usuário possa enviar diversas consultas de uma só vez, diversas consultas não podem ser enviadas em uma conexão ocupada. Se uma consulta for enviada enquanto a conexão estiver ocupada, ela aguardará até que a última consulta termine e descarta todos os seus resultados.

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.
`query`

  A instrução ou instruções SQL a serem executadas.

  Os dados dentro da consulta devem ser escapados corretamente.

### Valor Retornado

Retorna `true` em caso de sucesso, `false` ou `0` em caso de falha. Use pg_get_result() para determinar o resultado da consulta.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_send_query()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Não foi possivel conectar");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from authors; select count(*) from authors;");
      }

      $res1 = pg_get_result($dbconn);
      echo "Primeira chamada a pg_get_result(): $res1\n";
      $rows1 = pg_num_rows($res1);
      echo "$res1 possui $rows1 registro(s)\n\n";

      $res2 = pg_get_result($dbconn);
      echo "Segunda chamada a pg_get_result(): $res2\n";
      $rows2 = pg_num_rows($res2);
      echo "$res2 possui $rows2 registro(s)\n";
    ?>

O exemplo acima produzirá:

    Primeira chamada a pg_get_result(): Resource id #3
    Resource id #3 possui 3 registro(s)

    Segunda chamada a pg_get_result(): Resource id #4
    Resource id #4 possui 1 registro(s)

### Veja Também

- pg_query() - Executa uma consulta
- pg_cancel_query() - Cancela uma consulta assíncrona
- pg_get_result() - Obtém o resultado da consulta assíncrona
- pg_connection_busy() - Obtém se conexão está ocupada ou não

# pg_send_query_params

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_send_query_params — Envia um comando e parâmetros separados para o servidor sem esperar pelo(s) resultado(s)

### Descrição

function pg_send_query_params(PgSql\Connection `$connection`, string `$query`, array `$params`): int|bool

Envia um comando e parâmetros separados ao servidor sem esperar pelo(s) resultado(s).

Isto é equivalente a pg_send_query() exceto que os parâmetros de consulta podem ser especificados separadamente da string `query`. Os parâmetros da função são tratados de forma idêntica a pg_query_params(). Assim como pg_query_params(), ele não funcionará em conexões PostgreSQL anteriores à versão 7.4 e permite apenas um comando na string de consulta.

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.
`query`

  A instrução SQL parametrizada. Deve conter apenas uma única instrução. (múltiplas instruções separadas por ponto e vírgula não são permitidas.) Se algum parâmetro for usado, ele será chamado de $1, $2, etc.

`params`

  Um array de valores de parâmetros para substituir os espaços reservados $1, $2, etc. na string de consulta preparada original. O número de elementos no array deve corresponder ao número de espaços reservados.

### Valor Retornado

Retorna `true` em caso de sucesso, `false` ou `0` em caso de falha. Use pg_get_result() para determinar o resultado da consulta.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Usando pg_send_query_params()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Não foi possível conectar");

      // Usando parâmetros. Observe que não é necessário citar ou escapar
      // o parâmetro.
      pg_send_query_params($dbconn, 'select count(*) from authors where city = $1', array('Perth'));

      // Compara com o uso básico de pg_send_query
      $str = pg_escape_string('Perth');
      pg_send_query($dbconn, "select count(*) from authors where city = '{$str}'");
    ?>

### Veja Também

- pg_send_query() - Envia consulta assíncrona

# pg_set_chunked_rows_size

(PHP 8 >= 8.4.0)

pg_set_chunked_rows_size — Define que os resultados da consulta sejam retornados em partes

### Descrição

function pg_set_chunked_rows_size(PgSql\Connection `$connection`, int `$size`): bool

Define que os resultados da consulta sejam retornados em pedaços. Os resultados de consulta retornados em seguida serão divididos em diversas partes, cada uma contendo até `size` linhas. Esta função precisa ser chamada antes de recuperar os resultados com pg_get_result(). Esta função está disponível somente quando a versão de libpq é 17 ou superior.

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.
`size`
  O número de linhas a recuperar em cada parte.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Se `size` for menor que `1`, uma exceção ValueError será lançada.

### Exemplos

Exemplo #1 Exemplo de pg_result_memory_size()

    <?php

    $conn = pg_connect($conn_str);

    for ($i = 0; $i < 10; $i ++) {
        pg_query($conn, "INSERT INTO users DEFAULT VALUES");
    }

    pg_send_query($conn, "SELECT * FROM users");
    pg_set_chunked_rows_size($conn, 1);

    $result = pg_get_result($conn);
    var_dump(pg_num_rows($result));

    // Sem efeito depois que o resultado é recuperado
    var_dump(pg_set_chunked_rows_size($conn, 10));

O exemplo acima produzirá:

    int(1)
    bool(false)

### Veja Também

- pg_get_result() - Obtém o resultado da consulta assíncrona
- pg_result_status() - Obtém o status do resultado da consulta

# pg_set_client_encoding

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_set_client_encoding — Define a codificação do cliente

### Descrição

function pg_set_client_encoding(PgSql\Connection `$connection` = ?, string `$encoding`): int

pg_set_client_encoding() define a codificação do cliente e retorna 0 em caso de sucesso ou -1 em caso de erro.

O PostgreSQL converterá automaticamente os dados da codificação do banco de dados backend na codificação frontend.

> Nota:

> A função costumava ser chamada de pg_setclientencoding().

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` não for especificado, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

`encoding`

  A codificação do cliente necessária. Um de `SQL_ASCII`, `EUC_JP`, `EUC_CN`, `EUC_KR`, `EUC_TW`, `UNICODE`, `MULE_INTERNAL`, `LATINX` (X=1...9), `KOI8`, `WIN` , `ALT`, `SJIS`, `BIG5` ou `WIN1250`.

  A lista exata de codificações disponíveis depende da sua versão do PostgreSQL, portanto verifique o manual do PostgreSQL para obter uma lista mais específica.

### Valor Retornado

Retorna `0` em caso de sucesso ou `-1` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_set_client_encoding()

    <?php

    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "An error occurred.\n";
      exit;
    }

    // Define a codificação do cliente como UNICODE. Os dados serão automaticamente
    // convertidos da codificação de backend para frontend.
    pg_set_client_encoding($conn, "UNICODE");

    $result = pg_query($conn, "SELECT author, email FROM authors");
    if (!$result) {
      echo "An error occurred.\n";
      exit;
    }

    // Escreve dados UTF-8
    while ($row = pg_fetch_row($result)) {
      echo "Author: $row[0]  E-mail: $row[1]";
      echo "<br />\n";
    }

    ?>

### Veja Também

- pg_client_encoding() - Obtém a codificação do cliente

# pg_set_error_context_visibility

(PHP 8 >= 8.3.0)

pg_set_error_context_visibility — Determina a visibilidade das mensagens de erro do contexto retornadas por pg_last_error() e pg_result_error()

### Descrição

function pg_set_error_context_visibility(PgSql\Connection `$connection`, int `$visibility`): int

Determina a visibilidade das mensagens de erro do contexto retornadas por pg_last_error() e pg_result_error()

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.
`visibility`

  A visibilidade necessária: `PGSQL_SHOW_CONTEXT_NEVER`, `PGSQL_SHOW_CONTEXT_ERRORS` ou `PGSQL_SHOW_CONTEXT_ALWAYS`.

### Valor Retornado

O nível de visibilidade anterior: `PGSQL_SHOW_CONTEXT_NEVER`, `PGSQL_SHOW_CONTEXT_ERRORS` ou `PGSQL_SHOW_CONTEXT_ALWAYS`.

### Exemplos

Exemplo #1 Exemplo de pg_set_error_context_visibility()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Não foi possível conectar");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from doesnotexist;");
      }

      pg_set_error_context_visibility($dbconn, PGSQL_SHOW_CONTEXT_ALWAYS);
      $res1 = pg_get_result($dbconn);
      echo pg_result_error($res1);
    ?>

### Veja Também

- pg_last_error() - Obtém a última string da mensagem de erro de uma conexão
- pg_result_error() - Obtém mensagem de erro associada ao resultado

# pg_set_error_verbosity

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_set_error_verbosity — Determina o detalhamento das mensagens retornadas por pg_last_error() e pg_result_error()

### Descrição

function pg_set_error_verbosity(PgSql\Connection `$connection` = ?, int `$verbosity`): int|false

Determina o detalhamento das mensagens retornadas por pg_last_error() e pg_result_error().

pg_set_error_verbosity() define o modo de verbosidade, retornando a configuração anterior da conexão. No modo `PGSQL_ERRORS_TERSE`, as mensagens retornadas incluem apenas severidade, texto primário e posição; isso normalmente caberá em uma única linha. O modo padrão (`PGSQL_ERRORS_DEFAULT`) produz mensagens que incluem o acima, além de quaisquer detalhes, dicas ou campos de contexto (estes podem abranger várias linhas). O modo `PGSQL_ERRORS_VERBOSE` inclui todos os campos disponíveis. A alteração do detalhamento não afeta as mensagens disponíveis nos objetos de resultado já existentes, apenas nos criados posteriormente.

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` não for especificado, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

`verbosity`

  A verbosidade necessária: `PGSQL_ERRORS_TERSE`, `PGSQL_ERRORS_DEFAULT` ou `PGSQL_ERRORS_VERBOSE`.

### Valor Retornado

O nível de verbosidade anterior: `PGSQL_ERRORS_TERSE`, `PGSQL_ERRORS_DEFAULT` ou `PGSQL_ERRORS_VERBOSE` ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_set_error_verbosity()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Não foi possível conectar");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from doesnotexist;");
      }

      pg_set_error_verbosity($dbconn, PGSQL_ERRORS_VERBOSE);
      $res1 = pg_get_result($dbconn);
      echo pg_result_error($res1);
    ?>

### Veja Também

- pg_last_error() - Obtém a última string da mensagem de erro de uma conexão
- pg_result_error() - Obtém mensagem de erro associada ao resultado

# pg_socket

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_socket — Obtém um identificador somente leitura para o socket subjacente a uma conexão PostgreSQL

### Descrição

function pg_socket(PgSql\Connection `$connection`): resource|false

pg_socket() retorna um resource somente leitura correspondente ao socket subjacente à conexão PostgreSQL fornecida.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.

### Valor Retornado

Um recurso socket em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

# pg_socket_poll

(PHP 8 >= 8.4.0)

pg_socket_poll — Verifica se um socket de conexão PostgreSQL está pronto para leitura/gravação

### Descrição

function pg_socket_poll(
resource `$socket`,
int `$read`,
int `$write`,
int `$timeout` = -1
): int

Verifica se um socket de conexão PostgreSQL está pronto para leitura e/ou gravação. O socket pode ser obtido usando pg_socket(). Esta função é útil para implementar fluxos de trabalho de consulta assíncronos e não bloqueantes.

### Parâmetros

`socket`
  Um recurso de soquete obtido de pg_socket().
`read`
  Indica se deve verificar se está pronto para leitura. Passe `1` para verificar, `0` para ignorar.
`write`
  Indica se deve verificar se está pronto para escrita. Passe `1` para verificar, `0` para ignorar.
`timeout`
  O número máximo de milissegundos para esperar. Passe `-1` para esperar indefinidamente ou `0` para não esperar.

### Valor Retornado

Retorna um valor positivo se o socket estiver pronto, `0` se o tempo limite foi atingido ou `-1` em caso de erro.

### Veja Também

- pg_socket() - Obtém um identificador somente leitura para o socket subjacente a uma conexão PostgreSQL
- pg_consume_input() - Lê a entrada na conexão
- pg_send_query() - Envia consulta assíncrona

# pg_trace

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

pg_trace — Ativa o rastreamento de uma conexão PostgreSQL

### Descrição

function pg_trace(
string `$filename`,
string `$mode` = "w",
?PgSql\Connection `$connection` = `null`,
int `$trace_mode` = 0
): bool

pg_trace() permite o rastreamento da comunicação frontend/backend do PostgreSQL para um arquivo. Para compreender totalmente os resultados, é necessário estar familiarizado com os componentes internos do protocolo de comunicação PostgreSQL.

Para quem não é, ainda pode ser útil para rastrear erros em consultas enviadas ao servidor, você poderia fazer por exemplo grep '^To backend' trace.log e ver quais consultas realmente foram enviados para o servidor PostgreSQL. Para obter mais informações, consulte a » Documentação do PostgreSQL.

### Parâmetros

`filename`

  O caminho completo e o nome do arquivo no qual gravar o log de rastreamento. O mesmo que em fopen().

`mode`

  Um modo opcional de acesso a arquivos, igual ao fopen().

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` for `null`, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

`trace_mode`

  Um modo de rastreamento opcional com as seguintes constantes `PGSQL_TRACE_SUPPRESS_TIMESTAMPS` e `PGSQL_TRACE_REGRESS_MODE`

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | `trace_mode` foi adicionado.
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.
8.0.0 | `connection` agora é anulável.

### Exemplos

Exemplo #1 Exemplo de pg_trace()

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
       pg_trace('/tmp/trace.log', 'w', $pgsql_conn);
       pg_query("SELECT 1");
       pg_untrace($pgsql_conn);
       // Agora /tmp/trace.log conterá comunicação de backend
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

### Veja Também

- fopen() - Abre um arquivo ou URL
- pg_untrace() - Desabilita o rastreamento de uma conexão PostgreSQL

# pg_transaction_status

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_transaction_status — Retorna o status atual da transação do servidor

### Descrição

function pg_transaction_status(PgSql\Connection `$connection`): int

Retorna o status atual da transação do servidor.

Cuidado

pg_transaction_status() fornecerá resultados incorretos ao usar um servidor PostgreSQL 7.3 que tenha o parâmetro `autocommit` desativado. O recurso de confirmação automática do lado do servidor foi descontinuado e não existe em versões de servidor posteriores.

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.

### Valor Retornado

O status pode ser `PGSQL_TRANSACTION_IDLE` (atualmente inativo), `PGSQL_TRANSACTION_ACTIVE` (um comando está em andamento), `PGSQL_TRANSACTION_INTRANS` (inativo, em um bloco de transação válido), ou `PGSQL_TRANSACTION_INERROR` (ocioso, em um bloco de transação com falha). `PGSQL_TRANSACTION_UNKNOWN` é relatado se a conexão estiver ruim. `PGSQL_TRANSACTION_ACTIVE` é relatado somente quando uma consulta foi enviada ao servidor e ainda não foi concluída.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_transaction_status()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Não foi possível conectar");
      $stat = pg_transaction_status($dbconn);
      if ($stat === PGSQL_TRANSACTION_UNKNOWN) {
          echo 'A conexão está ruim';
      } else if ($stat === PGSQL_TRANSACTION_IDLE) {
          echo 'A conexão está inativa no momento';
      } else {
          echo 'A conexão está em estado de transação';
      }
    ?>

# pg_tty

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_tty — Retorna o nome TTY associado à conexão

### Descrição

function pg_tty(?PgSql\Connection `$connection` = `null`): string

pg_tty() retorna o nome TTY para o qual a saída de depuração do lado do servidor é enviada na instância de `connection` do PostgreSQL fornecida.

> Nota:

> pg_tty() está obsoleto, pois o servidor não presta mais atenção à configuração do TTY, mas a função permanece para compatibilidade com versões anteriores.

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` for `null`, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

### Valor Retornado

Uma string contendo o TTY de depuração da `connection`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.
8.0.0 | `connection` agora é anulável.

### Exemplos

Exemplo #1 Exemplo de pg_tty()

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
       print "O TTY de depuração do servidor é: " . pg_tty($pgsql_conn) . "<br/>\n";
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

# pg_unescape_bytea

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_unescape_bytea — Desfaz escape binário para tipo bytea

### Descrição

function pg_unescape_bytea(string `$string`): string

pg_unescape_bytea() remove o escape dos valores de dados bytea do PostgreSQL. Ele retorna a string sem escape, possivelmente contendo dados binários.

> Nota:

> Quando seleciona-se um tipo bytea com `SELECT`, o PostgreSQL retorna valores de bytes octais prefixados com '\' (por exemplo, \032). Os usuários devem converter de volta para o formato binário manualmente.

### Parâmetros

`string`

  Uma string contendo dados bytea do PostgreSQL a serem convertidos em uma string binária PHP.

### Valor Retornado

Uma string contendo os dados sem escape.

### Exemplos

Exemplo #1 Exemplo de pg_unescape_bytea()

    <?php
      // Conecta-se ao banco de dados
      $dbconn = pg_connect('dbname=foo');

      // Obtém os dados do bytea
      $res = pg_query("SELECT data FROM gallery WHERE name='Pine trees'");
      $raw = pg_fetch_result($res, 'data');

      // Converte para binário e envia para o navegador
      header('Content-type: image/jpeg');
      echo pg_unescape_bytea($raw);
    ?>

### Veja Também

- pg_escape_bytea() - Escapa uma string para inserção em um campo bytea
- pg_escape_string() - Escapa uma string para consulta

# pg_untrace

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

pg_untrace — Desabilita o rastreamento de uma conexão PostgreSQL

### Descrição

function pg_untrace(?PgSql\Connection `$connection` = `null`): true

Para o rastreamento iniciado por pg_trace().

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` for `null`, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.2.0 | O tipo do retorno agora é `true`; anteriormente, era bool.
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.
8.0.0 | `connection` agora é anulável.

### Exemplos

Exemplo #1 Exemplo de pg_untrace()

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
       pg_trace('/tmp/trace.log', 'w', $pgsql_conn);
       pg_query("SELECT 1");
       pg_untrace($pgsql_conn);
       // Agora o rastreamento da comunicação de back-end está desativado
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

### Veja Também

- pg_trace() - Ativa o rastreamento de uma conexão PostgreSQL

# pg_update

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_update — Atualiza tabela

### Descrição

function pg_update(
PgSql\Connection `$connection`,
string `$table_name`,
array `$values`,
array `$conditions`,
int `$flags` = `PGSQL_DML_EXEC`
): string|bool

pg_update() atualiza registros que correspondem a `conditions` com `values`.

Se `flags` for especificado, pg_convert() será aplicado aos `values` com as opções especificadas.

Por padrão, pg_update() passa valores brutos. Os valores devem ser escapados ou a opção `PGSQL_DML_ESCAPE` deve ser especificado em `flags`. `PGSQL_DML_ESCAPE` cita e escapa parâmetros/identificadores. Portanto, os nomes de tabelas/colunas diferenciam maiúsculas de minúsculas.

Observe que nem o escape nem a consulta preparada podem proteger consultas LIKE, JSON, Array, Regex, etc. Estes parâmetros devem ser manipulados de acordo com seus contextos, ou seja, escapar/validar valores.

### Parâmetros

`connection`
  Uma instância de PgSql\Connection.
`table_name`

  Nome da tabela na qual as linhas serão atualizadas.

`values`

  Um array cujas chaves são nomes de campos na tabela `table_name` e cujos valores são os valores para os quais as linhas correspondentes devem ser atualizadas.

`conditions`

  Um array cujas chaves são nomes de campos na tabela `table_name` e cujos valores são as condições que uma linha deve atender para ser atualizada.

`flags`

  Qualquer número de `PGSQL_CONV_FORCE_NULL`, `PGSQL_DML_NO_CONV`, `PGSQL_DML_ESCAPE`, `PGSQL_DML_EXEC`, `PGSQL_DML_ASYNC` ou `PGSQL_DML_STRING` combinado. Se `PGSQL_DML_STRING` fizer parte dos `flags` então a string de consulta será retornada. Quando `PGSQL_DML_NO_CONV` ou `PGSQL_DML_ESCAPE` está definido, ele não chama pg_convert() internamente.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha. Retorna string se `PGSQL_DML_STRING` for passado através de `flags`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pg_update()

    <?php
      $db = pg_connect('dbname=foo');
      $data = array('field1'=>'AA', 'field2'=>'BB');
      // Isso é um tanto seguro, já que todos os valores têm escape.
      // No entanto, o PostgreSQL suporta JSON/Array. Estes não são
      // seguros nem por escape nem por consulta preparada.
      $res = pg_update($db, 'post_log', $_POST, $data);
      if ($res) {
          echo "Dados foram atualizados: $res\n";
      } else {
          echo "Usuário deve ter enviado dados errados\n";
      }
    ?>

### Veja Também

- pg_convert() - Converte valores de array associativo em formas adequadas para instruções SQL

# pg_version

(PHP 5, PHP 7, PHP 8)

pg_version — Retorna um array com versão do cliente, protocolo e servidor (quando disponível)

### Descrição

function pg_version(?PgSql\Connection `$connection` = `null`): array

pg_version() retorna um array com as versões do cliente, do protocolo e do servidor.

Para informações mais detalhadas do servidor, use pg_parameter_status().

### Parâmetros

`connection`

  Uma instância de PgSql\Connection. Quando o parâmetro `connection` for `null`, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

  Aviso

  A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

### Valor Retornado

Retorna um array com chaves e valores `client`, `protocol` e `server` (se disponível).

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.
8.0.0 | `connection` agora é anulável.

### Exemplos

Exemplo #1 Exemplo de pg_version()

    <?php
      $dbconn = pg_connect("host=localhost port=5432 dbname=mary")
         or die("Não foi possível conectar");

      $v = pg_version($dbconn);

      echo $v['client'];
    ?>

O exemplo acima produzirá:

    7.4

### Veja Também

- pg_parameter_status() - Procura uma configuração de parâmetro atual do servidor

## Índice

- pg_affected_rows — Retorna o número de registros afetados (tuplas)
- pg_cancel_query — Cancela uma consulta assíncrona
- pg_change_password — Altera a senha de um usuário do PostgreSQL
- pg_client_encoding — Obtém a codificação do cliente
- pg_close — Fecha uma conexão PostgreSQL
- pg_connect — Abre uma conexão PostgreSQL
- pg_connect_poll — Pesquisa o status de uma tentativa de conexão PostgreSQL assíncrona em andamento
- pg_connection_busy — Obtém se conexão está ocupada ou não
- pg_connection_reset — Redefine conexão (reconecta)
- pg_connection_status — Obtém o status da conexão
- pg_consume_input — Lê a entrada na conexão
- pg_convert — Converte valores de array associativo em formas adequadas para instruções SQL
- pg_copy_from — Insere registros em uma tabela a partir de um array
- pg_copy_to — Copia uma tabela para um array
- pg_dbname — Obtém o nome do banco de dados
- pg_delete — Exclui registros
- pg_end_copy — Sincroniza com back-end do PostgreSQL
- pg_escape_bytea — Escapa uma string para inserção em um campo bytea
- pg_escape_identifier — Escapa um identificador para inserção em um campo de texto
- pg_escape_literal — Escapa um literal para inserção em um campo de texto
- pg_escape_string — Escapa uma string para consulta
- pg_execute — Envia uma solicitação para executar uma instrução preparada com determinados parâmetros e aguarda o resultado
- pg_fetch_all — Busca todas as linhas de um resultado como um array
- pg_fetch_all_columns — Busca todas as linhas em uma determinada coluna de resultado como um array
- pg_fetch_array — Busca uma linha como um array
- pg_fetch_assoc — Busca uma linha como um array associativo
- pg_fetch_object — Busca uma linha como um objeto
- pg_fetch_result — Retorna valores de uma instância de resultado
- pg_fetch_row — Obtém uma linha como um array enumerado
- pg_field_is_null — Testa se um campo é SQL NULL
- pg_field_name — Retorna o nome de um campo
- pg_field_num — Retorna o número do campo para o campo nomeado
- pg_field_prtlen — Retorna o comprimento impresso
- pg_field_size — Retorna o tamanho de armazenamento interno do campo nomeado
- pg_field_table — Retorna o nome ou oid do campo da tabela
- pg_field_type — Retorna o nome do tipo para o número do campo correspondente
- pg_field_type_oid — Retorna o ID do tipo (OID) para o número do campo correspondente
- pg_flush — Libera dados de consulta de saída na conexão
- pg_free_result — Libera memória de resultados
- pg_get_notify — Obtém mensagem SQL NOTIFY
- pg_get_pid — Obtém o ID do processo do backend
- pg_get_result — Obtém o resultado da consulta assíncrona
- pg_host — Retorna o nome do host associado à conexão
- pg_insert — Insere array na tabela
- pg_jit — Retorna as informações JIT do servidor
- pg_last_error — Obtém a última string da mensagem de erro de uma conexão
- pg_last_notice — Retorna a última mensagem de aviso do servidor PostgreSQL
- pg_last_oid — Retorna o OID da última linha
- pg_lo_close — Fecha um objeto grande
- pg_lo_create — Cria um objeto grande
- pg_lo_export — Exporta um objeto grande para arquivo
- pg_lo_import — Importa um objeto grande do arquivo
- pg_lo_open — Abra um objeto grande
- pg_lo_read — Lê um objeto grande
- pg_lo_read_all — Lê um objeto grande inteiro e envia direto para o navegador
- pg_lo_seek — Aponta para posição dentro de um objeto grande
- pg_lo_tell — Retorna a posição de busca atual a de um objeto grande
- pg_lo_truncate — Trunca um objeto grande
- pg_lo_unlink — Exclui um objeto grande
- pg_lo_write — Escreve em um objeto grande
- pg_meta_data — Obtém metadados para tabela
- pg_num_fields — Retorna o número de campos em um resultado
- pg_num_rows — Retorna o número de linhas em um resultado
- pg_options — Obtém as opções associadas à conexão
- pg_parameter_status — Procura uma configuração de parâmetro atual do servidor
- pg_pconnect — Abre uma conexão PostgreSQL persistente
- pg_ping — Ping em conexão com banco de dados
- pg_port — Retorne o número da porta associada à conexão
- pg_prepare — Envia uma solicitação ao servidor para criar uma instrução preparada com os parâmetros fornecidos e aguarda a conclusão
- pg_put_copy_data — Envia dados para o servidor durante uma operação COPY
- pg_put_copy_end — Sinaliza a conclusão de uma operação COPY para o servidor
- pg_put_line — Envia uma string terminada em NULL para o backend do PostgreSQL
- pg_query — Executa uma consulta
- pg_query_params — Envia um comando ao servidor e aguarda o resultado, com a capacidade de passar parâmetros separadamente do texto do comando SQL
- pg_result_error — Obtém mensagem de erro associada ao resultado
- pg_result_error_field — Retorna um campo individual de um relatório de erros
- pg_result_memory_size — Retorna a quantidade de memória alocada para um resultado de consulta
- pg_result_seek — Define deslocamento interno de linha na instância de resultado
- pg_result_status — Obtém o status do resultado da consulta
- pg_select — Seleciona registros
- pg_send_execute — Envia uma solicitação para executar uma instrução preparada com determinados parâmetros, sem esperar pelo(s) resultado(s)
- pg_send_prepare — Envia uma solicitação para criar uma instrução preparada com os parâmetros fornecidos, sem esperar pela conclusão
- pg_send_query — Envia consulta assíncrona
- pg_send_query_params — Envia um comando e parâmetros separados para o servidor sem esperar pelo(s) resultado(s)
- pg_set_chunked_rows_size — Define que os resultados da consulta sejam retornados em partes
- pg_set_client_encoding — Define a codificação do cliente
- pg_set_error_context_visibility — Determina a visibilidade das mensagens de erro do contexto retornadas por pg_last_error e pg_result_error
- pg_set_error_verbosity — Determina o detalhamento das mensagens retornadas por pg_last_error e pg_result_error
- pg_socket — Obtém um identificador somente leitura para o socket subjacente a uma conexão PostgreSQL
- pg_socket_poll — Verifica se um socket de conexão PostgreSQL está pronto para leitura/gravação
- pg_trace — Ativa o rastreamento de uma conexão PostgreSQL
- pg_transaction_status — Retorna o status atual da transação do servidor
- pg_tty — Retorna o nome TTY associado à conexão
- pg_unescape_bytea — Desfaz escape binário para tipo bytea
- pg_untrace — Desabilita o rastreamento de uma conexão PostgreSQL
- pg_update — Atualiza tabela
- pg_version — Retorna um array com versão do cliente, protocolo e servidor (quando disponível)

# A classe PgSql\Connection

(PHP 8 >= 8.1.0)

## Introdução

Uma classe totalmente opaca que substitui um recurso `pgsql link` a partir do PHP 8.1.0.

## Resumo da classe

namespace PgSql;
final class Connection {
}

# A classe PgSql\Result

(PHP 8 >= 8.1.0)

## Introdução

Uma classe totalmente opaca que substitui um recurso `pgsql result` a partir do PHP 8.1.0.

## Resumo da classe

namespace PgSql;
final class Result {
}

# A classe PgSql\Lob

(PHP 8 >= 8.1.0)

## Introdução

Uma classe totalmente opaca que substitui um recurso `pgsql large object` a partir do PHP 8.1.0.

## Resumo da classe

namespace PgSql;
final class Lob {
}

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
  - Tipos de Recurso
- Constantes predefinidas
- Exemplos
  - Uso básico
  - Basic usage
- Funções PostgreSQL
  - pg_affected_rows — Retorna o número de registros afetados (tuplas)
  - pg_cancel_query — Cancela uma consulta assíncrona
  - pg_change_password — Altera a senha de um usuário do PostgreSQL
  - pg_client_encoding — Obtém a codificação do cliente
  - pg_close — Fecha uma conexão PostgreSQL
  - pg_connect — Abre uma conexão PostgreSQL
  - pg_connect_poll — Pesquisa o status de uma tentativa de conexão PostgreSQL assíncrona em andamento
  - pg_connection_busy — Obtém se conexão está ocupada ou não
  - pg_connection_reset — Redefine conexão (reconecta)
  - pg_connection_status — Obtém o status da conexão
  - pg_consume_input — Lê a entrada na conexão
  - pg_convert — Converte valores de array associativo em formas adequadas para instruções SQL
  - pg_copy_from — Insere registros em uma tabela a partir de um array
  - pg_copy_to — Copia uma tabela para um array
  - pg_dbname — Obtém o nome do banco de dados
  - pg_delete — Exclui registros
  - pg_end_copy — Sincroniza com back-end do PostgreSQL
  - pg_escape_bytea — Escapa uma string para inserção em um campo bytea
  - pg_escape_identifier — Escapa um identificador para inserção em um campo de texto
  - pg_escape_literal — Escapa um literal para inserção em um campo de texto
  - pg_escape_string — Escapa uma string para consulta
  - pg_execute — Envia uma solicitação para executar uma instrução preparada com determinados parâmetros e aguarda o resultado
  - pg_fetch_all — Busca todas as linhas de um resultado como um array
  - pg_fetch_all_columns — Busca todas as linhas em uma determinada coluna de resultado como um array
  - pg_fetch_array — Busca uma linha como um array
  - pg_fetch_assoc — Busca uma linha como um array associativo
  - pg_fetch_object — Busca uma linha como um objeto
  - pg_fetch_result — Retorna valores de uma instância de resultado
  - pg_fetch_row — Obtém uma linha como um array enumerado
  - pg_field_is_null — Testa se um campo é SQL NULL
  - pg_field_name — Retorna o nome de um campo
  - pg_field_num — Retorna o número do campo para o campo nomeado
  - pg_field_prtlen — Retorna o comprimento impresso
  - pg_field_size — Retorna o tamanho de armazenamento interno do campo nomeado
  - pg_field_table — Retorna o nome ou oid do campo da tabela
  - pg_field_type — Retorna o nome do tipo para o número do campo correspondente
  - pg_field_type_oid — Retorna o ID do tipo (OID) para o número do campo correspondente
  - pg_flush — Libera dados de consulta de saída na conexão
  - pg_free_result — Libera memória de resultados
  - pg_get_notify — Obtém mensagem SQL NOTIFY
  - pg_get_pid — Obtém o ID do processo do backend
  - pg_get_result — Obtém o resultado da consulta assíncrona
  - pg_host — Retorna o nome do host associado à conexão
  - pg_insert — Insere array na tabela
  - pg_jit — Retorna as informações JIT do servidor
  - pg_last_error — Obtém a última string da mensagem de erro de uma conexão
  - pg_last_notice — Retorna a última mensagem de aviso do servidor PostgreSQL
  - pg_last_oid — Retorna o OID da última linha
  - pg_lo_close — Fecha um objeto grande
  - pg_lo_create — Cria um objeto grande
  - pg_lo_export — Exporta um objeto grande para arquivo
  - pg_lo_import — Importa um objeto grande do arquivo
  - pg_lo_open — Abra um objeto grande
  - pg_lo_read — Lê um objeto grande
  - pg_lo_read_all — Lê um objeto grande inteiro e envia direto para o navegador
  - pg_lo_seek — Aponta para posição dentro de um objeto grande
  - pg_lo_tell — Retorna a posição de busca atual a de um objeto grande
  - pg_lo_truncate — Trunca um objeto grande
  - pg_lo_unlink — Exclui um objeto grande
  - pg_lo_write — Escreve em um objeto grande
  - pg_meta_data — Obtém metadados para tabela
  - pg_num_fields — Retorna o número de campos em um resultado
  - pg_num_rows — Retorna o número de linhas em um resultado
  - pg_options — Obtém as opções associadas à conexão
  - pg_parameter_status — Procura uma configuração de parâmetro atual do servidor
  - pg_pconnect — Abre uma conexão PostgreSQL persistente
  - pg_ping — Ping em conexão com banco de dados
  - pg_port — Retorne o número da porta associada à conexão
  - pg_prepare — Envia uma solicitação ao servidor para criar uma instrução preparada com os parâmetros fornecidos e aguarda a conclusão
  - pg_put_copy_data — Envia dados para o servidor durante uma operação COPY
  - pg_put_copy_end — Sinaliza a conclusão de uma operação COPY para o servidor
  - pg_put_line — Envia uma string terminada em NULL para o backend do PostgreSQL
  - pg_query — Executa uma consulta
  - pg_query_params — Envia um comando ao servidor e aguarda o resultado, com a capacidade de passar parâmetros separadamente do texto do comando SQL
  - pg_result_error — Obtém mensagem de erro associada ao resultado
  - pg_result_error_field — Retorna um campo individual de um relatório de erros
  - pg_result_memory_size — Retorna a quantidade de memória alocada para um resultado de consulta
  - pg_result_seek — Define deslocamento interno de linha na instância de resultado
  - pg_result_status — Obtém o status do resultado da consulta
  - pg_select — Seleciona registros
  - pg_send_execute — Envia uma solicitação para executar uma instrução preparada com determinados parâmetros, sem esperar pelo(s) resultado(s)
  - pg_send_prepare — Envia uma solicitação para criar uma instrução preparada com os parâmetros fornecidos, sem esperar pela conclusão
  - pg_send_query — Envia consulta assíncrona
  - pg_send_query_params — Envia um comando e parâmetros separados para o servidor sem esperar pelo(s) resultado(s)
  - pg_set_chunked_rows_size — Define que os resultados da consulta sejam retornados em partes
  - pg_set_client_encoding — Define a codificação do cliente
  - pg_set_error_context_visibility — Determina a visibilidade das mensagens de erro do contexto retornadas por pg_last_error e pg_result_error
  - pg_set_error_verbosity — Determina o detalhamento das mensagens retornadas por pg_last_error e pg_result_error
  - pg_socket — Obtém um identificador somente leitura para o socket subjacente a uma conexão PostgreSQL
  - pg_socket_poll — Verifica se um socket de conexão PostgreSQL está pronto para leitura/gravação
  - pg_trace — Ativa o rastreamento de uma conexão PostgreSQL
  - pg_transaction_status — Retorna o status atual da transação do servidor
  - pg_tty — Retorna o nome TTY associado à conexão
  - pg_unescape_bytea — Desfaz escape binário para tipo bytea
  - pg_untrace — Desabilita o rastreamento de uma conexão PostgreSQL
  - pg_update — Atualiza tabela
  - pg_version — Retorna um array com versão do cliente, protocolo e servidor (quando disponível)
- PgSql\Connection — A classe PgSql\Connection
- PgSql\Result — A classe PgSql\Result
- PgSql\Lob — A classe PgSql\Lob

# SQLite3

# Introdução

Suporte para bancos de dados SQLite versão 3.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução

## Dependências

A partir do PHP 7.4.0, é necessário o » libsqlite ≥ 3.7.4. Anteriormente, o libsqlite incluso poderia ter sido usado.

## Instalação

A extensão SQLite3 está habilitada por padrão. É possível desabilitá-la usando `--without-sqlite3` durante a compilação.

Usuários do Windows devem habilitar php_sqlite3.dll para usar esta extensão. Este arquivo DLL está incluído nas distribuições do PHP para Windows.

> Nota: Configuração adicional no Windows a partir do PHP 7.4.0

> Para que esta extensão funcione, existem arquivos DLL que devem estar disponíveis no PATH do sistema Windows. Para saber como fazer isso, veja a FAQ intitulada "Como eu adiciono o meu diretório PHP ao PATH do Windows". Embora copiar arquivos DLL da pasta do PHP para o diretório system do Windows também funcione (porque o diretório system está, por padrão, no PATH do sistema), isso não é recomendado. Esta extensão requer que os seguintes arquivos estejam no PATH: libsqlite3.dll.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de Configuração de SQLite3
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
sqlite3.extension_dir | "" | `INI_SYSTEM` |
sqlite3.defensive | 1 | `INI_USER` | Disponível a partir do PHP 7.2.17 e 7.3.4 para libsqlite ≥ 3.26.0. Antes do PHP 8.2.0, essa configuração só podia ser alterada como `INI_SYSTEM`.

Aqui está uma breve explicação das diretivas de configuração.

`sqlite3.extension_dir` string

  Caminho para o diretório onde as extensões carregáveis para o SQLite estão localizadas.

`sqlite3.defensive` bool

  Quando a flag defensiva está ativada, recursos de linguagem que permitem que SQL ordinário corrompa deliberadamente o arquivo de banco de dados são desabilitados. Isso proíbe a escrita diretamente no esquema, tabelas sombra (por exemplo, tabelas de dados FTS) ou a tabela virtual sqlite_dbpage. Esta configuração do php.ini só é eficaz para libsqlite ≥ 3.26.0.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`SQLITE3_ASSOC` (int)
  Especifica que o método Sqlite3Result::fetchArray() deve retornar um array indexado pelo nome da coluna conforme retornado no conjunto de resultados correspondente.
`SQLITE3_NUM` (int)
  Especifica que o método Sqlite3Result::fetchArray() deve retornar um array indexado pelo número da coluna conforme retornado no conjunto de resultados correspondente, começando na coluna 0.
`SQLITE3_BOTH` (int)
  Especifica que o método Sqlite3Result::fetchArray() deve retornar um array indexado tanto pelo nome quanto pelo número da coluna conforme retornado no conjunto de resultados correspondente, começando na coluna 0.
`SQLITE3_INTEGER` (int)
  Representa a classe de armazenamento INTEGER do SQLite3.
`SQLITE3_FLOAT` (int)
  Representa a classe de armazenamento REAL (FLOAT) do SQLite3.
`SQLITE3_TEXT` (int)
  Representa a classe de armazenamento TEXT do SQLite3.
`SQLITE3_BLOB` (int)
  Representa a classe de armazenamento BLOB do SQLite3.
`SQLITE3_NULL` (int)
  Representa a classe de armazenamento NULL do SQLite3.
`SQLITE3_OPEN_READONLY` (int)
  Especifica que o banco de dados SQLite3 deve ser aberto apenas para leitura.
`SQLITE3_OPEN_READWRITE` (int)
  Especifica que o banco de dados SQLite3 deve ser aberto para leitura e escrita.
`SQLITE3_OPEN_CREATE` (int)
  Especifica que o banco de dados SQLite3 deve ser criado se ainda não existir.
`SQLITE3_DETERMINISTIC` (int)
  Especifica que uma função criada com SQLite3::createFunction() é determinística, ou seja, ela sempre retorna o mesmo resultado dado os mesmos inputs dentro de uma única instrução SQL. (Disponível a partir do PHP 7.1.4.)

# A classe SQLite3

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Introdução

Uma classe que interage com bancos de dados SQLite 3.

## Resumo da classe

class SQLite3 {
/* Constantes */
public const int OK;
public const int DENY;
public const int IGNORE;
public const int CREATE_INDEX;
public const int CREATE_TABLE;
public const int CREATE_TEMP_INDEX;
public const int CREATE_TEMP_TABLE;
public const int CREATE_TEMP_TRIGGER;
public const int CREATE_TEMP_VIEW;
public const int CREATE_TRIGGER;
public const int CREATE_VIEW;
public const int DELETE;
public const int DROP_INDEX;
public const int DROP_TABLE;
public const int DROP_TEMP_INDEX;
public const int DROP_TEMP_TABLE;
public const int DROP_TEMP_TRIGGER;
public const int DROP_TEMP_VIEW;
public const int DROP_TRIGGER;
public const int DROP_VIEW;
public const int INSERT;
public const int PRAGMA;
public const int READ;
public const int SELECT;
public const int TRANSACTION;
public const int UPDATE;
public const int ATTACH;
public const int DETACH;
public const int ALTER_TABLE;
public const int REINDEX;
public const int ANALYZE;
public const int CREATE_VTABLE;
public const int DROP_VTABLE;
public const int FUNCTION;
public const int SAVEPOINT;
public const int COPY;
public const int RECURSIVE;
/* Métodos */
public function __construct(string `$filename`, int `$flags` = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string `$encryptionKey` = "")
public function backup(SQLite3 `$destination`, string `$sourceDatabase` = "main", string `$destinationDatabase` = "main"): bool
public function busyTimeout(int `$milliseconds`): bool
public function changes(): int
public function close(): bool
public function createAggregate(
string `$name`,
callable `$stepCallback`,
callable `$finalCallback`,
int `$argCount` = -1
): bool
public function createCollation(string `$name`, callable `$callback`): bool
public function createFunction(
string `$name`,
callable `$callback`,
int `$argCount` = -1,
int `$flags` = 0
): bool
public function enableExceptions(bool `$enable` = `false`): bool
public static function escapeString(string `$string`): string
public function exec(string `$query`): bool
public function lastErrorCode(): int
public function lastErrorMsg(): string
public function lastInsertRowID(): int
public function loadExtension(string `$name`): bool
public function open(string `$filename`, int `$flags` = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string `$encryptionKey` = ""): void
public function openBlob(
string `$table`,
string `$column`,
int `$rowid`,
string `$database` = "main",
int `$flags` = `SQLITE3_OPEN_READONLY`
): resource|false
public function prepare(string `$query`): SQLite3Stmt|false
public function query(string `$query`): SQLite3Result|false
public function querySingle(string `$query`, bool `$entireRow` = `false`): mixed
public function setAuthorizer(?callable `$callback`): bool
public static function version(): array
}

## Constantes predefinidas

`SQLite3::OK`

`SQLite3::DENY`

`SQLite3::IGNORE`

`SQLite3::CREATE_INDEX`

`SQLite3::CREATE_TABLE`

`SQLite3::CREATE_TEMP_INDEX`

`SQLite3::CREATE_TEMP_TABLE`

`SQLite3::CREATE_TEMP_TRIGGER`

`SQLite3::CREATE_TEMP_VIEW`

`SQLite3::CREATE_TRIGGER`

`SQLite3::CREATE_VIEW`

`SQLite3::DELETE`

`SQLite3::DROP_INDEX`

`SQLite3::DROP_TABLE`

`SQLite3::DROP_TEMP_INDEX`

`SQLite3::DROP_TEMP_TABLE`

`SQLite3::DROP_TEMP_TRIGGER`

`SQLite3::DROP_TEMP_VIEW`

`SQLite3::DROP_TRIGGER`

`SQLite3::DROP_VIEW`

`SQLite3::INSERT`

`SQLite3::PRAGMA`

`SQLite3::READ`

`SQLite3::SELECT`

`SQLite3::TRANSACTION`

`SQLite3::UPDATE`

`SQLite3::ATTACH`

`SQLite3::DETACH`

`SQLite3::ALTER_TABLE`

`SQLite3::REINDEX`

`SQLite3::ANALYZE`

`SQLite3::CREATE_VTABLE`

`SQLite3::DROP_VTABLE`

`SQLite3::FUNCTION`

`SQLite3::SAVEPOINT`

`SQLite3::COPY`

`SQLite3::RECURSIVE`

# SQLite3::backup

(PHP 7 >= 7.4.0, PHP 8)

SQLite3::backup — Copia um banco de dados para outro banco de dados

### Descrição

public function SQLite3::backup(SQLite3 `$destination`, string `$sourceDatabase` = "main", string `$destinationDatabase` = "main"): bool

SQLite3::backup() copia o conteúdo de um banco de dados para outro, sobrescrevendo o conteúdo do banco de dados de destino. É útil tanto para criar backups de bancos de dados quanto para copiar bancos de dados em memória para ou de arquivos persistentes.

Dica

A partir do SQLite 3.27.0 (2019-02-07), também é possível usar a instrução `VACUUM INTO 'file.db';` para fazer backup do banco de dados para um novo arquivo.

### Parâmetros

`destination`

  Uma conexão de banco de dados aberta com SQLite3::open().

`sourceDatabase`

  O nome do banco de dados é `"main"` para o banco de dados principal, `"temp"` para o banco de dados temporário, ou o nome especificado após a palavra-chave `AS` em uma instrução `ATTACH` para um banco de dados anexado.

`destinationDatabase`

  Analógico ao `sourceDatabase` mas para o `destination`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Fazer backup de um banco de dados existente

    <?php
    // $conn é uma conexão a um banco de dados sqlite3 já aberto

    $backup = new SQLite3('backup.sqlite');
    $conn->backup($backup);
    ?>

# SQLite3::busyTimeout

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

SQLite3::busyTimeout — Define o manipulador de conexão ocupada

### Descrição

public function SQLite3::busyTimeout(int `$milliseconds`): bool

Define um manipulador ocupado que irá dormir até que o banco de dados não esteja bloqueado ou o tempo limite seja atingido.

### Parâmetros

`milliseconds`

  Os milissegundos para dormir. Definir esse valor como um valor menor ou igual a zero desligará um manipulador de tempo limite já definido.

### Valor Retornado

Retorna `true` em caso de sucesso, ou `false` em caso de falha.

# SQLite3::changes

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::changes — Retorna o número de linhas do banco de dados que foram alteradas (ou inseridas ou excluídas) pela instrução SQL mais recente

### Descrição

public function SQLite3::changes(): int

Retorna o número de linhas do banco de dados que foram alteradas (ou inseridas ou excluídas) pela instrução SQL mais recente.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um valor int correspondente ao número de linhas do banco de dados alteradas (ou inseridas ou excluídas) pela instrução SQL mais recente.

### Exemplos

Exemplo #1 Exemplo de SQLite3::changes()

    <?php
    $db = new SQLite3('mysqlitedb.db');

    $query = $db->exec('UPDATE counter SET views=0 WHERE page="test"');
    if ($query) {
        echo 'Number of rows modified: ', $db->changes();
    }
    ?>

# SQLite3::close

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::close — Fecha a conexão com o banco de dados

### Descrição

public function SQLite3::close(): bool

Fecha a conexão com o banco de dados.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de SQLite3::close()

    <?php
    $db = new SQLite3('mysqlitedb.db');
    $db->close();
    ?>

# SQLite3::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::__construct — Instancia um objeto SQLite3 e abre um banco de dados SQLite 3

### Descrição

public function SQLite3::__construct(string `$filename`, int `$flags` = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string `$encryptionKey` = "")

Instancia um objeto SQLite3 e abre uma conexão com um banco de dados SQLite 3. Se a compilação incluir criptografia, ele tentará usar a chave.

### Parâmetros

`filename`

  Caminho para o banco de dados SQLite, ou `:memory:` para usar um banco de dados em memória. Se `filename` for uma string vazia, então um banco de dados privado, temporário no disco será criado. Este banco de dados privado será automaticamente excluído assim que a conexão com o banco de dados for fechada.

`flags`

  Flags opcionais usadas para determinar como abrir o banco de dados SQLite. Por padrão, abre usando `SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE`.

  - `SQLITE3_OPEN_READONLY`: Abre o banco de dados apenas para leitura.

  - `SQLITE3_OPEN_READWRITE`: Abre o banco de dados para leitura e escrita.

  - `SQLITE3_OPEN_CREATE`: Cria o banco de dados se ele não existir.

`encryptionKey`

  Uma chave de criptografia opcional usada ao criptografar e descriptografar um banco de dados SQLite. Se o módulo de criptografia SQLite não estiver instalado, este parâmetro não terá efeito.

### Erros/Exceções

Lança uma Exception em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
7.0.10 | O `filename` agora pode estar vazio para usar um banco de dados privado, temporário no disco.

### Exemplos

Exemplo #1 Exemplo de SQLite3::__construct()

    <?php
    $db = new SQLite3('mysqlitedb.db');

    $db->exec('CREATE TABLE foo (bar TEXT)');
    $db->exec("INSERT INTO foo (bar) VALUES ('Isto é um teste')");

    $result = $db->query('SELECT bar FROM foo');
    var_dump($result->fetchArray());
    ?>

# SQLite3::createAggregate

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::createAggregate — Registra uma função PHP para uso como uma função de agregação SQL

### Descrição

public function SQLite3::createAggregate(
string `$name`,
callable `$stepCallback`,
callable `$finalCallback`,
int `$argCount` = -1
): bool

Registra uma função PHP ou uma função definida pelo usuário para uso como uma função de agregação SQL dentro de declarações SQL.

### Parâmetros

`name`

  Nome do agregado SQL a ser criado ou redefinido.

`stepCallback`

  Função de retorno de chamada chamada para cada linha do conjunto de resultados. Sua função PHP deve acumular o resultado e armazená-lo no contexto de agregação.

  Esta função deve ser definida como:

  function step(
  mixed `$context`,
  int `$rownumber`,
  mixed `$value`,
  mixed `...$values`
  ): mixed
  `context`

    `null` para a primeira linha; nas linhas subsequentes, terá o valor que foi retornado anteriormente pela função step; você deve usar isso para manter o estado de agregação.

  `rownumber`

    O número da linha atual.

  `value`

    O primeiro argumento passado para a agregação.

  `values`

    Outros argumentos passados para a agregação.

  O valor de retorno desta função será usado como o argumento `context` na próxima chamada das funções step ou finalize.
`finalCallback`

  Função de retorno de chamada para agregar os dados "passados" de cada linha. Depois que todas as linhas forem processadas, esta função será chamada e ela deve então pegar os dados do contexto de agregação e retornar o resultado. Esta função de retorno de chamada deve retornar um tipo compreendido pelo SQLite (ou seja, tipo escalar).

  Esta função deve ser definida como:

  function fini(mixed `$context`, int `$rownumber`): mixed
  `context`

    Mantém o valor de retorno da última chamada à função step.

  `rownumber`

    Sempre `0`.

  O valor de retorno desta função será usado como o valor de retorno para o agregado.
`argCount`

  O número de argumentos que o agregado SQL recebe. Se este parâmetro for negativo, então o agregado SQL pode receber qualquer número de argumentos.

### Valor Retornado

Retorna `true` após a criação bem-sucedida do agregado, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de função de agregação max_length

    <?php
    $data = array(
       'one',
       'two',
       'three',
       'four',
       'five',
       'six',
       'seven',
       'eight',
       'nine',
       'ten',
       );
    $db = new SQLite3(':memory:');
    $db->exec("CREATE TABLE strings(a)");
    $insert = $db->prepare('INSERT INTO strings VALUES (?)');
    foreach ($data as $str) {
        $insert->bindValue(1, $str);
        $insert->execute();
    }
    $insert = null;

    function max_len_step($context, $rownumber, $string)
    {
        if (strlen($string) > $context) {
            $context = strlen($string);
        }
        return $context;
    }

    function max_len_finalize($context, $rownumber)
    {
        return $context === null ? 0 : $context;
    }

    $db->createAggregate('max_len', 'max_len_step', 'max_len_finalize');

    var_dump($db->querySingle('SELECT max_len(a) from strings'));
    ?>

O exemplo acima produzirá:

    int(5)

Neste exemplo, estamos criando uma função de agregação que calculará o comprimento da string mais longa em uma das colunas da tabela. Para cada linha, a função `max_len_step` é chamada e passada um parâmetro `$context`. O parâmetro de contexto é como qualquer outra variável PHP e pode ser definido para conter um array ou até mesmo um valor de objeto. Neste exemplo, estamos simplesmente usando-o para conter o comprimento máximo que vimos até agora; se a `$string` tiver um comprimento maior do que o máximo atual, atualizamos o contexto para armazenar este novo comprimento máximo.

Depois que todas as linhas forem processadas, o SQLite chama a função `max_len_finalize` para determinar o resultado da agregação. Aqui, poderíamos realizar algum tipo de cálculo com base nos dados encontrados no `$context`. Em nosso exemplo simples porém, estivemos calculando o resultado à medida que a consulta progredia, então simplesmente precisamos retornar o valor de contexto.

Dica

NÃO é recomendado que você armazene uma cópia dos valores no contexto e depois os processe no final, pois você faria com que o SQLite usasse muita memória para processar a consulta - apenas pense em quanto de memória você precisaria se um milhão de linhas fossem armazenadas em memória, cada uma contendo uma string de 32 bytes de comprimento.

Dica

Você pode usar SQLite3::createAggregate() para substituir funções SQL nativas do SQLite.

# SQLite3::createCollation

(PHP 5 >= 5.3.11, PHP 7, PHP 8)

SQLite3::createCollation — Registra uma função PHP para uso como uma função de comparação de SQL

### Descrição

public function SQLite3::createCollation(string `$name`, callable `$callback`): bool

Registra uma função PHP ou função definida pelo usuário para uso como uma função de comparação dentro de instruções SQL.

### Parâmetros

`name`

  Nome da função de comparação de SQL a ser criada ou redefinida

`callback`

  O nome de uma função PHP ou função definida pelo usuário para aplicar como um callback, definindo o comportamento da comparação. Ela deve aceitar dois valores e retornar como strcmp() faz, ou seja, deve retornar -1, 1 ou 0 se a primeira string ordena antes, ordena depois ou é igual à segunda.

  Esta função precisa ser definida como:

  function collation(mixed `$value1`, mixed `$value2`): int

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de SQLite3::createCollation()

Registre a função PHP strnatcmp() como uma sequência de comparação no banco de dados SQLite3.

    <?php

    $db = new SQLite3(":memory:");
    $db->exec("CREATE TABLE test (col1 string)");
    $db->exec("INSERT INTO test VALUES ('a1')");
    $db->exec("INSERT INTO test VALUES ('a10')");
    $db->exec("INSERT INTO test VALUES ('a2')");

    $db->createCollation('NATURAL_CMP', 'strnatcmp');

    $defaultSort = $db->query("SELECT col1 FROM test ORDER BY col1");
    $naturalSort = $db->query("SELECT col1 FROM test ORDER BY col1 COLLATE NATURAL_CMP");

    echo "default:\n";
    while ($row = $defaultSort->fetchArray()){
        echo $row['col1'], "\n";
    }

    echo "\nnatural:\n";
    while ($row = $naturalSort->fetchArray()){
        echo $row['col1'], "\n";
    }

    $db->close();

    ?>

O exemplo acima produzirá:

    default:
    a1
    a10
    a2

    natural:
    a1
    a2
    a10

### Veja Também

- A documentação de comparação SQLite: » http://sqlite.org/datatype3.html#collation

# SQLite3::createFunction

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::createFunction — Registra uma função PHP para uso como uma função escalar SQL

### Descrição

public function SQLite3::createFunction(
string `$name`,
callable `$callback`,
int `$argCount` = -1,
int `$flags` = 0
): bool

Registra uma função PHP ou função definida pelo usuário para uso como uma função escalar SQL dentro de instruções SQL.

### Parâmetros

`name`

  Nome da função SQL a ser criada ou redefinida.

`callback`

  O nome de uma função PHP ou função definida pelo usuário para aplicar como um callback, definindo o comportamento da função SQL.

  Esta função precisa ser definida como:

  function callback(mixed `$value`, mixed `...$values`): mixed
  `value`

    O primeiro argumento passado para a função SQL.

  `values`

    Mais argumentos passados para a função SQL.

`argCount`

  O número de argumentos que a função SQL recebe. Se este parâmetro for `-1`, então a função SQL pode receber qualquer número de argumentos.

`flags`

  Uma conjunção bitwise de opções. Atualmente, apenas `SQLITE3_DETERMINISTIC` é suportado, o que especifica que a função sempre retorna o mesmo resultado dado os mesmos argumentos dentro de uma única instrução SQL.

### Valor Retornado

Retorna `true` após a criação bem-sucedida da função, `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
7.1.4 | O parâmetro `flags` foi adicionado.

### Exemplos

Exemplo #1 Exemplo de SQLite3::createFunction()

    <?php
    function my_udf_md5($string) {
        return hash('md5', $string);
    }

    $db = new SQLite3('mysqlitedb.db');
    $db->createFunction('my_udf_md5', 'my_udf_md5');

    var_dump($db->querySingle('SELECT my_udf_md5("test")'));
    ?>

O exemplo acima produzirá algo semelhante a:

    string(32) "098f6bcd4621d373cade4e832627b4f6"

# SQLite3::enableExceptions

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::enableExceptions — Habilita o lançamento de exceções

### Descrição

public function SQLite3::enableExceptions(bool `$enable` = `false`): bool

Controla se a instância SQLite3 lançará exceções ou avisos em caso de erro.

### Parâmetros

`enable`

  Quando `true`, a instância SQLite3, e as instâncias SQLite3Stmt e SQLite3Result derivadas dela, lançarão exceções em caso de erro.

  Quando `false`, a instância SQLite3, e as instâncias SQLite3Stmt e SQLite3Result derivadas dela, emitirão avisos em caso de erro.

  Em qualquer modo, o código de erro e a mensagem, se houver, estarão disponíveis através de SQLite3::lastErrorCode() e SQLite3::lastErrorMsg(), respectivamente.

### Valor Retornado

Retorna o valor antigo; `true` se as exceções estavam habilitadas, `false` caso contrário.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Chamar SQLite3::enableExceptions() com `enable` como `false` irá disparar um aviso `E_DEPRECATED`.

### Exemplos

Exemplo #1 Exemplo de SQLite3::enableExceptions()

    <?php
    $sqlite = new SQLite3(':memory:');
    try {
        $sqlite->exec('create table foo');
        $sqlite->enableExceptions(true);
        $sqlite->exec('create table bar');
    } catch (Exception $e) {
        echo 'Caught exception: ' . $e->getMessage();
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Warning: SQLite3::exec(): near "foo": syntax error in example.php on line 4
    Caught exception: near "bar": syntax error

# SQLite3::escapeString

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::escapeString — Retorna uma string que foi devidamente escapada

### Descrição

public static function SQLite3::escapeString(string `$string`): string

Retorna uma string que foi devidamente escapada para inclusão segura em uma instrução SQL.

Aviso

Esta função (ainda) não é compatível com dados binários!

Para lidar adequadamente com campos BLOB que podem conter caracteres NUL, use SQLite3Stmt::bindParam() em vez disso.

### Parâmetros

`string`

  A string a ser escapada.

### Valor Retornado

Retorna uma string devidamente escapada que pode ser usada com segurança em uma instrução SQL.

### Notas

Aviso

addslashes() NÃO deve ser usado para citar suas strings para consultas SQLite; isso levará a resultados estranhos ao recuperar seus dados.

# SQLite3::exec

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::exec — Executa uma consulta sem resultado em um determinado banco de dados

### Descrição

public function SQLite3::exec(string `$query`): bool

Executa uma consulta sem resultado em um determinado banco de dados.

> Nota: O SQLite3 pode precisar criar » arquivos temporários durante a execução de consultas, então os diretórios respectivos podem precisar ter permissão de escrita.

### Parâmetros

`query`

  A consulta SQL a ser executada (geralmente uma consulta INSERT, UPDATE ou DELETE).

### Valor Retornado

Retorna `true` se a consulta for bem-sucedida, `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de SQLite3::exec()

    <?php
    $db = new SQLite3('mysqlitedb.db');

    $db->exec('CREATE TABLE bar (bar TEXT)');
    ?>

# SQLite3::lastErrorCode

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::lastErrorCode — Retorna o código de resultado numérico da última solicitação SQLite que falhou

### Descrição

public function SQLite3::lastErrorCode(): int

Retorna o código de resultado numérico da última solicitação SQLite que falhou.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um valor inteiro representando o código de resultado numérico da solicitação SQLite mais recente que falhou.

# SQLite3::lastErrorMsg

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::lastErrorMsg — Retorna o texto em inglês descrevendo a requisição SQLite mais recente que falhou

### Descrição

public function SQLite3::lastErrorMsg(): string

Retorna o texto em inglês descrevendo a requisição SQLite mais recente que falhou.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string em inglês descrevendo a requisição SQLite mais recente que falhou.

# SQLite3::lastInsertRowID

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::lastInsertRowID — Retorna o ID da linha mais recentemente INSERIDA no banco de dados

### Descrição

public function SQLite3::lastInsertRowID(): int

Retorna o ID da linha mais recentemente INSERIDA no banco de dados.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ID da linha mais recentemente inserida no banco de dados. Se nenhuma inserção bem-sucedida em tabelas com rowid já ocorreu nesta conexão de banco de dados, então SQLite3::lastInsertRowID() retorna `0`.

# SQLite3::loadExtension

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::loadExtension — Tenta carregar uma biblioteca de extensão do SQLite

### Descrição

public function SQLite3::loadExtension(string `$name`): bool

Tenta carregar uma biblioteca de extensão do SQLite.

### Parâmetros

`name`

  O nome da biblioteca a ser carregada. A biblioteca deve estar localizada no diretório especificado na opção de configuração sqlite3.extension_dir.

### Valor Retornado

Retorna `true` se a extensão for carregada com sucesso, `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de SQLite3::loadExtension()

    <?php
    $db = new SQLite3('mysqlitedb.db');
    $db->loadExtension('libagg.so');
    ?>

# SQLite3::open

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::open — Abre um banco de dados SQLite

### Descrição

public function SQLite3::open(string `$filename`, int `$flags` = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string `$encryptionKey` = ""): void

Abre um banco de dados SQLite 3. Se a compilação incluir criptografia, então tentará usar a chave.

### Parâmetros

`filename`

  Caminho para o banco de dados SQLite, ou `:memory:` para usar um banco de dados em memória.

`flags`

  Sinalizadores opcionais usados para determinar como abrir o banco de dados SQLite. Por padrão, o método open usa `SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE`.

  - `SQLITE3_OPEN_READONLY`: Abre o banco de dados somente para leitura.

  - `SQLITE3_OPEN_READWRITE`: Abre o banco de dados para leitura e escrita.

  - `SQLITE3_OPEN_CREATE`: Cria o banco de dados se ele não existir.

`encryptionKey`

  Uma chave de criptografia opcional usada ao criptografar e descriptografar um banco de dados SQLite. Se o módulo de criptografia SQLite não estiver instalado, este parâmetro não terá efeito.

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de SQLite3::open()

    <?php
    /**
     * Exemplo simples de extensão da classe SQLite3 e mudança dos parâmetros __construct,
     * e então usando o método open para inicializar o DB.
     */
    class MyDB extends SQLite3
    {
        function __construct()
        {
            $this->open('mysqlitedb.db');
        }
    }

    $db = new MyDB();

    $db->exec('CREATE TABLE foo (bar STRING)');
    $db->exec("INSERT INTO foo (bar) VALUES ('Isto é um teste')");

    $result = $db->query('SELECT bar FROM foo');
    var_dump($result->fetchArray());
    ?>

# SQLite3::openBlob

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::openBlob — Abre um recurso de fluxo para ler um BLOB

### Descrição

public function SQLite3::openBlob(
string `$table`,
string `$column`,
int `$rowid`,
string `$database` = "main",
int `$flags` = `SQLITE3_OPEN_READONLY`
): resource|false

Abre um recurso de fluxo para ler ou escrever um BLOB, que seria selecionado por:

SELECT `column` FROM `database`.`table` WHERE rowid = `rowid`

> Nota: Não é possível alterar o tamanho de um BLOB escrevendo no fluxo. Em vez disso, uma declaração UPDATE deve ser executada, possivelmente usando a função zeroblob() do SQLite para definir o tamanho desejado do BLOB.

### Parâmetros

`table`

  O nome da tabela.

`column`

  O nome da coluna.

`rowid`

  O ID da linha.

`database`

  O nome simbólico do banco de dados.

`flags`

  Seja `SQLITE3_OPEN_READONLY` ou `SQLITE3_OPEN_READWRITE` para abrir o fluxo somente para leitura ou para leitura e escrita, respectivamente.

### Valor Retornado

Retorna um recurso de fluxo, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
7.2.0 | O parâmetro `flags` foi adicionado, permitindo escrever BLOBs; anteriormente, apenas a leitura era suportada.

### Exemplos

Exemplo #1 Exemplo de SQLite3::openBlob()

    <?php
    $conn = new SQLite3(':memory:');
    $conn->exec('CREATE TABLE test (text text)');
    $conn->exec("INSERT INTO test VALUES ('Lorem ipsum')");
    $stream = $conn->openBlob('test', 'text', 1);
    echo stream_get_contents($stream);
    fclose($stream); // obrigatório, caso contrário a próxima linha falharia
    $conn->close();
    ?>

O exemplo acima produzirá:

    Lorem ipsum

Exemplo #2 Escrevendo incrementalmente um BLOB

    <?php
    $conn = new SQLite3(':memory:');
    $conn->exec('CREATE TABLE test (text text)');
    $conn->exec("INSERT INTO test VALUES (zeroblob(36))");
    $stream = $conn->openBlob('test', 'text', 1, 'main', SQLITE3_OPEN_READWRITE);
    for ($i = 0; $i < 3; $i++) {
        fwrite($stream,  "Lorem ipsum\n");
    }
    fclose($stream);
    echo $conn->querySingle("SELECT text FROM test");
    $conn->close();
    ?>

O exemplo acima produzirá:

    Lorem ipsum
    Lorem ipsum
    Lorem ipsum

# SQLite3::prepare

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::prepare — Prepara uma declaração SQL para execução

### Descrição

public function SQLite3::prepare(string `$query`): SQLite3Stmt|false

Prepara uma declaração SQL para execução e retorna um objeto SQLite3Stmt.

### Parâmetros

`query`

  A consulta SQL a ser preparada.

### Valor Retornado

Retorna um objeto SQLite3Stmt em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de SQLite3::prepare()

    <?php
    unlink('mysqlitedb.db');
    $db = new SQLite3('mysqlitedb.db');

    $db->exec('CREATE TABLE foo (id INTEGER, bar STRING)');
    $db->exec("INSERT INTO foo (id, bar) VALUES (1, 'Isto é um teste')");

    $stmt = $db->prepare('SELECT bar FROM foo WHERE id=:id');
    $stmt->bindValue(':id', 1, SQLITE3_INTEGER);

    $result = $stmt->execute();
    var_dump($result->fetchArray());
    ?>

### Veja Também

- SQLite3Stmt::paramCount() - Retorna o número de parâmetros dentro da declaração preparada
- SQLite3Stmt::bindValue() - Vincula o valor de um parâmetro a uma variável de instrução
- SQLite3Stmt::bindParam() - Vincula um parâmetro a uma variável de instrução

# SQLite3::query

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::query — Executa uma consulta SQL

### Descrição

public function SQLite3::query(string `$query`): SQLite3Result|false

Executa uma consulta SQL, retornando um objeto SQLite3Result. Se a consulta não produzir um resultado (como declarações DML), o objeto SQLite3Result retornado não será realmente utilizável. Use SQLite3::exec() para essas consultas.

### Parâmetros

`query`

  A consulta SQL a ser executada.

### Valor Retornado

Retorna um objeto SQLite3Result, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de SQLite3::query()

    <?php
    $db = new SQLite3('mysqlitedb.db');

    $results = $db->query('SELECT bar FROM foo');
    while ($row = $results->fetchArray()) {
        var_dump($row);
    }
    ?>

# SQLite3::querySingle

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::querySingle — Executa uma consulta e retorna um único resultado

### Descrição

public function SQLite3::querySingle(string `$query`, bool `$entireRow` = `false`): mixed

Executa uma consulta e retorna um único resultado.

### Parâmetros

`query`

  A consulta SQL a ser executada.

`entireRow`

  Por padrão, querySingle() retorna o valor da primeira coluna retornada pela consulta. Se `entireRow` for `true`, então ele retorna um array da linha inteira.

### Valor Retornado

Retorna o valor da primeira coluna dos resultados ou um array da primeira linha inteira (se `entireRow` for `true`).

Se a consulta for válida mas nenhum resultado for retornado, então `null` será retornado se `entireRow` for `false`, caso contrário um array vazio é retornado.

Consultas inválidas ou falhadas retornarão `false`.

### Exemplos

Exemplo #1 Exemplo de SQLite3::querySingle()

    <?php
    $db = new SQLite3('mysqlitedb.db');

    var_dump($db->querySingle('SELECT username FROM user WHERE userid=1'));
    print_r($db->querySingle('SELECT username, email FROM user WHERE userid=1', true));
    ?>

O exemplo acima produzirá algo semelhante a:

    string(5) "Scott"
    Array
    (
        [username] => Scott
        [email] => scott@example.com
    )

# SQLite3::setAuthorizer

(PHP 8)

SQLite3::setAuthorizer — Configura um retorno de chamada a ser usado como um autorizador para limitar o que uma declaração pode fazer

### Descrição

public function SQLite3::setAuthorizer(?callable `$callback`): bool

Define um retorno de chamada que será chamado pelo SQLite toda vez que uma ação for executada (leitura, exclusão, atualização, etc.). Isso é usado ao preparar uma declaração SQL de uma fonte não confiável para garantir que as declarações SQL não tentem acessar dados aos quais não têm permissão para ver, ou que não tentem executar declarações maliciosas que danifiquem o banco de dados. Por exemplo, um aplicativo pode permitir que um usuário insira consultas SQL arbitrárias para avaliação por um banco de dados. Mas o aplicativo não quer que o usuário possa fazer alterações arbitrárias no banco de dados. Um autorizador poderia então ser colocado em prática enquanto o SQL inserido pelo usuário está sendo preparado, o que proíbe tudo exceto declarações SELECT.

O retorno de chamada do autorizador pode ser chamado várias vezes para cada declaração preparada pelo SQLite. Uma consulta `SELECT` ou `UPDATE` chamará o autorizador para cada coluna que seria lida ou atualizada.

O autorizador é chamado com até cinco parâmetros. O primeiro parâmetro é sempre fornecido e é um int (código de ação) correspondente a uma constante de `SQLite3`. Os outros parâmetros são passados apenas para algumas ações. A tabela a seguir descreve o segundo e o terceiro parâmetros de acordo com a ação:

Lista de códigos de ação e parâmetros
Ação | Segundo parâmetro | Terceiro parâmetro
--- | --- | ---
`SQLite3::CREATE_INDEX` | Nome do Índice | Nome da Tabela
`SQLite3::CREATE_TABLE` | Nome da Tabela | `null`
`SQLite3::CREATE_TEMP_INDEX` | Nome do Índice | Nome da Tabela
`SQLite3::CREATE_TEMP_TABLE` | Nome da Tabela | `null`
`SQLite3::CREATE_TEMP_TRIGGER` | Nome do Gatilho | Nome da Tabela
`SQLite3::CREATE_TEMP_VIEW` | Nome da Visualização | `null`
`SQLite3::CREATE_TRIGGER` | Nome do Gatilho | Nome da Tabela
`SQLite3::CREATE_VIEW` | Nome da Visualização | `null`
`SQLite3::DELETE` | Nome da Tabela | `null`
`SQLite3::DROP_INDEX` | Nome do Índice | Nome da Tabela
`SQLite3::DROP_TABLE` | Nome da Tabela | `null`
`SQLite3::DROP_TEMP_INDEX` | Nome do Índice | Nome da Tabela
`SQLite3::DROP_TEMP_TABLE` | Nome da Tabela | `null`
`SQLite3::DROP_TEMP_TRIGGER` | Nome do Gatilho | Nome da Tabela
`SQLite3::DROP_TEMP_VIEW` | Nome da Visualização | `null`
`SQLite3::DROP_TRIGGER` | Nome do Gatilho | Nome da Tabela
`SQLite3::DROP_VIEW` | Nome da Visualização | `null`
`SQLite3::INSERT` | Nome da Tabela | `null`
`SQLite3::PRAGMA` | Nome do Pragma | Primeiro argumento passado ao pragma, ou `null`
`SQLite3::READ` | Nome da Tabela | Nome da Coluna
`SQLite3::SELECT` | `null` | `null`
`SQLite3::TRANSACTION` | Operação | `null`
`SQLite3::UPDATE` | Nome da Tabela | Nome da Coluna
`SQLite3::ATTACH` | Nome do Arquivo | `null`
`SQLite3::DETACH` | Nome do Banco de Dados | `null`
`SQLite3::ALTER_TABLE` | Nome do Banco de Dados | Nome da Tabela
`SQLite3::REINDEX` | Nome do Índice | `null`
`SQLite3::ANALYZE` | Nome da Tabela | `null`
`SQLite3::CREATE_VTABLE` | Nome da Tabela | Nome do Módulo
`SQLite3::DROP_VTABLE` | Nome da Tabela | Nome do Módulo
`SQLite3::FUNCTION` | `null` | Nome da Função
`SQLite3::SAVEPOINT` | Operação | Nome do Ponto de Salvamento
`SQLite3::RECURSIVE` | `null` | `null`

O 4º parâmetro será o nome do banco de dados (`"main"`, `"temp"`, etc.) se aplicável.

O 5º parâmetro para o retorno de chamada do autorizador é o nome do gatilho ou visualização mais interno responsável pela tentativa de acesso ou `null` se esta tentativa de acesso é diretamente a partir do código SQL de nível superior.

Quando o retorno de chamada retorna `SQLite3::OK`, isso significa que a operação solicitada é aceita. Quando o retorno de chamada retorna `SQLite3::DENY`, a chamada que acionou o autorizador falhará com uma mensagem de erro explicando que o acesso foi negado.

Se o código de ação for `SQLite3::READ` e o retorno de chamada retornar `SQLite3::IGNORE`, então a declaração preparada é construída para substituir um valor `null` no lugar da coluna da tabela que seria lida se `SQLite3::OK` tivesse sido retornado. O retorno `SQLite3::IGNORE` pode ser usado para negar a um usuário não confiável o acesso a colunas individuais de uma tabela.

Quando uma tabela é referenciada por um `SELECT`, mas nenhum valor de coluna é extraído dessa tabela (por exemplo, em uma consulta como `"SELECT count(*) FROM table"`), então o retorno de chamada do autorizador `SQLite3::READ` é invocado uma vez para essa tabela com um nome de coluna que é uma string vazia.

Se o código de ação for `SQLite3::DELETE` e o retorno de chamada retornar `SQLite3::IGNORE`, então a operação DELETE prossegue, mas a otimização de truncamento é desativada e todas as linhas são excluídas individualmente.

Apenas um autorizador pode estar em vigor em uma conexão de banco de dados de cada vez. Cada chamada para SQLite3::setAuthorizer() substitui a chamada anterior. Desative o autorizador instalando um retorno de chamada `null`. O autorizador é desativado por padrão.

O retorno de chamada do autorizador não deve fazer nada que modifique a conexão de banco de dados que invocou o retorno de chamada do autorizador.

Observe que o autorizador é chamado apenas quando uma declaração é preparada, não quando ela é executada.

Mais detalhes podem ser encontrados na » documentação do SQLite3.

### Parâmetros

`callback`

  O callable a ser chamado.

  Se `null` for passado, isso desativará o retorno de chamada do autorizador atual.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Este método não lança nenhum erro, mas se um autorizador estiver habilitado e retornar um valor inválido, a preparação da declaração lançará um erro (ou exceção, dependendo do uso do método SQLite3::enableExceptions()).

### Exemplos

Exemplo #1 Exemplo de SQLite3::setAuthorizer()

Isso permite apenas o acesso à leitura, e apenas algumas colunas da tabela `users` serão retornadas. Outras colunas serão substituídas por `null`.

    <?php
    $db = new SQLite3('data.sqlite');
    $db->exec('CREATE TABLE users (id, name, password);');
    $db->exec('INSERT INTO users VALUES (1, \'Pauline\', \'Snails4eva\');');

    $allowed_columns = ['id', 'name'];

    $db->setAuthorizer(function (int $action, ...$args) use ($allowed_columns) {
        if ($action === SQLite3::READ) {
            list($table, $column) = $args;

            if ($table === 'users' && in_array($column, $allowed_columns)) {
                return SQLite3::OK;
            }

            return SQLite3::IGNORE;
        }

        return SQLite3::DENY;
    });

    print_r($db->querySingle('SELECT * FROM users WHERE id = 1;'));

O exemplo acima produzirá:

    Array
    (
        [id] => 1
        [name] => Pauline
        [password] =>
    )

# SQLite3::version

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::version — Retorna a versão da biblioteca SQLite3 como uma constante de string e como um número

### Descrição

public static function SQLite3::version(): array

Retorna a versão da biblioteca SQLite3 como uma constante de string e como um número.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array associativo com as chaves "versionString" e "versionNumber".

### Exemplos

Exemplo #1 Exemplo de SQLite3::version()

    <?php
    print_r(SQLite3::version());
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [versionString] => 3.5.9
        [versionNumber] => 3005009
    )

## Índice

- SQLite3::backup — Copia um banco de dados para outro banco de dados
- SQLite3::busyTimeout — Define o manipulador de conexão ocupada
- SQLite3::changes — Retorna o número de linhas do banco de dados que foram alteradas (ou inseridas ou excluídas) pela instrução SQL mais recente
- SQLite3::close — Fecha a conexão com o banco de dados
- SQLite3::__construct — Instancia um objeto SQLite3 e abre um banco de dados SQLite 3
- SQLite3::createAggregate — Registra uma função PHP para uso como uma função de agregação SQL
- SQLite3::createCollation — Registra uma função PHP para uso como uma função de comparação de SQL
- SQLite3::createFunction — Registra uma função PHP para uso como uma função escalar SQL
- SQLite3::enableExceptions — Habilita o lançamento de exceções
- SQLite3::escapeString — Retorna uma string que foi devidamente escapada
- SQLite3::exec — Executa uma consulta sem resultado em um determinado banco de dados
- SQLite3::lastErrorCode — Retorna o código de resultado numérico da última solicitação SQLite que falhou
- SQLite3::lastErrorMsg — Retorna o texto em inglês descrevendo a requisição SQLite mais recente que falhou
- SQLite3::lastInsertRowID — Retorna o ID da linha mais recentemente INSERIDA no banco de dados
- SQLite3::loadExtension — Tenta carregar uma biblioteca de extensão do SQLite
- SQLite3::open — Abre um banco de dados SQLite
- SQLite3::openBlob — Abre um recurso de fluxo para ler um BLOB
- SQLite3::prepare — Prepara uma declaração SQL para execução
- SQLite3::query — Executa uma consulta SQL
- SQLite3::querySingle — Executa uma consulta e retorna um único resultado
- SQLite3::setAuthorizer — Configura um retorno de chamada a ser usado como um autorizador para limitar o que uma declaração pode fazer
- SQLite3::version — Retorna a versão da biblioteca SQLite3 como uma constante de string e como um número

# A classe SQLite3Exception

(PHP 8 >= 8.3.0)

## Introdução

Representa uma exceção específica do SQLite3.

## Resumo da classe

class SQLite3Exception extends Exception {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# A classe SQLite3Stmt

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Introdução

Uma classe que lida com declarações preparadas para a extensão SQLite 3.

## Resumo da classe

class SQLite3Stmt {
/* Métodos */
private function __construct(SQLite3 `$sqlite3`, string `$query`)
public function bindParam(string|int `$param`, mixed `&$var`, int `$type` = `SQLITE3_TEXT`): bool
public function bindValue(string|int `$param`, mixed `$value`, int `$type` = `SQLITE3_TEXT`): bool
public function clear(): bool
public function close(): true
public function execute(): SQLite3Result|false
public function getSQL(bool `$expand` = `false`): string|false
public function paramCount(): int
public function readOnly(): bool
public function reset(): bool
}

# SQLite3Stmt::bindParam

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::bindParam — Vincula um parâmetro a uma variável de instrução

### Descrição

public function SQLite3Stmt::bindParam(string|int `$param`, mixed `&$var`, int `$type` = `SQLITE3_TEXT`): bool

Vincula um parâmetro a uma variável de instrução.

Cuidado

Antes do PHP 7.2.14 e 7.3.0, respectivamente, SQLite3Stmt::reset() deve ser chamado após a primeira chamada para SQLite3Stmt::execute() se o valor vinculado deve ser corretamente atualizado nas chamadas seguintes para SQLite3Stmt::execute(). Se SQLite3Stmt::reset() não for chamado, o valor vinculado não será alterado, mesmo que o valor atribuído à variável passada para SQLite3Stmt::bindParam() tenha mudado, ou SQLite3Stmt::bindParam() tenha sido chamado novamente.

### Parâmetros

`param`
  Uma string (para parâmetros nomeados) ou um int (para parâmetros posicionais) identificando a variável de instrução à qual o valor deve ser vinculado. Se um parâmetro nomeado não começar com dois pontos (`:`) ou um sinal de arroba (`@`), dois pontos (`:`) são automaticamente adicionados. Parâmetros posicionais começam com `1`.
`var`

  O parâmetro a ser vinculado a uma variável de instrução.

`type`

  O tipo de dados do parâmetro a ser vinculado.

  - `SQLITE3_INTEGER`: O valor é um inteiro assinado, armazenado em 1, 2, 3, 4, 6 ou 8 bytes, dependendo da magnitude do valor.

  - `SQLITE3_FLOAT`: O valor é um valor de ponto flutuante, armazenado como um número de ponto flutuante IEEE de 8 bytes.

  - `SQLITE3_TEXT`: O valor é uma string de texto, armazenada usando a codificação do banco de dados (UTF-8, UTF-16BE ou UTF-16-LE).

  - `SQLITE3_BLOB`: O valor é um blob de dados, armazenado exatamente como foi inserido.

  - `SQLITE3_NULL`: O valor é um valor NULL.

  A partir do PHP 7.0.7, se `type` for omitido, ele é automaticamente detectado a partir do tipo do `var`: bool e int são tratados como `SQLITE3_INTEGER`, float como `SQLITE3_FLOAT`, null como `SQLITE3_NULL` e todos os outros como `SQLITE3_TEXT`. Anteriormente, se `type` fosse omitido, ele era predefinido como `SQLITE3_TEXT`.

  > Nota:

  > Se `var` for `null`, ele é sempre tratado como `SQLITE3_NULL`, independentemente do `type` fornecido.

### Valor Retornado

Retorna `true` se o parâmetro for vinculado à variável de instrução, `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
7.4.0 | `param` agora também suporta a notação `@param`.

### Exemplos

Exemplo #1 Uso de SQLite3Stmt::bindParam()

Este exemplo mostra como uma única instrução preparada com uma única vinculação de parâmetro pode ser usada para inserir várias linhas com valores diferentes.

    <?php
    $db = new SQLite3(':memory:');
    $db->exec("CREATE TABLE foo (bar TEXT)");

    $stmt = $db->prepare("INSERT INTO foo VALUES (:bar)");
    $stmt->bindParam(':bar', $bar, SQLITE3_TEXT);

    $bar = 'baz';
    $stmt->execute();

    $bar = 42;
    $stmt->execute();

    $res = $db->query("SELECT * FROM foo");
    while (($row = $res->fetchArray(SQLITE3_ASSOC))) {
        var_dump($row);
    }
    ?>

O exemplo acima produzirá:

    array(1) {
      ["bar"]=>
      string(3) "baz"
    }
    array(1) {
      ["bar"]=>
      string(2) "42"
    }

### Veja Também

- SQLite3Stmt::bindValue() - Vincula o valor de um parâmetro a uma variável de instrução
- SQLite3::prepare() - Prepara uma declaração SQL para execução

# SQLite3Stmt::bindValue

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::bindValue — Vincula o valor de um parâmetro a uma variável de instrução

### Descrição

public function SQLite3Stmt::bindValue(string|int `$param`, mixed `$value`, int `$type` = `SQLITE3_TEXT`): bool

Vincula o valor de um parâmetro a uma variável de instrução.

Cuidado

Antes do PHP 7.2.14 e 7.3.0, respectivamente, uma vez que a instrução foi executada, SQLite3Stmt::reset() precisa ser chamado para poder alterar o valor dos parâmetros vinculados.

### Parâmetros

`param`
  Uma string (para parâmetros nomeados) ou um int (para parâmetros posicionais) identificando a variável de instrução à qual o valor deve ser vinculado. Se um parâmetro nomeado não começar com dois pontos (`:`) ou um sinal de arroba (`@`), dois pontos (`:`) são automaticamente adicionados. Parâmetros posicionais começam com `1`.
`value`

  O valor a ser vinculado a uma variável de instrução.

`type`

  O tipo de dados do valor a ser vinculado.

  - `SQLITE3_INTEGER`: O valor é um inteiro assinado, armazenado em 1, 2, 3, 4, 6 ou 8 bytes, dependendo da magnitude do valor.

  - `SQLITE3_FLOAT`: O valor é um valor de ponto flutuante, armazenado como um número de ponto flutuante IEEE de 8 bytes.

  - `SQLITE3_TEXT`: O valor é uma string de texto, armazenada usando a codificação do banco de dados (UTF-8, UTF-16BE ou UTF-16-LE).

  - `SQLITE3_BLOB`: O valor é um blob de dados, armazenado exatamente como foi inserido.

  - `SQLITE3_NULL`: O valor é um valor NULL.

  A partir do PHP 7.0.7, se `type` for omitido, ele é automaticamente detectado a partir do tipo do `value`: bool e int são tratados como `SQLITE3_INTEGER`, float como `SQLITE3_FLOAT`, null como `SQLITE3_NULL` e todos os outros como `SQLITE3_TEXT`. Anteriormente, se `type` fosse omitido, ele era predefinido como `SQLITE3_TEXT`.

  > Nota:

  > Se `value` for `null`, ele é sempre tratado como `SQLITE3_NULL`, independentemente do `type` fornecido.

### Valor Retornado

Retorna `true` se o valor for vinculado à variável de instrução, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
7.4.0 | `param` agora também suporta a notação `@param`.

### Exemplos

Exemplo #1 Exemplo de SQLite3Stmt::bindValue()

    <?php
    $db = new SQLite3(':memory:');

    $db->exec('CREATE TABLE foo (id INTEGER, bar STRING)');
    $db->exec("INSERT INTO foo (id, bar) VALUES (1, 'Isto é um teste')");

    $stmt = $db->prepare('SELECT bar FROM foo WHERE id=:id');
    $stmt->bindValue(':id', 1, SQLITE3_INTEGER);

    $result = $stmt->execute();
    var_dump($result->fetchArray(SQLITE3_ASSOC));
    ?>

O exemplo acima produzirá:

    array(1) {
      ["bar"]=>
      string(14) "Isto é um teste"
    }

### Veja Também

- SQLite3Stmt::bindParam() - Vincula um parâmetro a uma variável de instrução
- SQLite3::prepare() - Prepara uma declaração SQL para execução

# SQLite3Stmt::clear

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::clear — Limpa todos os parâmetros vinculados atuais

### Descrição

public function SQLite3Stmt::clear(): bool

Limpa todos os parâmetros vinculados atuais (eles são definidos como `null`).

Cuidado

Este método precisa ser usado com SQLite3Stmt::reset(). Se usado sozinho, qualquer chamada para SQLite3Stmt::bindValue() ou SQLite3Stmt::bindParam() não terá efeito e todos os parâmetros vinculados terão o valor `null`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` após a limpeza bem-sucedida dos parâmetros vinculados, `false` em caso de falha.

# SQLite3Stmt::close

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::close — Fecha a declaração preparada

### Descrição

public function SQLite3Stmt::close(): true

Fecha a declaração preparada.

> Nota: Note que todos os SQLite3Results que foram recuperados executando esta declaração serão invalidados quando a declaração for fechada.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Sempre retorna `true`.

### Erros/Exceções

Uma exceção Error é lançada se o método for chamado em um objeto não inicializado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Este método agora lança uma exceção Error se o objeto não for inicializado corretamente. Anteriormente, retornava `false`.

# SQLite3Stmt::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::__construct — Constrói um objeto SQLite3Stmt

### Descrição

private function SQLite3Stmt::__construct(SQLite3 `$sqlite3`, string `$query`)

As instâncias de SQLite3Stmt são criadas por SQLite3::prepare().

### Parâmetros

`sqlite3`

`query`

# SQLite3Stmt::execute

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::execute — Executa uma declaração preparada e retorna um objeto de conjunto de resultados

### Descrição

public function SQLite3Stmt::execute(): SQLite3Result|false

Executa uma declaração preparada e retorna um objeto de conjunto de resultados.

Cuidado

Os objetos de conjunto de resultados recuperados chamando este método no mesmo objeto de declaração não são independentes, mas compartilham a mesma estrutura subjacente. Portanto, é recomendável chamar SQLite3Result::finalize() antes de chamar SQLite3Stmt::execute() novamente no mesmo objeto de declaração.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um objeto SQLite3Result na execução bem-sucedida da declaração preparada, `false` em caso de falha.

### Veja Também

- SQLite3::prepare() - Prepara uma declaração SQL para execução
- SQLite3Stmt::bindValue() - Vincula o valor de um parâmetro a uma variável de instrução
- SQLite3Stmt::bindParam() - Vincula um parâmetro a uma variável de instrução

# SQLite3Stmt::getSQL

(PHP 7 >= 7.4.0, PHP 8)

SQLite3Stmt::getSQL — Obtém o SQL da instrução

### Descrição

public function SQLite3Stmt::getSQL(bool `$expand` = `false`): string|false

Recupera o SQL da instrução preparada. Se `expand` for `false`, o SQL não modificado é recuperado. Se `expand` for `true`, todos os parâmetros da consulta são substituídos por seus valores vinculados, ou por um SQL `NULL`, se ainda não estiverem vinculados.

### Parâmetros

`expand`

  Se deseja recuperar o SQL expandido. Passar `true` só é suportado a partir do libsqlite 3.14.

### Valor Retornado

Retorna o SQL da instrução preparada, ou `false` em caso de falha.

### Erros/Exceções

Se `expand` for `true`, mas a versão do libsqlite for inferior a 3.14, um erro de nível `E_WARNING` ou uma Exception é emitido, de acordo com SQLite3::enableExceptions().

### Exemplos

Exemplo #1 Inspeção do SQL expandido

    <?php
    $db = new SQLite3(':memory:');
    $stmt = $db->prepare("SELECT :a, ?, :c");
    $stmt->bindValue(':a', 'foo');
    $answer = 42;
    $stmt->bindParam(2, $answer);
    var_dump($stmt->getSQL(true));
    ?>

O exemplo acima produzirá algo semelhante a:

    string(24) "SELECT 'foo', '42', NULL"

# SQLite3Stmt::paramCount

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::paramCount — Retorna o número de parâmetros dentro da declaração preparada

### Descrição

public function SQLite3Stmt::paramCount(): int

Retorna o número de parâmetros dentro da declaração preparada.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número de parâmetros dentro da declaração preparada.

### Veja Também

- SQLite3::prepare() - Prepara uma declaração SQL para execução

# SQLite3Stmt::readOnly

(PHP 5 >= 5.3.6, PHP 7, PHP 8)

SQLite3Stmt::readOnly — Retorna se uma declaração é definitivamente somente leitura

### Descrição

public function SQLite3Stmt::readOnly(): bool

Retorna se uma declaração é definitivamente somente leitura. Uma declaração é considerada somente leitura se não fizer alterações diretas no conteúdo do arquivo de banco de dados. Observe que funções SQL definidas pelo usuário podem alterar o banco de dados indiretamente como um efeito colateral.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se uma declaração é definitivamente somente leitura, `false` caso contrário.

# SQLite3Stmt::reset

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::reset — Reseta a declaração preparada

### Descrição

public function SQLite3Stmt::reset(): bool

Reseta a declaração preparada para seu estado anterior à execução. Todas as ligações permanecem intactas após o reset.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se a declaração for resetada com sucesso, ou `false` em caso de falha.

## Índice

- SQLite3Stmt::bindParam — Vincula um parâmetro a uma variável de instrução
- SQLite3Stmt::bindValue — Vincula o valor de um parâmetro a uma variável de instrução
- SQLite3Stmt::clear — Limpa todos os parâmetros vinculados atuais
- SQLite3Stmt::close — Fecha a declaração preparada
- SQLite3Stmt::__construct — Constrói um objeto SQLite3Stmt
- SQLite3Stmt::execute — Executa uma declaração preparada e retorna um objeto de conjunto de resultados
- SQLite3Stmt::getSQL — Obtém o SQL da instrução
- SQLite3Stmt::paramCount — Retorna o número de parâmetros dentro da declaração preparada
- SQLite3Stmt::readOnly — Retorna se uma declaração é definitivamente somente leitura
- SQLite3Stmt::reset — Reseta a declaração preparada

# A classe SQLite3Result

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Introdução

Uma classe que manipula conjuntos de resultados para a extensão SQLite 3.

## Resumo da classe

class SQLite3Result {
/* Métodos */
private function __construct()
public function columnName(int `$column`): string|false
public function columnType(int `$column`): int|false
public function fetchArray(int `$mode` = `SQLITE3_BOTH`): array|false
public function finalize(): true
public function numColumns(): int
public function reset(): bool
}

# SQLite3Result::columnName

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::columnName — Retorna o nome da enésima coluna

### Descrição

public function SQLite3Result::columnName(int `$column`): string|false

Retorna o nome da coluna especificada pelo `column`. Observe que o nome de uma coluna de resultado é o valor da cláusula `AS` para essa coluna, se houver uma cláusula `AS`. Se não houver uma cláusula `AS`, então o nome da coluna é não especificado e pode mudar de uma versão para outra do libsqlite3.

### Parâmetros

`column`

  O índice baseado em zero, numérico, da coluna.

### Valor Retornado

Retorna o string nome da coluna identificada por `column`, ou `false` se a coluna não existir.

# SQLite3Result::columnType

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::columnType — Retorna o tipo da enésima coluna

### Descrição

public function SQLite3Result::columnType(int `$column`): int|false

Retorna o tipo da coluna identificada por `column`.

### Parâmetros

`column`

  O índice baseado em zero, numérico, da coluna.

### Valor Retornado

Retorna o índice do tipo de dados da coluna identificada por `column` (um dos `SQLITE3_INTEGER`, `SQLITE3_FLOAT`, `SQLITE3_TEXT`, `SQLITE3_BLOB` ou `SQLITE3_NULL`), ou `false` se a coluna não existir.

# SQLite3Result::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::__construct — Constrói um SQLite3Result

### Descrição

private function SQLite3Result::__construct()

As instâncias de SQLite3Result são criadas por SQLite3::query() e SQLite3Stmt::execute().

### Parâmetros

Esta função não possui parâmetros.

# SQLite3Result::fetchArray

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::fetchArray — Obtém uma linha de resultado como um array associativo, numericamente indexado ou ambos

### Descrição

public function SQLite3Result::fetchArray(int `$mode` = `SQLITE3_BOTH`): array|false

Obtém uma linha de resultado como um array associativo, numericamente indexado ou ambos. Por padrão, obtém como ambos.

### Parâmetros

`mode`

  Controla como a próxima linha será retornada ao chamador. Este valor deve ser um dos seguintes: `SQLITE3_ASSOC`, `SQLITE3_NUM` ou `SQLITE3_BOTH`.

  - `SQLITE3_ASSOC`: retorna um array indexado pelo nome da coluna conforme retornado no conjunto de resultados correspondente

  - `SQLITE3_NUM`: retorna um array indexado pelo número da coluna conforme retornado no conjunto de resultados correspondente, começando na coluna 0

  - `SQLITE3_BOTH`: retorna um array indexado tanto pelo nome da coluna quanto pelo número da coluna conforme retornado no conjunto de resultados correspondente, começando na coluna 0

### Valor Retornado

Retorna uma linha de resultado como um array associativo, numericamente indexado ou ambos. Alternativamente, retornará `false` se não houver mais linhas.

Os tipos dos valores do array retornado são mapeados a partir dos tipos SQLite3 como segue: inteiros são mapeados para int se estiverem dentro do intervalo `PHP_INT_MIN`..`PHP_INT_MAX`, e para string caso contrário. Floats são mapeados para float, valores `NULL` são mapeados para null, e strings e blobs são mapeados para string.

# SQLite3Result::finalize

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::finalize — Fecha o conjunto de resultados

### Descrição

public function SQLite3Result::finalize(): true

Fecha o conjunto de resultados.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Sempre retorna `true`.

### Erros/Exceções

Uma exceção Error é lançada se o método for chamado em um objeto não inicializado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Este método agora lança uma exceção Error se o objeto não for inicializado corretamente. Anteriormente, retornava `false`.

# SQLite3Result::numColumns

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::numColumns — Retorna o número de colunas no conjunto de resultados

### Descrição

public function SQLite3Result::numColumns(): int

Retorna o número de colunas no conjunto de resultados.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número de colunas no conjunto de resultados.

# SQLite3Result::reset

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::reset — Reinicia o conjunto de resultados de volta para a primeira linha

### Descrição

public function SQLite3Result::reset(): bool

Reinicia o conjunto de resultados de volta para a primeira linha.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se o conjunto de resultados for reiniciado com sucesso para a primeira linha, `false` em caso de falha.

## Índice

- SQLite3Result::columnName — Retorna o nome da enésima coluna
- SQLite3Result::columnType — Retorna o tipo da enésima coluna
- SQLite3Result::__construct — Constrói um SQLite3Result
- SQLite3Result::fetchArray — Obtém uma linha de resultado como um array associativo, numericamente indexado ou ambos
- SQLite3Result::finalize — Fecha o conjunto de resultados
- SQLite3Result::numColumns — Retorna o número de colunas no conjunto de resultados
- SQLite3Result::reset — Reinicia o conjunto de resultados de volta para a primeira linha

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
- Constantes predefinidas
- SQLite3 — A classe SQLite3
  - SQLite3::backup — Copia um banco de dados para outro banco de dados
  - SQLite3::busyTimeout — Define o manipulador de conexão ocupada
  - SQLite3::changes — Retorna o número de linhas do banco de dados que foram alteradas (ou inseridas ou excluídas) pela instrução SQL mais recente
  - SQLite3::close — Fecha a conexão com o banco de dados
  - SQLite3::__construct — Instancia um objeto SQLite3 e abre um banco de dados SQLite 3
  - SQLite3::createAggregate — Registra uma função PHP para uso como uma função de agregação SQL
  - SQLite3::createCollation — Registra uma função PHP para uso como uma função de comparação de SQL
  - SQLite3::createFunction — Registra uma função PHP para uso como uma função escalar SQL
  - SQLite3::enableExceptions — Habilita o lançamento de exceções
  - SQLite3::escapeString — Retorna uma string que foi devidamente escapada
  - SQLite3::exec — Executa uma consulta sem resultado em um determinado banco de dados
  - SQLite3::lastErrorCode — Retorna o código de resultado numérico da última solicitação SQLite que falhou
  - SQLite3::lastErrorMsg — Retorna o texto em inglês descrevendo a requisição SQLite mais recente que falhou
  - SQLite3::lastInsertRowID — Retorna o ID da linha mais recentemente INSERIDA no banco de dados
  - SQLite3::loadExtension — Tenta carregar uma biblioteca de extensão do SQLite
  - SQLite3::open — Abre um banco de dados SQLite
  - SQLite3::openBlob — Abre um recurso de fluxo para ler um BLOB
  - SQLite3::prepare — Prepara uma declaração SQL para execução
  - SQLite3::query — Executa uma consulta SQL
  - SQLite3::querySingle — Executa uma consulta e retorna um único resultado
  - SQLite3::setAuthorizer — Configura um retorno de chamada a ser usado como um autorizador para limitar o que uma declaração pode fazer
  - SQLite3::version — Retorna a versão da biblioteca SQLite3 como uma constante de string e como um número
- SQLite3Exception — A classe SQLite3Exception
- SQLite3Stmt — A classe SQLite3Stmt
  - SQLite3Stmt::bindParam — Vincula um parâmetro a uma variável de instrução
  - SQLite3Stmt::bindValue — Vincula o valor de um parâmetro a uma variável de instrução
  - SQLite3Stmt::clear — Limpa todos os parâmetros vinculados atuais
  - SQLite3Stmt::close — Fecha a declaração preparada
  - SQLite3Stmt::__construct — Constrói um objeto SQLite3Stmt
  - SQLite3Stmt::execute — Executa uma declaração preparada e retorna um objeto de conjunto de resultados
  - SQLite3Stmt::getSQL — Obtém o SQL da instrução
  - SQLite3Stmt::paramCount — Retorna o número de parâmetros dentro da declaração preparada
  - SQLite3Stmt::readOnly — Retorna se uma declaração é definitivamente somente leitura
  - SQLite3Stmt::reset — Reseta a declaração preparada
- SQLite3Result — A classe SQLite3Result
  - SQLite3Result::columnName — Retorna o nome da enésima coluna
  - SQLite3Result::columnType — Retorna o tipo da enésima coluna
  - SQLite3Result::__construct — Constrói um SQLite3Result
  - SQLite3Result::fetchArray — Obtém uma linha de resultado como um array associativo, numericamente indexado ou ambos
  - SQLite3Result::finalize — Fecha o conjunto de resultados
  - SQLite3Result::numColumns — Retorna o número de colunas no conjunto de resultados
  - SQLite3Result::reset — Reinicia o conjunto de resultados de volta para a primeira linha

# Driver Microsoft SQL Server para PHP

# Introdução

A extensão SQLSRV permite acessar bancos de dados Microsoft SQL Server e SQL Azure. A versão 3.0 do driver suporta o SQL Server, começando com o SQL Server 2005, incluindo o SQL Server 2012 e o SQL Server 2012 LocalDB. (Para mais informações sobre o LocalDB, consulte » Suporte do Driver PHP para SQL Server para LocalDB e » Informações sobre o SQL Server 2012 Express LocalDB.)

A extensão SQLSRV é suportada pela Microsoft e está disponível para download aqui: » http://msdn.microsoft.com/en-us/sqlserver/ff657782.aspx. O SQL Server 2012 LocalDB pode ser baixado aqui: » http://go.microsoft.com/fwlink/?LinkID=237665.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução
- Tipos de Recurso

## Dependências

A extensão SQLSRV pode ser usada nos seguintes sistemas operacionais:

- Windows Vista Service Pack 2 ou posterior
- Windows Server 2008 Service Pack 2 ou posterior
- Windows Server 2008 R2
- Windows 7

A extensão SQLSRV requer que o Microsoft SQL Server 2012 Native Client esteja instalado no mesmo computador que está executando o PHP. Se o Microsoft SQL Server 2012 Native Client ainda não estiver instalado, clique no link apropriado abaixo para baixá-lo:

- » Baixe o pacote x86
- » Baixe o pacote x64

O download do SQLSRV inclui 8 arquivos de driver, quatro dos quais são para suporte PDO.

A versão mais recente do driver está disponível para download aqui: » Download do SQLSRV.

Para obter mais informações sobre os requisitos do SQLSRV, consulte » Requisitos do Sistema do SQLSRV.

## Instalação

A extensão SQLSRV é habilitada adicionando o arquivo DLL apropriado ao diretório de extensões do seu PHP e a entrada correspondente ao arquivo php.ini. O download do SQLSRV vem com 8 arquivos de driver, sendo quatro deles para suporte PDO.

A versão mais recente do driver está disponível para download aqui: » Download do SQLSRV.

Para obter mais informações sobre os requisitos do SQLSRV, consulte » Requisitos do Sistema SQLSRV.

Desde a versão 4.0, a extensão SQLSRV é compatível apenas com o PHP 7.0 em execução no Linux ou Windows.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

A tabela a seguir lista as opções de configuração disponíveis na extensão SQLSRV. Para obter mais informações sobre essas opções, consulte » Tratamento de Avisos e Erros do SQLSRV.

Opções de Configuração de SQLSRV
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
sqlsrv.WarningsReturnAsErrors | 1 (`true`) | `INI_ALL` | Disponível desde o SQLSRV 1.0
sqlsrv.LogSubsystems | 0 | `INI_ALL` | Disponível desde o SQLSRV 1.0
sqlsrv.LogSeverity | 1 | `INI_ALL` | Disponível desde o SQLSRV 1.0

## Tipos de Recurso

## Recurso de Conexão

Um recurso de conexão retornado por sqlsrv_connect().

## Recurso de Declaração

Um recurso de declaração retornado por sqlsrv_query() ou por sqlsrv_prepare().

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`SQLSRV_FETCH_ASSOC` (int)
  Força sqlsrv_fetch_array() a retornar um array associativo quando passado como parâmetro.
`SQLSRV_FETCH_NUMERIC` (int)
  Força sqlsrv_fetch_array() a retornar um array numérico quando passado como parâmetro.
`SQLSRV_FETCH_BOTH` (int)
  Força sqlsrv_fetch_array() a retornar um array com chaves associativas e numéricas quando passado como parâmetro (comportamento padrão).
`SQLSRV_ERR_ALL` (int)
  Força sqlsrv_errors() a retornar tanto erros quanto avisos quando passado como parâmetro (comportamento padrão).
`SQLSRV_ERR_ERRORS` (int)
  Força sqlsrv_errors() a retornar apenas erros (sem avisos) quando passado como parâmetro.
`SQLSRV_ERR_WARNINGS` (int)
  Força sqlsrv_errors() a retornar apenas avisos (sem erros) quando passado como parâmetro.
`SQLSRV_LOG_SYSTEM_ALL` (int)
  Ativa o registro de todos os subsistemas quando passado para sqlsrv_configure() como parâmetro.
`SQLSRV_LOG_SYSTEM_CONN` (int)
  Ativa o registro da atividade de conexão quando passado para sqlsrv_configure() como parâmetro.
`SQLSRV_LOG_SYSTEM_INIT` (int)
  Ativa o registro da atividade de inicialização quando passado para sqlsrv_configure() como parâmetro.
`SQLSRV_LOG_SYSTEM_OFF` (int)
  Desativa o registro de todos os subsistemas quando passado para sqlsrv_configure() como parâmetro.
`SQLSRV_LOG_SYSTEM_STMT` (int)
  Ativa o registro da atividade de declarações quando passado para sqlsrv_configure() como parâmetro.
`SQLSRV_LOG_SYSTEM_UTIL` (int)
  Ativa o registro da atividade da função de erro quando passado para sqlsrv_configure() como parâmetro.
`SQLSRV_LOG_SEVERITY_ALL` (int)
  Especifica que erros, avisos e notas serão registrados quando passado para sqlsrv_configure() como parâmetro.
`SQLSRV_LOG_SEVERITY_ERROR` (int)
  Especifica que apenas erros serão registrados quando passado para sqlsrv_configure() como parâmetro.
`SQLSRV_LOG_SEVERITY_NOTICE` (int)
  Especifica que as notificações serão registradas ao serem passadas para sqlsrv_configure() como parâmetro.
`SQLSRV_LOG_SEVERITY_WARNING` (int)
  Especifica que os avisos serão registrados ao serem passados para sqlsrv_configure() como parâmetro.
`SQLSRV_NULLABLE_YES` (int)
  Indica que uma coluna é nula.
`SQLSRV_NULLABLE_NO` (int)
  Indica que uma coluna não é nula.
`SQLSRV_NULLABLE_UNKNOWN` (int)
  Indica que não se sabe se uma coluna é nula.
`SQLSRV_PARAM_IN` (int)
  Indica um parâmetro de entrada ao ser passado para sqlsrv_query() ou sqlsrv_prepare().
`SQLSRV_PARAM_INOUT` (int)
  Indica um parâmetro bidirecional ao ser passado para sqlsrv_query() ou sqlsrv_prepare().
`SQLSRV_PARAM_OUT` (int)
  Indica um parâmetro de saída ao ser passado para sqlsrv_query() ou sqlsrv_prepare().
`SQLSRV_PHPTYPE_INT` (int)
  Especifica um tipo de dados inteiro PHP. Para informações de uso, consulte » Como: Especificar Tipos PHP.
`SQLSRV_PHPTYPE_DATETIME` (int)
  Especifica um tipo de dados de data e hora PHP. Para informações de uso, consulte » Como: Especificar Tipos PHP.
`SQLSRV_PHPTYPE_FLOAT` (int)
  Especifica um tipo de dados de ponto flutuante PHP. Para informações de uso, consulte » Como: Especificar Tipos PHP.
`SQLSRV_PHPTYPE_STREAM` (int)
  Especifica um fluxo PHP. Esta constante funciona como uma função e aceita uma constante de codificação. Consulte as constantes SQLSRV_ENC_*. Para informações de uso, consulte » Como: Especificar Tipos PHP.
`SQLSRV_PHPTYPE_STRING` (int)
  Especifica um tipo de dados de string PHP. Esta constante funciona como uma função e aceita uma constante de codificação. Consulte as constantes SQLSRV_ENC_*. Para informações de uso, consulte » Como: Especificar Tipos PHP.
`SQLSRV_ENC_BINARY` (int)
  Especifica que os dados são retornados como um fluxo de bytes bruto do servidor sem realizar codificação ou tradução. Para informações de uso, consulte » Como: Especificar Tipos PHP.
`SQLSRV_ENC_CHAR` (int)
  Os dados são retornados em caracteres de 8 bits conforme especificado na página de código da localidade do Windows que está configurada no sistema. Qualquer caractere multibyte ou caracteres que não sejam mapeados nesta página de código são substituídos por um caractere de ponto de interrogação (?) de um byte. Esta é a codificação padrão. Para informações de uso, consulte » Como: Especificar Tipos PHP.
`SQLSRV_SQLTYPE_BIGINT` (int)
  Descreve o tipo de dados bigint do SQL Server. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_BINARY` (int)
  Descreve o tipo de dados binary do SQL Server. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_BIT` (int)
  Descreve o tipo de dados bit do SQL Server. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_CHAR` (int)
  Descreve o tipo de dados char do SQL Server. Esta constante funciona como uma função e aceita um parâmetro indicando o número de caracteres. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_DATE` (int)
  Descreve o tipo de dados date do SQL Server. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_DATETIME` (int)
  Descreve o tipo de dados datetime do SQL Server. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_DATETIME2` (int)
  Descreve o tipo de dados datetime2 do SQL Server. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_DATETIMEOFFSET` (int)
  Descreve o tipo de dados datetimeoffset do SQL Server. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_DECIMAL` (int)
  Descreve o tipo de dados decimal do SQL Server. Esta constante funciona como uma função e aceita dois parâmetros indicando (na ordem) precisão e escala. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_FLOAT` (int)
  Descreve o tipo de dados float do SQL Server. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_IMAGE` (int)
  Descreve o tipo de dados image do SQL Server. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_INT` (int)
  Descreve o tipo de dados int do SQL Server. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_MONEY` (int)
  Descreve o tipo de dados money do SQL Server. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_NCHAR` (int)
  Descreve o tipo de dados nchar do SQL Server. Esta constante funciona como uma função e aceita um único parâmetro indicando a contagem de caracteres. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_NUMERIC` (int)
  Descreve o tipo de dados numeric do SQL Server. Esta constante funciona como uma função e aceita dois parâmetros indicando (na ordem) precisão e escala. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_NVARCHAR` (int)
  Descreve o tipo de dados nvarchar do SQL Server. Esta constante funciona como uma função e aceita um único parâmetro indicando a contagem de caracteres. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_NVARCHAR`('max') (int)
  Descreve o tipo de dados nvarchar(MAX) do SQL Server. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_NTEXT` (int)
  Descreve o tipo de dados ntext do SQL Server. Para informações de uso, consulte » Como Especificar Tipos SQL.
`SQLSRV_SQLTYPE_REAL` (int)
  Descreve o tipo de dados real do SQL Server. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_SMALLDATETIME` (int)
  Descreve o tipo de dados smalldatetime do SQL Server. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_SMALLINT` (int)
  Descreve o tipo de dados smallint do SQL Server. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_SMALLMONEY` (int)
  Descreve o tipo de dados smallmoney do SQL Server. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_TEXT` (int)
  Descreve o tipo de dados text do SQL Server. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_TIME` (int)
  Descreve o tipo de dados time do SQL Server. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_TIMESTAMP` (int)
  Descreve o tipo de dados timestamp do SQL Server. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_TINYINT` (int)
  Descreve o tipo de dados tinyint do SQL Server. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_UNIQUEIDENTIFIER` (int)
  Descreve o tipo de dados uniqueidentifier do SQL Server. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_UDT` (int)
  Descreve o tipo de dados UDT do SQL Server. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_VARBINARY` (int)
  Descreve o tipo de dados varbinary do SQL Server. Esta constante funciona como uma função e aceita um único parâmetro indicando a contagem de bytes. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_VARBINARY`('max') (int)
  Descreve o tipo de dados varbinary(MAX) do SQL Server. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_VARCHAR` (int)
  Descreve o tipo de dados varchar do SQL Server. Esta constante funciona como uma função e aceita um único parâmetro indicando a contagem de caracteres. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_VARCHAR`('max') (int)
  Descreve o tipo de dados varchar(MAX) do SQL Server. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_SQLTYPE_XML` (int)
  Descreve o tipo de dados XML do SQL Server. Para informações de uso, consulte » Como: Especificar Tipos SQL.
`SQLSRV_TXN_READ_UNCOMMITTED` (int)
  Indica um nível de isolamento de transação de LEITURA NÃO COMPROMETIDA. Este valor é usado para definir o nível de TransactionIsolation no array $connectionOptions passado para sqlsrv_connect().
`SQLSRV_TXN_READ_COMMITTED` (int)
  Indica um nível de isolamento de transação de LEITURA COMPROMETIDA. Este valor é usado para definir o nível de TransactionIsolation no array $connectionOptions passado para sqlsrv_connect().
`SQLSRV_TXN_REPEATABLE_READ` (int)
  Indica um nível de isolamento de transação de LEITURA REPETÍVEL. Este valor é usado para definir o nível de TransactionIsolation no array $connectionOptions passado para sqlsrv_connect().
`SQLSRV_TXN_SNAPSHOT` (int)
  Indica um nível de isolamento de transação de SNAPSHOT. Este valor é usado para definir o nível de TransactionIsolation no array $connectionOptions passado para sqlsrv_connect().
`SQLSRV_TXN_READ_SERIALIZABLE` (int)
  Indica um nível de isolamento de transação de SERIALIZÁVEL. Este valor é usado para definir o nível de TransactionIsolation no array $connectionOptions passado para sqlsrv_connect().
`SQLSRV_CURSOR_FORWARD` (int)
  Indica um cursor somente para frente. Para informações de uso, consulte » Especificando um Tipo de Cursor e Selecionando Linhas.
`SQLSRV_CURSOR_STATIC` (int)
  Indica um cursor estático. Para informações de uso, consulte » Especificando um Tipo de Cursor e Selecionando Linhas.
`SQLSRV_CURSOR_DYNAMIC` (int)
  Indica um cursor dinâmico. Para informações de uso, consulte » Especificando um Tipo de Cursor e Selecionando Linhas.
`SQLSRV_CURSOR_KEYSET` (int)
  Indica um cursor de conjunto de chaves. Para informações de uso, consulte » Especificando um Tipo de Cursor e Selecionando Linhas.
`SQLSRV_CURSOR_BUFFERED` (int)
  Cria uma consulta de cursor do lado do cliente. Permite que você acesse linhas em qualquer ordem. Para informações de uso, consulte » Especificando um Tipo de Cursor e Selecionando Linhas.
`SQLSRV_SCROLL_NEXT` (int)
  Especifica qual linha selecionar em um conjunto de resultados. Para informações de uso, consulte » Especificando um Tipo de Cursor e Selecionando Linhas.
`SQLSRV_SCROLL_PRIOR` (int)
  Especifica qual linha selecionar em um conjunto de resultados. Para informações de uso, consulte » Especificando um Tipo de Cursor e Selecionando Linhas.
`SQLSRV_SCROLL_FIRST` (int)
  Especifica qual linha selecionar em um conjunto de resultados. Para informações de uso, consulte » Especificando um Tipo de Cursor e Selecionando Linhas.
`SQLSRV_SCROLL_LAST` (int)
  Especifica qual linha selecionar em um conjunto de resultados. Para informações de uso, consulte » Especificando um Tipo de Cursor e Selecionando Linhas.
`SQLSRV_SCROLL_ABSOLUTE` (int)
  Especifica qual linha selecionar em um conjunto de resultados. Para informações de uso, consulte » Especificando um Tipo de Cursor e Selecionando Linhas.
`SQLSRV_SCROLL_RELATIVE` (int)
  Especifica qual linha selecionar em um conjunto de resultados. Para informações de uso, consulte » Especificando um Tipo de Cursor e Selecionando Linhas.

# Funções SQLSRV

# sqlsrv_begin_transaction

(No version information available, might only be in Git)

sqlsrv_begin_transaction — Inicia uma transação de banco de dados

### Descrição

function sqlsrv_begin_transaction(resource `$conn`): bool

A transação iniciada por sqlsrv_begin_transaction() inclui todas as instruções que foram executadas após a chamada para sqlsrv_begin_transaction() e antes das chamadas para sqlsrv_rollback() ou sqlsrv_commit(). Transações explícitas devem ser iniciadas e confirmadas ou revertidas usando essas funções em vez de executar instruções SQL que iniciam e confirmam/revertem transações. Para mais informações, consulte » Transações SQLSRV.

### Parâmetros

`conn`
  O recurso de conexão retornado por uma chamada para sqlsrv_connect().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de sqlsrv_begin_transaction()

O seguinte exemplo demonstra como usar sqlsrv_begin_transaction() junto com sqlsrv_commit() e sqlsrv_rollback().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true ));
    }

    /* Inicia a transação. */
    if ( sqlsrv_begin_transaction( $conn ) === false ) {
         die( print_r( sqlsrv_errors(), true ));
    }

    /* Inicializa os valores dos parâmetros. */
    $orderId = 1; $qty = 10; $productId = 100;

    /* Configura e executa a primeira consulta. */
    $sql1 = "INSERT INTO OrdersTable (ID, Quantity, ProductID)
              VALUES (?, ?, ?)";
    $params1 = array( $orderId, $qty, $productId );
    $stmt1 = sqlsrv_query( $conn, $sql1, $params1 );

    /* Configura e executa a segunda consulta. */
    $sql2 = "UPDATE InventoryTable
              SET Quantity = (Quantity - ?)
              WHERE ProductID = ?";
    $params2 = array($qty, $productId);
    $stmt2 = sqlsrv_query( $conn, $sql2, $params2 );

    /* Se ambas as consultas forem bem-sucedidas, confirma a transação. */
    /* Caso contrário, reverte a transação. */
    if( $stmt1 && $stmt2 ) {
         sqlsrv_commit( $conn );
         echo "Transaction committed.<br />";
    } else {
         sqlsrv_rollback( $conn );
         echo "Transaction rolled back.<br />";
    }
    ?>

O exemplo acima produzirá algo semelhante a:

### Veja Também

- sqlsrv_commit() - Confirma uma transação que foi iniciada com sqlsrv_begin_transaction
- sqlsrv_rollback() - Reverte uma transação que foi iniciada com sqlsrv_begin_transaction

# sqlsrv_cancel

(No version information available, might only be in Git)

sqlsrv_cancel — Cancela uma declaração

### Descrição

function sqlsrv_cancel(resource `$stmt`): bool

Cancela uma declaração. Quaisquer resultados associados à declaração que não tenham sido consumidos são excluídos. Depois que sqlsrv_cancel() for chamado, a declaração especificada pode ser reexecutada se tiver sido criada com sqlsrv_prepare(). Chamar sqlsrv_cancel() não é necessário se todos os resultados associados à declaração tiverem sido consumidos.

### Parâmetros

`stmt`
  O recurso de declaração a ser cancelado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de sqlsrv_cancel()

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array("Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect($serverName, $connectionInfo);
    if ($conn === false) {
         die(print_r(sqlsrv_errors(), true));
    }

    $sql = "SELECT Sales FROM Table_1";

    $stmt = sqlsrv_prepare($conn, $sql);

    if ($stmt === false) {
         die(print_r(sqlsrv_errors(), true));
    }

    if (sqlsrv_execute($stmt) === false) {
         die(print_r(sqlsrv_errors(), true));
    }

    $salesTotal = 0;
    $count = 0;

    while (($row = sqlsrv_fetch_array($stmt)) && $salesTotal <=100000)
    {
         $qty = $row[0];
         $price = $row[1];
         $salesTotal += ($price * $qty);
         $count++;
    }

    echo "$count sales accounted for the first $$salesTotal in revenue.<br />";

    // Cancela os resultados pendentes. A declaração pode ser reutilizada.
    sqlsrv_cancel($stmt);
    ?>

### Notas

A principal diferença entre sqlsrv_cancel() e sqlsrv_free_stmt() é que um recurso de declaração cancelado com sqlsrv_cancel() pode ser reexecutado se tiver sido criado com sqlsrv_prepare(). Um recurso de declaração cancelado com sqlsrv_free_statement() não pode ser reexecutado.

### Veja Também

- sqlsrv_free_stmt() - Libera todos os recursos para a declaração especificada
- sqlsrv_prepare() - Prepara uma consulta para execução

# sqlsrv_client_info

(No version information available, might only be in Git)

sqlsrv_client_info — Retorna informações sobre o cliente e a conexão especificada

### Descrição

function sqlsrv_client_info(resource `$conn`): array

Retorna informações sobre o cliente e a conexão especificada

### Parâmetros

`conn`
  A conexão sobre a qual as informações são retornadas.

### Valor Retornado

Retorna um array associativo com chaves descritas na tabela abaixo. Retorna `false` caso contrário.

Array retornado por sqlsrv_client_info
Chave | Descrição
--- | ---
DriverDllName | SQLNCLI10.DLL
DriverODBCVer | Versão ODBC (xx.yy)
DriverVer | Versão do DLL do SQL Server Native Client (10.5.xxx)
ExtensionVer | Versão do php_sqlsrv.dll (2.0.xxx.x)

### Exemplos

Exemplo #1 Exemplo de sqlsrv_client_info()

    <?php
    $serverName = "serverName\sqlexpress";
    $connOptions = array("UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connOptions );

    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true));
    }

    if( $client_info = sqlsrv_client_info( $conn)) {
        foreach( $client_info as $key => $value) {
            echo $key.": ".$value."<br />";
        }
    } else {
        echo "Error in retrieving client info.<br />";
    }
    ?>

### Veja Também

- sqlsrv_server_info() - Retorna informações sobre o servidor

# sqlsrv_close

(No version information available, might only be in Git)

sqlsrv_close — Fecha uma conexão aberta e libera os recursos associados à conexão

### Descrição

function sqlsrv_close(resource `$conn`): bool

Fecha uma conexão aberta e libera os recursos associados à conexão.

### Parâmetros

`conn`
  A conexão a ser fechada.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de sqlsrv_close()

    <?php
    $serverName = "serverName\sqlexpres";
    $connOptions = array("UID"=>"username", "PWD"=>"password", "Database"=>"dbname");
    $conn = sqlsrv_connect( $serverName, $connOptions );
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    //-------------------------------------
    // Execute operações de banco de dados aqui.
    //-------------------------------------

    // Fecha a conexão.
    sqlsrv_close( $conn );
    ?>

### Veja Também

- sqlsrv_connect() - Abre uma conexão com um banco de dados Microsoft SQL Server

# sqlsrv_commit

(No version information available, might only be in Git)

sqlsrv_commit — Confirma uma transação que foi iniciada com sqlsrv_begin_transaction()

### Descrição

function sqlsrv_commit(resource `$conn`): bool

Confirma uma transação que foi iniciada com sqlsrv_begin_transaction(). A conexão é retornada ao modo de auto-commit após a chamada de sqlsrv_commit(). A transação que é confirmada inclui todas as declarações que foram executadas após a chamada para sqlsrv_begin_transaction(). Transações explícitas devem ser iniciadas e confirmadas ou revertidas usando essas funções em vez de executar declarações SQL que iniciam e confirmam/revertem transações. Para mais informações, consulte » Transações SQLSRV.

### Parâmetros

`conn`
  A conexão na qual a transação será confirmada.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de sqlsrv_commit()

O exemplo a seguir demonstra como usar sqlsrv_commit() juntamente com sqlsrv_begin_transaction() e sqlsrv_rollback().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true ));
    }

    /* Inicia a transação. */
    if ( sqlsrv_begin_transaction( $conn ) === false ) {
         die( print_r( sqlsrv_errors(), true ));
    }

    /* Inicializa os valores dos parâmetros. */
    $orderId = 1; $qty = 10; $productId = 100;

    /* Configura e executa a primeira consulta. */
    $sql1 = "INSERT INTO OrdersTable (ID, Quantity, ProductID)
             VALUES (?, ?, ?)";
    $params1 = array( $orderId, $qty, $productId );
    $stmt1 = sqlsrv_query( $conn, $sql1, $params1 );

    /* Configura e executa a segunda consulta. */
    $sql2 = "UPDATE InventoryTable
             SET Quantity = (Quantity - ?)
             WHERE ProductID = ?";
    $params2 = array($qty, $productId);
    $stmt2 = sqlsrv_query( $conn, $sql2, $params2 );

    /* Se ambas as consultas forem bem-sucedidas, confirma a transação. */
    /* Caso contrário, reverte a transação. */
    if( $stmt1 && $stmt2 ) {
         sqlsrv_commit( $conn );
         echo "Transaction committed.<br />";
    } else {
         sqlsrv_rollback( $conn );
         echo "Transaction rolled back.<br />";
    }
    ?>

### Veja Também

- sqlsrv_begin_transaction() - Inicia uma transação de banco de dados
- sqlsrv_rollback() - Reverte uma transação que foi iniciada com sqlsrv_begin_transaction

# sqlsrv_configure

(No version information available, might only be in Git)

sqlsrv_configure — Altera as configurações de tratamento de erros e registro do driver

### Descrição

function sqlsrv_configure(string `$setting`, mixed `$value`): bool

Altera as configurações de tratamento de erros e registro do driver.

### Parâmetros

`setting`
  O nome da configuração a ser definida. Os valores possíveis são "WarningsReturnAsErrors", "LogSubsystems" e "LogSeverity".
`value`

  O valor da configuração especificada. A tabela a seguir mostra os valores possíveis:

  Opções de Configuração de Erro e Registro
  Configuração | Opções
  --- | ---
  WarningsReturnAsErrors | 1 (`true`) ou 0 (`false`)
  LogSubsystems | SQLSRV_LOG_SYSTEM_ALL (-1) SQLSRV_LOG_SYSTEM_CONN (2) SQLSRV_LOG_SYSTEM_INIT (1) SQLSRV_LOG_SYSTEM_OFF (0) SQLSRV_LOG_SYSTEM_STMT (4) SQLSRV_LOG_SYSTEM_UTIL (8)
  LogSeverity | SQLSRV_LOG_SEVERITY_ALL (-1) SQLSRV_LOG_SEVERITY_ERROR (1) SQLSRV_LOG_SEVERITY_NOTICE (4) SQLSRV_LOG_SEVERITY_WARNING (2)

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- » SQLSRV Error Handling.
- » Logging SQLSRV Activity.

# sqlsrv_connect

(No version information available, might only be in Git)

sqlsrv_connect — Abre uma conexão com um banco de dados Microsoft SQL Server

### Descrição

function sqlsrv_connect(string `$serverName`, array `$connectionInfo` = ?): resource

Abre uma conexão com um banco de dados Microsoft SQL Server. Por padrão, a conexão é tentada usando a Autenticação do Windows. Para conectar usando Autenticação do SQL Server, inclua "UID" e "PWD" no array de opções de conexão.

### Parâmetros

`serverName`
  O nome do servidor ao qual uma conexão é estabelecida. Para conectar a uma instância específica, siga o nome do servidor com uma barra invertida e o nome da instância (por exemplo, serverName\sqlexpress).
`connectionInfo`
  Um array associativo que especifica opções para conectar ao servidor. Se os valores para as chaves UID e PWD não forem especificados, a conexão será tentada usando a Autenticação do Windows. Para uma lista completa de chaves suportadas, consulte » Opções de Conexão SQLSRV.

### Valor Retornado

Um recurso de conexão. Se uma conexão não puder ser aberta com sucesso, `false` é retornado.

### Exemplos

Exemplo #1 Conectar usando Autenticação do Windows.

    <?php
    $serverName = "serverName\\sqlexpress"; //serverName\instanceName

    // Como UID e PWD não são especificados no array $connectionInfo,
    // A conexão será tentada usando a Autenticação do Windows.
    $connectionInfo = array( "Database"=>"dbName");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);

    if( $conn ) {
         echo "Connection established.<br />";
    }else{
         echo "Connection could not be established.<br />";
         die( print_r( sqlsrv_errors(), true));
    }
    ?>

Exemplo #2 Conectar especificando um nome de usuário e senha.

    <?php
    $serverName = "serverName\\sqlexpress"; //serverName\instanceName
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);

    if( $conn ) {
         echo "Connection established.<br />";
    }else{
         echo "Connection could not be established.<br />";
         die( print_r( sqlsrv_errors(), true));
    }
    ?>

Exemplo #3 Conectar em uma porta específica

    <?php
    $serverName = "serverName\\sqlexpress, 1542"; // nomeServidor\nomeInstancia, numeroPorta (padrão é 1433)
    $connectionInfo = array("Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect($serverName, $connectionInfo);

    if( $conn ) {
         echo "Conexão estabelecida.<br />";
    }else{
         echo "Conexão não pôde ser estabelecida.<br />";
         die(print_r(sqlsrv_errors(), true));
    }
    ?>

### Notas

Por padrão, o sqlsrv_connect() usa pooling de conexão para melhorar o desempenho da conexão. Para desativar o pooling de conexão (ou seja, forçar uma nova conexão em cada chamada), defina a opção "ConnectionPooling" no array $connectionOptions para 0 (ou `false`). Para mais informações, consulte » Pooling de Conexão SQLSRV.

A extensão SQLSRV não possui uma função dedicada para alterar qual banco de dados está conectado. O banco de dados de destino é especificado no array $connectionOptions que é passado para sqlsrv_connect. Para alterar o banco de dados em uma conexão aberta, execute a seguinte consulta "USE dbName" (por exemplo, sqlsrv_query($conn, "USE dbName")).

### Veja Também

- sqlsrv_close() - Fecha uma conexão aberta e libera os recursos associados à conexão
- sqlsrv_errors() - Retorna informações de erro e aviso sobre a última operação SQLSRV executada
- sqlsrv_query() - Prepara e executa uma consulta

# sqlsrv_errors

(No version information available, might only be in Git)

sqlsrv_errors — Retorna informações de erro e aviso sobre a última operação SQLSRV executada

### Descrição

function sqlsrv_errors(int `$errorsOrWarnings` = ?): mixed

Retorna informações de erro e aviso sobre a última operação SQLSRV executada.

### Parâmetros

`errorsOrWarnings`
  Determina se informações de erro, aviso ou ambos são retornados. Se este parâmetro não for fornecido, tanto as informações de erro quanto de aviso serão retornadas. Os seguintes são os valores suportados para este parâmetro: SQLSRV_ERR_ALL, SQLSRV_ERR_ERRORS, SQLSRV_ERR_WARNINGS.

### Valor Retornado

Se ocorrerem erros e/ou avisos na última operação sqlsrv, um array de arrays contendo informações de erro é retornado. Se não houver erros e/ou avisos na última operação sqlsrv, é retornado `null`. A tabela a seguir descreve a estrutura dos arrays retornados:

Array retornado por sqlsrv_errors
Chave | Descrição
--- | ---
SQLSTATE | Para erros que se originam do driver ODBC, o SQLSTATE retornado pelo ODBC. Para erros que se originam dos Drivers da Microsoft para PHP para SQL Server, um SQLSTATE de IMSSP. Para avisos que se originam dos Drivers da Microsoft para PHP para SQL Server, um SQLSTATE de 01SSP.
code | Para erros que se originam do SQL Server, o código de erro nativo do SQL Server. Para erros que se originam do driver ODBC, o código de erro retornado pelo ODBC. Para erros que se originam dos Drivers da Microsoft para PHP para SQL Server, o código de erro dos Drivers da Microsoft para PHP para SQL Server.
message | Uma descrição do erro.

### Exemplos

Exemplo #1 Exemplo de functionname()

    <?php
    $serverName = "serverName/sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    /* Configura uma consulta para selecionar um nome de coluna inválido. */
    $sql = "SELECT BadColumnName FROM Table_1";

    /* A execução da consulta falhará devido ao nome da coluna ruim. */
    $stmt = sqlsrv_query( $conn, $sql );
    if( $stmt === false ) {
        if( ($errors = sqlsrv_errors() ) != null) {
            foreach( $errors as $error ) {
                echo "SQLSTATE: ".$error[ 'SQLSTATE']."<br />";
                echo "code: ".$error[ 'code']."<br />";
                echo "message: ".$error[ 'message']."<br />";
            }
        }
    }
    ?>

### Notas

Por padrão, avisos gerados em uma chamada a qualquer função SQLSRV são tratados como erros. Isso significa que se um aviso ocorrer em uma chamada para uma função SQLSRV, a função retorna `false`. No entanto, avisos que correspondem a valores SQLSTATE 01000, 01001, 01003 e 01S02 nunca são tratados como erros. Para informações sobre como alterar esse comportamento, consulte sqlsrv_configure() e a configuração WarningsReturnAsErrors.

### Veja Também

- sqlsrv_configure() - Altera as configurações de tratamento de erros e registro do driver

# sqlsrv_execute

(No version information available, might only be in Git)

sqlsrv_execute — Executa uma declaração preparada com sqlsrv_prepare()

### Descrição

function sqlsrv_execute(resource `$stmt`): bool

Executa uma declaração preparada com sqlsrv_prepare(). Esta função é ideal para executar uma declaração preparada várias vezes com diferentes valores de parâmetro.

### Parâmetros

`stmt`
  Um recurso de declaração retornado por sqlsrv_prepare().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de sqlsrv_execute()

Este exemplo demonstra como preparar uma declaração com sqlsrv_prepare() e reexecutá-la várias vezes (com diferentes valores de parâmetro) usando sqlsrv_execute().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false) {
        die( print_r( sqlsrv_errors(), true));
    }

    $sql = "UPDATE Table_1
            SET OrderQty = ?
            WHERE SalesOrderID = ?";

    // Inicializa parâmetros e prepara a declaração.
    // Variáveis $qty e $id estão vinculadas à declaração, $stmt.
    $qty = 0; $id = 0;
    $stmt = sqlsrv_prepare( $conn, $sql, array( &$qty, &$id));
    if( !$stmt ) {
        die( print_r( sqlsrv_errors(), true));
    }

    // Configura as informações SalesOrderDetailID e OrderQty.
    // Este array mapeia o ID do pedido para a quantidade do pedido em pares chave=>valor.
    $orders = array( 1=>10, 2=>20, 3=>30);

    // Executa a declaração para cada pedido.
    foreach( $orders as $id => $qty) {
        // Porque $id e $qty estão vinculados a $stmt1, seus valores atualizados
        // são usados com cada execução da declaração.
        if( sqlsrv_execute( $stmt ) === false ) {
              die( print_r( sqlsrv_errors(), true));
        }
    }
    ?>

### Notas

Quando você prepara uma declaração que usa variáveis como parâmetros, as variáveis são vinculadas à declaração. Isso significa que se você atualizar os valores das variáveis, na próxima vez que executar a declaração, ela será executada com valores de parâmetro atualizados. Para declarações que você planeja executar apenas uma vez, use sqlsrv_query().

### Veja Também

- sqlsrv_prepare() - Prepara uma consulta para execução
- sqlsrv_query() - Prepara e executa uma consulta

# sqlsrv_fetch

(No version information available, might only be in Git)

sqlsrv_fetch — Torna a próxima linha em um conjunto de resultados disponível para leitura

### Descrição

function sqlsrv_fetch(resource `$stmt`, int `$row` = ?, int `$offset` = ?): mixed

Torna a próxima linha em um conjunto de resultados disponível para leitura. Use sqlsrv_get_field() para ler os campos da linha.

### Parâmetros

`stmt`
  Um recurso de declaração criado executando sqlsrv_query() ou sqlsrv_execute().
`row`

  A linha a ser acessada. Este parâmetro só pode ser usado se a declaração especificada foi preparada com um cursor rolável. Nesse caso, esse parâmetro pode assumir um dos seguintes valores:

  - SQLSRV_SCROLL_NEXT
  - SQLSRV_SCROLL_PRIOR
  - SQLSRV_SCROLL_FIRST
  - SQLSRV_SCROLL_LAST
  - SQLSRV_SCROLL_ABSOLUTE
  - SQLSRV_SCROLL_RELATIVE
`offset`
  Especifica a linha a ser acessada se o parâmetro row for definido como `SQLSRV_SCROLL_ABSOLUTE` ou `SQLSRV_SCROLL_RELATIVE`. Observe que a primeira linha em um conjunto de resultados tem índice 0.

### Valor Retornado

Retorna `true` se a próxima linha de um conjunto de resultados for recuperada com sucesso, `false` se ocorrer um erro e `null` se não houver mais linhas no conjunto de resultados.

### Exemplos

Exemplo #1 Exemplo de sqlsrv_fetch()

O exemplo a seguir demonstra como recuperar uma linha com sqlsrv_fetch() e obter os campos da linha com sqlsrv_get_field().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT Name, Comment
            FROM Table_1
            WHERE ReviewID=1";
    $stmt = sqlsrv_query( $conn, $sql);
    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    // Torna a primeira (e neste caso, única) linha do conjunto de resultados disponível para leitura.
    if( sqlsrv_fetch( $stmt ) === false) {
         die( print_r( sqlsrv_errors(), true));
    }

    // Obter os campos da linha. Os índices dos campos começam em 0 e devem ser recuperados na ordem.
    // A recuperação de campos da linha pelo nome não é suportada por sqlsrv_get_field.
    $name = sqlsrv_get_field( $stmt, 0);
    echo "$name: ";

    $comment = sqlsrv_get_field( $stmt, 1);
    echo $comment;
    ?>

### Veja Também

- sqlsrv_get_field() - Obtém dados do campo da linha atualmente selecionada
- sqlsrv_fetch_array() - Retorna uma linha como um array
- sqlsrv_fetch_object() - Recupera a próxima linha de dados em um conjunto de resultados como um objeto

# sqlsrv_fetch_array

(No version information available, might only be in Git)

sqlsrv_fetch_array — Retorna uma linha como um array

### Descrição

function sqlsrv_fetch_array(
resource `$stmt`,
int `$fetchType` = ?,
int `$row` = ?,
int `$offset` = ?
): array

Retorna a próxima linha disponível de dados como um array associativo, um array numérico ou ambos (o padrão).

### Parâmetros

`stmt`
  Um recurso de declaração retornado por sqlsrv_query ou sqlsrv_prepare.
`fetchType`
  Uma constante predefinida especificando o tipo de array a ser retornado. Valores possíveis são `SQLSRV_FETCH_ASSOC`, `SQLSRV_FETCH_NUMERIC` e `SQLSRV_FETCH_BOTH` (o padrão). Um tipo de busca de SQLSRV_FETCH_ASSOC não deve ser usado ao consumir um conjunto de resultados com várias colunas do mesmo nome.
`row`
  Especifica a linha a ser acessada em um conjunto de resultados que usa um cursor rolável. Os valores possíveis são `SQLSRV_SCROLL_NEXT`, `SQLSRV_SCROLL_PRIOR`, `SQLSRV_SCROLL_FIRST`, `SQLSRV_SCROLL_LAST`, `SQLSRV_SCROLL_ABSOLUTE` e, `SQLSRV_SCROLL_RELATIVE` (o padrão). Quando este parâmetro é especificado, o `fetchType` deve ser definido explicitamente.
`offset`
  Especifica a linha a ser acessada se o parâmetro row for definido como `SQLSRV_SCROLL_ABSOLUTE` ou `SQLSRV_SCROLL_RELATIVE`. Observe que a primeira linha em um conjunto de resultados tem índice 0.

### Valor Retornado

Retorna um array em caso de sucesso, `null` se não houver mais linhas para retornar, e `false` se ocorrer um erro.

### Exemplos

Exemplo #1 Recuperando um array associativo.

    <?php
    $serverName = "serverName\instanceName";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo );
    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT FirstName, LastName FROM SomeTable";
    $stmt = sqlsrv_query( $conn, $sql );
    if( $stmt === false) {
        die( print_r( sqlsrv_errors(), true) );
    }

    while( $row = sqlsrv_fetch_array( $stmt, SQLSRV_FETCH_ASSOC) ) {
          echo $row['LastName'].", ".$row['FirstName']."<br />";
    }

    sqlsrv_free_stmt( $stmt);
    ?>

Exemplo #2 Recuperando um array numérico.

    <?php
    $serverName = "serverName\instanceName";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo );
    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT FirstName, LastName FROM SomeTable";
    $stmt = sqlsrv_query( $conn, $sql );
    if( $stmt === false) {
        die( print_r( sqlsrv_errors(), true) );
    }

    while( $row = sqlsrv_fetch_array( $stmt, SQLSRV_FETCH_NUMERIC) ) {
          echo $row[0].", ".$row[1]."<br />";
    }

    sqlsrv_free_stmt( $stmt);
    ?>

### Notas

Não especificar o `fetchType` ou usar explicitamente o `SQLSRV_FETCH_TYPE` constante nos exemplos acima retornará um array que possui chaves associativas e numéricas.

Se mais de uma coluna for retornada com o mesmo nome, a última coluna terá precedência. Para evitar colisões de nomes de campo, use aliases.

Se uma coluna sem nome for retornada, a chave associativa para o elemento do array será uma string vazia ("").

### Veja Também

- sqlsrv_connect() - Abre uma conexão com um banco de dados Microsoft SQL Server
- sqlsrv_query() - Prepara e executa uma consulta
- sqlsrv_errors() - Retorna informações de erro e aviso sobre a última operação SQLSRV executada
- sqlsrv_fetch() - Torna a próxima linha em um conjunto de resultados disponível para leitura

# sqlsrv_fetch_object

(No version information available, might only be in Git)

sqlsrv_fetch_object — Recupera a próxima linha de dados em um conjunto de resultados como um objeto

### Descrição

function sqlsrv_fetch_object(
resource `$stmt`,
string `$className` = ?,
array `$ctorParams` = ?,
int `$row` = ?,
int `$offset` = ?
): mixed

Recupera a próxima linha de dados em um conjunto de resultados como uma instância da classe especificada com propriedades que correspondem aos nomes dos campos da linha e valores que correspondem aos valores dos campos da linha.

### Parâmetros

`stmt`
  Um recurso de declaração criado por sqlsrv_query() ou sqlsrv_execute().
`className`
  O nome da classe a ser instanciada. Se nenhum nome de classe for especificado, stdClass é instanciado.
`ctorParams`
  Valores passados para o construtor da classe especificada. Se o construtor da classe especificada aceitar parâmetros, o array ctorParams deve ser fornecido.
`row`

  A linha a ser acessada. Este parâmetro só pode ser usado se a declaração especificada foi preparada com um cursor rolável. Nesse caso, esse parâmetro pode assumir um dos seguintes valores:

  - SQLSRV_SCROLL_NEXT
  - SQLSRV_SCROLL_PRIOR
  - SQLSRV_SCROLL_FIRST
  - SQLSRV_SCROLL_LAST
  - SQLSRV_SCROLL_ABSOLUTE
  - SQLSRV_SCROLL_RELATIVE
`offset`
  Especifica a linha a ser acessada se o parâmetro row for definido como `SQLSRV_SCROLL_ABSOLUTE` ou `SQLSRV_SCROLL_RELATIVE`. Observe que a primeira linha em um conjunto de resultados tem índice 0.

### Valor Retornado

Retorna um objeto em caso de sucesso, `null` se não houver mais linhas para retornar, e `false` se ocorrer um erro ou se a classe especificada não existir.

### Exemplos

Exemplo #1 Exemplo de sqlsrv_fetch_object()

O exemplo a seguir demonstra como recuperar uma linha como um objeto stdClass.

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT fName, lName FROM Table_1";
    $stmt = sqlsrv_query( $conn, $sql);
    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    // Recupera cada linha como um objeto.
    // Como nenhum nome de classe é especificado, cada linha será recuperada como um objeto stdClass.
    // Os nomes das propriedades correspondem aos nomes dos campos.
    while( $obj = sqlsrv_fetch_object( $stmt)) {
          echo $obj->fName.", ".$obj->lName."<br />";
    }
    ?>

### Notas

Se um nome de classe for especificado com o parâmetro opcional $className e a classe tiver propriedades cujos nomes correspondam aos nomes dos campos do conjunto de resultados, os valores do conjunto de resultados correspondentes são aplicados às propriedades. Se um nome de campo do conjunto de resultados não corresponder a uma propriedade da classe, uma propriedade com o nome do campo do conjunto de resultados é adicionada ao objeto e o valor do conjunto de resultados é aplicado à propriedade. As seguintes regras se aplicam ao usar o parâmetro $className:

- A correspondência entre nome de campo e propriedade é sensível a maiúsculas e minúsculas.
- A correspondência entre nome de campo e propriedade ocorre independentemente dos modificadores de acesso.
- Os tipos de dados da propriedade da classe são ignorados ao aplicar um valor de campo a uma propriedade.
- Se a classe não existir, a função retorna `false` e adiciona um erro à coleção de erros.

Independentemente de o parâmetro $className ser fornecido ou não, se um campo sem nome for retornado, o valor do campo será ignorado e um aviso será adicionado à coleção de erros.

Ao consumir um conjunto de resultados que tenha várias colunas com o mesmo nome, pode ser melhor usar sqlsrv_fetch_array() ou a combinação de sqlsrv_fetch() e sqlsrv_get_field().

### Veja Também

- sqlsrv_fetch() - Torna a próxima linha em um conjunto de resultados disponível para leitura
- sqlsrv_fetch_array() - Retorna uma linha como um array

# sqlsrv_field_metadata

(No version information available, might only be in Git)

sqlsrv_field_metadata — Recupera metadados para os campos de uma declaração preparada por sqlsrv_prepare() ou sqlsrv_query()

### Descrição

function sqlsrv_field_metadata(resource `$stmt`): mixed

Recupera metadados para os campos de uma declaração preparada por sqlsrv_prepare() ou sqlsrv_query(). sqlsrv_field_metadata() pode ser chamado em uma declaração antes ou depois da execução da declaração.

### Parâmetros

`stmt`
  O recurso de declaração para o qual os metadados são retornados.

### Valor Retornado

Retorna um array de arrays em caso de sucesso. Caso contrário, é retornado `false`. Cada array retornado é descrito pela seguinte tabela:

Array retornado por sqlsrv_field_metadata
Chave | Descrição
--- | ---
Name | O nome do campo.
Type | O valor numérico para o tipo SQL.
Size | O número de caracteres para campos de tipo caractere, o número de bytes para campos de tipo binário, ou `null` para outros tipos.
Precision | A precisão para tipos de precisão variável, `null` para outros tipos.
Scale | A escala para tipos de escala variável, `null` para outros tipos.
Nullable | Uma enumeração indicando se a coluna é nula, não nula, ou se não é conhecida.

Para mais informações, consulte » sqlsrv_field_metadata na documentação do Microsoft SQLSRV.

### Exemplos

Exemplo #1 Exemplo de sqlsrv_field_metadata()

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"AdventureWorks", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
       die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT * FROM Table_1";
    $stmt = sqlsrv_prepare( $conn, $sql );

    foreach( sqlsrv_field_metadata( $stmt ) as $fieldMetadata ) {
        foreach( $fieldMetadata as $name => $value) {
           echo "$name: $value<br />";
        }
          echo "<br />";
    }
    ?>

### Veja Também

- sqlsrv_client_info() - Retorna informações sobre o cliente e a conexão especificada

# sqlsrv_free_stmt

(No version information available, might only be in Git)

sqlsrv_free_stmt — Libera todos os recursos para a declaração especificada

### Descrição

function sqlsrv_free_stmt(resource `$stmt`): bool

Libera todos os recursos para a declaração especificada. A declaração não pode ser usada após sqlsrv_free_stmt() ser chamada nela. Se sqlsrv_free_stmt() for chamada em uma declaração em andamento que altera o estado do servidor, a execução da declaração é interrompida e a declaração é revertida.

### Parâmetros

`stmt`
  A declaração para a qual os recursos são liberados. Note que `null` é um valor de parâmetro válido. Isso permite que a função seja chamada várias vezes em um script.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de sqlsrv_free_stmt()

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $stmt = sqlsrv_query( $conn, "SELECT * FROM Table_1");
    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    /*-------------------------------
         Processar os resultados da consulta aqui.
    -------------------------------*/

    /* Libere os recursos da declaração. */
    sqlsrv_free_stmt( $stmt);

    ?>

### Notas

A principal diferença entre sqlsrv_free_stmt() e sqlsrv_cancel() é que um recurso de declaração cancelado com sqlsrv_cancel() pode ser reexecutado se foi criado com sqlsrv_prepare(). Um recurso de declaração cancelado com sqlsrv_free_statement() não pode ser reexecutado.

### Veja Também

- sqlsrv_cancel() - Cancela uma declaração

# sqlsrv_get_config

(No version information available, might only be in Git)

sqlsrv_get_config — Retorna o valor da configuração especificada

### Descrição

function sqlsrv_get_config(string `$setting`): mixed

Retorna o valor da configuração especificada.

### Parâmetros

`setting`
  O nome da configuração para a qual o valor é retornado. Para uma lista de configurações configuráveis, consulte sqlsrv_configure().

### Valor Retornado

Retorna o valor da configuração especificada. Se uma configuração inválida for especificada, `false` é retornado.

### Veja Também

- sqlsrv_configure() - Altera as configurações de tratamento de erros e registro do driver

# sqlsrv_get_field

(No version information available, might only be in Git)

sqlsrv_get_field — Obtém dados do campo da linha atualmente selecionada

### Descrição

function sqlsrv_get_field(resource `$stmt`, int `$fieldIndex`, int `$getAsType` = ?): mixed

Obtém dados do campo da linha atualmente selecionada. Os campos devem ser acessados em ordem. Os índices dos campos começam em 0.

### Parâmetros

`stmt`
  Um recurso de declaração retornado por sqlsrv_query() ou sqlsrv_execute().
`fieldIndex`
  O índice do campo a ser recuperado. Os índices dos campos começam em 0. Os campos devem ser acessados em ordem. Ou seja, se você acessar o índice do campo 1, então o índice do campo 0 não estará disponível.
`getAsType`
  O tipo de dado PHP para os dados do campo retornados. Se este parâmetro não for definido, os dados do campo serão retornados como seu tipo de dados PHP padrão. Para obter informações sobre os tipos de dados PHP padrão, consulte » Tipos de Dados PHP Padrão na documentação do Microsoft SQLSRV.

### Valor Retornado

Retorna os dados do campo especificado com sucesso. Retorna `false` caso contrário.

### Exemplos

Exemplo #1 Exemplo de sqlsrv_get_field()

O exemplo a seguir demonstra como recuperar uma linha com sqlsrv_fetch() e obter os campos da linha com sqlsrv_get_field().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT Name, Comment
            FROM Table_1
            WHERE ReviewID=1";
    $stmt = sqlsrv_query( $conn, $sql);
    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    // Torna a primeira (e neste caso, única) linha do conjunto de resultados disponível para leitura.
    if( sqlsrv_fetch( $stmt ) === false) {
         die( print_r( sqlsrv_errors(), true));
    }

    // Obtém os campos da linha. Os índices de campo começam em 0 e devem ser recuperados em ordem.
    // A recuperação de campos de linha por nome não é suportada por sqlsrv_get_field.
    $name = sqlsrv_get_field( $stmt, 0);
    echo "$name: ";

    $comment = sqlsrv_get_field( $stmt, 1);
    echo $comment;
    ?>

### Veja Também

- sqlsrv_fetch() - Torna a próxima linha em um conjunto de resultados disponível para leitura
- sqlsrv_fetch_array() - Retorna uma linha como um array
- sqlsrv_fetch_object() - Recupera a próxima linha de dados em um conjunto de resultados como um objeto

# sqlsrv_has_rows

(No version information available, might only be in Git)

sqlsrv_has_rows — Indica se a declaração especificada possui linhas

### Descrição

function sqlsrv_has_rows(resource `$stmt`): bool

Indica se a declaração especificada possui linhas.

### Parâmetros

`stmt`
  Um recurso de declaração retornado por sqlsrv_query() ou sqlsrv_execute().

### Valor Retornado

Retorna `true` se a declaração especificada tiver linhas e `false` se a declaração não tiver linhas ou se ocorrer um erro.

### Exemplos

Exemplo #1 Exemplo de sqlsrv_has_rows()

    <?php
    $server = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
    $conn = sqlsrv_connect( $server, $connectionInfo );

    $stmt = sqlsrv_query( $conn, "SELECT * FROM Table_1");

    if ($stmt) {
       $rows = sqlsrv_has_rows( $stmt );
       if ($rows === true)
          echo "There are rows. <br />";
       else
          echo "There are no rows. <br />";
    }
    ?>

### Veja Também

- sqlsrv_num_rows() - Recupera o número de linhas em um conjunto de resultados
- sqlsrv_query() - Prepara e executa uma consulta

# sqlsrv_next_result

(No version information available, might only be in Git)

sqlsrv_next_result — Torna o próximo resultado da declaração especificada ativo

### Descrição

function sqlsrv_next_result(resource `$stmt`): mixed

Torna o próximo resultado da declaração especificada ativo. Os resultados incluem conjuntos de resultados, contagens de linhas e parâmetros de saída.

### Parâmetros

`stmt`
  A declaração na qual o próximo resultado está sendo chamado.

### Valor Retornado

Retorna `true` se o próximo resultado foi obtido com sucesso, `false` se ocorrer um erro e `null` se não houver mais resultados para recuperar.

### Exemplos

Exemplo #1 Exemplo de sqlsrv_next_result()

O exemplo a seguir executa uma consulta em lote que insere em uma tabela e depois seleciona da tabela. Isso produz dois resultados na declaração: um para as linhas afetadas pela INSERT e outro para as linhas retornadas pela SELECT. Para chegar às linhas retornadas pela SELECT, é necessário chamar sqlsrv_next_result() para passar pelo primeiro resultado.

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array("Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);

    $query = "INSERT INTO Table_1 (id, data) VALUES (?,?); SELECT * FROM TABLE_1;";
    $params = array(1, "some data");
    $stmt = sqlsrv_query($conn, $query, $params);

    // Consome o primeiro resultado (linhas afetadas por INSERT) sem chamar sqlsrv_next_result.
    echo "Rows affected: ".sqlsrv_rows_affected($stmt)."<br />";

    // Move para o próximo resultado e exibe os resultados.
    $next_result = sqlsrv_next_result($stmt);
    if( $next_result ) {
       while( $row = sqlsrv_fetch_array( $stmt, SQLSRV_FETCH_ASSOC)){
          echo $row['id'].": ".$row['data']."<br />";
       }
    } elseif( is_null($next_result)) {
         echo "No more results.<br />";
    } else {
         die(print_r(sqlsrv_errors(), true));
    }
    ?>

### Veja Também

- sqlsrv_query() - Prepara e executa uma consulta
- sqlsrv_fetch_array() - Retorna uma linha como um array
- sqlsrv_rows_affected() - Retorna o número de linhas modificadas pela última consulta INSERT, UPDATE ou DELETE executada

# sqlsrv_num_fields

(No version information available, might only be in Git)

sqlsrv_num_fields — Recupera o número de campos (colunas) em uma declaração

### Descrição

function sqlsrv_num_fields(resource `$stmt`): mixed

Recupera o número de campos (colunas) em uma declaração.

### Parâmetros

`stmt`
  A declaração para a qual o número de campos é retornado. sqlsrv_num_fields() pode ser chamado em uma declaração antes ou depois da execução da declaração.

### Valor Retornado

Retorna o número de campos em caso de sucesso. Retorna `false` caso contrário.

### Exemplos

Exemplo #1 Exemplo de sqlsrv_num_fields()

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
       die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT * FROM Table_1";
    $stmt = sqlsrv_query($conn, $sql);
    if( $stmt === false) {
       die( print_r( sqlsrv_errors(), true));
    }

    $numFields = sqlsrv_num_fields( $stmt );

    while( sqlsrv_fetch( $stmt )) {
       // Itere pelos campos de cada linha.
       for($i = 0; $i < $numFields; $i++) {
          echo sqlsrv_get_field($stmt, $i)." ";
       }
       echo "<br />";
    }
    ?>

### Veja Também

- sqlsrv_field_metadata() - Recupera metadados para os campos de uma declaração preparada por sqlsrv_prepare ou sqlsrv_query
- sqlsrv_fetch() - Torna a próxima linha em um conjunto de resultados disponível para leitura
- sqlsrv_get_field() - Obtém dados do campo da linha atualmente selecionada

# sqlsrv_num_rows

(No version information available, might only be in Git)

sqlsrv_num_rows — Recupera o número de linhas em um conjunto de resultados

### Descrição

function sqlsrv_num_rows(resource `$stmt`): mixed

Recupera o número de linhas em um conjunto de resultados. Esta função requer que o recurso de declaração seja criado com um cursor estático ou de conjunto de chaves. Para mais informações, consulte sqlsrv_query(), sqlsrv_prepare() ou » Especificar um Tipo de Cursor e Selecionar Linhas na documentação do Microsoft SQLSRV.

### Parâmetros

`stmt`
  A declaração para a qual a contagem de linhas é retornada. O recurso de declaração deve ser criado com um cursor estático ou de conjunto de chaves. Para mais informações, consulte sqlsrv_query(), sqlsrv_prepare() ou » Especificar um Tipo de Cursor e Selecionar Linhas na documentação do Microsoft SQLSRV.

### Valor Retornado

Retorna o número de linhas recuperadas em caso de sucesso e `false` se ocorrer um erro. Se um cursor avançado (o padrão) ou dinâmico for usado, `false` é retornado.

### Exemplos

Exemplo #1 Exemplo de sqlsrv_num_rows()

    <?php
    $server = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
    $conn = sqlsrv_connect( $server, $connectionInfo );

    $sql = "SELECT * FROM Table_1";
    $params = array();
    $options =  array( "Scrollable" => SQLSRV_CURSOR_KEYSET );
    $stmt = sqlsrv_query( $conn, $sql , $params, $options );

    $row_count = sqlsrv_num_rows( $stmt );

    if ($row_count === false)
       echo "Error in retrieveing row count.";
    else
       echo $row_count;
    ?>

### Veja Também

- sqlsrv_has_rows() - Indica se a declaração especificada possui linhas
- sqlsrv_rows_affected() - Retorna o número de linhas modificadas pela última consulta INSERT, UPDATE ou DELETE executada

# sqlsrv_prepare

(No version information available, might only be in Git)

sqlsrv_prepare — Prepara uma consulta para execução

### Descrição

function sqlsrv_prepare(
resource `$conn`,
string `$sql`,
array `$params` = ?,
array `$options` = ?
): mixed

Prepara uma consulta para execução. Esta função é ideal para preparar uma consulta que será executada várias vezes com diferentes valores de parâmetro.

### Parâmetros

`conn`
  Um recurso de conexão retornado por sqlsrv_connect().
`sql`
  A string que define a consulta a ser preparada e executada.
`params`

  Um array especificando informações de parâmetro ao executar uma consulta parametrizada. Os elementos do array podem ser um dos seguintes:

  - Um valor literal
  - Uma variável PHP
  - Um array com esta estrutura: array($valor [, $direção [, $tipoPHP [, $tipoSQL]]])
  A tabela a seguir descreve os elementos na estrutura do array acima:

  Estrutura do array
  Elemento | Descrição
  --- | ---
  $value | Um valor literal, uma variável PHP ou uma variável PHP por referência.
  $direction (opcional) | Uma das constantes SQLSRV usadas para indicar a direção do parâmetro: SQLSRV_PARAM_IN, SQLSRV_PARAM_OUT, SQLSRV_PARAM_INOUT. O valor padrão é SQLSRV_PARAM_IN.
  $phpType (opcional) | Uma constante SQLSRV_PHPTYPE_* que especifica o tipo de dado PHP do valor retornado.
  $sqlType (opcional) | Uma constante SQLSRV_SQLTYPE_* que especifica o tipo de dado do SQL Server do valor de entrada.

`options`
  Um array especificando opções de propriedade da consulta. As chaves suportadas são descritas na tabela a seguir:

  Opções de Consulta
  Chave | Valores | Descrição
  --- | --- | ---
  QueryTimeout | Um valor inteiro positivo. | Define o tempo limite da consulta em segundos. Por padrão, o driver aguardará indefinidamente por resultados.
  SendStreamParamsAtExec | `true` ou `false` (o padrão é `true`) | Configura o driver para enviar todos os dados de fluxo na execução (`true`), ou para enviar os dados de fluxo em blocos (`false`). Por padrão, o valor é `true`. Para mais informações, consulte sqlsrv_send_stream_data().
  Scrollable | SQLSRV_CURSOR_FORWARD, SQLSRV_CURSOR_STATIC, SQLSRV_CURSOR_DYNAMIC, ou SQLSRV_CURSOR_KEYSET | Veja » Especificar um Tipo de Cursor e Selecionar Linhas na documentação do Microsoft SQLSRV.

### Valor Retornado

Retorna um recurso de declaração em caso de sucesso e `false` se ocorrer um erro.

### Exemplos

Exemplo #1 Exemplo de sqlsrv_prepare()

Este exemplo demonstra como preparar uma declaração com sqlsrv_prepare() e reexecutá-la várias vezes (com diferentes valores de parâmetro) usando sqlsrv_execute().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false) {
        die( print_r( sqlsrv_errors(), true));
    }

    $sql = "UPDATE Table_1
            SET OrderQty = ?
            WHERE SalesOrderID = ?";

    // Inicializa os parâmetros e prepara a instrução.
    // As variáveis $qty e $id estão vinculadas à instrução $stmt.
    $qty = 0; $id = 0;
    $stmt = sqlsrv_prepare( $conn, $sql, array( &$qty, &$id));
    if( !$stmt ) {
        die( print_r( sqlsrv_errors(), true));
    }

    // Configure as informações de SalesOrderDetailID e OrderQty.
    // Este array mapeia o ID do pedido para a quantidade do pedido em pares chave=>valor.
    $orders = array( 1=>10, 2=>20, 3=>30);

    //Executa a instrução para cada pedido.
    foreach( $orders as $id => $qty) {
        // Como $id e $qty estão vinculados a $stmt1, seus valores atualizados
        // valores são usados em cada execução da instrução.
        if( sqlsrv_execute( $stmt ) === false ) {
              die( print_r( sqlsrv_errors(), true));
        }
    }
    ?>

### Notas

Ao preparar uma declaração que usa variáveis como parâmetros, as variáveis são vinculadas à declaração. Isso significa que se você atualizar os valores das variáveis, na próxima vez que executar a declaração, ela será executada com valores de parâmetro atualizados. Para declarações que você planeja executar apenas uma vez, use sqlsrv_query().

### Veja Também

- sqlsrv_execute() - Executa uma declaração preparada com sqlsrv_prepare
- sqlsrv_query() - Prepara e executa uma consulta

# sqlsrv_query

(No version information available, might only be in Git)

sqlsrv_query — Prepara e executa uma consulta

### Descrição

function sqlsrv_query(
resource `$conn`,
string `$sql`,
array `$params` = ?,
array `$options` = ?
): mixed

Prepara e executa uma consulta.

### Parâmetros

`conn`
  Um recurso de conexão retornado por sqlsrv_connect().
`sql`
  A string que define a consulta a ser preparada e executada.
`params`

  Um array especificando informações de parâmetro ao executar uma consulta parametrizada. Os elementos do array podem ser um dos seguintes:

  - Um valor literal
  - Uma variável PHP
  - Um array com esta estrutura: array($valor [, $direção [, $tipoPHP [, $tipoSQL]]])
  A tabela a seguir descreve os elementos na estrutura do array acima:

  Estrutura do array
  Elemento | Descrição
  --- | ---
  $value | Um valor literal, uma variável PHP ou uma variável PHP por referência.
  $direction (opcional) | Uma das constantes SQLSRV usadas para indicar a direção do parâmetro: SQLSRV_PARAM_IN, SQLSRV_PARAM_OUT, SQLSRV_PARAM_INOUT. O valor padrão é SQLSRV_PARAM_IN.
  $phpType (opcional) | Uma constante SQLSRV_PHPTYPE_* que especifica o tipo de dado PHP do valor retornado.
  $sqlType (opcional) | Uma constante SQLSRV_SQLTYPE_* que especifica o tipo de dado do SQL Server do valor de entrada.

`options`
  Um array especificando opções de propriedade da consulta. As chaves suportadas são descritas na tabela a seguir:

  Opções de Consulta
  Chave | Valores | Descrição
  --- | --- | ---
  QueryTimeout | Um valor inteiro positivo. | Define o tempo limite da consulta em segundos. Por padrão, o driver aguardará indefinidamente por resultados.
  SendStreamParamsAtExec | `true` ou `false` (o padrão é `true`) | Configura o driver para enviar todos os dados de fluxo na execução (`true`), ou para enviar os dados de fluxo em blocos (`false`). Por padrão, o valor é `true`. Para mais informações, consulte sqlsrv_send_stream_data().
  Scrollable | SQLSRV_CURSOR_FORWARD, SQLSRV_CURSOR_STATIC, SQLSRV_CURSOR_DYNAMIC, ou SQLSRV_CURSOR_KEYSET | Veja » Especificar um Tipo de Cursor e Selecionar Linhas na documentação do Microsoft SQLSRV.

### Valor Retornado

Retorna um recurso de declaração em caso de sucesso e `false` se ocorrer um erro.

### Exemplos

Exemplo #1 Exemplo de sqlsrv_query()

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "INSERT INTO Table_1 (id, data) VALUES (?, ?)";
    $params = array(1, "some data");

    $stmt = sqlsrv_query( $conn, $sql, $params);
    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }
    ?>

### Notas

Para declarações que você planeja executar apenas uma vez, use sqlsrv_query(). Se você pretende reexecutar uma declaração com diferentes valores de parâmetro, use a combinação de sqlsrv_prepare() e sqlsrv_execute().

### Veja Também

- sqlsrv_prepare() - Prepara uma consulta para execução
- sqlsrv_execute() - Executa uma declaração preparada com sqlsrv_prepare

# sqlsrv_rollback

(No version information available, might only be in Git)

sqlsrv_rollback — Reverte uma transação que foi iniciada com sqlsrv_begin_transaction()

### Descrição

function sqlsrv_rollback(resource `$conn`): bool

Reverte uma transação que foi iniciada com sqlsrv_begin_transaction() e retorna a conexão ao modo de auto-commit.

### Parâmetros

`conn`
  O recurso de conexão retornado por uma chamada para sqlsrv_connect().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de sqlsrv_rollback()

O exemplo a seguir demonstra como usar sqlsrv_begin_transaction() junto com sqlsrv_commit() e sqlsrv_rollback().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true ));
    }

    /* Inicia a transação. */
    if ( sqlsrv_begin_transaction( $conn ) === false ) {
         die( print_r( sqlsrv_errors(), true ));
    }

    /* Inicializa os valores dos parâmetros. */
    $orderId = 1; $qty = 10; $productId = 100;

    /* Configura e executa a primeira consulta. */
    $sql1 = "INSERT INTO OrdersTable (ID, Quantity, ProductID)
             VALUES (?, ?, ?)";
    $params1 = array( $orderId, $qty, $productId );
    $stmt1 = sqlsrv_query( $conn, $sql1, $params1 );

    /* Configura e executa a segunda consulta. */
    $sql2 = "UPDATE InventoryTable
             SET Quantity = (Quantity - ?)
             WHERE ProductID = ?";
    $params2 = array($qty, $productId);
    $stmt2 = sqlsrv_query( $conn, $sql2, $params2 );

    /* Se ambas as consultas foram bem-sucedidas, confirma a transação. */
    /* Caso contrário, reverte a transação. */
    if( $stmt1 && $stmt2 ) {
         sqlsrv_commit( $conn );
         echo "Transaction committed.<br />";
    } else {
         sqlsrv_rollback( $conn );
         echo "Transaction rolled back.<br />";
    }
    ?>

### Veja Também

- sqlsrv_begin_transaction() - Inicia uma transação de banco de dados
- sqlsrv_commit() - Confirma uma transação que foi iniciada com sqlsrv_begin_transaction

# sqlsrv_rows_affected

(No version information available, might only be in Git)

sqlsrv_rows_affected — Retorna o número de linhas modificadas pela última consulta INSERT, UPDATE ou DELETE executada

### Descrição

function sqlsrv_rows_affected(resource `$stmt`): int|false

Retorna o número de linhas modificadas pela última consulta INSERT, UPDATE ou DELETE executada. Para informações sobre o número de linhas retornadas por uma consulta SELECT, consulte sqlsrv_num_rows().

### Parâmetros

`stmt`
  O recurso da instrução executada para o qual o número de linhas afetadas é retornado.

### Valor Retornado

Retorna o número de linhas afetadas pela última consulta INSERT, UPDATE ou DELETE. Se nenhuma linha foi afetada, 0 é retornado. Se o número de linhas afetadas não puder ser determinado, -1 é retornado. Se ocorreu um erro, `false` é retornado.

### Exemplos

Exemplo #1 Exemplo de sqlsrv_rows_affected()

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "UPDATE Table_1 SET data = ? WHERE id = ?";

    $params = array("updated data", 1);

    $stmt = sqlsrv_query( $conn, $sql, $params);

    $rows_affected = sqlsrv_rows_affected( $stmt);
    if( $rows_affected === false) {
         die( print_r( sqlsrv_errors(), true));
    } elseif( $rows_affected == -1) {
          echo "Nenhuma informação disponível.<br>";
    } else {
          echo $rows_affected." linhas foram atualizadas.<br>";
    }
    ?>

### Veja Também

- sqlsrv_num_rows() - Recupera o número de linhas em um conjunto de resultados

# sqlsrv_send_stream_data

(No version information available, might only be in Git)

sqlsrv_send_stream_data — Envia dados de fluxos de parâmetros para o servidor

### Descrição

function sqlsrv_send_stream_data(resource `$stmt`): bool

Envia dados de fluxos de parâmetros para o servidor. Até 8 KB de dados são enviados com cada chamada.

### Parâmetros

`stmt`
  Um recurso de instrução retornado por sqlsrv_query() ou sqlsrv_execute().

### Valor Retornado

Retorna `true` se houver mais dados para enviar e `false` se não houver.

### Exemplos

Exemplo #1 Exemplo de sqlsrv_send_stream_data()

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "UPDATE Table_1 SET data = ( ?) WHERE id = 100";

    // Abre os dados do parâmetro como um fluxo e coloca-os no array $params.
    $data = fopen( "data://text/plain,[ Lengthy content here. ]", "r");
    $params = array( &$data);

    // Prepara a instrução. Use o array $options para desativar o
    // comportamento padrão, que é enviar todos os dados de fluxo no momento da consulta
    // execução.
    $options = array("SendStreamParamsAtExec" => 0);
    $stmt = sqlsrv_prepare( $conn, $sql, $params, $options);

    sqlsrv_execute( $stmt);

    // Envia até 8 KB de dados de parâmetro para o servidor
    // com cada chamada a sqlsrv_send_stream_data.
    $i = 1;
    while( sqlsrv_send_stream_data( $stmt)) {
          $i++;
    }
    echo "$i chamadas foram feitas.";
    ?>

### Veja Também

- sqlsrv_prepare() - Prepara uma consulta para execução
- sqlsrv_query() - Prepara e executa uma consulta

# sqlsrv_server_info

(No version information available, might only be in Git)

sqlsrv_server_info — Retorna informações sobre o servidor

### Descrição

function sqlsrv_server_info(resource `$conn`): array

Retorna informações sobre o servidor.

### Parâmetros

`conn`
  O recurso de conexão que conecta o cliente e o servidor.

### Valor Retornado

Retorna um array conforme descrito na seguinte tabela:

Array retornado
CurrentDatabase | O banco de dados conectado.
--- | ---
SQLServerVersion | A versão do SQL Server.
SQLServerName | O nome do servidor.

### Exemplos

Exemplo #1 Exemplo de sqlsrv_server_info()

    <?php
    $serverName = "serverName\sqlexpress";
    $conn = sqlsrv_connect( $serverName);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $server_info = sqlsrv_server_info( $conn);
    if( $server_info )
    {
        foreach( $server_info as $key => $value) {
           echo $key.": ".$value."<br />";
        }
    } else {
          die( print_r( sqlsrv_errors(), true));
    }
    ?>

### Veja Também

- sqlsrv_client_info() - Retorna informações sobre o cliente e a conexão especificada

## Índice

- sqlsrv_begin_transaction — Inicia uma transação de banco de dados
- sqlsrv_cancel — Cancela uma declaração
- sqlsrv_client_info — Retorna informações sobre o cliente e a conexão especificada
- sqlsrv_close — Fecha uma conexão aberta e libera os recursos associados à conexão
- sqlsrv_commit — Confirma uma transação que foi iniciada com sqlsrv_begin_transaction
- sqlsrv_configure — Altera as configurações de tratamento de erros e registro do driver
- sqlsrv_connect — Abre uma conexão com um banco de dados Microsoft SQL Server
- sqlsrv_errors — Retorna informações de erro e aviso sobre a última operação SQLSRV executada
- sqlsrv_execute — Executa uma declaração preparada com sqlsrv_prepare
- sqlsrv_fetch — Torna a próxima linha em um conjunto de resultados disponível para leitura
- sqlsrv_fetch_array — Retorna uma linha como um array
- sqlsrv_fetch_object — Recupera a próxima linha de dados em um conjunto de resultados como um objeto
- sqlsrv_field_metadata — Recupera metadados para os campos de uma declaração preparada por sqlsrv_prepare ou sqlsrv_query
- sqlsrv_free_stmt — Libera todos os recursos para a declaração especificada
- sqlsrv_get_config — Retorna o valor da configuração especificada
- sqlsrv_get_field — Obtém dados do campo da linha atualmente selecionada
- sqlsrv_has_rows — Indica se a declaração especificada possui linhas
- sqlsrv_next_result — Torna o próximo resultado da declaração especificada ativo
- sqlsrv_num_fields — Recupera o número de campos (colunas) em uma declaração
- sqlsrv_num_rows — Recupera o número de linhas em um conjunto de resultados
- sqlsrv_prepare — Prepara uma consulta para execução
- sqlsrv_query — Prepara e executa uma consulta
- sqlsrv_rollback — Reverte uma transação que foi iniciada com sqlsrv_begin_transaction
- sqlsrv_rows_affected — Retorna o número de linhas modificadas pela última consulta INSERT, UPDATE ou DELETE executada
- sqlsrv_send_stream_data — Envia dados de fluxos de parâmetros para o servidor
- sqlsrv_server_info — Retorna informações sobre o servidor

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
  - Tipos de Recurso
- Constantes predefinidas
- Funções SQLSRV
  - sqlsrv_begin_transaction — Inicia uma transação de banco de dados
  - sqlsrv_cancel — Cancela uma declaração
  - sqlsrv_client_info — Retorna informações sobre o cliente e a conexão especificada
  - sqlsrv_close — Fecha uma conexão aberta e libera os recursos associados à conexão
  - sqlsrv_commit — Confirma uma transação que foi iniciada com sqlsrv_begin_transaction
  - sqlsrv_configure — Altera as configurações de tratamento de erros e registro do driver
  - sqlsrv_connect — Abre uma conexão com um banco de dados Microsoft SQL Server
  - sqlsrv_errors — Retorna informações de erro e aviso sobre a última operação SQLSRV executada
  - sqlsrv_execute — Executa uma declaração preparada com sqlsrv_prepare
  - sqlsrv_fetch — Torna a próxima linha em um conjunto de resultados disponível para leitura
  - sqlsrv_fetch_array — Retorna uma linha como um array
  - sqlsrv_fetch_object — Recupera a próxima linha de dados em um conjunto de resultados como um objeto
  - sqlsrv_field_metadata — Recupera metadados para os campos de uma declaração preparada por sqlsrv_prepare ou sqlsrv_query
  - sqlsrv_free_stmt — Libera todos os recursos para a declaração especificada
  - sqlsrv_get_config — Retorna o valor da configuração especificada
  - sqlsrv_get_field — Obtém dados do campo da linha atualmente selecionada
  - sqlsrv_has_rows — Indica se a declaração especificada possui linhas
  - sqlsrv_next_result — Torna o próximo resultado da declaração especificada ativo
  - sqlsrv_num_fields — Recupera o número de campos (colunas) em uma declaração
  - sqlsrv_num_rows — Recupera o número de linhas em um conjunto de resultados
  - sqlsrv_prepare — Prepara uma consulta para execução
  - sqlsrv_query — Prepara e executa uma consulta
  - sqlsrv_rollback — Reverte uma transação que foi iniciada com sqlsrv_begin_transaction
  - sqlsrv_rows_affected — Retorna o número de linhas modificadas pela última consulta INSERT, UPDATE ou DELETE executada
  - sqlsrv_send_stream_data — Envia dados de fluxos de parâmetros para o servidor
  - sqlsrv_server_info — Retorna informações sobre o servidor

- CUBRID
  - Instalação/Configuração
  - Constantes predefinidas
  - Exemplos
  - Funções de CUBRID
  - Funções de compatibilidade CUBRID MySQL
  - Funções e sinônimos obsoletos do CUBRID
- dBase
  - Instalação/Configuração
  - Constantes predefinidas
  - Funções da dBase
- Firebird/InterBase
  - Instalação/Configuração
  - Constantes predefinidas
  - Funções para Firebird/InterBase
- IBM DB2 — IBM DB2, Cloudscape e Apache Derby
  - Instalação/Configuração
  - Constantes predefinidas
  - Funções de IBM DB2
- MongoDB — Extensão MongoDB
  - Instalação/Configuração
  - Constantes predefinidas
  - Tutoriais
  - Arquitetura do driver e componentes internos — Explica a arquitetura do driver e recursos especiais
  - Segurança
  - MongoDB\Driver — Classes da Extensão MongoDB
  - MongoDB\BSON — Classes e Funções BSON do MongoDB
  - MongoDB\Driver\Monitoring — Classes de monitoramento e funções assinantes
  - MongoDB\Driver\Exception — Classes de exceção
- MySQL — Drivers e Plugins MySQL
  - Visão geral dos drivers PHP para MySQL
  - MySQLi — Extensão MySQL Melhorada
  - Mysql_xdevapi
  - MySQL (Original) — API Original MySQL
  - Mysqlnd — Driver Nativo MySQL
- OCI8 — Oracle OCI8
  - Instalação/Configuração
  - Constantes predefinidas
  - Exemplos
  - Manipulação e conjunto de conexões do OCI8
  - Suporte à Notificação Rápida de Aplicação (FAN) do OCI8
  - Suporte ao OCI8 Transparent Application Failover (TAF)
  - OCI8 e Rastreamento dinâmico DTrace
  - Tipos de dados suportados
  - Funções OCI8
  - OCICollection — The OCICollection class
  - OCILob — A classe OCILob
  - Funções e sinônimos e obsoletos do OCI8
- PostgreSQL
  - Instalação/Configuração
  - Constantes predefinidas
  - Exemplos
  - Funções PostgreSQL
  - PgSql\Connection — A classe PgSql\Connection
  - PgSql\Result — A classe PgSql\Result
  - PgSql\Lob — A classe PgSql\Lob
- SQLite3
  - Instalação/Configuração
  - Constantes predefinidas
  - SQLite3 — A classe SQLite3
  - SQLite3Exception — A classe SQLite3Exception
  - SQLite3Stmt — A classe SQLite3Stmt
  - SQLite3Result — A classe SQLite3Result
- SQLSRV — Driver Microsoft SQL Server para PHP
  - Instalação/Configuração
  - Constantes predefinidas
  - Funções SQLSRV

- Camadas de Abstração
  - DBA — Camada de abstração de banco de dados (estilo dbm)
  - ODBC — ODBC (Unificado)
  - PDO — PHP Data Objects
- Extensões de Banco de Dados Específicas de Terceiros
  - CUBRID
  - dBase
  - Firebird/InterBase
  - IBM DB2 — IBM DB2, Cloudscape e Apache Derby
  - MongoDB — Extensão MongoDB
  - MySQL — Drivers e Plugins MySQL
  - OCI8 — Oracle OCI8
  - PostgreSQL
  - SQLite3
  - SQLSRV — Driver Microsoft SQL Server para PHP

# Extensões Relacionadas a Data e Horário

# Calendário

# Introdução

A extensão de calendário apresenta uma série de funções para simplificar a conversão entre diferentes formatos de calendários. O intermédiário ou padrão é baseado na Contagem de Dias Julianos. A Contagem de Dias Julianos é uma contagem de dias iniciando em 1º de Janeiro de 4713 AEC. Para converter entre sistemas de calendários, deve-se primeiro convertê-lo para a Contagem de Dias Julianos, e então convertê-lo para o sistema de calendário desejado. A Contagem de Dias Julianos é muito diferente do calendário juliano! Para mais informações sobre a Contagem de Dias Julianos, visite » http://www.hermetic.ch/cal_stud/jdn.htm. Para mais informações sobre sistemas de calendários, visite » http://www.fourmilab.ch/documents/calendar/. Trechos desta página estão incluídos nestas instruções e estão entre aspas.

# Instalação/Configuração

## Índice

- Instalação

## Instalação

Para estas funções funcionarem, é necessário compilar o PHP com --enable-calendar.

A versão do PHP para Windows tem suporte nativo para esta extensão. Nenhuma extensão adicional precisa ser carregada para usar essas funções.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`CAL_EASTER_DEFAULT` (int)
  Para a função easter_days(): calcula a data da Páscoa para anos anteriores a 1753 de acordo com o calendário Juliano, e para anos posteriores de acordo com o calendrário Gregoriano.
`CAL_EASTER_ROMAN` (int)
  Para a função easter_days(): calcula a data da Páscoa para anos anteriores a 1583 de acordo com o calendário Juliano, e para anos posteriores de acordo com o calendrário Gregoriano.
`CAL_EASTER_ALWAYS_GREGORIAN` (int)
  Para a função easter_days(): calcula a data da Páscoa de acordo com o calendário Gregoriano proléptico.
`CAL_EASTER_ALWAYS_JULIAN` (int)
  Para a função easter_days(): calcula a data da Páscoa de cordo com o calendário Juliano.
`CAL_GREGORIAN` (int)
  Para as funções cal_days_in_month(), cal_from_jd(), cal_info() e cal_to_jd(): usam o calendário Gregoriano proléptico.
`CAL_JULIAN` (int)
  Para as funções cal_days_in_month(), cal_from_jd(), cal_info() e cal_to_jd(): usam o calendário Juliano.
`CAL_JEWISH` (int)
  Para as funções cal_days_in_month(), cal_from_jd(), cal_info() e cal_to_jd(): usam o calendário Judeu.
`CAL_FRENCH` (int)
  Para as funções cal_days_in_month(), cal_from_jd(), cal_info() e cal_to_jd(): usam o calendário Republicano Francês.
`CAL_NUM_CALS` (int)
  O número de calendários disponíveis.
`CAL_JEWISH_ADD_ALAFIM_GERESH` (int)
  Para a função jdtojewish(): adiciona um símbolo de geresh (que lembra um apóstrofo) como separador de milhares ao número do ano.
`CAL_JEWISH_ADD_ALAFIM` (int)
  Para a função jdtojewish(): adiciona a palavra alafim como separadora de milhares ao número do ano.
`CAL_JEWISH_ADD_GERESHAYIM` (int)
  Para a função jdtojewish(): adiciona um símbolo gershayim (que lembra aspas duplas) antes da letra final dos número de dia e ano.
`CAL_DOW_DAYNO` (int)
  Para a função jddayofweek(): o dia da semana como int, onde `0` representa domingo e `6` representa sábado.
`CAL_DOW_SHORT` (int)
  Para a função jddayofweek(): o nome em inglês abreviado do dia da semana.
`CAL_DOW_LONG` (int)
  Para a função jddayofweek(): o nome em inglês do dia da semana.
`CAL_MONTH_GREGORIAN_SHORT` (int)
  Para a função jdmonthname(): o nome do mês Gregoriano abreviado.
`CAL_MONTH_GREGORIAN_LONG` (int)
  Para a função jdmonthname(): o nome do mês Gregoriano.
`CAL_MONTH_JULIAN_SHORT` (int)
  Para a função jdmonthname(): o nome do mês Juliano abreviado.
`CAL_MONTH_JULIAN_LONG` (int)
  Para a função jdmonthname(): o nome do mês Juliano.
`CAL_MONTH_JEWISH` (int)
  Para a função jdmonthname(): o nome do mês Judeu.
`CAL_MONTH_FRENCH` (int)
  Para a função jdmonthname(): o nome do mês Republicano Francês.

# Calendário Funções

# cal_days_in_month

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_days_in_month — Retorna o número de dias em um mês de um calendário e ano requisitado

### Descrição

function cal_days_in_month(int `$calendar`, int `$month`, int `$year`): int

Esta função irá retornar o número de dias em um `month` do `year` para o `calendar` especificado.

### Parâmetros

`calendar`

  Calendário para usar no cálculo

`month`

  Mês a ser selecionado no calendário

`year`

  Ano no selecionado calendário

### Valor Retornado

A quantidade de dias do selecionado mês no dado calendário

### Exemplos

Exemplo #1 Exemplo da cal_days_in_month()

    <?php
    $numero = cal_days_in_month(CAL_GREGORIAN, 8, 2003); // 31
    echo "Houve {$numero} dias em Agosto de 2003";
    ?>

# cal_from_jd

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_from_jd — Converte de uma Contagem de Dias Julianos para um calendário suportado

### Descrição

function cal_from_jd(int `$julian_day`, int `$calendar`): array

cal_from_jd() converte o dia Juliano fornecido em `julian_day` para uma data no calendário especificado em `calendar`. Valores suportados para `calendar` são `CAL_GREGORIAN`, `CAL_JULIAN`, `CAL_JEWISH` e `CAL_FRENCH`.

### Parâmetros

`julian_day`

  Dia Juliano como um número inteiro

`calendar`

  Calendário para o qual será feita a conversão.

### Valor Retornado

Retorna um array contendo informações do calendário como mês, dia, ano, dia da semana (`dow`), nomes abreviados e completos de meses e dias da semana e a data em string no formato "mês/dia/ano". O dia da semana pode variar de `0` (domingo) a `6` (sábado).

### Exemplos

Exemplo #1 Exemplo de cal_from_jd()

    <?php
    $today = unixtojd(mktime(0, 0, 0, 8, 16, 2003));
    print_r(cal_from_jd($today, CAL_GREGORIAN));
    ?>

O exemplo acima produzirá:

    Array
    (
        [date] => 8/16/2003
        [month] => 8
        [day] => 16
        [year] => 2003
        [dow] => 6
        [abbrevdayname] => Sat
        [dayname] => Saturday
        [abbrevmonth] => Aug
        [monthname] => August
    )

### Veja Também

- cal_to_jd() - Converte um calendário (suportado) para o calendário "Julian Day Count"
- jdtofrench() - Converte do calendário "Julian Day Count" para o calendário Republicano Francês
- jdtogregorian() - Converte uma data no formato "Julian Day Count" para o formato Gregoriano
- jdtojewish() - Converte uma contagem de dias Julianos para uma data do calendário Judeu
- jdtojulian() - Converte uma Contagem de Dias Julianos para uma data do calendário juliano
- jdtounix() - Converte Dia Juliano para timestamp Unix

# cal_info

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_info — Retorna informação sobre um calendário específico

### Descrição

function cal_info(int `$calendar` = -1): array

cal_info() retorna informação sobre o calendário especificado em `calendar`.

Informação sobre calendário é retornada como um array contendo os elementos `calname`, `calsymbol`, `month`, `abbrevmonth` e `maxdaysinmonth`. Os nomes dos diferentes calendários que podem ser usados no parâmetro `calendar` são os seguintes:

- 0 ou `CAL_GREGORIAN` - Calendário Gregoriano
- 1 ou `CAL_JULIAN` - Calendário Juliano
- 2 ou `CAL_JEWISH` - Calendário Judeu
- 3 ou `CAL_FRENCH` - Calendário da Revolução Francesa

Se o parâmetro `calendar` não for especificado, informação sobre todos os calendários suportados é retornada como um array.

### Parâmetros

`calendar`

  Calendário para o qual será retornada a informação. Se nenhum calendário for especificado, informação sobre todos os calendários suportados é retornada.

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de cal_info()

    <?php
    $info = cal_info(0);
    print_r($info);
    ?>

O exemplo acima produzirá:

    Array
    (
        [months] => Array
            (
                [1] => January
                [2] => February
                [3] => March
                [4] => April
                [5] => May
                [6] => June
                [7] => July
                [8] => August
                [9] => September
                [10] => October
                [11] => November
                [12] => December
            )

        [abbrevmonths] => Array
            (
                [1] => Jan
                [2] => Feb
                [3] => Mar
                [4] => Apr
                [5] => May
                [6] => Jun
                [7] => Jul
                [8] => Aug
                [9] => Sep
                [10] => Oct
                [11] => Nov
                [12] => Dec
            )

        [maxdaysinmonth] => 31
        [calname] => Gregorian
        [calsymbol] => CAL_GREGORIAN
    )

# cal_to_jd

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_to_jd — Converte um calendário (suportado) para o calendário "Julian Day Count"

### Descrição

function cal_to_jd(
int `$calendar`,
int `$month`,
int `$day`,
int `$year`
): int

cal_to_jd() calcula uma data em formato "Julian Day Count" à partir de um `calendar` suportado especificado. Os `calendar` suportados são: `CAL_GREGORIAN`, `CAL_JULIAN`, `CAL_JEWISH` e `CAL_FRENCH`.

### Parâmetros

`calendar`

  Calendário para converter, um dos `CAL_GREGORIAN`, `CAL_JULIAN`, `CAL_JEWISH` ou `CAL_FRENCH`.

`month`

  O mês como um número, o intervalo válido depende do `calendar`

`day`

  O dia como um número, o intervalo válido depende do `calendar`

`year`

  O ano como um número, o intervalo válido depende do `calendar`

### Valor Retornado

Um número de data juliana.

### Veja Também

- cal_from_jd() - Converte de uma Contagem de Dias Julianos para um calendário suportado
- frenchtojd() - Converte uma data do calendário Republicano Francês para uma contagem de Dias Julianos
- gregoriantojd() - Converte uma data gregoriana para o "Julian Day Count"
- jewishtojd() - Converte uma data do calendário Judaico para o calendário "Julian Day Count"
- juliantojd() - Converte uma data do calendário juliano para uma contagem de dias julianos
- unixtojd() - Converte um timestamp Unix para um dia Juliano

# easter_date

(PHP 4, PHP 5, PHP 7, PHP 8)

easter_date — Obtém o timestamp Unix para a meia-noite local da Páscoa de um ano informado

### Descrição

function easter_date(?int `$year` = `null`, int `$mode` = `CAL_EASTER_DEFAULT`): int

Retorna o timestamp Unix correspondente à meia-noite local da Páscoa do ano informado.

A data do Dia de Páscoa foi definida pelo Concílio de Niceia no ano 325 D.C. como o domingo após a primeira lua cheia que cai no equinócio de primavera ou depois dele. Assume-se que o equinócio seja sempre no dia 21 de março, portanto o cálculo se reduz a determinar a data da lua cheia e a data do domingo seguinte. O algoritmo usado aqui foi introduzido por volta do ano 532 por Dionísio, o exíguo. Sob o calendário Juliano (para anos anteriores a 1753), um ciclo simples de 19 anos é usado para acompanhar as fases da lua. Sob o calendário Gregoriano (para anos posteriores a 1753 - concebido por Cristóvão Clávio e Luís Lílio, e introduzido pelo Papa Gregório XIII em outubro de 1582, e na Grã-Bretanha e suas então colônias em setembro de 1752), dois fatores de correção são adicionados para deixar o ciclo mais preciso.

### Parâmetros

`year`

  O ano deve ser um número entre 1970 e 2037 para sistemas de 32 bits, ou entre 1970 e 2.000.000.000 para sistemas de 64 bits. Se omitido ou `null`, será usado o padrão que é o ano atual conforme o horário local.

`mode`

  Permite que datas de Páscoa sejam calculadas com base no calendário Juliano quando definido para `CAL_EASTER_ALWAYS_JULIAN`. Consulte também as constantes de calendário.

### Valor Retornado

A data da Páscoa como um timestamp Unix.

### Erros/Exceções

Uma exceção ValueError é lançada se o ano for anterior a 1970 ou posterior a 2037 em sistemas de 32 bits, ou posterior a 2.000.000.000 em sistemas de 64 bits.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Em sistemas de 64 bits, o parâmetro `year` agora aceita valores na faixa de 1970 a 2.000.000.000.
8.0.0 | `year` agora pode ser nulo.
8.0.0 | Uma exceção ValueError agora é lançada quando `year` estiver fora do intervalo permitido. Anteriormente, um `E_WARNING` era emitido e a função retornava `false`.

### Exemplos

Exemplo #1 Exemplo de easter_date()

    <?php

    echo date("M-d-Y", easter_date(1999));        // Apr-04-1999
    echo date("M-d-Y", easter_date(2000));        // Apr-23-2000
    echo date("M-d-Y", easter_date(2001));        // Apr-15-2001

    ?>

Exemplo #2 Usando easter_date() com DateTime

    <?php

    $timestamp = easter_date(2023);

    $datetime = new \DateTime();
    $datetime->setTimestamp($timestamp);

    echo $datetime->format('M-d-Y'); // Apr-09-2023

    ?>

### Notas

> Nota:

> easter_date() depende das funções de horário da biblioteca C do sistema, ao invés de usar as funções de data e horário internas do PHP. Como uma consequência, easter_date() usa a variável de ambiente `TZ` para determinar o fuso horário onde ela deve operar, ao invés de usar o fuso horário padrão do PHP, o que pode retultar em comportamento inesperado ao usar esta função em conjunto com outras funções de data no PHP.

> Como uma maneira de contornar isso, pode-se usar easter_days() com DateTime e DateInterval para calcular o início da Páscoa no fuso horário do PHP como no exemplo a seguir:

>     <?php
>     function get_easter_datetime($year) {
>         $base = new DateTime("$year-03-21");
>         $days = easter_days($year);

>         return $base->add(new DateInterval("P{$days}D"));
>     }

>     foreach (range(2012, 2015) as $year) {
>         printf("Páscoa em %d é no dia %s\n",
>                $year,
>                get_easter_datetime($year)->format('d/m'));
>     }
>     ?>

> O exemplo acima produzirá:

>     Páscoa em 2012 é no dia 08/04
>     Páscoa em 2013 é no dia 31/03
>     Páscoa em 2014 é no dia 20/04
>     Páscoa em 2015 é no dia 05/04

### Veja Também

- easter_days() - Obtém o número de dias depois de 21 de março no qual a Páscoa cai para um determinado ano para cálculo da Páscoa antes de 1970 ou depois de 2037

# easter_days

(PHP 4, PHP 5, PHP 7, PHP 8)

easter_days — Obtém o número de dias depois de 21 de março no qual a Páscoa cai para um determinado ano

### Descrição

function easter_days(?int `$year` = `null`, int `$mode` = `CAL_EASTER_DEFAULT`): int

Retorna o número de dias depois de 21 de março no qual a Páscoa cai para um determinado ano. Se nenhum ano for especificado, o ano atual é assumido como parâmetro.

Esta função pode ser usada no lugar de easter_date() para calculas a Páscoa para anos que caiam fora do intervalo de timestamps Unix (isto é, antes de 1970 ou depois de 2037).

A data do Dia de Páscoa foi definida pelo Concílio de Niceia no ano 325 D.C. como o domingo após a primeira lua cheia que caia no Equinócio de Primavera ou depois dele. Assume-se que o Equinócio seja sempre no dia 21 de março, portanto o cálculo se reduz a determinar a data da lua cheia e a data do domingo seguinte. O algoritmo usado aqui foi introduzido por volta do ano 532 por Dionísio, o Exíguo. Sob o calendário Juliano (para anos anteriores a 1753) um ciclo simples de 19 anos é usado para acompanhar as fases da lua. Sob o calendário Gregoriano (para anos posteriores a 1753 - concebido por Cristóvão Clávio e Luís Lílio, e introduzido pelo Papa Gregório XIII em outubro de 1582, e na Grã-Bretanha e suas então colônias em setembro de 1752) dois fatores de correção são adicionados para deixar o ciclo mais preciso.

### Parâmetros

`year`

  O ano como número positivo. Se omitido ou `null`, é usado como padrão o ano atual conforme o horário local.

`mode`

  Permite que datas de Páscoa sejam calculadas com base no calendário Gregoriano durante os anos 1582 a 1752 quando definido para `CAL_EASTER_ROMAN`. Consulte também as constantes de calendário para mais constantes válidas.

### Valor Retornado

O número de dias depois de 21 de março onde cai o domingo de Páscoa no ano informado no parâmetro `year`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `year` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo de easter_days()

    <?php

    echo easter_days(1999);        // 14, isto é, 4 de abril
    echo easter_days(1492);        // 32, isto é, 22 de abril
    echo easter_days(1913);        //  2, isto é, 23 de março

    ?>

### Veja Também

- easter_date() - Obtém o timestamp Unix para a meia-noite local da Páscoa de um ano informado

# frenchtojd

(PHP 4, PHP 5, PHP 7, PHP 8)

frenchtojd — Converte uma data do calendário Republicano Francês para uma contagem de Dias Julianos

### Descrição

function frenchtojd(int `$month`, int `$day`, int `$year`): int

Converte uma data do calendário Republicano Francês para uma contagem de Dias Julianos.

Estas rotinas convertem apenas datas dos anos 1 ao 14 (datas Gregorianas 22 de setembro de 1792 a 22 de setembro de 1806). Isto cobre mais que o período em que o calendário esteve em uso.

### Parâmetros

`month`

  O mês como um número de 1 (para Vendémiaire) a 13 (para o período de 5 a 6 dias no final de cada ano)

`day`

  O dia como um número de 1 a 30

`year`

  O ano como um número entre 1 e 14

### Valor Retornado

O dia Juliano para a data informada do calendário revolucionário francês, como um inteiro.

### Veja Também

- jdtofrench() - Converte do calendário "Julian Day Count" para o calendário Republicano Francês
- cal_to_jd() - Converte um calendário (suportado) para o calendário "Julian Day Count"

# gregoriantojd

(PHP 4, PHP 5, PHP 7, PHP 8)

gregoriantojd — Converte uma data gregoriana para o "Julian Day Count"

### Descrição

function gregoriantojd(int `$month`, int `$day`, int `$year`): int

A escala válida para o Calendário Gregoriano é de 25 de Novembro, 4714 A.C. até pelo menos 31 de Dezembro, 9999 D.C.

Entretanto esta função pode trabalhar com todas datas anteriores à, porém usá-la desta maneira não tem muito sentido. O Calendário Gregoriano não foi instituído até 15 de Outubro de 1582 (ou 5 de Outubro de 1582, no calendário JDC ("Julian Day Count")). Alguns países aceitaram este calendário um pouco mais tarde. Por exemplo, a Grã Bretanha converteu-se em 1752, a URSS em 1918 e a Grécia em 1923. A maioria dos países Europeus usaram o calendário "Julian" (JDC) antes do calendário Gregoriano.

### Parâmetros

`month`

  O mês como um número entre 1 (para janeiro) e 12 (para dezembro)

`day`

  O dia como um número entre 1 e 31 Se o mês tem menos dias do que o especificado; veja o exemplo abaixo.

`year`

  O ano como um número entre -4714 e 9999 Números negativos indicam anos A.C., números positivos indicam anos D.C. Note que não existe ano `0`; 31 de Dezembro, 1 A.C. é seguido emediatamente por 1 de Janeiro, 1 D.C.

### Valor Retornado

A data juliana para a dada data gregoriana como um inteiro. Datas fora da escala válida retornam `0`.

### Exemplos

Exemplo #1 Funções de Calendário

    <?php
    $jd = gregoriantojd(10,11,1970);
    echo "$jd\n";
    $gregorian = jdtogregorian($jd);
    echo "$gregorian\n";
    ?>

O exemplo acima produzirá:

    2440871
    10/11/1970

Exemplo #2 Overflow behavior

    <?php
    echo gregoriantojd(2, 31, 2018), PHP_EOL,
         gregoriantojd(3,  3, 2018), PHP_EOL;
    ?>

O exemplo acima produzirá:

    2458181
    2458181

### Veja Também

- jdtogregorian() - Converte uma data no formato "Julian Day Count" para o formato Gregoriano
- cal_to_jd() - Converte um calendário (suportado) para o calendário "Julian Day Count"

# jddayofweek

(PHP 4, PHP 5, PHP 7, PHP 8)

jddayofweek — Retorna o dia da semana de um dia Juliano

### Descrição

function jddayofweek(int `$julian_day`, int `$mode` = `CAL_DOW_DAYNO`): int|string

Retorna o dia da semana de um dia Juliano. Pode retornar uma string ou um inteiro dependendo do modo.

### Parâmetros

`julian_day`

  Um número inteiro do dia Juliano

`mode`

  Modos de semana do calendário
  Modo | Significado
  --- | ---
  0 (Padrão) | Retorna o número do dia como um int (0=domingo, 1=segunda, etc)
  1 | Retorna uma string contendo o dia de semana (Inglês-Gregoriano)
  2 | Retorna uma string contendo o dia da semana abreviado (Inglês-Gregoriano)

### Valor Retornado

O dia da semana gregoriano como um inteiro ou uma string.

# jdmonthname

(PHP 4, PHP 5, PHP 7, PHP 8)

jdmonthname — Retorna o nome de um mês

### Descrição

function jdmonthname(int `$julian_day`, int `$mode`): string

Retorna uma "string" contendo o nome do mês. O parâmetro `mode` diz à função qual calendário será convertido para o formato de Contagem de Dias Julianos e o tipo do nome do mês.

Calendário (modos)
Modo | Significado | Valores
--- | --- | ---
`CAL_MONTH_GREGORIAN_SHORT` | Gregoriano - abreviado | Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
`CAL_MONTH_GREGORIAN_LONG` | Gregoriano | January, February, March, April, May, June, July, August, September, October, November, December
`CAL_MONTH_JULIAN_SHORT` | Juliano - abreviado | Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
`CAL_MONTH_JULIAN_LONG` | Juliano | January, February, March, April, May, June, July, August, September, October, November, December
`CAL_MONTH_JEWISH` | Judeu | Tishri, Heshvan, Kislev, Tevet, Shevat, Adar, Adar I, Adar II, Nisan, Iyyar, Sivan, Tammuz, Av, Elul
`CAL_MONTH_FRENCH` | Republicano Francês | Vendemiaire, Brumaire, Frimaire, Nivose, Pluviose, Ventose, Germinal, Floreal, Prairial, Messidor, Thermidor, Fructidor, Extra

### Parâmetros

`julian_day`

  O dia juliano.

`mode`

  O modo do calendário (veja tabela acima).

### Valor Retornado

O nome do mês para o dia juliano e `mode`.

# jdtofrench

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtofrench — Converte do calendário "Julian Day Count" para o calendário Republicano Francês

### Descrição

function jdtofrench(int `$julian_day`): string

Converte do calendário de Contagem de Dias Julianos para o calendário Republicano Francês.

### Parâmetros

`julian_day`

  Um número de dia juliano como inteiro

### Valor Retornado

A data republicana francesa como uma string no formato "mês/dia/ano"

### Veja Também

- frenchtojd() - Converte uma data do calendário Republicano Francês para uma contagem de Dias Julianos
- cal_from_jd() - Converte de uma Contagem de Dias Julianos para um calendário suportado

# jdtogregorian

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtogregorian — Converte uma data no formato "Julian Day Count" para o formato Gregoriano

### Descrição

function jdtogregorian(int `$julian_day`): string

Converte da Contagem de Dias Julianos para uma "string" contendo a data gregoriana no formato "mês/dia/ano".

### Parâmetros

`julian_day`

  O número de um dia juliano como um inteiro

### Valor Retornado

A data gregoriana como uma string no formato "mês/dia/ano"

### Veja Também

- gregoriantojd() - Converte uma data gregoriana para o "Julian Day Count"
- cal_from_jd() - Converte de uma Contagem de Dias Julianos para um calendário suportado

# jdtojewish

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtojewish — Converte uma contagem de dias Julianos para uma data do calendário Judeu

### Descrição

function jdtojewish(int `$julian_day`, bool `$hebrew` = `false`, int `$flags` = 0): string

Converte uma contagem de dias Julianos para o calendário Judeu.

### Parâmetros

`julian_day`

  O número do dia Juliano como um inteiro

`hebrew`

  Se o parâmetro `hebrew` for definido para `true`, o parâmetro `flags` é usado para o formato de saída hebraico, baseado em string codificado em ISO-8859-8.

`flags`

  Uma máscara de bits que pode consistir em `CAL_JEWISH_ADD_ALAFIM_GERESH`, `CAL_JEWISH_ADD_ALAFIM` e `CAL_JEWISH_ADD_GERESHAYIM`.

### Valor Retornado

A data Judia como uma string no formato "mês/dia/ano", ou uma data string codificada em em ISO-8859-8, hebraico, de acordo com o parâmetro `hebrew`.

### Exemplos

Exemplo #1 Exemplo de jdtojewish()

    <?php
    $jd = gregoriantojd(10, 8, 2002);
    echo jdtojewish($jd, true), PHP_EOL,
         jdtojewish($jd, true, CAL_JEWISH_ADD_GERESHAYIM), PHP_EOL,
         jdtojewish($jd, true, CAL_JEWISH_ADD_ALAFIM), PHP_EOL,
         jdtojewish($jd, true,CAL_JEWISH_ADD_ALAFIM_GERESH), PHP_EOL;
    ?>

O exemplo acima produzirá:

    ב חשון התשסג
    ב' חשון התשס"ג
    ב חשון ה אלפים תשסג
    ב חשון ה'תשסג

### Veja Também

- jewishtojd() - Converte uma data do calendário Judaico para o calendário "Julian Day Count"
- cal_from_jd() - Converte de uma Contagem de Dias Julianos para um calendário suportado

# jdtojulian

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtojulian — Converte uma Contagem de Dias Julianos para uma data do calendário juliano

### Descrição

function jdtojulian(int `$julian_day`): string

Converte uma Contagem de Dias Julianos para uma "string" contendo a data do calendário juliano no formato "mês/dia/ano".

### Parâmetros

`julian_day`

  O número de dia juliano como um inteiro

### Valor Retornado

A data juliana como uma string no formato "mês/dia/ano"

### Veja Também

- juliantojd() - Converte uma data do calendário juliano para uma contagem de dias julianos
- cal_from_jd() - Converte de uma Contagem de Dias Julianos para um calendário suportado

# jdtounix

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtounix — Converte Dia Juliano para timestamp Unix

### Descrição

function jdtounix(int `$julian_day`): int

Esta função irá retorna um timestamp Unix correspondente ao Dia Juliano especificado no parâmetro `julian_day`. O horário retornado é UTC.

### Parâmetros

`julian_day`

  O número de dia juliano entre `2440588` e `106751993607888` em sistemas de 64 bits, ou entre `2440588` e `2465443` em sistemas de 32 bits

### Valor Retornado

O timestamp Unix para o início (meia noite, não meio dia) do dia juliano informado

### Erros/Exceções

Se `julian_day` estiver fora do intervalo permitido, um ValueError é lançado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Essa funcão não retorna mais `false` em caso de falha, mas lança um ValueError.
7.3.24, 7.4.12 | O limite superior de `julian_day` foi estendido. Antes, era `2465342` sem levar em consideração a arquitetura.

### Veja Também

- unixtojd() - Converte um timestamp Unix para um dia Juliano

# jewishtojd

(PHP 4, PHP 5, PHP 7, PHP 8)

jewishtojd — Converte uma data do calendário Judaico para o calendário "Julian Day Count"

### Descrição

function jewishtojd(int `$month`, int `$day`, int `$year`): int

Entretanto esta função suporta datas anteriores ao ano 1 (3761 A.C.), porém tal uso não faz sentido. O calendário Judaico vem sendo usado por centenas de anos, porém os primeiros dias não tem uma fórmula que determina qual é o começo do mês. Um novo mês começa quando uma lua nova é vista.

### Parâmetros

`month`

  O mês como um número entre `1` e `13`, onde `1` significa `Tishri`, `13` significa `Elul`, e `6` e `7` significa `Adar` em anos não bissexto, mas `Adar I` e `Adar II`, respectivamente, em anos bissextos.

`day`

  O dia como um número entre `1` e `30`. Se um mês tem apenas 29 dias, será considerado o primeiro dia do mês seguinte.

`year`

  O ano como um número entre 1 e 9999

### Valor Retornado

A data juliana para a dada data judaica como um inteiro.

### Veja Também

- jdtojewish() - Converte uma contagem de dias Julianos para uma data do calendário Judeu
- cal_to_jd() - Converte um calendário (suportado) para o calendário "Julian Day Count"

# juliantojd

(PHP 4, PHP 5, PHP 7, PHP 8)

juliantojd — Converte uma data do calendário juliano para uma contagem de dias julianos

### Descrição

function juliantojd(int `$month`, int `$day`, int `$year`): int

O Calendário juliano vai de 4713 AEC até 9999 EC.

Embora esta função possa lidar com datas tão antigas quanto 4713 AEC, seu uso pode não ter significado. O calendário foi criado em 46 AEC, mas os detalhes não foram padronizados até pelo menos no ano 8 EC, e talvez até mais tarde, no 4º século. Além disso, o começo de um ano variou de uma cultura para outra - nem todas aceitaram janeiro como o primeiro mês.

Cuidado

Lembre-se, o sistema atual de calendário que é usado mundialmente é o gregoriano. A função gregoriantojd() pode ser usada para converter essas datas para o formato de contagem de dias julianos.

### Parâmetros

`month`

  O mês como um número entre 1 (para janeiro) a 12 (para dezembro)

`day`

  O dia como um número entre 1 a 31

`year`

  O ano como um número entre -4713 a 9999

### Valor Retornado

O dia juliano para a dada juliana como um inteiro.

### Veja Também

- jdtojulian() - Converte uma Contagem de Dias Julianos para uma data do calendário juliano
- cal_to_jd() - Converte um calendário (suportado) para o calendário "Julian Day Count"

# unixtojd

(PHP 4, PHP 5, PHP 7, PHP 8)

unixtojd — Converte um timestamp Unix para um dia Juliano

### Descrição

function unixtojd(?int `$timestamp` = `null`): int|false

Retorna o dia Juliano para um `timestamp` Unix (segundos desde 01/01/1970), ou para o dia atual se nenhum `timestamp` for informado. De qualquer forma, o horário considerado é o local (não o UTC).

### Parâmetros

`timestamp`

  Um timestamp Unix a ser convertido.

### Valor Retornado

O dia Juliano como um inteiro, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `timestamp` agora pode ser nulo.

### Veja Também

- jdtounix() - Converte Dia Juliano para timestamp Unix

## Índice

- cal_days_in_month — Retorna o número de dias em um mês de um calendário e ano requisitado
- cal_from_jd — Converte de uma Contagem de Dias Julianos para um calendário suportado
- cal_info — Retorna informação sobre um calendário específico
- cal_to_jd — Converte um calendário (suportado) para o calendário "Julian Day Count"
- easter_date — Obtém o timestamp Unix para a meia-noite local da Páscoa de um ano informado
- easter_days — Obtém o número de dias depois de 21 de março no qual a Páscoa cai para um determinado ano
- frenchtojd — Converte uma data do calendário Republicano Francês para uma contagem de Dias Julianos
- gregoriantojd — Converte uma data gregoriana para o "Julian Day Count"
- jddayofweek — Retorna o dia da semana de um dia Juliano
- jdmonthname — Retorna o nome de um mês
- jdtofrench — Converte do calendário "Julian Day Count" para o calendário Republicano Francês
- jdtogregorian — Converte uma data no formato "Julian Day Count" para o formato Gregoriano
- jdtojewish — Converte uma contagem de dias Julianos para uma data do calendário Judeu
- jdtojulian — Converte uma Contagem de Dias Julianos para uma data do calendário juliano
- jdtounix — Converte Dia Juliano para timestamp Unix
- jewishtojd — Converte uma data do calendário Judaico para o calendário "Julian Day Count"
- juliantojd — Converte uma data do calendário juliano para uma contagem de dias julianos
- unixtojd — Converte um timestamp Unix para um dia Juliano

- Instalação/Configuração
  - Instalação
- Constantes predefinidas
- Calendário Funções
  - cal_days_in_month — Retorna o número de dias em um mês de um calendário e ano requisitado
  - cal_from_jd — Converte de uma Contagem de Dias Julianos para um calendário suportado
  - cal_info — Retorna informação sobre um calendário específico
  - cal_to_jd — Converte um calendário (suportado) para o calendário "Julian Day Count"
  - easter_date — Obtém o timestamp Unix para a meia-noite local da Páscoa de um ano informado
  - easter_days — Obtém o número de dias depois de 21 de março no qual a Páscoa cai para um determinado ano
  - frenchtojd — Converte uma data do calendário Republicano Francês para uma contagem de Dias Julianos
  - gregoriantojd — Converte uma data gregoriana para o "Julian Day Count"
  - jddayofweek — Retorna o dia da semana de um dia Juliano
  - jdmonthname — Retorna o nome de um mês
  - jdtofrench — Converte do calendário "Julian Day Count" para o calendário Republicano Francês
  - jdtogregorian — Converte uma data no formato "Julian Day Count" para o formato Gregoriano
  - jdtojewish — Converte uma contagem de dias Julianos para uma data do calendário Judeu
  - jdtojulian — Converte uma Contagem de Dias Julianos para uma data do calendário juliano
  - jdtounix — Converte Dia Juliano para timestamp Unix
  - jewishtojd — Converte uma data do calendário Judaico para o calendário "Julian Day Count"
  - juliantojd — Converte uma data do calendário juliano para uma contagem de dias julianos
  - unixtojd — Converte um timestamp Unix para um dia Juliano

# Data e Horário

# Introdução

A classe DateTimeImmutable e classes relacionadas permitem representar informações de data/horário. Os objetos podem ser criados passando-se uma representação de informação de data/horário no formato string, ou a partir do horário atual do sistema.

Existe também um conjunto rico de métodos para modificar e formatar estas informações, incluindo manipulação de fusos horários e transições de horários de verão.

As características de data/horário no PHP implementam o calendário ISO 8601, que é um » calendário gregoriano proléptico que implementa as regras atuais de anos bissextos estendidas a períodos anteriores ao que o calendário gregoriano foi adotado, e também inclui o ano `0` como o número do ano entre `-1 AEC` e `1 EC`. Segundos intercalares não são suportados.

A informação de data e horário é armazenada internamente como um número de 64 bits, sendo assim, todas as datas úteis concebíveis (incluindo anos negativos) são suportadas. O intervalo vai de aproximadamente 292 bilhões de anos no passado até o mesmo valor no futuro.

> Nota: Os fusos horários referenciados nesta seção podem ser encontrados em Lista de Fusos Horários Suportados.

# Instalação/Configuração

## Índice

- Instalação
- Configurações em Execução

## Instalação

Nenhuma instalação é necessária para usar estas funções; elas fazem parte do núcleo do PHP.

> Nota: Recuperando o banco de dados atualizado de fusos horários

> A versão mais recente do banco de dados de fusos horários pode ser instalada com o pacote PECL » timezonedb.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de Configuração de Data/Horário
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
date.default_latitude | "31.7667" | `INI_ALL` |
date.default_longitude | "35.2333" | `INI_ALL` |
date.sunrise_zenith | "90.833333" | `INI_ALL` | Antes do PHP 8.0.0, o padrão era "90.583333"
date.sunset_zenith | "90.833333" | `INI_ALL` | Antes do PHP 8.0.0, o padrão era "90.583333"
date.timezone | "UTC" | `INI_ALL` | A partir do PHP 8.2, um aviso é emitido quando este parâmetro é configurado para um valor inválido ou para um string vazio.

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`date.default_latitude` float

  A latitude padrão variando de `0` no equador, até `+90` para o norte, e `-90` para o sul.

`date.default_longitude` float

  A longitude padrão variando de `0` no meridiano primário até `+180` para o leste e `−180` para o oeste.

`date.sunrise_zenith` float

  O ápice do nascer do sol padrão.

  O valor padrão é 90°50'. Os 50' adicionais são devido a dois componentes: o raio aparente do sol, que é 16', e a refração atmosférica aparente, que é de 34'.

`date.sunset_zenith` float

  O ápice do pôr-do-sol padrão.

`date.timezone` string

  O fuso horário padrão usado por todas as funções de data/horário. A ordem de precedência para qual fuso horário será utilizado se nenhum for explicitamente mencionado é descrita na função date_default_timezone_get(). Acesse Lista de Fusos Horários Suportados para uma lista de todos os fusos horários suportados.

> Nota: As primeiras quatro opções de configuração são utilizadas somente pelas funções date_sunrise() e date_sunset().

# Constantes predefinidas

As constantes `DATE_*` estão definidas e oferecem uma representação padrão de datas, que podem ser utilizadas em conjunto com funções de formatação de data (como a função date()).

Valores possíveis do parâmetro `returnFormat` para date_sunrise() e date_sunset()
Aviso

Estas constantes estão descontinuadas a partir do PHP 8.4.0. As funções correspondentes date_sunrise() e date_sunset() estão descontinuadas a partir do PHP 8.1.0.

`SUNFUNCS_RET_TIMESTAMP` (int)
  Timestamp
`SUNFUNCS_RET_STRING` (int)
  Horas:minutos (exemplo: `08:02`)
`SUNFUNCS_RET_DOUBLE` (int)
  Horas como número em ponto flutuante (exemplo `8.75`)

Constantes `DATE_*`
`DATE_ATOM` (string)
  Atômico (exemplo: `2005-08-15T15:52:01+00:00`); compatível com ISO-8601, RFC 3339 e esquema XML
`DATE_COOKIE` (string)
  Cookies HTTP (exemplo: `Monday, 15-Aug-2005 15:52:01 UTC`)
`DATE_ISO8601` (string)
  Tipo ISO-8601 (exemplo: `2005-08-15T15:52:01+0000`)

  > Nota: Este formato não é compatível com ISO-8601, mas é deixado desta forma por motivo de compatibilidade. Use `DATE_ISO8601_EXPANDED`, `DATE_ATOM` para compatibilidade com ISO-8601 em seu lugar (ref. ISO8601:2004 seção 4.3.3 cláusula d).

`DATE_ISO8601_EXPANDED` (string)
  ISO-8601 Expandida (exemplo: `+10191-07-26T08:59:52+01:00`)

  > Nota: Este formato permite intervalos de anos fora dos limites padrão da ISO-8601 de `0000`-`9999` através da inclusão se um caractere de sinal. Ele também garante que a parte de fuso horário (`+01:00`) seja compatível com a ISO-8601.

`DATE_RFC822` (string)
  RFC 822 (exemplo: `Mon, 15 Aug 05 15:52:01 +0000`)
`DATE_RFC850` (string)
  RFC 850 (exemplo: `Monday, 15-Aug-05 15:52:01 UTC`)
`DATE_RFC1036` (string)
  RFC 1036 (exemplo: `Mon, 15 Aug 05 15:52:01 +0000`)
`DATE_RFC1123` (string)
  RFC 1123 (exemplo: `Mon, 15 Aug 2005 15:52:01 +0000`)
`DATE_RFC7231` (string)
  RFC 7231 (a partir do PHP 7.0.19 e 7.1.5) (exemplo: `Sat, 30 Apr 2016 17:52:13 GMT`)
`DATE_RFC2822` (string)
  RFC 2822 (exemplo: `Mon, 15 Aug 2005 15:52:01 +0000`)
`DATE_RFC3339` (string)
  O mesmo que `DATE_ATOM`.
`DATE_RFC3339_EXTENDED` (string)
  Formato RFC 3339 ESTENDIDO (exemplo: `2005-08-15T15:52:01.000+00:00`)
`DATE_RSS` (string)
  RSS (exemplo: `Mon, 15 Aug 2005 15:52:01 +0000`). Sinônimo de `DATE_RFC1123`.
`DATE_W3C` (string)
  World Wide Web Consortium (exemplo: `2005-08-15T15:52:01+00:00`). Sinônimo de `DATE_RFC3339`.

# Exemplos

## Índice

- Aritmética de Data e Horário

## Aritmética de Data e Horário

Os exemplos a seguir mostram algumas armadilhas da aritmética de data/horário em relação a transições de horário de verão e meses que contêm números diferentes de dias.

Exemplo #1 DateTimeImmutable::add/sub adicionando intervalos que tempo decorrido

Adicionar PT24H sobre uma transição de horário de verão irá aparentar uma adição de 23/25 horas (para a maioria dos fusos horários).

    <?php
    $dt = new DateTimeImmutable("2015-11-01 00:00:00", new DateTimeZone("America/New_York"));
    echo "Início: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->add(new DateInterval("PT3H"));
    echo "Fim:    ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

O exemplo acima produzirá:

    Início: 2015-11-01 00:00:00 -04:00
    Fim:    2015-11-01 02:00:00 -05:00

Exemplo #2 DateTimeImmutable::modify e strtotime incrementando ou decrementando valores de componentes individuais

Inserir "+24 hours" sobre uma transição de horário de verão irá adicionar exatamente 24 horas como visto na string de data/horário (a menos que o horário de início ou fim esteja em um ponto de transição).

    <?php
    $dt = new DateTimeImmutable("2015-11-01 00:00:00", new DateTimeZone("America/New_York"));
    echo "Início: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("+24 hours");
    echo "Fim:    ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

O exemplo acima produzirá:

    Início: 2015-11-01 00:00:00 -04:00
    Fim:    2015-11-02 00:00:00 -05:00

Exemplo #3 Adicionar ou substrair períodos pode causar transferência de datas

Como em 31 de janeiro + 1 mês, irá resultar em 2 de março (em ano bissexto) ou 3 de março (em ano normal).

    <?php
    echo "Ano normal:\n"; // fevereiro tem 28 dias
    $dt = new DateTimeImmutable("2015-01-31 00:00:00", new DateTimeZone("America/New_York"));
    echo "Início: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("+1 month");
    echo "Fim:    ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

    echo "Ano bissexto:\n"; // fevereiro tem 29 dias
    $dt = new DateTimeImmutable("2016-01-31 00:00:00", new DateTimeZone("America/New_York"));
    echo "Início: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("+1 month");
    echo "Fim:    ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

O exemplo acima produzirá:

    Ano normal:
    Início: 2015-01-31 00:00:00 -05:00
    Fim:    2015-03-03 00:00:00 -05:00
    Ano bissexto:
    Início: 2016-01-31 00:00:00 -05:00
    Fim:    2016-03-02 00:00:00 -05:00

Para obter o último dia do mês seguinte (para evitar a transferência), o formato `last day of` está disponível.

    <?php
    echo "Ano normal:\n"; // fevereiro tem 28 dias
    $dt = new DateTimeImmutable("2015-01-31 00:00:00", new DateTimeZone("America/New_York"));
    echo "Início: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("last day of next month");
    echo "Fim:    ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

    echo "Ano bissexto:\n"; // fevereiro tem 29 dias
    $dt = new DateTimeImmutable("2016-01-31 00:00:00", new DateTimeZone("America/New_York"));
    echo "Início: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("last day of next month");
    echo "Fim:    ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

O exemplo acima produzirá:

    Ano normal:
    Início: 2015-01-31 00:00:00 -05:00
    Fim:    2015-02-28 00:00:00 -05:00
    Ano bissexto:
    Início: 2016-01-31 00:00:00 -05:00
    Fim:    2016-02-29 00:00:00 -05:00

# A classe DateTime

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

## Introdução

Representação de data e hora.

Esta classe se comporta da mesma maneira que a classe DateTimeImmutable, exceto pelo fato de que os objetos se alteram quando métodos de modificação como DateTime::modify() são chamados.

Aviso

Chamar métodos em objetos da classe DateTime irá alterar a informação encapsulada nestes objetos. Se a intenção for evitar isso, deve ser usado o operador `clone` para criar um novo objeto. É recomendado usar DateTimeImmutable no lugar de DateTime para obter este comportamento por padrão.

## Resumo da classe

class DateTime implements DateTimeInterface {
/* Constantes herdadas */
public const string DateTimeInterface::ATOM = "Y-m-d\\TH:i:sP";
public const string DateTimeInterface::COOKIE = "l, d-M-Y H:i:s T";
public const string DateTimeInterface::ISO8601 = "Y-m-d\\TH:i:sO";
public const string DateTimeInterface::ISO8601_EXPANDED = "X-m-d\\TH:i:sP";
public const string DateTimeInterface::RFC822 = "D, d M y H:i:s O";
public const string DateTimeInterface::RFC850 = "l, d-M-y H:i:s T";
public const string DateTimeInterface::RFC1036 = "D, d M y H:i:s O";
public const string DateTimeInterface::RFC1123 = "D, d M Y H:i:s O";
public const string DateTimeInterface::RFC7231 = "D, d M Y H:i:s \\G\\M\\T";
public const string DateTimeInterface::RFC2822 = "D, d M Y H:i:s O";
public const string DateTimeInterface::RFC3339 = "Y-m-d\\TH:i:sP";
public const string DateTimeInterface::RFC3339_EXTENDED = "Y-m-d\\TH:i:s.vP";
public const string DateTimeInterface::RSS = "D, d M Y H:i:s O";
public const string DateTimeInterface::W3C = "Y-m-d\\TH:i:sP";
/* Métodos */
public function __construct(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`)
public function add(DateInterval `$interval`): DateTime
public static function createFromFormat(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTime|false
public static function createFromImmutable(DateTimeImmutable `$object`): static
public static function createFromInterface(DateTimeInterface `$object`): DateTime
public static function createFromTimestamp(int|float `$timestamp`): static
public function modify(string `$modifier`): DateTime
public static function __set_state(array `$array`): DateTime
public function setDate(int `$year`, int `$month`, int `$day`): DateTime
public function setISODate(int `$year`, int `$week`, int `$dayOfWeek` = 1): DateTime
public function setMicrosecond(int `$microsecond`): static
public function setTime(
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTime
public function setTimestamp(int `$timestamp`): DateTime
public function setTimezone(DateTimeZone `$timezone`): DateTime
public function sub(DateInterval `$interval`): DateTime
public function diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval
public function format(string `$format`): string
public function getMicrosecond(): int
public function getOffset(): int
public function getTimestamp(): int
public function getTimezone(): DateTimeZone|false
public function __serialize(): array
public function __unserialize(array `$data`): void
#[\Deprecated]
public function __wakeup(): void
}

## Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | As constantes de classe agora são tipadas.
7.2.0 | As constantes da classe DateTime são agora definidas na classe DateTimeInterface.
7.1.0 | O construtor da classe DateTime agora inclui os microssegundos atuais no valor construído. Antes disso, ele sempre inicializava os microssegundos em `0`.

# DateTime::add

# date_add

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::add -- date_add — Modifica um objeto DateTime, com adição de dias, meses, anos, horas, minutos e segundos.

### Descrição

Estilo orientado a objetos

public function DateTime::add(DateInterval `$interval`): DateTime

Estilo procedural

function date_add(DateTime `$object`, DateInterval `$interval`): DateTime

Adiciona o objeto DateInterval informado a um objeto DateTime especificado.

Equivalente a DateTimeImmutable::add() mas funciona com DateTime.

A versão procedural usa o objeto DateTime como primeiro argumento.

### Parâmetros

`object`
  Somente no estilo procedural: Um objeto DateTime retornado por date_create(). A função modifica este objeto.
`interval`

  Um objeto DateInterval

### Valor Retornado

Retorna o objeto DateTime modificado para encadeamento de métodos.

### Veja Também

- DateTimeImmutable::add() - Retorna um novo objeto, com adição de dias, meses, anos, horas, minutos e segundos

# DateTime::__construct

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::__construct — Retorna um novo objeto DateTime

### Descrição

public function DateTime::__construct(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`)

Equivalente a DateTimeImmutable::__construct() mas funciona com DateTime. Considere usar DateTimeImmutable e suas caracterísitcas.

Retorna um novo objeto DateTime.

### Parâmetros

`datetime`

  Uma string de data/hora. Os formatos válidos são explicados em Formatos de Data e Hora.

  Coloque `"now"` neste parâmetro para obter o horário atual quando utilizar o parâmetro `$timezone`.

`timezone`

  Um objeto DateTimeZone, representando o fuso horário do parâmetro `$datetime`.

  Se `$timezone` for `null` ou omitido, o fuso horário atual será utilizado.

  > Nota:

  > O parâmetro `$timezone` e o fuso horário atual são ignorados quando o parâmetro `$datetime` é um timestamp UNIX (exemplo, `@946684800`) ou quando o fuso horário é informado (exemplo. `2010-01-28T15:00:00+02:00`).

### Valor Retornado

Retorna uma nova instância de DateTime.

### Erros/Exceções

Se uma string inválida de data/horário for passada, uma exceção DateMalformedStringException é disparada. Antes do PHP 8.3, era uma Exception.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Agora dispara DateMalformedStringException se uma string inválida é passada, em vez de Exception.

### Veja Também

- DateTimeImmutable::__construct() - Retorna um novo objeto DateTimeImmutable

# DateTime::createFromFormat

# date_create_from_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::createFromFormat -- date_create_from_format — Interpreta um string de data/horário de acordo com um formato especificado.

### Descrição

Estilo orientado a objetos

public static function DateTime::createFromFormat(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTime|false

Estilo procedural

function date_create_from_format(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTime|false

Retorna um novo objeto DateTime representando a data e o horário especificados pela string `datetime`, que foi formatada de acordo com o parâmetro `format` fornecido.

Equivalente a DateTimeImmutable::createFromFormat() e date_create_immutable_from_format(), respectivamente, mas cria um objeto DateTime.

Este método, incluindo parâmetros, exemplos e considerações estão documentados na página DateTimeImmutable::createFromFormat.

### Parâmetros

Ver DateTimeImmutable::createFromFormat.

### Valor Retornado

Retorna uma nova instância de DateTime ou `false` em caso de falha.

### Erros/Exceções

Este método dispara uma exceção ValueError quando o parâmetro `datetime` contém bytes nulos.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.21, 8.1.8, 8.2.0 | Agora dispara ValueError quando bytes nulos são passados pelo parâmetro `datetime`, o que antes era silencioamente ignorado.

### Exemplos

Para um conjunto extenso de exemplos, veja DateTimeImmutable::createFromFormat.

### Veja Também

- DateTimeImmutable::createFromFormat() - Interpreta um string de data/horário de acordo com o formato especificado

# DateTime::createFromImmutable

(PHP 7 >= 7.3.0, PHP 8)

DateTime::createFromImmutable — Retorna uma nova instância de DateTime encapsulando o objeto DateTimeImmutable informado

### Descrição

public static function DateTime::createFromImmutable(DateTimeImmutable `$object`): static

### Parâmetros

`object`

  O objeto imutável DateTimeImmutable que necessita ser convertido para uma versão mutável. Este objeto não é modificado, em vez disso uma nova instância DateTime é criada contendo as mesmas informações de data, horário e fuso.

### Valor Retornado

Retorna uma nova instância DateTime.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O método agora retorna uma instância da classe que está sendo chamada. Anteriormente, ele criava uma nova instância de DateTime.

### Exemplos

Exemplo #1 Criando um objeto de data/horário mutável

    <?php
    $date = new DateTimeImmutable("2014-06-20 11:45 Europe/London");
    $mutable = DateTime::createFromImmutable( $date );

# DateTime::createFromInterface

(PHP 8)

DateTime::createFromInterface — Retorna um novo objeto DateTime encapsulando o objeto DateTimeInterface informado

### Descrição

public static function DateTime::createFromInterface(DateTimeInterface `$object`): DateTime

### Parâmetros

`object`

  O objeto DateTimeInterface que necessita ser convertido para uma versão mutável. Este objeto não é modificado, em vez disso uma nova instância DateTime é criada contendo as mesmas informações de data, horário e fuso.

### Valor Retornado

Retorna uma nova instância de DateTime.

### Exemplos

Exemplo #1 Criando um objeto de data/horário mutável

    <?php
    $date = new DateTimeImmutable("2014-06-20 11:45 Europe/London");
    $mutable = DateTime::createFromInterface($date);

    $date = new DateTime("2014-06-20 11:45 Europe/London");
    $also_mutable = DateTime::createFromInterface($date);

# DateTime::createFromTimestamp

(PHP 8 >= 8.4.0)

DateTime::createFromTimestamp — Cria uma instância a partir de um timestamp Unix

### Descrição

public static function DateTime::createFromTimestamp(int|float `$timestamp`): static

Cria uma instância a partir de um timestamp Unix.

### Parâmetros

`timestamp`
  Timestamp Unix representando a data/horário. Um valor float também é aceito, o que permite precisão de microssegundos.

### Valor Retornado

Retorna uma nova instância de DateTime.

### Erros/Exceções

Se `timestamp` estiver fora do intervalo [`PHP_INT_MIN`, `PHP_INT_MAX`], uma DateRangeError é lançada.

### Exemplos

Exemplo #1 Exemplo de DateTime::createFromTimestamp()

    <?php
    $date = DateTime::createFromTimestamp(123.456789);
    echo $date->format('Y-m-d H:i:s.u');
    ?>

O exemplo acima produzirá:

    1970-01-01 00:02:03.456789

# DateTime::getLastErrors

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::getLastErrors — Sinônimo de DateTimeImmutable::getLastErrors()

### Descrição

Esta função é um apelido para: DateTimeImmutable::getLastErrors()

# DateTime::modify

# date_modify

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::modify -- date_modify — Altera o timestamp

### Descrição

Estilo orientado a objetos

public function DateTime::modify(string `$modifier`): DateTime

Estilo procedural

function date_modify(DateTime `$object`, string `$modifier`): DateTime|false

Altera o timestamp de um objeto DateTime, incrementando-o ou decrementando-o, em um formato aceito pela função DateTimeImmutable::__construct().

### Parâmetros

`object`
  Somente no estilo procedural: Um objeto DateTime retornado por date_create(). A função modifica este objeto.
`modifier`

  Uma string de data/hora. Os formatos válidos são explicados em Formatos de Data e Hora.

### Valor Retornado

Retorna DateTime em caso de sucesso. Estilo procedural retorna `false` em caso de falha.

### Erros/Exceções

Apenas para API orientada a objetos: Se uma string inválida de data/horário for passada, uma exceção DateMalformedStringException é lançada.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Agora tem o tipo de retorno provisório DateTime. Anteriormente era DateTime|false.
8.3.0 | DateTime::modify() agora lança uma exceção DateMalformedStringException se uma string inválida for passada. Anteriormente, retornava `false` e um alerta era emitido. A função date_modify() não foi alterada.

### Exemplos

Exemplo #1 Exemplo do método DateTime::modify()

Estilo orientado a objetos

    <?php
    $date = new DateTime('2006-12-12');
    $date->modify('+1 day');
    echo $date->format('Y-m-d');

O exemplo acima produzirá:

    2006-12-13

Estilo procedural

    <?php
    $date = date_create('2006-12-12');
    date_modify($date, '+1 day');
    echo date_format($date, 'Y-m-d');

O exemplo acima produzirá:

    2006-12-13

Exemplo #2 Cuidados na adição ou subtração de meses

    <?php
    $date = new DateTime('2000-12-31');

    $date->modify('+1 month');
    echo $date->format('Y-m-d') . "\n";

    $date->modify('+1 month');
    echo $date->format('Y-m-d') . "\n";

O exemplo acima produzirá:

    2001-01-31
    2001-03-03

Exemplo #3 Todos os formatos de data e horário são suportados

    <?php
    $date = new DateTime('2020-12-31');

    $date->modify('July 1st, 2023');
    echo $date->format('Y-m-d H:i') . "\n";

    $date->modify('Monday next week');
    echo $date->format('Y-m-d H:i') . "\n";

    $date->modify('17:30');
    echo $date->format('Y-m-d H:i') . "\n";

O exemplo acima produzirá:

    2023-07-01 00:00
    2023-07-03 00:00
    2023-07-03 17:30

### Veja Também

- strtotime() - Interpreta qualquer descrição textual de data/horário em inglês para timestamp Unix
- DateTimeImmutable::modify() - Cria um novo objeto com seu timestamp modificado
- DateTime::add() - Modifica um objeto DateTime, com adição de dias, meses, anos, horas, minutos e segundos.
- DateTime::sub() - Subtrai uma quantidade de dias, meses, anos, horas, minutos e segundos de um objeto DateTime
- DateTime::setDate() - Define a data
- DateTime::setISODate() - Define uma data ISO
- DateTime::setTime() - Define o horário
- DateTime::setTimestamp() - Define a data e hora baseada em um timestamp Unix

# DateTime::__set_state

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::__set_state — O manipulador __set_state

### Descrição

public static function DateTime::__set_state(array `$array`): DateTime

O manipulador __set_state().

Equivalente a DateTimeImmutable::__set_state() mas funciona com DateTime.

### Parâmetros

`array`

  Inicialização do array.

### Valor Retornado

Retorna uma nova instância de um objeto DateTime.

# DateTime::setDate

# date_date_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setDate -- date_date_set — Define a data

### Descrição

Estilo orientado a objetos

public function DateTime::setDate(int `$year`, int `$month`, int `$day`): DateTime

Estilo procedural

function date_date_set(
DateTime `$object`,
int `$year`,
int `$month`,
int `$day`
): DateTime

Redefine a data atual do objeto Datetime para uma diferente.

Equivalente a DateTimeImmutable::setDate() mas funciona com DateTime, e modifica o objeto existente.

A versão procedural usa o objeto DateTime como seu primeiro argumento.

### Parâmetros

`object`
  Somente no estilo procedural: Um objeto DateTime retornado por date_create(). A função modifica este objeto.
`year`

  Ano da data.

`month`

  Mês da data.

`day`

  Dia da data.

### Valor Retornado

Retorna o objeto DateTime modificado para encadeamento de métodos.

### Veja Também

- DateTimeImmutable::setDate() - Define a data

# DateTime::setISODate

# date_isodate_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setISODate -- date_isodate_set — Define uma data ISO

### Descrição

Estilo orientado a objetos

public function DateTime::setISODate(int `$year`, int `$week`, int `$dayOfWeek` = 1): DateTime

Estilo procedural

function date_isodate_set(
DateTime `$object`,
int `$year`,
int `$week`,
int `$dayOfWeek` = 1
): DateTime

Define uma data, de acordo com o padrão ISO 8601 - utilizando a diferença de semanas e dias em vez de datas específicas.

Equivalente a DateTimeImmutable::setISODate() mas funciona com DateTime.

A versão procedural usa o objeto DateTime como seu primeiro argumento.

### Parâmetros

`object`
  Somente no estilo procedural: Um objeto DateTime retornado por date_create(). A função modifica este objeto.
`year`

  Ano da data.

`week`

  Semana da data.

`dayOfWeek`

  Diferença do primeiro dia da semana.

### Valor Retornado

Retorna o objeto DateTime modificado para encadeamento de métodos.

### Veja Também

- DateTimeImmutable::setISODate() - Define a data ISO

# DateTime::setMicrosecond

(PHP 8 >= 8.4.0)

DateTime::setMicrosecond — Define a parte de microssegundos do horário

### Descrição

public function DateTime::setMicrosecond(int `$microsecond`): static

Define a parte de microssegundos do horário.

Funciona como em DateTimeImmutable::setMicrosecond(), porém com DateTime.

### Parâmetros

`microsecond`
  O valor de microssegundos a ser definido (`0` a `999999`).

### Valor Retornado

Retorna o objeto DateTime modificado para encadeamento de métodos.

### Erros/Exceções

Se `microsecond` estiver fora do intervalo [`0`, `999999`], uma DateRangeError é lançada.

### Exemplos

Exemplo #1 Exemplo de DateTime::setMicrosecond()

    <?php
    $date = DateTime::createFromTimestamp(123.456789);
    echo $date->format('Y-m-d H:i:s.u') . PHP_EOL;
    $date->setMicrosecond(987654);
    echo $date->format('Y-m-d H:i:s.u') . PHP_EOL;
    ?>

O exemplo acima produzirá:

    1970-01-01 00:02:03.456789
    1970-01-01 00:02:03.987654

### Veja Também

- DateTimeInterface::getMicrosecond() - Obtém a parte de microssegundos do timestamp Unix

# DateTime::setTime

# date_time_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setTime -- date_time_set — Define o horário

### Descrição

Estilo orientado a objetos

public function DateTime::setTime(
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTime

Estilo procedural

function date_time_set(
DateTime `$object`,
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTime

Redefine o horário atual do objeto DateTime para um diferente.

Equivalente a DateTimeImmutable::setTime() mas funciona com DateTime.

A versão procedural usa o objeto DateTime como seu primeiro argumento.

### Parâmetros

`object`
  Somente no estilo procedural: Um objeto DateTime retornado por date_create(). A função modifica este objeto.
`hour`

  Horas do horário.

`minute`

  Minutos do horário.

`second`

  Segundos do horário.

`microsecond`

  Microssegundos do horário.

### Valor Retornado

Retorna o objeto DateTime modificado para encadeamento de métodos.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O comportamento com duplicidade de horários existentes (durante um retorno de horário de verão) mudou. Anteriormente, o PHP pegaria a segunda ocorrência (depois do retorno do horário de verão), em vez da primeira ocorrência (antes do retorno do horário de verão).
7.1.0 | O parâmetro `microsecond` foi adicionado.

### Veja Também

- DateTimeImmutable::setTime() - Define um horário

# DateTime::setTimestamp

# date_timestamp_set

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::setTimestamp -- date_timestamp_set — Define a data e hora baseada em um timestamp Unix

### Descrição

Estilo orientado a objetos

public function DateTime::setTimestamp(int `$timestamp`): DateTime

Estilo procedural

function date_timestamp_set(DateTime `$object`, int `$timestamp`): DateTime

Define a data e hora baseada em um timestamp Unix.

Equivalente a DateTimeImmutable::setTimestamp() mas funciona com DateTime.

A versão procedural usa o objeto DateTime como seu primeiro argumento.

### Parâmetros

`object`
  Somente no estilo procedural: Um objeto DateTime retornado por date_create(). A função modifica este objeto.
`timestamp`

  Timestam Unix representando a data. Configurar o timestamp fora dos limites de int é possível utilizando o método DateTimeImmutable::modify() com o formato `@`.

### Valor Retornado

Retorna o objeto DateTime modificado para encadeamento de métodos.

### Veja Também

- DateTimeImmutable::setTimestamp() - Define a data e o horário com base em um timestamp Unix
- DateTime::setMicrosecond() - Define a parte de microssegundos do horário

# DateTime::setTimezone

# date_timezone_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setTimezone -- date_timezone_set — Define o fuso horário de um objeto DateTime

### Descrição

Estilo orientado a objetos

public function DateTime::setTimezone(DateTimeZone `$timezone`): DateTime

Estilo procedural

function date_timezone_set(DateTime `$object`, DateTimeZone `$timezone`): DateTime

Define um novo fuso horário a um objeto (object) DateTime.

Equivalente a DateTimeImmutable::setTimezone() mas funciona com DateTime.

A versão procedural usa o objeto DateTime como seu primeiro argumento.

### Parâmetros

`object`
  Somente no estilo procedural: Um objeto DateTime retornado por date_create(). A função modifica este objeto.
`timezone`

  Um objeto DateTimeZone que representa o fuso horário desejado.

### Valor Retornado

Retorna o objeto da classe DateTime para ligação de métodos. O ponto no tempo subjacente não é modificado quando este método é chamado.

### Exemplos

Exemplo #1 Exemplo do método DateTime::setTimeZone()

Estilo orientado a objetos

    <?php
    $date = new DateTime('2000-01-01', new DateTimeZone('Pacific/Nauru'));
    echo $date->format('Y-m-d H:i:sP') . "\n";

    $date->setTimezone(new DateTimeZone('Pacific/Chatham'));
    echo $date->format('Y-m-d H:i:sP') . "\n";

O exemplo acima produzirá:

    2000-01-01 00:00:00+12:00
    2000-01-01 01:45:00+13:45

Estilo procedural

    <?php
    $date = date_create('2000-01-01', timezone_open('Pacific/Nauru'));
    echo date_format($date, 'Y-m-d H:i:sP') . "\n";

    date_timezone_set($date, timezone_open('Pacific/Chatham'));
    echo date_format($date, 'Y-m-d H:i:sP') . "\n";

O exemplo acima produzirá:

    2000-01-01 00:00:00+12:00
    2000-01-01 01:45:00+13:45

### Veja Também

- DateTimeImmutable::setTimezone() - Define o fuso horário
- DateTime::getTimezone() - Retorna o fuso horário correspondente a um DateTime informado
- DateTimeZone::__construct() - Cria um novo objeto DateTimeZone

# DateTime::sub

# date_sub

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::sub -- date_sub — Subtrai uma quantidade de dias, meses, anos, horas, minutos e segundos de um objeto DateTime

### Descrição

Estilo orientado a objetos

public function DateTime::sub(DateInterval `$interval`): DateTime

Estilo procedural

function date_sub(DateTime `$object`, DateInterval `$interval`): DateTime

Modifica o objeto DateTime especificado, subtraindo o objeto DateInterval especificado.

Equivalente a DateTimeImmutable::sub() mas funciona com DateTime.

A versão procedural usa o objeto DateTime como seu primeiro argumento.

### Parâmetros

`object`
  Somente no estilo procedural: Um objeto DateTime retornado por date_create(). A função modifica este objeto.
`interval`

  Um objeto DateInterval

### Valor Retornado

Retorna o objeto DateTime modificado para encadeamento de métodos.

### Erros/Exceções

Apenas para API orientada a objetos: Se uma operação não suportada for realizada, como o uso de um objeto DateInterval representando especificações de tempo relativo tipo `next weekday`, uma exceção DateInvalidOperationException é lançada.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Agora lança uma exceção DateInvalidOperationException com DateTime::sub(), em vez de um alerta quando uma operação não suportada é realizada. A função date_sub() não foi alterada.

### Veja Também

- DateTimeImmutable::sub() - Subtrai uma quantidade de dias, meses, anos, horas, minutos e segundos

## Índice

- DateTime::add — Modifica um objeto DateTime, com adição de dias, meses, anos, horas, minutos e segundos.
- DateTime::__construct — Retorna um novo objeto DateTime
- DateTime::createFromFormat — Interpreta um string de data/horário de acordo com um formato especificado.
- DateTime::createFromImmutable — Retorna uma nova instância de DateTime encapsulando o objeto DateTimeImmutable informado
- DateTime::createFromInterface — Retorna um novo objeto DateTime encapsulando o objeto DateTimeInterface informado
- DateTime::createFromTimestamp — Cria uma instância a partir de um timestamp Unix
- DateTime::getLastErrors — Sinônimo de DateTimeImmutable::getLastErrors
- DateTime::modify — Altera o timestamp
- DateTime::__set_state — O manipulador __set_state
- DateTime::setDate — Define a data
- DateTime::setISODate — Define uma data ISO
- DateTime::setMicrosecond — Define a parte de microssegundos do horário
- DateTime::setTime — Define o horário
- DateTime::setTimestamp — Define a data e hora baseada em um timestamp Unix
- DateTime::setTimezone — Define o fuso horário de um objeto DateTime
- DateTime::sub — Subtrai uma quantidade de dias, meses, anos, horas, minutos e segundos de um objeto DateTime

# A classe DateTimeImmutable

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introdução

Representação de data e hora.

Esta classe se comporta como a classe DateTime exceto pelo fato de que novos objetos são retornados quando métodos de modificação como DateTime::modify() são chamados.

## Resumo da classe

class DateTimeImmutable implements DateTimeInterface {
/* Constantes herdadas */
public const string DateTimeInterface::ATOM = "Y-m-d\\TH:i:sP";
public const string DateTimeInterface::COOKIE = "l, d-M-Y H:i:s T";
public const string DateTimeInterface::ISO8601 = "Y-m-d\\TH:i:sO";
public const string DateTimeInterface::ISO8601_EXPANDED = "X-m-d\\TH:i:sP";
public const string DateTimeInterface::RFC822 = "D, d M y H:i:s O";
public const string DateTimeInterface::RFC850 = "l, d-M-y H:i:s T";
public const string DateTimeInterface::RFC1036 = "D, d M y H:i:s O";
public const string DateTimeInterface::RFC1123 = "D, d M Y H:i:s O";
public const string DateTimeInterface::RFC7231 = "D, d M Y H:i:s \\G\\M\\T";
public const string DateTimeInterface::RFC2822 = "D, d M Y H:i:s O";
public const string DateTimeInterface::RFC3339 = "Y-m-d\\TH:i:sP";
public const string DateTimeInterface::RFC3339_EXTENDED = "Y-m-d\\TH:i:s.vP";
public const string DateTimeInterface::RSS = "D, d M Y H:i:s O";
public const string DateTimeInterface::W3C = "Y-m-d\\TH:i:sP";
/* Métodos */
public function __construct(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`)
#[\NoDiscard(message: "as DateTimeImmutable::add() does not modify the object itself")]
public function add(DateInterval `$interval`): DateTimeImmutable
public static function createFromFormat(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = null): DateTimeImmutable|false
public static function createFromInterface(DateTimeInterface `$object`): DateTimeImmutable
public static function createFromMutable(DateTime `$object`): static
public static function createFromTimestamp(int|float `$timestamp`): static
public static function getLastErrors(): array|false
#[\NoDiscard(message: "as DateTimeImmutable::modify() does not modify the object itself")]
public function modify(string `$modifier`): DateTimeImmutable
public static function __set_state(array `$array`): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setDate() does not modify the object itself")]
public function setDate(int `$year`, int `$month`, int `$day`): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setISODate() does not modify the object itself")]
public function setISODate(int `$year`, int `$week`, int `$dayOfWeek` = 1): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setMicrosecond() does not modify the object itself")]
public function setMicrosecond(int `$microsecond`): static
#[\NoDiscard(message: "as DateTimeImmutable::setTime() does not modify the object itself")]
public function setTime(
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setTimestamp() does not modify the object itself")]
public function setTimestamp(int `$timestamp`): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setTimezone() does not modify the object itself")]
public function setTimezone(DateTimeZone `$timezone`): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::sub() does not modify the object itself")]
public function sub(DateInterval `$interval`): DateTimeImmutable
public function diff(DateTimeInterface `$targetObject`, bool `$absolute` = false): DateInterval
public function format(string `$format`): string
public function getMicrosecond(): int
public function getOffset(): int
public function getTimestamp(): int
public function getTimezone(): DateTimeZone|false
public function __serialize(): array
public function __unserialize(array `$data`): void
#[\Deprecated]
public function __wakeup(): void
}

## Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | As constantes de classe agora são tipadas.
7.1.0 | O construtor da classe DateTimeImmutable agora inclui os microssegundos atuais no valor construído. Antes disso, ele iria sempre inicializar os microssegundos em `0`.

# DateTimeImmutable::add

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::add — Retorna um novo objeto, com adição de dias, meses, anos, horas, minutos e segundos

### Descrição

#[\NoDiscard(message: "as DateTimeImmutable::add() does not modify the object itself")]
public function DateTimeImmutable::add(DateInterval `$interval`): DateTimeImmutable

Cria um novo objeto DateTimeImmutable, e adiciona o objeto DateInterval a ele, para representar o novo valor.

### Parâmetros

`interval`

  Um objeto DateInterval

### Valor Retornado

Retorna um novo objeto DateTimeImmutable com os dados modificados.

### Exemplos

Exemplo #1 Exemplo da função DateTimeImmutable::add()

Estilo orientado a objetos

    <?php
    $date = new DateTimeImmutable('2000-01-01');
    $newDate = $date->add(new DateInterval('P10D'));
    echo $newDate->format('Y-m-d') . "\n";
    ?>

Exemplo #2 Mais exemplos da função DateTimeImmutable::add()

    <?php
    $date = new DateTimeImmutable('2000-01-01');
    $newDate = $date->add(new DateInterval('PT10H30S'));
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $date = new DateTimeImmutable('2000-01-01');
    $newDate = $date->add(new DateInterval('P7Y5M4DT4H3M2S'));
    echo $newDate->format('Y-m-d H:i:s') . "\n";
    ?>

O exemplo acima produzirá:

    2000-01-01 10:00:30
    2007-06-05 04:03:02

Exemplo #3 Cuidado ao adicionar meses

    <?php
    $date = new DateTimeImmutable('2000-12-31');
    $interval = new DateInterval('P1M');

    $newDate1 = $date->add($interval);
    echo $newDate1->format('Y-m-d') . "\n";

    $newDate2 = $newDate1->add($interval);
    echo $newDate2->format('Y-m-d') . "\n";
    ?>

O exemplo acima produzirá:

    2001-01-31
    2001-03-03

### Veja Também

- DateTimeImmutable::sub() - Subtrai uma quantidade de dias, meses, anos, horas, minutos e segundos
- DateTimeImmutable::diff() - Retorna a diferença entre dois objetos DateTime
- DateTimeImmutable::modify() - Cria um novo objeto com seu timestamp modificado

# DateTimeImmutable::__construct

# date_create_immutable

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::__construct -- date_create_immutable — Retorna um novo objeto DateTimeImmutable

### Descrição

Estilo orientado a objetos

public function DateTimeImmutable::__construct(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`)

Estilo procedural

function date_create_immutable(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`): DateTimeImmutable|false

Retorna um novo objeto DateTimeImmutable.

### Parâmetros

`datetime`

  Uma string de data/hora. Os formatos válidos são explicados em Formatos de Data e Hora.

  Utilize `"now"` para obter o horário atual quando usar o parâmetro`$timezone`.

`timezone`

  Um objeto DateTimeZone representando o fuso horário do parâmetro `$datetime`.

  Se `$timezone` for `null` ou omitido, o fuso horário atual será utilizado.

  > Nota:

  > O parâmetro `$timezone` e o fuso horário atual são ignorados quando o parâmetro `$datetime` for um timestamp UNIX (ex.: `@946684800`) ou especificar um fuso horário (ex.: `2010-01-28T15:00:00+02:00` ou `2010-07-05T06:00:00Z`).

### Valor Retornado

Retorna uma nova instância de DateTimeImmutable.

### Erros/Exceções

Se um string inválido de data/horário for passado, uma exceção DateMalformedStringException é disparada. Antes do PHP 8.3, era Exception.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Agora dispara DateMalformedStringException se uma string inválida for passada, em vez de Exception.
7.1.0 | De agora em diante os microssegundos são preenchidos com o valor real. Não mais com '00000'.

### Exemplos

Exemplo #1 Exemplo da função DateTimeImmutable::__construct()

Estilo orientado a objetos

    <?php
    try {
        $date = new DateTimeImmutable('2000-01-01');
    } catch (Exception $e) {
        echo $e->getMessage();
        exit(1);
    }

    echo $date->format('Y-m-d');

O exemplo acima produzirá:

    2000-01-01

Estilo procedural

    <?php
    $date = date_create('2000-01-01');
    if (!$date) {
        $e = date_get_last_errors();
        foreach ($e['errors'] as $error) {
            echo "$error\n";
        }
        exit(1);
    }

    echo date_format($date, 'Y-m-d');

O exemplo acima produzirá:

    2000-01-01

Exemplo #2 Complexidades de DateTimeImmutable::__construct()

    <?php
    date_default_timezone_set('America/Jamaica');

    // Data/horário especificados no fuso horário padrão do PHP.
    $date = new DateTimeImmutable('2000-01-01');
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // Data/horário especificados no fuso horário informado.
    $date = new DateTimeImmutable('2000-01-01', new DateTimeZone('Pacific/Nauru'));
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // Data/horário atual no fuso horário padrão do PHP.
    $date = new DateTimeImmutable();
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // Data/horário atual no fuso horário informado.
    $date = new DateTimeImmutable('now', new DateTimeZone('Pacific/Nauru'));
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // Usando um timestamp UNIX. Note que o resultado é no fuso horário UTC.
    $date = new DateTimeImmutable('@946684800');
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // Valores não existentes são transferidos.
    $date = new DateTimeImmutable('2000-02-30');
    echo $date->format('Y-m-d H:i:sP') . "\n";

O exemplo acima produzirá algo semelhante a:

    2000-01-01 00:00:00-05:00
    2000-01-01 00:00:00+12:00
    2010-04-24 10:24:16-04:00
    2010-04-25 02:24:16+12:00
    2000-01-01 00:00:00+00:00
    2000-03-01 00:00:00-05:00

> Nota:

> Datas transferidas podem ser detectadas através da verificação de avisos usando DateTimeImmutable::getLastErrors().

Exemplo #3 Mudando o fuso horário associado

    <?php
    $timeZone = new \DateTimeZone('Asia/Tokyo');

    $time = new \DateTimeImmutable();
    $time = $time->setTimezone($timeZone);

    echo $time->format('Y/m/d H:i:s e'), "\n";

O exemplo acima produzirá algo semelhante a:

    2022/08/12 23:49:23 Asia/Tokyo

Exemplo #4 Usando uma string relativo de data/horário

    <?php
    $time = new \DateTimeImmutable("-1 year");

    echo $time->format('Y/m/d H:i:s'), "\n";

O exemplo acima produzirá algo semelhante a:

    2021/08/12 15:43:51

# DateTimeImmutable::createFromFormat

# date_create_immutable_from_format

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::createFromFormat -- date_create_immutable_from_format — Interpreta um string de data/horário de acordo com o formato especificado

### Descrição

Estilo orientado a objetos

public static function DateTimeImmutable::createFromFormat(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTimeImmutable|false

Estilo procedural

function date_create_immutable_from_format(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTimeImmutable|false

Retorna um novo objeto DateTimeImmutable representando a data e o horário especificados pelo string `datetime`, formatado pelo parâmetro `format`.

### Parâmetros

`format`

  O formato no qual a string passada deve estar. Veja as opções de formatação abaixo. Na maioria dos casos, as mesmas letras da função date() podem ser usadas.

  Todos os campos são inicializados com a data/horário atual. Na maioria das vezes, a intenção pode ser "zerá-los" (época Unix, `1970-01-01 00:00:00 UTC`). Isto pode ser feito incluindo o caractere `!` como o primeiro no parâmetro `format`, ou `|` como o último. Favor verificar a documentação para cada caractere abaixo para mais informação.

  O formato é analisado da esquerda para a direita, o que significa que em algumas situações a ordem na qual os caracteres de formato estão presents afeta o resultado. No caso de `z` (o dia do ano), é necessário que um ano já tenha sido analisado, por exemplo através dos caracteres `Y` ou `y`.

  Letras que são usadas para representar números permitem uma ampla gama de valores, fora do que seria a faixa lógica. Por exemplo, a letra `d` (dia do mês) aceita valores na faixa de `00` a `99`. A única restrição é o número de dígitos. O mecanismo de overflow do analisador é usado quando valores fora da faixa são especificados. Os exemplos abaixo mostram alguns destes comportamentos.

  Isto também significa que os dados analisados para um caractere de formatação são ambiciosos, e irão ler até a quantidade de dígitos que o formato permite. Isto pode também então significar que não há mais caracteres suficientes na string do parâmetro `datetime` para os caracteres de formato seguintes. Um exemplo nesta página também ilustra este problema.

  Os seguintes caracteres são reconhecidos na string do parâmetros `format`
  Caractere de `format` | Descrição | Exemplo de valores analisáveis
  --- | --- | ---
  Dia | --- | ---
  `d` e `j` | Dia do mês, 2 dígitos com ou sem zeros na frente | `01` a `31` ou `1` a `31`. (números de 2 dígitos maiores queo número de dias no mês são aceitos, e neste caso irão causar uma transferência no mês. Por exemplo, usar 33 com janeiro, significa 2 de fevereiro)
  `D` e `l` | Uma representação textual de um dia | `Mon` a `Sun` ou `Sunday` a `Saturday`. Se o nome do dia informado for diferente do nome do dia pertencente a uma data analisada (ou data padrão), então uma transferência ocorre para a próxima data com o nome do dia informado. Veja os exemplos abaixo para uma explicação.
  `S` | Sufixo em inglês para o ordinal do dia do mês, 2 caracteres. É ignorado durante o processamento. | `st`, `nd`, `rd` ou `th`.
  `z` | O dia do ano (iniciando em 0); deve ser precedido de `Y` ou `y`. | `0` a `365`. (números de 3 dígitos maiores que o número de dias em um ano são aceitos, e neste caso case irão causar uma transferência de ano. Por exemplo, usar 366 com 2022, significa 2 de janeiro de 2023)
  Mês | --- | ---
  `F` e `M` | Uma representação textual do mês, como January ou Sept | `January` a `December` ou `Jan` a `Dec`
  `m` e `n` | Representação numérica de um mês, com ou sem zeros na frente | `01` a `12` ou `1` a `12`. (números de 2 dígitos maiores que 12 são aceitos, e neste caso eles irão causar uma transferência de ano. Por exemplo, usar 13 significa janeiro do ano seguinte)
  Ano | --- | ---
  `X` e `x` | Uma representação numérica completa de um ano, com até 19 dígitos, opcionalmente prefixada por `+` ou `-` | Exemplos: `0055`, `787`, `1999`, `-2003`, `+10191`
  `Y` | Uma representação numérica completa de um ano, com até 4 dígitos | Exemplos: `25` (o mesmo que `0025`), `787`, `1999`, `2003`
  `y` | Uma representação de dois dígitos de um ano (que assume-se estar na faixa 1970-2069, inclusive) | Exemplos: `99` ou `03` (que será interpretado como `1999` e `2003`, respectivamente)
  Horário | --- | ---
  `a` e `A` | Ante meridiem e Post meridiem | `am` ou `pm`
  `g` e `h` | Formato de 12 horas para uma hora com ou sem zeros na frente | `1` a `12` ou `01` a `12` (números de 2 dígitos maiores que 12 são aceitos, e neste caso eles irão causar uma transferência de período AM/PM. Por exemplo, usar `14` significa `02` no próximo período AM/PM)
  `G` e `H` | Formato de 24 horas para uma hora com ou sem zeros na frente | `0` a `23` ou `00` a `23` (números de 2 dígitos maiores que 24 são aceitos, e neste caso eles irão causar uma transferência de dia. Por exemplo, usar `26` significa `02:00` do dia seguinte)
  `i` | Minutos com zero na frente | `00` a `59`. (números de 2 dígitos maiores que 59 são aceitos, e neste caso irão causar uma transferência de hora. Por exemplo, usar `66` significa `:06` da hora seguinte)
  `s` | Segundos, com zero na frente | `00` a `59` (números de 2 dígitos maiores que 59 são aceitos, e neste caso irão causar uma transferência de minuto. Por exemplo, usar `90` significa `:30` do próximo minuto)
  `v` | Fração em milissegundos (até três dígitos) | Exemplo: `12` (`0.12` segundo), `345` (`0.345` segundo)
  `u` | Fração em microssegundos (até seis dígitos) | Exemplo: `45` (`0.45` segundo) `654321` (`0.654321` segundo)
  Fuso horário | --- | ---
  `e`, `O`, `p`, `P` e `T` | Identificador do fuso horário, ou a diferença para UTC em horas, ou a diferença para UTC com dois pontos entre horas e minutos, ou abreviação do fuso horário | Exemplos: `UTC`, `GMT`, `Atlantic/Azores` ou `+0200` ou `+02:00` ou `EST`, `MDT`
  Data/Horário completos | --- | ---
  `U` | Segundos desde a Época Unix (1 janeiro 1970 00:00:00 GMT) | Exemplo: `1292177455`
  Espaços em branco e separadores | --- | ---
  `` (espaço) | Zero ou mais espaços, tabulações, caracteres NBSP (U+A0), ou NNBSP (U+202F) | Exemplo: `"\t"`, `" "`
  `#` | Um dos símbolos de separação: `;`, `:`, `/`, `.`, `,`, `-`, `(` ou `)` | Exemplo: `/`
  `;`, `:`, `/`, `.`, `,`, `-`, `(` ou `)` | O caractere especificado. | Exemplo: `-`
  `?` | Um byte aleatório | Exemplo: `^` (Esteja ciente que para caracteres UTF-8 pode ser necessário mais de um `?`. Neste caso, usar `*` pode ser o o mais adequado na verdade)
  `*` | Bytes aleatórios até o próximo separador ou dígito | Exemplo: `*` em `Y-*-d` com o string `2009-aWord-08` será equivalente a `aWord`
  `!` | Reconfigura todos os campos (ano, mês, dia, hora, minuto, segundo, fração e informação de fuso horário) com valores tipo zero ( `0` para hora, minuto, segundo e fração, `1` para mês e dia, `1970` para ano e o fuso horário padrão) | Sem `!,` todos os campos serão configurados com a data/horário atual.
  `|` | Reconfigura todos os campos (ano, mês, dia, hora, minuto, segundo, fração e informação de fuso horário) com valores tipo zero se eles ainda não foram analisados | `Y-m-d|` irá configurar o ano, mês e dia para as informações encontradas na string a ser analisada, e configura a hora, minuto e segundo para 0.
  `+` | Se esta especificação de formato estiver presente, dados no final da string não irão causar um erro, mas sim um aviso | Use DateTimeImmutable::getLastErrors() para descobrir se dados no final da string estavam presentes.

  Caracteres não reconhecidos na string de formatação irão causar falha na análise e uma mensagem de erro será anexada na estrutura retornada. É possível recuperar a mensagem de erro com DateTimeImmutable::getLastErrors().

  Para incluir caracteres literais no parâmetro `format`, deve-se usar a barra invertida (`\`) antes deles.

  Se `format` não contiver o caractere `!` então partes da data/horário gerada que não foram especificadas em `format` serão configuradas para a data/horário atual do sistema.

  Se `format` contiver o caractere `!`, então partes da data/horário gerada não especificada em `format`, assim como valores à esquerda de `!`, serão configuradas aos valores correspondentes da época Unix.

  Se algum caractere de horário for analisado, então todos os outros campos relacionados a horário são configurados para "0", a menos que também tenham sido analisados.

  A Época Unix é 1970-01-01 00:00:00 UTC.

`datetime`

  String representando a data/horário.

`timezone`

  Um objeto DateTimeZone representando o fuso horário desejado.

  Se `timezone` for `null` ou omitido e `datetime` não contém o fuso horário, o fuso atual será usado.

  > Nota:

  > O parâmetro `timezone` e o fuso horário atual são ignorados quando o parâmetro `datetime` contém um timestamp UNIX (ex.: `946684800`) ou especifica um fuso horário (ex.: `2010-01-28T15:00:00+02:00`).

### Valor Retornado

Retorna uma nova instância de DateTimeImmutable ou `false` em caso de falha.

### Erros/Exceções

Este método lança uma exceção ValueError quando o parâmetro `datetime` contiver bytes nulos.

### Registro de Alterações

Versão | Descrição
--- | ---
8.2.9 | O especificador `` (space) agora também suporta caracteres NBSP (U+A0) e NNBSP (U+202F).
8.2.0 | Os especificadores `X` e `x` de `format` foram adicionados.
8.0.21, 8.1.8, 8.2.0 | Agora lança a exceção ValueError quando bytes nulos são passados no parâmetro `datetime`, o que antes era silenciosamente ignorado.
7.3.0 | O especificador `v` em `format` foi adicionado.

### Exemplos

Exemplo #1 Exemplo de DateTimeImmutable::createFromFormat()

Estilo orientado a objetos

    <?php
    $date = DateTimeImmutable::createFromFormat('j-M-Y', '15-Feb-2009');
    echo $date->format('Y-m-d');

Exemplo #2 Usando constantes predefinidas de formato com DateTimeImmutable::createFromFormat()

Estilo orientado a objetos

    <?php
    $date = DateTimeImmutable::createFromFormat(
        DateTimeInterface::ISO8601,
        '2004-02-12T15:19:21+00:00'
    );
    echo $date->format('c e') . "\n";

    $date = DateTimeImmutable::createFromFormat(
        DateTimeInterface::RFC3339_EXTENDED,
        '2013-10-14T09:00:00.000+02:00'
    );
    echo $date->format('c e') . "\n";

As constantes de formatação como usadas neste exemplo consistem de uma string de caracteres para formatar um objeto DateTimeImmutable. Na maioria dos casos, estas letras são equivalentes aos elementos de data/horário definidos na seção parameters acima, mas elas tendem a ser mais lenientes.

Exemplo #3 Complexidades de DateTimeImmutable::createFromFormat()

    <?php
    echo 'Horário atual: ' . date('Y-m-d H:i:s') . "\n";

    $format = 'Y-m-d';
    $date = DateTimeImmutable::createFromFormat($format, '2009-02-15');
    echo "Formato: $format; " . $date->format('Y-m-d H:i:s') . "\n";

    $format = 'Y-m-d H:i:s';
    $date = DateTimeImmutable::createFromFormat($format, '2009-02-15 15:16:17');
    echo "Formato: $format; " . $date->format('Y-m-d H:i:s') . "\n";

    $format = 'Y-m-!d H:i:s';
    $date = DateTimeImmutable::createFromFormat($format, '2009-02-15 15:16:17');
    echo "Formato: $format; " . $date->format('Y-m-d H:i:s') . "\n";

    $format = '!d';
    $date = DateTimeImmutable::createFromFormat($format, '15');
    echo "Formato: $format; " . $date->format('Y-m-d H:i:s') . "\n";

    $format = 'i';
    $date = DateTimeImmutable::createFromFormat($format, '15');
    echo "Formato: $format; " . $date->format('Y-m-d H:i:s') . "\n";

O exemplo acima produzirá algo semelhante a:

    Horário atual: 2022-06-02 15:50:46
    Formato: Y-m-d; 2009-02-15 15:50:46
    Formato: Y-m-d H:i:s; 2009-02-15 15:16:17
    Formato: Y-m-!d H:i:s; 1970-01-15 15:16:17
    Formato: !d; 1970-01-15 00:00:00
    Formato: i; 2022-06-02 00:15:00

Exemplo #4 String de formatação com caracteres literais

    <?php
    echo DateTimeImmutable::createFromFormat('H\h i\m s\s','23h 15m 03s')->format('H:i:s');

O exemplo acima produzirá algo semelhante a:

    23:15:03

Exemplo #5 Comportamento de transferência

    <?php
    echo DateTimeImmutable::createFromFormat('Y-m-d H:i:s', '2021-17-35 16:60:97')->format(DateTimeImmutable::RFC2822);

O exemplo acima produzirá algo semelhante a:

    Sat, 04 Jun 2022 17:01:37 +0000

Embora o resultado pareça estranho, ele está correto, já que as transferências abaixo ocorrem:

1. `97` segundos transferem para `1` minuto, sobrando `37` segundos.
2. `61` minutos transferem para `1` hora, sobrando `1` minuto.
3. `35` dias transferem para `1` mês, sobrando `4` dias. A quantidade de dias que sobram depende do mês, já que nem todo mês tem o mesmo número de dias.
4. `18` meses transferem para `1` ano, sobrando `6` meses.

Exemplo #6 Comportamento de transferência do nome do dia

    <?php
    $d = DateTime::createFromFormat(DateTimeInterface::RFC1123, 'Mon, 3 Aug 2020 25:00:00 +0000');
    echo $d->format(DateTime::RFC1123), "\n";

O exemplo acima produzirá algo semelhante a:

    Mon, 10 Aug 2020 01:00:00 +0000

Embora o resultado pareça estranho, ele está correto, já que as transferências abaixo ocorrem:

1. `3 Aug 2020 25:00:00` transfere para `(Tue) 4 Aug 2020 01:00`.
2. `Mon` é aplicado, o que avança a data para `Mon, 10 Aug 2020 01:00:00`. A explicação para as palavras-chaves relativas como `Mon` está disponível na seção sobre formatos relativos.

Para detectar transferências em datas/horas, pode-se usar o método DateTimeImmutable::getLastErrors(), que irá incluir um aviso se uma transferência tiver ocorrido.

Exemplo #7 Detectando transferência de datas/horas

    <?php
    $d = DateTimeImmutable::createFromFormat('Y-m-d H:i:s', '2021-17-35 16:60:97');
    echo $d->format(DateTimeImmutable::RFC2822), "\n\n";

    var_dump(DateTimeImmutable::getLastErrors());

O exemplo acima produzirá algo semelhante a:

    Sat, 04 Jun 2022 17:01:37 +0000

    array(4) {
      'warning_count' =>
      int(2)
      'warnings' =>
      array(1) {
        [19] =>
        string(27) "The parsed date was invalid"
      }
      'error_count' =>
      int(0)
      'errors' =>
      array(0) {
      }
    }

Exemplo #8 Comportamento de análise ambicioso

    <?php
    print_r(date_parse_from_format('Gis', '60101'));

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [year] =>
        [month] =>
        [day] =>
        [hour] => 60
        [minute] => 10
        [second] => 0
        [fraction] => 0
        [warning_count] => 1
        [warnings] => Array
            (
                [5] => The parsed time was invalid
            )

        [error_count] => 1
        [errors] => Array
            (
                [4] => A two digit second could not be found
            )

        [is_localtime] =>
    )

O formato `G` analisa horas no formato de 24 horas, com ou sem zeros na frente. Isto requer analisar 1 ou 2 dígitos. Como há dois dígitos disponíveis, o analisador ambiciosamente lê o valor como `60`.

Os caracteres seguintes `i` e `s` ambos requerem dois dígitos. Isto significa que `10` é passado como minutos (`i`), e que não há então dígitos suficientes restantes para serem analisados como segundos (`s`).

O array `errors` indica este problema.

Adicionalmente, um valor de hora de `60` está fora da faixa `0`-`24`, o que faz com que o array de `warnings` inclua um aviso de que o horário é inválido.

### Veja Também

- DateTimeImmutable::__construct() - Retorna um novo objeto DateTimeImmutable
- DateTimeImmutable::getLastErrors() - Retorna os avisos e erros
- checkdate() - Valida uma data gregoriana
- strptime() - Interpreta uma data/horário gerada pela função strftime

# DateTimeImmutable::createFromInterface

(PHP 8)

DateTimeImmutable::createFromInterface — Retorna um novo objeto DateTimeImmutable encapsulando o objeto DateTimeInterface informado

### Descrição

public static function DateTimeImmutable::createFromInterface(DateTimeInterface `$object`): DateTimeImmutable

### Parâmetros

`object`

  O objeto DateTimeInterface que necessita ser convertido para uma versão imutável. Este objeto não é modificado, em vez disso uma nova instância DateTimeImmutable é criada contendo as mesmas informações de data, horário e fuso.

### Valor Retornado

Retorna uma nova instância de DateTimeImmutable.

### Exemplos

Exemplo #1 Criando um objeto de data/horário imutável

    <?php
    $date = new DateTime("2014-06-20 11:45 Europe/London");
    $immutable = DateTimeImmutable::createFromInterface($date);

    $date = new DateTimeImmutable("2014-06-20 11:45 Europe/London");
    $also_immutable = DateTimeImmutable::createFromInterface($date);

# DateTimeImmutable::createFromMutable

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

DateTimeImmutable::createFromMutable — Retorna uma nova instância DateTimeImmutable que encapsula um objeto DateTime informado

### Descrição

public static function DateTimeImmutable::createFromMutable(DateTime `$object`): static

### Parâmetros

`object`

  O objeto mutável DateTime que se deseja converter para uma versão imutável. Este objeto não é modificado, mas em vez disso uma nova instância de DateTimeImmutable é criado contendo a mesma data/horário e informação de fuso horário.

### Valor Retornado

Retorna uma nova instância de DateTimeImmutable.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O método agora retorna uma instância da classe atualmente chamada. Antes, ele criava um nova instância de DateTimeImmutable.

### Exemplos

Exemplo #1 Criando um objeto DateTime imutável

    <?php
    $date = new DateTime("2014-06-20 11:45 Europe/London");
    $immutable = DateTimeImmutable::createFromMutable( $date );

# DateTimeImmutable::createFromTimestamp

(PHP 8 >= 8.4.0)

DateTimeImmutable::createFromTimestamp — Cria uma instância a partir de um timestamp Unix

### Descrição

public static function DateTimeImmutable::createFromTimestamp(int|float `$timestamp`): static

Cria uma instância a partir de um timestamp Unix.

### Parâmetros

`timestamp`
  Timestamp Unix representando a data/horário. Um valor float também é aceito, o que permite precisão de microssegundos.

### Valor Retornado

Retorna uma nova instância de DateTimeImmutable.

### Erros/Exceções

Se `timestamp` estiver fora do intervalo [`PHP_INT_MIN`, `PHP_INT_MAX`], uma DateRangeError é lançada.

### Exemplos

Exemplo #1 Exemplo de DateTimeImmutable::createFromTimestamp()

    <?php
    $date = DateTimeImmutable::createFromTimestamp(123.456789);
    echo $date->format('Y-m-d H:i:s.u');
    ?>

O exemplo acima produzirá:

    1970-01-01 00:02:03.456789

# DateTimeImmutable::getLastErrors

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::getLastErrors — Retorna os avisos e erros

### Descrição

public static function DateTimeImmutable::getLastErrors(): array|false

Retorna um array de avisos e erros encontrados durante a análise de uma string de data/horário.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array contendo informação sobre avisos e erros ou `false` se não houver nem avisos nem erros.

### Registro de Alterações

Versão | Descrição
--- | ---
8.2.0 | Antes do PHP 8.2.0, esta função não retornava `false` quando não havia warnings ou erros. Em vez disso, ela sempre retornaria a estrutura de array documentada.

### Exemplos

Exemplo #1 Exemplo da função DateTimeImmutable::getLastErrors()

    <?php
    try {
        $date = new DateTimeImmutable('asdfasdf');
    } catch (Exception $e) {
        // Apenas para propósito de demonstração...
        print_r(DateTimeImmutable::getLastErrors());

        // A maneira verdadeiramente real orientada a objeto de se fazer isto é
        echo $e->getMessage();
    }
    ?>

O exemplo acima produzirá:

    Array
    (
        [warning_count] => 1
        [warnings] => Array
            (
                [6] => Double timezone specification
            )

        [error_count] => 1
        [errors] => Array
            (
                [0] => The timezone could not be found in the database
            )
    )
    Failed to parse time string (asdfasdf) at position 0 (a): The timezone could not be found in the database

Os índices 6 e 0 na saída do exemplo referem-se ao índice do caractere no string onde o erro ocorreu.

Exemplo #2 Detectando datas transferidas

    <?php
    $date = DateTimeImmutable::createFromFormat('!Y-m-d', '2020-02-30');
    print_r(DateTimeImmutable::getLastErrors());

O exemplo acima produzirá:

    Array
    (
        [warning_count] => 1
        [warnings] => Array
            (
                [10] => The parsed date was invalid
            )

        [error_count] => 0
        [errors] => Array
            (
            )
    )

# DateTimeImmutable::modify

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::modify — Cria um novo objeto com seu timestamp modificado

### Descrição

#[\NoDiscard(message: "as DateTimeImmutable::modify() does not modify the object itself")]
public function DateTimeImmutable::modify(string `$modifier`): DateTimeImmutable

Cria um novo objeto DateTimeImmutable com seu timestamp modificado. O objeto original não é modificado.

### Parâmetros

`modifier`

  Uma string de data/hora. Os formatos válidos são explicados em Formatos de Data e Hora.

### Valor Retornado

Retorna DateTimeImmutable em caso de sucesso. Estilo procedural retorna `false` em caso de falha.

### Erros/Exceções

Se uma string inválida de data/horário for passada, uma exceção DateMalformedStringException é disparada. Antes do PHP 8.3, era um aviso.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Agora tem um tipo de retorno provisório DateTimeImmutable. Anteriormente era DateTimeImmutable|false.
8.3.0 | DateTimeImmutable::modify() agora lança uma exceção DateMalformedStringException se uma string inválida for passada. Anteriormente, retornava `false` e um alerta era emitido.

### Exemplos

Exemplo #1 Exemplo da função DateTimeImmutable::modify()

Estilo orientado a objetos

    <?php
    $date = new DateTimeImmutable('2006-12-12');
    $newDate = $date->modify('+1 day');
    echo $newDate->format('Y-m-d');

O exemplo acima produzirá:

    2006-12-13

Exemplo #2 Cuidado na adição ou subtração de meses

    <?php
    $date = new DateTimeImmutable('2000-12-31');

    $newDate1 = $date->modify('+1 month');
    echo $newDate1->format('Y-m-d') . "\n";

    $newDate2 = $newDate1->modify('+1 month');
    echo $newDate2->format('Y-m-d') . "\n";

O exemplo acima produzirá:

    2001-01-31
    2001-03-03

### Veja Também

- DateTimeImmutable::add() - Retorna um novo objeto, com adição de dias, meses, anos, horas, minutos e segundos
- DateTimeImmutable::sub() - Subtrai uma quantidade de dias, meses, anos, horas, minutos e segundos
- DateTimeImmutable::setDate() - Define a data
- DateTimeImmutable::setISODate() - Define a data ISO
- DateTimeImmutable::setTime() - Define um horário
- DateTimeImmutable::setTimestamp() - Define a data e o horário com base em um timestamp Unix

# DateTimeImmutable::__set_state

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::__set_state — O manipulador __set_state

### Descrição

public static function DateTimeImmutable::__set_state(array `$array`): DateTimeImmutable

O manipulador __set_state().

### Parâmetros

`array`

  Array de inicialização.

### Valor Retornado

Retorna uma nova instância de um objeto DateTimeImmutable.

# DateTimeImmutable::setDate

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setDate — Define a data

### Descrição

#[\NoDiscard(message: "as DateTimeImmutable::setDate() does not modify the object itself")]
public function DateTimeImmutable::setDate(int `$year`, int `$month`, int `$day`): DateTimeImmutable

Retorna um novo objeto DateTimeImmutable com a data atual do objeto DateTimeImmutable configurado com a data fornecida.

### Parâmetros

`object`
  Somente no estilo procedural: Um objeto DateTime retornado por date_create(). A função modifica este objeto.
`year`

  Ano da data.

`month`

  Mês da data.

`day`

  Dia da data.

### Valor Retornado

Retorna um novo objeto DateTimeImmutable com os dados modificados.

### Exemplos

Exemplo #1 Exemplo da função DateTimeImmutable::setDate()

Estilo orientado a objetos

    <?php
    $date = new DateTimeImmutable();
    $newDate = $date->setDate(2001, 2, 3);
    echo $newDate->format('Y-m-d');

O exemplo acima produzirá:

    2001-02-03

Exemplo #2 Valores que excedem os limites são transferidos para a escala imediatamente superior

    <?php
    $date = new DateTimeImmutable();

    $newDate = $date->setDate(2001, 2, 28);
    echo $newDate->format('Y-m-d') . "\n";

    $newDate = $date->setDate(2001, 2, 29);
    echo $newDate->format('Y-m-d') . "\n";

    $newDate = $date->setDate(2001, 14, 3);
    echo $newDate->format('Y-m-d') . "\n";

O exemplo acima produzirá:

    2001-02-28
    2001-03-01
    2002-02-03

### Veja Também

- DateTimeImmutable::setISODate() - Define a data ISO
- DateTimeImmutable::setTime() - Define um horário

# DateTimeImmutable::setISODate

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setISODate — Define a data ISO

### Descrição

#[\NoDiscard(message: "as DateTimeImmutable::setISODate() does not modify the object itself")]
public function DateTimeImmutable::setISODate(int `$year`, int `$week`, int `$dayOfWeek` = 1): DateTimeImmutable

Retorna um novo objeto DateTimeImmutable com a data configurada de acordo com o padrão ISO 8601 - usa semanas e deslocamentos de dias no lugar de datas específicas.

### Parâmetros

`year`

  Ano da data.

`week`

  Semana da data.

`dayOfWeek`

  Posição em relação ao primeiro dia da semana.

### Valor Retornado

Retorna um novo objeto DateTimeImmutable com os dados modificados.

### Exemplos

Exemplo #1 Exemplo da função DateTimeImmutable::setISODate()

Estilo orientado a objetos

    <?php

    $date = new DateTimeImmutable();

    $newDate = $date->setISODate(2008, 2);
    echo $newDate->format('Y-m-d') . "\n";

    $newDate = $date->setISODate(2008, 2, 7);
    echo $newDate->format('Y-m-d') . "\n";

O exemplo acima produzirá:

    2008-01-07
    2008-01-13

Estilo procedural

    <?php

    $date = date_create();

    date_isodate_set($date, 2008, 2);
    echo date_format($date, 'Y-m-d') . "\n";

    date_isodate_set($date, 2008, 2, 7);
    echo date_format($date, 'Y-m-d') . "\n";

O exemplo acima produzirá:

    2008-01-07
    2008-01-13

Exemplo #2 Valores que excedem os limites são transferidos para a escala imediatamente superior

    <?php

    $date = new DateTimeImmutable();

    $newDate = $date->setISODate(2008, 2, 7);
    echo $newDate->format('Y-m-d') . "\n";

    $newDate = $date->setISODate(2008, 2, 8);
    echo $newDate->format('Y-m-d') . "\n";

    $newDate = $date->setISODate(2008, 53, 7);
    echo $newDate->format('Y-m-d') . "\n";

O exemplo acima produzirá:

    2008-01-13
    2008-01-14
    2009-01-04

Exemplo #3 Para encontrar o mês em que uma semana se localiza

    <?php

    $date = new DateTimeImmutable();
    $newDate = $date->setISODate(2008, 14);
    echo $newDate->format('n');

O exemplo acima produzirá:

    3

### Veja Também

- DateTimeImmutable::setDate() - Define a data
- DateTimeImmutable::setTime() - Define um horário

# DateTimeImmutable::setMicrosecond

(PHP 8 >= 8.4.0)

DateTimeImmutable::setMicrosecond — Define a parte de microssegundos do horário

### Descrição

#[\NoDiscard(message: "as DateTimeImmutable::setMicrosecond() does not modify the object itself")]
public function DateTimeImmutable::setMicrosecond(int `$microsecond`): static

Retorna um novo objeto DateTimeImmutable construído a partir do antigo, com a parte de microssegundos modificada.

### Parâmetros

`microsecond`
  O valor de microssegundos a ser definido (`0` to `999999`).

### Valor Retornado

Retorna um novo objeto DateTimeImmutable com os dados modificados.

### Erros/Exceções

Se `microsecond` estiver fora do intervalo [`0`, `999999`], uma DateRangeError é lançada.

### Exemplos

Exemplo #1 Exemplo de DateTimeImmutable::setMicrosecond()

    <?php
    $date = DateTimeImmutable::createFromTimestamp(123.456789);
    echo $date->format('Y-m-d H:i:s.u') . PHP_EOL;
    $date = $date->setMicrosecond(987654);
    echo $date->format('Y-m-d H:i:s.u') . PHP_EOL;
    ?>

O exemplo acima produzirá:

    1970-01-01 00:02:03.456789
    1970-01-01 00:02:03.987654

### Veja Também

- DateTimeInterface::getMicrosecond() - Obtém a parte de microssegundos do timestamp Unix

# DateTimeImmutable::setTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setTime — Define um horário

### Descrição

#[\NoDiscard(message: "as DateTimeImmutable::setTime() does not modify the object itself")]
public function DateTimeImmutable::setTime(
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTimeImmutable

Retorna um novo objeto DateTimeImmutable configurado com o horário fornecido.

### Parâmetros

`hour`

  Hora do horário.

`minute`

  Minuto do horário.

`second`

  Segundo do horário.

`microsecond`

  Microssegundo do horário.

### Valor Retornado

Retorna um novo objeto DateTimeImmutable com os dados modificados.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O comportamento com horários que podem ter duplicidade (durante o retorno do horário de verão) mudou. Anteriormente, o PHP usaria a segunda ocorrência do horário (depois do retorno do horário de verão), em vez da primeira ocorrência (antes do retorno).
7.1.0 | O parâmetro `microsecond` foi incluído.

### Exemplos

Exemplo #1 Exemplo da função DateTimeImmutable::setTime()

Estilo orientado a objetos

    <?php
    $date = new DateTimeImmutable('2001-01-01');

    $newDate = $date->setTime(14, 55);
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $newDate = $date->setTime(14, 55, 24);
    echo $newDate->format('Y-m-d H:i:s') . "\n";
    ?>

O exemplo acima produzirá algo semelhante a:

    2001-01-01 14:55:00
    2001-01-01 14:55:24

Exemplo #2 Valores que excedem os limites são transferidos para a escala imediatamente superior

    <?php
    $date = new DateTimeImmutable('2001-01-01');

    $newDate = $date->setTime(14, 55, 24);
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $newDate = $date->setTime(14, 55, 65);
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $newDate = $date->setTime(14, 65, 24);
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $newDate = $date->setTime(25, 55, 24);
    echo $newDate->format('Y-m-d H:i:s') . "\n";
    ?>

O exemplo acima produzirá:

    2001-01-01 14:55:24
    2001-01-01 14:56:05
    2001-01-01 15:05:24
    2001-01-02 01:55:24

### Veja Também

- DateTimeImmutable::setDate() - Define a data
- DateTimeImmutable::setISODate() - Define a data ISO

# DateTimeImmutable::setTimestamp

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setTimestamp — Define a data e o horário com base em um timestamp Unix

### Descrição

#[\NoDiscard(message: "as DateTimeImmutable::setTimestamp() does not modify the object itself")]
public function DateTimeImmutable::setTimestamp(int `$timestamp`): DateTimeImmutable

Retorna um novo objeto DateTimeImmutable construído a partir do antigo, com a data e o horário configurados com base em um timestamp Unix.

### Parâmetros

`timestamp`

  Timestamp Unix representando a data e horário. Configurar timestamps fora dos limites de int é possível usando DateTimeImmutable::modify() com o formato `@`.

### Valor Retornado

Retorna um novo objeto DateTimeImmutable com os dados modificados.

### Exemplos

Exemplo #1 Exemplo da função DateTimeImmutable::setTimestamp()

Estilo orientado a objetos

    <?php
    $date = new DateTimeImmutable();
    echo $date->format('U = Y-m-d H:i:s') . "\n";

    $newDate = $date->setTimestamp(1171502725);
    echo $newDate->format('U = Y-m-d H:i:s') . "\n";

O exemplo acima produzirá algo semelhante a:

    1272508903 = 2010-04-28 22:41:43
    1171502725 = 2007-02-14 20:25:25

### Veja Também

- DateTimeImmutable::getTimestamp() - Obtém o timestamp Unix
- DateTimeImmutable::setMicrosecond() - Define a parte de microssegundos do horário

# DateTimeImmutable::setTimezone

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setTimezone — Define o fuso horário

### Descrição

#[\NoDiscard(message: "as DateTimeImmutable::setTimezone() does not modify the object itself")]
public function DateTimeImmutable::setTimezone(DateTimeZone `$timezone`): DateTimeImmutable

Retorna um novo objeto DateTimeImmutable com um novo fuso horário configurado.

### Parâmetros

`timezone`

  Um objeto DateTimeZone representando o fuso horário desejado.

### Valor Retornado

Retorna um novo objeto DateTimeImmutable modificado para ligação de método. O ponto no tempo subjacente não é modificado quando este médoto é chamado.

### Exemplos

Exemplo #1 Exemplo da função DateTimeImmutable::setTimeZone()

Estilo orientado a objetos

    <?php
    $date = new DateTimeImmutable('2000-01-01', new DateTimeZone('Pacific/Nauru'));
    echo $date->format('Y-m-d H:i:sP') . "\n";

    $newDate = $date->setTimezone(new DateTimeZone('Pacific/Chatham'));
    echo $newDate->format('Y-m-d H:i:sP') . "\n";
    ?>

O exemplo acima produzirá:

    2000-01-01 00:00:00+12:00
    2000-01-01 01:45:00+13:45

### Veja Também

- DateTimeImmutable::getTimezone() - Retorna o fuso horário correspondente a um DateTime informado
- DateTimeZone::__construct() - Cria um novo objeto DateTimeZone

# DateTimeImmutable::sub

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::sub — Subtrai uma quantidade de dias, meses, anos, horas, minutos e segundos

### Descrição

#[\NoDiscard(message: "as DateTimeImmutable::sub() does not modify the object itself")]
public function DateTimeImmutable::sub(DateInterval `$interval`): DateTimeImmutable

Retorna um novo objeto DateTimeImmutable, com o objeto DateInterval especificado substraído do objeto DateTimeImmutable original.

### Parâmetros

`interval`

  Um objeto DateInterval

### Valor Retornado

Retorna um novo objeto DateTimeImmutable com os dados modificados.

### Erros/Exceções

Se uma operação não suportada for solicitada, por exemplo usando um objeto DateInterval que representa especificação relativa de tempo como `next weekday`, uma exceção DateInvalidOperationException é lançada.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Agora lança uma exceção DateInvalidOperationException em vez de um aviso quando uma operação não suportada for solicitada.

### Exemplos

Exemplo #1 Exemplo da função DateTimeImmutable::sub()

Estilo orientado a objetos

    <?php
    $date = new DateTimeImmutable('2000-01-20');
    $newDate = $date->sub(new DateInterval('P10D'));
    echo $newDate->format('Y-m-d') . "\n";
    ?>

O exemplo acima produzirá:

    2000-01-10

Exemplo #2 Mais exemplos da função DateTimeImmutable::sub()

    <?php
    $date = new DateTimeImmutable('2000-01-20');
    $newDate = $date->sub(new DateInterval('PT10H30S'));
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $date = new DateTimeImmutable('2000-01-20');
    $newDate = $date->sub(new DateInterval('P7Y5M4DT4H3M2S'));
    echo $newDate->format('Y-m-d H:i:s') . "\n";
    ?>

O exemplo acima produzirá:

    2000-01-19 13:59:30
    1992-08-15 19:56:58

Exemplo #3 Cuidado ao subtrair meses

    <?php
    $date = new DateTimeImmutable('2001-04-30');
    $interval = new DateInterval('P1M');

    $newDate1 = $date->sub($interval);
    echo $newDate1->format('Y-m-d') . "\n";

    $newDate2 = $newDate1->sub($interval);
    echo $newDate2->format('Y-m-d') . "\n";
    ?>

O exemplo acima produzirá:

    2001-03-30
    2001-03-02

### Veja Também

- DateTimeImmutable::add() - Retorna um novo objeto, com adição de dias, meses, anos, horas, minutos e segundos
- DateTimeImmutable::diff() - Retorna a diferença entre dois objetos DateTime
- DateTimeImmutable::modify() - Cria um novo objeto com seu timestamp modificado

## Índice

- DateTimeImmutable::add — Retorna um novo objeto, com adição de dias, meses, anos, horas, minutos e segundos
- DateTimeImmutable::__construct — Retorna um novo objeto DateTimeImmutable
- DateTimeImmutable::createFromFormat — Interpreta um string de data/horário de acordo com o formato especificado
- DateTimeImmutable::createFromInterface — Retorna um novo objeto DateTimeImmutable encapsulando o objeto DateTimeInterface informado
- DateTimeImmutable::createFromMutable — Retorna uma nova instância DateTimeImmutable que encapsula um objeto DateTime informado
- DateTimeImmutable::createFromTimestamp — Cria uma instância a partir de um timestamp Unix
- DateTimeImmutable::getLastErrors — Retorna os avisos e erros
- DateTimeImmutable::modify — Cria um novo objeto com seu timestamp modificado
- DateTimeImmutable::__set_state — O manipulador __set_state
- DateTimeImmutable::setDate — Define a data
- DateTimeImmutable::setISODate — Define a data ISO
- DateTimeImmutable::setMicrosecond — Define a parte de microssegundos do horário
- DateTimeImmutable::setTime — Define um horário
- DateTimeImmutable::setTimestamp — Define a data e o horário com base em um timestamp Unix
- DateTimeImmutable::setTimezone — Define o fuso horário
- DateTimeImmutable::sub — Subtrai uma quantidade de dias, meses, anos, horas, minutos e segundos

# A interface DateTimeInterface

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introdução

DateTimeInterface foi criada para que os parâmetros, variáveis de retorno ou declarações de tipo de propriedades aceitem tanto DateTimeImmutable ou DateTime como um valor. Não é possível implementar esta interface em classes no espaço de usuário.

Constantes comuns que permitem formatar objetos DateTimeImmutable ou DateTime através de DateTimeImmutable::format() e DateTime::format() também são definidas nesta interface.

## Resumo da Interface

interface DateTimeInterface {
/* Constantes */
public const string ATOM = "Y-m-d\\TH:i:sP";
public const string COOKIE = "l, d-M-Y H:i:s T";
public const string ISO8601 = "Y-m-d\\TH:i:sO";
public const string ISO8601_EXPANDED = "X-m-d\\TH:i:sP";
public const string RFC822 = "D, d M y H:i:s O";
public const string RFC850 = "l, d-M-y H:i:s T";
public const string RFC1036 = "D, d M y H:i:s O";
public const string RFC1123 = "D, d M Y H:i:s O";
public const string RFC7231 = "D, d M Y H:i:s \\G\\M\\T";
public const string RFC2822 = "D, d M Y H:i:s O";
public const string RFC3339 = "Y-m-d\\TH:i:sP";
public const string RFC3339_EXTENDED = "Y-m-d\\TH:i:s.vP";
public const string RSS = "D, d M Y H:i:s O";
public const string W3C = "Y-m-d\\TH:i:sP";
/* Métodos */
public function diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval
public function format(string `$format`): string
public function getMicrosecond(): int
public function getOffset(): int
public function getTimestamp(): int
public function getTimezone(): DateTimeZone|false
public function __serialize(): array
public function __unserialize(array `$data`): void
#[\Deprecated]
public function __wakeup(): void
}

## Constantes predefinidas

DateTimeInterface::ATOM string
DATE_ATOM
  Atômico (exemplo: 2005-08-15T15:52:01+00:00); compatível com ISO-8601, RFC 3339 e esquema XML
DateTimeInterface::COOKIE string
DATE_COOKIE
  Cookies HTTP (exemplo: Monday, 15-Aug-2005 15:52:01 UTC)
DateTimeInterface::ISO8601 string
DATE_ISO8601
  Tipo ISO-8601 (exemplo: 2005-08-15T15:52:01+0000)

  > Nota: Este formato não é compatível com a ISO-8601, mas foi deixado assim por motivo de compatibilidade com versões anteriores. Use DateTimeInterface::ISO8601_EXPANDED, DateTimeInterface::ATOM para compatibilidade com a ISO-8601, alternativamente. (ref ISO8601:2004 seção 4.3.3 cláusula d)

DateTimeInterface::ISO8601_EXPANDED string
DATE_ISO8601_EXPANDED
  ISO-8601 Expandida (exemplo: +10191-07-26T08:59:52+01:00)

  > Nota: Este formato permite valores de ano fora do intervalo normal da ISO-8601 de `0000`-`9999` porque sempre inclui um caractere de sinal. Ele também garante que a parte do fuso horário (`+01:00`) seja compatível com a ISO-8601.

DateTimeInterface::RFC822 string
DATE_RFC822
  RFC 822 (exemplo: Mon, 15 Aug 05 15:52:01 +0000)
DateTimeInterface::RFC850 string
DATE_RFC850
  RFC 850 (exemplo: Monday, 15-Aug-05 15:52:01 UTC)
DateTimeInterface::RFC1036 string
DATE_RFC1036
  RFC 1036 (exemplo: Mon, 15 Aug 05 15:52:01 +0000)
DateTimeInterface::RFC1123 string
DATE_RFC1123
  RFC 1123 (exemplo: Mon, 15 Aug 2005 15:52:01 +0000)
DateTimeInterface::RFC7231 string
DATE_RFC7231
  RFC 7231 (desde o PHP 7.0.19 e 7.1.5) (exemplo: Sat, 30 Apr 2016 17:52:13 GMT)
DateTimeInterface::RFC2822 string
DATE_RFC2822
  RFC 2822 (exemplo: Mon, 15 Aug 2005 15:52:01 +0000)
DateTimeInterface::RFC3339 string
DATE_RFC3339
  O mesmo que DATE_ATOM
DateTimeInterface::RFC3339_EXTENDED string
DATE_RFC3339_EXTENDED
  RFC 3339 formato ESTENDIDO (exemplo: 2005-08-15T15:52:01.000+00:00)
DateTimeInterface::RSS string
DATE_RSS
  RSS (exemplo: Mon, 15 Aug 2005 15:52:01 +0000)
DateTimeInterface::W3C string
DATE_W3C
  World Wide Web Consortium (exemplo: 2005-08-15T15:52:01+00:00)

## Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | As constantes `DATE_RFC7231` e `DateTimeInterface::RFC7231` foram descontinuadas.
8.4.0 | As constantes de classe agora são tipadas.
8.2.0 | A constante `DateTimeInterface::ISO8601_EXPANDED` foi adicionada.
7.2.0 | As constantes da classe DateTime agora são definidas na classe DateTimeInterface.

# DateTimeInterface::diff

# DateTimeImmutable::diff

# DateTime::diff

# date_diff

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTimeInterface::diff -- DateTimeImmutable::diff -- DateTime::diff -- date_diff — Retorna a diferença entre dois objetos DateTime

### Descrição

Estilo orientado a objetos

public function DateTimeInterface::diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval
public function DateTimeImmutable::diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval
public function DateTime::diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval

Estilo procedural

function date_diff(DateTimeInterface `$baseObject`, DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval

Retorna a diferença entre dois objetos que implementam a classe DateTimeInterface.

### Parâmetros

`datetime`

  A data a ser comparada.

`absolute`

  Informa se o intervalo deve ser forçado como positivo.

### Valor Retornado

O objeto DateInterval representa a diferença entre as duas datas.

O parâmetro `absolute` afeta somente a propriedade `invert` de um objeto DateInterval.

O valor de retorno representa mais especificamente o intervalo de tempo a ser aplicado ao objeto original (`$this` ou `$originObject`) para se chegar ao `$targetObject`. Este processo nem sempre é reversível.

O método leva em conta mudanças de horário de verão, e por isso pode retornar um intervalo de `24 horas e 30 minutos`, por exemplo. Se a intenção for fazer cálculos com horários absolutos, será necessário converter tanto `$this`/`$baseObject` quanto `$targetObject` para UTC primeiro.

### Exemplos

Exemplo #1 Exemplo do método DateTimeImmutable::diff()

Estilo orientado a objetos

    <?php
    $origin = new DateTime('2009-10-11');
    $target = new DateTime('2009-10-13');
    $interval = $origin->diff($target);
    echo $interval->format('%R%a dias');

O exemplo acima produzirá:

    +2 dias

Estilo procedural

    <?php
    $origin = date_create('2009-10-11');
    $target = date_create('2009-10-13');
    $interval = date_diff($origin, $target);
    echo $interval->format('%R%a dias');

O exemplo acima produzirá:

    +2 dias

Exemplo #2 DateTimeInterface::diff() durante mudança de horário de verão

    <?php
    $originalTime = new DateTimeImmutable("2021-10-30 09:00:00 Europe/London");
    $targetTime = new DateTimeImmutable("2021-10-31 08:30:00 Europe/London");
    $interval = $originalTime->diff($targetTime);
    echo $interval->format("%H:%I:%S (Dias inteiros: %a)"), "\n";

O exemplo acima produzirá:

    24:30:00 (Dias inteiros: 0)

Exemplo #3 Intervalo do método DateTimeInterface::diff()

O valor que o método retorna é a quantidade exata de tempo para sair de `$this` e chegar em `$targetObject`. Comparando 1º de janeiro com 31 de dezembro retorna portanto 364, e não 365 dias (para anos não bissextos).

    <?php
    $originalTime = new DateTimeImmutable("2023-01-01 UTC");
    $targetTime = new DateTimeImmutable("2023-12-31 UTC");
    $interval = $originalTime->diff($targetTime);
    echo "Dias inteiros: ", $interval->format("%a"), "\n";

O exemplo acima produzirá:

    Dias inteiros: 364

Exemplo #4 Comparação entre objetos DateTime

> Nota:

> Objetos das classes DateTimeImmutable e DateTime podem ser comparados utilizando os operadores de comparação.

    <?php
    $date1 = new DateTime("now");
    $date2 = new DateTime("tomorrow");

    var_dump($date1 == $date2);
    var_dump($date1 < $date2);
    var_dump($date1 > $date2);

O exemplo acima produzirá:

    bool(false)
    bool(true)
    bool(false)

### Veja Também

- DateInterval::format() - Formata um intervalo
- DateTime::add() - Modifica um objeto DateTime, com adição de dias, meses, anos, horas, minutos e segundos.
- DateTime::sub() - Subtrai uma quantidade de dias, meses, anos, horas, minutos e segundos de um objeto DateTime

# DateTimeInterface::format

# DateTimeImmutable::format

# DateTime::format

# date_format

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeInterface::format -- DateTimeImmutable::format -- DateTime::format -- date_format — Retorna a data formatada de acordo com um formato informado

### Descrição

Estilo orientado a objetos

public function DateTimeInterface::format(string `$format`): string
public function DateTimeImmutable::format(string `$format`): string
public function DateTime::format(string `$format`): string

Estilo procedural

function date_format(DateTimeInterface `$object`, string `$format`): string

Retorna a data formatada de acordo com um formato informado.

### Parâmetros

`object`
  Somente no estilo procedural: Um objeto DateTime retornado por date_create()
`format`

  O formato da string de data resultante. Veja abaixo as opções de formatação. Existem também várias constantes de data predefinidas que podem ser usadas, por exemplo, `DATE_RSS` contém a string de formatação `'D, d M Y H:i:s'`.

  Os seguintes caracteres são reconhecidos na string do parâmetro `format`
  Caractere em `format` | Descrição | Exemplo de valores retornados
  --- | --- | ---
  Dia | --- | ---
  `d` | Dia do mês, 2 digits com zeros à esquerda | `01` a `31`
  `D` | Uma representação textual de um dia, três letras | `Mon` a `Sun`
  `j` | Dia do mês sem zeros à esquerda | `1` a `31`
  `l` (lowercase 'L') | Uma representação textual completa do dia da semana | `Sunday` a `Saturday`
  `N` | Representação numérica ISO 8601 do dia da semana | `1` (para segunda-feira) a `7` (para domingo)
  `S` | Sufixo ordinal inglês para o dia do mês, 2 caracteres | `st`, `nd`, `rd` ou `th`. Funciona bem com `j`
  `w` | Representação numérica do dia da semana | `0` (para domingo) a `6` (para sábado)
  `z` | O dia do ano (começando em 0) | `0` a `365`
  Semana | --- | ---
  `W` | Número da semana do mês ISO 8601, semanas começando na segunda-feira | Exemplo: `42` (a 42ª semana no ano)
  Mês | --- | ---
  `F` | Uma representação textual completa do mês, como January ou March | `January` a `December`
  `m` | Representação numérica de um mês, com zeros à esquerda | `01` a `12`
  `M` | Uma representação textual curta de um mês, três letras | `Jan` a `Dec`
  `n` | Representação numérica de um mês, sem zeros à esquerda | `1` a `12`
  `t` | Número de dias em determinado mês | `28` a `31`
  Ano | --- | ---
  `L` | Se é um ano bissexto | `1` se for um ano bissexto, `0` caso contrário.
  `o` | Ano de numeração da semana ISO 8601. Tem o mesmo valor que `Y`, exceto que se o número da semana ISO (`W`) pertencer ao ano anterior ou seguinte, esse ano será usado. | Exemplos: `1999` ou `2003`
  `X` | Uma representação numérica completa expandida de um ano, pelo menos 4 dígitos, com `-` para anos AEC, e `+` para anos EC. | Exemplos: `-0055`, `+0787`, `+1999`, `+10191`
  `x` | Uma representação numérica completa expandida se necessário, ou uma representação numérica completa padrão se possível (como `Y`). Pelo menos quatro dígitos. Anos AEC são prefixados com um `-`. Anos além de (e incluindo) `10000` são prefixados com um `+`. | Exemplos: `-0055`, `0787`, `1999`, `+10191`
  `Y` | Uma representação numérica completa de um ano, pelo menos 4 dígitos, com `-` para anos AEC. | Exemplos: `-0055`, `0787`, `1999`, `2003`, `10191`
  `y` | Uma representação de dois digitos do ano | Exemplos: `99` ou `03`
  Hora | --- | ---
  `a` | Ante meridiem e Post meridiem em letras minúsculas | `am` ou `pm`
  `A` | Ante meridiem e Post meridiem em letras maiúsculas | `AM` ou `PM`
  `B` | Internet Time da Swatch | `000` a `999`
  `g` | Formato de 12 horas de uma hora sem zeros à esquerda | `1` a `12`
  `G` | Formato de 24 horas de uma hora sem zeros à esquerda | `0` a `23`
  `h` | Formato de 12 horas de uma hora com zeros à esquerda | `01` a `12`
  `H` | Formato de 24 horas de uma hora com zeros à esquerda | `00` a `23`
  `i` | Minutos com zeros à esquerda | `00` to `59`
  `s` | Segundos com zeros à esquerda | `00` a `59`
  `u` | Microssegundos. Note que date() sempre irá gerar `000000` uma vez que leva um parâmetro int, enquanto DateTimeInterface::format() suporta microssegundos se um objeto do tipo DateTimeInterface foi criado com microssegundos. | Exemplo: `654321`
  `v` | Milissegundos. A mesma nota se aplica como no `u`. | Exemplo: `654`
  Fuso horário | --- | ---
  `e` | Identificador do fuso horário | Exemplos: `UTC`, `GMT`, `Atlantic/Azores`
  `I` (i maiúsculo) | Se a data está ou não no horário de verão | `1` se está no horário de verão, `0` caso contrário.
  `O` | Diferença para o horário de Greenwich (GMT) sem dois pontos entre horas e minutos | Example: `+0200`
  `P` | Diferença para o horário de Greenwich (GMT) com dois pontos entre horas e minutos | Exemplo: `+02:00`
  `p` | O mesmo que `P`, mas retorna `Z` em vez de `+00:00` (disponível a partir do PHP 8.0.0) | Exemplo: `Z` ou `+02:00`
  `T` | Abreviação do fuso horário, se conhecido; ou o deslocamento GMT caso contrário. | Exemplos: `EST`, `MDT`, `+05`
  `Z` | Deslocamento do fuso horário em segundos. O deslocamento para fusos a oeste de UTC é sempre negativo, e para aqueles a leste de UTC é sempre positivo. | `-43200` a `50400`
  Data/Horário completos | --- | ---
  `c` | Data ISO 8601. Compatível somente com o formato não expandido (até o ano 9999). Datas posteriores resultarão em string inválida. Para datas posteriores e formato expandido, consulte `x` e `X`. | 2004-02-12T15:19:21+00:00
  `r` | Data formatada » RFC 2822/» RFC 5322 | Exemplo: `Thu, 21 Dec 2000 16:01:07 +0200`
  `U` | Segundos desde a Época Unix (1 de janeiro de 1970 00:00:00 GMT) | Veja também time()

  Caracteres não reconhecidos na string de formatação serão impressos como estão. O formato `Z` sempre retornará `0` ao usar gmdate().

  > Nota:

  > Uma vez que esta função só aceita timestamps int, o caractere de formato `u` só é útil ao usar a função date_format() com timestamps baseados no usuário criados com date_create().

### Valor Retornado

Retorna a data formatada em caso de sucesso.

### Registro de Alterações

Versão | Descrição
--- | ---
8.2.0 | Os caracteres de formatação `X` e `x` foram adicionados.
8.0.0 | O caractere de formatação `p` foi adicionado.

### Exemplos

Exemplo #1 Exemplo de DateTimeInterface::format()

Estilo orientado a objetos

    <?php
    $date = new DateTimeImmutable('2000-01-01');
    echo $date->format('Y-m-d H:i:s');
    ?>

O exemplo acima produzirá:

    2000-01-01 00:00:00

Estilo procedural

    <?php
    $date = date_create('2000-01-01');
    echo date_format($date, 'Y-m-d H:i:s');
    ?>

O exemplo acima produzirá:

    2000-01-01 00:00:00

Exemplo #2 Mais exemplos

    <?php
    // define o fuso horário padrão a ser usado.
    date_default_timezone_set('UTC');

    // agora
    $date = new DateTimeImmutable();

    // Imprime algo como: Wednesday
    echo $date->format('l'), "\n";

    // Imprime algo como: Wednesday 19th of October 2022 08:40:48 AM
    echo $date->format('l jS \o\f F Y h:i:s A'), "\n";

    /* usa as constantes no parâmetro format */
    // Imprime algo como: Wed, 19 Oct 2022 08:40:48 +0000
    echo $date->format(DateTimeInterface::RFC2822), "\n";
    ?>

Pode-se evitar que um caractere reconhecido na string de formação seja expandido escapando-o com uma barra invertida antes. Se o caractere com uma barra invertida já for uma sequência especial, pode-se escapar também a barra invertida.

Exemplo #3 Escapando caracteres ao formatar

    <?php
    $date = new DateTimeImmutable();

    // exibe algo como: Wednesday the 19th
    echo $date->format('l \t\h\e jS');
    ?>

Para formatar datas em outras línguas, IntlDateFormatter::format() pode ser usado em vez do DateTimeInterface::format().

### Notas

Este método não utiliza configurações baseadas no idioma. Toda a saída será em Inglês.

### Veja Também

- IntlDateFormatter::format() - Formata data/horário como uma string

# DateTimeInterface::getMicrosecond

# DateTimeImmutable::getMicrosecond

# DateTime::getMicrosecond

(PHP 8 >= 8.4.0)

DateTimeInterface::getMicrosecond -- DateTimeImmutable::getMicrosecond -- DateTime::getMicrosecond — Obtém a parte de microssegundos do timestamp Unix

### Descrição

public function DateTimeInterface::getMicrosecond(): int
public function DateTimeImmutable::getMicrosecond(): int
public function DateTime::getMicrosecond(): int

Obtém a parte de microssegundos do timestamp Unix.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a parte de microssegundos do timestamp Unix que representa a data/horário.

### Exemplos

Exemplo #1 Exemplo de DateTimeInterface::getMicrosecond()

    <?php
    $date = new DateTimeImmutable('2024-01-01 12:34:56.789123');
    var_dump($date->format('u'));
    var_dump($date->getMicrosecond());
    ?>

O exemplo acima produzirá:

    string(6) "789123"
    int(789123)

### Veja Também

- DateTimeInterface::getTimestamp() - Obtém o timestamp Unix
- DateTimeInterface::format() - Retorna a data formatada de acordo com um formato informado

# DateTimeInterface::getOffset

# DateTimeImmutable::getOffset

# DateTime::getOffset

# date_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeInterface::getOffset -- DateTimeImmutable::getOffset -- DateTime::getOffset -- date_offset_get — Retorna o deslocamento do fuso horário

### Descrição

Estilo orientado a objetos

public function DateTimeInterface::getOffset(): int
public function DateTimeImmutable::getOffset(): int
public function DateTime::getOffset(): int

Estilo procedural

function date_offset_get(DateTimeInterface `$object`): int

Retorna o deslocamento do fuso horário.

### Parâmetros

`object`
  Somente no estilo procedural: Um objeto DateTime retornado por date_create()

### Valor Retornado

Retorna o deslocamento do fuso horário, em segundos, para UTC em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo do método DateTime::getOffset()

Estilo orientado a objetos

    <?php
    $winter = new DateTimeImmutable('2010-12-21', new DateTimeZone('America/New_York'));
    $summer = new DateTimeImmutable('2008-06-21', new DateTimeZone('America/New_York'));

    echo $winter->getOffset() . "\n";
    echo $summer->getOffset() . "\n";

O exemplo acima produzirá:

    -18000
    -14400

Estilo procedural

    <?php
    $winter = date_create('2010-12-21', timezone_open('America/New_York'));
    $summer = date_create('2008-06-21', timezone_open('America/New_York'));

    echo date_offset_get($winter) . "\n";
    echo date_offset_get($summer) . "\n";

O exemplo acima produzirá:

    -18000
    -14400

Nota: -18000 = -5 horas, -14400 = -4 horas.

# DateTimeInterface::getTimestamp

# DateTimeImmutable::getTimestamp

# DateTime::getTimestamp

# date_timestamp_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTimeInterface::getTimestamp -- DateTimeImmutable::getTimestamp -- DateTime::getTimestamp -- date_timestamp_get — Obtém o timestamp Unix

### Descrição

Estilo orientado a objetos

public function DateTimeInterface::getTimestamp(): int
public function DateTimeImmutable::getTimestamp(): int
public function DateTime::getTimestamp(): int

Estilo procedural

function date_timestamp_get(DateTimeInterface `$object`): int

Obtém o timestamp Unix.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o timestamp Unix que representa a data.

### Erros/Exceções

Se o timestamp não puder ser representado como um int, uma exceção DateRangeError é disparada. Antes do PHP 8.3.0, uma exceção ValueError era disparada. E, antes do PHP 8.0.0, `false` era retornado neste caso. Ainda, o timestamp pode ser recuperado como string usando o método DateTimeInterface::format() com o formato literal `U`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | A exceção fora do intervalo é agora DateRangeError.
8.0.0 | Esta função não mais retorna `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo do método DateTime::getTimestamp()

Estilo orientado a objetos

    <?php
    $date = new DateTimeImmutable();
    echo $date->getTimestamp();

O exemplo acima produzirá algo semelhante a:

    1272509157

Estilo procedural

    <?php
    $date = date_create();
    echo date_timestamp_get($date);

O exemplo acima produzirá algo semelhante a:

    1272509157

Se for necessário recuperar o timestamp com resolução de milissegundos ou microssegundos, pode ser utilizada a função DateTimeInterface::format().

Exemplo #2 Recuperando o timestamp com resolução de mili e microssegundos

Estilo orientado a objetos

    <?php
    $date = new DateTimeImmutable();
    $mili = (int) $date->format('Uv'); // Timestamp em milissegundos
    $micro = (int) $date->format('Uu'); // Timestamp em microssegundos

    echo $mili, "\n", $micro, "\n";

O exemplo acima produzirá algo semelhante a:

    1674057635586
    1674057635586918

### Veja Também

- DateTime::setTimestamp() - Define a data e hora baseada em um timestamp Unix
- DateTimeImmutable::setTimestamp() - Define a data e o horário com base em um timestamp Unix
- DateTimeInterface::format() - Retorna a data formatada de acordo com um formato informado
- DateTimeInterface::getMicrosecond() - Obtém a parte de microssegundos do timestamp Unix

# DateTimeInterface::getTimezone

# DateTimeImmutable::getTimezone

# DateTime::getTimezone

# date_timezone_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeInterface::getTimezone -- DateTimeImmutable::getTimezone -- DateTime::getTimezone -- date_timezone_get — Retorna o fuso horário correspondente a um DateTime informado

### Descrição

Estilo orientado a objetos

public function DateTimeInterface::getTimezone(): DateTimeZone|false
public function DateTimeImmutable::getTimezone(): DateTimeZone|false
public function DateTime::getTimezone(): DateTimeZone|false

Estilo procedural

function date_timezone_get(DateTimeInterface `$object`): DateTimeZone|false

Retorna o fuso horário de um DateTime informado

### Parâmetros

`object`
  Somente no estilo procedural: Um objeto DateTime retornado por date_create()

### Valor Retornado

Retorna um objeto DateTimeZone em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo do método DateTime::getTimezone()

Estilo orientado a objetos

    <?php
    $date = new DateTimeImmutable("now", new DateTimeZone('Europe/London'));
    $tz = $date->getTimezone();
    echo $tz->getName();

O exemplo acima produzirá:

    Europe/London

Estilo procedural

    <?php
    $date = date_create("now", timezone_open('Europe/London'));
    $tz = date_timezone_get($date);
    echo timezone_name_get($tz);

O exemplo acima produzirá:

    Europe/London

### Veja Também

- DateTime::setTimezone() - Define o fuso horário de um objeto DateTime

# DateTime::__serialize

# DateTimeImmutable::__serialize

# DateTimeInterface::__serialize

(PHP 8 >= 8.2.0)

DateTime::__serialize -- DateTimeImmutable::__serialize -- DateTimeInterface::__serialize — Serializa um DateTime

### Descrição

public function DateTime::__serialize(): array
public function DateTimeImmutable::__serialize(): array
public function DateTimeInterface::__serialize(): array

O manipulador __serialize().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

A representação serializada do objeto DateTime.

### Exemplos

Exemplo #1 Exemplo de DateTime::serialize()

    <?php
    $date = new DateTime('2025-03-27');
    var_dump(serialize($date));

O exemplo acima produzirá:

    string(114) "O:8:"DateTime":3:{s:4:"date";s:26:"2025-03-27 00:00:00.000000";s:13:"timezone_type";i:3;s:8:"timezone";s:3:"UTC";}"

### Veja Também

- DateTime::__unserialize() - Desserializa um Datetime

# DateTime::__unserialize

# DateTimeImmutable::__unserialize

# DateTimeInterface::__unserialize

(PHP 8 >= 8.2.0)

DateTime::__unserialize -- DateTimeImmutable::__unserialize -- DateTimeInterface::__unserialize — Desserializa um Datetime

### Descrição

public function DateTime::__unserialize(array `$data`): void
public function DateTimeImmutable::__unserialize(array `$data`): void
public function DateTimeInterface::__unserialize(array `$data`): void

O manipulador __unserialize().

### Parâmetros

`data`

  O DateTime serializado.

### Valor Retornado

O objeto DateTime.

### Exemplos

Exemplo #1 Exemplo de DateTime::unserialize()

    <?php
    $serializedDate = 'O:8:"DateTime":3:{s:4:"date";s:26:"2025-03-27 00:00:00.000000";s:13:"timezone_type";i:3;s:8:"timezone";s:3:"UTC";}';
    var_dump(unserialize($serializedDate));

O exemplo acima produzirá:

    object(DateTime)#1 (3) {
      ["date"]=>
      string(26) "2025-03-27 00:00:00.000000"
      ["timezone_type"]=>
      int(3)
      ["timezone"]=>
      string(3) "UTC"
    }

### Veja Também

- DateTime::__serialize() - Serializa um DateTime

# DateTime::__wakeup

# DateTimeImmutable::__wakeup

# DateTimeInterface::__wakeup

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::__wakeup -- DateTimeImmutable::__wakeup -- DateTimeInterface::__wakeup — O manipulador __wakeup

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.5.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
public function DateTime::__wakeup(): void
#[\Deprecated]
public function DateTimeImmutable::__wakeup(): void
#[\Deprecated]
public function DateTimeInterface::__wakeup(): void

O manipulador __wakeup().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Inicializa o objeto DateTime.

## Índice

- DateTimeInterface::diff — Retorna a diferença entre dois objetos DateTime
- DateTimeInterface::format — Retorna a data formatada de acordo com um formato informado
- DateTimeInterface::getMicrosecond — Obtém a parte de microssegundos do timestamp Unix
- DateTimeInterface::getOffset — Retorna o deslocamento do fuso horário
- DateTimeInterface::getTimestamp — Obtém o timestamp Unix
- DateTimeInterface::getTimezone — Retorna o fuso horário correspondente a um DateTime informado
- DateTime::__serialize — Serializa um DateTime
- DateTime::__unserialize — Desserializa um Datetime
- DateTime::__wakeup — O manipulador __wakeup

# A classe DateTimeZone

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

## Introdução

Representação de um fuso horário.

## Resumo da classe

class DateTimeZone {
/* Constantes */
public const int AFRICA;
public const int AMERICA;
public const int ANTARCTICA;
public const int ARCTIC;
public const int ASIA;
public const int ATLANTIC;
public const int AUSTRALIA;
public const int EUROPE;
public const int INDIAN;
public const int PACIFIC;
public const int UTC;
public const int ALL;
public const int ALL_WITH_BC;
public const int PER_COUNTRY;
/* Métodos */
public function __construct(string `$timezone`)
public function getLocation(): array|false
public function getName(): string
public function getOffset(DateTimeInterface `$datetime`): int
public function getTransitions(int `$timestampBegin` = `PHP_INT_MIN`, int `$timestampEnd` = 2147483647): array|false
public static function listAbbreviations(): array
public static function listIdentifiers(int `$timezoneGroup` = `DateTimeZone::ALL`, ?string `$countryCode` = `null`): array
}

## Constantes predefinidas

`DateTimeZone::AFRICA` int

  Fusos horários da África.

`DateTimeZone::AMERICA` int

  Fusos horários da América.

`DateTimeZone::ANTARCTICA` int

  Fusos horários da Antártida.

`DateTimeZone::ARCTIC` int

  Fusos horários do Ártico.

`DateTimeZone::ASIA` int

  Fusos horários da Ásia.

`DateTimeZone::ATLANTIC` int

  Fusos horários do Atlântico.

`DateTimeZone::AUSTRALIA` int

  Fusos horários da Austrália.

`DateTimeZone::EUROPE` int

  Fusos horários da Europa.

`DateTimeZone::INDIAN` int

  Fusos horários da Índia.

`DateTimeZone::PACIFIC` int

  Fusos horários do Pacífico.

`DateTimeZone::UTC` int

  Fusos horários UTC.

`DateTimeZone::ALL` int

  Todos os fusos horários.

`DateTimeZone::ALL_WITH_BC` int

  Todos os fusos horários, incluindo retrocompatíveis.

`DateTimeZone::PER_COUNTRY` int

  Fusos horários por país.

## Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | As constantes de classe agora são tipadas.

# DateTimeZone::__construct

# timezone_open

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::__construct -- timezone_open — Cria um novo objeto DateTimeZone

### Descrição

Estilo orientado a objetos

public function DateTimeZone::__construct(string `$timezone`)

Estilo procedural

function timezone_open(string `$timezone`): DateTimeZone|false

Cria um novo objeto DateTimeZone.

Um objeto DateTimeZone dá acesso a três diferentes tipos de regras de fuso horário: deslocamento UTC (tipo `1`), abreviação de fuso (tipo `2`), e identificadores de fuso horário como publicado no banco de dados de fusos horários da IANA (tipo `3`).

O objeto DateTimeZone pode ser anexado aos objetos DateTime e DateTimeImmutable para que sejam capazes de mostrar o fuso horário encapsulado por estes objetos em um fuso horário local.

### Parâmetros

`timezone`

  Um dos nomes de fuso horário suportados, um valor de deslocamento (+0200), ou um identificador de fuso (BST).

### Valor Retornado

Retorna um objeto DateTimeZone em caso de sucesso. Estilo procedural retorna `false` em caso de falha.

### Erros/Exceções

Este método lança uma exceção DateInvalidTimeZoneException se o fuso horário informado não for reconhecido com um fuso horário válido. Antes do PHP 8.3, era uma exceção Exception.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Valores inválidos agora retornam uma DateInvalidTimeZoneException em vez de uma Exception genérica.

### Exemplos

Exemplo #1 Criando e anexando DateTimeZone a um DateTimeImmutable

    <?php
    $d = new DateTimeImmutable("2022-06-02 15:44:48 UTC");

    $timezones = [ 'Europe/London', 'GMT+04:45', '-06:00', 'CEST' ];

    foreach ($timezones as $tz) {
        $tzo = new DateTimeZone($tz);

        $local = $d->setTimezone($tzo);
        echo $local->format(DateTimeInterface::RFC2822 . ' — e') . "\n";
    }

O exemplo acima produzirá:

    Thu, 02 Jun 2022 16:44:48 +0100 — Europe/London
    Thu, 02 Jun 2022 20:29:48 +0445 — +04:45
    Thu, 02 Jun 2022 09:44:48 -0600 — -06:00
    Thu, 02 Jun 2022 17:44:48 +0200 — CEST

Exemplo #2 Capturando erros na instanciação de DateTimeZone

    <?php
    // Lidando com erros através de captura de exceções
    $timezones = array('Europe/London', 'Mars/Phobos', 'Jupiter/Europa');

    foreach ($timezones as $tz) {
        try {
            $mars = new DateTimeZone($tz);
            echo $mars->getName() . "\n";
        } catch(Exception $e) {
            echo $e->getMessage() . "\n";
        }
    }

O exemplo acima produzirá:

    Europe/London
    DateTimeZone::__construct() [datetimezone.--construct]: Unknown or bad timezone (Mars/Phobos)
    DateTimeZone::__construct() [datetimezone.--construct]: Unknown or bad timezone (Jupiter/Europa)

# DateTimeZone::getLocation

# timezone_location_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTimeZone::getLocation -- timezone_location_get — Retorna informações da localização de um fuso horário

### Descrição

Estilo orientado a objetos

public function DateTimeZone::getLocation(): array|false

Estilo procedural

function timezone_location_get(DateTimeZone `$object`): array|false

Retorna informações da localização de um fuso horário, incluindo o código do país, latitude/longitude e comentários.

### Parâmetros

`object`
  Somente no estilo procedural: Um objeto DateTimeZone retornado por timezone_open()

### Valor Retornado

Array contendo informações da localização de um fuso horário ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo do método DateTimeZone::getLocation()

    <?php
    $tz = new DateTimeZone("Asia/Jakarta");
    print_r($tz->getLocation());
    print_r(timezone_location_get($tz));

O exemplo acima produzirá:

    Array
    (
        [country_code] => ID
        [latitude] => -6.16667
        [longitude] => 106.8
        [comments] => Java, Sumatra
    )
    Array
    (
        [country_code] => ID
        [latitude] => -6.16667
        [longitude] => 106.8
        [comments] => Java, Sumatra
    )

O elemento `country_code` contém o código de país de 2 letras conforme ISO 3166-1 para cada entrada. Os elementos `latitude` e `longitude` contêm as coordenadas da cidade nomeada pelo identificador do fuso horário e o elemento `comments` contém (quando não for `false`) uma dica de onde no país informado este fuso horário se aplica. Esta informação é adequada para apresentação ao usuário final.

### Veja Também

- DateTimeZone::listIdentifiers() - Retorna um array numericamente indexado contendo todos os indenticadores de fuso horário para obter uma lista completa ou parcial de todos os identificadores de fuso horário suportados

# DateTimeZone::getName

# timezone_name_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::getName -- timezone_name_get — Retorna o nome do fuso horário

### Descrição

Estilo orientado a objetos

public function DateTimeZone::getName(): string

Estilo procedural

function timezone_name_get(DateTimeZone `$object`): string

Retorna o nome do fuso horário.

### Parâmetros

`object`

  O objeto DateTimeZone do qual se deseja obter o nome.

### Valor Retornado

Dependendo do tipo do fuso horário, deslocamento UTC (tipo 1), abreviação do fuso (tipo 2), e identificadores de fuso como publicado no banco de dados da IANA (tipo 3), o valor retornado será um descritor string para criar um novo objeto DateTimeZone com o mesmo deslocamento e/ou regras. Por exemplo `02:00`, `CEST`, ou um dos nomes na lista de fusos horários.

# DateTimeZone::getOffset

# timezone_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::getOffset -- timezone_offset_get — Retorna o deslocamento do fuso horário em relação ao GMT

### Descrição

Estilo orientado a objetos

public function DateTimeZone::getOffset(DateTimeInterface `$datetime`): int

Estilo procedural

function timezone_offset_get(DateTimeZone `$object`, DateTimeInterface `$datetime`): int

Esta função retorna o deslocamento em relação ao GMT para a data/horário especificada no parâmetro `datetime`. O deslocamento GMT é calculado com informação do fuso horário contido no objeto DateTimeZone utilizado.

### Parâmetros

`object`
  Somente no estilo procedural: Um objeto DateTimeZone retornado por timezone_open()
`datetime`

  DateTime que contém a data/horário a partir da qual será computado o deslocamento.

### Valor Retornado

Retorna o deslocamento do fuso horário em segundos.

### Exemplos

Exemplo #1 Exemplos do método DateTimeZone::getOffset()

    <?php
    // Cria dois objetos de fuso horário, um para Taipei (Taiwan) e um para
    // Tokyo (Japão)
    $dateTimeZoneTaipei = new DateTimeZone("Asia/Taipei");
    $dateTimeZoneJapan = new DateTimeZone("Asia/Tokyo");

    // Cria dois objetos DateTime que irão conter o mesmo timestamp Unix, mas
    // têm fusos horários diferentes anexados a eles.
    $dateTimeTaipei = new DateTime("now", $dateTimeZoneTaipei);
    $dateTimeJapan = new DateTime("now", $dateTimeZoneJapan);

    // Calcula o deslocamento GMT para a data/horário contida no objeto $dateTimeTaipei,
    // mas usando as regras de fuso horário como definidas para Tokyo
    // ($dateTimeZoneJapan).
    $timeOffset = $dateTimeZoneJapan->getOffset($dateTimeTaipei);

    // Deve mostrar int(32400) (para datas após Sat Sep 8 01:00:00 1951 JST).
    var_dump($timeOffset);

O exemplo acima produzirá:

    int(32400)

# DateTimeZone::getTransitions

# timezone_transitions_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::getTransitions -- timezone_transitions_get — Retorna todas as transições para o fuso horário

### Descrição

Estilo orientado a objetos

public function DateTimeZone::getTransitions(int `$timestampBegin` = `PHP_INT_MIN`, int `$timestampEnd` = 2147483647): array|false

Estilo procedural

function timezone_transitions_get(DateTimeZone `$object`, int `$timestampBegin` = `PHP_INT_MIN`, int `$timestampEnd` = 2147483647): array|false

### Parâmetros

`object`
  Somente no estilo procedural: Um objeto DateTimeZone retornado por timezone_open()
`timestampBegin`

  Timestamp inicial.

`timestampEnd`

  Timestamp final.

### Valor Retornado

Retorna um array numericamente indexado de arrays de transições em caso de sucesso, ou `false` em caso de falha. Objetos DataTimeZone do tipo 1 (deslocamento UTC) e tipo 2 (abreviações) não contêm transições, e se tiverem este método chamado irão retornar `false`.

Se o parâmetro `timestampBegin` for informado, a primeira entrada no array de retorno irá contrer um elemento de transição no horário de `timestampBegin`.

Estrutura do Array de Transição
Key | Type | Description
--- | --- | ---
`ts` | int | Timestamp Unix
`time` | string | string de horário `DateTimeInterface::ISO8601_EXPANDED` (PHP 8.2 e seguintes), ou `DateTimeInterface::ISO8601` (PHP 8.1 e anteriores)
`offset` | int | Deslocamento UTC em segundos
`isdst` | bool | Se o horário de verão está ativo
`abbr` | string | Abreviação do fuso horário

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O valor padrão de `timestampEnd` foi alterado para 2147483647. Anteriormente era `PHP_INT_MAX`.

### Exemplos

Exemplo #1 Exemplo do método timezone_transitions_get()

    <?php
    $timezone = new DateTimeZone("Europe/London");
    $transitions = $timezone->getTransitions();
    print_r(array_slice($transitions, 0, 3));
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Array
            (
                [ts] => -2147483648
                [time] => 1901-12-13T20:45:52+00:00
                [offset] => -75
                [isdst] =>
                [abbr] => LMT
            )

        [1] => Array
            (
                [ts] => 442304971
                [time] => 1847-12-01T00:01:15+00:00
                [offset] => 0
                [isdst] =>
                [abbr] => GMT
            )

        [2] => Array
            (
                [ts] => -1691964000
                [time] => 1916-05-21T02:00:00+00:00
                [offset] => 3600
                [isdst] => 1
                [abbr] => BST
            )

    )

Exemplo #2 Um exemplo da função timezone_transitions_get() com o parâmetro `timestampBegin`

    <?php
    $timezone = new DateTimeZone("Europe/London");
    $transitions = $timezone->getTransitions(time());
    print_r(array_slice($transitions, 0, 3));
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Array
            (
                [ts] => 1759058251
                [time] => 2025-09-28T11:17:31+00:00
                [offset] => 3600
                [isdst] => 1
                [abbr] => BST
            )

        [1] => Array
            (
                [ts] => 1761440400
                [time] => 2025-10-26T01:00:00+00:00
                [offset] => 0
                [isdst] =>
                [abbr] => GMT
            )

        [2] => Array
            (
                [ts] => 1774746000
                [time] => 2026-03-29T01:00:00+00:00
                [offset] => 3600
                [isdst] => 1
                [abbr] => BST
            )

    )

# DateTimeZone::listAbbreviations

# timezone_abbreviations_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::listAbbreviations -- timezone_abbreviations_list — Retorna um array associativo contendo indicativo de horário de verão, deslocamento e nome do fuso horário

### Descrição

Estilo orientado a objetos

public static function DateTimeZone::listAbbreviations(): array

Estilo procedural

function timezone_abbreviations_list(): array

A lista de abreviações retornada inclui todo o uso histórico de abreviações, o que pode levar a entradas corretas, porém confusas. Também existem conflitos, já que `PST` é usado tanto nos EUA como nas Filipinas.

A lista que esta função retora não é portanto adequada para construir um array com opções para apresentar ao usuário para escolha de fusos horários.

> Nota:

> Os dados desta função são pré compilados por razões de desempenho, e não são atualizadas quado é usado um novo » timezonedb.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o array de abreviações de fuso horário.

### Exemplos

Exemplo #1 Exemplo da função timezone_abbreviations_list()

    <?php
    $timezone_abbreviations = DateTimeZone::listAbbreviations();
    print_r($timezone_abbreviations["acst"]);

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/Adelaide
            )

        [1] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/Broken_Hill
            )

        [2] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/Darwin
            )

        [3] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/North
            )

        [4] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/South
            )

        [5] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/Yancowinna
            )

    )

### Veja Também

- timezone_identifiers_list() - Sinônimo de DateTimeZone::listIdentifiers

# DateTimeZone::listIdentifiers

# timezone_identifiers_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::listIdentifiers -- timezone_identifiers_list — Retorna um array numericamente indexado contendo todos os indenticadores de fuso horário

### Descrição

Estilo orientado a objetos

public static function DateTimeZone::listIdentifiers(int `$timezoneGroup` = `DateTimeZone::ALL`, ?string `$countryCode` = `null`): array

Estilo procedural

function timezone_identifiers_list(int `$timezoneGroup` = `DateTimeZone::ALL`, ?string `$countryCode` = `null`): array

Retorna a lista de » identificadores de fuso horário IANA.

> Nota: É possível identificar o fuso horário do cliente (navegador) com JavaScript usando » Intl.DateTimeFormat ou » Temporal.ZonedDateTime.

### Parâmetros

`timezoneGroup`

  Uma das constantes da classe DateTimeZone (ou uma combinação).

`countryCode`

  Um código de país, com duas letras (maiúsculas), compatível com a ISO 3166-1.

  > Nota: Esta opção é utilizada somente quando o parâmetro `timezoneGroup` é configurado como `DateTimeZone::PER_COUNTRY`.

### Valor Retornado

Retorna o array de identificadores de fuso horário. Apenas itens não desatualizados são retornados. Para obter todos, incluindo identificadores desatualizados, use `DateTimeZone::ALL_WITH_BC` no valor de `timezoneGroup`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Antes desta versão, `false` era retornado em caso de falha.
7.1.0 | O parâmetro `countryCode` agora pode ser nulo.

### Exemplos

Exemplo #1 Listando identificadores com comentários de localização

    <?php
    $identifiers = DateTimeZone::listIdentifiers(DateTimeZone::ALL);

    foreach ($identifiers as $tzid) {
        $tz = new DateTimeZone($tzid);
        $comments = $tz->getLocation()['comments'];
        echo $tzid . " (" . ($comments ?: 'Região inteira') . ")\n";
    }

O exemplo acima produzirá algo semelhante a:

    America/Antigua (Região inteira)
    America/Araguaina (Tocantins)
    America/Argentina/Buenos_Aires (Buenos Aires (BA, CF))
    America/Argentina/Catamarca (Catamarca (CT), Chubut (CH))
    America/Argentina/Cordoba (Argentina (most areas: CB, CC, CN, ER, FM, MN, SE, SF))
    // (Saída truncada devido ao tamanho)

Exemplo #2 Listando identificadores para uma região específica

    <?php
    $timezone_identifiers = DateTimeZone::listIdentifiers( DateTimeZone::ASIA );
    for ($i=0; $i < 5; $i++) {
        echo "$timezone_identifiers[$i]\n";
    }

O exemplo acima produzirá algo semelhante a:

    Asia/Aden
    Asia/Almaty
    Asia/Amman
    Asia/Anadyr
    Asia/Aqtau

Exemplo #3 Listando identificadores para múltiplas regiões

    <?php
    $timezone_identifiers = DateTimeZone::listIdentifiers( DateTimeZone::ASIA | DateTimeZone::PACIFIC );
    echo join( ', ', $timezone_identifiers );

O exemplo acima produzirá algo semelhante a:

    Asia/Aden, Asia/Almaty, Asia/Amman, Asia/Anadyr, Asia/Aqtau, Asia/Aqtobe,
    Asia/Ashgabat, Asia/Atyrau, Asia/Baghdad, Asia/Bahrain, Asia/Baku,
    Asia/Bangkok, Asia/Barnaul, Asia/Beirut, Asia/Bishkek, Asia/Brunei,
    Asia/Chita, Asia/Choibalsan, Asia/Colombo, Asia/Damascus, Asia/Dhaka,
    Asia/Dili, Asia/Dubai, Asia/Dushanbe, Asia/Famagusta, Asia/Gaza, Asia/Hebron,
    Asia/Ho_Chi_Minh, Asia/Hong_Kong, Asia/Hovd, Asia/Irkutsk, Asia/Jakarta,
    Asia/Jayapura, Asia/Jerusalem, Asia/Kabul, Asia/Kamchatka, Asia/Karachi,
    Asia/Kathmandu, Asia/Khandyga, Asia/Kolkata, Asia/Krasnoyarsk,
    Asia/Kuala_Lumpur, Asia/Kuching, Asia/Kuwait, Asia/Macau, Asia/Magadan,
    Asia/Makassar, Asia/Manila, Asia/Muscat, Asia/Nicosia, Asia/Novokuznetsk,
    Asia/Novosibirsk, Asia/Omsk, Asia/Oral, Asia/Phnom_Penh, Asia/Pontianak,
    Asia/Pyongyang, Asia/Qatar, Asia/Qostanay, Asia/Qyzylorda, Asia/Riyadh,
    Asia/Sakhalin, Asia/Samarkand, Asia/Seoul, Asia/Shanghai, Asia/Singapore,
    Asia/Srednekolymsk, Asia/Taipei, Asia/Tashkent, Asia/Tbilisi, Asia/Tehran,
    Asia/Thimphu, Asia/Tokyo, Asia/Tomsk, Asia/Ulaanbaatar, Asia/Urumqi,
    Asia/Ust-Nera, Asia/Vientiane, Asia/Vladivostok, Asia/Yakutsk, Asia/Yangon,
    Asia/Yekaterinburg, Asia/Yerevan, Pacific/Apia, Pacific/Auckland,
    Pacific/Bougainville, Pacific/Chatham, Pacific/Chuuk, Pacific/Easter,
    Pacific/Efate, Pacific/Fakaofo, Pacific/Fiji, Pacific/Funafuti,
    Pacific/Galapagos, Pacific/Gambier, Pacific/Guadalcanal, Pacific/Guam,
    Pacific/Honolulu, Pacific/Kanton, Pacific/Kiritimati, Pacific/Kosrae,
    Pacific/Kwajalein, Pacific/Majuro, Pacific/Marquesas, Pacific/Midway,
    Pacific/Nauru, Pacific/Niue, Pacific/Norfolk, Pacific/Noumea,
    Pacific/Pago_Pago, Pacific/Palau, Pacific/Pitcairn, Pacific/Pohnpei,
    Pacific/Port_Moresby, Pacific/Rarotonga, Pacific/Saipan, Pacific/Tahiti,
    Pacific/Tarawa, Pacific/Tongatapu, Pacific/Wake, Pacific/Wallis

Exemplo #4 Listando identificadores para um único país

    <?php
    $timezone_identifiers = DateTimeZone::listIdentifiers( DateTimeZone::PER_COUNTRY, "UA" );
    foreach( $timezone_identifiers as $identifier ) {
        echo "$identifier\n";
    }

O exemplo acima produzirá algo semelhante a:

    Europe/Kyiv
    Europe/Simferopol
    Europe/Uzhgorod
    Europe/Zaporozhye

### Veja Também

- timezone_abbreviations_list() - Sinônimo de DateTimeZone::listAbbreviations

## Índice

- DateTimeZone::__construct — Cria um novo objeto DateTimeZone
- DateTimeZone::getLocation — Retorna informações da localização de um fuso horário
- DateTimeZone::getName — Retorna o nome do fuso horário
- DateTimeZone::getOffset — Retorna o deslocamento do fuso horário em relação ao GMT
- DateTimeZone::getTransitions — Retorna todas as transições para o fuso horário
- DateTimeZone::listAbbreviations — Retorna um array associativo contendo indicativo de horário de verão, deslocamento e nome do fuso horário
- DateTimeZone::listIdentifiers — Retorna um array numericamente indexado contendo todos os indenticadores de fuso horário

# A classe DateInterval

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Introdução

Representa um intervalo entre datas.

Um intervalo de data armazena, tanto uma quantidade de tempo (em anos, meses, dias, horas, etc), quanto uma string de tempo relativo no formato que os construtores das classes DateTimeImmutable e DateTime suportam.

Mais especificamente, a informação em um objeto da classe DateInterval é uma instrução para mover de uma data/horário para outra data/horário. Este processo nem sempre é reversível.

Uma maneira comum de criar um objeto DateInterval é calculando a diferença entre dois objetos data/horário através do método DateTimeInterface::diff().

Como não existe uma maneira bem definida de comparar intervalos de datas, as instâncias de DateInterval são incomparáveis.

## Resumo da classe

class DateInterval {
/* Propriedades */
public int $y;
public int $m;
public int $d;
public int $h;
public int $i;
public int $s;
public float $f;
public int $invert;
public mixed $days;
public bool $from_string;
public string $date_string;
/* Métodos */
public function __construct(string `$duration`)
public static function createFromDateString(string `$datetime`): DateInterval
public function format(string `$format`): string
}

## Propriedades

Aviso

As propriedades disponíveis listadas abaixo dependem da versão do PHP, e devem ser consideradas como somente-leitura.

y

  Número de anos.

m

  Número de meses.

d

  Número de dias.

h

  Número de horas.

i

  Número de minutos.

s

  Número de segundos.

f

  Número de microssegundos, como uma fração de um segundo.

invert

  Será `1` se o intervalo representa um período negativo de tempo e `0` caso contrário. Veja DateInterval::format().

days

  Se o objeto DateInterval foi criado por DateTimeImmutable::diff() ou DateTime::diff(), então ele representará o número total de dias inteiros entre a data inicial e final. Caso contrário, days será `false`.

from_string

  Se o objeto DateInterval foi criado por DateInterval::createFromDateString(), então o valor desta propriedade será `true` e a propriedade date_string será populada. Caso contrário, o valor será `false` e as propriedades y a f, invert e days serão populadas.

date_string

  String usado como argumento para DateInterval::createFromDateString().

## Registro de Alterações

Versão | Descrição
--- | ---
8.2.0 | As propriedades from_string e date_string foram adicionadas para instâncias DateInterval que foram criadas usando o método DateInterval::createFromDateString().
8.2.0 | Apenas as propriedades `y` a `f`, `invert`, e `days` serão visíveis.
7.4.0 | As instâncias de DateInterval agora são incomparáveis; antes, todas as instâncias de DateInterval eram consideradas iguais.
7.1.0 | A propriedade f foi adicionada.

# DateInterval::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateInterval::__construct — Cria um novo objeto DateInterval

### Descrição

public function DateInterval::__construct(string `$duration`)

Cria um novo objeto DateInterval.

### Parâmetros

`duration`

  Uma especificação de intervalo.

  O formato inicia-se com a letra `P`, de período. Cada período de duração é representado por um valor inteiro seguido do designador de período. Se a duração contiver elementos de tempo, essa porção da especificação é precedida pela letra `T`.

  `duration` Designadores de Período
  Designador de Período | Descrição
  --- | ---
  `Y` | anos
  `M` | meses
  `D` | dias
  `W` | semanas. Convertidas em dias. Antes do PHP 8.0.0, não pode ser combinada com `D`.
  `H` | horas
  `M` | minutos
  `S` | segundos

  Alguns exemplos simples. O período de dois dias é representado por `P2D`. O período de dois segundos é representado por `PT2S`. O período de seis anos e cinco minutos é representado por `P6YT5M`.

  > Nota:

  > Os tipos de unidade devem ser informados a partir da maior unidade de escala na esquerda até a menor escala na direita. Ou seja, anos antes de meses, meses antes de dias, dias antes de minutos etc. Assim, um ano e quatro dias deve ser representado por `P1Y4D`, e não `P4D1Y`.

  A especificação também pode ser representada como data e horário. Um exemplo de um ano e quatro dias seria `P0001-00-04T00:00:00`. Porém, valores neste formato não podem exceder o tamanho máximo do período (por exemplo `25` horas é inválido).

  Estes formatos são baseados na » especificação de duração ISO 8601.

### Erros/Exceções

Lança uma exceção DateMalformedIntervalStringException quando o parâmetro `duration` não puder ser interpretado como um intervalo. Antes do PHP 8.3, era uma Exception.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Agora lança DateMalformedIntervalStringException em vez de Exception.
8.2.0 | Apenas as propriedades `y` a `f`, `invert` e `days` estarão visíveis, incluindo uma nova propriedade booleana `from_string`.
8.0.0 | `W` pode ser combinado com `D`.

### Exemplos

Exemplo #1 Construindo e usando objetos da classe DateInterval

    <?php
    // Cria uma data específica
    $someDate = \DateTime::createFromFormat("Y-m-d H:i", "2022-08-25 14:18");

    // Cria um intervalo
    $interval = new \DateInterval("P7D");

    // Adiciona o intervalo
    $someDate->add($interval);

    // Converte o intervalo para string
    echo $interval->format("%d");

O exemplo acima produzirá:

    7

Exemplo #2 Exemplo da classe DateInterval

    <?php
    $interval = new DateInterval('P1W2D');
    var_dump($interval);

Saída do exemplo acima no PHP 8.2:

    object(DateInterval)#1 (10) {
      ["y"]=>
      int(0)
      ["m"]=>
      int(0)
      ["d"]=>
      int(9)
      ["h"]=>
      int(0)
      ["i"]=>
      int(0)
      ["s"]=>
      int(0)
      ["f"]=>
      float(0)
      ["invert"]=>
      int(0)
      ["days"]=>
      bool(false)
      ["from_string"]=>
      bool(false)
    }

Saída do exemplo acima no PHP 8:

    object(DateInterval)#1 (16) {
      ["y"]=>
      int(0)
      ["m"]=>
      int(0)
      ["d"]=>
      int(9)
      ["h"]=>
      int(0)
      ["i"]=>
      int(0)
      ["s"]=>
      int(0)
      ["f"]=>
      float(0)
      ["weekday"]=>
      int(0)
      ["weekday_behavior"]=>
      int(0)
      ["first_last_day_of"]=>
      int(0)
      ["invert"]=>
      int(0)
      ["days"]=>
      bool(false)
      ["special_type"]=>
      int(0)
      ["special_amount"]=>
      int(0)
      ["have_weekday_relative"]=>
      int(0)
      ["have_special_relative"]=>
      int(0)
    }

Saída do exemplo acima no PHP 7:

    object(DateInterval)#1 (16) {
      ["y"]=>
      int(0)
      ["m"]=>
      int(0)
      ["d"]=>
      int(2)
      ["h"]=>
      int(0)
      ["i"]=>
      int(0)
      ["s"]=>
      int(0)
      ["f"]=>
      float(0)
      ["weekday"]=>
      int(0)
      ["weekday_behavior"]=>
      int(0)
      ["first_last_day_of"]=>
      int(0)
      ["invert"]=>
      int(0)
      ["days"]=>
      bool(false)
      ["special_type"]=>
      int(0)
      ["special_amount"]=>
      int(0)
      ["have_weekday_relative"]=>
      int(0)
      ["have_special_relative"]=>
      int(0)
    }

### Veja Também

- DateInterval::format() - Formata um intervalo
- DateTime::add() - Modifica um objeto DateTime, com adição de dias, meses, anos, horas, minutos e segundos.
- DateTime::sub() - Subtrai uma quantidade de dias, meses, anos, horas, minutos e segundos de um objeto DateTime
- DateTime::diff() - Retorna a diferença entre dois objetos DateTime

# DateInterval::createFromDateString

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateInterval::createFromDateString — Cria um DateInterval de porções relativas da string

### Descrição

Estilo orientado a objetos

public static function DateInterval::createFromDateString(string `$datetime`): DateInterval

Estilo procedural

function date_interval_create_from_date_string(string `$datetime`): DateInterval|false

Utiliza o interpretador de data/horário como no construtor da classe DateTimeImmutable para criar um DateInterval a partir das partes relacionadas de uma string analisada.

### Parâmetros

`datetime`

  Uma data com porções relativas. Especificamente, os formatos relativos suportados pelo analisador utilizados em DateTimeImmutable, DateTime e strtotime() serão utilizados para construir o DateInterval.

  Para usar um string no formato ISO-8601 como `P7D`, deve-se usar o construtor DateInterval::__construct().

### Valor Retornado

Retorna DateInterval em caso de sucesso. Estilo procedural retorna `false` em caso de falha.

### Erros/Exceções

Apenas para API orientada a objetos: Se uma string de data/horário inválida for passada, uma exceção DateMalformedIntervalStringException é lançada.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Agora possui um tipo de retorno provisório de DateInterval. Anteriormente era DateInterval|false.
8.3.0 | DateInterval::createFromDateString() agora lança uma exceção DateMalformedIntervalStringException se uma string inválida for passada. Anteriormente, retornava `false` e um alerta era emitido. A função date_interval_create_from_date_string() não foi alterada.
8.2.0 | Apenas as propriedades `from_string` e `date_string` estarão visíveis quando um DateInterval for criado com este método.

### Exemplos

Exemplo #1 Analisando intervalos de datas válidos

    <?php
    // Cada conjunto de intervalos é igual.
    $i = new DateInterval('P1D');
    $i = DateInterval::createFromDateString('1 day');

    $i = new DateInterval('P2W');
    $i = DateInterval::createFromDateString('2 weeks');

    $i = new DateInterval('P3M');
    $i = DateInterval::createFromDateString('3 months');

    $i = new DateInterval('P4Y');
    $i = DateInterval::createFromDateString('4 years');

    $i = new DateInterval('P1Y1D');
    $i = DateInterval::createFromDateString('1 year + 1 day');

    $i = new DateInterval('P1DT12H');
    $i = DateInterval::createFromDateString('1 day + 12 hours');

    $i = new DateInterval('PT3600S');
    $i = DateInterval::createFromDateString('3600 seconds');

Exemplo #2 Analisando combinações e intervalos negativos

    <?php
    $i = DateInterval::createFromDateString('62 weeks + 1 day + 2 weeks + 2 hours + 70 minutes');
    echo $i->format('%d %h %i'), "\n";

    $i = DateInterval::createFromDateString('1 year - 10 days');
    echo $i->format('%y %d'), "\n";

O exemplo acima produzirá:

    449 2 70
    1 -10

Exemplo #3 Analisando intervalos especiais de data

    <?php
    $i = DateInterval::createFromDateString('last day of next month');
    var_dump($i);

    $i = DateInterval::createFromDateString('last weekday');
    var_dump($i);

Saída do exemplo acima no PHP 8.2:

    object(DateInterval)#1 (2) {
      ["from_string"]=>
      bool(true)
      ["date_string"]=>
      string(22) "last day of next month"
    }
    object(DateInterval)#2 (2) {
      ["from_string"]=>
      bool(true)
      ["date_string"]=>
      string(12) "last weekday"
    }

A saída do exemplo acima no PHP 8 é semelhante a:

    object(DateInterval)#1 (16) {
      ["y"]=>
      int(0)
      ["m"]=>
      int(1)
      ["d"]=>
      int(0)
      ["h"]=>
      int(0)
      ["i"]=>
      int(0)
      ["s"]=>
      int(0)
      ["f"]=>
      float(0)
      ["weekday"]=>
      int(0)
      ["weekday_behavior"]=>
      int(0)
      ["first_last_day_of"]=>
      int(2)
      ["invert"]=>
      int(0)
      ["days"]=>
      bool(false)
      ["special_type"]=>
      int(0)
      ["special_amount"]=>
      int(0)
      ["have_weekday_relative"]=>
      int(0)
      ["have_special_relative"]=>
      int(0)
    }
    object(DateInterval)#2 (16) {
      ["y"]=>
      int(0)
      ["m"]=>
      int(0)
      ["d"]=>
      int(0)
      ["h"]=>
      int(0)
      ["i"]=>
      int(0)
      ["s"]=>
      int(0)
      ["f"]=>
      float(0)
      ["weekday"]=>
      int(0)
      ["weekday_behavior"]=>
      int(0)
      ["first_last_day_of"]=>
      int(0)
      ["invert"]=>
      int(0)
      ["days"]=>
      bool(false)
      ["special_type"]=>
      int(1)
      ["special_amount"]=>
      int(-1)
      ["have_weekday_relative"]=>
      int(0)
      ["have_special_relative"]=>
      int(1)
    }

# DateInterval::format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateInterval::format — Formata um intervalo

### Descrição

public function DateInterval::format(string `$format`): string

Formata um intervalo.

### Parâmetros

`format`

  Os caracteres a seguir são reconhecidos como string no parâmetro `format`. Cada um dos caracteres de formato deve ser precedidos com o sinal de porcentagem (`%`).
  Caractere de `format` | Descrição | Exemplo de valores
  --- | --- | ---
  `%` | `%` literal | `%`
  `Y` | Anos, em representação numérica, com dois dígitos e zero à esquerda | `01`, `03`
  `y` | Anos, em representação numérica | `1`, `3`
  `M` | Meses, em representação numérica, com dois dígitos e zero à esquerda | `01`, `03`, `12`
  `m` | Meses, em representação numérica | `1`, `3`, `12`
  `D` | Dias, em representação numérica, com dois dígitos e zero à esquerda | `01`, `03`, `31`
  `d` | Dias, em representação numérica | `1`, `3`, `31`
  `a` | Número total de dias resultante de DateTime::diff() ou `(unknown)`, caso contrário | `4`, `18`, `8123`
  `H` | Horas, em representação numérica, com dois dígitos e zero à esquerda | `01`, `03`, `23`
  `h` | Horas, em representação numérica | `1`, `3`, `23`
  `I` | Minutos, em representação numérica, com dois dígitos e zero à esquerda | `01`, `03`, `59`
  `i` | Minutos, em representação numérica | `1`, `3`, `59`
  `S` | Segundos, em representação numérica, com dois dígitos e zero à esquerda | `01`, `03`, `57`
  `s` | Segundos, em representação numérica | `1`, `3`, `57`
  `F` | Microssegundos, numérico, pelo menos 6 dígitos precedidos com 0 | `007701`, `052738`, `428291`
  `f` | Microssegundos, numérico | `7701`, `52738`, `428291`
  `R` | Sinal "`-`" quando negativo, "`+`" quando positivo | `-`, `+`
  `r` | Sinal "`-`" quando negativo, sem sinal quando positivo | `-`, ``

### Valor Retornado

Retorna o intervalo formatado.

### Registro de Alterações

Versão | Descrição
--- | ---
7.2.12 | Os formatos `F` e `f` agora são sempre positivos.
7.1.0 | Os formatos `F` e `f` foram adicionados.

### Exemplos

Exemplo #1 Exemplo da classe DateInterval

    <?php
    $interval = new DateInterval('P2Y4DT6H8M');
    echo $interval->format('%d days');

O exemplo acima produzirá:

    4 days

Exemplo #2 A classe DateInterval e os pontos de transferência

    <?php
    $interval = new DateInterval('P32D');
    echo $interval->format('%d days');

O exemplo acima produzirá:

    32 days

Exemplo #3 DateInterval e DateTime::diff() com os modificadores %a e %d

    <?php
    $janeiro = new DateTime('2010-01-01');
    $fevereiro = new DateTime('2010-02-01');
    $intervalo = $fevereiro->diff($janeiro);

    // %a irá resultar no número total de dias.
    echo $intervalo->format('%a dias totais')."\n";

    // Enquanto %d irá apenas resultar no número de dias ainda não cobertos pelo
    // mês.
    echo $intervalo->format('%m mês, %d dias');

O exemplo acima produzirá:

    31 total days
    1 month, 0 days

### Notas

> Nota:

> O método DateInterval::format() não recalcula pontos de transferência em strings de data/horário. Isto é esperado porque não é possível extrapolar valores como `"32 days"`, o que poderia ser interpretado como qualquer coisa entre `"1 month and 4 days"` e `"1 month and 1 day"`.

### Veja Também

- DateTime::diff() - Retorna a diferença entre dois objetos DateTime

## Índice

- DateInterval::__construct — Cria um novo objeto DateInterval
- DateInterval::createFromDateString — Cria um DateInterval de porções relativas da string
- DateInterval::format — Formata um intervalo

# A classe DatePeriod

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Introdução

Representa um período entre datas.

O período entre datas permite a interação entre um conjunto de datas e horários recorrentes a intervalos regulares, durante um determinado período.

## Resumo da classe

class DatePeriod implements IteratorAggregate {
/* Constantes */
public const int EXCLUDE_START_DATE;
public const int INCLUDE_END_DATE;
/* Propriedades */
public readonly ?DateTimeInterface $start;
public readonly ?DateTimeInterface $current;
public readonly ?DateTimeInterface $end;
public readonly ?DateInterval $interval;
public readonly int $recurrences;
public readonly bool $include_start_date;
public readonly bool $include_end_date;
/* Métodos */
public function __construct(
DateTimeInterface `$start`,
DateInterval `$interval`,
int `$recurrences`,
int `$options` = 0
)
public function __construct(
DateTimeInterface `$start`,
DateInterval `$interval`,
DateTimeInterface `$end`,
int `$options` = 0
)
public function __construct(string `$isostr`, int `$options` = 0)
public static function createFromISO8601String(string `$specification`, int `$options` = 0): static
public function getDateInterval(): DateInterval
public function getEndDate(): ?DateTimeInterface
public function getRecurrences(): ?int
public function getStartDate(): DateTimeInterface
}

## Constantes predefinidas

`DatePeriod::EXCLUDE_START_DATE` int

  Exclui a data inicial, utilizada em DatePeriod::__construct().

`DatePeriod::INCLUDE_END_DATE` int

  Inclui a data final, utilizado em DatePeriod::__construct().

## Propriedades

recurrences

  O número mínimo de instâncias retornadas pelo iterador.

  O número de recorrências que foi informado explicitamente no parâmetro recurrences no construtor da instância de DatePeriod, de forma que essa propriedade contém este valor, mais um se a data inicial não foi excluída através de `DatePeriod::EXCLUDE_START_DATE`, mais um se a data final foi incluída através de `DatePeriod::INCLUDE_END_DATE`.

  Se o número de recorrências não foi informado explicitamente, então esta propriedade conta o número mínimo de recorrências a retornar. Isto pode ser `0`, mais um se a data inicial não foi excluída através de `DatePeriod::EXCLUDE_START_DATE`, mais um se a data final não foi incluída através de `DatePeriod::INCLUDE_END_DATE`.

      <?php
      $start = new DateTime('2018-12-31 00:00:00');
      $end   = new DateTime('2021-12-31 00:00:00');
      $interval = new DateInterval('P1M');
      $recurrences = 5;

      // recorrências informadas no construtor
      $period = new DatePeriod($start, $interval, $recurrences, DatePeriod::EXCLUDE_START_DATE);
      echo $period->recurrences, "\n";

      $period = new DatePeriod($start, $interval, $recurrences);
      echo $period->recurrences, "\n";

      $period = new DatePeriod($start, $interval, $recurrences, DatePeriod::INCLUDE_END_DATE);
      echo $period->recurrences, "\n";

      // recorrências não informadas no construtor
      $period = new DatePeriod($start, $interval, $end);
      echo $period->recurrences, "\n";

      $period = new DatePeriod($start, $interval, $end, DatePeriod::EXCLUDE_START_DATE);
      echo $period->recurrences, "\n";

  O exemplo acima produzirá:

      5
      6
      7
      1
      0

  Veja também DatePeriod::getRecurrences().

include_end_date

  Informa se deve ser incluída a data final no conjunto de datas a retornar.

include_start_date

  Informa se deve ser incluída a data inicial no conjunto de datas a retornar.

start

  A data inicial do período.

current

  Contém a data atual dentro do período.

end

  Data final do período.

interval

  Uma especificação ISO 8601 do intervalo repetidor.

## Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | As constantes de classe agora são tipadas.
8.2.0 | A constante `DatePeriod::INCLUDE_END_DATE` e a propriedade include_end_date foram adicionados.
8.0.0 | DatePeriod agora implementa IteratorAggregate. Anteriormente implementava Traversable.

# DatePeriod::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DatePeriod::__construct — Cria um novo objeto DatePeriod

### Descrição

public function DatePeriod::__construct(
DateTimeInterface `$start`,
DateInterval `$interval`,
int `$recurrences`,
int `$options` = 0
)
public function DatePeriod::__construct(
DateTimeInterface `$start`,
DateInterval `$interval`,
DateTimeInterface `$end`,
int `$options` = 0
)
Aviso

A variante de construtor a seguir foi descontinuada:

public function DatePeriod::__construct(string `$isostr`, int `$options` = 0)

Esta variante do construtor foi descontinuada a partir do PHP 8.4.0, use o método DatePeriod::createFromISO8601String() em seu lugar.

Cria um objeto DatePeriod.

Objetos DatePeriod podem ser usados como um iterador para gerar um número de objetos DateTimeImmutable ou DateTime a partir de uma data inicial (`start`), um intervalo (`interval`), e uma data final (`end`) ou o número de recorrências (`recurrences`).

A classe do objeto retornado é equivalente à classe ancestral DateTimeImmutable ou DateTime do objeto do parâmetro `start`.

### Parâmetros

`start`

  A data inicial do período. Incluído por padrão no conjunto de resultados.

`interval`

  A recorrência de intervalos entre os períodos.

`recurrences`

  O número de recorrências. O número do resultado retornado é uma unidade a mais que isto, já que a data de início é incluída no conjunto de resultados por padrão. Deve ser maior que `0`.

`end`

  A data final do período.

`isostr`

  Um sobconjunto da » especificação de intervalos recorrented ISO 8601.

  Exemplos de algumas características de especificação de intervalos ISO 8601 que o PHP não suporta são:

  1. zero ocorrências (`R0/`)
  2. fusos horários diferentes de UTC (`Z`), como `+02:00`.
`options`

  Um campo de bits que pode ser usado para controlar certos comportamentos com datas de início e fim.

  Com `DatePeriod::EXCLUDE_START_DATE` exclui-se a data inicial do conjunto de datas recorrentes dentro do período.

  Com `DatePeriod::INCLUDE_END_DATE` inclui-se a data final do conjunto de datas recorrentes dentro do período.

### Erros/Exceções

Lança uma exceção DateMalformedPeriodStringException quando o parâmetro `isostr` não puder ser interpretado como um período ISO 8601 válido. Antes do PHP 8.3, isto era uma Exception.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | A assinatura que usa `isostr` foi descontinuada, use DatePeriod::createFromISO8601String() em seu lugar.
8.3.0 | Agora dispara DateMalformedPeriodStringException em vez de Exception.
8.2.0 | A constante `DatePeriod::INCLUDE_END_DATE` foi incluída.
7.2.19, 7.3.6, 7.4.0 | O parâmetro `recurrences` agora deve ser maior que `0`.

### Exemplos

Exemplo #1 Exemplos de DatePeriod

    <?php
    $inicio = new DateTime('2012-07-01');
    $intervalo = new DateInterval('P7D');
    $fim = new DateTime('2012-07-31');
    $recorrencias = 4;
    $iso = 'R4/2012-07-01T00:00:00Z/P7D';

    // Todos estes períodos são equivalentes.
    $periodo = new DatePeriod($inicio, $intervalo, $recorrencias);
    $periodo = new DatePeriod($inicio, $intervalo, $fim);
    $periodo = new DatePeriod($iso);

    // Ao iterar sobre o objeto DatePeriod, todas as
    // datas recorrentes dentro do período são exibidas.
    foreach ($periodo as $data) {
        echo $data->format('Y-m-d')."\n";
    }

O exemplo acima produzirá:

    Deprecated: Calling DatePeriod::__construct(string $isostr, int $options = 0) is deprecated, use DatePeriod::createFromISO8601String() instead in script on line 11
    2012-07-01
    2012-07-08
    2012-07-15
    2012-07-22
    2012-07-29

Exemplo #2 Exemplo de DatePeriod com `DatePeriod::EXCLUDE_START_DATE`

    <?php
    $inicio = new DateTime('2012-07-01');
    $intervalo = new DateInterval('P7D');
    $fim = new DateTime('2012-07-31');

    $periodo = new DatePeriod($inicio, $intervalo, $fim,
                             DatePeriod::EXCLUDE_START_DATE);

    // Ao iterar sobre o objeto DatePeriod, todas as
    // datas recorrentes dentro do período são exibidas.
    // Note que, neste caso, 2012-07-01 não é mostrada.
    foreach ($periodo as $data) {
        echo $data->format('Y-m-d')."\n";
    }

O exemplo acima produzirá:

    2012-07-08
    2012-07-15
    2012-07-22
    2012-07-29

Exemplo #3 Exemplo de DatePeriod mostrando todas as últimas quintas-feiras do ano

    <?php
    $inicio = new DateTime('2021-12-31');
    $fim = new DateTime('2022-12-31 23:59:59');

    $intervalo = DateInterval::createFromDateString('last thursday of next month');
    $periodo = new DatePeriod($inicio, $intervalo, $fim, DatePeriod::EXCLUDE_START_DATE);

    foreach ($periodo as $data) {
        echo $data->format('l Y-m-d'), "\n";
    }

O exemplo acima produzirá:

    Thursday 2022-01-27
    Thursday 2022-02-24
    Thursday 2022-03-31
    Thursday 2022-04-28
    Thursday 2022-05-26
    Thursday 2022-06-30
    Thursday 2022-07-28
    Thursday 2022-08-25
    Thursday 2022-09-29
    Thursday 2022-10-27
    Thursday 2022-11-24
    Thursday 2022-12-29

### Notas

Npumeros de repetições não vinculados como especificado pela ISO 8601 seção 4.5 "Recurring time interval" não são suportados, ex.: nem passando passando `"R/..."` como parâmetro `isostr` nem passando `null` como parâmetro `end` funcionaria.

# DatePeriod::createFromISO8601String

(PHP 8 >= 8.3.0)

DatePeriod::createFromISO8601String — Cria um novo objeto DatePeriod a partir de uma string ISO8601

### Descrição

public static function DatePeriod::createFromISO8601String(string `$specification`, int `$options` = 0): static

Cria um novo objeto DatePeriod a partir de uma string ISO8601, como especificado no parâmetro `specification`.

### Parâmetros

`specification`

  Um subconjunto da » especificação ISO 8601 de intervalos repetitivos.

  Um exemplo de uma especificação de intervalo ISO 8601 aceitável é `R5/2008-03-01T13:00:00Z/P1Y2M10DT2H30M`, que especifica:

  - 5 iterações (`R5/`)
  - Inicia em `2008-03-01T13:00:00Z`.
  - Cada iteração ocorrem em um intervalo de 1 ano, 2 meses, 10 dias, 2 horas e 30 minutos (`/P1Y2M10DT2H30M`).

  Exemplo de recursos de especificação de intervalos ISO 8601 que o PHP não suporta são:

  1. zero ocorrências (`R0/`)
  2. deslocamento de fuso horário que não seja UTC (`Z`), como em `+02:00`.
`options`

  Um campo de bits que pode ser utilizado para controlar certos comportamentos com datas iniciais e finais.

  Com `DatePeriod::EXCLUDE_START_DATE`, pode-se excluir a data inicial do conjunto de datas recorrentes dentro do período.

  Com `DatePeriod::INCLUDE_END_DATE`, pode-se incluir a data final no conjunto de datas recorrentes dentro do período.

### Valor Retornado

Retorna um novo objeto DatePeriod.

Objetos DatePeriod criados com este método podem ser usador como um iterador para gerar um número de objetos DateTimeImmutable.

### Erros/Exceções

Lanã uma DateMalformedPeriodStringException quando o parâmetro `specification` não puder ser analisado como um período ISO 8601 válido.

### Exemplos

Exemplo #1 Exemplo de DatePeriod::createFromISO8601String

    <?php
    $iso = 'R4/2023-07-01T00:00:00Z/P7D';
    $period = DatePeriod::createFromISO8601String($iso);

    // Iterando pelo objeto DatePeriod, todas as
    // datas recorrentes dentro do período são exibidas.
    foreach ($period as $date) {
        echo $date->format('Y-m-d'), "\n";
    }

O exemplo acima produzirá:

    2023-07-01
    2023-07-08
    2023-07-15
    2023-07-22
    2023-07-29

# DatePeriod::getDateInterval

(PHP 5 >= 5.6.5, PHP 7, PHP 8)

DatePeriod::getDateInterval — Obtém o intervalo

### Descrição

Estilo orientado a objetos

public function DatePeriod::getDateInterval(): DateInterval

Obtém um object da classe DateInterval representando o intervalo usado para o período.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um object DateInterval.

### Exemplos

Exemplo #1 Exemplo de DatePeriod::getDateInterval()

    <?php
    $period = DatePeriod::createFromIso8601String('R7/2016-05-16T00:00:00Z/P1D');
    $interval = $period->getDateInterval();
    echo $interval->format('%d day');

O exemplo acima produzirá:

    1 day

### Veja Também

- DatePeriod::getStartDate() - Obtém a data inicial
- DatePeriod::getEndDate() - Obtém a data final

# DatePeriod::getEndDate

(PHP 5 >= 5.6.5, PHP 7, PHP 8)

DatePeriod::getEndDate — Obtém a data final

### Descrição

Estilo orientado a objetos

public function DatePeriod::getEndDate(): ?DateTimeInterface

Obtém a data final do período.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `null` se o DatePeriod não tiver uma data final. Por exemplo, quando inicializado com o parâmetro `recurrences` ou `isostr` sem uma data final.

Retorna um object DateTimeImmutable quando o DatePeriod é inicializado com um object DateTimeImmutable no parâmetro `end`.

Caso contrário, retorna um clone do object DateTime representando a data final.

### Exemplos

Exemplo #1 Exemplo de DatePeriod::getEndDate()

    <?php
    $period = new DatePeriod(
        new DateTime('2016-05-16T00:00:00Z'),
        new DateInterval('P1D'),
        new DateTime('2016-05-20T00:00:00Z')
    );
    $start = $period->getEndDate();
    echo $start->format(DateTime::ISO8601);

Os exemplos acima produzirão:

    2016-05-20T00:00:00+0000

Exemplo #2 Exemplo de DatePeriod::getEndDate() sem uma data final

    <?php
    $period = new DatePeriod(
        new DateTime('2016-05-16T00:00:00Z'),
        new DateInterval('P1D'),
        7
    );
    var_dump($period->getEndDate());

O exemplo acima produzirá:

    NULL

### Veja Também

- DatePeriod::getStartDate() - Obtém a data inicial
- DatePeriod::getDateInterval() - Obtém o intervalo

# DatePeriod::getRecurrences

(PHP 7 >= 7.2.17/7.3.4, PHP 8)

DatePeriod::getRecurrences — Obtém o número de recorrências

### Descrição

Estilo orientado a objetos

public function DatePeriod::getRecurrences(): ?int

Obtém o número de recorrências.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O número de recorrências como definido explicitamente pelo parâmetro `$recurrences` passado ao construtor da classe DatePeriod, ou `null` caso não tenha sido definido.

### Exemplos

Exemplo #1 Diferentes valores para DatePeriod::getRecurrences()

    <?php
    $start = new DateTime('2018-12-31 00:00:00');
    $end   = new DateTime('2021-12-31 00:00:00');
    $interval = new DateInterval('P1M');
    $recurrences = 5;

    // recorrências definidas explicitamente através do construtor
    $period = new DatePeriod($start, $interval, $recurrences, DatePeriod::EXCLUDE_START_DATE);
    echo $period->getRecurrences(), "\n";

    $period = new DatePeriod($start, $interval, $recurrences);
    echo $period->getRecurrences(), "\n";

    $period = new DatePeriod($start, $interval, $recurrences, DatePeriod::INCLUDE_END_DATE);
    echo $period->getRecurrences(), "\n\n";

    // recorrências não definidas no construtor
    $period = new DatePeriod($start, $interval, $end);
    var_dump($period->getRecurrences());

    $period = new DatePeriod($start, $interval, $end, DatePeriod::EXCLUDE_START_DATE);
    var_dump($period->getRecurrences());

O exemplo acima produzirá:

    5
    5
    5

    NULL
    NULL

### Veja Também

- DatePeriod::$recurrences

# DatePeriod::getStartDate

(PHP 5 >= 5.6.5, PHP 7, PHP 8)

DatePeriod::getStartDate — Obtém a data inicial

### Descrição

Estilo orientado a objetos

public function DatePeriod::getStartDate(): DateTimeInterface

Obtém a data inicial do período.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um object DateTimeImmutable quando o DatePeriod é inicializado com um object DateTimeImmutable no parâmetro `start`.

Caso contrário, retorna um object DateTime.

### Exemplos

Exemplo #1 Exemplo de DatePeriod::getStartDate()

    <?php
    $period = DatePeriod::createFromIso8601String('R7/2016-05-16T00:00:00Z/P1D');
    $start = $period->getStartDate();
    echo $start->format(DateTime::ISO8601);

O exemplo acima produzirá:

    2016-05-16T00:00:00+0000

### Veja Também

- DatePeriod::getEndDate() - Obtém a data final
- DatePeriod::getDateInterval() - Obtém o intervalo

## Índice

- DatePeriod::__construct — Cria um novo objeto DatePeriod
- DatePeriod::createFromISO8601String — Cria um novo objeto DatePeriod a partir de uma string ISO8601
- DatePeriod::getDateInterval — Obtém o intervalo
- DatePeriod::getEndDate — Obtém a data final
- DatePeriod::getRecurrences — Obtém o número de recorrências
- DatePeriod::getStartDate — Obtém a data inicial

# Funções de Data/Horário

# checkdate

(PHP 4, PHP 5, PHP 7, PHP 8)

checkdate — Valida uma data gregoriana

### Descrição

function checkdate(int `$month`, int `$day`, int `$year`): bool

Verifica a validade da data formada pelos argumentos. Uma data é considerada válida se cada parâmetro é adequadamente definido.

### Parâmetros

`month`

  O mês entre 1 e 12.

`day`

  O dia está dentro do número permitido de dias para o mês (`month`). Anos (`year`) bissextos são levados em consideração.

`year`

  O ano está entre 1 e 32767, inclusive.

### Valor Retornado

Retorna `true` se a data informada é valida; caso contrário retorna `false`.

### Exemplos

Exemplo #1 Exemplo de checkdate()

    <?php
    var_dump(checkdate(12, 31, 2000));
    var_dump(checkdate(2, 29, 2001));

O exemplo acima produzirá:

    bool(true)
    bool(false)

### Veja Também

- mktime() - Obtém um timestamp Unix de uma data
- strtotime() - Interpreta qualquer descrição textual de data/horário em inglês para timestamp Unix

# date

(PHP 4, PHP 5, PHP 7, PHP 8)

date — Formata um timestamp Unix

### Descrição

function date(string `$format`, ?int `$timestamp` = `null`): string

Retorna uma string de acordo com a string de formato informada usando o inteiro `timestamp` (timestamp Unix) informado, ou o horário local atual se nenhum timestamp for informado. Em outras palavras, o parâmetro `timestamp` é opcional e padronizado para o valor de time().

Aviso

Timestamps Unix não lidam com fusos horários. Use a classe DateTimeImmutable e seu método de formatação DateTimeInterface::format() para formatar informações de data/horário com um fuso horário anexado.

### Parâmetros

`format`

  Formato aceito pelo DateTimeInterface::format().

  > Nota: date() irá sempre gerar `000000` para os microssegundos já que ele usa um parâmetro int, enquanto que DateTimeInterface::format() suporta microssegundos se um objeto do tipo DateTimeInterface foi criado com microssegundos.

`timestamp`
  O parâmetro opcional `timestamp` é um int de timestamp Unix cujo padrão é a hora local atual se `timestamp` não for informado ou for `null`. Em outras palavras, o padrão é o valor de time().

### Valor Retornado

Retorna uma string formatada de data.

### Erros/Exceções

Toda chamada a uma função de data/hora gerará um `E_WARNING` se o fuso horário não for válido. Veja também date_default_timezone_set()

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `timestamp` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplos da função date()

    <?php
    // Modifica o fuso horário a ser utilizado.
    date_default_timezone_set('UTC');

    // Exibe algo coisa como: Monday
    echo date("l") . "\n";

    // Exibe algo como: Monday 8th of August 2005 03:12:46 PM
    echo date('l jS \of F Y h:i:s A') . "\n";

    // Exibe: July 1, 2000 is on a Saturday
    echo "July 1, 2000 is on a " . date("l", mktime(0, 0, 0, 7, 1, 2000)) . "\n";

    /* Utiliza as constantes do parâmetro de formato */
    // Exibe algo como: Mon, 15 Aug 2005 15:12:46 UTC
    echo date(DATE_RFC2822) . "\n";

    // Exibe algo como: 2000-07-01T00:00:00+00:00
    echo date(DATE_ATOM, mktime(0, 0, 0, 7, 1, 2000));

Para evitar que um caractere reconhecido na string de formatação seja expandido, prefixe-o com uma barra invertida. Se o caractere com a barra invertida já for uma sequência especial, pode ser necessário também prefixá-lo com a barra invertida.

Exemplo #2 Caracteres de escape em date()

    <?php
    // Exibe algo como: Wednesday the 15th
    echo date("l \\t\h\e jS");

Alguns exemplos de formatação de date(). Observe que qualquer outro caractere deve ser escapado, pois qualquer um que possua um significado especial produzirá resultados indesejáveis, e outros caracteres podem assumir significado em futuras versões do PHP. Quando usar escape, certifique-se de usar aspas simples para evitar que caracteres como \n virem novas linhas.

Exemplo #3 Formatação com a função date()

    <?php
    // Assumindo que hoje é dia 10 de março de 2001, 17:16:18, e que estamos no
    // fuso horário Mountain Standard Time (MST)
    date_default_timezone_set("America/Phoenix");

    $today = date("F j, Y, g:i a") . "\n";                 // March 10, 2001, 5:16 pm
    $today = date("m.d.y") . "\n";                         // 03.10.01
    $today = date("j, n, Y") . "\n";                       // 10, 3, 2001
    $today = date("Ymd") . "\n";                           // 20010310
    $today = date('h-i-s, j-m-y, it is w Day') . "\n";     // 05-16-18, 10-03-01, 1631 1618 6 Satpm01
    $today = date('\i\t \i\s \t\h\e jS \d\a\y.') . "\n";   // it is the 10th day.
    $today = date("D M j G:i:s T Y") . "\n";               // Sat Mar 10 17:16:18 MST 2001
    $today = date('H:m:s \m \i\s\ \m\o\n\t\h') . "\n";     // 17:03:18 m is month
    $today = date("H:i:s") . "\n";                         // 17:16:18
    $today = date("Y-m-d H:i:s") . "\n";                   // 2001-03-10 17:16:18 (o formato DATETIME do MySQL)

Para formatar datas em outros idiomas, IntlDateFormatter::format() pode ser utilizada em vez de date().

### Notas

> Nota:

> Para gerar um timestamp de uma string da representação da data, pode-se utilizar as funções strtotime(). Adicionalmente, alguns banco de dados tem funções para converter os formatos de data para timestamps (como a função » UNIX_TIMESTAMP do MySQL).

Dica

O timestamp do início da requisição está disponível na variável $_SERVER['REQUEST_TIME'].

### Veja Também

- DateTimeImmutable::__construct() - Retorna um novo objeto DateTimeImmutable
- DateTimeInterface::format() - Retorna a data formatada de acordo com um formato informado
- gmdate() - Formata uma data/horário GMT/CUT
- idate() - Formata uma parte de uma data/horário local como um inteiro
- getdate() - Recupera informações de data/horário
- getlastmod() - Obtém o horário da última modificação na página
- mktime() - Obtém um timestamp Unix de uma data
- IntlDateFormatter::format() - Formata data/horário como uma string
- time() - Retorna o timestamp Unix atual
- Constantes Predefinidas da Classe DateTime

# date_add

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_add — Sinônimo de DateTime::add()

### Descrição

Esta função é um apelido para: DateTime::add()

# date_create

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_create — Cria um novo objeto DateTime

### Descrição

function date_create(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`): DateTime|false

Esta é a versão procedural de DateTime::__construct().

Diferentemente do construtor de DateTime, irá retornar `false` em vez de uma exceção se a string `datetime` for inválida.

### Parâmetros

Ver DateTimeImmutable::__construct.

### Valor Retornado

Retorna uma nova instância de DateTime ou `false` em caso de falha

### Veja Também

- DateTimeImmutable::__construct() - Retorna um novo objeto DateTimeImmutable
- DateTimeImmutable::createFromFormat() - Interpreta um string de data/horário de acordo com o formato especificado
- DateTime::__construct() - Retorna um novo objeto DateTime

# date_create_from_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_create_from_format — Sinônimo de DateTime::createFromFormat()

### Descrição

Esta função é um apelido para: DateTime::createFromFormat()

# date_create_immutable

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

date_create_immutable — Cria um novo objeto DateTimeImmutable

### Descrição

function date_create_immutable(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`): DateTimeImmutable|false

Esta é a versão procedural de DateTimeImmutable::__construct().

Diferentemente do construtor de DateTimeImmutable, irá retornar `false` em vez de uma exceção se a string `datetime` for inválida.

### Parâmetros

Ver DateTimeImmutable::__construct.

### Valor Retornado

Retorna uma nova instância de DateTimeImmutable ou `false` em caso de falha

### Veja Também

- DateTimeImmutable::createFromFormat() - Interpreta um string de data/horário de acordo com o formato especificado

# date_create_immutable_from_format

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

date_create_immutable_from_format — Sinônimo de DateTimeImmutable::createFromFormat()

### Descrição

Esta função é um apelido para: DateTimeImmutable::createFromFormat()

# date_date_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_date_set — Sinônimo de DateTime::setDate()

### Descrição

Esta função é um apelido para: DateTime::setDate()

# date_default_timezone_get

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

date_default_timezone_get — Retorna o fuso horário padrão usado por todas as funções de data/horário em um script

### Descrição

function date_default_timezone_get(): string

Em ordem de preferência, essa função retorna o fuso horário padrão:

- Lendo o fuso horário configurado pela função date_default_timezone_set() (se existir)

- Lendo o valor da opção date.timezone do arquivo INI (se configurada)

Se nenhuma das opções acima tiver êxito, a função date_default_timezone_get() retornará o fuso horário padrão `UTC`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string.

### Exemplos

Exemplo #1 Lendo o fuso horário padrão

    <?php
    date_default_timezone_set('Europe/London');

    if (date_default_timezone_get()) {
        echo 'date_default_timezone_set: ' . date_default_timezone_get() . "\n";
    }

    if (ini_get('date.timezone')) {
        echo 'date.timezone: ' . ini_get('date.timezone');
    }

O exemplo acima produzirá algo semelhante a:

    date_default_timezone_set: Europe/London
    date.timezone: Europe/London

Exemplo #2 Lendo a abreviação de um fuso horário

    <?php
    date_default_timezone_set('America/Los_Angeles');
    echo date_default_timezone_get() . ' => ' . date('e') . ' => ' . date('T');

O exemplo acima produzirá:

    America/Los_Angeles => America/Los_Angeles => PST

### Veja Também

- date_default_timezone_set() - Configura o fuso horário padrão utilizado por todas as funções de data/horário em um script
- Lista de Fusos Horários Suportados

# date_default_timezone_set

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

date_default_timezone_set — Configura o fuso horário padrão utilizado por todas as funções de data/horário em um script

### Descrição

function date_default_timezone_set(string `$timezoneId`): bool

date_default_timezone_set() configura o fuso horário padrão utilizado por todas as funções de data e hora.

Em vez de utilizar essa função para definir o fuso horário padrão no script, a configuração INI date.timezone também pode ser usada para configurar o fuso horário padrão.

### Parâmetros

`timezoneId`

  O identificador do fuso horário, como `UTC`, `Africa/Lagos`, `Asia/Hong_Kong`, ou `Europe/Lisbon`. A lista de identificadores válidos está disponível em Lista de Fusos Horários Suportados.

### Valor Retornado

A função retorna `false` se o `timezoneId` não for válido, ou `true` caso contrário.

### Exemplos

Exemplo #1 Lendo o fuso horário padrão

    <?php
    date_default_timezone_set('America/Los_Angeles');

    $script_tz = date_default_timezone_get();
    $ini_tz = ini_get('date.timezone');

    if (strcmp($script_tz, $ini_tz)){
        echo 'Fuso horário do script é diferente do definido no INI.';
    } else {
        echo 'Fuso horário do script corresponde ao definido no INI.';
    }

### Veja Também

- date_default_timezone_get() - Retorna o fuso horário padrão usado por todas as funções de data/horário em um script
- Lista de Fusos Horários Suportados

# date_diff

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_diff — Sinônimo de DateTime::diff()

### Descrição

Esta função é um apelido para: DateTime::diff()

# date_format

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_format — Sinônimo de DateTime::format()

### Descrição

Esta função é um apelido para: DateTime::format()

# date_get_last_errors

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_get_last_errors — Sinônimo de DateTimeImmutable::getLastErrors()

### Descrição

Esta função é um apelido para: DateTimeImmutable::getLastErrors()

# date_interval_create_from_date_string

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_interval_create_from_date_string — Sinônimo de DateInterval::createFromDateString()

### Descrição

Esta função é um apelido para: DateInterval::createFromDateString()

# date_interval_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_interval_format — Sinônimo de DateInterval::format()

### Descrição

Esta função é um apelido para: DateInterval::format()

# date_isodate_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_isodate_set — Sinônimo de DateTime::setISODate()

### Descrição

Esta função é um apelido para: DateTime::setISODate()

# date_modify

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_modify — Sinônimo de DateTime::modify()

### Descrição

Esta função é um apelido para: DateTime::modify()

# date_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_offset_get — Sinônimo de DateTime::getOffset()

### Descrição

Esta função é um apelido para: DateTime::getOffset()

# date_parse

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_parse — Retorna um array associativo com informações detalhadas da data/horário informada

### Descrição

function date_parse(string `$datetime`): array

A função date_parse() analisa a string `datetime` informada conforme as mesmas regras de strtotime() e DateTimeImmutable::__construct(). Ao invés de retornar um timestamp Unix (com strtotime()) ou objeto DateTimeImmutable (com a função DateTimeImmutable::__construct()), ela retorna um array associativo com a informação que ela poderia detectar na string `datetime` fornecida.

Se nenhuma informação sobre um certo grupo de elementos puder ser encontrada, estes elementos do array serão configurados para `false` ou omitidos. Se necessário para construção de um timestamp ou objeto DateTimeImmutable a partir da mesma string `datetime`, mais campos podem ser configurados para um valor não-`false`. Veja os exemplos para casos onde isso acontece..

### Parâmetros

`datetime`

  Data/horário no formato aceito pela função DateTimeImmutable::__construct().

### Valor Retornado

Retorna um array com informações da data/horário analisada.

O array de retorno tem chaves para `year`, `month`, `day`, `hour`, `minute`, `second`, `fraction`, e `is_localtime`.

Se `is_localtime` estiver presente então `zone_type` indica o tipo do fuso horário. Para o tipo `1` (deslocamento UTC), os campos `zone` e `is_dst` são incluídos; para o tipo `2` (abreviação), os campos `tz_abbr` e `is_dst` são incluídos; e para tipo `3` (identificador de fuso), os campos `tz_abbr` e `tz_id` são incluídos.

Se elementos de tempo relativo estiverem presentes na string `datetime` como `+3 days`, então o array retornado incluirá um array aninhado com a chave `relative`. Este array então conterá as chaves `year`, `month`, `day`, `hour`, `minute`, `second`, e se necessário `weekday` e `weekdays`, dependendo da string que foi passada.

O array inclui os campos `warning_count` e `warnings`. O primeiro indica quantos avisos ocorreram. As chaves dos elementos do array `warnings` indicam as posições na string `datetime` onde os avisos ocorreram, com o valor da string descrevendo o aviso em si.

O array também contém os campos `error_count` e `errors`. O primeiro indica quantos erros foram encontrados. As chaves dos elementos do array `errors` indicam posição na string `datetime` onde os erros ocorreram, com o valor da string descrevendo o erro em si.

Aviso

O número de elementos do arrays `warnings` ou `errors` pode ser menor que `warning_count` ou `error_count` se eles ocorreram na mesma posição.

### Erros/Exceções

Se o formato da data/horário contiver erro, o elemento 'errors' conterá as mensagens de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
7.2.0 | O elemento `zone` do array de retorno agora representa segundos no lugar de minutos, e seu sinal é invertido. Por exemplo, `-120` é agora `7200`.

### Exemplos

Exemplo #1 Um exemplo da função date_parse()com um string `datetime` compreensivo

    <?php
    var_dump(date_parse("2006-12-12 10:00:00.5"));

O exemplo acima produzirá:

    array(12) {
      ["year"]=>
      int(2006)
      ["month"]=>
      int(12)
      ["day"]=>
      int(12)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(0)
      ["second"]=>
      int(0)
      ["fraction"]=>
      float(0.5)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
    }

Os elementos de fuso horário só aparecem se eles forem incluídos no parâmetro `datetime`. Neste caso sempre haverá um elemento `zone_type` e alguns mais dependendo do seu valor.

Exemplo #2 Exemplo da função date_parse() com informação de abreviação de fuso horário

    <?php
    var_dump(date_parse("June 2nd, 2022, 10:28:17 BST"));

O exemplo acima produzirá:

    array(16) {
      ["year"]=>
      int(2022)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(28)
      ["second"]=>
      int(17)
      ["fraction"]=>
      float(0)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(true)
      ["zone_type"]=>
      int(2)
      ["zone"]=>
      int(0)
      ["is_dst"]=>
      bool(true)
      ["tz_abbr"]=>
      string(3) "BST"
    }

Exemplo #3 Exemplo da função date_parse() com informação de identificador de fuso horário

    <?php
    var_dump(date_parse("June 2nd, 2022, 10:28:17 Europe/London"));

O exemplo acima produzirá:

    array(14) {
      ["year"]=>
      int(2022)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(28)
      ["second"]=>
      int(17)
      ["fraction"]=>
      float(0)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(true)
      ["zone_type"]=>
      int(3)
      ["tz_id"]=>
      string(13) "Europe/London"
    }

Se uma string mais enxuta de `datetime` for analisada, menos informação estará disponível. Neste exemplo, todas as partes de horário são retornadas como `false`.

Exemplo #4 Função date_parse() com um string minimizado

    <?php
    var_dump(date_parse("June 2nd, 2022"));

O exemplo acima produzirá:

    array(12) {
      ["year"]=>
      int(2022)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      bool(false)
      ["minute"]=>
      bool(false)
      ["second"]=>
      bool(false)
      ["fraction"]=>
      bool(false)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
    }

Formatos relativos não influenciam valores interpretados de formatos absolutos, mas são analisados no elemento "relative".

Exemplo #5 date_parse() com formatos relativos

    <?php
    var_dump(date_parse("2006-12-12 10:00:00.5 +1 week +1 hour"));

O exemplo acima produzirá:

    array(13) {
      ["year"]=>
      int(2006)
      ["month"]=>
      int(12)
      ["day"]=>
      int(12)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(0)
      ["second"]=>
      int(0)
      ["fraction"]=>
      float(0.5)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
      ["relative"]=>
      array(6) {
        ["year"]=>
        int(0)
        ["month"]=>
        int(0)
        ["day"]=>
        int(7)
        ["hour"]=>
        int(1)
        ["minute"]=>
        int(0)
        ["second"]=>
        int(0)
      }
    }

Algumas strings, como `Thursday` por exemplo, irão configurar a parte de horário da string para `0`. Se `Thursday` for passado para a função DateTimeImmutable::__construct(), ela também teria resultado em hora, minuto, segundo e fração configurados para `0`. No exemplo abaixo, o elemento do ano também é configurado como `false`.

Exemplo #6 Função date_parse() com efeitos colaterais

    <?php
    var_dump(date_parse("Thursday, June 2nd"));

O exemplo acima produzirá:

    array(13) {
      ["year"]=>
      bool(false)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      int(0)
      ["minute"]=>
      int(0)
      ["second"]=>
      int(0)
      ["fraction"]=>
      float(0)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
      ["relative"]=>
      array(7) {
        ["year"]=>
        int(0)
        ["month"]=>
        int(0)
        ["day"]=>
        int(0)
        ["hour"]=>
        int(0)
        ["minute"]=>
        int(0)
        ["second"]=>
        int(0)
        ["weekday"]=>
        int(4)
      }
    }

### Veja Também

- date_parse_from_format() - Retorna informações sobre uma data informada de acordo com um formato para analisar um `datetime` com um formato específico
- checkdate() - Valida uma data gregoriana para validação da data do calendário gregoriano
- getdate() - Recupera informações de data/horário

# date_parse_from_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_parse_from_format — Retorna informações sobre uma data informada de acordo com um formato

### Descrição

function date_parse_from_format(string `$format`, string `$datetime`): array

Retorna um array associativo com informação detalhada sobre a data/horário informada.

### Parâmetros

`format`

  Para documentação sobre como o parâmetro `format` é usado, favor se referir à documentação da função DateTimeImmutable::createFromFormat(). As mesmas regras se aplicam.

`datetime`

  String que representa a data/horário.

### Valor Retornado

Retorna um array associativo com informação detalhada da data/horário informada.

O array de retorno tem chaves para `year`, `month`, `day`, `hour`, `minute`, `second`, `fraction`, e `is_localtime`.

Se `is_localtime` estiver presente então `zone_type` indica o tipo do fuso horário. Para o tipo `1` (deslocamento UTC), os campos `zone` e `is_dst` são incluídos; para o tipo `2` (abreviação), os campos `tz_abbr` e `is_dst` são incluídos; e para tipo `3` (identificador de fuso), os campos `tz_abbr` e `tz_id` são incluídos.

O array inclui os campos `warning_count` e `warnings`. O primeiro indica quantos avisos ocorreram. As chaves dos elementos do array `warnings` indicam as posições na string `datetime` onde os avisos ocorreram, com o valor da string descrevendo o aviso em si. Um exemplo abaixo mostra tal aviso.

O array também contém os campos `error_count` e `errors`. O primeiro indica quantos erros foram encontrados. As chaves dos elementos do array `errors` indicam posição na string `datetime` onde os erros ocorreram, com o valor da string descrevendo o erro em si. Um exemplo abaixo mostra tal erro.

Aviso

O número de elementos do arrays `warnings` ou `errors` pode ser menor que `warning_count` ou `error_count` se eles ocorreram na mesma posição.

### Erros/Exceções

Esta função dispara a exceção ValueError quando o parâmetro `datetime` contém bytes nulos.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.21, 8.1.8, 8.2.0 | Agora lança ValueError quando bytes nulos são passados por `datetime`, o que antes era silenciosamente ignorado.
7.2.0 | O elemento `zone` do array retornado agora representa segundos em vez de minutos, e seu sinal é invertido. Por exemplo, `-120` agora é `7200`.

### Exemplos

Exemplo #1 Exemplo da função date_parse_from_format()

    <?php
    $date = "6.1.2009 13:00+01:00";
    print_r(date_parse_from_format("j.n.Y H:iP", $date));

O exemplo acima produzirá:

    Array
    (
        [year] => 2009
        [month] => 1
        [day] => 6
        [hour] => 13
        [minute] => 0
        [second] => 0
        [fraction] => 0
        [warning_count] => 0
        [warnings] => Array
            (
            )

        [error_count] => 0
        [errors] => Array
            (
            )

        [is_localtime] => 1
        [zone_type] => 1
        [zone] => 3600
        [is_dst] =>
    )

Exemplo #2 Exemplo da função date_parse_from_format() com avisos

    <?php
    $date = "26 August 2022 22:30 pm";
    $parsed = date_parse_from_format("j F Y G:i a", $date);

    echo "Contagem de avisos: ", $parsed['warning_count'], "\n";
    foreach ($parsed['warnings'] as $position => $message) {
        echo "\tNa posição {$position}: {$message}\n";
    }

O exemplo acima produzirá:

    Contagem de avisos: 1
    Na posição 23: The parsed time was invalid

Exemplo #3 Exemplo da função date_parse_from_format() com erros

    <?php
    $date = "26 August 2022 CEST";
    $parsed = date_parse_from_format("j F Y H:i", $date);

    echo "Contagem de erros: ", $parsed['error_count'], "\n";
    foreach ($parsed['errors'] as $position => $message) {
        echo "\tNa posição {$position}: {$message}\n";
    }

O exemplo acima produzirá:

    Contagem de erros: 3
    Na posição 15: A two digit hour could not be found
    Na posição 19: Not enough data available to satisfy format

### Veja Também

- DateTimeImmutable::createFromFormat() - Interpreta um string de data/horário de acordo com o formato especificado
- checkdate() - Valida uma data gregoriana

# date_sub

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_sub — Sinônimo de DateTime::sub()

### Descrição

Esta função é um apelido para: DateTime::sub()

### Veja Também

- DateTimeImmutable::sub() - Subtrai uma quantidade de dias, meses, anos, horas, minutos e segundos
- DateTime::sub() - Subtrai uma quantidade de dias, meses, anos, horas, minutos e segundos de um objeto DateTime

# date_sun_info

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

date_sun_info — Retorna um array com informações sobre pôr/nascer do sol e o início/fim do dia

### Descrição

function date_sun_info(int `$timestamp`, float `$latitude`, float `$longitude`): array

### Parâmetros

`timestamp`

  Timestamp Unix.

`latitude`

  Latitude em graus.

`longitude`

  Longitude em graus.

### Valor Retornado

Retorna um cuja estrutura é detalhada na lista abaixo:

`sunrise`
  O timestamp do nascer do sol (ângulo em relação ao zênite = 90°35').
`sunset`
  O timestamp do pôr do sol (ângulo em relação ao zênite = 90°35').
`transit`
  O timestamp quando o sol está em seu zênite, ou seja, atingiu seu ponto mais alto.
`civil_twilight_begin`
  O início do amanhecer civil (ângulo em relação ao zênite = 96°). Termina no `sunrise`.
`civil_twilight_end`
  O final do crepúsculo civil (ângulo em relação ao zênite = 96°). Começa no `sunset`.
`nautical_twilight_begin`
  O início do amanhecer náutico (ângulo em relação ao zênite = 102°). Termina no `civil_twilight_begin`.
`nautical_twilight_end`
  O final do crepúsculo náutico (ângulo em relação ao zênite = 102°). Começa no `civil_twilight_end`.
`astronomical_twilight_begin`
  O início do amanhecer astronômico (ângulo em relação ao zênite = 108°). Termina no `nautical_twilight_begin`.
`astronomical_twilight_end`
  O final do crepúsculo astronômico (ângulo em relação ao zênite = 108°). Começa no `nautical_twilight_end`.

Os valores dos elementos do array podem ser timestamps UNIX, `false` se o sol estiver abaixo do respectivo ângulo durante todo o dia, ou `true` se o sol estiver acima do respectivo ângulo durante todo o dia.

### Registro de Alterações

Versão | Descrição
--- | ---
7.2.0 | Os cálculos foram corrigidos com base na meia-noite local em vez do meio-dia local, o que muda os resultados um pouco.

### Exemplos

Exemplo #1 Um exemplo de date_sun_info()

    <?php
    $sun_info = date_sun_info(strtotime("2006-12-12"), 31.7667, 35.2333);
    foreach ($sun_info as $key => $val) {
        echo "$key: " . date("H:i:s", $val) . "\n";
    }

O exemplo acima produzirá:

    sunrise: 05:52:11
    sunset: 15:41:21
    transit: 10:46:46
    civil_twilight_begin: 05:24:08
    civil_twilight_end: 16:09:24
    nautical_twilight_begin: 04:52:25
    nautical_twilight_end: 16:41:06
    astronomical_twilight_begin: 04:21:32
    astronomical_twilight_end: 17:12:00

Exemplo #2 Noite polar, com algum processamento

    <?php
    $tz = new \DateTimeZone('America/Anchorage');

    $si = date_sun_info(strtotime("2022-12-21"), 70.21, -148.51);
    foreach ($si as $key => $value) {
        echo
            match ($value) {
                true => 'always',
                false => 'never',
                default => date_create("@{$value}")->setTimeZone($tz)->format( 'H:i:s T' ),
            },
            ": {$key}",
            "\n";
    }

O exemplo acima produzirá:

    never: sunrise
    never: sunset
    12:52:18 AKST: transit
    10:53:19 AKST: civil_twilight_begin
    14:51:17 AKST: civil_twilight_end
    09:01:47 AKST: nautical_twilight_begin
    16:42:48 AKST: nautical_twilight_end
    07:40:47 AKST: astronomical_twilight_begin
    18:03:49 AKST: astronomical_twilight_end

Exemplo #3 Sol da meia-noite (Tromsø, Norway)

    <?php
    $si = date_sun_info(strtotime("2022-06-26"), 69.68, 18.94);
    print_r($si);

O exemplo acima produzirá:

    Array
    (
        [sunrise] => 1
        [sunset] => 1
        [transit] => 1656240426
        [civil_twilight_begin] => 1
        [civil_twilight_end] => 1
        [nautical_twilight_begin] => 1
        [nautical_twilight_end] => 1
        [astronomical_twilight_begin] => 1
        [astronomical_twilight_end] => 1
    )

Exemplo #4 Calculando a duração do dia (Kiev)

    <?php
    $si = date_sun_info(strtotime('2022-08-26'), 50.45, 30.52);
    $diff = $si['sunset'] - $si['sunrise'];
    echo "Duração do dia: ",
        floor($diff / 3600), "h ",
        floor(($diff % 3600) / 60), "s\n";

O exemplo acima produzirá:

    Duração do dia: 13h 56s

# date_sunrise

(PHP 5, PHP 7, PHP 8)

date_sunrise — Retorna a hora do nascer do sol para um dia e uma localicação informados

Aviso

Esta função foi DESCONTINUADA desde o PHP 8.1.0. Confiar nesta função é altamente desencorajado. Use date_sun_info() no lugar.

### Descrição

#[\Deprecated]
function date_sunrise(
int `$timestamp`,
int `$returnFormat` = SUNFUNCS_RET_STRING,
?float `$latitude` = null,
?float `$longitude` = null,
?float `$zenith` = null,
?float `$utcOffset` = null
): string|int|float|false

A função date_sunrise() retorna a hora do nascer do sol para um dia (especificado como um `timestamp`) e uma localização informados.

### Parâmetros

`timestamp`

  O `timestamp` do nascer do sol do dia desejado.

`returnFormat`

  Constantes de `returnFormat`
  Constante | Descrição | Exemplo
  --- | --- | ---
  SUNFUNCS_RET_STRING | Retorna o resultado como uma string | 16:46
  SUNFUNCS_RET_DOUBLE | Retorna o resultado como um float | 16.78243132
  SUNFUNCS_RET_TIMESTAMP | Retorna o resultado como um int (timestamp) | 1095034606

`latitude`

  Padronizado para o norte, passe um valor negativo para o sul. Veja também: date.default_latitude

`longitude`

  Padronizado para o leste, passe um valor negativado para o oeste. Veja também: date.default_longitude

`zenith`

  `zenith` é o ângulo entre o centro do sol e uma linha perpendicular à superfície da Terra. É padronizado para date.sunrise_zenith

  Ângulos comuns em relação ao `zenith`
  Ângulo | Descrição
  --- | ---
  90°50' | Nascer do sol: o ponto onde o sol se torna visível.
  96° | Amanhecer civil: convencionado para significar o início do amanhecer.
  102° | Amanhecer náutico: o ponto no qual o horizonte começa a ficar visível no mar.
  108° | Amanhecer astronômico: o ponto no qual o sol começa a se tornar fonte de iluminação.

`utcOffset`

  Especificado em horas. O parâmetro `utcOffset` é ignorado se `returnFormat` for `SUNFUNCS_RET_TIMESTAMP`.

### Valor Retornado

Retorna o horário do nascer do sol no `returnFormat` especificado em caso de sucesso ou `false` em caso de falha. Um potencial motivo para falha é quando o sol não nasce, o que acontece dentro dos círculos polares durante parte do ano.

### Erros/Exceções

Toda chamada a uma função de data/hora gerará um `E_WARNING` se o fuso horário não for válido. Veja também date_default_timezone_set()

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Esta função foi descontinuada em favor de date_sun_info().
8.0.0 | `latitude`, `longitude`, `zenith` e `utcOffset` agora podem ser nulos.

### Exemplos

Exemplo #1 Exemplo da função date_sunrise()

    <?php

    /* Calcula o nascer do sol em Lisboa, Portugal
    Latitude: 38.4 norte
    Longitude: 9 oeste
    Zênite ~= 90
    deslocamento UTC: +01:00
    */

    echo date("D M d Y"). ', horário do nascer do sol : ' .date_sunrise(time(), SUNFUNCS_RET_STRING, 38.4, -9, 90, 1);

O exemplo acima produzirá algo semelhante a:

    Deprecated: Constant SUNFUNCS_RET_STRING is deprecated in script on line 10
    Deprecated: Function date_sunrise() is deprecated since 8.1, use date_sun_info() instead in script on line 10
    Mon Dec 20 2004, horário do nascer do sol : 08:54

Exemplo #2 Sem nascer do sol

    <?php
    $solstice = strtotime('2017-12-21');
    var_dump(date_sunrise($solstice, SUNFUNCS_RET_STRING, 69.245833, -53.537222));

O exemplo acima produzirá:

    Deprecated: Constant SUNFUNCS_RET_STRING is deprecated in script on line 3
    Deprecated: Function date_sunrise() is deprecated since 8.1, use date_sun_info() instead in script on line 3
    bool(false)

### Veja Também

- date_sun_info() - Retorna um array com informações sobre pôr/nascer do sol e o início/fim do dia

# date_sunset

(PHP 5, PHP 7, PHP 8)

date_sunset — Retorna a hora do pôr do sol para um dia e uma localização informados.

Aviso

Esta função foi DESCONTINUADA desde o PHP 8.1.0. Confiar nesta função é altamente desencorajado. Use date_sun_info() no lugar.

### Descrição

#[\Deprecated]
function date_sunset(
int `$timestamp`,
int `$returnFormat` = SUNFUNCS_RET_STRING,
?float `$latitude` = null,
?float `$longitude` = null,
?float `$zenith` = null,
?float `$utcOffset` = null
): string|int|float|false

A função date_sunset() retorna o horário do pôr do sol para um dia (especificado como um `timestamp`) e uma localização informados.

### Parâmetros

`timestamp`

  O `timestamp` do dia do pôr do sol desejado.

`returnFormat`

  Constantes de `returnFormat`
  Constante | Descrição | Exemplo
  --- | --- | ---
  SUNFUNCS_RET_STRING | Retorna o resultado como uma string | 16:46
  SUNFUNCS_RET_DOUBLE | Retorna o resultado como um float | 16.78243132
  SUNFUNCS_RET_TIMESTAMP | Retorna o resultado como um int (timestamp) | 1095034606

`latitude`

  Padronizado para o norte, passe um valor negativo para o sul. Veja também: date.default_latitude

`longitude`

  Padronizado para o leste, passe um valor negativo para o oeste. Veja também: date.default_longitude

`zenith`

  `zenith` é o ângulo entre o centro do sol e uma linha perpendicular à superfície da Terra. É padronizado para date.sunset_zenith

  Ângulos comuns em relação ao `zenith`
  Ângulo | Descrição
  --- | ---
  90°50' | Pôr do sol: o ponto onde o sol se torna invisível.
  96° | Crepúsculo civil: convencionado para significar o final do crepúsculo.
  102° | Crepúsculo náutico: o ponto no qual o horizonte termina de ficar visível no mar.
  108° | Crepúsculo astronômico: o ponto no qual o sol termina se tornar fonte de iluminação.

`utcOffset`

  Especificado em horas. O parâmetro `utcOffset` é ignorado se `returnFormat` for `SUNFUNCS_RET_TIMESTAMP`.

### Valor Retornado

Retorna o horário do pôr do sol no `returnFormat` especificado em caso de sucesso ou `false` em caso de falha. Um potencial motivo para falha é quando o sol não se põe, o que acontece dentro dos círculos polares durante parte do ano.

### Erros/Exceções

Toda chamada a uma função de data/hora gerará um `E_WARNING` se o fuso horário não for válido. Veja também date_default_timezone_set()

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Esta função foi descontinuada em favor de date_sun_info().
8.0.0 | `latitude`, `longitude`, `zenith` e `utcOffset` agora podem ser nulos.

### Exemplos

Exemplo #1 Exemplo da função date_sunset()

    <?php

    /* Calcula o horário do pôr do sol para Lisboa, Portugal
    Latitude: 38.4 norte
    Longitude: 9 oeste
    Zênite ~= 90
    deslocamento UTC: +01:00 GMT
    */

    echo date("D M d Y"). ', horário do pôr do sol : ' .date_sunset(time(), SUNFUNCS_RET_STRING, 38.4, -9, 90, 1);

O exemplo acima produzirá algo semelhante a:

    Deprecated: Constant SUNFUNCS_RET_STRING is deprecated in script on line 10
    Deprecated: Function date_sunset() is deprecated since 8.1, use date_sun_info() instead in script on line 10
    Mon Dec 20 2004, horário do pôr do sol : 18:13

Exemplo #2 Sem pôr do sol

    <?php
    $solstice = strtotime('2017-12-21');
    var_dump(date_sunset($solstice, SUNFUNCS_RET_STRING, 69.245833, -53.537222));

O exemplo acima produzirá:

    Deprecated: Constant SUNFUNCS_RET_STRING is deprecated in script on line 3
    Deprecated: Function date_sunset() is deprecated since 8.1, use date_sun_info() instead in script on line 3
    bool(false)

### Veja Também

- date_sun_info() - Retorna um array com informações sobre pôr/nascer do sol e o início/fim do dia

# date_time_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_time_set — Sinônimo de DateTime::setTime()

### Descrição

Esta função é um apelido para: DateTime::setTime()

# date_timestamp_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_timestamp_get — Sinônimo de DateTime::getTimestamp()

### Descrição

Esta função é um apelido para: DateTime::getTimestamp()

# date_timestamp_set

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_timestamp_set — Sinônimo de DateTime::setTimestamp()

### Descrição

Esta função é um apelido para: DateTime::setTimestamp()

# date_timezone_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_timezone_get — Sinônimo de DateTime::getTimezone()

### Descrição

Esta função é um apelido para: DateTime::getTimezone()

# date_timezone_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_timezone_set — Sinônimo de DateTime::setTimezone()

### Descrição

Esta função é um apelido para: DateTime::setTimezone()

# getdate

(PHP 4, PHP 5, PHP 7, PHP 8)

getdate — Recupera informações de data/horário

### Descrição

function getdate(?int `$timestamp` = `null`): array

Retorna um array associativo contendo a informação da data do `timestamp`, ou o horário atual local se `timestamp` for `null` ou omitido.

### Parâmetros

`timestamp`
  O parâmetro opcional `timestamp` é um int de timestamp Unix cujo padrão é a hora local atual se `timestamp` não for informado ou for `null`. Em outras palavras, o padrão é o valor de time().

### Valor Retornado

Retorna um array associativo de informação sobre o `timestamp`. Os elementos do array associativo são os seguintes:

Elementos chave de retorno do array associativo
Chave | Descrição | Exemplo dos valores retornados
--- | --- | ---
`"seconds"` | Representação numérica dos segundos | `0` a `59`
`"minutes"` | Representação numérica dos minutos | `0` a `59`
`"hours"` | Representação numérica das horas | `0` a `23`
`"mday"` | Representação numérica do dia do mês | `1` a `31`
`"wday"` | Representação numérica do dia da semana | `0` (para Sunday) a `6` (para Saturday)
`"mon"` | Representação numérica de um mês | `1` a `12`
`"year"` | Representação numérica completa do ano, 4 dígitos | Exemplos: `1999` ou `2003`
`"yday"` | Representação numérica do dia do ano | `0` a `365`
`"weekday"` | Representação textual completa do dia da semana | `Sunday` a `Saturday`
`"month"` | Representação textual completa de um mês, tal como January ou March | `January` a `December`
`0` | Segundos desde a época UNIX, similar ao valor retornados pela função time() e utilizado pela função date(). | Dependente do sistema, tipicamente `-2147483648` à `2147483647`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `timestamp` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo da função getdate()

    <?php
    $today = getdate();
    print_r($today);

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [seconds] => 40
        [minutes] => 58
        [hours] => 21
        [mday] => 17
        [wday] => 2
        [mon] => 6
        [year] => 2003
        [yday] => 167
        [weekday] => Tuesday
        [month] => June
        [0] => 1055901520
    )

### Veja Também

- date() - Formata um timestamp Unix
- idate() - Formata uma parte de uma data/horário local como um inteiro
- localtime() - Obtém o horário local
- time() - Retorna o timestamp Unix atual
- setlocale() - Define informação de localidade

# gettimeofday

(PHP 4, PHP 5, PHP 7, PHP 8)

gettimeofday — Obtém o horário atual

### Descrição

function gettimeofday(bool `$as_float` = `false`): array|float

Esta é uma interface para gettimeofday(2). Retorna um array contendo os dados retornando a chamada ao sistema.

### Parâmetros

`as_float`

  Quando definido como `true`, um float, ao invés de array, é retornado.

### Valor Retornado

Por padrão, um array é retornado. Se o parâmetro `as_float` é definido, então um float é retornado.

Chaves do array:

- "sec" - segundos desde a época Unix
- "usec" - microssegundos
- "minuteswest" - minutos a oeste de Greenwich
- "dsttime" - tipo de correção dst

### Exemplos

Exemplo #1 Exemplo da função gettimeofday()

    <?php
    print_r(gettimeofday());

    echo gettimeofday(true);

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [sec] => 1073504408
        [usec] => 238215
        [minuteswest] => 0
        [dsttime] => 1
    )
    1073504408.23910

# gmdate

(PHP 4, PHP 5, PHP 7, PHP 8)

gmdate — Formata uma data/horário GMT/CUT

### Descrição

function gmdate(string `$format`, ?int `$timestamp` = `null`): string

Idêntica à função date(), exceto que o horário retornado será baseado no Horário de Greenwich (GMT).

### Parâmetros

`format`

  O formato da saída da string da data. Veja as opções de formatação para a função date().

`timestamp`
  O parâmetro opcional `timestamp` é um int de timestamp Unix cujo padrão é a hora local atual se `timestamp` não for informado ou for `null`. Em outras palavras, o padrão é o valor de time().

### Valor Retornado

Retorna uma string da data formatada.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `timestamp` agora é anulável.

### Exemplos

Exemplo #1 Exemplo da gmdate()

    <?php
    date_default_timezone_set("Europe/Helsinki");

    echo date("M d Y H:i:s e", mktime(0, 0, 0, 1, 1, 1998)) . "\n";
    echo gmdate("M d Y H:i:s e", mktime(0, 0, 0, 1, 1, 1998));

O exemplo acima produzirá:

    Jan 01 1998 00:00:00 Europe/Helsinki
    Dec 31 1997 22:00:00 UTC

### Veja Também

- DateTimeImmutable::__construct() - Retorna um novo objeto DateTimeImmutable
- DateTimeInterface::format() - Retorna a data formatada de acordo com um formato informado
- date() - Formata um timestamp Unix
- mktime() - Obtém um timestamp Unix de uma data
- gmmktime() - Obtém um timestamp Unix para uma data GMT
- IntlDateFormatter::format() - Formata data/horário como uma string

# gmmktime

(PHP 4, PHP 5, PHP 7, PHP 8)

gmmktime — Obtém um timestamp Unix para uma data GMT

### Descrição

function gmmktime(
int `$hour`,
?int `$minute` = `null`,
?int `$second` = `null`,
?int `$month` = `null`,
?int `$day` = `null`,
?int `$year` = `null`
): int|false

Idêntico ao mktime() exceto que os parâmetros representam uma data GMT. A função gmmktime() usa internamente a função mktime(), significando que somente horários válidos derivados de horários locais podem ser utilizados.

Como em mktime(), argumentos opcionais podem ser omitidos da direita para esquerda, com todos os argumentos omitidos sendo definidos para o valor GMT correspondente.

Chamar gmmktime() sem nenhum argumento não é suportado, e vai resultar em um ArgumentCountError. time() pode ser usado para obter o horário atual.

### Parâmetros

`hour`

  O número de horas relativas ao início do dia determinadas pelos parâmetros `month`, `day` e `year`. Valores negativos são referenciados à horas antes da meia noite do dia em questão. Valores maiores que 23 referenciam horas correspondentes ao(s) próximo(s) dia(s).

`minute`

  O número de minutos relativos ao início da `hour`. Valores negativos referenciam minutos da hora anterior. Valores maiores que 23 referenciam os minutos correspondentes a(s) próxima(s) horas(s).

`second`

  O número de segundos relativos ao início do `minute`. Valores negativos referenciam segundos do minuto anterior. Valores maiores que 23 referenciam os segundos correspondentes ao(s) próximo(s) minuto(s).

`month`

  O número do mês relativo ao fim do anterior. Valores de 1 a 12 referenciam o calendário normal de meses do ano em questão. Valores menores que 1 (valores negativos, incluso) referenciam meses do ano anterior em ordem reversa, então 0 é Dezembro, -1 Novembro, e etc. Valores maiores que 12 referenciam meses correspondentes ao(s) próximo(s) ano(s).

`day`

  O número do dia relativo ao final do mês anterior. Valores de 1 a 28, 29, 30 e 31 (dependendo do mês) corresponde a dias normais no mês. Valores menores que 1 (valores negativos, incluso) corresponde a dias no mês anterior, então 0 é o último dia do mês anterior, -1 é o dia anterior a este, e etc. Valores maiores que o número de dias do mês, referenciam dias correspondentes ao(s) próximo(s) mês(es).

`year`

  O ano

### Valor Retornado

Retorna um int timestamp Unix em caso de sucesso, ou `false` se o timestamp não couber em um número inteiro do PHP.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `hour` não é mais opcional. Se for necessário um timestamp Unix, use time().
8.0.0 | `minute`, `second`, `month`, `day` e `year` agora podem ser nulos.

### Exemplos

Exemplo #1 A função gmmktime() no Windows

    <?php
    date_default_timezone_set("Indian/Maldives");

    echo "July 1, 2000 is on a " . date("l", gmmktime(0, 0, 0, 7, 1, 2000));

O exemplo acima produzirá:

    July 1, 2000 is on a Saturday

### Veja Também

- A classe DateTimeImmutable
- mktime() - Obtém um timestamp Unix de uma data
- date() - Formata um timestamp Unix
- time() - Retorna o timestamp Unix atual

# gmstrftime

(PHP 4, PHP 5, PHP 7, PHP 8)

gmstrftime — Formata uma data/horário GMT/UTC de acordo com as configurações de localidade

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.1.0. O uso desta função é fortemente desencorajado.

Alternativas a esta função incluem:

- gmdate()
- IntlDateFormatter::format()

### Descrição

#[\Deprecated]
function gmstrftime(string `$format`, ?int `$timestamp` = null): string|false

Possui o mesmo comportamento que a função strftime() exceto que o tempo retornado será no Horário de Greenwich (GMT). Por exemplo, quando executada no fuso horário EST (GMT -0500), a primeira linha abaixo imprime "Dec 31 1998 20:00:00", enquanto a segunda linha imprime "Jan 01 1999 01:00:00".

Aviso

Esta função depende das informações de localidade do sistema operacional, que podem ser inconsistentes ou não disponíveis. Ao invés disso, use o método IntlDateFormatter::format().

### Parâmetros

`format`

  Veja a descrição em strftime().

`timestamp`
  O parâmetro opcional `timestamp` é um int de timestamp Unix cujo padrão é a hora local atual se `timestamp` não for informado ou for `null`. Em outras palavras, o padrão é o valor de time().

### Valor Retornado

Retorna uma string formatada de acordo com a string de formatação, usando o `timestamp` informado, ou o horário local se nenhum timestamp é informado. Nomes de meses, dias da semana e outras strings que dependem do idioma respeitam a configuração de localidade atual definido com a função setlocale(). Em caso de falha, é retornado `false`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `timestamp` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo da função gmstrftime()

    <?php

    setlocale(LC_TIME, 'es_ES.UTF-8');
    date_default_timezone_set('EST');

    echo strftime("%B %d %Y %H:%M:%S",   mktime(20, 0, 0, 12, 31, 98)) . "\n";
    echo gmstrftime("%B %d %Y %H:%M:%S", mktime(20, 0, 0, 12, 31, 98));

O exemplo acima produzirá:

    Deprecated: Function strftime() is deprecated since 8.1, use IntlDateFormatter::format() instead in script on line 6
    diciembre 31 1998 20:00:00

    Deprecated: Function gmstrftime() is deprecated since 8.1, use IntlDateFormatter::format() instead in script on line 7
    enero 01 1999 01:00:00

### Veja Também

- IntlDateFormatter::format() - Formata data/horário como uma string
- DateTimeInterface::format() - Retorna a data formatada de acordo com um formato informado
- strftime() - Formata uma data/horário de acordo com as configurações locais

# idate

(PHP 5, PHP 7, PHP 8)

idate — Formata uma parte de uma data/horário local como um inteiro

### Descrição

function idate(string `$format`, ?int `$timestamp` = `null`): int|false

Retorna um número formatado de acordo com um formato informado utilizando o inteiro `timestamp`, ou o horário local atual se nenhum timestamp foi informado. Em outras palavras, `timestamp` é opcional e tem como padrão o valor da função time().

Ao contrário da função date(), a idate(), aceita apenas um caractere no parâmetro `format`.

### Parâmetros

`format`

  Os caracteres a seguir são reconhecidos como válidos no parâmetro `format`
  Caractere `format` | Descrição
  --- | ---
  `B` | Swatch Beat/Horário da Internet
  `d` | Dia do mês
  `h` | Hora (no formato de 12 horas)
  `H` | Hora (no formato de 24 horas)
  `i` | Minutos
  `I` (i maiúsculo) | retorna `1` se o horário de verão está ativo, `0`, caso contrário
  `L` (l maiúsculo) | retorna `1` para anos bissextos, `0`, caso contrário
  `m` | Número do mês
  `N` | Dia da semana, baseado na ISO-8601 (`1` para segunda-feira até`7` para domingo)
  `o` | ISO-8601 year (4 digits)
  `s` | Segundos
  `t` | Dias do mês atual
  `U` | Segundos desde a época Unix - January 1 1970 00:00:00 UTC - isso é o mesmo que a função time()
  `w` | Dia da semana (`0` para domingo)
  `W` | Semana do ano, baseado na ISO-8601, com a semana começando na segunda-feira
  `y` | Ano (1 ou 2 dígitos - veja a nota abaixo)
  `Y` | Ano (4 dígitos)
  `z` | Dia do ano
  `Z` | Deslocamento do fuso horário em segundos

`timestamp`
  O parâmetro opcional `timestamp` é um int de timestamp Unix cujo padrão é a hora local atual se `timestamp` não for informado ou for `null`. Em outras palavras, o padrão é o valor de time().

### Valor Retornado

Retorna um int em caso de sucesso, ou `false` em caso de falha.

Como a função idate() sempre retorna um int e como ela não começa com um "0", idate() pode retornar menos dígitos do que se espera. Veja o exemplo abaixo.

### Erros/Exceções

Toda chamada a uma função de data/hora gerará um `E_WARNING` se o fuso horário não for válido. Veja também date_default_timezone_set()

### Registro de Alterações

Versão | Descrição
--- | ---
8.2.0 | Inclui os caracteres de formato `N` (dia da semana ISO-8601) e `o` (ano ISO-8601).
8.0.0 | `timestamp` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo da função idate()

    <?php
    $timestamp = strtotime('1st January 2004'); // 1072915200

    // este código imprime o ano em um formato de dois dígitos
    // entretanto, como começaria com um "0", ele
    // só imprime "4"
    echo idate('y', $timestamp) . "\n";

    $timestamp = strtotime('1st January 2024'); // 1704067200
    echo idate('y', $timestamp);

O exemplo acima produzirá:

    4
    24

### Veja Também

- DateTimeInterface::format() - Retorna a data formatada de acordo com um formato informado
- date() - Formata um timestamp Unix
- getdate() - Recupera informações de data/horário
- time() - Retorna o timestamp Unix atual

# localtime

(PHP 4, PHP 5, PHP 7, PHP 8)

localtime — Obtém o horário local

### Descrição

function localtime(?int `$timestamp` = `null`, bool `$associative` = `false`): array

A função localtime() retorna um array idêntico à estrutura retornada pela chamada da função em C.

### Parâmetros

`timestamp`
  O parâmetro opcional `timestamp` é um int de timestamp Unix cujo padrão é a hora local atual se `timestamp` não for informado ou for `null`. Em outras palavras, o padrão é o valor de time().
`associative`

### Valor Retornado

Se `associative` for definido para `false` ou não fornecido, o retorno é um array normal, indexado numericamente. Se `associative` for definido para `true`, então localtime() retorna um array associativo contendo os elementos da estrutura retornados pela chamada da função C para o horário local. Os nomes das chaves do array associativo são as seguintes:

- "tm_sec" - segundos, `0` a `59`
- "tm_min" - minutos, `0` a `59`
- "tm_hour" - horas, `0` a `23`
- "tm_mday" - dia do mês, `1` a `31`
- "tm_mon" - mês do ano, `0` (Jan) a `11` (Dez)
- "tm_year" - anos desde 1900
- "tm_wday" - dia da semana, `0` (Dom) a `6` (Sáb)
- "tm_yday" - dia do ano, `0` a `365`
- "tm_isdst" - Se está em horário de verão Positivo se sim, `0` se não, negativo se é desconhecido.

### Erros/Exceções

Toda chamada a uma função de data/hora gerará um `E_WARNING` se o fuso horário não for válido. Veja também date_default_timezone_set()

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `timestamp` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo da função localtime()

    <?php
    $localtime = localtime();
    $localtime_assoc = localtime(time(), true);
    print_r($localtime);
    print_r($localtime_assoc);

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => 24
        [1] => 3
        [2] => 19
        [3] => 3
        [4] => 3
        [5] => 105
        [6] => 0
        [7] => 92
        [8] => 1
    )

    Array
    (
        [tm_sec] => 24
        [tm_min] => 3
        [tm_hour] => 19
        [tm_mday] => 3
        [tm_mon] => 3
        [tm_year] => 105
        [tm_wday] => 0
        [tm_yday] => 92
        [tm_isdst] => 1
    )

### Veja Também

- getdate() - Recupera informações de data/horário

# microtime

(PHP 4, PHP 5, PHP 7, PHP 8)

microtime — Retorna o timestamp Unix atual com microssegundos

### Descrição

function microtime(bool `$as_float` = `false`): string|float

A função microtime() retorna o timestamp atual com microssegundos. Esta função está disponível apenas em sistemas operacionais que suportam a chamada de sistema gettimeofday().

Para medições de desempenho, é recomendado utilizar hrtime().

### Parâmetros

`as_float`

  Se utilizada e definida como `true`, a função microtime() retornará um float em vez de uma string, como descrito na seção de valores de retorno a seguir.

### Valor Retornado

Por padrão, a função microtime() retorna uma string no formato "msec sec", onde `sec` é o número de segundos desde a época Unix (1 de Janeiro de 1970, 00:00:00 GMT), e `msec` mensura os microssegundos que se passaram desde `sec` e também é expressa em segundos, na forma de fração decimal.

Se o parâmetro opcional `as_float` for definido para `true`, a função microtime() retorna um float que representa a hora atual em segundos desde a época Unix com precisão de microssegundos.

### Exemplos

Exemplo #1 Cronometrando a execução do script

    <?php
    $time_start = microtime(true);

    // Espera um momento
    usleep(10_000);

    $time_end = microtime(true);
    $time = $time_end - $time_start;

    print "Nada foi feito em $time segundo(s).\n";

Exemplo #2 microtime() e `REQUEST_TIME_FLOAT`

    <?php
    // Tempo de espera aleatório
    usleep(random_int(10_000, 1_000_000));

    // REQUEST_TIME_FLOAT está disponível no array superglobal $_SERVER.
    // Ele contém o timestamp do início da requisição com precisão de microssegundos.
    $time = microtime(true) - $_SERVER["REQUEST_TIME_FLOAT"];

    echo "Nada foi feito em $time segundo(s).\n";

### Veja Também

- time() - Retorna o timestamp Unix atual
- hrtime() - Obtém o tempo de alta resolução do sistema

# mktime

(PHP 4, PHP 5, PHP 7, PHP 8)

mktime — Obtém um timestamp Unix de uma data

### Descrição

function mktime(
int `$hour`,
?int `$minute` = `null`,
?int `$second` = `null`,
?int `$month` = `null`,
?int `$day` = `null`,
?int `$year` = `null`
): int|false

Retorna o timestamp Unix correspondente aos argumentos informados. Este timestamp é um inteiro longo contendo o número de segundos entre a Época Unix (January 1 1970 00:00:00 GMT), e o horário especificado.

Quaisquer argumentos opcionais omitidos ou `null` serão definidos para os valores correntes de acordo com a data e horário locais.

Aviso

Favor notar que os argumentos estão em uma ordem não usual: `month`, `day`, `year`, e não na ordem mais razoável `year`, `month`, `day`.

Chamar mktime() sem argumentos não é suportado, e irá resultar em um ArgumentCountError. time() pode ser usada para obter o timestamp atual.

### Parâmetros

`hour`

  O número da hora relativa ao início de determinado dia do `month`, `day` e `year`. Valores negativos referenciam a hora anterior a meia noite do dia em questão. Valores maiores que 23 referenciam a hora correspondente no(s) próximo(s) dia(s).

`minute`

  O número de minutos relativos ao início da `hour`. Valores negativos referenciam minutos da hora anterior. Valores maiores que 23 referenciam os minutos correspondentes a(s) próxima(s) horas(s).

`second`

  O número de segundos relativos ao início do `minute`. Valores negativos referenciam segundos do minuto anterior. Valores maiores que 23 referenciam os segundos correspondentes ao(s) próximo(s) minuto(s).

`month`

  O número do mês relativo ao fim do anterior. Valores de 1 a 12 referenciam o calendário normal de meses do ano em questão. Valores menores que 1 (valores negativos, inclusos) referenciam meses do ano anterior em ordem reversa, então 0 é Dezembro, -1 Novembro, e etc. Valores maiores que 12 referenciam meses correspondentes ao(s) próximo(s) ano(s).

`day`

  O número do dia relativo ao final do mês anterior. Valores de 1 a 28, 29, 30 e 31 (dependendo do mês) corresponde a dias normais no mês. Valores menores que 1 (valores negativos, inclusos) corresponde a dias no mês anterior, então 0 é o último dia do mês anterior, -1 é o dia anterior a este, e etc. Valores maiores que o número de dias do mês, referenciam dias correspondentes ao(s) próximo(s) mês(es).

`year`

  O número do ano. Pode conter dois ou quatro dígitos, com os valores entre 0-69 significando 2000-2069 e 70-100 para 1970-2000. Em sistemas aonde o time_t é um inteiro assinado de 32 bit, como é mais comum, o faixa de valores para `year` é algo entre 1901 e 2038.

### Valor Retornado

A função mktime() retorna o timestamp Unix dos argumentos informados ou `false` se o timestamp não couber em um inteiro do PHP.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `hour` não é mais opcional. Se for necessário um timestamp Unix, use a função time().
8.0.0 | `minute`, `second`, `month`, `day` e `year` agora podem ser nulos.

### Exemplos

Exemplo #1 Exemplo básico da função mktime()

    <?php
    // Configura o fuso horário padrão a ser utilizado.
    date_default_timezone_set('UTC');

    // Imprime: July 1, 2000 is on a Saturday
    echo "July 1, 2000 is on a " . date("l", mktime(0, 0, 0, 7, 1, 2000)) . "\n";

    // Imprime algo como: 2006-04-05T01:02:03+00:00
    echo date('c', mktime(1, 2, 3, 4, 5, 2006)) . "\n";

O exemplo acima produzirá algo semelhante a:

    July 1, 2000 is on a Saturday
    2006-04-05T01:02:03+00:00

Exemplo #2 Exemplo da mktime()

mktime() é útil para a aritmética e validação de data, já que calculará automaticamente o valor correto para a entrada fora do intervalo. Por exemplo, cada uma das seguintes linhas produzirá a string "Jan-01-1998".

    <?php
    date_default_timezone_set('America/New_York');

    echo date("c", mktime(0, 0, 0, 12, 32, 1997)) . "\n";
    echo date("c", mktime(0, 0, 0, 13, 1, 1997)) . "\n";
    echo date("c", mktime(0, 0, 0, 1, 1, 1998)) . "\n";
    echo date("c", mktime(0, 0, 0, 1, 1, 98)) . "\n";

O exemplo acima produzirá algo semelhante a:

    1998-01-01T00:00:00-05:00
    1998-01-01T00:00:00-05:00
    1998-01-01T00:00:00-05:00
    1998-01-01T00:00:00-05:00

Exemplo #3 Usando mktime para encontrar datas relativas

    <?php
    date_default_timezone_set('Asia/Tokyo');

    $tomorrow  = mktime(0, 0, 0, date("m")  , date("d")+1, date("Y"));
    print date('c', $tomorrow) . "\n";

    $lastmonth = mktime(0, 0, 0, date("m")-1, date("d"),   date("Y"));
    print date('c', $lastmonth) . "\n";

    $nextyear  = mktime(0, 0, 0, date("m"),   date("d"),   date("Y")+1) . "\n";
    print date('c', $nextyear) . "\n";

O exemplo acima produzirá algo semelhante a:

    2025-09-30T00:00:00+09:00
    2025-08-29T00:00:00+09:00
    2026-09-29T00:00:00+09:00

> Nota:

> Isto pode ser mais confiável que simplesmente adicionar ou substrair o número de segundos em um dia ou mês de um timestamp por causa do fuso horário.

Exemplo #4 Último dia do próximo mês

O último dia de um mês informado pode ser expressado como o dia "0" do mês seguinte, não o dia -1. Os dois exemplos a seguir produzirão a string "Last day in Feb 2000 is: 29".

    <?php

    $lastday = mktime(0, 0, 0, 3, 0, 2000);
    echo 'Last day in Feb 2000 is: ', date('d', $lastday) . "\n";

    $lastday = mktime(0, 0, 0, 4, -31, 2000);
    echo 'Last day in Feb 2000 is: ', date('d', $lastday) . "\n";

O exemplo acima produzirá:

    Last day in Feb 2000 is: 29
    Last day in Feb 2000 is: 29

### Veja Também

- A classe DateTimeImmutable
- checkdate() - Valida uma data gregoriana
- gmmktime() - Obtém um timestamp Unix para uma data GMT
- date() - Formata um timestamp Unix
- time() - Retorna o timestamp Unix atual

# strftime

(PHP 4, PHP 5, PHP 7, PHP 8)

strftime — Formata uma data/horário de acordo com as configurações locais

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.1.0. O uso desta função é fortemente desencorajado.

Alternativas a esta função incluem:

- date()
- IntlDateFormatter::format()

### Descrição

#[\Deprecated]
function strftime(string `$format`, ?int `$timestamp` = null): string|false

Formata uma data/horário local de acordo com a configuração do idioma. Nome do mês e dia da semana e outras strings respeitam o idioma corrente definido com a função setlocale().

Aviso

Nem todos os especificadores de conversão podem ser suportados por suas bibliotecas C, e nestes casos eles não serão suportados pela função do PHP strftime(). Além disso, nem todas as plataformas suportam timestamps negativos, então sua faixa de datas pode ficar limitada a um valor não anterior à época Unix. Isto significa que %e, %T, %R e %D (e possivelmente outras) - assim como datas anteriores a `1 de janeiro de 1970` - não funcionarão no Windows, algumas distribuições Linux, e alguns outros sistemas operacionais. Para sistemas Windows, uma visão completa dos especificadores de conversão suportados podem ser encontrados em » MSDN. No lugar desta função, use o método IntlDateFormatter::format().

### Parâmetros

`format`

  Os seguintes caracteres são reconhecidos na string do parâmetro `format`
  `format` | Descrição | Exemplo de valores retornados
  --- | --- | ---
  Dia | --- | ---
  `%a` | Representação textual abreviada do dia | `Sun` até `Sat`
  `%A` | Representação textual completa do dia | `Sunday` até `Saturday`
  `%d` | Dia do mês, com dois dígitos (com zeros à esquerda) | `01` a `31`
  `%e` | Dia do mês com um dígito, precedido com um espaço. Não implementado como descrito no Windows. Veja abaixo para mais informações. | `1` a `31`
  `%j` | Dia do ano, com 3 dígitos e zeros à esquerda | `001` a `366`
  `%u` | Representação numérica, do dia da semana, compatível com a ISO-8601 | `1` (para segunda-feira) até `7` (para domingo)
  `%w` | Representação numérica do dia da semana | `0` (para domingo) até `6` (para sábado)
  Semana | --- | ---
  `%U` | Número da semana de um dado ano, iniciado com o primeiro domingo sendo a primeira semana | `13` (como a 13ª semana completa do ano)
  `%V` | Número da semana, compatível com a ISO-8601:1988 de um dado ano, iniciada com a primeira semana do ano com pelo menos 4 finais de semana, sendo a segunda-feira como o início da semana. | `01` até `53` (onde 53 é responsável por uma sobreposição)
  `%W` | Representação numérica da semana do ano, começando pela primeira segunda-feira como primeira semana | `46` (como a 46ª semana do do ano iniciando na segunda-feira)
  Mês | --- | ---
  `%b` | Nome do mês abreviado, baseado no idioma | `jan` até `dez`
  `%B` | Nome completo do mês, baseado no idioma | `janeiro` até `dezembro`
  `%h` | Nome do mês abreviado, baseado no idioma (sinônimo de %b) | `jan` até `dez`
  `%m` | Representação com dois dígitos do mês | `01` (para janeiro) até `12` (para dezembro)
  Ano | --- | ---
  `%C` | Representação, com dois dígitos, do século (ano dividido por 100, truncado como inteiro) | `19` para o século 20
  `%g` | Representação do ano, com dois dígitos, seguindo o padrão ISO-8601:1988 (veja %V) | Exemplo: `09` de 6 de janeiro de 2009
  `%G` | Versão de 4 dígitos de %g | Exemplo: `2008` de 3 de janeiro de 2009
  `%y` | Representação, com dois dígitos, do ano | Exemplo: `09` de 2009, `79` de 1979
  `%Y` | Representação, com quatro dígitos, do ano | Exemplo: `2038`
  Hora | --- | ---
  `%H` | Representação, com dois dígitos, da hora no formato 24 horas | `00` até `23`
  `%k` | Representação da hora no formato 24 horas, com um espaço precedendo dígito único | `0` até `23`
  `%I` | Representação, com dois dígitos, da hora no formato 12 horas | `01` até `12`
  `%l ('L' minúsculo)` | Representação da hora no formato 12 horas, com um espaço precedendo dígito único | `1` até `12`
  `%M` | Representação, com dois dígitos, do minuto | `00` até `59`
  `%p` | 'AM' ou 'PM' maiúsculo baseado na hora informada | Exemplo: `AM` para 00:31, `PM` para 22:23. O resultado exato depende do sistema operacional, e pode retornar variantes em minúsculoas, ou variantes com pontos (como `a.m.`).
  `%P` | 'am' ou 'pm' maiúsculo baseado na hora informada | Exemplo: `am` para 00:31, `pm` para 22:23. Não suportado por todos os sistemas operacionais.
  `%r` | O mesmo que "%I:%M:%S %p" | Exemplo: `09:34:17 PM` de 21:34:17
  `%R` | O mesmo que "%H:%M" | Exemplo: `00:35` de 12:35 AM, `16:44` de 4:44 PM
  `%S` | Representação, com dois dígitos, do segundo | `00` até `59`
  `%T` | O mesmo que "%H:%M:%S" | Exemplo: `21:34:17` para 09:34:17 PM
  `%X` | Representação escolhida baseada no idioma, sem a data | Exemplo: `03:59:16` ou `15:59:16`
  `%z` | O deslocamento do fuso horário. Não implementado como descrito no Windows. Veja mais informações a seguir. | Exemplo: `-0500` para hora à leste dos EUA
  `%Z` | A abreviação do fuso horário. Não implementado como descrito no Windows. Veja mais informações a seguir. | Exemplo: `EST` para Eastern Time
  Carimbos de Data e Hora | --- | ---
  `%c` | Carimbo escolhido de data e hora baseado no idioma | Exemplo: `Ter Fev 5 00:45:10 2009` de February 5, 2009 at 12:45:10 AM
  `%D` | O mesmo que "%m/%d/%y" | Exemplo: `02/05/09` de February 5, 2009
  `%F` | O mesmo que "%Y-%m-%d" (geralmente utilizado em carimbos de data em bancos de dados) | Exemplo: `2009-02-05` de February 5, 2009
  `%s` | Timestamp Unix(o mesmo que a função time() function) | Exemplo: `305815200` de September 10, 1979 08:40:00 AM
  `%x` | Representação da data baseada na preferência da localidade, sem a hora | Exemplo: `02/05/09` de February 5, 2009
  Miscelânea | --- | ---
  `%n` | Uma nova linha ("\n") | ---
  `%t` | Um caractere TAB ("\t") | ---
  `%%` | Um caractere literal de porcento ("%") | ---

  Aviso

  Contrário a ISO-9899:1999, o sistema Sun Solaris começa a semana no Domingo, como 1. Resultando em `%u` não funcionando como descrito neste manual.

  Aviso

  Somente no Windows:

  O modificador `%e` não possui suporte a implementação desta função no Windows. Para conseguir este valor, o modificador `%#d` pode ser utilizado em substituição. O exemplo a seguir ilustra como escrever uma função com compatibilidade multiplataforma.

  Os modificadores `%z` e `%Z` retornam o nome do fuso horário em vez do deslocamento ou abreviação do mesmo.

  Aviso

  macOS e musl somente: O modificador `%P` não é suportado na implementação macOS desta função.

`timestamp`
  O parâmetro opcional `timestamp` é um int de timestamp Unix cujo padrão é a hora local atual se `timestamp` não for informado ou for `null`. Em outras palavras, o padrão é o valor de time().

### Valor Retornado

Retorna uma string formatada de acordo com o `format` informado em `timestamp` ou o horário local atual se nenhum timestamp foi informado. Nomes de meses e dia da semana, e outras strings dependentes de linguagens respeitam o idioma definido com a função setlocale(). A função retorna `false` se `format` for vazio, contém especificadores de conversão não suportados, ou se o comprimento da string retornada fosse maior que `4095`.

### Erros/Exceções

Toda chamada a uma função de data/hora gerará um `E_WARNING` se o fuso horário não for válido. Veja também date_default_timezone_set()

Como a saída depende da biblioteca C disponível, alguns especificadores de conversão não possuem suporte. No Windows, informar especificadores de conversão desconhecidos resultará em mensagens `E_WARNING` e retornará `false`. Em outros sistemas operacionais, pode não haver nenhuma mensagem `E_WARNING` e a saída poderá conter os especificadores de conversão não convertidos.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `timestamp` agora pode ser nulo.

### Exemplos

Este exemplo funciona se os respectivos idiomas estiverem instalados no sistema.

Exemplo #1 Exemplo da função strftime() com idiomas

    <?php
    setlocale(LC_TIME, "C");
    echo strftime("%A");
    setlocale(LC_TIME, "fi_FI");
    echo strftime(" em finlandês é %A,");
    setlocale(LC_TIME, "fr_FR");
    echo strftime(" em francês %A e");
    setlocale(LC_TIME, "de_DE");
    echo strftime(" em alemão %A.\n");

Exemplo #2 Exemplo do número de semana ISO 8601:1988

    <?php
    /*     Dezembro 2002 / Janeiro 2003
    ISOWk  M   Tu  W   Thu F   Sa  Su
    ----- ----------------------------
    51     16  17  18  19  20  21  22
    52     23  24  25  26  27  28  29
    1      30  31   1   2   3   4   5
    2       6   7   8   9  10  11  12
    3      13  14  15  16  17  18  19   */

    // Mostra: 12/28/2002 - %V,%G,%Y = 52,2002,2002
    echo "12/28/2002 - %V,%G,%Y = " . strftime("%V,%G,%Y", strtotime("12/28/2002")) . "\n";

    // Mostra: 12/30/2002 - %V,%G,%Y = 1,2003,2002
    echo "12/30/2002 - %V,%G,%Y = " . strftime("%V,%G,%Y", strtotime("12/30/2002")) . "\n";

    // Mostra: 1/3/2003 - %V,%G,%Y = 1,2003,2003
    echo "1/3/2003 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/3/2003")) . "\n";

    // Mostra: 1/10/2003 - %V,%G,%Y = 2,2003,2003
    echo "1/10/2003 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/10/2003")) . "\n";

    /*     Dezembro 2004 / Janeiro 2005
    ISOWk  M   Tu  W   Thu F   Sa  Su
    ----- ----------------------------
    51     13  14  15  16  17  18  19
    52     20  21  22  23  24  25  26
    53     27  28  29  30  31   1   2
    1       3   4   5   6   7   8   9
    2      10  11  12  13  14  15  16   */

    // Mostra: 12/23/2004 - %V,%G,%Y = 52,2004,2004
    echo "12/23/2004 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("12/23/2004")) . "\n";

    // Mostra: 12/31/2004 - %V,%G,%Y = 53,2004,2004
    echo "12/31/2004 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("12/31/2004")) . "\n";

    // Mostra: 1/2/2005 - %V,%G,%Y = 53,2004,2005
    echo "1/2/2005 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/2/2005")) . "\n";

    // Mostra: 1/3/2005 - %V,%G,%Y = 1,2005,2005
    echo "1/3/2005 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/3/2005")) . "\n";

Exemplo #3 Exemplo do uso do modificador `%e` compatível com múltiplas plataformas

    <?php

    // Jan 1: resulta em: '%e%1%' (%%, e, %%, %e, %%)
    $format = '%%e%%%e%%';

    // Verifica se está no Windows e substitui o modificador %e
    // adequadamente
    if (strtoupper(substr(PHP_OS, 0, 3)) == 'WIN') {
        $format = preg_replace('#(?<!%)((?:%%)*)%e#', '\1%#d', $format);
    }

    echo strftime($format);

Exemplo #4 Mostra os formatos conhecidos e desconhecidos

    <?php

    // Descreve os formatos
    $strftimeFormats = array(
        'A' => 'A full textual representation of the day',
        'B' => 'Full month name, based on the locale',
        'C' => 'Two digit representation of the century (year divided by 100, truncated to an integer)',
        'D' => 'Same as "%m/%d/%y"',
        'E' => '',
        'F' => 'Same as "%Y-%m-%d"',
        'G' => 'The full four-digit version of %g',
        'H' => 'Two digit representation of the hour in 24-hour format',
        'I' => 'Two digit representation of the hour in 12-hour format',
        'J' => '',
        'K' => '',
        'L' => '',
        'M' => 'Two digit representation of the minute',
        'N' => '',
        'O' => '',
        'P' => 'lower-case "am" or "pm" based on the given time',
        'Q' => '',
        'R' => 'Same as "%H:%M"',
        'S' => 'Two digit representation of the second',
        'T' => 'Same as "%H:%M:%S"',
        'U' => 'Week number of the given year, starting with the first Sunday as the first week',
        'V' => 'ISO-8601:1988 week number of the given year, starting with the first week of the year with at least 4 weekdays, with Monday being the start of the week',
        'W' => 'A numeric representation of the week of the year, starting with the first Monday as the first week',
        'X' => 'Preferred time representation based on locale, without the date',
        'Y' => 'Four digit representation for the year',
        'Z' => 'The time zone offset/abbreviation option NOT given by %z (depends on operating system)',
        'a' => 'An abbreviated textual representation of the day',
        'b' => 'Abbreviated month name, based on the locale',
        'c' => 'Preferred date and time stamp based on local',
        'd' => 'Two-digit day of the month (with leading zeros)',
        'e' => 'Day of the month, with a space preceding single digits',
        'f' => '',
        'g' => 'Two digit representation of the year going by ISO-8601:1988 standards (see %V)',
        'h' => 'Abbreviated month name, based on the locale (an alias of %b)',
        'i' => '',
        'j' => 'Day of the year, 3 digits with leading zeros',
        'k' => 'Hour in 24-hour format, with a space preceding single digits',
        'l' => 'Hour in 12-hour format, with a space preceding single digits',
        'm' => 'Two digit representation of the month',
        'n' => 'A newline character ("\n")',
        'o' => '',
        'p' => 'UPPER-CASE "AM" or "PM" based on the given time',
        'q' => '',
        'r' => 'Same as "%I:%M:%S %p"',
        's' => 'Unix Epoch Time timestamp',
        't' => 'A Tab character ("\t")',
        'u' => 'ISO-8601 numeric representation of the day of the week',
        'v' => '',
        'w' => 'Numeric representation of the day of the week',
        'x' => 'Preferred date representation based on locale, without the time',
        'y' => 'Two digit representation of the year',
        'z' => 'Either the time zone offset from UTC or the abbreviation (depends on operating system)',
        '%' => 'A literal percentage character ("%")',
    );

    // Resultados
    $strftimeValues = array();

    // Avalia os formatos enqunto suprime os erros.
    foreach ($strftimeFormats as $format => $description) {
        if (false !== ($value = @strftime("%{$format}"))) {
            $strftimeValues[$format] = $value;
        }
    }

    // Encontra o valor mais longo
    $maxValueLength = 2 + max(array_map('strlen', $strftimeValues));

    // Reporta formatos conhecidos
    foreach ($strftimeValues as $format => $value) {
        echo "Formato conhecido    : '{$format}' = ", str_pad("'{$value}'", $maxValueLength), " ( {$strftimeFormats[$format]} )\n";
    }

    // Reporta formatos desconhecidos
    foreach (array_diff_key($strftimeFormats, $strftimeValues) as $format => $description) {
        echo "Formato desconhecido : '{$format}'   ", str_pad(' ', $maxValueLength), ($description ? " ( {$description} )" : ''), "\n";
    }

O exemplo acima produzirá algo semelhante a:

    Formato conhecido    : 'A' = 'Friday'            ( A full textual representation of the day )
    Formato conhecido    : 'B' = 'December'          ( Full month name, based on the locale )
    Formato conhecido    : 'H' = '11'                ( Two digit representation of the hour in 24-hour format )
    Formato conhecido    : 'I' = '11'                ( Two digit representation of the hour in 12-hour format )
    Formato conhecido    : 'M' = '24'                ( Two digit representation of the minute )
    Formato conhecido    : 'S' = '44'                ( Two digit representation of the second )
    Formato conhecido    : 'U' = '48'                ( Week number of the given year, starting with the first Sunday as the first week )
    Formato conhecido    : 'W' = '48'                ( A numeric representation of the week of the year, starting with the first Monday as the first week )
    Formato conhecido    : 'X' = '11:24:44'          ( Preferred time representation based on locale, without the date )
    Formato conhecido    : 'Y' = '2010'              ( Four digit representation for the year )
    Formato conhecido    : 'Z' = 'GMT Standard Time' ( The time zone offset/abbreviation option NOT given by %z (depends on operating system) )
    Formato conhecido    : 'a' = 'Fri'               ( An abbreviated textual representation of the day )
    Formato conhecido    : 'b' = 'Dec'               ( Abbreviated month name, based on the locale )
    Formato conhecido    : 'c' = '12/03/10 11:24:44' ( Preferred date and time stamp based on local )
    Formato conhecido    : 'd' = '03'                ( Two-digit day of the month (with leading zeros) )
    Formato conhecido    : 'j' = '337'               ( Day of the year, 3 digits with leading zeros )
    Formato conhecido    : 'm' = '12'                ( Two digit representation of the month )
    Formato conhecido    : 'p' = 'AM'                ( UPPER-CASE "AM" or "PM" based on the given time )
    Formato conhecido    : 'w' = '5'                 ( Numeric representation of the day of the week )
    Formato conhecido    : 'x' = '12/03/10'          ( Preferred date representation based on locale, without the time )
    Formato conhecido    : 'y' = '10'                ( Two digit representation of the year )
    Formato conhecido    : 'z' = 'GMT Standard Time' ( Either the time zone offset from UTC or the abbreviation (depends on operating system) )
    Formato conhecido    : '%' = '%'                 ( A literal percentage character ("%") )
    Formato desconhecido : 'C'                       ( Two digit representation of the century (year divided by 100, truncated to an integer) )
    Formato desconhecido : 'D'                       ( Same as "%m/%d/%y" )
    Formato desconhecido : 'E'
    Formato desconhecido : 'F'                       ( Same as "%Y-%m-%d" )
    Formato desconhecido : 'G'                       ( The full four-digit version of %g )
    Formato desconhecido : 'J'
    Formato desconhecido : 'K'
    Formato desconhecido : 'L'
    Formato desconhecido : 'N'
    Formato desconhecido : 'O'
    Formato desconhecido : 'P'                       ( lower-case "am" or "pm" based on the given time )
    Formato desconhecido : 'Q'
    Formato desconhecido : 'R'                       ( Same as "%H:%M" )
    Formato desconhecido : 'T'                       ( Same as "%H:%M:%S" )
    Formato desconhecido : 'V'                       ( ISO-8601:1988 week number of the given year, starting with the first week of the year with at least 4 weekdays, with Monday being the start of the week )
    Formato desconhecido : 'e'                       ( Day of the month, with a space preceding single digits )
    Formato desconhecido : 'f'
    Formato desconhecido : 'g'                       ( Two digit representation of the year going by ISO-8601:1988 standards (see %V) )
    Formato desconhecido : 'h'                       ( Abbreviated month name, based on the locale (an alias of %b) )
    Formato desconhecido : 'i'
    Formato desconhecido : 'k'                       ( Hour in 24-hour format, with a space preceding single digits )
    Formato desconhecido : 'l'                       ( Hour in 12-hour format, with a space preceding single digits )
    Formato desconhecido : 'n'                       ( A newline character ("\n") )
    Formato desconhecido : 'o'
    Formato desconhecido : 'q'
    Formato desconhecido : 'r'                       ( Same as "%I:%M:%S %p" )
    Formato desconhecido : 's'                       ( Unix Epoch Time timestamp )
    Formato desconhecido : 't'                       ( A Tab character ("\t") )
    Formato desconhecido : 'u'                       ( ISO-8601 numeric representation of the day of the week )
    Formato desconhecido : 'v'

### Notas

> Nota: %G e %V, que são baseadas nos números de semana da ISO 8601:1988, podem dar resultados inesperados (embora corretos), se o sistema numérico não for reconhecido perfeitamente. Veja exemplos da %V nesta página do manual.

### Veja Também

- IntlDateFormatter::format() - Formata data/horário como uma string
- DateTimeInterface::format() - Retorna a data formatada de acordo com um formato informado
- » Ferramenta online para criação de formatos compatíveis com o strftime()
- setlocale() - Define informação de localidade
- mktime() - Obtém um timestamp Unix de uma data
- strptime() - Interpreta uma data/horário gerada pela função strftime
- gmstrftime() - Formata uma data/horário GMT/UTC de acordo com as configurações de localidade
- » Especificação Open Group da strftime()

# strptime

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

strptime — Interpreta uma data/horário gerada pela função strftime()

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.1.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
function strptime(string `$timestamp`, string `$format`): array|false

strptime() retorna um array com a `timestamp` analisada, ou false em caso de erro.

Nomes de meses e semanas, e outras strings que dependem do idioma, respeitam o idioma corrente definido com a função setlocale() (LC_TIME).

### Parâmetros

`timestamp` (string)

  A string a ser interpretada (retornada da função strftime()).

`format` (string)

  O formato utilizado em `timestamp` (o mesmo utilizado na função strftime()). Note que algumas opções de formato disponíveis na função strftime() podem não ter nenhum efeito com strptime(); o subconjunto exato que é suportado vai variar por ser baseado no sistema operacional e biblioteca C em uso.

  Para mais informações sobre as opções de formato, veja a página da função strftime().

### Valor Retornado

Retorna um array ou `false` em caso de falha.

Os seguintes parâmetros são retornados no array
Parâmetro | Descrição
--- | ---
`"tm_sec"` | Segundos após o minuto (0-61)
`"tm_min"` | Minutos após a hora (0-59)
`"tm_hour"` | Horas passadas desde a meia-noite (0-23)
`"tm_mday"` | Dia do mês (1-31)
`"tm_mon"` | Meses passados desde janeiro (0-11)
`"tm_year"` | Anos passados desde 1900
`"tm_wday"` | Dias passados desde domingo (0-6)
`"tm_yday"` | Dias passados desde 1º de janeiro 1 (0-365)
`"unparsed"` | A parte `timestamp` que não foi reconhecida usando o `format` especificado

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Esta função foi descontinuada. Use date_parse_from_format() no lugar (para análise independente de localidade), ou IntlDateFormatter::parse() (para análise dependente de localidade).

### Exemplos

Exemplo #1 Exemplo da função strptime()

    <?php
    $format = '%d/%m/%Y %H:%M:%S';
    $strf = strftime($format);

    echo "$strf\n";

    print_r(strptime($strf, $format));

O exemplo acima produzirá algo semelhante a:

    03/10/2004 15:54:19

    Array
    (
        [tm_sec] => 19
        [tm_min] => 54
        [tm_hour] => 15
        [tm_mday] => 3
        [tm_mon] => 9
        [tm_year] => 104
        [tm_wday] => 0
        [tm_yday] => 276
        [unparsed] =>
    )

### Notas

> Nota: Esta função não foi implementada em plataformas Windows.

> Nota:

> Internamente, esta função chama a função `strptime()` presente na biblioteca C do sistema. Esta função pode apresentar um comportamento diferente entre diferentes sistemas operacionais. A utilização da função date_parse_from_format(), que não é afetada por esta questão, é recomendada.

> Nota:

> `"tm_sec"` inclui todos os segundos intercalares (atualmente 2 por ano). Para mais informações sobre segundos intercalares, veja o » o artigo da Wikipedia sobre segundos intercalares.

### Veja Também

- IntlDateFormatter::parse() - Interpreta uma string para uma valor de timestamp
- DateTime::createFromFormat() - Interpreta um string de data/horário de acordo com um formato especificado.
- checkdate() - Valida uma data gregoriana
- strftime() - Formata uma data/horário de acordo com as configurações locais
- date_parse_from_format() - Retorna informações sobre uma data informada de acordo com um formato

# strtotime

(PHP 4, PHP 5, PHP 7, PHP 8)

strtotime — Interpreta qualquer descrição textual de data/horário em inglês para timestamp Unix

### Descrição

function strtotime(string `$datetime`, ?int `$baseTimestamp` = `null`): int|false

A função espera que seja informada uma string contendo um formato de data em inglês US, e tentará interpretá-lo para um timestamp Unix (o número de segundos desde 1º de janeiro de 1970 00:00:00 GMT), relativo ao timestamp dado em `baseTimestamp`, ou o horário atual se `baseTimestamp` não for fornecido. A interpretação da string de data está definida em Formatos de Data e Horário, e tem várias considerações sutis. Rever os detalhes completos dessas definições é fortemente recomendado.

Aviso

O timestamp Unix que esta função retorna não contém informação sobre fuso horário. Para realizar cálculos com informação de data/horário, deve-se usar a classe com mais capacidade DateTimeImmutable.

Cada parâmetro desta função utiliza o fuso horário padrão, a não ser que um fuso horário seja especificado neste parâmetro. Tome cuidado para não utilizar fusos horários diferentes em cada um dos parâmetros a não ser que seja o pretendido. Veja a função date_default_timezone_get() para verificar as diversas formas de definir um fuso horário padrão.

### Parâmetros

`datetime`

  Uma string de data/hora. Os formatos válidos são explicados em Formatos de Data e Hora.

`baseTimestamp`

  O timestamp que será utilizado como base no cálculo das datas relativas.

### Valor Retornado

Retorna um timestamp em sucesso, `false` caso contrário.

### Erros/Exceções

Toda chamada a uma função de data/hora gerará um `E_WARNING` se o fuso horário não for válido. Veja também date_default_timezone_set()

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `baseTimestamp` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo da função strtotime()

    <?php
    echo strtotime("now"), "\n";
    echo strtotime("10 September 2000"), "\n";
    echo strtotime("+1 day"), "\n";
    echo strtotime("+1 week"), "\n";
    echo strtotime("+1 week 2 days 4 hours 2 seconds"), "\n";
    echo strtotime("next Thursday"), "\n";
    echo strtotime("last Monday"), "\n";

Exemplo #2 Verificando erros

    <?php
    $str = 'Not Good';

    if (($timestamp = strtotime($str)) === false) {
        echo "A string ($str) tem problemas";
    } else {
        echo "$str == " . date('l dS \o\f F Y h:i:s A', $timestamp);
    }

### Notas

> Nota:

> Data "relativa" neste caso também significa que se um componente em particular do timestamp de data/horário não for fornecido, ele será removido literalmente do parâmetro `baseTimestamp`. Isto é, `strtotime('February')`, se executado em 31 de maio de 2022, será interpretado como `31 de fevereiro de 2022`, o que vai transferir para um timestamp de `3 de março` (em um ano bissexto, seria `2 de março`). Usar `strtotime('1 February')` ou `strtotime('first day of February')` evitaria este problema.

> Nota:

> Se o número do ano for especificado no formato com dois dígitos, o valor entre 00-60 será mapeado para 2000-2069 e 70-99 para 1970-1999. Veja as notas a seguir para possíveis diferenças em sistemas de 32 bits (as datas possíveis acabam em 2038-01-19 03:14:07),

> Nota:

> O intervalo válido de um timestamp é tipicamente de Sex, 13 Dez 1901 20:45:54 GMT até Ter, 19 Jan 2038 03:14:07 GMT. Estas são datas que correspondem aos valores máximos e mínimos para um inteiro sem sinal em sistemas de 32 bits.

> Em versões do PHP em 64 bits, a faixa válida de um timestamp é praticamente infinita, já que 64 bits podem representar aproximadamente 293 bilhões de anos em ambas direções.

> Nota:

> O uso desta função para operações matemáticas não é recomendado. É melhor utilizar os métodos DateTime::add() e DateTime::sub().

### Veja Também

- DateTimeImmutable
- DateTimeImmutable::createFromFormat() - Interpreta um string de data/horário de acordo com o formato especificado
- Formatos de Data e Horário
- checkdate() - Valida uma data gregoriana
- strptime() - Interpreta uma data/horário gerada pela função strftime

# time

(PHP 4, PHP 5, PHP 7, PHP 8)

time — Retorna o timestamp Unix atual

### Descrição

function time(): int

Retorna o horário atual medido como o número de segundos desde a Época Unix (1 de janeiro de 1970 00:00:00 GMT).

> Nota:

> Timestamps Unix não contêm nenhuma informação sobre fuso horário local. Recomenda-se usar a classe DateTimeImmutable para lidar com informações de data e horário para evitar as armadilhas que vêm com o uso exclusivo de timestamps Unix.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o timestamp atual.

### Exemplos

Exemplo #1 Exemplo de time()

    <?php
    echo 'Agora: '. time();

O exemplo acima produzirá algo semelhante a:

    Agora: 1660338149

### Notas

Dica

O timestamp do início da requisição está disponível na variável $_SERVER['REQUEST_TIME'].

### Veja Também

- DateTimeImmutable
- date() - Formata um timestamp Unix
- microtime() - Retorna o timestamp Unix atual com microssegundos

# timezone_abbreviations_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_abbreviations_list — Sinônimo de DateTimeZone::listAbbreviations()

### Descrição

Esta função é um apelido para: DateTimeZone::listAbbreviations()

# timezone_identifiers_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_identifiers_list — Sinônimo de DateTimeZone::listIdentifiers()

### Descrição

Esta função é um apelido para: DateTimeZone::listIdentifiers()

# timezone_location_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

timezone_location_get — Sinônimo de DateTimeZone::getLocation()

### Descrição

Esta função é um apelido para: DateTimeZone::getLocation()

# timezone_name_from_abbr

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

timezone_name_from_abbr — Retorna um nome de fuso horário através da abreviação e do deslocamento UTC

### Descrição

function timezone_name_from_abbr(string `$abbr`, int `$utcOffset` = -1, int `$isDST` = -1): string|false

### Parâmetros

`abbr`

  A abreviação do fuso horário.

`utcOffset`

  Deslocamento em relação ao GMT em segundos. Sendo -1 o padrão, que significa que o primeiro fuso horário correspondente encontrado com `abbr` é retornado. Caso contrário o deslocamento é buscao, e caso não encontrado, o o primeiro fuso horário, com qualquer deslocamento, é retornado.

`isDST`

  Indicador do horário de verão. O padrão é -1, e informa que tendo o fuso horário horário de verão, ou não, este não será levado em consideração na busca. Se configurado para 1, então `utcOffset` é utilizado como diferença no horário de verão; se 0, então `utcOffset` é utilizado sem a diferença do horário de verão. Se `abbr` não existir, o fuso horário será buscado exclusivamente pelo `utcOffset` e `isDST`.

### Valor Retornado

Retorna o fuso horário em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Um exemplo da função timezone_name_from_abbr()

    <?php
    echo timezone_name_from_abbr("CET") . "\n";
    echo timezone_name_from_abbr("", 3600, 0) . "\n";

O exemplo acima produzirá algo semelhante a:

    Europe/Berlin
    Europe/Paris

### Veja Também

- timezone_abbreviations_list() - Sinônimo de DateTimeZone::listAbbreviations

# timezone_name_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_name_get — Sinônimo de DateTimeZone::getName()

### Descrição

Esta função é um apelido para: DateTimeZone::getName()

# timezone_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_offset_get — Sinônimo de DateTimeZone::getOffset()

### Descrição

Esta função é um apelido para: DateTimeZone::getOffset()

# timezone_open

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_open — Sinônimo de DateTimeZone::__construct()

### Descrição

Esta função é um apelido para: DateTimeZone::__construct()

# timezone_transitions_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_transitions_get — Sinônimo de DateTimeZone::getTransitions()

### Descrição

Esta função é um apelido para: DateTimeZone::getTransitions()

# timezone_version_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

timezone_version_get — Obtém a versão do banco de dados de fuso horário.

### Descrição

function timezone_version_get(): string

Obtém a versão atual do banco de dados de fuso horário.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string no formato `YYYY.incremento`, como em `2022.2`.

Se a versão instalada do banco de dados de fuso horário for antiga (por exemplo, ela não mostra o ano atual), pode-se atualizar a informação do fuso horário tanto atualizando a versão do PHP, ou instalando o pacote PECL » timezonedb.

Algumas distribuições Linux alteram o suporte do PHP para data/horário para usar uma fonte alternativa de informação de fuso horário. Neste caso, esta função irá retornar `0.system`. Recomenda-se instalar o pacote PECL » timezonedb neste caso também.

### Exemplos

Exemplo #1 Obtendo a versão do banco de dados de fuso horário

    <?php
    echo timezone_version_get();

O exemplo acima produzirá algo semelhante a:

    2022.2

### Veja Também

- Lista de fusos horários suportados

## Índice

- checkdate — Valida uma data gregoriana
- date — Formata um timestamp Unix
- date_add — Sinônimo de DateTime::add
- date_create — Cria um novo objeto DateTime
- date_create_from_format — Sinônimo de DateTime::createFromFormat
- date_create_immutable — Cria um novo objeto DateTimeImmutable
- date_create_immutable_from_format — Sinônimo de DateTimeImmutable::createFromFormat
- date_date_set — Sinônimo de DateTime::setDate
- date_default_timezone_get — Retorna o fuso horário padrão usado por todas as funções de data/horário em um script
- date_default_timezone_set — Configura o fuso horário padrão utilizado por todas as funções de data/horário em um script
- date_diff — Sinônimo de DateTime::diff
- date_format — Sinônimo de DateTime::format
- date_get_last_errors — Sinônimo de DateTimeImmutable::getLastErrors
- date_interval_create_from_date_string — Sinônimo de DateInterval::createFromDateString
- date_interval_format — Sinônimo de DateInterval::format
- date_isodate_set — Sinônimo de DateTime::setISODate
- date_modify — Sinônimo de DateTime::modify
- date_offset_get — Sinônimo de DateTime::getOffset
- date_parse — Retorna um array associativo com informações detalhadas da data/horário informada
- date_parse_from_format — Retorna informações sobre uma data informada de acordo com um formato
- date_sub — Sinônimo de DateTime::sub
- date_sun_info — Retorna um array com informações sobre pôr/nascer do sol e o início/fim do dia
- date_sunrise — Retorna a hora do nascer do sol para um dia e uma localicação informados
- date_sunset — Retorna a hora do pôr do sol para um dia e uma localização informados.
- date_time_set — Sinônimo de DateTime::setTime
- date_timestamp_get — Sinônimo de DateTime::getTimestamp
- date_timestamp_set — Sinônimo de DateTime::setTimestamp
- date_timezone_get — Sinônimo de DateTime::getTimezone
- date_timezone_set — Sinônimo de DateTime::setTimezone
- getdate — Recupera informações de data/horário
- gettimeofday — Obtém o horário atual
- gmdate — Formata uma data/horário GMT/CUT
- gmmktime — Obtém um timestamp Unix para uma data GMT
- gmstrftime — Formata uma data/horário GMT/UTC de acordo com as configurações de localidade
- idate — Formata uma parte de uma data/horário local como um inteiro
- localtime — Obtém o horário local
- microtime — Retorna o timestamp Unix atual com microssegundos
- mktime — Obtém um timestamp Unix de uma data
- strftime — Formata uma data/horário de acordo com as configurações locais
- strptime — Interpreta uma data/horário gerada pela função strftime
- strtotime — Interpreta qualquer descrição textual de data/horário em inglês para timestamp Unix
- time — Retorna o timestamp Unix atual
- timezone_abbreviations_list — Sinônimo de DateTimeZone::listAbbreviations
- timezone_identifiers_list — Sinônimo de DateTimeZone::listIdentifiers
- timezone_location_get — Sinônimo de DateTimeZone::getLocation
- timezone_name_from_abbr — Retorna um nome de fuso horário através da abreviação e do deslocamento UTC
- timezone_name_get — Sinônimo de DateTimeZone::getName
- timezone_offset_get — Sinônimo de DateTimeZone::getOffset
- timezone_open — Sinônimo de DateTimeZone::__construct
- timezone_transitions_get — Sinônimo de DateTimeZone::getTransitions
- timezone_version_get — Obtém a versão do banco de dados de fuso horário.

# Erros e Exceções de Data/Horário

- DateError (herda de Error)
  - DateObjectError DateRangeError
- DateException (herda de Exception)
  - - DateInvalidOperationException
    - DateInvalidTimezoneException
    - DateMalformedIntervalStringException
    - DateMalformedPeriodStringException
    - DateMalformedStringException

# Formatos de Data e Horário Suportados

Esta seção descreve todos os diferentes formatos em uma sintaxe BNF, que os analisadores de DateTimeImmutable, DateTime, date_create_immutable(), date_create(), date_parse() e strtotime() entendem. Os formatos estão agrupados por seção. Na maioria dos casos, formatos de diferentes seções, separados por espaços, vírgula ou ponto, podem ser utilizados com a mesma string data/horário. Para cada um dos formatos suportados, um ou mais exemplos estão disponíveis, assim como a descrição do formato. Nos formatos, caracteres entre aspas simples são insensíveis a maiúsculas/minúsculas (`'t'` pode ser `t` ou `T`), caracteres entre aspas duplas são sensíveis a maiúsculas/minúsculas (`"T"` só pode ser `T`).

Para formatar objetos DateTimeImmutable e DateTime, favor se referir à documentação do método DateTimeInterface::format().

Um conjunto geral de regras deve ser considerado.

1. O analisador permite para cada unidade (ano, mês, dia, hora, minuto, segundo) o intervalo completo de valores. Para um ano são apenas 4 dígitos, para um mês o intervalo é 0-12, dia é 0-31, hora é 0-24, e minuto é 0-59.
2. 60 é permitido para segundos, e algumas vezes strings com este segundo adicional aparecem. Porém, o PHP implementa o horário Unix onde "60" não é um segundo válido e por isso ocorre sobrecarga.
3. strtotime() retorna `false` se quaisquer números estiverem fora dos intervalos, e DateTimeImmutable::__construct() dispara uma exceção.
4. Se um string contém somente uma data, todos os elementos de horário são inicializados em 0.
5. Todos os elementos menos significativos são inicializados em 0 se alguma parte do horário estiver presente no string.
6. O analisador é muito simples, e não faz verificações adicionais, o que o torna mais rápido (e mais genérico).
7. Além das regras para os elementos de horário individuais, o analisador também entende formatos compostos mais específicos, como análise de timestamps Unix (`@1690388256`) e números de semana ISO (`2008-W28-3`).

8. Há uma verificação adicional se uma data inválida é fornecida:

       <?php
       $res = date_parse("2015-09-31");
       var_dump($res["warnings"]);

   O exemplo acima produzirá:

       array(1) {
         [11] =>
         string(27) "The parsed date was invalid"
       }

9. Já é possível lidar com casos extremos, mas neste caso a função DateTimeImmutable::createFromFormat() deve ser usada e o formato correto fornecido.

       <?php
       $res = DateTimeImmutable::createFromFormat("Y-m-d", "2015-09-34");
       var_dump($res);

   O exemplo acima produzirá:

       object(DateTimeImmutable)#1 (3) {
         ["date"]=>
         string(26) "2015-10-04 17:24:43.000000"
         ["timezone_type"]=>
         int(3)
         ["timezone"]=>
         string(13) "Europe/London"
       }

## Formatos de Horário

Esta página descreve os diferentes formatos de data/horário em uma sintaxe BNF, que os analisadores de DateTimeImmutable, DateTime, date_create(), date_create_immutable() e strtotime() entendem.

Para formatar objetos DateTimeImmutable e DateTime, favor se referir à documentação do método DateTimeInterface::format().

Símbolos utilizados
Descrição | Formatos | Exemplos
--- | --- | ---
`frac` | . [0-9]+ | ".21342", ".85"
`hh` | "0"?[1-9] | "1"[0-2] | "04", "7", "12"
`HH` | [01][0-9] | "2"[0-4] | "04", "07", "19"
`meridian` | [AaPp] .? [Mm] .? [\0\t ] | "A.m.", "pM", "am."
`MM` | [0-5][0-9] | "00", "12", "59"
`II` | [0-5][0-9] | "00", "12", "59"
`space` | [ \t] |
`tz` | "("? [A-Za-z]{1,6} ")"? | [A-Z][a-z]+([_/][A-Z][a-z]+)+ | "CEST", "Europe/Amsterdam", "America/Indiana/Knox"
`tzcorrection` | "GMT"? [+-] `hh` ":"? `MM`? | "+0400", "GMT-07:00", "-07:00"

Notação de 12 Horas
Descrição | Formatos | Exemplos
--- | --- | ---
Somente as horas, com o meridiano | `hh` `space`? `meridian` | "4 am", "5PM"
Horas e minutos, com o meridiano | `hh` [.:] `MM` `space`? `meridian` | "4:08 am", "7:19P.M."
Horas, minutos e segundos, com o meridiano | `hh` [.:] `MM` [.:] `II` `space`? `meridian` | "4:08:37 am", "7:19:19P.M."
MS SQL (Horas, minutos, segundos e a fração com o meridiano) | `hh` ":" `MM` ":" `II` [.:] [0-9]+ `meridian` | "4:08:39:12313am"

Notação de 24 Horas
Descrição | Formato | Exemplos
--- | --- | ---
Horas e minutos | 't'? `HH` [.:] `MM` | "04:08", "19.19", "T23:43"
Horas e minutos, sem dois-pontos | 't'? `HH` `MM` | "0408", "t1919", "T2343"
Horas, minutos e segundos | 't'? `HH` [.:] `MM` [.:] `II` | "04.08.37", "t19:19:19"
Horas, minutos e segundos, sem dois-pontos | 't'? `HH` `MM` `II` | "040837", "T191919"
Horas, minutos, segundos e fuso horário | 't'? `HH` [.:] `MM` [.:] `II` `space`? ( `tzcorrection` | `tz` ) | "040837CEST", "T191919-0700"
Horas, minutos, segundos e fração | 't'? `HH` [.:] `MM` [.:] `II` `frac` | "04.08.37.81412", "19:19:19.532453"
Informações do fuso horário | `tz` | `tzcorrection` | "CEST", "Europe/Amsterdam", "+0430", "GMT-06:00"

## Formatos de Data

Esta página descreve os diferentes formatos de data em uma sintaxe BNF, que os analisadores de DateTimeImmutable, DateTime, date_create(), date_create_immutable() e strtotime() entendem.

Para formatar objetos DateTimeImmutable e DateTime, favor se referir à documentação do método DateTimeInterface::format().

Simbolos Utilizados
Descrição | Formato | Exemplos
--- | --- | ---
`daysuf` | "st" | "nd" | "rd" | "th" |
`dd` | ([0-2]?[0-9] | "3"[01]) `daysuf`? | "7th", "22nd", "31"
`DD` | "0" [0-9] | [1-2][0-9] | "3" [01] | "07", "31"
`m` | 'january' | 'february' | 'march' | 'april' | 'may' | 'june' | 'july' | 'august' | 'september' | 'october' | 'november' | 'december' | 'jan' | 'feb' | 'mar' | 'apr' | 'may' | 'jun' | 'jul' | 'aug' | 'sep' | 'sept' | 'oct' | 'nov' | 'dec' | "I" | "II" | "III" | "IV" | "V" | "VI" | "VII" | "VIII" | "IX" | "X" | "XI" | "XII" |
`M` | 'jan' | 'feb' | 'mar' | 'apr' | 'may' | 'jun' | 'jul' | 'aug' | 'sep' | 'sept' | 'oct' | 'nov' | 'dec' |
`mm` | "0"? [0-9] | "1"[0-2] | "0", "04", "7", "12"
`MM` | "0" [0-9] | "1"[0-2] | "00", "04", "07", "12"
`y` | [0-9]{1,4} | "00", "78", "08", "8", "2008"
`yy` | [0-9]{2} | "00", "08", "78"
`YY` | [0-9]{4} | "2000", "2008", "1978"
`YYY` | [0-9]{5,19} | "81412", "20192"

Notações Localizadas
Descrição | Formato | Exemplos
--- | --- | ---
Dia e mês americano | `mm` "/" `dd` | "5/12", "10/27"
Dia, mês e ano americano | `mm` "/" `dd` "/" `y` | "12/22/78", "1/17/2006", "1/17/6"
Ano com quatro dígitos, mês e dia com barras | `YY` "/" `mm` "/" `dd` | "2008/6/30", "1978/12/22"
Ano com quatro dígitos e mês (GNU) | `YY` "-" `mm` | "2008-6", "2008-06", "1978-12"
Ano, mês e dia com traços | `y` "-" `mm` "-" `dd` | "2008-6-30", "78-12-22", "8-6-21"
Dia, mês e ano, com quatro dígitos, com pontos, tabulações ou traços | `dd` [.\t-] `mm` [.-] `YY` | "30-6-2008", "22.12.1978"
Dia, mês e ano, com dois dígitos, com pontos ou tabulações | `dd` [.\t] `mm` "." `yy` | "30.6.08", "22\t12.78"
Dia, mês textual e ano | `dd` ([ \t.-])* `m` ([ \t.-])* `y` | "30-June 2008", "22DEC78", "14 III 1879"
Mês textual e ano com quatro dígitos (O dia é redefinido para 1) | `m` ([ \t.-])* `YY` | "June 2008", "DEC1978", "March 1879"
Ano com quatro dígitos e mês textual (O dia é redefinido para 1) | `YY` ([ \t.-])* `m` | "2008 June", "1978-XII", "1879.MArCH"
Mês textual, dia e ano | `m` ([ .\t-])* `dd` [,.stndrh\t ]+ `y` | "July 1st, 2008", "April 17, 1790", "May.9,78"
Mês textual e dia | `m` ([ .\t-])* `dd` [,.stndrh\t ]* | "July 1st,", "Apr 17", "May.9"
Dia e mês textual | `dd` ([ .\t-])* `m` | "1 July", "17 Apr", "9.May"
Mês abreviado, dia e ano | `M` "-" `DD` "-" `y` | "May-09-78", "Apr-17-1790"
Ano, mês abreviado e dia | `y` "-" `M` "-" `DD` | "78-Dec-22", "1814-MAY-17"
Ano (somente o ano) | `YY` | "1978", "2008"
Year (expandido, 5-19 dígitos com sinal) | [+-] `YYY` | "-81120", "+20192"
Mês textual (somente o mês) | `m` | "March", "jun", "DEC"

Notação ISO8601
Descrição | Formato | Exemplos
--- | --- | ---
Ano com oito dígitos, mês e dia | `YY` `MM` `DD` | "15810726", "19780417", "18140517"
Ano com quatro dígitos, mês e dia com barras | `YY` "/" `MM` "/" `DD` | "2008/06/30", "1978/12/22"
Ano com dois dígitos, mês e dia com traços | `yy` "-" `MM` "-" `DD` | "08-06-30", "78-12-22"
Ano com quatro dígitos, com sinal opcional, mês e dia | [+-]? `YY` "-" `MM` "-" `DD` | "-0002-07-26", "+1978-04-17", "1814-05-17"
Ano com 5+ dígitos com sinal, mês e dia | [+-] `YYY` "-" `MM` "-" `DD` | "-81120-02-26", "+20192-04-17"

> Nota:

> Para os formatos `y` e `yy`, anos abaixo de 100 são manipulados de maneira especial quando os símbolos `y` ou `yy` são utilizados. Se o ano cair no período de 0 (incluso) a 69 (incluso), 2000 anos são adicionados. Se o ano cair no período de 70 (incluso) a 99 (incluso), então 1900 são adicionados. Isso significa que "00-01-01" será interpretado como "2000-01-01".

> Nota:

> O formato "Dia, mês e ano com dois dígitos, com pontos ou tabulações" (`dd` [.\t] `mm` "." `yy`) somente funciona para valores de ano que variam 61 (incluso) até 99 (incluso) - fora destes anos, o formato de tempo "`HH` [.:] `MM` [.:] `SS`" possui precedência.

> Nota:

> O formato "Ano (e somente o ano)", só funcionará de maneira confiável se uma string de horário já tiver sido encontrada. Caso contrário, se o ano de quatro dígitos corresponder a `HH` `MM`, estes dois elementos serão definidos no lugar.

> Para interpretear consistentemente só um valor de ano, use DateTimeImmutable::createFromFormat() com o especificador `Y`.

Cuidado

É possível exceder positivamente e negativamente os formatos `dd` e `DD`. Dia 0 corresponde a último dia do mês anterior, assim como excedências positivas contam no próximo mês. Isso faz com que "2008-08-00" seja equivalente a "2008-07-31" e "2008-07-31" seja equivalente a "2008-07-01" (junho possui somente 30 dias).

Note que o intervalo de dia é restrito a 0-31 como indicado pela expressão regular acima. Por isso, "2008-06-32" não é um string de data válida, por exemplo.

É possível exceder negativamente os formatos `mm` e `MM` com o valor 0. O valor de mês 0 corresponde a dezembro do mês anterior. Como exemplo, "2008-00-22" é equivalente a "2007-12-22".

Se os dois fatos forem combinados e o dia e o mês forem excedidos negativamente, o que segue acontece: "2008-00-00" primeiro será convertido para "2007-12-00" que então será convertido para "2007-11-30". Isso também acontece com a string "0000-00-00", que é transformada em "-0001-11-30" (o ano -1 ano calendário ISO 8601, que é 2 anos DC no calendário que antecede o calendário gregoriano).

## Formatos Compostos

Esta página descreve os diferentes formatos compostos de data/horário em uma sintaxe BNF, que os analisadores de DateTimeImmutable, DateTime, date_create(), date_create_immutable() e strtotime() entendem.

Para formatar objetos DateTimeImmutable e DateTime, favor se referir à documentação do método DateTimeInterface::format().

Símbolos Utilizados
Descrição | Formato | Exemplos
--- | --- | ---
`DD` | "0" [0-9] | [1-2][0-9] | "3" [01] | "02", "12", "31"
`doy` | "00"[1-9] | "0"[1-9][0-9] | [1-2][0-9][0-9] | "3"[0-5][0-9] | "36"[0-6] | "001", "012", "180", "350", "366"
`frac` | . [0-9]+ | ".21342", ".85"
`hh` | "0"?[1-9] | "1"[0-2] | "04", "7", "12"
`HH` | [01][0-9] | "2"[0-4] | "04", "07", "19"
`meridian` | [AaPp] .? [Mm] .? [\0\t ] | "A.m.", "pM", "am."
`ii` | [0-5]?[0-9] | "04", "8", "59"
`II` | [0-5][0-9] | "04", "08", "59"
`M` | 'jan' | 'feb' | 'mar' | 'apr' | 'may' | 'jun' | 'jul' | 'aug' | 'sep' | 'sept' | 'oct' | 'nov' | 'dec' |
`MM` | [0-1][0-9] | "00", "12"
`space` | [ \t] |
`ss` | [0-5]?[0-9]|60 | "04", "8", "59"
`SS` | [0-5][0-9] | "04", "08", "59", "60" (segundo intercalar)
`W` | "0"[1-9] | [1-4][0-9] | "5"[0-3] | "05", "17", "53"
`tzcorrection` | "GMT"? [+-] `hh` ":"? `II`? | "+0400", "GMT-07:00", "-07:00"
`YY` | [0-9]{4} | "2000", "2008", "1978"

Formatos padrões
Descrição | Exemplos
--- | ---
ATOM | "2022-06-02T16:58:35+00:00"
COOKIE | "Thursday, 02-Jun-2022 16:58:35 UTC"
ISO8601 | "2022-06-02T16:58:35+0000"
» RFC 822 | "Thu, 02 Jun 22 16:58:35 +0000"
» RFC 850 | "Thursday, 02-Jun-22 16:58:35 UTC"
» RFC 1036 | "Thu, 02 Jun 22 16:58:35 +0000"
» RFC 1123 | "Thu, 02 Jun 2022 16:58:35 +0000"
» RFC 2822 | "Thu, 02 Jun 2022 16:58:35 +0000"
» RFC 3339 | "2022-06-02T16:58:35+00:00"
» RFC 3339 estendida | "2022-06-02T16:58:35.698+00:00"
» RFC 7231 | "Thu, 02 Jun 2022 16:58:35 GMT"
RSS | "Thu, 02 Jun 2022 16:58:35 +0000"
W3C | "2022-06-02T16:58:35+00:00"

Notações Localizadas
Descrição | Formato | Exemplos
--- | --- | ---
Formato de Log Popular | `dd` "/" `M` "/" `YY` : `HH` ":" `II` ":" `SS` `space` `tzcorrection` | "10/Oct/2000:13:55:36 -0700"
EXIF | `YY` ":" `MM` ":" `DD` " " `HH` ":" `II` ":" `SS` | "2008:08:07 18:11:31"
Ano ISO com Semana ISO | `YY` "-"? "W" `W` | "2008W27", "2008-W28"
Ano ISO com Semana ISO e dia | `YY` "-"? "W" `W` "-"? [0-7] | "2008W273", "2008-W28-3"
MySQL | `YY` "-" `MM` "-" `DD` " " `HH` ":" `II` ":" `SS` | "2008-08-07 18:11:31"
PostgreSQL: Ano com dia do ano | `YY` "."? `doy` | "2008.197", "2008197"
SOAP | `YY` "-" `MM` "-" `DD` "T" `HH` ":" `II` ":" `SS` `frac` `tzcorrection`? | "2008-07-01T22:35:17.02", "2008-07-01T22:35:17.03+08:00"
Timestamp Unix | "@" "-"? [0-9]+ | "@1215282385"
Timestamp Unix com microssegundos | "@" "-"? [0-9]+ "." [0-9]{0,6} | "@1607974647.503686"
XMLRPC | `YY` `MM` `DD` "T" `hh` ":" `II` ":" `SS` | "20080701T22:38:07", "20080701T9:38:07"
XMLRPC (Compacto) | `YY` `MM` `DD` 't' `hh` `II` `SS` | "20080701t223807", "20080701T093807"
WDDX | `YY` "-" `mm` "-" `dd` "T" `hh` ":" `ii` ":" `ss` | "2008-7-1T9:3:37"

> Nota:

> O "W" nos formatos "Ano ISO com semana ISO" e "Ano ISO com semana ISO e dia" são sensíveis a maiúsculas/minúsculas, só pode ser usado o "W" maiúsculo.

> O "T", nos formatos SOAP, XMLRPC e WDDX é sensível a maiúsculas/minúsculas, só pode ser usado o "T" maiúsculo.

> O formato "Timestamp Unix" define o fuso horário para UTC.

## Formatos relativos

Esta página descreve os diferentes formatos de data/horário relativos em uma sintaxe BNF, que os analisadores de DateTimeImmutable, DateTime, date_create(), date_create_immutable() e strtotime() entendem.

Para formatar objetos DateTimeImmutable e DateTime, favor se referir à documentação do método DateTimeInterface::format().

Símbolos Utilizados
Descrição | Formato
--- | ---
`dayname` | 'sunday' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
`daytext` | 'weekday' | 'weekdays'
`number` | [+-]?[0-9]+
`ordinal` | 'first' | 'second' | 'third' | 'fourth' | 'fifth' | 'sixth' | 'seventh' | 'eighth' | 'ninth' | 'tenth' | 'eleventh' | 'twelfth' | 'next' | 'last' | 'previous' | 'this'
`reltext` | 'next' | 'last' | 'previous' | 'this'
`space` | [ \t]+
`unit` | 'ms' | 'µs' | (( 'msec' | 'millisecond' | 'µsec' | 'microsecond' | 'usec' | 'sec' | 'second' | 'min' | 'minute' | 'hour' | 'day' | 'fortnight' | 'forthnight' | 'month' | 'year') 's'?) | 'weeks' | `daytext`

Notação baseada no dia
Formato | Descrição | Exemplos
--- | --- | ---
'yesterday' | Meia-noite de ontem | "yesterday 14:00"
'midnight' | O horário é definido para 00:00:00 |
'today' | O horário é definido para 00:00:00 |
'now' | Agora - isto é simplesmente ignorado |
'noon' | O horário é definido para 12:00:00 | "yesterday noon"
'tomorrow' | Meia-noite de amanhã |
'back of' `hour` | 15 minutos após o horário informado | "back of 7pm", "back of 15"
'front of' `hour` | 15 minutos antes do horário informado | "front of 5am", "front of 23"
'first day of' | Define o dia para o primeiro dia do mês atual. Essa frase é normalmente usada da melhor forma em conjunto com um nome de mês, já que ela somente afeta o mês atual. | "first day of January 2008"
'last day of' | Define o dia para o último do mês corrente. Essa frase é normalmente usada da melhor forma em conjunto com um nome de mês, já que ela somente afeta o mês atual. | "last day of next month"
`ordinal` `space` `dayname` `space` 'of' | Calcula o número ordinal `x`-th da semana do mês corrente. | "first sat of July 2008"
'last' `space` `dayname` `space` 'of' | Calcular o último dia da semana do mês corrente. | "last sat of July 2008"
`number` `space`? (`unit` | 'week') | Manipula porções de tempo relativas onde o valor seja um número. | "+5 weeks", "12 day", "-7 weekdays"
(`ordinal` | `reltext`) `space` `unit` | Manipula porções de tempo relativas onde o valor seja um texto. `last` e `previous` são equivalentes a `-1`, `this` equivalente a nada, e `next` equivamente a `+1`. | "fifth day", "second month", "last day", "previous year"
'ago' | Nega todos os valores das porções de tempo relativas anteriores. | "2 days ago", "8 days ago 14:00", "2 months 5 days ago", "2 months ago 5 days", "2 days ago"
`dayname` | Move para o próximo dia deste nome.(See note) | "Monday"
`reltext` `space` 'week' | Manipula o formato especial "weekday + last/this/next week". | "Monday next week"

> Nota:

> Declarações relativas são sempre processadas depois de declarações não relativas. Isso faz com que "+1 week july 2008" e "july 2008 +1 week" sejam equivalentes.

> As exceções desta regra são "yesterday", "midnight", "today", "noon" e "tomorrow". Observe que "tomorrow 11:00" e "11:00 tomorrow" são diferentes. Considerando que a data hoje como "July 23rd, 2008", o primeiro produzirá "2008-07-24 11:00" assim como o segundo produzirá "2008-07-24 00:00". Isso acontece por que as cinco declarações influenciam diretamente o tempo corrente.

> Palavras-chave como "first day of" dependem do contexto no qual o string de formato relativo é usado. Se usado com um método ou funcão estáticos, a referência é o timestamp atual do sistema. Entretanto, se usado em DateTime::modify() ou DateTimeImmutable::modify(), a referência é o objeto no qual o método `modify()` é chamado.

> Nota:

> Observe as seguintes considerações quando o dia da semana corrente é o mesmo que o dia da semana utilizada na string date/horário. O dia da semana corrente pode ser (re-)calculado para porções não relativas de strings de data/horário.

> 1. "`dayname`" não avança para outro dia. (Exemplo: "Wed July 23rd, 2008" referencia "2008-07-23").
> 2. "`number` `dayname`" não avança para outro dia. (Exemplo: "1 wednesday july 23rd, 2008" referencia "2008-07-23").
> 3. "`number` week `dayname`" adicionará primeiro o dia da semana, mas not avançará para outro dia. Neste caso, "`number` week" e "`dayname`" são dois blocos distintos. (Exemplo: "+1 week wednesday july 23rd, 2008" referencia "2008-07-30").
> 4. "`ordinal` `dayname`" avançarápara outro dia. (Exemplo "first wednesday july 23rd, 2008" referencia "2008-07-30").
> 5. "`number` week `ordinal` `dayname`" adicionará primeiro o número de semanas, e então avançará para outro dia. Neste caso "`number` week" e "`ordinal` `dayname` são dois blocos distintos. (Exemplo: "+1 week first wednesday july 23rd, 2008" referencia "2008-08-06").
> 6. "`ordinal` `dayname` 'of' " não avança para outro dia. (Exemplo: "first wednesday of july 23rd, 2008" referencia "2008-07-02" porque a frase específica com 'of' redefine o dia do mês para '1' e o '23rd' é ignorado).

> Também observe que o "of" em "`ordinal` `space` `dayname` `space` 'of' " e "'last' `space` `dayname` `space` 'of' " fazem coisas especiais.

> 1. Ele definirá o dia do mês para 1.
> 2. "`ordinal` `dayname` 'of' " não avançará para outro dia. (Exemplo: "first tuesday of july 2008" referencia "2008-07-01").
> 3. "`ordinal` `dayname` " avançará para outro dia. (Exemplo: "first tuesday july 2008" referencia "2008-07-08", veja também o item 4 na lista acima).
> 4. "'last' `dayname` 'of' " captura o último `dayname` do mês corrente. (Exemplo: "last wed of july 2008" referencia "2008-07-30")
> 5. "'last' `dayname`" captura o último `dayname` do mês corrente. (Exemplo: "last wed july 2008" referencia "2008-06-25"; "july 2008" primeiro definirá a data corrente para "2008-07-01" e então "last wed" moverá para a última Quarta-feira que será "2008-06-25").

> Nota:

> Meses com valores relativos são calculados baseados no tamanho do mês passado. Um exemplo seria "+2 month 2011-11-30",que produziria "2012-01-30". Isso é devido a Novembro tendo 30 dias como tamanho, e Dezembro tendo 31, produzindo um total de 61 dias.

> Nota:

> `number` é um número inteiro; se um número decimal é informado, o ponto (ou vírgula) provavelmente será interpretado como delimitador. Por exemplo, `'+1.5 hours'` é analisado como `'+1 5 hours'`, não como `'+1 hour +30 minutes'`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `number` agora aceita novamente um sinal positivo seguido por um sinal negativo, por exemplo, `+-2` e outras combinações de múltiplos sinais.
8.2.0 | `number` não aceita mais um sinal positivo seguido por um sinal negativo, por exemplo, `+-2`.
7.0.8 | Semanas sempre começam na segunda-feira. Antes, considerava-se que o domingo também poderia começar uma semana.

# Lista de Fusos Horários Suportados

## Índice

- África
- América
- Antártica
- Ártico
- Ásia
- Atlântico
- Austrália
- Europa
- Índia
- Pacífico
- Outros

Aqui pode ser encontrada a lista completa de fusos horários suportados pelo PHP, os quais podem ser usados, por exemplo, com date_default_timezone_set().

Cuidado

O comportamento dos fusos horários não listados aqui é indefinido.

> Nota: A versão mais recente do banco de dados de fusos horários pode ser instalada através do pacote PECL » timezonedb.

> Nota: Esta lista é baseada na versão do banco de dados de fusos horários 2026.1.

## África

África
Africa/Abidjan | Africa/Accra | Africa/Addis_Ababa | Africa/Algiers
Africa/Asmara | Africa/Bamako | Africa/Bangui | Africa/Banjul
Africa/Bissau | Africa/Blantyre | Africa/Brazzaville | Africa/Bujumbura
Africa/Cairo | Africa/Casablanca | Africa/Ceuta | Africa/Conakry
Africa/Dakar | Africa/Dar_es_Salaam | Africa/Djibouti | Africa/Douala
Africa/El_Aaiun | Africa/Freetown | Africa/Gaborone | Africa/Harare
Africa/Johannesburg | Africa/Juba | Africa/Kampala | Africa/Khartoum
Africa/Kigali | Africa/Kinshasa | Africa/Lagos | Africa/Libreville
Africa/Lome | Africa/Luanda | Africa/Lubumbashi | Africa/Lusaka
Africa/Malabo | Africa/Maputo | Africa/Maseru | Africa/Mbabane
Africa/Mogadishu | Africa/Monrovia | Africa/Nairobi | Africa/Ndjamena
Africa/Niamey | Africa/Nouakchott | Africa/Ouagadougou | Africa/Porto-Novo
Africa/Sao_Tome | Africa/Tripoli | Africa/Tunis | Africa/Windhoek

## América

América
America/Adak | America/Anchorage | America/Anguilla | America/Antigua
America/Araguaina | America/Argentina/Buenos_Aires | America/Argentina/Catamarca | America/Argentina/Cordoba
America/Argentina/Jujuy | America/Argentina/La_Rioja | America/Argentina/Mendoza | America/Argentina/Rio_Gallegos
America/Argentina/Salta | America/Argentina/San_Juan | America/Argentina/San_Luis | America/Argentina/Tucuman
America/Argentina/Ushuaia | America/Aruba | America/Asuncion | America/Atikokan
America/Bahia | America/Bahia_Banderas | America/Barbados | America/Belem
America/Belize | America/Blanc-Sablon | America/Boa_Vista | America/Bogota
America/Boise | America/Cambridge_Bay | America/Campo_Grande | America/Cancun
America/Caracas | America/Cayenne | America/Cayman | America/Chicago
America/Chihuahua | America/Ciudad_Juarez | America/Costa_Rica | America/Coyhaique
America/Creston | America/Cuiaba | America/Curacao | America/Danmarkshavn
America/Dawson | America/Dawson_Creek | America/Denver | America/Detroit
America/Dominica | America/Edmonton | America/Eirunepe | America/El_Salvador
America/Fort_Nelson | America/Fortaleza | America/Glace_Bay | America/Goose_Bay
America/Grand_Turk | America/Grenada | America/Guadeloupe | America/Guatemala
America/Guayaquil | America/Guyana | America/Halifax | America/Havana
America/Hermosillo | America/Indiana/Indianapolis | America/Indiana/Knox | America/Indiana/Marengo
America/Indiana/Petersburg | America/Indiana/Tell_City | America/Indiana/Vevay | America/Indiana/Vincennes
America/Indiana/Winamac | America/Inuvik | America/Iqaluit | America/Jamaica
America/Juneau | America/Kentucky/Louisville | America/Kentucky/Monticello | America/Kralendijk
America/La_Paz | America/Lima | America/Los_Angeles | America/Lower_Princes
America/Maceio | America/Managua | America/Manaus | America/Marigot
America/Martinique | America/Matamoros | America/Mazatlan | America/Menominee
America/Merida | America/Metlakatla | America/Mexico_City | America/Miquelon
America/Moncton | America/Monterrey | America/Montevideo | America/Montserrat
America/Nassau | America/New_York | America/Nome | America/Noronha
America/North_Dakota/Beulah | America/North_Dakota/Center | America/North_Dakota/New_Salem | America/Nuuk
America/Ojinaga | America/Panama | America/Paramaribo | America/Phoenix
America/Port-au-Prince | America/Port_of_Spain | America/Porto_Velho | America/Puerto_Rico
America/Punta_Arenas | America/Rankin_Inlet | America/Recife | America/Regina
America/Resolute | America/Rio_Branco | America/Santarem | America/Santiago
America/Santo_Domingo | America/Sao_Paulo | America/Scoresbysund | America/Sitka
America/St_Barthelemy | America/St_Johns | America/St_Kitts | America/St_Lucia
America/St_Thomas | America/St_Vincent | America/Swift_Current | America/Tegucigalpa
America/Thule | America/Tijuana | America/Toronto | America/Tortola
America/Vancouver | America/Whitehorse | America/Winnipeg | America/Yakutat

## Antártica

Antártica
Antarctica/Casey | Antarctica/Davis | Antarctica/DumontDUrville | Antarctica/Macquarie
Antarctica/Mawson | Antarctica/McMurdo | Antarctica/Palmer | Antarctica/Rothera
Antarctica/Syowa | Antarctica/Troll | Antarctica/Vostok |

## Ártico

Ártico
Arctic/Longyearbyen

## Ásia

Ásia
Asia/Aden | Asia/Almaty | Asia/Amman | Asia/Anadyr
Asia/Aqtau | Asia/Aqtobe | Asia/Ashgabat | Asia/Atyrau
Asia/Baghdad | Asia/Bahrain | Asia/Baku | Asia/Bangkok
Asia/Barnaul | Asia/Beirut | Asia/Bishkek | Asia/Brunei
Asia/Chita | Asia/Colombo | Asia/Damascus | Asia/Dhaka
Asia/Dili | Asia/Dubai | Asia/Dushanbe | Asia/Famagusta
Asia/Gaza | Asia/Hebron | Asia/Ho_Chi_Minh | Asia/Hong_Kong
Asia/Hovd | Asia/Irkutsk | Asia/Jakarta | Asia/Jayapura
Asia/Jerusalem | Asia/Kabul | Asia/Kamchatka | Asia/Karachi
Asia/Kathmandu | Asia/Khandyga | Asia/Kolkata | Asia/Krasnoyarsk
Asia/Kuala_Lumpur | Asia/Kuching | Asia/Kuwait | Asia/Macau
Asia/Magadan | Asia/Makassar | Asia/Manila | Asia/Muscat
Asia/Nicosia | Asia/Novokuznetsk | Asia/Novosibirsk | Asia/Omsk
Asia/Oral | Asia/Phnom_Penh | Asia/Pontianak | Asia/Pyongyang
Asia/Qatar | Asia/Qostanay | Asia/Qyzylorda | Asia/Riyadh
Asia/Sakhalin | Asia/Samarkand | Asia/Seoul | Asia/Shanghai
Asia/Singapore | Asia/Srednekolymsk | Asia/Taipei | Asia/Tashkent
Asia/Tbilisi | Asia/Tehran | Asia/Thimphu | Asia/Tokyo
Asia/Tomsk | Asia/Ulaanbaatar | Asia/Urumqi | Asia/Ust-Nera
Asia/Vientiane | Asia/Vladivostok | Asia/Yakutsk | Asia/Yangon
Asia/Yekaterinburg | Asia/Yerevan |  |

## Atlântico

Atlântico
Atlantic/Azores | Atlantic/Bermuda | Atlantic/Canary | Atlantic/Cape_Verde
Atlantic/Faroe | Atlantic/Madeira | Atlantic/Reykjavik | Atlantic/South_Georgia
Atlantic/St_Helena | Atlantic/Stanley |  |

## Austrália

Austrália
Australia/Adelaide | Australia/Brisbane | Australia/Broken_Hill | Australia/Darwin
Australia/Eucla | Australia/Hobart | Australia/Lindeman | Australia/Lord_Howe
Australia/Melbourne | Australia/Perth | Australia/Sydney |

## Europa

Europa
Europe/Amsterdam | Europe/Andorra | Europe/Astrakhan | Europe/Athens
Europe/Belgrade | Europe/Berlin | Europe/Bratislava | Europe/Brussels
Europe/Bucharest | Europe/Budapest | Europe/Busingen | Europe/Chisinau
Europe/Copenhagen | Europe/Dublin | Europe/Gibraltar | Europe/Guernsey
Europe/Helsinki | Europe/Isle_of_Man | Europe/Istanbul | Europe/Jersey
Europe/Kaliningrad | Europe/Kirov | Europe/Kyiv | Europe/Lisbon
Europe/Ljubljana | Europe/London | Europe/Luxembourg | Europe/Madrid
Europe/Malta | Europe/Mariehamn | Europe/Minsk | Europe/Monaco
Europe/Moscow | Europe/Oslo | Europe/Paris | Europe/Podgorica
Europe/Prague | Europe/Riga | Europe/Rome | Europe/Samara
Europe/San_Marino | Europe/Sarajevo | Europe/Saratov | Europe/Simferopol
Europe/Skopje | Europe/Sofia | Europe/Stockholm | Europe/Tallinn
Europe/Tirane | Europe/Ulyanovsk | Europe/Vaduz | Europe/Vatican
Europe/Vienna | Europe/Vilnius | Europe/Volgograd | Europe/Warsaw
Europe/Zagreb | Europe/Zurich |  |

## Índia

Índia
Indian/Antananarivo | Indian/Chagos | Indian/Christmas | Indian/Cocos
Indian/Comoro | Indian/Kerguelen | Indian/Mahe | Indian/Maldives
Indian/Mauritius | Indian/Mayotte | Indian/Reunion |

## Pacífico

Pacífico
Pacific/Apia | Pacific/Auckland | Pacific/Bougainville | Pacific/Chatham
Pacific/Chuuk | Pacific/Easter | Pacific/Efate | Pacific/Fakaofo
Pacific/Fiji | Pacific/Funafuti | Pacific/Galapagos | Pacific/Gambier
Pacific/Guadalcanal | Pacific/Guam | Pacific/Honolulu | Pacific/Kanton
Pacific/Kiritimati | Pacific/Kosrae | Pacific/Kwajalein | Pacific/Majuro
Pacific/Marquesas | Pacific/Midway | Pacific/Nauru | Pacific/Niue
Pacific/Norfolk | Pacific/Noumea | Pacific/Pago_Pago | Pacific/Palau
Pacific/Pitcairn | Pacific/Pohnpei | Pacific/Port_Moresby | Pacific/Rarotonga
Pacific/Saipan | Pacific/Tahiti | Pacific/Tarawa | Pacific/Tongatapu
Pacific/Wake | Pacific/Wallis |  |

## Outros

Aviso

Não use nenhum dos fusos horários listados aqui (exceto o UTC), pois eles existem apenas por motivos de compatibilidade com versões anteriores e podem ter comportamento errôneo. Além disso, esses fusos horários podem ser removidos do banco de dados de fusos horários da IANA a qualquer momento.

Aviso

Se o aviso acima for desconsiderado, observe também que o banco de dados de fusos horários da IANA que fornece suporte aos fusos horários do PHP usa sinais no estilo POSIX, o que resulta nos fusos horários `Etc/GMT+n` e `Etc/GMT-n` sendo invertidos do uso comum.

Por exemplo, o fuso horário 8 horas à frente do GMT usado na China e na Austrália Ocidental (entre outros lugares) é, na verdade, `Etc/GMT-8` neste banco de dados, e não `Etc/GMT+8`, como normalmente esperado.

Novamente, é altamente recomendável que seja usado o fuso horário correto para sua localização, como `Asia/Shanghai` ou `Australia/Perth` nos exemplos acima.

Outros
Africa/Asmera | Africa/Timbuktu | America/Argentina/ComodRivadavia | America/Atka
America/Buenos_Aires | America/Catamarca | America/Coral_Harbour | America/Cordoba
America/Ensenada | America/Fort_Wayne | America/Godthab | America/Indianapolis
America/Jujuy | America/Knox_IN | America/Louisville | America/Mendoza
America/Montreal | America/Nipigon | America/Pangnirtung | America/Porto_Acre
America/Rainy_River | America/Rosario | America/Santa_Isabel | America/Shiprock
America/Thunder_Bay | America/Virgin | America/Yellowknife | Antarctica/South_Pole
Asia/Ashkhabad | Asia/Calcutta | Asia/Choibalsan | Asia/Chongqing
Asia/Chungking | Asia/Dacca | Asia/Harbin | Asia/Istanbul
Asia/Kashgar | Asia/Katmandu | Asia/Macao | Asia/Rangoon
Asia/Saigon | Asia/Tel_Aviv | Asia/Thimbu | Asia/Ujung_Pandang
Asia/Ulan_Bator | Atlantic/Faeroe | Atlantic/Jan_Mayen | Australia/ACT
Australia/Canberra | Australia/Currie | Australia/LHI | Australia/North
Australia/NSW | Australia/Queensland | Australia/South | Australia/Tasmania
Australia/Victoria | Australia/West | Australia/Yancowinna | Brazil/Acre
Brazil/DeNoronha | Brazil/East | Brazil/West | Canada/Atlantic
Canada/Central | Canada/Eastern | Canada/Mountain | Canada/Newfoundland
Canada/Pacific | Canada/Saskatchewan | Canada/Yukon | CET
Chile/Continental | Chile/EasterIsland | CST6CDT | Cuba
EET | Egypt | Eire | EST
EST5EDT | Etc/GMT | Etc/GMT+0 | Etc/GMT+1
Etc/GMT+10 | Etc/GMT+11 | Etc/GMT+12 | Etc/GMT+2
Etc/GMT+3 | Etc/GMT+4 | Etc/GMT+5 | Etc/GMT+6
Etc/GMT+7 | Etc/GMT+8 | Etc/GMT+9 | Etc/GMT-0
Etc/GMT-1 | Etc/GMT-10 | Etc/GMT-11 | Etc/GMT-12
Etc/GMT-13 | Etc/GMT-14 | Etc/GMT-2 | Etc/GMT-3
Etc/GMT-4 | Etc/GMT-5 | Etc/GMT-6 | Etc/GMT-7
Etc/GMT-8 | Etc/GMT-9 | Etc/GMT0 | Etc/Greenwich
Etc/UCT | Etc/Universal | Etc/UTC | Etc/Zulu
Europe/Belfast | Europe/Kiev | Europe/Nicosia | Europe/Tiraspol
Europe/Uzhgorod | Europe/Zaporozhye | Factory | GB
GB-Eire | GMT | GMT+0 | GMT-0
GMT0 | Greenwich | Hongkong | HST
Iceland | Iran | Israel | Jamaica
Japan | Kwajalein | Libya | MET
Mexico/BajaNorte | Mexico/BajaSur | Mexico/General | MST
MST7MDT | Navajo | NZ | NZ-CHAT
Pacific/Enderbury | Pacific/Johnston | Pacific/Ponape | Pacific/Samoa
Pacific/Truk | Pacific/Yap | Poland | Portugal
PRC | PST8PDT | ROC | ROK
Singapore | Turkey | UCT | Universal
US/Alaska | US/Aleutian | US/Arizona | US/Central
US/East-Indiana | US/Eastern | US/Hawaii | US/Indiana-Starke
US/Michigan | US/Mountain | US/Pacific | US/Samoa
UTC | W-SU | WET | Zulu

# A classe DateError

(PHP 8 >= 8.3.0)

## Introdução

Disparada quando o banco de dados de fuso horário não for encontrado ou contiver dados inválidos.

Este erro nunca deveria ocorrer, e não é dependente do código. Existem duas exceções-filhas (DateObjectError e DateRangeError) que são disparadas dependendo do erro do programados ou de problemas relacionados a faixas de datas.

## Resumo da classe

class DateError extends Error {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

## Veja Também

- DateObjectError
- DateRangeError

# A classe DateObjectError

(PHP 8 >= 8.3.0)

## Introdução

Disparada quando uma das classe de Data/Horário não foi corretamente inicializada.

Como as classes de Data/Horário não são finais, eles podem ser herdadas. Quando um construtor da classe superior não for chamado, este erro é lançado. Este é sempre um erro de programação.

## Resumo da classe

class DateObjectError extends DateError {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

## Veja Também

- DateError
- DateRangeError

# A classe DateRangeError

(PHP 8 >= 8.3.0)

## Introdução

Disparada por DateTime::getTimestamp(), DateTimeImmutable::getTimestamp() e date_timestamp_get()em plataformas de 32 bits se o objeto representa uma data fora da faixa de inteiros de 32 bits com sinal.

## Resumo da classe

class DateRangeError extends DateError {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

## Veja Também

- DateError
- DateObjectError

# A classe DateException

(PHP 8 >= 8.3.0)

## Introdução

Classe mãe das exceções de Data/Horário, para problemas que surgem devido a entradas do usuário ou argumentos texto em formato livre que precisam ser analisados.

As exceções-filhas a seguir são disparadas pela extensão:

- DateInvalidOperationException
- DateInvalidTimezoneException
- DateMalformedIntervalStringException
- DateMalformedPeriodStringException
- DateMalformedStringException

## Resumo da classe

class DateException extends Exception {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# A classe DateInvalidOperationException

(PHP 8 >= 8.3.0)

## Introdução

Disparada por DateTimeImmutable::sub() e DateTime::sub() quando uma operação não suportada é solicitada.

Um exemplo de operação não suportada é o uso de um objeto DateInterval representando especificação de tempo relativo como `next weekday`, que não permite construir um objeto por ser inválido.

## Resumo da classe

class DateInvalidOperationException extends DateException {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# A classe DateInvalidTimeZoneException

(PHP 8 >= 8.3.0)

## Introdução

Disparada quando um valor incorreto é passado para DateTimeZone::__construct().

## Resumo da classe

class DateInvalidTimeZoneException extends DateException {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# The DateMalformedIntervalStringException class

(PHP 8 >= 8.3.0)

## Introdução

Disparada quando um argumento `duration` inválido é passado para DateInterval::__construct().

## Resumo da classe

class DateMalformedIntervalStringException extends DateException {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# A classe DateMalformedPeriodStringException

(PHP 8 >= 8.3.0)

## Introdução

Disparaqa quando um argumento `isostr` inválido é passado para DatePeriod::__construct().

## Resumo da classe

class DateMalformedPeriodStringException extends DateException {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# A classe DateMalformedStringException

(PHP 8 >= 8.3.0)

## Introdução

Disparada quando uma string inválida de Data/Horário é detectada.

Pode ser um valor para DateTimeImmutable::__construct(), DateTimeImmutable::modify(), DateTime::__construct() ou DateTime::modify().

## Resumo da classe

class DateMalformedStringException extends DateException {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

- Instalação/Configuração
  - Instalação
  - Configurações em Execução
- Constantes predefinidas
- Exemplos
  - Aritmética de Data e Horário
- DateTime — A classe DateTime
  - DateTime::add — Modifica um objeto DateTime, com adição de dias, meses, anos, horas, minutos e segundos.
  - DateTime::__construct — Retorna um novo objeto DateTime
  - DateTime::createFromFormat — Interpreta um string de data/horário de acordo com um formato especificado.
  - DateTime::createFromImmutable — Retorna uma nova instância de DateTime encapsulando o objeto DateTimeImmutable informado
  - DateTime::createFromInterface — Retorna um novo objeto DateTime encapsulando o objeto DateTimeInterface informado
  - DateTime::createFromTimestamp — Cria uma instância a partir de um timestamp Unix
  - DateTime::getLastErrors — Sinônimo de DateTimeImmutable::getLastErrors
  - DateTime::modify — Altera o timestamp
  - DateTime::__set_state — O manipulador __set_state
  - DateTime::setDate — Define a data
  - DateTime::setISODate — Define uma data ISO
  - DateTime::setMicrosecond — Define a parte de microssegundos do horário
  - DateTime::setTime — Define o horário
  - DateTime::setTimestamp — Define a data e hora baseada em um timestamp Unix
  - DateTime::setTimezone — Define o fuso horário de um objeto DateTime
  - DateTime::sub — Subtrai uma quantidade de dias, meses, anos, horas, minutos e segundos de um objeto DateTime
- DateTimeImmutable — A classe DateTimeImmutable
  - DateTimeImmutable::add — Retorna um novo objeto, com adição de dias, meses, anos, horas, minutos e segundos
  - DateTimeImmutable::__construct — Retorna um novo objeto DateTimeImmutable
  - DateTimeImmutable::createFromFormat — Interpreta um string de data/horário de acordo com o formato especificado
  - DateTimeImmutable::createFromInterface — Retorna um novo objeto DateTimeImmutable encapsulando o objeto DateTimeInterface informado
  - DateTimeImmutable::createFromMutable — Retorna uma nova instância DateTimeImmutable que encapsula um objeto DateTime informado
  - DateTimeImmutable::createFromTimestamp — Cria uma instância a partir de um timestamp Unix
  - DateTimeImmutable::getLastErrors — Retorna os avisos e erros
  - DateTimeImmutable::modify — Cria um novo objeto com seu timestamp modificado
  - DateTimeImmutable::__set_state — O manipulador __set_state
  - DateTimeImmutable::setDate — Define a data
  - DateTimeImmutable::setISODate — Define a data ISO
  - DateTimeImmutable::setMicrosecond — Define a parte de microssegundos do horário
  - DateTimeImmutable::setTime — Define um horário
  - DateTimeImmutable::setTimestamp — Define a data e o horário com base em um timestamp Unix
  - DateTimeImmutable::setTimezone — Define o fuso horário
  - DateTimeImmutable::sub — Subtrai uma quantidade de dias, meses, anos, horas, minutos e segundos
- DateTimeInterface — A interface DateTimeInterface
  - DateTimeInterface::diff — Retorna a diferença entre dois objetos DateTime
  - DateTimeInterface::format — Retorna a data formatada de acordo com um formato informado
  - DateTimeInterface::getMicrosecond — Obtém a parte de microssegundos do timestamp Unix
  - DateTimeInterface::getOffset — Retorna o deslocamento do fuso horário
  - DateTimeInterface::getTimestamp — Obtém o timestamp Unix
  - DateTimeInterface::getTimezone — Retorna o fuso horário correspondente a um DateTime informado
  - DateTime::__serialize — Serializa um DateTime
  - DateTime::__unserialize — Desserializa um Datetime
  - DateTime::__wakeup — O manipulador __wakeup
- DateTimeZone — A classe DateTimeZone
  - DateTimeZone::__construct — Cria um novo objeto DateTimeZone
  - DateTimeZone::getLocation — Retorna informações da localização de um fuso horário
  - DateTimeZone::getName — Retorna o nome do fuso horário
  - DateTimeZone::getOffset — Retorna o deslocamento do fuso horário em relação ao GMT
  - DateTimeZone::getTransitions — Retorna todas as transições para o fuso horário
  - DateTimeZone::listAbbreviations — Retorna um array associativo contendo indicativo de horário de verão, deslocamento e nome do fuso horário
  - DateTimeZone::listIdentifiers — Retorna um array numericamente indexado contendo todos os indenticadores de fuso horário
- DateInterval — A classe DateInterval
  - DateInterval::__construct — Cria um novo objeto DateInterval
  - DateInterval::createFromDateString — Cria um DateInterval de porções relativas da string
  - DateInterval::format — Formata um intervalo
- DatePeriod — A classe DatePeriod
  - DatePeriod::__construct — Cria um novo objeto DatePeriod
  - DatePeriod::createFromISO8601String — Cria um novo objeto DatePeriod a partir de uma string ISO8601
  - DatePeriod::getDateInterval — Obtém o intervalo
  - DatePeriod::getEndDate — Obtém a data final
  - DatePeriod::getRecurrences — Obtém o número de recorrências
  - DatePeriod::getStartDate — Obtém a data inicial
- Funções de Data/Horário
  - checkdate — Valida uma data gregoriana
  - date — Formata um timestamp Unix
  - date_add — Sinônimo de DateTime::add
  - date_create — Cria um novo objeto DateTime
  - date_create_from_format — Sinônimo de DateTime::createFromFormat
  - date_create_immutable — Cria um novo objeto DateTimeImmutable
  - date_create_immutable_from_format — Sinônimo de DateTimeImmutable::createFromFormat
  - date_date_set — Sinônimo de DateTime::setDate
  - date_default_timezone_get — Retorna o fuso horário padrão usado por todas as funções de data/horário em um script
  - date_default_timezone_set — Configura o fuso horário padrão utilizado por todas as funções de data/horário em um script
  - date_diff — Sinônimo de DateTime::diff
  - date_format — Sinônimo de DateTime::format
  - date_get_last_errors — Sinônimo de DateTimeImmutable::getLastErrors
  - date_interval_create_from_date_string — Sinônimo de DateInterval::createFromDateString
  - date_interval_format — Sinônimo de DateInterval::format
  - date_isodate_set — Sinônimo de DateTime::setISODate
  - date_modify — Sinônimo de DateTime::modify
  - date_offset_get — Sinônimo de DateTime::getOffset
  - date_parse — Retorna um array associativo com informações detalhadas da data/horário informada
  - date_parse_from_format — Retorna informações sobre uma data informada de acordo com um formato
  - date_sub — Sinônimo de DateTime::sub
  - date_sun_info — Retorna um array com informações sobre pôr/nascer do sol e o início/fim do dia
  - date_sunrise — Retorna a hora do nascer do sol para um dia e uma localicação informados
  - date_sunset — Retorna a hora do pôr do sol para um dia e uma localização informados.
  - date_time_set — Sinônimo de DateTime::setTime
  - date_timestamp_get — Sinônimo de DateTime::getTimestamp
  - date_timestamp_set — Sinônimo de DateTime::setTimestamp
  - date_timezone_get — Sinônimo de DateTime::getTimezone
  - date_timezone_set — Sinônimo de DateTime::setTimezone
  - getdate — Recupera informações de data/horário
  - gettimeofday — Obtém o horário atual
  - gmdate — Formata uma data/horário GMT/CUT
  - gmmktime — Obtém um timestamp Unix para uma data GMT
  - gmstrftime — Formata uma data/horário GMT/UTC de acordo com as configurações de localidade
  - idate — Formata uma parte de uma data/horário local como um inteiro
  - localtime — Obtém o horário local
  - microtime — Retorna o timestamp Unix atual com microssegundos
  - mktime — Obtém um timestamp Unix de uma data
  - strftime — Formata uma data/horário de acordo com as configurações locais
  - strptime — Interpreta uma data/horário gerada pela função strftime
  - strtotime — Interpreta qualquer descrição textual de data/horário em inglês para timestamp Unix
  - time — Retorna o timestamp Unix atual
  - timezone_abbreviations_list — Sinônimo de DateTimeZone::listAbbreviations
  - timezone_identifiers_list — Sinônimo de DateTimeZone::listIdentifiers
  - timezone_location_get — Sinônimo de DateTimeZone::getLocation
  - timezone_name_from_abbr — Retorna um nome de fuso horário através da abreviação e do deslocamento UTC
  - timezone_name_get — Sinônimo de DateTimeZone::getName
  - timezone_offset_get — Sinônimo de DateTimeZone::getOffset
  - timezone_open — Sinônimo de DateTimeZone::__construct
  - timezone_transitions_get — Sinônimo de DateTimeZone::getTransitions
  - timezone_version_get — Obtém a versão do banco de dados de fuso horário.
- Erros e Exceções de Data/Horário
- Formatos de Data e Horário Suportados
- Lista de Fusos Horários Suportados
  - África
  - América
  - Antártica
  - Ártico
  - Ásia
  - Atlântico
  - Austrália
  - Europa
  - Índia
  - Pacífico
  - Outros
- DateError — A classe DateError
- DateObjectError — A classe DateObjectError
- DateRangeError — A classe DateRangeError
- DateException — A classe DateException
- DateInvalidOperationException — A classe DateInvalidOperationException
- DateInvalidTimeZoneException — A classe DateInvalidTimeZoneException
- DateMalformedIntervalStringException — The DateMalformedIntervalStringException class
- DateMalformedPeriodStringException — A classe DateMalformedPeriodStringException
- DateMalformedStringException — A classe DateMalformedStringException

# Temporização de alta resolução

# Introdução

A extensão HRTime implementa uma classe StopWatch de alta resolução. Ela usa as melhores APIs possíveis em diferentes plataformas, o que traz resolução de até nanossegundos. Ela também torna possível implementar um cronômetro personalizado usando tiques de baixo nível entregues pelas APIs subjacentes.

> Nota: A partir do PHP 7.3.0, a função relacionada hrtime() faz parte do núcleo.

# Instalação/Configuração

## Índice

- Instalação

## Instalação

Esta extensão » PECL não é distribuída com o PHP.

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/hrtime.

# Exemplos

## Índice

- Uso básico

## Uso básico

O exemplo ilustra o uso básico da classe StopWatch

Exemplo #1 Meça a execução de vários blocos de código e obtenha o total

    <?php

    $c = new HRTime\StopWatch;

    $c->start();
    /* mede a execução deste bloco de código */
    for ($i = 0; $i < 1024*1024; $i++);
    $c->stop();
    $elapsed0 = $c->getLastElapsedTime(HRTime\Unit::NANOSECOND);

    /* a medição não está sendo executada aqui*/
    for ($i = 0; $i < 1024*1024; $i++);

    $c->start();
    /* mede a execução deste bloco de código */
    for ($i = 0; $i < 1024*1024; $i++);
    $c->stop();
    $elapsed1 = $c->getLastElapsedTime(HRTime\Unit::NANOSECOND);

    $elapsed_total = $c->getElapsedTime(HRTime\Unit::NANOSECOND);

    ?>

# A classe HRTime\PerformanceCounter

(PECL hrtime >= 0.4.3)

## Introdução

## Resumo da classe

class HRTime\PerformanceCounter {
/* Métodos */
public static function getFrequency(): int
public static function getTicks(): int
public static function getTicksSince(int `$start`): int
}

# HRTime\PerformanceCounter::getFrequency

(PECL hrtime >= 0.4.3)

HRTime\PerformanceCounter::getFrequency — Frequência do temporizador em tiques por segundo

### Descrição

public static function HRTime\PerformanceCounter::getFrequency(): int

Retorna a frequência do temporizador em tiques por segundo. Este valor é constante após a inicialização em quase todos os sistemas operacionais.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um int indicando a frequência do temporizador.

# HRTime\PerformanceCounter::getTicks

(PECL hrtime >= 0.6.0)

HRTime\PerformanceCounter::getTicks — Tiques atuais do sistema

### Descrição

public static function HRTime\PerformanceCounter::getTicks(): int

Retorna a contagem de tiques.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um int indicando a contagem de tiques.

# HRTime\PerformanceCounter::getTicksSince

(PECL hrtime >= 0.6.0)

HRTime\PerformanceCounter::getTicksSince — Tiques decorridos desde um valor informado

### Descrição

public static function HRTime\PerformanceCounter::getTicksSince(int `$start`): int

Retorna a contagem de tiques decorridos desde o valor de início informado.

### Parâmetros

`start`
  Valor de início da contagem dos tiques.

### Valor Retornado

Retorna um int indicando a contagem de tiques.

## Índice

- HRTime\PerformanceCounter::getFrequency — Frequência do temporizador em tiques por segundo
- HRTime\PerformanceCounter::getTicks — Tiques atuais do sistema
- HRTime\PerformanceCounter::getTicksSince — Tiques decorridos desde um valor informado

# A classe HRTime\StopWatch

(PECL hrtime >= 0.4.3)

## Introdução

## Resumo da classe

class HRTime\StopWatch extends HRTime\PerformanceCounter {
/* Métodos */
public function getElapsedTicks(): int
public function getElapsedTime(int `$unit` = ?): float
public function getLastElapsedTicks(): int
public function getLastElapsedTime(int `$unit` = ?): float
public function isRunning(): bool
public function start(): void
public function stop(): void
/* Métodos herdados */
public static function HRTime\PerformanceCounter::getFrequency(): int
public static function HRTime\PerformanceCounter::getTicks(): int
public static function HRTime\PerformanceCounter::getTicksSince(int `$start`): int
}

# HRTime\StopWatch::getElapsedTicks

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getElapsedTicks — Obtém os tiques decorridos para todos os intervalos

### Descrição

public function HRTime\StopWatch::getElapsedTicks(): int

Obtém os tiques decorridos para todos os intervalos previamente fechados.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um int indicando os tiques decorridos.

# HRTime\StopWatch::getElapsedTime

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getElapsedTime — Obtém o tempo decorrido para todos os intervalos

### Descrição

public function HRTime\StopWatch::getElapsedTime(int `$unit` = ?): float

Obtém o tempo decorrido para todos os intervalos previamente fechados.

### Parâmetros

`unit`
  Unidade de tempo representada por uma constante HRTime\Unit. O padrão é HRTime\Unit::SECOND.

### Valor Retornado

Retorna um float indicando o tempo decorrido.

# HRTime\StopWatch::getLastElapsedTicks

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getLastElapsedTicks — Obtém os tiques decorridos para o último intervalo

### Descrição

public function HRTime\StopWatch::getLastElapsedTicks(): int

Obtém os tiques decorridos para o último intervalo previamente fechado.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um int indicando od tiques decorridos.

# HRTime\StopWatch::getLastElapsedTime

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getLastElapsedTime — Obtém o tempo decorrido para o último intervalo

### Descrição

public function HRTime\StopWatch::getLastElapsedTime(int `$unit` = ?): float

Obtém o tempo decorrido para o último intervalo previamente fechado.

### Parâmetros

`unit`
  Unidade de tempo representada por uma constante HRTime\Unit. O padrão é HRTime\Unit::SECOND.

### Valor Retornado

Retorna um float indicando o tempo decorrido.

# HRTime\StopWatch::isRunning

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::isRunning — Informa se a medição está em execução

### Descrição

public function HRTime\StopWatch::isRunning(): bool

Revela se a medição foi iniciada.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um bool indicando se a medição está em execução.

# HRTime\StopWatch::start

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::start — Inicia a medição de tempo

### Descrição

public function HRTime\StopWatch::start(): void

Inicia a medição de tempo. Não tem efeito se a medição já tiver sido iniciada. A medição será continuada se tiver sido parada anteriormente.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna void.

# HRTime\StopWatch::stop

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::stop — Para a medição do tempo

### Descrição

public function HRTime\StopWatch::stop(): void

Para a medição do tempo para o intervalo iniciado anteriormente.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna void.

## Índice

- HRTime\StopWatch::getElapsedTicks — Obtém os tiques decorridos para todos os intervalos
- HRTime\StopWatch::getElapsedTime — Obtém o tempo decorrido para todos os intervalos
- HRTime\StopWatch::getLastElapsedTicks — Obtém os tiques decorridos para o último intervalo
- HRTime\StopWatch::getLastElapsedTime — Obtém o tempo decorrido para o último intervalo
- HRTime\StopWatch::isRunning — Informa se a medição está em execução
- HRTime\StopWatch::start — Inicia a medição de tempo
- HRTime\StopWatch::stop — Para a medição do tempo

# A classe HRTime\Unit

(PECL hrtime >= 0.4.3)

## Introdução

## Resumo da classe

class HRTime\Unit {
/* Constantes */
const int SECOND = 0;
const int MILLISECOND = 1;
const int MICROSECOND = 2;
const int NANOSECOND = 3;
/* Métodos */
}

## Constantes predefinidas

`HRTime\Unit::SECOND`
`HRTime\Unit::MILLISECOND`
`HRTime\Unit::MICROSECOND`
`HRTime\Unit::NANOSECOND`

- Instalação/Configuração
  - Instalação
- Exemplos
  - Uso básico
- HRTime\PerformanceCounter — A classe HRTime\PerformanceCounter
  - HRTime\PerformanceCounter::getFrequency — Frequência do temporizador em tiques por segundo
  - HRTime\PerformanceCounter::getTicks — Tiques atuais do sistema
  - HRTime\PerformanceCounter::getTicksSince — Tiques decorridos desde um valor informado
- HRTime\StopWatch — A classe HRTime\StopWatch
  - HRTime\StopWatch::getElapsedTicks — Obtém os tiques decorridos para todos os intervalos
  - HRTime\StopWatch::getElapsedTime — Obtém o tempo decorrido para todos os intervalos
  - HRTime\StopWatch::getLastElapsedTicks — Obtém os tiques decorridos para o último intervalo
  - HRTime\StopWatch::getLastElapsedTime — Obtém o tempo decorrido para o último intervalo
  - HRTime\StopWatch::isRunning — Informa se a medição está em execução
  - HRTime\StopWatch::start — Inicia a medição de tempo
  - HRTime\StopWatch::stop — Para a medição do tempo
- HRTime\Unit — A classe HRTime\Unit

- Calendário
  - Instalação/Configuração
  - Constantes predefinidas
  - Calendário Funções
- Data/Horário — Data e Horário
  - Instalação/Configuração
  - Constantes predefinidas
  - Exemplos
  - DateTime — A classe DateTime
  - DateTimeImmutable — A classe DateTimeImmutable
  - DateTimeInterface — A interface DateTimeInterface
  - DateTimeZone — A classe DateTimeZone
  - DateInterval — A classe DateInterval
  - DatePeriod — A classe DatePeriod
  - Funções de Data/Horário
  - Erros e Exceções de Data/Horário
  - Formatos de Data e Horário Suportados
  - Lista de Fusos Horários Suportados
  - DateError — A classe DateError
  - DateObjectError — A classe DateObjectError
  - DateRangeError — A classe DateRangeError
  - DateException — A classe DateException
  - DateInvalidOperationException — A classe DateInvalidOperationException
  - DateInvalidTimeZoneException — A classe DateInvalidTimeZoneException
  - DateMalformedIntervalStringException — The DateMalformedIntervalStringException class
  - DateMalformedPeriodStringException — A classe DateMalformedPeriodStringException
  - DateMalformedStringException — A classe DateMalformedStringException
- HRTime — Temporização de alta resolução
  - Instalação/Configuração
  - Exemplos
  - HRTime\PerformanceCounter — A classe HRTime\PerformanceCounter
  - HRTime\StopWatch — A classe HRTime\StopWatch
  - HRTime\Unit — A classe HRTime\Unit

# Extensões Relacionadas a Sistema de Arquivo

# E/S Direta

# Introdução

O PHP oferece suporte às funções de E/S Direta, conforme descrito no Padrão Posix (Seção 6), para realizar funções de E/S em um nível mais baixo do que as funções de E/S de fluxo da linguagem C (fopen(), fread(),..). O uso das funções de E/S Direta deve ser considerado apenas quando é necessário o controle direto de um dispositivo. Em todos os outros casos, as funções padrão do sistema de arquivos são mais do que adequadas.

# Instalação/Configuração

## Índice

- Instalação
- Tipos de Recurso

## Instalação

Esta extensão » PECL não é distribuída com o PHP.

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/dio.

## Tipos de Recurso

Um tipo de recurso é definido por esta extensão: um descritor de arquivo retornado por dio_open().

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`F_DUPFD` (int)

`F_GETFD` (int)

`F_GETFL` (int)

`F_GETLK` (int)

`F_GETOWN` (int)

`F_RDLCK` (int)

`F_SETFL` (int)

`F_SETLK` (int)

`F_SETLKW` (int)

`F_SETOWN` (int)

`F_UNLCK` (int)

`F_WRLCK` (int)

`O_APPEND` (int)

`O_ASYNC` (int)

`O_CREAT` (int)

`O_EXCL` (int)

`O_NDELAY` (int)

`O_NOCTTY` (int)

`O_NONBLOCK` (int)

`O_RDONLY` (int)

`O_RDWR` (int)

`O_SYNC` (int)

`O_TRUNC` (int)

`O_WRONLY` (int)

`S_IRGRP` (int)

`S_IROTH` (int)

`S_IRUSR` (int)

`S_IRWXG` (int)

`S_IRWXO` (int)

`S_IRWXU` (int)

`S_IWGRP` (int)

`S_IWOTH` (int)

`S_IWUSR` (int)

`S_IXGRP` (int)

`S_IXOTH` (int)

`S_IXUSR` (int)

# Funções de E/S Direta

# dio_close

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_close — Fecha o descritor de arquivo fornecido por fd

### Descrição

function dio_close(resource `$fd`): void

A função dio_close() fecha o descritor de arquivo `fd`.

### Parâmetros

`fd`

  O descritor de arquivo retornado por dio_open().

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Fechando um descritor de arquivo aberto

    <?php
    $fd = dio_open('/dev/ttyS0', O_RDWR);

    dio_close($fd);
    ?>

### Veja Também

- dio_open() - Abre um arquivo (criando-o, se necessário) em um nível mais baixo do que as funções de entrada/saída da biblioteca C permitem

# dio_fcntl

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_fcntl — Realiza uma chamada à função fcntl da biblioteca C no descritor de arquivo

### Descrição

function dio_fcntl(resource `$fd`, int `$cmd`, mixed `$args` = ?): mixed

A função dio_fcntl() realiza a operação especificada por `cmd` no descritor de arquivo `fd`. Alguns comandos exigem que argumentos adicionais `args` sejam fornecidos.

### Parâmetros

`fd`

  O descritor de arquivo retornado por dio_open().

`cmd`

  Pode ser uma das seguintes operações:

  - `F_SETLK` - A trava é definida ou removida. Se a trava estiver sendo mantida por outra pessoa, dio_fcntl() retorna -1.

  - `F_SETLKW` - semelhante a `F_SETLK`, mas caso a trava esteja sendo mantida por outra pessoa, dio_fcntl() aguarda até que a trava seja liberada.

  - `F_GETLK` - dio_fcntl() retorna um array associativo (conforme descrito abaixo) se alguém mais estiver impedindo a trava. Se não houver obstrução, a chave "type" será definida como `F_UNLCK`.

  - `F_DUPFD` - encontra o menor número de descritor de arquivo disponível maior ou igual a `args` e os retorna.

  - `F_SETFL` - Define as flags do descritor de arquivo para o valor especificado por `args`, que pode ser `O_APPEND`, `O_NONBLOCK` ou `O_ASYNC`. Para usar `O_ASYNC`, é necessário usar a extensão PCNTL.

`args`

  `args` é um array associativo, quando `cmd` é `F_SETLK` ou `F_SETLKW`, com as seguintes chaves:

  - `start` - posição onde a trava começa

  - `length` - tamanho da área travada. Zero significa até o final do arquivo

  - `whence` - Onde l_start é relativo a: pode ser `SEEK_SET`, `SEEK_END` e `SEEK_CUR`

  - `type` - tipo de trava: pode ser `F_RDLCK` (trava de leitura), `F_WRLCK` (trava de escrita) ou `F_UNLCK` (destrava)

### Valor Retornado

Retorna o resultado da chamada C.

### Exemplos

Exemplo #1 Definindo e removendo uma trava

    <?php

    $fd = dio_open('/dev/ttyS0', O_RDWR);

    if (dio_fcntl($fd, F_SETLK, Array("type"=>F_WRLCK)) == -1) {
       // o descritor de arquivo parece estar travado
       echo "A trava não pode ser removida. Está sendo usada por outra pessoa.";
    } else {
       echo "Trava definida/removida com sucesso.";
    }

    dio_close($fd);
    ?>

### Notas

> Nota: Esta função não foi implementada em plataformas Windows.

# dio_open

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_open — Abre um arquivo (criando-o, se necessário) em um nível mais baixo do que as funções de entrada/saída da biblioteca C permitem

### Descrição

function dio_open(string `$filename`, int `$flags`, int `$mode` = 0): resource

dio_open() abre um arquivo e retorna um novo descritor de arquivo para ele.

### Parâmetros

`filename`

  O caminho do arquivo a ser aberto.

`flags`

  O parâmetro `flags` é um valor resultante da operação OR bit a bit compreendendo flags da seguinte lista. Esse valor deve incluir um dos `O_RDONLY`, `O_WRONLY` ou `O_RDWR`. Adicionalmente, pode incluir qualquer combinação de outras flags desta lista.

  - `O_RDONLY` - abre o arquivo para acesso somente leitura.

  - `O_WRONLY` - abre o arquivo para escrita.

  - `O_RDWR` - abre o arquivo para leitura e escrita.

  - `O_CREAT` - cria o arquivo, se ele ainda não existe.

  - `O_EXCL` - se ambos `O_CREAT` e `O_EXCL` estiverem definidos e o arquivo já existir, dio_open() falhará.

  - `O_TRUNC` - se o arquivo existir e for aberto para acesso de escrita, o arquivo será truncado para o comprimento zero.

  - `O_APPEND` - operações de escrita gravam dados no final do arquivo.

  - `O_NONBLOCK` - define o modo não bloqueante.

  - `O_NOCTTY` - impede que o sistema operacional atribua o arquivo aberto como o terminal de controle do processo ao abrir um arquivo de dispositivo TTY.

`mode`

  Se `flags` contiver `O_CREAT`, `mode` definirá as permissões do arquivo (permissões de criação). `mode` é necessário para a operação correta quando `O_CREAT` é especificado em `flags` e é ignorado caso contrário.

  As permissões reais atribuídas ao arquivo criado serão afetadas pela configuração do umask do processo como de costume.

### Valor Retornado

Um descritor de arquivo ou `false` em caso de erro.

### Exemplos

Exemplo #1 Abrindo um descritor de arquivo

    <?php

    $fd = dio_open('/dev/ttyS0', O_RDWR | O_NOCTTY | O_NONBLOCK);

    dio_close($fd);
    ?>

### Veja Também

- dio_close() - Fecha o descritor de arquivo fornecido por fd

# dio_read

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_read — Lê bytes de um descritor de arquivo

### Descrição

function dio_read(resource `$fd`, int `$len` = 1024): string

A função dio_read() lê e retorna `len` bytes do arquivo com descritor `fd`.

### Parâmetros

`fd`

  O descritor de arquivo retornado por dio_open().

`len`

  O número de bytes a serem lidos. Se não especificado, dio_read() lê um bloco de tamanho 1K.

### Valor Retornado

Os bytes lidos de `fd`.

### Veja Também

- dio_write() - Escreve dados em fd com opção de truncamento no comprimento

# dio_seek

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_seek — Move para a posição pos no descritor de arquivo (fd) a partir de whence

### Descrição

function dio_seek(resource `$fd`, int `$pos`, int `$whence` = SEEK_SET): int

A função dio_seek() é usada para alterar a posição do arquivo associada ao descritor de arquivo fornecido.

### Parâmetros

`fd`

  O descritor de arquivo retornado por dio_open().

`pos`

  A nova posição.

`whence`

  Especifica como a posição `pos` deve ser interpretada:

  - `SEEK_SET` (padrão) - especifica que `pos` é especificado a partir do início do arquivo.

  - `SEEK_CUR` - Especifica que `pos` é um contador de caracteres a partir da posição atual do arquivo. Esse contador pode ser positivo ou negativo.

  - `SEEK_END` - Especifica que `pos` é um contador de caracteres a partir do final do arquivo. Um contador negativo especifica uma posição dentro da extensão atual do arquivo; um contador positivo especifica uma posição além do final atual. Se for definida a posição além do final atual e dados realmente forem gravados, o arquivo será preenchido com zeros até aquela posição.

### Valor Retornado

### Exemplos

Exemplo #1 Posicionamento em um arquivo

    <?php

    $fd = dio_open('/dev/ttyS0', O_RDWR);

    dio_seek($fd, 10, SEEK_SET);
    // a posição agora está em 10 caracteres a partir do início do arquivo

    dio_seek($fd, -2, SEEK_CUR);
    // a posição agora está em 8 caracteres a partir do início do arquivo

    dio_seek($fd, -5, SEEK_END);
    // a posição agora está em 5 caracteres do final do arquivo

    dio_seek($fd, 10, SEEK_END);
    // a posição agora está em 10 caracteres além do final do arquivo.
    // Os 10 caracteres entre o final do arquivo e a posição atual
    // são preenchidos com zeros.

    dio_close($fd);
    ?>

# dio_stat

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_stat — Obtém informações estatísticas sobre o descritor de arquivo fd

### Descrição

function dio_stat(resource `$fd`): array

dio_stat() retorna informações sobre o descritor de arquivo fornecido.

### Parâmetros

`fd`

  O descritor de arquivo retornado por dio_open().

### Valor Retornado

Retorna um array associativo com as seguintes chaves:

- "device" - dispositivo

- "inode" - inode

- "mode" - modo

- "nlink" - número de links físicos

- "uid" - id do usuário

- "gid" - id do grupo

- "device_type" - tipo de dispositivo (se inode for um dispositivo)

- "size" - tamanho total em bytes

- "blocksize" - tamanho do bloco

- "blocks" - número de blocos alocados

- "atime" - hora do último acesso

- "mtime" - hora da última modificação

- "ctime" - hora da última alteração

Em caso de erro dio_stat() retorna `null`.

# dio_tcsetattr

(PHP 4 >= 4.3.0, PHP 5 < 5.1.0)

dio_tcsetattr — Define os atributos do terminal e a taxa de transmissão para uma porta serial

### Descrição

function dio_tcsetattr(resource `$fd`, array `$options`): bool

dio_tcsetattr() define os atributos do terminal e a taxa de transmissão do `fd` aberto.

### Parâmetros

`fd`

  O descritor de arquivo retornado por dio_open().

`options`

  As opções atualmente disponíveis são:

  - 'baud' - taxa de transmissão da porta - pode ser 38400, 19200, 9600, 4800, 2400, 1800, 1200, 600, 300, 200, 150, 134, 110, 75 ou 50. O valor padrão é 9600.

  - 'bits' - bits de dados - pode ser 8, 7, 6 ou 5. O valor padrão é 8.

  - 'stop' - bits de parada - pode ser 1 ou 2. O valor padrão é 1.

  - 'parity' - pode ser 0, 1 ou 2. O valor padrão é 0.

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Configurando a taxa de transmissão em uma porta serial

    <?php

    $fd = dio_open('/dev/ttyS0', O_RDWR | O_NOCTTY | O_NONBLOCK);

    dio_fcntl($fd, F_SETFL, O_SYNC);

    dio_tcsetattr($fd, array(
        'baud' => 9600,
        'bits' => 8,
        'stop'  => 1,
        'parity' => 0
    ));

    while (true) {
        $data = dio_read($fd, 256);
        if ($data !== null && $data !== '') {
            echo $data;
        }
    }

    ?>

### Notas

> Nota: Esta função não foi implementada em plataformas Windows.

# dio_truncate

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_truncate — Trunca o descritor de arquivo fd para o deslocamento em bytes

### Descrição

function dio_truncate(resource `$fd`, int `$offset`): bool

dio_truncate() trunca um arquivo para no máximo `offset` bytes de tamanho.

Se o arquivo era anteriormente maior do que esse tamanho, os dados extras são perdidos. Se o arquivo era anteriormente menor, não é especificado se o arquivo permanece inalterado ou é estendido. No último caso, a parte estendida é preenchida com bytes zero.

### Parâmetros

`fd`

  O descritor de arquivo retornado por dio_open().

`offset`

  O deslocamento (offset) em bytes

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Notas

> Nota: Esta função não foi implementada em plataformas Windows.

# dio_write

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_write — Escreve dados em fd com opção de truncamento no comprimento

### Descrição

function dio_write(resource `$fd`, string `$data`, int `$len` = 0): int

A função dio_write() escreve até `len` bytes de `data` para o arquivo `fd`.

### Parâmetros

`fd`

  O descritor de arquivo retornado por dio_open().

`data`

  Os dados a serem escritos.

`len`

  O comprimento dos dados a serem escritos em bytes. Se não especificado, a função escreve todos os dados no arquivo especificado.

### Valor Retornado

Retorna o número de bytes escritos em `fd`.

### Veja Também

- dio_read() - Lê bytes de um descritor de arquivo

## Índice

- dio_close — Fecha o descritor de arquivo fornecido por fd
- dio_fcntl — Realiza uma chamada à função fcntl da biblioteca C no descritor de arquivo
- dio_open — Abre um arquivo (criando-o, se necessário) em um nível mais baixo do que as funções de entrada/saída da biblioteca C permitem
- dio_read — Lê bytes de um descritor de arquivo
- dio_seek — Move para a posição pos no descritor de arquivo (fd) a partir de whence
- dio_stat — Obtém informações estatísticas sobre o descritor de arquivo fd
- dio_tcsetattr — Define os atributos do terminal e a taxa de transmissão para uma porta serial
- dio_truncate — Trunca o descritor de arquivo fd para o deslocamento em bytes
- dio_write — Escreve dados em fd com opção de truncamento no comprimento

- Instalação/Configuração
  - Instalação
  - Tipos de Recurso
- Constantes predefinidas
- Funções de E/S Direta
  - dio_close — Fecha o descritor de arquivo fornecido por fd
  - dio_fcntl — Realiza uma chamada à função fcntl da biblioteca C no descritor de arquivo
  - dio_open — Abre um arquivo (criando-o, se necessário) em um nível mais baixo do que as funções de entrada/saída da biblioteca C permitem
  - dio_read — Lê bytes de um descritor de arquivo
  - dio_seek — Move para a posição pos no descritor de arquivo (fd) a partir de whence
  - dio_stat — Obtém informações estatísticas sobre o descritor de arquivo fd
  - dio_tcsetattr — Define os atributos do terminal e a taxa de transmissão para uma porta serial
  - dio_truncate — Trunca o descritor de arquivo fd para o deslocamento em bytes
  - dio_write — Escreve dados em fd com opção de truncamento no comprimento

# Diretórios

# Constantes predefinidas

`DIRECTORY_SEPARATOR` (string)
`PATH_SEPARATOR` (string)
  Ponto-e-vírgula no Windows, dois-pontos nos demais.
`SCANDIR_SORT_ASCENDING` (int)
`SCANDIR_SORT_DESCENDING` (int)
`SCANDIR_SORT_NONE` (int)

# A classe Directory

(PHP 4, PHP 5, PHP 7, PHP 8)

## Introdução

Instâncias de Directory são criadas chamando-se a função dir(), e não através do operador new.

## Resumo da classe

final class Directory {
/* Propriedades */
public readonly string $path;
public readonly resource $handle;
/* Métodos */
public function close(): void
public function read(): string|false
public function rewind(): void
}

## Propriedades

path

  O diretórioque foi aberto.

handle

  Pode ser usada com outras funções de diretório como readdir(), rewinddir() e closedir().

## Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | A class agora é final.
8.1.0 | As propriedades path e handle agora são somente-leitura.

# Directory::close

(PHP 4, PHP 5, PHP 7, PHP 8)

Directory::close — Fecha o manipulador de diretório

### Descrição

public function Directory::close(): void

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Nenhum parâmetro é aceito. Anteriormente, um manipulador de diretório poderia ser passado como argumento.

# Directory::read

(PHP 4, PHP 5, PHP 7, PHP 8)

Directory::read — Lê entrada de um manipulador de diretório

### Descrição

public function Directory::read(): string|false

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Nenhum parâmetro é aceito. Anteriormente, um manipulador de diretório poderia ser passado como argumento.

# Directory::rewind

(PHP 4, PHP 5, PHP 7, PHP 8)

Directory::rewind — Retrocede um manipulador de diretório

### Descrição

public function Directory::rewind(): void

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Nenhum parâmetro é aceito. Anteriormente, um manipulador de diretório poderia ser passado como argumento.

## Índice

- Directory::close — Fecha o manipulador de diretório
- Directory::read — Lê entrada de um manipulador de diretório
- Directory::rewind — Retrocede um manipulador de diretório

# Funções de Diretórios

# Veja Também

Para funções relacionadas como dirname(), is_dir(), mkdir() e rmdir(), consulte a seção Filesystem.

# chdir

(PHP 4, PHP 5, PHP 7, PHP 8)

chdir — Muda o diretório

### Descrição

function chdir(string `$directory`): bool

Muda o diretório atual do PHP para `directory`.

### Parâmetros

`directory`

  O novo diretório atual

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Dispara um aviso `E_WARNING` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de chdir()

    <?php

    // diretório atual
    echo getcwd() . "\n";

    chdir('public_html');

    // diretório atual
    echo getcwd() . "\n";

    ?>

O exemplo acima produzirá algo semelhante a:

    /home/vincent
    /home/vincent/public_html

### Notas

Cuidado

Se o interpretador PHP foi compilado com ZTS (Zend Thread Safety) habilitado, quaisquer mudanças ao diretório atual através de chdir() serão invisíveis ao sistema operacional. Todas as funções internas do PHP ainda irão respeitar a mudança do diretório atual; mas funções de bibliotecas externas, chamadas usando FFI não irão. Pode-se verificar se a cópia do PHP foi compilada com ZTS habilitado usando o comando php -i ou a constante interna `PHP_ZTS`.

### Veja Também

- getcwd() - Obtém o diretório atual

# chroot

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

chroot — Muda o diretório raiz

### Descrição

function chroot(string `$directory`): bool

Muda o diretório raiz do processo atual para `directory`, e muda o diretório de trabalho atual para "/".

Esta função está disponível somente para sistemas GNU e BSD, e apenas quando CLI, CGI ou Embed SAPI estiverem sendo usados. Além disso, esta função requer privilégio de administrador.

Chamar esta função não muda os valores das constantes mágicas `__DIR__` e `__FILE__`.

### Parâmetros

`directory`

  O caminho para o qual apontar o novo diretório raiz.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de chroot()

    <?php
    chroot("/caminho/para/seu/chroot/");
    echo getcwd();
    ?>

O exemplo acima produzirá:

    /

### Notas

> Nota: Esta função não foi implementada em plataformas Windows.

> Nota: Esta função não está disponível em interpretadores PHP compilados com o recurso ZTS (Zend Thread Safety) habilitado. Para verificar se sua cópia do PHP foi compilada com o ZTS habilitado, use o comando php -i ou teste a constante `PHP_ZTS`.

# closedir

(PHP 4, PHP 5, PHP 7, PHP 8)

closedir — Fecha o manipulador do diretório

### Descrição

function closedir(?resource `$dir_handle` = `null`): void

Fecha o fluxo de diretório indicado por `dir_handle`.

### Parâmetros

`dir_handle`
  O manipulador de diretório do tipo resource aberto previamente com opendir(). Se `dir_handle` for `null`, o último manipulador aberto por opendir() será usado.

### Valor Retornado

Nenhum valor é retornado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | Usar `null` para `dir_handle` foi descontinuado. Em vez disso, o manipulador do último diretório aberto deve ser fornecido explicitamente.
8.0.0 | `dir_handle` agora pode ser nulo.

### Exemplos

Para um exemplo completo, consulte a documentação de opendir().

### Veja Também

- opendir() - Abre um manipulador de diretório
- readdir() - Lê entrada do manipulador do diretório
- rewinddir() - Retroceder o manipulador de diretório
- dir() - Retorna uma instância da classe Directory
- is_dir() - Diz se o caminho é um diretório
- glob() - Encontra caminhos que combinam com uma expressão
- scandir() - Lista arquivos e diretórios dentro do caminho especificado

# dir

(PHP 4, PHP 5, PHP 7, PHP 8)

dir — Retorna uma instância da classe Directory

### Descrição

function dir(string `$directory`, ?resource `$context` = `null`): Directory|false

Um mecanismo pseudo-orientado a objeto para ler um diretório. O diretório fornecido pelo parâmetro `directory` é aberto.

### Parâmetros

`directory`

  Diretório a ser aberto

`context`
  Um resource de contexto de fluxo.

### Valor Retornado

Retorna uma instância de Directory, ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `context` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo da dir()

Repare nos detalhes de como o valor retornado de Directory::read() é verificado no exemplo abaixo. É testado explicitamente se o valor de retorno é idêntico a (igual e do mesmo tipo que - consulte operadores de comparação para mais informação) `false`, caso contrário, qualquer entrada de diretório cujo nome seja interpretado como `false` fará parar o loop.

    <?php
    $d = dir("/etc/php5");
    echo "Handle: " . $d->handle . "\n";
    echo "Caminho: " . $d->path . "\n";
    while (false !== ($entry = $d->read())) {
       echo $entry."\n";
    }
    $d->close();
    ?>

O exemplo acima produzirá algo semelhante a:

    Handle: Resource id #2
    Caminho: /etc/php5
    .
    ..
    apache
    cgi
    cli

### Notas

> Nota:

> A ordem em que as entradas do diretório são retornadas pelo método de leitura é dependente do sistema operacional.

# getcwd

(PHP 4, PHP 5, PHP 7, PHP 8)

getcwd — Obtém o diretório atual

### Descrição

function getcwd(): string|false

Obtém o diretório atual.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o diretório atual em caso de sucesso ou `false` em caso de falha.

Em algunmas variantes Unix, getcwd() irá retornar `false` se qualquer um dos diretórios-pai não tiver o modo leitura ou pesquisa definidos, mesmo se diretório atual tiver. Consulte chmod() para mais informação sobre modos e permissões.

### Exemplos

Exemplo #1 Exemplo de getcwd()

    <?php

    // diretório atual
    echo getcwd() . "\n";

    chdir('cvs');

    // diretório atual
    echo getcwd() . "\n";

    ?>

O exemplo acima produzirá algo semelhante a:

    /home/didou
    /home/didou/cvs

### Notas

Cuidado

Se o interpretador PHP foi compilado com ZTS (Zend Thread Safety) habilitado, o diretório de trabalho atual retornado por getcwd() pode ser diferente do retornado pelas interfaces do sistema operacional. Bibliotecas externas (chamadas usando FFI) que dependem do diretório de trabalho atual serão afetadas.

### Veja Também

- chdir() - Muda o diretório
- chmod() - Modifica as permissões do arquivo

# opendir

(PHP 4, PHP 5, PHP 7, PHP 8)

opendir — Abre um manipulador de diretório

### Descrição

function opendir(string `$directory`, ?resource `$context` = `null`): resource|false

Abre um manipulador de diretório para ser usado em chamadas subsequentes de closedir(), readdir() e rewinddir().

### Parâmetros

`directory`
  O caminho do diretório a ser aberto.
`context`
  Para descrição do parâmetro `context`, consulte a seção sobre fluxos do manual.

### Valor Retornado

Retorna um manipulador de diretório em caso de sucesso, ou `false` em caso de falha

### Erros/Exceções

Em caso de falha, um `E_WARNING` será emitido.

Isto pode ocorrer se `directory` não for um nome de diretório válido, o diretório não puder ser aberto por restrições de permissão, ou por erros no sistema de arquivos.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `context` agora pode ser nulo.

### Exemplos

Exemplo #1 Lista todas as entradas de um diretório, pulando os especiais `.` e `..`

Como os nomes de diretório e arquivo podem ser strings interpretadas como "falso" pelo PHP (por exemplo um diretório com nome `"0"`) e readdir() retorna `false` quando tiver lido todas as entradas em um diretório, deve-se usar o operador de comparação `===` para distinguir adequadamente entre uma entrada de diretório cujo nome seja interpretado como "falso" e a função ter terminado de ler todas as entradas.

    <?php

    if ($handle = opendir('/path/to/files')) {
        echo "Entradas:\n";

        /* Lidando corretamente com entradas de diretório que podem ser interpretadas como "falso" */
        while (false !== ($entry = readdir($handle))) {
            if ($entry === '.' || $entry === '..') {
                continue;
            }
            echo "$entry\n";
        }

        closedir($handle);
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Entradas:
    base
    en
    fr
    output.md
    test.php

### Veja Também

- readdir() - Lê entrada do manipulador do diretório
- rewinddir() - Retroceder o manipulador de diretório
- closedir() - Fecha o manipulador do diretório
- dir() - Retorna uma instância da classe Directory
- is_dir() - Diz se o caminho é um diretório
- glob() - Encontra caminhos que combinam com uma expressão
- scandir() - Lista arquivos e diretórios dentro do caminho especificado

# readdir

(PHP 4, PHP 5, PHP 7, PHP 8)

readdir — Lê entrada do manipulador do diretório

### Descrição

function readdir(?resource `$dir_handle` = `null`): string|false

Retorna o nome da próxima entrada do diretório. As entradas são retornadas na ordem em que estão armazenadas no sistema de arquivos.

### Parâmetros

`dir_handle`
  O manipulador de diretório do tipo resource previamente aberto por opendir(). Se `dir_handle` for `null`, o último manipulador aberto por opendir() será usado.

### Valor Retornado

Retorna o nome do arquivo em caso de sucesso, ou `false` em caso de falha.

Aviso

Esta função pode retornar o valor booleano `false`, mas também pode retornar um valor não booleano que pode ser avaliado como `false`. Leia a seção sobre Booleanos para mais informações. Use o operador === para testar o valor retornado por esta função.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | Usar `null` para `dir_handle` foi descontinuado. Em vez disso, o manipulador do último diretório aberto deve ser fornecido explicitamente.
8.0.0 | `dir_handle` agora pode ser nulo.

### Exemplos

Para um exemplo completo, consulte a documentação de opendir().

### Veja Também

- opendir() - Abre um manipulador de diretório
- rewinddir() - Retroceder o manipulador de diretório
- closedir() - Fecha o manipulador do diretório
- dir() - Retorna uma instância da classe Directory
- is_dir() - Diz se o caminho é um diretório
- glob() - Encontra caminhos que combinam com uma expressão
- scandir() - Lista arquivos e diretórios dentro do caminho especificado

# rewinddir

(PHP 4, PHP 5, PHP 7, PHP 8)

rewinddir — Retroceder o manipulador de diretório

### Descrição

function rewinddir(?resource `$dir_handle` = `null`): void

Reinicia o fluxo do diretório indicado por `dir_handle` para o início do diretório.

### Parâmetros

`dir_handle`
  O manipulador de diretório do tipo resource previamente aberto por opendir(). Se `dir_handle` for `null`, o último manipulador aberto por opendir() será usado.

### Valor Retornado

Nenhum valor é retornado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | Usar `null` para `dir_handle` foi descontinuado. Em vez disso, o manipulador do último diretório aberto deve ser fornecido explicitamente.
8.0.0 | `dir_handle` agora pode ser nulo.

### Exemplos

Para um exemplo completo, consulte a documentação de opendir().

### Veja Também

- opendir() - Abre um manipulador de diretório
- readdir() - Lê entrada do manipulador do diretório
- closedir() - Fecha o manipulador do diretório
- dir() - Retorna uma instância da classe Directory
- is_dir() - Diz se o caminho é um diretório
- glob() - Encontra caminhos que combinam com uma expressão
- scandir() - Lista arquivos e diretórios dentro do caminho especificado

# scandir

(PHP 5, PHP 7, PHP 8)

scandir — Lista arquivos e diretórios dentro do caminho especificado

### Descrição

function scandir(string `$directory`, int `$sorting_order` = `SCANDIR_SORT_ASCENDING`, ?resource `$context` = `null`): array|false

Retorna um array de arquivos e diretórios dentro de `directory`.

### Parâmetros

`directory`

  O diretório que será pesquisado.

`sorting_order`

  Por padrão, a lista está em ordem alfabética crescente. Se o parâmetro opcional `sorting_order` for definido para `SCANDIR_SORT_DESCENDING`, a ordenação será alfabética decrescente. Se definida para `SCANDIR_SORT_NONE`, o resultado não será ordenado.

`context`

  Para uma descrição do parâmetro `context` refira-se à seção de fluxos do manual.

### Valor Retornado

Retorna um array com nomes de arquivos em caso de sucesso, ou `false` em caso de falha. Se `directory` não for um diretório, `false` é retornado e um aviso `E_WARNING` é gerado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `context` agora pode ser nulo.

### Exemplos

Exemplo #1 Um exemplo simples de scandir()

    <?php
    $dir    = '/tmp';
    $files1 = scandir($dir);
    $files2 = scandir($dir, 1);

    print_r($files1);
    print_r($files2);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => .
        [1] => ..
        [2] => bar.php
        [3] => foo.txt
        [4] => algumdiretorio
    )
    Array
    (
        [0] => algumdiretorio
        [1] => foo.txt
        [2] => bar.php
        [3] => ..
        [4] => .
    )

### Notas

Dica

Uma URL pode ser usada como um nome de arquivo com esta função se os empacotadores fopen estiverem habilitados. Consulte a função fopen() para mais detalhes sobre como especificar o nome do arquivo. Consulte os Protocolos e empacotadores suportados para obter links para informações sobre as capacidades de cada empacotador, notas de uso e informações sobre quaisquer variáveis predefinidas que eles possam fornecer.

### Veja Também

- opendir() - Abre um manipulador de diretório
- readdir() - Lê entrada do manipulador do diretório
- glob() - Encontra caminhos que combinam com uma expressão
- is_dir() - Diz se o caminho é um diretório
- sort() - Ordena um array em ordem ascendente

## Índice

- chdir — Muda o diretório
- chroot — Muda o diretório raiz
- closedir — Fecha o manipulador do diretório
- dir — Retorna uma instância da classe Directory
- getcwd — Obtém o diretório atual
- opendir — Abre um manipulador de diretório
- readdir — Lê entrada do manipulador do diretório
- rewinddir — Retroceder o manipulador de diretório
- scandir — Lista arquivos e diretórios dentro do caminho especificado

- Constantes predefinidas
- Directory — A classe Directory
  - Directory::close — Fecha o manipulador de diretório
  - Directory::read — Lê entrada de um manipulador de diretório
  - Directory::rewind — Retrocede um manipulador de diretório
- Funções de Diretórios
  - chdir — Muda o diretório
  - chroot — Muda o diretório raiz
  - closedir — Fecha o manipulador do diretório
  - dir — Retorna uma instância da classe Directory
  - getcwd — Obtém o diretório atual
  - opendir — Abre um manipulador de diretório
  - readdir — Lê entrada do manipulador do diretório
  - rewinddir — Retroceder o manipulador de diretório
  - scandir — Lista arquivos e diretórios dentro do caminho especificado

# Informações do arquivo

# Introdução

As funções nesta extensão tentam adivinhar o tipo de conteúdo e a codificação de um arquivo procurando por algumas sequências mágicas de bytes em posições específicas no arquivo. Embora esta não seja uma abordagem à prova de balas, a heurística usada faz um excelente trabalho.

# Instalação/Configuração

## Índice

- Instalação
- Tipos de Recurso

## Instalação

Esta extensão está habilitada por padrão.

Usuários do Windows devem incluir a DLL fornecida php_fileinfo.dll no php.ini para habilitar esta extensão.

A biblioteca libmagic é fornecida com o PHP, mas inclui alterações específicas do PHP. Uma alteração para libmagic chamada libmagic.patch é mantido e pode ser encontrada no diretório de arquivos fontes da extensão fileinfo.

## Tipos de Recurso

Antes do PHP 8.1.0, um recurso era usado na extensão Fileinfo: um descritor de banco de dados mágico retornado por finfo_open().

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`FILEINFO_NONE` (int)
  Nenhum tratamento especial.
`FILEINFO_SYMLINK` (int)
  Segue links simbólicos.
`FILEINFO_MIME_TYPE` (int)
  Retorna o tipo MIME.
`FILEINFO_MIME_ENCODING` (int)
  Retorna a codificação MIME do arquivo.
`FILEINFO_MIME` (int)
  Retorna o tipo e a codificação MIME conforme definido pela RFC 2045.
`FILEINFO_COMPRESS` (int)
  Descompacta arquivos compactados. Desabilitada devido a problemas com thread safety.
`FILEINFO_DEVICES` (int)
  Verifica o conteúdo dos dispositivos especiais de blocos ou caracteres.
`FILEINFO_CONTINUE` (int)
  Retorne todas as correspondências, não apenas a primeira.
`FILEINFO_PRESERVE_ATIME` (int)
  Se possível, preserva o tempo de acesso original.
`FILEINFO_RAW` (int)
  Não traduz caracteres não imprimíveis para uma representação octal `\ooo`.
`FILEINFO_EXTENSION` (int)
  Retorna a extensão de arquivo apropriada para o tipo MIME detectado no arquivo. Para tipos que normalmente possuem múltiplas extensões de arquivo, como imagens `JPEG`, o valor retornado é composto por múltiplas extensões separadas por uma barra, por exemplo: `"jpeg/jpg/jpe/jfif"`. Para tipos desconhecidos indisponíveis no banco de dados magic.mime, o valor de retorno é `"???"`. Disponível desde o PHP 7.2.0.
`FILEINFO_APPLE` (int)
  Retorna o autor e o tipo Apple.

# Funções da Fileinfo

# finfo_buffer

# finfo::buffer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_buffer -- finfo::buffer — Retorna informações sobre um buffer de string

### Descrição

Estilo procedural

function finfo_buffer(
finfo `$finfo`,
string `$string`,
int `$flags` = `FILEINFO_NONE`,
?resource `$context` = `null`
): string|false

Estilo orientado a objetos

public function finfo::buffer(string `$string`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false

Esta função é usada para obter informações sobre dados binários em uma string.

### Parâmetros

`finfo`
  Uma instância de finfo, retornada por finfo_open().
`string`
  Conteúdo do arquivo a ser verificado.
`flags`
  Uma ou disjunção de mais constantes Fileinfo.
`context`

### Valor Retornado

Retorna uma descrição textual do parâmetro `string`, ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | O parâmetro `context` foi descontinuado e é ignorado.
8.1.0 | O parâmetro `finfo` agora espera uma instância de finfo; anteriormente, um resource era esperado.
8.0.0 | O parâmetro `context` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo de finfo_buffer()

    <?php
    $finfo = new finfo(FILEINFO_MIME);
    echo $finfo->buffer($_POST["script"]) . "\n";
    ?>

O exemplo acima produzirá algo semelhante a:

    application/x-sh; charset=us-ascii

### Veja Também

- finfo_file() - Retorna informações sobre um arquivo

# finfo_close

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_close — Fecha uma instância de finfo

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.5.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
function finfo_close(finfo `$finfo`): true

O objetivo desta função era fechar a instância aberta por finfo_open() até o PHP 7.4, mas é uma função inoperante desde a conversão de recurso para objeto finfo implementada no PHP 8.0, e foi descontinuada no PHP 8.5.

### Parâmetros

`finfo`
  Uma instância de finfo, retornada por finfo_open().

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | Esta função foi descontinuada.
8.5.0 | Agora o tipo de retorno é `true`; antes era bool.
8.1.0 | Esta função agora é um NOP.
8.1.0 | O parâmetro `finfo` agora espera uma instância de finfo; anteriormente, um resource era esperado.

# finfo_file

# finfo::file

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_file -- finfo::file — Retorna informações sobre um arquivo

### Descrição

Estilo procedural

function finfo_file(
finfo `$finfo`,
string `$filename`,
int `$flags` = `FILEINFO_NONE`,
?resource `$context` = `null`
): string|false

Estilo orientado a objetos

public function finfo::file(string `$filename`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false

Esta função é usada para obter informações sobre um arquivo.

### Parâmetros

`finfo`
  Uma instância de finfo, retornada por finfo_open().
`filename`
  Nome do arquivo a ser verificado.
`flags`
  Uma ou disjunção de mais constantes Fileinfo.
`context`
  Para uma descrição de `contexts`, consulte Funções de Fluxo.

### Valor Retornado

Retorna uma descrição textual do conteúdo do argumento `filename` ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `finfo` agora espera uma instância de finfo; anteriormente, um resource era esperado.
8.0.0 | O parâmetro `context` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo de finfo_file()

    <?php
    $finfo = finfo_open(FILEINFO_MIME_TYPE); // retorna o tipo MIME, também conhecido como extensão mimetype
    foreach (glob("*") as $nome_do_arquivo) {
        echo finfo_file($finfo, $nome_do_arquivo) . "\n";
    }
    finfo_close($finfo);
    ?>

O exemplo acima produzirá algo semelhante a:

    text/html
    image/gif
    application/vnd.ms-excel

### Veja Também

- finfo_buffer() - Retorna informações sobre um buffer de string

# finfo_open

# finfo::__construct

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_open -- finfo::__construct — Cria uma instância de finfo

### Descrição

Estilo procedural

function finfo_open(int `$flags` = `FILEINFO_NONE`, ?string `$magic_database` = `null`): finfo|false

Estilo orientado a objetos (construtor):

public function finfo::__construct(int `$flags` = `FILEINFO_NONE`, ?string `$magic_database` = `null`)

Esta função abre um banco de dados mágico e retorna a instância.

### Parâmetros

`flags`
  Uma ou disjunção de mais constantes Fileinfo.
`magic_database`
  Nome de um arquivo de banco de dados mágico, geralmente algo como /caminho/para/magic.mime. Se não for especificado, a variável de ambiente `MAGIC` será usada. O banco de dados mágico incluído no PHP será usado se a variável de ambiente não estiver definida. Passar `null` ou uma string vazia será equivalente ao valor padrão.

### Valor Retornado

(Apenas no estilo procedural) Retorna uma instância de finfo em caso de sucesso, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Agora retorna uma instância de finfo; anteriormente, um resource era retornado.
8.0.3 | O parâmetro `magic_database` agora pode ser nulo.

### Exemplos

Exemplo #1 Estilo orientado a objetos

    <?php
    $finfo = new finfo(FILEINFO_MIME, "/usr/share/misc/magic"); // retorna o tipo MIME, também conhecido como extensão mimetype

    /* Obtém o tipo MIME de arquivo específico */
    $nome_do_arquivo = "/usr/local/alguma_coisa.txt";
    echo $finfo->file($nome_do_arquivo);

    ?>

Exemplo #2 Estilo procedural

    <?php
    $finfo = finfo_open(FILEINFO_MIME, "/usr/share/misc/magic"); // retorna o tipo MIME, também conhecido como extensão mimetype

    if (!$finfo) {
        echo "Falha ao abrir banco de dados fileinfo";
        exit();
    }

    /* Obtém o tipo MIME de arquivo específico */
    $nome_do_arquivo = "/usr/local/alguma_coisa.txt";
    echo finfo_file($finfo, $nome_do_arquivo);

    /* fecha a conexão */
    finfo_close($finfo);
    ?>

O exemplo acima produzirá:

    text/plain; charset=us-ascii

### Notas

> Nota: Geralmente, usar o banco de dados mágico incluído no PHP (deixando o parâmetro `magic_database` e as variáveis de ambiente `MAGIC` indefinidos) é o melhor caminho a seguir, a menos que um banco de dados mágico personalizado seja necessário.

### Veja Também

- finfo_close() - Fecha uma instância de finfo

# finfo_set_flags

# finfo::set_flags

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_set_flags -- finfo::set_flags — Define as opções de configuração da libmagic

### Descrição

Estilo procedural

function finfo_set_flags(finfo `$finfo`, int `$flags`): true

Estilo orientado a objetos

public function finfo::set_flags(int `$flags`): true

Esta função define várias opções de Fileinfo. As opções também podem ser definidas diretamente em finfo_open() ou em outras funções da Fileinfo.

### Parâmetros

`finfo`
  Uma instância de finfo, retornada por finfo_open().
`flags`
  Uma ou disjunção de mais constantes Fileinfo.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `finfo` agora espera uma instância de finfo; anteriormente, um resource era esperado.

# mime_content_type

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mime_content_type — Detecta o tipo de conteúdo MIME de um arquivo

### Descrição

function mime_content_type(resource|string `$filename`): string|false

Retorna o tipo de conteúdo MIME de um arquivo conforme determinado usando informações do arquivo magic.mime.

### Parâmetros

`filename`
  Caminho para o arquivo.

### Valor Retornado

Retorna o tipo de conteúdo no formato MIME, como `text/plain` ou `application/octet-stream`, ou `false` em caso de falha.

### Erros/Exceções

Em caso de falha, um `E_WARNING` será emitido.

### Exemplos

Exemplo #1 Exemplo de mime_content_type()

    <?php
    echo mime_content_type('php.gif') . "\n";
    echo mime_content_type('teste.php');
    ?>

O exemplo acima produzirá:

    image/gif
    text/plain

### Veja Também

- finfo_file() - Retorna informações sobre um arquivo
- finfo_buffer() - Retorna informações sobre um buffer de string

## Índice

- finfo_buffer — Retorna informações sobre um buffer de string
- finfo_close — Fecha uma instância de finfo
- finfo_file — Retorna informações sobre um arquivo
- finfo_open — Cria uma instância de finfo
- finfo_set_flags — Define as opções de configuração da libmagic
- mime_content_type — Detecta o tipo de conteúdo MIME de um arquivo

# A classe finfo

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

## Introdução

Esta classe fornece uma interface orientada a objetos para as funções fileinfo.

## Resumo da classe

class finfo {
/* Métodos */
public function __construct(int `$flags` = `FILEINFO_NONE`, ?string `$magic_database` = `null`)
public function buffer(string `$string`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false
public function file(string `$filename`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false
public function set_flags(int `$flags`): true
}

# finfo::buffer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::buffer — Sinônimo de finfo_buffer()

### Descrição

public function finfo::buffer(string `$string`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false

Esta função é um apelido para: finfo_buffer()

# finfo::__construct

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::__construct — Sinônimo de finfo_open()

### Descrição

public function finfo::__construct(int `$flags` = `FILEINFO_NONE`, ?string `$magic_database` = `null`)

Esta função é um apelido para: finfo_open()

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.3 | O parâmetro `magic_database` agora pode ser nulo.

# finfo::file

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::file — Sinônimo de finfo_file()

### Descrição

public function finfo::file(string `$filename`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false

Esta função é um apelido para: finfo_file()

# finfo::set_flags

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::set_flags — Sinônimo de finfo_set_flags()

### Descrição

public function finfo::set_flags(int `$flags`): true

Esta função é um apelido para: finfo_set_flags()

## Índice

- finfo::buffer — Sinônimo de finfo_buffer()
- finfo::__construct — Sinônimo de finfo_open
- finfo::file — Sinônimo de finfo_file()
- finfo::set_flags — Sinônimo de finfo_set_flags()

- Instalação/Configuração
  - Instalação
  - Tipos de Recurso
- Constantes predefinidas
- Funções da Fileinfo
  - finfo_buffer — Retorna informações sobre um buffer de string
  - finfo_close — Fecha uma instância de finfo
  - finfo_file — Retorna informações sobre um arquivo
  - finfo_open — Cria uma instância de finfo
  - finfo_set_flags — Define as opções de configuração da libmagic
  - mime_content_type — Detecta o tipo de conteúdo MIME de um arquivo
- finfo — A classe finfo
  - finfo::buffer — Sinônimo de finfo_buffer()
  - finfo::__construct — Sinônimo de finfo_open
  - finfo::file — Sinônimo de finfo_file()
  - finfo::set_flags — Sinônimo de finfo_set_flags()

# Extensão Filesystem (Sistema de Arquivos)

# Introdução

Nenhuma bilbioteca externa é necessária para compilar esta extensão, porém se for desejado que o PHP suporte LFS (grandes arquivos) no Linux, será necessária uma biblioteca glibc recente e o PHP precisa ser compilado com as seguintes opções: `-D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64`.

# Instalação/Configuração

## Índice

- Configurações em Execução
- Tipos de Recurso

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de configuração do Sistema de Arquivos e de Fluxos
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
allow_url_fopen | "1" | `INI_SYSTEM` |
allow_url_include | "0" | `INI_SYSTEM` | Descontinuada a partir do PHP 7.4.0.
user_agent | NULL | `INI_ALL` |
default_socket_timeout | "60" | `INI_ALL` |
from | "" | `INI_ALL` |
auto_detect_line_endings | "0" | `INI_ALL` | Descontinuada a partir do PHP 8.1.0.
sys_temp_dir | "" | `INI_SYSTEM` |

Aqui está uma breve explicação das diretivas de configuração.

`allow_url_fopen` bool

  Esta opção habilita os empacotadores fopen sensíveis a URL que permitem acessar objetos URL como se fossem arquivos. Empacotadores padrão são fornecidos para o acesso a arquivos remotos usando o protocolo ftp ou http, e algumas extensões como zlib podem registrar empacotadores adicionais.

`allow_url_include` bool

  Esta opção permite o uso de empacotadores fopen sensíveis a URL com as seguintes funções: include, include_once, require e require_once.

  > Nota:

  > Esta configuração requer que a opção allow_url_fopen esteja habilitada.

`user_agent` string

  Define o agente do usuário que o PHP irá enviar.

`default_socket_timeout` int

  Limite padrão de tempo (em segundos) para fluxos baseados em soquete. Especificar um valor negativo significa um limite de tempo infinito.

`from` string

  O endereço de e-mail que será usado em conexões FTP não autenticadas e como o valor do cabeçalho From em conexões HTTP, ao usar os empacotadores ftp e http, respectivamente.

`auto_detect_line_endings` bool

  Quando habilitada, o PHP examinará os dados lidos por fgets() e file() para verificar se está usando a convenção de fim de linha do Unix, MS-DOS ou Macintosh.

  Isso permite que o PHP interopere com sistemas Macintosh, mas o padrão é Off (desligado), pois há uma penalidade de desempenho muito pequena ao detectar as convenções de fim de linha para a primeira linha, e também porque as pessoas que usam retornos de carro como separadores de itens nos sistemas Unix podem experimentar problemas de incompatibilidade com versões anteriores.

`sys_temp_dir` string

## Tipos de Recurso

O sistema de arquivos usa fluxos (`streams`) como seu tipo de recurso. Fluxos estão documentados em seu próprio capítulo de referência, Fluxos.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`SEEK_SET` (int)
`SEEK_CUR` (int)
`SEEK_END` (int)
`LOCK_SH` (int)
`LOCK_EX` (int)
`LOCK_UN` (int)
`LOCK_NB` (int)

Valores para o parâmetro `flags` da função file()
`FILE_USE_INCLUDE_PATH` (int)
  Procura por `filename` no include_path.
`FILE_NO_DEFAULT_CONTEXT` (int)
`FILE_APPEND` (int)
  Adiciona conteúdo ao arquivo existente.
`FILE_IGNORE_NEW_LINES` (int)
  Remove caracteres de fim de linha.
`FILE_SKIP_EMPTY_LINES` (int)
  Pula linhas em branco.
`FILE_BINARY` (int)

  Modo binário.

  Aviso

  Esta constante não tem efeito e foi descontinuada a partir do PHP 8.1.0.

`FILE_TEXT` (int)

  Modo texto.

  Aviso

  Esta constante não tem efeito e foi descontinuada a partir do PHP 8.1.0.

Valores para o parâmetro `flags` da função glob()
`GLOB_AVAILABLE_FLAGS` (int)
  Todas as constantes `GLOB_*` combinadas. Equivalente a `0` | `GLOB_BRACE` | `GLOB_MARK` | `GLOB_NOSORT` | `GLOB_NOCHECK` | `GLOB_NOESCAPE` | `GLOB_ERR` | `GLOB_ONLYDIR`
`GLOB_BRACE` (int)
  Expande {a,b,c} para corresponder a 'a', 'b', ou 'c'

  > Nota: `GLOB_BRACE` não está disponível em alguns sistemas não-GNU, como Solaris ou Alpine Linux.

`GLOB_ERR` (int)
  Para em erros de leitura (como diretórios não legíveis), por padrão erros são ignorados.
`GLOB_MARK` (int)
  Adiciona uma barra (ou barra invertida no Windows) para cada diretório retornado
`GLOB_NOCHECK` (int)
  Retorna a expressão de pesquisa se nenhum arquivo correspondente a ela for encontrado.
`GLOB_NOESCAPE` (int)
  Barras invertidas não escapam meta-caracteres.
`GLOB_NOSORT` (int)
  Retorna os arquivos conforme aparecem no diretório (sem ordenação). Quando esta opção não é usada, os nomes são ordenados alfabeticamente.
`GLOB_ONLYDIR` (int)
  Retorna somente as entradas de diretório que corresponderem à expressão.

Valores para o parâmetro `flags` da função pathinfo()
`PATHINFO_ALL` (int)
  Todas as partes da informação do caminho retornadas como um array associativo.
`PATHINFO_DIRNAME` (int)
  O caminho do diretório ou arquivo.
`PATHINFO_BASENAME` (int)
  O nome do diretório ou o nome e extensão do arquivo.
`PATHINFO_EXTENSION` (int)
  A extensão do arquivo.
`PATHINFO_FILENAME` (int)
  O nome do arquivo (sem a extensão) ou diretório.

Valores para o parâmetro `scanner_mode` das funções parse_ini_file() e parse_ini_string()
`INI_SCANNER_NORMAL` (int)
  Modo de scanner INI normal.
`INI_SCANNER_RAW` (int)
  Modo de scanner INI original.
`INI_SCANNER_TYPED` (int)
  Modo de scanner INI tipado.

Valores para o parâmetro `flags` da função fnmatch()
`FNM_NOESCAPE` (int)
  Desativa o escape de barra invertida.
`FNM_PATHNAME` (int)
  A barra na string corresponde apenas à barra no padrão fornecido.
`FNM_PERIOD` (int)
  O ponto inicial na string deve corresponder exatamente ao ponto no padrão fornecido.
`FNM_CASEFOLD` (int)
  Corresponde sem diferenciar maiúsculas e minúsculas. Parte da extensão GNU.

Constantes de Envio de Arquivo do PHP
`UPLOAD_ERR_CANT_WRITE` (int)

  Falha ao gravar o arquivo no disco. O valor da constante é `7`.

`UPLOAD_ERR_EXTENSION` (int)

  Uma extesão PHP parou o envio do arquivo. O PHP não fornece um meio de certificar que extensão causou a parada do envio; examinar a lista de extensões carregadas com phpinfo() pode ajudar. O valor da constante é `8`.

`UPLOAD_ERR_FORM_SIZE` (int)

  O arquivo enviado excede o tamanho da diretiva MAX_FILE_SIZE que foi especificada no formulário HTML. O valor da constante é `2`.

`UPLOAD_ERR_INI_SIZE` (int)

  O arquivo enviado excede o tamanho especificado na diretiva upload_max_filesize do php.ini. O valor da constante é `1`.

`UPLOAD_ERR_NO_FILE` (int)

  Nenhum arquivo foi enviado. O valor da constante é `4`.

`UPLOAD_ERR_NO_TMP_DIR` (int)

  Falta um diretório temporário. O valor da constante é `6`.

`UPLOAD_ERR_OK` (int)

  Não houve erro, o arquivo foi enviado com sucesso. O valor da constante é `0`.

`UPLOAD_ERR_PARTIAL` (int)

  O arquivo foi enviado apenas parcialmente. O valor da constante é `3`.

# Funções de Filesystem

# Veja Também

Para funções relacionadas, consulte também as seções Diretório e Execução de Programas.

Para obter uma lista e a descrição dos vários empacotadors de URL que podem ser usados como arquivos remotos, veja também Protocolos e empacotadores suportados.

# basename

(PHP 4, PHP 5, PHP 7, PHP 8)

basename — Retorna a última parte do caminho

### Descrição

function basename(string `$path`, string `$suffix` = ""): string

Dada uma string contendo o caminho para um arquivo ou diretório, esta função retornará a última parte do caminho.

> Nota:

> A função basename() opera de forma ingênua na string fornecida e não tem conhecimento do sistema de arquivos real ou dos componentes de caminho como "`..`".

Cuidado

A função basename() reconhece a localidade, portanto, para obter o nome correto ao usar caminhos com caracteres multibyte, a localidade correspondente deve ser definida com a função setlocale(). Se o parâmetro `path` contiver caracteres inválidos para a localidade atual, o comportamento de basename() será indefinido.

### Parâmetros

`path`

  Um caminho.

  No Windows, tanto a barra (`/`) quanto a barra invertida (`\`) são usadas como caractere separador de diretório. Em outros ambientes, apenas a barra (`/`) é usada.

`suffix`

  Se a última parte do caminho terminar em `suffix`, ele será removido.

### Valor Retornado

Retorna a última parte de um dado `path`.

### Exemplos

Exemplo #1 Exemplo de basename()

    <?php
    echo "1) ".basename("/etc/sudoers.d", ".d").PHP_EOL;
    echo "2) ".basename("/etc/sudoers.d").PHP_EOL;
    echo "3) ".basename("/etc/passwd").PHP_EOL;
    echo "4) ".basename("/etc/").PHP_EOL;
    echo "5) ".basename(".").PHP_EOL;
    echo "6) ".basename("/");
    ?>

O exemplo acima produzirá:

    1) sudoers
    2) sudoers.d
    3) passwd
    4) etc
    5) .
    6)

### Veja Também

- dirname() - Retorna o caminho para o diretório pai
- pathinfo() - Retorna informações sobre um caminho de arquivo

# chgrp

(PHP 4, PHP 5, PHP 7, PHP 8)

chgrp — Altera o grupo do arquivo

### Descrição

function chgrp(string `$filename`, string|int `$group`): bool

Tenta alterar o grupo do arquivo `filename` para `group`.

Somente o superusuário pode alterar arbitrariamente o grupo de um arquivo; outros usuários podem alterar o grupo de um arquivo para qualquer grupo do qual sejam membros.

### Parâmetros

`filename`

  Caminho para o arquivo.

`group`

  O nome ou número do grupo.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Alterando o grupo de um arquivo

    <?php
    $arquivo = 'arquivo_compartilhado.txt';
    $formato = "ID do grupo de %s em %s: %d\n";
    printf($formato, $arquivo, date('r'), filegroup($arquivo));
    chgrp($arquivo, 8);
    clearstatcache(); // não armazena em cache os resultados de filegroup()
    printf($formato, $arquivo, date('r'), filegroup($arquivo));
    ?>

### Notas

> Nota: Esta função não funcionará em arquivos remotos, pois o arquivo a ser examinado deve ser acessível através do sistema de arquivos do servidor.

> Nota: No Windows, esta função falha silenciosamente quando aplicada em um arquivo normal.

### Veja Também

- chown() - Modifica o proprietário do arquivo
- chmod() - Modifica as permissões do arquivo

# chmod

(PHP 4, PHP 5, PHP 7, PHP 8)

chmod — Modifica as permissões do arquivo

### Descrição

function chmod(string `$filename`, int `$permissions`): bool

Tenta mudar as permissões do arquivo especificado para o especificado em `permissions`.

### Parâmetros

`filename`

  O caminho para o arquivo.

`permissions`

  Note que `permissions` não é automaticamente assumido como valor em octal, então para assegurar a operação esperada, é necessário prefixar `permissions` com um zero (0). Strings como "g+w" não irão funcionar adequadamente.

      <?php
      chmod ("/arquivo/diretorio", 755);   // decimal; provavelmente incorreto
      chmod ("/arquivo/diretorio", "u+rwx,go+rx"); // string; incorreto
      chmod ("/arquivo/diretorio", 0755);  // octal; representação correta do modo
      ?>

  O parâmetro `permissions` consiste de três componentes numéricos em octal especificando restrições de acesso para o proprietário, para o grupo de usuário onde está o proprietário e para todos os outros usuários, nesta ordem. Um componente pode ser calculado adicionando-se as permissões necessárias para o usuário alvo. O número 1 significa direito de execução, 2 significa direito de escrita, 4 significa direito de leitura. Some esses números para especificar os direitos desejados. Pode-se consultar mais sobre modos em sistemas Unix com os comandos 'man 1 chmod' e 'man 2 chmod'.

      <?php
      // Escrita e leitura para o proprietário, nada mais para ninguém
      chmod ("/somedir/somefile", 0600);

      // Escrita e leitura para o proprietário, leitura para todos os outros
      chmod ("/somedir/somefile", 0644);

      // Tudo para o proprietário, leitura e execução para os outros
      chmod ("/somedir/somefile", 0755);

      // Tudo para o proprietário, leitura e execução para o grupo do prop
      chmod ("/somedir/somefile", 0750);
      ?>

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Em caso de falha, um aviso `E_WARNING` é emitido.

### Notas

> Nota:

> O usuário atual é aquele sob o qual o PHP é executado. Provavelmente não é o mesmo usuário que acessa linha de comando ou FTP. O modo pode ser modificado apenas pelo usuário proprietário do arquivo na maioria dos sistemas.

> Nota: Esta função não funcionará em arquivos remotos, pois o arquivo a ser examinado deve ser acessível através do sistema de arquivos do servidor.

### Veja Também

- chown() - Modifica o proprietário do arquivo
- chgrp() - Altera o grupo do arquivo
- fileperms() - Obtém permissões de arquivo
- stat() - Obtém informações sobre um arquivo

# chown

(PHP 4, PHP 5, PHP 7, PHP 8)

chown — Modifica o proprietário do arquivo

### Descrição

function chown(string `$filename`, string|int `$user`): bool

Tenta modificar o proprietário do `filename` para `user`. Somente o superusuário pode modificar o proprietário de um arquivo.

### Parâmetros

`filename`

  Caminho para o arquivo.

`user`

  O nome do usuário ou número.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Uso simples de chown()

    <?php

    // Nome de usuário e do arquivo que serão usados
    $file_name= "foo.php";
    $path = "/home/sites/php.net/public_html/sandbox/" . $file_name ;
    $user_name = "root";

    // Define o usuário proprietário
    chown($path, $user_name);

    // Verifica o resultado
    $stat = stat($path);
    print_r(posix_getpwuid($stat['uid']));

    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [name] => root
        [passwd] => x
        [uid] => 0
        [gid] => 0
        [gecos] => root
        [dir] => /root
        [shell] => /bin/bash
    )

### Notas

> Nota: Esta função não funcionará em arquivos remotos, pois o arquivo a ser examinado deve ser acessível através do sistema de arquivos do servidor.

> Nota: No Windows, esta função falha silenciosamente quando aplicada a um arquivo normal.

### Veja Também

- chmod() - Modifica as permissões do arquivo
- chgrp() - Altera o grupo do arquivo

# clearstatcache

(PHP 4, PHP 5, PHP 7, PHP 8)

clearstatcache — Limpa o cache de estado de arquivos

### Descrição

function clearstatcache(bool `$clear_realpath_cache` = `false`, string `$filename` = ""): void

Quando são chamadas as funções stat(), lstat() ou qualquer uma das funções afetadas (listadas abaixo), o PHP mantém em cache as informações que essas funções retornam para fornecer desempenho mais rápido. Entretanto, em certos casos pode ser necessário limpar as informações em cache. Por exemplo, se um mesmo arquivo é verificado várias vezes em um único script, e esse arquivo corre o risco de ser apagado ou modificado durante a operação do script, pode ser necessário limpar os dados do cache. Nesses casos, pode-se utilizar a função clearstatcache() para limpar as informações que o PHP mantém em cache sobre um arquivo.

Deve-se notar também que o PHP não guarda informação em cache sobre arquivos não existente. Assim, a função file_exists() for chamada em um arquivo que não existe, ela retornará `false` até que o arquivo seja criado. Se o arquivo for criado, ela retornará `true` mesmo que o arquivo seja removido. Entretanto, a função unlink() limpa o cache automaticamente.

> Nota:

> Esta função guarda informações em cache sobre nomes de arquivos específicos, de forma que somente será necessário chamar clearstatcache() se estão sendo realizadas várias operações sobre o mesmo nome de arquivo e seja necessário que a informação sobre esse arquivo em particular não seja armazenada em cache.

As funções afetadas incluem stat(), lstat(), file_exists(), is_writable(), is_readable(), is_executable(), is_file(), is_dir(), is_link(), filectime(), fileatime(), filemtime(), fileinode(), filegroup(), fileowner(), filesize(), filetype(), e fileperms().

### Parâmetros

`clear_realpath_cache`

  Se deve-se também limpar o cache de caminho real.

`filename`

  Limpa o cache de caminho real para um arquivo específico somente; apenas usado se `clear_realpath_cache` for `true`.

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de clearstatcache()

    <?php
    $file = 'output_log.txt';

    function get_owner($file)
    {
        $stat = stat($file);
        $user = posix_getpwuid($stat['uid']);
        return $user['name'];
    }

    $format = "UID @ %s: %s\n";

    printf($format, date('r'), get_owner($file));

    chown($file, 'ross');
    printf($format, date('r'), get_owner($file));

    clearstatcache();
    printf($format, date('r'), get_owner($file));
    ?>

O exemplo acima produzirá algo semelhante a:

    UID @ Sun, 12 Oct 2008 20:48:28 +0100: root
    UID @ Sun, 12 Oct 2008 20:48:28 +0100: root
    UID @ Sun, 12 Oct 2008 20:48:28 +0100: ross

# copy

(PHP 4, PHP 5, PHP 7, PHP 8)

copy — Copia arquivo

### Descrição

function copy(string `$from`, string `$to`, ?resource `$context` = `null`): bool

Faz uma cópia do arquivo informado em `from` para o arquivo informado em `to`.

Se o pretendido for mover um arquivo, utilize a função rename().

### Parâmetros

`from`

  Caminho para o arquivo de origem.

`to`

  O caminho de destino. Se o parâmetro `to` for uma URL, a operação de cópia pode falhar se o empacotador não suportar a sobrescrita de arquivos existentes.

  Aviso

  Se o arquivo de destino já existir, ele será sobrescrito.

`context`

  Um resource válido de contexto criado com stream_context_create().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de copy()

    <?php
    $file = 'example.txt';
    $newfile = 'example.txt.bak';

    if (!copy($file, $newfile)) {
        echo "falha ao copiar $file...\n";
    }
    ?>

### Veja Também

- move_uploaded_file() - Move um arquivo enviado para uma nova localização
- rename() - Renomeia um arquivo ou diretório
- A seção do manual sobre Gerenciamento de envio de arquivos

# delete

delete — Consulte unlink() ou unset()

### Descrição

Não existe função ou instrução "delete" no PHP. Se você chegou nesta página procurando por deletar arquivos, consulte unlink(). Para excluir uma variável de um escopo local, consulte unset().

### Veja Também

- unlink() - Apaga um arquivo
- unset() - unset remove a definição de uma variável informada

# dirname

(PHP 4, PHP 5, PHP 7, PHP 8)

dirname — Retorna o caminho para o diretório pai

### Descrição

function dirname(string `$path`, int `$levels` = 1): string

Dada uma string contendo um caminho para um arquivo ou diretório, esta função irá retornar o caminho do diretório pai que é `levels` acima do diretório atual.

> Nota:

> dirname() opera ingenuamente sobre a string de entrada, e não tem conhecimento do sistema de arquivos real, ou componentes de caminho de diretório como "`..`".

Cuidado

No Windows, dirname() assume o código de página atual, portanto para que possa ver os nomes corretos de diretório com caracteres multi-byte, o código de página correspondente deve ser configurado. Se `path` contiver caracteres que são inválidos para o código de página ativo, o comportamento de dirname() será indefinido.

Em outros sistemas, dirname() assume que `path` estará codificado em formato compatível com ASCII. Caso contrário o comportamento da função será indefinido.

### Parâmetros

`path`

  Um caminho.

  No Windows, tanto a barra (`/`) quanto a barra invertida (`\`) são usadas como caractere separador de diretório. Em outros ambientes, é utilizada a barra (`/`).

`levels`

  O número de diretórios pai para subir.

  Deve ser um inteiro maior que 0.

### Valor Retornado

Retorna o caminho do diretório pai. Se não houver nenhuma barra no `path`, um ponto ('`.`') é retornado, indicando o diretório atual. Do contrário, a string retornada é o `path` com qualquer `/componente` ao final da string removido.

Cuidado

Deve-se tomar cuidado ao usar esta função em um loop que alcança o diretório raiz pois isto pode resultar em um loop infinito.

    <?php
    dirname('.');    // Retornará '.'.
    dirname('/');    // Retornará `\` no Windows e '/' em sistemas *nix.
    dirname('\\');   // Retornará `\` no Windows e '.' em sistemas *nix.
    dirname('C:\\'); // Retornará 'C:\' no Windows e '.' em sistemas *nix.
    ?>

### Exemplos

Exemplo #1 Exemplo de dirname()

    <?php
     echo dirname("/etc/passwd") . PHP_EOL;
     echo dirname("/etc/") . PHP_EOL;
     echo dirname(".") . PHP_EOL;
     echo dirname("C:\\") . PHP_EOL;
     echo dirname("/usr/local/lib", 2);

O exemplo acima produzirá algo semelhante a:

    /etc
     / (ou \ no Windows)
     .
     C:\
     /usr

### Veja Também

- basename() - Retorna a última parte do caminho
- pathinfo() - Retorna informações sobre um caminho de arquivo
- realpath() - Retorna o path absoluto canonizado

# disk_free_space

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

disk_free_space — Retorna o espaço disponível no sistema de arquivos ou partição de disco

### Descrição

function disk_free_space(string `$directory`): float|false

Dado uma string contendo um diretório, esta função retornará o número de bytes disponíveis no sistema de arquivos ou partição de disco.

### Parâmetros

`directory`

  Um diretório do sistema de arquivos ou partição de disco.

  > Nota:

  > Dado um nome de arquivo ao invés de um diretório, o comportamento da função não é especificado e pode ser diferente entre sistemas operacionais e versões do PHP.

### Valor Retornado

Retorna o número de bytes disponíveis como um float ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de disk_free_space()

    <?php
    // $df contém o número de bytes disponíveis em "/"
    $df = disk_free_space("/");

    // No Windows:
    $df_c = disk_free_space("C:");
    $df_d = disk_free_space("D:");
    ?>

### Notas

> Nota: Esta função não funcionará em arquivos remotos, pois o arquivo a ser examinado deve ser acessível através do sistema de arquivos do servidor.

### Veja Também

- disk_total_space() - Retorna o tamanho total de um sistema de arquivos ou partição de disco

# disk_total_space

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

disk_total_space — Retorna o tamanho total de um sistema de arquivos ou partição de disco

### Descrição

function disk_total_space(string `$directory`): float|false

Dado uma string contendo um diretório, esta função retornará o número total de bytes do sistema de arquivos ou da partição de disco.

### Parâmetros

`directory`

  Um diretório do sistema de arquivos ou uma partição de disco.

### Valor Retornado

Retorna o número total de bytes como um float ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de disk_total_space()

    <?php
    // $ds contém o numero total de bytes disponíveis em "/"
    $ds = disk_total_space("/");

    // No Windows:
    disk_total_space("C:");
    disk_total_space("D:");
    ?>

### Notas

> Nota: Esta função não funcionará em arquivos remotos, pois o arquivo a ser examinado deve ser acessível através do sistema de arquivos do servidor.

### Veja Também

- disk_free_space() - Retorna o espaço disponível no sistema de arquivos ou partição de disco

# diskfreespace

(PHP 4, PHP 5, PHP 7, PHP 8)

diskfreespace — Sinônimo de disk_free_space()

### Descrição

Esta função é um apelido para: disk_free_space().

# fclose

(PHP 4, PHP 5, PHP 7, PHP 8)

fclose — Fecha um ponteiro de arquivo aberto

### Descrição

function fclose(resource `$stream`): bool

O arquivo apontado por `stream` é fechado.

### Parâmetros

`stream`

  O ponteiro para o arquivo tem que ser válido e tem que apontar para um arquivo aberto por fopen() ou fsockopen().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de fclose()

    <?php

      $handle = fopen('qualquerarquivo.txt', 'r');

      fclose($handle);

    ?>

### Veja Também

- fopen() - Abre um arquivo ou URL
- fsockopen() - Abre uma conexão socket de domínio Unix ou de Internet

# fdatasync

(PHP 8 >= 8.1.0)

fdatasync — Sincroniza dados (mas não metadados) ao arquivo

### Descrição

function fdatasync(resource `$stream`): bool

Esta função sincroniza o conteúdo do fluxo definido em `stream` para a mídia de armazenamento, da mesma forma que fsync(), mas não sincroniza os metadados de arquivo. Note que esta função só é efetivamente diferente em sistemas POSIX. No Windows, esta função é apelidada de fsync().

### Parâmetros

`stream`
  O ponteiro de arquivo deve ser válido e deve apontar para um arquivo aberto com sucesso por fopen() ou fsockopen() (e ainda não fechado por fclose()).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de fdatasync()

    <?php

    $file = 'test.txt';

    $stream = fopen($file, 'w');
    fwrite($stream, 'test data');
    fwrite($stream, "\r\n");
    fwrite($stream, 'dados adicionais');

    fdatasync($stream);
    fclose($stream);
    ?>

### Veja Também

- fflush() - Força a liberação do buffer para um arquivo
- fsync() - Sincroniza mudanças ao arquivo (incluindo metadados)

# feof

(PHP 4, PHP 5, PHP 7, PHP 8)

feof — Testa pelo fim-de-arquivo em um ponteiro de arquivo

### Descrição

function feof(resource `$stream`): bool

Testa pelo fim-de-arquivo em um ponteiro de arquivo.

### Parâmetros

`stream`
  O ponteiro de arquivo deve ser válido e deve apontar para um arquivo aberto com sucesso por fopen() ou fsockopen() (e ainda não fechado por fclose()).

### Valor Retornado

Retorna `true` se o ponteiro estiver no fim do arquivo ou um erro ocorrer (incluindo um limite de tempo de socket); caso contrário retorna `false`.

### Notas

Aviso

Se uma conexão aberta por fsockopen() não foi fechada pelo servidor, feof() irá travar. Para contornar isto, veja o exemplo abaixo:

Exemplo #1 Manipulando limites de tempo com feof()

    <?php
    function safe_feof($fp, &$start = NULL) {
     $start = microtime(true);

     return feof($fp);
    }

    /* Assumindo que $fp foi previamente aberto por fsockopen() */

    $start = NULL;
    $timeout = ini_get('default_socket_timeout');

    while(!safe_feof($fp, $start) && (microtime(true) - $start) < $timeout)
    {
     /* Manipulação */
    }
    ?>

Aviso

Se o ponteiro de arquivo passado não for válido pode-se chegar a um loop infinito, porque feof() falha em retornar `true`.

Exemplo #2 Exemplo de feof() com um ponteiro de arquivo inválido

    <?php
    // se o arquivo não puder ser lido ou não existir a função fopen retorna FALSE
    $file = @fopen("no_such_file", "r");

    // FALSE a partir do fopen irá emitir um aviso (warning) e resultar em um loop infinito aqui
    while (!feof($file)) {
    }

    fclose($file);
    ?>

# fflush

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

fflush — Força a liberação do buffer para um arquivo

### Descrição

function fflush(resource `$stream`): bool

Esta função força a escrita de toda saída cacheada para o recurso apontado fluxo de arquivo `stream`.

### Parâmetros

`stream`
  O ponteiro de arquivo deve ser válido e deve apontar para um arquivo aberto com sucesso por fopen() ou fsockopen() (e ainda não fechado por fclose()).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de escrita em arquivo usando fflush()

    <?php
    $filename = 'bar.txt';

    $file = fopen($filename, 'r+');
    rewind($file);
    fwrite($file, 'Foo');
    fflush($file);
    ftruncate($file, ftell($file));
    fclose($file);
    ?>

### Veja Também

- clearstatcache() - Limpa o cache de estado de arquivos
- fwrite() - Escrita binary-safe em arquivos

# fgetc

(PHP 4, PHP 5, PHP 7, PHP 8)

fgetc — Lê um caractere do ponteiro de arquivo

### Descrição

function fgetc(resource `$stream`): string|false

Obtém um caractere de um dado ponteiro de arquivo.

### Parâmetros

`stream`
  O ponteiro de arquivo deve ser válido e deve apontar para um arquivo aberto com sucesso por fopen() ou fsockopen() (e ainda não fechado por fclose()).

### Valor Retornado

Retorna uma string contendo um único caractere lido do ponteiro do arquivo passado por `stream`. Retorna `false` em EOF.

Aviso

Esta função pode retornar o valor booleano `false`, mas também pode retornar um valor não booleano que pode ser avaliado como `false`. Leia a seção sobre Booleanos para mais informações. Use o operador === para testar o valor retornado por esta função.

### Exemplos

Exemplo #1 Um exemplo da fgetc()

    <?php
    $fp = fopen('algumarquivo.txt', 'r');
    if (!$fp) {
        echo 'Não é possivel abrir algumarquivo.txt';
    }
    while (false !== ($char = fgetc($fp))) {
        echo "$char\n";
    }
    ?>

### Notas

> Nota: Esta função é compatível com dados binários.

### Veja Também

- fread() - Leitura de arquivo segura para binário
- fopen() - Abre um arquivo ou URL
- popen() - Abre um processo como ponteiro de arquivo
- fsockopen() - Abre uma conexão socket de domínio Unix ou de Internet
- fgets() - Lê uma linha de um ponteiro de arquivo

# fgetcsv

(PHP 4, PHP 5, PHP 7, PHP 8)

fgetcsv — Lê uma linha do ponteiro de arquivos e a interpreta como campos CSV

### Descrição

function fgetcsv(
resource `$stream`,
?int `$length` = `null`,
string `$separator` = ",",
string `$enclosure` = "\"",
string `$escape` = "\\"
): array|false

Similar à função fgets(), exceto que a fgetcsv() interpreta a linha em busca de campos no formato CSV e retorna um array contendo os campos lidos.

> Nota: As configurações de localidade são consideradas por esta função. Por exemplo, dados em certas codificações de um byte podem ser interpretados incorretamente se `LC_CTYPE` for `en_US.UTF-8`.

### Parâmetros

`stream`

  Um ponteiro de arquivo válido para um arquivo aberto com sucesso por fopen(), popen() ou fsockopen().

`length`

  Deve ser maior do que a maior linha (em caracteres) a ser encontrada no arquivo CSV (considerando também os caracteres de fim-de-linha). Caso contrário a linha é dividida em partes de `length` caracteres, a não ser que a divisão ocorra dentro de um caractere que cerca os campos (enclosure).

  Se este parâmetro for omitido (ou definido em 0 ou `null` a partir do PHP 8.0.0), o tamanho máximo das linhas não é limitado, o que é um pouco mais lento.

`separator`

  O parâmetro `separator` define o delimitador de campo. Precisa ser um caractere de um byte.

`enclosure`

  O parâmetro `enclosure` define o caractere que cerca um campo. Precisa ser um caractere de um byte.

`escape`

  O parâmetro `escape` define o caractere de escape. Precisa ser um caractere de um byte ou uma string vazia. Uma string vazia (`""`) desabilita o mecanismo de escape proprietário.

  Aviso

  No fluxo de entrada, o caractere `enclosure` sempre pode ser escapado por duplicação dentro de uma string delimitada, resultando em um único caractere `enclosure` no resultado interpretado. O caractere `escape` funciona de forma diferente: Se uma sequência de caracteres `escape` e `enclosure` aparecerem no fluxo, ambos os caracteres estarão presentes no valor interpretado. Portanto, para os parâmetros padrão, uma linha CSV como `"a""b","c\"d"` terá os campos interpretados como `a"b` e `c\"d`, respectivamente.

  Aviso

  A partir do PHP 8.4.0, depender do valor padrão de `escape` foi descontinuado. Ele precisa ser fornecido explicitamente tanto por posição quanto pelo uso de argumentos nomeados.

Aviso

Quando o parâmetro `escape` for definido para algo diferente de uma string vazia (`""`), isso pode resultar em um CSV que não esteja conforme a » RFC 4180 ou que não seja capaz de sobreviver a uma viagem de ida e volta através das funções CSV do PHP. O padrão para `escape` é `"\\"`, portanto é recomendado defini-lo explicitamente para a string vazia. O valor padrão será alterado em uma versão futura do PHP, mas não antes do PHP 9.0.

### Valor Retornado

Retorna um array indexado contendo os campos lidos em caso de sucesso, ou `false` em caso de falha.

> Nota:

> Uma linha em branco em um arquivo CSV será retornada como um array contendo um único campo nulo (null) e não será tratada como um erro.

> Nota: Se o PHP não estiver reconhecendo corretamente os finais de linha ao ler arquivos em um computador Macintosh ou que foram criados em um, habilitar a opção de configuração em tempo de execução auto_detect_line_endings pode ajudar a resolver o problema.

### Erros/Exceções

Lança uma ValueError se `separator` ou `enclosure` não tiver comprimento de um byte.

Lança uma ValueError se `escape` não tiver comprimento de um byte ou se for uma string vazia.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Depender do valor padrão de `escape` agora está descontinuado.
8.3.0 | Uma string vazia é retornada ao invés de uma string com um único byte nulo para o último campo, se ele contiver apenas um demarcador não terminado.
8.0.0 | O parâmetro `length` agora pode ser nulo.
7.4.0 | O parâmetro `escape` agora aceita uma string vazia para desabilitar o mecanismo de escape proprietário.

### Exemplos

Exemplo #1 Lê e imprime todo o conteúdo de um arquivo CSV

    <?php
    $row = 1;
    if (($handle = fopen("teste.csv", "r")) !== FALSE) {
        while (($data = fgetcsv($handle, 1000, ",")) !== FALSE) {
            $num = count($data);
            echo "<p> $num campos na linha $row: <br /></p>\n";
            $row++;
            for ($c=0; $c < $num; $c++) {
                echo $data[$c] . "<br />\n";
            }
        }
        fclose($handle);
    }
    ?>

### Veja Também

- fputcsv() - Formata a linha como CSV e a escreve em um ponteiro de arquivo
- str_getcsv() - Analisa uma string CSV e retorna os dados em um array
- SplFileObject::fgetcsv() - Obtém linha do arquivo e interpreta como campos CSV
- SplFileObject::fputcsv() - Escreve um array de campos como uma linha CSV
- SplFileObject::setCsvControl() - Definir o delimitador, o encapsulador e o caractere de escape para CSV
- SplFileObject::getCsvControl() - Obtém o delimitador, o caractere de fechamento e o caractere de escape para CSV
- explode() - Divide uma string com base em outra string
- file() - Lê todo o arquivo para um array
- pack() - Empacota dados em uma string binária

# fgets

(PHP 4, PHP 5, PHP 7, PHP 8)

fgets — Lê uma linha de um ponteiro de arquivo

### Descrição

function fgets(resource `$stream`, ?int `$length` = `null`): string|false

Retorna uma linha do ponteiro do arquivo.

### Parâmetros

`stream`
  O ponteiro de arquivo deve ser válido e deve apontar para um arquivo aberto com sucesso por fopen() ou fsockopen() (e ainda não fechado por fclose()).
`length`

  A leitura termina quando `length` - 1 bytes tenham sido lidos, ou uma quebra de linha (que é incluída no retorno), ou no final do arquivo (EOF), o que acontecer primeiro. Se nenhum comprimento for especificado, a leitura do fluxo continuará até chegar ao final da linha.

### Valor Retornado

Retorna uma string de até `length` - 1 bytes lida do arquivo apontado por `stream`. Se não tiver mais dados para ler no ponteiro do arquivo, então retorna `false`.

Se um erro ocorrer, é retornado `false`.

### Exemplos

Exemplo #1 Lendo um arquivo linha por linha

    <?php

    $fp = @fopen("/tmp/arquivodeentrada.txt", "r");

    if ($fp) {
        while (($buffer = fgets($fp, 4096)) !== false) {
            echo $buffer, PHP_EOL;
        }

        if (!feof($fp)) {
            echo "Erro: falha inexperada de fgets()\n";
        }

        fclose($fp);
    }

    ?>

### Notas

> Nota: Se o PHP não estiver reconhecendo corretamente os finais de linha ao ler arquivos em um computador Macintosh ou que foram criados em um, habilitar a opção de configuração em tempo de execução auto_detect_line_endings pode ajudar a resolver o problema.

> Nota:

> Pessoas acostumadas à semântica do fgets() em 'C' devem notar a diferença em como o fim do arquivo (`EOF`) é retornado.

### Veja Também

- fgetss() - Ler uma linha de um ponteiro de arquivo e retira as tags HTML
- fread() - Leitura de arquivo segura para binário
- fgetc() - Lê um caractere do ponteiro de arquivo
- stream_get_line() - Obtém uma linha do recurso do fluxo até um delimitador informado
- fopen() - Abre um arquivo ou URL
- popen() - Abre um processo como ponteiro de arquivo
- fsockopen() - Abre uma conexão socket de domínio Unix ou de Internet
- stream_set_timeout() - Define o limite de tempo em um fluxo

# fgetss

(PHP 4, PHP 5, PHP 7)

fgetss — Ler uma linha de um ponteiro de arquivo e retira as tags HTML

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.3.0 e foi REMOVIDA a partir do PHP 8.0.0. O uso desta função é fortemente desencorajado.

### Descrição

function fgetss(resource `$handle`, int `$length` = ?, string `$allowable_tags` = ?): string

Idêntico a fgets(), exceto que fgetss() tenta retirar qualquer byte NUL, tag HTML ou PHP do texto que ela lê. A função retém o estado de interpretação de chamada para chamada, e desta forma não É equivalente a chamar strip_tags() no valor de retorno de fgets().

### Parâmetros

`handle`
  O ponteiro de arquivo deve ser válido e deve apontar para um arquivo aberto com sucesso por fopen() ou fsockopen() (e ainda não fechado por fclose()).
`length`

  Tamanho da informação a ser recebida.

`allowable_tags`

  Pode-se usar o terceiro parâmetro opcional para especificar as tags que não devem ser removidas. Consulte strip_tags() para detalhes sobre `allowable_tags`.

### Valor Retornado

Retorna uma string de até `length` - 1 bytes lidos do arquivo apontado por `handle`, com todo o código HTML e PHP removidos.

Se um erro ocorrer, retorna `false`.

### Exemplos

Exemplo #1 Lendo um arquivo PHP linha por linha

    <?php
    $str = <<<EOD
    <html><body>
     <p>Bem-vindo! Hoje é <?php echo(date('jS')); ?> de <?= date('F'); ?>.</p>
    </body></html>
    Texto fora do bloco HTML.
    EOD;
    file_put_contents('sample.php', $str);

    $handle = @fopen("sample.php", "r");
    if ($handle) {
        while (!feof($handle)) {
            $buffer = fgetss($handle, 4096);
            echo $buffer;
        }
        fclose($handle);
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Bem-vindo! Hoje é  de .

    Texto fora do bloco HTML.

### Notas

> Nota: Se o PHP não estiver reconhecendo corretamente os finais de linha ao ler arquivos em um computador Macintosh ou que foram criados em um, habilitar a opção de configuração em tempo de execução auto_detect_line_endings pode ajudar a resolver o problema.

### Veja Também

- fgets() - Lê uma linha de um ponteiro de arquivo
- fopen() - Abre um arquivo ou URL
- popen() - Abre um processo como ponteiro de arquivo
- fsockopen() - Abre uma conexão socket de domínio Unix ou de Internet
- strip_tags() - Retira as tags HTML e PHP de uma string
- SplFileObject::fgetss() - Obtém linha do arquivo e remove tags HTML
- O filtro string.strip_tags

# file

(PHP 4, PHP 5, PHP 7, PHP 8)

file — Lê todo o arquivo para um array

### Descrição

function file(string `$filename`, int `$flags` = 0, ?resource `$context` = `null`): array|false

Carrega todo um arquivo em um array.

> Nota:

> Pode-se utilizar file_get_contents() para retornar o conteúdo de um arquivo como uma string.

### Parâmetros

`filename`

  Caminho para o arquivo.

  Dica

  Uma URL pode ser usada como um nome de arquivo com esta função se os empacotadores fopen estiverem habilitados. Consulte a função fopen() para mais detalhes sobre como especificar o nome do arquivo. Consulte os Protocolos e empacotadores suportados para obter links para informações sobre as capacidades de cada empacotador, notas de uso e informações sobre quaisquer variáveis predefinidas que eles possam fornecer.

`flags`

  O parâmetro opcional `flags` pode ser uma ou mais das seguintes constantes:

  `FILE_USE_INCLUDE_PATH`
    Procurar pelo arquivo no include_path.
  `FILE_IGNORE_NEW_LINES`
    Omite a quebra de linha no final de cada elemento do array.
  `FILE_SKIP_EMPTY_LINES`
    Pula linhas vazias.
  `FILE_NO_DEFAULT_CONTEXT`
    Não usa o contexto padrão.
`context`
  Um resource de contexto de fluxo.

### Valor Retornado

Retorna o arquivo em um array. Cada elemento do array corresponde a uma linha no arquivo, ainda com a quebra de linha. Em caso de falha, file() retorna `false`

> Nota:

> Cada linha no array incluirá a quebra de linha, a não ser que `FILE_IGNORE_NEW_LINES` seja usado.

> Nota: Se o PHP não estiver reconhecendo corretamente os finais de linha ao ler arquivos em um computador Macintosh ou que foram criados em um, habilitar a opção de configuração em tempo de execução auto_detect_line_endings pode ajudar a resolver o problema.

### Erros/Exceções

A partir do PHP 8.3.0, lança uma exceção ValueError se `flags` incluir qualquer valor inválido, tal como `FILE_APPEND`.

Emite um aviso `E_WARNING` se o arquivo não existe.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Uma exceção ValueError é lançada para qualquer valor inválido no parâmetro `flags`.

### Exemplos

Exemplo #1 Exemplo de file()

    <?php
    // Lê um arquivo em um array.  Nesse exemplo será obtido o código fonte HTML de
    // uma URL via HTTP
    $lines = file ('http://www.example.com/');

    // Percorre o array, mostrando o fonte HTML com numeração de linhas.
    foreach ($lines as $line_num => $line) {
        echo "Linha #<b>{$line_num}</b> : " . htmlspecialchars($line) . "<br />\n";
    }

    // Usando o parâmetro de opções opcionais
    $trimmed = file('somefile.txt', FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);
    ?>

### Notas

Aviso

Ao usar SSL, o Microsoft IIS violará o protocolo fechando a conexão sem enviar uma notificação `close_notify`. O PHP reportará isso como "SSL: Fatal Protocol Error" quando chegar ao final dos dados. Para contornar isso, o valor de error_reporting deve ser reduzido a um nível que não inclua avisos. O PHP pode detectar servidores IIS defeituosos quando o fluxo é aberto usando o empacotador `https://` e suprimirá o aviso. Ao usar fsockopen() para criar um soquete `ssl://`, o desenvolvedor é responsável por detectar e suprimir este aviso.

### Veja Também

- file_get_contents() - Lê todo o conteúdo de um arquivo para uma string
- readfile() - Exibe o conteúdo de um arquivo
- fopen() - Abre um arquivo ou URL
- fsockopen() - Abre uma conexão socket de domínio Unix ou de Internet
- popen() - Abre um processo como ponteiro de arquivo
- include - include
- stream_context_create() - Cria um contexto de fluxo

# file_exists

(PHP 4, PHP 5, PHP 7, PHP 8)

file_exists — Verifica se um arquivo ou diretório existe

### Descrição

function file_exists(string `$filename`): bool

Verifica se um arquivo ou diretório existe.

### Parâmetros

`filename`

  Caminho para o arquivo ou diretório.

  No Windows, use //computername/share/filename ou \\computername\share\filename para checar arquivos em compartilhamentos de rede.

### Valor Retornado

Retorna `true` se o arquivo ou diretório especificado por `filename` existe; `false` caso contrário.

> Nota:

> Esta função retorna `false` para ligações simbólicas apontando para arquivos inexistentes.

> Nota:

> O teste é realizado utilizando o UID/GID real, em vez de outro valor efetivo.

> Nota: Como o tipo inteiro do PHP possui sinal e muitas plataformas usam números inteiros de 32 bits, algumas funções do sistema de arquivos podem retornar resultados inesperados para arquivos maiores que 2GB.

### Erros/Exceções

Em caso de falha, um `E_WARNING` será emitido.

### Exemplos

Exemplo #1 Testando se um arquivo existe

    <?php
    $filename = '/caminho/para/arquivo.txt';

    if (file_exists($filename)) {
        echo "O arquivo $filename existe";
    } else {
        echo "O arquivo $filename não existe";
    }
    ?>

### Notas

> Nota: Os resultados desta função são armazenados em cache. Consulte a função clearstatcache() para mais detalhes.

Dica

A partir do PHP 5.0.0, esta função também pode ser usada com alguns empacotadores de URL. Consulte os Protocolos e empacotadores suportados para determinar quais empacotadores suportam a família de funções stat().

### Veja Também

- is_readable() - Diz se o arquivo existe e se ele pode ser lido
- is_writable() - Diz se o arquivo pode ser modificado
- is_file() - Informa se o arquivo é um arquivo comum
- file() - Lê todo o arquivo para um array
- SplFileInfo

# file_get_contents

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

file_get_contents — Lê todo o conteúdo de um arquivo para uma string

### Descrição

function file_get_contents(
string `$filename`,
bool `$use_include_path` = `false`,
?resource `$context` = `null`,
int `$offset` = 0,
?int `$length` = `null`
): string|false

Esta função é semelhante à file(), exceto que file_get_contents() retorna o arquivo em uma string, começando a partir de `offset` até `length` bytes. Em caso de falha, file_get_contents() retornará `false`.

file_get_contents() é o método preferível para ler o conteúdo de um arquivo em uma string. Ela usa técnicas de mapeamento de memória suportadas pelo sistema operacional para melhorar o desempenho.

> Nota:

> Se for aberta uma URI com caracteres especiais, como espaços, é necessário codificar a URI com urlencode().

### Parâmetros

`filename`

  Nome do arquivo para ler.

`use_include_path`

  > Nota:

  > A constante `FILE_USE_INCLUDE_PATH` pode ser usada para acionar a busca no include path. Isto não é possível se a tipagem estrita estiver habilitada, já que `FILE_USE_INCLUDE_PATH` é um int. Em vez disso, use `true`.

`context`

  Um recurso de contexto válido, criado com stream_context_create(). Se você não precisa usar um contexto personalizado, você pode ignorar este parâmetro passando `null`.

`offset`

  O ponto onde a leitura deve começar no fluxo original. Offsets negativos contam a partir do final do fluxo.

  `offset` não é suportado em arquivos remotos. Tentar fazer busca em arquivos não locais pode funcionar com offsets pequenos, mas isso é imprevisível pois só funciona no fluxo com buffer.

`length`

  Comprimento máximo dos dados lidos. O padrão é ler até que o fim do arquivo seja alcançado. Note que este parâmetro é aplicado para o fluxo processado pelos filtros.

### Valor Retornado

A função retorna os dados lidos ou `false` em caso de falha.

Aviso

Esta função pode retornar o valor booleano `false`, mas também pode retornar um valor não booleano que pode ser avaliado como `false`. Leia a seção sobre Booleanos para mais informações. Use o operador === para testar o valor retornado por esta função.

### Erros/Exceções

Um erro de nível `E_WARNING` é gerado se `filename` não puder ser encontrado, `length` é menor que zero, ou se a busca no fluxo pelo `offset` especificado falhar.

Quando file_get_contents() é chamada em um diretório, um erro nível `E_WARNING` é gerado no Windows, e a partir do PHP 7.4 em outros sistemas operacionais também.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `length` agora é anulável.
7.1.0 | Suporte para `offset`s negativos foi adicionado.

### Exemplos

Exemplo #1 Obtém e exibe o código-fonte da página inicial de um website

    <?php
    $homepage = file_get_contents('http://www.example.com/');
    echo $homepage;
    ?>

Exemplo #2 Buscando no include_path

    <?php
    // Se strict types estiver ativado com declare(strict_types=1);
    $file = file_get_contents('./people.txt', true);
    // Se não
    $file = file_get_contents('./people.txt', FILE_USE_INCLUDE_PATH);
    ?>

Exemplo #3 Lendo uma sessão de um arquivo

    <?php
    // Lê 14 letras começando da letra 21
    $section = file_get_contents('./people.txt', FALSE, NULL, 20, 14);
    var_dump($section);
    ?>

O exemplo acima produzirá algo semelhante a:

    string(14) "lle Bjori Ro"

Exemplo #4 Usando contextos de fluxo

    <?php
    // Criam um fluxo
    $opts = [
        'http' => [
            'method' => "GET",
            'header' => "Accept-language: en\r\n" .
                    "Cookie: foo=bar\r\n"
        ]
    ];

    $context = stream_context_create($opts);

    // Abre o arquivo utilizando os headers HTTP craidos acima
    $file = file_get_contents('http://www.example.com/', false, $context);
    ?>

### Notas

> Nota: Esta função é compatível com dados binários.

Dica

Uma URL pode ser usada como um nome de arquivo com esta função se os empacotadores fopen estiverem habilitados. Consulte a função fopen() para mais detalhes sobre como especificar o nome do arquivo. Consulte os Protocolos e empacotadores suportados para obter links para informações sobre as capacidades de cada empacotador, notas de uso e informações sobre quaisquer variáveis predefinidas que eles possam fornecer.

Aviso

Ao usar SSL, o Microsoft IIS violará o protocolo fechando a conexão sem enviar uma notificação `close_notify`. O PHP reportará isso como "SSL: Fatal Protocol Error" quando chegar ao final dos dados. Para contornar isso, o valor de error_reporting deve ser reduzido a um nível que não inclua avisos. O PHP pode detectar servidores IIS defeituosos quando o fluxo é aberto usando o empacotador `https://` e suprimirá o aviso. Ao usar fsockopen() para criar um soquete `ssl://`, o desenvolvedor é responsável por detectar e suprimir este aviso.

### Veja Também

- file() - Lê todo o arquivo para um array
- fgets() - Lê uma linha de um ponteiro de arquivo
- fread() - Leitura de arquivo segura para binário
- readfile() - Exibe o conteúdo de um arquivo
- file_put_contents() - Escreve dados em um arquivo
- stream_get_contents() - Lê o restante de um fluxo em uma string
- stream_context_create() - Cria um contexto de fluxo
- $http_response_header

# file_put_contents

(PHP 5, PHP 7, PHP 8)

file_put_contents — Escreve dados em um arquivo

### Descrição

function file_put_contents(
string `$filename`,
mixed `$data`,
int `$flags` = 0,
?resource `$context` = `null`
): int|false

Esta função é idêntica a chamar fopen(), fwrite() e fclose() sucessivamente para escrever dados em um arquivo.

Se o arquivo informado em `filename` não existir, o arquivo é criado. Do contrário, o arquivo existente é sobrescrito, a não ser que a opção `FILE_APPEND` seja definida.

### Parâmetros

`filename`

  O caminho para o arquivo onde os dados serão escritos.

`data`

  Os dados a serem escritos. Pode ser uma string, um array ou um recurso stream.

  Se `data` for um recurso stream, o buffer restante desse fluxo será copiado para o arquivo especificado, semelhante à utilização de stream_copy_to_stream().

  Você também pode especificar o parâmetro `data` como um array unidimensional. Isso é equivalente a `file_put_contents($filename, implode('', $array))`.

`flags`

  O valor de `flags` pode ser qualquer combinação das seguintes opções, adicionadas com o operador binário OR (`|`).

  Opções disponíveis
  Opção | Descrição
  --- | ---
  `FILE_USE_INCLUDE_PATH` | Procura o arquivo `filename` nos diretórios de include. Consulte include_path para mais informações.
  `FILE_APPEND` | Se o arquivo `filename` já existir, acrescenta os dados ao arquivo ao invés de sobrescrevê-lo.
  `LOCK_EX` | Adquire uma trava exclusiva no arquivo ao prosseguir para a escrita. Em outras palavras, uma chamada a flock() acontece entre a chamada fopen() e a chamada fwrite(). Isso não é idêntico à uma chamada fopen() com modo "x".

`context`

  Um recurso de contexto válido criado com stream_context_create().

### Valor Retornado

Esta função retorna a quantidade de bytes que foi escrita no arquivo ou `false` em caso de falha.

Aviso

Esta função pode retornar o valor booleano `false`, mas também pode retornar um valor não booleano que pode ser avaliado como `false`. Leia a seção sobre Booleanos para mais informações. Use o operador === para testar o valor retornado por esta função.

### Exemplos

Exemplo #1 Exemplo de uso simples

    <?php
    $file = 'people.txt';
    // Abre o arquivo para obter o conteúdo existente
    $current = file_get_contents($file);
    // Acrescenta a nova pessoa no arquivo
    $current .= "John Smith\n";
    // Escreve o conteúdo de volta no arquivo
    file_put_contents($file, $current);
    ?>

Exemplo #2 Usando flags

    <?php
    $file = 'people.txt';
    // A nova pessoa para adicionar no arquivo
    $person = "John Smith\n";
    // Escreve o conteúdo no arquivo,
    // usando a flag FILE_APPEND para acrescentar o conteúdo no fim do arquivo
    // e a flag LOCK_EX para evitar que outra pessoa escreva no arquivo ao mesmo tempo
    file_put_contents($file, $person, FILE_APPEND | LOCK_EX);
    ?>

### Notas

> Nota: Esta função é compatível com dados binários.

Dica

Uma URL pode ser usada como um nome de arquivo com esta função se os empacotadores fopen estiverem habilitados. Consulte a função fopen() para mais detalhes sobre como especificar o nome do arquivo. Consulte os Protocolos e empacotadores suportados para obter links para informações sobre as capacidades de cada empacotador, notas de uso e informações sobre quaisquer variáveis predefinidas que eles possam fornecer.

### Veja Também

- fopen() - Abre um arquivo ou URL
- fwrite() - Escrita binary-safe em arquivos
- file_get_contents() - Lê todo o conteúdo de um arquivo para uma string
- stream_context_create() - Cria um contexto de fluxo

# fileatime

(PHP 4, PHP 5, PHP 7, PHP 8)

fileatime — Obtém o último horário de acesso do arquivo

### Descrição

function fileatime(string `$filename`): int|false

Obtém o último horário de acesso do arquivo.

### Parâmetros

`filename`

  Caminho para o arquivo.

### Valor Retornado

Retorna o horário em que um arquivo foi acessado pela última vez, ou `false` em caso de falha. O horário é retornado como um timestamp Unix.

### Erros/Exceções

Em caso de falha, um `E_WARNING` será emitido.

### Exemplos

Exemplo #1 Exemplo de fileatime()

    <?php

    // Exibe algo como: arquivo.txt teve o último acesso em: December 29 2002 22:16:23.

    $filename = 'arquivo.txt';
    if (file_exists($filename)) {
        echo "$filename teve o último acesso em: " . date ("F d Y H:i:s.", fileatime($filename));
    }

    ?>

### Notas

> Nota:

> O horário de acesso de um arquivo deve mudar sempre os blocos de dados de um arquivo estão sendo lidos. Isto pode ser custoso do ponto de vista de desempenho quando uma aplicação acessa regularmente um grande número de arquivos ou diretórios.

> Alguns sistemas de arquivos Unix podem ser montados com atualizações de horário de acesso desabilitadas para aumentar o desempenho de tais aplicações; os spools de notícias da USENET são um exemplo comum. Nestes sistemas de arquivos esta função não terá utilidade.

> Nota: Note que a resolução de tempo pode variar de um sistema de arquivos para outro.

> Nota: Os resultados desta função são armazenados em cache. Consulte a função clearstatcache() para mais detalhes.

Dica

A partir do PHP 5.0.0, esta função também pode ser usada com alguns empacotadores de URL. Consulte os Protocolos e empacotadores suportados para determinar quais empacotadores suportam a família de funções stat().

### Veja Também

- filemtime() - Obtém o horário de modificação do arquivo
- fileinode() - Lê o inode do arquivo
- date() - Formata um timestamp Unix

# filectime

(PHP 4, PHP 5, PHP 7, PHP 8)

filectime — Obtém o horário de modificação de inode do arquivo

### Descrição

function filectime(string `$filename`): int|false

Obtém o horário de modificação do inode de um arquivo.

### Parâmetros

`filename`

  Caminho para o arquivo.

### Valor Retornado

Retorna o horário em que o arquivo foi modificado pela última vez, ou `false` em caso de falha. O horário é retornado como um timestamp Unix.

### Erros/Exceções

Em caso de falha, um `E_WARNING` será emitido.

### Exemplos

Exemplo #1 Exemplo de filectime()

    <?php

    // Exibe algo como: arquivo.txt foi modificado em: December 29 2002 22:16:23.

    $filename = 'arquivo.txt';
    if (file_exists($filename)) {
        echo "$filename foi modificado em: " . date ("F d Y H:i:s.", filectime($filename));
    }

    ?>

### Notas

> Nota:

> Nota: Na maioria dos sistemas de arquivos Unix, um arquivo é considerado modificado quando seus dados de inode são modificados; isto é, quando as permissões, proprietário, grupo ou outros metadados do inode são atualizados. Consulte também filemtime() (que é usado quando se deseja criar rodapés de páginas web do tipo "Última Modificação") e fileatime().

> Nota:

> Note também que em alguns textos sobre Unix o horário de modificação de um arquivo é definido como sendo o horário de criação do arquivo. Isto está errado. Não existe horário de criação para arquivos na maioria dos sistemas de arquivos Unix.

> Nota: Note que a resolução de tempo pode variar de um sistema de arquivos para outro.

> Nota: Os resultados desta função são armazenados em cache. Consulte a função clearstatcache() para mais detalhes.

Dica

A partir do PHP 5.0.0, esta função também pode ser usada com alguns empacotadores de URL. Consulte os Protocolos e empacotadores suportados para determinar quais empacotadores suportam a família de funções stat().

### Veja Também

- filemtime() - Obtém o horário de modificação do arquivo

# filegroup

(PHP 4, PHP 5, PHP 7, PHP 8)

filegroup — Lê o grupo do arquivo

### Descrição

function filegroup(string `$filename`): int|false

Obtém o grupo do arquivo. O ID do grupo é retornado no formato numérico, use posix_getgrgid() para resolvê-lo para um nome do grupo.

### Parâmetros

`filename`

  Caminho do arquivo.

### Valor Retornado

Retorna o group ID do arquivo, ou `false` no caso de um erro. O group ID é retornado em um formato numérico. Use posix_getgrgid() para resolver para o nome do grupo. Em caso de falha, `false` é retornado.

### Erros/Exceções

Em caso de falha. um `E_WARNING` é emitido.

### Exemplos

Exemplo #1 Descobrindo o grupo de um arquivo

    <?php
    $filename = 'index.php';
    print_r(posix_getgrgid(filegroup($filename)));
    ?>

### Notas

> Nota: Os resultados desta função são armazenados em cache. Consulte a função clearstatcache() para mais detalhes.

Dica

A partir do PHP 5.0.0, esta função também pode ser usada com alguns empacotadores de URL. Consulte os Protocolos e empacotadores suportados para determinar quais empacotadores suportam a família de funções stat().

### Veja Também

- fileowner() - Obtem o proprietário do arquivo
- posix_getgrgid() - Retorna informação sobre um grupo a partir de um ID de grupo

# fileinode

(PHP 4, PHP 5, PHP 7, PHP 8)

fileinode — Lê o inode do arquivo

### Descrição

function fileinode(string `$filename`): int|false

Obtém o inode do arquivo.

### Parâmetros

`filename`

  Caminho para o arquivo.

### Valor Retornado

Retorna o número do inode do arquivo, ou `false` em caso de falha.

### Erros/Exceções

Em caso de falha, um `E_WARNING` será emitido.

### Exemplos

Exemplo #1 Comparando o inode de um arquivo com o arquivo atual

    <?php
    $filename = 'index.php';
    if (getmyinode() == fileinode($filename)) {
        echo 'Você está verificando o arquivo atual.';
    }
    ?>

### Notas

> Nota: Os resultados desta função são armazenados em cache. Consulte a função clearstatcache() para mais detalhes.

Dica

A partir do PHP 5.0.0, esta função também pode ser usada com alguns empacotadores de URL. Consulte os Protocolos e empacotadores suportados para determinar quais empacotadores suportam a família de funções stat().

### Veja Também

- getmyinode() - Obtém o inode do script atual
- stat() - Obtém informações sobre um arquivo

# filemtime

(PHP 4, PHP 5, PHP 7, PHP 8)

filemtime — Obtém o horário de modificação do arquivo

### Descrição

function filemtime(string `$filename`): int|false

Esta função retorna o horário em que os blocos de dados de um arquivo estavam sendo escritos, isto é, o horário em que o conteúdo do arquivo foi modificado.

### Parâmetros

`filename`

  Caminho para o arquivo.

### Valor Retornado

Retorna o horário em que o arquivo foi modificado pela última vez, ou `false` em caso de falha. O horário é retornado como um timestamp Unix, que é adequado para a função date().

### Erros/Exceções

Em caso de falha, um `E_WARNING` será emitido.

### Exemplos

Exemplo #1 Exemplo de filemtime()

    <?php
    // exibe algo como: arquivo.txt foi modificado em December 29 2002 22:16:23.

    $filename = 'arquivo.txt';
    if (file_exists($filename)) {
        echo "$filename foi modificado em " . date ("F d Y H:i:s.", filemtime($filename));
    }
    ?>

### Notas

> Nota: Note que a resolução de tempo pode variar de um sistema de arquivos para outro.

> Nota: Os resultados desta função são armazenados em cache. Consulte a função clearstatcache() para mais detalhes.

Dica

A partir do PHP 5.0.0, esta função também pode ser usada com alguns empacotadores de URL. Consulte os Protocolos e empacotadores suportados para determinar quais empacotadores suportam a família de funções stat().

### Veja Também

- filectime() - Obtém o horário de modificação de inode do arquivo
- stat() - Obtém informações sobre um arquivo
- touch() - Define horário de acesso e de modificação de arquivo
- getlastmod() - Obtém o horário da última modificação na página

# fileowner

(PHP 4, PHP 5, PHP 7, PHP 8)

fileowner — Obtem o proprietário do arquivo

### Descrição

function fileowner(string `$filename`): int|false

Obtém o proprietário do arquivo.

### Parâmetros

`filename`

  Caminho para o arquivo.

### Valor Retornado

Retorna a ID do usuário do proprietário do arquivo, ou `false` em caso de falha. A ID do usuário é retornada em formato numérico, use a função posix_getpwuid() para obter o nome do usuário.

### Erros/Exceções

Em caso de falha, um `E_WARNING` será emitido.

### Exemplos

Exemplo #1 Encontrando o proprietário de um arquivo

    <?php
    $filename = 'index.php';
    print_r(posix_getpwuid(fileowner($filename)));
    ?>

### Notas

> Nota: Os resultados desta função são armazenados em cache. Consulte a função clearstatcache() para mais detalhes.

Dica

A partir do PHP 5.0.0, esta função também pode ser usada com alguns empacotadores de URL. Consulte os Protocolos e empacotadores suportados para determinar quais empacotadores suportam a família de funções stat().

### Veja Também

- filegroup() - Lê o grupo do arquivo
- stat() - Obtém informações sobre um arquivo
- posix_getpwuid() - Retorna informações sobre um usuário por ID de usuário

# fileperms

(PHP 4, PHP 5, PHP 7, PHP 8)

fileperms — Obtém permissões de arquivo

### Descrição

function fileperms(string `$filename`): int|false

Obtém as permissões para o arquivo informado.

### Parâmetros

`filename`

  Caminho para o arquivo.

### Valor Retornado

Retorna as permissões do arquivo em modo numérico. Os bits menos significativos deste modo são os mesmos das permissões esperadas por chmod(), entretanto na maioria das plataformas o valor de retorno também inclui informação sobre o tipo do arquivo informado em `filename`. Os exemplos abaixo demonstram como testar o valor de retorno para permissões e tipos de arquivos específicos em sistemas POSIX, incluindo Linux e macOS.

Para aquivos locais, o valor de retorno específico é o do membro `st_mode` da estrutura retornada pela função stat() da biblioteca C. Exatamente quais bits são definidos pode variar de plataforma para plataforma, e é recomendado consultar a documentação específica da plataforma se for necessária uma interpretação dos bits de não-permissão do valor de retorno.

Retorna `false` em caso de falha.

### Erros/Exceções

Em caso de falha, um `E_WARNING` será emitido.

### Exemplos

Exemplo #1 Mostra as permissões como um valor em octal

    <?php
    echo substr(sprintf('%o', fileperms('/tmp')), -4);
    echo substr(sprintf('%o', fileperms('/etc/passwd')), -4);
    ?>

O exemplo acima produzirá:

    1777
    0644

Exemplo #2 Mostra as permissões completas

    <?php
    $perms = fileperms('/etc/passwd');

    switch ($perms & 0xF000) {
        case 0xC000: // socket
            $info = 's';
            break;
        case 0xA000: // ligação simbólica
            $info = 'l';
            break;
        case 0x8000: // regular
            $info = 'r';
            break;
        case 0x6000: // bloco special
            $info = 'b';
            break;
        case 0x4000: // diretório
            $info = 'd';
            break;
        case 0x2000: // caractere especial
            $info = 'c';
            break;
        case 0x1000: // tubo FIFO
            $info = 'p';
            break;
        default: // desconhecido
            $info = 'u';
    }

    // Owner
    $info .= (($perms & 0x0100) ? 'r' : '-');
    $info .= (($perms & 0x0080) ? 'w' : '-');
    $info .= (($perms & 0x0040) ?
                (($perms & 0x0800) ? 's' : 'x' ) :
                (($perms & 0x0800) ? 'S' : '-'));

    // Group
    $info .= (($perms & 0x0020) ? 'r' : '-');
    $info .= (($perms & 0x0010) ? 'w' : '-');
    $info .= (($perms & 0x0008) ?
                (($perms & 0x0400) ? 's' : 'x' ) :
                (($perms & 0x0400) ? 'S' : '-'));

    // World
    $info .= (($perms & 0x0004) ? 'r' : '-');
    $info .= (($perms & 0x0002) ? 'w' : '-');
    $info .= (($perms & 0x0001) ?
                (($perms & 0x0200) ? 't' : 'x' ) :
                (($perms & 0x0200) ? 'T' : '-'));

    echo $info;
    ?>

O exemplo acima produzirá:

    -rw-r--r--

### Notas

> Nota: Os resultados desta função são armazenados em cache. Consulte a função clearstatcache() para mais detalhes.

Dica

A partir do PHP 5.0.0, esta função também pode ser usada com alguns empacotadores de URL. Consulte os Protocolos e empacotadores suportados para determinar quais empacotadores suportam a família de funções stat().

### Veja Também

- chmod() - Modifica as permissões do arquivo
- is_readable() - Diz se o arquivo existe e se ele pode ser lido
- stat() - Obtém informações sobre um arquivo

# filesize

(PHP 4, PHP 5, PHP 7, PHP 8)

filesize — Obtém o tamanho do arquivo

### Descrição

function filesize(string `$filename`): int|false

Obtém o tamanho do arquivo.

### Parâmetros

`filename`

  Caminho para o arquivo.

### Valor Retornado

Retorna o tamanho do arquivo em bytes, ou `false` (e gera um aviso `E_WARNING`) em caso de erro.

> Nota: Como o tipo inteiro do PHP possui sinal e muitas plataformas usam números inteiros de 32 bits, algumas funções do sistema de arquivos podem retornar resultados inesperados para arquivos maiores que 2GB.

### Erros/Exceções

Em caso de falha, um `E_WARNING` será emitido.

### Exemplos

Exemplo #1 Exemplo de filesize()

    <?php

    // Exibe algo como: arquivo.txt: 1024 bytes

    $filename = 'arquivo.txt';
    echo $filename . ': ' . filesize($filename) . ' bytes';

    ?>

### Notas

> Nota: Os resultados desta função são armazenados em cache. Consulte a função clearstatcache() para mais detalhes.

Dica

A partir do PHP 5.0.0, esta função também pode ser usada com alguns empacotadores de URL. Consulte os Protocolos e empacotadores suportados para determinar quais empacotadores suportam a família de funções stat().

### Veja Também

- file_exists() - Verifica se um arquivo ou diretório existe

# filetype

(PHP 4, PHP 5, PHP 7, PHP 8)

filetype — Lê o tipo do arquivo

### Descrição

function filetype(string `$filename`): string|false

Retorna o tipo do arquivo.

### Parâmetros

`filename`

  Caminho até o arquivo.

### Valor Retornado

Retorna o tipo do arquivo. Os valores possíveis são fifo, char, dir, block, link, file, socket e unknown (desconhecido).

Retorna `false` se ocorrer algum erro. filetype() também produzirá uma mensagem `E_NOTICE` se a chamada stat falhar ou se o tipo do arquivo for desconhecido.

### Erros/Exceções

Em caso de falha, um `E_WARNING` será emitido.

### Exemplos

Exemplo #1 Exemplo de filetype()

    <?php

    echo filetype('/etc/passwd');
    echo "\n";
    echo filetype('/etc/');

    ?>

O exemplo acima produzirá:

    file
    dir

### Notas

> Nota: Os resultados desta função são armazenados em cache. Consulte a função clearstatcache() para mais detalhes.

Dica

A partir do PHP 5.0.0, esta função também pode ser usada com alguns empacotadores de URL. Consulte os Protocolos e empacotadores suportados para determinar quais empacotadores suportam a família de funções stat().

### Veja Também

- is_dir() - Diz se o caminho é um diretório
- is_file() - Informa se o arquivo é um arquivo comum
- is_link() - Informa se o arquivo é uma ligação simbólica
- file_exists() - Verifica se um arquivo ou diretório existe
- mime_content_type() - Detecta o tipo de conteúdo MIME de um arquivo
- pathinfo() - Retorna informações sobre um caminho de arquivo
- stat() - Obtém informações sobre um arquivo

# flock

(PHP 4, PHP 5, PHP 7, PHP 8)

flock — Travamento consultivo portável de arquivo

### Descrição

function flock(resource `$stream`, int `$operation`, int `&$would_block` = `null`): bool

flock() permite realizar um modelo simples de leitura/escrita que pode ser usado virtualmente em qualquer plataforma (incluindo na maioria dos derivados Unix e até mesmo no Windows).

A trava é liberada também por fclose(), ou quando o fluxo `stream` sofrer coleta de lixo.

O PHP suporta uma maneira portável de travamento de arquivos completos de forma consultiva (que significa que todos programas de acesso devem usar a mesma forma de travamento ou ela não irá funcionar). Por padrão, esta função irá bloquear até que a trava solicitada seja adquirida; isto pode ser controlado com a opção `LOCK_NB` documentada abaixo.

### Parâmetros

`stream`
  Um resource de ponteiro do sistema de arquivos que normalmente é criado usando fopen().
`operation`

  `operation` deve ser uma das opções a seguir:

  - `LOCK_SH` para obter uma trava compartilhada (leitura).
  - `LOCK_EX` para obter uma trava exclusiva (escrita).
  - `LOCK_UN` para liberar uma trava (compartilhada ou exclusiva).

  É possível também adicionar `LOCK_NB` como uma máscara de bits a uma das operações acima, caso seja necessário que flock() não bloqueie durante a tentativa de travamento.

`would_block`

  O terceiro argumento opcional é definido como 1 se a trava for bloquear (condição de erro número EWOULDBLOCK).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de flock()

    <?php

    $fp = fopen("/tmp/lock.txt", "r+");

    if (flock($fp, LOCK_EX)) {  // adquire uma trava exclusiva
        ftruncate($fp, 0);      // trunca o arquivo
        rewind($fp);
        fwrite($fp, "Escreve alguma coisa aqui\n");
        fflush($fp);            // descarrega a saída antes de liberar a trava
        flock($fp, LOCK_UN);    // libera a trava
    } else {
        echo "Não foi possível obter a trava!";
    }

    fclose($fp);

    ?>

Exemplo #2 flock() usando a opção `LOCK_NB`

    <?php
    $fp = fopen('/tmp/lock.txt', 'r+');

    /* Ativa a opção LOCK_NB em uma operação LOCK_EX */
    if(!flock($fp, LOCK_EX | LOCK_NB)) {
        echo 'Não foi possível obter a trava';
        exit(-1);
    }

    /* ... */

    fclose($fp);
    ?>

### Notas

> Nota:

> flock() usa travamento mandatório no lugar de travamento consultivo no Windows. Travamento mandatório também é suportado no Linux e em sistemas operacionais baseados em System V através do mecanismo usual suportado pela chamada de sistema fcntl(): isto é, se o arquivo em questão tem a o bit de permissão setgid ligado e o bit de execução do grupo desligado. No Linux, o sistema de arquivos também precisará ser montado com a opção mand para que isto funcione.

> Nota:

> Pelo motivo de flock() requerer um ponteiro de arquivo, pode ser necessário usar um arquivo de trava especial para proteger o acesso a um aqruivo que deseja-se truncar abrindo-o em modo de escrita (com um argumento "w" ou "w+" para fopen()).

> Nota:

> Pode somente ser usado em ponteiros de arquivos retornados por fopen() para arquivos locais, ou ponteiros de arquivos que apontam para fluxo no espaço do usuário que implementam o método streamWrapper::stream_lock().

Aviso

Atribuir outro valor ao argumento `stream` em código subsequente irá liberar a trava.

Aviso

Em alguns sistemas operacionais, flock() é implementado no nível de processos. Ao usar uma API de servidor multi-tarefa pode ser que se consiga confiar em flock() para proteger arquivos contra outros scripts PHP sendo executados em tarefas parelelas da mesma instância do servidor!

flock() não é suportado em sistemas de arquivos antiquados como `FAT` e seus derivativos e portanto sempre retornará `false` nestes ambientes.

> Nota:

> No Windows, se o processo de travamento abrir o arquivo uma segunda vez, ele não poderá acessar o arquivo através deste segundo manipulador até que destrave o arquivo.

# fnmatch

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

fnmatch — Compara nome de arquivo com um padrão

### Descrição

function fnmatch(string `$pattern`, string `$filename`, int `$flags` = 0): bool

fnmatch() verifica se o parâmetro `filename` informado corresponde com o padrão de curingas shell `pattern`.

### Parâmetros

`pattern`

  O parâmetro `pattern` deve conter o padrão para correspondência. Normalmente, `pattern` conterá curingas como `'?'` e `'*'`.

  Curingas a serem usados no parâmetro `pattern`
  Curinga | Descrição
  --- | ---
  `?` | Ponto de interrogação irá corresponder a um caractere único. Por exemplo, o padrão `"file?.txt"` corresponderá a `"file1.txt"` e `"fileA.txt"`, mas não a `"file10.txt"`.
  `*` | Asteriscos corresponderá zero ou mais caracteres. Por exemplo, o padrão `"foo*.xml"` corresponderá a `"foo.xml"` e `"foobar.xml"`.
  `[ ]` | Colchetes são usados para criar intervalos de caracteres ASCII ou conjuntos de caracteres. Por exemplo, o padrão `"index.php[45]"` corresponderá a `"index.php4"` e `"index.php5"`, mas não a `"index.phpt"`. Intervalos bem conhecidos são `[0-9]`, `[a-z]` e `[A-Z]`. Conjuntos e intervalos múltiplos podem ser usados ao mesmo tempo, por exemplo `[0-9a-zABC]`.
  `!` | Ponto de exclamação é usado para negar caracteres dentro de colchetes. Por exemplo, `"[!A-Z]*.html"` corresponderá a `"demo.html"`, mas não a `"Demo.html"`.
  `\` | Barra invertida é usada para escapar caracteres especiais. Por exemplo, `"Name\?"` corresponderá a `"Name?"`, mas não a `"Names"`.

`filename`

  A string testada. Esta função é especialmente útil para nomes de arquivo, mas também pode ser usada em strings normais.

  O usuário comum pode estar acostumado com padrões shell ou pelo menos, na sua forma mais simples, aos curingas `'?'` e `'*'`. Então usar fnmatch() ao invés de preg_match() para entrada de expressões de busca na interface com o usuário pode ser muito mais conveniente para não programadores.

`flags`

  O valor do parâmetro `flags` pode ser qualquer combinação das opções a seguir, unidos com o operador binário OR (|).

  Uma lista de opções possíveis para fnmatch()
  `Flag` | Descrição
  --- | ---
  `FNM_NOESCAPE` | Desabilita escape por barra invertida.
  `FNM_PATHNAME` | Barra na string somente corresponde a barra no padrão fornecido.
  `FNM_PERIOD` | Um ponto no início da string deve corresponder a exatamente um ponto no padrão fornecido.
  `FNM_CASEFOLD` | Não diferencia maiúsculas de minúsculas. Parte da extensão GNU.

### Valor Retornado

Retorna `true` se houver correspondência, `false` caso contrário.

### Exemplos

Exemplo #1 Comparando uma cor com um padrão de curingas shell

    <?php
    if (fnmatch("*gr[ae]y", $color)) {
      echo "alguma forma de cinza (grey ou gray) ...";
    }
    ?>

### Notas

Aviso

Por enquanto esta função não está disponível em sistemas não-POSIX exceto pelo Windows.

### Veja Também

- glob() - Encontra caminhos que combinam com uma expressão
- preg_match() - Realiza uma correspondência com expressão regular
- sscanf() - Interpreta a entrada de uma string de acordo com um formato
- printf() - Envia uma string formatada para a saída
- sprintf() - Retona uma string formatada

# fopen

(PHP 4, PHP 5, PHP 7, PHP 8)

fopen — Abre um arquivo ou URL

### Descrição

function fopen(
string `$filename`,
string `$mode`,
bool `$use_include_path` = `false`,
?resource `$context` = `null`
): resource|false

fopen() conecta um recurso nomeado, especificado por `filename`, a um fluxo.

### Parâmetros

`filename`

  Se `filename` estiver na forma de "esquema://...", assume-se que seja uma URL, e o PHP buscará por um manipulador de protocolo (também conhecido como empacotador) para aquele esquema. Se nenhum empacotador para aquele protocolo estiver registrado, o PHP emitirá uma aviso para auxiliar no rastreio de potenciais problemas no script, e então continuará presumindo que `filename` especifica um arquivo normal.

  Se o PHP decidiu que `filename` se refere a um arquivo local, então ele tentará abrir um fluxo para aquele arquivo. O arquivo precisa ser acessível pelo PHP, portanto é necessário garantir que as permissões de acesso do arquivo possibilitem este acesso. Se estiver habilitado open_basedir, outras restrições podem se aplicar.

  Se o PHP decidiu que `filename` se refere a um protocolo registrado e esse protocolo estiver registrado como uma URL de rede, o PHP irá verificar para ter certeza que allow_url_fopen está habilitado. Se não estiver, o PHP emitirá um alerta e a chamada a fopen() irá falhar.

  > Nota:

  > A lista de protocolos suportados pode ser encontrada em Protocolos e empacotadores suportados. Alguns protocolos (também mencionados como empacotadores - `wrappers`) suportam `context` e/ou opções do php.ini. Recorra à página específica do protocolo em uso para uma lista das opções que podem ser definidas. (ex.: o valor php.ini `user_agent` utilizado pelo protocolo `http`).

  Na plataforma Windows, tenha cuidado de escapar qualquer barra invertida usada no caminho do arquivo, ou use barras normais.

      <?php
      $handle = fopen("c:\\data\\info.txt", "r");
      ?>

`mode`

  O parâmetro `mode` especifica o tipo de acesso que você precisa ao fluxo. Pode ser um dos seguintes:

  Lista dos possíveis modos de fopen() utilizando `mode`
  `mode` | Descrição
  --- | ---
  `'r'` | Abre somente para leitura; coloca o ponteiro do arquivo no começo do arquivo.
  `'r+'` | Abre para leitura e escrita; coloca o ponteiro do arquivo no começo do arquivo.
  `'w'` | Abre somente para escrita; coloca o ponteiro do arquivo no começo do arquivo e reduz o comprimento do arquivo para zero. Se o arquivo não existir, tenta criá-lo.
  `'w+'` | Abre para leitura e escrita; fora isso, tem o mesmo comportamento de `'w'`.
  `'a'` | Abre somente para escrita; coloca o ponteiro do arquivo no final do arquivo. Se o arquivo não existir, tenta criá-lo. Neste modo, fseek() não tem efeito, a escrita é sempre adicionada.
  `'a+'` | Abre para leitura e escrita; coloca o ponteiro do arquivo no final do arquivo. Se o arquivo não existir, tenta criá-lo. Neste modo, fseek() somente afeta a posição de leitura, escrita é sempre adicionada.
  `'x'` | Cria e abre o arquivo somente para escrita; coloca o ponteiro no começo do arquivo. Se o arquivo já existir, a chamada a fopen() falhará, retornando `false` e gerando um erro de nível `E_WARNING`. Se o arquivo não existir, tenta criá-lo. Isto é equivalente a especificar as opções `O_EXCL|O_CREAT` para a chamada de sistema `open(2)` subjacente.
  `'x+'` | Cria e abre o arquivo para leitura e escrita; fora isso, tem o mesmo comportamento de `'x'`.
  `'c'` | Abre o arquivo somente para escrita. Se o arquivo não existir, ele é criado. Se existir, ele não é truncado (ao contrário de `'w'`) e nem a chamada a esta função falha (como no caso de `'x'`). O ponteiro é posicionado no início do arquivo. Isto pode ser útil se for desejado obter uma trava consultiva (consulte flock()) antes de tentar modificar o arquivo, já que usar `'w'` poderia trincar o arquivo antes que a trava fosse obtida (se o truncamento for desejado, ftruncate() pode ser usando depois que a trava for requisitada).
  `'c+'` | Abre o arquivo para leitura e escrita; fora isso, tem o mesmo comportamento de `'c'`.
  `'e'` | Define a opção close-on-exec no descritor do arquivo aberto. Somente disponível no PHP compilado em sistemas compatíveis com POSIX.1-2008.
  `'n'` | Define o sinalizador não bloqueante no descritor de arquivo aberto. Disponível apenas no PHP compilado em sistemas compatíveis com POSIX.1-2008.

  > Nota:

  > Diferentes famílias de sistemas operacionais têm diferentes convenções de final de linha. Quando um arquivo texto é escrito e deseja-se inserir uma quebra de linha, é necessário usar o caractere correto de fim de linha para o sistema operacional. Sistemas baseados no Unix utilizam `\n` como o caractere de fim de linha, sistemas baseados no Windows utilizam `\r\n` e sistemas baseados no Macintosh (Mac OS Classic) utilizavam `\r`.

  > Se forem usados os caracteres de fim de linha inadequados em seus arquivos, pode ser que esses arquivos "parecer estranhos" quando forem abertos em outras aplicações.

  > O Windows oferece uma opção de tradução do modo texto (`'t'`) que traduz, transparentemente, `\n` para `\r\n` quando estiver trabalhando com o arquivo. Em contraste, pode-se também utilizar `'b'` para forçar o modo binário, que não irá traduzir os dados. Para usar essas opções, especifique `'b'` ou `'t'` como o último caractere do parâmetro `mode`.

  > O modo de tradução padrão é `'b'`. Pode-se usar o modo `'t'` ao trabalhar com arquivos texto e usar `\n` para delimitar as linhas no script, de forma que pode-se esperar que eles sejam lidos em aplicações como versões antigas do bloco de notas. Deve-se usar `'b'` em todos os outros casos.

  > Se for especificada a opção 't' ao trabalhar com arquivos binários, pode-se experimentar problemas estranhos com os dados, incluindo arquivos de imagens corrompidos e problemas estranhos com os caracteres `\r\n`.

  > Nota:

  > Para portabilidade, é fortemente recomendado que se reescreva códigos que usem ou dependam do modo `'t'` de forma que passem a usar o fim de linha correto e o modo `'b'` em seu lugar.

  > Nota: O parâmetro `mode` é ignorado para os empacotadores de fluxo php://output, php://input, php://stdin, php://stdout, php://stderr e php://fd.

`use_include_path`

  O terceiro parâmetro opcional `use_include_path` pode ser definido `true` se for desejado buscar o arquivo também no include_path.

`context`
  Um resource de contexto de fluxo.

### Valor Retornado

Retorna um recurso de ponteiro de arquivo em caso de sucesso, ou `false` em caso de falha

### Erros/Exceções

Em caso de falha, um `E_WARNING` será emitido.

### Registro de Alterações

Versão | Descrição
--- | ---
7.0.16, 7.1.2 | A opção `'e'` foi adicionada.

### Exemplos

Exemplo #1 Exemplos de fopen()

    <?php
    $handle = fopen("/home/rasmus/file.txt", "r");
    $handle = fopen("/home/rasmus/file.gif", "wb");
    $handle = fopen("http://www.example.com/", "r");
    $handle = fopen("ftp://user:password@example.com/somefile.txt", "w");
    ?>

### Notas

Aviso

Ao usar SSL, o Microsoft IIS violará o protocolo fechando a conexão sem enviar uma notificação `close_notify`. O PHP reportará isso como "SSL: Fatal Protocol Error" quando chegar ao final dos dados. Para contornar isso, o valor de error_reporting deve ser reduzido a um nível que não inclua avisos. O PHP pode detectar servidores IIS defeituosos quando o fluxo é aberto usando o empacotador `https://` e suprimirá o aviso. Ao usar fsockopen() para criar um soquete `ssl://`, o desenvolvedor é responsável por detectar e suprimir este aviso.

> Nota:

> Se houver problemas com leitura e gravação de arquivos e a versão de módulo de servidor do PHP estiver sendo usada, deve-se garantir que os arquivos e diretórios sendo usados são acessíveis ao processo do servidor.

> Nota:

> Esta função também pode ter sucesso quando `filename` for um diretório. Se não houver certeza se `filename` é um arquivo ou um diretório, pode ser necessário usar a função is_dir() antes de chamar fopen().

### Veja Também

- Protocolos e empacotadores suportados
- fclose() - Fecha um ponteiro de arquivo aberto
- fgets() - Lê uma linha de um ponteiro de arquivo
- fread() - Leitura de arquivo segura para binário
- fwrite() - Escrita binary-safe em arquivos
- fsockopen() - Abre uma conexão socket de domínio Unix ou de Internet
- file() - Lê todo o arquivo para um array
- file_exists() - Verifica se um arquivo ou diretório existe
- is_readable() - Diz se o arquivo existe e se ele pode ser lido
- stream_set_timeout() - Define o limite de tempo em um fluxo
- popen() - Abre um processo como ponteiro de arquivo
- stream_context_create() - Cria um contexto de fluxo
- umask() - Modificar a umask atual
- SplFileObject

# fpassthru

(PHP 4, PHP 5, PHP 7, PHP 8)

fpassthru — Imprime todos os dados restantes de um ponteiro de arquivo

### Descrição

function fpassthru(resource `$stream`): int

Lê até o fim do arquivo (EOF) do ponteiro de arquivo dado e imprime os resultados para a buffer de saída.

Pode ser necessário chamar rewind() para redefinir o ponteiro do arquivo para início do arquivo se dados já tiverem sido escritos no arquivo.

Se for desejado apenas descarregar o conteúdo de um arquivo para o buffer de saída, sem primeiro modificá-lo ou deslocar o ponteiro até uma posição, pode-se usar a função readfile(), que vai economizar uma chamada à função fopen().

### Parâmetros

`stream`
  O ponteiro de arquivo deve ser válido e deve apontar para um arquivo aberto com sucesso por fopen() ou fsockopen() (e ainda não fechado por fclose()).

### Valor Retornado

Retorna o número de caracteres lidos do fluxo `stream` e passados para a saída.

### Exemplos

Exemplo #1 Usando fpassthru() com arquivo binário

    <?php

    // Abre o arquivo em modo binário
    $name = './img/ok.png';
    $fp = fopen($name, 'rb');

    // Envia os cabeçalhos
    header("Content-Type: image/png");
    header("Content-Length: ".filesize($name));

    // Manda a imagem e para o script
    fpassthru($fp);
    exit;

    ?>

### Notas

> Nota:

> Ao utilizar fpassthru() em um arquivo binário em sistemas Windows, assegure-se de abrir o arquivo em modo binário, acrescentando um `b` ao modo informado na chamada a fopen().

> Recomenda-se utilizar o modo `b` ao lidar com arquivos binários, mesmo que seu sistema não exiga isso, de forma que seus scripts se tornem mais portáveis.

### Veja Também

- readfile() - Exibe o conteúdo de um arquivo
- fopen() - Abre um arquivo ou URL
- popen() - Abre um processo como ponteiro de arquivo
- fsockopen() - Abre uma conexão socket de domínio Unix ou de Internet

# fputcsv

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

fputcsv — Formata a linha como CSV e a escreve em um ponteiro de arquivo

### Descrição

function fputcsv(
resource `$stream`,
array `$fields`,
string `$separator` = ",",
string `$enclosure` = "\"",
string `$escape` = "\\",
string `$eol` = "\n"
): int|false

fputcsv() formata uma linha (passada como um array de campos `fields`) como CSV e a escreve (terminando com uma nova linha `eol`) no fluxo de arquivo especificado por `stream`.

### Parâmetros

`stream`
  O ponteiro de arquivo deve ser válido e deve apontar para um arquivo aberto com sucesso por fopen() ou fsockopen() (e ainda não fechado por fclose()).
`fields`

  Um array de strings.

`separator`

  O parâmetro `separator` define o delimitador de campo. Precisa ser um caractere de um byte.

`enclosure`

  O parâmetro `enclosure` define o caractere que cerca um campo. Precisa ser um caractere de um byte.

`escape`

  O parâmetro `escape` define o caractere de escape. Precisa ser um caractere de um byte ou uma string vazia. Uma string vazia (`""`) desabilita o mecanismo de escape proprietário.

  Aviso

  No fluxo de entrada, o caractere `enclosure` sempre pode ser escapado por duplicação dentro de uma string delimitada, resultando em um único caractere `enclosure` no resultado interpretado. O caractere `escape` funciona de forma diferente: Se uma sequência de caracteres `escape` e `enclosure` aparecerem no fluxo, ambos os caracteres estarão presentes no valor interpretado. Portanto, para os parâmetros padrão, uma linha CSV como `"a""b","c\"d"` terá os campos interpretados como `a"b` e `c\"d`, respectivamente.

  Aviso

  A partir do PHP 8.4.0, depender do valor padrão de `escape` foi descontinuado. Ele precisa ser fornecido explicitamente tanto por posição quanto pelo uso de argumentos nomeados.

`eol`

  O parâmetro opcional `eol` define uma sequência customizada de Fim de Linha.

Aviso

Quando o parâmetro `escape` for definido para algo diferente de uma string vazia (`""`), isso pode resultar em um CSV que não esteja conforme a » RFC 4180 ou que não seja capaz de sobreviver a uma viagem de ida e volta através das funções CSV do PHP. O padrão para `escape` é `"\\"`, portanto é recomendado defini-lo explicitamente para a string vazia. O valor padrão será alterado em uma versão futura do PHP, mas não antes do PHP 9.0.

> Nota:

> Se um caractere `enclosure` estiver contido em um campo, ele sofrerá escape por duplicação, a menos que seja imediatamente precedido por um `escape`.

### Valor Retornado

Retorna o comprimento da string escrita ou `false` em caso de falha.

### Erros/Exceções

Lança uma ValueError se `separator` ou `enclosure` não tiver comprimento de um byte.

Lança uma ValueError se `escape` não tiver comprimento de um byte ou se for uma string vazia.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Depender do valor padrão de `escape` agora está descontinuado.
8.1.0 | O parâmetro opcional `eol` foi adicionado.
7.4.0 | O parâmetro `escape` agora aceita uma string vazia para desabilitar o mecanismo de escape proprietário.

### Exemplos

Exemplo #1 Exemplo da fputcsv()

    <?php

    $lista = [
        ['aaa', 'bbb', 'ccc', 'dddd'],
        ['123', '456', '789'],
        ['"aaa"', '"bbb"']
    ];

    $fp = fopen('file.csv', 'w');

    foreach ($lista as $linha) {
        fputcsv($fp, $linha, ',', '"', '');
    }

    fclose($fp);
    ?>

O exemplo acima irá escrever o seguinte no arquivo `file.csv`:

    aaa,bbb,ccc,dddd
    123,456,789
    """aaa""","""bbb"""

### Veja Também

- fgetcsv() - Lê uma linha do ponteiro de arquivos e a interpreta como campos CSV
- str_getcsv() - Analisa uma string CSV e retorna os dados em um array
- SplFileObject::fgetcsv() - Obtém linha do arquivo e interpreta como campos CSV
- SplFileObject::fputcsv() - Escreve um array de campos como uma linha CSV
- SplFileObject::setCsvControl() - Definir o delimitador, o encapsulador e o caractere de escape para CSV
- SplFileObject::getCsvControl() - Obtém o delimitador, o caractere de fechamento e o caractere de escape para CSV

# fputs

(PHP 4, PHP 5, PHP 7, PHP 8)

fputs — Sinônimo de fwrite()

### Descrição

Esta função é um apelido para: fwrite().

# fread

(PHP 4, PHP 5, PHP 7, PHP 8)

fread — Leitura de arquivo segura para binário

### Descrição

function fread(resource `$stream`, int `$length`): string|false

fread() lê até `length` bytes do ponteiro de arquivo informado em `stream`. A leitura é interrompida quando uma das seguintes condições são satisfeitas:

- `length` bytes foram lidos
- EOF (final do arquivo) é alcançado
- um pacote tornou-se disponível ou o limite de tempo de socket foi atingido (para fluxos de rede)
- se o fluxo é lido com buffer e não representa um arquivo, é realizada no máximo uma leitura de até o número de bytes igual ao tamanho do bloco (normalmente 8192); dependendo dos dados previamente armazenados em buffer, o tamanho dos dados retornados pode ser maior que o tamanho do bloco.

### Parâmetros

`stream`
  Um resource de ponteiro do sistema de arquivos que normalmente é criado usando fopen().
`length`

  Limite de até `length` bytes lidos.

### Valor Retornado

Retorna a string lida ou `false` em caso de falha.

### Exemplos

Exemplo #1 Um simples exemplo de fread()

    <?php
    // lê o conteúdo do arquivo para uma string
    $filename = "/usr/local/qualquer.txt";
    $handle = fopen ($filename, "r");
    $conteudo = fread ($handle, filesize ($filename));
    fclose ($handle);
    ?>

Exemplo #2 Exemplo de fread() binário

Aviso

Em sistemas que diferenciam entre arquivos binários e texto (por exemplo Windows) o arquivo tem que ser aberto com 'b' incluído no parâmetro 'mode' da função fopen().

    <?php
    $filename = "c:\\files\\figura.gif";
    $handle = fopen ($filename, "rb");
    $conteudo = fread ($handle, filesize ($filename));
    fclose ($handle);
    ?>

Exemplo #3 Exemplos de fread() remoto

Aviso

Ao ler de qualquer coisa que não seja um arquivo local comum, tal como de fluxos retornados ao ler arquivos remotos, ou de popen() e fsockopen(), a leitura irá parar depois que um pacote estiver disponível. Isto significa que deve-se juntar os dados em blocos como demonstrado nos exemplos abaixo.

    <?php
    $handle = fopen("http://www.example.com/", "rb");
    $contents = stream_get_contents($handle);
    fclose($handle);
    ?>

    <?php
    $handle = fopen("http://www.example.com/", "rb");
    if (FALSE === $handle) {
        exit("Falha ao abrir fluxo para a URL");
    }

    $contents = '';

    while (!feof($handle)) {
        $contents .= fread($handle, 8192);
    }
    fclose($handle);
    ?>

### Notas

> Nota:

> Se for desejado apenas obter o conteúdo de um arquivo para uma string, utilize file_get_contents() que tem um desempenho muito melhor que o código acima.

> Nota:

> Note que fread() lê da posição atual do ponteiro de arquivo. Use ftell() para encontrar a posição atual do ponteiro e rewind() para retroceder a posição do ponteiro.

### Veja Também

- fwrite() - Escrita binary-safe em arquivos
- fopen() - Abre um arquivo ou URL
- fsockopen() - Abre uma conexão socket de domínio Unix ou de Internet
- popen() - Abre um processo como ponteiro de arquivo
- fgets() - Lê uma linha de um ponteiro de arquivo
- fgetss() - Ler uma linha de um ponteiro de arquivo e retira as tags HTML
- fscanf() - Interpreta a leitura de um arquivo de acordo com um formato
- file() - Lê todo o arquivo para um array
- fpassthru() - Imprime todos os dados restantes de um ponteiro de arquivo
- fseek() - Aponta para uma posição no arquivo
- ftell() - Retorna a posição atual do ponteiro de leitura/gravação do arquivo
- rewind() - Retrocede a posição de um ponteiro de arquivos
- unpack() - Desempacota dados de uma string binária

# fscanf

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

fscanf — Interpreta a leitura de um arquivo de acordo com um formato

### Descrição

function fscanf(resource `$stream`, string `$format`, mixed `&...$vars`): array|int|false|null

A função fscanf() é semelhante à sscanf(), mas usa como entrada um arquivo associado com o fluxo `stream` e interpreta a entrada de acordo com o especificado em `format`.

Qualquer espaço em branco na string do formato corresponde a quaisquer espaços em branco no fluxo de entrada. Isto significa que até mesmo uma tabulação (`\t`) na string do formato pode corresponder a um único caractere de espaço no fluxo de entrada.

Cada chamada a fscanf() lê uma linha do arquivo.

### Parâmetros

`stream`
  Um resource de ponteiro do sistema de arquivos que normalmente é criado usando fopen().
`format`

  O formato interpretado para `string`, que é descrito na documentação para sprintf() com as seguintes diferenças:

  - A função não reconhece a localidade.
  - `F`, `g`, `G` e `b` não são suportados.
  - `D` significa número decimal.
  - `i` significa inteiro com detecção de base.
  - `n` representa o número de caracteres processados até o momento.
  - `s` pára de ler em qualquer caractere de espaço em branco.
  - `*` em vez de `argnum$` suprime a atribuição desta especificação de conversão.
`vars`
  Os valores opcionais atribuídos.

### Valor Retornado

Se somente dois parâmetros forem passados a esta função, os valores interpretados serão retornados como um array. Do contrário, se parâmetros opcionais forem passados, a função retornará o número de valores atribuídos. Os parâmetros opcionais devem ser passados por referência.

Se houver mais substrings esperadas no parâmetro `format` do que estiverem disponíveis na `string`, `null` será retornado. Para outros erros, `false` será retornado.

Quando parâmetros opcionais são usados e o fim da entrada lida de `stream` é alcançado antes que qualquer valor tenha sido interpretado, `-1` é retornado.

### Exemplos

Exemplo #1 Exemplo de fscanf()

    <?php
    $handle = fopen("users.txt", "r");
    while ($userinfo = fscanf($handle, "%s\t%s\t%s\n")) {
        list ($name, $profession, $countrycode) = $userinfo;
        //... faz algo com os valores
    }
    fclose($handle);
    ?>

Exemplo #2 Conteúdo de users.txt

    javier  argonaut        pe
    hiroshi sculptor        jp
    robert  slacker us
    luigi   florist it

### Veja Também

- fread() - Leitura de arquivo segura para binário
- fgets() - Lê uma linha de um ponteiro de arquivo
- fgetss() - Ler uma linha de um ponteiro de arquivo e retira as tags HTML
- sscanf() - Interpreta a entrada de uma string de acordo com um formato
- printf() - Envia uma string formatada para a saída
- sprintf() - Retona uma string formatada

# fseek

(PHP 4, PHP 5, PHP 7, PHP 8)

fseek — Aponta para uma posição no arquivo

### Descrição

function fseek(resource `$stream`, int `$offset`, int `$whence` = `SEEK_SET`): int

Modifica o indicador de posição do arquivo referenciado por `stream`. A nova posição, medida em bytes a partir do início do arquivo, é obtida ao adicionar `offset` à posição especificada por `whence`.

Geralmente é permitido apontar para além do fim-do-arquivo; se algum dado for então escrito, leituras além de qualquer região escrita entre o fim-do-arquivo e a região desejada irão trazer bytes com valor 0. Entretanto, alguns fluxos podem não suportar esse comportamento, especialmente quando têm definido um tamanho de armazenamento fixo.

### Parâmetros

`stream`
  Um resource de ponteiro do sistema de arquivos que normalmente é criado usando fopen().
`offset`

  A posição.

  Para apontar para uma posição anterior ao fim-do-arquivo, um valor negativo em `offset` deve ser passado e o parâmetro `whence` deve ser definido para `SEEK_END`.

`whence`

  Valores de `whence` são:

  - `SEEK_SET` - Define a posição igual ao número de bytes informado em `offset` desde o início do arquivo.
  - `SEEK_CUR` - Define a posição para a localização atual mais o número de bytes informado em `offset`.
  - `SEEK_END` - Define a posição para o final do arquivo mais o número de bytes informado em `offset`.

### Valor Retornado

Em caso de sucesso, retorna `0`; caso contrário, retorna `-1`.

Aviso

Esta função foi criada para imitar a função de mesmo nome da linguagem C. Atenção aos valores de retorno, pois eles diferem do esperado no PHP.

### Exemplos

Exemplo #1 Exemplo de fseek()

    <?php

    $fp = fopen('arquivo.txt');

    // lê alguns dados
    $data = fgets($fp, 4096);

    // move de volta para o inicio do arquivo
    // o mesmo que rewind($fp);
    fseek($fp, 0);

    ?>

### Notas

> Nota:

> Se o arquivo foi aberto em modo de adição (`a` ou `a+`), quaisquer dados que sejam escritos no arquivo serão sempre acrescentados ao final, independente da posição do arquivo, e o resultado da chamada a fseek() será indefinido.

> Nota:

> Nem todos os fluxos suportam pesquisa. Para aqueles que não suportam, pesquisas além da posição atual podem ser feitas através da leitura e descarte de dados; outras formas de pesquisa irão falhar.

### Veja Também

- ftell() - Retorna a posição atual do ponteiro de leitura/gravação do arquivo
- rewind() - Retrocede a posição de um ponteiro de arquivos

# fstat

(PHP 4, PHP 5, PHP 7, PHP 8)

fstat — Lê informações sobre um arquivo usando um ponteiro de arquivo aberto

### Descrição

function fstat(resource `$stream`): array|false

Obtêm estatísticas do arquivo aberto pelo ponteiro de arquivos `stream`. Esta função é similar à função stat() exceto que ela opera em um ponteiro de arquivo aberto ao invés de um nome de arquivo.

### Parâmetros

`stream`
  Um resource de ponteiro do sistema de arquivos que normalmente é criado usando fopen().

### Valor Retornado

Retorna um array com as estatísticas de um arquivo. O formato do array é descrito em detalhes na página do manual sobre stat(). Returns `false` on failure.

### Exemplos

Exemplo #1 Exemplo fstat()

    <?php

    // abre um arquivo
    $fp = fopen("/etc/passwd", "r");

    // colhe as estatísticas
    $fstat = fstat($fp);

    // fecha o arquivo
    fclose($fp);

    // imprime somente a parte de índices associativos
    print_r(array_slice($fstat, 13));

    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [dev] => 771
        [ino] => 488704
        [mode] => 33188
        [nlink] => 1
        [uid] => 0
        [gid] => 0
        [rdev] => 0
        [size] => 1114
        [atime] => 1061067181
        [mtime] => 1056136526
        [ctime] => 1056136526
        [blksize] => 4096
        [blocks] => 8
    )

### Notas

> Nota: Esta função não funcionará em arquivos remotos, pois o arquivo a ser examinado deve ser acessível através do sistema de arquivos do servidor.

# fsync

(PHP 8 >= 8.1.0)

fsync — Sincroniza mudanças ao arquivo (incluindo metadados)

### Descrição

function fsync(resource `$stream`): bool

Este função sincroniza mudanças ao arquivo, incluindo seus metadados. Isto é semelhante a fflush(), mas também instrui o sistema operacional a escrever na mídia de armazenamento.

### Parâmetros

`stream`
  O ponteiro de arquivo deve ser válido e deve apontar para um arquivo aberto com sucesso por fopen() ou fsockopen() (e ainda não fechado por fclose()).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de fsync()

    <?php

    $file = 'test.txt';

    $stream = fopen($file, 'w');
    fwrite($stream, 'dados de teste');
    fwrite($stream, "\r\n");
    fwrite($stream, 'dados adicionais');

    fsync($stream);
    fclose($stream);
    ?>

### Veja Também

- fdatasync() - Sincroniza dados (mas não metadados) ao arquivo
- fflush() - Força a liberação do buffer para um arquivo

# ftell

(PHP 4, PHP 5, PHP 7, PHP 8)

ftell — Retorna a posição atual do ponteiro de leitura/gravação do arquivo

### Descrição

function ftell(resource `$stream`): int|false

Retorna a posição do ponteiro do arquivo referenciado por `stream`.

### Parâmetros

`stream`

  O ponteiro de arquivo precisa ser válido, e deve apontar para um arquivo aberto com sucesso por fopen() ou popen(). ftell() dá resultados indefinidos para fluxos no modo de acréscimo (abertos com a opção "a").

### Valor Retornado

Retorna a posição do ponteiro do arquivo referenciado por `stream` como um inteiro; isto é, seu deslocamento no fluxo do arquivo.

Se um erro ocorrer, retorna `false`.

> Nota: Como o tipo inteiro do PHP possui sinal e muitas plataformas usam números inteiros de 32 bits, algumas funções do sistema de arquivos podem retornar resultados inesperados para arquivos maiores que 2GB.

### Exemplos

Exemplo #1 Exemplo de ftell()

    <?php

    // abre o arquivo e lê alguns dados
    $fp = fopen("/etc/passwd", "r");
    $data = fgets($fp, 12);

    // onde estamos?
    echo ftell($fp); // 11

    fclose($fp);

    ?>

### Veja Também

- fopen() - Abre um arquivo ou URL
- popen() - Abre um processo como ponteiro de arquivo
- fseek() - Aponta para uma posição no arquivo
- rewind() - Retrocede a posição de um ponteiro de arquivos

# ftruncate

(PHP 4, PHP 5, PHP 7, PHP 8)

ftruncate — Trunca um arquivo a um tamanho especificado

### Descrição

function ftruncate(resource `$stream`, int `$size`): bool

Toma o ponteiro de arquivo `stream` e trunca o arquivo para o comprimento definido em `size`.

### Parâmetros

`stream`

  O ponteiro do arquivo.

  > Nota:

  > O fluxo `stream` deve estar aberto para escrita.

`size`

  O tamanho para o qual será truncado.

  > Nota:

  > Se o parâmetro `size` for maior que o arquivo, o arquivo será estendido com bytes nulos.

  > Se o parâmetro `size` for menor que o arquivo, o arquivo será truncado para este tamanho.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de truncamento de arquivo

    <?php
    $filename = 'lorem_ipsum.txt';

    $handle = fopen($filename, 'r+');
    ftruncate($handle, rand(1, filesize($filename)));
    rewind($handle);
    echo fread($handle, filesize($filename));
    fclose($handle);
    ?>

### Notas

> Nota:

> O ponteiro do arquivo não é alterado.

### Veja Também

- fopen() - Abre um arquivo ou URL
- fseek() - Aponta para uma posição no arquivo

# fwrite

(PHP 4, PHP 5, PHP 7, PHP 8)

fwrite — Escrita binary-safe em arquivos

### Descrição

function fwrite(resource `$stream`, string `$data`, ?int `$length` = `null`): int|false

fwrite() grava o conteúdo de `data` no ponteiro de arquivo informado em `stream`.

### Parâmetros

`stream`
  Um resource de ponteiro do sistema de arquivos que normalmente é criado usando fopen().
`data`

  A string a ser escrita.

`length`

  Se `length` for um int, a escrita irá parar depois que`length` forem escritos, ou o o fim de `data` for alcançado, o que ocorrer primeiro.

### Valor Retornado

fwrite() retorna o número de bytes escritos, ou `false` em caso de falha.

### Erros/Exceções

fwrite() emite um `E_WARNING` em caso falhas.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `length` pode ser null.

### Exemplos

Exemplo #1 Exemplo de fwrite()

    <?php
    $filename = 'test.txt';
    $somecontent = "Acrescente isso no arquivo\n";

    // Vamos garantir que o arquivo existe e pode ser escrito
    if (is_writable($filename)) {

        // Nesse exemplo estamos abrindo o $filename em modo append.
        // O ponteiro do arquivo estará no final do arquivo
        // e portanto é aqui que $somecontent será posicionado pelo fwrite().
        if (!$fp = fopen($filename, 'a')) {
             echo "Erro ao abrir o ($filename)";
             exit;
        }

        // Escrever alguma coisa no arquivo.
        if (fwrite($fp, $somecontent) === FALSE) {
            echo "Erro ao escrever no arquivo ($filename)";
            exit;
        }

        echo "Sucesso, escrito ($somecontent) no arquivo ($filename)";

        fclose($fp);

    } else {
        echo "O arquivo não permite escrita";
    }
    ?>

### Notas

> Nota:

> Escrever em um fluxo de rede pode acabar antes de toda a string ser transmitida. O retorno de fwrite() precisa ser inspecionado:

>     <?php
>     function fwrite_stream($fp, $string) {
>         for ($written = 0; $written < strlen($string); $written += $fwrite) {
>             $fwrite = fwrite($fp, substr($string, $written));
>             if ($fwrite === false) {
>                 return $written;
>             }
>         }
>         return $written;
>     }
>     ?>

> Nota:

> Em sistemas que diferenciam entre arquivos binários e texto (por exemplo Windows) o arquivo tem que ser aberto com 'b' incluído no parâmetro 'mode' na fopen().

> Nota:

> Se o `stream` foi aberto com fopen() em modo de adição, escritas com fwrite() são atômicas (a não ser que o tamanho da `data` exceda o tamanho de bloco do sistema de arquivos, em algumas plataformas, e contanto que o arquivo esteja em um sistema de arquivos local). Sendo assim, não há necessidade de bloquear um recurso com flock() antes de chamar fwrite(); todos os dados serão escritos sem interrupção.

> Nota:

> Se escrever duas vezes no ponteiro do arquivo, então a informação será adicionado ao final do contéudo do arquivo:

>     <?php
>     $fp = fopen('data.txt', 'w');
>     fwrite($fp, '1');
>     fwrite($fp, '23');
>     fclose($fp);

>     // O conteúdo de 'data.txt' é 123, e não 23
>     ?>

### Veja Também

- fread() - Leitura de arquivo segura para binário
- fopen() - Abre um arquivo ou URL
- fsockopen() - Abre uma conexão socket de domínio Unix ou de Internet
- popen() - Abre um processo como ponteiro de arquivo
- file_get_contents() - Lê todo o conteúdo de um arquivo para uma string
- pack() - Empacota dados em uma string binária

# glob

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

glob — Encontra caminhos que combinam com uma expressão

### Descrição

function glob(string `$pattern`, int `$flags` = 0): array|false

A função glob() procura por todos os caminhos que correspondem à expressão em `pattern` de acordo com as regras usadas pela função glob() da libc, que é semelhante às regras usadas por shells comuns.

O comportamento em sistemas Unix e macOS é determinado pela implementação de glob() no sistema. No Windows, é usada uma implementação que está em conformidade com a definição POSIX 1003.2 para glob() e inclui uma extensão para lidar com a convenção `[!...]` para negar um intervalo.

### Parâmetros

`pattern`

  O padrão. Não é feita nenhuma expansão de til ou substituição de parâmetros.

  Caracteres especiais:

  - `*` - Corresponde a zero ou mais caracteres.
  - `?` - Corresponde a exatamente um caractere (qualquer caractere).
  - `[...]` - Corresponde a um caractere de um grupo de caracteres. Se o primeiro caractere for `!`, corresponde a qualquer caractere que não estiver no grupo.
  - `{a,b,c}` - Corresponde a uma string de um grupo de strings delimitadas por vírgula quando a opção `GLOB_BRACE` for usada.
  - `\` - Faz escape no caractere seguinte, exceto quando a opção `GLOB_NOESCAPE` for usada.
`flags`

  Umas das constantes `GLOB_*`.

### Valor Retornado

Retorna um array contendo os arquivos/diretórios que corresponderam, um array vazio se nenhum arquivo correspondeu ou `false` em caso de erro. A menos que `GLOB_NOSORT` tenha sido usada, os nomes serão ordenados alfabeticamente e numericamente.

### Exemplos

Exemplo #1 Modo conveniente de como glob() pode susbstituir opendir() e companhia.

    <?php
    foreach (glob("*.txt") as $arquivo) {
        echo "tamanho de $arquivo " . filesize($arquivo) . "\n";
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    tamanho de funclist.txt 44686
    tamanho de funcsummary.txt 267625
    tamanho de quickref.txt 137820

Exemplo #2 Exemplo com uma expressão mais complexa

    <?php
    foreach (glob("caminho/*/*.{txt,md}", \GLOB_BRACE) as $filename) {
        echo "$filename\n";
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    caminho/docs/mailinglist-rules.md
    caminho/docs/README.md
    caminho/docs/release-process.md
    caminho/pear/install-pear.txt
    caminho/Zend/README.md

### Notas

> Nota: Esta função não funcionará em arquivos remotos, pois o arquivo a ser examinado deve ser acessível através do sistema de arquivos do servidor.

> Nota: Esta função não está disponível em alguns sistemas (ex.: antigo Sun OS).

### Veja Também

- opendir() - Abre um manipulador de diretório
- readdir() - Lê entrada do manipulador do diretório
- closedir() - Fecha o manipulador do diretório
- fnmatch() - Compara nome de arquivo com um padrão

# is_dir

(PHP 4, PHP 5, PHP 7, PHP 8)

is_dir — Diz se o caminho é um diretório

### Descrição

function is_dir(string `$filename`): bool

Informa se o dado nome de arquivo é um diretório.

### Parâmetros

`filename`

  Caminho para o arquivo. Se `filename` for um nome de arquivo relativo, será verificado relativamente ao diretório atual de trabalho. Se `filename` for uma ligação simbólica ou ligação rígida então a ligação será resolvida e validado. Se open_basedir estiver habilitado restrições adicionais podem ser aplicáveis.

### Valor Retornado

Retorna `true` se o nome do arquivo existe e é um diretório, `false` caso contrário.

### Erros/Exceções

Em caso de falha, um `E_WARNING` será emitido.

### Exemplos

Exemplo #1 Exemplo da is_dir()

    <?php
    var_dump(is_dir('a_file.txt'));
    var_dump(is_dir('bogus_dir/abc'));

    var_dump(is_dir('..')); // um diretório acima
    ?>

O exemplo acima produzirá:

    bool(false)
    bool(false)
    bool(true)

### Notas

> Nota: Os resultados desta função são armazenados em cache. Consulte a função clearstatcache() para mais detalhes.

Dica

A partir do PHP 5.0.0, esta função também pode ser usada com alguns empacotadores de URL. Consulte os Protocolos e empacotadores suportados para determinar quais empacotadores suportam a família de funções stat().

### Veja Também

- chdir() - Muda o diretório
- dir() - Retorna uma instância da classe Directory
- opendir() - Abre um manipulador de diretório
- is_file() - Informa se o arquivo é um arquivo comum
- is_link() - Informa se o arquivo é uma ligação simbólica

# is_executable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_executable — Diz se um arquivo é executável

### Descrição

function is_executable(string `$filename`): bool

Diz se um arquivo é executável.

### Parâmetros

`filename`

  Caminho para o arquivo.

### Valor Retornado

Retorna `true` se o arquivo existe e é executável, ou `false` em caso de erro. Em sistemas POSIX, um arquivo é executável se o bit de executável das permissões de arquivo estiver ligado. Para Windows, veja a nota abaixo.

### Erros/Exceções

Em caso de falha, um `E_WARNING` será emitido.

### Exemplos

Exemplo #1 Exemplo da is_executable()

    <?php

    $file = '/home/vincent/arquivo.sh';

    if (is_executable($file)) {
        echo $file.' é executável';
    } else {
        echo $file.' não é executável';
    }

    ?>

### Notas

> Nota: Os resultados desta função são armazenados em cache. Consulte a função clearstatcache() para mais detalhes.

Dica

A partir do PHP 5.0.0, esta função também pode ser usada com alguns empacotadores de URL. Consulte os Protocolos e empacotadores suportados para determinar quais empacotadores suportam a família de funções stat().

> Nota: No Windows, um arquivo é considerado executável se for assim reportado pela função `GetBinaryType()` da API do Windows; por razões de compatibilidade, arquivos com extensões .bat ou .cmd também são considerados executáveis. Antes do PHP 7.4.0, qualquer arquivo não vazio com extensão .exe ou .com era considerado executável. Note que PATHEXT é irrelevante para a função is_executable().

### Veja Também

- is_file() - Informa se o arquivo é um arquivo comum
- is_link() - Informa se o arquivo é uma ligação simbólica

# is_file

(PHP 4, PHP 5, PHP 7, PHP 8)

is_file — Informa se o arquivo é um arquivo comum

### Descrição

function is_file(string `$filename`): bool

Informa se o arquivo é um arquivo comum. Se o parâmetro `filename` apontar para uma ligação simbólica, a função resolverá a ligação e dará informação sobre o arquivo referenciado.

### Parâmetros

`filename`

  Caminho para o arquivo.

### Valor Retornado

Retorna `true` se o arquivo existe e é um arquivo comum, `false` caso contrário.

> Nota: Como o tipo inteiro do PHP possui sinal e muitas plataformas usam números inteiros de 32 bits, algumas funções do sistema de arquivos podem retornar resultados inesperados para arquivos maiores que 2GB.

### Erros/Exceções

Em caso de falha, um `E_WARNING` será emitido.

### Exemplos

Exemplo #1 Exemplo da is_file()

    <?php
    var_dump(is_file('a_file.txt')) . "\n";
    var_dump(is_file('/usr/bin/')) . "\n";
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(false)

### Notas

> Nota: Os resultados desta função são armazenados em cache. Consulte a função clearstatcache() para mais detalhes.

Dica

A partir do PHP 5.0.0, esta função também pode ser usada com alguns empacotadores de URL. Consulte os Protocolos e empacotadores suportados para determinar quais empacotadores suportam a família de funções stat().

### Veja Também

- is_dir() - Diz se o caminho é um diretório
- is_link() - Informa se o arquivo é uma ligação simbólica
- SplFileInfo

# is_link

(PHP 4, PHP 5, PHP 7, PHP 8)

is_link — Informa se o arquivo é uma ligação simbólica

### Descrição

function is_link(string `$filename`): bool

Informa se o arquivo informado é uma ligação simbólica (symbolic link).

### Parâmetros

`filename`

  O caminho para o arquivo.

### Valor Retornado

Retorna `true` se o nome do arquivo existe e se é uma ligação simbólica, `false` caso contrário.

### Erros/Exceções

Em caso de falha, um `E_WARNING` será emitido.

### Exemplos

Exemplo #1 Cria e confirma se um arquivo é uma ligação simbólica

    <?php
    $link = 'uploads';

    if (is_link($link)) {
        echo readlink($link);
    } else {
        symlink('uploads.php', $link);
    }
    ?>

### Notas

> Nota: Os resultados desta função são armazenados em cache. Consulte a função clearstatcache() para mais detalhes.

Dica

A partir do PHP 5.0.0, esta função também pode ser usada com alguns empacotadores de URL. Consulte os Protocolos e empacotadores suportados para determinar quais empacotadores suportam a família de funções stat().

### Veja Também

- is_dir() - Diz se o caminho é um diretório
- is_file() - Informa se o arquivo é um arquivo comum
- readlink() - Retornar o alvo de uma ligação simbólica
- symlink() - Cria uma ligação simbólica

# is_readable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_readable — Diz se o arquivo existe e se ele pode ser lido

### Descrição

function is_readable(string `$filename`): bool

Diz se o arquivo existe e se ele pode ser lido

### Parâmetros

`filename`

  Caminho do arquivo.

### Valor Retornado

Retorna `true` se o arquivo ou diretório especificado por `filename` existe e pode ser lido, `false` do contrário.

### Erros/Exceções

Em caso de falha, um `E_WARNING` será emitido.

### Exemplos

Exemplo #1 Exemplo de is_readable()

    <?php
    $filename = 'teste.txt';
    if (is_readable($filename)) {
        echo 'O arquivo pode ser lido.';
    } else {
        echo 'O arquivo não pode ser lido.';
    }
    ?>

### Notas

Lembre-se que o PHP pode acessar o arquivo como o usuário com o qual o servidor web é executado (geralmente 'nobody').

> Nota: Os resultados desta função são armazenados em cache. Consulte a função clearstatcache() para mais detalhes.

Dica

A partir do PHP 5.0.0, esta função também pode ser usada com alguns empacotadores de URL. Consulte os Protocolos e empacotadores suportados para determinar quais empacotadores suportam a família de funções stat().

> Nota:

> A verificação é feita usando os UID/GID reais ao invés dos efetivos.

Essa função pode retornar `true` para diretórios. Use a is_dir() para diferenciar entre arquivo e diretório.

### Veja Também

- is_writable() - Diz se o arquivo pode ser modificado
- file_exists() - Verifica se um arquivo ou diretório existe
- fgets() - Lê uma linha de um ponteiro de arquivo

# is_uploaded_file

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

is_uploaded_file — Informa se o arquivo foi enviado por POST HTTP

### Descrição

function is_uploaded_file(string `$filename`): bool

Retorna `true` se o arquivo com o nome `filename` foi enviado por POST HTTP. Isto é útil para garantir que um usuário malicioso não está tentando levar o script a trabalhar em arquivos que não deveria estar trabalhando -- por exemplo, /etc/passwd.

Este tipo de confirmação é importante principalmente se existe alguma chance que qualquer coisa feita com os arquivos enviados possa revelar seu conteúdo para o usuário, ou mesmo para outros usuários no mesmo sistema.

Para o funcionamento apropriado, a função is_uploaded_file() precisa de um argumento como $_FILES['userfile']['tmp_name'], - o nome do arquivo enviado na máquina do cliente $_FILES['userfile']['name'] não funciona.

### Parâmetros

`filename`

  O nome do arquivo sendo verificado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de is_uploaded_file()

    <?php

    if (is_uploaded_file($_FILES['userfile']['tmp_name'])) {
       echo "O arquivo ". $_FILES['userfile']['name'] ." foi enviado com sucesso.\n";
       echo "Mostrando o conteúdo\n";
       readfile($_FILES['userfile']['tmp_name']);
    } else {
       echo "Possível ataque de envio de arquivo: ";
       echo "nome do arquivo '". $_FILES['userfile']['tmp_name'] . "'.";
    }

    ?>

### Veja Também

- move_uploaded_file() - Move um arquivo enviado para uma nova localização
- $_FILES
- Consulte Gerenciando Envio de Arquivos para um exemplo de uso básico.

# is_writable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_writable — Diz se o arquivo pode ser modificado

### Descrição

function is_writable(string `$filename`): bool

Retorna `true` se o arquivo em `filename` existe e pode ser modificado. O argumento filename pode ser um diretório, permitindo que você verifique se o diretório tem permissão de escrita.

Lembre-se que o PHP pode acessar o arquivo como o usuário com o qual o servidor web é executado (geralmente 'nobody').

### Parâmetros

`filename`

  O arquivo sendo verificado.

### Valor Retornado

Retorna `true` se o arquivo em `filename` existe e pode ser modificado.

### Erros/Exceções

Em caso de falha, um `E_WARNING` será emitido.

### Exemplos

Exemplo #1 Exemplo de is_writable()

    <?php
    $filename = 'teste.txt';
    if (is_writable($filename)) {
        echo 'O arquivo possui permissão de escrita';
    } else {
        echo 'O arquivo não possui permissão de escrita';
    }
    ?>

### Notas

> Nota: Os resultados desta função são armazenados em cache. Consulte a função clearstatcache() para mais detalhes.

Dica

A partir do PHP 5.0.0, esta função também pode ser usada com alguns empacotadores de URL. Consulte os Protocolos e empacotadores suportados para determinar quais empacotadores suportam a família de funções stat().

### Veja Também

- is_readable() - Diz se o arquivo existe e se ele pode ser lido
- file_exists() - Verifica se um arquivo ou diretório existe
- fwrite() - Escrita binary-safe em arquivos

# is_writeable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_writeable — Sinônimo de is_writable()

### Descrição

Esta função é um apelido para: is_writable().

# lchgrp

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

lchgrp — Modifica o grupo de proprietário da ligação simbólica

### Descrição

function lchgrp(string `$filename`, string|int `$group`): bool

Tenta modificar o grupo da ligação simbólica `filename` para o valor do parâmetro `group`.

Somente o superusuário pode alterar arbitrariamente o grupo de uma ligação simbólica; outros usuários podem alterar o grupo de uma ligação simbólica para qualquer grupo do qual esse usuário seja um membro.

### Parâmetros

`filename`

  Caminho para a ligação simbólica.

`group`

  O grupo especificado por nome ou número.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Alterando um grupo de um ligação simbólica

    <?php
    $target = 'output.php';
    $link = 'output.html';
    symlink($target, $link);

    lchgrp($link, 8);
    ?>

### Notas

> Nota: Esta função não funcionará em arquivos remotos, pois o arquivo a ser examinado deve ser acessível através do sistema de arquivos do servidor.

> Nota: Esta função não foi implementada em plataformas Windows.

### Veja Também

- chgrp() - Altera o grupo do arquivo
- lchown() - Modifica o proprietário da ligação simbólica
- chown() - Modifica o proprietário do arquivo
- chmod() - Modifica as permissões do arquivo

# lchown

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

lchown — Modifica o proprietário da ligação simbólica

### Descrição

function lchown(string `$filename`, string|int `$user`): bool

Tenta modificar o proprietário da ligação simbólica `filename` para o usuário `user`.

Somente o superusuário pode mudar o proprietário de uma ligação simbólica.

### Parâmetros

`filename`

  Caminho para o arquivo.

`user`

  O nome do usuário ou número.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Alterando o proprietário de uma ligação simbólica

    <?php
    $target = 'output.php';
    $link = 'output.html';
    symlink($target, $link);

    lchown($link, 8);
    ?>

### Notas

> Nota: Esta função não funcionará em arquivos remotos, pois o arquivo a ser examinado deve ser acessível através do sistema de arquivos do servidor.

> Nota: Esta função não foi implementada em plataformas Windows.

### Veja Também

- chown() - Modifica o proprietário do arquivo
- lchgrp() - Modifica o grupo de proprietário da ligação simbólica
- chgrp() - Altera o grupo do arquivo
- chmod() - Modifica as permissões do arquivo

# link

(PHP 4, PHP 5, PHP 7, PHP 8)

link — Criando uma ligação rígida

### Descrição

function link(string `$target`, string `$link`): bool

link() cria uma ligação rígida.

### Parâmetros

`target`

  Alvo da ligação.

`link`

  O nome da ligação.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

A função falha e emite um `E_WARNING` se `link` já existir, ou se `target` não existir.

### Exemplos

Exemplo #1 Criando uma ligação rígida

    <?php
    $target = 'source.ext'; // Esse é o arquivo existente
    $link = 'newfile.ext';  // Esse é o nome da ligação

    link($target, $link);
    ?>

### Notas

> Nota: Esta função não funcionará em arquivos remotos, pois o arquivo a ser examinado deve ser acessível através do sistema de arquivos do servidor.

> Nota: No Windows, essa função requer o PHP rodando em nível elevado de privilégios ou com o UAC desabilitado.

### Veja Também

- symlink() - Cria uma ligação simbólica
- readlink() - Retornar o alvo de uma ligação simbólica
- linkinfo() - Obtém informação sobre uma ligação
- unlink() - Apaga um arquivo

# linkinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

linkinfo — Obtém informação sobre uma ligação

### Descrição

function linkinfo(string `$path`): int|false

Obtém informação sobre uma ligação.

Esta função é usada para verificar se uma ligação (apontada por `path`) realmente existe (usando o mesmo método da macro S_ISLNK definida em stat.h).

### Parâmetros

`path`

  Caminho para a ligação.

### Valor Retornado

linkinfo() retorna o campo `st_dev` da estrutura stat do Unix C retornado pela chamada de sistema `lstat`. Retorna um inteiro não negativo em caso de sucesso, -1 caso a ligação não seja encontrada, ou `false` se uma violação de open.base_dir ocorrer.

### Exemplos

Exemplo #1 Exemplo de linkinfo()

    <?php

    echo linkinfo('/vmlinuz'); // 835

    ?>

### Veja Também

- symlink() - Cria uma ligação simbólica
- link() - Criando uma ligação rígida
- readlink() - Retornar o alvo de uma ligação simbólica

# lstat

(PHP 4, PHP 5, PHP 7, PHP 8)

lstat — Obtém informações sobre um arquivo ou ligação simbólica

### Descrição

function lstat(string `$filename`): array|false

Obtém estatísticas do arquivo ou ligação simbólica com o nome de `filename`.

### Parâmetros

`filename`

  Caminho para um arquivo ou ligação simbólica.

### Valor Retornado

Veja a página do manual para stat() para informações sobre a estrutura do array retornado que lstat() retorna. Esta função é idêntica à stat() exceto que se o parâmetro `filename` é uma ligação simbólica, e o status da ligação simbólica é retornado e não o status do arquivo apontado pela ligação simbólica.

Em caso de falhas retorna `false`.

### Erros/Exceções

Em caso de falha, um `E_WARNING` será emitido.

### Exemplos

Exemplo #1 Comparação de stat() e lstat()

    <?php
    symlink('uploads.php', 'uploads');

    // Compara a informação de uploads.php e uploads
    array_diff(stat('uploads'), lstat('uploads'));
    ?>

O exemplo acima produzirá algo semelhante a:

Informação que difere entre os dois arquivos:

    Array
    (
        [ino] => 97236376
        [mode] => 33188
        [size] => 34
        [atime] => 1223580003
        [mtime] => 1223581848
        [ctime] => 1223581848
        [blocks] => 8
    )

### Notas

> Nota: Os resultados desta função são armazenados em cache. Consulte a função clearstatcache() para mais detalhes.

Dica

A partir do PHP 5.0.0, esta função também pode ser usada com alguns empacotadores de URL. Consulte os Protocolos e empacotadores suportados para determinar quais empacotadores suportam a família de funções stat().

### Veja Também

- stat() - Obtém informações sobre um arquivo

# mkdir

(PHP 4, PHP 5, PHP 7, PHP 8)

mkdir — Cria um diretório

### Descrição

function mkdir(
string `$directory`,
int `$permissions` = 0777,
bool `$recursive` = `false`,
?resource `$context` = `null`
): bool

Tenta criar o diretório especificado pelo parâmetro `directory`.

### Parâmetros

`directory`

  O caminho do diretório.

  Dica

  Uma URL pode ser usada como um nome de arquivo com esta função se os empacotadores fopen estiverem habilitados. Consulte a função fopen() para mais detalhes sobre como especificar o nome do arquivo. Consulte os Protocolos e empacotadores suportados para obter links para informações sobre as capacidades de cada empacotador, notas de uso e informações sobre quaisquer variáveis predefinidas que eles possam fornecer.

`permissions`

  A permissão padrão é o octal 0777, que significa o acesso mais abrangente possível. Para mais informações sobre permissões, leia os detalhes na página da função chmod().

  > Nota:

  > O parâmetro `permissions` é ignorado no Windows.

  Note que provavelmente será desejado especificar `permissions` como um número octal, o que significa que ele deve ser precedido por zero. `permissions` também é modificado inicial. O mode é também modificado pela umaks atual, pela umask atual, que pode ser modificada usando umask().

`recursive`

  Se for `true`, quaisquer diretórios acima do especificado em `directory` serão criados, com as mesmas permissões.

`context`
  Um resource de contexto de fluxo.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

> Nota:

> Se o diretório a ser criado já existir, será considerado um erro e `false` será retornado. Use is_dir() ou file_exists() para verificar se o diretório já existe antes de tentar criá-lo.

### Erros/Exceções

Emite um erro de nível `E_WARNING` se o diretório já existir.

Emite um erro de nível `E_WARNING` se as permissões relevantes impedem a criação do diretório.

### Exemplos

Exemplo #1 Exemplo de mkdir()

    <?php
    mkdir("/caminho/para/meu/diretorio", 0700);
    ?>

Exemplo #2 mkdir() usando o parâmetro `recursive`

    <?php
    // Estrutura de diretório desejada
    $structure = './profundidade1/profundidade2/profundidade3/';

    // Para criar a estrutura aninhada, o parâmetro $recursive
    // para mkdir() deve ser especificado.

    if (!mkdir($structure, 0777, true)) {
        die('Falha ao criar os diretórios...');
    }

    // ...
    ?>

### Veja Também

- is_dir() - Diz se o caminho é um diretório
- rmdir() - Remove um diretório
- umask() - Modificar a umask atual

# move_uploaded_file

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

move_uploaded_file — Move um arquivo enviado para uma nova localização

### Descrição

function move_uploaded_file(string `$from`, string `$to`): bool

Esta função faz uma verificação para garantir que o arquivo designado por `from` é um arquivo de envio válido (que tenha sido enviado pelo mecanismo de envio POST HTTP do PHP). Se o arquivo for válido, ele será movido para o nome de arquivo dado por `to`.

Este tipo de verificação é especialmente imporante se existir alguma chance de que qualquer coisa feita com os arquivos enviados possa revelar seus conteúdos ao usuário, ou mesmo para outros usuários no mesmo sistema.

### Parâmetros

`from`

  O nome do arquivo enviado.

`to`

  O destino do arquivo movido.

### Valor Retornado

Retorna `true` em caso de sucesso.

Se `from` não for um arquivo enviado válido, nenhuma ação ocorrerá e move_uploaded_file() retornará `false`.

Se `from` for um arquivo enviado válido, mas não puder ser movido por alguma razão, nenhuma ação ocorrerá e move_uploaded_file() retornará `false`. Adicionalmente, um alerta será emitido.

### Exemplos

Exemplo #1 Enviando múltiplos arquivos

    <?php
    $uploads_dir = '/uploads';
    foreach ($_FILES["pictures"]["error"] as $key => $error) {
        if ($error == UPLOAD_ERR_OK) {
            $tmp_name = $_FILES["pictures"]["tmp_name"][$key];
            // basename() pode evitar ataques no sistema de arquivos;
            // valização e sanitização adicionais no nome do arquivo podem ser necessárias
            $name = basename($_FILES["pictures"]["name"][$key]);
            move_uploaded_file($tmp_name, "$uploads_dir/$name");
        }
    }
    ?>

### Notas

> Nota:

> move_uploaded_file() é afetada por open_basedir. Entretanto, restrições são aplicadas apenas no caminho de `to` para permitir a movimentação de arquivos enviados nos quais `from` possa conflitar com tais restrições. move_uploaded_file() assegura a segurança desta operação permitindo que apenas arquivos enviados através do PHP possam ser movidos.

Aviso

Se o arquivo de destino já existir, ele será sobrescrito.

### Veja Também

- is_uploaded_file() - Informa se o arquivo foi enviado por POST HTTP
- rename() - Renomeia um arquivo ou diretório
- Consulteja Gerenciando envio de arquivos para um exemplo de uso básico

# parse_ini_file

(PHP 4, PHP 5, PHP 7, PHP 8)

parse_ini_file — Interpreta um arquivo de configuração

### Descrição

function parse_ini_file(string `$filename`, bool `$process_sections` = `false`, int `$scanner_mode` = `INI_SCANNER_NORMAL`): array|false

parse_ini_file() carrega o arquivo INI especificado em `filename` e retorna as configurações contidas nele em um array associativo.

A estrutura do arquivo INI é a mesma do php.ini.

Aviso

Esta função não deve ser usada com entradas não confiáveis a menos que `scanner_mode` seja igual a `INI_SCANNER_RAW`, já que a saída analisada pode conter valores de constantes sensíveis como as que contêm senhas de banco de dados.

### Parâmetros

`filename`

  O nome do arquivo INI sendo interpretado. Se um caminho relativo for usado, será avaliado relativamente ao diretório atual de trabalho, e depois no caminho include_path.

`process_sections`

  Definindo o parâmetro `process_sections` para `true`, obtém-se um array multidimensional com os nomes das seções e configurações incluídos. O padrão para `process_sections` é `false`

`scanner_mode`

  Pode ser `INI_SCANNER_NORMAL` (padrão) ou `INI_SCANNER_RAW`. Se `INI_SCANNER_RAW` for fornecido, os valores das opções não serão interpretados.

  A partir do PHP 5.6.1, também pode ser especificado como `INI_SCANNER_TYPED`. Nesse modo, os tipos boolean, null e integer são preservados quando possível. Os valores string `"true"`, `"on"` e `"yes"` são convertidos em `true`. `"false"`, `"off"`, `"no"` e `"none"` são considerados `false`. `"null"` é convertido para `null` no modo tipado. Além disso, todas as strings numéricas são convertidas para o tipo inteiro, se possível.

### Valor Retornado

As configurações são retornadas como um array associativo em caso de sucesso, e `false` em caso de falha.

### Exemplos

Exemplo #1 Conteúdo de sample.ini

    ; Este é um arquivo de configuração de exemplo
    ; Comentários iniciam com ';', como no php.ini

    [primeira_secao]
    um = 1
    cinco = 5
    animal = PASSARO

    [segunda_secao]
    path = "/usr/local/bin"
    URL = "http://www.example.com/~username"

    [terceira_secao]
    versaophp[] = "5.0"
    versaophp[] = "5.1"
    versaophp[] = "5.2"
    versaophp[] = "5.3"

    urls[svn] = "http://svn.php.net"
    urls[git] = "http://git.php.net"

Exemplo #2 Exemplo de parse_ini_file()

Constantes (mas não "constantes mágicas" como `__FILE__`) também podem ser interpretadas no arquivo INI. Se for definida uma constante como um valor INI antes de executar parse_ini_file(), ela será intergrada aos resultados. Somente valores INI são avaliados e o valor deve ser apenas a constante. Por exemplo:

    <?php

    define('PASSARO', 'Pássaro Dodo');

    // Interpreta sem as seções
    $ini_array = parse_ini_file("sample.ini");
    print_r($ini_array);

    // Interpreta com as seções
    $ini_array = parse_ini_file("sample.ini", true);
    print_r($ini_array);

    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [um] => 1
        [cinco] => 5
        [animal] => Pássaro Dodo
        [path] => /usr/local/bin
        [URL] => http://www.example.com/~username
        [versaophp] => Array
            (
                [0] => 5.0
                [1] => 5.1
                [2] => 5.2
                [3] => 5.3
            )

        [urls] => Array
            (
                [svn] => http://svn.php.net
                [git] => http://git.php.net
            )

    )
    Array
    (
        [primeira_secao] => Array
            (
                [um] => 1
                [cinco] => 5
                [animal] = Pássaro Dodo
            )

        [segunda_secao] => Array
            (
                [path] => /usr/local/bin
                [URL] => http://www.example.com/~username
            )

        [terceira_secao] => Array
            (
                [versaophp] => Array
                    (
                        [0] => 5.0
                        [1] => 5.1
                        [2] => 5.2
                        [3] => 5.3
                    )

                [urls] => Array
                    (
                        [svn] => http://svn.php.net
                        [git] => http://git.php.net
                    )

            )

    )

Exemplo #3 parse_ini_file() interpretando um arquivo php.ini

    <?php
    // Uma função simples usada para comparar os resultados abaixo
    function sim_nao($expression)
    {
        return($expression ? 'Sim' : 'Não');
    }

    // Obtém o caminho para o php.ini usando a função php_ini_loaded_file()
    $ini_path = php_ini_loaded_file();

    // Interpreta o php.ini
    $ini = parse_ini_file($ini_path);

    // Mostra e compara os valores, note que usar get_cfg_var()
    // levará aos mesmos resultados para interpretado e carregado aqui
    echo '(interpretado) magic_quotes_gpc = ' . sim_nao($ini['magic_quotes_gpc']) . PHP_EOL;
    echo '(carregado) magic_quotes_gpc = ' . sim_nao(get_cfg_var('magic_quotes_gpc')) . PHP_EOL;
    ?>

O exemplo acima produzirá algo semelhante a:

    (parsed) magic_quotes_gpc = Sim
    (loaded) magic_quotes_gpc = Sim

Exemplo #4 Interpolação de Valor

Além de avaliar constantes, alguns caracteres possuem significado especial em um valor INI. Adicionamente, variáveis de ambiente e opções de configuração previamente definidas (consulte get_cfg_var()) podem ser lidas usando a sintaxe `${}`.

    ; | é usado par OR bit a bit
    tres = 2|3

    ; & é usado para AND bit a bit
    quatro = 6&5

    ; ^ é usado para XOR bit a bit
    cinco = 3^6

    ; ~ é usado para inversão bit a bit
    dois_negativo = ~1

    ; () é usado para agrupamento
    sete = (8|7)&(6|5)

    ; Interpola a variável de ambiente PATH
    path = ${PATH}

    ; Interpola a opção de configuração 'memory_limit'
    limite_de_memoria_configurado = ${memory_limit}

Exemplo #5 Fazendo Escape de Caracteres

Alguns caracteres têm significado especial em strings com aspas duplas e devem ser escapados pela barra invertida prefixada. Primeiramente, eles são as aspas duplas `"` como marcação dos limites, e a barra invertida `\` em si (se seguida por um dos caracteres especiais):

    fala = "Ela disse \"Exatamente meu ponto\"." ; Resulta em uma string contendo aspas duplas.
    dica = "Use \\\" para escapar aspas duplas" ; Resulta em: Use \" para escapar aspas duplas

Há uma excecão feita para caminhos do tipo Windows: é possível não escapar barra invertida no final se a string entre aspas for diretamente seguida por uma quebra de linha:

    save_path = "C:\Temp\"

Se for necessário escapar aspas duplas seguidas pode quebra de linha em um valor com várias linhas, é possível usar concatenação de valores da seguinte forma (há uma string com aspas duplas diretamente seguida por outra):

    long_text = "Lorem \"ipsum\"""
     dolor" ; Resulta em: Lorem "ipsum"\n dolor

Outro caractere com significado especial é `$` (sinal de cifrão). Deve ser escapado se for seguido de chave:

    code = "\${test}"

Escapar caracteres não é suportado no modo `INI_SCANNER_RAW` (neste modo todos os caracateres são processados como eles são).

Note que o interpretador INI não suporta sequências escape padrões (`\n`, `\t` etc.). Se necessário, faça pós processamento do resultado de parse_ini_file() com a função stripcslashes().

### Notas

> Nota:

> Essa função não tem relação nenhuma com o arquivo php.ini. Ele já está processado no momento em o script é executado. Esta função pode ser usada para ler os arquivos de configuração da própria aplicação do usuário.

> Nota:

> Se um valor no arquivo INI tiver algum caractere não alfanumérico, ele precisará ser envolvido em aspas duplas (").

> Nota: Existem algumas palavras reservadas que não podem ser usadas como chaves em arquivos INI. Elas incluem: `null`, `yes`, `no`, `true`, `false`, `on`, `off` e `none`. Valores `null`, `off`, `no` e `false` resultam em `""`, e os valores `on`, `yes` e `true` resultam em `"1"`, a menos que o modo `INI_SCANNER_TYPED` seja usado. Os caracteres `?{}|&~!()^"` não devem ser usados em nenhum lugar da chave e têm um significado especial no valor.

> Nota:

> Entradas sem um sinal de igualdade são ignoradas. Por exemplo, "foo" é ignorado enquanto que "bar =" é interpretado e adicionado com um valor vazio. Por exemplo, o MySQL tem uma configuração "no-auto-rehash" no arquivo my.cnf que não leva um valor, portanto ela é ignorada.

> Nota:

> Arquivos INI são feralmente tratados como texto puro por servidores web e depois enviados aos navegadores se requisitados. Isto quer dizer que para segurança deve-se manter os arquivos INI fora da raiz de documentos da web ou reconfigurar seu servidor web para não disponibilizá-los. Falha em fazer isso pode introduzir um risco de segurança.

### Veja Também

- parse_ini_string() - Interpreta uma string de configuração

# parse_ini_string

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

parse_ini_string — Interpreta uma string de configuração

### Descrição

function parse_ini_string(string `$ini_string`, bool `$process_sections` = `false`, int `$scanner_mode` = `INI_SCANNER_NORMAL`): array|false

parse_ini_string() retorna as configurações da string `ini_string` em um array associativo.

A estrutura da string INI é a mesma dos php.ini's.

Aviso

Esta função não deve ser usada com entradas não confiáveis a menos que `scanner_mode` seja igual a `INI_SCANNER_RAW`, já que a saída analisada pode conter valores de constantes sensíveis como as que contêm senhas de banco de dados.

### Parâmetros

`ini_string`

  O conteúdo do arquivo ini sendo interpretado.

`process_sections`

  Definindo o último parâmetro `process_sections` como `true`, você recupera um array multidimensional com o nome das seções e configurações inclusas. O padrão para `process_sections` é `false`

`scanner_mode`

  O parâmetro pode ser `INI_SCANNER_NORMAL` (default) ou `INI_SCANNER_RAW`. Se `INI_SCANNER_RAW` for fornecido, então os valores das opçoes não serão analisados.

  A partir do PHP 5.6.1, também pode ser especificado como `INI_SCANNER_TYPED`. Nesse modo, os tipos boolean, null e integer são preservados quando possível. Os valores string `"true"`, `"on"` e `"yes"` são convertidos em `true`. `"false"`, `"off"`, `"no"` e `"none"` são considerados `false`. `"null"` é convertido para `null` no modo tipado. Além disso, todas as strings numéricas são convertidas para o tipo inteiro, se possível.

### Valor Retornado

As configurações são retornadas como um array associativo, se sucesso e `false` caso falhe.

### Notas

> Nota: Existem algumas palavras reservadas que não podem ser usadas como chaves em arquivos INI. Elas incluem: `null`, `yes`, `no`, `true` e `false`, `on`, `off`, `none`. Valores `null`, `off`, `no` e `false` retornam como `""`, e valores `on`, `yes` e `true` resultam em `"1"`, a menos que o modo `INI_SCANNER_TYPED` seja usado. Os caracteres `?{}|&~![()^"` não podem ser usados em lugar algum na chave e têm significado especial no valor.

### Veja Também

- parse_ini_file() - Interpreta um arquivo de configuração

# pathinfo

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pathinfo — Retorna informações sobre um caminho de arquivo

### Descrição

function pathinfo(string `$path`, int `$flags` = `PATHINFO_ALL`): array|string

pathinfo() retorna informações sobre o caminho em `path`: ou um array associativo ou uma string, dependendo das opções em `flags`.

> Nota:

> Para informação sobre obtenção de informação sobre o caminho atual, leia a seção sobre variáveis reservadas predefinidas.

> Nota:

> pathinfo() opera ingenuamente na string de entrada, e não tem ciência sobre o sistema de arquivos real, ou componentes de caminho como "`..`".

> Nota:

> Apenas nos sistemas Windows, o caractere `\` será interpretado como um separador de diretório. Em outros sistemas será tratado como qualquer outro caractere.

Cuidado

pathinfo() é afetado pela localidade, então para que seja interpretado corretamente um caminho contendo caracteres multibyte, a localização correspondente deve ser definida pela função setlocale().

### Parâmetros

`path`

  O caminho a ser analisado.

`flags`

  Se presente, define o elemento expecífico a ser retornado; pode ser `PATHINFO_DIRNAME`, `PATHINFO_BASENAME`, `PATHINFO_EXTENSION` ou `PATHINFO_FILENAME`.

  Se `flags` não for especificado, retorna todos os elementos disponíveis.

### Valor Retornado

Se o parâmetro `flags` não for passado, um array associativo contendo os seguintes elementos é retornado: `dirname`, `basename`, `extension` (se houver), e `filename`.

> Nota:

> Se `path` tiver mais de uma extensão, `PATHINFO_EXTENSION` retorna apenas a última e `PATHINFO_FILENAME` apenas remove a última. (veja o primeiro exemplo abaixo).

> Nota:

> Se `path` não tiver uma extensão, nenhum elemento `extension` será retornado (veja o segundo exemplo abaixo).

> Nota:

> Se o `basename` do parâmetro `path` começa com um ponto, os seguintes caracteres são interpretados como `extension`, e o `filename` estará vazio (veja o terceiro exemplo abaixo).

Se `flags` estiver presente, retorna uma string contendo o elemento solicitado.

### Exemplos

Exemplo #1 Exemplo de pathinfo()

    <?php
    $path_parts = pathinfo('/www/htdocs/inc/lib.inc.php');

    echo $path_parts['dirname'], "\n";
    echo $path_parts['basename'], "\n";
    echo $path_parts['extension'], "\n";
    echo $path_parts['filename'], "\n";
    ?>

O exemplo acima produzirá:

    /www/htdocs/inc
    lib.inc.php
    php
    lib.inc

Exemplo #2 Exemplo de pathinfo() mostrando a diferença entre null e nenhuma extensão

    <?php
    $path_parts = pathinfo('/path/emptyextension.');
    var_dump($path_parts['extension']);

    $path_parts = pathinfo('/path/noextension');
    var_dump($path_parts['extension']);
    ?>

O exemplo acima produzirá algo semelhante a:

    string(0) ""

    Notice: Undefined index: extension in test.php on line 6
    NULL

Exemplo #3 Exemplo de pathinfo() para um arquivo iniciado por ponto

    <?php
    print_r(pathinfo('/some/path/.test'));
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [dirname] => /some/path
        [basename] => .test
        [extension] => test
        [filename] =>
    )

Exemplo #4 Exemplo de pathinfo() com desconstrução de array

O parâmetro `flags` não é uma máscara de bits. Apenas um único valor pode ser fornecido. Para selecionar apenas um conjunto limitado de valores interpretados, use desconstrução de array desta forma:

    <?php
    ['basename' => $basename, 'dirname' => $dirname] = pathinfo('/www/htdocs/inc/lib.inc.php');

    var_dump($basename, $dirname);
    ?>

O exemplo acima produzirá algo semelhante a:

    string(11) "lib.inc.php"
    string(15) "/www/htdocs/inc"

### Veja Também

- dirname() - Retorna o caminho para o diretório pai
- basename() - Retorna a última parte do caminho
- parse_url() - Analisa uma URL e retorna seus componentes
- realpath() - Retorna o path absoluto canonizado

# pclose

(PHP 4, PHP 5, PHP 7, PHP 8)

pclose — Fecha o ponteiro de arquivo de processo

### Descrição

function pclose(resource `$handle`): int

Fecha um ponteiro de arquivo a um tubo aberto por popen().

### Parâmetros

`handle`

  O ponteiro de arquivo deve ser válido e deve ter sido retornado por uma chamada bem sucedida à função popen().

### Valor Retornado

Retorna o estado da finalização do processo que estava em execução. Em caso de erro, `-1` é retornado.

> Nota: Se o PHP foi compilado com --enable-sigchild, o valor retornado por esta função é indefinido.

### Exemplos

Exemplo #1 Exemplo de pclose()

    <?php
    $handle = popen('/bin/ls', 'r');
    pclose($handle);
    ?>

### Notas

> Nota: Somente Unix:

> pclose() é implementada internamente usando a chamada de sistema `waitpid(3)`. Para obter o código real do estado de saída, a função pcntl_wexitstatus() deve ser usada.

### Veja Também

- popen() - Abre um processo como ponteiro de arquivo

# popen

(PHP 4, PHP 5, PHP 7, PHP 8)

popen — Abre um processo como ponteiro de arquivo

### Descrição

function popen(string `$command`, string `$mode`): resource|false

Abre uma pipe para um processo executado ao se dar um fork para o comando dado por `command`.

### Parâmetros

`command`

  O comando

`mode`

  O modo. Pode ser `'r'` para leitura ou `'w'` para escrita.

  No Windows, o padrão de popen() é modo texto, isto é, qualquer caractere `\n` escrito ou lido do tubo será traduzido para `\r\n`. Se isto não for desejado, o modo binário pode ser forçado definindo-se o `mode` para `'rb'` e `'wb'`, respectivamente.

### Valor Retornado

Retorna um ponteiro de arquivo idêntico ao retornado por fopen(), exceto que ele é unidirecional (pode ser usado somente para leitura ou gravação) e tem que ser fechado com pclose(). Este ponteiro pode ser usado com fgets(), fgetss() e fwrite(). Quando o modo é 'r', o ponteiro de arquivo retornado é igual ao STDOUT do comando; quando o modo é 'w', o ponteiro de arquivo é igual ao STDIN do comando.

Se um erro ocorrer, retorna `false`.

### Exemplos

Exemplo #1 Exemplo de popen()

    <?php
    $handle = popen("/bin/ls", "r");
    ?>

Se o comando a ser executado não for encontrado, um resource válido é retornado. Isso pode parecer estranho, mas tem sentido: permite que você acesse qualquer mensagem de erro retornado pelo sistema operacional.

Exemplo #2 Exemplo da popen()

    <?php
    error_reporting(E_ALL);

    /* Adiciona redirecionamento para que seja obtido stderr. */
    $handle = popen('/caminho/para/executavel 2>&1', 'r');
    echo "'$handle'; " . gettype($handle) . "\n";
    $read = fread($handle, 2096);
    echo $read;
    pclose($handle);
    ?>

### Notas

> Nota:

> Se for necessário suporte bidirecional (duas mãos), use proc_open().

### Veja Também

- pclose() - Fecha o ponteiro de arquivo de processo
- fopen() - Abre um arquivo ou URL
- proc_open() - Executa um comando e abre ponteiros de arquivo para entrada/saída

# readfile

(PHP 4, PHP 5, PHP 7, PHP 8)

readfile — Exibe o conteúdo de um arquivo

### Descrição

function readfile(string `$filename`, bool `$use_include_path` = `false`, ?resource `$context` = `null`): int|false

Lê um arquivo e escreve o seu conteúdo para o buffer de saída.

### Parâmetros

`filename`

  O nome do arquivo a ser lido.

`use_include_path`

  Pode-se usar o segundo parâmetro opcional e configurá-lo para `true`, se for desejado procurar o arquivo no include_path também.

`context`
  Um resource de contexto de fluxo.

### Valor Retornado

Retorna o número de bytes lidos do arquivo em caso de sucesso, ou `false` em caso de falha

### Erros/Exceções

Em caso de falha, um `E_WARNING` será emitido.

### Exemplos

Exemplo #1 Forçando um recebimento usando readfile()

    <?php
    $file = 'monkey.gif';

    if (file_exists($file)) {
        header('Content-Description: File Transfer');
        header('Content-Type: application/octet-stream');
        header('Content-Disposition: attachment; filename="'.basename($file).'"');
        header('Expires: 0');
        header('Cache-Control: must-revalidate');
        header('Pragma: public');
        header('Content-Length: ' . filesize($file));
        readfile($file);
        exit;
    }
    ?>

O exemplo acima produzirá algo semelhante a:

### Notas

> Nota:

> readfile() não apresentará por si só nenhum problema de memória, mesmo no envio de grandes arquivos. Se for encontrado um erro de falta de memória, certifique-se que o buffer de saída está desligado com ob_get_level().

Dica

Uma URL pode ser usada como um nome de arquivo com esta função se os empacotadores fopen estiverem habilitados. Consulte a função fopen() para mais detalhes sobre como especificar o nome do arquivo. Consulte os Protocolos e empacotadores suportados para obter links para informações sobre as capacidades de cada empacotador, notas de uso e informações sobre quaisquer variáveis predefinidas que eles possam fornecer.

### Veja Também

- fpassthru() - Imprime todos os dados restantes de um ponteiro de arquivo
- file() - Lê todo o arquivo para um array
- fopen() - Abre um arquivo ou URL
- include - include
- require - require
- virtual() - Realiza uma sub-requisição Apache
- file_get_contents() - Lê todo o conteúdo de um arquivo para uma string
- Protocolos e empacotadores suportados

# readlink

(PHP 4, PHP 5, PHP 7, PHP 8)

readlink — Retornar o alvo de uma ligação simbólica

### Descrição

function readlink(string `$path`): string|false

readlink() faz o mesmo que a função do C.

### Parâmetros

`path`

  O caminho para a ligação simbólica.

### Valor Retornado

Retorna o conteúdo do caminho da ligação simbólica ou `false` em erro.

> Nota: Esta função falha se `path` não é um symlink, exceto no Windows, onde o caminho normalizado é retornado.

### Exemplos

Exemplo #1 Exemplo de readlink()

    <?php

    // Exibe algo como /boot/vmlinux-2.4.20-xfs
    echo readlink('/vmlinuz');

    ?>

### Veja Também

- is_link() - Informa se o arquivo é uma ligação simbólica
- symlink() - Cria uma ligação simbólica
- linkinfo() - Obtém informação sobre uma ligação

# realpath

(PHP 4, PHP 5, PHP 7, PHP 8)

realpath — Retorna o path absoluto canonizado

### Descrição

function realpath(string `$path`): string|false

realpath() expande todas as ligações simbólicas e resolve referências para `/./`, `/../` e caracteres `/` extras no caminho `path`, e retorna o caminho absoluto canonizado.

### Parâmetros

`path`

  O caminho a ser verificado.

  > Nota:

  > Ainda que caminho precise ser fornecido, o valor pode ser uma string vazia. Neste caso, o valor é interpretado como o diretório atual.

### Valor Retornado

Retorna o caminho absouto canonizado em caso de sucesso. O caminho resultante não conterá nenhuma ligação simbólica ou componentes `/./` e `/../`. Delimitadores no final da string, como `\` e `/`, também são removidos.

realpath() retorna `false` em caso de falha, por exemplo, se o caminho não existir.

> Nota:

> O script em execução deve ter permissões de executável em todos os diretórios na hierarquia, caso contrário realpath() retornará `false`.

> Nota:

> Para sistemas de arquivos insensíveis a maiúsculas/minúsculas, realpath() pode ou não normalizar a forma maiúscula/minúscula do caractere.

> Nota:

> A função realpath() não funcionará para um arquivo que estiver dentro de um Phar pois este caminho será virtual, e não real.

> Nota:

> No Windows, junções e ligações simbólicas a diretórios somente são expandidas em um nível.

> Nota: Como o tipo inteiro do PHP possui sinal e muitas plataformas usam números inteiros de 32 bits, algumas funções do sistema de arquivos podem retornar resultados inesperados para arquivos maiores que 2GB.

### Exemplos

Exemplo #1 Exemplo de realpath()

    <?php
    chdir('/var/www/');
    echo realpath('./../../etc/passwd') . PHP_EOL;

    echo realpath('/tmp/') . PHP_EOL;
    ?>

O exemplo acima produzirá:

    /etc/passwd

Exemplo #2 realpath() no Windows

No Windows, realpath() modificará o estilo Unix de diretórios para o estilo Windows.

    <?php
    echo realpath('/windows/system32'), PHP_EOL;

    echo realpath('C:\Program Files\\'), PHP_EOL;
    ?>

O exemplo acima produzirá:

    C:\WINDOWS\System32
    C:\Program Files

### Veja Também

- basename() - Retorna a última parte do caminho
- dirname() - Retorna o caminho para o diretório pai
- pathinfo() - Retorna informações sobre um caminho de arquivo

# realpath_cache_get

(PHP 5 >= 5.3.2, PHP 7, PHP 8)

realpath_cache_get — Obter entradas de cache do caminho absoluto

### Descrição

function realpath_cache_get(): array

Obtém o conteúdo do cache do caminho absoluto.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array com as entradas do caminho absoluto. As chaves são o caminho absoluto, e os valores são arrays de informações dos dados, contendo o caminho absoluto, data de expiração, e outras informações mantidas no cache.

### Exemplos

Exemplo #1 Exemplo de realpath_cache_get()

    <?php
    var_dump(realpath_cache_get());
    ?>

O exemplo acima produzirá algo semelhante a:

    array(2) {
      ["/test"]=>
      array(4) {
        ["key"]=>
        int(123456789)
        ["is_dir"]=>
        bool(true)
        ["realpath"]=>
        string(5) "/test"
        ["expires"]=>
        int(1260318939)
      }
      ["/test/test.php"]=>
      array(4) {
        ["key"]=>
        int(987654321)
        ["is_dir"]=>
        bool(false)
        ["realpath"]=>
        string(12) "/root/test.php"
        ["expires"]=>
        int(1260318939)
      }
    }

### Veja Também

- realpath_cache_size() - Obter o tamanho do cache do caminho absoluto

# realpath_cache_size

(PHP 5 >= 5.3.2, PHP 7, PHP 8)

realpath_cache_size — Obter o tamanho do cache do caminho absoluto

### Descrição

function realpath_cache_size(): int

Obtém a quantidade de memória utilizada pelo cache do caminho absoluto.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna quanta memória o cache do caminho absoluto está utilizando.

### Exemplos

Exemplo #1 Exemplo de realpath_cache_size()

    <?php
    var_dump(realpath_cache_size());
    ?>

O exemplo acima produzirá algo semelhante a:

    int(412)

### Veja Também

- realpath_cache_get() - Obter entradas de cache do caminho absoluto
- As opções de configurações de realpath_cache_size

# rename

(PHP 4, PHP 5, PHP 7, PHP 8)

rename — Renomeia um arquivo ou diretório

### Descrição

function rename(string `$from`, string `$to`, ?resource `$context` = `null`): bool

Tenta renomear `from` para `to`, movendo entre diretórios se necessário. Se o arquivo `to` já existir, ele será sobrescrito. Se renomeando um diretório e `to` já existir, esta função emite um warning.

### Parâmetros

`from`

  O nome anterior.

  > Nota:

  > O empacotador utilizado em `from` precisa ser o mesmo empacotador utilizado em `to`.

`to`

  O novo nome.

  > Nota: No Windows, se `to` já existir, ele precisa ter permissão de escrita. Se não a função rename() falhará e emitirá um `E_WARNING`.

`context`
  Um resource de contexto de fluxo.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo da rename()

    <?php
    rename("/tmp/tmp_file.txt", "/home/user/login/docs/my_file.txt");
    ?>

### Veja Também

- copy() - Copia arquivo
- unlink() - Apaga um arquivo
- move_uploaded_file() - Move um arquivo enviado para uma nova localização

# rewind

(PHP 4, PHP 5, PHP 7, PHP 8)

rewind — Retrocede a posição de um ponteiro de arquivos

### Descrição

function rewind(resource `$stream`): bool

Define o indicador de posição de arquivo de `stream` para o início do fluxo do arquivo.

> Nota:

> Se o arquivo foi aberto no modo de acréscimo ("a" ou "a+"), qualquer dado que for escrito no arquivo será sempre acrescentado, independente da posição do ponteiro.

### Parâmetros

`stream`

  O ponteiro de arquivo deve ser válido e deve apontar para um arquivo aberto com sucesso por fopen().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de rewind() sobrescrevendo

    <?php
    $handle = fopen('output.txt', 'r+');

    fwrite($handle, 'Frase realmente longa.');
    rewind($handle);
    fwrite($handle, 'Foo');
    rewind($handle);

    echo fread($handle, filesize('output.txt'));

    fclose($handle);
    ?>

O exemplo acima produzirá algo semelhante a:

    Foose realmente longa.

### Veja Também

- fread() - Leitura de arquivo segura para binário
- fseek() - Aponta para uma posição no arquivo
- ftell() - Retorna a posição atual do ponteiro de leitura/gravação do arquivo
- fwrite() - Escrita binary-safe em arquivos

# rmdir

(PHP 4, PHP 5, PHP 7, PHP 8)

rmdir — Remove um diretório

### Descrição

function rmdir(string `$directory`, ?resource `$context` = `null`): bool

Tenta remover o diretório com o nome de `directory`. O diretório deve estar vazio e as permissões relevantes devem autorizar a operação. Um erro de nível `E_WARNING` será gerado em caso de falha.

### Parâmetros

`directory`

  Caminho para o diretório.

`context`
  Um resource de contexto de fluxo.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de rmdir()

    <?php
    if (!is_dir('examples')) {
        mkdir('examples');
    }

    rmdir('examples');
    ?>

### Veja Também

- is_dir() - Diz se o caminho é um diretório
- mkdir() - Cria um diretório
- unlink() - Apaga um arquivo

# set_file_buffer

(PHP 4, PHP 5, PHP 7, PHP 8)

set_file_buffer — Sinônimo de stream_set_write_buffer()

### Descrição

Esta função é um apelido para: stream_set_write_buffer().

# stat

(PHP 4, PHP 5, PHP 7, PHP 8)

stat — Obtém informações sobre um arquivo

### Descrição

function stat(string `$filename`): array|false

Coleta estatísticas do arquivo informado em `filename`. Se `filename` for uma ligação simbólica, estatísticas serão do próprio arquivo, não da ligação. Antes do PHP 7.4.0, nas compilações NTS do Windows, as estatísticas `size`, `atime`, `mtime` e `ctime` são da ligação simbólica, neste caso.

lstat() é idêntica à stat() exceto que ela foi baseada no estado de ligações simbólicas.

### Parâmetros

`filename`

  Caminho para o arquivo.

### Valor Retornado

Formato de retorno de stat() e fstat()
Numérico | Associativo | Descrição
--- | --- | ---
0 | dev | número do dispositivo ***
1 | ino | número do inode ***
2 | mode | modo de proteção do inode *****
3 | nlink | número de ligações
4 | uid | id de usuário do proprietário *
5 | gid | id de grupo do proprietário *
6 | rdev | tipo de dispositivo, se for inode
7 | size | tamanho em bytes
8 | atime | horário do último acesso (timestamp Unix)
9 | mtime | horário da última modificação (timestamp Unix)
10 | ctime | hora da última modificação do inode (timestamp Unix)
11 | blksize | tamanho do bloco de E/S no sistema de arquivos **
12 | blocks | número de blocos de 512 bytes alocados **

* No Windows será sempre `0`.

** Válido apenas em sistemas que suportam o tipo st_blksize type - outros sistemas (ex.: Windows) retornam `-1`.

*** No Windows, a partir do PHP 7.4.0, este é o número de série do volume que contém o arquivo, que é um inteiro de 64-bits sem sinal, ou seja, pode sobrecarregar. Anteriormente, era uma representação numérica da letra do dispositivo (ex.: `2` para `C:`) para stat(), e `0` para lstat().

**** No Windows, a partir do PHP 7.4.0, este é o identificador associado com o arquivo, que é um inteiro de 64-bits sem sinal, ou seja, pode sobrecarregar. Anteriormente, era sempre `0`.

***** No Windows, o bit de permissão de escrita é definido de acordo com o atributo de somente-leitura do arquivo, e o mesmo valor é reportado para todos os usuários, grupos e proprietários. A ACL não é levada em consideração, contrário a is_writable().

O valor de `mode` contém informação lida por várias funções. Quando escrita em octal, começando da direita, os primeiros três dígitos são retornados por chmod(). O dígito seguinte é ignorado pelo PHP. Os dois dígitos seguintes indicam o tipo de arquivo:

Tipos de arquivo para `mode`
`mode` em octal | Significado
--- | ---
`0140000` | socket
`0120000` | ligação
`0100000` | arquivo normal
`0060000` | dispositivo de bloco
`0040000` | diretório
`0020000` | dispositivo de caracteres
`0010000` | fifo

Por exemplo, um arquivo normal poderia ser `0100644` e um diretório poderia ser `0040755`.

Em caso de erro, stat() retorna `false`.

> Nota: Como o tipo inteiro do PHP possui sinal e muitas plataformas usam números inteiros de 32 bits, algumas funções do sistema de arquivos podem retornar resultados inesperados para arquivos maiores que 2GB.

### Erros/Exceções

Em caso de falha, um `E_WARNING` é emitido.

### Registro de Alterações

Versão | Descrição
--- | ---
7.4.0 | No Windows, o número do dispositivo agora é o número de série do volume que contém o arquivo, e o número do inode é o identificador associado com o arquivo.
7.4.0 | As estatísticas `size`, `atime`, `mtime` e `ctime` de ligações simbólicas agora são sempre aquelas do alvo. Anteriormente não era o caso para compilações NTS do Windows.

### Exemplos

Exemplo #1 Exemplo de stat()

    <?php
    /* Obtém estatística sobre o arquivo */
    $stat = stat('C:\php\php.exe');

    /*
     * Mostra o horário de acesso ao arquivo, é o mesmo que
     * chamar fileatime()
     */
    echo 'Horário de acesso: ' . $stat['atime'];

    /*
     * Mostra o horário de modificação do arquivo, é o mesmo que
     * chamar filemtime()
     */
    echo 'Horário de modificação: ' . $stat['mtime'];

    /* Mostra o número de dispositivo */
    echo 'Número de dispositivo: ' . $stat['dev'];
    ?>

Exemplo #2 Usando informação de stat() junto com a função touch()

    <?php
    /* Obtém estatística sobre o arquivo */
    $stat = stat('C:\php\php.exe');

    /* Falhou a obtenção de estatística? */
    if (!$stat) {
        echo 'stat() falhou...';
    } else {
        /*
         * Queremos o horário de acesso 1 semana
         * depois do atual.
         */
        $atime = $stat['atime'] + 604800;

        /* Toca o arquivo */
        if (!touch('some_file.txt', time(), $atime)) {
            echo 'Falha ao tocar o arquivo...';
        } else {
            echo 'touch() retorno com sucesso...';
        }
    }
    ?>

### Notas

> Nota: Note que a resolução de tempo pode variar de um sistema de arquivos para outro.

> Nota: Os resultados desta função são armazenados em cache. Consulte a função clearstatcache() para mais detalhes.

Dica

A partir do PHP 5.0.0, esta função também pode ser usada com alguns empacotadores de URL. Consulte os Protocolos e empacotadores suportados para determinar quais empacotadores suportam a família de funções stat().

### Veja Também

- lstat() - Obtém informações sobre um arquivo ou ligação simbólica
- fstat() - Lê informações sobre um arquivo usando um ponteiro de arquivo aberto
- filemtime() - Obtém o horário de modificação do arquivo
- filegroup() - Lê o grupo do arquivo
- SplFileInfo

# symlink

(PHP 4, PHP 5, PHP 7, PHP 8)

symlink — Cria uma ligação simbólica

### Descrição

function symlink(string `$target`, string `$link`): bool

symlink() cria uma ligação simbólica ao alvo existente em `target` com o nome especificado em `link`.

### Parâmetros

`target`

  Alvo da ligação.

`link`

  O nome da ligação.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

A função falha e emite um `E_WARNING`, se `link` já existir. No Windows, a função também falha e emite um `E_WARNING` se `target` não existir.

### Exemplos

Exemplo #1 Cria uma ligação simbólica

    <?php
    $target = 'uploads.php';
    $link = 'uploads';
    symlink($target, $link);

    echo readlink($link);
    ?>

### Veja Também

- is_link() - Informa se o arquivo é uma ligação simbólica
- link() - Criando uma ligação rígida
- readlink() - Retornar o alvo de uma ligação simbólica
- linkinfo() - Obtém informação sobre uma ligação
- unlink() - Apaga um arquivo

# tempnam

(PHP 4, PHP 5, PHP 7, PHP 8)

tempnam — Cria arquivo com nome único

### Descrição

function tempnam(string `$directory`, string `$prefix`): string|false

Cria um arquivo com nome único, com permissões de acesso definidas para 0600, no diretório especificado. Se o diretório não existir ou não puder ser escrito, tempnam() pode gerar um arquivo no diretório temporário do sistema e retornar o caminho completo ao arquivo, incluindo seu nome.

### Parâmetros

`directory`

  O diretório onde o arquivo temporário será criado.

`prefix`

  O prefixo do nome do arquivo temporário gerado.

  > Nota: Apenas os primeiros 63 caracteres do prefixo são usados, o restante é ignorado. Windows usa apenas os primeiros três caracteres do prefixo.

### Valor Retornado

Retorna o novo nome do arquivo temporário (com caminho), ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | O nome dos arquivos criados por tempnam() agora é 13 bytes mais longo. O comprimento total ainda depende da plataforma.
7.1.0 | tempnam() agora emite um aviso ao cair de volta no diretório temporário do sistema.

### Exemplos

Exemplo #1 Exemplo de tempnam()

    <?php
    $tmpfname = tempnam ("/tmp", "FOO");

    $handle = fopen($tmpfname, "w");
    fwrite($handle, "writing to tempfile");
    fclose($handle);

    // faz alguma coisa

    unlink($tmpfname);
    ?>

### Notas

> Nota: Se o PHP não conseguir criar um arquivo no diretório informado `directory`, ele cria no diretório padrão do sistema. No sistema de arquivos NTFS isto também acontece se o diretório especificado em `directory` contiver mais que 65534 arquivos.

### Veja Também

- tmpfile() - Cria um arquivo temporário
- sys_get_temp_dir() - Retorna o caminho do diretório usado para arquivos temporários
- unlink() - Apaga um arquivo

# tmpfile

(PHP 4, PHP 5, PHP 7, PHP 8)

tmpfile — Cria um arquivo temporário

### Descrição

function tmpfile(): resource|false

Cria um arquivo temporário com um nome único em modo de leitura-gravação-binário (w+b) e retorna um manipulador do arquivo.

O arquivo é automaticamente removido quando ele é fechado (por exemplo, ao chamar fclose(), ou quando não há mais referências para o manipulador do arquivo retornado por tmpfile()), ou quando o script finalizar.

Cuidado

Se o script terminar inesperadamente, o arquivo temporário pode não ser removido.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o manipulador de arquivo, similar ao que é retornado por fopen(), para o novo arquivo ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo da tmpfile()

    <?php
    $temp = tmpfile();
    fwrite($temp, "escrevendo no arquivo temporario");
    fseek($temp, 0);
    echo fread($temp, 1024);
    fclose($temp); // isto remove o arquivo
    ?>

O exemplo acima produzirá:

    writing to tempfile

### Veja Também

- tempnam() - Cria arquivo com nome único
- sys_get_temp_dir() - Retorna o caminho do diretório usado para arquivos temporários

# touch

(PHP 4, PHP 5, PHP 7, PHP 8)

touch — Define horário de acesso e de modificação de arquivo

### Descrição

function touch(string `$filename`, ?int `$mtime` = `null`, ?int `$atime` = `null`): bool

Tenta mudar os horários de acesso e modificação do arquivo no parâmetro `filename` para o valor informado em `mtime`. Note que o horário de acesso é sempre modificado, independente do número de parâmetros.

Se o arquivo não existe, ele será criado.

### Parâmetros

`filename`

  O nome do arquivo a ser atualizado.

`mtime`

  Horário da atualização. Se `mtime` for `null`, o horário atual do sistema (time()) é usado.

`atime`

  Se não `null`, o horário de acesso do arquivo é definido para o valor de `atime`. Caso contrário, é definido para o valor passado ao parâmetro `mtime`. Se ambos forem `null`, o horário atual do sistema é usado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `mtime` e `atime` agora podem ser nulos.

### Exemplos

Exemplo #1 Exemplo da função touch()

    <?php
    if (touch ($nomedoarquivo)) {
        echo 'O horário de ' . $nomedoarquivo . ' foi modificado para o horário atual';
    } else {
        echo 'Desculpe, não foi possivel modificar o horário de ' . $nomedoarquivo;
    }
    ?>

Exemplo #2 touch() usando o parâmetro `mtime`

    <?php
    // Este é o horário de modificação, vamos defini-lo para uma hora no passado.
    $hora = time() - 3600;

    // Toca o arquivo
    if (!touch('algum_arquivo.txt', $hora)) {
        echo 'Opa, algo deu errado...';
    } else {
        echo 'Horário modificado com sucesso';
    }
    ?>

### Notas

> Nota: Note que a resolução de tempo pode variar de um sistema de arquivos para outro.

# umask

(PHP 4, PHP 5, PHP 7, PHP 8)

umask — Modificar a umask atual

### Descrição

function umask(?int `$mask` = `null`): int

umask() modifica o umask do PHP para a `mask` & 0777 e retorna o umask antigo. Quando o PHP está sendo usado como um módulo de servidor, o umask é restaurado ao final de cada requisição.

### Parâmetros

`mask`

  A nova máscara.

### Valor Retornado

Se `mask` for `null`, umask() simplesmente retorna a umask atual senão a umask antiga é retornada.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `mask` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo da umask()

    <?php
    $umaskAntigo = umask(0);
    chmod("/caminho/diretorio/arquivo.txt", 0755);
    umask($umaskAntigo);

    // Checking
    if ($umaskAntigo != umask()) {
        die('Ocorreu um erro ao voltar para o umask antigo');
    }
    ?>

### Notas

> Nota:

> Evite usar esta função em servidores web multithreaded. É melhor modificar as permissões do arquivo com chmod() depois de criar o arquivo. Usando umask() pode levar a comportamento inesperado de scripts executados concorrentemente e do próprio webserver porque todos eles usam a mesma umask.

# unlink

(PHP 4, PHP 5, PHP 7, PHP 8)

unlink — Apaga um arquivo

### Descrição

function unlink(string `$filename`, ?resource `$context` = `null`): bool

Apaga o arquivo `filename`. Similar a função do C no Unix unlink(). Emite um erro `E_WARNING` level no caso de falha.

### Parâmetros

`filename`

  Caminho para o arquivo.

  Se o arquivo for uma ligação simbólica, a ligação será apagada. No Windows, para apagar uma ligação para um diretório, deve ser utilizada a função rmdir().

`context`
  Um resource de contexto de fluxo.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
7.3.0 | No Windows, agora é possível realizar o unlink() em arquivos abertos, quando antes isso falhava. Entretanto, ainda não é possível de recriar o arquivo apagado, até que o acessos ao arquivo anterior tenham sido fechados.

### Exemplos

Exemplo #1 Exemplo de unlink()

    <?php
    $fh = fopen('test.html', 'a');
    fwrite($fh, '<h1>Hello world!</h1>');
    fclose($fh);

    unlink('test.html');
    ?>

### Veja Também

- rmdir() - Remove um diretório

## Índice

- basename — Retorna a última parte do caminho
- chgrp — Altera o grupo do arquivo
- chmod — Modifica as permissões do arquivo
- chown — Modifica o proprietário do arquivo
- clearstatcache — Limpa o cache de estado de arquivos
- copy — Copia arquivo
- delete — Consulte unlink ou unset
- dirname — Retorna o caminho para o diretório pai
- disk_free_space — Retorna o espaço disponível no sistema de arquivos ou partição de disco
- disk_total_space — Retorna o tamanho total de um sistema de arquivos ou partição de disco
- diskfreespace — Sinônimo de disk_free_space
- fclose — Fecha um ponteiro de arquivo aberto
- fdatasync — Sincroniza dados (mas não metadados) ao arquivo
- feof — Testa pelo fim-de-arquivo em um ponteiro de arquivo
- fflush — Força a liberação do buffer para um arquivo
- fgetc — Lê um caractere do ponteiro de arquivo
- fgetcsv — Lê uma linha do ponteiro de arquivos e a interpreta como campos CSV
- fgets — Lê uma linha de um ponteiro de arquivo
- fgetss — Ler uma linha de um ponteiro de arquivo e retira as tags HTML
- file — Lê todo o arquivo para um array
- file_exists — Verifica se um arquivo ou diretório existe
- file_get_contents — Lê todo o conteúdo de um arquivo para uma string
- file_put_contents — Escreve dados em um arquivo
- fileatime — Obtém o último horário de acesso do arquivo
- filectime — Obtém o horário de modificação de inode do arquivo
- filegroup — Lê o grupo do arquivo
- fileinode — Lê o inode do arquivo
- filemtime — Obtém o horário de modificação do arquivo
- fileowner — Obtem o proprietário do arquivo
- fileperms — Obtém permissões de arquivo
- filesize — Obtém o tamanho do arquivo
- filetype — Lê o tipo do arquivo
- flock — Travamento consultivo portável de arquivo
- fnmatch — Compara nome de arquivo com um padrão
- fopen — Abre um arquivo ou URL
- fpassthru — Imprime todos os dados restantes de um ponteiro de arquivo
- fputcsv — Formata a linha como CSV e a escreve em um ponteiro de arquivo
- fputs — Sinônimo de fwrite
- fread — Leitura de arquivo segura para binário
- fscanf — Interpreta a leitura de um arquivo de acordo com um formato
- fseek — Aponta para uma posição no arquivo
- fstat — Lê informações sobre um arquivo usando um ponteiro de arquivo aberto
- fsync — Sincroniza mudanças ao arquivo (incluindo metadados)
- ftell — Retorna a posição atual do ponteiro de leitura/gravação do arquivo
- ftruncate — Trunca um arquivo a um tamanho especificado
- fwrite — Escrita binary-safe em arquivos
- glob — Encontra caminhos que combinam com uma expressão
- is_dir — Diz se o caminho é um diretório
- is_executable — Diz se um arquivo é executável
- is_file — Informa se o arquivo é um arquivo comum
- is_link — Informa se o arquivo é uma ligação simbólica
- is_readable — Diz se o arquivo existe e se ele pode ser lido
- is_uploaded_file — Informa se o arquivo foi enviado por POST HTTP
- is_writable — Diz se o arquivo pode ser modificado
- is_writeable — Sinônimo de is_writable
- lchgrp — Modifica o grupo de proprietário da ligação simbólica
- lchown — Modifica o proprietário da ligação simbólica
- link — Criando uma ligação rígida
- linkinfo — Obtém informação sobre uma ligação
- lstat — Obtém informações sobre um arquivo ou ligação simbólica
- mkdir — Cria um diretório
- move_uploaded_file — Move um arquivo enviado para uma nova localização
- parse_ini_file — Interpreta um arquivo de configuração
- parse_ini_string — Interpreta uma string de configuração
- pathinfo — Retorna informações sobre um caminho de arquivo
- pclose — Fecha o ponteiro de arquivo de processo
- popen — Abre um processo como ponteiro de arquivo
- readfile — Exibe o conteúdo de um arquivo
- readlink — Retornar o alvo de uma ligação simbólica
- realpath — Retorna o path absoluto canonizado
- realpath_cache_get — Obter entradas de cache do caminho absoluto
- realpath_cache_size — Obter o tamanho do cache do caminho absoluto
- rename — Renomeia um arquivo ou diretório
- rewind — Retrocede a posição de um ponteiro de arquivos
- rmdir — Remove um diretório
- set_file_buffer — Sinônimo de stream_set_write_buffer
- stat — Obtém informações sobre um arquivo
- symlink — Cria uma ligação simbólica
- tempnam — Cria arquivo com nome único
- tmpfile — Cria um arquivo temporário
- touch — Define horário de acesso e de modificação de arquivo
- umask — Modificar a umask atual
- unlink — Apaga um arquivo

- Instalação/Configuração
  - Configurações em Execução
  - Tipos de Recurso
- Constantes predefinidas
- Funções de Filesystem
  - basename — Retorna a última parte do caminho
  - chgrp — Altera o grupo do arquivo
  - chmod — Modifica as permissões do arquivo
  - chown — Modifica o proprietário do arquivo
  - clearstatcache — Limpa o cache de estado de arquivos
  - copy — Copia arquivo
  - delete — Consulte unlink ou unset
  - dirname — Retorna o caminho para o diretório pai
  - disk_free_space — Retorna o espaço disponível no sistema de arquivos ou partição de disco
  - disk_total_space — Retorna o tamanho total de um sistema de arquivos ou partição de disco
  - diskfreespace — Sinônimo de disk_free_space
  - fclose — Fecha um ponteiro de arquivo aberto
  - fdatasync — Sincroniza dados (mas não metadados) ao arquivo
  - feof — Testa pelo fim-de-arquivo em um ponteiro de arquivo
  - fflush — Força a liberação do buffer para um arquivo
  - fgetc — Lê um caractere do ponteiro de arquivo
  - fgetcsv — Lê uma linha do ponteiro de arquivos e a interpreta como campos CSV
  - fgets — Lê uma linha de um ponteiro de arquivo
  - fgetss — Ler uma linha de um ponteiro de arquivo e retira as tags HTML
  - file — Lê todo o arquivo para um array
  - file_exists — Verifica se um arquivo ou diretório existe
  - file_get_contents — Lê todo o conteúdo de um arquivo para uma string
  - file_put_contents — Escreve dados em um arquivo
  - fileatime — Obtém o último horário de acesso do arquivo
  - filectime — Obtém o horário de modificação de inode do arquivo
  - filegroup — Lê o grupo do arquivo
  - fileinode — Lê o inode do arquivo
  - filemtime — Obtém o horário de modificação do arquivo
  - fileowner — Obtem o proprietário do arquivo
  - fileperms — Obtém permissões de arquivo
  - filesize — Obtém o tamanho do arquivo
  - filetype — Lê o tipo do arquivo
  - flock — Travamento consultivo portável de arquivo
  - fnmatch — Compara nome de arquivo com um padrão
  - fopen — Abre um arquivo ou URL
  - fpassthru — Imprime todos os dados restantes de um ponteiro de arquivo
  - fputcsv — Formata a linha como CSV e a escreve em um ponteiro de arquivo
  - fputs — Sinônimo de fwrite
  - fread — Leitura de arquivo segura para binário
  - fscanf — Interpreta a leitura de um arquivo de acordo com um formato
  - fseek — Aponta para uma posição no arquivo
  - fstat — Lê informações sobre um arquivo usando um ponteiro de arquivo aberto
  - fsync — Sincroniza mudanças ao arquivo (incluindo metadados)
  - ftell — Retorna a posição atual do ponteiro de leitura/gravação do arquivo
  - ftruncate — Trunca um arquivo a um tamanho especificado
  - fwrite — Escrita binary-safe em arquivos
  - glob — Encontra caminhos que combinam com uma expressão
  - is_dir — Diz se o caminho é um diretório
  - is_executable — Diz se um arquivo é executável
  - is_file — Informa se o arquivo é um arquivo comum
  - is_link — Informa se o arquivo é uma ligação simbólica
  - is_readable — Diz se o arquivo existe e se ele pode ser lido
  - is_uploaded_file — Informa se o arquivo foi enviado por POST HTTP
  - is_writable — Diz se o arquivo pode ser modificado
  - is_writeable — Sinônimo de is_writable
  - lchgrp — Modifica o grupo de proprietário da ligação simbólica
  - lchown — Modifica o proprietário da ligação simbólica
  - link — Criando uma ligação rígida
  - linkinfo — Obtém informação sobre uma ligação
  - lstat — Obtém informações sobre um arquivo ou ligação simbólica
  - mkdir — Cria um diretório
  - move_uploaded_file — Move um arquivo enviado para uma nova localização
  - parse_ini_file — Interpreta um arquivo de configuração
  - parse_ini_string — Interpreta uma string de configuração
  - pathinfo — Retorna informações sobre um caminho de arquivo
  - pclose — Fecha o ponteiro de arquivo de processo
  - popen — Abre um processo como ponteiro de arquivo
  - readfile — Exibe o conteúdo de um arquivo
  - readlink — Retornar o alvo de uma ligação simbólica
  - realpath — Retorna o path absoluto canonizado
  - realpath_cache_get — Obter entradas de cache do caminho absoluto
  - realpath_cache_size — Obter o tamanho do cache do caminho absoluto
  - rename — Renomeia um arquivo ou diretório
  - rewind — Retrocede a posição de um ponteiro de arquivos
  - rmdir — Remove um diretório
  - set_file_buffer — Sinônimo de stream_set_write_buffer
  - stat — Obtém informações sobre um arquivo
  - symlink — Cria uma ligação simbólica
  - tempnam — Cria arquivo com nome único
  - tmpfile — Cria um arquivo temporário
  - touch — Define horário de acesso e de modificação de arquivo
  - umask — Modificar a umask atual
  - unlink — Apaga um arquivo

# Inotify

# Introdução

A extensão inotify expõe as funções inotify_init(), inotify_add_watch() e inotify_rm_watch().

Como a função C inotify_init() retorna um descritor de arquivo, a inotify_init() do PHP retorna um recurso de fluxo, utilizável com funções de fluxo padrão, como stream_select(), stream_set_blocking() e fclose(). inotify_read() substitui a forma C de ler eventos inotify.

# Instalação/Configuração

## Índice

- Instalação/Configuração
- Tipos de Recurso

## Instalação/Configuração

Esta extensão » PECL não é distribuída com o PHP.

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/inotify.

## Tipos de Recurso

Esta extensão define um recurso de fluxo retornado por inotify_init().

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

Constantes Inotify utilizáveis com inotify_add_watch() e/ou retornadas por inotify_read()
`IN_ACCESS` (int)
  Arquivo foi acessado (lido) (*)
`IN_MODIFY` (int)
  O arquivo foi modificado (*)
`IN_ATTRIB` (int)
  Metadados alterados (por exemplo, permissões, data/horário de modificação etc.) (*)
`IN_CLOSE_WRITE` (int)
  Arquivo aberto para escrita foi fechado (*)
`IN_CLOSE_NOWRITE` (int)
  Arquivo não aberto para escrita foi fechado (*)
`IN_OPEN` (int)
  O arquivo foi aberto (*)
`IN_MOVED_TO` (int)
  Arquivo movido para o diretório monitorado (*)
`IN_MOVED_FROM` (int)
  Arquivo movido para fora do diretório monitorado (*)
`IN_CREATE` (int)
  Arquivo ou diretório criado no diretório monitorado (*)
`IN_DELETE` (int)
  Arquivo ou diretório excluído no diretório monitorado (*)
`IN_DELETE_SELF` (int)
  O arquivo ou diretório monitorado foi excluído
`IN_MOVE_SELF` (int)
  O arquivo ou diretório monitorado foi movido
`IN_CLOSE` (int)
  Igual a IN_CLOSE_WRITE | IN_CLOSE_NOWRITE
`IN_MOVE` (int)
  Igual a IN_MOVED_FROM | IN_MOVED_TO
`IN_ALL_EVENTS` (int)
  Máscara de bits de todas as constantes acima
`IN_UNMOUNT` (int)
  O sistema de arquivos que contém o objeto monitorado foi desmontado
`IN_Q_OVERFLOW` (int)
  A fila de eventos estourou (wd é -1 para este evento)
`IN_IGNORED` (int)
  O monitoramento foi removido (explicitamente por inotify_rm_watch() ou porque o arquivo foi removido ou o sistema de arquivos foi desmontado)
`IN_ISDIR` (int)
  O sujeito deste evento é um diretório
`IN_ONLYDIR` (int)
  Somente monitora o nome do caminho se for um diretório (desde o Linux 2.6.15)
`IN_DONT_FOLLOW` (int)
  Não remove a referência do caminho se for uma ligação simbólica (desde o Linux 2.6.15)
`IN_MASK_ADD` (int)
  Adiciona eventos para a máscara de monitoramento para este nome de caminho, se ele já existir (em vez de substituir a máscara).
`IN_ONESHOT` (int)
  Monitora o nome do caminho de um evento e remove-o da lista de monitoramento.

> Nota: Os eventos marcados com um asterisco (*) acima podem ocorrer para arquivos em diretórios monitorados.

# Funções de Inotify

# inotify_add_watch

(PECL inotify >= 0.1.2)

inotify_add_watch — Adiciona um monitoramento a uma instância Inotify inicializada

### Descrição

function inotify_add_watch(resource `$inotify_instance`, string `$pathname`, int `$mask`): int|false

inotify_add_watch() adiciona um novo monitoramento ou modifica um monitoramento existente para o arquivo ou diretório especificado em `pathname`.

Usar inotify_add_watch() em um objeto monitorado substitui o monitoramento existente. Usar a constante `IN_MASK_ADD` adiciona eventos (com o operador OR) ao monitoramento existente.

### Parâmetros

`inotify_instance`
  Um resource retornado por inotify_init()
`pathname`
  Arquivo ou diretório a ser monitorado.
`mask`
  Eventos a serem monitorados. Consulte Constantes Predefinidas.

### Valor Retornado

O valor de retorno é um descritor de monitoramento exclusivo (em toda a instância do Inotify), ou `false` em caso de falha.

### Veja Também

- inotify_init() - Inicializa uma instância do Inotify

# inotify_init

(PECL inotify >= 0.1.2)

inotify_init — Inicializa uma instância do Inotify

### Descrição

function inotify_init(): resource|false

Inicializa uma instância do Inotify para uso com inotify_add_watch().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um recurso de fluxo ou `false` em caso de erro.

### Exemplos

Exemplo #1 Exemplo de uso de Inotify

    <?php
    // Abre uma instância Inotify
    $fd = inotify_init();

    // Monitora __FILE__ para alterações de metadados (por exemplo, data/horário de modificação)
    $watch_descriptor = inotify_add_watch($fd, __FILE__, IN_ATTRIB);

    // Gera um evento
    touch(__FILE__);

    // Lê os eventos
    $events = inotify_read($fd);
    print_r($events);

    // Os métodos a seguir permitem usar funções Inotify sem bloquear em inotify_read():

    // - Usando stream_select() em $fd:
    $read = array($fd);
    $write = null;
    $except = null;
    stream_select($read,$write,$except,0);

    // - Usando stream_set_blocking() em $fd
    stream_set_blocking($fd, 0);
    inotify_read($fd); // Não bloqueia e retorna falso se nenhum evento estiver pendente

    // - Usando inotify_queue_len() para verificar se a fila de eventos não está vazia
    $queue_len = inotify_queue_len($fd); // Se > 0, inotify_read() não irá bloquear

    // Encerra o monitoramento __FILE__ para alterações de metadados
    inotify_rm_watch($fd, $watch_descriptor);

    // Fecha a instância do Inotify
    // Isso pode encerrar todos os monitoramentos se isso ainda não tiver sido feito
    fclose($fd);

    ?>

O exemplo acima produzirá algo semelhante a:

    array(
      array(
        'wd' => 1,     // Igual a $watch_descriptor
        'mask' => 4,   // Bit IN_ATTRIB definido
        'cookie' => 0, // ID esclusivo para conectar eventos relacionados (ex.:
                       // eventos IN_MOVE_FROM e IN_MOVE_TO)
        'name' => '',  // o nome de um arquivo (ex.: se as alterações são monitoradas
                       // em um diretório)
      ),
    );

### Veja Também

- inotify_add_watch() - Adiciona um monitoramento a uma instância Inotify inicializada
- inotify_rm_watch() - Remove um monitoramento existente de uma instância do Inotify
- inotify_queue_len() - Retorna um número maior que zero se houver eventos pendentes
- inotify_read() - Lê eventos de uma instância do Inotify
- fclose() - Fecha um ponteiro de arquivo aberto

# inotify_queue_len

(PECL inotify >= 0.1.2)

inotify_queue_len — Retorna um número maior que zero se houver eventos pendentes

### Descrição

function inotify_queue_len(resource `$inotify_instance`): int

Esta função permite saber se inotify_read() irá bloquear ou não. Se um número maior que zero for retornado, há eventos pendentes e inotify_read() não irá bloquear.

### Parâmetros

`inotify_instance`
  Um resource retornado por inotify_init()

### Valor Retornado

Retorna um número maior que zero se houver eventos pendentes.

### Veja Também

- inotify_init() - Inicializa uma instância do Inotify
- stream_select() - Executa o equivalente à chamada de sistema select() nos arrays de fluxos informados com um limite de tempo especificado por segundos e microssegundos
- stream_set_blocking() - Definir modo de bloqueio/não-bloqueio em um fluxo

# inotify_read

(PECL inotify >= 0.1.2)

inotify_read — Lê eventos de uma instância do Inotify

### Descrição

function inotify_read(resource `$inotify_instance`): array

Lê eventos do Inotify de uma instância do Inotify.

### Parâmetros

`inotify_instance`
  Um resource retornado por inotify_init()

### Valor Retornado

Um array de eventos Inotify ou `false` se nenhum evento estiver pendente e `inotify_instance` for não-bloqueante. Cada evento é um array com as seguintes chaves:

- "wd" é um descritor de monitoramento retornado por inotify_add_watch()
- "mask" é uma máscara de bits de eventos
- "cookie" é um ID exclusivo para conectar eventos relacionados (ex.: `IN_MOVE_FROM` e `IN_MOVE_TO`)
- "name" é o nome de um arquivo (ex.: se um arquivo foi modificado em um diretório monitorado)

### Veja Também

- inotify_init() - Inicializa uma instância do Inotify
- stream_select() - Executa o equivalente à chamada de sistema select() nos arrays de fluxos informados com um limite de tempo especificado por segundos e microssegundos
- stream_set_blocking() - Definir modo de bloqueio/não-bloqueio em um fluxo
- inotify_queue_len() - Retorna um número maior que zero se houver eventos pendentes

# inotify_rm_watch

(PECL inotify >= 0.1.2)

inotify_rm_watch — Remove um monitoramento existente de uma instância do Inotify

### Descrição

function inotify_rm_watch(resource `$inotify_instance`, int `$watch_descriptor`): bool

inotify_rm_watch() remove o monitoramento `watch_descriptor` da instância `inotify_instance` no Inotify.

### Parâmetros

`inotify_instance`
  Um resource retornado por inotify_init()
`watch_descriptor`
  Monitoramento a ser removido da instância.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- inotify_init() - Inicializa uma instância do Inotify

## Índice

- inotify_add_watch — Adiciona um monitoramento a uma instância Inotify inicializada
- inotify_init — Inicializa uma instância do Inotify
- inotify_queue_len — Retorna um número maior que zero se houver eventos pendentes
- inotify_read — Lê eventos de uma instância do Inotify
- inotify_rm_watch — Remove um monitoramento existente de uma instância do Inotify

- Instalação/Configuração
  - Instalação/Configuração
  - Tipos de Recurso
- Constantes predefinidas
- Funções de Inotify
  - inotify_add_watch — Adiciona um monitoramento a uma instância Inotify inicializada
  - inotify_init — Inicializa uma instância do Inotify
  - inotify_queue_len — Retorna um número maior que zero se houver eventos pendentes
  - inotify_read — Lê eventos de uma instância do Inotify
  - inotify_rm_watch — Remove um monitoramento existente de uma instância do Inotify

# xattr

# Introdução

A extensão xattr permite a manipulação de atributos estendidos em um sistema de arquivos.

# Instalação/Configuração

## Índice

- Dependências
- Instalação

## Dependências

Para usar xattr, você precisará ter a biblioteca libattr instalada no seu sistema. Ela está disponível em » http://savannah.nongnu.org/projects/attr/.

> Nota:

> Essas funções só funcionarão em sistemas de arquivos que suportam atributos estendidos, e os quais tenham esses atributos habilitados no momento da montagem. Alguns sistemas de arquivos que suportam atributos estendidos são `ext2`, `ext3`, `reiserfs`, `jfs` e `xfs`.

## Instalação

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/xattr.

Uma DLL para esta extensão PECL não está disponível no momento. Veja também a seção Compilando no Windows.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`XATTR_ROOT` (int)
  Edita atributo no namespace do administrador. Requer privilégios de root.
`XATTR_DONTFOLLOW` (int)
  Não segue o link simbólico mas opera no link em si.
`XATTR_CREATE` (int)
  Função falhará se o atributo estendido já existir.
`XATTR_REPLACE` (int)
  Função falhará se atributo estendido não existir.

# Funções da xattr

# xattr_get

(PECL xattr >= 0.9.0)

xattr_get — Obtém um atributo estendido

### Descrição

function xattr_get(string `$filename`, string `$name`, int `$flags` = 0): string|false

Esta função obtém o valor de um atributo estendido de um arquivo.

Os atributos estendidos têm dois namespaces diferentes: usuário e root. O namespace de usuário está disponível para todos os usuários, enquanto o namespace de root está disponível apenas para o usuário com privilégios de root. xattr opera no namespace de usuário por padrão, mas isso pode ser alterado com o parâmetro `flags`.

### Parâmetros

`filename`

  O arquivo do qual o atributo será obtido.

`name`

  O nome do atributo.

`flags`

  Opções suportadas por xattr
  `XATTR_DONTFOLLOW` | Não segue o link simbólico mas opera no link em si.
  `XATTR_ROOT` | Define o atributo no espaço de nomes (confiável) do administrador. Requer privilégios de administrador.

### Valor Retornado

Retorna uma string contento o valor ou `false` se o atributo não existir.

### Exemplos

Exemplo #1 Verifica se o adminitrador do sistema assinou o arquivo

    <?php
    $file = '/usr/local/sbin/some_binary';
    $signature = xattr_get($file, 'Root signature', XATTR_ROOT);

    /* ... verifica se $signature é válida ... */

    ?>

### Veja Também

- xattr_list() - Obtém uma lista de atributos estendidos
- xattr_set() - Define um atributo estendido
- xattr_remove() - Remove um atributo estendido

# xattr_list

(PECL xattr >= 0.9.0)

xattr_list — Obtém uma lista de atributos estendidos

### Descrição

function xattr_list(string `$filename`, int `$flags` = 0): array

Esta função obtém uma lista de nomes de atributos estendidos de um arquivo.

Os atributos estendidos têm dois namespaces diferentes: usuário e root. O namespace de usuário está disponível para todos os usuários, enquanto o namespace de root está disponível apenas para o usuário com privilégios de root. xattr opera no namespace de usuário por padrão, mas isso pode ser alterado com o parâmetro `flags`.

### Parâmetros

`filename`

  O caminho do arquivo.

`flags`

  Opções suportadas por xattr
  `XATTR_DONTFOLLOW` | Não segue o link simbólico mas opera no link em si.
  `XATTR_ROOT` | Define o atributo no espaço de nomes (confiável) do administrador. Requer privilégios de administrador.

### Valor Retornado

Esta função retorna um array com nomes de atributos estendidos.

### Exemplos

Exemplo #1 Exibe nomes de todos os atributos estendidos do arquivo

    <?php
    $file = 'some_file';
    $root_attributes = xattr_list($file, XATTR_ROOT);
    $user_attributes = xattr_list($file);

    echo "Atributos de administrador: \n";
    foreach ($root_attributes as $attr_name) {
        printf("%s\n", $attr_name);
    }

    echo "\n Atributos de usuário: \n";
    foreach ($user_attributes as $attr_name) {
        printf("%s\n", $attr_name);
    }

    ?>

### Veja Também

- xattr_get() - Obtém um atributo estendido

# xattr_remove

(PECL xattr >= 0.9.0)

xattr_remove — Remove um atributo estendido

### Descrição

function xattr_remove(string `$filename`, string `$name`, int `$flags` = 0): bool

Esta função remove um atributo estendido de um arquivo.

Os atributos estendidos têm dois namespaces diferentes: usuário e root. O namespace de usuário está disponível para todos os usuários, enquanto o namespace de root está disponível apenas para o usuário com privilégios de root. xattr opera no namespace de usuário por padrão, mas isso pode ser alterado com o parâmetro `flags`.

### Parâmetros

`filename`

  O arquivo do qual o atributo será removido.

`name`

  O nome do atributo a ser removido.

`flags`

  Opções suportadas por xattr
  `XATTR_DONTFOLLOW` | Não segue o link simbólico mas opera no link em si.
  `XATTR_ROOT` | Define o atributo no espaço de nomes (confiável) do administrador. Requer privilégios de administrador.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Remove todos os atributos estendidos de um arquivo

    <?php
    $file = 'some_file';
    $attributes = xattr_list($file);

    foreach ($attributes as $attr_name) {
        xattr_remove($file, $attr_name);
    }
    ?>

### Veja Também

- xattr_list() - Obtém uma lista de atributos estendidos
- xattr_set() - Define um atributo estendido
- xattr_get() - Obtém um atributo estendido

# xattr_set

(PECL xattr >= 0.9.0)

xattr_set — Define um atributo estendido

### Descrição

function xattr_set(
string `$filename`,
string `$name`,
string `$value`,
int `$flags` = 0
): bool

Esta função define o valor de um atributo estendido de um arquivo.

Os atributos estendidos têm dois namespaces diferentes: usuário e root. O namespace de usuário está disponível para todos os usuários, enquanto o namespace de root está disponível apenas para o usuário com privilégios de root. xattr opera no namespace de usuário por padrão, mas isso pode ser alterado com o parâmetro `flags`.

### Parâmetros

`filename`

  O arquivo no qual o atributo será definido.

`name`

  O nome do atributo estendido. Este atributo será criado se não existir ou, caso contrário, será substituído. Este comportamento pode ser alterado usando o parâmetro `flags`.

`value`

  O valor do atributo.

`flags`

  Opções suportadas por xattr
  `XATTR_CREATE` | A função falhará se o atributo estendido já existir.
  `XATTR_REPLACE` | A função falhará se o atributo estendido não existir.
  `XATTR_DONTFOLLOW` | Não segue o link simbólico mas opera no link em si.
  `XATTR_ROOT` | Define o atributo no espaço de nomes (confiável) do administrador. Requer privilégios de administrador.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Define atributos estendidos no arquivo .wav

    <?php
    $file = 'minha_música_favorita.wav';
    xattr_set($file, 'Artista', 'Alguém');
    xattr_set($file, 'Minha avaliação', 'Boa');
    xattr_set($file, 'Quantas vezes foi ouvida', '34');

    /* ... outro código ... */

    printf("Você ouviu esta música %d vezes", xattr_get($file, 'Quantas vezes foi ouvida'));
    ?>

### Veja Também

- xattr_get() - Obtém um atributo estendido
- xattr_remove() - Remove um atributo estendido

# xattr_supported

(PECL xattr >= 1.0.0)

xattr_supported — Verifique se o sistema de arquivos suporta atributos estendidos

### Descrição

function xattr_supported(string `$filename`, int `$flags` = 0): bool

Esta função verifica se o sistema de arquivos que contém o arquivo fornecido suporta atributos estendidos. É necessário acesso de leitura ao arquivo.

### Parâmetros

`filename`

  O caminho do arquivo testado.

`flags`

  Opções suportadas por xattr
  `XATTR_DONTFOLLOW` | Não segue o link simbólico mas opera no link em si.

### Valor Retornado

Esta função retorna `true` se o sistema de arquivos suportar atributos estendidos, `false` se não suportar e `null` se não puder ser determinado (por exemplo, caminho errado ou falta de permissões para o arquivo).

### Exemplos

Exemplo #1 Exemplo de xattr_supported()

O código a seguir verifica se podemos usar atributos estendidos.

    <?php
    $file = 'algum_arquivo';

    if (xattr_supported($file)) {
        /* ... uso de algumas funções xattr_* ... */
    }

    ?>

### Veja Também

- xattr_get() - Obtém um atributo estendido
- xattr_list() - Obtém uma lista de atributos estendidos

## Índice

- xattr_get — Obtém um atributo estendido
- xattr_list — Obtém uma lista de atributos estendidos
- xattr_remove — Remove um atributo estendido
- xattr_set — Define um atributo estendido
- xattr_supported — Verifique se o sistema de arquivos suporta atributos estendidos

- Instalação/Configuração
  - Dependências
  - Instalação
- Constantes predefinidas
- Funções da xattr
  - xattr_get — Obtém um atributo estendido
  - xattr_list — Obtém uma lista de atributos estendidos
  - xattr_remove — Remove um atributo estendido
  - xattr_set — Define um atributo estendido
  - xattr_supported — Verifique se o sistema de arquivos suporta atributos estendidos

# xdiff

# Introdução

A extensão xdiff permite que sejam criados e aplicados arquivos de patch contendo diferenças entre diferentes revisões de arquivos.

Esta extensão suporta dois modos de operação - em strings e em arquivos, bem como dois formatos de patch diferentes - unificado e binário. Patches unificados são excelentes para arquivos de texto, pois são legíveis por humanos e fáceis de revisar. Para arquivos binários, como arquivos ou imagens, patches binários serão uma escolha adequada, pois são seguros para binários e lidam bem com caracteres não imprimíveis.

A partir da versão 1.5.0, existem dois conjuntos diferentes de funções para gerar patches binários. As novas funções - xdiff_string_rabdiff() e xdiff_file_rabdiff() geram saídas compatíveis com funções mais antigas, mas geralmente são mais rápidas e geram resultados menores. Para mais detalhes sobre os métodos de geração de patches binários e as diferenças entre eles, consulte o site » libxdiff.

Esta extensão usa libxdiff para implementar essas funções. Consulte » http://www.xmailserver.org/xdiff-lib.html para mais informações.

# Instalação/Configuração

## Índice

- Dependências
- Instalação

## Dependências

Para usar o xdiff, é necessário ter o libxdiff instalado, disponível na página inicial do libxdiff » http://www.xmailserver.org/xdiff-lib.html.

> Nota:

> É necessário pelo menos o libxdiff 0.7 para que essas funções estejam cientes do limite de memória.

## Instalação

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/xdiff.

Binários do Windows (arquivos DLL) para esta extensão PECL estão disponíveis no site do PECL.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`XDIFF_PATCH_NORMAL` (int)
  Este sinalizador indica que as funções xdiff_string_patch() e xdiff_file_patch() devem criar um resultado aplicando o patch ao conteúdo original, criando assim uma versão mais recente do arquivo. Este é o modo de operação padrão.
`XDIFF_PATCH_REVERSE` (int)
  Este sinalizador indica que as funções xdiff_string_patch() e xdiff_file_patch() devem criar resultados revertendo o patch alterado do conteúdo mais recente, criando assim a versão original.

# Funções de xdiff

# xdiff_file_bdiff

(PECL xdiff >= 1.5.0)

xdiff_file_bdiff — Diferencia dois arquivos de forma binária

### Descrição

function xdiff_file_bdiff(string `$old_file`, string `$new_file`, string `$dest`): bool

Cria uma comparação binária de dois arquivos e armazena o resultado em um arquivo de patch. Esta função funciona tanto com arquivos de texto quanto com arquivos binários. O arquivo de patch resultante pode ser aplicado posteriormente usando xdiff_file_bpatch()/xdiff_string_bpatch().

### Parâmetros

`old_file`

  Caminho para o primeiro arquivo. Este arquivo atua como o arquivo "antigo".

`new_file`

  Caminho para o segundo arquivo. Este arquivo atua como um arquivo "novo".

`dest`

  Caminho do arquivo de patch resultante. O arquivo resultante contém diferenças entre os arquivos "antigo" e "novo". Em formato binário e ilegível por humanos.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de xdiff_file_bdiff()

O código a seguir faz uma comparação binária de dois arquivos.

    <?php
    $old_version = 'my_script_1.0.tgz';
    $new_version = 'my_script_1.1.tgz';

    xdiff_file_bdiff($old_version, $new_version, 'my_script.bdiff');
    ?>

### Notas

> Nota:

> Ambos os arquivos serão carregados na memória, portanto, certifique-se de que o limite de memória esteja definido como alto o suficiente.

### Veja Também

- xdiff_file_bpatch() - Corrige um arquivo com uma diferença binária

# xdiff_file_bdiff_size

(PECL xdiff >= 1.5.0)

xdiff_file_bdiff_size — Lê um tamanho de arquivo criado pela aplicação de um diff binário

### Descrição

function xdiff_file_bdiff_size(string `$file`): int

Retorna o tamanho de um arquivo de resultado que seria criado após a aplicação do patch binário do arquivo `file` ao arquivo original.

### Parâmetros

`file`

  O caminho para o patch binário criado pela função xdiff_string_bdiff() ou xdiff_string_rabdiff().

### Valor Retornado

Retorna o tamanho do arquivo que seria criado.

### Exemplos

Exemplo #1 Exemplo de xdiff_file_bdiff_size()

O código a seguir lê o tamanho do arquivo que seria criado após a aplicação de uma diferença binária.

    <?php
    $length = xdiff_string_bdiff_size('file.bdiff');
    echo "O arquivo resultante terá $length bytes de comprimento";
    ?>

### Veja Também

- xdiff_file_bdiff() - Diferencia dois arquivos de forma binária
- xdiff_file_rabdiff() - Faz a comparação binária de dois arquivos usando o algoritmo de impressão digital polinomial de Rabin
- xdiff_file_bpatch() - Corrige um arquivo com uma diferença binária

# xdiff_file_bpatch

(PECL xdiff >= 1.5.0)

xdiff_file_bpatch — Corrige um arquivo com uma diferença binária

### Descrição

function xdiff_file_bpatch(string `$file`, string `$patch`, string `$dest`): bool

Corrige o arquivo `file` com um `patch` binário e armazena o resultado no arquivo `dest`. Esta função aceita patches criados por meio das funções xdiff_file_bdiff() e xdiff_file_rabdiff() ou suas contrapartes em string.

### Parâmetros

`file`

  O arquivo original.

`patch`

  O arquivo de patch binário.

`dest`

  Caminho do arquivo resultante.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de xdiff_file_bpatch()

O código a seguir aplica comparação binária a um arquivo.

    <?php
    $old_version = 'archive-1.0.tgz';
    $patch = 'archive.bpatch';

    $result = xdiff_file_bpatch($old_version, $patch, 'archive-1.1.tgz');
    if ($result) {
       echo "Arquivo corrigido";
    } else {
       echo "O arquivo não pôde ser corrigido";
    }

    ?>

### Notas

> Nota:

> Ambos os arquivos (`file` e `patch`) serão carregados na memória, portanto, certifique-se de que o limite de memória esteja definido como alto o suficiente.

### Veja Também

- xdiff_file_bdiff() - Diferencia dois arquivos de forma binária
- xdiff_file_rabdiff() - Faz a comparação binária de dois arquivos usando o algoritmo de impressão digital polinomial de Rabin

# xdiff_file_diff

(PECL xdiff >= 0.2.0)

xdiff_file_diff — Faz uma comparação unificada de dois arquivos

### Descrição

function xdiff_file_diff(
string `$old_file`,
string `$new_file`,
string `$dest`,
int `$context` = 3,
bool `$minimal` = `false`
): bool

Faz uma comparação unificada contendo as diferenças entre `old_file` e `new_file` e o armazena no arquivo `dest`. O arquivo resultante é legível por humanos. Um parâmetro opcional `context` especifica quantas linhas de contexto devem ser adicionadas em torno de cada alteração. Definir o parâmetro `minimal` como true resultará na saída do menor arquivo de patch possível (pode levar muito tempo).

### Parâmetros

`old_file`

  Caminho para o primeiro arquivo. Este arquivo atua como o arquivo "antigo".

`new_file`

  Caminho para o segundo arquivo. Este arquivo atua como um arquivo "novo".

`dest`

  Caminho do arquivo de patch resultante.

`context`

  Indica quantas linhas de contexto devem ser incluídas no resultado da comparação.

`minimal`

  Defina este parâmetro como `true` se quiser minimizar o tamanho do resultado (pode levar muito tempo).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de xdiff_file_diff()

O código a seguir cria uma comparação unificada de dois arquivos PHP com comprimento de contexto de 2.

    <?php
    $old_version = 'my_script.php';
    $new_version = 'my_new_script.php';

    xdiff_file_diff($old_version, $new_version, 'my_script.diff', 2);
    ?>

### Notas

> Nota:

> Esta função não funciona bem com arquivos binários. Para fazer comparações de arquivos binários, use a função xdiff_file_bdiff()/xdiff_file_rabdiff().

### Veja Também

- xdiff_file_patch() - Corrige um arquivo com uma comparação unificada

# xdiff_file_diff_binary

(PECL xdiff >= 0.2.0)

xdiff_file_diff_binary — Sinônimo de xdiff_file_bdiff()

### Descrição

function xdiff_file_diff_binary(string `$old_file`, string `$new_file`, string `$dest`): bool

Cria uma comparação binária de dois arquivos e armazena o resultado em um arquivo de patch. Esta função funciona tanto com arquivos de texto quanto com arquivos binários. O arquivo de patch resultante pode ser aplicado posteriormente usando xdiff_file_bpatch().

A partir da versão 1.5.0, esta função é um sinônimo de xdiff_file_bdiff().

### Parâmetros

`old_file`

  Caminho para o primeiro arquivo. Este arquivo atua como o arquivo "antigo".

`new_file`

  Caminho para o segundo arquivo. Este arquivo atua como um arquivo "novo".

`dest`

  Caminho do arquivo de patch resultante. O arquivo resultante contém diferenças entre os arquivos "antigo" e "novo". Em formato binário e ilegível por humanos.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de xdiff_file_diff_binary()

O código a seguir faz uma comparação binária de dois arquivos.

    <?php
    $old_version = 'my_script_1.0.tgz';
    $new_version = 'my_script_1.1.tgz';

    xdiff_file_diff_binary($old_version, $new_version, 'my_script.bdiff');
    ?>

### Notas

> Nota:

> Ambos os arquivos serão carregados na memória, portanto, certifique-se de que o limite de memória esteja definido como alto o suficiente.

### Veja Também

- xdiff_file_bdiff() - Diferencia dois arquivos de forma binária
- xdiff_file_bpatch() - Corrige um arquivo com uma diferença binária

# xdiff_file_merge3

(PECL xdiff >= 0.2.0)

xdiff_file_merge3 — Mescla 3 arquivos em um

### Descrição

function xdiff_file_merge3(
string `$old_file`,
string `$new_file1`,
string `$new_file2`,
string `$dest`
): mixed

Mescla três arquivos em um e armazena o resultado em um arquivo `dest`. O `old_file` é uma versão original, enquanto o `new_file1` e o `new_file2` são versões modificadas de um original.

### Parâmetros

`old_file`

  Caminho para o primeiro arquivo. Atua como arquivo "antigo".

`new_file1`

  Caminho para o segundo arquivo. Ele atua como uma versão modificada de `old_file`.

`new_file2`

  Caminho para o terceiro arquivo. Ele atua como uma versão modificada de `old_file`.

`dest`

  Caminho do arquivo resultante, contendo as alterações mescladas de `new_file1` e `new_file2`.

### Valor Retornado

Retorna `true` se a mesclagem foi bem-sucedida, string com pedaços rejeitados se não foi ou `false` se ocorreu um erro interno.

### Exemplos

Exemplo #1 Exemplo de xdiff_file_merge3()

O código a seguir mescla três arquivos em um.

    <?php
    $old_version = 'original_script.php';
    $fix1 = 'script_with_fix1.php';
    $fix2 = 'script_with_fix2.php';

    $errors = xdiff_file_merge3($old_version, $fix1, $fix2, 'fixed_script.php');
    if (is_string($errors)) {
        echo "Rejects:\n";
        echo $errors;
    }
    ?>

### Veja Também

- xdiff_string_merge3() - Mesclar 3 strings em uma

# xdiff_file_patch

(PECL xdiff >= 0.2.0)

xdiff_file_patch — Corrige um arquivo com uma comparação unificada

### Descrição

function xdiff_file_patch(
string `$file`,
string `$patch`,
string `$dest`,
int `$flags` = DIFF_PATCH_NORMAL
): mixed

Corrige o arquivo `file` com um `patch` e armazena o resultado em um arquivo. `patch` deve ser uma comparação unificada criada pela função xdiff_file_diff()/xdiff_string_diff(). Um parâmetro opcional `flags` especifica o modo de operação.

### Parâmetros

`file`

  O arquivo original.

`patch`

  O arquivo de patch unificado. Ele deve ser criado usando as funções xdiff_string_diff(), xdiff_file_diff() ou ferramentas compatíveis.

`dest`

  Caminho do arquivo resultante.

`flags`

  Pode ser `XDIFF_PATCH_NORMAL` (modo padrão, patch normal) ou `XDIFF_PATCH_REVERSE` (patch reverso).

  A partir da versão 1.5.0, pode-se também usar a operação binária OR para habilitar o sinalizador `XDIFF_PATCH_IGNORESPACE`.

### Valor Retornado

Retorna `false` se ocorreu um erro interno, string com pedaços rejeitados se o patch não pôde ser aplicado ou `true` se o patch foi aplicado com sucesso.

### Exemplos

Exemplo #1 Exemplo de xdiff_file_patch()

O código a seguir aplica uma comparação unificada a um arquivo.

    <?php
    $old_version = 'my_script-1.0.php';
    $patch = 'my_script.patch';

    $errors = xdiff_file_patch($old_version, $patch, 'my_script-1.1.php');
    if (is_string($errors)) {
       echo "Rejects:\n";
       echo $errors;
    }

    ?>

Exemplo #2 Patch reversing example

O código a seguir reverte um patch.

    <?php
    $new_version = 'my_script-1.1.php';
    $patch = 'my_script.patch';

    $errors = xdiff_file_patch($new_version, $patch, 'my_script-1.0.php', XDIFF_PATCH_REVERSE);
    if (is_string($errors)) {
       echo "Rejects:\n";
       echo $errors;
    }

    ?>

### Veja Também

- xdiff_file_diff() - Faz uma comparação unificada de dois arquivos

# xdiff_file_patch_binary

(PECL xdiff >= 0.2.0)

xdiff_file_patch_binary — Sinônimo de xdiff_file_bpatch()

### Descrição

function xdiff_file_patch_binary(string `$file`, string `$patch`, string `$dest`): bool

Corrige o arquivo `file` com um `patch` binário e armazena o resultado no arquivo `dest`. Esta função aceita patches criados por meio das funções xdiff_file_bdiff() ou xdiff_file_rabdiff() ou suas contrapartes em string.

A partir da versão 1.5.0, esta função é um alias de xdiff_file_bpatch().

### Parâmetros

`file`

  O arquivo original.

`patch`

  O arquivo de patch binário.

`dest`

  Caminho do arquivo resultante.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de xdiff_file_patch_binary()

O código a seguir aplica comparação binária a um arquivo.

    <?php
    $old_version = 'archive-1.0.tgz';
    $patch = 'archive.bpatch';

    $result = xdiff_file_patch_binary($old_version, $patch, 'archive-1.1.tgz');
    if ($result) {
       echo "Arquivo corrigido";
    } else {
       echo "O arquivo não pôde ser corrigido";
    }

    ?>

### Notas

> Nota:

> Ambos os arquivos (`file` e `patch`) serão carregados na memória, portanto, certifique-se de que o limite de memória esteja definido como alto o suficiente.

### Veja Também

- xdiff_string_patch_binary() - Sinônimo de xdiff_string_bpatch

# xdiff_file_rabdiff

(PECL xdiff >= 1.5.0)

xdiff_file_rabdiff — Faz a comparação binária de dois arquivos usando o algoritmo de impressão digital polinomial de Rabin

### Descrição

function xdiff_file_rabdiff(string `$old_file`, string `$new_file`, string `$dest`): bool

Cria uma comparação binária de dois arquivos e armazena o resultado em um arquivo de patch. A diferença entre esta função e xdiff_file_bdiff() é o algoritmo diferente utilizado, que deve resultar em uma execução mais rápida e em uma comparação menor produzida. Esta função funciona tanto com arquivos de texto quanto binários. O arquivo de patch resultante pode ser aplicado posteriormente usando xdiff_file_bpatch()/xdiff_string_bpatch().

Para mais detalhes sobre as diferenças entre os algoritmos utilizados, consulte o site » libxdiff.

### Parâmetros

`old_file`

  Caminho para o primeiro arquivo. Este arquivo atua como o arquivo "antigo".

`new_file`

  Caminho para o segundo arquivo. Este arquivo atua como um arquivo "novo".

`dest`

  Caminho do arquivo de patch resultante. O arquivo resultante contém diferenças entre os arquivos "antigo" e "novo". Em formato binário e ilegível por humanos.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de xdiff_file_rabdiff()

O código a seguir faz uma comparação binária de dois arquivos.

    <?php
    $old_version = 'my_script_1.0.tgz';
    $new_version = 'my_script_1.1.tgz';

    xdiff_file_rabdiff($old_version, $new_version, 'my_script.bdiff');
    ?>

### Notas

> Nota:

> Ambos os arquivos serão carregados na memória, portanto, certifique-se de que o limite de memória esteja definido como alto o suficiente.

### Veja Também

- xdiff_file_bpatch() - Corrige um arquivo com uma diferença binária

# xdiff_string_bdiff

(PECL xdiff >= 1.5.0)

xdiff_string_bdiff — Faz diferença binária de duas strings

### Descrição

function xdiff_string_bdiff(string `$old_data`, string `$new_data`): string

Cria uma comparação binária de duas strings e retorna o resultado. Esta função funciona tanto com texto quanto com dados binários. O patch resultante pode ser aplicado posteriormente usando xdiff_string_bpatch()/xdiff_file_bpatch().

### Parâmetros

`old_data`

  Primeira sequência com dados binários. Atua como dados "antigos".

`new_data`

  Segunda sequência com dados binários. Atua como dados "novos".

### Valor Retornado

Retorna uma string com diferença binária contendo diferenças entre os dados "antigo" e "novo" ou `false` se ocorreu um erro interno.

### Veja Também

- xdiff_string_bpatch() - Corrige uma string com uma diferença binária

# xdiff_string_bdiff_size

(PECL xdiff >= 1.5.0)

xdiff_string_bdiff_size — Lê um tamanho de arquivo criado pela aplicação de uma comparação binária

### Descrição

function xdiff_string_bdiff_size(string `$patch`): int

Retorna o tamanho de um arquivo de resultado que seria criado após a aplicação do `patch` binário ao arquivo original.

### Parâmetros

`patch`

  O patch binário criado pela função xdiff_string_bdiff() ou xdiff_string_rabdiff().

### Valor Retornado

Retorna o tamanho do arquivo que seria criado.

### Exemplos

Exemplo #1 Exemplo de xdiff_string_bdiff_size()

O código a seguir lê o tamanho do arquivo que seria criado após a aplicação de uma diferença binária.

    <?php
    $binary_patch = file_get_contents('file.bdiff');
    $length = xdiff_string_bdiff_size($binary_patch);
    echo "O arquivo resultante terá $length bytes de comprimento";
    ?>

### Veja Também

- xdiff_string_bdiff() - Faz diferença binária de duas strings
- xdiff_string_rabdiff() - Gera a diferença binária de duas strings usando o algoritmo de impressão digital polinomial de Rabin
- xdiff_string_bpatch() - Corrige uma string com uma diferença binária

# xdiff_string_bpatch

(PECL xdiff >= 1.5.0)

xdiff_string_bpatch — Corrige uma string com uma diferença binária

### Descrição

function xdiff_string_bpatch(string `$str`, string `$patch`): string

Corrige uma string `str` com um `patch` binário. Esta função aceita patches criados tanto pelas funções xdiff_string_bdiff() quanto xdiff_string_rabdiff() ou suas contrapartes de arquivo.

### Parâmetros

`str`

  A sequência binária original.

`patch`

  A sequência de patch binária.

### Valor Retornado

Retorna a string corrigida ou `false` em caso de erro.

### Veja Também

- xdiff_string_bdiff() - Faz diferença binária de duas strings
- xdiff_string_rabdiff() - Gera a diferença binária de duas strings usando o algoritmo de impressão digital polinomial de Rabin

# xdiff_string_diff

(PECL xdiff >= 0.2.0)

xdiff_string_diff — Faz uma diferença unificada entre duas strings

### Descrição

function xdiff_string_diff(
string `$old_data`,
string `$new_data`,
int `$context` = 3,
bool `$minimal` = `false`
): string

Cria uma diferença unificada contendo as diferenças entre a string `old_data` e a string `new_data` e o retorna. A diferença resultante é legível por humanos. Um parâmetro opcional `context` especifica quantas linhas de contexto devem ser adicionadas em torno de cada alteração. Definir o parâmetro `minimal` como verdadeiro resultará na saída do menor arquivo de patch possível (pode levar muito tempo).

### Parâmetros

`old_data`

  Primeira sequência com dados. Atua como dados "antigos".

`new_data`

  Segunda sequência com dados. Atua como dados "novos".

`context`

  Indica quantas linhas de contexto você deseja incluir no resultado da diferença.

`minimal`

  Defina este parâmetro como `true` se quiser minimizar o tamanho do resultado (pode levar muito tempo).

### Valor Retornado

Retorna uma string com a diferença resultante ou `false` se ocorrer um erro interno.

### Exemplos

Exemplo #1 Exemplo de xdiff_string_diff()

O código a seguir faz uma comparação unificada de dois artigos.

    <?php
    $old_article = file_get_contents('./old_article.txt');
    $new_article = $_REQUEST['article']; /* Digamos que alguém colou um novo artigo em um formato HTML */

    $diff = xdiff_string_diff($old_article, $new_article, 1);
    if (is_string($diff)) {
        echo "Diferenças entre dois artigos:\n";
        echo $diff;
    }

    ?>

### Notas

> Nota:

> Esta função não funciona bem com strings binárias. Para obter diferenças de strings binárias, use xdiff_string_bdiff()/xdiff_string_rabdiff().

### Veja Também

- xdiff_string_patch() - Altera uma string com uma correção unificada

# xdiff_string_diff_binary

(PECL xdiff >= 0.2.0)

xdiff_string_diff_binary — Sinônimo de xdiff_string_bdiff()

### Descrição

function xdiff_string_bdiff(string `$old_data`, string `$new_data`): string

Cria uma comparação binária de duas strings e retorna o resultado. Esta função funciona tanto com texto quanto com dados binários. O patch resultante pode ser aplicado posteriormente usando xdiff_string_bpatch()/xdiff_file_bpatch().

A partir da versão 1.5.0, esta função é um sinônimo de xdiff_string_bdiff().

### Parâmetros

`old_data`

  Primeira sequência com dados binários. Atua como dados "antigos".

`new_data`

  Segunda sequência com dados binários. Atua como dados "novos".

### Valor Retornado

Retorna uma string com resultado ou `false` se ocorrer um erro interno.

### Veja Também

- xdiff_string_bdiff() - Faz diferença binária de duas strings
- xdiff_string_bpatch() - Corrige uma string com uma diferença binária

# xdiff_string_merge3

(PECL xdiff >= 0.2.0)

xdiff_string_merge3 — Mesclar 3 strings em uma

### Descrição

function xdiff_string_merge3(
string `$old_data`,
string `$new_data1`,
string `$new_data2`,
string `&$error` = ?
): mixed

Mescla três strings em uma e retorna o resultado. O `old_data` é uma versão original dos dados, enquanto `new_data1` e `new_data2` são versões modificadas de um original. Um erro opcional no parâmetro `error` opcional é usado para passar quaisquer partes rejeitadas durante o processo de mesclagem.

### Parâmetros

`old_data`

  Primeira sequência com dados. Atua como dados "antigos".

`new_data1`

  Segunda string com dados. Atua como uma versão modificada de `old_data`.

`new_data2`

  Terceira string com dados. Atua como uma versão modificada de `old_data`.

`error`

  Se fornecido, as peças rejeitadas serão armazenadas dentro desta variável.

### Valor Retornado

Retorna a string mesclada, `false` se ocorrer um erro interno, ou `true` se a string mesclada estiver vazia.

### Veja Também

- xdiff_file_merge3() - Mescla 3 arquivos em um

# xdiff_string_patch

(PECL xdiff >= 0.2.0)

xdiff_string_patch — Altera uma string com uma correção unificada

### Descrição

function xdiff_string_patch(
string `$str`,
string `$patch`,
int `$flags` = ?,
string `&$error` = ?
): string

Corrige uma string `str` com uma correção unificada no parâmetro `patch` e retorna o resultado. `patch` deve ser uma correção unificada criada pela função xdiff_file_diff()/xdiff_string_diff(). Um parâmetro opcional `flags` especifica o modo de operação. Quaisquer partes rejeitadas da correção serão armazenadas dentro da variável `error` se forem fornecidas.

### Parâmetros

`str`

  A string original.

`patch`

  A string de correção unificada. Ela deve ser criada usando as funções xdiff_string_diff(), xdiff_file_diff() ou ferramentas compatíveis.

`flags`

  `flags` podem ser `XDIFF_PATCH_NORMAL` (modo padrão, correção normal) ou `XDIFF_PATCH_REVERSE` (correção reversa).

  A partir da versão 1.5.0, também pode-se usar a operação binária OR para habilitar o sinalizador `XDIFF_PATCH_IGNORESPACE`.

`error`

  Se fornecido, as partes rejeitadas serão armazenadas dentro desta variável.

### Valor Retornado

Retorna a string corrigida ou `false` em caso de erro.

### Exemplos

Exemplo #1 Exemplo de xdiff_string_patch()

O código a seguir aplica alterações a alguns artigos.

    <?php
    $old_article = file_get_contents('./old_article.txt');
    $diff = $_SERVER['patch']; /* Digamos que alguém colou uma correção em um formulário HTML */

    $errors = '';

    $new_article = xdiff_string_patch($old_article, $diff, XDIFF_PATCH_NORMAL, $errors);
    if (is_string($new_article)) {
        echo "Novo artigo:\n";
        echo $new_article;
    }

    if (strlen($errors)) {
        echo "Rejeições: \n";
        echo $errors;
    }

    ?>

### Veja Também

- xdiff_string_diff() - Faz uma diferença unificada entre duas strings

# xdiff_string_patch_binary

(PECL xdiff >= 0.2.0)

xdiff_string_patch_binary — Sinônimo de xdiff_string_bpatch()

### Descrição

function xdiff_string_patch_binary(string `$str`, string `$patch`): string

Corrige uma string `str` com um `patch` binário. Esta função aceita patches criados tanto pelas funções xdiff_string_bdiff() quanto xdiff_string_rabdiff() ou suas contrapartes de arquivo.

A partir da versão 1.5.0, esta função é um alias de xdiff_string_bpatch().

### Parâmetros

`str`

  A string binária original.

`patch`

  A string de patch binária.

### Valor Retornado

Retorna a string corrigida ou `false` em caso de erro.

### Veja Também

- xdiff_string_bpatch() - Corrige uma string com uma diferença binária
- xdiff_string_bdiff() - Faz diferença binária de duas strings
- xdiff_string_rabdiff() - Gera a diferença binária de duas strings usando o algoritmo de impressão digital polinomial de Rabin

# xdiff_string_rabdiff

(PECL xdiff >= 1.5.0)

xdiff_string_rabdiff — Gera a diferença binária de duas strings usando o algoritmo de impressão digital polinomial de Rabin

### Descrição

function xdiff_string_rabdiff(string `$old_data`, string `$new_data`): string|false

Cria uma comparação binária de duas strings usando o algoritmo de impressão digital polinomial de Rabin implementado pela » libxdiff. Comparada à xdiff_string_bdiff(), este algoritmo geralmente produz diferenças menores, é mais rápido e mantém compatibilidade total com xdiff_string_bpatch() e xdiff_file_bpatch() para aplicação das diferenças.

Esta função pode ser usada com texto ou com dados binários. Os dados de diferença resultantes podem ser aplicados posteriormente para recriar a nova versão a partir da antiga.

Para mais informação sobre o algoritmo, consulte a » documentação da libxdiff.

### Parâmetros

`old_data`

  A primeira string contendo os dados binários "antigos".

`new_data`

  A segunda string contendo os "novos" dados binários.

### Valor Retornado

Retorna uma string com diferença binária entre os dados antigos e novos, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Criação de diferença binária entre duas strings

    <?php
    $old = file_get_contents('file_v1.txt');
    $new = file_get_contents('file_v2.txt');

    $diff = xdiff_string_rabdiff($old, $new);
    file_put_contents('patch.rdiff', $diff);
    ?>

### Veja Também

- xdiff_string_bdiff() - Faz diferença binária de duas strings
- xdiff_string_bpatch() - Corrige uma string com uma diferença binária
- xdiff_file_bpatch() - Corrige um arquivo com uma diferença binária

## Índice

- xdiff_file_bdiff — Diferencia dois arquivos de forma binária
- xdiff_file_bdiff_size — Lê um tamanho de arquivo criado pela aplicação de um diff binário
- xdiff_file_bpatch — Corrige um arquivo com uma diferença binária
- xdiff_file_diff — Faz uma comparação unificada de dois arquivos
- xdiff_file_diff_binary — Sinônimo de xdiff_file_bdiff
- xdiff_file_merge3 — Mescla 3 arquivos em um
- xdiff_file_patch — Corrige um arquivo com uma comparação unificada
- xdiff_file_patch_binary — Sinônimo de xdiff_file_bpatch
- xdiff_file_rabdiff — Faz a comparação binária de dois arquivos usando o algoritmo de impressão digital polinomial de Rabin
- xdiff_string_bdiff — Faz diferença binária de duas strings
- xdiff_string_bdiff_size — Lê um tamanho de arquivo criado pela aplicação de uma comparação binária
- xdiff_string_bpatch — Corrige uma string com uma diferença binária
- xdiff_string_diff — Faz uma diferença unificada entre duas strings
- xdiff_string_diff_binary — Sinônimo de xdiff_string_bdiff
- xdiff_string_merge3 — Mesclar 3 strings em uma
- xdiff_string_patch — Altera uma string com uma correção unificada
- xdiff_string_patch_binary — Sinônimo de xdiff_string_bpatch
- xdiff_string_rabdiff — Gera a diferença binária de duas strings usando o algoritmo de impressão digital polinomial de Rabin

- Instalação/Configuração
  - Dependências
  - Instalação
- Constantes predefinidas
- Funções de xdiff
  - xdiff_file_bdiff — Diferencia dois arquivos de forma binária
  - xdiff_file_bdiff_size — Lê um tamanho de arquivo criado pela aplicação de um diff binário
  - xdiff_file_bpatch — Corrige um arquivo com uma diferença binária
  - xdiff_file_diff — Faz uma comparação unificada de dois arquivos
  - xdiff_file_diff_binary — Sinônimo de xdiff_file_bdiff
  - xdiff_file_merge3 — Mescla 3 arquivos em um
  - xdiff_file_patch — Corrige um arquivo com uma comparação unificada
  - xdiff_file_patch_binary — Sinônimo de xdiff_file_bpatch
  - xdiff_file_rabdiff — Faz a comparação binária de dois arquivos usando o algoritmo de impressão digital polinomial de Rabin
  - xdiff_string_bdiff — Faz diferença binária de duas strings
  - xdiff_string_bdiff_size — Lê um tamanho de arquivo criado pela aplicação de uma comparação binária
  - xdiff_string_bpatch — Corrige uma string com uma diferença binária
  - xdiff_string_diff — Faz uma diferença unificada entre duas strings
  - xdiff_string_diff_binary — Sinônimo de xdiff_string_bdiff
  - xdiff_string_merge3 — Mesclar 3 strings em uma
  - xdiff_string_patch — Altera uma string com uma correção unificada
  - xdiff_string_patch_binary — Sinônimo de xdiff_string_bpatch
  - xdiff_string_rabdiff — Gera a diferença binária de duas strings usando o algoritmo de impressão digital polinomial de Rabin

- E/S Direta
  - Instalação/Configuração
  - Constantes predefinidas
  - Funções de E/S Direta
- Diretórios
  - Constantes predefinidas
  - Directory — A classe Directory
  - Funções de Diretórios
- Fileinfo — Informações do arquivo
  - Instalação/Configuração
  - Constantes predefinidas
  - Funções da Fileinfo
  - finfo — A classe finfo
- Extensão Filesystem (Sistema de Arquivos)
  - Instalação/Configuração
  - Constantes predefinidas
  - Funções de Filesystem
- Inotify
  - Instalação/Configuração
  - Constantes predefinidas
  - Funções de Inotify
- xattr
  - Instalação/Configuração
  - Constantes predefinidas
  - Funções da xattr
- xdiff
  - Instalação/Configuração
  - Constantes predefinidas
  - Funções de xdiff

# Linguagem Humana e Suporte a Codificação de Caracteres

# Enchant - Biblioteca de verificação ortográfica

# Introdução

Enchant é a ligação PHP para a » biblioteca Enchant. O Enchant intervém para fornecer uniformidade e conformidade em todas as bibliotecas ortográficas e implementar certos recursos que podem estar faltando em qualquer biblioteca fornecedora individual. Tudo deveria “simplesmente funcionar” para toda e qualquer definição de “simplesmente funcionando”.

O Enchant oferece suporte aos seguintes backends:

- `Aspell/Pspell (pretende substituir Ispell)`
- `Ispell (muito antigo, poderia ser interpretado como um padrão de fato)`
- `MySpell/Hunspell (um projeto OpenOffice.org, também usado pela Mozilla)`
- `Uspell (principalmente iídiche, hebraico, e idiomas do Leste Europeu - hospedado no CVS do AbiWord no módulo "uspell")`
- `Hspell (hebraico)`
- `AppleSpell (Mac OSX)`

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Tipos de Recurso

## Dependências

Esta versão utiliza as funções da » biblioteca Enchant de Dom Lachowicz. É necessário o Enchant 1.2.4 ou posterior. Enchant 2.0.0 ou posterior só é suportado a partir do PHP 8.0.0.

O Enchant também requer » Glib 2.6 ou superior. Bibliotecas pré-compiladas do Windows estão disponíveis em » http://ftp.gnome.org/pub/gnome/binaries/win32/glib/.

## Instalação

Desde que as bibliotecas necessárias estejam instaladas, os usuários podem ativar o enchant adicionando a opção --with-enchant[=dir] ao compilar o PHP.

Os usuários do Windows devem habilitar php_enchant.dll para usar esta extensão.

> Nota: Configuração adicional no Windows
> Para que esta extensão funcione, existem arquivos DLL que devem estar disponíveis no PATH do sistema Windows. Para saber como fazer isso, veja a FAQ intitulada "Como eu adiciono o meu diretório PHP ao PATH do Windows". Embora copiar arquivos DLL da pasta do PHP para o diretório system do Windows também funcione (porque o diretório system está, por padrão, no PATH do sistema), isso não é recomendado. Esta extensão requer que os seguintes arquivos estejam no PATH: libenchant.dll, glib-2.dll, gmodule-2.dll. Além disso, é necessário copiar pelo menos um dos provedores enviados em lib\enchant para \usr\local\lib\enchant-2 (que é um caminho absoluto de a raiz do drive atual). Antes do PHP 8.0.0, ou seja, usando o Enchant v1, os provedores tinham que ser copiados para C:\enchant_plugins, onde esse caminho poderia ser personalizado criando o valor de registro `HKEY_CURRENT_USER\SOFTWARE\Enchant\Config\Module_Dir` e configurando-o para o caminho desejado.

## Tipos de Recurso

Antes do PHP 8.0.0, havia dois tipos de recursos nesta extensão. O primeiro é o corretor (gerenciador de backends) e o segundo é para o dicionário.

# Constantes predefinidas

`LIBENCHANT_VERSION` (string)
  A versão do libenchant. Disponível a partir do PHP 8.0.0.
`ENCHANT_MYSPELL` (int)
  Tipo de dicionário para MySpell. Usado com enchant_broker_get_dict_path() e enchant_broker_set_dict_path(). Descontinuado a partir do PHP 8.0.0.
`ENCHANT_ISPELL` (int)
  Tipo de dicionário para Ispell. Usado com enchant_broker_get_dict_path() e enchant_broker_set_dict_path(). Descontinuado a partir do PHP 8.0.0.

# Exemplos

Exemplo #1 Exemplo de uso de Enchant

    <?php
    $tag = 'en_US';
    $r = enchant_broker_init();
    $bprovides = enchant_broker_describe($r);
    echo "O broker atual fornece os seguintes backend(s):\n";
    print_r($bprovides);

    $dicts = enchant_broker_list_dicts($r);
    print_r($dicts);
    if (enchant_broker_dict_exists($r,$tag)) {
        $d = enchant_broker_request_dict($r, $tag);
        $dprovides = enchant_dict_describe($d);
        echo "dicionário $tag fornece:\n";
        $wordcorrect = enchant_dict_check($d, "soong");
        print_r($dprovides);
        if (!$wordcorrect) {
            $suggs = enchant_dict_suggest($d, "soong");
            echo "Sugestões para 'soong':";
            print_r($suggs);
        }
        enchant_broker_free_dict($d);
    } else {
    }
    enchant_broker_free($r);
    ?>

# Funções de Enchant

# enchant_broker_describe

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0)

enchant_broker_describe — Enumera os provedores de Enchant

### Descrição

function enchant_broker_describe(EnchantBroker `$broker`): array

Enumera os provedores de Enchant e fornece algumas informações rudimentares sobre eles. A mesma informação é fornecida por phpinfo().

### Parâmetros

`broker`
  Um agente Enchant retornado por enchant_broker_init().

### Valor Retornado

Retorna um array de provedores Enchant com seus detalhes.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `broker` agora espera uma instância de EnchantBroker; anteriormente, um resource era esperado.
8.0.0 | Antes deseta versão, a função retornava `false` em caso de falha.

### Exemplos

Exemplo #1 Lista os backends providos pelo broker informado

    <?php
    $r = enchant_broker_init();
    $bprovides = enchant_broker_describe($r);
    echo "O broker atual fornece os seguintes backend(s):\n";
    print_r($bprovides);

    ?>

O exemplo acima produzirá algo semelhante a:

    O broker atual fornece os seguintes backend(s):
    Array
    (
        [0] => Array
            (
                [name] => aspell
                [desc] => Aspell Provider
                [file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [1] => Array
            (
                [name] => hspell
                [desc] => Hspell Provider
                [file] => /usr/lib/enchant/libenchant_hspell.so
            )

        [2] => Array
            (
                [name] => ispell
                [desc] => Ispell Provider
                [file] => /usr/lib/enchant/libenchant_ispell.so
            )

        [3] => Array
            (
                [name] => myspell
                [desc] => Myspell Provider
                [file] => /usr/lib/enchant/libenchant_myspell.so
            )

    )

# enchant_broker_dict_exists

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_dict_exists — Informa se um dicionário existe ou não

### Descrição

function enchant_broker_dict_exists(EnchantBroker `$broker`, string `$tag`): bool

Informa se um dicionário existe ou não, usando etiqueta não vazia.

### Parâmetros

`broker`
  Um agente Enchant retornado por enchant_broker_init().
`tag`
  Etiqueta não vazia no formato da localidade, por exemplo, us_US, pt_BR, etc.

### Valor Retornado

Retorna `true` quando a etiqueta existe ou `false` quando não existe.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `broker` agora espera uma instância de EnchantBroker; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Um exemplo de enchant_broker_dict_exists()

    <?php
    $tag = 'en_US';
    $r = enchant_broker_init();
    if (enchant_broker_dict_exists($r,$tag)) {
        echo "Dicionário $tag encontrado.\n";
    }
    ?>

### Veja Também

- enchant_broker_describe() - Enumera os provedores de Enchant

# enchant_broker_free

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_free — Libera o recurso do broker e seus dicionários

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.0.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
function enchant_broker_free(EnchantBroker `$broker`): bool

Libera o recurso do broker e seus dicionários A partir do PHP 8.0.0, é recomendado remover a definição deste objeto em vez de chamar esta função.

### Parâmetros

`broker`
  Um agente Enchant retornado por enchant_broker_init().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Esta função foi descontinuada em favor de remover a definição do objeto.
8.0.0 | O parâmetro `broker` agora espera uma instância de EnchantBroker; anteriormente, um resource era esperado.

### Veja Também

- enchant_broker_init() - Cria um novo objeto broker

# enchant_broker_free_dict

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_free_dict — Libera um recurso de dicionário

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.0.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
function enchant_broker_free_dict(EnchantDictionary `$dictionary`): bool

Libera um recurso de dicionário A partir do PHP 8.0.0, é recomendado remover a definição deste objeto em vez de chamar esta função.

### Parâmetros

`dictionary`
  Um dicionário Enchant retornado por enchant_broker_request_dict() ou enchant_broker_request_pwl_dict().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Esta função foi descontinuada em favor de remover a definição do objeto.
8.0.0 | `dictionary` agora espera um objeto EnchantDictionary; anteriormente, esperava um resource.

### Veja Também

- enchant_broker_request_dict() - Cria um novo dicionário usando uma etiqueta
- enchant_broker_request_pwl_dict() - Cria um dicionário usando um arquivo PWL

# enchant_broker_get_dict_path

(PHP 5 >= 5.3.1, PHP 7, PHP 8, PECL enchant >= 1.0.1)

enchant_broker_get_dict_path — Obtém o caminho do diretório para um determinado back-end

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.0.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
function enchant_broker_get_dict_path(EnchantBroker `$broker`, int `$type`): string|false

Obtém o caminho do diretório para um determinado back-end.

### Parâmetros

`broker`
  Um agente Enchant retornado por enchant_broker_init().
`type`
  O tipo dos dicionários, ou seja `ENCHANT_MYSPELL` ou `ENCHANT_ISPELL`.

### Valor Retornado

Retorna o caminho do diretório do dicionário em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Esta função foi descontinuada.
8.0.0 | O parâmetro `broker` agora espera uma instância de EnchantBroker; anteriormente, um resource era esperado.

### Notas

> Nota: Esta função está disponível somente se a extensão foi compilada com Enchant v1.

### Veja Também

- enchant_broker_set_dict_path() - Define o caminho do diretório para um determinado back-end

# enchant_broker_get_error

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_get_error — Retorna o último erro do broker

### Descrição

function enchant_broker_get_error(EnchantBroker `$broker`): string|false

Retorna o último erro ocorrido neste broker.

### Parâmetros

`broker`
  Um agente Enchant retornado por enchant_broker_init().

### Valor Retornado

Retorne a string da mensagem se um erro for encontrado ou `false`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `broker` agora espera uma instância de EnchantBroker; anteriormente, um resource era esperado.

# enchant_broker_init

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_init — Cria um novo objeto broker

### Descrição

function enchant_broker_init(): EnchantBroker|false

### Parâmetros

### Valor Retornado

Retorna um recurso de broker em caso de sucesso ou `false`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Em caso de sucesso, esta função agora retorna uma instância de EnchantBroker; anteriormente, retornava um resource.

### Veja Também

- enchant_broker_free() - Libera o recurso do broker e seus dicionários

# enchant_broker_list_dicts

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 1.0.1)

enchant_broker_list_dicts — Retorna uma lista de dicionários disponíveis

### Descrição

function enchant_broker_list_dicts(EnchantBroker `$broker`): array

Retorna uma lista de dicionários disponíveis com seus detalhes.

### Parâmetros

`broker`
  Um agente Enchant retornado por enchant_broker_init().

### Valor Retornado

Retorna um array de dicionários disponíveis com seus detalhes.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `broker` agora espera uma instância de EnchantBroker; anteriormente, um resource era esperado.
8.0.0 | Antes desta versão, a função retornava `false` em caso de falha.

### Exemplos

Exemplo #1 Lista todos os dicionários disponíveis para um broker

    <?php
    $r = enchant_broker_init();
    $dicts = enchant_broker_list_dicts($r);
    print_r($dicts);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => Array
            (
                [lang_tag] => de
                [provider_name] => aspell
                [provider_desc] => Aspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [1] => Array
            (
                [lang_tag] => de_DE
                [provider_name] => aspell
                [provider_desc] => Aspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [3] => Array
            (
                [lang_tag] => en
                [provider_name] => aspell
                [provider_desc] => Aspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [4] => Array
            (
                [lang_tag] => en_GB
                [provider_name] => aspell
                [provider_desc] => Aspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [5] => Array
            (
                [lang_tag] => en_US
                [provider_name] => aspell
                [provider_desc] => Aspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [6] => Array
            (
                [lang_tag] => hi_IN
                [provider_name] => myspell
                [provider_desc] => Myspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_myspell.so
            )

    )

### Veja Também

- enchant_broker_describe() - Enumera os provedores de Enchant

# enchant_broker_request_dict

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_request_dict — Cria um novo dicionário usando uma etiqueta

### Descrição

function enchant_broker_request_dict(EnchantBroker `$broker`, string `$tag`): EnchantDictionary|false

Cria um novo dicionário usando a etiqueta de idioma não vazia para a qual se deseja solicitar um dicionário ("en_US", "pt_BR", ...).

### Parâmetros

`broker`
  Um agente Enchant retornado por enchant_broker_init().
`tag`
  Uma etiqueta descrevendo a localidade, por exemplo, pt_BR, en_US.

### Valor Retornado

Retorna um recurso de dicionário em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `broker` agora espera uma instância de EnchantBroker; anteriormente, um resource era esperado.
8.0.0 | Em caso de sucesso, esta função agora retorna uma instância de EnchantDictionary; anteriormente, um resource era retornado.

### Exemplos

Exemplo #1 Um exemplo de enchant_broker_request_dict()

Verifica se um dicionário existe usando enchant_broker_dict_exists() e o solicita.

    <?php
    $tag = 'en_US';
    $broker = enchant_broker_init();
    if (enchant_broker_dict_exists($broker,$tag)) {
        $dict = enchant_broker_request_dict($broker, $tag);
        var_dump($dict);
    }
    ?>

### Veja Também

- enchant_dict_describe() - Descreve um dicionário individual
- enchant_broker_dict_exists() - Informa se um dicionário existe ou não
- enchant_broker_free_dict() - Libera um recurso de dicionário

# enchant_broker_request_pwl_dict

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_request_pwl_dict — Cria um dicionário usando um arquivo PWL

### Descrição

function enchant_broker_request_pwl_dict(EnchantBroker `$broker`, string `$filename`): EnchantDictionary|false

Cria um dicionário usando um arquivo PWL. Um arquivo PWL é um arquivo de palavras personalizadas com uma palavra por linha.

### Parâmetros

`broker`
  Um agente Enchant retornado por enchant_broker_init().
`filename`
  Caminho para o arquivo PWL. Se não existir tal arquivo, um novo será criado, se possível.

### Valor Retornado

Retorna um recurso de dicionário em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `broker` agora espera uma instância de EnchantBroker; anteriormente, um resource era esperado.
8.0.0 | Em caso de sucesso, esta função agora retorna uma instância de EnchantDictionary; anteriormente, um resource era retornado.

### Veja Também

- enchant_dict_describe() - Descreve um dicionário individual
- enchant_broker_dict_exists() - Informa se um dicionário existe ou não
- enchant_broker_free_dict() - Libera um recurso de dicionário

# enchant_broker_set_dict_path

(PHP 5 >= 5.3.1, PHP 7, PHP 8, PECL enchant >= 1.0.1)

enchant_broker_set_dict_path — Define o caminho do diretório para um determinado back-end

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.0.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
function enchant_broker_set_dict_path(EnchantBroker `$broker`, int `$type`, string `$path`): bool

Define o caminho do diretório para um determinado back-end.

### Parâmetros

`broker`
  Um agente Enchant retornado por enchant_broker_init().
`type`
  O tipo dos dicionários, ou seja, `ENCHANT_MYSPELL` ou `ENCHANT_ISPELL`.
`path`
  O caminho do diretório do dicionário.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Esta função foi descontinuada.
8.0.0 | O parâmetro `broker` agora espera uma instância de EnchantBroker; anteriormente, um resource era esperado.

### Notas

> Nota: Esta função está disponível somente se a extensão foi compilada com Enchant v1.

### Veja Também

- enchant_broker_get_dict_path() - Obtém o caminho do diretório para um determinado back-end

# enchant_broker_set_ordering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_set_ordering — Declara uma preferência de dicionários a serem usados ​​para o idioma

### Descrição

function enchant_broker_set_ordering(EnchantBroker `$broker`, string `$tag`, string `$ordering`): bool

Declara uma preferência de dicionários a serem usados ​​para o idioma descrito/referido por 'tag'. A ordem é uma lista delimitada por vírgulas de nomes de provedores. Como uma exceção especial, a etiqueta "*" pode ser usada como uma etiqueta de idioma para declarar uma ordem padrão para qualquer idioma que não declare explicitamente uma ordem.

### Parâmetros

`broker`
  Um agente Enchant retornado por enchant_broker_init().
`tag`
  Etiqueta de idioma. A etiqueta especial "*" pode ser usada como uma etiqueta de idioma para declarar uma ordem padrão para qualquer idioma que não declare explicitamente uma ordem.
`ordering`
  Lista delimitada por vírgulas de nomes de provedores

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `broker` agora espera uma instância de EnchantBroker; anteriormente, um resource era esperado.

# enchant_dict_add

(PHP 8)

enchant_dict_add — Adiciona uma palavra à lista de palavras personalizadas

### Descrição

function enchant_dict_add(EnchantDictionary `$dictionary`, string `$word`): void

Adiciona uma palavra à lista de palavras personalizadas do dicionário informado.

### Parâmetros

`dictionary`
  Um dicionário Enchant retornado por enchant_broker_request_dict() ou enchant_broker_request_pwl_dict().
`word`
  A palavra a ser adicionada

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `dictionary` agora espera uma instância de EnchantDictionary; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Adicionando uma palavra a uma lista de palavras personalizadas

    <?php

    $filename = './minha_lista_de_palavras.pwl';
    $word = 'Inconstitucionalissimamente';

    $broker = enchant_broker_init();
    $dict = enchant_broker_request_pwl_dict($broker, $filename);

    enchant_dict_add($dict, $word);

    ?>

### Veja Também

- enchant_broker_request_pwl_dict() - Cria um dicionário usando um arquivo PWL
- enchant_broker_request_dict() - Cria um novo dicionário usando uma etiqueta

# enchant_dict_add_to_personal

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_add_to_personal — Sinônimo de enchant_dict_add()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 8.0.0.

### Descrição

Esta função é um apelido para: enchant_dict_add().

# enchant_dict_add_to_session

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_add_to_session — Adciona uma palavra a esta sessão de verificação de ortografia

### Descrição

function enchant_dict_add_to_session(EnchantDictionary `$dictionary`, string `$word`): void

Adiciona uma palavra ao dicionário informado. Ela será adicionada somente para a sessão ativa de verificação de ortografia.

### Parâmetros

`dictionary`
  Um dicionário Enchant retornado por enchant_broker_request_dict() ou enchant_broker_request_pwl_dict().
`word`
  A palavra a ser adicionada

### Valor Retornado

Nenhum valor é retornado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `dictionary` agora espera uma instância de EnchantDictionary; anteriormente, um resource era esperado.

### Veja Também

- enchant_broker_request_dict() - Cria um novo dicionário usando uma etiqueta

# enchant_dict_check

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_check — Verifica se uma palavra está escrita de forma correta

### Descrição

function enchant_dict_check(EnchantDictionary `$dictionary`, string `$word`): bool

Se a palavra está escrita de forma correta, retorna `true`, caso contrário retorna `false`.

### Parâmetros

`dictionary`
  Um dicionário Enchant retornado por enchant_broker_request_dict() ou enchant_broker_request_pwl_dict().
`word`
  A palavra a ser verificada

### Valor Retornado

Retorna `true` se a palavra estiver escrita corretamente, `false` caso contrário.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `dictionary` agora espera uma instância de EnchantDictionary; anteriormente, um resource era esperado.

# enchant_dict_describe

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_describe — Descreve um dicionário individual

### Descrição

function enchant_dict_describe(EnchantDictionary `$dictionary`): array

Retorna os detalhes do dicionário.

### Parâmetros

`dictionary`
  Um dicionário Enchant retornado por enchant_broker_request_dict() ou enchant_broker_request_pwl_dict().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `dictionary` agora espera uma instância de EnchantDictionary; anteriormente, um resource era esperado.
8.0.0 | Antes desta versão, a função retornava `false` em caso de falha.

### Exemplos

Exemplo #1 Um exemplo de enchant_dict_describe()

Verifica se um dicionário existe usando enchant_broker_dict_exists() e mostra seus detalhes.

    <?php
    $tag = 'en_US';
    $broker = enchant_broker_init();
    if (enchant_broker_dict_exists($broker, $tag)) {
        $dict = enchant_broker_request_dict($broker, $tag);
        $dict_details = enchant_dict_describe($dict);
        print_r($dict_details);
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [lang] => en_US
        [name] => aspell
        [desc] => Aspell Provider
        [file] => /usr/lib/enchant/libenchant_aspell.so
    )

# enchant_dict_get_error

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_get_error — Retorna o último erro da sessão de correção ortográfica atual

### Descrição

function enchant_dict_get_error(EnchantDictionary `$dictionary`): string|false

Retorna o último erro da sessão de correção ortográfica atual.

### Parâmetros

`dictionary`
  Um dicionário Enchant retornado por enchant_broker_request_dict() ou enchant_broker_request_pwl_dict().

### Valor Retornado

Retorna a mensagem de erro como uma string ou `false` se não tiver ocorrido nenhum erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `dictionary` agora espera uma instância de EnchantDictionary; anteriormente, um resource era esperado.

# enchant_dict_is_added

(PHP 8)

enchant_dict_is_added — Informa se uma palavra existe ou não nesta sessão de correção ortográfica

### Descrição

function enchant_dict_is_added(EnchantDictionary `$dictionary`, string `$word`): bool

Informa se uma palavra existe ou não na sessão atual.

### Parâmetros

`dictionary`
  Um dicionário Enchant retornado por enchant_broker_request_dict() ou enchant_broker_request_pwl_dict().
`word`
  A palavra a ser procurada

### Valor Retornado

Retorna `true` se a palavra existe ou `false` caso contrário.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `dictionary` agora espera uma instância de EnchantDictionary; anteriormente, um resource era esperado.

### Veja Também

- enchant_dict_add_to_session() - Adciona uma palavra a esta sessão de verificação de ortografia

# enchant_dict_is_in_session

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_is_in_session — Sinônimo de enchant_dict_is_added()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 8.0.0.

### Descrição

Esta função é um apelido para: enchant_dict_is_added().

# enchant_dict_quick_check

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant:0.2.0-1.0.1)

enchant_dict_quick_check — Verifica se a palavra está escrita corretamente e fornece sugestões

### Descrição

function enchant_dict_quick_check(EnchantDictionary `$dictionary`, string `$word`, array `&$suggestions` = `null`): bool

Se a palavra estiver escrita corretamente, retorna `true`, caso contrário retorna `false`. Se uma variável de sugestões for informada, esta função preenche-a com alternativas de escrita.

### Parâmetros

`dictionary`
  Um dicionário Enchant retornado por enchant_broker_request_dict() ou enchant_broker_request_pwl_dict().
`word`
  A palavra a ser verificada.
`suggestions`
  Se a palavra não estiver escrita corretamente, esta variável conterá um array de sugestões.

### Valor Retornado

Retorna `true` se a palavra estiver escrita corretamente ou `false` caso contrário.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `dictionary` agora espera uma instância de EnchantDictionary; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Um exemplo de enchant_dict_quick_check()

    <?php
    $tag = 'en_US';
    $r = enchant_broker_init();

    if (enchant_broker_dict_exists($r,$tag)) {
        $d = enchant_broker_request_dict($r, $tag);
        enchant_dict_quick_check($d, 'soong', $suggs);
        print_r($suggs);
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => song
        [1] => snog
        [2] => soon
        [3] => Sang
        [4] => Sung
        [5] => sang
        [6] => sung
        [7] => sponge
        [8] => spongy
        [9] => snag
        [10] => snug
        [11] => sonic
        [12] => sing
        [13] => songs
        [14] => Son
        [15] => Sonja
        [16] => Synge
        [17] => son
        [18] => Sejong
        [19] => sarong
        [20] => sooner
        [21] => Sony
        [22] => sown
        [23] => scone
        [24] => song's
    )

### Veja Também

- enchant_dict_check() - Verifica se uma palavra está escrita de forma correta
- enchant_dict_suggest() - Sugere grafias para uma palavra

# enchant_dict_store_replacement

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_store_replacement — Adiciona uma correção para uma palavra

### Descrição

function enchant_dict_store_replacement(EnchantDictionary `$dictionary`, string `$misspelled`, string `$correct`): void

Adiciona uma correção para 'misspelled' (a palavra que precisa ser corrigida) usando 'correct' (a palavra corrigida). Observe que ao substituir a palavra mal escrita com a corrigida, é bem possível que futuras ocorrências da palavra mal escrita sejam substituídas pela corrigida. Portanto, a palavra corrigida pode acabar aparecendo na lista de sugestões.

### Parâmetros

`dictionary`
  Um dicionário Enchant retornado por enchant_broker_request_dict() ou enchant_broker_request_pwl_dict().
`misspelled`
  A palavra a ser corrigida
`correct`
  A palavra corrigida

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `dictionary` agora espera uma instância de EnchantDictionary; anteriormente, um resource era esperado.

# enchant_dict_suggest

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_suggest — Sugere grafias para uma palavra

### Descrição

function enchant_dict_suggest(EnchantDictionary `$dictionary`, string `$word`): array

### Parâmetros

`dictionary`
  Um dicionário Enchant retornado por enchant_broker_request_dict() ou enchant_broker_request_pwl_dict().
`word`
  Palavra a ser usada para as sugestões.

### Valor Retornado

Retorna um array de sugestões se a palavra for escrita incorretamente.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `dictionary` agora espera uma instância de EnchantDictionary; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Um exemplo de enchant_dict_suggest()

    <?php
    $tag = 'en_US';
    $r = enchant_broker_init();
    if (enchant_broker_dict_exists($r,$tag)) {
        $d = enchant_broker_request_dict($r, $tag);

        $wordcorrect = enchant_dict_check($d, "soong");
        if (!$wordcorrect) {
            $suggs = enchant_dict_suggest($d, "soong");
            echo "Suggestions for 'soong':";
            print_r($suggs);
        }
    }
    ?>

### Veja Também

- enchant_dict_check() - Verifica se uma palavra está escrita de forma correta
- enchant_dict_quick_check() - Verifica se a palavra está escrita corretamente e fornece sugestões

## Índice

- enchant_broker_describe — Enumera os provedores de Enchant
- enchant_broker_dict_exists — Informa se um dicionário existe ou não
- enchant_broker_free — Libera o recurso do broker e seus dicionários
- enchant_broker_free_dict — Libera um recurso de dicionário
- enchant_broker_get_dict_path — Obtém o caminho do diretório para um determinado back-end
- enchant_broker_get_error — Retorna o último erro do broker
- enchant_broker_init — Cria um novo objeto broker
- enchant_broker_list_dicts — Retorna uma lista de dicionários disponíveis
- enchant_broker_request_dict — Cria um novo dicionário usando uma etiqueta
- enchant_broker_request_pwl_dict — Cria um dicionário usando um arquivo PWL
- enchant_broker_set_dict_path — Define o caminho do diretório para um determinado back-end
- enchant_broker_set_ordering — Declara uma preferência de dicionários a serem usados ​​para o idioma
- enchant_dict_add — Adiciona uma palavra à lista de palavras personalizadas
- enchant_dict_add_to_personal — Sinônimo de enchant_dict_add
- enchant_dict_add_to_session — Adciona uma palavra a esta sessão de verificação de ortografia
- enchant_dict_check — Verifica se uma palavra está escrita de forma correta
- enchant_dict_describe — Descreve um dicionário individual
- enchant_dict_get_error — Retorna o último erro da sessão de correção ortográfica atual
- enchant_dict_is_added — Informa se uma palavra existe ou não nesta sessão de correção ortográfica
- enchant_dict_is_in_session — Sinônimo de enchant_dict_is_added
- enchant_dict_quick_check — Verifica se a palavra está escrita corretamente e fornece sugestões
- enchant_dict_store_replacement — Adiciona uma correção para uma palavra
- enchant_dict_suggest — Sugere grafias para uma palavra

# A classe EnchantBroker

(PHP 8)

## Introdução

Uma classe totalmente opaca que substitui os recursos `enchant_broker` do PHP 8.0.0.

## Resumo da classe

final class EnchantBroker {
}

# A classe EnchantDictionary

(PHP 8)

## Introdução

Uma classe totalmente opaca que substitui os recursos `enchant_dict` do PHP 8.0.0.

## Resumo da classe

final class EnchantDictionary {
}

- Instalação/Configuração
  - Dependências
  - Instalação
  - Tipos de Recurso
- Constantes predefinidas
- Exemplos
- Funções de Enchant
  - enchant_broker_describe — Enumera os provedores de Enchant
  - enchant_broker_dict_exists — Informa se um dicionário existe ou não
  - enchant_broker_free — Libera o recurso do broker e seus dicionários
  - enchant_broker_free_dict — Libera um recurso de dicionário
  - enchant_broker_get_dict_path — Obtém o caminho do diretório para um determinado back-end
  - enchant_broker_get_error — Retorna o último erro do broker
  - enchant_broker_init — Cria um novo objeto broker
  - enchant_broker_list_dicts — Retorna uma lista de dicionários disponíveis
  - enchant_broker_request_dict — Cria um novo dicionário usando uma etiqueta
  - enchant_broker_request_pwl_dict — Cria um dicionário usando um arquivo PWL
  - enchant_broker_set_dict_path — Define o caminho do diretório para um determinado back-end
  - enchant_broker_set_ordering — Declara uma preferência de dicionários a serem usados ​​para o idioma
  - enchant_dict_add — Adiciona uma palavra à lista de palavras personalizadas
  - enchant_dict_add_to_personal — Sinônimo de enchant_dict_add
  - enchant_dict_add_to_session — Adciona uma palavra a esta sessão de verificação de ortografia
  - enchant_dict_check — Verifica se uma palavra está escrita de forma correta
  - enchant_dict_describe — Descreve um dicionário individual
  - enchant_dict_get_error — Retorna o último erro da sessão de correção ortográfica atual
  - enchant_dict_is_added — Informa se uma palavra existe ou não nesta sessão de correção ortográfica
  - enchant_dict_is_in_session — Sinônimo de enchant_dict_is_added
  - enchant_dict_quick_check — Verifica se a palavra está escrita corretamente e fornece sugestões
  - enchant_dict_store_replacement — Adiciona uma correção para uma palavra
  - enchant_dict_suggest — Sugere grafias para uma palavra
- EnchantBroker — A classe EnchantBroker
- EnchantDictionary — A classe EnchantDictionary

# Determina o gênero dos primeiros nomes

# Introdução

A extensão Gender PHP é uma versão do programa gender.c originalmente escrito por Joerg Michael. O objetivo principal é descobrir o gênero dos primeiros nomes. O banco de dados atual contém mais de 40.000 nomes de 54 países.

# Instalação/Configuração

## Índice

- Instalação

## Instalação

Esta extensão » PECL não é distribuída com o PHP.

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/gender.

# Exemplos

## Índice

- Exemplo de uso

## Exemplo de uso

Exemplo de uso da classe Gender.

Exemplo #1 Exemplo de uso

    <?php

    namespace Gender;

    $gender = new Gender;

    $name = "Milene";
    $country = Gender::FRANCE;

    $result = $gender->get($name, $country);

    $data = $gender->country($country);

    switch($result) {
        case Gender::IS_FEMALE:
            printf("O nome %s é feminimo em %s\n", $name, $data['country']);
        break;

        case Gender::IS_MOSTLY_FEMALE:
            printf("O nome %s é predominantemente feminino em %s\n", $name, $data['country']);
        break;

        case Gender::IS_MALE:
            printf("O nome %s é masculino em %s\n", $name, $data['country']);
        break;

        case Gender::IS_MOSTLY_MALE:
            printf("O nome %s é predominantemente masculino em %s\n", $name, $data['country']);
        break;

        case Gender::IS_UNISEX_NAME:
            printf("O nome %s é unissex em %s\n", $name, $data['country']);
        break;

        case Gender::IS_A_COUPLE:
            printf("O nome %s é masculino e feminino em %s\n", $name, $data['country']);
        break;

        case Gender::NAME_NOT_FOUND:
            printf("O nome %s não foi encontrado para %s\n", $name, $data['country']);
        break;

        case Gender::ERROR_IN_NAME:
            echo "Há um erro no nome fornecido!\n";
        break;

        default:
            echo "Ocorreu um erro!\n";
        break;

    }

# A classe Gender\Gender

(PECL gender >= 0.6.0)

## Introdução

## Resumo da classe

class Gender\Gender {
/* Constantes */
const int IS_FEMALE = 70;
const int IS_MOSTLY_FEMALE = 102;
const int IS_MALE = 77;
const int IS_MOSTLY_MALE = 109;
const int IS_UNISEX_NAME = 63;
const int IS_A_COUPLE = 67;
const int NAME_NOT_FOUND = 32;
const int ERROR_IN_NAME = 69;
const int ANY_COUNTRY = 0;
const int BRITAIN = 1;
const int IRELAND = 2;
const int USA = 3;
const int SPAIN = 4;
const int PORTUGAL = 5;
const int ITALY = 6;
const int MALTA = 7;
const int FRANCE = 8;
const int BELGIUM = 9;
const int LUXEMBOURG = 10;
const int NETHERLANDS = 11;
const int GERMANY = 12;
const int EAST_FRISIA = 13;
const int AUSTRIA = 14;
const int SWISS = 15;
const int ICELAND = 16;
const int DENMARK = 17;
const int NORWAY = 18;
const int SWEDEN = 19;
const int FINLAND = 20;
const int ESTONIA = 21;
const int LATVIA = 22;
const int LITHUANIA = 23;
const int POLAND = 24;
const int CZECH_REP = 25;
const int SLOVAKIA = 26;
const int HUNGARY = 27;
const int ROMANIA = 28;
const int BULGARIA = 29;
const int BOSNIA = 30;
const int CROATIA = 31;
const int KOSOVO = 32;
const int MACEDONIA = 33;
const int MONTENEGRO = 34;
const int SERBIA = 35;
const int SLOVENIA = 36;
const int ALBANIA = 37;
const int GREECE = 38;
const int RUSSIA = 39;
const int BELARUS = 40;
const int MOLDOVA = 41;
const int UKRAINE = 42;
const int ARMENIA = 43;
const int AZERBAIJAN = 44;
const int GEORGIA = 45;
const int KAZAKH_UZBEK = 46;
const int TURKEY = 47;
const int ARABIA = 48;
const int ISRAEL = 49;
const int CHINA = 50;
const int INDIA = 51;
const int JAPAN = 52;
const int KOREA = 53;
/* Métodos */
public function __construct(string `$dsn` = ?)
public function connect(string `$dsn`): bool
public function country(int `$country`): array|false
public function get(string `$name`, int `$country` = ?): int
public function isNick(string `$name0`, string `$name1`, int `$country` = ?): array
public function similarNames(string `$name`, int `$country` = ?): array
}

## Constantes predefinidas

`Gender\Gender::IS_FEMALE`
`Gender\Gender::IS_MOSTLY_FEMALE`
`Gender\Gender::IS_MALE`
`Gender\Gender::IS_MOSTLY_MALE`
`Gender\Gender::IS_UNISEX_NAME`
`Gender\Gender::IS_A_COUPLE`
`Gender\Gender::NAME_NOT_FOUND`
`Gender\Gender::ERROR_IN_NAME`
`Gender\Gender::ANY_COUNTRY`
`Gender\Gender::BRITAIN`
`Gender\Gender::IRELAND`
`Gender\Gender::USA`
`Gender\Gender::SPAIN`
`Gender\Gender::PORTUGAL`
`Gender\Gender::ITALY`
`Gender\Gender::MALTA`
`Gender\Gender::FRANCE`
`Gender\Gender::BELGIUM`
`Gender\Gender::LUXEMBOURG`
`Gender\Gender::NETHERLANDS`
`Gender\Gender::GERMANY`
`Gender\Gender::EAST_FRISIA`
`Gender\Gender::AUSTRIA`
`Gender\Gender::SWISS`
`Gender\Gender::ICELAND`
`Gender\Gender::DENMARK`
`Gender\Gender::NORWAY`
`Gender\Gender::SWEDEN`
`Gender\Gender::FINLAND`
`Gender\Gender::ESTONIA`
`Gender\Gender::LATVIA`
`Gender\Gender::LITHUANIA`
`Gender\Gender::POLAND`
`Gender\Gender::CZECH_REP`
`Gender\Gender::SLOVAKIA`
`Gender\Gender::HUNGARY`
`Gender\Gender::ROMANIA`
`Gender\Gender::BULGARIA`
`Gender\Gender::BOSNIA`
`Gender\Gender::CROATIA`
`Gender\Gender::KOSOVO`
`Gender\Gender::MACEDONIA`
`Gender\Gender::MONTENEGRO`
`Gender\Gender::SERBIA`
`Gender\Gender::SLOVENIA`
`Gender\Gender::ALBANIA`
`Gender\Gender::GREECE`
`Gender\Gender::RUSSIA`
`Gender\Gender::BELARUS`
`Gender\Gender::MOLDOVA`
`Gender\Gender::UKRAINE`
`Gender\Gender::ARMENIA`
`Gender\Gender::AZERBAIJAN`
`Gender\Gender::GEORGIA`
`Gender\Gender::KAZAKH_UZBEK`
`Gender\Gender::TURKEY`
`Gender\Gender::ARABIA`
`Gender\Gender::ISRAEL`
`Gender\Gender::CHINA`
`Gender\Gender::INDIA`
`Gender\Gender::JAPAN`
`Gender\Gender::KOREA`

# Gender\Gender::connect

(PECL gender >= 0.6.0)

Gender\Gender::connect — Conecta-se a um dicionário de nomes externo

### Descrição

public function Gender\Gender::connect(string `$dsn`): bool

Conecta-se a um dicionário de nomes externo. Atualmente, apenas fluxos são suportados.

### Parâmetros

`dsn`
  DSN a ser aberto

### Valor Retornado

Booleano como sucesso ou falha.

# Gender\Gender::__construct

(PECL gender >= 0.6.0)

Gender\Gender::__construct — Constrói o objeto Gender

### Descrição

public function Gender\Gender::__construct(string `$dsn` = ?)

Cria um objeto Gender opcionalmente conectando-se a um dicionário de nomes externo. Quando nenhum banco de dados externo for fornecido, os dados compilados serão usados.

### Parâmetros

`dsn`
  DSN a ser aberto

# Gender\Gender::country

(PECL gender >= 0.8.0)

Gender\Gender::country — Obtém representação textual do país

### Descrição

public function Gender\Gender::country(int `$country`): array|false

Retorna a representação textual de um país de uma constante de classe Gender.

### Parâmetros

`country`
  Um ID de país especificado por uma constante de classe Gender\Gender.

### Valor Retornado

Retorna um array com os nomes curtos e completos do país em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Usando Gender\Gender::country()

    $gender = new Gender\Gender;
    var_dump($gender->country(Gender\Gender::BRITAIN));

O exemplo acima produzirá:

    array(2) {
      'country_short' =>
      string(2) "UK"
      'country' =>
      string(13) "Great Britain"
    }

# Gender\Gender::get

(PECL gender >= 0.6.0)

Gender\Gender::get — Obtém o gênero de um nome

### Descrição

public function Gender\Gender::get(string `$name`, int `$country` = ?): int

Obtém o gênero do nome em um país específico.

### Parâmetros

`name`
  Nome a verificar.
`country`
  ID do país identificado pela constante de classe Gender.

### Valor Retornado

Retorna o gênero do nome.

# Gender\Gender::isNick

(PECL gender >= 0.9.0)

Gender\Gender::isNick — Verifica se um nome é apelido de outro

### Descrição

public function Gender\Gender::isNick(string `$name0`, string `$name1`, int `$country` = ?): array

Verifica se name0 é apelido de name1.

### Parâmetros

`name0`
  Nome a verificar.
`name1`
  Nome a verificar.
`country`
  ID do país identificado pela constante de classe Gender. Se omitido, ANY_COUNTRY é usado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# Gender\Gender::similarNames

(PECL gender >= 0.9.0)

Gender\Gender::similarNames — Obtém nomes semelhantes

### Descrição

public function Gender\Gender::similarNames(string `$name`, int `$country` = ?): array

Obtém nomes semelhantes para o nome e país fornecidos.

### Parâmetros

`name`
  Nome a verificar.
`country`
  ID do país identificado pela constante de classe Gender. Se omitido, ANY_COUNTRY é usado.

### Valor Retornado

Retorna um array com os nomes semelhantes encontrados.

## Índice

- Gender\Gender::connect — Conecta-se a um dicionário de nomes externo
- Gender\Gender::__construct — Constrói o objeto Gender
- Gender\Gender::country — Obtém representação textual do país
- Gender\Gender::get — Obtém o gênero de um nome
- Gender\Gender::isNick — Verifica se um nome é apelido de outro
- Gender\Gender::similarNames — Obtém nomes semelhantes

- Instalação/Configuração
  - Instalação
- Exemplos
  - Exemplo de uso
- Gender\Gender — A classe Gender\Gender
  - Gender\Gender::connect — Conecta-se a um dicionário de nomes externo
  - Gender\Gender::__construct — Constrói o objeto Gender
  - Gender\Gender::country — Obtém representação textual do país
  - Gender\Gender::get — Obtém o gênero de um nome
  - Gender\Gender::isNick — Verifica se um nome é apelido de outro
  - Gender\Gender::similarNames — Obtém nomes semelhantes

# Gettext

# Introdução

As funções gettext implementam uma API NLS (Native Language Support) que pode ser usada para internacionalizar aplicações PHP. Consulte a documentação da gettext para seu sistema para uma maior explicação destas funções ou acesse a documentação em » http://www.gnu.org/software/gettext/manual/gettext.html.

# Instalação/Configuração

## Índice

- Dependências
- Instalação

## Dependências

Para usar estas funções você precisa fazer download e instalar o pacote GNU gettext de » http://www.gnu.org/software/gettext/gettext.html

## Instalação

Para incluir o suporte ao GNU gettext na sua instalação PHP você deve adicionar a opção --with-gettext[=DIR] onde DIR é o diretório de instalação do gettext, o diretório padrão é /usr/local.

# Funções da Gettext

# _

(PHP 4, PHP 5, PHP 7, PHP 8)

_ — Sinônimo de gettext()

### Descrição

Esta função é um apelido para: gettext().

# bind_textdomain_codeset

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

bind_textdomain_codeset — Especifica ou obtém a codificação de caracteres na qual as mensagens do catálogo de mensagens de DOMÍNIO serão retornadas

### Descrição

function bind_textdomain_codeset(string `$domain`, ?string `$codeset` = `null`): string|false

bind_textdomain_codeset() permite definir ou obter a codificação na qual as mensagens de `domain` serão retornadas por gettext() e funções similares.

### Parâmetros

`domain`

  O domínio.

`codeset`

  O conjunto de caracteres. Se `null`, a codificação atualmente definida é retornada.

### Valor Retornado

Uma string em caso de sucesso.

### Erros/Exceções

Lança uma exceção ValueError se `domain` for uma string vazia.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Agora lança um ValueError se `domain` for uma string vazia.
8.4.0 | `codeset` agora é opcional. Anteriormente, sempre tinha que ser especificado.
8.0.3 | `codeset` agora pode ser nulo. Anteriormente, não era possível recuperar a codificação definida.

### Notas

> Nota:

> A informação de bind_textdomain_codeset() é mantida por processo, não por thread.

# bindtextdomain

(PHP 4, PHP 5, PHP 7, PHP 8)

bindtextdomain — Define ou obtém o caminho para um domínio

### Descrição

function bindtextdomain(string `$domain`, ?string `$directory` = `null`): string|false

A função bindtextdomain() define ou obtém um caminho para um domínio.

### Parâmetros

`domain`

  O domínio.

`directory`

  O caminho do diretório. Uma string vazia significa o diretório atual. Se `null`, o diretório definido para o domínio é retornado.

### Valor Retornado

O caminho completo para o domínio definido por `domain`, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | `directory` agora é opcional. Anteriormente, sempre tinha que ser especificado.
8.0.3 | `directory` agora pode ser nulo. Anteriormente, não era possível recuperar o diretório definido para o domínio.

### Exemplos

Exemplo #1 Exemplo de bindtextdomain()

    <?php

    $domain = 'myapp';
    echo bindtextdomain($domain, '/usr/share/myapp/locale');

    ?>

O exemplo acima produzirá:

    /usr/share/myapp/locale

### Notas

> Nota:

> A informação de bindtextdomain() é mantida por processo, não por thread.

# dcgettext

(PHP 4, PHP 5, PHP 7, PHP 8)

dcgettext — Substitui o domínio por um lookup

### Descrição

function dcgettext(string `$domain`, string `$message`, int `$category`): string

Esta função permite que você sobreescreva o domínio atual por uma simples mensagem de lookup.

### Parâmetros

`domain`

  O domínio

`message`

  A mensagem

`category`

  A categoria

### Valor Retornado

Uma string em sucesso.

### Veja Também

- gettext() - Pesquisa uma mensagem no domínio atual

# dcngettext

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

dcngettext — Versão plural de dcgettext

### Descrição

function dcngettext(
string `$domain`,
string `$singular`,
string `$plural`,
int `$count`,
int `$category`
): string

Esta função permite substituir o domínio atual para uma única pesquisa de mensagem no plural.

### Parâmetros

`domain`

  O domínio

`singular`

`plural`

`count`

`category`

### Valor Retornado

Uma string em caso de sucesso.

### Veja Também

- ngettext() - Versão plural de gettext

# dgettext

(PHP 4, PHP 5, PHP 7, PHP 8)

dgettext — Substitui o domínio atual

### Descrição

function dgettext(string `$domain`, string `$message`): string

A função dgettext() permite substituir o domínio atual informado em `domain` para uma única pesquisa de mensagem.

### Parâmetros

`domain`

  O domínio

`message`

  A mensagem

### Valor Retornado

Uma string em caso de sucesso.

### Erros/Exceções

Lança um ValueError se `domain` for uma string vazia.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Agora lança um ValueError se `domain` for uma string vazia.

### Veja Também

- gettext() - Pesquisa uma mensagem no domínio atual

# dngettext

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

dngettext — Versão plural de dgettext

### Descrição

function dngettext(
string `$domain`,
string `$singular`,
string `$plural`,
int `$count`
): string

A função dngettext() permite substituir o domínio atual informado em `domain` para uma única consulta de mensagem no plural.

### Parâmetros

`domain`

  O domínio

`singular`

`plural`

`count`

### Valor Retornado

Uma string em caso de sucesso.

### Erros/Exceções

Lança um ValueError se `domain` for uma string vazia.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Agora lança um ValueError se `domain` for uma string vazia.

### Veja Também

- ngettext() - Versão plural de gettext

# gettext

(PHP 4, PHP 5, PHP 7, PHP 8)

gettext — Pesquisa uma mensagem no domínio atual

### Descrição

function gettext(string `$message`): string

Procura uma mensagem no domínio atual.

### Parâmetros

`message`

  A mensagem que está sendo traduzida.

### Valor Retornado

Retorna uma string traduzida se for encontrada na tabela de tradução, ou a mensagem enviada se não for encontrada.

### Exemplos

Exemplo #1 gettext()-check

    <?php
    // Defina o idioma para alemão
    putenv('LC_ALL=de_DE');
    setlocale(LC_ALL, 'de_DE');

    // Especifique a localização das tabelas de tradução
    bindtextdomain("myPHPApp", "./locale");

    // Escolha o domínio
    textdomain("myPHPApp");

    // A tradução está sendo procurada em ./locale/de_DE/LC_MESSAGES/myPHPApp.mo atualmente

    // Imprima uma mensagem de teste
    echo gettext("Welcome to My PHP Application");

    // Ou utilize o apelido _() para gettext()
    echo _("Have a nice day");
    ?>

### Notas

> Nota:

> Você pode usar o caractere sublinhado '_' como um apelido para esta função.

> Nota:

> Definir um idioma não é suficiente para alguns sistemas e o putenv() deve ser usado para definir o código do idioma atual.

### Veja Também

- _() - Sinônimo de gettext
- setlocale() - Define informação de localidade

# ngettext

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ngettext — Versão plural de gettext

### Descrição

function ngettext(string `$singular`, string `$plural`, int `$count`): string

A versão plural de gettext(). Algumas línguas têm mais de uma forma para mensagens no plural dependendo da quantidade.

### Parâmetros

`singular`

  O ID da mensagem singular.

`plural`

  O ID da mensagem plural.

`count`

  O número (ex.: contagem de itens) para determinar a translação para o respectivo número gramatical.

### Valor Retornado

Retorna a forma plural correta da mensagem identificada por `singular` e `plural` para a quantidade em `count`.

### Exemplos

Exemplo #1 Exemplo de ngettext()

    <?php

    setlocale(LC_ALL, 'cs_CZ');
    printf(ngettext("%d window", "%d windows", 1), 1); // 1 okno
    printf(ngettext("%d window", "%d windows", 2), 2); // 2 okna
    printf(ngettext("%d window", "%d windows", 5), 5); // 5 oken

    ?>

# textdomain

(PHP 4, PHP 5, PHP 7, PHP 8)

textdomain — Define o domínio padrão

### Descrição

function textdomain(?string `$domain` = `null`): string

Esta função define o domínio a ser pesquisado quando chamadas são feitas para gettext(), geralmente o nome de um aplicativo.

### Parâmetros

`domain`

  O novo domínio de mensagem, ou `null` para obter a configuração atual sem alterá-la

### Valor Retornado

Se for bem-sucedida, esta função retorna o domínio de mensagem atual, após possivelmente alterá-lo.

### Erros/Exceções

Lança um ValueError se `domain` for uma string vazia.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Agora lança um ValueError se `domain` for uma string vazia.
8.4.0 | `domain` agora é opcional. Anteriormente, sempre tinha que ser especificado.

### Notas

> Nota:

> As informações do textdomain() são mantidas por processo, não por thread.

## Índice

- _ — Sinônimo de gettext
- bind_textdomain_codeset — Especifica ou obtém a codificação de caracteres na qual as mensagens do catálogo de mensagens de DOMÍNIO serão retornadas
- bindtextdomain — Define ou obtém o caminho para um domínio
- dcgettext — Substitui o domínio por um lookup
- dcngettext — Versão plural de dcgettext
- dgettext — Substitui o domínio atual
- dngettext — Versão plural de dgettext
- gettext — Pesquisa uma mensagem no domínio atual
- ngettext — Versão plural de gettext
- textdomain — Define o domínio padrão

- Instalação/Configuração
  - Dependências
  - Instalação
- Funções da Gettext
  - _ — Sinônimo de gettext
  - bind_textdomain_codeset — Especifica ou obtém a codificação de caracteres na qual as mensagens do catálogo de mensagens de DOMÍNIO serão retornadas
  - bindtextdomain — Define ou obtém o caminho para um domínio
  - dcgettext — Substitui o domínio por um lookup
  - dcngettext — Versão plural de dcgettext
  - dgettext — Substitui o domínio atual
  - dngettext — Versão plural de dgettext
  - gettext — Pesquisa uma mensagem no domínio atual
  - ngettext — Versão plural de gettext
  - textdomain — Define o domínio padrão

# iconv

# Introdução

Este módulo contém uma interface para o recurso de conversão do conjunto de caracteres iconv. Com este módulo, você pode transformar uma string representada por um conjunto de caracteres local em outra representada por outro conjunto de caracteres, que pode ser o conjunto de caracteres Unicode. Os conjuntos de caracteres suportados dependem da implementação iconv do seu sistema. Observe que a função iconv em alguns sistemas pode não funcionar conforme o esperado. Nesse caso, seria uma boa ideia instalar a biblioteca » GNU libiconv. Provavelmente acabará com resultados mais consistentes.

Esta extensão vem com várias funções utilitárias que ajudam você a escrever scripts multilíngues. Vamos dar uma olhada nas seções a seguir para explorar os novos recursos.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução

## Dependências

Você não precisará de nada se o sistema que estiver usando for um dos sistemas compatíveis com POSIX recentes porque as bibliotecas C padrão fornecidas neles devem fornecer o recurso iconv. Caso contrário, você deve ter a biblioteca » libiconv instalada em seu sistema.

## Instalação

Esta extensão é ativada por padrão, embora possa ser desativada compilando com --without-iconv.

A diretiva opcional --with-iconv[=DIR] é usada para especificar a localização do iconv no sistema em que o PHP está sendo compilado, caso contrário, apenas as localizações padrão são verificadas.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de Configuração de Iconv
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
iconv.input_encoding | "" | `INI_ALL` | Descontinuado no PHP 5.6.0.
iconv.output_encoding | "" | `INI_ALL` | Descontinuado no PHP 5.6.0.
iconv.internal_encoding | "" | `INI_ALL` | Descontinuado no PHP 5.6.0.

Aqui está uma breve explicação das diretivas de configuração.

Aviso

Alguns sistemas (como o IBM AIX) usam "ISO8859-1" em vez de "ISO-8859-1", então esse valor deve ser usado em opções de configuração e parâmetros de função.

`iconv.input_encoding` string
  Aviso

  Este recurso foi DESCONTINUADO a partir do PHP 5.6.0. O uso deste recurso é fortemente desencorajado.

  Os usuários do PHP 5.6 e posteriores devem deixar em branco e definir input_encoding .

`iconv.output_encoding` string
  Aviso

  Este recurso foi DESCONTINUADO a partir do PHP 5.6.0. O uso deste recurso é fortemente desencorajado.

  Os usuários do PHP 5.6 e posteriores devem deixar em branco e definir output_encoding

`iconv.internal_encoding` string
  Aviso

  Este recurso foi DESCONTINUADO a partir do PHP 5.6.0. O uso deste recurso é fortemente desencorajado.

  Os usuários do PHP 5.6 e posteriores devem deixar em branco e definir `default_charset` em seu lugar.

# Constantes predefinidas

É possível identificar em tempo de execução qual implementação do `iconv` é adotada por esta extensão.

Constantes de implementação `iconv`
Nome | Tipo | Descrição
--- | --- | ---
`ICONV_IMPL` (string) | string | O nome da implementação
`ICONV_VERSION` (string) | string | A versão de implementação

> Nota:

> Escrever scripts dependentes de implementação com essas constantes é fortemente desencorajado.

As seguintes constantes são também disponível:

Other `iconv` constants
Nome | Tipo | Descrição
--- | --- | ---
`ICONV_MIME_DECODE_STRICT` (int) | int | Uma máscara de bits usada para iconv_mime_decode()
`ICONV_MIME_DECODE_CONTINUE_ON_ERROR` (int) | int | Uma máscara de bits usada para iconv_mime_decode()

# iconv Funções

# Veja Também

Veja também as funções do GNU Recode.

# iconv

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

iconv — Converte uma string de uma codificação de caracteres para outra

### Descrição

function iconv(string `$from_encoding`, string `$to_encoding`, string `$string`): string|false

Converte `string` de `from_encoding` para `to_encoding`.

### Parâmetros

`from_encoding`

  A codificação atual usada para interpretar `string`.

`to_encoding`

  A codificação desejada do resultado.

  Se a string `//TRANSLIT` for anexada a `to_encoding`, a transliteração será ativada. Isso significa que, quando um caractere não pode ser representado no conjunto de caracteres de destino, ele pode ser aproximado por meio de um ou vários caracteres de aparência semelhante. Se a string `//IGNORE` for anexada, os caracteres que não podem ser representados no charset de destino são descartados silenciosamente. Caso contrário, `E_NOTICE` é gerado e a função retornará `false`.

  Cuidado

  Como `//TRANSLIT` funciona exatamente depende da implementação do iconv() do sistema (cf. `ICONV_IMPL`). Algumas implementações são conhecidas por ignorar `//TRANSLIT`, então a conversão provavelmente falhará para caracteres que são ilegais para `to_encoding`.

`string`

  A string a ser convertida

### Valor Retornado

Retorna a string convertida, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo iconv()

    <?php
    $text = "Este é o símbolo do Euro '€'.";

    echo 'Original : ', $text, PHP_EOL;
    echo 'TRANSLIT : ', iconv("UTF-8", "ISO-8859-1//TRANSLIT", $text), PHP_EOL;
    echo 'IGNORE   : ', iconv("UTF-8", "ISO-8859-1//IGNORE", $text), PHP_EOL;
    echo 'Plain    : ', iconv("UTF-8", "ISO-8859-1", $text), PHP_EOL;

    ?>

O exemplo acima produzirá algo semelhante a:

    Original : Este é o símbolo do Euro '€'.
    TRANSLIT : Este é o símbolo do Euro 'EUR'.
    IGNORE   : Este é o símbolo do Euro ''.
    Plain    :
    Notice: iconv(): Detected an illegal character in input string in .\iconv-example.php on line 7

### Notas

> Nota:

> As codificações de caracteres e as opções disponíveis dependem da implementação instalada do iconv. Se o argumento para `from_encoding` ou `to_encoding` não for suportado no sistema atual, `false` será retornado.

### Veja Também

- mb_convert_encoding() - Converte uma string de uma codificação de caracteres para outra
- UConverter::transcode() - Converte uma string de uma codificação de caracteres para outra

# iconv_get_encoding

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

iconv_get_encoding — Recuperar variáveis de configuração internas da extensão iconv

### Descrição

function iconv_get_encoding(string `$type` = "all"): array|string|false

Recuperar variáveis de configuração internas da extensão iconv

### Parâmetros

`type`

  O valor do parâmetro opcional `type` pode ser:

  - all
  - input_encoding
  - output_encoding
  - internal_encoding

### Valor Retornado

Retorna o valor atual da variável de configuração interna se bem sucedido ou `false` em caso de falha.

Se `type` for omitido ou definido como "all", iconv_get_encoding() retorna um array que armazena todas essas variáveis.

### Exemplos

Exemplo #1 Exemplo iconv_get_encoding()

    <pre>
    <?php
    iconv_set_encoding("internal_encoding", "UTF-8");
    iconv_set_encoding("output_encoding", "ISO-8859-1");
    var_dump(iconv_get_encoding('all'));
    ?>
    </pre>

O exemplo acima produzirá:

    Array
    (
        [input_encoding] => ISO-8859-1
        [output_encoding] => ISO-8859-1
        [internal_encoding] => UTF-8
    )

### Veja Também

- iconv_set_encoding() - Define a configuração atual para conversão de codificação de caracteres
- ob_iconv_handler() - Converte codificação de caracteres como manipulador de buffer de saída

# iconv_mime_decode

(PHP 5, PHP 7, PHP 8)

iconv_mime_decode — Decodifica um campo de cabeçalho `MIME`

### Descrição

function iconv_mime_decode(string `$string`, int `$mode` = 0, ?string `$encoding` = `null`): string|false

Decodifica um campo de cabeçalho `MIME`.

### Parâmetros

`string`

  O cabeçalho codificado, como uma string.

`mode`

  `mode` determina o comportamento no caso de iconv_mime_decode() encontrar um campo de cabeçalho `MIME` malformado. Você pode especificar qualquer combinação das seguintes máscaras de bits.

  Máscaras de bits aceitáveis para iconv_mime_decode()
  Valor | Constante | Descrição
  --- | --- | ---
  1 | ICONV_MIME_DECODE_STRICT | Se definido, o cabeçalho fornecido é decodificado em total conformidade com os padrões definidos em » RFC2047. Esta opção está desativada por padrão porque há muitos agentes de usuário de e-mail quebrados que não seguem a especificação e não produzem cabeçalhos `MIME` corretos.
  2 | ICONV_MIME_DECODE_CONTINUE_ON_ERROR | Se definido, iconv_mime_decode_headers() tenta ignorar quaisquer erros gramaticais e continuar a processar um determinado cabeçalho.

`encoding`

  O parâmetro opcional `encoding` especifica o conjunto de caracteres pelo qual representar o resultado. Se omitido ou `null`, iconv.internal_encoding será usado.

### Valor Retornado

Retorna um campo `MIME` decodificado em caso de sucesso ou `false` se ocorrer um erro durante a decodificação.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `encoding` é anulável agora.

### Exemplos

Exemplo #1 Exemplo iconv_mime_decode()

    <?php
    // Isto resulta em "Subject: Prüfung Prüfung"
    echo iconv_mime_decode("Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?=",
                           0, "ISO-8859-1");
    ?>

### Veja Também

- iconv_mime_decode_headers() - Decodifica vários campos de cabeçalho MIME de uma só vez
- mb_decode_mimeheader() - Decodifica string no campo de cabeçalho MIME
- imap_mime_header_decode() - Decodifica elementos do cabeçalho MIME
- imap_base64() - Decodifica texto codificado em BASE64
- imap_qprint() - Converte uma string imprimível escapada em uma string de 8 bits

# iconv_mime_decode_headers

(PHP 5, PHP 7, PHP 8)

iconv_mime_decode_headers — Decodifica vários campos de cabeçalho `MIME` de uma só vez

### Descrição

function iconv_mime_decode_headers(string `$headers`, int `$mode` = 0, ?string `$encoding` = `null`): array|false

Decodifica vários campos de cabeçalho `MIME` de uma só vez.

### Parâmetros

`headers`

  Os cabeçalhos codificados como uma string.

`mode`

  `mode` determina o comportamento no caso de iconv_mime_decode_headers() encontrar um campo de cabeçalho `MIME` malformado. Você pode especificar qualquer combinação das seguintes máscaras de bits.

  Máscaras de bits aceitáveis para iconv_mime_decode_headers()
  Valor | Constante | Descrição
  --- | --- | ---
  1 | ICONV_MIME_DECODE_STRICT | Se definido, o cabeçalho fornecido é decodificado em total conformidade com os padrões definidos em » RFC2047. Esta opção está desativada por padrão porque há muitos agentes de usuário de e-mail quebrados que não seguem a especificação e não produzem cabeçalhos `MIME` corretos.
  2 | ICONV_MIME_DECODE_CONTINUE_ON_ERROR | Se definido, iconv_mime_decode_headers() tenta ignorar quaisquer erros gramaticais e continuar a processar um determinado cabeçalho.

`encoding`

  O parâmetro opcional `encoding` especifica o conjunto de caracteres pelo qual representar o resultado. Se omitido ou `null`, iconv.internal_encoding será usado.

### Valor Retornado

Retorna um array associativo que contém todo um conjunto de campos de cabeçalho `MIME` especificados por `headers` em caso de sucesso ou `false` se ocorrer um erro durante a decodificação.

Cada chave do valor de retorno representa um nome de campo individual e o elemento correspondente representa um valor de campo. Se mais de um campo com o mesmo nome estiver presente, iconv_mime_decode_headers() os incorporará automaticamente em um array indexado numericamente na ordem de ocorrência. Observe que os nomes de cabeçalhos são sensíveis a maiúsculas/minúsculas.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `encoding` é anulável agora.

### Exemplos

Exemplo #1 Exemplo iconv_mime_decode_headers()

    <?php
    $headers_string = <<<EOF
    Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?=
    To: example@example.com
    Date: Thu, 1 Jan 1970 00:00:00 +0000
    Message-Id: <example@example.com>
    Received: from localhost (localhost [127.0.0.1]) by localhost
        with SMTP id example for <example@example.com>;
        Thu, 1 Jan 1970 00:00:00 +0000 (UTC)
        (envelope-from example-return-0000-example=example.com@example.com)
    Received: (qmail 0 invoked by uid 65534); 1 Thu 2003 00:00:00 +0000

    EOF;

    $headers =  iconv_mime_decode_headers($headers_string, 0, "ISO-8859-1");
    print_r($headers);
    ?>

O exemplo acima produzirá:

    Array
    (
        [Subject] => Prüfung Prüfung
        [To] => example@example.com
        [Date] => Thu, 1 Jan 1970 00:00:00 +0000
        [Message-Id] => <example@example.com>
        [Received] => Array
            (
                [0] => from localhost (localhost [127.0.0.1]) by localhost with SMTP id example for <example@example.com>; Thu, 1 Jan 1970 00:00:00 +0000 (UTC) (envelope-from example-return-0000-example=example.com@example.com)
                [1] => (qmail 0 invoked by uid 65534); 1 Thu 2003 00:00:00 +0000
            )

    )

### Veja Também

- iconv_mime_decode() - Decodifica um campo de cabeçalho MIME
- mb_decode_mimeheader() - Decodifica string no campo de cabeçalho MIME
- imap_mime_header_decode() - Decodifica elementos do cabeçalho MIME
- imap_base64() - Decodifica texto codificado em BASE64
- imap_qprint() - Converte uma string imprimível escapada em uma string de 8 bits

# iconv_mime_encode

(PHP 5, PHP 7, PHP 8)

iconv_mime_encode — Compõe um campo de cabeçalho `MIME`

### Descrição

function iconv_mime_encode(string `$field_name`, string `$field_value`, array `$options` = []): string|false

Compõe e retorna uma string que representa um campo de cabeçalho `MIME` válido, semelhante ao seguinte:

    Subject: =?ISO-8859-1?Q?Pr=FCfung_f=FCr?= Entwerfen von einer MIME kopfzeile

No exemplo acima, "Subject" é o nome do campo e a parte que começa com "=?ISO-8859-1?..." é o valor do campo.

### Parâmetros

`field_name`

  O nome do campo.

`field_value`

  O valor do campo.

`options`

  Você pode controlar o comportamento de iconv_mime_encode() especificando um array associativo que contém itens de configuração para as `options` opcionais do terceiro parâmetro. Os itens suportados por iconv_mime_encode() estão listados abaixo. Observe que os nomes dos itens são tratados com distinção entre maiúsculas e minúsculas.

  Itens de configuração suportados por iconv_mime_encode()
  Item | Tipo | Descrição | Valor padrão | Exemplo
  --- | --- | --- | --- | ---
  scheme | string | Especifica o método para codificar um valor de campo. O valor deste item pode ser "B" ou "Q", onde "B" significa esquema de codificação `base64` e "Q" significa esquema de codificação `quoted-printable`. | B | B
  input-charset | string | Especifica o conjunto de caracteres no qual o primeiro parâmetro `field_name` e o segundo parâmetro `field_value` são apresentados. Se não for fornecido, iconv_mime_encode() assume que esses parâmetros são apresentados a ele na configuração ini iconv.internal_encoding . | iconv.internal_encoding | ISO-8859-1
  output-charset | string | Especifica o conjunto de caracteres a ser usado para compor o cabeçalho `MIME`. | iconv.internal_encoding | UTF-8
  line-length | int | Especifica o comprimento máximo das linhas de cabeçalho. O cabeçalho resultante é "dobrado" em um conjunto de múltiplas linhas caso o campo do cabeçalho resultante seja maior que o valor deste parâmetro, de acordo com » RFC2822 - Internet Message Format. Se não for fornecido, o comprimento será limitado a 76 caracteres. | 76 | 996
  line-break-chars | string | Especifica a sequência de caracteres a ser anexada a cada linha como um sinal de fim de linha quando a "dobragem" é executada em um campo de cabeçalho longo. Se não fornecido, o padrão é "\r\n" (`CR` `LF`). Observe que esse parâmetro é sempre tratado como uma string ASCII, independentemente do valor de `input-charset`. | \r\n | \n

### Valor Retornado

Retorna um campo `MIME` codificado em caso de sucesso ou `false` se ocorrer um erro durante a codificação.

### Exemplos

Exemplo #1 Exemplo iconv_mime_encode()

    <?php
    $preferences = array(
        "input-charset" => "ISO-8859-1",
        "output-charset" => "UTF-8",
        "line-length" => 76,
        "line-break-chars" => "\n"
    );
    $preferences["scheme"] = "Q";
    // Isto resulta em "Subject: =?UTF-8?Q?Pr=C3=BCfung=20Pr=C3=BCfung?="
    echo iconv_mime_encode("Subject", "Prüfung Prüfung", $preferences);

    $preferences["scheme"] = "B";
    // Isto resulta em "Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?="
    echo iconv_mime_encode("Subject", "Prüfung Prüfung", $preferences);
    ?>

### Veja Também

- imap_binary() - Converte uma string de 8 bits em uma string base64
- mb_encode_mimeheader() - Codificar string para cabeçalho MIME
- imap_8bit() - Converte uma string de 8 bits em uma string imprimível escapada
- quoted_printable_encode() - Converte uma string de 8 bits para uma string Quoted-Printable

# iconv_set_encoding

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

iconv_set_encoding — Define a configuração atual para conversão de codificação de caracteres

### Descrição

function iconv_set_encoding(string `$type`, string `$encoding`): bool

Altera o valor da variável de configuração interna especificada por `type` para `encoding`.

### Parâmetros

`type`

  O valor de `type` pode ser qualquer um destes:

  - input_encoding
  - output_encoding
  - internal_encoding
`encoding`

  O conjunto de caracteres.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo iconv_set_encoding()

    <?php
    iconv_set_encoding("internal_encoding", "UTF-8");
    iconv_set_encoding("output_encoding", "ISO-8859-1");
    ?>

### Veja Também

- iconv_get_encoding() - Recuperar variáveis de configuração internas da extensão iconv
- ob_iconv_handler() - Converte codificação de caracteres como manipulador de buffer de saída

# iconv_strlen

(PHP 5, PHP 7, PHP 8)

iconv_strlen — Retorna a contagem de caracteres da string

### Descrição

function iconv_strlen(string `$string`, ?string `$encoding` = `null`): int|false

Ao contrário de strlen(), iconv_strlen() conta as ocorrências de caracteres na `string` de sequência de bytes fornecida com base no conjunto de caracteres especificado, cujo resultado não é necessariamente idêntico ao comprimento da string em bytes.

### Parâmetros

`string`

  A string.

`encoding`

  Se o parâmetro `encoding` for omitido ou `null`, presume-se que a `string` esteja codificada em iconv.internal_encoding.

### Valor Retornado

Retorna a contagem de caracteres da `string`, como um número inteiro, ou `false` se ocorrer um erro durante a codificação.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `encoding` é anulável agora.

### Veja Também

- grapheme_strlen() - Obtém o comprimento de uma string em unidade de grafema
- mb_strlen() - Obtém o comprimento da string
- strlen() - Retorna o tamanho de uma string

# iconv_strpos

(PHP 5, PHP 7, PHP 8)

iconv_strpos — Localiza a posição da primeira ocorrência de um caractere em uma string

### Descrição

function iconv_strpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

Localiza a posição da primeira ocorrência de um `needle` em um `haystack`.

Em contraste com strpos(), o valor de retorno de iconv_strpos() é o número de caracteres que aparecem antes da agulha, em vez do deslocamento em bytes para a posição onde a agulha foi encontrada. Os caracteres são contados com base no `encoding` do conjunto de caracteres especificado.

### Parâmetros

`haystack`

  A string inteira.

`needle`

  A substring pesquisada.

`offset`

  O parâmetro `offset` opcional especifica a posição a partir da qual a pesquisa deve ser realizada. Se o offset for negativo, ele será contado a partir do final da string.

`encoding`

  Se o parâmetro `encoding` for omitido ou `null`, presume-se que a `string` esteja codificada em iconv.internal_encoding.

Se `haystack` ou `needle` não for uma string, ela será convertida em uma string e aplicada como o valor ordinal de um caractere.

### Valor Retornado

Retorna a posição numérica da primeira ocorrência de `needle` em `haystack`.

Se `needle` não for encontrada, iconv_strpos() retornará `false`.

Aviso

Esta função pode retornar o valor booleano `false`, mas também pode retornar um valor não booleano que pode ser avaliado como `false`. Leia a seção sobre Booleanos para mais informações. Use o operador === para testar o valor retornado por esta função.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `encoding` é anulável agora.
7.1.0 | O suporte para `offset`s negativas foi adicionado.

### Veja Também

- strpos() - Encontra a posição da primeira ocorrência de uma substring em uma string
- iconv_strrpos() - Localiza a última ocorrência de um caractere em uma string
- mb_strpos() - Encontra a posição da primeira ocorrência de uma string em outra

# iconv_strrpos

(PHP 5, PHP 7, PHP 8)

iconv_strrpos — Localiza a última ocorrência de um caractere em uma string

### Descrição

function iconv_strrpos(string `$haystack`, string `$needle`, ?string `$encoding` = `null`): int|false

Localiza a última ocorrência de `needle` em `haystack`.

Em contraste com strrpos(), o valor de retorno de iconv_strrpos() é o número de caracteres que aparecem antes de needle, em vez do deslocamento em bytes para a posição onde needle foi encontrada. Os caracteres são contados com base no `encoding` do conjunto de caracteres especificado.

### Parâmetros

`haystack`

  The string inteira.

`needle`

  A substring pesquisada.

`encoding`

  Se o parâmetro `encoding` for omitido ou `null`, presume-se que a `string` esteja codificada em iconv.internal_encoding.

Se `haystack` ou `needle` não for uma string, ela será convertida em uma string e aplicada como o valor ordinal de um caractere.

### Valor Retornado

Retorna a posição numérica da última ocorrência de `needle` em `haystack`.

Se `needle` não for encontrada, iconv_strrpos() retornará `false`.

Aviso

Esta função pode retornar o valor booleano `false`, mas também pode retornar um valor não booleano que pode ser avaliado como `false`. Leia a seção sobre Booleanos para mais informações. Use o operador === para testar o valor retornado por esta função.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `encoding` é anulável agora.

### Veja Também

- strrpos() - Encontra a posição da última ocorrência de uma substring em uma string
- iconv_strpos() - Localiza a posição da primeira ocorrência de um caractere em uma string
- mb_strrpos() - Encontra a posição da última ocorrência de uma string em outra string

# iconv_substr

(PHP 5, PHP 7, PHP 8)

iconv_substr — Corta parte de uma string

### Descrição

function iconv_substr(
string `$string`,
int `$offset`,
?int `$length` = `null`,
?string `$encoding` = `null`
): string|false

Corta uma parte da `string` especificada pelos parâmetros `offset` e `length`.

### Parâmetros

`string`

  A string original.

`offset`

  Se `offset` não for negativo, iconv_substr() corta a parte da `string` começando no `offset`'th caractere, contando a partir de zero.

  Se `offset` for negativo, iconv_substr() corta a parte que começa na posição, desloca `offset` caracteres para longe do final da `string`.

`length`

  Se `length` for fornecido e for positivo, o valor de retorno conterá no máximo caracteres de `length` da parte que começa no `offset` (dependendo do comprimento da `string`).

  Se `length` for negativo, iconv_substr() cortará a parte da `string` desde o caractere `offset`'th até o caractere do `length` final da string. Caso `offset` também seja negativo, a posição inicial é calculada antecipadamente de acordo com a regra explicada acima.

`encoding`

  Se o parâmetro `encoding` for omitido ou `null`, presume-se que a `string` esteja codificada em iconv.internal_encoding.

  Observe que os parâmetros `offset` e `length` são sempre considerados como representando deslocamentos que são calculados com base no conjunto de caracteres determinado por `encoding`, enquanto a contraparte substr() sempre os considera deslocamentos de byte.

### Valor Retornado

Retorna a parte da `string` especificada pelos parâmetros `offset` e `length`.

Se `string` for menor que os caracteres de `offset`, `false` será retornado. Se `string` tiver exatamente o comprimento de caracteres de `offset`, uma string vazia será retornada.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `length` e `encoding` são anuláveis agora.
7.0.11 | Se `string` for igual ao comprimento dos caracteres de `offset`, uma string vazia será retornada. Antes desta versão, `false` era retornado neste caso.

### Veja Também

- substr() - Retorna parte de uma string
- mb_substr() - Obtém parte da string
- mb_strcut() - Obtém parte da string

# ob_iconv_handler

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

ob_iconv_handler — Converte codificação de caracteres como manipulador de buffer de saída

### Descrição

function ob_iconv_handler(string `$contents`, int `$status`): string

Converte a string codificada em `internal_encoding` em `output_encoding`.

`internal_encoding` e `output_encoding` devem ser definidos no arquivo php.ini ou em iconv_set_encoding().

### Parâmetros

Consulte ob_start() para obter informações sobre os parâmetros desse manipulador.

### Valor Retornado

Consulte ob_start() para obter informações sobre os valores de retorno desse manipulador.

### Exemplos

Exemplo #1 Exemplo ob_iconv_handler():

    <?php
    iconv_set_encoding("internal_encoding", "UTF-8");
    iconv_set_encoding("output_encoding", "ISO-8859-1");
    ob_start("ob_iconv_handler"); // start output buffering
    ?>

### Veja Também

- iconv_get_encoding() - Recuperar variáveis de configuração internas da extensão iconv
- iconv_set_encoding() - Define a configuração atual para conversão de codificação de caracteres
- output-control functions

## Índice

- iconv — Converte uma string de uma codificação de caracteres para outra
- iconv_get_encoding — Recuperar variáveis de configuração internas da extensão iconv
- iconv_mime_decode — Decodifica um campo de cabeçalho MIME
- iconv_mime_decode_headers — Decodifica vários campos de cabeçalho MIME de uma só vez
- iconv_mime_encode — Compõe um campo de cabeçalho MIME
- iconv_set_encoding — Define a configuração atual para conversão de codificação de caracteres
- iconv_strlen — Retorna a contagem de caracteres da string
- iconv_strpos — Localiza a posição da primeira ocorrência de um caractere em uma string
- iconv_strrpos — Localiza a última ocorrência de um caractere em uma string
- iconv_substr — Corta parte de uma string
- ob_iconv_handler — Converte codificação de caracteres como manipulador de buffer de saída

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
- Constantes predefinidas
- iconv Funções
  - iconv — Converte uma string de uma codificação de caracteres para outra
  - iconv_get_encoding — Recuperar variáveis de configuração internas da extensão iconv
  - iconv_mime_decode — Decodifica um campo de cabeçalho MIME
  - iconv_mime_decode_headers — Decodifica vários campos de cabeçalho MIME de uma só vez
  - iconv_mime_encode — Compõe um campo de cabeçalho MIME
  - iconv_set_encoding — Define a configuração atual para conversão de codificação de caracteres
  - iconv_strlen — Retorna a contagem de caracteres da string
  - iconv_strpos — Localiza a posição da primeira ocorrência de um caractere em uma string
  - iconv_strrpos — Localiza a última ocorrência de um caractere em uma string
  - iconv_substr — Corta parte de uma string
  - ob_iconv_handler — Converte codificação de caracteres como manipulador de buffer de saída

# Funções de Internacionalização

# Introdução

A extensão de Internacionalização (referenciada a partir daqui como Intl) é um empacotador para a biblioteca » ICU, e permite que programadores de PHP realizem várias operações dependentes de localidade, incluindo mas não limitadas a formatação, transliteração, conversão de codificação, operações de calendário, colação em conformidade com » UCA, localização de limites de texto e tarefas com identificadores de localidade, de fusos horários e de grafemas.

A extensão tende a seguir de perto as APIs da ICU, para que as pessoas com experiência em ICU com C/C++ ou Java possam facilmente usar a API do PHP. Além disso, dessa forma a documentação da ICU torna-se útil para se compreender várias funções da ICU.

Intl consiste de vários módulos, cada um expondo a correspondente API da ICU:

- Agrupador: fornece capacidade de comparação de strings com suporte ao ordenamento adequado, dependente da localidade.
- Formatador de Números: permite apresentar um número de acordo com o formato da localidade ou com um padrão ou conjunto de regras fornecido, e interpretar strings como números.
- Formatador de Mensagem: permite criar mensagens incorporando dados (como números ou datas) formatados de acordo com um padrão fornecido e com regras de localidade, e analisar mensagens extraindo dados delas. Pode lidar com plurais, números dependentes de localidade, moedas, condições e muito mais.
- Normalizador: fornece uma função para transformar texto em uma das formas de normalização Unicode, e fornece uma rotina para testar se uma string fornecida já está normalizada.
- Localidade: fornece interação com identificadores de localidade na forma de funções para obter sub-etiquetas a partir deles; analisar, compor e comparar (pesquisa e filtro) identificadores de localidade.
- Calendário: fornece uma classe que pode ser usada para operações de calendário dependentes de localidade e obtenção de várias informações como fuso horário para a localidade escolhida, primeiro dia da semana ou horário de verão.
- Fuso Horário: fornece um empacotador sobre o » banco de dados "Olson" que tem informação sobre todos os fusos horário ao redor do mundo.
- Formatador de Data: permite apresetar data e horário de acordo com o formato da localidade, ou um padrão ou um conjunto de regras fornecido, e converter strings como data e hora.
- Transliterador: permite obter representação latina de strings em várias línguas.

## Links

- » Documentos ICU miscelâneos

- » Guia do Usuário ICU

- » Algoritmo de Agrupamento Unicode

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução

## Dependências

Para construir a extensão é necessário instalar a biblioteca » ICU. Versão 4.0.0 ou posterior é requerida. A partir do PHP 7.4.0, ICU 50.1 ou posterior é requerida.

## Instalação

--enable-intl habilitará a extensão ao compilar o PHP.

Se a ICU estiver instalada em um diretório fora do padrão, sua localização pode ser especificada na variável de ambiente `LD_LIBRARY_PATH` para que o vinculador dinâmico possa encontrá-lo:

$ export LD_LIBRARY_PATH=/opt/icu/lib

Caso o PHP e a ICU estejam instalados em suas localizações padrão, as opções adicionais para o comando configure não são necessárias.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de Configuração de Intl
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
intl.default_locale |  | `INI_ALL` |
intl.error_level | 0 | `INI_ALL` |
intl.use_exceptions | 0 | `INI_ALL` | Disponível desde o PECL 3.0.0a1

Aqui está uma breve explicação das diretivas de configuração.

`intl.default_locale` string

  A localidade que será utilizada quando nenhuma for especificada (omitindo o argumento correspondente ou passando-se `NULL`). Estas são localidades ICU, não localidades de sistema. As localidades ICU embutidas e seus dados podem ser explorados em » https://unicode-org.github.io/icu/userguide/locale/.

  O valor padrão é vazio, o que força o uso da localidade ICU padrão. Uma vez definida, a configuração ini não pode ser redefinida para este valor padrão. Não é recomendado confiar neste padrão, pois seu valor efetivo depende do ambiente do servidor.

`intl.error_level` int

  O tipo de mensagens de erro geradas quando um erro ocorre em funções ICU. Isto é um nível de erro PHP, como `E_WARNING` por exemplo. Pode ser definida para `0` para inibir as mensagens. Não afeta os valores de retorno que indicam erro ou os valores retornados por intl_get_error_code() ou pelos métodos específicos da classe para recuperar códigos e mensagens de erro.

  O valor padrão é `0`.

`intl.use_exceptions` int

  Se definido para true, uma exceção será lançada quando um erro ocorrer em uma função intl. A exceção será do tipo IntlException. É possível fazer isto em adição à mensagem de erro gerada devido à configuração intl.error_level.

  O valor padrão é `false`.

# Constantes predefinidas

`INTL_ICU_DATA_VERSION` (string)
  Versão dos dados na ICU4C.
`INTL_ICU_VERSION` (string)
  A versão da biblioteca ICU atual como uma string decimal com pontos.
`INTL_MAX_LOCALE_LEN` (int)
  Limite de comprimento do nome da localidade, definido para 80 no código PHP. Nomes mais longos que este limite não serão aceitos.
`IDNA_DEFAULT` (int)
  Proíbe o processamento de pontos de código não atribuídos na entrada para funções IDN e não verifica se a entrada está conforme as regras ASCII de nome de domínio.
`IDNA_ALLOW_UNASSIGNED` (int)
  Permite o processamento de pontos de código não atribuídos na entrada para funções IDN.
`IDNA_USE_STD3_RULES` (int)
  Verifica se a entrada para funções IDN está conforme as regras ASCII de nome de domínio.
`IDNA_CHECK_BIDI` (int)
  Verifica se a entrada está conforme as regras BiDi. Ignorada pela implementação IDNA2003, que sempre faz esta verificação.
`IDNA_CHECK_CONTEXTJ` (int)
  Verifica se a entrada está conforme as regras CONTEXTJ. Ignorada pela implementação IDNA2003, pois é uma verificação nova na IDNA2008.
`IDNA_NONTRANSITIONAL_TO_ASCII` (int)
  Opção para processamento não transicional na função idn_to_ascii(). Processamento transicional é ativado por padrão. Esta opção é ignorada pela implementação IDNA2003.
`IDNA_NONTRANSITIONAL_TO_UNICODE` (int)
  Opção para processamento não transicional na função idn_to_utf8(). Processamento transicional é ativado por padrão. Esta opção é ignorada pela implementação IDNA2003.
`INTL_IDNA_VARIANT_2003` (int)
  Usa o algoritmo IDNA 2003 nas funções idn_to_utf8() e idn_to_ascii(). Este é o padrão. Esta constante e o uso do padrão foram descontinuados a partir do PHP 7.2.0.
`INTL_IDNA_VARIANT_UTS46` (int)
  Usa o algoritmo UTS #46 nas funções idn_to_utf8() e idn_to_ascii(). Disponível a partir da ICU 4.6.
`GRAPHEME_EXTR_COUNT` (int)
  O número padrão de conjuntos de grafemas a serem extraídos.
`GRAPHEME_EXTR_MAXBYTES` (int)
  O número máximo de bytes retornados.
`GRAPHEME_EXTR_MAXCHARS` (int)
  O número máximo de caracteres UTF-8 retornados.

Os erros a seguir são parte de uma máscara de bits retornada pelo algoritmo UTS #46 nas funções idn_to_utf8() e idn_to_ascii().

`IDNA_ERROR_EMPTY_LABEL` (int)
`IDNA_ERROR_LABEL_TOO_LONG` (int)
`IDNA_ERROR_DOMAIN_NAME_TOO_LONG` (int)
`IDNA_ERROR_LEADING_HYPHEN` (int)
`IDNA_ERROR_TRAILING_HYPHEN` (int)
`IDNA_ERROR_HYPHEN_3_4` (int)
`IDNA_ERROR_LEADING_COMBINING_MARK` (int)
`IDNA_ERROR_DISALLOWED` (int)
`IDNA_ERROR_PUNYCODE` (int)
`IDNA_ERROR_LABEL_HAS_DOT` (int)
`IDNA_ERROR_INVALID_ACE_LABEL` (int)
`IDNA_ERROR_BIDI` (int)
`IDNA_ERROR_CONTEXTJ` (int)
`ULOC_ACTUAL_LOCALE` (int)
  A localidade de onde os dados realmente vêm.
`ULOC_VALID_LOCALE` (int)
  A localidade mais específica suportada pela ICU.
`U_AMBIGUOUS_ALIAS_WARNING` (int)
  Este apelido de conversor pode ir para diferentes implementações de conversão.
`U_BAD_VARIABLE_DEFINITION` (int)
  Falta o caractere `'$'` ou existe um nome de variável duplicado.
`U_BRK_ASSIGN_ERROR` (int)
  Erro de sintaxe na isntrução de atribuição de regra RBBI.
`U_BRK_ERROR_LIMIT` (int)
  Este deve ser sempre o último valor para indicar o limite de falhas de Break Iterator.
`U_BRK_ERROR_START` (int)
  Início de códigos indicando falhas de Break Iterator.
`U_BRK_HEX_DIGITS_EXPECTED` (int)
  Dígitos hexadecimais esperados como parte de um caractere escapado em uma regra.
`U_BRK_INIT_ERROR` (int)
  Falha de inicialização. Provavelmente faltam dados da ICU.
`U_BRK_INTERNAL_ERROR` (int)
  Um erro interno foi detectado.
`U_BRK_MALFORMED_RULE_TAG` (int)
  A etiqueta `{nnn}` em uma regra está mal formada.
`U_BRK_MISMATCHED_PAREN` (int)
  Falta de correspondência de parênteses em uma regra RBBI.
`U_BRK_NEW_LINE_IN_QUOTED_STRING` (int)
  Faltam aspas de fechamento em uma regra RBBI.
`U_BRK_RULE_EMPTY_SET` (int)
  Regra contém um Conjunto Unicode vazio.
`U_BRK_RULE_SYNTAX` (int)
  Erro de sintaxe em regra RBBI.
`U_BRK_SEMICOLON_EXPECTED` (int)
  Falta `';'` ao final de uma regra RBBI.
`U_BRK_UNCLOSED_SET` (int)
  Conjunto Unicode escrevendo uma regra RBBI faltando um `']'` de fechamento.
`U_BRK_UNDEFINED_VARIABLE` (int)
  Uso de variável (`$Variable`) indefinida em uma regra RBBI.
`U_BRK_UNRECOGNIZED_OPTION` (int)
  Opção em regra RBBI não reconhecida.
`U_BRK_VARIABLE_REDFINITION` (int)
  Variável de regra RBBI redefinida.
`U_BUFFER_OVERFLOW_ERROR` (int)
  Um resultado não coube no buffer fornecido.
`U_CE_NOT_FOUND_ERROR` (int)
  Atualmente usado somente ao configurar topo de variável, mas pode ser usado genericamente.
`U_COLLATOR_VERSION_MISMATCH` (int)
  Versão da colação não compatível com a versão base.
`U_DIFFERENT_UCA_VERSION` (int)
  ucol_open encontrou uma inconsistência entre a versão UCA e a versão de imagem da colação, poratanto a colação foi contruída a partir de regras. Sem impacto para funções seguintes.
`U_ENUM_OUT_OF_SYNC_ERROR` (int)
  `UEnumeration` fora de sincronia com colação subjacente.
`U_ERROR_LIMIT` (int)
  Apelido de `U_PLUGIN_ERROR_LIMIT`.
`U_ERROR_WARNING_LIMIT` (int)
  Este precisa ser o último valor de alerta que indica o limite para alertas UErrorCode (último código de alerta +1).
`U_ERROR_WARNING_START` (int)
  Início dos resultados de informação (semanticamente bem-sucedidos).
`U_FILE_ACCESS_ERROR` (int)
  O arquivo solicitado não pôde ser encontrado.
`U_FMT_PARSE_ERROR_LIMIT` (int)
  O limite para erros de bibiliotecas de formatação.
`U_FMT_PARSE_ERROR_START` (int)
  Início de erros de bibiliotecas de formatação.
`U_IDNA_ACE_PREFIX_ERROR` (int)
`U_IDNA_CHECK_BIDI_ERROR` (int)
`U_IDNA_DOMAIN_NAME_TOO_LONG_ERROR` (int)
`U_IDNA_ERROR_LIMIT` (int)
`U_IDNA_ERROR_START` (int)
`U_IDNA_LABEL_TOO_LONG_ERROR` (int)
`U_IDNA_PROHIBITED_ERROR` (int)
`U_IDNA_STD3_ASCII_RULES_ERROR` (int)
`U_IDNA_UNASSIGNED_ERROR` (int)
`U_IDNA_VERIFICATION_ERROR` (int)
`U_IDNA_ZERO_LENGTH_LABEL_ERROR` (int)
`U_ILLEGAL_ARGUMENT_ERROR` (int)
  Indica um valor de argumento incorreto.
`U_ILLEGAL_CHAR_FOUND` (int)
  Conversão de caracteres: sequência ilegal de entrada.
`U_ILLEGAL_CHAR_IN_SEGMENT` (int)
  Não utilizada a partir da ICU 2.4.
`U_ILLEGAL_CHARACTER` (int)
  Um caractere especial está fora de seu contexto permitido.
`U_ILLEGAL_ESCAPE_SEQUENCE` (int)
  Sequência de escape ISO-2022 ilegal.
`U_ILLEGAL_PAD_POSITION` (int)
  Símbolo de preenchimento mal posicionado no modelo de numeral.
`U_INDEX_OUTOFBOUNDS_ERROR` (int)
  Tentativa de acessar índice fora do intervalo.
`U_INTERNAL_PROGRAM_ERROR` (int)
  Indica um problema no código de programação da biblioteca.
`U_INTERNAL_TRANSLITERATOR_ERROR` (int)
  Erro de sistema interno do transliterador.
`U_INVALID_CHAR_FOUND` (int)
  Conversão de caracteres: sequência de entrada não mapeada. Em outras APIs: caractere inválido.
`U_INVALID_FORMAT_ERROR` (int)
  Formato de data não está conforme esperado.
`U_INVALID_FUNCTION` (int)
  Uma regra `'&fn()'` especifica um transliterador desconhecido.
`U_INVALID_ID` (int)
  Uma regra `'::id'` especifica um transliterador desconhecido.
`U_INVALID_PROPERTY_PATTERN` (int)
  Não utilizada a partir da ICU 2.4.
`U_INVALID_RBT_SYNTAX` (int)
  Uma regra `'::id'` foi passada ao interpretador RuleBasedTransliterator.
`U_INVALID_STATE_ERROR` (int)
  A operação solicitada não pode ser concluída com a ICU no estado atual.
`U_INVALID_TABLE_FILE` (int)
  Arquivo de tabela de conversão não encontrado.
`U_INVALID_TABLE_FORMAT` (int)
  Arquivo de tabela de conversão encontrado, porém corrompido.
`U_INVARIANT_CONVERSION_ERROR` (int)
  Não foi possível converter uma string `UChar*` para `char*` com o conversor invariante.
`U_MALFORMED_EXPONENTIAL_PATTERN` (int)
  Símbolo de agrupamento no modelo de expoente.
`U_MALFORMED_PRAGMA` (int)
  Um pragma `'use'` está inválido.
`U_MALFORMED_RULE` (int)
  Elementos de uma regra estão mal posicionados.
`U_MALFORMED_SET` (int)
  Um modelo de `UnicodeSet` está inválido.
`U_MALFORMED_SYMBOL_REFERENCE` (int)
  Não utilizada a partir da ICU 2.4.
`U_MALFORMED_UNICODE_ESCAPE` (int)
  Um modelo de escape Unicode está inválido.
`U_MALFORMED_VARIABLE_DEFINITION` (int)
  Uma definição de variável está inválida.
`U_MALFORMED_VARIABLE_REFERENCE` (int)
  Uma referência a variável está inválida.
`U_MEMORY_ALLOCATION_ERROR` (int)
  Erro de alocação de memória.
`U_MESSAGE_PARSE_ERROR` (int)
  Não foi possível interpretar uma mensagem (formato da mensagem).
`U_MISMATCHED_SEGMENT_DELIMITERS` (int)
  Não utilizada a partir da ICU 2.4.
`U_MISPLACED_ANCHOR_START` (int)
  Uma âncora de início aparece em uma posição ilegal.
`U_MISPLACED_COMPOUND_FILTER` (int)
  Um filtro composto está em uma localização ilegal.
`U_MISPLACED_CURSOR_OFFSET` (int)
  Um deslocamento de cursor aparece em uma posição ilegal.
`U_MISPLACED_QUANTIFIER` (int)
  Um quantificador aparece após um delimitador de fechamento de segmento.
`U_MISSING_OPERATOR` (int)
  Uma regra não contém operador.
`U_MISSING_RESOURCE_ERROR` (int)
  O recurso solicitado não pôde ser encontrado.
`U_MISSING_SEGMENT_CLOSE` (int)
  Não utilizada a partir da ICU 2.4.
`U_MULTIPLE_ANTE_CONTEXTS` (int)
  Mais que um contexto "ante".
`U_MULTIPLE_COMPOUND_FILTERS` (int)
  Mais que um filtro composto.
`U_MULTIPLE_CURSORS` (int)
  Mais que um cursor.
`U_MULTIPLE_DECIMAL_SEPARATORS` (int)
  Mais que um separador de decimais no modelo de numeral.
`U_MULTIPLE_DECIMAL_SEPERATORS` (int)
  Apelido de `U_MULTIPLE_DECIMAL_SEPARATORS`.
`U_MULTIPLE_EXPONENTIAL_SYMBOLS` (int)
  Mais que um símbolo de expoente no modelo de numeral.
`U_MULTIPLE_PAD_SPECIFIERS` (int)
  Mais que um símbolo de preenchimento no modelo de numeral.
`U_MULTIPLE_PERCENT_SYMBOLS` (int)
  Mais que um símbolo de porcentagem no modelo de numeral.
`U_MULTIPLE_PERMILL_SYMBOLS` (int)
  Mais que um símbolo de permilagem no modelo de numeral.
`U_MULTIPLE_POST_CONTEXTS` (int)
  Mais que um contexto "post".
`U_NO_SPACE_AVAILABLE` (int)
  Não há espaço disponível para expansão em-buffer para formas arábicas.
`U_NO_WRITE_PERMISSION` (int)
  Tentativa de modificação de dados constantes ou somente-leitura.
`U_PARSE_ERROR` (int)
  Equivalente ao `ParseException` do Java.
`U_PARSE_ERROR_LIMIT` (int)
  O limite para erros de Transliteradores.
`U_PARSE_ERROR_START` (int)
  Início de erros de Transliteradores.
`U_PATTERN_SYNTAX_ERROR` (int)
  Erro de sintaxe no modelo de formatação.
`U_PRIMARY_TOO_LONG_ERROR` (int)
  Usuário tentou definit topo de variável a um primário mais longo que dois bytes.
`U_REGEX_BAD_ESCAPE_SEQUENCE` (int)
  Sequência de escape com barra invertida desconhecida no modelo.
`U_REGEX_BAD_INTERVAL` (int)
  Erro no intervalo `{min,max}`.
`U_REGEX_ERROR_LIMIT` (int)
  Este valor precisa ser o último a indicar o limite de erros de expressões regulares.
`U_REGEX_ERROR_START` (int)
  Início de código indicando falhas de expressões regulares.
`U_REGEX_INTERNAL_ERROR` (int)
  Um erro interno (bug) foi detectado.
`U_REGEX_INVALID_BACK_REF` (int)
  Referência retroativa a grupo de captura não existente.
`U_REGEX_INVALID_FLAG` (int)
  Valor inválido para sinalizadores de modo de correspondência.
`U_REGEX_INVALID_STATE` (int)
  `RegexMatcher` em estado inválido para a operação requisitada.
`U_REGEX_LOOK_BEHIND_LIMIT` (int)
  Correspondências de modelo de Look-Behind precisam ter um comprimento máximo limitado.
`U_REGEX_MAX_LT_MIN` (int)
  Em `{min,max}`, max é menor que min.
`U_REGEX_MISMATCHED_PAREN` (int)
  Parênteses aninhados incorretamente no modelo de expressões regulares.
`U_REGEX_NUMBER_TOO_BIG` (int)
  Número decimal é muito grande.
`U_REGEX_PROPERTY_SYNTAX` (int)
  Propriedade Unicode incorreta.
`U_REGEX_RULE_SYNTAX` (int)
  Erro de sintaxe no modelo de expressões regulares.
`U_REGEX_SET_CONTAINS_STRING` (int)
  Expressões regulares não podem ter `UnicodeSet`s contendo strings.
`U_REGEX_UNIMPLEMENTED` (int)
  Uso de um recurso de expressões regulares que ainda não está implementado.
`U_RESOURCE_TYPE_MISMATCH` (int)
  Uma operação é solicitada em um recurso que não a suporta.
`U_RULE_MASK_ERROR` (int)
  Uma regra está inibida por uma regra anterior mais geral.
`U_SAFECLONE_ALLOCATED_WARNING` (int)
  Uma operação `SafeClone` solicitou alocação de memória (apenas informacional).
`U_SORT_KEY_TOO_SHORT_WARNING` (int)
  Número de níveis solicitados em `getBound` é maior que o número de níveis na chave de ordenação.
`U_STANDARD_ERROR_LIMIT` (int)
  Este valor precisa ser um último a indicar o limite para erros padrão.
`U_STATE_OLD_WARNING` (int)
  ICU tem que usar camada de compatibilidade para construir o serviço. Esperada degradação de desempenho/uso de memória.
`U_STATE_TOO_OLD_ERROR` (int)
  ICU não pode construir um serviço a partir deste estado, já que não é mais suportado.
`U_STRING_NOT_TERMINATED_WARNING` (int)
  Uma string de saída não pode ter o byte NUL de terminação porque o comprimento da saída é igual à capacidade de destino (`length==destCapacity`).
`U_STRINGPREP_CHECK_BIDI_ERROR` (int)
  Apelido de `U_IDNA_CHECK_BIDI_ERROR`.
`U_STRINGPREP_PROHIBITED_ERROR` (int)
  Apelido de `U_IDNA_PROHIBITED_ERROR`.
`U_STRINGPREP_UNASSIGNED_ERROR` (int)
  Apelido de `U_IDNA_UNASSIGNED_ERROR`.
`U_TOO_MANY_ALIASES_ERROR` (int)
  Há muitos apelidos no caminho para o recurso solicitado. É bem possível que uma referência circular de definição de apelidos tenha ocorrido.
`U_TRAILING_BACKSLASH` (int)
  Uma barra invertida sobrando no final da sequência.
`U_TRUNCATED_CHAR_FOUND` (int)
  Conversão de caracteres: sequência de entrada incompleta.
`U_UNCLOSED_SEGMENT` (int)
  Um `')'` de fechamento está faltando.
`U_UNDEFINED_SEGMENT_REFERENCE` (int)
  Uma referência de segmento não corresponde a um segmento definido.
`U_UNDEFINED_VARIABLE` (int)
  Uma referência de variável não corresponde a uma variável definida.
`U_UNEXPECTED_TOKEN` (int)
  Erro de sintaxe no modelo de formatação.
`U_UNMATCHED_BRACES` (int)
  Colchetes não têm correspondência no modelo da mensagem.
`U_UNQUOTED_SPECIAL` (int)
  Um caractere especial não foi envolvido em aspas ou escapado.
`U_UNSUPPORTED_ATTRIBUTE` (int)
  Não utilizado a partir da ICU 2.4.
`U_UNSUPPORTED_ERROR` (int)
  Operação solicitada não suportada no contexto atual.
`U_UNSUPPORTED_ESCAPE_SEQUENCE` (int)
  Sequência de escape ISO-2022 não suportada.
`U_UNSUPPORTED_PROPERTY` (int)
  Não utilizada a partir da ICU 2.4.
`U_UNTERMINATED_QUOTE` (int)
  Uma apóstrofo (aspas simples) de fechamento está faltando.
`U_USELESS_COLLATOR_ERROR` (int)
  Colador é apenas de opções e nenhuma base foi especificada.
`U_USING_DEFAULT_WARNING` (int)
  Uma pesquisa no pacote de recursos retornou um resultado da localidade raiz (não é um erro).
`U_USING_FALLBACK_WARNING` (int)
  Uma pesquisa no pacote de recursos retornou um resultado reserva (not an error).
`U_VARIABLE_RANGE_EXHAUSTED` (int)
  Muitos substitutos gerados para o intervalo de variáveis selecionado.
`U_VARIABLE_RANGE_OVERLAP` (int)
  O intervalo de variáveis sobrepõe os caracteres usados nas regras.
`U_ZERO_ERROR` (int)
  Nenhum erro, nenhum alerta.

# Exemplos

## Índice

- Uso básico desta extensão

## Uso básico desta extensão

Cada módulo fornece dois tipos de API: um procedural e um orientado a objeto. Ambos são na realidade idênticos e descritos no documento correspondente.

> Nota:

> Todos as strings de entrada devem estar na codificação UTF-8. Todas as strings de saída também estarão em UTF-8.

Exemplo #1 Exemplo de uso da API procedural

    <?php
    $coll  = collator_create('pt_BR');
    $result = collator_compare($coll, "string#1", "string#2");
    ?>

Exemplo #2 Exemplo de uso da API procedural orientada a objeto

    <?php
    $coll = new Collator('pt_BR');
    $al   = $coll->getLocale(Locale::ACTUAL_LOCALE);
    echo "Localidade atual: $al\n";

    $formatter = new NumberFormatter('pt_BR', NumberFormatter::DECIMAL);
    echo $formatter->format(1234567);
    ?>

# A classe Collator

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Introdução

Fornece capacidade de comparação de strings com suporte ao ordenamento apropriado de acordo com a localidade.

## Resumo da classe

class Collator {
/* Constantes */
public const int DEFAULT_VALUE;
public const int PRIMARY;
public const int SECONDARY;
public const int TERTIARY;
public const int DEFAULT_STRENGTH;
public const int QUATERNARY;
public const int IDENTICAL;
public const int OFF;
public const int ON;
public const int SHIFTED;
public const int NON_IGNORABLE;
public const int LOWER_FIRST;
public const int UPPER_FIRST;
public const int FRENCH_COLLATION;
public const int ALTERNATE_HANDLING;
public const int CASE_FIRST;
public const int CASE_LEVEL;
public const int NORMALIZATION_MODE;
public const int STRENGTH;
public const int HIRAGANA_QUATERNARY_MODE;
public const int NUMERIC_COLLATION;
public const int SORT_REGULAR;
public const int SORT_STRING;
public const int SORT_NUMERIC;
/* Métodos */
public function __construct(string `$locale`)
public function asort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool
public function compare(string `$string1`, string `$string2`): int|false
public static function create(string `$locale`): ?Collator
public function getAttribute(int `$attribute`): int|false
public function getErrorCode(): int|false
public function getErrorMessage(): string|false
public function getLocale(int `$type`): string|false
public function getSortKey(string `$string`): string|false
public function getStrength(): int
public function setAttribute(int `$attribute`, int `$value`): bool
public function setStrength(int `$strength`): true
public function sort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool
public function sortWithSortKeys(array `&$array`): bool
}

## Constantes predefinidas

`Collator::FRENCH_COLLATION` int

  Ordena strings com diferentes acentuações a partir do final da string. Este atributo é automaticamente definido para ON (ligado) para as localidades francesas e algumas outras. Usuários normalmente não precisam definir explicitamente este atributo. Há um custo de desempenho de comparação de strings quando definida para ON, mas o comprimento da chave de ordenação não é afetado. Os valores possíveis são:

  - `Collator::ON`
  - `Collator::OFF`(padrão)
  - `Collator::DEFAULT_VALUE`

  Exemplo #1 Regras da FRENCH_COLLATION

  - F=OFF cote < coté < côte < côté
  - F=ON cote < côte < coté < côté
`Collator::ALTERNATE_HANDLING`

  O atributo alternativo é usado para controlar o gerenciamento dos chamados caracteres variáveis na UCA: espaços em branco, pontuações e símbolos. Se ALTERNATE_HANDLING (A) for definido para NON_IGNORABLE (N), as diferenças entre estes caracteres são da mesma importância que as diferenças entre letras. Se ALTERNATE_HANDLING for definida para SHIFTED (S), estes caracteres são somente de importância menor. O valor SHIFTED é frequentemente usado em combinação com STRENGTH definida para set to QUATERNARY. Neste caso, espaços em branco, pontuações e símbolos são considerados ao comparar strings, mas somente se todos os outros aspectos das strings (letras base, acentos e forma) forem idênticos. Se ALTERNATE_HANDLING não for definida para SHIFTED, não haverá diferença entre uma STRENGTH de 3 e uma STRENGTH de 4. Para mais informações e exemplos, consulte "Variable_Weighting" na » UCA. A razão pela qual os valores para ALTERNATE_HANDLING não são simplesmente ON (ligado) e OFF (desligado) é que valores adicionais podem ser necessários no futuro. A opção BLANKED da UCA é expressa com STRENGTH de 3, e ALTERNATE_HANDLING definida para SHIFTED. O padrão para a maioria das localidades é NON_IGNORABLE. Se SHIFTED for selecionado, pode ser mais lento se houver muitas strings que são as mesmas exceto pela pontuação; o comprimento da chave de ordenação não será afetado a menos que o nível de STRENGHT seja também aumentado.

  Os valores possíveis são:

  - `Collator::NON_IGNORABLE`(padrão)
  - `Collator::SHIFTED`
  - `Collator::DEFAULT_VALUE`

  Exemplo #2 Regras de ALTERNATE_HANDLING

  - S=3, A=N di Silva < Di Silva < diSilva < U.S.A. < USA
  - S=3, A=S di Silva = diSilva < Di Silva < U.S.A. = USA
  - S=4, A=S di Silva < diSilva < Di Silva < U.S.A. < USA
`Collator::CASE_FIRST` int

  O atributo CASE_FIRST é usado para controlar se letras maiúsculas vêm antes de letras minúsculas ou vice-versa, na ausência de outras diferenças nas strings. Os valores possíveis são UPPER_FIRST (maiúsculas primeiro - U) e LOWER_FIRST (minúsculas primeiro - L), mais o DEFAULT (padrão) e OFF (desligado - X). Quase não há diferença entre as opções OFF e LOWER_FIRST em termos de resultados, portanto tipicamente os usuários não usarão LOWER_FIRST: apenas OFF ou UPPER_FIRST. (Os interessados nas diferenças detalhadas entre X e L devem consultar a `Collation Customization` - Customização de Agrupamento). Especificar L ou U não afetará o desempenho de comparação de strings, mas afetará o comprimento da chave de ordenação.

  Os valores possíveis são:

  - `Collator::OFF`(padrão)
  - `Collator::LOWER_FIRST`
  - `Collator::UPPER_FIRST`
  - `Collator:DEFAULT`

  Exemplo #3 Regras de CASE_FIRST

  - C=X ou C=L "china" < "China" < "denmark" < "Denmark"
  - C=U "China" < "china" < "Denmark" < "denmark"
`Collator::CASE_LEVEL` int

  O atributo CASE_LEVEL é usado quando os acentos são ignorados mas as maiúsculas/minúsculas não são. Nesta situação, deve-se definir STRENGTH para PRIMARY, e CASE_LEVEL para ON. Na maioria das localidades, esta configuração é OFF por padrão. Existe um pequeno impacto no desempenho de comparação de strings e na chave de ordenação se este atributo for definido para ON.

  Os valores possíveis são:

  - `Collator::OFF`(padrão)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`

  Exemplo #4 Regras de CASE_LEVEL

  - S=1, E=X role = Role = rôle
  - S=1, E=O role = rôle < Role
`Collator::NORMALIZATION_MODE` int

  A configuração NORMALIZATION_MODE determina se o texto está completamente normalizado ou não na comparação. Mesmo se a configuração esteja em OFF (que é o padrão para muitas localidades), texto como representado em uso comum irá comparar corretamente (para detalhes, consulte UTN #5). Somente se as marcas de acentos estiverem em ordem não canônica haverá problema. Se a configuração estiver em ON, os melhores resultados são garantidos para todas as entradas de texto possíveis. Existe um custo médio de desempenho na comparação de strings se este atributo estiver em ON, dependendo da frequência de sequências que requerem normalização. Não há efeito significativo no comprimento da chave de ordenação. Se for sabido que o texto de entrada está nas formas de normalização NFD ou NFKD, não há necessidade de habilitar esta opção de normalização.

  Os valores possíveis são:

  - `Collator::OFF`(padrão)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::STRENGTH` int

  O Serviço de Agrupamento ICU suporta vários níveis de comparação, chamados também de "Strengths" (forças). Ter estas categorias possibilita à ICU ordenar as strings de forma precisa conforme as convenções locais. Entretanto, ao permitir que os níveis sejam seletivamente empregados, a pesquisa por uma string no texto pode ser realizada com várias condições de correspondência. Para informações mais detalhadas, consulte o capítulo collator_set_strength().

  Os valores possíveis são:

  - `Collator::PRIMARY`
  - `Collator::SECONDARY`
  - `Collator::TERTIARY`(padrão)
  - `Collator::QUATERNARY`
  - `Collator::IDENTICAL`
  - `Collator::DEFAULT_VALUE`
`Collator::HIRAGANA_QUATERNARY_MODE` int

  Compatibilidade com JIS x 4061 requer a introdução de um nível adicional para distinguir caracteres Hiragana e Katakana. Se for requerida compatibilidade com o esse padrão, este atributo deve ser definido para ON, e a STRENGTH deve ser definida para QUATERNARY. Isto afetará o comprimento da chave de ordenação e desempenho de comparação de strings.

  Os valores possíveis são:

  - `Collator::OFF`(padrão)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::NUMERIC_COLLATION` int

  Quando definido para ON, este atributo gera uma chave de agrupamento para o valor numérico de substrings de dígitos. Esta é uma maneira de obter '100' ordenado DEPOIS de '2'.

  Os valores possíveis são:

  - `Collator::OFF`(padrão)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::DEFAULT_VALUE` int
`Collator::PRIMARY` int
`Collator::SECONDARY` int
`Collator::TERTIARY` int
`Collator::DEFAULT_STRENGTH` int
`Collator::QUATERNARY` int
`Collator::IDENTICAL` int
`Collator::OFF` int
`Collator::ON` int
`Collator::SHIFTED` int
`Collator::NON_IGNORABLE` int
`Collator::LOWER_FIRST` int
`Collator::UPPER_FIRST` int
`Collator::SORT_REGULAR` int

`Collator::SORT_STRING` int

`Collator::SORT_NUMERIC` int

## Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | As constantes de classe agora são tipadas.

# Collator::asort

# collator_asort

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::asort -- collator_asort — Ordena array mantendo associação de índice

### Descrição

Estilo orientado a objetos

public function Collator::asort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool

Estilo procedural

function collator_asort(Collator `$object`, array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool

Esta função ordena um array de forma que seus índices mantenham as correlações com os elementos aos quais estão associados. Isto é usado principalmente ao ordenar arrays associativos onde a ordem real dos elementos é significativa. Elementos dos arrays terão a ordenação conforme as regras atuais da localidade.

Equivalente à função padrão do PHP asort().

### Parâmetros

`object`

  Objeto Collator.

`array`

  Array de strings a ordenar.

`flags`

  Tipo de ordenação opcional, um dos seguintes:

  - `Collator::SORT_REGULAR` - compara os itens normalmente (não altera os tipos)

  - `Collator::SORT_NUMERIC` - compara os itens numericamente

  - `Collator::SORT_STRING` - compara os itens como strings

  O valor padrão de `flags` é `Collator::SORT_REGULAR`. Também é usado se um valor inválido de `flags` tiver sido especificado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de collator_asort()

    <?php
    $coll = collator_create( 'en_US' );
    $arr = array(
         'a' => '100',
         'b' => '50',
         'c' => '7'
    );
    collator_asort( $coll, $arr, Collator::SORT_NUMERIC );
    var_export( $arr );

    collator_asort( $coll, $arr, Collator::SORT_STRING );
    var_export( $arr );
    ?>

O exemplo acima produzirá:

    array (
      'c' => '7',
      'b' => '50',
      'a' => '100',
    )array (
      'a' => '100',
      'b' => '50',
      'c' => '7',
    )

### Veja Também

- Constantes de Collator
- collator_sort() - Ordena um array usando o agrupador especificado
- collator_sort_with_sort_keys() - Ordena um array usando agrupador e chaves de ordenação especificados

# Collator::compare

# collator_compare

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::compare -- collator_compare — Compara duas strings Unicode

### Descrição

Estilo orientado a objetos

public function Collator::compare(string `$string1`, string `$string2`): int|false

Estilo procedural

function collator_compare(Collator `$object`, string `$string1`, string `$string2`): int|false

Compara duas strings Unicode de acordo com as regras de agrupamento.

### Parâmetros

`object`

  Objeto Collator.

`string1`

  A primeira string a comparar.

`string2`

  A segunda string a comparar.

### Valor Retornado

Retorna o resultado da comparação:

- 1 se `string1` for maior que `string2`;

- 0 se `string1` for igual a `string2`;

- -1 se `string1` for menor que `string2`.

Retorna `false` em caso de falha.
Aviso

Esta função pode retornar o valor booleano `false`, mas também pode retornar um valor não booleano que pode ser avaliado como `false`. Leia a seção sobre Booleanos para mais informações. Use o operador === para testar o valor retornado por esta função.

### Exemplos

Exemplo #1 Exemplo de collator_compare()

    <?php
    $s1 = 'Hello';
    $s2 = 'hello';

    $coll = collator_create( 'en_US' );
    $res  = collator_compare( $coll, $s1, $s2 );

    if ($res === false) {
        echo collator_get_error_message( $coll );
    } else if( $res > 0 ) {
        echo "s1 é maior que s2\n";
    } else if( $res < 0 ) {
        echo "s1 é menor que s2\n";
    } else {
        echo "s1 é igual a s2\n";
    }
    ?>

O exemplo acima produzirá:

s1 é maior que s2

Exemplo #2 Comparando strings sem diacríticos ou diferenciação entre maiúsculas/minúsculas

    <?php
    $c = new Collator( 'en' );
    $c->setStrength( Collator::PRIMARY );

    if ( $c->compare( 'Séan', 'Sean' ) == 0 )
    {
        echo "Iguais\n";
    }

O exemplo acima produzirá:

Iguais

Este exemplo instrui o agrupador a comparar levando em conta apenas os caracteres base. A documentação da função Collator->setStrength() explica as diferentes forças ("strengths").

### Veja Também

- collator_sort() - Ordena um array usando o agrupador especificado

# Collator::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::__construct — Cria um agrupador (Collator)

### Descrição

public function Collator::__construct(string `$locale`)

Cria uma nova instância de Collator.

### Parâmetros

`locale`

  A localidade cujas regras de agrupamento devem ser usadas. Valores especiais para localidades podem ser passadas - se uma string vazia for passada, as regras de agrupamento da localidade padrão serão usadas. Se `"root"` for passado, as regras » UCA serão usadas.

  O atributo `locale` é tipicamente o mais importante para ordenação e correspondências corretas, conforme expectativas do usuário em diferentes países e regiões. A ordenação » UCA padrão ordenará somente poucas línguas como holandês e português corretamente ("corretamente" significa de acordo com a expectativa normal para os usuários da língua). Em outras situações, é necessário fornecer a localidade para a UCA para agrupar adequadamente o texto para uma língua específica. Portanto, uma localidade precisa ser informada para que seja escolhido um agrupador que tenha sido corretamente elaborado para aquela localidade. A escolha de uma localidade irá predefinir automaticamente os valores de todos os atributos para algo que seja razoável para a localidade. Por isso, na maior parte do tempo os outros atributos não precisam ser definidos explicitamente. Em alguns casos, a escolha de localidade fará diferença em desempenho de comparação de strings e/ou em comprimento de chave de ordenação.

### Erros/Exceções

Retorna um objeto "vazio" em caso de erro. User as funções intl_get_error_code() e/ou intl_get_error_message() para descobrir o que ocorreu.

### Exemplos

Exemplo #1 Exemplo de Collator::__construct()

    <?php
    $coll = new Collator('en_CA');
    ?>

### Veja Também

- Collator::create() - Cria um agrupador
- collator_create() - Cria um agrupador

# Collator::create

# collator_create

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::create -- collator_create — Cria um agrupador

### Descrição

Estilo orientado a objetos

public static function Collator::create(string `$locale`): ?Collator

Estilo procedural

function collator_create(string `$locale`): ?Collator

As strings serão comparadas usando as opções já especificadas.

### Parâmetros

`locale`

  A localidade contendo as regras de agrupamento requeridas. Valores especiais para localidades podem ser passadas - se uma string vazia for passada, as regras de agrupamento da localidade padrão serão usadas. Se `"root"` for passado, as regras » UCA serão usadas.

### Valor Retornado

Retorna uma nova instância de Collator, ou `null` em caso de erro.

### Exemplos

Exemplo #1 Exemplo de collator_create()

    <?php
    $coll = collator_create( 'en_US' );

    if( !isset( $coll ) ) {
        printf( "Criação do agrupador falhou: %s\n", intl_get_error_message() );
        exit( 1 );
    }
    ?>

### Veja Também

- Collator::__construct() - Cria um agrupador (Collator)

# Collator::getAttribute

# collator_get_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getAttribute -- collator_get_attribute — Obtém o valor de atributo de um agrupador

### Descrição

Estilo orientado a objetos

public function Collator::getAttribute(int `$attribute`): int|false

Estilo procedural

function collator_get_attribute(Collator `$object`, int `$attribute`): int|false

Obtém um valor de um atributo inteiro de um agrupador.

### Parâmetros

`object`

  Objeto Collator.

`attribute`

  Atributo do qual o valor será obtido.

### Valor Retornado

Valor do atributo, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de collator_get_attribute()

    <?php
    $coll = collator_create( 'en_CA' );
    $val = collator_get_attribute( $coll, Collator::NUMERIC_COLLATION );
    if( $val === false )
    {
        // Gerencia o erro.
    }
    ?>

### Veja Também

- Constantes de Collator
- collator_set_attribute() - Define atributo do agrupador
- collator_get_strength() - Obtém a força atual de agrupamento

# Collator::getErrorCode

# collator_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getErrorCode -- collator_get_error_code — Obtém o último código de erro do agrupador

### Descrição

Estilo orientado a objetos

public function Collator::getErrorCode(): int|false

Estilo procedural

function collator_get_error_code(Collator `$object`): int|false

Obtém o último código de erro do agrupador.

### Parâmetros

`object`

  Objeto Collator.

### Valor Retornado

Código de erro retornado pela última chamada a uma função da API Collator, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de collator_get_error_code()

    <?php
    $coll = collator_create( 'en_US' );
    if( collator_get_attribute( $coll, Collator::FRENCH_COLLATION ) === false )
            handle_error( collator_get_error_code() );
    ?>

### Veja Também

- collator_get_error_message() - Obtém o texto para o último código de erro do agrupador

# Collator::getErrorMessage

# collator_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getErrorMessage -- collator_get_error_message — Obtém o texto para o último código de erro do agrupador

### Descrição

Estilo orientado a objetos

public function Collator::getErrorMessage(): string|false

Estilo procedural

function collator_get_error_message(Collator `$object`): string|false

Obtém a mensagem para o último erro.

### Parâmetros

`object`

  Objeto Collator.

### Valor Retornado

Descrição de um erro que ocorreu na última chamada de uma função da API Collator, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de collator_get_error_message()

    <?php
    $coll = collator_create( 'lt' );
    if( collator_compare( $coll, 'y', 'k' ) === false ) {
        echo collator_get_error_message( $coll );
    }
    ?>

### Veja Também

- collator_get_error_code() - Obtém o último código de erro do agrupador

# Collator::getLocale

# collator_get_locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getLocale -- collator_get_locale — Obtém o nome da localidade do agrupador

### Descrição

Estilo orientado a objetos

public function Collator::getLocale(int `$type`): string|false

Estilo procedural

function collator_get_locale(Collator `$object`, int `$type`): string|false

Obtém o nome da localidade do agrupador.

### Parâmetros

`object`

  Objeto Collator.

`type`

  Pode-se escolher entre localidae válida ou real ( `Locale::VALID_LOCALE` e `Locale::ACTUAL_LOCALE`, respectivamente).

### Valor Retornado

Nome real de localidade de onde se originam os dados do agrupador. Se o agrupador tiver sido instanciado a partir de regras ou se um erro tiver ocorrido, retornará `false`.

### Exemplos

Exemplo #1 Exemplo de collator_get_locale()

    <?php
    $coll    = collator_create( 'en_US_California' );
    $res_val = collator_get_locale( $coll, Locale::VALID_LOCALE );
    $res_act = collator_get_locale( $coll, Locale::ACTUAL_LOCALE );
    printf( "Nome de localidade válido: %s\nNome de localidade real: %s\n",
             $res_val, $res_act );
    ?>

O exemplo acima produzirá:

    Nome de localidade válido: en_US
    Nome de localidade real: root

### Veja Também

- collator_create() - Cria um agrupador

# Collator::getSortKey

# collator_get_sort_key

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 1.0.3)

Collator::getSortKey -- collator_get_sort_key — Obtém a chave de ordenação de uma string

### Descrição

Estilo orientado a objetos

public function Collator::getSortKey(string `$string`): string|false

Estilo procedural

function collator_get_sort_key(Collator `$object`, string `$string`): string|false

Retorna a chave de agrupamento de uma string. Chaves de agrupamento podem ser comparadas diretamente ao invés de se comparar strings, mas são específicas de implementação e podem mudar entre versões de biblioteca ICU. Chaver de ordenação geralmente são úteis apenas em bancos de dados ou em outras circunstâncias onde chamadas a funções são extremamente custosas.

### Parâmetros

`object`

  Objeto de Collator.

`string`

  A string a partir da qual a chave será produzida.

### Valor Retornado

Retorna a chave de agrupamento para a string, ou `false` em caso de falha.

Aviso

Esta função pode retornar o valor booleano `false`, mas também pode retornar um valor não booleano que pode ser avaliado como `false`. Leia a seção sobre Booleanos para mais informações. Use o operador === para testar o valor retornado por esta função.

### Exemplos

Exemplo #1 Exemplo de collator_get_sort_key()

    <?php

    $s1 = 'Hello';

    $coll = collator_create('en_US');
    $res  = collator_get_sort_key($coll, $s1);

    echo bin2hex($res);
    ?>

O exemplo acima produzirá algo semelhante a:

3832404046010901dc08

Exemplo #2 Exemplo de Collator::getSortKey() com usort()

    <?php

    $data = [
        [ 'name' => '🇳🇱 Derick Rethans', 'linked_account' => 'https://phpc.social/users/derickr' ],
        [ 'name' => 'Elephpant', 'linked_account' => 'https://phpc.social/phpc' ],
        [ 'name' => '🇫🇷 Marcus Bointon', 'linked_account' => 'https://phpc.social/users/Synchro' ],
    ];

    /* Cria o ordenador */
    $col = new Collator('en');

    /* Ordena letras maiúsculas antes de minúsculas */
    $col->setAttribute(Collator::CASE_FIRST, Collator::UPPER_FIRST);

    /* Usa uma função definida pelo usuário com ordenação que remove os emojis */
    usort(
        $data,
        function($a, $b) use ($col) {
            /* Remove a classe de caracteres 'S' (os símbolos) e espaços em branco
             * (com trim) */
            $aName = trim(preg_replace('/\p{S}+/u', '', $a['name']));
            $bName = trim(preg_replace('/\p{S}+/u', '', $b['name']));

            /* Cria a chave de ordenação */
            $aKey = $col->getSortKey($aName);
            $bKey = $col->getSortKey($bName);

            /* Usa a chave de ordenação para sinalizar que elementos são ordenados primeiro */
            return $aKey <=> $bKey;
        }
    );

    var_dump($data);
    ?>

O exemplo acima produzirá algo semelhante a:

array(3) {
[0] =>
array(2) {
'name' =>
string(25) "🇳🇱 Derick Rethans"
'linked_account' =>
string(33) "https://phpc.social/users/derickr"
}
[1] =>
array(2) {
'name' =>
string(9) "Elephpant"
'linked_account' =>
string(24) "https://phpc.social/phpc"
}
[2] =>
array(2) {
'name' =>
string(25) "🇫🇷 Marcus Bointon"
'linked_account' =>
string(33) "https://phpc.social/users/Synchro"
}
}

### Veja Também

- collator_sort() - Ordena um array usando o agrupador especificado
- collator_sort_with_sort_keys() - Ordena um array usando agrupador e chaves de ordenação especificados

# Collator::getStrength

# collator_get_strength

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getStrength -- collator_get_strength — Obtém a força atual de agrupamento

### Descrição

Estilo orientado a objetos

public function Collator::getStrength(): int

Estilo procedural

function collator_get_strength(Collator `$object`): int

### Parâmetros

`object`

  Objeto Collator.

### Valor Retornado

Retorna a força atual de agrupamento, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de collator_get_strength()

    <?php
    $coll     = collator_create( 'en_US' );
    $strength = collator_get_strength( $coll );
    ?>

### Veja Também

- Constantes de Collator
- collator_set_strength() - Define a força do agrupador
- collator_get_attribute() - Obtém o valor de atributo de um agrupador

# Collator::setAttribute

# collator_set_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::setAttribute -- collator_set_attribute — Define atributo do agrupador

### Descrição

Estilo orientado a objetos

public function Collator::setAttribute(int `$attribute`, int `$value`): bool

Estilo procedural

function collator_set_attribute(Collator `$object`, int `$attribute`, int `$value`): bool

Define atributo do agrupador.

### Parâmetros

`object`

  Objeto Collator.

`attribute`

  Atributo.

`value`

  Valor do atributo.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de collator_set_attribute()

    <?php
    $coll = collator_create('en_CA');
    collator_set_attribute($coll, Collator::NORMALIZATION_MODE, Collator::ON);
    ?>

### Veja Também

- Constantes de Collator
- collator_get_attribute() - Obtém o valor de atributo de um agrupador
- collator_set_strength() - Define a força do agrupador

# Collator::setStrength

# collator_set_strength

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::setStrength -- collator_set_strength — Define a força do agrupador

### Descrição

Estilo orientado a objetos

public function Collator::setStrength(int `$strength`): true

Estilo procedural

function collator_set_strength(Collator `$object`, int `$strength`): true

O Serviço de Agrupamento » ICU suporta vários níveis de comparação, também chamados de "forças" ("strengths"). Estas categorias permitem à ICU ordenar strings com precisão conforme convenções locais. Entretanto, ao permitir que os níveis sejam seletivamente empregados, a pesquisa por uma string em um texto pode ser realizada com várias condições de correspondência.

1. Nível primário: Tipicamento usado para indicar diferenças entre caracteres base (por exemplo "a" < "b"). É a diferença mais forte. Por exemplo, dicionários são divididos em seções por caractere base. É também chamado de força nível 1 (`level 1`).

2. Nível secundário: Acentuações nos caracteres são consideradas diferenças secundárias (por exemplo, "as" < "às" < "at"). Outras diferenças entre letras podem também ser consideradas secundárias, dependendo da língua. Uma diferença secundária é ignorada quando existir uma diferença primária em qualquer lugar nas strings. Também chamado de força nível 2 (`level 2`).

   > Nota:

   > Nota: Em algumas línguas (como o dinamarquês), certas letras acentuadas são consideradas como caracteres base separados. Na maioria da línguas, entretanto, uma letra com acentuação tem apenas diferença secundária em relação à versão não acentuada dessa letra.

3. Nível terciário: Diferenças de maiúsculas e minúsculas são distinguidas no nível terciário (por exemplo, "ao" < "Ao" < "aò"). Além disso, uma variante de uma letra se diferencia da forma base no nível terciário (como "a" e "𝒶"). Outro exemplo é a diferença entre o Kana grande e o pequeno. Uma diferença terciária é ignorada quando existir uma diferença primária ou secundária em qualquer lugar nas strings. Também chamado de força nível 3 (`level 3`).

4. Nível quaternário: Quando a pontuação é ignorada (consulte Ignorando Pontuaçõs) em níveis 1-3, um nível adicional pode ser usado para distinguir palavras com e sem pontuação (por exemplo, "ab" < "a-b" < "aB"). Esta diferença é ignorada quando há uma diferença primária, secundária ou terciária. Também conhecida como força nível 4 (`level 4`). O nível quaternário deve ser usado apenas se for requerido ignorar a pontuação ou ao processar texto em japonês (consulte processamento de Hiragana).

5. Nível idêntico: Quando todos os outros níveis são iguais, o nível idêntico é usado como um desempate. Os valores de ponto de código Unicode para a forma NFD de cada string são comparados neste nível, apenas caso não haja nenhuma diferença nos níveis 1 a 4. Por exemplo, os sinais hebraicos de cantilação somente são distinguidos neste nível. Este nível deve ser usado com moderação, já que diferenças somente de valores de ponto de código entre duas strings é uma ocorrência extremamente rara. Usar este nível diminui consideravelmente o desempenho tanto para comparação incremental quanto para geração de chave de ordenação (e também aumenta o comprimento da chave). Também conhecido como força nível 5 (`level 5`).

Por exemplo, pode-se decidir por ignorar acentuação ou ignorar tanto acentuação quanto maiúsculas e minúsculas ao pesquisar por texto. Quase todos os caracteres são diferenciáveis pelos primeiros três níveis e por isso, na maior parte das localidades, o valor padrão é o terciário. Entratanto, se a opção ALTERNATE for definida para SHIFTED, a força quaternária pode ser usada para desempatar entre espaços em branco, pontuação e símbolos que em outros casos seriam ignorados. Se uma distinção muito fina entre caracteres for necessária, o nível idêntico pode ser usado (por exemplo, o nível idêntico distingue entre a letra "a" minúscula matemática em negrito e a letra "a" minúscula matemática em itálico). Entretanto, usar níveis mais altos que o terciário resulta em chaves de ordenação significativamente mais longas, e desempenho mais lento de comparação para strings iguais.

### Parâmetros

`object`

  Objeto Collator.

`strength`

  Força a ser definida.

  Valores possíveis são:

  - `Collator::PRIMARY`

  - `Collator::SECONDARY`

  - `Collator::TERTIARY`

  - `Collator::QUATERNARY`

  - `Collator::IDENTICAL`

  - `Collator::DEFAULT_STRENGTH`

### Valor Retornado

Sempre retorna `true`.

### Exemplos

Exemplo #1 Exemplo de collator_set_strength()

    <?php
    $arr  = array( 'aò', 'Ao', 'ao' );
    $coll = collator_create( 'en_US' );

    // Ordena o array usando a força padrão.
    collator_sort( $coll, $arr );
    var_export( $arr );

    // Ordena o array usando a força primária.
    collator_set_strength( $coll, Collator::PRIMARY );
    collator_sort( $coll, $arr );
    var_export( $arr );
    ?>

O exemplo acima produzirá:

    array (
      0 => 'ao',
      1 => 'Ao',
      2 => 'aò',
    )
    array (
      0 => 'aò',
      1 => 'Ao',
      2 => 'ao',
    )

### Veja Também

- Constantes de Collator
- collator_get_strength() - Obtém a força atual de agrupamento

# Collator::sort

# collator_sort

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::sort -- collator_sort — Ordena um array usando o agrupador especificado

### Descrição

Estilo orientado a objetos

public function Collator::sort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool

Estilo procedural

function collator_sort(Collator `$object`, array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool

Esta função ordena um array conforme as regras da localidade atual.

Equivalente à função padrão do PHP sort() .

### Parâmetros

`object`

  Objeto Collator.

`array`

  Array de strings a ordenar.

`flags`

  Tipo de ordenação opcional, um dos seguintes:

  - `Collator::SORT_REGULAR` - compara os itens normalmente (não altera os tipos)

  - `Collator::SORT_NUMERIC` - compara os itens numericamente

  - `Collator::SORT_STRING` - compara os itens como strings

  O tipo de ordenação padrão é `Collator::SORT_REGULAR`. Também é usado se um valor inválido de `flags` tiver sido especificado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de collator_sort()

    <?php
    $coll = collator_create( 'en_US' );
    $arr  = array( 'at', 'às', 'as' );

    var_export( $arr );
    collator_sort( $coll, $arr );
    var_export( $arr );
    ?>

O exemplo acima produzirá:

    array (
      0 => 'at',
      1 => 'às',
      2 => 'as',
    )array (
      0 => 'as',
      1 => 'às',
      2 => 'at',
    )

### Veja Também

- Constantes de Collator
- collator_asort() - Ordena array mantendo associação de índice
- collator_sort_with_sort_keys() - Ordena um array usando agrupador e chaves de ordenação especificados

# Collator::sortWithSortKeys

# collator_sort_with_sort_keys

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::sortWithSortKeys -- collator_sort_with_sort_keys — Ordena um array usando agrupador e chaves de ordenação especificados

### Descrição

Estilo orientado a objetos

public function Collator::sortWithSortKeys(array `&$array`): bool

Estilo procedural

function collator_sort_with_sort_keys(Collator `$object`, array `&$array`): bool

Similar à função collator_sort() mas usa chaves de ordenação ICU produzidas por ucol_getSortKey() para ganhar mais velocidade em arrays grandes.

### Parâmetros

`object`

  Objeto Collator.

`array`

  Array de strings a ordenar

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de collator_sort_with_sort_keys()

    <?php
    $arr  = array( 'Köpfe', 'Kypper', 'Kopfe' );
    $coll = collator_create( 'sv' );

    collator_sort_with_sort_keys( $coll, $arr );
    var_export( $arr );
    ?>

O exemplo acima produzirá:

    array (
      0 => 'Kopfe',
      1 => 'Kypper',
      2 => 'Köpfe',
    )

### Veja Também

- Constantes Collator
- collator_sort() - Ordena um array usando o agrupador especificado
- collator_asort() - Ordena array mantendo associação de índice

## Índice

- Collator::asort — Ordena array mantendo associação de índice
- Collator::compare — Compara duas strings Unicode
- Collator::__construct — Cria um agrupador (Collator)
- Collator::create — Cria um agrupador
- Collator::getAttribute — Obtém o valor de atributo de um agrupador
- Collator::getErrorCode — Obtém o último código de erro do agrupador
- Collator::getErrorMessage — Obtém o texto para o último código de erro do agrupador
- Collator::getLocale — Obtém o nome da localidade do agrupador
- Collator::getSortKey — Obtém a chave de ordenação de uma string
- Collator::getStrength — Obtém a força atual de agrupamento
- Collator::setAttribute — Define atributo do agrupador
- Collator::setStrength — Define a força do agrupador
- Collator::sort — Ordena um array usando o agrupador especificado
- Collator::sortWithSortKeys — Ordena um array usando agrupador e chaves de ordenação especificados

# A classe NumberFormatter

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Introdução

Programas armazenam e operam números usando uma representação binária que não depende da localidade. Ao apresentar ou imprimir um número, ele é convertido para uma string específica para a localidade. Por exemplo, o número 12345.67 é "12,345.67" nos Estados Unidos, "12 345,67" na França e "12.345,67" na Alemanha e no Brasil.

Ao invocar os métodos fornecidos pela classe NumberFormatter, pode-se formatar números, moedas, e percentagens de acordo com o especificado ou com a localidade padrão. NumberFormatter é sensível à localidade, portanto é necessário criar um novo objeto NumberFormatter para cada localidade. Métodos NumberFormatter formatam números com tipos primitivos, como 'double' e mostram o número como uma string específica para a localidade

Para moedas, pode-se usar o tipo de formato de moeda para criar um formatador que retorne uma string com o número formatado e com o sinal apropriado para a moeda. Obviamente, a classe NumberFormatter não tem ciência de taxas de câmbio, portanto, a saída é a mesma independente da moeda especificada. Isto significa que o mesmo número tem diferentes valores monteários dependendo da moeda da localidade. Se o número for 9988776.65, os resultados serão:

- 9 988 776,65 € na França
- 9.988.776,65 € na Alemanha
- $9,988,776.65 nos Estados Unidos

Para formatar percentagens, deve-se criar um formatador específico da localidade com o tipo de formato de percentual. Com este formatados, uma fração decimal como 0.75 é mostrada como 75%.

Para formatações mais complexas, como números por extenso, os formatadores de número baseados em regras são utilizados.

## Resumo da classe

class NumberFormatter {
/* Constantes */
public const int PATTERN_DECIMAL;
public const int DECIMAL;
public const int DECIMAL_COMPACT_SHORT;
public const int DECIMAL_COMPACT_LONG;
public const int CURRENCY;
public const int PERCENT;
public const int SCIENTIFIC;
public const int SPELLOUT;
public const int ORDINAL;
public const int DURATION;
public const int PATTERN_RULEBASED;
public const int IGNORE;
public const int CURRENCY_ISO;
public const int CURRENCY_PLURAL;
public const int CURRENCY_ACCOUNTING;
public const int CASH_CURRENCY;
public const int CURRENCY_STANDARD;
public const int DEFAULT_STYLE;
public const int ROUND_CEILING;
public const int ROUND_FLOOR;
public const int ROUND_DOWN;
public const int ROUND_UP;
public const int ROUND_TOWARD_ZERO;
public const int ROUND_AWAY_FROM_ZERO;
public const int ROUND_HALFEVEN;
public const int ROUND_HALFODD;
public const int ROUND_HALFDOWN;
public const int ROUND_HALFUP;
public const int PAD_BEFORE_PREFIX;
public const int PAD_AFTER_PREFIX;
public const int PAD_BEFORE_SUFFIX;
public const int PAD_AFTER_SUFFIX;
public const int PARSE_INT_ONLY;
public const int GROUPING_USED;
public const int DECIMAL_ALWAYS_SHOWN;
public const int MAX_INTEGER_DIGITS;
public const int MIN_INTEGER_DIGITS;
public const int INTEGER_DIGITS;
public const int MAX_FRACTION_DIGITS;
public const int MIN_FRACTION_DIGITS;
public const int FRACTION_DIGITS;
public const int MULTIPLIER;
public const int GROUPING_SIZE;
public const int ROUNDING_MODE;
public const int ROUNDING_INCREMENT;
public const int FORMAT_WIDTH;
public const int PADDING_POSITION;
public const int SECONDARY_GROUPING_SIZE;
public const int SIGNIFICANT_DIGITS_USED;
public const int MIN_SIGNIFICANT_DIGITS;
public const int MAX_SIGNIFICANT_DIGITS;
public const int LENIENT_PARSE;
public const int POSITIVE_PREFIX;
public const int POSITIVE_SUFFIX;
public const int NEGATIVE_PREFIX;
public const int NEGATIVE_SUFFIX;
public const int PADDING_CHARACTER;
public const int CURRENCY_CODE;
public const int DEFAULT_RULESET;
public const int PUBLIC_RULESETS;
public const int DECIMAL_SEPARATOR_SYMBOL;
public const int GROUPING_SEPARATOR_SYMBOL;
public const int PATTERN_SEPARATOR_SYMBOL;
public const int PERCENT_SYMBOL;
public const int ZERO_DIGIT_SYMBOL;
public const int DIGIT_SYMBOL;
public const int MINUS_SIGN_SYMBOL;
public const int PLUS_SIGN_SYMBOL;
public const int CURRENCY_SYMBOL;
public const int INTL_CURRENCY_SYMBOL;
public const int MONETARY_SEPARATOR_SYMBOL;
public const int EXPONENTIAL_SYMBOL;
public const int PERMILL_SYMBOL;
public const int PAD_ESCAPE_SYMBOL;
public const int INFINITY_SYMBOL;
public const int NAN_SYMBOL;
public const int SIGNIFICANT_DIGIT_SYMBOL;
public const int MONETARY_GROUPING_SEPARATOR_SYMBOL;
public const int TYPE_DEFAULT;
public const int TYPE_INT32;
public const int TYPE_INT64;
public const int TYPE_DOUBLE;
public const int TYPE_CURRENCY;
/* Métodos */
public function __construct(string `$locale`, int `$style`, ?string `$pattern` = `null`)
public static function create(string `$locale`, int `$style`, ?string `$pattern` = `null`): ?NumberFormatter
public function format(int|float `$num`, int `$type` = `NumberFormatter::TYPE_DEFAULT`): string|false
public function formatCurrency(float `$amount`, string `$currency`): string|false
public function getAttribute(int `$attribute`): int|float|false
public function getErrorCode(): int
public function getErrorMessage(): string
public function getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false
public function getPattern(): string|false
public function getSymbol(int `$symbol`): string|false
public function getTextAttribute(int `$attribute`): string|false
public function parse(string `$string`, int `$type` = `NumberFormatter::TYPE_DOUBLE`, int `&$offset` = `null`): int|float|false
public function parseCurrency(string `$string`, string `&$currency`, int `&$offset` = `null`): float|false
public function setAttribute(int `$attribute`, int|float `$value`): bool
public function setPattern(string `$pattern`): bool
public function setSymbol(int `$symbol`, string `$value`): bool
public function setTextAttribute(int `$attribute`, string `$value`): bool
}

## Constantes predefinidas

## Tipos de Formato

Estes estilos são usados pela função numfmt_create() para definir o tipo do formatador.

`NumberFormatter::PATTERN_DECIMAL` int
  Formato decimal definido por modelo
`NumberFormatter::DECIMAL` int
  Formato decimal
`NumberFormatter::DECIMAL_COMPACT_SHORT` int
  Formato decimal expresso em notação compacta (forma curta), por exemplo, "23K", "45B". Disponível a partir do PHP 8.5.0 e ICU 56.
`NumberFormatter::DECIMAL_COMPACT_LONG` int
  Formato decimal expresso em notação compacta (forma longa), por exemplo, "23 thousand", "45 billion". Disponível a partir do PHP 8.5.0 e ICU 56.
`NumberFormatter::CURRENCY` int
  Formato de moeda
`NumberFormatter::CURRENCY_ISO` int
  Formato ISO de moeda (ex.: "USD1.00"). Disponível a partir do PHP 8.5.0.
`NumberFormatter::CURRENCY_PLURAL` int
  Formato pluralizado de moeda (ex.: "1.00 US dollar" e "3.00 US dollars"). Disponível a partir do PHP 8.5.0.
`NumberFormatter::CASH_CURRENCY` int
  Símbolo da moeda em uso de DINHEIRO, por exemplo, "NT$3" em vez de "NT$3.23". Disponível a partir do PHP 8.5.0 e ICU 54.
`NumberFormatter::CURRENCY_STANDARD` int
  Símbolo de moeda, por exemplo, "$1.00", usando estilo não contábil para valores negativos (por exemplo, sinal de menos). Disponível a partir do PHP 8.5.0 e ICU 56.
`NumberFormatter::PERCENT` int
  Formato de percentual
`NumberFormatter::SCIENTIFIC` int
  Formato científico
`NumberFormatter::SPELLOUT` int
  Formato baseado em regras ortográficas
`NumberFormatter::ORDINAL` int
  Formato baseado em regras ordinais
`NumberFormatter::DURATION` int
  Formato baseado em regras de duração
`NumberFormatter::PATTERN_RULEBASED` int
  Formato baseado em regras definido por modelo
`NumberFormatter::CURRENCY_ACCOUNTING` int
  Formato de moeda para contabilidade, ex.: `($3.00)` para quantidade negativa de moeda ao invés de `-$3.00`. Disponível a partir do PHP 7.4.1 e ICU 53.
`NumberFormatter::DEFAULT_STYLE` int
  Formato padrão para a localidade
`NumberFormatter::IGNORE` int
  Apelido para PATTERN_DECIMAL

## Especificadores de Formatos de Números

Estas constantes definem como os números são analisados ou formatados. Eles devem ser usados como argumentos para as funções numfmt_format() e numfmt_parse().

`NumberFormatter::TYPE_DEFAULT` int
  Deriva o tipo a partir do tipo da variável
`NumberFormatter::TYPE_INT32` int
  Formata/analisa como um inteiro de 32 bits
`NumberFormatter::TYPE_INT64` int
  Formata/analisa como um inteiro de 64 bits
`NumberFormatter::TYPE_DOUBLE` int
  Formata/analisa como um valor de ponto flutuante
`NumberFormatter::TYPE_CURRENCY` int
  Formata/analisa como um valor de moeda. Descontinuado a partir do PHP 8.3.0

## Atributos de Formatos de Números

Atributo de formato de número usado pelas funções numfmt_get_attribute() e numfmt_set_attribute().

`NumberFormatter::PARSE_INT_ONLY` int
  Analisa inteiros somente.
`NumberFormatter::GROUPING_USED` int
  Usa separador de agrupamento.
`NumberFormatter::DECIMAL_ALWAYS_SHOWN` int
  Sempre mostra o separador de decimais.
`NumberFormatter::MAX_INTEGER_DIGITS` int
  Máximo de dígitos inteiros.
`NumberFormatter::MIN_INTEGER_DIGITS` int
  Mínimo de dígitos inteiros.
`NumberFormatter::INTEGER_DIGITS` int
  Dígitos inteiros.
`NumberFormatter::MAX_FRACTION_DIGITS` int
  Máximo de dígitos decimais.
`NumberFormatter::MIN_FRACTION_DIGITS` int
  Mínimo de dígitos decimais.
`NumberFormatter::FRACTION_DIGITS` int
  Dígitos decimais.
`NumberFormatter::MULTIPLIER` int
  Multiplicador.
`NumberFormatter::GROUPING_SIZE` int
  Tamanho do agrupamento.
`NumberFormatter::ROUNDING_MODE` int
  Modo de arredondamento.
`NumberFormatter::ROUNDING_INCREMENT` int
  Incremento de arredondamento.
`NumberFormatter::FORMAT_WIDTH` int
  A largura para a qual a saída de format() será preenchida.
`NumberFormatter::PADDING_POSITION` int
  A posição na qual o preenchimento acontecerá. Consulte as constantes de posição de preenchimento para possíveis valores de argumentos.
`NumberFormatter::SECONDARY_GROUPING_SIZE` int
  Tamanho de agrupamento secundário.
`NumberFormatter::SIGNIFICANT_DIGITS_USED` int
  Usa dígitos significativos.
`NumberFormatter::MIN_SIGNIFICANT_DIGITS` int
  Mínimo de dígitos significativos.
`NumberFormatter::MAX_SIGNIFICANT_DIGITS` int
  Máximo de dígitos significativos.
`NumberFormatter::LENIENT_PARSE` int
  Modo de análise brando usado por formatos baseados em regras.

## Atributos de Texto de Formatos de Números

Atributo de texto de formato numérico usado por numfmt_get_text_attribute() e numfmt_set_text_attribute().

`NumberFormatter::POSITIVE_PREFIX` int
  Prefixo positivo.
`NumberFormatter::POSITIVE_SUFFIX` int
  Sufixo positivo.
`NumberFormatter::NEGATIVE_PREFIX` int
  Prefixo negativo.
`NumberFormatter::NEGATIVE_SUFFIX` int
  Sufixo negativo.
`NumberFormatter::PADDING_CHARACTER` int
  O caractere usado para preencher a largura do formato.
`NumberFormatter::CURRENCY_CODE` int
  O código de moeda ISO.
`NumberFormatter::DEFAULT_RULESET` int
  O conjunto de regras padrão. Isso está disponível apenas com formatadores baseados em regras.
`NumberFormatter::PUBLIC_RULESETS` int
  Os conjuntos de regras públicas. Isso está disponível apenas com formatadores baseados em regras. Este é um atributo somente leitura. Os conjuntos de regras públicos são retornados como uma única string, com cada nome de conjunto de regras delimitado por ';' (ponto e vírgula).

## Especificadores de Formatos de Símbolos

Símbolos de formato de número usados por numfmt_get_symbol() e numfmt_set_symbol().

`NumberFormatter::DECIMAL_SEPARATOR_SYMBOL` int
  O separador de decimais.
`NumberFormatter::GROUPING_SEPARATOR_SYMBOL` int
  O separador de agrupamento.
`NumberFormatter::PATTERN_SEPARATOR_SYMBOL` int
  O separador de padrão.
`NumberFormatter::PERCENT_SYMBOL` int
  O sinal de percentagem.
`NumberFormatter::ZERO_DIGIT_SYMBOL` int
  Zero.
`NumberFormatter::DIGIT_SYMBOL` int
  Caractere representando um dígito no padrão.
`NumberFormatter::MINUS_SIGN_SYMBOL` int
  O sinal de menos.
`NumberFormatter::PLUS_SIGN_SYMBOL` int
  O sinal de mais.
`NumberFormatter::CURRENCY_SYMBOL` int
  O símbolo da moeda.
`NumberFormatter::INTL_CURRENCY_SYMBOL` int
  O símbolo internacional da moeda.
`NumberFormatter::MONETARY_SEPARATOR_SYMBOL` int
  O separador monetário.
`NumberFormatter::EXPONENTIAL_SYMBOL` int
  O símbolo exponencial.
`NumberFormatter::PERMILL_SYMBOL` int
  O símbolo de permilagem.
`NumberFormatter::PAD_ESCAPE_SYMBOL` int
  Caractere de preenchimento de escape.
`NumberFormatter::INFINITY_SYMBOL` int
  Símbolo de infinito.
`NumberFormatter::NAN_SYMBOL` int
  Símbolo representando que o valor não é um número.
`NumberFormatter::SIGNIFICANT_DIGIT_SYMBOL` int
  Símbolo de dígito significativo.
`NumberFormatter::MONETARY_GROUPING_SEPARATOR_SYMBOL` int
  O separador de agrupamento monetário.

## Modos de Arredondamento

Valores de modo de arredondamento usados por numfmt_get_attribute() e numfmt_set_attribute() com o atributo `NumberFormatter::ROUNDING_MODE`.

`NumberFormatter::ROUND_AWAY_FROM_ZERO`
  Sinônimo de `NumberFormatter::ROUND_UP`.
`NumberFormatter::ROUND_CEILING` int
  Modo de arredondamento para arredondar em direção ao infinito positivo.
`NumberFormatter::ROUND_DOWN` int
  Modo de arredondamento para arredondar para zero.
`NumberFormatter::ROUND_FLOOR` int
  Modo de arredondamento para arredondar em direção ao infinito negativo.
`NumberFormatter::ROUND_HALFDOWN` int
  Modo de arredondamento para arredondar para o "vizinho mais próximo", a menos que ambos os vizinhos sejam equidistantes, caso em que arredonda para baixo.
`NumberFormatter::ROUND_HALFEVEN` int
  Modo de arredondamento para arredondar em direção ao "vizinho mais próximo", a menos que ambos os vizinhos sejam equidistantes; nesse caso, arredondar em direção ao vizinho par.
`NumberFormatter::ROUND_HALFODD`
  Modo de arredondamento na direção do "vizinho ímpar".
`NumberFormatter::ROUND_HALFUP` int
  Modo de arredondamento para arredondar para o "vizinho mais próximo", a menos que ambos os vizinhos sejam equidistantes; nesse caso, arredondar para cima.
`NumberFormatter::ROUND_TOWARD_ZERO`
  Sinônimo de `NumberFormatter::ROUND_DOWN`.
`NumberFormatter::ROUND_UP` int
  Modo de arredondamento para arredondar a partir de zero.

## Especificadores de Preenchimento

Valores de posição de preenchimento usados por numfmt_get_attribute() e numfmt_set_attribute() com o atributo `NumberFormatter::PADDING_POSITION`.

`NumberFormatter::PAD_AFTER_PREFIX` int
  Caracteres de preenchimento inseridos após o prefixo.
`NumberFormatter::PAD_AFTER_SUFFIX` int
  Caracteres de preenchimento inseridos após o sufixo.
`NumberFormatter::PAD_BEFORE_PREFIX` int
  Caracteres de preenchimento inseridos antes do prefixo.
`NumberFormatter::PAD_BEFORE_SUFFIX` int
  Caracteres de preenchimento inseridos antes do sufixo.

## Veja Também

- » Documentação de formatação ICU
- » Formatadores de números ICU
- » Formatadores de decimais ICU
- » Formatadores de números baseados em regras ICU

## Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | Adicionadas as constantes `NumberFormatter::DECIMAL_COMPACT_SHORT`, `NumberFormatter::DECIMAL_COMPACT_LONG`, `NumberFormatter::CURRENCY_ISO`, `NumberFormatter::CURRENCY_PLURAL`, `NumberFormatter::CASH_CURRENCY` e `NumberFormatter::CURRENCY_STANDARD`.
8.4.0 | As constantes de classe agora são tipadas.

# NumberFormatter::create

# numfmt_create

# NumberFormatter::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::create -- numfmt_create -- NumberFormatter::__construct — Cria um formatador de número

### Descrição

Estilo orientado a objetos (método)

public static function NumberFormatter::create(string `$locale`, int `$style`, ?string `$pattern` = `null`): ?NumberFormatter

Estilo procedural

function numfmt_create(string `$locale`, int `$style`, ?string `$pattern` = `null`): ?NumberFormatter

Estilo orientado a objetos (construtor):

public function NumberFormatter::__construct(string `$locale`, int `$style`, ?string `$pattern` = `null`)

Cria um formatador de número.

### Parâmetros

`locale`

  Localidade na qual o número deve ser formatado (nome da localidade, ex.: pt_BR).

`style`

  Estilo da formatação, uma das constantes de estilo de formatação. Se `NumberFormatter::PATTERN_DECIMAL` ou `NumberFormatter::PATTERN_RULEBASED` forem passadas, o formato do número será aberto usando o modelo fornecido, que deve estar conforme a sintaxe descrita na » documentação de formato decimal da ICU ou na » documentação de formato de número com base em regras da ICU, respectively.

`pattern`

  String de modelo se o estilo escolhido requerer um modelo.

### Valor Retornado

Retorna um objeto NumberFormatter ou `null` em caso de erro.

### Erros/Exceções

Uma exceção ValueError é lançada se `locale` for inválido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Uma exceção ValueError agora é lançada se `locale` for inválido.
8.0.0 | `pattern` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo de numfmt_create()

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    $fmt = numfmt_create( 'it', NumberFormatter::SPELLOUT );
    echo numfmt_format($fmt, 1142)."\n";
    ?>

Exemplo #2 Exemplo de NumberFormatter::create()

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt = new NumberFormatter( 'it', NumberFormatter::SPELLOUT );
    echo $fmt->format(1142)."\n";
    ?>

O exemplo acima produzirá:

    1.234.567,891
    millicentoquarantadue

### Veja Também

- numfmt_format() - Formata um número
- numfmt_parse() - Interpreta um número

# NumberFormatter::format

# numfmt_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::format -- numfmt_format — Formata um número

### Descrição

Estilo orientado a objetos

public function NumberFormatter::format(int|float `$num`, int `$type` = `NumberFormatter::TYPE_DEFAULT`): string|false

Estilo procedural

function numfmt_format(NumberFormatter `$formatter`, int|float `$num`, int `$type` = `NumberFormatter::TYPE_DEFAULT`): string|false

Formata um valor numérico de acordo com as regras de formatação.

### Parâmetros

`formatter`

  Objeto NumberFormatter.

`num`

  O valor a formatar. Pode ser int ou float, outros tipos serão convertidos para valores numéricos.

`type`

  O tipo de formatação a ser usado. Observe que `NumberFormatter::TYPE_CURRENCY` não é suportado; use NumberFormatter::formatCurrency() em seu lugar.

### Valor Retornado

Retorna a string contendo o valor formatado, ou `false` em caso de erro.

### Exemplos

Exemplo #1 Exemplo de numfmt_format()

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    $data = numfmt_format($fmt, 1234567.891234567890000);
    var_dump($data);
    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    $data = $fmt->format(1234567.891234567890000);
    var_dump($data);
    ?>

O exemplo acima produzirá:

    string(13) "1.234.567,891"

### Notas

> Nota:

> Formatos possíveis por este método não usam todas as possibilidades da biblioteca ICU subjacente, como por exemplo usar o símbolo da moeda em sua forma curta ou abreviada.

> Para usar todas as possibilidades, use a função msgfmt_format_message().

### Veja Também

- numfmt_get_error_code() - Obtém o último código de erro do formatador
- numfmt_format_currency() - Formata um valor de moeda
- numfmt_parse() - Interpreta um número
- msgfmt_format_message() - Formata uma mensagem rapidamente

# NumberFormatter::formatCurrency

# numfmt_format_currency

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::formatCurrency -- numfmt_format_currency — Formata um valor de moeda

### Descrição

Estilo orientado a objetos

public function NumberFormatter::formatCurrency(float `$amount`, string `$currency`): string|false

Estilo procedural

function numfmt_format_currency(NumberFormatter `$formatter`, float `$amount`, string `$currency`): string|false

Formata o valor de moeda de acordo com as regras de formatação.

### Parâmetros

`formatter`

  Objeto NumberFormatter.

`amount`

  O valor numérico monetário.

`currency`

  O código de moeda de 3 letras ISO 4217 indicando a moeda a ser usada.

### Valor Retornado

String representando o valor monetário formatado, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de numfmt_format_currency()

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::CURRENCY );
    echo numfmt_format_currency($fmt, 1234567.891234567890000, "EUR")."\n";
    echo numfmt_format_currency($fmt, 1234567.891234567890000, "RUR")."\n";
    $fmt = numfmt_create( 'ru_RU', NumberFormatter::CURRENCY );
    echo numfmt_format_currency($fmt, 1234567.891234567890000, "EUR")."\n";
    echo numfmt_format_currency($fmt, 1234567.891234567890000, "RUR")."\n";
    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::CURRENCY );
    echo $fmt->formatCurrency(1234567.891234567890000, "EUR")."\n";
    echo $fmt->formatCurrency(1234567.891234567890000, "RUR")."\n";
    $fmt = new NumberFormatter( 'ru_RU', NumberFormatter::CURRENCY );
    echo $fmt->formatCurrency(1234567.891234567890000, "EUR")."\n";
    echo $fmt->formatCurrency(1234567.891234567890000, "RUR")."\n";
    ?>

O exemplo acima produzirá:

    1.234.567,89 €
    1.234.567,89 RUR
    1 234 567,89€
    1 234 567,89р.

### Notas

> Nota:

> Formatos possíveis por este método não usam todas as possibilidades da biblioteca ICU subjacente, como por exemplo usar o símbolo da moeda em sua forma curta ou abreviada.

> Para usar todas as possibilidades, use a função msgfmt_format_message().

### Veja Também

- numfmt_get_error_code() - Obtém o último código de erro do formatador
- numfmt_format() - Formata um número
- numfmt_parse_currency() - Interpreta um valor monetário
- msgfmt_format_message() - Formata uma mensagem rapidamente

# NumberFormatter::getAttribute

# numfmt_get_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getAttribute -- numfmt_get_attribute — Obtém um atributo

### Descrição

Estilo orientado a objetos

public function NumberFormatter::getAttribute(int `$attribute`): int|float|false

Estilo procedural

function numfmt_get_attribute(NumberFormatter `$formatter`, int `$attribute`): int|float|false

Obtém um atributo numérico associado com o formatador. Um exemplo de um atributo numérico é o número de dígitos inteiros que o formatador irá produzir.

### Parâmetros

`formatter`

  Objeto NumberFormatter.

`attribute`

  Especificador de atributo - uma das constantes de atributo numérico.

### Valor Retornado

Retorna o valor do atributo em caso de sucesso, ou `false` em caso de erro.

### Exemplos

Exemplo #1 Exemplo de numfmt_get_attribute()

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Dígitos: ".numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS, 2);
    echo "Dígitos: ".numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Dígitos: ".$fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setAttribute(NumberFormatter::MAX_FRACTION_DIGITS, 2);
    echo "Dígitos: ".$fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

O exemplo acima produzirá:

    Dígitos: 3
    1.234.567,891
    Dígitos: 2
    1.234.567,89

### Veja Também

- numfmt_get_error_code() - Obtém o último código de erro do formatador
- numfmt_get_text_attribute() - Obtém um atributo de texto
- numfmt_set_attribute() - Define um atributo

# NumberFormatter::getErrorCode

# numfmt_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getErrorCode -- numfmt_get_error_code — Obtém o último código de erro do formatador

### Descrição

Estilo orientado a objetos

public function NumberFormatter::getErrorCode(): int

Estilo procedural

function numfmt_get_error_code(NumberFormatter `$formatter`): int

Obtém o código de erro da última função realizada pelo formatador.

### Parâmetros

`formatter`

  Objeto NumberFormatter.

### Valor Retornado

Retorna o código de erro da última chamada ao formatador.

### Exemplos

Exemplo #1 Exemplo de numfmt_get_error_code()

    <?php
    $fmt  = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    $data = numfmt_format($fmt, 1234567.891234567890000);
    if (intl_is_failure(numfmt_get_error_code($fmt))) {
        echo 'Erro do formatador';
    }
    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    $fmt->format(1234567.891234567890000);
    if (intl_is_failure($fmt->getErrorCode())) {
        echo 'Erro do formatador';
    }
    ?>

### Veja Também

- numfmt_get_error_message() - Obtém a última mensagem de erro do formatador
- intl_get_error_code() - Obtém o último código de erro
- intl_is_failure() - Verifica se o código de erro fornecido indica falha

# NumberFormatter::getErrorMessage

# numfmt_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getErrorMessage -- numfmt_get_error_message — Obtém a última mensagem de erro do formatador

### Descrição

Estilo orientado a objetos

public function NumberFormatter::getErrorMessage(): string

Estilo procedural

function numfmt_get_error_message(NumberFormatter `$formatter`): string

Obtém a mensagem de erro da última função realizada pelo formatador.

### Parâmetros

`formatter`

  Objeto NumberFormatter.

### Valor Retornado

Retorna a mensagem de erro da última chamada ao formatador.

### Exemplos

Exemplo #1 Exemplo de numfmt_get_error_message()

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    $data = numfmt_format($fmt, 1234567.891234567890000);
    var_dump(numfmt_get_error_message($fmt));
    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    $fmt->format(1234567.891234567890000);
    var_dump(numfmt_get_error_message($fmt));
    ?>

### Veja Também

- numfmt_get_error_code() - Obtém o último código de erro do formatador
- intl_get_error_code() - Obtém o último código de erro
- intl_is_failure() - Verifica se o código de erro fornecido indica falha

# NumberFormatter::getLocale

# numfmt_get_locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getLocale -- numfmt_get_locale — Obtém a localidade do formatador

### Descrição

Estilo orientado a objetos

public function NumberFormatter::getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false

Estilo procedural

function numfmt_get_locale(NumberFormatter `$formatter`, int `$type` = `ULOC_ACTUAL_LOCALE`): string|false

Obtém o nome da localidade do formatador.

### Parâmetros

`formatter`

  Objeto NumberFormatter.

`type`

  Pode-se escolher entre localidade válida e localidade real ( `Locale::VALID_LOCALE`, `Locale::ACTUAL_LOCALE`, respectivamente). O padrão é a localidade real.

### Valor Retornado

O nome da localidade usada para criar o formatador, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de numfmt_get_locale()

    <?php
    $req     = 'fr_FR_PARIS';
    $fmt     = numfmt_create( $req,  NumberFormatter::DECIMAL);
    $res_val = numfmt_get_locale( $fmt, Locale::VALID_LOCALE );
    $res_act = numfmt_get_locale( $fmt, Locale::ACTUAL_LOCALE );
    printf( "Nome de localidade requisitado: %s\nNome de localidade válido: %s\nNome de localidade atual: %s\n",
             $req, $res_val, $res_act );
    ?>

O exemplo acima produzirá:

    Nome de localidade requisitado: fr_FR_PARIS
    Nome de localidade válido: fr_FR
    Nome de localidade atual: fr

### Veja Também

- numfmt_create() - Cria um formatador de número
- numfmt_get_error_code() - Obtém o último código de erro do formatador

# NumberFormatter::getPattern

# numfmt_get_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getPattern -- numfmt_get_pattern — Obtém padrão do formatador

### Descrição

Estilo orientado a objetos

public function NumberFormatter::getPattern(): string|false

Estilo procedural

function numfmt_get_pattern(NumberFormatter `$formatter`): string|false

Extrai o padrão usado pelo formatador.

### Parâmetros

`formatter`

  Objeto NumberFormatter.

### Valor Retornado

string do padrão usado pelo formatador, ou `false` se um erro acontecer.

### Exemplos

Exemplo #1 Exemplo de numfmt_get_pattern()

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Padrão: ".numfmt_get_pattern($fmt)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_pattern($fmt, "#0.# kg");
    echo "Padrão: ".numfmt_get_pattern($fmt)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Padrão: ".$fmt->getPattern()."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setPattern("#0.# kg");
    echo "Padrão: ".$fmt->getPattern()."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

O exemplo acima produzirá:

    Padrão: #,##0.###
    1.234.567,891
    Padrão: #0.# kg
    1234567,9 kg

### Veja Também

- numfmt_get_error_code() - Obtém o último código de erro do formatador
- numfmt_set_pattern() - Define o padrão do formatador
- numfmt_create() - Cria um formatador de número

# NumberFormatter::getSymbol

# numfmt_get_symbol

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getSymbol -- numfmt_get_symbol — Obtém um valor de símbolo

### Descrição

Estilo orientado a objetos

public function NumberFormatter::getSymbol(int `$symbol`): string|false

Estilo procedural

function numfmt_get_symbol(NumberFormatter `$formatter`, int `$symbol`): string|false

Obtém um símbolo associado ao formatador. O formatador usa símbolos para representar os caracteres especiais dependentes de localidade em um número, por exemplo o sinal de percentagem. Esta API não é suportada para formatadores baseados em regras.

### Parâmetros

`formatter`

  Objeto NumberFormatter.

`symbol`

  Especificador de símbolo, uma das constantes de símbolo de formatação.

### Valor Retornado

A string do símbolo ou `false` em caso de erro.

### Exemplos

Exemplo #1 Exemplo de numfmt_get_symbol()

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Sep: ".numfmt_get_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL, "*");
    echo "Sep: ".numfmt_get_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Sep: ".$fmt->getSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL, "*");
    echo "Sep: ".$fmt->getSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

O exemplo acima produzirá:

    Sep: .
    1.234.567,891
    Sep: *
    1*234*567,891

### Veja Também

- numfmt_get_error_code() - Obtém o último código de erro do formatador
- numfmt_set_symbol() - Define um valor de símbolo

# NumberFormatter::getTextAttribute

# numfmt_get_text_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getTextAttribute -- numfmt_get_text_attribute — Obtém um atributo de texto

### Descrição

Estilo orientado a objetos

public function NumberFormatter::getTextAttribute(int `$attribute`): string|false

Estilo procedural

function numfmt_get_text_attribute(NumberFormatter `$formatter`, int `$attribute`): string|false

Obtém um atributo de texto associado ao formatador. Um exemplo de um atributo de texto é o sufixo para números positivos. Se o formatador não entender o atributo, o erro `U_UNSUPPORTED_ERROR` é produzido. Formatadores baseados em regras entendem apenas `NumberFormatter::DEFAULT_RULESET` e `NumberFormatter::PUBLIC_RULESETS`.

### Parâmetros

`formatter`

  Objeto NumberFormatter.

`attribute`

  Especificador de atributo - uma das constantes de atributo de texto.

### Valor Retornado

Retorna o valor do atributo em caso de sucesso, ou `false` em caso de erro.

### Exemplos

Exemplo #1 Exemplo de numfmt_get_text_attribute()

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Prefixo: ".numfmt_get_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo numfmt_format($fmt, -1234567.891234567890000)."\n";
    numfmt_set_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX, "MENOS");
    echo "Prefixo: ".numfmt_get_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo numfmt_format($fmt, -1234567.891234567890000)."\n";
    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Prefixo: ".$fmt->getTextAttribute(NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo $fmt->format(-1234567.891234567890000)."\n";
    $fmt->setTextAttribute(NumberFormatter::NEGATIVE_PREFIX, "MENOS");
    echo "Prefixo: ".$fmt->getTextAttribute(NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo $fmt->format(-1234567.891234567890000)."\n";
    ?>

O exemplo acima produzirá:

    Prefixo: -
    -1.234.567,891
    Prefixo: MENOS
    MENOS1.234.567,891

### Veja Também

- numfmt_get_error_code() - Obtém o último código de erro do formatador
- numfmt_get_attribute() - Obtém um atributo
- numfmt_set_text_attribute() - Define um atributo de texto

# NumberFormatter::parse

# numfmt_parse

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::parse -- numfmt_parse — Interpreta um número

### Descrição

Estilo orientado a objetos

public function NumberFormatter::parse(string `$string`, int `$type` = `NumberFormatter::TYPE_DOUBLE`, int `&$offset` = `null`): int|float|false

Estilo procedural

function numfmt_parse(
NumberFormatter `$formatter`,
string `$string`,
int `$type` = `NumberFormatter::TYPE_DOUBLE`,
int `&$offset` = `null`
): int|float|false

Converte uma string em um número usando as regras atuais do formatador.

### Parâmetros

`formatter`

  Objeto NumberFormatter.

`string`

  A string a ser convertida para um número.

`type`

  O tipo de formatação a ser usado. Por padrão, `NumberFormatter::TYPE_DOUBLE` é usado. Observe que `NumberFormatter::TYPE_CURRENCY` não é suportado; use NumberFormatter::parseCurrency() em seu lugar.

`offset`

  Deslocamento na string a partir do qual a interpretação será iniciada. Ao retornar, este valor conterá o deslocamento no qual a interpretação terminou.

### Valor Retornado

O valor numérico convertido ou `false` em caso de erro.

### Exemplos

Exemplo #1 Exemplo de numfmt_parse()

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    $num = "1.234.567,891";
    echo numfmt_parse($fmt, $num)."\n";
    echo numfmt_parse($fmt, $num, NumberFormatter::TYPE_INT32)."\n";
    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    $num = "1.234.567,891";
    echo $fmt->parse($num)."\n";
    echo $fmt->parse($num, NumberFormatter::TYPE_INT32)."\n";
    ?>

O exemplo acima produzirá:

    1234567.891
    1234567

### Veja Também

- numfmt_get_error_code() - Obtém o último código de erro do formatador
- numfmt_format() - Formata um número
- numfmt_parse_currency() - Interpreta um valor monetário

# NumberFormatter::parseCurrency

# numfmt_parse_currency

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::parseCurrency -- numfmt_parse_currency — Interpreta um valor monetário

### Descrição

Estilo orientado a objetos

public function NumberFormatter::parseCurrency(string `$string`, string `&$currency`, int `&$offset` = `null`): float|false

Estilo procedural

function numfmt_parse_currency(
NumberFormatter `$formatter`,
string `$string`,
string `&$currency`,
int `&$offset` = `null`
): float|false

Interpreta uma string em um valor decimal e uma moeda usando o formatador atual.

### Parâmetros

`formatter`

  Objeto NumberFormatter.

`currency`

  Parâmetro que irá receber o nome da moeda (código de moeda de 3 letras ISO 4217).

`offset`

  Deslocamento na string a partir do qual a interpretação será iniciada. Ao retornar, este valor conterá o deslocamento no qual a interpretação terminou.

### Valor Retornado

O valor numérico interpretado ou `false` em caso de erro.

### Exemplos

Exemplo #1 Exemplo de numfmt_parse_currency()

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::CURRENCY );
    $num = "1.234.567,89\xc2\xa0$";
    echo "Temos ".numfmt_parse_currency($fmt, $num, $curr)." em $curr\n";
    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::CURRENCY );
    $num = "1.234.567,89\xc2\xa0$";
    echo "Temos ".$fmt->parseCurrency($num, $curr)." em $curr\n";
    ?>

O exemplo acima produzirá:

    Temos 1234567.89 em USD

### Veja Também

- numfmt_get_error_code() - Obtém o último código de erro do formatador
- numfmt_parse() - Interpreta um número
- numfmt_format_currency() - Formata um valor de moeda

# NumberFormatter::setAttribute

# numfmt_set_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::setAttribute -- numfmt_set_attribute — Define um atributo

### Descrição

Estilo orientado a objetos

public function NumberFormatter::setAttribute(int `$attribute`, int|float `$value`): bool

Estilo procedural

function numfmt_set_attribute(NumberFormatter `$formatter`, int `$attribute`, int|float `$value`): bool

Define um atributo numérico associado ao formatador. Um exemplo de atributo numérico é o número de dígitos inteiros que o formatador irá produzir.

### Parâmetros

`formatter`

  Objeto NumberFormatter.

`attribute`

  Especificador de atributo - uma das constantes de atributo numérico.

`value`

  O valor do atributo.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de numfmt_set_attribute()

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Dígitos: ".numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS, 2);
    echo "Dígitos: ".numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Dígitos: ".$fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setAttribute(NumberFormatter::MAX_FRACTION_DIGITS, 2);
    echo "Dígitos: ".$fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

O exemplo acima produzirá:

    Dígitos: 3
    1.234.567,891
    Dígitos: 2
    1.234.567,89

Exemplo #3 Usando `NumberFormatter::ROUNDING_MODE` para truncar valores

Por padrão, NumberFormatter arredonda valores. Usar `NumberFormatter::ROUND_DOWN` como o modo de arredondamento `NumberFormatter::ROUNDING_MODE` trunca o valor para o número especificado de dígitos fracionários sem arredondamento.

    <?php
    $fmt = new NumberFormatter('en_US', NumberFormatter::DECIMAL);
    $fmt->setAttribute(NumberFormatter::FRACTION_DIGITS, 2);

    echo "Modo de arredondamento padrão:\n";
    echo $fmt->format(3.789), "\n"; // 3.79 (arredonda para cima)
    echo $fmt->format(3.781), "\n"; // 3.78 (arredonda para baixo)

    $fmt->setAttribute(NumberFormatter::ROUNDING_MODE, NumberFormatter::ROUND_DOWN);

    echo "\Com ROUND_DOWN (trunca):\n";
    echo $fmt->format(3.789), "\n"; // 3.78 (truncado)
    echo $fmt->format(3.781), "\n"; // 3.78 (truncado)
    ?>

O exemplo acima produzirá:

    Modo de arredondamento padrão:
    3.79
    3.78

    Com ROUND_DOWN (trunca):
    3.78
    3.78

### Veja Também

- numfmt_get_error_code() - Obtém o último código de erro do formatador
- numfmt_get_attribute() - Obtém um atributo
- numfmt_set_text_attribute() - Define um atributo de texto

# NumberFormatter::setPattern

# numfmt_set_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::setPattern -- numfmt_set_pattern — Define o padrão do formatador

### Descrição

Estilo orientado a objetos

public function NumberFormatter::setPattern(string `$pattern`): bool

Estilo procedural

function numfmt_set_pattern(NumberFormatter `$formatter`, string `$pattern`): bool

Define o padrão a ser usado pelo formatador. Não pode ser usado em um formatador baseado em regras.

### Parâmetros

`formatter`

  Objeto NumberFormatter.

`pattern`

  O padrão na sintaxe descrita na » Documentação DecimalFormat da ICU.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de numfmt_set_pattern()

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Padrão: ".numfmt_get_pattern($fmt)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_pattern($fmt, "#0.# kg");
    echo "Padrão: ".numfmt_get_pattern($fmt)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Padrão: ".$fmt->getPattern()."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setPattern("#0.# kg");
    echo "Padrão: ".$fmt->getPattern()."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

O exemplo acima produzirá:

    Padrão: #,##0.###
    1.234.567,891
    Padrão: #0.# kg
    1234567,9 kg

### Veja Também

- numfmt_get_error_code() - Obtém o último código de erro do formatador
- numfmt_create() - Cria um formatador de número
- numfmt_get_pattern() - Obtém padrão do formatador

# NumberFormatter::setSymbol

# numfmt_set_symbol

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::setSymbol -- numfmt_set_symbol — Define um valor de símbolo

### Descrição

Estilo orientado a objetos

public function NumberFormatter::setSymbol(int `$symbol`, string `$value`): bool

Estilo procedural

function numfmt_set_symbol(NumberFormatter `$formatter`, int `$symbol`, string `$value`): bool

Define um símbolo associado ao formatador. O formatador usa símbolos para representar os caracteres especiais dependentes de localidade em um número, por exemplo o sinal de percentagem. Esta API não é suportada para formatadores baseados em regras.

### Parâmetros

`formatter`

  Objeto NumberFormatter.

`symbol`

  Especificador de símbolo, uma das constantes de símbolo de formatação.

`value`

  Texto para o símbolo.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de numfmt_set_symbol()

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Sep: ".numfmt_get_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL, "*");
    echo "Sep: ".numfmt_get_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Sep: ".$fmt->getSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL, "*");
    echo "Sep: ".$fmt->getSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

O exemplo acima produzirá:

    Sep: .
    1.234.567,891
    Sep: *
    1*234*567,891

### Veja Também

- numfmt_get_error_code() - Obtém o último código de erro do formatador
- numfmt_get_symbol() - Obtém um valor de símbolo

# NumberFormatter::setTextAttribute

# numfmt_set_text_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::setTextAttribute -- numfmt_set_text_attribute — Define um atributo de texto

### Descrição

Estilo orientado a objetos

public function NumberFormatter::setTextAttribute(int `$attribute`, string `$value`): bool

Estilo procedural

function numfmt_set_text_attribute(NumberFormatter `$formatter`, int `$attribute`, string `$value`): bool

Define um atributo de texto associado ao formatador. Um exemplo de um atributo de texto é o sufixo para números positivos. Se o formatador não entender o atributo, o erro `U_UNSUPPORTED_ERROR` é produzido. Formatadores baseados em regras somente entendem `NumberFormatter::DEFAULT_RULESET` e `NumberFormatter::PUBLIC_RULESETS`.

### Parâmetros

`formatter`

  Objeto NumberFormatter.

`attribute`

  Especificador de atributo - uma das constantes de atributo de texto.

`value`

  Texto para o valor do atributo.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de numfmt_set_text_attribute()

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Prefixo: ".numfmt_get_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo numfmt_format($fmt, -1234567.891234567890000)."\n";
    numfmt_set_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX, "MENOS");
    echo "Prefixo: ".numfmt_get_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo numfmt_format($fmt, -1234567.891234567890000)."\n";
    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Prefixo: ".$fmt->getTextAttribute(NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo $fmt->format(-1234567.891234567890000)."\n";
    $fmt->setTextAttribute(NumberFormatter::NEGATIVE_PREFIX, "MENOS");
    echo "Prefixo: ".$fmt->getTextAttribute(NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo $fmt->format(-1234567.891234567890000)."\n";
    ?>

O exemplo acima produzirá:

    Prefixo: -
    -1.234.567,891
    Prefixo: MENOS
    MENOS1.234.567,891

### Veja Também

- numfmt_get_error_code() - Obtém o último código de erro do formatador
- numfmt_get_text_attribute() - Obtém um atributo de texto
- numfmt_set_attribute() - Define um atributo

## Índice

- NumberFormatter::create — Cria um formatador de número
- NumberFormatter::format — Formata um número
- NumberFormatter::formatCurrency — Formata um valor de moeda
- NumberFormatter::getAttribute — Obtém um atributo
- NumberFormatter::getErrorCode — Obtém o último código de erro do formatador
- NumberFormatter::getErrorMessage — Obtém a última mensagem de erro do formatador
- NumberFormatter::getLocale — Obtém a localidade do formatador
- NumberFormatter::getPattern — Obtém padrão do formatador
- NumberFormatter::getSymbol — Obtém um valor de símbolo
- NumberFormatter::getTextAttribute — Obtém um atributo de texto
- NumberFormatter::parse — Interpreta um número
- NumberFormatter::parseCurrency — Interpreta um valor monetário
- NumberFormatter::setAttribute — Define um atributo
- NumberFormatter::setPattern — Define o padrão do formatador
- NumberFormatter::setSymbol — Define um valor de símbolo
- NumberFormatter::setTextAttribute — Define um atributo de texto

# A classe Locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Introdução

Uma "Locale" (localidade) é um identificador usado para se obter língua, cultura ou comportamento regional específico a partir de uma API. Localidades PHP são organizadas e identificadas da mesma forma que as localidades CLDR usadas pela ICU (e por muitos fornecedores de sistemas operacionais do tipo Unix, Mac, Java e assim por diante). Localidades são identificadas usando-se etiquetas de linguagem RFC 4646 (que usa hífen, e não sublinhado) em adição aos identificadores mais tradicionais que usam sublinhado. As funções desta classe são tolerantes a ambos os formatos, a não ser que seja especificado o contrário.

Exemplos de identificadores incluem:

- en-US (Ingês, Estados Unidos)
- zh-Hant-TW (Chinês, Tradicional, Taiwan)
- fr-CA, fr-FR (Francês para Canadá e França respectivamente)

A classe Locale (e funções procedurais relacionadas) são usadas para interagir com identificadores de localidade--para verificar que um ID está bem formado, válido, etc. As extensões usadas pela CLDR na UAX #35 (e herdadas pela ICU) são válidas e utilizadas em qualquer lugar que seriam normalmente usadas na ICU.

A classe Locale não pode ser instanciada como objeto. Todas as funções e métodos fornecidos são estáticos.

A string nula ou vazia obtém a localidade "raiz". A localidade "raiz" é equivalente a "en_US_POSIX" na CLDR. Etiquetas de língua (e portanto identificadores de localidade) são sensíveis a maiúsculas/minúsculas. Existe uma função de canonização para fazer com que as maiúsculas/minúsculas correspondam à especificação.

## Resumo da classe

class Locale {
/* Constantes */
public const int ACTUAL_LOCALE;
public const int VALID_LOCALE;
public const null DEFAULT_LOCALE = null;
public const string LANG_TAG;
public const string EXTLANG_TAG;
public const string SCRIPT_TAG;
public const string REGION_TAG;
public const string VARIANT_TAG;
public const string GRANDFATHERED_LANG_TAG;
public const string PRIVATE_TAG;
/* Métodos */
public static function acceptFromHttp(string `$header`): string|false
public static function canonicalize(string `$locale`): ?string
public static function composeLocale(array `$subtags`): string|false
public static function filterMatches(string `$languageTag`, string `$locale`, bool `$canonicalize` = `false`): ?bool
public static function getAllVariants(string `$locale`): ?array
public static function getDefault(): string
public static function getDisplayLanguage(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getDisplayName(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getDisplayRegion(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getDisplayScript(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getDisplayVariant(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getKeywords(string `$locale`): array|false|null
public static function getPrimaryLanguage(string `$locale`): ?string
public static function getRegion(string `$locale`): ?string
public static function getScript(string `$locale`): ?string
public static function isRightToLeft( string `$locale` = "" ): bool
public static function lookup(
array `$languageTag`,
string `$locale`,
bool `$canonicalize` = `false`,
?string `$defaultLocale` = `null`
): ?string
public static function parseLocale(string `$locale`): ?array
public static function setDefault(string `$locale`): true
}

## Constantes predefinidas

`Locale::DEFAULT_LOCALE` null
  Usada como parâmetro de localidade com os métodos das várias classes afetadas por localidade, como NumberFormatter por exemplo. Esta constante faz com que os métodos utilizem a localidade padrão.

Estas constantes descrevem a escolha da localidade para o método getLocale de diferentes classes.

`Locale::ACTUAL_LOCALE` int
  Esta é a localidade de onde os dados realmente vieram.
`Locale::VALID_LOCALE` int
  Esta é a localidade mais específica suportada pela ICU.

## Sub-etiquetas de localidade

Estas constantes definem como as localidades são analisadas ou compostas. Elas devem ser usadas como chaves no array de argumentos para a função locale_compose() e são retornadas de locale_parse() como chaves do array associativo retornado.

`Locale::LANG_TAG` string
  Sub-etiqueta de língua
`Locale::EXTLANG_TAG` string
  Sub-etiqueta de língua estendida
`Locale::SCRIPT_TAG` string
  Sub-etiqueta de script
`Locale::REGION_TAG` string
  Sub-etiqueta de região
`Locale::VARIANT_TAG` string
  Sub-etiqueta de variante
`Locale::GRANDFATHERED_LANG_TAG` string
  Sub-etiqueta de idioma antigo
`Locale::PRIVATE_TAG` string
  Sub-etiqueta privada

## Veja Também

- » RFC 4646 - Etiquetas para Identificação de Línguas
- » RFC 4647 - Correspondência de Etiquetas de Línguas
- » Projeto CLDR Unicode: Repositório da Dados de Localidades Comuns
- » Registro de Sub-etiquetas de Línguas IANA
- » Guia do Usuário ICU - Localidade
- » API de Localidade ICU

## Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | As constantes de classe agora são tipadas.

# Locale::acceptFromHttp

# locale_accept_from_http

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::acceptFromHttp -- locale_accept_from_http — Tenta descobrir a melhor localidade disponível baseado no cabeçalho HTTP "Accept-Language"

### Descrição

Estilo orientado a objetos

public static function Locale::acceptFromHttp(string `$header`): string|false

Estilo procedural

function locale_accept_from_http(string `$header`): string|false

Tenta encontrar a localidade que satisfaça a lista de línguas que é requisitada pelo cabeçalho HTTP "Accept-Language".

### Parâmetros

`header`

  A string contendo o cabeçalho "Accept-Language" de acordo com o formato RFC 2616.

### Valor Retornado

O identificador de localidade correspondente.

Retorna `false` quando o comprimento de `header` exceder `INTL_MAX_LOCALE_LEN`.

### Exemplos

Exemplo #1 Exemplo de locale_accept_from_http()

    <?php
    $locale = locale_accept_from_http($_SERVER['HTTP_ACCEPT_LANGUAGE']);
    echo $locale;
    ?>

Exemplo #2 Exemplo OO

    <?php
    $locale = Locale::acceptFromHttp($_SERVER['HTTP_ACCEPT_LANGUAGE']);
    echo $locale;
    ?>

O exemplo acima produzirá:

    en_US

### Veja Também

- locale_lookup() - Pesquisa a lista de etiquetas de língua pela melhor correspondência à língua

# Locale::canonicalize

# locale_canonicalize

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::canonicalize -- locale_canonicalize — Canoniza a string de localidade

### Descrição

public static function Locale::canonicalize(string `$locale`): ?string

Canonicaliza a string de localidade informada para o formato ICU.

Isso não indica ou retorna necessariamente uma localidade válida. É apenas uma versão da entrada que foi canonicalizada de acordo com as regras da ICU.

O comportamento desta função depende da versão do ICU que o PHP está utilizando (`INTL_ICU_VERSION`).

### Parâmetros

`locale`
  String de localidade original.

### Valor Retornado

A string de localidade canonizada.

Retorna `null` quando o comprimento de `locale` excede `INTL_MAX_LOCALE_LEN`.

### Exemplos

Exemplo #1 Exemplo de locale_canonicalize()

    echo Locale::canonicalize('en-US.utf8') . "\n";
    echo Locale::canonicalize('totally-not-valid') . "\n";

O exemplo acima produzirá algo semelhante a:

    en_US
    totally_NOT_VALID

# Locale::composeLocale

# locale_compose

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::composeLocale -- locale_compose — Retorna ID de localidade corretamente ordenado e delimitado

### Descrição

Estilo orientado a objetos

public static function Locale::composeLocale(array `$subtags`): string|false

Estilo procedural

function locale_compose(array `$subtags`): string|false

Retorna um ID de localidade corretamente ordenado e delimitado. As chaves identificam as sub-etiquetas de ID da localidade em particular, e os valores são associados às sub-etiquetas.

### Parâmetros

`subtags`

  Um array contendo uma lista de pares de chave-valor, onde as chaves identificam as sub-etiquetas de ID da localidade em particular, e os valores são os associados às sub-etiquetas.

  > Nota:

  > As sub-etiquetas `'variant'` e `'private'` suportam no máximo 15 valores enquanto que `'extlang'` suporta no máximo 3. Por exemplo, variantes são permitiras com sufixo no intervalo 0-14. Por isso as chaver para o array de entrada podem ser `variant0`, `variant1`, …,`variant14`. No ID de localidade retornado, a sub-etiqueta é ordenada pelo sufixo resultando em `variant0` seguida por `variant1`, seguida por `variant2` e assim por diante.

  > Alternativamente, os valores de `'variant'`, `'private'` e `'extlang'` podem ser especificados como array sob chave específica (ex.: `'variant'`). Neste caso não se aplica limite ao número de sub-etiquetas reconhecidas.

### Valor Retornado

O identificador de localidade correspondente, ou `false` quando `subtags` estiver vazio.

### Exemplos

Exemplo #1 Exemplo de locale_compose()

    <?php
    $arr = array(
        'language'=>'en',
        'script'  =>'Hans',
        'region'  =>'CN',
        'variant2'=>'rozaj',
        'variant1'=>'nedis',
        'private1'=>'prv1',
        'private2'=>'prv2',
    );
    echo locale_compose($arr);
    ?>

Exemplo #2 Exemplo OO

    <?php
    $arr = array(
        'language'=>'en' ,
        'script'  =>'Hans',
        'region'  =>'CN',
        'variant2'=>'rozaj',
        'variant1'=>'nedis',
        'private1'=>'prv1',
        'private2'=>'prv2',
    );
    echo Locale::composeLocale($arr);
    ?>

O exemplo acima produzirá:

    Locale: en_Hans_CN_nedis_rozaj_x_prv1_prv2

Exemplo #3 Limites de sub-etiquetas

Se `subtags` são fornecidas como chaves separadas com sufixo numérico, chaves não suportadas são silenciosamente ignoradas (neste caso `'extlang3'`), e ordenadas no resultado pelo sufixo numérico. Não é limites se as sub-etiquetas são informadas como array; a ordem é conforme informada.

    <?php
    $arr = array(
        'language' => 'en',
        'script'   => 'Hans',
        'region'   => 'CN',
        'extlang3' => 'd',
        'extlang2' => 'c',
        'extlang1' => 'b',
        'extlang0' => 'a',
    );
    echo locale_compose($arr), PHP_EOL;

    $arr = array(
        'language' => 'en',
        'script'   => 'Hans',
        'region'   => 'CN',
        'extlang'  => ['a', 'b', 'c', 'd'],
    );
    echo locale_compose($arr), PHP_EOL;
    ?>

O exemplo acima produzirá:

    en_a_b_c_Hans_CN
    en_a_b_c_d_Hans_CN

### Veja Também

- locale_parse() - Retorna um array de chaves-valores de elementos de sub-etiquetas de ID de localidade

# Locale::filterMatches

# locale_filter_matches

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::filterMatches -- locale_filter_matches — Verifica se um filtro de etiqueta de língua corresponde à localidade

### Descrição

Estilo orientado a objetos

public static function Locale::filterMatches(string `$languageTag`, string `$locale`, bool `$canonicalize` = `false`): ?bool

Estilo procedural

function locale_filter_matches(string `$languageTag`, string `$locale`, bool `$canonicalize` = `false`): ?bool

Verifica se um filtro `languageTag` corresponde à localidade `locale` de acordo com o algoritmo básico de filtragem da RFC 4647.

### Parâmetros

`languageTag`

  A etiqueta de língua a ser verificada

`locale`

  O intervalo de línguas contra o qual será feita a verificação

`canonicalize`

  Se verdadeiro, os argumentos serão convertidos à forma canônica antes da correspondência.

### Valor Retornado

`true` se `locale` corresponder a `languageTag`, `false` caso contrário.

Retorna `null` quando o comprimento de `locale` excede `INTL_MAX_LOCALE_LEN`.

### Exemplos

Exemplo #1 Exemplo de locale_filter_matches()

    <?php
    echo (locale_filter_matches('de-DEVA','de-DE', false)) ? "Corresponde" : "Não corresponde";
    echo '; ';
    echo (locale_filter_matches('de-DE_1996','de-DE', false)) ? "Corresponde" : "Não corresponde";
    ?>

Exemplo #2 Exemplo OO

    <?php
    echo (Locale::filterMatches('de-DEVA','de-DE', false)) ? "Corresponde" : "Não corresponde";
    echo '; ';
    echo (Locale::filterMatches('de-DE-1996','de-DE', false)) ? "Corresponde" : "Não corresponde";
    ?>

O exemplo acima produzirá:

    Não corresponde; Corresponde

### Veja Também

- locale_lookup() - Pesquisa a lista de etiquetas de língua pela melhor correspondência à língua

# Locale::getAllVariants

# locale_get_all_variants

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getAllVariants -- locale_get_all_variants — Obtém as variantes para a localidade

### Descrição

Estilo orientado a objetos

public static function Locale::getAllVariants(string `$locale`): ?array

Estilo procedural

function locale_get_all_variants(string `$locale`): ?array

Obtém as variantes para a localidade.

### Parâmetros

`locale`

  A localidade da qual serão extraídas as variantes.

### Valor Retornado

O array contendo a lista de todas as sub-etiquetas de variantes para a localidade ou `null` se não houver.

Retorna `null` quando o comprimento de `locale` excede `INTL_MAX_LOCALE_LEN`.

### Exemplos

Exemplo #1 Exemplo de locale_get_all_variants()

    <?php
    $arr = locale_get_all_variants('sl_IT_NEDIS_ROJAZ_1901');
    var_export( $arr );
    ?>

Exemplo #2 Exemplo OO

    <?php
     $arr = Locale::getAllVariants('sl_IT_NEDIS_ROJAZ_1901');
     var_export( $arr );
    ?>

O exemplo acima produzirá:

    array (
        0 => 'NEDIS',
        1 => 'ROJAZ',
        2 => '1901',
    )

### Veja Também

- locale_get_primary_language() - Obtém a língua primária para a localidade
- locale_get_script() - Obtém o tipo de escrita para a localidade
- locale_get_region() - Obtém a região para a localidade

# Locale::getDefault

# locale_get_default

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDefault -- locale_get_default — Obtém o valor de localidade padrão da variável global de INTL 'default_locale'

### Descrição

Estilo orientado a objetos

public static function Locale::getDefault(): string

Estilo procedural

function locale_get_default(): string

Obtém o valor de localidade padrão. Na inicialização do PHP este valor é definido para o valor do php.ini em 'intl.default_locale' se esse valor existir ou da função da ICU, uloc_getDefault().

### Parâmetros

### Valor Retornado

A localidade atual em tempo de execução.

### Exemplos

Exemplo #1 Exemplo de locale_get_default()

    <?php
    ini_set('intl.default_locale', 'de-DE');
    echo locale_get_default();
    echo '; ';
    locale_set_default('fr');
    echo locale_get_default();
    ?>

Exemplo #2 Exemplo OO

    <?php
    ini_set('intl.default_locale', 'de-DE');
    echo Locale::getDefault();
    echo '; ';
    Locale::setDefault('fr');
    echo Locale::getDefault();
    ?>

O exemplo acima produzirá:

    de-DE; fr

### Veja Também

- locale_set_default() - Define a localidade padrão em tempo de execução

# Locale::getDisplayLanguage

# locale_get_display_language

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayLanguage -- locale_get_display_language — Retorna um nome apropriadamente localizado para a língua da localidade

### Descrição

Estilo orientado a objetos

public static function Locale::getDisplayLanguage(string `$locale`, ?string `$displayLocale` = `null`): string|false

Estilo procedural

function locale_get_display_language(string `$locale`, ?string `$displayLocale` = `null`): string|false

Retorna um nome apropriadamente localizado para a língua da localidade. Se a localidade de entrada for `null`, a localidade padrão será usada.

### Parâmetros

`locale`

  A localidade para a qual será mostrada a língua

`displayLocale`

  Formato de localidade, opcional, para mostrar o nome da língua

### Valor Retornado

Nome da língua para a localidade `locale` no formato apropriado para `displayLocale`, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `displayLocale` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo de locale_get_display_language()

    <?php
    echo locale_get_display_language('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo locale_get_display_language('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo locale_get_display_language('sl-Latn-IT-nedis', 'de');
    ?>

Exemplo #2 Exemplo OO

    <?php
    echo Locale::getDisplayLanguage('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo Locale::getDisplayLanguage('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo Locale::getDisplayLanguage('sl-Latn-IT-nedis', 'de');
    ?>

O exemplo acima produzirá:

    Slovenian;
    slov\xc3\xa8ne;
    Slowenisch

### Veja Também

- locale_get_display_name() - Retorna um nome apropriadamente localizado para a localidade
- locale_get_display_script() - Retorna um nome apropriadamente localizado para o tipo de escrita da localidade
- locale_get_display_region() - Retorna um nome apropriadamente localizado para a região da localidade
- locale_get_display_variant() - Retorna um nome apropriadamente localizado para as variantes da localidade

# Locale::getDisplayName

# locale_get_display_name

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayName -- locale_get_display_name — Retorna um nome apropriadamente localizado para a localidade

### Descrição

Estilo orientado a objetos

public static function Locale::getDisplayName(string `$locale`, ?string `$displayLocale` = `null`): string|false

Estilo procedural

function locale_get_display_name(string `$locale`, ?string `$displayLocale` = `null`): string|false

Retorna um nome apropriadamente localizado para a localidade. Se `locale` for `null`, a localidade padrão é usada.

### Parâmetros

`locale`

  A localidade para a qual o nome será mostrado

`displayLocale`

  Localidade de formatação, opcional

### Valor Retornado

Nome da localidade no formato apropriado para `displayLocale`, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `displayLocale` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo de locale_get_display_name()

    <?php
    echo locale_get_display_name('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo locale_get_display_name('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo locale_get_display_name('sl-Latn-IT-nedis', 'de');
    ?>

Exemplo #2 Exemplo OO

    <?php
    echo Locale::getDisplayName('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo Locale::getDisplayName('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo Locale::getDisplayName('sl-Latn-IT-nedis', 'de');
    ?>

O exemplo acima produzirá:

    Slovenian (Latin, Italy, Natisone dialect);
    slov\xc3\xa8ne (latin, Italie, dialecte de Natisone;
    Slowenisch (Lateinisch, Italien, NEDIS)

### Veja Também

- locale_get_display_language() - Retorna um nome apropriadamente localizado para a língua da localidade
- locale_get_display_script() - Retorna um nome apropriadamente localizado para o tipo de escrita da localidade
- locale_get_display_region() - Retorna um nome apropriadamente localizado para a região da localidade
- locale_get_display_variant() - Retorna um nome apropriadamente localizado para as variantes da localidade

# Locale::getDisplayRegion

# locale_get_display_region

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayRegion -- locale_get_display_region — Retorna um nome apropriadamente localizado para a região da localidade

### Descrição

Estilo orientado a objetos

public static function Locale::getDisplayRegion(string `$locale`, ?string `$displayLocale` = `null`): string|false

Estilo procedural

function locale_get_display_region(string `$locale`, ?string `$displayLocale` = `null`): string|false

Retorna um nome apropriadamente localizado para a região da localidade. Se a localidade for `null`, a padrão é usada.

### Parâmetros

`locale`

  A localidade para a qual será retornada a região

`displayLocale`

  Localidade de formatação, opcional, para mostrar o nome da região

### Valor Retornado

O nome da região para a localidade `locale` no formato apropriado para `displayLocale`, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `displayLocale` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo de locale_get_display_region()

    <?php
    echo locale_get_display_region('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo locale_get_display_region('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo locale_get_display_region('sl-Latn-IT-nedis', 'de');
    ?>

Exemplo #2 Exemplo OO

    <?php
    echo Locale::getDisplayRegion('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo Locale::getDisplayRegion('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo Locale::getDisplayRegion('sl-Latn-IT-nedis', 'de');
    ?>

O exemplo acima produzirá:

    Italy;
    Italie;
    Italien

### Veja Também

- locale_get_display_name() - Retorna um nome apropriadamente localizado para a localidade
- locale_get_display_language() - Retorna um nome apropriadamente localizado para a língua da localidade
- locale_get_display_script() - Retorna um nome apropriadamente localizado para o tipo de escrita da localidade
- locale_get_display_variant() - Retorna um nome apropriadamente localizado para as variantes da localidade

# Locale::getDisplayScript

# locale_get_display_script

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayScript -- locale_get_display_script — Retorna um nome apropriadamente localizado para o tipo de escrita da localidade

### Descrição

Estilo orientado a objetos

public static function Locale::getDisplayScript(string `$locale`, ?string `$displayLocale` = `null`): string|false

Estilo procedural

function locale_get_display_script(string `$locale`, ?string `$displayLocale` = `null`): string|false

Retorna um nome apropriadamente localizado para o tipo de escrita da localidade. Se for `null`, a localidade padrão é usada.

### Parâmetros

`locale`

  A localidade para a qual será retornado o tipo de escrita

`displayLocale`

  Localidade de formatação, opcional, para mostrar o nome do tipo de escrita

### Valor Retornado

Tipo de escrita para a localidade (`locale`) no formato apropriado para `displayLocale`, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `displayLocale` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo de locale_get_display_script()

    <?php
    echo locale_get_display_script('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo locale_get_display_script('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo locale_get_display_script('sl-Latn-IT-nedis', 'de');
    ?>

Exemplo #2 Exemplo OO

    <?php
    echo Locale::getDisplayScript('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo Locale::getDisplayScript('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo Locale::getDisplayScript('sl-Latn-IT-nedis', 'de');
    ?>

O exemplo acima produzirá:

    Latin;
    latin;
    Lateinisch

### Veja Também

- locale_get_display_name() - Retorna um nome apropriadamente localizado para a localidade
- locale_get_display_language() - Retorna um nome apropriadamente localizado para a língua da localidade
- locale_get_display_region() - Retorna um nome apropriadamente localizado para a região da localidade
- locale_get_display_variant() - Retorna um nome apropriadamente localizado para as variantes da localidade

# Locale::getDisplayVariant

# locale_get_display_variant

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayVariant -- locale_get_display_variant — Retorna um nome apropriadamente localizado para as variantes da localidade

### Descrição

Estilo orientado a objetos

public static function Locale::getDisplayVariant(string `$locale`, ?string `$displayLocale` = `null`): string|false

Estilo procedural

function locale_get_display_variant(string `$locale`, ?string `$displayLocale` = `null`): string|false

Retorna um nome apropriadamente localizado para as variantes da localidade. Se for `null`, a localidade padrão será usada.

### Parâmetros

`locale`

  A localidade para a qual será mostrada a variante

`displayLocale`

  Localidade de formatação, opcional, usada para mostrar o nome da variante

### Valor Retornado

Nome da variante para a localidade (`locale`) no formato apropriado para `displayLocale`, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `displayLocale` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo de locale_get_display_variant()

    <?php
    echo locale_get_display_variant('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo locale_get_display_variant('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo locale_get_display_variant('sl-Latn-IT-nedis', 'de');
    ?>

Exemplo #2 Exemplo OO

    <?php
    echo Locale::getDisplayVariant('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo Locale::getDisplayVariant('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo Locale::getDisplayVariant('sl-Latn-IT-nedis', 'de');
    ?>

O exemplo acima produzirá:

    Natisone dialect;
    dialecte de Natisone;
    NEDIS

### Veja Também

- locale_get_display_name() - Retorna um nome apropriadamente localizado para a localidade
- locale_get_display_language() - Retorna um nome apropriadamente localizado para a língua da localidade
- locale_get_display_script() - Retorna um nome apropriadamente localizado para o tipo de escrita da localidade
- locale_get_display_region() - Retorna um nome apropriadamente localizado para a região da localidade

# Locale::getKeywords

# locale_get_keywords

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getKeywords -- locale_get_keywords — Obtém as palavras-chave para a localidade

### Descrição

Estilo orientado a objetos

public static function Locale::getKeywords(string `$locale`): array|false|null

Estilo procedural

function locale_get_keywords(string `$locale`): array|false|null

Obtém as palavras-chave para a localidade.

### Parâmetros

`locale`

  A localidade da qual as palavras-chave serão extraídas

### Valor Retornado

array associativo contendo pares chave-valor para a localidade.

Retorna `null` quando o comprimento de `locale` excede `INTL_MAX_LOCALE_LEN`.

### Exemplos

Exemplo #1 Exemplo de locale_get_keywords()

    <?php
    $keywords_arr = locale_get_keywords('de_DE@currency=EUR;collation=PHONEBOOK');
    if ($keywords_arr) {
        foreach ($keywords_arr as $key => $value) {
            echo "$key = $value\n";
        }
    }
    ?>

Exemplo #2 Exemplo OO

    <?php
    $keywords_arr = Locale::getKeywords('de_DE@currency=EUR;collation=PHONEBOOK');
    if ($keywords_arr) {
        foreach ($keywords_arr as $key => $value) {
            echo "$key = $value\n";
        }
    }
    ?>

O exemplo acima produzirá:

    collation = PHONEBOOK
    currency = EUR

### Veja Também

- locale_get_all_variants() - Obtém as variantes para a localidade

# Locale::getPrimaryLanguage

# locale_get_primary_language

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getPrimaryLanguage -- locale_get_primary_language — Obtém a língua primária para a localidade

### Descrição

Estilo orientado a objetos

public static function Locale::getPrimaryLanguage(string `$locale`): ?string

Estilo procedural

function locale_get_primary_language(string `$locale`): ?string

Obtém a língua primária para a localidade

### Parâmetros

`locale`

  A localidade da qual será extraída a língua primária

### Valor Retornado

O código da língua associada com a localidade.

Retorna `null` quando o comprimento de `locale` excede `INTL_MAX_LOCALE_LEN`.

### Exemplos

Exemplo #1 Exemplo de locale_get_primary_language()

    <?php
    echo locale_get_primary_language('zh-Hant');
    ?>

Exemplo #2 Exemplo OO

    <?php
    echo Locale::getPrimaryLanguage('zh-Hant');
    ?>

O exemplo acima produzirá:

    zh

### Veja Também

- locale_get_script() - Obtém o tipo de escrita para a localidade
- locale_get_region() - Obtém a região para a localidade
- locale_get_all_variants() - Obtém as variantes para a localidade

# Locale::getRegion

# locale_get_region

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getRegion -- locale_get_region — Obtém a região para a localidade

### Descrição

Estilo orientado a objetos

public static function Locale::getRegion(string `$locale`): ?string

Estilo procedural

function locale_get_region(string `$locale`): ?string

Obtém a região para a localidade.

### Parâmetros

`locale`

  A localidade da qual a região será extraída.

### Valor Retornado

A sub-etiqueta da região para a localidade ou `null` se não existir.

Retorna `null` quando o comprimento de `locale` excede `INTL_MAX_LOCALE_LEN`.

### Exemplos

Exemplo #1 Exemplo de locale_get_region()

    <?php
    echo locale_get_region('de-CH-1901');
    ?>

Exemplo #2 Exemplo OO

    <?php
    echo Locale::getRegion('de-CH-1901');
    ?>

O exemplo acima produzirá:

    CH

### Veja Também

- locale_get_primary_language() - Obtém a língua primária para a localidade
- locale_get_script() - Obtém o tipo de escrita para a localidade
- locale_get_all_variants() - Obtém as variantes para a localidade

# Locale::getScript

# locale_get_script

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getScript -- locale_get_script — Obtém o tipo de escrita para a localidade

### Descrição

Estilo orientado a objetos

public static function Locale::getScript(string `$locale`): ?string

Estilo procedural

function locale_get_script(string `$locale`): ?string

Obtém o tipo de escrita para a localidade.

### Parâmetros

`locale`

  A localidade da qual o tipo de escrita será extraído

### Valor Retornado

A sub-etiqueta de tipo de escrita para a localidade ou `null` se não estiver presente.

### Exemplos

Exemplo #1 Exemplo de locale_get_script()

    <?php
    echo locale_get_script('sr-Cyrl');
    ?>

Exemplo #2 Exemplo OO

    <?php
    echo Locale::getScript('sr-Cyrl');
    ?>

O exemplo acima produzirá:

    Cyrl

### Veja Também

- locale_get_primary_language() - Obtém a língua primária para a localidade
- locale_get_region() - Obtém a região para a localidade
- locale_get_all_variants() - Obtém as variantes para a localidade

# Locale::isRightToLeft

(No version information available, might only be in Git)

Locale::isRightToLeft — Verifica se uma localidade usa um sistema de escrita da direita para a esquerda

### Descrição

public static function Locale::isRightToLeft( string `$locale` = "" ): bool

Determina se uma localidade usa um sistema de escrita da direita para a esquerda.

Este método se baseia na biblioteca ICU e avalia a escrita dominante associada à localidade.

Se uma string vazia for informada, a localidade padrão será usada.

### Parâmetros

`locale`
  O identificador de localidade. Se estiver vazio, a localidade padrão será usada.

### Valor Retornado

Retorna `true` se a localidade usa um sistema de escrita da direita para a esquerda ou `false` caso contrário.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | Adicionado o método Locale::isRightToLeft().

### Exemplos

Exemplo #1 Verificando a direção do texto para uma localidade

    <?php

    var_dump(Locale::isRightToLeft('en-US'));
    var_dump(Locale::isRightToLeft('ar'));

O exemplo acima produzirá:

    bool(false)
    bool(true)

# Locale::lookup

# locale_lookup

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::lookup -- locale_lookup — Pesquisa a lista de etiquetas de língua pela melhor correspondência à língua

### Descrição

Estilo orientado a objetos

public static function Locale::lookup(
array `$languageTag`,
string `$locale`,
bool `$canonicalize` = `false`,
?string `$defaultLocale` = `null`
): ?string

Estilo procedural

function locale_lookup(
array `$languageTag`,
string `$locale`,
bool `$canonicalize` = `false`,
?string `$defaultLocale` = `null`
): ?string

Pesquisa os itens em `languageTag` pela melhor correspondência ao intervalo de línguas especificado em `locale` de acordo com o algoritmo de procura da RFC 4647.

### Parâmetros

`languageTag`

  Um array contendo uma lista de etiquetas de língua para comparar a `locale`. Máximo de 100 itens permitidos.

`locale`

  A localidade a ser usada como faixa de línguas na pesquisa.

`canonicalize`

  Se verdedeiro, os argumentos serão convertidos para a forma canônica antes de se fazer a correspondência.

`defaultLocale`

  A localidade a ser usada se nenhuma correspondência for encontrada.

### Valor Retornado

A etiqueta de língua que melhor corresponder ou o valor padrão.

Retorna `null` quando o comprimento de `locale` excede `INTL_MAX_LOCALE_LEN`.

### Registro de Alterações

Versão | Descrição
--- | ---
7.4.0 | `defaultLocale` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo de locale_lookup()

    <?php
    $arr = array(
        'de-DEVA',
        'de-DE-1996',
        'de',
        'de-De'
    );
    echo locale_lookup($arr, 'de-DE-1996-x-prv1-prv2', true, 'en_US');
    ?>

Exemplo #2 Exemplo OO

    <?php
    $arr = array(
        'de-DEVA',
        'de-DE-1996',
        'de',
        'de-De'
    );
    echo Locale::lookup($arr, 'de-DE-1996-x-prv1-prv2', true, 'en_US');
    ?>

O exemplo acima produzirá:

    de_de_1996

### Veja Também

- locale_filter_matches() - Verifica se um filtro de etiqueta de língua corresponde à localidade

# Locale::parseLocale

# locale_parse

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::parseLocale -- locale_parse — Retorna um array de chaves-valores de elementos de sub-etiquetas de ID de localidade

### Descrição

Estilo orientado a objetos

public static function Locale::parseLocale(string `$locale`): ?array

Estilo procedural

function locale_parse(string `$locale`): ?array

Retorna um array de chaves-valores de elementos de sub-etiquetas de ID de localidade.

### Parâmetros

`locale`

  A localidade da qual será extraído o array de sub-etiquetas. Nota: as sub-etiquetas 'variant' e 'private' podem ter no máximo 15 valores enquanto que 'extlang' pode ter no máximo 3 valores.

### Valor Retornado

Retorna um array contendo uma lista de pares de chave-valor, onde as chaves identificam as sub-etiquetas do ID de localidade em particular, e os valores são os associados às sub-etiquetas. O array será ordenado como nas sub-etiquetas do ID de localidade, por exemplo, se as variantes são '-varX-varY-varZ', o array retornado terá variant0=>varX, variant1=>varY, variant2=>varZ.

Retorna `null` quando o comprimento de `locale` exceder `INTL_MAX_LOCALE_LEN`.

### Exemplos

Exemplo #1 Exemplo de locale_parse()

    <?php
    $arr = locale_parse('sl-Latn-IT-nedis');
    if ($arr) {
        foreach ($arr as $key => $value) {
            echo "$key : $value , ";
        }
    }
    ?>

Exemplo #2 Exemplo OO

    <?php
    $arr = Locale::parseLocale('sl-Latn-IT-nedis');
    if ($arr) {
        foreach ($arr as $key => $value) {
            echo "$key : $value , ";
        }
    }
    ?>

O exemplo acima produzirá:

    language : sl , script : Latn , region : IT , variant0 : NEDIS ,

### Veja Também

- locale_compose() - Retorna ID de localidade corretamente ordenado e delimitado

# Locale::setDefault

# locale_set_default

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::setDefault -- locale_set_default — Define a localidade padrão em tempo de execução

### Descrição

Estilo orientado a objetos

public static function Locale::setDefault(string `$locale`): true

Estilo procedural

function locale_set_default(string `$locale`): true

Define a localidade padrão em tempo de execução para `locale`. Isto altera o valor do identificador de localidade global 'default_locale' da extensão INTL. Extensões UAX #35 são aceitas.

### Parâmetros

`locale`

  Uma etiqueta de localidade conforme a BCP 47.

### Valor Retornado

Retorna `true`.

### Exemplos

Exemplo #1 Exemplo de locale_set_default()

    <?php
    locale_set_default('de-DE');
    echo locale_get_default();
    ?>

Exemplo #2 Exemplo OO

    <?php
    Locale::setDefault('de-DE');
    echo Locale::getDefault();
    ?>

O exemplo acima produzirá:

    de-DE

### Veja Também

- locale_get_default() - Obtém o valor de localidade padrão da variável global de INTL 'default_locale'

## Índice

- Locale::acceptFromHttp — Tenta descobrir a melhor localidade disponível baseado no cabeçalho HTTP "Accept-Language"
- Locale::canonicalize — Canoniza a string de localidade
- Locale::composeLocale — Retorna ID de localidade corretamente ordenado e delimitado
- Locale::filterMatches — Verifica se um filtro de etiqueta de língua corresponde à localidade
- Locale::getAllVariants — Obtém as variantes para a localidade
- Locale::getDefault — Obtém o valor de localidade padrão da variável global de INTL 'default_locale'
- Locale::getDisplayLanguage — Retorna um nome apropriadamente localizado para a língua da localidade
- Locale::getDisplayName — Retorna um nome apropriadamente localizado para a localidade
- Locale::getDisplayRegion — Retorna um nome apropriadamente localizado para a região da localidade
- Locale::getDisplayScript — Retorna um nome apropriadamente localizado para o tipo de escrita da localidade
- Locale::getDisplayVariant — Retorna um nome apropriadamente localizado para as variantes da localidade
- Locale::getKeywords — Obtém as palavras-chave para a localidade
- Locale::getPrimaryLanguage — Obtém a língua primária para a localidade
- Locale::getRegion — Obtém a região para a localidade
- Locale::getScript — Obtém o tipo de escrita para a localidade
- Locale::isRightToLeft — Verifica se uma localidade usa um sistema de escrita da direita para a esquerda
- Locale::lookup — Pesquisa a lista de etiquetas de língua pela melhor correspondência à língua
- Locale::parseLocale — Retorna um array de chaves-valores de elementos de sub-etiquetas de ID de localidade
- Locale::setDefault — Define a localidade padrão em tempo de execução

# A classe Normalizer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Introdução

Normalização é um processo que envolve transformar caracteres e sequências de caracteres em uma representação subjacente formalmente definida. Este processo é mais importante quando o texto precisa ser comparado para ordenação e pesquisa, mas também é usado ao armazenar texto para garantir que seja armazenado em uma representação consistente.

O Consórcio Unicode definiu um número de formas de normalização refletindo as várias necessidades das aplicações:

- Forma de Normalização D (NFD) - Decomposição Canônica
- Forma de Normalização C (NFC) - Decomposição Canônica seguida por Composição Canônica
- Forma de Normalização KD (NFKD) - Decomposição de Compatibilidade
- Forma de Normalização KC (NFKC) - Decomposição de Compatibilidade seguida por Composição Canônica

As diferentes formas são definidas em termos de um conjunto de transformações no texto, que são expressas por um algoritmo em por um conjunto de arquivos de dados.

## Resumo da classe

class Normalizer {
/* Constantes */
public const int FORM_D;
public const int NFD;
public const int FORM_KD;
public const int NFKD;
public const int FORM_C;
public const int NFC;
public const int FORM_KC;
public const int NFKC;
public const int FORM_KC_CF;
public const int NFKC_CF;
/* Métodos */
public static function getRawDecomposition(string `$string`, int `$form` = `Normalizer::FORM_C`): ?string
public static function isNormalized(string `$string`, int `$form` = `Normalizer::FORM_C`): bool
public static function normalize(string `$string`, int `$form` = `Normalizer::FORM_C`): string|false
}

## Constantes predefinidas

As seguintes constantes definem a forma de normalização usada pelo normalizador:

`Normalizer::FORM_C` int
  Forma de Normalização C (NFC) - Decomposição Canônica seguida por Composição Canônica
`Normalizer::FORM_D` int
  Forma de Normalização D (NFD) - Decomposição Canônica
`Normalizer::NFD` int

`Normalizer::FORM_KC` int
  Forma de Normalização KC (NFKC) - Decomposição de Compatibilidade, seguida por Composição Canônica
`Normalizer::NFKC` int

`Normalizer::FORM_KC_CF` int

`Normalizer::FORM_KD` int
  Forma de Normalização KD (NFKD) - Decomposição de Compatibilidade
`Normalizer::NFKD` int

`Normalizer::NFC` int

`Normalizer::NFKC_CF` int

## Veja Também

- » Normalização Unicode
- » Perguntas Frequentes sobre Normalização Unicode
- » Guia do Usuário ICU - Normalização
- » Referência da API ICU - Normalização

## Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | As constantes de classe agora são tipadas.
8.0.0 | `Normalizer::NONE` foi removida.

# Normalizer::getRawDecomposition

# normalizer_get_raw_decomposition

(PHP 7 >= 7.3, PHP 8)

Normalizer::getRawDecomposition -- normalizer_get_raw_decomposition — Obtém a propriedade Decomposition_Mapping para o ponto de código UTF-8 fornecido

### Descrição

Estilo orientado a objetos

public static function Normalizer::getRawDecomposition(string `$string`, int `$form` = `Normalizer::FORM_C`): ?string

Estilo procedural

function normalizer_get_raw_decomposition(string `$string`, int `$form` = `Normalizer::FORM_C`): ?string

Obtém a propriedade Decomposition_Mapping, como especificada no Banco de Dados de Caracteres Unicode (UCD), para o ponto de código fornecido, codificado em UTF-8.

### Parâmetros

`string`

  A string de entrada, que deve ser um único ponto de código, codificado em UTF-8.

### Valor Retornado

Retorna uma string contendo a propriedade Decomposition_Mapping, caso presente na UCD.

Retorna `null` se não houver propriedade Decomposition_Mapping para o caractere.

### Exemplos

Exemplo #1 Exemplo de Normalizer::getRawDecomposition()

    <?php

    $result = "";
    $strings = [
        "a",
        "\u{FFDA}",
        "\u{FDFA}",
        "",
        "aa",
        "\xF5",
    ];

    foreach ($strings as $string) {
        $decomposition = Normalizer::getRawDecomposition($string);
        // $decomposition = normalizer_get_raw_decomposition($string); Modo procedural

        $error_code = intl_get_error_code();
        $error_message = intl_get_error_message();

        $string_hex = bin2hex($string);
        $result .= "---------------------\n";

        if ($decomposition === null) {
            $result .= "'$string_hex' não tem mapeamento de decomposição\n" ;
        } else {
            $result .= "'$string_hex' tem o mapeamento de decomposição '" . bin2hex($decomposition) . "'\n" ;
        }

        $result .= "informação de erro: '$error_message' ($error_code)\n";
    }

    echo $result;
    ?>

O exemplo acima produzirá:

    ---------------------
    '61' não tem mapeamento de decomposição
    informação de erro: 'U_ZERO_ERROR' (0)
    ---------------------
    'efbf9a' tem o mapeamento de decomposição 'e385a1'
    informação de erro: 'U_ZERO_ERROR' (0)
    ---------------------
    'efb7ba' tem o mapeamento de decomposição 'd8b5d984d98920d8a7d984d984d98720d8b9d984d98ad98720d988d8b3d984d985'
    informação de erro: 'U_ZERO_ERROR' (0)
    ---------------------
    '' não tem mapeamento de decomposição
    informação de erro: 'Input string must be exactly one UTF-8 encoded code point long.: U_ILLEGAL_ARGUMENT_ERROR' (1)
    ---------------------
    '6161' não tem mapeamento de decomposição
    informação de erro: 'Input string must be exactly one UTF-8 encoded code point long.: U_ILLEGAL_ARGUMENT_ERROR' (1)
    ---------------------
    'f5' não tem mapeamento de decomposição
    informação de erro: 'Code point out of range: U_ILLEGAL_ARGUMENT_ERROR' (1)

### Veja Também

- Normalizer::normalize() - Normaliza a entrada fornecida e retorna a string normalizada
- Normalizer::isNormalized() - Verifica se a string fornecida já está normalizada na forma especificada.

# Normalizer::isNormalized

# normalizer_is_normalized

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Normalizer::isNormalized -- normalizer_is_normalized — Verifica se a string fornecida já está normalizada na forma especificada.

### Descrição

Estilo orientado a objetos

public static function Normalizer::isNormalized(string `$string`, int `$form` = `Normalizer::FORM_C`): bool

Estilo procedural

function normalizer_is_normalized(string `$string`, int `$form` = `Normalizer::FORM_C`): bool

Verifica se a string fornecida já está normalizada na forma especificada.

### Parâmetros

`string`

  A string de entrada para verificar a normalização

`form`

  Uma das formas de normalização.

### Valor Retornado

`true` se a string estiver normalizada, `false` caso contrário ou se houver um erro

### Exemplos

Exemplo #1 Exemplo de normalizer_is_normalized()

    <?php
    $char_A_ring = "\xC3\x85"; // 'LATIN CAPITAL LETTER A WITH RING ABOVE' (U+00C5)
    $char_combining_ring_above = "\xCC\x8A";  // 'COMBINING RING ABOVE' (U+030A)

    $char_orig = 'A' . $char_combining_ring_above;
    $char_norm = normalizer_normalize( 'A' . $char_combining_ring_above, Normalizer::FORM_C );

    echo ( normalizer_is_normalized($char_orig, Normalizer::FORM_C) ) ? "normalized" : "not normalized";
    echo '; ';
    echo ( normalizer_is_normalized($char_norm, Normalizer::FORM_C) ) ? "normalized" : "not normalized";
    ?>

Exemplo #2 Exemplo orientado a objetos

    <?php
    $char_A_ring = "\xC3\x85"; // 'LATIN CAPITAL LETTER A WITH RING ABOVE' (U+00C5)
    $char_combining_ring_above = "\xCC\x8A";  // 'COMBINING RING ABOVE' (U+030A)

    $char_orig = 'A' . $char_combining_ring_above;
    $char_norm = Normalizer::normalize( 'A' . $char_combining_ring_above, Normalizer::FORM_C );

    echo ( Normalizer::isNormalized($char_orig, Normalizer::FORM_C) ) ? "normalized" : "not normalized";
    echo '; ';
    echo ( Normalizer::isNormalized($char_norm, Normalizer::FORM_C) ) ? "normalized" : "not normalized";
    ?>

O exemplo acima produzirá:

    not normalized; normalized

### Veja Também

- normalizer_normalize() - Normaliza a entrada fornecida e retorna a string normalizada

# Normalizer::normalize

# normalizer_normalize

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Normalizer::normalize -- normalizer_normalize — Normaliza a entrada fornecida e retorna a string normalizada

### Descrição

Estilo orientado a objetos

public static function Normalizer::normalize(string `$string`, int `$form` = `Normalizer::FORM_C`): string|false

Estilo procedural

function normalizer_normalize(string `$string`, int `$form` = `Normalizer::FORM_C`): string|false

Normaliza a entrada fornecida e retorna a string normalizada

### Parâmetros

`string`

  A string de entrada a ser normalizada

`form`

  Uma das formas de normalização.

### Valor Retornado

A string normalizada ou `false` se ocorrer um erro.

### Exemplos

Exemplo #1 Exemplo de normalizer_normalize()

    <?php
    $char_A_ring = "\xC3\x85"; // 'LATIN CAPITAL LETTER A WITH RING ABOVE' (U+00C5)
    $char_combining_ring_above = "\xCC\x8A";  // 'COMBINING RING ABOVE' (U+030A)

    $char_1 = normalizer_normalize( $char_A_ring, Normalizer::FORM_C );
    $char_2 = normalizer_normalize( 'A' . $char_combining_ring_above, Normalizer::FORM_C );

    echo urlencode($char_1);
    echo ' ';
    echo urlencode($char_2);
    ?>

Exemplo #2 Exemplo orientado a objetos

    <?php
    $char_A_ring = "\xC3\x85"; // 'LATIN CAPITAL LETTER A WITH RING ABOVE' (U+00C5)
    $char_combining_ring_above = "\xCC\x8A";  // 'COMBINING RING ABOVE' (U+030A)

    $char_1 = Normalizer::normalize( $char_A_ring, Normalizer::FORM_C );
    $char_2 = Normalizer::normalize( 'A' . $char_combining_ring_above, Normalizer::FORM_C );

    echo urlencode($char_1);
    echo ' ';
    echo urlencode($char_2);
    ?>

O exemplo acima produzirá:

    %C3%85 %C3%85

### Veja Também

- normalizer_is_normalized() - Verifica se a string fornecida já está normalizada na forma especificada.

## Índice

- Normalizer::getRawDecomposition — Obtém a propriedade Decomposition_Mapping para o ponto de código UTF-8 fornecido
- Normalizer::isNormalized — Verifica se a string fornecida já está normalizada na forma especificada.
- Normalizer::normalize — Normaliza a entrada fornecida e retorna a string normalizada

# A classe MessageFormatter

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Introdução

MessageFormatter é uma classe concreta que permite aos usuários produzir mensagens concatenadas, neutras do ponto de vista da língua. Os métodos fornecido nesta classe são usados para construir todas as mensagens que são vistas pelos usuários finais.

A classe MessageFormatter monta mensagens a partir de vários fragmentos (como fragmentos de texto, números e datas) fornecidos pelo programa. Por causa da classe MessageFormatter, o programa não precisa saber a ordem dos fragmentos. A classe usa as especificações de formatação para os fragmentos para montá-los em uma mensagem que fica contida em uma única string dentro de um pacote de recurso. Por exemplo, MessageFormatter permite mostrar a frase "Concluída a impressão de x arquivos em um total de y..." de uma maneira que ainda permita flexibilidade na tradução.

Anteriormente, uma mensagem para o usuário final era criada como uma frase e manipulada como uma string. Este procedimento criava problemas para localizadores porque a estrutura da frase, ordem de palavras, formato de números e outros mais são muito diferentes de língua para língua. A maneira neutra de criar mensagens mantém cada parte da mensagem separada e fornece chaves para os dados. Usando estas chaves, a classe MessageFormatter pode concatenar as partes da mensagem, localizá-las, e monstrar uma string bem formada ao usuário final.

MessageFormatter toma um conjunto de objetos, formata-os, e depois insere as strings formatadas no modelo nos locais apropriados. Formatos de escolha podem ser usados em conjunto com MessageFormatter para manipular plurais, fazer correspondência de números, e fazer seleção a partir de um array de itens. Tipicamente, o formato da mensagem virá de recursos e os argumentos serão definidos dinamicamente em tempo de execução.

## Resumo da classe

class MessageFormatter {
/* Métodos */
public function __construct(string `$locale`, string `$pattern`)
public static function create(string `$locale`, string `$pattern`): ?MessageFormatter
public function format(array `$values`): string|false
public static function formatMessage(string `$locale`, string `$pattern`, array `$values`): string|false
public function getErrorCode(): int
public function getErrorMessage(): string
public function getLocale(): string
public function getPattern(): string|false
public function parse(string `$string`): array|false
public static function parseMessage(string `$locale`, string `$pattern`, string `$message`): array|false
public function setPattern(string `$pattern`): bool
}

## Veja Também

- » Documentação de formatação ICU
- » Descrição de formatação de mensagens ICU
- » Formatadores de mensagem ICU
- » Formatadores de escolha ICU

# MessageFormatter::create

# MessageFormatter::__construct

# msgfmt_create

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::create -- MessageFormatter::__construct -- msgfmt_create — Constrói um novo formatador de mensagem

### Descrição

Estilo orientado a objetos (method)

public static function MessageFormatter::create(string `$locale`, string `$pattern`): ?MessageFormatter

Estilo orientado a objetos (construtor):

public function MessageFormatter::__construct(string `$locale`, string `$pattern`)

Estilo procedural

function msgfmt_create(string `$locale`, string `$pattern`): ?MessageFormatter

Constrói um novo formatador de mensagem.

### Parâmetros

`locale`

  A localidade a ser utilizada ao formatar argumentos

`pattern`

  A string com o modelo para formatar os argumentos. O modelo usa uma sintaxe adequada para tratar apóstrofos/aspas; consulte » Aspas/Escape para detalhes.

### Valor Retornado

O formatador do tipo object, ou `null` em caso de falha.

### Erros/Exceções

Quando invocado como construtor, em caso de falha uma exceção IntlException é lançada.

### Exemplos

Exemplo #1 Exemplo de msgfmt_create()

    <?php
    $fmt = msgfmt_create("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
    echo msgfmt_format($fmt, array(4560, 123, 4560/123));
    $fmt = msgfmt_create("de", "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum");
    echo msgfmt_format($fmt, array(4560, 123, 4560/123));
    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new MessageFormatter("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
    echo $fmt->format(array(4560, 123, 4560/123));
    $fmt = new MessageFormatter("de", "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum");
    echo $fmt->format(array(4560, 123, 4560/123));
    ?>

O exemplo acima produzirá:

    4,560 monkeys on 123 trees make 37.073 monkeys per tree
    4.560 Affen auf 123 Bäumen sind 37,073 Affen pro Baum

### Veja Também

- msgfmt_format() - Formata a mensagem
- msgfmt_parse() - Interpreta a string de entrada de acordo com o modelo
- msgfmt_get_error_code() - Obtém o código de erro da última operação
- msgfmt_get_error_message() - Obtém o texto do erro da última operação

# MessageFormatter::format

# msgfmt_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::format -- msgfmt_format — Formata a mensagem

### Descrição

Estilo orientado a objetos

public function MessageFormatter::format(array `$values`): string|false

Estilo procedural

function msgfmt_format(MessageFormatter `$formatter`, array `$values`): string|false

Formata a mensagem substituindo os dados na string de formato de acordo com as regras da localidade.

### Parâmetros

`formatter`

  O formatador de mensagem

`values`

  Argumentos a inserir na string de formato

### Valor Retornado

A string formatada, ou `false` se ocorrer um erro.

### Exemplos

Exemplo #1 Exemplo de msgfmt_format()

    <?php
    $fmt = msgfmt_create("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
    echo msgfmt_format($fmt, array(4560, 123, 4560/123));
    $fmt = msgfmt_create("de", "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum");
    echo msgfmt_format($fmt, array(4560, 123, 4560/123));
    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new MessageFormatter("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
    echo $fmt->format(array(4560, 123, 4560/123));
    $fmt = new MessageFormatter("de", "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum");
    echo $fmt->format(array(4560, 123, 4560/123));
    ?>

O exemplo acima produzirá:

    4,560 monkeys on 123 trees make 37.073 monkeys per tree
    4.560 Affen auf 123 Bäumen sind 37,073 Affen pro Baum

### Veja Também

- msgfmt_create() - Constrói um novo formatador de mensagem
- msgfmt_parse() - Interpreta a string de entrada de acordo com o modelo
- msgfmt_format_message() - Formata uma mensagem rapidamente
- msgfmt_get_error_code() - Obtém o código de erro da última operação
- msgfmt_get_error_message() - Obtém o texto do erro da última operação

# MessageFormatter::formatMessage

# msgfmt_format_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::formatMessage -- msgfmt_format_message — Formata uma mensagem rapidamente

### Descrição

Estilo orientado a objetos

public static function MessageFormatter::formatMessage(string `$locale`, string `$pattern`, array `$values`): string|false

Estilo procedural

function msgfmt_format_message(string `$locale`, string `$pattern`, array `$values`): string|false

Função de formatação rápida que não precisa criar explicitamente o objeto formatador. Use esta função quando a operação de formatação for feita apenas uma vez, não precisar de parâmetros, não precisar manter estados ou quando for desejado customizar a saída fornecendo contexto adicional diretamente à ICU.

### Parâmetros

`locale`

  A localidade a ser utilizada para formatar as partes que dependem dela.

`pattern`

  A string com o modelo para inserir os valores. O modelo usa uma sintaxe adequada para tratar apóstrofos/aspas; consulte » Aspas/Escape para detalhes.

`values`

  O array de valores a inserir na string do modelo.

### Valor Retornado

A string formatada de acordo com o modelo ou `false` se ocorrer um erro.

### Exemplos

Exemplo #1 Exemplo de msgfmt_format_message()

    <?php
    echo msgfmt_format_message("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree\n", array(4560, 123, 4560/123));
    echo msgfmt_format_message("de", "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum\n", array(4560, 123, 4560/123));
    echo msgfmt_format_message("en", 'You finished {place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}!', ['place' => 3]), "\n";
    echo msgfmt_format_message("en",
            "There {apple, plural,
                =0 {are no apples}
                =1 {is one apple...}
                other {are # apples!}
            }",
        ['apple' => 0]
    ), "\n";

Exemplo #2 Exemplo orientado a objeto

    <?php
    echo MessageFormatter::formatMessage("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree\n", array(4560, 123, 4560/123));
    echo MessageFormatter::formatMessage("de", "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum\n", array(4560, 123, 4560/123));
    echo MessageFormatter::formatMessage("en", 'You finished {place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}!', ['place' => 3]), "\n";
    echo MessageFormatter::formatMessage("en",
            "There {apple, plural,
                =0 {are no apples}
                =1 {is one apple...}
                other {are # apples!}
            }",
        ['apple' => 0]
    ), "\n";

O exemplo acima produzirá:

    4,560 monkeys on 123 trees make 37.073 monkeys per tree
    4.560 Affen auf 123 Bäumen sind 37,073 Affen pro Baum
    You finished 3rd!
    There are no apples

Exemplo #3 Instruindo a ICU a formatar moeda com símbolo normal e símbolo abreviado

Requer a ICU ≥ 67.

    <?php
    echo msgfmt_format_message("cs_CZ", "{0, number, :: currency/CAD}", array(123.45));
    echo msgfmt_format_message("cs_CZ", "{0, number, :: currency/CAD unit-width-narrow}", array(123.45));

O exemplo acima produzirá:

    123,45 CA$
    123,45 $

### Veja Também

- msgfmt_create() - Constrói um novo formatador de mensagem
- msgfmt_parse() - Interpreta a string de entrada de acordo com o modelo
- msgfmt_get_error_code() - Obtém o código de erro da última operação
- msgfmt_get_error_message() - Obtém o texto do erro da última operação

# MessageFormatter::getErrorCode

# msgfmt_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::getErrorCode -- msgfmt_get_error_code — Obtém o código de erro da última operação

### Descrição

Estilo orientado a objetos

public function MessageFormatter::getErrorCode(): int

Estilo procedural

function msgfmt_get_error_code(MessageFormatter `$formatter`): int

Obtém o código de erro da última operação.

### Parâmetros

`formatter`

  O formatador de mensagem

### Valor Retornado

O código de erro, um dos valores UErrorCode. O valor inicial (sem erro) é U_ZERO_ERROR.

### Veja Também

- msgfmt_get_error_message() - Obtém o texto do erro da última operação
- intl_get_error_code() - Obtém o último código de erro
- intl_is_failure() - Verifica se o código de erro fornecido indica falha

# MessageFormatter::getErrorMessage

# msgfmt_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::getErrorMessage -- msgfmt_get_error_message — Obtém o texto do erro da última operação

### Descrição

Estilo orientado a objetos

public function MessageFormatter::getErrorMessage(): string

Estilo procedural

function msgfmt_get_error_message(MessageFormatter `$formatter`): string

Obtém o texto do erro da última operação.

### Parâmetros

`formatter`

  O formatador de mensagem

### Valor Retornado

A descrição do último erro.

### Exemplos

Exemplo #1 Exemplo de msgfmt_get_error_message()

    <?php
    $fmt = msgfmt_create("en_US", "{0, number} monkeys on {1, number} trees");
    $str = msgfmt_format($fmt, array());
    if(!$str) {
        echo "ERROR: ".msgfmt_get_error_message($fmt) . " (" . msgfmt_get_error_code($fmt) . ")\n";
    }
    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new MessageFormatter("en_US", "{0, number} monkeys on {1, number} trees");
    $str = $fmt->format(array());
    if(!$str) {
        echo "ERROR: ".$fmt->getErrorMessage() . " (" . $fmt->getErrorCode() . ")\n";
    }
    ?>

O exemplo acima produzirá:

    ERROR: msgfmt_format: not enough parameters: U_ILLEGAL_ARGUMENT_ERROR (1)

### Veja Também

- msgfmt_get_error_code() - Obtém o código de erro da última operação
- intl_get_error_code() - Obtém o último código de erro
- intl_is_failure() - Verifica se o código de erro fornecido indica falha

# MessageFormatter::getLocale

# msgfmt_get_locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::getLocale -- msgfmt_get_locale — Obtém a localidade para a qual o formatador foi criado

### Descrição

Estilo orientado a objetos

public function MessageFormatter::getLocale(): string

Estilo procedural

function msgfmt_get_locale(MessageFormatter `$formatter`): string

Obtém a localidade para a qual o formatador foi criado.

### Parâmetros

`formatter`

  O formatador de mensagem

### Valor Retornado

O nome da localidade.

### Exemplos

Exemplo #1 Exemplo de msgfmt_get_locale()

    <?php
    $fmt = msgfmt_create('en_US', "Number {0,number}");
    echo msgfmt_get_locale($fmt);
    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new MessageFormatter('en_US', "Number {0,number}");
    echo $fmt->getLocale();
    ?>

O exemplo acima produzirá:

    en_US

### Veja Também

- msgfmt_create() - Constrói um novo formatador de mensagem

# MessageFormatter::getPattern

# msgfmt_get_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::getPattern -- msgfmt_get_pattern — Obtém o modelo usado pelo formatador

### Descrição

Estilo orientado a objetos

public function MessageFormatter::getPattern(): string|false

Estilo procedural

function msgfmt_get_pattern(MessageFormatter `$formatter`): string|false

Obtém o modelo usado pelo formatador.

### Parâmetros

`formatter`

  O formatador de mensagem

### Valor Retornado

A string de modelo usada para o formatador de mensagem, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de msgfmt_get_pattern()

    <?php
    $fmt = msgfmt_create( "en_US", "{0, number} monkeys on {1, number} trees" );
    echo "Modelo atual: '" . msgfmt_get_pattern( $fmt ) . "'\n";
    echo "Resultado da formatação: " . msgfmt_format( $fmt, array(123, 456) ) . "\n";

    msgfmt_set_pattern( $fmt, "{0, number} trees hosting {1, number} monkeys" );
    echo "Novo modelo: '" . msgfmt_get_pattern( $fmt ) . "'\n";
    echo "Número formatado: " . msgfmt_format( $fmt, array(123, 456) ) . "\n";
    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new MessageFormatter( "en_US", "{0, number} monkeys on {1, number} trees" );
    echo "Modelo atual: '" . $fmt->getPattern() . "'\n";
    echo "Resultado da formatação: " . $fmt->format(array(123, 456)) . "\n";

    $fmt->setPattern("{0, number} trees hosting {1, number} monkeys" );
    echo "Novo modelo: '" . $fmt->getPattern() . "'\n";
    echo "Número formatado: " . $fmt->format(array(123, 456)) . "\n";
    ?>

O exemplo acima produzirá:

    Modelo atual: '{0,number} monkeys on {1,number} trees'
    Resultado da formatação: 123 monkeys on 456 trees
    Novo modelo: '{0,number} trees hosting {1,number} monkeys'
    Número formatado: 123 trees hosting 456 monkeys

### Veja Também

- msgfmt_create() - Constrói um novo formatador de mensagem
- msgfmt_set_pattern() - Define o modelo usado pelo formatador

# MessageFormatter::parse

# msgfmt_parse

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::parse -- msgfmt_parse — Interpreta a string de entrada de acordo com o modelo

### Descrição

Estilo orientado a objetos

public function MessageFormatter::parse(string `$string`): array|false

Estilo procedural

function msgfmt_parse(MessageFormatter `$formatter`, string `$string`): array|false

Interpreta a string de entrada e retorna os itens extraídos como um array.

### Parâmetros

`formatter`

  O formatador de mensagem

`string`

  A string a ser interpretada

### Valor Retornado

Um array contendo os itens extraídos, ou `false` em caso de erro.

### Exemplos

Exemplo #1 Exemplo de msgfmt_parse()

    <?php
    $fmt = msgfmt_create('en_US', "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
    $res = msgfmt_parse($fmt, "4,560 monkeys on 123 trees make 37.073 monkeys per tree");
    var_export($res);

    $fmt = msgfmt_create('de', "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum");
    $res = msgfmt_parse($fmt, "4.560 Affen auf 123 Bäumen sind 37,073 Affen pro Baum");
    var_export($res);
    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new MessageFormatter('en_US', "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
    $res = $fmt->parse("4,560 monkeys on 123 trees make 37.073 monkeys per tree");
    var_export($res);

    $fmt = new MessageFormatter('de', "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum");
    $res = $fmt->parse("4.560 Affen auf 123 Bäumen sind 37,073 Affen pro Baum");
    var_export($res);
    ?>

O exemplo acima produzirá:

    array (
      0 => 4560,
      1 => 123,
      2 => 37.073,
    )
    array (
      0 => 4560,
      1 => 123,
      2 => 37.073,
    )

### Veja Também

- msgfmt_create() - Constrói um novo formatador de mensagem
- msgfmt_format() - Formata a mensagem
- msgfmt_parse_message() - Interpreta rapidamente a string de entrada

# MessageFormatter::parseMessage

# msgfmt_parse_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::parseMessage -- msgfmt_parse_message — Interpreta rapidamente a string de entrada

### Descrição

Estilo orientado a objetos

public static function MessageFormatter::parseMessage(string `$locale`, string `$pattern`, string `$message`): array|false

Estilo procedural

function msgfmt_parse_message(string `$locale`, string `$pattern`, string `$message`): array|false

Interpreta a string de entrada sem criar explicitamente o objeto formatador. Use esta função quando a operação de formatação é feita apenas uma vez e não precisa de parâmetros ou de manter estados.

### Parâmetros

`locale`

  A localidade a ser usada para interpretação das partes que dependem dela.

`pattern`

  O modelo com o qual o parâmetro `message` será interpretado.

`message`

  A string a ser interpretada, conforme definido em `pattern`.

### Valor Retornado

Um array contendo os itens extraídos, ou `false` em caso de erro.

### Exemplos

Exemplo #1 Exemplo de msgfmt_parse_message()

    <?php
    $fmt = msgfmt_parse_message('en_US', "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree",
                                "4,560 monkeys on 123 trees make 37.073 monkeys per tree");
    var_export($fmt);

    $fmt = msgfmt_parse_message('de', "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum",
                                "4.560 Affen auf 123 Bäumen sind 37,073 Affen pro Baum");
    var_export($fmt);
    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = MessageFormatter::parseMessage('en_US', "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree",
                                "4,560 monkeys on 123 trees make 37.073 monkeys per tree");
    var_export($fmt);

    $fmt = MessageFormatter::parseMessage('de', "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum",
                                "4.560 Affen auf 123 Bäumen sind 37,073 Affen pro Baum");
    var_export($fmt);
    ?>

O exemplo acima produzirá:

    array (
      0 => 4560,
      1 => 123,
      2 => 37.073,
    )
    array (
      0 => 4560,
      1 => 123,
      2 => 37.073,
    )

### Veja Também

- msgfmt_create() - Constrói um novo formatador de mensagem
- msgfmt_format_message() - Formata uma mensagem rapidamente
- msgfmt_parse() - Interpreta a string de entrada de acordo com o modelo

# MessageFormatter::setPattern

# msgfmt_set_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::setPattern -- msgfmt_set_pattern — Define o modelo usado pelo formatador

### Descrição

Estilo orientado a objetos

public function MessageFormatter::setPattern(string `$pattern`): bool

Estilo procedural

function msgfmt_set_pattern(MessageFormatter `$formatter`, string `$pattern`): bool

Define o modelo a ser usado pelo formatador.

### Parâmetros

`formatter`

  O formatador de mensagem

`pattern`

  A string com o modelo a ser usado no formatador. O modelo usa uma sintaxe adequada para tratar apóstrofos/aspas; consulte » Aspas/Escape para detalhes.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de msgfmt_set_pattern()

    <?php
    $fmt = msgfmt_create( "en_US", "{0, number} monkeys on {1, number} trees" );
    echo "Modelo atual: '" . msgfmt_get_pattern( $fmt ) . "'\n";
    echo "Resultado da formatação: " . msgfmt_format( $fmt, array(123, 456) ) . "\n";

    msgfmt_set_pattern( $fmt, "{0, number} trees hosting {1, number} monkeys" );
    echo "Novo modelo: '" . msgfmt_get_pattern( $fmt ) . "'\n";
    echo "Número formatado: " . msgfmt_format( $fmt, array(123, 456) ) . "\n";
    ?>

Exemplo #2 Exemplo orientado a objeto

    <?php
    $fmt = new MessageFormatter( "en_US", "{0, number} monkeys on {1, number} trees" );
    echo "Modelo atual: '" . $fmt->getPattern() . "'\n";
    echo "Resultado da formatação: " . $fmt->format(array(123, 456)) . "\n";

    $fmt->setPattern("{0, number} trees hosting {1, number} monkeys" );
    echo "Novo modelo: '" . $fmt->getPattern() . "'\n";
    echo "Número formatado: " . $fmt->format(array(123, 456)) . "\n";
    ?>

O exemplo acima produzirá:

    Modelo atual: '{0,number} monkeys on {1,number} trees'
    Resultado da formatação: 123 monkeys on 456 trees
    Novo modelo: '{0,number} trees hosting {1,number} monkeys'
    Número formatado: 123 trees hosting 456 monkeys

### Veja Também

- msgfmt_create() - Constrói um novo formatador de mensagem
- msgfmt_get_pattern() - Obtém o modelo usado pelo formatador

## Índice

- MessageFormatter::create — Constrói um novo formatador de mensagem
- MessageFormatter::format — Formata a mensagem
- MessageFormatter::formatMessage — Formata uma mensagem rapidamente
- MessageFormatter::getErrorCode — Obtém o código de erro da última operação
- MessageFormatter::getErrorMessage — Obtém o texto do erro da última operação
- MessageFormatter::getLocale — Obtém a localidade para a qual o formatador foi criado
- MessageFormatter::getPattern — Obtém o modelo usado pelo formatador
- MessageFormatter::parse — Interpreta a string de entrada de acordo com o modelo
- MessageFormatter::parseMessage — Interpreta rapidamente a string de entrada
- MessageFormatter::setPattern — Define o modelo usado pelo formatador

# A classe IntlCalendar

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

## Introdução

## Resumo da classe

class IntlCalendar {
/* Constantes */
public const int FIELD_ERA;
public const int FIELD_YEAR;
public const int FIELD_MONTH;
public const int FIELD_WEEK_OF_YEAR;
public const int FIELD_WEEK_OF_MONTH;
public const int FIELD_DATE;
public const int FIELD_DAY_OF_YEAR;
public const int FIELD_DAY_OF_WEEK;
public const int FIELD_DAY_OF_WEEK_IN_MONTH;
public const int FIELD_AM_PM;
public const int FIELD_HOUR;
public const int FIELD_HOUR_OF_DAY;
public const int FIELD_MINUTE;
public const int FIELD_SECOND;
public const int FIELD_MILLISECOND;
public const int FIELD_ZONE_OFFSET;
public const int FIELD_DST_OFFSET;
public const int FIELD_YEAR_WOY;
public const int FIELD_DOW_LOCAL;
public const int FIELD_EXTENDED_YEAR;
public const int FIELD_JULIAN_DAY;
public const int FIELD_MILLISECONDS_IN_DAY;
public const int FIELD_IS_LEAP_MONTH;
public const int FIELD_FIELD_COUNT;
public const int FIELD_DAY_OF_MONTH;
public const int DOW_SUNDAY;
public const int DOW_MONDAY;
public const int DOW_TUESDAY;
public const int DOW_WEDNESDAY;
public const int DOW_THURSDAY;
public const int DOW_FRIDAY;
public const int DOW_SATURDAY;
public const int DOW_TYPE_WEEKDAY;
public const int DOW_TYPE_WEEKEND;
public const int DOW_TYPE_WEEKEND_OFFSET;
public const int DOW_TYPE_WEEKEND_CEASE;
public const int WALLTIME_FIRST;
public const int WALLTIME_LAST;
public const int WALLTIME_NEXT_VALID;
/* Métodos */
private function __construct()
public function add(int `$field`, int `$value`): bool
public function after(IntlCalendar `$other`): bool
public function before(IntlCalendar `$other`): bool
public function clear(?int `$field` = `null`): true
public static function createInstance(IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`, ?string `$locale` = `null`): ?IntlCalendar
public function equals(IntlCalendar `$other`): bool
public function fieldDifference(float `$timestamp`, int `$field`): int|false
public static function fromDateTime(DateTime|string `$datetime`, ?string `$locale` = `null`): ?IntlCalendar
public function get(int `$field`): int|false
public function getActualMaximum(int `$field`): int|false
public function getActualMinimum(int `$field`): int|false
public static function getAvailableLocales(): array
public function getDayOfWeekType(int `$dayOfWeek`): int|false
public function getErrorCode(): int|false
public function getErrorMessage(): string|false
public function getFirstDayOfWeek(): int|false
public function getGreatestMinimum(int `$field`): int|false
public static function getKeywordValuesForLocale(string `$keyword`, string `$locale`, bool `$onlyCommon`): IntlIterator|false
public function getLeastMaximum(int `$field`): int|false
public function getLocale(int `$type`): string|false
public function getMaximum(int `$field`): int|false
public function getMinimalDaysInFirstWeek(): int|false
public function getMinimum(int `$field`): int|false
public static function getNow(): float
public function getRepeatedWallTimeOption(): int
public function getSkippedWallTimeOption(): int
public function getTime(): float|false
public function getTimeZone(): IntlTimeZone|false
public function getType(): string
public function getWeekendTransition(int `$dayOfWeek`): int|false
public function inDaylightTime(): bool
public function isEquivalentTo(IntlCalendar `$other`): bool
public function isLenient(): bool
public function isSet(int `$field`): bool
public function isWeekend(?float `$timestamp` = `null`): bool
public function roll(int `$field`, int|bool `$value`): bool
public function set(int `$field`, int `$value`): true
public function set(
int `$year`,
int `$month`,
int `$dayOfMonth` = NULL,
int `$hour` = NULL,
int `$minute` = NULL,
int `$second` = NULL
): true
public function setDate(int `$year`, int `$month`, int `$dayOfMonth`): void
public function setDateTime(
int `$year`,
int `$month`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
?int `$second` = `null`
): void
public function setFirstDayOfWeek(int `$dayOfWeek`): true
public function setLenient(bool `$lenient`): true
public function setMinimalDaysInFirstWeek(int `$days`): true
public function setRepeatedWallTimeOption(int `$option`): true
public function setSkippedWallTimeOption(int `$option`): true
public function setTime(float `$timestamp`): bool
public function setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool
public function toDateTime(): DateTime|false
}

## Constantes predefinidas

`IntlCalendar::FIELD_ERA` int

  Campo de calendário que representa uma era numericamente, por exemplo `1` para DC e `0` para AC nos calendários gregorianos/julianos e `235` para a era Heisei (平成) no calendário japonês. Nem todos os calendários têm mais de uma era.

`IntlCalendar::FIELD_YEAR` int

  Campo de calendário para o ano. Isto não é único através das eras. Se o tipo do calendário tem mais que uma era, geralmente o valor mínimo para este campo será `1`.

`IntlCalendar::FIELD_MONTH` int

  Campo de calendário para o mês. A sequência de meses é baseada em zero, portanto janeiro (aqui usado com o significado do primeiro mês do calendário; mas pode ser chamado outro nome, como Moarrão no calendário islâmico) é representado por `0`, fevereiro por `1`, …, dezembro por `11` e, para calendários que o têm, o 13º ou mês adicional por `12`.

`IntlCalendar::FIELD_WEEK_OF_YEAR` int

  Campo de calendário para o número da semana no ano. Isto depende de que dia da semana é definido para começar a semana e o número mínimo de dias em uma semana.

`IntlCalendar::FIELD_WEEK_OF_MONTH` int

  Campo de calendário para o número da semana no mês. Isto depende de que dia da semana é definido para começar a semana e o número mínimo de dias em uma semana.

`IntlCalendar::FIELD_DATE` int

  Campo de calendário para o dia do mês. O mesmo que `IntlCalendar::FIELD_DAY_OF_MONTH`, que tem um nome mais claro.

`IntlCalendar::FIELD_DAY_OF_YEAR` int

  Campo de calendário para o dia no ano. Para o calendário gregoriano, começa com `1` e termina com `365` ou `366`.

`IntlCalendar::FIELD_DAY_OF_WEEK` int

  Campo de calendário para o dia da semana. Seus valores começam com `1` (domingo, consulte `IntlCalendar::DOW_SUNDAY` e constantes subsequentes) e o último valor válido é 7 (sábado).

`IntlCalendar::FIELD_DAY_OF_WEEK_IN_MONTH` int

  Dado um dia da semana (domingo, segunda-feira, …), este campo de calendário atribui um ordinal ao dia da semana em um mês específico. Portanto, se o valor deste campo for `1` e o valor do dia da semana for `2` (segunda-feira), o dia do mês será a 1ª segunda-feira do mês; o valor máximo é `5`.

  Adicionalmente, o valor `0` e números negativos também são permitidos. O valor `0` abrange os sete dias que ocorrem imediatamente antes dos primeiros sete dias de um mês (que por sua vez têm o ‘dia da semana no mês’ com valor `1`). Valores negativos começam a contagem do final do mês – `-1` aponta para a última ocorrência de um dia da semana em um mês, `-2` para a penúltima, e assim por diante.

  Diferentemente de `IntlCalendar::FIELD_WEEK_OF_MONTH` e `IntlCalendar::FIELD_WEEK_OF_YEAR`, este valor não depende de IntlCalendar::getFirstDayOfWeek() ou de IntlCalendar::getMinimalDaysInFirstWeek(). A primeira segunda-feira é a primeira segunda-feira, mesmo se ela ocorrer em uma semana que pertença ao mês anterior.

`IntlCalendar::FIELD_AM_PM` int

  Campo de calendário que indica se um horário é antes de meio-dia (valor `0`, a.m.) ou depois (`1`). Meia-noite é a.m., meio-dia é p.m..

`IntlCalendar::FIELD_HOUR` int

  Campo de calendário para a hora, sem especificar se é antes ou depois do meio-dia. Valores válidos são `0` a `11`.

`IntlCalendar::FIELD_HOUR_OF_DAY` int

  Campo de calendário para as horas integrais do dia (24h). Valores válidos são `0` a `23`.

`IntlCalendar::FIELD_MINUTE` int

  Campo de calendário para o componente de minutos do horário.

`IntlCalendar::FIELD_SECOND` int

  Campo de calendário para o componente de segundos do horário.

`IntlCalendar::FIELD_MILLISECOND` int

  Campo de calendário para o componente de milissegundos do horário.

`IntlCalendar::FIELD_ZONE_OFFSET` int

  Campo de calendário que indica o deslocamento puro do fuso horário, em milissegundos. O deslocamento puro é o deslocamento do fuso horário, excluindo qualquer deslocamento devido a horário de verão.

`IntlCalendar::FIELD_DST_OFFSET` int

  Campo de calendário para o deslocamento de horário de verão do fuso horário do calendário, em milissegundos, se ativo para o horário do calendário.

`IntlCalendar::FIELD_YEAR_WOY` int

  Campo de calendário que represente o ano para propósito de semana do ano

`IntlCalendar::FIELD_DOW_LOCAL` int

  Campo de calendário para o dia da semana da localidade. Este é um valor entre `1` e `7`, `1` é usado para o dia da semana que corresponde ao valor retornado por IntlCalendar::getFirstDayOfWeek().

`IntlCalendar::FIELD_EXTENDED_YEAR` int

  Campo de calendário para uma representação numérica do ano que é contínua através das eras. Para o calendário gregoriano, o valor deste campo corresponde ao de `IntlCalendar::FIELD_YEAR` para anos DC; um ano AC `y` é representando por `-y + 1`.

`IntlCalendar::FIELD_JULIAN_DAY` int

  Campo de calendário para um número de dia juliano modificado. É diferente de um número de dia juliano convencional pois sua transição ocorre à meia-noite do fuso horário local ao invés da meia-noite UTC. Identifica unicamente uma data.

`IntlCalendar::FIELD_MILLISECONDS_IN_DAY` int

  Campo de calendário que abrange a informação em `IntlCalendar::FIELD_HOUR_OF_DAY`, `IntlCalendar::FIELD_MINUTE`, `IntlCalendar::FIELD_SECOND` e `IntlCalendar::FIELD_MILLISECOND`. O intervalo é de `0` a `24 * 3600 * 1000 - 1`. Não é a quantidade de milissegundos decorridos no dia pois em transições de horário de verão haverá descontinuidades análogas àquelas do horário do relógio de parede.

`IntlCalendar::FIELD_IS_LEAP_MONTH` int

  Campo de calendário cujo valor é `1` para indicar um mês adicional e `0` caso contrário.

`IntlCalendar::FIELD_FIELD_COUNT` int

  O número total de campos.

`IntlCalendar::FIELD_DAY_OF_MONTH` int

  Apelido para `IntlCalendar::FIELD_DATE`.

`IntlCalendar::DOW_SUNDAY` int

  Domingo.

`IntlCalendar::DOW_MONDAY` int

  Segunda-feira.

`IntlCalendar::DOW_TUESDAY` int

  Terça-feira.

`IntlCalendar::DOW_WEDNESDAY` int

  Quarta-feira.

`IntlCalendar::DOW_THURSDAY` int

  Quinta-feira.

`IntlCalendar::DOW_FRIDAY` int

  Sexta-feira.

`IntlCalendar::DOW_SATURDAY` int

  Sábado.

`IntlCalendar::DOW_TYPE_WEEKDAY` int

  Saída de IntlCalendar::getDayOfWeekType() que indica se o dia é um dia da semana (e não do final de semana).

`IntlCalendar::DOW_TYPE_WEEKEND` int

  Saída de IntlCalendar::getDayOfWeekType() que indica se o dia pertence ao final de semana.

`IntlCalendar::DOW_TYPE_WEEKEND_OFFSET` int

  Saída de IntlCalendar::getDayOfWeekType() que indica que o final de semana começa no dia da semana informado.

`IntlCalendar::DOW_TYPE_WEEKEND_CEASE` int

  Saída de IntlCalendar::getDayOfWeekType() que indica que o final de semana termina no dia da semana informado.

`IntlCalendar::WALLTIME_FIRST` int

  Saída de IntlCalendar::getSkippedWallTimeOption() que indica que o horário de relógio na faixa pulada deve se referir ao mesmo instante que o relógio com uma hora a menos; e a saída de IntlCalendar::getRepeatedWallTimeOption() que indica que o horário do relógio na faixa repetida deve se referir ao instante da primeira ocorrência do horário em questão.

`IntlCalendar::WALLTIME_LAST` int

  Saída de IntlCalendar::getSkippedWallTimeOption() que indica que o horário de relógio na faixa pulada deve se referir ao mesmo instante que o relógio com uma hora a mais; e a saída de IntlCalendar::getRepeatedWallTimeOption() que indica que o horário do relógio na faixa repetida deve se referir ao instante da segunda ocorrência do horário em questão.

`IntlCalendar::WALLTIME_NEXT_VALID` int

  Saída de IntlCalendar::getSkippedWallTimeOption() que indica que o horário de relógio na faixa pulada deve se referir ao intante em que a transição de horário de verão ocorre (inicia).

## Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | As constantes de classe agora são tipadas.

# IntlCalendar::add

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::add — Adiciona uma quantidade de tempo (com sinal) a um campo

### Descrição

Estilo orientado a objetos

public function IntlCalendar::add(int `$field`, int `$value`): bool

Estilo procedural

function intlcal_add(IntlCalendar `$calendar`, int `$field`, int `$value`): bool

Adiciona uma quantidade de tempo com sinal a um campo. Adicionar uma quantidade positiva permite avançar no tempo, mesmo se o valor numérico do campo diminua (por exemplo, ao trabalhar com anos em datas AC).

Outros campos podem precisar de ajuste – por exemplo, adicionar um mês a 31 de janeiro irá resultar em 28 (ou 29) de fevereiro. Contrário ao que ocorre em IntlCalendar::roll(), quando um valor passa do limite, mais campos significativos podem ser alterados. Por exemplo, adicionar um dia a 31 de janeiro irá resultar em 1º de fevereiro, e não em 1º de janeiro.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.
`field`

  Uma das constantes de campo de data/horário da classe IntlCalendar. São valores inteiros entre `0` e `IntlCalendar::FIELD_COUNT`.

`value`

  A quantidade com sinal a ser adicionada ao campo atual. Se a quantidade for positiva, o instantes de tempo será movido para a frente; se for negativa, o instante será movido para o passado. A unidade é implícita ao tipo do campo. Por exemplo, horas para `IntlCalendar::FIELD_HOUR_OF_DAY`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 IntlCalendar::add()

    <?php
    ini_set('intl.default_locale', 'fr_FR');
    ini_set('date.timezone', 'UTC');

    $cal = new IntlGregorianCalendar(2012, 0 /* janeiro */, 31);
    echo IntlDateFormatter::formatObject($cal), "\n";

    $cal->add(IntlCalendar::FIELD_MONTH, 1);
    echo IntlDateFormatter::formatObject($cal), "\n";

    $cal->add(IntlCalendar::FIELD_DAY_OF_MONTH, 1);
    echo IntlDateFormatter::formatObject($cal), "\n";

O exemplo acima produzirá:

    31 janv. 2012 00:00:00
    29 févr. 2012 00:00:00
    1 mars 2012 00:00:00

# IntlCalendar::after

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::after — Informa se o instante de tempo deste objeto é posterior ao instante do objeto passado

### Descrição

Estilo orientado a objetos

public function IntlCalendar::after(IntlCalendar `$other`): bool

Estilo procedural

function intlcal_after(IntlCalendar `$calendar`, IntlCalendar `$other`): bool

Retorna se o instante de tempo deste objeto sucede o instante do argumento.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.
`other`

  O calendário cujo instante será verificado em relação ao instante do objeto primário.

### Valor Retornado

Retorna `true` se o instante deste objeto for posterior ao do argumento `calendar`. Retorna `false` caso contrário.

Em caso de falha, `false` também é retornado. Para detectar condições de erro, use intl_get_error_code() ou configure Intl para lançar exceções.

### Exemplos

Exemplo #1 IntlCalendar::after()

    <?php
    $cal1 = IntlCalendar::createInstance();
    $cal2 = clone $cal1;

    var_dump($cal1->after($cal2), // falso
            $cal2->after($cal1)); // falso

    $cal1->roll(IntlCalendar::FIELD_MILLISECOND, true);

    var_dump($cal1->after($cal2), // verdadeiro
            $cal2->after($cal1)); // falso

# IntlCalendar::before

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::before — Informa se o instante de tempo deste objeto é anterior ao instante do objeto passado

### Descrição

Estilo orientado a objetos

public function IntlCalendar::before(IntlCalendar `$other`): bool

Estilo procedural

function intlcal_before(IntlCalendar `$calendar`, IntlCalendar `$other`): bool

Retorna se o instante de tempo deste objeto precede o instante do argumento.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.
`other`

  O calendário cujo instante será verificado em relação ao instante do objeto primário.

### Valor Retornado

Retorna `true` se o instante deste objeto for anterior ao do argumento `calendar`. Retorna `false` caso contrário.

Em caso de falha, `false` também é retornado. Para detectar condições de erro, use intl_get_error_code() ou configure Intl para lançar exceções.

# IntlCalendar::clear

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::clear — Limpa um campo ou todos os campos

### Descrição

Estilo orientado a objetos

public function IntlCalendar::clear(?int `$field` = `null`): true

Estilo procedural

function intlcal_clear(IntlCalendar `$calendar`, ?int `$field` = `null`): true

Limpa todos os campos ou um campo específico. Um campo limpo é marcado como indefinido, dando a ele a menor prioridade em relação a campos sobrepostos ou mesmo a valores padrões ao calcular o instante de tempo. Adicionalmente, seu valor é definido para `0`, embora devido à baixa prioridade do campo, seu valor poderá ter sido definido internamente para outro valor no momento que o campo tenha terminado de ser consultado.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.
`field`

  Uma das constantes de campo de data/horário da classe IntlCalendar. São valores inteiros entre `0` e `IntlCalendar::FIELD_COUNT`.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.2.0 | O tipo do retorno agora é `true`; anteriormente, era bool.

### Exemplos

Exemplo #1 Exemplos de IntlCalendar::clear()

    <?php
    ini_set('intl.default_locale', 'es_ES');
    ini_set('date.timezone', 'UTC');

    $fields = array(
        'FIELD_ERA'                  => 0,
        'FIELD_YEAR'                 => 1,
        'FIELD_MONTH'                => 2,
        'FIELD_WEEK_OF_YEAR'         => 3,
        'FIELD_WEEK_OF_MONTH'        => 4,
        'FIELD_DATE'                 => 5,
        'FIELD_DAY_OF_YEAR'          => 6,
        'FIELD_DAY_OF_WEEK'          => 7,
        'FIELD_DAY_OF_WEEK_IN_MONTH' => 8,
        'FIELD_AM_PM'                => 9,
        'FIELD_HOUR'                 => 10,
        'FIELD_HOUR_OF_DAY'          => 11,
        'FIELD_MINUTE'               => 12,
        'FIELD_SECOND'               => 13,
        'FIELD_MILLISECOND'          => 14,
        'FIELD_ZONE_OFFSET'          => 15,
        'FIELD_DST_OFFSET'           => 16,
        'FIELD_YEAR_WOY'             => 17,
        'FIELD_DOW_LOCAL'            => 18,
        'FIELD_EXTENDED_YEAR'        => 19,
        'FIELD_JULIAN_DAY'           => 20,
        'FIELD_MILLISECONDS_IN_DAY'  => 21,
        'FIELD_IS_LEAP_MONTH'        => 22,
        'FIELD_FIELD_COUNT'          => 23,
    );
    function getSetFields(IntlCalendar $cal) {
        global $fields;
        $ret = array();
        foreach ($fields as $name => $value) {
            if ($cal->isSet($value)) {
                $ret[] = $name;
            }
        }
        return $ret;
    }

    $cal = new IntlGregorianCalendar(2013, 2 /* março */, 15);
    echo "Depois da criação do calendário gregoriano\n";
    print_r(getSetFields($cal));
    echo "\n";

    echo IntlDateFormatter::formatObject($cal), "\n";
    echo "Depois do formatador requisitar o ano estendido\n";
    print_r(getSetFields($cal));
    echo "\n";

    $cal->clear(IntlCalendar::FIELD_YEAR);
    echo "Depois do ano ter sido limpo, a data fica a mesma\n";
    echo IntlDateFormatter::formatObject($cal), "\n";
    echo "porque FIELD_EXTENDED_YEAR ainda está definida\n";
    print_r(getSetFields($cal));
    echo "\n";

    var_dump($cal->clear(IntlCalendar::FIELD_EXTENDED_YEAR));
    echo "Depois que o ano estendido foi limpo\n";
    print_r(getSetFields($cal));
    echo IntlDateFormatter::formatObject($cal), "\n";
    echo "\n";

    echo "Depois que os campos são recalculados,\n"
            . " o ano estendido é definido novamente (para 1970)\n";
    print_r(getSetFields($cal));
    echo "\n";

    $cal->clear();
    echo "Depois de chamar a variante sem argumentos\n";
    print_r(getSetFields($cal));
    echo IntlDateFormatter::formatObject($cal), "\n";

O exemplo acima produzirá:

    Depois da criação do calendário gregoriano
    Array
    (
        [0] => FIELD_ERA
        [1] => FIELD_YEAR
        [2] => FIELD_MONTH
        [3] => FIELD_DATE
    )

    15/03/2013 00:00:00
    Depois do formatador requisitar o ano estendido
    Array
    (
        [0] => FIELD_ERA
        [1] => FIELD_YEAR
        [2] => FIELD_MONTH
        [3] => FIELD_DATE
        [4] => FIELD_EXTENDED_YEAR
    )

    Depois do ano ter sido limpo, a data fica a mesma
    15/03/2013 00:00:00
    porque FIELD_EXTENDED_YEAR ainda está definida
    Array
    (
        [0] => FIELD_ERA
        [1] => FIELD_MONTH
        [2] => FIELD_DATE
        [3] => FIELD_EXTENDED_YEAR
    )

    bool(true)
    Depois que o ano estendido foi limpo
    Array
    (
        [0] => FIELD_ERA
        [1] => FIELD_MONTH
        [2] => FIELD_DATE
    )
    15/03/1970 00:00:00

    Depois que os campos são recalculados,
     o ano estendido é definido novamente (para 1970)
    Array
    (
        [0] => FIELD_ERA
        [1] => FIELD_MONTH
        [2] => FIELD_DATE
        [3] => FIELD_EXTENDED_YEAR
    )

    Depois de chamar a variante sem argumentos
    Array
    (
    )
    01/01/1970 00:00:00

# IntlCalendar::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::__construct — Construtor privado para não permitir instanciação

### Descrição

private function IntlCalendar::__construct()

Um construtor privado para não permitir instanciação com o operador new.

Chame IntlCalendar::createInstance() em seu lugar.

### Parâmetros

Esta função não possui parâmetros.

# IntlCalendar::createInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::createInstance — Cria um novo IntlCalendar

### Descrição

Estilo orientado a objetos

public static function IntlCalendar::createInstance(IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`, ?string `$locale` = `null`): ?IntlCalendar

Estilo procedural

function intlcal_create_instance(IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`, ?string `$locale` = `null`): ?IntlCalendar

Informados um fuso horário e uma localidade, este método cria um objeto IntlCalendar. Este método de criação pode retornar uma sub-classe de IntlCalendar.

O calendário criado representará o instante de tempo no qual foi criado, baseado no horário do sistema. Os campos podem ser todos limpos chamando-se IntCalendar::clear() sem argumentos. Veja também IntlGregorianCalendar::__construct().

### Parâmetros

`timezone`

  O fuso horário a ser utilizado.

  - `null`, neste caso o fuso horário padrão será usado, como especificado na configuração ini date.timezone ou através da função date_default_timezone_set() e como retornado por date_default_timezone_get().

  - Um objeto IntlTimeZone, que será usado diretamente.

  - Um objeto DateTimeZone. Seu identificador será extraído e um objeto de fuso horário ICU será criado; o fuso horário será apoiado pelo banco de dados da ICU, não pelo do PHP.

  - Uma string, que deve ser um identificador de fuso horário ICU válido. Consulte a função IntlTimeZone::createTimeZoneIDEnumeration(). Deslocamentos puros como `"GMT+08:30"` também são aceitos.

`locale`

  A localidade a ser utilizada ou `null` para usar a localidade padrão.

### Valor Retornado

A instância IntlCalendar criada ou `null` em caso de falha.

### Exemplos

Exemplo #1 IntlCalendar::createInstance()

    <?php
    ini_set('intl.default_locale', 'es_ES');
    ini_set('date.timezone', 'Europe/Madrid');

    $cal = IntlCalendar::createInstance();
    echo "Sem argumentos\n";
    var_dump(get_class($cal),
            IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL));
    echo "\n";

    echo "Fuso horário explicitado\n";
    $cal = IntlCalendar::createInstance(IntlTimeZone::getGMT());
    var_dump(get_class($cal),
            IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL));
    echo "\n";

    echo "Localidade explicitada (com calendário)\n";
    $cal = IntlCalendar::createInstance(NULL, 'es_ES@calendar=persian');
    var_dump(get_class($cal),
            IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL));

O exemplo acima produzirá:

    Sem argumentos
    string(21) "IntlGregorianCalendar"
    string(68) "martes 18 de junio de 2013 14:11:02 Hora de verano de Europa Central"

    Fuso horário explicitado
    string(21) "IntlGregorianCalendar"
    string(45) "martes 18 de junio de 2013 12:11:02 GMT+00:00"

    Localidade explicitada (com calendário)
    string(12) "IntlCalendar"
    string(70) "martes 28 de Khordad de 1392 14:11:02 Hora de verano de Europa Central"

### Veja Também

- IntlGregorianCalendar::__construct() - Cria um objeto de calendário gregoriano

# IntlCalendar::equals

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::equals — Compara horários de dois objetos IntlCalendar para igualidade

### Descrição

Estilo orientado a objetos

public function IntlCalendar::equals(IntlCalendar `$other`): bool

Estilo procedural

function intlcal_equals(IntlCalendar `$calendar`, IntlCalendar `$other`): bool

Retorna verdadeiro se este calendário e o calendário informado tiverem o mesmo horário. As configurações, tipos de calendário e estados de campos não precisam ser os mesmos.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.
`other`

  O calendário a ser comparado com o objeto primário.

### Valor Retornado

Retorna `true` se os horário de ambos os objetos IntlCalendar forem o mesmo, ou `false` caso contrário.

Em caso de falha, `false` também é retornado. Para detectar condições de erro, use intl_get_error_code() ou configure Intl para lançar exceções.

### Exemplos

Exemplo #1 IntlCalendar::equals()

    <?php
    ini_set('date.timezone', 'UTC');

    $cal1 = IntlCalendar::createInstance(NULL, 'es_ES');
    $cal2 = clone $cal1;

    var_dump($cal1->equals($cal2)); //TRUE

    //A localidade não é incluída na comparação
    $cal2 = IntlCalendar::createInstance(NULL, 'pt_PT');
    $cal2->setTime($cal1->getTime());
    var_dump($cal1->equals($cal2)); //TRUE

    //E os estados definidos para os campos também não são incluídos
    $cal2->clear(IntlCalendar::FIELD_YEAR);
    var_dump($cal1->isSet(IntlCalendar::FIELD_YEAR) ==
            $cal2->isSet(IntlCalendar::FIELD_YEAR)); //FALSE
    var_dump($cal1->equals($cal2)); //TRUE

    //E nem o tipo do calendário
    $cal2 = IntlCalendar::createInstance(NULL, 'es_ES@calendar=islamic');
    $cal2->setTime($cal1->getTime());
    var_dump($cal1->equals($cal2)); //TRUE

    //Apenas o instante de tempo é incluído
    $cal2 = clone $cal1;
    $cal2->setTime($cal1->getTime() + 1.);
    var_dump($cal1->equals($cal2)); //FALSE

# IntlCalendar::fieldDifference

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::fieldDifference — Calcula a diferença entre o horário fornecido e o horário deste objeto

### Descrição

Estilo orientado a objetos

public function IntlCalendar::fieldDifference(float `$timestamp`, int `$field`): int|false

Estilo procedural

function intlcal_field_difference(IntlCalendar `$calendar`, float `$timestamp`, int `$field`): int|false

Calcula a diferença entre o horário fornecido e o horário definido para este objeto, com respeito à quantidade especificada pelo parâmetro `field`.

Este método foi projetado para ser chamado sucessivamente, primeiro com o campo de interesse mais significativo até o menos significativo. Para isto, como efeito colateral, o valor do campo para este calendário é avançado na quantidade retornada.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.
`timestamp`

  O horário com o qual a quantidade representada pelo `field` será comparada. Para que o resultado seja positivo, o horário informado para este parâmetro deve ser posterior ao do objeto em que este método está sendo chamado.

`field`

  O campos que representa a quantidade sendo comparada.

  Uma das constantes de campo de data/horário da classe IntlCalendar. São valores inteiros entre `0` e `IntlCalendar::FIELD_COUNT`.

### Valor Retornado

Retorna uma diferença (com sinal) de tempo na unidade associada com o campo especificado ou `false` em caso de falha.

### Exemplos

Exemplo #1 IntlCalendar::fieldDifference()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'fr_FR');

    $cal1 = IntlCalendar::fromDateTime('2012-02-29 09:00:11');
    $cal2 = IntlCalendar::fromDateTime('2013-03-01 09:19:29');
    $time = $cal2->getTime();

    echo "Horário antes: ", IntlDateFormatter::formatObject($cal1), "\n";

    printf(
        "A diferença de tempo é de %d ano(s), %d mês(es), "
      . "%d dia(s), %d hora(s) e %d minutos(s)\n",
        $cal1->fieldDifference($time, IntlCalendar::FIELD_YEAR),
        $cal1->fieldDifference($time, IntlCalendar::FIELD_MONTH),
        $cal1->fieldDifference($time, IntlCalendar::FIELD_DAY_OF_MONTH),
        $cal1->fieldDifference($time, IntlCalendar::FIELD_HOUR_OF_DAY),
        $cal1->fieldDifference($time, IntlCalendar::FIELD_MINUTE)
    );

    //agora o objeto avançou para o tempo alvo, exteto pelos segundos,
    //para os quais não foram medidas as diferenças
    echo "Horário depois: ", IntlDateFormatter::formatObject($cal1), "\n";

O exemplo acima produzirá:

    Horário antes: 29 févr. 2012 09:00:11
    A diferença de tempo é de 1 ano(s), 0 mês(es), 1 dia(s), 0 hora(s) e 19 minutos(s)
    Horário depois: 1 mars 2013 09:19:11

# IntlCalendar::fromDateTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a2)

IntlCalendar::fromDateTime — Cria um IntlCalendar a partir de um objeto DateTime ou uma string

### Descrição

Estilo orientado a objetos

public static function IntlCalendar::fromDateTime(DateTime|string `$datetime`, ?string `$locale` = `null`): ?IntlCalendar

Estilo procedural

function intlcal_from_date_time(DateTime|string `$datetime`, ?string `$locale` = `null`): ?IntlCalendar

Cria um objeto IntlCalendar a partir de um objeto DateTime ou a partir de uma string da qual seja possível criar um objeto DateTime.

O novo calendário representará não somente o mesmo instante do DateTime informado (sujeito a perda de precisão para datas muito distantes no passado ou no futuro), mas também o mesmo fuso horário (sujeito à ressalva de que diferentes bancos de dados de fuso horário serão usados, e portanto os resultados podem ser diferentes).

### Parâmetros

`datetime`

  Um objeto DateTime ou uma string que possa ser passada a DateTime::__construct().

### Valor Retornado

O objeto IntlCalendar criado ou `null` em caso de falha. Se uma string for informada, qualquer exceção que ocorrer dentro do construtor DateTime será propagada.

### Exemplos

Exemplo #1 IntlCalendar::fromDateTime()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');

    //o mesmo que IntlCalendar::fromDateTime(new DateTime(...))
    $cal1 = IntlCalendar::fromDateTime('2013-02-28 00:01:02 Europe/Berlin', 'de_DE');

    //Note que o fuso horário é Europe/Berlin, e não o padrão Europe/Lisbon
    echo IntlDateFormatter::formatObject($cal1, 'yyyy MMMM d HH:mm:ss VVVV', 'de_DE'), "\n";

O exemplo acima produzirá:

    2013 Februar 28 00:01:02 Deutschland Zeit

# IntlCalendar::get

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::get — Obtém o valor de um campo

### Descrição

Estilo orientado a objetos

public function IntlCalendar::get(int `$field`): int|false

Estilo procedural

function intlcal_get(IntlCalendar `$calendar`, int `$field`): int|false

Obtém o valor de um campo específico.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.
`field`

  Uma das constantes de campo de data/horário da classe IntlCalendar. São valores inteiros entre `0` e `IntlCalendar::FIELD_COUNT`.

### Valor Retornado

Um inteiro com o valor do campo de horário.

### Exemplos

Exemplo #1 IntlCalendar::get()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'en_US');

    $class = new ReflectionClass('IntlCalendar');
    $fields = array();
    foreach ($class->getConstants() as $name => $val) {
        if (strpos($name, 'FIELD_') !== 0 || $val > 22)
            continue;
        $fields[$val] = $name;
    }

    $cal = IntlCalendar::createInstance(); // horário atual
    var_dump(IntlDateFormatter::formatObject($cal));
    foreach ($fields as $val => $name) {
        echo "$val ($name)", "\n    ", $cal->get($val), "\n";
    }

O exemplo acima produzirá:

    string(23) "Jul 1, 2013, 4:44:44 AM"
    0 (FIELD_ERA)
        1
    1 (FIELD_YEAR)
        2013
    2 (FIELD_MONTH)
        6
    3 (FIELD_WEEK_OF_YEAR)
        27
    4 (FIELD_WEEK_OF_MONTH)
        1
    5 (FIELD_DAY_OF_MONTH)
        1
    6 (FIELD_DAY_OF_YEAR)
        182
    7 (FIELD_DAY_OF_WEEK)
        2
    8 (FIELD_DAY_OF_WEEK_IN_MONTH)
        1
    9 (FIELD_AM_PM)
        0
    10 (FIELD_HOUR)
        4
    11 (FIELD_HOUR_OF_DAY)
        4
    12 (FIELD_MINUTE)
        44
    13 (FIELD_SECOND)
        44
    14 (FIELD_MILLISECOND)
        551
    15 (FIELD_ZONE_OFFSET)
        0
    16 (FIELD_DST_OFFSET)
        3600000
    17 (FIELD_YEAR_WOY)
        2013
    18 (FIELD_DOW_LOCAL)
        2
    19 (FIELD_EXTENDED_YEAR)
        2013
    20 (FIELD_JULIAN_DAY)
        2456475
    21 (FIELD_MILLISECONDS_IN_DAY)
        17084551
    22 (FIELD_IS_LEAP_MONTH)
        0

# IntlCalendar::getActualMaximum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getActualMaximum — O valor máximo para um campo, considerando o horário atual do objeto

### Descrição

Estilo orientado a objetos

public function IntlCalendar::getActualMaximum(int `$field`): int|false

Estilo procedural

function intlcal_get_actual_maximum(IntlCalendar `$calendar`, int `$field`): int|false

Retorna o valor máximo relativo de um campo em relação ao horário atual. A semântica exata varia por campo, mas em geral é o valor que seria obtido se fosse definido o valor do campo para o menor máximo relativo para o campo e fosse incrementado até alcançar o máximo global ou até que o valor do campo retorne ao inicial, no qual o valor retornado seria o máximo global ou o valor antes de retornar ao incial, respectivamente.

Por exemplo, no calendário gregoriano, o valor máximo real para o dia do mês pode variar entre `28` e `31`, dependendo do mês e do ano do horário atual.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.
`field`

  Uma das constantes de campo de data/horário da classe IntlCalendar. São valores inteiros entre `0` e `IntlCalendar::FIELD_COUNT`.

### Valor Retornado

Um número int representando o valor máximo na unidade associada ao parâmetro `field` informado ou `false` em caso de falha.

### Exemplos

Exemplo #1 IntlCalendar::getActualMaximum()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');

    $cal = IntlCalendar::fromDateTime('2013-02-15');
    var_dump($cal->getActualMaximum(IntlCalendar::FIELD_DAY_OF_MONTH)); //28

    $cal->add(IntlCalendar::FIELD_EXTENDED_YEAR, -1);
    var_dump($cal->getActualMaximum(IntlCalendar::FIELD_DAY_OF_MONTH)); //29

O exemplo acima produzirá:

    int(28)
    int(29)

### Veja Também

- IntlCalendar::getMaximum() - Obtém o valor máximo global para um campo
- IntlCalendar::getLeastMaximum() - Obtém o menor máximo local para um campo
- IntlCalendar::getActualMinimum() - O valor mínimo para um campo, considerando o horário atual do objeto

# IntlCalendar::getActualMinimum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getActualMinimum — O valor mínimo para um campo, considerando o horário atual do objeto

### Descrição

Estilo orientado a objetos

public function IntlCalendar::getActualMinimum(int `$field`): int|false

Estilo procedural

function intlcal_get_actual_minimum(IntlCalendar `$calendar`, int `$field`): int|false

Retorna o valor mínimo relativo de um campo em relação ao horário atual. A semântica exata varia por campo, mas em geral é o valor que seria obtido se fosse definido o valor do campo para o maior mínimo relativo para o campo e fosse decrementado até alcançar o mínimo global ou até que o valor do campo retorne ao final da escala, no qual o valor retornado seria o mínimo global ou o valor antes de retornar ao final da escala, respectivamente.

Para o calendário gregoriano, será sempre o mesmo que IntlCalendar::getMinimum().

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.
`field`

  Uma das constantes de campo de data/horário da classe IntlCalendar. São valores inteiros entre `0` e `IntlCalendar::FIELD_COUNT`.

### Valor Retornado

Um número int representando o valor mínimo na unidade do campo ou `false` em caso de falha.

### Veja Também

- IntlCalendar::getMinimum() - Obtém o mínimo global para um campo
- IntlCalendar::getGreatestMinimum() - Obtém o maior valor mínimo local para um campo
- IntlCalendar::getActualMaximum() - O valor máximo para um campo, considerando o horário atual do objeto

# IntlCalendar::getAvailableLocales

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getAvailableLocales — Obtém um array de localidades para as quais existem dados

### Descrição

Estilo orientado a objetos

public static function IntlCalendar::getAvailableLocales(): array

Estilo procedural

function intlcal_get_available_locales(): array

Fornece a lista de localidades para as quais existem calendários instalados. A partir da ICU 51, esta é a list de todas as localidades ICU instaladas.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array de strings, uma para cada localidade.

### Exemplos

Exemplo #1 IntlCalendar::getAvailableLocales()

    <?php
    print_r(IntlCalendar::getAvailableLocales());

O exemplo acima produzirá:

    Array
    (
        [0] => af
        [1] => af_NA
        [2] => af_ZA
        [3] => agq
        [4] => agq_CM
        [5] => ak
        [6] => ak_GH
        [7] => am
        [8] => am_ET
        [9] => ar
        [10] => ar_001
        [11] => ar_AE
        [12] => ar_BH
        [13] => ar_DJ
        … output abbreviated …
        [595] => zh_Hant_HK
        [596] => zh_Hant_MO
        [597] => zh_Hant_TW
        [598] => zu
        [599] => zu_ZA
    )

# IntlCalendar::getDayOfWeekType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getDayOfWeekType — Informa se o dia é dia de semana, de final de semana ou de transição entre os dois

### Descrição

Estilo orientado a objetos

public function IntlCalendar::getDayOfWeekType(int `$dayOfWeek`): int|false

Estilo procedural

function intlcal_get_day_of_week_type(IntlCalendar `$calendar`, int `$dayOfWeek`): int|false

Retorna se o dia informado é um dia de semana (`IntlCalendar::DOW_TYPE_WEEKDAY`), de final de semana (`IntlCalendar::DOW_TYPE_WEEKEND`), ou um dia durante o qual uma transição ocorre entrando no final de semana (`IntlCalendar::DOW_TYPE_WEEKEND_OFFSET`) ou um dia durante o qual o final de semana termina (`IntlCalendar::DOW_TYPE_WEEKEND_CEASE`).

Se o valor de retorno for `IntlCalendar::DOW_TYPE_WEEKEND_OFFSET` ou `IntlCalendar::DOW_TYPE_WEEKEND_CEASE`, então pode-se chamar IntlCalendar::getWeekendTransition() para se obter o horário da transição.

Esta função requer a ICU 4.4 ou posterior.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.
`dayOfWeek`

  Uma das constantes `IntlCalendar::DOW_SUNDAY`, `IntlCalendar::DOW_MONDAY`, …, `IntlCalendar::DOW_SATURDAY`.

### Valor Retornado

Retorna uma das constantes `IntlCalendar::DOW_TYPE_WEEKDAY`, `IntlCalendar::DOW_TYPE_WEEKEND`, `IntlCalendar::DOW_TYPE_WEEKEND_OFFSET` ou `IntlCalendar::DOW_TYPE_WEEKEND_CEASE` ou `false` em caso de falha.

### Exemplos

Exemplo #1 IntlCalendar::getDayOfWeekType()

    <?php
    foreach (array('en_US', 'ar_SA') as $locale) {
        echo "Localidade: ", Locale::getDisplayName($locale, "en_US"), "\n";

        $cal = IntlCalendar::createInstance('UTC', $locale);

        for ($i = IntlCalendar::DOW_SUNDAY; $i <= IntlCalendar::DOW_SATURDAY; $i++) {
            $type = $cal->getDayOfWeekType($i);
            $transition = ($type !== IntlCalendar::DOW_TYPE_WEEKDAY)
                ? $cal->getWeekendTransition($i)
                : '';
            echo $i, " ", $type, " ", $transition, "\n";
        }
        echo "\n";
    }
    ?>

O exemplo acima produzirá:

    Localidade: English (United States)
    1 1 86400000
    2 0
    3 0
    4 0
    5 0
    6 0
    7 1 0

    Localidade: Arabic (Saudi Arabia)
    1 0
    2 0
    3 0
    4 0
    5 0
    6 1 0
    7 1 86400000

# IntlCalendar::getErrorCode

# intlcal_get_error_code

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getErrorCode -- intlcal_get_error_code — Obtém o último código de erro no objeto

### Descrição

Estilo orientado a objetos (method):

public function IntlCalendar::getErrorCode(): int|false

Estilo procedural:

function intlcal_get_error_code(IntlCalendar `$calendar`): int|false

Retorna o código de erro numérico da ICU para a última chamada neste objeto (incluindo clonagem) ou no objeto IntlCalendar informado no parâmetro `calendar` (na versão em estilo procedural). Pode indicar apenas um alerta (código de erro negativo) ou nenhum erro (`U_ZERO_ERROR`). A presença real de erro pode ser testada com intl_is_failure().

Argumentos inválidos detectados no lado do PHP (antes de chamar funções da biblioteca ICU) não são registradas para o propósito desta função.

O último erro que ocorreu em qualquer chamada a uma função da extensão Intl, incluindo erros de argumentos, podem ser obtidos com intl_get_error_code(). Esta função redefine o código de erro global, mas não o código de erro do objeto.

### Parâmetros

`calendar`

  O objeto calendário, na interface em estilo procedural.

### Valor Retornado

Um código de erro ICU indicando sucesso, falha ou um alerta. Retorna `false` em caso de falha.

### Exemplos

Exemplo #1 IntlCalendar::getErrorCode() e IntlCalendar::getErrorMessage()

    <?php
    ini_set("intl.error_level", E_WARNING);
    ini_set("intl.default_locale", "nl");

    $intlcal = new IntlGregorianCalendar(2012, 1, 29);
    var_dump(
        $intlcal->getErrorCode(),
        $intlcal->getErrorMessage()
    );
    $intlcal->fieldDifference(-1e100, IntlCalendar::FIELD_SECOND);

    var_dump(
        $intlcal->getErrorCode(),
        $intlcal->getErrorMessage()
    );

O exemplo acima produzirá:

    int(0)
    string(12) "U_ZERO_ERROR"

    Warning: IntlCalendar::fieldDifference(): intlcal_field_difference: Call to ICU method has failed in /home/glopes/php/ws/example.php on line 10
    int(1)
    string(81) "intlcal_field_difference: Call to ICU method has failed: U_ILLEGAL_ARGUMENT_ERROR"

### Veja Também

- IntlCalendar::getErrorMessage() - Obtém a última mensagem de erro no objeto
- intl_is_failure() - Verifica se o código de erro fornecido indica falha
- intl_error_name() - Obtém nome simbólico para um código de erro informado
- intl_get_error_code() - Obtém o último código de erro
- intl_get_error_message() - Obtém a descrição do último erro

# IntlCalendar::getErrorMessage

# intlcal_get_error_message

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getErrorMessage -- intlcal_get_error_message — Obtém a última mensagem de erro no objeto

### Descrição

Estilo orientado a objetos (method):

public function IntlCalendar::getErrorMessage(): string|false

Estilo procedural:

function intlcal_get_error_message(IntlCalendar `$calendar`): string|false

Retorna a mensagem de erro (se houver) associada com o erro reportado por IntlCalendar::getErrorCode() ou intlcal_get_error_code(). Se não houver mensagem de erro associada, apenas a representação em string do nome da constante de erro será retornada. Caso contrário, o texto também incluirá uma mensagem definida no lado da ligação com o PHP.

### Parâmetros

`calendar`

  O objeto calendário, na interface de estilo procedural.

### Valor Retornado

A mensagem de erro associada com o último erro ocorrido em uma chamada de função neste objeto, ou uma string indicando a não existência de erro. Retorna `false` em caso de falha.

### Exemplos

Exemplo #1 IntlCalendar::getErrorMessage()

    <?php
    $cal = IntlCalendar::createInstance('UTC', 'en_US');
    var_dump($cal->getErrorMessage());

    $cal->getWeekendTransition(IntlCalendar::DOW_WEDNESDAY);
    var_dump($cal->getErrorMessage());

O exemplo acima produzirá:

    string(12) "U_ZERO_ERROR"
    string(82) "intlcal_get_weekend_transition: Error calling ICU method: U_ILLEGAL_ARGUMENT_ERROR"

# IntlCalendar::getFirstDayOfWeek

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getFirstDayOfWeek — Obtém o primeiro dia da semana para a localidade do calendário

### Descrição

Estilo orientado a objetos

public function IntlCalendar::getFirstDayOfWeek(): int|false

Estilo procedural

function intlcal_get_first_day_of_week(IntlCalendar `$calendar`): int|false

O dia da semana que inicia a semana, pode ser o valor padrão para esta localidade ou o valor definido com IntlCalendar::setFirstDayOfWeek().

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.

### Valor Retornado

Uma das constantes `IntlCalendar::DOW_SUNDAY`, `IntlCalendar::DOW_MONDAY`, …, `IntlCalendar::DOW_SATURDAY` ou `false` em caso de falha.

### Exemplos

Exemplo #1 IntlCalendar::getFirstDayOfWeek()

    <?php
    ini_set('date.timezone', 'UTC');

    $cal1 = IntlCalendar::createInstance(NULL, 'es_ES');
    var_dump($cal1->getFirstDayOfWeek()); // segunda-feira
    $cal1->set(2013, 1 /* fevereiro */, 3); // um domingo
    var_dump($cal1->get(IntlCalendar::FIELD_WEEK_OF_YEAR)); // 5

    $cal2 = IntlCalendar::createInstance(NULL, 'en_US');
    var_dump($cal2->getFirstDayOfWeek()); // domingo
    $cal2->set(2013, 1 /* fevereiro */, 3); // um domingo
    var_dump($cal2->get(IntlCalendar::FIELD_WEEK_OF_YEAR)); // 6

O exemplo acima produzirá:

    int(2)
    int(5)
    int(1)
    int(6)

### Veja Também

- IntlCalendar::setFirstDayOfWeek() - Define o dia da semana no qual a semana inicia

# IntlCalendar::getGreatestMinimum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getGreatestMinimum — Obtém o maior valor mínimo local para um campo

### Descrição

Estilo orientado a objetos

public function IntlCalendar::getGreatestMinimum(int `$field`): int|false

Estilo procedural

function intlcal_get_greatest_minimum(IntlCalendar `$calendar`, int `$field`): int|false

Returns o maior mínimo local para um campo. Este deverá ser um valor maior ou igual ao retornado por IntlCalendar::getActualMinimum(), que por sua vez é maior ou igual ao retornado por IntlCalendar::getMinimum(). Todas estas três funções retornam o mesmo valor para o calendário gregoriano.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.
`field`

  Uma das constantes de campo de data/horário da classe IntlCalendar. São valores inteiros entre `0` e `IntlCalendar::FIELD_COUNT`.

### Valor Retornado

Um número int representando um valor de campo, na unidade do campo, ou `false` em caso de falha.

# IntlCalendar::getKeywordValuesForLocale

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getKeywordValuesForLocale — Obtém um conjunto de valores de palavras-chaves de localidade

### Descrição

Estilo orientado a objetos

public static function IntlCalendar::getKeywordValuesForLocale(string `$keyword`, string `$locale`, bool `$onlyCommon`): IntlIterator|false

Estilo procedural

function intlcal_get_keyword_values_for_locale(string `$keyword`, string `$locale`, bool `$onlyCommon`): IntlIterator|false

Para uma chave de localidade informada, obtém o conjunto de valores para essa chave que resultaria em um comportamento diferente. Por agora, apenas a palavra-chave `'calendar'` é suportada.

Esta função requer a ICU 4.2 ou posterior.

### Parâmetros

`keyword`

  A palavra-chave de localidade para a qual valores relevantes serão consultados. Apenas `'calendar'` é suportada.

`locale`

  A localidade na qual o par palavra-chave/valor será anexado.

`onlyCommon`

  Determina se deve-se mostrar apenas os valores comumente usados para a localidade especificada.

### Valor Retornado

Um iterador que gera strings com os valores de palavra-chave da localidade ou `false` em caso de falha.

### Exemplos

Exemplo #1 IntlCalendar::getKeywordValuesForLocale()

    <?php
    print_r(
            iterator_to_array(
                    IntlCalendar::getKeywordValuesForLocale(
                            'calendar', 'fa_IR', true)));
    print_r(
            iterator_to_array(
                    IntlCalendar::getKeywordValuesForLocale(
                            'calendar', 'fa_IR', false)));

O exemplo acima produzirá:

    Array
    (
        [0] => persian
        [1] => gregorian
        [2] => islamic
        [3] => islamic-civil
    )
    Array
    (
        [0] => persian
        [1] => gregorian
        [2] => islamic
        [3] => islamic-civil
        [4] => japanese
        [5] => buddhist
        [6] => roc
        [7] => hebrew
        [8] => chinese
        [9] => indian
        [10] => coptic
        [11] => ethiopic
        [12] => ethiopic-amete-alem
    )

# IntlCalendar::getLeastMaximum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getLeastMaximum — Obtém o menor máximo local para um campo

### Descrição

Estilo orientado a objetos

public function IntlCalendar::getLeastMaximum(int `$field`): int|false

Estilo procedural

function intlcal_get_least_maximum(IntlCalendar `$calendar`, int `$field`): int|false

Retorna o menor máximo local para um campo. Deve ser um valor menor ou igual ao retornado por IntlCalendar::getActualMaximum(), que por usa vez é menor ou igual ao retornado por IntlCalendar::getMaximum().

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.
`field`

  Uma das constantes de campo de data/horário da classe IntlCalendar. São valores inteiros entre `0` e `IntlCalendar::FIELD_COUNT`.

### Valor Retornado

Um número int representando um valor de campo na unidade do campo ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplos de máximos

    <?php
    ini_set('date.timezone', 'UTC');
    ini_set('intl.default_locale', 'it_IT');

    $cal = new IntlGregorianCalendar(2013, 3 /* abril */, 6);
    var_dump(
        $cal->getLeastMaximum(IntlCalendar::FIELD_DAY_OF_MONTH),  // 28
        $cal->getActualMaximum(IntlCalendar::FIELD_DAY_OF_MONTH), // 30
        $cal->getMaximum(IntlCalendar::FIELD_DAY_OF_MONTH)        // 31
    );

O exemplo acima produzirá:

    int(28)
    int(30)
    int(31)

### Veja Também

- IntlCalendar::getActualMaximum() - O valor máximo para um campo, considerando o horário atual do objeto
- IntlCalendar::getMaximum() - Obtém o valor máximo global para um campo
- IntlCalendar::getGreatestMinimum() - Obtém o maior valor mínimo local para um campo

# IntlCalendar::getLocale

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getLocale — Obtém a localidade associada com o objeto

### Descrição

Estilo orientado a objetos

public function IntlCalendar::getLocale(int `$type`): string|false

Estilo procedural

function intlcal_get_locale(IntlCalendar `$calendar`, int `$type`): string|false

Retorna a localidade usada por este objeto calendário.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.
`type`

  Determina se deve-se obter a localidade real (a localidade da qual os dados do calendário se originam, com `Locale::ACTUAL_LOCALE`) ou a localidade válida, isto é, a localidade mais específica suportada pela ICU em relação à localidade solicitada – veja `Locale::VALID_LOCALE`. Da mais geral à mais específica, as localidades são ordenadas desta forma – localidade real, localidade válida, localidade solicitada.

### Valor Retornado

Uma string de localidade ou `false` em caso de falha.

### Exemplos

Exemplo #1 IntlCalendar::getLocale()

    <?php
    $cal = IntlCalendar::createInstance(IntlTimeZone::getGMT(), 'en_US_CALIFORNIA');
    var_dump(
        $cal->getLocale(Locale::ACTUAL_LOCALE),
        $cal->getLocale(Locale::VALID_LOCALE)
    );

O exemplo acima produzirá:

    string(2) "en"
    string(5) "en_US"

# IntlCalendar::getMaximum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getMaximum — Obtém o valor máximo global para um campo

### Descrição

Estilo orientado a objetos

public function IntlCalendar::getMaximum(int `$field`): int|false

Estilo procedural

function intlcal_get_maximum(IntlCalendar `$calendar`, int `$field`): int|false

Obtém o máximo global para um campo, neste calendário específico. Este valor é maior ou igual ao retornado por IntlCalendar::getActualMaximum(), que por usa vez é maior ou igual ao retornado por IntlCalendar::getLeastMaximum().

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.
`field`

  Uma das constantes de campo de data/horário da classe IntlCalendar. São valores inteiros entre `0` e `IntlCalendar::FIELD_COUNT`.

### Valor Retornado

Um int representando um valor de campo na unidade do campo ou `false` em caso de falha.

### Veja Também

- IntlCalendar::getActualMaximum() - O valor máximo para um campo, considerando o horário atual do objeto
- IntlCalendar::getLeastMaximum() - Obtém o menor máximo local para um campo
- IntlCalendar::getMinimum() - Obtém o mínimo global para um campo

# IntlCalendar::getMinimalDaysInFirstWeek

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getMinimalDaysInFirstWeek — Obtém o número mínimo de dias que a primeira semana do ano ou do mês pode ter

### Descrição

Estilo orientado a objetos

public function IntlCalendar::getMinimalDaysInFirstWeek(): int|false

Estilo procedural

function intlcal_get_minimal_days_in_first_week(IntlCalendar `$calendar`): int|false

Retorna o menor número de dias que a primeira semana do ano ou do mês deve ter no novo ano ou no novo mês. Por exemplo, no calendário gregoriano, se este valor for 1, então a primeira semana do ano necessariamente incluirá 1º de janeiro, enquanto que se este valor for 7, então a semana que contém 1º de janeiro será a primeira semana do ano somente se o dia da semana para 1º de janeiro corresponder ao dia da semana retornado por IntlCalendar::getFirstDayOfWeek(); caso contrário será a última semana do ano anterior.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.

### Valor Retornado

Um int representando o número de dias ou `false` em caso de falha.

### Exemplos

Exemplo #1 IntlCalendar::getMinimalDaysInFirstWeek()

    <?php
    ini_set('date.timezone', 'UTC');
    ini_set('intl.default_locale', 'en_US');

    $cal = new IntlGregorianCalendar(2013, 0 /* janeiro */, 2);
    var_dump(IntlDateFormatter::formatObject($cal, 'cccc')); // quarta-feira

    var_dump($cal->getMinimalDaysInFirstWeek(), // 1
    $cal->getFirstDayofWeek()); // 1 (domingo)

    // Semana 1 de 2013
    var_dump(IntlDateFormatter::formatObject($cal, "'Semana 'w' de 'Y"));

    $cal->setMinimalDaysInFirstWeek(4);
    // Ainda na semana 1 de 2013 (1ª semana tem 5 dias no novo ano)
    var_dump(IntlDateFormatter::formatObject($cal, "'Semana 'w' de 'Y"));

    $cal->setMinimalDaysInFirstWeek(6);
    // Semana 53 de 2012
    var_dump(IntlDateFormatter::formatObject($cal, "'Semana 'w' de 'Y"));

O exemplo acima produzirá:

    string(9) "Wednesday"
    int(1)
    int(1)
    string(14) "Semana 1 de 2013"
    string(14) "Semana 1 de 2013"
    string(15) "Semana 53 de 2012"

# IntlCalendar::getMinimum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getMinimum — Obtém o mínimo global para um campo

### Descrição

Estilo orientado a objetos

public function IntlCalendar::getMinimum(int `$field`): int|false

Estilo procedural

function intlcal_get_minimum(IntlCalendar `$calendar`, int `$field`): int|false

Obtém o mínimo global para um campo, neste calendário específico. Este valor é menos ou igual ao retornado por IntlCalendar::getActualMinimum(), que por sua vez é menor ou igual ao retornado por IntlCalendar::getGreatestMinimum(). Para o calendário gregoriano, estas três funções sempre retornam o mesmo valor (para cada campo).

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.
`field`

  Uma das constantes de campo de data/horário da classe IntlCalendar. São valores inteiros entre `0` e `IntlCalendar::FIELD_COUNT`.

### Valor Retornado

Um int representando um valor para o campo fornecido, na unidade do campo ou `false` em caso de falha.

# IntlCalendar::getNow

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getNow — Obtém um número representando o horário atual

### Descrição

Estilo orientado a objetos

public static function IntlCalendar::getNow(): float

Estilo procedural

function intlcal_get_now(): float

O número de milissegundos que se passaram desde a data de referência. Este número é derivado do horário do sistema.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um float representando um número de milissegundos desde a época, sem contar os segundos intercalares.

### Exemplos

Exemplo #1 Exemplo de IntlCalendar::getNow()

    <?php
    $formatter = IntlDateFormatter::create('es_ES',
            IntlDateFormatter::FULL,
            IntlDateFormatter::FULL,
            'Europe/Madrid');

    $val = IntlCalendar::getNow();

    var_dump($val);
    echo $formatter->format(IntlCalendar::getNow() / 1000.), "\n";

O exemplo acima produzirá:

    float(1371425814666)
    lunes, 17 de junio de 2013 01:36:54 Hora de verano de Europa central

# IntlCalendar::getRepeatedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getRepeatedWallTimeOption — Obtém o comportamento ao lidar com o horário de relógio repetido

### Descrição

Estilo orientado a objetos

public function IntlCalendar::getRepeatedWallTimeOption(): int

Estilo procedural

function intlcal_get_repeated_wall_time_option(IntlCalendar `$calendar`): int

Obtém a estratégia atual para lidar com horários de relógio que se repetem toda vez que o relógio é atrasado durante o retorno de um horário de verão. O valor padrão é `IntlCalendar::WALLTIME_LAST`.

Esta função requer a ICU 4.9 ou posterior.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.

### Valor Retornado

Uma das constantes `IntlCalendar::WALLTIME_FIRST` ou `IntlCalendar::WALLTIME_LAST`.

### Exemplos

Exemplo #1 IntlCalendar::getRepeatedWallTimeOption()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'pt_BR');
    ini_set('intl.error_level', E_WARNING);

    //Em Lisboa, 27 de outubro às 02:00, o relógio volta 1 hora no tempo, de GMT+01 para GMT+00
    $cal = new IntlGregorianCalendar(2013, 9 /* outubro */, 27, 1, 30);

    var_dump($cal->getRepeatedWalltimeOption()); // 0 WALLTIME_LAST

    $formatter = IntlDateFormatter::create(
        NULL,
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'UTC'
    );
    var_dump($formatter->format($cal->getTime() / 1000.));

    $cal->setRepeatedWalltimeOption(IntlCalendar::WALLTIME_FIRST);
    var_dump($cal->getRepeatedWalltimeOption()); // 1 WALLTIME_FIRST
    $cal->set(IntlCalendar::FIELD_HOUR_OF_DAY, 1);

    var_dump($formatter->format($cal->getTime() / 1000.));

O exemplo acima produzirá:

    int(0)
    string(69) "domingo, 27 de outubro de 2013 01:30:00 Horário Universal Coordenado"
    int(1)
    string(69) "domingo, 27 de outubro de 2013 00:30:00 Horário Universal Coordenado"

### Veja Também

- IntlCalendar::getSkippedWallTimeOption() - Obtém o comportamento para o horário de relógio saltado
- IntlCalendar::setSkippedWallTimeOption() - Define o comportamento ao lidar com horário de relógio saltado ao entrar no horário de verão
- IntlCalendar::setRepeatedWallTimeOption() - Define o comportamento ao lidar com horário de relógio repetido ao sair do horário de verão

# IntlCalendar::getSkippedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getSkippedWallTimeOption — Obtém o comportamento para o horário de relógio saltado

### Descrição

Estilo orientado a objetos

public function IntlCalendar::getSkippedWallTimeOption(): int

Estilo procedural

function intlcal_get_skipped_wall_time_option(IntlCalendar `$calendar`): int

Obtém a estratégia atual para lidar com horários de relógio saltados quando o relógio é adiantado durante a transição para o horário de verão. O valor padrão é `IntlCalendar::WALLTIME_LAST`.

O calendário precisa ser leniente para que esta opção tenha algum efeito, caso contrário a tentativa de definir um horário não existente causará um erro.

Esta função requer a ICU 4.9 ou posterior.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.

### Valor Retornado

Uma das constantes `IntlCalendar::WALLTIME_FIRST`, `IntlCalendar::WALLTIME_LAST` ou `IntlCalendar::WALLTIME_NEXT_VALID`.

### Exemplos

Exemplo #1 IntlCalendar::getSkippedWallTimeOption()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'pt_BR');
    ini_set('intl.error_level', E_WARNING);

    //Em Lisboa, no dia 31 de março de 2013 à 01:00, o relógio é adiantado 1 hora, de GMT+00 para GMT+01
    $cal = new IntlGregorianCalendar(2013, 2 /* março */, 31, 1, 30);

    var_dump(
        $cal->isLenient(),               // true
        $cal->getSkippedWalltimeOption() // 0 WALLTIME_LAST
    );

    $formatter = IntlDateFormatter::create(
        NULL,
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'UTC'
    );
    var_dump($formatter->format($cal->getTime() / 1000));

    $cal->setSkippedWallTimeOption(IntlCalendar::WALLTIME_FIRST);
    var_dump($cal->getSkippedWalltimeOption()); // 1 WALLTIME_FIRST
    $cal->set(IntlCalendar::FIELD_HOUR_OF_DAY, 1);

    var_dump($formatter->format($cal->getTime() / 1000));

    $cal->setSkippedWallTimeOption(IntlCalendar::WALLTIME_NEXT_VALID);
    var_dump($cal->getSkippedWalltimeOption()); // 2 WALLTIME_NEXT_VALID
    $cal->set(IntlCalendar::FIELD_HOUR_OF_DAY, 1);

    var_dump($formatter->format($cal->getTime() / 1000));

O exemplo acima produzirá:

    bool(true)
    int(0)
    string(68) "domingo, 31 de março de 2013 01:30:00 Horário Universal Coordenado"
    int(1)
    string(68) "domingo, 31 de março de 2013 00:30:00 Horário Universal Coordenado"
    int(2)
    string(68) "domingo, 31 de março de 2013 01:00:00 Horário Universal Coordenado"

### Veja Também

- IntlCalendar::getRepeatedWallTimeOption() - Obtém o comportamento ao lidar com o horário de relógio repetido
- IntlCalendar::setSkippedWallTimeOption() - Define o comportamento ao lidar com horário de relógio saltado ao entrar no horário de verão
- IntlCalendar::setRepeatedWallTimeOption() - Define o comportamento ao lidar com horário de relógio repetido ao sair do horário de verão

# IntlCalendar::getTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getTime — Obtém o horário atualmente representado pelo objeto

### Descrição

Estilo orientado a objetos

public function IntlCalendar::getTime(): float|false

Estilo procedural

function intlcal_get_time(IntlCalendar `$calendar`): float|false

Retorna o horário associado a este objeto, expresso como o número de milissegundos desde a época de referência.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.

### Valor Retornado

Um float representando o número de milissegundos decorridos desde o horário de referência (1 Jan 1970 00:00:00 UTC), ou `false` em caso de falha

### Exemplos

Exemplo #1 IntlCalendar::getTime()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'pt_BR');

    $cal = new IntlGregorianCalendar(2013, 4 /* maio */, 1, 0, 0, 0);
    $time = $cal->getTime();
    var_dump($time, $time / 1000 == strtotime('2013-05-01 00:00:00')); //true

O exemplo acima produzirá:

    float(1367362800000)
    bool(true)

### Veja Também

- IntlCalendar::getNow() - Obtém um número representando o horário atual

# IntlCalendar::getTimeZone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getTimeZone — Obtém o fuso horário do objeto

### Descrição

Estilo orientado a objetos

public function IntlCalendar::getTimeZone(): IntlTimeZone|false

Estilo procedural

function intlcal_get_time_zone(IntlCalendar `$calendar`): IntlTimeZone|false

Retorna o objeto IntlTimeZone associado a este calendário.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.

### Valor Retornado

Um objeto IntlTimeZone correspondendo ao usado internamente neste objeto. Retorna `false` em caso de falha.

### Exemplos

Exemplo #1 IntlCalendar::getTimeZone()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'pt_BR');

    $cal = IntlCalendar::createInstance();
    print_r($cal->getTimeZone());

    $cal->setTimeZone('UTC');
    print_r($cal->getTimeZone());

    $cal = IntlCalendar::fromDateTime('2012-01-01 00:00:00 GMT+03:33');
    print_r($cal->getTimeZone());

O exemplo acima produzirá:

    IntlTimeZone Object
    (
        [valid] => 1
        [id] => Europe/Lisbon
        [rawOffset] => 0
        [currentOffset] => 0
    )
    IntlTimeZone Object
    (
        [valid] => 1
        [id] => UTC
        [rawOffset] => 0
        [currentOffset] => 0
    )
    IntlTimeZone Object
    (
        [valid] => 1
        [id] => GMT+03:33
        [rawOffset] => 12780000
        [currentOffset] => 12780000
    )

### Veja Também

- IntlCalendar::setTimeZone() - Define o fuso horário usado por este calendário
- IntlCalendar::createInstance() - Cria um novo IntlCalendar
- IntlGregorianCalendar::__construct() - Cria um objeto de calendário gregoriano

# IntlCalendar::getType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getType — Obtém o tipo de calendário

### Descrição

Estilo orientado a objetos

public function IntlCalendar::getType(): string

Estilo procedural

function intlcal_get_type(IntlCalendar `$calendar`): string

Uma string descrevendo o tipo deste calendário. Será um dos valores válidos para a palavra-chave `'calendar'`.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.

### Valor Retornado

Uma string representando o tipo de calendário, como `'gregorian'`, `'islamic'`, etc.

### Exemplos

Exemplo #1 IntlCalendar::getType()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'pt_BR');

    $cal = IntlCalendar::createInstance(NULL, '@calendar=ethiopic-amete-alem');
    var_dump($cal->getType());

    $cal = new IntlGregorianCalendar();
    var_dump($cal->getType());

O exemplo acima produzirá:

    string(19) "ethiopic-amete-alem"
    string(9) "gregorian"

# IntlCalendar::getWeekendTransition

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getWeekendTransition — Obtém o horário do dia no qual o final de semana inicia ou termina

### Descrição

Estilo orientado a objetos

public function IntlCalendar::getWeekendTransition(int `$dayOfWeek`): int|false

Estilo procedural

function intlcal_get_weekend_transition(IntlCalendar `$calendar`, int `$dayOfWeek`): int|false

Retorna o número de milissegundos após a meia-noite quando o final de semana inicia ou termina.

É aplicável somente para dias da semana para os quais IntlCalendar::getDayOfWeekType() retorna `IntlCalendar::DOW_TYPE_WEEKEND_OFFSET` ou `IntlCalendar::DOW_TYPE_WEEKEND_CEASE`. Chamar estas funções para outros dias da semana é uma condição de erro.

Esta função requer a ICU 4.4 ou posterior.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.
`dayOfWeek`

  Uma das constantes `IntlCalendar::DOW_SUNDAY`, `IntlCalendar::DOW_MONDAY`, …, `IntlCalendar::DOW_SATURDAY`.

### Valor Retornado

O número de milissegundos no dia quando o final de semana inicia ou termina ou `false` em caso de falha.

### Exemplos

Vaja exemplo em IntlCalendar::getDayOfWeekType().

# IntlCalendar::inDaylightTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::inDaylightTime — Informa se o horário do objeto está no horário de verão

### Descrição

Estilo orientado a objetos

public function IntlCalendar::inDaylightTime(): bool

Estilo procedural

function intlcal_in_daylight_time(IntlCalendar `$calendar`): bool

Informa se, para o instante representado por este objeto e para o fuso horário deste objeto, o horário de verão estaria em vigor.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.

### Valor Retornado

Retorna `true` se a data estiver no horário de verão, `false` caso contrário.

Em caso de falha, `false` também é retornado. Para detectar condições de erro, use intl_get_error_code() ou configure Intl para lançar exceções.

### Exemplos

Exemplo #1 IntlCalendar::inDaylightTime()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'pt_PT');

    $cal = new IntlGregorianCalendar(2013, 6 /* julho */, 1, 4, 56, 31);
    var_dump($cal->inDaylightTime()); // true
    $cal->set(IntlCalendar::FIELD_MONTH, 11 /* dezembro */);
    var_dump($cal->inDaylightTime()); // false

    // Horário de verão transiciona de volta no dia 2013-10-27 às 0200 (volta 1 hora)
    $cal = new IntlGregorianCalendar(2013, 9 /* October */, 27, 1, 30, 0);

    var_dump($cal->inDaylightTime()); // false (padrão WALLTIME_LAST)

    $cal->setRepeatedWallTimeOption(IntlCalendar::WALLTIME_FIRST);
    $cal->set(IntlCalendar::FIELD_HOUR_OF_DAY, 1); // força recálculo do horário
    var_dump($cal->inDaylightTime()); // true

# IntlCalendar::isEquivalentTo

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::isEquivalentTo — Verifica se outro calendário é igual exceto pelo horário

### Descrição

Estilo orientado a objetos

public function IntlCalendar::isEquivalentTo(IntlCalendar `$other`): bool

Estilo procedural

function intlcal_is_equivalent_to(IntlCalendar `$calendar`, IntlCalendar `$other`): bool

Retorna se este objeto e o objeto informado são equivalentes para todos os propósitos exceto pelo horário definido neles. As localidades não precisam corresponder, desde que nenhuma mudança no comportamento resulte em diferenças. Isto inclui o fuso horário, se o modo leniente está definido, as configurações de horários de relógio repetidos e saltados, os dias da semana onde o final de semana inicia e termina e os horários onde tais transições ocorrem. A comparação também pode incluir outras configurações específicas de calendário, tal como o instante de transição do calendário juliano para o gregoriano.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.
`other`

  O outro calendário com o qual a comparação será realizada.

### Valor Retornado

Assumindo que não haja erros de argumentos, retorna `true` se os calendários forem equivalentes exceto possivelmente pelo horário definido neles.

### Exemplos

Exemplo #1 IntlCalendar::isEquivalentTo()

    <?php
    $cal1 = IntlCalendar::createInstance('Europe/Lisbon', 'pt_BR');
    $cal2 = IntlCalendar::createInstance('Europe/Lisbon', 'en_US');
    $cal2->clear();

    var_dump($cal1->isEquivalentTo($cal2)); // true

    $cal3 = IntlCalendar::createInstance('Europe/Lisbon', 'es_ES');
    var_dump($cal1->isEquivalentTo($cal3)); // false
    var_dump($cal1->getFirstDayOfWeek(),    // 1 (domingo)
    $cal3->getFirstDayOfWeek());            // 2 (segunda-feira)

O exemplo acima produzirá:

    bool(true)
    bool(false)
    int(1)
    int(2)

### Veja Também

- IntlCalendar::equals() - Compara horários de dois objetos IntlCalendar para igualidade

# IntlCalendar::isLenient

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::isLenient — Verifica se a interpretação de data/horário está no modo leniente

### Descrição

Estilo orientado a objetos

public function IntlCalendar::isLenient(): bool

Estilo procedural

function intlcal_is_lenient(IntlCalendar `$calendar`): bool

Retorna se a interpretação atual de data/horário está no modo leniente (o padrão). Se for este o caso, alguns valores que estejam fora dos limites para seus campos serão aceitos ao invés de disparar um erro.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.

### Valor Retornado

Um bool representando se o calendário está definido para modo leniente.

### Exemplos

Exemplo #1 IntlCalendar::isLenient()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'pt_PT');
    ini_set('intl.use_exceptions', '1');

    $cal = new IntlGregorianCalendar(2013, 6 /* julho */, 1);
    var_dump(IntlDateFormatter::formatObject($cal), // 01/07/2013, 00:00:00
    $cal->isLenient()); // true

    $cal->set(IntlCalendar::FIELD_DAY_OF_MONTH, 33);
    var_dump(IntlDateFormatter::formatObject($cal)); // 02/08/2013, 00:00:00

    $cal->setLenient(false);
    var_dump($cal->isLenient()); // false
    $cal->set(IntlCalendar::FIELD_DAY_OF_MONTH, 33);
    var_dump(IntlDateFormatter::formatObject($cal)); // erro

O exemplo acima produzirá:

    string(20) "01/07/2013, 00:00:00"
    bool(true)
    string(20) "02/08/2013, 00:00:00"
    bool(false)

    Fatal error: Uncaught IntlException: datefmt_format_object: error obtaining instant from IntlCalendar in /home/foobar/example.php:16
    Stack trace:
    #0 /home/foobar/example.php(16): IntlDateFormatter::formatObject()
    #1 {main}
      thrown in /home/foobar/example.php on line 16

# IntlCalendar::isSet

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::isSet — Verifica se um campo está definido

### Descrição

Estilo orientado a objetos

public function IntlCalendar::isSet(int `$field`): bool

Estilo procedural

function intlcal_is_set(IntlCalendar `$calendar`, int `$field`): bool

Retorna se um campo está definido (o oposto de clear). Campos definidos têm prioridade sobre campos indefinidos e sobre seus valores padrão quando a data e horário estão sendo calculados. Campos definidos mais tarde têm prioridade sobre campos definidos mais cedo.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.
`field`

  Uma das constantes de campo de data/horário da classe IntlCalendar. São valores inteiros entre `0` e `IntlCalendar::FIELD_COUNT`.

### Valor Retornado

Assumindo que não haja erros de argumentos, retorna `true` se o campo estiver definido.

### Exemplos

Veja o exemplo em IntlCalendar::clear().

### Veja Também

- IntlCalendar::clear() - Limpa um campo ou todos os campos
- IntlCalendar::set() - Define um campo de horário ou vários campos comuns de uma vez

# IntlCalendar::isWeekend

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::isWeekend — Verifica se uma data e um horário estão no final de semana

### Descrição

Estilo orientado a objetos

public function IntlCalendar::isWeekend(?float `$timestamp` = `null`): bool

Estilo procedural

function intlcal_is_weekend(IntlCalendar `$calendar`, ?float `$timestamp` = `null`): bool

Retorna se o horário atual do objeto ou o timestamp fornecido ocorrem durante um final de semana no sistema de calendário deste objeto.

Esta função requer a ICU 4.4 ou posterior.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.
`timestamp`

  Um timestamp opcional representando o número de milissegundos desde a época de referência, excluindo os segundos intercalares. Se for `null`, o horário atual do objeto é utilizado.

### Valor Retornado

Um bool indicando se o horário fornecido ou do objeto ocorre em um final de semana.

Em caso de falha, `false` também é retornado. Para detectar condições de erro, use intl_get_error_code() ou configure Intl para lançar exceções.

### Exemplos

Exemplo #1 IntlCalendar::isWeekend()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');

    $cal = new IntlGregorianCalendar(NULL, 'en_US');
    $cal->set(2013, 6 /* julho */, 7); // um domingo

    var_dump($cal->isWeekend()); // true
    var_dump($cal->isWeekend(strtotime('2013-07-01 00:00:00'))); // false, segunda-feira

    $cal = new IntlGregorianCalendar(NULL, 'ar_SA');
    $cal->set(2013, 6 /* julho */, 7); // um domingo
    var_dump($cal->isWeekend()); // false, domingo não está no final de semana neste calendário

### Veja Também

- IntlCalendar::getDayOfWeekType() - Informa se o dia é dia de semana, de final de semana ou de transição entre os dois
- IntlCalendar::getWeekendTransition() - Obtém o horário do dia no qual o final de semana inicia ou termina

# IntlCalendar::roll

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::roll — Adiciona valor ao campo sem transferir para campos mais significativos

### Descrição

Estilo orientado a objetos

public function IntlCalendar::roll(int `$field`, int|bool `$value`): bool

Estilo procedural

function intlcal_roll(IntlCalendar `$calendar`, int `$field`, int|bool `$value`): bool

Adiciona uma quantidade (com sinal) a um campo. A diferença em relação a IntlCalendar::add() é que quando o valor do campo passar do limite, a função não transfere este transbordamento para campos mais significativos.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.
`field`

  Uma das constantes de campo de data/horário da classe IntlCalendar. São valores inteiros entre `0` e `IntlCalendar::FIELD_COUNT`.

`value`

  A quantidade (com sinal) para adicionar ao campo, `true` para aumentar (adicionar `1`), ou `false` para reduzir (subtrair `1`).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 IntlCalendar::roll()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'pt_PT');

    $cal = new IntlGregorianCalendar(2013, 5 /* junho */, 30);

    $cal->add(IntlCalendar::FIELD_DAY_OF_MONTH, 1);
    var_dump(IntlDateFormatter::formatObject($cal)); // "01/07/2013, 00:00:00"

    $cal->set(2013, 5 /* junho */, 30);
    $cal->roll(IntlCalendar::FIELD_DAY_OF_MONTH, true); // soma +1
    var_dump(IntlDateFormatter::formatObject($cal)); // "01/06/2013, 00:00:00"

O exemplo acima produzirá:

    string(20) "01/07/2013, 00:00:00"
    string(20) "01/06/2013, 00:00:00"

### Veja Também

- IntlCalendar::add() - Adiciona uma quantidade de tempo (com sinal) a um campo
- IntlCalendar::set() - Define um campo de horário ou vários campos comuns de uma vez

# IntlCalendar::set

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::set — Define um campo de horário ou vários campos comuns de uma vez

### Descrição

Estilo orientado a objetos

public function IntlCalendar::set(int `$field`, int `$value`): true
public function IntlCalendar::set(
int `$year`,
int `$month`,
int `$dayOfMonth` = NULL,
int `$hour` = NULL,
int `$minute` = NULL,
int `$second` = NULL
): true

Estilo procedural

function intlcal_set(IntlCalendar `$cal`, int `$field`, int `$value`): true
function intlcal_set(
IntlCalendar `$cal`,
int `$year`,
int `$month`,
int `$dayOfMonth` = NULL,
int `$hour` = NULL,
int `$minute` = NULL,
int `$second` = NULL
): bool

Define um campo específico para o valor fornecido, ou define de uma só vez vários campos comuns. O intervalo de valores aceitos depende se o calendário está usado o modo leniente.

Para campos que conflitarem entre si, os campos que forem definidos mais tarde têm prioridade.

Este método não pode ser chamado com exatamente quatro argumentos.

### Parâmetros

`cal`
  Uma instância de IntlCalendar.
`field`

  Uma das constantes de campo de data/horário da classe IntlCalendar. São valores inteiros entre `0` e `IntlCalendar::FIELD_COUNT`.

`value`

  O novo valor para o campo informado.

`year`

  O novo valor para `IntlCalendar::FIELD_YEAR`.

`month`

  O novo valor para `IntlCalendar::FIELD_MONTH`. A sequência de meses é baseada em zero, isto é, janeiro é representado por 0, fevereiro por 1, …, dezembro é 11 e undecember (se o calendário tiver) é 12.

`dayOfMonth`

  O novo valor para `IntlCalendar::FIELD_DAY_OF_MONTH`.

`hour`

  O novo valor para `IntlCalendar::FIELD_HOUR_OF_DAY`.

`minute`

  O novo valor para `IntlCalendar::FIELD_MINUTE`.

`second`

  O novo valor para `IntlCalendar::FIELD_SECOND`.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.2.0 | O tipo do retorno agora é `true`; anteriormente, era bool.
8.4.0 | Este método foi descontinuado em favor dos métodos IntlCalendar::setDate() e IntlCalendar::setDateTime().

### Exemplos

Exemplo #1 IntlCalendar::set()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'pt_PT');

    // Chamadas feitas mais tarde têm prioridade
    $cal = new IntlGregorianCalendar(2013, 6 /* julho */, 1);
    $cal->set(IntlCalendar::FIELD_YEAR, 2012);
    $cal->set(IntlCalendar::FIELD_EXTENDED_YEAR, 2011);
    var_dump(IntlDateFormatter::formatObject($cal));

    $cal = new IntlGregorianCalendar(2013, 6 /* julho */, 1);
    $cal->set(IntlCalendar::FIELD_YEAR, 2012);
    $cal->set(IntlCalendar::FIELD_EXTENDED_YEAR, 2011);
    // O horário não foi recalculado ainda. Se o ano estendido for limpo,
    // o ano definido anteriormente será usado
    $cal->clear(IntlCalendar::FIELD_EXTENDED_YEAR);
    var_dump(IntlDateFormatter::formatObject($cal));

O exemplo acima produzirá:

    string(20) "01/07/2011, 00:00:00"
    string(20) "01/07/2012, 00:00:00"

### Veja Também

- IntlCalendar::get() - Obtém o valor de um campo
- IntlCalendar::add() - Adiciona uma quantidade de tempo (com sinal) a um campo
- IntlCalendar::roll() - Adiciona valor ao campo sem transferir para campos mais significativos

# IntlCalendar::setDate

(PHP 8 >= 8.3.0)

IntlCalendar::setDate — Define campos de data

### Descrição

public function IntlCalendar::setDate(int `$year`, int `$month`, int `$dayOfMonth`): void

Define os campos de data para os valores fornecidos.

### Parâmetros

`year`

  O novo valor para `IntlCalendar::FIELD_YEAR`.

`month`

  O novo valor para `IntlCalendar::FIELD_MONTH`. A sequência de meses é baseada em zero, isto é, janeiro é representado por 0, fevereiro por 1, …, dezembro é 11 e undecember (se o calendário tiver) é 12.

`dayOfMonth`

  O novo valor para `IntlCalendar::FIELD_DAY_OF_MONTH`.

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de IntlCalendar::setDate()

    <?php
    $intlCal = IntlCalendar::createInstance('UTC');

    $intlCal->setDate(2012, 1 /* fevereiro */, 29);
    ?>

# IntlCalendar::setDateTime

(PHP 8 >= 8.3.0)

IntlCalendar::setDateTime — Define campos de data e horário

### Descrição

public function IntlCalendar::setDateTime(
int `$year`,
int `$month`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
?int `$second` = `null`
): void

Define campos de data e horário para os valores fornecidos.

### Parâmetros

`year`

  O novo valor para `IntlCalendar::FIELD_YEAR`.

`month`

  O novo valor para `IntlCalendar::FIELD_MONTH`. A sequência de meses é baseada em zero, isto é, janeiro é representado por 0, fevereiro por 1, …, dezembro é 11 e undecember (se o calendário tiver) é 12.

`dayOfMonth`

  O novo valor para `IntlCalendar::FIELD_DAY_OF_MONTH`.

`hour`

  O novo valor para `IntlCalendar::FIELD_HOUR_OF_DAY`.

`minute`

  O novo valor para `IntlCalendar::FIELD_MINUTE`.

`second`

  O novo valor para `IntlCalendar::FIELD_SECOND`.

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de IntlCalendar::setDateTime()

    <?php
    $intlCal = IntlCalendar::createInstance('UTC');

    $intlCal->setDateTime(2012, 1 /* fevereiro */, 29, 23, 58);
    ?>

# IntlCalendar::setFirstDayOfWeek

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setFirstDayOfWeek — Define o dia da semana no qual a semana inicia

### Descrição

Estilo orientado a objetos

public function IntlCalendar::setFirstDayOfWeek(int `$dayOfWeek`): true

Estilo procedural

function intlcal_set_first_day_of_week(IntlCalendar `$calendar`, int `$dayOfWeek`): true

Define o dia da semana no qual a semana inicia. Isto afeta o comportamento de campos que dependem do conceito de início e fim da semana tais como `IntlCalendar::FIELD_WEEK_OF_YEAR` e `IntlCalendar::FIELD_YEAR_WOY`.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.
`dayOfWeek`

  Uma das constantes `IntlCalendar::DOW_SUNDAY`, `IntlCalendar::DOW_MONDAY`, …, `IntlCalendar::DOW_SATURDAY`.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.2.0 | O tipo do retorno agora é `true`; anteriormente, era bool.

### Exemplos

Exemplo #1 IntlCalendar::setFirstDayOfWeek()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'es_ES');

    $cal = IntlCalendar::createInstance();
    $cal->set(2013, 5 /* junho */, 30); // um domingo

    var_dump($cal->getFirstDayOfWeek()); // 2 (segunda-feira)

    echo IntlDateFormatter::formatObject($cal, <<<EOD
    'dia da semana local: 'cc'
    semana do mês    : 'W'
    semana do ano     : 'ww
    EOD
    ), "\n";

    $cal->setFirstDayOfWeek(IntlCalendar::DOW_SUNDAY);

    echo IntlDateFormatter::formatObject($cal, <<<EOD
    'dia da semana local: 'cc'
    semana do mês    : 'W'
    semana do ano     : 'ww
    EOD
    ), "\n";

O exemplo acima produzirá:

    int(2)
    dia da semana local: 7
    semana do mês    : 4
    semana do ano     : 26
    dia da semana local: 1
    semana do mês    : 5
    semana do ano     : 27

# IntlCalendar::setLenient

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setLenient — Define se a interpretação de data/horário deve ser leniente

### Descrição

Estilo orientado a objetos

public function IntlCalendar::setLenient(bool `$lenient`): true

Estilo procedural

function intlcal_set_lenient(IntlCalendar `$calendar`, bool `$lenient`): true

Define se o calendário deve estar no ‘modo leniente’. Neste modo, alguns valores fora dos limites para alguns campos são aceitos, com comportamento similar ao da função IntlCalendar::add() (isto é, o valor transborda, carregando os campos mais significativos a cada vez que isso acontece). Se o modo leniente estiver desabilitado, tais valores irão gerar um erro.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.
`lenient`

  Use `true` para habilitar o modo leniente; `false` para desabilitar.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.2.0 | O tipo do retorno agora é `true`; anteriormente, era bool.

### Exemplos

Veja o exemplo em IntlCalendar::isLenient().

# IntlCalendar::setMinimalDaysInFirstWeek

(PHP 5 >= 5.5.1, PHP 7, PHP 8)

IntlCalendar::setMinimalDaysInFirstWeek — Define o número mínimo de dias que a primeira semana do ano ou do mês pode ter

### Descrição

Estilo orientado a objetos

public function IntlCalendar::setMinimalDaysInFirstWeek(int `$days`): true

Estilo procedural

function intlcal_set_minimal_days_in_first_week(IntlCalendar `$calendar`, int `$days`): true

Define o menor número de dias que a primeira semana do ano ou do mês precisa ter no novo ano ou no novo mês. Por exemplo, no calendário gregoriano, se este valor for 1, então a primeira semana do ano incluirá necessariamente o dia 1º de janeiro, enquanto que se este valor for 7, então a semana com o dia 1º de janeiro será a primeira semana do ano somente se o dia da semana para 1º de janeiro corresponder ao dia da semana retornado por IntlCalendar::getFirstDayOfWeek(); caso contrário será a última semana do ano anterior.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.
`days`

  O número mínimo de dias a ser definido.

### Valor Retornado

Sempre retorna `true`.

### Erros/Exceções

ValueError se `days` estiver fora do intervalo (menos que `1` ou mais que `7`).

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Um ValueError agora é lançado em caso de entrada inválida. Anteriormente, `false` era retornado.

# IntlCalendar::setRepeatedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setRepeatedWallTimeOption — Define o comportamento ao lidar com horário de relógio repetido ao sair do horário de verão

### Descrição

Estilo orientado a objetos

public function IntlCalendar::setRepeatedWallTimeOption(int `$option`): true

Estilo procedural

function intlcal_set_repeated_wall_time_option(IntlCalendar `$calendar`, int `$option`): true

Define a estratégia atual para lidar com horários de relógio que se repetem ao voltar o relógio no final do horário de verão. O valor padrão é `IntlCalendar::WALLTIME_LAST` (considera o instante após a transição). O outro valor possível é `IntlCalendar::WALLTIME_FIRST` (considera o instante que ocorre antes da transição).

Esta função requer a ICU 4.9 ou posterior.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.
`option`

  Uma das constantes `IntlCalendar::WALLTIME_FIRST` ou `IntlCalendar::WALLTIME_LAST`.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.2.0 | O tipo do retorno agora é `true`; anteriormente, era bool.

### Exemplos

Veja o exemplo em IntlCalendar::getRepeatedWallTimeOption().

### Veja Também

- intlCalendar::getRepeatedWallTimeOption() - Obtém o comportamento ao lidar com o horário de relógio repetido
- intlCalendar::setSkippedWallTimeOption() - Define o comportamento ao lidar com horário de relógio saltado ao entrar no horário de verão
- intlCalendar::getSkippedWallTimeOption() - Obtém o comportamento para o horário de relógio saltado

# IntlCalendar::setSkippedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setSkippedWallTimeOption — Define o comportamento ao lidar com horário de relógio saltado ao entrar no horário de verão

### Descrição

Estilo orientado a objetos

public function IntlCalendar::setSkippedWallTimeOption(int `$option`): true

Estilo procedural

function intlcal_set_skipped_wall_time_option(IntlCalendar `$calendar`, int `$option`): true

Define a estratégia atual para lidar com horários de relógio que são saltados ao adiantar o relógio no início do horário de verão. O valor padrão é `IntlCalendar::WALLTIME_LAST` (considera como o mesmo instante do tempo em que o horário do relógio é uma hora a mais). Valores alternativos são `IntlCalendar::WALLTIME_FIRST` (mesmo instante daquele com horário de relógio com uma hora a menos) e `IntlCalendar::WALLTIME_NEXT_VALID` (mesmo instante em que o horário de verão inicia).

Isto afeta apenas o instante representado pelo calendário (como reportado por IntlCalendar::getTime()), os valores de campo não serão re-escritos de acordo.

O calendário precisa estar em modo leniente para que esta opção tenha algum efeito, caso contrário a tentativa de se definir um horário não existente irá causar um erro.

Esta função requer a ICU 4.9 ou posterior.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.
`option`

  Uma das constantes `IntlCalendar::WALLTIME_FIRST`, `IntlCalendar::WALLTIME_LAST` ou `IntlCalendar::WALLTIME_NEXT_VALID`.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.2.0 | O tipo do retorno agora é `true`; anteriormente, era bool.

### Exemplos

Veja o exemplo em IntlCalendar::getSkippedWallTimeOption().

### Veja Também

- intlCalendar::getSkippedWallTimeOption() - Obtém o comportamento para o horário de relógio saltado
- intlCalendar::setRepeatedWallTimeOption() - Define o comportamento ao lidar com horário de relógio repetido ao sair do horário de verão
- intlCalendar::getRepeatedWallTimeOption() - Obtém o comportamento ao lidar com o horário de relógio repetido

# IntlCalendar::setTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setTime — Define o horário do calendário em milissegundos desde a época de referência

### Descrição

Estilo orientado a objetos

public function IntlCalendar::setTime(float `$timestamp`): bool

Estilo procedural

function intlcal_set_time(IntlCalendar `$calendar`, float `$timestamp`): bool

Define o instante representado por este objeto. O instante é representado por um float cujo valor deve ser um número inteiro de milissegundos desde a época de referência (1 Jan 1970 00:00:00.000 UTC), ignorando segundos intercalares. Todos os valores de campo serão recalculados de acordo.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.
`timestamp`

  Um instante representado pelo número de milissegundos desde a época de referência, ignorando segundos intercalares.

### Valor Retornado

Retorna `true` em caso de sucesso e `false` em caso de falha.

### Exemplos

Exemplo #1 IntlCalendar::setTime()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'fr_FR');

    $cal = new IntlGregorianCalendar(2013, 5 /* maio */, 1, 12, 0, 0);

    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";

    /* Em Lisboa, em 2013-10-27 at 0200, o relógio volta uma hora e
       o fuso horário passa de UTC+01 para UTC+00 */

    $cal->setTime(strtotime('2013-10-27 00:30:00 UTC') * 1000.);

    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";

    $cal->setTime(strtotime('2013-10-27 01:30:00 UTC') * 1000.);

    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";

O exemplo acima produzirá:

    samedi 1 juin 2013 12:00:00 heure avancée d’Europe de l’Ouest
    dimanche 27 octobre 2013 01:30:00 heure avancée d’Europe de l’Ouest
    dimanche 27 octobre 2013 01:30:00 heure normale d’Europe de l’Ouest

# IntlCalendar::setTimeZone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setTimeZone — Define o fuso horário usado por este calendário

### Descrição

Estilo orientado a objetos

public function IntlCalendar::setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool

Estilo procedural

function intlcal_set_time_zone(IntlCalendar `$calendar`, IntlTimeZone|DateTimeZone|string|null `$timezone`): bool

Define um novo fuso horário para este calendário. O horário representado pelo objeto é preservado em detrimento dos valores de campo.

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.
`timezone`

  O novo fuso horário a ser usado por este calendário. Pode ser especificado das seguintes maneiras:

  - `null`, neste caso o fuso horário padrão será usado, como especificado na configuração ini date.timezone ou através da função date_default_timezone_set() e como retornado por date_default_timezone_get().

  - Um objeto IntlTimeZone, que será usado diretamente.

  - Um objeto DateTimeZone. Seu identificador será extraído e um objeto de fuso horário ICU será criado; o fuso horário será apoiado pelo banco de dados da ICU, não pelo do PHP.

  - Uma string, que deve ser um identificador de fuso horário ICU válido. Consulte a função IntlTimeZone::createTimeZoneIDEnumeration(). Deslocamentos puros como `"GMT+08:30"` também são aceitos.

### Valor Retornado

Retorna `true` em caso de sucesso e `false` em caso de falha.

### Exemplos

Exemplo #1 IntlCalendar::setTimeZone()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'es_ES');

    $cal = new IntlGregorianCalendar(2013, 5 /* maio */, 1, 12, 0, 0);

    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";
    echo "(instant {$cal->getTime()})\n";

    $cal->setTimeZone(IntlTimeZone::getGMT());
    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";
    echo "(instant {$cal->getTime()})\n";

    $cal->setTimeZone('GMT+03:33');
    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";
    echo "(instant {$cal->getTime()})\n";

O exemplo acima produzirá:

    sábado, 1 de junio de 2013 12:00:00 Hora de verano de Europa occidental
    (instant 1370084400000)
    sábado, 1 de junio de 2013 11:00:00 GMT
    (instant 1370084400000)
    sábado, 1 de junio de 2013 14:33:00 GMT+03:33
    (instant 1370084400000)

# IntlCalendar::toDateTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a2)

IntlCalendar::toDateTime — Converte um objeto IntlCalendar para um DateTime

### Descrição

Estilo orientado a objetos

public function IntlCalendar::toDateTime(): DateTime|false

Estilo procedural

function intlcal_to_date_time(IntlCalendar `$calendar`): DateTime|false

Cria um objeto DateTime que representa o mesmo instante (até a precisão de segundos, com um erro de arredondamento de menos de 1 segundo) e que tenha um fuso horário análogo a este objeto (a diferença sendo que o fuso horário de DateTime será suportado pelo PHP enquanto que o fuso horário de IntlCalendar será suportado pela ICU).

### Parâmetros

`calendar`
  Uma instância de IntlCalendar.

### Valor Retornado

Um objeto DateTime com o mesmo fuso horário deste objeto (embora usando o banco de dados do PHP no lugar do banco da ICU) e com o mesmo horário, exceto pela precisão menos (precisão de segundos ao invés de milissegundos). Retorna `false` em caso de falha.

### Exemplos

Exemplo #1 IntlCalendar::toDateTime()

    <?php
    ini_set('date.timezone', 'UTC');
    ini_set('intl.default_locale', 'pt_PT');

    $cal = IntlCalendar::createInstance('Europe/Lisbon'); //horário atual

    $dt = $cal->toDateTime();
    print_r($dt);

O exemplo acima produzirá:

    DateTime Object
    (
        [date] => 2024-01-24 13:32:05.000000
        [timezone_type] => 3
        [timezone] => Europe/Lisbon
    )

### Veja Também

- IntlCalendar::fromDateTime() - Cria um IntlCalendar a partir de um objeto DateTime ou uma string
- IntlCalendar::getTime() - Obtém o horário atualmente representado pelo objeto
- IntlCalendar::createInstance() - Cria um novo IntlCalendar
- DateTime::__construct() - Retorna um novo objeto DateTime

## Índice

- IntlCalendar::add — Adiciona uma quantidade de tempo (com sinal) a um campo
- IntlCalendar::after — Informa se o instante de tempo deste objeto é posterior ao instante do objeto passado
- IntlCalendar::before — Informa se o instante de tempo deste objeto é anterior ao instante do objeto passado
- IntlCalendar::clear — Limpa um campo ou todos os campos
- IntlCalendar::__construct — Construtor privado para não permitir instanciação
- IntlCalendar::createInstance — Cria um novo IntlCalendar
- IntlCalendar::equals — Compara horários de dois objetos IntlCalendar para igualidade
- IntlCalendar::fieldDifference — Calcula a diferença entre o horário fornecido e o horário deste objeto
- IntlCalendar::fromDateTime — Cria um IntlCalendar a partir de um objeto DateTime ou uma string
- IntlCalendar::get — Obtém o valor de um campo
- IntlCalendar::getActualMaximum — O valor máximo para um campo, considerando o horário atual do objeto
- IntlCalendar::getActualMinimum — O valor mínimo para um campo, considerando o horário atual do objeto
- IntlCalendar::getAvailableLocales — Obtém um array de localidades para as quais existem dados
- IntlCalendar::getDayOfWeekType — Informa se o dia é dia de semana, de final de semana ou de transição entre os dois
- IntlCalendar::getErrorCode — Obtém o último código de erro no objeto
- IntlCalendar::getErrorMessage — Obtém a última mensagem de erro no objeto
- IntlCalendar::getFirstDayOfWeek — Obtém o primeiro dia da semana para a localidade do calendário
- IntlCalendar::getGreatestMinimum — Obtém o maior valor mínimo local para um campo
- IntlCalendar::getKeywordValuesForLocale — Obtém um conjunto de valores de palavras-chaves de localidade
- IntlCalendar::getLeastMaximum — Obtém o menor máximo local para um campo
- IntlCalendar::getLocale — Obtém a localidade associada com o objeto
- IntlCalendar::getMaximum — Obtém o valor máximo global para um campo
- IntlCalendar::getMinimalDaysInFirstWeek — Obtém o número mínimo de dias que a primeira semana do ano ou do mês pode ter
- IntlCalendar::getMinimum — Obtém o mínimo global para um campo
- IntlCalendar::getNow — Obtém um número representando o horário atual
- IntlCalendar::getRepeatedWallTimeOption — Obtém o comportamento ao lidar com o horário de relógio repetido
- IntlCalendar::getSkippedWallTimeOption — Obtém o comportamento para o horário de relógio saltado
- IntlCalendar::getTime — Obtém o horário atualmente representado pelo objeto
- IntlCalendar::getTimeZone — Obtém o fuso horário do objeto
- IntlCalendar::getType — Obtém o tipo de calendário
- IntlCalendar::getWeekendTransition — Obtém o horário do dia no qual o final de semana inicia ou termina
- IntlCalendar::inDaylightTime — Informa se o horário do objeto está no horário de verão
- IntlCalendar::isEquivalentTo — Verifica se outro calendário é igual exceto pelo horário
- IntlCalendar::isLenient — Verifica se a interpretação de data/horário está no modo leniente
- IntlCalendar::isSet — Verifica se um campo está definido
- IntlCalendar::isWeekend — Verifica se uma data e um horário estão no final de semana
- IntlCalendar::roll — Adiciona valor ao campo sem transferir para campos mais significativos
- IntlCalendar::set — Define um campo de horário ou vários campos comuns de uma vez
- IntlCalendar::setDate — Define campos de data
- IntlCalendar::setDateTime — Define campos de data e horário
- IntlCalendar::setFirstDayOfWeek — Define o dia da semana no qual a semana inicia
- IntlCalendar::setLenient — Define se a interpretação de data/horário deve ser leniente
- IntlCalendar::setMinimalDaysInFirstWeek — Define o número mínimo de dias que a primeira semana do ano ou do mês pode ter
- IntlCalendar::setRepeatedWallTimeOption — Define o comportamento ao lidar com horário de relógio repetido ao sair do horário de verão
- IntlCalendar::setSkippedWallTimeOption — Define o comportamento ao lidar com horário de relógio saltado ao entrar no horário de verão
- IntlCalendar::setTime — Define o horário do calendário em milissegundos desde a época de referência
- IntlCalendar::setTimeZone — Define o fuso horário usado por este calendário
- IntlCalendar::toDateTime — Converte um objeto IntlCalendar para um DateTime

# A classe IntlGregorianCalendar

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introdução

## Resumo da classe

class IntlGregorianCalendar extends IntlCalendar {
/* Constantes herdadas */
public const int IntlCalendar::FIELD_ERA;
public const int IntlCalendar::FIELD_YEAR;
public const int IntlCalendar::FIELD_MONTH;
public const int IntlCalendar::FIELD_WEEK_OF_YEAR;
public const int IntlCalendar::FIELD_WEEK_OF_MONTH;
public const int IntlCalendar::FIELD_DATE;
public const int IntlCalendar::FIELD_DAY_OF_YEAR;
public const int IntlCalendar::FIELD_DAY_OF_WEEK;
public const int IntlCalendar::FIELD_DAY_OF_WEEK_IN_MONTH;
public const int IntlCalendar::FIELD_AM_PM;
public const int IntlCalendar::FIELD_HOUR;
public const int IntlCalendar::FIELD_HOUR_OF_DAY;
public const int IntlCalendar::FIELD_MINUTE;
public const int IntlCalendar::FIELD_SECOND;
public const int IntlCalendar::FIELD_MILLISECOND;
public const int IntlCalendar::FIELD_ZONE_OFFSET;
public const int IntlCalendar::FIELD_DST_OFFSET;
public const int IntlCalendar::FIELD_YEAR_WOY;
public const int IntlCalendar::FIELD_DOW_LOCAL;
public const int IntlCalendar::FIELD_EXTENDED_YEAR;
public const int IntlCalendar::FIELD_JULIAN_DAY;
public const int IntlCalendar::FIELD_MILLISECONDS_IN_DAY;
public const int IntlCalendar::FIELD_IS_LEAP_MONTH;
public const int IntlCalendar::FIELD_FIELD_COUNT;
public const int IntlCalendar::FIELD_DAY_OF_MONTH;
public const int IntlCalendar::DOW_SUNDAY;
public const int IntlCalendar::DOW_MONDAY;
public const int IntlCalendar::DOW_TUESDAY;
public const int IntlCalendar::DOW_WEDNESDAY;
public const int IntlCalendar::DOW_THURSDAY;
public const int IntlCalendar::DOW_FRIDAY;
public const int IntlCalendar::DOW_SATURDAY;
public const int IntlCalendar::DOW_TYPE_WEEKDAY;
public const int IntlCalendar::DOW_TYPE_WEEKEND;
public const int IntlCalendar::DOW_TYPE_WEEKEND_OFFSET;
public const int IntlCalendar::DOW_TYPE_WEEKEND_CEASE;
public const int IntlCalendar::WALLTIME_FIRST;
public const int IntlCalendar::WALLTIME_LAST;
public const int IntlCalendar::WALLTIME_NEXT_VALID;
/* Métodos */
public function __construct(IntlTimeZone `$tz` = ?, string `$locale` = ?)
public function __construct(int `$timeZoneOrYear`, int `$localeOrMonth`, int `$dayOfMonth`)
public function __construct(
int `$timeZoneOrYear`,
int `$localeOrMonth`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
int `$second` = ?
)
public static function createFromDate(int `$year`, int `$month`, int `$dayOfMonth`): static
public static function createFromDateTime(
int `$year`,
int `$month`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
?int `$second` = `null`
): static
public function getGregorianChange(): float
public function isLeapYear(int `$year`): bool
public function setGregorianChange(float `$timestamp`): bool
/* Métodos herdados */
public function IntlCalendar::add(int `$field`, int `$value`): bool
public function IntlCalendar::after(IntlCalendar `$other`): bool
public function IntlCalendar::before(IntlCalendar `$other`): bool
public function IntlCalendar::clear(?int `$field` = `null`): true
public static function IntlCalendar::createInstance(IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`, ?string `$locale` = `null`): ?IntlCalendar
public function IntlCalendar::equals(IntlCalendar `$other`): bool
public function IntlCalendar::fieldDifference(float `$timestamp`, int `$field`): int|false
public static function IntlCalendar::fromDateTime(DateTime|string `$datetime`, ?string `$locale` = `null`): ?IntlCalendar
public function IntlCalendar::get(int `$field`): int|false
public function IntlCalendar::getActualMaximum(int `$field`): int|false
public function IntlCalendar::getActualMinimum(int `$field`): int|false
public static function IntlCalendar::getAvailableLocales(): array
public function IntlCalendar::getDayOfWeekType(int `$dayOfWeek`): int|false
public function IntlCalendar::getErrorCode(): int|false
public function IntlCalendar::getErrorMessage(): string|false
public function IntlCalendar::getFirstDayOfWeek(): int|false
public function IntlCalendar::getGreatestMinimum(int `$field`): int|false
public static function IntlCalendar::getKeywordValuesForLocale(string `$keyword`, string `$locale`, bool `$onlyCommon`): IntlIterator|false
public function IntlCalendar::getLeastMaximum(int `$field`): int|false
public function IntlCalendar::getLocale(int `$type`): string|false
public function IntlCalendar::getMaximum(int `$field`): int|false
public function IntlCalendar::getMinimalDaysInFirstWeek(): int|false
public function IntlCalendar::getMinimum(int `$field`): int|false
public static function IntlCalendar::getNow(): float
public function IntlCalendar::getRepeatedWallTimeOption(): int
public function IntlCalendar::getSkippedWallTimeOption(): int
public function IntlCalendar::getTime(): float|false
public function IntlCalendar::getTimeZone(): IntlTimeZone|false
public function IntlCalendar::getType(): string
public function IntlCalendar::getWeekendTransition(int `$dayOfWeek`): int|false
public function IntlCalendar::inDaylightTime(): bool
public function IntlCalendar::isEquivalentTo(IntlCalendar `$other`): bool
public function IntlCalendar::isLenient(): bool
public function IntlCalendar::isSet(int `$field`): bool
public function IntlCalendar::isWeekend(?float `$timestamp` = `null`): bool
public function IntlCalendar::roll(int `$field`, int|bool `$value`): bool
public function IntlCalendar::set(int `$field`, int `$value`): true
public function IntlCalendar::set(
int `$year`,
int `$month`,
int `$dayOfMonth` = NULL,
int `$hour` = NULL,
int `$minute` = NULL,
int `$second` = NULL
): true
public function IntlCalendar::setDate(int `$year`, int `$month`, int `$dayOfMonth`): void
public function IntlCalendar::setDateTime(
int `$year`,
int `$month`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
?int `$second` = `null`
): void
public function IntlCalendar::setFirstDayOfWeek(int `$dayOfWeek`): true
public function IntlCalendar::setLenient(bool `$lenient`): true
public function IntlCalendar::setMinimalDaysInFirstWeek(int `$days`): true
public function IntlCalendar::setRepeatedWallTimeOption(int `$option`): true
public function IntlCalendar::setSkippedWallTimeOption(int `$option`): true
public function IntlCalendar::setTime(float `$timestamp`): bool
public function IntlCalendar::setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool
public function IntlCalendar::toDateTime(): DateTime|false
}

# IntlGregorianCalendar::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlGregorianCalendar::__construct — Cria um objeto de calendário gregoriano

### Descrição

public function IntlGregorianCalendar::__construct(IntlTimeZone `$tz` = ?, string `$locale` = ?)
public function IntlGregorianCalendar::__construct(int `$timeZoneOrYear`, int `$localeOrMonth`, int `$dayOfMonth`)
public function IntlGregorianCalendar::__construct(
int `$timeZoneOrYear`,
int `$localeOrMonth`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
int `$second` = ?
)

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`tz`

`locale`

`timeZoneOrYear`

`localeOrMonth`

`dayOfMonth`

`hour`

`minute`

`second`

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Este método foi descontinuado em favor dos métodos IntlGregorianCalendar::createFromDate() e IntlGregorianCalendar::createFromDateTime().

# IntlGregorianCalendar::createFromDate

(PHP 8 >= 8.3.0)

IntlGregorianCalendar::createFromDate — Cria uma nova instância de IntlGregorianCalendar a partir de uma data

### Descrição

public static function IntlGregorianCalendar::createFromDate(int `$year`, int `$month`, int `$dayOfMonth`): static

Cria uma nova instância de IntlGregorianCalendar a partir de uma data.

### Parâmetros

`year`

  O novo valor para o ano, `IntlGregorianCalendar::FIELD_YEAR`.

`month`

  O novo valor para o mês, `IntlGregorianCalendar::FIELD_MONTH`. A sequência de meses é baseada em zero, isto é, janeiro é representado por 0, fevereiro por 1, …, dezembro é 11 e undecember (se o calendário o tiver) é 12.

`dayOfMonth`

  O novo valor para o dia, `IntlGregorianCalendar::FIELD_DAY_OF_MONTH`.

### Valor Retornado

Retorna uma nova instância de IntlGregorianCalendar.

### Exemplos

Exemplo #1 Exemplo de IntlGregorianCalendar::createFromDate()

    <?php

    $intlCalendar = IntlGregorianCalendar::createFromDate(2023, 11, 23);
    var_dump($intlCalendar);
    ?>

O exemplo acima produzirá algo semelhante a:

    object(IntlGregorianCalendar)#1 (5) {
      ["valid"]=>
      bool(true)
      ["type"]=>
      string(9) "gregorian"
      ["timeZone"]=>
      array(4) {
        ["valid"]=>
        bool(true)
        ["id"]=>
        string(16) "Europe/Amsterdam"
        ["rawOffset"]=>
        int(3600000)
        ["currentOffset"]=>
        int(3600000)
      }
      ["locale"]=>
      string(11) "en_US_POSIX"
      ["fields"]=>
      array(23) {
        ["era"]=>
        int(1)
        ["year"]=>
        int(2023)
        ["month"]=>
        int(11)
        ["week of year"]=>
        int(51)
        ["week of month"]=>
        int(4)
        ["day of year"]=>
        int(357)
        ["day of month"]=>
        int(23)
        ["day of week"]=>
        int(7)
        ["day of week in month"]=>
        int(4)
        ["AM/PM"]=>
        int(0)
        ["hour"]=>
        int(0)
        ["hour of day"]=>
        int(0)
        ["minute"]=>
        int(0)
        ["second"]=>
        int(0)
        ["millisecond"]=>
        int(0)
        ["zone offset"]=>
        int(3600000)
        ["DST offset"]=>
        int(0)
        ["year for week of year"]=>
        int(2023)
        ["localized day of week"]=>
        int(7)
        ["extended year"]=>
        int(2023)
        ["julian day"]=>
        int(2460302)
        ["milliseconds in day"]=>
        int(0)
        ["is leap month"]=>
        int(0)
      }
    }

### Veja Também

- IntlGregorianCalendar::createFromDateTime() - Cria uma instância de IntlGregorianCalendar a partir de data e horário

# IntlGregorianCalendar::createFromDateTime

(PHP 8 >= 8.3.0)

IntlGregorianCalendar::createFromDateTime — Cria uma instância de IntlGregorianCalendar a partir de data e horário

### Descrição

public static function IntlGregorianCalendar::createFromDateTime(
int `$year`,
int `$month`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
?int `$second` = `null`
): static

Cria uma nova instância de IntlGregorianCalendar a partir de data e horário.

### Parâmetros

`year`

  O novo valor para o ano, `IntlGregorianCalendar::FIELD_YEAR`.

`month`

  O novo valor para o mês, `IntlGregorianCalendar::FIELD_MONTH`. A sequência de meses é baseada em zero, isto é, janeiro é representado por 0, fevereiro por 1, …, dezembro é 11 e undecember (se o calendário o tiver) é 12.

`dayOfMonth`

  O novo valor para o dia, `IntlGregorianCalendar::FIELD_DAY_OF_MONTH`.

`hour`

  O novo valor para a hora, `IntlGregorianCalendar::FIELD_HOUR_OF_DAY`.

`minute`

  O novo valor para o minuto, `IntlGregorianCalendar::FIELD_MINUTE`.

`second`

  O novo valor para o segundo, `IntlGregorianCalendar::FIELD_SECOND`.

### Valor Retornado

Retorna uma nova instância de IntlGregorianCalendar.

### Exemplos

Exemplo #1 Exemplo de IntlGregorianCalendar::createFromDateTime()

    <?php

    $intlCalendar = IntlGregorianCalendar::createFromDateTime(2023, 11, 23, 12, 00);
    var_dump($intlCalendar);
    ?>

O exemplo acima produzirá algo semelhante a:

    object(IntlGregorianCalendar)#1 (5) {
      ["valid"]=>
      bool(true)
      ["type"]=>
      string(9) "gregorian"
      ["timeZone"]=>
      array(4) {
        ["valid"]=>
        bool(true)
        ["id"]=>
        string(16) "Europe/Amsterdam"
        ["rawOffset"]=>
        int(3600000)
        ["currentOffset"]=>
        int(3600000)
      }
      ["locale"]=>
      string(11) "en_US_POSIX"
      ["fields"]=>
      array(23) {
        ["era"]=>
        int(1)
        ["year"]=>
        int(2023)
        ["month"]=>
        int(11)
        ["week of year"]=>
        int(51)
        ["week of month"]=>
        int(4)
        ["day of year"]=>
        int(357)
        ["day of month"]=>
        int(23)
        ["day of week"]=>
        int(7)
        ["day of week in month"]=>
        int(4)
        ["AM/PM"]=>
        int(1)
        ["hour"]=>
        int(0)
        ["hour of day"]=>
        int(12)
        ["minute"]=>
        int(0)
        ["second"]=>
        int(0)
        ["millisecond"]=>
        int(0)
        ["zone offset"]=>
        int(3600000)
        ["DST offset"]=>
        int(0)
        ["year for week of year"]=>
        int(2023)
        ["localized day of week"]=>
        int(7)
        ["extended year"]=>
        int(2023)
        ["julian day"]=>
        int(2460302)
        ["milliseconds in day"]=>
        int(43200000)
        ["is leap month"]=>
        int(0)
      }
    }

### Veja Também

- IntlGregorianCalendar::createFromDate() - Cria uma nova instância de IntlGregorianCalendar a partir de uma data

# IntlGregorianCalendar::getGregorianChange

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlGregorianCalendar::getGregorianChange — Obtém a data de mudança do calendário gregoriano

### Descrição

public function IntlGregorianCalendar::getGregorianChange(): float

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a data de mudança.

# IntlGregorianCalendar::isLeapYear

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlGregorianCalendar::isLeapYear — Determina se o ano é bissexto

### Descrição

public function IntlGregorianCalendar::isLeapYear(int `$year`): bool

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`year`

### Valor Retornado

Retorna `true` para anos bissextos, `false` caso contrário e em caso de falha.

# IntlGregorianCalendar::setGregorianChange

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlGregorianCalendar::setGregorianChange — Define a data de mudança do calendário gregoriano

### Descrição

public function IntlGregorianCalendar::setGregorianChange(float `$timestamp`): bool

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`timestamp`

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

## Índice

- IntlGregorianCalendar::__construct — Cria um objeto de calendário gregoriano
- IntlGregorianCalendar::createFromDate — Cria uma nova instância de IntlGregorianCalendar a partir de uma data
- IntlGregorianCalendar::createFromDateTime — Cria uma instância de IntlGregorianCalendar a partir de data e horário
- IntlGregorianCalendar::getGregorianChange — Obtém a data de mudança do calendário gregoriano
- IntlGregorianCalendar::isLeapYear — Determina se o ano é bissexto
- IntlGregorianCalendar::setGregorianChange — Define a data de mudança do calendário gregoriano

# A classe IntlTimeZone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

## Introdução

## Resumo da classe

class IntlTimeZone {
/* Constantes */
public const int DISPLAY_SHORT;
public const int DISPLAY_LONG;
public const int DISPLAY_SHORT_GENERIC;
public const int DISPLAY_LONG_GENERIC;
public const int DISPLAY_SHORT_GMT;
public const int DISPLAY_LONG_GMT;
public const int DISPLAY_SHORT_COMMONLY_USED;
public const int DISPLAY_GENERIC_LOCATION;
public const int TYPE_ANY;
public const int TYPE_CANONICAL;
public const int TYPE_CANONICAL_LOCATION;
/* Métodos */
private function __construct()
public static function countEquivalentIDs(string `$timezoneId`): int|false
public static function createDefault(): IntlTimeZone
public static function createEnumeration(string|int|null `$countryOrRawOffset` = `null`): IntlIterator|false
public static function createTimeZone(string `$timezoneId`): ?IntlTimeZone
public static function createTimeZoneIDEnumeration(int `$type`, ?string `$region` = `null`, ?int `$rawOffset` = `null`): IntlIterator|false
public static function fromDateTimeZone(DateTimeZone `$timezone`): ?IntlTimeZone
public static function getCanonicalID(string `$timezoneId`, bool `&$isSystemId` = `null`): string|false
public function getDisplayName(bool `$dst` = `false`, int `$style` = `IntlTimeZone::DISPLAY_LONG`, ?string `$locale` = `null`): string|false
public function getDSTSavings(): int
public static function getEquivalentID(string `$timezoneId`, int `$offset`): string|false
public function getErrorCode(): int|false
public function getErrorMessage(): string|false
public static function getGMT(): IntlTimeZone
public static function getIanaID(string `$timezoneId`): string|false
public function getID(): string|false
public static function getIDForWindowsID(string `$timezoneId`, ?string `$region` = `null`): string|false
public function getOffset(
float `$timestamp`,
bool `$local`,
int `&$rawOffset`,
int `&$dstOffset`
): bool
public function getRawOffset(): int
public static function getRegion(string `$timezoneId`): string|false
public static function getTZDataVersion(): string|false
public static function getUnknown(): IntlTimeZone
public static function getWindowsID(string `$timezoneId`): string|false
public function hasSameRules(IntlTimeZone `$other`): bool
public function toDateTimeZone(): DateTimeZone|false
public function useDaylightTime(): bool
}

## Constantes predefinidas

`IntlTimeZone::DISPLAY_SHORT` int

`IntlTimeZone::DISPLAY_LONG` int

`IntlTimeZone::DISPLAY_SHORT_GENERIC` int

`IntlTimeZone::DISPLAY_LONG_GENERIC` int

`IntlTimeZone::DISPLAY_SHORT_GMT` int

`IntlTimeZone::DISPLAY_LONG_GMT` int

`IntlTimeZone::DISPLAY_SHORT_COMMONLY_USED` int

`IntlTimeZone::DISPLAY_GENERIC_LOCATION` int

`IntlTimeZone::TYPE_ANY` int

`IntlTimeZone::TYPE_CANONICAL` int

`IntlTimeZone::TYPE_CANONICAL_LOCATION` int

## Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | As constantes de classe agora são tipadas.

# IntlTimeZone::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::__construct — Construtor privado para não permitir instanciação direta

### Descrição

private function IntlTimeZone::__construct()

### Parâmetros

Esta função não possui parâmetros.

# IntlTimeZone::countEquivalentIDs

# intltz_count_equivalent_ids

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::countEquivalentIDs -- intltz_count_equivalent_ids — Obtém o número de IDs no grupo de equivalÇencia que inclui o ID informado

### Descrição

Estilo orientado a objetos (método):

public static function IntlTimeZone::countEquivalentIDs(string `$timezoneId`): int|false

Estilo procedural:

function intltz_count_equivalent_ids(string `$timezoneId`): int|false

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`timezoneId`

### Valor Retornado

# IntlTimeZone::createDefault

# intltz_create_default

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::createDefault -- intltz_create_default — Cria uma nova cópia do fuso horário padrão para este host

### Descrição

Estilo orientado a objetos (método):

public static function IntlTimeZone::createDefault(): IntlTimeZone

Estilo procedural:

function intltz_create_default(): IntlTimeZone

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# IntlTimeZone::createEnumeration

# intltz_create_enumeration

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::createEnumeration -- intltz_create_enumeration — Obtém uma enumeração a partir de IDs de fuso horário associados com o país informado ou com o deslocamento UTC

### Descrição

Estilo orientado a objetos (método):

public static function IntlTimeZone::createEnumeration(string|int|null `$countryOrRawOffset` = `null`): IntlIterator|false

Estilo procedural:

function intltz_create_enumeration(string|int|null `$countryOrRawOffset` = `null`): IntlIterator|false

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`countryOrRawOffset`

### Valor Retornado

# IntlTimeZone::createTimeZone

# intltz_create_time_zone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::createTimeZone -- intltz_create_time_zone — Cria um objeto IntlTimeZone para o ID informado

### Descrição

Estilo orientado a objetos (método):

public static function IntlTimeZone::createTimeZone(string `$timezoneId`): ?IntlTimeZone

Estilo procedural:

function intltz_create_time_zone(string `$timezoneId`): ?IntlTimeZone

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`timezoneId`

### Valor Retornado

# IntlTimeZone::createTimeZoneIDEnumeration

# intltz_create_time_zone_id_enumeration

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlTimeZone::createTimeZoneIDEnumeration -- intltz_create_time_zone_id_enumeration — Obtém uma enumeração a partir de IDs de fuso horário do sistema com as condições de filtro informadas

### Descrição

Estilo orientado a objetos (método):

public static function IntlTimeZone::createTimeZoneIDEnumeration(int `$type`, ?string `$region` = `null`, ?int `$rawOffset` = `null`): IntlIterator|false

Estilo procedural:

function intltz_create_time_zone_id_enumeration(int `$type`, ?string `$region` = `null`, ?int `$rawOffset` = `null`): IntlIterator|false

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`type`

`region`

`rawOffset`

### Valor Retornado

Retorna um objeto IntlIterator ou `false` em caso de falha.

# IntlTimeZone::fromDateTimeZone

# intltz_from_date_time_zone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::fromDateTimeZone -- intltz_from_date_time_zone — Cria um objeto IntlTimeZone a partir de um DateTimeZone

### Descrição

Estilo orientado a objetos (método):

public static function IntlTimeZone::fromDateTimeZone(DateTimeZone `$timezone`): ?IntlTimeZone

Estilo procedural:

function intltz_from_date_time_zone(DateTimeZone `$timezone`): ?IntlTimeZone

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`timezone`

### Valor Retornado

# IntlTimeZone::getCanonicalID

# intltz_get_canonical_id

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getCanonicalID -- intltz_get_canonical_id — Obtém o ID do fuso horário de sistema canônico ou o cutomizado normalizado para o ID de fuso horário informado

### Descrição

Estilo orientado a objetos (método):

public static function IntlTimeZone::getCanonicalID(string `$timezoneId`, bool `&$isSystemId` = `null`): string|false

Estilo procedural:

function intltz_get_canonical_id(string `$timezoneId`, bool `&$isSystemId` = `null`): string|false

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`timezoneId`

`isSystemId`

### Valor Retornado

# IntlTimeZone::getDisplayName

# intltz_get_display_name

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getDisplayName -- intltz_get_display_name — Obtém o nome do fuso horário adequado para apresentação ao usuário

### Descrição

Estilo orientado a objetos (método):

public function IntlTimeZone::getDisplayName(bool `$dst` = `false`, int `$style` = `IntlTimeZone::DISPLAY_LONG`, ?string `$locale` = `null`): string|false

Estilo procedural:

function intltz_get_display_name(
IntlTimeZone `$timezone`,
bool `$dst` = `false`,
int `$style` = `IntlTimeZone::DISPLAY_LONG`,
?string `$locale` = `null`
): string|false

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`dst`

`style`

`locale`

### Valor Retornado

# IntlTimeZone::getDSTSavings

# intltz_get_dst_savings

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getDSTSavings -- intltz_get_dst_savings — Obtém a quantidade de tempo a ser adicionado ao horário local padrão para obter o horário local real de relógio

### Descrição

Estilo orientado a objetos (método):

public function IntlTimeZone::getDSTSavings(): int

Estilo procedural:

function intltz_get_dst_savings(IntlTimeZone `$timezone`): int

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# IntlTimeZone::getEquivalentID

# intltz_get_equivalent_id

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getEquivalentID -- intltz_get_equivalent_id — Obtém um ID no grupo de equivalência que inclui o ID informado

### Descrição

Estilo orientado a objetos (método):

public static function IntlTimeZone::getEquivalentID(string `$timezoneId`, int `$offset`): string|false

Estilo procedural:

function intltz_get_equivalent_id(string `$timezoneId`, int `$offset`): string|false

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`timezoneId`

`offset`

### Valor Retornado

# IntlTimeZone::getErrorCode

# intltz_get_error_code

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getErrorCode -- intltz_get_error_code — Obtém o último código de erro no objeto

### Descrição

Estilo orientado a objetos (método):

public function IntlTimeZone::getErrorCode(): int|false

Estilo procedural:

function intltz_get_error_code(IntlTimeZone `$timezone`): int|false

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# IntlTimeZone::getErrorMessage

# intltz_get_error_message

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getErrorMessage -- intltz_get_error_message — Obtém a última mensagem de erro no objeto

### Descrição

Estilo orientado a objetos (método):

public function IntlTimeZone::getErrorMessage(): string|false

Estilo procedural:

function intltz_get_error_message(IntlTimeZone `$timezone`): string|false

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# IntlTimeZone::getGMT

# intltz_get_gmt

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getGMT -- intltz_get_gmt — Cria um fuso horário GMT (UTC)

### Descrição

Estilo orientado a objetos (método):

public static function IntlTimeZone::getGMT(): IntlTimeZone

Estilo procedural:

function intltz_get_gmt(): IntlTimeZone

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# IntlTimeZone::getIanaID

# intltz_get_iana_id

(PHP 8 >= 8.4.0)

IntlTimeZone::getIanaID -- intltz_get_iana_id — Traduz um identificador de fuso horário para seu equivalente IANA

### Descrição

Estilo orientado a objetos (method):

public static function IntlTimeZone::getIanaID(string `$timezoneId`): string|false

Estilo procedural:

function intltz_get_iana_id(string `$timezoneId`): string|false

Traduz um identificador de fuso horário para seu equivalente IANA. Por exemplo, `"GMT"` retorna `"Etc/GMT"` e `"US/Eastern"` retorna `"America/New_York"`.

> Nota: Esta função requer a ICU versão >= 74.

### Parâmetros

`timezoneId`
  O identificador de fuso horário a ser traduzido.

### Valor Retornado

Retorna o identificador de fuso horário IANA como uma string, ou `false` em caso de falha.

### Veja Também

- intltz_get_id_for_windows_id() - Traduz um fuso horário do Windows para um fuso horário de sistema
- intltz_get_windows_id() - Traduz um fuso horário de sistema em um fuso horário do Windows
- intltz_create_time_zone() - Cria um objeto IntlTimeZone para o ID informado

# IntlTimeZone::getID

# intltz_get_id

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getID -- intltz_get_id — Obtém o ID do fuso horário

### Descrição

Estilo orientado a objetos (método):

public function IntlTimeZone::getID(): string|false

Estilo procedural:

function intltz_get_id(IntlTimeZone `$timezone`): string|false

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# IntlTimeZone::getIDForWindowsID

# intltz_get_id_for_windows_id

(PHP 7 >= 7.1.0, PHP 8)

IntlTimeZone::getIDForWindowsID -- intltz_get_id_for_windows_id — Traduz um fuso horário do Windows para um fuso horário de sistema

### Descrição

Estilo orientado a objetos (método):

public static function IntlTimeZone::getIDForWindowsID(string `$timezoneId`, ?string `$region` = `null`): string|false

Estilo procedural:

function intltz_get_id_for_windows_id(string `$timezoneId`, ?string `$region` = `null`): string|false

Traduz um fuso horário do Windows (ex.: "Pacific Standard Time") para um fuso horário de sistema (ex.: "America/Los_Angeles").

> Nota: Esta função requer a ICU versão ≥ 52.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`timezoneId`

`region`

### Valor Retornado

Retorna o fuso horário de sistema ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `region` agora pode ser nulo.

### Veja Também

- IntlTimeZone::getWindowsID() - Traduz um fuso horário de sistema em um fuso horário do Windows

# IntlTimeZone::getOffset

# intltz_get_offset

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getOffset -- intltz_get_offset — Obtém o deslocamento UTC padrão e o deslocamento com horário de verão para um determinado timestamp Unix

### Descrição

Estilo orientado a objetos (método):

public function IntlTimeZone::getOffset(
float `$timestamp`,
bool `$local`,
int `&$rawOffset`,
int `&$dstOffset`
): bool

Estilo procedural:

function intltz_get_offset(
IntlTimeZone `$timezone`,
float `$timestamp`,
bool `$local`,
int `&$rawOffset`,
int `&$dstOffset`
): bool

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`timestamp`

`local`

`rawOffset`

`dstOffset`

### Valor Retornado

# IntlTimeZone::getRawOffset

# intltz_get_raw_offset

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getRawOffset -- intltz_get_raw_offset — Obtém o deslocamento UTC puro (antes de considerar horário de verão)

### Descrição

Estilo orientado a objetos (método):

public function IntlTimeZone::getRawOffset(): int

Estilo procedural:

function intltz_get_raw_offset(IntlTimeZone `$timezone`): int

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# IntlTimeZone::getRegion

# intltz_get_region

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlTimeZone::getRegion -- intltz_get_region — Obtém o código da região associada com o ID de fuso horário de sistema informado

### Descrição

Estilo orientado a objetos (método):

public static function IntlTimeZone::getRegion(string `$timezoneId`): string|false

Estilo procedural:

function intltz_get_region(string `$timezoneId`): string|false

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`timezoneId`

### Valor Retornado

Retorna a região ou `false` em caso de falha.

# IntlTimeZone::getTZDataVersion

# intltz_get_tz_data_version

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getTZDataVersion -- intltz_get_tz_data_version — Obtém a versão de dados de fuso horário atualmente usados pela ICU

### Descrição

Estilo orientado a objetos (método):

public static function IntlTimeZone::getTZDataVersion(): string|false

Estilo procedural:

function intltz_get_tz_data_version(): string|false

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# IntlTimeZone::getUnknown

# intltz_get_unknown

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlTimeZone::getUnknown -- intltz_get_unknown — Obtém o fuso horário "desconhecido"

### Descrição

Estilo orientado a objetos (método):

public static function IntlTimeZone::getUnknown(): IntlTimeZone

Estilo procedural:

function intltz_get_unknown(): IntlTimeZone

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um objeto IntlTimeZone ou `null` em caso de falha.

# IntlTimeZone::getWindowsID

# intltz_get_windows_id

(PHP 7 >= 7.1.0, PHP 8)

IntlTimeZone::getWindowsID -- intltz_get_windows_id — Traduz um fuso horário de sistema em um fuso horário do Windows

### Descrição

Estilo orientado a objetos (método):

public static function IntlTimeZone::getWindowsID(string `$timezoneId`): string|false

Estilo procedural:

function intltz_get_windows_id(string `$timezoneId`): string|false

Traduz um fuso horário de sistema (ex;: "America/Los_Angeles") em um fuso horário do Windows (e.: "Pacific Standard Time").

> Nota: Esta função requer a ICU versão ≥ 52.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`timezoneId`

### Valor Retornado

Retorna o fuso horário do Windows ou `false` em caso de falha.

### Veja Também

- IntlTimeZone::getIDForWindowsID() - Traduz um fuso horário do Windows para um fuso horário de sistema

# IntlTimeZone::hasSameRules

# intltz_has_same_rules

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::hasSameRules -- intltz_has_same_rules — Verifica se um fuso horário tem as mesmas regras e deslocamentos de um outro

### Descrição

Estilo orientado a objetos (método):

public function IntlTimeZone::hasSameRules(IntlTimeZone `$other`): bool

Estilo procedural:

function intltz_has_same_rules(IntlTimeZone `$timezone`, IntlTimeZone `$other`): bool

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`other`

### Valor Retornado

# IntlTimeZone::toDateTimeZone

# intltz_to_date_time_zone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::toDateTimeZone -- intltz_to_date_time_zone — Converte em um objeto DateTimeZone

### Descrição

Estilo orientado a objetos (método):

public function IntlTimeZone::toDateTimeZone(): DateTimeZone|false

Estilo procedural:

function intltz_to_date_time_zone(IntlTimeZone `$timezone`): DateTimeZone|false

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# IntlTimeZone::useDaylightTime

# intltz_use_daylight_time

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::useDaylightTime -- intltz_use_daylight_time — Verifica se o fuso horário usa horário de verão

### Descrição

Estilo orientado a objetos (método):

public function IntlTimeZone::useDaylightTime(): bool

Estilo procedural:

function intltz_use_daylight_time(IntlTimeZone `$timezone`): bool

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

## Índice

- IntlTimeZone::__construct — Construtor privado para não permitir instanciação direta
- IntlTimeZone::countEquivalentIDs — Obtém o número de IDs no grupo de equivalÇencia que inclui o ID informado
- IntlTimeZone::createDefault — Cria uma nova cópia do fuso horário padrão para este host
- IntlTimeZone::createEnumeration — Obtém uma enumeração a partir de IDs de fuso horário associados com o país informado ou com o deslocamento UTC
- IntlTimeZone::createTimeZone — Cria um objeto IntlTimeZone para o ID informado
- IntlTimeZone::createTimeZoneIDEnumeration — Obtém uma enumeração a partir de IDs de fuso horário do sistema com as condições de filtro informadas
- IntlTimeZone::fromDateTimeZone — Cria um objeto IntlTimeZone a partir de um DateTimeZone
- IntlTimeZone::getCanonicalID — Obtém o ID do fuso horário de sistema canônico ou o cutomizado normalizado para o ID de fuso horário informado
- IntlTimeZone::getDisplayName — Obtém o nome do fuso horário adequado para apresentação ao usuário
- IntlTimeZone::getDSTSavings — Obtém a quantidade de tempo a ser adicionado ao horário local padrão para obter o horário local real de relógio
- IntlTimeZone::getEquivalentID — Obtém um ID no grupo de equivalência que inclui o ID informado
- IntlTimeZone::getErrorCode — Obtém o último código de erro no objeto
- IntlTimeZone::getErrorMessage — Obtém a última mensagem de erro no objeto
- IntlTimeZone::getGMT — Cria um fuso horário GMT (UTC)
- IntlTimeZone::getIanaID — Traduz um identificador de fuso horário para seu equivalente IANA
- IntlTimeZone::getID — Obtém o ID do fuso horário
- IntlTimeZone::getIDForWindowsID — Traduz um fuso horário do Windows para um fuso horário de sistema
- IntlTimeZone::getOffset — Obtém o deslocamento UTC padrão e o deslocamento com horário de verão para um determinado timestamp Unix
- IntlTimeZone::getRawOffset — Obtém o deslocamento UTC puro (antes de considerar horário de verão)
- IntlTimeZone::getRegion — Obtém o código da região associada com o ID de fuso horário de sistema informado
- IntlTimeZone::getTZDataVersion — Obtém a versão de dados de fuso horário atualmente usados pela ICU
- IntlTimeZone::getUnknown — Obtém o fuso horário "desconhecido"
- IntlTimeZone::getWindowsID — Traduz um fuso horário de sistema em um fuso horário do Windows
- IntlTimeZone::hasSameRules — Verifica se um fuso horário tem as mesmas regras e deslocamentos de um outro
- IntlTimeZone::toDateTimeZone — Converte em um objeto DateTimeZone
- IntlTimeZone::useDaylightTime — Verifica se o fuso horário usa horário de verão

# A classe IntlDateFormatter

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Introdução

O formatador de datas é uma classe concreta que habilita formatação/interpretação dependetes de localidade de datas usando strings de padrões e/ou padrões já existentes.

Esta classe representa a funcionalidade de formatação de datas da ICU. Permite aos usuários apresentar datas em formato dependente de localidade ou converter strings em valores de datas do PHP usando strings de padrões e/ou padrões já existentes.

## Resumo da classe

class IntlDateFormatter {
/* Constantes */
public const int FULL;
public const int LONG;
public const int MEDIUM;
public const int SHORT;
public const int NONE;
public const int RELATIVE_FULL;
public const int RELATIVE_LONG;
public const int RELATIVE_MEDIUM;
public const int RELATIVE_SHORT;
public const int PATTERN;
public const int GREGORIAN;
public const int TRADITIONAL;
/* Métodos */
public function __construct(
?string `$locale`,
int `$dateType` = `IntlDateFormatter::FULL`,
int `$timeType` = `IntlDateFormatter::FULL`,
IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`,
IntlCalendar|int|null `$calendar` = `null`,
?string `$pattern` = `null`
)
public static function create(
?string `$locale`,
int `$dateType` = `IntlDateFormatter::FULL`,
int `$timeType` = `IntlDateFormatter::FULL`,
IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`,
IntlCalendar|int|null `$calendar` = `null`,
?string `$pattern` = `null`
): ?IntlDateFormatter
public function format(IntlCalendar|DateTimeInterface|array|string|int|float `$datetime`): string|false
public static function formatObject(IntlCalendar|DateTimeInterface `$datetime`, array|int|string|null `$format` = `null`, ?string `$locale` = `null`): string|false
public function getCalendar(): int|false
public function getDateType(): int|false
public function getErrorCode(): int
public function getErrorMessage(): string
public function getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false
public function getPattern(): string|false
public function getTimeType(): int|false
public function getTimeZoneId(): string|false
public function getCalendarObject(): IntlCalendar|false|null
public function getTimeZone(): IntlTimeZone|false
public function isLenient(): bool
public function localtime(string `$string`, int `&$offset` = `null`): array|false
public function parse(string `$string`, int `&$offset` = `null`): int|float|false
public function parseToCalendar(string `$string`, int `&$offset` = `null`): int|float|false
public function setCalendar(IntlCalendar|int|null `$calendar`): bool
public function setLenient(bool `$lenient`): void
public function setPattern(string `$pattern`): bool
public function setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool
}

## Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Adicionada a constante `IntlDateFormatter::PATTERN`.

## Veja Também

- » Formatador de Datas ICU

- » Formatos de Datas ICU

## Constantes predefinidas

Estas constantes são usadas para especificar diferentes formatos nos construtores para DateType e TimeType.

`IntlDateFormatter::NONE` int
  Não incluir este elemento
`IntlDateFormatter::FULL` int
  Estilo completamente especificado (Tuesday, April 12, 1952 AD ou 3:30:42pm PST)
`IntlDateFormatter::LONG` int
  Estilo longo (January 12, 1952 ou 3:30:32pm)
`IntlDateFormatter::MEDIUM` int
  Estilo médio (Jan 12, 1952)
`IntlDateFormatter::SHORT` int
  O estilo mais abreviado, apenas dados essenciais (12/13/52 ou 3:30pm)
`IntlDateFormatter::RELATIVE_FULL` int
  O mesmo que `IntlDateFormatter::FULL`, porém ontem, hoje e amanhã são mostrados como `yesterday`, `today`, e `tomorrow`, respectivamente. Disponível a partir do PHP 8.0.0, somente para `dateType`.
`IntlDateFormatter::RELATIVE_LONG` int
  O mesmo que `IntlDateFormatter::LONG`, porém ontem, hoje e amanhã são mostrados como `yesterday`, `today`, e `tomorrow`, respectivamente. Disponível a partir do PHP 8.0.0, somente para `dateType`.
`IntlDateFormatter::RELATIVE_MEDIUM` int
  O mesmo que `IntlDateFormatter::MEDIUM`, porém ontem, hoje e amanhã são mostrados como `yesterday`, `today`, e `tomorrow`, respectivamente. Disponível a partir do PHP 8.0.0, somente para `dateType`.
`IntlDateFormatter::RELATIVE_SHORT` int
  O mesmo que `IntlDateFormatter::SHORT`, porém ontem, hoje e amanhã são mostrados como `yesterday`, `today`, e `tomorrow`, respectivamente. Disponível a partir do PHP 8.0.0, somente para `dateType`.
`IntlDateFormatter::PATTERN` int
  Usa o padrão informado em `pattern`. Disponível a partir do PHP 8.4.0.

As constantes inteiras a seguir são usadas para especificar o calendário. Estes calendários são todos baseados diretamente no calendário gregoriano. Calendários não gregorianos precisam ser especificados na localidade. Exemplos podem incluir locale="hi@calendar=BUDDHIST".

`IntlDateFormatter::TRADITIONAL` int
  Calendário Não Gregoriano
`IntlDateFormatter::GREGORIAN` int
  Calendário Gregoriano

## Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | As constantes de classe agora são tipadas.

# IntlDateFormatter::create

# datefmt_create

# IntlDateFormatter::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::create -- datefmt_create -- IntlDateFormatter::__construct — Cria um formatador de data

### Descrição

Estilo orientado a objetos

public static function IntlDateFormatter::create(
?string `$locale`,
int `$dateType` = `IntlDateFormatter::FULL`,
int `$timeType` = `IntlDateFormatter::FULL`,
IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`,
IntlCalendar|int|null `$calendar` = `null`,
?string `$pattern` = `null`
): ?IntlDateFormatter

Estilo orientado a objetos (construtor)

public function IntlDateFormatter::__construct(
?string `$locale`,
int `$dateType` = `IntlDateFormatter::FULL`,
int `$timeType` = `IntlDateFormatter::FULL`,
IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`,
IntlCalendar|int|null `$calendar` = `null`,
?string `$pattern` = `null`
)

Estilo procedural

function datefmt_create(
?string `$locale`,
int `$dateType` = `IntlDateFormatter::FULL`,
int `$timeType` = `IntlDateFormatter::FULL`,
IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`,
IntlCalendar|int|null `$calendar` = `null`,
?string `$pattern` = `null`
): ?IntlDateFormatter

Cria um formatador de data.

### Parâmetros

`locale`

  Localidade a ser utilizada ao formatar ou interpretar, ou `null` para utilizar o valor especificado na configuração ini intl.default_locale.

`dateType`

  Formato da data determinado por uma das constantes IntlDateFormatter. O valor padrão é `IntlDateFormatter::FULL`.

`timeType`

  Formato do horário determinado por uma das constantes IntlDateFormatter. O valor padrão é `IntlDateFormatter::FULL`.

`timezone`

  ID do fuso horário. O padrão (que também é usado se `null` for fornecido) é o retornado por date_default_timezone_get() ou, se aplicável, o do objeto IntlCalendar passado para o parâmetro `calendar`. Este ID precisa ser um identificador válido no banco de dados da ICU ou um ID representando um deslocamento específico, como em `GMT-05:30`.

  Este parâmetro tammbém pode ser um objeto IntlTimeZone ou DateTimeZone.

`calendar`

  Calendário a ser utilizado para formatação ou interpretação. O valor padrão é `null`, que corresponde a `IntlDateFormatter::GREGORIAN`. Pode ser uma das constantes de calendário IntlDateFormatter ou um objeto IntlCalendar. Qualquer objeto IntlCalendar passado será clonado; ele não será alterado por IntlDateFormatter. Este parâmetro determinará o tipo de calendário utilizado (gregoriano, islâmico, persa, etc.) e, se `null` for fornecido para o parâmetro `timezone`, também definirá o fuso horário utilizado.

`pattern`

  Modelo opcional a ser utilizado ao formatar ou interpretar. Modelos possíveis estão documentados em » https://unicode-org.github.io/icu/userguide/format_parse/datetime/.

### Valor Retornado

O objeto IntlDateFormatter criado ou `null` em caso de falha.

### Erros/Exceções

Uma exceção ValueError é lançada se `locale` for inválido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Uma exceção ValueError agora é lançada se `locale` for inválido.
8.1.0 | Parêmatros `dateType` e `timeType` agora são opcionais.

### Exemplos

Exemplo #1 Exemplo de datefmt_create()

    <?php
    $fmt = datefmt_create( "pt_BR" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
        'America/Sao_Paulo', IntlDateFormatter::GREGORIAN  );
    echo "Primeira saída formatada é ".datefmt_format( $fmt , 0)."\n";
    $fmt = datefmt_create( "de-DE" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
        'America/Sao_Paulo',IntlDateFormatter::GREGORIAN  );
    echo "Segunda saída formatada é ".datefmt_format( $fmt , 0)."\n";

    $fmt = datefmt_create( "pt_BR" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
         'America/Sao_Paulo',IntlDateFormatter::GREGORIAN  ,"MM/dd/yyyy");
    echo "Primeira saída formatada com modelo é ".datefmt_format( $fmt , 0)."\n";
    $fmt = datefmt_create( "de-DE" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
         'America/Sao_Paulo',IntlDateFormatter::GREGORIAN  ,"MM/dd/yyyy");
    echo "Segunda saída formatada com modelo é ".datefmt_format( $fmt , 0)."\n";
    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new IntlDateFormatter( "pt_BR" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
        'America/Sao_Paulo',IntlDateFormatter::GREGORIAN  );
    echo "Primeira saída formatada é ".$fmt->format(0)."\n";
    $fmt = new IntlDateFormatter( "de-DE" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
        'America/Sao_Paulo',IntlDateFormatter::GREGORIAN  );
    echo "Segunda saída formatada é ".$fmt->format(0)."\n";

    $fmt = new IntlDateFormatter( "pt_BR" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
         'America/Sao_Paulo',IntlDateFormatter::GREGORIAN  ,"MM/dd/yyyy");
    echo "Primeira saída formatada com modelo é ".$fmt->format(0)."\n";
    $fmt = new IntlDateFormatter( "de-DE" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
          'America/Sao_Paulo',IntlDateFormatter::GREGORIAN , "MM/dd/yyyy");
    echo "Segunda saída formatada com modelo é ".$fmt->format(0)."\n";
    ?>

Exemplo #3 Exemplo de manipulação de localidade inválida

    <?php
    try {
        $fmt = new IntlDateFormatter(
            'invalid_locale',
            IntlDateFormatter::FULL,
            IntlDateFormatter::FULL,
            'dunno',
            IntlDateFormatter::GREGORIAN,
        );
    } catch (\Error $e) {
        // ...
    }
    ?>

O exemplo acima produzirá:

    Primeira saída formatada é quarta-feira, 31 de dezembro de 1969 21:00:00 Horário Padrão de Brasília
    Segunda saída formatada é Mittwoch, 31. Dezember 1969 um 21:00:00 Brasília-Normalzeit
    Primeira saída formatada com modelo é 12/31/1969
    Segunda saída formatada com modelo é 12/31/1969

### Veja Também

- datefmt_format() - Formata data/horário como uma string
- datefmt_parse() - Interpreta uma string para uma valor de timestamp
- datefmt_get_error_code() - Obtém o código de erro da última operação
- datefmt_get_error_message() - Obtém a mensagem de erro da última operação

# IntlDateFormatter::format

# datefmt_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::format -- datefmt_format — Formata data/horário como uma string

### Descrição

Estilo orientado a objetos

public function IntlDateFormatter::format(IntlCalendar|DateTimeInterface|array|string|int|float `$datetime`): string|false

Estilo procedural

function datefmt_format(IntlDateFormatter `$formatter`, IntlCalendar|DateTimeInterface|array|string|int|float `$datetime`): string|false

Formata o valor de data/horário como uma string.

### Parâmetros

`formatter`

  O recurso de formatador de data.

`datetime`

  O valor a ser formatado. Pode ser um objeto DateTimeInterface, um objeto IntlCalendar, um valor do tipo numeric representando um número (possivelmente fracionário) de segundos desde a época ou um array no formato da saída de localtime().

  Se um objeto DateTime ou IntlCalendar for passado, seu fuso horário não será considerado. O objeto será formatado usando o fuso horário configurado pelo formatador. Se for desejado usar o fuso horário do objeto a ser formatado, IntlDateFormatter::setTimeZone() deve ser chamada antes com o fuso horário do objeto. Alternativamente, a função estática IntlDateFormatter::formatObject() pode ser usada em seu lugar.

### Valor Retornado

A string formatada ou, se ocorrer um erro, `false`.

### Registro de Alterações

Versão | Descrição
--- | ---
7.1.5 | Suporte para fornecer objetos DateTimeInterface ao parâmetro `datetime` foi adicionado. Anteriormente, somente objetos DateTime eram suportados.
PECL intl 3.0.0 | Suporte para fornecer objetos IntlCalendar ao parâmetro `datetime` foi adicionado.

### Exemplos

Exemplo #1 Exemplo de datefmt_format()

    <?php
    $fmt = datefmt_create(
        'pt_BR',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Sao_Paulo',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Primeira saída formatada é ' . datefmt_format($fmt, 0);

    $fmt = datefmt_create(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Sao_Paulo',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Segunda saída formatada é ' . datefmt_format($fmt, 0);

    $fmt = datefmt_create(
        'pt_BR',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Sao_Paulo',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'Primeira saída formatada com modelo é ' . datefmt_format($fmt, 0);

    $fmt = datefmt_create(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Sao_Paulo',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo "Segunda saída formatada com modelo é " . datefmt_format($fmt, 0);
    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new IntlDateFormatter(
        'pt_BR',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Sao_Paulo',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Primeira saída formatada é ' . $fmt->format(0), "\n";

    $fmt = new IntlDateFormatter(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Sao_Paulo',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Segunda saída formatada é ' . $fmt->format(0), "\n";

    $fmt = new IntlDateFormatter(
        'pt_BR',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Sao_Paulo',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'Primeira saída formatada com modelo é ' . $fmt->format(0), "\n";

    $fmt = new IntlDateFormatter(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Sao_Paulo',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'Segunda saída formatada com modelo é ' . $fmt->format(0), "\n";
    ?>

O exemplo acima produzirá:

    Primeira saída formatada é quarta-feira, 31 de dezembro de 1969 21:00:00 Horário Padrão de Brasília
    Segunda saída formatada é Mittwoch, 31. Dezember 1969 um 21:00:00 Brasília-Normalzeit
    Primeira saída formatada com modelo é 12/31/1969
    Segunda saída formatada com modelo é 12/31/1969

Exemplo #3 Com objeto IntlCalendar

    <?php
    $tz = reset(iterator_to_array(IntlTimeZone::createEnumeration('FR')));
    $formatter = IntlDateFormatter::create(
        'fr_FR',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        $tz,
        IntlDateFormatter::GREGORIAN
    );

    $cal = IntlCalendar::createInstance($tz, '@calendar=islamic-civil');
    $cal->set(IntlCalendar::FIELD_MONTH, 8); //9º mês, Ramadã
    $cal->set(IntlCalendar::FIELD_DAY_OF_MONTH, 1); //1º dia
    $cal->clear(IntlCalendar::FIELD_HOUR_OF_DAY);
    $cal->clear(IntlCalendar::FIELD_MINUTE);
    $cal->clear(IntlCalendar::FIELD_SECOND);
    $cal->clear(IntlCalendar::FIELD_MILLISECOND);

    echo "Neste ano islâmico, o Ramadã começou/começará em:\n\t",
            $formatter->format($cal), "\n";

    //O fuso horário do formatador será o o utilizado:
    $formatter->setTimeZone('Asia/Tokyo');
    echo "Após alterar o fuso horário:\n\t",
            $formatter->format($cal), "\n";

O exemplo acima produzirá:

    Neste ano islâmico, o Ramadã começou/começará em:
        mardi 9 juillet 2013 19:00:00 heure avancée d’Europe centrale
    Após alterar o fuso horário:
        mercredi 10 juillet 2013 02:00:00 heure normale du Japon

### Veja Também

- datefmt_create() - Cria um formatador de data
- datefmt_parse() - Interpreta uma string para uma valor de timestamp
- datefmt_get_error_code() - Obtém o código de erro da última operação
- datefmt_get_error_message() - Obtém a mensagem de erro da última operação
- datefmt_format_object() - Formata um objeto

# IntlDateFormatter::formatObject

# datefmt_format_object

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL intl >= 3.0.0)

IntlDateFormatter::formatObject -- datefmt_format_object — Formata um objeto

### Descrição

Estilo orientado a objetos

public static function IntlDateFormatter::formatObject(IntlCalendar|DateTimeInterface `$datetime`, array|int|string|null `$format` = `null`, ?string `$locale` = `null`): string|false

Estilo procedural

function datefmt_format_object(IntlCalendar|DateTimeInterface `$datetime`, array|int|string|null `$format` = `null`, ?string `$locale` = `null`): string|false

Esta função permite formatar um objeto IntlCalendar ou DateTime sem que antes seja criado um objeto IntlDateFormatter explicitamente.

O objeto IntlDateFormatter temporário que será criado irá receber o fuso horário do objeto passado. O banco de dados de fuso horário incluído com o PHP não será utilizado - o banco da ICU será usado no lugar. O identificador de fuso horário usado em objetos DateTime precisa, portanto, existir também no banco de dados da ICU.

### Parâmetros

`datetime`

  Um objeto da classe IntlCalendar ou DateTime. A informação de fuso horário no objeto será utilizada.

`format`

  Este parâmetro indica como formatar a data/horário. Pode ser um array com dois elementos (primeiro o estilo de data, depois o de horário, com uma das constantes `IntlDateFormatter::NONE`, `IntlDateFormatter::SHORT`, `IntlDateFormatter::MEDIUM`, `IntlDateFormatter::LONG`, `IntlDateFormatter::FULL`), um int com o valor de uma dessas constantes (que no caso será usado tanto para o horário como para a data) ou uma string com o formato descrito na » documentação ICU. Caso seja `null`, o estilo padrão será usado.

`locale`

  A localidade a ser utilizada, ou `null` para usar a localidade padrão.

### Valor Retornado

Uma string com o resultado ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplos de IntlDateFormatter::formatObject()

    <?php
    /* fuso horário padrão é irrelevante; o fuso horário vem do objeto */
    ini_set('date.timezone', 'UTC');
    /* localidade padrão é lida desta configuração ini */
    ini_set('intl.default_locale', 'fr_FR');

    $cal = IntlCalendar::fromDateTime("2013-06-06 17:05:06 Europe/Dublin");
    echo "padrão:\n\t",
            IntlDateFormatter::formatObject($cal),
            "\n";

    echo "\$format longo (FULL):\n\t",
            IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL),
            "\n";

    echo "\$format array (NONE, FULL):\n\t",
            IntlDateFormatter::formatObject($cal, array(
                    IntlDateFormatter::NONE,
                    IntlDateFormatter::FULL)),
            "\n";

    echo "\$format string (d 'of' MMMM y):\n\t",
            IntlDateFormatter::formatObject($cal, "d 'of' MMMM y", 'en_US'),
            "\n";

    echo "com DateTime:\n\t",
            IntlDateFormatter::formatObject(
                    new DateTime("2013-09-09 09:09:09 Europe/Madrid"),
                    IntlDateFormatter::FULL,
                    'es_ES'),
            "\n";

O exemplo acima produzirá:

    default:
        6 juin 2013 17:05:06
    $format longo (FULL):
        jeudi 6 juin 2013 17:05:06 heure d’été irlandaise
    $format array (NONE, FULL):
        17:05:06 heure d’été irlandaise
    $format string (d 'of' MMMM y):
        6 of June 2013
    com DateTime:
        lunes, 9 de septiembre de 2013 09:09:09 Hora de verano de Europa central

# IntlDateFormatter::getCalendar

# datefmt_get_calendar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getCalendar -- datefmt_get_calendar — Obtém o tipo de calendário usado para o IntlDateFormatter

### Descrição

Estilo orientado a objetos

public function IntlDateFormatter::getCalendar(): int|false

Estilo procedural

function datefmt_get_calendar(IntlDateFormatter `$formatter`): int|false

### Parâmetros

`formatter`

  O recurso do formatador

### Valor Retornado

O tipo de calendário sendo usado pelo formatador. Pode ser `IntlDateFormatter::TRADITIONAL` ou `IntlDateFormatter::GREGORIAN`. Retorna `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de datefmt_get_calendar()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'O calendário do formatador é : ' . datefmt_get_calendar($fmt);
    datefmt_set_calendar($fmt, IntlDateFormatter::TRADITIONAL);
    echo 'Agora o calendário do formatador é : ' . datefmt_get_calendar($fmt);
    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'O calendário do formatador é : ' . $fmt->getCalendar();
    $fmt->setCalendar(IntlDateFormatter::TRADITIONAL);
    echo 'Agora o calendário do formatador é : ' . $fmt->getCalendar();

    ?>

Exemplo #3 Exemplo de manipulação de localidade inválida

    <?php
    try {
        $fmt = new IntlDateFormatter(
            'invalid_locale',
            IntlDateFormatter::FULL,
            IntlDateFormatter::FULL,
            'dunno',
            IntlDateFormatter::GREGORIAN,
        );
        $cal = $fmt->getCalendar();
    } catch (\Error $e) {
        // ...
    }
    ?>

O exemplo acima produzirá:

    O calendário do formatador é : 1
    Agora o calendário do formatador é : 0

### Veja Também

- datefmt_get_calendar_object() - Obtém uma cópia do objeto de calendário do formatador
- datefmt_set_calendar() - Define o tipo de calendário usado pelo formatador
- datefmt_create() - Cria um formatador de data

# IntlDateFormatter::getDateType

# datefmt_get_datetype

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getDateType -- datefmt_get_datetype — Obtém o tipo de data usado para o IntlDateFormatter

### Descrição

Estilo orientado a objetos

public function IntlDateFormatter::getDateType(): int|false

Estilo procedural

function datefmt_get_datetype(IntlDateFormatter `$formatter`): int|false

Retorna o tipo de data usado pelo formatador.

### Parâmetros

`formatter`

  O recurso do formatador.

### Valor Retornado

O valor de tipo de data atual do formatador, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de datefmt_get_datetype()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Tipo de data do formatador é: ' . datefmt_get_datetype($fmt);
    echo 'A primeira saída formatada é ' . datefmt_format($fmt, 0);

    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::SHORT,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Agora o tipo de data do formatador é: ' . datefmt_get_datetype($fmt);
    echo 'A segunda saída formatada com o tipo de data é ' . datefmt_format($fmt, 0);

    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Tipo de data do formatador é: ' . $fmt->getDateType();
    echo 'A primeira saída formatada é ' . $fmt->format(0);
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::SHORT,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Agora o tipo de data do formatador é: ' . $fmt->getDateType();
    echo 'A segunda saída formatada com o tipo de data é ' . $fmt->format(0);

    ?>

O exemplo acima produzirá:

    Tipo de data do formatador é: 0
    A primeira saída formatada é Wednesday, December 31, 1969 4:00:00 PM PT
    Agora o tipo de data do formatador é: 2
    A segunda saída formatada com o tipo de data é 12/31/69 4:00:00 PM PT

### Veja Também

- datefmt_get_timetype() - Obtém o tipo de horário usado para o IntlDateFormatter
- datefmt_create() - Cria um formatador de data

# IntlDateFormatter::getErrorCode

# datefmt_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getErrorCode -- datefmt_get_error_code — Obtém o código de erro da última operação

### Descrição

Estilo orientado a objetos

public function IntlDateFormatter::getErrorCode(): int

Estilo procedural

function datefmt_get_error_code(IntlDateFormatter `$formatter`): int

Retorn o código de erro da última operação de formatação.

### Parâmetros

`formatter`

  O recurso do formatador.

### Valor Retornado

O código de erro, um dos valores de UErrorCode. Se não houver erro, o valor é U_ZERO_ERROR.

### Exemplos

Exemplo #1 Exemplo de datefmt_get_error_code()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    $str = datefmt_format($fmt,0);

    printf(
        "ERRO: %s (%d)\n",
        datefmt_get_error_message($fmt),
        datefmt_get_error_code($fmt)
    );
    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    $str = $fmt->format(0);

    printf(
        "ERRO: %s (%d)\n",
        $fmt->getErrorMessage(),
        $fmt->getErrorCode()
    );
    ?>

O exemplo acima produzirá:

    ERRO: U_ZERO_ERROR (0)

### Veja Também

- datefmt_get_error_message() - Obtém a mensagem de erro da última operação
- intl_get_error_code() - Obtém o último código de erro
- intl_is_failure() - Verifica se o código de erro fornecido indica falha

# IntlDateFormatter::getErrorMessage

# datefmt_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getErrorMessage -- datefmt_get_error_message — Obtém a mensagem de erro da última operação

### Descrição

Estilo orientado a objetos

public function IntlDateFormatter::getErrorMessage(): string

Estilo procedural

function datefmt_get_error_message(IntlDateFormatter `$formatter`): string

Retorna a mensagem de erro da última operação de formatação.

### Parâmetros

`formatter`

  O recurso do formatador.

### Valor Retornado

Descrição do último erro.

### Exemplos

Exemplo #1 Exemplo de datefmt_get_error_message()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    $str = datefmt_format($fmt, 0);

    printf(
        "ERRO: %s (%d)\n",
        datefmt_get_error_message($fmt),
        datefmt_get_error_code($fmt)
    );
    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    $str = $fmt->format(0);

    printf(
        "ERRO: %s (%d)\n",
        $fmt->getErrorMessage(),
        $fmt->getErrorCode()
    );
    ?>

O exemplo acima produzirá:

    ERRO: U_ZERO_ERROR (0)

### Veja Também

- datefmt_get_error_code() - Obtém o código de erro da última operação
- intl_get_error_code() - Obtém o último código de erro
- intl_is_failure() - Verifica se o código de erro fornecido indica falha

# IntlDateFormatter::getLocale

# datefmt_get_locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getLocale -- datefmt_get_locale — Obtém a localidade usada pelo formatador

### Descrição

Estilo orientado a objetos

public function IntlDateFormatter::getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false

Estilo procedural

function datefmt_get_locale(IntlDateFormatter `$formatter`, int `$type` = `ULOC_ACTUAL_LOCALE`): string|false

Obtém a localidade usada pelo formatador.

### Parâmetros

`formatter`

  O recurso do formatador

`type`

  Pode-se escolher entre localidade válida e real ( `Locale::VALID_LOCALE`, `Locale::ACTUAL_LOCALE`, respectivamente). O padrão é a localidade real.

### Valor Retornado

A localidade do formatador, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de datefmt_get_locale()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Localidade do formatador é: ' . datefmt_get_locale($fmt), "\n";
    echo 'Primeira saída formatada é ' . datefmt_format($fmt, 0), "\n";

    $fmt = datefmt_create(
        'pt_BR',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Localidade do formatador é: ' . datefmt_get_locale($fmt), "\n";
    echo 'Segunda saída formatada é ' . datefmt_format($fmt, 0), "\n";

    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Localidade do formatador é: ' . $fmt->getLocale(), "\n";
    echo 'Primeira saída formatada é ' . $fmt->format(0), "\n";

    $fmt = new IntlDateFormatter(
        'pt_BR',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Localidade do formatador é: ' . $fmt->getLocale(), "\n";
    echo 'Segunda saída formatada é ' . $fmt->format(0), "\n";

    ?>

O exemplo acima produzirá:

    Localidade do formatador é: en
    Primeira saída formatada é Wednesday, December 31, 1969 at 4:00:00 PM Pacific Standard Time
    Localidade do formatador é: pt
    Segunda saída formatada é quarta-feira, 31 de dezembro de 1969 16:00:00 Horário Padrão do Pacífico

### Veja Também

- datefmt_create() - Cria um formatador de data

# IntlDateFormatter::getPattern

# datefmt_get_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getPattern -- datefmt_get_pattern — Obtém o modelo usado para o IntlDateFormatter

### Descrição

Estilo orientado a objetos

public function IntlDateFormatter::getPattern(): string|false

Estilo procedural

function datefmt_get_pattern(IntlDateFormatter `$formatter`): string|false

Obtém o modelo usado pelo formatador.

### Parâmetros

`formatter`

  O recurso do formatador.

### Valor Retornado

A string do modelo sendo usado para formatar/interpretar, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de datefmt_get_pattern()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'Modelo do formatador é : ' . datefmt_get_pattern($fmt);
    echo 'Primeira saída formatada com o modelo é ' . datefmt_format($fmt, 0);
    datefmt_set_pattern($fmt,'yyyymmdd hh:mm:ss z');
    echo 'Agora o modelo do formatador é : ' . datefmt_get_pattern($fmt);
    echo 'Segunda saída formatada com o modelo é ' . datefmt_format($fmt, 0);

    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'Modelo do formatador é : ' . $fmt->getPattern();
    echo 'Primeira saída formatada com o modelo é ' . $fmt->format(0);
    $fmt->setPattern('yyyyMMdd hh:mm:ss z');
    echo 'Agora o modelo do formatador é : ' . $fmt->getPattern();
    echo 'Segunda saída formatada com o modelo é ' . $fmt->format(0);
    ?>

O exemplo acima produzirá:

    Modelo do formatador é : MM/dd/yyyy
    Primeira saída formatada com o modelo é 12/31/1969
    Agora o modelo do formatador é : yyyyMMdd hh:mm:ss z
    Segunda saída formatada com o modelo é 19691231 04:00:00 PST

### Veja Também

- datefmt_set_pattern() - Define o modelo usado para o IntlDateFormatter
- datefmt_create() - Cria um formatador de data

# IntlDateFormatter::getTimeType

# datefmt_get_timetype

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getTimeType -- datefmt_get_timetype — Obtém o tipo de horário usado para o IntlDateFormatter

### Descrição

Estilo orientado a objetos

public function IntlDateFormatter::getTimeType(): int|false

Estilo procedural

function datefmt_get_timetype(IntlDateFormatter `$formatter`): int|false

Retorna o tipo de horário usado pelo formatador.

### Parâmetros

`formatter`

  O recurso do formatador.

### Valor Retornado

O valor do tipo de horário atual do formatador, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de datefmt_get_timetype()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Tipo de horário do formatador é : ' . datefmt_get_timetype($fmt), "\n";
    echo 'Primeira saída formatada com o tipo de horário é ' . datefmt_format($fmt, 0), "\n";

    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::SHORT,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Agora o tipo de horário do formatador é : ' . datefmt_get_timetype($fmt), "\n";
    echo 'Segunda saída formatada com o tipo de horário é ' . datefmt_format($fmt, 0), "\n";

    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Tipo de horário do formatador é : ' . $fmt->getTimeType(), "\n";
    echo 'Primeira saída formatada com o tipo de horário é ' . $fmt->format(0), "\n";

    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::SHORT,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Agora o tipo de horário do formatador é : ' . $fmt->getTimeType(), "\n";
    echo 'Segunda saída formatada com o tipo de horário é ' . $fmt->format(0), "\n";

    ?>

O exemplo acima produzirá:

    Tipo de horário do formatador é : 0
    Primeira saída formatada com o tipo de horário é Wednesday, December 31, 1969 at 4:00:00 PM Pacific Standard Time
    Agora o tipo de horário do formatador é : 3
    Segunda saída formatada com o tipo de horário é Wednesday, December 31, 1969 at 4:00 PM

### Veja Também

- datefmt_get_datetype() - Obtém o tipo de data usado para o IntlDateFormatter
- datefmt_create() - Cria um formatador de data

# IntlDateFormatter::getTimeZoneId

# datefmt_get_timezone_id

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getTimeZoneId -- datefmt_get_timezone_id — Obtém o identificador de fuso horário usado para o IntlDateFormatter

### Descrição

Estilo orientado a objetos

public function IntlDateFormatter::getTimeZoneId(): string|false

Estilo procedural

function datefmt_get_timezone_id(IntlDateFormatter `$formatter`): string|false

Obtém o identificador de fuso horário usado para o IntlDateFormatter.

### Parâmetros

`formatter`

  O recurso do formatador.

### Valor Retornado

String contendo o ID para o fuso horário usado pelo formatador, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de datefmt_get_timezone_id()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'ID de fuso horário do formatador é: ' . datefmt_get_timezone_id($fmt) . "\n";
    datefmt_set_timezone($fmt, 'Europe/Madrid');
    echo 'Agora, o ID de fuso horário do formatador é: ' . datefmt_get_timezone_id($fmt);

    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'ID de fuso horário do formatador é: ' . $fmt->getTimezoneId() . "\n";
    $fmt->setTimezone('Europe/Madrid');
    echo 'Agora, o ID de fuso horário do formatador é: ' . $fmt->getTimezoneId();

    ?>

O exemplo acima produzirá:

    ID de fuso horário do formatador é: America/Los_Angeles
    Agora, o ID de fuso horário do formatador é: Europe/Madrid

### Veja Também

- datefmt_set_timezone() - Define o fuso horário do formatador
- datefmt_create() - Cria um formatador de data

# IntlDateFormatter::getCalendarObject

# datefmt_get_calendar_object

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL intl >= 3.0.0)

IntlDateFormatter::getCalendarObject -- datefmt_get_calendar_object — Obtém uma cópia do objeto de calendário do formatador

### Descrição

Estilo orientado a objetos

public function IntlDateFormatter::getCalendarObject(): IntlCalendar|false|null

Estilo procedural

function datefmt_get_calendar_object(IntlDateFormatter `$formatter`): IntlCalendar|false|null

Obtém uma cópia do objeto de calendário usado internamente pelo formatador. Este calendário terá um tipo (como gregoriano, japonês, budista, persa, islâmico, etc.) e um fuso horário que corresponde ao tipo e ao fuso usados pelo formatador. A data e o horário do objeto não são especificados.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Uma cópia do objeto de calendário interno usado pelo formatador, ou `null` se nenhum foi definido, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de IntlDateFormatter::getCalendarObject()

    <?php
    $formatter = IntlDateFormatter::create(
        "fr_FR@calendar=islamic",
        NULL,
        NULL,
        "GMT-01:00",
        IntlDateFormatter::TRADITIONAL
    );

    $cal = $formatter->getCalendarObject();

    var_dump(
        $cal->getType(),
        $cal->getTimeZone(),
        $cal->getLocale(Locale::VALID_LOCALE)
    );

O exemplo acima produzirá:

    string(7) "islamic"
    object(IntlTimeZone)#3 (4) {
      ["valid"]=>
      bool(true)
      ["id"]=>
      string(9) "GMT-01:00"
      ["rawOffset"]=>
      int(-3600000)
      ["currentOffset"]=>
      int(-3600000)
    }
    string(5) "fr_FR"

### Veja Também

- IntlDateFormatter::getCalendar() - Obtém o tipo de calendário usado para o IntlDateFormatter
- IntlDateFormatter::setCalendar() - Define o tipo de calendário usado pelo formatador
- IntlCalendar

# IntlDateFormatter::getTimeZone

# datefmt_get_timezone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL intl >= 3.0.0)

IntlDateFormatter::getTimeZone -- datefmt_get_timezone — Obtem o fuso horário do formatador

### Descrição

Estilo orientado a objetos

public function IntlDateFormatter::getTimeZone(): IntlTimeZone|false

Estilo procedural

function datefmt_get_timezone(IntlDateFormatter `$formatter`): IntlTimeZone|false

Retorna um objeto IntlTimeZone representando o fuso horário que será usado por este objeto para formatar datas e horários. Ao formatar objetos IntlCalendar e DateTime com esta classe IntlDateFormatter, o fuso horário usado será o retornado por este método, e não o associado com os objetos sendo formatados.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O objeto IntlTimeZone associado ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplos de IntlDateFormatter::getTimeZone()

    <?php

    $madrid = IntlDateFormatter::create(NULL, NULL, NULL, 'Europe/Madrid');
    $lisbon = IntlDateFormatter::create(NULL, NULL, NULL, 'Europe/Lisbon');

    var_dump($madrid->getTimezone());
    echo $madrid->getTimezone()->getDisplayName(
            false, IntlTimeZone::DISPLAY_GENERIC_LOCATION, "en_US"), "\n";
    echo $lisbon->getTimeZone()->getId(), "\n";
    //O id também pode ser obtido com ->getTimezoneId()
    echo $lisbon->getTimeZoneId(), "\n";

O exemplo acima produzirá:

    object(IntlTimeZone)#4 (4) {
      ["valid"]=>
      bool(true)
      ["id"]=>
      string(13) "Europe/Madrid"
      ["rawOffset"]=>
      int(3600000)
      ["currentOffset"]=>
      int(7200000)
    }
    Spain Time
    Europe/Lisbon
    Europe/Lisbon

### Veja Também

- IntlDateFormatter::getTimeZoneId() - Obtém o identificador de fuso horário usado para o IntlDateFormatter
- IntlDateFormatter::setTimeZone() - Define o fuso horário do formatador
- IntlTimeZone

# IntlDateFormatter::isLenient

# datefmt_is_lenient

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::isLenient -- datefmt_is_lenient — Obtém a leniência usada para o IntlDateFormatter

### Descrição

Estilo orientado a objetos

public function IntlDateFormatter::isLenient(): bool

Estilo procedural

function datefmt_is_lenient(IntlDateFormatter `$formatter`): bool

Verifica se o interpretador é estrito ou leniente ao interpretar entradas que não correspondem exatamente ao modelo.

### Parâmetros

`formatter`

  O recurso do formatador.

### Valor Retornado

`true` se o interpretador for leniente, `false` se for estrito. Por padrão o interpretador é leniente.

### Exemplos

Exemplo #1 Exemplo de datefmt_is_lenient()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'dd/MM/yyyy'
    );
    echo 'Leniência do formatador é : ';
    if ($fmt->isLenient()) {
        echo 'TRUE';
    } else {
        echo 'FALSE';
    }
    datefmt_parse($fmt, '35/13/1971');
    echo "\nTentando interpretar '35/13/1971'.\nO resultado é: " . datefmt_parse($fmt, '35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nMensagem de erro: " . intl_get_error_message();
        echo "\nCódigo de erro: " . intl_get_error_code();
    }
    datefmt_set_lenient($fmt,false);
    echo "\nAgora a leniência do formatador é: ";
    if ($fmt->isLenient()) {
        echo 'TRUE';
    } else {
        echo 'FALSE';
    }
    datefmt_parse($fmt, '35/13/1971');
    echo "\nTentando interpretar '35/13/1971'.\nO resultado é: " . datefmt_parse($fmt, '35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nMensagem de erro: " . intl_get_error_message();
        echo "\nCódigo de erro: " . intl_get_error_code();
    }

    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        "dd/MM/yyyy"
    );
    echo "Leniência do formatador é : ";
    if ($fmt->isLenient()) {
        echo 'TRUE';
    } else {
        echo 'FALSE';
    }
    $fmt->parse('35/13/1971');
    echo "\nTentando interpretar '35/13/1971'.\nO resultado é: " . $fmt->parse('35/13/1971');
    if (intl_get_error_code() != 0){
        echo "\nMensagem de erro: " . intl_get_error_message();
        echo "\nCódigo de erro: " . intl_get_error_code();
    }

    $fmt->setLenient(FALSE);
    echo "\nAgora a leniência do formatador é: ";
    if ($fmt->isLenient()) {
        echo 'TRUE';
    } else {
        echo 'FALSE';
    }
    $fmt->parse('35/13/1971');
    echo "\nTentando interpretar '35/13/1971'.\nO resultado é: " . $fmt->parse('35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nMensagem de erro: " . intl_get_error_message();
        echo "\nCódigo de erro: " . intl_get_error_code();
    }

    ?>

O exemplo acima produzirá:

    Leniência do formatador é : TRUE
    Tentando interpretar '35/13/1971'.
    O resultado é: 66038400
    Agora a leniência do formatador é: FALSE
    Tentando interpretar '35/13/1971'.
    O resultado é:
    Mensagem de erro: Date parsing failed: U_PARSE_ERROR
    Código de erro: 9

### Veja Também

- datefmt_set_lenient() - Define a leniência do interpretador
- datefmt_create() - Cria um formatador de data

# IntlDateFormatter::localtime

# datefmt_localtime

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::localtime -- datefmt_localtime — Interpreta uma string para um valor de horário baseado em campos

### Descrição

Estilo orientado a objetos

public function IntlDateFormatter::localtime(string `$string`, int `&$offset` = `null`): array|false

Estilo procedural

function datefmt_localtime(IntlDateFormatter `$formatter`, string `$string`, int `&$offset` = `null`): array|false

Converte o valor da string para um valor de horário baseado em campos (um array com vários campos), iniciando em offset e consumindo o máximo possível do valor de entrada.

### Parâmetros

`formatter`

  O recurso do formatador

`string`

  A string a ser convertida para um horário

`offset`

  Posição na qual a interpretação da string será iniciada (baseada em zero). Se não ocorrer erros antes que a string seja consumida, offset conterá -1, caso contrário conterá a posição na qual a interpretação terminou. Se offset > strlen(string), a interpretação falha imediatamente.

### Valor Retornado

Array de inteiros compatível com o horário da localidade: contém valor de hora no formato de 24 horas no campo tm_hour, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de datefmt_localtime()

    <?php

    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    $arr = datefmt_localtime($fmt, 'Wednesday, December 31, 1969 at 4:00:00 PM Pacific Standard Time', $offset);
    echo 'Valor interpretado: ';
    if ($arr) {
        foreach ($arr as $key => $value) {
            echo "$key : $value , ";
        }
    }

    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    $arr = $fmt->localtime('Wednesday, December 31, 1969 at 4:00:00 PM Pacific Standard Time', $offset);
    echo 'Valor interpretado: ';
    if ($arr) {
        foreach ($arr as $key => $value) {
            echo "$key : $value , ";
        }
    }

    ?>

O exemplo acima produzirá:

    Valor interpretado: tm_sec : 0 , tm_min : 0 , tm_hour : 16 , tm_year : 69 ,
    tm_mday : 31 , tm_wday : 3 , tm_yday : 365 , tm_mon : 11 , tm_isdst : 0 ,

### Veja Também

- datefmt_create() - Cria um formatador de data
- datefmt_format() - Formata data/horário como uma string
- datefmt_parse() - Interpreta uma string para uma valor de timestamp
- datefmt_get_error_code() - Obtém o código de erro da última operação
- datefmt_get_error_message() - Obtém a mensagem de erro da última operação

# IntlDateFormatter::parse

# datefmt_parse

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::parse -- datefmt_parse — Interpreta uma string para uma valor de timestamp

### Descrição

Estilo orientado a objetos

public function IntlDateFormatter::parse(string `$string`, int `&$offset` = `null`): int|float|false

Estilo procedural

function datefmt_parse(IntlDateFormatter `$formatter`, string `$string`, int `&$offset` = `null`): int|float|false

Converte `string` para um valor de tempo incremental, iniciando em `offset` e consumindo o máximo possível do valor de entrada.

### Parâmetros

`formatter`

  O recurso do formatador

`string`

  String a ser convertida para um horário.

`offset`

  Posição na qual será iniciada a interpretação da `string` (baseada em zero). Se nenhum erro ocorrer antes que a `string` seja consumida, `offset` conterá -1, caso contrário conterá a posição na qual a interpretação terminou (e onde o erro ocorreu). Se `offset` > `strlen($string)`, a interpretação falha imediatamente.

### Valor Retornado

Timestamp do valor interpretado, ou `false` se o valor não puder ser interpretado.

### Exemplos

Exemplo #1 Exemplo OO

    <?php
    $fmt = new IntlDateFormatter(
        'pt_BR',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Sao_Paulo', IntlDateFormatter::GREGORIAN
    );
    echo 'Primeira saída interpretada: ' . $fmt->parse('quinta-feira, 20 de julho de 1989 21:00:00 Horário Padrão de Brasília');
    $fmt = new IntlDateFormatter(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Sao_Paulo',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Segunda saída interpretada: ' . datefmt_parse($fmt, 'Donnerstag, 20. Juli 1989 um 21:00:00 Brasília-Normalzeit');
    ?>

Exemplo #2 Exemplo de datefmt_parse()

    <?php
    $fmt = datefmt_create(
        'pt_BR',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Sao_Paulo',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Primeira saída interpretada: ' . datefmt_parse($fmt, 'quinta-feira, 20 de julho de 1989 21:00:00 Horário Padrão de Brasília');
    $fmt = datefmt_create(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Sao_Paulo',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Segunda saída interpretada: ' . datefmt_parse($fmt, 'Donnerstag, 20. Juli 1989 um 21:00:00 Brasília-Normalzeit');
    ?>

O exemplo acima produzirá:

    Primeira saída interpretada: 616982400
    Segunda saída interpretada: 616982400

### Veja Também

- datefmt_create() - Cria um formatador de data
- datefmt_format() - Formata data/horário como uma string
- datefmt_localtime() - Interpreta uma string para um valor de horário baseado em campos
- datefmt_get_error_code() - Obtém o código de erro da última operação
- datefmt_get_error_message() - Obtém a mensagem de erro da última operação

# IntlDateFormatter::parseToCalendar

(PHP 8 >= 8.4.0)

IntlDateFormatter::parseToCalendar — Analisa uma string e a converte em um timestamp, atualizando um calendário aberto

### Descrição

public function IntlDateFormatter::parseToCalendar(string `$string`, int `&$offset` = `null`): int|float|false

Converte `string` em um valor de tempo incremental, começando em `offset` e consumindo o máximo possível do valor de entrada.

Este método se comporta como IntlDateFormatter::parse(), exceto que o fuso horário do formatador é atualizado de acordo com as informações de fuso horário contidas na `string` analisada.

### Parâmetros

`string`
  A string a ser convertida em um horário.
`offset`
  Posição inicial da análise em `string` (base zero). Se nenhum erro ocorrer antes da `string` ser consumida, `offset` conterá -1; caso contrário, conterá a posição em que a análise terminou (e o erro ocorreu). Esta variável conterá a posição final se a análise falhar. Se `offset` > `strlen($string)`, a análise falhará imediatamente.

### Valor Retornado

Timestamp do valor analisado ou `false` se o valor não puder ser analisado.

### Exemplos

Exemplo #1 Exemplo de IntlDateFormatter::parseToCalendar()

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo $fmt->parseToCalendar('Wednesday, December 20, 1989 at 4:00:00 PM Pacific Standard Time');
    ?>

O exemplo acima produzirá:

    630201600

### Veja Também

- IntlDateFormatter::parse() - Interpreta uma string para uma valor de timestamp
- IntlDateFormatter::format() - Formata data/horário como uma string
- IntlDateFormatter::getErrorCode() - Obtém o código de erro da última operação
- IntlDateFormatter::getErrorMessage() - Obtém a mensagem de erro da última operação

# IntlDateFormatter::setCalendar

# datefmt_set_calendar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::setCalendar -- datefmt_set_calendar — Define o tipo de calendário usado pelo formatador

### Descrição

Estilo orientado a objetos

public function IntlDateFormatter::setCalendar(IntlCalendar|int|null `$calendar`): bool

Estilo procedural

function datefmt_set_calendar(IntlDateFormatter `$formatter`, IntlCalendar|int|null `$calendar`): bool

Define o tipo de calendário usado pelo formatador.

### Parâmetros

`formatter`

  O recurso do formatador.

`calendar`

  Pode ser: o tipo de calendário a ser usado (o padrão é `IntlDateFormatter::GREGORIAN`, que também é usado se `null` for especificado) ou um objeto IntlCalendar.

  Qualquer objeto IntlCalendar passado será clonado; nenhuma modificação será feita no objeto do argumento.

  O fuso horário do formatador somente será mantido se um objeto IntlCalendar não for passado, caso contrário o novo fuso horário será o do objeto passado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL intl 3.0.0 | Tornou-se possível passar um objeto IntlCalendar.

### Exemplos

Exemplo #1 Exemplo de datefmt_set_calendar()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'O calendário do formatador é: ' . datefmt_get_calendar($fmt), "\n";
    datefmt_set_calendar($fmt, IntlDateFormatter::TRADITIONAL);
    echo 'Agora, o calendário do formatador é: ' . datefmt_get_calendar($fmt);
    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'O calendário do formatador é: ' . $fmt->getCalendar(), "\n";
    $fmt->setCalendar(IntlDateFormatter::TRADITIONAL);
    echo 'Agora, o calendário do formatador é: ' . $fmt->getCalendar();
    ?>

O exemplo acima produzirá:

    O calendário do formatador é: 1
    Agora, o calendário do formatador é: 0

Exemplo #3 Exemplo com argumento IntlCalendar

    <?php
    $time = strtotime("2013-03-03 00:00:00 UTC");
    $formatter = IntlDateFormatter::create("en_US", NULL, NULL, "Europe/Amsterdam");

    echo "antes: ", $formatter->format($time), "\n";

    /* note que a localidade do calendário não é usada! */
    $formatter->setCalendar(IntlCalendar::createInstance(
                   "America/New_York", "pt_BR@calendar=islamic"));

    echo "depois:  ", $formatter->format($time), "\n";
    ?>

O exemplo acima produzirá:

    antes: Sunday, March 3, 2013 at 1:00:00 AM Central European Standard Time
    depois:  Saturday, Rabiʻ II 20, 1434 at 7:00:00 PM Eastern Standard Time

### Veja Também

- datefmt_get_calendar() - Obtém o tipo de calendário usado para o IntlDateFormatter
- datefmt_get_calendar_object() - Obtém uma cópia do objeto de calendário do formatador
- datefmt_create() - Cria um formatador de data

# IntlDateFormatter::setLenient

# datefmt_set_lenient

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::setLenient -- datefmt_set_lenient — Define a leniência do interpretador

### Descrição

Estilo orientado a objetos

public function IntlDateFormatter::setLenient(bool `$lenient`): void

Estilo procedural

function datefmt_set_lenient(IntlDateFormatter `$formatter`, bool `$lenient`): void

Define se o interpretador é estrito ou leniente ao interpretar entradas que não correspondem exatamente ao modelo. Habilitar interpretação leniente permite ao interpretador aceitar modelos de data e horário que poderiam falhar, analisando o máximo possível para obter um valor. Espaços extras, marcadores não reconhecidos ou valores inválidos ("30 de fevereiro") não são aceitos.

### Parâmetros

`formatter`

  O recurso do formatador

`lenient`

  Define de o interpretador é leniente ou não, o padrão é `true` (leniente).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de datefmt_set_lenient()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'dd/MM/yyyy'
    );
    echo 'Leniência do formatador é : ';
    if ($fmt->isLenient()) {
        echo 'TRUE';
    } else {
        echo 'FALSE';
    }
    datefmt_parse($fmt, '35/13/1971');
    echo "\nTentando interpretar '35/13/1971'.\nO resultado é: " . datefmt_parse($fmt, '35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nMensagem de erro: " . intl_get_error_message();
        echo "\nCódigo de erro: " . intl_get_error_code();
    }
    datefmt_set_lenient($fmt,false);
    echo "\nAgora a leniência do formatador é: ";
    if ($fmt->isLenient()) {
        echo 'TRUE';
    } else {
        echo 'FALSE';
    }
    datefmt_parse($fmt, '35/13/1971');
    echo "\nTentando interpretar '35/13/1971'.\nO resultado é: " . datefmt_parse($fmt, '35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nMensagem de erro: " . intl_get_error_message();
        echo "\nCódigo de erro: " . intl_get_error_code();
    }

    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        "dd/MM/yyyy"
    );
    echo "Leniência do formatador é : ";
    if ($fmt->isLenient()) {
        echo 'TRUE';
    } else {
        echo 'FALSE';
    }
    $fmt->parse('35/13/1971');
    echo "\nTentando interpretar '35/13/1971'.\nO resultado é: " . $fmt->parse('35/13/1971');
    if (intl_get_error_code() != 0){
        echo "\nMensagem de erro: " . intl_get_error_message();
        echo "\nCódigo de erro: " . intl_get_error_code();
    }

    $fmt->setLenient(FALSE);
    echo "\nAgora a leniência do formatador é: ";
    if ($fmt->isLenient()) {
        echo 'TRUE';
    } else {
        echo 'FALSE';
    }
    $fmt->parse('35/13/1971');
    echo "\nTentando interpretar '35/13/1971'.\nO resultado é: " . $fmt->parse('35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nMensagem de erro: " . intl_get_error_message();
        echo "\nCódigo de erro: " . intl_get_error_code();
    }

    ?>

O exemplo acima produzirá:

    Leniência do formatador é : TRUE
    Tentando interpretar '35/13/1971'.
    O resultado é: 66038400
    Agora a leniência do formatador é: FALSE
    Tentando interpretar '35/13/1971'.
    O resultado é:
    Mensagem de erro: Date parsing failed: U_PARSE_ERROR
    Código de erro: 9

### Veja Também

- datefmt_is_lenient() - Obtém a leniência usada para o IntlDateFormatter
- datefmt_create() - Cria um formatador de data

# IntlDateFormatter::setPattern

# datefmt_set_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::setPattern -- datefmt_set_pattern — Define o modelo usado para o IntlDateFormatter

### Descrição

Estilo orientado a objetos

public function IntlDateFormatter::setPattern(string `$pattern`): bool

Estilo procedural

function datefmt_set_pattern(IntlDateFormatter `$formatter`, string `$pattern`): bool

Define o modelo usado para o IntlDateFormatter.

### Parâmetros

`formatter`

  O recurso do formatador.

`pattern`

  Nova string de modelo a ser utilizado. Os modelos possíveis estão documentados em » https://unicode-org.github.io/icu/userguide/format_parse/datetime/.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha. Strings de formato mal formadas são normalmente as causas de falhas.

### Exemplos

Exemplo #1 Exemplo de datefmt_set_pattern()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'Modelo do formatador é: ', datefmt_get_pattern($fmt), PHP_EOL;
    echo 'Primeira saída formatada é ', datefmt_format($fmt, 0), PHP_EOL;
    datefmt_set_pattern($fmt, 'yyyyMMdd hh:mm:ss z');
    echo 'Agora o modelo do formatador é: ', datefmt_get_pattern($fmt), PHP_EOL;
    echo 'Segunda saída formatada com o modelo é ', datefmt_format($fmt, 0), PHP_EOL;
    ?>

Exemplo #2 Exemplo OO

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'Modelo do formatador é: ', $fmt->getPattern(), PHP_EOL;
    echo 'Primeira saída formatada é ', $fmt->format(0), PHP_EOL;
    $fmt->setPattern('yyyyMMdd hh:mm:ss z');
    echo 'Agora o modelo do formatador é: ', $fmt->getPattern(), PHP_EOL;
    echo 'Segunda saída formatada com o modelo é ', $fmt->format(0), PHP_EOL;
    ?>

O exemplo acima produzirá:

    Modelo do formatador é: MM/dd/yyyy
    Primeira saída formatada é 12/31/1969
    Agora o modelo do formatador é: yyyyMMdd hh:mm:ss z
    Segunda saída formatada com o modelo é 19691231 04:00:00 PST

### Veja Também

- datefmt_get_pattern() - Obtém o modelo usado para o IntlDateFormatter
- datefmt_create() - Cria um formatador de data

# IntlDateFormatter::setTimeZone

# datefmt_set_timezone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL intl >= 3.0.0)

IntlDateFormatter::setTimeZone -- datefmt_set_timezone — Define o fuso horário do formatador

### Descrição

Estilo orientado a objetos

public function IntlDateFormatter::setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool

Estilo procedural

function datefmt_set_timezone(IntlDateFormatter `$formatter`, IntlTimeZone|DateTimeZone|string|null `$timezone`): bool

Define o fuso horário usado para o objeto IntlDateFormatter.

### Parâmetros

`formatter`

  O recurso do formatador.

`timezone`

  O fuso horário a ser utilizado para este formatador. Pode ser especificado nas formas a seguir:

  - `null`, neste caso o fuso horário padrão será usado, como especificado na configuração ini date.timezone ou através da função date_default_timezone_set() e como retornado por date_default_timezone_get().

  - Um objeto IntlTimeZone, que será usado diretamente.

  - Um objeto DateTimeZone. Seu identificador será extraído e um objeto de fuso horário ICU será criado; o fuso horário será apoiado pelo banco de dados da ICU, não pelo do PHP.

  - Uma string, que deve ser um identificador de fuso horário ICU válido. Consulte a função IntlTimeZone::createTimeZoneIDEnumeration(). Deslocamentos puros como `"GMT+08:30"` também são aceitos.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Esta função agora retorna `true` em caso de sucesso; anteriormente, retornava `null`.

### Exemplos

Exemplo #1 Exemplos de IntlDateFormatter::setTimeZone()

    <?php
    ini_set('date.timezone', 'Europe/Amsterdam');

    $formatter = IntlDateFormatter::create(NULL, NULL, NULL, "UTC");

    $formatter->setTimeZone(NULL);
    echo "NULL\n    ", $formatter->getTimeZone()->getId(), "\n";

    $formatter->setTimeZone(IntlTimeZone::createTimeZone('Europe/Lisbon'));
    echo "IntlTimeZone\n    ", $formatter->getTimeZone()->getId(), "\n";

    $formatter->setTimeZone(new DateTimeZone('Europe/Paris'));
    echo "DateTimeZone\n    ", $formatter->getTimeZone()->getId(), "\n";

    $formatter->setTimeZone('Europe/Rome');
    echo "String\n    ", $formatter->getTimeZone()->getId(), "\n";

    $formatter->setTimeZone('GMT+00:30');
    print_r($formatter->getTimeZone());

O exemplo acima produzirá:

    NULL
        Europe/Amsterdam
    IntlTimeZone
        Europe/Lisbon
    DateTimeZone
        Europe/Paris
    String
        Europe/Rome
    IntlTimeZone Object
    (
        [valid] => 1
        [id] => GMT+00:30
        [rawOffset] => 1800000
        [currentOffset] => 1800000
    )

### Veja Também

- IntlDateFormatter::getTimeZone() - Obtem o fuso horário do formatador

## Índice

- IntlDateFormatter::create — Cria um formatador de data
- IntlDateFormatter::format — Formata data/horário como uma string
- IntlDateFormatter::formatObject — Formata um objeto
- IntlDateFormatter::getCalendar — Obtém o tipo de calendário usado para o IntlDateFormatter
- IntlDateFormatter::getDateType — Obtém o tipo de data usado para o IntlDateFormatter
- IntlDateFormatter::getErrorCode — Obtém o código de erro da última operação
- IntlDateFormatter::getErrorMessage — Obtém a mensagem de erro da última operação
- IntlDateFormatter::getLocale — Obtém a localidade usada pelo formatador
- IntlDateFormatter::getPattern — Obtém o modelo usado para o IntlDateFormatter
- IntlDateFormatter::getTimeType — Obtém o tipo de horário usado para o IntlDateFormatter
- IntlDateFormatter::getTimeZoneId — Obtém o identificador de fuso horário usado para o IntlDateFormatter
- IntlDateFormatter::getCalendarObject — Obtém uma cópia do objeto de calendário do formatador
- IntlDateFormatter::getTimeZone — Obtem o fuso horário do formatador
- IntlDateFormatter::isLenient — Obtém a leniência usada para o IntlDateFormatter
- IntlDateFormatter::localtime — Interpreta uma string para um valor de horário baseado em campos
- IntlDateFormatter::parse — Interpreta uma string para uma valor de timestamp
- IntlDateFormatter::parseToCalendar — Analisa uma string e a converte em um timestamp, atualizando um calendário aberto
- IntlDateFormatter::setCalendar — Define o tipo de calendário usado pelo formatador
- IntlDateFormatter::setLenient — Define a leniência do interpretador
- IntlDateFormatter::setPattern — Define o modelo usado para o IntlDateFormatter
- IntlDateFormatter::setTimeZone — Define o fuso horário do formatador

# A classe ResourceBundle

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

## Introdução

Produtos de software específicos para localiades frequentemente requerem conjuntos de dados que devem ser customizados dependendo da localidade atual, ex.: mensagens, etiquetas, modelos de formatação. O mecanismo de recursos da ICU permite definir conjuntos de recursos que a aplicação pode carregar com base na localidade, enquanto acessa-as em uma maneira unificada, independente de localidade.

Esta classe implemente o acesso aos arquivos de dados de recursos ICU. Estes arquivos são arrays de dados binários que a ICU usa para armazenar os dados de localidade.

O pacote de recursos ICU pode ter recursos simples e complexos. Recursos complexos são contêineres que podem ser indexados com números inteiros ou strings (da mesma forma que arrays PHP). Recursos simples podem ser dos seguintes tipos: string, inteiro, campo de dado binário ou array inteiro.

ResourceBundle suporta acesso direto aos dados através de padrão de acesso a array e iteração através de foreach, assim como acesso por métodos de classe. O resultado será um valor PHP para os recursos simples e um objeto ResourceBundle para os complexos. Todos os recursos são somente-leitura.

## Resumo da classe

class ResourceBundle implements IteratorAggregate, Countable {
/* Métodos */
public function __construct(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`)
public function count(): int
public static function create(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`): ?ResourceBundle
public function get(string|int `$index`, bool `$fallback` = `true`): ResourceBundle|array|string|int|null
public function getErrorCode(): int
public function getErrorMessage(): string
public static function getLocales(string `$bundle`): array|false
}

## Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | ResourceBundle implementa IteratorAggregate agora. Anteriormente, Traversable era implementado no lugar.
7.4.0 | ResourceBundle implementa Countable agora.

## Veja Também

- » Gereciamento de Recursos ICU
- » Dados ICU

# ResourceBundle::count

# resourcebundle_count

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::count -- resourcebundle_count — Obtém o número de elementos no pacote

### Descrição

Estilo orientado a objetos

public function ResourceBundle::count(): int

Estilo procedural

function resourcebundle_count(ResourceBundle `$bundle`): int

Obtém o número de elementos no pacote.

### Parâmetros

`bundle`

  Um objeto ResourceBundle.

### Valor Retornado

Retorna o número de elementos no pacote.

### Exemplos

Exemplo #1 Exemplo da função resourcebundle_count()

    <?php
    $r = resourcebundle_create( 'es', "/usr/share/data/meuapp");
    echo resourcebundle_count($r);
    ?>

Exemplo #2 Exemplo orientado a objeto

    <?php
    $r = new ResourceBundle( 'es', "/usr/share/data/meuapp");
    echo $r->count();
    ?>

O exemplo acima produzirá:

    42

### Veja Também

- resourcebundle_get() - Obtém os dados do pacote

# ResourceBundle::create

# resourcebundle_create

# ResourceBundle::__construct

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::create -- resourcebundle_create -- ResourceBundle::__construct — Cria um pacote de recursos

### Descrição

Estilo orientado a objetos (method)

public static function ResourceBundle::create(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`): ?ResourceBundle

Estilo procedural

function resourcebundle_create(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`): ?ResourceBundle

Estilo orientado a objetos (constructor):

public function ResourceBundle::__construct(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`)

Cria um pacote de recursos.

### Parâmetros

`locale`

  Localidade para a qual os recursos devem ser carregados (nome da localidade, ex. en_CA).

`bundle`

  O diretório onde os dados estão armazenados ou o nome do arquivo .dat.

`fallback`

  Indica se a localidade deve ser uma correspondência exata ou se a retroação para a localidade base é permitida.

### Valor Retornado

Retorna um objeto ResourceBundle ou `null` caso haja erro.

### Exemplos

Exemplo #1 Exemplo de resourcebundle_create()

    <?php
    $r = resourcebundle_create( 'es', "/usr/share/data/myapp");
    echo $r['teststring'];
    ?>

Exemplo #2 Exemplo de ResourceBundle::create()

    <?php
    $r = ResourceBundle::create( 'es', "/usr/share/data/myapp");
    echo $r['teststring'];
    ?>

O exemplo acima produzirá:

    ¡Hola, mundo!

### Veja Também

- resourcebundle_get() - Obtém os dados do pacote

# ResourceBundle::get

# resourcebundle_get

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::get -- resourcebundle_get — Obtém os dados do pacote

### Descrição

Estilo orientado a objetos

public function ResourceBundle::get(string|int `$index`, bool `$fallback` = `true`): ResourceBundle|array|string|int|null

Estilo procedural

function resourcebundle_get(ResourceBundle `$bundle`, string|int `$index`, bool `$fallback` = `true`): ResourceBundle|array|string|int|null

Obtém os dados do pacote através de um índice ou de uma string chave.

### Parâmetros

`bundle`

  Um objeto ResourceBundle.

`index`

  O índice onde os dados estão. Pode ser uma string ou um intero.

`fallback`

  O locale alternativo no caso de não encontrar o item exato ou outra alternativa.

### Valor Retornado

Retorna os dados localizados no índice informado ou `null` caso haja erro. Strings, inteiros e dados em binário são retornados como seus tipo correspondentes em PHP. Um array de inteiros é retornado como um array PHP. Tipos complexos são retornados como objetos ResourceBundle.

### Erros/Exceções

Uma exceção TypeError é lançada se o tipo do índice for inválido.

Uma exceção ValueError é lançada se `index` for uma string e estiver vazia ou se for um int e não couber em um tipo inteiro de 32 bits.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Uma exceção TypeError é lançada se o tipo do índice for inválido. Uma exceção ValueError é lançada se `index` for uma string e estiver vazia ou se for um int e não couber em um tipo inteiro de 32 bits.

### Exemplos

Exemplo #1 Exemplo da função resourcebundle_get()

    <?php
    $r = resourcebundle_create( 'es', "/usr/share/data/myapp");
    echo resourcebundle_get($r, 'somestring');
    ?>

Exemplo #2 Exemplo orientado à objeto

    <?php
    $r = new ResourceBundle( 'es', "/usr/share/data/myapp");
    echo $r->get('somestring');
    ?>

O exemplo acima produzirá:

    ?Hola, mundo!

### Veja Também

- resourcebundle_count() - Obtém o número de elementos no pacote

# ResourceBundle::getErrorCode

# resourcebundle_get_error_code

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::getErrorCode -- resourcebundle_get_error_code — Obtém o código do último erro gerado pelo pacote.

### Descrição

Estilo orientado a objetos

public function ResourceBundle::getErrorCode(): int

Estilo procedural

function resourcebundle_get_error_code(ResourceBundle `$bundle`): int

Obtém o código do erro gerado pela última função realizada pelo objeto pacote.

### Parâmetros

`bundle`

  Um objeto ResourceBundle.

### Valor Retornado

Retorna o código de erro da última chamada do objeto pacote.

### Exemplos

Exemplo #1 Exemplo da função resourcebundle_get_error_code()

    <?php
    $r = resourcebundle_create( 'es', "/usr/share/data/myapp");
    echo $r['somestring'];
    if(intl_is_failure(resourcebundle_get_error_code($r))) {
        report_error("Bundle error");
    }
    ?>

Exemplo #2 Exemplo orientado à objeto

    <?php
    $r = new ResourceBundle( 'es', "/usr/share/data/myapp");
    echo $r['somestring'];
    if(intl_is_failure(ResourceBundle::getErrorCode($r))) {
        report_error("Bundle error");
    }
    ?>

### Veja Também

- resourcebundle_get_error_message() - Obtém a última mensagem de erro gerada pelo pacote
- intl_get_error_code() - Obtém o último código de erro
- intl_is_failure() - Verifica se o código de erro fornecido indica falha

# ResourceBundle::getErrorMessage

# resourcebundle_get_error_message

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::getErrorMessage -- resourcebundle_get_error_message — Obtém a última mensagem de erro gerada pelo pacote

### Descrição

Estilo orientado a objetos

public function ResourceBundle::getErrorMessage(): string

Estilo procedural

function resourcebundle_get_error_message(ResourceBundle `$bundle`): string

Obtém a mensagem do erro gerado pela última função realizada pelo objeto pacote.

### Parâmetros

`bundle`

  Um objeto ResourceBundle.

### Valor Retornado

Retorna a mensagem de erro da última chamada do objeto pacote.

### Exemplos

Exemplo #1 Exemplo da função resourcebundle_get_error_message()

    <?php
    $r = resourcebundle_create( 'es', "/usr/share/data/myapp");
    echo $r['somestring'];
    if(intl_is_failure(resourcebundle_get_error_code($r))) {
        report_error("Bundle error: ".resourcebundle_get_error_message($r));
    }
    ?>

Exemplo #2 Exemplo orientado à objeto

    <?php
    $r = new ResourceBundle( 'es', "/usr/share/data/myapp");
    echo $r['somestring'];
    if(intl_is_failure(ResourceBundle::getErrorCode($r))) {
        report_error("Bundle error: ".ResourceBundle::getErrorMessage($r));
    }
    ?>

### Veja Também

- resourcebundle_get_error_code() - Obtém o código do último erro gerado pelo pacote.
- intl_get_error_code() - Obtém o último código de erro
- intl_is_failure() - Verifica se o código de erro fornecido indica falha

# ResourceBundle::getLocales

# resourcebundle_locales

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::getLocales -- resourcebundle_locales — Obtém as localidades suportadas

### Descrição

Estilo orientado a objetos

public static function ResourceBundle::getLocales(string `$bundle`): array|false

Estilo procedural

function resourcebundle_locales(string `$bundle`): array|false

Obtém as localidades disponíveis a partir do pacote informado.

### Parâmetros

`bundle`

  Caminho do ResourceBundle de onde se obterão as localidades disponíveis, ou uma string vazia para a lista padrão de localidades.

### Valor Retornado

Retorna a lista de localidades suportadas pelo pacote, ou `false` em caso de erros.

### Exemplos

Exemplo #1 Exemplo da função resourcebundle_locales()

    <?php
    $bundle = "/user/share/data/myapp";
    echo join(PHP_EOL, resourcebundle_locales($bundle));
    ?>

O exemplo acima produzirá algo semelhante a:

    es
    root

Exemplo #2 Exemplo orientado à objetos

    <?php
    $bundle = "/usr/share/data/myapp";
    $r = new ResourceBundle( 'es', $bundle);
    echo join("\n", $r->getLocales($bundle));
    ?>

O exemplo acima produzirá algo semelhante a:

    es
    root

### Veja Também

- resourcebundle_get() - Obtém os dados do pacote

## Índice

- ResourceBundle::count — Obtém o número de elementos no pacote
- ResourceBundle::create — Cria um pacote de recursos
- ResourceBundle::get — Obtém os dados do pacote
- ResourceBundle::getErrorCode — Obtém o código do último erro gerado pelo pacote.
- ResourceBundle::getErrorMessage — Obtém a última mensagem de erro gerada pelo pacote
- ResourceBundle::getLocales — Obtém as localidades suportadas

# A classe Spoofchecker

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

## Introdução

Esta classe é fornecida porque o Unicode contém um grande número de caractares e incorpora sistemas variados de escrita de todo o mundo e seu uso incorreto pode expor programas ou sistemas a possíveis ataques à segurança usando similaridade de caracteres.

Os métodos fornecidos permitem verificar se uma string individual pode ser uma tentativa de confundir o leitor (`spoof detection`), como em "pаypаl" escrito com caracteres cirílicos 'а'.

## Resumo da classe

class Spoofchecker {
/* Constantes */
public const int SINGLE_SCRIPT_CONFUSABLE;
public const int MIXED_SCRIPT_CONFUSABLE;
public const int WHOLE_SCRIPT_CONFUSABLE;
public const int ANY_CASE;
public const int SINGLE_SCRIPT;
public const int INVISIBLE;
public const int CHAR_LIMIT;
public const int ASCII;
public const int HIGHLY_RESTRICTIVE;
public const int MODERATELY_RESTRICTIVE;
public const int MINIMALLY_RESTRICTIVE;
public const int UNRESTRICTIVE;
public const int SINGLE_SCRIPT_RESTRICTIVE;
public const int MIXED_NUMBERS;
public const int HIDDEN_OVERLAY;
public const int IGNORE_SPACE;
public const int CASE_INSENSITIVE;
public const int ADD_CASE_MAPPINGS;
public const int SIMPLE_CASE_INSENSITIVE;
/* Métodos */
public function __construct()
public function areConfusable(string `$string1`, string `$string2`, int `&$errorCode` = `null`): bool
public function isSuspicious(string `$string`, int `&$errorCode` = `null`): bool
public function setAllowedChars(string `$pattern`, int `$patternOptions` = 0): void
public function setAllowedLocales(string `$locales`): void
public function setChecks(int `$checks`): void
public function setRestrictionLevel(int `$level`): void
}

## Constantes predefinidas

`Spoofchecker::SINGLE_SCRIPT_CONFUSABLE` int

`Spoofchecker::MIXED_SCRIPT_CONFUSABLE` int

`Spoofchecker::WHOLE_SCRIPT_CONFUSABLE` int

`Spoofchecker::ANY_CASE` int

`Spoofchecker::SINGLE_SCRIPT` int

`Spoofchecker::INVISIBLE` int

`Spoofchecker::CHAR_LIMIT` int

`Spoofchecker::ASCII` int

`Spoofchecker::HIGHLY_RESTRICTIVE` int

`Spoofchecker::MODERATELY_RESTRICTIVE` int

`Spoofchecker::MINIMALLY_RESTRICTIVE` int

`Spoofchecker::UNRESTRICTIVE` int

`Spoofchecker::SINGLE_SCRIPT_RESTRICTIVE` int

`Spoofchecker::MIXED_NUMBERS` int

`Spoofchecker::HIDDEN_OVERLAY` int

`Spoofchecker::IGNORE_SPACE` int

`Spoofchecker::CASE_INSENSITIVE` int
  Habilita correspondência insensível a maiúsculas/minúsculas
`Spoofchecker::ADD_CASE_MAPPINGS` int

  Adiciona todos os mapeamentos de maiúsculas/minúsculas para cada elemento no conjunto

`Spoofchecker::SIMPLE_CASE_INSENSITIVE` int
  Habilita correspondência insensível a maiúsculas/minúsculas

## Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Adicionadas as constantes `Spoofchecker::IGNORE_SPACE`, `Spoofchecker::CASE_INSENSITIVE`, `Spoofchecker::ADD_CASE_MAPPINGS` e `Spoofchecker::SIMPLE_CASE_INSENSITIVE`.
8.4.0 | As constantes de classe agora são tipadas.
7.3.0 | Constantes de classe usadas por Spoofchecker::setRestrictionLevel() como `Spoofchecker::ASCII`, `Spoofchecker::HIGHLY_RESTRICTIVE`, `Spoofchecker::MODERATELY_RESTRICTIVE`, `Spoofchecker::MINIMALLY_RESTRICTIVE`, `Spoofchecker::UNRESTRICTIVE`, `Spoofchecker::SINGLE_SCRIPT_RESTRICTIVE` foram adicionadas.

# Spoofchecker::areConfusable

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::areConfusable — Verifica se as strings fornecidas podem ser confundidas

### Descrição

public function Spoofchecker::areConfusable(string `$string1`, string `$string2`, int `&$errorCode` = `null`): bool

Verifica se duas strings fornecidas podem ser facilmente confundidas.

### Parâmetros

`string1`

  Primeira string a verificar.

`string2`

  Segunda string a verificar.

`errorCode`

  Esta variável é definida por referência para int contendo um erro, se houver algum.

### Valor Retornado

Retorna `true` se as duas strings podem ser confundidas, `false` caso contrário.

### Exemplos

Exemplo #1 Exemplo de Spoofchecker::areConfusable()

    <?php
    $checker = new Spoofchecker();

    $checker->areConfusable('google.com', 'goog1e.com'); // verdadeiro
    // L minúsculo pode ser confundido com o número 1

    $checker->areConfusable('google.com', 'g00g1e.com'); // falso
    // Zero (0) não é facilmente confundido com a letra "o" minúscula

# Spoofchecker::__construct

(No version information available, might only be in Git)

Spoofchecker::__construct — Construtor

### Descrição

public function Spoofchecker::__construct()

Cria uma nova instância de Spoofchecker.

### Parâmetros

Esta função não possui parâmetros.

# Spoofchecker::isSuspicious

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::isSuspicious — Verifica se um texto fornecido contém algum caractere suspeito

### Descrição

public function Spoofchecker::isSuspicious(string `$string`, int `&$errorCode` = `null`): bool

Verifica se uma string contém algum caractere suspeito como letras que são quase idênticas visualmente, mas são caracteres Unicode de conjuntos diferentes.

### Parâmetros

`string`

  String a ser testada.

`errorCode`

  Esta variável é definida por referência para int contendo um erro, se houver algum.

### Valor Retornado

Retorna `true` se houver caracteres suspeitos, `false` caso contrário.

### Exemplos

Exemplo #1 Exemplo de Spoofchecker::isSuspicious()

    <?php
    $checker = new Spoofchecker();

    $checker->isSuspicious('google.com'); // FALSO: apenas caracteres ASCII

    $checker->isSuspicious('Рaypal.com'); // VERDADEIRO
    // A primeira letra é do alfabeto cirílico, e não um "P" latino

# Spoofchecker::setAllowedChars

(PHP 8 >= 8.4.0)

Spoofchecker::setAllowedChars — Define o conjunto de caracteres permitidos ao executar verificações

### Descrição

public function Spoofchecker::setAllowedChars(string `$pattern`, int `$patternOptions` = 0): void

Restringe os caracteres considerados aceitáveis ​​por verificações subsequentes ao conjunto descrito por `pattern`. Qualquer caractere fora deste conjunto faz com que Spoofchecker::isSuspicious() reporte um resultado.

### Parâmetros

`pattern`
  Um conjunto de caracteres descrito como um padrão `UnicodeSet`, que é uma classe de caracteres no estilo de expressão regular. Deve começar com `[` e terminar com `]`, por exemplo, `[a-z0-9]`.
`patternOptions`
  Uma máscara de bits que controla como `pattern` é interpretado. Deve ser `0`, ou `Spoofchecker::IGNORE_SPACE` sozinho ou combinado com exatamente um dos seguintes: `Spoofchecker::CASE_INSENSITIVE`, `Spoofchecker::ADD_CASE_MAPPINGS`, ou `Spoofchecker::SIMPLE_CASE_INSENSITIVE`.

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

Lança um ValueError se `pattern` não for um padrão de conjunto de caracteres válido ou se `patternOptions` não for uma combinação válida de opções.

### Exemplos

Exemplo #1 Exemplo de Spoofchecker::setAllowedChars()

    <?php
    $checker = new Spoofchecker();
    $checker->setAllowedChars('[a-z0-9]');

    var_dump($checker->isSuspicious('hello'));
    var_dump($checker->isSuspicious('héllo'));
    ?>

O exemplo acima produzirá:

    bool(false)
    bool(true)

### Veja Também

- Spoofchecker::setAllowedLocales() - Localidades a usar nas verificações executadas
- Spoofchecker::isSuspicious() - Verifica se um texto fornecido contém algum caractere suspeito

# Spoofchecker::setAllowedLocales

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::setAllowedLocales — Localidades a usar nas verificações executadas

### Descrição

public function Spoofchecker::setAllowedLocales(string `$locales`): void

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`locales`

### Valor Retornado

# Spoofchecker::setChecks

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::setChecks — Define as verificações que serão executadas

### Descrição

public function Spoofchecker::setChecks(int `$checks`): void

Define as verificações que serão executadas por SpoofChecker::isSuspicious().

### Parâmetros

`checks`

  As verificações que serão executadas por SpoofChecker::isSuspicious(). Uma máscara de bits das constantes `Spoofchecker::SINGLE_SCRIPT_CONFUSABLE`, `Spoofchecker::MIXED_SCRIPT_CONFUSABLE`, `Spoofchecker::WHOLE_SCRIPT_CONFUSABLE`, `Spoofchecker::ANY_CASE`, `Spoofchecker::SINGLE_SCRIPT`, `Spoofchecker::INVISIBLE`, ou `Spoofchecker::CHAR_LIMIT`. O padrão é realizar todas as verificações a partir da ICU 58; antes desta versão, `Spoofchecker::SINGLE_SCRIPT` era excluída.

### Valor Retornado

Nenhum valor é retornado.

# Spoofchecker::setRestrictionLevel

(PHP 7 >= 7.3.0, PHP 8)

Spoofchecker::setRestrictionLevel — Define o nível de restrição

### Descrição

public function Spoofchecker::setRestrictionLevel(int `$level`): void

Define o nível de restrição de SpoofChecker::isSuspicious().

### Parâmetros

`level`

  O nível de restrição de SpoofChecker::isSuspicious(). Uma das constantes `Spoofchecker::ASCII`, `Spoofchecker::SINGLE_SCRIPT_RESTRICTIVE`, `Spoofchecker::HIGHLY_RESTRICTIVE`, `Spoofchecker::MODERATELY_RESTRICTIVE`, `Spoofchecker::MINIMALLY_RESTRICTIVE` ou `Spoofchecker::UNRESTRICTIVE`. O padrão é `Spoofchecker::HIGHLY_RESTRICTIVE`.

### Valor Retornado

Nenhum valor é retornado.

## Índice

- Spoofchecker::areConfusable — Verifica se as strings fornecidas podem ser confundidas
- Spoofchecker::__construct — Construtor
- Spoofchecker::isSuspicious — Verifica se um texto fornecido contém algum caractere suspeito
- Spoofchecker::setAllowedChars — Define o conjunto de caracteres permitidos ao executar verificações
- Spoofchecker::setAllowedLocales — Localidades a usar nas verificações executadas
- Spoofchecker::setChecks — Define as verificações que serão executadas
- Spoofchecker::setRestrictionLevel — Define o nível de restrição

# A classe Transliterator

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

## Introdução

Transliterator fornece transliteração de strings.

## Resumo da classe

class Transliterator {
/* Constantes */
public const int FORWARD;
public const int REVERSE;
/* Propriedades */
public readonly string $id;
/* Métodos */
final private function __construct()
public static function create(string `$id`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator
public static function createFromRules(string `$rules`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator
public function createInverse(): ?Transliterator
public function getErrorCode(): int
public function getErrorMessage(): string
public static function listIDs(): array|false
public function transliterate(string `$string`, int `$start` = 0, int `$end` = -1): string|false
}

## Propriedades

id

## Constantes predefinidas

`Transliterator::FORWARD` int

`Transliterator::REVERSE` int

## Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | As constantes de classe agora são tipadas.
8.2.0 | A propriedade id agora é somente-leitura.

# Transliterator::__construct

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::__construct — Construtor privado para proibir instanciação

### Descrição

final private function Transliterator::__construct()

Este método não deve ser chamado. Seu único propósito é inibir instanciação com o operador new.

Use os métodos de criação Transliterator::create() ou Transliterator::createFromRules() em seu lugar.

### Parâmetros

Esta função não possui parâmetros.

### Veja Também

- Transliterator::create() - Cria um transliterador
- Transliterator::createFromRules() - Cria um transliterador a partir de regras

# Transliterator::create

# transliterator_create

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::create -- transliterator_create — Cria um transliterador

### Descrição

Estilo orientado a objetos

public static function Transliterator::create(string `$id`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator

Estilo procedural

function transliterator_create(string `$id`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator

Abre um Transliterador por ID.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`id`

  O ID. Uma lista de todos os IDs de transliteradores registrador pode ser obtido usando-se Transliterator::listIDs().

`direction`

  A direção, o padrão é Transliterator::FORWARD. Também pode ser definido para Transliterator::REVERSE.

### Valor Retornado

Retorna um objeto Transliterator em caso de sucesso, ou `null` em caso de falha.

### Veja Também

- Transliterator::getErrorMessage() - Obtém a última mensagem de erro
- Transliterator::__construct() - Construtor privado para proibir instanciação

# Transliterator::createFromRules

# transliterator_create_from_rules

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::createFromRules -- transliterator_create_from_rules — Cria um transliterador a partir de regras

### Descrição

Estilo orientado a objetos

public static function Transliterator::createFromRules(string `$rules`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator

Estilo procedural

function transliterator_create_from_rules(string `$rules`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator

Cria um transliterador a partir de regras.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`rules`

  As regras como definidas na Sintaxe de Regras de Transformação da UTS #35: LDML Unicode.

`direction`

  A direção, o padrão é Transliterator::FORWARD. Também pode ser definido para Transliterator::REVERSE.

### Valor Retornado

Retorna um objeto Transliterator em caso de sucesso, ou `null` em caso de falha.

### Veja Também

- Transliterator::getErrorMessage() - Obtém a última mensagem de erro
- Transliterator::create() - Cria um transliterador

# Transliterator::createInverse

# transliterator_create_inverse

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::createInverse -- transliterator_create_inverse — Cria um transliterador inverso

### Descrição

Estilo orientado a objetos

public function Transliterator::createInverse(): ?Transliterator

Estilo procedural

function transliterator_create_inverse(Transliterator `$transliterator`): ?Transliterator

Abre o transliterador inverso.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um objeto Transliterator em caso de sucesso ou `null` em caso de falha.

### Veja Também

- Transliterator::getErrorMessage() - Obtém a última mensagem de erro
- Transliterator::create() - Cria um transliterador

# Transliterator::getErrorCode

# transliterator_get_error_code

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::getErrorCode -- transliterator_get_error_code — Obtém o último código de erro

### Descrição

Estilo orientado a objetos

public function Transliterator::getErrorCode(): int

Estilo procedural

function transliterator_get_error_code(Transliterator `$transliterator`): int

Obtém o último código de erro para este transliterador.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`transliterator`

### Valor Retornado

O código de erro em caso de sucesso, ou `false` se nenhum existir ou em caso de falha.

### Veja Também

- Transliterator::getErrorMessage() - Obtém a última mensagem de erro
- Transliterator::listIDs() - Obtém IDs de transliteradores

# Transliterator::getErrorMessage

# transliterator_get_error_message

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::getErrorMessage -- transliterator_get_error_message — Obtém a última mensagem de erro

### Descrição

Estilo orientado a objetos

public function Transliterator::getErrorMessage(): string

Estilo procedural

function transliterator_get_error_message(Transliterator `$transliterator`): string

Obtém a última mensagem de erro para este transliterador.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`transliterator`

### Valor Retornado

A mensagem de erro em caso de sucesso, ou `false` se nenhuma existir ou em caso de falha.

### Veja Também

- Transliterator::getErrorCode() - Obtém o último código de erro
- Transliterator::listIDs() - Obtém IDs de transliteradores

# Transliterator::listIDs

# transliterator_list_ids

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::listIDs -- transliterator_list_ids — Obtém IDs de transliteradores

### Descrição

Estilo orientado a objetos

public static function Transliterator::listIDs(): array|false

Estilo procedural

function transliterator_list_ids(): array|false

Retorna um array com os IDs de transliteradores registrados.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array de IDs de transliteradores registrados em caso de sucesso, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Obtendo os IDs de transliteradores registrados

    <?php
    print_r(Transliterator::listIDs());
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => ASCII-Latin
        [1] => Accents-Any
        [2] => Amharic-Latin/BGN
        [3] => Any-Accents
        [4] => Any-Publishing
    ...
        [650] => Any-ps_Latn/BGN
        [651] => Any-tk/BGN
        [652] => Any-ch_FONIPA
        [653] => Any-cs_FONIPA
        [654] => Any-cy_FONIPA
    )

### Veja Também

- Transliterator::getErrorMessage() - Obtém a última mensagem de erro
- Transliterator::transliterate() - Translitera uma string

# Transliterator::transliterate

# transliterator_transliterate

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::transliterate -- transliterator_transliterate — Translitera uma string

### Descrição

Estilo orientado a objetos

public function Transliterator::transliterate(string `$string`, int `$start` = 0, int `$end` = -1): string|false

Estilo procedural

function transliterator_transliterate(
Transliterator|string `$transliterator`,
string `$string`,
int `$start` = 0,
int `$end` = -1
): string|false

Transforma uma string ou parte dela usando um transliterador ICU.

### Parâmetros

`transliterator`

  Na versão procedura, pode ser um objeto Transliterator ou uma string a partir da qual um objeto Transliterator possa ser construído.

`string`

  A string a ser transformada.

`start`

  O índice do início (em unidades de código UTF-16) a partir do qual a string começará a ser transformada, inclusive. A indexação inicia em 0. O texto anterior a este índice será mantido sem alteração.

`end`

  O índice do final (em unidades de código UTF-16) até o qual a string será transformada, exclusive. A indexação inicia em 0. O texto neste índice e posteriores será mantido sem alteração.

### Valor Retornado

A string transformada em caso de sucesso, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Convertendo unidades de código UTF-16 escapados

    <?php
    $s = "\u304A\u65E9\u3046\u3054\u3056\u3044\u307E\u3059";
    echo transliterator_transliterate("Hex-Any/Java", $s), "\n";

    //agora a operação reversa com um caractere suplementar
    $supplChar = html_entity_decode('&#x1D11E;');
    echo mb_strlen($supplChar, "UTF-8"), "\n";
    $encSupplChar = transliterator_transliterate("Any-Hex/Java", $supplChar);
    //mostra duas unidades de código UTF-16 codificadas
    echo $encSupplChar, "\n";
    //e de volta
    echo transliterator_transliterate("Hex-Any/Java", $encSupplChar), "\n";
    ?>

O exemplo acima produzirá algo semelhante a:

    お早うございます
    1
    \uD834\uDD1E
    𝄞

### Veja Também

- Transliterator::getErrorMessage() - Obtém a última mensagem de erro
- Transliterator::__construct() - Construtor privado para proibir instanciação

## Índice

- Transliterator::__construct — Construtor privado para proibir instanciação
- Transliterator::create — Cria um transliterador
- Transliterator::createFromRules — Cria um transliterador a partir de regras
- Transliterator::createInverse — Cria um transliterador inverso
- Transliterator::getErrorCode — Obtém o último código de erro
- Transliterator::getErrorMessage — Obtém a última mensagem de erro
- Transliterator::listIDs — Obtém IDs de transliteradores
- Transliterator::transliterate — Translitera uma string

# A classe IntlBreakIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introdução

Um “iterador de quebra” é um objeto ICU que expõe métodos para localização de limites no texto (ex.: início/fim de palavras ou frases). A classe IntlBreakIterator do PHP serve como classe base para todos os tipos de iteradores de quebra ICU. Onde existir funcionalidade extra, a extensão Intl pode expor o iterador de quebra ICU com subclasses convenientes, como IntlRuleBasedBreakIterator ou IntlCodePointBreakIterator.

Esta classe implementa a interface IteratorAggregate. Percorrer um IntlBreakIterator produz valores inteiros não negativos que representam as localizações sucessivas dos limites do texto, expressos como contagem de unidades de código (bytes) UTF-8, tomadas do início do texto (que tem a localização `0`). As chaves geradas pelo iterador formam simplesmente a sequência de números naturais `{0, 1, 2, …}`.

## Resumo da classe

class IntlBreakIterator implements IteratorAggregate {
/* Constantes */
public const int DONE;
public const int WORD_NONE;
public const int WORD_NONE_LIMIT;
public const int WORD_NUMBER;
public const int WORD_NUMBER_LIMIT;
public const int WORD_LETTER;
public const int WORD_LETTER_LIMIT;
public const int WORD_KANA;
public const int WORD_KANA_LIMIT;
public const int WORD_IDEO;
public const int WORD_IDEO_LIMIT;
public const int LINE_SOFT;
public const int LINE_SOFT_LIMIT;
public const int LINE_HARD;
public const int LINE_HARD_LIMIT;
public const int SENTENCE_TERM;
public const int SENTENCE_TERM_LIMIT;
public const int SENTENCE_SEP;
public const int SENTENCE_SEP_LIMIT;
/* Métodos */
private function __construct()
public static function createCharacterInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function createCodePointInstance(): IntlCodePointBreakIterator
public static function createLineInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function createSentenceInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function createTitleInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function createWordInstance(?string `$locale` = `null`): ?IntlBreakIterator
public function current(): int
public function first(): int
public function following(int `$offset`): int
public function getErrorCode(): int
public function getErrorMessage(): string
public function getLocale(int `$type`): string|false
public function getPartsIterator(string `$type` = `IntlPartsIterator::KEY_SEQUENTIAL`): IntlPartsIterator
public function getText(): ?string
public function isBoundary(int `$offset`): bool
public function last(): int
public function next(?int `$offset` = `null`): int
public function preceding(int `$offset`): int
public function previous(): int
public function setText(string `$text`): bool
}

## Constantes predefinidas

`IntlBreakIterator::DONE` int

`IntlBreakIterator::WORD_NONE` int

`IntlBreakIterator::WORD_NONE_LIMIT` int

`IntlBreakIterator::WORD_NUMBER` int

`IntlBreakIterator::WORD_NUMBER_LIMIT` int

`IntlBreakIterator::WORD_LETTER` int

`IntlBreakIterator::WORD_LETTER_LIMIT` int

`IntlBreakIterator::WORD_KANA` int

`IntlBreakIterator::WORD_KANA_LIMIT` int

`IntlBreakIterator::WORD_IDEO` int

`IntlBreakIterator::WORD_IDEO_LIMIT` int

`IntlBreakIterator::LINE_SOFT` int

`IntlBreakIterator::LINE_SOFT_LIMIT` int

`IntlBreakIterator::LINE_HARD` int

`IntlBreakIterator::LINE_HARD_LIMIT` int

`IntlBreakIterator::SENTENCE_TERM` int

`IntlBreakIterator::SENTENCE_TERM_LIMIT` int

`IntlBreakIterator::SENTENCE_SEP` int

`IntlBreakIterator::SENTENCE_SEP_LIMIT` int

## Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | As constantes de classe agora são tipadas.
8.0.0 | IntlBreakIterator agora implementa IteratorAggregate. Anteriormente, Traversable era implementado.

# IntlBreakIterator::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::__construct — Construtor privado para não permitir instanciação

### Descrição

private function IntlBreakIterator::__construct()

Instâncias de IntlBreakIterator devem ser criadas usando um dos métodos estáticos de fabricação.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

### Veja Também

- IntlBreakIterator::createCharacterInstance() - Cria um iterador de quebra para limites de sequências de combinação de caracteres
- IntlBreakIterator::createCodePointInstance() - Cria um iterador de quebra para limites de pontos de código
- IntlBreakIterator::createLineInstance() - Cria um iterador de quebra para quebras de linha logicamente possíveis
- IntlBreakIterator::createSentenceInstance() - Cria um iterador de quebra para separação de sentenças
- IntlBreakIterator::createTitleInstance() - Cria um iterador para quebras de letras de título
- IntlBreakIterator::createWordInstance() - Cria um iterador de quebra para separação de palavras

# IntlBreakIterator::createCharacterInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createCharacterInstance — Cria um iterador de quebra para limites de sequências de combinação de caracteres

### Descrição

public static function IntlBreakIterator::createCharacterInstance(?string `$locale` = `null`): ?IntlBreakIterator

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`locale`

### Valor Retornado

# IntlBreakIterator::createCodePointInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createCodePointInstance — Cria um iterador de quebra para limites de pontos de código

### Descrição

public static function IntlBreakIterator::createCodePointInstance(): IntlCodePointBreakIterator

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# IntlBreakIterator::createLineInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createLineInstance — Cria um iterador de quebra para quebras de linha logicamente possíveis

### Descrição

public static function IntlBreakIterator::createLineInstance(?string `$locale` = `null`): ?IntlBreakIterator

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`locale`

### Valor Retornado

# IntlBreakIterator::createSentenceInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createSentenceInstance — Cria um iterador de quebra para separação de sentenças

### Descrição

public static function IntlBreakIterator::createSentenceInstance(?string `$locale` = `null`): ?IntlBreakIterator

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`locale`

### Valor Retornado

# IntlBreakIterator::createTitleInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createTitleInstance — Cria um iterador para quebras de letras de título

### Descrição

public static function IntlBreakIterator::createTitleInstance(?string `$locale` = `null`): ?IntlBreakIterator

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`locale`

### Valor Retornado

# IntlBreakIterator::createWordInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createWordInstance — Cria um iterador de quebra para separação de palavras

### Descrição

public static function IntlBreakIterator::createWordInstance(?string `$locale` = `null`): ?IntlBreakIterator

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`locale`

### Valor Retornado

# IntlBreakIterator::current

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::current — Obtém o índice da posição atual

### Descrição

public function IntlBreakIterator::current(): int

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# IntlBreakIterator::first

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::first — Define a posição para o primeiro caractere no texto

### Descrição

public function IntlBreakIterator::first(): int

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# IntlBreakIterator::following

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::following — Avança o iterador para o primeiro limite após o deslocamento especificado

### Descrição

public function IntlBreakIterator::following(int `$offset`): int

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`offset`

### Valor Retornado

# IntlBreakIterator::getErrorCode

# intl_get_error_code

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getErrorCode -- intl_get_error_code — Obtém o último código de erro no objeto

### Descrição

Estilo orientado a objetos (método):

public function IntlBreakIterator::getErrorCode(): int

Estilo procedural:

function intl_get_error_code(): int

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# IntlBreakIterator::getErrorMessage

# intl_get_error_message

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getErrorMessage -- intl_get_error_message — Obtém a última mensagem de erro no objeto

### Descrição

Estilo orientado a objetos (método):

public function IntlBreakIterator::getErrorMessage(): string

Estilo procedural:

function intl_get_error_message(): string

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# IntlBreakIterator::getLocale

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getLocale — Obtém a localidade associada com o objeto

### Descrição

public function IntlBreakIterator::getLocale(int `$type`): string|false

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`type`

### Valor Retornado

# IntlBreakIterator::getPartsIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getPartsIterator — Cria um iterador para navegar por fragmentos entre limites

### Descrição

public function IntlBreakIterator::getPartsIterator(string `$type` = `IntlPartsIterator::KEY_SEQUENTIAL`): IntlPartsIterator

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`type`

  Tipo de chave, opcional. Os valores possíveis são:

  - `IntlPartsIterator::KEY_SEQUENTIAL` - O padrão. Inteiros sequenciais usados como chave.
  - `IntlPartsIterator::KEY_LEFT` - Deslocamento em bytes à esquerda da parte atual usado como chave.
  - `IntlPartsIterator::KEY_RIGHT` - Deslocamento em bytes à direita da parte atual usado como chave.

### Valor Retornado

# IntlBreakIterator::getText

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getText — Obtém o texto sendo percorrido

### Descrição

public function IntlBreakIterator::getText(): ?string

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# IntlBreakIterator::isBoundary

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::isBoundary — Indica se uma posição é um posição de limite

### Descrição

public function IntlBreakIterator::isBoundary(int `$offset`): bool

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`offset`

### Valor Retornado

# IntlBreakIterator::last

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::last — Define a posição do iterador para um índice além do último caractere

### Descrição

public function IntlBreakIterator::last(): int

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# IntlBreakIterator::next

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::next — Avança o iterador para o próximo limite

### Descrição

public function IntlBreakIterator::next(?int `$offset` = `null`): int

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`offset`

### Valor Retornado

# IntlBreakIterator::preceding

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::preceding — Define a posição do iterador para o primeiro limite depois de um deslocamento

### Descrição

public function IntlBreakIterator::preceding(int `$offset`): int

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`offset`

### Valor Retornado

# IntlBreakIterator::previous

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::previous — Define a posição do iterador para o limite imediatamente anterior ao atual

### Descrição

public function IntlBreakIterator::previous(): int

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# IntlBreakIterator::setText

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::setText — Define o texto a ser percorrido

### Descrição

public function IntlBreakIterator::setText(string `$text`): bool

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`text`

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Este método agora retorna `false` em caso de falha; anteriormente retornava `null`.

## Índice

- IntlBreakIterator::__construct — Construtor privado para não permitir instanciação
- IntlBreakIterator::createCharacterInstance — Cria um iterador de quebra para limites de sequências de combinação de caracteres
- IntlBreakIterator::createCodePointInstance — Cria um iterador de quebra para limites de pontos de código
- IntlBreakIterator::createLineInstance — Cria um iterador de quebra para quebras de linha logicamente possíveis
- IntlBreakIterator::createSentenceInstance — Cria um iterador de quebra para separação de sentenças
- IntlBreakIterator::createTitleInstance — Cria um iterador para quebras de letras de título
- IntlBreakIterator::createWordInstance — Cria um iterador de quebra para separação de palavras
- IntlBreakIterator::current — Obtém o índice da posição atual
- IntlBreakIterator::first — Define a posição para o primeiro caractere no texto
- IntlBreakIterator::following — Avança o iterador para o primeiro limite após o deslocamento especificado
- IntlBreakIterator::getErrorCode — Obtém o último código de erro no objeto
- IntlBreakIterator::getErrorMessage — Obtém a última mensagem de erro no objeto
- IntlBreakIterator::getLocale — Obtém a localidade associada com o objeto
- IntlBreakIterator::getPartsIterator — Cria um iterador para navegar por fragmentos entre limites
- IntlBreakIterator::getText — Obtém o texto sendo percorrido
- IntlBreakIterator::isBoundary — Indica se uma posição é um posição de limite
- IntlBreakIterator::last — Define a posição do iterador para um índice além do último caractere
- IntlBreakIterator::next — Avança o iterador para o próximo limite
- IntlBreakIterator::preceding — Define a posição do iterador para o primeiro limite depois de um deslocamento
- IntlBreakIterator::previous — Define a posição do iterador para o limite imediatamente anterior ao atual
- IntlBreakIterator::setText — Define o texto a ser percorrido

# A classe IntlRuleBasedBreakIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introdução

Uma subclasse de IntlBreakIterator que faz encapsulamento de iteradores de quebra ICU cujo comportamento é especificado usando-se um conjunto de regras. Este é o tipo mais comum de iteradores de quebra.

Estas regras estão descritas no » Guia do Usuário de Análise de Limites ICU.

## Resumo da classe

class IntlRuleBasedBreakIterator extends IntlBreakIterator {
/* Constantes herdadas */
public const int IntlBreakIterator::DONE;
public const int IntlBreakIterator::WORD_NONE;
public const int IntlBreakIterator::WORD_NONE_LIMIT;
public const int IntlBreakIterator::WORD_NUMBER;
public const int IntlBreakIterator::WORD_NUMBER_LIMIT;
public const int IntlBreakIterator::WORD_LETTER;
public const int IntlBreakIterator::WORD_LETTER_LIMIT;
public const int IntlBreakIterator::WORD_KANA;
public const int IntlBreakIterator::WORD_KANA_LIMIT;
public const int IntlBreakIterator::WORD_IDEO;
public const int IntlBreakIterator::WORD_IDEO_LIMIT;
public const int IntlBreakIterator::LINE_SOFT;
public const int IntlBreakIterator::LINE_SOFT_LIMIT;
public const int IntlBreakIterator::LINE_HARD;
public const int IntlBreakIterator::LINE_HARD_LIMIT;
public const int IntlBreakIterator::SENTENCE_TERM;
public const int IntlBreakIterator::SENTENCE_TERM_LIMIT;
public const int IntlBreakIterator::SENTENCE_SEP;
public const int IntlBreakIterator::SENTENCE_SEP_LIMIT;
/* Métodos */
public function __construct(string `$rules`, bool `$compiled` = `false`)
public function getBinaryRules(): string|false
public function getRules(): string|false
public function getRuleStatus(): int
public function getRuleStatusVec(): array|false
/* Métodos herdados */
public static function IntlBreakIterator::createCharacterInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createCodePointInstance(): IntlCodePointBreakIterator
public static function IntlBreakIterator::createLineInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createSentenceInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createTitleInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createWordInstance(?string `$locale` = `null`): ?IntlBreakIterator
public function IntlBreakIterator::current(): int
public function IntlBreakIterator::first(): int
public function IntlBreakIterator::following(int `$offset`): int
public function IntlBreakIterator::getErrorCode(): int
public function IntlBreakIterator::getErrorMessage(): string
public function IntlBreakIterator::getLocale(int `$type`): string|false
public function IntlBreakIterator::getPartsIterator(string `$type` = `IntlPartsIterator::KEY_SEQUENTIAL`): IntlPartsIterator
public function IntlBreakIterator::getText(): ?string
public function IntlBreakIterator::isBoundary(int `$offset`): bool
public function IntlBreakIterator::last(): int
public function IntlBreakIterator::next(?int `$offset` = `null`): int
public function IntlBreakIterator::preceding(int `$offset`): int
public function IntlBreakIterator::previous(): int
public function IntlBreakIterator::setText(string `$text`): bool
}

# IntlRuleBasedBreakIterator::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::__construct — Cria um iterador a partir de um conjunto de regras

### Descrição

public function IntlRuleBasedBreakIterator::__construct(string `$rules`, bool `$compiled` = `false`)

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`rules`

`compiled`

### Valor Retornado

# IntlRuleBasedBreakIterator::getBinaryRules

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getBinaryRules — Obtém a forma binária de regras compiladas

### Descrição

public function IntlRuleBasedBreakIterator::getBinaryRules(): string|false

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# IntlRuleBasedBreakIterator::getRules

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getRules — Obtém o conjunto de regras usado para criar este objeto

### Descrição

public function IntlRuleBasedBreakIterator::getRules(): string|false

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# IntlRuleBasedBreakIterator::getRuleStatus

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getRuleStatus — Obtém o maior valor de status a partir de regras de quebras que determinaram a posição de quebra atual

### Descrição

public function IntlRuleBasedBreakIterator::getRuleStatus(): int

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# IntlRuleBasedBreakIterator::getRuleStatusVec

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getRuleStatusVec — Obtém os valores de status das regras de quebra que determinaram a posição de quebra atual

### Descrição

public function IntlRuleBasedBreakIterator::getRuleStatusVec(): array|false

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

## Índice

- IntlRuleBasedBreakIterator::__construct — Cria um iterador a partir de um conjunto de regras
- IntlRuleBasedBreakIterator::getBinaryRules — Obtém a forma binária de regras compiladas
- IntlRuleBasedBreakIterator::getRules — Obtém o conjunto de regras usado para criar este objeto
- IntlRuleBasedBreakIterator::getRuleStatus — Obtém o maior valor de status a partir de regras de quebras que determinaram a posição de quebra atual
- IntlRuleBasedBreakIterator::getRuleStatusVec — Obtém os valores de status das regras de quebra que determinaram a posição de quebra atual

# A classe IntlCodePointBreakIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introdução

Este iterador de quebra identifica os limites entre os pontos de código UTF-8.

## Resumo da classe

class IntlCodePointBreakIterator extends IntlBreakIterator {
/* Constantes herdadas */
public const int IntlBreakIterator::DONE;
public const int IntlBreakIterator::WORD_NONE;
public const int IntlBreakIterator::WORD_NONE_LIMIT;
public const int IntlBreakIterator::WORD_NUMBER;
public const int IntlBreakIterator::WORD_NUMBER_LIMIT;
public const int IntlBreakIterator::WORD_LETTER;
public const int IntlBreakIterator::WORD_LETTER_LIMIT;
public const int IntlBreakIterator::WORD_KANA;
public const int IntlBreakIterator::WORD_KANA_LIMIT;
public const int IntlBreakIterator::WORD_IDEO;
public const int IntlBreakIterator::WORD_IDEO_LIMIT;
public const int IntlBreakIterator::LINE_SOFT;
public const int IntlBreakIterator::LINE_SOFT_LIMIT;
public const int IntlBreakIterator::LINE_HARD;
public const int IntlBreakIterator::LINE_HARD_LIMIT;
public const int IntlBreakIterator::SENTENCE_TERM;
public const int IntlBreakIterator::SENTENCE_TERM_LIMIT;
public const int IntlBreakIterator::SENTENCE_SEP;
public const int IntlBreakIterator::SENTENCE_SEP_LIMIT;
/* Métodos */
public function getLastCodePoint(): int
/* Métodos herdados */
public static function IntlBreakIterator::createCharacterInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createCodePointInstance(): IntlCodePointBreakIterator
public static function IntlBreakIterator::createLineInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createSentenceInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createTitleInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createWordInstance(?string `$locale` = `null`): ?IntlBreakIterator
public function IntlBreakIterator::current(): int
public function IntlBreakIterator::first(): int
public function IntlBreakIterator::following(int `$offset`): int
public function IntlBreakIterator::getErrorCode(): int
public function IntlBreakIterator::getErrorMessage(): string
public function IntlBreakIterator::getLocale(int `$type`): string|false
public function IntlBreakIterator::getPartsIterator(string `$type` = `IntlPartsIterator::KEY_SEQUENTIAL`): IntlPartsIterator
public function IntlBreakIterator::getText(): ?string
public function IntlBreakIterator::isBoundary(int `$offset`): bool
public function IntlBreakIterator::last(): int
public function IntlBreakIterator::next(?int `$offset` = `null`): int
public function IntlBreakIterator::preceding(int `$offset`): int
public function IntlBreakIterator::previous(): int
public function IntlBreakIterator::setText(string `$text`): bool
}

# IntlCodePointBreakIterator::getLastCodePoint

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlCodePointBreakIterator::getLastCodePoint — Obtém o último code point passado após avançar ou retroceder o iterador

### Descrição

public function IntlCodePointBreakIterator::getLastCodePoint(): int

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

## Índice

- IntlCodePointBreakIterator::getLastCodePoint — Obtém o último code point passado após avançar ou retroceder o iterador

# A classe IntlDatePatternGenerator

(PHP 8 >= 8.1.0)

## Introdução

Gera strings de padrão de formatação para data e/ou horário dependentes de localidade, adequadas para uso em IntlDateFormatter.

## Resumo da classe

class IntlDatePatternGenerator {
/* Métodos */
public function __construct(?string `$locale` = `null`)
public static function create(?string `$locale` = `null`): ?IntlDatePatternGenerator
public function getBestPattern(string `$skeleton`): string|false
}

# IntlDatePatternGenerator::create

# IntlDatePatternGenerator::__construct

(PHP 8 >= 8.1.0)

IntlDatePatternGenerator::create -- IntlDatePatternGenerator::__construct — Cria uma nova instância de IntlDatePatternGenerator

### Descrição

public static function IntlDatePatternGenerator::create(?string `$locale` = `null`): ?IntlDatePatternGenerator
public function IntlDatePatternGenerator::__construct(?string `$locale` = `null`)

Cria uma nova instância de IntlDatePatternGenerator.

### Parâmetros

`locale`

  A localidade. Se `null` for passado, usa a configuração ini intl.default_locale.

### Valor Retornado

Retorna uma instância de IntlDatePatternGenerator em caso de sucesso ou `null` em caso de falha.

# IntlDatePatternGenerator::getBestPattern

(PHP 8 >= 8.1.0)

IntlDatePatternGenerator::getBestPattern — Determina o formato de data/horário mais adequado

### Descrição

public function IntlDatePatternGenerator::getBestPattern(string `$skeleton`): string|false

Determina que formato de data/horário é mais adequado para uma localidade em particular.

### Parâmetros

`skeleton`

  O esqueleto.

### Valor Retornado

Retorna um padrão ICU de data/horário, aceito por IntlDateFormatter em caso de sucesso, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de IntlDatePatternGenerator::getBestPattern()

    <?php

    $skeleton = 'YYYYMMdd';
    $today = \DateTimeImmutable::createFromFormat('Y-m-d', '2021-04-24');

    $patternGenerator = new \IntlDatePatternGenerator('de_DE');
    $pattern = $patternGenerator->getBestPattern($skeleton);
    echo 'de: ', \IntlDateFormatter::formatObject($today, $pattern, 'de_DE'), "\n";

    $patternGenerator = new \IntlDatePatternGenerator('en_US');
    $pattern = $patternGenerator->getBestPattern($skeleton);
    echo 'en: ', \IntlDateFormatter::formatObject($today, $pattern, 'en_US');
    ?>

O exemplo acima produzirá:

    de: 24.04.2021
    en: 04/24/2021

## Índice

- IntlDatePatternGenerator::create — Cria uma nova instância de IntlDatePatternGenerator
- IntlDatePatternGenerator::getBestPattern — Determina o formato de data/horário mais adequado

# A classe IntlPartsIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introdução

Objetos desta classe podem ser obtidos a partir de objetos IntlBreakIterator. Enquanto os iteradores de quebra fornecem uma sequência de posições de limites quando iterados, objetos IntlPartsIterator fornecem, por conveniência, os fragmentos de texto compreendidos entre dois limites consecutivos.

As chaves podem representar o deslocamento do limite esquerdo, do limite direito, ou podem ser apenas a sequência de inteiros não negativos. Consulte IntlBreakIterator::getPartsIterator().

## Resumo da classe

class IntlPartsIterator extends IntlIterator {
/* Constantes */
public const int KEY_SEQUENTIAL;
public const int KEY_LEFT;
public const int KEY_RIGHT;
/* Métodos */
public function getBreakIterator(): IntlBreakIterator
/* Métodos herdados */
public function IntlIterator::current(): mixed
public function IntlIterator::key(): mixed
public function IntlIterator::next(): void
public function IntlIterator::rewind(): void
public function IntlIterator::valid(): bool
}

## Constantes predefinidas

`IntlPartsIterator::KEY_SEQUENTIAL` int

`IntlPartsIterator::KEY_LEFT` int

`IntlPartsIterator::KEY_RIGHT` int

## Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | As constantes de classe agora são tipadas.

# IntlPartsIterator::getBreakIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlPartsIterator::getBreakIterator — Obtém o IntlBreakIterator que é utilizado pelo iterador

### Descrição

public function IntlPartsIterator::getBreakIterator(): IntlBreakIterator

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

## Índice

- IntlPartsIterator::getBreakIterator — Obtém o IntlBreakIterator que é utilizado pelo iterador

# A classe UConverter

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

## Introdução

## Resumo da classe

class UConverter {
/* Constantes */
public const int REASON_UNASSIGNED;
public const int REASON_ILLEGAL;
public const int REASON_IRREGULAR;
public const int REASON_RESET;
public const int REASON_CLOSE;
public const int REASON_CLONE;
public const int UNSUPPORTED_CONVERTER;
public const int SBCS;
public const int DBCS;
public const int MBCS;
public const int LATIN_1;
public const int UTF8;
public const int UTF16_BigEndian;
public const int UTF16_LittleEndian;
public const int UTF32_BigEndian;
public const int UTF32_LittleEndian;
public const int EBCDIC_STATEFUL;
public const int ISO_2022;
public const int LMBCS_1;
public const int LMBCS_2;
public const int LMBCS_3;
public const int LMBCS_4;
public const int LMBCS_5;
public const int LMBCS_6;
public const int LMBCS_8;
public const int LMBCS_11;
public const int LMBCS_16;
public const int LMBCS_17;
public const int LMBCS_18;
public const int LMBCS_19;
public const int LMBCS_LAST;
public const int HZ;
public const int SCSU;
public const int ISCII;
public const int US_ASCII;
public const int UTF7;
public const int BOCU1;
public const int UTF16;
public const int UTF32;
public const int CESU8;
public const int IMAP_MAILBOX;
/* Métodos */
public function __construct(?string `$destination_encoding` = `null`, ?string `$source_encoding` = `null`)
public function convert(string `$str`, bool `$reverse` = `false`): string|false
public function fromUCallback(
int `$reason`,
array `$source`,
int `$codePoint`,
int `&$error`
): string|int|array|null
public static function getAliases(string `$name`): array|false|null
public static function getAvailable(): array
public function getDestinationEncoding(): string|false|null
public function getDestinationType(): int|false|null
public function getErrorCode(): int
public function getErrorMessage(): ?string
public function getSourceEncoding(): string|false|null
public function getSourceType(): int|false|null
public static function getStandards(): ?array
public function getSubstChars(): string|false|null
public static function reasonText(int `$reason`): string
public function setDestinationEncoding(string `$encoding`): bool
public function setSourceEncoding(string `$encoding`): bool
public function setSubstChars(string `$chars`): bool
public function toUCallback(
int `$reason`,
string `$source`,
string `$codeUnits`,
int `&$error`
): string|int|array|null
public static function transcode(
string `$str`,
string `$toEncoding`,
string `$fromEncoding`,
?array `$options` = `null`
): string|false
}

## Constantes predefinidas

`UConverter::REASON_UNASSIGNED` int

`UConverter::REASON_ILLEGAL` int

`UConverter::REASON_IRREGULAR` int

`UConverter::REASON_RESET` int

`UConverter::REASON_CLOSE` int

`UConverter::REASON_CLONE` int

`UConverter::UNSUPPORTED_CONVERTER` int

`UConverter::SBCS` int

`UConverter::DBCS` int

`UConverter::MBCS` int

`UConverter::LATIN_1` int

`UConverter::UTF8` int

`UConverter::UTF16_BigEndian` int

`UConverter::UTF16_LittleEndian` int

`UConverter::UTF32_BigEndian` int

`UConverter::UTF32_LittleEndian` int

`UConverter::EBCDIC_STATEFUL` int

`UConverter::ISO_2022` int

`UConverter::LMBCS_1` int

`UConverter::LMBCS_2` int

`UConverter::LMBCS_3` int

`UConverter::LMBCS_4` int

`UConverter::LMBCS_5` int

`UConverter::LMBCS_6` int

`UConverter::LMBCS_8` int

`UConverter::LMBCS_11` int

`UConverter::LMBCS_16` int

`UConverter::LMBCS_17` int

`UConverter::LMBCS_18` int

`UConverter::LMBCS_19` int

`UConverter::LMBCS_LAST` int

`UConverter::HZ` int

`UConverter::SCSU` int

`UConverter::ISCII` int

`UConverter::US_ASCII` int

`UConverter::UTF7` int

`UConverter::BOCU1` int

`UConverter::UTF16` int

`UConverter::UTF32` int

`UConverter::CESU8` int

`UConverter::IMAP_MAILBOX` int

## Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | As constantes de classe agora são tipadas.

# UConverter::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::__construct — Cria um objeto UConverter

### Descrição

public function UConverter::__construct(?string `$destination_encoding` = `null`, ?string `$source_encoding` = `null`)

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`destination_encoding`

`source_encoding`

### Valor Retornado

# UConverter::convert

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::convert — Converte uma string de um conjunto de caracteres (charset) para outro

### Descrição

public function UConverter::convert(string `$str`, bool `$reverse` = `false`): string|false

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`str`

`reverse`

### Valor Retornado

# UConverter::fromUCallback

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::fromUCallback — Função de retorno de origem padrão

### Descrição

public function UConverter::fromUCallback(
int `$reason`,
array `$source`,
int `$codePoint`,
int `&$error`
): string|int|array|null

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`reason`

`source`

`codePoint`

`error`

### Valor Retornado

# UConverter::getAliases

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getAliases — Obtém o pseudônimo de um nome

### Descrição

public static function UConverter::getAliases(string `$name`): array|false|null

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`name`

### Valor Retornado

# UConverter::getAvailable

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getAvailable — Obtém os nomes canônicos dos conversores disponíveis

### Descrição

public static function UConverter::getAvailable(): array

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# UConverter::getDestinationEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getDestinationEncoding — Obtém a codificação de destino

### Descrição

public function UConverter::getDestinationEncoding(): string|false|null

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# UConverter::getDestinationType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getDestinationType — Obtém o tipo do conversor de destino

### Descrição

public function UConverter::getDestinationType(): int|false|null

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# UConverter::getErrorCode

# intl_get_error_code

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getErrorCode -- intl_get_error_code — Obtém o código do último erro gerado pelo objeto

### Descrição

public function UConverter::getErrorCode(): int

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# UConverter::getErrorMessage

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getErrorMessage — Obtém a mensagem do último erro gerado pelo objeto

### Descrição

public function UConverter::getErrorMessage(): ?string

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# UConverter::getSourceEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getSourceEncoding — Obtém a codificação de origem

### Descrição

public function UConverter::getSourceEncoding(): string|false|null

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# UConverter::getSourceType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getSourceType — Obtém o tipo do conversor de origem

### Descrição

public function UConverter::getSourceType(): int|false|null

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# UConverter::getStandards

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getStandards — Obtém os nomes dos conversores padrão associados

### Descrição

public static function UConverter::getStandards(): ?array

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# UConverter::getSubstChars

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getSubstChars — Obtém os caracteres de substituição

### Descrição

public function UConverter::getSubstChars(): string|false|null

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# UConverter::reasonText

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::reasonText — Obtém uma representação em string da razão da chamada de retorno

### Descrição

public static function UConverter::reasonText(int `$reason`): string

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`reason`

### Valor Retornado

# UConverter::setDestinationEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::setDestinationEncoding — Define a codificação de destino

### Descrição

public function UConverter::setDestinationEncoding(string `$encoding`): bool

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`encoding`

### Valor Retornado

# UConverter::setSourceEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::setSourceEncoding — Define a codificação da origem

### Descrição

public function UConverter::setSourceEncoding(string `$encoding`): bool

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`encoding`

### Valor Retornado

# UConverter::setSubstChars

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::setSubstChars — Define os caracteres de substituição

### Descrição

public function UConverter::setSubstChars(string `$chars`): bool

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`chars`

### Valor Retornado

# UConverter::toUCallback

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::toUCallback — Função de retorno padrão de destino

### Descrição

public function UConverter::toUCallback(
int `$reason`,
string `$source`,
string `$codeUnits`,
int `&$error`
): string|int|array|null

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`reason`

`source`

`codeUnits`

`error`

### Valor Retornado

# UConverter::transcode

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::transcode — Converte uma string de uma codificação de caracteres para outra

### Descrição

public static function UConverter::transcode(
string `$str`,
string `$toEncoding`,
string `$fromEncoding`,
?array `$options` = `null`
): string|false

Converte `str` de `fromEncoding` para `toEncoding`.

### Parâmetros

`str`

  A string a ser convertida.

`toEncoding`

  A codificação desejada do resultado.

`fromEncoding`

  A codificação atual usada para interpretar `str`.

`options`

  Um array opcional, que pode conter as seguintes chaves:

  - `'to_subst'` - o caractere de substituição a ser usado no lugar de qualquer caractere de `str` que não possa ser codificado com `toEncoding`. Se especificado, deve representar um único caractere na codificação de destino.

### Valor Retornado

Retorna a string convertida ou `false` em caso de falha.

### Exemplos

Exemplo #1 Convertendo de UTF-8 para UTF-16 e vice-versa

    <?php
    $utf8_string = "\x5A\x6F\xC3\xAB"; // 'Zoë' em UTF-8
    $utf16_string = UConverter::transcode($utf8_string, 'UTF-16BE', 'UTF-8');
    echo bin2hex($utf16_string), "\n";

    $new_utf8_string = UConverter::transcode($utf16_string, 'UTF-8', 'UTF-16BE');
    echo bin2hex($new_utf8_string), "\n";
    ?>

O exemplo acima produzirá:

    005a006f00eb
    5a6fc3ab

Exemplo #2 Caracteres inválidos na entrada

Se a string de entrada contiver uma sequência de bytes que não seja válida na codificação especificada por `fromEncoding`, eles são substituídos pelo código do ponto em Unicode U+FFFD (Caractere de Substituição) antes da conversão para `toEncoding`.

    <?php
    $invalid_utf8_string = "\xC3"; // sequência UTF-8 multi-bytes incompleta
    $utf16_string = UConverter::transcode($invalid_utf8_string, 'UTF-16BE', 'UTF-8');
    echo bin2hex($utf16_string), "\n";
    ?>

O exemplo acima produzirá:

    fffd

Exemplo #3 Caracteres que não podem ser codificados

Se a string de entrada contiver caracteres que não possam ser representados na codificação especificada por `toEncoding`, eles são substituídos por um caractere simples. O caractere padrão a ser usado depende da codificação e pode ser controlado usando a opção `'to_subst'`.

    <?php
    $utf8_string = "\xE2\x82\xAC"; // € (sinal de Euro) não existe na ISO 8859-1

    // Substituição padrão na ISO 8859-1 é "\x1A" (Substituto)
    $iso8859_1_string = UConverter::transcode($utf8_string, 'ISO-8859-1', 'UTF-8');
    echo bin2hex($iso8859_1_string), "\n";

    // Especifica uma substituição por '?' ("\x3F") alternativamente
    $iso8859_1_string = UConverter::transcode(
        $utf8_string, 'ISO-8859-1', 'UTF-8', ['to_subst' => '?']
    );
    echo bin2hex($iso8859_1_string), "\n";

    // Como a ISO 8859-1 não consegue mapear U+FFFD, a entrada inválida também é substituída por to_subst
    $invalid_utf8_string = "\xC3"; // sequência UTF-8 multi-bytes incompleta
    $iso8859_1_string = UConverter::transcode(
        $invalid_utf8_string, 'ISO-8859-1', 'UTF-8', ['to_subst' => '?']
    );
    echo bin2hex($iso8859_1_string), "\n";
    ?>

O exemplo acima produzirá:

    1a
    3f
    3f

### Veja Também

- mb_convert_encoding() - Converte uma string de uma codificação de caracteres para outra
- iconv() - Converte uma string de uma codificação de caracteres para outra

## Índice

- UConverter::__construct — Cria um objeto UConverter
- UConverter::convert — Converte uma string de um conjunto de caracteres (charset) para outro
- UConverter::fromUCallback — Função de retorno de origem padrão
- UConverter::getAliases — Obtém o pseudônimo de um nome
- UConverter::getAvailable — Obtém os nomes canônicos dos conversores disponíveis
- UConverter::getDestinationEncoding — Obtém a codificação de destino
- UConverter::getDestinationType — Obtém o tipo do conversor de destino
- UConverter::getErrorCode — Obtém o código do último erro gerado pelo objeto
- UConverter::getErrorMessage — Obtém a mensagem do último erro gerado pelo objeto
- UConverter::getSourceEncoding — Obtém a codificação de origem
- UConverter::getSourceType — Obtém o tipo do conversor de origem
- UConverter::getStandards — Obtém os nomes dos conversores padrão associados
- UConverter::getSubstChars — Obtém os caracteres de substituição
- UConverter::reasonText — Obtém uma representação em string da razão da chamada de retorno
- UConverter::setDestinationEncoding — Define a codificação de destino
- UConverter::setSourceEncoding — Define a codificação da origem
- UConverter::setSubstChars — Define os caracteres de substituição
- UConverter::toUCallback — Função de retorno padrão de destino
- UConverter::transcode — Converte uma string de uma codificação de caracteres para outra

# Funções de Grapheme

# grapheme_extract

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_extract — Extrai uma sequência de grupos padrão de grafemas de um buffer de texto em UTF-8

### Descrição

Estilo procedural

function grapheme_extract(
string `$haystack`,
int `$size`,
int `$type` = `GRAPHEME_EXTR_COUNT`,
int `$offset` = 0,
int `&$next` = `null`
): string|false

Esta função extrai uma sequência de grupos padrão de grafemas a partir de um buffer de texto codificado em UTF-8.

### Parâmetros

`haystack`

  A string onde a pesquisa será feita.

`size`

  Número máximo de itens - baseado no tipo `type` - a retornar.

`type`

  Define o tipo de unidades referidas pelo parâmetro `size`:

  - GRAPHEME_EXTR_COUNT (padrão) - `size` é o número de grupos padrão de grafemas a extrair.
  - GRAPHEME_EXTR_MAXBYTES - `size` é o número máximo de bytes retornados.
  - GRAPHEME_EXTR_MAXCHARS - `size` é o número máximo de caracteres UTF-8 retornados.
`offset`

  Posição inicial no `haystack` em bytes - se informado, precisa ser zero ou um inteiro positivo que seja menor ou igual ao comprimento de `haystack` em bytes, ou um valor negativo que conta a partir do final de `haystack`. Se `offset` não apontar para o primeiro byte de um caractere UTF-8, a posição de início é movida para o primeiro byte do caractere seguinte.

`next`

  Referência a um valor que será definido para a próxima posição de início. Quando a chamada retornar, esta variável poderá apontar para a primeira posição em bytes após o final da string.

### Valor Retornado

Um string com deslocamento em `offset` e terminando em um limite de grupo padrão de grafema que esteja em conformidade com os parâmetros `size` e `type` especificados, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
7.1.0 | Suporte para `offset` negativo foi adicionado.

### Exemplos

Exemplo #1 Exemplo de grapheme_extract()

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) NFD
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) NFD

    print urlencode(grapheme_extract( $char_a_ring_nfd . $char_o_diaeresis_nfd, 1, GRAPHEME_EXTR_COUNT, 2));

    ?>

O exemplo acima produzirá:

    o%CC%88

### Veja Também

- grapheme_substr() - Retorna parte de uma string
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_str_split

(PHP 8 >= 8.4.0)

grapheme_str_split — Separa uma string em um array

### Descrição

function grapheme_str_split(string `$string`, int `$length` = 1): array|false

Esta função retorna um array de strings. É uma versão de str_split() com suporte para caracteres de byte de grupos de grafema. Se o parâmetro `length` for especificado, a string é quebrada em pedaços desse comprimento em unidades de grupos de grafema (não em bytes).

### Parâmetros

`string`

  A string a ser separada em grupos de grafemas ou pedaços. `string` precisa ser em UTF-8 válido.

`length`

  Cada elemento do array retornado será composto pelo número de grupos de grafema especificado no parâmetro `length`.

### Valor Retornado

grapheme_str_split() retorna um array de strings, ou `false` em caso de falha.

### Erros/Exceções

Se `length` for menor que `1`, um ValueError será lançado.

### Veja Também

- str_split() - Converte uma string em um array
- mb_str_split() - Dada uma string multibyte, retorna um array de seus caracteres
- » Segmentação de texto Unicode: limites do grupo de grafema

# grapheme_stripos

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_stripos — Encontra a posição (em unidades de grafema) da primeira ocorrência de uma string não sensível a maiúsculas/minúsculas

### Descrição

Estilo procedural

function grapheme_stripos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
string `$locale` = ""
): int|false

Encontra a posição (em unidades de grafema) da primeira ocorrência de uma string não sensível a maiúsculas/minúsculas.

### Parâmetros

`haystack`

  A string onde ocorrerá a pesquisa. Deve ser em UTF-8 válido.

`needle`

  A string a ser procurada. Deve ser em UTF-8 válido.

`offset`

  O parâmetro opcional `offset` permite especificar onde no `haystack` deve-se iniciar a pesquisa, como uma posição em unidades de grafema (não em bytes ou caracteres). Se a posição for negativa, será tratada como relativa ao final da string. A posição retornada ainda será relativa ao início do `haystack` independentemente do valor de `offset`.

`locale`
  Localidade a ser usada.

### Valor Retornado

Retora a posição como um inteiro. Se `needle` não for encontrado, grapheme_stripos() retornará `false`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | O parâmetro opcional `locale` foi adicionado.
7.1.0 | Suporte para `offset` negativo foi adicionado.

### Exemplos

Exemplo #1 Exemplo de grapheme_stripos()

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) NFD
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) NFD
    $char_O_diaeresis_nfd = "O\xCC\x88"; // 'LATIN CAPITAL LETTER O WITH DIAERESIS' (U+00D6) NFD

    print grapheme_stripos( $char_a_ring_nfd . $char_a_ring_nfd . $char_o_diaeresis_nfd, $char_O_diaeresis_nfd);

    ?>

O exemplo acima produzirá:

    2

### Veja Também

- grapheme_stristr() - Retorna parte de uma string a partir da primeira ocorrência de outra string (insensível a maiúsculas/minúsculas) até o final
- grapheme_strpos() - Encontra a posição (em unidades de grafema) da primeira ocorrência de uma string
- grapheme_strripos() - Encontra a posição (em unidades de grafema) da última ocorrência de uma string (insensível a maiúsculas/minúsculas)
- grapheme_strrpos() - Encontra a posição (em unidades de grafema) da última ocorrência de uma string
- grapheme_strstr() - Retorna parte de uma string a partir da primeira ocorrência de outra string até o final
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_stristr

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_stristr — Retorna parte de uma string a partir da primeira ocorrência de outra string (insensível a maiúsculas/minúsculas) até o final

### Descrição

Estilo procedural

function grapheme_stristr(
string `$haystack`,
string `$needle`,
bool `$beforeNeedle` = `false`,
string `$locale` = ""
): string|false

Retorna parte da string `haystack` iniciando da primeira ocorrência de uma outra string (insensível a maiúsculas/minúsculas) até o final de `haystack`.

### Parâmetros

`haystack`

  A string de entrada. Deve ser em UTF-8 válido.

`needle`

  A string a ser procurada. Deve ser em UTF-8 válido.

`beforeNeedle`

  Caso seja `true`, grapheme_stristr() retorna a parte da string `haystack` antes da primeira ocorrência da string procurada (excluindo `needle`).

`locale`
  Localidade a ser usada.

### Valor Retornado

Retorna a parte de `haystack`, ou `false` se `needle` não for encontrada.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | O parâmetro opcional `locale` foi adicionado.

### Exemplos

Exemplo #1 Exemplo de grapheme_stristr()

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) NFD
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) NFD
    $char_O_diaeresis_nfd = "O\xCC\x88"; // 'LATIN CAPITAL LETTER O WITH DIAERESIS' (U+00D6) NFD

    print urlencode(grapheme_stristr( $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_a_ring_nfd, $char_O_diaeresis_nfd));

    ?>

O exemplo acima produzirá:

    o%CC%88a%CC%8A

### Veja Também

- grapheme_stripos() - Encontra a posição (em unidades de grafema) da primeira ocorrência de uma string não sensível a maiúsculas/minúsculas
- grapheme_strpos() - Encontra a posição (em unidades de grafema) da primeira ocorrência de uma string
- grapheme_strripos() - Encontra a posição (em unidades de grafema) da última ocorrência de uma string (insensível a maiúsculas/minúsculas)
- grapheme_strrpos() - Encontra a posição (em unidades de grafema) da última ocorrência de uma string
- grapheme_strstr() - Retorna parte de uma string a partir da primeira ocorrência de outra string até o final
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_strlen

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strlen — Obtém o comprimento de uma string em unidade de grafema

### Descrição

Estilo procedural

function grapheme_strlen(string `$string`): int|false|null

Obtém o comprimento de uma string em unidade de grafema (não em bytes ou caracteres).

### Parâmetros

`string`

  A string sendo medida. Deve ser em UTF-8 válido.

### Valor Retornado

O comprimento da string em caso de sucesso, `null` ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de grapheme_strlen()

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) NFD
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) NFD

    print grapheme_strlen( 'abc' . $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_a_ring_nfd);

    ?>

O exemplo acima produzirá:

    6

### Veja Também

- » Unicode Text Segmentation: Grapheme Cluster Boundaries
- iconv_strlen() - Retorna a contagem de caracteres da string
- mb_strlen() - Obtém o comprimento da string
- strlen() - Retorna o tamanho de uma string

# grapheme_strpos

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strpos — Encontra a posição (em unidades de grafema) da primeira ocorrência de uma string

### Descrição

Estilo procedural

function grapheme_strpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
string `$locale` = ""
): int|false

Encontra a posição (em unidades de grafema) da primeira ocorrência de uma string.

### Parâmetros

`haystack`

  A string onde ocorrerá a pesquisa. Deve ser em UTF-8 válido.

`needle`

  A string a ser procurada. Deve ser em UTF-8 válido.

`offset`

  O parâmetro opcional `offset` permite especificar onde no `haystack` deve-se iniciar a pesquisa, como uma posição em unidades de grafema (não em bytes ou caracteres). Se a posição for negativa, será tratada como relativa ao final da string. A posição retornada ainda será relativa ao início do `haystack` independentemente do valor de `offset`.

`locale`
  Localidade a ser usada.

### Valor Retornado

Retora a posição como um inteiro. Se `needle` não for encontrado, grapheme_strpos() retornará `false`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | O parâmetro opcional `locale` foi adicionado.
7.1.0 | Suporte para `offset` negativo foi adicionado.

### Exemplos

Exemplo #1 Exemplo de grapheme_strpos()

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) NFD
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) NFD

    print grapheme_strpos( $char_a_ring_nfd . $char_a_ring_nfd . $char_o_diaeresis_nfd, $char_o_diaeresis_nfd);

    ?>

O exemplo acima produzirá:

    2

### Veja Também

- grapheme_stripos() - Encontra a posição (em unidades de grafema) da primeira ocorrência de uma string não sensível a maiúsculas/minúsculas
- grapheme_stristr() - Retorna parte de uma string a partir da primeira ocorrência de outra string (insensível a maiúsculas/minúsculas) até o final
- grapheme_strripos() - Encontra a posição (em unidades de grafema) da última ocorrência de uma string (insensível a maiúsculas/minúsculas)
- grapheme_strrpos() - Encontra a posição (em unidades de grafema) da última ocorrência de uma string
- grapheme_strstr() - Retorna parte de uma string a partir da primeira ocorrência de outra string até o final
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_strripos

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strripos — Encontra a posição (em unidades de grafema) da última ocorrência de uma string (insensível a maiúsculas/minúsculas)

### Descrição

Estilo procedural

function grapheme_strripos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
string `$locale` = ""
): int|false

Encontra a posição (em unidades de grafema) da última ocorrência de uma string (insensível a maiúsculas/minúsculas).

### Parâmetros

`haystack`

  A string onde ocorrerá a pesquisa. Deve ser em UTF-8 válido.

`needle`

  A string a ser procurada. Deve ser em UTF-8 válido.

`offset`

  O parâmetro opcional `offset` permite especificar onde no `haystack` deve-se iniciar a pesquisa, como uma posição em unidades de grafema (não em bytes ou caracteres). A posição retornada ainda será relativa ao início do `haystack` independentemente do valor de `offset`.

`locale`
  Localidade a ser usada.

### Valor Retornado

Retora a posição como um inteiro. Se `needle` não for encontrado, grapheme_strripos() retornará `false`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | O parâmetro opcional `locale` foi adicionado.

### Exemplos

Exemplo #1 Exemplo de grapheme_strripos()

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) NFD
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) NFD
    $char_O_diaeresis_nfd = "O\xCC\x88"; // 'LATIN CAPITAL LETTER O WITH DIAERESIS' (U+00D6) NFD

    print grapheme_strripos( $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_o_diaeresis_nfd, $char_O_diaeresis_nfd);

    ?>

O exemplo acima produzirá:

    2

### Veja Também

- grapheme_stripos() - Encontra a posição (em unidades de grafema) da primeira ocorrência de uma string não sensível a maiúsculas/minúsculas
- grapheme_stristr() - Retorna parte de uma string a partir da primeira ocorrência de outra string (insensível a maiúsculas/minúsculas) até o final
- grapheme_strpos() - Encontra a posição (em unidades de grafema) da primeira ocorrência de uma string
- grapheme_strrpos() - Encontra a posição (em unidades de grafema) da última ocorrência de uma string
- grapheme_strstr() - Retorna parte de uma string a partir da primeira ocorrência de outra string até o final
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_strrpos

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strrpos — Encontra a posição (em unidades de grafema) da última ocorrência de uma string

### Descrição

Estilo procedural

function grapheme_strrpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
string `$locale` = ""
): int|false

Encontra a posição (em unidades de grafema) da última ocorrência de uma string.

### Parâmetros

`haystack`

  A string onde ocorrerá a pesquisa. Deve ser em UTF-8 válido.

`needle`

  A string a ser procurada. Deve ser em UTF-8 válido.

`offset`

  O parâmetro opcional `offset` permite especificar onde no `haystack` deve-se iniciar a pesquisa, como uma posição em unidades de grafema (não em bytes ou caracteres). A posição retornada ainda será relativa ao início do `haystack` independentemente do valor de `offset`.

`locale`
  Localidade a ser usada.

### Valor Retornado

Retora a posição como um inteiro. Se `needle` não for encontrado, grapheme_strrpos() retornará `false`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | O parâmetro opcional `locale` foi adicionado.

### Exemplos

Exemplo #1 Exemplo de grapheme_strrpos()

    <?php
    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' NFD
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) NFD

    print grapheme_strrpos( $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_o_diaeresis_nfd, $char_o_diaeresis_nfd);
    ?>

O exemplo acima produzirá:

    2

### Veja Também

- grapheme_stripos() - Encontra a posição (em unidades de grafema) da primeira ocorrência de uma string não sensível a maiúsculas/minúsculas
- grapheme_stristr() - Retorna parte de uma string a partir da primeira ocorrência de outra string (insensível a maiúsculas/minúsculas) até o final
- grapheme_strpos() - Encontra a posição (em unidades de grafema) da primeira ocorrência de uma string
- grapheme_strripos() - Encontra a posição (em unidades de grafema) da última ocorrência de uma string (insensível a maiúsculas/minúsculas)
- grapheme_strstr() - Retorna parte de uma string a partir da primeira ocorrência de outra string até o final
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_strstr

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strstr — Retorna parte de uma string a partir da primeira ocorrência de outra string até o final

### Descrição

Estilo procedural

function grapheme_strstr(
string `$haystack`,
string `$needle`,
bool `$beforeNeedle` = `false`,
string `$locale` = ""
): string|false

Retorna parte de uma string a partir da primeira ocorrência de outra string (inclusive) até o final.

### Parâmetros

`haystack`

  A string onde ocorrerá a pesquisa. Deve ser em UTF-8 válido.

`needle`

  A string a ser procurada. Deve ser em UTF-8 válido.

`beforeNeedle`

  Caso seja `true`, grapheme_strstr() retorna a parte da string `haystack` antes da primeira ocorrência de `needle` (excluindo `needle`).

`locale`
  Localidade a ser usada.

### Valor Retornado

Retorna a parte de `haystack`, ou `false` se `needle` não for encontrada.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | O parâmetro opcional `locale` foi adicionado.

### Exemplos

Exemplo #1 Exemplo de grapheme_strstr()

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) NFD
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) NFD

    print urlencode(grapheme_stristr( $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_a_ring_nfd, $char_o_diaeresis_nfd));

    ?>

O exemplo acima produzirá:

    o%CC%88a%CC%8A

### Veja Também

- grapheme_stristr() - Retorna parte de uma string a partir da primeira ocorrência de outra string (insensível a maiúsculas/minúsculas) até o final
- grapheme_stripos() - Encontra a posição (em unidades de grafema) da primeira ocorrência de uma string não sensível a maiúsculas/minúsculas
- grapheme_strpos() - Encontra a posição (em unidades de grafema) da primeira ocorrência de uma string
- grapheme_strripos() - Encontra a posição (em unidades de grafema) da última ocorrência de uma string (insensível a maiúsculas/minúsculas)
- grapheme_strrpos() - Encontra a posição (em unidades de grafema) da última ocorrência de uma string
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_substr

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_substr — Retorna parte de uma string

### Descrição

Estilo procedural

function grapheme_substr(
string `$string`,
int `$offset`,
?int `$length` = `null`,
string `$locale` = ""
): string|false

Retorna parte de uma string.

### Parâmetros

`string`

  A string de entrada. Deve ser em UTF-8 válido.

`offset`

  Posição de início em unidades padrão de grafema. Se `offset` for não negativo, a string retornada iniciará na posição `offset` da `string`, contando a partir de zero. Se `offset` for negativo, a string retornada iniciará no posição `offset` em unidades de grafema contada a partir do final da string.

`length`

  Comprimento em unidades de grafema. Se `length` for informado e positivo, a string retornada conterá, no máximo, a quantidade de grafemas informada em `length`, iniciando de `offset` (dependendo do comprimento da string). Se `length` for informado e negativo, representará as unidades de grafema que serão omitidas no final da string (depois da posição de início calculada quando `offset` é negativo). Se `offset` denotar uma posição além deste truncamento, uma string vazia será retornada.

`locale`
  Localidade a ser usada.

### Valor Retornado

Retorna a parte extraída da `string`, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | O parâmetro opcional `locale` foi adicionado.
8.0.0 | A função agora fixa consistentemente deslocamentos fora dos limites ao limite da string. Anteriormente, `false` era retornado em vez da string vazia em alguns casos.

### Exemplos

Exemplo #1 Exemplo de grapheme_substr()

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) NFD
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) NFD

    print urlencode(grapheme_substr( "ao" . $char_a_ring_nfd . "bc" . $char_o_diaeresis_nfd . "O", 2, -1 ));
    ?>

O exemplo acima produzirá:

    a%CC%8Abco%CC%88

### Veja Também

- grapheme_extract() - Extrai uma sequência de grupos padrão de grafemas de um buffer de texto em UTF-8
- » Segmentação de texto Unicode: limites do cluster de grafema (em inglês)

## Índice

- grapheme_extract — Extrai uma sequência de grupos padrão de grafemas de um buffer de texto em UTF-8
- grapheme_str_split — Separa uma string em um array
- grapheme_stripos — Encontra a posição (em unidades de grafema) da primeira ocorrência de uma string não sensível a maiúsculas/minúsculas
- grapheme_stristr — Retorna parte de uma string a partir da primeira ocorrência de outra string (insensível a maiúsculas/minúsculas) até o final
- grapheme_strlen — Obtém o comprimento de uma string em unidade de grafema
- grapheme_strpos — Encontra a posição (em unidades de grafema) da primeira ocorrência de uma string
- grapheme_strripos — Encontra a posição (em unidades de grafema) da última ocorrência de uma string (insensível a maiúsculas/minúsculas)
- grapheme_strrpos — Encontra a posição (em unidades de grafema) da última ocorrência de uma string
- grapheme_strstr — Retorna parte de uma string a partir da primeira ocorrência de outra string até o final
- grapheme_substr — Retorna parte de uma string

# Funções de IDN

# idn_to_ascii

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.2, PECL idn >= 0.1)

idn_to_ascii — Converte nome de domínio para a forma ASCII IDNA

### Descrição

Estilo procedural

function idn_to_ascii(
string `$domain`,
int `$flags` = `IDNA_DEFAULT`,
int `$variant` = `INTL_IDNA_VARIANT_UTS46`,
array `&$idna_info` = `null`
): string|false

Esta função converte um nome de domínio Unicode para um formato IDNA compatível com ASCII em minúsculas.

### Parâmetros

`domain`

  O domínio a converter, que precisa ser codificado em UTF-8.

`flags`

  Opções de conversão - combinação de constantes IDNA_* (exceto constantes IDNA_ERROR_*).

`variant`

  Pode ser `INTL_IDNA_VARIANT_2003` (descontinuada a partir do PHP 7.2.0) para IDNA 2003 ou `INTL_IDNA_VARIANT_UTS46` (disponível apenas a partir da ICU 4.6) para UTS #46.

`idna_info`

  Este parâmetro pode ser usado somente se `INTL_IDNA_VARIANT_UTS46` foi usado no parâmetro `variant`. Neste caso, será preenchido com um array com as chaves `'result'`, o possível resultado ilegal da transformação, `'isTransitionalDifferent'`, um booleano indicando se o uso de mecanismos transicionais da UTS #46 mudou ou teria mudado o resultado e `'errors'`, que é um int representando um conjunto de bits das constantes de erro IDNA_ERROR_*.

### Valor Retornado

O nome de domínio codificado em forma compatível com ASCII-compatible, ou `false` em caso de falha

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Agora lança um ValueError se o parâmetro `domain` for vazio.
8.4.0 | Agora lança um ValueError se o parâmetro `variant` não for `INTL_IDNA_VARIANT_UTS46`.
7.4.0 | O valor padrão de `variant` agora é `INTL_IDNA_VARIANT_UTS46` ao invés da `INTL_IDNA_VARIANT_2003` que foi descontinuada.
7.2.0 | `INTL_IDNA_VARIANT_2003` foi descontinuada; use `INTL_IDNA_VARIANT_UTS46` em seu lugar.

### Exemplos

Exemplo #1 Exemplo de idn_to_ascii()

    <?php

    echo idn_to_ascii('täst.de');

    ?>

O exemplo acima produzirá:

    xn--tst-qla.de

Exemplo #2 Nomes de domínio inteiramente em ASCII são simplesmente convertidos para minúsculas

    <?php

    var_dump(idn_to_ascii('Example.com'));

    ?>

O exemplo acima produzirá:

    string(11) "example.com"

### Veja Também

- idn_to_utf8() - Converte nome de domínio de ASCII IDNA para Unicode

# idn_to_utf8

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.2, PECL idn >= 0.1)

idn_to_utf8 — Converte nome de domínio de ASCII IDNA para Unicode

### Descrição

Estilo procedural

function idn_to_utf8(
string `$domain`,
int `$flags` = `IDNA_DEFAULT`,
int `$variant` = `INTL_IDNA_VARIANT_UTS46`,
array `&$idna_info` = `null`
): string|false

Esta função converte um nome de domínio Unicode a partir de um formato compatível com ASCII IDNA para Unicode puro, codificado em UTF-8.

### Parâmetros

`domain`

  Domínio em formato compatível com ASCII IDNA a ser convertido.

`flags`

  Opções de conversão - combinação de constantes IDNA_* (exceto constantes IDNA_ERROR_*).

`variant`

  Pode ser `INTL_IDNA_VARIANT_2003` (descontinuada a partir do PHP 7.2.0) para IDNA 2003 ou `INTL_IDNA_VARIANT_UTS46` (disponível apenas a partir da ICU 4.6) para UTS #46.

`idna_info`

  Este parâmetro pode ser usado somente se `INTL_IDNA_VARIANT_UTS46` foi usado no parâmetro `variant`. Neste caso, será preenchido com um array com as chaves `'result'`, o possível resultado ilegal da transformação, `'isTransitionalDifferent'`, um booleano indicando se o uso de mecanismos transicionais da UTS #46 mudou ou teria mudado o resultado e `'errors'`, que é um int representando um conjunto de bits das constantes de erro IDNA_ERROR_*.

### Valor Retornado

O nome de domínio em Unicode, codificado em UTF-8, ou `false` em caso de falha

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Agora lança um ValueError se o parâmetro `domain` for vazio.
8.4.0 | Agora lança um ValueError se o parâmetro `variant` não for `INTL_IDNA_VARIANT_UTS46`.
7.4.0 | O valor padrão de `variant` agora é `INTL_IDNA_VARIANT_UTS46` ao invés da `INTL_IDNA_VARIANT_2003` que foi descontinuada.
7.2.0 | `INTL_IDNA_VARIANT_2003` foi descontinuada; use `INTL_IDNA_VARIANT_UTS46` em seu lugar.

### Exemplos

Exemplo #1 Exemplo de idn_to_utf8()

    <?php

    echo idn_to_utf8('xn--tst-qla.de');

    ?>

O exemplo acima produzirá:

    täst.de

### Veja Também

- idn_to_ascii() - Converte nome de domínio para a forma ASCII IDNA

## Índice

- idn_to_ascii — Converte nome de domínio para a forma ASCII IDNA
- idn_to_utf8 — Converte nome de domínio de ASCII IDNA para Unicode

# IntlChar

(PHP 7, PHP 8)

## Introdução

IntlChar fornece acesso a um número de métodos utilitários que podem ser usados para acessar informações sobre caracteres Unicode.

Os métodos e constantes são aderentes de maneira muito próxima aos nomes e comportamentos utilizados pela biblioteca ICU subjacente.

## Resumo da classe

class IntlChar {
/* Constantes */
public const string UNICODE_VERSION;
public const int CODEPOINT_MIN;
public const int CODEPOINT_MAX;
public const float NO_NUMERIC_VALUE;
public const int PROPERTY_ALPHABETIC;
public const int PROPERTY_BINARY_START;
public const int PROPERTY_ASCII_HEX_DIGIT;
public const int PROPERTY_BIDI_CONTROL;
public const int PROPERTY_BIDI_MIRRORED;
public const int PROPERTY_DASH;
public const int PROPERTY_DEFAULT_IGNORABLE_CODE_POINT;
public const int PROPERTY_DEPRECATED;
public const int PROPERTY_DIACRITIC;
public const int PROPERTY_EXTENDER;
public const int PROPERTY_FULL_COMPOSITION_EXCLUSION;
public const int PROPERTY_GRAPHEME_BASE;
public const int PROPERTY_GRAPHEME_EXTEND;
public const int PROPERTY_GRAPHEME_LINK;
public const int PROPERTY_HEX_DIGIT;
public const int PROPERTY_HYPHEN;
public const int PROPERTY_ID_CONTINUE;
public const int PROPERTY_ID_START;
public const int PROPERTY_IDEOGRAPHIC;
public const int PROPERTY_IDS_BINARY_OPERATOR;
public const int PROPERTY_IDS_TRINARY_OPERATOR;
public const int PROPERTY_IDS_UNARY_OPERATOR;
public const int PROPERTY_ID_COMPAT_MATH_START;
public const int PROPERTY_ID_COMPAT_MATH_CONTINUE;
public const int PROPERTY_JOIN_CONTROL;
public const int PROPERTY_LOGICAL_ORDER_EXCEPTION;
public const int PROPERTY_LOWERCASE;
public const int PROPERTY_MATH;
public const int PROPERTY_NONCHARACTER_CODE_POINT;
public const int PROPERTY_QUOTATION_MARK;
public const int PROPERTY_RADICAL;
public const int PROPERTY_SOFT_DOTTED;
public const int PROPERTY_TERMINAL_PUNCTUATION;
public const int PROPERTY_UNIFIED_IDEOGRAPH;
public const int PROPERTY_UPPERCASE;
public const int PROPERTY_WHITE_SPACE;
public const int PROPERTY_XID_CONTINUE;
public const int PROPERTY_XID_START;
public const int PROPERTY_CASE_SENSITIVE;
public const int PROPERTY_S_TERM;
public const int PROPERTY_VARIATION_SELECTOR;
public const int PROPERTY_NFD_INERT;
public const int PROPERTY_NFKD_INERT;
public const int PROPERTY_NFC_INERT;
public const int PROPERTY_NFKC_INERT;
public const int PROPERTY_SEGMENT_STARTER;
public const int PROPERTY_PATTERN_SYNTAX;
public const int PROPERTY_PATTERN_WHITE_SPACE;
public const int PROPERTY_POSIX_ALNUM;
public const int PROPERTY_POSIX_BLANK;
public const int PROPERTY_POSIX_GRAPH;
public const int PROPERTY_POSIX_PRINT;
public const int PROPERTY_POSIX_XDIGIT;
public const int PROPERTY_CASED;
public const int PROPERTY_CASE_IGNORABLE;
public const int PROPERTY_CHANGES_WHEN_LOWERCASED;
public const int PROPERTY_CHANGES_WHEN_UPPERCASED;
public const int PROPERTY_CHANGES_WHEN_TITLECASED;
public const int PROPERTY_CHANGES_WHEN_CASEFOLDED;
public const int PROPERTY_CHANGES_WHEN_CASEMAPPED;
public const int PROPERTY_CHANGES_WHEN_NFKC_CASEFOLDED;
public const int PROPERTY_BINARY_LIMIT;
public const int PROPERTY_BIDI_CLASS;
public const int PROPERTY_INT_START;
public const int PROPERTY_BLOCK;
public const int PROPERTY_CANONICAL_COMBINING_CLASS;
public const int PROPERTY_DECOMPOSITION_TYPE;
public const int PROPERTY_EAST_ASIAN_WIDTH;
public const int PROPERTY_GENERAL_CATEGORY;
public const int PROPERTY_JOINING_GROUP;
public const int PROPERTY_JOINING_TYPE;
public const int PROPERTY_LINE_BREAK;
public const int PROPERTY_NUMERIC_TYPE;
public const int PROPERTY_SCRIPT;
public const int PROPERTY_HANGUL_SYLLABLE_TYPE;
public const int PROPERTY_NFD_QUICK_CHECK;
public const int PROPERTY_NFKD_QUICK_CHECK;
public const int PROPERTY_NFC_QUICK_CHECK;
public const int PROPERTY_NFKC_QUICK_CHECK;
public const int PROPERTY_LEAD_CANONICAL_COMBINING_CLASS;
public const int PROPERTY_TRAIL_CANONICAL_COMBINING_CLASS;
public const int PROPERTY_GRAPHEME_CLUSTER_BREAK;
public const int PROPERTY_SENTENCE_BREAK;
public const int PROPERTY_WORD_BREAK;
public const int PROPERTY_BIDI_PAIRED_BRACKET_TYPE;
public const int PROPERTY_INT_LIMIT;
public const int PROPERTY_GENERAL_CATEGORY_MASK;
public const int PROPERTY_MASK_START;
public const int PROPERTY_MASK_LIMIT;
public const int PROPERTY_NUMERIC_VALUE;
public const int PROPERTY_DOUBLE_START;
public const int PROPERTY_DOUBLE_LIMIT;
public const int PROPERTY_AGE;
public const int PROPERTY_STRING_START;
public const int PROPERTY_BIDI_MIRRORING_GLYPH;
public const int PROPERTY_CASE_FOLDING;
public const int PROPERTY_ISO_COMMENT;
public const int PROPERTY_LOWERCASE_MAPPING;
public const int PROPERTY_NAME;
public const int PROPERTY_SIMPLE_CASE_FOLDING;
public const int PROPERTY_SIMPLE_LOWERCASE_MAPPING;
public const int PROPERTY_SIMPLE_TITLECASE_MAPPING;
public const int PROPERTY_SIMPLE_UPPERCASE_MAPPING;
public const int PROPERTY_TITLECASE_MAPPING;
public const int PROPERTY_UNICODE_1_NAME;
public const int PROPERTY_UPPERCASE_MAPPING;
public const int PROPERTY_BIDI_PAIRED_BRACKET;
public const int PROPERTY_STRING_LIMIT;
public const int PROPERTY_SCRIPT_EXTENSIONS;
public const int PROPERTY_OTHER_PROPERTY_START;
public const int PROPERTY_OTHER_PROPERTY_LIMIT;
public const int PROPERTY_INVALID_CODE;
public const int CHAR_CATEGORY_UNASSIGNED;
public const int CHAR_CATEGORY_GENERAL_OTHER_TYPES;
public const int CHAR_CATEGORY_UPPERCASE_LETTER;
public const int CHAR_CATEGORY_LOWERCASE_LETTER;
public const int CHAR_CATEGORY_TITLECASE_LETTER;
public const int CHAR_CATEGORY_MODIFIER_LETTER;
public const int CHAR_CATEGORY_OTHER_LETTER;
public const int CHAR_CATEGORY_NON_SPACING_MARK;
public const int CHAR_CATEGORY_ENCLOSING_MARK;
public const int CHAR_CATEGORY_COMBINING_SPACING_MARK;
public const int CHAR_CATEGORY_DECIMAL_DIGIT_NUMBER;
public const int CHAR_CATEGORY_LETTER_NUMBER;
public const int CHAR_CATEGORY_OTHER_NUMBER;
public const int CHAR_CATEGORY_SPACE_SEPARATOR;
public const int CHAR_CATEGORY_LINE_SEPARATOR;
public const int CHAR_CATEGORY_PARAGRAPH_SEPARATOR;
public const int CHAR_CATEGORY_CONTROL_CHAR;
public const int CHAR_CATEGORY_FORMAT_CHAR;
public const int CHAR_CATEGORY_PRIVATE_USE_CHAR;
public const int CHAR_CATEGORY_SURROGATE;
public const int CHAR_CATEGORY_DASH_PUNCTUATION;
public const int CHAR_CATEGORY_START_PUNCTUATION;
public const int CHAR_CATEGORY_END_PUNCTUATION;
public const int CHAR_CATEGORY_CONNECTOR_PUNCTUATION;
public const int CHAR_CATEGORY_OTHER_PUNCTUATION;
public const int CHAR_CATEGORY_MATH_SYMBOL;
public const int CHAR_CATEGORY_CURRENCY_SYMBOL;
public const int CHAR_CATEGORY_MODIFIER_SYMBOL;
public const int CHAR_CATEGORY_OTHER_SYMBOL;
public const int CHAR_CATEGORY_INITIAL_PUNCTUATION;
public const int CHAR_CATEGORY_FINAL_PUNCTUATION;
public const int CHAR_CATEGORY_CHAR_CATEGORY_COUNT;
public const int CHAR_DIRECTION_LEFT_TO_RIGHT;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT;
public const int CHAR_DIRECTION_EUROPEAN_NUMBER;
public const int CHAR_DIRECTION_EUROPEAN_NUMBER_SEPARATOR;
public const int CHAR_DIRECTION_EUROPEAN_NUMBER_TERMINATOR;
public const int CHAR_DIRECTION_ARABIC_NUMBER;
public const int CHAR_DIRECTION_COMMON_NUMBER_SEPARATOR;
public const int CHAR_DIRECTION_BLOCK_SEPARATOR;
public const int CHAR_DIRECTION_SEGMENT_SEPARATOR;
public const int CHAR_DIRECTION_WHITE_SPACE_NEUTRAL;
public const int CHAR_DIRECTION_OTHER_NEUTRAL;
public const int CHAR_DIRECTION_LEFT_TO_RIGHT_EMBEDDING;
public const int CHAR_DIRECTION_LEFT_TO_RIGHT_OVERRIDE;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT_ARABIC;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT_EMBEDDING;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT_OVERRIDE;
public const int CHAR_DIRECTION_POP_DIRECTIONAL_FORMAT;
public const int CHAR_DIRECTION_DIR_NON_SPACING_MARK;
public const int CHAR_DIRECTION_BOUNDARY_NEUTRAL;
public const int CHAR_DIRECTION_FIRST_STRONG_ISOLATE;
public const int CHAR_DIRECTION_LEFT_TO_RIGHT_ISOLATE;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT_ISOLATE;
public const int CHAR_DIRECTION_POP_DIRECTIONAL_ISOLATE;
public const int CHAR_DIRECTION_CHAR_DIRECTION_COUNT;
public const int BLOCK_CODE_NO_BLOCK;
public const int BLOCK_CODE_BASIC_LATIN;
public const int BLOCK_CODE_LATIN_1_SUPPLEMENT;
public const int BLOCK_CODE_LATIN_EXTENDED_A;
public const int BLOCK_CODE_LATIN_EXTENDED_B;
public const int BLOCK_CODE_IPA_EXTENSIONS;
public const int BLOCK_CODE_SPACING_MODIFIER_LETTERS;
public const int BLOCK_CODE_COMBINING_DIACRITICAL_MARKS;
public const int BLOCK_CODE_GREEK;
public const int BLOCK_CODE_CYRILLIC;
public const int BLOCK_CODE_ARMENIAN;
public const int BLOCK_CODE_HEBREW;
public const int BLOCK_CODE_ARABIC;
public const int BLOCK_CODE_SYRIAC;
public const int BLOCK_CODE_THAANA;
public const int BLOCK_CODE_DEVANAGARI;
public const int BLOCK_CODE_BENGALI;
public const int BLOCK_CODE_GURMUKHI;
public const int BLOCK_CODE_GUJARATI;
public const int BLOCK_CODE_ORIYA;
public const int BLOCK_CODE_TAMIL;
public const int BLOCK_CODE_TELUGU;
public const int BLOCK_CODE_KANNADA;
public const int BLOCK_CODE_MALAYALAM;
public const int BLOCK_CODE_SINHALA;
public const int BLOCK_CODE_THAI;
public const int BLOCK_CODE_LAO;
public const int BLOCK_CODE_TIBETAN;
public const int BLOCK_CODE_MYANMAR;
public const int BLOCK_CODE_GEORGIAN;
public const int BLOCK_CODE_HANGUL_JAMO;
public const int BLOCK_CODE_ETHIOPIC;
public const int BLOCK_CODE_CHEROKEE;
public const int BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS;
public const int BLOCK_CODE_OGHAM;
public const int BLOCK_CODE_RUNIC;
public const int BLOCK_CODE_KHMER;
public const int BLOCK_CODE_MONGOLIAN;
public const int BLOCK_CODE_LATIN_EXTENDED_ADDITIONAL;
public const int BLOCK_CODE_GREEK_EXTENDED;
public const int BLOCK_CODE_GENERAL_PUNCTUATION;
public const int BLOCK_CODE_SUPERSCRIPTS_AND_SUBSCRIPTS;
public const int BLOCK_CODE_CURRENCY_SYMBOLS;
public const int BLOCK_CODE_COMBINING_MARKS_FOR_SYMBOLS;
public const int BLOCK_CODE_LETTERLIKE_SYMBOLS;
public const int BLOCK_CODE_NUMBER_FORMS;
public const int BLOCK_CODE_ARROWS;
public const int BLOCK_CODE_MATHEMATICAL_OPERATORS;
public const int BLOCK_CODE_MISCELLANEOUS_TECHNICAL;
public const int BLOCK_CODE_CONTROL_PICTURES;
public const int BLOCK_CODE_OPTICAL_CHARACTER_RECOGNITION;
public const int BLOCK_CODE_ENCLOSED_ALPHANUMERICS;
public const int BLOCK_CODE_BOX_DRAWING;
public const int BLOCK_CODE_BLOCK_ELEMENTS;
public const int BLOCK_CODE_GEOMETRIC_SHAPES;
public const int BLOCK_CODE_MISCELLANEOUS_SYMBOLS;
public const int BLOCK_CODE_DINGBATS;
public const int BLOCK_CODE_BRAILLE_PATTERNS;
public const int BLOCK_CODE_CJK_RADICALS_SUPPLEMENT;
public const int BLOCK_CODE_KANGXI_RADICALS;
public const int BLOCK_CODE_IDEOGRAPHIC_DESCRIPTION_CHARACTERS;
public const int BLOCK_CODE_CJK_SYMBOLS_AND_PUNCTUATION;
public const int BLOCK_CODE_HIRAGANA;
public const int BLOCK_CODE_KATAKANA;
public const int BLOCK_CODE_BOPOMOFO;
public const int BLOCK_CODE_HANGUL_COMPATIBILITY_JAMO;
public const int BLOCK_CODE_KANBUN;
public const int BLOCK_CODE_BOPOMOFO_EXTENDED;
public const int BLOCK_CODE_ENCLOSED_CJK_LETTERS_AND_MONTHS;
public const int BLOCK_CODE_CJK_COMPATIBILITY;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_A;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS;
public const int BLOCK_CODE_YI_SYLLABLES;
public const int BLOCK_CODE_YI_RADICALS;
public const int BLOCK_CODE_HANGUL_SYLLABLES;
public const int BLOCK_CODE_HIGH_SURROGATES;
public const int BLOCK_CODE_HIGH_PRIVATE_USE_SURROGATES;
public const int BLOCK_CODE_LOW_SURROGATES;
public const int BLOCK_CODE_PRIVATE_USE_AREA;
public const int BLOCK_CODE_PRIVATE_USE;
public const int BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS;
public const int BLOCK_CODE_ALPHABETIC_PRESENTATION_FORMS;
public const int BLOCK_CODE_ARABIC_PRESENTATION_FORMS_A;
public const int BLOCK_CODE_COMBINING_HALF_MARKS;
public const int BLOCK_CODE_CJK_COMPATIBILITY_FORMS;
public const int BLOCK_CODE_SMALL_FORM_VARIANTS;
public const int BLOCK_CODE_ARABIC_PRESENTATION_FORMS_B;
public const int BLOCK_CODE_SPECIALS;
public const int BLOCK_CODE_HALFWIDTH_AND_FULLWIDTH_FORMS;
public const int BLOCK_CODE_OLD_ITALIC;
public const int BLOCK_CODE_GOTHIC;
public const int BLOCK_CODE_DESERET;
public const int BLOCK_CODE_BYZANTINE_MUSICAL_SYMBOLS;
public const int BLOCK_CODE_MUSICAL_SYMBOLS;
public const int BLOCK_CODE_MATHEMATICAL_ALPHANUMERIC_SYMBOLS;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_B;
public const int BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS_SUPPLEMENT;
public const int BLOCK_CODE_TAGS;
public const int BLOCK_CODE_CYRILLIC_SUPPLEMENT;
public const int BLOCK_CODE_CYRILLIC_SUPPLEMENTARY;
public const int BLOCK_CODE_TAGALOG;
public const int BLOCK_CODE_HANUNOO;
public const int BLOCK_CODE_BUHID;
public const int BLOCK_CODE_TAGBANWA;
public const int BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_A;
public const int BLOCK_CODE_SUPPLEMENTAL_ARROWS_A;
public const int BLOCK_CODE_SUPPLEMENTAL_ARROWS_B;
public const int BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_B;
public const int BLOCK_CODE_SUPPLEMENTAL_MATHEMATICAL_OPERATORS;
public const int BLOCK_CODE_KATAKANA_PHONETIC_EXTENSIONS;
public const int BLOCK_CODE_VARIATION_SELECTORS;
public const int BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_A;
public const int BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_B;
public const int BLOCK_CODE_LIMBU;
public const int BLOCK_CODE_TAI_LE;
public const int BLOCK_CODE_KHMER_SYMBOLS;
public const int BLOCK_CODE_PHONETIC_EXTENSIONS;
public const int BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_ARROWS;
public const int BLOCK_CODE_YIJING_HEXAGRAM_SYMBOLS;
public const int BLOCK_CODE_LINEAR_B_SYLLABARY;
public const int BLOCK_CODE_LINEAR_B_IDEOGRAMS;
public const int BLOCK_CODE_AEGEAN_NUMBERS;
public const int BLOCK_CODE_UGARITIC;
public const int BLOCK_CODE_SHAVIAN;
public const int BLOCK_CODE_OSMANYA;
public const int BLOCK_CODE_CYPRIOT_SYLLABARY;
public const int BLOCK_CODE_TAI_XUAN_JING_SYMBOLS;
public const int BLOCK_CODE_VARIATION_SELECTORS_SUPPLEMENT;
public const int BLOCK_CODE_ANCIENT_GREEK_MUSICAL_NOTATION;
public const int BLOCK_CODE_ANCIENT_GREEK_NUMBERS;
public const int BLOCK_CODE_ARABIC_SUPPLEMENT;
public const int BLOCK_CODE_BUGINESE;
public const int BLOCK_CODE_CJK_STROKES;
public const int BLOCK_CODE_COMBINING_DIACRITICAL_MARKS_SUPPLEMENT;
public const int BLOCK_CODE_COPTIC;
public const int BLOCK_CODE_ETHIOPIC_EXTENDED;
public const int BLOCK_CODE_ETHIOPIC_SUPPLEMENT;
public const int BLOCK_CODE_GEORGIAN_SUPPLEMENT;
public const int BLOCK_CODE_GLAGOLITIC;
public const int BLOCK_CODE_KHAROSHTHI;
public const int BLOCK_CODE_MODIFIER_TONE_LETTERS;
public const int BLOCK_CODE_NEW_TAI_LUE;
public const int BLOCK_CODE_OLD_PERSIAN;
public const int BLOCK_CODE_PHONETIC_EXTENSIONS_SUPPLEMENT;
public const int BLOCK_CODE_SUPPLEMENTAL_PUNCTUATION;
public const int BLOCK_CODE_SYLOTI_NAGRI;
public const int BLOCK_CODE_TIFINAGH;
public const int BLOCK_CODE_VERTICAL_FORMS;
public const int BLOCK_CODE_NKO;
public const int BLOCK_CODE_BALINESE;
public const int BLOCK_CODE_LATIN_EXTENDED_C;
public const int BLOCK_CODE_LATIN_EXTENDED_D;
public const int BLOCK_CODE_PHAGS_PA;
public const int BLOCK_CODE_PHOENICIAN;
public const int BLOCK_CODE_CUNEIFORM;
public const int BLOCK_CODE_CUNEIFORM_NUMBERS_AND_PUNCTUATION;
public const int BLOCK_CODE_COUNTING_ROD_NUMERALS;
public const int BLOCK_CODE_SUNDANESE;
public const int BLOCK_CODE_LEPCHA;
public const int BLOCK_CODE_OL_CHIKI;
public const int BLOCK_CODE_CYRILLIC_EXTENDED_A;
public const int BLOCK_CODE_VAI;
public const int BLOCK_CODE_CYRILLIC_EXTENDED_B;
public const int BLOCK_CODE_SAURASHTRA;
public const int BLOCK_CODE_KAYAH_LI;
public const int BLOCK_CODE_REJANG;
public const int BLOCK_CODE_CHAM;
public const int BLOCK_CODE_ANCIENT_SYMBOLS;
public const int BLOCK_CODE_PHAISTOS_DISC;
public const int BLOCK_CODE_LYCIAN;
public const int BLOCK_CODE_CARIAN;
public const int BLOCK_CODE_LYDIAN;
public const int BLOCK_CODE_MAHJONG_TILES;
public const int BLOCK_CODE_DOMINO_TILES;
public const int BLOCK_CODE_SAMARITAN;
public const int BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS_EXTENDED;
public const int BLOCK_CODE_TAI_THAM;
public const int BLOCK_CODE_VEDIC_EXTENSIONS;
public const int BLOCK_CODE_LISU;
public const int BLOCK_CODE_BAMUM;
public const int BLOCK_CODE_COMMON_INDIC_NUMBER_FORMS;
public const int BLOCK_CODE_DEVANAGARI_EXTENDED;
public const int BLOCK_CODE_HANGUL_JAMO_EXTENDED_A;
public const int BLOCK_CODE_JAVANESE;
public const int BLOCK_CODE_MYANMAR_EXTENDED_A;
public const int BLOCK_CODE_TAI_VIET;
public const int BLOCK_CODE_MEETEI_MAYEK;
public const int BLOCK_CODE_HANGUL_JAMO_EXTENDED_B;
public const int BLOCK_CODE_IMPERIAL_ARAMAIC;
public const int BLOCK_CODE_OLD_SOUTH_ARABIAN;
public const int BLOCK_CODE_AVESTAN;
public const int BLOCK_CODE_INSCRIPTIONAL_PARTHIAN;
public const int BLOCK_CODE_INSCRIPTIONAL_PAHLAVI;
public const int BLOCK_CODE_OLD_TURKIC;
public const int BLOCK_CODE_RUMI_NUMERAL_SYMBOLS;
public const int BLOCK_CODE_KAITHI;
public const int BLOCK_CODE_EGYPTIAN_HIEROGLYPHS;
public const int BLOCK_CODE_ENCLOSED_ALPHANUMERIC_SUPPLEMENT;
public const int BLOCK_CODE_ENCLOSED_IDEOGRAPHIC_SUPPLEMENT;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_C;
public const int BLOCK_CODE_MANDAIC;
public const int BLOCK_CODE_BATAK;
public const int BLOCK_CODE_ETHIOPIC_EXTENDED_A;
public const int BLOCK_CODE_BRAHMI;
public const int BLOCK_CODE_BAMUM_SUPPLEMENT;
public const int BLOCK_CODE_KANA_SUPPLEMENT;
public const int BLOCK_CODE_PLAYING_CARDS;
public const int BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_PICTOGRAPHS;
public const int BLOCK_CODE_EMOTICONS;
public const int BLOCK_CODE_TRANSPORT_AND_MAP_SYMBOLS;
public const int BLOCK_CODE_ALCHEMICAL_SYMBOLS;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_D;
public const int BLOCK_CODE_ARABIC_EXTENDED_A;
public const int BLOCK_CODE_ARABIC_MATHEMATICAL_ALPHABETIC_SYMBOLS;
public const int BLOCK_CODE_CHAKMA;
public const int BLOCK_CODE_MEETEI_MAYEK_EXTENSIONS;
public const int BLOCK_CODE_MEROITIC_CURSIVE;
public const int BLOCK_CODE_MEROITIC_HIEROGLYPHS;
public const int BLOCK_CODE_MIAO;
public const int BLOCK_CODE_SHARADA;
public const int BLOCK_CODE_SORA_SOMPENG;
public const int BLOCK_CODE_SUNDANESE_SUPPLEMENT;
public const int BLOCK_CODE_TAKRI;
public const int BLOCK_CODE_BASSA_VAH;
public const int BLOCK_CODE_CAUCASIAN_ALBANIAN;
public const int BLOCK_CODE_COPTIC_EPACT_NUMBERS;
public const int BLOCK_CODE_COMBINING_DIACRITICAL_MARKS_EXTENDED;
public const int BLOCK_CODE_DUPLOYAN;
public const int BLOCK_CODE_ELBASAN;
public const int BLOCK_CODE_GEOMETRIC_SHAPES_EXTENDED;
public const int BLOCK_CODE_GRANTHA;
public const int BLOCK_CODE_KHOJKI;
public const int BLOCK_CODE_KHUDAWADI;
public const int BLOCK_CODE_LATIN_EXTENDED_E;
public const int BLOCK_CODE_LINEAR_A;
public const int BLOCK_CODE_MAHAJANI;
public const int BLOCK_CODE_MANICHAEAN;
public const int BLOCK_CODE_MENDE_KIKAKUI;
public const int BLOCK_CODE_MODI;
public const int BLOCK_CODE_MRO;
public const int BLOCK_CODE_MYANMAR_EXTENDED_B;
public const int BLOCK_CODE_NABATAEAN;
public const int BLOCK_CODE_OLD_NORTH_ARABIAN;
public const int BLOCK_CODE_OLD_PERMIC;
public const int BLOCK_CODE_ORNAMENTAL_DINGBATS;
public const int BLOCK_CODE_PAHAWH_HMONG;
public const int BLOCK_CODE_PALMYRENE;
public const int BLOCK_CODE_PAU_CIN_HAU;
public const int BLOCK_CODE_PSALTER_PAHLAVI;
public const int BLOCK_CODE_SHORTHAND_FORMAT_CONTROLS;
public const int BLOCK_CODE_SIDDHAM;
public const int BLOCK_CODE_SINHALA_ARCHAIC_NUMBERS;
public const int BLOCK_CODE_SUPPLEMENTAL_ARROWS_C;
public const int BLOCK_CODE_TIRHUTA;
public const int BLOCK_CODE_WARANG_CITI;
public const int BLOCK_CODE_COUNT;
public const int BLOCK_CODE_INVALID_CODE;
public const int BPT_NONE;
public const int BPT_OPEN;
public const int BPT_CLOSE;
public const int BPT_COUNT;
public const int EA_NEUTRAL;
public const int EA_AMBIGUOUS;
public const int EA_HALFWIDTH;
public const int EA_FULLWIDTH;
public const int EA_NARROW;
public const int EA_WIDE;
public const int EA_COUNT;
public const int UNICODE_CHAR_NAME;
public const int UNICODE_10_CHAR_NAME;
public const int EXTENDED_CHAR_NAME;
public const int CHAR_NAME_ALIAS;
public const int CHAR_NAME_CHOICE_COUNT;
public const int SHORT_PROPERTY_NAME;
public const int LONG_PROPERTY_NAME;
public const int PROPERTY_NAME_CHOICE_COUNT;
public const int DT_NONE;
public const int DT_CANONICAL;
public const int DT_COMPAT;
public const int DT_CIRCLE;
public const int DT_FINAL;
public const int DT_FONT;
public const int DT_FRACTION;
public const int DT_INITIAL;
public const int DT_ISOLATED;
public const int DT_MEDIAL;
public const int DT_NARROW;
public const int DT_NOBREAK;
public const int DT_SMALL;
public const int DT_SQUARE;
public const int DT_SUB;
public const int DT_SUPER;
public const int DT_VERTICAL;
public const int DT_WIDE;
public const int DT_COUNT;
public const int JT_NON_JOINING;
public const int JT_JOIN_CAUSING;
public const int JT_DUAL_JOINING;
public const int JT_LEFT_JOINING;
public const int JT_RIGHT_JOINING;
public const int JT_TRANSPARENT;
public const int JT_COUNT;
public const int JG_NO_JOINING_GROUP;
public const int JG_AIN;
public const int JG_ALAPH;
public const int JG_ALEF;
public const int JG_BEH;
public const int JG_BETH;
public const int JG_DAL;
public const int JG_DALATH_RISH;
public const int JG_E;
public const int JG_FEH;
public const int JG_FINAL_SEMKATH;
public const int JG_GAF;
public const int JG_GAMAL;
public const int JG_HAH;
public const int JG_TEH_MARBUTA_GOAL;
public const int JG_HAMZA_ON_HEH_GOAL;
public const int JG_HE;
public const int JG_HEH;
public const int JG_HEH_GOAL;
public const int JG_HETH;
public const int JG_KAF;
public const int JG_KAPH;
public const int JG_KNOTTED_HEH;
public const int JG_LAM;
public const int JG_LAMADH;
public const int JG_MEEM;
public const int JG_MIM;
public const int JG_NOON;
public const int JG_NUN;
public const int JG_PE;
public const int JG_QAF;
public const int JG_QAPH;
public const int JG_REH;
public const int JG_REVERSED_PE;
public const int JG_SAD;
public const int JG_SADHE;
public const int JG_SEEN;
public const int JG_SEMKATH;
public const int JG_SHIN;
public const int JG_SWASH_KAF;
public const int JG_SYRIAC_WAW;
public const int JG_TAH;
public const int JG_TAW;
public const int JG_TEH_MARBUTA;
public const int JG_TETH;
public const int JG_WAW;
public const int JG_YEH;
public const int JG_YEH_BARREE;
public const int JG_YEH_WITH_TAIL;
public const int JG_YUDH;
public const int JG_YUDH_HE;
public const int JG_ZAIN;
public const int JG_FE;
public const int JG_KHAPH;
public const int JG_ZHAIN;
public const int JG_BURUSHASKI_YEH_BARREE;
public const int JG_FARSI_YEH;
public const int JG_NYA;
public const int JG_ROHINGYA_YEH;
public const int JG_MANICHAEAN_ALEPH;
public const int JG_MANICHAEAN_AYIN;
public const int JG_MANICHAEAN_BETH;
public const int JG_MANICHAEAN_DALETH;
public const int JG_MANICHAEAN_DHAMEDH;
public const int JG_MANICHAEAN_FIVE;
public const int JG_MANICHAEAN_GIMEL;
public const int JG_MANICHAEAN_HETH;
public const int JG_MANICHAEAN_HUNDRED;
public const int JG_MANICHAEAN_KAPH;
public const int JG_MANICHAEAN_LAMEDH;
public const int JG_MANICHAEAN_MEM;
public const int JG_MANICHAEAN_NUN;
public const int JG_MANICHAEAN_ONE;
public const int JG_MANICHAEAN_PE;
public const int JG_MANICHAEAN_QOPH;
public const int JG_MANICHAEAN_RESH;
public const int JG_MANICHAEAN_SADHE;
public const int JG_MANICHAEAN_SAMEKH;
public const int JG_MANICHAEAN_TAW;
public const int JG_MANICHAEAN_TEN;
public const int JG_MANICHAEAN_TETH;
public const int JG_MANICHAEAN_THAMEDH;
public const int JG_MANICHAEAN_TWENTY;
public const int JG_MANICHAEAN_WAW;
public const int JG_MANICHAEAN_YODH;
public const int JG_MANICHAEAN_ZAYIN;
public const int JG_STRAIGHT_WAW;
public const int JG_COUNT;
public const int GCB_OTHER;
public const int GCB_CONTROL;
public const int GCB_CR;
public const int GCB_EXTEND;
public const int GCB_L;
public const int GCB_LF;
public const int GCB_LV;
public const int GCB_LVT;
public const int GCB_T;
public const int GCB_V;
public const int GCB_SPACING_MARK;
public const int GCB_PREPEND;
public const int GCB_REGIONAL_INDICATOR;
public const int GCB_COUNT;
public const int WB_OTHER;
public const int WB_ALETTER;
public const int WB_FORMAT;
public const int WB_KATAKANA;
public const int WB_MIDLETTER;
public const int WB_MIDNUM;
public const int WB_NUMERIC;
public const int WB_EXTENDNUMLET;
public const int WB_CR;
public const int WB_EXTEND;
public const int WB_LF;
public const int WB_MIDNUMLET;
public const int WB_NEWLINE;
public const int WB_REGIONAL_INDICATOR;
public const int WB_HEBREW_LETTER;
public const int WB_SINGLE_QUOTE;
public const int WB_DOUBLE_QUOTE;
public const int WB_COUNT;
public const int SB_OTHER;
public const int SB_ATERM;
public const int SB_CLOSE;
public const int SB_FORMAT;
public const int SB_LOWER;
public const int SB_NUMERIC;
public const int SB_OLETTER;
public const int SB_SEP;
public const int SB_SP;
public const int SB_STERM;
public const int SB_UPPER;
public const int SB_CR;
public const int SB_EXTEND;
public const int SB_LF;
public const int SB_SCONTINUE;
public const int SB_COUNT;
public const int LB_UNKNOWN;
public const int LB_AMBIGUOUS;
public const int LB_ALPHABETIC;
public const int LB_BREAK_BOTH;
public const int LB_BREAK_AFTER;
public const int LB_BREAK_BEFORE;
public const int LB_MANDATORY_BREAK;
public const int LB_CONTINGENT_BREAK;
public const int LB_CLOSE_PUNCTUATION;
public const int LB_COMBINING_MARK;
public const int LB_CARRIAGE_RETURN;
public const int LB_EXCLAMATION;
public const int LB_GLUE;
public const int LB_HYPHEN;
public const int LB_IDEOGRAPHIC;
public const int LB_INSEPARABLE;
public const int LB_INSEPERABLE;
public const int LB_INFIX_NUMERIC;
public const int LB_LINE_FEED;
public const int LB_NONSTARTER;
public const int LB_NUMERIC;
public const int LB_OPEN_PUNCTUATION;
public const int LB_POSTFIX_NUMERIC;
public const int LB_PREFIX_NUMERIC;
public const int LB_QUOTATION;
public const int LB_COMPLEX_CONTEXT;
public const int LB_SURROGATE;
public const int LB_SPACE;
public const int LB_BREAK_SYMBOLS;
public const int LB_ZWSPACE;
public const int LB_NEXT_LINE;
public const int LB_WORD_JOINER;
public const int LB_H2;
public const int LB_H3;
public const int LB_JL;
public const int LB_JT;
public const int LB_JV;
public const int LB_CLOSE_PARENTHESIS;
public const int LB_CONDITIONAL_JAPANESE_STARTER;
public const int LB_HEBREW_LETTER;
public const int LB_REGIONAL_INDICATOR;
public const int LB_COUNT;
public const int NT_NONE;
public const int NT_DECIMAL;
public const int NT_DIGIT;
public const int NT_NUMERIC;
public const int NT_COUNT;
public const int HST_NOT_APPLICABLE;
public const int HST_LEADING_JAMO;
public const int HST_VOWEL_JAMO;
public const int HST_TRAILING_JAMO;
public const int HST_LV_SYLLABLE;
public const int HST_LVT_SYLLABLE;
public const int HST_COUNT;
public const int FOLD_CASE_DEFAULT;
public const int FOLD_CASE_EXCLUDE_SPECIAL_I;
/* Métodos */
public static function charAge(int|string `$codepoint`): ?array
public static function charDigitValue(int|string `$codepoint`): ?int
public static function charDirection(int|string `$codepoint`): ?int
public static function charFromName(string `$name`, int `$type` = `IntlChar::UNICODE_CHAR_NAME`): ?int
public static function charMirror(int|string `$codepoint`): int|string|null
public static function charName(int|string `$codepoint`, int `$type` = `IntlChar::UNICODE_CHAR_NAME`): ?string
public static function charType(int|string `$codepoint`): ?int
public static function chr(int|string `$codepoint`): ?string
public static function digit(int|string `$codepoint`, int `$base` = 10): int|false|null
public static function enumCharNames(
int|string `$start`,
int|string `$end`,
callable `$callback`,
int `$type` = `IntlChar::UNICODE_CHAR_NAME`
): bool
public static function enumCharTypes(callable `$callback`): void
public static function foldCase(int|string `$codepoint`, int `$options` = `IntlChar::FOLD_CASE_DEFAULT`): int|string|null
public static function forDigit(int `$digit`, int `$base` = 10): int
public static function getBidiPairedBracket(int|string `$codepoint`): int|string|null
public static function getBlockCode(int|string `$codepoint`): ?int
public static function getCombiningClass(int|string `$codepoint`): ?int
public static function getFC_NFKC_Closure(int|string `$codepoint`): string|false|null
public static function getIntPropertyMaxValue(int `$property`): int
public static function getIntPropertyMinValue(int `$property`): int
public static function getIntPropertyValue(int|string `$codepoint`, int `$property`): ?int
public static function getNumericValue(int|string `$codepoint`): ?float
public static function getPropertyEnum(string `$alias`): int
public static function getPropertyName(int `$property`, int `$type` = `IntlChar::LONG_PROPERTY_NAME`): string|false
public static function getPropertyValueEnum(int `$property`, string `$name`): int
public static function getPropertyValueName(int `$property`, int `$value`, int `$type` = `IntlChar::LONG_PROPERTY_NAME`): string|false
public static function getUnicodeVersion(): array
public static function hasBinaryProperty(int|string `$codepoint`, int `$property`): ?bool
public static function isalnum(int|string `$codepoint`): ?bool
public static function isalpha(int|string `$codepoint`): ?bool
public static function isbase(int|string `$codepoint`): ?bool
public static function isblank(int|string `$codepoint`): ?bool
public static function iscntrl(int|string `$codepoint`): ?bool
public static function isdefined(int|string `$codepoint`): ?bool
public static function isdigit(int|string `$codepoint`): ?bool
public static function isgraph(int|string `$codepoint`): ?bool
public static function isIDIgnorable(int|string `$codepoint`): ?bool
public static function isIDPart(int|string `$codepoint`): ?bool
public static function isIDStart(int|string `$codepoint`): ?bool
public static function isISOControl(int|string `$codepoint`): ?bool
public static function isJavaIDPart(int|string `$codepoint`): ?bool
public static function isJavaIDStart(int|string `$codepoint`): ?bool
public static function isJavaSpaceChar(int|string `$codepoint`): ?bool
public static function islower(int|string `$codepoint`): ?bool
public static function isMirrored(int|string `$codepoint`): ?bool
public static function isprint(int|string `$codepoint`): ?bool
public static function ispunct(int|string `$codepoint`): ?bool
public static function isspace(int|string `$codepoint`): ?bool
public static function istitle(int|string `$codepoint`): ?bool
public static function isUAlphabetic(int|string `$codepoint`): ?bool
public static function isULowercase(int|string `$codepoint`): ?bool
public static function isupper(int|string `$codepoint`): ?bool
public static function isUUppercase(int|string `$codepoint`): ?bool
public static function isUWhiteSpace(int|string `$codepoint`): ?bool
public static function isWhitespace(int|string `$codepoint`): ?bool
public static function isxdigit(int|string `$codepoint`): ?bool
public static function ord(int|string `$character`): ?int
public static function tolower(int|string `$codepoint`): int|string|null
public static function totitle(int|string `$codepoint`): int|string|null
public static function toupper(int|string `$codepoint`): int|string|null
}

## Constantes predefinidas

`IntlChar::UNICODE_VERSION` string

`IntlChar::CODEPOINT_MIN` int

`IntlChar::CODEPOINT_MAX` int

`IntlChar::NO_NUMERIC_VALUE` int

  Valor especial retornado por IntlChar::getNumericValue() quando nenhum valor numérico estiver difinido para um ponto de código.

`IntlChar::PROPERTY_ALPHABETIC` int

`IntlChar::PROPERTY_BINARY_START` int

`IntlChar::PROPERTY_ASCII_HEX_DIGIT` int

`IntlChar::PROPERTY_BIDI_CONTROL` int

`IntlChar::PROPERTY_BIDI_MIRRORED` int

`IntlChar::PROPERTY_DASH` int

`IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT` int

`IntlChar::PROPERTY_DEPRECATED` int

`IntlChar::PROPERTY_DIACRITIC` int

`IntlChar::PROPERTY_EXTENDER` int

`IntlChar::PROPERTY_FULL_COMPOSITION_EXCLUSION` int

`IntlChar::PROPERTY_GRAPHEME_BASE` int

`IntlChar::PROPERTY_GRAPHEME_EXTEND` int

`IntlChar::PROPERTY_GRAPHEME_LINK` int

`IntlChar::PROPERTY_HEX_DIGIT` int

`IntlChar::PROPERTY_HYPHEN` int

`IntlChar::PROPERTY_ID_CONTINUE` int

`IntlChar::PROPERTY_ID_START` int

`IntlChar::PROPERTY_IDEOGRAPHIC` int

`IntlChar::PROPERTY_IDS_BINARY_OPERATOR` int

`IntlChar::PROPERTY_IDS_TRINARY_OPERATOR` int

`IntlChar::PROPERTY_IDS_UNARY_OPERATOR` int
  Para determinação programática de Sequências de Descrição Ideográficas. Disponível a partir do PHP 8.4.0.
`IntlChar::PROPERTY_ID_COMPAT_MATH_START` int
  Usada em perfil de identificação matemática no UAX 31. Disponível a partir do PHP 8.4.0.
`IntlChar::PROPERTY_ID_COMPAT_MATH_CONTINUE` int
  Usada em perfil de identificação matemática no UAX 31. Disponível a partir do PHP 8.4.0.
`IntlChar::PROPERTY_JOIN_CONTROL` int

`IntlChar::PROPERTY_LOGICAL_ORDER_EXCEPTION` int

`IntlChar::PROPERTY_LOWERCASE` int

`IntlChar::PROPERTY_MATH` int

`IntlChar::PROPERTY_NONCHARACTER_CODE_POINT` int

`IntlChar::PROPERTY_QUOTATION_MARK` int

`IntlChar::PROPERTY_RADICAL` int

`IntlChar::PROPERTY_SOFT_DOTTED` int

`IntlChar::PROPERTY_TERMINAL_PUNCTUATION` int

`IntlChar::PROPERTY_UNIFIED_IDEOGRAPH` int

`IntlChar::PROPERTY_UPPERCASE` int

`IntlChar::PROPERTY_WHITE_SPACE` int

`IntlChar::PROPERTY_XID_CONTINUE` int

`IntlChar::PROPERTY_XID_START` int

`IntlChar::PROPERTY_CASE_SENSITIVE` int

`IntlChar::PROPERTY_S_TERM` int

`IntlChar::PROPERTY_VARIATION_SELECTOR` int

`IntlChar::PROPERTY_NFD_INERT` int

`IntlChar::PROPERTY_NFKD_INERT` int

`IntlChar::PROPERTY_NFC_INERT` int

`IntlChar::PROPERTY_NFKC_INERT` int

`IntlChar::PROPERTY_SEGMENT_STARTER` int

`IntlChar::PROPERTY_PATTERN_SYNTAX` int

`IntlChar::PROPERTY_PATTERN_WHITE_SPACE` int

`IntlChar::PROPERTY_POSIX_ALNUM` int

`IntlChar::PROPERTY_POSIX_BLANK` int

`IntlChar::PROPERTY_POSIX_GRAPH` int

`IntlChar::PROPERTY_POSIX_PRINT` int

`IntlChar::PROPERTY_POSIX_XDIGIT` int

`IntlChar::PROPERTY_CASED` int

`IntlChar::PROPERTY_CASE_IGNORABLE` int

`IntlChar::PROPERTY_CHANGES_WHEN_LOWERCASED` int

`IntlChar::PROPERTY_CHANGES_WHEN_UPPERCASED` int

`IntlChar::PROPERTY_CHANGES_WHEN_TITLECASED` int

`IntlChar::PROPERTY_CHANGES_WHEN_CASEFOLDED` int

`IntlChar::PROPERTY_CHANGES_WHEN_CASEMAPPED` int

`IntlChar::PROPERTY_CHANGES_WHEN_NFKC_CASEFOLDED` int

`IntlChar::PROPERTY_BINARY_LIMIT` int

`IntlChar::PROPERTY_BIDI_CLASS` int

`IntlChar::PROPERTY_INT_START` int

`IntlChar::PROPERTY_BLOCK` int

`IntlChar::PROPERTY_CANONICAL_COMBINING_CLASS` int

`IntlChar::PROPERTY_DECOMPOSITION_TYPE` int

`IntlChar::PROPERTY_EAST_ASIAN_WIDTH` int

`IntlChar::PROPERTY_GENERAL_CATEGORY` int

`IntlChar::PROPERTY_JOINING_GROUP` int

`IntlChar::PROPERTY_JOINING_TYPE` int

`IntlChar::PROPERTY_LINE_BREAK` int

`IntlChar::PROPERTY_NUMERIC_TYPE` int

`IntlChar::PROPERTY_SCRIPT` int

`IntlChar::PROPERTY_HANGUL_SYLLABLE_TYPE` int

`IntlChar::PROPERTY_NFD_QUICK_CHECK` int

`IntlChar::PROPERTY_NFKD_QUICK_CHECK` int

`IntlChar::PROPERTY_NFC_QUICK_CHECK` int

`IntlChar::PROPERTY_NFKC_QUICK_CHECK` int

`IntlChar::PROPERTY_LEAD_CANONICAL_COMBINING_CLASS` int

`IntlChar::PROPERTY_TRAIL_CANONICAL_COMBINING_CLASS` int

`IntlChar::PROPERTY_GRAPHEME_CLUSTER_BREAK` int

`IntlChar::PROPERTY_SENTENCE_BREAK` int

`IntlChar::PROPERTY_WORD_BREAK` int

`IntlChar::PROPERTY_BIDI_PAIRED_BRACKET_TYPE` int

`IntlChar::PROPERTY_INT_LIMIT` int

`IntlChar::PROPERTY_GENERAL_CATEGORY_MASK` int

`IntlChar::PROPERTY_MASK_START` int

`IntlChar::PROPERTY_MASK_LIMIT` int

`IntlChar::PROPERTY_NUMERIC_VALUE` int

`IntlChar::PROPERTY_DOUBLE_START` int

`IntlChar::PROPERTY_DOUBLE_LIMIT` int

`IntlChar::PROPERTY_AGE` int

`IntlChar::PROPERTY_STRING_START` int

`IntlChar::PROPERTY_BIDI_MIRRORING_GLYPH` int

`IntlChar::PROPERTY_CASE_FOLDING` int

`IntlChar::PROPERTY_ISO_COMMENT` int

`IntlChar::PROPERTY_LOWERCASE_MAPPING` int

`IntlChar::PROPERTY_NAME` int

`IntlChar::PROPERTY_SIMPLE_CASE_FOLDING` int

`IntlChar::PROPERTY_SIMPLE_LOWERCASE_MAPPING` int

`IntlChar::PROPERTY_SIMPLE_TITLECASE_MAPPING` int

`IntlChar::PROPERTY_SIMPLE_UPPERCASE_MAPPING` int

`IntlChar::PROPERTY_TITLECASE_MAPPING` int

`IntlChar::PROPERTY_UNICODE_1_NAME` int

`IntlChar::PROPERTY_UPPERCASE_MAPPING` int

`IntlChar::PROPERTY_BIDI_PAIRED_BRACKET` int

`IntlChar::PROPERTY_STRING_LIMIT` int

`IntlChar::PROPERTY_SCRIPT_EXTENSIONS` int

`IntlChar::PROPERTY_OTHER_PROPERTY_START` int

`IntlChar::PROPERTY_OTHER_PROPERTY_LIMIT` int

`IntlChar::PROPERTY_INVALID_CODE` int

`IntlChar::CHAR_CATEGORY_UNASSIGNED` int

`IntlChar::CHAR_CATEGORY_GENERAL_OTHER_TYPES` int

`IntlChar::CHAR_CATEGORY_UPPERCASE_LETTER` int

`IntlChar::CHAR_CATEGORY_LOWERCASE_LETTER` int

`IntlChar::CHAR_CATEGORY_TITLECASE_LETTER` int

`IntlChar::CHAR_CATEGORY_MODIFIER_LETTER` int

`IntlChar::CHAR_CATEGORY_OTHER_LETTER` int

`IntlChar::CHAR_CATEGORY_NON_SPACING_MARK` int

`IntlChar::CHAR_CATEGORY_ENCLOSING_MARK` int

`IntlChar::CHAR_CATEGORY_COMBINING_SPACING_MARK` int

`IntlChar::CHAR_CATEGORY_DECIMAL_DIGIT_NUMBER` int

`IntlChar::CHAR_CATEGORY_LETTER_NUMBER` int

`IntlChar::CHAR_CATEGORY_OTHER_NUMBER` int

`IntlChar::CHAR_CATEGORY_SPACE_SEPARATOR` int

`IntlChar::CHAR_CATEGORY_LINE_SEPARATOR` int

`IntlChar::CHAR_CATEGORY_PARAGRAPH_SEPARATOR` int

`IntlChar::CHAR_CATEGORY_CONTROL_CHAR` int

`IntlChar::CHAR_CATEGORY_FORMAT_CHAR` int

`IntlChar::CHAR_CATEGORY_PRIVATE_USE_CHAR` int

`IntlChar::CHAR_CATEGORY_SURROGATE` int

`IntlChar::CHAR_CATEGORY_DASH_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_START_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_END_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_CONNECTOR_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_OTHER_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_MATH_SYMBOL` int

`IntlChar::CHAR_CATEGORY_CURRENCY_SYMBOL` int

`IntlChar::CHAR_CATEGORY_MODIFIER_SYMBOL` int

`IntlChar::CHAR_CATEGORY_OTHER_SYMBOL` int

`IntlChar::CHAR_CATEGORY_INITIAL_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_FINAL_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_CHAR_CATEGORY_COUNT` int

`IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT` int

`IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER` int

`IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_SEPARATOR` int

`IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_TERMINATOR` int

`IntlChar::CHAR_DIRECTION_ARABIC_NUMBER` int

`IntlChar::CHAR_DIRECTION_COMMON_NUMBER_SEPARATOR` int

`IntlChar::CHAR_DIRECTION_BLOCK_SEPARATOR` int

`IntlChar::CHAR_DIRECTION_SEGMENT_SEPARATOR` int

`IntlChar::CHAR_DIRECTION_WHITE_SPACE_NEUTRAL` int

`IntlChar::CHAR_DIRECTION_OTHER_NEUTRAL` int

`IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_EMBEDDING` int

`IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_OVERRIDE` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_ARABIC` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_EMBEDDING` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_OVERRIDE` int

`IntlChar::CHAR_DIRECTION_POP_DIRECTIONAL_FORMAT` int

`IntlChar::CHAR_DIRECTION_DIR_NON_SPACING_MARK` int

`IntlChar::CHAR_DIRECTION_BOUNDARY_NEUTRAL` int

`IntlChar::CHAR_DIRECTION_FIRST_STRONG_ISOLATE` int

`IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_ISOLATE` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_ISOLATE` int

`IntlChar::CHAR_DIRECTION_POP_DIRECTIONAL_ISOLATE` int

`IntlChar::CHAR_DIRECTION_CHAR_DIRECTION_COUNT` int

`IntlChar::BLOCK_CODE_NO_BLOCK` int

`IntlChar::BLOCK_CODE_BASIC_LATIN` int

`IntlChar::BLOCK_CODE_LATIN_1_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_A` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_B` int

`IntlChar::BLOCK_CODE_IPA_EXTENSIONS` int

`IntlChar::BLOCK_CODE_SPACING_MODIFIER_LETTERS` int

`IntlChar::BLOCK_CODE_COMBINING_DIACRITICAL_MARKS` int

`IntlChar::BLOCK_CODE_GREEK` int

`IntlChar::BLOCK_CODE_CYRILLIC` int

`IntlChar::BLOCK_CODE_ARMENIAN` int

`IntlChar::BLOCK_CODE_HEBREW` int

`IntlChar::BLOCK_CODE_ARABIC` int

`IntlChar::BLOCK_CODE_SYRIAC` int

`IntlChar::BLOCK_CODE_THAANA` int

`IntlChar::BLOCK_CODE_DEVANAGARI` int

`IntlChar::BLOCK_CODE_BENGALI` int

`IntlChar::BLOCK_CODE_GURMUKHI` int

`IntlChar::BLOCK_CODE_GUJARATI` int

`IntlChar::BLOCK_CODE_ORIYA` int

`IntlChar::BLOCK_CODE_TAMIL` int

`IntlChar::BLOCK_CODE_TELUGU` int

`IntlChar::BLOCK_CODE_KANNADA` int

`IntlChar::BLOCK_CODE_MALAYALAM` int

`IntlChar::BLOCK_CODE_SINHALA` int

`IntlChar::BLOCK_CODE_THAI` int

`IntlChar::BLOCK_CODE_LAO` int

`IntlChar::BLOCK_CODE_TIBETAN` int

`IntlChar::BLOCK_CODE_MYANMAR` int

`IntlChar::BLOCK_CODE_GEORGIAN` int

`IntlChar::BLOCK_CODE_HANGUL_JAMO` int

`IntlChar::BLOCK_CODE_ETHIOPIC` int

`IntlChar::BLOCK_CODE_CHEROKEE` int

`IntlChar::BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS` int

`IntlChar::BLOCK_CODE_OGHAM` int

`IntlChar::BLOCK_CODE_RUNIC` int

`IntlChar::BLOCK_CODE_KHMER` int

`IntlChar::BLOCK_CODE_MONGOLIAN` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_ADDITIONAL` int

`IntlChar::BLOCK_CODE_GREEK_EXTENDED` int

`IntlChar::BLOCK_CODE_GENERAL_PUNCTUATION` int

`IntlChar::BLOCK_CODE_SUPERSCRIPTS_AND_SUBSCRIPTS` int

`IntlChar::BLOCK_CODE_CURRENCY_SYMBOLS` int

`IntlChar::BLOCK_CODE_COMBINING_MARKS_FOR_SYMBOLS` int

`IntlChar::BLOCK_CODE_LETTERLIKE_SYMBOLS` int

`IntlChar::BLOCK_CODE_NUMBER_FORMS` int

`IntlChar::BLOCK_CODE_ARROWS` int

`IntlChar::BLOCK_CODE_MATHEMATICAL_OPERATORS` int

`IntlChar::BLOCK_CODE_MISCELLANEOUS_TECHNICAL` int

`IntlChar::BLOCK_CODE_CONTROL_PICTURES` int

`IntlChar::BLOCK_CODE_OPTICAL_CHARACTER_RECOGNITION` int

`IntlChar::BLOCK_CODE_ENCLOSED_ALPHANUMERICS` int

`IntlChar::BLOCK_CODE_BOX_DRAWING` int

`IntlChar::BLOCK_CODE_BLOCK_ELEMENTS` int

`IntlChar::BLOCK_CODE_GEOMETRIC_SHAPES` int

`IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS` int

`IntlChar::BLOCK_CODE_DINGBATS` int

`IntlChar::BLOCK_CODE_BRAILLE_PATTERNS` int

`IntlChar::BLOCK_CODE_CJK_RADICALS_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_KANGXI_RADICALS` int

`IntlChar::BLOCK_CODE_IDEOGRAPHIC_DESCRIPTION_CHARACTERS` int

`IntlChar::BLOCK_CODE_CJK_SYMBOLS_AND_PUNCTUATION` int

`IntlChar::BLOCK_CODE_HIRAGANA` int

`IntlChar::BLOCK_CODE_KATAKANA` int

`IntlChar::BLOCK_CODE_BOPOMOFO` int

`IntlChar::BLOCK_CODE_HANGUL_COMPATIBILITY_JAMO` int

`IntlChar::BLOCK_CODE_KANBUN` int

`IntlChar::BLOCK_CODE_BOPOMOFO_EXTENDED` int

`IntlChar::BLOCK_CODE_ENCLOSED_CJK_LETTERS_AND_MONTHS` int

`IntlChar::BLOCK_CODE_CJK_COMPATIBILITY` int

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_A` int

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS` int

`IntlChar::BLOCK_CODE_YI_SYLLABLES` int

`IntlChar::BLOCK_CODE_YI_RADICALS` int

`IntlChar::BLOCK_CODE_HANGUL_SYLLABLES` int

`IntlChar::BLOCK_CODE_HIGH_SURROGATES` int

`IntlChar::BLOCK_CODE_HIGH_PRIVATE_USE_SURROGATES` int

`IntlChar::BLOCK_CODE_LOW_SURROGATES` int

`IntlChar::BLOCK_CODE_PRIVATE_USE_AREA` int

`IntlChar::BLOCK_CODE_PRIVATE_USE` int

`IntlChar::BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS` int

`IntlChar::BLOCK_CODE_ALPHABETIC_PRESENTATION_FORMS` int

`IntlChar::BLOCK_CODE_ARABIC_PRESENTATION_FORMS_A` int

`IntlChar::BLOCK_CODE_COMBINING_HALF_MARKS` int

`IntlChar::BLOCK_CODE_CJK_COMPATIBILITY_FORMS` int

`IntlChar::BLOCK_CODE_SMALL_FORM_VARIANTS` int

`IntlChar::BLOCK_CODE_ARABIC_PRESENTATION_FORMS_B` int

`IntlChar::BLOCK_CODE_SPECIALS` int

`IntlChar::BLOCK_CODE_HALFWIDTH_AND_FULLWIDTH_FORMS` int

`IntlChar::BLOCK_CODE_OLD_ITALIC` int

`IntlChar::BLOCK_CODE_GOTHIC` int

`IntlChar::BLOCK_CODE_DESERET` int

`IntlChar::BLOCK_CODE_BYZANTINE_MUSICAL_SYMBOLS` int

`IntlChar::BLOCK_CODE_MUSICAL_SYMBOLS` int

`IntlChar::BLOCK_CODE_MATHEMATICAL_ALPHANUMERIC_SYMBOLS` int

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_B` int

`IntlChar::BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_TAGS` int

`IntlChar::BLOCK_CODE_CYRILLIC_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_CYRILLIC_SUPPLEMENTARY` int

`IntlChar::BLOCK_CODE_TAGALOG` int

`IntlChar::BLOCK_CODE_HANUNOO` int

`IntlChar::BLOCK_CODE_BUHID` int

`IntlChar::BLOCK_CODE_TAGBANWA` int

`IntlChar::BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_A` int

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_ARROWS_A` int

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_ARROWS_B` int

`IntlChar::BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_B` int

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_MATHEMATICAL_OPERATORS` int

`IntlChar::BLOCK_CODE_KATAKANA_PHONETIC_EXTENSIONS` int

`IntlChar::BLOCK_CODE_VARIATION_SELECTORS` int

`IntlChar::BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_A` int

`IntlChar::BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_B` int

`IntlChar::BLOCK_CODE_LIMBU` int

`IntlChar::BLOCK_CODE_TAI_LE` int

`IntlChar::BLOCK_CODE_KHMER_SYMBOLS` int

`IntlChar::BLOCK_CODE_PHONETIC_EXTENSIONS` int

`IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_ARROWS` int

`IntlChar::BLOCK_CODE_YIJING_HEXAGRAM_SYMBOLS` int

`IntlChar::BLOCK_CODE_LINEAR_B_SYLLABARY` int

`IntlChar::BLOCK_CODE_LINEAR_B_IDEOGRAMS` int

`IntlChar::BLOCK_CODE_AEGEAN_NUMBERS` int

`IntlChar::BLOCK_CODE_UGARITIC` int

`IntlChar::BLOCK_CODE_SHAVIAN` int

`IntlChar::BLOCK_CODE_OSMANYA` int

`IntlChar::BLOCK_CODE_CYPRIOT_SYLLABARY` int

`IntlChar::BLOCK_CODE_TAI_XUAN_JING_SYMBOLS` int

`IntlChar::BLOCK_CODE_VARIATION_SELECTORS_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_ANCIENT_GREEK_MUSICAL_NOTATION` int

`IntlChar::BLOCK_CODE_ANCIENT_GREEK_NUMBERS` int

`IntlChar::BLOCK_CODE_ARABIC_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_BUGINESE` int

`IntlChar::BLOCK_CODE_CJK_STROKES` int

`IntlChar::BLOCK_CODE_COMBINING_DIACRITICAL_MARKS_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_COPTIC` int

`IntlChar::BLOCK_CODE_ETHIOPIC_EXTENDED` int

`IntlChar::BLOCK_CODE_ETHIOPIC_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_GEORGIAN_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_GLAGOLITIC` int

`IntlChar::BLOCK_CODE_KHAROSHTHI` int

`IntlChar::BLOCK_CODE_MODIFIER_TONE_LETTERS` int

`IntlChar::BLOCK_CODE_NEW_TAI_LUE` int

`IntlChar::BLOCK_CODE_OLD_PERSIAN` int

`IntlChar::BLOCK_CODE_PHONETIC_EXTENSIONS_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_PUNCTUATION` int

`IntlChar::BLOCK_CODE_SYLOTI_NAGRI` int

`IntlChar::BLOCK_CODE_TIFINAGH` int

`IntlChar::BLOCK_CODE_VERTICAL_FORMS` int

`IntlChar::BLOCK_CODE_NKO` int

`IntlChar::BLOCK_CODE_BALINESE` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_C` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_D` int

`IntlChar::BLOCK_CODE_PHAGS_PA` int

`IntlChar::BLOCK_CODE_PHOENICIAN` int

`IntlChar::BLOCK_CODE_CUNEIFORM` int

`IntlChar::BLOCK_CODE_CUNEIFORM_NUMBERS_AND_PUNCTUATION` int

`IntlChar::BLOCK_CODE_COUNTING_ROD_NUMERALS` int

`IntlChar::BLOCK_CODE_SUNDANESE` int

`IntlChar::BLOCK_CODE_LEPCHA` int

`IntlChar::BLOCK_CODE_OL_CHIKI` int

`IntlChar::BLOCK_CODE_CYRILLIC_EXTENDED_A` int

`IntlChar::BLOCK_CODE_VAI` int

`IntlChar::BLOCK_CODE_CYRILLIC_EXTENDED_B` int

`IntlChar::BLOCK_CODE_SAURASHTRA` int

`IntlChar::BLOCK_CODE_KAYAH_LI` int

`IntlChar::BLOCK_CODE_REJANG` int

`IntlChar::BLOCK_CODE_CHAM` int

`IntlChar::BLOCK_CODE_ANCIENT_SYMBOLS` int

`IntlChar::BLOCK_CODE_PHAISTOS_DISC` int

`IntlChar::BLOCK_CODE_LYCIAN` int

`IntlChar::BLOCK_CODE_CARIAN` int

`IntlChar::BLOCK_CODE_LYDIAN` int

`IntlChar::BLOCK_CODE_MAHJONG_TILES` int

`IntlChar::BLOCK_CODE_DOMINO_TILES` int

`IntlChar::BLOCK_CODE_SAMARITAN` int

`IntlChar::BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS_EXTENDED` int

`IntlChar::BLOCK_CODE_TAI_THAM` int

`IntlChar::BLOCK_CODE_VEDIC_EXTENSIONS` int

`IntlChar::BLOCK_CODE_LISU` int

`IntlChar::BLOCK_CODE_BAMUM` int

`IntlChar::BLOCK_CODE_COMMON_INDIC_NUMBER_FORMS` int

`IntlChar::BLOCK_CODE_DEVANAGARI_EXTENDED` int

`IntlChar::BLOCK_CODE_HANGUL_JAMO_EXTENDED_A` int

`IntlChar::BLOCK_CODE_JAVANESE` int

`IntlChar::BLOCK_CODE_MYANMAR_EXTENDED_A` int

`IntlChar::BLOCK_CODE_TAI_VIET` int

`IntlChar::BLOCK_CODE_MEETEI_MAYEK` int

`IntlChar::BLOCK_CODE_HANGUL_JAMO_EXTENDED_B` int

`IntlChar::BLOCK_CODE_IMPERIAL_ARAMAIC` int

`IntlChar::BLOCK_CODE_OLD_SOUTH_ARABIAN` int

`IntlChar::BLOCK_CODE_AVESTAN` int

`IntlChar::BLOCK_CODE_INSCRIPTIONAL_PARTHIAN` int

`IntlChar::BLOCK_CODE_INSCRIPTIONAL_PAHLAVI` int

`IntlChar::BLOCK_CODE_OLD_TURKIC` int

`IntlChar::BLOCK_CODE_RUMI_NUMERAL_SYMBOLS` int

`IntlChar::BLOCK_CODE_KAITHI` int

`IntlChar::BLOCK_CODE_EGYPTIAN_HIEROGLYPHS` int

`IntlChar::BLOCK_CODE_ENCLOSED_ALPHANUMERIC_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_ENCLOSED_IDEOGRAPHIC_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_C` int

`IntlChar::BLOCK_CODE_MANDAIC` int

`IntlChar::BLOCK_CODE_BATAK` int

`IntlChar::BLOCK_CODE_ETHIOPIC_EXTENDED_A` int

`IntlChar::BLOCK_CODE_BRAHMI` int

`IntlChar::BLOCK_CODE_BAMUM_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_KANA_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_PLAYING_CARDS` int

`IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_PICTOGRAPHS` int

`IntlChar::BLOCK_CODE_EMOTICONS` int

`IntlChar::BLOCK_CODE_TRANSPORT_AND_MAP_SYMBOLS` int

`IntlChar::BLOCK_CODE_ALCHEMICAL_SYMBOLS` int

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_D` int

`IntlChar::BLOCK_CODE_ARABIC_EXTENDED_A` int

`IntlChar::BLOCK_CODE_ARABIC_MATHEMATICAL_ALPHABETIC_SYMBOLS` int

`IntlChar::BLOCK_CODE_CHAKMA` int

`IntlChar::BLOCK_CODE_MEETEI_MAYEK_EXTENSIONS` int

`IntlChar::BLOCK_CODE_MEROITIC_CURSIVE` int

`IntlChar::BLOCK_CODE_MEROITIC_HIEROGLYPHS` int

`IntlChar::BLOCK_CODE_MIAO` int

`IntlChar::BLOCK_CODE_SHARADA` int

`IntlChar::BLOCK_CODE_SORA_SOMPENG` int

`IntlChar::BLOCK_CODE_SUNDANESE_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_TAKRI` int

`IntlChar::BLOCK_CODE_BASSA_VAH` int

`IntlChar::BLOCK_CODE_CAUCASIAN_ALBANIAN` int

`IntlChar::BLOCK_CODE_COPTIC_EPACT_NUMBERS` int

`IntlChar::BLOCK_CODE_COMBINING_DIACRITICAL_MARKS_EXTENDED` int

`IntlChar::BLOCK_CODE_DUPLOYAN` int

`IntlChar::BLOCK_CODE_ELBASAN` int

`IntlChar::BLOCK_CODE_GEOMETRIC_SHAPES_EXTENDED` int

`IntlChar::BLOCK_CODE_GRANTHA` int

`IntlChar::BLOCK_CODE_KHOJKI` int

`IntlChar::BLOCK_CODE_KHUDAWADI` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_E` int

`IntlChar::BLOCK_CODE_LINEAR_A` int

`IntlChar::BLOCK_CODE_MAHAJANI` int

`IntlChar::BLOCK_CODE_MANICHAEAN` int

`IntlChar::BLOCK_CODE_MENDE_KIKAKUI` int

`IntlChar::BLOCK_CODE_MODI` int

`IntlChar::BLOCK_CODE_MRO` int

`IntlChar::BLOCK_CODE_MYANMAR_EXTENDED_B` int

`IntlChar::BLOCK_CODE_NABATAEAN` int

`IntlChar::BLOCK_CODE_OLD_NORTH_ARABIAN` int

`IntlChar::BLOCK_CODE_OLD_PERMIC` int

`IntlChar::BLOCK_CODE_ORNAMENTAL_DINGBATS` int

`IntlChar::BLOCK_CODE_PAHAWH_HMONG` int

`IntlChar::BLOCK_CODE_PALMYRENE` int

`IntlChar::BLOCK_CODE_PAU_CIN_HAU` int

`IntlChar::BLOCK_CODE_PSALTER_PAHLAVI` int

`IntlChar::BLOCK_CODE_SHORTHAND_FORMAT_CONTROLS` int

`IntlChar::BLOCK_CODE_SIDDHAM` int

`IntlChar::BLOCK_CODE_SINHALA_ARCHAIC_NUMBERS` int

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_ARROWS_C` int

`IntlChar::BLOCK_CODE_TIRHUTA` int

`IntlChar::BLOCK_CODE_WARANG_CITI` int

`IntlChar::BLOCK_CODE_COUNT` int

`IntlChar::BLOCK_CODE_INVALID_CODE` int

`IntlChar::BPT_NONE` int

`IntlChar::BPT_OPEN` int

`IntlChar::BPT_CLOSE` int

`IntlChar::BPT_COUNT` int

`IntlChar::EA_NEUTRAL` int

`IntlChar::EA_AMBIGUOUS` int

`IntlChar::EA_HALFWIDTH` int

`IntlChar::EA_FULLWIDTH` int

`IntlChar::EA_NARROW` int

`IntlChar::EA_WIDE` int

`IntlChar::EA_COUNT` int

`IntlChar::UNICODE_CHAR_NAME` int

`IntlChar::UNICODE_10_CHAR_NAME` int

`IntlChar::EXTENDED_CHAR_NAME` int

`IntlChar::CHAR_NAME_ALIAS` int

`IntlChar::CHAR_NAME_CHOICE_COUNT` int

`IntlChar::SHORT_PROPERTY_NAME` int

`IntlChar::LONG_PROPERTY_NAME` int

`IntlChar::PROPERTY_NAME_CHOICE_COUNT` int

`IntlChar::DT_NONE` int

`IntlChar::DT_CANONICAL` int

`IntlChar::DT_COMPAT` int

`IntlChar::DT_CIRCLE` int

`IntlChar::DT_FINAL` int

`IntlChar::DT_FONT` int

`IntlChar::DT_FRACTION` int

`IntlChar::DT_INITIAL` int

`IntlChar::DT_ISOLATED` int

`IntlChar::DT_MEDIAL` int

`IntlChar::DT_NARROW` int

`IntlChar::DT_NOBREAK` int

`IntlChar::DT_SMALL` int

`IntlChar::DT_SQUARE` int

`IntlChar::DT_SUB` int

`IntlChar::DT_SUPER` int

`IntlChar::DT_VERTICAL` int

`IntlChar::DT_WIDE` int

`IntlChar::DT_COUNT` int

`IntlChar::JT_NON_JOINING` int

`IntlChar::JT_JOIN_CAUSING` int

`IntlChar::JT_DUAL_JOINING` int

`IntlChar::JT_LEFT_JOINING` int

`IntlChar::JT_RIGHT_JOINING` int

`IntlChar::JT_TRANSPARENT` int

`IntlChar::JT_COUNT` int

`IntlChar::JG_NO_JOINING_GROUP` int

`IntlChar::JG_AIN` int

`IntlChar::JG_ALAPH` int

`IntlChar::JG_ALEF` int

`IntlChar::JG_BEH` int

`IntlChar::JG_BETH` int

`IntlChar::JG_DAL` int

`IntlChar::JG_DALATH_RISH` int

`IntlChar::JG_E` int

`IntlChar::JG_FEH` int

`IntlChar::JG_FINAL_SEMKATH` int

`IntlChar::JG_GAF` int

`IntlChar::JG_GAMAL` int

`IntlChar::JG_HAH` int

`IntlChar::JG_TEH_MARBUTA_GOAL` int

`IntlChar::JG_HAMZA_ON_HEH_GOAL` int

`IntlChar::JG_HE` int

`IntlChar::JG_HEH` int

`IntlChar::JG_HEH_GOAL` int

`IntlChar::JG_HETH` int

`IntlChar::JG_KAF` int

`IntlChar::JG_KAPH` int

`IntlChar::JG_KNOTTED_HEH` int

`IntlChar::JG_LAM` int

`IntlChar::JG_LAMADH` int

`IntlChar::JG_MEEM` int

`IntlChar::JG_MIM` int

`IntlChar::JG_NOON` int

`IntlChar::JG_NUN` int

`IntlChar::JG_PE` int

`IntlChar::JG_QAF` int

`IntlChar::JG_QAPH` int

`IntlChar::JG_REH` int

`IntlChar::JG_REVERSED_PE` int

`IntlChar::JG_SAD` int

`IntlChar::JG_SADHE` int

`IntlChar::JG_SEEN` int

`IntlChar::JG_SEMKATH` int

`IntlChar::JG_SHIN` int

`IntlChar::JG_SWASH_KAF` int

`IntlChar::JG_SYRIAC_WAW` int

`IntlChar::JG_TAH` int

`IntlChar::JG_TAW` int

`IntlChar::JG_TEH_MARBUTA` int

`IntlChar::JG_TETH` int

`IntlChar::JG_WAW` int

`IntlChar::JG_YEH` int

`IntlChar::JG_YEH_BARREE` int

`IntlChar::JG_YEH_WITH_TAIL` int

`IntlChar::JG_YUDH` int

`IntlChar::JG_YUDH_HE` int

`IntlChar::JG_ZAIN` int

`IntlChar::JG_FE` int

`IntlChar::JG_KHAPH` int

`IntlChar::JG_ZHAIN` int

`IntlChar::JG_BURUSHASKI_YEH_BARREE` int

`IntlChar::JG_FARSI_YEH` int

`IntlChar::JG_NYA` int

`IntlChar::JG_ROHINGYA_YEH` int

`IntlChar::JG_MANICHAEAN_ALEPH` int

`IntlChar::JG_MANICHAEAN_AYIN` int

`IntlChar::JG_MANICHAEAN_BETH` int

`IntlChar::JG_MANICHAEAN_DALETH` int

`IntlChar::JG_MANICHAEAN_DHAMEDH` int

`IntlChar::JG_MANICHAEAN_FIVE` int

`IntlChar::JG_MANICHAEAN_GIMEL` int

`IntlChar::JG_MANICHAEAN_HETH` int

`IntlChar::JG_MANICHAEAN_HUNDRED` int

`IntlChar::JG_MANICHAEAN_KAPH` int

`IntlChar::JG_MANICHAEAN_LAMEDH` int

`IntlChar::JG_MANICHAEAN_MEM` int

`IntlChar::JG_MANICHAEAN_NUN` int

`IntlChar::JG_MANICHAEAN_ONE` int

`IntlChar::JG_MANICHAEAN_PE` int

`IntlChar::JG_MANICHAEAN_QOPH` int

`IntlChar::JG_MANICHAEAN_RESH` int

`IntlChar::JG_MANICHAEAN_SADHE` int

`IntlChar::JG_MANICHAEAN_SAMEKH` int

`IntlChar::JG_MANICHAEAN_TAW` int

`IntlChar::JG_MANICHAEAN_TEN` int

`IntlChar::JG_MANICHAEAN_TETH` int

`IntlChar::JG_MANICHAEAN_THAMEDH` int

`IntlChar::JG_MANICHAEAN_TWENTY` int

`IntlChar::JG_MANICHAEAN_WAW` int

`IntlChar::JG_MANICHAEAN_YODH` int

`IntlChar::JG_MANICHAEAN_ZAYIN` int

`IntlChar::JG_STRAIGHT_WAW` int

`IntlChar::JG_COUNT` int

`IntlChar::GCB_OTHER` int

`IntlChar::GCB_CONTROL` int

`IntlChar::GCB_CR` int

`IntlChar::GCB_EXTEND` int

`IntlChar::GCB_L` int

`IntlChar::GCB_LF` int

`IntlChar::GCB_LV` int

`IntlChar::GCB_LVT` int

`IntlChar::GCB_T` int

`IntlChar::GCB_V` int

`IntlChar::GCB_SPACING_MARK` int

`IntlChar::GCB_PREPEND` int

`IntlChar::GCB_REGIONAL_INDICATOR` int

`IntlChar::GCB_COUNT` int

`IntlChar::WB_OTHER` int

`IntlChar::WB_ALETTER` int

`IntlChar::WB_FORMAT` int

`IntlChar::WB_KATAKANA` int

`IntlChar::WB_MIDLETTER` int

`IntlChar::WB_MIDNUM` int

`IntlChar::WB_NUMERIC` int

`IntlChar::WB_EXTENDNUMLET` int

`IntlChar::WB_CR` int

`IntlChar::WB_EXTEND` int

`IntlChar::WB_LF` int

`IntlChar::WB_MIDNUMLET` int

`IntlChar::WB_NEWLINE` int

`IntlChar::WB_REGIONAL_INDICATOR` int

`IntlChar::WB_HEBREW_LETTER` int

`IntlChar::WB_SINGLE_QUOTE` int

`IntlChar::WB_DOUBLE_QUOTE` int

`IntlChar::WB_COUNT` int

`IntlChar::SB_OTHER` int

`IntlChar::SB_ATERM` int

`IntlChar::SB_CLOSE` int

`IntlChar::SB_FORMAT` int

`IntlChar::SB_LOWER` int

`IntlChar::SB_NUMERIC` int

`IntlChar::SB_OLETTER` int

`IntlChar::SB_SEP` int

`IntlChar::SB_SP` int

`IntlChar::SB_STERM` int

`IntlChar::SB_UPPER` int

`IntlChar::SB_CR` int

`IntlChar::SB_EXTEND` int

`IntlChar::SB_LF` int

`IntlChar::SB_SCONTINUE` int

`IntlChar::SB_COUNT` int

`IntlChar::LB_UNKNOWN` int

`IntlChar::LB_AMBIGUOUS` int

`IntlChar::LB_ALPHABETIC` int

`IntlChar::LB_BREAK_BOTH` int

`IntlChar::LB_BREAK_AFTER` int

`IntlChar::LB_BREAK_BEFORE` int

`IntlChar::LB_MANDATORY_BREAK` int

`IntlChar::LB_CONTINGENT_BREAK` int

`IntlChar::LB_CLOSE_PUNCTUATION` int

`IntlChar::LB_COMBINING_MARK` int

`IntlChar::LB_CARRIAGE_RETURN` int

`IntlChar::LB_EXCLAMATION` int

`IntlChar::LB_GLUE` int

`IntlChar::LB_HYPHEN` int

`IntlChar::LB_IDEOGRAPHIC` int

`IntlChar::LB_INSEPARABLE` int

`IntlChar::LB_INSEPERABLE` int

`IntlChar::LB_INFIX_NUMERIC` int

`IntlChar::LB_LINE_FEED` int

`IntlChar::LB_NONSTARTER` int

`IntlChar::LB_NUMERIC` int

`IntlChar::LB_OPEN_PUNCTUATION` int

`IntlChar::LB_POSTFIX_NUMERIC` int

`IntlChar::LB_PREFIX_NUMERIC` int

`IntlChar::LB_QUOTATION` int

`IntlChar::LB_COMPLEX_CONTEXT` int

`IntlChar::LB_SURROGATE` int

`IntlChar::LB_SPACE` int

`IntlChar::LB_BREAK_SYMBOLS` int

`IntlChar::LB_ZWSPACE` int

`IntlChar::LB_NEXT_LINE` int

`IntlChar::LB_WORD_JOINER` int

`IntlChar::LB_H2` int

`IntlChar::LB_H3` int

`IntlChar::LB_JL` int

`IntlChar::LB_JT` int

`IntlChar::LB_JV` int

`IntlChar::LB_CLOSE_PARENTHESIS` int

`IntlChar::LB_CONDITIONAL_JAPANESE_STARTER` int

`IntlChar::LB_HEBREW_LETTER` int

`IntlChar::LB_REGIONAL_INDICATOR` int

`IntlChar::LB_COUNT` int

`IntlChar::NT_NONE` int

`IntlChar::NT_DECIMAL` int

`IntlChar::NT_DIGIT` int

`IntlChar::NT_NUMERIC` int

`IntlChar::NT_COUNT` int

`IntlChar::HST_NOT_APPLICABLE` int

`IntlChar::HST_LEADING_JAMO` int

`IntlChar::HST_VOWEL_JAMO` int

`IntlChar::HST_TRAILING_JAMO` int

`IntlChar::HST_LV_SYLLABLE` int

`IntlChar::HST_LVT_SYLLABLE` int

`IntlChar::HST_COUNT` int

`IntlChar::FOLD_CASE_DEFAULT` int

`IntlChar::FOLD_CASE_EXCLUDE_SPECIAL_I` int

## Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Adicionadas as constantes `IntlChar::PROPERTY_IDS_UNARY_OPERATOR`, `IntlChar::PROPERTY_ID_COMPAT_MATH_START` e `IntlChar::PROPERTY_ID_COMPAT_MATH_CONTINUE`.
8.4.0 | As constantes de classe agora são tipadas.
7.0.6 | A constante `IntlChar::NO_NUMERIC_VALUE` foi adicionada.

# IntlChar::charAge

(PHP 7, PHP 8)

IntlChar::charAge — Obtém a "idade" do ponto de código

### Descrição

public static function IntlChar::charAge(int|string `$codepoint`): ?array

Obtém a "idade" do ponto de código.

A "idade" é a versão Unicode de quando o ponto de código foi primeiramente designado (como um não-caractere para Uso Privado) ou atribuído a um caractere. Isto pode ser útil para evitar emitir pontos de código para receber processos que não aceitam novos caracteres.

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

O número da versão Unicode, como um array. Por exemplo, a versão 1.3.31.2 seria representada como `[1, 3, 31, 2]`. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::charage("\u{2603}"));
    var_dump(IntlChar::charage("\u{1F576}"));
    ?>

O exemplo acima produzirá:

    array(4) {
      [0]=>
      int(1)
      [1]=>
      int(1)
      [2]=>
      int(0)
      [3]=>
      int(0)
    }
    array(4) {
      [0]=>
      int(7)
      [1]=>
      int(0)
      [2]=>
      int(0)
      [3]=>
      int(0)
    }

### Veja Também

- IntlChar::getUnicodeVersion() - Obtém a versão do Unicode
- IntlChar::getIntPropertyMinValue() - Obtém o valor mínimo para uma propriedade Unicode
- IntlChar::getIntPropertyValue() - Obtém o valor de uma propriedade Unicode de um ponto de código

# IntlChar::charDigitValue

(PHP 7, PHP 8)

IntlChar::charDigitValue — Obtém o valor do dígito decimal de um caractere de dígito decimal

### Descrição

public static function IntlChar::charDigitValue(int|string `$codepoint`): ?int

Retorna o valor do dígito decimal de um caractere de dígito decimal.

Tais caracteres têm a categoria geral "Nd" (números de dígitos decimais) e um Numeric_Type igual a Decimal.

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

O valor de dígito decimal de `codepoint`, ou `-1` se não for um caractere de dígito decimal. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::charDigitValue("1"));
    var_dump(IntlChar::charDigitValue("\u{0662}"));
    var_dump(IntlChar::charDigitValue("\u{0E53}"));
    ?>

O exemplo acima produzirá:

    int(1)
    int(2)
    int(3)

### Veja Também

- IntlChar::getNumericValue() - Obtém o valor numérico para um ponto de código Unicode

# IntlChar::charDirection

(PHP 7, PHP 8)

IntlChar::charDirection — Obtém o valor de categoria bidirecional para um ponto de código

### Descrição

public static function IntlChar::charDirection(int|string `$codepoint`): ?int

Retorna o valor de categoria bidirecional para um ponto de código, que é usado no » Algoritmo Bidirecional Unicode (UAX #9).

> Nota:

> Alguns pontos de código não atribuídos têm valores bidirecionais de R ou AL porque estão em blocos reservador para escrita da direita para a esquerda.

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

O valor da categoria bidirecional; uma das constantes a seguir:

- `IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT`
- `IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT`
- `IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER`
- `IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_SEPARATOR`
- `IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_TERMINATOR`
- `IntlChar::CHAR_DIRECTION_ARABIC_NUMBER`
- `IntlChar::CHAR_DIRECTION_COMMON_NUMBER_SEPARATOR`
- `IntlChar::CHAR_DIRECTION_BLOCK_SEPARATOR`
- `IntlChar::CHAR_DIRECTION_SEGMENT_SEPARATOR`
- `IntlChar::CHAR_DIRECTION_WHITE_SPACE_NEUTRAL`
- `IntlChar::CHAR_DIRECTION_OTHER_NEUTRAL`
- `IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_EMBEDDING`
- `IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_OVERRIDE`
- `IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_ARABIC`
- `IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_EMBEDDING`
- `IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_OVERRIDE`
- `IntlChar::CHAR_DIRECTION_POP_DIRECTIONAL_FORMAT`
- `IntlChar::CHAR_DIRECTION_DIR_NON_SPACING_MARK`
- `IntlChar::CHAR_DIRECTION_BOUNDARY_NEUTRAL`
- `IntlChar::CHAR_DIRECTION_FIRST_STRONG_ISOLATE`
- `IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_ISOLATE`
- `IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_ISOLATE`
- `IntlChar::CHAR_DIRECTION_POP_DIRECTIONAL_ISOLATE`
- `IntlChar::CHAR_DIRECTION_CHAR_DIRECTION_COUNT`

Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::charDirection("A") === IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT);
    var_dump(IntlChar::charDirection("\u{05E9}") === IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT);
    var_dump(IntlChar::charDirection("+") === IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_SEPARATOR);
    var_dump(IntlChar::charDirection(".") === IntlChar::CHAR_DIRECTION_COMMON_NUMBER_SEPARATOR);
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(true)
    bool(true)
    bool(true)

# IntlChar::charFromName

(PHP 7, PHP 8)

IntlChar::charFromName — Encontra um caractere Unicode pelo nome e retorna seu valor de ponto de código

### Descrição

public static function IntlChar::charFromName(string `$name`, int `$type` = `IntlChar::UNICODE_CHAR_NAME`): ?int

Encontra um caractere Unicode pelo nome e retorna seu valor de ponto de código.

O nome deve corresponder de forma exata e completa. Se o nome não corresponder a um ponto de código, `null` é retornado.

Um nome Unicode 1.0 é correspondido somente se ele for diferente do nome moderno. Os nomes Unicode são todos em letras maiúsculas. Nomes estendidos são em letras minúsculas seguidos por um número hexadecimal em maiúsculas, e dentro de colchetes angulares.

### Parâmetros

`name`

  Nome completo do caractere Unicode.

`type`

  Informa qual deve ser o conjunto de nomes usados na pesquisa. Pode ser uma destas constantes:

  - `IntlChar::UNICODE_CHAR_NAME` (padrão)
  - `IntlChar::UNICODE_10_CHAR_NAME`
  - `IntlChar::EXTENDED_CHAR_NAME`
  - `IntlChar::CHAR_NAME_ALIAS`
  - `IntlChar::CHAR_NAME_CHOICE_COUNT`

### Valor Retornado

O valor Unicode do ponto de código do nome fornecido (como um int), ou `null` se não houver tal ponto de código.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::charFromName("LATIN CAPITAL LETTER A"));
    var_dump(IntlChar::charFromName("SNOWMAN"));
    var_dump(IntlChar::charFromName("RECYCLING SYMBOL FOR TYPE-1 PLASTICS"));
    var_dump(IntlChar::charFromName("UM TEXTO ALEATÓRIO QUE NÃO CORRESPONDE A NENHUM CARACTERE UNICODE"));
    ?>

O exemplo acima produzirá:

    int(65)
    int(9731)
    int(9843)
    NULL

### Veja Também

- IntlChar::charName() - Obtém o nome de um caractere Unicode
- IntlChar::enumCharNames() - Enumera todos os caracteres Unicode atribuídos dentro de um intervalo

# IntlChar::charMirror

(PHP 7, PHP 8)

IntlChar::charMirror — Obtém o caractere "espelho" para um ponto de código

### Descrição

public static function IntlChar::charMirror(int|string `$codepoint`): int|string|null

Mapeia o caractere especificado para um caractere "espelho".

Para caracteres com a propriedade Bidi_Mirrored (bidirecional espelhado), as implementações algumas vezes precisam de um mapeamento simples para outro caractere Unicode (ponto de código) de forma que o glifo padrão possa servir como espelho do glifo padrão do caractere especificado. Isto é útil para conversão de texto de páginas de código com ordenamento visual, e para telas sem capacidades de seleção de glifos.

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna outro ponto de código Unicode que possa servir como substituto espelho, ou o parâmetro `codepoint` em si, se não houver tal mapeamento ou se `codepoint` não tiver a propriedade Bidi_Mirrored.

O tipo do retorno é int, a menos que o ponto de código tenha sido passado como uma string UTF-8, caso em que uma string é retornada. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::charMirror("A"));
    var_dump(IntlChar::charMirror("<"));
    var_dump(IntlChar::charMirror("("));
    ?>

O exemplo acima produzirá:

    string(1) "A"
    string(1) ">"
    string(2) ")"

### Veja Também

- IntlChar::isMirrored() - Verifica se um ponto de código tem a propriedade Bidi_Mirrored
- `IntlChar::PROPERTY_BIDI_MIRRORED`

# IntlChar::charName

(PHP 7, PHP 8)

IntlChar::charName — Obtém o nome de um caractere Unicode

### Descrição

public static function IntlChar::charName(int|string `$codepoint`, int `$type` = `IntlChar::UNICODE_CHAR_NAME`): ?string

Obtém o nome de um caractere Unicode.

Dependendo do parâmetro `type`, o nome resultante do caractere será o nome "moderno" ou o nome que foi definido na versão 1.0 do Unicode. O nome contém apenas caracteres "invariantes" como A-Z, 0-9, espaço e '-'. Nomes do Unicode 1.0 somente são obtidos se eles fores diferentes dos nomes modernos e se a ICU contiver dados para eles.

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).
`type`

  Define qual o conjunto de nomes usado na pesquisa. Pode ser uma destas constantes:

  - `IntlChar::UNICODE_CHAR_NAME` (padrão)
  - `IntlChar::UNICODE_10_CHAR_NAME`
  - `IntlChar::EXTENDED_CHAR_NAME`
  - `IntlChar::CHAR_NAME_ALIAS`
  - `IntlChar::CHAR_NAME_CHOICE_COUNT`

### Valor Retornado

O nome correspondente, ou uma string vazia se não houver nome para este caractere, ou `null` se não houver tal ponto de código.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::charName("."));
    var_dump(IntlChar::charName(".", IntlChar::UNICODE_CHAR_NAME));
    var_dump(IntlChar::charName("\u{2603}"));
    var_dump(IntlChar::charName("\u{0000}"));
    ?>

O exemplo acima produzirá:

    string(9) "FULL STOP"
    string(9) "FULL STOP"
    string(7) "SNOWMAN"
    string(0) ""

### Veja Também

- IntlChar::charFromName() - Encontra um caractere Unicode pelo nome e retorna seu valor de ponto de código
- IntlChar::enumCharNames() - Enumera todos os caracteres Unicode atribuídos dentro de um intervalo

# IntlChar::charType

(PHP 7, PHP 8)

IntlChar::charType — Obtém o valor da categoria geral para um ponto de código

### Descrição

public static function IntlChar::charType(int|string `$codepoint`): ?int

Retorna o valor da categoria geral para um ponto de código.

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna o tipo de categoria geral, que pode ser uma das constantes a seguir:

- `IntlChar::CHAR_CATEGORY_UNASSIGNED`
- `IntlChar::CHAR_CATEGORY_GENERAL_OTHER_TYPES`
- `IntlChar::CHAR_CATEGORY_UPPERCASE_LETTER`
- `IntlChar::CHAR_CATEGORY_LOWERCASE_LETTER`
- `IntlChar::CHAR_CATEGORY_TITLECASE_LETTER`
- `IntlChar::CHAR_CATEGORY_MODIFIER_LETTER`
- `IntlChar::CHAR_CATEGORY_OTHER_LETTER`
- `IntlChar::CHAR_CATEGORY_NON_SPACING_MARK`
- `IntlChar::CHAR_CATEGORY_ENCLOSING_MARK`
- `IntlChar::CHAR_CATEGORY_COMBINING_SPACING_MARK`
- `IntlChar::CHAR_CATEGORY_DECIMAL_DIGIT_NUMBER`
- `IntlChar::CHAR_CATEGORY_LETTER_NUMBER`
- `IntlChar::CHAR_CATEGORY_OTHER_NUMBER`
- `IntlChar::CHAR_CATEGORY_SPACE_SEPARATOR`
- `IntlChar::CHAR_CATEGORY_LINE_SEPARATOR`
- `IntlChar::CHAR_CATEGORY_PARAGRAPH_SEPARATOR`
- `IntlChar::CHAR_CATEGORY_CONTROL_CHAR`
- `IntlChar::CHAR_CATEGORY_FORMAT_CHAR`
- `IntlChar::CHAR_CATEGORY_PRIVATE_USE_CHAR`
- `IntlChar::CHAR_CATEGORY_SURROGATE`
- `IntlChar::CHAR_CATEGORY_DASH_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_START_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_END_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_CONNECTOR_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_OTHER_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_MATH_SYMBOL`
- `IntlChar::CHAR_CATEGORY_CURRENCY_SYMBOL`
- `IntlChar::CHAR_CATEGORY_MODIFIER_SYMBOL`
- `IntlChar::CHAR_CATEGORY_OTHER_SYMBOL`
- `IntlChar::CHAR_CATEGORY_INITIAL_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_FINAL_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_CHAR_CATEGORY_COUNT`

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::charType("A") === IntlChar::CHAR_CATEGORY_UPPERCASE_LETTER);
    var_dump(IntlChar::charType(".") === IntlChar::CHAR_CATEGORY_OTHER_PUNCTUATION);
    var_dump(IntlChar::charType("\t") === IntlChar::CHAR_CATEGORY_CONTROL_CHAR);
    var_dump(IntlChar::charType("\u{2603}") === IntlChar::CHAR_CATEGORY_OTHER_SYMBOL);
    var_dump(IntlChar::charType("multiple chars") === null);
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(true)
    bool(true)
    bool(true)
    bool(true)

# IntlChar::chr

(PHP 7, PHP 8)

IntlChar::chr — Retorna um caractere Unicode por valor de ponto de código

### Descrição

public static function IntlChar::chr(int|string `$codepoint`): ?string

Retorna uma string contendo o caractere especificado pelo valor de ponto de código Unicode.

Este método é complementar ao método IntlChar::ord().

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Uma string contendo o caractere único especificado pelo valor de ponto de código, ou `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    $values = ["A", 63, 123, 9731];
    foreach ($values as $value) {
        var_dump(IntlChar::chr($value));
    }
    ?>

O exemplo acima produzirá:

    string(1) "A"
    string(1) "?"
    string(1) "{"
    string(3) "☃"

### Veja Também

- IntlChar::ord() - Retorna o valor do ponto de código Unicode do caractere
- mb_chr() - Retorna um caractere pelo valor do ponto de código Unicode
- chr() - Gera uma string de um byte a partir de um número

# IntlChar::digit

(PHP 7, PHP 8)

IntlChar::digit — Obtém o valor de dígito decimal de um ponto de código para uma base fornecida

### Descrição

public static function IntlChar::digit(int|string `$codepoint`, int `$base` = 10): int|false|null

Retorna o valor de dígito decimal de um ponto de código para uma base numérica fornecida.

Se a base (radix) não estiver no intervalo `2 <= radix <= 36` ou se o valor de `codepoint` não for um dígito válido na base especificada, `false` é retornado. Um caractere é um dígito válido se pelo menos uma das condições a seguir for verdadeira:

- O caractere tem um valor de dígito decimal. Tais caracteres têm a categoria geral "Nd" (número de dígito decimal) e um Numeric_Type igual a Decimal. Neste caso o valor é o valor do dígito decimal do caractere.
- O caractere é uma das letras latinas maiúsculas de `'A'` a `'Z'`. Neste caso, o valor é `codepoint - 'A' + 10`.
- O caractere é uma das letras latinas minúsculas de `'a'` a `'z'`. Neste caso, o valor é `codepoint - 'a' + 10`.
- Letras latinas do intervalo ASCII (`0061..007A`, `0041..005A`) e do intervalo ASCII de escopo completo (`FF41..FF5A`, `FF21..FF3A`) são reconhecidas.

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).
`base`

  A base numérica (o padrão é `10`).

### Valor Retornado

Retorna o valor numérico representado pelo caractere na base especificada, ou `false` se o valor não existir ou se o valor exceder a base. Retorna `null` em caso de falha.

Aviso

Esta função pode retornar o valor booleano `false`, mas também pode retornar um valor não booleano que pode ser avaliado como `false`. Leia a seção sobre Booleanos para mais informações. Use o operador === para testar o valor retornado por esta função.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php

    var_dump(IntlChar::digit("0"));
    var_dump(IntlChar::digit("3"));

    var_dump(IntlChar::digit("A", 16));
    var_dump(IntlChar::digit("A"));

    ?>

O exemplo acima produzirá:

    int(0)
    int(3)
    int(10)
    bool(false)

### Veja Também

- IntlChar::forDigit() - Obtém a representação em caractere para um dígito e uma base fornecidos
- IntlChar::charDigitValue() - Obtém o valor do dígito decimal de um caractere de dígito decimal
- IntlChar::isdigit() - Verifica se um ponto de código é um caractere de dígito
- `IntlChar::PROPERTY_NUMERIC_TYPE`

# IntlChar::enumCharNames

(PHP 7, PHP 8)

IntlChar::enumCharNames — Enumera todos os caracteres Unicode atribuídos dentro de um intervalo

### Descrição

public static function IntlChar::enumCharNames(
int|string `$start`,
int|string `$end`,
callable `$callback`,
int `$type` = `IntlChar::UNICODE_CHAR_NAME`
): bool

Enumera todos os caracteres Unicode atribuídos entre o início e os pontos de código limite (início inclusive, pontos de código exclusive) e chama uma função para cada, passando o valor de ponto de código e o nome do caractere.

Para nomes Unicode 1.0, são enumerados somente os que são diferentes dos nomes modernos.

### Parâmetros

`start`

  O primeiro ponto de código no intervalo de enumeração.

`end`

  Um a mais que o último ponto de código no intervalo da enumeração (o primeiro depois do intervalo).

`callback`

  A função que deve ser chamada para cada nome de caractere. Os três argumentos a seguir serão passados na função:

  - int `$codepoint` - O valor numérico do ponto de código
  - int `$nameChoice` - O mesmo valor do parâmetro `type` abaixo
  - string `$name` - O nome do caractere
`type`

  Seletor para o tipo de nomes e enumerar. Pode ser uma destas constantes:

  - `IntlChar::UNICODE_CHAR_NAME` (padrão)
  - `IntlChar::UNICODE_10_CHAR_NAME`
  - `IntlChar::EXTENDED_CHAR_NAME`
  - `IntlChar::CHAR_NAME_ALIAS`
  - `IntlChar::CHAR_NAME_CHOICE_COUNT`

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Este método agora retorna `false` em caso de falha; anteriormente retornava `null`.

### Exemplos

Exemplo #1 Exemplo de enumeração em uma faixa de pontos de código

    <?php
    IntlChar::enumCharNames(0x2600, 0x2610, function($codepoint, $nameChoice, $name) {
        printf("U+%04x %s\n", $codepoint, $name);
    });
    ?>

O exemplo acima produzirá:

    U+2600 BLACK SUN WITH RAYS
    U+2601 CLOUD
    U+2602 UMBRELLA
    U+2603 SNOWMAN
    U+2604 COMET
    U+2605 BLACK STAR
    U+2606 WHITE STAR
    U+2607 LIGHTNING
    U+2608 THUNDERSTORM
    U+2609 SUN
    U+260a ASCENDING NODE
    U+260b DESCENDING NODE
    U+260c CONJUNCTION
    U+260d OPPOSITION
    U+260e BLACK TELEPHONE
    U+260f WHITE TELEPHONE

### Veja Também

- IntlChar::charName() - Obtém o nome de um caractere Unicode
- IntlChar::charFromName() - Encontra um caractere Unicode pelo nome e retorna seu valor de ponto de código

# IntlChar::enumCharTypes

(PHP 7, PHP 8)

IntlChar::enumCharTypes — Enumera todos os pontos de código com suas categorias gerais Unicode

### Descrição

public static function IntlChar::enumCharTypes(callable `$callback`): void

Enumera de maneira eficiente todos os pontos de código com suas categorias gerais Unicode. É útil para construir estruturas de dados, para enumerar todos os pontos de código atribuídos, etc.

Para cada invervalo contíguo de pontos de código com uma categoria geral fornecida ("tipo de caractere"), a função `callback` é chamada. Intervalos adjacentes têm tipos diferentes. O Padrão Unicode garante que o valor numérico do tipo esteja na faixa 0..31.

### Parâmetros

`callback`

  A função que deve er chamada para cada intervalo contíguo de pontos de código com a mesma categoria geral. Os três argumentos a seguir serão passadoa à função:

  - int `$start` - O ponto de código inicial do intervalo
  - int `$end` - O ponto de código final do intervalo
  - int `$name` - O tipo da categoria (uma das constantes `IntlChar::CHAR_CATEGORY_*`)

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de enumeração de um intervalo de pontos de código

    <?php
    IntlChar::enumCharTypes(function($start, $end, $type) {
        printf("U+%04x até U+%04x estão na categoria %d\n", $start, $end, $type);
    });
    ?>

O exemplo acima produzirá:

    U+0000 até U+0020 estão na categoria 15
    U+0020 até U+0021 estão na categoria 12
    U+0021 até U+0024 estão na categoria 23
    U+0024 até U+0025 estão na categoria 25
    U+0025 até U+0028 estão na categoria 23
    U+0028 até U+0029 estão na categoria 20
    U+0029 até U+002a estão na categoria 21
    U+002a até U+002b estão na categoria 23
    U+002b até U+002c estão na categoria 24
    U+002c até U+002d estão na categoria 23
    U+002d até U+002e estão na categoria 19
    U+002e até U+0030 estão na categoria 23
    U+0030 até U+003a estão na categoria 9
    ...

# IntlChar::foldCase

(PHP 7, PHP 8)

IntlChar::foldCase — Converte maiúscula/minúscula em um ponto de código

### Descrição

public static function IntlChar::foldCase(int|string `$codepoint`, int `$options` = `IntlChar::FOLD_CASE_DEFAULT`): int|string|null

O caractere fornecido é mapeados para a sua maiúscula ou minúscula equivalente; se o caractere não tiver este mapeamento, o prórpio caractere é retornado.

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).
`options`

  Pode ser `IntlChar::FOLD_CASE_DEFAULT` (padrão) ou `IntlChar::FOLD_CASE_EXCLUDE_SPECIAL_I`.

### Valor Retornado

Retorna a Conversão Simples (cujo mapeamento não altera o tamanho da string) do ponto de código, se houver; caso contrário retorna o próprio ponto de código em caso de sucesso, ou `null` em caso de falha.

# IntlChar::forDigit

(PHP 7, PHP 8)

IntlChar::forDigit — Obtém a representação em caractere para um dígito e uma base fornecidos

### Descrição

public static function IntlChar::forDigit(int `$digit`, int `$base` = 10): int

Determina a representação em caractere para um dígito específico na base fornecida.

E o valor de base não for válido, ou se o valor do dígito não for válido na base especificada, o caractere nulo (`U+0000`) é retornado.

A base (radix) é válida se for maior ou igual a `2` e menor ou igual a `36`. O dígito (digit) é válido se `0 <= digit < radix`.

Se o dígito for menor que `10`, '0' + dígito é retornado. Caso contrário, o valor 'a' + dígito - 10 é retornado.

### Parâmetros

`digit`

  O número a ser convertido para um caractere.

`base`

  A base (o padrão é `10`).

### Valor Retornado

A representação em caractere (como um int) do dígito especificado na base fornecida.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::forDigit(0));
    var_dump(IntlChar::forDigit(3));
    var_dump(IntlChar::forDigit(3, 10));
    var_dump(IntlChar::forDigit(10));
    var_dump(IntlChar::forDigit(10, 16));
    ?>

O exemplo acima produzirá:

    int(48)
    int(51)
    int(51)
    int(0)
    int(97)

### Veja Também

- IntlChar::digit() - Obtém o valor de dígito decimal de um ponto de código para uma base fornecida
- IntlChar::charDigitValue() - Obtém o valor do dígito decimal de um caractere de dígito decimal
- IntlChar::isdigit() - Verifica se um ponto de código é um caractere de dígito
- `IntlChar::PROPERTY_NUMERIC_TYPE`

# IntlChar::getBidiPairedBracket

(PHP 7, PHP 8)

IntlChar::getBidiPairedBracket — Obtém o caractere de par de abertura/fechamento para um ponto de código

### Descrição

public static function IntlChar::getBidiPairedBracket(int|string `$codepoint`): int|string|null

Mapeia o caractere especificado para o seu par de abertura/fechamento.

Para `IntlChar::PROPERTY_BIDI_PAIRED_BRACKET_TYPE !== IntlChar::BPT_NONE`, isso é o mesmo que IntlChar::charMirror(). Caso contrário, o próprio `codepoint` é retornado.

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna o ponto de código do caractere de par de abertura/fechamento, ou o próprio `codepoint` se não existir este mapeamento. Retorna `null` em caso de falha.

O tipo do retorno é int, a menos que o ponto de código tenha sido passado como uma string UTF-8, caso em que uma string é retornada. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::getBidiPairedBracket(91));
    var_dump(IntlChar::getBidiPairedBracket('['));
    ?>

O exemplo acima produzirá:

    int(93)
    string(1) "]"

### Notas

> Nota:

> Este método está disponível a partir da ICU versão 52.

### Veja Também

- IntlChar::charMirror() - Obtém o caractere "espelho" para um ponto de código
- `IntlChar::PROPERTY_BIDI_PAIRED_BRACKET`
- `IntlChar::PROPERTY_BIDI_PAIRED_BRACKET_TYPE`

# IntlChar::getBlockCode

(PHP 7, PHP 8)

IntlChar::getBlockCode — Obtém o bloco de alocação Unicode contendo um ponto de código

### Descrição

public static function IntlChar::getBlockCode(int|string `$codepoint`): ?int

Obtém o bloco de alocação Unicode que contém o caractere.

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna o valor do bloco para o `codepoint`. Veja as constantes `IntlChar::BLOCK_CODE_*` para possíveis valores de retorno. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::getBlockCode("A") === IntlChar::BLOCK_CODE_BASIC_LATIN);
    var_dump(IntlChar::getBlockCode("Φ") === IntlChar::BLOCK_CODE_GREEK);
    var_dump(IntlChar::getBlockCode("\u{2603}") === IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS);
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(true)
    bool(true)

# IntlChar::getCombiningClass

(PHP 7, PHP 8)

IntlChar::getCombiningClass — Obtém a classe de combinação de um ponto de código

### Descrição

public static function IntlChar::getCombiningClass(int|string `$codepoint`): ?int

Retorna a classe de combinação de um ponto de código.

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna a classe de combinação do caractere. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::getCombiningClass("A"));
    var_dump(IntlChar::getCombiningClass("\u{0334}"));
    var_dump(IntlChar::getCombiningClass("\u{0358}"));
    ?>

O exemplo acima produzirá:

    int(0)
    int(1)
    int(232)

# IntlChar::getFC_NFKC_Closure

(PHP 7, PHP 8)

IntlChar::getFC_NFKC_Closure — Obtém a propriedade FC_NFKC_Closure para um ponto de código

### Descrição

public static function IntlChar::getFC_NFKC_Closure(int|string `$codepoint`): string|false|null

Obtém a string da propriedade FC_NFKC_Closure para um caractere.

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna a string da propriedade FC_NFKC_Closure para o `codepoint`, ou uma string vazia se não houver. Retorna `null` ou `false` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::getFC_NFKC_Closure("\u{2121}"));
    var_dump(IntlChar::getFC_NFKC_Closure("\u{1D2D}"));
    ?>

O exemplo acima produzirá:

    string(3) "tel"
    string(2) "æ"

# IntlChar::getIntPropertyMaxValue

(PHP 7, PHP 8)

IntlChar::getIntPropertyMaxValue — Obtém o valor máximo para uma propriedade Unicode

### Descrição

public static function IntlChar::getIntPropertyMaxValue(int `$property`): int

Obtém o valor máximo para uma propriedade enumarada/inteira/binária Unicode.

### Parâmetros

`property`
  A propriedade Unicode a ser pesquisada (consulte as constantes `IntlChar::PROPERTY_*`).

### Valor Retornado

O valor máximo retornado por IntlChar::getIntPropertyValue() para uma propriedade Unicode. `<=0` se o seletor de propriedade estiver fora do intervalo.

### Exemplos

Exemplo #1 Testando diferentes propriedades

    <?php
    var_dump(IntlChar::getIntPropertyMaxValue(IntlChar::PROPERTY_BIDI_CLASS));
    var_dump(IntlChar::getIntPropertyMaxValue(IntlChar::PROPERTY_SCRIPT));
    var_dump(IntlChar::getIntPropertyMaxValue(IntlChar::PROPERTY_IDEOGRAPHIC));
    var_dump(IntlChar::getIntPropertyMaxValue(999999999)); // Um valor inventado
    ?>

O exemplo acima produzirá:

    int(22)
    int(166)
    int(1)
    int(-1)

### Veja Também

- IntlChar::hasBinaryProperty() - Verifica uma propriedade binária Unicode para um ponto de código
- IntlChar::getIntPropertyMinValue() - Obtém o valor mínimo para uma propriedade Unicode
- IntlChar::getIntPropertyValue() - Obtém o valor de uma propriedade Unicode de um ponto de código
- IntlChar::getUnicodeVersion() - Obtém a versão do Unicode

# IntlChar::getIntPropertyMinValue

(PHP 7, PHP 8)

IntlChar::getIntPropertyMinValue — Obtém o valor mínimo para uma propriedade Unicode

### Descrição

public static function IntlChar::getIntPropertyMinValue(int `$property`): int

Obtém o valor mínimo para uma propriedade Unicode enumerada/inteira/binária.

### Parâmetros

`property`
  A propriedade Unicode a ser pesquisada (consulte as constantes `IntlChar::PROPERTY_*`).

### Valor Retornado

O valor mínimo retornado por IntlChar::getIntPropertyValue() para uma propriedade Unicode. `0` se o seletor de propriedade estiver fora do intervalo.

### Exemplos

Exemplo #1 Testando diferentes propriedades

    <?php
    var_dump(IntlChar::getIntPropertyMinValue(IntlChar::PROPERTY_BIDI_CLASS));
    var_dump(IntlChar::getIntPropertyMinValue(IntlChar::PROPERTY_SCRIPT));
    var_dump(IntlChar::getIntPropertyMinValue(IntlChar::PROPERTY_IDEOGRAPHIC));
    var_dump(IntlChar::getIntPropertyMinValue(999999999)); // Um valor inventado
    ?>

O exemplo acima produzirá:

    int(0)
    int(0)
    int(0)
    int(0)

### Veja Também

- IntlChar::hasBinaryProperty() - Verifica uma propriedade binária Unicode para um ponto de código
- IntlChar::getIntPropertyMaxValue() - Obtém o valor máximo para uma propriedade Unicode
- IntlChar::getIntPropertyValue() - Obtém o valor de uma propriedade Unicode de um ponto de código
- IntlChar::getUnicodeVersion() - Obtém a versão do Unicode

# IntlChar::getIntPropertyValue

(PHP 7, PHP 8)

IntlChar::getIntPropertyValue — Obtém o valor de uma propriedade Unicode de um ponto de código

### Descrição

public static function IntlChar::getIntPropertyValue(int|string `$codepoint`, int `$property`): ?int

Obtém o valor de uma propriedade Unicode inteira ou enumerada para um ponto de código. Também retorna valores de propriedades binárias e de máscara.

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).
`property`
  A propriedade Unicode a ser pesquisada (consulte as constantes `IntlChar::PROPERTY_*`).

### Valor Retornado

Retorna o valor numérico que é diretamente o valor da propriedade ou, para propriedade enumeradas, o que corresponde ao valor numérico da constante enumerada do tipo de enumeração do valor da propriedade respectiva. Retorna `null` em caso de falha.

Retorna `0` ou `1` (para `false`/`true`) para propriedades Unicode binárias.

Retorna uma máscara de bits para propriedades de máscara.

Retorna `0` se `property` estiver fora dos limites ou se a versão Unicode não tiver nenhum dado para a propriedade, ou não tiver para este ponto de código.

### Exemplos

Exemplo #1 Testando diferentes propriedades

    <?php
    var_dump(IntlChar::getIntPropertyValue("A", IntlChar::PROPERTY_ALPHABETIC) === 1);
    var_dump(IntlChar::getIntPropertyValue("[", IntlChar::PROPERTY_BIDI_MIRRORED) === 1);
    var_dump(IntlChar::getIntPropertyValue("Φ", IntlChar::PROPERTY_BLOCK) === IntlChar::BLOCK_CODE_GREEK);
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(true)
    bool(true)

### Veja Também

- IntlChar::hasBinaryProperty() - Verifica uma propriedade binária Unicode para um ponto de código
- IntlChar::getIntPropertyMinValue() - Obtém o valor mínimo para uma propriedade Unicode
- IntlChar::getIntPropertyMaxValue() - Obtém o valor máximo para uma propriedade Unicode
- IntlChar::getUnicodeVersion() - Obtém a versão do Unicode

# IntlChar::getNumericValue

(PHP 7, PHP 8)

IntlChar::getNumericValue — Obtém o valor numérico para um ponto de código Unicode

### Descrição

public static function IntlChar::getNumericValue(int|string `$codepoint`): ?float

Obtém o valor numérico para um ponto de código Unicode como definido no Banco de Dados de Caracteres Unicode.

Para caracteres sem nenhum valor numérico no Banco de Dados de Caracteres Unicode, esta função retornará `IntlChar::NO_NUMERIC_VALUE`.

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Valor numérico de `codepoint`, ou `IntlChar::NO_NUMERIC_VALUE` se nenhum estiver definido. Esta constantes foi adicionada no 7.0.6, antes dessa versão o valor literal (float)`-123456789` pode ser usado no lugar. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::getNumericValue("4"));
    var_dump(IntlChar::getNumericValue("x"));
    var_dump(IntlChar::getNumericValue("\u{216C}"));
    ?>

O exemplo acima produzirá:

    float(4)
    float(-123456789)
    float(50)

# IntlChar::getPropertyEnum

(PHP 7, PHP 8)

IntlChar::getPropertyEnum — Obtém o valor da constante da propriedade para uma propriedade informada

### Descrição

public static function IntlChar::getPropertyEnum(string `$alias`): int

Obtém o valor da constante da propriedade para uma propriedade informada, como especificado no arquivo de banco de dados Unicode PropertyAliases.txt. Curtas, longas, e outras variantes são reconhecidas.

Além disso, esta função mapeia os nomes sintéticos "gcm" / "General_Category_Mask" para a propriedade `IntlChar::PROPERTY_GENERAL_CATEGORY_MASK`. Estes nomes não estão no arquivo PropertyAliases.txt.

Esta função é complementar à IntlChar::getPropertyName().

### Parâmetros

`alias`

  O nome da propriedade a ser correspondida. O nome é comparado usando o modo "loose matching" (correspondência solta) como descrito no arquivo PropertyAliases.txt.

### Valor Retornado

Retorna um valor de constante `IntlChar::PROPERTY_`, ou `IntlChar::PROPERTY_INVALID_CODE` se o nome fornecido não corresponder a nenhuma propriedade.

### Exemplos

Exemplo #1 Testando diferentes propriedades

    <?php
    var_dump(IntlChar::getPropertyEnum('Bidi_Class') === IntlChar::PROPERTY_BIDI_CLASS);
    var_dump(IntlChar::getPropertyEnum('script') === IntlChar::PROPERTY_SCRIPT);
    var_dump(IntlChar::getPropertyEnum('IDEOGRAPHIC') === IntlChar::PROPERTY_IDEOGRAPHIC);
    var_dump(IntlChar::getPropertyEnum('Uma string inventada') === IntlChar::PROPERTY_INVALID_CODE);
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(true)
    bool(true)
    bool(true)

### Veja Também

- IntlChar::getPropertyName() - Obtém o nome Unicode de uma propriedade

# IntlChar::getPropertyName

(PHP 7, PHP 8)

IntlChar::getPropertyName — Obtém o nome Unicode de uma propriedade

### Descrição

public static function IntlChar::getPropertyName(int `$property`, int `$type` = `IntlChar::LONG_PROPERTY_NAME`): string|false

Retorna o nome Unicode de uma propriedade fornecida, como especificado no arquivo de banco de dados PropertyAliases.txt.

Além disso, esta função mapeia a propriedade `IntlChar::PROPERTY_GENERAL_CATEGORY_MASK` para os nomes sintéticos "gcm" / "General_Category_Mask". Estes nomes não estão no arquivo PropertyAliases.txt.

Esta função é complementar à IntlChar::getPropertyEnum().

### Parâmetros

`property`
  A propriedade Unicode a ser pesquisada (consulte as constantes `IntlChar::PROPERTY_*`).

  `IntlChar::PROPERTY_INVALID_CODE` não deve ser usada. Além disso, se `property` estiver fora do intervalo, `false` é retornado.

`type`

  Selector para o nome que deve ser obtido. Se for do intervalo, `false` é retornado.

  Todas as propriedades têm um nome longo. A maioria tem um nome curto, mas algumas não têm. Unicode permite nomes adicionais; caso presentes, estes serão retornados adicionando-se 1, 2, etc. a `IntlChar::LONG_PROPERTY_NAME`.

### Valor Retornado

Retorna o nome, ou `false` se `property` ou `type` estiverem fora de seus intervalos.

Se um `type` retornar `false`, todos os valores maiores de `type` retornarão `false`, com uma exceção: se `false` for retornado para `IntlChar::SHORT_PROPERTY_NAME`, então `IntlChar::LONG_PROPERTY_NAME` (e maiores) podem ainda retornar valores não-`false`.

### Exemplos

Exemplo #1 Testando diferentes propriedades

    <?php
    var_dump(IntlChar::getPropertyName(IntlChar::PROPERTY_BIDI_CLASS));
    var_dump(IntlChar::getPropertyName(IntlChar::PROPERTY_BIDI_CLASS, IntlChar::SHORT_PROPERTY_NAME));
    var_dump(IntlChar::getPropertyName(IntlChar::PROPERTY_BIDI_CLASS, IntlChar::LONG_PROPERTY_NAME));
    var_dump(IntlChar::getPropertyName(IntlChar::PROPERTY_BIDI_CLASS, IntlChar::LONG_PROPERTY_NAME + 1));
    ?>

O exemplo acima produzirá:

    string(10) "Bidi_Class"
    string(2) "bc"
    string(10) "Bidi_Class"
    bool(false)

### Veja Também

- IntlChar::getPropertyEnum() - Obtém o valor da constante da propriedade para uma propriedade informada

# IntlChar::getPropertyValueEnum

(PHP 7, PHP 8)

IntlChar::getPropertyValueEnum — Obtém o valor da propriedade para um nome de valor fornecido

### Descrição

public static function IntlChar::getPropertyValueEnum(int `$property`, string `$name`): int

Retorna o valor inteiro da propriedade para um nome de valor fornecido, como especificado no arquivo de dados Unicode PropertyValueAliases.txt. Nomes curtos, longos e outras variantes são reconhecidos.

> Nota:

> Alguns dos nomes em PropertyValueAliases.txt somente serão reconhecidos com `IntlChar::PROPERTY_GENERAL_CATEGORY_MASK` e não com `IntlChar::PROPERTY_GENERAL_CATEGORY`. Estes incluem:

> - "C" / "Other"
> - "L" / "Letter"
> - "LC" / "Cased_Letter"
> - "M" / "Mark"
> - "N" / "Number"
> - "P" / "Punctuation"
> - "S" / "Symbol"
> - "Z" / "Separator"

### Parâmetros

`property`
  A propriedade Unicode a ser pesquisada (consulte as constantes `IntlChar::PROPERTY_*`).

  Se estiver fora do intervalo, ou se este método não funcionar com o valor fornecido, `IntlChar::PROPERTY_INVALID_CODE` é retornado.

`name`

  O valor a ser correspondido. O nome é comparado usando "loose matching" (correspondência solta) como descrito em PropertyValueAliases.txt.

### Valor Retornado

Retorna o valor inteiro correspondente ou `IntlChar::PROPERTY_INVALID_CODE` se o nome fornecido não corresponder a nenhum valor da propriedade informada ou se a propriedade for inválida.

### Exemplos

Exemplo #1 Testando diferentes propriedades

    <?php
    var_dump(IntlChar::getPropertyValueEnum(IntlChar::PROPERTY_BLOCK, 'greek') === IntlChar::BLOCK_CODE_GREEK);
    var_dump(IntlChar::getPropertyValueEnum(IntlChar::PROPERTY_BIDI_CLASS, 'RIGHT_TO_LEFT') === IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT);
    var_dump(IntlChar::getPropertyValueEnum(IntlChar::PROPERTY_BIDI_CLASS, 'uma string inventada') === IntlChar::PROPERTY_INVALID_CODE);
    var_dump(IntlChar::getPropertyValueEnum(123456789, 'RIGHT_TO_LEFT') === IntlChar::PROPERTY_INVALID_CODE);
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(true)
    bool(true)
    bool(true)

# IntlChar::getPropertyValueName

(PHP 7, PHP 8)

IntlChar::getPropertyValueName — Obtém o nome Unicode para um valor de propriedade

### Descrição

public static function IntlChar::getPropertyValueName(int `$property`, int `$value`, int `$type` = `IntlChar::LONG_PROPERTY_NAME`): string|false

Retorna o nome Unicode para um valor de propriedade fornecido, como especificado no arquivo de dados Unicode PropertyValueAliases.txt.

> Nota:

> Alguns nomes no PropertyValueAliases.txt somente podem ser obtidos usando-se `IntlChar::PROPERTY_GENERAL_CATEGORY_MASK` e não `IntlChar::PROPERTY_GENERAL_CATEGORY`. Estes incluem:

> - "C" / "Other"
> - "L" / "Letter"
> - "LC" / "Cased_Letter"
> - "M" / "Mark"
> - "N" / "Number"
> - "P" / "Punctuation"
> - "S" / "Symbol"
> - "Z" / "Separator"

### Parâmetros

`property`
  A propriedade Unicode a ser pesquisada (consulte as constantes `IntlChar::PROPERTY_*`).

  Se estiver fora do intervalo ou se este método não funcionar com o valor fornecido, `false` é retornado.

`value`

  Seletor de um valor para a propriedade fornecida. Se estiver fora dos limites, `false` é retornado.

  Em geral, nomes válidos variam de `0` até um máximo. Existem exceções:

  - Valores de `IntlChar::PROPERTY_BLOCK` começam no valor diferente de zero `IntlChar::BLOCK_CODE_BASIC_LATIN`.
  - Valores `IntlChar::PROPERTY_CANONICAL_COMBINING_CLASS` não são contíguos e variam de 0 a 240.
`type`

  Seletor para o nome a ser obtido. Se estiver fora dos limites, `false` é retornado.

  Todos os valores têm um nome longo. A maioria tem um nome curto, mas alguns não têm. Unicode permite nomes adicionais; se presentes, estes serão retornados adicionando-se 1, 2, etc. a `IntlChar::LONG_PROPERTY_NAME`.

### Valor Retornado

Retorna o nome ou `false` se `property` ou `type` estiverem fora de seus intervalos. Retorna `null` em caso de falha.

Se um `type` retornar `false`, todos os valores maiores de `type` retornarão `false`, com uma exceção: se `false` for retornado para `IntlChar::SHORT_PROPERTY_NAME`, então `IntlChar::LONG_PROPERTY_NAME` (e acima) podem ainda retornar valor não-`false`.

### Exemplos

Exemplo #1 Testando diferentes propriedades

    <?php
    var_dump(IntlChar::getPropertyValueName(IntlChar::PROPERTY_BLOCK, IntlChar::BLOCK_CODE_GREEK));
    var_dump(IntlChar::getPropertyValueName(IntlChar::PROPERTY_BLOCK, IntlChar::BLOCK_CODE_GREEK, IntlChar::SHORT_PROPERTY_NAME));
    var_dump(IntlChar::getPropertyValueName(IntlChar::PROPERTY_BLOCK, IntlChar::BLOCK_CODE_GREEK, IntlChar::LONG_PROPERTY_NAME));
    var_dump(IntlChar::getPropertyValueName(IntlChar::PROPERTY_BLOCK, IntlChar::BLOCK_CODE_GREEK, IntlChar::LONG_PROPERTY_NAME + 1));
    ?>

O exemplo acima produzirá:

    string(16) "Greek_And_Coptic"
    string(5) "Greek"
    string(16) "Greek_And_Coptic"
    bool(false)

# IntlChar::getUnicodeVersion

(PHP 7, PHP 8)

IntlChar::getUnicodeVersion — Obtém a versão do Unicode

### Descrição

public static function IntlChar::getUnicodeVersion(): array

Obtém informação sobre a versão do Unicode.

O array é preenchido com a informação de versão do padrão Unicode atualmente usado pela ICU. Por exemplo, Unicode versão 3.1.1 é representado por um array com os valores `[3, 1, 1, 0]`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array contendo o número de versão Unicode.

### Exemplos

Exemplo #1 Testando diferentes propriedades

    <?php
    var_dump(IntlChar::getUnicodeVersion());
    ?>

O exemplo acima produzirá:

    array(4) {
      [0]=>
      int(7)
      [1]=>
      int(0)
      [2]=>
      int(0)
      [3]=>
      int(0)
    }

### Veja Também

- IntlChar::charAge() - Obtém a "idade" do ponto de código

# IntlChar::hasBinaryProperty

(PHP 7, PHP 8)

IntlChar::hasBinaryProperty — Verifica uma propriedade binária Unicode para um ponto de código

### Descrição

public static function IntlChar::hasBinaryProperty(int|string `$codepoint`, int `$property`): ?bool

Verifica uma propriedade binária Unicode para um ponto de código.

Unicode, especialmente na versão 3.2, define muito mais propriedades que as originais definidas em UnicodeData.txt.

As APIs de propriedades têm o objetivo de refletir as propriedades Unicode como definidas no Banco de Dados de Caracteres Unicode (UCD) e nos Relatórios Técnicos Unicode. Para detalhes sobre as propriedades consulte » http://www.unicode.org/ucd/. Para nomes de propriedades Unicode consulte o arquivo da UCD, PropertyAliases.txt.

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).
`property`
  A propriedade Unicode a ser pesquisada (consulte as constantes `IntlChar::PROPERTY_*`).

### Valor Retornado

Retorna `true` ou `false` de acordo com o valor binário da propriedade Unicode para o `codepoint`. Também retorna `false` se `property` estiver fora dos limites ou se a versão Unicode não tiver dados desta propriedade ou se não tiver para este ponto de código. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes propriedades

    <?php
    var_dump(IntlChar::hasBinaryProperty("A", IntlChar::PROPERTY_ALPHABETIC));
    var_dump(IntlChar::hasBinaryProperty("A", IntlChar::PROPERTY_CASE_SENSITIVE));
    var_dump(IntlChar::hasBinaryProperty("A", IntlChar::PROPERTY_BIDI_MIRRORED));
    var_dump(IntlChar::hasBinaryProperty("[", IntlChar::PROPERTY_ALPHABETIC));
    var_dump(IntlChar::hasBinaryProperty("[", IntlChar::PROPERTY_CASE_SENSITIVE));
    var_dump(IntlChar::hasBinaryProperty("[", IntlChar::PROPERTY_BIDI_MIRRORED));
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(true)
    bool(false)
    bool(false)
    bool(false)
    bool(true)

### Veja Também

- IntlChar::getIntPropertyValue() - Obtém o valor de uma propriedade Unicode de um ponto de código
- IntlChar::getUnicodeVersion() - Obtém a versão do Unicode

# IntlChar::isalnum

(PHP 7, PHP 8)

IntlChar::isalnum — Verifica se um ponto de código é um caractere alfanumérico

### Descrição

public static function IntlChar::isalnum(int|string `$codepoint`): ?bool

Determina se o ponto de código especificado é um caractere alfanumérico (letra ou dígito). `true` para caracteres com categoria geral "L" (letras) e "Nd" (números de dígito decimal).

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna `true` se `codepoint` for um caractere alfanumérico, `false` se não for. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::isalnum("A"));
    var_dump(IntlChar::isalnum("1"));
    var_dump(IntlChar::isalnum("\u{2603}"));
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(true)
    bool(false)

### Veja Também

- IntlChar::isalpha() - Verifica se um ponto de código é uma letra
- IntlChar::isdigit() - Verifica se um ponto de código é um caractere de dígito
- ctype_alnum() - Verifica se os caracteres são alfanuméricos

# IntlChar::isalpha

(PHP 7, PHP 8)

IntlChar::isalpha — Verifica se um ponto de código é uma letra

### Descrição

public static function IntlChar::isalpha(int|string `$codepoint`): ?bool

Determina se o ponto de código especificado é uma letra. `true` para categoria geral "L" (letras).

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna `true` se `codepoint` é uma letra, `false` se não for. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::isalpha("A"));
    var_dump(IntlChar::isalpha("1"));
    var_dump(IntlChar::isalpha("\u{2603}"));
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(false)
    bool(false)

### Veja Também

- IntlChar::isalnum() - Verifica se um ponto de código é um caractere alfanumérico
- IntlChar::isdigit() - Verifica se um ponto de código é um caractere de dígito
- ctype_alpha() - Verifica se os caracteres são alfabéticos

# IntlChar::isbase

(PHP 7, PHP 8)

IntlChar::isbase — Verifica se um ponto de código é um caractere base

### Descrição

public static function IntlChar::isbase(int|string `$codepoint`): ?bool

Determina se o ponto de código especificado é um caractere base. `true` para categoria geral "L" (letras), "N" (números), "Mc" (marcas de combinação de espaçamento) e "Me" (marcas de envoltório).

> Nota:

> Isto é diferente da definição Unicode no capítulo 3.5, cláusula de conformidade clause D13, que define que caracteres base são todos os caracteres (não Cn) que não combinam graficamente com os caracteres precedentes (M) e que não são de controle (Cc) nem de formatação (Cf).

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna `true` se `codepoint` for um caractere base, `false` se não for. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::isbase("A"));
    var_dump(IntlChar::isbase("1"));
    var_dump(IntlChar::isbase("\u{2603}"));
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(true)
    bool(false)

### Veja Também

- IntlChar::isalpha() - Verifica se um ponto de código é uma letra
- IntlChar::isdigit() - Verifica se um ponto de código é um caractere de dígito

# IntlChar::isblank

(PHP 7, PHP 8)

IntlChar::isblank — Verifica se um ponto de código é um caractere "vazio" ou um "espaço horizontal"

### Descrição

public static function IntlChar::isblank(int|string `$codepoint`): ?bool

Determina se o ponto de código especificado é um "vazio" ou um "espaço horizontal", um caractere que visivelmente separa palavras em uma linha.

As definições a seguir são equivalentes:

- `true` para caracteres Unicode White_Space (espaço em branco) exceto para "controles de espaço vertical" que são os seguintes caracteres: U+000A (LF), U+000B (VT), U+000C (FF), U+000D (CR), U+0085 (NEL), U+2028 (LS) e U+2029 (PS)
- `true` para U+0009 (TAB) e caracteres com categoria geral "Zs" (separadores de espaço) exceto o Espaço de Largura Zero (ZWSP, U+200B).

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna `true` se `codepoint` for um caractere "vazio" ou de "espaço horizontal", `false` se não for. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::isblank("A"));
    var_dump(IntlChar::isblank(" "));
    var_dump(IntlChar::isblank("\t"));
    ?>

O exemplo acima produzirá:

    bool(false)
    bool(true)
    bool(true)

### Veja Também

- IntlChar::isspace() - Verifica se um ponto de código é um caractere de espaçamento
- IntlChar::isJavaSpaceChar() - Verifica se um ponto de código é um caractere de espaçamento de acordo com o Java
- IntlChar::isUWhiteSpace() - Verifica se um ponto de código tem a propriedade White_Space do Unicode
- IntlChar::isWhitespace() - Verifica se um ponto de código é um caractere de espaço em branco de acordo com a ICU

# IntlChar::iscntrl

(PHP 7, PHP 8)

IntlChar::iscntrl — Verifica se um ponto de código é um caractere de controle

### Descrição

public static function IntlChar::iscntrl(int|string `$codepoint`): ?bool

Determina se o ponto de código especificado é um caractere de controle.

Um caractere de controle é um dos seguintes:

- Caractere de controle ISO de 8 bits (U+0000..U+001f e U+007f..U+009f)
- `IntlChar::CHAR_CATEGORY_CONTROL_CHAR` (Cc)
- `IntlChar::CHAR_CATEGORY_FORMAT_CHAR` (Cf)
- `IntlChar::CHAR_CATEGORY_LINE_SEPARATOR` (Zl)
- `IntlChar::CHAR_CATEGORY_PARAGRAPH_SEPARATOR` (Zp)

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna `true` se `codepoint` for um caractere de controle, `false` se não for. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::iscntrl("A"));
    var_dump(IntlChar::iscntrl(" "));
    var_dump(IntlChar::iscntrl("\n"));
    var_dump(IntlChar::iscntrl("\u{200e}"));
    ?>

O exemplo acima produzirá:

    bool(false)
    bool(false)
    bool(true)
    bool(true)

### Veja Também

- IntlChar::isprint() - Verifica se um ponto de código é um caractere imprimível
- `IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT`
- ctype_cntrl() - Verifica se os caracteres são de controle

# IntlChar::isdefined

(PHP 7, PHP 8)

IntlChar::isdefined — Verifica se o ponto de código está definido

### Descrição

public static function IntlChar::isdefined(int|string `$codepoint`): ?bool

Determina se o ponto de código especificado está "definido", o que normalmente significa que está atribuído a um caractere.

`true` para categorias gerais diferentes de "Cn" (outros, não atribuídos).

> Nota:

> Observe que pontos de código que não são caracteres (ex.: U+FDD0) não estão "definidos" (eles são Cn), mas os pontos de código substitutos estão "definidos" (Cs).

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna `true` se `codepoint` for um caractere definido, `false` se não for. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::isdefined("A"));
    var_dump(IntlChar::isdefined(" "));
    var_dump(IntlChar::isdefined("\u{FDD0}"));
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(true)
    bool(false)

### Veja Também

- IntlChar::isdigit() - Verifica se um ponto de código é um caractere de dígito
- IntlChar::isalpha() - Verifica se um ponto de código é uma letra
- IntlChar::isalnum() - Verifica se um ponto de código é um caractere alfanumérico
- IntlChar::isupper() - Verifica se um ponto de código tem a categoria geral "Lu" (letra maiúscula)
- IntlChar::islower() - Verifica se um ponto de código é uma letra minúscula
- IntlChar::istitle() - Verifica se um ponto de código é uma letra com grafia mista

# IntlChar::isdigit

(PHP 7, PHP 8)

IntlChar::isdigit — Verifica se um ponto de código é um caractere de dígito

### Descrição

public static function IntlChar::isdigit(int|string `$codepoint`): ?bool

Determina se um ponto de código especificado é um caractere de dígito.

`true` para caracteres com categoria geral "Nd" (números de dígito decimal). A partir do Unicode 4, isto é o mesmo que testar se a propriedade Numeric_Type é Decimal.

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna `true` se `codepoint` é um caractere de dígito, `false` se não for. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::isdigit("A"));
    var_dump(IntlChar::isdigit("1"));
    var_dump(IntlChar::isdigit("\t"));
    ?>

O exemplo acima produzirá:

    bool(false)
    bool(true)
    bool(false)

### Veja Também

- IntlChar::isalpha() - Verifica se um ponto de código é uma letra
- IntlChar::isalnum() - Verifica se um ponto de código é um caractere alfanumérico
- IntlChar::isxdigit() - Verifica se um ponto de código é um dígito hexadecimal
- ctype_digit() - Verifica se os caracteres são numéricos

# IntlChar::isgraph

(PHP 7, PHP 8)

IntlChar::isgraph — Verifica se um ponto de código é um caractere gráfico

### Descrição

public static function IntlChar::isgraph(int|string `$codepoint`): ?bool

Determina se o ponto de código especificado é um caractere "gráfico" (imprimível, excluindo espaços).

`true` para todos os caracteres exceto aqueles com categoria geral "Cc" (códigos de controle), "Cf" (códigos de formatação), "Cs" (substitutos), "Cn" (não atribuídos), e "Z" (separadores).

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna `true` se `codepoint` for um caractere "gráfico", `false` se não for. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::isgraph("A"));
    var_dump(IntlChar::isgraph("1"));
    var_dump(IntlChar::isgraph("\u{2603}"));
    var_dump(IntlChar::isgraph("\n"));
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(true)
    bool(true)
    bool(false)

### Veja Também

- ctype_graph() - Verifica se os caracteres são imprimíveis exceto espaço

# IntlChar::isIDIgnorable

(PHP 7, PHP 8)

IntlChar::isIDIgnorable — Verifica se um ponto de código é um caractere ignorável

### Descrição

public static function IntlChar::isIDIgnorable(int|string `$codepoint`): ?bool

Determina se o caractere especificado deve ser considerado um caractere ignorável em um identificador.

`true` para caracteres com categoria geral "Cf" (códigos de formatação) assim como controles ISO que não são espaços em branco (U+0000..U+0008, U+000E..U+001B, U+007F..U+009F).

> Nota:

> Observe que o Unicode recomenda ignorar Cf (códigos de formatação).

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna `true` se `codepoint` for ignorável em identificadores, `false` se não for. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::isIDIgnorable("A"));
    var_dump(IntlChar::isIDIgnorable(" "));
    var_dump(IntlChar::isIDIgnorable("\u{007F}"));
    ?>

O exemplo acima produzirá:

    bool(false)
    bool(false)
    bool(true)

### Veja Também

- IntlChar::isIDStart() - Verifica se um ponto de código é permissível como o primeiro caractere em um identificador
- IntlChar::isIDPart() - Verifica se um ponto de código é permissível em um identificador
- `IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT`

# IntlChar::isIDPart

(PHP 7, PHP 8)

IntlChar::isIDPart — Verifica se um ponto de código é permissível em um identificador

### Descrição

public static function IntlChar::isIDPart(int|string `$codepoint`): ?bool

Determina se o caractere especificado é permissível em um identificador.

`true` para caracteres com categoria geral "L" (letras), "Nl" (números letras), "Nd" (dígitos decimais), "Mc" e "Mn" (marcas de combinação), "Pc" (pontuação de conexão) e u_isIDIgnorable(c).

> Nota:

> Isto é quase o mesmo que o ID_Continue do Unicode (`IntlChar::PROPERTY_ID_CONTINUE`) exceto que o Unicode recomenda ignorar Cf que seja menor que IntlChar::isIDIgnorable().

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna `true` se `codepoint` puder ocorrer em um identificador, `false` se não puder. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::isIDPart("A"));
    var_dump(IntlChar::isIDPart("$"));
    var_dump(IntlChar::isIDPart("\n"));
    var_dump(IntlChar::isIDPart("\u{2603}"));
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(false)
    bool(false)
    bool(false)

### Veja Também

- IntlChar::isIDIgnorable() - Verifica se um ponto de código é um caractere ignorável
- IntlChar::isIDStart() - Verifica se um ponto de código é permissível como o primeiro caractere em um identificador
- `IntlChar::PROPERTY_ID_CONTINUE`

# IntlChar::isIDStart

(PHP 7, PHP 8)

IntlChar::isIDStart — Verifica se um ponto de código é permissível como o primeiro caractere em um identificador

### Descrição

public static function IntlChar::isIDStart(int|string `$codepoint`): ?bool

Determina se o caractere especificado é permissível como o primeiro caractere em um identificador de acordo com o Unicode (O Padrão Unicode, Versão 3.0, capítulo 5.16, Identificadores).

`true` para caracteres com categoria geral "L" (letras) e "Nl" (letras números).

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna `true` se `codepoint` puder iniciar um identificador, `false` se não puder. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::isIDStart("A"));
    var_dump(IntlChar::isIDStart("$"));
    var_dump(IntlChar::isIDStart("\n"));
    var_dump(IntlChar::isIDStart("\u{2603}"));
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(false)
    bool(false)
    bool(false)

### Veja Também

- IntlChar::isalpha() - Verifica se um ponto de código é uma letra
- IntlChar::isIDPart() - Verifica se um ponto de código é permissível em um identificador
- `IntlChar::PROPERTY_ID_START`

# IntlChar::isISOControl

(PHP 7, PHP 8)

IntlChar::isISOControl — Verifica se o ponto de código é um código de controle ISO

### Descrição

public static function IntlChar::isISOControl(int|string `$codepoint`): ?bool

Determina se o ponto de código especificado é um código de controle ISO.

`true` para U+0000..U+001f e U+007f..U+009f (categoria geral "Cc").

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna `true` se `codepoint` for um código de controle ISO, `false` se não for. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::isISOControl(" "));
    var_dump(IntlChar::isISOControl("\n"));
    var_dump(IntlChar::isISOControl("\u{200e}"));
    ?>

O exemplo acima produzirá:

    bool(false)
    bool(true)
    bool(false)

### Veja Também

- IntlChar::iscntrl() - Verifica se um ponto de código é um caractere de controle

# IntlChar::isJavaIDPart

(PHP 7, PHP 8)

IntlChar::isJavaIDPart — Verifica se um ponto de código é permissível em um identificador Java

### Descrição

public static function IntlChar::isJavaIDPart(int|string `$codepoint`): ?bool

Determina se o caractere especificado é permissível em um identificador Java.

Em adição a IntlChar::isIDPart(), `true` para caracteres com categoria geral "Sc" (símbolos de moeda).

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna `true` se `codepoint` puder ocorrer em um identificador Java, `false` se não puder. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::isJavaIDPart("A"));
    var_dump(IntlChar::isJavaIDPart("$"));
    var_dump(IntlChar::isJavaIDPart("\n"));
    var_dump(IntlChar::isJavaIDPart("\u{2603}"));
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(true)
    bool(false)
    bool(false)

### Veja Também

- IntlChar::isIDIgnorable() - Verifica se um ponto de código é um caractere ignorável
- IntlChar::isIDPart() - Verifica se um ponto de código é permissível em um identificador
- IntlChar::isJavaIDStart() - Verifica se um ponto de código é permissível como o primeiro caractere em um identificador Java
- IntlChar::isalpha() - Verifica se um ponto de código é uma letra
- IntlChar::isdigit() - Verifica se um ponto de código é um caractere de dígito

# IntlChar::isJavaIDStart

(PHP 7, PHP 8)

IntlChar::isJavaIDStart — Verifica se um ponto de código é permissível como o primeiro caractere em um identificador Java

### Descrição

public static function IntlChar::isJavaIDStart(int|string `$codepoint`): ?bool

Determina se o caractere especificado é permissível como o início de um identificador Java.

Em adição a IntlChar::isIDStart(), `true` para caracteres com categoria geral "Sc" (símbolos de moeda) e "Pc" (pontuação de conexão).

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna `true` se `codepoint` puder iniciar um identificador Java, `false` se não puder. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::isJavaIDStart("A"));
    var_dump(IntlChar::isJavaIDStart("$"));
    var_dump(IntlChar::isJavaIDStart("\n"));
    var_dump(IntlChar::isJavaIDStart("\u{2603}"));
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(true)
    bool(false)
    bool(false)

### Veja Também

- IntlChar::isIDStart() - Verifica se um ponto de código é permissível como o primeiro caractere em um identificador
- IntlChar::isJavaIDPart() - Verifica se um ponto de código é permissível em um identificador Java
- IntlChar::isalpha() - Verifica se um ponto de código é uma letra

# IntlChar::isJavaSpaceChar

(PHP 7, PHP 8)

IntlChar::isJavaSpaceChar — Verifica se um ponto de código é um caractere de espaçamento de acordo com o Java

### Descrição

public static function IntlChar::isJavaSpaceChar(int|string `$codepoint`): ?bool

Determina se o ponto de código especificado é um caractere de espaçamento de acordo com o Java.

`true` para caracteres com categoria geral "Z" (separadores), que não incluem códigos de controle (ex.: TAB ou LF).

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna `true` se `codepoint` for um caractere de espaçamento de acordo com o Java, `false` se não for. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::isJavaSpaceChar("A"));
    var_dump(IntlChar::isJavaSpaceChar(" "));
    var_dump(IntlChar::isJavaSpaceChar("\n"));
    var_dump(IntlChar::isJavaSpaceChar("\t"));
    var_dump(IntlChar::isJavaSpaceChar("\u{00A0}"));
    ?>

O exemplo acima produzirá:

    bool(false)
    bool(true)
    bool(false)
    bool(false)
    bool(true)

### Veja Também

- IntlChar::isspace() - Verifica se um ponto de código é um caractere de espaçamento
- IntlChar::isWhitespace() - Verifica se um ponto de código é um caractere de espaço em branco de acordo com a ICU
- IntlChar::isUWhiteSpace() - Verifica se um ponto de código tem a propriedade White_Space do Unicode

# IntlChar::islower

(PHP 7, PHP 8)

IntlChar::islower — Verifica se um ponto de código é uma letra minúscula

### Descrição

public static function IntlChar::islower(int|string `$codepoint`): ?bool

Determina se o ponto de código especificado tem a categoria geral "Ll" (letra minúscula).

> Nota:

> Isto deixa passar alguns caracteres que também são letras minúsculas mas têm uma categoria geral diferente. Para incluir esses, use a função IntlChar::isULowercase().

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna `true` se `codepoint` for uma letra minúscula (Ll), `false` se não for. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::islower("A"));
    var_dump(IntlChar::islower("a"));
    var_dump(IntlChar::islower("Φ"));
    var_dump(IntlChar::islower("φ"));
    var_dump(IntlChar::islower("1"));
    ?>

O exemplo acima produzirá:

    bool(false)
    bool(true)
    bool(false)
    bool(true)
    bool(false)

### Veja Também

- IntlChar::isupper() - Verifica se um ponto de código tem a categoria geral "Lu" (letra maiúscula)
- IntlChar::istitle() - Verifica se um ponto de código é uma letra com grafia mista
- IntlChar::tolower() - Transforma o caractere Unicode em minúscula
- IntlChar::toupper() - Transforma um caractere Unicode em maiúscula
- `IntlChar::PROPERTY_LOWERCASE`
- ctype_lower() - Verifica se os caracteres são minúsculos

# IntlChar::isMirrored

(PHP 7, PHP 8)

IntlChar::isMirrored — Verifica se um ponto de código tem a propriedade Bidi_Mirrored

### Descrição

public static function IntlChar::isMirrored(int|string `$codepoint`): ?bool

Determina se o ponto de código têm a propriedade Bidi_Mirrored (espelhado bidirecional).

Esta propriedade é definida para caracteres que são normalmente usados em contextos da direita para a esquerda e precisam ser mostrados com um glifo "espelhado".

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna `true` se `codepoint` tiver a propriedade Bidi_Mirrored, `false` se não tiver. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::isMirrored("A"));
    var_dump(IntlChar::isMirrored("<"));
    var_dump(IntlChar::isMirrored("("));
    ?>

O exemplo acima produzirá:

    bool(false)
    bool(true)
    bool(true)

### Veja Também

- IntlChar::charMirror() - Obtém o caractere "espelho" para um ponto de código
- `IntlChar::PROPERTY_BIDI_MIRRORED`

# IntlChar::isprint

(PHP 7, PHP 8)

IntlChar::isprint — Verifica se um ponto de código é um caractere imprimível

### Descrição

public static function IntlChar::isprint(int|string `$codepoint`): ?bool

Determina se o ponto de código especificado é um caractere imprimível.

`true` para categoria geral diferente de "C" (controles).

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna `true` se `codepoint` for um caractere imprimível, `false` se não for. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::isprint("A"));
    var_dump(IntlChar::isprint(" "));
    var_dump(IntlChar::isprint("\n"));
    var_dump(IntlChar::isprint("\u{200e}"));
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(true)
    bool(false)
    bool(false)

### Veja Também

- IntlChar::iscntrl() - Verifica se um ponto de código é um caractere de controle
- `IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT`
- ctype_print() - Verifica se os caracteres são imprimíveis

# IntlChar::ispunct

(PHP 7, PHP 8)

IntlChar::ispunct — Verifica se um ponto de código é um caractere de pontuação

### Descrição

public static function IntlChar::ispunct(int|string `$codepoint`): ?bool

Determina se o ponto de código especificado é um caractere de pontuação.

`true` para caracteres com categoria geral "P" (pontuação).

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna `true` se `codepoint` for um caractere de pontuação, `false` se não for. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::ispunct("."));
    var_dump(IntlChar::ispunct(","));
    var_dump(IntlChar::ispunct("\n"));
    var_dump(IntlChar::ispunct("$"));

O exemplo acima produzirá:

    bool(true)
    bool(true)
    bool(false)
    bool(false)

### Veja Também

- ctype_punct() - Verifica se é um caractere imprimível que não é um caractere de espaço ou alfanumério

# IntlChar::isspace

(PHP 7, PHP 8)

IntlChar::isspace — Verifica se um ponto de código é um caractere de espaçamento

### Descrição

public static function IntlChar::isspace(int|string `$codepoint`): ?bool

Determina se o caractere especificado é um caractere de espaçamento ou não.

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna `true` se `codepoint` for um caractere de espaçamento, `false` se não for. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::isspace("A"));
    var_dump(IntlChar::isspace(" "));
    var_dump(IntlChar::isspace("\n"));
    var_dump(IntlChar::isspace("\t"));
    var_dump(IntlChar::isspace("\u{00A0}"));
    ?>

O exemplo acima produzirá:

    bool(false)
    bool(true)
    bool(true)
    bool(true)
    bool(true)

### Veja Também

- IntlChar::isJavaSpaceChar() - Verifica se um ponto de código é um caractere de espaçamento de acordo com o Java
- IntlChar::isWhitespace() - Verifica se um ponto de código é um caractere de espaço em branco de acordo com a ICU
- IntlChar::isUWhiteSpace() - Verifica se um ponto de código tem a propriedade White_Space do Unicode
- ctype_space() - Verifica se os caracteres são espaço em branco

# IntlChar::istitle

(PHP 7, PHP 8)

IntlChar::istitle — Verifica se um ponto de código é uma letra com grafia mista

### Descrição

public static function IntlChar::istitle(int|string `$codepoint`): ?bool

Determina se o ponto de código especificado é uma letra com grafia de título (um só caractere Unicode com dois glifos combinados, o primeiro maiúsculo e o segundo minúsculo, presente em algumas línguas como grego e croata).

`true` para a categoria geral "Lt" (letra com grafia de título).

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna `true` se `codepoint` for uma letra com grafia de título, `false` se não for. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    // Latin Capital Letter Dz with Caron U+01C4
    var_dump(IntlChar::istitle("Ǆ"));
    // Latin Capital Letter D with Small Letter Z with Caron U+01C5
    var_dump(IntlChar::istitle("ǅ"));
    // Latin Small Letter Dz with Caron U+01C6
    var_dump(IntlChar::istitle("ǆ"));

    // Greek Capital Letter Alpha with Prosgegrammeni U+1FBC
    var_dump(IntlChar::istitle("ᾼ"));
    // Greek Small Letter Alpha with Ypogegrammeni U+1FB3
    var_dump(IntlChar::istitle("ᾳ"));
    // Greek Capital Letter Alpha U+0391
    var_dump(IntlChar::istitle("Α"));
    ?>

O exemplo acima produzirá:

    bool(false)
    bool(true)
    bool(false)
    bool(true)
    bool(false)
    bool(false)

### Veja Também

- IntlChar::isupper() - Verifica se um ponto de código tem a categoria geral "Lu" (letra maiúscula)
- IntlChar::islower() - Verifica se um ponto de código é uma letra minúscula
- IntlChar::totitle() - Transforma o caractere Unicode em letra de título

# IntlChar::isUAlphabetic

(PHP 7, PHP 8)

IntlChar::isUAlphabetic — Verifica se um ponto de código tem a propriedade Alphabetic do Unicode

### Descrição

public static function IntlChar::isUAlphabetic(int|string `$codepoint`): ?bool

Verifica se um ponto de código tem a propriedade Alphabetic do Unicode.

É o mesmo que `IntlChar::hasBinaryProperty($codepoint, IntlChar::PROPERTY_ALPHABETIC)`

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna `true` se `codepoint` tiver a propriedade Alphabetic do Unicode, `false` se não tiver. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::isUAlphabetic("A"));
    var_dump(IntlChar::isUAlphabetic("1"));
    var_dump(IntlChar::isUAlphabetic("\u{2603}"));
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(false)
    bool(false)

### Veja Também

- IntlChar::isalpha() - Verifica se um ponto de código é uma letra
- IntlChar::hasBinaryProperty() - Verifica uma propriedade binária Unicode para um ponto de código
- `IntlChar::PROPERTY_ALPHABETIC`

# IntlChar::isULowercase

(PHP 7, PHP 8)

IntlChar::isULowercase — Verifica se um ponto de código tem a propriedade Lowercase do Unicode

### Descrição

public static function IntlChar::isULowercase(int|string `$codepoint`): ?bool

Verifica se um ponto de código tem a propriedade Lowercase do Unicode.

É o mesmo que `IntlChar::hasBinaryProperty($codepoint, IntlChar::PROPERTY_LOWERCASE)`

> Nota:

> É diferente de IntlChar::islower() e retornará `true` para mais caracteres.

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna `true` se `codepoint` tiver a propriedade Lowercase do Unicode, `false` se não tiver. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::isULowercase("A"));
    var_dump(IntlChar::isULowercase("a"));
    var_dump(IntlChar::isULowercase("Φ"));
    var_dump(IntlChar::isULowercase("φ"));
    var_dump(IntlChar::isULowercase("1"));
    ?>

O exemplo acima produzirá:

    bool(false)
    bool(true)
    bool(false)
    bool(true)
    bool(false)

### Veja Também

- IntlChar::islower() - Verifica se um ponto de código é uma letra minúscula
- IntlChar::hasBinaryProperty() - Verifica uma propriedade binária Unicode para um ponto de código
- `IntlChar::PROPERTY_LOWERCASE`

# IntlChar::isupper

(PHP 7, PHP 8)

IntlChar::isupper — Verifica se um ponto de código tem a categoria geral "Lu" (letra maiúscula)

### Descrição

public static function IntlChar::isupper(int|string `$codepoint`): ?bool

Determina se o ponto de código especificado tem a categoria geral "Lu" (letra maiúscula).

> Nota:

> Esta função deixa passar alguns caracteres que também são letras maiúsculas mas têm um valor diferente de categoria geral. Para incluir esses, use IntlChar::isUUppercase().

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna `true` se `codepoint` for uma letra maiúscula (Lu), `false` se não for. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::isupper("A"));
    var_dump(IntlChar::isupper("a"));
    var_dump(IntlChar::isupper("Φ"));
    var_dump(IntlChar::isupper("φ"));
    var_dump(IntlChar::isupper("1"));
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(false)
    bool(true)
    bool(false)
    bool(false)

### Veja Também

- IntlChar::islower() - Verifica se um ponto de código é uma letra minúscula
- IntlChar::istitle() - Verifica se um ponto de código é uma letra com grafia mista
- IntlChar::tolower() - Transforma o caractere Unicode em minúscula
- IntlChar::toupper() - Transforma um caractere Unicode em maiúscula
- `IntlChar::PROPERTY_UPPERCASE`
- ctype_upper() - Verifica se os caracteres são maiúsculos

# IntlChar::isUUppercase

(PHP 7, PHP 8)

IntlChar::isUUppercase — Verifica se um ponto de código tem a propriedade Uppercase do Unicode

### Descrição

public static function IntlChar::isUUppercase(int|string `$codepoint`): ?bool

Verifica se um ponto de código tem a propriedade Uppercase do Unicode.

É o mesmo que `IntlChar::hasBinaryProperty($codepoint, IntlChar::PROPERTY_UPPERCASE)`

> Nota:

> É diferente de IntlChar::isupper() e retornará `true` para mais caracteres.

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna `true` se `codepoint` tiver a propriedade Uppercase do Unicode, `false` se não tiver. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::isUUppercase("A"));
    var_dump(IntlChar::isUUppercase("a"));
    var_dump(IntlChar::isUUppercase("Φ"));
    var_dump(IntlChar::isUUppercase("φ"));
    var_dump(IntlChar::isUUppercase("1"));
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(false)
    bool(true)
    bool(false)
    bool(false)

### Veja Também

- IntlChar::isupper() - Verifica se um ponto de código tem a categoria geral "Lu" (letra maiúscula)
- IntlChar::hasBinaryProperty() - Verifica uma propriedade binária Unicode para um ponto de código
- `IntlChar::PROPERTY_UPPERCASE`

# IntlChar::isUWhiteSpace

(PHP 7, PHP 8)

IntlChar::isUWhiteSpace — Verifica se um ponto de código tem a propriedade White_Space do Unicode

### Descrição

public static function IntlChar::isUWhiteSpace(int|string `$codepoint`): ?bool

Verifica se um ponto de código tem a propriedade White_Space do Unicode.

É o mesmo que `IntlChar::hasBinaryProperty($codepoint, IntlChar::PROPERTY_WHITE_SPACE)`

> Nota:

> É diferente de IntlChar::isspace() e de IntlChar::isWhitespace().

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna `true` se `codepoint` tiver a propriedade White_Space do Unicode, `false` se não tiver. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::isUWhiteSpace("A"));
    var_dump(IntlChar::isUWhiteSpace(" "));
    var_dump(IntlChar::isUWhiteSpace("\n"));
    var_dump(IntlChar::isUWhiteSpace("\t"));
    var_dump(IntlChar::isUWhiteSpace("\u{00A0}"));
    ?>

O exemplo acima produzirá:

    bool(false)
    bool(true)
    bool(true)
    bool(true)
    bool(true)

### Veja Também

- IntlChar::isspace() - Verifica se um ponto de código é um caractere de espaçamento
- IntlChar::isWhitespace() - Verifica se um ponto de código é um caractere de espaço em branco de acordo com a ICU
- IntlChar::isJavaSpaceChar() - Verifica se um ponto de código é um caractere de espaçamento de acordo com o Java
- IntlChar::hasBinaryProperty() - Verifica uma propriedade binária Unicode para um ponto de código
- `IntlChar::PROPERTY_WHITE_SPACE`

# IntlChar::isWhitespace

(PHP 7, PHP 8)

IntlChar::isWhitespace — Verifica se um ponto de código é um caractere de espaço em branco de acordo com a ICU

### Descrição

public static function IntlChar::isWhitespace(int|string `$codepoint`): ?bool

Determina se o ponto de código especificado é um caractere de espaço em branco de acordo com a ICU.

Um caractere é considerado como um espaço em branco pela ICU se e somente se satisfizer um dos seguintes critérios:

- É um caractere separador Unicode (categorias "Z" = "Zs" ou "Zl" ou "Zp"), mas não pode ser também um espaço sem quebra (U+00A0 NBSP ou U+2007 Figure Space ou U+202F Narrow NBSP).
- É um U+0009 HORIZONTAL TABULATION.
- É um U+000A LINE FEED.
- É um U+000B VERTICAL TABULATION.
- É um U+000C FORM FEED.
- É um U+000D CARRIAGE RETURN.
- É um U+001C FILE SEPARATOR.
- É um U+001D GROUP SEPARATOR.
- É um U+001E RECORD SEPARATOR.
- É um U+001F UNIT SEPARATOR.

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna `true` se `codepoint` for um caractere de espaço em branco de acordo com a ICU, `false` se não for. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::iswhitespace("A"));
    var_dump(IntlChar::iswhitespace(" "));
    var_dump(IntlChar::iswhitespace("\n"));
    var_dump(IntlChar::iswhitespace("\t"));
    var_dump(IntlChar::iswhitespace("\u{00A0}"));
    ?>

O exemplo acima produzirá:

    bool(false)
    bool(true)
    bool(true)
    bool(true)
    bool(false)

### Veja Também

- IntlChar::isspace() - Verifica se um ponto de código é um caractere de espaçamento
- IntlChar::isJavaSpaceChar() - Verifica se um ponto de código é um caractere de espaçamento de acordo com o Java
- IntlChar::isUWhiteSpace() - Verifica se um ponto de código tem a propriedade White_Space do Unicode

# IntlChar::isxdigit

(PHP 7, PHP 8)

IntlChar::isxdigit — Verifica se um ponto de código é um dígito hexadecimal

### Descrição

public static function IntlChar::isxdigit(int|string `$codepoint`): ?bool

Determina se o ponto de código especificado é um dígito hexadecimal.

`true` para caracteres com categoria geral "Nd" (números de dígitos decimais) e também para letras latinas a-f e A-F tanto em ASCII quanto em ASCII de largura completa. (Isto é, para letras com pontos de código 0041..0046, 0061..0066, FF21..FF26, FF41..FF46.)

É equivalente a `IntlChar::digit($codepoint, 16) >= 0`.

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna `true` se `codepoint` for um caractere hexadecimal, `false` se não for. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::isxdigit("A"));
    var_dump(IntlChar::isxdigit("1"));
    var_dump(IntlChar::isxdigit("\u{2603}"));
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(true)
    bool(false)

### Notas

> Nota:

> Para restringir a definição de dígitos hexadecimais a apenas caracteres ASCII, use:

>     <?php
>     $isASCIIHexadecimal = IntlChar::ord($codepoint) <= 0x7F && IntlChar::isxdigit($codepoint);
>     ?>

### Veja Também

- IntlChar::isdigit() - Verifica se um ponto de código é um caractere de dígito
- ctype_xdigit() - Verifica se os caracteres representam um dígito hexadecimal

# IntlChar::ord

(PHP 7, PHP 8)

IntlChar::ord — Retorna o valor do ponto de código Unicode do caractere

### Descrição

public static function IntlChar::ord(int|string `$character`): ?int

Retorna o valor do ponto de código Unicode do caractere fornecido.

Esta função é complementar à IntlChar::chr().

### Parâmetros

`character`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna o valor do ponto de código Unicode como um inteiro.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::ord("A"));
    var_dump(IntlChar::ord(" "));
    var_dump(IntlChar::ord("\u{2603}"));
    ?>

O exemplo acima produzirá:

    int(65)
    int(32)
    int(9731)

### Veja Também

- IntlChar::chr() - Retorna um caractere Unicode por valor de ponto de código
- mb_ord() - Obtém o ponto de código Unicode do caractere
- ord() - Converte o primeiro byte de uma string para um valor entre 0 e 255

# IntlChar::tolower

(PHP 7, PHP 8)

IntlChar::tolower — Transforma o caractere Unicode em minúscula

### Descrição

public static function IntlChar::tolower(int|string `$codepoint`): int|string|null

O caractere é mapeado para a sua letra minúscula equivalente. Se o caractere não tiver minúscula equivalente, o caractere original em si é retornado.

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna o mapeamento do tipo Simple_Lowercase_Mapping do ponto de código, se houver; caso contrário, o próprio ponto de código. Retorna `null` em caso de falha.

O tipo do retorno é int, a menos que o ponto de código tenha sido passado como uma string UTF-8, caso em que uma string é retornada. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::tolower("A"));
    var_dump(IntlChar::tolower("a"));
    var_dump(IntlChar::tolower("Φ"));
    var_dump(IntlChar::tolower("φ"));
    var_dump(IntlChar::tolower("1"));
    var_dump(IntlChar::tolower(ord("A")));
    var_dump(IntlChar::tolower(ord("a")));
    ?>

O exemplo acima produzirá:

    string(1) "a"
    string(1) "a"
    string(2) "φ"
    string(2) "φ"
    string(1) "1"
    int(97)
    int(97)

### Veja Também

- IntlChar::totitle() - Transforma o caractere Unicode em letra de título
- IntlChar::toupper() - Transforma um caractere Unicode em maiúscula
- mb_strtolower() - Torna uma string minúscula

# IntlChar::totitle

(PHP 7, PHP 8)

IntlChar::totitle — Transforma o caractere Unicode em letra de título

### Descrição

public static function IntlChar::totitle(int|string `$codepoint`): int|string|null

O caractere informado é mapeado para seu equivalente em letra de título. Se o caractere não tiver letra de título equivalente, o caractere original em si é retornado.

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna o mapeamento Simple_Titlecase_Mapping do ponto de código, se houver; caso contrário, o próprio ponto de código. Retorna `null` em caso de falha.

O tipo do retorno é int, a menos que o ponto de código tenha sido passado como uma string UTF-8, caso em que uma string é retornada. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::totitle("Ǆ"));
    var_dump(IntlChar::totitle("ǆ"));
    var_dump(IntlChar::totitle("Φ"));
    var_dump(IntlChar::totitle("φ"));
    var_dump(IntlChar::totitle("1"));
    var_dump(IntlChar::totitle("ᾳ"));
    var_dump(IntlChar::totitle(ord("A")));
    ?>

O exemplo acima produzirá:

    string(1) "ǅ"
    string(1) "ǅ"
    string(2) "Φ"
    string(2) "φ"
    string(1) "1"
    string(1) "ᾼ"
    int(65)

### Veja Também

- IntlChar::tolower() - Transforma o caractere Unicode em minúscula
- IntlChar::toupper() - Transforma um caractere Unicode em maiúscula
- IntlChar::istitle() - Verifica se um ponto de código é uma letra com grafia mista
- mb_convert_case() - Realiza a conversão de caixa em uma string

# IntlChar::toupper

(PHP 7, PHP 8)

IntlChar::toupper — Transforma um caractere Unicode em maiúscula

### Descrição

public static function IntlChar::toupper(int|string `$codepoint`): int|string|null

O caractere fornecido é mapeado para seu equivalente maiúsculo. Se o caractere não tiver equivalente maiúsculo, o próprio caractere é retornado.

### Parâmetros

`codepoint`
  O valor int do ponto de código (por exemplo, `0x2603` para U+2603 SNOWMAN) ou o caractere codificado como uma string UTF-8 (por exemplo, `"\u{2603}"`).

### Valor Retornado

Retorna o mapeamento Simple_Uppercase_Mapping do ponto de código, se houver; caso contrário o próprio ponto de código.

O tipo do retorno é int, a menos que o ponto de código tenha sido passado como uma string UTF-8, caso em que uma string é retornada. Retorna `null` em caso de falha.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    var_dump(IntlChar::toupper("A"));
    var_dump(IntlChar::toupper("a"));
    var_dump(IntlChar::toupper("Φ"));
    var_dump(IntlChar::toupper("φ"));
    var_dump(IntlChar::toupper("1"));
    var_dump(IntlChar::toupper(ord("A")));
    var_dump(IntlChar::toupper(ord("a")));
    ?>

O exemplo acima produzirá:

    string(1) "A"
    string(1) "A"
    string(2) "Φ"
    string(2) "Φ"
    string(1) "1"
    int(65)
    int(65)

### Veja Também

- IntlChar::tolower() - Transforma o caractere Unicode em minúscula
- IntlChar::totitle() - Transforma o caractere Unicode em letra de título
- mb_strtoupper() - Faz uma string ficar em maiúsculas

## Índice

- IntlChar::charAge — Obtém a "idade" do ponto de código
- IntlChar::charDigitValue — Obtém o valor do dígito decimal de um caractere de dígito decimal
- IntlChar::charDirection — Obtém o valor de categoria bidirecional para um ponto de código
- IntlChar::charFromName — Encontra um caractere Unicode pelo nome e retorna seu valor de ponto de código
- IntlChar::charMirror — Obtém o caractere "espelho" para um ponto de código
- IntlChar::charName — Obtém o nome de um caractere Unicode
- IntlChar::charType — Obtém o valor da categoria geral para um ponto de código
- IntlChar::chr — Retorna um caractere Unicode por valor de ponto de código
- IntlChar::digit — Obtém o valor de dígito decimal de um ponto de código para uma base fornecida
- IntlChar::enumCharNames — Enumera todos os caracteres Unicode atribuídos dentro de um intervalo
- IntlChar::enumCharTypes — Enumera todos os pontos de código com suas categorias gerais Unicode
- IntlChar::foldCase — Converte maiúscula/minúscula em um ponto de código
- IntlChar::forDigit — Obtém a representação em caractere para um dígito e uma base fornecidos
- IntlChar::getBidiPairedBracket — Obtém o caractere de par de abertura/fechamento para um ponto de código
- IntlChar::getBlockCode — Obtém o bloco de alocação Unicode contendo um ponto de código
- IntlChar::getCombiningClass — Obtém a classe de combinação de um ponto de código
- IntlChar::getFC_NFKC_Closure — Obtém a propriedade FC_NFKC_Closure para um ponto de código
- IntlChar::getIntPropertyMaxValue — Obtém o valor máximo para uma propriedade Unicode
- IntlChar::getIntPropertyMinValue — Obtém o valor mínimo para uma propriedade Unicode
- IntlChar::getIntPropertyValue — Obtém o valor de uma propriedade Unicode de um ponto de código
- IntlChar::getNumericValue — Obtém o valor numérico para um ponto de código Unicode
- IntlChar::getPropertyEnum — Obtém o valor da constante da propriedade para uma propriedade informada
- IntlChar::getPropertyName — Obtém o nome Unicode de uma propriedade
- IntlChar::getPropertyValueEnum — Obtém o valor da propriedade para um nome de valor fornecido
- IntlChar::getPropertyValueName — Obtém o nome Unicode para um valor de propriedade
- IntlChar::getUnicodeVersion — Obtém a versão do Unicode
- IntlChar::hasBinaryProperty — Verifica uma propriedade binária Unicode para um ponto de código
- IntlChar::isalnum — Verifica se um ponto de código é um caractere alfanumérico
- IntlChar::isalpha — Verifica se um ponto de código é uma letra
- IntlChar::isbase — Verifica se um ponto de código é um caractere base
- IntlChar::isblank — Verifica se um ponto de código é um caractere "vazio" ou um "espaço horizontal"
- IntlChar::iscntrl — Verifica se um ponto de código é um caractere de controle
- IntlChar::isdefined — Verifica se o ponto de código está definido
- IntlChar::isdigit — Verifica se um ponto de código é um caractere de dígito
- IntlChar::isgraph — Verifica se um ponto de código é um caractere gráfico
- IntlChar::isIDIgnorable — Verifica se um ponto de código é um caractere ignorável
- IntlChar::isIDPart — Verifica se um ponto de código é permissível em um identificador
- IntlChar::isIDStart — Verifica se um ponto de código é permissível como o primeiro caractere em um identificador
- IntlChar::isISOControl — Verifica se o ponto de código é um código de controle ISO
- IntlChar::isJavaIDPart — Verifica se um ponto de código é permissível em um identificador Java
- IntlChar::isJavaIDStart — Verifica se um ponto de código é permissível como o primeiro caractere em um identificador Java
- IntlChar::isJavaSpaceChar — Verifica se um ponto de código é um caractere de espaçamento de acordo com o Java
- IntlChar::islower — Verifica se um ponto de código é uma letra minúscula
- IntlChar::isMirrored — Verifica se um ponto de código tem a propriedade Bidi_Mirrored
- IntlChar::isprint — Verifica se um ponto de código é um caractere imprimível
- IntlChar::ispunct — Verifica se um ponto de código é um caractere de pontuação
- IntlChar::isspace — Verifica se um ponto de código é um caractere de espaçamento
- IntlChar::istitle — Verifica se um ponto de código é uma letra com grafia mista
- IntlChar::isUAlphabetic — Verifica se um ponto de código tem a propriedade Alphabetic do Unicode
- IntlChar::isULowercase — Verifica se um ponto de código tem a propriedade Lowercase do Unicode
- IntlChar::isupper — Verifica se um ponto de código tem a categoria geral "Lu" (letra maiúscula)
- IntlChar::isUUppercase — Verifica se um ponto de código tem a propriedade Uppercase do Unicode
- IntlChar::isUWhiteSpace — Verifica se um ponto de código tem a propriedade White_Space do Unicode
- IntlChar::isWhitespace — Verifica se um ponto de código é um caractere de espaço em branco de acordo com a ICU
- IntlChar::isxdigit — Verifica se um ponto de código é um dígito hexadecimal
- IntlChar::ord — Retorna o valor do ponto de código Unicode do caractere
- IntlChar::tolower — Transforma o caractere Unicode em minúscula
- IntlChar::totitle — Transforma o caractere Unicode em letra de título
- IntlChar::toupper — Transforma um caractere Unicode em maiúscula

# Classe de exceção para erros da extensão Intl

(PHP 5 > 5.5.0, PHP 7, PHP 8, PECL intl > 3.0.0a1)

## Introdução

Esta classe é usada para gerar exceções quando erros ocorrerem dentro das funções Intl. Tais exceções somente são geradas quando a opção intl.use_exceptions estiver habilitada.

## Resumo da classe

class IntlException extends Exception {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos herdados */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# A classe IntlIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introdução

Essa classe representa objetos iteradores em toda extensão intl sempre que o iterador não puder ser identificado com qualquer outro objeto fornecido pela extensão. O objeto iterador distinto usado internamente pelo construtor `foreach` só pode ser obtido (na parte relevante aqui) a partir de objetos, então objetos dessa classe tem o propósito de fornecer o gancho através da qual este objeto interno pode ser obtido. Como uma conveniência, essa classe também implementa a interface Iterator, permitindo que a coleção de valores sejam navegados usando os métodos definidos nessa interface. Ambos os métodos e objetos iteradores internos fornecidos pelo `foreach` são apoiados pelo mesmo estado (ex. a posição do iterador e o seu valor atual).

As subclasses podem fornecer funcionalidades mais valiosas.

## Resumo da classe

class IntlIterator implements Iterator {
/* Métodos */
public function current(): mixed
public function key(): mixed
public function next(): void
public function rewind(): void
public function valid(): bool
}

# IntlIterator::current

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::current — Retorna o elemento atual

### Descrição

public function IntlIterator::current(): mixed

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# IntlIterator::key

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::key — Retorna a chave do elemento atual

### Descrição

public function IntlIterator::key(): mixed

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# IntlIterator::next

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::next — Avança para o próximo elemento

### Descrição

public function IntlIterator::next(): void

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# IntlIterator::rewind

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::rewind — Rebobina o iterador para o primeiro elemento

### Descrição

public function IntlIterator::rewind(): void

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# IntlIterator::valid

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::valid — Verifica se a posição atual é válida

### Descrição

public function IntlIterator::valid(): bool

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

## Índice

- IntlIterator::current — Retorna o elemento atual
- IntlIterator::key — Retorna a chave do elemento atual
- IntlIterator::next — Avança para o próximo elemento
- IntlIterator::rewind — Rebobina o iterador para o primeiro elemento
- IntlIterator::valid — Verifica se a posição atual é válida

# Funções de Intl

# intl_error_name

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

intl_error_name — Obtém nome simbólico para um código de erro informado

### Descrição

function intl_error_name(int `$errorCode`): string

Retorna o nome do código de erro ICU.

### Parâmetros

`errorCode`

  Código de erro ICU.

### Valor Retornado

A string retornada será igual ao nome da constante do código de erro..

### Exemplos

Exemplo #1 Exemplo de intl_error_name()

    <?php
    $coll     = collator_create( 'en_RU' );
    $err_code = collator_get_error_code( $coll );

    printf( "Nome simbólico para %d é %s\n.", $err_code, intl_error_name( $err_code ) );
    ?>

O exemplo acima produzirá algo semelhante a:

    Nome simbólico para -128 é U_USING_FALLBACK_WARNING.

### Veja Também

- intl_is_failure() - Verifica se o código de erro fornecido indica falha
- intl_get_error_code() - Obtém o último código de erro
- intl_get_error_message() - Obtém a descrição do último erro

# intl_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

intl_get_error_code — Obtém o último código de erro

### Descrição

function intl_get_error_code(): int

Útil para lidar com erros ocorridos em métods estáticos quando não existe objeto a partir do qual o erro seria obtido.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Código de erro retornado pela última chamada de função da API.

### Exemplos

Exemplo #1 Exemplo de intl_get_error_code()

    <?php
    $coll = collator_create( '<bad_param>' );
    if( !$coll ) {
        handle_error( intl_get_error_code() );
    }
    ?>

### Veja Também

- intl_is_failure() - Verifica se o código de erro fornecido indica falha
- intl_error_name() - Obtém nome simbólico para um código de erro informado
- intl_get_error_message() - Obtém a descrição do último erro
- collator_get_error_code() - Obtém o último código de erro do agrupador
- numfmt_get_error_code() - Obtém o último código de erro do formatador

# intl_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

intl_get_error_message — Obtém a descrição do último erro

### Descrição

function intl_get_error_message(): string

Obtém mensagem de erro da última função de internacionalização chamada.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Descrição de um erro ocorrido na última chamada de função da API.

### Exemplos

Exemplo #1 Exemplo de intl_get_error_message()

    <?php
    if( Collator::getAvailableLocales() === false ) {
        show_error( intl_get_error_message() );
    }
    ?>

### Veja Também

- intl_error_name() - Obtém nome simbólico para um código de erro informado
- intl_get_error_code() - Obtém o último código de erro
- intl_is_failure() - Verifica se o código de erro fornecido indica falha
- collator_get_error_message() - Obtém o texto para o último código de erro do agrupador
- numfmt_get_error_message() - Obtém a última mensagem de erro do formatador

# intl_is_failure

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

intl_is_failure — Verifica se o código de erro fornecido indica falha

### Descrição

function intl_is_failure(int `$errorCode`): bool

Verifica se o código de erro fornecido indica falha

### Parâmetros

`errorCode`

  É um valor retornado pelas funções intl_get_error_code() ou collator_get_error_code() .

### Valor Retornado

`true` se o código indica alguma falha e `false` em caso de sucesso ou de um alerta.

### Exemplos

Exemplo #1 Exemplo de intl_is_failure()

    <?php
    function check( $err_code )
    {
        var_export( intl_is_failure( $err_code ) );
        echo "\n";
    }

    check( U_ZERO_ERROR );
    check( U_USING_FALLBACK_WARNING );
    check( U_ILLEGAL_ARGUMENT_ERROR );
    ?>

O exemplo acima produzirá algo semelhante a:

    false
    false
    true

### Veja Também

- intl_get_error_code() - Obtém o último código de erro
- collator_get_error_code() - Obtém o último código de erro do agrupador
- Collator-getErrorCode()

## Índice

- intl_error_name — Obtém nome simbólico para um código de erro informado
- intl_get_error_code — Obtém o último código de erro
- intl_get_error_message — Obtém a descrição do último erro
- intl_is_failure — Verifica se o código de erro fornecido indica falha

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
- Constantes predefinidas
- Exemplos
  - Uso básico desta extensão
- Collator — A classe Collator
  - Collator::asort — Ordena array mantendo associação de índice
  - Collator::compare — Compara duas strings Unicode
  - Collator::__construct — Cria um agrupador (Collator)
  - Collator::create — Cria um agrupador
  - Collator::getAttribute — Obtém o valor de atributo de um agrupador
  - Collator::getErrorCode — Obtém o último código de erro do agrupador
  - Collator::getErrorMessage — Obtém o texto para o último código de erro do agrupador
  - Collator::getLocale — Obtém o nome da localidade do agrupador
  - Collator::getSortKey — Obtém a chave de ordenação de uma string
  - Collator::getStrength — Obtém a força atual de agrupamento
  - Collator::setAttribute — Define atributo do agrupador
  - Collator::setStrength — Define a força do agrupador
  - Collator::sort — Ordena um array usando o agrupador especificado
  - Collator::sortWithSortKeys — Ordena um array usando agrupador e chaves de ordenação especificados
- NumberFormatter — A classe NumberFormatter
  - NumberFormatter::create — Cria um formatador de número
  - NumberFormatter::format — Formata um número
  - NumberFormatter::formatCurrency — Formata um valor de moeda
  - NumberFormatter::getAttribute — Obtém um atributo
  - NumberFormatter::getErrorCode — Obtém o último código de erro do formatador
  - NumberFormatter::getErrorMessage — Obtém a última mensagem de erro do formatador
  - NumberFormatter::getLocale — Obtém a localidade do formatador
  - NumberFormatter::getPattern — Obtém padrão do formatador
  - NumberFormatter::getSymbol — Obtém um valor de símbolo
  - NumberFormatter::getTextAttribute — Obtém um atributo de texto
  - NumberFormatter::parse — Interpreta um número
  - NumberFormatter::parseCurrency — Interpreta um valor monetário
  - NumberFormatter::setAttribute — Define um atributo
  - NumberFormatter::setPattern — Define o padrão do formatador
  - NumberFormatter::setSymbol — Define um valor de símbolo
  - NumberFormatter::setTextAttribute — Define um atributo de texto
- Locale — A classe Locale
  - Locale::acceptFromHttp — Tenta descobrir a melhor localidade disponível baseado no cabeçalho HTTP "Accept-Language"
  - Locale::canonicalize — Canoniza a string de localidade
  - Locale::composeLocale — Retorna ID de localidade corretamente ordenado e delimitado
  - Locale::filterMatches — Verifica se um filtro de etiqueta de língua corresponde à localidade
  - Locale::getAllVariants — Obtém as variantes para a localidade
  - Locale::getDefault — Obtém o valor de localidade padrão da variável global de INTL 'default_locale'
  - Locale::getDisplayLanguage — Retorna um nome apropriadamente localizado para a língua da localidade
  - Locale::getDisplayName — Retorna um nome apropriadamente localizado para a localidade
  - Locale::getDisplayRegion — Retorna um nome apropriadamente localizado para a região da localidade
  - Locale::getDisplayScript — Retorna um nome apropriadamente localizado para o tipo de escrita da localidade
  - Locale::getDisplayVariant — Retorna um nome apropriadamente localizado para as variantes da localidade
  - Locale::getKeywords — Obtém as palavras-chave para a localidade
  - Locale::getPrimaryLanguage — Obtém a língua primária para a localidade
  - Locale::getRegion — Obtém a região para a localidade
  - Locale::getScript — Obtém o tipo de escrita para a localidade
  - Locale::isRightToLeft — Verifica se uma localidade usa um sistema de escrita da direita para a esquerda
  - Locale::lookup — Pesquisa a lista de etiquetas de língua pela melhor correspondência à língua
  - Locale::parseLocale — Retorna um array de chaves-valores de elementos de sub-etiquetas de ID de localidade
  - Locale::setDefault — Define a localidade padrão em tempo de execução
- Normalizer — A classe Normalizer
  - Normalizer::getRawDecomposition — Obtém a propriedade Decomposition_Mapping para o ponto de código UTF-8 fornecido
  - Normalizer::isNormalized — Verifica se a string fornecida já está normalizada na forma especificada.
  - Normalizer::normalize — Normaliza a entrada fornecida e retorna a string normalizada
- MessageFormatter — A classe MessageFormatter
  - MessageFormatter::create — Constrói um novo formatador de mensagem
  - MessageFormatter::format — Formata a mensagem
  - MessageFormatter::formatMessage — Formata uma mensagem rapidamente
  - MessageFormatter::getErrorCode — Obtém o código de erro da última operação
  - MessageFormatter::getErrorMessage — Obtém o texto do erro da última operação
  - MessageFormatter::getLocale — Obtém a localidade para a qual o formatador foi criado
  - MessageFormatter::getPattern — Obtém o modelo usado pelo formatador
  - MessageFormatter::parse — Interpreta a string de entrada de acordo com o modelo
  - MessageFormatter::parseMessage — Interpreta rapidamente a string de entrada
  - MessageFormatter::setPattern — Define o modelo usado pelo formatador
- IntlCalendar — A classe IntlCalendar
  - IntlCalendar::add — Adiciona uma quantidade de tempo (com sinal) a um campo
  - IntlCalendar::after — Informa se o instante de tempo deste objeto é posterior ao instante do objeto passado
  - IntlCalendar::before — Informa se o instante de tempo deste objeto é anterior ao instante do objeto passado
  - IntlCalendar::clear — Limpa um campo ou todos os campos
  - IntlCalendar::__construct — Construtor privado para não permitir instanciação
  - IntlCalendar::createInstance — Cria um novo IntlCalendar
  - IntlCalendar::equals — Compara horários de dois objetos IntlCalendar para igualidade
  - IntlCalendar::fieldDifference — Calcula a diferença entre o horário fornecido e o horário deste objeto
  - IntlCalendar::fromDateTime — Cria um IntlCalendar a partir de um objeto DateTime ou uma string
  - IntlCalendar::get — Obtém o valor de um campo
  - IntlCalendar::getActualMaximum — O valor máximo para um campo, considerando o horário atual do objeto
  - IntlCalendar::getActualMinimum — O valor mínimo para um campo, considerando o horário atual do objeto
  - IntlCalendar::getAvailableLocales — Obtém um array de localidades para as quais existem dados
  - IntlCalendar::getDayOfWeekType — Informa se o dia é dia de semana, de final de semana ou de transição entre os dois
  - IntlCalendar::getErrorCode — Obtém o último código de erro no objeto
  - IntlCalendar::getErrorMessage — Obtém a última mensagem de erro no objeto
  - IntlCalendar::getFirstDayOfWeek — Obtém o primeiro dia da semana para a localidade do calendário
  - IntlCalendar::getGreatestMinimum — Obtém o maior valor mínimo local para um campo
  - IntlCalendar::getKeywordValuesForLocale — Obtém um conjunto de valores de palavras-chaves de localidade
  - IntlCalendar::getLeastMaximum — Obtém o menor máximo local para um campo
  - IntlCalendar::getLocale — Obtém a localidade associada com o objeto
  - IntlCalendar::getMaximum — Obtém o valor máximo global para um campo
  - IntlCalendar::getMinimalDaysInFirstWeek — Obtém o número mínimo de dias que a primeira semana do ano ou do mês pode ter
  - IntlCalendar::getMinimum — Obtém o mínimo global para um campo
  - IntlCalendar::getNow — Obtém um número representando o horário atual
  - IntlCalendar::getRepeatedWallTimeOption — Obtém o comportamento ao lidar com o horário de relógio repetido
  - IntlCalendar::getSkippedWallTimeOption — Obtém o comportamento para o horário de relógio saltado
  - IntlCalendar::getTime — Obtém o horário atualmente representado pelo objeto
  - IntlCalendar::getTimeZone — Obtém o fuso horário do objeto
  - IntlCalendar::getType — Obtém o tipo de calendário
  - IntlCalendar::getWeekendTransition — Obtém o horário do dia no qual o final de semana inicia ou termina
  - IntlCalendar::inDaylightTime — Informa se o horário do objeto está no horário de verão
  - IntlCalendar::isEquivalentTo — Verifica se outro calendário é igual exceto pelo horário
  - IntlCalendar::isLenient — Verifica se a interpretação de data/horário está no modo leniente
  - IntlCalendar::isSet — Verifica se um campo está definido
  - IntlCalendar::isWeekend — Verifica se uma data e um horário estão no final de semana
  - IntlCalendar::roll — Adiciona valor ao campo sem transferir para campos mais significativos
  - IntlCalendar::set — Define um campo de horário ou vários campos comuns de uma vez
  - IntlCalendar::setDate — Define campos de data
  - IntlCalendar::setDateTime — Define campos de data e horário
  - IntlCalendar::setFirstDayOfWeek — Define o dia da semana no qual a semana inicia
  - IntlCalendar::setLenient — Define se a interpretação de data/horário deve ser leniente
  - IntlCalendar::setMinimalDaysInFirstWeek — Define o número mínimo de dias que a primeira semana do ano ou do mês pode ter
  - IntlCalendar::setRepeatedWallTimeOption — Define o comportamento ao lidar com horário de relógio repetido ao sair do horário de verão
  - IntlCalendar::setSkippedWallTimeOption — Define o comportamento ao lidar com horário de relógio saltado ao entrar no horário de verão
  - IntlCalendar::setTime — Define o horário do calendário em milissegundos desde a época de referência
  - IntlCalendar::setTimeZone — Define o fuso horário usado por este calendário
  - IntlCalendar::toDateTime — Converte um objeto IntlCalendar para um DateTime
- IntlGregorianCalendar — A classe IntlGregorianCalendar
  - IntlGregorianCalendar::__construct — Cria um objeto de calendário gregoriano
  - IntlGregorianCalendar::createFromDate — Cria uma nova instância de IntlGregorianCalendar a partir de uma data
  - IntlGregorianCalendar::createFromDateTime — Cria uma instância de IntlGregorianCalendar a partir de data e horário
  - IntlGregorianCalendar::getGregorianChange — Obtém a data de mudança do calendário gregoriano
  - IntlGregorianCalendar::isLeapYear — Determina se o ano é bissexto
  - IntlGregorianCalendar::setGregorianChange — Define a data de mudança do calendário gregoriano
- IntlTimeZone — A classe IntlTimeZone
  - IntlTimeZone::__construct — Construtor privado para não permitir instanciação direta
  - IntlTimeZone::countEquivalentIDs — Obtém o número de IDs no grupo de equivalÇencia que inclui o ID informado
  - IntlTimeZone::createDefault — Cria uma nova cópia do fuso horário padrão para este host
  - IntlTimeZone::createEnumeration — Obtém uma enumeração a partir de IDs de fuso horário associados com o país informado ou com o deslocamento UTC
  - IntlTimeZone::createTimeZone — Cria um objeto IntlTimeZone para o ID informado
  - IntlTimeZone::createTimeZoneIDEnumeration — Obtém uma enumeração a partir de IDs de fuso horário do sistema com as condições de filtro informadas
  - IntlTimeZone::fromDateTimeZone — Cria um objeto IntlTimeZone a partir de um DateTimeZone
  - IntlTimeZone::getCanonicalID — Obtém o ID do fuso horário de sistema canônico ou o cutomizado normalizado para o ID de fuso horário informado
  - IntlTimeZone::getDisplayName — Obtém o nome do fuso horário adequado para apresentação ao usuário
  - IntlTimeZone::getDSTSavings — Obtém a quantidade de tempo a ser adicionado ao horário local padrão para obter o horário local real de relógio
  - IntlTimeZone::getEquivalentID — Obtém um ID no grupo de equivalência que inclui o ID informado
  - IntlTimeZone::getErrorCode — Obtém o último código de erro no objeto
  - IntlTimeZone::getErrorMessage — Obtém a última mensagem de erro no objeto
  - IntlTimeZone::getGMT — Cria um fuso horário GMT (UTC)
  - IntlTimeZone::getIanaID — Traduz um identificador de fuso horário para seu equivalente IANA
  - IntlTimeZone::getID — Obtém o ID do fuso horário
  - IntlTimeZone::getIDForWindowsID — Traduz um fuso horário do Windows para um fuso horário de sistema
  - IntlTimeZone::getOffset — Obtém o deslocamento UTC padrão e o deslocamento com horário de verão para um determinado timestamp Unix
  - IntlTimeZone::getRawOffset — Obtém o deslocamento UTC puro (antes de considerar horário de verão)
  - IntlTimeZone::getRegion — Obtém o código da região associada com o ID de fuso horário de sistema informado
  - IntlTimeZone::getTZDataVersion — Obtém a versão de dados de fuso horário atualmente usados pela ICU
  - IntlTimeZone::getUnknown — Obtém o fuso horário "desconhecido"
  - IntlTimeZone::getWindowsID — Traduz um fuso horário de sistema em um fuso horário do Windows
  - IntlTimeZone::hasSameRules — Verifica se um fuso horário tem as mesmas regras e deslocamentos de um outro
  - IntlTimeZone::toDateTimeZone — Converte em um objeto DateTimeZone
  - IntlTimeZone::useDaylightTime — Verifica se o fuso horário usa horário de verão
- IntlDateFormatter — A classe IntlDateFormatter
  - IntlDateFormatter::create — Cria um formatador de data
  - IntlDateFormatter::format — Formata data/horário como uma string
  - IntlDateFormatter::formatObject — Formata um objeto
  - IntlDateFormatter::getCalendar — Obtém o tipo de calendário usado para o IntlDateFormatter
  - IntlDateFormatter::getDateType — Obtém o tipo de data usado para o IntlDateFormatter
  - IntlDateFormatter::getErrorCode — Obtém o código de erro da última operação
  - IntlDateFormatter::getErrorMessage — Obtém a mensagem de erro da última operação
  - IntlDateFormatter::getLocale — Obtém a localidade usada pelo formatador
  - IntlDateFormatter::getPattern — Obtém o modelo usado para o IntlDateFormatter
  - IntlDateFormatter::getTimeType — Obtém o tipo de horário usado para o IntlDateFormatter
  - IntlDateFormatter::getTimeZoneId — Obtém o identificador de fuso horário usado para o IntlDateFormatter
  - IntlDateFormatter::getCalendarObject — Obtém uma cópia do objeto de calendário do formatador
  - IntlDateFormatter::getTimeZone — Obtem o fuso horário do formatador
  - IntlDateFormatter::isLenient — Obtém a leniência usada para o IntlDateFormatter
  - IntlDateFormatter::localtime — Interpreta uma string para um valor de horário baseado em campos
  - IntlDateFormatter::parse — Interpreta uma string para uma valor de timestamp
  - IntlDateFormatter::parseToCalendar — Analisa uma string e a converte em um timestamp, atualizando um calendário aberto
  - IntlDateFormatter::setCalendar — Define o tipo de calendário usado pelo formatador
  - IntlDateFormatter::setLenient — Define a leniência do interpretador
  - IntlDateFormatter::setPattern — Define o modelo usado para o IntlDateFormatter
  - IntlDateFormatter::setTimeZone — Define o fuso horário do formatador
- ResourceBundle — A classe ResourceBundle
  - ResourceBundle::count — Obtém o número de elementos no pacote
  - ResourceBundle::create — Cria um pacote de recursos
  - ResourceBundle::get — Obtém os dados do pacote
  - ResourceBundle::getErrorCode — Obtém o código do último erro gerado pelo pacote.
  - ResourceBundle::getErrorMessage — Obtém a última mensagem de erro gerada pelo pacote
  - ResourceBundle::getLocales — Obtém as localidades suportadas
- Spoofchecker — A classe Spoofchecker
  - Spoofchecker::areConfusable — Verifica se as strings fornecidas podem ser confundidas
  - Spoofchecker::__construct — Construtor
  - Spoofchecker::isSuspicious — Verifica se um texto fornecido contém algum caractere suspeito
  - Spoofchecker::setAllowedChars — Define o conjunto de caracteres permitidos ao executar verificações
  - Spoofchecker::setAllowedLocales — Localidades a usar nas verificações executadas
  - Spoofchecker::setChecks — Define as verificações que serão executadas
  - Spoofchecker::setRestrictionLevel — Define o nível de restrição
- Transliterator — A classe Transliterator
  - Transliterator::__construct — Construtor privado para proibir instanciação
  - Transliterator::create — Cria um transliterador
  - Transliterator::createFromRules — Cria um transliterador a partir de regras
  - Transliterator::createInverse — Cria um transliterador inverso
  - Transliterator::getErrorCode — Obtém o último código de erro
  - Transliterator::getErrorMessage — Obtém a última mensagem de erro
  - Transliterator::listIDs — Obtém IDs de transliteradores
  - Transliterator::transliterate — Translitera uma string
- IntlBreakIterator — A classe IntlBreakIterator
  - IntlBreakIterator::__construct — Construtor privado para não permitir instanciação
  - IntlBreakIterator::createCharacterInstance — Cria um iterador de quebra para limites de sequências de combinação de caracteres
  - IntlBreakIterator::createCodePointInstance — Cria um iterador de quebra para limites de pontos de código
  - IntlBreakIterator::createLineInstance — Cria um iterador de quebra para quebras de linha logicamente possíveis
  - IntlBreakIterator::createSentenceInstance — Cria um iterador de quebra para separação de sentenças
  - IntlBreakIterator::createTitleInstance — Cria um iterador para quebras de letras de título
  - IntlBreakIterator::createWordInstance — Cria um iterador de quebra para separação de palavras
  - IntlBreakIterator::current — Obtém o índice da posição atual
  - IntlBreakIterator::first — Define a posição para o primeiro caractere no texto
  - IntlBreakIterator::following — Avança o iterador para o primeiro limite após o deslocamento especificado
  - IntlBreakIterator::getErrorCode — Obtém o último código de erro no objeto
  - IntlBreakIterator::getErrorMessage — Obtém a última mensagem de erro no objeto
  - IntlBreakIterator::getLocale — Obtém a localidade associada com o objeto
  - IntlBreakIterator::getPartsIterator — Cria um iterador para navegar por fragmentos entre limites
  - IntlBreakIterator::getText — Obtém o texto sendo percorrido
  - IntlBreakIterator::isBoundary — Indica se uma posição é um posição de limite
  - IntlBreakIterator::last — Define a posição do iterador para um índice além do último caractere
  - IntlBreakIterator::next — Avança o iterador para o próximo limite
  - IntlBreakIterator::preceding — Define a posição do iterador para o primeiro limite depois de um deslocamento
  - IntlBreakIterator::previous — Define a posição do iterador para o limite imediatamente anterior ao atual
  - IntlBreakIterator::setText — Define o texto a ser percorrido
- IntlRuleBasedBreakIterator — A classe IntlRuleBasedBreakIterator
  - IntlRuleBasedBreakIterator::__construct — Cria um iterador a partir de um conjunto de regras
  - IntlRuleBasedBreakIterator::getBinaryRules — Obtém a forma binária de regras compiladas
  - IntlRuleBasedBreakIterator::getRules — Obtém o conjunto de regras usado para criar este objeto
  - IntlRuleBasedBreakIterator::getRuleStatus — Obtém o maior valor de status a partir de regras de quebras que determinaram a posição de quebra atual
  - IntlRuleBasedBreakIterator::getRuleStatusVec — Obtém os valores de status das regras de quebra que determinaram a posição de quebra atual
- IntlCodePointBreakIterator — A classe IntlCodePointBreakIterator
  - IntlCodePointBreakIterator::getLastCodePoint — Obtém o último code point passado após avançar ou retroceder o iterador
- IntlDatePatternGenerator — A classe IntlDatePatternGenerator
  - IntlDatePatternGenerator::create — Cria uma nova instância de IntlDatePatternGenerator
  - IntlDatePatternGenerator::getBestPattern — Determina o formato de data/horário mais adequado
- IntlPartsIterator — A classe IntlPartsIterator
  - IntlPartsIterator::getBreakIterator — Obtém o IntlBreakIterator que é utilizado pelo iterador
- UConverter — A classe UConverter
  - UConverter::__construct — Cria um objeto UConverter
  - UConverter::convert — Converte uma string de um conjunto de caracteres (charset) para outro
  - UConverter::fromUCallback — Função de retorno de origem padrão
  - UConverter::getAliases — Obtém o pseudônimo de um nome
  - UConverter::getAvailable — Obtém os nomes canônicos dos conversores disponíveis
  - UConverter::getDestinationEncoding — Obtém a codificação de destino
  - UConverter::getDestinationType — Obtém o tipo do conversor de destino
  - UConverter::getErrorCode — Obtém o código do último erro gerado pelo objeto
  - UConverter::getErrorMessage — Obtém a mensagem do último erro gerado pelo objeto
  - UConverter::getSourceEncoding — Obtém a codificação de origem
  - UConverter::getSourceType — Obtém o tipo do conversor de origem
  - UConverter::getStandards — Obtém os nomes dos conversores padrão associados
  - UConverter::getSubstChars — Obtém os caracteres de substituição
  - UConverter::reasonText — Obtém uma representação em string da razão da chamada de retorno
  - UConverter::setDestinationEncoding — Define a codificação de destino
  - UConverter::setSourceEncoding — Define a codificação da origem
  - UConverter::setSubstChars — Define os caracteres de substituição
  - UConverter::toUCallback — Função de retorno padrão de destino
  - UConverter::transcode — Converte uma string de uma codificação de caracteres para outra
- Funções de Grapheme
  - grapheme_extract — Extrai uma sequência de grupos padrão de grafemas de um buffer de texto em UTF-8
  - grapheme_str_split — Separa uma string em um array
  - grapheme_stripos — Encontra a posição (em unidades de grafema) da primeira ocorrência de uma string não sensível a maiúsculas/minúsculas
  - grapheme_stristr — Retorna parte de uma string a partir da primeira ocorrência de outra string (insensível a maiúsculas/minúsculas) até o final
  - grapheme_strlen — Obtém o comprimento de uma string em unidade de grafema
  - grapheme_strpos — Encontra a posição (em unidades de grafema) da primeira ocorrência de uma string
  - grapheme_strripos — Encontra a posição (em unidades de grafema) da última ocorrência de uma string (insensível a maiúsculas/minúsculas)
  - grapheme_strrpos — Encontra a posição (em unidades de grafema) da última ocorrência de uma string
  - grapheme_strstr — Retorna parte de uma string a partir da primeira ocorrência de outra string até o final
  - grapheme_substr — Retorna parte de uma string
- Funções de IDN
  - idn_to_ascii — Converte nome de domínio para a forma ASCII IDNA
  - idn_to_utf8 — Converte nome de domínio de ASCII IDNA para Unicode
- IntlChar
  - IntlChar::charAge — Obtém a "idade" do ponto de código
  - IntlChar::charDigitValue — Obtém o valor do dígito decimal de um caractere de dígito decimal
  - IntlChar::charDirection — Obtém o valor de categoria bidirecional para um ponto de código
  - IntlChar::charFromName — Encontra um caractere Unicode pelo nome e retorna seu valor de ponto de código
  - IntlChar::charMirror — Obtém o caractere "espelho" para um ponto de código
  - IntlChar::charName — Obtém o nome de um caractere Unicode
  - IntlChar::charType — Obtém o valor da categoria geral para um ponto de código
  - IntlChar::chr — Retorna um caractere Unicode por valor de ponto de código
  - IntlChar::digit — Obtém o valor de dígito decimal de um ponto de código para uma base fornecida
  - IntlChar::enumCharNames — Enumera todos os caracteres Unicode atribuídos dentro de um intervalo
  - IntlChar::enumCharTypes — Enumera todos os pontos de código com suas categorias gerais Unicode
  - IntlChar::foldCase — Converte maiúscula/minúscula em um ponto de código
  - IntlChar::forDigit — Obtém a representação em caractere para um dígito e uma base fornecidos
  - IntlChar::getBidiPairedBracket — Obtém o caractere de par de abertura/fechamento para um ponto de código
  - IntlChar::getBlockCode — Obtém o bloco de alocação Unicode contendo um ponto de código
  - IntlChar::getCombiningClass — Obtém a classe de combinação de um ponto de código
  - IntlChar::getFC_NFKC_Closure — Obtém a propriedade FC_NFKC_Closure para um ponto de código
  - IntlChar::getIntPropertyMaxValue — Obtém o valor máximo para uma propriedade Unicode
  - IntlChar::getIntPropertyMinValue — Obtém o valor mínimo para uma propriedade Unicode
  - IntlChar::getIntPropertyValue — Obtém o valor de uma propriedade Unicode de um ponto de código
  - IntlChar::getNumericValue — Obtém o valor numérico para um ponto de código Unicode
  - IntlChar::getPropertyEnum — Obtém o valor da constante da propriedade para uma propriedade informada
  - IntlChar::getPropertyName — Obtém o nome Unicode de uma propriedade
  - IntlChar::getPropertyValueEnum — Obtém o valor da propriedade para um nome de valor fornecido
  - IntlChar::getPropertyValueName — Obtém o nome Unicode para um valor de propriedade
  - IntlChar::getUnicodeVersion — Obtém a versão do Unicode
  - IntlChar::hasBinaryProperty — Verifica uma propriedade binária Unicode para um ponto de código
  - IntlChar::isalnum — Verifica se um ponto de código é um caractere alfanumérico
  - IntlChar::isalpha — Verifica se um ponto de código é uma letra
  - IntlChar::isbase — Verifica se um ponto de código é um caractere base
  - IntlChar::isblank — Verifica se um ponto de código é um caractere "vazio" ou um "espaço horizontal"
  - IntlChar::iscntrl — Verifica se um ponto de código é um caractere de controle
  - IntlChar::isdefined — Verifica se o ponto de código está definido
  - IntlChar::isdigit — Verifica se um ponto de código é um caractere de dígito
  - IntlChar::isgraph — Verifica se um ponto de código é um caractere gráfico
  - IntlChar::isIDIgnorable — Verifica se um ponto de código é um caractere ignorável
  - IntlChar::isIDPart — Verifica se um ponto de código é permissível em um identificador
  - IntlChar::isIDStart — Verifica se um ponto de código é permissível como o primeiro caractere em um identificador
  - IntlChar::isISOControl — Verifica se o ponto de código é um código de controle ISO
  - IntlChar::isJavaIDPart — Verifica se um ponto de código é permissível em um identificador Java
  - IntlChar::isJavaIDStart — Verifica se um ponto de código é permissível como o primeiro caractere em um identificador Java
  - IntlChar::isJavaSpaceChar — Verifica se um ponto de código é um caractere de espaçamento de acordo com o Java
  - IntlChar::islower — Verifica se um ponto de código é uma letra minúscula
  - IntlChar::isMirrored — Verifica se um ponto de código tem a propriedade Bidi_Mirrored
  - IntlChar::isprint — Verifica se um ponto de código é um caractere imprimível
  - IntlChar::ispunct — Verifica se um ponto de código é um caractere de pontuação
  - IntlChar::isspace — Verifica se um ponto de código é um caractere de espaçamento
  - IntlChar::istitle — Verifica se um ponto de código é uma letra com grafia mista
  - IntlChar::isUAlphabetic — Verifica se um ponto de código tem a propriedade Alphabetic do Unicode
  - IntlChar::isULowercase — Verifica se um ponto de código tem a propriedade Lowercase do Unicode
  - IntlChar::isupper — Verifica se um ponto de código tem a categoria geral "Lu" (letra maiúscula)
  - IntlChar::isUUppercase — Verifica se um ponto de código tem a propriedade Uppercase do Unicode
  - IntlChar::isUWhiteSpace — Verifica se um ponto de código tem a propriedade White_Space do Unicode
  - IntlChar::isWhitespace — Verifica se um ponto de código é um caractere de espaço em branco de acordo com a ICU
  - IntlChar::isxdigit — Verifica se um ponto de código é um dígito hexadecimal
  - IntlChar::ord — Retorna o valor do ponto de código Unicode do caractere
  - IntlChar::tolower — Transforma o caractere Unicode em minúscula
  - IntlChar::totitle — Transforma o caractere Unicode em letra de título
  - IntlChar::toupper — Transforma um caractere Unicode em maiúscula
- IntlException — Classe de exceção para erros da extensão Intl
- IntlIterator — A classe IntlIterator
  - IntlIterator::current — Retorna o elemento atual
  - IntlIterator::key — Retorna a chave do elemento atual
  - IntlIterator::next — Avança para o próximo elemento
  - IntlIterator::rewind — Rebobina o iterador para o primeiro elemento
  - IntlIterator::valid — Verifica se a posição atual é válida
- Funções de Intl
  - intl_error_name — Obtém nome simbólico para um código de erro informado
  - intl_get_error_code — Obtém o último código de erro
  - intl_get_error_message — Obtém a descrição do último erro
  - intl_is_failure — Verifica se o código de erro fornecido indica falha

# String Multibyte

# Introdução

Embora existam muitas linguagens nas quais cada caractere necessário pode ser representado por um mapeamento de um para um para um valor de 8 bits, há também várias linguagens que exigem tantos caracteres para a comunicação escrita que não podem ser contidos dentro da faixa que um simples byte pode codificar (um byte é composto por oito bits. Cada bit pode conter apenas dois valores distintos, um ou zero. Devido a isso, um byte só pode representar 256 valores únicos (dois elevado à potência de oito)). Esquemas de codificação de caracteres multibyte foram desenvolvidos para expressar mais de 256 caracteres no sistema de codificação de bytes regular.

Ao manipular (cortar, dividir, emendar, etc.) strings codificadas em uma codificação multibyte, você precisa usar funções especiais, pois dois ou mais bytes consecutivos podem representar um único caractere em tais esquemas de codificação. Caso contrário, se você aplicar uma função de string que não é sensível a multibyte à string, ela provavelmente falhará em detectar o início ou o final do caractere multibyte e acabará com uma string corrompida e inútil que provavelmente perde seu significado original.

`mbstring` fornece funções de string específicas para multibyte que ajudam a lidar com codificações multibyte em PHP. Além disso, `mbstring` lida com a conversão de codificação de caracteres entre os pares de codificação possíveis. `mbstring` é projetada para lidar com codificações baseadas em Unicode, como UTF-8 e UCS-2, e muitas codificações de byte único por conveniência (listadas em Codificações de Caracteres Suportadas).

# Instalação/Configuração

## Índice

- Instalação
- Configurações em Execução

## Instalação

`mbstring` é uma extensão não padrão. Isso significa que ela não está habilitada por padrão. Você deve habilitar explicitamente o módulo com a opção `configure`. Veja a seção Instalação para detalhes.

As seguintes opções de configuração estão relacionadas ao módulo `mbstring`.

- --enable-mbstring: Habilita as funções do `mbstring`. Esta opção é necessária para usar as funções do `mbstring`.

  libmbfl é necessário para o `mbstring`. libmbfl é incluído com o `mbstring`. Antes do PHP 7.3.0, se libmbfl já está instalado no sistema, --with-libmbfl[=DIR] pode ser especificado para usar a biblioteca instalada.

- --disable-mbregex: Desabilita funções de expressão regular com suporte a caracteres multibyte.

  Oniguruma é necessário para as funções de expressão regular com suporte a caracteres multibyte. A partir do PHP 7.4.0, pkg-config é usado para detectar a biblioteca libonig. Antes do PHP 7.4.0, Oniguruma estava incluído com o `mbstring`, mas era possível compilá-lo com uma libonig já instalada passando --with-onig[=DIR].

  É possível desabilitar a verificação de retrocesso multibyte na expressão regular especificando --disable-mbregex-backtrack.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de configuração do mbstring
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
mbstring.language | "neutral" | `INI_ALL` |
mbstring.detect_order | NULL | `INI_ALL` |
mbstring.http_input | "pass" | `INI_ALL` | Descontinuado
mbstring.http_output | "pass" | `INI_ALL` | Descontinuado
mbstring.internal_encoding | NULL | `INI_ALL` | Descontinuado
mbstring.substitute_character | NULL | `INI_ALL` |
mbstring.func_overload | "0" | `INI_SYSTEM` | Descontinuado a partir do PHP 7.2.0; removido a partir do PHP 8.0.0.
mbstring.encoding_translation | "0" | `INI_PERDIR` |
mbstring.http_output_conv_mimetypes | "^(text/|application/xhtml\+xml)" | `INI_ALL` |
mbstring.strict_detection | "0" | `INI_ALL` |
mbstring.regex_retry_limit | "1000000" | `INI_ALL` | Disponível a partir do PHP 7.4.0.
mbstring.regex_stack_limit | "100000" | `INI_ALL` | Disponível a partir do PHP 7.3.5.

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`mbstring.language` string

  A configuração padrão do idioma nacional (NLS) usada no mbstring. Note que esta opção define automaticamente `mbstring.internal_encoding` e `mbstring.internal_encoding` deve ser colocada após `mbstring.language` no php.ini

`mbstring.encoding_translation` bool

  Ativa o filtro de codificação de caracteres transparente para as consultas HTTP de entrada, que realiza a detecção e conversão da codificação de entrada para a codificação de caracteres interna.

`mbstring.internal_encoding` string
  Aviso

  Este recurso descontinuado será certamente removido no futuro.

  Define a codificação de caracteres interna padrão.

  Os usuários devem deixar isso vazio e definir `default_charset` em vez disso.

`mbstring.http_input` string
  Aviso

  Este recurso descontinuado será certamente removido no futuro.

  Define a codificação de caracteres de entrada HTTP padrão.

  Os usuários devem deixar isso vazio e definir `default_charset` em vez disso.

`mbstring.http_output` string
  Aviso

  Este recurso descontinuado será certamente removido no futuro.

  Define a codificação de caracteres de saída HTTP padrão (a saída será convertida da codificação interna para a codificação de saída HTTP na saída).

  Os usuários devem deixar isso vazio e definir `default_charset` em vez disso.

`mbstring.detect_order` string

  Define a ordem padrão de detecção de código de caracteres. Veja também mb_detect_order().

`mbstring.substitute_character` string

  Define o caractere a ser substituído por codificação de caracteres inválida. Veja mb_substitute_character() para os valores suportados.

`mbstring.func_overload` string
  Aviso

  Este recurso foi DESCONTINUADO a partir do PHP 7.2.0 e foi REMOVIDO a partir do PHP 8.0.0. O uso deste recurso é fortemente desencorajado.

  Sobrecarrega um conjunto de funções de byte único pelas contrapartes do mbstring. Veja Sobrecarga de Funções para mais informações.

  Esta configuração só pode ser alterada no arquivo php.ini.

`mbstring.http_output_conv_mimetypes` string

`mbstring.strict_detection` bool

  Ativa a detecção estrita de codificação. Veja mb_detect_encoding() para uma descrição e exemplos.

`mbstring.regex_retry_limit` int

  Limita a quantidade de retrocesso que pode ser executada durante uma correspondência de mbregex.

  Esta configuração só tem efeito ao vincular contra oniguruma >= 6.8.0.

`mbstring.regex_stack_limit` int

  Limita a profundidade da pilha de expressões regulares mbstring.

De acordo com a » especificação HTML 4.01, os navegadores podem codificar um formulário sendo enviado com uma codificação de caracteres diferente da usada para a página. Veja mb_http_input() para detectar a codificação de caracteres usada pelos navegadores.

Embora os navegadores populares sejam capazes de fazer uma suposição razoavelmente precisa sobre a codificação de caracteres de um documento HTML específico, seria melhor definir o parâmetro `charset` no cabeçalho HTTP `Content-Type` para o valor apropriado usando a função header() ou a configuração ini default_charset.

Exemplo #1 Exemplos de configuração do php.ini

    ; Define idioma padrão
    mbstring.language        = Neutral; Define o idioma padrão como neutro (UTF-8) (padrão)
    mbstring.language        = English; Define o idioma padrão para inglês
    mbstring.language        = Japanese; Define o idioma padrão para japonês

    ;; Define a codificação interna padrão
    ;; Nota: Certifique-se de usar a codificação de caracteres que funciona com PHP
    mbstring.internal_encoding    = UTF-8  ; Define a codificação interna para UTF-8

    ;; A tradução da codificação de entrada HTTP está habilitada.
    mbstring.encoding_translation = On

    ;; Define a codificação de caracteres de entrada HTTP padrão
    ;; Nota: O script não pode alterar a configuração http_input.
    mbstring.http_input           = pass    ; Sem conversão.
    mbstring.http_input           = auto    ; Define a entrada HTTP como automática
                                    ; "auto" é expandido de acordo com mbstring.language
    mbstring.http_input           = SJIS    ; Define a entrada HTTP para SJIS
    mbstring.http_input           = UTF-8,SJIS,EUC-JP ; Especifica a ordenação

    ;; Define a codificação de caracteres de saída HTTP padrão
    mbstring.http_output          = pass    ; Sem conversão
    mbstring.http_output          = UTF-8   ; Define a codificação de saída HTTP para UTF-8

    ;; Define a ordem de detecção de codificação de caracteres padrão
    mbstring.detect_order         = auto    ; Define a ordem de detecção como automática
    mbstring.detect_order         = ASCII,JIS,UTF-8,SJIS,EUC-JP ; Especifica o pedido

    ;; Define o caractere substituto padrão
    mbstring.substitute_character = 12307   ; Especifica o valor Unicode
    mbstring.substitute_character = none    ; Não imprime caractere
    mbstring.substitute_character = long    ; Exemplo longo: U+3000,JIS+7E7E

Exemplo #2 php.ini configuração para usuários `EUC-JP`

    ;; Desativa buffer de saída
    output_buffering      = Off

    ;; Define conjunto de caracteres do cabeçalho HTTP
    default_charset       = EUC-JP

    ;; Define o idioma padrão para japonês
    mbstring.language = Japanese

    ;; A tradução da codificação de entrada HTTP está habilitada
    mbstring.encoding_translation = On

    ;; Define a conversão de codificação de entrada HTTP como automática
    mbstring.http_input   = auto

    ;; Converte saída HTTP para EUC-JP
    mbstring.http_output  = EUC-JP

    ;; Define a codificação interna para EUC-JP
    mbstring.internal_encoding = EUC-JP

    ;; Não imprime caracteres inválidos
    mbstring.substitute_character = none

Exemplo #3 php.ini configuração para usuários `SJIS`

    ;; Habilita buffer de saída
    output_buffering     = On

    ;; Define mb_output_handler para ativar a conversão de saída
    output_handler       = mb_output_handler

    ;; Define o conjunto de caracteres do cabeçalho HTTP
    default_charset      = Shift_JIS

    ;; Define o idioma padrão para japonês
    mbstring.language = Japanese

    ;; Define a conversão de codificação de entrada http como automática
    mbstring.http_input  = auto

    ;; Converte para SJIS
    mbstring.http_output = SJIS

    ;; Define a codificação interna para EUC-JP
    mbstring.internal_encoding = EUC-JP

    ;; Não imprime caracteres inválidos
    mbstring.substitute_character = none

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`MB_OVERLOAD_MAIL` (int)
  Removido a partir do PHP 8.0.0
`MB_OVERLOAD_STRING` (int)
  Removido a partir do PHP 8.0.0
`MB_OVERLOAD_REGEX` (int)
  Removido a partir do PHP 8.0.0
`MB_CASE_UPPER` (int)
  Realiza uma dobragem completa em maiúsculas. Isso pode alterar o comprimento da string. Este é o modo usado por mb_strtoupper().
`MB_CASE_LOWER` (int)
  Realiza uma dobragem completa em minúsculas. Isso pode alterar o comprimento da string. Este é o modo usado por mb_strtolower().
`MB_CASE_TITLE` (int)
  Realiza uma conversão completa de título com base nas propriedades Unicode derivadas de Cased e CaseIgnorable. Em particular, isso melhora o manuseio de aspas e apóstrofos. Isso pode alterar o comprimento da string.
`MB_CASE_FOLD` (int)
  Realiza uma conversão completa de dobragem de caso que remove distinções de caso presentes na string. Isso é usado para correspondência sem distinção de maiúsculas e minúsculas. Isso pode alterar o comprimento da string. Disponível desde o PHP 7.3.
`MB_CASE_LOWER_SIMPLE` (int)
  Realiza uma conversão simples de dobragem em minúsculas. Isso não altera o comprimento da string. Disponível desde o PHP 7.3.
`MB_CASE_UPPER_SIMPLE` (int)
  Realiza uma conversão simples de dobragem em maiúsculas. Isso não altera o comprimento da string. Disponível desde o PHP 7.3.
`MB_CASE_TITLE_SIMPLE` (int)
  Realiza uma conversão simples de dobragem de título. Isso não altera o comprimento da string. Disponível desde o PHP 7.3.
`MB_CASE_FOLD_SIMPLE` (int)
  Realiza uma conversão simples de dobragem de caso que remove distinções de caso presentes na string. Isso é usado para correspondência sem distinção de maiúsculas e minúsculas. Isso não altera o comprimento da string. Usado internamente pela extensão MBString em operações insensíveis a maiúsculas e minúsculas. Disponível desde o PHP 7.3.
`MB_ONIGURUMA_VERSION` (string)
  A versão do Oniguruma, por exemplo, `6.9.4`. Disponível desde o PHP 7.4.

# Sumários de Codificações Suportadas

Sumários de Codificações Suportadas
Nome no registro de conjunto de caracteres da IANA | Conjunto de caracteres subjacente | Descrição | Nota Adicional
--- | --- | --- | ---
ISO-10646-UCS-4 | ISO 10646 | O Conjunto de Caracteres Universal com espaço de código de 31 bits, padronizado como UCS-4 pela ISO/IEC 10646. Mantido sincronizado com a versão mais recente do mapa de códigos Unicode. | Se este nome for usado na facilidade de conversão de codificação, o conversor tenta identificar pelo BOM precedente (marcador de ordem de byte) em qual endian os bytes subsequentes estão representados.
ISO-10646-UCS-4 | UCS-4 | Ver acima. | Ao contrário do `UCS-4`, as strings são sempre assumidas estar na forma big endian.
ISO-10646-UCS-4 | UCS-4 | Ver acima. | Ao contrário do `UCS-4`, as strings são sempre assumidas estar na forma little endian.
ISO-10646-UCS-2 | UCS-2 | O Conjunto de Caracteres Universal com espaço de código de 16 bits, padronizado como UCS-2 pela ISO/IEC 10646. Mantido sincronizado com a versão mais recente do mapa de códigos Unicode. | Se este nome for usado na facilidade de conversão de codificação, o conversor tenta identificar pelo BOM precedente (marcador de ordem de byte) em qual endian os bytes subsequentes estão representados.
ISO-10646-UCS-2 | UCS-2 | Ver acima. | Ao contrário do `UCS-2`, as strings são sempre assumidas estar na forma big endian.
ISO-10646-UCS-2 | UCS-2 | Ver acima. | Ao contrário do `UCS-2`, as strings são sempre assumidas estar na forma big endian.
UTF-32 | Unicode | Formato de Transformação Unicode de largura de unidade de 32 bits, cujo espaço de codificação refere-se ao padrão de conjunto de códigos Unicode. Este esquema de codificação não era idêntico ao UCS-4 porque o espaço de código do Unicode era limitado a um valor de 21 bits. | Se este nome for usado na facilidade de conversão de codificação, o conversor tenta identificar pelo BOM precedente (marcador de ordem de byte) em qual endian os bytes subsequentes estão representados.
UTF-32BE | Unicode | Ver acima | Ao contrário do `UTF-32`, as strings são sempre assumidas estar na forma big endian.
UTF-32LE | Unicode | Ver acima | Ao contrário do `UTF-32`, as strings são sempre assumidas estar na forma little endian.
UTF-16 | Unicode | Formato de Transformação Unicode de largura de unidade de 16 bits. Vale a pena observar que o UTF-16 não é mais a mesma especificação que UCS-2 porque o mecanismo de substituição foi introduzido desde o Unicode 2.0 e UTF-16 agora se refere a um espaço de código de 21 bits. | Se este nome for usado na facilidade de conversão de codificação, o conversor tenta identificar pelo BOM precedente (marcador de ordem de byte) em qual endian os bytes subsequentes estão representados.
UTF-16BE | Unicode | Ver acima. | Ao contrário do `UTF-16`, as strings são sempre assumidas estar na forma big endian.
UTF-16LE | Unicode | Ver acima. | Ao contrário do `UTF-16`, as strings são sempre assumidas estar na forma little endian.
UTF-8 | Unicode / UCS | Formato de Transformação Unicode de largura de unidade de 8 bits. | none
UTF-7 | Unicode | Um formato de transformação seguro para e-mails do Unicode, especificado em » RFC2152. | none
(none) | Unicode | Uma variante de UTF-7 especializada para uso no » protocolo IMAP. | none
US-ASCII (preferred MIME name) / iso-ir-6 / ANSI_X3.4-1986 / ISO_646.irv:1991 / ASCII / ISO646-US / us / IBM367 / CP367 / csASCII | ASCII / ISO 646 | Código Padrão Americano para Intercâmbio de Informações é uma codificação comumente usada de 7 bits. Também padronizado como um padrão internacional, ISO 646. | (none)
EUC-JP (preferred MIME name) / Extended_UNIX_Code_Packed_Format_for_Japanese / csEUCPkdFmtJapanese | Compound of US-ASCII / JIS X0201:1997 (hankaku kana part) / JIS X0208:1990 / JIS X0212:1990 | Como pode ser visto, o nome é derivado de uma abreviação de Formato Padrão de Código UNIX Packed para Japonês, esta codificação é principalmente usada em UNIX ou plataformas semelhantes. O esquema de codificação original, Extended UNIX Code, é projetado com base no ISO 2022. | O conjunto de caracteres referido pelo EUC-JP é diferente do IBM932 / CP932, que são usados pelo OS/2® e Microsoft® Windows®. Para a troca de informações com essas plataformas, use EUCJP-WIN em vez disso.
Shift_JIS (preferred MIME name) / MS_Kanji / csShift_JIS | Compound of JIS X0201:1997 / JIS X0208:1997 | Shift_JIS foi desenvolvido no início dos anos 80, na época dos processadores de palavras japoneses pessoais foram lançados no mercado, a fim de manter compatibilidades com o esquema de codificação legado JIS X 0201:1976. De acordo com a definição da IANA, o conjunto de códigos do Shift_JIS é ligeiramente diferente de IBM932 / CP932. No entanto, os nomes "SJIS" / "Shift_JIS" são frequentemente usados erroneamente para se referir a esses conjuntos de códigos. | Para o mapa de código CP932, use SJIS-WIN em vez disso.
(nenhum) | Composto de JIS X0201:1997 / JIS X0208:1997 / extensões IBM / extensões NEC | Embora esta "codificação" use o mesmo esquema de codificação que EUC-JP, o conjunto de caracteres subjacente é diferente. Ou seja, alguns pontos de código mapeiam para caracteres diferentes do EUC-JP. | nenhum
Windows-31J / csWindows31J | Composto de JIS X0201:1997 / JIS X0208:1997 / extensões IBM / extensões NEC | Embora esta "codificação" use o mesmo esquema de codificação que Shift_JIS, o conjunto de caracteres subjacente é diferente. Isso significa que alguns códigos pontos mapeiam para caracteres diferentes do Shift_JIS. | (none)
ISO-2022-JP (preferred MIME name) / csISO2022JP | US-ASCII / JIS X0201:1976 / JIS X0208:1978 / JIS X0208:1983 | » RFC1468 | (nenhum)
JIS |  |  |
ISO-8859-1 |  |  |
ISO-8859-2 |  |  |
ISO-8859-3 |  |  |
ISO-8859-4 |  |  |
ISO-8859-5 |  |  |
ISO-8859-6 |  |  |
ISO-8859-7 |  |  |
ISO-8859-8 |  |  |
ISO-8859-9 |  |  |
ISO-8859-10 |  |  |
ISO-8859-13 |  |  |
ISO-8859-14 |  |  |
ISO-8859-15 |  |  |
ISO-8859-16 |  |  |
byte2be |  |  |
byte2le |  |  |
byte4be |  |  |
byte4le |  |  |
BASE64 |  |  |
HTML-ENTITIES |  |  |
7bit |  |  |
8bit |  |  |
EUC-CN |  |  |
CP936 |  |  |
HZ |  |  |
EUC-TW |  |  |
CP950 |  |  |
BIG-5 |  |  |
EUC-KR |  |  |
UHC (CP949) |  |  |
ISO-2022-KR |  |  |
Windows-1251 (CP1251) |  |  |
Windows-1252 (CP1252) |  |  |
CP866 (IBM866) |  |  |
KOI8-R |  |  |
KOI8-U |  |  |

# Noções Básicas de Codificações Multibyte Japonesas

Os caracteres japoneses só podem ser representados por codificações multibyte, e vários padrões de codificação são usados dependendo da plataforma e da finalidade do texto. Para piorar a situação, esses padrões de codificação diferem um pouco um do outro. Para criar uma aplicação web que possa ser usada em um ambiente japonês, o desenvolvedor precisa ter em mente essas complexidades para garantir que as codificações de caracteres adequadas sejam usadas.

- O armazenamento de um caractere pode ter até seis bytes.
- A maioria dos caracteres multibyte japoneses aparece com o dobro da largura dos caracteres de byte único. Esses caracteres são chamados "zen-kaku" em japonês, que significa "largura total". Outros caracteres mais estreitos, são chamados "han-kaku", que significa "meia largura". As propriedades gráficas dos caracteres, no entanto, dependem das fontes usadas para exibi-las.
- Algumas codificações de caracteres usam sequências de deslocamento (escape) definidas na ISO-2022 para alternar o mapa de código da área de código específica (`00h` a `7fh`).
- A ISO-2022-JP deve ser usada no SMTP/NNTP, e cabeçalhos e entidades devem ser recodificados de acordo com os requisitos da RFC. Embora esses não sejam requisitos, ainda é uma boa ideia porque vários agentes de usuário populares não podem reconhecer nenhum outro método de codificação.
- As páginas web criadas para serviços de telefonia móvel, como » i-mode ou » EZweb devem usar Shift_JIS.
- Emoji usados em serviços de telefonia móvel, como » i-mode ou » EZweb são suportados.

# Entrada e Saída HTTP

A conversão de codificação de caracteres de entrada/saída HTTP pode converter dados binários também. Os usuários devem controlar a conversão de codificação de caracteres se dados binários forem usados para entrada/saída HTTP.

> Nota:

> Se `enctype` para o formulário HTML estiver configurado como `multipart/form-data` e `mbstring.encoding_translation` estiver ativado no php.ini, as variáveis POST'ed e os nomes dos arquivos enviados serão convertidos para a codificação de caracteres interna também. No entanto, a conversão não é aplicada às chaves de consulta.

- Entrada HTTP

  Não há maneira de controlar a conversão de caracteres de entrada HTTP a partir de um script PHP. Para desativar a conversão de caracteres de entrada HTTP, isso deve ser feito no php.ini.

  Exemplo #1 Desativando a conversão de entrada HTTP no php.ini

      ;; Disable HTTP Input conversion
      mbstring.http_input = pass
      ;; Disable HTTP Input conversion
      mbstring.encoding_translation = Off

  Ao usar o PHP como um módulo do Apache, é possível substituir essas configurações em cada diretiva Virtual Host no httpd.conf ou por diretório com .htaccess. Consulte a seção Configuração e o Manual do Apache para obter detalhes.

- Saída HTTP

  Existem várias maneiras de habilitar a conversão de codificação de caracteres de saída. Uma é usando o php.ini, outra é usando ob_start() com mb_output_handler() como a `ob_start` função de retorno de chamada.

Exemplo #2 Exemplo de configuração no php.ini

    ;; Enable output character encoding conversion for all PHP pages

    ;; Enable Output Buffering
    output_buffering    = On

    ;; Set mb_output_handler to enable output conversion
    output_handler      = mb_output_handler

Exemplo #3 Exemplo de script

    <?php

    // Habilitar a conversão de codificação de caracteres de saída apenas para esta página

    // Definir a codificação de caracteres de saída HTTP para SJIS
    mb_http_output('SJIS');

    // Iniciar o buffer e especificar "mb_output_handler" como
    // função de callback
    ob_start('mb_output_handler');

    ?>

# Codificações de Caracteres Suportadas

Atualmente, as seguintes codificações de caracteres são suportadas pelo módulo `mbstring`. Qualquer uma dessas codificações pode ser especificada no parâmetro `encoding` das funções `mbstring`.

As seguintes codificações de caracteres são suportadas nesta extensão PHP:

- UCS-4*
- UCS-4BE
- UCS-4LE*
- UCS-2
- UCS-2BE
- UCS-2LE
- UTF-32*
- UTF-32BE*
- UTF-32LE*
- UTF-16*
- UTF-16BE*
- UTF-16LE*
- UTF-7
- UTF7-IMAP
- UTF-8*
- ASCII*
- EUC-JP*
- SJIS*
- eucJP-win*
- SJIS-win*
- ISO-2022-JP
- ISO-2022-JP-MS
- CP932
- CP51932
- SJIS-mac (alias: MacJapanese)
- SJIS-Mobile#DOCOMO (alias: SJIS-DOCOMO)
- SJIS-Mobile#KDDI (alias: SJIS-KDDI)
- SJIS-Mobile#SOFTBANK (alias: SJIS-SOFTBANK)
- UTF-8-Mobile#DOCOMO (alias: UTF-8-DOCOMO)
- UTF-8-Mobile#KDDI-A
- UTF-8-Mobile#KDDI-B (alias: UTF-8-KDDI)
- UTF-8-Mobile#SOFTBANK (alias: UTF-8-SOFTBANK)
- ISO-2022-JP-MOBILE#KDDI (alias: ISO-2022-JP-KDDI)
- JIS
- JIS-ms
- CP50220
- CP50220raw
- CP50221
- CP50222
- ISO-8859-1*
- ISO-8859-2*
- ISO-8859-3*
- ISO-8859-4*
- ISO-8859-5*
- ISO-8859-6*
- ISO-8859-7*
- ISO-8859-8*
- ISO-8859-9*
- ISO-8859-10*
- ISO-8859-13*
- ISO-8859-14*
- ISO-8859-15*
- ISO-8859-16*
- byte2be
- byte2le
- byte4be
- byte4le
- BASE64
- HTML-ENTITIES (alias: HTML)
- 7bit
- 8bit
- EUC-CN*
- CP936
- GB18030
- HZ
- EUC-TW*
- CP950
- BIG-5*
- EUC-KR*
- UHC (alias: CP949)
- ISO-2022-KR
- Windows-1251 (alias: CP1251)
- Windows-1252 (alias: CP1252)
- CP866 (alias: IBM866)
- KOI8-R*
- KOI8-U*
- ArmSCII-8 (alias: ArmSCII8)

* denota codificações também utilizáveis em expressões regulares.

Qualquer entrada php.ini que aceite um nome de codificação também pode usar os valores "`auto`" e "`pass`". Funções `mbstring` que aceitam um nome de codificação também podem usar o valor "`auto`".

Se "`pass`" estiver definido, nenhuma conversão de codificação de caracteres será realizada.

Se "`auto`" estiver definido, ele é expandido para a lista de codificações definidas de acordo com o NLS. Por exemplo, se o NLS estiver definido como `Japanese`, o valor é assumido como "`ASCII,JIS,UTF-8,EUC-JP,SJIS`".

Veja também mb_detect_order()

# Recurso de Sobrecarga de Funções

Aviso

Este recurso foi DESCONTINUADO a partir do PHP 7.2.0 e foi REMOVIDO a partir do PHP 8.0.0. O uso deste recurso é fortemente desencorajado.

É possível que frequentemente sejam encontradas dificuldades ao fazer com que uma aplicação PHP existente funcione em um ambiente multibyte específico. Isso acontece porque a maioria das aplicações PHP por aí são escritas com funções de string padrão como substr(), que são conhecidas por não lidar corretamente com strings codificadas em multibyte.

mbstring suporta um recurso de 'sobrecarga de funções' que permite adicionar suporte a multibyte a uma aplicação dessas sem modificar o código, sobrecarregando as contrapartes multibyte das funções de string padrão. Por exemplo, mb_substr() é chamada em vez de substr() se a sobrecarga de funções estiver ativada. Esse recurso facilita a migração de aplicações que suportam apenas codificações de byte único para um ambiente multibyte em muitos casos.

Para usar a sobrecarga de funções, defina `mbstring.func_overload` no php.ini para um valor positivo que represente uma combinação de máscaras de bits especificando as categorias de funções a serem sobrecarregadas. Deve ser definido como 1 para sobrecarregar a função mail(), 2 para funções de string, 4 para funções de expressão regular. Por exemplo, se for definido como 7, as funções de correio, strings e expressões regulares serão sobrecarregadas. A lista de funções sobrecarregadas é mostrada abaixo.

Funções a serem sobrecarregadas
valor de mbstring.func_overload | função original | função sobrecarregada
--- | --- | ---
1 | mail() | mb_send_mail()
2 | strlen() | mb_strlen()
2 | strpos() | mb_strpos()
2 | strrpos() | mb_strrpos()
2 | substr() | mb_substr()
2 | strtolower() | mb_strtolower()
2 | strtoupper() | mb_strtoupper()
2 | stripos() | mb_stripos()
2 | strripos() | mb_strripos()
2 | strstr() | mb_strstr()
2 | stristr() | mb_stristr()
2 | strrchr() | mb_strrchr()
2 | substr_count() | mb_substr_count()

> Nota:

> Não é recomendado usar a opção de sobrecarga de funções no contexto por diretório, porque ainda não foi confirmado como sendo estável o suficiente em um ambiente de produção e pode levar a um comportamento indefinido.

# Requisitos de Codificação de Caracteres em PHP

As codificações dos seguintes tipos são seguras para uso com o PHP.

- Uma codificação de byte único,

  - que possui mapeamentos compatíveis com ASCII (compatíveis com ISO646) para os caracteres no intervalo de `00h` a `7fh`.

- Uma codificação multibyte,

  - que possui mapeamentos compatíveis com ASCII para os caracteres no intervalo de `00h` a `7fh`.
  - que não usa sequências de escape ISO2022.
  - que não usa um valor de `00h` a `7fh` em nenhum dos bytes compostos que representam um único caractere.

Esses são exemplos de codificações de caracteres que provavelmente não funcionarão corretamente com o PHP.

    JIS, SJIS, ISO-2022-JP, BIG-5

Embora scripts PHP escritos em qualquer uma dessas codificações possam não funcionar, especialmente no caso em que strings codificadas aparecem como identificadores ou literais no script, você pode evitar o uso dessas codificações configurando a função de filtro de codificação transparente do `mbstring` para consultas HTTP de entrada.

> Nota:

> É altamente desencorajado usar SJIS, BIG5, CP936, CP949 e GB18030 para a codificação interna, a menos que você esteja familiarizado com o analisador, o scanner e a codificação de caracteres.

> Nota:

> Se você estiver se conectando a um banco de dados com PHP, é recomendável que você use a mesma codificação de caracteres para tanto o banco de dados quanto o `codificação interna` para facilitar o uso e obter melhor desempenho.

> Se estiver usando o PostgreSQL, a codificação de caracteres usada no banco de dados e aquela usada no PHP podem diferir, pois ele oferece suporte à conversão automática de conjunto de caracteres entre o backend e o frontend.

# Strings Multibyte e Funções

# Referências

Esquemas de codificação de caracteres multibyte e seus problemas relacionados são bastante complicados e estão além do escopo desta documentação. Consulte as seguintes URLs e outros recursos para obter mais informações sobre esses tópicos.

- Materiais Unicode

  » http://www.unicode.org/

- Informações sobre caracteres Japoneses/Coreanos/Chineses

  » https://resources.oreilly.com/examples/9781565922242/blob/master/doc/cjk.inf

# mb_check_encoding

(PHP 4 >= 4.4.3, PHP 5 >= 5.1.3, PHP 7, PHP 8)

mb_check_encoding — Verifica se as strings são válidas para a codificação especificada

### Descrição

function mb_check_encoding(array|string|null `$value` = `null`, ?string `$encoding` = `null`): bool

Verifica se o fluxo de bytes especificado é válido para a codificação especificada. Se `value` for do tipo array, todas as chaves e valores são validados recursivamente. É útil para prevenir ataques chamados "Invalid Encoding Attack".

### Parâmetros

`value`

  O fluxo de bytes ou array a ser verificado. Se omitido, esta função verifica toda a entrada desde o início da requisição.

  Aviso

  A partir do PHP 8.1.0, omitir este parâmetro ou passar `null` está descontinuado.

`encoding`

  A codificação esperada.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Chamar esta função com `null` como `value` ou sem argumento está descontinuado.
8.0.0 | `value` e `encoding` são anuláveis agora.
7.2.0 | Esta função agora aceita também um array como `value`. Anteriormente, apenas strings eram suportadas.

# mb_chr

(PHP 7 >= 7.2.0, PHP 8)

mb_chr — Retorna um caractere pelo valor do ponto de código Unicode

### Descrição

function mb_chr(int `$codepoint`, ?string `$encoding` = `null`): string|false

Retorna uma string contendo o caractere especificado pelo valor do ponto de código Unicode, codificado na codificação especificada.

Esta função complementa mb_ord().

### Parâmetros

`codepoint`

  Um valor de ponto de código Unicode, por exemplo, `128024` para U+1F418 ELEPHANT

`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.

### Valor Retornado

Uma string contendo o caractere solicitado, se puder ser representado na codificação especificada ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `encoding` agora pode ser nulo.

### Exemplos

Exemplo #1 Testando diferentes pontos de código

    <?php
    $values = [65, 63, 0x20AC, 128024];
    foreach ($values as $value) {
        var_dump(mb_chr($value, 'UTF-8'));
        var_dump(mb_chr($value, 'ISO-8859-1'));
    }
    ?>

O exemplo acima produzirá:

    string(1) "A"
    string(1) "A"
    string(1) "?"
    string(1) "?"
    string(3) "€"
    bool(false)
    string(4) "🐘"
    bool(false)

### Veja Também

- mb_internal_encoding() - Define/Obtém a codificação de caracteres interna
- mb_ord() - Obtém o ponto de código Unicode do caractere
- IntlChar::ord() - Retorna o valor do ponto de código Unicode do caractere
- chr() - Gera uma string de um byte a partir de um número

# mb_convert_case

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_convert_case — Realiza a conversão de caixa em uma string

### Descrição

function mb_convert_case(string `$string`, int `$mode`, ?string `$encoding` = `null`): string

Realiza a conversão de caixa em uma string, convertida da maneira especificada por `mode`.

### Parâmetros

`string`

  A string sendo convertida.

`mode`

  O modo de conversão. Pode ser um dos `MB_CASE_UPPER`, `MB_CASE_LOWER`, `MB_CASE_TITLE`, `MB_CASE_FOLD`, `MB_CASE_UPPER_SIMPLE`, `MB_CASE_LOWER_SIMPLE`, `MB_CASE_TITLE_SIMPLE`, `MB_CASE_FOLD_SIMPLE`.

`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.

### Valor Retornado

Uma versão da `string` com conversão de caixa conforme especificado por `mode`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Implementadas regras condicionais de maiúsculas/minúsculas para a letra grega sigma que só se aplicam aos modos `MB_CASE_LOWER` e `MB_CASE_TITLE`, e não a `MB_CASE_LOWER_SIMPLE` e `MB_CASE_TITLE_SIMPLE`.
7.3.0 | Adicionado suporte para `MB_CASE_FOLD`, `MB_CASE_UPPER_SIMPLE`, `MB_CASE_LOWER_SIMPLE`, `MB_CASE_TITLE_SIMPLE`, e `MB_CASE_FOLD_SIMPLE` como `mode`.

### Exemplos

Exemplo #1 Exemplo de mb_convert_case()

    <?php
    $str = "mary had a Little lamb and she loved it so";
    $str = mb_convert_case($str, MB_CASE_UPPER, "UTF-8");
    echo $str, PHP_EOL;
    $str = mb_convert_case($str, MB_CASE_TITLE, "UTF-8");
    echo $str, PHP_EOL;
    ?>

Exemplo #2 Exemplo de mb_convert_case() com texto UTF-8 não latino

    <?php
    $str = "Τάχιστη αλώπηξ βαφής ψημένη γη, δρασκελίζει υπέρ νωθρού κυνός";
    $str = mb_convert_case($str, MB_CASE_UPPER, "UTF-8");
    echo $str, PHP_EOL;
    $str = mb_convert_case($str, MB_CASE_TITLE, "UTF-8");
    echo $str, PHP_EOL;
    ?>

### Notas

Ao contrário das funções padrão de conversão de caixa, como strtolower() e strtoupper(), a conversão de caixa é realizada com base nas propriedades dos caracteres Unicode. Assim, o comportamento desta função não é afetado pelas configurações de localidade e ela pode converter qualquer caractere que tenha a propriedade 'alfabética', como o a-umlaut (ä).

Para obter mais informações sobre as propriedades Unicode, consulte » http://www.unicode.org/reports/tr21/.

### Veja Também

- mb_strtolower() - Torna uma string minúscula
- mb_strtoupper() - Faz uma string ficar em maiúsculas
- strtolower() - Converte uma string para minúsculas
- strtoupper() - Converte uma string em maiúsculas
- ucfirst() - Transforma o primeiro caractere de uma string em maiúsculo
- ucwords() - Converte para maiúsculas o primeiro caractere de cada palavra

# mb_convert_encoding

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_convert_encoding — Converte uma string de uma codificação de caracteres para outra

### Descrição

function mb_convert_encoding(array|string `$string`, string `$to_encoding`, array|string|null `$from_encoding` = `null`): array|string|false

Converte `string` de `from_encoding`, ou a codificação interna atual, para `to_encoding`. Se `string` for um array, todos os seus valores string serão convertidos recursivamente.

### Parâmetros

`string`

  A string ou array a ser convertida.

`to_encoding`

  A codificação desejada para o resultado.

`from_encoding`

  A codificação atual usada para interpretar `string`. Múltiplas codificações podem ser especificadas como um array ou uma lista separada por vírgulas, nesse caso, a codificação correta será detectada usando o mesmo algoritmo que mb_detect_encoding().

  Se `from_encoding` for omitida ou `null`, a configuração mbstring.internal_encoding será usada se definida, caso contrário, a configuração default_charset.

  Consulte codificações suportadas para os valores válidos de `to_encoding` e `from_encoding`.

### Valor Retornado

A string ou array codificada em caso de sucesso, ou `false` em caso de falha.

### Erros/Exceções

A partir do PHP 8.0.0, um ValueError é lançado se o valor de `to_encoding` ou `from_encoding` for uma codificação inválida. Antes do PHP 8.0.0, um `E_WARNING` era emitido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.2.0 | mb_convert_encoding() não retornará mais as seguintes codificações não textuais: `"Base64"`, `"QPrint"`, `"UUencode"`, `"HTML entities"`, `"7 bit"` e `"8 bit"`.
8.0.0 | mb_convert_encoding() agora lançará um ValueError quando `to_encoding` receber uma codificação inválida.
8.0.0 | mb_convert_encoding() agora lançará um ValueError quando `from_encoding` receber uma codificação inválida.
8.0.0 | `from_encoding` agora é anulável.
7.2.0 | Esta função agora aceita um array como `string`. Anteriormente, apenas strings eram suportadas.

### Exemplos

Exemplo #1 Exemplo de mb_convert_encoding()

    <?php
    /* Converte a codificação interna para SJIS */
    $str = mb_convert_encoding($str, "SJIS");

    /* Converte EUC-JP para UTF-7 */
    $str = mb_convert_encoding($str, "UTF-7", "EUC-JP");

    /* Detecta automaticamente a codificação a partir de JIS, eucjp-win, sjis-win, e converte str para UCS-2LE */
    $str = mb_convert_encoding($str, "UCS-2LE", "JIS, eucjp-win, sjis-win");

    /* Se mbstring.language for "Japanese", "auto" é expandido para "ASCII,JIS,UTF-8,EUC-JP,SJIS" */
    $str = mb_convert_encoding($str, "EUC-JP", "auto");
    ?>

### Veja Também

- mb_detect_order() - Define ou obtém a ordem de detecção de codificação de caracteres
- UConverter::transcode() - Converte uma string de uma codificação de caracteres para outra
- iconv() - Converte uma string de uma codificação de caracteres para outra

# mb_convert_kana

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_convert_kana — Converte "kana" de um tipo para outro ("zen-kaku", "han-kaku" e mais)

### Descrição

function mb_convert_kana(string `$string`, string `$mode` = "KV", ?string `$encoding` = `null`): string

Realiza uma conversão "han-kaku" - "zen-kaku" para a string `string`. Esta função é útil apenas para o japonês.

### Parâmetros

`string`

  A string a ser convertida.

`mode`

  A opção de conversão.

  Especifique com uma combinação das seguintes opções.

  Opções de Conversão Aplicáveis
  Opção | Significado
  --- | ---
  `r` | Converte alfabetos "zen-kaku" para "han-kaku"
  `R` | Converte alfabetos "han-kaku" para "zen-kaku"
  `n` | Converte números "zen-kaku" para "han-kaku"
  `N` | Converte números "han-kaku" para "zen-kaku"
  `a` | Converte alfabetos e números "zen-kaku" para "han-kaku"
  `A` | Converte alfabetos e números "han-kaku" para "zen-kaku" (Caracteres incluídos nas opções "a", "A" são U+0021 - U+007E, excluindo U+0022, U+0027, U+005C, U+007E)
  `s` | Converte espaço "zen-kaku" para "han-kaku" (U+3000 -> U+0020)
  `S` | Converte espaço "han-kaku" para "zen-kaku" (U+0020 -> U+3000)
  `k` | Converte "zen-kaku kata-kana" para "han-kaku kata-kana"
  `K` | Converte "han-kaku kata-kana" para "zen-kaku kata-kana"
  `h` | Converte "zen-kaku hira-gana" para "han-kaku kata-kana"
  `H` | Converte "han-kaku kata-kana" para "zen-kaku hira-gana"
  `c` | Converte "zen-kaku kata-kana" para "zen-kaku hira-gana"
  `C` | Converte "zen-kaku hira-gana" para "zen-kaku kata-kana"
  `V` | Colapsa a notação de som sonoro e converte-os em um caractere. Use com "K","H"

`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.

### Valor Retornado

A string convertida.

### Erros/Exceções

Gera um ValueError se a combinação de diferentes `mode`s for inválida. Por exemplo, `"sS"`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.2.0 | Um ValueError agora é gerado se a combinação de diferentes `mode`s for inválida.
8.0.0 | O parâmetro `encoding` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo de mb_convert_kana()

    <?php
    /* Converte todos "han-kaku" "kata-kana" para "zen-kaku" "hira-gana" */
    echo mb_convert_kana('ﾔﾏﾀﾞ ﾊﾅｺ', "HV") . "\n";

    /* Converte "han-kaku" "kata-kana" para "zen-kaku" "kata-kana"
       e alfanuméricos "zen-kaku" para "han-kaku" */
    echo mb_convert_kana('ｺｳｻﾞﾊﾞﾝｺﾞｳ ０１２３４５６', "KVa") . "\n";
    ?>

O exemplo acima produzirá:

    やまだ はなこ
    コウザバンゴウ 0123456

# mb_convert_variables

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_convert_variables — Converte o código de caracteres em variável(is)

### Descrição

function mb_convert_variables(
string `$to_encoding`,
array|string `$from_encoding`,
mixed `&$var`,
mixed `&...$vars`
): string|false

Converte a codificação de caracteres das variáveis `var` e `vars` de codificação `from_encoding` para a codificação `to_encoding`.

mb_convert_variables() une strings em Arrays ou Objetos para detectar a codificação, já que a detecção de codificação tende a falhar para strings curtas. Portanto, é impossível misturar codificações em um único array ou objeto.

### Parâmetros

`to_encoding`

  A codificação para a qual a string está sendo convertida.

`from_encoding`

  Se `from_encoding` for especificado como um array ou uma string separada por vírgula, ele tenta detectar a codificação de `from-coding`. Quando `from_encoding` é omitido, é usado `detect_order`.

`var`

  `var` é a referência para a variável sendo convertida. String, Array e Object são aceitos. mb_convert_variables() assume que todos os parâmetros têm a mesma codificação.

`vars`

  Variáveis adicionais `var`s.

### Valor Retornado

A codificação de caracteres antes da conversão para sucesso, ou `false` para falha.

### Exemplos

Exemplo #1 Exemplo de mb_convert_variables()

    <?php
    /* Converte as variáveis $post1, $post2 para a codificação interna */
    $interenc = mb_internal_encoding();
    $inputenc = mb_convert_variables($interenc, "ASCII,UTF-8,SJIS-win", $post1, $post2);
    ?>

# mb_decode_mimeheader

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_decode_mimeheader — Decodifica string no campo de cabeçalho MIME

### Descrição

function mb_decode_mimeheader(string `$string`): string

Decodifica a string codificada `string` no cabeçalho MIME.

### Parâmetros

`string`

  A string sendo decodificada.

### Valor Retornado

A string decodificada na codificação interna de caracteres.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Caracteres de sublinhado (_) são convertidos para espaços conforme especificado na » RFC 2047.

### Veja Também

- mb_encode_mimeheader() - Codificar string para cabeçalho MIME

# mb_decode_numericentity

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_decode_numericentity — Decodifica referência de string numérica HTML para caractere

### Descrição

function mb_decode_numericentity(string `$string`, array `$map`, ?string `$encoding` = `null`): string

Converte a referência de string numérica de string `string`, em um bloco especificado, para caractere.

### Parâmetros

`string`

  A string sendo decodificada.

`map`

  `map` é um array que especifica a área de código a ser convertida.

`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.

### Valor Retornado

A string convertida.

### Erros/Exceções

Lança uma exceção ValueError se `map` não for uma lista de ints.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | mb_decode_numericentity() agora lança uma exceção ValueError se `map` não for uma lista de ints.
8.0.0 | O parâmetro `encoding` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo de `map`

    <?php
    $convmap = array (
       int start_code1, int end_code1, int offset1, int mask1,
       int start_code2, int end_code2, int offset2, int mask2,
       //  ........
       int start_codeN, int end_codeN, int offsetN, int maskN );
    // Especifique o valor Unicode para start_codeN e end_codeN
    // Adicione offsetN ao valor e faça 'AND' bit a bit com maskN,
    // em seguida, converta o valor para referência de string numérica.
    ?>

Exemplo #2 Exemplo de `map` escapando string JavaScript

    <?php
    function escape_javascript_string($str) {
      $map = [
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,0,0, // 49
              0,0,0,0,0,0,0,0,1,1,
              1,1,1,1,1,0,0,0,0,0,
              0,0,0,0,0,0,0,0,0,0,
              0,0,0,0,0,0,0,0,0,0,
              0,1,1,1,1,1,1,0,0,0, // 99
              0,0,0,0,0,0,0,0,0,0,
              0,0,0,0,0,0,0,0,0,0,
              0,0,0,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1, // 149
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1, // 199
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1, // 249
              1,1,1,1,1,1,1, // 255
              ];
      // Codificação de caractere é UTF-8
      $mblen = mb_strlen($str, 'UTF-8');
      $utf32 = bin2hex(mb_convert_encoding($str, 'UTF-32', 'UTF-8'));
      for ($i=0, $encoded=''; $i < $mblen; $i++) {
          $u = substr($utf32, $i*8, 8);
          $v = base_convert($u, 16, 10);
          if ($v < 256 && $map[$v]) {
            $encoded .= '\\x'.substr($u, 6,2);
          } else if ($v == 2028) {
            $encoded .= '\\u2028';
          } else if ($v == 2029) {
            $encoded .= '\\u2029';
          } else {
            $encoded .= mb_convert_encoding(hex2bin($u), 'UTF-8', 'UTF-32');
          }
       }
       return $encoded;
    }

    // Dados de teste
    $convmap = [ 0x0, 0xffff, 0, 0xffff ];
    $msg = '';
    for ($i=0; $i < 1000; $i++) {
      // chr() não pode gerar dados UTF-8 corretos com valor maior que 128, use mb_decode_numericentity().
      $msg .= mb_decode_numericentity('&#'.$i.';', $convmap, 'UTF-8');
    }

    // var_dump($msg);
    var_dump(escape_javascript_string($msg));

### Veja Também

- mb_encode_numericentity() - Codificar caractere para referência numérica HTML

# mb_detect_encoding

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_detect_encoding — Detectar a codificação de caracteres

### Descrição

function mb_detect_encoding(string `$string`, array|string|null `$encodings` = `null`, bool `$strict` = `false`): string|false

Detecta a codificação de caracteres mais provável para a string `string` a partir de uma lista de candidatos.

A partir do PHP 8.1, esta função usa heurística para detectar qual das codificações de texto válidas na lista especificada tem maior probabilidade de estar correta e pode não estar na ordem das codificações fornecidas no parâmetro `encodings`.

A detecção automática da codificação de caracteres pretendida nunca pode ser totalmente confiável; sem informações adicionais, é semelhante a decodificar uma string criptografada sem a chave. É sempre preferível usar uma indicação de codificação de caracteres armazenada ou transmitida com os dados, como um cabeçalho HTTP "Content-Type".

Esta função é mais útil com codificações multibyte, onde nem todas as sequências de bytes formam uma string válida. Se a string de entrada contiver tal sequência, essa codificação será rejeitada.

Aviso

# O resultado não é preciso

O nome dessa função é enganoso: ela realiza "adivinhação" em vez de "detecção".

Os palpites estão longe de ser precisos e, portanto, esta função não pode ser usada para detectar com precisão a codificação correta de caracteres.

### Parâmetros

`string`

  A string sendo inspecionada.

`encodings`

  Uma lista de codificações de caracteres para tentar. A lista pode ser especificada como um array de strings ou uma única string separada por vírgulas.

  Se `encodings` for omitido ou `null`, a detect_order atual (definida com a opção de configuração mbstring.detect_order, ou função mb_detect_order()) será usada.

`strict`

  Controla o comportamento quando `string` não é válida em nenhuma das `encodings` listadas. Se `strict` for definido como `false`, a codificação mais próxima correspondente será retornada; se `strict` for definido como `true`, `false` será retornado.

  O valor padrão para `strict` pode ser definido com a opção de configuração mbstring.strict_detection.

### Valor Retornado

A codificação de caracteres detectada ou `false` se a string não for válida em nenhuma das codificações listadas.

### Registro de Alterações

Versão | Descrição
--- | ---
8.2.0 | mb_detect_encoding() não retornará mais as seguintes codificações não textuais: `"Base64"`, `"QPrint"`, `"UUencode"`, `"HTML entities"`, `"7 bit"` e `"8 bit"`.

### Exemplos

Exemplo #1 Exemplo de mb_detect_encoding()

    <?php

    $str = "\x95\xB6\x8E\x9A\x83\x52\x81\x5B\x83\x68";

    // Detecta codificação de caracteres com a ordem de detecção atual
    var_dump(mb_detect_encoding($str));

    // "auto" é expandido de acordo com mbstring.language
    var_dump(mb_detect_encoding($str, "auto"));

    // Especifica parâmetro "encodings" com lista separada por vírgula
    var_dump(mb_detect_encoding($str, "JIS, eucjp-win, sjis-win"));

    // Usa array para especificar parâmetro "encodings"
    $encodings = [
      "ASCII",
      "JIS",
      "EUC-JP"
    ];
    var_dump(mb_detect_encoding($str, $encodings));
    ?>

O exemplo acima produzirá:

    string(5) "ASCII"
    string(5) "ASCII"
    string(8) "SJIS-win"
    string(5) "ASCII"

Exemplo #2 Efeito do parâmetro `strict`

    <?php
    // 'áéóú' codificado em ISO-8859-1
    $str = "\xE1\xE9\xF3\xFA";

    // A string não é válida em ASCII ou UTF-8, mas UTF-8 é considerado uma correspondência mais próxima
    var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8'], false));
    var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8'], true));

    // Se uma codificação válida for encontrada, o parâmetro strict não muda o resultado
    var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8', 'ISO-8859-1'], false));
    var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8', 'ISO-8859-1'], true));
    ?>

O exemplo acima produzirá:

    string(5) "UTF-8"
    bool(false)
    string(10) "ISO-8859-1"
    string(10) "ISO-8859-1"

Em alguns casos, a mesma sequência de bytes pode formar uma string válida em várias codificações de caracteres, e é impossível saber qual interpretação foi pretendida. Por exemplo, entre muitos outros, a sequência de bytes "\xC4\xA2" poderia ser:

- "Ä¢" (U+00C4 LATIN CAPITAL LETTER A WITH DIAERESIS seguido por U+00A2 CENT SIGN) codificado em qualquer um de of ISO-8859-1, ISO-8859-15, ou Windows-1252
- "ФЂ" (U+0424 CYRILLIC CAPITAL LETTER EF seguido por U+0402 CYRILLIC CAPITAL LETTER DJE) codificado em ISO-8859-5
- "Ģ" (U+0122 LATIN CAPITAL LETTER G WITH CEDILLA) codificado em UTF-8

Exemplo #3 Efeito da ordem quando várias codificações correspondem

    <?php
    $str = "\xC4\xA2";

    // A string é válida em todas as três codificações, mas a primeira listada pode nem sempre ser a retornada
    var_dump(mb_detect_encoding($str, ['UTF-8']));
    var_dump(mb_detect_encoding($str, ['UTF-8', 'ISO-8859-1', 'ISO-8859-5'])); // a partir do PHP 8.1, retorna ISO-8859-1 em vez de UTF-8
    var_dump(mb_detect_encoding($str, ['ISO-8859-1', 'ISO-8859-5', 'UTF-8']));
    var_dump(mb_detect_encoding($str, ['ISO-8859-5', 'UTF-8', 'ISO-8859-1']));
    ?>

O exemplo acima produzirá:

    string(5) "UTF-8"
    string(10) "ISO-8859-1"
    string(10) "ISO-8859-1"
    string(10) "ISO-8859-5"

### Veja Também

- mb_detect_order() - Define ou obtém a ordem de detecção de codificação de caracteres

# mb_detect_order

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_detect_order — Define ou obtém a ordem de detecção de codificação de caracteres

### Descrição

function mb_detect_order(array|string|null `$encoding` = `null`): array|bool

Define a ordem automática de detecção de codificação de caracteres para `encoding`.

### Parâmetros

`encoding`

  `encoding` é um array ou lista de codificações de caracteres separadas por vírgula. Veja codificações suportadas.

  Se `encoding` for omitido ou `null`, ele retorna a ordem atual de detecção de codificação de caracteres como um array.

  Essa configuração afeta mb_detect_encoding() e mb_send_mail().

  `mbstring` implementa atualmente os seguintes filtros de detecção de codificação. Se houver uma sequência de bytes inválida para as seguintes codificações, a detecção de codificação falhará.

  `UTF-8`, `UTF-7`, `ASCII`, `EUC-JP`,`SJIS`, `eucJP-win`, `SJIS-win`, `JIS`, `ISO-2022-JP`

  Para `ISO-8859-*`, `mbstring` sempre detecta como `ISO-8859-*`.

  Para `UTF-16`, `UTF-32`, `UCS2` e `UCS4`, a detecção de codificação sempre falhará.

### Valor Retornado

Ao definir a ordem de detecção de codificação, `true` é retornado em caso de sucesso ou `false` em caso de falha.

Ao obter a ordem de detecção de codificação, um array ordenado das codificações é retornado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `encoding` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplos de mb_detect_order()

    <?php
    /* Define ordem de detecção por lista enumerada */
    mb_detect_order("eucjp-win,sjis-win,UTF-8");

    /* Define ordem de detecção por array */
    $ary[] = "ASCII";
    $ary[] = "JIS";
    $ary[] = "EUC-JP";
    mb_detect_order($ary);

    /* Exibe ordem de detecção atual */
    echo implode(", ", mb_detect_order());
    ?>

Exemplo #2 Exemplo mostrando ordens de detecção inúteis

    ; Sempre detecta como ISO-8859-1
    detect_order = ISO-8859-1, UTF-8

    ; Sempre detecta como UTF-8, porque os valores ASCII/UTF-7 são
    ; válidos para UTF-8
    detect_order = UTF-8, ASCII, UTF-7

### Veja Também

- mb_internal_encoding() - Define/Obtém a codificação de caracteres interna
- mb_http_input() - Detecta a codificação de caracteres de entrada HTTP
- mb_http_output() - Define/Obtém a codificação de caracteres de saída HTTP
- mb_send_mail() - Envia email codificado

# mb_encode_mimeheader

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_encode_mimeheader — Codificar string para cabeçalho MIME

### Descrição

function mb_encode_mimeheader(
string `$string`,
?string `$charset` = `null`,
?string `$transfer_encoding` = `null`,
string `$newline` = "\r\n",
int `$indent` = 0
): string

Codifica uma string `string` pelo esquema de codificação de cabeçalho MIME.

### Parâmetros

`string`

  A string a ser codificada. Sua codificação deve ser a mesma que mb_internal_encoding().

`charset`

  `charset` especifica o nome do conjunto de caracteres no qual `string` está representada. O valor padrão é determinado pela configuração NLS atual (`mbstring.language`).

`transfer_encoding`

  `transfer_encoding` especifica o esquema de codificação MIME. Deve ser ou `"B"` (Base64) ou `"Q"` (Quoted-Printable). Retrocede para `"B"` se não fornecido.

`newline`

  `newline` especifica o marcador de EOL (end-of-line) com o qual mb_encode_mimeheader() realiza a quebra de linha (um termo » RFC, o ato de quebrar uma linha mais longa que um certo comprimento em várias linhas. O comprimento é atualmente codificado como 74 caracteres). Retrocede para `"\r\n"` (CRLF) se não fornecido.

`indent`

  Recuo da primeira linha (número de caracteres no cabeçalho antes de `string`).

### Valor Retornado

Uma versão convertida da string representada em ASCII.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Bytes `NUL` (0) não são mais excluídos quando codificados através da codificação Quoted-Printable, mas são codificados como `=00`.
8.0.0 | `charset` e `transfer_encoding` agora são anuláveis.

### Exemplos

Exemplo #1 Exemplo de mb_encode_mimeheader()

    <?php
    $name = "太郎"; // kanji
    $mbox = "kru";
    $doma = "gtinn.mon";
    $addr = '"' . addcslashes(mb_encode_mimeheader($name, "UTF-7", "Q"), '"') . '" <' . $mbox . "@" . $doma . ">";
    echo $addr;
    ?>

O exemplo acima produzirá:

    "=?UTF-7?Q?+WSqQzg-?=" <kru@gtinn.mon>

### Notas

> Nota:

> Esta função não é projetada para quebrar linhas em pontos de quebra de contexto de nível superior (limites de palavra, etc.). Esse comportamento pode poluir a string original com espaços inesperados.

### Veja Também

- mb_decode_mimeheader() - Decodifica string no campo de cabeçalho MIME

# mb_encode_numericentity

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_encode_numericentity — Codificar caractere para referência numérica HTML

### Descrição

function mb_encode_numericentity(
string `$string`,
array `$map`,
?string `$encoding` = `null`,
bool `$hex` = `false`
): string

Converte códigos de caractere especificados em string `string` de códigos de caractere para referência numérica de caractere HTML.

### Parâmetros

`string`

  A string a ser codificada.

`map`

  `map` é um array que especifica a área de código para converter.

`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.
`hex`

  Se a referência de entidade retornada deve estar em notação hexadecimal (caso contrário, estará em notação decimal).

### Valor Retornado

A string convertida.

### Erros/Exceções

Lança uma exceção ValueError se `map` não for uma lista de ints.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | mb_encode_numericentity() agora lança uma exceção ValueError se `map` não for uma lista de ints.
8.0.0 | O parâmetro `encoding` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo de `map`

    <?php

    $convmap = array (
     int start_code1, int end_code1, int offset1, int mask1,
     int start_code2, int end_code2, int offset2, int mask2,
     ........
     int start_codeN, int end_codeN, int offsetN, int maskN );
    // Especifique o valor Unicode para start_codeN e end_codeN
    // Adicione offsetN ao valor e faça um 'AND' bit a bit com maskN, então
    // converta o valor para referência numérica de string.
    ?>

Exemplo #2 Exemplo de mb_encode_numericentity()

    <?php
    $str = "aAæÆあア𩸽";

    /* Converte todos os caracteres UTF8 de até 4 bytes para referência numérica de caracteres HTML */
    $convmap = [0, 0x1FFFFF, 0, 0x10FFFF];
    var_dump(mb_encode_numericentity($str, $convmap, "utf8"));

    /* Converte somente caracteres UTF8 de 2 bytes e de 4 bytes para referência numérica de caracteres HTML */
    $convmap = [
        0x80, 0x7FF, 0, 0x10FFFF,
        0x10000, 0x1FFFFF, 0, 0x10FFFF,
    ];
    var_dump(mb_encode_numericentity($str, $convmap, "utf8"));
    ?>

O exemplo acima produzirá:

    string(46) "&#97;&#65;&#230;&#198;&#12354;&#12450;&#40509;"
    string(28) "aA&#230;&#198;あア&#40509;"

### Veja Também

- mb_decode_numericentity() - Decodifica referência de string numérica HTML para caractere

# mb_encoding_aliases

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mb_encoding_aliases — Obtém aliases de um tipo de codificação conhecido

### Descrição

function mb_encoding_aliases(string `$encoding`): array

Retorna um array de aliases para um tipo de `encoding` conhecido.

### Parâmetros

`encoding`

  O tipo de codificação a ser verificado, para aliases.

### Valor Retornado

Retorna um array indexada numericamente de aliases de codificação.

### Erros/Exceções

Lança um ValueError se `encoding` for desconhecido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Se o `encoding` for desconhecido, agora é lançado um ValueError; anteriormente, um `E_WARNING` era emitido, e a função retornava `false`.

### Exemplos

Exemplo #1 Exemplo de mb_encoding_aliases()

    <?php
    $encoding        = 'ASCII';
    $known_encodings = mb_list_encodings();

    if (in_array($encoding, $known_encodings)) {

        $aliases = mb_encoding_aliases($encoding);
        print_r($aliases);

    } else {

        echo "Unknown ($encoding) encoding.\n";

    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => ANSI_X3.4-1968
        [1] => iso-ir-6
        [2] => ANSI_X3.4-1986
        [3] => ISO_646.irv:1991
        [4] => US-ASCII
        [5] => ISO646-US
        [6] => us
        [7] => IBM367
        [8] => cp367
        [9] => csASCII
    )

### Veja Também

- mb_list_encodings() - Retorna um array de todas as codificações suportadas

# mb_ereg

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg — Correspondência de expressão regular com suporte multibyte

### Descrição

function mb_ereg(string `$pattern`, string `$string`, array `&$matches` = `null`): bool

Executa a correspondência de expressão regular com suporte multibyte..

### Parâmetros

`pattern`

  O padrão de busca.

`string`

  A string de busca.

`matches`

  Se forem encontradas correspondências para substrings entre parênteses de `pattern` e a função for chamada com o terceiro argumento `matches`, as correspondências serão armazenadas nos elementos do array `matches`. Se não forem encontradas correspondências, `matches` é definido como um array vazio.

  $matches[1] conterá a substring que começa no primeiro parêntese à esquerda; $matches[2] conterá a substring que começa no segundo parêntese, e assim por diante. $matches[0] conterá uma cópia da string completa correspondida.

### Valor Retornado

Retorna se `pattern` corresponde a `string`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Esta função agora retorna `true` em caso de sucesso. Anteriormente, ela retornava o comprimento em bytes da string correspondida se uma correspondência para `pattern` fosse encontrada em `string` e `matches` fosse passado. Se o parâmetro opcional `matches` não fosse passado ou o comprimento da string correspondida fosse `0`, esta função retornava `1`.
7.1.0 | mb_ereg() agora define `matches` como um array vazio se nada for correspondido. Anteriormente, `matches` não era modificado nesse caso.

### Notas

> Nota: A codificação interna ou a codificação de caracteres especificada por mb_regex_encoding() será usada como a codificação de caracteres para esta função.

### Veja Também

- mb_regex_encoding() - Define/Obtém codificação de caracteres para regex multibyte
- mb_eregi() - Correspondência de expressão regular sem diferenciar maiúsculas e minúsculas com suporte multibyte

# mb_ereg_match

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_match — Coincidência de expressão regular para string multibyte

### Descrição

function mb_ereg_match(string `$pattern`, string `$string`, ?string `$options` = `null`): bool

Uma correspondência de expressão regular para uma string multibyte

> Nota: `pattern` só é correspondido no início de `string`.

### Parâmetros

`pattern`

  O padrão de expressão regular.

`string`

  A string sendo avaliada.

`options`

  A opção de pesquisa. Consulte mb_regex_set_options() para explicação.

### Valor Retornado

Retorna `true` se `string` coincide com a expressão regular `pattern`, `false` se não.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `options` é anulável agora.

### Notas

> Nota: A codificação interna ou a codificação de caracteres especificada por mb_regex_encoding() será usada como a codificação de caracteres para esta função.

### Veja Também

- mb_regex_encoding() - Define/Obtém codificação de caracteres para regex multibyte
- mb_ereg() - Correspondência de expressão regular com suporte multibyte

# mb_ereg_replace

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_replace — Substituir expressão regular com suporte a multibyte

### Descrição

function mb_ereg_replace(
string `$pattern`,
string `$replacement`,
string `$string`,
?string `$options` = `null`
): string|false|null

Examina `string` em busca de correspondências com `pattern`, em seguida, substitui o texto correspondido por `replacement`

### Parâmetros

`pattern`

  O padrão de expressão regular.

  Caracteres multibyte podem ser usados em `pattern`.

`replacement`

  O texto de substituição.

`string`

  A string sendo verificada.

`options`
  A opção de pesquisa. Consulte mb_regex_set_options() para explicação.

### Valor Retornado

A string resultante em caso de sucesso, ou `false` em caso de erro. Se `string` não for válida para a codificação atual, `null` é retornado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `options` é anulável agora.
7.1.0 | A função verifica se `string` é válida para a codificação atual.
7.1.0 | O modificador `e` foi descontinuado.

### Notas

> Nota: A codificação interna ou a codificação de caracteres especificada por mb_regex_encoding() será usada como a codificação de caracteres para esta função.

Aviso

Nunca use o modificador `e` ao trabalhar com entradas não confiáveis. Nenhum escape automático acontecerá (como é conhecido em preg_replace()). Não cuidar disso provavelmente criará vulnerabilidades de execução remota de código na sua aplicação.

### Veja Também

- mb_regex_encoding() - Define/Obtém codificação de caracteres para regex multibyte
- mb_eregi_replace() - Substituir expressão regular com suporte multibyte, ignorando maiúsculas e minúsculas

# mb_ereg_replace_callback

(PHP 5 >= 5.4.1, PHP 7, PHP 8)

mb_ereg_replace_callback — Realiza uma busca e substituição de expressão regular com suporte a string multibyte usando um callback

### Descrição

function mb_ereg_replace_callback(
string `$pattern`,
callable `$callback`,
string `$string`,
?string `$options` = `null`
): string|false|null

Examina `string` em busca de correspondências com `pattern`, em seguida, substitui o texto correspondido pelo resultado da função `callback`.

O comportamento desta função é quase idêntico ao de mb_ereg_replace(), exceto pelo fato de que, em vez de `replacement`, deve-se especificar um `callback`.

### Parâmetros

`pattern`

  O padrão de expressão regular.

  Caracteres multibyte podem ser usados em `pattern`.

`callback`

  Um callback que será chamado e receberá um array de elementos correspondidos na `string`. O callback deve retornar a string de substituição.

  Você frequentemente precisará da função `callback` para um mb_ereg_replace_callback() em apenas um lugar. Nesse caso, você pode usar uma função anônima para declarar o retorno de chamada dentro da chamada para mb_ereg_replace_callback(). Fazendo isso, você tem todas as informações para a chamada em um só lugar e não polui o namespace da função com o nome de uma função de callback não utilizada em nenhum outro lugar.

`string`

  A string sendo verificada.

`options`

  A opção de pesquisa. Consulte mb_regex_set_options() para explicação.

### Valor Retornado

A string resultante em caso de sucesso ou `false` em caso de erro. Se `string` não for válida para a codificação atual, `null` é retornado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `options` é anulável agora.
7.1.0 | A função verifica se `string` é válida para a codificação atual.

### Exemplos

Exemplo #1 Exemplo de mb_ereg_replace_callback()

    <?php
    // este texto foi usado em 2002
    // queremos atualizá-lo para 2003
    $text = "April fools day is 04/01/2002\n";
    $text.= "Last christmas was 12/24/2001\n";
    // a função callback
    function next_year($matches)
    {
      // como de costume: $matches[0] é a correspondência completa
      // $matches[1] é a correspondência para a primeira sub-expressão
      // envolvida por '(...)' e assim por diante
      return $matches[1].($matches[2]+1);
    }
    echo mb_ereg_replace_callback(
                "(\d{2}/\d{2}/)(\d{4})",
                "next_year",
                $text);

    ?>

O exemplo acima produzirá:

    April fools day is 04/01/2003
    Last christmas was 12/24/2002

Exemplo #2 mb_ereg_replace_callback() usando função anônima

    <?php
    // este texto foi usado em 2002
    // queremos atualizá-lo para 2003
    $text = "April fools day is 04/01/2002\n";
    $text.= "Last christmas was 12/24/2001\n";

    echo mb_ereg_replace_callback(
                "(\d{2}/\d{2}/)(\d{4})",
                function ($matches) {
                   return $matches[1].($matches[2]+1);
                },
                $text);
    ?>

### Notas

> Nota: A codificação interna ou a codificação de caracteres especificada por mb_regex_encoding() será usada como a codificação de caracteres para esta função.

### Veja Também

- mb_regex_encoding() - Define/Obtém codificação de caracteres para regex multibyte
- mb_ereg_replace() - Substituir expressão regular com suporte a multibyte
- Funções Anônimas

# mb_ereg_search

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search — Correspondência de expressão regular multibyte para uma string multibyte predefinida

### Descrição

function mb_ereg_search(?string `$pattern` = `null`, ?string `$options` = `null`): bool

Realiza uma correspondência de expressão regular multibyte para uma string multibyte predefinida.

### Parâmetros

`pattern`

  O padrão de busca.

`options`

  A opção de busca. Veja mb_regex_set_options() para explicação.

### Valor Retornado

mb_ereg_search() retorna `true` se a string multibyte corresponder à expressão regular, ou `false` caso contrário. A string para correspondência é definida por mb_ereg_search_init(). Se `pattern` não for especificado, o anterior é utilizado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `pattern` e `options` agora são anuláveis.

### Notas

> Nota: A codificação interna ou a codificação de caracteres especificada por mb_regex_encoding() será usada como a codificação de caracteres para esta função.

### Veja Também

- mb_regex_encoding() - Define/Obtém codificação de caracteres para regex multibyte
- mb_ereg_search_init() - Configura a string e a expressão regular para uma correspondência de expressão regular multibyte

# mb_ereg_search_getpos

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_getpos — Retorna o ponto de início para a próxima correspondência de expressão regular

### Descrição

function mb_ereg_search_getpos(): int

Retorna o ponto de início para a próxima correspondência de expressão regular.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

mb_ereg_search_getpos() retorna o ponto de início da correspondência de expressão regular para mb_ereg_search(), mb_ereg_search_pos(), mb_ereg_search_regs(). A posição é representada em bytes a partir do início da string.

### Notas

> Nota: A codificação interna ou a codificação de caracteres especificada por mb_regex_encoding() será usada como a codificação de caracteres para esta função.

### Veja Também

- mb_regex_encoding() - Define/Obtém codificação de caracteres para regex multibyte
- mb_ereg_search_setpos() - Define o ponto de início para a próxima correspondência de expressão regular

# mb_ereg_search_getregs

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_getregs — Recupera o resultado da última correspondência de expressão regular multibyte

### Descrição

function mb_ereg_search_getregs(): array|false

Recupera o resultado da última correspondência de expressão regular multibyte

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array incluindo a sub-string da parte correspondente pela última mb_ereg_search(), mb_ereg_search_pos(), mb_ereg_search_regs(). Se houver algumas correspondências, o primeiro elemento terá a sub-string correspondente, o segundo elemento terá a primeira parte agrupada com colchetes, o terceiro elemento terá a segunda parte agrupada com colchetes, e assim por diante. Retorna `false` em caso de erro.

### Notas

> Nota: A codificação interna ou a codificação de caracteres especificada por mb_regex_encoding() será usada como a codificação de caracteres para esta função.

### Veja Também

- mb_regex_encoding() - Define/Obtém codificação de caracteres para regex multibyte
- mb_ereg_search_init() - Configura a string e a expressão regular para uma correspondência de expressão regular multibyte

# mb_ereg_search_init

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_init — Configura a string e a expressão regular para uma correspondência de expressão regular multibyte

### Descrição

function mb_ereg_search_init(string `$string`, ?string `$pattern` = `null`, ?string `$options` = `null`): bool

mb_ereg_search_init() configura `string` e `pattern` para uma expressão regular multibyte. Esses valores são usados para mb_ereg_search(), mb_ereg_search_pos() e mb_ereg_search_regs().

### Parâmetros

`string`

  A string de busca.

`pattern`

  O padrão de busca.

`options`

  A opção de busca. Consulte mb_regex_set_options() para obter uma explicação.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `pattern` e `options` são anuláveis agora.

### Notas

> Nota: A codificação interna ou a codificação de caracteres especificada por mb_regex_encoding() será usada como a codificação de caracteres para esta função.

### Veja Também

- mb_regex_encoding() - Define/Obtém codificação de caracteres para regex multibyte
- mb_ereg_search_regs() - Retorna a parte correspondida de uma expressão regular multibyte

# mb_ereg_search_pos

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_pos — Retorna a posição e o comprimento de uma parte correspondida da expressão regular multibyte para uma string multibyte predefinida

### Descrição

function mb_ereg_search_pos(?string `$pattern` = `null`, ?string `$options` = `null`): array|false

Retorna a posição e o comprimento de uma parte correspondida da expressão regular multibyte para uma string multibyte predefinida.

A string para a correspondência é especificada por mb_ereg_search_init(). Se não for especificada, a anterior será usada.

### Parâmetros

`pattern`

  O padrão de busca.

`options`

  A opção de busca. Consulte mb_regex_set_options() para obter uma explicação.

### Valor Retornado

Um array contendo dois elementos. O primeiro elemento é o deslocamento, em bytes, onde a correspondência começa em relação ao início da string de busca, e o segundo elemento é o comprimento, em bytes, da correspondência.

Se ocorrer um erro, é retornado `false`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `pattern` e `options` são anuláveis agora.

### Notas

> Nota: A codificação interna ou a codificação de caracteres especificada por mb_regex_encoding() será usada como a codificação de caracteres para esta função.

### Veja Também

- mb_regex_encoding() - Define/Obtém codificação de caracteres para regex multibyte
- mb_ereg_search_init() - Configura a string e a expressão regular para uma correspondência de expressão regular multibyte

# mb_ereg_search_regs

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_regs — Retorna a parte correspondida de uma expressão regular multibyte

### Descrição

function mb_ereg_search_regs(?string `$pattern` = `null`, ?string `$options` = `null`): array|false

Retorna a parte correspondida de uma expressão regular multibyte.

### Parâmetros

`pattern`

  O padrão de busca.

`options`

  A opção de busca. Consulte mb_regex_set_options() para obter uma explicação.

### Valor Retornado

mb_ereg_search_regs() executa a correspondência da expressão regular multibyte e, se houver alguma parte correspondida, ela retorna um array contendo a substring da parte correspondida como primeiro elemento, a primeira parte agrupada com colchetes como segundo elemento, a segunda parte agrupada como terceiro elemento, e assim por diante. Retorna `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `pattern` e `options` agora são anuláveis.

### Notas

> Nota: A codificação interna ou a codificação de caracteres especificada por mb_regex_encoding() será usada como a codificação de caracteres para esta função.

### Veja Também

- mb_regex_encoding() - Define/Obtém codificação de caracteres para regex multibyte
- mb_ereg_search_init() - Configura a string e a expressão regular para uma correspondência de expressão regular multibyte

# mb_ereg_search_setpos

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_setpos — Define o ponto de início para a próxima correspondência de expressão regular

### Descrição

function mb_ereg_search_setpos(int `$offset`): bool

mb_ereg_search_setpos() define o ponto de início de uma correspondência para mb_ereg_search().

### Parâmetros

`offset`

  A posição a definir. Se for negativo, conta a partir do final da string.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
7.1.0 | Suporte para `offset`s negativo foi adicionado.

### Notas

> Nota: A codificação interna ou a codificação de caracteres especificada por mb_regex_encoding() será usada como a codificação de caracteres para esta função.

### Veja Também

- mb_regex_encoding() - Define/Obtém codificação de caracteres para regex multibyte
- mb_ereg_search_init() - Configura a string e a expressão regular para uma correspondência de expressão regular multibyte

# mb_eregi

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_eregi — Correspondência de expressão regular sem diferenciar maiúsculas e minúsculas com suporte multibyte

### Descrição

function mb_eregi(string `$pattern`, string `$string`, array `&$matches` = `null`): bool

Executa a correspondência de expressão regular sem diferenciar maiúsculas e minúsculas com suporte multibyte.

### Parâmetros

`pattern`

  O padrão de expressão regular.

`string`

  A string sendo pesquisada.

`matches`

  Se correspondências forem encontradas para substrings entre parênteses de `pattern` e a função for chamada com o terceiro argumento `matches`, as correspondências serão armazenadas nos elementos do array `matches`. Se nenhuma correspondência for encontrada, `matches` será configurado como um array vazio.

  $matches[1] conterá a substring que começa em o primeiro parêntese à esquerda; $matches[2] conterá a substring que começa no segundo, e assim por diante. $matches[0] conterá uma cópia da string completa correspondida.

### Valor Retornado

Retorna se `pattern` corresponde a `string`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Esta função agora retorna `true` em caso de sucesso. Anteriormente, ela retornava o comprimento em bytes da string correspondida se uma correspondência para `pattern` fosse encontrada em `string` e `matches` fosse passado. Se o parâmetro opcional `matches` não fosse passado ou o comprimento da string correspondida fosse `0`, esta função retornava `1`.
7.1.0 | mb_eregi() agora define `matches` como um array vazio, se nada coincidir. Anteriormente, `matches` não era modificado nesse caso.

### Notas

> Nota: A codificação interna ou a codificação de caracteres especificada por mb_regex_encoding() será usada como a codificação de caracteres para esta função.

### Veja Também

- mb_regex_encoding() - Define/Obtém codificação de caracteres para regex multibyte
- mb_ereg() - Correspondência de expressão regular com suporte multibyte

# mb_eregi_replace

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_eregi_replace — Substituir expressão regular com suporte multibyte, ignorando maiúsculas e minúsculas

### Descrição

function mb_eregi_replace(
string `$pattern`,
string `$replacement`,
string `$string`,
?string `$options` = `null`
): string|false|null

Examina `string` em busca de correspondências com `pattern`, e substitui o texto correspondido por `replacement`.

### Parâmetros

`pattern`

  O padrão de expressão regular. Caracteres multibyte podem ser usados. A diferenciação entre maiúsculas e minúsculas será ignorada.

`replacement`

  O texto de substituição.

`string`

  A string pesquisada.

`options`
  A opção de pesquisa. Veja mb_regex_set_options() para explicação.

### Valor Retornado

A string resultante ou `false` em caso de erro. Se `string` não for válida para a codificação atual, `null` é retornado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `options` é anulável agora.
7.1.0 | A função verifica se `string` é válida para a codificação atual.
7.1.0 | O modificador `e` foi descontinuado.

### Notas

> Nota: A codificação interna ou a codificação de caracteres especificada por mb_regex_encoding() será usada como a codificação de caracteres para esta função.

Aviso

Nunca use o modificador `e` ao trabalhar com entradas não confiáveis. Nenhum escape automático acontecerá (como é conhecido em preg_replace()). Não cuidar disso provavelmente criará vulnerabilidades de execução remota de código na sua aplicação.

### Veja Também

- mb_regex_encoding() - Define/Obtém codificação de caracteres para regex multibyte
- mb_ereg_replace() - Substituir expressão regular com suporte a multibyte

# mb_get_info

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_get_info — Obtém configurações internas do mbstring

### Descrição

function mb_get_info(string `$type` = "all"): array|string|int|false|null

mb_get_info() retorna os parâmetros de configuração internos do mbstring.

### Parâmetros

`type`

  Se `type` não for especificado ou for especificado como `"all"`, `"internal_encoding"`, `"http_input"`, `"http_output"`, `"http_output_conv_mimetypes"`, `"mail_charset"`, `"mail_header_encoding"`, `"mail_body_encoding"`, `"illegal_chars"`, `"encoding_translation"`, `"language"`, `"detect_order"`, `"substitute_character"` e `"strict_detection"` serão retornados.

  Se `type` for especificado como `"internal_encoding"`, `"http_input"`, `"http_output"`, `"http_output_conv_mimetypes"`, `"mail_charset"`, `"mail_header_encoding"`, `"mail_body_encoding"`, `"illegal_chars"`, `"encoding_translation"`, `"language"`, `"detect_order"`, `"substitute_character"` ou `"strict_detection"`, o parâmetro de configuração especificado será retornado.

### Valor Retornado

Um array de informações do tipo se `type` não for especificado, caso contrário, um `type` específico, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Os `type`s `"func_overload"` e `"func_overload_list"` não são mais suportados.

### Veja Também

- mb_regex_encoding() - Define/Obtém codificação de caracteres para regex multibyte
- mb_http_output() - Define/Obtém a codificação de caracteres de saída HTTP

# mb_http_input

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_http_input — Detecta a codificação de caracteres de entrada HTTP

### Descrição

function mb_http_input(?string `$type` = `null`): array|string|false

Detecta a codificação de caracteres de entrada HTTP.

### Parâmetros

`type`

  A string de entrada especifica o tipo de entrada. `"G"` para GET, `"P"` para POST, `"C"` para COOKIE, `"S"` para string, `"L"` para lista, e `"I"` para a lista inteira (retornará um array). Se o tipo for omitido, ele retorna o último tipo de entrada processado.

### Valor Retornado

O nome da codificação de caracteres, conforme o `type`, ou um array de nomes de codificação de caracteres, se `type` for `"I"`. Se mb_http_input() não processar a entrada HTTP especificada, ele retorna `false`.

### Erros/Exceções

Lança uma exceção ValueError se `type` for inválido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | mb_http_input() agora lança uma exceção ValueError se `type` for inválido.
8.0.0 | `type` é anulável agora.

### Veja Também

- mb_internal_encoding() - Define/Obtém a codificação de caracteres interna
- mb_http_output() - Define/Obtém a codificação de caracteres de saída HTTP
- mb_detect_order() - Define ou obtém a ordem de detecção de codificação de caracteres

# mb_http_output

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_http_output — Define/Obtém a codificação de caracteres de saída HTTP

### Descrição

function mb_http_output(?string `$encoding` = `null`): string|bool

Define/obtém a codificação de caracteres de saída HTTP. A saída após a chamada desta função será convertida da codificação interna definida para `encoding`.

### Parâmetros

`encoding`

  Se `encoding` estiver definido, mb_http_output() define a codificação de caracteres de saída HTTP para `encoding`.

  Se `encoding` for omitido, mb_http_output() retorna a codificação de caracteres de saída HTTP atual.

### Valor Retornado

Se `encoding` for omitido, mb_http_output() retorna a codificação de caracteres de saída HTTP atual. Caso contrário, Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Lança uma exceção ValueError se `encoding` contiver bytes nulos.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | mb_http_output() agora lança uma exceção ValueError se `encoding` contiver bytes nulos.
8.0.0 | O parâmetro `encoding` agora pode ser nulo.

### Veja Também

- mb_internal_encoding() - Define/Obtém a codificação de caracteres interna
- mb_http_input() - Detecta a codificação de caracteres de entrada HTTP
- mb_detect_order() - Define ou obtém a ordem de detecção de codificação de caracteres

# mb_internal_encoding

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_internal_encoding — Define/Obtém a codificação de caracteres interna

### Descrição

function mb_internal_encoding(?string `$encoding` = `null`): string|bool

Define/Obtém a codificação de caracteres interna

### Parâmetros

`encoding`

  `encoding` é o nome da codificação de caracteres usado para a conversão de codificação de caracteres de entrada HTTP, conversão de codificação de caracteres de saída HTTP, e a codificação de caracteres padrão para funções de string definidas pelo módulo mbstring. Deve-se observar que a codificação interna é totalmente diferente da utilizada em regex multibyte.

### Valor Retornado

Se `encoding` for definido, então Retorna `true` em caso de sucesso ou `false` em caso de falha. Nesse caso, a codificação de caracteres para regex multibyte NÃO é alterada. Se `encoding` for omitido, então o nome atual da codificação de caracteres é retornado.

### Erros/Exceções

A partir do PHP 8.0.0, um ValueError é lançado se o valor de `encoding` for uma codificação inválida. Antes do PHP 8.0.0, um `E_WARNING` era emitido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `encoding` agora pode ser nulo.
8.0.0 | Agora lança um ValueError se `encoding` for uma codificação inválida. Anteriormente, um `E_WARNING` era emitido.

### Exemplos

Exemplo #1 Exemplo de mb_internal_encoding()

    <?php
    /* Define a codificação de caracteres interna como UTF-8 */
    mb_internal_encoding("UTF-8");

    /* Exibe a codificação de caracteres interna atual */
    echo mb_internal_encoding();
    ?>

### Veja Também

- mb_http_input() - Detecta a codificação de caracteres de entrada HTTP
- mb_http_output() - Define/Obtém a codificação de caracteres de saída HTTP
- mb_detect_order() - Define ou obtém a ordem de detecção de codificação de caracteres
- mb_regex_encoding() - Define/Obtém codificação de caracteres para regex multibyte

# mb_language

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_language — Define/Obtém o idioma atual

### Descrição

function mb_language(?string `$language` = `null`): string|bool

Define/Obtém o idioma atual.

### Parâmetros

`language`

  Usado para codificar mensagens de e-mail. Os idiomas válidos estão listados na tabela a seguir. mb_send_mail() usa essa configuração para codificar e-mails.

  Idioma | Charset | Codificação | Alias
  --- | --- | --- | ---
  German/de | ISO-8859-15 | Quoted-Printable | Deutsch
  English/en | ISO-8859-1 | Quoted-Printable |
  Armenian/hy | ArmSCII-8 | Quoted-Printable |
  Japanese/ja | ISO-2022-JP | BASE64 |
  Korean/ko | ISO-2022-KR | BASE64 |
  neutral | UTF-8 | BASE64 |
  Russian/ru | KOI8-R | Quoted-Printable |
  Turkish/tr | ISO-8859-9 | Quoted-Printable |
  Ukrainian/ua | KOI8-U | Quoted-Printable |
  uni | UTF-8 | BASE64 | universal
  Simplified Chinese/zh-cn | HZ | BASE64 |
  Traditional Chinese/zh-tw | BIG-5 | BASE64 |

### Valor Retornado

Se `language` for definido e `language` for válido, retorna `true`. Caso contrário, retorna `false`. Quando `language` é omitido ou `null`, retorna o nome do idioma como uma string.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `language` é anulável agora.

### Veja Também

- mb_send_mail() - Envia email codificado

# mb_lcfirst

(PHP 8 >= 8.4.0)

mb_lcfirst — Converte parap minúscula o primeiro caractere de uma string

### Descrição

function mb_lcfirst(string `$string`, ?string `$encoding` = `null`): string

Realiza uma operação lcfirst() segura para caracteres multi-byte, e retorna uma string com o primeiro caractere de `string` convertido para minúscula.

### Parâmetros

`string`
  A string de entrada.
`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.

### Valor Retornado

Retorna a string resultante.

### Veja Também

- mb_ucfirst() - Converte para maiúscula o primeiro caractere de uma string
- lcfirst() - Torna minúsculo o primeiro caractere de uma string

# mb_list_encodings

(PHP 5, PHP 7, PHP 8)

mb_list_encodings — Retorna um array de todas as codificações suportadas

### Descrição

function mb_list_encodings(): array

Retorna um array contendo todas as codificações suportadas.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array indexado numericamente.

### Erros/Exceções

Esta função não emite erros.

### Exemplos

Exemplo #1 Exemplo de mb_list_encodings()

    <?php

    print_r(mb_list_encodings());

    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => pass
        [1] => auto
        [2] => wchar
        [3] => byte2be
        [4] => byte2le
        [5] => byte4be
        [6] => byte4le
        [7] => BASE64
        [8] => UUENCODE
        [9] => HTML-ENTITIES
        [10] => Quoted-Printable
        [11] => 7bit
        [12] => 8bit
        [13] => UCS-4
        [14] => UCS-4BE
        [15] => UCS-4LE
        [16] => UCS-2
        [17] => UCS-2BE
        [18] => UCS-2LE
        [19] => UTF-32
        [20] => UTF-32BE
        [21] => UTF-32LE
        [22] => UTF-16
        [23] => UTF-16BE
        [24] => UTF-16LE
        [25] => UTF-8
        [26] => UTF-7
        [27] => UTF7-IMAP
        [28] => ASCII
        [29] => EUC-JP
        [30] => SJIS
        [31] => eucJP-win
        [32] => SJIS-win
        [33] => JIS
        [34] => ISO-2022-JP
        [35] => Windows-1252
        [36] => ISO-8859-1
        [37] => ISO-8859-2
        [38] => ISO-8859-3
        [39] => ISO-8859-4
        [40] => ISO-8859-5
        [41] => ISO-8859-6
        [42] => ISO-8859-7
        [43] => ISO-8859-8
        [44] => ISO-8859-9
        [45] => ISO-8859-10
        [46] => ISO-8859-13
        [47] => ISO-8859-14
        [48] => ISO-8859-15
        [49] => EUC-CN
        [50] => CP936
        [51] => HZ
        [52] => EUC-TW
        [53] => BIG-5
        [54] => EUC-KR
        [55] => UHC
        [56] => ISO-2022-KR
        [57] => Windows-1251
        [58] => CP866
        [59] => KOI8-R
    )

### Veja Também

- mb_encoding_aliases() - Obtém aliases de um tipo de codificação conhecido

# mb_ltrim

(PHP 8 >= 8.4.0)

mb_ltrim — Remove espaços em branco (ou outros caracteres) do início de uma string

### Descrição

function mb_ltrim(string `$string`, ?string `$characters` = `null`, ?string `$encoding` = `null`): string

Realiza uma operação ltrim() segura para strings multi-byte. Remove espaços em branco (ou outros caracteres) do início de uma string.

Sem o segundo parâmetro, mb_ltrim() removerá estes caracteres:

- `" "` (Unicode U+0020), um espaço em branco normal.
- `"\t"` (Unicode U+0009), uma tabulação horizontal.
- `"\n"` (Unicode U+000A), uma nova linha (alimentação de linha).
- `"\r"` (Unicode U+000D), um retorno de carro.
- `"\0"` (Unicode U+0000), o byte NUL.
- `"\v"` (Unicode U+000B), uma tabulação vertical.
- `"\f"` (Unicode U+000C), uma alimentação de formulário.
- `"\u00A0"` (Unicode U+00A0), um espaço sem quebra de palavra (NO-BREAK SPACE).
- `"\u1680"` (Unicode U+1680), uma marca de espaço Ogham.
- `"\u2000"` (Unicode U+2000), um EN QUAD.
- `"\u2001"` (Unicode U+2001), um EM QUAD.
- `"\u2002"` (Unicode U+2002), um EN SPACE.
- `"\u2003"` (Unicode U+2003), um EM SPACE.
- `"\u2004"` (Unicode U+2004), um THREE-PER-EM SPACE.
- `"\u2005"` (Unicode U+2005), um FOUR-PER-EM SPACE.
- `"\u2006"` (Unicode U+2006), um SIX-PER-EM SPACE.
- `"\u2007"` (Unicode U+2007), um FIGURE SPACE.
- `"\u2008"` (Unicode U+2008), um PUNCTUATION SPACE.
- `"\u2009"` (Unicode U+2009), um THIN SPACE.
- `"\u200A"` (Unicode U+200A), um HAIR SPACE.
- `"\u2028"` (Unicode U+2028), um LINE SEPARATOR.
- `"\u2029"` (Unicode U+2029), um PARAGRAPH SEPARATOR.
- `"\u202F"` (Unicode U+202F), um NARROW NO-BREAK SPACE.
- `"\u205F"` (Unicode U+205F), um MEDIUM MATHEMATICAL SPACE.
- `"\u3000"` (Unicode U+3000), um IDEOGRAPHIC SPACE.
- `"\u0085"` (Unicode U+0085), um NEXT LINE (NEL).
- `"\u180E"` (Unicode U+180E), um MONGOLIAN VOWEL SEPARATOR.

### Parâmetros

`string`
  A string de entrada.
`characters`
  Opcionalmente, os caracteres a serem removidos também podem ser especificados usando o parâmetro `characters`. Simplesmente liste todos os caracteres que precisam ser removidos.
`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.

### Valor Retornado

Esta função retorna uma string com espaços em branco removidos do início da `string`.

### Veja Também

- mb_trim() - Remove espaços em branco (ou outros caracteres) do início e do final de uma string
- mb_rtrim() - Remove espaços em branco (ou outros caracteres) do final de uma string
- ltrim() - Retira espaços em branco (ou outros caracteres) do início de uma string

# mb_ord

(PHP 7 >= 7.2.0, PHP 8)

mb_ord — Obtém o ponto de código Unicode do caractere

### Descrição

function mb_ord(string `$string`, ?string `$encoding` = `null`): int|false

Retorna o valor do ponto de código Unicode do caractere fornecido.

Esta função complementa mb_chr().

### Parâmetros

`string`

  Uma string

`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.

### Valor Retornado

O ponto de código Unicode para o primeiro caractere de `string` ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `encoding` agora pode ser nulo.

### Exemplos

Exemplo #1 Um exemplo básico de mb_ord()

    <?php
    var_dump(mb_ord("A", "UTF-8"));
    var_dump(mb_ord("🐘", "UTF-8"));
    var_dump(mb_ord("\x80", "ISO-8859-1"));
    var_dump(mb_ord("\x80", "Windows-1252"));
    ?>

O exemplo acima produzirá:

int(65)
int(128024)
int(128)
int(8364)

### Veja Também

- mb_internal_encoding() - Define/Obtém a codificação de caracteres interna
- mb_chr() - Retorna um caractere pelo valor do ponto de código Unicode
- IntlChar::ord() - Retorna o valor do ponto de código Unicode do caractere
- ord() - Converte o primeiro byte de uma string para um valor entre 0 e 255

# mb_output_handler

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_output_handler — Callback converte a codificação de caracteres no buffer de saída

### Descrição

function mb_output_handler(string `$string`, int `$status`): string

mb_output_handler() é um callback ob_start(). mb_output_handler() converte caracteres no buffer de saída da codificação de caracteres interna para a codificação de caracteres de saída HTTP.

### Parâmetros

`string`

  O conteúdo do buffer de saída.

`status`

  O status do buffer de saída.

### Valor Retornado

A string convertida.

### Exemplos

Exemplo #1 Exemplo de mb_output_handler()

    <?php
    mb_http_output("UTF-8");
    ob_start("mb_output_handler");
    ?>

### Notas

> Nota:

> Se você deseja enviar dados binários, como uma imagem, um cabeçalho Content-Type: deve ser definido usando header() antes que quaisquer dados binários sejam enviados ao cliente (por exemplo, header("Content-Type: image/png")). Se o cabeçalho Content-Type: for enviado, a conversão de codificação de caracteres de saída não será realizada.

> Observe que se 'Content-Type: text/*' for enviado, o corpo do conteúdo é considerado como texto; a conversão será realizada.

### Veja Também

- ob_start() - Ativa o buffer de saída

# mb_parse_str

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_parse_str — Analisa dados GET/POST/COOKIE e define variável global

### Descrição

function mb_parse_str(string `$string`, array `&$result`): bool

Analisa dados GET/POST/COOKIE e define variáveis globais. Como o PHP não fornece dados brutos POST/COOKIE, ele só pode ser usado para dados GET por enquanto. Analisa dados codificados em URL, detecta a codificação, converte a codificação para a codificação interna e define valores para o `result` array ou variáveis globais.

### Parâmetros

`string`

  Os dados codificados em URL.

`result`

  Um array contendo valores decodificados e convertidos de caracteres.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O segundo parâmetro não é mais opcional.
7.2.0 | Chamar mb_parse_str() sem o segundo parâmetro foi descontinuado.

### Veja Também

- mb_detect_order() - Define ou obtém a ordem de detecção de codificação de caracteres
- mb_internal_encoding() - Define/Obtém a codificação de caracteres interna

# mb_preferred_mime_name

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_preferred_mime_name — Obter uma string MIME charset

### Descrição

function mb_preferred_mime_name(string `$encoding`): string|false

Obtém MIME charset string para uma codificação específica.

### Parâmetros

`encoding`

  A codificação que está sendo verificada.

### Valor Retornado

A string contendo o conjunto de caracteres MIME (`charset`) para a codificação de caracteres especificada em `encoding`, ou `false` se nenhum conjunto de caracteres for preferido para a codificação informada em `encoding`.

### Exemplos

Exemplo #1 Exemplo de mb_preferred_mime_name()

    <?php
    $outputenc = "sjis-win";
    mb_http_output($outputenc);
    ob_start("mb_output_handler");
    header("Content-Type: text/html; charset=" . mb_preferred_mime_name($outputenc));
    ?>

# mb_regex_encoding

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_regex_encoding — Define/Obtém codificação de caracteres para regex multibyte

### Descrição

function mb_regex_encoding(?string `$encoding` = `null`): string|bool

Define/obtém a codificação de caracteres para uma regex multibyte.

### Parâmetros

`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.

### Valor Retornado

Se `encoding` for definido, então Retorna `true` em caso de sucesso ou `false` em caso de falha. Neste caso, a codificação de caracteres interna NÃO é alterada. Se `encoding` for omitido, então o nome da codificação de caracteres atual para uma regex multibyte é retornado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `encoding` agora pode ser nulo.

### Veja Também

- mb_internal_encoding() - Define/Obtém a codificação de caracteres interna
- mb_ereg() - Correspondência de expressão regular com suporte multibyte

# mb_regex_set_options

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_regex_set_options — Define/Obtém as opções padrão para funções mbregex

### Descrição

function mb_regex_set_options(?string `$options` = `null`): string

Define/obtém as opções padrão descritas por `options` para funções de regex multibyte.

### Parâmetros

`options`

  As opções a serem definidas. Esta é uma string onde cada caractere é uma opção. Para definir um modo, o caractere de modo deve ser o último a ser definido, no entanto, pode haver apenas um modo, mas várias opções podem ser definidas.

  Opções de Regex
  Opção | Significado | Registro de Alterações
  --- | --- | ---
  i | correspondência ambígua ativada |
  x | Ativa a forma de padrão estendida |
  m | `'.'` corresponde a quebras de linha |
  s | `'^'` -> `'\A'`, `'$'` -> `'\Z'` |
  p | Mesmo que as opçõe `m` e `s` |
  l | Encontrar as correspondências mais longas |
  n | Ignorar correspondências vazias |
  e | eval() código resultante | Descontinuado desde o PHP 7.1.0 e removido a partir do PHP 8.0.0

  > Nota:

  > A opção `"e"` não tem efeito quando definida através de mb_regex_set_options(). Use-a com mb_ereg_replace() ou mb_eregi_replace().

  Modos de sintaxe Regex (apenas um pode ser definido)
  Modo | Significado
  --- | ---
  j | Java (Sun java.util.regex)
  u | GNU regex
  g | grep
  c | Emacs
  r | Ruby
  z | Perl
  b | Regex Básico POSIX
  d | Regex Estendido POSIX

### Valor Retornado

As opções anteriores. Se `options` for omitido ou `null`, retorna a string que descreve as opções atuais.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Se o parâmetro `options` for fornecido e não for `null`, as opções anteriores são retornadas. Anteriormente, as opções atuais eram retornadas.
8.0.0 | `options` é anulável agora.
8.0.0 | A opção `"e"` agora lança um ValueError.
7.1.0 | A opção `"e"` agora emite um `E_DEPRECATED`.

### Veja Também

- mb_split() - Divide uma string multibyte usando expressão regular
- mb_ereg() - Correspondência de expressão regular com suporte multibyte
- mb_eregi() - Correspondência de expressão regular sem diferenciar maiúsculas e minúsculas com suporte multibyte

# mb_rtrim

(PHP 8 >= 8.4.0)

mb_rtrim — Remove espaços em branco (ou outros caracteres) do final de uma string

### Descrição

function mb_rtrim(string `$string`, ?string `$characters` = `null`, ?string `$encoding` = `null`): string

Realiza uma operação rtrim() regura para strings multi-byte, e retorna uma string com espaços em branco (ou outros caracteres) removidos do final da `string`.

Sem o segundo parâmetro, mb_rtrim() removerá estes caracteres:

- `" "` (Unicode U+0020), um espaço em branco normal.
- `"\t"` (Unicode U+0009), uma tabulação horizontal.
- `"\n"` (Unicode U+000A), uma nova linha (alimentação de linha).
- `"\r"` (Unicode U+000D), um retorno de carro.
- `"\0"` (Unicode U+0000), o byte NUL.
- `"\v"` (Unicode U+000B), uma tabulação vertical.
- `"\f"` (Unicode U+000C), uma alimentação de formulário.
- `"\u00A0"` (Unicode U+00A0), um espaço sem quebra de palavra (NO-BREAK SPACE).
- `"\u1680"` (Unicode U+1680), uma marca de espaço Ogham.
- `"\u2000"` (Unicode U+2000), um EN QUAD.
- `"\u2001"` (Unicode U+2001), um EM QUAD.
- `"\u2002"` (Unicode U+2002), um EN SPACE.
- `"\u2003"` (Unicode U+2003), um EM SPACE.
- `"\u2004"` (Unicode U+2004), um THREE-PER-EM SPACE.
- `"\u2005"` (Unicode U+2005), um FOUR-PER-EM SPACE.
- `"\u2006"` (Unicode U+2006), um SIX-PER-EM SPACE.
- `"\u2007"` (Unicode U+2007), um FIGURE SPACE.
- `"\u2008"` (Unicode U+2008), um PUNCTUATION SPACE.
- `"\u2009"` (Unicode U+2009), um THIN SPACE.
- `"\u200A"` (Unicode U+200A), um HAIR SPACE.
- `"\u2028"` (Unicode U+2028), um LINE SEPARATOR.
- `"\u2029"` (Unicode U+2029), um PARAGRAPH SEPARATOR.
- `"\u202F"` (Unicode U+202F), um NARROW NO-BREAK SPACE.
- `"\u205F"` (Unicode U+205F), um MEDIUM MATHEMATICAL SPACE.
- `"\u3000"` (Unicode U+3000), um IDEOGRAPHIC SPACE.
- `"\u0085"` (Unicode U+0085), um NEXT LINE (NEL).
- `"\u180E"` (Unicode U+180E), um MONGOLIAN VOWEL SEPARATOR.

### Parâmetros

`string`
  A string de entrada.
`characters`
  Opcionalmente, os caracteres a serem removidos também podem ser especificados usando o parâmetro `characters`. Simplesmente liste todos os caracteres que precisam ser removidos.
`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.

### Valor Retornado

Retorna a string modificada.

### Veja Também

- mb_trim() - Remove espaços em branco (ou outros caracteres) do início e do final de uma string
- mb_ltrim() - Remove espaços em branco (ou outros caracteres) do início de uma string
- rtrim() - Retira espaços em branco (ou outros caracteres) do final de uma string

# mb_scrub

(PHP 7 >= 7.2.0, PHP 8)

mb_scrub — Substitui sequências de bytes malformadas pelo caractere substituto

### Descrição

function mb_scrub(string `$string`, ?string `$encoding` = `null`): string

Realiza uma conversão de conjunto de caracteres a partir da codificação especificada, ou a codificação padrão se nenhuma codificação for especificada, para a mesma codificação. Isso tem o efeito de substituir qualquer sequência de bytes inválida pelo caractere substituto.

### Parâmetros

`string`

  A string de entrada.

`encoding`

  A codificação usada para interpretar `string`. Se for omitida ou `null`, o mbstring.internal_encoding setting será usado se configurado, caso contrário, o default_charset setting será usado.

### Valor Retornado

O resultado string com sequências de bytes inválidas substituídas.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `encoding` agora pode ser nulo.

# mb_send_mail

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_send_mail — Envia email codificado

### Descrição

function mb_send_mail(
string `$to`,
string `$subject`,
string `$message`,
array|string `$additional_headers` = [],
?string `$additional_params` = `null`
): bool

Envia e-mails. Cabeçalhos e mensagens são convertidos e codificados de acordo com a configuração de mb_language(). É uma função encapsuladora para mail(), então veja também mail() para detalhes.

### Parâmetros

`to`

  Os endereços de e-mail para os quais o e-mail será enviado. Múltiplos destinatários podem ser especificados separando cada endereço em `to` por vírgula. Este parâmetro não é automaticamente codificado.

`subject`

  O assunto do e-mail.

`message`

  A mensagem do e-mail.

`additional_headers` (opcional)

  String ou array a ser inserido no final do cabeçalho do e-mail.

  Isso é tipicamente usado para adicionar cabeçalhos extras (De, Cc e Bcc). Múltiplos cabeçalhos extras devem ser separados por um CRLF (\r\n). Valide o parâmetro para não injetar cabeçalhos indesejados por atacantes.

  Se um array for passado, suas chaves são os nomes dos cabeçalhos e seus valores são os respectivos valores dos cabeçalhos.

  > Nota:

  > Ao enviar e-mails, o e-mail deve conter um cabeçalho `From`. Isso pode ser configurado com o parâmetro `additional_headers`, ou um padrão pode ser configurado no php.ini.

  > Falhar em fazer isso resultará em uma mensagem de erro semelhante a `Warning: mail(): "sendmail_from" not set in php.ini or custom "From:" header missing`. O cabeçalho `From` também define `Return-Path` no Windows.

  > Nota:

  > Se as mensagens não forem recebidas, tente usar apenas LF (\n). Alguns agentes de transferência de email Unix (notavelmente » qmail) substituem LF por CRLF automaticamente (o que leva a duplicação de CR se CRLF for usado). Isso deve ser usado apenas como último recurso, pois não está em conformidade com » RFC 2822.

`additional_params`

  `additional_params` é um parâmetro de linha de comando MTA útil ao definir o cabeçalho Return-Path correto ao usar sendmail.

  Este parâmetro é escapado internamente por escapeshellcmd() para evitar a execução de comandos. escapeshellcmd() evita a execução de comandos, mas permite adicionar parâmetros adicionais. Por razões de segurança, este parâmetro deve ser validado.

  Como escapeshellcmd() é aplicado automaticamente, alguns caracteres que são permitidos como endereços de e-mail por RFCs da Internet não podem ser usados. Programas que são obrigados a usar esses caracteres mail() não podem ser usados.

  O usuário que o servidor da web executa deve ser adicionado como um usuário confiável para o arquivo de configuração do sendmail para evitar a adição de um cabeçalho 'X-Warning' à mensagem quando o remetente do envelope (-f) é definido usando este método. Para usuários do sendmail, este arquivo é /etc/mail/trusted-users.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `additional_params` é anulável agora.
7.2.0 | O parâmetro `additional_headers` agora também aceita um array.

### Veja Também

- mail() - Envia e-mail
- mb_encode_mimeheader() - Codificar string para cabeçalho MIME
- mb_language() - Define/Obtém o idioma atual

# mb_split

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_split — Divide uma string multibyte usando expressão regular

### Descrição

function mb_split(string `$pattern`, string `$string`, int `$limit` = -1): array|false

Divide uma `string` multibyte usando expressão regular `pattern` e retorna o resultado como um array.

### Parâmetros

`pattern`

  O padrão da expressão regular.

`string`

  A string sendo dividida.

`limit`
  Se o parâmetro opcional `limit` for especificado, ele será dividido em `limit` elementos no máximo.

### Valor Retornado

O resultado como um array, ou `false` em caso de falha.

### Notas

> Nota: A codificação de caracteres especificada por mb_regex_encoding() será usada como a codificação de caracteres para esta função por padrão.

### Veja Também

- mb_regex_encoding() - Define/Obtém codificação de caracteres para regex multibyte
- mb_ereg() - Correspondência de expressão regular com suporte multibyte
- explode() - Divide uma string com base em outra string

# mb_str_pad

(PHP 8 >= PHP 8.3.0)

mb_str_pad — Preenche uma string multibyte para um comprimento específico com outra string multibyte

### Descrição

function mb_str_pad(
string `$string`,
int `$length`,
string `$pad_string` = " ",
int `$pad_type` = `STR_PAD_RIGHT`,
?string `$encoding` = `null`
): string

Esta função retorna a `string` preenchida à esquerda, à direita ou em ambos os lados até o comprimento de preenchimento especificado, onde o comprimento é medido em pontos de código Unicode. Se o argumento opcional `pad_string` não for fornecido, a `string` será preenchida com espaços, caso contrário, ela será preenchida com caracteres de `pad_string` até o limite.

### Parâmetros

`string`

  A string de entrada.

`length`

  Se o valor de `length` for negativo, menor ou igual ao comprimento da string de entrada, nenhum preenchimento ocorre, e a `string` será retornada.

`pad_string`

  > Nota:

  > O `pad_string` pode ser truncado se o número necessário de caracteres de preenchimento não puder ser dividido uniformemente pelo comprimento de `pad_string`.

`pad_type`

  O argumento opcional `pad_type` pode ser `STR_PAD_RIGHT`, `STR_PAD_LEFT`, ou `STR_PAD_BOTH`. Por padrão, `STR_PAD_RIGHT`.

`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.

### Valor Retornado

Retorna a string preenchida.

### Exemplos

Exemplo #1 Exemplo de mb_str_pad()

    <?php
    var_dump(mb_str_pad('▶▶', 6, '❤❓❇', STR_PAD_RIGHT)); // string(18) "▶▶❤❓❇❤"
    var_dump(mb_str_pad('▶▶', 6, '❤❓❇', STR_PAD_LEFT));  // string(18) "❤❓❇❤▶▶"
    var_dump(mb_str_pad('▶▶', 6, '❤❓❇', STR_PAD_BOTH));  // string(18) "❤❓▶▶❤❓"

    var_dump(mb_str_pad("🎉", 3, "祝", STR_PAD_LEFT));   // string(10) "祝祝🎉"
    ?>

# mb_str_split

(PHP 7 >= 7.4.0, PHP 8)

mb_str_split — Dada uma string multibyte, retorna um array de seus caracteres

### Descrição

function mb_str_split(string `$string`, int `$length` = 1, ?string `$encoding` = `null`): array

Esta função retornará um array de strings, sendo uma versão de str_split() com suporte para codificações de tamanho de caractere variável, bem como codificações de tamanho fixo de caracteres de 1, 2 ou 4 bytes. Se o parâmetro `length` for especificado, a string será dividida em partes do comprimento especificado em caracteres (não bytes). O parâmetro `encoding` pode ser especificado opcionalmente e é uma boa prática fazê-lo.

### Parâmetros

`string`

  A string para dividir em caracteres ou partes.

`length`

  Se especificado, cada elemento do array retornado será composto por vários caracteres em vez de um único caractere.

`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.

  Uma string especificando uma das codificações suportadas.

### Valor Retornado

mb_str_split() retorna um array de strings.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `encoding` agora pode ser nulo.
8.0.0 | Esta função não retorna mais `false` em caso de falha.

### Veja Também

- str_split() - Converte uma string em um array
- grapheme_str_split() - Separa uma string em um array
- explode() - Divide uma string com base em outra string

# mb_strcut

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strcut — Obtém parte da string

### Descrição

function mb_strcut(
string `$string`,
int `$start`,
?int `$length` = `null`,
?string `$encoding` = `null`
): string

mb_strcut() extrai uma substring de uma string de forma semelhante a mb_substr(), mas opera em bytes em vez de caracteres. Se a posição de corte estiver entre dois bytes de um caractere multibyte, o corte é realizado a partir do primeiro byte desse caractere. Essa também é a diferença para a função substr(), que simplesmente cortaria a string entre os bytes e resultaria em uma sequência de bytes malformada.

### Parâmetros

`string`

  A string a ser cortada.

`start`

  Se `start` for não negativo, a string retornada começará na posição de byte `start` em `string`, contando a partir do zero. Por exemplo, na string '`abcdef`', o byte na posição `0` é '`a`', o byte na posição `2` é '`c`', e assim por diante.

  Se `start` for negativo, a string retornada começará no byte `start` contando a partir do final de `string`. No entanto, se o valor absoluto de um `start` negativo for maior que o comprimento da string, a parte retornada começará do início de `string`.

`length`

  Comprimento em bytes. Se omitido ou `NULL` for passado, extrai todos os bytes até o final da string.

  Se `length` for negativo, a string retornada terminará no byte de número `length` contando a partir do final de `string`. No entanto, se o valor absoluto de um `length` negativo for maior que o número de caracteres após a posição de `start`, uma string vazia será retornada.

`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.

### Valor Retornado

mb_strcut() retorna a parte de `string` especificada pelos parâmetros `start` e `length`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | O comportamento agora é mais consistente em strings `UTF-8` e `UTF-16` inválidas.
8.0.0 | O parâmetro `encoding` agora pode ser nulo.

### Veja Também

- mb_substr() - Obtém parte da string
- mb_internal_encoding() - Define/Obtém a codificação de caracteres interna

# mb_strimwidth

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strimwidth — Obtém string truncada com largura especificada

### Descrição

function mb_strimwidth(
string `$string`,
int `$start`,
int `$width`,
string `$trim_marker` = "",
?string `$encoding` = `null`
): string

Trunca a string `string` para a largura especificada `width`, onde caracteres de meia largura contam como `1`, e caracteres de largura total contam como `2`. Consulte » http://www.unicode.org/reports/tr11/ para detalhes sobre larguras de caracteres do leste asiático.

### Parâmetros

`string`

  A string a ser decodificada.

`start`

  O deslocamento da posição inicial. Número de caracteres a partir do início da string (o primeiro caractere é 0), ou se start for negativo, o número de caracteres a partir do final da string.

`width`

  A largura do corte desejado. Se uma largura negativa for especificada, conta a partir do final da string.

  > Nota:

  > Passar uma largura negativa foi descontinuado a partir do PHP 8.3.0.

`trim_marker`

  Uma string que é adicionada ao final de string quando a string é truncada.

`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.

### Valor Retornado

A string truncada. Se `trim_marker` estiver definido, `trim_marker` substitui os últimos caracteres para corresponder à `width`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Passar uma largura negativa `width` para mb_strimwidth() agora foi descontinuado.
8.0.0 | O parâmetro `encoding` agora pode ser nulo.
7.1.0 | Adicionado suporte para `start`s e `width`s negativos.

### Exemplos

Exemplo #1 Exemplo de mb_strimwidth()

    <?php
    echo mb_strimwidth("Hello World", 0, 10, "...");
    // saída: "Hello W..."
    ?>

### Veja Também

- mb_strwidth() - Retorna a largura da string
- mb_internal_encoding() - Define/Obtém a codificação de caracteres interna

# mb_stripos

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_stripos — Encontra a posição da primeira ocorrência de uma string dentro de outra, sem diferenciar maiúsculas de minúsculas

### Descrição

function mb_stripos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

mb_stripos() retorna a posição numérica da primeira ocorrência de `needle` na string `haystack`. Ao contrário de mb_strpos(), mb_stripos() não faz distinção entre maiúsculas e minúsculas. Se `needle` não for encontrado, retorna `false`.

### Parâmetros

`haystack`

  A string da qual deve ser obtida a posição da primeira ocorrência de `needle`

`needle`

  A string a ser encontrada em `haystack`

`offset`

  A posição em `haystack` a partir da qual a pesquisa deve ser iniciada. Um valor negativo é contado no sentido contrário a partir do final da string.

`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.

### Valor Retornado

Retorna a posição numérica da primeira ocorrência de `needle` na string `haystack`, ou `false` se `needle` não for encontrado.

### Erros/Exceções

- Se `offset` for maior que o comprimento de `haystack`, um ValueError será lançado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `needle` agora aceita uma string vazia.
8.0.0 | O parâmetro `encoding` agora pode ser nulo.
7.1.0 | Adicionado suporte para `offset` negativo.

### Veja Também

- stripos() - Encontra a posição da primeira ocorrência de uma substring em uma string, de forma insensível a maiúsculas/minúsculas
- strpos() - Encontra a posição da primeira ocorrência de uma substring em uma string
- mb_strpos() - Encontra a posição da primeira ocorrência de uma string em outra

# mb_stristr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_stristr — Encontra a primeira ocorrência de uma string dentro de outra, sem diferenciar maiúsculas de minúsculas

### Descrição

function mb_stristr(
string `$haystack`,
string `$needle`,
bool `$before_needle` = `false`,
?string `$encoding` = `null`
): string|false

mb_stristr() encontra a primeira ocorrência de `needle` em `haystack` e retorna a parte de `haystack`. Ao contrário de mb_strstr(), mb_stristr() não faz distinção entre maiúsculas e minúsculas. Se `needle` não for encontrado, retorna `false`.

### Parâmetros

`haystack`

  A string da qual obter a primeira ocorrência de `needle`

`needle`

  A string a ser encontrada em `haystack`

`before_needle`

  Determina qual parte de `haystack` esta função retorna. Se definido como `true`, retorna toda `haystack` desde o início até a primeira ocorrência de `needle` (excluindo needle). Se definido como `false`, retorna toda `haystack` desde a primeira ocorrência de `needle` até o final (incluindo needle).

`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.

### Valor Retornado

Retorna a parte de `haystack`, ou `false` se `needle` não for encontrado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `needle` agora aceita uma string vazia.
8.0.0 | O parâmetro `encoding` agora pode ser nulo.

### Veja Também

- stristr() - strstr insensível a maiúsculas/minúsculas
- strstr() - Encontra a primeira ocorrência de uma string
- mb_strstr() - Encontra a primeira ocorrência de uma string em outra

# mb_strlen

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strlen — Obtém o comprimento da string

### Descrição

function mb_strlen(string `$string`, ?string `$encoding` = `null`): int

Obtém o comprimento de uma string.

### Parâmetros

`string`

  A string sendo verificada quanto ao comprimento.

`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.

### Valor Retornado

Retorna o número de caracteres em string `string` tendo codificação de caracteres `encoding`. Um caractere multibyte é contado como 1.

### Erros/Exceções

Se a codificação for desconhecida, um erro do nível `E_WARNING` é gerado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `encoding` agora pode ser nulo.

### Veja Também

- mb_internal_encoding() - Define/Obtém a codificação de caracteres interna
- grapheme_strlen() - Obtém o comprimento de uma string em unidade de grafema
- iconv_strlen() - Retorna a contagem de caracteres da string
- strlen() - Retorna o tamanho de uma string

# mb_strpos

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strpos — Encontra a posição da primeira ocorrência de uma string em outra

### Descrição

function mb_strpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

Encontra a posição da primeira ocorrência de `needle` na string de `haystack`.

Realiza uma operação strpos() segura para multibyte com base no número de caracteres. A posição do primeiro caractere é 0, a posição do segundo caractere é 1, e assim por diante.

### Parâmetros

`haystack`

  A string da qual será obtida a posição da primeira ocorrência de `needle`.

`needle`

  A string a ser encontrada em `haystack`. Em contraste com strpos(), valores numéricos não são aplicados como o valor ordinal de um caractere.

`offset`

  A posição de início da pesquisa. Se não for especificada, 0 é usado. Uma posição negativa conta a partir do final da string no sentido contrário.

`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.

### Valor Retornado

Retorna a posição numérica da primeira ocorrência de `needle` na string `haystack`. Se `needle` não for encontrada, retorna `false`.

### Erros/Exceções

- Se `offset` for maior que o comprimento de `haystack`, um ValueError será lançado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `needle` agora aceita uma string vazia.
8.0.0 | O parâmetro `encoding` agora pode ser nulo.
7.1.0 | Adicionado suporte para posições negativas no parâmetro `offset`.

### Veja Também

- mb_internal_encoding() - Define/Obtém a codificação de caracteres interna
- strpos() - Encontra a posição da primeira ocorrência de uma substring em uma string

# mb_strrchr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strrchr — Encontra a última ocorrência de um caractere em uma string dentro de outra

### Descrição

function mb_strrchr(
string `$haystack`,
string `$needle`,
bool `$before_needle` = `false`,
?string `$encoding` = `null`
): string|false

mb_strrchr() encontra a última ocorrência de `needle` em `haystack` e retorna a porção de `haystack`. Se `needle` não for encontrada, retorna `false`.

### Parâmetros

`haystack`

  A string da qual será obtida a última ocorrência de `needle`.

`needle`

  A string a ser encontrada em `haystack`.

`before_needle`

  Determina qual porção de `haystack` esta função retorna. Se definido como `true`, retorna toda `haystack` desde o início até a última ocorrência de `needle`. Se definido como `false`, retorna toda `haystack` desde a última ocorrência de `needle` até o final.

`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.

### Valor Retornado

Retorna a porção de `haystack`. ou `false` se `needle` não for encontrada.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `needle` agora aceita uma string vazia.
8.0.0 | O parâmetro `encoding` agora pode ser nulo.

### Veja Também

- strrchr() - Encontra a última ocorrência de um caractere em uma string
- mb_strstr() - Encontra a primeira ocorrência de uma string em outra
- mb_strrichr() - Encontra a última ocorrência de um caractere em uma string dentro de outra, sem diferenciar maiúsculas de minúsculas

# mb_strrichr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strrichr — Encontra a última ocorrência de um caractere em uma string dentro de outra, sem diferenciar maiúsculas de minúsculas

### Descrição

function mb_strrichr(
string `$haystack`,
string `$needle`,
bool `$before_needle` = `false`,
?string `$encoding` = `null`
): string|false

mb_strrichr() encontra a última ocorrência de `needle` em `haystack` e retorna a porção de `haystack`. Ao contrário de mb_strrchr(), mb_strrichr() é insensível a maiúsculas e minúsculas. Se `needle` não for encontrada, retorna `false`.

### Parâmetros

`haystack`

  A string da será obtida a última ocorrência de `needle`.

`needle`

  A string a ser encontrada em `haystack`.

`before_needle`

  Determina qual porção de `haystack` esta função retorna. Se definido como `true`, retorna toda `haystack` desde o início até a última ocorrência de `needle`. Se definido como `false`, retorna toda `haystack` desde a última ocorrência de `needle` até o final.

`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.

### Valor Retornado

Retorna a porção de `haystack`. ou `false` se `needle` não for encontrada.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `needle` agora aceita uma string vazia.
8.0.0 | O parâmetro `encoding` agora pode ser nulo.

### Veja Também

- mb_stristr() - Encontra a primeira ocorrência de uma string dentro de outra, sem diferenciar maiúsculas de minúsculas
- mb_strrchr() - Encontra a última ocorrência de um caractere em uma string dentro de outra

# mb_strripos

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strripos — Encontra a posição da última ocorrência de uma string em outra, sem diferenciar maiúsculas de minúsculas

### Descrição

function mb_strripos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

mb_strripos() realiza uma operação segura para multibyte de strripos() com base no número de caracteres. A posição de `needle` é contada a partir do início de `haystack`. A posição do primeiro caractere é 0. A posição do segundo caractere é 1. Ao contrário de mb_strrpos(), mb_strripos() é insensível a maiúsculas e minúsculas.

### Parâmetros

`haystack`

  A string da qual deve ser obtida a posição da última ocorrência de `needle`.

`needle`

  A string a ser encontrada em `haystack`.

`offset`

  Pode ser especificado para iniciar a busca a partir de um número arbitrário de caracteres de `haystack`. Valores negativos encerram a busca em um ponto arbitrário antes do final de `haystack`.

`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.

### Valor Retornado

Retorna a posição numérica da última ocorrência de `needle` na string `haystack` ou `false` se `needle` não for encontrada.

### Erros/Exceções

- Se `offset` for maior que o comprimento de `haystack`, um ValueError será lançado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `needle` agora aceita uma string vazia.
8.0.0 | O parâmetro `encoding` agora pode ser nulo.

### Veja Também

- strripos() - Encontra a posição da última ocorrência de uma substring em uma string, insensível a maiúsculas/minúsculas
- strrpos() - Encontra a posição da última ocorrência de uma substring em uma string
- mb_strrpos() - Encontra a posição da última ocorrência de uma string em outra string

# mb_strrpos

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strrpos — Encontra a posição da última ocorrência de uma string em outra string

### Descrição

function mb_strrpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

Realiza uma operação segura para multibyte strrpos() com base no número de caracteres. A posição de `needle` é contada a partir do início de `haystack`. A posição do primeiro caractere é 0. A posição do segundo caractere é 1.

### Parâmetros

`haystack`

  A string que está sendo verificada, para a última ocorrência de `needle`

`needle`

  A string a ser encontrada em `haystack`.

`offset`
  Pode ser especificado para começar a busca a partir de um número arbitrário de caracteres em `haystack`. Valores negativos interromperão a busca em um ponto arbitrário antes do final de `haystack`.
`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.

### Valor Retornado

Retorna a posição numérica da última ocorrência de `needle` na string `haystack`. Se `needle` não for encontrada, retorna `false`.

### Erros/Exceções

- Se `offset` for maior que o comprimento de `haystack`, um ValueError será lançado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `needle` agora aceita uma string vazia.
8.0.0 | O envio de `encoding` como terceiro argumento em vez de `offset` foi removido.
8.0.0 | O parâmetro `encoding` agora pode ser nulo.

### Veja Também

- mb_strpos() - Encontra a posição da primeira ocorrência de uma string em outra
- mb_internal_encoding() - Define/Obtém a codificação de caracteres interna
- strrpos() - Encontra a posição da última ocorrência de uma substring em uma string

# mb_strstr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strstr — Encontra a primeira ocorrência de uma string em outra

### Descrição

function mb_strstr(
string `$haystack`,
string `$needle`,
bool `$before_needle` = `false`,
?string `$encoding` = `null`
): string|false

mb_strstr() encontra a primeira ocorrência de `needle` em `haystack` e retorna a porção de `haystack`. Se `needle` não for encontrado, retorna `false`.

### Parâmetros

`haystack`

  A string da qual obter a primeira ocorrência de `needle`

`needle`

  A string a ser encontrada em `haystack`

`before_needle`

  Determina qual parte de `haystack` essa função retorna. Se definido como `true`, retorna toda a `haystack` desde o início até a primeira ocorrência de `needle` (excluindo needle). Se definido como `false`, retorna toda a `haystack` da primeira ocorrência de `needle` até o final (incluindo needle).

`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.

### Valor Retornado

Retorna a porção de `haystack`, ou `false` se `needle` não for encontrado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `needle` agora aceita uma string vazia.
8.0.0 | O parâmetro `encoding` agora pode ser nulo.

### Veja Também

- stristr() - strstr insensível a maiúsculas/minúsculas
- strstr() - Encontra a primeira ocorrência de uma string
- mb_stristr() - Encontra a primeira ocorrência de uma string dentro de outra, sem diferenciar maiúsculas de minúsculas

# mb_strtolower

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_strtolower — Torna uma string minúscula

### Descrição

function mb_strtolower(string `$string`, ?string `$encoding` = `null`): string

Retorna a `string` com todos os caracteres alfabéticos convertidos em minúsculas.

### Parâmetros

`string`

  A string a ser convertida em minúsculas.

`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.

### Valor Retornado

`string` com todos os caracteres alfabéticos convertidos em minúsculas.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | Implementadas regras condicionais de maiúscula/minúscula para a letra grega sigma.

### Exemplos

Exemplo #1 Exemplo de mb_strtolower()

    <?php
    $str = "Maria Tinha Um Cordeirinho e Ela O AMAVA";
    $str = mb_strtolower($str);
    echo $str; // Imprime maria tinha um cordeirinho e ela o amava
    ?>

Exemplo #2 Exemplo de mb_strtolower() com texto UTF-8 não-Latin

    <?php
    $str = "Τάχιστη αλώπηξ βαφής ψημένη γη, δρασκελίζει υπέρ νωθρού κυνός";
    $str = mb_strtolower($str, 'UTF-8');
    echo $str; // Imprime τάχιστη αλώπηξ βαφής ψημένη γη, δρασκελίζει υπέρ νωθρού κυνός
    ?>

### Notas

Ao contrário de strtolower(), 'alphabetic' é determinado pelas propriedades de caractere Unicode. Portanto, o comportamento desta função não é afetado pelas configurações de localidade e pode converter qualquer caractere com uma propriedade 'alphabetic', como um trema (ä).

Para obter mais informações sobre as propriedades Unicode, consulte » http://www.unicode.org/reports/tr21/.

### Veja Também

- mb_strtoupper() - Faz uma string ficar em maiúsculas
- mb_convert_case() - Realiza a conversão de caixa em uma string
- strtolower() - Converte uma string para minúsculas

# mb_strtoupper

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_strtoupper — Faz uma string ficar em maiúsculas

### Descrição

function mb_strtoupper(string `$string`, ?string `$encoding` = `null`): string

Retorna `string` com todos os caracteres alfabéticos convertidos para maiúsculas.

### Parâmetros

`string`

  A string que será convertida para maiúsculas.

`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.

### Valor Retornado

`string` com todos os caracteres alfabéticos convertidos para maiúsculas.

### Exemplos

Exemplo #1 Exemplo de mb_strtoupper()

    <?php
    $str = "Mary Had A Little Lamb and She LOVED It So";
    $str = mb_strtoupper($str);
    echo $str; // Imprime MARY HAD A LITTLE LAMB AND SHE LOVED IT SO
    ?>

Exemplo #2 Exemplo de mb_strtoupper() com texto UTF-8 não latino

    <?php
    $str = "Τάχιστη αλώπηξ βαφής ψημένη γη, δρασκελίζει υπέρ νωθρού κυνός";
    $str = mb_strtoupper($str, 'UTF-8');
    echo $str; // Imprime ΤΆΧΙΣΤΗ ΑΛΏΠΗΞ ΒΑΦΉΣ ΨΗΜΈΝΗ ΓΗ, ΔΡΑΣΚΕΛΊΖΕΙ ΥΠΈΡ ΝΩΘΡΟΎ ΚΥΝΌΣ
    ?>

### Notas

Ao contrário de strtoupper(), 'alfabético' é determinado pelas propriedades de caracteres Unicode. Assim, o comportamento desta função não é afetado pelas configurações de localidade e pode converter qualquer caractere que tenha a propriedade 'alfabético', como a-umlaut (ä).

Para obter mais informações sobre as propriedades Unicode, consulte » http://www.unicode.org/reports/tr21/.

### Veja Também

- mb_strtolower() - Torna uma string minúscula
- mb_convert_case() - Realiza a conversão de caixa em uma string
- strtoupper() - Converte uma string em maiúsculas

# mb_strwidth

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strwidth — Retorna a largura da string

### Descrição

function mb_strwidth(string `$string`, ?string `$encoding` = `null`): int

Retorna a largura da string `string`, onde os caracteres de meia largura contam como `1`, e os caracteres de largura total contam como `2`. Consulte » http://www.unicode.org/reports/tr11/ para detalhes sobre larguras de caracteres no leste asiático.

Os caracteres de largura total são: `U+1100`-`U+115F`, `U+11A3`-`U+11A7`, `U+11FA`-`U+11FF`, `U+2329`-`U+232A`, `U+2E80`-`U+2E99`, `U+2E9B`-`U+2EF3`, `U+2F00`-`U+2FD5`, `U+2FF0`-`U+2FFB`, `U+3000`-`U+303E`, `U+3041`-`U+3096`, `U+3099`-`U+30FF`, `U+3105`-`U+312D`, `U+3131`-`U+318E`, `U+3190`-`U+31BA`, `U+31C0`-`U+31E3`, `U+31F0`-`U+321E`, `U+3220`-`U+3247`, `U+3250`-`U+32FE`, `U+3300`-`U+4DBF`, `U+4E00`-`U+A48C`, `U+A490`-`U+A4C6`, `U+A960`-`U+A97C`, `U+AC00`-`U+D7A3`, `U+D7B0`-`U+D7C6`, `U+D7CB`-`U+D7FB`, `U+F900`-`U+FAFF`, `U+FE10`-`U+FE19`, `U+FE30`-`U+FE52`, `U+FE54`-`U+FE66`, `U+FE68`-`U+FE6B`, `U+FF01`-`U+FF60`, `U+FFE0`-`U+FFE6`, `U+1B000`-`U+1B001`, `U+1F200`-`U+1F202`, `U+1F210`-`U+1F23A`, `U+1F240`-`U+1F248`, `U+1F250`-`U+1F251`, `U+20000`-`U+2FFFD`, `U+30000`-`U+3FFFD`. Todos os outros caracteres são de meia largura.

### Parâmetros

`string`

  A string a ser decodificada.

`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.

### Valor Retornado

A largura da string `string`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `encoding` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo de mb_strwidth()

    <?php
    var_dump(
        mb_strwidth('a'),       // LATIN SMALL LETTER A
        mb_strwidth("\u{ff41}") // FULLWIDTH LATIN SMALL LETTER A
    );
    ?>

O exemplo acima produzirá:

    int(1)
    int(2)

### Veja Também

- mb_strimwidth() - Obtém string truncada com largura especificada
- mb_internal_encoding() - Define/Obtém a codificação de caracteres interna

# mb_substitute_character

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_substitute_character — Define/Obtém caractere de substituição

### Descrição

function mb_substitute_character(string|int|null `$substitute_character` = `null`): string|int|bool

Especifica um caractere de substituição quando a codificação de caracteres de entrada é inválida ou o código de caractere não existe na codificação de caracteres de saída. Caracteres inválidos podem ser substituídos por `"none"` (sem saída), string ou valor int (valor do código de caractere Unicode).

Essa configuração afeta as funções mb_convert_encoding(), mb_convert_variables(), mb_output_handler(), mb_scrub() e mb_send_mail().

### Parâmetros

`substitute_character`

  Especifique o valor Unicode como um int, ou como uma das seguintes strings:

  - `"none"`: sem saída
  - `"long"`: Valor do código de caractere de saída (Exemplo: `U+3000`, `JIS+7E7E`)
  - `"entity"`: Entidade de caractere de saída (Exemplo: `&#x200;`)

### Valor Retornado

Se `substitute_character` for configurado, retorna `true` para sucesso, caso contrário, retorna `false`. Se `substitute_character` não estiver configurado, retorna a configuração atual.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Passar uma string vazia para `substitute_character` não é mais suportado; deve-se passar `"none"` em vez disso.
8.0.0 | O parâmetro `encoding` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo de mb_substitute_character()

    <?php
    /* Definir com Unicode U+3013 (GETA MARK) */
    mb_substitute_character(0x3013);

    /* Definir no formato hexadecimal */
    mb_substitute_character("long");

    /* Exibir configuração atual */
    echo mb_substitute_character();
    ?>

# mb_substr

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_substr — Obtém parte da string

### Descrição

function mb_substr(
string `$string`,
int `$start`,
?int `$length` = `null`,
?string `$encoding` = `null`
): string

Realiza uma operação de substr() segura para múltiplos bytes baseada no número de caracteres. A posição é contada a partir do início de `string`. A posição do primeiro caractere é 0. A posição do segundo caractere é 1, e assim por diante.

### Parâmetros

`string`

  A string da qual extrair a substring.

`start`

  Se `start` for não negativo, a string retornada começará na posição `start`-ésima em `string`, contando a partir de zero. Por exemplo, na string '`abcdef`', o caractere na posição `0` é '`a`', o caractere na posição `2` é '`c`', e assim por diante.

  Se `start` for negativo, a string retornada começará no caractere `start`-ésimo a partir do final de `string`.

`length`

  Número máximo de caracteres a serem usados de `string`. Se omitido ou `NULL` for passado, extrai todos os caracteres até o final da string.

`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.

### Valor Retornado

mb_substr() retorna a porção de `string` especificada pelos parâmetros `start` e `length`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Em strings inválidas (aquelas com erros de codificação), os índices de caractere agora são interpretados da mesma maneira que a maioria das outras funções mbstring. Isso significa que os índices de caractere retornados por mb_strpos() podem ser passados diretamente.
8.0.0 | O parâmetro `encoding` agora pode ser nulo.

### Veja Também

- mb_strcut() - Obtém parte da string
- mb_internal_encoding() - Define/Obtém a codificação de caracteres interna

# mb_substr_count

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_substr_count — Conta o número de ocorrências de substring

### Descrição

function mb_substr_count(string `$haystack`, string `$needle`, ?string `$encoding` = `null`): int

Conta o número de vezes que a substring `needle` ocorre na `haystack` string.

### Parâmetros

`haystack`

  A string sendo verificada.

`needle`

  A string sendo procurada.

`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.

### Valor Retornado

O número de vezes que a substring `needle` ocorre na `haystack` string.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `encoding` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo de mb_substr_count()

    <?php
    echo mb_substr_count("This is a test", "is"); // Imprime 2
    ?>

### Veja Também

- mb_strpos() - Encontra a posição da primeira ocorrência de uma string em outra
- mb_substr() - Obtém parte da string
- substr_count() - Conta o número de ocorrências de uma substring

# mb_trim

(PHP 8 >= 8.4.0)

mb_trim — Remove espaços em branco (ou outros caracteres) do início e do final de uma string

### Descrição

function mb_trim(string `$string`, ?string `$characters` = `null`, ?string `$encoding` = `null`): string

Realiza uma operação trim() segura para strings multi-byte, e retorna uma string com os espaços em branco (ou outros caracteres) removidos do início e do final da `string`. Sem o segundo parâmetro, mb_trim() removerá estes caracteres:

- `" "` (Unicode U+0020), um espaço em branco normal.
- `"\t"` (Unicode U+0009), uma tabulação horizontal.
- `"\n"` (Unicode U+000A), uma nova linha (alimentação de linha).
- `"\r"` (Unicode U+000D), um retorno de carro.
- `"\0"` (Unicode U+0000), o byte NUL.
- `"\v"` (Unicode U+000B), uma tabulação vertical.
- `"\f"` (Unicode U+000C), uma alimentação de formulário.
- `"\u00A0"` (Unicode U+00A0), um espaço sem quebra de palavra (NO-BREAK SPACE).
- `"\u1680"` (Unicode U+1680), uma marca de espaço Ogham.
- `"\u2000"` (Unicode U+2000), um EN QUAD.
- `"\u2001"` (Unicode U+2001), um EM QUAD.
- `"\u2002"` (Unicode U+2002), um EN SPACE.
- `"\u2003"` (Unicode U+2003), um EM SPACE.
- `"\u2004"` (Unicode U+2004), um THREE-PER-EM SPACE.
- `"\u2005"` (Unicode U+2005), um FOUR-PER-EM SPACE.
- `"\u2006"` (Unicode U+2006), um SIX-PER-EM SPACE.
- `"\u2007"` (Unicode U+2007), um FIGURE SPACE.
- `"\u2008"` (Unicode U+2008), um PUNCTUATION SPACE.
- `"\u2009"` (Unicode U+2009), um THIN SPACE.
- `"\u200A"` (Unicode U+200A), um HAIR SPACE.
- `"\u2028"` (Unicode U+2028), um LINE SEPARATOR.
- `"\u2029"` (Unicode U+2029), um PARAGRAPH SEPARATOR.
- `"\u202F"` (Unicode U+202F), um NARROW NO-BREAK SPACE.
- `"\u205F"` (Unicode U+205F), um MEDIUM MATHEMATICAL SPACE.
- `"\u3000"` (Unicode U+3000), um IDEOGRAPHIC SPACE.
- `"\u0085"` (Unicode U+0085), um NEXT LINE (NEL).
- `"\u180E"` (Unicode U+180E), um MONGOLIAN VOWEL SEPARATOR.

### Parâmetros

`string`
  A string de entrada.
`characters`
  Opcionalmente, os caracteres a serem removidos também podem ser especificados usando o parâmetro `characters`. Simplesmente liste todos os caracteres que precisam ser removidos.
`encoding`
  O parâmetro `encoding` é a codificação de caracteres. Se for omitido ou `null`, o valor da codificação de caracteres interna será usado.

### Valor Retornado

Retorna a string resultante.

### Veja Também

- mb_ltrim() - Remove espaços em branco (ou outros caracteres) do início de uma string
- mb_rtrim() - Remove espaços em branco (ou outros caracteres) do final de uma string
- trim() - Retira espaços (ou outros caracteres) do início e do final de uma string

# mb_ucfirst

(PHP 8 >= 8.4.0)

mb_ucfirst — Converte para maiúscula o primeiro caractere de uma string

### Descrição

function mb_ucfirst(string `$string`, ?string `$encoding` = `null`): string

Realizad uma operação ucfirst() segura para strings multi-byte, e retorna uma string com o primeiro caractere do parâmetro `string` convertido para letra de título.

### Parâmetros

`string`
  A string de entrada.
`encoding`
  A codificação da string.

### Valor Retornado

Retorna a string resultante.

### Notas

> Nota:

> Em contraste com as funções padrão de conversão de maiúsculas e minúsculas, como strtolower() e strtoupper(), a conversão é executada com base nas propriedades dos caracteres Unicode. Assim, o comportamento desta função não é afetado pelas configurações de localidade e pode converter quaisquer caracteres que tenham propriedade 'alphabetic' (alfabética), como trema (ä) por exemplo.

Para obter mais informações sobre as propriedades Unicode, consulte » http://www.unicode.org/reports/tr21/.

### Veja Também

- mb_lcfirst() - Converte parap minúscula o primeiro caractere de uma string
- mb_convert_case() - Realiza a conversão de caixa em uma string
- ucfirst() - Transforma o primeiro caractere de uma string em maiúsculo

## Índice

- mb_check_encoding — Verifica se as strings são válidas para a codificação especificada
- mb_chr — Retorna um caractere pelo valor do ponto de código Unicode
- mb_convert_case — Realiza a conversão de caixa em uma string
- mb_convert_encoding — Converte uma string de uma codificação de caracteres para outra
- mb_convert_kana — Converte "kana" de um tipo para outro ("zen-kaku", "han-kaku" e mais)
- mb_convert_variables — Converte o código de caracteres em variável(is)
- mb_decode_mimeheader — Decodifica string no campo de cabeçalho MIME
- mb_decode_numericentity — Decodifica referência de string numérica HTML para caractere
- mb_detect_encoding — Detectar a codificação de caracteres
- mb_detect_order — Define ou obtém a ordem de detecção de codificação de caracteres
- mb_encode_mimeheader — Codificar string para cabeçalho MIME
- mb_encode_numericentity — Codificar caractere para referência numérica HTML
- mb_encoding_aliases — Obtém aliases de um tipo de codificação conhecido
- mb_ereg — Correspondência de expressão regular com suporte multibyte
- mb_ereg_match — Coincidência de expressão regular para string multibyte
- mb_ereg_replace — Substituir expressão regular com suporte a multibyte
- mb_ereg_replace_callback — Realiza uma busca e substituição de expressão regular com suporte a string multibyte usando um callback
- mb_ereg_search — Correspondência de expressão regular multibyte para uma string multibyte predefinida
- mb_ereg_search_getpos — Retorna o ponto de início para a próxima correspondência de expressão regular
- mb_ereg_search_getregs — Recupera o resultado da última correspondência de expressão regular multibyte
- mb_ereg_search_init — Configura a string e a expressão regular para uma correspondência de expressão regular multibyte
- mb_ereg_search_pos — Retorna a posição e o comprimento de uma parte correspondida da expressão regular multibyte para uma string multibyte predefinida
- mb_ereg_search_regs — Retorna a parte correspondida de uma expressão regular multibyte
- mb_ereg_search_setpos — Define o ponto de início para a próxima correspondência de expressão regular
- mb_eregi — Correspondência de expressão regular sem diferenciar maiúsculas e minúsculas com suporte multibyte
- mb_eregi_replace — Substituir expressão regular com suporte multibyte, ignorando maiúsculas e minúsculas
- mb_get_info — Obtém configurações internas do mbstring
- mb_http_input — Detecta a codificação de caracteres de entrada HTTP
- mb_http_output — Define/Obtém a codificação de caracteres de saída HTTP
- mb_internal_encoding — Define/Obtém a codificação de caracteres interna
- mb_language — Define/Obtém o idioma atual
- mb_lcfirst — Converte parap minúscula o primeiro caractere de uma string
- mb_list_encodings — Retorna um array de todas as codificações suportadas
- mb_ltrim — Remove espaços em branco (ou outros caracteres) do início de uma string
- mb_ord — Obtém o ponto de código Unicode do caractere
- mb_output_handler — Callback converte a codificação de caracteres no buffer de saída
- mb_parse_str — Analisa dados GET/POST/COOKIE e define variável global
- mb_preferred_mime_name — Obter uma string MIME charset
- mb_regex_encoding — Define/Obtém codificação de caracteres para regex multibyte
- mb_regex_set_options — Define/Obtém as opções padrão para funções mbregex
- mb_rtrim — Remove espaços em branco (ou outros caracteres) do final de uma string
- mb_scrub — Substitui sequências de bytes malformadas pelo caractere substituto
- mb_send_mail — Envia email codificado
- mb_split — Divide uma string multibyte usando expressão regular
- mb_str_pad — Preenche uma string multibyte para um comprimento específico com outra string multibyte
- mb_str_split — Dada uma string multibyte, retorna um array de seus caracteres
- mb_strcut — Obtém parte da string
- mb_strimwidth — Obtém string truncada com largura especificada
- mb_stripos — Encontra a posição da primeira ocorrência de uma string dentro de outra, sem diferenciar maiúsculas de minúsculas
- mb_stristr — Encontra a primeira ocorrência de uma string dentro de outra, sem diferenciar maiúsculas de minúsculas
- mb_strlen — Obtém o comprimento da string
- mb_strpos — Encontra a posição da primeira ocorrência de uma string em outra
- mb_strrchr — Encontra a última ocorrência de um caractere em uma string dentro de outra
- mb_strrichr — Encontra a última ocorrência de um caractere em uma string dentro de outra, sem diferenciar maiúsculas de minúsculas
- mb_strripos — Encontra a posição da última ocorrência de uma string em outra, sem diferenciar maiúsculas de minúsculas
- mb_strrpos — Encontra a posição da última ocorrência de uma string em outra string
- mb_strstr — Encontra a primeira ocorrência de uma string em outra
- mb_strtolower — Torna uma string minúscula
- mb_strtoupper — Faz uma string ficar em maiúsculas
- mb_strwidth — Retorna a largura da string
- mb_substitute_character — Define/Obtém caractere de substituição
- mb_substr — Obtém parte da string
- mb_substr_count — Conta o número de ocorrências de substring
- mb_trim — Remove espaços em branco (ou outros caracteres) do início e do final de uma string
- mb_ucfirst — Converte para maiúscula o primeiro caractere de uma string

- Instalação/Configuração
  - Instalação
  - Configurações em Execução
- Constantes predefinidas
- Sumários de Codificações Suportadas
- Noções Básicas de Codificações Multibyte Japonesas
- Entrada e Saída HTTP
- Codificações de Caracteres Suportadas
- Recurso de Sobrecarga de Funções
- Requisitos de Codificação de Caracteres em PHP
- Strings Multibyte e Funções
  - mb_check_encoding — Verifica se as strings são válidas para a codificação especificada
  - mb_chr — Retorna um caractere pelo valor do ponto de código Unicode
  - mb_convert_case — Realiza a conversão de caixa em uma string
  - mb_convert_encoding — Converte uma string de uma codificação de caracteres para outra
  - mb_convert_kana — Converte "kana" de um tipo para outro ("zen-kaku", "han-kaku" e mais)
  - mb_convert_variables — Converte o código de caracteres em variável(is)
  - mb_decode_mimeheader — Decodifica string no campo de cabeçalho MIME
  - mb_decode_numericentity — Decodifica referência de string numérica HTML para caractere
  - mb_detect_encoding — Detectar a codificação de caracteres
  - mb_detect_order — Define ou obtém a ordem de detecção de codificação de caracteres
  - mb_encode_mimeheader — Codificar string para cabeçalho MIME
  - mb_encode_numericentity — Codificar caractere para referência numérica HTML
  - mb_encoding_aliases — Obtém aliases de um tipo de codificação conhecido
  - mb_ereg — Correspondência de expressão regular com suporte multibyte
  - mb_ereg_match — Coincidência de expressão regular para string multibyte
  - mb_ereg_replace — Substituir expressão regular com suporte a multibyte
  - mb_ereg_replace_callback — Realiza uma busca e substituição de expressão regular com suporte a string multibyte usando um callback
  - mb_ereg_search — Correspondência de expressão regular multibyte para uma string multibyte predefinida
  - mb_ereg_search_getpos — Retorna o ponto de início para a próxima correspondência de expressão regular
  - mb_ereg_search_getregs — Recupera o resultado da última correspondência de expressão regular multibyte
  - mb_ereg_search_init — Configura a string e a expressão regular para uma correspondência de expressão regular multibyte
  - mb_ereg_search_pos — Retorna a posição e o comprimento de uma parte correspondida da expressão regular multibyte para uma string multibyte predefinida
  - mb_ereg_search_regs — Retorna a parte correspondida de uma expressão regular multibyte
  - mb_ereg_search_setpos — Define o ponto de início para a próxima correspondência de expressão regular
  - mb_eregi — Correspondência de expressão regular sem diferenciar maiúsculas e minúsculas com suporte multibyte
  - mb_eregi_replace — Substituir expressão regular com suporte multibyte, ignorando maiúsculas e minúsculas
  - mb_get_info — Obtém configurações internas do mbstring
  - mb_http_input — Detecta a codificação de caracteres de entrada HTTP
  - mb_http_output — Define/Obtém a codificação de caracteres de saída HTTP
  - mb_internal_encoding — Define/Obtém a codificação de caracteres interna
  - mb_language — Define/Obtém o idioma atual
  - mb_lcfirst — Converte parap minúscula o primeiro caractere de uma string
  - mb_list_encodings — Retorna um array de todas as codificações suportadas
  - mb_ltrim — Remove espaços em branco (ou outros caracteres) do início de uma string
  - mb_ord — Obtém o ponto de código Unicode do caractere
  - mb_output_handler — Callback converte a codificação de caracteres no buffer de saída
  - mb_parse_str — Analisa dados GET/POST/COOKIE e define variável global
  - mb_preferred_mime_name — Obter uma string MIME charset
  - mb_regex_encoding — Define/Obtém codificação de caracteres para regex multibyte
  - mb_regex_set_options — Define/Obtém as opções padrão para funções mbregex
  - mb_rtrim — Remove espaços em branco (ou outros caracteres) do final de uma string
  - mb_scrub — Substitui sequências de bytes malformadas pelo caractere substituto
  - mb_send_mail — Envia email codificado
  - mb_split — Divide uma string multibyte usando expressão regular
  - mb_str_pad — Preenche uma string multibyte para um comprimento específico com outra string multibyte
  - mb_str_split — Dada uma string multibyte, retorna um array de seus caracteres
  - mb_strcut — Obtém parte da string
  - mb_strimwidth — Obtém string truncada com largura especificada
  - mb_stripos — Encontra a posição da primeira ocorrência de uma string dentro de outra, sem diferenciar maiúsculas de minúsculas
  - mb_stristr — Encontra a primeira ocorrência de uma string dentro de outra, sem diferenciar maiúsculas de minúsculas
  - mb_strlen — Obtém o comprimento da string
  - mb_strpos — Encontra a posição da primeira ocorrência de uma string em outra
  - mb_strrchr — Encontra a última ocorrência de um caractere em uma string dentro de outra
  - mb_strrichr — Encontra a última ocorrência de um caractere em uma string dentro de outra, sem diferenciar maiúsculas de minúsculas
  - mb_strripos — Encontra a posição da última ocorrência de uma string em outra, sem diferenciar maiúsculas de minúsculas
  - mb_strrpos — Encontra a posição da última ocorrência de uma string em outra string
  - mb_strstr — Encontra a primeira ocorrência de uma string em outra
  - mb_strtolower — Torna uma string minúscula
  - mb_strtoupper — Faz uma string ficar em maiúsculas
  - mb_strwidth — Retorna a largura da string
  - mb_substitute_character — Define/Obtém caractere de substituição
  - mb_substr — Obtém parte da string
  - mb_substr_count — Conta o número de ocorrências de substring
  - mb_trim — Remove espaços em branco (ou outros caracteres) do início e do final de uma string
  - mb_ucfirst — Converte para maiúscula o primeiro caractere de uma string

# Pspell

# Introdução

Aviso

Esta extensão foi DESCONTINUADA e DESAGREGADA a partir do PHP 8.4.0.

Essas funções permitem verificar a ortografia de uma palavra e oferecer sugestões.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Tipos de Recurso

## Dependências

Para compilar PHP com suporte pspell, é necessária a biblioteca aspell, disponível em » http://aspell.net/.

## Instalação

## PHP 8.4

Esta extensão foi movida para o repositório » PECL e não é mais distribuída com o PHP desde a versão 8.4.0

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/pspell.

## PHP < 8.4

Para habilitar esta extensão, o PHP deve ser compilado com a opção --with-pspell[=dir].

> Nota: Nota para usuários Win32

> Para que esta extensão funcione, existem arquivos DLL que devem estar disponíveis no PATH do sistema Windows. Para saber como fazer isso, veja a FAQ intitulada "Como eu adiciono o meu diretório PHP ao PATH do Windows". Embora copiar arquivos DLL da pasta do PHP para o diretório system do Windows também funcione (porque o diretório system está, por padrão, no PATH do sistema), isso não é recomendado. Esta extensão requer que os seguintes arquivos estejam no PATH: aspell-15.dll da pasta bin da instalação do aspell.

> O suporte Win32 requer pelo menos a versão 0.50 do aspell.

## Tipos de Recurso

Antes do PHP 8.1.0, havia dois tipos de recursos usados nesta extensão. O primeiro é o identificador de conexão do dicionário, o segundo é um recurso que contém a configuração do pspell.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`PSPELL_FAST` (int)
`PSPELL_NORMAL` (int)
`PSPELL_BAD_SPELLERS` (int)
`PSPELL_RUN_TOGETHER` (int)

# Funções de Pspell

# pspell_add_to_personal

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_add_to_personal — Adiciona a palavra a uma lista de palavras pessoal

### Descrição

function pspell_add_to_personal(PSpell\Dictionary `$dictionary`, string `$word`): bool

pspell_add_to_personal() adiciona uma palavra à lista de palavras pessoal. Se foi usada pspell_new_config() com pspell_config_personal() para abrir o dicionário, pode-se salvar a lista de palavras posteriormente com pspell_save_wordlist().

### Parâmetros

`dictionary`
  Uma instância de PSpell\Dictionary.
`word`

  A palavra adicionada.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `dictionary` agora espera uma instância de PSpell\Dictionary; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 pspell_add_to_personal()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    $pspell = pspell_new_config($pspell_config);

    pspell_add_to_personal($pspell, "Vlad");
    pspell_save_wordlist($pspell);
    ?>

### Notas

> Nota:

> Esta função não funcionará a menos que se tenha o pspell .11.2 e o aspell .32.5 ou posterior.

# pspell_add_to_session

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_add_to_session — Adiciona a palavra à lista de palavras na sessão atual

### Descrição

function pspell_add_to_session(PSpell\Dictionary `$dictionary`, string `$word`): bool

pspell_add_to_session() adiciona uma palavra à lista de palavras associada à sessão atual. É muito semelhante a pspell_add_to_personal().

### Parâmetros

`dictionary`
  Uma instância de PSpell\Dictionary.
`word`

  A palavra adicionada.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `dictionary` agora espera uma instância de PSpell\Dictionary; anteriormente, um resource era esperado.

# pspell_check

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_check — Verifica uma palavra

### Descrição

function pspell_check(PSpell\Dictionary `$dictionary`, string `$word`): bool

pspell_check() verifica a ortografia de uma palavra.

### Parâmetros

`dictionary`
  Uma instância de PSpell\Dictionary.
`word`

  A palavra testada.

### Valor Retornado

Retorna `true` se a grafia estiver correta, `false` caso contrário.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `dictionary` agora espera uma instância de PSpell\Dictionary; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pspell_check()

    <?php
    $pspell = pspell_new("en");

    if (pspell_check($pspell, "testt")) {
        echo "Esta é uma grafia válida";
    } else {
        echo "Desculpe, ortografia errada";
    }
    ?>

# pspell_clear_session

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_clear_session — Limpa a sessão atual

### Descrição

function pspell_clear_session(PSpell\Dictionary `$dictionary`): bool

pspell_clear_session() limpa a sessão atual. A lista de palavras atual fica em branco e, por exemplo, se for usada a função pspell_save_wordlist() para salvá-la, nada acontece.

### Parâmetros

`dictionary`
  Uma instância de PSpell\Dictionary.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `dictionary` agora espera uma instância de PSpell\Dictionary; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pspell_add_to_personal()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    $pspell = pspell_new_config($pspell_config);

    pspell_add_to_personal($pspell, "Vlad");
    pspell_clear_session($pspell);
    pspell_save_wordlist($pspell);    // "Vlad" não será salva
    ?>

# pspell_config_create

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_create — Cria uma configuração usada para abrir um dicionário

### Descrição

function pspell_config_create(
string `$language`,
string `$spelling` = "",
string `$jargon` = "",
string `$encoding` = ""
): PSpell\Config

Cria uma configuração usada para abrir um dicionário.

pspell_config_create() tem uma sintaxe muito semelhante a pspell_new(). De fato, usar pspell_config_create() imediatamente seguido por pspell_new_config() produzirá exatamente o mesmo resultado. No entanto, após criar uma nova configuração, também podem ser usadas as funções pspell_config_*() antes de chamar pspell_new_config() para aproveitar algumas funcionalidades avançadas.

Para mais informações e exemplos, confira o manual no site do pspell:» http://aspell.net/.

### Parâmetros

`language`

  O parâmetro language é o código do idioma, que consiste no código de idioma ISO 639 de duas letras e um código de país ISO 3166 opcional de duas letras após um hífen ou sublinhado.

`spelling`

  O parâmetro spelling é a ortografia solicitada para idiomas com mais de uma grafia, como o inglês. Os valores conhecidos são 'american', 'british' e 'canadian'.

`jargon`

  O parâmetro jargon contém informações extras para distinguir duas listas de palavras diferentes que possuem os mesmos parâmetros de idioma e ortografia.

`encoding`

  O parâmetro encoding é a codificação em que se espera que as palavras estejam. Os valores válidos são 'utf-8', 'iso8859-*', 'koi8-r', 'viscii', 'cp1252', 'machine unsigned 16', 'machine unsigned 32'. Este parâmetro ainda não foi testado, portanto, tenha cuidado ao usá-lo.

### Valor Retornado

Retorna uma instância de PSpell\Config.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Retorna uma instância de PSpell\Config agora; anteriormente, um resource era retornado.

### Exemplos

Exemplo #1 pspell_config_create()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    pspell_config_repl($pspell_config, "/var/dictionaries/custom.repl");
    $pspell = pspell_new_personal($pspell_config, "en");
    ?>

# pspell_config_data_dir

(PHP 5, PHP 7, PHP 8)

pspell_config_data_dir — Localização dos arquivos de dados de idioma

### Descrição

function pspell_config_data_dir(PSpell\Config `$config`, string `$directory`): bool

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `config` agora espera uma instância de PSpell\Config; anteriormente, um resource era esperado.

# pspell_config_dict_dir

(PHP 5, PHP 7, PHP 8)

pspell_config_dict_dir — Localização da lista principal de palavras

### Descrição

function pspell_config_dict_dir(PSpell\Config `$config`, string `$directory`): bool

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `config` agora espera uma instância de PSpell\Config; anteriormente, um resource era esperado.

# pspell_config_ignore

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_ignore — Ignora palavras com menos de N caracteres

### Descrição

function pspell_config_ignore(PSpell\Config `$config`, int `$min_length`): bool

pspell_config_ignore() deve ser usada em uma configuração antes de chamar pspell_new_config(). Esta função permite que palavras curtas sejam ignoradas pelo corretor ortográfico.

### Parâmetros

`config`
  Uma instância de PSpell\Config.
`min_length`

  Palavras com menos de `min_length` caracteres serão ignoradas.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `config` agora espera uma instância de PSpell\Config; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 pspell_config_ignore()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_ignore($pspell_config, 5);
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "abcd");    // não resultará em erro
    ?>

# pspell_config_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_mode — Altera o número do modo de sugestões retornadas

### Descrição

function pspell_config_mode(PSpell\Config `$config`, int `$mode`): bool

pspell_config_mode() deve ser usada em uma configuração antes de chamar pspell_new_config(). Esta função determina quantas sugestões serão retornadas por pspell_suggest().

### Parâmetros

`config`
  Uma instância de PSpell\Config.
`mode`

  O parâmetro mode define o modo em que o corretor ortográfico funcionará. Há vários modos disponíveis:

  - `PSPELL_FAST` - Modo rápido (menor número de sugestões)
  - `PSPELL_NORMAL` - Modo normal (mais sugestões)
  - `PSPELL_BAD_SPELLERS` - Modo lento (muitas sugestões)

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `config` agora espera uma instância de PSpell\Config; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pspell_config_mode()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_mode($pspell_config, PSPELL_FAST);
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "thecat");
    ?>

# pspell_config_personal

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_personal — Define um arquivo que contém uma lista de palavras pessoais

### Descrição

function pspell_config_personal(PSpell\Config `$config`, string `$filename`): bool

Define um arquivo que contém uma lista de palavras pessoal. A lista de palavras pessoal será carregada e usada além da lista padrão após pspell_new_config() ser chamada. O arquivo também é o arquivo onde pspell_save_wordlist() salvará a lista de palavras pessoal.

pspell_config_personal() deve ser usada em uma configuração antes de chamar pspell_new_config().

### Parâmetros

`config`
  Uma instância de PSpell\Config.
`filename`

  A lista de palavras pessoal. Se o arquivo não existir, ele será criado. O arquivo deve ter acesso de escrita para o usuário com o qual o PHP está sendo executado (por exemplo, nobody).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `config` agora espera uma instância de PSpell\Config; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 pspell_config_personal()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "thecat");
    ?>

### Notas

> Nota:

> Esta função não funcionará a menos que se tenha o pspell .11.2 e o aspell .32.5 ou posterior.

# pspell_config_repl

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_repl — Define um arquivo que contém pares de substituição

### Descrição

function pspell_config_repl(PSpell\Config `$config`, string `$filename`): bool

Define um arquivo que contém pares de substituição.

Os pares de substituição melhoram a qualidade do corretor ortográfico. Quando uma palavra está escrita incorretamente e uma sugestão adequada não foi encontrada na lista, pspell_store_replacement() pode ser usada para armazenar um par de substituição e, em seguida, pspell_save_wordlist() para salvar a lista de palavras junto com os pares de substituição.

pspell_config_repl() deve ser usado em uma configuração antes de chamar pspell_new_config().

### Parâmetros

`config`
  Uma instância de PSpell\Config.
`filename`

  O arquivo deve ter acesso de escrita para o usuário com o qual o PHP está sendo executado (por exemplo, nobody).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `config` agora espera uma instância de PSpell\Config; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 pspell_config_repl()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    pspell_config_repl($pspell_config, "/var/dictionaries/custom.repl");
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "thecat");
    ?>

### Notas

> Nota:

> Esta função não funcionará a menos que se tenha o pspell .11.2 e o aspell .32.5 ou posterior.

# pspell_config_runtogether

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_runtogether — Considera palavras que se juntam como compostos válidos

### Descrição

function pspell_config_runtogether(PSpell\Config `$config`, bool `$allow`): bool

Esta função determina se palavras juntas serão tratadas como palavras compostas válidas. Ou seja, "thecat" em inglês será uma palavra composta válida, embora deva haver um espaço entre as duas palavras. Alterar esta configuração afeta apenas os resultados retornados por pspell_check(); pspell_suggest() ainda retornará sugestões.

pspell_config_runtogether() deve ser usada em uma configuração antes de chamar pspell_new_config().

### Parâmetros

`config`
  Uma instância de PSpell\Config.
`allow`

  `true` se palavras unidas devem ser tratadas como compostos legais, `false` caso contrário.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `config` agora espera uma instância de PSpell\Config; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 pspell_config_runtogether()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_runtogether($pspell_config, true);
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "thecat");
    ?>

# pspell_config_save_repl

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_save_repl — Determina se uma lista de pares de substituição deve ser salva junto com a lista de palavras

### Descrição

function pspell_config_save_repl(PSpell\Config `$config`, bool `$save`): bool

pspell_config_save_repl() determina se pspell_save_wordlist() salvará os pares de substituição junto com a lista de palavras. Normalmente, não há necessidade de usar esta função porque se pspell_config_repl() for usada, os pares de substituição serão salvos por pspell_save_wordlist() de qualquer maneira, e se não for usada, os pares de substituição não serão salvos.

pspell_config_save_repl() deve ser usado em uma configuração antes de chamar pspell_new_config().

### Parâmetros

`config`
  Uma instância de PSpell\Config.
`save`

  `true` se os pares de substituição devem ser salvos, `false` caso contrário.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `config` agora espera uma instância de PSpell\Config; anteriormente, um resource era esperado.

### Notas

> Nota:

> Esta função não funcionará a menos que se tenha o pspell .11.2 e o aspell .32.5 ou posterior.

# pspell_new

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_new — Carrega um novo dicionário

### Descrição

function pspell_new(
string `$language`,
string `$spelling` = "",
string `$jargon` = "",
string `$encoding` = "",
int `$mode` = 0
): PSpell\Dictionary|false

pspell_new() abre um novo dicionário e retorna uma instância de PSpell\Dictionary para uso em outras funções pspell.

Para mais informações e exemplos, confira o manual no site do pspell:» http://aspell.net/.

### Parâmetros

`language`

  O parâmetro language é o código do idioma, que consiste no código de idioma ISO 639 de duas letras e um código de país ISO 3166 opcional de duas letras após um hífen ou sublinhado.

`spelling`

  O parâmetro spelling é a ortografia solicitada para idiomas com mais de uma ortografia, como o inglês. Os valores conhecidos são 'american', 'british' e 'canadian'.

`jargon`

  O parâmetro jargon contém informações extras para distinguir duas listas de palavras diferentes que possuem os mesmos parâmetros de idioma e ortografia.

`encoding`

  O parâmetro de codificação é a codificação em que se espera que as palavras estejam. Os valores válidos são 'utf-8', 'iso8859-*', 'koi8-r', 'viscii', 'cp1252', 'machine unsigned 16', 'machine unsigned 32'. Este parâmetro ainda não foi testado, portanto, tenha cuidado ao usá-lo.

`mode`

  O parâmetro mode define o modo em que o corretor ortográfico funcionará. Há vários modos disponíveis:

  - `PSPELL_FAST` - Modo rápido (menor número de sugestões)
  - `PSPELL_NORMAL` - Modo normal (mais sugestões)
  - `PSPELL_BAD_SPELLERS` - Modo lento (muitas sugestões)
  - `PSPELL_RUN_TOGETHER` - Considera palavras que se juntam como palavras compostas legais. Ou seja, "thecat" será uma palavra composta legal em inglês, embora deva haver um espaço entre as duas palavras. Alterar esta configuração afeta apenas os resultados retornados por pspell_check(); pspell_suggest() ainda retornará sugestões.
  Mode é uma máscara de bits construída a partir das diferentes constantes listadas acima. No entanto, `PSPELL_FAST`, `PSPELL_NORMAL` e `PSPELL_BAD_SPELLERS` são mutuamente exclusivas, portanto, deve-se selecionar apenas uma delas.

### Valor Retornado

Retorna uma instância de PSpell\Dictionary em caso de sucesso, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Agora, retorna uma instância de PSpell\Dictionary; anteriormente, um resource era retornado.

### Exemplos

Exemplo #1 pspell_new()

    <?php
    $pspell = pspell_new("en", "", "", "",
                         (PSPELL_FAST|PSPELL_RUN_TOGETHER));
    ?>

# pspell_new_config

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_new_config — Carrega um novo dicionário com configurações baseadas em uma configuração fornecida

### Descrição

function pspell_new_config(PSpell\Config `$config`): PSpell\Dictionary|false

pspell_new_config() abre um novo dicionário com configurações especificadas em um `config`, criado com pspell_config_create() e modificado com funções pspell_config_*(). Este método oferece a maior flexibilidade e possui todas as funcionalidades fornecidas por pspell_new() e pspell_new_personal().

### Parâmetros

`config`

  O parâmetro `config` é aquele retornado por pspell_config_create() quando a configuração foi criada.

### Valor Retornado

Retorna uma instância de PSpell\Dictionary em caso de sucesso, ou `false` em caso de falha

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `config` agora espera uma instância de PSpell\Config; anteriormente, um resource era esperado.
8.1.0 | Agora, retorna uma instância de PSpell\Dictionary; anteriormente, um resource era retornado.

### Exemplos

Exemplo #1 pspell_new_config()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    pspell_config_repl($pspell_config, "/var/dictionaries/custom.repl");
    $pspell = pspell_new_config($pspell_config);
    ?>

# pspell_new_personal

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_new_personal — Carrega um novo dicionário com lista de palavras pessoal

### Descrição

function pspell_new_personal(
string `$filename`,
string `$language`,
string `$spelling` = "",
string `$jargon` = "",
string `$encoding` = "",
int `$mode` = 0
): PSpell\Dictionary|false

pspell_new_personal() abre um novo dicionário com uma lista de palavras pessoal. A lista de palavras pode ser modificada e salva com pspell_save_wordlist(), se desejado. No entanto, os pares de substituição não são salvos. Para salvar os pares de substituição, deve-se criar uma configuração usando pspell_config_create(), definir o arquivo da lista de palavras pessoal com pspell_config_personal(), definir o arquivo para pares de substituição com pspell_config_repl() e abrir um novo dicionário com pspell_new_config().

Para mais informações e exemplos, confira o manual do site do pspell:» http://aspell.net/.

### Parâmetros

`filename`

  O arquivo onde as palavras adicionadas à lista pessoal serão armazenadas. Deve ser um nome de arquivo absoluto começando com '/', pois, caso contrário, será relativo a $HOME, que é "/root" para a maioria dos sistemas, e provavelmente não é o que se deseja.

`language`

  O código de idioma consiste no código de idioma ISO 639 de duas letras e um código de país ISO 3166 opcional de duas letras após um hífen ou sublinhado.

`spelling`

  A grafia solicitada para idiomas com mais de uma grafia, como o inglês. Os valores conhecidos são 'american', 'british' e 'canadian'.

`jargon`

  Informações extras para distinguir duas listas de palavras diferentes que têm os mesmos parâmetros de idioma e ortografia.

`encoding`

  A codificação em que se espera que as palavras estejam. Os valores válidos são `utf-8`, `iso8859-*`, `koi8-r`, `viscii`, `cp1252`, `machine unsigned 16`, `machine unsigned 32`.

`mode`

  O modo como o corretor ortográfico funcionará. Há vários modos disponíveis:

  - `PSPELL_FAST` - Modo rápido (menor número de sugestões)
  - `PSPELL_NORMAL` - Modo normal (mais sugestões)
  - `PSPELL_BAD_SPELLERS` - Modo lento (muitas sugestões)
  - `PSPELL_RUN_TOGETHER` - Considera palavras que se juntam como palavras compostas legais. Ou seja, "thecat" será uma palavra composta legal em inglês, embora deva haver um espaço entre as duas palavras. Alterar esta configuração afeta apenas os resultados retornados por pspell_check(); pspell_suggest() ainda retornará sugestões.
  Mode é uma máscara de bits construída a partir das diferentes constantes listadas acima. No entanto, `PSPELL_FAST`, `PSPELL_NORMAL` e `PSPELL_BAD_SPELLERS` são mutuamente exclusivas, portanto, deve-se selecionar apenas uma delas.

### Valor Retornado

Retorna uma instância de PSpell\Dictionary em caso de sucesso, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Agora, retorna uma instância de PSpell\Dictionary; anteriormente, um resource era retornado.

### Exemplos

Exemplo #1 pspell_new_personal()

    <?php
    $pspell = pspell_new_personal ("/var/dictionaries/custom.pws",
            "en", "", "", "", PSPELL_FAST|PSPELL_RUN_TOGETHER);
    ?>

# pspell_save_wordlist

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_save_wordlist — Salva a lista de palavras pessoal em um arquivo

### Descrição

function pspell_save_wordlist(PSpell\Dictionary `$dictionary`): bool

pspell_save_wordlist() salva a lista de palavras pessoal da sessão atual. O local dos arquivos a serem salvos é especificado com pspell_config_personal() e (opcionalmente) pspell_config_repl().

### Parâmetros

`dictionary`
  Uma instância de PSpell\Dictionary.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `dictionary` agora espera uma instância de PSpell\Dictionary; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 pspell_add_to_personal()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/tmp/dicts/newdict");
    $pspell = pspell_new_config($pspell_config);

    pspell_add_to_personal($pspell, "Vlad");
    pspell_save_wordlist($pspell);
    ?>

### Notas

> Nota:

> Esta função não funcionará a menos que se tenha o pspell .11.2 e o aspell .32.5 ou posterior.

# pspell_store_replacement

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_store_replacement — Armazena um par de substituição para uma palavra

### Descrição

function pspell_store_replacement(PSpell\Dictionary `$dictionary`, string `$misspelled`, string `$correct`): bool

pspell_store_replacement() armazena um par de substituição para uma palavra, para que a substituição possa ser retornada por pspell_suggest() posteriormente. Para poder aproveitar esta função, é necessário usar pspell_new_personal() para abrir o dicionário. Para salvar permanentemente o par de substituição, deve-se usar pspell_config_personal() e pspell_config_repl() para definir o caminho onde salvar as listas de palavras personalizadas e, em seguida, usar pspell_save_wordlist() para que as alterações sejam gravadas no disco.

### Parâmetros

`dictionary`
  Uma instância de PSpell\Dictionary.
`misspelled`

  A palavra escrita incorretamente.

`correct`

  A grafia corrigida para a palavra `misspelled`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `dictionary` agora espera uma instância de PSpell\Dictionary; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 pspell_store_replacement()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    pspell_config_repl($pspell_config, "/var/dictionaries/custom.repl");
    $pspell = pspell_new_config($pspell_config);

    pspell_store_replacement($pspell, $misspelled, $correct);
    pspell_save_wordlist($pspell);
    ?>

### Notas

> Nota:

> Esta função não funcionará a menos que se tenha o pspell .11.2 e o aspell .32.5 ou posterior.

# pspell_suggest

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_suggest — Sugere grafias de uma palavra

### Descrição

function pspell_suggest(PSpell\Dictionary `$dictionary`, string `$word`): array|false

pspell_suggest() retorna um array de possíveis grafias para a palavra fornecida.

### Parâmetros

`dictionary`
  Uma instância de PSpell\Dictionary.
`word`

  A palavra testada.

### Valor Retornado

Retorna um array de grafias possíveis.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `dictionary` agora espera uma instância de PSpell\Dictionary; anteriormente, um resource era esperado.

### Exemplos

Exemplo #1 Exemplo de pspell_suggest()

    <?php
    $pspell = pspell_new("en");

    if (!pspell_check($pspell, "testt")) {
        $suggestions = pspell_suggest($pspell, "testt");

        foreach ($suggestions as $suggestion) {
            echo "Possível ortografia: $suggestion<br />";
        }
    }
    ?>

## Índice

- pspell_add_to_personal — Adiciona a palavra a uma lista de palavras pessoal
- pspell_add_to_session — Adiciona a palavra à lista de palavras na sessão atual
- pspell_check — Verifica uma palavra
- pspell_clear_session — Limpa a sessão atual
- pspell_config_create — Cria uma configuração usada para abrir um dicionário
- pspell_config_data_dir — Localização dos arquivos de dados de idioma
- pspell_config_dict_dir — Localização da lista principal de palavras
- pspell_config_ignore — Ignora palavras com menos de N caracteres
- pspell_config_mode — Altera o número do modo de sugestões retornadas
- pspell_config_personal — Define um arquivo que contém uma lista de palavras pessoais
- pspell_config_repl — Define um arquivo que contém pares de substituição
- pspell_config_runtogether — Considera palavras que se juntam como compostos válidos
- pspell_config_save_repl — Determina se uma lista de pares de substituição deve ser salva junto com a lista de palavras
- pspell_new — Carrega um novo dicionário
- pspell_new_config — Carrega um novo dicionário com configurações baseadas em uma configuração fornecida
- pspell_new_personal — Carrega um novo dicionário com lista de palavras pessoal
- pspell_save_wordlist — Salva a lista de palavras pessoal em um arquivo
- pspell_store_replacement — Armazena um par de substituição para uma palavra
- pspell_suggest — Sugere grafias de uma palavra

# A classe PSpell\Dictionary

(PHP 8 >= 8.1.0)

## Introdução

Uma classe totalmente opaca que substitui um recurso `pspell` a partir do PHP 8.1.0.

## Resumo da classe

final class PSpell\Dictionary {
}

# A classe PSpell\Config

(PHP 8 >= 8.1.0)

## Introdução

Uma classe totalmente opaca que substitui um recurso `pspell config` do PHP 8.1.0.

## Resumo da classe

final class PSpell\Config {
}

- Instalação/Configuração
  - Dependências
  - Instalação
  - Tipos de Recurso
- Constantes predefinidas
- Funções de Pspell
  - pspell_add_to_personal — Adiciona a palavra a uma lista de palavras pessoal
  - pspell_add_to_session — Adiciona a palavra à lista de palavras na sessão atual
  - pspell_check — Verifica uma palavra
  - pspell_clear_session — Limpa a sessão atual
  - pspell_config_create — Cria uma configuração usada para abrir um dicionário
  - pspell_config_data_dir — Localização dos arquivos de dados de idioma
  - pspell_config_dict_dir — Localização da lista principal de palavras
  - pspell_config_ignore — Ignora palavras com menos de N caracteres
  - pspell_config_mode — Altera o número do modo de sugestões retornadas
  - pspell_config_personal — Define um arquivo que contém uma lista de palavras pessoais
  - pspell_config_repl — Define um arquivo que contém pares de substituição
  - pspell_config_runtogether — Considera palavras que se juntam como compostos válidos
  - pspell_config_save_repl — Determina se uma lista de pares de substituição deve ser salva junto com a lista de palavras
  - pspell_new — Carrega um novo dicionário
  - pspell_new_config — Carrega um novo dicionário com configurações baseadas em uma configuração fornecida
  - pspell_new_personal — Carrega um novo dicionário com lista de palavras pessoal
  - pspell_save_wordlist — Salva a lista de palavras pessoal em um arquivo
  - pspell_store_replacement — Armazena um par de substituição para uma palavra
  - pspell_suggest — Sugere grafias de uma palavra
- PSpell\Dictionary — A classe PSpell\Dictionary
- PSpell\Config — A classe PSpell\Config

# Recodificação GNU

# Introdução

Aviso

Esta extensão está sem manutenção.

Este módulo contém uma interface para a biblioteca GNU Recode. A biblioteca GNU Recode converte arquivos entre vários conjuntos de caracteres codificados e codificações de superfície. Quando isso não pode ser alcançado com exatidão, pode eliminar os caracteres ofensivos ou recorrer a aproximações. A biblioteca reconhece ou produz cerca de 150 conjuntos de caracteres diferentes e é capaz de converter arquivos entre praticamente qualquer par. A maioria dos conjuntos de caracteres » RFC 1345 são suportados.

> Nota: Esta extensão foi desagregada e movida para » PECL a partir do PHP 7.4.0. Considere usar as extensões Multibyte String ou iconv no lugar.

> Nota: Esta extensão não está disponível em plataformas Windows.

# Instalação/Configuração

## Índice

- Dependências
- Instalação

## Dependências

Você deve ter o GNU Recode 3.5 ou superior instalado em seu sistema. Você pode baixar o pacote em » http://directory.fsf.org/All_GNU_Packages/recode.html.

Aviso

A biblioteca Recode versão 3.6 adiciona caracteres estranhos atrás de strings convertidas sob certas circunstâncias. Portanto, é mais seguro usar o Recode v3.5 ou uma das alternativas disponíveis como a extensão iconv ou mbstring.

## Instalação

## PHP 7.4

Esta extensão foi movida para o repositório » PECL e não é mais distribuída com o PHP desde a versão 7.4.0

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/recode.

## PHP < 7.4

Para poder utilizar as funções definidas neste módulo você deve compilar seu interpretador PHP utilizando a opção --with-recode[=DIR].

Aviso

Falhas e problemas de inicialização do PHP podem ser encontrados ao carregar o recode como extensão após carregar qualquer extensão de mysql ou imap. Carregar o recode antes dessas extensões provou resolver o problema. Isto se deve a um problema técnico de que tanto a biblioteca c-client usada pelo imap quanto pelo recode possuem sua própria função `hash_lookup()` e tanto o mysql quanto o recode possuem sua própria função `hash_insert`.

Aviso

As extensões IMAP, recode e YAZ não podem ser usadas em conjunto, pois compartilham os mesmos símbolos internos. Observação: a Yaz 2.0 e superiores não sofrem deste problema.

# Funções de Recode

# recode

(PHP 4, PHP 5, PHP 7 < 7.4.0)

recode — Sinônimo de recode_string()

### Descrição

Esta função é um apelido para: recode_string().

# recode_file

(PHP 4, PHP 5, PHP 7 < 7.4.0)

recode_file — Recodifica de arquivo para arquivo de acordo com a solicitação de recodificação

### Descrição

function recode_file(string `$request`, resource `$input`, resource `$output`): bool

Recodifica o arquivo referenciado pelo identificador `input` no arquivo referenciado pelo identificador `output` de acordo com a requisição de recodificação `request`.

### Parâmetros

`request`
  O tipo de solicitação de recodificação desejada
`input`
  `input` deve ser um identificador de arquivo local do tipo resource para a entrada
`output`
  `output` deve ser um identificador de arquivo local do tipo resource para a saída

### Valor Retornado

Retorna `false` se não for possível cumprir, `true` caso contrário.

### Exemplos

Exemplo #1 Exemplo básico de recode_file()

    <?php
    $input = fopen('input.txt', 'r');
    $output = fopen('output.txt', 'w');
    recode_file("us..flat", $input, $output);
    ?>

### Notas

Esta função atualmente não processa identificadores de arquivo que fazem referência a arquivos remotos (URLs). Ambos os identificadores de arquivo devem referir-se a arquivos locais.

### Veja Também

- fopen() - Abre um arquivo ou URL

# recode_string

(PHP 4, PHP 5, PHP 7 < 7.4.0)

recode_string — Recodifica uma string de acordo com uma solicitação de recodificação

### Descrição

function recode_string(string `$request`, string `$string`): string

Recodifica a string `string` de acordo com a solicitação de recodificação `request`.

### Parâmetros

`request`
  O tipo de solicitação de recodificação desejada
`string`
  A string a ser recodificada

### Valor Retornado

Retorna a string recodificada ou `false` se não for possível executar a solicitação de recodificação.

### Exemplos

Exemplo #1 Exemplo básico de recode_string()

    <?php
    echo recode_string("us..flat", "O caractere a seguir tem uma marca diacrítica: á");
    ?>

### Notas

Uma solicitação de recodificação simples pode ser "lat1..iso646-de".

### Veja Também

- A documentação do GNU Recode para instruções detalhadas sobre solicitações de recodificação.
- mb_convert_encoding() - Converte uma string de uma codificação de caracteres para outra
- UConverter::transcode() - Converte uma string de uma codificação de caracteres para outra
- iconv() - Converte uma string de uma codificação de caracteres para outra

## Índice

- recode — Sinônimo de recode_string
- recode_file — Recodifica de arquivo para arquivo de acordo com a solicitação de recodificação
- recode_string — Recodifica uma string de acordo com uma solicitação de recodificação

- Instalação/Configuração
  - Dependências
  - Instalação
- Funções de Recode
  - recode — Sinônimo de recode_string
  - recode_file — Recodifica de arquivo para arquivo de acordo com a solicitação de recodificação
  - recode_string — Recodifica uma string de acordo com uma solicitação de recodificação

- Enchant — Enchant - Biblioteca de verificação ortográfica
  - Instalação/Configuração
  - Constantes predefinidas
  - Exemplos
  - Funções de Enchant
  - EnchantBroker — A classe EnchantBroker
  - EnchantDictionary — A classe EnchantDictionary
- Gender — Determina o gênero dos primeiros nomes
  - Instalação/Configuração
  - Exemplos
  - Gender\Gender — A classe Gender\Gender
- Gettext
  - Instalação/Configuração
  - Funções da Gettext
- iconv
  - Instalação/Configuração
  - Constantes predefinidas
  - iconv Funções
- intl — Funções de Internacionalização
  - Instalação/Configuração
  - Constantes predefinidas
  - Exemplos
  - Collator — A classe Collator
  - NumberFormatter — A classe NumberFormatter
  - Locale — A classe Locale
  - Normalizer — A classe Normalizer
  - MessageFormatter — A classe MessageFormatter
  - IntlCalendar — A classe IntlCalendar
  - IntlGregorianCalendar — A classe IntlGregorianCalendar
  - IntlTimeZone — A classe IntlTimeZone
  - IntlDateFormatter — A classe IntlDateFormatter
  - ResourceBundle — A classe ResourceBundle
  - Spoofchecker — A classe Spoofchecker
  - Transliterator — A classe Transliterator
  - IntlBreakIterator — A classe IntlBreakIterator
  - IntlRuleBasedBreakIterator — A classe IntlRuleBasedBreakIterator
  - IntlCodePointBreakIterator — A classe IntlCodePointBreakIterator
  - IntlDatePatternGenerator — A classe IntlDatePatternGenerator
  - IntlPartsIterator — A classe IntlPartsIterator
  - UConverter — A classe UConverter
  - Funções de Grapheme
  - Funções de IDN
  - IntlChar
  - IntlException — Classe de exceção para erros da extensão Intl
  - IntlIterator — A classe IntlIterator
  - Funções de Intl
- String Multibyte
  - Instalação/Configuração
  - Constantes predefinidas
  - Sumários de Codificações Suportadas
  - Noções Básicas de Codificações Multibyte Japonesas
  - Entrada e Saída HTTP
  - Codificações de Caracteres Suportadas
  - Recurso de Sobrecarga de Funções
  - Requisitos de Codificação de Caracteres em PHP
  - Strings Multibyte e Funções
- Pspell
  - Instalação/Configuração
  - Constantes predefinidas
  - Funções de Pspell
  - PSpell\Dictionary — A classe PSpell\Dictionary
  - PSpell\Config — A classe PSpell\Config
- Recode — Recodificação GNU
  - Instalação/Configuração
  - Funções de Recode

# Processamento e Geração de Imagem

# Informações de imagem

# Introdução

Com a extensão exif pode-se trabalhar com metadados de imagem. Por exemplo, pode-se usar funções exif para ler metadados de fotografias obtidas de câmeras digitais com informações armazenadas no cabeçalho do aqruivo. Estas informações são usualmente encontradas em imagens JPEG e TIFF.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução

## Dependências

O PHP precisa ser compilado com `--enable-exif`. Para habilitar suporte a caracteres multi-byte em etiquetas EXIF, a extensão mbstring precisa estar habilitada, compilando o PHP com `--enable-mbstring`. O PHP não requer bilbioteca adicional para o módulo exif.

## Instalação

Para habilitar suporte a exif configure o PHP com --enable-exif

Usuários Windows precisam habilitar as DLLs php_mbstring.dll e php_exif.dll no php.ini. A DLL php_mbstring.dll precisa ser carregada antes da php_exif.dll então ajuste seu php.ini corretamente.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Exif suporta conversão automática para codificações de caracteres Unicode e JIS de comentários de usuários quando o módulo mbstring está disponível. Isto é feito primeiro decodificando-se o comentário usando o conjunto de caracteres especificado. o resultado é então codificado com outro conjunto de caracteres que deve corresponder à saída `HTTP`.

Opções de configuração de Exif
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
exif.encode_unicode | "ISO-8859-15" | `INI_ALL` |
exif.decode_unicode_motorola | "UCS-2BE" | `INI_ALL` |
exif.decode_unicode_intel | "UCS-2LE" | `INI_ALL` |
exif.encode_jis | "" | `INI_ALL` |
exif.decode_jis_motorola | "JIS" | `INI_ALL` |
exif.decode_jis_intel | "JIS" | `INI_ALL` |

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`exif.encode_unicode` string
  `exif.encode_unicode` define o conjunto de caracteres UNICODE para lidar com os comentários de usuário. O padrão é ISO-8859-15 que deve funcionar para a maioria dos países não asiáticos. A configuração pode ser vazia ou deve ser uma codificação suportada por mbstring. Se for vazia,a codificação interna atual de mbstring é usada.
`exif.decode_unicode_motorola` string
  `exif.decode_unicode_motorola` define o conjunto de caracteres internos da imagem para os comentários de usuário codificados em Unicode se a imagem está na ordem de bytes Motorola (Big Endian). Esta configuração não pode ser vazia mas pode-se especificar uma lista de codificações suportadas por. O padrão é UCS-2BE.
`exif.decode_unicode_intel` string
  `exif.decode_unicode_intel` define o conjunto de caracteres internos da imagem para os comentários de usuário se a imagem está na ordem de bytes Intel (Little Endian). Esta configuração não pode ser vazia mas pode-se especificar uma lista de codificações suportadas por. O padrão é UCS-2LE.
`exif.encode_jis` string
  `exif.encode_jis` define o conjunto de caracteres JIS com o qual os comentários são lidos. O padrão é um valor vazio que força as funções a usarem a codificação interna atual de mbstring.
`exif.decode_jis_motorola` string
  `exif.decode_jis_motorola` define o conjunto de caracteres internos da imagem para comentários codificados com JIS se a imagem está na ordem de bytes Motorola (Big Endian). Esta configuração não pode ser vazia mas pode-se especificar uma lista de codificações suportadas por. O padrão é JIS.
`exif.decode_jis_intel` string
  `exif.decode_jis_intel` define o conjunto de caracteres internos da imagem para comentários codificados com JIS se a imagem está na ordem de bytes Intel (Little Endian). Esta configuração não pode ser vazia mas pode-se especificar uma lista de codificações suportadas por. O padrão é JIS.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`EXIF_USE_MBSTRING` (int)
  Esta constante tem o valor igual a `1` se mbstring estiver habilidado, caso contrário tem o valor igual a `0`.

A função exif_imagetype() lista várias constantes internas relacionadas.

# Funções de Exif

# exif_imagetype

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

exif_imagetype — Verifica o tipo de uma imagem

### Descrição

function exif_imagetype(string `$filename`): int|false

exif_imagetype() lê os primeiros bytes de uma imagem e verifica sua assinatura.

exif_imagetype() pode ser usada para evitar chamadas a outras funções exif que não têm suporte a certos tipos de arquivos ou um conjunção com $_SERVER['HTTP_ACCEPT'] para verificar se o visualizador é capaz de mostrar uma imagem específica no navegador.

### Parâmetros

`filename`
  A imagem a ser verificada.

### Valor Retornado

Quando uma assinatura correta é encontrada, o valor da constante associada será retornado, caso contrário o valor de retorno será `false`. O valor retornado é o mesmo valor que getimagesize() retorna no índice 2, mas exif_imagetype() é bem mais rápida.

As seguintes constantes estão definidas, e representam os possíveis valores de retorno de exif_imagetype():

Constantes Imagetype
Valor | Constante
--- | ---
1 | `IMAGETYPE_GIF`
2 | `IMAGETYPE_JPEG`
3 | `IMAGETYPE_PNG`
4 | `IMAGETYPE_SWF`
5 | `IMAGETYPE_PSD`
6 | `IMAGETYPE_BMP`
7 | `IMAGETYPE_TIFF_II` (ordem de bytes Intel)
8 | `IMAGETYPE_TIFF_MM` (ordem de bytes Motorola)
9 | `IMAGETYPE_JPC`
10 | `IMAGETYPE_JP2`
11 | `IMAGETYPE_JPX`
12 | `IMAGETYPE_JB2`
13 | `IMAGETYPE_SWC`
14 | `IMAGETYPE_IFF`
15 | `IMAGETYPE_WBMP`
16 | `IMAGETYPE_XBM`
17 | `IMAGETYPE_ICO`
18 | `IMAGETYPE_WEBP`
19 | `IMAGETYPE_AVIF`
20 | `IMAGETYPE_HEIF`

> Nota: exif_imagetype() emitirá um erro de nível `E_NOTICE` e retornará `false` se for incapaz de ler bytes suficientes do arquivo para determinar o tipo da imagem.

### Registro de Alterações

Versão | Descrição
--- | ---
7.1.0 | Adicionado suporte a WebP.
8.1.0 | Adicionado suporte a AVIF.
8.5.0 | Adicionado suporte a HEIF.

### Exemplos

Exemplo #1 Exemplo de exif_imagetype()

    <?php
    if (exif_imagetype('image.gif') != IMAGETYPE_GIF) {
        echo 'A imagem não é do tipo gif';
    }
    ?>

### Veja Também

- image_type_to_mime_type() - Obtém o Mime-Type para o tipo de imagem retornado por getimagesize, exif_read_data, exif_thumbnail e exif_imagetype
- getimagesize() - Obtém o tamanho de uma imagem

# exif_read_data

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

exif_read_data — Lê os cabeçalhos EXIF de um arquivo de imagen

### Descrição

function exif_read_data(
resource|string `$file`,
?string `$required_sections` = `null`,
bool `$as_arrays` = `false`,
bool `$read_thumbnail` = `false`
): array|false

A função exif_read_data() lê os cabeçalhos EXIF de um arquivo de imagem. Desta forma é possível ler metadados gerados por câmeras digitais.

Cabeçalhos EXIF tendem a estar presentes em imagens JPEG/TIFF geradas por camêras digitais, mas infelizmente, cada fabricante de camêra digital tem uma ideia diferente de como rotular suas imagens, então não se pode confiar sempre que um cabeçalho EXIF específico estará presente.

Altura (`Height`) e largura (`Width`) sao computadas da mesma maneira que getimagesize() faz, então seus valores não devem ser parte de nenhum cabeçalho retornado. Além disso, `html` é uma string de texto com altura/largura a ser usado dentro de umHTML normal.

Quando um cabeçalho Exif contém uma nota de direitos autorais, esta nota pode conter dois valores. Como a solução é inconsistente com o padrão Exif 2.10 a seção `COMPUTED` irá retornar ambas as entradas `Copyright.Photographer` e `Copyright.Editor` enquanto que as seções `IFD0` contém um array de bytes com o caractere NULL que separa as duas entradas. Ou apenas a primeira entrada se o tipo de dados estiver errado (funcionamento normal do Exif). `COMPUTED` irá conter também a entrada `Copyright` que será a string original do copyright ou uma lista separada por vírgula dos direitos autorais da foto e do editor.

A etiqueta `UserComment` tem o mesmo problema que a etiqueta de Copyright. Ela pode guardar dois valores. Primeiro a codificação usada e em segundo o valor em si. Então a seção `IFD` contém somente a codificação ou um array de bytes. A seção `COMPUTED` irá guardar ambos nas entradas `UserCommentEncoding` e `UserComment`. A entrada `UserComment` está disponível em ambos os casos então deve ser usada em preferência ao valor da seção `IFD0`.

exif_read_data() também valida etiquetas de dados EXIF de acordo com a especificação EXIF (» http://exif.org/Exif2-2.PDF, página 20).

### Parâmetros

`file`
  A localização do arquivo de imagem. Pode ser uma caminho para o arquivo (empacotadores de fluxo são também suportados) ou um fluxo do tipo resource.
`required_sections`

  Uma lista de seções separadas por vírgula que precisam estar presentes no arquivo para produzir o resultado do tipo array. Se nenhuma das seções informadas puder ser encontrada o valor de retorno é `false`.

  FILE | FileName, FileSize, FileDateTime, SectionsFound
  COMPUTED | html, Width, Height, IsColor, e mais se disponíveis. Height e Width são computadas da mesma maneira que getimagesize() faz, portanto seus valores não deve ser parte de nenhum cabeçalho retornado. Além disso, `html` é uma string de texto com altura/largura a ser usado dentro de um HTML normal.
  ANY_TAG | Qualquer informação que tenha uma etiqueta, ex.: `IFD0`, `EXIF`, ...
  IFD0 | Todos os dados etiquetados de IFD0. Em arquivos de imagem normais, contém o tamanho da imagem e outros dados.
  THUMBNAIL | Um arquivo deveria ter uma miniatura se tiver um segundo `IFD`. Todas as informações etiquetadas sobre a miniatura embutida estão gravadas nesta seção.
  COMMENT | Cabeçalho de comentários de imagens JPEG.
  EXIF | A seção EXIF é uma sub-seção de `IFD0`. Contém informação mais detalhada sobre uma imagem. A maior parte destas entradas são relacionadas a câmeras digitais.

`as_arrays`
  Especifica se cada seção se torna ou não um array. As seções `COMPUTED`, `THUMBNAIL` E `COMMENT` de `required_sections` sempre se toranm arrays por que contêm valores cujos nomes conflitam com outras seções.
`read_thumbnail`
  Quando definida para `true` a miniatura em si é lida. Caso contrário, apenas os dados etiquetados são lidos.

### Valor Retornado

Retorna um array associativo onde os índices são os nomes dos cabeçalhos e os valores são os associados com esses cabeçalhos. Se nenhum dado puder ser retornado, exif_read_data() retornará `false`.

### Erros/Exceções

Erros de nível `E_WARNING` e/ou `E_NOTICE` podem ser disparados para etiquetas não suportadas ou outras condições de erros potenciais, mas a função ainda tenta lêr toda a informação compreensível.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `required_sections` agora pode ser nulo.
7.2.0 | O parâmetro `file` agora suporta tanto arquivos locais quanto recursos de fluxo.
7.2.0 | Adicionado suporte aos seguintes formatos EXIF: Samsung DJI Panasonic Sony Pentax Minolta Sigma/Foveon AGFA Kyocera Ricoh Epson

### Exemplos

Exemplo #1 Exemplo exif_read_data()

    <?php
    echo "test1.jpg:<br />\n";
    $exif = exif_read_data('tests/test1.jpg', 'IFD0');
    echo $exif===false ? "Dados de cabeçalho não encontrados.<br />\n" : "Imagem contém cabeçalhos<br />";

    $exif = exif_read_data('tests/test2.jpg', 0, true);
    echo "test2.jpg:<br />\n";
    foreach ($exif as $key => $section) {
        foreach ($section as $name => $val) {
            echo "$key.$name: $val<br />\n";
        }
    }
    ?>

A primeira chamada falha porque a imagem não tem informações no cabeçalho.

O exemplo acima produzirá algo semelhante a:

    test1.jpg:
    Dados de cabeçalho não encontrados.
    test2.jpg:
    FILE.FileName: test2.jpg
    FILE.FileDateTime: 1017666176
    FILE.FileSize: 1240
    FILE.FileType: 2
    FILE.SectionsFound: ANY_TAG, IFD0, THUMBNAIL, COMMENT
    COMPUTED.html: width="1" height="1"
    COMPUTED.Height: 1
    COMPUTED.Width: 1
    COMPUTED.IsColor: 1
    COMPUTED.ByteOrderMotorola: 1
    COMPUTED.UserComment: Exif test image.
    COMPUTED.UserCommentEncoding: ASCII
    COMPUTED.Copyright: Photo (c) M.Boerger, Edited by M.Boerger.
    COMPUTED.Copyright.Photographer: Photo (c) M.Boerger
    COMPUTED.Copyright.Editor: Edited by M.Boerger.
    IFD0.Copyright: Photo (c) M.Boerger
    IFD0.UserComment: ASCII
    THUMBNAIL.JPEGInterchangeFormat: 134
    THUMBNAIL.JPEGInterchangeFormatLength: 523
    COMMENT.0: Comment #1.
    COMMENT.1: Comment #2.
    COMMENT.2: Comment #3end
    THUMBNAIL.JPEGInterchangeFormat: 134
    THUMBNAIL.Thumbnail.Height: 1
    THUMBNAIL.Thumbnail.Height: 1

Exemplo #2 exif_read_data() com fluxos, disponível a partir do PHP 7.2.0

    <?php
    // Abre o arquivo, deve ser em modo binário
    $fp = fopen('/path/to/image.jpg', 'rb');

    if (!$fp) {
        echo 'Erro: Não foi possível abrir a imagem para leitura';
        exit;
    }

    // Tenta ler o cabeçalhos exif
    $headers = exif_read_data($fp);

    if (!$headers) {
        echo 'Erro: Não foi possível ler os cabeçalhos exif';
        exit;
    }

    // Mostra os cabeçalhos de 'COMPUTED'
    echo 'Cabeçalhos EXIF:' . PHP_EOL;

    foreach ($headers['COMPUTED'] as $header => $value) {
        printf(' %s => %s%s', $header, $value, PHP_EOL);
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    Cabeçalhos EXIF:
     Height => 576
     Width => 1024
     IsColor => 1
     ByteOrderMotorola => 0
     ApertureFNumber => f/5.6
     UserComment =>
     UserCommentEncoding => UNDEFINED
     Copyright => Denis
     Thumbnail.FileType => 2
     Thumbnail.MimeType => image/jpeg

### Notas

> Nota: Se mbstring estiver habilitado, exif tentará processar em codificação unicode e escolher um conjunto de caracteres como especificado por exif.decode_unicode_motorola e exif.decode_unicode_intel. A extensão exif não tentará descobrir a codificação por si mesma, é responsabilidade do programador especificar corretamente a codificação a ser usada, configurando uma das duas diretivas ini antes de chamar exif_read_data().

> Nota: Se `file` for usado para passar um fluxo a esta função, o fluxo deve ser do tipo pesquisável. Note que a posição do ponteiro do arquivo não é alterada depois que esta função retorna.

### Veja Também

- exif_thumbnail() - Recupera a miniatura embutida de uma imagem
- getimagesize() - Obtém o tamanho de uma imagem
- Protocolos e empacotadores suportados

# exif_tagname

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

exif_tagname — Obtém o nome do cabeçalho para um índice

### Descrição

function exif_tagname(int `$index`): string|false

### Parâmetros

`index`
  O ID da etiqueta para o qual o nome do cabeçalho será pesquisado

### Valor Retornado

Retorna o nome do cabeçalho, ou `false` se `index` não for um id de etiqueta EXIF definido.

### Exemplos

Exemplo #1 Exemplo de exif_tagname()

    <?php
    echo "256: ".exif_tagname(256).PHP_EOL;
    echo "257: ".exif_tagname(257).PHP_EOL;
    ?>

O exemplo acima produzirá:

    256: ImageWidth
    257: ImageLength

### Veja Também

- exif_imagetype() - Verifica o tipo de uma imagem
- » Especificação EXIF
- » Etiquetas EXIF

# exif_thumbnail

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

exif_thumbnail — Recupera a miniatura embutida de uma imagem

### Descrição

function exif_thumbnail(
resource|string `$file`,
int `&$width` = `null`,
int `&$height` = `null`,
int `&$image_type` = `null`
): string|false

exif_thumbnail() lê a miniatura embutida de uma imagem.

Se for desejado exibir miniaturas através desta função, deve-se enviar a informação do tipo de mídia usando a função header().

É possível que exif_thumbnail() não possa criar uma imagem mas possa determinar seu tamanho. Neste caso, o valor retornado é `false` mas a largura (`width`) e altura (`height`) serão definidos.

### Parâmetros

`file`
  A localização do arquivo de imagem. Pode ser um caminho ou um fluxo do tipo resource.
`width`
  A largura da miniatura retornada.
`height`
  A altura da miniatura retornada.
`image_type`
  O tipo da imagem da miniatura retornada. Pode ser TIFF ou JPEG.

### Valor Retornado

Retorna a miniatura embutida, ou `false` se a imagem não contiver miniatura.

### Registro de Alterações

Versão | Descrição
--- | ---
7.2.0 | O parâmetro `file` agora suporta arquivos locais e recursos de fluxo.

### Exemplos

Exemplo #1 Exemplo de exif_thumbnail()

    <?php
    $image = exif_thumbnail('/path/to/image.jpg', $width, $height, $type);

    if ($image!==false) {
        header('Content-type: ' .image_type_to_mime_type($type));
        echo $image;
        exit;
    } else {
        // sem miniatura, gerencia o erro aqui
        echo 'Não há miniatura disponível';
    }
    ?>

### Notas

> Nota: Se o parâmetro `file` for usado para passar um fluxo a esta função, ele deve ser do tipo pesquisável. Note que a posição do ponteiro do arquivo não é alterada após o retorno desta função.

### Veja Também

- exif_read_data() - Lê os cabeçalhos EXIF de um arquivo de imagen
- image_type_to_mime_type() - Obtém o Mime-Type para o tipo de imagem retornado por getimagesize, exif_read_data, exif_thumbnail e exif_imagetype

# read_exif_data

(PHP 4 >= 4.0.1, PHP 5, PHP 7)

read_exif_data — Sinônimo de exif_read_data()

Aviso

Este apelido foi DESCONTINUADO a partir do PHP 7.2.0 e foi REMOVIDO a partir do PHP 8.0.0.

### Descrição

Esta função é um apelido para: exif_read_data().

### Registro de Alterações

Versão | Descrição
--- | ---
7.2.0 | O apelido desta função foi descontinuado.

## Índice

- exif_imagetype — Verifica o tipo de uma imagem
- exif_read_data — Lê os cabeçalhos EXIF de um arquivo de imagen
- exif_tagname — Obtém o nome do cabeçalho para um índice
- exif_thumbnail — Recupera a miniatura embutida de uma imagem
- read_exif_data — Sinônimo de exif_read_data

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
- Constantes predefinidas
- Funções de Exif
  - exif_imagetype — Verifica o tipo de uma imagem
  - exif_read_data — Lê os cabeçalhos EXIF de um arquivo de imagen
  - exif_tagname — Obtém o nome do cabeçalho para um índice
  - exif_thumbnail — Recupera a miniatura embutida de uma imagem
  - read_exif_data — Sinônimo de exif_read_data

# Processamento de Imagem e GD

# Introdução

O PHP não está limitado a criar apenas saída em HTML. Ele também pode ser usado para criar e manipular arquivos de imagem em uma diversidade de formatos, incluindo GIF, PNG, JPEG, WBMP, e XPM. E ainda mais convenientemente, o PHP pode enviar fluxos de imagem diretamente para o navegador. É necessário compilar o PHP com a biblioteca GD de funções de imagens para que isto funcione. GD e o PHP podem também requerer outras bibliotecas, dependendo de quais formatos de imagens serão trabalhados.

Pode-se usar as funções de imagem no PHP para obter o tamanho de imagens JPEG, GIF, PNG, SWF, TIFF e JPEG2000.

Com a extensão exif, pode-se trabalhar com informações armazenadas nos cabeçalhos de imagens JPEG e TIFF. Desta forma, pode-se ler metadados gerados por câmeras digitais. As funções exif não requerem a biblioteca GD.

> Nota: Leia a seção de requerimentos sobre como expandir a capacidade de leitura, escrita e modificação de imagens. Para ler metadados de fotografias tiradas de uma câmera digital, é necessária a extensão exif mencionada acima.

> Nota: A função getimagesize() não requqer a extensão GD.

Cuidado

Enquanto que a versão da biblioteca GD fornecida com o PHP usa o gerenciador de memória Zend para alocar memória, as versões de sistema não o fazem, de forma que memory_limit não se aplica.

GD suporta uma diversidade de formatos. Veja abaixo uma lista de formatos suportados por GD e notas sobre suas disponibilidades incluindo suporte a leitura/escrita.

Formatos suportados por GD
Formato | Suporte a leitura | Suporte a escrita | Notas
--- | --- | --- | ---
JPEG | `true` | `true` |
PNG | `true` | `true` |
GIF | `true` | `true` |
XBM | `true` | `true` |
XPM | `true` | `false` |
WBMP | `true` | `true` |
WebP | `true` | `true` |
BMP | `true` | `true` | Disponível a partir do PHP 7.2.0

Embora a maioria dos formatos esteja disponível para leitura e escrita na tabela acima, isto não significa que o PHP foi compilado com suporte a eles. Para descobrir quais formatos estavam disponíveis para o GD durante a compilação, use a função gd_info(). Para mais informação sobre compilação de suporte a um ou mais formantos, consulte o capítulo sobre instalação.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução
- Tipos de Recurso

## Dependências

Se a biblioteca GD estiver presente (disponível em » http://www.libgd.org/) será possível criar e manipular imagens.

Os formatos de imagens possíveis de ser manipulados dependem da versão da GD instalada, e de quaisquer outras bibliotecas GD possivelmente necessárias para acessar esses formatos.

> Nota: libgd-2.1.0 ou superior é requerida. Alternativamente, pode-se usar a biblioteca GD fornecida com o PHP.

> Nota: A biblioteca GD requer a zlib >= 1.2.0.4.

Pode ser desejado melhorar a GD para lidar com mais formatos de imagens.

Formatos de imagem suportados
Formato de imagem | Biblioteca a ser instalada | Notas
--- | --- | ---
`gif` |  |
`avif` |  |
`jpeg` | » http://www.ijg.org/ | Ao compilar a biblioteca jpeg (antes de compilar o PHP) deve-se usar a opção --enable-shared no passo de configuração. Senão, ocorrerá um erro dizendo `libjpeg.(a|so) not found` (biblioteca não encontrada) quando chegar o passo de configuração na compilação do PHP.
`png` | » http://www.libpng.org/pub/png/libpng.html |
`xpm` | » http://www.ibiblio.org/pub/Linux/libs/X/!INDEX.html | Em ambientes Unix, muito provavelmente a biblioteca já deve estar disponível, se o sistema tiver um ambiente X instalado.
`webp` |  |

Pode-se melhorar a GD para lidar com fontes diferentes. A biblioteca » FreeType 2 é suportada.

## Instalação

Para ativar suporte ao GD, configure o PHP com --with-gd[=DIR], aonde DIR é o diretório de instalação. Para usar a versão recomendada da biblioteca GD que acompanha o PHP, use a opção de configuração --with-gd. Biblioteca GD requer libpng e libjpeg para compilar. Desde o PHP 7.4.0, --with-gd se torna --enable-gd (para simplesmente abilitar a extensão) e --with-external-gd (para selecionar uma instalação libgd externa, diferente da que acompanha o PHP).

No Windows, você irá incluir a DLL do GD php_gd.dll como uma extensão no php.ini. Antes do PHP 8.0.0 a DLL se chamava php_gd2.dll.

Melhore as capacidades do GD para manipular mais formatos de imagens especificando a opção `--with-XXXX` na sua linha de configuração do PHP.

Formatos de imagens suportados
Formato de Imagem | Opção de Configuração
--- | ---
`avif` | Para habilitar suporte a avif aicione --with-avif. Disponível a partir do PHP 8.1.0.
`jpeg` | Para ativar suporte a jpeg adicione --with-jpeg-dir=DIR. Jpeg 6b, 7 ou 8 são suportados. A partir do PHP 7.4.0, use a opção --with-jpeg.
`png` | Para ativar suporte para png adicione --with-png-dir=DIR. Note que, libpng precisa de zlib library, portanto adicione a opção --with-zlib-dir[=DIR] na sua linha de configuração. A partir do PHP 7.4.0, --with-png-dir e --with-zlib-dir foram removidas. libpng e zlib são necessárias.
`xpm` | Para ativar suporte a xpm adicione --with-xpm-dir=DIR. Se o configure não for capaz de encontrar as bibliotecas necessárias, você deverá adicionar o caminho até as suas bibliotecas X11. A partir do PHP 7.4.0, use a opção --with-xpm.
`webp` | Para habilitar suporte a webp, adicione --with-webp-dir=DIR. A partir do PHP 7.4.0, use a opção --with-webp.

> Nota: Ao compilar o PHP com a libpng, você deve usar a mesma versão que foi ligada com a biblioteca GD.

Melhore as capacidades do GD para lidar com fontes diferentes especificando a opção de configuração `--with-XXXX` na linha de configuração do PHP.

Bibliotecas de Fontes Suportadas
Biblioteca de Fonte | Opção de Configuração
--- | ---
`FreeType 2` | Para ativar suporte a FreeType 2 adicione --with-freetype-dir=DIR. A partir do PHP 7.4.0, use --with-freetype, que usa pkg-config.
`Native TrueType string function` | Para ativar suporte a native TrueType string function adicione --enable-gd-native-ttf. (Essa opção não tem efeito e foi removida no PHP 7.2.0).

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de Configuração de Image
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
gd.jpeg_ignore_warning | "1" | `INI_ALL` |

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`gd.jpeg_ignore_warning` bool

  Ignora os avisos (mas não os erros) criado por libjpeg(-turbo).

Registro de alterações para `gd.jpeg_ignore_warning`
Versão | Descrição
--- | ---
7.1.0 | O padrão de gd.jpeg_ignore_warning foi alterado de 0 para 1.

Veja também as diretivas de configuração exif.

Aviso

As funções para imagem usam bastante memória. Certifique-se de definir memory_limit grande o bastante, se você estiver usando a versão fornecida da biblioteca GD.

## Tipos de Recurso

Esta extensão define os seguintes tipos de recursos:

Lista de tipos de recursos na GD
Nome | Descrição | Notas
--- | --- | ---
`gd` | Recurso de imagem, usado por funções como imagecreatefrompng() | Antes do PHP 8.0.0
`gd font` | Recurso de fonte criado internamente por imageloadfont() | Antes do PHP 8.1.0

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`GD_VERSION` (string)
  A versão da biblioteca GD que foi compilada com o PHP.
`GD_MAJOR_VERSION` (int)
  A maior versão da biblioteca GD compilada com o PHP.
`GD_MINOR_VERSION` (int)
  A menor versão da biblioteca GD compilada com o PHP.
`GD_RELEASE_VERSION` (int)
  A versão release da biblioteca GD compilada com o PHP.
`GD_EXTRA_VERSION` (string)
  A versão "extra" da biblioteca GD (beta/rc..) compilada com o PHP.
`GD_BUNDLED` (int)
  1 quando for uma versão incorporada do GD e 0 nos demais casos.
`IMG_AVIF` (int)
  Usada como valor retornado por imagetypes(). (Disponível a partir do PHP 8.1.0.)
`IMG_BMP` (int)
  Usada como valor retornado por imagetypes().
`IMG_GIF` (int)
  Usada como valor retornado por imagetypes().
`IMG_JPG` (int)
  Usada como valor retornado por imagetypes().
`IMG_JPEG` (int)
  Usada como valor retornado por imagetypes().

  > Nota:

  > Esta constante tem o mesmo valor que `IMG_JPG`

`IMG_PNG` (int)
  Usada como valor retornado por imagetypes().
`IMG_TGA` (int)
  Usada como valor retornado por imagetypes(). (Disponível a partir do PHP 7.4.0)
`IMG_WBMP` (int)
  Usada como valor retornado por imagetypes().
`IMG_XPM` (int)
  Usada como valor retornado por imagetypes().
`IMG_WEBP` (int)
  Usada como valor retornado por imagetypes(). (Disponível a partir do PHP 7.0.10.)
`IMG_WEBP_LOSSLESS` (int)
  (Disponível a partir do PHP 8.1.0.)
`IMG_COLOR_TILED` (int)
  Opção de cor especial que pode ser usada em vez de uma cor alocada com imagecolorallocate() ou imagecolorallocatealpha().
`IMG_COLOR_STYLED` (int)
  Opção de cor especial que pode ser usada em vez de uma cor alocada com imagecolorallocate() ou imagecolorallocatealpha().
`IMG_COLOR_BRUSHED` (int)
  Opção de cor especial que pode ser usada em vez de uma cor alocada com imagecolorallocate() ou imagecolorallocatealpha().
`IMG_COLOR_STYLEDBRUSHED` (int)
  Opção de cor especial que pode ser usada em vez de uma cor alocada com imagecolorallocate() ou imagecolorallocatealpha().
`IMG_COLOR_TRANSPARENT` (int)
  Opção de cor especial que pode ser usada em vez de uma cor alocada com imagecolorallocate() ou imagecolorallocatealpha().
`IMG_AFFINE_TRANSLATE` (int)
  Uma constante de tipo de transformação afim usada pela função imageaffinematrixget().
`IMG_AFFINE_SCALE` (int)
  Uma constante de tipo de transformação afim usada pela função imageaffinematrixget().
`IMG_AFFINE_ROTATE` (int)
  Uma constante de tipo de transformação afim usada pela função imageaffinematrixget().
`IMG_AFFINE_SHEAR_HORIZONTAL` (int)
  Uma constante de tipo de transformação afim usada pela função imageaffinematrixget().
`IMG_AFFINE_SHEAR_VERTICAL` (int)
  Uma constante de tipo de transformação afim usada pela função imageaffinematrixget().
`IMG_ARC_ROUNDED` (int)
  Uma constante de estilo usada pela função imagefilledarc().

  > Nota:

  > Esta constante tem o mesmo valor de `IMG_ARC_PIE`

`IMG_ARC_PIE` (int)
  Uma constante de estilo usada pela função imagefilledarc().
`IMG_ARC_CHORD` (int)
  Uma constante de estilo usada pela função imagefilledarc().
`IMG_ARC_NOFILL` (int)
  Uma constante de estilo usada pela função imagefilledarc().
`IMG_ARC_EDGED` (int)
  Uma constante de estilo usada pela função imagefilledarc().
`IMG_GD2_RAW` (int)
  Uma constante de tipo usada pela função imagegd2().
`IMG_GD2_COMPRESSED` (int)
  Uma constante de tipo usada pela função imagegd2().
`IMG_EFFECT_REPLACE` (int)
  Efeito de mesclagem alfa usado pela função imagelayereffect().
`IMG_EFFECT_ALPHABLEND` (int)
  Efeito de mesclagem alfa usado pela função imagelayereffect().
`IMG_EFFECT_NORMAL` (int)
  Efeito de mesclagem alfa usado pela função imagelayereffect().
`IMG_EFFECT_OVERLAY` (int)
  Efeito de mesclagem alfa usado pela função imagelayereffect().
`IMG_EFFECT_MULTIPLY` (int)
  Efeito de mesclagem alfa usado pela função imagelayereffect().
`IMG_FILTER_NEGATE` (int)
  Filtro GD especial usado pela função imagefilter().
`IMG_FILTER_GRAYSCALE` (int)
  Filtro GD especial usado pela função imagefilter().
`IMG_FILTER_BRIGHTNESS` (int)
  Filtro GD especial usado pela função imagefilter().
`IMG_FILTER_CONTRAST` (int)
  Filtro GD especial usado pela função imagefilter().
`IMG_FILTER_COLORIZE` (int)
  Filtro GD especial usado pela função imagefilter().
`IMG_FILTER_EDGEDETECT` (int)
  Filtro GD especial usado pela função imagefilter().
`IMG_FILTER_GAUSSIAN_BLUR` (int)
  Filtro GD especial usado pela função imagefilter().
`IMG_FILTER_SELECTIVE_BLUR` (int)
  Filtro GD especial usado pela função imagefilter().
`IMG_FILTER_EMBOSS` (int)
  Filtro GD especial usado pela função imagefilter().
`IMG_FILTER_MEAN_REMOVAL` (int)
  Filtro GD especial usado pela função imagefilter().
`IMG_FILTER_SMOOTH` (int)
  Filtro GD especial usado pela função imagefilter().
`IMG_FILTER_PIXELATE` (int)
  Filtro GD especial usado pela função imagefilter().
`IMG_FILTER_SCATTER` (int)
  Filtro GD especial usado pela função imagefilter(). (Disponível a partir do PHP 7.4.0)
`IMAGETYPE_GIF` (int)
  Constante do tipo de imagem usada pelas funções image_type_to_mime_type() e image_type_to_extension().
`IMAGETYPE_JPEG` (int)
  Constante do tipo de imagem usada pelas funções image_type_to_mime_type() e image_type_to_extension().
`IMAGETYPE_JPEG2000` (int)
  Constante do tipo de imagem usada pelas funções image_type_to_mime_type() e image_type_to_extension().
`IMAGETYPE_PNG` (int)
  Constante do tipo de imagem usada pelas funções image_type_to_mime_type() e image_type_to_extension().
`IMAGETYPE_SWF` (int)
  Constante do tipo de imagem usada pelas funções image_type_to_mime_type() e image_type_to_extension().
`IMAGETYPE_PSD` (int)
  Constante do tipo de imagem usada pelas funções image_type_to_mime_type() e image_type_to_extension().
`IMAGETYPE_BMP` (int)
  Constante do tipo de imagem usada pelas funções image_type_to_mime_type() e image_type_to_extension().
`IMAGETYPE_WBMP` (int)
  Constante do tipo de imagem usada pelas funções image_type_to_mime_type() e image_type_to_extension().
`IMAGETYPE_XBM` (int)
  Constante do tipo de imagem usada pelas funções image_type_to_mime_type() e image_type_to_extension().
`IMAGETYPE_TIFF_II` (int)
  Constante do tipo de imagem usada pelas funções image_type_to_mime_type() e image_type_to_extension().
`IMAGETYPE_TIFF_MM` (int)
  Constante do tipo de imagem usada pelas funções image_type_to_mime_type() e image_type_to_extension().
`IMAGETYPE_IFF` (int)
  Constante do tipo de imagem usada pelas funções image_type_to_mime_type() e image_type_to_extension().
`IMAGETYPE_JB2` (int)
  Constante do tipo de imagem usada pelas funções image_type_to_mime_type() e image_type_to_extension().
`IMAGETYPE_JPC` (int)
  Constante do tipo de imagem usada pelas funções image_type_to_mime_type() e image_type_to_extension().
`IMAGETYPE_JP2` (int)
  Constante do tipo de imagem usada pelas funções image_type_to_mime_type() e image_type_to_extension().
`IMAGETYPE_JPX` (int)
  Constante do tipo de imagem usada pelas funções image_type_to_mime_type() e image_type_to_extension().
`IMAGETYPE_SWC` (int)
  Constante do tipo de imagem usada pelas funções image_type_to_mime_type() e image_type_to_extension().
`IMAGETYPE_ICO` (int)
  Constante do tipo de imagem usada pelas funções image_type_to_mime_type() e image_type_to_extension().
`IMAGETYPE_WEBP` (int)
  Constante do tipo de imagem usada pelas funções image_type_to_mime_type() e image_type_to_extension(). (Diponível no PHP 7.1.0)
`IMAGETYPE_AVIF` (int)
  Constante do tipo de imagem usada pelas funções image_type_to_mime_type() e image_type_to_extension(). (Disponível a partir do PHP 8.1.0)
`IMAGETYPE_HEIF` (int)
  Constante do tipo de imagem usada pelas funções image_type_to_mime_type() e image_type_to_extension(). (Disponível a partir do PHP 8.5.0)
`IMAGETYPE_UNKNOWN` (int)
  Constante do tipo de imagem usada pelas funções image_type_to_mime_type() e image_type_to_extension().
`IMAGETYPE_COUNT` (int)
  O número de constantes de tipos de imagem (incluindo o tipo "desconhecido") suportadas pelas funções image_type_to_mime_type() e image_type_to_extension().
`PNG_NO_FILTER` (int)
  Um filtro PNG especial usado pela função imagepng().
`PNG_FILTER_NONE` (int)
  Um filtro PNG especial usado pela função imagepng().
`PNG_FILTER_SUB` (int)
  Um filtro PNG especial usado pela função imagepng().
`PNG_FILTER_UP` (int)
  Um filtro PNG especial usado pela função imagepng().
`PNG_FILTER_AVG` (int)
  Um filtro PNG especial usado pela função imagepng().
`PNG_FILTER_PAETH` (int)
  Um filtro PNG especial usado pela função imagepng().
`PNG_ALL_FILTERS` (int)
  Um filtro PNG especial usado pela função imagepng().
`IMG_FLIP_VERTICAL` (int)
  Usada junto com imageflip(), disponível a partir do PHP 5.5.0.
`IMG_FLIP_HORIZONTAL` (int)
  Usada junto com imageflip(), disponível a partir do PHP 5.5.0.
`IMG_FLIP_BOTH` (int)
  Usada junto com imageflip(), disponível a partir do PHP 5.5.0.
`IMG_BELL` (int)
  Usada junto com imagesetinterpolation(), disponível a partir do PHP 5.5.0.
`IMG_BESSEL` (int)
  Usada junto com imagesetinterpolation(), disponível a partir do PHP 5.5.0.
`IMG_BILINEAR_FIXED` (int)
  Usada junto com imagesetinterpolation(), disponível a partir do PHP 5.5.0.
`IMG_BICUBIC` (int)
  Usada junto com imagesetinterpolation(), disponível a partir do PHP 5.5.0.
`IMG_BICUBIC_FIXED` (int)
  Usada junto com imagesetinterpolation(), disponível a partir do PHP 5.5.0.
`IMG_BLACKMAN` (int)
  Usada junto com imagesetinterpolation(), disponível a partir do PHP 5.5.0.
`IMG_BOX` (int)
  Usada junto com imagesetinterpolation(), disponível a partir do PHP 5.5.0.
`IMG_BSPLINE` (int)
  Usada junto com imagesetinterpolation(), disponível a partir do PHP 5.5.0.
`IMG_CATMULLROM` (int)
  Usada junto com imagesetinterpolation(), disponível a partir do PHP 5.5.0.
`IMG_GAUSSIAN` (int)
  Usada junto com imagesetinterpolation(), disponível a partir do PHP 5.5.0.
`IMG_GENERALIZED_CUBIC` (int)
  Usada junto com imagesetinterpolation(), disponível a partir do PHP 5.5.0.
`IMG_HERMITE` (int)
  Usada junto com imagesetinterpolation(), disponível a partir do PHP 5.5.0.
`IMG_HAMMING` (int)
  Usada junto com imagesetinterpolation(), disponível a partir do PHP 5.5.0.
`IMG_HANNING` (int)
  Usada junto com imagesetinterpolation(), disponível a partir do PHP 5.5.0.
`IMG_MITCHELL` (int)
  Usada junto com imagesetinterpolation(), disponível a partir do PHP 5.5.0.
`IMG_POWER` (int)
  Usada junto com imagesetinterpolation(), disponível a partir do PHP 5.5.0.
`IMG_QUADRATIC` (int)
  Usada junto com imagesetinterpolation(), disponível a partir do PHP 5.5.0.
`IMG_SINC` (int)
  Usada junto com imagesetinterpolation(), disponível a partir do PHP 5.5.0.
`IMG_NEAREST_NEIGHBOUR` (int)
  Usada junto com imagesetinterpolation(), disponível a partir do PHP 5.5.0.
`IMG_WEIGHTED4` (int)
  Usada junto com imagesetinterpolation(), disponível a partir do PHP 5.5.0.
`IMG_TRIANGLE` (int)
  Usada junto com imagesetinterpolation(), disponível a partir do PHP 5.5.0.
`IMG_CROP_BLACK` (int)
  Recorta um fundo preto.
`IMG_CROP_DEFAULT` (int)
  O mesmo que `IMG_CROP_TRANSPARENT`. Antes do PHP 7.4.0, a libgd incluída convertia para `IMG_CROP_SIDES`, caso a imagem não tivesse cor transparente.
`IMG_CROP_SIDES` (int)
  Usa os 4 cantos da imagem para tentar detectar o fundo a ser recortado.
`IMG_CROP_THRESHOLD` (int)
  Recorta uma imagem usando o limite (informado em `threshold`) e a cor (informada em `color`).
`IMG_CROP_TRANSPARENT` (int)
  Recorta um fundo transparente.
`IMG_CROP_WHITE` (int)
  Recorta um fundo branco.

# Exemplos

## Índice

- Criação de PNG com PHP
- Adicionando marcas d'água a imagens usando canais alfa
- Usando imagecopymerge para criar uma marca d'água translúcida

## Criação de PNG com PHP

Exemplo #1 Criação de PNG com PHP

    <?php

    header("Content-type: image/png");
    $string = $_GET['text'];
    $im     = imagecreatefrompng("images/button1.png");
    $orange = imagecolorallocate($im, 220, 210, 60);
    $px     = (imagesx($im) - 7.5 * strlen($string)) / 2;
    imagestring($im, 3, $px, 9, $string, $orange);
    imagepng($im);

    ?>

Este exemplo seria chamado de uma página com uma etiqueta HTML parecida com: `<img src="button.php?text=text">`. O script button.php acima usa essa string `"text"` e o sobrepõe uma camada na imagem base que neste caso é `"images/button1.png"` e produz a imagem resultante. Esta é uma forma muito conveniente de evitar que se desenhe novas imagens de botões toda vez que se deseja alterar o texto de um botão. Com este método, eles são gerados dinamicamente.

## Adicionando marcas d'água a imagens usando canais alfa

Exemplo #1 Adicionando marcas d'água a imagens usando canais alfa

    <?php
    // Carrega o carimbo e a foto para aplicar a marca d'água
    $stamp = imagecreatefrompng('stamp.png'); // carimbo
    $im = imagecreatefromjpeg('photo.jpeg'); // foto

    // Define as margens para o carimbo e obtém a altura/largura da imagem
    $marge_right = 10;
    $marge_bottom = 10;
    $sx = imagesx($stamp);
    $sy = imagesy($stamp);

    // Copia a imagem do carimbo na foto usando os deslocamentos das margens e a largura
    // da foto para calcular o posicionamento do carimbo.
    imagecopy($im, $stamp, imagesx($im) - $sx - $marge_right, imagesy($im) - $sy - $marge_bottom, 0, 0, imagesx($stamp), imagesy($stamp));

    // Mostra a imagem
    header('Content-type: image/png');
    imagepng($im);
    ?>

Este exemplo é uma forma comum de adicionar marcas d'água e carimbos a fotos e imagens com direitos autorais. Note que a presença de um canal alfa na imagem do carimbo tem suavização de serrilhado. Isto é preservado durante a cópia.

## Usando imagecopymerge() para criar uma marca d'água translúcida

Exemplo #1 Usando imagecopymerge() para criar uma marca d'água translúcida

    <?php
    // Carrega o carimbo e a foto para aplicar a marca d'água
    $im = imagecreatefromjpeg('photo.jpeg');

    // Primeiro cria-se a imagem do carimbo manualmente a partir da GD
    $stamp = imagecreatetruecolor(100, 70);
    imagefilledrectangle($stamp, 0, 0, 99, 69, 0x0000FF);
    imagefilledrectangle($stamp, 9, 9, 90, 60, 0xFFFFFF);
    imagestring($stamp, 5, 20, 20, 'libGD', 0x0000FF);
    imagestring($stamp, 3, 20, 40, '(c) 2007-9', 0x0000FF);

    // Define-se as margens para o carimbo e obtém-se a altura/largura da imagem do carimbo
    $marge_right = 10;
    $marge_bottom = 10;
    $sx = imagesx($stamp);
    $sy = imagesy($stamp);

    // Funde o carimbo com a foto usando uma opacidade de 50%
    imagecopymerge($im, $stamp, imagesx($im) - $sx - $marge_right, imagesy($im) - $sy - $marge_bottom, 0, 0, imagesx($stamp), imagesy($stamp), 50);

    // Salva a imagem em arquivo
    imagepng($im, 'photo_stamp.png');

    ?>

Este exemplo usa imagecopymerge() para fundir a estampa com a imagem original. Desta forma pode-se definir a opacidade do carimbo - no exemplo foi definido para 50%. Na prática isto pode ser útil em proteção contra cópia já que marcas d'água semi-transparentes são difíceis de se remover mas ainda permitem que a imagem seja visualizada.

# Funções de GD e Image

# gd_info

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

gd_info — Obtém informações sobre a biblioteca GD instalada atualmente

### Descrição

function gd_info(): array

Obtém informação sobre a versão e as capacidades da biblioteca GD instalada.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array associativo.

Elementos de array retornados por gd_info()
Atributo | Significado
--- | ---
GD Version | Valor string descrevendo a versão da `libgd` instalada.
FreeType Support | Valor bool. `true` se o suporte FreeType estiver instalado.
FreeType Linkage | Valor string descrevendo a maneira que FreeType foi linkado. Os valores esperados são: 'with freetype', 'with TTF library', e 'with unknown library'. Este elemento será definido apenas se `FreeType Support` for `true`.
GIF Read Support | Valor bool. `true` se o suporte para ler imagens `GIF` estiver incluso.
GIF Create Support | Valor bool. `true` se o suporte para criação de imagens `GIF` estiver incluso.
JPEG Support | Valor bool. `true` se o suporte a `JPEG` estiver incluso.
PNG Support | Valor bool. `true` se o suporte a `PNG` estiver incluso.
WBMP Support | Valor bool. `true` se o suporte a `WBMP` estiver incluso.
XBM Support | Valor bool. `true` se o suporte a `XBM` estiver incluso.
WebP Support | Valor bool. `true` se o suporte a `WebP` estiver incluso.
AVIF Support | Valor bool. `true` se o suporte a `AVIF` estiver incluso. Disponível a partir do PHP 8.1.0.

### Exemplos

Exemplo #1 Usando gd_info()

    <?php
    var_dump(gd_info());
    ?>

O exemplo acima produzirá algo semelhante a:

    array(10) {
      ["GD Version"]=>
      string(24) "bundled (2.1.0 compatible)"
      ["FreeType Support"]=>
      bool(false)
      ["GIF Read Support"]=>
      bool(true)
      ["GIF Create Support"]=>
      bool(false)
      ["JPEG Support"]=>
      bool(false)
      ["PNG Support"]=>
      bool(true)
      ["WBMP Support"]=>
      bool(true)
      ["XBM Support"]=>
      bool(false)
      ["WebP Support"]=>
      bool(false)
      ["AVIF Support"]=>
      bool(false)
    }

### Veja Também

- imagepng() - Envia uma imagem PNG para o navegador ou arquivo
- imagejpeg() - Envia a imagem para o navegador ou para um arquivo
- imagegif() - Envia a imagem para o navegador ou para um arquivo
- imagewbmp() - Envia a imagem para o navegador ou para um arquivo
- imagewebp() - Mostra uma imagem WebP no navegador ou grava em arquivo
- imageavif() - Envia a imagem para o navegador ou para um arquivo
- imagetypes() - Retorna os tipos de imagens suportados pela instalação do PHP

# getimagesize

(PHP 4, PHP 5, PHP 7, PHP 8)

getimagesize — Obtém o tamanho de uma imagem

### Descrição

function getimagesize(string `$filename`, array `&$image_info` = `null`): array|false

A função getimagesize() irá determinar o tamanho de qualquer arquivo de imagem suportado fornecido e retornar as dimensões, juntamente com o tipo de arquivo e uma string de texto `height/width` a ser usada dentro de uma tagHTML`IMG` normal, juntamente com o tipo de conteúdo HTTP correspondente.

getimagesize() também pode retornar mais informações no parâmetro `image_info`.

Cuidado

Essa função espera que `filename` seja um arquivo de imagem válido. Se um arquivo que não seja uma imagem for fornecido, ele pode ser incorretamente detectado como uma imagem, e a função será bem-sucedida, mas o array pode conter valores sem sentido.

Não utilize a função getimagesize() para verificar se um determinado arquivo é uma imagem válida. Em vez disso, utilize uma solução específica para essa finalidade, como a extensão Fileinfo.

> Nota: Observe que os formatos JPC e JP2 podem ter componentes com diferentes profundidades de bits. Nesse caso, o valor "bits" representa a maior profundidade de bits encontrada. Além disso, arquivos JP2 podem conter `multiple JPEG 2000 codestreams`. Nesse caso, a função getimagesize() retorna os valores do primeiro codestream que encontra na raiz do arquivo.

> Nota: As informações sobre ícones são obtidas a partir do ícone com a maior taxa de bits.

> Nota: As imagens GIF consistem em um ou mais frames, em que cada frame pode ocupar apenas uma parte da imagem. O tamanho da imagem relatado pela função getimagesize() é o tamanho geral (lido do descritor da tela lógica).

### Parâmetros

`filename`

  Este parâmetro especifica o arquivo do qual você deseja obter informações. Ele pode fazer referência a um arquivo local ou (se a configuração permitir) a um arquivo remoto usando um dos streams suportados.

`image_info`

  Este parâmetro opcional permite extrair informações estendidas do arquivo de imagem. Atualmente, isso retornará os diferentes marcadores APP JPG como um array associativo. Alguns programas usam esses marcadores APP para incorporar informações de texto em imagens. Um dos usos comuns é incorporar informações » IPTC no marcador APP13. Você pode usar a função iptcparse() para analisar o marcador binário APP13 em algo legível.

  > Nota:

  > O parâmetro `image_info` suporta apenas arquivos no formato JFIF.

### Valor Retornado

Retorna um array com até 7 elementos. Nem todos os tipos de imagem incluirão os elementos `channels` e `bits`.

O índice 0 e 1 contém, respectivamente, a largura e a altura da imagem.

> Nota:

> Alguns formatos podem não conter nenhuma imagem ou podem conter várias imagens. Nesses casos, a função getimagesize() pode não ser capaz de determinar corretamente o tamanho da imagem. A função getimagesize() retornará zero para largura e altura nesses casos.

> Nota: getimagesize() é agnóstica a quaisquer metadados de imagem. Se, por exemplo, a opção `Orientation` de Exif estiver definida para um valor que rotaciona a imagem em 90 ou 270 graus, os índices 0 e 1 trocam de posição, ou seja, eles conterão a altura e a largura, respectivamente.

O índice 2 é uma das constantes `IMAGETYPE_*`, que indica o tipo da imagem.

O índice 3 é uma sequência de texto com a string correta `height="yyy" width="xxx"` que pode ser usada diretamente em uma tag IMG.

`mime` é o tipo MIME correspondente da imagem. Essa informação pode ser usada para fornecer imagens com o cabeçalho `Content-type` HTTP correto:

Exemplo #1 getimagesize() e tipos MIME.

    <?php
    $size = getimagesize($filename);
    $fp = fopen($filename, "rb");
    if ($size && $fp) {
        header("Content-type: {$size['mime']}");
        fpassthru($fp);
        exit;
    } else {
        // erro
    }
    ?>

`channels` Será 3 para imagens RGB e 4 para imagens CMYK.

`bits` é o número de bits para cada cor.

Para alguns tipos de imagem, a presença dos valores de `channels` e `bits` pode ser um pouco confusa. Por exemplo, o formato GIF sempre utiliza 3 canais por pixel, mas o número de bits por pixel não pode ser calculado para um GIF animado com uma tabela de cores global.

Em caso de falha, é retornado `false`.

### Erros/Exceções

Se for impossível acessar a imagem do `filename`, a função getimagesize() gerará um erro de nível `E_WARNING`. Em caso de erro de leitura, getimagesize() gerará um erro de nível `E_NOTICE`.

A partir do PHP 8.0.0, um ValueError é lançado se `filename` estiver vazio.

### Registro de Alterações

Versão | Descrição
--- | ---
8.2.0 | Agora, a função retorna as dimensões reais da imagem, bits e canais de imagens AVIF; anteriormente, as dimensões eram relatadas como `0x0`, e bits e channels não eram relatados de forma alguma.
8.0.0 | Um ValueError agora é lançado se `filename` estiver vazio; anteriormente, um `E_WARNING` era emitido e a função retornava `false`.
7.1.0 | Foi adicionado suporte para WebP.

### Exemplos

Exemplo #2 Exemplo de getimagesize()

    <?php
    list($width, $height, $type, $attr) = getimagesize("img/flag.jpg");
    echo "<img src=\"img/flag.jpg\" $attr alt=\"getimagesize() example\" />";
    ?>

Exemplo #3 getimagesize (URL)

    <?php
    $size = getimagesize("http://www.example.com/gifs/logo.gif");

    // se o nome do arquivo contiver espaços, ele será codificado adequadamente.
    $size = getimagesize("http://www.example.com/gifs/lo%20go.gif");

    ?>

Exemplo #4 getimagesize() retornando IPTC.

    <?php
    $size = getimagesize("testimg.jpg", $info);
    if (isset($info["APP13"])) {
        $iptc = iptcparse($info["APP13"]);
        var_dump($iptc);
    }
    ?>

### Notas

> Nota: Esta função não requer a biblioteca de imagens GD.

### Veja Também

- image_type_to_mime_type() - Obtém o Mime-Type para o tipo de imagem retornado por getimagesize, exif_read_data, exif_thumbnail e exif_imagetype
- exif_imagetype() - Verifica o tipo de uma imagem
- exif_read_data() - Lê os cabeçalhos EXIF de um arquivo de imagen
- exif_thumbnail() - Recupera a miniatura embutida de uma imagem
- imagesx() - Obtém a largura da imagem
- imagesy() - Obtém a altura da imagem

# getimagesizefromstring

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

getimagesizefromstring — Obtém o tamanho de uma imagem a partir de uma string

### Descrição

function getimagesizefromstring(string `$string`, array `&$image_info` = `null`): array|false

Idêntica a getimagesize() exceto que getimagesizefromstring() aceita uma string ao invés de um nome de arquivo como o primeiro parâmetro.

Consulte a documentação de getimagesize() para detalhes de como esta função opera.

### Parâmetros

`string`

  Os dados da imagem, como uma string.

`image_info`

  Consulte getimagesize().

### Valor Retornado

Consulte getimagesize().

### Exemplos

Exemplo #1 Exemplo de getimagesizefromstring()

    <?php
    $img = '/path/to/test.png';

    // Abre como um arquivo
    $size_info1 = getimagesize($img);

    // Ou abre como uma string
    $data       = file_get_contents($img);
    $size_info2 = getimagesizefromstring($data);
    ?>

### Veja Também

- getimagesize() - Obtém o tamanho de uma imagem

# image_type_to_extension

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

image_type_to_extension — Obtém a extensão de arquivo para o tipo da imagem

### Descrição

function image_type_to_extension(int `$image_type`, bool `$include_dot` = `true`): string|false

Retorna a extensão de arquivo para a constante `IMAGETYPE_*` informada.

### Parâmetros

`image_type`

  Uma das constantes `IMAGETYPE_*`.

`include_dot`

  Informa se deve-se prefixar um ponto à extensão ou não. O padrão é `true` (prefixar).

### Valor Retornado

Uma string com a extensão correspondente ao tipo de imagem informado, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de image_type_to_extension()

    <?php
    // Cria instância da imagem
    $im = imagecreatetruecolor(100, 100);

    // Salva a imagem
    imagepng($im, './test' . image_type_to_extension(IMAGETYPE_PNG));
    ?>

### Notas

> Nota: Esta função não requer a biblioteca de imagens GD.

# image_type_to_mime_type

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

image_type_to_mime_type — Obtém o Mime-Type para o tipo de imagem retornado por getimagesize, exif_read_data, exif_thumbnail e exif_imagetype

### Descrição

function image_type_to_mime_type(int `$image_type`): string

A função image_type_to_mime_type() determina o Mime-Type (tipo de mídia) para uma constante IMAGETYPE.

### Parâmetros

`image_type`

  Uma das constantes `IMAGETYPE_*`.

### Valor Retornado

Os valores retornados são os seguintes:

Constantes de valores de retorno
`image_type` | Valor retornado
--- | ---
`IMAGETYPE_GIF` | `image/gif`
`IMAGETYPE_JPEG` | `image/jpeg`
`IMAGETYPE_PNG` | `image/png`
`IMAGETYPE_SWF` | `application/x-shockwave-flash`
`IMAGETYPE_PSD` | `image/psd`
`IMAGETYPE_BMP` | `image/bmp`
`IMAGETYPE_TIFF_II` (ordem de bytes Intel - little endian) | `image/tiff`
`IMAGETYPE_TIFF_MM` (ordem de bytes Motorola - big endian) | `image/tiff`
`IMAGETYPE_JPC` | `application/octet-stream`
`IMAGETYPE_JP2` | `image/jp2`
`IMAGETYPE_JPX` | `application/octet-stream`
`IMAGETYPE_JB2` | `application/octet-stream`
`IMAGETYPE_SWC` | `application/x-shockwave-flash`
`IMAGETYPE_IFF` | `image/iff`
`IMAGETYPE_WBMP` | `image/vnd.wap.wbmp`
`IMAGETYPE_XBM` | `image/xbm`
`IMAGETYPE_ICO` | `image/vnd.microsoft.icon`
`IMAGETYPE_WEBP` | `image/webp`
`IMAGETYPE_AVIF` | `image/avif`
`IMAGETYPE_HEIF` | `image/heif`

### Exemplos

Exemplo #1 Exemplo de image_type_to_mime_type()

    <?php
    header("Content-type: " . image_type_to_mime_type(IMAGETYPE_PNG));
    ?>

### Notas

> Nota: Esta função não requer a biblioteca de imagens GD.

### Veja Também

- getimagesize() - Obtém o tamanho de uma imagem
- exif_imagetype() - Verifica o tipo de uma imagem
- exif_read_data() - Lê os cabeçalhos EXIF de um arquivo de imagen
- exif_thumbnail() - Recupera a miniatura embutida de uma imagem

# image2wbmp

(PHP 4 >= 4.0.5, PHP 5, PHP 7)

image2wbmp — Envia a imagem para o navegador ou para um arquivo

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.3.0 e foi REMOVIDA a partir do PHP 8.0.0. O uso desta função é fortemente desencorajado.

### Descrição

function image2wbmp(resource `$image`, string `$filename` = ?, int `$foreground` = ?): bool

image2wbmp() mostra ou grava uma versão WBMP da imagem informada no parâmetro `image`.

### Parâmetros

`image`

  Um recurso de imagem, retornado por uma das funções de criação de imagem, tal como imagecreatetruecolor().

`filename`

  Caminho para o arquivo gravado. Se não fornecido, o fluxo de imagem puro será mostrado/gravado diretamente.

`foreground`

  Pode-se definir a cor de primeiro plano com este parâmetro configurando um identificador obtido a partir de imagecolorallocate(). A cor padrão de primeiro plano é preta.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

Cuidado

Entretanto, se a biblioteca libgd falhar ao gerar a imagem, esta função retornará `true`.

### Exemplos

Exemplo #1 Exemplo de image2wbmp()

    <?php
    $file = 'php.png';
    $image = imagecreatefrompng($file);

    header('Content-Type: ' . image_type_to_mime_type(IMAGETYPE_WBMP));
    image2wbmp($image); // mostra o fluxo diretamente
    ?>

### Veja Também

- imagewbmp() - Envia a imagem para o navegador ou para um arquivo

# imageaffine

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageaffine — Retorna uma imagem contendo a imagem fonte com transformação afim, usando uma área de recorte opcional

### Descrição

function imageaffine(GdImage `$image`, array `$affine`, ?array `$clip` = `null`): GdImage|false

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`affine`

  Array com chaves de 0 a 5.

`clip`

  Array com chaves "x", "y", "width" (largura) e "height" (altura); ou `null`.

### Valor Retornado

Retorna o objeto da imagem com transformação afim em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `clip` agora pode ser nulo.
8.0.0 | Em caso de sucesso, esta função retorna uma instância de GDImage agora; anteriormente, um resource era retornado.

# imageaffinematrixconcat

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageaffinematrixconcat — Concatena duas matrizes de transformação afim

### Descrição

function imageaffinematrixconcat(array `$matrix1`, array `$matrix2`): array|false

Retorna a concatenação de duas matrizes de transformação afim, que é útil se múltiplas transformações devem ser aplicadas na mesma imagem diretamente.

### Parâmetros

`matrix1`

  Uma matriz de transformação afim (um array com chaves de `0` a `5` e valores float).

`matrix2`

  Uma matriz de transformação afim (um array com chaves de `0` a `5` e valores float).

### Valor Retornado

Uma matriz de transformação afim (um array com chaves de `0` a `5` e valores float) ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de imageaffinematrixconcat()

    <?php
    $m1 = imageaffinematrixget(IMG_AFFINE_TRANSLATE, array('x' => 2, 'y' => 3));
    $m2 = imageaffinematrixget(IMG_AFFINE_SCALE, array('x' => 4, 'y' => 5));
    $matrix = imageaffinematrixconcat($m1, $m2);
    print_r($matrix);
    ?>

O exemplo acima produzirá:

    Array
    (
        [0] => 4
        [1] => 0
        [2] => 0
        [3] => 5
        [4] => 8
        [5] => 15
    )

### Veja Também

- imageaffine() - Retorna uma imagem contendo a imagem fonte com transformação afim, usando uma área de recorte opcional
- imageaffinematrixget() - Obtém uma matriz de transformação afim

# imageaffinematrixget

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageaffinematrixget — Obtém uma matriz de transformação afim

### Descrição

function imageaffinematrixget(int `$type`, array|float `$options`): array|false

Retorna uma matriz de transformação afim.

### Parâmetros

`type`

  Uma das constantes `IMG_AFFINE_*`.

`options`

  Se `type` for `IMG_AFFINE_TRANSLATE` ou `IMG_AFFINE_SCALE`, `options` deve ser um array com chaves `x` e `y`, ambas tendo valores float.

  Se `type` for `IMG_AFFINE_ROTATE`, `IMG_AFFINE_SHEAR_HORIZONTAL` ou `IMG_AFFINE_SHEAR_VERTICAL`, `options` deve ser um float especificando o ângulo em graus.

### Valor Retornado

Uma matriz de transformação afim (um array com chaves de `0` a `5` e valores float) ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de imageaffinematrixget()

    <?php
    $matrix = imageaffinematrixget(IMG_AFFINE_TRANSLATE, array('x' => 2, 'y' => 3));
    print_r($matrix);
    ?>

O exemplo acima produzirá:

    Array
    (
        [0] => 1
        [1] => 0
        [2] => 0
        [3] => 1
        [4] => 2
        [5] => 3
    )

### Veja Também

- imageaffine() - Retorna uma imagem contendo a imagem fonte com transformação afim, usando uma área de recorte opcional
- imageaffinematrixconcat() - Concatena duas matrizes de transformação afim

# imagealphablending

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagealphablending — Define o modo de combinação para uma imagem

### Descrição

function imagealphablending(GdImage `$image`, bool `$enable`): true

imagealphablending() permite dois modos diferentes para desenhar em imagens com cores verdadeiras. No modo de combinação, o componente alfa da cor fornecida para todas as funções de desenho, tal como imagesetpixel(), determina o quanto da cor subjacente deve ser permitido passar. Como resultado, GD automaticamente combina a cor existente naquele ponto com a cor de desenho, e grava o resultado na imagem. O pixel resultante é opaco. Em modo de não-combinação, a cor de desenho é copiada literalmente com sua informação do canal alfa, substituindo o pixel de destino. O modo de combinação não está disponível ao desenhar em imagens com paletas de cores.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`enable`

  Informa se o modo de combinação deve ser habilitado ou não. Em imagens com cores verdadeiras, o padrão é `true` caso contrário o valor padrão é `false`.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de uso de imagealphablending()

    <?php
    // Cria a imagem
    $im = imagecreatetruecolor(100, 100);

    // Define a combinação de alfa para habilitado
    imagealphablending($im, true);

    // Desenha um quadrado
    imagefilledrectangle($im, 30, 30, 70, 70, imagecolorallocate($im, 255, 0, 0));

    // Mostra o resultado
    header('Content-Type: image/png');

    imagepng($im);
    ?>

# imageantialias

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imageantialias — Define se as funções de suavização de serrilhado devem ser usadas ou não

### Descrição

function imageantialias(GdImage `$image`, bool `$enable`): true

Ativa os métodos rápidos de suavização de serrilhado para linhas e polígonos. Não suporta componentes alfa. Funciona usando um operação de combinação direta, e somente com imagens de cores verdadeiras.

Linhas com espessura e com estilos não são suportadas.

Usar primitivas com redução de serrilhado em plano de fundo transparente pode gerar alguns resultados inesperados. O método de combinação usa a cor de fundo como qualquer outra. A falta de suporte ao componente alfa não permite um método de redução de serrilhado baseado no canal alfa.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`enable`

  Informa se a redução de serrilhado deve ser habilitada ou não.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.
7.2.0 | imageantialias() agora está disponível de forma geral. Anteriormente estava disponível somente se o PHP fosse compilado com a versão já incluída da biblioteca GD.

### Exemplos

Exemplo #1 Uma comparação de duas linhas, uma delas com redução de serrilhado

    <?php
    // Comfigura uma imagem com redução de serrilhado e outra normal
    $aa = imagecreatetruecolor(400, 100);
    $normal = imagecreatetruecolor(200, 100);

    // Habilita redução de serrilhado em uma imagem
    imageantialias($aa, true);

    // Aloca cores
    $red = imagecolorallocate($normal, 255, 0, 0);
    $red_aa = imagecolorallocate($aa, 255, 0, 0);

    // Desenha duas linhas, uma com RS habilitada
    imageline($normal, 0, 0, 200, 100, $red);
    imageline($aa, 0, 0, 200, 100, $red_aa);

    // Funde as duas imagens lado a lado para saída (RS: esquerda, Normal: direita)
    imagecopymerge($aa, $normal, 200, 0, 0, 0, 200, 100, 100);

    // Mostra a imagem
    header('Content-type: image/png');

    imagepng($aa);
    ?>

O exemplo acima produzirá algo semelhante a:

### Veja Também

- imagecreatetruecolor() - Cria uma nova imagem em cores verdadeiras

# imagearc

(PHP 4, PHP 5, PHP 7, PHP 8)

imagearc — Desenha um arco

### Descrição

function imagearc(
GdImage `$image`,
int `$center_x`,
int `$center_y`,
int `$width`,
int `$height`,
int `$start_angle`,
int `$end_angle`,
int `$color`
): true

imagearc() desenha um arco de círculo centrado nas coordenadas fornecidas.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`center_x`

  Coordenada x do centro.

`center_y`

  Coordenada y do centro.

`width`

  Largura do arco.

`height`

  Altura do arco.

`start_angle`

  Ângulo inicial do arco, em graus.

`end_angle`

  Ângulo final do arco, em graus. 0° está localizado na posição de 3 horas, e o arco é desenhado no sentido horário.

`color`

  Um identificador de cor criado com imagecolorallocate().

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Desenhando um círculo com imagearc()

    <?php

    // cria uma imagem 200x200
    $img = imagecreatetruecolor(200, 200);

    // aloca algumas cores
    $white = imagecolorallocate($img, 255, 255, 255);
    $red   = imagecolorallocate($img, 255,   0,   0);
    $green = imagecolorallocate($img,   0, 255,   0);
    $blue  = imagecolorallocate($img,   0,   0, 255);

    // desenha a cabeça
    imagearc($img, 100, 100, 200, 200,  0, 360, $white);
    // boca
    imagearc($img, 100, 100, 150, 150, 25, 155, $red);
    // olho esquerdo e olho direito
    imagearc($img,  60,  75,  50,  50,  0, 360, $green);
    imagearc($img, 140,  75,  50,  50,  0, 360, $blue);

    // mostra a imagem no navegador
    header("Content-type: image/png");
    imagepng($img);

    ?>

O exemplo acima produzirá algo semelhante a:

### Veja Também

- imagefilledarc() - Desenha um arco parcial preenchido
- imageellipse() - Desenha uma elipse
- imagefilledellipse() - Desenha uma elipse preenchida

# imageavif

(PHP 8 >= 8.1.0)

imageavif — Envia a imagem para o navegador ou para um arquivo

### Descrição

function imageavif(
GdImage `$image`,
resource|string|null `$file` = `null`,
int `$quality` = -1,
int `$speed` = -1
): bool

Mostra ou grava uma imagem rasterizada AVIF a partir da imagem fornecida em `image`.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`file`

  O caminho ou um recurso de fluxo aberto (que será fechado automaticamente após o retorno desta função) para salvar o arquivo. Se não for definido ou for `null`, o fluxo da imagem bruta será enviado diretamente.

`quality`

  `quality` é opcional, e varia de 0 (pior qualidade, arquivo menor) a 100 (melhor qualidade, arquivo maior). Se `-1` for fornecido, o valor padrão de `52` será usado.

`speed`

  `speed` é opcional, e varia de 0 (lento, arquivo menor) a 10 (rápido, arquivo maior). Se `-1` for fornecido, o valor padrão `6` será usado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

Cuidado

Entretanto, se a biblioteca libgd falhar ao gerar a imagem, esta função retornará `true`.

### Erros/Exceções

Lança um ValueError se `quality` ou `speed` forem inválidos.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Agora lança um ValueError se `quality` ou `speed` forem inválidos.

### Veja Também

- imagepng() - Envia uma imagem PNG para o navegador ou arquivo
- imagewbmp() - Envia a imagem para o navegador ou para um arquivo
- imagejpeg() - Envia a imagem para o navegador ou para um arquivo
- imagetypes() - Retorna os tipos de imagens suportados pela instalação do PHP

# imagebmp

(PHP 7 >= 7.2.0, PHP 8)

imagebmp — Mostra ou grava uma imagem BMP

### Descrição

function imagebmp(GdImage `$image`, resource|string|null `$file` = `null`, bool `$compressed` = `true`): bool

Mostra ou grava uma versão BMP da imagem fornecida em `image`.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`file`

  O caminho ou um recurso de fluxo aberto (que será fechado automaticamente após o retorno desta função) para salvar o arquivo. Se não for definido ou for `null`, o fluxo da imagem bruta será enviado diretamente.

  > Nota:

  > `null` é inválido se o parâmetro `compressed` não for usado.

`compressed`

  Define se o BMP deve ser comprimido com codificação run-length (RLE), ou não.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

Cuidado

Entretanto, se a biblioteca libgd falhar ao gerar a imagem, esta função retornará `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.
8.0.0 | O tipo de `compressed` agora é bool; anteriormente era int.

### Exemplos

Exemplo #1 Gravando um arquivo BMP

    <?php
    // Cria uma imagem vazia e adiciona texto
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);

    imagestring($im, 1, 5, 5,  'BMP com PHP', $text_color);

    // Grava a imagem
    imagebmp($im, 'php.bmp');
    ?>

# imagechar

(PHP 4, PHP 5, PHP 7, PHP 8)

imagechar — Desenha um caractere horizontalmente

### Descrição

function imagechar(
GdImage `$image`,
GdFont|int `$font`,
int `$x`,
int `$y`,
string `$char`,
int `$color`
): true

imagechar() desenha o primeiro caractere de `char` na imagem identificada por `image` com seu canto superior esquerdo em `x`,`y` (superior esquerdo é 0, 0) com a cor `color`.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`font`
  Pode ser 1, 2, 3, 4, 5 para as fontes nativas na codificação latin2 (onde números maiores correspondem a fontes maiores) ou uma instância de GdFont, retornada por imageloadfont().
`x`

  Coordenada x do início.

`y`

  Coordenada y do início.

`char`

  O caractere a ser desenhado.

`color`

  Um identificador de cor criado com imagecolorallocate().

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `font` agora aceita uma instância de GdFont ou um int; anteriormente, apenas int era aceito.
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imagechar()

    <?php

    $im = imagecreate(100, 100);

    $string = 'PHP';

    $bg = imagecolorallocate($im, 255, 255, 255);
    $black = imagecolorallocate($im, 0, 0, 0);

    // mostra um "P" na cor preta no canto superior esquerdo
    imagechar($im, 1, 0, 0, $string, $black);

    header('Content-type: image/png');
    imagepng($im);

    ?>

O exemplo acima produzirá algo semelhante a:

### Veja Também

- imagecharup() - Desenha um caractere verticalmente
- imageloadfont() - Carrega uma nova fonte

# imagecharup

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecharup — Desenha um caractere verticalmente

### Descrição

function imagecharup(
GdImage `$image`,
GdFont|int `$font`,
int `$x`,
int `$y`,
string `$char`,
int `$color`
): true

Desenha o caractere `char` verticalmente na coordenada especificada na imagem informada em `image`.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`font`
  Pode ser 1, 2, 3, 4, 5 para as fontes nativas na codificação latin2 (onde números maiores correspondem a fontes maiores) ou uma instância de GdFont, retornada por imageloadfont().
`x`

  Coordenada x do início.

`y`

  Coordenada y do início.

`char`

  O caractere a ser desenhado.

`color`

  Um identificador de cor criado com imagecolorallocate().

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `font` agora aceita uma instância de GdFont ou um int; anteriormente, apenas int era aceito.
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imagecharup()

    <?php

    $im = imagecreate(100, 100);

    $string = 'Note que a primeira letra é um N';

    $bg = imagecolorallocate($im, 255, 255, 255);
    $black = imagecolorallocate($im, 0, 0, 0);

    // mostra um "Z" na cor preta em um fundo branco
    imagecharup($im, 3, 10, 10, $string, $black);

    header('Content-type: image/png');
    imagepng($im);

    ?>

O exemplo acima produzirá algo semelhante a:

### Veja Também

- imagechar() - Desenha um caractere horizontalmente
- imageloadfont() - Carrega uma nova fonte

# imagecolorallocate

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorallocate — Aloca uma cor para uma imagem

### Descrição

function imagecolorallocate(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int|false

Retorna um identificador de cor representando a cor composta pelos componentes RGB.

imagecolorallocate() precisa ser chamada para criar cada cor que será usada na imagem representada por `image`.

> Nota:

> A primeira chamada a imagecolorallocate() preenche a cor de fundo em imagens com base em paletas - imagens criadas usando imagecreate().

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`red`

  Valor do componente vermelho.

`green`

  Valor do componente verde.

`blue`

  Valor do componente azul.

Estes parâmetros são inteiros entre 0 e 255 ou hexadecimais entre 0x00 e 0xFF.

### Valor Retornado

Um identificador de cor ou `false` se a alocação falhar.

Aviso

Esta função pode retornar o valor booleano `false`, mas também pode retornar um valor não booleano que pode ser avaliado como `false`. Leia a seção sobre Booleanos para mais informações. Use o operador === para testar o valor retornado por esta função.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imagecolorallocate()

    <?php

    $im = imagecreate(100, 100);

    // define a cor de fundo para vermelha
    $background = imagecolorallocate($im, 255, 0, 0);

    // define algumas cores
    $white = imagecolorallocate($im, 255, 255, 255); //branca
    $black = imagecolorallocate($im, 0, 0, 0); //preta

    // com hexadecimais
    $white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF); //branca
    $black = imagecolorallocate($im, 0x00, 0x00, 0x00); //preta

    ?>

### Veja Também

- imagecolorallocatealpha() - Aloca uma cor para uma imagem
- imagecolordeallocate() - Desaloca uma cor de uma imagem

# imagecolorallocatealpha

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imagecolorallocatealpha — Aloca uma cor para uma imagem

### Descrição

function imagecolorallocatealpha(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha`
): int|false

imagecolorallocatealpha() se comporta de forma idêntica a imagecolorallocate() com a adição do parâmetro de transparência `alpha`.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`red`

  Valor do componente vermelho.

`green`

  Valor do componente verde.

`blue`

  Valor do componente azul.

`alpha`

  Um valor entre `0` e `127`. `0` indica completamente opaco enquanto que `127` indica completamente transparente.

Os parâmetros `red`, `green` e `blue` são inteiros entre 0 e 255 ou haxadecimais entre 0x00 e 0xFF.

### Valor Retornado

Um identificador de cor ou `false` se a alocação falhar.

Aviso

Esta função pode retornar o valor booleano `false`, mas também pode retornar um valor não booleano que pode ser avaliado como `false`. Leia a seção sobre Booleanos para mais informações. Use o operador === para testar o valor retornado por esta função.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de uso de imagecolorallocatealpha()

    <?php
    $size = 300;
    $image=imagecreatetruecolor($size, $size);

    // algo para obter fundo branco com borda preta
    $back = imagecolorallocate($image, 255, 255, 255); //fundo
    $border = imagecolorallocate($image, 0, 0, 0); //borda
    imagefilledrectangle($image, 0, 0, $size - 1, $size - 1, $back);
    imagerectangle($image, 0, 0, $size - 1, $size - 1, $border);

    $yellow_x = 100;
    $yellow_y = 75;
    $red_x    = 120;
    $red_y    = 165;
    $blue_x   = 187;
    $blue_y   = 125;
    $radius   = 150;

    // aloca cores com valores de alfa
    $yellow = imagecolorallocatealpha($image, 255, 255, 0, 75);
    $red    = imagecolorallocatealpha($image, 255, 0, 0, 75);
    $blue   = imagecolorallocatealpha($image, 0, 0, 255, 75);

    // desenhando 3 círculos sobrepostos
    imagefilledellipse($image, $yellow_x, $yellow_y, $radius, $radius, $yellow);
    imagefilledellipse($image, $red_x, $red_y, $radius, $radius, $red);
    imagefilledellipse($image, $blue_x, $blue_y, $radius, $radius, $blue);

    // não esquecer de emitir um cabeçalho corretamente!
    header('Content-Type: image/png');

    // e finalmente, mostra o resultado
    imagepng($image);
    ?>

O exemplo acima produzirá algo semelhante a:

Exemplo #2 Converte valores típicos de alfa para uso com imagecolorallocatealpha()

Normalmente, valores de alfa `0` designam pixels totalmente transparentes, e o canal alfa tem 8 bits. Para converter taia valores de alfa para que sejam compatíveis com imagecolorallocatealpha(), uma aritmética simples é suficiente:

    <?php
    $alpha8 = 0; // totalmente transparente
    var_dump(127 - ($alpha8 >> 1));
    $alpha8 = 255; // totalmente opaco
    var_dump(127 - ($alpha8 >> 1));
    ?>

O exemplo acima produzirá:

    int(127)
    int(0)

### Veja Também

- imagecolorallocate() - Aloca uma cor para uma imagem
- imagecolordeallocate() - Desaloca uma cor de uma imagem

# imagecolorat

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorat — Obtém o índica da cor de um pixel

### Descrição

function imagecolorat(GdImage `$image`, int `$x`, int `$y`): int|false

Retorna o índice da cor do pixel na localização especificada na imagem informada em `image`.

Se a imagem for em cores verdadeiras, esta função retorna o valor RGB do pixel como inteiro. Use deslocamentos de bits e máscaras para distinguir os componentes de vermelho, verde e azul:

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`x`

  Coordenada x do pixel.

`y`

  Coordenada y do pixel.

### Valor Retornado

Retorna o índice da cor ou `false` em caso de falha.

Aviso

Esta função pode retornar o valor booleano `false`, mas também pode retornar um valor não booleano que pode ser avaliado como `false`. Leia a seção sobre Booleanos para mais informações. Use o operador === para testar o valor retornado por esta função.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Acessando valores decompostos de RGB

    <?php
    $im = imagecreatefrompng("php.png");
    $rgb = imagecolorat($im, 10, 15);
    $r = ($rgb >> 16) & 0xFF;
    $g = ($rgb >> 8) & 0xFF;
    $b = $rgb & 0xFF;

    var_dump($r, $g, $b);
    ?>

O exemplo acima produzirá algo semelhante a:

    int(119)
    int(123)
    int(180)

Exemplo #2 Valores legíveis de RGB usando imagecolorsforindex()

    <?php
    $im = imagecreatefrompng("php.png");
    $rgb = imagecolorat($im, 10, 15);

    $colors = imagecolorsforindex($im, $rgb);

    var_dump($colors);
    ?>

O exemplo acima produzirá algo semelhante a:

    array(4) {
      ["red"]=>
      int(119)
      ["green"]=>
      int(123)
      ["blue"]=>
      int(180)
      ["alpha"]=>
      int(127)
    }

### Veja Também

- imagecolorset() - Define a cor para o índice da paleta especificado
- imagecolorsforindex() - Obtém as cores para um índice
- imagesetpixel() - Desenha um pixel

# imagecolorclosest

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorclosest — Obtém o índice da cor mais próxima à especificada

### Descrição

function imagecolorclosest(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int

Retorna o índice da cor na paleta da imagem que for a mais "próxima" ao valor RGB especificado.

A "distância" entre a cor desejada em relação a cada cor da paleta é calculada como se os valores RGB representassem pontos no espaço tridimensional.

Se a imagem foi criada a partir de um arquivo, apenas as cores usadas na imagem são resolvidas. As cores presentes apenas na paleta não serão resolvidas.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`red`

  Valor do componente vermelho.

`green`

  Valor do componente verde.

`blue`

  Valor do componente azul.

Os parâmetros de cores são inteiros entre 0 e 255 ou hexadecimais entre 0x00 e 0xFF.

### Valor Retornado

Retorna o índice na paleta da imagem da cor mais próxima à especificada.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Procura por um conjunto de cores em uma imagem

    <?php
    // Inicia com uma imagem e converte-a para uma baseada em paleta
    $im = imagecreatefrompng('figures/imagecolorclosest.png');
    imagetruecolortopalette($im, false, 255);

    // Cores que serão procuradas (RGB)
    $colors = array(
        array(254, 145, 154),
        array(153, 145, 188),
        array(153, 90, 145),
        array(255, 137, 92)
    );

    // Faz uma repeticação para cada procura e encontra a cor mais próxima na paleta.
    // Retorna o número da procura, a cor RGB sendo procurada e a cor correspondente encontrada, convertida para RGB
    foreach($colors as $id => $rgb)
    {
        $result = imagecolorclosest($im, $rgb[0], $rgb[1], $rgb[2]);
        $result = imagecolorsforindex($im, $result);
        $result = "({$result['red']}, {$result['green']}, {$result['blue']})";

        echo "#$id: Cor procurada: ($rgb[0], $rgb[1], $rgb[2]); Cor mais próxima: $result.\n";
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    #0: Cor procurada: (254, 145, 154); Cor mais próxima: (252, 150, 148).
    #1: Cor procurada: (153, 145, 188); Cor mais próxima: (148, 150, 196).
    #2: Cor procurada: (153, 90, 145); Cor mais próxima: (148, 90, 156).
    #3: Cor procurada: (255, 137, 92); Cor mais próxima: (252, 150, 92).

### Veja Também

- imagecolorexact() - Obtém o índice da cor especificada
- imagecolorclosestalpha() - Obtém o índice da cor mais próxima à especificada (incluindo alfa)
- imagecolorclosesthwb() - Obtém o índice da cor que tem a matiz, brancura e negritude mais próximas de uma cor informada

# imagecolorclosestalpha

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecolorclosestalpha — Obtém o índice da cor mais próxima à especificada (incluindo alfa)

### Descrição

function imagecolorclosestalpha(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha`
): int

Retorna o índice da cor na paleta da imagem que for a mais "próxima" ao valor RGB e ao nível `alpha` especificados.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`red`

  Valor do componente vermelho.

`green`

  Valor do componente verde.

`blue`

  Valor do componente azul.

`alpha`

  Um valor entre `0` e `127`. `0` indica completamente opaco enquanto que `127` indica completamente transparente.

Os parâmetros de cores são inteiros entre 0 e 255 ou hexadecimais entre 0x00 e 0xFF.

### Valor Retornado

Retorna o índice na paleta da imagem da cor mais próxima à especificada.

### Exemplos

Exemplo #1 Procura por um conjunto de cores em uma imagem

    <?php
    // Inicia com uma imagem e converte-a para uma baseada em paleta
    $im = imagecreatefrompng('figures/imagecolorclosest.png');
    imagetruecolortopalette($im, false, 255);

    // Cores que serão procuradas (RGB)
    $colors = array(
        array(254, 145, 154, 50),
        array(153, 145, 188, 127),
        array(153, 90, 145, 0),
        array(255, 137, 92, 84)
    );

    // Faz uma repeticação para cada procura e encontra a cor mais próxima na paleta.
    // Retorna o número da procura, a cor RGB sendo procurada e a cor correspondente encontrada, convertida para RGB
    foreach($colors as $id => $rgb)
    {
        $result = imagecolorclosestalpha($im, $rgb[0], $rgb[1], $rgb[2], $rgb[3]);
        $result = imagecolorsforindex($im, $result);
        $result = "({$result['red']}, {$result['green']}, {$result['blue']}, {$result['alpha']})";

        echo "#$id: Cor procurada: ($rgb[0], $rgb[1], $rgb[2], $rgb[3]); Cor mais próxima: $result.\n";
    }
    ?>

O exemplo acima produzirá algo semelhante a:

    #0: Cor procurada: (254, 145, 154, 50); Cor mais próxima: (252, 150, 148, 0).
    #1: Cor procurada: (153, 145, 188, 127); Cor mais próxima: (148, 150, 196, 0).
    #2: Cor procurada: (153, 90, 145, 0); Cor mais próxima: (148, 90, 156, 0).
    #3: Cor procurada: (255, 137, 92, 84); Cor mais próxima: (252, 150, 92, 0).

### Veja Também

- imagecolorexactalpha() - Obtém o índice da cor e alfa especificados
- imagecolorclosest() - Obtém o índice da cor mais próxima à especificada
- imagecolorclosesthwb() - Obtém o índice da cor que tem a matiz, brancura e negritude mais próximas de uma cor informada

# imagecolorclosesthwb

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecolorclosesthwb — Obtém o índice da cor que tem a matiz, brancura e negritude mais próximas de uma cor informada

### Descrição

function imagecolorclosesthwb(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int

Obtém o índice da cor que tem a matiz, a brancura e a negritude mais próximas da cor informada.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`red`

  Valor do componente vermelho.

`green`

  Valor do componente verde.

`blue`

  Valor do componente azul.

### Valor Retornado

Retorna um inteiro com o índice da cor que tem a matiz, a brancura e a negritude mais próxima da cor informada.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de uso de imagecolorclosesthwb()

    <?php
    $im = imagecreatefromgif('php.gif');

    echo 'HWB: ' . imagecolorclosesthwb($im, 116, 115, 152);
    ?>

O exemplo acima produzirá algo semelhante a:

    HWB: 33

### Veja Também

- imagecolorclosest() - Obtém o índice da cor mais próxima à especificada

# imagecolordeallocate

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolordeallocate — Desaloca uma cor de uma imagem

### Descrição

function imagecolordeallocate(GdImage `$image`, int `$color`): true

Desaloca uma cor previamente alocada com imagecolorallocate() ou imagecolorallocatealpha().

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`color`

  O identificador da cor.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Usando imagecolordeallocate()

    <?php
    $white = imagecolorallocate($im, 255, 255, 255);
    imagecolordeallocate($im, $white);
    ?>

### Veja Também

- imagecolorallocate() - Aloca uma cor para uma imagem
- imagecolorallocatealpha() - Aloca uma cor para uma imagem

# imagecolorexact

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorexact — Obtém o índice da cor especificada

### Descrição

function imagecolorexact(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int

Retorna o índice, na paleta da imagem, da cor especificada.

Se a imagem foi criada a partir de um arquivo, apenas as cores usadas na imagem são resolvidas. As cores presentes apenas na paleta não serão resolvidas.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`red`

  Valor do componente vermelho.

`green`

  Valor do componente verde.

`blue`

  Valor do componente azul.

### Valor Retornado

Retorna o índice, na paleta da imagem, da cor especificada, ou -1 se a cor não existir.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Obtém cores da logomarca GD

    <?php
    // Configura uma imagem
    $im = imagecreatefrompng('./gdlogo.png');

    $colors   = Array();
    $colors[] = imagecolorexact($im, 255, 0, 0);
    $colors[] = imagecolorexact($im, 0, 0, 0);
    $colors[] = imagecolorexact($im, 255, 255, 255);
    $colors[] = imagecolorexact($im, 100, 255, 52);

    print_r($colors);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => 16711680
        [1] => 0
        [2] => 16777215
        [3] => 6618932
    )

### Veja Também

- imagecolorclosest() - Obtém o índice da cor mais próxima à especificada

# imagecolorexactalpha

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecolorexactalpha — Obtém o índice da cor e alfa especificados

### Descrição

function imagecolorexactalpha(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha`
): int

Retorna o índice, na paleta da imagem, da cor e do alfa especificados.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`red`

  Valor do componente vermelho.

`green`

  Valor do componente verde.

`blue`

  Valor do componente azul.

`alpha`

  Um valor entre `0` e `127`. `0` indica completamente opaco enquanto que `127` indica completamente transparente.

Os parâmetros de cores são inteiros entre 0 e 255 ou hexadecimais entre 0x00 e 0xFF.

### Valor Retornado

Retorna o índice, na paleta da imagem, da cor + alfa especificados, ou -1 se a cor + alfa não existir na paleta.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Obtém cores da logomarca GD

    <?php

    // Configura uma imagem
    $im = imagecreatefrompng('./gdlogo.png');

    $colors   = Array();
    $colors[] = imagecolorexactalpha($im, 255, 0, 0, 0);
    $colors[] = imagecolorexactalpha($im, 0, 0, 0, 127);
    $colors[] = imagecolorexactalpha($im, 255, 255, 255, 55);
    $colors[] = imagecolorexactalpha($im, 100, 255, 52, 20);

    print_r($colors);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => 16711680
        [1] => 2130706432
        [2] => 939524095
        [3] => 342163252
    )

### Veja Também

- imagecolorclosestalpha() - Obtém o índice da cor mais próxima à especificada (incluindo alfa)

# imagecolormatch

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imagecolormatch — Faz com que as cores da versão em paleta da imagem fiquem mais próximas da versão em cores verdadeiras

### Descrição

function imagecolormatch(GdImage `$image1`, GdImage `$image2`): true

Faz com que as cores da versão em paleta da imagem fiquem mais próximas da versão em cores verdadeiras.

### Parâmetros

`image1`

  Um objeto de imagem em cores verdadeiras.

`image2`

  Um objeto de imagem em paleta apontando para uma imagem que tenha o mesmo tamanho da `image1`.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `image1` e `image2` agora esperam instâncias de GdImage; anteriormente, resources eram esperados.

### Exemplos

Exemplo #1 Exemplo de imagecolormatch()

    <?php
    // Configura as imagens com cores verdadeiras e com paleta
    $im1 = imagecreatefrompng('./gdlogo.png');
    $im2 = imagecreate(imagesx($im1), imagesy($im1));

    // Adiciona algumas cores a $im2
    $colors   = Array();
    $colors[] = imagecolorallocate($im2, 255, 36, 74);
    $colors[] = imagecolorallocate($im2, 40, 0, 240);
    $colors[] = imagecolorallocate($im2, 82, 100, 255);
    $colors[] = imagecolorallocate($im2, 84, 63, 44);

    // Faz correspondência dessas cores com a imagem em cores verdadeiras
    imagecolormatch($im1, $im2);
    ?>

### Veja Também

- imagecreatetruecolor() - Cria uma nova imagem em cores verdadeiras

# imagecolorresolve

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorresolve — Obtém o índice da cor especificada ou a alternativa mais próxima

### Descrição

function imagecolorresolve(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int

Esta função garantidamente retorna um índice para uma cor solicitada, pode ser a cor exata ou a cor mais alternativa mais próxima.

Se a imagem foi criada a partir de um arquivo, apenas as cores usadas na imagem são resolvidas. As cores presentes apenas na paleta não serão resolvidas.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`red`

  Valor do componente vermelho.

`green`

  Valor do componente verde.

`blue`

  Valor do componente azul.

### Valor Retornado

Retorna um índice de cor.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Usando imagecoloresolve() para obter cores de uma imagem

    <?php
    // Carrega uma imagem
    $im = imagecreatefromgif('phplogo.gif');

    // Obtém as cores mais próximas da imagem
    $colors = array();
    $colors[] = imagecolorresolve($im, 255, 255, 255);
    $colors[] = imagecolorresolve($im, 0, 0, 200);

    // Saída
    print_r($colors);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => 89
        [1] => 85
    )

### Veja Também

- imagecolorclosest() - Obtém o índice da cor mais próxima à especificada

# imagecolorresolvealpha

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecolorresolvealpha — Obtém o índice da cor + alfa especificados ou a alternativa mais próxima

### Descrição

function imagecolorresolvealpha(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha`
): int

Esta função garantidamente retorna um índice para uma cor solicitada, pode ser a cor exata ou a cor mais alternativa mais próxima.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`red`

  Valor do componente vermelho.

`green`

  Valor do componente verde.

`blue`

  Valor do componente azul.

`alpha`

  Um valor entre `0` e `127`. `0` indica completamente opaco enquanto que `127` indica completamente transparente.

Os parâmetros de cores são inteiros entre 0 e 255 ou hexadecimais entre 0x00 e 0xFF.

### Valor Retornado

Retorna um índice de cor.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Usando imagecoloresolvealpha() para obter cores de uma imagem

    <?php
    // Carrega uma imagem
    $im = imagecreatefromgif('phplogo.gif');

    // Obtém as cores mais próximas da imagem
    $colors = array();
    $colors[] = imagecolorresolvealpha($im, 255, 255, 255, 0);
    $colors[] = imagecolorresolvealpha($im, 0, 0, 200, 127);

    // Saída
    print_r($colors);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => 89
        [1] => 85
    )

### Veja Também

- imagecolorclosestalpha() - Obtém o índice da cor mais próxima à especificada (incluindo alfa)

# imagecolorset

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorset — Define a cor para o índice da paleta especificado

### Descrição

function imagecolorset(
GdImage `$image`,
int `$color`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha` = 0
): ?false

Esta função atribui a cor especificada ao índice especificado na paleta. Isto é útil para criar efeitos de preenchimento em imagens de paleta sem a sobrecarga de realizar verdadeiramente o preenchimento.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`color`

  Um índice na paleta.

`red`

  Valor do componente vermelho.

`green`

  Valor do componente verde.

`blue`

  Valor do componente azul.

`alpha`

  Valor do componente alfa.

### Valor Retornado

A função retorna `null` em caso de sucesso, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imagecolorset()

    <?php
    // Cria uma imagem 300x100
    $im = imagecreate(300, 100);

    // Define o plano de fundo para vermelho
    imagecolorallocate($im, 255, 0, 0);

    // Obtém o índice de cor para o plano de fundo
    $bg = imagecolorat($im, 0, 0);

    // Define o plano de fundo para azul
    imagecolorset($im, $bg, 0, 0, 255);

    // Mostra a imagem no navegador
    header('Content-Type: image/png');

    imagepng($im);
    ?>

### Veja Também

- imagecolorat() - Obtém o índica da cor de um pixel

# imagecolorsforindex

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorsforindex — Obtém as cores para um índice

### Descrição

function imagecolorsforindex(GdImage `$image`, int `$color`): array

Obtém a cor para um índice especificado.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`color`

  O índice de cor.

### Valor Retornado

Retorna um array associativo com chaves para vermelho, verde, azul e alfa que contêm os valores correspondentes à cor do índice especificado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.
8.0.0 | imagecolorsforindex() agora lança uma exceção ValueError se `color` estiver fora dos limites; anteriormente, `false` era retornado.

### Exemplos

Exemplo #1 Exemplo de imagecolorsforindex()

    <?php

    // abre uma imagem
    $im = imagecreatefrompng('nexen.png');

    // obtém uma cor
    $start_x = 40;
    $start_y = 50;
    $color_index = imagecolorat($im, $start_x, $start_y);

    // torna legível
    $color_tran = imagecolorsforindex($im, $color_index);

    // que cor é essa ?
    print_r($color_tran);

    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
       [red] => 226
       [green] => 222
       [blue] => 252
       [alpha] => 0
    )

### Veja Também

- imagecolorat() - Obtém o índica da cor de um pixel
- imagecolorexact() - Obtém o índice da cor especificada

# imagecolorstotal

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorstotal — Obtém o número de cores em uma paleta de imagem

### Descrição

function imagecolorstotal(GdImage `$image`): int

Retorna o número de cores em uma paleta de imagem.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().

### Valor Retornado

Retorna o número de cores em uma paleta de imagem especificada ou 0 para imagens em cores verdadeiras.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Obtendo o número total de cores em uma imagem usando imagecolorstotal()

    <?php
    // Cria uma instência de imagem
    $im = imagecreatefromgif('php.gif');

    echo 'Total de cores na imagem: ' . imagecolorstotal($im);
    ?>

O exemplo acima produzirá algo semelhante a:

    Total de cores na imagem: 128

### Veja Também

- imagecolorat() - Obtém o índica da cor de um pixel
- imagecolorsforindex() - Obtém as cores para um índice
- imageistruecolor() - Descobre se uma imagem está em cores verdadeiras

# imagecolortransparent

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolortransparent — Define uma cor como transparente

### Descrição

function imagecolortransparent(GdImage `$image`, ?int `$color` = `null`): int

Obtém ou define a cor transparente na imagem fornecida em `image`.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`color`

  Um identificador de cor criado com imagecolorallocate().

### Valor Retornado

O identificador da nova (ou atual se nenhuma for especificada) cor transparente é retornado. Se `color` for `null`, e a imagem não tiver cor transparente, o identificador retornado será `-1`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.
8.0.0 | `color` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo de imagecolortransparent()

    <?php
    // Cria uma image 55 x 30
    $im = imagecreatetruecolor(55, 30);
    $red = imagecolorallocate($im, 255, 0, 0);
    $black = imagecolorallocate($im, 0, 0, 0);

    // Define o fundo para transparente
    imagecolortransparent($im, $black);

    // Desenha um retângulo vermelho
    imagefilledrectangle($im, 4, 4, 50, 25, $red);

    // Grava a imagem
    imagepng($im, './imagecolortransparent.png');
    ?>

O exemplo acima produzirá algo semelhante a:

### Notas

> Nota: Transparência é copiada apenas com imagecopymerge() e imagens com cores verdadeiras, e não com imagecopy() ou imagens com paleta.

> Nota:

> A cor transparente é uma propriedade da imagem, a transparência não é uma propriedade da cor. Uma vez definida uma cor transparente, as regiões da imagem com essa cor que foram desenhadas anteriormente serão transparentes.

# imageconvolution

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

imageconvolution — Aplica uma matriz de convolução 3x3, usando coeficiente e deslocamento

### Descrição

function imageconvolution(
GdImage `$image`,
array `$matrix`,
float `$divisor`,
float `$offset`
): bool

Aplica uma matriz de convolução à imagem, usando o coeficiente e o deslocamento fornecidos.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`matrix`

  Um matriz 3x3: um array de três arrays de três números em ponto flutuante.

`divisor`

  O divisor do resultado da convolução, usado para normalização.

`offset`

  Deslocamento de cor.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Gravando em relevo a logomarca do PHP.net

    <?php
    $image = imagecreatefromgif('http://www.php.net/images/php.gif');

    $emboss = array(array(2, 0, 0), array(0, -1, 0), array(0, 0, -1));
    imageconvolution($image, $emboss, 1, 127);

    header('Content-Type: image/png');
    imagepng($image, null, 9);
    ?>

O exemplo acima produzirá:

Exemplo #2 Desfoque gaussiano

    <?php
    $image = imagecreatetruecolor(180,40);

    // Escreve o texto e aplica um desfoque gaussiano na imagem
    imagestring($image, 5, 10, 8, 'Gaussian Blur Text', 0x00ff00);
    $gaussian = array(array(1.0, 2.0, 1.0), array(2.0, 4.0, 2.0), array(1.0, 2.0, 1.0));
    imageconvolution($image, $gaussian, 16, 0);

    // Re-escreve o texto para comparação
    imagestring($image, 5, 10, 18, 'Gaussian Blur Text', 0x00ff00);

    header('Content-Type: image/png');
    imagepng($image, null, 9);
    ?>

O exemplo acima produzirá:

### Veja Também

- imagefilter() - Aplica um filtro a uma imagem

# imagecopy

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecopy — Copia uma parte de uma imagem

### Descrição

function imagecopy(
GdImage `$dst_image`,
GdImage `$src_image`,
int `$dst_x`,
int `$dst_y`,
int `$src_x`,
int `$src_y`,
int `$src_width`,
int `$src_height`
): true

Copia uma parte de `src_image` para `dst_image`, começando nas coordenadas x, y `src_x`, `src_y` com uma largura de `src_width` e uma altura de `src_height`. A porção definida será copiada para as coordenadas x, y, `dst_x` e `dst_y`.

### Parâmetros

`dst_image`

  Recurso da imagem de destino.

`src_image`

  Recurso da imagem de origem.

`dst_x`

  Coordenada x do ponto de destino.

`dst_y`

  Coordenada y do ponto de destino.

`src_x`

  Coordenada x do ponto de origem.

`src_y`

  Coordenada y do ponto de origem.

`src_width`

  Largura da imagem de origem.

`src_height`

  Altura da imagem de origem.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `dst_image` e `src_image` esperam instâncias de GdImage; anteriormente, esperavam resource.

### Exemplos

Exemplo #1 Recortando o logotipo do PHP.net

    <?php
    // Criar instâncias de imagens
    $src = imagecreatefromgif('php.gif');
    $dest = imagecreatetruecolor(80, 40);

    // Copiar
    imagecopy($dest, $src, 0, 0, 20, 13, 80, 40);

    // Exibir
    header('Content-Type: image/gif');
    imagegif($dest);
    ?>

O exemplo acima produzirá algo semelhante a:

### Veja Também

- imagecrop() - Recorta uma imagem no retângulo informado

# imagecopymerge

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecopymerge — Copia e funde parte de uma imagem

### Descrição

function imagecopymerge(
GdImage `$dst_image`,
GdImage `$src_image`,
int `$dst_x`,
int `$dst_y`,
int `$src_x`,
int `$src_y`,
int `$src_width`,
int `$src_height`,
int `$pct`
): true

Copia uma parte de `src_image` sobre `dst_image` iniciando nas coordenadas x,y `src_x`, `src_y` com uma largura de `src_width` e uma altura de `src_height`. A porção definida será copiada nas coordenadas x,y, `dst_x` e `dst_y`.

### Parâmetros

`dst_image`

  Recurso da imagem de destino.

`src_image`

  Recurso da imagem de origem.

`dst_x`

  Coordenada x do ponto de destino.

`dst_y`

  Coordenada y do ponto de destino.

`src_x`

  Coordenada x do ponto de origem.

`src_y`

  Coordenada y do ponto de origem.

`src_width`

  Largura da imagem de origem.

`src_height`

  Altura da imagem de origem.

`pct`
  As duas imagens podem ser fundidas de acordo com o parâmetro `pct` que vai de 0 a 100. Quando `pct` = 0, nenhuma ação é tomada, e quando for 100 esta função se comporta de forma idêntica a imagecopy() para imagens de paleta, exceto por ignorar componentes alfa, enquanto implementa transparência alfa para imagens em cores verdadeiras.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `dst_image` e `src_image` esperam instâncias GdImage agora; anteriormente, resources eram esperados.

### Exemplos

Exemplo #1 Funde duas cópias da logomarca PHP.net com 75% de transparência

    <?php
    // Cria instâncias de imagens
    $dest = imagecreatefromgif('php.gif');
    $src = imagecreatefromgif('php.gif');

    // Copia e funde
    imagecopymerge($dest, $src, 10, 10, 0, 0, 100, 47, 75);

    // Mostra
    header('Content-Type: image/gif');
    imagegif($dest);
    ?>

# imagecopymergegray

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecopymergegray — Copia e funde parte de uma imagem com escala de cinza

### Descrição

function imagecopymergegray(
GdImage `$dst_image`,
GdImage `$src_image`,
int `$dst_x`,
int `$dst_y`,
int `$src_x`,
int `$src_y`,
int `$src_width`,
int `$src_height`,
int `$pct`
): true

imagecopymergegray() copia uma parte de `src_image` sobre `dst_image` iniciando nas coordenadas x,y `src_x`, `src_y` com uma largura de `src_width` e uma altura de `src_height`. A porção definida será copiada nas coordenadas x,y, `dst_x` e `dst_y`.

Esta função é idêntica à imagecopymerge() exceto que ao fundir ela preserva a matiz da origem convertendo os pixels de destino para escala de cinza antes da operação de cópia.

### Parâmetros

`dst_image`

  Recurso da imagem de destino.

`src_image`

  Recurso da imagem de origem.

`dst_x`

  Coordenada x do ponto de destino.

`dst_y`

  Coordenada y do ponto de destino.

`src_x`

  Coordenada x do ponto de origem.

`src_y`

  Coordenada y do ponto de origem.

`src_width`

  Largura da imagem de origem.

`src_height`

  Altura da imagem de origem.

`pct`
  O parâmetro `src_image` será alterado para escala de cinza de acordo com `pct`, onde 0 é totalmente em cinza e 100 é sem alteração. Quando `pct` = 100, esta função é idêntica a imagecopy() para imagems de paleta, exceto por ignorar componentes alfa, enquanto implementa transparência alfa para imagens em cores verdadeiras.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `dst_image` e `src_image` esperam instâncias GdImage agora; anteriormente, resources eram esperados.

### Exemplos

Exemplo #1 Uso de imagecopymergegray()

    <?php
    // Cria instâncias de imagens
    $dest = imagecreatefromgif('php.gif');
    $src = imagecreatefromgif('php.gif');

    // Copia e funde - Cinza = 20%
    imagecopymergegray($dest, $src, 10, 10, 0, 0, 100, 47, 20);

    // Mostra
    header('Content-Type: image/gif');
    imagegif($dest);
    ?>

# imagecopyresampled

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecopyresampled — Copia e redimensiona parte de uma imagem com reamostragem

### Descrição

function imagecopyresampled(
GdImage `$dst_image`,
GdImage `$src_image`,
int `$dst_x`,
int `$dst_y`,
int `$src_x`,
int `$src_y`,
int `$dst_width`,
int `$dst_height`,
int `$src_width`,
int `$src_height`
): true

imagecopyresampled() copia uma porção retangular de uma imagem em outra imagem, suavemente interpolando valores de pixels de forma que, em particular, a redução do tamanho de uma imagem ainda retenha bastante clareza.

Em outras palavras, imagecopyresampled() pegará uma área retangular de `src_image`, de largura `src_width` e altura `src_height` na posição (`src_x`,`src_y`), e posicionará esta área em uma outra área retangular de `dst_image`, de largura `dst_width` e altura `dst_height`, na posição (`dst_x`,`dst_y`).

Se as coordenadas de origem e destino e larguras e alturas forem diferentes, um alongamento ou um encolhimento apropriado do fragmento da imagem será realizado. As coordenadas se referem ao canto superior esquerdo. Esta função pode ser usada para copiar regiões dentro da mesma imagem (se `dst_image` for igual a `src_image`) mas se as regiões se sobrepuserem, os resultados serão imprevisíveis.

### Parâmetros

`dst_image`

  Recurso da imagem de destino.

`src_image`

  Recurso da imagem de origem.

`dst_x`

  Coordenada x do ponto de destino.

`dst_y`

  Coordenada y do ponto de destino.

`src_x`

  Coordenada x do ponto de origem.

`src_y`

  Coordenada y do ponto de origem.

`dst_width`

  Largura do destino.

`dst_height`

  Altura do destino.

`src_width`

  Largura da imagem de origem.

`src_height`

  Altura da imagem de origem.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | O tipo de retorno agora é `true`; anteriormente era bool.
8.0.0 | `dst_image` e `src_image` esperam instâncias GdImage agora; anteriormente, resources eram esperadas.

### Exemplos

Exemplo #1 Exemplo simples

Este exemplo irá reamostrar uma imagem para metade de seu tamanho original.

    <?php
    // O arquivo
    $filename = 'test.jpg';
    $percent = 0.5;

    // Tipo de conteúdo
    header('Content-Type: image/jpeg');

    // Obtém novas dimensões
    list($width, $height) = getimagesize($filename);
    $new_width = $width * $percent;
    $new_height = $height * $percent;

    // Reamostra
    $image_p = imagecreatetruecolor($new_width, $new_height);
    $image = imagecreatefromjpeg($filename);
    imagecopyresampled($image_p, $image, 0, 0, 0, 0, $new_width, $new_height, $width, $height);

    // Mostra
    imagejpeg($image_p, null, 100);
    ?>

O exemplo acima produzirá algo semelhante a:

Exemplo #2 Reamostrando uma imagem proporcionalmente

Este exemplo irá mostrar uma imagem com a largura e altura máximas de 200 pixels.

    <?php
    // O arquivo
    $filename = 'test.jpg';

    // Define altura e largura máximas
    $width = 200;
    $height = 200;

    // Tipo de conteúdo
    header('Content-Type: image/jpeg');

    // Obtém novas dimensões
    list($width_orig, $height_orig) = getimagesize($filename);

    $ratio_orig = $width_orig/$height_orig;

    if ($width/$height > $ratio_orig) {
       $width = $height*$ratio_orig;
    } else {
       $height = $width/$ratio_orig;
    }

    // Reamostra
    $image_p = imagecreatetruecolor($width, $height);
    $image = imagecreatefromjpeg($filename);
    imagecopyresampled($image_p, $image, 0, 0, 0, 0, $width, $height, $width_orig, $height_orig);

    // Mostra
    imagejpeg($image_p, null, 100);
    ?>

O exemplo acima produzirá algo semelhante a:

### Notas

> Nota:

> Existe um problema devido a limitações de imagem de paleta (255+1 cores). A reamostragem ou a filtragem de uma imagem normalmente precisa de mais cores que 255, um tipo de aproximação é usada para calcular o novo pixel reamostrado e sua cor. Com imagem de paleta tenta-se alocar uma nova cor, se isso falhar, escolhe-se a cor computada mais próxima (em teoria). Isto nem sempre é a cor mais próxima visualmente. Isto pode produzir um resultado estranho, tal como imagem vazia (ou visualmente vazia). Para evitar esse problema, favor utilizar uma imagem em cores verdadeiras como imagem de destino, tal como a criada por imagecreatetruecolor().

### Veja Também

- imagecopyresized() - Copia e redimensiona parte de uma imagem
- imagescale() - Muda a escala de uma imagem usando largura e altura informadas
- imagecrop() - Recorta uma imagem no retângulo informado

# imagecopyresized

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecopyresized — Copia e redimensiona parte de uma imagem

### Descrição

function imagecopyresized(
GdImage `$dst_image`,
GdImage `$src_image`,
int `$dst_x`,
int `$dst_y`,
int `$src_x`,
int `$src_y`,
int `$dst_width`,
int `$dst_height`,
int `$src_width`,
int `$src_height`
): true

imagecopyresized() copia uma porção retangular de uma imagem para outra imagem. `dst_image` é a imagem de destino, `src_image` é a imagem de origem.

Em outras palavras, imagecopyresized() pegará uma área retangular de `src_image`, de largura `src_width` e altura `src_height` na posição (`src_x`,`src_y`), e posicionará esta área em uma outra área retangular de `dst_image`, de largura `dst_width` e altura `dst_height`, na posição (`dst_x`,`dst_y`).

Se as coordenadas de origem e destino e larguras e alturas forem diferentes, um alongamento ou um encolhimento apropriado do fragmento da imagem será realizado. As coordenadas se referem ao canto superior esquerdo. Esta função pode ser usada para copiar regiões dentro da mesma imagem (se `dst_image` for igual a `src_image`) mas se as regiões se sobrepuserem, os resultados serão imprevisíveis.

### Parâmetros

`dst_image`

  Recurso da imagem de destino.

`src_image`

  Recurso da imagem de origem.

`dst_x`

  Coordenada x do ponto de destino.

`dst_y`

  Coordenada y do ponto de destino.

`src_x`

  Coordenada x do ponto de origem.

`src_y`

  Coordenada y do ponto de origem.

`dst_width`

  Largura do destino.

`dst_height`

  Altura do destino.

`src_width`

  Largura da imagem de origem.

`src_height`

  Altura da imagem de origem.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `dst_image` e `src_image` esperam instâncias GdImage agora; anteriormente, resources eram esperadas.

### Exemplos

Exemplo #1 Redimensionando uma imagem

Este exemplo irá mostrar a imagem com a metade do tamanho.

    <?php
    // Arquivo e novo tamanho
    $filename = 'test.jpg';
    $percent = 0.5;

    // Tipo de conteúdo
    header('Content-Type: image/jpeg');

    // Obtém novos tamanhos
    list($width, $height) = getimagesize($filename);
    $newwidth = $width * $percent;
    $newheight = $height * $percent;

    // Carrega
    $thumb = imagecreatetruecolor($newwidth, $newheight);
    $source = imagecreatefromjpeg($filename);

    // Redimensiona
    imagecopyresized($thumb, $source, 0, 0, 0, 0, $newwidth, $newheight, $width, $height);

    // Mostra
    imagejpeg($thumb);
    ?>

O exemplo acima produzirá algo semelhante a:

A imagem será mostrada com a metade do tamanho, mas uma qualidade melhor poderia ser obtida usando a função imagecopyresampled().

### Notas

> Nota:

> Existe um problema devido a limitações de imagem de paleta (255+1 cores). A reamostragem ou a filtragem de uma imagem normalmente precisa de mais cores que 255, um tipo de aproximação é usada para calcular o novo pixel reamostrado e sua cor. Com imagem de paleta tenta-se alocar uma nova cor, se isso falhar, escolhe-se a cor computada mais próxima (em teoria). Isto nem sempre é a cor mais próxima visualmente. Isto pode produzir um resultado estranho, tal como imagem vazia (ou visualmente vazia). Para evitar esse problema, favor utilizar uma imagem em cores verdadeiras como imagem de destino, tal como a criada por imagecreatetruecolor().

### Veja Também

- imagecopyresampled() - Copia e redimensiona parte de uma imagem com reamostragem
- imagescale() - Muda a escala de uma imagem usando largura e altura informadas
- imagecrop() - Recorta uma imagem no retângulo informado

# imagecreate

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreate — Crie uma nova imagem baseada em paleta

### Descrição

function imagecreate(int `$width`, int `$height`): GdImage|false

imagecreate() retorna um identificador de imagem que representa uma imagem em branco do tamanho especificado.

Em geral, recomendamos o uso de imagecreatetruecolor() em vez de imagecreate() para que o processamento da imagem ocorra na mais alta qualidade possível. Se você deseja gerar uma imagem paletizada, então imagetruecolortopalette() deve ser chamada imediatamente antes de salvar a imagem com imagepng() ou imagegif().

### Parâmetros

`width`

  A largura da imagem.

`height`

  A altura da imagem.

### Valor Retornado

Retorna um objeto de imagem em caso de sucesso, `false` em caso de erros.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Em caso de sucesso, esta função agora retorna uma instância de GDImage; anteriormente, era retornado um resource.

### Exemplos

Exemplo #1 Criando um novo fluxo de imagem GD e exibindo uma imagem.

    <?php
    header("Content-Type: image/png");
    $im = @imagecreate(110, 20)
        or die("Não é possível inicializar um novo fluxo de imagem GD.");
    $background_color = imagecolorallocate($im, 0, 0, 0);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "A Simple Text String", $text_color);
    imagepng($im);
    ?>

O exemplo acima produzirá algo semelhante a:

### Veja Também

- imagecreatetruecolor() - Cria uma nova imagem em cores verdadeiras

# imagecreatefromavif

(PHP 8 >= 8.1.0)

imagecreatefromavif — Cria uma nova imagem a partir de um arquivo ou URL

### Descrição

function imagecreatefromavif(string `$filename`): GdImage|false

imagecreatefromavif() retorna um objeto de imagem representando a imagem obtida pelo nome de arquivo fornecido.

### Parâmetros

`filename`

  Caminho para a imagem rasterizada AVIF.

### Valor Retornado

Retorna um objeto de imagem em caso de sucesso, `false` em caso de erros.

# imagecreatefrombmp

(PHP 7 >= 7.2.0, PHP 8)

imagecreatefrombmp — Cria uma nova imagem a partir de um arquivo ou URL

### Descrição

function imagecreatefrombmp(string `$filename`): GdImage|false

imagecreatefrombmp() retorna um identificador de imagem representando a imagem obtida pelo nome de arquivo fornecido.

Dica

Uma URL pode ser usada como um nome de arquivo com esta função se os empacotadores fopen estiverem habilitados. Consulte a função fopen() para mais detalhes sobre como especificar o nome do arquivo. Consulte os Protocolos e empacotadores suportados para obter links para informações sobre as capacidades de cada empacotador, notas de uso e informações sobre quaisquer variáveis predefinidas que eles possam fornecer.

### Parâmetros

`filename`

  Caminho para a imagem BMP.

### Valor Retornado

Retorna um objeto de imagem em caso de sucesso, `false` em caso de erros.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Em caso de sucesso, esta função agora retorna um objeto GDImage; anteriormente, um resource era retornado.

### Exemplos

Exemplo #1 Converte uma imagem BMP para PNG usando imagecreatefrombmp()

    <?php
    // Carrega o arquivo BMP
    $im = imagecreatefrombmp('./example.bmp');

    // Converte para um PNG com a configuração padrão
    imagepng($im, './example.png');
    ?>

# imagecreatefromgd

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagecreatefromgd — Cria uma nova imagem a partir de um arquivo GD ou URL

### Descrição

function imagecreatefromgd(string `$filename`): GdImage|false

Cria uma nova imagem a partir de um arquivo GD ou URL.

Dica

Uma URL pode ser usada como um nome de arquivo com esta função se os empacotadores fopen estiverem habilitados. Consulte a função fopen() para mais detalhes sobre como especificar o nome do arquivo. Consulte os Protocolos e empacotadores suportados para obter links para informações sobre as capacidades de cada empacotador, notas de uso e informações sobre quaisquer variáveis predefinidas que eles possam fornecer.

### Parâmetros

`filename`

  Caminho para o arquivo GD.

### Valor Retornado

Retorna um objeto de imagem em caso de sucesso, `false` em caso de erros.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Em caso de sucesso, esta função agora retorna uma instância de GDImage; anteriormente, era retornado um resource.

### Exemplos

Exemplo #1 Exemplo de imagecreatefromgd()

    <?php
    // Carregar a imagem GD
    $im = @imagecreatefromgd('./test.gd');

    // Testa se a imagem foi carregada
    if(!$im)
    {
         die('Incapaz de carregar a imagem GD!');
    }

    // Realiza operações na imagem aqui

    // Salva a imagem
    imagegd($im, './test_updated.gd');
    ?>

### Notas

Aviso

Os formatos de imagem GD e GD2 são formatos de imagem proprietários da biblioteca libgd. Eles devem ser considerados obsoletos e só devem ser usados para propósitos de desenvolvimento e testes.

# imagecreatefromgd2

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagecreatefromgd2 — Cria uma nova imagem a partir de um arquivo GD2 ou URL

### Descrição

function imagecreatefromgd2(string `$filename`): GdImage|false

Cria uma nova imagem a partir de um arquivo GD2 ou URL.

Dica

Uma URL pode ser usada como um nome de arquivo com esta função se os empacotadores fopen estiverem habilitados. Consulte a função fopen() para mais detalhes sobre como especificar o nome do arquivo. Consulte os Protocolos e empacotadores suportados para obter links para informações sobre as capacidades de cada empacotador, notas de uso e informações sobre quaisquer variáveis predefinidas que eles possam fornecer.

### Parâmetros

`filename`

  Caminho para o arquivo GD2.

### Valor Retornado

Retorna um objeto de imagem em caso de sucesso, `false` em caso de erros.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Em caso de sucesso, esta função agora retorna uma instância de GDImage; anteriormente, era retornado um resource.

### Exemplos

Exemplo #1 Exemplo de imagecreatefromgd2()

    <?php
    // Carregar a imagem GD2
    $im = imagecreatefromgd2('./test.gd2');

    // Aplica um efeito, neste caso
    // aplica um filtro que negativa a imagem
    if(function_exists('imagefilter'))
    {
        imagefilter($im, IMG_FILTER_NEGATE);
    }

    // Grava a imagem
    imagegd2($im, './test_updated.gd2');
    ?>

### Notas

Aviso

Os formatos de imagem GD e GD2 são formatos de imagem proprietários da biblioteca libgd. Eles devem ser considerados obsoletos e só devem ser usados para propósitos de desenvolvimento e testes.

# imagecreatefromgd2part

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagecreatefromgd2part — Cria uma nova imagem a partir de uma parte de um arquivo GD2 ou URL

### Descrição

function imagecreatefromgd2part(
string `$filename`,
int `$x`,
int `$y`,
int `$width`,
int `$height`
): GdImage|false

Cria uma nova imagem a partir de uma parte de um arquivo GD2 ou URL.

Dica

Uma URL pode ser usada como um nome de arquivo com esta função se os empacotadores fopen estiverem habilitados. Consulte a função fopen() para mais detalhes sobre como especificar o nome do arquivo. Consulte os Protocolos e empacotadores suportados para obter links para informações sobre as capacidades de cada empacotador, notas de uso e informações sobre quaisquer variáveis predefinidas que eles possam fornecer.

### Parâmetros

`filename`

  Caminho para a imagem GD2.

`x`

  Coordenada x do ponto de origem.

`y`

  Coordenada y do ponto de origem.

`width`

  Largura da imagem de origem.

`height`

  Altura da imagem de origem.

### Valor Retornado

Retorna um objeto de imagem em caso de sucesso, `false` em caso de erros.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Em caso de sucesso, esta função agora retorna um objeto GDImage; anteriormente, um resource era retornado.

### Exemplos

Exemplo #1 Exemplo de imagecreatefromgd2part()

    <?php
    // Para este exemplo é necessário obter antes o tamanho da imagem
    $image = getimagesize('./test.gd2');

    // Cria a instância de imagem agora que já foi obtido o tamanho
    // da imagem
    $im = imagecreatefromgd2part('./test.gd2', 4, 4, ($image[0] / 2) - 6, ($image[1] / 2) - 6);

    // Faz uma operação, neste caso transforma a imagem em alto relevo
    if(function_exists('imagefilter'))
    {
        imagefilter($im, IMG_FILTER_EMBOSS);
    }

    // Grava a imagem transformada
    imagegd2($im, './test_emboss.gd2');
    ?>

### Notas

Aviso

Os formatos de imagem GD e GD2 são formatos de imagem proprietários da biblioteca libgd. Eles devem ser considerados obsoletos e só devem ser usados para propósitos de desenvolvimento e testes.

# imagecreatefromgif

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreatefromgif — Cria uma nova imagem a partir de um arquivo ou URL

### Descrição

function imagecreatefromgif(string `$filename`): GdImage|false

imagecreatefromgif() retorna um identificador de imagem representando a imagem obtida a partir do arquivo informado.

Cuidado

Ao carregar arquivos GIF na memória, apenas o primeiro quadro é retornado ao objeto da imagem. O tamanho da imagem não é necessariamente o reportado por getimagesize().

Dica

Uma URL pode ser usada como um nome de arquivo com esta função se os empacotadores fopen estiverem habilitados. Consulte a função fopen() para mais detalhes sobre como especificar o nome do arquivo. Consulte os Protocolos e empacotadores suportados para obter links para informações sobre as capacidades de cada empacotador, notas de uso e informações sobre quaisquer variáveis predefinidas que eles possam fornecer.

### Parâmetros

`filename`

  Caminho para a imagem GIF.

### Valor Retornado

Retorna um objeto de imagem em caso de sucesso, `false` em caso de erros.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Em caso de sucesso, esta função agora retorna um objeto GDImage; anteriormente, um resource era retornado.

### Exemplos

Exemplo #1 Exemplo de gerenciamento de erro durante carregamento de um GIF

    <?php
    function LoadGif($imgname)
    {
        /* Tenta abrir */
        $im = @imagecreatefromgif($imgname);

        /* Ver se falhou */
        if(!$im)
        {
            /* Cria uma imagem vazia */
            $im = imagecreatetruecolor (150, 30);
            $bgc = imagecolorallocate ($im, 255, 255, 255);
            $tc = imagecolorallocate ($im, 0, 0, 0);

            imagefilledrectangle ($im, 0, 0, 150, 30, $bgc);

            /* Mostra uma mensagem de erro */
            imagestring ($im, 1, 5, 5, 'Error loading ' . $imgname, $tc);
        }

        return $im;
    }

    header('Content-Type: image/gif');

    $img = LoadGif('bogus.image');

    imagegif($img);
    ?>

O exemplo acima produzirá algo semelhante a:

# imagecreatefromjpeg

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreatefromjpeg — Cria uma nova imagem a partir de um arquivo ou URL

### Descrição

function imagecreatefromjpeg(string `$filename`): GdImage|false

imagecreatefromjpeg() retorna um identificador de imagem que representa a imagem obtida a partir do nome de arquivo fornecido.

Dica

Uma URL pode ser usada como um nome de arquivo com esta função se os empacotadores fopen estiverem habilitados. Consulte a função fopen() para mais detalhes sobre como especificar o nome do arquivo. Consulte os Protocolos e empacotadores suportados para obter links para informações sobre as capacidades de cada empacotador, notas de uso e informações sobre quaisquer variáveis predefinidas que eles possam fornecer.

### Parâmetros

`filename`

  Caminho para a imagem JPEG.

### Valor Retornado

Retorna um objeto de imagem em caso de sucesso, `false` em caso de erros.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Caso for sucesso, esta função agora retorna uma instância de GDImage; anteriormente, era retornado um resource.

### Exemplos

Exemplo #1 Exemplo de como lidar com um erro durante o carregamento de uma imagem JPEG.

    <?php
    function LoadJpeg($imgname)
    {
        /* Tentativa de abrir */
        $im = @imagecreatefromjpeg($imgname);

        /* Verificar se falhou */
        if(!$im)
        {
            /* Crie uma imagem preta */
            $im  = imagecreatetruecolor(150, 30);
            $bgc = imagecolorallocate($im, 255, 255, 255);
            $tc  = imagecolorallocate($im, 0, 0, 0);

            imagefilledrectangle($im, 0, 0, 150, 30, $bgc);

            /* Exibir uma mensagem de erro */
            imagestring($im, 1, 5, 5, 'Erro ao carregar ' . $imgname, $tc);
        }

        return $im;
    }

    header('Content-Type: image/jpeg');

    $img = LoadJpeg('bogus.image');

    imagejpeg($img);
    ?>

O exemplo acima produzirá algo semelhante a:

# imagecreatefrompng

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreatefrompng — Cria uma nova imagem a partir de um arquivo ou URL

### Descrição

function imagecreatefrompng(string `$filename`): GdImage|false

imagecreatefrompng() retorna um identificador de imagem que representa a imagem obtida a partir do nome de arquivo fornecido.

Dica

Uma URL pode ser usada como um nome de arquivo com esta função se os empacotadores fopen estiverem habilitados. Consulte a função fopen() para mais detalhes sobre como especificar o nome do arquivo. Consulte os Protocolos e empacotadores suportados para obter links para informações sobre as capacidades de cada empacotador, notas de uso e informações sobre quaisquer variáveis predefinidas que eles possam fornecer.

### Parâmetros

`filename`

  Caminho para a imagem PNG

### Valor Retornado

Retorna um objeto de imagem em caso de sucesso, `false` em caso de erros.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Caso for sucesso, esta função agora retorna uma instância de GDImage; anteriormente, era retornado um resource.

### Exemplos

Exemplo #1 Exemplo de como lidar com um erro durante o carregamento de uma imagem PNG

    <?php
    function LoadPNG($imgname)
    {
        /* Tentativa de abrir */
        $im = @imagecreatefrompng($imgname);

        /* Verificar se falhou */
        if(!$im)
        {
            /* Crie uma imagem em branco */
            $im  = imagecreatetruecolor(150, 30);
            $bgc = imagecolorallocate($im, 255, 255, 255);
            $tc  = imagecolorallocate($im, 0, 0, 0);

            imagefilledrectangle($im, 0, 0, 150, 30, $bgc);

            /* Output an error message */
            imagestring($im, 1, 5, 5, 'Erro ao carregar ' . $imgname, $tc);
        }

        return $im;
    }

    header('Content-Type: image/png');

    $img = LoadPNG('bogus.image');

    imagepng($img);
    ?>

O exemplo acima produzirá algo semelhante a:

# imagecreatefromstring

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

imagecreatefromstring — Cria uma nova imagem a partir de um fluxo de imagem na string

### Descrição

function imagecreatefromstring(string `$data`): GdImage|false

imagecreatefromstring() retorna um identificador de imagem representando a imagem obtida pelos dados informados no parâmetro `data`. Estes tipos serão automaticamente detectados se a compilação do PHP suportá-los: JPEG, PNG, GIF, BMP, WBMP, GD2, WEBP e AVIF.

### Parâmetros

`data`

  Uma string contendo os dados da imagem.

### Valor Retornado

Um objeto de imagem será retornado em caso de sucesso. `false` é retornado se o tipo da imagem não for suportado, se os dados não estiverem em formato reconhecido, ou se a imagem estiver corrompida e não puder ser carregada.

### Erros/Exceções

imagecreatefromstring() emite um erro de nível E_WARNING, se os dados não estiverem em um formato reconhecido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Em caso de sucesso, esta função retorna agora uma instância de GDImage; anteriormente, retornava um resource.
7.3.0 | WEBP agora é suportado (caso seja suportado pela libgd em uso).

### Exemplos

Exemplo #1 Exemplo de imagecreatefromstring()

    <?php
    $data = 'iVBORw0KGgoAAAANSUhEUgAAABwAAAASCAMAAAB/2U7WAAAABl'
           . 'BMVEUAAAD///+l2Z/dAAAASUlEQVR4XqWQUQoAIAxC2/0vXZDr'
           . 'EX4IJTRkb7lobNUStXsB0jIXIAMSsQnWlsV+wULF4Avk9fLq2r'
           . '8a5HSE35Q3eO2XP1A1wQkZSgETvDtKdQAAAABJRU5ErkJggg==';
    $data = base64_decode($data);

    $im = imagecreatefromstring($data);
    if ($im !== false) {
        header('Content-Type: image/png');
        imagepng($im);
    }
    else {
        echo 'Ocorreu um erro.';
    }
    ?>

O exemplo acima produzirá algo semelhante a:

### Veja Também

- imagecreatefromjpeg() - Cria uma nova imagem a partir de um arquivo ou URL
- imagecreatefrompng() - Cria uma nova imagem a partir de um arquivo ou URL
- imagecreatefromgif() - Cria uma nova imagem a partir de um arquivo ou URL
- imagecreatetruecolor() - Cria uma nova imagem em cores verdadeiras

# imagecreatefromtga

(PHP 7 >= 7.4.0, PHP 8)

imagecreatefromtga — Cria uma nova imagem a partir de um arquivo ou URL

### Descrição

function imagecreatefromtga(string `$filename`): GdImage|false

imagecreatefromtga() retorna um identificador de imagem representando a imagem obtida a partir do arquivo informado.

### Parâmetros

`filename`

  Caminho para a imagem Truevision TGA.

### Valor Retornado

Retorna um objeto de imagem em caso de sucesso, `false` em caso de erros.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Em caso de sucesso, esta função agora retorna um objeto GDImage; anteriormente, um resource era retornado.

# imagecreatefromwbmp

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecreatefromwbmp — Cria uma nova imagem a partir de um arquivo ou URL

### Descrição

function imagecreatefromwbmp(string `$filename`): GdImage|false

imagecreatefromwbmp() retorna um identificador de imagem representando a imagem obtida a partir do arquivo informado.

> Nota: Imagen WBMP é um Bitmap "Wireless", e não um Bitmap do Windows. Este último pode ser carregado com imagecreatefrombmp().

Dica

Uma URL pode ser usada como um nome de arquivo com esta função se os empacotadores fopen estiverem habilitados. Consulte a função fopen() para mais detalhes sobre como especificar o nome do arquivo. Consulte os Protocolos e empacotadores suportados para obter links para informações sobre as capacidades de cada empacotador, notas de uso e informações sobre quaisquer variáveis predefinidas que eles possam fornecer.

### Parâmetros

`filename`

  Caminho para a imagem WBMP.

### Valor Retornado

Retorna um objeto de imagem em caso de sucesso, `false` em caso de erros.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Em caso de sucesso, esta função agora retorna um objeto GDImage; anteriormente, um resource era retornado.

### Exemplos

Exemplo #1 Exemplo de gerenciamento de erro ao carregar um WBMP

    <?php
    function LoadWBMP($imgname)
    {
        /* Tenta abrir */
        $im = @imagecreatefromwbmp($imgname);

        /* Vê se falhou */
        if(!$im)
        {
            /* Cria uma imagem vazia */
            $im  = imagecreatetruecolor(150, 30);
            $bgc = imagecolorallocate($im, 255, 255, 255);
            $tc  = imagecolorallocate($im, 0, 0, 0);

            imagefilledrectangle($im, 0, 0, 150, 30, $bgc);

            /* Mostra mensagem de erro */
            imagestring($im, 1, 5, 5, 'Error loading ' . $imgname, $tc);
        }

        return $im;
    }

    header('Content-Type: image/vnd.wap.wbmp');

    $img = LoadWBMP('bogus.image');

    imagewbmp($img);
    ?>

# imagecreatefromwebp

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

imagecreatefromwebp — Cria uma nova imagem a partir de um arquivo ou URL

### Descrição

function imagecreatefromwebp(string `$filename`): GdImage|false

imagecreatefromwebp() retorna um identificador de imagem representando a imagem obtida a partir do arquivo informado. Observe que arquivos WebP animados não podem ser lidos.

Dica

Uma URL pode ser usada como um nome de arquivo com esta função se os empacotadores fopen estiverem habilitados. Consulte a função fopen() para mais detalhes sobre como especificar o nome do arquivo. Consulte os Protocolos e empacotadores suportados para obter links para informações sobre as capacidades de cada empacotador, notas de uso e informações sobre quaisquer variáveis predefinidas que eles possam fornecer.

### Parâmetros

`filename`

  Caminho para a imagem WebP.

### Valor Retornado

Retorna um objeto de imagem em caso de sucesso, `false` em caso de erros.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Em caso de sucesso, esta função agora retorna um objeto GDImage; anteriormente, um resource era retornado.

### Exemplos

Exemplo #1 Converte uma imagem WebP para jpeg usando imagecreatefromwebp()

    <?php
    // Carrega o arquivo WebP
    $im = imagecreatefromwebp('./example.webp');

    // Converte para um jpeg com 100% de qualidade
    imagejpeg($im, './example.jpeg', 100);
    ?>

# imagecreatefromxbm

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecreatefromxbm — Cria uma nova imagem a partir de um arquivo ou URL

### Descrição

function imagecreatefromxbm(string `$filename`): GdImage|false

imagecreatefromxbm() retorna um identificador de imagem representando a imagem obtida a partir do arquivo informado.

Dica

Uma URL pode ser usada como um nome de arquivo com esta função se os empacotadores fopen estiverem habilitados. Consulte a função fopen() para mais detalhes sobre como especificar o nome do arquivo. Consulte os Protocolos e empacotadores suportados para obter links para informações sobre as capacidades de cada empacotador, notas de uso e informações sobre quaisquer variáveis predefinidas que eles possam fornecer.

### Parâmetros

`filename`

  Caminho para a imagem XBM.

### Valor Retornado

Retorna um objeto de imagem em caso de sucesso, `false` em caso de erros.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Em caso de sucesso, esta função agora retorna um objeto GDImage; anteriormente, um resource era retornado.

### Exemplos

Exemplo #1 Converte uma imagem XBM para um png usando imagecreatefromxbm()

    <?php
    // Carrega o arquivo xbm
    $xbm = imagecreatefromxbm('./example.xbm');

    // Converte para um arquivo png
    imagepng($xbm, './example.png');
    ?>

# imagecreatefromxpm

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecreatefromxpm — Cria uma nova imagem a partir de um arquivo ou URL

### Descrição

function imagecreatefromxpm(string `$filename`): GdImage|false

imagecreatefromxpm() retorna um identificador de imagem representando a imagem obtida a partir do arquivo informado.

Dica

Uma URL pode ser usada como um nome de arquivo com esta função se os empacotadores fopen estiverem habilitados. Consulte a função fopen() para mais detalhes sobre como especificar o nome do arquivo. Consulte os Protocolos e empacotadores suportados para obter links para informações sobre as capacidades de cada empacotador, notas de uso e informações sobre quaisquer variáveis predefinidas que eles possam fornecer.

### Parâmetros

`filename`

  Caminho para a imagem XPM.

### Valor Retornado

Retorna um objeto de imagem em caso de sucesso, `false` em caso de erros.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Em caso de sucesso, esta função agora retorna um objeto GDImage; anteriormente, um resource era retornado.

### Exemplos

Exemplo #1 Cria uma instância de imagem usando imagecreatefromxpm()

    <?php
    // Verifica se existe suporte para XPM
    if(!(imagetypes() & IMG_XPM))
    {
        die('Suporte para xpm não encontrado!');
    }

    // Cria a instância da imagem
    $xpm = imagecreatefromxpm('./example.xpm');

    // Aqui são feitas as operações na imagem

    // PHP não tem suporte para gravar imagens xpm
    // portanto neste caso uma imagem jpeg é
    // gravada com 100% de qualidade
    imagejpeg($xpm, './example.jpg', 100);
    ?>

# imagecreatetruecolor

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecreatetruecolor — Cria uma nova imagem em cores verdadeiras

### Descrição

function imagecreatetruecolor(int `$width`, int `$height`): GdImage|false

imagecreatetruecolor() retorna um objeto de imagem representando uma imagem em preto do tamanho especificado.

### Parâmetros

`width`

  Largura da imagem.

`height`

  Altura da imagem.

### Valor Retornado

Retorna um objeto de imagem em caso de sucesso, `false` em caso de erros.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Em caso de sucesso, esta função agora retorna um objeto GDImage; anteriormente, um resource era retornado.

### Exemplos

Exemplo #1 Criando uma novo fluxo de imagem GD e mostrando uma imagem.

    <?php
    header ('Content-Type: image/png');
    $im = @imagecreatetruecolor(120, 20)
          or die('Não foi possível inicializar um novo fluxo de imagem');
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);
    imagepng($im);
    ?>

O exemplo acima produzirá algo semelhante a:

### Veja Também

- imagecreate() - Crie uma nova imagem baseada em paleta

# imagecrop

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagecrop — Recorta uma imagem no retângulo informado

### Descrição

function imagecrop(GdImage `$image`, array `$rectangle`): GdImage|false

Recorta uma imagem na área retangular informada e retorna a imagem resultante. A imagem fornecida em `image` não é modificada.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`rectangle`

  O retângulo de recorte com um array com chaves `x`, `y`, `width` e `height`.

### Valor Retornado

Retorna o objeto da imagem recortada em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.
8.0.0 | Em caso de sucesso, esta função agora retorna um objeto GDImage; anteriormente, um resource era retornado.

### Exemplos

Exemplo #1 Exemplo de imagecrop()

Este exemplo mostra como recortar uma imagem em uma área quadrada.

    <?php
    $im = imagecreatefrompng('example.png');
    $size = min(imagesx($im), imagesy($im));
    $im2 = imagecrop($im, ['x' => 0, 'y' => 0, 'width' => $size, 'height' => $size]);
    if ($im2 !== FALSE) {
        imagepng($im2, 'example-cropped.png');
    }
    ?>

### Veja Também

- imagecropauto() - Recorta uma imagem automaticamente usando um dos modos disponíveis

# imagecropauto

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagecropauto — Recorta uma imagem automaticamente usando um dos modos disponíveis

### Descrição

function imagecropauto(
GdImage `$image`,
int `$mode` = `IMG_CROP_DEFAULT`,
float `$threshold` = 0.5,
int `$color` = -1
): GdImage|false

Automaticamente recorta uma imagem de acordo com o modo informado no parâmetro `mode`.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`mode`

  Uma das constantes a seguir:

  `IMG_CROP_DEFAULT`
    O mesmo que `IMG_CROP_TRANSPARENT`. Antes do PHP 7.4.0, a libgd fornecida retrocedia para `IMG_CROP_SIDES`, se a imagem não tivesse cor transparente.
  `IMG_CROP_TRANSPARENT`
    Corta um plano de fundo transparente.
  `IMG_CROP_BLACK`
    Corta um plano de fundo preto.
  `IMG_CROP_WHITE`
    Corta um plano de fundo branco.
  `IMG_CROP_SIDES`
    Usa os 4 cantos da imagem para tentar detectar o plano de fundo a ser cortado.
  `IMG_CROP_THRESHOLD`
    Corta uma imagem usando os parâmetros `threshold` e `color` fornecidos.
`threshold`

  Especifica a tolerância em percentagem que será usada ao comparar a cor da imagem com a cor a ser cortada. O método usado para calcular a diferença de cor é baseado na distância de cores no cubo RGB(a).

  Usado somente no modo `IMG_CROP_THRESHOLD`.

  > Nota: Antes do PHP 7.4.0, a libgd fornecida usava um algotitmo ligeiramente diferente, por isso o mesmo `threshold` gerava resultados diferentes para a libgd de sistema e a fornecida.

`color`

  Um valor de cor RGB ou um índice de paleta.

  Usado somente no modo `IMG_CROP_THRESHOLD`.

### Valor Retornado

Retorna um objeto de imagem cortada em caso de sucesso ou `false` em caso de falha. `false` também é retornado se a imagem for inteiramente cortada.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.
8.0.0 | Em caso de sucesso, esta função agora retorna um objeto GDImage; anteriormente, um resource era retornado.
7.4.0 | O comportamento de imagecropauto() na libgd fornecida foi sincronizado com o da libgd de sistema: `IMG_CROP_DEFAULT` não mais retrocede para `IMG_CROP_SIDES` e o recorte de limites agora usa o mesmo algoritmo da libgd de sistema.
7.4.0 | O valor padrão de `mode` mudou para `IMG_CROP_AUTO`. Anteriormente, o valor padrão era `-1` que corresponde a `IMG_CROP_DEFAULT`, mas passar `-1` agora foi descontinuado.

### Exemplos

Exemplo #1 Gerenciamento adequado de auto-recorte

Como percebido na seção de valores de retorno, imagecropauto() retorna `false` se a imagem inteira foi recortada. Neste exemplo será trabalho o objeto de imagem `$im` que deve ser automaticamente recortado somente se houver algo a ser recortado; caso contrário será mantida a imagem original.

    <?php
    $cropped = imagecropauto($im, IMG_CROP_DEFAULT);
    if ($cropped !== false) { // caso um novo objeto de imagem tenha sido retornado
        $im = $cropped;       // a imagem recortada é atribuída a $im
    }
    ?>

### Veja Também

- imagecrop() - Recorta uma imagem no retângulo informado

# imagedashedline

(PHP 4, PHP 5, PHP 7, PHP 8)

imagedashedline — Desenha uma linha tracejada

### Descrição

function imagedashedline(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`,
int `$color`
): true

Esta função foi descontinuada. Use uma combinação de imagesetstyle() e imageline() em seu lugar. 0, 0 é o canto superior esquerdo da imagem.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`x1`

  Coordenada x do primeiro ponto.

`y1`

  Coordenada y do primeiro ponto.

`x2`

  Coordenada x do segundo ponto.

`y2`

  Coordenada y do segundo ponto.

`color`

  A cor de preenchimento. Um identificador de cor criado com imagecolorallocate().

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imagedashedline()

    <?php
    // Cria uma imagem 100x100
    $im = imagecreatetruecolor(100, 100);
    $white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);

    // Desenha uma linha tracejada vertical
    imagedashedline($im, 50, 25, 50, 75, $white);

    // Grava a imagem
    imagepng($im, './dashedline.png');
    ?>

O exemplo acima produzirá algo semelhante a:

Exemplo #2 Alternativa a imagedashedline()

    <?php
    // Cria uma imagem 100x100
    $im = imagecreatetruecolor(100, 100);
    $white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);

    // Define o estilo: primeiros 4 pixels brancos e os 4
    // seguintes transparentes. Isto cria o efeito tracejado.
    $style = Array(
                    $white,
                    $white,
                    $white,
                    $white,
                    IMG_COLOR_TRANSPARENT,
                    IMG_COLOR_TRANSPARENT,
                    IMG_COLOR_TRANSPARENT,
                    IMG_COLOR_TRANSPARENT
                    );

    imagesetstyle($im, $style);

    // Desenha a linha tracejada
    imageline($im, 50, 25, 50, 75, IMG_COLOR_STYLED);

    // Grava a imagem
    imagepng($im, './imageline.png');
    ?>

### Veja Também

- imagesetstyle() - Define o estilo para desenho de linhas
- imageline() - Desenha uma linha

# imagedestroy

(PHP 4, PHP 5, PHP 7, PHP 8)

imagedestroy — Destrói uma imagem

Aviso

Esta função foi DESCONTINUADA a partir do PHP 8.5.0. O uso desta função é fortemente desencorajado.

### Descrição

#[\Deprecated]
function imagedestroy(GdImage `$image`): true

> Nota: Esta função não tem efeito. Antes do PHP 8.0.0, esta função era usada para fechar o recurso.

Antes do PHP 8.0.0, a função imagedestroy() liberava qualquer memória associada ao recurso do parâmetro `image`. A partir do PHP 8.0.0, a extensão GD usa objetos no lugar de recursos, e objetos não podem ser fechados explicitamente.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.5.0 | Esta função foi descontinuada.
8.0.0 | Essa função é um NOP agora.
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Usando imagedestroy() antes do PHP 8.0.0

    <?php
    // criar uma imagem de 100 x 100 pixels
    $im = imagecreatetruecolor(100, 100);

    // alterar ou salvar a imagem

    // libera a imagem da memória
    imagedestroy($im);
    ?>

# imageellipse

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imageellipse — Desenha uma elipse

### Descrição

function imageellipse(
GdImage `$image`,
int `$center_x`,
int `$center_y`,
int `$width`,
int `$height`,
int `$color`
): true

Desenha uma elipse centrada nas coordenadas especificadas.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`center_x`

  Coordenada x do centro.

`center_y`

  Coordenada y do centro.

`width`

  Largura da elipse.

`height`

  Altura da elipse.

`color`

  Cor da elipse. Um identificador de cor criado com imagecolorallocate().

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imageellipse()

    <?php

    // Cria uma imagem vazia.
    $image = imagecreatetruecolor(400, 300);

    // Seleciona a cor de fundo.
    $bg = imagecolorallocate($image, 0, 0, 0);

    // Preenche o fundo com a cor selecionada acima.
    imagefill($image, 0, 0, $bg);

    // Escolhe uma cor para a elipse.
    $col_ellipse = imagecolorallocate($image, 255, 255, 255);

    // Desenha a elipse.
    imageellipse($image, 200, 150, 300, 200, $col_ellipse);

    // Mostra a imagem.
    header("Content-type: image/png");
    imagepng($image);

    ?>

O exemplo acima produzirá algo semelhante a:

### Notas

> Nota:

> imageellipse() ignora imagesetthickness().

### Veja Também

- imagefilledellipse() - Desenha uma elipse preenchida
- imagearc() - Desenha um arco

# imagefill

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefill — Preenchimento

### Descrição

function imagefill(
GdImage `$image`,
int `$x`,
int `$y`,
int `$color`
): true

Esta função realiza um preenchimento iniciando na coordenada fornecida (canto superior esquerdo é 0, 0) com a cor especificada em `color`, na imagem `image`.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`x`

  Coordenada x do ponto de partida.

`y`

  Coordenada y do ponto de partida.

`color`

  A cor de preenchimento. Um identificador de cor criado com imagecolorallocate().

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imagefill()

    <?php

    $im = imagecreatetruecolor(100, 100);

    // define o fundo vermelho
    $red = imagecolorallocate($im, 255, 0, 0);
    imagefill($im, 0, 0, $red);

    header('Content-type: image/png');
    imagepng($im);
    ?>

O exemplo acima produzirá algo semelhante a:

### Veja Também

- imagecolorallocate() - Aloca uma cor para uma imagem

# imagefilledarc

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagefilledarc — Desenha um arco parcial preenchido

### Descrição

function imagefilledarc(
GdImage `$image`,
int `$center_x`,
int `$center_y`,
int `$width`,
int `$height`,
int `$start_angle`,
int `$end_angle`,
int `$color`,
int `$style`
): true

Desenha um arco parcial centrado na coordenada especificada na imagem fornecida em `image`.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`center_x`

  Coordenada x do centro.

`center_y`

  Coordenada y do centro.

`width`

  Largura do arco.

`height`

  Altura do arco.

`start_angle`

  O ângulo inicial do arco, em graus.

`end_angle`

  O ângulo final do arco, em graus. 0° está localizado na posição 3 horas do relógio, e o arco é desenhado no sentido horário.

`color`

  Um identificador de cor criado com imagecolorallocate().

`style`

  Um OR binário das seguinte possibilidades:

  1. `IMG_ARC_PIE`
  2. `IMG_ARC_CHORD`
  3. `IMG_ARC_NOFILL`
  4. `IMG_ARC_EDGED`
  `IMG_ARC_PIE` e `IMG_ARC_CHORD` são mutualmente exclusivas; `IMG_ARC_CHORD` apenas conecta os ângulos inicial e final com uma linha reta, enquanto que `IMG_ARC_PIE` produz uma borda arredondada. `IMG_ARC_NOFILL` indica que o arco ou corda devem ser contornados, não preenchidos. `IMG_ARC_EDGED`, usado em conjunto com `IMG_ARC_NOFILL`, indica que o ângulo inicial e o final devem ser conectados ao centro - é uma boa forma de se contornar (em vez de preencher) uma 'fatia de pizza'.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Criando uma pizza em 3D

    <?php

    // cria a imagem
    $image = imagecreatetruecolor(100, 100);

    // aloca algumas cores
    $white    = imagecolorallocate($image, 0xFF, 0xFF, 0xFF);
    $gray     = imagecolorallocate($image, 0xC0, 0xC0, 0xC0);
    $darkgray = imagecolorallocate($image, 0x90, 0x90, 0x90);
    $navy     = imagecolorallocate($image, 0x00, 0x00, 0x80);
    $darknavy = imagecolorallocate($image, 0x00, 0x00, 0x50);
    $red      = imagecolorallocate($image, 0xFF, 0x00, 0x00);
    $darkred  = imagecolorallocate($image, 0x90, 0x00, 0x00);

    // faz o efeito 3D
    for ($i = 60; $i > 50; $i--) {
       imagefilledarc($image, 50, $i, 100, 50, 0, 45, $darknavy, IMG_ARC_PIE);
       imagefilledarc($image, 50, $i, 100, 50, 45, 75 , $darkgray, IMG_ARC_PIE);
       imagefilledarc($image, 50, $i, 100, 50, 75, 360 , $darkred, IMG_ARC_PIE);
    }

    imagefilledarc($image, 50, 50, 100, 50, 0, 45, $navy, IMG_ARC_PIE);
    imagefilledarc($image, 50, 50, 100, 50, 45, 75 , $gray, IMG_ARC_PIE);
    imagefilledarc($image, 50, 50, 100, 50, 75, 360 , $red, IMG_ARC_PIE);

    // descarrega a imagem
    header('Content-type: image/png');
    imagepng($image);
    ?>

O exemplo acima produzirá algo semelhante a:

# imagefilledellipse

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagefilledellipse — Desenha uma elipse preenchida

### Descrição

function imagefilledellipse(
GdImage `$image`,
int `$center_x`,
int `$center_y`,
int `$width`,
int `$height`,
int `$color`
): true

Desenha uma elipse centrada nas coordenadas especificadas na imagem informada em `image`.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`center_x`

  Coordenada x do centro da elipse.

`center_y`

  Coordenada y do centro da elipse.

`width`

  Largura da elipse.

`height`

  Altura da elipse.

`color`

  Cor de preenchimento. Um identificador de cor criado com imagecolorallocate().

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imagefilledellipse()

    <?php

    // cria uma imagem vazia
    $image = imagecreatetruecolor(400, 300);

    // preenche a cor de fundo
    $bg = imagecolorallocate($image, 0, 0, 0);

    // escolhe uma cor para a elipse
    $col_ellipse = imagecolorallocate($image, 255, 255, 255);

    // desenha a elipse branca
    imagefilledellipse($image, 200, 150, 300, 200, $col_ellipse);

    // mostra a figura
    header("Content-type: image/png");
    imagepng($image);

    ?>

O exemplo acima produzirá algo semelhante a:

### Notas

> Nota:

> imagefilledellipse() ignora imagesetthickness().

### Veja Também

- imageellipse() - Desenha uma elipse
- imagefilledarc() - Desenha um arco parcial preenchido

# imagefilledpolygon

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefilledpolygon — Desenha um polígono preenchido

### Descrição

Assinatura a partir do PHP 8.0.0 (sem suporte a argumentos com nome)

function imagefilledpolygon(GdImage `$image`, array `$points`, int `$color`): bool

Assinatura alternativa (descontinuada a partir do PHP 8.1.0)

function imagefilledpolygon(
GdImage `$image`,
array `$points`,
int `$num_points`,
int `$color`
): bool

imagefilledpolygon() cria um polígono preenchido na imagem fornecida em `image`.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`points`

  Um array contendo as coordenadas `x` e `y` dos vértices consecutivos do polígono.

`num_points`

  Número total de pontos (vértices), que devem ser pelo menos 3.

  Se este parâmetro for omitido na segunda assinatura, `points` deve ter um número par de elementos, e `num_points` será assumido como `count($points)/2`.
`color`

  Um identificador de cor criado com imagecolorallocate().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `num_points` foi descontinuado.
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imagefilledpolygon()

    <?php
    // configura o array de pontos para o polígono
    $values = array(
                40,  50,  // Ponto 1 (x, y)
                20,  240, // Ponto 2 (x, y)
                60,  60,  // Ponto 3 (x, y)
                240, 20,  // Ponto 4 (x, y)
                50,  40,  // Ponto 5 (x, y)
                10,  10   // Ponto 6 (x, y)
                );

    // cria imagem
    $image = imagecreatetruecolor(250, 250);

    // aloca cores
    $bg   = imagecolorallocate($image, 0, 0, 0);
    $blue = imagecolorallocate($image, 0, 0, 255);

    // preenche o fundo
    imagefilledrectangle($image, 0, 0, 249, 249, $bg);

    // desenha um polígono
    imagefilledpolygon($image, $values, $blue);

    // descarrega a imagem
    header('Content-type: image/png');
    imagepng($image);
    ?>

O exemplo acima produzirá algo semelhante a:

### Veja Também

- imagepolygon() - Desenha um polígono

# imagefilledrectangle

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefilledrectangle — Desenha um retângulo preenchido

### Descrição

function imagefilledrectangle(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`,
int `$color`
): true

Cria um retângulo preenchido com a cor informada no parâmetro `color` na imagem fornecida em `image`, iniciando no ponto 1 e terminando no ponto 2. 0, 0 é o canto superior esquerdo da imagem.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`x1`

  Coordenada x do ponto 1.

`y1`

  Coordenada y do ponto 1.

`x2`

  Coordenada x do ponto 2.

`y2`

  Coordenada y do ponto 2.

`color`

  A cor de preenchimento. Um identificador de cor criado com imagecolorallocate().

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Uso de imagefilledrectangle()

    <?php
    // Cria uma imagem 55x30
    $im = imagecreatetruecolor(55, 30);
    $white = imagecolorallocate($im, 255, 255, 255);

    // Desenha um retângulo branco
    imagefilledrectangle($im, 4, 4, 50, 25, $white);

    // Grava a imagem
    imagepng($im, './imagefilledrectangle.png');
    ?>

O exemplo acima produzirá algo semelhante a:

# imagefilltoborder

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefilltoborder — Preenche até encontrar uma cor especificada

### Descrição

function imagefilltoborder(
GdImage `$image`,
int `$x`,
int `$y`,
int `$border_color`,
int `$color`
): true

imagefilltoborder() realiza um preenchimento cuja cor de borda é definida por `border_color`. O ponto de início do preenchimento é `x`, `y` (canto superior esquerdo é 0, 0) e a região é preenchida com a cor informada em `color`.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`x`

  Coordenada x do início.

`y`

  Coordenada y do início.

`border_color`

  A cor da borda. Um identificador de cor criado com imagecolorallocate().

`color`

  A cor de preenchimento. Um identificador de cor criado com imagecolorallocate().

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Preenchendo uma elipse com uma cor

    <?php
    // Cria a imagem, com fundo branco
    $im = imagecreatetruecolor(100, 100);
    imagefilledrectangle($im, 0, 0, 100, 100, imagecolorallocate($im, 255, 255, 255));

    // Desenha uma elipse com borda preta para ser preenchida
    imageellipse($im, 50, 50, 50, 50, imagecolorallocate($im, 0, 0, 0));

    // Define a borda e a cor de preenchimento
    $border = imagecolorallocate($im, 0, 0, 0);
    $fill = imagecolorallocate($im, 255, 0, 0);

    // Preenche a seleção
    imagefilltoborder($im, 50, 50, $border, $fill);

    // Exibe
    header('Content-type: image/png');
    imagepng($im);
    ?>

O exemplo acima produzirá algo semelhante a:

### Notas

O algoritmo não se lembra explicitamente de quais pixels já foram definidos, mas infere isso a partir da cor do pixel, portanto ele não consegue distinguir entre pixels que acabaram de ser definidos de pixels que já estavam lá. Isto significa que ao escolher uma cor de preenchimento que já existe na imagem pode gerar resultados indesejados.

# imagefilter

(PHP 5, PHP 7, PHP 8)

imagefilter — Aplica um filtro a uma imagem

### Descrição

function imagefilter(GdImage `$image`, int `$filter`, array|int|float|bool `...$args`): bool

imagefilter() aplica o filtro informado em `filter` na imagem fornecida em `image`.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`filter`

  `filter` pode ser uma das seguintes constantes:

  - `IMG_FILTER_NEGATE`: Inverte todas as cores da imagem.
  - `IMG_FILTER_GRAYSCALE`: Converte a imagem em escala de cinza alterando os componentes vermelho, verde e azul para suas respectivas somas ponderadas, usando os mesmos coeficientes de cálculo de luminância (Y') da REC.601. Os componentes alfa são retidos. Para imagens de paleta, o resultado pode ser diferente devido a limitações da paleta.
  - `IMG_FILTER_BRIGHTNESS`: Altera o brilho da imagem. Use `args` para definir o nível de brilho. O intervalo de brilho é de -255 a 255.
  - `IMG_FILTER_CONTRAST`: Altera o contraste da imagem. Use `args` para definir o nível de contraste.
  - `IMG_FILTER_COLORIZE`: Parecida com `IMG_FILTER_GRAYSCALE`, exceto que pode-se especificar a cor. Use `args`, `arg2` e `arg3` na forma de `red` (vermelho), `green` (verde), `blue` (azul) e `arg4` para o canal `alpha` (alfa). O intervalo de cada cor é de 0 a 255.
  - `IMG_FILTER_EDGEDETECT`: Usa detecção de borda para destacar as bordas da imagem.
  - `IMG_FILTER_EMBOSS`: Faz alto relevo da imagem.
  - `IMG_FILTER_GAUSSIAN_BLUR`: Desfoca a imagem usando o método gaussiano.
  - `IMG_FILTER_SELECTIVE_BLUR`: Desfoca a imagem.
  - `IMG_FILTER_MEAN_REMOVAL`: Usa a remoção de média para alcançar um efeito de "esboço".
  - `IMG_FILTER_SMOOTH`: Torna a imagem mais suave. Use `args` para definir o nível de suavidade.
  - `IMG_FILTER_PIXELATE`: Aplica efeito de pixelização à imagem, use `args` para definir o tamanho do bloco e `arg2` para definir o modo do efeito de pixelização.
  - `IMG_FILTER_SCATTER`: Aplica efeito de dispersão à imagem, use `args` e `arg2` para definir a intensidade do efeito e adicionalmente `arg3` para aplicar o efeito somente em cores de pixels selecionadas.
`args`

  - `IMG_FILTER_BRIGHTNESS`: Nível de brilho.
  - `IMG_FILTER_CONTRAST`: Nível de contraste.
  - `IMG_FILTER_COLORIZE`: Valor do componente vermelho.
  - `IMG_FILTER_SMOOTH`: Nível de suavidade.
  - `IMG_FILTER_PIXELATE`: Tamanho do bloco em pixels.
  - `IMG_FILTER_SCATTER`: Nível de subtração de efeito. Não pode ser maior ou igual ao nível de adição de efeito definido com `arg2`.
`arg2`

  - `IMG_FILTER_COLORIZE`: Valor do componente verde.
  - `IMG_FILTER_PIXELATE`: Informa se deve ser usada efeito de pixelização avançada ou não (o padrão é `false`).
  - `IMG_FILTER_SCATTER`: Nível de adição de efeito.
`arg3`

  - `IMG_FILTER_COLORIZE`: Valor do componente azul.
  - `IMG_FILTER_SCATTER`: Array opcional indexado com valores de cores nas quais os efeitos serão aplicados.
`arg4`

  - `IMG_FILTER_COLORIZE`: Canal alfa, um valor entre 0 e 127. 0 indica completamente opaco e 127 indica completamente transparente.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Lança um ValueError se `sub` ou `plus` puderem causar um estouro de limites com `IMG_FILTER_SCATTER` definido em `filter`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Agora lança um ValueError se `sub` ou `plus` puderem causar um estouro de limites com `IMG_FILTER_SCATTER` definido em `filter`.
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.
7.4.0 | Suporte a dispersão (`IMG_FILTER_SCATTER`) foi adicionado.

### Exemplos

Exemplo #1 Exemplo de escala de cinza com imagefilter()

    <?php
    $im = imagecreatefrompng('dave.png');

    if($im && imagefilter($im, IMG_FILTER_GRAYSCALE))
    {
        echo 'Imagem convertida para escala de cinza.';

        imagepng($im, 'dave.png');
    }
    else
    {
        echo 'Conversão para escala de cinza falhou.';
    }
    ?>

Exemplo #2 Exemplo de brilho com imagefilter()

    <?php
    $im = imagecreatefrompng('sean.png');

    if($im && imagefilter($im, IMG_FILTER_BRIGHTNESS, 20))
    {
        echo 'Brilho da imagem alterado.';

        imagepng($im, 'sean.png');
    }
    else
    {
        echo 'Alteração no brilho da imagem falhou.';
    }
    ?>

Exemplo #3 Exemplo de colorização com imagefilter()

    <?php
    $im = imagecreatefrompng('philip.png');

    /* R, G, B, portanto 0, 255, 0 é verde */
    if($im && imagefilter($im, IMG_FILTER_COLORIZE, 0, 255, 0))
    {
        echo 'Imagem tonalizada em verde com sucesso.';

        imagepng($im, 'philip.png');
    }
    else
    {
        echo 'Tonalização em verde falhou.';
    }
    ?>

Exemplo #4 Exemplo de inversão com imagefilter()

    <?php
    // Define a função de inversão de forma que seja portável
    // para versões de php sem imagefilter()
    function negate($im)
    {
        if(function_exists('imagefilter'))
        {
            return imagefilter($im, IMG_FILTER_NEGATE);
        }

        for($x = 0; $x < imagesx($im); ++$x)
        {
            for($y = 0; $y < imagesy($im); ++$y)
            {
                $index = imagecolorat($im, $x, $y);
                $rgb = imagecolorsforindex($index);
                $color = imagecolorallocate($im, 255 - $rgb['red'], 255 - $rgb['green'], 255 - $rgb['blue']);

                imagesetpixel($im, $x, $y, $color);
            }
        }

        return(true);
    }

    $im = imagecreatefromjpeg('kalle.jpg');

    if($im && negate($im))
    {
        echo 'Imagem convertida com sucesso para cores invertidas.';

        imagejpeg($im, 'kalle.jpg', 100);
    }
    else
    {
        echo 'Conversão para cores invertidas falhou.';
    }
    ?>

Exemplo #5 Exemplo de pixelização com imagefilter()

    <?php
    // Carrega a logomarca do PHP, necessáio criar duas instâncias
    // para mostrar as diferenças
    $logo1 = imagecreatefrompng('./php.png');
    $logo2 = imagecreatefrompng('./php.png');

    // Cria a instância da imagem onde as diferenças serão
    // mostradas
    $output = imagecreatetruecolor(imagesx($logo1) * 2, imagesy($logo1));

    // Aplica a pixelização para cada instância, com um bloco
    // de tamanho 3
    imagefilter($logo1, IMG_FILTER_PIXELATE, 3);
    imagefilter($logo2, IMG_FILTER_PIXELATE, 3, true);

    // Funde as diferenças na imagem de saída
    imagecopy($output, $logo1, 0, 0, 0, 0, imagesx($logo1) - 1, imagesy($logo1) - 1);
    imagecopy($output, $logo2, imagesx($logo2), 0, 0, 0, imagesx($logo2) - 1, imagesy($logo2) - 1);

    // Mostra a diferença
    header('Content-Type: image/png');
    imagepng($output);
    ?>

O exemplo acima produzirá algo semelhante a:

Exemplo #6 Exemplo de dispersão com imagefilter()

    <?php
    // Carrega a imagem
    $logo = imagecreatefrompng('./php.png');

    // Aplica um efeito bem leve de dispersão à imagem
    imagefilter($logo, IMG_FILTER_SCATTER, 3, 5);

    // Mostra a imagem com o efeito de dispersão
    header('Content-Type: image/png');
    imagepng($logo);
    ?>

O exemplo acima produzirá algo semelhante a:

### Notas

> Nota: O resultado de `IMG_FILTER_SCATTER` é sempre aleatório.

### Veja Também

- imageconvolution() - Aplica uma matriz de convolução 3x3, usando coeficiente e deslocamento

# imageflip

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageflip — Vira uma imagem usando um modo especificado

### Descrição

function imageflip(GdImage `$image`, int `$mode`): true

Vira a imagem definida por `image` usando o modo informado em `mode`.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`mode`

  Modo para virar a imagem, pode ser uma das constantes `IMG_FLIP_*`:

  Constante | Significado
  --- | ---
  `IMG_FLIP_HORIZONTAL` | Vira a imagem horizontalmente.
  `IMG_FLIP_VERTICAL` | Vira a imagem verticalmente.
  `IMG_FLIP_BOTH` | Vira a imagem tanto verticalmente quanto horizontalmente.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Vira uma imagem verticalmente

Este exemplo usa a constante `IMG_FLIP_VERTICAL`.

    <?php
    // Arquivo
    $filename = 'phplogo.png';

    // Tipo de conteúdo
    header('Content-type: image/png');

    // Carrega
    $im = imagecreatefrompng($filename);

    // Vira verticalmente
    imageflip($im, IMG_FLIP_VERTICAL);

    // Mostra
    imagejpeg($im);
    ?>

O exemplo acima produzirá algo semelhante a:

Exemplo #2 Vira uma imagem horizontalmente

Este exemplo usa a constante `IMG_FLIP_HORIZONTAL`.

    <?php
    // Arquivo
    $filename = 'phplogo.png';

    // Tipo de conteúdo
    header('Content-type: image/png');

    // Carrega
    $im = imagecreatefrompng($filename);

    // Vira horizontalmente
    imageflip($im, IMG_FLIP_HORIZONTAL);

    // Mostra
    imagejpeg($im);
    ?>

O exemplo acima produzirá algo semelhante a:

# imagefontheight

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefontheight — Obtém a altura da fonte

### Descrição

function imagefontheight(GdFont|int `$font`): int

Retorna a altura da fonte, em pixels, de um caractere em determinada fonte.

### Parâmetros

`font`
  Pode ser 1, 2, 3, 4, 5 para as fontes nativas na codificação latin2 (onde números maiores correspondem a fontes maiores) ou uma instância de GdFont, retornada por imageloadfont().

### Valor Retornado

Retorna a altura da fonte em pixels.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `font` agora aceita uma instância de GdFont ou um int; anteriormente, apenas int era aceito.

### Exemplos

Exemplo #1 Usando imagefontheight() em fontes internas

    <?php
    echo 'Altura da fonte: ' . imagefontheight(4);
    ?>

O exemplo acima produzirá algo semelhante a:

    Altura da fonte: 16

Exemplo #2 Usando imagefontheight() junto com imageloadfont()

    <?php
    // Carrega uma fonte .gdf
    $font = imageloadfont('anonymous.gdf');

    echo 'Altura da fonte: ' . imagefontheight($font);
    ?>

O exemplo acima produzirá algo semelhante a:

    Altura da fonte: 43

### Veja Também

- imagefontwidth() - Obtém a largura da fonte
- imageloadfont() - Carrega uma nova fonte

# imagefontwidth

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefontwidth — Obtém a largura da fonte

### Descrição

function imagefontwidth(GdFont|int `$font`): int

Retorna a largura da fonte, em pixels, de um caractere em determinada fonte.

### Parâmetros

`font`
  Pode ser 1, 2, 3, 4, 5 para as fontes nativas na codificação latin2 (onde números maiores correspondem a fontes maiores) ou uma instância de GdFont, retornada por imageloadfont().

### Valor Retornado

Retorna a largura da fonte em pixels.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `font` agora aceita uma instância de GdFont ou um int; anteriormente, apenas int era aceito.

### Exemplos

Exemplo #1 Usando imagefontwidth() em fontes internas

    <?php
    echo 'Largura da fonte: ' . imagefontwidth(4);
    ?>

O exemplo acima produzirá algo semelhante a:

    Largura da fonte: 8

Exemplo #2 Usando imagefontwidth() junto com imageloadfont()

    <?php
    // Carrega uma fonte .gdf
    $font = imageloadfont('anonymous.gdf');

    echo 'Largura da fonte: ' . imagefontwidth($font);
    ?>

O exemplo acima produzirá algo semelhante a:

    Largura da fonte: 23

### Veja Também

- imagefontheight() - Obtém a altura da fonte
- imageloadfont() - Carrega uma nova fonte

# imageftbbox

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imageftbbox — Fornece a caixa limite de um texto usando fontes via freetype2

### Descrição

function imageftbbox(
float `$size`,
float `$angle`,
string `$font_filename`,
string `$string`,
array `$options` = []
): array|false

Esta função calcula e retorna a caixa limite em pixels para um texto em FreeType.

> Nota:

> Antes do PHP 8.0.0, imageftbbox() era uma variante estendida de imagettfbbox() que suportava adicionalmente o parâmetro `options`. A partir do PHP 8.0.0, imagettfbbox() é um apelido de imageftbbox().

### Parâmetros

`size`

  O tamanho da fonte em pontos.

`angle`

  Ângulo em graus no qual a `string` será medida.

`font_filename`

  O nome do arquivo da fonte TrueType (pode ser uma URL). Dependendo de qual versão da biblioteca GD que o PHP estiver usando, pode ser que ele tente pesquisar por arquivos que não iniciem com uma barra '/', anexando a extensão '.ttf' ao nome do arquivo e pesquisando ao longo de um caminho de fonte definido pela biblioteca.

`string`

  A string a ser medida.

`options`

  Índices de array possíveis para `options`
  Chave | Tipo | Significado
  --- | --- | ---
  `linespacing` | float | Define o espaçamento entre linhas

### Valor Retornado

imageftbbox() retorna um array com 8 elementos representando os quatro pontos que definem os limites do texto:

0 | canto inferior esquerdo, posição X
1 | canto inferior esquerdo, posição Y
2 | canto inferior direito, posição X
3 | canto inferior direito, posição Y
4 | canto superior direito, posição X
5 | canto superior direito, posição Y
6 | canto superior esquerdo, posição X
7 | canto superior esquerdo, posição Y

Os pontos são relativos ao texto independente do parâmetro `angle`, portanto "superior esquerdo" significa no canto da parte superior esquerda vendo o texto horizontalmente.

Em caso de falha, `false` é retornado.

### Exemplos

Exemplo #1 Exemplo de imageftbbox()

    <?php
    // Cria uma imagem 300x150
    $im = imagecreatetruecolor(300, 150);
    $black = imagecolorallocate($im, 0, 0, 0);
    $white = imagecolorallocate($im, 255, 255, 255);

    // Define o fundo para branco
    imagefilledrectangle($im, 0, 0, 299, 299, $white);

    // Caminho para o arquivo da fonte
    $font = './arial.ttf';

    // Primeiramente cria-se a caixa limite
    $bbox = imageftbbox(10, 0, $font, 'The PHP Documentation Group');

    // Estas são as coordenadas para X e Y
    $x = $bbox[0] + (imagesx($im) / 2) - ($bbox[4] / 2) - 5;
    $y = $bbox[1] + (imagesy($im) / 2) - ($bbox[5] / 2) - 5;

    imagefttext($im, 10, 0, $x, $y, $black, $font, 'The PHP Documentation Group');

    // Mostra no navegador
    header('Content-Type: image/png');

    imagepng($im);
    ?>

### Notas

> Nota: Esta função só estará disponível se o PHP for compilado com suporte ao freetype (--with-freetype-dir=DIR).

### Veja Também

- imagefttext() - Escreve texto em uma imagem usando fontes FreeType 2
- imagettfbbox() - Fornece a os limites retangulares de um texto usando fontes TrueType

# imagefttext

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagefttext — Escreve texto em uma imagem usando fontes FreeType 2

### Descrição

function imagefttext(
GdImage `$image`,
float `$size`,
float `$angle`,
int `$x`,
int `$y`,
int `$color`,
string `$font_filename`,
string `$text`,
array `$options` = []
): array|false

> Nota:

> Antes do PHP 8.0.0, imagefttext() era uma variante estendida de imagettftext() que suportava adicionalmente o parâmetro `options`. A partir do PHP 8.0.0, imagettftext() é um apelido de imagefttext().

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`size`

  O tamanho da fonte a ser usado, em pontos.

`angle`

  O ângulo em graus, com 0 grau sendo a leitura da esquerda para a direita. Valores maiores representam a rotação no sentido anti-horário. Por exemplo, um valor de 90 resultaria em uma leitura de baixo para cima.

`x`

  As coordenadas dadas por `x` e `y` definirão o ponto base do primeiro caractere (aproximadamente o canto inferior esquerdo do caractere. Isto é diferente de imagestring(), onde `x` e `y` definem o canto superior esquerdo do primeiro caractere. Por exemplo, "superior esquerdo" é 0, 0.

`y`

  A ordenada y. Isto define a posição da linha de base da fonte, e não a parte mais baixa do caractere.

`color`

  O índice da cor desejada para o texto, veja imagecolorexact().

`font_filename`

  O caminho para a fonte TrueType a ser usada.

  Dependendo de qual versão da biblioteca GD que o PHP estiver usando, quando `font_filename` não iniciar com uma barra `/`. a extensão `.ttf` será anexada ao nome do arquivo e a biblioteca tentará pesquisar por este arquivo ao longo do caminho definido pela biblioteca.

  Em muitos casos onde uma fonte reside no mesmo diretório que o script que está sendo executado, o truque a seguir aliviará problemas ao incluir arquivos.

      <?php
      //Define a variável de ambiente para GD
      putenv('GDFONTPATH=' . realpath('.'));

      // Nomeia a fonte a ser usada (note a falta da extensão .ttf)
      $font = 'SomeFont';
      ?>

`text`

  Texto a ser inserido na imagem.

`options`

  Índices de array possíveis para `options`
  Chave | Tipo | Significado
  --- | --- | ---
  `linespacing` | float | Define espaçamento entre linhas

### Valor Retornado

Esta função retorna um array com os quatro pontos que definem os limites do texto, iniciando no canto inferior esquerdo e seguindo no sentido anti-horário:

0 | canto inferior esquerdo, posição X
1 | canto inferior esquerdo, posição Y
2 | canto inferior direito, posição X
3 | canto inferior direito, posição Y
4 | canto superior direito, posição X
5 | canto superior direito, posição Y
6 | canto superior esquerdo, posição X
7 | canto superior esquerdo, posição Y

Em caso de falha, `false` é retornado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imagefttext()

    <?php
    // Cria uma imagem 300x100
    $im = imagecreatetruecolor(300, 100);
    $red = imagecolorallocate($im, 0xFF, 0x00, 0x00);
    $black = imagecolorallocate($im, 0x00, 0x00, 0x00);

    // Deixa o fundo vermelho
    imagefilledrectangle($im, 0, 0, 299, 99, $red);

    // Caminho para o arquivo de fonte ttf
    $font_file = './arial.ttf';

    // Desenha o texto 'PHP Manual' usando fonte tamanho 13
    imagefttext($im, 13, 0, 105, 55, $black, $font_file, 'PHP Manual');

    // Mostr a imagem no navegador
    header('Content-Type: image/png');

    imagepng($im);
    ?>

### Notas

> Nota: Esta função só estará disponível se o PHP for compilado com suporte ao freetype (--with-freetype-dir=DIR).

### Veja Também

- imageftbbox() - Fornece a caixa limite de um texto usando fontes via freetype2
- imagettftext() - Escreve texto na imagem usando fontes TrueType

# imagegammacorrect

(PHP 4, PHP 5, PHP 7, PHP 8)

imagegammacorrect — Aplica uma correção de gama a uma imagem GD

### Descrição

function imagegammacorrect(GdImage `$image`, float `$input_gamma`, float `$output_gamma`): true

Aplica uma correção de gama à imagem GD informada em `image`, sendo fornecido um gama de entrada e de saída.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`input_gamma`

  O gama de entrada.

`output_gamma`

  O gama de saída.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Uso de imagegammacorrect()

    <?php
    // Cria a instância de imagem
    $im = imagecreatefromgif('php.gif');

    // Corrige o gama, saída = 1.537
    imagegammacorrect($im, 1.0, 1.537);

    // Grava a imagem
    imagegif($im, './php_gamma_corrected.gif');
    ?>

# imagegd

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagegd — Envia uma imagem GD para o navegador ou para um arquivo

### Descrição

function imagegd(GdImage `$image`, ?string `$file` = `null`): bool

Exibe ou salva a imagem informada em `image` no formato GD.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`file`

  O caminho ou um recurso de fluxo aberto (que será fechado automaticamente após o retorno desta função) para salvar o arquivo. Se não for definido ou for `null`, o fluxo da imagem bruta será enviado diretamente.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

Cuidado

Entretanto, se a biblioteca libgd falhar ao gerar a imagem, esta função retornará `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.3 | `file` agora pode ser nulo.
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.
7.2.0 | imagegd() agora permite gerar imagens em cores verdadeiras. Anteriormente, elas eram convertidas implicitamente para paleta.

### Exemplos

Exemplo #1 Mostrando uma imagem GD

    <?php
    // Cria uma imagem vazia e adiciona algum texto
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "A Simple Text String", $text_color);

    // Mostra a imagem
    imagegd($im);
    ?>

Exemplo #2 Saving a GD image

    <?php
    // Cria uma imagem vazia e adiciona algum texto
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "A Simple Text String", $text_color);

    // Grava a imagem GD
    // O formato de arquivo para imagens GD é .gd, consulte http://www.libgd.org/GdFileFormats
    imagegd($im, 'simple.gd');
    ?>

### Notas

> Nota:

> O formato GD é usado normalmente para permitir carregamento rápido de partes de imagens. Observe que o formato GD é utilizável somente em aplicações compatíveis com GD.

Aviso

Os formatos de imagem GD e GD2 são formatos de imagem proprietários da biblioteca libgd. Eles devem ser considerados obsoletos e só devem ser usados para propósitos de desenvolvimento e testes.

### Veja Também

- imagegd2() - Envia uma imagem GD2 ao navegador ou a um arquivo

# imagegd2

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagegd2 — Envia uma imagem GD2 ao navegador ou a um arquivo

### Descrição

function imagegd2(
GdImage `$image`,
?string `$file` = `null`,
int `$chunk_size` = 128,
int `$mode` = `IMG_GD2_RAW`
): bool

Exibe ou salva a imagem informada em `image` no formato GD2.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`file`

  O caminho ou um recurso de fluxo aberto (que será fechado automaticamente após o retorno desta função) para salvar o arquivo. Se não for definido ou for `null`, o fluxo da imagem bruta será enviado diretamente.

`chunk_size`

  Tamanho do pacote.

`mode`

  Pode ser `IMG_GD2_RAW` ou `IMG_GD2_COMPRESSED`. O padrão é `IMG_GD2_RAW`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

Cuidado

Entretanto, se a biblioteca libgd falhar ao gerar a imagem, esta função retornará `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.3 | `file` agora pode ser nulo.
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Mostrando uma imagem GD2

    <?php
    // Cria uma imagem vazia e adiciona algum texto
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "A Simple Text String", $text_color);

    // Mostra a imagem
    imagegd2($im);
    ?>

Exemplo #2 Saving a GD2 image

    <?php
    // Cria uma imagem vazia e adiciona algum texto
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "A Simple Text String", $text_color);

    // Grava a imagem GD2
    // O formato de arquivo para imagens GD2 é .gd2, consulte http://www.libgd.org/GdFileFormats
    imagegd2($im, 'simple.gd2');
    ?>

### Notas

> Nota:

> O formato GD2 é usado normalmente para permitir carregamento rápido de partes de imagens. Observe que o formato GD é utilizável somente em aplicações compatíveis com GD2.

Aviso

Os formatos de imagem GD e GD2 são formatos de imagem proprietários da biblioteca libgd. Eles devem ser considerados obsoletos e só devem ser usados para propósitos de desenvolvimento e testes.

### Veja Também

- imagegd() - Envia uma imagem GD para o navegador ou para um arquivo

# imagegetclip

(PHP 7 >= 7.2.0, PHP 8)

imagegetclip — Obtém o retângulo de recorte

### Descrição

function imagegetclip(GdImage `$image`): array

imagegetclip() obtém o retângulo de recorte atual, isto é, a área além da qual nenhum pixel será desenhado.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().

### Valor Retornado

A função retorna um array indexado com as coordenadas do retângulo de recorte, com as seguintes entradas:

- Coordenada x do canto superior esquerdo
- Coordenada y do canto superior esquerdo
- Coordenada x do canto inferior direito
- Coordenada y do canto inferior direito

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imagegetclip()

Definindo e obtendo o retângulo de recorte.

    <?php
    $im = imagecreate(100, 100);
    imagesetclip($im, 10,10, 89,89);
    print_r(imagegetclip($im));

O exemplo acima produzirá:

    Array
    (
        [0] => 10
        [1] => 10
        [2] => 89
        [3] => 89
    )

### Veja Também

- imagesetclip() - Define o retângulo de recorte

# imagegetinterpolation

(PHP 8)

imagegetinterpolation — Obtém o método de interpolação

### Descrição

function imagegetinterpolation(GdImage `$image`): int

Obtém o método de interpolação atualmente definido para a imagem informada em `image`.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().

### Valor Retornado

Retorna o método de interpolação.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Veja Também

- imagesetinterpolation() - Define o método de interpolação

# imagegif

(PHP 4, PHP 5, PHP 7, PHP 8)

imagegif — Envia a imagem para o navegador ou para um arquivo

### Descrição

function imagegif(GdImage `$image`, resource|string|null `$file` = `null`): bool

imagegif() cria o arquivo GIF especificado em `file` a partir da imagem em `image`. O argumento `image` é o retorno da função imagecreate() ou `imagecreatefrom*`.

O formato da imagem será GIF87a a menos que a imagem tenha se tornado transparente com imagecolortransparent(), e neste caso o formato da imagem será GIF89a.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`file`

  O caminho ou um recurso de fluxo aberto (que será fechado automaticamente após o retorno desta função) para salvar o arquivo. Se não for definido ou for `null`, o fluxo da imagem bruta será enviado diretamente.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

Cuidado

Entretanto, se a biblioteca libgd falhar ao gerar a imagem, esta função retornará `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Mostrando uma imagem usando imagegif()

    <?php
    // Cria uma nova instância de imagem
    $im = imagecreatetruecolor(100, 100);

    // Deixa o fundo branco
    imagefilledrectangle($im, 0, 0, 99, 99, 0xFFFFFF);

    // Desenha uma string na imagem
    imagestring($im, 3, 40, 20, 'GD Library', 0xFFBA00);

    // Mostra a imagem no navegador
    header('Content-Type: image/gif');

    imagegif($im);
    ?>

Exemplo #2 Convertendo uma imagem PNG para GIF usando imagegif()

    <?php

    // Carrega o PNG
    $png = imagecreatefrompng('./php.png');

    // Grava a imagem como GIF
    imagegif($png, './php.gif');

    // Pronto
    echo 'Convertida a imagem PNG para GIF com sucesso!';
    ?>

### Notas

> Nota:

> O extrato de código a seguir permite esrever aplicações PHP mais portáveis através de auto-detecção do tipo de suporte GD disponível. Substitua sequência `header ("Content-Type: image/gif"); imagegif ($im);` pela sequência mais flexível:

>     <?php
>     // Cria uma nova instância de imagem
>     $im = imagecreatetruecolor(100, 100);

>     // Faz aqui algumas operações

>     // Lida com a saída
>     if(function_exists('imagegif'))
>     {
>         // Para GIF
>         header('Content-Type: image/gif');

>         imagegif($im);
>     }
>     elseif(function_exists('imagejpeg'))
>     {
>         // Para JPEG
>         header('Content-Type: image/jpeg');

>         imagejpeg($im, NULL, 100);
>     }
>     elseif(function_exists('imagepng'))
>     {
>         // Para PNG
>         header('Content-Type: image/png');

>         imagepng($im);
>     }
>     elseif(function_exists('imagewbmp'))
>     {
>         // Para WBMP
>         header('Content-Type: image/vnd.wap.wbmp');

>         imagewbmp($im);
>     }
>     else
>     {
>         die('Não existe suporte para imagem neste servidor PHP');
>     }
>     ?>

> Nota:

> Pode-se usar a função imagetypes() para verificar a presenção de vários formatos de imagem suportados:

>     <?php
>     if(imagetypes() & IMG_GIF)
>     {
>         header('Content-Type: image/gif');
>         imagegif($im);
>     }
>     elseif(imagetypes() & IMG_JPG)
>     {
>         /* ... etc. */
>     }
>     ?>

### Veja Também

- imagepng() - Envia uma imagem PNG para o navegador ou arquivo
- imagewbmp() - Envia a imagem para o navegador ou para um arquivo
- imagejpeg() - Envia a imagem para o navegador ou para um arquivo
- imagetypes() - Retorna os tipos de imagens suportados pela instalação do PHP

# imagegrabscreen

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

imagegrabscreen — Captura toda a tela

### Descrição

function imagegrabscreen(): GdImage|false

Captura uma fotografia de toda a tela.

> Nota:

> Esta função está disponível apenas no Windows.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um objeto de imagem em caso de sucesso, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Em caso de sucesso, esta função retorna agora uma instância de GDImage; anteriormente, um resource era retornado.

### Exemplos

Exemplo #1 Exemplo de imagegrabscreen()

Este exemplo demonstra como tirar uma fotografia da tela atual e gravá-la como uma imagem PNG.

    <?php
    $im = imagegrabscreen();
    imagepng($im, "myscreenshot.png");
    ?>

### Veja Também

- imagegrabwindow() - Captura uma janela

# imagegrabwindow

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

imagegrabwindow — Captura uma janela

### Descrição

function imagegrabwindow(int `$handle`, bool `$client_area` = `false`): GdImage|false

Captura uma janela ou sua área de cliente usando um manipulador do Windows (propriedade HWND na instância COM)

> Nota:

> Esta função está disponível apenas no Windows.

### Parâmetros

`handle`

  O ID da janela HWND.

`client_area`

  Inclui a área de cliente da janela da aplicação.

### Valor Retornado

Retorna um objeto de imagem em caso de sucesso, `false` em caso de falha.

### Erros/Exceções

E_NOTICE é emitido se `handle` for um manipulador de janela inválido. E_WARNING é emitido se a API do Windows for muito antiga.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Em caso de sucesso, esta função retorna agora uma instância de GDImage; anteriormente, um resource era retornado.
8.0.0 | `client_area` agora espera um valor do tipo bool; anteriormente era esperado um valor do tipo int.

### Exemplos

Exemplo #1 Exemplo de imagegrabwindow()

Captura uma janela (IE por exemplo)

    <?php
    $browser = new COM("InternetExplorer.Application");
    $handle = $browser->HWND;
    $browser->Visible = true;
    $im = imagegrabwindow($handle);
    $browser->Quit();
    imagepng($im, "iesnap.png");
    ?>

Captura uma janela (IE por exemplo) mas com seu conteúdo

    <?php
    $browser = new COM("InternetExplorer.Application");
    $handle = $browser->HWND;
    $browser->Visible = true;
    $browser->Navigate("http://www.libgd.org");

    /* Ainda funcionando? */
    while ($browser->Busy) {
        com_message_pump(4000);
    }
    $im = imagegrabwindow($handle, 0);
    $browser->Quit();
    imagepng($im, "iesnap.png");
    ?>

### Veja Também

- imagegrabscreen() - Captura toda a tela

# imageinterlace

(PHP 4, PHP 5, PHP 7, PHP 8)

imageinterlace — Habilita ou desabilita entrelace

### Descrição

function imageinterlace(GdImage `$image`, ?bool `$enable` = `null`): bool

imageinterlace() liga ou desliga o bit de entrelace.

Se o bit de entrelace estiver ligado e a imagem for usada como JPEG, a imagem é criada como um JPEG progressivo.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`enable`

  Se `true`, a imagem será entrelaçada, se `false` o bit de entrelace é desligado. Passar `null` fará com que o comportamento de entrelace não seja alterado.

### Valor Retornado

Retorna `true` se o bit de entrelace estiver ligador para a imagem, `false` caso contrário.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.5 | imageinterlace() agora retorna um bool; anteriormente retornava um int (não zero para imagens entrelaçadas, zero caso contrário).
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.
8.0.0 | `enable` agora espera um bool; anteriormente esperava um int.

### Exemplos

Exemplo #1 Ligando o entrelace usando imageinterlace()

    <?php
    // Cria uma instância de imagem
    $im = imagecreatefromgif('php.gif');

    // Habilita entrelace
    imageinterlace($im, true);

    // Grava a imagem entrelaçada
    imagegif($im, './php_interlaced.gif');
    ?>

# imageistruecolor

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imageistruecolor — Descobre se uma imagem está em cores verdadeiras

### Descrição

function imageistruecolor(GdImage `$image`): bool

imageistruecolor() Descobre se a imagem definida em `image` está em cores verdadeiras.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().

### Valor Retornado

Retorna `true` se `image` estiver em cores verdadeiras, `false` caso contrário.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Detecção simples de instâncias de imagem em cores verdadeiras usando imageistruecolor()

    <?php
    // $im é uma instância de imagem

    // Verifica se a imagem está ou não em cores verdadeiras
    if(!imageistruecolor($im))
    {
        // Cria uma nova instância de imagem em cores verdadeiras
        $tc = imagecreatetruecolor(imagesx($im), imagesy($im));

        // Copia os pixels
        imagecopy($tc, $im, 0, 0, 0, 0, imagesx($im), imagesy($im));

        $im = $tc;
        $tc = NULL;

        // OU use imagepalettetotruecolor()
    }

    // Continua trabalhando com a instância de imagem
    ?>

### Veja Também

- imagecreatetruecolor() - Cria uma nova imagem em cores verdadeiras
- imagepalettetotruecolor() - Converte uma imagem baseada em paleta para cores verdadeiras

# imagejpeg

(PHP 4, PHP 5, PHP 7, PHP 8)

imagejpeg — Envia a imagem para o navegador ou para um arquivo

### Descrição

function imagejpeg(GdImage `$image`, resource|string|null `$file` = `null`, int `$quality` = -1): bool

imagejpeg() cria um arquivo JPEG a partir da imagem informada em `image`.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`file`

  O caminho ou um recurso de fluxo aberto (que será fechado automaticamente após o retorno desta função) para salvar o arquivo. Se não for definido ou for `null`, o fluxo da imagem bruta será enviado diretamente.

`quality`

  `quality` é opcional e varia de 0 (pior qualidade, arquivo menor) a 100 (melhor qualidade, arquivo maior). O padrão (`-1`) usa o valor de qualidade IJG padrão (por volta de 75).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

Cuidado

Entretanto, se a biblioteca libgd falhar ao gerar a imagem, esta função retornará `true`.

### Erros/Exceções

Lança um ValueError se `quality` for inválido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Agora lança um ValueError se `quality` for inválido.
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Mostrando uma imagem JPEG no navegador

    <?php
    // Cria uma imagem vazia e adiciona um texto
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // Define o cabeçalho de tipo de conteúdo - neste caso image/jpeg
    header('Content-Type: image/jpeg');

    // Mostra a imagem
    imagejpeg($im);
    ?>

O exemplo acima produzirá algo semelhante a:

Exemplo #2 Gravando uma imagem JPEG em um arquivo

    <?php
    // Cria uma imagem vazia e adiciona um texto
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // Grava a imagem como 'simpletext.jpg'
    imagejpeg($im, 'simpletext.jpg');
    ?>

Exemplo #3 Mostrando a imagem com 75% de qualidade no navegador

    <?php
    // Cria uma imagem vazia e adiciona um texto
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // Define o cabeçalho de tipo de conteúdo - neste caso image/jpeg
    header('Content-Type: image/jpeg');

    // Ignora o parâmetro arquivo usando NULL, e então define a qualidade para 75%
    imagejpeg($im, NULL, 75);
    ?>

### Notas

> Nota:

> Se for desejado mostrar JPEGs progressivos, deve-se habilitar entrelace com a função imageinterlace().

### Veja Também

- imagepng() - Envia uma imagem PNG para o navegador ou arquivo
- imagegif() - Envia a imagem para o navegador ou para um arquivo
- imagewbmp() - Envia a imagem para o navegador ou para um arquivo
- imageinterlace() - Habilita ou desabilita entrelace
- imagetypes() - Retorna os tipos de imagens suportados pela instalação do PHP

# imagelayereffect

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imagelayereffect — Define a opção de mesclagem alfa para usar efeitos de camada

### Descrição

function imagelayereffect(GdImage `$image`, int `$effect`): true

Define a opção de mesclagem alfa para usar efeitos de camada.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`effect`

  Uma das constantes a seguir:

  `IMG_EFFECT_REPLACE`
    Usa substituição de pixel (equivalente a passar `true` para imagealphablending())
  `IMG_EFFECT_ALPHABLEND`
    Usa mesclagem de pixel normal (equivalent a passar `false` para imagealphablending())
  `IMG_EFFECT_NORMAL`
    O mesmo que `IMG_EFFECT_ALPHABLEND`.
  `IMG_EFFECT_OVERLAY`
    Sobreposição tem o efeito em que os pixels do fundo preto permanecerão pretos, pixels de fundo branco permanecerão brancos, mas pixels de fundo cinza tomarão a cor do pixel de primeiro plano.
  `IMG_EFFECT_MULTIPLY`
    Sobrepõe com efeito de multiplicação.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.
7.2.0 | Adicionada a constante `IMG_EFFECT_MULTIPLY` (requer libgd de sistema >= 2.1.1 ou a libgd incluída no pacote).

### Exemplos

Exemplo #1 Exemplo de imagelayereffect()

    <?php
    // Configura uma imagem
    $im = imagecreatetruecolor(100, 100);

    // Define a cor de fundo
    imagefilledrectangle($im, 0, 0, 100, 100, imagecolorallocate($im, 220, 220, 220));

    // Applica a opção de mesclagem alfa de sobreposição
    imagelayereffect($im, IMG_EFFECT_OVERLAY);

    // Desenha duas elipses cinzas
    imagefilledellipse($im, 50, 50, 40, 40, imagecolorallocate($im, 100, 255, 100));
    imagefilledellipse($im, 50, 50, 50, 80, imagecolorallocate($im, 100, 100, 255));
    imagefilledellipse($im, 50, 50, 80, 50, imagecolorallocate($im, 255, 100, 100));

    // Mostra
    header('Content-type: image/png');

    imagepng($im);
    ?>

O exemplo acima produzirá algo semelhante a:

# imageline

(PHP 4, PHP 5, PHP 7, PHP 8)

imageline — Desenha uma linha

### Descrição

function imageline(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`,
int `$color`
): true

Desenha uma linha entre dois pontos informados.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`x1`

  Coordenada x do primeiro ponto.

`y1`

  Coordenada y do primeiro ponto.

`x2`

  Coordenada x do segundo ponto.

`y2`

  Coordenada y do segundo ponto.

`color`

  A cor da linha. Um identificador de cor criado com imagecolorallocate().

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Desenhando uma linha espessa

    <?php

    function imagelinethick($image, $x1, $y1, $x2, $y2, $color, $thick = 1)
    {
        /* desta forma só funciona bem com linhas ortogonais
        imagesetthickness($image, $thick);
        return imageline($image, $x1, $y1, $x2, $y2, $color);
        */
        if ($thick == 1) {
            return imageline($image, $x1, $y1, $x2, $y2, $color);
        }
        $t = $thick / 2 - 0.5;
        if ($x1 == $x2 || $y1 == $y2) {
            return imagefilledrectangle($image, round(min($x1, $x2) - $t), round(min($y1, $y2) - $t), round(max($x1, $x2) + $t), round(max($y1, $y2) + $t), $color);
        }
        $k = ($y2 - $y1) / ($x2 - $x1); //y = kx + q
        $a = $t / sqrt(1 + pow($k, 2));
        $points = array(
            round($x1 - (1+$k)*$a), round($y1 + (1-$k)*$a),
            round($x1 - (1-$k)*$a), round($y1 - (1+$k)*$a),
            round($x2 + (1+$k)*$a), round($y2 - (1-$k)*$a),
            round($x2 + (1-$k)*$a), round($y2 + (1+$k)*$a),
        );
        imagefilledpolygon($image, $points, 4, $color);
        return imagepolygon($image, $points, 4, $color);
    }

    ?>

### Veja Também

- imagecreatetruecolor() - Cria uma nova imagem em cores verdadeiras
- imagecolorallocate() - Aloca uma cor para uma imagem

# imageloadfont

(PHP 4, PHP 5, PHP 7, PHP 8)

imageloadfont — Carrega uma nova fonte

### Descrição

function imageloadfont(string `$filename`): GdFont|false

imageloadfont() carrega um mapa de bits definido pelo usuário e retorna seu identificador.

### Parâmetros

`filename`

  O formato de arquivo de fonte atualmente é binário e dependente de arquitetura. Isto significa que os arquivos de fonte devem ser gerados no mesmo tipo de CPU da máquina onde o PHP estiver sendo executado.

  Formato de arquivo de fonte
  posição do byte | tipo de dados C | descrição
  --- | --- | ---
  bytes 0-3 | int | número de caracteres na fonte
  bytes 4-7 | int | valor do primeiro caractere na fonte (normalmente 32 para espaço)
  bytes 8-11 | int | largura em pixel para cada caractere
  bytes 12-15 | int | altura em pixel para cada caractere
  bytes 16- | char | array com dados de caracteres, um byte por pixel em cada caractere, para um total de (num_caracteres * largura * altura) bytes.

### Valor Retornado

Retorna uma instância GdFont, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Retorna uma instância GdFont agora; anteriormente, um int era retornado.

### Exemplos

Exemplo #1 Exemplo de uso de imageloadfont()

    <?php
    // Cria uma nova instância de imagem
    $im = imagecreatetruecolor(50, 20);
    $black = imagecolorallocate($im, 0, 0, 0);
    $white = imagecolorallocate($im, 255, 255, 255);

    // Torna o fundo branco
    imagefilledrectangle($im, 0, 0, 49, 19, $white);

    // Carrega a fonte GD e escreve 'Hello'
    $font = imageloadfont('./04b.gdf');
    imagestring($im, $font, 0, 0, 'Hello', $black);

    // Mostra no navegador
    header('Content-type: image/png');

    imagepng($im);
    ?>

### Veja Também

- imagefontwidth() - Obtém a largura da fonte
- imagefontheight() - Obtém a altura da fonte
- imagestring() - Desenha uma string na horizontal

# imageopenpolygon

(PHP 7 >= 7.2.0, PHP 8)

imageopenpolygon — Desenha um polígono aberto

### Descrição

Assinatura a partir do PHP 8.0.0 (não suportada com argumentos nomeados)

function imageopenpolygon(GdImage `$image`, array `$points`, int `$color`): bool

Assinatura alternativa (descontinuada a partir do PHP 8.1.0)

function imageopenpolygon(
GdImage `$image`,
array `$points`,
int `$num_points`,
int `$color`
): bool

imageopenpolygon() desenha um polígono aberto na imagem informada em `image`. A contrário de imagepolygon(), nenhuma linha é desenhada entre o último ponto e o primeiro ponto.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`points`

  Um array contendo os vértices do polígono, por exemplo:

  points[0] | = x0
  points[1] | = y0
  points[2] | = x1
  points[3] | = y1

`num_points`

  Número total de pontos (vértices), que devem ser pelo menos 3.

  Se este parâmetro for omitido conforme a segunda assinatura, `points` precisa ter um número par de elementos, e será assumido que `num_points` será igual a `count($points)/2`.
`color`

  Um identificador de cor criado com imagecolorallocate().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `num_points` foi descontinuado.
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imageopenpolygon()

    <?php
    // Cria uma imagem vazia
    $image = imagecreatetruecolor(400, 300);

    // Aloca uma cor para o polígono
    $col_poly = imagecolorallocate($image, 255, 255, 255);

    // Desenha o polígono
    imageopenpolygon($image, array(
            0,   0,
            100, 200,
            300, 200
        ),
        $col_poly);

    // Mostra a imagem no navegador
    header('Content-type: image/png');

    imagepng($image);
    ?>

O exemplo acima produzirá algo semelhante a:

### Veja Também

- imagepolygon() - Desenha um polígono

# imagepalettecopy

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagepalettecopy — Copia a paleta de uma imagem para outra

### Descrição

function imagepalettecopy(GdImage `$dst`, GdImage `$src`): void

imagepalettecopy() copia a paleta da imagem `src` para a imagem `dst`.

### Parâmetros

`dst`

  O objeto imagem de destino.

`src`

  O objeto imagem de origem.

### Valor Retornado

Nenhum valor é retornado.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `dst` e `src` agora esperam instâncias GdImage; anteriormente, recursos do tipo resource eram esperados.

### Exemplos

Exemplo #1 Exemplo de imagepalettecopy()

    <?php
    // Cria duas imagens de paleta
    $palette1 = imagecreate(100, 100);
    $palette2 = imagecreate(100, 100);

    // Aloca a cor verde para o
    // fundo da primeira imagem de paleta
    $green = imagecolorallocate($palette1, 0, 255, 0);

    // Copia a paleta da imagem 1 para a imagem 2
    imagepalettecopy($palette2, $palette1);

    // Agora que a paleta está copiada, pode-se usar
    // a cor verde alocada à imagem 1 sem usar
    // imagecolorallocate() duas vezes
    imagefilledrectangle($palette2, 0, 0, 99, 99, $green);

    // Mostra a imagem no navegador
    header('Content-type: image/png');

    imagepng($palette2);
    ?>

# imagepalettetotruecolor

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagepalettetotruecolor — Converte uma imagem baseada em paleta para cores verdadeiras

### Descrição

function imagepalettetotruecolor(GdImage `$image`): bool

Converte uma imagem baseada em paleta, criada por funções como imagecreate(), para uma imagem em cores verdadeiras, como imagecreatetruecolor().

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().

### Valor Retornado

Retorna `true` se a conversão for concluída, ou se a imagem de origem já estiver em cores verdadeiras, caso contrário é retornado `false`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Converte qualquer objeto de imagem para cores verdadeiras

    <?php
    // Compatibilidade com versões anteriores
    if(!function_exists('imagepalettetotruecolor'))
    {
        function imagepalettetotruecolor(&$src)
        {
            if(imageistruecolor($src))
            {
                return(true);
            }

            $dst = imagecreatetruecolor(imagesx($src), imagesy($src));

            imagecopy($dst, $src, 0, 0, 0, 0, imagesx($src), imagesy($src));

            $src = $dst;

            return(true);
        }
    }

    // Closure de apoio
    $typeof = function() use($im)
    {
        echo 'typeof($im) = ' . (imageistruecolor($im) ? 'cores verdadeiras' : 'paleta'), PHP_EOL;
    };

    // Cria uma imagem baseada em paleta
    $im = imagecreate(100, 100);
    $typeof();

    // Converte para cores verdadeiras
    imagepalettetotruecolor($im);
    $typeof();
    ?>

O exemplo acima produzirá:

    typeof($im) = paleta
    typeof($im) = cores verdadeiras

### Veja Também

- imagecreatetruecolor() - Cria uma nova imagem em cores verdadeiras
- imageistruecolor() - Descobre se uma imagem está em cores verdadeiras

# imagepng

(PHP 4, PHP 5, PHP 7, PHP 8)

imagepng — Envia uma imagem PNG para o navegador ou arquivo

### Descrição

function imagepng(
GdImage `$image`,
resource|string|null `$file` = `null`,
int `$quality` = -1,
int `$filters` = -1
): bool

Envia ou grava uma imagem PNG a partir do parâmetro `image`.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`file`

  O caminho ou um recurso de fluxo aberto (que será fechado automaticamente após o retorno desta função) para salvar o arquivo. Se não for definido ou for `null`, o fluxo da imagem bruta será enviado diretamente.

  > Nota:

  > `null` é inválido se os argumentos `quality` e `filters` não forem informados.

`quality`

  Nível de compressão: de 0 (sem compressão) a 9. O padrão (`-1`) utiliza a compressão padrão da zlib. Para mais informações, consulte o » manual zlib.

`filters`

  Permite reduzir o tamanho do arquivo PNG. Uma máscara de bits pode ser informada por qualquer combinação das constantes `PNG_FILTER_*`. `PNG_NO_FILTER` ou `PNG_ALL_FILTERS` também podem ser utilizadas, respectivamente, para desativar ou ativar todos os filtros. O valor padrão (`-1`) desativa os filtros.

  Cuidado

  O parâmetro `filters` é ignorado pela libgd de sistema.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

Cuidado

Entretanto, se a biblioteca libgd falhar ao gerar a imagem, esta função retornará `true`.

### Erros/Exceções

Lança uma exceção ValueError se `quality` for inválido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Agora lança uma exceção ValueError se `quality` for inválido.
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

    <?php
    $im = imagecreatefrompng("test.png");

    header('Content-Type: image/png');

    imagepng($im);
    ?>

### Veja Também

- imagegif() - Envia a imagem para o navegador ou para um arquivo
- imagewbmp() - Envia a imagem para o navegador ou para um arquivo
- imagejpeg() - Envia a imagem para o navegador ou para um arquivo
- imagetypes() - Retorna os tipos de imagens suportados pela instalação do PHP
- imagesavealpha() - Informa se a informação de canal alfa deve ser retida ao gravar imagens

# imagepolygon

(PHP 4, PHP 5, PHP 7, PHP 8)

imagepolygon — Desenha um polígono

### Descrição

Assinatura a partir do PHP 8.0.0 (não suportada com argumentos nomeados)

function imagepolygon(GdImage `$image`, array `$points`, int `$color`): bool

Assinatura alternativa (descontinuada a partir do PHP 8.1.0)

function imagepolygon(
GdImage `$image`,
array `$points`,
int `$num_points`,
int `$color`
): bool

imagepolygon() cria um polígono na imagem informada em `image`.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`points`

  Um array contendo os vértices do polígono, por exemplo:

  points[0] | = x0
  points[1] | = y0
  points[2] | = x1
  points[3] | = y1

`num_points`

  Número total de pontos (vértices), que devem ser pelo menos 3.

  Se este parâmetro for omitido conforme a segunda assinatura, `points` precisa ter um número par de elementos, e será assumido que `num_points` será igual a `count($points)/2`.
`color`

  Um identificador de cor criado com imagecolorallocate().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `num_points` foi descontinuado.
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imagepolygon()

    <?php
    // Cria uma imagem vazia
    $image = imagecreatetruecolor(400, 300);

    // Aloca uma cor para o polígono
    $col_poly = imagecolorallocate($image, 255, 255, 255);

    // Desenha o polígono
    imagepolygon($image, array(
            0,   0,
            100, 200,
            300, 200
        ),
        $col_poly);

    // Mostra a imagem no navegador
    header('Content-type: image/png');

    imagepng($image);
    ?>

O exemplo acima produzirá algo semelhante a:

### Veja Também

- imagefilledpolygon() - Desenha um polígono preenchido
- imageopenpolygon() - Desenha um polígono aberto
- imagecreate() - Crie uma nova imagem baseada em paleta
- imagecreatetruecolor() - Cria uma nova imagem em cores verdadeiras

# imagerectangle

(PHP 4, PHP 5, PHP 7, PHP 8)

imagerectangle — Desenha um retângulo

### Descrição

function imagerectangle(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`,
int `$color`
): true

imagerectangle() cria um retângulo nas coordenadas especificadas. 0, 0 é o canto superior esquerdo da imagem.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`x1`

  Coordenada x do canto superior esquerdo.

`y1`

  Coordenada y do canto superior esquerdo.

`x2`

  Coordenada x do canto inferior direito.

`y2`

  Coordenada y do canto inferior direito.

`color`

  Um identificador de cor criado com imagecolorallocate().

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Exemplo simples de imagerectangle()

    <?php
    // Cria uma imagem 200 x 200
    $canvas = imagecreatetruecolor(200, 200);

    // Aloca cores
    $pink = imagecolorallocate($canvas, 255, 105, 180);
    $white = imagecolorallocate($canvas, 255, 255, 255);
    $green = imagecolorallocate($canvas, 132, 135, 28);

    // Desenha três retângulos cada um com sua própria cor
    imagerectangle($canvas, 50, 50, 150, 150, $pink);
    imagerectangle($canvas, 45, 60, 120, 100, $white);
    imagerectangle($canvas, 100, 120, 75, 160, $green);

    // Mostra a imagem
    header('Content-Type: image/jpeg');
    imagejpeg($canvas);
    ?>

O exemplo acima produzirá algo semelhante a:

# imageresolution

(PHP 7 >= 7.2.0, PHP 8)

imageresolution — Obtém ou define a resolução da imagem

### Descrição

function imageresolution(GdImage `$image`, ?int `$resolution_x` = `null`, ?int `$resolution_y` = `null`): array|true

imageresolution() permite definir ou obter a resolução de uma imagem em PPP (pontos por polegada). Se os parâmetros opcionais forem `null`, a resolução atual é retornada como um array indexado. Se somente `resolution_x` não for `null`, as resoluções horizontal e vertical são definidas para este valor. Se nenhum dos parâmetros opcionais for `null`, as resoluções horizontal e vertical são definidas para estes valores, respectivamente.

A resolução é usada somente como meta-informação quando imagens são lidas e gravadas de/para formatos que suportam este tipo de informação (atualmente PNG e JPEG). Ela não afeta nenhuma operação de desenho. A resolução padrão para novas imagens é 96 PPP.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`resolution_x`

  A resolução horizontal em PPP.

`resolution_y`

  A resolução vertical em PPP.

### Valor Retornado

Quando usado para obter a resolução, retorna um array indexado das resoluções horizontal e vertical em caso de sucesso. Quando usado para definir a resolução, sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `resolution_x` e `resolution_y` agora podem ser nulos.

### Exemplos

Exemplo #1 Definindo e obtendo a resolução de uma imagem

    <?php
    $im = imagecreatetruecolor(100, 100);
    imageresolution($im, 200);
    print_r(imageresolution($im));
    imageresolution($im, 300, 72);
    print_r(imageresolution($im));
    ?>

O exemplo acima produzirá:

    Array
    (
        [0] => 200
        [1] => 200
    )
    Array
    (
        [0] => 300
        [1] => 72
    )

# imagerotate

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imagerotate — Rotaciona uma imagem em um ângulo informado

### Descrição

function imagerotate(GdImage `$image`, float `$angle`, int `$background_color`): GdImage|false

Rotaciona a imagem informada em `image` usando o ângulo, em graus, definido por `angle`.

O centro de rotação é o centro da image, e a imagem rotacionada pode ter dimensões diferentes da imagem original.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`angle`

  Ângulo de rotação, em graus. O ângulo de rotação é interpretado como o número de graus a rotacionar a imagem no sentido anti-horário.

`background_color`

  Especifica a cor da área não coberta após a rotação.

### Valor Retornado

Retorna um objeto de imagem para a imagem rotacionada, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.3.0 | O parâmetro não utilizado `ignore_transparent` foi completamente removido.
8.0.0 | Em caso de sucesso, a função agora retorna uma instância GDImage; anteriormente, um resource era retornado.
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.
8.0.0 | O parâmetrop não utilizado `ignore_transparent` agora espera um bool; anteriormente era esperado um int.

### Exemplos

Exemplo #1 Rotaciona a imagem em 180 graus

Este exemplo rotaciona a imagem em 180 graus - de cabeça para baixo.

    <?php
    // Arquivo e rotação
    $filename = 'test.jpg';
    $degrees = 180;

    // Tipo de conteúdo
    header('Content-type: image/jpeg');

    // Carrega
    $source = imagecreatefromjpeg($filename);

    // Rotaciona
    $rotate = imagerotate($source, $degrees, 0);

    // Mostra
    imagejpeg($rotate);
    ?>

O exemplo acima produzirá algo semelhante a:

### Notas

> Nota: Esta função é afetada pelo método de interpolação definido por imagesetinterpolation().

### Veja Também

- imagesetinterpolation() - Define o método de interpolação

# imagesavealpha

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imagesavealpha — Informa se a informação de canal alfa deve ser retida ao gravar imagens

### Descrição

function imagesavealpha(GdImage `$image`, bool `$enable`): true

imagesavealpha() define a opção que determina se a informação completa do canal alfa deve ser retida (ao contrário de manter transparência de uma cor) ao gravar imagens. Isto somente é suportado para formatos de imagem que suportam informação de canal alfa completo, isto é, `PNG`, `WebP` e `AVIF`.

> Nota: imagesavealpha() só faz sentido para imagens `PNG`, já que o canal alfa completo é sempre gravado para `WebP` e `AVIF`. Não pe recomendado confiar neste comportamento, pois ele pode mudar no futuro. Por isso, imagesavealpha() deve ser chamada deliberadamente também para imagens `WebP` e `AVIF`.

Mesclagem de alfa tem que ser desabilitada (`imagealphablending($im, false)`) para reter o canal alfa em primeiro lugar.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`enable`

  Informa se o canal alfa deve ou não ser retido. O padrão é `false`.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Uso básico de imagesavealpha()

    <?php
    // Carrega uma imagem PNG com canal alfa
    $png = imagecreatefrompng('./alphachannel_example.png');

    // Desabilita mesclagem alfa
    imagealphablending($png, false);

    // Faz as operações desejadas

    // Define a opção de gravação alfa
    imagesavealpha($png, true);

    // Mostra imagem no navegador
    header('Content-Type: image/png');

    imagepng($png);
    ?>

### Veja Também

- imagealphablending() - Define o modo de combinação para uma imagem

# imagescale

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagescale — Muda a escala de uma imagem usando largura e altura informadas

### Descrição

function imagescale(
GdImage `$image`,
int `$width`,
int `$height` = -1,
int `$mode` = `IMG_BILINEAR_FIXED`
): GdImage|false

imagescale() escala de uma imagem usando o algoritmo de interpolação informado.

> Nota:

> Diferentemente de muitas outras funções de imagem, imagescale() não modifica o argumento `image` informado; ao invés disso, uma nova imagem é retornada.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`width`

  A largura que a imagem terá na nova escala.

`height`

  A altura que a imagem terá na nova escala. Se for omitida ou se for negativa, a razão de aspecto será preservada.

`mode`

  Uma das constantes `IMG_NEAREST_NEIGHBOUR`, `IMG_BILINEAR_FIXED` (o padrão), `IMG_BICUBIC`, `IMG_BICUBIC_FIXED` ou qualquer outro valor (neste caso será feita dupla passagem).

  > Nota: `IMG_WEIGHTED4` ainda não é suportada.

### Valor Retornado

Retorna o objeto imagem com a escala modificada em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Lança uma ValueError se `width` ou `height` puderem causar um estouro de limites.

Lança uma ValueError se `mode` for inválido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Agora lança uma ValueError se `width` ou `height` puderem causar um estouro de limites.
8.4.0 | Agora lança uma ValueError se `mode` for inválido.
8.0.0 | Em caso de sucesso, esta função agora retorna uma instância de GDImage; anteriormente, um resource era retornado.
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Veja Também

- imagecopyresized() - Copia e redimensiona parte de uma imagem
- imagecopyresampled() - Copia e redimensiona parte de uma imagem com reamostragem

# imagesetbrush

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesetbrush — Define o tipo de pincel para desenho de linhas

### Descrição

function imagesetbrush(GdImage `$image`, GdImage `$brush`): true

imagesetbrush() define a imagem de pincel para ser usada por todas as funções de desenho de linhas (como imageline() e imagepolygon()) ao desenhar com as cores especiais `IMG_COLOR_BRUSHED` ou `IMG_COLOR_STYLEDBRUSHED`.

Cuidado

Não é necessário tomar medidas especiais ao terminar de usar um pincel, mas se a imagem do pincel for destruída (ou se o PHP destruí-la), as cores `IMG_COLOR_BRUSHED` ou `IMG_COLOR_STYLEDBRUSHED` não podem ser usadas até que uma nova imagem de pincel seja definida!

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`brush`

  Um objeto de imagem.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `image` e `brush` agora esperam instâncias de GdImage anteriormente, resources eram esperados.

### Exemplos

Exemplo #1 Exemplo de imagesetbrush()

    <?php

    // Carrega uma mini logomarca do PHP
    $php = imagecreatefrompng('./php.png');

    // Cria a imagem principal, 100x100
    $im = imagecreatetruecolor(100, 100);

    // Preenche o fundo com a cor branca
    $white = imagecolorallocate($im, 255, 255, 255);
    imagefilledrectangle($im, 0, 0, 99, 99, $white);

    // Define o pincel
    imagesetbrush($im, $php);

    // Desenha um par de pincéis, um sobrepondo o outro
    imageline($im, 50, 50, 50, 60, IMG_COLOR_BRUSHED);

    // Mostra a imagem no navegador
    header('Content-type: image/png');

    imagepng($im);
    ?>

O exemplo acima produzirá algo semelhante a:

# imagesetclip

(PHP 7 >= 7.2.0, PHP 8)

imagesetclip — Define o retângulo de recorte

### Descrição

function imagesetclip(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`
): true

imagesetclip() define o retêngulo de recorte atual, isto é, a área além da qual nenhum pixel será desenhado.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`x1`

  A coordenada x do canto superior esquerdo.

`y1`

  A coordenada y do canto superior esquerdo.

`x2`

  A coordenada x do canto inferior direito.

`y2`

  A coordenada y do canto inferior direito.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Veja Também

- imagegetclip() - Obtém o retângulo de recorte

# imagesetinterpolation

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagesetinterpolation — Define o método de interpolação

### Descrição

function imagesetinterpolation(GdImage `$image`, int `$method` = `IMG_BILINEAR_FIXED`): bool

Define o método de interpolação, que afeta a renderização de várias funções da GD, tal como a função imagerotate().

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`method`

  O método de interpolação, que pode ser um dos seguintes:

  - `IMG_BELL`: Filtro Bell.
  - `IMG_BESSEL`: Filtro Bessel.
  - `IMG_BICUBIC`: Interpolação bicúbica.
  - `IMG_BICUBIC_FIXED`: Implementação de ponto fixo da interpolação bicúbica.
  - `IMG_BILINEAR_FIXED`: Implementação de ponto fixo da interpolação bilinear (`padrão (também na criação da imagem)`).
  - `IMG_BLACKMAN`: Função de janela Blackman.
  - `IMG_BOX`: Filtro de desfoque de caixa.
  - `IMG_BSPLINE`: Interpolação Spline.
  - `IMG_CATMULLROM`: Interpolação Spline Hermite cúbica.
  - `IMG_GAUSSIAN`: Função gaussiana.
  - `IMG_GENERALIZED_CUBIC`: Interpolação fractal spline cúbica generalizada.
  - `IMG_HERMITE`: Interpolação Hermite.
  - `IMG_HAMMING`: Filtro Hamming.
  - `IMG_HANNING`: Filtro Hanning.
  - `IMG_MITCHELL`: Filtro Mitchell.
  - `IMG_POWER`: Interpolation de potência.
  - `IMG_QUADRATIC`: Interpolação quadrática inversa.
  - `IMG_SINC`: Função sinc.
  - `IMG_NEAREST_NEIGHBOUR`: Interpolação do ponto mais próximo.
  - `IMG_WEIGHTED4`: Filtro ponderado.
  - `IMG_TRIANGLE`: Interpolação triangular.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imagesetinterpolation()

    <?php
    // Carrega uma imagem
    $im = imagecreate(500, 500);

    // Por padrão a interpolação é IMG_BILINEAR_FIXED, trocando
    // para o filtro 'Mitchell':
    imagesetinterpolation($im, IMG_MITCHELL);

    // Continua o trabalho com $im ...
    ?>

### Notas

Alterar o método de interpolação afeta as seguintes funções durante a renderização:

- imageaffine()
- imagerotate()

### Veja Também

- imagegetinterpolation() - Obtém o método de interpolação

# imagesetpixel

(PHP 4, PHP 5, PHP 7, PHP 8)

imagesetpixel — Desenha um pixel

### Descrição

function imagesetpixel(
GdImage `$image`,
int `$x`,
int `$y`,
int `$color`
): true

imagesetpixel() desenha um pixel na coordenada especificada.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`x`

  Coordenada x.

`y`

  Coordenada y.

`color`

  Um identificador de cor criado com imagecolorallocate().

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imagesetpixel()

Um desenho aleatório que termina com uma imagem normal.

    <?php

    $x = 200;
    $y = 200;

    $gd = imagecreatetruecolor($x, $y);

    $corners[0] = array('x' => 100, 'y' =>  10);
    $corners[1] = array('x' =>   0, 'y' => 190);
    $corners[2] = array('x' => 200, 'y' => 190);

    $red = imagecolorallocate($gd, 255, 0, 0);

    for ($i = 0; $i < 100000; $i++) {
      imagesetpixel($gd, round($x), round($y), $red);
      $a = rand(0, 2);
      $x = ($x + $corners[$a]['x']) / 2;
      $y = ($y + $corners[$a]['y']) / 2;
    }

    header('Content-Type: image/png');
    imagepng($gd);

    ?>

O exemplo acima produzirá algo semelhante a:

### Veja Também

- imagecreatetruecolor() - Cria uma nova imagem em cores verdadeiras
- imagecolorallocate() - Aloca uma cor para uma imagem
- imagecolorat() - Obtém o índica da cor de um pixel

# imagesetstyle

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesetstyle — Define o estilo para desenho de linhas

### Descrição

function imagesetstyle(GdImage `$image`, array `$style`): bool

imagesetstyle() define o estilo para ser usado por todas as funções de desenho de linhas (tal como imageline() e imagepolygon()) ao desenhar com as cores especiais `IMG_COLOR_STYLED` ou linhas de imagens com a cor `IMG_COLOR_STYLEDBRUSHED`.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`style`

  Um array de cores de pixel. Pode-se usar a constante `IMG_COLOR_TRANSPARENT` para adicionar um pixel transparente. Observe que `style` não pode ser um array vazio.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

O exemplo a seguir desenha uma linha tracejada do canto superior esquerdo para o inferior direito da imagem:

Exemplo #1 Exemplo de imagesetstyle()

    <?php
    header("Content-type: image/jpeg");
    $im  = imagecreatetruecolor(100, 100);
    $w   = imagecolorallocate($im, 255, 255, 255);
    $red = imagecolorallocate($im, 255, 0, 0);

    /* Desenha uma linha tracejada, 5 pixels vermelhos, 5 brancos */
    $style = array($red, $red, $red, $red, $red, $w, $w, $w, $w, $w);
    imagesetstyle($im, $style);
    imageline($im, 0, 0, 100, 100, IMG_COLOR_STYLED);

    /* Desenha uma linha de rostos felizes usando imagesetbrush() com imagesetstyle */
    $style = array($w, $w, $w, $w, $w, $w, $w, $w, $w, $w, $w, $w, $red);
    imagesetstyle($im, $style);

    $brush = imagecreatefrompng("http://www.libpng.org/pub/png/images/smile.happy.png");
    $w2 = imagecolorallocate($brush, 255, 255, 255);
    imagecolortransparent($brush, $w2);
    imagesetbrush($im, $brush);
    imageline($im, 100, 0, 0, 100, IMG_COLOR_STYLEDBRUSHED);

    imagejpeg($im);
    ?>

O exemplo acima produzirá algo semelhante a:

### Veja Também

- imagesetbrush() - Define o tipo de pincel para desenho de linhas
- imageline() - Desenha uma linha

# imagesetthickness

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesetthickness — Define a espessura para desenho de linhas

### Descrição

function imagesetthickness(GdImage `$image`, int `$thickness`): true

imagesetthickness() define a espessura para as linhas ao desenhar retângulos, polígonos, arcos, etc. para o valor de `thickness` em pixels.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`thickness`

  Espessura, em pixels.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imagesetthickness()

    <?php

    // Cria uma imagem 200x100
    $im = imagecreatetruecolor(200, 100);
    $white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);
    $black = imagecolorallocate($im, 0x00, 0x00, 0x00);

    // Fundo branco
    imagefilledrectangle($im, 0, 0, 199, 99, $white);

    // Espessura da linha de 5 pixels
    imagesetthickness($im, 5);

    // Desenha o retângulo
    imagerectangle($im, 14, 14, 185, 85, $black);

    // Mostra no navegador
    header('Content-Type: image/png');

    imagepng($im);
    ?>

O exemplo acima produzirá algo semelhante a:

# imagesettile

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesettile — Define a imagem de ladrilho para preenchimento

### Descrição

function imagesettile(GdImage `$image`, GdImage `$tile`): true

imagesettile() define a imagem de ladrilho para ser usada por todas as funções de preenchimento de região (tal como imagefill() e imagefilledpolygon()) ao preencher com a cor especial `IMG_COLOR_TILED`.

O ladrilho é uma imagem usada para preencher uma área com um padrão repetido. Qualquer imagem GD pode ser usada como ladrilho, e ao definir o índice de cor transparente da imagem de ladrilho com imagecolortransparent(), permite-se que certas partes da área subjacente apareçam.

Cuidado

Não é necessário tomar ações especiais ao terminar de usar uma imagem de ladrilho, mas se ela for destruída, a cor `IMG_COLOR_TILED` não poderá ser usada até que uma nova imagem de ladrilho seja definida!

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`tile`

  O objeto imagem a ser usado como ladrilho.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `image` e `tile` agora esperam instâncias GdImage; anteriormente, resources eram esperados.

### Exemplos

Exemplo #1 Exemplo de imagesettile()

    <?php
    // Carrega uma imagem externa
    $zend = imagecreatefromgif('./zend.gif');

    // Cria uma imagem 200x200
    $im = imagecreatetruecolor(200, 200);

    // Define o ladrilho
    imagesettile($im, $zend);

    // Faz a imagem se repetir
    imagefilledrectangle($im, 0, 0, 199, 199, IMG_COLOR_TILED);

    // Mostra a imagem no navegador
    header('Content-Type: image/png');

    imagepng($im);
    ?>

O exemplo acima produzirá algo semelhante a:

# imagestring

(PHP 4, PHP 5, PHP 7, PHP 8)

imagestring — Desenha uma string na horizontal

### Descrição

function imagestring(
GdImage `$image`,
GdFont|int `$font`,
int `$x`,
int `$y`,
string `$string`,
int `$color`
): true

Desenha uma `string` nas coordenadas informadas.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`font`
  Pode ser 1, 2, 3, 4, 5 para as fontes nativas na codificação latin2 (onde números maiores correspondem a fontes maiores) ou uma instância de GdFont, retornada por imageloadfont().
`x`

  Coordenada x do canto superior esquerdo.

`y`

  Coordenada y do canto superior esquerdo.

`string`

  A string a ser desenhada.

`color`

  Um identificador de cor criado com imagecolorallocate().

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `font` agora aceita uma instância de GdFont ou um int; anteriormente, apenas int era aceito.
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imagestring()

    <?php
    // Cria uma imagem 100*30
    $im = imagecreate(100, 30);

    // Fundo branco e texto azul
    $bg = imagecolorallocate($im, 255, 255, 255);
    $textcolor = imagecolorallocate($im, 0, 0, 255);

    // Desenha o texto no canto superior esquerdo
    imagestring($im, 5, 0, 0, 'Hello world!', $textcolor);

    // Mostra a imagem
    header('Content-type: image/png');

    imagepng($im);
    ?>

O exemplo acima produzirá algo semelhante a:

### Veja Também

- imagestringup() - Desenha uma string na vertical
- imageloadfont() - Carrega uma nova fonte
- imagettftext() - Escreve texto na imagem usando fontes TrueType

# imagestringup

(PHP 4, PHP 5, PHP 7, PHP 8)

imagestringup — Desenha uma string na vertical

### Descrição

function imagestringup(
GdImage `$image`,
GdFont|int `$font`,
int `$x`,
int `$y`,
string `$string`,
int `$color`
): true

Desenha uma `string` na vertical nas coordenadas informadas.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`font`
  Pode ser 1, 2, 3, 4, 5 para as fontes nativas na codificação latin2 (onde números maiores correspondem a fontes maiores) ou uma instância de GdFont, retornada por imageloadfont().
`x`

  Coordenada x do canto inferior esquerdo.

`y`

  Coordenada y do canto inferior esquerdo.

`string`

  O texto a ser desenhado.

`color`

  Um identificador de cor criado com imagecolorallocate().

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `font` agora aceita uma instância de GdFont ou um int; anteriormente, apenas int era aceito.
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imagestringup()

    <?php
    // cria uma imagem 100*100
    $im = imagecreatetruecolor(100, 100);

    // Desenha o texto
    $textcolor = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);
    imagestringup($im, 3, 40, 80, 'gd library', $textcolor);

    // Grava a imagem
    imagepng($im, './stringup.png');
    ?>

O exemplo acima produzirá algo semelhante a:

### Veja Também

- imagestring() - Desenha uma string na horizontal
- imageloadfont() - Carrega uma nova fonte

# imagesx

(PHP 4, PHP 5, PHP 7, PHP 8)

imagesx — Obtém a largura da imagem

### Descrição

function imagesx(GdImage `$image`): int

Retorna a largura do objeto informado em `image`.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().

### Valor Retornado

Retorna a largura de `image`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Usando imagesx()

    <?php

    // cria uma imagem de 300*200
    $img = imagecreatetruecolor(300, 200);

    echo imagesx($img); // 300

    ?>

### Veja Também

- imagecreatetruecolor() - Cria uma nova imagem em cores verdadeiras
- getimagesize() - Obtém o tamanho de uma imagem
- imagesy() - Obtém a altura da imagem

# imagesy

(PHP 4, PHP 5, PHP 7, PHP 8)

imagesy — Obtém a altura da imagem

### Descrição

function imagesy(GdImage `$image`): int

Retorna a altura do objeto informado em `image`.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().

### Valor Retornado

Retorna a altura de `image`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Usando imagesy()

    <?php

    // create a 300*200 image
    $img = imagecreatetruecolor(300, 200);

    echo imagesy($img); // 200

    ?>

### Veja Também

- imagecreatetruecolor() - Cria uma nova imagem em cores verdadeiras
- getimagesize() - Obtém o tamanho de uma imagem
- imagesx() - Obtém a largura da imagem

# imagetruecolortopalette

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagetruecolortopalette — Converte uma imagem em cores verdadeiras em uma imagem de paleta

### Descrição

function imagetruecolortopalette(GdImage `$image`, bool `$dither`, int `$num_colors`): bool

imagetruecolortopalette() converte uma imagem em cores verdadeiras em uma imagem de paleta. O código para esta função foi originalmente escrito a partir do código da biblioteca do Independent JPEG Group, que é excelente. O código foi modificado para preservar o máximo possível de informação do canal alfa na paleta resultante, além de preservar as cores da melhor maneira possível. Isto não funciona tão bem quanto esperado. Normalmente é melhor simplesmente produzir uma imagem em cores verdadeiras, o que garante a qualidade de saída mais alta possível.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`dither`

  Indica se a imagem deve ser pontilhada - se for `true` o pontilhamento será usado, o que resultará em uma imagem mais salpicada mas com uma melhor aproximação de cores.

`num_colors`

  Define o número máximo de cores que deve sem mantido na paleta.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Convertendo uma imagem em cores verdadeiras em uma imagem de paleta

    <?php
    // Cria uma nova imagem em cores verdadeiras
    $im = imagecreatetruecolor(100, 100);

    // Converte para paleta sem pontilhamento e com 255 cores
    imagetruecolortopalette($im, false, 255);

    // Grava a imagem
    imagepng($im, './paletteimage.png');
    ?>

# imagettfbbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imagettfbbox — Fornece a os limites retangulares de um texto usando fontes TrueType

### Descrição

function imagettfbbox(
float `$size`,
float `$angle`,
string `$font_filename`,
string `$string`,
array `$options` = []
): array|false

Esta função calcula e retorna os limites retangulares em pixels para um texto TrueType.

> Nota:

> Antes do PHP 8.0.0, imageftbbox() era uma variante estendida de imagettfbbox() que adicionalmente suportava o parâmetro `extrainfo`. A partir do PHP 8.0.0, imagettfbbox() é um apelido de imageftbbox().

### Parâmetros

`size`

  O tamanho da fonte em pontos.

`angle`

  Ângulo em graus em que a `string` será medida.

`fontfile`
  O caminho para a fonte TrueType que será usada. Dependendo de qual versão da biblioteca GD o PHP estiver usando, quando `fontfile` não começar com uma `/` então `.ttf` será adicionado ao nome do arquivo e a biblioteca tentará procurá-lo em um caminho de fontes definido pela biblioteca. Ao usar versões da biblioteca GD anteriores à versão 2.0.18, um caractere `espaço`, em vez de um ponto-e-vírgula, foi usado como 'separador de caminho' para diferentes arquivos de fonte. O uso não intencional desse recurso resultará na mensagem de aviso: `Warning: Could not find/open font`. Para essas versões afetadas, a única solução é mover a fonte para um caminho que não contenha espaços.

  Em muitos casos em que uma fonte reside no mesmo diretório que o script que a usa, o truque a seguir aliviará qualquer problema de inclusão.

      <?php
      // Define a variável de ambiente GDFONTPATH
      putenv('GDFONTPATH=' . realpath('.'));

      // Define a fonte a ser usada (observe a ausência da extensão .ttf)
      $font = 'SomeFont';
      ?>

  > Nota: Note que open_basedir não se aplica a `fontfile`.

`string`

  A string a ser medida.

`options`

  Consulte a função imagettftext().

### Valor Retornado

imagettfbbox() retorna um array com 8 elementos representando quatro pontos que definem os limites retangulares do texto em caso de sucesso e `false` em caso de erro.

key | contents
--- | ---
0 | canto inferior esquerdo, posição X
1 | canto inferior esquerdo, posição Y
2 | canto inferior direito, posição X
3 | canto inferior direito, posição Y
4 | canto superior direito, posição X
5 | canto superior direito, posição Y
6 | canto superior esquerdo, posição X
7 | canto superior esquerdo, posição Y

Os pontos são relativos ao texto, independente do parâmetro `angle`, portanto "superior esquerdo" significa no canto superior esquerdo ao ver o texto na horizontal.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `options` foi adicionado.

### Exemplos

Exemplo #1 Exemplo de imagettfbbox()

    <?php
    // Cria uma imagem 300x150
    $im = imagecreatetruecolor(300, 150);
    $black = imagecolorallocate($im, 0, 0, 0);
    $white = imagecolorallocate($im, 255, 255, 255);

    // Fundo branco
    imagefilledrectangle($im, 0, 0, 299, 299, $white);

    // Caminho para o arquivo da fonte
    $font = './arial.ttf';

    // Primeiro é criado o retângulo limite para o primeiro texto
    $bbox = imagettfbbox(10, 45, $font, 'Powered by PHP ' . phpversion());

    // Estas são as coordenadas de X e Y
    $x = $bbox[0] + (imagesx($im) / 2) - ($bbox[4] / 2) - 25;
    $y = $bbox[1] + (imagesy($im) / 2) - ($bbox[5] / 2) - 5;

    // Escreve
    imagettftext($im, 10, 45, $x, $y, $black, $font, 'Powered by PHP ' . phpversion());

    // O próximo retângulo limite é criado para o segundo texto
    $bbox = imagettfbbox(10, 45, $font, 'and Zend Engine ' . zend_version());

    // Define as coordenadas de forma que fique próxima ao primeiro texto
    $x = $bbox[0] + (imagesx($im) / 2) - ($bbox[4] / 2) + 10;
    $y = $bbox[1] + (imagesy($im) / 2) - ($bbox[5] / 2) - 5;

    // Escreve
    imagettftext($im, 10, 45, $x, $y, $black, $font, 'and Zend Engine ' . zend_version());

    // Mostra no navegador
    header('Content-Type: image/png');

    imagepng($im);
    ?>

### Notas

> Nota: Esta função só estará disponível se o PHP for compilado com suporte ao freetype (--with-freetype-dir=DIR).

### Veja Também

- imagettftext() - Escreve texto na imagem usando fontes TrueType
- imageftbbox() - Fornece a caixa limite de um texto usando fontes via freetype2

# imagettftext

(PHP 4, PHP 5, PHP 7, PHP 8)

imagettftext — Escreve texto na imagem usando fontes TrueType

### Descrição

function imagettftext(
GdImage `$image`,
float `$size`,
float `$angle`,
int `$x`,
int `$y`,
int `$color`,
string `$font_filename`,
string `$text`,
array `$options` = []
): array|false

Escreve o texto definido em `text` na imagem, usando fontes TrueType.

> Nota:

> Antes do PHP 8.0.0, imagefttext() era uma variante estendida de imagettftext() que adicionalmente suportava o parâmetro `extrainfo`. A partir do PHP 8.0.0, imagettftext() é um apelido de imagefttext().

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`size`

  O tamanho da fonte em pontos.

`angle`

  O ângulo em graus, com 0 grau sendo um texto lido da esquerda para a direita. Valores mais altos representam uma rotação no sentido anti-horário. Por exemplo, um valor de 90 resultaria em um texto lido de baixo para cima.

`x`

  A coordenada fornecida por `x` e `y` definirá o ponto base do primeiro caractere (aproximadamente o canto inferior esquerdo do caractere). Isto é diferente de imagestring(), onde `x` e `y` definem o canto superior esquerdo do primeiro caractere. Por exemplo, "superior esquerdo" é 0, 0.

`y`

  A ordenada y. Define a posição da linha base das fontes, e não a parte mais baixa do caractere.

`color`

  O índica de cor. Usar o valor negativo de um índice de cor tem o efeito de desligar a redução de serrilhado. Consulte imagecolorallocate().

`fontfile`
  O caminho para a fonte TrueType que será usada. Dependendo de qual versão da biblioteca GD o PHP estiver usando, quando `fontfile` não começar com uma `/` então `.ttf` será adicionado ao nome do arquivo e a biblioteca tentará procurá-lo em um caminho de fontes definido pela biblioteca. Ao usar versões da biblioteca GD anteriores à versão 2.0.18, um caractere `espaço`, em vez de um ponto-e-vírgula, foi usado como 'separador de caminho' para diferentes arquivos de fonte. O uso não intencional desse recurso resultará na mensagem de aviso: `Warning: Could not find/open font`. Para essas versões afetadas, a única solução é mover a fonte para um caminho que não contenha espaços.

  Em muitos casos em que uma fonte reside no mesmo diretório que o script que a usa, o truque a seguir aliviará qualquer problema de inclusão.

      <?php
      // Define a variável de ambiente GDFONTPATH
      putenv('GDFONTPATH=' . realpath('.'));

      // Define a fonte a ser usada (observe a ausência da extensão .ttf)
      $font = 'SomeFont';
      ?>

  > Nota: Note que open_basedir não se aplica a `fontfile`.

`text`

  A string de texto em codificação UTF-8.

  Pode incluir referências a caracteres numéricos decimais (na forma: `&#8364;`) para acessar caracteres em uma fonte além da posição 127. O formato hexadecimal (como `&#xA9;`) é suportado. Strings em codificação UTF-8 pode ser passado diretamente.

  Entidades nomeadas, tal como `&copy;`, não são suportadas. Considere usar html_entity_decode() para decodificar estas entidades nomeadas em strings UTF-8.

  Se um caractere usado na string não for suportado pela fonte, um retêngulo vazado substituirá o caractere.

`options`

  Um array com a chave `linespacing` contendo um valor float.

### Valor Retornado

Retorna um array com 8 elementos representando quatro pontos que formam o retângulo limite do texto. A ordem dos pontos é inferior esquerdo, inferior direito, superior direito, superior esquerdo. Os pontos são relativos ao texto independente do ângulo, portanto "superior esquerdo" significa o canto superior esquerdo quando o texto é visto na horizontal. Retorna `false` em caso de erros.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `options` foi adicionado.

### Exemplos

Exemplo #1 Exemplo de imagettftext()

Este script de exemplo produz um PNG branco de 400x30 pixels, com a palavra "Testing..." em preto (com sombra cinza), na fonte Arial.

    <?php

    // Define o tipo de conteúdo
    header('Content-Type: image/png');

    // Cria a imagem
    $im = imagecreatetruecolor(400, 30);

    // Cria algumas cores
    $white = imagecolorallocate($im, 255, 255, 255);
    $grey = imagecolorallocate($im, 128, 128, 128);
    $black = imagecolorallocate($im, 0, 0, 0);
    imagefilledrectangle($im, 0, 0, 399, 29, $white);

    // O texto a ser desenhado
    $text = 'Testing...';

    // Substitui o caminho da fonte
    $font = 'arial.ttf';

    // Adiciona sombra ao texto
    imagettftext($im, 20, 0, 11, 21, $grey, $font, $text);

    // Adiciona o texto
    imagettftext($im, 20, 0, 10, 20, $black, $font, $text);

    // Usar imagepng() resulta em um texto mais nítido comparado com imagejpeg()
    imagepng($im);

    ?>

O exemplo acima produzirá algo semelhante a:

### Notas

> Nota: Esta função só estará disponível se o PHP for compilado com suporte ao freetype (--with-freetype-dir=DIR).

### Veja Também

- imagettfbbox() - Fornece a os limites retangulares de um texto usando fontes TrueType
- imagefttext() - Escreve texto em uma imagem usando fontes FreeType 2
- imagestring() - Desenha uma string na horizontal

# imagetypes

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

imagetypes — Retorna os tipos de imagens suportados pela instalação do PHP

### Descrição

function imagetypes(): int

Retorna os tipos de imagens suportados pela instalação atual do PHP.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um campo de bits correspondente aos formatos de imagem suportados pela versão da GD linkada no PHP. Os seguintes bits são retornados: `IMG_AVIF` | `IMG_BMP` | `IMG_GIF` | `IMG_JPG` | `IMG_PNG` | `IMG_WBMP` | `IMG_XPM` | `IMG_WEBP`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | `IMG_AVIF` adicionado.
7.2.0 | `IMG_BMP` adicionado.
7.0.10 | `IMG_WEBP` adicionado.

### Exemplos

Exemplo #1 Verificando o suporte a PNG

    <?php
    if (imagetypes() & IMG_PNG) {
        echo "O suporte a PNG está ativado";
    }
    ?>

### Veja Também

- gd_info() - Obtém informações sobre a biblioteca GD instalada atualmente

# imagewbmp

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagewbmp — Envia a imagem para o navegador ou para um arquivo

### Descrição

function imagewbmp(GdImage `$image`, resource|string|null `$file` = `null`, ?int `$foreground_color` = `null`): bool

imagewbmp() mostra ou grava uma versão WBMP da imagem informada em `image`.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`file`

  O caminho ou um recurso de fluxo aberto (que será fechado automaticamente após o retorno desta função) para salvar o arquivo. Se não for definido ou for `null`, o fluxo da imagem bruta será enviado diretamente.

`foreground_color`

  Pode-se definir a cor de primeiro plano com este parâmetro, configurando-se um identificador obtido a partir da função imagecolorallocate(). A cor de primeiro plano padrão é preta.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

Cuidado

Entretanto, se a biblioteca libgd falhar ao gerar a imagem, esta função retornará `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.
8.0.0 | `foreground_color` agora pode ser nulo.

### Exemplos

Exemplo #1 Mostrando uma imagem WBMP

    <?php
    // Cria uma imagem vazia e adiciona texto
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // Define o cabeçalho de tipo de conteúdo - neste caso image/vnd.wap.wbmp
    // Dica: veja image_type_to_mime_type() para tipos de conteúdo
    header('Content-Type: image/vnd.wap.wbmp');

    // Mostra a imagem
    imagewbmp($im);
    ?>

Exemplo #2 Gravando a imagem WBMP

    <?php
    // Cria uma imagem vazia e adiciona texto
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // Grava a imagem
    imagewbmp($im, 'simpletext.wbmp');
    ?>

Exemplo #3 Mostrando a imagem com primeiro plano diferente

    <?php
    // Cria uma imagem vazia e adiciona texto
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // Define o cabeçalho de tipo de conteúdo - neste caso image/vnd.wap.wbmp
    // Dica: veja image_type_to_mime_type() para tipos de conteúdo
    header('Content-Type: image/vnd.wap.wbmp');

    // Define uma cor substituta para primeiro plano
    $foreground_color = imagecolorallocate($im, 255, 0, 0);

    imagewbmp($im, NULL, $foreground_color);
    ?>

### Veja Também

- image2wbmp() - Envia a imagem para o navegador ou para um arquivo
- imagepng() - Envia uma imagem PNG para o navegador ou arquivo
- imagegif() - Envia a imagem para o navegador ou para um arquivo
- imagejpeg() - Envia a imagem para o navegador ou para um arquivo
- imagetypes() - Retorna os tipos de imagens suportados pela instalação do PHP

# imagewebp

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

imagewebp — Mostra uma imagem WebP no navegador ou grava em arquivo

### Descrição

function imagewebp(GdImage `$image`, resource|string|null `$file` = `null`, int `$quality` = -1): bool

Mostra ou grava uma versão WebP da imagem informada em `image`.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`file`

  O caminho ou um recurso de fluxo aberto (que será fechado automaticamente após o retorno desta função) para salvar o arquivo. Se não for definido ou for `null`, o fluxo da imagem bruta será enviado diretamente.

`quality`

  `quality` varia de 0 (pior qualidade, arquivo menor) a 100 (melhor qualidade, arquivo maior). Se `-1` for informado, o valor padrão de `80` será usado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

Cuidado

Entretanto, se a biblioteca libgd falhar ao gerar a imagem, esta função retornará `true`.

### Erros/Exceções

Lança um ValueError se `quality` for inválido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Agora lança um ValueError se `quality` for inválido.
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.

### Exemplos

Exemplo #1 Gravando um arquivo WebP

    <?php
    // Cria uma imagem vazia e adiciona texto
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);

    imagestring($im, 1, 5, 5,  'WebP with PHP', $text_color);

    // Grava a imagem
    imagewebp($im, 'php.webp');
    ?>

# imagexbm

(PHP 5, PHP 7, PHP 8)

imagexbm — Mostra uma imagem XBM em um navegador ou grava em arquivo

### Descrição

function imagexbm(GdImage `$image`, ?string `$filename`, ?int `$foreground_color` = `null`): bool

Mostra ou grava uma versão XBM da imagem informada em `image`.

> Nota: imagexbm() não aplica nenhum deslocamento, portanto a largura da imagem deve ser um múltiplo de 8. Esta restrição não se aplica mais a partir do PHP 7.0.9.

### Parâmetros

`image`
  Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().
`filename`

  O caminho do arquivo a ser gravado, fornecido como string. Se for `null`, o fluxo bruto da imagem será enviado diretamente.

  O nome de arquivo em `filename` (sem a extensão .xbm) também é usado para o identificadores C do XBM, onde caracteres não alfanuméricos da localidade atual são substituídos por sublinhados. Se `filename` for definido para `null`, `image` é usado para construir os identificadores C.

`foreground_color`

  Pode-se definir a cor de primeiro plano com este parâmetro configurando um identificador obtido a partir da função imagecolorallocate(). A cor de primeiro plano padrão é preta. Todas as outras cores são tratadas como cores de fundo.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

Cuidado

Entretanto, se a biblioteca libgd falhar ao gerar a imagem, esta função retornará `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.
8.0.0 | `foreground_color` agora pode ser nulo.
8.0.0 | O quarto parâmetro, que não era usado, foi removido.

### Exemplos

Exemplo #1 Gravando um arquivo XBM

    <?php
    // Cria uma imagem vazia e adiciona texto
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // Grava a imagem
    imagexbm($im, 'simpletext.xbm');
    ?>

Exemplo #2 Gravando um arquivo XBM com uma cor de fundo diferente

    <?php
    // Cria uma imagem vazia e adiciona texto
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // Define uma cor substituta para primeiro plano
    $foreground_color = imagecolorallocate($im, 255, 0, 0);

    // Grava a imagem
    imagexbm($im, NULL, $foreground_color);
    ?>

# iptcembed

(PHP 4, PHP 5, PHP 7, PHP 8)

iptcembed — Incorpora dados binários IPTC em uma imagem JPEG

### Descrição

function iptcembed(string `$iptc_data`, string `$filename`, int `$spool` = 0): string|bool

Incorpora dados binários IPTC em uma imagem JPEG.

### Parâmetros

`iptc_data`

  Os dados a serem escritos.

`filename`

  Caminho para a imagem JPEG.

`spool`

  Opção de enfileiramento. Se esta opção for menor que 2, o JPEG será retornado como uma string. Caso contrário será mostrado em STDOUT.

### Valor Retornado

Se `spool` for menor que 2, o JPEG será retornado, ou `false` em caso de falha. Caso contrário, retorna `true` se bem sucedido ou `false` em caso de falha.

### Exemplos

Exemplo #1 Incorporando dados IPTC em um JPEG

    <?php

    // função iptc_make_tag() por Thies C. Arntzen
    function iptc_make_tag($rec, $data, $value)
    {
        $length = strlen($value);
        $retval = chr(0x1C) . chr($rec) . chr($data);

        if($length < 0x8000)
        {
            $retval .= chr($length >> 8) .  chr($length & 0xFF);
        }
        else
        {
            $retval .= chr(0x80) .
                       chr(0x04) .
                       chr(($length >> 24) & 0xFF) .
                       chr(($length >> 16) & 0xFF) .
                       chr(($length >> 8) & 0xFF) .
                       chr($length & 0xFF);
        }

        return $retval . $value;
    }

    // Caminho para o arquivo JPEG
    $path = './phplogo.jpg';

    // Define as etiquetas IPTC
    $iptc = array(
        '2#120' => 'Test image',
        '2#116' => 'Copyright 2008-2009, The PHP Group'
    );

    // Converte as etiquetas IPTC em código binário
    $data = '';

    foreach($iptc as $tag => $string)
    {
        $tag = substr($tag, 2);
        $data .= iptc_make_tag(2, $tag, $string);
    }

    // Incorpora os dados IPTC
    $content = iptcembed($data, $path);

    // Grava os novos dados de imagem no arquivo.
    $fp = fopen($path, "wb");
    fwrite($fp, $content);
    fclose($fp);
    ?>

### Notas

> Nota: Esta função não requer a biblioteca de imagens GD.

# iptcparse

(PHP 4, PHP 5, PHP 7, PHP 8)

iptcparse — Interpreta um bloco IPTC binário em etiquetas simples

### Descrição

function iptcparse(string `$iptc_block`): array|false

Interpreta um bloco » IPTC em etiquetas simples.

### Parâmetros

`iptc_block`

  Um bloco binário IPTC.

### Valor Retornado

Retorna um array usando o marcador de etiquetas como um índice e o valor como o valor. Retorna `false` em caso de erro ou se nenhum dado IPTC for encontrado.

### Exemplos

Exemplo #1 iptcparse() usado junto com getimagesize()

    <?php
    $size = getimagesize('./test.jpg', $info);
    if(isset($info['APP13']))
    {
        $iptc = iptcparse($info['APP13']);
        var_dump($iptc);
    }
    ?>

### Notas

> Nota: Esta função não requer a biblioteca de imagens GD.

# jpeg2wbmp

(PHP 4 >= 4.0.5, PHP 5, PHP 7)

jpeg2wbmp — Converte arquivo de imagem JPEG para WBMP

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.2.0 e foi REMOVIDA a partir do PHP 8.0.0. O uso desta função é fortemente desencorajado.

### Descrição

function jpeg2wbmp(
string `$jpegname`,
string `$wbmpname`,
int `$dest_height`,
int `$dest_width`,
int `$threshold`
): bool

Converte um arquivo JPEG em um WBMP.

### Parâmetros

`jpegname`

  Caminho para o arquivo JPEG.

`wbmpname`

  Caminho para o arquivo WBMP de destino.

`dest_height`

  Altura da imagem de destino.

`dest_width`

  Largura da imagem de destino.

`threshold`

  Valor de limite, entre 0 e 8 (inclusive).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

Cuidado

Entretanto, se a biblioteca libgd falhar ao gerar a imagem, esta função retornará `true`.

### Exemplos

Exemplo #1 Exemplo de jpeg2wbmp()

    <?php
    // Caminho para o JPEG alvo
    $path = './test.jpg';

    // Obtém o tamanho da imagem
    $image = getimagesize($path);

    // Converte a imagem
    jpeg2wbmp($path, './test.wbmp', $image[1], $image[0], 5);
    ?>

### Veja Também

- png2wbmp() - Converte arquivo de imagem PNG em WBMP

# png2wbmp

(PHP 4 >= 4.0.5, PHP 5, PHP 7)

png2wbmp — Converte arquivo de imagem PNG em WBMP

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.2.0 e foi REMOVIDA a partir do PHP 8.0.0. O uso desta função é fortemente desencorajado.

### Descrição

function png2wbmp(
string `$pngname`,
string `$wbmpname`,
int `$dest_height`,
int `$dest_width`,
int `$threshold`
): bool

Converte um arquivo PNG em um WBMP.

### Parâmetros

`pngname`

  Caminho para o arquivo PNG.

`wbmpname`

  Caminho para o arquivo WBMP de destino.

`dest_height`

  Altura da imagem de destino.

`dest_width`

  Largura da imagem de destino.

`threshold`

  Valor de limite, entre 0 e 8 (inclusive).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

Cuidado

Entretanto, se a biblioteca libgd falhar ao gerar a imagem, esta função retornará `true`.

### Exemplos

Exemplo #1 Exemplo de png2wbmp()

    <?php
    // Caminho para o PNG alvo
    $path = './test.png';

    // Obtém o tamanho da imagem
    $image = getimagesize($path);

    // Converte a imagem
    png2wbmp($path, './test.wbmp', $image[1], $image[0], 7);
    ?>

### Veja Também

- jpeg2wbmp() - Converte arquivo de imagem JPEG para WBMP

## Índice

- gd_info — Obtém informações sobre a biblioteca GD instalada atualmente
- getimagesize — Obtém o tamanho de uma imagem
- getimagesizefromstring — Obtém o tamanho de uma imagem a partir de uma string
- image_type_to_extension — Obtém a extensão de arquivo para o tipo da imagem
- image_type_to_mime_type — Obtém o Mime-Type para o tipo de imagem retornado por getimagesize, exif_read_data, exif_thumbnail e exif_imagetype
- image2wbmp — Envia a imagem para o navegador ou para um arquivo
- imageaffine — Retorna uma imagem contendo a imagem fonte com transformação afim, usando uma área de recorte opcional
- imageaffinematrixconcat — Concatena duas matrizes de transformação afim
- imageaffinematrixget — Obtém uma matriz de transformação afim
- imagealphablending — Define o modo de combinação para uma imagem
- imageantialias — Define se as funções de suavização de serrilhado devem ser usadas ou não
- imagearc — Desenha um arco
- imageavif — Envia a imagem para o navegador ou para um arquivo
- imagebmp — Mostra ou grava uma imagem BMP
- imagechar — Desenha um caractere horizontalmente
- imagecharup — Desenha um caractere verticalmente
- imagecolorallocate — Aloca uma cor para uma imagem
- imagecolorallocatealpha — Aloca uma cor para uma imagem
- imagecolorat — Obtém o índica da cor de um pixel
- imagecolorclosest — Obtém o índice da cor mais próxima à especificada
- imagecolorclosestalpha — Obtém o índice da cor mais próxima à especificada (incluindo alfa)
- imagecolorclosesthwb — Obtém o índice da cor que tem a matiz, brancura e negritude mais próximas de uma cor informada
- imagecolordeallocate — Desaloca uma cor de uma imagem
- imagecolorexact — Obtém o índice da cor especificada
- imagecolorexactalpha — Obtém o índice da cor e alfa especificados
- imagecolormatch — Faz com que as cores da versão em paleta da imagem fiquem mais próximas da versão em cores verdadeiras
- imagecolorresolve — Obtém o índice da cor especificada ou a alternativa mais próxima
- imagecolorresolvealpha — Obtém o índice da cor + alfa especificados ou a alternativa mais próxima
- imagecolorset — Define a cor para o índice da paleta especificado
- imagecolorsforindex — Obtém as cores para um índice
- imagecolorstotal — Obtém o número de cores em uma paleta de imagem
- imagecolortransparent — Define uma cor como transparente
- imageconvolution — Aplica uma matriz de convolução 3x3, usando coeficiente e deslocamento
- imagecopy — Copia uma parte de uma imagem
- imagecopymerge — Copia e funde parte de uma imagem
- imagecopymergegray — Copia e funde parte de uma imagem com escala de cinza
- imagecopyresampled — Copia e redimensiona parte de uma imagem com reamostragem
- imagecopyresized — Copia e redimensiona parte de uma imagem
- imagecreate — Crie uma nova imagem baseada em paleta
- imagecreatefromavif — Cria uma nova imagem a partir de um arquivo ou URL
- imagecreatefrombmp — Cria uma nova imagem a partir de um arquivo ou URL
- imagecreatefromgd — Cria uma nova imagem a partir de um arquivo GD ou URL
- imagecreatefromgd2 — Cria uma nova imagem a partir de um arquivo GD2 ou URL
- imagecreatefromgd2part — Cria uma nova imagem a partir de uma parte de um arquivo GD2 ou URL
- imagecreatefromgif — Cria uma nova imagem a partir de um arquivo ou URL
- imagecreatefromjpeg — Cria uma nova imagem a partir de um arquivo ou URL
- imagecreatefrompng — Cria uma nova imagem a partir de um arquivo ou URL
- imagecreatefromstring — Cria uma nova imagem a partir de um fluxo de imagem na string
- imagecreatefromtga — Cria uma nova imagem a partir de um arquivo ou URL
- imagecreatefromwbmp — Cria uma nova imagem a partir de um arquivo ou URL
- imagecreatefromwebp — Cria uma nova imagem a partir de um arquivo ou URL
- imagecreatefromxbm — Cria uma nova imagem a partir de um arquivo ou URL
- imagecreatefromxpm — Cria uma nova imagem a partir de um arquivo ou URL
- imagecreatetruecolor — Cria uma nova imagem em cores verdadeiras
- imagecrop — Recorta uma imagem no retângulo informado
- imagecropauto — Recorta uma imagem automaticamente usando um dos modos disponíveis
- imagedashedline — Desenha uma linha tracejada
- imagedestroy — Destrói uma imagem
- imageellipse — Desenha uma elipse
- imagefill — Preenchimento
- imagefilledarc — Desenha um arco parcial preenchido
- imagefilledellipse — Desenha uma elipse preenchida
- imagefilledpolygon — Desenha um polígono preenchido
- imagefilledrectangle — Desenha um retângulo preenchido
- imagefilltoborder — Preenche até encontrar uma cor especificada
- imagefilter — Aplica um filtro a uma imagem
- imageflip — Vira uma imagem usando um modo especificado
- imagefontheight — Obtém a altura da fonte
- imagefontwidth — Obtém a largura da fonte
- imageftbbox — Fornece a caixa limite de um texto usando fontes via freetype2
- imagefttext — Escreve texto em uma imagem usando fontes FreeType 2
- imagegammacorrect — Aplica uma correção de gama a uma imagem GD
- imagegd — Envia uma imagem GD para o navegador ou para um arquivo
- imagegd2 — Envia uma imagem GD2 ao navegador ou a um arquivo
- imagegetclip — Obtém o retângulo de recorte
- imagegetinterpolation — Obtém o método de interpolação
- imagegif — Envia a imagem para o navegador ou para um arquivo
- imagegrabscreen — Captura toda a tela
- imagegrabwindow — Captura uma janela
- imageinterlace — Habilita ou desabilita entrelace
- imageistruecolor — Descobre se uma imagem está em cores verdadeiras
- imagejpeg — Envia a imagem para o navegador ou para um arquivo
- imagelayereffect — Define a opção de mesclagem alfa para usar efeitos de camada
- imageline — Desenha uma linha
- imageloadfont — Carrega uma nova fonte
- imageopenpolygon — Desenha um polígono aberto
- imagepalettecopy — Copia a paleta de uma imagem para outra
- imagepalettetotruecolor — Converte uma imagem baseada em paleta para cores verdadeiras
- imagepng — Envia uma imagem PNG para o navegador ou arquivo
- imagepolygon — Desenha um polígono
- imagerectangle — Desenha um retângulo
- imageresolution — Obtém ou define a resolução da imagem
- imagerotate — Rotaciona uma imagem em um ângulo informado
- imagesavealpha — Informa se a informação de canal alfa deve ser retida ao gravar imagens
- imagescale — Muda a escala de uma imagem usando largura e altura informadas
- imagesetbrush — Define o tipo de pincel para desenho de linhas
- imagesetclip — Define o retângulo de recorte
- imagesetinterpolation — Define o método de interpolação
- imagesetpixel — Desenha um pixel
- imagesetstyle — Define o estilo para desenho de linhas
- imagesetthickness — Define a espessura para desenho de linhas
- imagesettile — Define a imagem de ladrilho para preenchimento
- imagestring — Desenha uma string na horizontal
- imagestringup — Desenha uma string na vertical
- imagesx — Obtém a largura da imagem
- imagesy — Obtém a altura da imagem
- imagetruecolortopalette — Converte uma imagem em cores verdadeiras em uma imagem de paleta
- imagettfbbox — Fornece a os limites retangulares de um texto usando fontes TrueType
- imagettftext — Escreve texto na imagem usando fontes TrueType
- imagetypes — Retorna os tipos de imagens suportados pela instalação do PHP
- imagewbmp — Envia a imagem para o navegador ou para um arquivo
- imagewebp — Mostra uma imagem WebP no navegador ou grava em arquivo
- imagexbm — Mostra uma imagem XBM em um navegador ou grava em arquivo
- iptcembed — Incorpora dados binários IPTC em uma imagem JPEG
- iptcparse — Interpreta um bloco IPTC binário em etiquetas simples
- jpeg2wbmp — Converte arquivo de imagem JPEG para WBMP
- png2wbmp — Converte arquivo de imagem PNG em WBMP

# A classe GdImage

(PHP 8)

## Introdução

Um classe completamente opaca que substitui recursos `gd` a partir do PHP 8.0.0.

## Resumo da classe

final class GdImage {
}

# A classe GdFont

(PHP 8 >= 8.1.0)

## Introdução

Um classe completamente opaca que substitui recursos `gd font` a partir do PHP 8.1.0.

## Resumo da classe

final class GdFont {
}

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
  - Tipos de Recurso
- Constantes predefinidas
- Exemplos
  - Criação de PNG com PHP
  - Adicionando marcas d'água a imagens usando canais alfa
  - Usando imagecopymerge para criar uma marca d'água translúcida
- Funções de GD e Image
  - gd_info — Obtém informações sobre a biblioteca GD instalada atualmente
  - getimagesize — Obtém o tamanho de uma imagem
  - getimagesizefromstring — Obtém o tamanho de uma imagem a partir de uma string
  - image_type_to_extension — Obtém a extensão de arquivo para o tipo da imagem
  - image_type_to_mime_type — Obtém o Mime-Type para o tipo de imagem retornado por getimagesize, exif_read_data, exif_thumbnail e exif_imagetype
  - image2wbmp — Envia a imagem para o navegador ou para um arquivo
  - imageaffine — Retorna uma imagem contendo a imagem fonte com transformação afim, usando uma área de recorte opcional
  - imageaffinematrixconcat — Concatena duas matrizes de transformação afim
  - imageaffinematrixget — Obtém uma matriz de transformação afim
  - imagealphablending — Define o modo de combinação para uma imagem
  - imageantialias — Define se as funções de suavização de serrilhado devem ser usadas ou não
  - imagearc — Desenha um arco
  - imageavif — Envia a imagem para o navegador ou para um arquivo
  - imagebmp — Mostra ou grava uma imagem BMP
  - imagechar — Desenha um caractere horizontalmente
  - imagecharup — Desenha um caractere verticalmente
  - imagecolorallocate — Aloca uma cor para uma imagem
  - imagecolorallocatealpha — Aloca uma cor para uma imagem
  - imagecolorat — Obtém o índica da cor de um pixel
  - imagecolorclosest — Obtém o índice da cor mais próxima à especificada
  - imagecolorclosestalpha — Obtém o índice da cor mais próxima à especificada (incluindo alfa)
  - imagecolorclosesthwb — Obtém o índice da cor que tem a matiz, brancura e negritude mais próximas de uma cor informada
  - imagecolordeallocate — Desaloca uma cor de uma imagem
  - imagecolorexact — Obtém o índice da cor especificada
  - imagecolorexactalpha — Obtém o índice da cor e alfa especificados
  - imagecolormatch — Faz com que as cores da versão em paleta da imagem fiquem mais próximas da versão em cores verdadeiras
  - imagecolorresolve — Obtém o índice da cor especificada ou a alternativa mais próxima
  - imagecolorresolvealpha — Obtém o índice da cor + alfa especificados ou a alternativa mais próxima
  - imagecolorset — Define a cor para o índice da paleta especificado
  - imagecolorsforindex — Obtém as cores para um índice
  - imagecolorstotal — Obtém o número de cores em uma paleta de imagem
  - imagecolortransparent — Define uma cor como transparente
  - imageconvolution — Aplica uma matriz de convolução 3x3, usando coeficiente e deslocamento
  - imagecopy — Copia uma parte de uma imagem
  - imagecopymerge — Copia e funde parte de uma imagem
  - imagecopymergegray — Copia e funde parte de uma imagem com escala de cinza
  - imagecopyresampled — Copia e redimensiona parte de uma imagem com reamostragem
  - imagecopyresized — Copia e redimensiona parte de uma imagem
  - imagecreate — Crie uma nova imagem baseada em paleta
  - imagecreatefromavif — Cria uma nova imagem a partir de um arquivo ou URL
  - imagecreatefrombmp — Cria uma nova imagem a partir de um arquivo ou URL
  - imagecreatefromgd — Cria uma nova imagem a partir de um arquivo GD ou URL
  - imagecreatefromgd2 — Cria uma nova imagem a partir de um arquivo GD2 ou URL
  - imagecreatefromgd2part — Cria uma nova imagem a partir de uma parte de um arquivo GD2 ou URL
  - imagecreatefromgif — Cria uma nova imagem a partir de um arquivo ou URL
  - imagecreatefromjpeg — Cria uma nova imagem a partir de um arquivo ou URL
  - imagecreatefrompng — Cria uma nova imagem a partir de um arquivo ou URL
  - imagecreatefromstring — Cria uma nova imagem a partir de um fluxo de imagem na string
  - imagecreatefromtga — Cria uma nova imagem a partir de um arquivo ou URL
  - imagecreatefromwbmp — Cria uma nova imagem a partir de um arquivo ou URL
  - imagecreatefromwebp — Cria uma nova imagem a partir de um arquivo ou URL
  - imagecreatefromxbm — Cria uma nova imagem a partir de um arquivo ou URL
  - imagecreatefromxpm — Cria uma nova imagem a partir de um arquivo ou URL
  - imagecreatetruecolor — Cria uma nova imagem em cores verdadeiras
  - imagecrop — Recorta uma imagem no retângulo informado
  - imagecropauto — Recorta uma imagem automaticamente usando um dos modos disponíveis
  - imagedashedline — Desenha uma linha tracejada
  - imagedestroy — Destrói uma imagem
  - imageellipse — Desenha uma elipse
  - imagefill — Preenchimento
  - imagefilledarc — Desenha um arco parcial preenchido
  - imagefilledellipse — Desenha uma elipse preenchida
  - imagefilledpolygon — Desenha um polígono preenchido
  - imagefilledrectangle — Desenha um retângulo preenchido
  - imagefilltoborder — Preenche até encontrar uma cor especificada
  - imagefilter — Aplica um filtro a uma imagem
  - imageflip — Vira uma imagem usando um modo especificado
  - imagefontheight — Obtém a altura da fonte
  - imagefontwidth — Obtém a largura da fonte
  - imageftbbox — Fornece a caixa limite de um texto usando fontes via freetype2
  - imagefttext — Escreve texto em uma imagem usando fontes FreeType 2
  - imagegammacorrect — Aplica uma correção de gama a uma imagem GD
  - imagegd — Envia uma imagem GD para o navegador ou para um arquivo
  - imagegd2 — Envia uma imagem GD2 ao navegador ou a um arquivo
  - imagegetclip — Obtém o retângulo de recorte
  - imagegetinterpolation — Obtém o método de interpolação
  - imagegif — Envia a imagem para o navegador ou para um arquivo
  - imagegrabscreen — Captura toda a tela
  - imagegrabwindow — Captura uma janela
  - imageinterlace — Habilita ou desabilita entrelace
  - imageistruecolor — Descobre se uma imagem está em cores verdadeiras
  - imagejpeg — Envia a imagem para o navegador ou para um arquivo
  - imagelayereffect — Define a opção de mesclagem alfa para usar efeitos de camada
  - imageline — Desenha uma linha
  - imageloadfont — Carrega uma nova fonte
  - imageopenpolygon — Desenha um polígono aberto
  - imagepalettecopy — Copia a paleta de uma imagem para outra
  - imagepalettetotruecolor — Converte uma imagem baseada em paleta para cores verdadeiras
  - imagepng — Envia uma imagem PNG para o navegador ou arquivo
  - imagepolygon — Desenha um polígono
  - imagerectangle — Desenha um retângulo
  - imageresolution — Obtém ou define a resolução da imagem
  - imagerotate — Rotaciona uma imagem em um ângulo informado
  - imagesavealpha — Informa se a informação de canal alfa deve ser retida ao gravar imagens
  - imagescale — Muda a escala de uma imagem usando largura e altura informadas
  - imagesetbrush — Define o tipo de pincel para desenho de linhas
  - imagesetclip — Define o retângulo de recorte
  - imagesetinterpolation — Define o método de interpolação
  - imagesetpixel — Desenha um pixel
  - imagesetstyle — Define o estilo para desenho de linhas
  - imagesetthickness — Define a espessura para desenho de linhas
  - imagesettile — Define a imagem de ladrilho para preenchimento
  - imagestring — Desenha uma string na horizontal
  - imagestringup — Desenha uma string na vertical
  - imagesx — Obtém a largura da imagem
  - imagesy — Obtém a altura da imagem
  - imagetruecolortopalette — Converte uma imagem em cores verdadeiras em uma imagem de paleta
  - imagettfbbox — Fornece a os limites retangulares de um texto usando fontes TrueType
  - imagettftext — Escreve texto na imagem usando fontes TrueType
  - imagetypes — Retorna os tipos de imagens suportados pela instalação do PHP
  - imagewbmp — Envia a imagem para o navegador ou para um arquivo
  - imagewebp — Mostra uma imagem WebP no navegador ou grava em arquivo
  - imagexbm — Mostra uma imagem XBM em um navegador ou grava em arquivo
  - iptcembed — Incorpora dados binários IPTC em uma imagem JPEG
  - iptcparse — Interpreta um bloco IPTC binário em etiquetas simples
  - jpeg2wbmp — Converte arquivo de imagem JPEG para WBMP
  - png2wbmp — Converte arquivo de imagem PNG em WBMP
- GdImage — A classe GdImage
- GdFont — A classe GdFont

# Gmagick

# Introdução

Aviso

Esta extensão é EXPERIMENTAL. O comportamento desta extensão, incluindo os nomes de suas funções e qualquer outra documentação relacionada a esta extensão, pode mudar sem aviso prévio em futuras versões do PHP. Use por sua conta e risco.

Gmagick é uma extensão PHP para criar, modificar e obter metainformações de imagens usando a API GraphicsMagick.

GraphicsMagick orgulha-se de ser o canivete suíço no processamento de imagens. Funciona com 88 principais formatos incluindo formatos importantes como DPX, GIF, JPEG, JPEG-2000, PNG, PDF, PNM e TIFF.

Gmagick consiste de uma classe principal Gmagick, uma classe GmagickDraw que é na verdade uma varinha de desenho e uma classe GmagickPixel cujas instâncias representam um único pixel de uma imagem (cor, opacidade).

# Instalação/Configuração

## Índice

- Dependências
- Instalação

## Dependências

Esta extensão funciona melhor com GraphicsMagick versão 1.4+. Gmagick deve funcionar com versões anteriores até GraphicsMagick 1.2.6, mas alguns recursos e formatos não são suportados por essas versões. A versão Windows do GraphicsMagick está disponível no site GraphicsMagick. Para ler sobre a diferença entre ImageMagick e GraphicsMagick, confira: » FAQ.

## Instalação

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/gmagick.

> Nota: O nome oficial desta extensão é gmagick.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

Constantes de tipo de cor
`Gmagick::COLOR_BLACK` (int)
  Preto
`Gmagick::COLOR_BLUE` (int)
  Azul
`Gmagick::COLOR_CYAN` (int)
  Ciano
`Gmagick::COLOR_GREEN` (int)
  Verde
`Gmagick::COLOR_RED` (int)
  Vermelho
`Gmagick::COLOR_YELLOW` (int)
  Amarelo
`Gmagick::COLOR_MAGENTA` (int)
  Magenta
`Gmagick::COLOR_OPACITY` (int)
  Opacidade
`Gmagick::COLOR_ALPHA` (int)
  Alfa
`Gmagick::COLOR_FUZZ` (int)
  Fuzz

Composite Operator Constants
`Gmagick::COMPOSITE_DEFAULT` (int)
  O operador composto padrão
`Gmagick::COMPOSITE_UNDEFINED` (int)
  Operador composto indefinido
`Gmagick::COMPOSITE_NO` (int)
  Nenhum operador composto definido
`Gmagick::COMPOSITE_ADD` (int)
  O resultado de imagem + imagem
`Gmagick::COMPOSITE_ATOP` (int)
  O resultado é o mesmo formato da imagem, com a imagem composta obscurecendo a imagem onde as formas da imagem se sobrepõem
`Gmagick::COMPOSITE_BLEND` (int)
  Combina a imagem
`Gmagick::COMPOSITE_BUMPMAP` (int)
  O mesmo que COMPOSITE_MULTIPLY, exceto que a origem é convertida primeiro em escala de cinza.
`Gmagick::COMPOSITE_CLEAR` (int)
  Torna a imagem de destino transparente
`Gmagick::COMPOSITE_COLORBURN` (int)
  Escurece a imagem de destino para refletir a imagem de origem
`Gmagick::COMPOSITE_COLORDODGE` (int)
  Ilumina a imagem de destino para refletir a imagem de origem
`Gmagick::COMPOSITE_COLORIZE` (int)
  Colore a imagem de destino usando a imagem composta
`Gmagick::COMPOSITE_COPYBLACK` (int)
  Copia preto da origem para o destino
`Gmagick::COMPOSITE_COPYBLUE` (int)
  Copia azul da origem para o destino
`Gmagick::COMPOSITE_COPY` (int)
  Copia a imagem de origem na imagem de destino
`Gmagick::COMPOSITE_COPYCYAN` (int)
  Copia ciano da origem para o destino
`Gmagick::COMPOSITE_COPYGREEN` (int)
  Copia verde da origem para o destino
`Gmagick::COMPOSITE_COPYMAGENTA` (int)
  Copia magenta da origem para o destino
`Gmagick::COMPOSITE_COPYOPACITY` (int)
  Copia opacidade da origem para o destino
`Gmagick::COMPOSITE_COPYRED` (int)
  Copia vermelho da origem para o destino
`Gmagick::COMPOSITE_COPYYELLOW` (int)
  Copia amarelo da origem para o destino
`Gmagick::COMPOSITE_DARKEN` (int)
  Escurece a imagem de destino
`Gmagick::COMPOSITE_DSTATOP` (int)
  A parte do destino que está dentro da origem é composta pela origem e substitui o destino
`Gmagick::COMPOSITE_DST` (int)
  O destino permanece intocado
`Gmagick::COMPOSITE_DSTIN` (int)
  As partes dentro da origem substituem o destino
`Gmagick::COMPOSITE_DSTOUT` (int)
  As partes fora da origem substituem o destino
`Gmagick::COMPOSITE_DSTOVER` (int)
  Destino subsitui a origem
`Gmagick::COMPOSITE_DIFFERENCE` (int)
  Subtrai a mais escura das duas cores constituintes da mais clara
`Gmagick::COMPOSITE_DISPLACE` (int)
  Desloca os pixels da imagem destino conforme definido pela origem
`Gmagick::COMPOSITE_DISSOLVE` (int)
  Dissolve a origem no destino
`Gmagick::COMPOSITE_EXCLUSION` (int)
  Produz um efeito semelhante ao de Gmagick::COMPOSITE_DIFFERENCE, mas aparece com menor contraste
`Gmagick::COMPOSITE_HARDLIGHT` (int)
  Multiplica ou filtra as cores, dependendo do valor da cor de origem
`Gmagick::COMPOSITE_HUE` (int)
  Modifica o matiz do destino conforme definido pela origem
`Gmagick::COMPOSITE_IN` (int)
  Compõe a origem no destino
`Gmagick::COMPOSITE_LIGHTEN` (int)
  Ilumina o alvo conforme definido pela origem
`Gmagick::COMPOSITE_LUMINIZE` (int)
  Ilumina o alvo conforme definido pela origem
`Gmagick::COMPOSITE_MINUS` (int)
  Subtrai a origem do destino
`Gmagick::COMPOSITE_MODULATE` (int)
  Modula o brilho, saturação e matiz alvo conforme definido pela origem
`Gmagick::COMPOSITE_MULTIPLY` (int)
  Multiplica o destino pela origem
`Gmagick::COMPOSITE_OUT` (int)
  Compõe partes externas da origem no destino
`Gmagick::COMPOSITE_OVER` (int)
  Compõe a origem sobre o destino
`Gmagick::COMPOSITE_OVERLAY` (int)
  Sobrepõe a origem no destino
`Gmagick::COMPOSITE_PLUS` (int)
  Adiciona a origem ao destino
`Gmagick::COMPOSITE_REPLACE` (int)
  Substitui o destino pela origem
`Gmagick::COMPOSITE_SATURATE` (int)
  Satura o destino conforme definido pela origem
`Gmagick::COMPOSITE_SCREEN` (int)
  A origem e o destino são complementados e depois multiplicados e depois substituem o destino
`Gmagick::COMPOSITE_SOFTLIGHT` (int)
  Escurece ou clareia as cores, dependendo da origem
`Gmagick::COMPOSITE_SRCATOP` (int)
  A parte da origem que fica dentro do destino é composta no destino
`Gmagick::COMPOSITE_SRC` (int)
  A origem é copiada para o destino
`Gmagick::COMPOSITE_SRCIN` (int)
  A parte da origem que está dentro do destino substitui o destino
`Gmagick::COMPOSITE_SRCOUT` (int)
  A parte da origem fora do destino substitui o destino
`Gmagick::COMPOSITE_SRCOVER` (int)
  A origem substitui o destino
`Gmagick::COMPOSITE_SUBTRACT` (int)
  Subtrai as cores da imagem de origem da imagem de destino
`Gmagick::COMPOSITE_THRESHOLD` (int)
  A origem é composta no destino conforme definido pelo limite de origem
`Gmagick::COMPOSITE_XOR` (int)
  A parte da origem que fica fora do destino é combinada com a parte do destino que fica fora da origem

Constantes do modo de montagem
`Gmagick::MONTAGEMODE_FRAME` (int)
`Gmagick::MONTAGEMODE_UNFRAME` (int)
`Gmagick::MONTAGEMODE_CONCATENATE` (int)

Constantes de estilo
`Gmagick::STYLE_NORMAL` (int)
`Gmagick::STYLE_ITALIC` (int)
`Gmagick::STYLE_OBLIQUE` (int)
`Gmagick::STYLE_ANY` (int)

Constantes de filtro
`Gmagick::FILTER_UNDEFINED` (int)
`Gmagick::FILTER_POINT` (int)
`Gmagick::FILTER_BOX` (int)
`Gmagick::FILTER_TRIANGLE` (int)
`Gmagick::FILTER_HERMITE` (int)
`Gmagick::FILTER_HANNING` (int)
`Gmagick::FILTER_HAMMING` (int)
`Gmagick::FILTER_BLACKMAN` (int)
`Gmagick::FILTER_GAUSSIAN` (int)
`Gmagick::FILTER_QUADRATIC` (int)
`Gmagick::FILTER_CUBIC` (int)
`Gmagick::FILTER_CATROM` (int)
`Gmagick::FILTER_MITCHELL` (int)
`Gmagick::FILTER_LANCZOS` (int)
`Gmagick::FILTER_BESSEL` (int)
`Gmagick::FILTER_SINC` (int)

Constantes de tipo de imagem
`Gmagick::IMGTYPE_UNDEFINED` (int)
`Gmagick::IMGTYPE_BILEVEL` (int)
`Gmagick::IMGTYPE_GRAYSCALE` (int)
`Gmagick::IMGTYPE_GRAYSCALEMATTE` (int)
`Gmagick::IMGTYPE_PALETTE` (int)
`Gmagick::IMGTYPE_PALETTEMATTE` (int)
`Gmagick::IMGTYPE_TRUECOLOR` (int)
`Gmagick::IMGTYPE_TRUECOLORMATTE` (int)
`Gmagick::IMGTYPE_COLORSEPARATION` (int)
`Gmagick::IMGTYPE_COLORSEPARATIONMATTE` (int)
`Gmagick::IMGTYPE_OPTIMIZE` (int)

Constantes de resolução
`Gmagick::RESOLUTION_UNDEFINED` (int)
`Gmagick::RESOLUTION_PIXELSPERINCH` (int)
`Gmagick::RESOLUTION_PIXELSPERCENTIMETER` (int)

Constantes de compressão
`Gmagick::COMPRESSION_UNDEFINED` (int)
`Gmagick::COMPRESSION_NO` (int)
`Gmagick::COMPRESSION_BZIP` (int)
`Gmagick::COMPRESSION_FAX` (int)
`Gmagick::COMPRESSION_GROUP4` (int)
`Gmagick::COMPRESSION_JPEG` (int)
`Gmagick::COMPRESSION_JPEG2000` (int)
`Gmagick::COMPRESSION_LOSSLESSJPEG` (int)
`Gmagick::COMPRESSION_LZW` (int)
`Gmagick::COMPRESSION_RLE` (int)
`Gmagick::COMPRESSION_ZIP` (int)

Constantes de pintura
`Gmagick::PAINT_POINT` (int)
`Gmagick::PAINT_REPLACE` (int)
`Gmagick::PAINT_FLOODFILL` (int)
`Gmagick::PAINT_FILLTOBORDER` (int)
`Gmagick::PAINT_RESET` (int)

Constantes de gravidade
`Gmagick::GRAVITY_NORTHWEST` (int)
`Gmagick::GRAVITY_NORTH` (int)
`Gmagick::GRAVITY_NORTHEAST` (int)
`Gmagick::GRAVITY_WEST` (int)
`Gmagick::GRAVITY_CENTER` (int)
`Gmagick::GRAVITY_EAST` (int)
`Gmagick::GRAVITY_SOUTHWEST` (int)
`Gmagick::GRAVITY_SOUTH` (int)
`Gmagick::GRAVITY_SOUTHEAST` (int)

Constantes de esticamento
`Gmagick::STRETCH_NORMAL` (int)
`Gmagick::STRETCH_ULTRACONDENSED` (int)
`Gmagick::STRETCH_CONDENSED` (int)
`Gmagick::STRETCH_SEMICONDENSED` (int)
`Gmagick::STRETCH_SEMIEXPANDED` (int)
`Gmagick::STRETCH_EXPANDED` (int)
`Gmagick::STRETCH_EXTRAEXPANDED` (int)
`Gmagick::STRETCH_ULTRAEXPANDED` (int)
`Gmagick::STRETCH_ANY` (int)

Constantes de alinhamento
`Gmagick::ALIGN_UNDEFINED` (int)
`Gmagick::ALIGN_LEFT` (int)
`Gmagick::ALIGN_CENTER` (int)
`Gmagick::ALIGN_RIGHT` (int)

Constantes de decoração
`Gmagick::DECORATION_NO` (int)
`Gmagick::DECORATION_UNDERLINE` (int)
`Gmagick::DECORATION_OVERLINE` (int)
`Gmagick::DECORATION_LINETROUGH` (int)

Constantes de ruído
`Gmagick::NOISE_UNIFORM` (int)
`Gmagick::NOISE_GAUSSIAN` (int)
`Gmagick::NOISE_MULTIPLICATIVEGAUSSIAN` (int)
`Gmagick::NOISE_IMPULSE` (int)
`Gmagick::NOISE_LAPLACIAN` (int)
`Gmagick::NOISE_POISSON` (int)

Constantes de canal
`Gmagick::CHANNEL_UNDEFINED` (int)
`Gmagick::CHANNEL_RED` (int)
`Gmagick::CHANNEL_GRAY` (int)
`Gmagick::CHANNEL_CYAN` (int)
`Gmagick::CHANNEL_GREEN` (int)
`Gmagick::CHANNEL_MAGENTA` (int)
`Gmagick::CHANNEL_BLUE` (int)
`Gmagick::CHANNEL_YELLOW` (int)
`Gmagick::CHANNEL_ALPHA` (int)
`Gmagick::CHANNEL_OPACITY` (int)
`Gmagick::CHANNEL_MATTE` (int)
`Gmagick::CHANNEL_BLACK` (int)
`Gmagick::CHANNEL_INDEX` (int)
`Gmagick::CHANNEL_ALL` (int)

Constantes métricas
`Gmagick::METRIC_UNDEFINED` (int)
`Gmagick::METRIC_MEANABSOLUTEERROR` (int)
`Gmagick::METRIC_MEANSQUAREERROR` (int)
`Gmagick::METRIC_PEAKABSOLUTEERROR` (int)
`Gmagick::METRIC_PEAKSIGNALTONOISERATIO` (int)
`Gmagick::METRIC_ROOTMEANSQUAREDERROR` (int)

Constantes de pixels
`Gmagick::PIXEL_CHAR` (int)
`Gmagick::PIXEL_DOUBLE` (int)
`Gmagick::PIXEL_FLOAT` (int)
`Gmagick::PIXEL_INTEGER` (int)
`Gmagick::PIXEL_LONG` (int)
`Gmagick::PIXEL_QUANTUM` (int)
`Gmagick::PIXEL_SHORT` (int)

Constantes de espaço de cores
`Gmagick::COLORSPACE_UNDEFINED` (int)
`Gmagick::COLORSPACE_RGB` (int)
`Gmagick::COLORSPACE_GRAY` (int)
`Gmagick::COLORSPACE_TRANSPARENT` (int)
`Gmagick::COLORSPACE_OHTA` (int)
`Gmagick::COLORSPACE_LAB` (int)
`Gmagick::COLORSPACE_XYZ` (int)
`Gmagick::COLORSPACE_YCBCR` (int)
`Gmagick::COLORSPACE_YCC` (int)
`Gmagick::COLORSPACE_YIQ` (int)
`Gmagick::COLORSPACE_YPBPR` (int)
`Gmagick::COLORSPACE_YUV` (int)
`Gmagick::COLORSPACE_CMYK` (int)
`Gmagick::COLORSPACE_SRGB` (int)
`Gmagick::COLORSPACE_HSB` (int)
`Gmagick::COLORSPACE_HSL` (int)
`Gmagick::COLORSPACE_HWB` (int)
`Gmagick::COLORSPACE_REC601LUMA` (int)
`Gmagick::COLORSPACE_REC709LUMA` (int)
`Gmagick::COLORSPACE_LOG` (int)

Constantes de Método de Pixel Virtual
`Gmagick::VIRTUALPIXELMETHOD_UNDEFINED` (int)
`Gmagick::VIRTUALPIXELMETHOD_BACKGROUND` (int)
`Gmagick::VIRTUALPIXELMETHOD_CONSTANT` (int)
`Gmagick::VIRTUALPIXELMETHOD_EDGE` (int)
`Gmagick::VIRTUALPIXELMETHOD_MIRROR` (int)
`Gmagick::VIRTUALPIXELMETHOD_TILE` (int)
`Gmagick::VIRTUALPIXELMETHOD_TRANSPARENT` (int)

Constantes de pré-visualização
`Gmagick::PREVIEW_UNDEFINED` (int)
`Gmagick::PREVIEW_ROTATE` (int)
`Gmagick::PREVIEW_SHEAR` (int)
`Gmagick::PREVIEW_ROLL` (int)
`Gmagick::PREVIEW_HUE` (int)
`Gmagick::PREVIEW_SATURATION` (int)
`Gmagick::PREVIEW_BRIGHTNESS` (int)
`Gmagick::PREVIEW_GAMMA` (int)
`Gmagick::PREVIEW_SPIFF` (int)
`Gmagick::PREVIEW_DULL` (int)
`Gmagick::PREVIEW_GRAYSCALE` (int)
`Gmagick::PREVIEW_QUANTIZE` (int)
`Gmagick::PREVIEW_DESPECKLE` (int)
`Gmagick::PREVIEW_REDUCENOISE` (int)
`Gmagick::PREVIEW_ADDNOISE` (int)
`Gmagick::PREVIEW_SHARPEN` (int)
`Gmagick::PREVIEW_BLUR` (int)
`Gmagick::PREVIEW_THRESHOLD` (int)
`Gmagick::PREVIEW_EDGEDETECT` (int)
`Gmagick::PREVIEW_SPREAD` (int)
`Gmagick::PREVIEW_SOLARIZE` (int)
`Gmagick::PREVIEW_SHADE` (int)
`Gmagick::PREVIEW_RAISE` (int)
`Gmagick::PREVIEW_SEGMENT` (int)
`Gmagick::PREVIEW_SWIRL` (int)
`Gmagick::PREVIEW_IMPLODE` (int)
`Gmagick::PREVIEW_WAVE` (int)
`Gmagick::PREVIEW_OILPAINT` (int)
`Gmagick::PREVIEW_CHARCOALDRAWING` (int)
`Gmagick::PREVIEW_JPEG` (int)

Constantes de intenção de renderização
`Gmagick::RENDERINGINTENT_UNDEFINED` (int)
`Gmagick::RENDERINGINTENT_SATURATION` (int)
`Gmagick::RENDERINGINTENT_PERCEPTUAL` (int)
`Gmagick::RENDERINGINTENT_ABSOLUTE` (int)
`Gmagick::RENDERINGINTENT_RELATIVE` (int)

Constantes de regra de preenchimento
`Gmagick::FILLRULE_UNDEFINED` (int)
`Gmagick::FILLRULE_EVENODD` (int)
`Gmagick::FILLRULE_NONZERO` (int)

Constantes de unidade de caminho
`Gmagick::PATHUNITS_UNDEFINED` (int)
`Gmagick::PATHUNITS_USERSPACE` (int)
`Gmagick::PATHUNITS_USERSPACEONUSE` (int)
`Gmagick::PATHUNITS_OBJECTBOUNDINGBOX` (int)

Constantes extremidade de linha
`Gmagick::LINECAP_UNDEFINED` (int)
`Gmagick::LINECAP_BUTT` (int)
`Gmagick::LINECAP_ROUND` (int)
`Gmagick::LINECAP_SQUARE` (int)

Constantes de junção de linhas
`Gmagick::LINEJOIN_UNDEFINED` (int)
`Gmagick::LINEJOIN_MITER` (int)
`Gmagick::LINEJOIN_ROUND` (int)
`Gmagick::LINEJOIN_BEVEL` (int)

Constantes de tipo de recurso
`Gmagick::RESOURCETYPE_UNDEFINED` (int)
`Gmagick::RESOURCETYPE_AREA` (int)
`Gmagick::RESOURCETYPE_DISK` (int)
`Gmagick::RESOURCETYPE_FILE` (int)
`Gmagick::RESOURCETYPE_MAP` (int)
`Gmagick::RESOURCETYPE_MEMORY` (int)

Constantes de orientação
`Gmagick::ORIENTATION_UNDEFINED` (int)
`Gmagick::ORIENTATION_TOPLEFT` (int)
`Gmagick::ORIENTATION_TOPRIGHT` (int)
`Gmagick::ORIENTATION_BOTTOMRIGHT` (int)
`Gmagick::ORIENTATION_BOTTOMLEFT` (int)
`Gmagick::ORIENTATION_LEFTTOP` (int)
`Gmagick::ORIENTATION_RIGHTTOP` (int)
`Gmagick::ORIENTATION_RIGHTBOTTOM` (int)
`Gmagick::ORIENTATION_LEFTBOTTOM` (int)

Constantes de entrelaçamento
`Gmagick::INTERLACE_UNDEFINED` (int)
`Gmagick::INTERLACE_NO` (int)
`Gmagick::INTERLACE_NONE` (int)
`Gmagick::INTERLACE_LINE` (int)
`Gmagick::INTERLACE_PLANE` (int)
`Gmagick::INTERLACE_PARTITION` (int)

# Exemplos

A seguir alguns exemplos de algumas operações comuns da Gmagick.

Exemplo #1 Exemplo de Gmagick

    <?php
    // Instancia um novo objeto Gmagick
    $image = new Gmagick('exemplo.jpg');

    // Carrega miniatura da imagem. 0 para qualquer eixo preserva a razão de aspecto
    $image->thumbnailimage(100, 0);

    // Cria uma borda ao redor da imagem e simula como a imagem ficará como uma pintura a óleo
    // Observe o encadeamento de métodos mutadores, que é suportado no gmagick
    $image->borderimage("yellow", 8, 8)->oilpaintimage(0.3);

    // Grava a imagem atual no estado atual em um arquivo
    $image->write('miniatura_exemplo.jpg');
    ?>

# A classe Gmagick

(PECL gmagick >= Unknown)

## Introdução

## Resumo da classe

class Gmagick {
/* Métodos */
public function __construct(string `$filename` = ?)
public function addimage(Gmagick `$source`): Gmagick
public function addnoiseimage(int `$noise_type`): Gmagick
public function annotateimage(
GmagickDraw `$GmagickDraw`,
float `$x`,
float `$y`,
float `$angle`,
string `$text`
): Gmagick
public function blurimage(float `$radius`, float `$sigma`, int `$channel` = ?): Gmagick
public function borderimage(GmagickPixel `$color`, int `$width`, int `$height`): Gmagick
public function charcoalimage(float `$radius`, float `$sigma`): Gmagick
public function chopimage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): Gmagick
public function clear(): Gmagick
public function commentimage(string `$comment`): Gmagick
public function compositeimage(
Gmagick `$source`,
int `$COMPOSE`,
int `$x`,
int `$y`
): Gmagick
public function cropimage(
int `$width` ,
int `$height` ,
int `$x`,
int `$y`
): Gmagick
public function cropthumbnailimage(int `$width`, int `$height`): Gmagick
public function current(): Gmagick
public function cyclecolormapimage(int `$displace`): Gmagick
public function deconstructimages(): Gmagick
public function despeckleimage(): Gmagick
public function destroy(): bool
public function drawimage(GmagickDraw `$GmagickDraw`): Gmagick
public function edgeimage(float `$radius`): Gmagick
public function embossimage(float `$radius`, float `$sigma`): Gmagick
public function enhanceimage(): Gmagick
public function equalizeimage(): Gmagick
public function flipimage(): Gmagick
public function flopimage(): Gmagick
public function frameimage(
GmagickPixel `$color`,
int `$width`,
int `$height`,
int `$inner_bevel`,
int `$outer_bevel`
): Gmagick
public function gammaimage(float `$gamma`): Gmagick
public function getcopyright(): string
public function getfilename(): string
public function getimagebackgroundcolor(): GmagickPixel
public function getimageblueprimary(): array
public function getimagebordercolor(): GmagickPixel
public function getimagechanneldepth(int `$channel_type`): int
public function getimagecolors(): int
public function getimagecolorspace(): int
public function getimagecompose(): int
public function getimagedelay(): int
public function getimagedepth(): int
public function getimagedispose(): int
public function getimageextrema(): array
public function getimagefilename(): string
public function getimageformat(): string
public function getimagegamma(): float
public function getimagegreenprimary(): array
public function getimageheight(): int
public function getimagehistogram(): array
public function getimageindex(): int
public function getimageinterlacescheme(): int
public function getimageiterations(): int
public function getimagematte(): int
public function getimagemattecolor(): GmagickPixel
public function getimageprofile(string `$name`): string
public function getimageredprimary(): array
public function getimagerenderingintent(): int
public function getimageresolution(): array
public function getimagescene(): int
public function getimagesignature(): string
public function getimagetype(): int
public function getimageunits(): int
public function getimagewhitepoint(): array
public function getimagewidth(): int
public function getpackagename(): string
public function getquantumdepth(): array
public function getreleasedate(): string
public function getsamplingfactors(): array
public function getsize(): array
public function getversion(): array
public function hasnextimage(): mixed
public function haspreviousimage(): mixed
public function implodeimage(float `$radius`): mixed
public function labelimage(string `$label`): mixed
public function levelimage(
float `$blackPoint`,
float `$gamma`,
float `$whitePoint`,
int `$channel` = Gmagick::CHANNEL_DEFAULT
): mixed
public function magnifyimage(): mixed
public function mapimage(gmagick `$gmagick`, bool `$dither`): Gmagick
public function medianfilterimage(float `$radius`): void
public function minifyimage(): Gmagick
public function modulateimage(float `$brightness`, float `$saturation`, float `$hue`): Gmagick
public function motionblurimage(float `$radius`, float `$sigma`, float `$angle`): Gmagick
public function newimage(
int `$width`,
int `$height`,
string `$background`,
string `$format` = ?
): Gmagick
public function nextimage(): bool
public function normalizeimage(int `$channel` = ?): Gmagick
public function oilpaintimage( float `$radius` ): Gmagick
public function previousimage(): bool
public function profileimage(string `$name`, string `$profile`): Gmagick
public function quantizeimage(
int `$numColors`,
int `$colorspace`,
int `$treeDepth`,
bool `$dither`,
bool `$measureError`
): Gmagick
public function quantizeimages(
int `$numColors`,
int `$colorspace`,
int `$treeDepth`,
bool `$dither`,
bool `$measureError`
): Gmagick
public function queryfontmetrics(GmagickDraw `$draw`, string `$text`): array
public function queryfonts(string `$pattern` = "*"): array
public function queryformats(string `$pattern` = "*"): array
public function radialblurimage(float `$angle`, int `$channel` = Gmagick::CHANNEL_DEFAULT): Gmagick
public function raiseimage(
int `$width`,
int `$height`,
int `$x`,
int `$y`,
bool `$raise`
): Gmagick
public function read(string `$filename`): Gmagick
public function readimage(string `$filename`): Gmagick
public function readimageblob(string `$imageContents`, string `$filename` = ?): Gmagick
public function readimagefile(resource `$fp`, string `$filename` = ?): Gmagick
public function reducenoiseimage(float `$radius`): Gmagick
public function removeimage(): Gmagick
public function removeimageprofile(string `$name`): string
public function resampleimage(
float `$xResolution`,
float `$yResolution`,
int `$filter`,
float `$blur`
): Gmagick
public function resizeimage(
int `$width`,
int `$height`,
int `$filter`,
float `$blur`,
bool `$fit` = `false`
): Gmagick
public function rollimage(int `$x`, int `$y`): Gmagick
public function rotateimage(mixed `$color`, float `$degrees`): Gmagick
public function scaleimage(int `$width`, int `$height`, bool `$fit` = `false`): Gmagick
public function separateimagechannel(int `$channel`): Gmagick
function setCompressionQuality( int `$quality` ): Gmagick
public function setfilename(string `$filename`): Gmagick
public function setimagebackgroundcolor(GmagickPixel `$color`): Gmagick
public function setimageblueprimary(float `$x`, float `$y`): Gmagick
public function setimagebordercolor(GmagickPixel `$color`): Gmagick
public function setimagechanneldepth(int `$channel`, int `$depth`): Gmagick
public function setimagecolorspace(int `$colorspace`): Gmagick
public function setimagecompose(int `$composite`): Gmagick
public function setimagedelay(int `$delay`): Gmagick
public function setimagedepth(int `$depth`): Gmagick
public function setimagedispose(int `$disposeType`): Gmagick
public function setimagefilename(string `$filename`): Gmagick
public function setimageformat(string `$imageFormat`): Gmagick
public function setimagegamma(float `$gamma`): Gmagick
public function setimagegreenprimary(float `$x`, float `$y`): Gmagick
public function setimageindex(int `$index`): Gmagick
public function setimageinterlacescheme(int `$interlace`): Gmagick
public function setimageiterations(int `$iterations`): Gmagick
public function setimageprofile(string `$name`, string `$profile`): Gmagick
public function setimageredprimary(float `$x`, float `$y`): Gmagick
public function setimagerenderingintent(int `$rendering_intent`): Gmagick
public function setimageresolution(float `$xResolution`, float `$yResolution`): Gmagick
public function setimagescene(int `$scene`): Gmagick
public function setimagetype(int `$imgType`): Gmagick
public function setimageunits(int `$resolution`): Gmagick
public function setimagewhitepoint(float `$x`, float `$y`): Gmagick
public function setsamplingfactors(array `$factors`): Gmagick
public function setsize(int `$columns`, int `$rows`): Gmagick
public function shearimage(mixed `$color`, float `$xShear`, float `$yShear`): Gmagick
public function solarizeimage(int `$threshold`): Gmagick
public function spreadimage(float `$radius`): Gmagick
public function stripimage(): Gmagick
public function swirlimage(float `$degrees`): Gmagick
public function thumbnailimage(int `$width`, int `$height`, bool `$fit` = `false`): Gmagick
public function trimimage(float `$fuzz`): Gmagick
public function writeimage(string `$filename`, bool `$all_frames` = `false`): Gmagick
}

# Gmagick::addimage

(PECL gmagick >= Unknown)

Gmagick::addimage — Adiciona nova imagem à lista de imagens de objetos Gmagick

### Descrição

public function Gmagick::addimage(Gmagick `$source`): Gmagick

Adiciona uma nova imagem ao objeto Gmagick a partir da posição atual do objeto de origem. Após a operação, a posição do iterador é movida para o final da lista.

### Parâmetros

`source`
  O objeto Gmagick de origem

### Valor Retornado

O objeto Gmagick com a imagem adicionada

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::addnoiseimage

(PECL gmagick >= Unknown)

Gmagick::addnoiseimage — Adiciona ruído aleatório à imagem

### Descrição

public function Gmagick::addnoiseimage(int `$noise_type`): Gmagick

Adiciona ruído aleatório à imagem.

### Parâmetros

`noise_type`
  O tipo de ruído. Consulte esta lista de constantes de ruído.

### Valor Retornado

O objeto Gmagick com o ruído adicionado.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::annotateimage

(PECL gmagick >= Unknown)

Gmagick::annotateimage — Anota uma imagem com texto

### Descrição

public function Gmagick::annotateimage(
GmagickDraw `$GmagickDraw`,
float `$x`,
float `$y`,
float `$angle`,
string `$text`
): Gmagick

Anota uma imagem com texto.

### Parâmetros

`GmagickDraw`
  O objeto GmagickDraw que contém configurações para desenhar o texto.
`x`
  Deslocamento horizontal em pixels à esquerda do texto.
`y`
  Deslocamento vertical em pixels até a linha de base do texto.
`angle`
  O ângulo no qual o texto será escrito.
`text`
  A string a ser desenhada.

### Valor Retornado

O objeto Gmagick com anotação feita.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::blurimage

(PECL gmagick >= Unknown)

Gmagick::blurimage — Adiciona filtro de desfoque à imagem

### Descrição

public function Gmagick::blurimage(float `$radius`, float `$sigma`, int `$channel` = ?): Gmagick

Adiciona filtro de desfoque à imagem.

### Parâmetros

`radius`
  Raio de desfoque
`sigma`
  Desvio padrão

### Valor Retornado

O objeto Gmagick desfocado

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::borderimage

(PECL gmagick >= Unknown)

Gmagick::borderimage — Envolve a imagem com uma borda

### Descrição

public function Gmagick::borderimage(GmagickPixel `$color`, int `$width`, int `$height`): Gmagick

Envolve a imagem com uma borda da cor definida pelo objeto GmagickPixel da cor da borda ou por uma sequência de cores.

### Parâmetros

`color`
  Objeto GmagickPixel ou uma string contendo a cor da borda.
`width`
  Largura da borda.
`height`
  Altura da borda.

### Valor Retornado

O objeto Gmagick com borda definida.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::charcoalimage

(PECL gmagick >= Unknown)

Gmagick::charcoalimage — Simula um desenho a carvão

### Descrição

public function Gmagick::charcoalimage(float `$radius`, float `$sigma`): Gmagick

Simula um desenho a carvão.

### Parâmetros

`radius`
  O raio do gaussiano, em pixels, sem contar o pixel central.
`sigma`
  O desvio padrão do gaussiano, em pixels.

### Valor Retornado

O objeto Gmagick com simulação de carvão.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::chopimage

(PECL gmagick >= Unknown)

Gmagick::chopimage — Remove uma região de uma imagem e corta

### Descrição

public function Gmagick::chopimage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): Gmagick

Remove uma região de uma imagem e colapsa a imagem para ocupar a parte removida.

### Parâmetros

`width`
  Largura da área cortada.
`height`
  Altura da área cortada.
`x`
  Coordenada X da origem da área cortada.
`y`
  Coordenada Y da origem da área cortada.

### Valor Retornado

O objeto Gmagick cortado.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::clear

(PECL gmagick >= Unknown)

Gmagick::clear — Limpa todos os recursos associados ao objeto Gmagick

### Descrição

public function Gmagick::clear(): Gmagick

Limpa todos os recursos associados ao objeto Gmagick.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O objeto Gmagick limpo.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::commentimage

(PECL gmagick >= Unknown)

Gmagick::commentimage — Adiciona um comentário à sua imagem

### Descrição

public function Gmagick::commentimage(string `$comment`): Gmagick

Adiciona um comentário à sua imagem.

### Parâmetros

`comment`
  O comentário a ser adicionado.

### Valor Retornado

O objeto Gmagick com comentário adicionado.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::compositeimage

(PECL gmagick >= Unknown)

Gmagick::compositeimage — Compõe uma imagem em outra

### Descrição

public function Gmagick::compositeimage(
Gmagick `$source`,
int `$COMPOSE`,
int `$x`,
int `$y`
): Gmagick

Compõe uma imagem em outra na posição especificada.

### Parâmetros

`source`
  Objeto Gmagick que contém a imagem a ser composta.
`COMPOSE`
  Operador de composição.
`x`
  A posição X da imagem composta.
`y`
  A posição Y da imagem composta.

### Valor Retornado

O objeto Gmagick com composição.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::__construct

(PECL gmagick >= Unknown)

Gmagick::__construct — O construtor Gmagick

### Descrição

public function Gmagick::__construct(string `$filename` = ?)

O construtor Gmagick.

### Parâmetros

`filename`
  O caminho para uma imagem a ser carregada ou um array de caminhos.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::cropimage

(PECL gmagick >= Unknown)

Gmagick::cropimage — Extrai uma região da imagem

### Descrição

public function Gmagick::cropimage(
int `$width` ,
int `$height` ,
int `$x`,
int `$y`
): Gmagick

Extrai uma região da imagem.

### Parâmetros

`width`
  A largura do recorte.
`height`
  A altura do recorte.
`x`
  A coordenada X do canto superior esquerdo da região recortada.
`y`
  A coordenada Y do canto superior esquerdo da região recortada.

### Valor Retornado

O objeto Gmagick recortado.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::cropthumbnailimage

(PECL gmagick >= Unknown)

Gmagick::cropthumbnailimage — Cria uma miniatura de corte

### Descrição

public function Gmagick::cropthumbnailimage(int `$width`, int `$height`): Gmagick

Cria uma miniatura de tamanho fixo primeiro reduzindo a imagem e cortando uma área específica a partir do centro.

### Parâmetros

`width`
  A largura da miniatura.
`height`
  A altura da miniatura.

### Valor Retornado

O objeto Gmagick recortado.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::current

(PECL gmagick >= Unknown)

Gmagick::current — Retorna referência ao objeto Gmagick atual

### Descrição

public function Gmagick::current(): Gmagick

Retorna referência ao objeto Gmagick atual com o ponteiro de imagem na sequência correta.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o próprio objeto em caso de sucesso.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::cyclecolormapimage

(PECL gmagick >= Unknown)

Gmagick::cyclecolormapimage — Desloca o mapa de cores de uma imagem

### Descrição

public function Gmagick::cyclecolormapimage(int `$displace`): Gmagick

Desloca o mapa de cores de uma imagem em um determinado número de posições. Se o mapa de cores for alternado várias vezes, é possível produzir um efeito psicodélico.

### Parâmetros

`displace`
  A quantidade a deslocar o mapa de cores.

### Valor Retornado

Retorna o próprio objeto em caso de sucesso.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::deconstructimages

(PECL gmagick >= Unknown)

Gmagick::deconstructimages — Retorna certas diferenças de pixels entre imagens

### Descrição

public function Gmagick::deconstructimages(): Gmagick

Compara cada imagem com a próxima em uma sequência e retorna a região delimitadora máxima de quaisquer diferenças de pixels descobertas.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um novo objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::despeckleimage

(PECL gmagick >= Unknown)

Gmagick::despeckleimage — Reduz manchas em uma imagem

### Descrição

public function Gmagick::despeckleimage(): Gmagick

Reduz o ruído pontilhado em uma imagem, preservando as bordas da imagem original.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O objeto Gmagick sem manchas.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Gmagick::despeckleimage()

    <?php
    /* ... */
    ?>

O exemplo acima produzirá algo semelhante a:

    ...

# Gmagick::destroy

(PECL gmagick >= Unknown)

Gmagick::destroy — Destrói o objeto Gmagick

### Descrição

public function Gmagick::destroy(): bool

Destrói o objeto Gmagick e libera todos os recursos associados a ele.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::drawimage

(PECL gmagick >= Unknown)

Gmagick::drawimage — Renderiza o objeto GmagickDraw na imagem atual

### Descrição

public function Gmagick::drawimage(GmagickDraw `$GmagickDraw`): Gmagick

Renderiza o objeto GmagickDraw na imagem atual.

### Parâmetros

`GmagickDraw`
  As operações de desenho a serem renderizadas na imagem.

### Valor Retornado

O objeto Gmagick desenhado.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::edgeimage

(PECL gmagick >= Unknown)

Gmagick::edgeimage — Melhora as bordas da imagem

### Descrição

public function Gmagick::edgeimage(float `$radius`): Gmagick

Aprimora as bordas da imagem com um filtro de convolução de um determinado raio. Use o raio 0 e ele será selecionado automaticamente.

### Parâmetros

`radius`
  O raio da operação.

### Valor Retornado

O objeto Gmagick com bordas aprimoradas.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::embossimage

(PECL gmagick >= Unknown)

Gmagick::embossimage — Retorna uma imagem em tons de cinza com efeito tridimensional

### Descrição

public function Gmagick::embossimage(float `$radius`, float `$sigma`): Gmagick

Retorna uma imagem em tons de cinza com efeito tridimensional. A imagem sofre convolução com um operador gaussiano de determinado raio e desvio padrão (sigma). Para resultados razoáveis, o raio deve ser maior que o sigma. Use um raio de 0 e o raio mais adequado será definido automaticamente.

### Parâmetros

`radius`
  O raio do efeito.
`sigma`
  O desvio padrão do efeito.

### Valor Retornado

O objeto Gmagick em relevo.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::enhanceimage

(PECL gmagick >= Unknown)

Gmagick::enhanceimage — Melhora a qualidade de uma imagem com ruído

### Descrição

public function Gmagick::enhanceimage(): Gmagick

Aplica um filtro digital que melhora a qualidade de uma imagem com ruído.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O objeto Gmagick aprimorado.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::equalizeimage

(PECL gmagick >= Unknown)

Gmagick::equalizeimage — Equaliza o histograma da imagem

### Descrição

public function Gmagick::equalizeimage(): Gmagick

Equaliza o histograma da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O objeto Gmagick equalizado.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::flipimage

(PECL gmagick >= Unknown)

Gmagick::flipimage — Cria uma imagem espelhada vertical

### Descrição

public function Gmagick::flipimage(): Gmagick

Cria uma imagem espelhada vertical refletindo os pixels em torno do eixo x central.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O objeto Gmagick espelhado.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

### Veja Também

- Gmagick::flopimage() - Cria uma imagem espelhada horizontal

# Gmagick::flopimage

(PECL gmagick >= Unknown)

Gmagick::flopimage — Cria uma imagem espelhada horizontal

### Descrição

public function Gmagick::flopimage(): Gmagick

Cria uma imagem espelhada horizontal refletindo os pixels em torno do eixo y central.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O objeto Gmagick espelhado.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

### Veja Também

- Gmagick::flipimage() - Cria uma imagem espelhada vertical

# Gmagick::frameimage

(PECL gmagick >= Unknown)

Gmagick::frameimage — Adiciona uma borda tridimensional simulada

### Descrição

public function Gmagick::frameimage(
GmagickPixel `$color`,
int `$width`,
int `$height`,
int `$inner_bevel`,
int `$outer_bevel`
): Gmagick

Adiciona uma borda tridimensional simulada ao redor da imagem. A largura e a altura especificam a largura da borda dos lados vertical e horizontal do quadro. Os chanfros internos e externos indicam a largura das sombras internas e externas do quadro.

### Parâmetros

`color`
  Objeto GmagickPixel ou um ponto flutuante representando a cor fosca.
`width`
  A largura da borda.
`height`
  A altura da borda.
`inner_bevel`
  A largura do chanfro interno.
`outer_bevel`
  A largura do chanfro externo.

### Valor Retornado

O objeto Gmagick emoldurado.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::gammaimage

(PECL gmagick >= Unknown)

Gmagick::gammaimage — Corrige o gama da imagem

### Descrição

public function Gmagick::gammaimage(float `$gamma`): Gmagick

Corrige o gama da imagem. A mesma imagem visualizada em diferentes dispositivos terá diferenças perceptivas na forma como as intensidades da imagem são representadas na tela. Especifique níveis de gama individuais para os canais vermelho, verde e azul ou ajuste todos os três com o parâmetro gama. Os valores normalmente variam de 0.8 a 2.3.

### Parâmetros

`gamma`
  A quantidade de correção de gama.

### Valor Retornado

O objeto Gmagick com correção de gama.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getcopyright

(PECL gmagick >= Unknown)

Gmagick::getcopyright — Retorna os direitos autorais da API GraphicsMagick como uma string

### Descrição

public function Gmagick::getcopyright(): string

Retorna os direitos autorais da API GraphicsMagick como uma string.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string contendo o aviso de direitos autorais da API GraphicsMagick e Magickwand C.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getfilename

(PECL gmagick >= Unknown)

Gmagick::getfilename — Obtém o nome do arquivo associado a uma sequência de imagens

### Descrição

public function Gmagick::getfilename(): string

Retorna o nome do arquivo associado a uma sequência de imagens.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string em caso de sucesso.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimagebackgroundcolor

(PECL gmagick >= Unknown)

Gmagick::getimagebackgroundcolor — Retorna a cor de fundo da imagem

### Descrição

public function Gmagick::getimagebackgroundcolor(): GmagickPixel

Retorna a cor de fundo da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um GmagickPixel definido para a cor de fundo da imagem.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimageblueprimary

(PECL gmagick >= Unknown)

Gmagick::getimageblueprimary — Retorna o ponto primário azul da cromaticidade

### Descrição

public function Gmagick::getimageblueprimary(): array

Retorna o ponto primário azul da cromaticidade para a imagem.

### Parâmetros

`x`
  O ponto x do primário azul da cromaticidade.
`y`
  O ponto y do primário azul da cromaticidade.

### Valor Retornado

Array que consiste nas coordenadas "x" e "y" do ponto.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimagebordercolor

(PECL gmagick >= Unknown)

Gmagick::getimagebordercolor — Retorna a cor da borda da imagem

### Descrição

public function Gmagick::getimagebordercolor(): GmagickPixel

Retorna a cor da borda da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Objeto GmagickPixel que representa a cor da borda.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimagechanneldepth

(PECL gmagick >= Unknown)

Gmagick::getimagechanneldepth — Obtém a profundidade de um canal de imagem específico

### Descrição

public function Gmagick::getimagechanneldepth(int `$channel_type`): int

Obtém a profundidade de um canal de imagem específico.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Profundidade do canal de imagem

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimagecolors

(PECL gmagick >= Unknown)

Gmagick::getimagecolors — Retorna a cor do índice do mapa de cores especificado

### Descrição

public function Gmagick::getimagecolors(): int

Retorna a cor do índice do mapa de cores especificado.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O número de cores na imagem.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimagecolorspace

(PECL gmagick >= Unknown)

Gmagick::getimagecolorspace — Obtém o espaço de cores da imagem

### Descrição

public function Gmagick::getimagecolorspace(): int

Obtém o espaço de cores da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O espaço de cores da imagem.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimagecompose

(PECL gmagick >= Unknown)

Gmagick::getimagecompose — Retorna o operador de composição associado à imagem

### Descrição

public function Gmagick::getimagecompose(): int

Retorna o operador de composição associado à imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o operador de composição associado à imagem.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimagedelay

(PECL gmagick >= Unknown)

Gmagick::getimagedelay — Obtém o atraso da imagem

### Descrição

public function Gmagick::getimagedelay(): int

Obtém o atraso da imagem

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o atraso da imagem.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimagedepth

(PECL gmagick >= Unknown)

Gmagick::getimagedepth — Obtém a profundidade da imagem

### Descrição

public function Gmagick::getimagedepth(): int

Obtém a profundidade da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

A profundidade da imagem.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimagedispose

(PECL gmagick >= Unknown)

Gmagick::getimagedispose — Obtém o método de descarte de imagem

### Descrição

public function Gmagick::getimagedispose(): int

Obtém o método de descarte de imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o método de descarte em caso de sucesso.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimageextrema

(PECL gmagick >= Unknown)

Gmagick::getimageextrema — Obtém os extremos da imagem

### Descrição

public function Gmagick::getimageextrema(): array

Retorna um array associativo com as chaves "min" e "max". Lança uma exceção GmagickException em caso de erro.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array associativo com as chaves "min" e "max".

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimagefilename

(PECL gmagick >= Unknown)

Gmagick::getimagefilename — Retorna o nome do arquivo de uma imagem específica em uma sequência

### Descrição

public function Gmagick::getimagefilename(): string

Retorna o nome do arquivo de uma imagem específica em uma sequência

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string com o nome do arquivo da imagem

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimageformat

(PECL gmagick >= Unknown)

Gmagick::getimageformat — Retorna o formato de uma imagem específica em uma sequência

### Descrição

public function Gmagick::getimageformat(): string

Retorna o formato de uma imagem específica em uma sequência.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string contendo o formato da imagem em caso de sucesso.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimagegamma

(PECL gmagick >= Unknown)

Gmagick::getimagegamma — Obtém o gama da imagem

### Descrição

public function Gmagick::getimagegamma(): float

Obtém o gama da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o gama da imagem em caso de sucesso

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimagegreenprimary

(PECL gmagick >= Unknown)

Gmagick::getimagegreenprimary — Retorna o ponto primário verde da cromaticidade

### Descrição

public function Gmagick::getimagegreenprimary(): array

Retorna o ponto primário verde da cromaticidade. Retorna um array com as chaves "x" e "y".

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array com as chaves "x" e "y" em caso de sucesso.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimageheight

(PECL gmagick >= Unknown)

Gmagick::getimageheight — Retorna a altura da imagem

### Descrição

public function Gmagick::getimageheight(): int

Retorna a altura da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a altura da imagem em pixels.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimagehistogram

(PECL gmagick >= Unknown)

Gmagick::getimagehistogram — Obtém o histograma da imagem

### Descrição

public function Gmagick::getimagehistogram(): array

Retorna o histograma da imagem como um array de objetos GmagickPixel. Lança uma GmagickException em caso de erro.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o histograma da imagem como um array de objetos GmagickPixel.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimageindex

(PECL gmagick >= Unknown)

Gmagick::getimageindex — Obtém o índice da imagem ativa atual

### Descrição

public function Gmagick::getimageindex(): int

Retorna o índice da imagem ativa atual dentro do objeto Gmagick.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Índice da imagem ativa atual.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimageinterlacescheme

(PECL gmagick >= Unknown)

Gmagick::getimageinterlacescheme — Obtém o esquema de entrelaçamento da imagem

### Descrição

public function Gmagick::getimageinterlacescheme(): int

Obtém o esquema da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o esquema de entrelaçamento como um número inteiro em caso de sucesso.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimageiterations

(PECL gmagick >= Unknown)

Gmagick::getimageiterations — Obtém as iterações da imagem

### Descrição

public function Gmagick::getimageiterations(): int

Obtém as iterações da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna as iterações da imagem como um número inteiro.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimagematte

(PECL gmagick >= Unknown)

Gmagick::getimagematte — Verifique se a imagem possui um canal fosco

### Descrição

public function Gmagick::getimagematte(): int

Retorna `true` se a imagem tiver um canal fosco, caso contrário, `false`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se a imagem tiver um canal fosco, caso contrário, `false`.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimagemattecolor

(PECL gmagick >= Unknown)

Gmagick::getimagemattecolor — Retorna a cor fosca da imagem

### Descrição

public function Gmagick::getimagemattecolor(): GmagickPixel

Retorna o objeto GmagickPixel em caso de sucesso. Lança uma GmagickException em caso de erro.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o objeto GmagickPixel em caso de sucesso.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimageprofile

(PECL gmagick >= Unknown)

Gmagick::getimageprofile — Retorna o perfil de imagem nomeado

### Descrição

public function Gmagick::getimageprofile(string `$name`): string

Retorna o perfil de imagem nomeado.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string contendo o perfil da imagem.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimageredprimary

(PECL gmagick >= Unknown)

Gmagick::getimageredprimary — Retorna o ponto primário vermelho da cromaticidade

### Descrição

public function Gmagick::getimageredprimary(): array

Retorna o ponto primário vermelho de cromaticidade como um array com as chaves "x" e "y".

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ponto primário vermelho de cromaticidade como um array com as chaves "x" e "y".

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimagerenderingintent

(PECL gmagick >= Unknown)

Gmagick::getimagerenderingintent — Obtém a intenção de renderização da imagem

### Descrição

public function Gmagick::getimagerenderingintent(): int

Obtém a intenção de renderização da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a intenção de renderização da imagem.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimageresolution

(PECL gmagick >= Unknown)

Gmagick::getimageresolution — Obtém a resolução X e Y da imagem

### Descrição

public function Gmagick::getimageresolution(): array

Retorna a resolução como um array.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a resolução como um array.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimagescene

(PECL gmagick >= Unknown)

Gmagick::getimagescene — Obtém a cena da imagem

### Descrição

public function Gmagick::getimagescene(): int

Obtém a cena da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a cena da imagem.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimagesignature

(PECL gmagick >= Unknown)

Gmagick::getimagesignature — Gera um resumo de mensagem SHA-256

### Descrição

public function Gmagick::getimagesignature(): string

Gera um resumo de mensagem SHA-256 para o fluxo de pixels da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string contendo o hash SHA-256 do arquivo.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimagetype

(PECL gmagick >= Unknown)

Gmagick::getimagetype — Obtém o tipo de imagem potencial

### Descrição

public function Gmagick::getimagetype(): int

Obtém o tipo de imagem potencial.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o tipo de imagem potencial.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimageunits

(PECL gmagick >= Unknown)

Gmagick::getimageunits — Obtém as unidades de resolução da imagem

### Descrição

public function Gmagick::getimageunits(): int

Obtém as unidades de resolução da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna as unidades de resolução da imagem.

# Gmagick::getimagewhitepoint

(PECL gmagick >= Unknown)

Gmagick::getimagewhitepoint — Retorna o ponto branco da cromaticidade

### Descrição

public function Gmagick::getimagewhitepoint(): array

Retorna o ponto branco da cromaticidade como um array associativo com as chaves "x" e "y".

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ponto branco da cromaticidade como um array associativo com as chaves "x" e "y".

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getimagewidth

(PECL gmagick >= Unknown)

Gmagick::getimagewidth — Retorna a largura da imagem

### Descrição

public function Gmagick::getimagewidth(): int

Retorna a largura da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a largura da imagem.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getpackagename

(PECL gmagick >= Unknown)

Gmagick::getpackagename — Retorna o nome do pacote GraphicsMagick

### Descrição

public function Gmagick::getpackagename(): string

Retorna o nome do pacote GraphicsMagick.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o nome do pacote GraphicsMagick como uma string.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getquantumdepth

(PECL gmagick >= Unknown)

Gmagick::getquantumdepth — Retorna a profundidade de Quantum do Gmagick como uma string

### Descrição

public function Gmagick::getquantumdepth(): array

Retorna a profundidade de Quantum Gmagick como uma string.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a profundidade de Quantum Gmagick como uma string.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getreleasedate

(PECL gmagick >= Unknown)

Gmagick::getreleasedate — Retorna a data de lançamento do GraphicsMagick como uma string

### Descrição

public function Gmagick::getreleasedate(): string

Retorna a data de lançamento do GraphicsMagick como uma string.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a data de lançamento do GraphicsMagick como uma string.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getsamplingfactors

(PECL gmagick >= Unknown)

Gmagick::getsamplingfactors — Obtém o fator de amostragem horizontal e vertical

### Descrição

public function Gmagick::getsamplingfactors(): array

Obtém o fator de amostragem horizontal e vertical.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array associativo com os fatores de amostragem horizontal e vertical da imagem.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getsize

(PECL gmagick >= Unknown)

Gmagick::getsize — Retorna o tamanho associado ao objeto Gmagick

### Descrição

public function Gmagick::getsize(): array

Retorna o tamanho associado ao objeto Gmagick como um array com as chaves "columns" (colunas) e "rows" (linhas).

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o tamanho associado ao objeto Gmagick como um array com as chaves "columns" (colunas) e "rows" (linhas).

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::getversion

(PECL gmagick >= Unknown)

Gmagick::getversion — Retorna a versão da API GraphicsMagick

### Descrição

public function Gmagick::getversion(): array

Retorna a versão da API GraphicsMagick como uma string e um número.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a versão da API GraphicsMagick como uma string e um número.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::hasnextimage

(PECL gmagick >= Unknown)

Gmagick::hasnextimage — Verifica se o objeto possui mais imagens

### Descrição

public function Gmagick::hasnextimage(): mixed

Retorna `true` se o objeto tiver mais imagens ao percorrer a lista na direção direta.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se o objeto tiver mais imagens ao percorrer a lista na direção direta, retorna `false` se não houver nenhum.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::haspreviousimage

(PECL gmagick >= Unknown)

Gmagick::haspreviousimage — Verifica se o objeto possui uma imagem anterior

### Descrição

public function Gmagick::haspreviousimage(): mixed

Retorna `true` se o objeto tiver mais imagens ao percorrer a lista na direção inversa.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se o objeto tiver mais imagens ao percorrer a lista no sentido inverso, retorna `false` se não houver nenhum.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::implodeimage

(PECL gmagick >= Unknown)

Gmagick::implodeimage — Cria uma nova imagem implodida

### Descrição

public function Gmagick::implodeimage(float `$radius`): mixed

Cria uma nova imagem que é uma cópia de uma existente com os pixels da imagem "implodidos" pela porcentagem especificada.

### Parâmetros

`radius`
  O raio da implosão.

### Valor Retornado

Retorna o objeto Gmagick implodido.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::labelimage

(PECL gmagick >= Unknown)

Gmagick::labelimage — Adiciona um rótulo a uma imagem

### Descrição

public function Gmagick::labelimage(string `$label`): mixed

Adiciona um rótulo a uma imagem.

### Parâmetros

`label`
  O rótulo a ser adicionado

### Valor Retornado

Gmagick com rótulo.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::levelimage

(PECL gmagick >= Unknown)

Gmagick::levelimage — Ajusta os níveis de uma imagem

### Descrição

public function Gmagick::levelimage(
float `$blackPoint`,
float `$gamma`,
float `$whitePoint`,
int `$channel` = Gmagick::CHANNEL_DEFAULT
): mixed

Ajusta os níveis de uma imagem dimensionando as cores que ficam entre os pontos brancos e pretos especificados para toda a faixa de Quantum disponível. Os parâmetros fornecidos representam os pontos preto, médio e branco. O ponto preto especifica a cor mais escura da imagem. As cores mais escuras que o ponto preto são definidas como zero. O ponto médio especifica uma correção de gama a ser aplicada à imagem. O ponto branco especifica a cor mais clara da imagem. As cores mais claras que o ponto branco são definidas com o valor máximo de Quantum.

### Parâmetros

`blackPoint`
  O ponto preto da imagem.
`gamma`
  O valor de gama.
`whitePoint`
  O ponto branco da imagem.
`channel`
  Pode ser fornecida qualquer constante de canal válida para o modo de canal. Para aplicar a mais de um canal, constantes de tipo de canal devem ser combinadas usando operadores binários. Consulte esta lista de constantes de canal.

### Valor Retornado

Objeto Gmagick com imagem nivelada.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::magnifyimage

(PECL gmagick >= Unknown)

Gmagick::magnifyimage — Amplia uma imagem para o dobro de seu tamanho

### Descrição

public function Gmagick::magnifyimage(): mixed

Dimensiona convenientemente uma imagem proporcionalmente ao dobro do seu tamanho original.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Objeto Gmagick ampliado.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::mapimage

(PECL gmagick >= Unknown)

Gmagick::mapimage — Substitui as cores de uma imagem pela cor mais próxima de uma imagem de referência

### Descrição

public function Gmagick::mapimage(gmagick `$gmagick`, bool `$dither`): Gmagick

Substitui as cores de uma imagem pela cor mais próxima de uma imagem de referência.

### Parâmetros

`gmagick`
  A imagem de referência.
`dither`
  Defina esse valor inteiro como algo diferente de zero para pontilhar a imagem mapeada.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::medianfilterimage

(PECL gmagick >= Unknown)

Gmagick::medianfilterimage — Aplica um filtro digital

### Descrição

public function Gmagick::medianfilterimage(float `$radius`): void

Aplica um filtro digital que melhora a qualidade de uma imagem com ruído. Cada pixel é substituído pela mediana em um conjunto de pixels vizinhos conforme definido pelo raio.

### Parâmetros

`radius`
  O raio da vizinhança do pixel.

### Valor Retornado

Objeto Gmagick com filtro de mediana aplicado.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::minifyimage

(PECL gmagick >= Unknown)

Gmagick::minifyimage — Reduz uma imagem à metade de seu tamanho

### Descrição

public function Gmagick::minifyimage(): Gmagick

Um método conveniente que dimensiona uma imagem proporcionalmente à metade do seu tamanho original.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::modulateimage

(PECL gmagick >= Unknown)

Gmagick::modulateimage — Controle brilho, saturação e matiz

### Descrição

public function Gmagick::modulateimage(float `$brightness`, float `$saturation`, float `$hue`): Gmagick

Permite controlar o brilho, a saturação e o matiz de uma imagem. Matiz é a porcentagem de rotação absoluta da posição atual. Por exemplo, 50 resulta em uma rotação no sentido anti-horário de 90 graus, 150 resulta em uma rotação no sentido horário de 90 graus, com 0 e 200 resultando em uma rotação de 180 graus.

### Parâmetros

`brightness`
  A alteração percentual no brilho (-100 a +100).
`saturation`
  A mudança percentual na saturação (-100 a +100)
`hue`
  A mudança percentual no matiz (-100 a +100)

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::motionblurimage

(PECL gmagick >= Unknown)

Gmagick::motionblurimage — Simula desfoque de movimento

### Descrição

public function Gmagick::motionblurimage(float `$radius`, float `$sigma`, float `$angle`): Gmagick

Simula desfoque de movimento. A imagem sofre convolução com um operador gaussiano de determinado raio e desvio padrão (sigma). Para resultados razoáveis, o raio deve ser maior que o sigma. Com um raio de 0, Gmagick::motionblurimage() seleciona um raio adequado automaticamente. O parâmetro "angle" informa o ângulo do movimento de desfoque.

### Parâmetros

`radius`
  O raio do gaussiano, em pixels, sem contar o pixel central.
`sigma`
  O desvio padrão do gaussiano, em pixels.
`angle`
  O efeito será aplicado no ângulo definido por este parâmetro.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::newimage

(PECL gmagick >= Unknown)

Gmagick::newimage — Cria uma nova imagem

### Descrição

public function Gmagick::newimage(
int `$width`,
int `$height`,
string `$background`,
string `$format` = ?
): Gmagick

Cria uma nova imagem com a cor de fundo especificada.

### Parâmetros

`width`
  Largura da nova imagem.
`height`
  Altura da nova imagem.
`background`
  A cor de fundo usada para esta imagem (como float).
`format`
  Formato de imagem.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::nextimage

(PECL gmagick >= Unknown)

Gmagick::nextimage — Passa para a próxima imagem

### Descrição

public function Gmagick::nextimage(): bool

Associa a próxima imagem na lista de imagens a um objeto Gmagick.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::normalizeimage

(PECL gmagick >= Unknown)

Gmagick::normalizeimage — Melhora o contraste de uma imagem colorida

### Descrição

public function Gmagick::normalizeimage(int `$channel` = ?): Gmagick

Melhora o contraste de uma imagem colorida ajustando a cor dos pixels para abranger toda a gama de cores disponíveis.

### Parâmetros

`channel`
  Identifica qual canal será normalizado.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::oilpaintimage

(PECL gmagick >= Unknown)

Gmagick::oilpaintimage — Simula uma pintura a óleo

### Descrição

public function Gmagick::oilpaintimage( float `$radius` ): Gmagick

Aplica um filtro de efeito especial que simula uma pintura a óleo. Cada pixel é substituído pela cor mais frequente que ocorre em uma região circular definida pelo raio.

### Parâmetros

`radius`
  O raio da vizinhança circular.

### Valor Retornado

O objeto Gmagick em caso de sucesso.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::previousimage

(PECL gmagick >= Unknown)

Gmagick::previousimage — Passa para a imagem anterior no objeto

### Descrição

public function Gmagick::previousimage(): bool

Associa a imagem anterior em uma lista de imagens ao objeto Gmagick.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::profileimage

(PECL gmagick >= Unknown)

Gmagick::profileimage — Adiciona ou remove um perfil de uma imagem

### Descrição

public function Gmagick::profileimage(string `$name`, string `$profile`): Gmagick

Adiciona ou remove um perfil ICC, IPTC ou genérico de uma imagem. Se o perfil for `null`, ele será removido da imagem adicionada. Use um nome `*` e um perfil `null` para remover todos os perfis da imagem.

### Parâmetros

`name`
  Nome do perfil a ser adicionado ou removido: ICC, IPTC ou perfil genérico.
`profile`
  O perfil.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::quantizeimage

(PECL gmagick >= Unknown)

Gmagick::quantizeimage — Analisa as cores dentro de uma imagem de referência

### Descrição

public function Gmagick::quantizeimage(
int `$numColors`,
int `$colorspace`,
int `$treeDepth`,
bool `$dither`,
bool `$measureError`
): Gmagick

Analisa as cores em uma imagem de referência e escolhe um número fixo de cores para representar a imagem. O objetivo do algoritmo é minimizar a diferença de cor entre a imagem de entrada e de saída e, ao mesmo tempo, minimizar o tempo de processamento.

### Parâmetros

`numColors`
  O número de cores.
`colorspace`
  Executa a redução de cores neste espaço de cores, normalmente RGBColorspace.
`treeDepth`
  Normalmente, esse valor inteiro é zero ou um. Zero ou um diz à função para escolher uma profundidade de árvore ideal de Log4(número_de_cores). Uma árvore com essa profundidade geralmente permite a melhor representação da imagem de referência com a menor quantidade de memória e a velocidade computacional mais rápida. Em alguns casos, como uma imagem com baixa dispersão de cores (poucos números de cores), é necessário um valor diferente de Log4(number_colors). Para expandir completamente a árvore de cores, use o valor 8.
`dither`
  Um valor diferente de zero distribui a diferença entre uma imagem original e o algoritmo de redução de cor correspondente para pixels vizinhos ao longo de uma curva de Hilbert.
`measureError`
  Um valor diferente de zero mede a diferença entre as imagens original e quantizada. Essa diferença é o erro total de quantização. O erro é calculado somando todos os pixels de uma imagem a distância ao quadrado no espaço RGB entre cada valor de pixel de referência e seu valor quantizado.

### Valor Retornado

O objeto Gmagick em caso de sucesso.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::quantizeimages

(PECL gmagick >= Unknown)

Gmagick::quantizeimages — Analisa as cores dentro de imagens de referência

### Descrição

public function Gmagick::quantizeimages(
int `$numColors`,
int `$colorspace`,
int `$treeDepth`,
bool `$dither`,
bool `$measureError`
): Gmagick

Analisa as cores dentro de uma sequência de imagens e escolhe um número fixo de cores para representar a imagem. O objetivo do algoritmo é minimizar a, diferença de cor entre a imagem de entrada e de saída e, ao mesmo tempo, minimizar o tempo de processamento.

### Parâmetros

`numColors`
  O número de cores.
`colorspace`
  Executa a redução de cores neste espaço de cores, normalmente RGBColorspace.
`treeDepth`
  Normalmente, esse valor inteiro é zero ou um. Zero ou um diz à função para escolher uma profundidade de árvore ideal de Log4(número_de_cores). Uma árvore com essa profundidade geralmente permite a melhor representação da imagem de referência com a menor quantidade de memória e a velocidade computacional mais rápida. Em alguns casos, como uma imagem com baixa dispersão de cores (poucos números de cores), é necessário um valor diferente de Log4(number_colors). Para expandir completamente a árvore de cores, use o valor 8.
`dither`
  Um valor diferente de zero distribui a diferença entre uma imagem original e o algoritmo de redução de cor correspondente para pixels vizinhos ao longo de uma curva de Hilbert.
`measureError`
  Um valor diferente de zero mede a diferença entre as imagens original e quantizada. Essa diferença é o erro total de quantização. O erro é calculado somando todos os pixels de uma imagem a distância ao quadrado no espaço RGB entre cada valor de pixel de referência e seu valor quantizado.

### Valor Retornado

O objeto Gmagick em caso de sucesso.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::queryfontmetrics

(PECL gmagick >= Unknown)

Gmagick::queryfontmetrics — Retorna um array representando as métricas da fonte

### Descrição

public function Gmagick::queryfontmetrics(GmagickDraw `$draw`, string `$text`): array

MagickQueryFontMetrics() retorna um array representando as métricas da fonte.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O objeto Gmagick em caso de sucesso.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::queryfonts

(PECL gmagick >= Unknown)

Gmagick::queryfonts — Retorna as fontes configuradas

### Descrição

public function Gmagick::queryfonts(string `$pattern` = "*"): array

Retorna fontes suportadas pelo Gmagick.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O objeto Gmagick em caso de sucesso.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::queryformats

(PECL gmagick >= Unknown)

Gmagick::queryformats — Retorna formatos suportados pelo Gmagick

### Descrição

public function Gmagick::queryformats(string `$pattern` = "*"): array

Retorna formatos suportados pelo Gmagick.

### Parâmetros

`pattern`
  Especifica uma string contendo um padrão.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::radialblurimage

(PECL gmagick >= Unknown)

Gmagick::radialblurimage — Desfoca uma imagem de forma radial

### Descrição

public function Gmagick::radialblurimage(float `$angle`, int `$channel` = Gmagick::CHANNEL_DEFAULT): Gmagick

Desfoca uma imagem de forma radial

### Parâmetros

`angle`
  O ângulo do desfoque em graus.
`channel`
  Canal relacionado.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::raiseimage

(PECL gmagick >= Unknown)

Gmagick::raiseimage — Cria um efeito simulado de botão 3D

### Descrição

public function Gmagick::raiseimage(
int `$width`,
int `$height`,
int `$x`,
int `$y`,
bool `$raise`
): Gmagick

Cria um efeito simulado de botão tridimensional, iluminando e escurecendo as bordas da imagem. Os membros "width" e "height" definem a largura da borda vertical e horizontal do efeito.

### Parâmetros

`width`
  Largura da área a elevar.
`height`
  Altura da área a elevar.
`x`
  Coordenada X.
`y`
  Coordenada Y.
`raise`
  Um valor diferente de zero cria um efeito 3D de elevação, caso contrário, tem um efeito de rebaixamento.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::read

(PECL gmagick >= Unknown)

Gmagick::read — Lê imagem a partir de um arquivo

### Descrição

public function Gmagick::read(string `$filename`): Gmagick

Lê imagem a partir de um arquivo.

### Parâmetros

`filename`
  O nome do arquivo da imagem.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::readimage

(PECL gmagick >= Unknown)

Gmagick::readimage — Lê imagem a partir de um arquivo

### Descrição

public function Gmagick::readimage(string `$filename`): Gmagick

Lê imagem a partir de um arquivo.

### Parâmetros

`filename`
  O nome do arquivo da imagem.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::readimageblob

(PECL gmagick >= Unknown)

Gmagick::readimageblob — Lê imagem a partir de uma string binária

### Descrição

public function Gmagick::readimageblob(string `$imageContents`, string `$filename` = ?): Gmagick

Lê imagem a partir de uma string binária

### Parâmetros

`imageContents`
  Conteúdo da imagem.
`filename`
  O nome do arquivo da imagem.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::readimagefile

(PECL gmagick >= Unknown)

Gmagick::readimagefile — Lê imagem a partir de um descritor de arquivo

### Descrição

public function Gmagick::readimagefile(resource `$fp`, string `$filename` = ?): Gmagick

Lê uma imagem ou sequência de imagens de um descritor de arquivo aberto.

### Parâmetros

`fp`
  O descritor de arquivo.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::reducenoiseimage

(PECL gmagick >= Unknown)

Gmagick::reducenoiseimage — Suaviza os contornos de uma imagem

### Descrição

public function Gmagick::reducenoiseimage(float `$radius`): Gmagick

Suaviza os contornos de uma imagem enquanto preserva as informações das bordas. O algoritmo funciona substituindo cada pixel pelo seu vizinho de valor mais próximo. Um vizinho é definido pelo raio. Com um raio de 0, Gmagick::reducenoiseimage() seleciona um raio adequado automaticamente.

### Parâmetros

`radius`
  O raio da vizinhança do pixel.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::removeimage

(PECL gmagick >= Unknown)

Gmagick::removeimage — Remove uma imagem da lista de imagens

### Descrição

public function Gmagick::removeimage(): Gmagick

Remove uma imagem da lista de imagens.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::removeimageprofile

(PECL gmagick >= Unknown)

Gmagick::removeimageprofile — Remove o perfil de imagem nomeado e o retorna

### Descrição

public function Gmagick::removeimageprofile(string `$name`): string

Remove o perfil de imagem nomeado e o retorna.

### Parâmetros

`name`
  Nome do perfil a ser retornado: ICC, IPTC ou perfil genérico.

### Valor Retornado

O perfil nomeado.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::resampleimage

(PECL gmagick >= Unknown)

Gmagick::resampleimage — Reamostra imagem para a resolução desejada

### Descrição

public function Gmagick::resampleimage(
float `$xResolution`,
float `$yResolution`,
int `$filter`,
float `$blur`
): Gmagick

Reamostra imagem para a resolução desejada.

### Parâmetros

`xResolution`
  A nova resolução X da imagem.
`yResolution`
  A nova resolução Y da imagem.
`filter`
  Filtro de imagem a ser usado.
`blur`
  O fator de desfoque onde maior que 1 é desfocado, menor que 1 é nítido.

### Valor Retornado

O objeto Gmagick em caso de sucesso.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::resizeimage

(PECL gmagick >= Unknown)

Gmagick::resizeimage — Dimensiona uma imagem

### Descrição

public function Gmagick::resizeimage(
int `$width`,
int `$height`,
int `$filter`,
float `$blur`,
bool `$fit` = `false`
): Gmagick

Dimensiona uma imagem para as dimensões desejadas com um filtro.

### Parâmetros

`width`
  O número de colunas na imagem dimensionada.
`height`
  O número de linhas na imagem dimensionada.
`filter`
  Filtro de imagem a ser usado.
`blur`
  O fator de desfoque onde maior que 1 é desfocado, menor que 1 é nítido.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::rollimage

(PECL gmagick >= Unknown)

Gmagick::rollimage — Desloca uma imagem

### Descrição

public function Gmagick::rollimage(int `$x`, int `$y`): Gmagick

Desloca uma imagem conforme definido por x e y.

### Parâmetros

`x`
  O deslocamento em x.
`y`
  O deslocamento em y.

### Valor Retornado

O objeto Gmagick em caso de sucesso.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::rotateimage

(PECL gmagick >= Unknown)

Gmagick::rotateimage — Rotaciona uma imagem

### Descrição

public function Gmagick::rotateimage(mixed `$color`, float `$degrees`): Gmagick

Rotaciona uma imagem no número especificado de graus. Os triângulos vazios que sobrarem da rotação da imagem são preenchidos com a cor de fundo.

### Parâmetros

`color`
  A cor de fundo.
`degrees`
  O número de graus para rotacionar a imagem.

### Valor Retornado

O objeto Gmagick em caso de sucesso.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::scaleimage

(PECL gmagick >= Unknown)

Gmagick::scaleimage — Dimensiona o tamanho de uma imagem

### Descrição

public function Gmagick::scaleimage(int `$width`, int `$height`, bool `$fit` = `false`): Gmagick

Dimensiona o tamanho de uma imagem para as dimensões fornecidas. O outro parâmetro será calculado se 0 for passado como qualquer um dos parâmetros.

### Parâmetros

`width`
  O número de colunas na imagem dimensionada.
`height`
  O número de linhas na imagem dimensionada.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::separateimagechannel

(PECL gmagick >= Unknown)

Gmagick::separateimagechannel — Separa um canal da imagem

### Descrição

public function Gmagick::separateimagechannel(int `$channel`): Gmagick

Separa um canal da imagem e retorna uma imagem em tons de cinza. Um canal é um componente de cor específico de cada pixel da imagem.

### Parâmetros

`channel`
  Uma das constantes Channel (`Gmagick::CHANNEL_*`).

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::setCompressionQuality

(No version information available, might only be in Git)

Gmagick::setCompressionQuality — Define a qualidade de compactação padrão do objeto

### Descrição

function Gmagick::setCompressionQuality( int `$quality` ): Gmagick

Define a qualidade de compactação padrão do objeto.

### Parâmetros

`quality`
  O valor padrão de GraphicsMagick é 75.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

### Exemplos

Exemplo #1 Gmagick::setCompressionQuality()

    <?php
    $gm = new Gmagick();
    $gm->read("magick:rose");
    $gm->setCompressionQuality(2);
    ?>

# Gmagick::setfilename

(PECL gmagick >= Unknown)

Gmagick::setfilename — Define o nome do arquivo antes de ler ou gravar a imagem

### Descrição

public function Gmagick::setfilename(string `$filename`): Gmagick

Define o nome do arquivo antes de ler ou gravar um arquivo de imagem.

### Parâmetros

`filename`
  O nome do arquivo da imagem.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::setimagebackgroundcolor

(PECL gmagick >= Unknown)

Gmagick::setimagebackgroundcolor — Define a cor de fundo da imagem

### Descrição

public function Gmagick::setimagebackgroundcolor(GmagickPixel `$color`): Gmagick

Define a cor de fundo da imagem.

### Parâmetros

`color`
  A varinha de pixel de fundo.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::setimageblueprimary

(PECL gmagick >= Unknown)

Gmagick::setimageblueprimary — Define o ponto primário azul da cromaticidade da imagem

### Descrição

public function Gmagick::setimageblueprimary(float `$x`, float `$y`): Gmagick

Define o ponto primário azul da cromaticidade da imagem.

### Parâmetros

`x`
  A coordenada x do ponto primário azul.
`y`
  A coordenada y do ponto primário azul.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::setimagebordercolor

(PECL gmagick >= Unknown)

Gmagick::setimagebordercolor — Define a cor da borda da imagem

### Descrição

public function Gmagick::setimagebordercolor(GmagickPixel `$color`): Gmagick

Define a cor da borda da imagem.

### Parâmetros

`color`
  A varinha de pixel de borda.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::setimagechanneldepth

(PECL gmagick >= Unknown)

Gmagick::setimagechanneldepth — Define a profundidade de um canal de imagem específico

### Descrição

public function Gmagick::setimagechanneldepth(int `$channel`, int `$depth`): Gmagick

Define a profundidade de um canal de imagem específico.

### Parâmetros

`channel`
  Uma das constantes Channel (`Gmagick::CHANNEL_*`).
`depth`
  A profundidade da imagem em bits.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::setimagecolorspace

(PECL gmagick >= Unknown)

Gmagick::setimagecolorspace — Define o espaço de cores da imagem

### Descrição

public function Gmagick::setimagecolorspace(int `$colorspace`): Gmagick

Define o espaço de cores da imagem.

### Parâmetros

`colorspace`
  Uma das constantes Colorspace (`Gmagick::COLORSPACE_*`).

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::setimagecompose

(PECL gmagick >= Unknown)

Gmagick::setimagecompose — Define o operador de composição da imagem

### Descrição

public function Gmagick::setimagecompose(int `$composite`): Gmagick

Define o operador de composição da imagem.

### Parâmetros

`composite`
  O operador de composição da imagem.

### Valor Retornado

O objeto Gmagick em caso de sucesso.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::setimagedelay

(PECL gmagick >= Unknown)

Gmagick::setimagedelay — Define o atraso da imagem

### Descrição

public function Gmagick::setimagedelay(int `$delay`): Gmagick

Define o atraso da imagem.

### Parâmetros

`delay`
  O atraso da imagem em 1/100 de segundo.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::setimagedepth

(PECL gmagick >= Unknown)

Gmagick::setimagedepth — Define a profundidade da imagem

### Descrição

public function Gmagick::setimagedepth(int `$depth`): Gmagick

Define a profundidade da imagem.

### Parâmetros

`depth`
  A profundidade da imagem em bits: 8, 16 ou 32.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::setimagedispose

(PECL gmagick >= Unknown)

Gmagick::setimagedispose — Define o método de descarte de imagem

### Descrição

public function Gmagick::setimagedispose(int `$disposeType`): Gmagick

Define o método de descarte de imagem.

### Parâmetros

`disposeType`
  O método de descarte de imagem.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::setimagefilename

(PECL gmagick >= Unknown)

Gmagick::setimagefilename — Define o nome do arquivo de uma imagem específica em uma sequência

### Descrição

public function Gmagick::setimagefilename(string `$filename`): Gmagick

Define o nome do arquivo de uma imagem específica em uma sequência.

### Parâmetros

`filename`
  O nome do arquivo da imagem

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::setimageformat

(PECL gmagick >= Unknown)

Gmagick::setimageformat — Define o formato de uma imagem específica

### Descrição

public function Gmagick::setimageformat(string `$imageFormat`): Gmagick

Define o formato de uma imagem específica em uma sequência.

### Parâmetros

`imageFormat`
  O formato da imagem

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::setimagegamma

(PECL gmagick >= Unknown)

Gmagick::setimagegamma — Define o gama da imagem

### Descrição

public function Gmagick::setimagegamma(float `$gamma`): Gmagick

Define o gama da imagem.

### Parâmetros

`gamma`
  O gama da imagem.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::setimagegreenprimary

(PECL gmagick >= Unknown)

Gmagick::setimagegreenprimary — Define o ponto primário verde da cromaticidade da imagem

### Descrição

public function Gmagick::setimagegreenprimary(float `$x`, float `$y`): Gmagick

Define o ponto primário verde da cromaticidade da imagem.

### Parâmetros

`x`
  A coordenada x do ponto primário verde de cromaticidade.
`y`
  A coordenada y do ponto primário verde de cromaticidade.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::setimageindex

(PECL gmagick >= Unknown)

Gmagick::setimageindex — Defina o iterador para a posição na lista de imagens especificada

### Descrição

public function Gmagick::setimageindex(int `$index`): Gmagick

Defina o iterador para a posição definida pelo índice na lista de imagens especificada.

### Parâmetros

`index`
  Índice da cena.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::setimageinterlacescheme

(PECL gmagick >= Unknown)

Gmagick::setimageinterlacescheme — Define o esquema de entrelaçamento da imagem

### Descrição

public function Gmagick::setimageinterlacescheme(int `$interlace`): Gmagick

Define o esquema de entrelaçamento da imagem.

### Parâmetros

`interlace`
  Uma das constantes Interlace (`Gmagick::INTERLACE_*`).

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::setimageiterations

(PECL gmagick >= Unknown)

Gmagick::setimageiterations — Define as iterações da imagem

### Descrição

public function Gmagick::setimageiterations(int `$iterations`): Gmagick

Define as iterações da imagem.

### Parâmetros

`iterations`
  O número de iterações.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::setimageprofile

(PECL gmagick >= Unknown)

Gmagick::setimageprofile — Adiciona um perfil nomeado ao objeto Gmagick

### Descrição

public function Gmagick::setimageprofile(string `$name`, string `$profile`): Gmagick

Adiciona um perfil nomeado ao objeto Gmagick. Se já existir um perfil com o mesmo nome, ele será substituído. Este método difere do método Gmagick::profileimage() porque não aplica nenhum perfil de cores CMS.

### Parâmetros

`name`
  Nome do perfil a ser adicionado ou removido: ICC, IPTC ou perfil genérico.
`profile`
  O perfil.

### Valor Retornado

O objeto Gmagick em caso de sucesso.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::setimageredprimary

(PECL gmagick >= Unknown)

Gmagick::setimageredprimary — Define o ponto primário vermelho da cromaticidade da imagem

### Descrição

public function Gmagick::setimageredprimary(float `$x`, float `$y`): Gmagick

Define o ponto primário vermelho da cromaticidade da imagem.

### Parâmetros

`x`
  Coordenada x do ponto primário vermelho.
`y`
  Coordenada y do ponto primário vermelho.

### Valor Retornado

O objeto Gmagick em caso de sucesso.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::setimagerenderingintent

(PECL gmagick >= Unknown)

Gmagick::setimagerenderingintent — Define a intenção de renderização da imagem

### Descrição

public function Gmagick::setimagerenderingintent(int `$rendering_intent`): Gmagick

Define a intenção de renderização da imagem.

### Parâmetros

`rendering_intent`
  Uma das constantes de intenção de renderização (`Gmagick::RENDERINGINTENT_*`).

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::setimageresolution

(PECL gmagick >= Unknown)

Gmagick::setimageresolution — Define a resolução da imagem

### Descrição

public function Gmagick::setimageresolution(float `$xResolution`, float `$yResolution`): Gmagick

Define a resolução da imagem.

### Parâmetros

`xResolution`
  A resolução x da imagem.
`yResolution`
  A resolução y da imagem.

### Valor Retornado

O objeto Gmagick em caso de sucesso.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::setimagescene

(PECL gmagick >= Unknown)

Gmagick::setimagescene — Define a cena da imagem

### Descrição

public function Gmagick::setimagescene(int `$scene`): Gmagick

Define a cena da imagem.

### Parâmetros

`scene`
  O número da cena da imagem.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::setimagetype

(PECL gmagick >= Unknown)

Gmagick::setimagetype — Define o tipo de imagem

### Descrição

public function Gmagick::setimagetype(int `$imgType`): Gmagick

Define o tipo de imagem.

### Parâmetros

`imgType`
  Uma das constantes tipo de imagem (`Gmagick::IMGTYPE_*`).

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::setimageunits

(PECL gmagick >= Unknown)

Gmagick::setimageunits — Define as unidades de resolução da imagem

### Descrição

public function Gmagick::setimageunits(int `$resolution`): Gmagick

Define as unidades de resolução da imagem.

### Parâmetros

`resolution`
  Uma das constantes de resolução (`Gmagick::RESOLUTION_*`).

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::setimagewhitepoint

(PECL gmagick >= Unknown)

Gmagick::setimagewhitepoint — Define o ponto branco da cromaticidade da imagem

### Descrição

public function Gmagick::setimagewhitepoint(float `$x`, float `$y`): Gmagick

Define o ponto branco da cromaticidade da imagem.

### Parâmetros

`x`
  A coordenada x do ponto branco.
`y`
  A coordenada y do ponto branco.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::setsamplingfactors

(PECL gmagick >= Unknown)

Gmagick::setsamplingfactors — Define os fatores de amostragem da imagem

### Descrição

public function Gmagick::setsamplingfactors(array `$factors`): Gmagick

Define os fatores de amostragem da imagem.

### Parâmetros

`factors`
  Um array de floats representando o fator de amostragem para cada componente de cor (na ordem RGB).

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::setsize

(PECL gmagick >= Unknown)

Gmagick::setsize — Define o tamanho do objeto Gmagick

### Descrição

public function Gmagick::setsize(int `$columns`, int `$rows`): Gmagick

Define o tamanho do objeto Gmagick. Defina-o antes de ler um formato de imagem bruto, como `Gmagick::COLORSPACE_RGB`, `Gmagick::COLORSPACE_GRAY` ou `Gmagick::COLORSPACE_CMYK`.

### Parâmetros

`columns`
  A largura em pixels.
`rows`
  A altura em pixels.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::shearimage

(PECL gmagick >= Unknown)

Gmagick::shearimage — Criando um paralelogramo

### Descrição

public function Gmagick::shearimage(mixed `$color`, float `$xShear`, float `$yShear`): Gmagick

Desliza uma borda de uma imagem ao longo do eixo X ou Y, criando um paralelogramo. Um cisalhamento na direção X desliza uma aresta ao longo do eixo X, enquanto um cisalhamento na direção Y desliza uma aresta ao longo do eixo Y. A quantidade de cisalhamento é controlada por um ângulo de cisalhamento. Para cisalhamentos na direção X, x_shear é medido em relação ao eixo Y e, da mesma forma, para cisalhamentos na direção Y, y_shear é medido em relação ao eixo X. Os triângulos vazios que sobrarem do cisalhamento da imagem são preenchidos com a cor de fundo.

### Parâmetros

`color`
  A varinha de pixel de fundo.
`xShear`
  O número de graus para cisalhar a imagem no eixo X.
`yShear`
  O número de graus para cisalhar a imagem no eixo Y.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::solarizeimage

(PECL gmagick >= Unknown)

Gmagick::solarizeimage — Aplica um efeito de solarização à imagem

### Descrição

public function Gmagick::solarizeimage(int `$threshold`): Gmagick

Aplica um efeito especial à imagem, semelhante ao efeito obtido em uma câmara escura fotográfica, expondo seletivamente áreas de papel fotossensível à luz. O limite varia de 0 a QuantumRange e é uma medida da extensão da solarização.

### Parâmetros

`threshold`
  Define a extensão da solarização.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::spreadimage

(PECL gmagick >= Unknown)

Gmagick::spreadimage — Desloca aleatoriamente cada pixel em um bloco

### Descrição

public function Gmagick::spreadimage(float `$radius`): Gmagick

Método de efeitos especiais que desloca aleatoriamente cada pixel em um bloco definido pelo raio.

### Parâmetros

`radius`
  Escolhe um pixel aleatório em uma vizinhança desta extensão.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::stripimage

(PECL gmagick >= Unknown)

Gmagick::stripimage — Remove todos os comentário e perfir de uma imagem

### Descrição

public function Gmagick::stripimage(): Gmagick

Remove todos os comentário e perfir de uma imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::swirlimage

(PECL gmagick >= Unknown)

Gmagick::swirlimage — Turbilhona os pixels em torno do centro da imagem

### Descrição

public function Gmagick::swirlimage(float `$degrees`): Gmagick

Turbilhona os pixels em torno do centro da imagem, onde os graus indicam a varredura do arco através do qual cada pixel é movido. Um efeito cada vez mais dramático é obtido à medida em que os graus aumentam de 1 a 360.

### Parâmetros

`degrees`
  Defina a intensidade do efeito de turbilhonamento.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::thumbnailimage

(PECL gmagick >= Unknown)

Gmagick::thumbnailimage — Altera o tamanho de uma imagem

### Descrição

public function Gmagick::thumbnailimage(int `$width`, int `$height`, bool `$fit` = `false`): Gmagick

Altera o tamanho de uma imagem para as dimensões fornecidas e remove quaisquer perfis associados. O objetivo é produzir pequenas imagens em miniatura de baixo custo, adequadas para exibição na Web. Se `true` for fornecido como um terceiro parâmetro, os parâmetros de colunas e linhas serão usados ​​como máximos para cada lado. Ambos os lados serão reduzidos até corresponderem ou ficarem menores que o parâmetro fornecido para o lado.

### Parâmetros

`width`
  Largura da imagem.
`height`
  Altura da imagem.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::trimimage

(PECL gmagick >= Unknown)

Gmagick::trimimage — Remover bordas da imagem

### Descrição

public function Gmagick::trimimage(float `$fuzz`): Gmagick

Remova as bordas que são a cor de fundo da imagem.

### Parâmetros

`fuzz`
  Por padrão, o alvo deve corresponder exatamente a uma determinada cor de pixel. No entanto, em muitos casos, duas cores podem diferir um pouco. O membro "fuzz" da imagem define quanta tolerância é aceitável para considerar duas cores iguais. Este parâmetro representa a variação na faixa Quantum.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

# Gmagick::write

(PECL gmagick >= Unknown)

Gmagick::write — Sinônimo de Gmagick::writeimage()

### Descrição

Este método é um apelido para: Gmagick::writeimage().

# Gmagick::writeimage

(PECL gmagick >= Unknown)

Gmagick::writeimage — Grava uma imagem no arquivo especificado

### Descrição

public function Gmagick::writeimage(string `$filename`, bool `$all_frames` = `false`): Gmagick

Grava uma imagem no arquivo especificado. Se o parâmetro de nome de arquivo for `null`, a imagem será gravada no nome de arquivo definido por Gmagick::readimage() ou Gmagick::setimagefilename().

### Parâmetros

`filename`
  O nome do arquivo da imagem.

### Valor Retornado

O objeto Gmagick.

### Erros/Exceções

Lança uma exceção GmagickException em caso de erro.

## Índice

- Gmagick::addimage — Adiciona nova imagem à lista de imagens de objetos Gmagick
- Gmagick::addnoiseimage — Adiciona ruído aleatório à imagem
- Gmagick::annotateimage — Anota uma imagem com texto
- Gmagick::blurimage — Adiciona filtro de desfoque à imagem
- Gmagick::borderimage — Envolve a imagem com uma borda
- Gmagick::charcoalimage — Simula um desenho a carvão
- Gmagick::chopimage — Remove uma região de uma imagem e corta
- Gmagick::clear — Limpa todos os recursos associados ao objeto Gmagick
- Gmagick::commentimage — Adiciona um comentário à sua imagem
- Gmagick::compositeimage — Compõe uma imagem em outra
- Gmagick::__construct — O construtor Gmagick
- Gmagick::cropimage — Extrai uma região da imagem
- Gmagick::cropthumbnailimage — Cria uma miniatura de corte
- Gmagick::current — Retorna referência ao objeto Gmagick atual
- Gmagick::cyclecolormapimage — Desloca o mapa de cores de uma imagem
- Gmagick::deconstructimages — Retorna certas diferenças de pixels entre imagens
- Gmagick::despeckleimage — Reduz manchas em uma imagem
- Gmagick::destroy — Destrói o objeto Gmagick
- Gmagick::drawimage — Renderiza o objeto GmagickDraw na imagem atual
- Gmagick::edgeimage — Melhora as bordas da imagem
- Gmagick::embossimage — Retorna uma imagem em tons de cinza com efeito tridimensional
- Gmagick::enhanceimage — Melhora a qualidade de uma imagem com ruído
- Gmagick::equalizeimage — Equaliza o histograma da imagem
- Gmagick::flipimage — Cria uma imagem espelhada vertical
- Gmagick::flopimage — Cria uma imagem espelhada horizontal
- Gmagick::frameimage — Adiciona uma borda tridimensional simulada
- Gmagick::gammaimage — Corrige o gama da imagem
- Gmagick::getcopyright — Retorna os direitos autorais da API GraphicsMagick como uma string
- Gmagick::getfilename — Obtém o nome do arquivo associado a uma sequência de imagens
- Gmagick::getimagebackgroundcolor — Retorna a cor de fundo da imagem
- Gmagick::getimageblueprimary — Retorna o ponto primário azul da cromaticidade
- Gmagick::getimagebordercolor — Retorna a cor da borda da imagem
- Gmagick::getimagechanneldepth — Obtém a profundidade de um canal de imagem específico
- Gmagick::getimagecolors — Retorna a cor do índice do mapa de cores especificado
- Gmagick::getimagecolorspace — Obtém o espaço de cores da imagem
- Gmagick::getimagecompose — Retorna o operador de composição associado à imagem
- Gmagick::getimagedelay — Obtém o atraso da imagem
- Gmagick::getimagedepth — Obtém a profundidade da imagem
- Gmagick::getimagedispose — Obtém o método de descarte de imagem
- Gmagick::getimageextrema — Obtém os extremos da imagem
- Gmagick::getimagefilename — Retorna o nome do arquivo de uma imagem específica em uma sequência
- Gmagick::getimageformat — Retorna o formato de uma imagem específica em uma sequência
- Gmagick::getimagegamma — Obtém o gama da imagem
- Gmagick::getimagegreenprimary — Retorna o ponto primário verde da cromaticidade
- Gmagick::getimageheight — Retorna a altura da imagem
- Gmagick::getimagehistogram — Obtém o histograma da imagem
- Gmagick::getimageindex — Obtém o índice da imagem ativa atual
- Gmagick::getimageinterlacescheme — Obtém o esquema de entrelaçamento da imagem
- Gmagick::getimageiterations — Obtém as iterações da imagem
- Gmagick::getimagematte — Verifique se a imagem possui um canal fosco
- Gmagick::getimagemattecolor — Retorna a cor fosca da imagem
- Gmagick::getimageprofile — Retorna o perfil de imagem nomeado
- Gmagick::getimageredprimary — Retorna o ponto primário vermelho da cromaticidade
- Gmagick::getimagerenderingintent — Obtém a intenção de renderização da imagem
- Gmagick::getimageresolution — Obtém a resolução X e Y da imagem
- Gmagick::getimagescene — Obtém a cena da imagem
- Gmagick::getimagesignature — Gera um resumo de mensagem SHA-256
- Gmagick::getimagetype — Obtém o tipo de imagem potencial
- Gmagick::getimageunits — Obtém as unidades de resolução da imagem
- Gmagick::getimagewhitepoint — Retorna o ponto branco da cromaticidade
- Gmagick::getimagewidth — Retorna a largura da imagem
- Gmagick::getpackagename — Retorna o nome do pacote GraphicsMagick
- Gmagick::getquantumdepth — Retorna a profundidade de Quantum do Gmagick como uma string
- Gmagick::getreleasedate — Retorna a data de lançamento do GraphicsMagick como uma string
- Gmagick::getsamplingfactors — Obtém o fator de amostragem horizontal e vertical
- Gmagick::getsize — Retorna o tamanho associado ao objeto Gmagick
- Gmagick::getversion — Retorna a versão da API GraphicsMagick
- Gmagick::hasnextimage — Verifica se o objeto possui mais imagens
- Gmagick::haspreviousimage — Verifica se o objeto possui uma imagem anterior
- Gmagick::implodeimage — Cria uma nova imagem implodida
- Gmagick::labelimage — Adiciona um rótulo a uma imagem
- Gmagick::levelimage — Ajusta os níveis de uma imagem
- Gmagick::magnifyimage — Amplia uma imagem para o dobro de seu tamanho
- Gmagick::mapimage — Substitui as cores de uma imagem pela cor mais próxima de uma imagem de referência
- Gmagick::medianfilterimage — Aplica um filtro digital
- Gmagick::minifyimage — Reduz uma imagem à metade de seu tamanho
- Gmagick::modulateimage — Controle brilho, saturação e matiz
- Gmagick::motionblurimage — Simula desfoque de movimento
- Gmagick::newimage — Cria uma nova imagem
- Gmagick::nextimage — Passa para a próxima imagem
- Gmagick::normalizeimage — Melhora o contraste de uma imagem colorida
- Gmagick::oilpaintimage — Simula uma pintura a óleo
- Gmagick::previousimage — Passa para a imagem anterior no objeto
- Gmagick::profileimage — Adiciona ou remove um perfil de uma imagem
- Gmagick::quantizeimage — Analisa as cores dentro de uma imagem de referência
- Gmagick::quantizeimages — Analisa as cores dentro de imagens de referência
- Gmagick::queryfontmetrics — Retorna um array representando as métricas da fonte
- Gmagick::queryfonts — Retorna as fontes configuradas
- Gmagick::queryformats — Retorna formatos suportados pelo Gmagick
- Gmagick::radialblurimage — Desfoca uma imagem de forma radial
- Gmagick::raiseimage — Cria um efeito simulado de botão 3D
- Gmagick::read — Lê imagem a partir de um arquivo
- Gmagick::readimage — Lê imagem a partir de um arquivo
- Gmagick::readimageblob — Lê imagem a partir de uma string binária
- Gmagick::readimagefile — Lê imagem a partir de um descritor de arquivo
- Gmagick::reducenoiseimage — Suaviza os contornos de uma imagem
- Gmagick::removeimage — Remove uma imagem da lista de imagens
- Gmagick::removeimageprofile — Remove o perfil de imagem nomeado e o retorna
- Gmagick::resampleimage — Reamostra imagem para a resolução desejada
- Gmagick::resizeimage — Dimensiona uma imagem
- Gmagick::rollimage — Desloca uma imagem
- Gmagick::rotateimage — Rotaciona uma imagem
- Gmagick::scaleimage — Dimensiona o tamanho de uma imagem
- Gmagick::separateimagechannel — Separa um canal da imagem
- Gmagick::setCompressionQuality — Define a qualidade de compactação padrão do objeto
- Gmagick::setfilename — Define o nome do arquivo antes de ler ou gravar a imagem
- Gmagick::setimagebackgroundcolor — Define a cor de fundo da imagem
- Gmagick::setimageblueprimary — Define o ponto primário azul da cromaticidade da imagem
- Gmagick::setimagebordercolor — Define a cor da borda da imagem
- Gmagick::setimagechanneldepth — Define a profundidade de um canal de imagem específico
- Gmagick::setimagecolorspace — Define o espaço de cores da imagem
- Gmagick::setimagecompose — Define o operador de composição da imagem
- Gmagick::setimagedelay — Define o atraso da imagem
- Gmagick::setimagedepth — Define a profundidade da imagem
- Gmagick::setimagedispose — Define o método de descarte de imagem
- Gmagick::setimagefilename — Define o nome do arquivo de uma imagem específica em uma sequência
- Gmagick::setimageformat — Define o formato de uma imagem específica
- Gmagick::setimagegamma — Define o gama da imagem
- Gmagick::setimagegreenprimary — Define o ponto primário verde da cromaticidade da imagem
- Gmagick::setimageindex — Defina o iterador para a posição na lista de imagens especificada
- Gmagick::setimageinterlacescheme — Define o esquema de entrelaçamento da imagem
- Gmagick::setimageiterations — Define as iterações da imagem
- Gmagick::setimageprofile — Adiciona um perfil nomeado ao objeto Gmagick
- Gmagick::setimageredprimary — Define o ponto primário vermelho da cromaticidade da imagem
- Gmagick::setimagerenderingintent — Define a intenção de renderização da imagem
- Gmagick::setimageresolution — Define a resolução da imagem
- Gmagick::setimagescene — Define a cena da imagem
- Gmagick::setimagetype — Define o tipo de imagem
- Gmagick::setimageunits — Define as unidades de resolução da imagem
- Gmagick::setimagewhitepoint — Define o ponto branco da cromaticidade da imagem
- Gmagick::setsamplingfactors — Define os fatores de amostragem da imagem
- Gmagick::setsize — Define o tamanho do objeto Gmagick
- Gmagick::shearimage — Criando um paralelogramo
- Gmagick::solarizeimage — Aplica um efeito de solarização à imagem
- Gmagick::spreadimage — Desloca aleatoriamente cada pixel em um bloco
- Gmagick::stripimage — Remove todos os comentário e perfir de uma imagem
- Gmagick::swirlimage — Turbilhona os pixels em torno do centro da imagem
- Gmagick::thumbnailimage — Altera o tamanho de uma imagem
- Gmagick::trimimage — Remover bordas da imagem
- Gmagick::write — Sinônimo de Gmagick::writeimage
- Gmagick::writeimage — Grava uma imagem no arquivo especificado

# A classe GmagickDraw

(PECL gmagick >= Unknown)

## Introdução

## Resumo da classe

class GmagickDraw {
/* Métodos */
public function annotate(float `$x`, float `$y`, string `$text`): GmagickDraw
public function arc(
float `$sx`,
float `$sy`,
float `$ex`,
float `$ey`,
float `$sd`,
float `$ed`
): GmagickDraw
public function bezier(array `$coordinate_array`): GmagickDraw
public function ellipse(
float `$ox`,
float `$oy`,
float `$rx`,
float `$ry`,
float `$start`,
float `$end`
): GmagickDraw
public function getfillcolor(): GmagickPixel
public function getfillopacity(): float
public function getfont(): mixed
public function getfontsize(): float
public function getfontstyle(): int
public function getfontweight(): int
public function getstrokecolor(): GmagickPixel
public function getstrokeopacity(): float
public function getstrokewidth(): float
public function gettextdecoration(): int
public function gettextencoding(): mixed
public function line(
float `$sx`,
float `$sy`,
float `$ex`,
float `$ey`
): GmagickDraw
public function point(float `$x`, float `$y`): GmagickDraw
public function polygon(array `$coordinates`): GmagickDraw
public function polyline(array `$coordinate_array`): GmagickDraw
public function rectangle(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`
): GmagickDraw
public function rotate(float `$degrees`): GmagickDraw
public function roundrectangle(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$rx`,
float `$ry`
): GmagickDraw
public function scale(float `$x`, float `$y`): GmagickDraw
public function setfillcolor(mixed `$color`): GmagickDraw
public function setfillopacity(float `$fill_opacity`): GmagickDraw
public function setfont(string `$font`): GmagickDraw
public function setfontsize(float `$pointsize`): GmagickDraw
public function setfontstyle(int `$style`): GmagickDraw
public function setfontweight(int `$weight`): GmagickDraw
public function setstrokecolor(mixed `$color`): GmagickDraw
public function setstrokeopacity(float `$stroke_opacity`): GmagickDraw
public function setstrokewidth(float `$width`): GmagickDraw
public function settextdecoration(int `$decoration`): GmagickDraw
public function settextencoding(string `$encoding`): GmagickDraw
}

# GmagickDraw::annotate

(PECL gmagick >= Unknown)

GmagickDraw::annotate — Desenha texto na imagem

### Descrição

public function GmagickDraw::annotate(float `$x`, float `$y`, string `$text`): GmagickDraw

Desenha texto na imagem.

### Parâmetros

`x`
  Coordenada x à esquerda do texto
`y`
  Coordenada y da linha de base do texto
`text`
  Texto a ser desenhado

### Valor Retornado

O objeto GmagickDraw.

# GmagickDraw::arc

(PECL gmagick >= Unknown)

GmagickDraw::arc — Desenha um arco

### Descrição

public function GmagickDraw::arc(
float `$sx`,
float `$sy`,
float `$ex`,
float `$ey`,
float `$sd`,
float `$ed`
): GmagickDraw

Desenha um arco dentro de um retângulo delimitador especificado na imagem.

### Parâmetros

`sx`
  Coordenada x inicial do retângulo delimitador.
`sy`
  Coordenada y inicial do retângulo delimitador.
`ex`
  Coordenada x final do retângulo delimitador.
`ey`
  Coordenada y final do retângulo delimitador.
`sd`
  Ângulo inicial do arco.
`ed`
  Ângulo final do arco.

### Valor Retornado

O objeto GmagickDraw.

# GmagickDraw::bezier

(PECL gmagick >= Unknown)

GmagickDraw::bezier — Desenha uma curva de Bézier

### Descrição

public function GmagickDraw::bezier(array `$coordinate_array`): GmagickDraw

Desenha uma curva de Bézier através de um conjunto de pontos na imagem.

### Parâmetros

`coordinate_array`
  Array de coordenadas.

### Valor Retornado

O objeto GmagickDraw.

# GmagickDraw::ellipse

(PECL gmagick >= Unknown)

GmagickDraw::ellipse — Desenha uma elipse na imagem

### Descrição

public function GmagickDraw::ellipse(
float `$ox`,
float `$oy`,
float `$rx`,
float `$ry`,
float `$start`,
float `$end`
): GmagickDraw

Desenha uma elipse na imagem.

### Parâmetros

`ox`
  Coordenada x da origem.
`oy`
  Coordenada y da origem.
`rx`
  Raio no eixo x.
`ry`
  Raio no eixo y.
`start`
  Ângulo inicial em graus.
`end`
  Ângulo final em graus.

### Valor Retornado

O objeto GmagickDraw.

# GmagickDraw::getfillcolor

(PECL gmagick >= Unknown)

GmagickDraw::getfillcolor — Retorna a cor de preenchimento

### Descrição

public function GmagickDraw::getfillcolor(): GmagickPixel

Retorna a cor de preenchimento usada para desenhar objetos preenchidos.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

A cor de preenchimento GmagickPixel usada para desenhar objetos preenchidos.

# GmagickDraw::getfillopacity

(PECL gmagick >= Unknown)

GmagickDraw::getfillopacity — Retorna a opacidade usada ao desenhar

### Descrição

public function GmagickDraw::getfillopacity(): float

Retorna a opacidade usada ao desenhar

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a opacidade usada ao desenhar usando a cor ou textura de preenchimento. Totalmente opaco é 1.0.

# GmagickDraw::getfont

(PECL gmagick >= Unknown)

GmagickDraw::getfont — Retorna a fonte

### Descrição

public function GmagickDraw::getfont(): mixed

Retorna uma string especificando a fonte usada ao fazer anotações com texto.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string em caso de sucesso ou `false` se nenhuma fonte estiver definida.

# GmagickDraw::getfontsize

(PECL gmagick >= Unknown)

GmagickDraw::getfontsize — Retorna o tamanho da fonte em pontos

### Descrição

public function GmagickDraw::getfontsize(): float

Retorna o tamanho da fonte, em pontos, usado ao fazer anotações com texto.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o tamanho da fonte associado ao objeto GmagickDraw atual.

# GmagickDraw::getfontstyle

(PECL gmagick >= Unknown)

GmagickDraw::getfontstyle — Retorna o estilo da fonte

### Descrição

public function GmagickDraw::getfontstyle(): int

Retorna o estilo de fonte usado ao fazer anotações com texto.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a constante (STYLE_) de estilo da fonte associada ao objeto GmagickDraw ou `0` se nenhum estilo estiver definido.

# GmagickDraw::getfontweight

(PECL gmagick >= Unknown)

GmagickDraw::getfontweight — Retorna o peso da fonte

### Descrição

public function GmagickDraw::getfontweight(): int

Retorna a espessura da fonte usada ao fazer anotações com texto.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um inteiro em caso de sucesso ou 0 se nenhum peso for definido.

# GmagickDraw::getstrokecolor

(PECL gmagick >= Unknown)

GmagickDraw::getstrokecolor — Retorna a cor usada para traçar os contornos dos objetos

### Descrição

public function GmagickDraw::getstrokecolor(): GmagickPixel

Retorna a cor usada para traçar os contornos dos objetos.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um objeto GmagickPixel que descreve a cor.

# GmagickDraw::getstrokeopacity

(PECL gmagick >= Unknown)

GmagickDraw::getstrokeopacity — Retorna a opacidade dos contornos dos objetos traçados

### Descrição

public function GmagickDraw::getstrokeopacity(): float

Retorna a opacidade dos contornos dos objetos traçados.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um float descrevendo a opacidade.

# GmagickDraw::getstrokewidth

(PECL gmagick >= Unknown)

GmagickDraw::getstrokewidth — Retorna a largura do traço usado para desenhar contornos de objetos

### Descrição

public function GmagickDraw::getstrokewidth(): float

Retorna a largura do traço usado para desenhar contornos de objetos.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um float que descreve a largura do traço.

# GmagickDraw::gettextdecoration

(PECL gmagick >= Unknown)

GmagickDraw::gettextdecoration — Retorna a decoração do texto

### Descrição

public function GmagickDraw::gettextdecoration(): int

Retorna a decoração aplicada ao anotar com texto.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma das constantes DECORATION_ ou 0 se nenhuma decoração estiver definida.

# GmagickDraw::gettextencoding

(PECL gmagick >= Unknown)

GmagickDraw::gettextencoding — Retorna o conjunto de caracteres usado para anotações de texto

### Descrição

public function GmagickDraw::gettextencoding(): mixed

Retorna uma string que especifica o conjunto de caracteres usado para anotações de texto.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string especificando o conjunto de caracteres ou `false` se a codificação do texto não estiver definida.

# GmagickDraw::line

(PECL gmagick >= Unknown)

GmagickDraw::line — Desenha uma linha

### Descrição

public function GmagickDraw::line(
float `$sx`,
float `$sy`,
float `$ex`,
float `$ey`
): GmagickDraw

Desenha uma linha na imagem usando a cor, a opacidade e a largura do traço atuais.

### Parâmetros

`sx`
  Coordenada x do ponto inicial.
`sy`
  Coordenada y do ponto inicial.
`ex`
  Coordenada x do ponto final.
`ey`
  Coordenada y do ponto final.

### Valor Retornado

O objeto GmagickDraw.

# GmagickDraw::point

(PECL gmagick >= Unknown)

GmagickDraw::point — Desenha um ponto

### Descrição

public function GmagickDraw::point(float `$x`, float `$y`): GmagickDraw

Desenha um ponto usando a cor e a espessura do traço atuais nas coordenadas especificadas.

### Parâmetros

`x`
  Coordenada x do ponto.
`y`
  Coordenada y do ponto.

### Valor Retornado

O objeto GmagickDraw.

# GmagickDraw::polygon

(PECL gmagick >= Unknown)

GmagickDraw::polygon — Desenha um polígono

### Descrição

public function GmagickDraw::polygon(array `$coordinates`): GmagickDraw

Desenha um polígono usando o traço, a largura do traço e a cor ou textura de preenchimento atuais, usando o array de coordenadas especificado.

### Parâmetros

`coordinates`
  Array de coordenadas.

### Valor Retornado

O objeto GmagickDraw.

# GmagickDraw::polyline

(PECL gmagick >= Unknown)

GmagickDraw::polyline — Desenha uma polilinha

### Descrição

public function GmagickDraw::polyline(array `$coordinate_array`): GmagickDraw

Desenha uma polilinha usando o traço, a largura do traço e a cor ou textura de preenchimento atuais, usando o array de coordenadas especificado.

### Parâmetros

`coordinate_array`
  O array de coordenadas.

### Valor Retornado

O objeto GmagickDraw.

# GmagickDraw::rectangle

(PECL gmagick >= Unknown)

GmagickDraw::rectangle — Desenha um retângulo

### Descrição

public function GmagickDraw::rectangle(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`
): GmagickDraw

Desenha um retângulo com duas coordenadas e usando as configurações atuais de traçado, largura do traçado e preenchimento.

### Parâmetros

`x1`
  Coordenada x do primeiro ponto.
`y1`
  Coordenada y do primeiro ponto.
`x2`
  Coordenada x do segundo ponto.
`y2`
  Coordenada y do segundo ponto.

### Valor Retornado

O objeto GmagickDraw.

# GmagickDraw::rotate

(PECL gmagick >= Unknown)

GmagickDraw::rotate — Aplica a rotação especificada ao espaço de coordenadas atual

### Descrição

public function GmagickDraw::rotate(float `$degrees`): GmagickDraw

Aplica a rotação especificada ao espaço de coordenadas atual.

### Parâmetros

`degrees`
  Graus de rotação.

### Valor Retornado

O objeto GmagickDraw.

# GmagickDraw::roundrectangle

(PECL gmagick >= Unknown)

GmagickDraw::roundrectangle — Desenha um retângulo arredondado

### Descrição

public function GmagickDraw::roundrectangle(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$rx`,
float `$ry`
): GmagickDraw

Desenha um retângulo arredondado com duas coordenadas e raios de canto, usando as configurações atuais de traço, largura de traço e preenchimento.

### Parâmetros

`x1`
  Coordenada x do primeiro ponto.
`y1`
  Coordenada y do primeiro ponto.
`x2`
  Coordenada x do segundo ponto.
`y2`
  Coordenada y do segundo ponto.
`rx`
  Raio do canto na direção horizontal.
`ry`
  Raio do canto na direção vertical.

### Valor Retornado

O objeto GmagickDraw.

# GmagickDraw::scale

(PECL gmagick >= Unknown)

GmagickDraw::scale — Ajusta o fator de escala

### Descrição

public function GmagickDraw::scale(float `$x`, float `$y`): GmagickDraw

Ajusta o fator de escala para aplicar nas direções horizontal e vertical ao espaço de coordenadas atual.

### Parâmetros

`x`
  Fator de escala horizontal.
`y`
  Fator de escala vertical.

### Valor Retornado

O objeto GmagickDraw.

# GmagickDraw::setfillcolor

(PECL gmagick >= Unknown)

GmagickDraw::setfillcolor — Define a cor de preenchimento a ser usada para desenhar objetos preenchidos

### Descrição

public function GmagickDraw::setfillcolor(mixed `$color`): GmagickDraw

Define a cor de preenchimento a ser usada para desenhar objetos preenchidos

### Parâmetros

`color`
  GmagickPixel ou string indicando a cor a ser usada para preenchimento.

### Valor Retornado

O objeto GmagickDraw em caso de sucesso.

# GmagickDraw::setfillopacity

(PECL gmagick >= Unknown)

GmagickDraw::setfillopacity — Define a opacidade de preenchimento

### Descrição

public function GmagickDraw::setfillopacity(float `$fill_opacity`): GmagickDraw

Define a opacidade a ser usada ao desenhar usando a cor ou textura de preenchimento. Definir como 1.0 tornará o preenchimento totalmente opaco.

### Parâmetros

`fill_opacity`
  Opacidade de preenchimento.

### Valor Retornado

O objeto GmagickDraw.

# GmagickDraw::setfont

(PECL gmagick >= Unknown)

GmagickDraw::setfont — Define a fonte totalmente especificada a ser usada ao fazer anotações com texto

### Descrição

public function GmagickDraw::setfont(string `$font`): GmagickDraw

Define a fonte totalmente especificada a ser usada ao fazer anotações com texto.

### Parâmetros

`font`
  Nome da fonte.

### Valor Retornado

O objeto GmagickDraw.

# GmagickDraw::setfontsize

(PECL gmagick >= Unknown)

GmagickDraw::setfontsize — Define o tamanho da fonte a ser usado ao fazer anotações com texto

### Descrição

public function GmagickDraw::setfontsize(float `$pointsize`): GmagickDraw

Define o tamanho da fonte a ser usado ao fazer anotações com texto.

### Parâmetros

`pointsize`
  O tamanho da fonte em pontos.

### Valor Retornado

O objeto GmagickDraw.

# GmagickDraw::setfontstyle

(PECL gmagick >= Unknown)

GmagickDraw::setfontstyle — Define o estilo da fonte a ser usado ao fazer anotações com texto

### Descrição

public function GmagickDraw::setfontstyle(int `$style`): GmagickDraw

Define o estilo da fonte a ser usado ao fazer anotações com texto. A enumeração AnyStyle atua como uma opção curinga "tanto faz".

### Parâmetros

`style`
  Estilo da fonte (NormalStyle, ItalicStyle, ObliqueStyle, AnyStyle)

### Valor Retornado

O objeto GmagickDraw.

# GmagickDraw::setfontweight

(PECL gmagick >= Unknown)

GmagickDraw::setfontweight — Define o peso da fonte

### Descrição

public function GmagickDraw::setfontweight(int `$weight`): GmagickDraw

Define a espessura da fonte a ser usada ao fazer anotações com texto.

### Parâmetros

`weight`
  Peso da fonte (intervalo válido 100-900)

### Valor Retornado

O objeto GmagickDraw.

# GmagickDraw::setstrokecolor

(PECL gmagick >= Unknown)

GmagickDraw::setstrokecolor — Define a cor usada para traçar os contornos dos objetos

### Descrição

public function GmagickDraw::setstrokecolor(mixed `$color`): GmagickDraw

Define a cor usada para traçar os contornos dos objetos

### Parâmetros

`color`
  GmagickPixel ou string representando a cor do traço.

### Valor Retornado

O objeto GmagickDraw em caso de sucesso.

# GmagickDraw::setstrokeopacity

(PECL gmagick >= Unknown)

GmagickDraw::setstrokeopacity — Especifica a opacidade dos contornos dos objetos traçados

### Descrição

public function GmagickDraw::setstrokeopacity(float `$stroke_opacity`): GmagickDraw

Especifica a opacidade dos contornos dos objetos traçados.

### Parâmetros

`stroke_opacity`
  Opacidade do traço. O valor 1.0 é totalmente opaco.

### Valor Retornado

O objeto GmagickDraw.

# GmagickDraw::setstrokewidth

(PECL gmagick >= Unknown)

GmagickDraw::setstrokewidth — Define a largura do traço usado para desenhar contornos de objetos

### Descrição

public function GmagickDraw::setstrokewidth(float `$width`): GmagickDraw

Define a largura do traço usado para desenhar contornos de objetos.

### Parâmetros

`width`
  Largura do traço

### Valor Retornado

O objeto GmagickDraw.

# GmagickDraw::settextdecoration

(PECL gmagick >= Unknown)

GmagickDraw::settextdecoration — Especifica uma decoração

### Descrição

public function GmagickDraw::settextdecoration(int `$decoration`): GmagickDraw

Especifica uma decoração a ser aplicada ao fazer anotações com texto.

### Parâmetros

`int`
  Decoração de texto. Uma das constantes NoDecoration, UnderlineDecoration, OverlineDecoration ou LineThroughDecoration.

### Valor Retornado

O objeto GmagickDraw.

# GmagickDraw::settextencoding

(PECL gmagick >= Unknown)

GmagickDraw::settextencoding — Especifica a codificação de caracteres de texto

### Descrição

public function GmagickDraw::settextencoding(string `$encoding`): GmagickDraw

Especifica a codificação de caracteres a ser usada para anotações de texto. A única codificação de caracteres que pode ser especificada neste momento é "UTF-8" para representar Unicode como uma sequência de bytes. Ao especificar uma sequência vazia, será definida a codificação de texto padrão do sistema. A anotação de texto bem-sucedida usando Unicode pode exigir fontes projetadas para suportar Unicode.

### Parâmetros

`encoding`
  String de caracteres especificando a codificação de texto.

### Valor Retornado

O objeto GmagickDraw.

## Índice

- GmagickDraw::annotate — Desenha texto na imagem
- GmagickDraw::arc — Desenha um arco
- GmagickDraw::bezier — Desenha uma curva de Bézier
- GmagickDraw::ellipse — Desenha uma elipse na imagem
- GmagickDraw::getfillcolor — Retorna a cor de preenchimento
- GmagickDraw::getfillopacity — Retorna a opacidade usada ao desenhar
- GmagickDraw::getfont — Retorna a fonte
- GmagickDraw::getfontsize — Retorna o tamanho da fonte em pontos
- GmagickDraw::getfontstyle — Retorna o estilo da fonte
- GmagickDraw::getfontweight — Retorna o peso da fonte
- GmagickDraw::getstrokecolor — Retorna a cor usada para traçar os contornos dos objetos
- GmagickDraw::getstrokeopacity — Retorna a opacidade dos contornos dos objetos traçados
- GmagickDraw::getstrokewidth — Retorna a largura do traço usado para desenhar contornos de objetos
- GmagickDraw::gettextdecoration — Retorna a decoração do texto
- GmagickDraw::gettextencoding — Retorna o conjunto de caracteres usado para anotações de texto
- GmagickDraw::line — Desenha uma linha
- GmagickDraw::point — Desenha um ponto
- GmagickDraw::polygon — Desenha um polígono
- GmagickDraw::polyline — Desenha uma polilinha
- GmagickDraw::rectangle — Desenha um retângulo
- GmagickDraw::rotate — Aplica a rotação especificada ao espaço de coordenadas atual
- GmagickDraw::roundrectangle — Desenha um retângulo arredondado
- GmagickDraw::scale — Ajusta o fator de escala
- GmagickDraw::setfillcolor — Define a cor de preenchimento a ser usada para desenhar objetos preenchidos
- GmagickDraw::setfillopacity — Define a opacidade de preenchimento
- GmagickDraw::setfont — Define a fonte totalmente especificada a ser usada ao fazer anotações com texto
- GmagickDraw::setfontsize — Define o tamanho da fonte a ser usado ao fazer anotações com texto
- GmagickDraw::setfontstyle — Define o estilo da fonte a ser usado ao fazer anotações com texto
- GmagickDraw::setfontweight — Define o peso da fonte
- GmagickDraw::setstrokecolor — Define a cor usada para traçar os contornos dos objetos
- GmagickDraw::setstrokeopacity — Especifica a opacidade dos contornos dos objetos traçados
- GmagickDraw::setstrokewidth — Define a largura do traço usado para desenhar contornos de objetos
- GmagickDraw::settextdecoration — Especifica uma decoração
- GmagickDraw::settextencoding — Especifica a codificação de caracteres de texto

# A classe GmagickPixel

(PECL gmagick >= Unknown)

## Introdução

## Resumo da classe

class GmagickPixel {
/* Métodos */
public function __construct(string `$color` = ?)
public function getcolor(bool `$as_array` = `false`, bool `$normalize_array` = `false`): mixed
public function getcolorcount(): int
public function getcolorvalue(int `$color`): float
public function setcolor(string `$color`): GmagickPixel
public function setcolorvalue(int `$color`, float `$value`): GmagickPixel
}

# GmagickPixel::__construct

(PECL gmagick >= Unknown)

GmagickPixel::__construct — O construtor GmagickPixel

### Descrição

public function GmagickPixel::__construct(string `$color` = ?)

Constrói um objeto GmagickPixel. Se uma cor for especificada, o objeto será construído e inicializado com essa cor antes de ser retornado.

### Parâmetros

`color`
  A string de cores opcional a ser usada como valor inicial deste objeto.

# GmagickPixel::getcolor

(PECL gmagick >= Unknown)

GmagickPixel::getcolor — Retorna a cor

### Descrição

public function GmagickPixel::getcolor(bool `$as_array` = `false`, bool `$normalize_array` = `false`): mixed

Retorna a cor descrita pelo objeto GmagickPixel, como uma string ou um array. Se a cor tiver um canal de opacidade definido, ele será fornecido como o quarto valor da lista.

### Parâmetros

`as_array`
  `true` para indicar o retorno de array em vez de string.
`normalize_array`
  `true` para normalizar os valores de cores.

### Valor Retornado

Uma string ou um array de valores de canal, cada um normalizado se `true` for informado no parâmetro `normalize_array`. Lança uma GmagickPixelException em caso de erro.

# GmagickPixel::getcolorcount

(PECL gmagick >= Unknown)

GmagickPixel::getcolorcount — Retorna a contagem de cores associada a esta cor

### Descrição

public function GmagickPixel::getcolorcount(): int

Retorna a contagem de cores associada a esta cor.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a contagem de cores como um número inteiro em caso de sucesso, lança uma GmagickPixelException em caso de falha.

# GmagickPixel::getcolorvalue

(PECL gmagick >= Unknown)

GmagickPixel::getcolorvalue — Obtém o valor normalizado do canal de cores fornecido

### Descrição

public function GmagickPixel::getcolorvalue(int `$color`): float

Recupera o valor do canal de cores especificado, como um número em ponto flutuante entre 0 e 1.

### Parâmetros

`color`
  O canal a ser verificado, especificado como uma das constantes de canal Gmagick.

### Valor Retornado

O valor do canal, como um número em ponto flutuante normalizado, lança uma GmagickPixelException em caso de erro.

# GmagickPixel::setcolor

(PECL gmagick >= Unknown)

GmagickPixel::setcolor — Define a cor

### Descrição

public function GmagickPixel::setcolor(string `$color`): GmagickPixel

Define a cor descrita pelo objeto GmagickPixel, com uma string (por exemplo, "blue", "#0000ff", "rgb(0,0,255)", "cmyk(100,100,100,10)" etc.).

### Parâmetros

`color`
  A definição de cor a ser usada para inicializar o objeto GmagickPixel.

### Valor Retornado

O objeto GmagickPixel.

# GmagickPixel::setcolorvalue

(PECL gmagick >= Unknown)

GmagickPixel::setcolorvalue — Define o valor normalizado de um dos canais

### Descrição

public function GmagickPixel::setcolorvalue(int `$color`, float `$value`): GmagickPixel

Define o valor do canal especificado deste objeto para o valor fornecido, que deve estar entre 0 e 1. Esta função pode ser usada para fornecer um canal de opacidade para um objeto GmagickPixel.

### Parâmetros

`color`
  Uma das constantes de cor de canal Gmagick.
`value`
  O valor a ser definido para este canal, variando de 0 a 1.

### Valor Retornado

O objeto GmagickPixel.

## Índice

- GmagickPixel::__construct — O construtor GmagickPixel
- GmagickPixel::getcolor — Retorna a cor
- GmagickPixel::getcolorcount — Retorna a contagem de cores associada a esta cor
- GmagickPixel::getcolorvalue — Obtém o valor normalizado do canal de cores fornecido
- GmagickPixel::setcolor — Define a cor
- GmagickPixel::setcolorvalue — Define o valor normalizado de um dos canais

- Instalação/Configuração
  - Dependências
  - Instalação
- Constantes predefinidas
- Exemplos
- Gmagick — A classe Gmagick
  - Gmagick::addimage — Adiciona nova imagem à lista de imagens de objetos Gmagick
  - Gmagick::addnoiseimage — Adiciona ruído aleatório à imagem
  - Gmagick::annotateimage — Anota uma imagem com texto
  - Gmagick::blurimage — Adiciona filtro de desfoque à imagem
  - Gmagick::borderimage — Envolve a imagem com uma borda
  - Gmagick::charcoalimage — Simula um desenho a carvão
  - Gmagick::chopimage — Remove uma região de uma imagem e corta
  - Gmagick::clear — Limpa todos os recursos associados ao objeto Gmagick
  - Gmagick::commentimage — Adiciona um comentário à sua imagem
  - Gmagick::compositeimage — Compõe uma imagem em outra
  - Gmagick::__construct — O construtor Gmagick
  - Gmagick::cropimage — Extrai uma região da imagem
  - Gmagick::cropthumbnailimage — Cria uma miniatura de corte
  - Gmagick::current — Retorna referência ao objeto Gmagick atual
  - Gmagick::cyclecolormapimage — Desloca o mapa de cores de uma imagem
  - Gmagick::deconstructimages — Retorna certas diferenças de pixels entre imagens
  - Gmagick::despeckleimage — Reduz manchas em uma imagem
  - Gmagick::destroy — Destrói o objeto Gmagick
  - Gmagick::drawimage — Renderiza o objeto GmagickDraw na imagem atual
  - Gmagick::edgeimage — Melhora as bordas da imagem
  - Gmagick::embossimage — Retorna uma imagem em tons de cinza com efeito tridimensional
  - Gmagick::enhanceimage — Melhora a qualidade de uma imagem com ruído
  - Gmagick::equalizeimage — Equaliza o histograma da imagem
  - Gmagick::flipimage — Cria uma imagem espelhada vertical
  - Gmagick::flopimage — Cria uma imagem espelhada horizontal
  - Gmagick::frameimage — Adiciona uma borda tridimensional simulada
  - Gmagick::gammaimage — Corrige o gama da imagem
  - Gmagick::getcopyright — Retorna os direitos autorais da API GraphicsMagick como uma string
  - Gmagick::getfilename — Obtém o nome do arquivo associado a uma sequência de imagens
  - Gmagick::getimagebackgroundcolor — Retorna a cor de fundo da imagem
  - Gmagick::getimageblueprimary — Retorna o ponto primário azul da cromaticidade
  - Gmagick::getimagebordercolor — Retorna a cor da borda da imagem
  - Gmagick::getimagechanneldepth — Obtém a profundidade de um canal de imagem específico
  - Gmagick::getimagecolors — Retorna a cor do índice do mapa de cores especificado
  - Gmagick::getimagecolorspace — Obtém o espaço de cores da imagem
  - Gmagick::getimagecompose — Retorna o operador de composição associado à imagem
  - Gmagick::getimagedelay — Obtém o atraso da imagem
  - Gmagick::getimagedepth — Obtém a profundidade da imagem
  - Gmagick::getimagedispose — Obtém o método de descarte de imagem
  - Gmagick::getimageextrema — Obtém os extremos da imagem
  - Gmagick::getimagefilename — Retorna o nome do arquivo de uma imagem específica em uma sequência
  - Gmagick::getimageformat — Retorna o formato de uma imagem específica em uma sequência
  - Gmagick::getimagegamma — Obtém o gama da imagem
  - Gmagick::getimagegreenprimary — Retorna o ponto primário verde da cromaticidade
  - Gmagick::getimageheight — Retorna a altura da imagem
  - Gmagick::getimagehistogram — Obtém o histograma da imagem
  - Gmagick::getimageindex — Obtém o índice da imagem ativa atual
  - Gmagick::getimageinterlacescheme — Obtém o esquema de entrelaçamento da imagem
  - Gmagick::getimageiterations — Obtém as iterações da imagem
  - Gmagick::getimagematte — Verifique se a imagem possui um canal fosco
  - Gmagick::getimagemattecolor — Retorna a cor fosca da imagem
  - Gmagick::getimageprofile — Retorna o perfil de imagem nomeado
  - Gmagick::getimageredprimary — Retorna o ponto primário vermelho da cromaticidade
  - Gmagick::getimagerenderingintent — Obtém a intenção de renderização da imagem
  - Gmagick::getimageresolution — Obtém a resolução X e Y da imagem
  - Gmagick::getimagescene — Obtém a cena da imagem
  - Gmagick::getimagesignature — Gera um resumo de mensagem SHA-256
  - Gmagick::getimagetype — Obtém o tipo de imagem potencial
  - Gmagick::getimageunits — Obtém as unidades de resolução da imagem
  - Gmagick::getimagewhitepoint — Retorna o ponto branco da cromaticidade
  - Gmagick::getimagewidth — Retorna a largura da imagem
  - Gmagick::getpackagename — Retorna o nome do pacote GraphicsMagick
  - Gmagick::getquantumdepth — Retorna a profundidade de Quantum do Gmagick como uma string
  - Gmagick::getreleasedate — Retorna a data de lançamento do GraphicsMagick como uma string
  - Gmagick::getsamplingfactors — Obtém o fator de amostragem horizontal e vertical
  - Gmagick::getsize — Retorna o tamanho associado ao objeto Gmagick
  - Gmagick::getversion — Retorna a versão da API GraphicsMagick
  - Gmagick::hasnextimage — Verifica se o objeto possui mais imagens
  - Gmagick::haspreviousimage — Verifica se o objeto possui uma imagem anterior
  - Gmagick::implodeimage — Cria uma nova imagem implodida
  - Gmagick::labelimage — Adiciona um rótulo a uma imagem
  - Gmagick::levelimage — Ajusta os níveis de uma imagem
  - Gmagick::magnifyimage — Amplia uma imagem para o dobro de seu tamanho
  - Gmagick::mapimage — Substitui as cores de uma imagem pela cor mais próxima de uma imagem de referência
  - Gmagick::medianfilterimage — Aplica um filtro digital
  - Gmagick::minifyimage — Reduz uma imagem à metade de seu tamanho
  - Gmagick::modulateimage — Controle brilho, saturação e matiz
  - Gmagick::motionblurimage — Simula desfoque de movimento
  - Gmagick::newimage — Cria uma nova imagem
  - Gmagick::nextimage — Passa para a próxima imagem
  - Gmagick::normalizeimage — Melhora o contraste de uma imagem colorida
  - Gmagick::oilpaintimage — Simula uma pintura a óleo
  - Gmagick::previousimage — Passa para a imagem anterior no objeto
  - Gmagick::profileimage — Adiciona ou remove um perfil de uma imagem
  - Gmagick::quantizeimage — Analisa as cores dentro de uma imagem de referência
  - Gmagick::quantizeimages — Analisa as cores dentro de imagens de referência
  - Gmagick::queryfontmetrics — Retorna um array representando as métricas da fonte
  - Gmagick::queryfonts — Retorna as fontes configuradas
  - Gmagick::queryformats — Retorna formatos suportados pelo Gmagick
  - Gmagick::radialblurimage — Desfoca uma imagem de forma radial
  - Gmagick::raiseimage — Cria um efeito simulado de botão 3D
  - Gmagick::read — Lê imagem a partir de um arquivo
  - Gmagick::readimage — Lê imagem a partir de um arquivo
  - Gmagick::readimageblob — Lê imagem a partir de uma string binária
  - Gmagick::readimagefile — Lê imagem a partir de um descritor de arquivo
  - Gmagick::reducenoiseimage — Suaviza os contornos de uma imagem
  - Gmagick::removeimage — Remove uma imagem da lista de imagens
  - Gmagick::removeimageprofile — Remove o perfil de imagem nomeado e o retorna
  - Gmagick::resampleimage — Reamostra imagem para a resolução desejada
  - Gmagick::resizeimage — Dimensiona uma imagem
  - Gmagick::rollimage — Desloca uma imagem
  - Gmagick::rotateimage — Rotaciona uma imagem
  - Gmagick::scaleimage — Dimensiona o tamanho de uma imagem
  - Gmagick::separateimagechannel — Separa um canal da imagem
  - Gmagick::setCompressionQuality — Define a qualidade de compactação padrão do objeto
  - Gmagick::setfilename — Define o nome do arquivo antes de ler ou gravar a imagem
  - Gmagick::setimagebackgroundcolor — Define a cor de fundo da imagem
  - Gmagick::setimageblueprimary — Define o ponto primário azul da cromaticidade da imagem
  - Gmagick::setimagebordercolor — Define a cor da borda da imagem
  - Gmagick::setimagechanneldepth — Define a profundidade de um canal de imagem específico
  - Gmagick::setimagecolorspace — Define o espaço de cores da imagem
  - Gmagick::setimagecompose — Define o operador de composição da imagem
  - Gmagick::setimagedelay — Define o atraso da imagem
  - Gmagick::setimagedepth — Define a profundidade da imagem
  - Gmagick::setimagedispose — Define o método de descarte de imagem
  - Gmagick::setimagefilename — Define o nome do arquivo de uma imagem específica em uma sequência
  - Gmagick::setimageformat — Define o formato de uma imagem específica
  - Gmagick::setimagegamma — Define o gama da imagem
  - Gmagick::setimagegreenprimary — Define o ponto primário verde da cromaticidade da imagem
  - Gmagick::setimageindex — Defina o iterador para a posição na lista de imagens especificada
  - Gmagick::setimageinterlacescheme — Define o esquema de entrelaçamento da imagem
  - Gmagick::setimageiterations — Define as iterações da imagem
  - Gmagick::setimageprofile — Adiciona um perfil nomeado ao objeto Gmagick
  - Gmagick::setimageredprimary — Define o ponto primário vermelho da cromaticidade da imagem
  - Gmagick::setimagerenderingintent — Define a intenção de renderização da imagem
  - Gmagick::setimageresolution — Define a resolução da imagem
  - Gmagick::setimagescene — Define a cena da imagem
  - Gmagick::setimagetype — Define o tipo de imagem
  - Gmagick::setimageunits — Define as unidades de resolução da imagem
  - Gmagick::setimagewhitepoint — Define o ponto branco da cromaticidade da imagem
  - Gmagick::setsamplingfactors — Define os fatores de amostragem da imagem
  - Gmagick::setsize — Define o tamanho do objeto Gmagick
  - Gmagick::shearimage — Criando um paralelogramo
  - Gmagick::solarizeimage — Aplica um efeito de solarização à imagem
  - Gmagick::spreadimage — Desloca aleatoriamente cada pixel em um bloco
  - Gmagick::stripimage — Remove todos os comentário e perfir de uma imagem
  - Gmagick::swirlimage — Turbilhona os pixels em torno do centro da imagem
  - Gmagick::thumbnailimage — Altera o tamanho de uma imagem
  - Gmagick::trimimage — Remover bordas da imagem
  - Gmagick::write — Sinônimo de Gmagick::writeimage
  - Gmagick::writeimage — Grava uma imagem no arquivo especificado
- GmagickDraw — A classe GmagickDraw
  - GmagickDraw::annotate — Desenha texto na imagem
  - GmagickDraw::arc — Desenha um arco
  - GmagickDraw::bezier — Desenha uma curva de Bézier
  - GmagickDraw::ellipse — Desenha uma elipse na imagem
  - GmagickDraw::getfillcolor — Retorna a cor de preenchimento
  - GmagickDraw::getfillopacity — Retorna a opacidade usada ao desenhar
  - GmagickDraw::getfont — Retorna a fonte
  - GmagickDraw::getfontsize — Retorna o tamanho da fonte em pontos
  - GmagickDraw::getfontstyle — Retorna o estilo da fonte
  - GmagickDraw::getfontweight — Retorna o peso da fonte
  - GmagickDraw::getstrokecolor — Retorna a cor usada para traçar os contornos dos objetos
  - GmagickDraw::getstrokeopacity — Retorna a opacidade dos contornos dos objetos traçados
  - GmagickDraw::getstrokewidth — Retorna a largura do traço usado para desenhar contornos de objetos
  - GmagickDraw::gettextdecoration — Retorna a decoração do texto
  - GmagickDraw::gettextencoding — Retorna o conjunto de caracteres usado para anotações de texto
  - GmagickDraw::line — Desenha uma linha
  - GmagickDraw::point — Desenha um ponto
  - GmagickDraw::polygon — Desenha um polígono
  - GmagickDraw::polyline — Desenha uma polilinha
  - GmagickDraw::rectangle — Desenha um retângulo
  - GmagickDraw::rotate — Aplica a rotação especificada ao espaço de coordenadas atual
  - GmagickDraw::roundrectangle — Desenha um retângulo arredondado
  - GmagickDraw::scale — Ajusta o fator de escala
  - GmagickDraw::setfillcolor — Define a cor de preenchimento a ser usada para desenhar objetos preenchidos
  - GmagickDraw::setfillopacity — Define a opacidade de preenchimento
  - GmagickDraw::setfont — Define a fonte totalmente especificada a ser usada ao fazer anotações com texto
  - GmagickDraw::setfontsize — Define o tamanho da fonte a ser usado ao fazer anotações com texto
  - GmagickDraw::setfontstyle — Define o estilo da fonte a ser usado ao fazer anotações com texto
  - GmagickDraw::setfontweight — Define o peso da fonte
  - GmagickDraw::setstrokecolor — Define a cor usada para traçar os contornos dos objetos
  - GmagickDraw::setstrokeopacity — Especifica a opacidade dos contornos dos objetos traçados
  - GmagickDraw::setstrokewidth — Define a largura do traço usado para desenhar contornos de objetos
  - GmagickDraw::settextdecoration — Especifica uma decoração
  - GmagickDraw::settextencoding — Especifica a codificação de caracteres de texto
- GmagickPixel — A classe GmagickPixel
  - GmagickPixel::__construct — O construtor GmagickPixel
  - GmagickPixel::getcolor — Retorna a cor
  - GmagickPixel::getcolorcount — Retorna a contagem de cores associada a esta cor
  - GmagickPixel::getcolorvalue — Obtém o valor normalizado do canal de cores fornecido
  - GmagickPixel::setcolor — Define a cor
  - GmagickPixel::setcolorvalue — Define o valor normalizado de um dos canais

# Processamento de Imagem

# Introdução

Aviso

Esta extensão é EXPERIMENTAL. O comportamento desta extensão, incluindo os nomes de suas funções e qualquer outra documentação relacionada a esta extensão, pode mudar sem aviso prévio em futuras versões do PHP. Use por sua conta e risco.

Imagick é uma extensão PHP nativa para criar e modificar imagens usando a API ImageMagick.

## Sobre o ImageMagick

ImageMagick é um conjunto de aplicações para criar, editar e compor imagens bitmap. Ele pode ler, converter e gravar imagens em vários formatos (mais de 100) incluindo DPX, EXR, GIF, JPEG, JPEG-2000, PDF, PhotoCD, PNG, Postscript, SVG e TIFF.

ImageMagick Studio LLC é uma organização sem fins lucrativos dedicada a criação de soluções de software para imagens disponíveis gratuitamente.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução

## Dependências

## Requisitos de instalação em plataformas não Windows

ImageMagick >= 6.2.4 é necessária. A quantidade de formatos de arquivo suportados pela Imagick depende inteiramente da quantidade de formatos suportados pela instalação da ImageMagick. Por exemplo, Imagemagick requer ghostscript para realizar operações de PDF.

## Instalação

Esta extensão » PECL não é distribuída com o PHP.

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/imagick.

> Nota: O nome oficial desta extensão é imagick.

Os usuários do Windows podem baixar a DLL pré-construída no site » PECL. Esses pacotes já contêm a extensão DLL (php_imagick.dll) que precisa ser colocada em extension_dir. Eles também contêm as DLLs do ImageMagick, que precisam ser colocadas em algum lugar no PATH. A partir do Imagick 3.6.0, eles também contêm arquivos de configuração XML em config; para usá-los no lugar dos padrões internos, eles precisam ser colocados em `%USERPROFILE%/.config/ImageMagick` ou, alternativamente, no caminho fornecido pela variável de ambiente MAGICK_CONFIGURE_PATH. Consulte a » documentação dos arquivos de configuração do ImageMagick para obter mais detalhes.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de configuração de Imagick
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
imagick.locale_fix | `false` | `INI_ALL` | Disponível desde Imagick 2.1.0
imagick.progress_monitor | `false` | `INI_SYSTEM` | Disponível desde Imagick 2.2.2
imagick.skip_version_check | `false` | `INI_SYSTEM` | Disponível desde Imagick 3.3.0

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`imagick.locale_fix` bool

  Corrige um problema de desenho com localidades que usam '`,`' como separador de decimais.

`imagick.progress_monitor` bool

  Usada para habilitar o monitor de progresso de imagem.

`imagick.skip_version_check` bool

  Quando a Imagick é carregada, ela compara a versão da ImageMagick com a qual foi compilada, com a versão atualmente utilizada e gera um alerta caso sejam diferentes. Este alerta pode ser suprimido habilitando-se esta configuração ini.

  Não é recomendado usar uma versão da Imagick que foi compilada em uma versão diferente da ImageMagick sendo utilizada. Embora possa parecer funcionar, pode levar a travamentos aleatórios ou outro comportamento indefinido.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

Constantes `COLOR_*`

Constantes de tipo de cor. Estas constantes são usadas principalmente com ImagickPixel.

`imagick::COLOR_BLACK` (int)
  Cor preta
`imagick::COLOR_BLUE` (int)
  Cor azul
`imagick::COLOR_CYAN` (int)
  Cor ciano
`imagick::COLOR_GREEN` (int)
  Cor verde
`imagick::COLOR_RED` (int)
  Cor vermelha
`imagick::COLOR_YELLOW` (int)
  Cor amarela
`imagick::COLOR_MAGENTA` (int)
  Cor magenta
`imagick::COLOR_OPACITY` (int)
  Opacidade da cor
`imagick::COLOR_ALPHA` (int)
  Alfa da cor
`imagick::COLOR_FUZZ` (int)
  Fuzz da cor

Constantes `DISPOSE_*`DISPOSE

Constantes de tipo de descarte

`imagick::DISPOSE_UNRECOGNIZED` (int)
  Tipo de descarte não reconhecido
`imagick::DISPOSE_UNDEFINED` (int)
  Tipo de descarte indefinido
`imagick::DISPOSE_NONE` (int)
  Nenhum tipo de descarte definido
`imagick::DISPOSE_BACKGROUND` (int)
  Descartar plano de fundo
`imagick::DISPOSE_PREVIOUS` (int)
  Descartar anterior

Constantes `COMPOSITE_*`
`imagick::COMPOSITE_DEFAULT` (int)
  O operador de composição padrão
`imagick::COMPOSITE_UNDEFINED` (int)
  Operador de composição indefinido
`imagick::COMPOSITE_NO` (int)
  Nenhum operador de composição definido
`imagick::COMPOSITE_ADD` (int)
  O resultado de imagem + imagem
`imagick::COMPOSITE_ATOP` (int)
  O resultado é o mesmo formato da imagem, com a imagem composta obscurecendo a imagem onde as formas da imagem se sobrepõem
`imagick::COMPOSITE_BLEND` (int)
  Combina a imagem
`imagick::COMPOSITE_BUMPMAP` (int)
  O mesmo que COMPOSITE_MULTIPLY, exceto que a origem é convertida primeiro em escala de cinza.
`imagick::COMPOSITE_CLEAR` (int)
  Torna a imagem de destino transparente
`imagick::COMPOSITE_COLORBURN` (int)
  Escurece a imagem de destino para refletir a imagem de origem
`imagick::COMPOSITE_COLORDODGE` (int)
  Ilumina a imagem de destino para refletir a imagem de origem
`imagick::COMPOSITE_COLORIZE` (int)
  Colore a imagem de destino usando a imagem composta
`imagick::COMPOSITE_COPYBLACK` (int)
  Copia preto da origem para o destino
`imagick::COMPOSITE_COPYBLUE` (int)
  Copia azul da origem para o destino
`imagick::COMPOSITE_COPY` (int)
  Copia a imagem de origem na imagem de destino
`imagick::COMPOSITE_COPYCYAN` (int)
  Copia ciano da origem para o destino
`imagick::COMPOSITE_COPYGREEN` (int)
  Copia verde da origem ao destino
`imagick::COMPOSITE_COPYMAGENTA` (int)
  Copia magenta da origem ao destino
`imagick::COMPOSITE_COPYOPACITY` (int)
  Copia a opacidade da origem ao destino
`imagick::COMPOSITE_COPYRED` (int)
  Copia o vermelho da origem ao destino
`imagick::COMPOSITE_COPYYELLOW` (int)
  Copia amarelo da origem ao destino
`imagick::COMPOSITE_DARKEN` (int)
  Escurece a imagem de destino
`imagick::COMPOSITE_DSTATOP` (int)
  A parte do destino que fica dentro da origem é composta sobre a origem e substitui o destino
`imagick::COMPOSITE_DST` (int)
  O destino permanece intocado
`imagick::COMPOSITE_DSTIN` (int)
  As partes dentro da origem substituem o destino
`imagick::COMPOSITE_DSTOUT` (int)
  As partes fora da origem substituem o destino
`imagick::COMPOSITE_DSTOVER` (int)
  O destino substitui a origem
`imagick::COMPOSITE_DIFFERENCE` (int)
  Subtrai a mais escura das duas cores constituintes da mais clara
`imagick::COMPOSITE_DISPLACE` (int)
  Desloca os pixels da imagem de destino conforme definido pela origem
`imagick::COMPOSITE_DISSOLVE` (int)
  Dissolve a origem no destino
`imagick::COMPOSITE_EXCLUSION` (int)
  Produz um efeito semelhante ao de imagick::COMPOSITE_DIFFERENCE, mas aparece com menor contraste
`imagick::COMPOSITE_HARDLIGHT` (int)
  Multiplica ou filtra as cores, dependendo do valor da cor de origem
`imagick::COMPOSITE_HUE` (int)
  Modifica o matiz do destino conforme definido pela origem
`imagick::COMPOSITE_IN` (int)
  Origem dos compostos até o destino
`imagick::COMPOSITE_LIGHTEN` (int)
  Ilumina o destino conforme definido pela origem
`imagick::COMPOSITE_LUMINIZE` (int)
  Ilumina o destino conforme definido pela origem
`imagick::COMPOSITE_MINUS` (int)
  Subtrai a origem do destino
`imagick::COMPOSITE_MODULATE` (int)
  Modula o brilho, saturação e matiz do destino conforme definido pela origem
`imagick::COMPOSITE_MULTIPLY` (int)
  Multiplica o destino pela origem
`imagick::COMPOSITE_OUT` (int)
  Compõe partes externas da origem no destino
`imagick::COMPOSITE_OVER` (int)
  Compõe a origem sobre o destino
`imagick::COMPOSITE_OVERLAY` (int)
  Sobrepõe a origem no destino
`imagick::COMPOSITE_PLUS` (int)
  Adiciona a origem ao destino
`imagick::COMPOSITE_REPLACE` (int)
  Substitui o destino pela origem
`imagick::COMPOSITE_SATURATE` (int)
  Satura o destino conforme definido pela origem
`imagick::COMPOSITE_SCREEN` (int)
  A origem e o destino são complementados e depois multiplicados e depois substituem o destino
`imagick::COMPOSITE_SOFTLIGHT` (int)
  Escurece ou clareia as cores, dependendo da origem
`imagick::COMPOSITE_SRCATOP` (int)
  A parte da origem que fica dentro do destino é composta no destino
`imagick::COMPOSITE_SRC` (int)
  A origem é copiada para o destino
`imagick::COMPOSITE_SRCIN` (int)
  A parte da origem situada dentro do destino substitui o destino
`imagick::COMPOSITE_SRCOUT` (int)
  A parte da origem fora do destino substitui o destino
`imagick::COMPOSITE_SRCOVER` (int)
  A origem substitui o destino
`imagick::COMPOSITE_SUBTRACT` (int)
  Subtrai as cores da imagem de origem da imagem de destino
`imagick::COMPOSITE_THRESHOLD` (int)
  A origem é composta pelo destino conforme definido pelo limite da origem
`imagick::COMPOSITE_XOR` (int)
  A parte da origem que fica fora do destino é combinada com a parte do destino que fica fora da origem

Constantes `MONTAGEMODE_*`

`imagick::MONTAGEMODE_FRAME` (int)
`imagick::MONTAGEMODE_UNFRAME` (int)
`imagick::MONTAGEMODE_CONCATENATE` (int)

Constantes `STYLE_*`

`imagick::STYLE_NORMAL` (int)
`imagick::STYLE_ITALIC` (int)
`imagick::STYLE_OBLIQUE` (int)
`imagick::STYLE_ANY` (int)

Constantes `FILTER_*`

`imagick::FILTER_UNDEFINED` (int)
`imagick::FILTER_POINT` (int)
`imagick::FILTER_BOX` (int)
`imagick::FILTER_TRIANGLE` (int)
`imagick::FILTER_HERMITE` (int)
`imagick::FILTER_HANNING` (int)
`imagick::FILTER_HAMMING` (int)
`imagick::FILTER_BLACKMAN` (int)
`imagick::FILTER_GAUSSIAN` (int)
`imagick::FILTER_QUADRATIC` (int)
`imagick::FILTER_CUBIC` (int)
`imagick::FILTER_CATROM` (int)
`imagick::FILTER_MITCHELL` (int)
`imagick::FILTER_LANCZOS` (int)
`imagick::FILTER_BESSEL` (int)
`imagick::FILTER_SINC` (int)

Constantes `IMGTYPE_*`

`imagick::IMGTYPE_UNDEFINED` (int)
`imagick::IMGTYPE_BILEVEL` (int)
`imagick::IMGTYPE_GRAYSCALE` (int)
`imagick::IMGTYPE_GRAYSCALEMATTE` (int)
`imagick::IMGTYPE_PALETTE` (int)
`imagick::IMGTYPE_PALETTEMATTE` (int)
`imagick::IMGTYPE_TRUECOLOR` (int)
`imagick::IMGTYPE_TRUECOLORMATTE` (int)
`imagick::IMGTYPE_COLORSEPARATION` (int)
`imagick::IMGTYPE_COLORSEPARATIONMATTE` (int)
`imagick::IMGTYPE_OPTIMIZE` (int)

Constantes `RESOLUTION_*`

`imagick::RESOLUTION_UNDEFINED` (int)
`imagick::RESOLUTION_PIXELSPERINCH` (int)
`imagick::RESOLUTION_PIXELSPERCENTIMETER` (int)

Constantes `COMPRESSION_*`

`imagick::COMPRESSION_UNDEFINED` (int)
`imagick::COMPRESSION_NO` (int)
`imagick::COMPRESSION_BZIP` (int)
`imagick::COMPRESSION_FAX` (int)
`imagick::COMPRESSION_GROUP4` (int)
`imagick::COMPRESSION_JPEG` (int)
`imagick::COMPRESSION_JPEG2000` (int)
`imagick::COMPRESSION_LOSSLESSJPEG` (int)
`imagick::COMPRESSION_LZW` (int)
`imagick::COMPRESSION_RLE` (int)
`imagick::COMPRESSION_ZIP` (int)
`imagick::COMPRESSION_DXT1` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.0 ou superior.
`imagick::COMPRESSION_DXT3` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.0 ou superior.
`imagick::COMPRESSION_DXT5` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.0 ou superior.

Constantes `PAINT_*`

`imagick::PAINT_POINT` (int)
`imagick::PAINT_REPLACE` (int)
`imagick::PAINT_FLOODFILL` (int)
`imagick::PAINT_FILLTOBORDER` (int)
`imagick::PAINT_RESET` (int)

Constantes `GRAVITY_*`

`imagick::GRAVITY_NORTHWEST` (int)
`imagick::GRAVITY_NORTH` (int)
`imagick::GRAVITY_NORTHEAST` (int)
`imagick::GRAVITY_WEST` (int)
`imagick::GRAVITY_CENTER` (int)
`imagick::GRAVITY_EAST` (int)
`imagick::GRAVITY_SOUTHWEST` (int)
`imagick::GRAVITY_SOUTH` (int)
`imagick::GRAVITY_SOUTHEAST` (int)

Constantes `STRETCH_*`

`imagick::STRETCH_NORMAL` (int)
`imagick::STRETCH_ULTRACONDENSED` (int)
`imagick::STRETCH_CONDENSED` (int)
`imagick::STRETCH_SEMICONDENSED` (int)
`imagick::STRETCH_SEMIEXPANDED` (int)
`imagick::STRETCH_EXPANDED` (int)
`imagick::STRETCH_EXTRAEXPANDED` (int)
`imagick::STRETCH_ULTRAEXPANDED` (int)
`imagick::STRETCH_ANY` (int)

Constantes `ALIGN_*`

`imagick::ALIGN_UNDEFINED` (int)
`imagick::ALIGN_LEFT` (int)
`imagick::ALIGN_CENTER` (int)
`imagick::ALIGN_RIGHT` (int)

Constantes `DECORATION_*`

`imagick::DECORATION_NO` (int)
`imagick::DECORATION_UNDERLINE` (int)
`imagick::DECORATION_OVERLINE` (int)
`imagick::DECORATION_LINETROUGH` (int)

Constantes `NOISE_*`

`imagick::NOISE_UNIFORM` (int)
`imagick::NOISE_GAUSSIAN` (int)
`imagick::NOISE_MULTIPLICATIVEGAUSSIAN` (int)
`imagick::NOISE_IMPULSE` (int)
`imagick::NOISE_LAPLACIAN` (int)
`imagick::NOISE_POISSON` (int)
`imagick::NOISE_RANDOM` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.6 ou superior.

Constantes `CHANNEL_*`

`imagick::CHANNEL_UNDEFINED` (int)
`imagick::CHANNEL_RED` (int)
`imagick::CHANNEL_GRAY` (int)
`imagick::CHANNEL_CYAN` (int)
`imagick::CHANNEL_GREEN` (int)
`imagick::CHANNEL_MAGENTA` (int)
`imagick::CHANNEL_BLUE` (int)
`imagick::CHANNEL_YELLOW` (int)
`imagick::CHANNEL_ALPHA` (int)
`imagick::CHANNEL_OPACITY` (int)
`imagick::CHANNEL_MATTE` (int)
`imagick::CHANNEL_BLACK` (int)
`imagick::CHANNEL_INDEX` (int)
`imagick::CHANNEL_ALL` (int)
`imagick::CHANNEL_DEFAULT` (int)

Constantes `METRIC_*`

`imagick::METRIC_UNDEFINED` (int)
`imagick::METRIC_MEANABSOLUTEERROR` (int)
`imagick::METRIC_MEANSQUAREERROR` (int)
`imagick::METRIC_PEAKABSOLUTEERROR` (int)
`imagick::METRIC_PEAKSIGNALTONOISERATIO` (int)
`imagick::METRIC_ROOTMEANSQUAREDERROR` (int)

Constantes `PIXEL_*`

`imagick::PIXEL_CHAR` (int)
`imagick::PIXEL_DOUBLE` (int)
`imagick::PIXEL_FLOAT` (int)
`imagick::PIXEL_INTEGER` (int)
  Disponível somente para ImageMagick < 7.
`imagick::PIXEL_LONG` (int)
`imagick::PIXEL_QUANTUM` (int)
`imagick::PIXEL_SHORT` (int)

Constantes `EVALUATE_*`

`imagick::EVALUATE_UNDEFINED` (int)
`imagick::EVALUATE_ADD` (int)
`imagick::EVALUATE_AND` (int)
`imagick::EVALUATE_DIVIDE` (int)
`imagick::EVALUATE_LEFTSHIFT` (int)
`imagick::EVALUATE_MAX` (int)
`imagick::EVALUATE_MIN` (int)
`imagick::EVALUATE_MULTIPLY` (int)
`imagick::EVALUATE_OR` (int)
`imagick::EVALUATE_RIGHTSHIFT` (int)
`imagick::EVALUATE_SET` (int)
`imagick::EVALUATE_SUBTRACT` (int)
`imagick::EVALUATE_XOR` (int)
`imagick::EVALUATE_POW` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.4 ou superior.
`imagick::EVALUATE_LOG` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.4 ou superior.
`imagick::EVALUATE_THRESHOLD` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.4 ou superior.
`imagick::EVALUATE_THRESHOLDBLACK` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.4 ou superior.
`imagick::EVALUATE_THRESHOLDWHITE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.4 ou superior.
`imagick::EVALUATE_GAUSSIANNOISE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.4 ou superior.
`imagick::EVALUATE_IMPULSENOISE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.4 ou superior.
`imagick::EVALUATE_LAPLACIANNOISE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.4 ou superior.
`imagick::EVALUATE_MULTIPLICATIVENOISE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.4 ou superior.
`imagick::EVALUATE_POISSONNOISE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.4 ou superior.
`imagick::EVALUATE_UNIFORMNOISE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.4 ou superior.
`imagick::EVALUATE_COSINE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.4 ou superior.
`imagick::EVALUATE_SINE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.4 ou superior.
`imagick::EVALUATE_ADDMODULUS` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.4 ou superior.

Constantes `COLORSPACE_*`

`imagick::COLORSPACE_UNDEFINED` (int)
`imagick::COLORSPACE_RGB` (int)
`imagick::COLORSPACE_GRAY` (int)
`imagick::COLORSPACE_TRANSPARENT` (int)
`imagick::COLORSPACE_OHTA` (int)
`imagick::COLORSPACE_LAB` (int)
`imagick::COLORSPACE_XYZ` (int)
`imagick::COLORSPACE_YCBCR` (int)
`imagick::COLORSPACE_YCC` (int)
`imagick::COLORSPACE_YIQ` (int)
`imagick::COLORSPACE_YPBPR` (int)
`imagick::COLORSPACE_YUV` (int)
`imagick::COLORSPACE_CMYK` (int)
`imagick::COLORSPACE_SRGB` (int)
`imagick::COLORSPACE_HSB` (int)
`imagick::COLORSPACE_HSL` (int)
`imagick::COLORSPACE_HWB` (int)
`imagick::COLORSPACE_REC601LUMA` (int)
`imagick::COLORSPACE_REC709LUMA` (int)
`imagick::COLORSPACE_LOG` (int)
`imagick::COLORSPACE_CMY` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.2 ou superior.

Constantes `VIRTUALPIXELMETHOD_*`

`imagick::VIRTUALPIXELMETHOD_UNDEFINED` (int)
`imagick::VIRTUALPIXELMETHOD_BACKGROUND` (int)
`imagick::VIRTUALPIXELMETHOD_CONSTANT` (int)
`imagick::VIRTUALPIXELMETHOD_EDGE` (int)
`imagick::VIRTUALPIXELMETHOD_MIRROR` (int)
`imagick::VIRTUALPIXELMETHOD_TILE` (int)
`imagick::VIRTUALPIXELMETHOD_TRANSPARENT` (int)
`imagick::VIRTUALPIXELMETHOD_MASK` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.2 ou superior.
`imagick::VIRTUALPIXELMETHOD_BLACK` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.2 ou superior.
`imagick::VIRTUALPIXELMETHOD_GRAY` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.2 ou superior.
`imagick::VIRTUALPIXELMETHOD_WHITE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.2 ou superior.
`imagick::VIRTUALPIXELMETHOD_HORIZONTALTILE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.3 ou superior.
`imagick::VIRTUALPIXELMETHOD_VERTICALTILE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.3 ou superior.

Constantes `PREVIEW_*`

`imagick::PREVIEW_UNDEFINED` (int)
`imagick::PREVIEW_ROTATE` (int)
`imagick::PREVIEW_SHEAR` (int)
`imagick::PREVIEW_ROLL` (int)
`imagick::PREVIEW_HUE` (int)
`imagick::PREVIEW_SATURATION` (int)
`imagick::PREVIEW_BRIGHTNESS` (int)
`imagick::PREVIEW_GAMMA` (int)
`imagick::PREVIEW_SPIFF` (int)
`imagick::PREVIEW_DULL` (int)
`imagick::PREVIEW_GRAYSCALE` (int)
`imagick::PREVIEW_QUANTIZE` (int)
`imagick::PREVIEW_DESPECKLE` (int)
`imagick::PREVIEW_REDUCENOISE` (int)
`imagick::PREVIEW_ADDNOISE` (int)
`imagick::PREVIEW_SHARPEN` (int)
`imagick::PREVIEW_BLUR` (int)
`imagick::PREVIEW_THRESHOLD` (int)
`imagick::PREVIEW_EDGEDETECT` (int)
`imagick::PREVIEW_SPREAD` (int)
`imagick::PREVIEW_SOLARIZE` (int)
`imagick::PREVIEW_SHADE` (int)
`imagick::PREVIEW_RAISE` (int)
`imagick::PREVIEW_SEGMENT` (int)
`imagick::PREVIEW_SWIRL` (int)
`imagick::PREVIEW_IMPLODE` (int)
`imagick::PREVIEW_WAVE` (int)
`imagick::PREVIEW_OILPAINT` (int)
`imagick::PREVIEW_CHARCOALDRAWING` (int)
`imagick::PREVIEW_JPEG` (int)

Constantes `RENDERINGINTENT_*`

`imagick::RENDERINGINTENT_UNDEFINED` (int)
`imagick::RENDERINGINTENT_SATURATION` (int)
`imagick::RENDERINGINTENT_PERCEPTUAL` (int)
`imagick::RENDERINGINTENT_ABSOLUTE` (int)
`imagick::RENDERINGINTENT_RELATIVE` (int)

Constantes `INTERLACE_*`

`imagick::INTERLACE_UNDEFINED` (int)
`imagick::INTERLACE_NO` (int)
`imagick::INTERLACE_LINE` (int)
`imagick::INTERLACE_PLANE` (int)
`imagick::INTERLACE_PARTITION` (int)
`imagick::INTERLACE_GIF` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.4 ou superior.
`imagick::INTERLACE_JPEG` (int)
`imagick::INTERLACE_PNG` (int)

Constantes `FILLRULE_*`

`imagick::FILLRULE_UNDEFINED` (int)
`imagick::FILLRULE_EVENODD` (int)
`imagick::FILLRULE_NONZERO` (int)

Constantes `PATHUNITS_*`

`imagick::PATHUNITS_UNDEFINED` (int)
`imagick::PATHUNITS_USERSPACE` (int)
`imagick::PATHUNITS_USERSPACEONUSE` (int)
`imagick::PATHUNITS_OBJECTBOUNDINGBOX` (int)

Constantes `LINECAP_*`

`imagick::LINECAP_UNDEFINED` (int)
`imagick::LINECAP_BUTT` (int)
`imagick::LINECAP_ROUND` (int)
`imagick::LINECAP_SQUARE` (int)

Constantes `LINEJOIN_*`

`imagick::LINEJOIN_UNDEFINED` (int)
`imagick::LINEJOIN_MITER` (int)
`imagick::LINEJOIN_ROUND` (int)
`imagick::LINEJOIN_BEVEL` (int)

Constantes `RESOURCETYPE_*`

`imagick::RESOURCETYPE_UNDEFINED` (int)
`imagick::RESOURCETYPE_AREA` (int)
  Define a máxima largura * altura de uma imagem que pode residir na memória cache de pixels.
`imagick::RESOURCETYPE_DISK` (int)
  Define a quantidade máxima de espaço em disco em bytes permitida para uso pelo cache de pixels.
`imagick::RESOURCETYPE_FILE` (int)
  Define o número máximo de arquivos de cache de pixels abertos.
`imagick::RESOURCETYPE_MAP` (int)
  Define a quantidade máxima de mapa de memória em bytes a ser alocada para o cache de pixels.
`imagick::RESOURCETYPE_MEMORY` (int)
  Define a quantidade máxima de memória em bytes a ser alocada para o cache de pixels da memória.
`imagick::RESOURCETYPE_THREAD` (int)
  Define o máximo de threads paralelos. Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.7.8 ou superior.

Constantes `LAYERMETHOD_*`

`imagick::LAYERMETHOD_UNDEFINED` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.
`imagick::LAYERMETHOD_COALESCE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.
`imagick::LAYERMETHOD_COMPAREANY` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.
`imagick::LAYERMETHOD_COMPARECLEAR` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.
`imagick::LAYERMETHOD_COMPAREOVERLAY` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.
`imagick::LAYERMETHOD_DISPOSE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.
`imagick::LAYERMETHOD_OPTIMIZE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.
`imagick::LAYERMETHOD_OPTIMIZEPLUS` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.
`imagick::LAYERMETHOD_OPTIMIZEIMAGE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.0 ou superior.
`imagick::LAYERMETHOD_OPTIMIZETRANS` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.0 ou superior.
`imagick::LAYERMETHOD_REMOVEDUPS` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.0 ou superior.
`imagick::LAYERMETHOD_REMOVEZERO` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.0 ou superior.
`imagick::LAYERMETHOD_COMPOSITE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.0 ou superior.
`imagick::LAYERMETHOD_MERGE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.7 ou superior.
`imagick::LAYERMETHOD_FLATTEN` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.7 ou superior.
`imagick::LAYERMETHOD_MOSAIC` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.7 ou superior.

Constantes `ORIENTATION_*`

`imagick::ORIENTATION_UNDEFINED` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.0 ou superior.
`imagick::ORIENTATION_TOPLEFT` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.0 ou superior.
`imagick::ORIENTATION_TOPRIGHT` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.0 ou superior.
`imagick::ORIENTATION_BOTTOMRIGHT` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.0 ou superior.
`imagick::ORIENTATION_BOTTOMLEFT` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.0 ou superior.
`imagick::ORIENTATION_LEFTTOP` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.0 ou superior.
`imagick::ORIENTATION_RIGHTTOP` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.0 ou superior.
`imagick::ORIENTATION_RIGHTBOTTOM` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.0 ou superior.
`imagick::ORIENTATION_LEFTBOTTOM` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.0 ou superior.

Constantes `DISTORTION_*`

`imagick::DISTORTION_UNDEFINED` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.6 ou superior.
`imagick::DISTORTION_AFFINE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.6 ou superior.
`imagick::DISTORTION_AFFINEPROJECTION` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.6 ou superior.
`imagick::DISTORTION_ARC` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.6 ou superior.
`imagick::DISTORTION_BILINEAR` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.6 ou superior.
`imagick::DISTORTION_PERSPECTIVE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.6 ou superior.
`imagick::DISTORTION_PERSPECTIVEPROJECTION` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.6 ou superior.
`imagick::DISTORTION_SCALEROTATETRANSLATE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.6 ou superior.
`imagick::DISTORTION_POLYNOMIAL` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.6 ou superior.
`imagick::DISTORTION_POLAR` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.6 ou superior.
`imagick::DISTORTION_DEPOLAR` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.6 ou superior.
`imagick::DISTORTION_BARREL` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.6 ou superior.
`imagick::DISTORTION_BARRELINVERSE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.6 ou superior.
`imagick::DISTORTION_SHEPARDS` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.6 ou superior.
`imagick::DISTORTION_SENTINEL` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.6 ou superior.

Constantes `ALPHACHANNEL_*`

`imagick::ALPHACHANNEL_ACTIVATE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.8 ou superior.
`imagick::ALPHACHANNEL_DEACTIVATE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.8 ou superior.
`imagick::ALPHACHANNEL_RESET` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.8 ou superior.
`imagick::ALPHACHANNEL_SET` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.8 ou superior.
`imagick::ALPHACHANNEL_UNDEFINED` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.6 ou superior.
`imagick::ALPHACHANNEL_COPY` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.6 ou superior.
`imagick::ALPHACHANNEL_EXTRACT` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.6 ou superior.
`imagick::ALPHACHANNEL_OPAQUE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.6 ou superior.
`imagick::ALPHACHANNEL_SHAPE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.6 ou superior.
`imagick::ALPHACHANNEL_TRANSPARENT` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.6 ou superior.
`imagick::ALPHACHANNEL_BACKGROUND` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.5.3 ou superior.
`imagick::ALPHACHANNEL_REMOVE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.7.8 ou superior.
`imagick::ALPHACHANNEL_ASSOCIATE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.9.0 ou superior.
`imagick::ALPHACHANNEL_DISSOCIATE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.9.0 ou superior.
`imagick::ALPHACHANNEL_ON` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 7.0.0 ou superior.
`imagick::ALPHACHANNEL_OFF` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 7.0.0 ou superior.
`imagick::ALPHACHANNEL_DISCRETE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 7.0.0 ou superior.

Constantes `SPARSECOLORMETHOD_*`

`imagick::SPARSECOLORMETHOD_UNDEFINED` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.6 ou superior.
`imagick::SPARSECOLORMETHOD_BARYCENTRIC` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.6 ou superior.
`imagick::SPARSECOLORMETHOD_BILINEAR` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.6 ou superior.
`imagick::SPARSECOLORMETHOD_POLYNOMIAL` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.6 ou superior.
`imagick::SPARSECOLORMETHOD_SPEPARDS` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.6 ou superior.
`imagick::SPARSECOLORMETHOD_VORONOI` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.6 ou superior.

Constantes `FUNCTION_*`

`imagick::FUNCTION_UNDEFINED` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.9 ou superior.
`imagick::FUNCTION_POLYNOMIAL` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.9 ou superior.
`imagick::FUNCTION_SINUSOID` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.9 ou superior.

Constantes `INTERPOLATE_*`

`imagick::INTERPOLATE_UNDEFINED` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.2 ou superior.
`imagick::INTERPOLATE_AVERAGE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.2 ou superior.
`imagick::INTERPOLATE_BICUBIC` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.2 ou superior.
`imagick::INTERPOLATE_BILINEAR` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.2 ou superior.
`imagick::INTERPOLATE_FILTER` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.2 ou superior.
`imagick::INTERPOLATE_INTEGER` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.2 ou superior.
`imagick::INTERPOLATE_MESH` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.2 ou superior.
`imagick::INTERPOLATE_NEARESTNEIGHBOR` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.2 ou superior.
`imagick::INTERPOLATE_SPLINE` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.4 ou superior.

Constantes `DITHERMETHOD_*`

`imagick::DITHERMETHOD_UNDEFINED` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.6 ou superior.
`imagick::DITHERMETHOD_NO` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.6 ou superior.
`imagick::DITHERMETHOD_RIEMERSMA` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.6 ou superior.
`imagick::DITHERMETHOD_FLOYDSTEINBERG` (int)
  Esta constante estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.6 ou superior.

# Exemplos

## Índice

- Uso básico

## Uso básico

Imagick faz com que a manipulação de imagem no PHP seja extremamente fácil através de uma interface orientada a objetos. Aqui está um exemplo rápido de como criar uma miniatura:

Exemplo #1 Criando uma miniatura em Imagick

    <?php

    header('Content-type: image/jpeg');

    $image = new Imagick('image.jpg');

    // Se 0 for informado em um parâmetro de largura ou altura,
    // a razão de aspecto é mantida
    $image->thumbnailImage(100, 0);

    echo $image;

    ?>

Usando SPL e outros recursos OO suportados no Imagick, pode ser simples redimensionar todos os arquivos em um diretório (útil para redimensionar em lote grandes imagens de câmeras digitais para serem visualizadas na web). Aqui usamos redimensionamento, pois podemos querer reter certos metadados:

Exemplo #2 Criando uma miniatura de todos os arquivos JPG em um diretório

    <?php

    $images = new Imagick(glob('images/*.JPG'));

    foreach($images as $image) {

        // Informar 0 vai forçar a miniatura a manter a razão de aspecto
        $image->thumbnailImage(1024,0);

    }

    $images->writeImages();

    ?>

Este é um exemplo de criação do reflexo de uma imagem. O reflexo é criado invertendo a imagem e sobrepondo um gradiente nela. Em seguida, a imagem original e o reflexo são sobrepostos em uma tela.

Exemplo #3 Criando o reflexo de uma imagem

    <?php
    /* Lê a imagem */
    $im = new Imagick("teste.png");

    /* Faz a miniatura da imagem */
    $im->thumbnailImage(200, null);

    /* Cria uma borda para a imagem */
    $im->borderImage(new ImagickPixel("white"), 5, 5);

    /* Clona e inverte a imagem */
    $reflection = $im->clone();
    $reflection->flipImage();

    /* Cria um gradiente. Ele será sobreposto no reflexo */
    $gradient = new Imagick();

    /* O gradiente precisa ser grande o suficiente para a imagem e para as bordas */
    $gradient->newPseudoImage($reflection->getImageWidth() + 10, $reflection->getImageHeight() + 10, "gradient:transparent-black");

    /* Compõe o gradiente no reflexo */
    $reflection->compositeImage($gradient, imagick::COMPOSITE_OVER, 0, 0);

    /* Adiciona um pouco de opacidade. Requer ImageMagick 6.2.9 ou superior */
    $reflection->setImageOpacity( 0.3 );

    /* Cria uma tela vazia */
    $canvas = new Imagick();

    /* A tela precisa ser grande o suficiente para conter as duas imagens */
    $width = $im->getImageWidth() + 40;
    $height = ($im->getImageHeight() * 2) + 30;
    $canvas->newImage($width, $height, new ImagickPixel("black"));
    $canvas->setImageFormat("png");

    /* Compõe a imagem original e o reflexo na tela */
    $canvas->compositeImage($im, imagick::COMPOSITE_OVER, 20, 10);
    $canvas->compositeImage($reflection, imagick::COMPOSITE_OVER, 20, $im->getImageHeight() + 10);

    /* Mostra a imagem */
    header("Content-Type: image/png");
    echo $canvas;
    ?>

O exemplo acima produzirá algo semelhante a:

Este exemplo ilustra como usar padrões de preenchimento no desenho.

Exemplo #4 Preenchendo texto com gradiente

    <?php

    /* Cria um novo objeto Imagick */
    $im = new Imagick();

    /* Cria uma nova imagem que será usada como padrão de preenchimento */
    $im->newPseudoImage(50, 50, "gradient:red-black");

    /* Cria objeto ImagickDraw */
    $draw = new ImagickDraw();

    /* Inicia um padrão chamado "gradiente" */
    $draw->pushPattern('gradiente', 0, 0, 50, 50);

    /* Compõe o gradiente no padrão */
    $draw->composite(Imagick::COMPOSITE_OVER, 0, 0, 50, 50, $im);

    /* Fecha o padrão */
    $draw->popPattern();

    /* Usa o padrão chamado "gradiente" como preenchimento */
    $draw->setFillPatternURL('#gradiente');

    /* Define o tamanho da fonte para 52 */
    $draw->setFontSize(52);

    /* Escreve um texto */
    $draw->annotation(20, 50, "Hello World!");

    /* Cria um novo objeto de tela e uma imagem branca */
    $canvas = new Imagick();
    $canvas->newImage(350, 70, "white");

    /* Desenha o ImagickDraw na tela */
    $canvas->drawImage($draw);

    /* borda preta de 1 pixel em torno da imagem */
    $canvas->borderImage('black', 1, 1);

    /* Define o formato para PNG */
    $canvas->setImageFormat('png');

    /* Mostra a imagem */
    header("Content-Type: image/png");
    echo $canvas;
    ?>

O exemplo acima produzirá algo semelhante a:

Trabalhando com GIFs animados

Exemplo #5 Lê a imagem GIF e redimensiona todos os quadros

    <?php

    /* Cria um novo objeto Imagick e lê o arquivo GIF */
    $im = new Imagick("exemplo.gif");

    /* Redimensiona todos os quadros */
    foreach ($im as $frame) {
        /* quadros de 50x50 */
        $frame->thumbnailImage(50, 50);

        /* Define a tela virtual para o tamanho correto */
        $frame->setImagePage(50, 50, 0, 0);
    }

    /* Observe que a função writeImages é usada no lugar de writeImage */
    $im->writeImages("example_small.gif", true);
    ?>

Trabalhando com a primitiva de elipse e fontes customizadas

Exemplo #6 Criando a logomarca do PHP

    <?php
    /* Define largura e altura na proporção da logomarca genuína do PHP */
    $width = 400;
    $height = 210;

    /* Cria um objeto Imagick com tela transparente */
    $img = new Imagick();
    $img->newImage($width, $height, new ImagickPixel('transparent'));

    /* Nova instância de ImagickDraw para desenhar a elipse */
    $draw = new ImagickDraw();
    /* Define cor de preenchimento roxa para a elipse */
    $draw->setFillColor('#777bb4');
    /* Define as dimensões da elipse */
    $draw->ellipse($width / 2, $height / 2, $width / 2, $height / 2, 0, 360);
    /* Desenha a elipse na tela */
    $img->drawImage($draw);

    /* Redefine a cor de preenchimento de roxa para preta para o texto (nota: reutilizando o objeto ImagickDraw) */
    $draw->setFillColor('black');
    /* Define a borda para a cor branca */
    $draw->setStrokeColor('white');
    /* Define a espessura da borda */
    $draw->setStrokeWidth(2);
    /* Define o espaçamento da fonte (valor negativo significa que as letras ficam mais próximas uma da outra) */
    $draw->setTextKerning(-8);
    /* Define a fonte e o tamanho usados na logomarca do PHP */
    $draw->setFont('Handel Gothic.ttf');
    $draw->setFontSize(150);
    /* Centra o texto horizontalmente e verticalmente */
    $draw->setGravity(Imagick::GRAVITY_CENTER);

    /* Adiciona o texto central "php" com deslocamento Y de -10 na tela (dentro da elipse) */
    $img->annotateImage($draw, 0, -10, 0, 'php');
    $img->setImageFormat('png');

    /* Define o cabeçalho adequado para PNG e mostra a imagem */
    header('Content-Type: image/png');
    echo $img;
    ?>

O exemplo acima produzirá algo semelhante a:

# A classe Imagick

(PECL imagick 2, PECL imagick 3)

## Resumo da classe

class Imagick implements Iterator {
public function __construct(mixed `$files` = ?)
public function adaptiveBlurImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function adaptiveResizeImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool
public function adaptiveSharpenImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function adaptiveThresholdImage(int `$width`, int `$height`, int `$offset`): bool
public function addImage(Imagick `$source`): bool
public function addNoiseImage(int `$noise_type`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function affineTransformImage(ImagickDraw `$matrix`): bool
public function animateImages(string `$x_server`): bool
public function annotateImage(
ImagickDraw `$draw_settings`,
float `$x`,
float `$y`,
float `$angle`,
string `$text`
): bool
public function appendImages(bool `$stack`): Imagick
public function autoLevelImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function averageImages(): Imagick
public function blackThresholdImage(mixed `$threshold`): bool
public function blueShiftImage(float `$factor` = 1.5): bool
public function blurImage(float `$radius`, float `$sigma`, int `$channel` = ?): bool
public function borderImage(mixed `$bordercolor`, int `$width`, int `$height`): bool
public function brightnessContrastImage(float `$brightness`, float `$contrast`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function charcoalImage(float `$radius`, float `$sigma`): bool
public function chopImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function clampImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function clear(): bool
public function clipImage(): bool
public function clipImagePath(string `$pathname`, string `$inside`): void
public function clipPathImage(string `$pathname`, bool `$inside`): bool
public function clone(): Imagick
public function clutImage(Imagick `$lookup_table`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function coalesceImages(): Imagick
public function colorFloodfillImage(
mixed `$fill`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`
): bool
public function colorizeImage(mixed `$colorize`, mixed `$opacity`, bool `$legacy` = `false`): bool
public function colorMatrixImage(array `$color_matrix`): bool
public function combineImages(int `$channelType`): Imagick
public function commentImage(string `$comment`): bool
public function compareImageChannels(Imagick `$image`, int `$channelType`, int `$metricType`): array
public function compareImageLayers(int `$method`): Imagick
public function compareImages(Imagick `$compare`, int `$metric`): array
public function compositeImage(
Imagick `$composite_object`,
int `$composite`,
int `$x`,
int `$y`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function contrastImage(bool `$sharpen`): bool
public function contrastStretchImage(float `$black_point`, float `$white_point`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function convolveImage(array `$kernel`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function count(int `$mode` = 0): int
public function cropImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function cropThumbnailImage(int `$width`, int `$height`, bool `$legacy` = `false`): bool
public function current(): Imagick
public function cycleColormapImage(int `$displace`): bool
public function decipherImage(string `$passphrase`): bool
public function deconstructImages(): Imagick
public function deleteImageArtifact(string `$artifact`): bool
public function deleteImageProperty(string `$name`): bool
public function deskewImage(float `$threshold`): bool
public function despeckleImage(): bool
public function destroy(): bool
public function displayImage(string `$servername`): bool
public function displayImages(string `$servername`): bool
public function distortImage(int `$method`, array `$arguments`, bool `$bestfit`): bool
public function drawImage(ImagickDraw `$draw`): bool
public function edgeImage(float `$radius`): bool
public function embossImage(float `$radius`, float `$sigma`): bool
public function encipherImage(string `$passphrase`): bool
public function enhanceImage(): bool
public function equalizeImage(): bool
public function evaluateImage(int `$op`, float `$constant`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function exportImagePixels(
int `$x`,
int `$y`,
int `$width`,
int `$height`,
string `$map`,
int `$STORAGE`
): array
public function extentImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function filter(ImagickKernel `$ImagickKernel`, int `$channel` = Imagick::CHANNEL_UNDEFINED): bool
public function flattenImages(): Imagick
public function flipImage(): bool
public function floodFillPaintImage(
mixed `$fill`,
float `$fuzz`,
mixed `$target`,
int `$x`,
int `$y`,
bool `$invert`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function flopImage(): bool
public function forwardFourierTransformimage(bool `$magnitude`): bool
public function frameImage(
mixed `$matte_color`,
int `$width`,
int `$height`,
int `$inner_bevel`,
int `$outer_bevel`
): bool
public function functionImage(int `$function`, array `$arguments`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function fxImage(string `$expression`, int `$channel` = Imagick::CHANNEL_DEFAULT): Imagick
public function gammaImage(float `$gamma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function gaussianBlurImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function getColorspace(): int
public function getCompression(): int
public function getCompressionQuality(): int
public static function getCopyright(): string
public function getFilename(): string
public function getFont(): string
public function getFormat(): string
public function getGravity(): int
public static function getHomeURL(): string
public function getImage(): Imagick
public function getImageAlphaChannel(): bool
public function getImageArtifact(string `$artifact`): string
public function getImageAttribute(string `$key`): string
public function getImageBackgroundColor(): ImagickPixel
public function getImageBlob(): string
public function getImageBluePrimary(): array
public function getImageBorderColor(): ImagickPixel
public function getImageChannelDepth(int `$channel`): int
public function getImageChannelDistortion(Imagick `$reference`, int `$channel`, int `$metric`): float
public function getImageChannelDistortions(Imagick `$reference`, int `$metric`, int `$channel` = Imagick::CHANNEL_DEFAULT): float
public function getImageChannelExtrema(int `$channel`): array
public function getImageChannelKurtosis(int `$channel` = Imagick::CHANNEL_DEFAULT): array
public function getImageChannelMean(int `$channel`): array
public function getImageChannelRange(int `$channel`): array
public function getImageChannelStatistics(): array
public function getImageClipMask(): Imagick
public function getImageColormapColor(int `$index`): ImagickPixel
public function getImageColors(): int
public function getImageColorspace(): int
public function getImageCompose(): int
public function getImageCompression(): int
public function getImageCompressionQuality(): int
public function getImageDelay(): int
public function getImageDepth(): int
public function getImageDispose(): int
public function getImageDistortion(MagickWand `$reference`, int `$metric`): float
public function getImageExtrema(): array
public function getImageFilename(): string
public function getImageFormat(): string
public function getImageGamma(): float
public function getImageGeometry(): array
public function getImageGravity(): int
public function getImageGreenPrimary(): array
public function getImageHeight(): int
public function getImageHistogram(): array
public function getImageIndex(): int
public function getImageInterlaceScheme(): int
public function getImageInterpolateMethod(): int
public function getImageIterations(): int
public function getImageLength(): int
public function getImageMatte(): bool
public function getImageMatteColor(): ImagickPixel
public function getImageMimeType(): string
public function getImageOrientation(): int
public function getImagePage(): array
public function getImagePixelColor(int `$x`, int `$y`): ImagickPixel
public function getImageProfile(string `$name`): string
public function getImageProfiles(string `$pattern` = "*", bool `$include_values` = `true`): array
public function getImageProperties(string `$pattern` = "*", bool `$include_values` = `true`): array
public function getImageProperty(string `$name`): string
public function getImageRedPrimary(): array
public function getImageRegion(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): Imagick
public function getImageRenderingIntent(): int
public function getImageResolution(): array
public function getImagesBlob(): string
public function getImageScene(): int
public function getImageSignature(): string
public function getImageSize(): int
public function getImageTicksPerSecond(): int
public function getImageTotalInkDensity(): float
public function getImageType(): int
public function getImageUnits(): int
public function getImageVirtualPixelMethod(): int
public function getImageWhitePoint(): array
public function getImageWidth(): int
public function getInterlaceScheme(): int
public function getIteratorIndex(): int
public function getNumberImages(): int
public function getOption(string `$key`): string
public static function getPackageName(): string
public function getPage(): array
public function getPixelIterator(): ImagickPixelIterator
public function getPixelRegionIterator(
int `$x`,
int `$y`,
int `$columns`,
int `$rows`
): ImagickPixelIterator
public function getPointSize(): float
public static function getQuantum(): int
public static function getQuantumDepth(): array
public static function getQuantumRange(): array
public static function getRegistry(string `$key`): string
public static function getReleaseDate(): string
public static function getResource(int `$type`): int
public static function getResourceLimit(int `$type`): int
public function getSamplingFactors(): array
public function getSize(): array
public function getSizeOffset(): int
public static function getVersion(): array
public function haldClutImage(Imagick `$clut`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function hasNextImage(): bool
public function hasPreviousImage(): bool
public function identifyFormat(string `$embedText`): string|false
public function identifyImage(bool `$appendRawOutput` = `false`): array
public function implodeImage(float `$radius`): bool
public function importImagePixels(
int `$x`,
int `$y`,
int `$width`,
int `$height`,
string `$map`,
int `$storage`,
array `$pixels`
): bool
public function inverseFourierTransformImage(Imagick `$complement`, bool `$magnitude`): bool
public function labelImage(string `$label`): bool
public function levelImage(
float `$blackPoint`,
float `$gamma`,
float `$whitePoint`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function linearStretchImage(float `$blackPoint`, float `$whitePoint`): bool
public function liquidRescaleImage(
int `$width`,
int `$height`,
float `$delta_x`,
float `$rigidity`
): bool
public static function listRegistry(): array
public function magnifyImage(): bool
public function mapImage(Imagick `$map`, bool `$dither`): bool
public function matteFloodfillImage(
float `$alpha`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`
): bool
public function medianFilterImage(float `$radius`): bool
public function mergeImageLayers(int `$layer_method`): Imagick
public function minifyImage(): bool
public function modulateImage(float `$brightness`, float `$saturation`, float `$hue`): bool
public function montageImage(
ImagickDraw `$draw`,
string `$tile_geometry`,
string `$thumbnail_geometry`,
int `$mode`,
string `$frame`
): Imagick
public function morphImages(int `$number_frames`): Imagick
public function morphology(
int `$morphologyMethod`,
int `$iterations`,
ImagickKernel `$ImagickKernel`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function mosaicImages(): Imagick
public function motionBlurImage(
float `$radius`,
float `$sigma`,
float `$angle`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function negateImage(bool `$gray`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function newImage(
int `$cols`,
int `$rows`,
mixed `$background`,
string `$format` = ?
): bool
public function newPseudoImage(int `$columns`, int `$rows`, string `$pseudoString`): bool
public function nextImage(): bool
public function normalizeImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function oilPaintImage(float `$radius`): bool
public function opaquePaintImage(
mixed `$target`,
mixed `$fill`,
float `$fuzz`,
bool `$invert`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function optimizeImageLayers(): bool
public function orderedPosterizeImage(string `$threshold_map`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function paintFloodfillImage(
mixed `$fill`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function paintOpaqueImage(
mixed `$target`,
mixed `$fill`,
float `$fuzz`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function paintTransparentImage(mixed `$target`, float `$alpha`, float `$fuzz`): bool
public function pingImage(string `$filename`): bool
public function pingImageBlob(string `$image`): bool
public function pingImageFile(resource `$filehandle`, string `$fileName` = ?): bool
public function polaroidImage(ImagickDraw `$properties`, float `$angle`): bool
public function posterizeImage(int `$levels`, bool `$dither`): bool
public function previewImages(int `$preview`): bool
public function previousImage(): bool
public function profileImage(string `$name`, string `$profile` = ?): bool
public function quantizeImage(
int `$numberColors`,
int `$colorspace`,
int `$treedepth`,
bool `$dither`,
bool `$measureError`
): bool
public function quantizeImages(
int `$numberColors`,
int `$colorspace`,
int `$treedepth`,
bool `$dither`,
bool `$measureError`
): bool
public function queryFontMetrics(ImagickDraw `$properties`, string `$text`, bool `$multiline` = ?): array
public static function queryFonts(string `$pattern` = "*"): array
public static function queryFormats(string `$pattern` = "*"): array
public function radialBlurImage(float `$angle`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function raiseImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`,
bool `$raise`
): bool
public function randomThresholdImage(float `$low`, float `$high`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function readImage(string `$filename`): bool
public function readImageBlob(string `$image`, string `$filename` = ?): bool
public function readImageFile(resource `$filehandle`, string `$fileName` = `null`): bool
public function readImages(array `$filenames`): bool
public function recolorImage(array `$matrix`): bool
public function reduceNoiseImage(float `$radius`): bool
public function remapImage(Imagick `$replacement`, int `$DITHER`): bool
public function removeImage(): bool
public function removeImageProfile(string `$name`): string
public function render(): bool
public function resampleImage(
float `$x_resolution`,
float `$y_resolution`,
int `$filter`,
float `$blur`
): bool
public function resetImagePage(string `$page`): bool
public function resizeImage(
int `$columns`,
int `$rows`,
int `$filter`,
float `$blur`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool
public function rollImage(int `$x`, int `$y`): bool
public function rotateImage(mixed `$background`, float `$degrees`): bool
public function rotationalBlurImage(float `$angle`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function roundCorners(
float `$x_rounding`,
float `$y_rounding`,
float `$stroke_width` = 10,
float `$displace` = 5,
float `$size_correction` = -6
): bool
public function sampleImage(int `$columns`, int `$rows`): bool
public function scaleImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool
public function segmentImage(
int `$COLORSPACE`,
float `$cluster_threshold`,
float `$smooth_threshold`,
bool `$verbose` = `false`
): bool
public function selectiveBlurImage(
float `$radius`,
float `$sigma`,
float `$threshold`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function separateImageChannel(int `$channel`): bool
public function sepiaToneImage(float `$threshold`): bool
public function setBackgroundColor(mixed `$background`): bool
public function setColorspace(int `$COLORSPACE`): bool
public function setCompression(int `$compression`): bool
public function setCompressionQuality(int `$quality`): bool
public function setFilename(string `$filename`): bool
public function setFirstIterator(): bool
public function setFont(string `$font`): bool
public function setFormat(string `$format`): bool
public function setGravity(int `$gravity`): bool
public function setImage(Imagick `$replace`): bool
public function setImageAlphaChannel(int `$mode`): bool
public function setImageArtifact(string `$artifact`, string `$value`): bool
public function setImageAttribute(string `$key`, string `$value`): bool
public function setImageBackgroundColor(mixed `$background`): bool
public function setImageBias(float `$bias`): bool
public function setImageBiasQuantum(float `$bias`): void
public function setImageBluePrimary(float `$x`, float `$y`): bool
public function setImageBorderColor(mixed `$border`): bool
public function setImageChannelDepth(int `$channel`, int `$depth`): bool
public function setImageClipMask(Imagick `$clip_mask`): bool
public function setImageColormapColor(int `$index`, ImagickPixel `$color`): bool
public function setImageColorspace(int `$colorspace`): bool
public function setImageCompose(int `$compose`): bool
public function setImageCompression(int `$compression`): bool
public function setImageCompressionQuality(int `$quality`): bool
public function setImageDelay(int `$delay`): bool
public function setImageDepth(int `$depth`): bool
public function setImageDispose(int `$dispose`): bool
public function setImageExtent(int `$columns`, int `$rows`): bool
public function setImageFilename(string `$filename`): bool
public function setImageFormat(string `$format`): bool
public function setImageGamma(float `$gamma`): bool
public function setImageGravity(int `$gravity`): bool
public function setImageGreenPrimary(float `$x`, float `$y`): bool
public function setImageIndex(int `$index`): bool
public function setImageInterlaceScheme(int `$interlace_scheme`): bool
public function setImageInterpolateMethod(int `$method`): bool
public function setImageIterations(int `$iterations`): bool
public function setImageMatte(bool `$matte`): bool
public function setImageMatteColor(mixed `$matte`): bool
public function setImageOpacity(float `$opacity`): bool
public function setImageOrientation(int `$orientation`): bool
public function setImagePage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function setImageProfile(string `$name`, string `$profile`): bool
public function setImageProperty(string `$name`, string `$value`): bool
public function setImageRedPrimary(float `$x`, float `$y`): bool
public function setImageRenderingIntent(int `$rendering_intent`): bool
public function setImageResolution(float `$x_resolution`, float `$y_resolution`): bool
public function setImageScene(int `$scene`): bool
public function setImageTicksPerSecond(int `$ticks_per_second`): bool
public function setImageType(int `$image_type`): bool
public function setImageUnits(int `$units`): bool
public function setImageVirtualPixelMethod(int `$method`): bool
public function setImageWhitePoint(float `$x`, float `$y`): bool
public function setInterlaceScheme(int `$interlace_scheme`): bool
public function setIteratorIndex(int `$index`): bool
public function setLastIterator(): bool
public function setOption(string `$key`, string `$value`): bool
public function setPage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function setPointSize(float `$point_size`): bool
public function setProgressMonitor(callable `$callback`): bool
public static function setRegistry(string `$key`, string `$value`): bool
public function setResolution(float `$x_resolution`, float `$y_resolution`): bool
public static function setResourceLimit(int `$type`, int `$limit`): bool
public function setSamplingFactors(array `$factors`): bool
public function setSize(int `$columns`, int `$rows`): bool
public function setSizeOffset(int `$columns`, int `$rows`, int `$offset`): bool
public function setType(int `$image_type`): bool
public function shadeImage(bool `$gray`, float `$azimuth`, float `$elevation`): bool
public function shadowImage(
float `$opacity`,
float `$sigma`,
int `$x`,
int `$y`
): bool
public function sharpenImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function shaveImage(int `$columns`, int `$rows`): bool
public function shearImage(mixed `$background`, float `$x_shear`, float `$y_shear`): bool
public function sigmoidalContrastImage(
bool `$sharpen`,
float `$alpha`,
float `$beta`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function sketchImage(float `$radius`, float `$sigma`, float `$angle`): bool
public function smushImages(bool `$stack`, int `$offset`): Imagick
public function solarizeImage(int `$threshold`): bool
public function sparseColorImage(int `$SPARSE_METHOD`, array `$arguments`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function spliceImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function spreadImage(float `$radius`): bool
public function statisticImage(
int `$type`,
int `$width`,
int `$height`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function steganoImage(Imagick `$watermark_wand`, int `$offset`): Imagick
public function stereoImage(Imagick `$offset_wand`): bool
public function stripImage(): bool
public function subImageMatch(Imagick `$Imagick`, array `&$offset` = ?, float `&$similarity` = ?): Imagick
function swirlImage(float `$degrees`): bool
function textureImage(Imagick `$texture_wand`): Imagick
public function thresholdImage(float `$threshold`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function thumbnailImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$fill` = `false`,
bool `$legacy` = `false`
): bool
public function tintImage(mixed `$tint`, mixed `$opacity`, bool `$legacy` = `false`): bool
public function __toString(): string
public function transformImage(string `$crop`, string `$geometry`): Imagick
public function transformImageColorspace(int `$colorspace`): bool
public function transparentPaintImage(
mixed `$target`,
float `$alpha`,
float `$fuzz`,
bool `$invert`
): bool
public function transposeImage(): bool
public function transverseImage(): bool
public function trimImage(float `$fuzz`): bool
public function uniqueImageColors(): bool
public function unsharpMaskImage(
float `$radius`,
float `$sigma`,
float `$amount`,
float `$threshold`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function valid(): bool
public function vignetteImage(
float `$blackPoint`,
float `$whitePoint`,
int `$x`,
int `$y`
): bool
public function waveImage(float `$amplitude`, float `$length`): bool
public function whiteThresholdImage(mixed `$threshold`): bool
public function writeImage(string `$filename` = NULL): bool
public function writeImageFile(resource `$filehandle`, string `$format` = ?): bool
public function writeImages(string `$filename`, bool `$adjoin`): bool
public function writeImagesFile(resource `$filehandle`, string `$format` = ?): bool
}

## Métodos de imagem e métodos globais

A classe Imagick tem a capacidade de armazenar e operar em múltiplas imagens simultaneamente. Isto é conseguido através de uma pilha interna. Sempre existe um ponteiro interno que aponta para a imagem atual. Algumas funções operam em todas as imagens da classe Imagick, mas a maioria opera apenas na imagem atual da pilha interna. Por convenção, os nomes dos métodos podem conter a palavra Image para indicar que afetam apenas a imagem atual na pilha.

## Métodos da classe

Como existem muitos métodos, aqui está uma lista útil de métodos, reduzida para propósito geral:

Métodos da classe por propósito
Efeitos de imagem | Métodos de obtenção | Métodos de definição | Ler/gravar imagens | Outros
--- | --- | --- | --- | ---
Imagick::adaptiveBlurImage() | Imagick::getCompression() | Imagick::setBackgroundColor() | Imagick::__construct() | Imagick::clear()
Imagick::adaptiveResizeImage() | Imagick::getFilename() | Imagick::setCompressionQuality() | Imagick::addImage() | Imagick::clone()
Imagick::adaptiveSharpenImage() | Imagick::getFormat() | Imagick::setCompression() | Imagick::appendImages() | Imagick::current()
Imagick::adaptiveThresholdImage() | Imagick::getImageBackgroundColor() | Imagick::setFilename() | Imagick::getFilename() | Imagick::destroy()
Imagick::addNoiseImage() | Imagick::getImageBlob() | Imagick::getImagesBlob() | Imagick::setFormat() | Imagick::getFormat()
Imagick::affinetransformimage() | Imagick::getImageBluePrimary() | Imagick::setImageBackgroundColor() | Imagick::getImageFilename() | Imagick::getHomeURL()
Imagick::annotateImage() | Imagick::getImageBorderColor() | Imagick::setFirstIterator() | Imagick::getImageFormat() | Imagick::commentImage()
Imagick::averageImages() | Imagick::getImageChannelDepth() | Imagick::setImageBias() | Imagick::getImage() | Imagick::getNumberImages()
Imagick::blackThresholdImage() | Imagick::getImageChannelDistortion() | Imagick::setImageBluePrimary() | Imagick::setImageFilename() | Imagick::getReleaseDate()
Imagick::blurImage() | Imagick::getImageChannelExtrema() | Imagick::setImageBorderColor() | Imagick::setImageFormat() | Imagick::getVersion()
Imagick::borderImage() | Imagick::getImageChannelMean() | Imagick::setImageChannelDepth() | Imagick::readImageFile() | Imagick::hasNextImage()
Imagick::charcoalImage() | Imagick::getImageChannelStatistics() | Imagick::setImageColormapColor() | Imagick::readImage() | Imagick::hasPreviousImage()
Imagick::chopImage() | Imagick::getImageColormapColor() | Imagick::setImageColorSpace() | Imagick::writeImages() | Imagick::labelImage()
Imagick::clipImage() | Imagick::getImageColorspace() | Imagick::setImageCompose() | Imagick::writeImage() | Imagick::newImage()
Imagick::clipPathImage() | Imagick::getImageColors() | Imagick::setImageCompression() |  | Imagick::newPseudoImage()
Imagick::coalesceImages() | Imagick::getImageCompose() | Imagick::setImageDelay() |  | Imagick::nextImage()
Imagick::colorFloodFillImage() | Imagick::getImageDelay() | Imagick::setImageDepth() |  | Imagick::pingImageBlob()
Imagick::colorizeImage() | Imagick::getImageDepth() | Imagick::setImageDispose() |  | Imagick::pingImageFile()
Imagick::combineImages() | Imagick::getImageDispose() | Imagick::setImageDispose() |  | Imagick::pingImage()
Imagick::compareImageChannels() | Imagick::getImageDistortion() | Imagick::setImageExtent() |  | Imagick::previousImage()
Imagick::compareImageLayers() | Imagick::getImageExtrema() | Imagick::setImageFilename() |  | Imagick::profileImage()
Imagick::compositeImage() | Imagick::getImageFilename() | Imagick::setImageFormat() |  | Imagick::queryFormats()
Imagick::contrastImage() | Imagick::getImageFormat() | Imagick::setImageGamma() |  | Imagick::removeImageProfile()
Imagick::contrastStretchImage() | Imagick::getImageGamma() | Imagick::setImageGreenPrimary() |  | Imagick::removeImage()
Imagick::convolveImage() | Imagick::getImageGeometry() | Imagick::setImageIndex() |  | Imagick::setFirstIterator()
Imagick::cropImage() | Imagick::getImageGreenPrimary() | Imagick::setImageInterpolateMethod() |  | Imagick::setImageIndex()
Imagick::cycleColormapImage() | Imagick::getImageHeight() | Imagick::setImageIterations() |  | Imagick::valid()
Imagick::deconstructImages() | Imagick::getImageHistogram() | Imagick::setImageMatteColor() |  | Imagick::getCopyright()
Imagick::drawImage() | Imagick::getImageIndex() | Imagick::setImageMatte() |  |
Imagick::edgeImage() | Imagick::getImageInterlaceScheme() | Imagick::setImagePage() |  |
Imagick::embossImage() | Imagick::getImageInterpolateMethod() | Imagick::setImageProfile() |  |
Imagick::enhanceImage() | Imagick::getImageIterations() | Imagick::setImageProperty() |  |
Imagick::equalizeImage() | Imagick::getImageMatteColor() | Imagick::setImageRedPrimary() |  |
Imagick::evaluateImage() | Imagick::getImageMatte() | Imagick::setImageRenderingIntent() |  |
Imagick::flattenImages() | Imagick::getImagePage() | Imagick::setImageResolution() |  |
Imagick::flipImage() | Imagick::getImagePixelColor() | Imagick::setImageScene() |  |
Imagick::flopImage() | Imagick::getImageProfile() | Imagick::setImageTicksPerSecond() |  |
| Imagick::getImageProperty() | Imagick::setImageType() |  |
Imagick::fxImage() | Imagick::getImageRedPrimary() | Imagick::setImageUnits() |  |
Imagick::gammaImage() | Imagick::getImageRegion() | Imagick::setImageVirtualPixelMethod() |  |
Imagick::gaussianBlurImage() | Imagick::getImageRenderingIntent() | Imagick::setImageWhitepoint() |  |
Imagick::implodeImage() | Imagick::getImageResolution() | Imagick::setInterlaceScheme() |  |
Imagick::levelImage() | Imagick::getImageScene() | Imagick::setOption() |  |
Imagick::linearStretchImage() | Imagick::getImageSignature() | Imagick::setPage() |  |
Imagick::magnifyImage() | Imagick::getImageTicksPerSecond() | Imagick::setResolution() |  |
Imagick::matteFloodFillImage() | Imagick::getImageTotalInkDensity() | Imagick::setResourceLimit() |  |
Imagick::medianFilterImage() | Imagick::getImageType() | Imagick::setSamplingFactors() |  |
Imagick::minifyImage() | Imagick::getImageUnits() | Imagick::setSizeOffset() |  |
Imagick::modulateImage() | Imagick::getImageVirtualPixelMethod() | Imagick::setSize() |  |
Imagick::montageImage() | Imagick::getImageWhitepoint() | Imagick::setType() |  |
Imagick::morphImages() | Imagick::getImageWidth() |  |  |
Imagick::mosaicImages() | Imagick::getImage() |  |  |
Imagick::motionBlurImage() | Imagick::getInterlaceScheme() |  |  |
Imagick::negateImage() | Imagick::getNumberImages() |  |  |
Imagick::normalizeImage() | Imagick::getOption() |  |  |
Imagick::oilPaintImage() | Imagick::getPackageName() |  |  |
Imagick::optimizeImageLayers() | Imagick::getPage() |  |  |
Imagick::paintOpaqueImage() | Imagick::getPixelIterator() |  |  |
Imagick::paintTransparentImage() | Imagick::getPixelRegionIterator() |  |  |
Imagick::posterizeImage() | Imagick::getQuantumDepth() |  |  |
Imagick::radialBlurImage() | Imagick::getQuantumRange() |  |  |
Imagick::raiseImage() | Imagick::getResourceLimit() |  |  |
Imagick::randomThresholdImage() | Imagick::getResource() |  |  |
Imagick::reduceNoiseImage() | Imagick::getSamplingFactors() |  |  |
Imagick::render() | Imagick::getSizeOffset() |  |  |
Imagick::resampleImage() | Imagick::getSize() |  |  |
Imagick::resizeImage() | Imagick::identifyImage() |  |  |
Imagick::rollImage() | Imagick::getImageSize() |  |  |
Imagick::rotateImage() |  |  |  |
Imagick::sampleImage() |  |  |  |
Imagick::scaleImage() |  |  |  |
Imagick::separateImageChannel() |  |  |  |
Imagick::sepiaToneImage() |  |  |  |
Imagick::shadeImage() |  |  |  |
Imagick::shadowImage() |  |  |  |
Imagick::sharpenImage() |  |  |  |
Imagick::shaveImage() |  |  |  |
Imagick::shearImage() |  |  |  |
Imagick::sigmoidalContrastImage() |  |  |  |
Imagick::sketchImage() |  |  |  |
Imagick::solarizeImage() |  |  |  |
Imagick::spliceImage() |  |  |  |
Imagick::spreadImage() |  |  |  |
Imagick::steganoImage() |  |  |  |
Imagick::stereoImage() |  |  |  |
Imagick::stripImage() |  |  |  |
Imagick::swirlImage() |  |  |  |
Imagick::textureImage() |  |  |  |
Imagick::thresholdImage() |  |  |  |
Imagick::thumbnailImage() |  |  |  |
Imagick::tintImage() |  |  |  |
Imagick::transverseImage() |  |  |  |
Imagick::trimImage() |  |  |  |
Imagick::uniqueImageColors() |  |  |  |
Imagick::unsharpMaskImage() |  |  |  |
Imagick::vignetteImage() |  |  |  |
Imagick::waveImage() |  |  |  |
Imagick::whiteThresholdImage() |  |  |  |

# Imagick::adaptiveBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveBlurImage — Adiciona filtro de desfoque adaptável à imagem

### Descrição

public function Imagick::adaptiveBlurImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Adiciona um filtro de desfoque adaptável à imagem. A intensidade de um desfoque adaptativo diminui drasticamente na borda da imagem, enquanto um desfoque padrão é uniforme em toda a imagem. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.

### Parâmetros

`radius`

  O raio do desfoque gaussiano, em pixels, sem contar o pixel central. Forneça um valor 0 e o raio será escolhido automagicamente.

`sigma`

  O desvio padrão do desfoque gaussiano, em pixels.

`channel`

  Fornece qualquer constante de canal que seja válida no modo de canal. Para aplicar a mais de um canal, constantes de canal devem ser combinadas usando operadores bit a bit. O padrão é `Imagick::CHANNEL_DEFAULT`. Consulte esta lista de constantes de canal

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Usando Imagick::adaptiveBlurImage():

Desfoca uma imagem de forma adaptativa e depois exibe-a no navegador.

    <?php

    header('Content-type: image/jpeg');

    $image = new Imagick('test.jpg');

    $image->adaptiveBlurImage(5,3);
    echo $image;

    ?>

O exemplo acima produzirá algo semelhante a:

### Veja Também

- Imagick::blurImage() - Adiciona filtro de desfoque à imagem
- Imagick::motionBlurImage() - Simula desfoque de movimento
- Imagick::radialBlurImage() - Desfoca uma imagem de forma radial

# Imagick::adaptiveResizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveResizeImage — Redimensiona imagem de forma adaptativa com triangulação dependente de dados

### Descrição

public function Imagick::adaptiveResizeImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool

Redimensiona a imagem de forma adaptativa com triangulação dependente de dados. Evita o desfoque em mudanças súbitas de cores. Mais útil quando usado para reduzir imagens ligeiramente para um "tamanho da web"; pode não parecer bom quando uma imagem em tamanho real é redimensionada de forma adaptativa para uma miniatura. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.

> Nota: O comportamento do parâmetro `bestfit` mudou na Imagick 3.0.0. Antes desta versão, dadas as dimensões 400x400, uma imagem de dimensões 200x150 permaneceria intocada. Na Imagick 3.0.0 e superiores, a imagem será escalada para 400x300, pois este é o "melhor ajuste" para as dimensões fornecidas. Se o parâmetro `bestfit` for usado, tanto a largura quanto a altura devem ser informadas.

### Parâmetros

`columns`

  O número de colunas na imagem dimensionada.

`rows`

  O número de linhas na imagem dimensionada.

`bestfit`

  Define se a imagem deve ser ajustada dentro de uma caixa delimitadora.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL imagick 2.1.0 | Adicionado o parâmetro opcional bestfit.
PECL imagick 2.1.0 | Este método agora suporta redimensionamento proporcional. Passe zero como um dos parâmetros para redimensionamento proporcional.

### Exemplos

Exemplo #1 Usando Imagick::adaptiveResizeImage()

Redimensiona uma imagem para um tamanho padrão para a web. Este método funciona melhor ao redimensionar para um tamanho ligeiramente menor que o tamanho da imagem anterior.

    <?php
    header('Content-type: image/jpeg');

    $image = new Imagick('image.jpg');
    $image->adaptiveResizeImage(1024,768);

    echo $image;
    ?>

### Veja Também

- Imagick::chopImage() - Remove uma região de uma imagem e corta
- Imagick::cropImage() - Extrai uma região da imagem
- Imagick::magnifyImage() - Dimensiona uma imagem proporcionalmente 2x
- Imagick::minifyImage() - Dimensiona uma imagem proporcionalmente à metade do seu tamanho
- Imagick::resizeImage() - Dimensiona uma imagem
- Imagick::scaleImage() - Dimensiona o tamanho de uma imagem
- Imagick::shaveImage() - Raspa pixels das bordas da imagem
- Imagick::thumbnailImage() - Altera o tamanho de uma imagem
- Imagick::trimImage() - Apara as bordas da imagem

# Imagick::adaptiveSharpenImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveSharpenImage — Aumenta a nitidez da imagem de forma adaptativa

### Descrição

public function Imagick::adaptiveSharpenImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Aumente a nitidez da imagem de forma adaptativa, aumentando a nitidez mais intensamente perto das bordas da imagem e menos intensamente longe das bordas. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.

### Parâmetros

`radius`

  O raio do gaussiano, em pixels, sem contar o pixel central. Use 0 para seleção automática.

`sigma`

  O desvio padrão do gaussiano, em pixels.

`channel`

  Fornece qualquer constante de canal que seja válida no modo de canal. Para aplicar a mais de um canal, constantes de canal devem ser combinadas usando operadores bit a bit. O padrão é `Imagick::CHANNEL_DEFAULT`. Consulte esta lista de constantes de canal

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Um exemplo de Imagick::adaptiveSharpenImage()

Aumente a nitidez da imagem de forma adaptativa com raio 2 e sigma 1.

    <?php
    try {
        $image = new Imagick('image.png');
        $image->adaptiveSharpenImage(2,1);
    } catch(ImagickException $e) {
        echo 'Error: ' , $e->getMessage();
        die();
    }
    header('Content-type: image/png');
    echo $image;
    ?>

### Veja Também

- Imagick::sharpenImage() - Torna uma imagem mais nítida

# Imagick::adaptiveThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveThresholdImage — Seleciona um limite para cada pixel com base em uma faixa de intensidade

### Descrição

public function Imagick::adaptiveThresholdImage(int `$width`, int `$height`, int `$offset`): bool

Seleciona um limite individual para cada pixel com base na faixa de valores de intensidade em sua vizinhança local. Isto permite o limiar de uma imagem cujo histograma de intensidade global não contém picos distintos.

### Parâmetros

`width`

  Largura da vizinhança local.

`height`

  Altura da vizinhança local.

`offset`

  O deslocamento médio.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::adaptiveThresholdImage()

    <?php
    function adaptiveThresholdImage($imagePath, $width, $height, $adaptiveOffset) {
        $imagick = new \Imagick(realpath($imagePath));
        $adaptiveOffsetQuantum = intval($adaptiveOffset * \Imagick::getQuantum());
        $imagick->adaptiveThresholdImage($width, $height, $adaptiveOffsetQuantum);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::addImage

(PECL imagick 2, PECL imagick 3)

Imagick::addImage — Adiciona nova imagem à lista de imagens de objetos Imagick

### Descrição

public function Imagick::addImage(Imagick `$source`): bool

Adiciona uma nova imagem ao objeto Imagick a partir da posição atual do objeto de origem. Após a operação, a posição do iterador é movida para o final da lista.

### Parâmetros

`source`

  O objeto Imagick de origem.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::addNoiseImage

(PECL imagick 2, PECL imagick 3)

Imagick::addNoiseImage — Adiciona ruído aleatório à imagem

### Descrição

public function Imagick::addNoiseImage(int `$noise_type`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Adiciona ruído aleatório à imagem.

### Parâmetros

`noise_type`

  O tipo de ruído. Consulte esta lista de constantes de ruído.

`channel`

  Fornece qualquer constante de canal que seja válida no modo de canal. Para aplicar a mais de um canal, constantes de canal devem ser combinadas usando operadores bit a bit. O padrão é `Imagick::CHANNEL_DEFAULT`. Consulte esta lista de constantes de canal

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::addNoiseImage()

    <?php
    function addNoiseImage($noiseType, $imagePath, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->addNoiseImage($noiseType, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::affineTransformImage

(PECL imagick 2, PECL imagick 3)

Imagick::affineTransformImage — Transforma uma imagem

### Descrição

public function Imagick::affineTransformImage(ImagickDraw `$matrix`): bool

Transforma uma imagem conforme ditado pela matriz afim.

### Parâmetros

`matrix`

  A matriz afim.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::affineTransformImage()

    <?php
    function affineTransformImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $draw = new \ImagickDraw();

        $angle = deg2rad(40);

        $affineRotate = array(
            "sx" => cos($angle), "sy" => cos($angle),
            "rx" => sin($angle), "ry" => -sin($angle),
            "tx" => 0, "ty" => 0,
        );

        $draw->affine($affineRotate);

        $imagick->affineTransformImage($draw);

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::animateImages

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::animateImages — Anima uma imagem ou imagens

### Descrição

public function Imagick::animateImages(string `$x_server`): bool

Este método anima a imagem em um servidor X local ou remoto. Este método não está disponível no Windows. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.6 ou superior.

### Parâmetros

`x_server`

  Endereço do servidor X.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Veja Também

- Imagick::displayImage() - Exibe uma imagem

# Imagick::annotateImage

(PECL imagick 2, PECL imagick 3)

Imagick::annotateImage — Cria anotação em uma imagem com texto

### Descrição

public function Imagick::annotateImage(
ImagickDraw `$draw_settings`,
float `$x`,
float `$y`,
float `$angle`,
string `$text`
): bool

Cria anotação em imagem com texto.

### Parâmetros

`draw_settings`

  O objeto ImagickDraw que contém configurações para desenhar o texto

`x`

  Deslocamento horizontal em pixels à esquerda do texto

`y`

  Deslocamento vertical em pixels até a linha de base do texto

`angle`

  O ângulo em que o texto deve ser escrito

`text`

  A string a ser desenhada

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Usando Imagick::annotateImage():

Anotando texto em uma imagem vazia

    <?php
    /* Cria alguns objetos */
    $image = new Imagick();
    $draw = new ImagickDraw();
    $pixel = new ImagickPixel( 'gray' );

    /* Nova imagem */
    $image->newImage(800, 75, $pixel);

    /* Texto preto */
    $draw->setFillColor('black');

    /* Propriedades da fonte */
    $draw->setFont('Bookman-DemiItalic');
    $draw->setFontSize( 30 );

    /* Cria texto */
    $image->annotateImage($draw, 10, 45, 0, 'The quick brown fox jumps over the lazy dog');

    /* Dá um formato à imagem */
    $image->setImageFormat('png');

    /* Mostra a imagem com cabeçalho */
    header('Content-type: image/png');
    echo $image;

    ?>

### Veja Também

- ImagickDraw::annotation() - Desenha texto na imagem
- ImagickDraw::setFont() - Define a fonte totalmente especificada a ser usada ao fazer anotações com texto

# Imagick::appendImages

(PECL imagick 2, PECL imagick 3)

Imagick::appendImages — Anexa um conjunto de imagens

### Descrição

public function Imagick::appendImages(bool `$stack`): Imagick

Acrescenta um conjunto de imagens em uma imagem maior.

### Parâmetros

`stack`

  Informa se as imagens devem ser empilhadas verticalmente. Por padrão (ou se `false` for especificado), as imagens são empilhadas da esquerda para a direita. Se `stack` for `true`, as imagens serão empilhadas de cima para baixo.

### Valor Retornado

Retorna uma instância Imagick em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::appendImages()

    <?php

    /* Cria um novo objeto Imagick */
    $im = new Imagick();

    /* cria imagens com vermelho, verde e azul */
    $im->newImage(100, 50, "red");
    $im->newImage(100, 50, "green");
    $im->newImage(100, 50, "blue");

    /* Anexa as imagens em uma */
    $im->resetIterator();
    $combined = $im->appendImages(true);

    /* Mostra a imagem */
    $combined->setImageFormat("png");
    header("Content-Type: image/png");
    echo $combined;
    ?>

O exemplo acima produzirá algo semelhante a:

# Imagick::autoLevelImage

(PECL imagick 3 >= 3.3.0)

Imagick::autoLevelImage — Ajusta os níveis de um canal de imagem específico

### Descrição

public function Imagick::autoLevelImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Ajusta os níveis de um canal de imagem específico, dimensionando os valores mínimo e máximo para toda a faixa Quantum.

### Parâmetros

`channel`

  Em qual canal o nivelamento automático deve ser feito.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::autoLevelImage()

    <?php
    function autoLevelImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->autoLevelImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::averageImages

(PECL imagick 2, PECL imagick 3)

Imagick::averageImages — Tira a média de um conjunto de imagens

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::averageImages(): Imagick

Tira a média de um conjunto de imagens.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um novo objeto Imagick em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::blackThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::blackThresholdImage — Força todos os pixels abaixo do limite para preto

### Descrição

public function Imagick::blackThresholdImage(mixed `$threshold`): bool

É como Imagick::thresholdImage() mas força todos os pixels abaixo do limite para preto, deixando todos os pixels acima do limite inalterados.

### Parâmetros

`threshold`

  O limite abaixo do qual tudo fica preto

### Valor Retornado

Retorna `true` em caso de sucesso.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL imagick 2.1.0 | Agora permite uma string representando a cor como parâmetro. As versões anteriores permitiam apenas um objeto ImagickPixel.

### Exemplos

Exemplo #1 Exemplo de Imagick::blackThresholdImage()

    <?php
    function blackThresholdImage($imagePath, $thresholdColor) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->blackthresholdimage($thresholdColor);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::blueShiftImage

(PECL imagick 3 >= 3.3.0)

Imagick::blueShiftImage — Silencia as cores da imagem

### Descrição

public function Imagick::blueShiftImage(float `$factor` = 1.5): bool

Silencia as cores da imagem para simular uma cena noturna sob o luar.

### Parâmetros

`factor`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::blueShiftImage()

    <?php
    function blueShiftImage($imagePath, $blueShift) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->blueShiftImage($blueShift);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::blurImage

(PECL imagick 2, PECL imagick 3)

Imagick::blurImage — Adiciona filtro de desfoque à imagem

### Descrição

public function Imagick::blurImage(float `$radius`, float `$sigma`, int `$channel` = ?): bool

Adiciona filtro de desfoque à imagem. Terceiro parâmetro opcional para desfocar um canal específico.

### Parâmetros

`radius`

  Raio de desfoque

`sigma`

  Desvio padrão

`channel`

  A constante de tipo de canal. Quando não fornecida, todos os canais são desfocados.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Usando Imagick::blurImage():

Desfoca uma image e mostra no navegador.

    <?php

    header('Content-type: image/jpeg');

    $image = new Imagick('test.jpg');

    $image->blurImage(5,3);
    echo $image;

    ?>

### Veja Também

- Imagick::adaptiveBlurImage() - Adiciona filtro de desfoque adaptável à imagem
- Imagick::motionBlurImage() - Simula desfoque de movimento
- Imagick::radialBlurImage() - Desfoca uma imagem de forma radial

# Imagick::borderImage

(PECL imagick 2, PECL imagick 3)

Imagick::borderImage — Envolve a imagem com uma borda

### Descrição

public function Imagick::borderImage(mixed `$bordercolor`, int `$width`, int `$height`): bool

Envolve a imagem com uma borda da cor definida pelo objeto bordercolor ImagickPixel.

### Parâmetros

`bordercolor`

  Objeto ImagickPixel ou uma string contendo a cor da borda

`width`

  Largura da borda

`height`

  Altura da borda

### Valor Retornado

Retorna `true` em caso de sucesso.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL imagick 2.1.0 | Agora permite uma string representando a cor como primeiro parâmetro. As versões anteriores permitiam apenas um objeto ImagickPixel.

### Exemplos

Exemplo #1 Exemplo de Imagick::borderImage()

    <?php
    function borderImage($imagePath, $color, $width, $height) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->borderImage($color, $width, $height);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::brightnessContrastImage

(PECL imagick 3 >= 3.3.0)

Imagick::brightnessContrastImage — Altera o brilho e/ou contraste de uma imagem

### Descrição

public function Imagick::brightnessContrastImage(float `$brightness`, float `$contrast`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Altera o brilho e/ou contraste de uma imagem. Converte os parâmetros de brilho e contraste em inclinação e interceptação e chama uma função polinomial para aplicar à imagem.

### Parâmetros

`brightness`

`contrast`

`channel`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::brightnessContrastImage()

    <?php
    function brightnessContrastImage($imagePath, $brightness, $contrast, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->brightnessContrastImage($brightness, $contrast, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::charcoalImage

(PECL imagick 2, PECL imagick 3)

Imagick::charcoalImage — Simula um desenho a carvão

### Descrição

public function Imagick::charcoalImage(float `$radius`, float `$sigma`): bool

Simula um desenho a carvão.

### Parâmetros

`radius`

  O raio do gaussiano, em pixels, sem contar o pixel central

`sigma`

  O desvio padrão do gaussiano, em pixels

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::charcoalImage()

    <?php
    function charcoalImage($imagePath, $radius, $sigma) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->charcoalImage($radius, $sigma);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::chopImage

(PECL imagick 2, PECL imagick 3)

Imagick::chopImage — Remove uma região de uma imagem e corta

### Descrição

public function Imagick::chopImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Remove uma região de uma imagem e colapsa a imagem para ocupar a parte removida.

### Parâmetros

`width`

  Largura da área cortada

`height`

  Altura da área cortada

`x`

  X da origem da área cortada

`y`

  Y da origem da área cortada

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Usando Imagick::chopImage():

Exemplo de uso de Imagick::chopImage

    <?php
    /* Cria alguns objetos */
    $image = new Imagick();
    $pixel = new ImagickPixel( 'gray' );

    /* Nova imagem */
    $image->newImage(400, 200, $pixel);

    /* Corta a imagem */
    $image->chopImage(200, 200, 0, 0);

    /* Seleciona formato da imagem */
    $image->setImageFormat('png');

    /* Mostra a imagem com cabeçalho */
    header('Content-type: image/png');
    echo $image;

    ?>

### Veja Também

- Imagick::cropImage() - Extrai uma região da imagem

# Imagick::clampImage

(PECL imagick 3 >= 3.3.0)

Imagick::clampImage — Restringe a faixa de cores de 0 à profundidade do Quantum

### Descrição

public function Imagick::clampImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Restringe a faixa de cores de 0 à profundidade do Quantum.

### Parâmetros

`channel`

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# Imagick::clear

(PECL imagick 2, PECL imagick 3)

Imagick::clear — Limpa todos os recursos associados ao objeto Imagick

### Descrição

public function Imagick::clear(): bool

Limpa todos os recursos associados ao objeto Imagick.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::clipImage

(PECL imagick 2, PECL imagick 3)

Imagick::clipImage — Recorta ao longo do primeiro caminho do perfil 8BIM

### Descrição

public function Imagick::clipImage(): bool

Recorta ao longo do primeiro caminho do perfil 8BIM, se estiver presente.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::clipImagePath

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::clipImagePath — Recorta ao longo dos caminhos nomeados do perfil 8BIM, se presente

### Descrição

public function Imagick::clipImagePath(string `$pathname`, string `$inside`): void

Recorta ao longo dos caminhos nomeados do perfil 8BIM, se presente. As operações posteriores entram em vigor dentro do caminho. Pode ser um número se precedido de #, para trabalhar em um caminho numerado, por exemplo, "#1" para usar o primeiro caminho.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`pathname`

`inside`

### Valor Retornado

# Imagick::clipPathImage

(PECL imagick 2, PECL imagick 3)

Imagick::clipPathImage — Recorta ao longo dos caminhos nomeados do perfil 8BIM

### Descrição

public function Imagick::clipPathImage(string `$pathname`, bool `$inside`): bool

Recorta ao longo dos caminhos nomeados do perfil 8BIM, se presente. As operações posteriores entram em vigor dentro do caminho. Pode ser um número se precedido de #, para trabalhar em um caminho numerado, por exemplo, "#1" para usar o primeiro caminho.

### Parâmetros

`pathname`

  O nome do caminho

`inside`

  Se `true` as operações posteriores têm efeito dentro do caminho de recorte. Caso contrário, as operações posteriores terão efeito fora do caminho de recorte.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::clone

(PECL imagick 2, PECL imagick 3)

Imagick::clone — Faz uma cópia exata do objeto Imagick

### Descrição

public function Imagick::clone(): Imagick

Faz uma cópia exata do objeto Imagick.

Aviso

Esta função tornou-se PRETERIDA a partir do imagick 3.1.0 em favor do uso da palavra-chave clone.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Uma cópia do objeto Imagick é retornada.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL imagick 3.1.0 | Este método tornou-se preterido em favor da palavra-chave clone.

### Exemplos

Exemplo #1 Clonagem de objetos Imagick em diferentes versões do imagick

    <?php
    // Clonando um objeto Imagick no imagick versões 2.x e 3.0:
    $newImage = $image->clone();

    // Clonando um objeto Imagick a partir da versão 3.1.0:
    $newImage = clone $image;
    ?>

# Imagick::clutImage

(PECL imagick 2, PECL imagick 3)

Imagick::clutImage — Substitui cores na imagem

### Descrição

public function Imagick::clutImage(Imagick `$lookup_table`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Substitui cores na imagem a partir de uma tabela de pesquisa de cores. O segundo parâmetro opcional serve para substituir cores em um canal específico. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.6 ou superior.

### Parâmetros

`lookup_table`

  Objeto Imagick contendo a tabela de pesquisa de cores

`channel`

  A constante de tipo de canal. Se não fornecida, os canais padrão são substituídos.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Usando Imagick::clutImage():

Substitui as cores na imagem a partir de uma tabela de pesquisa de cores.

    <?php
    $image = new Imagick('test.jpg');
    $clut = new Imagick();
    $clut->newImage(1, 1, new ImagickPixel('black'));
    $image->clutImage($clut);
    $image->writeImage('test_out.jpg');
    ?>

### Veja Também

- Imagick::adaptiveBlurImage() - Adiciona filtro de desfoque adaptável à imagem
- Imagick::motionBlurImage() - Simula desfoque de movimento
- Imagick::radialBlurImage() - Desfoca uma imagem de forma radial

# Imagick::coalesceImages

(PECL imagick 2, PECL imagick 3)

Imagick::coalesceImages — Compõe um conjunto de imagens

### Descrição

public function Imagick::coalesceImages(): Imagick

Compõe um conjunto de imagens respeitando quaisquer deslocamentos de página e métodos de descarte. As sequências de animação GIF, MIFF e MNG normalmente começam com uma imagem de fundo e cada imagem subsequente varia em tamanho e deslocamento. Retorna um novo objeto Imagick onde cada imagem na sequência tem o mesmo tamanho da primeira e é composta com a próxima imagem na sequência.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um novo objeto Imagick em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::colorFloodfillImage

(PECL imagick 2, PECL imagick 3)

Imagick::colorFloodfillImage — Altera o valor da cor de qualquer pixel que corresponda ao alvo

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::colorFloodfillImage(
mixed `$fill`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`
): bool

Altera o valor da cor de qualquer pixel que corresponda ao alvo e seja um vizinho imediato.

### Parâmetros

`fill`

  Objeto ImagickPixel contendo a cor de preenchimento

`fuzz`

  A quantidade de fuzz. Por exemplo, definir fuzz para 10 e a cor vermelha em intensidades de 100 e 102, respectivamente, agora são interpretadas como a mesma cor para fins de preenchimento.

`bordercolor`

  Objeto ImagickPixel contendo a cor da borda

`x`

  X da posição inicial do preenchimento

`y`

  Y da posição inicial do preenchimento

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL imagick 2.1.0 | Agora permite uma string representando a cor como primeiro e terceiro parâmetro. As versões anteriores permitiam apenas um objeto ImagickPixel.

# Imagick::colorizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::colorizeImage — Mescla a cor de preenchimento com a imagem

### Descrição

public function Imagick::colorizeImage(mixed `$colorize`, mixed `$opacity`, bool `$legacy` = `false`): bool

Mescla a cor de preenchimento com cada pixel da imagem.

### Parâmetros

`colorize`

  Objeto ImagickPixel ou uma string contendo a cor de colorização.

`opacity`

  Objeto ImagickPixel ou um float contendo o valor de opacidade. 1.0 é totalmente opaco e 0.0 é totalmente transparente.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL imagick 2.1.0 | Agora permite uma string representando a cor como o primeiro parâmetro e um float representando o valor da opacidade como o segundo parâmetro. Versões anteriores permitiam apenas objetos ImagickPixel.

### Exemplos

Exemplo #1 Exemplo de Imagick::colorizeImage()

    <?php
    function colorizeImage($imagePath, $color, $opacity) {
        $imagick = new \Imagick(realpath($imagePath));
        $opacity = $opacity / 255.0;
        $opacityColor = new \ImagickPixel("rgba(0, 0, 0, $opacity)");
        $imagick->colorizeImage($color, $opacityColor);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::colorMatrixImage

(PECL imagick 3 >= 3.3.0)

Imagick::colorMatrixImage — Aplica transformação de cores a uma imagem

### Descrição

public function Imagick::colorMatrixImage(array `$color_matrix`): bool

Aplica transformação de cores a uma imagem. O método permite alterações de saturação, rotação de matiz, luminância para alfa e vários outros efeitos. Embora matrizes de transformação de tamanho variável possam ser usadas, normalmente é usada uma matriz 5x5 para uma imagem RGBA e 6x6 para CMYKA (ou RGBA com deslocamentos). A matriz é semelhante àquelas usadas pelo Adobe Flash, exceto que os deslocamentos estão na coluna 6 em vez da 5 (para suporte a imagens CMYKA) e os deslocamentos são normalizados (divida o deslocamento do Flash por 255).

### Parâmetros

`color_matrix`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::colorMatrixImage()

    <?php
    function colorMatrixImage($imagePath, $colorMatrix) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageOpacity(1);

        // Uma matriz de cores deve se parecer com:
        //    $colorMatrix = [
        //        1.5, 0.0, 0.0, 0.0, 0.0, -0.157,
        //        0.0, 1.0, 0.5, 0.0, 0.0, -0.157,
        //        0.0, 0.0, 1.5, 0.0, 0.0, -0.157,
        //        0.0, 0.0, 0.0, 1.0, 0.0,  0.0,
        //        0.0, 0.0, 0.0, 0.0, 1.0,  0.0,
        //        0.0, 0.0, 0.0, 0.0, 0.0,  1.0
        //    ];

        $background = new \Imagick();
        $background->newPseudoImage($imagick->getImageWidth(), $imagick->getImageHeight(),  "pattern:checkerboard");

        $background->setImageFormat('png');

        $imagick->setImageFormat('png');
        $imagick->colorMatrixImage($colorMatrix);

        $background->compositeImage($imagick, \Imagick::COMPOSITE_ATOP, 0, 0);

        header("Content-Type: image/png");
        echo $background->getImageBlob();
    }

    ?>

# Imagick::combineImages

(PECL imagick 2, PECL imagick 3)

Imagick::combineImages — Combina uma ou mais imagens em uma única imagem

### Descrição

public function Imagick::combineImages(int `$channelType`): Imagick

Combina uma ou mais imagens em uma única imagem. Os valores de escala de cinza dos pixels de cada imagem na sequência são atribuídos na ordem dos canais especificados da imagem combinada. A ordem típica seria imagem 1 => Vermelho, 2 => Verde, 3 => Azul, etc.

### Parâmetros

`channelType`

  Forneça qualquer constante de canal válida para o modo de canal. Para aplicar a mais de um canal, combine constantes de tipo de canal usando operadores bit a bit. Consulte esta lista de constantes de canal.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::commentImage

(PECL imagick 2, PECL imagick 3)

Imagick::commentImage — Adiciona um comentário à sua imagem

### Descrição

public function Imagick::commentImage(string `$comment`): bool

Adiciona um comentário à sua imagem.

### Parâmetros

`comment`

  O comentário a ser adicionado.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Usando Imagick::commentImage():

Comentando uma imagem e recuperando o comentário:

    <?php

    /* Cria um novo objeto Imagick */
    $im = new imagick();

    /* Cria uma imagem vazia */
    $im->newImage(100, 100, new ImagickPixel("red"));

    /* Adiciona comentário à imagem */
    $im->commentImage("Olá, mundo!");

    /* Mostra o comentário */
    echo $im->getImageProperty("comment");

    ?>

# Imagick::compareImageChannels

(PECL imagick 2, PECL imagick 3)

Imagick::compareImageChannels — Retorna a diferença em uma ou mais imagens

### Descrição

public function Imagick::compareImageChannels(Imagick `$image`, int `$channelType`, int `$metricType`): array

Compara uma ou mais imagens e retorna a imagem diferença.

### Parâmetros

`image`

  Objeto Imagick contendo a imagem a ser comparada.

`channelType`

  Forneça qualquer constante de canal válida para o modo de canal. Para aplicar a mais de um canal, combine constantes de tipo de canal usando operadores bit a bit. Consulte esta lista de constantes de canal.

`metricType`

  Uma das constantes de tipos de métricas.

### Valor Retornado

Array consistindo de `new_wand` e `distortion`.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::compareImageLayers

(PECL imagick 2, PECL imagick 3)

Imagick::compareImageLayers — Retorna a região delimitadora máxima entre imagens

### Descrição

public function Imagick::compareImageLayers(int `$method`): Imagick

Compara cada imagem com a próxima em uma sequência e retorna a região delimitadora máxima de quaisquer diferenças de pixels que descobre. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.

### Parâmetros

`method`

  Uma das constantes de métodos de camadas.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Usando Imagick::compareImageLayers()

Comparando camadas de imagens

    <?php
    /* cria um novo objeto Imagick */
    $im = new Imagick("test.gif");

    /* otimiza as camadas da imagem */
    $result = $im->compareImageLayers(imagick::LAYERMETHOD_COALESCE);

    /* trabalha com $result */
    ?>

### Veja Também

- Imagick::optimizeImageLayers() - Remove partes repetidas de imagens para otimizar
- Imagick::writeImages() - Grava uma imagem ou sequência de imagens
- Imagick::writeImage() - Grava uma imagem no nome de arquivo especificado

# Imagick::compareImages

(PECL imagick 2, PECL imagick 3)

Imagick::compareImages — Compara uma imagem com uma imagem reconstruída

### Descrição

public function Imagick::compareImages(Imagick `$compare`, int `$metric`): array

Retorna um array contendo uma imagem reconstruída e a diferença entre as imagens.

### Parâmetros

`compare`

  Uma imagem para comparar.

`metric`

  Forneça uma constante de tipo de métrica válida. Consulte esta lista de constantes métricas.

### Valor Retornado

Retorna um array contendo uma imagem reconstruída e a diferença entre as imagens.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Usando Imagick::compareImages():

Compara imagens e exibe a imagem reconstruída

    <?php

    $image1 = new imagick("image1.png");
    $image2 = new imagick("image2.png");

    $result = $image1->compareImages($image2, Imagick::METRIC_MEANSQUAREERROR);
    $result[0]->setImageFormat("png");

    header("Content-Type: image/png");
    echo $result[0];

    ?>

# Imagick::compositeImage

(PECL imagick 2, PECL imagick 3)

Imagick::compositeImage — Compor uma imagem em outra

### Descrição

public function Imagick::compositeImage(
Imagick `$composite_object`,
int `$composite`,
int `$x`,
int `$y`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Compõe uma imagem em outra na posição especificada. Quaisquer argumentos extras necessários para o algoritmo de composição devem ser passados ​​para setImageArtifact com 'compose:args' como o primeiro parâmetro e os dados como o segundo parâmetro.

### Parâmetros

`composite_object`

  Objeto Imagick que contém a imagem composta.

`compose`

  Operador de composição. Consulte Constantes de Operador de Composição

`x`

  A posição da coluna da imagem composta

`y`

  A posição da linha da imagem composta

`channel`

  Forneça qualquer constante de canal válida para o modo de canal. Para aplicar a mais de um canal, combine constantes de tipo de canal usando operadores bit a bit. Consulte esta lista de constantes de canal.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Usando Imagick::compositeImage():

Compõe duas imagens com o método de composição 'matemática'

    <?php

    // Equivalente a executar o comando
    // convert src1.png src2.png -compose mathematics -define compose:args="1,0,-0.5,0.5" -composite output.png

    $src1 = new \Imagick("./src1.png");
    $src2 = new \Imagick("./src2.png");

    $src1->setImageVirtualPixelMethod(Imagick::VIRTUALPIXELMETHOD_TRANSPARENT);
    $src1->setImageArtifact('compose:args', "1,0,-0.5,0.5");
    $src1->compositeImage($src2, Imagick::COMPOSITE_MATHEMATICS, 0, 0);
    $src1->writeImage("./output.png");

    ?>

### Veja Também

- Imagick::setImageArtifact() - Definir artefato de imagem

# Imagick::__construct

(PECL imagick 2, PECL imagick 3)

Imagick::__construct — O construtor Imagick

### Descrição

public function Imagick::__construct(mixed `$files` = ?)

Cria uma instância do Imagick para uma imagem ou conjunto de imagens especificado.

### Parâmetros

`files`

  O caminho para uma imagem a ser carregada ou um array de caminhos. Os caminhos podem incluir curingas para nomes de arquivos ou podem ser URLs.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::contrastImage

(PECL imagick 2, PECL imagick 3)

Imagick::contrastImage — Altera o contraste da imagem

### Descrição

public function Imagick::contrastImage(bool `$sharpen`): bool

Melhora as diferenças de intensidade entre os elementos mais claros e mais escuros da imagem. Defina a nitidez para um valor diferente de 0 para aumentar o contraste da imagem, caso contrário o contraste será reduzido.

### Parâmetros

`sharpen`

  O valor de nitidez

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::contrastImage()

    <?php
    function contrastImage($imagePath, $contrastType) {
        $imagick = new \Imagick(realpath($imagePath));
        if ($contrastType != 2) {
            $imagick->contrastImage($contrastType);
        }

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::contrastStretchImage

(PECL imagick 2, PECL imagick 3)

Imagick::contrastStretchImage — Melhora o contraste de uma imagem colorida

### Descrição

public function Imagick::contrastStretchImage(float `$black_point`, float `$white_point`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Melhora o contraste de uma imagem colorida ajustando a cor dos pixels para abranger toda a gama de cores disponíveis. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.

### Parâmetros

`black_point`

  O ponto preto.

`white_point`

  O ponto branco.

`channel`

  Forneça qualquer constante de canal válida para o modo de canal. Para aplicar a mais de um canal, combine constantes de tipo de canal usando operadores bit a bit (ex.: `Imagick::CHANNEL_ALL`). Consulte esta lista de constantes de canal.

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::convolveImage

(PECL imagick 2, PECL imagick 3)

Imagick::convolveImage — Aplica um kernel de convolução personalizado à imagem

### Descrição

public function Imagick::convolveImage(array `$kernel`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Aplica um kernel de convolução personalizado à imagem.

### Parâmetros

`kernel`

  O kernel de convolução

`channel`

  Forneça qualquer constante de canal válida para o modo de canal. Para aplicar a mais de um canal, combine constantes de tipo de canal usando operadores bit a bit. Consulte esta lista de constantes de canal.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::convolveImage()

    <?php
    function convolveImage($imagePath, $bias, $kernelMatrix) {
        $imagick = new \Imagick(realpath($imagePath));
        //$edgeFindingKernel = [-1, -1, -1, -1, 8, -1, -1, -1, -1,];
        $imagick->setImageBias($bias * \Imagick::getQuantum());
        $imagick->convolveImage($kernelMatrix);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::count

(PECL imagick 3 >= 3.3.0)

Imagick::count — Obtém o número de imagens

### Descrição

public function Imagick::count(int `$mode` = 0): int

Retorna o número de imagens.

### Parâmetros

`mode`

  Um argumento não utilizado. Atualmente existe um recurso não particularmente bem definido no PHP onde chamar count() em um objeto contável pode (ou não) exigir que este método aceite um parâmetro. Este parâmetro está aqui para estar em conformidade com a interface de Countable, mesmo que o parâmetro não seja usado.

### Valor Retornado

Retorna o número de imagens.

# Imagick::cropImage

(PECL imagick 2, PECL imagick 3)

Imagick::cropImage — Extrai uma região da imagem

### Descrição

public function Imagick::cropImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Extrai uma região da imagem.

### Parâmetros

`width`

  A largura do recorte

`height`

  A altura do recorte

`x`

  A coordenada X do canto superior esquerdo da região recortada

`y`

  A coordenada Y do canto superior esquerdo da região recortada

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::cropImage()

    <?php
    function cropImage($imagePath, $startX, $startY, $width, $height) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->cropImage($width, $height, $startX, $startY);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::cropThumbnailImage

(PECL imagick 2, PECL imagick 3)

Imagick::cropThumbnailImage — Cria uma miniatura de recorte

### Descrição

public function Imagick::cropThumbnailImage(int `$width`, int `$height`, bool `$legacy` = `false`): bool

Cria uma miniatura de tamanho fixo primeiro aumentando ou diminuindo a imagem e recortando uma área especificada a partir do centro.

### Parâmetros

`width`

  A largura da miniatura

`height`

  A altura da miniatura

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::current

(PECL imagick 2, PECL imagick 3)

Imagick::current — Retorna uma referência ao objeto Imagick atual

### Descrição

public function Imagick::current(): Imagick

Retorna referência ao objeto Imagick atual com ponteiro de imagem na sequência correta.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o próprio objeto em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::cycleColormapImage

(PECL imagick 2, PECL imagick 3)

Imagick::cycleColormapImage — Desloca o mapa de cores de uma imagem

### Descrição

public function Imagick::cycleColormapImage(int `$displace`): bool

Desloca o mapa de cores de uma imagem em um determinado número de posições. Se o mapa de cores for ciclado várias vezes, pode-se produzir um efeito psicodélico.

### Parâmetros

`displace`

  A quantidade para deslocar o mapa de cores.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::decipherImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::decipherImage — Decifra uma imagem

### Descrição

public function Imagick::decipherImage(string `$passphrase`): bool

Decifra a imagem que foi cifrada antes. A imagem deve ser criptografada usando Imagick::encipherImage(). Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.9 ou superior.

### Parâmetros

`passphrase`

  A senha

### Valor Retornado

Retorna `true` em caso de sucesso.

### Veja Também

- Imagick::encipherImage() - Cifra uma imagem

# Imagick::deconstructImages

(PECL imagick 2, PECL imagick 3)

Imagick::deconstructImages — Retorna certas diferenças de pixels entre imagens

### Descrição

public function Imagick::deconstructImages(): Imagick

Compara cada imagem com a próxima em uma sequência e retorna a região delimitadora máxima de quaisquer diferenças de pixels que encontradas.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um novo objeto Imagick em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::deleteImageArtifact

(PECL imagick 3)

Imagick::deleteImageArtifact — Excluir artefato de imagem

### Descrição

public function Imagick::deleteImageArtifact(string `$artifact`): bool

Exclui um artefato associado à imagem. A diferença entre propriedades de imagem e artefatos de imagem é que as propriedades são públicas e os artefatos são privados. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.5.7 ou superior.

### Parâmetros

`artifact`

  O nome do artefato a ser excluído

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Veja Também

- Imagick::setImageArtifact() - Definir artefato de imagem
- Imagick::getImageArtifact() - Obtém artefato da imagem

# Imagick::deleteImageProperty

(PECL imagick 3 >= 3.3.0)

Imagick::deleteImageProperty — Exclui uma propriedade de imagem

### Descrição

public function Imagick::deleteImageProperty(string `$name`): bool

Exclui uma propriedade de imagem.

### Parâmetros

`name`

  O nome da propriedade a ser excluída.

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::deskewImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3 >= 3.3.0)

Imagick::deskewImage — Remove distorção da imagem

### Descrição

public function Imagick::deskewImage(float `$threshold`): bool

Este método pode ser usado para remover distorções, por exemplo, de imagens digitalizadas onde o papel não foi colocado corretamente na superfície de digitalização. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.5 ou superior.

### Parâmetros

`threshold`

  Limite de remoção de desalinhamento

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de Imagick::deskewImage()

    <?php
    function deskewImage($threshold) {
        $imagick = new \Imagick(realpath("images/NYTimes-Page1-11-11-1918.jpg"));
        $deskewImagick = clone $imagick;

        // Esta é a única coisa necessária para o alinhamento.
        $deskewImagick->deskewImage($threshold);

        // O resto deste exemplo é para tornar o resultado óbvio - porque
        // caso contrário o resultado não será óbvio.
        $trim = 9;

        $deskewImagick->cropImage($deskewImagick->getImageWidth() - $trim, $deskewImagick->getImageHeight(), $trim, 0);
        $imagick->cropImage($imagick->getImageWidth() - $trim, $imagick->getImageHeight(), $trim, 0);
        $deskewImagick->resizeimage($deskewImagick->getImageWidth() / 2, $deskewImagick->getImageHeight() / 2, \Imagick::FILTER_LANCZOS, 1);
        $imagick->resizeimage($imagick->getImageWidth() / 2, $imagick->getImageHeight() / 2, \Imagick::FILTER_LANCZOS, 1);
        $newCanvas = new \Imagick();
        $newCanvas->newimage($imagick->getImageWidth() + $deskewImagick->getImageWidth() + 20, $imagick->getImageHeight(), 'red', 'jpg');
        $newCanvas->compositeimage($imagick, \Imagick::COMPOSITE_COPY, 5, 0);
        $newCanvas->compositeimage($deskewImagick, \Imagick::COMPOSITE_COPY, $imagick->getImageWidth() + 10, 0);

        header("Content-Type: image/jpg");
        echo $newCanvas->getImageBlob();
    }

    ?>

# Imagick::despeckleImage

(PECL imagick 2, PECL imagick 3)

Imagick::despeckleImage — Reduz o ruído pontilhado em uma imagem

### Descrição

public function Imagick::despeckleImage(): bool

Reduz o ruído pontilhado em uma imagem, preservando as bordas da imagem original.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::despeckleImage()

    <?php
    function despeckleImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->despeckleImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::destroy

(PECL imagick 2, PECL imagick 3)

Imagick::destroy — Destrói o objeto Imagick

### Descrição

public function Imagick::destroy(): bool

Destrói o objeto Imagick e libera todos os recursos associados a ele. Este método está preterido em favor de Imagick::clear.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::displayImage

(PECL imagick 2, PECL imagick 3)

Imagick::displayImage — Exibe uma imagem

### Descrição

public function Imagick::displayImage(string `$servername`): bool

Este método exibe uma imagem em um servidor X.

### Parâmetros

`servername`

  O nome do servidor X

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::displayImages

(PECL imagick 2, PECL imagick 3)

Imagick::displayImages — Exibe uma imagem ou sequência de imagens

### Descrição

public function Imagick::displayImages(string `$servername`): bool

Exibe uma imagem ou sequência de imagens em um servidor X.

### Parâmetros

`servername`

  O nome do servidor X

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::distortImage

(PECL imagick 2 >= 2.0.1, PECL imagick 3)

Imagick::distortImage — Distorce uma imagem usando vários métodos de distorção

### Descrição

public function Imagick::distortImage(int `$method`, array `$arguments`, bool `$bestfit`): bool

Distorce uma imagem usando vários métodos de distorção, mapeando pesquisas de cores da imagem de origem para uma nova imagem de destino, geralmente do mesmo tamanho da imagem de origem, a menos que 'bestfit' esteja definido como `true`.

Se 'bestfit' estiver ativado e a distorção permitir, a imagem de destino será ajustada para garantir que toda a 'imagem' de origem caiba na imagem de destino final, que será dimensionada e deslocada de acordo. Além disso, em muitos casos, o deslocamento virtual da imagem de origem será levado em consideração no mapeamento.

Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.6 ou superior.

### Parâmetros

`method`

  O método de distorção de imagem. Consulte as constantes de distorção

`arguments`

  Os argumentos para este método de distorção

`bestfit`

  Tentativa de redimensionar o destino para caber na fonte distorcida

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Usando Imagick::distortImage()

Distorce uma imagem e exibe-a no navegador.

    <?php
    /* Cria novo objeto */
    $im = new Imagick();

    /* Cria novo padrão xadrez */
    $im->newPseudoImage(100, 100, "pattern:checkerboard");

    /* Define o formato da imagem como PNG */
    $im->setImageFormat('png');

    /* Preenche novas áreas visíveis com transparente */
    $im->setImageVirtualPixelMethod(Imagick::VIRTUALPIXELMETHOD_TRANSPARENT);

    /* Ativa fosco */
    $im->setImageMatte(true);

    /* Pontos de controle para a distorção */
    $controlPoints = array( 10, 10,
                            10, 5,

                            10, $im->getImageHeight() - 20,
                            10, $im->getImageHeight() - 5,

                            $im->getImageWidth() - 10, 10,
                            $im->getImageWidth() - 10, 20,

                            $im->getImageWidth() - 10, $im->getImageHeight() - 10,
                            $im->getImageWidth() - 10, $im->getImageHeight() - 30);

    /* Realiza a distorção */
    $im->distortImage(Imagick::DISTORTION_PERSPECTIVE, $controlPoints, true);

    /* Exibe a imagem */
    header("Content-Type: image/png");
    echo $im;
    ?>

O exemplo acima produzirá algo semelhante a:

### Veja Também

- Imagick::blurImage() - Adiciona filtro de desfoque à imagem
- Imagick::motionBlurImage() - Simula desfoque de movimento
- Imagick::radialBlurImage() - Desfoca uma imagem de forma radial

# Imagick::drawImage

(PECL imagick 2, PECL imagick 3)

Imagick::drawImage — Renderiza o objeto ImagickDraw na imagem atual

### Descrição

public function Imagick::drawImage(ImagickDraw `$draw`): bool

Renderiza o objeto ImagickDraw na imagem atual.

### Parâmetros

`draw`

  As operações de desenho a serem renderizadas na imagem.

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::edgeImage

(PECL imagick 2, PECL imagick 3)

Imagick::edgeImage — Melhora as bordas da imagem

### Descrição

public function Imagick::edgeImage(float `$radius`): bool

Aprimora as bordas da imagem com um filtro de convolução de um determinado raio. Use o raio 0 e ele será selecionado automaticamente.

### Parâmetros

`radius`

  O raio da operação.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::edgeImage()

    <?php
    function edgeImage($imagePath, $radius) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->edgeImage($radius);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::embossImage

(PECL imagick 2, PECL imagick 3)

Imagick::embossImage — Retorna uma imagem em tons de cinza com efeito tridimensional

### Descrição

public function Imagick::embossImage(float `$radius`, float `$sigma`): bool

Retorna uma imagem em tons de cinza com efeito tridimensional. A imagem sofre uma convolução com um operador gaussiano de determinado raio e desvio padrão (sigma). Para resultados razoáveis, o raio deve ser maior que o sigma. Use um raio de 0 e um raio adequado será selecionado automaticamente.

### Parâmetros

`radius`

  O raio do efeito.

`sigma`

  O sigma do efeito.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::embossImage()

    <?php
    function embossImage($imagePath, $radius, $sigma) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->embossImage($radius, $sigma);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::encipherImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::encipherImage — Cifra uma imagem

### Descrição

public function Imagick::encipherImage(string `$passphrase`): bool

Converte pixels simples em pixels criptografados. A imagem não é legível até que seja decifrada usando Imagick::decipherImage() Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.9 ou superior.

### Parâmetros

`passphrase`

  A senha.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Veja Também

- Imagick::decipherImage() - Decifra uma imagem

# Imagick::enhanceImage

(PECL imagick 2, PECL imagick 3)

Imagick::enhanceImage — Melhora a qualidade de uma imagem com ruído

### Descrição

public function Imagick::enhanceImage(): bool

Aplica um filtro digital que melhora a qualidade de uma imagem com ruído.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::enhanceImage()

    <?php
    function enhanceImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->enhanceImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::equalizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::equalizeImage — Equaliza o histograma da imagem

### Descrição

public function Imagick::equalizeImage(): bool

Equaliza o histograma da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::equalizeImage()

    <?php
    function equalizeImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->equalizeImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::evaluateImage

(PECL imagick 2, PECL imagick 3)

Imagick::evaluateImage — Aplica uma expressão a uma imagem

### Descrição

public function Imagick::evaluateImage(int `$op`, float `$constant`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Aplica uma expressão aritmética, relacional ou lógica a uma imagem. Use esses operadores para clarear ou escurecer uma imagem, para aumentar ou diminuir o contraste de uma imagem ou para produzir o “negativo” de uma imagem.

### Parâmetros

`op`

  O operador de avaliação

`constant`

  O valor do operador

`channel`

  Forneça qualquer constante de canal válida para o modo de canal. Para aplicar a mais de um canal, combine constantes de tipo de canal usando operadores bit a bit. Consulte esta lista de constantes de canal.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Usando Imagick::evaluateImage()

Usando evaluateImage para reduzir a opacidade em uma imagem.

    <?php
    // Cria novo objeto com a imagem
    $im = new Imagick('example-alpha.png');

    // Reduz alfa em 50%
    $im->evaluateImage(Imagick::EVALUATE_DIVIDE, 2, Imagick::CHANNEL_ALPHA);

    // Exibe a imagem
    header("Content-Type: image/png");
    echo $im;
    ?>

# Imagick::exportImagePixels

(PECL imagick 2 >=2.3.0, PECL imagick 3)

Imagick::exportImagePixels — Exporta os pixels da imagem não processada

### Descrição

public function Imagick::exportImagePixels(
int `$x`,
int `$y`,
int `$width`,
int `$height`,
string `$map`,
int `$STORAGE`
): array

Exporta pixels da imagem para um array. O mapa define a ordem dos pixels exportados. O tamanho do array retornado é `width * height * strlen(map)`. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.7 ou superior.

### Parâmetros

`x`

  Coordenada X da área exportada

`y`

  Coordenada Y da área exportada

`width`

  Largura da área exportada

`height`

  Altura da área exportada

`map`

  Ordenação dos pixels exportados. Por exemplo `"RGB"`. Os caracteres válidos para o mapa são R, G, B, A, O, C, Y, M, K, I e P.

`STORAGE`

  Consulte esta lista de constantes de tipo de pixel

### Valor Retornado

Retorna um array contendo os valores dos pixels.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Usando Imagick::exportImagePixels()

Exporta pixels da imagem para um array

    <?php

    /* Cria novo objeto */
    $im = new Imagick();

    /* Cria nova imagem */
    $im->newPseudoImage(0, 0, "magick:rose");

    /* Exporta os pixels da imagem */
    $pixels = $im->exportImagePixels(10, 10, 2, 2, "RGB", Imagick::PIXEL_CHAR);

    /* Exibe */
    var_dump($pixels);
    ?>

O exemplo acima produzirá:

    array(12) {
      [0]=>
      int(72)
      [1]=>
      int(64)
      [2]=>
      int(57)
      [3]=>
      int(69)
      [4]=>
      int(59)
      [5]=>
      int(43)
      [6]=>
      int(124)
      [7]=>
      int(120)
      [8]=>
      int(-96)
      [9]=>
      int(91)
      [10]=>
      int(84)
      [11]=>
      int(111)
    }

# Imagick::extentImage

(PECL imagick 2, PECL imagick 3)

Imagick::extentImage — Define tamanho da imagem

### Descrição

public function Imagick::extentImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Método de conforto para definir o tamanho da imagem. O método define o tamanho da imagem e permite definir as coordenadas x,y onde começa a nova área. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.1 ou superior.

Cuidado

Antes do ImageMagick 6.5.7-8 (1623), $x era positivo ao deslocar para a esquerda e negativo ao deslocar para a direita, e $y era positivo ao deslocar uma imagem para cima e negativo ao deslocar uma imagem para baixo. Em algum momento entre o ImageMagick 6.3.7 (1591) e o ImageMagick 6.5.7-8 (1623), os eixos de $x e $y foram invertidos, de modo que $x fosse negativo ao deslocar para a esquerda e positivo ao deslocar para a direita, e $y foi negativo ao deslocar uma imagem para cima e positivo ao deslocar uma imagem para baixo. Em algum momento entre o ImageMagick 6.5.7-8 (1623) e o ImageMagick 6.6.9-7 (1641), os eixos de $x e $y foram revertidos para a funcionalidade pré-ImageMagick 6.5.7-8 (1623).

### Parâmetros

`width`

  A nova largura

`height`

  A nova altura

`x`

  Posição X para o novo tamanho

`y`

  Posição Y para o novo tamanho

### Valor Retornado

Retorna `true` em caso de sucesso.

### Veja Também

- Imagick::resizeImage() - Dimensiona uma imagem
- Imagick::thumbnailImage() - Altera o tamanho de uma imagem
- Imagick::cropImage() - Extrai uma região da imagem

# Imagick::filter

(PECL imagick 3 >= 3.3.0)

Imagick::filter — Aplica um kernel de convolução personalizado à imagem

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::filter(ImagickKernel `$ImagickKernel`, int `$channel` = Imagick::CHANNEL_UNDEFINED): bool

Aplica um kernel de convolução personalizado à imagem.

### Parâmetros

`ImagickKernel`

  Uma instância de ImagickKernel que representa um único kernel ou uma série vinculada de kernels.

`channel`

  Fornece qualquer constante de canal que seja válida no modo de canal. Para aplicar a mais de um canal, constantes de canal devem ser combinadas usando operadores bit a bit. O padrão é `Imagick::CHANNEL_DEFAULT`. Consulte esta lista de constantes de canal

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::filter()

    <?php
    function filter($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $matrix = [
            [-1, 0, -1],
            [0,  5,  0],
            [-1, 0, -1],
        ];

        $kernel = \ImagickKernel::fromMatrix($matrix);
        $strength = 0.5;
        $kernel->scale($strength, \Imagick::NORMALIZE_KERNEL_VALUE);
        $kernel->addUnityKernel(1 - $strength);

        $imagick->filter($kernel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::flattenImages

(PECL imagick 2, PECL imagick 3)

Imagick::flattenImages — Mescla uma sequência de imagens

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::flattenImages(): Imagick

Mescla uma sequência de imagens. Isso é útil para combinar camadas Photoshop em uma única imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::flipImage

(PECL imagick 2, PECL imagick 3)

Imagick::flipImage — Cria uma imagem espelhada vertical

### Descrição

public function Imagick::flipImage(): bool

Cria uma imagem espelhada vertical refletindo os pixels em torno do eixo x central.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::flipImage()

    <?php
    function flipImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->flipImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Veja Também

- Imagick::flopimage() - Cria uma imagem espelhada horizontal

# Imagick::floodFillPaintImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::floodFillPaintImage — Altera o valor da cor de qualquer pixel que corresponda ao alvo

### Descrição

public function Imagick::floodFillPaintImage(
mixed `$fill`,
float `$fuzz`,
mixed `$target`,
int `$x`,
int `$y`,
bool `$invert`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Altera o valor da cor de qualquer pixel que corresponda ao alvo e seja um vizinho imediato. Este método é um substituto para a função preterida Imagick::paintFloodFillImage(). Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.8 ou superior.

### Parâmetros

`fill`

  Objeto ImagickPixel ou uma string contendo a cor de preenchimento

`fuzz`

  A quantidade de fuzz. Por exemplo, definir fuzz como 10 e a cor vermelha nas intensidades de 100 e 102, respectivamente, agora são interpretadas como a mesma cor.

`target`

  Objeto ImagickPixel ou uma string contendo a cor alvo a ser pintada

`x`

  Posição X do início do preenchimento

`y`

  Posição Y do início do preenchimento

`invert`

  Se `true` pinta qualquer pixel que não corresponda à cor alvo.

`channel`

  Fornece qualquer constante de canal que seja válida no modo de canal. Para aplicar a mais de um canal, constantes de canal devem ser combinadas usando operadores bit a bit. O padrão é `Imagick::CHANNEL_DEFAULT`. Consulte esta lista de constantes de canal

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::floodfillPaintImage()

    <?php

    /* Cria novo objeto Imagick */
    $im = new Imagick();

    /* cria imagens vermelha, verde e azul */
    $im->newImage(100, 50, "red");
    $im->newImage(100, 50, "green");
    $im->newImage(100, 50, "blue");

    /* Anexa as imagens em uma só */
    $im->resetIterator();
    $combined = $im->appendImages(true);

    /* Grava a imagem intermediária para comparação */
    $combined->writeImage("floodfillpaint_intermediate.png");

    /* O pixel alvo para pintura */
    $x = 1;
    $y = 1;

    /* Obtém a cor de pintura */
    $target = $combined->getImagePixelColor($x, $y);

    /* Pinta o pixel na posição 1,1 de preto e todos os pixels
       vizinhos que correspondam à cor alvo */
    $combined->floodfillPaintImage("black", 1, $target, $x, $y, false);

    /* Grava o resultado */
    $combined->writeImage("floodfillpaint_result.png");
    ?>

O exemplo acima produzirá algo semelhante a:

# Imagick::flopImage

(PECL imagick 2, PECL imagick 3)

Imagick::flopImage — Cria uma imagem espelhada horizontal

### Descrição

public function Imagick::flopImage(): bool

Cria uma imagem espelhada horizontal refletindo os pixels em torno do eixo y central.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::flopImage()

    <?php
    function flopImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->flopImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Veja Também

- Imagick::flipimage() - Cria uma imagem espelhada vertical

# Imagick::forwardFourierTransformImage

(PECL imagick 3 >= 3.3.0)

Imagick::forwardFourierTransformImage — Implementa a transformada discreta de Fourier (DFT)

### Descrição

public function Imagick::forwardFourierTransformimage(bool `$magnitude`): bool

Implementa a transformada discreta de Fourier (DFT) da imagem como um par magnitude/fase ou imagem real/imaginária.

### Parâmetros

`magnitude`

  Se verdadeiro, retorna um par magnitude/fase, caso contrário, um par de imagens real/imaginária.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::forwardFourierTransformImage()

    <?php
    // Função utilitária para forwardTransformImage
    function createMask() {
        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(0);
        $draw->setStrokeColor('rgb(255, 255, 255)');
        $draw->setFillColor('rgb(255, 255, 255)');

        // Desenha um círculo no eixo y, com seu centro
        // em x, y que toca a origem
        $draw->circle(250, 250, 220, 250);

        $imagick = new \Imagick();
        $imagick->newImage(512, 512, "black");
        $imagick->drawImage($draw);
        $imagick->gaussianBlurImage(20, 20);
        $imagick->autoLevelImage();

        return $imagick;
    }

    function forwardFourierTransformImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->resizeimage(512, 512, \Imagick::FILTER_LANCZOS, 1);

        $mask = createMask();
        $imagick->forwardFourierTransformImage(true);

        @$imagick->setimageindex(0);
        $magnitude = $imagick->getimage();

        @$imagick->setimageindex(1);
        $imagickPhase = $imagick->getimage();

        if (true) {
            $imagickPhase->compositeImage($mask, \Imagick::COMPOSITE_MULTIPLY, 0, 0);
        }

        if (false) {
            $output = clone $imagickPhase;
            $output->setimageformat('png');
            header("Content-Type: image/png");
            echo $output->getImageBlob();
        }

        $magnitude->inverseFourierTransformImage($imagickPhase, true);

        $magnitude->setimageformat('png');
        header("Content-Type: image/png");
        echo $magnitude->getImageBlob();
    }

    ?>

# Imagick::frameImage

(PECL imagick 2, PECL imagick 3)

Imagick::frameImage — Adiciona uma borda tridimensional simulada

### Descrição

public function Imagick::frameImage(
mixed `$matte_color`,
int `$width`,
int `$height`,
int `$inner_bevel`,
int `$outer_bevel`
): bool

Adiciona uma borda tridimensional simulada ao redor da imagem. A largura e a altura especificam a largura da borda dos lados vertical e horizontal do quadro. Os chanfros internos e externos indicam a largura das sombras internas e externas do quadro.

### Parâmetros

`matte_color`

  Objeto ImagickPixel ou uma string representando a cor fosca

`width`

  A largura da borda

`height`

  A altura da borda

`inner_bevel`

  A largura do chanfro interno

`outer_bevel`

  A largura do chanfro externo

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL imagick 2.1.0 | Agora permite uma string representando a cor como primeiro parâmetro. As versões anteriores permitiam apenas um objeto ImagickPixel.

### Exemplos

Exemplo #1 Exemplo de Imagick::frameImage()

    <?php
    function frameImage($imagePath, $color, $width, $height, $innerBevel, $outerBevel) {
        $imagick = new \Imagick(realpath($imagePath));

        $width = $width + $innerBevel + $outerBevel;
        $height = $height + $innerBevel + $outerBevel;

        $imagick->frameimage(
            $color,
            $width,
            $height,
            $innerBevel,
            $outerBevel
        );
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::functionImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::functionImage — Aplica uma função na imagem

### Descrição

public function Imagick::functionImage(int `$function`, array `$arguments`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Aplica uma expressão aritmética, relacional ou lógica a uma pseudoimagem.

Consulte também » Exemplos do ImageMagick v6 - Transformações de Imagens — Função, Avaliação de Multi-Argumentos

Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.9 ou superior.

### Parâmetros

`function`

  Consulte a lista de constantes de função

`arguments`

  Array de argumentos a serem passados ​​para esta função.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Cria um gradiente senoidal

    <?php
    $imagick = new Imagick();
    $imagick->newPseudoImage(200, 200, 'gradient:black-white');
    $arguments = array(3, -90);
    $imagick->functionImage(Imagick::FUNCTION_SINUSOID, $arguments);

    header("Content-Type: image/png");
    $imagick->setImageFormat("png");
    echo $imagick->getImageBlob();
    ?>

O exemplo acima produzirá algo semelhante a:

Exemplo #2 Cria um gradiente a partir do polinômio (4x^2 - 4x + 1)

    <?php
    $imagick = new Imagick();
    $imagick->newPseudoImage(200, 200, 'gradient:black-white');
    $arguments = array(4, -4, 1);
    $imagick->functionImage(Imagick::FUNCTION_POLYNOMIAL, $arguments);

    header("Content-Type: image/png");
    $imagick->setimageformat("png");
    echo $imagick->getImageBlob();
    ?>

O exemplo acima produzirá algo semelhante a:

Exemplo #3 Cria um gradiente complexo a partir do polinômio (4x^2 - 4x^2 + 1) modulado por um gradiente senoidal

    <?php
    $imagick1 = new Imagick();
    $imagick1->newPseudoImage(200, 200, 'gradient:black-white');
    $arguments = array(9, -90);
    $imagick1->functionImage(Imagick::FUNCTION_SINUSOID, $arguments);

    $imagick2 = new Imagick();
    $imagick2->newPseudoImage(200, 200, 'gradient:black-white');
    $arguments = array(0.5, 0);
    $imagick2->functionImage(Imagick::FUNCTION_SINUSOID, $arguments);
    $imagick1->compositeimage($imagick2, Imagick::COMPOSITE_MULTIPLY, 0, 0);

    header("Content-Type: image/png");
    $imagick1->setImageFormat("png");
    echo $imagick1->getImageBlob();
    ?>

O exemplo acima produzirá algo semelhante a:

# Imagick::fxImage

(PECL imagick 2, PECL imagick 3)

Imagick::fxImage — Avalia uma expressão para cada pixel da imagem

### Descrição

public function Imagick::fxImage(string `$expression`, int `$channel` = Imagick::CHANNEL_DEFAULT): Imagick

Avalia uma expressão para cada pixel da imagem. Consulte » O Operador de Imagem de Efeitos Especiais Fx para mais informação.

### Parâmetros

`expression`

  A expressão.

`channel`

  Forneça qualquer constante de canal válida para o modo de canal. Para aplicar a mais de um canal, combine constantes de tipo de canal usando operadores bit a bit. Consulte esta lista de constantes de canal.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::fxImage()

    <?php
    function fxImage() {
        $imagick = new \Imagick();
        $imagick->newPseudoImage(200, 200, "xc:white");

        $fx = 'xx=i-w/2; yy=j-h/2; rr=hypot(xx,yy); (.5-rr/140)*1.2+.5';
        $fxImage = $imagick->fxImage($fx);

        header("Content-Type: image/png");
        $fxImage->setimageformat('png');
        echo $fxImage->getImageBlob();
    }

    ?>

# Imagick::gammaImage

(PECL imagick 2, PECL imagick 3)

Imagick::gammaImage — Corrige o gama de uma imagem

### Descrição

public function Imagick::gammaImage(float `$gamma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Corrige o gama de uma imagem. A mesma imagem visualizada em diferentes dispositivos terá diferenças perceptivas na forma como as intensidades da imagem são representadas na tela. Especifica níveis de gama individuais para os canais vermelho, verde e azul ou ajusta todos os três com o parâmetro gama. Os valores normalmente variam de 0.8 a 2.3.

### Parâmetros

`gamma`

  A quantidade de correção de gama.

`channel`

  Forneça qualquer constante de canal válida para o modo de canal. Para aplicar a mais de um canal, combine constantes de tipo de canal usando operadores bit a bit. Consulte esta lista de constantes de canal.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::gammaImage()

    <?php
    function gammaImage($imagePath, $gamma, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->gammaImage($gamma, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::gaussianBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::gaussianBlurImage — Desfoca uma imagem

### Descrição

public function Imagick::gaussianBlurImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Desfoca uma imagem. A imagem sofre convolulção com um operador gaussiano de determinado raio e desvio padrão (sigma). Para resultados razoáveis, o raio deve ser maior que o sigma. Usando um raio de 0, a função selecione um raio automaticamente.

### Parâmetros

`radius`

  O raio do gaussiano, em pixels, sem contar o pixel central.

`sigma`

  O desvio padrão do gaussiano, em pixels.

`channel`

  Forneça qualquer constante de canal válida para o modo de canal. Para aplicar a mais de um canal, combine constantes de tipo de canal usando operadores bit a bit. Consulte esta lista de constantes de canal.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::gaussianBlurImage()

    <?php
    function gaussianBlurImage($imagePath, $radius, $sigma, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->gaussianBlurImage($radius, $sigma, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::getColorspace

(PECL imagick 3)

Imagick::getColorspace — Obtém o espaço de cores

### Descrição

public function Imagick::getColorspace(): int

Obtém o valor global do espaço de cores. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.5.7 ou superior.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um inteiro que pode ser comparado com constantes COLORSPACE.

# Imagick::getCompression

(PECL imagick 2, PECL imagick 3)

Imagick::getCompression — Obtém o tipo de compactação do objeto

### Descrição

public function Imagick::getCompression(): int

Obtém o tipo de compactação do objeto.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a constante de compactação.

# Imagick::getCompressionQuality

(PECL imagick 2, PECL imagick 3)

Imagick::getCompressionQuality — Obtém a qualidade de compactação do objeto

### Descrição

public function Imagick::getCompressionQuality(): int

Obtém a qualidade de compactação do objeto.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um número inteiro que descreve a qualidade da compactação

# Imagick::getCopyright

(PECL imagick 2, PECL imagick 3)

Imagick::getCopyright — Retorna os direitos autorais da API ImageMagick como uma string

### Descrição

public static function Imagick::getCopyright(): string

Retorna os direitos autorais da API ImageMagick como uma string.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string contendo o aviso de direitos autorais da API Imagemagick e Magickwand C.

# Imagick::getFilename

(PECL imagick 2, PECL imagick 3)

Imagick::getFilename — Obtém o nome do arquivo associado a uma sequência de imagens

### Descrição

public function Imagick::getFilename(): string

Retorna o nome do arquivo associado a uma sequência de imagens

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getFont

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::getFont — Obtem a fonte

### Descrição

public function Imagick::getFont(): string

Retorna a proriedade da fonte do objeto. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.7 ou superior.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string contendo o nome da fonte ou `false` se nenhuma estiver definida.

### Veja Também

- Imagick::setFont() - Define a fonte
- ImagickDraw::setFont() - Define a fonte totalmente especificada a ser usada ao fazer anotações com texto
- ImagickDraw::getFont() - Retorna a fonte

# Imagick::getFormat

(PECL imagick 2, PECL imagick 3)

Imagick::getFormat — Retorna o formato do objeto Imagick

### Descrição

public function Imagick::getFormat(): string

Retorna o formato do objeto Imagick.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o formato da imagem.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getGravity

(PECL imagick 2, PECL imagick 3)

Imagick::getGravity — Obtém a gravidade

### Descrição

public function Imagick::getGravity(): int

Obtám a propriedade de gravidade global para o objeto Imagick. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.0 ou superior.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a propriedade de gravidade. Consulte a lista de constantes de gravidade.

# Imagick::getHomeURL

(PECL imagick 2, PECL imagick 3)

Imagick::getHomeURL — Retorna o URL da página do ImageMagick

### Descrição

public static function Imagick::getHomeURL(): string

Retorna o URL da página do ImageMagick

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um atalho para a página do ImageMagick

# Imagick::getImage

(PECL imagick 2, PECL imagick 3)

Imagick::getImage — Retorna um novo objeto Imagick

### Descrição

public function Imagick::getImage(): Imagick

Retorna um novo objeto Imagick com a sequência de imagem atual.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um novo objeto Imagick com a sequência de imagem atual.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageAlphaChannel

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageAlphaChannel — Verifica se a imagem tem um canal alfa

### Descrição

public function Imagick::getImageAlphaChannel(): bool

Retorna se a imagem tem ou não um canal alfa.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se a imagem tiver um canal alfa e `false` se não tiver, ou seja, se a imagem for RGB ao invés de RGBA ou CMYK ao invés de CMYKA.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL imagick 3.6.0 | Retorna agora um bool; anteriormente, retornava um int.

# Imagick::getImageArtifact

(PECL imagick 3)

Imagick::getImageArtifact — Obtém artefato da imagem

### Descrição

public function Imagick::getImageArtifact(string `$artifact`): string

Obtém um artefato associado com a imagem. A diferença entre propriedades da imagem e artefatos da imagem é que as propriedades são públicas e os artefatos são privados. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.5.7 ou superior.

### Parâmetros

`artifact`

  O nome do artefato.

### Valor Retornado

Retorna o valor do artefato em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Veja Também

- Imagick::setImageArtifact() - Definir artefato de imagem
- Imagick::deleteImageArtifact() - Excluir artefato de imagem

# Imagick::getImageAttribute

(PECL imagick 2, PECL imagick 3)

Imagick::getImageAttribute — Retorna um atributo nomeado

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::getImageAttribute(string `$key`): string

Retorna um atributo nomeado.

### Parâmetros

`key`

  A chave do atributo a ser obtido.

### Valor Retornado

# Imagick::getImageBackgroundColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBackgroundColor — Retorna a cor de fundo a imagem

### Descrição

public function Imagick::getImageBackgroundColor(): ImagickPixel

Retorna a cor de fundo a imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retornma um objeto ImagickPixel definido com a cor de fundo da imagem.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageBlob

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBlob — Retorna a sequência de imagem como um BLOB

### Descrição

public function Imagick::getImageBlob(): string

Implementa formatos de imagem direto para a memória. Retorna a sequência de imagem como uma string. O formato da imagem determina o formato do BLOB retornado (GIF, JPEG, PNG, etc.). Para retornar um formato de imagem diferente, use Imagick::setImageFormat().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string contendo a imagem.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageBluePrimary

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBluePrimary — Retorna o ponto primário azul da cromaticidade

### Descrição

public function Imagick::getImageBluePrimary(): array

Retorna o ponto primário azul de cromaticidade da imagem.

### Parâmetros

`x`

  O ponto x primário azul da cromaticidade.

`y`

  O ponto y primário azul da cromaticidade.

### Valor Retornado

Array que consiste nas coordenadas "x" e "y" do ponto.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageBorderColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBorderColor — Retorna a cor da borda da imagem

### Descrição

public function Imagick::getImageBorderColor(): ImagickPixel

Retorna a cor da borda da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageChannelDepth

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelDepth — Obtém a profundidade de um canal de imagem específico

### Descrição

public function Imagick::getImageChannelDepth(int `$channel`): int

Obtém a profundidade de um canal de imagem específico.

### Parâmetros

`channel`

  Fornece qualquer constante de canal que seja válida no modo de canal. Para aplicar a mais de um canal, constantes de canal devem ser combinadas usando operadores bit a bit. O padrão é `Imagick::CHANNEL_DEFAULT`. Consulte esta lista de constantes de canal

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::getImageChannelDistortion

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelDistortion — Compara canais de uma imagem com uma imagem reconstruída

### Descrição

public function Imagick::getImageChannelDistortion(Imagick `$reference`, int `$channel`, int `$metric`): float

Compara um ou mais canais de uma imagem com uma reconstruída e retorna a métrica de distorção especificada.

### Parâmetros

`reference`

  Objeto Imagick a ser comparado.

`channel`

  Forneça qualquer constante de canal válida para o modo de canal. Para aplicar a mais de um canal, combine constantes de tipo de canal usando operadores bit a bit. Consulte esta lista de constantes de canal.

`metric`

  Uma das constantes de tipos de métricas.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageChannelDistortions

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageChannelDistortions — Obtém distorções de canal

### Descrição

public function Imagick::getImageChannelDistortions(Imagick `$reference`, int `$metric`, int `$channel` = Imagick::CHANNEL_DEFAULT): float

Compara um ou mais canais de uma imagem com uma reconstruída e retorna as métricas de distorção especificadas. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.4 ou superior.

### Parâmetros

`reference`

  Objeto Imagick contendo a imagem de referência.

`metric`

  Consulte esta lista de constantes de tipos de métricas.

`channel`

  Fornece qualquer constante de canal que seja válida no modo de canal. Para aplicar a mais de um canal, constantes de canal devem ser combinadas usando operadores bit a bit. O padrão é `Imagick::CHANNEL_DEFAULT`. Consulte esta lista de constantes de canal

### Valor Retornado

Retorna um float descrevendo a distorção do canal.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageChannelExtrema

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelExtrema — Obtém os extremos de um ou mais canais de imagem

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::getImageChannelExtrema(int `$channel`): array

Obtém os extremos de um ou mais canais de imagem. O valor de retorno é um array associativo com as chaves "minima" (mínimos) e "maxima" (máximos).

### Parâmetros

`channel`

  Forneça qualquer constante de canal válida para o modo de canal. Para aplicar a mais de um canal, combine constantes de tipo de canal usando operadores bit a bit. Consulte esta lista de constantes de canal.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageChannelKurtosis

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageChannelKurtosis — Obtenha a curtose e a assimetria de um canal específico

### Descrição

public function Imagick::getImageChannelKurtosis(int `$channel` = Imagick::CHANNEL_DEFAULT): array

Obtenha a curtose e a assimetria de um canal específico. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.9 ou superior.

### Parâmetros

`channel`

  Fornece qualquer constante de canal que seja válida no modo de canal. Para aplicar a mais de um canal, constantes de canal devem ser combinadas usando operadores bit a bit. O padrão é `Imagick::CHANNEL_DEFAULT`. Consulte esta lista de constantes de canal

### Valor Retornado

Retorna um array com os membros `kurtosis` (curtose) e `skewness` (assimetria).

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageChannelMean

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelMean — Obtém a média e o desvio padrão

### Descrição

public function Imagick::getImageChannelMean(int `$channel`): array

Obtém a média e o desvio padrão de um ou mais canais de imagem.

### Parâmetros

`channel`

  Forneça qualquer constante de canal válida para o modo de canal. Para aplicar a mais de um canal, combine constantes de tipo de canal usando operadores bit a bit. Consulte esta lista de constantes de canal.

### Valor Retornado

Retorna um array com os membros `"mean"` (média) e `"standardDeviation"` (desvio padrão).

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageChannelRange

(PECL imagick 2 >= 2.2.1, PECL imagick 3)

Imagick::getImageChannelRange — Obtém o intervalo do canal

### Descrição

public function Imagick::getImageChannelRange(int `$channel`): array

Obtém o intervalo de um ou mais canais de imagem. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.0 ou superior.

### Parâmetros

`channel`

  Fornece qualquer constante de canal que seja válida no modo de canal. Para aplicar a mais de um canal, constantes de canal devem ser combinadas usando operadores bit a bit. O padrão é `Imagick::CHANNEL_DEFAULT`. Consulte esta lista de constantes de canal

### Valor Retornado

Retorna um array contendo valores mínimos e máximos do(s) canal(is).

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageChannelStatistics

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelStatistics — Retorna estatísticas para cada canal na imagem

### Descrição

public function Imagick::getImageChannelStatistics(): array

Retorna estatísticas para cada canal na imagem. As estatísticas incluem a profundidade do canal, seus mínimos e máximos, a média e o desvio padrão.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::getImageClipMask

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageClipMask — Obtém a máscara de recorte da imagem

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::getImageClipMask(): Imagick

Retorna a máscara de recorte da imagem. A máscara de recorte é um objeto Imagick contendo a máscara. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.6 ou superior.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um objeto Imagick contendo a máscara de recorte.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageColormapColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageColormapColor — Retorna a cor do índice especificado do mapa de cores

### Descrição

public function Imagick::getImageColormapColor(int `$index`): ImagickPixel

Retorna a cor do índice especificado do mapa de cores.

### Parâmetros

`index`

  A posição no mapa de cores da imagem.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageColors

(PECL imagick 2, PECL imagick 3)

Imagick::getImageColors — Obtém o número de cores únicas na imagem

### Descrição

public function Imagick::getImageColors(): int

Obtém o número de cores únicas na imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um int, o número de cores únicas na imagem.

# Imagick::getImageColorspace

(PECL imagick 2, PECL imagick 3)

Imagick::getImageColorspace — Obtém o espaço de cores da imagem

### Descrição

public function Imagick::getImageColorspace(): int

Obtém o espaço de cores da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um número inteiro que pode ser comparado com as constantes de espaço de cores.

# Imagick::getImageCompose

(PECL imagick 2, PECL imagick 3)

Imagick::getImageCompose — Retorna o operador de composição associado à imagem

### Descrição

public function Imagick::getImageCompose(): int

Retorna o operador de composição associado à imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::getImageCompression

(PECL imagick 3 >= 3.3.0)

Imagick::getImageCompression — Obtém o tipo de compactação da imagem atual

### Descrição

public function Imagick::getImageCompression(): int

Obtém o tipo de compactação da imagem atual.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a constante de compactação.

# Imagick::getImageCompressionQuality

(PECL imagick 2 >= 2.2.2, PECL imagick 3)

Imagick::getImageCompressionQuality — Obtém a qualidade de compressão da imagem atual

### Descrição

public function Imagick::getImageCompressionQuality(): int

Obtém a qualidade de compressão da imagem atual.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um número inteiro que descreve a qualidade de compressão das imagens.

# Imagick::getImageDelay

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDelay — Obtém o atraso da imagem

### Descrição

public function Imagick::getImageDelay(): int

Obtém o atraso da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o atraso da imagem.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageDepth

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDepth — Obtém a profundidade da imagem

### Descrição

public function Imagick::getImageDepth(): int

Obtém a profundidade da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

A profundidade da imagem.

# Imagick::getImageDispose

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDispose — Obtém o método de descarte de imagem

### Descrição

public function Imagick::getImageDispose(): int

Obtém o método de descarte de imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o método de descarte em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageDistortion

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDistortion — Compara uma imagem com uma imagem reconstruída

### Descrição

public function Imagick::getImageDistortion(MagickWand `$reference`, int `$metric`): float

Compara uma imagem com uma imagem reconstruída e retorna a métrica de distorção especificada.

### Parâmetros

`reference`

  Objeto Imagick para comparação.

`metric`

  Uma das constantes de tipos de métricas.

### Valor Retornado

Retorna a métrica de distorção usada na imagem (ou a melhor estimativa dela).

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageExtrema

(PECL imagick 2, PECL imagick 3)

Imagick::getImageExtrema — Obtém os extremos da imagem

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::getImageExtrema(): array

Obtém os extremos da imagem. Retorna um array associativo com as chaves "min" e "max".

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array associativo com as chaves "min" e "max".

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageFilename

(PECL imagick 2, PECL imagick 3)

Imagick::getImageFilename — Retorna o nome do arquivo de uma imagem específica em uma sequência

### Descrição

public function Imagick::getImageFilename(): string

Retorna o nome do arquivo de uma imagem específica em uma sequência.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

RRetorna uma string com o nome do arquivo da imagem.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageFormat

(PECL imagick 2, PECL imagick 3)

Imagick::getImageFormat — Retorna o formato de uma imagem específica em uma sequência

### Descrição

public function Imagick::getImageFormat(): string

Retorna o formato de uma imagem específica em uma sequência.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string contendo o formato da imagem em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageGamma

(PECL imagick 2, PECL imagick 3)

Imagick::getImageGamma — Obtém o gama da imagem

### Descrição

public function Imagick::getImageGamma(): float

Obtém o gama da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o gama da imagem em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageGeometry

(PECL imagick 2, PECL imagick 3)

Imagick::getImageGeometry — Obtém a largura e a altura como um array associativo

### Descrição

public function Imagick::getImageGeometry(): array

Retorna a largura e a altura como um array associativa.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array com a largura/altura da imagem.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Usando Imagick::getImageGeometry()

    <?php
    $imagick = new Imagick();
    $imagick->newImage(100, 200, "black");
    print_r($imagick->getImageGeometry());
    ?>

O exemplo acima produzirá:

    Array
    (
        [width] => 100
        [height] => 200
    )

# Imagick::getImageGravity

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageGravity — Obtém a gravidade da imagem

### Descrição

public function Imagick::getImageGravity(): int

Obtém o valor atual da gravidade da imagem. Ao contrário de Imagick::getGravity(), este método retorna a gravidade definida para a sequência de imagens atual. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.4 ou superior.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a propriedade de gravidade da imagem. Consulte a lista de constantes de gravidade.

# Imagick::getImageGreenPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::getImageGreenPrimary — Retorna o ponto primário verde da cromaticidade

### Descrição

public function Imagick::getImageGreenPrimary(): array

Retorna o ponto primário verde da cromaticidade. Retorna um array com as chaves "x" e "y".

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array com as chaves "x" e "y". em caso de sucesso, lança uma ImagickException em caso de falha.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageHeight

(PECL imagick 2, PECL imagick 3)

Imagick::getImageHeight — Retorna a altura da imagem

### Descrição

public function Imagick::getImageHeight(): int

Retorna a altura da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a altura da imagem em pixels.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageHistogram

(PECL imagick 2, PECL imagick 3)

Imagick::getImageHistogram — Obtém o histograma da imagem

### Descrição

public function Imagick::getImageHistogram(): array

Retorna o histograma da imagem como um array de objetos ImagickPixel.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o histograma da imagem como um array de objetos ImagickPixel.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::getImageHistogram()

    <?php
    function getColorStatistics($histogramElements, $colorChannel) {
        $colorStatistics = [];

        foreach ($histogramElements as $histogramElement) {
            $color = $histogramElement->getColorValue($colorChannel);
            $color = intval($color * 255);
            $count = $histogramElement->getColorCount();

            if (array_key_exists($color, $colorStatistics)) {
                $colorStatistics[$color] += $count;
            }
            else {
                $colorStatistics[$color] = $count;
            }
        }

        ksort($colorStatistics);

        return $colorStatistics;
    }

    function getImageHistogram($imagePath) {

        $backgroundColor = 'black';

        $draw = new \ImagickDraw();
        $draw->setStrokeWidth(0); // menor espessura possível para as linha

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        $histogramWidth = 256;
        $histogramHeight = 100; // a altura para cada segmento RGB

        $imagick = new \Imagick(realpath($imagePath));
        // Redimensione a imagem para ficar pequena, caso contrário o PHP tende a ficar sem memória
        // Isso pode levar a resultados ruins para imagens patologicamente 'pixeladas'
        $imagick->adaptiveResizeImage(200, 200, true);
        $histogramElements = $imagick->getImageHistogram();

        $histogram = new \Imagick();
        $histogram->newpseudoimage($histogramWidth, $histogramHeight * 3, 'xc:black');
        $histogram->setImageFormat('png');

        $getMax = function ($carry, $item)  {
            if ($item > $carry) {
                return $item;
            }
            return $carry;
        };

        $colorValues = [
            'red' => getColorStatistics($histogramElements, \Imagick::COLOR_RED),
            'lime' => getColorStatistics($histogramElements, \Imagick::COLOR_GREEN),
            'blue' => getColorStatistics($histogramElements, \Imagick::COLOR_BLUE),
        ];

        $max = array_reduce($colorValues['red'] , $getMax, 0);
        $max = array_reduce($colorValues['lime'] , $getMax, $max);
        $max = array_reduce($colorValues['blue'] , $getMax, $max);

        $scale =  $histogramHeight / $max;

        $count = 0;
        foreach ($colorValues as $color => $values) {
            $draw->setstrokecolor($color);

            $offset = ($count + 1) * $histogramHeight;

            foreach ($values as $index => $value) {
                $draw->line($index, $offset, $index, $offset - ($value * $scale));
            }
            $count++;
        }

        $histogram->drawImage($draw);

        header( "Content-Type: image/png" );
        echo $histogram;
    }

    ?>

# Imagick::getImageIndex

(PECL imagick 2, PECL imagick 3)

Imagick::getImageIndex — Obtém o índice da imagem ativa atual

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::getImageIndex(): int

Retorna o índice da imagem ativa atual dentro do objeto Imagick. Este método foi preterido. Consulte Imagick::getIteratorIndex().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um inteiro contendo o índice da imagem na pilha.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::getImageInterlaceScheme — Obtém o esquema de entrelaçamento da imagem

### Descrição

public function Imagick::getImageInterlaceScheme(): int

Obtém o esquema de entrelaçamento da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o esquema de entrelaçamento como um número inteiro em caso de sucesso. Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageInterpolateMethod

(PECL imagick 2, PECL imagick 3)

Imagick::getImageInterpolateMethod — Retorna o método de interpolação

### Descrição

public function Imagick::getImageInterpolateMethod(): int

Retorna o método de interpolação para a imagem especificada. O método é uma das constantes `Imagick::INTERPOLATE_*`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o método de interpolação em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageIterations

(PECL imagick 2, PECL imagick 3)

Imagick::getImageIterations — Obtém as iterações da imagem

### Descrição

public function Imagick::getImageIterations(): int

Obtém as iterações da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna as iterações da imagem como um número inteiro.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageLength

(PECL imagick 2, PECL imagick 3)

Imagick::getImageLength — Retorna o comprimento da imagem em bytes

### Descrição

public function Imagick::getImageLength(): int

Retorna o comprimento da imagem em bytes.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um inteiro contendo o tamanho atual da imagem.

### Exemplos

Exemplo #1 Usando Imagick::getImageLength()

Obtendo o comprimento da imagem em bytes

    <?php
    $image = new Imagick('test.jpg');
    echo $image->getImageLength() . ' bytes';
    ?>

# Imagick::getImageMatte

(PECL imagick 2, PECL imagick 3)

Imagick::getImageMatte — Informa se a imagem tem um canal fosco

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::getImageMatte(): bool

Retorna `true` sese a imagem tiver um canal fosco, false caso contrário. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::getImageMatteColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageMatteColor — Retorna a cor fosca da imagem

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::getImageMatteColor(): ImagickPixel

Retorna a cor fosca da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o objeto ImagickPixel em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageMimeType

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageMimeType — Retorna o tipo de mídia da imagem

### Descrição

public function Imagick::getImageMimeType(): string

Retorna o tipo de mídia da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# Imagick::getImageOrientation

(PECL imagick 2, PECL imagick 3)

Imagick::getImageOrientation — Obtém a orientação da imagem

### Descrição

public function Imagick::getImageOrientation(): int

Obtém a orientação da imagem. O valor de retorno é uma das constantes de orientação.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um inteiro em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImagePage

(PECL imagick 2, PECL imagick 3)

Imagick::getImagePage — Retorna a geometria da página

### Descrição

public function Imagick::getImagePage(): array

Retorna a geometria da página associada à imagem em um array com as chaves "width" (largura), "height" (altura), "x" e "y".

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a geometria da página associada à imagem em um array com as chaves "width" (largura), "height" (altura), "x" e "y".

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImagePixelColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImagePixelColor — Retorna a cor do pixel especificado

### Descrição

public function Imagick::getImagePixelColor(int `$x`, int `$y`): ImagickPixel

Retorna a cor do pixel especificado.

### Parâmetros

`x`

  A coordenada X do pixel

`y`

  A coordenada Y do pixel

### Valor Retornado

Retorna uma instância ImagickPixel para a cor nas coordenadas fornecidas.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageProfile

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProfile — Retorna o perfil nomeado de imagem

### Descrição

public function Imagick::getImageProfile(string `$name`): string

Retorna o perfil nomeado de imagem.

### Parâmetros

`name`

  O nome do perfil a retornar.

### Valor Retornado

Retorna uma string contendo o perfil de imagem.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageProfiles

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProfiles — Retorna os perfis de imagem

### Descrição

public function Imagick::getImageProfiles(string `$pattern` = "*", bool `$include_values` = `true`): array

Retorna todos os perfis associados que correspondem ao padrão. Se `false` for passado como segundo parâmetro, apenas os nomes dos perfis são retornados. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.6 ou superior.

### Parâmetros

`pattern`

  O padrão para os nomes de perfis.

`include_values`

  Informa se devem ser retornados apenas os nomes dos perfis. Se for `false`, apenas os nomes dos perfis são retornados.

### Valor Retornado

Retorna um array contendo os perfis de imagem ou nomes de perfis.

# Imagick::getImageProperties

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProperties — Retorna as propriedades da imagem

### Descrição

public function Imagick::getImageProperties(string `$pattern` = "*", bool `$include_values` = `true`): array

Retorna todas as propriedades associadas que correspondem ao padrão. Se `false` for passado como segundo parâmetro, apenas os nomes das propriedades são retornados. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.6 ou superior.

### Parâmetros

`pattern`

  O padrão para os nomes das propriedades.

`include_values`

  Informa se devem ser retornados apenas os nomes das propriedades. Se for `false`, apenas os nomes das propriedades são retornados.

### Valor Retornado

Retorna um array contendo as propriedades da imagem ou nomes de propriedades.

### Exemplos

Exemplo #1 Usando Imagick::getImageProperties()

Um exemplo de extração de informações EXIF.

    <?php

    /* Cria o objeto */
    $im = new imagick("/path/to/example.jpg");

    /* Obtém as informações EXIF */
    $exifArray = $im->getImageProperties("exif:*");

    /* Faz um laço de repetição pelas propriedades EXIF */
    foreach ($exifArray as $name => $property)
    {
        echo "{$name} => {$property}<br />\n";
    }

    ?>

# Imagick::getImageProperty

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProperty — Retorna a propriedade nomeada da imagem

### Descrição

public function Imagick::getImageProperty(string `$name`): string

Retorna a propriedade nomeada da imagem. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.2 ou superior.

### Parâmetros

`name`

  Nome da propriedade (por exemplo, Exif:DateTime)

### Valor Retornado

Retorna uma string contendo a propriedade da imagem, false se não existir uma propriedade com o nome fornecido.

### Exemplos

Exemplo #1 Usando Imagick::getImageProperty()

Configurando e obtendo propriedade de imagem

    <?php
    $image = new Imagick();
    $image->newImage(300, 200, "black");

    $image->setImageProperty('Exif:Make', 'Imagick');
    echo $image->getImageProperty('Exif:Make');
    ?>

### Veja Também

- Imagick::setImageProperty() - Define uma propriedade de imagem

# Imagick::getImageRedPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::getImageRedPrimary — Retorna o ponto primário vermelho da cromaticidade

### Descrição

public function Imagick::getImageRedPrimary(): array

Retorna o ponto primário vermelho de cromaticidade como um array com as chaves "x" e "y".

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ponto primário vermelho de cromaticidade como um array com as chaves "x" e "y". Lança uma exceção ImagickException em caso de erro.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageRegion

(PECL imagick 2, PECL imagick 3)

Imagick::getImageRegion — Extrai uma região da imagem

### Descrição

public function Imagick::getImageRegion(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): Imagick

Extrai uma região da imagem e a retorna como um novo objeto Imagick.

### Parâmetros

`width`

  A largura da região extraída.

`height`

  A altura da região extraída.

`x`

  Coordenada X do canto superior esquerdo da região extraída.

`y`

  Coordenada Y do canto superior esquerdo da região extraída.

### Valor Retornado

Extrai uma região da imagem e a retorna como uma nova varinha.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageRenderingIntent

(PECL imagick 2, PECL imagick 3)

Imagick::getImageRenderingIntent — Obtém a intenção de renderização da imagem

### Descrição

public function Imagick::getImageRenderingIntent(): int

Obtém a intenção de renderização da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Returns a intenção de renderização da imagem.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageResolution

(PECL imagick 2, PECL imagick 3)

Imagick::getImageResolution — Obtém a resolução X e Y da imagem

### Descrição

public function Imagick::getImageResolution(): array

Obtém a resolução X e Y da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a resolução como um array.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImagesBlob

(PECL imagick 2, PECL imagick 3)

Imagick::getImagesBlob — Retorna todas as sequências de imagens como um BLOB

### Descrição

public function Imagick::getImagesBlob(): string

Implementa formatos de imagem com acesso direto na memória. Ela retorna todas as sequências de imagens como uma string. O formato da imagem determina o formato do BLOB retornado (GIF, JPEG, PNG, etc.). Para retornar um formato de imagem diferente, use Imagick::setImageFormat().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string contendo as imagens. Em caso de falha, lança uma ImagickException.

# Imagick::getImageScene

(PECL imagick 2, PECL imagick 3)

Imagick::getImageScene — Obtém a cena da imagem

### Descrição

public function Imagick::getImageScene(): int

Obtém a cena da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a cena da imagem.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageSignature

(PECL imagick 2, PECL imagick 3)

Imagick::getImageSignature — Gera um resumo da mensagem SHA-256

### Descrição

public function Imagick::getImageSignature(): string

Gera um resumo da mensagem SHA-256 para o fluxo de pixels da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string contendo o hash SHA-256 do arquivo.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageSize

(PECL imagick 2, PECL imagick 3)

Imagick::getImageSize — Retorna o comprimento da imagem em bytes

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::getImageSize(): int

Retorna o comprimento da imagem em bytes. Função preterida em favor de Imagick::getImageLength()

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um int contendo o comprimento atual da imagem.

# Imagick::getImageTicksPerSecond

(PECL imagick 2, PECL imagick 3)

Imagick::getImageTicksPerSecond — Obtém os tiques por segundo da imagem

### Descrição

public function Imagick::getImageTicksPerSecond(): int

Obtém os tiques por segundo da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna os tiques por segundo da imagem.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageTotalInkDensity

(PECL imagick 2, PECL imagick 3)

Imagick::getImageTotalInkDensity — Obtém a densidade total de tinta da imagem

### Descrição

public function Imagick::getImageTotalInkDensity(): float

Obtém a densidade total de tinta da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a densidade total de tinta da imagem. Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageType

(PECL imagick 2, PECL imagick 3)

Imagick::getImageType — Obtém o tipo potencial da imagem

### Descrição

public function Imagick::getImageType(): int

Obtém o tipo potencial da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o tipo potencial da imagem

- `imagick::IMGTYPE_UNDEFINED`
- `imagick::IMGTYPE_BILEVEL`
- `imagick::IMGTYPE_GRAYSCALE`
- `imagick::IMGTYPE_GRAYSCALEMATTE`
- `imagick::IMGTYPE_PALETTE`
- `imagick::IMGTYPE_PALETTEMATTE`
- `imagick::IMGTYPE_TRUECOLOR`
- `imagick::IMGTYPE_TRUECOLORMATTE`
- `imagick::IMGTYPE_COLORSEPARATION`
- `imagick::IMGTYPE_COLORSEPARATIONMATTE`
- `imagick::IMGTYPE_OPTIMIZE`

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageUnits

(PECL imagick 2, PECL imagick 3)

Imagick::getImageUnits — Obtém as unidades de resolução da imagem

### Descrição

public function Imagick::getImageUnits(): int

Obtém as unidades de resolução da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna as unidades de resolução da imagem.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageVirtualPixelMethod

(PECL imagick 2, PECL imagick 3)

Imagick::getImageVirtualPixelMethod — Retorna o método do pixel virtual

### Descrição

public function Imagick::getImageVirtualPixelMethod(): int

Retorna o método do pixel virtual para a imagem especificada.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o método do pixel virtual em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageWhitePoint

(PECL imagick 2, PECL imagick 3)

Imagick::getImageWhitePoint — Retorna o ponto branco da cromaticidade

### Descrição

public function Imagick::getImageWhitePoint(): array

Retorna o ponto branco da cromaticidade como um array associativo com as chaves "x" e "y".

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ponto branco da cromaticidade como um array associativo com as chaves "x" e "y".

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getImageWidth

(PECL imagick 2, PECL imagick 3)

Imagick::getImageWidth — Retorna a largura da imagem

### Descrição

public function Imagick::getImageWidth(): int

Retorna a largura da imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a largura da imagem.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::getInterlaceScheme — Obtém o esquema de entrelaçamento do objeto

### Descrição

public function Imagick::getInterlaceScheme(): int

Obtém o esquema de entrelaçamento do objeto.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Obtém o esquema de entrelaçamento da varinha.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getIteratorIndex

(PECL imagick 2, PECL imagick 3)

Imagick::getIteratorIndex — Obtém o índice da imagem ativa atual

### Descrição

public function Imagick::getIteratorIndex(): int

Retorna o índice da imagem ativa atual dentro do objeto Imagick. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um inteiro contendo o índice da imagem na pilha.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Usando Imagick::getIteratorIndex()

Cria imagens, define e obtém o índice do iterador

    <?php
    $im = new Imagick();
    $im->newImage(100, 100, new ImagickPixel("red"));
    $im->newImage(100, 100, new ImagickPixel("green"));
    $im->newImage(100, 100, new ImagickPixel("blue"));

    $im->setIteratorIndex(1);
    echo $im->getIteratorIndex();
    ?>

### Veja Também

- Imagick::setIteratorIndex() - Define a posição do iterador
- Imagick::getImageIndex() - Obtém o índice da imagem ativa atual
- Imagick::setImageIndex() - Define a posição do iterador

# Imagick::getNumberImages

(PECL imagick 2, PECL imagick 3)

Imagick::getNumberImages — Retorna o número de imagens no objeto

### Descrição

public function Imagick::getNumberImages(): int

Retorna o número de imagens associadas ao objeto Imagick.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o número de imagens associadas ao objeto Imagick.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getOption

(PECL imagick 2, PECL imagick 3)

Imagick::getOption — Retorna um valor associado à chave especificada

### Descrição

public function Imagick::getOption(string `$key`): string

Retorna um valor associado ao objeto para a chave especificada.

### Parâmetros

`key`

  O nome da opção

### Valor Retornado

Retorna um valor associado a uma varinha e à chave especificada.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getPackageName

(PECL imagick 2, PECL imagick 3)

Imagick::getPackageName — Retorna o nome do pacote ImageMagick

### Descrição

public static function Imagick::getPackageName(): string

Retorna o nome do pacote ImageMagick.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o nome do pacote ImageMagick como uma string.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getPage

(PECL imagick 2, PECL imagick 3)

Imagick::getPage — Retorna a geometria da página

### Descrição

public function Imagick::getPage(): array

Retorna a geometria da página associada ao objeto Imagick em um array associativo com as chaves "width" (largura), "height" (altura), "x" e "y".

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a geometria da página associada ao objeto Imagick em um array associativo com as chaves "width" (largura), "height" (altura), "x" e "y", e lançando uma ImagickException em caso de erro.

# Imagick::getPixelIterator

(PECL imagick 2, PECL imagick 3)

Imagick::getPixelIterator — Retorna um MagickPixelIterator

### Descrição

public function Imagick::getPixelIterator(): ImagickPixelIterator

Retorna um MagickPixelIterator.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um ImagickPixelIterator em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::getPixelIterator()

    <?php
    function getPixelIterator($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imageIterator = $imagick->getPixelIterator();

        foreach ($imageIterator as $row => $pixels) { /* Faz um laço de repetição pelas linhas de pixels */
            foreach ($pixels as $column => $pixel) { /* Faz um laço de repetição pelos pixels na linha (colunas) */
                /** @var $pixel \ImagickPixel */
                if ($column % 2) {
                    $pixel->setColor("rgba(0, 0, 0, 0)"); /* Pinta cada segundo pixel de preto */
                }
            }
            $imageIterator->syncIterator(); /* Sincroniza o iterador, é importante fazer isto em cada iteração */
        }

        header("Content-Type: image/jpg");
        echo $imagick;
    }

    ?>

# Imagick::getPixelRegionIterator

(PECL imagick 2, PECL imagick 3)

Imagick::getPixelRegionIterator — Obtém um ImagickPixelIterator para uma seção de imagem

### Descrição

public function Imagick::getPixelRegionIterator(
int `$x`,
int `$y`,
int `$columns`,
int `$rows`
): ImagickPixelIterator

Obtém um ImagickPixelIterator para uma seção de imagem.

### Parâmetros

`x`

  A coordenada X da região.

`y`

  A coordenada Y da região.

`columns`

  A largura da região.

`rows`

  A altura da região.

### Valor Retornado

Retorna um ImagickPixelIterator para uma seção de imagem.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::getPixelRegionIterator()

Itera sobre os pixels no canto superior esquerdo da imagem, alterando-os para pretos.

    <?php
    $im = new Imagick(realpath("./testImage.png"));
    $areaIterator = $im->getPixelRegionIterator(0, 0, 10, 10);

    foreach ($areaIterator as $rowIterator) {
        foreach ($rowIterator as $pixel) {
            // Paint every pixel black
            $pixel->setColor("rgba(0, 0, 0, 0)");
        }
        $areaIterator->syncIterator();
    }
    $im->writeImage("./output.png");
    ?>

# Imagick::getPointSize

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::getPointSize — Obtém o tamanho do ponto

### Descrição

public function Imagick::getPointSize(): float

Retorna a propriedade de tamanho de ponto do objeto. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.7 ou superior.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um float contendo o tamanho do ponto.

### Veja Também

- Imagick::setPointSize() - Define o tamanho em pontos

# Imagick::getQuantum

(PECL imagick 3 >= 3.3.0)

Imagick::getQuantum — Retorna o intervalo Quantum do Imagick

### Descrição

public static function Imagick::getQuantum(): int

Retorna o intervalo Quantum do Imagick. Se HDRI estiver habilitado, o tipo será float, caso contrário, será int.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# Imagick::getQuantumDepth

(PECL imagick 2, PECL imagick 3)

Imagick::getQuantumDepth — Obtém a profundidade Quantum

### Descrição

public static function Imagick::getQuantumDepth(): array

Retorna a profundidade Quantum do Imagick.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array com membros `"quantumDepthLong"` e `"quantumDepthString"`.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getQuantumRange

(PECL imagick 2, PECL imagick 3)

Imagick::getQuantumRange — Retorna o intervalo Quantum do Imagick

### Descrição

public static function Imagick::getQuantumRange(): array

Retorna o intervalo Quantum da instância Imagick.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array associativo contento o intervalo Quantum como um int (`"quantumRangeLong"`) e como uma string (`"quantumRangeString"`).

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getRegistry

(PECL imagick 3 >= 3.3.0)

Imagick::getRegistry — Obtém uma entrada StringRegistry

### Descrição

public static function Imagick::getRegistry(string `$key`): string

Obtém a entrada StringRegistry para a chave nomeada ou false se não estiver definida.

### Parâmetros

`key`

  A entrada a ser obtida.

### Valor Retornado

# Imagick::getReleaseDate

(PECL imagick 2, PECL imagick 3)

Imagick::getReleaseDate — Retorna a data da versão do ImageMagick

### Descrição

public static function Imagick::getReleaseDate(): string

Retorna a data da versão do ImageMagick como uma string.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a data da versão do ImageMagick como uma string.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getResource

(PECL imagick 2, PECL imagick 3)

Imagick::getResource — Retorna o uso de memória do recurso especificado

### Descrição

public static function Imagick::getResource(int `$type`): int

Retorna o uso de memória do recurso especificado em megabytes.

### Parâmetros

`type`

  Consulte a lista de constantes de tipo de recurso.

### Valor Retornado

Retorna o uso de memória do recurso especificado em megabytes.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getResourceLimit

(PECL imagick 2, PECL imagick 3)

Imagick::getResourceLimit — Retorna o limite de recursos especificado

### Descrição

public static function Imagick::getResourceLimit(int `$type`): int

Retorna o limite de recursos especificado.

### Parâmetros

`type`

  Uma das constantes de tipo de recurso.

### Valor Retornado

Retorna o limite de recursos especificado. A unidade depende do tipo de recurso que está sendo limitado.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Veja Também

- Imagick::setResourceLimit() - Define o limite para um recurso específico

# Imagick::getSamplingFactors

(PECL imagick 2, PECL imagick 3)

Imagick::getSamplingFactors — Obtém o fator de amostragem horizontal e vertical

### Descrição

public function Imagick::getSamplingFactors(): array

Obtém o fator de amostragem horizontal e vertical.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array associativo com os fatores de amostragem horizontal e vertical da imagem.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getSize

(PECL imagick 2, PECL imagick 3)

Imagick::getSize — Retorna o tamanho associado ao objeto Imagick

### Descrição

public function Imagick::getSize(): array

Obtém o tamanho em pixels associado ao objeto Imagick, previamente definido por Imagick::setSize().

> Nota:

> Este método apenas retorna o tamanho que foi definido usando Imagick::setSize(). Se a intenção for obter a largura/altura real da imagem, devem ser usados os métodos Imagick::getImageWidth() e Imagick::getImageHeight().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o tamanho associado ao objeto Imagick como um array com as chaves "columns" (colunas) e "rows" (linhas).

### Exemplos

Exemplo #1 Obtendo o tamanho de uma imagem RGB bruta definida em 200x400, após dimensionar para 400x800 (em comparação com largura/altura)

    <?php
    // Defina o tamanho primeiro e depois carrega a imagem bruta
    $img = new Imagick();
    $img->setSize(200, 400);
    $img->readImage("image.rgb");

    $img->scaleImage(400, 800);

    $size = $img->getSize();
    print_r($size);

    echo $img->getImageWidth()."x".$img->getImageHeight();
    ?>

O exemplo acima produzirá:

    Array
    (
        [columns] => 200
        [rows] => 400
    )
    400x800

# Imagick::getSizeOffset

(PECL imagick 2, PECL imagick 3)

Imagick::getSizeOffset — Retorna o deslocamento de tamanho

### Descrição

public function Imagick::getSizeOffset(): int

Retorna o deslocamento de tamanho associado ao objeto Imagick. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o deslocamento de tamanho associado ao objeto Imagick.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::getVersion

(PECL imagick 2, PECL imagick 3)

Imagick::getVersion — Retorna a versão da API ImageMagick

### Descrição

public static function Imagick::getVersion(): array

Retorna a versão da API ImageMagick como uma string e como um número.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a versão da API ImageMagick como uma string e como um número.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::haldClutImage

(PECL imagick 3)

Imagick::haldClutImage — Substitui cores na imagem

### Descrição

public function Imagick::haldClutImage(Imagick `$clut`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Substitui cores na imagem usando uma tabela de pesquisa Hald. Imagens Hald podem ser criadas usando o codificador de cores HALD.

### Parâmetros

`clut`

  Objeto Imagick contendo a imagem de pesquisa Hald.

`channel`

  Fornece qualquer constante de canal que seja válida no modo de canal. Para aplicar a mais de um canal, constantes de canal devem ser combinadas usando operadores bit a bit. O padrão é `Imagick::CHANNEL_DEFAULT`. Consulte esta lista de constantes de canal

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::haldClutImage()

    <?php
    function haldClutImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagickPalette = new \Imagick(realpath("images/hald/hald_8.png"));
        $imagickPalette->sepiatoneImage(55);
        $imagick->haldClutImage($imagickPalette);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::hasNextImage

(PECL imagick 2, PECL imagick 3)

Imagick::hasNextImage — Verifica se o objeto possui mais imagens

### Descrição

public function Imagick::hasNextImage(): bool

Retorna `true` se o objeto tiver mais imagens ao percorrer a lista para a frente.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se o objeto tiver mais imagens ao percorrer a lista para a frente, retorna `false` se não tiver.

# Imagick::hasPreviousImage

(PECL imagick 2, PECL imagick 3)

Imagick::hasPreviousImage — Verifica se o objeto possui uma imagem anterior

### Descrição

public function Imagick::hasPreviousImage(): bool

Retorna `true` se o objeto tiver mais imagens ao percorrer a lista na direção inversa.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` se o objeto tiver mais imagens ao percorrer a lista na direção inversa, retorna `false` se não houver.

# Imagick::identifyFormat

(PECL imagick 3 >= 3.3.0)

Imagick::identifyFormat — Formata uma string com detalhes da imagem

### Descrição

public function Imagick::identifyFormat(string `$embedText`): string|false

Substitui quaisquer caracteres de formatação incorporados pela propriedade de imagem apropriada e retorna o texto interpretado. Consulte http://www.imagemagick.org/script/escape.php para sequências de escape.

### Parâmetros

`embedText`

  Uma string contendo sequências de formatação, por ex. "Caixa de acabamento: %@ número de cores exclusivas: %k".

### Valor Retornado

Retorna o formato ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de Imagick::identifyFormat()

    <?php
        $output = "Saída de 'Caixa de acabamento: %@ número de cores exclusivas: %k' é: <br/>";
        $imagick = new \Imagick(realpath("./images/artifact/mask.png"));
        $output .= $imagick->identifyFormat("Caixa de acabamento: %@ número de cores exclusivas: %k");

    ?>

# Imagick::identifyImage

(PECL imagick 2, PECL imagick 3)

Imagick::identifyImage — Identifica uma imagem e busca atributos

### Descrição

public function Imagick::identifyImage(bool `$appendRawOutput` = `false`): array

Identifica uma imagem e retorna os atributos. Os atributos incluem largura, altura, tamanho da imagem e outros.

### Parâmetros

`appendRawOutput`

  Se `true` então a saída bruta é anexada ao array.

### Valor Retornado

Identifica uma imagem e retorna os atributos. Os atributos incluem largura, altura, tamanho da imagem e outros.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Formato de Resultado

    Array
    (
        [imageName] => /some/path/image.jpg
        [format] => JPEG (Joint Photographic Experts Group JFIF format)
        [geometry] => Array
            (
                [width] => 90
                [height] => 90
            )

        [type] => TrueColor
        [colorSpace] => RGB
        [resolution] => Array
            (
                [x] => 300
                [y] => 300
            )

        [units] => PixelsPerInch
        [fileSize] => 1.88672kb
        [compression] => JPEG
        [signature] => 9a6dc8f604f97d0d691c0286176ddf992e188f0bebba98494b2146ee2d7118da
    )

# Imagick::implodeImage

(PECL imagick 2, PECL imagick 3)

Imagick::implodeImage — Cria uma nova imagem como cópia

### Descrição

public function Imagick::implodeImage(float `$radius`): bool

Cria uma nova imagem que é uma cópia de uma existente com os pixels da imagem "implodidos" pela porcentagem especificada.

### Parâmetros

`radius`

  O raio da implosão

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::implodeImage()

    <?php
    function implodeImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->implodeImage(0.0001);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();

    }

    ?>

# Imagick::importImagePixels

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::importImagePixels — Importa pixels de imagem

### Descrição

public function Imagick::importImagePixels(
int `$x`,
int `$y`,
int `$width`,
int `$height`,
string `$map`,
int `$storage`,
array `$pixels`
): bool

Importa pixels de um array para uma imagem. O parâmetro `map` geralmente é 'RGB'. Este método impõe as seguintes restrições para os parâmetros: a quantidade de pixels no array deve corresponder a `width` (largura) x `height` (altura) x comprimento do mapa. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.5 ou superior.

### Parâmetros

`x`

  A posição X da imagem

`y`

  A posição Y da imagem

`width`

  A largura da imagem

`height`

  A altura da imagem

`map`

  Mapa de ordenação de pixels como uma string. Pode ser, por exemplo, `RGB`. O valor pode ser qualquer combinação ou ordem de R = vermelho, G = verde, B = azul, A = alfa (0 é transparente), O = opacidade (0 é opaco), C = ciano, Y = amarelo, M = magenta , K = preto, I = intensidade (para tons de cinza), P = preenchimento.

`storage`

  O método de armazenamento de pixels. Consulte a lista de constantes de pixels.

`pixels`

  O array de pixels.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::importImagePixels()

    <?php

    /* Gera array de pixels. 2000 pixels por faixa de cor */
    $count = 2000 * 3;

    $pixels =
        array_merge(array_pad(array(), $count, 0),
                   array_pad(array(), $count, 255),
                   array_pad(array(), $count, 0),
                   array_pad(array(), $count, 255),
                   array_pad(array(), $count, 0));

    /* Largura e altura. A área é a quantidade de pixels dividida
       por três. Três vem de 'RGB', três valores por pixel */
    $width = $height = pow((count($pixels) / 3), 0.5);

    /* Cria imagem vazia */
    $im = new Imagick();
    $im->newImage($width, $height, 'gray');

    /* Importa os pixels na imagem.
       largura * altura * strlen("RGB") precisa corresponder a count($pixels) */
    $im->importImagePixels(0, 0, $width, $height, "RGB", Imagick::PIXEL_CHAR, $pixels);

    /* exibe como imagem JPEG */
    $im->setImageFormat('jpg');
    header("Content-Type: image/jpg");
    echo $im;

    ?>

O exemplo acima produzirá algo semelhante a:

# Imagick::inverseFourierTransformImage

(PECL imagick 3 >= 3.3.0)

Imagick::inverseFourierTransformImage — Implementa a transformada discreta inversa de Fourier (DFT)

### Descrição

public function Imagick::inverseFourierTransformImage(Imagick `$complement`, bool `$magnitude`): bool

Implementa a transformada discreta inversa de Fourier (DFT) da imagem como um par de magnitude/fase ou imagem real/imaginária.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`complement`

  A segunda imagem a ser combinada com esta para formar o par magnitude/fase ou imagem real/imaginária.

`magnitude`

  Se for igual a true, combina como par magnitude/fase, caso contrário, como par de imagens real/imaginária.

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::labelImage

(PECL imagick 2, PECL imagick 3)

Imagick::labelImage — Adiciona um rótulo a uma imagem

### Descrição

public function Imagick::labelImage(string `$label`): bool

Adiciona um rótulo a uma imagem.

### Parâmetros

`label`

  O rótulo a ser adicionado.

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::levelImage

(PECL imagick 2, PECL imagick 3)

Imagick::levelImage — Ajusta os níveis de uma imagem

### Descrição

public function Imagick::levelImage(
float `$blackPoint`,
float `$gamma`,
float `$whitePoint`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Ajusta os níveis de uma imagem dimensionando as cores que ficam entre os pontos brancos e pretos especificados para toda a faixa de Quantum disponível. Os parâmetros fornecidos representam os pontos preto, médio e branco. O ponto preto especifica a cor mais escura da imagem. As cores mais escuras que o ponto preto são definidas como zero. O ponto médio especifica uma correção gama a ser aplicada à imagem. O ponto branco especifica a cor mais clara da imagem. As cores mais claras que o ponto branco são definidas com o valor máximo de Quantum.

### Parâmetros

`blackPoint`

  O ponto preto da imagem.

`gamma`

  O valor de gama.

`whitePoint`

  O ponto branco da imagem.

`channel`

  Forneça qualquer constante de canal válida para o modo de canal. Para aplicar a mais de um canal, combine constantes de tipo de canal usando operadores bit a bit. Consulte esta lista de constantes de canal.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::levelImage()

    <?php
    function levelImage($blackPoint, $gamma, $whitePoint) {
        $imagick = new \Imagick();
        $imagick->newPseudoimage(500, 500, 'gradient:black-white');

        $imagick->setFormat('png');
        $quantum = $imagick->getQuantum();
        $imagick->levelImage($blackPoint / 100 , $gamma, $quantum * $whitePoint / 100);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::linearStretchImage

(PECL imagick 2, PECL imagick 3)

Imagick::linearStretchImage — Estica com saturação a intensidade da imagem

### Descrição

public function Imagick::linearStretchImage(float `$blackPoint`, float `$whitePoint`): bool

Estica com saturação a intensidade da imagem.

### Parâmetros

`blackPoint`

  O ponto preto da imagem.

`whitePoint`

  O ponto branco da imagem.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::linearStretchImage()

    <?php
    function linearStretchImage($imagePath, $blackThreshold, $whiteThreshold) {
        $imagick = new \Imagick(realpath($imagePath));
        $pixels = $imagick->getImageWidth() * $imagick->getImageHeight();
        $imagick->linearStretchImage($blackThreshold * $pixels, $whiteThreshold * $pixels);

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::liquidRescaleImage

(PECL imagick 2 >= 2.2.0, PECL imagick 3)

Imagick::liquidRescaleImage — Anima uma imagem ou imagens

### Descrição

public function Imagick::liquidRescaleImage(
int `$width`,
int `$height`,
float `$delta_x`,
float `$rigidity`
): bool

Este método dimensiona as imagens usando o método de redimensionamento líquido. Este método é uma implementação de uma técnica chamada "remoção de costura". Para que este método funcione conforme o esperado, o ImageMagick precisa ser compilado com suporte à biblioteca liblqr. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.9 ou superior.

### Parâmetros

`width`

  A largura do tamanho alvo

`height`

  A altura do tamanho do alvo

`delta_x`

  Quanto a costura pode percorrer no eixo x. Passar 0 faz com que as costuras fiquem retas.

`rigidity`

  Introduz um adicional para costuras não retas. Este parâmetro normalmente é 0.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Veja Também

- Imagick::resizeImage() - Dimensiona uma imagem

# Imagick::listRegistry

(PECL imagick 3 >= 3.3.0)

Imagick::listRegistry — Lista todas as configurações do registro

### Descrição

public static function Imagick::listRegistry(): array

Lista todas as configurações do registro. Retorna um array com todos os pares chave/valor no registro

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um array contendo as chaves/valores do registro.

# Imagick::magnifyImage

(PECL imagick 2, PECL imagick 3)

Imagick::magnifyImage — Dimensiona uma imagem proporcionalmente 2x

### Descrição

public function Imagick::magnifyImage(): bool

É um método de conveniência que dimensiona uma imagem proporcionalmente ao dobro do seu tamanho original.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::magnifyImage()

    <?php
    function magnifyImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->magnifyImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::mapImage

(PECL imagick 2, PECL imagick 3)

Imagick::mapImage — Substitui as cores de uma imagem pela cor mais próxima de uma imagem de referência

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::mapImage(Imagick `$map`, bool `$dither`): bool

### Parâmetros

`map`

`dither`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::matteFloodfillImage

(PECL imagick 2, PECL imagick 3)

Imagick::matteFloodfillImage — Altera o valor de transparência de uma cor

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::matteFloodfillImage(
float `$alpha`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`
): bool

Altera o valor de transparência de qualquer pixel que corresponda ao alvo e seja um vizinho imediato. Se o método `FillToBorderMethod` for especificado, o valor da transparência será alterado para qualquer pixel vizinho que não corresponda à cor de borda da imagem (parâmetro "bordercolor").

### Parâmetros

`alpha`

  O nível de transparência: 1.0 é totalmente opaco e 0.0 é totalmente transparente.

`fuzz`

  O membro "fuzz" da imagem define quanta tolerância é aceitável para considerar duas cores iguais.

`bordercolor`

  Um objeto ImagickPixel ou string representando a cor de borda.

`x`

  A coordenada x inicial da operação.

`y`

  A coordenada y inicial da operação.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL imagick 2.1.0 | Agora permite uma string representando a cor como terceiro parâmetro. Versões anteriores permitiam apenas um objeto ImagickPixel.

# Imagick::medianFilterImage

(PECL imagick 2, PECL imagick 3)

Imagick::medianFilterImage — Aplica um filtro digital

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::medianFilterImage(float `$radius`): bool

Aplica um filtro digital que melhora a qualidade de uma imagem com ruído. Cada pixel é substituído pela mediana em um conjunto de pixels vizinhos conforme definido pelo raio.

### Parâmetros

`radius`

  O raio da vizinhança do pixel.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::medianFilterImage()

    <?php
    function medianFilterImage($radius, $imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        @$imagick->medianFilterImage($radius);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::mergeImageLayers

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::mergeImageLayers — Mescla camadas de imagem

### Descrição

public function Imagick::mergeImageLayers(int `$layer_method`): Imagick

Mescla camadas de imagem em uma. Este método é útil ao trabalhar com formatos de imagem que usam múltiplas camadas, como PSD. A fusão é controlada usando o `layer_method` que define como as camadas são mescladas. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.7 ou superior.

### Parâmetros

`layer_method`

  Uma das constantes `Imagick::LAYERMETHOD_*`.

### Valor Retornado

Retorna um objeto Imagick contendo a imagem mesclada.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::mergeImageLayers()

    <?php
    function mergeImageLayers($layerMethodType, $imagePath1, $imagePath2) {

        $imagick = new \Imagick(realpath($imagePath1));

        $imagick2 = new \Imagick(realpath($imagePath2));
        $imagick->addImage($imagick2);
        $imagick->setImageFormat('png');

        $result = $imagick->mergeImageLayers($layerMethodType);
        header("Content-Type: image/png");
        echo $result->getImageBlob();
    }

    ?>

### Veja Também

- Imagick::flattenImages() - Mescla uma sequência de imagens

# Imagick::minifyImage

(PECL imagick 2, PECL imagick 3)

Imagick::minifyImage — Dimensiona uma imagem proporcionalmente à metade do seu tamanho

### Descrição

public function Imagick::minifyImage(): bool

É um método de conveniência que dimensiona uma imagem proporcionalmente à metade do seu tamanho original.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::modulateImage

(PECL imagick 2, PECL imagick 3)

Imagick::modulateImage — Controle brilho, saturação e matiz

### Descrição

public function Imagick::modulateImage(float `$brightness`, float `$saturation`, float `$hue`): bool

Permite controlar o brilho, a saturação e o matiz de uma imagem. Matiz é a porcentagem de rotação absoluta da posição atual. Por exemplo, 50 resulta em uma rotação no sentido anti-horário de 90 graus, 150 resulta em uma rotação no sentido horário de 90 graus, com 0 e 200 resultando em uma rotação de 180 graus.

### Parâmetros

`brightness`

`saturation`

`hue`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::modulateImage()

    <?php
    function modulateImage($imagePath, $hue, $brightness, $saturation) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->modulateImage($brightness, $saturation, $hue);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::montageImage

(PECL imagick 2, PECL imagick 3)

Imagick::montageImage — Cria uma imagem composta

### Descrição

public function Imagick::montageImage(
ImagickDraw `$draw`,
string `$tile_geometry`,
string `$thumbnail_geometry`,
int `$mode`,
string `$frame`
): Imagick

Cria uma imagem composta combinando várias imagens separadas. As imagens são dispostas lado a lado na imagem composta, com o nome da imagem aparecendo opcionalmente logo abaixo do bloco individual.

### Parâmetros

`draw`

  O nome, tamanho e cor da fonte são obtidos deste objeto.

`tile_geometry`

  O número de blocos por linha e página (por exemplo, 6x4+0+0).

`thumbnail_geometry`

  Tamanho de imagem preferido e tamanho da borda de cada miniatura (por exemplo, 120x120+4+3).

`mode`

  Modo de enquadramento de miniatura, consulte as constantes de modos de montagem.

`frame`

  Envolve a imagem com uma borda ornamental (por exemplo, 15x15+3+3). A cor da moldura é a cor fosca da miniatura.

### Valor Retornado

Cria uma imagem composta e a retorna como um novo objeto Imagick.

# Imagick::morphImages

(PECL imagick 2, PECL imagick 3)

Imagick::morphImages — Transforma um conjunto de imagens

### Descrição

public function Imagick::morphImages(int `$number_frames`): Imagick

Transforma um conjunto de imagens. Tanto os pixels quanto o tamanho da imagem são interpolados linearmente para dar a aparência de uma metamorfose de uma imagem para outra.

### Parâmetros

`number_frames`

  O número de imagens intermediárias a serem geradas.

### Valor Retornado

Este método retorna um novo objeto Imagick em caso de sucesso. Lança uma exceção ImagickException em caso de erro.

# Imagick::morphology

(PECL imagick 3 >= 3.3.0)

Imagick::morphology — Aplica um kernel fornecido pelo usuário à imagem de acordo com o método de morfologia fornecido

### Descrição

public function Imagick::morphology(
int `$morphologyMethod`,
int `$iterations`,
ImagickKernel `$ImagickKernel`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Aplica um kernel fornecido pelo usuário à imagem de acordo com o método de morfologia fornecido.

### Parâmetros

`morphologyMethod`

  Qual método de morfologia usar, uma das constantes \Imagick::MORPHOLOGY_*.

`iterations`

  O número de iterações em que a função de morfologia será aplicada. Um valor de -1 significa repetição até que mais nenhuma alteração seja encontrada. A forma como isso é aplicado pode depender do método de morfologia. Normalmente tem o valor de 1.

`ImagickKernel`

`channel`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Imagick::morphology() com morfologia de convolução

    <?php
            $imagick = $this->getCharacter();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_GAUSSIAN, "5,1");
            $imagick->morphology(\Imagick::MORPHOLOGY_CONVOLVE, 2, $kernel);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();

    ?>

Exemplo #2 Imagick::morphology() com morfologia de correlação

    <?php

            // O pixel superior esquerdo deve ser preto
            // O pixel inferior direito deve ser branco
            // O resto não é importante.

            $imagick = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromMatrix(self::$correlateMatrix, [2, 2]);
            $imagick->morphology(\Imagick::MORPHOLOGY_CORRELATE, 1, $kernel);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();

    ?>

Exemplo #3 Imagick::morphology() com morfologia de erosão

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
            $canvas->morphology(\Imagick::MORPHOLOGY_ERODE, 2, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemplo #4 Imagick::morphology() com morfologia de erosão de intensidade

    <?php
            $canvas = $this->getCharacter();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "1");
            $canvas->morphology(\Imagick::MORPHOLOGY_ERODE_INTENSITY, 2, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemplo #5 Imagick::morphology() com morfologia de dilatação

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
            $canvas->morphology(\Imagick::MORPHOLOGY_DILATE, 4, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemplo #6 Imagick::morphology() com morfologia de dilatação de intensidade

    <?php
            $canvas = $this->getCharacter();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "1");
            $canvas->morphology(\Imagick::MORPHOLOGY_DILATE_INTENSITY, 4, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemplo #7 Imagick::morphology() com morfologia de distância do kernel Chebyshev

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_CHEBYSHEV, "3");
            $canvas->morphology(\Imagick::MORPHOLOGY_DISTANCE, 3, $kernel);
            $canvas->autoLevelImage();
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemplo #8 Imagick::morphology() com morfologia de distância do kernel Manhattan

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_MANHATTAN, "5");
            $canvas->morphology(\Imagick::MORPHOLOGY_DISTANCE, 3, $kernel);
            $canvas->autoLevelImage();
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemplo #9 Imagick::morphology() com morfologia de distância do kernel octogonal

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGONAL, "5");
            $canvas->morphology(\Imagick::MORPHOLOGY_DISTANCE, 3, $kernel);
            $canvas->autoLevelImage();
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemplo #10 Imagick::morphology() com morfologia de distância do kernel euclidiano

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_EUCLIDEAN, "4");
            $canvas->morphology(\Imagick::MORPHOLOGY_DISTANCE, 3, $kernel);
            $canvas->autoLevelImage();
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemplo #11 Imagick::morphology() com morfologia de borda

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
            $canvas->morphology(\Imagick::MORPHOLOGY_EDGE, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemplo #12 Imagick::morphology() com morfologia de abertura

    <?php
            // Como resultado, será visto que o método de abertura suavizará o contorno, arredondando os pontos afiados, e removerá as partes menores que a forma usada. Também irá desconectar ou abrir todas a pontes finas.
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "6");
            $canvas->morphology(\Imagick::MORPHOLOGY_OPEN, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemplo #13 Imagick::morphology() com morfologia de abertura de intensidade

    <?php
            // Como resultado, será visto que o método de abertura suavizará o contorno, arredondando os pontos afiados, e removerá as partes menores que a forma usada. Também irá desconectar ou abrir todas a pontes finas.

            $canvas = $this->getCharacter();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "6");
            $canvas->morphology(\Imagick::MORPHOLOGY_OPEN_INTENSITY, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemplo #14 Imagick::morphology() com morfologia de fechamento

    <?php
            // O uso básico do método de fechamento é reduzir ou remover quaisquer buracos ou lacunas com tamanho próximo ao do 'Elemento de estrutura' do kernel. Isto é, fechar as partes do plano de fundo que são têm aproximadamente esse tamanho.
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "6");
            $canvas->morphology(\Imagick::MORPHOLOGY_CLOSE, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemplo #15 Imagick::morphology() com morfologia de fechamento de intensidade

    <?php
            // O uso básico do método de fechamento é reduzir ou remover quaisquer buracos ou lacunas com tamanho próximo ao do 'Elemento de estrutura' do kernel. Isto é, fechar as partes do plano de fundo que são têm aproximadamente esse tamanho.
            $canvas = $this->getCharacter();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "6");
            $canvas->morphology(\Imagick::MORPHOLOGY_CLOSE_INTENSITY, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemplo #16 Imagick::morphology() com morfologia de suavização

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
            $canvas->morphology(\Imagick::MORPHOLOGY_SMOOTH, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemplo #17 Imagick::morphology() com morfologia de bordas para dentro

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
            $canvas->morphology(\Imagick::MORPHOLOGY_EDGE_IN, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemplo #18 Edge out Imagick::morphology() com morfologia de bordas para fora

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
            $canvas->morphology(\Imagick::MORPHOLOGY_EDGE_OUT, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemplo #19 Imagick::morphology() com morfologia de 'TopHat', ou mais especificamente 'TopHat Branco'. Retorna os pixels que foram removidos por uma abertura da forma, ou seja, os pixels que foram removidos para arredondar os pontos e as pontes de conexão entre as formas.

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "5");
            $canvas->morphology(\Imagick::MORPHOLOGY_TOP_HAT, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemplo #20 Imagick::morphology() com morfologia de 'BottomHat', também conhecido como 'TopHat Preto'. São os pixels que um fechamento de forma adiciona à imagem. Isto é, os pixels que foram usados ​​para preencher os buracos, lacunas e pontes.

    <?php

            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "5");
            $canvas->morphology(\Imagick::MORPHOLOGY_BOTTOM_HAT, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemplo #21 Imagick::morphology() com morfologia de acerto e erro

    <?php
            $canvas = $this->getCharacterOutline();
            // Isto encontra todos os pixels com 3 pixels da borda direita
            $matrix = [[1, false, false, 0]];
            $kernel = \ImagickKernel::fromMatrix(
                $matrix,
                [0, 0]
            );
            $canvas->morphology(\Imagick::MORPHOLOGY_HIT_AND_MISS, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemplo #22 Imagick::morphology() com morfologia de desbaste

    <?php
            $canvas = $this->getCharacterOutline();
            $leftEdgeKernel = \ImagickKernel::fromMatrix([[0, 1]], [1, 0]);
            $rightEdgeKernel = \ImagickKernel::fromMatrix([[1, 0]], [0, 0]);
            $leftEdgeKernel->addKernel($rightEdgeKernel);

            $canvas->morphology(\Imagick::MORPHOLOGY_THINNING, 3, $leftEdgeKernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemplo #23 Imagick::morphology() com morfologia de espessamento

    <?php
            $canvas = $this->getCharacterOutline();
            $leftEdgeKernel = \ImagickKernel::fromMatrix([[0, 1]], [1, 0]);
            $rightEdgeKernel = \ImagickKernel::fromMatrix([[1, 0]], [0, 0]);
            $leftEdgeKernel->addKernel($rightEdgeKernel);

            $canvas->morphology(\Imagick::MORPHOLOGY_THICKEN, 3, $leftEdgeKernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemplo #24 Imagick::morphology() com morfologia de espessamento para gerar um casco convexo

    <?php
            $canvas = $this->getCharacterOutline();
            $diamondKernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DIAMOND, "1");
            $convexKernel =  \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_CONVEX_HULL, "");

            // A morfologia de espessamento não consegue lidar com lacunas pequenas. Eslas são fechadas
            // com a morfologia de fechamento.
            $canvas->morphology(\Imagick::MORPHOLOGY_CLOSE, 1, $diamondKernel);
            $canvas->morphology(\Imagick::MORPHOLOGY_THICKEN, -1, $convexKernel);
            $canvas->morphology(\Imagick::MORPHOLOGY_CLOSE, 1, $diamondKernel);

            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemplo #25 Imagick::morphology() com morfologia de iteração

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "2");
            $canvas->morphology(\Imagick::MORPHOLOGY_ITERATIVE, 3, $kernel);
            $canvas->autoLevelImage();
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemplo #26 Imagick::morphology() com função auxiliar para obter silhueta de imagem

    <?php
    function getCharacterOutline() {
        $imagick = new \Imagick(realpath("./images/character.png"));
        $character = new \Imagick();
        $character->newPseudoImage(
            $imagick->getImageWidth(),
            $imagick->getImageHeight(),
            "canvas:white"
        );
        $canvas = new \Imagick();
        $canvas->newPseudoImage(
            $imagick->getImageWidth(),
            $imagick->getImageHeight(),
            "canvas:black"
        );

        $character->compositeimage(
            $imagick,
            \Imagick::COMPOSITE_COPYOPACITY,
            0, 0
        );
        $canvas->compositeimage(
            $character,
            \Imagick::COMPOSITE_ATOP,
            0, 0
        );
        $canvas->setFormat('png');

        return $canvas;
    }
    ?>

# Imagick::mosaicImages

(PECL imagick 2, PECL imagick 3)

Imagick::mosaicImages — Forma um mosaico a partir de imagens

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::mosaicImages(): Imagick

Insere uma sequência de imagens para formar uma única imagem coerente. Retorna uma varinha com cada imagem da sequência composta no local definido pela posição da imagem na página.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::motionBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::motionBlurImage — Simula desfoque de movimento

### Descrição

public function Imagick::motionBlurImage(
float `$radius`,
float `$sigma`,
float `$angle`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Simula desfoque de movimento. A imagem sofre convolução com um operador gaussiano de determinado raio e desvio padrão (sigma). Para resultados razoáveis, o raio deve ser maior que o sigma. Use um raio de 0 e MotionBlurImage() seleciona um raio adequado automaticamente. O parâmetro 'angle' fornece o ângulo do movimento de desfoque.

### Parâmetros

`radius`

  O raio do gaussiano, em pixels, sem contar o pixel central.

`sigma`

  O desvio padrão do gaussiano, em pixels.

`angle`

  O efeito será aplicado ao longo deste ângulo.

`channel`

  Forneça qualquer constante de canal válida para o modo de canal. Para aplicar a mais de um canal, combine constantes de tipo de canal usando operadores bit a bit. Consulte esta lista de constantes de canal. Este parâmetro terá efeito apenas se o Imagick for compilado no ImageMagick versão 6.4.4 ou superior.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::motionBlurImage()

    <?php
    function motionBlurImage($imagePath, $radius, $sigma, $angle, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->motionBlurImage($radius, $sigma, $angle, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::negateImage

(PECL imagick 2, PECL imagick 3)

Imagick::negateImage — Negativa as cores na imagem de referência

### Descrição

public function Imagick::negateImage(bool `$gray`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Negativa as cores na imagem de referência. O parâmetro 'gray' define se apenas os valores da escala de cinza na imagem são negativados.

### Parâmetros

`gray`

  Se apenas serão negativados pixels na escala de cinza na imagem.

`channel`

  Forneça qualquer constante de canal válida para o modo de canal. Para aplicar a mais de um canal, combine constantes de tipo de canal usando operadores bit a bit. Consulte esta lista de constantes de canal.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::negateImage()

    <?php
    function negateImage($imagePath, $grayOnly, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->negateImage($grayOnly, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::newImage

(PECL imagick 2, PECL imagick 3)

Imagick::newImage — Cria uma nova imagem

### Descrição

public function Imagick::newImage(
int `$cols`,
int `$rows`,
mixed `$background`,
string `$format` = ?
): bool

Cria uma nova imagem e associa o valor ImagickPixel como cor de fundo.

### Parâmetros

`cols`

  Colunas na nova imagem.

`rows`

  Linhas na nova imagem.

`background`

  A cor de fundo usada para esta imagem.

`format`

  Formato de imagem. Este parâmetro foi adicionado no Imagick versão 2.0.1.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL imagick 2.1.0 | Agora permite uma string representando a cor como terceiro parâmetro. As versões anteriores permitiam apenas um objeto ImagickPixel.

### Exemplos

Exemplo #1 Usando Imagick::newImage()

Cria uma nova imagem e mostra-a no navegador.

    <?php

    $image = new Imagick();
    $image->newImage(100, 100, new ImagickPixel('red'));
    $image->setImageFormat('png');

    header('Content-type: image/png');
    echo $image;

    ?>

# Imagick::newPseudoImage

(PECL imagick 2, PECL imagick 3)

Imagick::newPseudoImage — Cria uma nova imagem

### Descrição

public function Imagick::newPseudoImage(int `$columns`, int `$rows`, string `$pseudoString`): bool

Cria uma nova imagem usando pseudoformatos ImageMagick.

### Parâmetros

`columns`

  Colunas na nova imagem

`rows`

  Linhas na nova imagem

`pseudoString`

  String contendo definição de pseudoimagem.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::newPseudoImage()

    <?php
    function newPseudoImage($canvasType) {
        $imagick = new \Imagick();
        $imagick->newPseudoImage(300, 300, $canvasType);
        $imagick->setImageFormat("png");
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    // newPseudoImage('gradient:red-rgba(64, 255, 255, 0.5)');
    // newPseudoImage("radial-gradient:red-blue");
    newPseudoImage("plasma:fractal");

    ?>

# Imagick::nextImage

(PECL imagick 2, PECL imagick 3)

Imagick::nextImage — Passa para a próxima imagem

### Descrição

public function Imagick::nextImage(): bool

Associa a próxima imagem na lista de imagens a um objeto Imagick.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::normalizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::normalizeImage — Melhora o contraste de uma imagem colorida

### Descrição

public function Imagick::normalizeImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Melhora o contraste de uma imagem colorida ajustando a cor dos pixels para abranger toda a gama de cores disponíveis.

### Parâmetros

`channel`

  Forneça qualquer constante de canal válida para o modo de canal. Para aplicar a mais de um canal, combine constantes de tipo de canal usando operadores bit a bit. Consulte esta lista de constantes de canal.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::normalizeImage()

    <?php
    function normalizeImage($imagePath, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $original = clone $imagick;
        $original->cropimage($original->getImageWidth() / 2, $original->getImageHeight(), 0, 0);
        $imagick->normalizeImage($channel);
        $imagick->compositeimage($original, \Imagick::COMPOSITE_ATOP, 0, 0);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::oilPaintImage

(PECL imagick 2, PECL imagick 3)

Imagick::oilPaintImage — Simula uma pintura a óleo

### Descrição

public function Imagick::oilPaintImage(float `$radius`): bool

Aplica um filtro de efeito especial que simula uma pintura a óleo. Cada pixel é substituído pela cor mais frequente que ocorre em uma região circular definida pelo raio.

### Parâmetros

`radius`

  O raio da vizinhança circular.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::oilPaintImage()

    <?php
    function oilPaintImage($imagePath, $radius) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->oilPaintImage($radius);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::opaquePaintImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::opaquePaintImage — Altera o valor da cor de qualquer pixel que corresponda ao alvo

### Descrição

public function Imagick::opaquePaintImage(
mixed `$target`,
mixed `$fill`,
float `$fuzz`,
bool `$invert`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Altera qualquer pixel que corresponda à cor definida pelo preenchimento. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.8 ou superior.

### Parâmetros

`target`

  Objeto ImagickPixel ou uma string contendo a cor a ser alterada.

`fill`

  A cor de substituição.

`fuzz`

  A quantidade de fuzz. Por exemplo, definir fuzz como 10 e a cor vermelha nas intensidades de 100 e 102, respectivamente, agora são interpretadas como a mesma cor.

`invert`

  Se `true`, pinta qualquer pixel que não corresponda à cor alvo.

`channel`

  Fornece qualquer constante de canal que seja válida no modo de canal. Para aplicar a mais de um canal, constantes de canal devem ser combinadas usando operadores bit a bit. O padrão é `Imagick::CHANNEL_DEFAULT`. Consulte esta lista de constantes de canal

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::optimizeImageLayers

(PECL imagick 2, PECL imagick 3)

Imagick::optimizeImageLayers — Remove partes repetidas de imagens para otimizar

### Descrição

public function Imagick::optimizeImageLayers(): bool

Compara cada imagem com as formas dispostas em GIF da imagem anterior na sequência. A partir disso, tenta selecionar a menor imagem recortada para substituir cada quadro, preservando os resultados da animação. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Usando Imagick::optimizeImageLayers()

Lendo, otimizando e gravando uma imagem GIF

    <?php
    /* Cria novo objeto Imagick */
    $im = new Imagick("test.gif");

    /* otimizar as camadas da imagem */
    $im->optimizeImageLayers();

    /* grava a imagem de volta */
    $im->writeImages("test_optimized.gif", true);
    ?>

### Veja Também

- Imagick::compareImageLayers() - Retorna a região delimitadora máxima entre imagens
- Imagick::writeImages() - Grava uma imagem ou sequência de imagens
- Imagick::writeImage() - Grava uma imagem no nome de arquivo especificado

# Imagick::orderedPosterizeImage

(PECL imagick 2 >= 2.2.2, PECL imagick 3)

Imagick::orderedPosterizeImage — Executa um pontilhamento ordenado

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::orderedPosterizeImage(string `$threshold_map`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Executa um pontilhamento ordenado com base em vários mapas de limite de pontilhamento predefinidos, mas em vários níveis de intensidade, que podem ser diferentes para canais diferentes, de acordo com os argumentos de entrada. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.1 ou superior.

### Parâmetros

`threshold_map`

  Uma string contendo o nome do mapa de limite de pontilhamento a ser usado.

`channel`

  Forneça qualquer constante de canal válida para o modo de canal. Para aplicar a mais de um canal, combine constantes de tipo de canal usando operadores bit a bit. Consulte esta lista de constantes de canal.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::orderedPosterizeImage()

    <?php
    function orderedPosterizeImage($imagePath, $orderedPosterizeType) {
        $imagick = new \Imagick(realpath($imagePath));

        $imagick->orderedPosterizeImage($orderedPosterizeType);
        $imagick->setImageFormat('png');

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    // orderedPosterizeImage($imagePath, 'o4x4,3,3');
    // orderedPosterizeImage($imagePath, 'o8x8,6,6');
    orderedPosterizeImage($imagePath, 'h8x8a');

    ?>

# Imagick::paintFloodfillImage

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::paintFloodfillImage — Altera o valor da cor de qualquer pixel que corresponda ao alvo

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::paintFloodfillImage(
mixed `$fill`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Altera o valor da cor de qualquer pixel que corresponda ao alvo e seja um vizinho imediato. A partir do ImageMagick 6.3.8 este método foi preterido e Imagick::floodfillPaintImage() deve ser usado em seu lugar.

### Parâmetros

`fill`

  Objeto ImagickPixel ou uma string contendo a cor de preenchimento.

`fuzz`

  A quantidade de fuzz. Por exemplo, definir fuzz como 10 e a cor vermelha em intensidades de 100 e 102, respectivamente, agora são interpretadas como a mesma cor para fins de preenchimento.

`bordercolor`

  Objeto ImagickPixel ou uma string contendo a cor da borda.

`x`

  Coordenada X da posição inicial do preenchimento.

`y`

  Coordenada Y da posição inicial do preenchimento.

`channel`

  Fornece qualquer constante de canal que seja válida no modo de canal. Para aplicar a mais de um canal, constantes de canal devem ser combinadas usando operadores bit a bit. O padrão é `Imagick::CHANNEL_DEFAULT`. Consulte esta lista de constantes de canal

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::paintOpaqueImage

(PECL imagick 2, PECL imagick 3)

Imagick::paintOpaqueImage — Altera qualquer pixel que corresponda à cor

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::paintOpaqueImage(
mixed `$target`,
mixed `$fill`,
float `$fuzz`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Altera qualquer pixel que corresponda à cor definida pelo preenchimento.

### Parâmetros

`target`

  Altere esta cor de destino para a cor de preenchimento da imagem. Um objeto ImagickPixel ou uma string que representa a cor de destino.

`fill`

  Um objeto ImagickPixel ou uma string que representa a cor de preenchimento.

`fuzz`

  O membro fuzz da imagem define quanta tolerância é aceitável para considerar duas cores iguais.

`channel`

  Forneça qualquer constante de canal válida para o modo de canal. Para aplicar a mais de um canal, combine constantes de tipo de canal usando operadores bit a bit. Consulte esta lista de constantes de canal.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL imagick 2.1.0 | Agora permite uma string representando a cor como primeiro e segundo parâmetro. As versões anteriores permitiam apenas um objeto ImagickPixel.

# Imagick::paintTransparentImage

(PECL imagick 2, PECL imagick 3)

Imagick::paintTransparentImage — Altera qualquer pixel que corresponda à cor definida pelo preenchimento

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::paintTransparentImage(mixed `$target`, float `$alpha`, float `$fuzz`): bool

Altera qualquer pixel que corresponda à cor definida pelo preenchimento.

### Parâmetros

`target`

  Altere esta cor de destino para o valor de opacidade especificado na imagem.

`alpha`

  O nível de transparência: 1.0 é totalmente opaco e 0.0 é totalmente transparente.

`fuzz`

  O membro fuzz da imagem define quanta tolerância é aceitável para considerar duas cores iguais.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL imagick 2.1.0 | Agora permite uma string representando a cor como primeiro parâmetro. As versões anteriores permitiam apenas um objeto ImagickPixel.

# Imagick::pingImage

(PECL imagick 2, PECL imagick 3)

Imagick::pingImage — Busca atributos básicos sobre a imagem

### Descrição

public function Imagick::pingImage(string `$filename`): bool

Este método pode ser usado para consultar a largura, altura, tamanho e formato da imagem sem ler a imagem inteira na memória.

### Parâmetros

`filename`

  O nome do arquivo do qual as informações serão lidas.

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::pingImageBlob

(PECL imagick 2, PECL imagick 3)

Imagick::pingImageBlob — Busca atributos rapidamente

### Descrição

public function Imagick::pingImageBlob(string `$image`): bool

Este método pode ser usado para consultar a largura, altura, tamanho e formato da imagem sem ler a imagem inteira na memória. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.

### Parâmetros

`image`

  Uma string contendo a imagem.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Usando Imagick::pingImageBlob()

Consultando uma imagem a partir de uma string

    <?php
    /* lê conteúdo da imagem */
    $image = file_get_contents("test.jpg");

    /* Cria novo objeto Imagick */
    $im = new Imagick();

    /* passa a string para o objeto Imagick */
    $im->pingImageBlob($image);

    /* exibe largura e altura da imagem */
    echo $im->getImageWidth() . 'x' . $im->getImageHeight();
    ?>

### Veja Também

- Imagick::pingImage() - Busca atributos básicos sobre a imagem
- Imagick::pingImageFile() - Obtém atributos básicos de imagem de maneira leve
- Imagick::readImage() - Lê imagem de um arquivo
- Imagick::readImageBlob() - Lê imagem de uma string binária
- Imagick::readImageFile() - Lê imagem a partir de um descritor de arquivo

# Imagick::pingImageFile

(PECL imagick 2, PECL imagick 3)

Imagick::pingImageFile — Obtém atributos básicos de imagem de maneira leve

### Descrição

public function Imagick::pingImageFile(resource `$filehandle`, string `$fileName` = ?): bool

Este método pode ser usado para consultar a largura, altura, tamanho e formato da imagem sem ler a imagem inteira na memória. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.

### Parâmetros

`filehandle`

  Um identificador de arquivo aberto para a imagem.

`fileName`

  Nome de arquivo opcional para esta imagem.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Usando Imagick::pingImageFile()

Abrindo um local remoto

    <?php
    /* abrindo um local remoto com fopen */
    $fp = fopen("http://example.com/test.jpg");

    /* Cria novo objeto Imagick */
    $im = new Imagick();

    /* passa o identificador para o objeto Imagick */
    $im->pingImageFile($fp);
    ?>

### Veja Também

- Imagick::pingImage() - Busca atributos básicos sobre a imagem
- Imagick::pingImageBlob() - Busca atributos rapidamente
- Imagick::readImage() - Lê imagem de um arquivo
- Imagick::readImageBlob() - Lê imagem de uma string binária
- Imagick::readImageFile() - Lê imagem a partir de um descritor de arquivo

# Imagick::polaroidImage

(PECL imagick 2, PECL imagick 3)

Imagick::polaroidImage — Simula uma imagem Polaroid

### Descrição

public function Imagick::polaroidImage(ImagickDraw `$properties`, float `$angle`): bool

Simula uma imagem Polaroid. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.2 ou superior.

### Parâmetros

`properties`

  As propriedades da Polaroid.

`angle`

  O ângulo da Polaroid.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Um exemplo de Imagick::polaroidImage()

Um exemplo de uso de Imagick::polaroidImage()

    <?php
    /* Cria o objeto */
    $image = new Imagick('source.png');

    /* Define a opacidade */
    $image->polaroidImage(new ImagickDraw(), 25);

    /* exibe a imagem */
    header('Content-type: image/png');
    echo $image;

    ?>

# Imagick::posterizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::posterizeImage — Reduz a imagem a um número limitado de níveis de cor

### Descrição

public function Imagick::posterizeImage(int `$levels`, bool `$dither`): bool

Reduz a imagem a um número limitado de níveis de cor.

### Parâmetros

`levels`

`dither`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::posterizeImage()

    <?php
    function posterizeImage($imagePath, $posterizeType, $numberLevels) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->posterizeImage($numberLevels, $posterizeType);
        $imagick->setImageFormat('png');
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    posterizeImage($imagePath, \Imagick::DITHERMETHOD_RIEMERSMA, 8);

    ?>

# Imagick::previewImages

(PECL imagick 2, PECL imagick 3)

Imagick::previewImages — Identifica rapidamente os parâmetros apropriados para processamento de imagem

### Descrição

public function Imagick::previewImages(int `$preview`): bool

Coloca 9 miniaturas da imagem especificada lado a lado com uma operação de processamento de imagem aplicada em intensidades variadas. Isto é útil para identificar rapidamente um parâmetro apropriado para uma operação de processamento de imagem.

### Parâmetros

`preview`

  Tipo de pré-visualização. Consulte as constantes de tipo de pré-visualização

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::previousImage

(PECL imagick 2, PECL imagick 3)

Imagick::previousImage — Passa para a imagem anterior no objeto

### Descrição

public function Imagick::previousImage(): bool

Associa a imagem anterior em uma lista de imagens ao objeto Imagick.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::profileImage

(PECL imagick 2, PECL imagick 3)

Imagick::profileImage — Adiciona ou remove um perfil de uma imagem

### Descrição

public function Imagick::profileImage(string `$name`, string `$profile` = ?): bool

Adiciona ou remove um perfil ICC, IPTC ou genérico de uma imagem. Se `profile` for `null`, o perfil que tiver sido adicionado será removido da imagem em vez de adicionado.

Para remover todos os perfis da imagem, use `'*'` no parâmetro `name` e `null` no parâmetro `profile`.

### Parâmetros

`name`
  O nome do perfil.
`profile`
  Os dados do perfil. Se o valor for definido para `null`, o perfil especificado será removido.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::quantizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::quantizeImage — Analisa as cores dentro de uma imagem de referência

### Descrição

public function Imagick::quantizeImage(
int `$numberColors`,
int `$colorspace`,
int `$treedepth`,
bool `$dither`,
bool `$measureError`
): bool

### Parâmetros

`numberColors`

`colorspace`

`treedepth`

`dither`

`measureError`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::quantizeImage()

    <?php
    function quantizeImage($imagePath, $numberColors, $colorSpace, $treeDepth, $dither) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->quantizeImage($numberColors, $colorSpace, $treeDepth, $dither, false);
        $imagick->setImageFormat('png');
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::quantizeImages

(PECL imagick 2, PECL imagick 3)

Imagick::quantizeImages — Analisa as cores dentro de uma sequência de imagens

### Descrição

public function Imagick::quantizeImages(
int `$numberColors`,
int `$colorspace`,
int `$treedepth`,
bool `$dither`,
bool `$measureError`
): bool

### Parâmetros

`numberColors`

`colorspace`

`treedepth`

`dither`

`measureError`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::queryFontMetrics

(PECL imagick 2, PECL imagick 3)

Imagick::queryFontMetrics — Retorna um array representando as métricas da fonte

### Descrição

public function Imagick::queryFontMetrics(ImagickDraw `$properties`, string `$text`, bool `$multiline` = ?): array

Retorna um array multi-dimensional representando as métricas da fonte.

### Parâmetros

`properties`

  Objeto ImagickDraw contendo propriedades de fonte

`text`

  O texto

`multiline`

  Parâmetro multilinha. Se deixado em branco, será detectado automaticamente.

### Valor Retornado

Retorna um array multi-dimensional representando as métricas da fonte.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Usando Imagick::queryFontMetrics()

Consulta as métricas do texto e despeja os resultados na tela.

    <?php
    /* Cria um novo objeto Imagick */
    $im = new Imagick();

    /* Cria um novo objeto ImagickDraw */
    $draw = new ImagickDraw();

    /* Define a fonte */
    $draw->setFont('/caminho/para/fonte.ttf');

    /* Despeja a métrica da fonte, detecta multilinhas automaticamente */
    var_dump($im->queryFontMetrics($draw, "Olá, Mundo!"));
    ?>

# Imagick::queryFonts

(PECL imagick 2, PECL imagick 3)

Imagick::queryFonts — Retorna as fontes configuradas

### Descrição

public static function Imagick::queryFonts(string `$pattern` = "*"): array

Retorna as fontes configuradas.

### Parâmetros

`pattern`

  O padrão de consulta

### Valor Retornado

Retorna um array contendo as fontes configuradas.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::queryFonts()

    <?php
        $output = '';
        $output .= "As fontes que correspondem a 'Helvetica*' são:<br/>";

        $fontList = \Imagick::queryFonts("Helvetica*");

        foreach ($fontList as $fontName) {
            $output .= '<li>'. $fontName."</li>";
        }

        return $output;

    ?>

# Imagick::queryFormats

(PECL imagick 2, PECL imagick 3)

Imagick::queryFormats — Retorna formatos suportados pelo Imagick

### Descrição

public static function Imagick::queryFormats(string `$pattern` = "*"): array

Retorna formatos suportados pelo Imagick.

### Parâmetros

`pattern`

### Valor Retornado

Retorna um array contendo os formatos suportados pelo Imagick.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::queryFormats()

    <?php
        function render() {
            $output = "";
            $input = \Imagick::queryformats();
            $columns = 6;

            $output .= "<table border='2'>";

            for ($i=0; $i < count($input); $i += $columns) {
                $output .= "<tr>";
                for ($c=0; $c<$columns; $c++) {
                    $output .= "<td>";
                    if (($i + $c) <  count($input)) {
                        $output .= $input[$i + $c];
                    }
                    $output .= "</td>";
                }
                $output .= "</tr>";
            }

            $output .= "</table>";

            return $output;
        }

    ?>

# Imagick::radialBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::radialBlurImage — Desfoca uma imagem de forma radial

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::radialBlurImage(float `$angle`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Desfoca uma imagem de forma radial.

### Parâmetros

`angle`

`channel`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::radialBlurImage()

    <?php
    function radialBlurImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        // Desfoce 3 vezes com raios diferentes
        $imagick->radialBlurImage(3);
        $imagick->radialBlurImage(5);
        $imagick->radialBlurImage(7);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::raiseImage

(PECL imagick 2, PECL imagick 3)

Imagick::raiseImage — Cria um efeito simulado de botão 3D

### Descrição

public function Imagick::raiseImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`,
bool `$raise`
): bool

Cria um efeito simulado de botão tridimensional, clareando e escurecendo as bordas da imagem. Os membros "width" e "height" definem a largura das bordas vertical e horizontal do efeito.

### Parâmetros

`width`

`height`

`x`

`y`

`raise`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::raiseImage()

    <?php
    function raiseImage($imagePath, $width, $height, $x, $y, $raise) {
        $imagick = new \Imagick(realpath($imagePath));

        // verificando o efeito de x e y
        $imagick->raiseImage($width, $height, $x, $y, $raise);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::randomThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::randomThresholdImage — Cria uma imagem de alto contraste e duas cores

### Descrição

public function Imagick::randomThresholdImage(float `$low`, float `$high`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Altera o valor de pixels individuais com base na intensidade de cada pixel em comparação com o limite. O resultado é uma imagem de alto contraste e duas cores. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.

### Parâmetros

`low`

  O ponto baixo.

`high`

  O ponto alto.

`channel`

  Forneça qualquer constante de canal válida para o modo de canal. Para aplicar a mais de um canal, combine constantes de tipo de canal usando operadores bit a bit. Consulte esta lista de constantes de canal.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::randomThresholdImage()

    <?php
    function randomThresholdimage($imagePath, $lowThreshold, $highThreshold, $channel) {
        $imagick = new \Imagick(realpath($imagePath));

        $imagick->randomThresholdimage(
            $lowThreshold * \Imagick::getQuantum(),
            $highThreshold * \Imagick::getQuantum(),
            $channel
        );
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::readImage

(PECL imagick 2, PECL imagick 3)

Imagick::readImage — Lê imagem de um arquivo

### Descrição

public function Imagick::readImage(string `$filename`): bool

Lê imagem de um arquivo.

### Parâmetros

`filename`

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::readImageBlob

(PECL imagick 2, PECL imagick 3)

Imagick::readImageBlob — Lê imagem de uma string binária

### Descrição

public function Imagick::readImageBlob(string `$image`, string `$filename` = ?): bool

Lê uma imagem a partir de uma string binária.

### Parâmetros

`image`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::readImageBlob()

    <?php
    function readImageBlob() {
        $base64 = "iVBORw0KGgoAAAANSUhEUgAAAM0AAAD
     NCAMAAAAsYgRbAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5c
     cllPAAAABJQTFRF3NSmzMewPxIG//ncJEJsldTou1jHgAAAARBJREFUeNrs2EEK
     gCAQBVDLuv+V20dENbMY831wKz4Y/VHb/5RGQ0NDQ0NDQ0NDQ0NDQ0NDQ
     0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0PzMWtyaGhoaGhoaGhoaGhoaGhoxtb0QGho
     aGhoaGhoaGhoaGhoaMbRLEvv50VTQ9OTQ5OpyZ01GpM2g0bfmDQaL7S+ofFC6x
     v3ZpxJiywakzbvd9r3RWPS9I2+MWk0+kbf0Hih9Y17U0nTHibrDDQ0NDQ0NDQ0
     NDQ0NDQ0NTXbRSL/AK72o6GhoaGhoRlL8951vwsNDQ0NDQ1NDc0WyHtDTEhD
     Q0NDQ0NTS5MdGhoaGhoaGhoaGhoaGhoaGhoaGhoaGposzSHAAErMwwQ2HwRQ
     AAAAAElFTkSuQmCC";

        $imageBlob = base64_decode($base64);

        $imagick = new Imagick();
        $imagick->readImageBlob($imageBlob);

        header("Content-Type: image/png");
        echo $imagick;
    }

    ?>

# Imagick::readImageFile

(PECL imagick 2, PECL imagick 3)

Imagick::readImageFile — Lê imagem a partir de um descritor de arquivo

### Descrição

public function Imagick::readImageFile(resource `$filehandle`, string `$fileName` = `null`): bool

Lê uma imagem a partir de um descritor de arquivo aberto.

### Parâmetros

`filehandle`

`fileName`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::readimages

(PECL imagick 2, PECL imagick 3)

Imagick::readimages — Lê imagens de um array de arquivos

### Descrição

public function Imagick::readImages(array `$filenames`): bool

Lê imagens a partir de um array de arquivos. Todas as imagens são mantidas em um único objeto Imagick.

### Parâmetros

`filenames`

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::recolorImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::recolorImage — Recolore imagem

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::recolorImage(array `$matrix`): bool

Traslada, dimensiona, cisalha ou rotaciona as cores da imagem. Este método suporta matrizes de tamanho variável, mas normalmente a matriz 5x5 é usada para RGBA e 6x6 é usada para CMYK. A última linha deve conter os valores normalizados. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.6 ou superior.

### Parâmetros

`matrix`

  A matriz contendo os valores das cores

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::recolorImage()

    <?php
    function recolorImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $remapColor = [ 1, 0, 0,
            0, 0, 1,
            0, 1, 0,];

    //$remapColor = [
    //    1.438, -0.122, -0.016,  0, 0, -0.03,
    //    -0.062,  1.378, -0.016,  0, 0,  0.05,
    //    -0.062, -0.122, 1.483,   0, 0, -0.02,
    //];

        @$imagick->recolorImage($remapColor);

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Veja Também

- Imagick::displayImage() - Exibe uma imagem

# Imagick::reduceNoiseImage

(PECL imagick 2, PECL imagick 3)

Imagick::reduceNoiseImage — Suaviza os contornos de uma imagem

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::reduceNoiseImage(float `$radius`): bool

Suaviza os contornos de uma imagem enquanto preserva as informações das bordas. O algoritmo funciona substituindo cada pixel pelo seu vizinho de valor mais próximo. Um vizinho é definido pelo raio. Use um raio de 0 e Imagick::reduceNoiseImage() seleciona um raio adequado automaticamente.

### Parâmetros

`radius`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::reduceNoiseImage()

    <?php
    function reduceNoiseImage($imagePath, $reduceNoise) {
        $imagick = new \Imagick(realpath($imagePath));
        @$imagick->reduceNoiseImage($reduceNoise);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::remapImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::remapImage — Remapeia as cores da imagem

### Descrição

public function Imagick::remapImage(Imagick `$replacement`, int `$DITHER`): bool

Substitui as cores de uma imagem pelas definidas por `replacement`. As cores são substituídas pela cor mais próxima possível. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.5 ou superior.

### Parâmetros

`replacement`

  Um objeto Imagick contendo as cores de substituição

`DITHER`

  Consulte a lista de constantes de método de pontilhamento

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::removeImage

(PECL imagick 2, PECL imagick 3)

Imagick::removeImage — Remove uma imagem da lista de imagens

### Descrição

public function Imagick::removeImage(): bool

Remove uma imagem da lista de imagens.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::removeImageProfile

(PECL imagick 2, PECL imagick 3)

Imagick::removeImageProfile — Remove o perfil de imagem nomeado e o retorna

### Descrição

public function Imagick::removeImageProfile(string `$name`): string

Remove o perfil de imagem nomeado e o retorna.

### Parâmetros

`name`

### Valor Retornado

Retorna uma string contendo o perfil da imagem.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::render

(PECL imagick 2, PECL imagick 3)

Imagick::render — Renderiza todos os comandos de desenho anteriores

### Descrição

public function Imagick::render(): bool

Renderiza todos os comandos de desenho anteriores.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::resampleImage

(PECL imagick 2, PECL imagick 3)

Imagick::resampleImage — Reamostra imagem para a resolução desejada

### Descrição

public function Imagick::resampleImage(
float `$x_resolution`,
float `$y_resolution`,
int `$filter`,
float `$blur`
): bool

Reamostra imagem para a resolução desejada.

### Parâmetros

`x_resolution`

`y_resolution`

`filter`

`blur`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::resampleImage()

    <?php
    function resampleImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));

        $imagick->resampleImage(200, 200, \Imagick::FILTER_LANCZOS, 1);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::resetImagePage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::resetImagePage — Redefine página de imagem

### Descrição

public function Imagick::resetImagePage(string `$page`): bool

A definição da página como uma string. A string deve ser no formato WxH+x+y. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.6 ou superior.

### Parâmetros

`page`

  A definição da página. Por exemplo, `7168x5147+0+0`.

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::resizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::resizeImage — Dimensiona uma imagem

### Descrição

public function Imagick::resizeImage(
int `$columns`,
int `$rows`,
int `$filter`,
float `$blur`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool

Dimensiona uma imagem para as dimensões desejadas com um filtro.

> Nota: O comportamento do parâmetro `bestfit` mudou na Imagick 3.0.0. Antes desta versão, dadas as dimensões 400x400, uma imagem de dimensões 200x150 permaneceria intocada. Na Imagick 3.0.0 e superiores, a imagem será escalada para 400x300, pois este é o "melhor ajuste" para as dimensões fornecidas. Se o parâmetro `bestfit` for usado, tanto a largura quanto a altura devem ser informadas.

### Parâmetros

`columns`

  Largura da imagem

`rows`

  Altura da imagem

`filter`

  Consulte a lista de constantes de filtros.

`blur`

  O fator de desfoque onde > 1 é desfocado, < 1 é nítido.

`bestfit`

  Parâmetro de ajuste opcional.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL imagick 2.1.0 | Adicionado parâmetro de ajuste opcional. Este método agora oferece suporte ao dimensionamento proporcional. Passe zero como qualquer parâmetro para dimensionamento proporcional.

### Exemplos

Exemplo #1 Exemplo de Imagick::resizeImage()

    <?php
    function resizeImage($imagePath, $width, $height, $filterType, $blur, $bestFit, $cropZoom) {
        // O fator de desfoque onde > 1 é desfocado, < 1 é nítido.
        $imagick = new \Imagick(realpath($imagePath));

        $imagick->resizeImage($width, $height, $filterType, $blur, $bestFit);

        $cropWidth = $imagick->getImageWidth();
        $cropHeight = $imagick->getImageHeight();

        if ($cropZoom) {
            $newWidth = $cropWidth / 2;
            $newHeight = $cropHeight / 2;

            $imagick->cropimage(
                $newWidth,
                $newHeight,
                ($cropWidth - $newWidth) / 2,
                ($cropHeight - $newHeight) / 2
            );

            $imagick->scaleimage(
                $imagick->getImageWidth() * 4,
                $imagick->getImageHeight() * 4
            );
        }

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::rollImage

(PECL imagick 2, PECL imagick 3)

Imagick::rollImage — Desloca uma imagem

### Descrição

public function Imagick::rollImage(int `$x`, int `$y`): bool

Desloca uma imagem conforme definido por x e y.

### Parâmetros

`x`

  O deslocamento X.

`y`

  O deslocamento Y.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::rollImage()

    <?php
    function rollImage($imagePath, $rollX, $rollY) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->rollimage($rollX, $rollY);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::rotateImage

(PECL imagick 2, PECL imagick 3)

Imagick::rotateImage — Rotaciona uma imagem

### Descrição

public function Imagick::rotateImage(mixed `$background`, float `$degrees`): bool

Rotaciona uma imagem no número especificado de graus. Os triângulos vazios que sobrarem da rotação da imagem são preenchidos com a cor de fundo.

### Parâmetros

`background`

  A cor de fundo

`degrees`

  Ângulo de rotação, em graus. O ângulo de rotação é interpretado como o número de graus para rotacionar a imagem no sentido horário.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL imagick 2.1.0 | Agora permite uma string representando a cor como primeiro parâmetro. As versões anteriores permitiam apenas um objeto ImagickPixel.

### Exemplos

Exemplo #1 Exemplo de Imagick::rotateImage()

    <?php
    function rotateImage($imagePath, $angle, $color) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->rotateimage($color, $angle);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::rotationalBlurImage

(PECL imagick 3 >= 3.3.0)

Imagick::rotationalBlurImage — Desfoca uma imagem de forma rotacional

### Descrição

public function Imagick::rotationalBlurImage(float `$angle`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Desfoca uma imagem de forma rotacional.

### Parâmetros

`angle`

  O ângulo no qual o desfoque será aplicado.

`channel`

  Fornece qualquer constante de canal que seja válida no modo de canal. Para aplicar a mais de um canal, constantes de canal devem ser combinadas usando operadores bit a bit. O padrão é `Imagick::CHANNEL_DEFAULT`. Consulte esta lista de constantes de canal

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::rotationalBlurImage()

    <?php
    function rotationalBlurImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->rotationalBlurImage(3);
        $imagick->rotationalBlurImage(5);
        $imagick->rotationalBlurImage(7);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::roundCorners

(PECL imagick 2, PECL imagick 3)

Imagick::roundCorners — Arredonda os cantos da imagem

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::roundCorners(
float `$x_rounding`,
float `$y_rounding`,
float `$stroke_width` = 10,
float `$displace` = 5,
float `$size_correction` = -6
): bool

Arredonda os cantos da imagem. Os primeiros dois parâmetros controlam a quantidade de arredondamento e os três últimos parâmetros podem ser usados ​​para ajuste fino do processo de arredondamento. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior. Este método não estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 7.0.0 ou superior.

### Parâmetros

`x_rounding`

  Arredondamento X.

`y_rounding`

  Arredondamento Y.

`stroke_width`

  Largura do traço.

`displace`

  Deslocamento da imagem.

`size_correction`

  Correção de tamanho.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Usando Imagick::roundCorners()

Arredonda os cantos da imagem.

    <?php

    $image = new Imagick();
    $image->newPseudoImage(100, 100, "magick:rose");
    $image->setImageFormat("png");

    $image->roundCorners(5,3);
    $image->writeImage("rounded.png");
    ?>

# Imagick::sampleImage

(PECL imagick 2, PECL imagick 3)

Imagick::sampleImage — Dimensiona uma imagem com amostragem de pixels

### Descrição

public function Imagick::sampleImage(int `$columns`, int `$rows`): bool

Dimensiona uma imagem para as dimensões desejadas com amostragem de pixels. Ao contrário de outros métodos de dimensionamento, este método não introduz nenhuma cor adicional na imagem dimensionada.

### Parâmetros

`columns`

`rows`

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::scaleImage

(PECL imagick 2, PECL imagick 3)

Imagick::scaleImage — Dimensiona o tamanho de uma imagem

### Descrição

public function Imagick::scaleImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool

Dimensiona o tamanho de uma imagem para as dimensões fornecidas. O outro parâmetro será calculado se 0 for passado como qualquer um dos parâmetros.

> Nota: O comportamento do parâmetro `bestfit` mudou na Imagick 3.0.0. Antes desta versão, dadas as dimensões 400x400, uma imagem de dimensões 200x150 permaneceria intocada. Na Imagick 3.0.0 e superiores, a imagem será escalada para 400x300, pois este é o "melhor ajuste" para as dimensões fornecidas. Se o parâmetro `bestfit` for usado, tanto a largura quanto a altura devem ser informadas.

### Parâmetros

`columns`

`rows`

`bestfit`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL imagick 2.1.0 | Adicionado parâmetro de ajuste opcional. Este método agora oferece suporte ao dimensionamento proporcional. Passe zero como qualquer parâmetro para dimensionamento proporcional.

### Exemplos

Exemplo #1 Exemplo de Imagick::scaleImage()

    <?php
    function scaleImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->scaleImage(150, 150, true);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::segmentImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::segmentImage — Segmenta uma imagem

### Descrição

public function Imagick::segmentImage(
int `$COLORSPACE`,
float `$cluster_threshold`,
float `$smooth_threshold`,
bool `$verbose` = `false`
): bool

Analisa a imagem e identifica unidades semelhantes. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.5 ou superior.

### Parâmetros

`COLORSPACE`

  Uma das constantes COLORSPACE.

`cluster_threshold`

  Uma porcentagem que descreve o número mínimo de pixels contidos em um hexaedro antes de ser considerado válido.

`smooth_threshold`

  Elimina o ruído do histograma.

`verbose`

  Informa se devem ser geradas informações detalhadas sobre classes reconhecidas.

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de Imagick::segmentImage()

    <?php
    function segmentImage($imagePath, $colorSpace, $clusterThreshold, $smoothThreshold) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->segmentImage($colorSpace, $clusterThreshold, $smoothThreshold);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    segmentImage($imagePath, \Imagick::COLORSPACE_RGB, 5, 5);

    ?>

# Imagick::selectiveBlurImage

(PECL imagick 3 >= 3.3.0)

Imagick::selectiveBlurImage — Desfocar seletivamente uma imagem dentro de um limite de contraste

### Descrição

public function Imagick::selectiveBlurImage(
float `$radius`,
float `$sigma`,
float `$threshold`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Desfoca seletivamente uma imagem dentro de um limite de contraste. É semelhante à máscara de nitidez que torna tudo mais nítido com contraste acima de um certo limite.

### Parâmetros

`radius`

`sigma`

`threshold`

`channel`

  Fornece qualquer constante de canal que seja válida no modo de canal. Para aplicar a mais de um canal, constantes de canal devem ser combinadas usando operadores bit a bit. O padrão é `Imagick::CHANNEL_DEFAULT`. Consulte esta lista de constantes de canal

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::selectiveBlurImage()

    <?php
    function selectiveBlurImage($imagePath, $radius, $sigma, $threshold, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->selectiveBlurImage($radius, $sigma, $threshold, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::separateImageChannel

(PECL imagick 2, PECL imagick 3)

Imagick::separateImageChannel — Separa um canal da imagem

### Descrição

public function Imagick::separateImageChannel(int `$channel`): bool

Separa um canal da imagem e retorna uma imagem em tons de cinza. Um canal é um componente de cor específico de cada pixel da imagem.

### Parâmetros

`channel`

  Informa qual canal será retornado. Para espaços de cores diferentes de RGB, podem ser usadas as constantes CHANNEL_RED, CHANNEL_GREEN e CHANNEL_BLUE para indicar o 1º, 2º e 3º canais.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::separateImageChannel()

    <?php
    function separateImageChannel($imagePath, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->separateimagechannel($channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    separateImageChannel($imagePath, \Imagick::CHANNEL_GREEN);

    ?>

# Imagick::sepiaToneImage

(PECL imagick 2, PECL imagick 3)

Imagick::sepiaToneImage — Aplica tons de sépia em uma imagem

### Descrição

public function Imagick::sepiaToneImage(float `$threshold`): bool

Aplica um efeito especial à imagem, semelhante ao efeito obtido em uma câmara escura fotográfica com aplicação de tom de sépia. O limite varia de 0 a QuantumRange e é uma medida da extensão da tonalidade sépia. Um limite de 80 é um bom ponto de partida para um tom razoável.

### Parâmetros

`threshold`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::sepiaToneImage()

    <?php
    function sepiaToneImage($imagePath, $sepia) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->sepiaToneImage($sepia);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setBackgroundColor

(PECL imagick 2, PECL imagick 3)

Imagick::setBackgroundColor — Define a cor de fundo padrão do objeto

### Descrição

public function Imagick::setBackgroundColor(mixed `$background`): bool

Define a cor de fundo padrão do objeto.

### Parâmetros

`background`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL imagick 2.1.0 | Agora permite uma string representando a cor como parâmetro. As versões anteriores permitiam apenas um objeto ImagickPixel.

# Imagick::setColorspace

(PECL imagick 3)

Imagick::setColorspace — Define espaço de cores

### Descrição

public function Imagick::setColorspace(int `$COLORSPACE`): bool

Define o valor global do espaço de cores para o objeto. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.5.7 ou superior.

### Parâmetros

`COLORSPACE`

  Uma das constantes COLORSPACE.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::setCompression

(PECL imagick 2, PECL imagick 3)

Imagick::setCompression — Define o tipo de compactação padrão do objeto

### Descrição

public function Imagick::setCompression(int `$compression`): bool

Define o tipo de compactação padrão do objeto.

### Parâmetros

`compression`

  O tipo de comactação. Consulte as constantes Imagick::COMPRESSION_*.

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::setCompressionQuality

(PECL imagick 2, PECL imagick 3)

Imagick::setCompressionQuality — Define a qualidade de compactação padrão do objeto

### Descrição

public function Imagick::setCompressionQuality(int `$quality`): bool

Define a qualidade de compactação padrão do objeto.

Cuidado

Este método só funciona para novas imagens, por ex. aqueles criados através do Imagick::newPseudoImage. Para imagens existentes deve ser usado o método Imagick::setImageCompressionQuality().

### Parâmetros

`quality`

  Um int entre 1 e 100, 1 = alta compactação, 100 baixa compactação.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::setCompressionQuality()

    <?php
    function setCompressionQuality($imagePath, $quality) {

        $backgroundImagick = new \Imagick(realpath($imagePath));
        $imagick = new \Imagick();
        $imagick->setCompressionQuality($quality);
        $imagick->newPseudoImage(
            $backgroundImagick->getImageWidth(),
            $backgroundImagick->getImageHeight(),
            'canvas:white'
        );

        $imagick->compositeImage(
            $backgroundImagick,
            \Imagick::COMPOSITE_ATOP,
            0,
            0
        );

        $imagick->setFormat("jpg");
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setFilename

(PECL imagick 2, PECL imagick 3)

Imagick::setFilename — Define o nome do arquivo antes de ler ou gravar a imagem

### Descrição

public function Imagick::setFilename(string `$filename`): bool

Define o nome do arquivo antes de ler ou gravar um arquivo de imagem.

### Parâmetros

`filename`

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::setFirstIterator

(PECL imagick 2, PECL imagick 3)

Imagick::setFirstIterator — Define o iterador Imagick para a primeira imagem

### Descrição

public function Imagick::setFirstIterator(): bool

Define o iterador Imagick para a primeira imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::setFont

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::setFont — Define a fonte

### Descrição

public function Imagick::setFont(string `$font`): bool

Define a propriedade da fonte do objeto. Este método pode ser usado, por exemplo, para definir a fonte do pseudoformato "caption:". A fonte precisa ser definida na configuração do ImageMagick ou deve existir um arquivo com o nome definido no parâmetro `font`. Este método não deve ser confundido com ImagickDraw::setFont() que define a fonte para um objeto ImagickDraw específico. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.7 ou superior.

### Parâmetros

`font`

  Nome da fonte ou um nome de arquivo.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Um exemplo de Imagick::setFont()

Exemplo de uso de Imagick::setFont

    <?php
    /* Cria novo objeto Imagick */
    $im = new Imagick();

    /* Define a fonte para o objeto */
    $im->setFont("example.ttf");

    /* Cria nova legenda */
    $im->newPseudoImage(100, 100, "caption:Hello");

    /* Faz algo com a imagem */
    ?>

### Veja Também

- Imagick::getFont() - Obtem a fonte
- ImagickDraw::setFont() - Define a fonte totalmente especificada a ser usada ao fazer anotações com texto
- ImagickDraw::getFont() - Retorna a fonte

# Imagick::setFormat

(PECL imagick 2, PECL imagick 3)

Imagick::setFormat — Define o formato do objeto Imagick

### Descrição

public function Imagick::setFormat(string `$format`): bool

Define o formato do objeto Imagick.

### Parâmetros

`format`

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::setGravity

(PECL imagick 2 >= 2.2.0, PECL imagick 3)

Imagick::setGravity — Define a gravidade

### Descrição

public function Imagick::setGravity(int `$gravity`): bool

Define a propriedade de gravidade global para o objeto Imagick. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.0 ou superior.

### Parâmetros

`gravity`

  A propriedade da gravidade. Consulte a lista de constantes de gravidade.

### Valor Retornado

Nenhum valor é retornado.

# Imagick::setImage

(PECL imagick 2, PECL imagick 3)

Imagick::setImage — Substitui imagem no objeto

### Descrição

public function Imagick::setImage(Imagick `$replace`): bool

Substitui a sequência de imagens atual pela imagem do objeto de substituição.

### Parâmetros

`replace`

  O objeto Imagick de substituição

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Um exemplo de Imagick::setImage()

Um exemplo de uso de Imagick::setImage()

    <?php
    /* Cria o objeto */
    $image = new Imagick('origem.jpg');
    $replace = new Imagick('substituto.jpg');

    /* origem.jpg é substituído por substituto.jpg */
    $image->setImage($replace);

    /* exibe a imagem */
    header('Content-type: image/jpeg');
    echo $image;

    ?>

# Imagick::setImageAlphaChannel

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::setImageAlphaChannel — Define o canal alfa da imagem

### Descrição

public function Imagick::setImageAlphaChannel(int `$mode`): bool

Ativa ou desativa o canal alfa da imagem. O parâmetro `mode` deve ser uma das constantes `Imagick::ALPHACHANNEL_*`. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.8 ou superior.

### Parâmetros

`mode`

  Uma das constantes `Imagick::ALPHACHANNEL_*`.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Veja Também

- Imagick::setImageMatte() - Define o canal fosco da imagem
- Constantes de Canal Alfa do Imagick

# Imagick::setImageArtifact

(PECL imagick 3)

Imagick::setImageArtifact — Definir artefato de imagem

### Descrição

public function Imagick::setImageArtifact(string `$artifact`, string `$value`): bool

Associa um artefato à imagem. A diferença entre propriedades de imagem e artefatos de imagem é que as propriedades são públicas e os artefatos são privados. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.5.7 ou superior.

### Parâmetros

`artifact`

  O nome do artefato

`value`

  O valor do artefato

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::setImageArtifact()

    <?php
    function setImageArtifact() {

        $src1 = new \Imagick(realpath("./images/artifact/source1.png"));
        $src2 = new \Imagick(realpath("./images/artifact/source2.png"));

        $src2->setImageVirtualPixelMethod(\Imagick::VIRTUALPIXELMETHOD_TRANSPARENT);
        $src2->setImageArtifact('compose:args', "1,0,-0.5,0.5");
        $src1->compositeImage($src2, Imagick::COMPOSITE_MATHEMATICS, 0, 0);

        $src1->setImageFormat('png');
        header("Content-Type: image/png");
        echo $src1->getImagesBlob();
    }

    ?>

### Veja Também

- Imagick::getImageArtifact() - Obtém artefato da imagem
- Imagick::deleteImageArtifact() - Excluir artefato de imagem

# Imagick::setImageAttribute

(PECL imagick 2, PECL imagick 3)

Imagick::setImageAttribute — Define um atributo de imagem

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::setImageAttribute(string `$key`, string `$value`): bool

Define um atributo de imagem.

### Parâmetros

`key`

`value`

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::setImageBackgroundColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBackgroundColor — Define a cor de fundo da imagem

### Descrição

public function Imagick::setImageBackgroundColor(mixed `$background`): bool

Define a cor de fundo da imagem.

### Parâmetros

`background`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL imagick 2.1.0 | Agora permite uma string representando a cor como parâmetro. As versões anteriores permitiam apenas um objeto ImagickPixel.

# Imagick::setImageBias

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBias — Define o ajuste (bias) da imagem para qualquer método que faça convolução em uma imagem

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::setImageBias(float `$bias`): bool

Define o ajuste (bias) da imagem para qualquer método que faça convolução em uma imagem (ex.: Imagick::ConvolveImage()).

### Parâmetros

`bias`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::setImageBias()

    <?php
    //requires ImageMagick version 6.9.0-1 to have an effect on convolveImage
    function setImageBias($bias) {
        $imagick = new \Imagick(realpath("images/stack.jpg"));

        $xKernel = array(
            -0.70, 0, 0.70,
            -0.70, 0, 0.70,
            -0.70, 0, 0.70
        );

        $imagick->setImageBias($bias * \Imagick::getQuantum());
        $imagick->convolveImage($xKernel, \Imagick::CHANNEL_ALL);

        $imagick->setImageFormat('png');

        header('Content-type: image/png');
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setImageBiasQuantum

(PECL imagick 3 >= 3.3.0)

Imagick::setImageBiasQuantum — Define o ajuste (bias) da imagem

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::setImageBiasQuantum(float `$bias`): void

Define o ajuste da imagem. O ajuste deve ser dimensionado entre `0` (sem ajuste) a `1` (valor Quantum).

### Parâmetros

`bias`

### Valor Retornado

# Imagick::setImageBluePrimary

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBluePrimary — Define o ponto primário azul da cromaticidade da imagem

### Descrição

public function Imagick::setImageBluePrimary(float `$x`, float `$y`): bool

Define o ponto primário azul da cromaticidade da imagem.

### Parâmetros

`x`

`y`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::setImageBorderColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBorderColor — Define a cor da borda da imagem

### Descrição

public function Imagick::setImageBorderColor(mixed `$border`): bool

Define a cor da borda da imagem.

### Parâmetros

`border`

  A cor da borda.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL imagick 2.1.0 | Agora permite uma string representando a cor como parâmetro. As versões anteriores permitiam apenas um objeto ImagickPixel.

# Imagick::setImageChannelDepth

(PECL imagick 2, PECL imagick 3)

Imagick::setImageChannelDepth — Define a profundidade de um canal de imagem específico

### Descrição

public function Imagick::setImageChannelDepth(int `$channel`, int `$depth`): bool

Define a profundidade de um canal de imagem específico.

### Parâmetros

`channel`

`depth`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::setImageClipMask

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::setImageClipMask — Define a máscara de recorte da imagem

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::setImageClipMask(Imagick `$clip_mask`): bool

Define a máscara de recorte da imagem a partir de outro objeto Imagick. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.6 ou superior.

### Parâmetros

`clip_mask`

  O objeto Imagick que contém a máscara de recorte.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::setImageClipMask()

    <?php
    function setImageClipMask($imagePath) {
        $imagick = new \Imagick();
        $imagick->readImage(realpath($imagePath));

        $width = $imagick->getImageWidth();
        $height = $imagick->getImageHeight();

        $clipMask = new \Imagick();
        $clipMask->newPseudoImage(
            $width,
            $height,
            "canvas:transparent"
        );

        $draw = new \ImagickDraw();
        $draw->setFillColor('white');
        $draw->circle(
            $width / 2,
            $height / 2,
            ($width / 2) + ($width / 4),
            $height / 2
        );
        $clipMask->drawImage($draw);
        $imagick->setImageClipMask($clipMask);

        $imagick->negateImage(false);
        $imagick->setFormat("png");

        header("Content-Type: image/png");
        echo $imagick->getImagesBlob();

    }

    ?>

# Imagick::setImageColormapColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageColormapColor — Define a cor do índice do mapa de cores especificado

### Descrição

public function Imagick::setImageColormapColor(int `$index`, ImagickPixel `$color`): bool

Define a cor do índice do mapa de cores especificado.

### Parâmetros

`index`

`color`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::setImageColorspace

(PECL imagick 2, PECL imagick 3)

Imagick::setImageColorspace — Define o espaço de cores da imagem

### Descrição

public function Imagick::setImageColorspace(int `$colorspace`): bool

Define o espaço de cores da imagem. Este método deve ser usado ao criar novas imagens. Para alterar o espaço de cores de uma imagem existente, deve ser usado o método Imagick::transformImageColorspace().

### Parâmetros

`colorspace`

  Uma das constantes COLORSPACE.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::setImageCompose

(PECL imagick 2, PECL imagick 3)

Imagick::setImageCompose — Define o operador de composição de imagem

### Descrição

public function Imagick::setImageCompose(int `$compose`): bool

Define o operador de composição de imagem, útil para especificar como compor a miniatura da imagem ao usar o método Imagick::montageImage().

### Parâmetros

`compose`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::setImageCompression

(PECL imagick 2, PECL imagick 3)

Imagick::setImageCompression — Define a compactação da imagem

### Descrição

public function Imagick::setImageCompression(int `$compression`): bool

### Parâmetros

`compression`

  Uma das constantes `COMPRESSION`.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::setImageCompressionQuality

(PECL imagick 2, PECL imagick 3)

Imagick::setImageCompressionQuality — Define a qualidade de compactação da imagem

### Descrição

public function Imagick::setImageCompressionQuality(int `$quality`): bool

Define a qualidade de compactação da imagem.

### Parâmetros

`quality`

  A qualidade de compactação da imagem como um número inteiro.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::setImageCompressionQuality()

    <?php
    function setImageCompressionQuality($imagePath, $quality) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageCompressionQuality($quality);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setImageDelay

(PECL imagick 2, PECL imagick 3)

Imagick::setImageDelay — Define o atraso da imagem

### Descrição

public function Imagick::setImageDelay(int `$delay`): bool

Define o atraso da imagem. Para uma imagem animada, este é o tempo durante o qual esse quadro da imagem deve ser exibido, antes de exibir o próximo quadro.

O atraso pode ser definido individualmente para cada quadro de uma imagem.

### Parâmetros

`delay`

  A quantidade de tempo expressa em 'tiques' durante o qual a imagem deve ser exibida. Para GIFs animados, há 100 tiques por segundo, então um valor de 20 seria 20/100 de um segundo, também conhecido como 1/5 de segundo.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Modifica um GIF animado com Imagick::setImageDelay()

    <?php

    // Modifica um GIF animado para que seus quadros sejam reproduzidos em uma velocidade variável,
    // variando a exibição em 50ms baixando até 0ms, o que fará com que o quadro
    // seja pulado na maioria dos navegadores.
    $imagick = new Imagick(realpath("Test.gif"));
    $imagick = $imagick->coalesceImages();

    $frameCount = 0;

    foreach ($imagick as $frame) {
        $imagick->setImageDelay((($frameCount % 11) * 5));
        $frameCount++;
    }

    $imagick = $imagick->deconstructImages();

    $imagick->writeImages("/path/to/save/output.gif", true);

    ?>

# Imagick::setImageDepth

(PECL imagick 2, PECL imagick 3)

Imagick::setImageDepth — Define a profundidade da imagem

### Descrição

public function Imagick::setImageDepth(int `$depth`): bool

Define a profundidade da imagem.

### Parâmetros

`depth`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::setImageDispose

(PECL imagick 2, PECL imagick 3)

Imagick::setImageDispose — Define o método de descarte de imagem

### Descrição

public function Imagick::setImageDispose(int `$dispose`): bool

Define o método de descarte de imagem.

### Parâmetros

`dispose`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::setImageExtent

(PECL imagick 2, PECL imagick 3)

Imagick::setImageExtent — Define o tamanho da imagem

### Descrição

public function Imagick::setImageExtent(int `$columns`, int `$rows`): bool

Define o tamanho da imagem (ou seja, colunas e linhas).

### Parâmetros

`columns`

`rows`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::setImageFilename

(PECL imagick 2, PECL imagick 3)

Imagick::setImageFilename — Define o nome do arquivo de uma imagem específica

### Descrição

public function Imagick::setImageFilename(string `$filename`): bool

Define o nome do arquivo de uma imagem específica em uma sequência.

### Parâmetros

`filename`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::setImageFormat

(PECL imagick 2, PECL imagick 3)

Imagick::setImageFormat — Define o formato de uma imagem específica

### Descrição

public function Imagick::setImageFormat(string `$format`): bool

Define o formato de uma imagem específica em uma sequência.

### Parâmetros

`format`

  Apresentação em string do formato da imagem. O suporte ao formato depende da instalação do ImageMagick.

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::setImageGamma

(PECL imagick 2, PECL imagick 3)

Imagick::setImageGamma — Define o gama da imagem

### Descrição

public function Imagick::setImageGamma(float `$gamma`): bool

Define o gama da imagem.

### Parâmetros

`gamma`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::setImageGravity

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::setImageGravity — Define a gravidade da imagem

### Descrição

public function Imagick::setImageGravity(int `$gravity`): bool

Define a propriedade de gravidade da imagem atual. Este método pode ser usado para definir a propriedade de gravidade para uma única sequência de imagens. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.4 ou superior.

### Parâmetros

`gravity`

  A propriedade da gravidade. Consulte a lista de constantes de gravidade.

### Valor Retornado

Nenhum valor é retornado.

# Imagick::setImageGreenPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::setImageGreenPrimary — Define o ponto primário verde da cromaticidade da imagem

### Descrição

public function Imagick::setImageGreenPrimary(float `$x`, float `$y`): bool

Define o ponto primário verde da cromaticidade da imagem.

### Parâmetros

`x`

`y`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::setImageIndex

(PECL imagick 2, PECL imagick 3)

Imagick::setImageIndex — Define a posição do iterador

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::setImageIndex(int `$index`): bool

Define o iterador para a posição na lista de imagens especificada com o parâmetro index.

Este método foi preterido em favor do Imagick::setIteratorIndex().

### Parâmetros

`index`

  A posição na qual o iterador será definido.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::setImageInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::setImageInterlaceScheme — Define a compactação da imagem

### Descrição

public function Imagick::setImageInterlaceScheme(int `$interlace_scheme`): bool

Define a compactação da imagem.

### Parâmetros

`interlace_scheme`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::setImageInterpolateMethod

(PECL imagick 2, PECL imagick 3)

Imagick::setImageInterpolateMethod — Define o método de interpolação de pixel da imagem.

### Descrição

public function Imagick::setImageInterpolateMethod(int `$method`): bool

Define o método de interpolação de pixel da imagem.

### Parâmetros

`method`

  O método é uma das constantes `Imagick::INTERPOLATE_*`.

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::setImageIterations

(PECL imagick 2, PECL imagick 3)

Imagick::setImageIterations — Define as iterações da imagem

### Descrição

public function Imagick::setImageIterations(int `$iterations`): bool

Define o número de iterações que uma imagem animada é repetida.

### Parâmetros

`iterations`

  O número de iterações que a imagem deve repetir. Zero define uma repetição contínua.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Uso básico de Imagick::setImageIterations()

    <?php

    $imagick = new Imagick(realpath("Teste.gif"));

    $imagick = $imagick->coalesceImages();
    $imagick->setImageIterations(1);
    $imagick = $imagick->deconstructImages();

    $imagick->writeImages('/caminho/para/gravar/UmaVez.gif', true);

    ?>

# Imagick::setImageMatte

(PECL imagick 2, PECL imagick 3)

Imagick::setImageMatte — Define o canal fosco da imagem

### Descrição

public function Imagick::setImageMatte(bool `$matte`): bool

Define o canal fosco da imagem. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.

### Parâmetros

`matte`

  True ativa o canal fosco e false o desativa.

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::setImageMatteColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageMatteColor — Define a cor fosca da imagem

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::setImageMatteColor(mixed `$matte`): bool

Define a cor fosca da imagem.

### Parâmetros

`matte`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL imagick 2.1.0 | Agora permite uma string representando a cor como parâmetro. As versões anteriores permitiam apenas um objeto ImagickPixel.

# Imagick::setImageOpacity

(PECL imagick 2, PECL imagick 3)

Imagick::setImageOpacity — Define o nível de opacidade da imagem

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::setImageOpacity(float `$opacity`): bool

Define a imagem para o nível de opacidade especificado. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.1 ou superior. Este método funciona em todos os canais, o que significa que, por exemplo, um valor de opacidade de 0.5 definirá todas as áreas transparentes como parcialmente opacas. Para adicionar transparência a áreas que ainda não são transparentes, use Imagick::evaluateImage().

### Parâmetros

`opacity`

  O nível de transparência: 1.0 é totalmente opaco e 0.0 é totalmente transparente.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Um exemplo de Imagick::setImageOpacity()

Um exemplo de uso de Imagick::setImageOpacity()

    <?php
    /* Cria o objeto */
    $image = new Imagick('source.png');

    /* Define a opacidade */
    $image->setImageOpacity(0.7);

    /* exibe a imagem */
    header('Content-type: image/png');
    echo $image;

    ?>

# Imagick::setImageOrientation

(PECL imagick 2, PECL imagick 3)

Imagick::setImageOrientation — Define a orientação da imagem

### Descrição

public function Imagick::setImageOrientation(int `$orientation`): bool

Define a orientação da imagem.

### Parâmetros

`orientation`

  Uma das constantes de orientação

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::setImageOrientation()

    <?php
    // Parece não fazer nada
    function setImageOrientation($imagePath, $orientationType) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageOrientation($orientationType);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setImagePage

(PECL imagick 2, PECL imagick 3)

Imagick::setImagePage — Define a geometria da página da imagem

### Descrição

public function Imagick::setImagePage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Define a geometria da página da imagem.

### Parâmetros

`width`

`height`

`x`

`y`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::setImageProfile

(PECL imagick 2, PECL imagick 3)

Imagick::setImageProfile — Adiciona um perfil nomeado ao objeto Imagick

### Descrição

public function Imagick::setImageProfile(string `$name`, string `$profile`): bool

Adiciona um perfil nomeado ao objeto Imagick. Se já existir um perfil com o mesmo nome, ele será substituído. Este método difere do método Imagick::ProfileImage() porque não aplica nenhum perfil de cores CMS.

### Parâmetros

`name`

`profile`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::setImageProperty

(PECL imagick 2, PECL imagick 3)

Imagick::setImageProperty — Define uma propriedade de imagem

### Descrição

public function Imagick::setImageProperty(string `$name`, string `$value`): bool

Define uma propriedade nomeada para a imagem. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.2 ou superior.

### Parâmetros

`name`

`value`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Usando Imagick::setImageProperty()

Definindo e obtendo propriedades da imagem

    <?php
    $image = new Imagick();
    $image->newImage(300, 200, "black");

    $image->setImageProperty('Exif:Make', 'Imagick');
    echo $image->getImageProperty('Exif:Make');
    ?>

### Veja Também

- Imagick::getImageProperty() - Retorna a propriedade nomeada da imagem

# Imagick::setImageRedPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::setImageRedPrimary — Define o ponto primário vermelho da cromaticidade da imagem

### Descrição

public function Imagick::setImageRedPrimary(float `$x`, float `$y`): bool

Define o ponto primário vermelho da cromaticidade da imagem.

### Parâmetros

`x`

`y`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::setImageRenderingIntent

(PECL imagick 2, PECL imagick 3)

Imagick::setImageRenderingIntent — Define a intenção de renderização da imagem

### Descrição

public function Imagick::setImageRenderingIntent(int `$rendering_intent`): bool

Define a intenção de renderização da imagem.

### Parâmetros

`rendering_intent`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::setImageResolution

(PECL imagick 2, PECL imagick 3)

Imagick::setImageResolution — Define a resolução da imagem

### Descrição

public function Imagick::setImageResolution(float `$x_resolution`, float `$y_resolution`): bool

Define a resolução da imagem.

### Parâmetros

`x_resolution`

`y_resolution`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::setImageResolution()

    <?php
    function setImageResolution($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageResolution(50, 50);

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setImageScene

(PECL imagick 2, PECL imagick 3)

Imagick::setImageScene — Define a cena da imagem

### Descrição

public function Imagick::setImageScene(int `$scene`): bool

Define a cena da imagem.

### Parâmetros

`scene`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::setImageTicksPerSecond

(PECL imagick 2, PECL imagick 3)

Imagick::setImageTicksPerSecond — Define os tiques por segundo da imagem

### Descrição

public function Imagick::setImageTicksPerSecond(int `$ticks_per_second`): bool

Ajusta o tempo durante o qual um quadro de uma imagem animada é exibido.

> Nota:

> Para GIFs animados, esta função não altera o número de 'tiques de imagem' por segundo, que é sempre definido como 100. Em vez disso, ajusta a quantidade de tempo que o quadro é exibido para simular a mudança em 'tiques por segundo'.

> Por exemplo, para um GIF animado onde cada quadro é exibido por 20 tiques (1/5 de segundo), quando este método é chamado em cada quadro da imagem com um argumento de `50`, os quadros são ajustados para serem exibidos por 40 tiques (2/5 de segundo) e a animação será reproduzida na metade da velocidade original.

### Parâmetros

`ticks_per_second`

  A duração durante a qual uma imagem deve ser exibida, expressa em tiques por segundo.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Modificando GIF animado com Imagick::setImageTicksPerSecond()

    <?php

    // Modifica um GIF animado para que a primeira metade do gif seja reproduzida na metade da
    // velocidade atual e a segunda metade seja reproduzida no dobro da velocidade
    // atual

    $imagick = new Imagick(realpath("Teste.gif"));
    $imagick = $imagick->coalesceImages();

    $totalFrames = $imagick->getNumberImages();

    $frameCount = 0;

    foreach ($imagick as $frame) {
        $imagick->setImageTicksPerSecond(50);

        if ($frameCount < ($totalFrames / 2)) {
            // Modifica o quado para ser mostrado por um tempo duas vezes maior que o atual
            $imagick->setImageTicksPerSecond(50);
        } else {
            // Modifica o quado para ser mostrado pela metado do tempo atual
            $imagick->setImageTicksPerSecond(200);
        }

        $frameCount++;
    }

    $imagick = $imagick->deconstructImages();

    $imagick->writeImages("/caminho/para/gravar/resultado.gif", true);

    ?>

# Imagick::setImageType

(PECL imagick 2, PECL imagick 3)

Imagick::setImageType — Define o tipo de imagem

### Descrição

public function Imagick::setImageType(int `$image_type`): bool

Define o tipo de imagem.

### Parâmetros

`image_type`

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::setImageUnits

(PECL imagick 2, PECL imagick 3)

Imagick::setImageUnits — Define as unidades de resolução da imagem

### Descrição

public function Imagick::setImageUnits(int `$units`): bool

Define as unidades de resolução da imagem.

### Parâmetros

`units`

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::setImageVirtualPixelMethod

(PECL imagick 2, PECL imagick 3)

Imagick::setImageVirtualPixelMethod — Define o método de pixel virtual da imagem

### Descrição

public function Imagick::setImageVirtualPixelMethod(int `$method`): bool

Define o método de pixel virtual da imagem.

### Parâmetros

`method`

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::setImageWhitePoint

(PECL imagick 2, PECL imagick 3)

Imagick::setImageWhitePoint — Define o ponto branco da cromaticidade da imagem

### Descrição

public function Imagick::setImageWhitePoint(float `$x`, float `$y`): bool

Define o ponto branco da cromaticidade da imagem.

### Parâmetros

`x`

`y`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::setInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::setInterlaceScheme — Define o esquema de entrelaçamento da imagem

### Descrição

public function Imagick::setInterlaceScheme(int `$interlace_scheme`): bool

Define o esquema de entrelaçamento da imagem.

### Parâmetros

`interlace_scheme`

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::setIteratorIndex

(PECL imagick 2, PECL imagick 3)

Imagick::setIteratorIndex — Define a posição do iterador

### Descrição

public function Imagick::setIteratorIndex(int `$index`): bool

Define o iterador para a posição na lista de imagens especificada com o parâmetro index. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.

### Parâmetros

`index`

  A posição para a qual o iterador será definido.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Usando Imagick::setIteratorIndex()

Cria imagens, define e obtém o índice do iterador.

    <?php
    $im = new Imagick();
    $im->newImage(100, 100, new ImagickPixel("red"));
    $im->newImage(100, 100, new ImagickPixel("green"));
    $im->newImage(100, 100, new ImagickPixel("blue"));

    $im->setIteratorIndex(1);
    echo $im->getIteratorIndex();
    ?>

### Veja Também

- Imagick::getIteratorIndex() - Obtém o índice da imagem ativa atual
- Imagick::getImageIndex() - Obtém o índice da imagem ativa atual
- Imagick::setImageIndex() - Define a posição do iterador

# Imagick::setLastIterator

(PECL imagick 2 >= 2.0.1, PECL imagick 3)

Imagick::setLastIterator — Define o iterador Imagick para a última imagem

### Descrição

public function Imagick::setLastIterator(): bool

Define o iterador Imagick para a última imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::setOption

(PECL imagick 2, PECL imagick 3)

Imagick::setOption — Define uma opção

### Descrição

public function Imagick::setOption(string `$key`, string `$value`): bool

Associa uma ou mais opções à varinha.

### Parâmetros

`key`

`value`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Tenta definir o tamanho de '$extent' com Imagick::setOption()

    <?php
        function renderJPG($extent) {
            $imagePath = $this->control->getImagePath();
            $imagick = new \Imagick(realpath($imagePath));
            $imagick->setImageFormat('jpg');
            $imagick->setOption('jpeg:extent', $extent);
            header("Content-Type: image/jpg");
            echo $imagick->getImageBlob();
        }

    ?>

Exemplo #2 Exemplo de Imagick::setOption()

    <?php
        function renderPNG($imagePath, $format) {

            $imagick = new \Imagick(realpath($imagePath));
            $imagick->setImageFormat('png');
            $imagick->setOption('png:format', $format);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

        // Grava como PNG de 64 bits.
        renderPNG($imagePath, 'png64');

    ?>

Exemplo #3 Exemplo de Imagick::setOption()

    <?php
        function renderCustomBitDepthPNG() {
            $imagePath = $this->control->getImagePath();
            $imagick = new \Imagick(realpath($imagePath));
            $imagick->setImageFormat('png');

            $imagick->setOption('png:bit-depth', '16');
            $imagick->setOption('png:color-type', 6);
            header("Content-Type: image/png");
            $crash = true;
            if ($crash) {
                echo $imagick->getImageBlob();
            }
            else {
                $tempFilename = tempnam('./', 'imagick');
                $imagick->writeimage(realpath($tempFilename));
                echo file_get_contents($tempFilename);
            }
        }

    ?>

# Imagick::setPage

(PECL imagick 2, PECL imagick 3)

Imagick::setPage — Define a geometria da página do objeto Imagick

### Descrição

public function Imagick::setPage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Define a geometria da página do objeto Imagick.

### Parâmetros

`width`

`height`

`x`

`y`

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::setPointSize

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::setPointSize — Define o tamanho em pontos

### Descrição

public function Imagick::setPointSize(float `$point_size`): bool

Define a propriedade de tamanho em pontos do objeto. Este método pode ser usado, por exemplo, para definir o tamanho da fonte para o pseudoformato "caption:". Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.7 ou superior.

### Parâmetros

`point_size`

  Tamanho em pontos.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Um exemplo de Imagick::setPointSize()

Exemplo de uso de Imagick::setPointSize()

    <?php
    /* Cria novo objeto Imagick */
    $im = new Imagick();

    /* Define a fonte para o objeto */
    $im->setFont("example.ttf");

    /* Define o tamanho em pontos */
    $im->setPointSize(12);

    /* Cria a nova legenda */
    $im->newPseudoImage(100, 100, "caption:Hello");

    /* Faz algo com a imagem */
    ?>

### Veja Também

- Imagick::getPointSize() - Obtém o tamanho do ponto

# Imagick::setProgressMonitor

(PECL imagick 3 >= 3.3.0)

Imagick::setProgressMonitor — Define uma função de retorno a ser chamada durante o processamento

### Descrição

public function Imagick::setProgressMonitor(callable `$callback`): bool

Define uma função de retorno a ser chamada durante o processamento da imagem Imagick.

### Parâmetros

`callback`

  A função de progresso a ser chamada. Deve retornar true se o processamento da imagem continuar ou false se for cancelado. O parâmetro 'offset' indica o progresso e o parâmetro 'span' indica a quantidade total de trabalho necessário a ser feito.

  function callback ( mixed `$offset` , mixed `$span` ): bool
  Cuidado

  Os valores passados ​​para a função de retorno não são consistentes. Em particular, o parâmetro 'span' pode aumentar durante o processamento da imagem. Por causa disso, calcular a porcentagem concluída de uma operação de imagem não é trivial.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::setProgressMonitor()

    <?php
        $abortReason = null;

        try {
            $imagick = new \Imagick(realpath($this->control->getImagePath()));
            $startTime = time();

            $callback = function ($offset, $span)  use ($startTime, &$abortReason) {
                if (((100 * $offset) / $span)  > 20) {
                    $abortReason = "Processamento alcançou 20%";
                    return false;
                }

                $nowTime = time();

                if ($nowTime - $startTime > 5) {
                    $abortReason = "Processamento de imagem levou mais de 5 segundos";
                    return false;
                }
                if (($offset % 5) == 0) {
                    echo "Progresso: $offset / $span <br/>";
                }
                return true;
            };

            $imagick->setProgressMonitor($callback);

            $imagick->waveImage(2, 15);

            echo "Comprimento dos dados é: ".strlen($imagick->getImageBlob());
        }
        catch(\ImagickException $e) {
            if ($abortReason != null) {
                echo "Processamento de imagem foi abortado: ".$abortReason."<br/>";
            }
            else {
                echo "ImagickException capturada: ".$e->getMessage()." Tipo da exceção é ".get_class($e);
            }
        }

    ?>

# Imagick::setRegistry

(PECL imagick 3 >= 3.3.0)

Imagick::setRegistry — Define a chave nomeada do registro do ImageMagick para um valor

### Descrição

public static function Imagick::setRegistry(string `$key`, string `$value`): bool

Define a chave nomeada do registro do ImageMagick para um valor. Isso é mais útil para definir o "caminho temporário" que controla onde o ImageMagick cria imagens temporárias, por exemplo, durante o processamento de PDFs.

### Parâmetros

`key`

`value`

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::setResolution

(PECL imagick 2, PECL imagick 3)

Imagick::setResolution — Define a resolução da imagem

### Descrição

public function Imagick::setResolution(float `$x_resolution`, float `$y_resolution`): bool

Define a resolução da imagem.

### Parâmetros

`x_resolution`

  A resolução horizontal.

`y_resolution`

  A resolução vertical.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Notas

Imagick::setResolution() precisa ser chamado antes do carregamento ou da criação de uma imagem.

### Veja Também

- Imagick::setImageResolution() - Define a resolução da imagem
- Imagick::getImageResolution() - Obtém a resolução X e Y da imagem

# Imagick::setResourceLimit

(PECL imagick 2, PECL imagick 3)

Imagick::setResourceLimit — Define o limite para um recurso específico

### Descrição

public static function Imagick::setResourceLimit(int `$type`, int `$limit`): bool

Este método é usado para modificar os limites de recursos da biblioteca ImageMagick subjacente.

### Parâmetros

`type`

  Consulte a lista de constantes de tipo de recurso.

`limit`

  Uma das constantes de tipo de recurso. A unidade depende do tipo de recurso que está sendo limitado.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Veja Também

- Imagick::getResourceLimit() - Retorna o limite de recursos especificado

# Imagick::setSamplingFactors

(PECL imagick 2, PECL imagick 3)

Imagick::setSamplingFactors — Define os fatores de amostragem da imagem

### Descrição

public function Imagick::setSamplingFactors(array `$factors`): bool

Define os fatores de amostragem da imagem.

### Parâmetros

`factors`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::setSamplingFactors()

    <?php
    function setSamplingFactors($imagePath) {

        $imagePath = "../imagick/imagens/DetalheFino.png";
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageFormat('jpg');
        $imagick->setSamplingFactors(array('2x2', '1x1', '1x1'));

        $compressed = $imagick->getImageBlob();

        $reopen = new \Imagick();
        $reopen->readImageBlob($compressed);

        $reopen->resizeImage(
            $reopen->getImageWidth() * 4,
            $reopen->getImageHeight() * 4,
            \Imagick::FILTER_POINT,
            1
        );

        header("Content-Type: image/jpg");
        echo $reopen->getImageBlob();
    }

    ?>

# Imagick::setSize

(PECL imagick 2, PECL imagick 3)

Imagick::setSize — Define o tamanho do objeto Imagick

### Descrição

public function Imagick::setSize(int `$columns`, int `$rows`): bool

Define o tamanho do objeto Imagick. Deve ser definido antes da leitura de um formato bruto como RGB, escala de cinza ou CMYK.

### Parâmetros

`columns`

`rows`

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::setSizeOffset

(PECL imagick 2, PECL imagick 3)

Imagick::setSizeOffset — Define o tamanho e o deslocamento do objeto Imagick

### Descrição

public function Imagick::setSizeOffset(int `$columns`, int `$rows`, int `$offset`): bool

Define o tamanho e o deslocamento do objeto Imagick. Deve-se definir estes itens antes da leitura de um formato de imagem bruto, como RGB, escala de cinza ou CMYK. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.

### Parâmetros

`columns`

  A largura em pixels.

`rows`

  A altura em pixels.

`offset`

  O deslocamento da imagem.

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::setType

(PECL imagick 2, PECL imagick 3)

Imagick::setType — Define o atributo de tipo de imagem

### Descrição

public function Imagick::setType(int `$image_type`): bool

Define o atributo de tipo de imagem.

### Parâmetros

`image_type`

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::shadeImage

(PECL imagick 2, PECL imagick 3)

Imagick::shadeImage — Cria um efeito 3D

### Descrição

public function Imagick::shadeImage(bool `$gray`, float `$azimuth`, float `$elevation`): bool

Ilumina à distância uma imagem para criar um efeito tridimensional. O controle do posicionamento da luz é feito com azimute e elevação; o azimute é medido em graus em relação ao X e a elevação é medida em pixels acima do eixo Z. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.

### Parâmetros

`gray`

  Um valor diferente de zero reduz a intensidade de cada pixel.

`azimuth`

  Azimute. Define a direção da fonte de luz.

`elevation`

  Elevação. Define a altura da fonte de luz.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma ImagickException em caso de falha.

### Exemplos

Exemplo #1 Exemplo de Imagick::shadeImage()

    <?php
    function shadeImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->shadeImage(true, 45, 20);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::shadowImage

(PECL imagick 2, PECL imagick 3)

Imagick::shadowImage — Simula uma sombra de imagem

### Descrição

public function Imagick::shadowImage(
float `$opacity`,
float `$sigma`,
int `$x`,
int `$y`
): bool

Simula uma sombra de imagem.

### Parâmetros

`opacity`

`sigma`

`x`

`y`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::shadowImage()

    <?php
    function shadowImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->shadowImage(0.4, 10, 50, 5);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::sharpenImage

(PECL imagick 2, PECL imagick 3)

Imagick::sharpenImage — Torna uma imagem mais nítida

### Descrição

public function Imagick::sharpenImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Torna uma imagem mais nítida. A imagem sofre convolução com um operador gaussiano de determinado raio e desvio padrão (sigma). Para resultados razoáveis, o raio deve ser maior que o sigma. Se um raio de 0 for usado, Imagick::sharpenImage() seleciona um raio adequado automaticamente.

### Parâmetros

`radius`

`sigma`

`channel`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::sharpenImage()

    <?php
    function sharpenImage($imagePath, $radius, $sigma, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->sharpenimage($radius, $sigma, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::shaveImage

(PECL imagick 2, PECL imagick 3)

Imagick::shaveImage — Raspa pixels das bordas da imagem

### Descrição

public function Imagick::shaveImage(int `$columns`, int `$rows`): bool

Raspa pixels das bordas da imagem. Ele aloca a memória necessária para a nova estrutura de imagem e retorna um ponteiro para a nova imagem.

### Parâmetros

`columns`

`rows`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::shaveImage()

    <?php
    function shaveImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->shaveImage(100, 50);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::shearImage

(PECL imagick 2, PECL imagick 3)

Imagick::shearImage — Cria um paralelogramo

### Descrição

public function Imagick::shearImage(mixed `$background`, float `$x_shear`, float `$y_shear`): bool

Desliza uma borda de uma imagem ao longo do eixo X ou Y, criando um paralelogramo. Um cisalhamento na direção X desliza uma aresta ao longo do eixo X, enquanto um cisalhamento na direção Y desliza uma aresta ao longo do eixo Y. A quantidade de cisalhamento é controlada por um ângulo de cisalhamento. Para cisalhamentos na direção X, x_shear é medido em relação ao eixo Y e, da mesma forma, para cisalhamentos na direção Y, y_shear é medido em relação ao eixo X. Os triângulos vazios que sobrarem do corte da imagem são preenchidos com a cor de fundo.

### Parâmetros

`background`

  A cor de fundo.

`x_shear`

  O número de graus para cisalhar no eixo X.

`y_shear`

  O número de graus para cisalhar no eixo Y.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL imagick 2.1.0 | Agora permite uma string representando a cor como primeiro parâmetro. As versões anteriores permitiam apenas um objeto ImagickPixel.

### Exemplos

Exemplo #1 Exemplo de Imagick::shearImage()

    <?php
    function shearImage($imagePath, $color, $shearX, $shearY) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->shearimage($color, $shearX, $shearY);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::sigmoidalContrastImage

(PECL imagick 2, PECL imagick 3)

Imagick::sigmoidalContrastImage — Ajusta o contraste de uma imagem

### Descrição

public function Imagick::sigmoidalContrastImage(
bool `$sharpen`,
float `$alpha`,
float `$beta`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Ajusta o contraste de uma imagem com um algoritmo de contraste sigmoide não linear. Aumenta o contraste da imagem usando uma função de transferência sigmoide sem saturar realces ou sombras. O parâmetro 'alpha' indica quanto aumentar o contraste (0 é nada; 3 é típico; 20 é muito); o parâmetro 'beta' indica onde os tons médios caem na imagem resultante (0 é branco; 50 é cinza médio; 100 é preto). Defina 'sharpen' `true` para aumentar o contraste da imagem, caso contrário o contraste será reduzido.

Consulte também » Exemplos do ImageMagick v6 - Transformações de Imagem - Constraste Não-linear Sigmoide

### Parâmetros

`sharpen`

  Se definido para true, aumenta o contraste, se definido para false, diminui o contraste.

`alpha`

  A quantidade de contraste a ser aplicada. 1 é muito pouco, 5 é uma quantia significativa, 20 é extremo.

`beta`

  Define onde estará o ponto médio do gradiente. Este valor deve estar no intervalo de 0 a 1 - multiplicado pelo valor Quantum do ImageMagick.

`channel`

  Em quais canais de cores o contraste será aplicado.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Cria uma imagem gradiente usando Imagick::sigmoidalContrastImage() adequado para mesclar duas imagens suavemente, com a mesclagem definida por $contrast e $midpoint

    <?php

    function generateBlendImage($width, $height, $contrast = 10, $midpoint = 0.5) {
        $imagick = new Imagick();
        $imagick->newPseudoImage($width, $height, 'gradient:black-white');
        $quanta = $imagick->getQuantumRange();
        $imagick->sigmoidalContrastImage(true, $contrast, $midpoint * $quanta["quantumRangeLong"]);

        return $imagick;
    }

    ?>

# Imagick::sketchImage

(PECL imagick 2, PECL imagick 3)

Imagick::sketchImage — Simula um esboço a lápis

### Descrição

public function Imagick::sketchImage(float `$radius`, float `$sigma`, float `$angle`): bool

Simula um esboço a lápis. A imagem sofre convolução com um operador gaussiano de determinado raio e desvio padrão (sigma). Para resultados razoáveis, o raio deve ser maior que o sigma. Usando um raio de 0, Imagick::sketchImage() seleciona um raio adequado automaticamente. O parâmetro 'angle' fornece o ângulo do movimento de desfoque. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.

### Parâmetros

`radius`

  O raio do gaussiano, em pixels, sem contar o pixel central.

`sigma`

  O desvio padrão do gaussiano, em pixels.

`angle`

  Ângulo ao longo do qual o efeito será aplicado.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::sketchImage()

    <?php
    function sketchImage($imagePath, $radius, $sigma, $angle) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->sketchimage($radius, $sigma, $angle);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::smushImages

(PECL imagick 3 >= 3.3.0)

Imagick::smushImages — Agrupa todas as imagens do ponteiro da imagem atual até o final da lista de imagens

### Descrição

public function Imagick::smushImages(bool `$stack`, int `$offset`): Imagick

Agrupa todas as imagens do ponteiro da imagem atual até o final da lista de imagens, umas próximas das outras, de cima para baixo se o parâmetro 'stack' for true, ou da esquerda para a direita se for false.

### Parâmetros

`stack`

`offset`

### Valor Retornado

The new smushed image.

### Exemplos

Exemplo #1 Exemplo de Imagick::smushImages()

    <?php
    function smushImages($imagePath, $imagePath2) {

        $imagick = new \Imagick(realpath($imagePath));
        $imagick2 = new \Imagick(realpath($imagePath2));

        $imagick->addimage($imagick2);
        $smushed = $imagick->smushImages(false, 50);
        $smushed->setImageFormat('jpg');
        header("Content-Type: image/jpg");
        echo $smushed->getImageBlob();
    }

    ?>

# Imagick::solarizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::solarizeImage — Aplica um efeito solarizante à imagem

### Descrição

public function Imagick::solarizeImage(int `$threshold`): bool

Aplica um efeito especial à imagem, semelhante ao efeito obtido em uma câmara escura fotográfica, expondo seletivamente áreas de papel fotossensível à luz. O limite varia de 0 até QuantumRange e é uma medida da extensão da solarização.

### Parâmetros

`threshold`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::solarizeImage()

    <?php
    function solarizeImage($imagePath, $solarizeThreshold) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->solarizeImage($solarizeThreshold * \Imagick::getQuantum());
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::sparseColorImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::sparseColorImage — Interpola cores

### Descrição

public function Imagick::sparseColorImage(int `$SPARSE_METHOD`, array `$arguments`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Dado o array de argumentos contendo valores numéricos, este método interpola as cores encontradas nessas coordenadas em toda a imagem usando `sparse_method`. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.4.5 ou superior.

### Parâmetros

`SPARSE_METHOD`

  Consulte a lista de constantes SPARSE_METHOD.

`arguments`

  Um array contendo as coordenadas. O array deve estar no formato `array(1,1, 2,45)`

`channel`

  Fornece qualquer constante de canal que seja válida no modo de canal. Para aplicar a mais de um canal, constantes de canal devem ser combinadas usando operadores bit a bit. O padrão é `Imagick::CHANNEL_DEFAULT`. Consulte esta lista de constantes de canal

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Imagick::sparseColorImage() com SPARSECOLORMETHOD_BARYCENTRIC

    <?php
        function renderImageBarycentric2() {
            $points = [
                [0.30, 0.10, 'red'],
                [0.10, 0.80, 'blue'],
                [0.70, 0.60, 'lime'],
                [0.80, 0.20, 'yellow'],
            ];
            $imagick = createGradientImage(
                400, 400,
                $points,
                \Imagick::SPARSECOLORMETHOD_BARYCENTRIC
            );
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

    ?>

Exemplo #2 Imagick::sparseColorImage() com SPARSECOLORMETHOD_BILINEAR

    <?php
        function renderImageBilinear() {
            $points = [[0.30, 0.10, 'red'], [0.10, 0.80, 'blue'], [0.70, 0.60, 'lime'], [0.80, 0.20, 'yellow'],];
            $imagick = createGradientImage(500, 500, $points, \Imagick::SPARSECOLORMETHOD_BILINEAR);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

    ?>

Exemplo #3 Imagick::sparseColorImage() com SPARSECOLORMETHOD_SPEPARDS

    <?php
        function renderImageShepards() {
            $points = [
                [0.30, 0.10, 'red'],
                [0.10, 0.80, 'blue'],
                [0.70, 0.60, 'lime'],
                [0.80, 0.20, 'yellow'],
            ];
            $imagick = createGradientImage(600, 600, $points, \Imagick::SPARSECOLORMETHOD_SPEPARDS);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

    ?>

Exemplo #4 Imagick::sparseColorImage() com SPARSECOLORMETHOD_VORONOI

    <?php
        function renderImageVoronoi() {
            $points = [
                [0.30, 0.10, 'red'],
                [0.10, 0.80, 'blue'],
                [0.70, 0.60, 'lime'],
                [0.80, 0.20, 'yellow'],
            ];
            $imagick = createGradientImage(500, 500, $points, \Imagick::SPARSECOLORMETHOD_VORONOI);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

    ?>

Exemplo #5 Imagick::sparseColorImage() com SPARSECOLORMETHOD_BARYCENTRIC

    <?php
        function renderImageBarycentric() {
            $points = [
                [0, 0, 'skyblue'],
                [-1, 1, 'skyblue'],
                [1, 1, 'black'],
            ];
            $imagick = createGradientImage(600, 200, $points, \Imagick::SPARSECOLORMETHOD_BARYCENTRIC);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

    ?>

Exemplo #6 Imagick::sparseColorImage() na função createGradientImage() usada por outros exemplos

    <?php
    function createGradientImage($width, $height, $colorPoints, $sparseMethod, $absolute = false) {

        $imagick = new \Imagick();
        $imagick->newImage($width, $height, "white");
        $imagick->setImageFormat("png");

        $barycentricPoints = array();

        foreach ($colorPoints as $colorPoint) {

            if ($absolute == true) {
                $barycentricPoints[] = $colorPoint[0];
                $barycentricPoints[] = $colorPoint[1];
            }
            else {
                $barycentricPoints[] = $colorPoint[0] * $width;
                $barycentricPoints[] = $colorPoint[1] * $height;
            }

            if (is_string($colorPoint[2])) {
                $imagickPixel = new \ImagickPixel($colorPoint[2]);
            }
            else if ($colorPoint[2] instanceof \ImagickPixel) {
                $imagickPixel = $colorPoint[2];
            }
            else{
                $errorMessage = sprintf(
                    "O valor %s não é uma string e nem uma classe ImagickPixel. Não pode ser usado como uma cor.",
                    $colorPoint[2]
                );

                throw new \InvalidArgumentException(
                    $errorMessage
                );
            }

            $red = $imagickPixel->getColorValue(\Imagick::COLOR_RED);
            $green = $imagickPixel->getColorValue(\Imagick::COLOR_GREEN);
            $blue = $imagickPixel->getColorValue(\Imagick::COLOR_BLUE);
            $alpha = $imagickPixel->getColorValue(\Imagick::COLOR_ALPHA);

            $barycentricPoints[] = $red;
            $barycentricPoints[] = $green;
            $barycentricPoints[] = $blue;
            $barycentricPoints[] = $alpha;
        }

        $imagick->sparseColorImage($sparseMethod, $barycentricPoints);

        return $imagick;
    }

    ?>

# Imagick::spliceImage

(PECL imagick 2, PECL imagick 3)

Imagick::spliceImage — Une uma cor sólida na imagem

### Descrição

public function Imagick::spliceImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Une uma cor sólida na imagem.

### Parâmetros

`width`

`height`

`x`

`y`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::spliceImage()

    <?php
    function spliceImage($imagePath, $startX, $startY, $width, $height) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->spliceImage($width, $height, $startX, $startY);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::spreadImage

(PECL imagick 2, PECL imagick 3)

Imagick::spreadImage — Desloca aleatoriamente cada pixel em um bloco

### Descrição

public function Imagick::spreadImage(float `$radius`): bool

Método de efeitos especiais que desloca aleatoriamente cada pixel em um bloco definido pelo parâmetro 'radius' (raio).

### Parâmetros

`radius`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::spreadImage()

    <?php
    function spreadImage($imagePath, $radius) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->spreadImage($radius);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::statisticImage

(PECL imagick 3 >= 3.3.0)

Imagick::statisticImage — Modifica a imagem usando uma função estatística

### Descrição

public function Imagick::statisticImage(
int `$type`,
int `$width`,
int `$height`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Substitui cada pixel pela estatística correspondente da vizinhança na largura e altura especificadas.

### Parâmetros

`type`

`width`

`height`

`channel`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::statisticImage()

    <?php
    function statisticImage($imagePath, $statisticType, $width, $height, $channel) {
        $imagick = new \Imagick(realpath($imagePath));

        $imagick->statisticImage(
            $statisticType,
            $width,
            $height,
            $channel
        );

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    statisticImage($imagePath, \Imagick::STATISTIC_MEDIAN, 5, 5, \Imagick::CHANNEL_DEFAULT);

    ?>

# Imagick::steganoImage

(PECL imagick 2, PECL imagick 3)

Imagick::steganoImage — Oculta uma marca d'água digital na imagem

### Descrição

public function Imagick::steganoImage(Imagick `$watermark_wand`, int `$offset`): Imagick

Oculta uma marca d’água digital na imagem. Recupere a marca d'água oculta posteriormente para provar a autenticidade de uma imagem. O deslocamento define a posição inicial na imagem para ocultar a marca d’água.

### Parâmetros

`watermark_wand`

`offset`

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::stereoImage

(PECL imagick 2, PECL imagick 3)

Imagick::stereoImage — Compõe duas imagens

### Descrição

public function Imagick::stereoImage(Imagick `$offset_wand`): bool

Compõe duas imagens e produz uma única imagem que é a composição de uma imagem esquerda e direita de um par estéreo.

### Parâmetros

`offset_wand`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::stripImage

(PECL imagick 2, PECL imagick 3)

Imagick::stripImage — Remove todos os perfis e comentários de uma imagem

### Descrição

public function Imagick::stripImage(): bool

Remove todos os perfis e comentários de uma imagem.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

# Imagick::subImageMatch

(PECL imagick 3 >= 3.3.0)

Imagick::subImageMatch — Procura uma subimagem na imagem atual e retorna uma imagem semelhante

### Descrição

public function Imagick::subImageMatch(Imagick `$Imagick`, array `&$offset` = ?, float `&$similarity` = ?): Imagick

Procura uma subimagem na imagem atual e retorna uma imagem semelhante de forma que um local de correspondência exata seja completamente branco e, se nenhum dos pixels corresponder, preto, caso contrário, algum nível de cinza intermediário. Pode-se também passar os parâmetros opcionais 'bestMatch' e 'similarity'. Depois de chamar a função, 'similarity' será definida para a "pontuação" da similaridade entre a subimagem e a posição correspondente na imagem maior, 'bestMatch' conterá um array associativo com elementos 'x', 'y', 'width' (largura) e 'height' (altura) que descrevem a região correspondente.

### Parâmetros

`Imagick`

`offset`

`similarity`

  Uma nova imagem que exibe a quantidade de similaridade em cada pixel.

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de Imagick::subImageMatch()

    <?php
    function subImageMatch($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick2 = clone $imagick;
        $imagick2->cropimage(40, 40, 250, 110);
        $imagick2->vignetteimage(0, 1, 3, 3);

        $similarity = null;
        $bestMatch = null;
        $comparison = $imagick->subImageMatch($imagick2, $bestMatch, $similarity);

        $comparison->setImageFormat('png');
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::swirlImage

(PECL imagick 2, PECL imagick 3)

Imagick::swirlImage — Gira os pixels em torno do centro da imagem

### Descrição

function Imagick::swirlImage(float `$degrees`): bool

Gira os pixels em torno do centro da imagem, onde 'degrees' indica o ângulo de varredura do arco através do qual cada pixel é movido. Obtém-se um efeito mais dramático à medida que o ângulo varia de 1 a 360.

### Parâmetros

`degrees`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::swirlImage()

    <?php
    function swirlImage($imagePath, $swirl) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->swirlImage($swirl);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::textureImage

(PECL imagick 2, PECL imagick 3)

Imagick::textureImage — Ladrilha repetidamente a imagem da textura

### Descrição

function Imagick::textureImage(Imagick `$texture_wand`): Imagick

Distribui repetidamente a imagem da textura para a direita e para baixo na tela.

### Parâmetros

`texture_wand`

  Objeto Imagick para usar como imagem de textura

### Valor Retornado

Retorna um novo objeto Imagick que tem a textura repetida aplicada.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::textureImage()

    <?php
    function textureImage($imagePath) {
        $image = new \Imagick();
        $image->newImage(640, 480, new \ImagickPixel('pink'));
        $image->setImageFormat("jpg");
        $texture = new \Imagick(realpath($imagePath));
        $texture->scaleimage($image->getimagewidth() / 4, $image->getimageheight() / 4);
        $image = $image->textureImage($texture);
        header("Content-Type: image/jpg");
        echo $image;
    }

    ?>

# Imagick::thresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::thresholdImage — Altera o valor de pixels individuais com base em um limite

### Descrição

public function Imagick::thresholdImage(float `$threshold`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Altera o valor de pixels individuais com base na intensidade de cada pixel em comparação com o limite. O resultado é uma imagem de alto contraste e duas cores.

### Parâmetros

`threshold`

`channel`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::thresholdImage()

    <?php
    function thresholdimage($imagePath, $threshold, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->thresholdimage($threshold * \Imagick::getQuantum(), $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::thumbnailImage

(PECL imagick 2, PECL imagick 3)

Imagick::thumbnailImage — Altera o tamanho de uma imagem

### Descrição

public function Imagick::thumbnailImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$fill` = `false`,
bool `$legacy` = `false`
): bool

Altera o tamanho de uma imagem para as dimensões fornecidas e remove quaisquer perfis associados. O objetivo é produzir imagens em miniatura de baixo custo, adequadas para exibição na Web. Se `true` for informado no terceiro parâmetro, os parâmetros 'columns' (colunas) e 'rows' (linhas) serão usados ​​como máximos para cada lado. Ambos os lados serão reduzidos até corresponderem ou ficarem menores que o parâmetro fornecido para o lado.

> Nota: O comportamento do parâmetro `bestfit` mudou na Imagick 3.0.0. Antes desta versão, dadas as dimensões 400x400, uma imagem de dimensões 200x150 permaneceria intocada. Na Imagick 3.0.0 e superiores, a imagem será escalada para 400x300, pois este é o "melhor ajuste" para as dimensões fornecidas. Se o parâmetro `bestfit` for usado, tanto a largura quanto a altura devem ser informadas.

### Parâmetros

`columns`

  Largura da imagem.

`rows`

  Altura da imagem.

`bestfit`

  Informa se os valores máximos devem ser forçados.

`fill`

  Se a imagem não preencher completamente a caixa, ela será preenchida com a cor de fundo da imagem.

`legacy`

  Arredonda para baixo a menor dimensão em vez de arredondar para o inteiro mais próximo.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::thumbnailImage()

    <?php
    function thumbnailImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setbackgroundcolor('rgb(64, 64, 64)');
        $imagick->thumbnailImage(100, 100, true, true);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::tintImage

(PECL imagick 2, PECL imagick 3)

Imagick::tintImage — Aplica um vetor de cores a cada pixel da imagem

### Descrição

public function Imagick::tintImage(mixed `$tint`, mixed `$opacity`, bool `$legacy` = `false`): bool

Aplica um vetor de cores a cada pixel da imagem. O comprimento do vetor é 0 para preto e branco e máximo para tons médios. A função de peso do vetor é f(x)=(1-(4.0*((x-0.5)*(x-0.5)))).

### Parâmetros

`tint`

`opacity`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL imagick 2.1.0 | Agora permite uma string representando a cor como o primeiro parâmetro e um float representando o valor da opacidade como o segundo parâmetro. Versões anteriores permitiam apenas objetos ImagickPixel.

### Exemplos

Exemplo #1 Exemplo de Imagick::tintImage()

    <?php
    function tintImage($r, $g, $b, $a) {
        $a = $a / 100;

        $imagick = new \Imagick();
        $imagick->newPseudoImage(400, 400, 'gradient:black-white');

        $tint = new \ImagickPixel("rgb($r, $g, $b)");
        $opacity = new \ImagickPixel("rgb(128, 128, 128, $a)");
        $imagick->tintImage($tint, $opacity);
        $imagick->setImageFormat('png');
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::__toString

(PECL imagick 2, PECL imagick 3)

Imagick::__toString — Retorna a imagem como uma string

### Descrição

public function Imagick::__toString(): string

Retorna a imagem atual como uma string. Isso retornará apenas uma única imagem; não deve ser usado para objetos Imagick que contenham múltiplas imagens, por exemplo, um GIF animado ou PDF com várias páginas.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o conteúdo da string em caso de sucesso ou uma string vazia em caso de falha.

### Veja Também

- Imagick::getImageBlob() - Retorna a sequência de imagem como um BLOB
- Imagick::getImagesBlob() - Retorna todas as sequências de imagens como um BLOB

# Imagick::transformImage

(PECL imagick 2, PECL imagick 3)

Imagick::transformImage — Método conveniente para definir o tamanho do corte e a geometria da imagem

Aviso

Esta função foi DESCONTINUADA a partir da Imagick 3.4.4. O uso desta função é fortemente desencorajado.

### Descrição

public function Imagick::transformImage(string `$crop`, string `$geometry`): Imagick

Um método conveniente para definir o tamanho do corte e a geometria da imagem a partir de strings. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.

### Parâmetros

`crop`

  Uma string de geometria de corte. Esta geometria define uma sub-região da imagem a ser cortada.

`geometry`

  Uma string de geometria de imagem. Esta geometria define o tamanho final da imagem.

### Valor Retornado

Retorna um objeto Imagick contendo a imagem transformada.

### Exemplos

Exemplo #1 Usando Imagick::transformImage()

O exemplo cria uma imagem preta de 100x100.

    <?php
    $image = new Imagick();
    $image->newImage(300, 200, "black");
    $new_image = $image->transformImage("100x100", "100x100");
    $new_image->writeImage('test_out.jpg');
    ?>

### Veja Também

- Imagick::cropImage() - Extrai uma região da imagem
- Imagick::resizeImage() - Dimensiona uma imagem
- Imagick::thumbnailImage() - Altera o tamanho de uma imagem

# Imagick::transformImageColorspace

(PECL imagick 3)

Imagick::transformImageColorspace — Transforma uma imagem em um novo espaço de cores

### Descrição

public function Imagick::transformImageColorspace(int `$colorspace`): bool

Transforma uma imagem em um novo espaço de cores

### Parâmetros

`colorspace`

  O espaço de cores para o qual a imagem deve ser transformada, uma das constantes COLORSPACE, por exemplo, Imagick::COLORSPACE_CMYK.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::transformImageColorspace()

Transforma uma imagem em um novo espaço de cores e, em seguida, extrai um único canal para que os valores individuais do canal possam ser visualizados.

    <?php
    function transformImageColorspace($imagePath, $colorSpace, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->transformimagecolorspace($colorSpace);
        // $channel deve ser uma das constantes de canal, exemplo: \Imagick::CHANNEL_BLUE
        $imagick->separateImageChannel($channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }
    ?>

### Veja Também

- Imagick::setColorSpace() - Define espaço de cores

# Imagick::transparentPaintImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::transparentPaintImage — Pinta pixels com a cor transparente

### Descrição

public function Imagick::transparentPaintImage(
mixed `$target`,
float `$alpha`,
float `$fuzz`,
bool `$invert`
): bool

Pinta pixels que correspondem à cor alvo com a cor transparente. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.8 ou superior.

### Parâmetros

`target`

  A cor alvo a ser pintada

`alpha`

  O nível de transparência: 1.0 é totalmente opaco e 0.0 é totalmente transparente.

`fuzz`

  A quantidade de fuzz. Por exemplo, definir fuzz como 10 e a cor vermelha nas intensidades de 100 e 102, respectivamente, agora são interpretadas como a mesma cor.

`invert`

  Se igual a `true`, pinta qualquer pixel que não corresponda à cor alvo.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::transparentPaintImage()

    <?php
    function transparentPaintImage($color, $alpha, $fuzz) {
        $imagick = new \Imagick(realpath("images/BlueScreen.jpg"));

        // Precisa estar em um formato que suporte transparência
        $imagick->setimageformat('png');

        $imagick->transparentPaintImage(
            $color, $alpha, $fuzz * \Imagick::getQuantum(), false
        );

        // Não requerido, mas ajuda a organizar os pixels deixados para trás
        $imagick->despeckleimage();

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::transposeImage

(PECL imagick 2, PECL imagick 3)

Imagick::transposeImage — Cria uma imagem espelhada vertical

### Descrição

public function Imagick::transposeImage(): bool

Cria uma imagem espelhada vertical refletindo os pixels em torno do eixo X central enquanto os gira em 90 graus. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::transposeImage()

    <?php
    function transposeImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->transposeImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Veja Também

- Imagick::transverseImage() - Cria uma imagem espelhada horizontal

# Imagick::transverseImage

(PECL imagick 2, PECL imagick 3)

Imagick::transverseImage — Cria uma imagem espelhada horizontal

### Descrição

public function Imagick::transverseImage(): bool

Cria uma imagem espelhada horizontal refletindo os pixels em torno do eixo Y central enquanto os gira em 270 graus. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::transverseImage()

    <?php
    function transverseImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->transverseImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Veja Também

- Imagick::transposeImage() - Cria uma imagem espelhada vertical

# Imagick::trimImage

(PECL imagick 2, PECL imagick 3)

Imagick::trimImage — Apara as bordas da imagem

### Descrição

public function Imagick::trimImage(float `$fuzz`): bool

Remove as bordas que são da cor de fundo da imagem. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.

### Parâmetros

`fuzz`

  Por padrão, o alvo deve corresponder exatamente a uma determinada cor de pixel. No entanto, em muitos casos, duas cores podem diferir um pouco. O membro fuzz da imagem define quanta tolerância é aceitável para considerar duas cores iguais. Este parâmetro representa a variação na faixa Quantum.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Usando Imagick::trimImage()

Apara uma imagem e exiba-a no navegador.

    <?php
    /* Cria o objeto e lê a imagem */
    $im = new Imagick("imagem.jpg");

    /* Apara a imagem */
    $im->trimImage(0);

    /* Exibe a imagem */
    header("Content-Type: image/" . $im->getImageFormat());
    echo $im;
    ?>

### Veja Também

- Imagick::getQuantumDepth() - Obtém a profundidade Quantum
- Imagick::getQuantumRange() - Retorna o intervalo Quantum do Imagick
- imagecropauto() - Recorta uma imagem automaticamente usando um dos modos disponíveis

# Imagick::uniqueImageColors

(PECL imagick 2,PECL imagick 3)

Imagick::uniqueImageColors — Descarta todas, exceto uma, de qualquer cor de pixel

### Descrição

public function Imagick::uniqueImageColors(): bool

Descarta todas, exceto uma, de qualquer cor de pixel. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::uniqueImageColors()

    <?php
    function uniqueImageColors($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        // Reduz a imagem para 256 cores
        $imagick->quantizeImage(256, \Imagick::COLORSPACE_YIQ, 0, false, false);
        $imagick->uniqueImageColors();
        $imagick->scaleimage($imagick->getImageWidth(), $imagick->getImageHeight() * 20);
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::unsharpMaskImage

(PECL imagick 2, PECL imagick 3)

Imagick::unsharpMaskImage — Torna uma imagem mais nítida

### Descrição

public function Imagick::unsharpMaskImage(
float `$radius`,
float `$sigma`,
float `$amount`,
float `$threshold`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Torna uma imagem mais nítida. A imagem sofre convolução com um operador gaussiano de determinado raio e desvio padrão (sigma). Para resultados razoáveis, o raio deve ser maior que o sigma. Usando um raio de 0, Imagick::UnsharpMaskImage() seleciona um raio adequado automaticamente.

### Parâmetros

`radius`

`sigma`

`amount`

`threshold`

`channel`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de Imagick::unsharpMaskImage()

    <?php
    function unsharpMaskImage($imagePath, $radius, $sigma, $amount, $unsharpThreshold) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->unsharpMaskImage($radius, $sigma, $amount, $unsharpThreshold);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::valid

(PECL imagick 2, PECL imagick 3)

Imagick::valid — Verifica se o item atual é válido

### Descrição

public function Imagick::valid(): bool

Verifica se o item atual é válido.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::vignetteImage

(PECL imagick 2, PECL imagick 3)

Imagick::vignetteImage — Adiciona filtro de vinheta à imagem

### Descrição

public function Imagick::vignetteImage(
float `$blackPoint`,
float `$whitePoint`,
int `$x`,
int `$y`
): bool

Suaviza as bordas da imagem no estilo vinheta. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.

### Parâmetros

`blackPoint`

  O ponto preto.

`whitePoint`

  O ponto branco.

`x`

  Deslocamento X da elipse

`y`

  Deslocamento Y da elipse

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de Imagick::vignetteImage()

    <?php
    function vignetteImage($imagePath, $blackPoint, $whitePoint, $x, $y) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->vignetteImage($blackPoint, $whitePoint, $x, $y);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Veja Também

- Imagick::waveImage() - Aplica filtro de onda à imagem
- Imagick::swirlImage() - Gira os pixels em torno do centro da imagem

# Imagick::waveImage

(PECL imagick 2, PECL imagick 3)

Imagick::waveImage — Aplica filtro de onda à imagem

### Descrição

public function Imagick::waveImage(float `$amplitude`, float `$length`): bool

Aplica um filtro de onda à imagem Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.2.9 ou superior.

### Parâmetros

`amplitude`

  A amplitude da onda.

`length`

  O comprimento da onda.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Erros/Exceções

Lança uma exceção ImagickException em caso de erro.

### Exemplos

Exemplo #1 A função Imagick::waveImage() pode ser bem lenta

    <?php
    function waveImage($imagePath, $amplitude, $length) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->waveImage($amplitude, $length);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Veja Também

- Imagick::solarizeImage() - Aplica um efeito solarizante à imagem
- Imagick::oilpaintImage() - Simula uma pintura a óleo
- Imagick::embossImage() - Retorna uma imagem em tons de cinza com efeito tridimensional
- Imagick::addNoiseImage() - Adiciona ruído aleatório à imagem
- Imagick::swirlImage() - Gira os pixels em torno do centro da imagem

# Imagick::whiteThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::whiteThresholdImage — Força todos os pixels acima de um limite para branco

### Descrição

public function Imagick::whiteThresholdImage(mixed `$threshold`): bool

É como Imagick::ThresholdImage() mas força todos os pixels acima do limite para branco, deixando todos os pixels abaixo do limite inalterados.

### Parâmetros

`threshold`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL imagick 2.1.0 | Agora permite uma string representando a cor como parâmetro. As versões anteriores permitiam apenas um objeto ImagickPixel.

### Exemplos

Exemplo #1 Exemplo de Imagick::whiteThresholdImage()

    <?php
    function whiteThresholdImage($imagePath, $color) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->whiteThresholdImage($color);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::writeImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImage — Grava uma imagem no nome de arquivo especificado

### Descrição

public function Imagick::writeImage(string `$filename` = NULL): bool

Grava uma imagem no nome de arquivo especificado. Se o parâmetro filename for NULL, a imagem será gravada no nome de arquivo definido por Imagick::readImage() ou Imagick::setImageFilename().

### Parâmetros

`filename`

  Nome do arquivo onde a imagem será gravada. A extensão do nome do arquivo define o tipo do arquivo. O formato pode ser forçado independentemente da extensão do arquivo usando o prefixo "formato:", por exemplo "jpg:test.png".

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::writeImageFile

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImageFile — Grava uma imagem em um descritor de arquivo

### Descrição

public function Imagick::writeImageFile(resource `$filehandle`, string `$format` = ?): bool

Grava uma sequência de imagem em um descritor de arquivo aberto. O descritor precisa ser aberto com fopen(), por exemplo. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.6 ou superior.

### Parâmetros

`filehandle`

  Descritor do arquivo onde a imagem será gravada.

`format`

  O formato da imagem. A lista de especificadores de formato válidos depende do conjunto de recursos compilados do ImageMagick e pode ser consultada em tempo de execução via Imagick::queryFormats().

### Valor Retornado

Retorna `true` em caso de sucesso.

### Veja Também

- Imagick::queryFormats() - Retorna formatos suportados pelo Imagick

# Imagick::writeImages

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImages — Grava uma imagem ou sequência de imagens

### Descrição

public function Imagick::writeImages(string `$filename`, bool `$adjoin`): bool

Grava uma imagem ou sequência de imagens.

### Parâmetros

`filename`

`adjoin`

### Valor Retornado

Retorna `true` em caso de sucesso.

# Imagick::writeImagesFile

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImagesFile — Grava quadros em um descritor de arquivo

### Descrição

public function Imagick::writeImagesFile(resource `$filehandle`, string `$format` = ?): bool

Grava todos os quadros da imagem em um descritor de arquivo aberto. Este método pode ser usado para gravar GIFs animados ou outras imagens multi-quadros em um descritor de arquivo aberto. Este método estará disponível se a extensão Imagick tiver sido compilada com a ImageMagick versão 6.3.6 ou superior.

### Parâmetros

`filehandle`

  Descritor do arquivo onde a imagem será gravada.

`format`

  O formato da imagem. A lista de especificadores de formato válidos depende do conjunto de recursos compilados do ImageMagick e pode ser consultada em tempo de execução via Imagick::queryFormats().

### Valor Retornado

Retorna `true` em caso de sucesso.

### Veja Também

- Imagick::queryFormats() - Retorna formatos suportados pelo Imagick

## Índice

- Imagick::adaptiveBlurImage — Adiciona filtro de desfoque adaptável à imagem
- Imagick::adaptiveResizeImage — Redimensiona imagem de forma adaptativa com triangulação dependente de dados
- Imagick::adaptiveSharpenImage — Aumenta a nitidez da imagem de forma adaptativa
- Imagick::adaptiveThresholdImage — Seleciona um limite para cada pixel com base em uma faixa de intensidade
- Imagick::addImage — Adiciona nova imagem à lista de imagens de objetos Imagick
- Imagick::addNoiseImage — Adiciona ruído aleatório à imagem
- Imagick::affineTransformImage — Transforma uma imagem
- Imagick::animateImages — Anima uma imagem ou imagens
- Imagick::annotateImage — Cria anotação em uma imagem com texto
- Imagick::appendImages — Anexa um conjunto de imagens
- Imagick::autoLevelImage — Ajusta os níveis de um canal de imagem específico
- Imagick::averageImages — Tira a média de um conjunto de imagens
- Imagick::blackThresholdImage — Força todos os pixels abaixo do limite para preto
- Imagick::blueShiftImage — Silencia as cores da imagem
- Imagick::blurImage — Adiciona filtro de desfoque à imagem
- Imagick::borderImage — Envolve a imagem com uma borda
- Imagick::brightnessContrastImage — Altera o brilho e/ou contraste de uma imagem
- Imagick::charcoalImage — Simula um desenho a carvão
- Imagick::chopImage — Remove uma região de uma imagem e corta
- Imagick::clampImage — Restringe a faixa de cores de 0 à profundidade do Quantum
- Imagick::clear — Limpa todos os recursos associados ao objeto Imagick
- Imagick::clipImage — Recorta ao longo do primeiro caminho do perfil 8BIM
- Imagick::clipImagePath — Recorta ao longo dos caminhos nomeados do perfil 8BIM, se presente
- Imagick::clipPathImage — Recorta ao longo dos caminhos nomeados do perfil 8BIM
- Imagick::clone — Faz uma cópia exata do objeto Imagick
- Imagick::clutImage — Substitui cores na imagem
- Imagick::coalesceImages — Compõe um conjunto de imagens
- Imagick::colorFloodfillImage — Altera o valor da cor de qualquer pixel que corresponda ao alvo
- Imagick::colorizeImage — Mescla a cor de preenchimento com a imagem
- Imagick::colorMatrixImage — Aplica transformação de cores a uma imagem
- Imagick::combineImages — Combina uma ou mais imagens em uma única imagem
- Imagick::commentImage — Adiciona um comentário à sua imagem
- Imagick::compareImageChannels — Retorna a diferença em uma ou mais imagens
- Imagick::compareImageLayers — Retorna a região delimitadora máxima entre imagens
- Imagick::compareImages — Compara uma imagem com uma imagem reconstruída
- Imagick::compositeImage — Compor uma imagem em outra
- Imagick::__construct — O construtor Imagick
- Imagick::contrastImage — Altera o contraste da imagem
- Imagick::contrastStretchImage — Melhora o contraste de uma imagem colorida
- Imagick::convolveImage — Aplica um kernel de convolução personalizado à imagem
- Imagick::count — Obtém o número de imagens
- Imagick::cropImage — Extrai uma região da imagem
- Imagick::cropThumbnailImage — Cria uma miniatura de recorte
- Imagick::current — Retorna uma referência ao objeto Imagick atual
- Imagick::cycleColormapImage — Desloca o mapa de cores de uma imagem
- Imagick::decipherImage — Decifra uma imagem
- Imagick::deconstructImages — Retorna certas diferenças de pixels entre imagens
- Imagick::deleteImageArtifact — Excluir artefato de imagem
- Imagick::deleteImageProperty — Exclui uma propriedade de imagem
- Imagick::deskewImage — Remove distorção da imagem
- Imagick::despeckleImage — Reduz o ruído pontilhado em uma imagem
- Imagick::destroy — Destrói o objeto Imagick
- Imagick::displayImage — Exibe uma imagem
- Imagick::displayImages — Exibe uma imagem ou sequência de imagens
- Imagick::distortImage — Distorce uma imagem usando vários métodos de distorção
- Imagick::drawImage — Renderiza o objeto ImagickDraw na imagem atual
- Imagick::edgeImage — Melhora as bordas da imagem
- Imagick::embossImage — Retorna uma imagem em tons de cinza com efeito tridimensional
- Imagick::encipherImage — Cifra uma imagem
- Imagick::enhanceImage — Melhora a qualidade de uma imagem com ruído
- Imagick::equalizeImage — Equaliza o histograma da imagem
- Imagick::evaluateImage — Aplica uma expressão a uma imagem
- Imagick::exportImagePixels — Exporta os pixels da imagem não processada
- Imagick::extentImage — Define tamanho da imagem
- Imagick::filter — Aplica um kernel de convolução personalizado à imagem
- Imagick::flattenImages — Mescla uma sequência de imagens
- Imagick::flipImage — Cria uma imagem espelhada vertical
- Imagick::floodFillPaintImage — Altera o valor da cor de qualquer pixel que corresponda ao alvo
- Imagick::flopImage — Cria uma imagem espelhada horizontal
- Imagick::forwardFourierTransformImage — Implementa a transformada discreta de Fourier (DFT)
- Imagick::frameImage — Adiciona uma borda tridimensional simulada
- Imagick::functionImage — Aplica uma função na imagem
- Imagick::fxImage — Avalia uma expressão para cada pixel da imagem
- Imagick::gammaImage — Corrige o gama de uma imagem
- Imagick::gaussianBlurImage — Desfoca uma imagem
- Imagick::getColorspace — Obtém o espaço de cores
- Imagick::getCompression — Obtém o tipo de compactação do objeto
- Imagick::getCompressionQuality — Obtém a qualidade de compactação do objeto
- Imagick::getCopyright — Retorna os direitos autorais da API ImageMagick como uma string
- Imagick::getFilename — Obtém o nome do arquivo associado a uma sequência de imagens
- Imagick::getFont — Obtem a fonte
- Imagick::getFormat — Retorna o formato do objeto Imagick
- Imagick::getGravity — Obtém a gravidade
- Imagick::getHomeURL — Retorna o URL da página do ImageMagick
- Imagick::getImage — Retorna um novo objeto Imagick
- Imagick::getImageAlphaChannel — Verifica se a imagem tem um canal alfa
- Imagick::getImageArtifact — Obtém artefato da imagem
- Imagick::getImageAttribute — Retorna um atributo nomeado
- Imagick::getImageBackgroundColor — Retorna a cor de fundo a imagem
- Imagick::getImageBlob — Retorna a sequência de imagem como um BLOB
- Imagick::getImageBluePrimary — Retorna o ponto primário azul da cromaticidade
- Imagick::getImageBorderColor — Retorna a cor da borda da imagem
- Imagick::getImageChannelDepth — Obtém a profundidade de um canal de imagem específico
- Imagick::getImageChannelDistortion — Compara canais de uma imagem com uma imagem reconstruída
- Imagick::getImageChannelDistortions — Obtém distorções de canal
- Imagick::getImageChannelExtrema — Obtém os extremos de um ou mais canais de imagem
- Imagick::getImageChannelKurtosis — Obtenha a curtose e a assimetria de um canal específico
- Imagick::getImageChannelMean — Obtém a média e o desvio padrão
- Imagick::getImageChannelRange — Obtém o intervalo do canal
- Imagick::getImageChannelStatistics — Retorna estatísticas para cada canal na imagem
- Imagick::getImageClipMask — Obtém a máscara de recorte da imagem
- Imagick::getImageColormapColor — Retorna a cor do índice especificado do mapa de cores
- Imagick::getImageColors — Obtém o número de cores únicas na imagem
- Imagick::getImageColorspace — Obtém o espaço de cores da imagem
- Imagick::getImageCompose — Retorna o operador de composição associado à imagem
- Imagick::getImageCompression — Obtém o tipo de compactação da imagem atual
- Imagick::getImageCompressionQuality — Obtém a qualidade de compressão da imagem atual
- Imagick::getImageDelay — Obtém o atraso da imagem
- Imagick::getImageDepth — Obtém a profundidade da imagem
- Imagick::getImageDispose — Obtém o método de descarte de imagem
- Imagick::getImageDistortion — Compara uma imagem com uma imagem reconstruída
- Imagick::getImageExtrema — Obtém os extremos da imagem
- Imagick::getImageFilename — Retorna o nome do arquivo de uma imagem específica em uma sequência
- Imagick::getImageFormat — Retorna o formato de uma imagem específica em uma sequência
- Imagick::getImageGamma — Obtém o gama da imagem
- Imagick::getImageGeometry — Obtém a largura e a altura como um array associativo
- Imagick::getImageGravity — Obtém a gravidade da imagem
- Imagick::getImageGreenPrimary — Retorna o ponto primário verde da cromaticidade
- Imagick::getImageHeight — Retorna a altura da imagem
- Imagick::getImageHistogram — Obtém o histograma da imagem
- Imagick::getImageIndex — Obtém o índice da imagem ativa atual
- Imagick::getImageInterlaceScheme — Obtém o esquema de entrelaçamento da imagem
- Imagick::getImageInterpolateMethod — Retorna o método de interpolação
- Imagick::getImageIterations — Obtém as iterações da imagem
- Imagick::getImageLength — Retorna o comprimento da imagem em bytes
- Imagick::getImageMatte — Informa se a imagem tem um canal fosco
- Imagick::getImageMatteColor — Retorna a cor fosca da imagem
- Imagick::getImageMimeType — Retorna o tipo de mídia da imagem
- Imagick::getImageOrientation — Obtém a orientação da imagem
- Imagick::getImagePage — Retorna a geometria da página
- Imagick::getImagePixelColor — Retorna a cor do pixel especificado
- Imagick::getImageProfile — Retorna o perfil nomeado de imagem
- Imagick::getImageProfiles — Retorna os perfis de imagem
- Imagick::getImageProperties — Retorna as propriedades da imagem
- Imagick::getImageProperty — Retorna a propriedade nomeada da imagem
- Imagick::getImageRedPrimary — Retorna o ponto primário vermelho da cromaticidade
- Imagick::getImageRegion — Extrai uma região da imagem
- Imagick::getImageRenderingIntent — Obtém a intenção de renderização da imagem
- Imagick::getImageResolution — Obtém a resolução X e Y da imagem
- Imagick::getImagesBlob — Retorna todas as sequências de imagens como um BLOB
- Imagick::getImageScene — Obtém a cena da imagem
- Imagick::getImageSignature — Gera um resumo da mensagem SHA-256
- Imagick::getImageSize — Retorna o comprimento da imagem em bytes
- Imagick::getImageTicksPerSecond — Obtém os tiques por segundo da imagem
- Imagick::getImageTotalInkDensity — Obtém a densidade total de tinta da imagem
- Imagick::getImageType — Obtém o tipo potencial da imagem
- Imagick::getImageUnits — Obtém as unidades de resolução da imagem
- Imagick::getImageVirtualPixelMethod — Retorna o método do pixel virtual
- Imagick::getImageWhitePoint — Retorna o ponto branco da cromaticidade
- Imagick::getImageWidth — Retorna a largura da imagem
- Imagick::getInterlaceScheme — Obtém o esquema de entrelaçamento do objeto
- Imagick::getIteratorIndex — Obtém o índice da imagem ativa atual
- Imagick::getNumberImages — Retorna o número de imagens no objeto
- Imagick::getOption — Retorna um valor associado à chave especificada
- Imagick::getPackageName — Retorna o nome do pacote ImageMagick
- Imagick::getPage — Retorna a geometria da página
- Imagick::getPixelIterator — Retorna um MagickPixelIterator
- Imagick::getPixelRegionIterator — Obtém um ImagickPixelIterator para uma seção de imagem
- Imagick::getPointSize — Obtém o tamanho do ponto
- Imagick::getQuantum — Retorna o intervalo Quantum do Imagick
- Imagick::getQuantumDepth — Obtém a profundidade Quantum
- Imagick::getQuantumRange — Retorna o intervalo Quantum do Imagick
- Imagick::getRegistry — Obtém uma entrada StringRegistry
- Imagick::getReleaseDate — Retorna a data da versão do ImageMagick
- Imagick::getResource — Retorna o uso de memória do recurso especificado
- Imagick::getResourceLimit — Retorna o limite de recursos especificado
- Imagick::getSamplingFactors — Obtém o fator de amostragem horizontal e vertical
- Imagick::getSize — Retorna o tamanho associado ao objeto Imagick
- Imagick::getSizeOffset — Retorna o deslocamento de tamanho
- Imagick::getVersion — Retorna a versão da API ImageMagick
- Imagick::haldClutImage — Substitui cores na imagem
- Imagick::hasNextImage — Verifica se o objeto possui mais imagens
- Imagick::hasPreviousImage — Verifica se o objeto possui uma imagem anterior
- Imagick::identifyFormat — Formata uma string com detalhes da imagem
- Imagick::identifyImage — Identifica uma imagem e busca atributos
- Imagick::implodeImage — Cria uma nova imagem como cópia
- Imagick::importImagePixels — Importa pixels de imagem
- Imagick::inverseFourierTransformImage — Implementa a transformada discreta inversa de Fourier (DFT)
- Imagick::labelImage — Adiciona um rótulo a uma imagem
- Imagick::levelImage — Ajusta os níveis de uma imagem
- Imagick::linearStretchImage — Estica com saturação a intensidade da imagem
- Imagick::liquidRescaleImage — Anima uma imagem ou imagens
- Imagick::listRegistry — Lista todas as configurações do registro
- Imagick::magnifyImage — Dimensiona uma imagem proporcionalmente 2x
- Imagick::mapImage — Substitui as cores de uma imagem pela cor mais próxima de uma imagem de referência
- Imagick::matteFloodfillImage — Altera o valor de transparência de uma cor
- Imagick::medianFilterImage — Aplica um filtro digital
- Imagick::mergeImageLayers — Mescla camadas de imagem
- Imagick::minifyImage — Dimensiona uma imagem proporcionalmente à metade do seu tamanho
- Imagick::modulateImage — Controle brilho, saturação e matiz
- Imagick::montageImage — Cria uma imagem composta
- Imagick::morphImages — Transforma um conjunto de imagens
- Imagick::morphology — Aplica um kernel fornecido pelo usuário à imagem de acordo com o método de morfologia fornecido
- Imagick::mosaicImages — Forma um mosaico a partir de imagens
- Imagick::motionBlurImage — Simula desfoque de movimento
- Imagick::negateImage — Negativa as cores na imagem de referência
- Imagick::newImage — Cria uma nova imagem
- Imagick::newPseudoImage — Cria uma nova imagem
- Imagick::nextImage — Passa para a próxima imagem
- Imagick::normalizeImage — Melhora o contraste de uma imagem colorida
- Imagick::oilPaintImage — Simula uma pintura a óleo
- Imagick::opaquePaintImage — Altera o valor da cor de qualquer pixel que corresponda ao alvo
- Imagick::optimizeImageLayers — Remove partes repetidas de imagens para otimizar
- Imagick::orderedPosterizeImage — Executa um pontilhamento ordenado
- Imagick::paintFloodfillImage — Altera o valor da cor de qualquer pixel que corresponda ao alvo
- Imagick::paintOpaqueImage — Altera qualquer pixel que corresponda à cor
- Imagick::paintTransparentImage — Altera qualquer pixel que corresponda à cor definida pelo preenchimento
- Imagick::pingImage — Busca atributos básicos sobre a imagem
- Imagick::pingImageBlob — Busca atributos rapidamente
- Imagick::pingImageFile — Obtém atributos básicos de imagem de maneira leve
- Imagick::polaroidImage — Simula uma imagem Polaroid
- Imagick::posterizeImage — Reduz a imagem a um número limitado de níveis de cor
- Imagick::previewImages — Identifica rapidamente os parâmetros apropriados para processamento de imagem
- Imagick::previousImage — Passa para a imagem anterior no objeto
- Imagick::profileImage — Adiciona ou remove um perfil de uma imagem
- Imagick::quantizeImage — Analisa as cores dentro de uma imagem de referência
- Imagick::quantizeImages — Analisa as cores dentro de uma sequência de imagens
- Imagick::queryFontMetrics — Retorna um array representando as métricas da fonte
- Imagick::queryFonts — Retorna as fontes configuradas
- Imagick::queryFormats — Retorna formatos suportados pelo Imagick
- Imagick::radialBlurImage — Desfoca uma imagem de forma radial
- Imagick::raiseImage — Cria um efeito simulado de botão 3D
- Imagick::randomThresholdImage — Cria uma imagem de alto contraste e duas cores
- Imagick::readImage — Lê imagem de um arquivo
- Imagick::readImageBlob — Lê imagem de uma string binária
- Imagick::readImageFile — Lê imagem a partir de um descritor de arquivo
- Imagick::readimages — Lê imagens de um array de arquivos
- Imagick::recolorImage — Recolore imagem
- Imagick::reduceNoiseImage — Suaviza os contornos de uma imagem
- Imagick::remapImage — Remapeia as cores da imagem
- Imagick::removeImage — Remove uma imagem da lista de imagens
- Imagick::removeImageProfile — Remove o perfil de imagem nomeado e o retorna
- Imagick::render — Renderiza todos os comandos de desenho anteriores
- Imagick::resampleImage — Reamostra imagem para a resolução desejada
- Imagick::resetImagePage — Redefine página de imagem
- Imagick::resizeImage — Dimensiona uma imagem
- Imagick::rollImage — Desloca uma imagem
- Imagick::rotateImage — Rotaciona uma imagem
- Imagick::rotationalBlurImage — Desfoca uma imagem de forma rotacional
- Imagick::roundCorners — Arredonda os cantos da imagem
- Imagick::sampleImage — Dimensiona uma imagem com amostragem de pixels
- Imagick::scaleImage — Dimensiona o tamanho de uma imagem
- Imagick::segmentImage — Segmenta uma imagem
- Imagick::selectiveBlurImage — Desfocar seletivamente uma imagem dentro de um limite de contraste
- Imagick::separateImageChannel — Separa um canal da imagem
- Imagick::sepiaToneImage — Aplica tons de sépia em uma imagem
- Imagick::setBackgroundColor — Define a cor de fundo padrão do objeto
- Imagick::setColorspace — Define espaço de cores
- Imagick::setCompression — Define o tipo de compactação padrão do objeto
- Imagick::setCompressionQuality — Define a qualidade de compactação padrão do objeto
- Imagick::setFilename — Define o nome do arquivo antes de ler ou gravar a imagem
- Imagick::setFirstIterator — Define o iterador Imagick para a primeira imagem
- Imagick::setFont — Define a fonte
- Imagick::setFormat — Define o formato do objeto Imagick
- Imagick::setGravity — Define a gravidade
- Imagick::setImage — Substitui imagem no objeto
- Imagick::setImageAlphaChannel — Define o canal alfa da imagem
- Imagick::setImageArtifact — Definir artefato de imagem
- Imagick::setImageAttribute — Define um atributo de imagem
- Imagick::setImageBackgroundColor — Define a cor de fundo da imagem
- Imagick::setImageBias — Define o ajuste (bias) da imagem para qualquer método que faça convolução em uma imagem
- Imagick::setImageBiasQuantum — Define o ajuste (bias) da imagem
- Imagick::setImageBluePrimary — Define o ponto primário azul da cromaticidade da imagem
- Imagick::setImageBorderColor — Define a cor da borda da imagem
- Imagick::setImageChannelDepth — Define a profundidade de um canal de imagem específico
- Imagick::setImageClipMask — Define a máscara de recorte da imagem
- Imagick::setImageColormapColor — Define a cor do índice do mapa de cores especificado
- Imagick::setImageColorspace — Define o espaço de cores da imagem
- Imagick::setImageCompose — Define o operador de composição de imagem
- Imagick::setImageCompression — Define a compactação da imagem
- Imagick::setImageCompressionQuality — Define a qualidade de compactação da imagem
- Imagick::setImageDelay — Define o atraso da imagem
- Imagick::setImageDepth — Define a profundidade da imagem
- Imagick::setImageDispose — Define o método de descarte de imagem
- Imagick::setImageExtent — Define o tamanho da imagem
- Imagick::setImageFilename — Define o nome do arquivo de uma imagem específica
- Imagick::setImageFormat — Define o formato de uma imagem específica
- Imagick::setImageGamma — Define o gama da imagem
- Imagick::setImageGravity — Define a gravidade da imagem
- Imagick::setImageGreenPrimary — Define o ponto primário verde da cromaticidade da imagem
- Imagick::setImageIndex — Define a posição do iterador
- Imagick::setImageInterlaceScheme — Define a compactação da imagem
- Imagick::setImageInterpolateMethod — Define o método de interpolação de pixel da imagem.
- Imagick::setImageIterations — Define as iterações da imagem
- Imagick::setImageMatte — Define o canal fosco da imagem
- Imagick::setImageMatteColor — Define a cor fosca da imagem
- Imagick::setImageOpacity — Define o nível de opacidade da imagem
- Imagick::setImageOrientation — Define a orientação da imagem
- Imagick::setImagePage — Define a geometria da página da imagem
- Imagick::setImageProfile — Adiciona um perfil nomeado ao objeto Imagick
- Imagick::setImageProperty — Define uma propriedade de imagem
- Imagick::setImageRedPrimary — Define o ponto primário vermelho da cromaticidade da imagem
- Imagick::setImageRenderingIntent — Define a intenção de renderização da imagem
- Imagick::setImageResolution — Define a resolução da imagem
- Imagick::setImageScene — Define a cena da imagem
- Imagick::setImageTicksPerSecond — Define os tiques por segundo da imagem
- Imagick::setImageType — Define o tipo de imagem
- Imagick::setImageUnits — Define as unidades de resolução da imagem
- Imagick::setImageVirtualPixelMethod — Define o método de pixel virtual da imagem
- Imagick::setImageWhitePoint — Define o ponto branco da cromaticidade da imagem
- Imagick::setInterlaceScheme — Define o esquema de entrelaçamento da imagem
- Imagick::setIteratorIndex — Define a posição do iterador
- Imagick::setLastIterator — Define o iterador Imagick para a última imagem
- Imagick::setOption — Define uma opção
- Imagick::setPage — Define a geometria da página do objeto Imagick
- Imagick::setPointSize — Define o tamanho em pontos
- Imagick::setProgressMonitor — Define uma função de retorno a ser chamada durante o processamento
- Imagick::setRegistry — Define a chave nomeada do registro do ImageMagick para um valor
- Imagick::setResolution — Define a resolução da imagem
- Imagick::setResourceLimit — Define o limite para um recurso específico
- Imagick::setSamplingFactors — Define os fatores de amostragem da imagem
- Imagick::setSize — Define o tamanho do objeto Imagick
- Imagick::setSizeOffset — Define o tamanho e o deslocamento do objeto Imagick
- Imagick::setType — Define o atributo de tipo de imagem
- Imagick::shadeImage — Cria um efeito 3D
- Imagick::shadowImage — Simula uma sombra de imagem
- Imagick::sharpenImage — Torna uma imagem mais nítida
- Imagick::shaveImage — Raspa pixels das bordas da imagem
- Imagick::shearImage — Cria um paralelogramo
- Imagick::sigmoidalContrastImage — Ajusta o contraste de uma imagem
- Imagick::sketchImage — Simula um esboço a lápis
- Imagick::smushImages — Agrupa todas as imagens do ponteiro da imagem atual até o final da lista de imagens
- Imagick::solarizeImage — Aplica um efeito solarizante à imagem
- Imagick::sparseColorImage — Interpola cores
- Imagick::spliceImage — Une uma cor sólida na imagem
- Imagick::spreadImage — Desloca aleatoriamente cada pixel em um bloco
- Imagick::statisticImage — Modifica a imagem usando uma função estatística
- Imagick::steganoImage — Oculta uma marca d'água digital na imagem
- Imagick::stereoImage — Compõe duas imagens
- Imagick::stripImage — Remove todos os perfis e comentários de uma imagem
- Imagick::subImageMatch — Procura uma subimagem na imagem atual e retorna uma imagem semelhante
- Imagick::swirlImage — Gira os pixels em torno do centro da imagem
- Imagick::textureImage — Ladrilha repetidamente a imagem da textura
- Imagick::thresholdImage — Altera o valor de pixels individuais com base em um limite
- Imagick::thumbnailImage — Altera o tamanho de uma imagem
- Imagick::tintImage — Aplica um vetor de cores a cada pixel da imagem
- Imagick::__toString — Retorna a imagem como uma string
- Imagick::transformImage — Método conveniente para definir o tamanho do corte e a geometria da imagem
- Imagick::transformImageColorspace — Transforma uma imagem em um novo espaço de cores
- Imagick::transparentPaintImage — Pinta pixels com a cor transparente
- Imagick::transposeImage — Cria uma imagem espelhada vertical
- Imagick::transverseImage — Cria uma imagem espelhada horizontal
- Imagick::trimImage — Apara as bordas da imagem
- Imagick::uniqueImageColors — Descarta todas, exceto uma, de qualquer cor de pixel
- Imagick::unsharpMaskImage — Torna uma imagem mais nítida
- Imagick::valid — Verifica se o item atual é válido
- Imagick::vignetteImage — Adiciona filtro de vinheta à imagem
- Imagick::waveImage — Aplica filtro de onda à imagem
- Imagick::whiteThresholdImage — Força todos os pixels acima de um limite para branco
- Imagick::writeImage — Grava uma imagem no nome de arquivo especificado
- Imagick::writeImageFile — Grava uma imagem em um descritor de arquivo
- Imagick::writeImages — Grava uma imagem ou sequência de imagens
- Imagick::writeImagesFile — Grava quadros em um descritor de arquivo

# A classe ImagickDraw

(PECL imagick 2, PECL imagick 3)

## Resumo da classe

class ImagickDraw {
public function affine(array `$affine`): bool
public function annotation(float `$x`, float `$y`, string `$text`): bool
public function arc(
float `$start_x`,
float `$start_y`,
float `$end_x`,
float `$end_y`,
float `$start_angle`,
float `$end_angle`
): bool
public function bezier(array `$coordinates`): bool
public function circle(
float `$origin_x`,
float `$origin_y`,
float `$perimeter_x`,
float `$perimeter_y`
): bool
public function clear(): bool
public function clone(): ImagickDraw
public function color(float `$x`, float `$y`, int `$paint`): bool
public function comment(string `$comment`): bool
public function composite(
int `$composite`,
float `$x`,
float `$y`,
float `$width`,
float `$height`,
Imagick `$image`
): bool
public function destroy(): bool
public function ellipse(
float `$origin_x`,
float `$origin_y`,
float `$radius_x`,
float `$radius_y`,
float `$angle_start`,
float `$angle_end`
): bool
public function getClipPath(): false|string
public function getClipRule(): int
public function getClipUnits(): int
public function getFillColor(): ImagickPixel
public function getFillOpacity(): float
public function getFillRule(): int
public function getFont(): string
public function getFontFamily(): string
public function getFontSize(): float
public function getFontStretch(): int
public function getFontStyle(): int
public function getFontWeight(): int
public function getGravity(): int
public function getStrokeAntialias(): bool
public function getStrokeColor(): ImagickPixel
public function getStrokeDashArray(): array
public function getStrokeDashOffset(): float
public function getStrokeLineCap(): int
public function getStrokeLineJoin(): int
public function getStrokeMiterLimit(): int
public function getStrokeOpacity(): float
public function getStrokeWidth(): float
public function getTextAlignment(): int
public function getTextAntialias(): bool
public function getTextDecoration(): int
public function getTextEncoding(): false|string
public function getTextInterlineSpacing(): float
public function getTextInterwordSpacing(): float
public function getTextKerning(): float
public function getTextUnderColor(): ImagickPixel
public function getVectorGraphics(): string
public function line(
float `$start_x`,
float `$start_y`,
float `$end_x`,
float `$end_y`
): bool
public function matte(float `$x`, float `$y`, int `$paint`): bool
public function pathClose(): bool
public function pathCurveToAbsolute(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
public function pathCurveToQuadraticBezierAbsolute(
float `$x1`,
float `$y1`,
float `$x_end`,
float `$y`
): bool
public function pathCurveToQuadraticBezierRelative(
float `$x1`,
float `$y1`,
float `$x_end`,
float `$y`
): bool
public function pathCurveToQuadraticBezierSmoothAbsolute(float `$x`, float `$y`): bool
public function pathCurveToQuadraticBezierSmoothRelative(float `$x`, float `$y`): bool
public function pathCurveToRelative(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
public function pathCurveToSmoothAbsolute(
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
public function pathCurveToSmoothRelative(
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
public function pathEllipticArcAbsolute(
float `$rx`,
float `$ry`,
float `$x_axis_rotation`,
bool `$large_arc`,
bool `$sweep`,
float `$x`,
float `$y`
): bool
public function pathEllipticArcRelative(
float `$rx`,
float `$ry`,
float `$x_axis_rotation`,
bool `$large_arc`,
bool `$sweep`,
float `$x`,
float `$y`
): bool
public function pathFinish(): bool
public function pathLineToAbsolute(float `$x`, float `$y`): bool
public function pathLineToHorizontalAbsolute(float `$x`): bool
public function pathLineToHorizontalRelative(float `$x`): bool
public function pathLineToRelative(float `$x`, float `$y`): bool
public function pathLineToVerticalAbsolute(float `$y`): bool
public function pathLineToVerticalRelative(float `$y`): bool
public function pathMoveToAbsolute(float `$x`, float `$y`): bool
public function pathMoveToRelative(float `$x`, float `$y`): bool
public function pathStart(): bool
public function point(float `$x`, float `$y`): bool
public function polygon(array `$coordinates`): bool
public function polyline(array `$coordinates`): bool
public function pop(): bool
public function popClipPath(): bool
public function popDefs(): bool
public function popPattern(): bool
public function push(): bool
public function pushClipPath(string `$clip_mask_id`): bool
public function pushDefs(): bool
public function pushPattern(
string `$pattern_id`,
float `$x`,
float `$y`,
float `$width`,
float `$height`
): bool
public function rectangle(
float `$top_left_x`,
float `$top_left_y`,
float `$bottom_right_x`,
float `$bottom_right_y`
): bool
public function render(): bool
public function resetVectorGraphics(): bool
public function rotate(float `$degrees`): bool
public function roundRectangle(
float `$top_left_x`,
float `$top_left_y`,
float `$bottom_right_x`,
float `$bottom_right_y`,
float `$rounding_x`,
float `$rounding_y`
): bool
public function scale(float `$x`, float `$y`): bool
public function setClipPath(string `$clip_mask`): bool
public function setClipRule(int `$fillrule`): bool
public function setClipUnits(int `$pathunits`): bool
public function setFillAlpha(float `$alpha`): bool
public function setFillColor(ImagickPixel|string `$fill_color`): bool
public function setFillOpacity(float `$opacity`): bool
public function setFillPatternURL(string `$fill_url`): bool
public function setFillRule(int `$fillrule`): bool
public function setFont(string `$font_name`): bool
public function setFontFamily(string `$font_family`): bool
public function setFontSize(float `$point_size`): bool
public function setFontStretch(int `$stretch`): bool
public function setFontStyle(int `$style`): bool
public function setFontWeight(int `$weight`): bool
public function setGravity(int `$gravity`): bool
public function setResolution(float `$resolution_x`, float `$resolution_y`): bool
public function setStrokeAlpha(float `$alpha`): bool
public function setStrokeAntialias(bool `$enabled`): bool
public function setStrokeColor(ImagickPixel|string `$color`): bool
public function setStrokeDashArray(?array `$dashes`): bool
public function setStrokeDashOffset(float `$dash_offset`): bool
public function setStrokeLineCap(int `$linecap`): bool
public function setStrokeLineJoin(int `$linejoin`): bool
public function setStrokeMiterLimit(int `$miterlimit`): bool
public function setStrokeOpacity(float `$opacity`): bool
public function setStrokePatternURL(string `$stroke_url`): bool
public function setStrokeWidth(float `$width`): bool
public function setTextAlignment(int `$align`): bool
public function setTextAntialias(bool `$antialias`): bool
public function setTextDecoration(int `$decoration`): bool
public function setTextEncoding(string `$encoding`): bool
public function setTextInterlineSpacing(float `$spacing`): bool
public function setTextInterwordSpacing(float `$spacing`): bool
public function setTextKerning(float `$kerning`): bool
public function setTextUnderColor(ImagickPixel|string `$under_color`): bool
public function setVectorGraphics(string `$xml`): bool
public function setViewbox(
int `$left_x`,
int `$top_y`,
int `$right_x`,
int `$bottom_y`
): bool
public function skewX(float `$degrees`): bool
public function skewY(float `$degrees`): bool
public function translate(float `$x`, float `$y`): bool
}

# ImagickDraw::affine

(PECL imagick 2, PECL imagick 3)

ImagickDraw::affine — Ajusta a matriz de transformação afim atual

### Descrição

public function ImagickDraw::affine(array `$affine`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Ajusta a matriz de transformação afim atual com a matriz de transformação afim especificada.

### Parâmetros

`affine`

  Parâmetros da matriz afim.

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::affine()

    <?php
    function affine($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeWidth(1);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);

        $PI = 3.141592653589794;
        $angle = 60 * $PI / 360;

        // Dimensiona as coordernadas de desenho.
        $affineScale = array("sx" => 1.75, "sy" => 1.75, "rx" => 0, "ry" => 0, "tx" => 0, "ty" => 0);

        // Cisalha as coordernadas de desenho.
        $affineShear = array("sx" => 1, "sy" => 1, "rx" => sin($angle), "ry" => -sin($angle), "tx" => 0, "ty" => 0);

        // Rotaciona as coordernadas. A matriz afim de cisalhamento
        // produz desenhos com escala incorreta.
        $affineRotate = array("sx" => cos($angle), "sy" => cos($angle), "rx" => sin($angle), "ry" => -sin($angle), "tx" => 0, "ty" => 0,);

        // Translação (deslocamento) do desenho
        $affineTranslate = array("sx" => 1, "sy" => 1, "rx" => 0, "ry" => 0, "tx" => 30, "ty" => 30);

        // A matriz afim de identidade
        $affineIdentity = array("sx" => 1, "sy" => 1, "rx" => 0, "ry" => 0, "tx" => 0, "ty" => 0);

        $examples = [$affineScale, $affineShear, $affineRotate, $affineTranslate, $affineIdentity,];

        $count = 0;

        foreach ($examples as $example) {
            $draw->push();
            $draw->translate(($count % 2) * 250, intval($count / 2) * 250);
            $draw->translate(100, 100);
            $draw->affine($example);
            $draw->rectangle(-50, -50, 50, 50);
            $draw->pop();
            $count++;
        }

        // Cria um objeto de imagem no qual os comandos de desenho podem ser processados
        $image = new \Imagick();
        $image->newImage(500, 750, $backgroundColor);
        $image->setImageFormat("png");

        // Renderiza os comandos de desenho no objeto ImagickDraw
        // na imagem.
        $image->drawImage($draw);

        // Envia a imagem para o navegador
        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::annotation

(PECL imagick 2, PECL imagick 3)

ImagickDraw::annotation — Desenha texto na imagem

### Descrição

public function ImagickDraw::annotation(float `$x`, float `$y`, string `$text`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desenha texto na imagem.

### Parâmetros

`x`

  A coodernada x onde o texto será desenhado

`y`

  A coodernada y onde o texto será desenhado

`text`

  O texto a ser desenhado na imagem

### Valor Retornado

Nenhum valor é retornado.

# ImagickDraw::arc

(PECL imagick 2, PECL imagick 3)

ImagickDraw::arc — Desenha um arco

### Descrição

public function ImagickDraw::arc(
float `$start_x`,
float `$start_y`,
float `$end_x`,
float `$end_y`,
float `$start_angle`,
float `$end_angle`
): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desenha um arco dentro de uma área retangular especificada na imagem.

### Parâmetros

`start_x`

  coordenada x do começo da área retangular

`start_y`

  coordenada y do começo da área retangular

`end_x`

  coordenada x do fim da área retangular

`end_y`

  coordenada y do fim da área retangular

`start_angle`

  ângulo inicial, em graus, da rotação

`end_angle`

  ângulo final, em graus, da rotação

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::arc()

    <?php
    function arc($strokeColor, $fillColor, $backgroundColor, $startX, $startY, $endX, $endY, $startAngle, $endAngle) {

        // Cria um objeto ImagickDraw onde será desenhado.
        $draw = new \ImagickDraw();
        $draw->setStrokeWidth(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(2);

        $draw->arc($startX, $startY, $endX, $endY, $startAngle, $endAngle);

        // Cria um objeto de imagem no qual os comandos de desenho serão processados
        $image = new \Imagick();
        $image->newImage(IMAGE_WIDTH, IMAGE_HEIGHT, $backgroundColor);
        $image->setImageFormat("png");

        // Renderiza os comandos de desenho no objeto ImagickDraw
        // da imagem.
        $image->drawImage($draw);

        // Envia a imagem ao navegador
        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::bezier

(PECL imagick 2, PECL imagick 3)

ImagickDraw::bezier — Desenha uma curva de Bézier

### Descrição

public function ImagickDraw::bezier(array `$coordinates`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desenha uma curva de Bézier através de um conjunto de pontos na imagem.

### Parâmetros

`coordinates`

  Array multidimensional do tipo: array( array( 'x' => 1, 'y' => 2 ), array( 'x' => 3, 'y' => 4 ) )

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::bezier()

    <?php
    function bezier($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $strokeColor = new \ImagickPixel($strokeColor);
        $fillColor = new \ImagickPixel($fillColor);

        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);

        $smoothPointsSet = [
            [
                ['x' => 10.0 * 5, 'y' => 10.0 * 5],
                ['x' => 30.0 * 5, 'y' => 90.0 * 5],
                ['x' => 25.0 * 5, 'y' => 10.0 * 5],
                ['x' => 50.0 * 5, 'y' => 50.0 * 5],
            ],
            [
                ['x' => 50.0 * 5, 'y' => 50.0 * 5],
                ['x' => 75.0 * 5, 'y' => 90.0 * 5],
                ['x' => 70.0 * 5, 'y' => 10.0 * 5],
                ['x' => 90.0 * 5, 'y' => 40.0 * 5],
            ],
        ];

        foreach ($smoothPointsSet as $points) {
            $draw->bezier($points);
        }

        $disjointPoints = [
            [
                ['x' => 10 * 5, 'y' => 10 * 5],
                ['x' => 30 * 5, 'y' => 90 * 5],
                ['x' => 25 * 5, 'y' => 10 * 5],
                ['x' => 50 * 5, 'y' => 50 * 5],
            ],
            [
                ['x' => 50 * 5, 'y' => 50 * 5],
                ['x' => 80 * 5, 'y' => 50 * 5],
                ['x' => 70 * 5, 'y' => 10 * 5],
                ['x' => 90 * 5, 'y' => 40 * 5],
            ]
        ];
        $draw->translate(0, 200);

        foreach ($disjointPoints as $points) {
            $draw->bezier($points);
        }

        // Cria um objeto de imagem no qual os comandos de desenho serão processados
        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        // Renderiza os comandos de desenho no objeto ImagickDraw
        // da imagem.
        $imagick->drawImage($draw);

        // Envia a imagem para o navegador
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::circle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::circle — Desenha um círculo

### Descrição

public function ImagickDraw::circle(
float `$origin_x`,
float `$origin_y`,
float `$perimeter_x`,
float `$perimeter_y`
): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desenha um círculo na imagem.

### Parâmetros

`origin_x`

  Coordenada x da origem.

`origin_y`

  Coordenada y da origem.

`perimeter_x`

  Coordenada x do perímetro.

`perimeter_y`

  Coordenada y do perímetro.

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::circle()

    <?php
    function circle($strokeColor, $fillColor, $backgroundColor, $originX, $originY, $endX, $endY) {

        // Cria um objeto ImagickDraw onde o círculo será desenhado.
        $draw = new \ImagickDraw();

        $strokeColor = new \ImagickPixel($strokeColor);
        $fillColor = new \ImagickPixel($fillColor);

        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);

        $draw->circle($originX, $originY, $endX, $endY);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::clear

(PECL imagick 2, PECL imagick 3)

ImagickDraw::clear — Limpa o ImagickDraw

### Descrição

public function ImagickDraw::clear(): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Limpa todos os comandos acumulados do objeto ImagickDraw e redefine as configurações para o seu padrão.

### Valor Retornado

Retorna um objeto ImagickDraw.

# ImagickDraw::clone

(PECL imagick 2, PECL imagick 3)

ImagickDraw::clone — Faz uma cópia exata do objeto ImagickDraw especificado

### Descrição

public function ImagickDraw::clone(): ImagickDraw
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Faz uma cópia exata do objeto ImagickDraw especificado.

### Valor Retornado

Retorna uma cópia exata do objeto ImagickDraw especificado.

# ImagickDraw::color

(PECL imagick 2, PECL imagick 3)

ImagickDraw::color — Desenha cores na imagem

### Descrição

public function ImagickDraw::color(float `$x`, float `$y`, int `$paint`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desenha a cor na imagem usando a cor de preenchimento atual, começando na posição especificada e usando o método de pintura especificado.

### Parâmetros

`x`

  Coordernada x da pintura.

`y`

  Coordernada y da pintura.

`paint`

  Uma das constantes PAINT (`imagick::PAINT_*`).

### Valor Retornado

Nenhum valor é retornado.

# ImagickDraw::comment

(PECL imagick 2, PECL imagick 3)

ImagickDraw::comment — Adiciona um comentário

### Descrição

public function ImagickDraw::comment(string `$comment`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Adiciona um comentário a um fluxo de saída de vetor.

### Parâmetros

`comment`

  A string de comentário a ser adicionada ao fluxo de saída do vetor.

### Valor Retornado

Nenhum valor é retornado.

# ImagickDraw::composite

(PECL imagick 2, PECL imagick 3)

ImagickDraw::composite — Compõe uma imagem sobre a imagem atual

### Descrição

public function ImagickDraw::composite(
int `$composite`,
float `$x`,
float `$y`,
float `$width`,
float `$height`,
Imagick `$image`
): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Compõe uma imagem sobre a imagem atual, usando o operador de composição especificado, a posição especificada e o tamanho especificado.

### Parâmetros

`composite`

  Operador de composição. Uma das constantes de operação de composição (`imagick::COMPOSITE_*`).

`x`

  Coordenada x do canto superior esquerdo.

`y`

  Coordenada y do canto superior esquerdo.

`width`

  Largura da imagem de composição.

`height`

  Altura da imagem de composição.

`image`

  O objeto Imagick de onde a imagem de composição foi tirada.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::composite()

    <?php
    function composite($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setFillOpacity(1);
        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setStrokeWidth(2);
        $draw->setFont("../fonts/CANDY.TTF");
        $draw->setFontSize(140);
        $draw->rectangle(0, 0, 1000, 300);
        $draw->setFillColor('white');
        $draw->setfillopacity(1);
        $draw->annotation(50, 180, "Lorem Ipsum!");

        // Cria um objeto de imagem no qual os comandos de desenho possam ser renderizados
        $imagick = new \Imagick();
        $imagick->newImage(1000, 302, $backgroundColor);
        $imagick->setImageFormat("png");

        // Renderiza os comandos de desenho no objeto ImagickDraw
        // na imagem.
        $imagick->drawImage($draw);

        // Envia a imagem para o navegador
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::__construct

(PECL imagick 2, PECL imagick 3)

ImagickDraw::__construct — O construtor ImagickDraw

### Descrição

public function ImagickDraw::__construct()
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

O construtor ImagickDraw.

### Valor Retornado

Nenhum valor é retornado.

# ImagickDraw::destroy

(PECL imagick 2, PECL imagick 3)

ImagickDraw::destroy — Libera todos os recursos associados

### Descrição

public function ImagickDraw::destroy(): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Libera todos os recursos associados ao objeto ImagickDraw.

### Valor Retornado

Nenhum valor é retornado.

# ImagickDraw::ellipse

(PECL imagick 2, PECL imagick 3)

ImagickDraw::ellipse — Desenha uma elipse na imagem

### Descrição

public function ImagickDraw::ellipse(
float `$origin_x`,
float `$origin_y`,
float `$radius_x`,
float `$radius_y`,
float `$angle_start`,
float `$angle_end`
): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desenha uma elipse na imagem.

### Parâmetros

`origin_x`

`origin_y`

`radius_x`

`radius_y`

`angle_start`

`angle_end`

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::ellipse()

    <?php
    function ellipse($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);

        $draw->ellipse(125, 70, 100, 50, 0, 360);
        $draw->ellipse(350, 70, 100, 50, 0, 315);

        $draw->push();
        $draw->translate(125, 250);
        $draw->rotate(30);
        $draw->ellipse(0, 0, 100, 50, 0, 360);
        $draw->pop();

        $draw->push();
        $draw->translate(350, 250);
        $draw->rotate(30);
        $draw->ellipse(0, 0, 100, 50, 0, 315);
        $draw->pop();

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::getClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getClipPath — Obtém o ID do caminho de recorte atual

### Descrição

public function ImagickDraw::getClipPath(): false|string
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Obtém o ID do caminho de recorte atual.

### Valor Retornado

Retorna uma string contendo o ID do caminho de recorte ou false se não existir nenhum.

# ImagickDraw::getClipRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getClipRule — Retorna a regra atual de preenchimento do polígono

### Descrição

public function ImagickDraw::getClipRule(): int
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna a regra atual de preenchimento do polígono para ser usada pelo caminho de recorte.

### Valor Retornado

Retorna uma constante FILLRULE (`imagick::FILLRULE_*`).

# ImagickDraw::getClipUnits

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getClipUnits — Retorna a interpretação das unidades de caminho de recorte

### Descrição

public function ImagickDraw::getClipUnits(): int
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna a interpretação das unidades de caminho de recorte.

### Valor Retornado

Retorna um int em caso de sucesso.

# ImagickDraw::getFillColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFillColor — Retorna a cor de preenchimento

### Descrição

public function ImagickDraw::getFillColor(): ImagickPixel
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna a cor de preenchimento usada para desenhar objetos preenchidos.

### Valor Retornado

Retorna um objeto ImagickPixel.

# ImagickDraw::getFillOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFillOpacity — Retorna a opacidade usada ao desenhar

### Descrição

public function ImagickDraw::getFillOpacity(): float
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna a opacidade usada ao desenhar usando a cor ou textura de preenchimento. Totalmente opaco é 1.0.

### Valor Retornado

A opacidade.

# ImagickDraw::getFillRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFillRule — Retorna a regra de preenchimento

### Descrição

public function ImagickDraw::getFillRule(): int
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna a regra de preenchimento usada ao desenhar polígonos.

### Valor Retornado

Retorna uma constante FILLRULE (`imagick::FILLRULE_*`).

# ImagickDraw::getFont

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFont — Retorna a fonte

### Descrição

public function ImagickDraw::getFont(): string
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna uma string especificando a fonte usada ao fazer anotações com texto.

### Valor Retornado

Retorna uma string em caso de sucesso e falso se nenhuma fonte for definida.

# ImagickDraw::getFontFamily

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontFamily — Retorna a família de fontes

### Descrição

public function ImagickDraw::getFontFamily(): string
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna a família de fontes a ser usada ao fazer anotações com texto.

### Valor Retornado

Retorna a família de fontes atualmente selecionada ou falso se a família de fontes não estiver definida.

# ImagickDraw::getFontSize

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontSize — Retorna o tamanho da fonte em pontos

### Descrição

public function ImagickDraw::getFontSize(): float
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna o tamanho da fonte usado ao fazer anotações com texto.

### Valor Retornado

Retorna o tamanho da fonte associado ao objeto ImagickDraw atual.

# ImagickDraw::getFontStretch

(PECL imagick 2 >=2.3.0, PECL imagick 3)

ImagickDraw::getFontStretch — Obtém o esticamento de fonte a ser usado ao fazer anotações com texto

### Descrição

public function ImagickDraw::getFontStretch(): int

Obtém o esticamento de fonte a ser usado ao fazer anotações com texto. Retorna um StretchType.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# ImagickDraw::getFontStyle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontStyle — Retorna o estilo da fonte

### Descrição

public function ImagickDraw::getFontStyle(): int
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna o estilo de fonte usado ao fazer anotações com texto.

### Valor Retornado

Retorna uma constante STYLE (`imagick::STYLE_*`) associada ao objeto ImagickDraw ou 0 se nenhum estilo estiver definido.

# ImagickDraw::getFontWeight

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontWeight — Retorna a espessura da fonte

### Descrição

public function ImagickDraw::getFontWeight(): int
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna a espessura da fonte usada ao fazer anotações com texto.

### Valor Retornado

Retorna um int em caso de sucesso e 0 se nenhum peso for definido.

# ImagickDraw::getGravity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getGravity — Retorna o alinhamento de posicionamento do texto

### Descrição

public function ImagickDraw::getGravity(): int
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna o alinhento de posicionamento usado ao fazer anotações com texto.

### Valor Retornado

Retorna uma constante GRAVITY (`imagick::GRAVITY_*`) em caso de sucesso ou 0 se nenhum alinhamento estiver definido.

# ImagickDraw::getStrokeAntialias

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeAntialias — Retorna a configuração atual de suavização do traço

### Descrição

public function ImagickDraw::getStrokeAntialias(): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna a configuração atual de anti-serrilhamento do traço. Os contornos traçados são suavizados por padrão. Quando a suavização está desabilitada, os pixels traçados são analisados para determinar se deve ser usada a cor do traço ou a cor subjacente da tela.

### Valor Retornado

Retorna `true` se a suavização está ligada ou `false` se estiver desligada.

# ImagickDraw::getStrokeColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeColor — Retorna a cor usada para traçar os contornos dos objetos

### Descrição

public function ImagickDraw::getStrokeColor(): ImagickPixel
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna a cor usada para traçar os contornos dos objetos.

### Parâmetros

`stroke_color`

### Valor Retornado

Retorna um objeto ImagickPixel que descreve a cor.

# ImagickDraw::getStrokeDashArray

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeDashArray — Retorna um array que representa o padrão de traços e espaços usados ​​para traçar caminhos

### Descrição

public function ImagickDraw::getStrokeDashArray(): array
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna um array que representa o padrão de traços e espaços usados ​​para traçar caminhos.

### Valor Retornado

Retorna um array em caso de sucesso e um array vazio se não definido.

# ImagickDraw::getStrokeDashOffset

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeDashOffset — Retorna o deslocamento no padrão de traço para iniciar o traço

### Descrição

public function ImagickDraw::getStrokeDashOffset(): float
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna o deslocamento no padrão de traço para iniciar o traço.

### Valor Retornado

Retorna um float representando o deslocamento ou 0 se não estiver definido.

# ImagickDraw::getStrokeLineCap

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeLineCap — Retorna a forma a ser usada no final dos subcaminhos abertos quando eles são traçados

### Descrição

public function ImagickDraw::getStrokeLineCap(): int
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna a forma a ser usada no final dos subcaminhos abertos quando eles são traçados.

### Valor Retornado

Retorna uma constante LINECAP (`imagick::LINECAP_*`) ou 0 se a forma não estiver definida.

# ImagickDraw::getStrokeLineJoin

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeLineJoin — Retorna a forma a ser usada nos cantos dos caminhos quando eles são traçados

### Descrição

public function ImagickDraw::getStrokeLineJoin(): int
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna a forma a ser usada nos cantos dos caminhos (ou de outras formas vetoriais) quando eles são traçados.

### Valor Retornado

Retorna uma constante LINEJOIN (`imagick::LINEJOIN_*`) ou 0 se a junção da linha do traço não estiver definida.

# ImagickDraw::getStrokeMiterLimit

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeMiterLimit — Retorna o limite de esquadria do traçado

### Descrição

public function ImagickDraw::getStrokeMiterLimit(): int
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna o limite de esquadria. Quando dois segmentos de linha se encontram em um ângulo agudo e as junções de esquadria foram especificadas para 'lineJoin', é possível que a esquadria se estenda muito além da espessura da linha que traça o caminho. O 'miterLimit' impõe um limite na proporção entre o comprimento da esquadria e o 'lineWidth'.

### Valor Retornado

Retorna um inteiro que descreve o limite de esquadria e 0 se nenhum limite estiver definido.

# ImagickDraw::getStrokeOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeOpacity — Retorna a opacidade dos contornos dos objetos traçados

### Descrição

public function ImagickDraw::getStrokeOpacity(): float
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna a opacidade dos contornos dos objetos traçados.

### Valor Retornado

Retorna um float descrevendo a opacidade.

# ImagickDraw::getStrokeWidth

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeWidth — Retorna a largura do traço usado para desenhar contornos de objetos

### Descrição

public function ImagickDraw::getStrokeWidth(): float
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna a largura do traço usado para desenhar contornos de objetos.

### Valor Retornado

Retorna um float que descreve a largura do traço.

# ImagickDraw::getTextAlignment

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextAlignment — Retorna o alinhamento do texto

### Descrição

public function ImagickDraw::getTextAlignment(): int
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna o alinhamento aplicado ao fazer anotações com texto.

### Valor Retornado

Retorna uma constante ALIGN (`imagick::ALIGN_*`) ou 0 se nenhum alinhamento estiver definido.

# ImagickDraw::getTextAntialias

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextAntialias — Retorna a configuração atual de antialias do texto

### Descrição

public function ImagickDraw::getTextAntialias(): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna a configuração atual de suavização de texto, que determina se o texto será suavizado. O texto é suavizado por padrão.

### Valor Retornado

Retorna `true` se o texto for suavizado e `false` se não.

# ImagickDraw::getTextDecoration

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextDecoration — Retorna a decoração do texto

### Descrição

public function ImagickDraw::getTextDecoration(): int
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna a decoração aplicada ao anotar com texto.

### Valor Retornado

Retorna uma constante DECORATION (`imagick::DECORATION_*`) ou 0 se nenhuma decoração estiver definida.

# ImagickDraw::getTextEncoding

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextEncoding — Retorna o conjunto de caracteres usado para anotações de texto

### Descrição

public function ImagickDraw::getTextEncoding(): false|string
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna uma string que especifica o conjunto de caracteres usado para anotações de texto.

### Valor Retornado

Retorna uma string que especifica o conjunto de caracteres ou false se nenhum conjunto estiver definido.

# ImagickDraw::getTextInterlineSpacing

(PECL imagick 3 >= 3.1.0)

ImagickDraw::getTextInterlineSpacing — Obtém o espaçamento entre linhas do texto

### Descrição

public function ImagickDraw::getTextInterlineSpacing(): float

Obtém o espaçamento entre linhas do texto.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# ImagickDraw::getTextInterwordSpacing

(PECL imagick 2 >= 2.3.0, PECL imagick 3 >= 3.1.0)

ImagickDraw::getTextInterwordSpacing — Obtém o espaçamento entre palavras do texto

### Descrição

public function ImagickDraw::getTextInterwordSpacing(): float

Obtém o espaçamento entre palavras do texto.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# ImagickDraw::getTextKerning

(PECL imagick 2 >= 2.3.0, PECL imagick 3 >= 3.1.0)

ImagickDraw::getTextKerning — Obtém o espaçamento entre letras do texto

### Descrição

public function ImagickDraw::getTextKerning(): float

Obtém o espaçamento entre letras do texto.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# ImagickDraw::getTextUnderColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextUnderColor — Retorna a cor sob o texto

### Descrição

public function ImagickDraw::getTextUnderColor(): ImagickPixel
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna a cor do retângulo de fundo colocado sob as anotações de texto.

### Valor Retornado

Retorna um objeto ImagickPixel que descreve a cor.

# ImagickDraw::getVectorGraphics

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getVectorGraphics — Retorna uma string contendo gráficos vetoriais

### Descrição

public function ImagickDraw::getVectorGraphics(): string
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna uma string que especifica os gráficos vetoriais gerados por quaisquer chamadas gráficas feitas desde que o objeto ImagickDraw foi instanciado.

### Valor Retornado

Retorna uma string contendo os gráficos vetoriais.

# ImagickDraw::line

(PECL imagick 2, PECL imagick 3)

ImagickDraw::line — Desenha uma linha

### Descrição

public function ImagickDraw::line(
float `$start_x`,
float `$start_y`,
float `$end_x`,
float `$end_y`
): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desenha uma linha na imagem usando a cor, a opacidade e a largura do traço atuais.

### Parâmetros

`start_x`

  Coordenada x de início

`start_y`

  Coordenada y de início

`end_x`

  Coordenada x final

`end_y`

  Coordenada y final

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::line()

    <?php
    function line($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);

        $draw->line(125, 70, 100, 50);
        $draw->line(350, 170, 100, 150);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::matte

(PECL imagick 2, PECL imagick 3)

ImagickDraw::matte — Pinta no canal de opacidade da imagem

### Descrição

public function ImagickDraw::matte(float `$x`, float `$y`, int `$paint`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Pinta no canal de opacidade da imagem para definir os pixels afetados como transparentes, para influenciar a opacidade dos pixels.

### Parâmetros

`x`

  Coordenada x da pintura

`y`

  Coordenada y da pintura

`paint`

  Uma das constantes PAINT (`imagick::PAINT_*`).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::matte()

    <?php
    function matte($strokeColor, $fillColor, $backgroundColor, $paintType) {
        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);

        $draw->matte(120, 120, $paintType);
        $draw->rectangle(100, 100, 300, 200);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::pathClose

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathClose — Adiciona um elemento de caminho ao caminho atual

### Descrição

public function ImagickDraw::pathClose(): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Adiciona um elemento de caminho ao caminho atual que fecha o subcaminho atual desenhando uma linha reta do ponto atual até o ponto inicial mais recente do subcaminho atual (geralmente, o ponto 'moveto' mais recente).

### Valor Retornado

Nenhum valor é retornado.

# ImagickDraw::pathCurveToAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToAbsolute — Desenha uma curva cúbica de Bézier

### Descrição

public function ImagickDraw::pathCurveToAbsolute(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desenha uma curva de Bézier cúbica do ponto atual até (x,y) usando (x1,y1) como ponto de controle no início da curva e (x2,y2) como ponto de controle no final da curva usando coordenadas absolutas. No final do comando, o novo ponto atual se torna o par de coordenadas final (x,y) usado no polibézier.

### Parâmetros

`x1`

  coordenada x do primeiro ponto de controle

`y1`

  coordenada y do primeiro ponto de controle

`x2`

  coordenada x do segundo ponto de controle

`y2`

  coordenada y do segundo ponto de controle

`x`

  coordenada x do final da curva

`y`

  coordenada y do final da curva

### Valor Retornado

Nenhum valor é retornado.

# ImagickDraw::pathCurveToQuadraticBezierAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierAbsolute — Desenha uma curva quadrática de Bézier

### Descrição

public function ImagickDraw::pathCurveToQuadraticBezierAbsolute(
float `$x1`,
float `$y1`,
float `$x_end`,
float `$y`
): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desenha uma curva Bézier quadrática do ponto atual até (x,y) usando (x1,y1) como ponto de controle usando coordenadas absolutas. No final do comando, o novo ponto atual se torna o par de coordenadas final (x,y) usado no polibézier.

### Parâmetros

`x1`

  coordenada x do ponto de controle

`y1`

  coordenada y do ponto de controle

`x_end`

  coordenada x do ponto final

`y`

  coordenada y do ponto final

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::pathCurveToQuadraticBezierAbsolute()

    <?php
    function pathCurveToQuadraticBezierAbsolute($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);

        $draw->pathStart();
        $draw->pathMoveToAbsolute(50,250);

        // Isso especifica uma curva Bézier quadrática com a posição atual como ponto
        // inicial, o ponto de controle são os dois primeiros parâmetros e o ponto final são os dois últimos parâmetros.
        $draw->pathCurveToQuadraticBezierAbsolute(
            150,50,
            250,250
        );

        // Isso especifica uma curva Bézier quadrática com a posição atual como ponto
        // inicial, o ponto de controle é espelhado do ponto de controle da curva anterior
        // e o ponto final é definido pelos valores x, y.
        $draw->pathCurveToQuadraticBezierSmoothAbsolute(
            450,250
        );

        // Isso especifica uma curva Bézier quadrática com a posição atual como ponto
        // inicial, o ponto de controle é espelhado do ponto de controle da curva anterior
        // e o ponto final é definido em relação à posição atual pelos valores x, y.
        $draw->pathCurveToQuadraticBezierSmoothRelative(
            200,-100
        );

        $draw->pathFinish();

        $imagick = new \Imagick();
        $imagick->newImage(700, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();

    }

    ?>

# ImagickDraw::pathCurveToQuadraticBezierRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierRelative — Desenha uma curva quadrática de Bézier

### Descrição

public function ImagickDraw::pathCurveToQuadraticBezierRelative(
float `$x1`,
float `$y1`,
float `$x_end`,
float `$y`
): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desenha uma curva Bézier quadrática do ponto atual até (x,y) usando (x1,y1) como ponto de controle usando coordenadas relativas. No final do comando, o novo ponto atual se torna o par de coordenadas final (x,y) usado no polibézier.

### Parâmetros

`x1`

  coordenada x inicial

`y1`

  coordenada y inicial

`x_end`

  coordenada x final

`y`

  coordenada y final

### Valor Retornado

Nenhum valor é retornado.

# ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute — Desenha uma curva quadrática de Bézier

### Descrição

public function ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute(float `$x`, float `$y`): bool

Desenha uma curva quadrática de Bézier (usando coordenadas absolutas) do ponto atual até (x,y). O ponto de controle é considerado o reflexo do ponto de controle no comando anterior em relação ao ponto atual. (Se não houver nenhum comando anterior ou se o comando anterior não for DrawPathCurveToQuadraticBezierAbsolute, DrawPathCurveToQuadraticBezierRelative, DrawPathCurveToQuadraticBezierSmoothAbsolut ou DrawPathCurveToQuadraticBezierSmoothRelative, assume que o ponto de controle é coincidente com o ponto atual.). No final do comando, o novo ponto atual se torna o par de coordenadas final (x,y) usado no polibézier.

Esta função não pode ser usada para continuar suavemente uma curva de Bézier cúbica. Só pode continuar suavemente a partir de uma curva quadrática.

### Parâmetros

`x`

  coordenada x final

`y`

  coordenada y final

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute()

    <?php
    $draw = new \ImagickDraw();

    $draw->setStrokeOpacity(1);
    $draw->setStrokeColor("black");
    $draw->setFillColor("blue");

    $draw->setStrokeWidth(2);
    $draw->setFontSize(72);

    $draw->pathStart();
    $draw->pathMoveToAbsolute(50,250);

    // Isso especifica uma curva Bézier quadrática com a posição atual como ponto
    // inicial, o ponto de controle são os dois primeiros parâmetros e o ponto final são os dois últimos parâmetros.
    $draw->pathCurveToQuadraticBezierAbsolute(
        150,50,
        250,250
    );

    // Isso especifica uma curva Bézier quadrática com a posição atual como ponto
    // inicial, o ponto de controle é espelhado do ponto de controle da curva anterior
    // e o ponto final é definido pelos valores x, y.
    $draw->pathCurveToQuadraticBezierSmoothAbsolute(
        450,250
    );

    // Isso especifica uma curva Bézier quadrática com a posição atual como ponto
    // inicial, o ponto de controle é espelhado do ponto de controle da curva anterior
    // e o ponto final é definido em relação à posição atual pelos valores x, y.
    $draw->pathCurveToQuadraticBezierSmoothRelative(
        200,-100
    );

    $draw->pathFinish();

    $imagick = new \Imagick();
    $imagick->newImage(700, 500, $backgroundColor);
    $imagick->setImageFormat("png");

    $imagick->drawImage($draw);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
    ?>

# ImagickDraw::pathCurveToQuadraticBezierSmoothRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierSmoothRelative — Desenha uma curva quadrática de Bézier

### Descrição

public function ImagickDraw::pathCurveToQuadraticBezierSmoothRelative(float `$x`, float `$y`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desenha uma curva quadrática de Bézier (usando coordenadas relativas) do ponto atual até (x,y). O ponto de controle é considerado o reflexo do ponto de controle no comando anterior em relação ao ponto atual. (Se não houver nenhum comando anterior ou se o comando anterior não for DrawPathCurveToQuadraticBezierAbsolute, DrawPathCurveToQuadraticBezierRelative, DrawPathCurveToQuadraticBezierSmoothAbsolut ou DrawPathCurveToQuadraticBezierSmoothRelative, assume que o ponto de controle é coincidente com o ponto atual.). No final do comando, o novo ponto atual se torna o par de coordenadas final (x,y) usado no polibézier.

Esta função não pode ser usada para continuar suavemente uma curva de Bézier cúbica. Só pode continuar suavemente a partir de uma curva quadrática.

### Parâmetros

`x`

  coordenada x final

`y`

  coordenada y final

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::pathCurveToQuadraticBezierSmoothRelative()

    <?php
    $draw = new \ImagickDraw();

    $draw->setStrokeOpacity(1);
    $draw->setStrokeColor("black");
    $draw->setFillColor("blue");

    $draw->setStrokeWidth(2);
    $draw->setFontSize(72);

    $draw->pathStart();
    $draw->pathMoveToAbsolute(50,250);

    // Isso especifica uma curva Bézier quadrática com a posição atual como ponto
    // inicial, o ponto de controle são os dois primeiros parâmetros e o ponto final são os dois últimos parâmetros.
    $draw->pathCurveToQuadraticBezierAbsolute(
        150,50,
        250,250
    );

    // Isso especifica uma curva Bézier quadrática com a posição atual como ponto
    // inicial, o ponto de controle é espelhado do ponto de controle da curva anterior
    // e o ponto final é definido pelos valores x, y.
    $draw->pathCurveToQuadraticBezierSmoothAbsolute(
        450,250
    );

    // Isso especifica uma curva Bézier quadrática com a posição atual como ponto
    // inicial, o ponto de controle é espelhado do ponto de controle da curva anterior
    // e o ponto final é definido em relação à posição atual pelos valores x, y.
    $draw->pathCurveToQuadraticBezierSmoothRelative(
        200,-100
    );

    $draw->pathFinish();

    $imagick = new \Imagick();
    $imagick->newImage(700, 500, $backgroundColor);
    $imagick->setImageFormat("png");

    $imagick->drawImage($draw);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
    ?>

# ImagickDraw::pathCurveToRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToRelative — Desenha uma curva cúbica de Bézier

### Descrição

public function ImagickDraw::pathCurveToRelative(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desenha uma curva de Bézier cúbica do ponto atual até (x,y) usando (x1,y1) como ponto de controle no início da curva e (x2,y2) como ponto de controle no final da curva usando coordenadas relativas. No final do comando, o novo ponto atual se torna o par de coordenadas final (x,y) usado no polibézier.

### Parâmetros

`x1`

  coordenada x do ponto de controle inicial

`y1`

  coordenada y do ponto de controle inicial

`x2`

  coordenada x do ponto de controle final

`y2`

  coordenada y do ponto de controle final

`x`

  coordenada x final

`y`

  coordenada y final

### Valor Retornado

Nenhum valor é retornado.

# ImagickDraw::pathCurveToSmoothAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToSmoothAbsolute — Desenha uma curva cúbica de Bézier

### Descrição

public function ImagickDraw::pathCurveToSmoothAbsolute(
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desenha uma curva de Bézier cúbica do ponto atual até (x,y) usando coordenadas absolutas. Assume-se que o primeiro ponto de controle seja o reflexo do segundo ponto de controle no comando anterior em relação ao ponto atual. (Se não houver nenhum comando anterior ou se o comando anterior não for DrawPathCurveToAbsolute, DrawPathCurveToRelative, DrawPathCurveToSmoothAbsolute ou DrawPathCurveToSmoothRelative, assume que o primeiro ponto de controle é coincidente com o ponto atual.) (x2,y2) é o segundo ponto de controle (ou seja, o ponto de controle no final da curva). No final do comando, o novo ponto atual se torna o par de coordenadas final (x,y) usado no polibézier.

### Parâmetros

`x2`

  coordenada x do segundo ponto de controle

`y2`

  coordenada y do segundo ponto de controle

`x`

  coordenada x do ponto final

`y`

  coordenada y do ponto final

### Valor Retornado

Nenhum valor é retornado.

# ImagickDraw::pathCurveToSmoothRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToSmoothRelative — Desenha uma curva cúbica de Bézier

### Descrição

public function ImagickDraw::pathCurveToSmoothRelative(
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desenha uma curva de Bézier cúbica do ponto atual até (x,y) usando coordenadas relativas. Assume-se que o primeiro ponto de controle seja o reflexo do segundo ponto de controle no comando anterior em relação ao ponto atual. (Se não houver nenhum comando anterior ou se o comando anterior não for DrawPathCurveToAbsolute, DrawPathCurveToRelative, DrawPathCurveToSmoothAbsolute ou DrawPathCurveToSmoothRelative, assume que o primeiro ponto de controle é coincidente com o ponto atual.) (x2,y2) é o segundo ponto de controle (ou seja, o ponto de controle no final da curva). No final do comando, o novo ponto atual se torna o par de coordenadas final (x,y) usado no polibézier.

### Parâmetros

`x2`

  coordenada x do segundo ponto de controle

`y2`

  coordenada y do segundo ponto de controle

`x`

  coordenada x do ponto final

`y`

  coordenada y do ponto final

### Valor Retornado

Nenhum valor é retornado.

# ImagickDraw::pathEllipticArcAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathEllipticArcAbsolute — Desenha um arco elíptico

### Descrição

public function ImagickDraw::pathEllipticArcAbsolute(
float `$rx`,
float `$ry`,
float `$x_axis_rotation`,
bool `$large_arc`,
bool `$sweep`,
float `$x`,
float `$y`
): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desenha um arco elíptico do ponto atual até (x, y) usando coordenadas absolutas. O tamanho e a orientação da elipse são definidos por dois raios (rx, ry) e um xAxisRotation, que indica como a elipse como um todo é rotacionada em relação ao sistema de coordenadas atual. O centro (cx, cy) da elipse é calculado automaticamente para satisfazer as restrições impostas pelos outros parâmetros. largeArcFlag e sweepFlag contribuem para os cálculos automáticos e ajudam a determinar como o arco é desenhado. Se `large_arc` for `true`, o maior dos arcos disponíveis será desenhado. Se `sweep` for true, o arco correspondente a uma rotação no sentido horário será desenhado.

### Parâmetros

`rx`

  raio x

`ry`

  raio y

`x_axis_rotation`

  rotação do eixo x

`large_arc`

  opção de arco grande

`sweep`

  opção de varredura

`x`

  coordenada x

`y`

  coordenada y

### Valor Retornado

Nenhum valor é retornado.

# ImagickDraw::pathEllipticArcRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathEllipticArcRelative — Desenha um arco elíptico

### Descrição

public function ImagickDraw::pathEllipticArcRelative(
float `$rx`,
float `$ry`,
float `$x_axis_rotation`,
bool `$large_arc`,
bool `$sweep`,
float `$x`,
float `$y`
): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desenha um arco elíptico do ponto atual até (x, y) usando coordenadas relativas. O tamanho e a orientação da elipse são definidos por dois raios (rx, ry) e um xAxisRotation, que indica como a elipse como um todo é rotacionada em relação ao sistema de coordenadas atual. O centro (cx, cy) da elipse é calculado automaticamente para satisfazer as restrições impostas pelos outros parâmetros. largeArcFlag e sweepFlag contribuem para os cálculos automáticos e ajudam a determinar como o arco é desenhado. Se `large_arc` for `true`, o maior dos arcos disponíveis será desenhado. Se `sweep` for true, o arco correspondente a uma rotação no sentido horário será desenhado.

### Parâmetros

`rx`

  raio x

`ry`

  raio y

`x_axis_rotation`

  rotação do eixo x

`large_arc`

  opção de arco grande

`sweep`

  opção de varredura

`x`

  coordenada x

`y`

  coordenada y

### Valor Retornado

Nenhum valor é retornado.

# ImagickDraw::pathFinish

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathFinish — Termina o caminho atual

### Descrição

public function ImagickDraw::pathFinish(): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Termina o caminho atual.

### Valor Retornado

Nenhum valor é retornado.

# ImagickDraw::pathLineToAbsolute

(PECL imagick 2)

ImagickDraw::pathLineToAbsolute — Desenha um caminho de linha

### Descrição

public function ImagickDraw::pathLineToAbsolute(float `$x`, float `$y`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desenha um caminho de linha do ponto atual até a coordenada fornecida usando coordenadas absolutas. A coordenada então se torna o novo ponto atual.

### Parâmetros

`x`

  coordenada x inicial

`y`

  coordenada x final

### Valor Retornado

Nenhum valor é retornado.

# ImagickDraw::pathLineToHorizontalAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToHorizontalAbsolute — Desenha um caminho de linha horizontal

### Descrição

public function ImagickDraw::pathLineToHorizontalAbsolute(float `$x`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desenha um caminho de linha horizontal do ponto atual até o ponto de destino usando coordenadas absolutas. O ponto alvo então se torna o novo ponto atual.

### Parâmetros

`x`

  coordenada x

### Valor Retornado

Nenhum valor é retornado.

# ImagickDraw::pathLineToHorizontalRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToHorizontalRelative — Desenha um caminho de linha horizontal

### Descrição

public function ImagickDraw::pathLineToHorizontalRelative(float `$x`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desenha um caminho de linha horizontal do ponto atual até o ponto de destino usando coordenadas relativas. O ponto alvo então se torna o novo ponto atual.

### Parâmetros

`x`

  coordenada x

### Valor Retornado

Nenhum valor é retornado.

# ImagickDraw::pathLineToRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToRelative — Desenha um caminho de linha

### Descrição

public function ImagickDraw::pathLineToRelative(float `$x`, float `$y`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desenha um caminho de linha do ponto atual até a coordenada fornecida usando coordenadas relativas. A coordenada então se torna o novo ponto atual.

### Parâmetros

`x`

  coordenada x inicial

`y`

  coordenada y inicial

### Valor Retornado

Nenhum valor é retornado.

# ImagickDraw::pathLineToVerticalAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToVerticalAbsolute — Desenha um caminho de linha vertical

### Descrição

public function ImagickDraw::pathLineToVerticalAbsolute(float `$y`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desenha um caminho de linha vertical do ponto atual até o ponto alvo usando coordenadas absolutas. O ponto alvo então se torna o novo ponto atual.

### Parâmetros

`y`

  coordenada y

### Valor Retornado

Nenhum valor é retornado.

# ImagickDraw::pathLineToVerticalRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToVerticalRelative — Desenha um caminho de linha vertical

### Descrição

public function ImagickDraw::pathLineToVerticalRelative(float `$y`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desenha um caminho de linha vertical do ponto atual até o ponto alvo usando coordenadas relativas. O ponto alvo então se torna o novo ponto atual.

### Parâmetros

`y`

  coordenada y

### Valor Retornado

Nenhum valor é retornado.

# ImagickDraw::pathMoveToAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathMoveToAbsolute — Inicia um novo subcaminho

### Descrição

public function ImagickDraw::pathMoveToAbsolute(float `$x`, float `$y`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Inicia um novo subcaminho na coordenada fornecida usando coordenadas absolutas. O ponto atual torna-se então a coordenada especificada.

### Parâmetros

`x`

  coordenada alvo x

`y`

  coordenada alvo y

### Valor Retornado

Nenhum valor é retornado.

# ImagickDraw::pathMoveToRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathMoveToRelative — Inicia um novo subcaminho

### Descrição

public function ImagickDraw::pathMoveToRelative(float `$x`, float `$y`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Inicia um novo subcaminho na coordenada fornecida usando coordenadas relativas. O ponto atual torna-se então a coordenada especificada.

### Parâmetros

`x`

  coordenada alvo x

`y`

  coordenada alvo y

### Valor Retornado

Nenhum valor é retornado.

# ImagickDraw::pathStart

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathStart — Declara o início de uma lista de desenho de caminho

### Descrição

public function ImagickDraw::pathStart(): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Declara o início de uma lista de desenho de caminho que é finalizada por um comando DrawPathFinish() correspondente. Todos os outros comandos DrawPath devem ser colocados entre um comando DrawPathStart() e um comando DrawPathFinish(). Isso ocorre porque os comandos de desenho de caminho são comandos subordinados e não funcionam sozinhos.

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::pathStart()

    <?php
    function pathStart($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);

        $draw->pathStart();
        $draw->pathMoveToAbsolute(50, 50);
        $draw->pathLineToAbsolute(100, 50);
        $draw->pathLineToRelative(0, 50);
        $draw->pathLineToHorizontalRelative(-50);
        $draw->pathFinish();

        $draw->pathStart();
        $draw->pathMoveToAbsolute(50, 50);
        $draw->pathMoveToRelative(300, 0);
        $draw->pathLineToRelative(50, 0);
        $draw->pathLineToVerticalRelative(50);
        $draw->pathLineToHorizontalAbsolute(350);
        $draw->pathclose();
        $draw->pathFinish();

        $draw->pathStart();
        $draw->pathMoveToAbsolute(50, 300);
        $draw->pathCurveToAbsolute(50, 300, 100, 200, 300, 300);
        $draw->pathLineToVerticalAbsolute(350);
        $draw->pathFinish();

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::point

(PECL imagick 2, PECL imagick 3)

ImagickDraw::point — Desenha um ponto

### Descrição

public function ImagickDraw::point(float `$x`, float `$y`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desenha um ponto usando a cor e a espessura atual do traço nas coordenadas especificadas.

### Parâmetros

`x`

  Coordenada x do ponto.

`y`

  Coordenada y do ponto.

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::point()

    <?php
    function point($fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setFillColor($fillColor);

        for ($x = 0; $x < 10000; $x++) {
            $draw->point(rand(0, 500), rand(0, 500));
        }

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::polygon

(PECL imagick 2, PECL imagick 3)

ImagickDraw::polygon — Desenha um polígono

### Descrição

public function ImagickDraw::polygon(array `$coordinates`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desenha um polígono usando o traço atual, a largura do traço e a cor ou textura de preenchimento, usando o array de coordenadas especificado.

### Parâmetros

`coordinates`

  array multi-dimensional como: array( array( 'x' => 3, 'y' => 4 ), array( 'x' => 2, 'y' => 6 ) );

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::polygon()

    <?php
    function polygon($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setStrokeWidth(4);

        $draw->setFillColor($fillColor);

        $points = [
            ['x' => 40 * 5, 'y' => 10 * 5],
            ['x' => 20 * 5, 'y' => 20 * 5],
            ['x' => 70 * 5, 'y' => 50 * 5],
            ['x' => 60 * 5, 'y' => 15 * 5],
        ];

        $draw->polygon($points);

        $image = new \Imagick();
        $image->newImage(500, 300, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::polyline

(PECL imagick 2, PECL imagick 3)

ImagickDraw::polyline — Desenha uma polilinha

### Descrição

public function ImagickDraw::polyline(array `$coordinates`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desenha uma polilinha usando o traço atual, a largura do traço e a cor ou textura de preenchimento, usando o array de coordenadas especificado.

### Parâmetros

`coordinates`

  array de coordenadas x e y: array( array( 'x' => 4, 'y' => 6 ), array( 'x' => 8, 'y' => 10 ) )

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::polyline()

    <?php
    function polyline($strokeColor, $fillColor, $backgroundColor) {
        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(5);

        $points = [
            ['x' => 40 * 5, 'y' => 10 * 5],
            ['x' => 20 * 5, 'y' => 20 * 5],
            ['x' => 70 * 5, 'y' => 50 * 5],
            ['x' => 60 * 5, 'y' => 15 * 5]
        ];

        $draw->polyline($points);

        $image = new \Imagick();
        $image->newImage(500, 300, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::pop

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pop — Destrói o ImagickDraw atual na pilha e retorna ao ImagickDraw enviado anteriormente

### Descrição

public function ImagickDraw::pop(): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Destrói o ImagickDraw atual na pilha e retorna ao ImagickDraw enviado anteriormente. Podem existir vários ImagickDraws. É um erro tentar exibir mais ImagickDraws do que os que foram enviados, e é a forma correta de exibir todos os ImagickDraws que foram enviados.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# ImagickDraw::popClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::popClipPath — Encerra uma definição de caminho de recorte

### Descrição

public function ImagickDraw::popClipPath(): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Encerra uma definição de caminho de recorte.

### Valor Retornado

Nenhum valor é retornado.

# ImagickDraw::popDefs

(PECL imagick 2, PECL imagick 3)

ImagickDraw::popDefs — Encerra uma lista de definições

### Descrição

public function ImagickDraw::popDefs(): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Encerra uma lista de definições.

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::popDefs()

    <?php
    function popDefs($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setstrokeOpacity(1);
        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);
        $draw->pushDefs();
        $draw->setStrokeColor('white');
        $draw->rectangle(50, 50, 200, 200);
        $draw->popDefs();

        $draw->rectangle(300, 50, 450, 200);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::popPattern

(PECL imagick 2, PECL imagick 3)

ImagickDraw::popPattern — Encerra uma definição de padrão

### Descrição

public function ImagickDraw::popPattern(): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Encerra uma definição de padrão.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# ImagickDraw::push

(PECL imagick 2, PECL imagick 3)

ImagickDraw::push — Clona o ImagickDraw atual e o coloca na pilha

### Descrição

public function ImagickDraw::push(): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Clona o ImagickDraw atual para criar um novo ImagickDraw, que é então adicionado à pilha do ImagickDraw. O(s) ImagickDraw(s) do desenho original podem ser retornados invocando ImagickDraw::pop(). Os ImagickDraws são armazenados em uma pilha ImagickDraw. Para cada Pop já deve ter havido um Push equivalente.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::push()

    <?php
    function push($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillModifiedColor);
        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);
        $draw->push();
        $draw->translate(50, 50);
        $draw->rectangle(200, 200, 300, 300);
        $draw->pop();
        $draw->setFillColor($fillColor);
        $draw->rectangle(200, 200, 300, 300);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::pushClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pushClipPath — Inicia uma definição de caminho de recorte

### Descrição

public function ImagickDraw::pushClipPath(string `$clip_mask_id`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Inicia uma definição de caminho de recorte que é composta por qualquer número de comandos de desenho e terminada por um comando ImagickDraw::popClipPath().

### Parâmetros

`clip_mask_id`

  ID da máscara de recorte

### Valor Retornado

Nenhum valor é retornado.

# ImagickDraw::pushDefs

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pushDefs — Indica que os comandos a seguir criam elementos nomeados para processamento antecipado

### Descrição

public function ImagickDraw::pushDefs(): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Indica que comandos até um comando de terminação ImagickDraw::popDefs() criam elementos nomeados (por exemplo, caminhos de recorte, texturas, etc.) que podem ser processados ​​com segurança mais cedo por uma questão de eficiência.

### Valor Retornado

Nenhum valor é retornado.

# ImagickDraw::pushPattern

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pushPattern — Indica que os comandos subsequentes até um comando ImagickDraw::opPattern() compreendem a definição de um padrão nomeado

### Descrição

public function ImagickDraw::pushPattern(
string `$pattern_id`,
float `$x`,
float `$y`,
float `$width`,
float `$height`
): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Indica que os comandos subsequentes até um comando DrawPopPattern() compreendem a definição de um padrão nomeado. O espaço do padrão recebe coordenadas do canto superior esquerdo, largura e altura, e se torna seu próprio espaço de desenho. Qualquer coisa que possa ser desenhada pode ser usada na definição de um padrão. Padrões nomeados podem ser usados ​​como definições de traçado ou pincel.

### Parâmetros

`pattern_id`

  O Id do padrão

`x`

  coordenada x do canto superior esquerdo

`y`

  coordenada y do canto superior esquerdo

`width`

  largura do padrão

`height`

  altura do padrão

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::pushPattern()

    <?php
    function pushPattern($strokeColor, $fillColor, $backgroundColor) {
        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(1);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(1);

        $draw->pushPattern("MyFirstPattern", 0, 0, 50, 50);
        for ($x = 0; $x < 50; $x += 10) {
            for ($y = 0; $y < 50; $y += 5) {
                $positionX = $x + (($y / 5) % 5);
                $draw->rectangle($positionX, $y, $positionX + 5, $y + 5);
            }
        }
        $draw->popPattern();

        $draw->setFillOpacity(0);
        $draw->rectangle(100, 100, 400, 400);
        $draw->setFillOpacity(1);

        $draw->setFillOpacity(1);

        $draw->push();
        $draw->setFillPatternURL('#MyFirstPattern');
        $draw->setFillColor('yellow');
        $draw->rectangle(100, 100, 400, 400);
        $draw->pop();

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::rectangle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::rectangle — Desenha um retângulo

### Descrição

public function ImagickDraw::rectangle(
float `$top_left_x`,
float `$top_left_y`,
float `$bottom_right_x`,
float `$bottom_right_y`
): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desenha um retângulo com duas coordenadas e usando as configurações atuais de traçado, largura do traçado e preenchimento.

### Parâmetros

`top_left_x`

  coordenada x do canto superior esquerdo

`top_left_y`

  coordenada y do canto superior esquerdo

`bottom_right_x`

  coordenada x do canto inferior direito

`bottom_right_y`

  coordenada y do canto inferior direito

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::rectangle()

    <?php
    function rectangle($strokeColor, $fillColor, $backgroundColor) {
        $draw = new \ImagickDraw();
        $strokeColor = new \ImagickPixel($strokeColor);
        $fillColor = new \ImagickPixel($fillColor);

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(2);

        $draw->rectangle(200, 200, 300, 300);
        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::render

(PECL imagick 2, PECL imagick 3)

ImagickDraw::render — Renderiza todos os comandos de desenho anteriores na imagem

### Descrição

public function ImagickDraw::render(): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Renderiza todos os comandos de desenho anteriores na imagem.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# ImagickDraw::resetVectorGraphics

(PECL imagick 2, PECL imagick 3)

ImagickDraw::resetVectorGraphics — Redefine os gráficos vetoriais

### Descrição

public function ImagickDraw::resetVectorGraphics(): bool

Redefine os gráficos vetoriais.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna `true` em caso de sucesso.

# ImagickDraw::rotate

(PECL imagick 2, PECL imagick 3)

ImagickDraw::rotate — Aplica a rotação especificada ao espaço de coordenadas atual

### Descrição

public function ImagickDraw::rotate(float `$degrees`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Aplica a rotação especificada ao espaço de coordenadas atual.

### Parâmetros

`degrees`

  graus para rotação

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::rotate()

    <?php
    function rotate($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor) {
        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setStrokeOpacity(1);
        $draw->setFillColor($fillColor);
        $draw->rectangle(200, 200, 300, 300);
        $draw->setFillColor($fillModifiedColor);
        $draw->rotate(15);
        $draw->rectangle(200, 200, 300, 300);

        $image = new \Imagick();
        $image->newImage(500, 500, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::roundRectangle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::roundRectangle — Desenha um retângulo arredondado

### Descrição

public function ImagickDraw::roundRectangle(
float `$top_left_x`,
float `$top_left_y`,
float `$bottom_right_x`,
float `$bottom_right_y`,
float `$rounding_x`,
float `$rounding_y`
): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desenha um retângulo arredondado com duas coordenadas, raios de canto x e y e usando o traço atual, largura do traço e configurações de preenchimento.

### Parâmetros

`top_left_x`

  coordenada x do canto superior esquerdo

`top_left_y`

  coordenada y do canto superior esquerdo

`bottom_right_x`

  coordenada x do canto inferior direito

`bottom_right_y`

  coordenada y do canto inferior direito

`rounding_x`

  raio x de arredondamento

`rounding_y`

  raio y de arredondamento

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::roundRectangle()

    <?php
    function roundRectangle($strokeColor, $fillColor, $backgroundColor, $startX, $startY, $endX, $endY, $roundX, $roundY) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(2);

        $draw->roundRectangle($startX, $startY, $endX, $endY, $roundX, $roundY);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::scale

(PECL imagick 2, PECL imagick 3)

ImagickDraw::scale — Ajusta o fator de escala

### Descrição

public function ImagickDraw::scale(float `$x`, float `$y`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Ajusta o fator de escala para aplicar nas direções horizontal e vertical ao espaço de coordenadas atual.

### Parâmetros

`x`

  fator horizontal

`y`

  fator vertical

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::scale()

    <?php
    function scale($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setStrokeWidth(4);
        $draw->setFillColor($fillColor);
        $draw->rectangle(200, 200, 300, 300);
        $draw->setFillColor($fillModifiedColor);
        $draw->scale(1.4, 1.4);
        $draw->rectangle(200, 200, 300, 300);

        $image = new \Imagick();
        $image->newImage(500, 500, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setClipPath — Associa um caminho de recorte nomeado à imagem

### Descrição

public function ImagickDraw::setClipPath(string `$clip_mask`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Associa um caminho de recorte nomeado à imagem. Somente as áreas desenhadas pelo traçado de recorte serão modificadas enquanto ele permanecer em vigor.

### Parâmetros

`clip_mask`

  o nome do caminho de recorte

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setClipPath()

    <?php
    function setClipPath($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(2);

        $clipPathName = 'testClipPath';

        $draw->pushClipPath($clipPathName);
        $draw->rectangle(0, 0, 250, 250);
        $draw->popClipPath();
        $draw->setClipPath($clipPathName);
        $draw->rectangle(100, 100, 400, 400);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setClipRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setClipRule — Define a regra de preenchimento do polígono a ser usada pelo traçado de recorte

### Descrição

public function ImagickDraw::setClipRule(int `$fillrule`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Define a regra de preenchimento do polígono a ser usada pelo traçado de recorte.

### Parâmetros

`fillrule`

  Uma das constantes FILLRULE (`imagick::FILLRULE_*`).

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setClipRule()

    <?php
    function setClipRule($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(2);
        //\Imagick::FILLRULE_EVENODD
        //\Imagick::FILLRULE_NONZERO

        $clipPathName = 'testClipPath';
        $draw->pushClipPath($clipPathName);
        $draw->setClipRule(\Imagick::FILLRULE_EVENODD);
        $draw->rectangle(0, 0, 300, 500);
        $draw->rectangle(200, 0, 500, 500);
        $draw->popClipPath();
        $draw->setClipPath($clipPathName);
        $draw->rectangle(200, 200, 300, 300);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setClipUnits

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setClipUnits — Define a interpretação das unidades do caminho de recorte

### Descrição

public function ImagickDraw::setClipUnits(int `$pathunits`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Define a interpretação das unidades do caminho de recorte.

### Parâmetros

`pathunits`

  o número de unidades de recorte

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setClipUnits()

    <?php
    function setClipUnits($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(2);
        $clipPathName = 'testClipPath';
        $draw->setClipUnits(\Imagick::RESOLUTION_PIXELSPERINCH);
        $draw->pushClipPath($clipPathName);
        $draw->rectangle(0, 0, 250, 250);
        $draw->popClipPath();
        $draw->setClipPath($clipPathName);

        //RESOLUTION_PIXELSPERINCH
        //RESOLUTION_PIXELSPERCENTIMETER

        $draw->rectangle(200, 200, 300, 300);
        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFillAlpha

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillAlpha — Define a opacidade a ser usada ao desenhar usando a cor ou textura de preenchimento

### Descrição

public function ImagickDraw::setFillAlpha(float `$alpha`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Define a opacidade a ser usada ao desenhar usando a cor ou textura de preenchimento. Totalmente opaco é 1.0.

### Parâmetros

`alpha`

  alfa de preenchimento

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setFillAlpha()

    <?php
    function setFillAlpha($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(2);
        $draw->rectangle(100, 200, 200, 300);
        @$draw->setFillAlpha(0.4);
        $draw->rectangle(300, 200, 400, 300);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFillColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillColor — Define a cor de preenchimento a ser usada para desenhar objetos preenchidos

### Descrição

public function ImagickDraw::setFillColor(ImagickPixel|string `$fill_color`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Define a cor de preenchimento a ser usada para desenhar objetos preenchidos.

### Parâmetros

`fill_color`

  ImagickPixel a ser usado para definir a cor

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setFillColor()

    <?php
    function setFillColor($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(1.5);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->rectangle(50, 50, 150, 150);

        $draw->setFillColor("rgb(200, 32, 32)");
        $draw->rectangle(200, 50, 300, 150);

        $image = new \Imagick();
        $image->newImage(500, 500, $backgroundColor);
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setFillOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillOpacity — Define a opacidade a ser usada ao desenhar usando a cor ou textura de preenchimento

### Descrição

public function ImagickDraw::setFillOpacity(float `$opacity`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Define a opacidade a ser usada ao desenhar usando a cor ou textura de preenchimento. Totalmente opaco é 1.0.

### Parâmetros

`opacity`

  a opacidade de preenchimento

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setFillOpacity()

    <?php
    function setFillOpacity($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(2);

        $draw->rectangle(100, 200, 200, 300);

        $draw->setFillOpacity(0.4);
        $draw->rectangle(300, 200, 400, 300);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFillPatternURL

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillPatternURL — Define a URL a ser usada como padrão de preenchimento para preencher objetos

### Descrição

public function ImagickDraw::setFillPatternURL(string `$fill_url`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Define a URL a ser usada como padrão de preenchimento para preencher objetos. Somente URLs locais ("#identifier") são suportados no momento. Esses URLs locais normalmente são criados definindo um padrão de preenchimento nomeado com DrawPushPattern/DrawPopPattern.

### Parâmetros

`fill_url`

  URL a ser usada para obter o padrão de preenchimento.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# ImagickDraw::setFillRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillRule — Define a regra de preenchimento a ser usada ao desenhar polígonos

### Descrição

public function ImagickDraw::setFillRule(int `$fillrule`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Define a regra de preenchimento a ser usada ao desenhar polígonos.

### Parâmetros

`fillrule`

  Uma das constantes FILLRULE (`imagick::FILLRULE_*`).

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setFillRule()

    <?php
    function setFillRule($fillColor, $strokeColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeWidth(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $fillRules = [\Imagick::FILLRULE_NONZERO, \Imagick::FILLRULE_EVENODD];

        $points = 11;
        $size = 150;

        $draw->translate(175, 160);

        for ($x = 0; $x < 2; $x++) {
            $draw->setFillRule($fillRules[$x]);
            $draw->pathStart();
            for ($n = 0; $n < $points * 2; $n++) {

                if ($n >= $points) {
                    $angle = fmod($n * 360 * 4 / $points, 360) * pi() / 180;
                }
                else {
                    $angle = fmod($n * 360 * 3 / $points, 360) * pi() / 180;
                }

                $positionX = $size * sin($angle);
                $positionY = $size * cos($angle);

                if ($n == 0) {
                    $draw->pathMoveToAbsolute($positionX, $positionY);
                }
                else {
                    $draw->pathLineToAbsolute($positionX, $positionY);
                }
            }

            $draw->pathClose();
            $draw->pathFinish();

            $draw->translate(325, 0);
        }

        $image = new \Imagick();
        $image->newImage(700, 320, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setFont

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFont — Define a fonte totalmente especificada a ser usada ao fazer anotações com texto

### Descrição

public function ImagickDraw::setFont(string `$font_name`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Define a fonte totalmente especificada a ser usada ao fazer anotações com texto.

### Parâmetros

`font_name`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setFont()

    <?php
    function setFont($fillColor, $strokeColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);
        $draw->setFontSize(36);

        $draw->setFont("../fonts/Arial.ttf");
        $draw->annotation(50, 50, "Lorem Ipsum!");

        $draw->setFont("../fonts/Consolas.ttf");
        $draw->annotation(50, 100, "Lorem Ipsum!");

        $draw->setFont("../fonts/CANDY.TTF");
        $draw->annotation(50, 150, "Lorem Ipsum!");

        $draw->setFont("../fonts/Inconsolata-dz.otf");
        $draw->annotation(50, 200, "Lorem Ipsum!");

        $imagick = new \Imagick();
        $imagick->newImage(500, 300, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFontFamily

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontFamily — Define a família de fontes a ser usada ao fazer anotações com texto

### Descrição

public function ImagickDraw::setFontFamily(string `$font_family`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Define a família de fontes a ser usada ao fazer anotações com texto.

### Parâmetros

`font_family`

  a família de fontes

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setFontFamily()

    <?php
    function setFontFamily($fillColor, $strokeColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $strokeColor = new \ImagickPixel($strokeColor);
        $fillColor = new \ImagickPixel($fillColor);

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);

        $draw->setFontSize(48);

        $draw->setFontFamily("Times");
        $draw->annotation(50, 50, "Lorem Ipsum!");

        $draw->setFontFamily("AvantGarde");
        $draw->annotation(50, 100, "Lorem Ipsum!");

        $draw->setFontFamily("NewCenturySchlbk");
        $draw->annotation(50, 150, "Lorem Ipsum!");

        $draw->setFontFamily("Palatino");
        $draw->annotation(50, 200, "Lorem Ipsum!");

        $imagick = new \Imagick();
        $imagick->newImage(450, 250, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFontSize

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontSize — Define o tamanho da fonte a ser usado ao fazer anotações com texto

### Descrição

public function ImagickDraw::setFontSize(float `$point_size`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Define o tamanho da fonte a ser usado ao fazer anotações com texto.

### Parâmetros

`point_size`

  o tamanho da fonte em pontos

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setFontSize()

    <?php
    function setFontSize($fillColor, $strokeColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(2);
        $draw->setFont("../fonts/Arial.ttf");

        $sizes = [24, 36, 48, 60, 72];

        foreach ($sizes as $size) {
            $draw->setFontSize($size);
            $draw->annotation(50, ($size * $size / 16), "Lorem Ipsum!");
        }

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFontStretch

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontStretch — Define o esticamento da fonte a ser usado ao fazer anotações com texto

### Descrição

public function ImagickDraw::setFontStretch(int `$stretch`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Define o esticamento da fonte a ser usado ao fazer anotações com texto. A enumeração AnyStretch atua como uma opção curinga "qualquer valor".

### Parâmetros

`stretch`

  Uma das constantes STRETCH (`imagick::STRETCH_*`).

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setFontStretch()

    <?php
    function setFontStretch($fillColor, $strokeColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(2);
        $draw->setFontSize(36);

        $fontStretchTypes = [
            \Imagick::STRETCH_ULTRACONDENSED,
            \Imagick::STRETCH_CONDENSED,
            \Imagick::STRETCH_SEMICONDENSED,
            \Imagick::STRETCH_SEMIEXPANDED,
            \Imagick::STRETCH_EXPANDED,
            \Imagick::STRETCH_EXTRAEXPANDED,
            \Imagick::STRETCH_ULTRAEXPANDED,
            \Imagick::STRETCH_ANY
        ];

        $offset = 0;
        foreach ($fontStretchTypes as $fontStretch) {
            $draw->setFontStretch($fontStretch);
            $draw->annotation(50, 75 + $offset, "Lorem Ipsum!");
            $offset += 50;
        }

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFontStyle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontStyle — Define o estilo da fonte a ser usado ao fazer anotações com texto

### Descrição

public function ImagickDraw::setFontStyle(int `$style`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Define o estilo da fonte a ser usado ao fazer anotações com texto. A enumeração AnyStyle atua como uma opção curinga "qualquer estilo".

### Parâmetros

`style`

  Uma das constantes STYLE (`imagick::STYLE_*`).

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setFontStyle()

    <?php
    function setFontStyle($fillColor, $strokeColor, $backgroundColor) {
        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(1);
        $draw->setFontSize(36);
        $draw->setFontStyle(\Imagick::STYLE_NORMAL);
        $draw->annotation(50, 50, "Lorem Ipsum!");

        $draw->setFontStyle(\Imagick::STYLE_ITALIC);
        $draw->annotation(50, 100, "Lorem Ipsum!");

        $draw->setFontStyle(\Imagick::STYLE_OBLIQUE);
        $draw->annotation(50, 150, "Lorem Ipsum!");

        $imagick = new \Imagick();
        $imagick->newImage(350, 300, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFontWeight

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontWeight — Define a espessura da fonte

### Descrição

public function ImagickDraw::setFontWeight(int `$weight`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Define a espessura da fonte a ser usada ao fazer anotações com texto.

### Parâmetros

`weight`

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setFontWeight()

    <?php
    function setFontWeight($fillColor, $strokeColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(1);

        $draw->setFontSize(36);

        $draw->setFontWeight(100);
        $draw->annotation(50, 50, "Lorem Ipsum!");

        $draw->setFontWeight(200);
        $draw->annotation(50, 100, "Lorem Ipsum!");

        $draw->setFontWeight(400);
        $draw->annotation(50, 150, "Lorem Ipsum!");

        $draw->setFontWeight(800);
        $draw->annotation(50, 200, "Lorem Ipsum!");

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setGravity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setGravity — Define a gravidade do posicionamento do texto

### Descrição

public function ImagickDraw::setGravity(int `$gravity`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Define a gravidade do posicionamento do texto a ser usada ao fazer anotações com texto.

### Parâmetros

`gravity`

  Uma das constantes GRAVITY (`imagick::GRAVITY_*`).

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setGravity()

    <?php
    function setGravity($fillColor, $strokeColor, $backgroundColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(1);
        $draw->setFontSize(24);

        $gravitySettings = array(
            \Imagick::GRAVITY_NORTHWEST => 'NorthWest',
            \Imagick::GRAVITY_NORTH => 'North',
            \Imagick::GRAVITY_NORTHEAST => 'NorthEast',
            \Imagick::GRAVITY_WEST => 'West',
            \Imagick::GRAVITY_CENTER => 'Centre',
            \Imagick::GRAVITY_SOUTHWEST => 'SouthWest',
            \Imagick::GRAVITY_SOUTH => 'South',
            \Imagick::GRAVITY_SOUTHEAST => 'SouthEast',
            \Imagick::GRAVITY_EAST => 'East'
        );

        $draw->setFont("../fonts/Arial.ttf");

        foreach ($gravitySettings as $type => $description) {
            $draw->setGravity($type);
            $draw->annotation(50, 50, '"' . $description . '"');
        }

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setResolution

(PECL imagick 3 >= 3.1.0)

ImagickDraw::setResolution — Define a resolução

### Descrição

public function ImagickDraw::setResolution(float `$resolution_x`, float `$resolution_y`): bool

Define a resolução.

### Parâmetros

`resolution_x`

`resolution_y`

### Valor Retornado

Retorna `true` em caso de sucesso.

# ImagickDraw::setStrokeAlpha

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeAlpha — Especifica a opacidade dos contornos dos objetos traçados

### Descrição

public function ImagickDraw::setStrokeAlpha(float `$alpha`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Especifica a opacidade dos contornos dos objetos traçados.

### Parâmetros

`alpha`

  opacidade

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setStrokeAlpha()

    <?php
    function setStrokeAlpha($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(4);
        $draw->line(100, 100, 400, 145);
        $draw->rectangle(100, 200, 225, 350);
        $draw->setStrokeOpacity(0.1);
        $draw->line(100, 120, 400, 165);
        $draw->rectangle(275, 200, 400, 350);

        $image = new \Imagick();
        $image->newImage(500, 400, $backgroundColor);
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeAntialias

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeAntialias — Controla se os contornos traçados são suavizados

### Descrição

public function ImagickDraw::setStrokeAntialias(bool `$enabled`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Controla se os contornos traçados são suavizados. Os contornos traçados são suavizados por padrão. Quando a suavização está desabilitada, os pixels traçados são analisados para determinar se será usada a cor do traço ou a cor subjacente da tela.

### Parâmetros

`enabled`

  a configuração da suavização

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setStrokeAntialias()

    <?php
    function setStrokeAntialias($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(1);
        $draw->setStrokeAntialias(false);
        $draw->line(100, 100, 400, 105);

        $draw->line(100, 140, 400, 185);

        $draw->setStrokeAntialias(true);
        $draw->line(100, 110, 400, 115);
        $draw->line(100, 150, 400, 195);

        $image = new \Imagick();
        $image->newImage(500, 250, $backgroundColor);
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeColor — Define a cor usada para traçar os contornos dos objetos

### Descrição

public function ImagickDraw::setStrokeColor(ImagickPixel|string `$color`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Define a cor usada para traçar os contornos dos objetos.

### Parâmetros

`color`

  a cor do traço

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setStrokeColor()

    <?php
    function setStrokeColor($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(5);

        $draw->line(100, 100, 400, 145);
        $draw->rectangle(100, 200, 225, 350);

        $draw->setStrokeOpacity(0.1);
        $draw->line(100, 120, 400, 165);
        $draw->rectangle(275, 200, 400, 350);

        $image = new \Imagick();
        $image->newImage(500, 400, $backgroundColor);
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeDashArray

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeDashArray — Especifica o padrão de traços e espaços usados ​​para traçar caminhos

### Descrição

public function ImagickDraw::setStrokeDashArray(?array `$dashes`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Especifica o padrão de traços e espaços usados ​​para traçar caminhos. O strokeDashArray representa um array de números que especifica os comprimentos de traços e lacunas alternados em pixels. Se um número ímpar de valores for fornecido, a lista de valores será repetida para produzir um número par de valores. Para remover um array de traços existente, passe zero no argumento number_elements e nulo no dash_array. Um array strokeDashArray_ típico pode conter os membros 5 3 2.

### Parâmetros

`dashes`

  array de números em ponto flutuante

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setStrokeDashArray()

    <?php
    function setStrokeDashArray($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(4);

        $draw->setStrokeDashArray([10, 10]);
        $draw->rectangle(100, 50, 225, 175);

        $draw->setStrokeDashArray([20, 5, 20, 5, 5, 5,]);
        $draw->rectangle(275, 50, 400, 175);

        $draw->setStrokeDashArray([20, 5, 20, 5, 5]);
        $draw->rectangle(100, 200, 225, 350);

        $draw->setStrokeDashArray([1, 1, 1, 1, 2, 2, 3, 3, 5, 5, 8, 8, 13, 13, 21, 21, 34, 34, 55, 55, 89, 89, 144, 144, 233, 233, 377, 377, 610, 610, 987, 987, 1597, 1597, 2584, 2584, 4181, 4181,]);

        $draw->rectangle(275, 200, 400, 350);

        $image = new \Imagick();
        $image->newImage(500, 400, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeDashOffset

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeDashOffset — Especifica o deslocamento no padrão de traço para iniciar o traço

### Descrição

public function ImagickDraw::setStrokeDashOffset(float `$dash_offset`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Especifica o deslocamento no padrão de traço para iniciar o traço.

### Parâmetros

`dash_offset`

  deslocamento do traço

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setStrokeDashOffset()

    <?php
    function setStrokeDashOffset($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(4);
        $draw->setStrokeDashArray([20, 20]);
        $draw->setStrokeDashOffset(0);
        $draw->rectangle(100, 50, 225, 175);

        //Start the dash effect halfway through the solid portion
        $draw->setStrokeDashOffset(10);
        $draw->rectangle(275, 50, 400, 175);

        //Start the dash effect on the space portion
        $draw->setStrokeDashOffset(20);
        $draw->rectangle(100, 200, 225, 350);
        $draw->setStrokeDashOffset(5);
        $draw->rectangle(275, 200, 400, 350);

        $image = new \Imagick();
        $image->newImage(500, 400, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeLineCap

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeLineCap — Especifica a forma a ser usada no final dos subcaminhos abertos quando eles são traçados

### Descrição

public function ImagickDraw::setStrokeLineCap(int `$linecap`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Especifica a forma a ser usada no final dos subcaminhos abertos quando eles são traçados.

### Parâmetros

`linecap`

  Uma das constantes LINECAP (`imagick::LINECAP_*`).

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setStrokeLineCap()

    <?php
    function setStrokeLineCap($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(25);

        $lineTypes = [\Imagick::LINECAP_BUTT, \Imagick::LINECAP_ROUND, \Imagick::LINECAP_SQUARE,];

        $offset = 0;

        foreach ($lineTypes as $lineType) {
            $draw->setStrokeLineCap($lineType);
            $draw->line(50 + $offset, 50, 50 + $offset, 250);
            $offset += 50;
        }

        $imagick = new \Imagick();
        $imagick->newImage(300, 300, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeLineJoin

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeLineJoin — Especifica a forma a ser usada nos cantos dos caminhos quando eles são traçados

### Descrição

public function ImagickDraw::setStrokeLineJoin(int `$linejoin`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Especifica a forma a ser usada nos cantos dos caminhos (ou outras formas vetoriais) quando eles são traçados.

### Parâmetros

`linejoin`

  Uma das constantes LINEJOIN (`imagick::LINEJOIN_*`).

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setStrokeLineJoin()

    <?php
    function setStrokeLineJoin($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeWidth(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(20);

        $offset = 220;

        $lineJoinStyle = [
            \Imagick::LINEJOIN_MITER,
            \Imagick::LINEJOIN_ROUND,
            \Imagick::LINEJOIN_BEVEL,
            ];

        for ($x = 0; $x < count($lineJoinStyle); $x++) {
            $draw->setStrokeLineJoin($lineJoinStyle[$x]);
            $points = [
                ['x' => 40 * 5, 'y' => 10 * 5 + $x * $offset],
                ['x' => 20 * 5, 'y' => 20 * 5 + $x * $offset],
                ['x' => 70 * 5, 'y' => 50 * 5 + $x * $offset],
                ['x' => 40 * 5, 'y' => 10 * 5 + $x * $offset],
            ];

            $draw->polyline($points);
        }

        $image = new \Imagick();
        $image->newImage(500, 700, $backgroundColor);
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeMiterLimit

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeMiterLimit — Especifica o limite de esquadria

### Descrição

public function ImagickDraw::setStrokeMiterLimit(int `$miterlimit`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Especifica o limite de esquadria. Quando dois segmentos de linha se encontram em um ângulo agudo e as junções de esquadria foram especificadas para 'lineJoin', é possível que a esquadria se estenda muito além da espessura da linha que traça o caminho. O 'miterLimit' impõe um limite na proporção entre o comprimento da esquadria e o 'lineWidth'.

### Parâmetros

`miterlimit`

  o limite de esquadria

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setStrokeMiterLimit()

    <?php
    function setStrokeMiterLimit($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setStrokeOpacity(0.6);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(10);

        $yOffset = 100;

        $draw->setStrokeLineJoin(\Imagick::LINEJOIN_MITER);

        for ($y = 0; $y < 3; $y++) {

            $draw->setStrokeMiterLimit(40 * $y);

            $points = [
                ['x' => 22 * 3, 'y' => 15 * 4 + $y * $yOffset],
                ['x' => 20 * 3, 'y' => 20 * 4 + $y * $yOffset],
                ['x' => 70 * 5, 'y' => 45 * 4 + $y * $yOffset],
            ];

            $draw->polygon($points);
        }

        $image = new \Imagick();
        $image->newImage(500, 500, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        $image->setImageType(\Imagick::IMGTYPE_PALETTE);
        $image->setImageCompressionQuality(100);
        $image->stripImage();

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeOpacity — Especifica a opacidade dos contornos dos objetos traçados

### Descrição

public function ImagickDraw::setStrokeOpacity(float `$opacity`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Especifica a opacidade dos contornos dos objetos traçados.

### Parâmetros

`opacity`

  Opacidade do traço. 1.0 é totalmente opaco.

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setStrokeOpacity()

    <?php
    function setStrokeOpacity($strokeColor, $fillColor, $backgroundColor) {
        $draw = new \ImagickDraw();

        $draw->setStrokeWidth(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(10);
        $draw->setStrokeOpacity(1);
        $draw->line(100, 80, 400, 125);
        $draw->rectangle(25, 200, 150, 350);
        $draw->setStrokeOpacity(0.5);
        $draw->line(100, 100, 400, 145);
        $draw->rectangle(200, 200, 325, 350);
        $draw->setStrokeOpacity(0.2);
        $draw->line(100, 120, 400, 165);
        $draw->rectangle(375, 200, 500, 350);

        $image = new \Imagick();
        $image->newImage(550, 400, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokePatternURL

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokePatternURL — Define o padrão usado para traçar contornos de objetos

### Descrição

public function ImagickDraw::setStrokePatternURL(string `$stroke_url`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Define o padrão usado para traçar contornos de objetos.

### Parâmetros

`stroke_url`

  URL do padrão de traço

### Valor Retornado

Retorna `true` em caso de sucesso.

# ImagickDraw::setStrokeWidth

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeWidth — Define a largura do traço usado para desenhar contornos de objetos

### Descrição

public function ImagickDraw::setStrokeWidth(float `$width`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Define a largura do traço usado para desenhar contornos de objetos.

### Parâmetros

`width`

  largura do traço

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setStrokeWidth()

    <?php
    function setStrokeWidth($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeWidth(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->line(100, 100, 400, 145);
        $draw->rectangle(100, 200, 225, 350);
        $draw->setStrokeWidth(5);
        $draw->line(100, 120, 400, 165);
        $draw->rectangle(275, 200, 400, 350);

        $image = new \Imagick();
        $image->newImage(500, 400, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setTextAlignment

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextAlignment — Especifica um alinhamento de texto

### Descrição

public function ImagickDraw::setTextAlignment(int `$align`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Especifica um alinhamento de texto a ser aplicado ao fazer anotações com texto.

### Parâmetros

`align`

  Uma das constantes ALIGN (`imagick::ALIGN_*`).

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setTextAlignment()

    <?php
    function setTextAlignment($strokeColor, $fillColor, $backgroundColor) {
        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(1);
        $draw->setFontSize(36);

        $draw->setTextAlignment(\Imagick::ALIGN_LEFT);
        $draw->annotation(250, 75, "Lorem Ipsum!");
        $draw->setTextAlignment(\Imagick::ALIGN_CENTER);
        $draw->annotation(250, 150, "Lorem Ipsum!");
        $draw->setTextAlignment(\Imagick::ALIGN_RIGHT);
        $draw->annotation(250, 225, "Lorem Ipsum!");
        $draw->line(250, 0, 250, 500);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setTextAntialias

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextAntialias — Controla se o texto é suavizado

### Descrição

public function ImagickDraw::setTextAntialias(bool `$antialias`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Controla se o texto é suavizado. Texto é suavizado por padrão.

### Parâmetros

`antialias`

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setTextAntialias()

    <?php
    function setTextAntialias($fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeColor('none');
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(1);
        $draw->setFontSize(32);
        $draw->setTextAntialias(false);
        $draw->annotation(5, 30, "Lorem Ipsum!");
        $draw->setTextAntialias(true);
        $draw->annotation(5, 65, "Lorem Ipsum!");

        $imagick = new \Imagick();
        $imagick->newImage(220, 80, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        // Aumenta a imagem para que a suavização possa ser visualizada.
        $imagick->scaleImage(220 * 6, 80 * 6);
        $imagick->cropImage(640, 480, 0, 0);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setTextDecoration

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextDecoration — Especifica uma decoração

### Descrição

public function ImagickDraw::setTextDecoration(int `$decoration`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Especifica uma decoração a ser aplicada ao fazer anotações com texto.

### Parâmetros

`decoration`

  Uma das constantes DECORATION (`imagick::DECORATION_*`).

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setTextDecoration()

    <?php
    function setTextDecoration($strokeColor, $fillColor, $backgroundColor, $textDecoration) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);
        $draw->setTextDecoration($textDecoration);
        $draw->annotation(50, 75, "Lorem Ipsum!");

        $imagick = new \Imagick();
        $imagick->newImage(500, 200, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setTextEncoding

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextEncoding — Especifica o conjunto de caracteres do texto

### Descrição

public function ImagickDraw::setTextEncoding(string `$encoding`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Especifica o conjunto de caracteres a ser usado para anotações de texto. O único conjunto de caracteres que pode ser especificado neste momento é "UTF-8" para representar Unicode como uma sequência de bytes. Especifique uma string vazia para definir o conjunto de caracteres para o padrão do sistema. Anotação de texto bem-sucedida usando Unicode pode exigir fontes projetadas para suportar Unicode.

### Parâmetros

`encoding`

  o nome do conjunto de caracteres

### Valor Retornado

Nenhum valor é retornado.

# ImagickDraw::setTextInterlineSpacing

(PECL imagick 3 >= 3.1.0)

ImagickDraw::setTextInterlineSpacing — Define o espaçamento entre linhas do texto

### Descrição

public function ImagickDraw::setTextInterlineSpacing(float `$spacing`): bool

Define o espaçamento entre linhas do texto.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`spacing`

### Valor Retornado

Retorna `true` em caso de sucesso.

# ImagickDraw::setTextInterwordSpacing

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickDraw::setTextInterwordSpacing — Define o espaçamento entre palavras do texto

### Descrição

public function ImagickDraw::setTextInterwordSpacing(float `$spacing`): bool

Define o espaçamento entre palavras do texto.

### Parâmetros

`spacing`

### Valor Retornado

Retorna `true` em caso de sucesso.

# ImagickDraw::setTextKerning

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickDraw::setTextKerning — Define o espaçamento entre letras do texto

### Descrição

public function ImagickDraw::setTextKerning(float `$kerning`): bool

Define o espaçamento entre letras do texto.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`kerning`

### Valor Retornado

Retorna `true` em caso de sucesso.

# ImagickDraw::setTextUnderColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextUnderColor — Especifica a cor de um retângulo de fundo

### Descrição

public function ImagickDraw::setTextUnderColor(ImagickPixel|string `$under_color`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Especifica a cor de um retângulo de fundo a ser colocado sob anotações de texto.

### Parâmetros

`under_color`

  a cor de fundo

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setTextUnderColor()

    <?php
    function setTextUnderColor($strokeColor, $fillColor, $backgroundColor, $textUnderColor) {
        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);
        $draw->annotation(50, 75, "Lorem Ipsum!");
        $draw->setTextUnderColor($textUnderColor);
        $draw->annotation(50, 175, "Lorem Ipsum!");

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setVectorGraphics

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setVectorGraphics — Define os gráficos vetoriais

### Descrição

public function ImagickDraw::setVectorGraphics(string `$xml`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Define os gráficos vetoriais associados ao objeto ImagickDraw especificado. Use este método com ImagickDraw::getVectorGraphics() como uma forma de persistir o estado dos gráficos vetoriais.

### Parâmetros

`xml`

  XML contendo os gráficos vetoriais

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setVectorGraphics()

    <?php
    function setVectorGraphics() {
        // Configura um objeto com um desenho
        $draw = new \ImagickDraw();
        $draw->setFillColor("red");
        $draw->circle(20, 20, 50, 50);
        $draw->setFillColor("blue");
        $draw->circle(50, 70, 50, 50);
        $draw->rectangle(50, 120, 80, 150);

        // Obtém o desenho como uma string
        $SVG = $draw->getVectorGraphics();

        // $svg é uma string e poderia ser salva em qualquer lugar que uma string puder ser salva

        // Use o desenho salvo para gerar um novo objeto de desenho
        $draw2 = new \ImagickDraw();
        // Aparentemento falta no texto SVG o elemento "root".
        $draw2->setVectorGraphics("<root>".$SVG."</root>");

        $imagick = new \Imagick();
        $imagick->newImage(200, 200, 'white');
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw2);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setViewbox

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setViewbox — Define o tamanho geral da tela

### Descrição

public function ImagickDraw::setViewbox(
int `$left_x`,
int `$top_y`,
int `$right_x`,
int `$bottom_y`
): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Define o tamanho geral da tela a ser gravado com os dados vetoriais do desenho. Geralmente isso será especificado usando o mesmo tamanho da imagem da tela. Quando os dados vetoriais são salvos nos formatos SVG ou MVG, a caixa de visualização é usada para especificar o tamanho da imagem da tela na qual um visualizador renderizará os dados vetoriais.

### Parâmetros

`left_x`

  coordenada x esquerda

`top_y`

  coordenada y esquerda

`right_x`

  coordenada x direita

`bottom_y`

  coordenada y direita

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::setViewBox()

    <?php
    function setViewBox($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);

        /*

        Define o tamanho geral da tela a ser gravado com os dados vetoriais do desenho. Geralmente isso será especificado usando o mesmo tamanho da imagem da tela. Quando os dados vetoriais são salvos nos formatos SVG ou MVG, a caixa de visualização é usada para especificar o tamanho da imagem da tela na qual um visualizador renderizará os dados vetoriais.

         */

        $draw->circle(250, 250, 250, 0);
        $draw->setviewbox(0, 0, 200, 200);
        $draw->circle(125, 250, 250, 250);
        $draw->translate(250, 125);
        $draw->circle(0, 0, 125, 0);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::skewX

(PECL imagick 2, PECL imagick 3)

ImagickDraw::skewX — Inclina o sistema de coordenadas atual na direção horizontal

### Descrição

public function ImagickDraw::skewX(float `$degrees`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Inclina o sistema de coordenadas atual na direção horizontal.

### Parâmetros

`degrees`

  graus para inclinar

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::skewX()

    <?php
    function skewX($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor,
                   $startX, $startY, $endX, $endY, $skew) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setStrokeWidth(2);
        $draw->setFillColor($fillColor);
        $draw->rectangle($startX, $startY, $endX, $endY);
        $draw->setFillColor($fillModifiedColor);
        $draw->skewX($skew);
        $draw->rectangle($startX, $startY, $endX, $endY);

        $image = new \Imagick();
        $image->newImage(500, 500, $backgroundColor);
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::skewY

(PECL imagick 2, PECL imagick 3)

ImagickDraw::skewY — Inclina o sistema de coordenadas atual na direção vertical

### Descrição

public function ImagickDraw::skewY(float `$degrees`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Inclina o sistema de coordenadas atual na direção vertical.

### Parâmetros

`degrees`

  graus para inclinar

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::skewY()

    <?php
    function skewY($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor,
                   $startX, $startY, $endX, $endY, $skew) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setStrokeWidth(2);
        $draw->setFillColor($fillColor);
        $draw->rectangle($startX, $startY, $endX, $endY);
        $draw->setFillColor($fillModifiedColor);
        $draw->skewY($skew);
        $draw->rectangle($startX, $startY, $endX, $endY);

        $image = new \Imagick();
        $image->newImage(500, 500, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::translate

(PECL imagick 2, PECL imagick 3)

ImagickDraw::translate — Aplica uma translação no sistema de coordenadas atual

### Descrição

public function ImagickDraw::translate(float `$x`, float `$y`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Aplica uma translação ao sistema de coordenadas atual que move a origem do sistema de coordenadas para a coordenada especificada.

### Parâmetros

`x`

  translação horizontal

`y`

  translação vertical

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de ImagickDraw::translate()

    <?php
    function translate($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor,
                       $startX, $startY, $endX, $endY, $translateX, $translateY) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->rectangle($startX, $startY, $endX, $endY);

        $draw->setFillColor($fillModifiedColor);
        $draw->translate($translateX, $translateY);
        $draw->rectangle($startX, $startY, $endX, $endY);

        $image = new \Imagick();
        $image->newImage(500, 500, $backgroundColor);
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

## Índice

- ImagickDraw::affine — Ajusta a matriz de transformação afim atual
- ImagickDraw::annotation — Desenha texto na imagem
- ImagickDraw::arc — Desenha um arco
- ImagickDraw::bezier — Desenha uma curva de Bézier
- ImagickDraw::circle — Desenha um círculo
- ImagickDraw::clear — Limpa o ImagickDraw
- ImagickDraw::clone — Faz uma cópia exata do objeto ImagickDraw especificado
- ImagickDraw::color — Desenha cores na imagem
- ImagickDraw::comment — Adiciona um comentário
- ImagickDraw::composite — Compõe uma imagem sobre a imagem atual
- ImagickDraw::__construct — O construtor ImagickDraw
- ImagickDraw::destroy — Libera todos os recursos associados
- ImagickDraw::ellipse — Desenha uma elipse na imagem
- ImagickDraw::getClipPath — Obtém o ID do caminho de recorte atual
- ImagickDraw::getClipRule — Retorna a regra atual de preenchimento do polígono
- ImagickDraw::getClipUnits — Retorna a interpretação das unidades de caminho de recorte
- ImagickDraw::getFillColor — Retorna a cor de preenchimento
- ImagickDraw::getFillOpacity — Retorna a opacidade usada ao desenhar
- ImagickDraw::getFillRule — Retorna a regra de preenchimento
- ImagickDraw::getFont — Retorna a fonte
- ImagickDraw::getFontFamily — Retorna a família de fontes
- ImagickDraw::getFontSize — Retorna o tamanho da fonte em pontos
- ImagickDraw::getFontStretch — Obtém o esticamento de fonte a ser usado ao fazer anotações com texto
- ImagickDraw::getFontStyle — Retorna o estilo da fonte
- ImagickDraw::getFontWeight — Retorna a espessura da fonte
- ImagickDraw::getGravity — Retorna o alinhamento de posicionamento do texto
- ImagickDraw::getStrokeAntialias — Retorna a configuração atual de suavização do traço
- ImagickDraw::getStrokeColor — Retorna a cor usada para traçar os contornos dos objetos
- ImagickDraw::getStrokeDashArray — Retorna um array que representa o padrão de traços e espaços usados ​​para traçar caminhos
- ImagickDraw::getStrokeDashOffset — Retorna o deslocamento no padrão de traço para iniciar o traço
- ImagickDraw::getStrokeLineCap — Retorna a forma a ser usada no final dos subcaminhos abertos quando eles são traçados
- ImagickDraw::getStrokeLineJoin — Retorna a forma a ser usada nos cantos dos caminhos quando eles são traçados
- ImagickDraw::getStrokeMiterLimit — Retorna o limite de esquadria do traçado
- ImagickDraw::getStrokeOpacity — Retorna a opacidade dos contornos dos objetos traçados
- ImagickDraw::getStrokeWidth — Retorna a largura do traço usado para desenhar contornos de objetos
- ImagickDraw::getTextAlignment — Retorna o alinhamento do texto
- ImagickDraw::getTextAntialias — Retorna a configuração atual de antialias do texto
- ImagickDraw::getTextDecoration — Retorna a decoração do texto
- ImagickDraw::getTextEncoding — Retorna o conjunto de caracteres usado para anotações de texto
- ImagickDraw::getTextInterlineSpacing — Obtém o espaçamento entre linhas do texto
- ImagickDraw::getTextInterwordSpacing — Obtém o espaçamento entre palavras do texto
- ImagickDraw::getTextKerning — Obtém o espaçamento entre letras do texto
- ImagickDraw::getTextUnderColor — Retorna a cor sob o texto
- ImagickDraw::getVectorGraphics — Retorna uma string contendo gráficos vetoriais
- ImagickDraw::line — Desenha uma linha
- ImagickDraw::matte — Pinta no canal de opacidade da imagem
- ImagickDraw::pathClose — Adiciona um elemento de caminho ao caminho atual
- ImagickDraw::pathCurveToAbsolute — Desenha uma curva cúbica de Bézier
- ImagickDraw::pathCurveToQuadraticBezierAbsolute — Desenha uma curva quadrática de Bézier
- ImagickDraw::pathCurveToQuadraticBezierRelative — Desenha uma curva quadrática de Bézier
- ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute — Desenha uma curva quadrática de Bézier
- ImagickDraw::pathCurveToQuadraticBezierSmoothRelative — Desenha uma curva quadrática de Bézier
- ImagickDraw::pathCurveToRelative — Desenha uma curva cúbica de Bézier
- ImagickDraw::pathCurveToSmoothAbsolute — Desenha uma curva cúbica de Bézier
- ImagickDraw::pathCurveToSmoothRelative — Desenha uma curva cúbica de Bézier
- ImagickDraw::pathEllipticArcAbsolute — Desenha um arco elíptico
- ImagickDraw::pathEllipticArcRelative — Desenha um arco elíptico
- ImagickDraw::pathFinish — Termina o caminho atual
- ImagickDraw::pathLineToAbsolute — Desenha um caminho de linha
- ImagickDraw::pathLineToHorizontalAbsolute — Desenha um caminho de linha horizontal
- ImagickDraw::pathLineToHorizontalRelative — Desenha um caminho de linha horizontal
- ImagickDraw::pathLineToRelative — Desenha um caminho de linha
- ImagickDraw::pathLineToVerticalAbsolute — Desenha um caminho de linha vertical
- ImagickDraw::pathLineToVerticalRelative — Desenha um caminho de linha vertical
- ImagickDraw::pathMoveToAbsolute — Inicia um novo subcaminho
- ImagickDraw::pathMoveToRelative — Inicia um novo subcaminho
- ImagickDraw::pathStart — Declara o início de uma lista de desenho de caminho
- ImagickDraw::point — Desenha um ponto
- ImagickDraw::polygon — Desenha um polígono
- ImagickDraw::polyline — Desenha uma polilinha
- ImagickDraw::pop — Destrói o ImagickDraw atual na pilha e retorna ao ImagickDraw enviado anteriormente
- ImagickDraw::popClipPath — Encerra uma definição de caminho de recorte
- ImagickDraw::popDefs — Encerra uma lista de definições
- ImagickDraw::popPattern — Encerra uma definição de padrão
- ImagickDraw::push — Clona o ImagickDraw atual e o coloca na pilha
- ImagickDraw::pushClipPath — Inicia uma definição de caminho de recorte
- ImagickDraw::pushDefs — Indica que os comandos a seguir criam elementos nomeados para processamento antecipado
- ImagickDraw::pushPattern — Indica que os comandos subsequentes até um comando ImagickDraw::opPattern() compreendem a definição de um padrão nomeado
- ImagickDraw::rectangle — Desenha um retângulo
- ImagickDraw::render — Renderiza todos os comandos de desenho anteriores na imagem
- ImagickDraw::resetVectorGraphics — Redefine os gráficos vetoriais
- ImagickDraw::rotate — Aplica a rotação especificada ao espaço de coordenadas atual
- ImagickDraw::roundRectangle — Desenha um retângulo arredondado
- ImagickDraw::scale — Ajusta o fator de escala
- ImagickDraw::setClipPath — Associa um caminho de recorte nomeado à imagem
- ImagickDraw::setClipRule — Define a regra de preenchimento do polígono a ser usada pelo traçado de recorte
- ImagickDraw::setClipUnits — Define a interpretação das unidades do caminho de recorte
- ImagickDraw::setFillAlpha — Define a opacidade a ser usada ao desenhar usando a cor ou textura de preenchimento
- ImagickDraw::setFillColor — Define a cor de preenchimento a ser usada para desenhar objetos preenchidos
- ImagickDraw::setFillOpacity — Define a opacidade a ser usada ao desenhar usando a cor ou textura de preenchimento
- ImagickDraw::setFillPatternURL — Define a URL a ser usada como padrão de preenchimento para preencher objetos
- ImagickDraw::setFillRule — Define a regra de preenchimento a ser usada ao desenhar polígonos
- ImagickDraw::setFont — Define a fonte totalmente especificada a ser usada ao fazer anotações com texto
- ImagickDraw::setFontFamily — Define a família de fontes a ser usada ao fazer anotações com texto
- ImagickDraw::setFontSize — Define o tamanho da fonte a ser usado ao fazer anotações com texto
- ImagickDraw::setFontStretch — Define o esticamento da fonte a ser usado ao fazer anotações com texto
- ImagickDraw::setFontStyle — Define o estilo da fonte a ser usado ao fazer anotações com texto
- ImagickDraw::setFontWeight — Define a espessura da fonte
- ImagickDraw::setGravity — Define a gravidade do posicionamento do texto
- ImagickDraw::setResolution — Define a resolução
- ImagickDraw::setStrokeAlpha — Especifica a opacidade dos contornos dos objetos traçados
- ImagickDraw::setStrokeAntialias — Controla se os contornos traçados são suavizados
- ImagickDraw::setStrokeColor — Define a cor usada para traçar os contornos dos objetos
- ImagickDraw::setStrokeDashArray — Especifica o padrão de traços e espaços usados ​​para traçar caminhos
- ImagickDraw::setStrokeDashOffset — Especifica o deslocamento no padrão de traço para iniciar o traço
- ImagickDraw::setStrokeLineCap — Especifica a forma a ser usada no final dos subcaminhos abertos quando eles são traçados
- ImagickDraw::setStrokeLineJoin — Especifica a forma a ser usada nos cantos dos caminhos quando eles são traçados
- ImagickDraw::setStrokeMiterLimit — Especifica o limite de esquadria
- ImagickDraw::setStrokeOpacity — Especifica a opacidade dos contornos dos objetos traçados
- ImagickDraw::setStrokePatternURL — Define o padrão usado para traçar contornos de objetos
- ImagickDraw::setStrokeWidth — Define a largura do traço usado para desenhar contornos de objetos
- ImagickDraw::setTextAlignment — Especifica um alinhamento de texto
- ImagickDraw::setTextAntialias — Controla se o texto é suavizado
- ImagickDraw::setTextDecoration — Especifica uma decoração
- ImagickDraw::setTextEncoding — Especifica o conjunto de caracteres do texto
- ImagickDraw::setTextInterlineSpacing — Define o espaçamento entre linhas do texto
- ImagickDraw::setTextInterwordSpacing — Define o espaçamento entre palavras do texto
- ImagickDraw::setTextKerning — Define o espaçamento entre letras do texto
- ImagickDraw::setTextUnderColor — Especifica a cor de um retângulo de fundo
- ImagickDraw::setVectorGraphics — Define os gráficos vetoriais
- ImagickDraw::setViewbox — Define o tamanho geral da tela
- ImagickDraw::skewX — Inclina o sistema de coordenadas atual na direção horizontal
- ImagickDraw::skewY — Inclina o sistema de coordenadas atual na direção vertical
- ImagickDraw::translate — Aplica uma translação no sistema de coordenadas atual

# A classe ImagickDrawException

(PECL imagick 3)

## Introdução

## Resumo da classe

class ImagickDrawException extends Exception implements Throwable {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
/* Métodos herdados */
}

# A classe ImagickException

(PECL imagick 3)

## Introdução

## Resumo da classe

class ImagickException extends Exception implements Throwable {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
/* Métodos herdados */
}

# A classe ImagickKernel

(PECL imagick >= 3.3.0)

## Introdução

## Resumo da classe

class ImagickKernel {
/* Métodos */
public function addKernel(ImagickKernel `$ImagickKernel`): void
public function addUnityKernel(float `$scale`): void
public static function fromBuiltin(int `$kernelType`, string `$kernelString`): ImagickKernel
public static function fromMatrix(array `$matrix`, array `$origin` = ?): ImagickKernel
public function getMatrix(): array
public function scale(float `$scale`, int `$normalizeFlag` = ?): void
public function separate(): array
}

# ImagickKernel::addKernel

(PECL imagick >= 3.3.0)

ImagickKernel::addKernel — Anexa outro kernel a uma lista de kernels

### Descrição

public function ImagickKernel::addKernel(ImagickKernel `$ImagickKernel`): void

Anexa outro kernel a este kernel para permitir que ambos sejam aplicados em uma única morfologia ou função de filtro. Retorna o novo kernel combinado.

### Parâmetros

`ImagickKernel`

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de ImagickKernel::addKernel()

    <?php
    function addKernel($imagePath) {
        $matrix1 = [
            [-1, -1, -1],
            [ 0,  0,  0],
            [ 1,  1,  1],
        ];

        $matrix2 = [
            [-1,  0,  1],
            [-1,  0,  1],
            [-1,  0,  1],
        ];

        $kernel1 = ImagickKernel::fromMatrix($matrix1);
        $kernel2 = ImagickKernel::fromMatrix($matrix2);
        $kernel1->addKernel($kernel2);

        $imagick = new \Imagick(realpath($imagePath));
        $imagick->filter($kernel1);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();

    }

    ?>

# ImagickKernel::addUnityKernel

(PECL imagick >= 3.3.0)

ImagickKernel::addUnityKernel — Adiciona um Kernel Unity à lista de kernels

### Descrição

public function ImagickKernel::addUnityKernel(float `$scale`): void

Adiciona uma determinada quantidade do Kernel de Convolução 'Unity' ao Kernel pré-escalado e normalizado fornecido. Na verdade, isso adiciona essa quantidade da imagem original ao kernel de convolução resultante. O efeito resultante é converter os kernels definidos em kernels desfocados suaves combinados, ou em kernels nítidos.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

### Exemplos

Exemplo #1 ImagickKernel::addUnityKernel()

    <?php

        function renderKernelTable($matrix) {
            $output = "<table class='infoTable'>";

            foreach ($matrix as $row) {
                $output .= "<tr>";
                foreach ($row as $cell) {
                    $output .= "<td style='text-align:left'>";
                    if ($cell === false) {
                        $output .= "false";
                    }
                    else {
                        $output .= round($cell, 3);
                    }
                    $output .= "</td>";
                }
                $output .= "</tr>";
            }

            $output .= "</table>";

            return $output;
        }

        $matrix = [
            [-1, 0, -1],
            [ 0, 4,  0],
            [-1, 0, -1],
        ];

        $kernel = \ImagickKernel::fromMatrix($matrix);
        $kernel->scale(1, \Imagick::NORMALIZE_KERNEL_VALUE);
        $output = "Before adding unity kernel: <br/>";
        $output .= renderKernelTable($kernel->getMatrix());
        $kernel->addUnityKernel(0.5);
        $output .= "After adding unity kernel: <br/>";
        $output .= renderKernelTable($kernel->getMatrix());

        $kernel->scale(1, \Imagick::NORMALIZE_KERNEL_VALUE);
        $output .= "After renormalizing kernel: <br/>";
        $output .= renderKernelTable($kernel->getMatrix());

        echo $output;

    ?>

Exemplo #2 Exemplo de ImagickKernel::addUnityKernel()

    <?php
    function addUnityKernel($imagePath) {

        $matrix = [
            [-1, 0, -1],
            [ 0, 4,  0],
            [-1, 0, -1],
        ];

        $kernel = ImagickKernel::fromMatrix($matrix);

        $kernel->scale(4, \Imagick::NORMALIZE_KERNEL_VALUE);
        $kernel->addUnityKernel(0.5);

        $imagick = new \Imagick(realpath($imagePath));
        $imagick->filter($kernel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();

    }

    ?>

# ImagickKernel::fromBuiltIn

(PECL imagick >= 3.3.0)

ImagickKernel::fromBuiltIn — Cria um kernel a partir de um kernel integrado

### Descrição

public static function ImagickKernel::fromBuiltin(int `$kernelType`, string `$kernelString`): ImagickKernel

Cria um kernel a partir de um kernel integrado. Consulte http://www.imagemagick.org/Usage/morphology/#kernel para obter exemplos. Atualmente os símbolos 'rotation' não são suportados. Exemplo: $diamondKernel = ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DIAMOND, "2");

### Parâmetros

`kerneltype`

  O tipo de kernel a ser construído, por ex. \Imagick::KERNEL_DIAMOND

`kernelString`

  Uma string que descreve os parâmetros, por exemplo. "4,2.5"

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de ImagickKernel::fromBuiltin()

    <?php

    function renderKernel(ImagickKernel $imagickKernel) {
        $matrix = $imagickKernel->getMatrix();

        $imageMargin = 20;

        $tileSize = 20;
        $tileSpace = 4;
        $shadowSigma = 4;
        $shadowDropX = 20;
        $shadowDropY = 0;

        $radius = ($tileSize / 2) * 0.9;

        $rows = count($matrix);
        $columns = count($matrix[0]);

        $imagickDraw = new \ImagickDraw();

        $imagickDraw->setFillColor('#afafaf');
        $imagickDraw->setStrokeColor('none');

        $imagickDraw->translate($imageMargin, $imageMargin);
        $imagickDraw->push();

        ksort($matrix);

        foreach ($matrix as $row) {
            ksort($row);
            $imagickDraw->push();
            foreach ($row as $cell) {
                if ($cell !== false) {
                    $color = intval(255 * $cell);
                    $colorString = sprintf("rgb(%f, %f, %f)", $color, $color, $color);
                    $imagickDraw->setFillColor($colorString);
                    $imagickDraw->rectangle(0, 0, $tileSize, $tileSize);
                }
                $imagickDraw->translate(($tileSize + $tileSpace), 0);
            }
            $imagickDraw->pop();
            $imagickDraw->translate(0, ($tileSize + $tileSpace));
        }

        $imagickDraw->pop();

        $width = ($columns * $tileSize) + (($columns - 1) * $tileSpace);
        $height = ($rows * $tileSize) + (($rows - 1) * $tileSpace);

        $imagickDraw->push();
        $imagickDraw->translate($width/2 , $height/2);
        $imagickDraw->setFillColor('rgba(0, 0, 0, 0)');
        $imagickDraw->setStrokeColor('white');
        $imagickDraw->circle(0, 0, $radius - 1, 0);
        $imagickDraw->setStrokeColor('black');
        $imagickDraw->circle(0, 0, $radius, 0);
        $imagickDraw->pop();

        $canvasWidth = $width + (2 * $imageMargin);
        $canvasHeight = $height + (2 * $imageMargin);

        $kernel = new \Imagick();
        $kernel->newPseudoImage(
            $canvasWidth,
            $canvasHeight,
            'canvas:none'
        );

        $kernel->setImageFormat('png');
        $kernel->drawImage($imagickDraw);

        /* cria sombra projetada em sua própria camada */
        $canvas = $kernel->clone();
        $canvas->setImageBackgroundColor(new \ImagickPixel('rgb(0, 0, 0)'));
        $canvas->shadowImage(100, $shadowSigma, $shadowDropX, $shadowDropY);

        $canvas->setImagePage($canvasWidth, $canvasHeight, -5, -5);
        $canvas->cropImage($canvasWidth, $canvasHeight, 0, 0);

        /* compõe text_layer original em shadow_layer */
        $canvas->compositeImage($kernel, \Imagick::COMPOSITE_OVER, 0, 0);
        $canvas->setImageFormat('png');

        return $canvas;
    }

    function createFromBuiltin($kernelType, $kernelFirstTerm, $kernelSecondTerm, $kernelThirdTerm) {
        $string = '';

        if ($kernelFirstTerm != false && strlen(trim($kernelFirstTerm)) != 0) {
            $string .= $kernelFirstTerm;

            if ($kernelSecondTerm != false && strlen(trim($kernelSecondTerm)) != 0) {
                $string .= ','.$kernelSecondTerm;
                if ($kernelThirdTerm != false && strlen(trim($kernelThirdTerm)) != 0) {
                    $string .= ','.$kernelThirdTerm;
                }
            }
        }

        $kernel = ImagickKernel::fromBuiltIn(
            $kernelType,
            $string
        );

        return $kernel;
    }

    function fromBuiltin($kernelType, $kernelFirstTerm, $kernelSecondTerm, $kernelThirdTerm) {
        $diamondKernel = createFromBuiltin($kernelType, $kernelFirstTerm, $kernelSecondTerm, $kernelThirdTerm);
        $imagick = renderKernel($diamondKernel);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    fromBuiltin(\Imagick::KERNEL_DIAMOND, 2, false, false);

    ?>

# ImagickKernel::fromMatrix

(PECL imagick >= 3.3.0)

ImagickKernel::fromMatrix — Crie um kernel a partir de uma matriz 2D de valores

### Descrição

public static function ImagickKernel::fromMatrix(array `$matrix`, array `$origin` = ?): ImagickKernel

Cria um kernel a partir de uma matriz 2D de valores. Cada valor deve ser um float (se o elemento deve ser usado) ou 'false' se o elemento deve ser ignorado. Para matrizes com tamanhos ímpares em ambas as dimensões, o pixel de origem será padronizado para o centro do kernel. Para todos os outros tamanhos de kernel, o pixel de origem deve ser especificado.

### Parâmetros

`array`

  Uma matriz (ou seja, array 2D) de valores que definem o kernel. Cada elemento deve ser um valor float ou FALSE se esse elemento não deve ser usado pelo kernel.

`array`

  Qual elemento do kernel deve ser usado como pixel de origem. Por exemplo, para uma matriz 3x3, especificar a origem como [2, 2] definiria que o elemento inferior direito deveria ser o pixel de origem.

### Valor Retornado

O ImagickKernel gerado.

### Exemplos

Exemplo #1 Exemplo de ImagickKernel::fromMatrix()

    <?php

    function renderKernel(ImagickKernel $imagickKernel) {
        $matrix = $imagickKernel->getMatrix();

        $imageMargin = 20;

        $tileSize = 20;
        $tileSpace = 4;
        $shadowSigma = 4;
        $shadowDropX = 20;
        $shadowDropY = 0;

        $radius = ($tileSize / 2) * 0.9;

        $rows = count($matrix);
        $columns = count($matrix[0]);

        $imagickDraw = new \ImagickDraw();

        $imagickDraw->setFillColor('#afafaf');
        $imagickDraw->setStrokeColor('none');

        $imagickDraw->translate($imageMargin, $imageMargin);
        $imagickDraw->push();

        ksort($matrix);

        foreach ($matrix as $row) {
            ksort($row);
            $imagickDraw->push();
            foreach ($row as $cell) {
                if ($cell !== false) {
                    $color = intval(255 * $cell);
                    $colorString = sprintf("rgb(%f, %f, %f)", $color, $color, $color);
                    $imagickDraw->setFillColor($colorString);
                    $imagickDraw->rectangle(0, 0, $tileSize, $tileSize);
                }
                $imagickDraw->translate(($tileSize + $tileSpace), 0);
            }
            $imagickDraw->pop();
            $imagickDraw->translate(0, ($tileSize + $tileSpace));
        }

        $imagickDraw->pop();

        $width = ($columns * $tileSize) + (($columns - 1) * $tileSpace);
        $height = ($rows * $tileSize) + (($rows - 1) * $tileSpace);

        $imagickDraw->push();
        $imagickDraw->translate($width/2 , $height/2);
        $imagickDraw->setFillColor('rgba(0, 0, 0, 0)');
        $imagickDraw->setStrokeColor('white');
        $imagickDraw->circle(0, 0, $radius - 1, 0);
        $imagickDraw->setStrokeColor('black');
        $imagickDraw->circle(0, 0, $radius, 0);
        $imagickDraw->pop();

        $canvasWidth = $width + (2 * $imageMargin);
        $canvasHeight = $height + (2 * $imageMargin);

        $kernel = new \Imagick();
        $kernel->newPseudoImage(
            $canvasWidth,
            $canvasHeight,
            'canvas:none'
        );

        $kernel->setImageFormat('png');
        $kernel->drawImage($imagickDraw);

        /* cria sombra projetada em sua própria camada */
        $canvas = $kernel->clone();
        $canvas->setImageBackgroundColor(new \ImagickPixel('rgb(0, 0, 0)'));
        $canvas->shadowImage(100, $shadowSigma, $shadowDropX, $shadowDropY);

        $canvas->setImagePage($canvasWidth, $canvasHeight, -5, -5);
        $canvas->cropImage($canvasWidth, $canvasHeight, 0, 0);

        /* compõe text_layer original em shadow_layer */
        $canvas->compositeImage($kernel, \Imagick::COMPOSITE_OVER, 0, 0);
        $canvas->setImageFormat('png');

        return $canvas;
    }

    function createFromMatrix() {
        $matrix = [
            [0.5, 0, 0.2],
            [0, 1, 0],
            [0.9, 0, false],
        ];

        $kernel = \ImagickKernel::fromMatrix($matrix);

        return $kernel;
    }

    function fromMatrix() {
        $kernel = createFromMatrix();
        $imagick = renderKernel($kernel);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickKernel::getMatrix

(PECL imagick >= 3.3.0)

ImagickKernel::getMatrix — Obtém a matriz 2D de valores usada neste kernel

### Descrição

public function ImagickKernel::getMatrix(): array

Obtém a matriz 2D de valores usada neste kernel. Os elementos são float para elementos usados ​​ou 'false' se o elemento deve ser ignorado.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Uma matriz (array 2D) dos valores que representam o kernel.

### Exemplos

Exemplo #1 Exemplo de ImagickKernel::getMatrix()

    <?php

    function renderKernelTable($matrix) {
        $output = "<table class='infoTable'>";

        foreach ($matrix as $row) {
            $output .= "<tr>";
            foreach ($row as $cell) {
                $output .= "<td style='text-align:left'>";
                if ($cell === false) {
                    $output .= "false";
                }
                else {
                    $output .= round($cell, 3);
                }
                $output .= "</td>";
            }
            $output .= "</tr>";
        }

        $output .= "</table>";

        return $output;
    }

        $output = "O nome do kernel integrado 'ring' com parâmetros de '2,3.5':<br/>";
        $kernel = \ImagickKernel::fromBuiltIn(
            \Imagick::KERNEL_RING,
            "2,3.5"
        );
        $matrix = $kernel->getMatrix();
        $output .= renderKernelTable($matrix);

        echo $output;

    ?>

# ImagickKernel::scale

(PECL imagick >= 3.3.0)

ImagickKernel::scale — Dimensiona uma lista de kernel pela quantidade especificada

### Descrição

public function ImagickKernel::scale(float `$scale`, int `$normalizeFlag` = ?): void

Dimensiona a lista de kernel fornecida de acordo com a quantidade especificada, com ou sem normalização da soma dos valores do kernel (de acordo com as opções fornecidas). O comportamento exato desta função depende do tipo de normalização usado. Consulte http://www.imagemagick.org/api/morphology.php#ScaleKernelInfo para obter detalhes.

### Parâmetros

`scale`

`normalizeFlag`

  - Imagick::NORMALIZE_KERNEL_NONE
  - Imagick::NORMALIZE_KERNEL_VALUE
  - Imagick::NORMALIZE_KERNEL_CORRELATE
  - Imagick::NORMALIZE_KERNEL_PERCENT

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de ImagickKernel::scale()

    <?php

        function renderKernelTable($matrix) {
            $output = "<table class='infoTable'>";

            foreach ($matrix as $row) {
                $output .= "<tr>";
                foreach ($row as $cell) {
                    $output .= "<td style='text-align:left'>";
                    if ($cell === false) {
                        $output .= "false";
                    }
                    else {
                        $output .= round($cell, 3);
                    }
                    $output .= "</td>";
                }
                $output .= "</tr>";
            }

            $output .= "</table>";

            return $output;
        }

        $output = "";

        $matrix = [
            [-1, 0, -1],
            [ 0, 4,  0],
            [-1, 0, -1],
        ];

        $kernel = \ImagickKernel::fromMatrix($matrix);
        $kernelClone = clone $kernel;

        $output .= "Inicia kernel<br/>";
        $output .= renderKernelTable($kernel->getMatrix());

        $output .= "Dimensionando com NORMALIZE_KERNEL_VALUE<br/>";
        $kernel->scale(2, \Imagick::NORMALIZE_KERNEL_VALUE);
        $output .= renderKernelTable($kernel->getMatrix());

        $kernel = clone $kernelClone;
        $output .= "Dimensionando por porcentagem<br/>";
        $kernel->scale(2, \Imagick::NORMALIZE_KERNEL_PERCENT);
        $output .= renderKernelTable($kernel->getMatrix());

        $matrix2 = [
            [-1, -1, 1],
            [ -1, false,  1],
            [1, 1, 1],
        ];

        $kernel = \ImagickKernel::fromMatrix($matrix2);
        $output .= "Dimensionando por correlação<br/>";
        $kernel->scale(1, \Imagick::NORMALIZE_KERNEL_CORRELATE);
        $output .= renderKernelTable($kernel->getMatrix());

        return $output;
    ?>

# ImagickKernel::separate

(PECL imagick >= 3.3.0)

ImagickKernel::separate — Separa um conjunto vinculado de kernels e retorna um array de ImagickKernels

### Descrição

public function ImagickKernel::separate(): array

Separa um conjunto vinculado de kernels e retorna um array de ImagickKernels.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

### Exemplos

Exemplo #1 Exemplo de ImagickKernel::separate()

    <?php

        function renderKernelTable($matrix) {

            $output = "<table class='infoTable'>";
            foreach ($matrix as $row) {
                $output .= "<tr>";
                foreach ($row as $cell) {
                    $output .= "<td style='text-align:left'>";
                    if ($cell === false) {
                        $output .= "false";
                    }
                    else {
                        $output .= round($cell, 3);
                    }
                    $output .= "</td>";
                }
                $output .= "</tr>";
            }

            $output .= "</table>";

            return $output;
        }

        $matrix = [
            [-1, 0, -1],
            [ 0, 4,  0],
            [-1, 0, -1],
        ];

        $kernel = \ImagickKernel::fromMatrix($matrix);
        $kernel->scale(4, \Imagick::NORMALIZE_KERNEL_VALUE);
        $diamondKernel = \ImagickKernel::fromBuiltIn(
            \Imagick::KERNEL_DIAMOND,
            "2"
        );

        $kernel->addKernel($diamondKernel);

        $kernelList = $kernel->separate();

        $output = '';
        $count = 0;
        foreach ($kernelList as $kernel) {
            $output .= "<br/>Kernel $count<br/>";
            $output .= renderKernelTable($kernel->getMatrix());
            $count++;
        }

        return $output;

    ?>

## Índice

- ImagickKernel::addKernel — Anexa outro kernel a uma lista de kernels
- ImagickKernel::addUnityKernel — Adiciona um Kernel Unity à lista de kernels
- ImagickKernel::fromBuiltIn — Cria um kernel a partir de um kernel integrado
- ImagickKernel::fromMatrix — Crie um kernel a partir de uma matriz 2D de valores
- ImagickKernel::getMatrix — Obtém a matriz 2D de valores usada neste kernel
- ImagickKernel::scale — Dimensiona uma lista de kernel pela quantidade especificada
- ImagickKernel::separate — Separa um conjunto vinculado de kernels e retorna um array de ImagickKernels

# A classe ImagickKernelException

(PECL imagick 3)

## Introdução

## Resumo da classe

class ImagickKernelException extends Exception {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
/* Métodos herdados */
}

# A classe ImagickPixel

(PECL imagick 2, PECL imagick 3)

## Resumo da classe

class ImagickPixel {
public function clear(): bool
public function __construct(string `$color` = ?)
public function destroy(): bool
public function getColor(int `$normalized` = 0): array
public function getColorAsString(): string
public function getColorCount(): int
public function getColorQuantum(): array
public function getColorValue(int `$color`): float
public function getColorValueQuantum(int `$color`): int|float
public function getHSL(): array
public function getIndex(): int
public function isPixelSimilar(ImagickPixel `$color`, float `$fuzz`): bool
public function isPixelSimilarQuantum(string `$color`, string `$fuzz` = ?): bool
public function isSimilar(ImagickPixel `$color`, float `$fuzz`): bool
public function setColor(string `$color`): bool
public function setcolorcount(int `$colorCount`): bool
public function setColorValue(int `$color`, float `$value`): bool
public function setColorValueQuantum(int `$color`, int|float `$value`): bool
public function setHSL(float `$hue`, float `$saturation`, float `$luminosity`): bool
public function setIndex(int `$index`): bool
}

# ImagickPixel::clear

(PECL imagick 2, PECL imagick 3)

ImagickPixel::clear — Limpa recursos associados a este objeto

### Descrição

public function ImagickPixel::clear(): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Limpa o objeto ImagickPixel, deixando-o em estado de novo. Isso também remove as definições de cor associadas ao objeto.

### Valor Retornado

Retorna `true` em caso de sucesso.

# ImagickPixel::__construct

(PECL imagick 2, PECL imagick 3)

ImagickPixel::__construct — O construtor de ImagickPixel

### Descrição

public function ImagickPixel::__construct(string `$color` = ?)
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Constrói um objeto ImagickPixel. Se uma cor for especificada, o objeto será construído e inicializado com essa cor antes de ser retornado.

### Parâmetros

`color`

  A string de cores opcional a ser usada como valor inicial deste objeto.

### Valor Retornado

Retorna um objeto ImagickPixel em caso de sucesso, lança uma ImagickPixelException em caso de falha.

### Exemplos

Exemplo #1 Exemplo de ImagickPixel::construct()

    <?php
    function construct() {

        $columns = 4;

        $exampleColors = array(
            "rgba(100%, 0%, 0%, 0.5)",
            "hsb(33.3333%, 100%,  75%)", // verde médio
            "hsl(120, 255,   191.25)", // verde médio
            "graya(50%, 0.5)", // cinza médio semi-transparente
            "LightCoral", "none", // "cmyk(0.9, 0.48, 0.83, 0.50)",
            "#f00", // #rgb
            "#ff0000", // #rrggbb
            "#ff0000ff", // #rrggbbaa
            "#ffff00000000", // #rrrrggggbbbb
            "#ffff00000000ffff", // #rrrrggggbbbbaaaa
            "rgb(255, 0, 0)", // um inteiro na faixa 0—255 para cada componente
            "rgb(100.0%, 0.0%, 0.0%)", // um float na faixa 0—100% para cada componente
            "rgb(255, 0, 0)", // faixa 0 - 255
            "rgba(255, 0, 0, 1.0)", // o mesmo, com um valor alfa explícito
            "rgb(100%, 0%, 0%)", // faixa 0.0% - 100.0%
            "rgba(100%, 0%, 0%, 1.0)", // o mesmo, com um valor alfa explícito
        );

        $draw = new \ImagickDraw();
        $count = 0;
        $black = new \ImagickPixel('rgb(0, 0, 0)');

        foreach ($exampleColors as $exampleColor) {
            $color = new \ImagickPixel($exampleColor);

            $draw->setstrokewidth(1.0);
            $draw->setStrokeColor($black);
            $draw->setFillColor($color);
            $offsetX = ($count % $columns) * 50 + 5;
            $offsetY = intval($count / $columns) * 50 + 5;
            $draw->rectangle(0 + $offsetX, 0 + $offsetY, 40 + $offsetX, 40 + $offsetY);
            $count++;
        }

        $image = new \Imagick();
        $image->newImage(350, 350, "blue");
        $image->setImageFormat("png");
        $image->drawImage($draw);
        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickPixel::destroy

(PECL imagick 2, PECL imagick 3)

ImagickPixel::destroy — Desaloca recursos associados a este objeto

### Descrição

public function ImagickPixel::destroy(): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desaloca quaisquer recursos usados ​​pelo objeto ImagickPixel e desativa qualquer cor associada. O objeto não deve ser usado após a função destroy() ter sido chamada.

### Valor Retornado

Retorna `true` em caso de sucesso.

# ImagickPixel::getColor

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getColor — Retorna a cor

### Descrição

public function ImagickPixel::getColor(int `$normalized` = 0): array

Retorna a cor descrita pelo objeto ImagickPixel, como um array. Se a cor tiver um canal de opacidade definido, ele será fornecido como o quarto valor da lista.

### Parâmetros

`normalized`

  Normaliza os valores de cor. Possíveis valores são `0`, `1` ou `2`.

  Lista de valores possíveis para `normalized`
  `normalized` | Descrição
  --- | ---
  `0` | Os valores RGB são retornados como int no intervalo `0` a `255` (inclusive). O valor alfa é retornado como int e pode ser `0` ou `1`.
  `1` | Os valores RGB são retornados como float no intervalo `0` a `1` (inclusive).
  `2` | Os valores RGB são retornados como int no intervalo `0` a `255` (inclusive).

### Valor Retornado

Um array de calores de canal. Lança uma ImagickPixelException em caso de erro.

### Exemplos

Exemplo #1 Uso básico de Imagick::getColor()

    <?php

    // Cria um ImagickPixel com a cor predefinida 'brown' (marrom)
    $color = new ImagickPixel('brown');

    // Define a cor com alfa de 25%
    $color->setColorValue(Imagick::COLOR_ALPHA, 64 / 256.0);

    $colorInfo = $color->getColor();

    echo "Valores padrão:".PHP_EOL;
    print_r($colorInfo);

    $colorInfo = $color->getColor(1);

    echo "Valores normalizados:".PHP_EOL;
    print_r($colorInfo);

    ?>

O exemplo acima produzirá:

    Valores padrão:
    Array
    (
        [r] => 165
        [g] => 42
        [b] => 42
        [a] => 0
    )
    Valores normalizados:
    Array
    (
        [r] => 0.64705882352941
        [g] => 0.16470588235294
        [b] => 0.16470588235294
        [a] => 0.25000381475547
    )

# ImagickPixel::getColorAsString

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

ImagickPixel::getColorAsString — Retorna a cor como uma string

### Descrição

public function ImagickPixel::getColorAsString(): string

Retorna a cor do objeto ImagickPixel como uma string.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a cor do objeto ImagickPixel como uma string.

### Exemplos

Exemplo #1 Uso básico de Imagick::getColorAsString()

    <?php

    // Cria um ImagickPixel com a cor predefinida 'brown' (marrom)
    $color = new ImagickPixel('brown');

    $color->setColorValue(Imagick::COLOR_ALPHA, 64 / 256.0);

    $colorInfo = $color->getColorAsString();

    print_r($colorInfo);
    ?>

O exemplo acima produzirá:

    rgb(165,42,42)

### Notas

> Nota: Alfa não retornado

> Esta função não retorna o valor alfa da cor na string.

# ImagickPixel::getColorCount

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getColorCount — Retorna a contagem de cores associada a esta cor

### Descrição

public function ImagickPixel::getColorCount(): int

Retorna a contagem de cores associada a esta cor.

A contagem de cores é o número de pixels na imagem que possuem a mesma cor deste ImagickPixel.

ImagickPixel::getColorCount parece funcionar apenas para objetos ImagickPixel criados por meio de Imagick::getImageHistogram()

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna a contagem de cores como um número inteiro em caso de sucesso, lança uma exceção ImagickPixelException em caso de falha.

### Exemplos

Exemplo #1 Exemplo de ImagickPixel::getColorCount()

    <?php
        $imagick = new \Imagick();
        $imagick->newPseudoImage(640, 480, "magick:logo");
        $histogramElements = $imagick->getImageHistogram();
        $lastColor = array_pop($histogramElements);
        echo "A última contagem de cores de pixel é: ".$lastColor->getColorCount();
    ?>

A saída para isso será semelhante a:

    A última contagem de cores de pixel é: 256244

# ImagickPixel::getColorQuantum

(No version information available, might only be in Git)

ImagickPixel::getColorQuantum — Retorna a cor do pixel em um array como valores Quantum

### Descrição

public function ImagickPixel::getColorQuantum(): array

Retorna a cor do pixel em um array como valores Quantum. Se o ImageMagick foi compilado como HDRI, eles serão em ponto flutuante, caso contrário, serão inteiros.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array com chaves `"r"`, `"g"`, `"b"` e `"a"`.

# ImagickPixel::getColorValue

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getColorValue — Obtém o valor normalizado do canal de cores fornecido

### Descrição

public function ImagickPixel::getColorValue(int `$color`): float

Recupera o valor do canal de cores especificado, como um número de ponto flutuante entre 0 e 1.

### Parâmetros

`color`

  A cor cujo valor será obtido, especificada como uma das constantes de cor do Imagick. Pode ser uma das cores RGB, cores CMYK, alfa e opacidade, por exemplo (Imagick::COLOR_BLUE, Imagick::COLOR_MAGENTA).

### Valor Retornado

O valor do canal, como um número de ponto flutuante normalizado, lançando uma ImagickPixelException em caso de erro.

### Exemplos

Exemplo #1 Uso básico de Imagick::getColorValue()

    <?php

    $color = new ImagickPixel('rgba(90%, 20%, 20%, 0.75)');

    echo "Valor de alfa é ".$color->getColorValue(Imagick::COLOR_ALPHA).PHP_EOL;
    echo "".PHP_EOL;
    echo "Valor de vermelho é ".$color->getColorValue(Imagick::COLOR_RED).PHP_EOL;
    echo "Valor de verde é ".$color->getColorValue(Imagick::COLOR_GREEN).PHP_EOL;
    echo "Valor de azul é ".$color->getColorValue(Imagick::COLOR_BLUE).PHP_EOL;
    echo "".PHP_EOL;
    echo "Valor de ciano é ".$color->getColorValue(Imagick::COLOR_CYAN).PHP_EOL;
    echo "Valor de magenta é ".$color->getColorValue(Imagick::COLOR_MAGENTA).PHP_EOL;
    echo "Valor de amarelo é ".$color->getColorValue(Imagick::COLOR_YELLOW).PHP_EOL;
    echo "Valor de preto é ".$color->getColorValue(Imagick::COLOR_BLACK).PHP_EOL;

    ?>

O exemplo acima produzirá:

    Valor de alfa é 0.74999618524453

    Valor de vermelho é 0.90000762951095
    Valor de verde é 0.2
    Valor de azul é 0.2

    Valor de ciano é 0.90000762951095
    Valor de magenta é 0.2
    Valor de amarelo é 0.2
    Valor de preto é 0

# ImagickPixel::getColorValueQuantum

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickPixel::getColorValueQuantum — Obtém o valor Quantum de uma cor no ImagickPixel

### Descrição

public function ImagickPixel::getColorValueQuantum(int `$color`): int|float

Obtém o valor Quantum de uma cor no ImagickPixel. O valor de retorno é em ponto flutuante se o ImageMagick foi compilado com HDRI, caso contrário, é um número inteiro.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O valor Quantum do elemento de cor. Float se o ImageMagick foi compilado com HDRI, caso contrário, um int.

### Exemplos

Exemplo #1 ImagickPixel::getColorValueQuantum()

    <?php
        $color = new \ImagickPixel('rgb(128, 5, 255)');
        $colorRed = $color->getColorValueQuantum(\Imagick::COLOR_RED);
        $colorGreen = $color->getColorValueQuantum(\Imagick::COLOR_GREEN);
        $colorBlue = $color->getColorValueQuantum(\Imagick::COLOR_BLUE);
        $colorAlpha = $color->getColorValueQuantum(\Imagick::COLOR_ALPHA);

        printf(
            "Vermelho: %s Verde: %s  Azul %s Alfa: %s",
            $colorRed,
            $colorGreen,
            $colorBlue,
            $colorAlpha
        );

    ?>

# ImagickPixel::getHSL

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getHSL — Retorna a cor HSL normalizada do objeto ImagickPixel

### Descrição

public function ImagickPixel::getHSL(): array

Retorna a cor HSL normalizada descrita pelo objeto ImagickPixel, com cada um dos três valores como números de ponto flutuante entre 0.0 e 1.0.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o valor HSL em um array com as chaves "hue" (matiz), "saturation" (saturação) e "luminosity" (luminosidade). Lança uma ImagickPixelException em caso de falha.

### Exemplos

Exemplo #1 Exemplo básico de Imagick::getHSL()

    <?php

    $color = new ImagickPixel('rgb(90%, 10%, 10%)');

    $colorInfo = $color->getHSL();

    print_r($colorInfo);

    ?>

O exemplo acima produzirá:

    Array
    (
        [hue] => 0
        [saturation] => 0.80001220740379
        [luminosity] => 0.50000762951095
    )

### Notas

> Nota:

> Disponível com a biblioteca ImageMagick versão 6.2.9 e superiores.

# ImagickPixel::getIndex

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickPixel::getIndex — Obtém o índice do mapa de cores da varinha de pixel

### Descrição

public function ImagickPixel::getIndex(): int

Obtém o índice do mapa de cores da varinha de pixel.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

# ImagickPixel::isPixelSimilar

(PECL imagick 3 >= 3.3.0)

ImagickPixel::isPixelSimilar — Verifica a distância entre esta cor e uma outra

### Descrição

public function ImagickPixel::isPixelSimilar(ImagickPixel `$color`, float `$fuzz`): bool

Verifica a distância entre a cor descrita por este objeto ImagickPixel e a do objeto fornecido, traçando seus valores RGB no cubo de cores. Se a distância entre os dois pontos for menor que o valor de fuzz fornecido, as cores serão semelhantes. Este método substitui ImagickPixel::isSimilar() e normaliza corretamente o valor fuzz para o QuantumRange do ImageMagick.

### Parâmetros

`color`

  O objeto ImagickPixel para comparar com este objeto.

`fuzz`

  A distância máxima dentro da qual estas cores serão consideradas similares. O máximo teórico para este valor é a raiz quadrada de três (1.732).

### Valor Retornado

Retorna `true` em caso de sucesso.

# ImagickPixel::isPixelSimilarQuantum

(PECL imagick 3 >= 3.3.0)

ImagickPixel::isPixelSimilarQuantum — Retorna se duas cores diferem em menos que a distância especificada

### Descrição

public function ImagickPixel::isPixelSimilarQuantum(string `$color`, string `$fuzz` = ?): bool

Retornará TRUE se a distância entre duas cores for menor que a distância especificada. O valor fuzz deve estar no intervalo 0-QuantumRange. O valor máximo representa a maior distância possível no espaço de cores. Por exemplo, de RGB(0, 0, 0) a RGB(255, 255, 255) para o espaço de cores RGB.

### Parâmetros

`color`

`fuzz`

### Valor Retornado

# ImagickPixel::isSimilar

(PECL imagick 2, PECL imagick 3)

ImagickPixel::isSimilar — Verifica a distância entre esta cor e uma outra

### Descrição

public function ImagickPixel::isSimilar(ImagickPixel `$color`, float `$fuzz`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Verifica a distância entre a cor descrita por este objeto ImagickPixel e a do objeto fornecido, traçando seus valores RGB no cubo de cores. Se a distância entre os dois pontos for menor que o valor de fuzz fornecido, as cores serão semelhantes. Preterida em favor de ImagickPixel::isPixelSimilar().

### Parâmetros

`color`

  O objeto ImagickPixel para comparar com este objeto.

`fuzz`

  A distância máxima dentro da qual estas cores serão consideradas similares. O máximo teórico para este valor é a raiz quadrada de três (1.732).

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de ImagickPixel::isSimilar()

    <?php
            // Os testes abaixo são escritos com a distância máxima expressa como 255,
            // portanto é necessário dimensioná-los pela raiz quadrada de 3 - o comprimento diagonal
            // de um cubo unitário.
            $root3 = 1.732050807568877;

            $tests = array(
                ['rgb(245, 0, 0)',      'rgb(255, 0, 0)',   9 / $root3,         false,],
                ['rgb(245, 0, 0)',      'rgb(255, 0, 0)',  10 / $root3,         true,],
                ['rgb(0, 0, 0)',        'rgb(7, 7, 0)',     9 / $root3,         false,],
                ['rgb(0, 0, 0)',        'rgb(7, 7, 0)',    10 / $root3,         true,],
                ['rgba(0, 0, 0, 1)',    'rgba(7, 7, 0, 1)', 9 / $root3,         false,],
                ['rgba(0, 0, 0, 1)',    'rgba(7, 7, 0, 1)',    10 / $root3,     true,],
                ['rgb(128, 128, 128)',  'rgb(128, 128, 120)',   7 / $root3,     false,],
                ['rgb(128, 128, 128)',  'rgb(128, 128, 120)',   8 / $root3,     true,],
                ['rgb(0, 0, 0)',        'rgb(255, 255, 255)',   254.9,          false,],
                ['rgb(0, 0, 0)',        'rgb(255, 255, 255)',   255,            true,],
                ['rgb(255, 0, 0)',      'rgb(0, 255, 255)',     254.9,          false,],
                ['rgb(255, 0, 0)',      'rgb(0, 255, 255)',     255,            true,],
                ['black',               'rgba(0, 0, 0)',        0.0,            true],
                ['black',               'rgba(10, 0, 0, 1.0)',  10.0 / $root3,  true],);

            $output = "<table width='100%' class='infoTable'><thead>
                    <tr>
                    <th>
                    Cor 1
                    </th>
                    <th>
                    Cor 2
                    </th>
                    <th>
                        Distância de teste * 255
                    </th>
                    <th>
                        Está dentro da distância
                    </th>
                    </tr>
            </thead>";

            $output .= "<tbody>";

            foreach ($tests as $testInfo) {
                $color1 = $testInfo[0];
                $color2 = $testInfo[1];
                $distance = $testInfo[2];
                $expectation = $testInfo[3];
                $testDistance = ($distance / 255.0);

                $color1Pixel = new \ImagickPixel($color1);
                $color2Pixel = new \ImagickPixel($color2);

                $isSimilar = $color1Pixel->isPixelSimilar($color2Pixel, $testDistance);

                if ($isSimilar !== $expectation) {
                    echo "Distância de teste falhou. Cor [$color1] comparada com cor [$color2] não está dentro da distância $testDistance, FALHOU.".NL;
                }

                $layout = "<tr>
                    <td>%s</td>
                    <td>%s</td>
                    <td>%s</td>
                    <td style='text-align: center;'>%s</td>
                </tr>";

                $output .= sprintf(
                    $layout,
                    $color1,
                    $color2,
                    $distance,
                    $isSimilar ? 'sim' : 'não'
                );
            }

            $output .= "</tbody></table>";

            return $output;

    ?>

# ImagickPixel::setColor

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setColor — Define a cor

### Descrição

public function ImagickPixel::setColor(string `$color`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Define a cor descrita pelo objeto ImagickPixel, com uma string (por exemplo, "blue", "#0000ff", "rgb(0,0,255)", "cmyk(100,100,100,10)", etc.).

### Parâmetros

`color`

  A definição de cor a ser usada para inicializar o objeto ImagickPixel.

### Valor Retornado

Retorna `true` se a cor especificada foi definida, `false` caso contrário.

### Exemplos

Exemplo #1 Exemplo de ImagickPixel::setColor()

    <?php
    function setColor() {
        $draw = new \ImagickDraw();

        $strokeColor = new \ImagickPixel('green');
        $fillColor = new \ImagickPixel();
        $fillColor->setColor('rgba(100%, 75%, 0%, 1.0)');

        $draw->setstrokewidth(3.0);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->rectangle(200, 200, 300, 300);

        $image = new \Imagick();
        $image->newImage(500, 500, "SteelBlue2");
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickPixel::setColorCount

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setColorCount — Define a contagem de cores associada a esta cor

### Descrição

public function ImagickPixel::setcolorcount(int `$colorCount`): bool

Define a contagem de cores associada a esta cor.

### Parâmetros

`colorCount`

### Valor Retornado

Retorna `true` em caso de sucesso.

# ImagickPixel::setColorValue

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setColorValue — Define o valor normalizado de um dos canais

### Descrição

public function ImagickPixel::setColorValue(int `$color`, float `$value`): bool

Define o valor do canal especificado deste objeto para o valor fornecido, que deve estar entre 0 e 1. Esta função pode ser usada para fornecer um canal de opacidade a um objeto ImagickPixel.

### Parâmetros

`color`

  Uma das constantes de cor Imagick, ex.: \Imagick::COLOR_GREEN ou \Imagick::COLOR_ALPHA.

`value`

  O valor para o qual este canal será definido, numa faixa de 0 a 1.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Uso básico de Imagick::setColorValue()

    <?php

    $color  = new \ImagickPixel('firebrick');

    $color->setColorValue(Imagick::COLOR_ALPHA, 0.5);

    print_r($color->getcolor(true));
    ?>

O exemplo acima produzirá:

    Array
    (
        [r] => 0.69803921568627
        [g] => 0.13333333333333
        [b] => 0.13333333333333
        [a] => 0.50000762951095
    )

# ImagickPixel::setColorValueQuantum

(PECL imagick 2 >=2.3.0, PECL imagick 3)

ImagickPixel::setColorValueQuantum — Define o valor Quantum de um elemento de cor do ImagickPixel

### Descrição

public function ImagickPixel::setColorValueQuantum(int `$color`, int|float `$value`): bool

Define o valor Quantum de um elemento de cor do ImagickPixel.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`color`

  Que elemento de cor será definido ex.: \Imagick::COLOR_GREEN.

`value`

  O valor Quantum para definir o elemento de cor. Deve ser um float se o ImageMagick foi compilado com HDRI, caso contrário, um int no intervalo de 0 a Imagick::getQuantum().

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 ImagickPixel::setColorValueQuantum()

    <?php
    function setColorValueQuantum() {
        $image = new \Imagick();

        $quantumRange = $image->getQuantumRange();

        $draw = new \ImagickDraw();
        $color = new \ImagickPixel('blue');
        $color->setcolorValueQuantum(\Imagick::COLOR_RED, 128 * $quantumRange['quantumRangeLong'] / 256);

        $draw->setstrokewidth(1.0);
        $draw->setStrokeColor($color);
        $draw->setFillColor($color);
        $draw->rectangle(200, 200, 300, 300);

        $image->newImage(500, 500, "SteelBlue2");
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickPixel::setHSL

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setHSL — Define a cor HSL normalizada

### Descrição

public function ImagickPixel::setHSL(float `$hue`, float `$saturation`, float `$luminosity`): bool

Define a cor descrita pelo objeto ImagickPixel usando valores normalizados para matiz, saturação e luminosidade.

### Parâmetros

`hue`

  O valor normalizado para matiz, descrito como um arco fracionário (entre 0 e 1) do círculo de matiz, onde o valor zero é vermelho.

`saturation`

  O valor normalizado para saturação, com 1 como saturação total.

`luminosity`

  O valor normalizado para luminosidade, em uma escala de preto em 0 a branco em 1, com o valor HS total em luminosidade 0.5.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Use ImagickPixel::setHSL() para modificar uma cor

    <?php

    // Cria uma cor vermelha quase pura
    $color = new ImagickPixel('rgb(90%, 10%, 10%)');

    // Obtém seus valores HSL
    $colorInfo = $color->getHSL();

    // Rotaciona o matiz em 180 graus
    $newHue = $colorInfo['hue'] + 0.5;
    if ($newHue > 1) {
        $newHue = $newHue - 1;
    }

    // Define o ImagickPixel com a nova cor
    $colorInfo = $color->setHSL($newHue, $colorInfo['saturation'], $colorInfo['luminosity']);

    // Verifica se a nova cor é azul/verde
    $colorInfo = $color->getcolor();
    print_r($colorInfo);

    ?>

O exemplo acima produzirá:

    Array
    (
        [r] => 26
        [g] => 230
        [b] => 230
        [a] => 255
    )

### Notas

> Nota:

> Disponível com a biblioteca ImageMagick versão 6.2.9 e superiores.

# ImagickPixel::setIndex

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickPixel::setIndex — Define o índice do mapa de cores da varinha de pixel

### Descrição

public function ImagickPixel::setIndex(int `$index`): bool

Define o índice do mapa de cores da varinha de pixel.

### Parâmetros

`index`

### Valor Retornado

Retorna `true` em caso de sucesso.

## Índice

- ImagickPixel::clear — Limpa recursos associados a este objeto
- ImagickPixel::__construct — O construtor de ImagickPixel
- ImagickPixel::destroy — Desaloca recursos associados a este objeto
- ImagickPixel::getColor — Retorna a cor
- ImagickPixel::getColorAsString — Retorna a cor como uma string
- ImagickPixel::getColorCount — Retorna a contagem de cores associada a esta cor
- ImagickPixel::getColorQuantum — Retorna a cor do pixel em um array como valores Quantum
- ImagickPixel::getColorValue — Obtém o valor normalizado do canal de cores fornecido
- ImagickPixel::getColorValueQuantum — Obtém o valor Quantum de uma cor no ImagickPixel
- ImagickPixel::getHSL — Retorna a cor HSL normalizada do objeto ImagickPixel
- ImagickPixel::getIndex — Obtém o índice do mapa de cores da varinha de pixel
- ImagickPixel::isPixelSimilar — Verifica a distância entre esta cor e uma outra
- ImagickPixel::isPixelSimilarQuantum — Retorna se duas cores diferem em menos que a distância especificada
- ImagickPixel::isSimilar — Verifica a distância entre esta cor e uma outra
- ImagickPixel::setColor — Define a cor
- ImagickPixel::setColorCount — Define a contagem de cores associada a esta cor
- ImagickPixel::setColorValue — Define o valor normalizado de um dos canais
- ImagickPixel::setColorValueQuantum — Define o valor Quantum de um elemento de cor do ImagickPixel
- ImagickPixel::setHSL — Define a cor HSL normalizada
- ImagickPixel::setIndex — Define o índice do mapa de cores da varinha de pixel

# A classe ImagickPixelException

(PECL imagick 3)

## Introdução

## Resumo da classe

class ImagickPixelException extends Exception implements Throwable {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
/* Métodos herdados */
}

# A classe ImagickPixelIterator

(PECL imagick 2, PECL imagick 3)

## Resumo da classe

class ImagickPixelIterator {
public function clear(): bool
public function __construct(Imagick `$wand`)
public function destroy(): bool
public function getCurrentIteratorRow(): array
public function getIteratorRow(): int
public function getNextIteratorRow(): array
public function getPreviousIteratorRow(): array
public function newPixelIterator(Imagick `$wand`): bool
public function newPixelRegionIterator(
Imagick `$wand`,
int `$x`,
int `$y`,
int `$columns`,
int `$rows`
): bool
public function resetIterator(): bool
public function setIteratorFirstRow(): bool
public function setIteratorLastRow(): bool
public function setIteratorRow(int `$row`): bool
public function syncIterator(): bool
}

# ImagickPixelIterator::clear

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::clear — Limpa recursos associados a um PixelIterator

### Descrição

public function ImagickPixelIterator::clear(): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Limpa recursos associados a um PixelIterator.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de ImagickPixelIterator::clear()

    <?php
    function clear($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));

        $imageIterator = $imagick->getPixelRegionIterator(100, 100, 250, 200);

        /* Itera sobre as linhas de pixels */
        foreach ($imageIterator as $pixels) {
            /** @var $pixel \ImagickPixel */
            /* Itera sobre os pixels na linha (colunas) */
            foreach ($pixels as $column => $pixel) {
                if ($column % 2) {
                    /* Pinta cada segundo pixel de preto */
                    $pixel->setColor("rgba(0, 0, 0, 0)");
                }
            }
            /* Sincroniza o iterador, importante fazer isso a cada iteração */
            $imageIterator->syncIterator();
        }

        $imageIterator->clear();

        header("Content-Type: image/jpg");
        echo $imagick;
    }

    ?>

# ImagickPixelIterator::__construct

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::__construct — O construtor de ImagickPixelIterator

### Descrição

public function ImagickPixelIterator::__construct(Imagick `$wand`)
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

O construtor de ImagickPixelIterator

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de ImagickPixelIterator::construct()

    <?php
    function construct($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imageIterator = new \ImagickPixelIterator($imagick);

        /* Itera sobre linhas de pixels */
        foreach ($imageIterator as $pixels) {
            /* Itera sobre os pixels na linha (colunas) */
            foreach ($pixels as $column => $pixel) {
                /** @var $pixel \ImagickPixel */
                if ($column % 2) {
                    /* Pinta cada segundo pixel de preto */
                    $pixel->setColor("rgba(0, 0, 0, 0)");
                }
            }
            /* Sincroniza o iterador, importante fazer isso a cada iteração */
            $imageIterator->syncIterator();
        }

        header("Content-Type: image/jpg");
        echo $imagick;
    }

    ?>

# ImagickPixelIterator::destroy

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::destroy — Desaloca recursos associados a um PixelIterator

### Descrição

public function ImagickPixelIterator::destroy(): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Desaloca recursos associados a um PixelIterator.

### Valor Retornado

Retorna `true` em caso de sucesso.

# ImagickPixelIterator::getCurrentIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getCurrentIteratorRow — Retorna a linha atual de objetos ImagickPixel

### Descrição

public function ImagickPixelIterator::getCurrentIteratorRow(): array
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna a linha atual como um array de objetos ImagickPixel do iterador de pixel.

### Valor Retornado

Retorna uma linha como um array de objetos ImagickPixel que podem ser iterados.

# ImagickPixelIterator::getIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getIteratorRow — Retorna a linha atual do iterador de pixel

### Descrição

public function ImagickPixelIterator::getIteratorRow(): int
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna a linha atual do iterador de pixel.

### Valor Retornado

Retorna a posição da linha como um inteiro, lançando uma ImagickPixelIteratorException em caso de erro.

# ImagickPixelIterator::getNextIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getNextIteratorRow — Retorna a próxima linha do iterador de pixel

### Descrição

public function ImagickPixelIterator::getNextIteratorRow(): array
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna a próxima linha como um array de varinhas de pixels do iterador de pixels.

### Valor Retornado

Retorna a próxima linha como um array de objetos ImagickPixel, lançando uma ImagickPixelIteratorException em caso de erro.

### Exemplos

Exemplo #1 Exemplo de ImagickPixelIterator::getNextIteratorRow()

    <?php
    function getNextIteratorRow($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imageIterator = $imagick->getPixelIterator();

        $count = 0;
        while ($pixels = $imageIterator->getNextIteratorRow()) {
            if (($count % 3) == 0) {
                /* Itera sobre os pixels na linha (colunas) */
                foreach ($pixels as $column => $pixel) {
                    /** @var $pixel \ImagickPixel */
                    if ($column % 2) {
                        /* Pinta cada segundo pixel de preto */
                        $pixel->setColor("rgba(0, 0, 0, 0)");
                    }
                }
                /* Sincroniza o iterador, importante fazer isso a cada iteração */
                $imageIterator->syncIterator();
            }

            $count += 1;
        }

        header("Content-Type: image/jpg");
        echo $imagick;
    }

    ?>

# ImagickPixelIterator::getPreviousIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getPreviousIteratorRow — Retorna a linha anterior

### Descrição

public function ImagickPixelIterator::getPreviousIteratorRow(): array
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna a linha anterior como um array de varinhas de pixels do iterador de pixels.

### Valor Retornado

Retorna a linha anterior como um array de objetos ImagickPixelWand do ImagickPixelIterator, lançando uma ImagickPixelIteratorException em caso de erro.

# ImagickPixelIterator::newPixelIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::newPixelIterator — Retorna um novo iterador de pixel

### Descrição

public function ImagickPixelIterator::newPixelIterator(Imagick `$wand`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna um novo iterador de pixel.

### Valor Retornado

Retorna `true` em caso de sucesso. lançando uma ImagickPixelIteratorException em caso de erro.

# ImagickPixelIterator::newPixelRegionIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::newPixelRegionIterator — Retorna um novo iterador de pixel

### Descrição

public function ImagickPixelIterator::newPixelRegionIterator(
Imagick `$wand`,
int `$x`,
int `$y`,
int `$columns`,
int `$rows`
): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Retorna um novo iterador de pixel.

### Parâmetros

`wand`

`x`

`y`

`columns`

`rows`

### Valor Retornado

Retorna um novo ImagickPixelIterator em caso de sucesso; em caso de falha, lança uma ImagickPixelIteratorException.

# ImagickPixelIterator::resetIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::resetIterator — Redefine o iterador de pixel

### Descrição

public function ImagickPixelIterator::resetIterator(): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Redefine o iterador de pixel. Use-o em conjunto com ImagickPixelIterator::getNextIteratorRow() para iterar sobre todos os pixels em um contêiner de pixels.

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de ImagickPixelIterator::resetIterator()

    <?php
    function resetIterator($imagePath) {

        $imagick = new \Imagick(realpath($imagePath));

        $imageIterator = $imagick->getPixelIterator();

        /* Itera sobre linhas de pixels */
        foreach ($imageIterator as $pixels) {
            /* Itera sobre os pixels na linha (colunas) */
            foreach ($pixels as $column => $pixel) {
                /** @var $pixel \ImagickPixel */
                if ($column % 2) {

                    /* Torna cada segundo pixel vermelho 25% */
                    $pixel->setColorValue(\Imagick::COLOR_RED, 64);
                }
            }
            /* Sincroniza o iterador, importante fazer isso a cada iteração */
            $imageIterator->syncIterator();
        }

        $imageIterator->resetiterator();

        /* Itera sobre linhas de pixels */
        foreach ($imageIterator as $pixels) {
            /* Itera sobre os pixels na linha (colunas) */
            foreach ($pixels as $column => $pixel) {
                /** @var $pixel \ImagickPixel */
                if ($column % 3) {
                    $pixel->setColorValue(\Imagick::COLOR_BLUE, 64); /* Torna cada segundo pixel um pouco azul */
                    //$pixel->setColor("rgba(0, 0, 128, 0)"); /* Pinta cada segundo pixel de preto */
                }
            }
            $imageIterator->syncIterator(); /* Sincroniza o iterador, importante fazer isso a cada iteração */
        }

        $imageIterator->clear();

        header("Content-Type: image/jpg");
        echo $imagick;
    }

    ?>

# ImagickPixelIterator::setIteratorFirstRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::setIteratorFirstRow — Define o iterador de pixels para a primeira linha de pixels

### Descrição

public function ImagickPixelIterator::setIteratorFirstRow(): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Define o iterador de pixels para a primeira linha de pixels.

### Valor Retornado

Retorna `true` em caso de sucesso.

# ImagickPixelIterator::setIteratorLastRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::setIteratorLastRow — Define o iterador de pixels para a última linha de pixels

### Descrição

public function ImagickPixelIterator::setIteratorLastRow(): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Define o iterador de pixels para a última linha de pixels.

### Valor Retornado

Retorna `true` em caso de sucesso.

# ImagickPixelIterator::setIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::setIteratorRow — Define a linha do iterador de pixel

### Descrição

public function ImagickPixelIterator::setIteratorRow(int `$row`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Define a linha do iterador de pixel.

### Parâmetros

`row`

### Valor Retornado

Retorna `true` em caso de sucesso.

### Exemplos

Exemplo #1 Exemplo de ImagickPixelIterator::setIteratorRow()

    <?php
    function setIteratorRow($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imageIterator = $imagick->getPixelRegionIterator(200, 100, 200, 200);

        for ($x = 0; $x < 20; $x++) {
            $imageIterator->setIteratorRow($x * 5);
            $pixels = $imageIterator->getCurrentIteratorRow();
            /* Itera sobre os pixels na linha (colunas) */
            foreach ($pixels as $pixel) {
                /** @var $pixel \ImagickPixel */
                /* Pinta cada segundo pixel de preto */
                $pixel->setColor("rgba(0, 0, 0, 0)");
            }

            /* Sincroniza o iterador, importante fazer isso a cada iteração */
            $imageIterator->syncIterator();
        }

        header("Content-Type: image/jpg");
        echo $imagick;
    }

    ?>

# ImagickPixelIterator::syncIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::syncIterator — Sincroniza o iterador de pixel

### Descrição

public function ImagickPixelIterator::syncIterator(): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

Sincroniza o iterador de pixel.

### Valor Retornado

Retorna `true` em caso de sucesso.

## Índice

- ImagickPixelIterator::clear — Limpa recursos associados a um PixelIterator
- ImagickPixelIterator::__construct — O construtor de ImagickPixelIterator
- ImagickPixelIterator::destroy — Desaloca recursos associados a um PixelIterator
- ImagickPixelIterator::getCurrentIteratorRow — Retorna a linha atual de objetos ImagickPixel
- ImagickPixelIterator::getIteratorRow — Retorna a linha atual do iterador de pixel
- ImagickPixelIterator::getNextIteratorRow — Retorna a próxima linha do iterador de pixel
- ImagickPixelIterator::getPreviousIteratorRow — Retorna a linha anterior
- ImagickPixelIterator::newPixelIterator — Retorna um novo iterador de pixel
- ImagickPixelIterator::newPixelRegionIterator — Retorna um novo iterador de pixel
- ImagickPixelIterator::resetIterator — Redefine o iterador de pixel
- ImagickPixelIterator::setIteratorFirstRow — Define o iterador de pixels para a primeira linha de pixels
- ImagickPixelIterator::setIteratorLastRow — Define o iterador de pixels para a última linha de pixels
- ImagickPixelIterator::setIteratorRow — Define a linha do iterador de pixel
- ImagickPixelIterator::syncIterator — Sincroniza o iterador de pixel

# A classe ImagickPixelIteratorException

(PECL imagick 3)

## Introdução

## Resumo da classe

class ImagickPixelIteratorException extends Exception implements Throwable {
/* Propriedades herdadas */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Métodos */
/* Métodos herdados */
}

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
- Constantes predefinidas
- Exemplos
  - Uso básico
- Imagick — A classe Imagick
  - Imagick::adaptiveBlurImage — Adiciona filtro de desfoque adaptável à imagem
  - Imagick::adaptiveResizeImage — Redimensiona imagem de forma adaptativa com triangulação dependente de dados
  - Imagick::adaptiveSharpenImage — Aumenta a nitidez da imagem de forma adaptativa
  - Imagick::adaptiveThresholdImage — Seleciona um limite para cada pixel com base em uma faixa de intensidade
  - Imagick::addImage — Adiciona nova imagem à lista de imagens de objetos Imagick
  - Imagick::addNoiseImage — Adiciona ruído aleatório à imagem
  - Imagick::affineTransformImage — Transforma uma imagem
  - Imagick::animateImages — Anima uma imagem ou imagens
  - Imagick::annotateImage — Cria anotação em uma imagem com texto
  - Imagick::appendImages — Anexa um conjunto de imagens
  - Imagick::autoLevelImage — Ajusta os níveis de um canal de imagem específico
  - Imagick::averageImages — Tira a média de um conjunto de imagens
  - Imagick::blackThresholdImage — Força todos os pixels abaixo do limite para preto
  - Imagick::blueShiftImage — Silencia as cores da imagem
  - Imagick::blurImage — Adiciona filtro de desfoque à imagem
  - Imagick::borderImage — Envolve a imagem com uma borda
  - Imagick::brightnessContrastImage — Altera o brilho e/ou contraste de uma imagem
  - Imagick::charcoalImage — Simula um desenho a carvão
  - Imagick::chopImage — Remove uma região de uma imagem e corta
  - Imagick::clampImage — Restringe a faixa de cores de 0 à profundidade do Quantum
  - Imagick::clear — Limpa todos os recursos associados ao objeto Imagick
  - Imagick::clipImage — Recorta ao longo do primeiro caminho do perfil 8BIM
  - Imagick::clipImagePath — Recorta ao longo dos caminhos nomeados do perfil 8BIM, se presente
  - Imagick::clipPathImage — Recorta ao longo dos caminhos nomeados do perfil 8BIM
  - Imagick::clone — Faz uma cópia exata do objeto Imagick
  - Imagick::clutImage — Substitui cores na imagem
  - Imagick::coalesceImages — Compõe um conjunto de imagens
  - Imagick::colorFloodfillImage — Altera o valor da cor de qualquer pixel que corresponda ao alvo
  - Imagick::colorizeImage — Mescla a cor de preenchimento com a imagem
  - Imagick::colorMatrixImage — Aplica transformação de cores a uma imagem
  - Imagick::combineImages — Combina uma ou mais imagens em uma única imagem
  - Imagick::commentImage — Adiciona um comentário à sua imagem
  - Imagick::compareImageChannels — Retorna a diferença em uma ou mais imagens
  - Imagick::compareImageLayers — Retorna a região delimitadora máxima entre imagens
  - Imagick::compareImages — Compara uma imagem com uma imagem reconstruída
  - Imagick::compositeImage — Compor uma imagem em outra
  - Imagick::__construct — O construtor Imagick
  - Imagick::contrastImage — Altera o contraste da imagem
  - Imagick::contrastStretchImage — Melhora o contraste de uma imagem colorida
  - Imagick::convolveImage — Aplica um kernel de convolução personalizado à imagem
  - Imagick::count — Obtém o número de imagens
  - Imagick::cropImage — Extrai uma região da imagem
  - Imagick::cropThumbnailImage — Cria uma miniatura de recorte
  - Imagick::current — Retorna uma referência ao objeto Imagick atual
  - Imagick::cycleColormapImage — Desloca o mapa de cores de uma imagem
  - Imagick::decipherImage — Decifra uma imagem
  - Imagick::deconstructImages — Retorna certas diferenças de pixels entre imagens
  - Imagick::deleteImageArtifact — Excluir artefato de imagem
  - Imagick::deleteImageProperty — Exclui uma propriedade de imagem
  - Imagick::deskewImage — Remove distorção da imagem
  - Imagick::despeckleImage — Reduz o ruído pontilhado em uma imagem
  - Imagick::destroy — Destrói o objeto Imagick
  - Imagick::displayImage — Exibe uma imagem
  - Imagick::displayImages — Exibe uma imagem ou sequência de imagens
  - Imagick::distortImage — Distorce uma imagem usando vários métodos de distorção
  - Imagick::drawImage — Renderiza o objeto ImagickDraw na imagem atual
  - Imagick::edgeImage — Melhora as bordas da imagem
  - Imagick::embossImage — Retorna uma imagem em tons de cinza com efeito tridimensional
  - Imagick::encipherImage — Cifra uma imagem
  - Imagick::enhanceImage — Melhora a qualidade de uma imagem com ruído
  - Imagick::equalizeImage — Equaliza o histograma da imagem
  - Imagick::evaluateImage — Aplica uma expressão a uma imagem
  - Imagick::exportImagePixels — Exporta os pixels da imagem não processada
  - Imagick::extentImage — Define tamanho da imagem
  - Imagick::filter — Aplica um kernel de convolução personalizado à imagem
  - Imagick::flattenImages — Mescla uma sequência de imagens
  - Imagick::flipImage — Cria uma imagem espelhada vertical
  - Imagick::floodFillPaintImage — Altera o valor da cor de qualquer pixel que corresponda ao alvo
  - Imagick::flopImage — Cria uma imagem espelhada horizontal
  - Imagick::forwardFourierTransformImage — Implementa a transformada discreta de Fourier (DFT)
  - Imagick::frameImage — Adiciona uma borda tridimensional simulada
  - Imagick::functionImage — Aplica uma função na imagem
  - Imagick::fxImage — Avalia uma expressão para cada pixel da imagem
  - Imagick::gammaImage — Corrige o gama de uma imagem
  - Imagick::gaussianBlurImage — Desfoca uma imagem
  - Imagick::getColorspace — Obtém o espaço de cores
  - Imagick::getCompression — Obtém o tipo de compactação do objeto
  - Imagick::getCompressionQuality — Obtém a qualidade de compactação do objeto
  - Imagick::getCopyright — Retorna os direitos autorais da API ImageMagick como uma string
  - Imagick::getFilename — Obtém o nome do arquivo associado a uma sequência de imagens
  - Imagick::getFont — Obtem a fonte
  - Imagick::getFormat — Retorna o formato do objeto Imagick
  - Imagick::getGravity — Obtém a gravidade
  - Imagick::getHomeURL — Retorna o URL da página do ImageMagick
  - Imagick::getImage — Retorna um novo objeto Imagick
  - Imagick::getImageAlphaChannel — Verifica se a imagem tem um canal alfa
  - Imagick::getImageArtifact — Obtém artefato da imagem
  - Imagick::getImageAttribute — Retorna um atributo nomeado
  - Imagick::getImageBackgroundColor — Retorna a cor de fundo a imagem
  - Imagick::getImageBlob — Retorna a sequência de imagem como um BLOB
  - Imagick::getImageBluePrimary — Retorna o ponto primário azul da cromaticidade
  - Imagick::getImageBorderColor — Retorna a cor da borda da imagem
  - Imagick::getImageChannelDepth — Obtém a profundidade de um canal de imagem específico
  - Imagick::getImageChannelDistortion — Compara canais de uma imagem com uma imagem reconstruída
  - Imagick::getImageChannelDistortions — Obtém distorções de canal
  - Imagick::getImageChannelExtrema — Obtém os extremos de um ou mais canais de imagem
  - Imagick::getImageChannelKurtosis — Obtenha a curtose e a assimetria de um canal específico
  - Imagick::getImageChannelMean — Obtém a média e o desvio padrão
  - Imagick::getImageChannelRange — Obtém o intervalo do canal
  - Imagick::getImageChannelStatistics — Retorna estatísticas para cada canal na imagem
  - Imagick::getImageClipMask — Obtém a máscara de recorte da imagem
  - Imagick::getImageColormapColor — Retorna a cor do índice especificado do mapa de cores
  - Imagick::getImageColors — Obtém o número de cores únicas na imagem
  - Imagick::getImageColorspace — Obtém o espaço de cores da imagem
  - Imagick::getImageCompose — Retorna o operador de composição associado à imagem
  - Imagick::getImageCompression — Obtém o tipo de compactação da imagem atual
  - Imagick::getImageCompressionQuality — Obtém a qualidade de compressão da imagem atual
  - Imagick::getImageDelay — Obtém o atraso da imagem
  - Imagick::getImageDepth — Obtém a profundidade da imagem
  - Imagick::getImageDispose — Obtém o método de descarte de imagem
  - Imagick::getImageDistortion — Compara uma imagem com uma imagem reconstruída
  - Imagick::getImageExtrema — Obtém os extremos da imagem
  - Imagick::getImageFilename — Retorna o nome do arquivo de uma imagem específica em uma sequência
  - Imagick::getImageFormat — Retorna o formato de uma imagem específica em uma sequência
  - Imagick::getImageGamma — Obtém o gama da imagem
  - Imagick::getImageGeometry — Obtém a largura e a altura como um array associativo
  - Imagick::getImageGravity — Obtém a gravidade da imagem
  - Imagick::getImageGreenPrimary — Retorna o ponto primário verde da cromaticidade
  - Imagick::getImageHeight — Retorna a altura da imagem
  - Imagick::getImageHistogram — Obtém o histograma da imagem
  - Imagick::getImageIndex — Obtém o índice da imagem ativa atual
  - Imagick::getImageInterlaceScheme — Obtém o esquema de entrelaçamento da imagem
  - Imagick::getImageInterpolateMethod — Retorna o método de interpolação
  - Imagick::getImageIterations — Obtém as iterações da imagem
  - Imagick::getImageLength — Retorna o comprimento da imagem em bytes
  - Imagick::getImageMatte — Informa se a imagem tem um canal fosco
  - Imagick::getImageMatteColor — Retorna a cor fosca da imagem
  - Imagick::getImageMimeType — Retorna o tipo de mídia da imagem
  - Imagick::getImageOrientation — Obtém a orientação da imagem
  - Imagick::getImagePage — Retorna a geometria da página
  - Imagick::getImagePixelColor — Retorna a cor do pixel especificado
  - Imagick::getImageProfile — Retorna o perfil nomeado de imagem
  - Imagick::getImageProfiles — Retorna os perfis de imagem
  - Imagick::getImageProperties — Retorna as propriedades da imagem
  - Imagick::getImageProperty — Retorna a propriedade nomeada da imagem
  - Imagick::getImageRedPrimary — Retorna o ponto primário vermelho da cromaticidade
  - Imagick::getImageRegion — Extrai uma região da imagem
  - Imagick::getImageRenderingIntent — Obtém a intenção de renderização da imagem
  - Imagick::getImageResolution — Obtém a resolução X e Y da imagem
  - Imagick::getImagesBlob — Retorna todas as sequências de imagens como um BLOB
  - Imagick::getImageScene — Obtém a cena da imagem
  - Imagick::getImageSignature — Gera um resumo da mensagem SHA-256
  - Imagick::getImageSize — Retorna o comprimento da imagem em bytes
  - Imagick::getImageTicksPerSecond — Obtém os tiques por segundo da imagem
  - Imagick::getImageTotalInkDensity — Obtém a densidade total de tinta da imagem
  - Imagick::getImageType — Obtém o tipo potencial da imagem
  - Imagick::getImageUnits — Obtém as unidades de resolução da imagem
  - Imagick::getImageVirtualPixelMethod — Retorna o método do pixel virtual
  - Imagick::getImageWhitePoint — Retorna o ponto branco da cromaticidade
  - Imagick::getImageWidth — Retorna a largura da imagem
  - Imagick::getInterlaceScheme — Obtém o esquema de entrelaçamento do objeto
  - Imagick::getIteratorIndex — Obtém o índice da imagem ativa atual
  - Imagick::getNumberImages — Retorna o número de imagens no objeto
  - Imagick::getOption — Retorna um valor associado à chave especificada
  - Imagick::getPackageName — Retorna o nome do pacote ImageMagick
  - Imagick::getPage — Retorna a geometria da página
  - Imagick::getPixelIterator — Retorna um MagickPixelIterator
  - Imagick::getPixelRegionIterator — Obtém um ImagickPixelIterator para uma seção de imagem
  - Imagick::getPointSize — Obtém o tamanho do ponto
  - Imagick::getQuantum — Retorna o intervalo Quantum do Imagick
  - Imagick::getQuantumDepth — Obtém a profundidade Quantum
  - Imagick::getQuantumRange — Retorna o intervalo Quantum do Imagick
  - Imagick::getRegistry — Obtém uma entrada StringRegistry
  - Imagick::getReleaseDate — Retorna a data da versão do ImageMagick
  - Imagick::getResource — Retorna o uso de memória do recurso especificado
  - Imagick::getResourceLimit — Retorna o limite de recursos especificado
  - Imagick::getSamplingFactors — Obtém o fator de amostragem horizontal e vertical
  - Imagick::getSize — Retorna o tamanho associado ao objeto Imagick
  - Imagick::getSizeOffset — Retorna o deslocamento de tamanho
  - Imagick::getVersion — Retorna a versão da API ImageMagick
  - Imagick::haldClutImage — Substitui cores na imagem
  - Imagick::hasNextImage — Verifica se o objeto possui mais imagens
  - Imagick::hasPreviousImage — Verifica se o objeto possui uma imagem anterior
  - Imagick::identifyFormat — Formata uma string com detalhes da imagem
  - Imagick::identifyImage — Identifica uma imagem e busca atributos
  - Imagick::implodeImage — Cria uma nova imagem como cópia
  - Imagick::importImagePixels — Importa pixels de imagem
  - Imagick::inverseFourierTransformImage — Implementa a transformada discreta inversa de Fourier (DFT)
  - Imagick::labelImage — Adiciona um rótulo a uma imagem
  - Imagick::levelImage — Ajusta os níveis de uma imagem
  - Imagick::linearStretchImage — Estica com saturação a intensidade da imagem
  - Imagick::liquidRescaleImage — Anima uma imagem ou imagens
  - Imagick::listRegistry — Lista todas as configurações do registro
  - Imagick::magnifyImage — Dimensiona uma imagem proporcionalmente 2x
  - Imagick::mapImage — Substitui as cores de uma imagem pela cor mais próxima de uma imagem de referência
  - Imagick::matteFloodfillImage — Altera o valor de transparência de uma cor
  - Imagick::medianFilterImage — Aplica um filtro digital
  - Imagick::mergeImageLayers — Mescla camadas de imagem
  - Imagick::minifyImage — Dimensiona uma imagem proporcionalmente à metade do seu tamanho
  - Imagick::modulateImage — Controle brilho, saturação e matiz
  - Imagick::montageImage — Cria uma imagem composta
  - Imagick::morphImages — Transforma um conjunto de imagens
  - Imagick::morphology — Aplica um kernel fornecido pelo usuário à imagem de acordo com o método de morfologia fornecido
  - Imagick::mosaicImages — Forma um mosaico a partir de imagens
  - Imagick::motionBlurImage — Simula desfoque de movimento
  - Imagick::negateImage — Negativa as cores na imagem de referência
  - Imagick::newImage — Cria uma nova imagem
  - Imagick::newPseudoImage — Cria uma nova imagem
  - Imagick::nextImage — Passa para a próxima imagem
  - Imagick::normalizeImage — Melhora o contraste de uma imagem colorida
  - Imagick::oilPaintImage — Simula uma pintura a óleo
  - Imagick::opaquePaintImage — Altera o valor da cor de qualquer pixel que corresponda ao alvo
  - Imagick::optimizeImageLayers — Remove partes repetidas de imagens para otimizar
  - Imagick::orderedPosterizeImage — Executa um pontilhamento ordenado
  - Imagick::paintFloodfillImage — Altera o valor da cor de qualquer pixel que corresponda ao alvo
  - Imagick::paintOpaqueImage — Altera qualquer pixel que corresponda à cor
  - Imagick::paintTransparentImage — Altera qualquer pixel que corresponda à cor definida pelo preenchimento
  - Imagick::pingImage — Busca atributos básicos sobre a imagem
  - Imagick::pingImageBlob — Busca atributos rapidamente
  - Imagick::pingImageFile — Obtém atributos básicos de imagem de maneira leve
  - Imagick::polaroidImage — Simula uma imagem Polaroid
  - Imagick::posterizeImage — Reduz a imagem a um número limitado de níveis de cor
  - Imagick::previewImages — Identifica rapidamente os parâmetros apropriados para processamento de imagem
  - Imagick::previousImage — Passa para a imagem anterior no objeto
  - Imagick::profileImage — Adiciona ou remove um perfil de uma imagem
  - Imagick::quantizeImage — Analisa as cores dentro de uma imagem de referência
  - Imagick::quantizeImages — Analisa as cores dentro de uma sequência de imagens
  - Imagick::queryFontMetrics — Retorna um array representando as métricas da fonte
  - Imagick::queryFonts — Retorna as fontes configuradas
  - Imagick::queryFormats — Retorna formatos suportados pelo Imagick
  - Imagick::radialBlurImage — Desfoca uma imagem de forma radial
  - Imagick::raiseImage — Cria um efeito simulado de botão 3D
  - Imagick::randomThresholdImage — Cria uma imagem de alto contraste e duas cores
  - Imagick::readImage — Lê imagem de um arquivo
  - Imagick::readImageBlob — Lê imagem de uma string binária
  - Imagick::readImageFile — Lê imagem a partir de um descritor de arquivo
  - Imagick::readimages — Lê imagens de um array de arquivos
  - Imagick::recolorImage — Recolore imagem
  - Imagick::reduceNoiseImage — Suaviza os contornos de uma imagem
  - Imagick::remapImage — Remapeia as cores da imagem
  - Imagick::removeImage — Remove uma imagem da lista de imagens
  - Imagick::removeImageProfile — Remove o perfil de imagem nomeado e o retorna
  - Imagick::render — Renderiza todos os comandos de desenho anteriores
  - Imagick::resampleImage — Reamostra imagem para a resolução desejada
  - Imagick::resetImagePage — Redefine página de imagem
  - Imagick::resizeImage — Dimensiona uma imagem
  - Imagick::rollImage — Desloca uma imagem
  - Imagick::rotateImage — Rotaciona uma imagem
  - Imagick::rotationalBlurImage — Desfoca uma imagem de forma rotacional
  - Imagick::roundCorners — Arredonda os cantos da imagem
  - Imagick::sampleImage — Dimensiona uma imagem com amostragem de pixels
  - Imagick::scaleImage — Dimensiona o tamanho de uma imagem
  - Imagick::segmentImage — Segmenta uma imagem
  - Imagick::selectiveBlurImage — Desfocar seletivamente uma imagem dentro de um limite de contraste
  - Imagick::separateImageChannel — Separa um canal da imagem
  - Imagick::sepiaToneImage — Aplica tons de sépia em uma imagem
  - Imagick::setBackgroundColor — Define a cor de fundo padrão do objeto
  - Imagick::setColorspace — Define espaço de cores
  - Imagick::setCompression — Define o tipo de compactação padrão do objeto
  - Imagick::setCompressionQuality — Define a qualidade de compactação padrão do objeto
  - Imagick::setFilename — Define o nome do arquivo antes de ler ou gravar a imagem
  - Imagick::setFirstIterator — Define o iterador Imagick para a primeira imagem
  - Imagick::setFont — Define a fonte
  - Imagick::setFormat — Define o formato do objeto Imagick
  - Imagick::setGravity — Define a gravidade
  - Imagick::setImage — Substitui imagem no objeto
  - Imagick::setImageAlphaChannel — Define o canal alfa da imagem
  - Imagick::setImageArtifact — Definir artefato de imagem
  - Imagick::setImageAttribute — Define um atributo de imagem
  - Imagick::setImageBackgroundColor — Define a cor de fundo da imagem
  - Imagick::setImageBias — Define o ajuste (bias) da imagem para qualquer método que faça convolução em uma imagem
  - Imagick::setImageBiasQuantum — Define o ajuste (bias) da imagem
  - Imagick::setImageBluePrimary — Define o ponto primário azul da cromaticidade da imagem
  - Imagick::setImageBorderColor — Define a cor da borda da imagem
  - Imagick::setImageChannelDepth — Define a profundidade de um canal de imagem específico
  - Imagick::setImageClipMask — Define a máscara de recorte da imagem
  - Imagick::setImageColormapColor — Define a cor do índice do mapa de cores especificado
  - Imagick::setImageColorspace — Define o espaço de cores da imagem
  - Imagick::setImageCompose — Define o operador de composição de imagem
  - Imagick::setImageCompression — Define a compactação da imagem
  - Imagick::setImageCompressionQuality — Define a qualidade de compactação da imagem
  - Imagick::setImageDelay — Define o atraso da imagem
  - Imagick::setImageDepth — Define a profundidade da imagem
  - Imagick::setImageDispose — Define o método de descarte de imagem
  - Imagick::setImageExtent — Define o tamanho da imagem
  - Imagick::setImageFilename — Define o nome do arquivo de uma imagem específica
  - Imagick::setImageFormat — Define o formato de uma imagem específica
  - Imagick::setImageGamma — Define o gama da imagem
  - Imagick::setImageGravity — Define a gravidade da imagem
  - Imagick::setImageGreenPrimary — Define o ponto primário verde da cromaticidade da imagem
  - Imagick::setImageIndex — Define a posição do iterador
  - Imagick::setImageInterlaceScheme — Define a compactação da imagem
  - Imagick::setImageInterpolateMethod — Define o método de interpolação de pixel da imagem.
  - Imagick::setImageIterations — Define as iterações da imagem
  - Imagick::setImageMatte — Define o canal fosco da imagem
  - Imagick::setImageMatteColor — Define a cor fosca da imagem
  - Imagick::setImageOpacity — Define o nível de opacidade da imagem
  - Imagick::setImageOrientation — Define a orientação da imagem
  - Imagick::setImagePage — Define a geometria da página da imagem
  - Imagick::setImageProfile — Adiciona um perfil nomeado ao objeto Imagick
  - Imagick::setImageProperty — Define uma propriedade de imagem
  - Imagick::setImageRedPrimary — Define o ponto primário vermelho da cromaticidade da imagem
  - Imagick::setImageRenderingIntent — Define a intenção de renderização da imagem
  - Imagick::setImageResolution — Define a resolução da imagem
  - Imagick::setImageScene — Define a cena da imagem
  - Imagick::setImageTicksPerSecond — Define os tiques por segundo da imagem
  - Imagick::setImageType — Define o tipo de imagem
  - Imagick::setImageUnits — Define as unidades de resolução da imagem
  - Imagick::setImageVirtualPixelMethod — Define o método de pixel virtual da imagem
  - Imagick::setImageWhitePoint — Define o ponto branco da cromaticidade da imagem
  - Imagick::setInterlaceScheme — Define o esquema de entrelaçamento da imagem
  - Imagick::setIteratorIndex — Define a posição do iterador
  - Imagick::setLastIterator — Define o iterador Imagick para a última imagem
  - Imagick::setOption — Define uma opção
  - Imagick::setPage — Define a geometria da página do objeto Imagick
  - Imagick::setPointSize — Define o tamanho em pontos
  - Imagick::setProgressMonitor — Define uma função de retorno a ser chamada durante o processamento
  - Imagick::setRegistry — Define a chave nomeada do registro do ImageMagick para um valor
  - Imagick::setResolution — Define a resolução da imagem
  - Imagick::setResourceLimit — Define o limite para um recurso específico
  - Imagick::setSamplingFactors — Define os fatores de amostragem da imagem
  - Imagick::setSize — Define o tamanho do objeto Imagick
  - Imagick::setSizeOffset — Define o tamanho e o deslocamento do objeto Imagick
  - Imagick::setType — Define o atributo de tipo de imagem
  - Imagick::shadeImage — Cria um efeito 3D
  - Imagick::shadowImage — Simula uma sombra de imagem
  - Imagick::sharpenImage — Torna uma imagem mais nítida
  - Imagick::shaveImage — Raspa pixels das bordas da imagem
  - Imagick::shearImage — Cria um paralelogramo
  - Imagick::sigmoidalContrastImage — Ajusta o contraste de uma imagem
  - Imagick::sketchImage — Simula um esboço a lápis
  - Imagick::smushImages — Agrupa todas as imagens do ponteiro da imagem atual até o final da lista de imagens
  - Imagick::solarizeImage — Aplica um efeito solarizante à imagem
  - Imagick::sparseColorImage — Interpola cores
  - Imagick::spliceImage — Une uma cor sólida na imagem
  - Imagick::spreadImage — Desloca aleatoriamente cada pixel em um bloco
  - Imagick::statisticImage — Modifica a imagem usando uma função estatística
  - Imagick::steganoImage — Oculta uma marca d'água digital na imagem
  - Imagick::stereoImage — Compõe duas imagens
  - Imagick::stripImage — Remove todos os perfis e comentários de uma imagem
  - Imagick::subImageMatch — Procura uma subimagem na imagem atual e retorna uma imagem semelhante
  - Imagick::swirlImage — Gira os pixels em torno do centro da imagem
  - Imagick::textureImage — Ladrilha repetidamente a imagem da textura
  - Imagick::thresholdImage — Altera o valor de pixels individuais com base em um limite
  - Imagick::thumbnailImage — Altera o tamanho de uma imagem
  - Imagick::tintImage — Aplica um vetor de cores a cada pixel da imagem
  - Imagick::__toString — Retorna a imagem como uma string
  - Imagick::transformImage — Método conveniente para definir o tamanho do corte e a geometria da imagem
  - Imagick::transformImageColorspace — Transforma uma imagem em um novo espaço de cores
  - Imagick::transparentPaintImage — Pinta pixels com a cor transparente
  - Imagick::transposeImage — Cria uma imagem espelhada vertical
  - Imagick::transverseImage — Cria uma imagem espelhada horizontal
  - Imagick::trimImage — Apara as bordas da imagem
  - Imagick::uniqueImageColors — Descarta todas, exceto uma, de qualquer cor de pixel
  - Imagick::unsharpMaskImage — Torna uma imagem mais nítida
  - Imagick::valid — Verifica se o item atual é válido
  - Imagick::vignetteImage — Adiciona filtro de vinheta à imagem
  - Imagick::waveImage — Aplica filtro de onda à imagem
  - Imagick::whiteThresholdImage — Força todos os pixels acima de um limite para branco
  - Imagick::writeImage — Grava uma imagem no nome de arquivo especificado
  - Imagick::writeImageFile — Grava uma imagem em um descritor de arquivo
  - Imagick::writeImages — Grava uma imagem ou sequência de imagens
  - Imagick::writeImagesFile — Grava quadros em um descritor de arquivo
- ImagickDraw — A classe ImagickDraw
  - ImagickDraw::affine — Ajusta a matriz de transformação afim atual
  - ImagickDraw::annotation — Desenha texto na imagem
  - ImagickDraw::arc — Desenha um arco
  - ImagickDraw::bezier — Desenha uma curva de Bézier
  - ImagickDraw::circle — Desenha um círculo
  - ImagickDraw::clear — Limpa o ImagickDraw
  - ImagickDraw::clone — Faz uma cópia exata do objeto ImagickDraw especificado
  - ImagickDraw::color — Desenha cores na imagem
  - ImagickDraw::comment — Adiciona um comentário
  - ImagickDraw::composite — Compõe uma imagem sobre a imagem atual
  - ImagickDraw::__construct — O construtor ImagickDraw
  - ImagickDraw::destroy — Libera todos os recursos associados
  - ImagickDraw::ellipse — Desenha uma elipse na imagem
  - ImagickDraw::getClipPath — Obtém o ID do caminho de recorte atual
  - ImagickDraw::getClipRule — Retorna a regra atual de preenchimento do polígono
  - ImagickDraw::getClipUnits — Retorna a interpretação das unidades de caminho de recorte
  - ImagickDraw::getFillColor — Retorna a cor de preenchimento
  - ImagickDraw::getFillOpacity — Retorna a opacidade usada ao desenhar
  - ImagickDraw::getFillRule — Retorna a regra de preenchimento
  - ImagickDraw::getFont — Retorna a fonte
  - ImagickDraw::getFontFamily — Retorna a família de fontes
  - ImagickDraw::getFontSize — Retorna o tamanho da fonte em pontos
  - ImagickDraw::getFontStretch — Obtém o esticamento de fonte a ser usado ao fazer anotações com texto
  - ImagickDraw::getFontStyle — Retorna o estilo da fonte
  - ImagickDraw::getFontWeight — Retorna a espessura da fonte
  - ImagickDraw::getGravity — Retorna o alinhamento de posicionamento do texto
  - ImagickDraw::getStrokeAntialias — Retorna a configuração atual de suavização do traço
  - ImagickDraw::getStrokeColor — Retorna a cor usada para traçar os contornos dos objetos
  - ImagickDraw::getStrokeDashArray — Retorna um array que representa o padrão de traços e espaços usados ​​para traçar caminhos
  - ImagickDraw::getStrokeDashOffset — Retorna o deslocamento no padrão de traço para iniciar o traço
  - ImagickDraw::getStrokeLineCap — Retorna a forma a ser usada no final dos subcaminhos abertos quando eles são traçados
  - ImagickDraw::getStrokeLineJoin — Retorna a forma a ser usada nos cantos dos caminhos quando eles são traçados
  - ImagickDraw::getStrokeMiterLimit — Retorna o limite de esquadria do traçado
  - ImagickDraw::getStrokeOpacity — Retorna a opacidade dos contornos dos objetos traçados
  - ImagickDraw::getStrokeWidth — Retorna a largura do traço usado para desenhar contornos de objetos
  - ImagickDraw::getTextAlignment — Retorna o alinhamento do texto
  - ImagickDraw::getTextAntialias — Retorna a configuração atual de antialias do texto
  - ImagickDraw::getTextDecoration — Retorna a decoração do texto
  - ImagickDraw::getTextEncoding — Retorna o conjunto de caracteres usado para anotações de texto
  - ImagickDraw::getTextInterlineSpacing — Obtém o espaçamento entre linhas do texto
  - ImagickDraw::getTextInterwordSpacing — Obtém o espaçamento entre palavras do texto
  - ImagickDraw::getTextKerning — Obtém o espaçamento entre letras do texto
  - ImagickDraw::getTextUnderColor — Retorna a cor sob o texto
  - ImagickDraw::getVectorGraphics — Retorna uma string contendo gráficos vetoriais
  - ImagickDraw::line — Desenha uma linha
  - ImagickDraw::matte — Pinta no canal de opacidade da imagem
  - ImagickDraw::pathClose — Adiciona um elemento de caminho ao caminho atual
  - ImagickDraw::pathCurveToAbsolute — Desenha uma curva cúbica de Bézier
  - ImagickDraw::pathCurveToQuadraticBezierAbsolute — Desenha uma curva quadrática de Bézier
  - ImagickDraw::pathCurveToQuadraticBezierRelative — Desenha uma curva quadrática de Bézier
  - ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute — Desenha uma curva quadrática de Bézier
  - ImagickDraw::pathCurveToQuadraticBezierSmoothRelative — Desenha uma curva quadrática de Bézier
  - ImagickDraw::pathCurveToRelative — Desenha uma curva cúbica de Bézier
  - ImagickDraw::pathCurveToSmoothAbsolute — Desenha uma curva cúbica de Bézier
  - ImagickDraw::pathCurveToSmoothRelative — Desenha uma curva cúbica de Bézier
  - ImagickDraw::pathEllipticArcAbsolute — Desenha um arco elíptico
  - ImagickDraw::pathEllipticArcRelative — Desenha um arco elíptico
  - ImagickDraw::pathFinish — Termina o caminho atual
  - ImagickDraw::pathLineToAbsolute — Desenha um caminho de linha
  - ImagickDraw::pathLineToHorizontalAbsolute — Desenha um caminho de linha horizontal
  - ImagickDraw::pathLineToHorizontalRelative — Desenha um caminho de linha horizontal
  - ImagickDraw::pathLineToRelative — Desenha um caminho de linha
  - ImagickDraw::pathLineToVerticalAbsolute — Desenha um caminho de linha vertical
  - ImagickDraw::pathLineToVerticalRelative — Desenha um caminho de linha vertical
  - ImagickDraw::pathMoveToAbsolute — Inicia um novo subcaminho
  - ImagickDraw::pathMoveToRelative — Inicia um novo subcaminho
  - ImagickDraw::pathStart — Declara o início de uma lista de desenho de caminho
  - ImagickDraw::point — Desenha um ponto
  - ImagickDraw::polygon — Desenha um polígono
  - ImagickDraw::polyline — Desenha uma polilinha
  - ImagickDraw::pop — Destrói o ImagickDraw atual na pilha e retorna ao ImagickDraw enviado anteriormente
  - ImagickDraw::popClipPath — Encerra uma definição de caminho de recorte
  - ImagickDraw::popDefs — Encerra uma lista de definições
  - ImagickDraw::popPattern — Encerra uma definição de padrão
  - ImagickDraw::push — Clona o ImagickDraw atual e o coloca na pilha
  - ImagickDraw::pushClipPath — Inicia uma definição de caminho de recorte
  - ImagickDraw::pushDefs — Indica que os comandos a seguir criam elementos nomeados para processamento antecipado
  - ImagickDraw::pushPattern — Indica que os comandos subsequentes até um comando ImagickDraw::opPattern() compreendem a definição de um padrão nomeado
  - ImagickDraw::rectangle — Desenha um retângulo
  - ImagickDraw::render — Renderiza todos os comandos de desenho anteriores na imagem
  - ImagickDraw::resetVectorGraphics — Redefine os gráficos vetoriais
  - ImagickDraw::rotate — Aplica a rotação especificada ao espaço de coordenadas atual
  - ImagickDraw::roundRectangle — Desenha um retângulo arredondado
  - ImagickDraw::scale — Ajusta o fator de escala
  - ImagickDraw::setClipPath — Associa um caminho de recorte nomeado à imagem
  - ImagickDraw::setClipRule — Define a regra de preenchimento do polígono a ser usada pelo traçado de recorte
  - ImagickDraw::setClipUnits — Define a interpretação das unidades do caminho de recorte
  - ImagickDraw::setFillAlpha — Define a opacidade a ser usada ao desenhar usando a cor ou textura de preenchimento
  - ImagickDraw::setFillColor — Define a cor de preenchimento a ser usada para desenhar objetos preenchidos
  - ImagickDraw::setFillOpacity — Define a opacidade a ser usada ao desenhar usando a cor ou textura de preenchimento
  - ImagickDraw::setFillPatternURL — Define a URL a ser usada como padrão de preenchimento para preencher objetos
  - ImagickDraw::setFillRule — Define a regra de preenchimento a ser usada ao desenhar polígonos
  - ImagickDraw::setFont — Define a fonte totalmente especificada a ser usada ao fazer anotações com texto
  - ImagickDraw::setFontFamily — Define a família de fontes a ser usada ao fazer anotações com texto
  - ImagickDraw::setFontSize — Define o tamanho da fonte a ser usado ao fazer anotações com texto
  - ImagickDraw::setFontStretch — Define o esticamento da fonte a ser usado ao fazer anotações com texto
  - ImagickDraw::setFontStyle — Define o estilo da fonte a ser usado ao fazer anotações com texto
  - ImagickDraw::setFontWeight — Define a espessura da fonte
  - ImagickDraw::setGravity — Define a gravidade do posicionamento do texto
  - ImagickDraw::setResolution — Define a resolução
  - ImagickDraw::setStrokeAlpha — Especifica a opacidade dos contornos dos objetos traçados
  - ImagickDraw::setStrokeAntialias — Controla se os contornos traçados são suavizados
  - ImagickDraw::setStrokeColor — Define a cor usada para traçar os contornos dos objetos
  - ImagickDraw::setStrokeDashArray — Especifica o padrão de traços e espaços usados ​​para traçar caminhos
  - ImagickDraw::setStrokeDashOffset — Especifica o deslocamento no padrão de traço para iniciar o traço
  - ImagickDraw::setStrokeLineCap — Especifica a forma a ser usada no final dos subcaminhos abertos quando eles são traçados
  - ImagickDraw::setStrokeLineJoin — Especifica a forma a ser usada nos cantos dos caminhos quando eles são traçados
  - ImagickDraw::setStrokeMiterLimit — Especifica o limite de esquadria
  - ImagickDraw::setStrokeOpacity — Especifica a opacidade dos contornos dos objetos traçados
  - ImagickDraw::setStrokePatternURL — Define o padrão usado para traçar contornos de objetos
  - ImagickDraw::setStrokeWidth — Define a largura do traço usado para desenhar contornos de objetos
  - ImagickDraw::setTextAlignment — Especifica um alinhamento de texto
  - ImagickDraw::setTextAntialias — Controla se o texto é suavizado
  - ImagickDraw::setTextDecoration — Especifica uma decoração
  - ImagickDraw::setTextEncoding — Especifica o conjunto de caracteres do texto
  - ImagickDraw::setTextInterlineSpacing — Define o espaçamento entre linhas do texto
  - ImagickDraw::setTextInterwordSpacing — Define o espaçamento entre palavras do texto
  - ImagickDraw::setTextKerning — Define o espaçamento entre letras do texto
  - ImagickDraw::setTextUnderColor — Especifica a cor de um retângulo de fundo
  - ImagickDraw::setVectorGraphics — Define os gráficos vetoriais
  - ImagickDraw::setViewbox — Define o tamanho geral da tela
  - ImagickDraw::skewX — Inclina o sistema de coordenadas atual na direção horizontal
  - ImagickDraw::skewY — Inclina o sistema de coordenadas atual na direção vertical
  - ImagickDraw::translate — Aplica uma translação no sistema de coordenadas atual
- ImagickDrawException — A classe ImagickDrawException
- ImagickException — A classe ImagickException
- ImagickKernel — A classe ImagickKernel
  - ImagickKernel::addKernel — Anexa outro kernel a uma lista de kernels
  - ImagickKernel::addUnityKernel — Adiciona um Kernel Unity à lista de kernels
  - ImagickKernel::fromBuiltIn — Cria um kernel a partir de um kernel integrado
  - ImagickKernel::fromMatrix — Crie um kernel a partir de uma matriz 2D de valores
  - ImagickKernel::getMatrix — Obtém a matriz 2D de valores usada neste kernel
  - ImagickKernel::scale — Dimensiona uma lista de kernel pela quantidade especificada
  - ImagickKernel::separate — Separa um conjunto vinculado de kernels e retorna um array de ImagickKernels
- ImagickKernelException — A classe ImagickKernelException
- ImagickPixel — A classe ImagickPixel
  - ImagickPixel::clear — Limpa recursos associados a este objeto
  - ImagickPixel::__construct — O construtor de ImagickPixel
  - ImagickPixel::destroy — Desaloca recursos associados a este objeto
  - ImagickPixel::getColor — Retorna a cor
  - ImagickPixel::getColorAsString — Retorna a cor como uma string
  - ImagickPixel::getColorCount — Retorna a contagem de cores associada a esta cor
  - ImagickPixel::getColorQuantum — Retorna a cor do pixel em um array como valores Quantum
  - ImagickPixel::getColorValue — Obtém o valor normalizado do canal de cores fornecido
  - ImagickPixel::getColorValueQuantum — Obtém o valor Quantum de uma cor no ImagickPixel
  - ImagickPixel::getHSL — Retorna a cor HSL normalizada do objeto ImagickPixel
  - ImagickPixel::getIndex — Obtém o índice do mapa de cores da varinha de pixel
  - ImagickPixel::isPixelSimilar — Verifica a distância entre esta cor e uma outra
  - ImagickPixel::isPixelSimilarQuantum — Retorna se duas cores diferem em menos que a distância especificada
  - ImagickPixel::isSimilar — Verifica a distância entre esta cor e uma outra
  - ImagickPixel::setColor — Define a cor
  - ImagickPixel::setColorCount — Define a contagem de cores associada a esta cor
  - ImagickPixel::setColorValue — Define o valor normalizado de um dos canais
  - ImagickPixel::setColorValueQuantum — Define o valor Quantum de um elemento de cor do ImagickPixel
  - ImagickPixel::setHSL — Define a cor HSL normalizada
  - ImagickPixel::setIndex — Define o índice do mapa de cores da varinha de pixel
- ImagickPixelException — A classe ImagickPixelException
- ImagickPixelIterator — A classe ImagickPixelIterator
  - ImagickPixelIterator::clear — Limpa recursos associados a um PixelIterator
  - ImagickPixelIterator::__construct — O construtor de ImagickPixelIterator
  - ImagickPixelIterator::destroy — Desaloca recursos associados a um PixelIterator
  - ImagickPixelIterator::getCurrentIteratorRow — Retorna a linha atual de objetos ImagickPixel
  - ImagickPixelIterator::getIteratorRow — Retorna a linha atual do iterador de pixel
  - ImagickPixelIterator::getNextIteratorRow — Retorna a próxima linha do iterador de pixel
  - ImagickPixelIterator::getPreviousIteratorRow — Retorna a linha anterior
  - ImagickPixelIterator::newPixelIterator — Retorna um novo iterador de pixel
  - ImagickPixelIterator::newPixelRegionIterator — Retorna um novo iterador de pixel
  - ImagickPixelIterator::resetIterator — Redefine o iterador de pixel
  - ImagickPixelIterator::setIteratorFirstRow — Define o iterador de pixels para a primeira linha de pixels
  - ImagickPixelIterator::setIteratorLastRow — Define o iterador de pixels para a última linha de pixels
  - ImagickPixelIterator::setIteratorRow — Define a linha do iterador de pixel
  - ImagickPixelIterator::syncIterator — Sincroniza o iterador de pixel
- ImagickPixelIteratorException — A classe ImagickPixelIteratorException

- Exif — Informações de imagem
  - Instalação/Configuração
  - Constantes predefinidas
  - Funções de Exif
- GD — Processamento de Imagem e GD
  - Instalação/Configuração
  - Constantes predefinidas
  - Exemplos
  - Funções de GD e Image
  - GdImage — A classe GdImage
  - GdFont — A classe GdFont
- Gmagick
  - Instalação/Configuração
  - Constantes predefinidas
  - Exemplos
  - Gmagick — A classe Gmagick
  - GmagickDraw — A classe GmagickDraw
  - GmagickPixel — A classe GmagickPixel
- ImageMagick — Processamento de Imagem
  - Instalação/Configuração
  - Constantes predefinidas
  - Exemplos
  - Imagick — A classe Imagick
  - ImagickDraw — A classe ImagickDraw
  - ImagickDrawException — A classe ImagickDrawException
  - ImagickException — A classe ImagickException
  - ImagickKernel — A classe ImagickKernel
  - ImagickKernelException — A classe ImagickKernelException
  - ImagickPixel — A classe ImagickPixel
  - ImagickPixelException — A classe ImagickPixelException
  - ImagickPixelIterator — A classe ImagickPixelIterator
  - ImagickPixelIteratorException — A classe ImagickPixelIteratorException

# Extensões Relacionadas a Correio Eletrônico

# IMAP, POP3 e NNTP

# Introdução

Aviso

Esta extensão foi DESCONTINUADA e DESAGREGADA a partir do PHP 8.4.0.

Essas funções permitem operações com o protocolo IMAP, bem como com os métodos de acesso NNTP, POP3 e caixa de correio local.

No entanto, esteja avisado de que algumas funções IMAP não funcionarão corretamente com o protocolo POP.

Aviso

A extensão IMAP não é segura para threads; ela não deve ser usada com compilações ZTS.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução
- Tipos de Recurso

## Dependências

Esta extensão requer que a biblioteca c-client seja instalada. Obtenha a versão mais recente de » https://github.com/uw-imap/imap e compile-a.

É importante que você não copie os arquivos-fonte de IMAP diretamente para o diretório de inclusão do sistema, pois podem ocorrer conflitos. Em vez disso, crie um novo diretório dentro do diretório de inclusão do sistema, como /usr/local/imap-2000b/ (o local e o nome dependem da configuração e versão do IMAP) e, dentro desse novo diretório, crie diretórios adicionais chamados lib/ e include/. A partir do diretório c-client da sua árvore fonte do IMAP, copie todos os arquivos *.h para include/ e todos os arquivos *.c para lib/. Além disso, quando o IMAP foi compilado, um arquivo chamado c-client.a foi criado. Ele deve ser colocado também no diretório lib/, mas renomeado como libc-client.a.

> Nota:

> Para criar a biblioteca c-client com suporte a SSL e/ou Kerberos, leia a documentação fornecida com o pacote.

> Nota: No Mandrake Linux, a biblioteca IMAP (libc-client.a) é compilada sem suporte a Kerberos. Uma versão separada com SSL (client-PHP4.a) é instalada. A biblioteca deve ser recompilada para adicionar suporte a Kerberos.

## Instalação

## PHP 8.4

Esta extensão foi movida para o repositório » PECL e não é mais distribuída com o PHP desde a versão 8.4.0

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/imap.

## PHP < 8.4

Para fazer estas funções funcionarem, é necessário compilar o PHP com --with-imap[=DIR], onde DIR é o prefixo de instalação c-client. Do exemplo acima, seria usada a opção --with-imap=/usr/local/imap-2000b. Este local depende de onde este diretório foi criado de acordo com a descrição acima. Usuários do Windows podem incluir a DLL php_imap.dll no php.ini.

> Nota: Dependendo de como o c-client foi configurado, talvez também seja necessário adicionar --with-imap-ssl=/path/to/openssl/ e/ou --with-kerberos=/path/to/kerberos à linha de configuração do PHP.

Aviso

A extensão IMAP não é segura para threads; ela não deve ser usada com compilações ZTS.

Aviso

As extensões IMAP, recode e YAZ não podem ser usadas em conjunto, pois compartilham os mesmos símbolos internos. Observação: a Yaz 2.0 e superiores não sofrem deste problema.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de Configuração de IMAP
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
imap.enable_insecure_rsh | "0" | `INI_SYSTEM` | Disponível a partir do PHP 7.1.25, 7.2.13 e 7.3.0. Anteriormente, era implicitamente habilitado.

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`imap.enable_insecure_rsh` bool

  Estabelecer uma conexão com um servidor pode invocar os comandos rsh ou ssh, a menos que esta opção no php.ini esteja desabilitada.

  Aviso

  Nem o PHP nem a biblioteca IMAP filtram nomes de caixas de correio antes de passá-los para os comandos rsh ou ssh, portanto, passar dados não confiáveis para esta função sem desabilitar esta opção php.ini é inseguro.

## Tipos de Recurso

Antes do PHP 8.1.0, esta extensão definia o tipo de recurso `imap`, conforme retornado por imap_open(), que faz referência a um fluxo IMAP aberto.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`NIL` (int)
  Descontinuado a partir do PHP 8.1.0.
`OP_DEBUG` (int)
`OP_READONLY` (int)
  Abre a caixa de correio somente leitura
`OP_ANONYMOUS` (int)
  Não usa ou atualiza um .newsrc para novidades (somente NNTP)
`OP_SHORTCACHE` (int)
`OP_SILENT` (int)
`OP_PROTOTYPE` (int)
`OP_HALFOPEN` (int)
  Para nomes IMAP e NNTP, abre uma conexão, mas não abre uma caixa de correio.
`OP_EXPUNGE` (int)
`OP_SECURE` (int)
`CL_EXPUNGE` (int)
  Expurga silenciosamente a caixa de correio antes de fechar ao chamar imap_close()
`FT_UID` (int)
  O parâmetro é um UID
`FT_PEEK` (int)
  Não define a opção \Seen se ainda não estiver definida
`FT_NOT` (int)
`FT_INTERNAL` (int)
  A string de retorno está em formato interno, não será canonizada para CRLF.
`FT_PREFETCHTEXT` (int)
`ST_UID` (int)
  O argumento de sequência contém UIDs em vez de números de sequência
`ST_SILENT` (int)
`ST_SET` (int)
`CP_UID` (int)
  Os números de sequência contêm UIDS
`CP_MOVE` (int)
  Exclui as mensagens da caixa de correio atual após copiar com imap_mail_copy()
`SE_UID` (int)
  Retorna UIDs em vez de números de sequência
`SE_FREE` (int)
`SE_NOPREFETCH` (int)
  Não pré-buscar mensagens pesquisadas
`SO_FREE` (int)
`SO_NOSERVER` (int)
`SA_MESSAGES` (int)
`SA_RECENT` (int)
`SA_UNSEEN` (int)
`SA_UIDNEXT` (int)
`SA_UIDVALIDITY` (int)
`SA_ALL` (int)
`LATT_NOINFERIORS` (int)
  Esta caixa de correio não tem "filhos" (não há caixas de correio abaixo desta).
`LATT_NOSELECT` (int)
  Este é apenas um contêiner, não uma caixa de correio - não pode ser aberto.
`LATT_MARKED` (int)
  Esta caixa de correio está marcada. Usada somente por UW-IMAPD.
`LATT_UNMARKED` (int)
  Esta caixa de correio não está marcada. Usada somente por UW-IMAPD.
`LATT_REFERRAL` (int)
  Este contêiner tem uma referência para uma caixa de correio remota.
`LATT_HASCHILDREN` (int)
  Esta caixa de correio tem caixas filhas selecionáveis.
`LATT_HASNOCHILDREN` (int)
  Esta caixa de correio não tem caixas filhas selecionáveis.
`SORTDATE` (int)
  Critérios de classificação para imap_sort(): data da mensagem
`SORTARRIVAL` (int)
  Critérios de classificação para imap_sort(): data de chegada
`SORTFROM` (int)
  Critérios de classificação para imap_sort(): caixa de correio no primeiro endereço "De:" (From)
`SORTSUBJECT` (int)
  Critérios de classificação para imap_sort(): assunto da mensagem
`SORTTO` (int)
  Critérios de classificação para imap_sort(): caixa de correio no primeiro endereço "Para:" (To)
`SORTCC` (int)
  Critérios de classificação para imap_sort(): caixa de correio no primeiro endereço "Cc:"
`SORTSIZE` (int)
  Critérios de classificação para imap_sort(): tamanho da mensagem em octetos
`TYPETEXT` (int)
  Tipo de corpo primário: texto não formatado
`TYPEMULTIPART` (int)
  Tipo de corpo primário: várias partes
`TYPEMESSAGE` (int)
  Tipo de corpo primário: mensagem encapsulada
`TYPEAPPLICATION` (int)
  Tipo de corpo primário: dados de aplicação
`TYPEAUDIO` (int)
  Tipo de corpo primário: áudio
`TYPEIMAGE` (int)
  Tipo de corpo primário: imagem estática
`TYPEVIDEO` (int)
  Tipo de corpo primário: vídeo
`TYPEMODEL` (int)
  Tipo de corpo primário: modelo
`TYPEOTHER` (int)
  Tipo de corpo primário: desconhecido
`ENC7BIT` (int)
  Codificação do corpo: dados semânticos SMTP de 7 bits
`ENC8BIT` (int)
  Codificação do corpo: dados semânticos SMTP de 8 bits
`ENCBINARY` (int)
  Codificação do corpo: dados binários de 8 bits
`ENCBASE64` (int)
  Codificação do corpo: dados codificados em base-64
`ENCQUOTEDPRINTABLE` (int)
  Codificação do corpo: dados de 8 bits como 7 bits legíveis por humanos
`ENCOTHER` (int)
  Codificação do corpo: desconhecido
`IMAP_OPENTIMEOUT` (int)
`IMAP_READTIMEOUT` (int)
`IMAP_WRITETIMEOUT` (int)
`IMAP_CLOSETIMEOUT` (int)
`IMAP_GC_ELT` (int)
  Coletor de lixo, limpa elementos de cache de mensagens.
`IMAP_GC_ENV` (int)
  Coletor de lixo, limpa envelopes e corpos.
`IMAP_GC_TEXTS` (int)
  Coletor de lixo, limpa textos.

# Funções de IMAP

# Veja Também

Este documento não pode entrar em detalhes sobre todos os tópicos abordados pelas funções fornecidas. Mais informações são fornecidas pela documentação da fonte da biblioteca c-client (docs/internal.txt). e os seguintes documentos RFC:

- » RFC2821: `Simple Mail Transfer Protocol` (SMTP).
- » RFC2822: `Standard for ARPA internet text messages`.
- » RFC2060: `Internet Message Access Protocol` (IMAP) Versão 4rev1.
- » RFC1939: `Post Office Protocol Version 3` (POP3).
- » RFC977: `Network News Transfer Protocol` (NNTP).
- » RFC2076: `Common Internet Message Headers`.
- » RFC2045, » RFC2046, » RFC2047, » RFC2048 & » RFC2049: `Multipurpose Internet Mail Extensions` (MIME).

Uma visão geral detalhada também está disponível nos livros » `Programming Internet Email` de David Wood e » Managing IMAP de Dianna Mullet e Kevin Mullet.

# imap_8bit

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_8bit — Converte uma string de 8 bits em uma string imprimível escapada

### Descrição

function imap_8bit(string `$string`): string|false

Converta uma string de 8 bits em uma string imprimível escapada (de acordo com » RFC2045, seção 6.7).

### Parâmetros

`string`

  A string de 8 bits a ser convertida

### Valor Retornado

Retorna uma string imprimível escapada, ou `false` em caso de falha.

### Veja Também

- imap_qprint() - Converte uma string imprimível escapada em uma string de 8 bits

# imap_alerts

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_alerts — Retorna todas as mensagens de alerta IMAP que ocorreram

### Descrição

function imap_alerts(): array|false

Retorna todas as mensagens de alerta IMAP geradas desde a última chamada imap_alerts() ou desde o início da página.

Quando imap_alerts() é chamada, a pilha de alertas é subsequentemente limpa. A especificação IMAP requer que essas mensagens sejam passadas ao usuário.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array de todas as mensagens de alerta IMAP geradas ou `false` se nenhuma mensagem de alerta estiver disponível.

### Veja Também

- imap_errors() - Retorna todos os erros IMAP que ocorreram

# imap_append

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_append — Acrescenta uma mensagem de string a uma caixa de correio especificada

### Descrição

function imap_append(
IMAP\Connection `$imap`,
string `$folder`,
string `$message`,
?string `$options` = `null`,
?string `$internal_date` = `null`
): bool

Acrescenta uma mensagem string informada no parâmetro `message` à caixa informada em `folder`.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`folder`

  O nome da caixa de correio, veja imap_open() para mais informações

  Aviso

  Passar dados não confiáveis para este parâmetro é inseguro, a menos que imap.enable_insecure_rsh esteja desabilitado.

`message`

  A mensagem a ser anexada, como uma string

  Ao comunicar com o servidor Cyrus IMAP, deve-se usar "\r\n" como o terminador de fim de linha em vez de "\n" ou a operação irá falhar

`options`

  Se fornecido, o `options` também será gravado em `folder`.

`internal_date`

  Se esse parâmetro for definido, ele definirá a data interna (INTERNALDATE) na mensagem anexada. O parâmetro deve ser uma string de data que esteja em conformidade com as especificações RFC2060 para um valor de data/horário.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.
8.0.0 | `options` e `internal_date` agora podem ser nulos.

### Exemplos

Exemplo #1 Exemplo de imap_append()

    <?php
    $imap = imap_open("{imap.example.org}INBOX.Drafts", "username", "password");

    $check = imap_check($imap);
    echo "Contagem de mensagens antes de anexar: ". $check->Nmsgs . "\n";

    imap_append($imap, "{imap.example.org}INBOX.Drafts"
                       , "From: eu@example.com\r\n"
                       . "To: voce@example.com\r\n"
                       . "Subject: teste\r\n"
                       . "\r\n"
                       . "esta é uma mensagem de teste, favor ignorar\r\n"
                       );

    $check = imap_check($imap);
    echo "Contagem de mensagens após anexar: ". $check->Nmsgs . "\n";

    imap_close($imap);
    ?>

# imap_base64

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_base64 — Decodifica texto codificado em BASE64

### Descrição

function imap_base64(string `$string`): string|false

Decodifica a `string` codificada em BASE-64 fornecida.

### Parâmetros

`string`

  O texto codificado

### Valor Retornado

Retorna a mensagem decodificada como uma string, ou `false` em caso de falha.

### Veja Também

- imap_binary() - Converte uma string de 8 bits em uma string base64
- base64_encode() - Codifica dados com MIME base64
- base64_decode() - Decodifica dados no formato MIME base64
- » RFC2045, Section 6.8

# imap_binary

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_binary — Converte uma string de 8 bits em uma string base64

### Descrição

function imap_binary(string `$string`): string|false

Converta uma string de 8 bits em uma string base64 de acordo com » RFC2045, Seção 6.8.

### Parâmetros

`string`

  A string de 8 bits

### Valor Retornado

Retorna uma string codificada em base64, ou `false` em caso de falha.

### Veja Também

- imap_base64() - Decodifica texto codificado em BASE64

# imap_body

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_body — Lê o corpo da mensagem

### Descrição

function imap_body(IMAP\Connection `$imap`, int `$message_num`, int `$flags` = 0): string|false

imap_body() retorna o corpo da mensagem, de número `message_num`, na caixa de correio atual.

imap_body() retornará apenas uma cópia literal do corpo da mensagem. Para extrair um único componente de uma mensagem multipartes codificada em MIME, é necessário usar imap_fetchstructure() para analisar sua estrutura e imap_fetchbody() para extrair uma cópia de um único componente do corpo.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`message_num`

  O número da mensagem

`flags`

  Os sinalizadores opcionais em `flags` são uma máscara de bits com uma ou mais das seguintes constantes:

  - `FT_UID` - O número da mensagem em `message_num` é um UID
  - `FT_PEEK` - Não define o sinalizador \Seen se ainda não estiver definido
  - `FT_INTERNAL` - A string de retorno está em formato interno, não será canonizada para CRLF.

### Valor Retornado

Retorna o corpo da mensagem especificada, como uma string, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

# imap_bodystruct

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_bodystruct — Lê a estrutura de uma seção específica do corpo de uma mensagem específica

### Descrição

function imap_bodystruct(IMAP\Connection `$imap`, int `$message_num`, string `$section`): stdClass|false

Lê a estrutura de uma seção específica do corpo de uma mensagem específica.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`message_num`

  O número da mensagem

`section`

  A seção do corpo a ser lida

### Valor Retornado

Retorna as informações em um objeto, ou `false` em caso de falha. Para uma descrição detalhada da estrutura e propriedades do objeto, veja imap_fetchstructure().

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Veja Também

- imap_fetchstructure() - Lê a estrutura de uma mensagem específica

# imap_check

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_check — Verifica a caixa de correio atual

### Descrição

function imap_check(IMAP\Connection `$imap`): stdClass|false

Verifica informações sobre a caixa de correio atual.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.

### Valor Retornado

Retorna as informações em um objeto com as seguintes propriedades:

- `Date` - horário atual do sistema formatado de acordo com » RFC2822
- `Driver` - protocolo usado para acessar esta caixa de correio: POP3, IMAP, NNTP
- `Mailbox` - o nome da caixa de correio
- `Nmsgs` - número de mensagens na caixa de correio
- `Recent` - número de mensagens recentes na caixa de correio

Retorna `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imap_check()

    <?php

    $imap = imap_check($imap_stream);
    var_dump($imap);

    ?>

O exemplo acima produzirá algo semelhante a:

    object(stdClass)(5) {
      ["Date"]=>
      string(37) "Wed, 10 Dec 2003 17:56:54 +0100 (CET)"
      ["Driver"]=>
      string(4) "imap"
      ["Mailbox"]=>
      string(54)
      "{www.example.com:143/imap/user="foo@example.com"}INBOX"
      ["Nmsgs"]=>
      int(1)
      ["Recent"]=>
      int(0)
    }

# imap_clearflag_full

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_clearflag_full — Limpa sinalizadores em mensagens

### Descrição

function imap_clearflag_full(
IMAP\Connection `$imap`,
string `$sequence`,
string `$flag`,
int `$options` = 0
): true

Esta função faz com seja excluído o sinalizador especificado em `flag` para as mensagens sequência especificada em `sequence`.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`sequence`

  Uma sequência de números de mensagens. Pod-se enumerar as mensagens desejadas com a sintaxe `X,Y` ou recuperar todas as mensagens dentro de um intervalo com a sintaxe `X:Y`.

`flag`

  Os sinalizadores que você pode desmarcar são "\\Seen" (visto), "\\Answered" (respondido), "\\Flagged" (sinalizado), "\\Deleted" (excluído) e "\\Draft" (rascunho), conforme definido pela » RFC2060.

`options`

  `options` são uma máscara de bits e pode conter a única opção:

  - `ST_UID` - O argumento de sequência contém UIDs em vez de números de sequência

### Valor Retornado

Sempre retorna `true`.

### Erros/Exceções

Lança um ValueError se `options` for inválido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.
8.0.0 | Um ValueError agora é lançado em valores de parâmetro `options` inválidos. Anteriormente, um aviso era emitido e a função retornava `false`.

### Veja Também

- imap_setflag_full() - Define sinalizadores em mensagens

# imap_close

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_close — Fecha um fluxo IMAP

### Descrição

function imap_close(IMAP\Connection `$imap`, int `$flags` = 0): true

Fecha o fluxo IMAP.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`flags`

  Se definido como `CL_EXPUNGE`, a função irá silenciosamente expurgar a caixa de correio antes de fechar, removendo todas as mensagens marcadas para exclusão. O mesmo pode ser obtido usando imap_expunge().

### Valor Retornado

Sempre retorna `true`.

### Erros/Exceções

Lança um ValueError se `flags` for inválido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.
8.0.0 | Um ValueError agora é lançado em valores de parâmetro `flags` inválidos. Anteriormente, um aviso era emitido e a função retornava `false`.

### Veja Também

- imap_open() - Abre um fluxo IMAP para uma caixa de correio

# imap_create

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_create — Sinônimo de imap_createmailbox()

### Descrição

Esta função é um apelido para: imap_createmailbox().

# imap_createmailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_createmailbox — Cria uma nova caixa de correio

### Descrição

function imap_createmailbox(IMAP\Connection `$imap`, string `$mailbox`): bool

Cria uma nova caixa de correio especificada por `mailbox`.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`mailbox`

  O nome da caixa de correio, veja imap_open() para mais informações. Nomes contendo caracteres internacionais devem ser codificados por imap_utf7_encode()

  Aviso

  Passar dados não confiáveis para este parâmetro é inseguro, a menos que imap.enable_insecure_rsh esteja desabilitado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imap_createmailbox()

    <?php
    $mbox = imap_open("{imap.example.org}", "username", "password", OP_HALFOPEN)
         or die("Não foi possível conectar: " . imap_last_error());

    $name1 = "phpnewbox";
    $name2 = imap_utf7_encode("phpnewböx"); // phpnewb&w7Y-x

    $newname = $name1;

    echo "O novo nome será '$name1'<br />\n";

    // Agora criaremos uma nova caixa de correio "phptestbox" na pasta de caixa de entrada,
    // verificaremos seu status após a criação e finalmente a
    // removeremos para restaurar a caixa de entrada ao seu estado inicial

    if (@imap_createmailbox($mbox, imap_utf7_encode("{imap.example.org}INBOX.$newname"))) {
        $status = @imap_status($mbox, "{imap.example.org}INBOX.$newname", SA_ALL);
        if ($status) {
            echo "Sua caixa de correio '$name1' tem o seguinte status:<br />\n";
            echo "Messages:   " . $status->messages    . "<br />\n";
            echo "Recent:     " . $status->recent      . "<br />\n";
            echo "Unseen:     " . $status->unseen      . "<br />\n";
            echo "UIDnext:    " . $status->uidnext     . "<br />\n";
            echo "UIDvalidity:" . $status->uidvalidity . "<br />\n";

            if (imap_renamemailbox($mbox, "{imap.example.org}INBOX.$newname", "{imap.example.org}INBOX.$name2")) {
                echo "Renomeada a nova caixa de correio de '$name1' para '$name2'<br />\n";
                $newname = $name2;
            } else {
                echo "imap_renamemailbox na nova caixa de correio falhou: " . imap_last_error() . "<br />\n";
            }
        } else {
            echo "imap_status na nova caixa de correio falhou: " . imap_last_error() . "<br />\n";
        }

        if (@imap_deletemailbox($mbox, "{imap.example.org}INBOX.$newname")) {
            echo "Nova caixa de correio removida para restaurar o status inicial<br />\n";
        } else {
            echo "imap_deletemailbox na nova caixa de correio falhou: " . implode("<br />\n", imap_errors()) . "<br />\n";
        }

    } else {
        echo "Não foi possível criar a nova caixa de correio: " . implode("<br />\n", imap_errors()) . "<br />\n";
    }

    imap_close($mbox);
    ?>

### Veja Também

- imap_renamemailbox() - Renomeia uma caixa de correio antiga para uma nova caixa de correio
- imap_deletemailbox() - Exclui uma caixa de correio

# imap_delete

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_delete — Marca uma mensagem para exclusão da caixa de correio atual

### Descrição

function imap_delete(IMAP\Connection `$imap`, string `$message_nums`, int `$flags` = 0): true

Marca mensagens listadas em `message_nums` para exclusão. Mensagens marcadas para exclusão permanecerão na caixa de correio até que imap_expunge() seja chamada ou imap_close() seja chamada com o parâmetro opcional `CL_EXPUNGE`.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`message_nums`

  Uma string representando uma ou mais mensagens no formato de sequência estilo IMAP4 (`"n"`, `"n:m"` ou uma combinação destes delimitados por vírgulas).

`flags`

  Pode ser definida a `FT_UID` que informa à função para tratar o argumento `message_nums` como um `UID`.

### Valor Retornado

Sempre retorna `true`.

### Erros/Exceções

Lança um ValueError se `flags` for inválido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.
8.0.0 | Um ValueError agora é lançado em valores de parâmetro `flags` inválidos. Anteriormente, um aviso era emitido e a função retornava `false`.

### Exemplos

Exemplo #1 Exemplo de imap_delete()

    <?php

    $mbox = imap_open("{imap.example.org}INBOX", "username", "password")
        or die("Não foi possível conectar: " . imap_last_error());

    $check = imap_mailboxmsginfo($mbox);
    echo "Mensagens antes da exclusão: " . $check->Nmsgs . "<br />\n";

    imap_delete($mbox, 1);

    $check = imap_mailboxmsginfo($mbox);
    echo "Mensagens após a exclusão: " . $check->Nmsgs . "<br />\n";

    imap_expunge($mbox);

    $check = imap_mailboxmsginfo($mbox);
    echo "Mensagens após a expurga: " . $check->Nmsgs . "<br />\n";

    imap_close($mbox);
    ?>

### Notas

> Nota:

> Caixas de correio IMAP podem não ter seus sinalizadores de mensagem salvos entre conexões, então imap_expunge() deve ser chamada durante a mesma conexão para garantir que as mensagens marcadas para exclusão sejam realmente eliminadas.

### Veja Também

- imap_undelete() - Desmarca a mensagem que está marcada como excluída
- imap_expunge() - Exclui todas as mensagens marcadas para exclusão
- imap_close() - Fecha um fluxo IMAP

# imap_deletemailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_deletemailbox — Exclui uma caixa de correio

### Descrição

function imap_deletemailbox(IMAP\Connection `$imap`, string `$mailbox`): bool

Exclui a caixa de correio especificada em `mailbox`.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`mailbox`

  O nome da caixa de correio, veja imap_open() para mais informações.

  Aviso

  Passar dados não confiáveis para este parâmetro é inseguro, a menos que imap.enable_insecure_rsh esteja desabilitado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Veja Também

- imap_createmailbox() - Cria uma nova caixa de correio
- imap_renamemailbox() - Renomeia uma caixa de correio antiga para uma nova caixa de correio
- imap_open() - Abre um fluxo IMAP para uma caixa de correio para o formato de `mbox`

# imap_errors

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_errors — Retorna todos os erros IMAP que ocorreram

### Descrição

function imap_errors(): array|false

Obtém todos os erros IMAP (se ocorreram) durante esta solicitação de página ou desde que a pilha de erros foi redefinida.

Quando imap_errors() é chamada, a pilha de erros é posteriormente limpa.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Esta função retorna um array de todas as mensagens de erro IMAP geradas desde a última chamada de imap_errors(), ou desde o início da página. Retorna `false` se nenhuma mensagem de erro estiver disponível.

### Veja Também

- imap_last_error() - Obtém o último erro IMAP que ocorreu durante esta solicitação de página
- imap_alerts() - Retorna todas as mensagens de alerta IMAP que ocorreram

# imap_expunge

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_expunge — Exclui todas as mensagens marcadas para exclusão

### Descrição

function imap_expunge(IMAP\Connection `$imap`): true

Exclui todas as mensagens marcadas para exclusão por imap_delete(), imap_mail_move() ou imap_setflag_full().

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

# imap_fetch_overview

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetch_overview — Lê uma visão geral das informações nos cabeçalhos da mensagem fornecida

### Descrição

function imap_fetch_overview(IMAP\Connection `$imap`, string `$sequence`, int `$flags` = 0): array|false

Esta função busca cabeçalhos de e-mail para a sequência fornecida em `sequence` e retorna uma visão geral de seus conteúdos.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`sequence`

  Uma descrição de sequência de mensagens. Pode-se enumerar mensagens desejadas com a sintaxe `X,Y` ou recuperar todas as mensagens dentro de um intervalo com a sintaxe `X:Y`.

`flags`

  `sequence` conterá uma sequência de índices de mensagens ou UIDs, se este parâmetro for definido como `FT_UID`.

### Valor Retornado

Retorna um array de objetos descrevendo um cabeçalho de mensagem cada. O objeto só definirá uma propriedade se ela existir. As possíveis propriedades são:

- `subject` - o assunto da mensagem
- `from` - quem enviou
- `to` - destinatário
- `date` - quando foi enviada
- `message_id` - identificador da mensagem
- `references` - é uma referência a esta identificação de mensagem
- `in_reply_to` - é uma resposta a esta identificação de mensagem
- `size` - tamanho em bytes
- `uid` - UID que a mensagem tem na caixa de correio
- `msgno` - número da mensagem na sequência da caixa de correio
- `recent` - esta mensagem está marcada como recente
- `flagged` - esta mensagem está marcada
- `answered` - esta mensagem está marcada como respondida
- `deleted` - esta mensagem está marcada para exclusão
- `seen` - esta mensagem está marcada como já lida
- `draft` - esta mensagem está marcada como um rascunho
- `udate` - o timestamp UNIX da data/horário de chegada

A função retorna `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imap_fetch_overview()

    <?php
    $mbox = imap_open("{imap.example.org:143}INBOX", "username", "password")
         or die("Não foi possível conectar: " . imap_last_error());

    $MC = imap_check($mbox);

    // Obtém uma visão geral de todas as mensagens na caixa INBOX
    $result = imap_fetch_overview($mbox,"1:{$MC->Nmsgs}",0);
    foreach ($result as $overview) {
        echo "#{$overview->msgno} ({$overview->date}) - De: {$overview->from}
        {$overview->subject}\n";
    }
    imap_close($mbox);
    ?>

### Veja Também

- imap_fetchheader() - Retorna o cabeçalho de uma mensagem

# imap_fetchbody

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchbody — Busca uma seção específica do corpo da mensagem

### Descrição

function imap_fetchbody(
IMAP\Connection `$imap`,
int `$message_num`,
string `$section`,
int `$flags` = 0
): string|false

Busca uma seção específica do corpo das mensagens especificadas. Partes do corpo não são decodificadas por esta função.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`message_num`

  O número da mensagem

`section`

  O número da parte. É uma sequência de inteiros delimitados por ponto que são índices de uma lista de partes do corpo conforme a especificação IMAP4.

`flags`

  Uma máscara de bits de uma das seguintes constantes:

  - `FT_UID` - O parâmetro `message_num` é um UID
  - `FT_PEEK` - Não define o marcador \Seen flag se já não estiver definido
  - `FT_INTERNAL` - A string de retorno está em formato interno, não será canonizada para CRLF.

### Valor Retornado

Retorna uma seção específica do corpo das mensagens informadas como uma string de texto, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Veja Também

- imap_savebody() - Salva uma seção específica do corpo em um arquivo
- imap_fetchstructure() - Lê a estrutura de uma mensagem específica

# imap_fetchheader

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchheader — Retorna o cabeçalho de uma mensagem

### Descrição

function imap_fetchheader(IMAP\Connection `$imap`, int `$message_num`, int `$flags` = 0): string|false

Esta função causa uma busca do cabeçalho completo e não filtrado no formato » RFC2822 da mensagem especificada.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`message_num`

  O número da mensagem

`flags`

  Os possíveis valores para `flags` são:

  - `FT_UID` - O argumento `message_num` é um UID
  - `FT_INTERNAL` - A string de retorno está no formato "interno", sem nenhuma tentativa de canonizar para novas linhas CRLF
  - `FT_PREFETCHTEXT` - O RFC822.TEXT deve ser pré-buscado ao mesmo tempo. Isso evita um RTT extra em uma conexão IMAP se um texto de mensagem completo for desejado (por exemplo, em uma operação "salvar em arquivo local")

### Valor Retornado

Retorna o cabeçalho da mensagem especificada como uma sequência de texto, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Veja Também

- imap_fetch_overview() - Lê uma visão geral das informações nos cabeçalhos da mensagem fornecida

# imap_fetchmime

(PHP 5 >= 5.3.6, PHP 7, PHP 8)

imap_fetchmime — Busca cabeçalhos MIME para uma seção específica da mensagem

### Descrição

function imap_fetchmime(
IMAP\Connection `$imap`,
int `$message_num`,
string `$section`,
int `$flags` = 0
): string|false

Busca os cabeçalhos MIME de uma seção específica do corpo das mensagens especificadas.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`message_num`

  O número da mensagem

`section`

  O número da parte. É uma sequência de inteiros delimitados por ponto que são índices de uma lista de partes do corpo conforme a especificação IMAP4.

`flags`

  Uma máscara de bits de uma das seguintes constantes:

  - `FT_UID` - O parâmetro `message_num` é um UID
  - `FT_PEEK` - Não define o marcador \Seen flag se já não estiver definido
  - `FT_INTERNAL` - A string de retorno está em formato interno, não será canonizada para CRLF.

### Valor Retornado

Retorna os cabeçalhos MIME de uma seção específica do corpo das mensagens especificadas como uma string de texto, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Veja Também

- imap_fetchbody() - Busca uma seção específica do corpo da mensagem
- imap_fetchstructure() - Lê a estrutura de uma mensagem específica
- imap_fetchheader() - Retorna o cabeçalho de uma mensagem

# imap_fetchstructure

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchstructure — Lê a estrutura de uma mensagem específica

### Descrição

function imap_fetchstructure(IMAP\Connection `$imap`, int `$message_num`, int `$flags` = 0): stdClass|false

Busca todas as informações estruturadas para uma determinada mensagem.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`message_num`

  O número da mensagem

`flags`

  Este parâmetro opcional tem apenas uma única opção, `FT_UID`, que diz à função para tratar o argumento `message_num` como um `UID`.

### Valor Retornado

Retorna um objeto com propriedades listadas na tabela abaixo, ou `false` em caso de falha.

Objeto retornado para imap_fetchstructure()
type | Tipo de corpo primário
encoding | Codificação de transferência de corpo
ifsubtype | `true` se houver uma string de subtipo
subtype | Subtipo MIME
ifdescription | `true` se houver uma string de descrição
description | String de descrição do conteúdo
ifid | `true` se houver uma string de identificação
id | String de identificação
lines | Número de linhas
bytes | Número de bytes
ifdisposition | `true` se houver uma string de disposição
disposition | String de disposição
ifdparameters | `true` se o array dparameters existir
dparameters | Um array de objetos onde cada objeto tem uma propriedade `"attribute"` e uma propriedade `"value"` correspondente aos parâmetros no cabeçalho MIME `Content-disposition`.
ifparameters | `true` se o array de parâmetros existir
parameters | Um array de objetos onde cada objeto tem uma propriedade `"attribute"` e uma propriedade `"value"`.
parts | Um array de objetos idênticos em estrutura ao objeto de nível superior, cada um dos quais corresponde a uma parte do corpo MIME.

Tipo de corpo primário (o valor pode variar com a biblioteca usada, o uso de constantes é recomendado)
Valor | Tipo | Constante
--- | --- | ---
0 | texto | TYPETEXT
1 | multipartes | TYPEMULTIPART
2 | mensagem | TYPEMESSAGE
3 | aplicação | TYPEAPPLICATION
4 | áudio | TYPEAUDIO
5 | imagem | TYPEIMAGE
6 | vídeo | TYPEVIDEO
7 | modelo | TYPEMODEL
8 | outro | TYPEOTHER

Codificações de transferência (o valor pode variar com a biblioteca usada, o uso de constantes é recomendado)
Valor | Tipo | Constante
--- | --- | ---
0 | 7 bits | ENC7BIT
1 | 8 bits | ENC8BIT
2 | Binária | ENCBINARY
3 | Base64 | ENCBASE64
4 | Escapada-Imprimível | ENCQUOTEDPRINTABLE
5 | Outra | ENCOTHER

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Veja Também

- imap_fetchbody() - Busca uma seção específica do corpo da mensagem
- imap_bodystruct() - Lê a estrutura de uma seção específica do corpo de uma mensagem específica

# imap_fetchtext

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchtext — Sinônimo de imap_body()

### Descrição

Esta função é um apelido para: imap_body().

# imap_gc

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

imap_gc — Limpa o cache IMAP

### Descrição

function imap_gc(IMAP\Connection `$imap`, int `$flags`): true

Limpa o cache de entradas de um tipo específico.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`flags`

  Especifica o cache a ser purgado. Pode ser uma ou mais das seguintes constantes combinadas: `IMAP_GC_ELT` (elementos de cache de mensagens), `IMAP_GC_ENV` (envelope e corpos), `IMAP_GC_TEXTS` (textos).

### Valor Retornado

Sempre retorna `true`.

### Erros/Exceções

Lança um ValueError se `flags` for inválido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.
8.0.0 | Um ValueError agora é lançado em valores de parâmetro `flags` inválidos. Anteriormente, um aviso era emitido e a função retornava `false`.

### Exemplos

Exemplo #1 Exemplo de imap_gc()

    <?php

    $mbox = imap_open("{imap.example.org:143}", "username", "password");

    imap_gc($mbox, IMAP_GC_ELT);

    ?>

# imap_get_quota

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

imap_get_quota — Recupera as configurações de nível de cota e estatísticas de uso por caixa de correio

### Descrição

function imap_get_quota(IMAP\Connection `$imap`, string `$quota_root`): array|false

Recupera as configurações de nível de cota e estatísticas de uso por caixa de correio.

Para uma versão desta função para usuários não administradores, consulte a função imap_get_quotaroot() do PHP.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`quota_root`

  `quota_root` normalmente deve estar no formato de `user.name` onde name é a caixa de correio sobre a qual se deseja recuperar informações.

### Valor Retornado

Retorna um array com valores inteiros de limite ("limit") e uso ("usage") para a caixa de correio fornecida. O valor de limite representa a quantidade total de espaço permitida para esta caixa de correio. O valor de uso representa o nível atual de capacidade da caixa de correio. Retornará `false` em caso de falha.

A partir do PHP 4.3, a função reflete mais adequadamente a funcionalidade conforme ditado pela » RFC2087. O valor de retorno do array foi alterado para suportar um número ilimitado de recursos retornados (por exemplo, mensagens ou subpastas) com cada recurso nomeado recebendo uma chave de array individual. Cada valor de chave contém então um outro array com os valores de uso e limite dentro dele.

Por razões de compatibilidade com versões anteriores, os métodos de acesso originais ainda estão disponíveis para uso, embora seja sugerido atualizá-los.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imap_get_quota()

    <?php
    $mbox = imap_open("{imap.example.org}", "mailadmin", "password", OP_HALFOPEN)
          or die("Não foi possível conectar: " . imap_last_error());

    $quota_value = imap_get_quota($mbox, "user.kalowsky");
    if (is_array($quota_value)) {
        echo "Nível de uso é: " . $quota_value['usage'];
        echo "Nível de limite é: " . $quota_value['limit'];
    }

    imap_close($mbox);
    ?>

Exemplo #2 Exemplo de imap_get_quota() para versão 4.3 ou superior

    <?php
    $mbox = imap_open("{imap.example.org}", "mailadmin", "password", OP_HALFOPEN)
          or die("Não foi possível conectar: " . imap_last_error());

    $quota_values = imap_get_quota($mbox, "user.kalowsky");
    if (is_array($quota_values)) {
       $storage = $quota_values['STORAGE'];
       echo "Nível de uso STORAGE é: " .  $storage['usage'];
       echo "Nível de limite STORAGE é: " .  $storage['limit'];

       $message = $quota_values['MESSAGE'];
       echo "Nível de uso MESSAGE é: " .  $message['usage'];
       echo "Nível de limite MESSAGE é: " .  $message['limit'];

       /* ...  */
    }

    imap_close($mbox);
    ?>

### Notas

Esta função está disponível atualmente apenas para usuários da biblioteca c-client2000 ou superior.

O `imap` fornecido deve ser aberto como administrador de e-mail, caso contrário, esta função falhará.

### Veja Também

- imap_open() - Abre um fluxo IMAP para uma caixa de correio
- imap_set_quota() - Define uma cota para uma determinada caixa de correio
- imap_get_quotaroot() - Recupera as configurações de cota por usuário

# imap_get_quotaroot

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imap_get_quotaroot — Recupera as configurações de cota por usuário

### Descrição

function imap_get_quotaroot(IMAP\Connection `$imap`, string `$mailbox`): array|false

Recupera as configurações de cota por usuário. O valor limite representa a quantidade total de espaço permitida para o uso total da caixa de correio deste usuário. O valor de uso representa a capacidade total atual da caixa de correio do usuário.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`mailbox`

  `mailbox` normalmente deve estar no formato de identificação da caixa de correio (ou seja, INBOX).

### Valor Retornado

Retorna um array de valores inteiros pertencentes à caixa de correio do usuário especificado. Todos os valores contêm uma chave com base no nome do recurso e um array correspondente com os valores de uso e limite internamente.

Esta função retornará `false` no caso de falha de chamada, e um array de informações sobre a conexão mediante uma resposta não analisável do servidor.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imap_get_quotaroot()

    <?php
    $mbox = imap_open("{imap.example.org}", "kalowsky", "password", OP_HALFOPEN)
          or die("Não foi possível conectar: " . imap_last_error());

    $quota = imap_get_quotaroot($mbox, "INBOX");
    if (is_array($quota)) {
       $storage = $quota['STORAGE'];
       echo "Nível de uso de STORAGE: " .  $storage['usage'];
       echo "Nível limite de STORAGE: " .  $storage['limit'];

       $message = $quota['MESSAGE'];
       echo "Nível de uso de MESSAGE: " .  $message['usage'];
       echo "Nível limite de MESSAGE: " .  $message['limit'];

       /* ...  */

    }

    imap_close($mbox);
    ?>

### Notas

Esta função está disponível atualmente apenas para usuários da biblioteca c-client2000 ou superior.

O `imap` deve ser aberto como o usuário cuja caixa de correio deve ser verificada.

### Veja Também

- imap_open() - Abre um fluxo IMAP para uma caixa de correio
- imap_set_quota() - Define uma cota para uma determinada caixa de correio
- imap_get_quota() - Recupera as configurações de nível de cota e estatísticas de uso por caixa de correio

# imap_getacl

(PHP 5, PHP 7, PHP 8)

imap_getacl — Obtém a ACL para uma determinada caixa de correio

### Descrição

function imap_getacl(IMAP\Connection `$imap`, string `$mailbox`): array|false

Obtém a ACL para uma determinada caixa de correio.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`mailbox`

  O nome da caixa de correio, veja imap_open() para mais informações

  Aviso

  Passar dados não confiáveis para este parâmetro é inseguro, a menos que imap.enable_insecure_rsh esteja desabilitado.

### Valor Retornado

Retorna um array associativo de pares "folder" => "acl", ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imap_getacl()

    <?php

    print_r(imap_getacl($imap, 'user.joecool'));

    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [asubfolder] => lrswipcda
        [anothersubfolder] => lrswipcda
    )

### Notas

Esta função está disponível atualmente apenas para usuários da biblioteca c-client2000 ou superior.

### Veja Também

- imap_setacl() - Define a ACL para uma determinada caixa de correio

# imap_getmailboxes

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_getmailboxes — Lê a lista de caixas de correio, retornando informações detalhadas sobre cada uma delas

### Descrição

function imap_getmailboxes(IMAP\Connection `$imap`, string `$reference`, string `$pattern`): array|false

Obtém informações sobre as caixas de correio.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`reference`

  `reference` normalmente deve ser apenas a especificação do servidor conforme descrito em imap_open()

  Aviso

  Passar dados não confiáveis para este parâmetro é inseguro, a menos que imap.enable_insecure_rsh esteja desabilitado.

`pattern`
  Especifica onde iniciar a pesquisa na hierarquia da caixa de mensagem.Existem dois caracteres especiais que podem ser passados como parte do parâmetro `pattern`: '`*`' e '`%`'. '`*`' significa retornar todas as caixas de mensagem. Se `pattern` for passado como '`*`', será retornada uma lista de toda a hierarquia da caixa de mensagem. '`%`' significa retornar apenas o nível atual. Passar '`%`' como o parâmetro `pattern` retornará apenas as caixas de mensagem do nível mais alto; Passar '`~/mail/%`' em `UW_IMAPD` retornará todas as caixas de mensagem no diretório ~/mail, mas não retornará nenhuma nas subpastas deste diretório.

### Valor Retornado

Retorna um array de objetos contendo informações da caixa de correio. Cada objeto tem os atributos `name`, especificando o nome completo da caixa de correio; `delimiter`, que é o delimitador de hierarquia para a parte da hierarquia em que esta caixa de correio está; e `attributes`. `Attributes` é uma máscara de bits que pode ser testada em relação a:

- `LATT_NOINFERIORS` - Esta caixa de correio não contém, e não pode conter nenhuma "filha" (não há caixas de correio abaixo desta). Chamar imap_createmailbox() não funcionará nesta caixa de correio.

- `LATT_NOSELECT` - Isto é apenas um contêiner, não uma caixa de correio - não se pode abri-lo.

- `LATT_MARKED` - Esta caixa de correio está marcada. Isso significa que ela pode conter novas mensagens desde a última vez que foi verificada. Não fornecido por todos os servidores IMAP.

- `LATT_UNMARKED` - Esta caixa de correio não está marcada, não contém novas mensagens. Se `MARKED` ou `UNMARKED` for fornecido, pode-se assumir que o servidor IMAP suporta esse recurso para esta caixa de correio.

- `LATT_REFERRAL` - Este contêiner tem uma referência para uma caixa de correio remota.

- `LATT_HASCHILDREN` - Esta caixa de correio tem filhas selecionáveis.

- `LATT_HASNOCHILDREN` - Esta caixa de correio não possui filhas selecionáveis.

A função retorna `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imap_getmailboxes()

    <?php
    $mbox = imap_open("{imap.example.org}", "username", "password", OP_HALFOPEN)
          or die("Não foi possível conectar: " . imap_last_error());

    $list = imap_getmailboxes($mbox, "{imap.example.org}", "*");
    if (is_array($list)) {
        foreach ($list as $key => $val) {
            echo "($key) ";
            echo imap_utf7_decode($val->name) . ",";
            echo "'" . $val->delimiter . "',";
            echo $val->attributes . "<br />\n";
        }
    } else {
        echo "imap_getmailboxes falhou: " . imap_last_error() . "\n";
    }

    imap_close($mbox);
    ?>

### Veja Também

- imap_getsubscribed() - Lista todas as caixas de correio assinadas

# imap_getsubscribed

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_getsubscribed — Lista todas as caixas de correio assinadas

### Descrição

function imap_getsubscribed(IMAP\Connection `$imap`, string `$reference`, string `$pattern`): array|false

Obtém informações sobre as caixas de correio assinadas.

Idêntico a imap_getmailboxes(), exceto que ele apenas retorna caixas de correio nas quais o usuário está inscrito.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`reference`

  `reference` normalmente deve ser apenas a especificação do servidor conforme descrito em imap_open()

  Aviso

  Passar dados não confiáveis para este parâmetro é inseguro, a menos que imap.enable_insecure_rsh esteja desabilitado.

`pattern`
  Especifica onde iniciar a pesquisa na hierarquia da caixa de mensagem.Existem dois caracteres especiais que podem ser passados como parte do parâmetro `pattern`: '`*`' e '`%`'. '`*`' significa retornar todas as caixas de mensagem. Se `pattern` for passado como '`*`', será retornada uma lista de toda a hierarquia da caixa de mensagem. '`%`' significa retornar apenas o nível atual. Passar '`%`' como o parâmetro `pattern` retornará apenas as caixas de mensagem do nível mais alto; Passar '`~/mail/%`' em `UW_IMAPD` retornará todas as caixas de mensagem no diretório ~/mail, mas não retornará nenhuma nas subpastas deste diretório.

### Valor Retornado

Retorna um array de objetos contendo informações da caixa de correio. Cada objeto tem os atributos `name`, especificando o nome completo da caixa de correio; `delimiter`, que é o delimitador de hierarquia para a parte da hierarquia em que esta caixa de correio está; e `attributes`. `Attributes` é uma máscara de bits que pode ser testada em relação a:

- `LATT_NOINFERIORS` - Esta caixa de correio não tem "filhas" (não há caixas de correio abaixo desta).
- `LATT_NOSELECT` - Isto é apenas um contêiner, não uma caixa de correio - não se pode abri-lo.
- `LATT_MARKED` - Esta caixa de correio está marcada. Usado somente por UW-IMAPD.
- `LATT_UNMARKED` - Esta caixa de correio não está marcada. Usada somente por UW-IMAPD.
- `LATT_REFERRAL` - Este contêiner tem uma referência para uma caixa de correio remota.
- `LATT_HASCHILDREN` - Esta caixa de correio tem filhas selecionáveis.
- `LATT_HASNOCHILDREN` - Esta caixa de correio não tem filhas selecionáveis.

A função retorna `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

# imap_header

(PHP 4, PHP 5, PHP 7)

imap_header — Sinônimo de imap_headerinfo()

Aviso

Este apelido foi REMOVIDO a partir do PHP 8.0.0.

### Descrição

Esta função é um apelido para: imap_headerinfo().

# imap_headerinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_headerinfo — Lê o cabeçalho da mensagem

### Descrição

function imap_headerinfo(
IMAP\Connection `$imap`,
int `$message_num`,
int `$from_length` = 0,
int `$subject_length` = 0
): stdClass|false

Obtém informações sobre o número da mensagem fornecida lendo seus cabeçalhos.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`message_num`

  O número da mensagem

`from_length`

  Número de caracteres para a propriedade `fetchfrom`. Deve ser maior ou igual a zero.

`subject_length`

  Número de caracteres para a propriedade `fetchsubject` Deve ser maior ou igual a zero.

### Valor Retornado

Retorna `false` em caso de erro ou, em caso de sucesso, as informações em um objeto com as seguintes propriedades:

- toaddress - linha completa "to:", com até 1024 caracteres
- to - um array de objetos da linha "To:", com as seguintes propriedades: `personal`, `adl`, `mailbox` e `host`
- fromaddress - linha completa "from:", com até 1024 caracteres
- from - um array de objetos da linha "From:", com as seguintes propriedades: `personal`, `adl`, `mailbox` e `host`
- ccaddress - linha completa "cc:", com até 1024 caracteres
- cc - um array de objetos da linha "Cc:", com as seguintes propriedades: `personal`, `adl`, `mailbox` e `host`
- bccaddress - linha completa "bcc:", com até 1024 caracteres
- bcc - um array de objetos da linha "Bcc:", com as seguintes propriedades: `personal`, `adl`, `mailbox` e `host`
- reply_toaddress - linha completa "Reply-To:", com até 1024 caracteres
- reply_to - um array de objetos da linha "Reply-To:", com as seguintes propriedades: `personal`, `adl`, `mailbox` e `host`
- senderaddress - linha completa "sender:", com até 1024 caracteres
- sender - um array de objetos da linha "Sender:", com as seguintes propriedades: `personal`, `adl`, `mailbox` e `host`
- return_pathaddress - linha completa "Return-Path:", com até 1024 caracteres
- return_path - um array de objetos da linha "Return-Path:", com as seguintes propriedades: `personal`, `adl`, `mailbox` e `host`
- remail -
- date - A data da mensagem conforme encontrada nos cabeçalhos
- Date - O mesmo que "date"
- subject - O assunto da mensagem
- Subject - O mesmo que "subject"
- in_reply_to -
- message_id -
- newsgroups -
- followup_to -
- references -
- Recent - `R` se recente e visto, `N` se recente e não visto, ' ' se não for recente.
- Unseen - `U` se não visto E não recente, ' ' se visto OU não visto e recente
- Flagged - `F` se marcada, ' ' se não marcada
- Answered - `A` se respondida, ' ' se não respondida
- Deleted - `D` se excluída, ' ' se não excluída
- Draft - `X` se for rascunho, ' ' se não for rascunho
- Msgno - O número da mensagem
- MailDate -
- Size - O tamanho da mensagem
- udate - data da mensagem de correio em timestamp Unix
- fetchfrom - linha "from:" formatada para caber em `from_length` caracteres
- fetchsubject - linha "subject:" formatada para caber em `subject_length` caaracteres

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.
8.0.0 | O parâmetro `defaulthost` não utilizado foi removido.

### Veja Também

- imap_fetch_overview() - Lê uma visão geral das informações nos cabeçalhos da mensagem fornecida

# imap_headers

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_headers — Retorna cabeçalhos para todas as mensagens em uma caixa de correio

### Descrição

function imap_headers(IMAP\Connection `$imap`): array|false

Retorna cabeçalhos para todas as mensagens em uma caixa de correio.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.

### Valor Retornado

Retorna um array de strings formatado com informações de cabeçalho. Um elemento por mensagem. Retorna `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

# imap_is_open

(PHP 8 >= 8.2.1)

imap_is_open — Verifica se o fluxo IMAP ainda é válido

### Descrição

function imap_is_open(IMAP\Connection `$imap`): bool

Verifica se o fluxo IMAP ainda é válido.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.

### Valor Retornado

Retorna `true` se o fluxo ainda for válido, `false` caso contrário.

### Exemplos

Exemplo #1 Exemplo de imap_is_open()

    <?php
    $mbox = imap_open("{imap.example.org:143}INBOX", "username", "password") or die(implode(", ", imap_errors()));
    imap_is_open($mbox);
    // ...
    ?>

# imap_last_error

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_last_error — Obtém o último erro IMAP que ocorreu durante esta solicitação de página

### Descrição

function imap_last_error(): string|false

Obtém o texto completo da última mensagem de erro IMAP que ocorreu na página atual. A pilha de erros não é tocada; chamar imap_last_error() subsequentemente, sem erros intervenientes, retornará o mesmo erro.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o texto completo da última mensagem de erro IMAP que ocorreu na página atual. Retorna `false` se nenhuma mensagem de erro estiver disponível.

### Veja Também

- imap_errors() - Retorna todos os erros IMAP que ocorreram

# imap_list

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_list — Lê a lista de caixas de correio

### Descrição

function imap_list(IMAP\Connection `$imap`, string `$reference`, string `$pattern`): array|false

Lê a lista de caixas de correio.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`reference`

  `reference` normalmente deve ser apenas a especificação do servidor conforme descrito em imap_open().

  Aviso

  Passar dados não confiáveis para este parâmetro é inseguro, a menos que imap.enable_insecure_rsh esteja desabilitado.

`pattern`
  Especifica onde iniciar a pesquisa na hierarquia da caixa de mensagem.Existem dois caracteres especiais que podem ser passados como parte do parâmetro `pattern`: '`*`' e '`%`'. '`*`' significa retornar todas as caixas de mensagem. Se `pattern` for passado como '`*`', será retornada uma lista de toda a hierarquia da caixa de mensagem. '`%`' significa retornar apenas o nível atual. Passar '`%`' como o parâmetro `pattern` retornará apenas as caixas de mensagem do nível mais alto; Passar '`~/mail/%`' em `UW_IMAPD` retornará todas as caixas de mensagem no diretório ~/mail, mas não retornará nenhuma nas subpastas deste diretório.

### Valor Retornado

Retorna um array contendo os nomes das caixas de correio ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imap_list()

    <?php
    $mbox = imap_open("{imap.example.org}", "username", "password", OP_HALFOPEN)
          or die("Não foi possível conectar: " . imap_last_error());

    $list = imap_list($mbox, "{imap.example.org}", "*");
    if (is_array($list)) {
        foreach ($list as $val) {
            echo imap_utf7_decode($val) . "\n";
        }
    } else {
        echo "imap_list falhou: " . imap_last_error() . "\n";
    }

    imap_close($mbox);
    ?>

### Veja Também

- imap_getmailboxes() - Lê a lista de caixas de correio, retornando informações detalhadas sobre cada uma delas
- imap_lsub() - Lista todas as caixas de correio assinadas

# imap_listmailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_listmailbox — Sinônimo de imap_list()

### Descrição

Esta função é um apelido para: imap_list().

# imap_listscan

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_listscan — Retorna a lista de caixas de correio que correspondem ao texto fornecido

### Descrição

function imap_listscan(
IMAP\Connection `$imap`,
string `$reference`,
string `$pattern`,
string `$content`
): array|false

Retorna um array contendo os nomes das caixas de correio que têm `content` no texto da caixa de correio.

Esta função é semelhante a imap_listmailbox(), mas também verificará a presença da string `content` dentro dos dados da caixa de correio.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`reference`

  `reference` normalmente deve ser apenas a especificação do servidor conforme descrito em imap_open()

  Aviso

  Passar dados não confiáveis para este parâmetro é inseguro, a menos que imap.enable_insecure_rsh esteja desabilitado.

`pattern`
  Especifica onde iniciar a pesquisa na hierarquia da caixa de mensagem.Existem dois caracteres especiais que podem ser passados como parte do parâmetro `pattern`: '`*`' e '`%`'. '`*`' significa retornar todas as caixas de mensagem. Se `pattern` for passado como '`*`', será retornada uma lista de toda a hierarquia da caixa de mensagem. '`%`' significa retornar apenas o nível atual. Passar '`%`' como o parâmetro `pattern` retornará apenas as caixas de mensagem do nível mais alto; Passar '`~/mail/%`' em `UW_IMAPD` retornará todas as caixas de mensagem no diretório ~/mail, mas não retornará nenhuma nas subpastas deste diretório.
`content`

  A string pesquisada

### Valor Retornado

Retorna um array contendo os nomes das caixas de correio que têm `content` no texto da caixa de correio, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Veja Também

- imap_listmailbox() - Sinônimo de imap_list
- imap_search() - Esta função retorna um array de mensagens que correspondem aos critérios de pesquisa fornecidos

# imap_listsubscribed

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_listsubscribed — Sinônimo de imap_lsub()

### Descrição

Esta função é um apelido para: imap_lsub().

# imap_lsub

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_lsub — Lista todas as caixas de correio assinadas

### Descrição

function imap_lsub(IMAP\Connection `$imap`, string `$reference`, string `$pattern`): array|false

Obtém um array de todas as caixas de correio assinadas.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`reference`

  `reference` normalmente deve ser apenas a especificação do servidor conforme descrito em imap_open()

  Aviso

  Passar dados não confiáveis para este parâmetro é inseguro, a menos que imap.enable_insecure_rsh esteja desabilitado.

`pattern`
  Especifica onde iniciar a pesquisa na hierarquia da caixa de mensagem.Existem dois caracteres especiais que podem ser passados como parte do parâmetro `pattern`: '`*`' e '`%`'. '`*`' significa retornar todas as caixas de mensagem. Se `pattern` for passado como '`*`', será retornada uma lista de toda a hierarquia da caixa de mensagem. '`%`' significa retornar apenas o nível atual. Passar '`%`' como o parâmetro `pattern` retornará apenas as caixas de mensagem do nível mais alto; Passar '`~/mail/%`' em `UW_IMAPD` retornará todas as caixas de mensagem no diretório ~/mail, mas não retornará nenhuma nas subpastas deste diretório.

### Valor Retornado

Retorna um array de todas as caixas de correio assinadas, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Veja Também

- imap_list() - Lê a lista de caixas de correio
- imap_getmailboxes() - Lê a lista de caixas de correio, retornando informações detalhadas sobre cada uma delas

# imap_mail

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail — Envia uma mensagem de e-mail

### Descrição

function imap_mail(
string `$to`,
string `$subject`,
string `$message`,
?string `$additional_headers` = `null`,
?string `$cc` = `null`,
?string `$bcc` = `null`,
?string `$return_path` = `null`
): bool

Esta função permite o envio de e-mails com o tratamento correto de destinatários Cc e Bcc.

Os parâmetros `to`, `cc` e `bcc` são todos strings e são todos analisados como listas de endereços » RFC822.

### Parâmetros

`to`

  O destinatário

`subject`

  O assunto do e-mail

`message`

  O corpo do e-mail, veja imap_mail_compose()

`additional_headers`

  Como string com cabeçalhos adicionais a serem definidos no e-mail

`cc`

`bcc`

  Os destinatários especificados em `bcc` receberão o e-mail, mas serão excluídos dos cabeçalhos.

`return_path`

  Use este parâmetro para especificar o caminho de retorno em caso de falha na entrega de e-mail. Isso é útil ao usar PHP como um cliente de e-mail para vários usuários.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `additional_headers`, `cc`, `bcc` e `return_path` agora podem ser nulos.

### Veja Também

- mail() - Envia e-mail
- imap_mail_compose() - Cria uma mensagem MIME com base nas seções de envelope e corpo fornecidas

# imap_mail_compose

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail_compose — Cria uma mensagem MIME com base nas seções de envelope e corpo fornecidas

### Descrição

function imap_mail_compose(array `$envelope`, array `$bodies`): string|false

Cria uma mensagem MIME com base nas seções `envelope` e `bodies` fornecidas.

### Parâmetros

`envelope`

  Um array associativo de campos de cabeçalho. As chaves válidas são: `"remail"`, `"return_path"`, `"date"`, `"from"`, `"reply_to"`, `"in_reply_to"`, `"subject"`, `"to"`, `"cc"`, `"bcc"` e `"message_id"`, que definem os respectivos cabeçalhos de mensagem para a string fornecida. Para definir cabeçalhos adicionais, a chave `"custom_headers"` é suportada, que espera um array desses cabeçalhos, por exemplo, `["User-Agent: My Mail Client"]`.

`bodies`

  Um array indexado de corpos. O primeiro corpo é o corpo principal da mensagem; somente se ele tiver um tipo de `TYPEMULTIPART`, corpos adicionais são processados; esses corpos constituem os corpos das partes.

  Body Array Structure
  Chave | Tipo | Descrição
  --- | --- | ---
  `type` | int | O tipo MIME. Uma das constantes `TYPETEXT` (default), `TYPEMULTIPART`, `TYPEMESSAGE`, `TYPEAPPLICATION`, `TYPEAUDIO`, `TYPEIMAGE`, `TYPEMODEL` ou `TYPEOTHER`.
  `encoding` | int | O `Content-Transfer-Encoding`. Uma das constantes `ENC7BIT` (padrão), `ENC8BIT`, `ENCBINARY`, `ENCBASE64`, `ENCQUOTEDPRINTABLE` ou `ENCOTHER`.
  `charset` | string | O parâmetro de conjunto de caracteres do tipo MIME.
  `type.parameters` | array | Um array associativo de nomes de parâmetros `Content-Type` e seus valores.
  `subtype` | string | O subtipo MIME, por exemplo, `'jpeg'` para `TYPEIMAGE`.
  `id` | string | O `Content-ID`.
  `description` | string | O `Content-Description`.
  `disposition.type` | string | O `Content-Disposition`, por exemplo, `'attachment'`.
  `disposition` | array | Um array associativo de nomes e valores de parâmetros `Content-Disposition`.
  `contents.data` | string | A carga útil.
  `lines` | int | O tamanho da carga útil em linhas.
  `bytes` | int | O tamanho da carga útil em bytes.
  `md5` | string | A soma de verificação MD5 da carga útil.

### Valor Retornado

Retorna a mensagem MIME como string, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de imap_mail_compose()

    <?php

    $envelope["from"]= "joe@example.com";
    $envelope["to"]  = "foo@example.com";
    $envelope["cc"]  = "bar@example.com";

    $part1["type"] = TYPEMULTIPART;
    $part1["subtype"] = "mixed";

    $filename = "/tmp/imap.c.gz";
    $fp = fopen($filename, "r");
    $contents = fread($fp, filesize($filename));
    fclose($fp);

    $part2["type"] = TYPEAPPLICATION;
    $part2["encoding"] = ENCBINARY;
    $part2["subtype"] = "octet-stream";
    $part2["description"] = basename($filename);
    $part2["contents.data"] = $contents;

    $part3["type"] = TYPETEXT;
    $part3["subtype"] = "plain";
    $part3["description"] = "description3";
    $part3["contents.data"] = "contents.data3\n\n\n\t";

    $body[1] = $part1;
    $body[2] = $part2;
    $body[3] = $part3;

    echo nl2br(imap_mail_compose($envelope, $body));

    ?>

# imap_mail_copy

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail_copy — Copia mensagens especificadas para uma caixa de correio

### Descrição

function imap_mail_copy(
IMAP\Connection `$imap`,
string `$message_nums`,
string `$mailbox`,
int `$flags` = 0
): bool

Copia mensagens de e-mail especificadas por `message_nums` para a caixa de correio especificada.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`message_nums`

  `message_nums` é um intervalo, não apenas números de mensagens (conforme descrito em » RFC2060).

`mailbox`

  O nome da caixa de correio, veja imap_open() para mais informações

  Aviso

  Passar dados não confiáveis para este parâmetro é inseguro, a menos que imap.enable_insecure_rsh esteja desabilitado.

`flags`

  `flags` é uma máscara de bits de uma ou mais das constantes a seguir:

  - `CP_UID` - os números de sequência contêm UIDS
  - `CP_MOVE` - Exclui as mensagens da caixa de correio atual após a cópia. Se este sinalizador estiver definido, a função se comporta de forma idêntica a imap_mail_move().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Veja Também

- imap_mail_move() - Move mensagens especificadas para uma caixa de correio

# imap_mail_move

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail_move — Move mensagens especificadas para uma caixa de correio

### Descrição

function imap_mail_move(
IMAP\Connection `$imap`,
string `$message_nums`,
string `$mailbox`,
int `$flags` = 0
): bool

Move mensagens de correio especificadas por `message_nums` para a caixa especificada em `mailbox`. Observe que as mensagens de correio são, na verdade, copiadas para a caixa `mailbox`, e as mensagens originais são sinalizadas para exclusão. Isso implica que as mensagens em `mailbox` recebem novos UIDs.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`message_nums`

  `message_nums` é um intervalo e não só números de mensagens (como descrito em » RFC2060).

`mailbox`

  O nome da caixa de correio, consulte imap_open() para mais informação.

  Aviso

  Passar dados não confiáveis para este parâmetro é inseguro, a menos que imap.enable_insecure_rsh esteja desabilitado.

`flags`

  `flags` é uma máscara de bits e pode conter esta única opção:

  - `CP_UID` - os números de sequência contêm UIDS

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Notas

> Nota:

> imap_mail_move() irá sinalizar a mensagem original com a marca de exclusão. Para excluí-la, é necessário chamar a função imap_expunge().

### Veja Também

- imap_mail_copy() - Copia mensagens especificadas para uma caixa de correio

# imap_mailboxmsginfo

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mailboxmsginfo — Obtém informações sobre a caixa de correio atual

### Descrição

function imap_mailboxmsginfo(IMAP\Connection `$imap`): stdClass

Verifica o status atual da caixa de correio no servidor. É semelhante a imap_status(), mas também somará o tamanho de todas as mensagens na caixa de correio, o que levará algum tempo adicional para executar.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.

### Valor Retornado

Retorna as informações em um objeto com as seguintes propriedades:

Propriedades da caixa de correio
Date | data da última alteração (data/horário atual)
Driver | driver
Mailbox | nome da caixa de correio
Nmsgs | número de mensagens
Recent | número de mensagens recentes
Unread | número de mensagens não lidas
Deleted | número de mensagens excluídas
Size | tamanho da caixa de correio

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imap_mailboxmsginfo()

    <?php

    $mbox = imap_open("{imap.example.org}INBOX", "username", "password")
          or die("Não foi possível conectar: " . imap_last_error());

    $check = imap_mailboxmsginfo($mbox);

    if ($check) {
        echo "Date: "     . $check->Date    . "<br />\n" ;
        echo "Driver: "   . $check->Driver  . "<br />\n" ;
        echo "Mailbox: "  . $check->Mailbox . "<br />\n" ;
        echo "Messages: " . $check->Nmsgs   . "<br />\n" ;
        echo "Recent: "   . $check->Recent  . "<br />\n" ;
        echo "Unread: "   . $check->Unread  . "<br />\n" ;
        echo "Deleted: "  . $check->Deleted . "<br />\n" ;
        echo "Size: "     . $check->Size    . "<br />\n" ;
    } else {
        echo "imap_mailboxmsginfo() falhou: " . imap_last_error() . "<br />\n";
    }

    imap_close($mbox);

    ?>

# imap_mime_header_decode

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mime_header_decode — Decodifica elementos do cabeçalho MIME

### Descrição

function imap_mime_header_decode(string `$string`): array|false

Decodifica extensões de cabeçalho de mensagem MIME que não são texto ASCII (consulte » RFC2047).

### Parâmetros

`string`

  O texto MIME

### Valor Retornado

Os elementos decodificados são retornados em um array de objetos, onde cada objeto tem duas propriedades, `charset` e `text`.

Se o elemento não foi codificado e, em outras palavras, está em US-ASCII simples, a propriedade `charset` desse elemento é definida como `default`.

A função retorna `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de imap_mime_header_decode()

    <?php
    $text = "=?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@example.com>";

    $elements = imap_mime_header_decode($text);
    for ($i=0; $i<count($elements); $i++) {
        echo "Charset: {$elements[$i]->charset}\n";
        echo "Text: {$elements[$i]->text}\n\n";
    }
    ?>

O exemplo acima produzirá:

    Charset: ISO-8859-1
    Text: Keld Jørn Simonsen

    Charset: default
    Text:  <keld@example.com>

No exemplo acima, teríamos dois elementos, enquanto o primeiro elemento foi codificado anteriormente com ISO-8859-1, e o segundo elemento seria US-ASCII simples.

### Veja Também

- imap_utf8() - Converte texto codificado em MIME para UTF-8

# imap_msgno

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_msgno — Obtém o número da sequência da mensagem para o UID fornecido

### Descrição

function imap_msgno(IMAP\Connection `$imap`, int `$message_uid`): int

Retorna o número da sequência da mensagem para o `message_uid` fornecido.

Esta função é a inversa de imap_uid().

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`message_uid`

  O UID da mensagem

### Valor Retornado

Retorna o número da sequência da mensagem para o `message_uid` fornecido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Veja Também

- imap_uid() - Retorna o UID para o número de sequência da mensagem fornecida

# imap_mutf7_to_utf8

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

imap_mutf7_to_utf8 — Decodifica uma string UTF-7 modificada para UTF-8

### Descrição

function imap_mutf7_to_utf8(string `$string`): string|false

Decodifica uma string UTF-7 modificada (conforme especificado no RFC 2060, seção 5.1.3) para UTF-8.

> Nota:

> Esta função só estará disponível se libcclient exportar utf8_to_mutf7().

### Parâmetros

`string`

  Uma string codificada em UTF-7 modificado.

### Valor Retornado

Retorna `string` convertida para UTF-8, ou `false` em caso de falha.

### Veja Também

- imap_utf8_to_mutf7() - Codifica uma string UTF-8 para UTF-7 modificado

# imap_num_msg

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_num_msg — Obtém o número de mensagens na caixa de correio atual

### Descrição

function imap_num_msg(IMAP\Connection `$imap`): int|false

Obtém o número de mensagens na caixa de correio atual.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.

### Valor Retornado

Retorna o número de mensagens na caixa de correio atual, como um inteiro, ou `false` em caso de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Veja Também

- imap_num_recent() - Obtém o número de mensagens recentes na caixa de correio atual
- imap_status() - Retorna informações de status sobre uma caixa de correio

# imap_num_recent

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_num_recent — Obtém o número de mensagens recentes na caixa de correio atual

### Descrição

function imap_num_recent(IMAP\Connection `$imap`): int

Obtém o número de mensagens recentes na caixa de correio atual.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.

### Valor Retornado

Retorna o número de mensagens recentes na caixa de correio atual, como um inteiro.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Veja Também

- imap_num_msg() - Obtém o número de mensagens na caixa de correio atual
- imap_status() - Retorna informações de status sobre uma caixa de correio

# imap_open

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_open — Abre um fluxo IMAP para uma caixa de correio

### Descrição

function imap_open(
string `$mailbox`,
string `$user`,
string `$password`,
int `$flags` = 0,
int `$retries` = 0,
array `$options` = []
): IMAP\Connection|false

Abre um fluxo IMAP para a caixa de correio informada em `mailbox`.

Esta função também pode ser usada para abrir fluxos para servidores POP3 e NNTP, mas algumas funções e recursos estão disponíveis apenas em servidores IMAP.

### Parâmetros

`mailbox`

  Um nome de caixa de correio consiste em um servidor e um caminho de caixa de correio neste servidor. O nome especial `INBOX` representa a caixa de correio pessoal dos usuários atuais. Nomes de caixa de correio que contêm caracteres internacionais além daqueles no escopo ASCII imprimível precisam ser codificados com imap_utf7_encode().

  Aviso

  Passar dados não confiáveis para este parâmetro é inseguro, a menos que imap.enable_insecure_rsh esteja desabilitado.

  A parte do servidor, que é delimitada por '{' e '}', consiste no nome ou endereço IP do servidor, uma porta opcional (prefixada por ':') e uma especificação de protocolo opcional (prefixada por '/').

  A parte do servidor é obrigatória em todos os parâmetros da caixa de correio.

  Todos os nomes que começam com `{` são nomes remotos e estão no formato `"{" remote_system_name [":" port] [flags] "}" [mailbox_name]` onde:

  - `remote_system_name` - Nome de domínio da Internet ou endereço IP entre colchetes do servidor.
  - `port` - número de porta TCP opcional, o padrão é a porta padrão para esse serviço
  - `flags` - sinalizadores opcionais, veja a tabela a seguir.
  - `mailbox_name` - nome da caixa de correio remota, o padrão é INBOX

  Sinalizadores opcionais para nomes
  Sinalizador | Descrição
  --- | ---
  `/service=`serviço | serviço de acesso à caixa de correio, o padrão é "imap"
  `/user=`usuário | nome de usuário remoto para login no servidor
  `/authuser=`usuário | usuário de autenticação remota; se especificado, este é o nome de usuário cuja senha é usada (por exemplo, administrador)
  `/anonymous` | acesso remoto como usuário anônimo
  `/debug` | registra a telemetria do protocolo no registro de depuração do aplicativo
  `/secure` | não transmite uma senha em texto simples pela rede
  `/imap`, `/imap2`, `/imap2bis`, `/imap4`, `/imap4rev1` | equivalente a `/service=imap`
  `/pop3` | equivalent to `/service=pop3`
  `/nntp` | equivalent a `/service=nntp`
  `/norsh` | não usa rsh ou ssh para estabelecer uma sessão IMAP pré-autenticada
  `/ssl` | usa o `Secure Socket Layer` (SSL) para criptografar a sessão
  `/validate-cert` | valida certificados do servidor TLS/SSL (este é o comportamento padrão)
  `/novalidate-cert` | não valida certificados do servidor TLS/SSL, necessário se o servidor usa certificados autoassinados
  `/tls` | força o uso de `start-TLS` para criptografar a sessão e rejeita conexão com servidores que não o suportam
  `/notls` | não faz uso de `start-TLS` para criptografar a sessão, mesmo com servidores que o suportam
  `/readonly` | solicita abertura de caixa de correio somente leitura (somente IMAP; ignorado em NNTP e um erro com SMTP e POP3)

`user`

  O nome de usuário

`password`

  A senha associada a `user`

`flags`

  O parâmetro `flags` consiste em uma máscara de bits com uma ou mais das seguintes constantes:

  - `OP_READONLY` - Abre a caixa de correio somente leitura
  - `OP_ANONYMOUS` - Não usa ou atualiza um .newsrc para notícias (somente NNTP)
  - `OP_HALFOPEN` - Para nomes IMAP e NNTP, abre uma conexão, mas não abre uma caixa de correio.
  - `CL_EXPUNGE` - Expurga a caixa de correio automaticamente ao fechar a caixa de correio (veja também imap_delete() e imap_expunge())
  - `OP_DEBUG` - Depura negociações de protocolo
  - `OP_SHORTCACHE` - Cache curto (somente `elt`)
  - `OP_SILENT` - Não deixa passar eventos (uso interno)
  - `OP_PROTOTYPE` - Retorna protótipo de driver
  - `OP_SECURE` - Não faz autenticação não segura
`retries`

  Número máximo de tentativas de conexão

`options`

  Parâmetros de conexão, as seguintes chaves (string) podem ser usadas para definir um ou mais parâmetros de conexão:

  - `DISABLE_AUTHENTICATOR` - Desativa propriedades de autenticação

### Valor Retornado

Retorna uma instância IMAP\Connection em caso de sucesso, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Retorna uma instância IMAP\Connection agora; anteriormente, um resource era retornado.

### Exemplos

Exemplo #1 Uso diferente de imap_open()

    <?php
    // Para conectar-se a um servidor IMAP em execução na porta 143 na máquina local,
    // faça o seguinte:
    $mbox = imap_open("{localhost:143}INBOX", "user_id", "password");

    // Para conectar-se a um servidor POP3 na porta 110 no servidor local, use:
    $mbox = imap_open ("{localhost:110/pop3}INBOX", "user_id", "password");

    // Para conectar-se a um servidor SSL IMAP ou POP3, adicione /ssl após a especificação
    // do protocolo:
    $mbox = imap_open ("{localhost:993/imap/ssl}INBOX", "user_id", "password");

    // Para conectar-se a um servidor SSL IMAP ou POP3 com um certificado autoassinado,
    // adicione /ssl/novalidate-cert após a especificação do protocolo:
    $mbox = imap_open ("{localhost:995/pop3/ssl/novalidate-cert}", "user_id", "password");

    // Para conectar a um servidor NNTP na porta 119 no servidor local, use:
    $nntp = imap_open ("{localhost:119/nntp}comp.test", "", "");
    // Para se conectar a um servidor remoto, substitua "localhost" pelo nome ou
    // endereço IP do servidor ao qual se deseja conectar.
    ?>

Exemplo #2 Exemplo de imap_open()

    <?php
    $mbox = imap_open("{imap.example.org:143}", "username", "password");

    echo "<h1>Mailboxes</h1>\n";
    $folders = imap_listmailbox($mbox, "{imap.example.org:143}", "*");

    if ($folders == false) {
        echo "Chamada falhou<br />\n";
    } else {
        foreach ($folders as $val) {
            echo $val . "<br />\n";
        }
    }

    echo "<h1>Cabeçalhos em INBOX</h1>\n";
    $headers = imap_headers($mbox);

    if ($headers == false) {
        echo "Chamada falhou<br />\n";
    } else {
        foreach ($headers as $val) {
            echo $val . "<br />\n";
        }
    }

    imap_close($mbox);
    ?>

### Veja Também

- imap_close() - Fecha um fluxo IMAP

# imap_ping

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_ping — Verifica se o fluxo IMAP ainda está ativo

### Descrição

function imap_ping(IMAP\Connection `$imap`): bool

imap_ping() faz ping no fluxo para ver se ele ainda está ativo. Ele pode descobrir novos e-mails; este é o método preferido para uma "verificação de novos e-mails" periódica, bem como um "monitoramento de atividade" para servidores que têm tempo limite de inatividade.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.

### Valor Retornado

Retorna `true` se o fluxo ainda estiver ativo, `false` caso contrário.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imap_ping()

    <?php

    $imap = imap_open("{imap.example.org}", "mailadmin", "password");

    // depois de esperar um pouco
    if (!imap_ping($imap)) {
        // faz algumas coisas para se reconectar
    }

    ?>

# imap_qprint

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_qprint — Converte uma string imprimível escapada em uma string de 8 bits

### Descrição

function imap_qprint(string `$string`): string|false

Converta uma string imprimível escapada em uma string de 8 bits de acordo com a » RFC2045, seção 6.7.

### Parâmetros

`string`

  Uma string imprimível escapada

### Valor Retornado

Retorna uma string de 8 bits, ou `false` em caso de falha.

### Veja Também

- imap_8bit() - Converte uma string de 8 bits em uma string imprimível escapada

# imap_rename

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rename — Sinônimo de imap_renamemailbox()

### Descrição

Esta função é um apelido para: imap_renamemailbox().

# imap_renamemailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_renamemailbox — Renomeia uma caixa de correio antiga para uma nova caixa de correio

### Descrição

function imap_renamemailbox(IMAP\Connection `$imap`, string `$from`, string `$to`): bool

Esta função renomeia uma caixa de correio antiga para uma nova caixa de correio (veja imap_open() para o formato de nomes para `mbox`).

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`from`

  O antigo nome da caixa de correio, veja imap_open() para mais informações

  Aviso

  Passar dados não confiáveis para este parâmetro é inseguro, a menos que imap.enable_insecure_rsh esteja desabilitado.

`to`

  O novo nome da caixa de correio, veja imap_open() para mais informações

  Aviso

  Passar dados não confiáveis para este parâmetro é inseguro, a menos que imap.enable_insecure_rsh esteja desabilitado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Veja Também

- imap_createmailbox() - Cria uma nova caixa de correio
- imap_deletemailbox() - Exclui uma caixa de correio

# imap_reopen

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_reopen — Reabre o fluxo IMAP para uma nova caixa de correio

### Descrição

function imap_reopen(
IMAP\Connection `$imap`,
string `$mailbox`,
int `$flags` = 0,
int `$retries` = 0
): bool

Reabre o fluxo especificado para uma nova caixa de correio informada em `mailbox` em um servidor IMAP ou NNTP.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`mailbox`

  O nome da caixa de correio, veja imap_open() para mais informações

  Aviso

  Passar dados não confiáveis para este parâmetro é inseguro, a menos que imap.enable_insecure_rsh esteja desabilitado.

`flags`

  Os `flags` são uma máscara de bits com uma ou mais das seguintes constantes:

  - `OP_READONLY` - Abre a caixa de correio somente leitura
  - `OP_ANONYMOUS` - Não usa ou atualiza um .newsrc para notícias (NNTP somente)
  - `OP_HALFOPEN` - Para nomes IMAP e NNTP, abre uma conexão, mas não abre uma caixa de correio.
  - `OP_EXPUNGE` - Expurga e recicla silenciosamente o fluxo
  - `CL_EXPUNGE` - Expurga a caixa de correio automaticamente ao fechar a caixa de correio (veja também imap_delete() e imap_expunge())
`retries`

  Número máximo de tentativas de conexão

### Valor Retornado

Retorna `true` se o fluxo for reaberto, `false` caso contrário.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imap_reopen()

    <?php
    $mbox = imap_open("{imap.example.org:143}INBOX", "username", "password") or die(implode(", ", imap_errors()));
    // ...
    imap_reopen($mbox, "{imap.example.org:143}INBOX.Sent") or die(implode(", ", imap_errors()));
    // ..
    ?>

# imap_rfc822_parse_adrlist

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rfc822_parse_adrlist — Analisa uma string de endereços

### Descrição

function imap_rfc822_parse_adrlist(string `$string`, string `$default_hostname`): array

Analisa a string de endereços conforme definido na » RFC2822 e para cada endereço.

### Parâmetros

`string`

  Uma string contendo endereços

`default_hostname`

  O nome do host padrão

### Valor Retornado

Retorna um array de objetos. As propriedades dos objetos são:

- mailbox - o nome da caixa de correio (nome de usuário)
- host - o nome do host
- personal - o nome pessoal
- adl - rota de origem do domínio

### Exemplos

Exemplo #1 Exemplo de imap_rfc822_parse_adrlist()

    <?php

    $address_string = "Joe Doe <doe@example.com>, postmaster@example.com, root";
    $address_array  = imap_rfc822_parse_adrlist($address_string, "example.com");
    if (!is_array($address_array) || count($address_array) < 1) {
        die("algo está errado\n");
    }

    foreach ($address_array as $id => $val) {
        echo "# $id\n";
        echo "  mailbox : " . $val->mailbox . "\n";
        echo "  host    : " . $val->host . "\n";
        echo "  personal: " . $val->personal . "\n";
        echo "  adl     : " . $val->adl . "\n";
    }
    ?>

O exemplo acima produzirá:

    # 0
      mailbox : doe
      host    : example.com
      personal: Joe Doe
      adl     :
    # 1
      mailbox : postmaster
      host    : example.com
      personal:
      adl     :
    # 2
      mailbox : root
      host    : example.com
      personal:
      adl     :

### Veja Também

- imap_rfc822_parse_headers() - Analisa cabeçalhos de e-mail de uma string

# imap_rfc822_parse_headers

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rfc822_parse_headers — Analisa cabeçalhos de e-mail de uma string

### Descrição

function imap_rfc822_parse_headers(string `$headers`, string `$default_hostname` = "UNKNOWN"): stdClass

Obtém um objeto de vários elementos de cabeçalho, semelhante a imap_header().

### Parâmetros

`headers`

  Os dados dos cabeçalhos analisados

`default_hostname`

  O nome do host padrão

### Valor Retornado

Retorna um objeto semelhante ao retornado por imap_header(), exceto pelos sinalizadores e outras propriedades que vêm do servidor IMAP.

### Veja Também

- imap_rfc822_parse_adrlist() - Analisa uma string de endereços

# imap_rfc822_write_address

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rfc822_write_address — Retorna um endereço de e-mail formatado corretamente, considerando a caixa de correio, o host e as informações pessoais

### Descrição

function imap_rfc822_write_address(string `$mailbox`, string `$hostname`, string `$personal`): string|false

Retorna um endereço de e-mail formatado corretamente, conforme definido na » RFC2822, com as informações necessárias.

### Parâmetros

`mailbox`

  O nome da caixa de correio, veja imap_open() para mais informações

  Aviso

  Passar dados não confiáveis para este parâmetro é inseguro, a menos que imap.enable_insecure_rsh esteja desabilitado.

`hostname`

  A parte do host de e-mail

`personal`

  O nome do proprietário da conta

### Valor Retornado

Retorna uma string com endereço de e-mail formatado corretamente, conforme definido na » RFC2822, ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de imap_rfc822_write_address()

    <?php
    echo imap_rfc822_write_address("hartmut", "example.com", "Hartmut Holzgraefe");
    ?>

O exemplo acima produzirá:

    Hartmut Holzgraefe <hartmut@example.com>

# imap_savebody

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

imap_savebody — Salva uma seção específica do corpo em um arquivo

### Descrição

function imap_savebody(
IMAP\Connection `$imap`,
resource|string|int `$file`,
int `$message_num`,
string `$section` = "",
int `$flags` = 0
): bool

Salva uma parte ou todo o corpo da mensagem especificada.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`file`

  O caminho (string) para o arquivo a ser gravado ou um descritor de arquivo válido retornado por fopen().

`message_num`

  O número da mensagem

`section`

  O número da parte. É uma sequência de inteiros delimitados por ponto que são índices de uma lista de partes do corpo conforme a especificação IMAP4.

`flags`

  Uma máscara de bits de uma das seguintes constantes:

  - `FT_UID` - O `message_num` é um UID
  - `FT_PEEK` - Não define o sinalizador \Seen se ainda não estiver definido
  - `FT_INTERNAL` - A string de retorno está em formato interno, não será canonizada para CRLF.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Veja Também

- imap_fetchbody() - Busca uma seção específica do corpo da mensagem

# imap_scan

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_scan — Sinônimo de imap_listscan()

### Descrição

Esta função é um apelido para: imap_listscan().

# imap_scanmailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_scanmailbox — Sinônimo de imap_listscan()

### Descrição

Esta função é um apelido para: imap_listscan().

# imap_search

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_search — Esta função retorna um array de mensagens que correspondem aos critérios de pesquisa fornecidos

### Descrição

function imap_search(
IMAP\Connection `$imap`,
string `$criteria`,
int `$flags` = `SE_FREE`,
string `$charset` = ""
): array|false

Esta função realiza uma pesquisa na caixa de correio atualmente aberta no fluxo IMAP fornecido.

Por exemplo, para corresponder a todas as mensagens não respondidas enviadas pela mãe, você usaria: "UNANSWERED FROM mãe". As pesquisas parecem não diferenciar maiúsculas de maiúsculas. Esta lista de critérios é de uma leitura do código-fonte do c-client UW e pode estar incompleta ou imprecisa (veja também a » RFC1176, seção "tag SEARCH search_criteria").

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`criteria`

  Uma string, delimitada por espaços, na qual as seguintes palavras-chave são permitidas. Quaisquer argumentos com várias palavras (por exemplo, `FROM "joey smith"`) devem ser citados. Os resultados corresponderão a todas as entradas do parâmetro `criteria`.

  - ALL - retorna todas as mensagens que correspondem ao restante dos critérios
  - ANSWERED - corresponde a mensagens com o sinalizador \\ANSWERED definido
  - BCC "string" - corresponde a mensagens com "string" no campo "Bcc:"
  - BEFORE "data" - corresponde a mensagens com "Date:" antes de "data"
  - BODY "string" - corresponde a mensagens com "string" no corpo da mensagem
  - CC "string" - corresponde a mensagens com "string" no campo "Cc:"
  - DELETED - corresponde a mensagens excluídas
  - FLAGGED - corresponde a mensagens com o sinalizador \\FLAGGED (às vezes chamado de Importante ou Urgente) definido
  - FROM "string" - corresponde a mensagens com "string" no campo "From:"
  - KEYWORD "string" - corresponde a mensagens com "string" como palavra-chave
  - NEW - corresponde a novas mensagens
  - OLD - corresponde a mensagens antigas
  - ON "data" - corresponde a mensagens com "Date:" correspondendo a "data"
  - RECENT - corresponde a mensagens com o sinalizador \\RECENT definido
  - SEEN - corresponde a mensagens que foram lidas (o sinalizador \\SEEN está definido)
  - SINCE "data" - corresponde a mensagens com "Date:" depois de "data"
  - SUBJECT "string" - corresponde a mensagens com "string" em "Subject:"
  - TEXT "string" - corresponde a mensagens com texto "string"
  - TO "string" - corresponde a mensagens com "string" em "To:"
  - UNANSWERED - corresponde a mensagens que não foram respondidas
  - UNDELETED - corresponde a mensagens que não foram excluídas
  - UNFLAGGED - corresponde a mensagens que não estão sinalizadas
  - UNKEYWORD "string" - corresponde a mensagens que não têm a palavra-chave "string"
  - UNSEEN - corresponde a mensagens que ainda não foram lidas
`flags`

  Os valores válidos para `flags` são `SE_UID`, o que faz com que o array retornado contenha UIDs em vez de números de sequência de mensagens.

`charset`

  Conjunto de caracteres MIME a ser usado ao pesquisar strings.

### Valor Retornado

Retorna um array de números de mensagens ou UIDs.

Retorna `false` se não entender os critério de pesquisa informados em `criteria` ou se nenhuma mensagem foi encontrada.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imap_search()

    <?php
    $imap   = imap_open('{imap.example.com:993/imap/ssl}INBOX', 'foo@example.com', 'pass123', OP_READONLY);

    $some   = imap_search($imap, 'SUBJECT "HOWTO be Awesome" SINCE "8 August 2008"', SE_UID);
    $msgnos = imap_search($imap, 'ALL');
    $uids   = imap_search($imap, 'ALL', SE_UID);

    print_r($some);
    print_r($msgnos);
    print_r($uids);
    ?>

O exemplo acima produzirá algo semelhante a:

    Array
    (
        [0] => 4
        [1] => 6
        [2] => 11
    )
    Array
    (
        [0] => 1
        [1] => 2
        [2] => 3
        [3] => 4
        [4] => 5
        [5] => 6
    )
    Array
    (
        [0] => 1
        [1] => 4
        [2] => 6
        [3] => 8
        [4] => 11
        [5] => 12
    )

### Veja Também

- imap_listscan() - Retorna a lista de caixas de correio que correspondem ao texto fornecido

# imap_set_quota

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

imap_set_quota — Define uma cota para uma determinada caixa de correio

### Descrição

function imap_set_quota(IMAP\Connection `$imap`, string `$quota_root`, int `$mailbox_size`): bool

Define uma cota limite superior por caixa de correio.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`quota_root`

  A caixa de correio a ter uma cota definida. Deve seguir o formato padrão IMAP para uma caixa de correio: `user.name`.

`mailbox_size`

  O tamanho máximo (em KB) para o `quota_root`

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imap_set_quota()

    <?php
    $mbox = imap_open("{imap.example.org:143}", "mailadmin", "password");

    if (!imap_set_quota($mbox, "user.kalowsky", 3000)) {
        echo "Erro ao definir cota\n";
        return;
    }

    imap_close($mbox);
    ?>

### Notas

Esta função está disponível atualmente apenas para usuários da biblioteca c-client2000 ou superior.

O `imap` fornecido deve ser aberto como administrador de e-mail, caso contrário, esta função falhará.

### Veja Também

- imap_open() - Abre um fluxo IMAP para uma caixa de correio
- imap_get_quota() - Recupera as configurações de nível de cota e estatísticas de uso por caixa de correio

# imap_setacl

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imap_setacl — Define a ACL para uma determinada caixa de correio

### Descrição

function imap_setacl(
IMAP\Connection `$imap`,
string `$mailbox`,
string `$user_id`,
string `$rights`
): bool

Define a ACL para uma determinada caixa de correio.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`mailbox`

  O nome da caixa de correio, veja imap_open() para mais informações

  Aviso

  Passar dados não confiáveis para este parâmetro é inseguro, a menos que imap.enable_insecure_rsh esteja desabilitado.

`user_id`

  O usuário que receberá os direitos.

`rights`

  Os direitos a serem dados ao usuário. Passar uma string vazia excluirá o acl.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Notas

Esta função está atualmente disponível apenas para usuários da biblioteca c-client2000 ou superior.

### Veja Também

- imap_getacl() - Obtém a ACL para uma determinada caixa de correio

# imap_setflag_full

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_setflag_full — Define sinalizadores em mensagens

### Descrição

function imap_setflag_full(
IMAP\Connection `$imap`,
string `$sequence`,
string `$flag`,
int `$options` = 0
): true

Faz com que um armazenamento adicione o sinalizador `flag` especificado ao conjunto de sinalizadores para as mensagens na sequência informada em `sequence`.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`sequence`

  Uma sequência de números de mensagens. Pode-se enumerar mensagens desejadas com a sintaxe `X,Y` ou recuperar todas as mensagens dentro de um intervalo com a sintaxe `X:Y`

`flag`

  Os sinalizadores que podem ser definir são `\Seen`, `\Answered`, `\Flagged`, `\Deleted` e `\Draft` conforme definido pela » RFC2060.

`options`

  Uma máscara de bits que pode conter a única opção:

  - `ST_UID` - O argumento de sequência contém UIDs em vez de números de sequência

### Valor Retornado

Sempre retorna `true`.

### Erros/Exceções

Lança um ValueError se `options` for inválido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.
8.0.0 | Um ValueError agora é lançado em valores de parâmetro `options` inválidos. Anteriormente, um aviso era emitido e a função retornava `false`.

### Exemplos

Exemplo #1 Exemplo de imap_setflag_full()

    <?php
    $mbox = imap_open("{imap.example.org:143}", "username", "password")
         or die("Não foi possível conectar: " . imap_last_error());

    $status = imap_setflag_full($mbox, "2,5", "\\Seen \\Flagged");

    echo gettype($status) . "\n";
    echo $status . "\n";

    imap_close($mbox);
    ?>

### Veja Também

- imap_clearflag_full() - Limpa sinalizadores em mensagens

# imap_sort

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_sort — Obtém e classifica mensagens

### Descrição

function imap_sort(
IMAP\Connection `$imap`,
int `$criteria`,
bool `$reverse`,
int `$flags` = 0,
?string `$search_criteria` = `null`,
?string `$charset` = `null`
): array|false

Obtém e classifica números de mensagens pelos parâmetros fornecidos.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`criteria`

  Os critérios podem ser um (e somente um) dos seguintes:

  - `SORTDATE` - data da mensagem
  - `SORTARRIVAL` - data de chegada
  - `SORTFROM` - caixa de correio no primeiro endereço de "From"
  - `SORTSUBJECT` - assunto da mensagem
  - `SORTTO` - caixa de correio no primeiro endereço de "To"
  - `SORTCC` - caixa de correio no primeiro endereço de "Cc"
  - `SORTSIZE` - tamanho da mensagem em octetos
`reverse`

  Informa se a classificação deve ser feita na ordem inversa.

`flags`

  The `flags` é uma máscara de bits de uma ou mais das seguintes constantes:

  - `SE_UID` - Retorna UIDs em vez de números de sequência
  - `SE_NOPREFETCH` - Não pré-busca mensagens pesquisadas
`search_criteria`

  String de critérios de pesquisa no formato IMAP2. Para detalhes, veja imap_search().

`charset`

  Conjunto de caracteres MIME a ser usado ao classificar strings.

### Valor Retornado

Retorna um array de números de mensagens classificadas pelos parâmetros fornecidos, ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.
8.0.0 | `reverse` agora é bool em vez de int.
8.0.0 | `search_criteria` e `charset` agora são nullable.

# imap_status

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_status — Retorna informações de status sobre uma caixa de correio

### Descrição

function imap_status(IMAP\Connection `$imap`, string `$mailbox`, int `$flags`): stdClass|false

Obtém informações de status sobre a caixa de correio informada em `mailbox`.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`mailbox`

  O nome da caixa de correio, veja imap_open() para mais informações

  Aviso

  Passar dados não confiáveis para este parâmetro é inseguro, a menos que imap.enable_insecure_rsh esteja desabilitado.

`flags`

  As opções válidas são:

  - `SA_MESSAGES` - define $status->messages para o número de mensagens na caixa de correio
  - `SA_RECENT` - define $status->recent para o número de mensagens recentes na caixa de correio
  - `SA_UNSEEN` - define $status->unseen para o número de mensagens não vistas (novas) na caixa de correio
  - `SA_UIDNEXT` - define $status->uidnext para o próximo UID a ser usado na caixa de correio
  - `SA_UIDVALIDITY` - define $status->uidvalidity para uma constante que altera quando os UIDs para a caixa de correio podem não mais ser válidos
  - `SA_ALL` - define todas as opções acima

### Valor Retornado

Esta função retorna um objeto contendo informações de status, ou `false` em caso de falha. O objeto tem as seguintes propriedades: `messages`, `recent`, `unseen`, `uidnext` e `uidvalidity`.

`flags` também é definido, o qual contém uma máscara de bits que pode ser verificada em relação a qualquer uma das constantes acima.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imap_status()

    <?php
    $mbox = imap_open("{imap.example.com}", "username", "password", OP_HALFOPEN)
          or die("Não foi possível conectar: " . imap_last_error());

    $status = imap_status($mbox, "{imap.example.org}INBOX", SA_ALL);
    if ($status) {
      echo "Mensagens:       " . $status->messages    . "<br />\n";
      echo "Recentes:        " . $status->recent      . "<br />\n";
      echo "Não vistas:      " . $status->unseen      . "<br />\n";
      echo "Próximo UID:     " . $status->uidnext     . "<br />\n";
      echo "Validade do UID: " . $status->uidvalidity . "<br />\n";
    } else {
      echo "imap_status falhou: " . imap_last_error() . "\n";
    }

    imap_close($mbox);
    ?>

# imap_subscribe

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_subscribe — Faz inscrição em uma caixa de correio

### Descrição

function imap_subscribe(IMAP\Connection `$imap`, string `$mailbox`): bool

Faz inscrição em uma nova caixa de correio.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`mailbox`

  O nome da caixa de correio, veja imap_open() para mais informações

  Aviso

  Passar dados não confiáveis para este parâmetro é inseguro, a menos que imap.enable_insecure_rsh esteja desabilitado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Veja Também

- imap_unsubscribe() - Cancela a inscrição em uma caixa de correio

# imap_thread

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imap_thread — Retorna uma árvore de mensagens encadeadas

### Descrição

function imap_thread(IMAP\Connection `$imap`, int `$flags` = `SE_FREE`): array|false

Obtém uma árvore de mensagens encadeadas.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`flags`

### Valor Retornado

imap_thread() retorna um array associativo contendo uma árvore de mensagens encadeadas por `REFERENCES`, ou `false` em caso de erro.

Cada mensagem na caixa de correio atual será representada por três entradas no array resultante:

- $thread["XX.num"] - número da mensagem atual

- $thread["XX.next"]

- $thread["XX.branch"]

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Exemplos

Exemplo #1 Exemplo de imap_thread()

    <?php

    // Aqui estamos exibindo os tópicos de um grupo de notícias, em HTML

    $nntp = imap_open('{news.example.com:119/nntp}some.newsgroup', '', '');
    $threads = imap_thread($nntp);

    foreach ($threads as $key => $val) {
      $tree = explode('.', $key);
      if ($tree[1] == 'num') {
        $header = imap_headerinfo($nntp, $val);
        echo "<ul>\n\t<li>" . $header->fromaddress . "\n";
      } elseif ($tree[1] == 'branch') {
        echo "\t</li>\n</ul>\n";
      }
    }

    imap_close($nntp);

    ?>

# imap_timeout

(PHP 4 >= 4.3.3, PHP 5, PHP 7, PHP 8)

imap_timeout — Define ou busca o tempo limite do imap

### Descrição

function imap_timeout(int `$timeout_type`, int `$timeout` = -1): int|bool

Define ou busca o tempo limite do imap.

### Parâmetros

`timeout_type`

  Uma das seguintes constantes: `IMAP_OPENTIMEOUT`, `IMAP_READTIMEOUT`, `IMAP_WRITETIMEOUT` ou `IMAP_CLOSETIMEOUT`.

`timeout`

  O tempo limite, em segundos.

### Valor Retornado

Se o parâmetro `timeout` estiver definido, esta função retornará `true` em caso de sucesso e `false` em caso de falha.

Se `timeout` não for fornecido ou for avaliado como -1, o valor de tempo limite atual de `timeout_type` será retornado como um inteiro.

### Exemplos

Exemplo #1 Exemplo de imap_timeout()

    <?php

    echo "O tempo limite de leitura atual é " . imap_timeout(IMAP_READTIMEOUT) . "\n";

    ?>

# imap_uid

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_uid — Retorna o UID para o número de sequência da mensagem fornecida

### Descrição

function imap_uid(IMAP\Connection `$imap`, int `$message_num`): int|false

Esta função retorna o UID para o número de sequência de mensagem dado. Um UID é um identificador exclusivo que não mudará ao longo do tempo, enquanto um número de sequência de mensagem pode mudar sempre que o conteúdo da caixa de correio mudar.

Esta função é o inverso de imap_msgno().

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`message_num`

  O número da mensagem.

### Valor Retornado

O UID da mensagem fornecida.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Notas

> Nota:

> Esta função não é suportada por caixas de correio POP3.

### Veja Também

- imap_msgno() - Obtém o número da sequência da mensagem para o UID fornecido

# imap_undelete

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_undelete — Desmarca a mensagem que está marcada como excluída

### Descrição

function imap_undelete(IMAP\Connection `$imap`, string `$message_nums`, int `$flags` = 0): true

Remove o sinalizador de exclusão para uma mensagem especificada, que é definido por imap_delete() ou imap_mail_move().

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`message_nums`

  Uma string representando uma ou mais mensagens no formato de sequência estilo IMAP4 (`"n"`, `"n:m"` ou uma combinação destes delimitados por vírgulas).

`flags`

### Valor Retornado

Sempre retorna `true`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Veja Também

- imap_delete() - Marca uma mensagem para exclusão da caixa de correio atual
- imap_mail_move() - Move mensagens especificadas para uma caixa de correio

# imap_unsubscribe

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_unsubscribe — Cancela a inscrição em uma caixa de correio

### Descrição

function imap_unsubscribe(IMAP\Connection `$imap`, string `$mailbox`): bool

Cancela a inscrição na caixa de correio informada em `mailbox`.

### Parâmetros

`imap`
  Uma instância de IMAP\Connection.
`mailbox`

  O nome da caixa de correio, veja imap_open() para mais informações

  Aviso

  Passar dados não confiáveis para este parâmetro é inseguro, a menos que imap.enable_insecure_rsh esteja desabilitado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | O parâmetro `imap` agora espera uma instância de IMAP\Connection; anteriormente, um resource `imap` válido era esperado.

### Veja Também

- imap_subscribe() - Faz inscrição em uma caixa de correio

# imap_utf7_decode

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_utf7_decode — Decodifica uma string codificada em UTF-7 modificada

### Descrição

function imap_utf7_decode(string `$string`): string|false

Decodifica `string` UTF-7 modificada em string ISO-8859-1.

Esta função é necessária para decodificar nomes de caixas de correio que contêm certos caracteres que não estão no intervalo de caracteres ASCII imprimíveis.

### Parâmetros

`string`

  Uma string em codificação UTF-7 modificada, conforme definido na » RFC 2060, seção 5.1.3.

### Valor Retornado

Retorna uma string que é codificada em ISO-8859-1 e consiste na mesma sequência de caracteres do parâmetro `string`, ou `false` se o parâmetro `string` contiver sequência UTF-7 modificada inválida ou se o parâmetro `string` contiver um caractere que não faz parte do conjunto de caracteres ISO-8859-1.

### Veja Também

- imap_utf7_encode() - Converte string ISO-8859-1 em texto UTF-7 modificado

# imap_utf7_encode

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_utf7_encode — Converte string ISO-8859-1 em texto UTF-7 modificado

### Descrição

function imap_utf7_encode(string `$string`): string

Converte `string` em texto UTF-7 modificado.

Isso é necessário para codificar nomes de caixas de correio que contêm certos caracteres que não estão no intervalo de caracteres ASCII imprimíveis.

### Parâmetros

`string`

  Uma sequência de caracteres ISO-8859-1.

### Valor Retornado

Retorna a `string` com a codificação UTF-7 modificada conforme definido na » RFC 2060, seção 5.1.3.

### Veja Também

- imap_utf7_decode() - Decodifica uma string codificada em UTF-7 modificada

# imap_utf8

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_utf8 — Converte texto codificado em MIME para UTF-8

### Descrição

function imap_utf8(string `$mime_encoded_text`): string

Converte o `mime_encoded_text` fornecido para UTF-8, se o conjunto de caracteres declarado for conhecido pelo libc-client. Caso contrário, o texto fornecido é decodificado, mas não convertido para UTF-8.

### Parâmetros

`mime_encoded_text`

  Uma string codificada em MIME. O método de codificação MIME e a especificação UTF-8 são descritos na » RFC2047 e na » RFC2044 respectivamente.

### Valor Retornado

Retorna a string decodificada, se possível convertida para UTF-8.

### Exemplos

Exemplo #1 Uso básico de imap_utf8()

    <?php
    echo imap_utf8("Johannes =?ISO-8859-1?Q?Schl=FCter?=");
    ?>

O exemplo acima produzirá algo semelhante a:

    Johannes Schlüter

### Veja Também

- imap_mime_header_decode() - Decodifica elementos do cabeçalho MIME

# imap_utf8_to_mutf7

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

imap_utf8_to_mutf7 — Codifica uma string UTF-8 para UTF-7 modificado

### Descrição

function imap_utf8_to_mutf7(string `$string`): string|false

Codifica uma string UTF-8 para UTF-7 modificado (conforme especificado na RFC 2060, seção 5.1.3).

> Nota:

> Esta função só estará disponível se libcclient exportar utf8_to_mutf7().

### Parâmetros

`string`

  Uma sequência de caracteres codificada em UTF-8.

### Valor Retornado

Retorna a `string` convertida para UTF-7 modificado, ou `false` em caso de falha.

### Veja Também

- imap_mutf7_to_utf8() - Decodifica uma string UTF-7 modificada para UTF-8

## Índice

- imap_8bit — Converte uma string de 8 bits em uma string imprimível escapada
- imap_alerts — Retorna todas as mensagens de alerta IMAP que ocorreram
- imap_append — Acrescenta uma mensagem de string a uma caixa de correio especificada
- imap_base64 — Decodifica texto codificado em BASE64
- imap_binary — Converte uma string de 8 bits em uma string base64
- imap_body — Lê o corpo da mensagem
- imap_bodystruct — Lê a estrutura de uma seção específica do corpo de uma mensagem específica
- imap_check — Verifica a caixa de correio atual
- imap_clearflag_full — Limpa sinalizadores em mensagens
- imap_close — Fecha um fluxo IMAP
- imap_create — Sinônimo de imap_createmailbox
- imap_createmailbox — Cria uma nova caixa de correio
- imap_delete — Marca uma mensagem para exclusão da caixa de correio atual
- imap_deletemailbox — Exclui uma caixa de correio
- imap_errors — Retorna todos os erros IMAP que ocorreram
- imap_expunge — Exclui todas as mensagens marcadas para exclusão
- imap_fetch_overview — Lê uma visão geral das informações nos cabeçalhos da mensagem fornecida
- imap_fetchbody — Busca uma seção específica do corpo da mensagem
- imap_fetchheader — Retorna o cabeçalho de uma mensagem
- imap_fetchmime — Busca cabeçalhos MIME para uma seção específica da mensagem
- imap_fetchstructure — Lê a estrutura de uma mensagem específica
- imap_fetchtext — Sinônimo de imap_body
- imap_gc — Limpa o cache IMAP
- imap_get_quota — Recupera as configurações de nível de cota e estatísticas de uso por caixa de correio
- imap_get_quotaroot — Recupera as configurações de cota por usuário
- imap_getacl — Obtém a ACL para uma determinada caixa de correio
- imap_getmailboxes — Lê a lista de caixas de correio, retornando informações detalhadas sobre cada uma delas
- imap_getsubscribed — Lista todas as caixas de correio assinadas
- imap_header — Sinônimo de imap_headerinfo
- imap_headerinfo — Lê o cabeçalho da mensagem
- imap_headers — Retorna cabeçalhos para todas as mensagens em uma caixa de correio
- imap_is_open — Verifica se o fluxo IMAP ainda é válido
- imap_last_error — Obtém o último erro IMAP que ocorreu durante esta solicitação de página
- imap_list — Lê a lista de caixas de correio
- imap_listmailbox — Sinônimo de imap_list
- imap_listscan — Retorna a lista de caixas de correio que correspondem ao texto fornecido
- imap_listsubscribed — Sinônimo de imap_lsub
- imap_lsub — Lista todas as caixas de correio assinadas
- imap_mail — Envia uma mensagem de e-mail
- imap_mail_compose — Cria uma mensagem MIME com base nas seções de envelope e corpo fornecidas
- imap_mail_copy — Copia mensagens especificadas para uma caixa de correio
- imap_mail_move — Move mensagens especificadas para uma caixa de correio
- imap_mailboxmsginfo — Obtém informações sobre a caixa de correio atual
- imap_mime_header_decode — Decodifica elementos do cabeçalho MIME
- imap_msgno — Obtém o número da sequência da mensagem para o UID fornecido
- imap_mutf7_to_utf8 — Decodifica uma string UTF-7 modificada para UTF-8
- imap_num_msg — Obtém o número de mensagens na caixa de correio atual
- imap_num_recent — Obtém o número de mensagens recentes na caixa de correio atual
- imap_open — Abre um fluxo IMAP para uma caixa de correio
- imap_ping — Verifica se o fluxo IMAP ainda está ativo
- imap_qprint — Converte uma string imprimível escapada em uma string de 8 bits
- imap_rename — Sinônimo de imap_renamemailbox
- imap_renamemailbox — Renomeia uma caixa de correio antiga para uma nova caixa de correio
- imap_reopen — Reabre o fluxo IMAP para uma nova caixa de correio
- imap_rfc822_parse_adrlist — Analisa uma string de endereços
- imap_rfc822_parse_headers — Analisa cabeçalhos de e-mail de uma string
- imap_rfc822_write_address — Retorna um endereço de e-mail formatado corretamente, considerando a caixa de correio, o host e as informações pessoais
- imap_savebody — Salva uma seção específica do corpo em um arquivo
- imap_scan — Sinônimo de imap_listscan
- imap_scanmailbox — Sinônimo de imap_listscan
- imap_search — Esta função retorna um array de mensagens que correspondem aos critérios de pesquisa fornecidos
- imap_set_quota — Define uma cota para uma determinada caixa de correio
- imap_setacl — Define a ACL para uma determinada caixa de correio
- imap_setflag_full — Define sinalizadores em mensagens
- imap_sort — Obtém e classifica mensagens
- imap_status — Retorna informações de status sobre uma caixa de correio
- imap_subscribe — Faz inscrição em uma caixa de correio
- imap_thread — Retorna uma árvore de mensagens encadeadas
- imap_timeout — Define ou busca o tempo limite do imap
- imap_uid — Retorna o UID para o número de sequência da mensagem fornecida
- imap_undelete — Desmarca a mensagem que está marcada como excluída
- imap_unsubscribe — Cancela a inscrição em uma caixa de correio
- imap_utf7_decode — Decodifica uma string codificada em UTF-7 modificada
- imap_utf7_encode — Converte string ISO-8859-1 em texto UTF-7 modificado
- imap_utf8 — Converte texto codificado em MIME para UTF-8
- imap_utf8_to_mutf7 — Codifica uma string UTF-8 para UTF-7 modificado

# A classe IMAP\Connection

(PHP 8 >= 8.1.0)

## Introdução

Uma classe totalmente opaca que substitui um recurso `imap` a partir do PHP 8.1.0.

## Resumo da classe

final class IMAP\Connection {
}

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
  - Tipos de Recurso
- Constantes predefinidas
- Funções de IMAP
  - imap_8bit — Converte uma string de 8 bits em uma string imprimível escapada
  - imap_alerts — Retorna todas as mensagens de alerta IMAP que ocorreram
  - imap_append — Acrescenta uma mensagem de string a uma caixa de correio especificada
  - imap_base64 — Decodifica texto codificado em BASE64
  - imap_binary — Converte uma string de 8 bits em uma string base64
  - imap_body — Lê o corpo da mensagem
  - imap_bodystruct — Lê a estrutura de uma seção específica do corpo de uma mensagem específica
  - imap_check — Verifica a caixa de correio atual
  - imap_clearflag_full — Limpa sinalizadores em mensagens
  - imap_close — Fecha um fluxo IMAP
  - imap_create — Sinônimo de imap_createmailbox
  - imap_createmailbox — Cria uma nova caixa de correio
  - imap_delete — Marca uma mensagem para exclusão da caixa de correio atual
  - imap_deletemailbox — Exclui uma caixa de correio
  - imap_errors — Retorna todos os erros IMAP que ocorreram
  - imap_expunge — Exclui todas as mensagens marcadas para exclusão
  - imap_fetch_overview — Lê uma visão geral das informações nos cabeçalhos da mensagem fornecida
  - imap_fetchbody — Busca uma seção específica do corpo da mensagem
  - imap_fetchheader — Retorna o cabeçalho de uma mensagem
  - imap_fetchmime — Busca cabeçalhos MIME para uma seção específica da mensagem
  - imap_fetchstructure — Lê a estrutura de uma mensagem específica
  - imap_fetchtext — Sinônimo de imap_body
  - imap_gc — Limpa o cache IMAP
  - imap_get_quota — Recupera as configurações de nível de cota e estatísticas de uso por caixa de correio
  - imap_get_quotaroot — Recupera as configurações de cota por usuário
  - imap_getacl — Obtém a ACL para uma determinada caixa de correio
  - imap_getmailboxes — Lê a lista de caixas de correio, retornando informações detalhadas sobre cada uma delas
  - imap_getsubscribed — Lista todas as caixas de correio assinadas
  - imap_header — Sinônimo de imap_headerinfo
  - imap_headerinfo — Lê o cabeçalho da mensagem
  - imap_headers — Retorna cabeçalhos para todas as mensagens em uma caixa de correio
  - imap_is_open — Verifica se o fluxo IMAP ainda é válido
  - imap_last_error — Obtém o último erro IMAP que ocorreu durante esta solicitação de página
  - imap_list — Lê a lista de caixas de correio
  - imap_listmailbox — Sinônimo de imap_list
  - imap_listscan — Retorna a lista de caixas de correio que correspondem ao texto fornecido
  - imap_listsubscribed — Sinônimo de imap_lsub
  - imap_lsub — Lista todas as caixas de correio assinadas
  - imap_mail — Envia uma mensagem de e-mail
  - imap_mail_compose — Cria uma mensagem MIME com base nas seções de envelope e corpo fornecidas
  - imap_mail_copy — Copia mensagens especificadas para uma caixa de correio
  - imap_mail_move — Move mensagens especificadas para uma caixa de correio
  - imap_mailboxmsginfo — Obtém informações sobre a caixa de correio atual
  - imap_mime_header_decode — Decodifica elementos do cabeçalho MIME
  - imap_msgno — Obtém o número da sequência da mensagem para o UID fornecido
  - imap_mutf7_to_utf8 — Decodifica uma string UTF-7 modificada para UTF-8
  - imap_num_msg — Obtém o número de mensagens na caixa de correio atual
  - imap_num_recent — Obtém o número de mensagens recentes na caixa de correio atual
  - imap_open — Abre um fluxo IMAP para uma caixa de correio
  - imap_ping — Verifica se o fluxo IMAP ainda está ativo
  - imap_qprint — Converte uma string imprimível escapada em uma string de 8 bits
  - imap_rename — Sinônimo de imap_renamemailbox
  - imap_renamemailbox — Renomeia uma caixa de correio antiga para uma nova caixa de correio
  - imap_reopen — Reabre o fluxo IMAP para uma nova caixa de correio
  - imap_rfc822_parse_adrlist — Analisa uma string de endereços
  - imap_rfc822_parse_headers — Analisa cabeçalhos de e-mail de uma string
  - imap_rfc822_write_address — Retorna um endereço de e-mail formatado corretamente, considerando a caixa de correio, o host e as informações pessoais
  - imap_savebody — Salva uma seção específica do corpo em um arquivo
  - imap_scan — Sinônimo de imap_listscan
  - imap_scanmailbox — Sinônimo de imap_listscan
  - imap_search — Esta função retorna um array de mensagens que correspondem aos critérios de pesquisa fornecidos
  - imap_set_quota — Define uma cota para uma determinada caixa de correio
  - imap_setacl — Define a ACL para uma determinada caixa de correio
  - imap_setflag_full — Define sinalizadores em mensagens
  - imap_sort — Obtém e classifica mensagens
  - imap_status — Retorna informações de status sobre uma caixa de correio
  - imap_subscribe — Faz inscrição em uma caixa de correio
  - imap_thread — Retorna uma árvore de mensagens encadeadas
  - imap_timeout — Define ou busca o tempo limite do imap
  - imap_uid — Retorna o UID para o número de sequência da mensagem fornecida
  - imap_undelete — Desmarca a mensagem que está marcada como excluída
  - imap_unsubscribe — Cancela a inscrição em uma caixa de correio
  - imap_utf7_decode — Decodifica uma string codificada em UTF-7 modificada
  - imap_utf7_encode — Converte string ISO-8859-1 em texto UTF-7 modificado
  - imap_utf8 — Converte texto codificado em MIME para UTF-8
  - imap_utf8_to_mutf7 — Codifica uma string UTF-8 para UTF-7 modificado
- IMAP\Connection — A classe IMAP\Connection

# Mail

# Introdução

A função mail() permite enviar correio eletrônico (e-mail).

# Instalação/Configuração

## Índice

- Dependências
- Configurações em Execução

## Dependências

Para que as funções da extensão Mail estejam disponíveis, o PHP deve ter acesso ao binário do `sendmail` no sistema durante a compilação. Se outro programa de correio eletrônico for utilizado, como qmail ou postfix, certifique-se de usar os empacotadores de sendmail apropriados que o acompanham. O PHP irá primeiramente procurar pelo sendmail na variável PATH, e depois nos seguintes locais: `/usr/bin:/usr/sbin:/usr/etc:/etc:/usr/ucblib:/usr/lib`. É altamente recomendado ter o sendmail disponível em PATH. Além disso, o usuário sob o qual o processo PHP é executado deve ter permissão para acessar o binário sendmail.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de configuração da função Mail
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
mail.add_x_header | "0" | `INI_PERDIR` |
mail.mixed_lf_and_crlf | "0" | `INI_SYSTEM`|`INI_PERDIR` | Adicionada no PHP 8.2.4
mail.log | NULL | `INI_SYSTEM`|`INI_PERDIR` |
mail.force_extra_parameters | NULL | `INI_SYSTEM` |
SMTP | "localhost" | `INI_ALL` |
smtp_port | "25" | `INI_ALL` |
sendmail_from | NULL | `INI_ALL` |
sendmail_path | "/usr/sbin/sendmail -t -i" | `INI_SYSTEM` |

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`mail.add_x_header` bool

  Adiciona `X-PHP-Originating-Script` que incluirá o UID do script seguido pelo nome do arquivo.

`mail.log` string

  O caminho para o arquivo de registro que irá armazenar todas as chamadas à função mail(). As entradas de registro incluirão o caminho completo do script, número da linha, endereço de destino `To` e cabeçalhos.

`mail.mixed_lf_and_crlf` bool

  Permite reverter o separador de linha para cabeçalhos de e-mail e corpos de mensagem para LF (Alimentação de Linha), imitando o comportamento não compatível do PHP 7. É fornecido como uma medida de compatibilidade para certos Agentes de Transferência de Correio Eletrônico (MTAs) não compatíveis que falham em processar corretamente CRLF (Retorno de Carro + Alimentação de Linha) como um separador de linha em cabeçalhos de e-mail e conteúdo de mensagem.

`mail.force_extra_parameters` string

  Força a adição de parâmetros específicos que serão passados como parâmetros extras para o binário sendmail. Estes parâmetros sempre substituirão o valor do quinto parâmetro da função mail().

  Além do comportamento padrão para `INI_SYSTEM`, este valor também pode ser definido com `php_value` no httpd.conf (mas isto não é recomendado).
`SMTP` string

  Usado somente no Windows: nome de servidor ou endereço IP do servidor SMTP que o PHP deve usar para e-mail envio com a função mail().

`smtp_port` int

  Usado somente no Windows: Número da porta para se conectar ao servidor definido com a configuração de `SMTP` ao enviar e-mail com a função mail(); a porta padrão é 25.

`sendmail_from` string

  Qual endereço de e-mail `"From:"` deve ser usado no e-mail enviado diretamente via SNMP (somente Windows). Esta diretiva também define o cabeçalho `"Return-Path:"`.

`sendmail_path` string

  Onde o programa sendmail pode ser encontrado, normalmente em /usr/sbin/sendmail ou /usr/lib/sendmail. configure faz uma tentativa de localizar e definir o padrão, mas se ele falhar, pode ser definido aqui.

  Sistema que não usam o sendmail devem configurar essa diretiva para a alternativa ao sendmail que o sistema oferece, se houver. Por exemplo, usuários do » Qmail normalmente usam /var/qmail/bin/sendmail ou /var/qmail/bin/qmail-inject.

  qmail-inject não requer nehuma opção para o processar o e-mail corretamente.

  Esta diretiva também funciona no Windows. Se definida, smtp, smtp_port e sendmail_from são ignorados e o comando especificado é executado.

# Funções da Mail

# ezmlm_hash

(PHP 4 >= 4.0.2, PHP 5, PHP 7)

ezmlm_hash — Calcula o valor do hash necessário para EZMLM

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.4.0 e foi REMOVIDA a partir do PHP 8.0.0. O uso desta função é fortemente desencorajado.

### Descrição

function ezmlm_hash(string `$addr`): int

ezmlm_hash() calcula valor do hash necessário ao se manter listas de e-mail EZMLM num banco de dados MySQL.

### Parâmetros

`addr`

  O endereço de e-mail para o qual está sendo calculado o hash.

### Valor Retornado

O valor do hash de `addr`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Esta função foi removida.
7.4.0 | Esta função foi descontinuada.

### Exemplos

Exemplo #1 Calculando o hash e inscrevendo um usuário

    <?php

    $user = "joecool@example.com";
    $hash = ezmlm_hash($user);
    $query = sprintf("INSERT INTO sample VALUES (%s, '%s')", $hash, $user);
    $db->query($query); // usando interface de banco de dados PHPLIB

    ?>

# mail

(PHP 4, PHP 5, PHP 7, PHP 8)

mail — Envia e-mail

### Descrição

function mail(
string `$to`,
string `$subject`,
string `$message`,
array|string `$additional_headers` = [],
string `$additional_params` = ""
): bool

Envia um e-mail.

### Parâmetros

`to`

  Destinatário, ou destinatários do e-mail.

  O formato desta string precisa estar de acordo com a » RFC 2822. Alguns exemplos:

  - user@example.com
  - user@example.com, anotheruser@example.com
  - User
  - User , Another User
`subject`

  Assunto do e-mail a ser enviado.

  Cuidado

  Assunto deve satisfazer a » RFC 2047.

`message`

  Mensagem a ser enviada.

  Cada linha deve ser separada com um CRLF (\r\n). Linhas não devem ser maiores que 70 caracteres.

  Cuidado

  (Somente Windows) Quando o PHP está se comunicando com o servidor SMTP diretamente, e um ponto final é encontrado no início de uma linha, ela é removida. Para se defender disto, substitua estas ocorrência por dois pontos seguidos.

      <?php
      $text = str_replace("\n.", "\n..", $text);
      ?>

`additional_headers` (opcional)

  String ou array a ser inserido no final do cabeçalho do e-mail.

  Isto é tipicamente usado para adicionar cabeçalhos extras (From, Cc, e Bcc). Múltiplos cabeçalhos extras devem ser separados com um CRLF (\r\n). Se dados externos forem usados para compor este cabeçalho, os dados devem ser sanitizados para que nenhum cabeçalho indesejado possa ser injetado.

  Se um array for passado, suas chaves são os nomes dos cabeçalhos e seus valores são os respectivos valores dos cabeçalhos.

  > Nota:

  > Ao enviar e-mail, ele precisa conter um cabeçalho `From`. Este pode ser definido com o parâmetro `additional_headers`, ou um padrão pode ser definido no php.ini.

  > Se isto não foi feito, ocorrerá uma mensagem de erro similar a `Warning: mail(): "sendmail_from" not set in php.ini or custom "From:" header missing`. O cabeçalho `From` define também o `Return-Path` ao enviar diretamente via SMTP (Windows somente).

  > Nota:

  > Se mensagens não estão sendo recebidas, tente usar somente um LF (\n). Alguns agentes Unix de transferência de e-mail (mais notavelmente » qmail) substituem LF por CRLF automaticamente (que leva à duplicação de CR se CRLF for usado). Este deve ser um último recurso, porque não está conforme a » RFC 2822.

`additional_params` (opcional)

  O parâmetro `additional_params` pode ser usado para passar um parâmetro adicional para o programa configurado para usa quando enviando e-mail usando a configuração `sendmail_path`. Por exemplo, isto pode ser usado para definir o endereço do envelope remetente quando usando sendmail com a opção do sendmail `-f`.

  Este parâmetro é escapado por escapeshellcmd() internamente para prevenir a execução do comando. escapeshellcmd() impede a execução de comandos, mas permite adicionar parâmetros adicionais. Por razões de segurança, é recomendado que o usuário higienize este parâmetro para evitar adicionar parâmetros indesejados ao comando shell.

  Uma vez que escapeshellcmd() é aplicada automaticamente, alguns caracteres que são permitidos como endereços de e-mail por RFCs da Internet não podem ser usados. mail() não pode permitir tais caracteres, portanto, em programas onde o uso de tais caracteres é necessário, meios alternativos de envio de e-mails (como o uso de um framework ou biblioteca) são recomendados.

  O usuário com o qual o servidor web roda deve ser adicionado como um usuário confiável à configuração do sendmail para evitar que um cabeçalho 'X-Warning' seja adicionado à mensagem quando o remetente do envelope (-f) é definido usando este método. Para usuários do sendmail, este arquivo é /etc/mail/trusted-users.

### Valor Retornado

Retorna `true` se o e-mail foi aceito com sucesso para entrega, `false` caso contrário.

É importante notar que somente pelo fato do e-mail ter sido aceito para entrega, NÃO significa que o e-mail realmente alcancará o destino esperado.

### Registro de Alterações

Versão | Descrição
--- | ---
7.2.0 | O parâmetro `additional_headers` agora aceita um array.

### Exemplos

Exemplo #1 Enviando e-mail.

Usando mail() para enviar um simples e-mail:

    <?php
    // A mensagem
    $message = "Line 1\r\nLine 2\r\nLine 3";

    // Se as linhas forem maiores que 70 caracteres, deve-se usar wordwrap()
    $message = wordwrap($message, 70, "\r\n");

    // Envia
    mail('caffeinated@example.com', 'Meu Assunto', $message);
    ?>

Exemplo #2 Enviando e-mail com cabeçalhos extras.

A adição de cabeçalhos básicos, informando à MUA os endereços From e Reply-To:

    <?php
    $to      = 'nobody@example.com';
    $subject = 'the subject';
    $message = 'hello';
    $headers = 'From: webmaster@example.com' . "\r\n" .
        'Reply-To: webmaster@example.com' . "\r\n" .
        'X-Mailer: PHP/' . phpversion();

    mail($to, $subject, $message, $headers);
    ?>

Exemplo #3 Enviando e-mail com cabeçalhos extras no formato array

Este exemplo envia o mesmo e-mail que o exemplo imediatamente acima, mas passa os cabeçalhos adicionais como array (disponível a partir do PHP 7.2.0).

    <?php
    $to      = 'nobody@example.com';
    $subject = 'the subject';
    $message = 'hello';
    $headers = array(
        'From' => 'webmaster@example.com',
        'Reply-To' => 'webmaster@example.com',
        'X-Mailer' => 'PHP/' . phpversion()
    );

    mail($to, $subject, $message, $headers);
    ?>

Exemplo #4 Enviando e-mail com um parâmetro de linha de comando adicional.

O parâmetro `additional_params` pode ser usado para passar um parâmetro adicional para o programa configurado para usar ao enviar e-mail usando o `sendmail_path`.

    <?php
    mail('nobody@example.com', 'the subject', 'the message', null,
       '-fwebmaster@example.com');
    ?>

Exemplo #5 Enviando e-mail HTML

É também possível enviar e-mail HTML com mail().

    <?php
    // Múltiplos recipientes
    $to = 'joao@example.com, susana@example.com'; // observe a vírgula

    // Assunto
    $subject = 'Lembrete de Aniversários para Novembro';

    // Message
    $message = '
    <html>
    <head>
      <title>Lembrete de Aniversários para Novembro</title>
    </head>
    <body>
      <p>Aqui estão os próximos aniversariantes de novembro!</p>
      <table>
        <tr>
          <th>Pessoa</th><th>Dia</th><th>Mês</th><th>Ano</th>
        </tr>
        <tr>
          <td>João</td><td>10</td><td>Agosto</td><td>1990</td>
        </tr>
        <tr>
          <td>Susana</td><td>17</td><td>Agosto</td><td>2003</td>
        </tr>
      </table>
    </body>
    </html>
    ';

    // Para enviar e-mail HTML, o cabeçalho Content-type deve ser definido
    $headers[] = 'MIME-Version: 1.0';
    $headers[] = 'Content-type: text/html; charset=iso-8859-1';

    // Cabeçalhos adicionais
    $headers[] = 'To: Maria <maria@example.com>, Rafael <rafael@example.com>';
    $headers[] = 'From: Lembrete de Aniversário <niver@example.com>';
    $headers[] = 'Cc: arquivo_niver@example.com';
    $headers[] = 'Bcc: verifica_niver@example.com';

    // Envia o e-mail
    mail($to, $subject, $message, implode("\r\n", $headers));
    ?>

> Nota:

> Se a intenção é enviar e-mail HTML ou outro formato complexo, é recomendado usar o pacote PEAR » PEAR::Mail_Mime.

### Notas

> Nota:

> A implentação SMTP (somente Windows) de mail() difere bastante da implentação do sendmail. Primeiro, ele não usa um binário local para compor mensagens mas apenas opera com sockets diretos, o que significa que uma `MTA` é necessária monitorando um socket de rede (que pode ser ou o localhost ou uma máquina remota).

> Segundo, cabeçalhos customizados como `From:`, `Cc:`, `Bcc:` e `Date:` não são interpretados pela `MTA`, mas são analisados pelo PHP.

> Desta forma, o parâmetro `to` não deve ser um endereço na forma de "Algo <alguem@example.com>". O comando de e-mail poderia não analisar isto adequadamente enquanto se comunica com o MTA.

> Nota:

> É válido notar que a função mail() não é apropriada para um grande volume de e-mail em um loop. Esta função abre e fecha um SMTP socket para cada e-mail, o que não é muito eficiente.

> Para enviar uma grande quantidade de e-mail, veja os pacotes » PEAR::Mail, e » PEAR::Mail_Queue.

> Nota:

> O seguintes RFCs podem ser úteis: » RFC 1896, » RFC 2045, » RFC 2046, » RFC 2047, » RFC 2048, » RFC 2049 e » RFC 2822.

### Veja Também

- mb_send_mail() - Envia email codificado
- imap_mail() - Envia uma mensagem de e-mail
- » PEAR::Mail
- » PEAR::Mail_Mime

## Índice

- ezmlm_hash — Calcula o valor do hash necessário para EZMLM
- mail — Envia e-mail

- Instalação/Configuração
  - Dependências
  - Configurações em Execução
- Funções da Mail
  - ezmlm_hash — Calcula o valor do hash necessário para EZMLM
  - mail — Envia e-mail

# Mailparse

# Introdução

Mailparse é uma extensão para análise e manipulação de mensagens de e-mail. Ele pode lidar com mensagens compatíveis com » RFC 822 e » RFC 2045 (`MIME`).

O Mailparse é baseado em fluxo, o que significa que não mantém cópias em memória dos arquivos que processa - sendo muito eficiente em termos de recursos ao lidar com mensagens grandes.

> Nota: O Mailparse requer a extensão mbstring, e a mbstring deve ser carregada antes do mailparse.

# Instalação/Configuração

## Índice

- Instalação
- Configurações em Execução
- Tipos de Recurso

## Instalação

Esta extensão » PECL não é distribuída com o PHP. Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/mailparse.

Para usar essas funções, você deve compilar o PHP com suporte ao mailparse usando a opção de configuração --enable-mailparse.

Usuários do Windows devem habilitar o php_mailparse.dll dentro de php.ini para usar essas funções. Binários do Windows (arquivos DLL) para esta extensão PECL estão disponíveis no site do PECL.

É necessário que a extensão mbstring esteja carregada antes do mailparse.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de Configuração de Mailparse
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
mailparse.def_charset | "us-ascii" | `INI_SYSTEM` |

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`mailparse.def_charset` string
  O conjunto de caracteres padrão.

## Tipos de Recurso

Mailparse define o tipo de recurso `mailparse_mail_structure`, que é retornado por mailparse_msg_create() e mailparse_msg_parse_file().

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`MAILPARSE_EXTRACT_OUTPUT` (int)
`MAILPARSE_EXTRACT_STREAM` (int)
`MAILPARSE_EXTRACT_RETURN` (int)

# Funções de Mailparse

# mailparse_determine_best_xfer_encoding

(PECL mailparse >= 0.9.0)

mailparse_determine_best_xfer_encoding — Obtém a melhor forma de codificação

### Descrição

function mailparse_determine_best_xfer_encoding(resource `$fp`): string

Determina a melhor forma de codificar o conteúdo lido do ponteiro de arquivo fornecido.

### Parâmetros

`fp`
  Um ponteiro de arquivo válido, que deve ser capaz de realizar operações de busca.

### Valor Retornado

Retorna uma das codificações de caracteres suportadas pelo módulo mbstring.

### Exemplos

Exemplo #1 Exemplo de mailparse_determine_best_xfer_encoding()

    <?php

    $fp = fopen('somemail.eml', 'r');
    echo 'Best encoding: ' . mailparse_determine_best_xfer_encoding($fp);

    ?>

O exemplo acima produzirá algo semelhante a:

    Best encoding: 7bit

# mailparse_msg_create

(PECL mailparse >= 0.9.0)

mailparse_msg_create — Cria um recurso de email MIME

### Descrição

function mailparse_msg_create(): resource

Cria um recurso de email `MIME`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um identificador que pode ser usado para analisar uma mensagem.

### Notas

> Nota: É recomendado chamar mailparse_msg_free() no resultado desta função, quando não for mais necessário, para evitar vazamentos de memória.

### Veja Também

- mailparse_msg_free() - Libera um recurso MIME
- mailparse_msg_parse_file() - Faz o parsing de um arquivo

# mailparse_msg_extract_part

(PECL mailparse >= 0.9.0)

mailparse_msg_extract_part — Extrai/decodifica uma seção da mensagem

### Descrição

function mailparse_msg_extract_part(resource `$mimemail`, string `$msgbody`, callable `$callbackfunc` = ?): void
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`mimemail`
  Um recurso `MIME` válido.
`msgbody`
`callbackfunc`

### Valor Retornado

Nenhum valor é retornado.

### Veja Também

- mailparse_msg_extract_part_file() - Extrai/decodifica uma seção da mensagem
- mailparse_msg_extract_whole_part_file() - Extrai uma seção da mensagem incluindo cabeçalhos sem decodificar a codificação de transferência

# mailparse_msg_extract_part_file

(PECL mailparse >= 0.9.0)

mailparse_msg_extract_part_file — Extrai/decodifica uma seção da mensagem

### Descrição

function mailparse_msg_extract_part_file(resource `$mimemail`, mixed `$filename`, callable `$callbackfunc` = ?): string

Extrai/decodifica uma seção da mensagem do nome de arquivo fornecido.

O conteúdo da seção será decodificado de acordo com sua codificação de transferência - suportando base64, quoted-printable e texto uuencoded.

### Parâmetros

`mimemail`
  Um recurso `MIME` válido, criado com mailparse_msg_create().
`filename`
  Pode ser um nome de arquivo ou um recurso de fluxo válido.
`callbackfunc`
  Se definido, isso deve ser um retorno de chamada válido que receberá a seção extraída, ou `null` para fazer com que esta função retorne a seção extraída. Se não especificado, o conteúdo será enviado para "stdout".

### Valor Retornado

Se `callbackfunc` não for `null` retorna `true` em caso de sucesso.

Se `callbackfunc` estiver definido para `null`, retorna a seção extraída como uma string.

Retorna `false` em caso de erro.

### Veja Também

- mailparse_msg_extract_part() - Extrai/decodifica uma seção da mensagem
- mailparse_msg_extract_whole_part_file() - Extrai uma seção da mensagem incluindo cabeçalhos sem decodificar a codificação de transferência

# mailparse_msg_extract_whole_part_file

(PECL mailparse >= 0.9.0)

mailparse_msg_extract_whole_part_file — Extrai uma seção da mensagem incluindo cabeçalhos sem decodificar a codificação de transferência

### Descrição

function mailparse_msg_extract_whole_part_file(resource `$mimemail`, string `$filename`, callable `$callbackfunc` = ?): string
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`mimemail`
  Um recurso `MIME` válido.
`filename`
`callbackfunc`

### Valor Retornado

### Veja Também

- mailparse_msg_extract_part() - Extrai/decodifica uma seção da mensagem
- mailparse_msg_extract_part_file() - Extrai/decodifica uma seção da mensagem

# mailparse_msg_free

(PECL mailparse >= 0.9.0)

mailparse_msg_free — Libera um recurso MIME

### Descrição

function mailparse_msg_free(resource `$mimemail`): bool

Libera um recurso `MIME`.

### Parâmetros

`mimemail`
  Um recurso `MIME` válido alocado por mailparse_msg_create() ou mailparse_msg_parse_file().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- mailparse_msg_create() - Cria um recurso de email MIME
- mailparse_msg_parse_file() - Faz o parsing de um arquivo

# mailparse_msg_get_part

(PECL mailparse >= 0.9.0)

mailparse_msg_get_part — Retorna um identificador para uma seção específica em uma mensagem MIME

### Descrição

function mailparse_msg_get_part(resource `$mimemail`, string `$mimesection`): resource
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`mimemail`
  Um recurso `MIME` válido.
`mimesection`

# mailparse_msg_get_part_data

(PECL mailparse >= 0.9.0)

mailparse_msg_get_part_data — Retorna um array associativo com informações sobre a mensagem

### Descrição

function mailparse_msg_get_part_data(resource `$mimemail`): array
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`mimemail`
  Um recurso `MIME` válido.

# mailparse_msg_get_structure

(PECL mailparse >= 0.9.0)

mailparse_msg_get_structure — Retorna um array de nomes de seções MIME na mensagem fornecida

### Descrição

function mailparse_msg_get_structure(resource `$mimemail`): array
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`mimemail`
  Um recurso `MIME` válido.

# mailparse_msg_parse

(PECL mailparse >= 0.9.0)

mailparse_msg_parse — Faz o parse incremental de dados no buffer

### Descrição

function mailparse_msg_parse(resource `$mimemail`, string `$data`): bool

Faz o parse incremental de dados no recurso de correio MIME fornecido.

Essa função permite transmitir porções de um arquivo de cada vez, em vez de ler e analisar o arquivo inteiro.

### Parâmetros

`mimemail`
  Um recurso `MIME` válido.
`data`

  > Nota: O último trecho de `data` deve terminar com uma quebra de linha (`CRLF`); caso contrário, a última linha da mensagem não será analisada.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# mailparse_msg_parse_file

(PECL mailparse >= 0.9.0)

mailparse_msg_parse_file — Faz o parsing de um arquivo

### Descrição

function mailparse_msg_parse_file(string `$filename`): resource

Faz o parsing de um arquivo. Esta é a forma ideal de analisar um arquivo de email que você tem no disco.

### Parâmetros

`filename`
  Caminho para o arquivo que contém a mensagem. O arquivo é aberto e transmitido através do analisador.

  > Nota: Supõe-se que a mensagem contida em `filename` termine com uma quebra de linha (`CRLF`); caso contrário, a última linha da mensagem não será analisada.

### Valor Retornado

Retorna um recurso `MIME` que representa a estrutura ou `false` em caso de erro.

### Notas

> Nota: É recomendável chamar mailparse_msg_free() no resultado desta função, quando não for mais necessário, para evitar vazamentos de memória.

### Veja Também

- mailparse_msg_free() - Libera um recurso MIME
- mailparse_msg_create() - Cria um recurso de email MIME

# mailparse_rfc822_parse_addresses

(PECL mailparse >= 0.9.0)

mailparse_rfc822_parse_addresses — Faz o parse de endereços compatíveis com o RFC 822

### Descrição

function mailparse_rfc822_parse_addresses(string `$addresses`): array

Faz o parse de uma lista de destinatários compatível com o » RFC 822, como encontrado no cabeçalho `To:`.

### Parâmetros

`addresses`
  Uma string contendo endereços, como em: `Wez Furlong <wez@example.com>, doe@example.com`

  > Nota: Esta string não deve incluir o nome do cabeçalho.

### Valor Retornado

Retorna um array de arrays associativos com as seguintes chaves para cada destinatário:

`display` | O nome do destinatário, para fins de exibição. Se esta parte não estiver definida para um destinatário, esta chave terá o mesmo valor de `address`.
`address` | The email address
`is_group` | `true` se o destinatário for um grupo de notícias, `false` caso contrário.

### Exemplos

Exemplo #1 Exemplo de mailparse_rfc822_parse_addresses()

    <?php

    $to = 'Wez Furlong <wez@example.com>, doe@example.com';
    var_dump(mailparse_rfc822_parse_addresses($to));

    ?>

O exemplo acima produzirá:

    array(2) {
      [0]=>
      array(3) {
        ["display"]=>
        string(11) "Wez Furlong"
        ["address"]=>
        string(15) "wez@example.com"
        ["is_group"]=>
        bool(false)
      }
      [1]=>
      array(3) {
        ["display"]=>
        string(15) "doe@example.com"
        ["address"]=>
        string(15) "doe@example.com"
        ["is_group"]=>
        bool(false)
      }
    }

# mailparse_stream_encode

(PECL mailparse >= 0.9.0)

mailparse_stream_encode — Transmite dados do ponteiro do arquivo de origem, aplica a codificação e escreve no destfp

### Descrição

function mailparse_stream_encode(resource `$sourcefp`, resource `$destfp`, string `$encoding`): bool

Transmite dados do ponteiro do arquivo de origem, aplica a `encoding` e escreve no ponteiro do arquivo de destino.

### Parâmetros

`sourcefp`
  Um identificador de arquivo válido. O arquivo é transmitido pelo analisador.
`destfp`
  O identificador de arquivo de destino no qual os dados codificados serão escritos.
`encoding`
  Uma das codificações de caracteres suportadas pelo módulo mbstring.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de mailparse_stream_encode()

    <?php

    // conteúdo de email.eml: hello, this is some text=hello.
    $fp = fopen('email.eml', 'r');

    $dest = tmpfile();

    mailparse_stream_encode($fp, $dest, "quoted-printable");

    rewind($dest);

    // Exibe o conteúdo do novo arquivo
    fpassthru($dest);

    ?>

O exemplo acima produzirá:

    hello, this is some text=3Dhello.

# mailparse_uudecode_all

(PECL mailparse >= 0.9.0)

mailparse_uudecode_all — Analisa os dados de fp e extrai cada arquivo uuencoded incorporado.

### Descrição

function mailparse_uudecode_all(resource `$fp`): array

Analisa os dados do ponteiro do arquivo fornecido e extrai cada arquivo uuencoded incorporado em um arquivo temporário.

### Parâmetros

`fp`
  Um identificador de arquivo válido.

### Valor Retornado

Retorna um array de arrays associativos listando informações sobre os nomes dos arquivos.

`filename` | Caminho para o nome do arquivo temporário criado
`origfilename` | O nome do arquivo original, apenas para partes uuencoded

A primeira entrada de nome de arquivo é o corpo da mensagem. As próximas entradas são os arquivos uuencoded decodificados.

### Exemplos

Exemplo #1 Exemplo de mailparse_uudecode_all()

    <?php

    $text = <<<EOD
    To: fred@example.com

    hello, this is some text hello.
    blah blah blah.

    begin 644 test.txt
    /=&AI<R!I<R!A('1E<W0*
    `
    end

    EOD;

    $fp = tmpfile();
    fwrite($fp, $text);

    $data = mailparse_uudecode_all($fp);

    echo "BODY\n";
    readfile($data[0]["filename"]);
    echo "UUE ({$data[1]['origfilename']})\n";
    readfile($data[1]["filename"]);

    // Clean up
    unlink($data[0]["filename"]);
    unlink($data[1]["filename"]);

    ?>

O exemplo acima produzirá:

    BODY
    To: fred@example.com

    hello, this is some text hello.
    blah blah blah.

    UUE (test.txt)
    this is a test

## Índice

- mailparse_determine_best_xfer_encoding — Obtém a melhor forma de codificação
- mailparse_msg_create — Cria um recurso de email MIME
- mailparse_msg_extract_part — Extrai/decodifica uma seção da mensagem
- mailparse_msg_extract_part_file — Extrai/decodifica uma seção da mensagem
- mailparse_msg_extract_whole_part_file — Extrai uma seção da mensagem incluindo cabeçalhos sem decodificar a codificação de transferência
- mailparse_msg_free — Libera um recurso MIME
- mailparse_msg_get_part — Retorna um identificador para uma seção específica em uma mensagem MIME
- mailparse_msg_get_part_data — Retorna um array associativo com informações sobre a mensagem
- mailparse_msg_get_structure — Retorna um array de nomes de seções MIME na mensagem fornecida
- mailparse_msg_parse — Faz o parse incremental de dados no buffer
- mailparse_msg_parse_file — Faz o parsing de um arquivo
- mailparse_rfc822_parse_addresses — Faz o parse de endereços compatíveis com o RFC 822
- mailparse_stream_encode — Transmite dados do ponteiro do arquivo de origem, aplica a codificação e escreve no destfp
- mailparse_uudecode_all — Analisa os dados de fp e extrai cada arquivo uuencoded incorporado.

- Instalação/Configuração
  - Instalação
  - Configurações em Execução
  - Tipos de Recurso
- Constantes predefinidas
- Funções de Mailparse
  - mailparse_determine_best_xfer_encoding — Obtém a melhor forma de codificação
  - mailparse_msg_create — Cria um recurso de email MIME
  - mailparse_msg_extract_part — Extrai/decodifica uma seção da mensagem
  - mailparse_msg_extract_part_file — Extrai/decodifica uma seção da mensagem
  - mailparse_msg_extract_whole_part_file — Extrai uma seção da mensagem incluindo cabeçalhos sem decodificar a codificação de transferência
  - mailparse_msg_free — Libera um recurso MIME
  - mailparse_msg_get_part — Retorna um identificador para uma seção específica em uma mensagem MIME
  - mailparse_msg_get_part_data — Retorna um array associativo com informações sobre a mensagem
  - mailparse_msg_get_structure — Retorna um array de nomes de seções MIME na mensagem fornecida
  - mailparse_msg_parse — Faz o parse incremental de dados no buffer
  - mailparse_msg_parse_file — Faz o parsing de um arquivo
  - mailparse_rfc822_parse_addresses — Faz o parse de endereços compatíveis com o RFC 822
  - mailparse_stream_encode — Transmite dados do ponteiro do arquivo de origem, aplica a codificação e escreve no destfp
  - mailparse_uudecode_all — Analisa os dados de fp e extrai cada arquivo uuencoded incorporado.

- IMAP — IMAP, POP3 e NNTP
  - Instalação/Configuração
  - Constantes predefinidas
  - Funções de IMAP
  - IMAP\Connection — A classe IMAP\Connection
- Mail
  - Instalação/Configuração
  - Funções da Mail
- Mailparse
  - Instalação/Configuração
  - Constantes predefinidas
  - Funções de Mailparse

# Extensões Matemáticas

# Funções matemáticas de precisão arbitrária

# Introdução

Para matemática de precisão arbitrária, o PHP oferece BCMath, que suporta números de qualquer tamanho e com precisão de até `2147483647` (ou `0x7FFFFFFF`) dígitos decimais, até a memória disponível, representadas como strings.

Números válidos (ou bem formados) são strings que concordam com a expressão regular `/^[+-]?[0-9]*(\.[0-9]*)?$/`.

Cuidado

Passar valores de tipo float para uma função BCMath, que espera um operando string pode não funcionar como esperado dado que o PHP converte valores float para string, especificamente que a string convertida pode estar numa notação exponencial (que não é suportado no BCMath), e dado que, anteriormente ao PHP 8.0.0, o separador decimal depende da locale configurada (enquanto BCMath sempre trabalha com ponto).

    <?php
    $num1 = 0; // (string) 0 => '0'
    $num2 = -0.000005; // (string) -0.000005 => '-5.05E-6'
    echo bcadd($num1, $num2, 6); // => '0.000000'

    setlocale(LC_NUMERIC, 'de_DE'); // usa uma vírgula como separador de decimais
    $num2 = 1.2; // (string) 1.2 => '1,2'
    echo bcsub($num1, $num2, 1); // => '0.0'
    ?>

# Instalação/Configuração

## Índice

- Instalação
- Configurações em Execução

## Instalação

Essas funções só estão disponíveis se o PHP foi configurado com a opção --enable-bcmath.

A versão do PHP para Windows tem suporte nativo para esta extensão. Nenhuma extensão adicional precisa ser carregada para usar essas funções.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de configuração da BC Math
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
bcmath.scale | "0" | `INI_ALL` |

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`bcmath.scale` int

  Número de casas decimais para todas as funções BC Math. Veja também bcscale().

  > Nota: BcMath\Number não é afetada por esta configuração.

# BC Math Funções

# bcadd

(PHP 4, PHP 5, PHP 7, PHP 8)

bcadd — Adiciona dois números de precisão arbitrária

### Descrição

function bcadd(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

Soma `num1` e `num2`.

### Parâmetros

`num1`

  O operando da esquerda, como uma string.

`num2`

  O operando da direita, como uma string.

`scale`
  Este parâmetro é usado para definir o número de dígitos após o separador de decimais do resultado. Se for `null`, será usada a escala padrão definida com bcscale(), ou será usado o valor da diretiva INI `bcmath.scale`.

### Valor Retornado

A soma de dois operandos, como uma string.

### Erros/Exceções

Esta função lança uma exceção ValueError nos seguintes casos:

- `num1` ou `num2` não for uma string numérica BCMath bem formada.
- `scale` estiver fora do intervalo válido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `scale` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo de bcadd()

    <?php

    $a = '1.234';
    $b = '5';

    echo bcadd($a, $b);     // 6
    echo bcadd($a, $b, 4);  // 6.2340

    ?>

### Veja Também

- bcsub() - Subtrai um número de precisão arbitrária de outro
- BcMath\Number::add() - Adiciona um número de precisão arbitrária

# bcceil

(PHP 8 >= 8.4.0)

bcceil — Arredonda para cima um número de precisão arbitrária

### Descrição

function bcceil(string `$num`): string

Retorna o próximo valor inteiro mais alto, arredondando `num` para cima se necessário.

### Parâmetros

`num`
  O valor a ser arredondado.

### Valor Retornado

Retorna uma string numérica representando `num` arredondado para cima em direção ao inteiro mais próximo.

### Erros/Exceções

Esta função lança uma exceção ValueError se `num` não for uma string numérica BCMath bem formada.

### Exemplos

Exemplo #1 Exemplo de bcceil()

    <?php
    var_dump(bcceil('4.3'));
    var_dump(bcceil('9.999'));
    var_dump(bcceil('-3.14'));
    ?>

O exemplo acima produzirá:

    string(1) "5"
    string(2) "10"
    string(2) "-3"

### Veja Também

- bcfloor() - Arredonda para baixo um número de precisão arbitrária
- bcround() - Arredonda número de precisão arbitrária
- BcMath\Number::ceil() - Arredonda para cima um número de precisão arbitrária

# bccomp

(PHP 4, PHP 5, PHP 7, PHP 8)

bccomp — Compara dois números de precisão arbitrária

### Descrição

function bccomp(string `$num1`, string `$num2`, ?int `$scale` = `null`): int

Compara `num1` com `num2` e retorna o resultado da comparação como um inteiro.

### Parâmetros

`num1`

  O operando da esquerda, como uma string.

`num2`

  O operando da direita, como uma string.

`scale`
  Este parâmetro é usado para definir o número de dígitos após o separador de decimais do resultado. Se for `null`, será usada a escala padrão definida com bcscale(), ou será usado o valor da diretiva INI `bcmath.scale`.

### Valor Retornado

Retorna `0` se ambos os operandos forem iguais, `1` se `num1` for maior que `num2`, `-1` para o restante.

### Erros/Exceções

Esta função lança uma exceção ValueError nos seguintes casos:

- `num1` ou `num2` não for uma string numérica BCMath bem formada.
- `scale` estiver fora do intervalo válido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `scale` pode ser nulo.

### Exemplos

Exemplo #1 Exemplo de bccomp()

    <?php

    echo bccomp('1', '2') . "\n";   // -1
    echo bccomp('1.00001', '1', 3); // 0
    echo bccomp('1.00001', '1', 5); // 1

    ?>

### Veja Também

- BcMath\Number::compare() - Compara dois números de precisão arbitrária

# bcdiv

(PHP 4, PHP 5, PHP 7, PHP 8)

bcdiv — Divide dois números de precisão arbitrária

### Descrição

function bcdiv(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

Divide `num1` por `num2`.

### Parâmetros

`num1`

  O dividendo, como uma string.

`num2`

  O divisor, como uma string.

`scale`
  Este parâmetro é usado para definir o número de dígitos após o separador de decimais do resultado. Se for `null`, será usada a escala padrão definida com bcscale(), ou será usado o valor da diretiva INI `bcmath.scale`.

### Valor Retornado

Retorna o resultado da divisão como uma string.

### Erros/Exceções

Esta função lança uma exceção ValueError nos seguintes casos:

- `num1` ou `num2` não for uma string numérica BCMath bem formada.
- `scale` estiver fora do intervalo válido.

Esta função lança uma exceção DivisionByZeroError se `num2` for igual a `0`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `scale` agora pode ser nulo.
8.0.0 | Dividir por `0` agora lança uma exceção DivisionByZeroError ao invés de retornar `null`.

### Exemplos

Exemplo #1 Exemplo de bcdiv()

    <?php

    echo bcdiv('105', '6.55957', 3);  // 16.007

    ?>

### Veja Também

- bcdivmod() - Obtém o quociente e o módulo de um número de precisão arbitrário
- bcmod() - Obtém o resto de uma divisão com precisão arbitrária
- bcmul() - Multiplica dois números de precisão arbitrária
- BcMath\Number::div() - Divide por um número de precisão arbitrária

# bcdivmod

(PHP 8 >= 8.4.0)

bcdivmod — Obtém o quociente e o módulo de um número de precisão arbitrário

### Descrição

function bcdivmod(string `$num1`, string `$num2`, ?int `$scale` = `null`): array

Obtém o quociente e o resto da divisão de `num1` por `num2`.

### Parâmetros

`num1`

  O dividendo, como uma string.

`num2`

  O divisor, como uma string.

`scale`
  Este parâmetro é usado para definir o número de dígitos após o separador de decimais do resultado. Se for `null`, será usada a escala padrão definida com bcscale(), ou será usado o valor da diretiva INI `bcmath.scale`.

### Valor Retornado

Retorna um array indexado onde o primeiro elemento é o quociente como uma string e o segundo elemento é o restante como uma string.

### Erros/Exceções

Esta função lança uma exceção ValueError nos seguintes casos:

- `num1` ou `num2` não for uma string numérica BCMath bem formada.
- `scale` estiver fora do intervalo válido.

Esta função lança uma exceção DivisionByZeroError se `num2` for igual a `0`.

### Exemplos

Exemplo #1 Exemplo de bcdivmod()

    <?php
    bcscale(0);

    [$quot, $rem] = bcdivmod('5',  '3');
    echo $quot; // 1
    echo $rem;  // 2

    [$quot, $rem] = bcdivmod('5',  '-3');
    echo $quot; // -1
    echo $rem;  // 2

    [$quot, $rem] = bcdivmod('-5',  '3');
    echo $quot; // -1
    echo $rem;  // -2

    [$quot, $rem] = bcdivmod('-5',  '-3');
    echo $quot; // 1
    echo $rem;  // -2
    ?>

Exemplo #2 bcdivmod() com decimais

    <?php
    [$quot, $rem] = bcdivmod('5.7', '1.3', 1);
    echo $quot; // 4
    echo $rem;  // 0.5
    ?>

### Veja Também

- bcdiv() - Divide dois números de precisão arbitrária
- bcmod() - Obtém o resto de uma divisão com precisão arbitrária
- BcMath\Number::divmod() - Obtém quociente e resto de um número de precisão arbitrária

# bcfloor

(PHP 8 >= 8.4.0)

bcfloor — Arredonda para baixo um número de precisão arbitrária

### Descrição

function bcfloor(string `$num`): string

Retorna o próximo valor inteiro mais baixo arredondando `num` para baixo, se necessário.

### Parâmetros

`num`
  O valor a ser arredondado.

### Valor Retornado

Retorna uma string numérica representando `num` arredondado para o número inteiro mais próximo.

### Erros/Exceções

Esta função lança uma exceção ValueError se `num` não for uma string numérica BCMath bem formada.

### Exemplos

Exemplo #1 Exemplo de bcfloor()

    <?php
    var_dump(bcfloor('4.3'));
    var_dump(bcfloor('9.999'));
    var_dump(bcfloor('-3.14'));
    ?>

O exemplo acima produzirá:

    string(1) "4"
    string(1) "9"
    string(2) "-4"

### Veja Também

- bcceil() - Arredonda para cima um número de precisão arbitrária
- bcround() - Arredonda número de precisão arbitrária
- BcMath\Number::floor() - Arredonda para baixo um número de precisão arbitrária

# bcmod

(PHP 4, PHP 5, PHP 7, PHP 8)

bcmod — Obtém o resto de uma divisão com precisão arbitrária

### Descrição

function bcmod(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

Obtém o resto da divisão de `num1` por `num2`. O resultado tem o mesmo sinal de `num1`.

### Parâmetros

`num1`

  O operando da esquerda, como uma string.

`num2`

  O operando da direita, como uma string.

`scale`
  Este parâmetro é usado para definir o número de dígitos após o separador de decimais do resultado. Se for `null`, será usada a escala padrão definida com bcscale(), ou será usado o valor da diretiva INI `bcmath.scale`.

### Valor Retornado

Retorna o resto como uma string.

### Erros/Exceções

Esta função lança uma exceção ValueError nos seguintes casos:

- `num1` ou `num2` não for uma string numérica BCMath bem formada.
- `scale` estiver fora do intervalo válido.

Esta função lança uma exceção DivisionByZeroError se `num2` for igual a `0`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `scale` pode ser null.
8.0.0 | Dividir por `0` agora lança uma exceção DivisionByZeroError ao invés de retornar null.
7.2.0 | `num1` e `num2` não são mais truncados para inteiro, de forma que o comportamento de bcmod() é o mesmo de fmod() ao invés do operador `%`.
7.2.0 | O parâmetro `scale` foi adicionado.

### Exemplos

Exemplo #1 Exemplo de bcmod()

    <?php
    bcscale(0);
    echo bcmod( '5',  '3'); //  2
    echo bcmod( '5', '-3'); //  2
    echo bcmod('-5',  '3'); // -2
    echo bcmod('-5', '-3'); // -2
    ?>

Exemplo #2 Exemplo de bcmod() com decimais

    <?php
    bcscale(1);
    echo bcmod('5.7', '1.3'); // 0.5 no PHP 7.2.0; anteriormente 0
    ?>

### Veja Também

- bcdiv() - Divide dois números de precisão arbitrária
- bcdivmod() - Obtém o quociente e o módulo de um número de precisão arbitrário
- BcMath\Number::mod() - Obtém o resto de um número de precisão arbitrária

# bcmul

(PHP 4, PHP 5, PHP 7, PHP 8)

bcmul — Multiplica dois números de precisão arbitrária

### Descrição

function bcmul(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

Multiplica `num1` por `num2`.

### Parâmetros

`num1`

  O operando da esquerda, como uma string.

`num2`

  O operando da direita, como uma string.

`scale`
  Este parâmetro é usado para definir o número de dígitos após o separador de decimais do resultado. Se for `null`, será usada a escala padrão definida com bcscale(), ou será usado o valor da diretiva INI `bcmath.scale`.

### Valor Retornado

Retorna o resultado como uma string.

### Erros/Exceções

Esta função lança uma exceção ValueError nos seguintes casos:

- `num1` ou `num2` não for uma string numérica BCMath bem formada.
- `scale` estiver fora do intervalo válido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `scale` agora pode ser nulo.
7.3.0 | bcmul() agora retorna números com a escala solicitada. Formalmente o número retornado pode ter alguns zeros decimais omitidos.

### Exemplos

Exemplo #1 Exemplo de bcmul()

    <?php
    echo bcmul('1.34747474747', '35', 3); // 47.161
    echo bcmul('2', '4'); // 8
    ?>

### Notas

> Nota:

> Anteriormente ao PHP 7.3.0, bcmul() poderia retornar um número com menos dígitos após o ponto decimal em comparação ao que o parâmetro `scale` indicaria. Isto ocorre apenas quando o resultado não exige toda a precisão permitida pelo parâmetro `scale`. Por exemplo:

> Exemplo #2 Exemplo de bcmul() com escala

>     <?php
>     echo bcmul('5', '2', 2);     // Exibe "10", não "10.00"
>     ?>

### Veja Também

- bcdiv() - Divide dois números de precisão arbitrária
- BcMath\Number::mul() - Multiplica um número de precisão arbitrária

# bcpow

(PHP 4, PHP 5, PHP 7, PHP 8)

bcpow — Eleva um número de precisão arbitrária a outro

### Descrição

function bcpow(string `$num`, string `$exponent`, ?int `$scale` = `null`): string

Eleva `num` à potência de `exponent`.

### Parâmetros

`num`

  O número base, como uma string.

`exponent`

  O número expoente, como uma string. Precisa ser um valor sem parte fracionária. Os expoentes válidos dependem da plataforma, mas ao menos são válidos de `-2147483648` até `2147483647`.

`scale`
  Este parâmetro é usado para definir o número de dígitos após o separador de decimais do resultado. Se for `null`, será usada a escala padrão definida com bcscale(), ou será usado o valor da diretiva INI `bcmath.scale`.

### Valor Retornado

Retorna o resultado como uma string.

### Erros/Exceções

Esta função lança uma exceção ValueError nos seguintes casos:

- `num` ou `exponent` não são strings numéricas BCMath bem formadas
- `exponent` tem uma parte fracionária
- `exponent` ou `scale` está fora do intervalo válido

Esta função lança uma exceção DivisionByZeroError se `num` for igual a `0` e `exponent` for um valor negativo.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Potências negativas de `0` anteriormente retornavam `0`, mas agora lançam uma exceção DivisionByZeroError.
8.0.0 | Quando `exponent` tem uma parte fracionária, lança uma exceção ValueError ao invés de truncar o valor.
7.3.0 | bcpow() agora retorna números com a escala solicitada. Mais exatamente, o número retornado pode omitir alguns zeros decimais.

### Exemplos

Exemplo #1 Exemplo da bcpow()

    <?php

    echo bcpow('4.2', '3', 2); // 74.08

    ?>

### Notas

> Nota:

> Anteriormente ao PHP 7.3.0, bcpow() podia retornar um resultado com menos dígitos decimais do que o indicado no parâmetro `scale`. Isto ocorre quando o resultado não requer toda a precisão permitida por `scale`. Por exemplo:

> Exemplo #2 Exemplo bcpow() com scale

>     <?php
>     echo bcpow('5', '2', 2);     // Imprime "25", não "25.00"
>     ?>

### Veja Também

- bcpowmod() - Eleva um número de precisão arbitrária para outro, reduzido por um módulo especificado
- bcsqrt() - Obtém a raiz quadrada de um número de precisão arbitrária
- BcMath\Number::pow() - Eleva um número de precisão arbitrária

# bcpowmod

(PHP 5, PHP 7, PHP 8)

bcpowmod — Eleva um número de precisão arbitrária para outro, reduzido por um módulo especificado

### Descrição

function bcpowmod(
string `$num`,
string `$exponent`,
string `$modulus`,
?int `$scale` = `null`
): string

Utiliza o método de exponenciação rápida para elevar `num` à potência `exponent` levando em conta o módulo `modulus`.

### Parâmetros

`num`

  A base, na forma de inteiro em string (a escala tem que ser zero).

`exponent`

  O expoente, na forma de um inteiro não negativo, em string (a escala tem que ser zero).

`modulus`

  O módulo, na forma de um inteiro em string (a escala tem que ser zero).

`scale`
  Este parâmetro é usado para definir o número de dígitos após o separador de decimais do resultado. Se for `null`, será usada a escala padrão definida com bcscale(), ou será usado o valor da diretiva INI `bcmath.scale`.

### Valor Retornado

Retorna o resultado como uma string.

### Erros/Exceções

Esta função lança uma exceção ValueError nos seguintes casos:

- `num`, `exponent` ou `modulus` não é uma string numérica BCMath bem formada
- `num`, `exponent` ou `modulus` tem uma parte fracionária
- `exponent` é um valor negativo
- `scale` está fora do intervalo válido

Esta função lança uma exceção DivisionByZeroError se `modulus` for igual a `0`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `scale` agora pode ser nulo.
8.0.0 | Agora lança uma exceção ValueError ao invés de retornar `false` se `exponent` for negativo.
8.0.0 | Dividir por `0` agora lança uma exceção DivisionByZeroError ao invés de retornar `false`.

### Exemplos

As seguintes instruções têm funcionalidades idênticas. A versão bcpowmod(), no entanto, executa em menos tempo e pode aceitar parâmetros maiores.

    <?php
    $a = bcpowmod($x, $y, $mod);

    $b = bcmod(bcpow($x, $y), $mod);

    // $a e $b são iguais.

    ?>

### Notas

> Nota:

> Por esse método realizar operações em módulo, números que não sejam inteiros positivos podem gerar resultados inesperados.

### Veja Também

- bcpow() - Eleva um número de precisão arbitrária a outro
- bcmod() - Obtém o resto de uma divisão com precisão arbitrária
- BcMath\Number::powmod() - Eleva um número de precisão arbitrária, reduzido por um módulo especificado

# bcround

(PHP 8 >= 8.4.0)

bcround — Arredonda número de precisão arbitrária

### Descrição

function bcround(string `$num`, int `$precision` = 0, RoundingMode `$mode` = `RoundingMode::HalfAwayFromZero`): string

Retorna o valor arredondado de `num` para a precisão informada em `precision` (número de dígitos após o separador decimal). `precision` também pode ser negativo ou zero (padrão).

### Parâmetros

`num`

  Valor a ser arredondado.

`precision`

  O número opcional de dígitos decimais para arredondar.

  Se `precision` for positivo, `num` será arredondado para `precision` de dígitos significativos depois do ponto decimal.

  Se `precision` for negativo, `num` será arredondado para `precision` de dígitos significativos depois do ponto decimal, isto é: o múltiplo mais próximo de `pow(10, -$precision)`, por exemplo: para um `precision` de -1 `num` é arredondado para dezenas, para um `precision` de -2 para centenas, etc.

`mode`
  Especifica o modo de arredondamento. Para mais informação sobre os modos, consulte RoundingMode.

### Valor Retornado

Retorna uma string numérica representando `num` arredondado para a precisão especificada.

### Erros/Exceções

Esta função lança uma exceção ValueError nos seguintes casos:

- `num` não é uma string numérica BCMath bem formada.
- Um `mode` inválido é especificado.

### Exemplos

Exemplo #1 Exemplos de bcround()

    <?php
    var_dump(bcround('3.4'));
    var_dump(bcround('3.5'));
    var_dump(bcround('3.6'));
    var_dump(bcround('3.6', 0));
    var_dump(bcround('5.045', 2));
    var_dump(bcround('5.055', 2));
    var_dump(bcround('345', -2));
    var_dump(bcround('345', -3));
    var_dump(bcround('678', -2));
    var_dump(bcround('678', -3));
    ?>

O exemplo acima produzirá:

    string(1) "3"
    string(1) "4"
    string(1) "4"
    string(1) "4"
    string(4) "5.05"
    string(4) "5.06"
    string(3) "300"
    string(1) "0"
    string(3) "700"
    string(4) "1000"

Exemplo #2 Exemplo de uso de bcround() com diferentes valores de `precision`

    <?php
    $number = '123.45';

    var_dump(bcround($number, 3));
    var_dump(bcround($number, 2));
    var_dump(bcround($number, 1));
    var_dump(bcround($number, 0));
    var_dump(bcround($number, -1));
    var_dump(bcround($number, -2));
    var_dump(bcround($number, -3));
    ?>

O exemplo acima produzirá:

    string(7) "123.450"
    string(6) "123.45"
    string(5) "123.5"
    string(3) "123"
    string(3) "120"
    string(3) "100"
    string(1) "0"

Exemplo #3 Exemplo de uso de bcround() com diferentes valores de `mode`

    <?php
    echo 'Modos de arredondamento com 9.5' . PHP_EOL;
    var_dump(bcround('9.5', 0, RoundingMode::HalfAwayFromZero));
    var_dump(bcround('9.5', 0, RoundingMode::HalfTowardsZero));
    var_dump(bcround('9.5', 0, RoundingMode::HalfEven));
    var_dump(bcround('9.5', 0, RoundingMode::HalfOdd));
    var_dump(bcround('9.5', 0, RoundingMode::TowardsZero));
    var_dump(bcround('9.5', 0, RoundingMode::AwayFromZero));
    var_dump(bcround('9.5', 0, RoundingMode::NegativeInfinity));
    var_dump(bcround('9.5', 0, RoundingMode::PositiveInfinity));

    echo PHP_EOL;
    echo 'Modos de arredondamento com 8.5' . PHP_EOL;
    var_dump(bcround('8.5', 0, RoundingMode::HalfAwayFromZero));
    var_dump(bcround('8.5', 0, RoundingMode::HalfTowardsZero));
    var_dump(bcround('8.5', 0, RoundingMode::HalfEven));
    var_dump(bcround('8.5', 0, RoundingMode::HalfOdd));
    var_dump(bcround('8.5', 0, RoundingMode::TowardsZero));
    var_dump(bcround('8.5', 0, RoundingMode::AwayFromZero));
    var_dump(bcround('8.5', 0, RoundingMode::NegativeInfinity));
    var_dump(bcround('8.5', 0, RoundingMode::PositiveInfinity));
    ?>

O exemplo acima produzirá:

    Modos de arredondamento com 9.5
    string(2) "10"
    string(1) "9"
    string(2) "10"
    string(1) "9"
    string(1) "9"
    string(2) "10"
    string(1) "9"
    string(2) "10"

    Modos de arredondamento com 8.5
    string(1) "9"
    string(1) "8"
    string(1) "8"
    string(1) "9"
    string(1) "8"
    string(1) "9"
    string(1) "8"
    string(1) "9"

Exemplo #4 Exemplo de uso de bcround() com diferentes valores de `mode` ao especificar `precision`

    <?php
    echo 'Usando RoundingMode::HalfAwayFromZero com precisão de 1 dígito decimal' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::HalfAwayFromZero));
    var_dump(bcround(-1.55, 1, RoundingMode::HalfAwayFromZero));

    echo PHP_EOL;
    echo 'Usando RoundingMode::HalfTowardsZero com precisão de 1 dígito decimal' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::HalfTowardsZero));
    var_dump(bcround(-1.55, 1, RoundingMode::HalfTowardsZero));

    echo PHP_EOL;
    echo 'Usando RoundingMode::HalfEven com precisão de 1 dígito decimal' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::HalfEven));
    var_dump(bcround(-1.55, 1, RoundingMode::HalfEven));

    echo PHP_EOL;
    echo 'Usando RoundingMode::HalfOdd com precisão de 1 dígito decimal' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::HalfOdd));
    var_dump(bcround(-1.55, 1, RoundingMode::HalfOdd));

    echo PHP_EOL;
    echo 'Usando RoundingMode::TowardsZero com precisão de 1 dígito decimal' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::TowardsZero));
    var_dump(bcround(-1.55, 1, RoundingMode::TowardsZero));

    echo PHP_EOL;
    echo 'Usando RoundingMode::AwayFromZero com precisão de 1 dígito decimal' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::AwayFromZero));
    var_dump(bcround(-1.55, 1, RoundingMode::AwayFromZero));

    echo PHP_EOL;
    echo 'Usando RoundingMode::NegativeInfinity com precisão de 1 dígito decimal' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::NegativeInfinity));
    var_dump(bcround(-1.55, 1, RoundingMode::NegativeInfinity));

    echo PHP_EOL;
    echo 'Usando RoundingMode::PositiveInfinity com precisão de 1 dígito decimal' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::PositiveInfinity));
    var_dump(bcround(-1.55, 1, RoundingMode::PositiveInfinity));
    ?>

O exemplo acima produzirá:

    Usando RoundingMode::HalfAwayFromZero com precisão de 1 dígito decimal
    string(3) "1.6"
    string(4) "-1.6"

    Usando RoundingMode::HalfTowardsZero com precisão de 1 dígito decimal
    string(3) "1.5"
    string(4) "-1.5"

    Usando RoundingMode::HalfEven com precisão de 1 dígito decimal
    string(3) "1.6"
    string(4) "-1.6"

    Usando RoundingMode::HalfOdd com precisão de 1 dígito decimal
    string(3) "1.5"
    string(4) "-1.5"

    Usando RoundingMode::TowardsZero com precisão de 1 dígito decimal
    string(3) "1.5"
    string(4) "-1.5"

    Usando RoundingMode::AwayFromZero com precisão de 1 dígito decimal
    string(3) "1.6"
    string(4) "-1.6"

    Usando RoundingMode::NegativeInfinity com precisão de 1 dígito decimal
    string(3) "1.5"
    string(4) "-1.6"

    Usando RoundingMode::PositiveInfinity com precisão de 1 dígito decimal
    string(3) "1.6"
    string(4) "-1.5"

### Veja Também

- bcceil() - Arredonda para cima um número de precisão arbitrária
- bcfloor() - Arredonda para baixo um número de precisão arbitrária
- BcMath\Number::round() - Arredonda um número de precisão arbitrária

# bcscale

(PHP 4, PHP 5, PHP 7, PHP 8)

bcscale — Configura ou obtêm o parâmetro escala para todas as funções bc

### Descrição

function bcscale(int `$scale`): int

Configura o parâmetro de escala padrão para todas as chamadas subsequentes às funções bcmath que não tenham o parâmatro escala informado explicitamente.

function bcscale(null `$scale` = `null`): int

Retorna o valor de escala atual.

### Parâmetros

`scale`

  O fator de escala.

### Valor Retornado

Retorna o valor de escala antigo quando configurando um novo, senão retorna o valor atual.

### Erros/Exceções

Esta função lança uma exceção ValueError se `scale` estiver fora do intervalo válido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `scale` agora pode ser null.
7.3.0 | bcscale() pode ser utilizado para obter o falor de escala atual, quando utilizado para configurar. Anteriormente, `scale` era obrigatório, e bcscale() sempre retornava `true`.

### Exemplos

Exemplo #1 Exemplo da bcscale()

    <?php

    // Escala default: 3
    bcscale(3);
    echo bcdiv('105', '6.55957'); // 16.007

    // Obtém o mesmo resultado sem bcscale()
    echo bcdiv('105', '6.55957', 3); // 16.007

    ?>

# bcsqrt

(PHP 4, PHP 5, PHP 7, PHP 8)

bcsqrt — Obtém a raiz quadrada de um número de precisão arbitrária

### Descrição

function bcsqrt(string `$num`, ?int `$scale` = `null`): string

Retorna a raiz quadrada de `num`.

### Parâmetros

`num`

  O operando, como uma string numérica no padrão BCMath.

`scale`
  Este parâmetro é usado para definir o número de dígitos após o separador de decimais do resultado. Se for `null`, será usada a escala padrão definida com bcscale(), ou será usado o valor da diretiva INI `bcmath.scale`.

### Valor Retornado

Retorna a raiz quadrada como uma string numérica no padrão BCMath.

### Erros/Exceções

Esta função lança um ValueError nas seguintes situações:

- `num` não é uma string numérica no padrão BCMath
- `num` é menor que `0`
- `scale` está fora do range válido

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Se `num` não é uma string numérica no padrão BCMath, ou menor que `0`, um ValueError é lançado. Anteriormente um `E_WARNING` era emitido.
8.0.0 | `scale` agora precisa estar entre `0` e `2147483647`; anteriormente, valores negativos eram tratados silenciosamente como `0`.
8.0.0 | `scale` agora é anulável.

### Exemplos

Exemplo #1 Exemplo de bcsqrt()

    <?php

    echo bcsqrt('2', 3); // 1.414

    ?>

### Veja Também

- bcpow() - Eleva um número de precisão arbitrária a outro
- BcMath\Number::sqrt() - Obtém a raiz quadrada de um número de precisão arbitrária

# bcsub

(PHP 4, PHP 5, PHP 7, PHP 8)

bcsub — Subtrai um número de precisão arbitrária de outro

### Descrição

function bcsub(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

Subtrai `num2` de `num1`.

### Parâmetros

`num1`

  O operando da esquerda, como uma string.

`num2`

  O operando da direita, como uma string.

`scale`
  Este parâmetro é usado para definir o número de dígitos após o separador de decimais do resultado. Se for `null`, será usada a escala padrão definida com bcscale(), ou será usado o valor da diretiva INI `bcmath.scale`.

### Valor Retornado

O resultado da subtração, como uma string.

### Erros/Exceções

Esta função lança uma exceção ValueError nos seguintes casos:

- `num1` ou `num2` não for uma string numérica BCMath bem formada.
- `scale` estiver fora do intervalo válido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `scale` agora pode ser nulo.

### Exemplos

Exemplo #1 Exemplo de bcsub()

    <?php

    $a = '1.234';
    $b = '5';

    echo bcsub($a, $b);     // -3
    echo bcsub($a, $b, 4);  // -3.7660

    ?>

### Veja Também

- bcadd() - Adiciona dois números de precisão arbitrária
- BcMath\Number::sub() - Subtrai um número de precisão arbitrária

## Índice

- bcadd — Adiciona dois números de precisão arbitrária
- bcceil — Arredonda para cima um número de precisão arbitrária
- bccomp — Compara dois números de precisão arbitrária
- bcdiv — Divide dois números de precisão arbitrária
- bcdivmod — Obtém o quociente e o módulo de um número de precisão arbitrário
- bcfloor — Arredonda para baixo um número de precisão arbitrária
- bcmod — Obtém o resto de uma divisão com precisão arbitrária
- bcmul — Multiplica dois números de precisão arbitrária
- bcpow — Eleva um número de precisão arbitrária a outro
- bcpowmod — Eleva um número de precisão arbitrária para outro, reduzido por um módulo especificado
- bcround — Arredonda número de precisão arbitrária
- bcscale — Configura ou obtêm o parâmetro escala para todas as funções bc
- bcsqrt — Obtém a raiz quadrada de um número de precisão arbitrária
- bcsub — Subtrai um número de precisão arbitrária de outro

# A classe BcMath\Number

(PHP 8 >= 8.4.0)

## Introdução

Uma classe para número de precisão arbitrária. Estes objetos suportam sobrecarga de operadores aritméticos e comparativos.

> Nota: Esta classe não é afetada pela diretiva INI bcmath.scale definida no php.ini.

> Nota: O comportamento de um operador sobrecarregado é o mesmo que especificar `null` para o parâmetro `scale` no método correspondente.

## Resumo da classe

namespace BcMath;
final readonly class Number implements Stringable {
/* Propriedades */
public string $value;
public int $scale;
/* Métodos */
public function __construct(string|int `$num`)
public function add(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number
public function ceil(): BcMath\Number
public function compare(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): int
public function div(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number
public function divmod(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): array
public function floor(): BcMath\Number
public function mod(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number
public function mul(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number
public function pow(BcMath\Number|string|int `$exponent`, ?int `$scale` = `null`): BcMath\Number
public function powmod(BcMath\Number|string|int `$exponent`, BcMath\Number|string|int `$modulus`, ?int `$scale` = `null`): BcMath\Number
public function round(int `$precision` = 0, RoundingMode `$mode` = `RoundingMode::HalfAwayFromZero`): BcMath\Number
public function __serialize(): array
public function sqrt(?int `$scale` = `null`): BcMath\Number
public function sub(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number
public function __toString(): string
public function __unserialize(array `$data`): void
}

## Propriedades

value
  Uma representação string de um número de precisão arbitrária.
scale
  O valor de escala atualmente definido no objeto. Para objetos resultantes de cálculos, este valore é computado e definido automaticamente, a menos que o parâmetro `scale` tenha sido definido no método de cálculo.

# BcMath\Number::add

(PHP 8 >= 8.4.0)

BcMath\Number::add — Adiciona um número de precisão arbitrária

### Descrição

public function BcMath\Number::add(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

Adiciona $this e `num`.

### Parâmetros

`num`
  O valor a adicionar.
`scale`
  A propriedade BcMath\Number::scale especifica explicitamente a escala para os resultados de cálculo. Se for `null`, a BcMath\Number::scale do resultado do cálculo será definida automaticamente.

### Valor Retornado

Retorna o resultado da adição como um novo objeto BcMath\Number.

Quando a propriedade BcMath\Number::scale do objeto resultante é definida automaticamente, o maior valor de BcMath\Number::scale dos dois números usados para adição será usado.

Isto é, com a propriedade BcMath\Number::scale de dois valores `2` e `5` respectivamente, a propriedade BcMath\Number::scale do resultado será `5`.

### Erros/Exceções

Este método lança uma exceção ValueError nos seguintes casos:

- `num` é string e não é uma string numérica BCMath bem formada
- `scale` está fora do intervalo válido

### Exemplos

Exemplo #1 Exemplo de BcMath\Number::add() quando `scale` não é especificado

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->add(new BcMath\Number('2.34567'));
    $ret2 = $number->add('-3.456');
    $ret3 = $number->add(7);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

O exemplo acima produzirá:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(7) "3.57967"
      ["scale"]=>
      int(5)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(6) "-2.222"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(5) "8.234"
      ["scale"]=>
      int(3)
    }

Exemplo #2 Exemplo de BcMath\Number::add() com `scale` especificado explicitamente

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->add(new BcMath\Number('2.34567'), 1);
    $ret2 = $number->add('-3.456', 10);
    $ret3 = $number->add(7, 0);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

O exemplo acima produzirá:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(3) "3.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(13) "-2.2220000000"
      ["scale"]=>
      int(10)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }

### Veja Também

- bcadd() - Adiciona dois números de precisão arbitrária
- BcMath\Number::sub() - Subtrai um número de precisão arbitrária

# BcMath\Number::ceil

(PHP 8 >= 8.4.0)

BcMath\Number::ceil — Arredonda para cima um número de precisão arbitrária

### Descrição

public function BcMath\Number::ceil(): BcMath\Number

Retorna o próximo maior valor inteiro arredondando para cima o valor de $this se necessário.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o resultado como um novo objeto BcMath\Number. A propriedade BcMath\Number::scale do resultado será sempre `0`.

### Exemplos

Exemplo #1 Exemplo de BcMath\Number::ceil()

    <?php
    $num1 = new BcMath\Number('4.3')->ceil();
    $num2 = new BcMath\Number('9.999')->ceil();
    $num3 = new BcMath\Number('-3.14')->ceil();

    var_dump($num1, $num2, $num3);
    ?>

O exemplo acima produzirá:

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "5"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(2) "10"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(2) "-3"
      ["scale"]=>
      int(0)
    }

### Veja Também

- bcceil() - Arredonda para cima um número de precisão arbitrária
- BcMath\Number::floor() - Arredonda para baixo um número de precisão arbitrária
- BcMath\Number::round() - Arredonda um número de precisão arbitrária

# BcMath\Number::compare

(PHP 8 >= 8.4.0)

BcMath\Number::compare — Compara dois números de precisão arbitrária

### Descrição

public function BcMath\Number::compare(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): int

Compara dois números de precisão arbitrária. Este método se comporta como o operador nave espacial.

### Parâmetros

`num`
  O valor com o qual será feita a comparação.
`scale`
  O parâmetro `scale` especifica a escala a ser usada para comparação. Se for `null`, todos os dígitos são usados na comparação.

### Valor Retornado

Retorna `0` se os dois números forem iguais, `1` se $this for maior que `num`, `-1` cado contrário.

### Erros/Exceções

Este método lança uma exceção ValueError nos seguintes casos:

- `num` é string e não é uma string numérica BCMath bem formada
- `scale` está fora do intervalo válido

### Exemplos

Exemplo #1 Exemplo de BcMath\Number::compare() quando `scale` não é especificado

    <?php
    $number = new BcMath\Number('1.234');

    var_dump(
        $number->compare(new BcMath\Number('1.234')),
        $number->compare('1.23400'),
        $number->compare('1.23401'),
        $number->compare(1),
    );
    ?>

O exemplo acima produzirá:

    int(0)
    int(0)
    int(-1)
    int(1)

Exemplo #2 Exemplo de BcMath\Number::compare() com especificação explícita de `scale`

    <?php
    $number = new BcMath\Number('1.234');

    var_dump(
        $number->compare(new BcMath\Number('1.299'), 1),
        $number->compare('1.24', 2),
        $number->compare('1.22', 2),
        $number->compare(1, 0),
    );
    ?>

O exemplo acima produzirá:

    int(0)
    int(-1)
    int(1)
    int(0)

### Veja Também

- bccomp() - Compara dois números de precisão arbitrária

# BcMath\Number::__construct

(PHP 8 >= 8.4.0)

BcMath\Number::__construct — Cria um objeto BcMath\Number

### Descrição

public function BcMath\Number::__construct(string|int `$num`)

Cria um objeto BcMath\Number a partir de um valor int ou string.

### Parâmetros

`num`
  Um valor int ou string. Se `num` for um int, BcMath\Number::scale será sempre definida como `0`. Se `num` for uma string, precisa ser um número válido e BcMath\Number::scale será definida automaticamente interpretando a string.

### Erros/Exceções

Este método lança uma exceção ValueError se `num` for uma string e não for uma string numérica BCMath bem formada.

### Exemplos

Exemplo #1 Exemplo de BcMath\Number::__construct()

    <?php
    $num1 = new BcMath\Number(100);
    $num2 = new BcMath\Number('-200');
    $num3 = new BcMath\Number('300.00');

    var_dump($num1, $num2, $num3);
    ?>

O exemplo acima produzirá:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(3) "100"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(4) "-200"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(6) "300.00"
      ["scale"]=>
      int(2)
    }

### Veja Também

- BcMath\Number::__serialize() - Serializa um objeto BcMath\Number
- BcMath\Number::__unserialize() - Desserializa um parâmetro de dados em um objeto BcMath\Number

# BcMath\Number::div

(PHP 8 >= 8.4.0)

BcMath\Number::div — Divide por um número de precisão arbitrária

### Descrição

public function BcMath\Number::div(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

Divide $this por `num`.

### Parâmetros

`num`
  O divisor.
`scale`
  A propriedade BcMath\Number::scale especifica explicitamente a escala para os resultados de cálculo. Se for `null`, a BcMath\Number::scale do resultado do cálculo será definida automaticamente.

### Valor Retornado

Retorna o resultado da divisão como um novo objeto BcMath\Number.

Quando a propriedade BcMath\Number::scale do objeto resultante é definida automaticamente, a BcMath\Number::scale do dividendo é usada. Entretanto, em casos como uma divisão indivisível, a BcMath\Number::scale do resultado é expandida. A expansão é feita apenas quando necessário, até um limite de `+10`.

Ou seja, se a BcMath\Number::scale do dividendo for `5`, a BcMath\Number::scale do resultado estará entre `5` e `15`.

Mesmo em cálculos indivisíveis, a BcMath\Number::scale não será sempre `+10`. Considera-se que um `0` no final do resultado não precisa de expansão, então a BcMath\Number::scale é reduzida por essa quantidade. A BcMath\Number::scale nunca será menor que a BcMath\Number::scale anterior à expansão. Consulte também o exemplo de código.

### Erros/Exceções

Este método lança uma exceção ValueError nos seguintes casos:

- `num` é uma string e não é uma string numérica BCMath bem formada
- `scale` está fora do intervalo válido
- BcMath\Number::scale do objeto resultante está fora do intervalo válido

Este método lança uma exceção DivisionByZeroError se `num` for `0`.

### Exemplos

Exemplo #1 Exemplo de BcMath\Number::div() quando `scale` não for especificado

    <?php
    $number = new BcMath\Number('0.002');

    $ret1 = $number->div(new BcMath\Number('2.000'));
    $ret2 = $number->div('-3');
    $ret3 = $number->div(32);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

O exemplo acima produzirá:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "0.002"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(5) "0.001"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(16) "-0.0006666666666"
      ["scale"]=>
      int(13)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(9) "0.0000625"
      ["scale"]=>
      int(7)
    }

Exemplo #2 Exemplo de BcMath\Number::div() especificando `scale` explicitamente

    <?php
    $number = new BcMath\Number('0.002');

    $ret1 = $number->div(new BcMath\Number('2.000'), 15);
    $ret2 = $number->div('-3', 5);
    $ret3 = $number->div(32, 2);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

O exemplo acima produzirá:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "0.002"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(17) "0.001000000000000"
      ["scale"]=>
      int(15)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(8) "-0.00066"
      ["scale"]=>
      int(5)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(4) "0.00"
      ["scale"]=>
      int(2)
    }

Exemplo #3 Exemplo de BcMath\Number::div() expandindo BcMath\Number::scale do objeto resultante

    <?php
    var_dump(
        new BcMath\Number('0.001')->div('10001'),
        new BcMath\Number('0.001')->div('10001', 13),
        new BcMath\Number('0.001')->div('100000000000001'),
    );
    ?>

O exemplo acima produzirá:

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(13) "0.00000009999"
      ["scale"]=>
      int(11)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(15) "0.0000000999900"
      ["scale"]=>
      int(13)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(5) "0.000"
      ["scale"]=>
      int(3)
    }

### Veja Também

- bcdiv() - Divide dois números de precisão arbitrária
- BcMath\Number::divmod() - Obtém quociente e resto de um número de precisão arbitrária
- BcMath\Number::mod() - Obtém o resto de um número de precisão arbitrária
- BcMath\Number::sqrt() - Obtém a raiz quadrada de um número de precisão arbitrária
- BcMath\Number::pow() - Eleva um número de precisão arbitrária
- BcMath\Number::mul() - Multiplica um número de precisão arbitrária

# BcMath\Number::divmod

(PHP 8 >= 8.4.0)

BcMath\Number::divmod — Obtém quociente e resto de um número de precisão arbitrária

### Descrição

public function BcMath\Number::divmod(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): array

Obtém quociente e resto da divisão de $this por `num`.

### Parâmetros

`num`
  O divisor.
`scale`
  A propriedade BcMath\Number::scale especifica explicitamente a escala para os resultados de cálculo. Se for `null`, a BcMath\Number::scale do resultado do cálculo será definida automaticamente.

### Valor Retornado

Retorna um array indexado onde o primeiro elemento é o quociente como um novo objeto BcMath\Number e o segundo elemento é o resto como um novo objeto BcMath\Number.

O quociente é sempre um valor inteiro, portanto a BcMath\Number::scale do quociente será sempre `0`, independente se `scale` foi definido explicitamente.

Se `scale` for definido explicitamente, a BcMath\Number::scale do resto será o valor especificado. Quando a BcMath\Number::scale do objeto de resto do resultado for definida automaticamente, a maior BcMath\Number::scale dos dois números usados para a operação de resto é usada.

Isto é, se as BcMath\Number::scales de dois valores forem `2` e `5` respectivamente, a BcMath\Number::scale do resto será `5`.

### Erros/Exceções

Este método lança uma exceção ValueError nos seguintes casos:

- `num` é string e não é uma string numérica BCMath bem formada
- `scale` está fora do intervalo válido

Este método lança uma exceção DivisionByZeroError se `num` for `0`.

### Exemplos

Exemplo #1 Exemplo de BcMath\Number::divmod() quando `scale` não for especificado

    <?php
    echo '8.3 / 2.22' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('8')->divmod(new BcMath\Number('2.22'));
    var_dump($quot, $rem);

    echo PHP_EOL . '8.3 / 8.3' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('8.3')->divmod('8.3');
    var_dump($quot, $rem);

    echo PHP_EOL . '10 / -3' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('10')->divmod(-3);
    var_dump($quot, $rem);
    ?>

O exemplo acima produzirá:

    8.3 / 2.22
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "3"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(4) "1.34"
      ["scale"]=>
      int(2)
    }

    8.3 / 8.3
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "1"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(3) "0.0"
      ["scale"]=>
      int(1)
    }

    10 / -3
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(2) "-3"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(1) "1"
      ["scale"]=>
      int(0)
    }

Exemplo #2 Exemplo de BcMath\Number::divmod() especificando `scale` explicitamente

    <?php
    echo '8.3 / 2.22' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('8')->divmod(new BcMath\Number('2.22'), 1);
    var_dump($quot, $rem);

    echo PHP_EOL . '8.3 / 8.3' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('8.3')->divmod('8.3', 4);
    var_dump($quot, $rem);

    echo PHP_EOL . '10 / -3' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('10')->divmod(-3, 5);
    var_dump($quot, $rem);
    ?>

O exemplo acima produzirá:

    8.3 / 2.22
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "3"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.3"
      ["scale"]=>
      int(1)
    }

    8.3 / 8.3
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "1"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(6) "0.0000"
      ["scale"]=>
      int(4)
    }

    10 / -3
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(2) "-3"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(7) "1.00000"
      ["scale"]=>
      int(5)
    }

### Veja Também

- bcdivmod() - Obtém o quociente e o módulo de um número de precisão arbitrário
- BcMath\Number::div() - Divide por um número de precisão arbitrária
- BcMath\Number::mod() - Obtém o resto de um número de precisão arbitrária

# BcMath\Number::floor

(PHP 8 >= 8.4.0)

BcMath\Number::floor — Arredonda para baixo um número de precisão arbitrária

### Descrição

public function BcMath\Number::floor(): BcMath\Number

Retorna o próximo maior valor inteiro arredondando para baixo $this se necessário.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o resultado como um novo objeto BcMath\Number. A propriedade BcMath\Number::scale do resultado será sempre `0`.

### Exemplos

Exemplo #1 Exemplo de BcMath\Number::floor()

    <?php
    $num1 = new BcMath\Number('4.3')->floor();
    $num2 = new BcMath\Number('9.999')->floor();
    $num3 = new BcMath\Number('-3.14')->floor();

    var_dump($num1, $num2, $num3);
    ?>

O exemplo acima produzirá:

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "4"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(2) "-4"
      ["scale"]=>
      int(0)
    }

### Veja Também

- bcfloor() - Arredonda para baixo um número de precisão arbitrária
- BcMath\Number::ceil() - Arredonda para cima um número de precisão arbitrária
- BcMath\Number::round() - Arredonda um número de precisão arbitrária

# BcMath\Number::mod

(PHP 8 >= 8.4.0)

BcMath\Number::mod — Obtém o resto de um número de precisão arbitrária

### Descrição

public function BcMath\Number::mod(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

Obtém o resto da divisão de $this por `num`. A menos que `num` seja `0`, o resultado tem o mesmo sinal de $this.

### Parâmetros

`num`
  O divisor.
`scale`
  A propriedade BcMath\Number::scale especifica explicitamente a escala para os resultados de cálculo. Se for `null`, a BcMath\Number::scale do resultado do cálculo será definida automaticamente.

### Valor Retornado

Retorna o resto como um novo objeto BcMath\Number.

Quando a BcMath\Number::scale do objeto resultante é definida automaticamente, a maior BcMath\Number::scale dos dois números da operação de resto é usada.

Isto é, com a propriedade BcMath\Number::scale de dois valores `2` e `5` respectivamente, a propriedade BcMath\Number::scale do resultado será `5`.

### Erros/Exceções

Este método lança uma exceção ValueError nos seguintes casos:

- `num` é string e não é uma string numérica BCMath bem formada
- `scale` está fora do intervalo válido

Este método lança uma exceção DivisionByZeroError se `num` for `0`.

### Exemplos

Exemplo #1 Exemplo de BcMath\Number::mod() quando `scale` não for especificado

    <?php
    $number = new BcMath\Number('8.3');

    $ret1 = $number->mod(new BcMath\Number('2.22'));
    $ret2 = $number->mod('8.3');
    $ret3 = $number->mod(-5);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

O exemplo acima produzirá:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(3) "8.3"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(4) "1.64"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(3) "0.0"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "3.3"
      ["scale"]=>
      int(1)
    }

Exemplo #2 Exemplo de BcMath\Number::mod() especificando `scale` explicitamente

    <?php
    $number = new BcMath\Number('8.3');

    $ret1 = $number->mod(new BcMath\Number('2.22'), 1);
    $ret2 = $number->mod('8.3', 3);
    $ret3 = $number->mod(-5, 0);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

O exemplo acima produzirá:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(3) "8.3"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(3) "1.6"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(5) "0.000"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "3"
      ["scale"]=>
      int(0)
    }

### Veja Também

- bcmod() - Obtém o resto de uma divisão com precisão arbitrária
- BcMath\Number::div() - Divide por um número de precisão arbitrária
- BcMath\Number::divmod() - Obtém quociente e resto de um número de precisão arbitrária
- BcMath\Number::powmod() - Eleva um número de precisão arbitrária, reduzido por um módulo especificado

# BcMath\Number::mul

(PHP 8 >= 8.4.0)

BcMath\Number::mul — Multiplica um número de precisão arbitrária

### Descrição

public function BcMath\Number::mul(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

Multiplica $this por `num`.

### Parâmetros

`num`
  O multiplicador.
`scale`
  A propriedade BcMath\Number::scale especifica explicitamente a escala para os resultados de cálculo. Se for `null`, a BcMath\Number::scale do resultado do cálculo será definida automaticamente.

### Valor Retornado

Retorna o resultado da multiplicação como um novo objeto BcMath\Number.

Quando a BcMath\Number::scale do objeto resultante é definida automaticamente, a soma das BcMath\Number::scales dos dois valores da multiplicação é usada.

Isto é, se as BcMath\Number::scales de dois valores forem `2` e `5` respectivamente, a BcMath\Number::scale do resultado será `7`.

### Erros/Exceções

Este método lança uma exceção ValueError nos seguintes casos:

- `num` é uma string e não é uma string numérica BCMath bem formada
- `scale` está fora do intervalo válido
- BcMath\Number::scale do objeto resultante está fora do intervalo válido

### Exemplos

Exemplo #1 Exemplo de BcMath\Number::mul() quando `scale` não é especificado

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->mul(new BcMath\Number('2.3456'));
    $ret2 = $number->mul('-3.4');
    $ret3 = $number->mul(7);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

O exemplo acima produzirá:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(9) "2.8944704"
      ["scale"]=>
      int(7)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(7) "-4.1956"
      ["scale"]=>
      int(4)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(5) "8.638"
      ["scale"]=>
      int(3)
    }

Exemplo #2 Exemplo de BcMath\Number::mul() especificando `scale` explicitamente

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->mul(new BcMath\Number('2.3456'), 1);
    $ret2 = $number->mul('-3.4', 10);
    $ret3 = $number->mul(7, 0);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

O exemplo acima produzirá:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(3) "2.8"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(13) "-4.1956000000"
      ["scale"]=>
      int(10)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }

### Veja Também

- bcmul() - Multiplica dois números de precisão arbitrária
- BcMath\Number::div() - Divide por um número de precisão arbitrária
- BcMath\Number::pow() - Eleva um número de precisão arbitrária
- BcMath\Number::powmod() - Eleva um número de precisão arbitrária, reduzido por um módulo especificado

# BcMath\Number::pow

(PHP 8 >= 8.4.0)

BcMath\Number::pow — Eleva um número de precisão arbitrária

### Descrição

public function BcMath\Number::pow(BcMath\Number|string|int `$exponent`, ?int `$scale` = `null`): BcMath\Number

Eleva $this à potência `exponent`.

### Parâmetros

`exponent`
  O expoente. Precisa ser um valor sem parte fracionária. O intervalo válido de `exponent` é específico por plataforma, mas é pelo menos de `-2147483648` a `2147483647`.
`scale`
  A propriedade BcMath\Number::scale especifica explicitamente a escala para os resultados de cálculo. Se for `null`, a BcMath\Number::scale do resultado do cálculo será definida automaticamente.

### Valor Retornado

Retorna o resultado da potenciação como um novo objeto BcMath\Number.

Quando a BcMath\Number::scale do objeto resultante é definida automaticamente, dependendo do valor de `exponent`, a BcMath\Number::scale do resultado será o seguinte:

`exponent` | BcMath\Number::scale do resultado
--- | ---
positivo | (BcMath\Number::scale da base) * (valor do `exponent`)
`0` | `0`
negativo | Entre (BcMath\Number::scale da base) e (BcMath\Number::scale da base + `10`)

Se uma divisão indivisível ocorrer devido a um `exponent` negativo, a BcMath\Number::scale do resultado é expandida. A expansão é feita conforme necessidade, até um máximo de `+10`. Este comportamento é o mesmo de BcMath\Number::div(), portanto consulte esse método para detalhes.

### Erros/Exceções

Este método lança uma exceção ValueError nos casos a seguir:

- `exponent` é uma string e não é uma string numérica BCMath bem formada
- `exponent` tem uma parte fracionária
- `exponent` ou `scale` está fora do intervalo válido
- BcMath\Number::scale do objeto resultante está fora do intervalo válido

Este método lança uma exceção DivisionByZeroError se o valor de $this for `0` e o `exponent` for um valor negativo.

### Exemplos

Exemplo #1 Exemplo de BcMath\Number::pow() quando `scale` não é especificado

    <?php
    $number = new BcMath\Number('3.0');

    $ret1 = $number->pow(new BcMath\Number('5'));
    $ret2 = $number->pow('-1');
    $ret3 = $number->pow(0);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

O exemplo acima produzirá:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(3) "3.0"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(9) "243.00000"
      ["scale"]=>
      int(5)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(13) "0.33333333333"
      ["scale"]=>
      int(11)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "1"
      ["scale"]=>
      int(0)
    }

Exemplo #2 Exemplo de BcMath\Number::pow() especificando `scale` explicitamente

    <?php
    $number = new BcMath\Number('3.0');

    $ret1 = $number->pow(new BcMath\Number('5'), 0);
    $ret2 = $number->pow('-1', 2);
    $ret3 = $number->pow(0, 10);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

O exemplo acima produzirá:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(3) "3.0"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(3) "243"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(4) "0.33"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(12) "1.0000000000"
      ["scale"]=>
      int(10)
    }

### Veja Também

- bcpow() - Eleva um número de precisão arbitrária a outro
- BcMath\Number::powmod() - Eleva um número de precisão arbitrária, reduzido por um módulo especificado
- BcMath\Number::mul() - Multiplica um número de precisão arbitrária
- BcMath\Number::sqrt() - Obtém a raiz quadrada de um número de precisão arbitrária
- BcMath\Number::div() - Divide por um número de precisão arbitrária

# BcMath\Number::powmod

(PHP 8 >= 8.4.0)

BcMath\Number::powmod — Eleva um número de precisão arbitrária, reduzido por um módulo especificado

### Descrição

public function BcMath\Number::powmod(BcMath\Number|string|int `$exponent`, BcMath\Number|string|int `$modulus`, ?int `$scale` = `null`): BcMath\Number

Usa o método de exponenciação rápida para elevar $this à potência de `exponent` em relação ao módulo `modulus`.

### Parâmetros

`exponent`
  O expoente, com um número inteiro não negativo (a escala precisa ser zero).
`modulus`
  O módulo, como um inteiro (a escala precisa ser zero).
`scale`
  A propriedade BcMath\Number::scale especifica explicitamente a escala para os resultados de cálculo. Se for `null`, a BcMath\Number::scale do resultado do cálculo será definida automaticamente.

### Valor Retornado

Retorna o resultado como um novo objeto BcMath\Number.

Quando a BcMath\Number::scale do objeto resultante é definida automaticamente, a BcMath\Number::scale do objeto resultante será sempre `0`.

### Erros/Exceções

Este método lança uma exceção ValueError nos casos a seguir:

- `exponent` ou `modulus` é uma string e não é uma string numérica BCMath bem formada
- $this, `exponent` ou `modulus` tem uma parte fracionária
- `exponent` é um valor negativo
- `scale` está fora do intervalo válido

Este método lança uma exceção DivisionByZeroError se o valor de `modulus` for igual a `0`.

### Exemplos

Exemplo #1 Exemplo de BcMath\Number::powmod() quando `scale` não é especificado

    <?php
    var_dump(
        new BcMath\Number('8')->powmod(new BcMath\Number('3'), 5),
        new BcMath\Number('-8')->powmod(new BcMath\Number('3'), 5),
        new BcMath\Number('8')->powmod('2', -3),
        new BcMath\Number('-8')->powmod(5, 7),
    );
    ?>

O exemplo acima produzirá:

    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "2"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(2) "-2"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "1"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(2) "-1"
      ["scale"]=>
      int(0)
    }

Exemplo #2 Exemplo de BcMath\Number::powmod() especificando `scale` explicitamente

    <?php
    var_dump(
        new BcMath\Number('8')->powmod(new BcMath\Number('3'), 5, 1),
        new BcMath\Number('-8')->powmod(new BcMath\Number('3'), 5, 2),
        new BcMath\Number('8')->powmod('2', -3, 3),
        new BcMath\Number('-8')->powmod(5, 7, 4),
    );
    ?>

O exemplo acima produzirá:

    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(3) "2.0"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(5) "-2.00"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(5) "1.000"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(7) "-1.0000"
      ["scale"]=>
      int(4)
    }

### Veja Também

- bcpowmod() - Eleva um número de precisão arbitrária para outro, reduzido por um módulo especificado
- BcMath\Number::pow() - Eleva um número de precisão arbitrária
- BcMath\Number::mod() - Obtém o resto de um número de precisão arbitrária

# BcMath\Number::round

(PHP 8 >= 8.4.0)

BcMath\Number::round — Arredonda um número de precisão arbitrária

### Descrição

public function BcMath\Number::round(int `$precision` = 0, RoundingMode `$mode` = `RoundingMode::HalfAwayFromZero`): BcMath\Number

Retorna o valor arredondado de $this para a precisão especificada em `precision` (número de dígitos fracionários). `precision` pode ser também negativo ou zero (padrão).

### Parâmetros

`precision`

  O número opcional de dígitos decimais para arredondar.

  Se `precision` for positivo, `num` será arredondado para `precision` de dígitos significativos depois do ponto decimal.

  Se `precision` for negativo, `num` será arredondado para `precision` de dígitos significativos depois do ponto decimal, isto é: o múltiplo mais próximo de `pow(10, -$precision)`, por exemplo: para um `precision` de -1 `num` é arredondado para dezenas, para um `precision` de -2 para centenas, etc.

`mode`
  Especifica o modo de arredondamento. Para mais informação sobre os modos, consulte RoundingMode.

### Valor Retornado

Retorna o resultado como um novo objeto BcMath\Number.

### Erros/Exceções

Este método lança uma exceção ValueError se um parâmetro `mode` inválido for especificado.

### Exemplos

Exemplo #1 Exemplo de BcMath\Number::round()

    <?php
    var_dump(
        new BcMath\Number('3.4')->round(),
        new BcMath\Number('3.5')->round(),
        new BcMath\Number('3.6')->round(),
        new BcMath\Number('3.6')->round(0),
        new BcMath\Number('5.045')->round(2),
        new BcMath\Number('5.055')->round(2),
        new BcMath\Number('345')->round(-2),
        new BcMath\Number('345')->round(-3),
        new BcMath\Number('678')->round(-2),
        new BcMath\Number('678')->round(-3),
    );
    ?>

O exemplo acima produzirá:

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "3"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "4"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "4"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(1) "4"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#6 (2) {
      ["value"]=>
      string(4) "5.05"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#7 (2) {
      ["value"]=>
      string(4) "5.06"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#8 (2) {
      ["value"]=>
      string(3) "300"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#9 (2) {
      ["value"]=>
      string(1) "0"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#10 (2) {
      ["value"]=>
      string(3) "700"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#11 (2) {
      ["value"]=>
      string(4) "1000"
      ["scale"]=>
      int(0)
    }

Exemplo #2 Exemplo de uso de BcMath\Number::round() com valores diferentes de `precision`

    <?php
    $number = new BcMath\Number('123.45');

    var_dump(
        $number->round(3),
        $number->round(2),
        $number->round(1),
        $number->round(0),
        $number->round(-1),
        $number->round(-2),
        $number->round(-3),
    );
    ?>

O exemplo acima produzirá:

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(7) "123.450"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(6) "123.45"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(5) "123.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(3) "123"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#6 (2) {
      ["value"]=>
      string(3) "120"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#7 (2) {
      ["value"]=>
      string(3) "100"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#8 (2) {
      ["value"]=>
      string(1) "0"
      ["scale"]=>
      int(0)
    }

Exemplo #3 Exemplo de uso de BcMath\Number::round() com valores diferentes de `mode`

    <?php
    echo 'Modos de arredondamento com 9.5' . PHP_EOL;
    $number = new BcMath\Number('9.5');
    var_dump(
        $number->round(0, RoundingMode::HalfAwayFromZero),
        $number->round(0, RoundingMode::HalfTowardsZero),
        $number->round(0, RoundingMode::HalfEven),
        $number->round(0, RoundingMode::HalfOdd),
        $number->round(0, RoundingMode::TowardsZero),
        $number->round(0, RoundingMode::AwayFromZero),
        $number->round(0, RoundingMode::NegativeInfinity),
        $number->round(0, RoundingMode::PositiveInfinity),
    );

    echo PHP_EOL;
    echo 'Modos de arredondamento com 8.5' . PHP_EOL;
    $number = new BcMath\Number('8.5');
    var_dump(
        $number->round(0, RoundingMode::HalfAwayFromZero),
        $number->round(0, RoundingMode::HalfTowardsZero),
        $number->round(0, RoundingMode::HalfEven),
        $number->round(0, RoundingMode::HalfOdd),
        $number->round(0, RoundingMode::TowardsZero),
        $number->round(0, RoundingMode::AwayFromZero),
        $number->round(0, RoundingMode::NegativeInfinity),
        $number->round(0, RoundingMode::PositiveInfinity),
    );
    ?>

O exemplo acima produzirá:

    Modos de arredondamento com 9.5
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(2) "10"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#7 (2) {
      ["value"]=>
      string(2) "10"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#9 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#11 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#13 (2) {
      ["value"]=>
      string(2) "10"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#15 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#17 (2) {
      ["value"]=>
      string(2) "10"
      ["scale"]=>
      int(0)
    }

    Modos de arredondamento com 8.5
    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#15 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#13 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#11 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#9 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#7 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }

Exemplo #4 Exemplo de uso de BcMath\Number::round() com valores diferentes de `mode` quando `precision` é especificado

    <?php
    $positive = new BcMath\Number('1.55');
    $negative = new BcMath\Number('-1.55');

    echo 'Usando RoundingMode::HalfAwayFromZero com precisão de 1 dígito decimal' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::HalfAwayFromZero),
        $negative->round(1, RoundingMode::HalfAwayFromZero),
    );

    echo PHP_EOL;
    echo 'Usando RoundingMode::HalfTowardsZero com precisão de 1 dígito decimal' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::HalfTowardsZero),
        $negative->round(1, RoundingMode::HalfTowardsZero),
    );

    echo PHP_EOL;
    echo 'Usando RoundingMode::HalfEven com precisão de 1 dígito decimal' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::HalfEven),
        $negative->round(1, RoundingMode::HalfEven),
    );

    echo PHP_EOL;
    echo 'Usando RoundingMode::HalfOdd com precisão de 1 dígito decimal' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::HalfOdd),
        $negative->round(1, RoundingMode::HalfOdd),
    );

    echo PHP_EOL;
    echo 'Usando RoundingMode::TowardsZero com precisão de 1 dígito decimal' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::TowardsZero),
        $negative->round(1, RoundingMode::TowardsZero),
    );

    echo PHP_EOL;
    echo 'Usando RoundingMode::AwayFromZero com precisão de 1 dígito decimal' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::AwayFromZero),
        $negative->round(1, RoundingMode::AwayFromZero),
    );

    echo PHP_EOL;
    echo 'Usando RoundingMode::NegativeInfinity com precisão de 1 dígito decimal' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::NegativeInfinity),
        $negative->round(1, RoundingMode::NegativeInfinity),
    );

    echo PHP_EOL;
    echo 'Usando RoundingMode::PositiveInfinity com precisão de 1 dígito decimal' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::PositiveInfinity),
        $negative->round(1, RoundingMode::PositiveInfinity),
    );
    ?>

O exemplo acima produzirá:

    Usando RoundingMode::HalfAwayFromZero com precisão de 1 dígito decimal
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.6"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(4) "-1.6"
      ["scale"]=>
      int(1)
    }

    Usando RoundingMode::HalfTowardsZero com precisão de 1 dígito decimal
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#6 (2) {
      ["value"]=>
      string(4) "-1.5"
      ["scale"]=>
      int(1)
    }

    Usando RoundingMode::HalfEven com precisão de 1 dígito decimal
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.6"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#7 (2) {
      ["value"]=>
      string(4) "-1.6"
      ["scale"]=>
      int(1)
    }

    Usando RoundingMode::HalfOdd com precisão de 1 dígito decimal
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#8 (2) {
      ["value"]=>
      string(4) "-1.5"
      ["scale"]=>
      int(1)
    }

    Usando RoundingMode::TowardsZero com precisão de 1 dígito decimal
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#9 (2) {
      ["value"]=>
      string(4) "-1.5"
      ["scale"]=>
      int(1)
    }

    Usando RoundingMode::AwayFromZero com precisão de 1 dígito decimal
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.6"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#10 (2) {
      ["value"]=>
      string(4) "-1.6"
      ["scale"]=>
      int(1)
    }

    Usando RoundingMode::NegativeInfinity com precisão de 1 dígito decimal
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#11 (2) {
      ["value"]=>
      string(4) "-1.6"
      ["scale"]=>
      int(1)
    }

    Usando RoundingMode::PositiveInfinity com precisão de 1 dígito decimal
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.6"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#12 (2) {
      ["value"]=>
      string(4) "-1.5"
      ["scale"]=>
      int(1)
    }

### Veja Também

- bcround() - Arredonda número de precisão arbitrária
- BcMath\Number::ceil() - Arredonda para cima um número de precisão arbitrária
- BcMath\Number::floor() - Arredonda para baixo um número de precisão arbitrária

# BcMath\Number::__serialize

(PHP 8 >= 8.4.0)

BcMath\Number::__serialize — Serializa um objeto BcMath\Number

### Descrição

public function BcMath\Number::__serialize(): array

Serializa $this.

### Parâmetros

Esta função não possui parâmetros.

### Veja Também

- BcMath\Number::__construct() - Cria um objeto BcMath\Number
- BcMath\Number::__unserialize() - Desserializa um parâmetro de dados em um objeto BcMath\Number

# BcMath\Number::sqrt

(PHP 8 >= 8.4.0)

BcMath\Number::sqrt — Obtém a raiz quadrada de um número de precisão arbitrária

### Descrição

public function BcMath\Number::sqrt(?int `$scale` = `null`): BcMath\Number

Retorna a raiz quadrada de $this.

### Parâmetros

`scale`
  A propriedade BcMath\Number::scale especifica explicitamente a escala para os resultados de cálculo. Se for `null`, a BcMath\Number::scale do resultado do cálculo será definida automaticamente.

### Valor Retornado

Retorna a raiz quadrada como um novo objeto BcMath\Number.

Quando a propriedade BcMath\Number::scale do objeto resultante é definida automaticamente, a BcMath\Number::scale de $this é usada. Entretanto, em casos como uma divisão indivisível, a BcMath\Number::scale do resultado é expandida. A expansão é feita apenas quando necessário, até um limite de `+10`. Este comportamento é o mesmo de BcMath\Number::div(), consulte este método para detalhes.

Ou seja, se a BcMath\Number::scale de $this for `5`, a BcMath\Number::scale do resultado estará entre `5` e `15`.

### Erros/Exceções

Este método lança uma exceção ValueError nos seguintes casos:

- $this é um valor negativo
- `scale` está fora do intervalo válido
- BcMath\Number::scale do objeto resultante está fora do intervalo válido

### Exemplos

Exemplo #1 Exemplo de BcMath\Number::sqrt()

    <?php
    var_dump(
        new BcMath\Number('2')->sqrt(),
        new BcMath\Number('2')->sqrt(3),
        new BcMath\Number('4')->sqrt(),
        new BcMath\Number('4')->sqrt(3),
    );
    ?>

O exemplo acima produzirá:

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(12) "1.4142135623"
      ["scale"]=>
      int(10)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(5) "1.414"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "2"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(5) "2.000"
      ["scale"]=>
      int(3)
    }

### Veja Também

- bcsqrt() - Obtém a raiz quadrada de um número de precisão arbitrária
- BcMath\Number::div() - Divide por um número de precisão arbitrária
- BcMath\Number::pow() - Eleva um número de precisão arbitrária

# BcMath\Number::sub

(PHP 8 >= 8.4.0)

BcMath\Number::sub — Subtrai um número de precisão arbitrária

### Descrição

public function BcMath\Number::sub(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

Subtrai `num` de $this.

### Parâmetros

`num`
  O valor a subtrair.
`scale`
  A propriedade BcMath\Number::scale especifica explicitamente a escala para os resultados de cálculo. Se for `null`, a BcMath\Number::scale do resultado do cálculo será definida automaticamente.

### Valor Retornado

Retorna o resultado da subtração como um novo objeto BcMath\Number.

Quando a propriedade BcMath\Number::scale do objeto resultante é definida automaticamente, o maior valor de BcMath\Number::scale dos dois números da subtração será usado.

Isto é, com a propriedade BcMath\Number::scale de dois valores `2` e `5` respectivamente, a propriedade BcMath\Number::scale do resultado será `5`.

### Erros/Exceções

Este método lança uma exceção ValueError nos seguintes casos:

- `num` é string e não é uma string numérica BCMath bem formada
- `scale` está fora do intervalo válido

### Exemplos

Exemplo #1 Exemplo de BcMath\Number::sub() quando `scale` não é especificado

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->sub(new BcMath\Number('2.34567'));
    $ret2 = $number->sub('-3.456');
    $ret3 = $number->sub(7);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

O exemplo acima produzirá:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(8) "-1.11167"
      ["scale"]=>
      int(5)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(5) "4.690"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(6) "-5.766"
      ["scale"]=>
      int(3)
    }

Exemplo #2 Exemplo de BcMath\Number::sub() com `scale` especificado explicitamente

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->sub(new BcMath\Number('2.34567'), 1);
    $ret2 = $number->sub('-3.456', 10);
    $ret3 = $number->sub(7, 0);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

O exemplo acima produzirá:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(4) "-1.1"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(12) "4.6900000000"
      ["scale"]=>
      int(10)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(2) "-5"
      ["scale"]=>
      int(0)
    }

### Veja Também

- bcsub() - Subtrai um número de precisão arbitrária de outro
- BcMath\Number::add() - Adiciona um número de precisão arbitrária

# BcMath\Number::__toString

(PHP 8 >= 8.4.0)

BcMath\Number::__toString — Converte BcMath\Number em uma string

### Descrição

public function BcMath\Number::__toString(): string

Converte BcMath\Number em uma string.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna BcMath\Number::value como uma string.

# BcMath\Number::__unserialize

(PHP 8 >= 8.4.0)

BcMath\Number::__unserialize — Desserializa um parâmetro de dados em um objeto BcMath\Number

### Descrição

public function BcMath\Number::__unserialize(array `$data`): void

Desserializa um parâmetro de dados em um objeto BcMath\Number.

### Parâmetros

`data`
  O parâmetro de dados serializado como um array associativo.

### Erros/Exceções

Este método lança uma exceção ValueError se dados serializados inválidos forem passados.

### Veja Também

- BcMath\Number::__construct() - Cria um objeto BcMath\Number
- BcMath\Number::serialize()

## Índice

- BcMath\Number::add — Adiciona um número de precisão arbitrária
- BcMath\Number::ceil — Arredonda para cima um número de precisão arbitrária
- BcMath\Number::compare — Compara dois números de precisão arbitrária
- BcMath\Number::__construct — Cria um objeto BcMath\Number
- BcMath\Number::div — Divide por um número de precisão arbitrária
- BcMath\Number::divmod — Obtém quociente e resto de um número de precisão arbitrária
- BcMath\Number::floor — Arredonda para baixo um número de precisão arbitrária
- BcMath\Number::mod — Obtém o resto de um número de precisão arbitrária
- BcMath\Number::mul — Multiplica um número de precisão arbitrária
- BcMath\Number::pow — Eleva um número de precisão arbitrária
- BcMath\Number::powmod — Eleva um número de precisão arbitrária, reduzido por um módulo especificado
- BcMath\Number::round — Arredonda um número de precisão arbitrária
- BcMath\Number::__serialize — Serializa um objeto BcMath\Number
- BcMath\Number::sqrt — Obtém a raiz quadrada de um número de precisão arbitrária
- BcMath\Number::sub — Subtrai um número de precisão arbitrária
- BcMath\Number::__toString — Converte BcMath\Number em uma string
- BcMath\Number::__unserialize — Desserializa um parâmetro de dados em um objeto BcMath\Number

- Instalação/Configuração
  - Instalação
  - Configurações em Execução
- BC Math Funções
  - bcadd — Adiciona dois números de precisão arbitrária
  - bcceil — Arredonda para cima um número de precisão arbitrária
  - bccomp — Compara dois números de precisão arbitrária
  - bcdiv — Divide dois números de precisão arbitrária
  - bcdivmod — Obtém o quociente e o módulo de um número de precisão arbitrário
  - bcfloor — Arredonda para baixo um número de precisão arbitrária
  - bcmod — Obtém o resto de uma divisão com precisão arbitrária
  - bcmul — Multiplica dois números de precisão arbitrária
  - bcpow — Eleva um número de precisão arbitrária a outro
  - bcpowmod — Eleva um número de precisão arbitrária para outro, reduzido por um módulo especificado
  - bcround — Arredonda número de precisão arbitrária
  - bcscale — Configura ou obtêm o parâmetro escala para todas as funções bc
  - bcsqrt — Obtém a raiz quadrada de um número de precisão arbitrária
  - bcsub — Subtrai um número de precisão arbitrária de outro
- BcMath\Number — A classe BcMath\Number
  - BcMath\Number::add — Adiciona um número de precisão arbitrária
  - BcMath\Number::ceil — Arredonda para cima um número de precisão arbitrária
  - BcMath\Number::compare — Compara dois números de precisão arbitrária
  - BcMath\Number::__construct — Cria um objeto BcMath\Number
  - BcMath\Number::div — Divide por um número de precisão arbitrária
  - BcMath\Number::divmod — Obtém quociente e resto de um número de precisão arbitrária
  - BcMath\Number::floor — Arredonda para baixo um número de precisão arbitrária
  - BcMath\Number::mod — Obtém o resto de um número de precisão arbitrária
  - BcMath\Number::mul — Multiplica um número de precisão arbitrária
  - BcMath\Number::pow — Eleva um número de precisão arbitrária
  - BcMath\Number::powmod — Eleva um número de precisão arbitrária, reduzido por um módulo especificado
  - BcMath\Number::round — Arredonda um número de precisão arbitrária
  - BcMath\Number::__serialize — Serializa um objeto BcMath\Number
  - BcMath\Number::sqrt — Obtém a raiz quadrada de um número de precisão arbitrária
  - BcMath\Number::sub — Subtrai um número de precisão arbitrária
  - BcMath\Number::__toString — Converte BcMath\Number em uma string
  - BcMath\Number::__unserialize — Desserializa um parâmetro de dados em um objeto BcMath\Number

# Precisão Múltipla GNU

# Introdução

Estas funções permitem que inteiros de comprimento arbitrário sejam trabalhados usando a biblioteca GNU MP.

> Nota:

> A maioria das funções GMP aceitam números GMP como argumentos. Estes são mostrados nesta documentação como objetos GMP. A maioria destas funções também aceitam argumentos númericos e strings, desde que seja possível converter a string para um número. Também, caso houver uma função com melhor desempenho que possa operar nos argumentos (inteiros somente), ela será usada (isso é feito de forma transparente). Consulte também a função gmp_init().

> Nota:

> Os operadores aritméticos, binários e comparativos podem ser usados com objetos GMP retornados de gmp_init() e de outras funções GMP.

Aviso

Inteiros grandes devem ser especificados como strings - caso contrário, o PHP irá convertê-los à força para o tipo float, resultando em perda de precisão.

# Instalação/Configuração

## Índice

- Dependências
- Instalação

## Dependências

A biblioteca GMP pode ser obtida em » http://gmplib.org/#DOWNLOAD. Essa página também disponibiliza o manual do GMP.

Pelo menos a versão 4.2 do GMP é requerida, com algumas funções requerendo uma versão mais recente da biblioteca GMP.

No Windows, MPIR é requerida ao invés da GMP.

## Instalação

Para ter estas funções disponíveis, o PHP deve ser compilado com suporte a GMP usando a opção de configuração --with-gmp.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`GMP_ROUND_ZERO` (int)
`GMP_ROUND_PLUSINF` (int)
`GMP_ROUND_MINUSINF` (int)
`GMP_MSW_FIRST` (int)
`GMP_LSW_FIRST` (int)
`GMP_LITTLE_ENDIAN` (int)
`GMP_BIG_ENDIAN` (int)
`GMP_NATIVE_ENDIAN` (int)
`GMP_VERSION` (string)
  A versão da biblioteca GMP.
`GMP_MPIR_VERSION` (string)
  A versão da biblioteca MPIR.

# Exemplos

Exemplo #1 Função fatorial usando GMP

    <?php
    function fact($x)
    {
        $return = 1;
        for ($i=2; $i <= $x; $i++) {
            $return = gmp_mul($return, $i);
        }
        return $return;
    }

    echo gmp_strval(fact(1000)) . "\n";
    ?>

Este código irá calcular o fatorial de 1000 (um número grande) de forma muito rápida.

# Funções GMP

## Veja Também

Mais funções matemáticas podem ser encontradas na seção Extensões Matemáticas

# gmp_abs

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_abs — Valor absoluto

### Descrição

function gmp_abs(GMP|int|string `$num`): GMP

Obtém o valor absoluto de um número.

### Parâmetros

`num`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

Retorna o valor absoluto de `num`, como um número GMP.

### Exemplos

Exemplo #1 Exemplo de gmp_abs()

    <?php
    $abs1 = gmp_abs("274982683358");
    $abs2 = gmp_abs("-274982683358");

    echo gmp_strval($abs1) . "\n";
    echo gmp_strval($abs2) . "\n";
    ?>

O exemplo acima produzirá:

    274982683358
    274982683358

# gmp_add

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_add — Adiciona números

### Descrição

function gmp_add(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Adiciona dois números.

### Parâmetros

`num1`
  A primeira parcela. Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`num2`

  A segunda parcela.

  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

Um número GMP representado a soma dos argumentos.

### Exemplos

Exemplo #1 Exemplo de gmp_add()

    <?php
    $sum = gmp_add("123456789012345", "76543210987655");
    echo gmp_strval($sum) . "\n";
    ?>

O exemplo acima produzirá:

    200000000000000

# gmp_and

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_and — Operação binária AND

### Descrição

function gmp_and(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Faz a operação binária AND de dois números GMP.

### Parâmetros

`num1`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`num2`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

Um número GMP representando a comparação binária `AND`.

### Exemplos

Exemplo #1 Exemplo de gmp_and()

    <?php
    $and1 = gmp_and("0xfffffffff4", "0x4");
    $and2 = gmp_and("0xfffffffff4", "0x8");
    echo gmp_strval($and1) . "\n";
    echo gmp_strval($and2) . "\n";
    ?>

O exemplo acima produzirá:

    4
    0

# gmp_binomial

(PHP 7 >= 7.3.0, PHP 8)

gmp_binomial — Calcula o coeficiente binomial

### Descrição

function gmp_binomial(GMP|int|string `$n`, int `$k`): GMP

Calcula o coeficiente binomial C(n, k).

### Parâmetros

`n`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`k`

### Valor Retornado

Retorna o coeficiente binomial C(n, k).

### Erros/Exceções

Lança um ValueError se `k` for negativo. Antes do PHP 8.0.0, `E_WARNING` era emitido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Esta função não mais retorna `false` em caso de falha.

# gmp_clrbit

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_clrbit — Limpa um bit

### Descrição

function gmp_clrbit(GMP `$num`, int `$index`): void

Limpa (define para 0) o bit na posição `index` no número informado em `num`. O índice começa em 0.

### Parâmetros

`num`

  Um objeto GMP.

`index`

  O índice do bit a ser zerado. Índice 0 representa o bit menos significativo.

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de gmp_clrbit()

    <?php
    $a = gmp_init("0xff");
    gmp_clrbit($a, 0); // índice inicia em 0, o bit menos significativo
    echo gmp_strval($a) . "\n";
    ?>

O exemplo acima produzirá:

    254

### Notas

> Nota:

> Diferentemente de outras funções GMP, gmp_clrbit() precisa ser chamada com um objeto GMP já existente (usando gmp_init() por exemplo). Ele não será automaticamente criado.

### Veja Também

- gmp_setbit() - Define um bit
- gmp_testbit() - Testa se um bit está definido

# gmp_cmp

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_cmp — Compara números

### Descrição

function gmp_cmp(GMP|int|string `$num1`, GMP|int|string `$num2`): int

Compara dois números.

### Parâmetros

`num1`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`num2`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

Retorna um valor positivo se `a > b`, zero se `a = b` e um valor negativo se `a < b`.

### Exemplos

Exemplo #1 Exemplo de gmp_cmp()

    <?php
    $cmp1 = gmp_cmp("1234", "1000"); // maior que
    $cmp2 = gmp_cmp("1000", "1234"); // menor que
    $cmp3 = gmp_cmp("1234", "1234"); // igual a

    echo "$cmp1 $cmp2 $cmp3\n";
    ?>

O exemplo acima produzirá:

    1 -1 0

# gmp_com

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_com — Calcula o complemento de um

### Descrição

function gmp_com(GMP|int|string `$num`): GMP

Retorna o complemento de um do valor `num`.

### Parâmetros

`num`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

Retorna o complemento de um do valor `num`, como um número GMP.

### Exemplos

Exemplo #1 Exemplo gmp_com()

    <?php
    $com = gmp_com("1234");
    echo gmp_strval($com) . "\n";
    ?>

O exemplo acima produzirá:

    -1235

# gmp_div

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div — Sinônimo de gmp_div_q()

### Descrição

Esta função é um apelido para: gmp_div_q().

# gmp_div_q

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div_q — Divide números

### Descrição

function gmp_div_q(GMP|int|string `$num1`, GMP|int|string `$num2`, int `$rounding_mode` = `GMP_ROUND_ZERO`): GMP

Divide `num1` por `num2` e retorna o resultado inteiro.

### Parâmetros

`num1`

  O número a ser dividido.

  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`num2`

  O número pelo qual `num1` será dividido.

  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`rounding_mode`

  O arredondamento do resultado é definido por `rounding_mode`, que pode ter os seguintes valores:

  - `GMP_ROUND_ZERO`: O resultado é truncado em direção a 0.
  - `GMP_ROUND_PLUSINF`: O resultado é arredondado em direção a `+infinito`.
  - `GMP_ROUND_MINUSINF`: O resultado é arredondado em direção a `-infinito`.
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

Um objeto GMP.

### Exemplos

Exemplo #1 Exemplo de gmp_div_q()

    <?php
    $div1 = gmp_div_q("100", "5");
    echo gmp_strval($div1) . "\n";

    $div2 = gmp_div_q("1", "3");
    echo gmp_strval($div2) . "\n";

    $div3 = gmp_div_q("1", "3", GMP_ROUND_PLUSINF);
    echo gmp_strval($div3) . "\n";

    $div4 = gmp_div_q("-1", "4", GMP_ROUND_PLUSINF);
    echo gmp_strval($div4) . "\n";

    $div5 = gmp_div_q("-1", "4", GMP_ROUND_MINUSINF);
    echo gmp_strval($div5) . "\n";
    ?>

O exemplo acima produzirá:

    20
    0
    1
    0
    -1

### Notas

> Nota:

> Esta função pode também ser chamada como gmp_div().

### Veja Também

- gmp_div_r() - Resto da divisão de dois números
- gmp_div_qr() - Divide números e obtém quociente e resto

# gmp_div_qr

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div_qr — Divide números e obtém quociente e resto

### Descrição

function gmp_div_qr(GMP|int|string `$num1`, GMP|int|string `$num2`, int `$rounding_mode` = `GMP_ROUND_ZERO`): array

A função divide `num1` por `num2`.

### Parâmetros

`num1`

  O número a ser dividido.

  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`num2`

  O número pelo qual `num1` será dividido.

  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`rounding_mode`

  Consulte a função gmp_div_q() para uma descrição do argumento `rounding_mode`.

### Valor Retornado

Retorna um array, com o primeiro elemento sendo `[n/d]` (o resultado inteiro da divisão) e o segundo sendo `(n - [n/d] * d)` (o resto da divisão).

### Exemplos

Exemplo #1 Divisão de números GMP

    <?php
    $a = gmp_init("0x41682179fbf5");
    $res = gmp_div_qr($a, "0xDEFE75");
    printf("Result is: q - %s, r - %s",
         gmp_strval ($res[0]), gmp_strval ($res[1]));
    ?>

### Veja Também

- gmp_div_q() - Divide números
- gmp_div_r() - Resto da divisão de dois números

# gmp_div_r

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div_r — Resto da divisão de dois números

### Descrição

function gmp_div_r(GMP|int|string `$num1`, GMP|int|string `$num2`, int `$rounding_mode` = `GMP_ROUND_ZERO`): GMP

Calcula o resto da divisão inteira de `num1` por `num2`. O resto tem o sinal do argumento `num1`, se não for zero.

### Parâmetros

`num1`

  O número a ser dividido.

  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`num2`

  O número pelo qual `num1` será dividido.

  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`rounding_mode`

  Consulte a função gmp_div_q() para descrição do argumento `rounding_mode`.

### Valor Retornado

O resto, como um número GMP.

### Exemplos

Exemplo #1 Exemplo de gmp_div_r()

    <?php
    $div = gmp_div_r("105", "20");
    echo gmp_strval($div) . "\n";
    ?>

O exemplo acima produzirá:

    5

### Veja Também

- gmp_div_q() - Divide números
- gmp_div_qr() - Divide números e obtém quociente e resto

# gmp_divexact

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_divexact — Divisão exata de números

### Descrição

function gmp_divexact(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Divide `num1` por `num2`, usando um algoritimo rápido de "divisão exata". Esta função produz resultados corretos apenas quando sabe anteriormente que `num2` é divisor de `num1`.

### Parâmetros

`num1`

  O número a ser dividido.

  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`num2`

  O número pelo qual `num1` será dividido.

  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

Um objeto GMP.

### Exemplos

Exemplo #1 Exemplo gmp_divexact()

    <?php
    $div1 = gmp_divexact("10", "2");
    echo gmp_strval($div1) . "\n";

    $div2 = gmp_divexact("10", "3"); // resultado errado
    echo gmp_strval($div2) . "\n";
    ?>

O exemplo acima produzirá:

    5
    2863311534

# gmp_export

(PHP 5 >= 5.6.1, PHP 7, PHP 8)

gmp_export — Exporta para uma string binária

### Descrição

function gmp_export(GMP|int|string `$num`, int `$word_size` = 1, int `$flags` = GMP_MSW_FIRST | GMP_NATIVE_ENDIAN): string

Exporta um número GMP para uma string binária.

### Parâmetros

`num`

  O número GMP que está sendo exportado.

`word_size`

  O valor padrão é 1. O número de bytes em cada bloco de dados binários. Isso é usado principalmente em conjunto com o parâmetro options.

`flags`

  O valor padrão é `GMP_MSW_FIRST` | `GMP_NATIVE_ENDIAN`.

### Valor Retornado

Retorna uma string.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Esta função não mais retorna `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de gmp_export()

    <?php
    $number = gmp_init(16705);
    echo gmp_export($number) . "\n";
    ?>

O exemplo acima produzirá:

    AA

### Veja Também

- gmp_import() - Importa de uma string binária

# gmp_fact

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_fact — Fatorial

### Descrição

function gmp_fact(GMP|int|string `$num`): GMP

Calcula o fatorial (`num!`) de `num`.

### Parâmetros

`num`

  O número fatorial.

  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

Um objeto GMP.

### Exemplos

Exemplo #1 Exemplo de gmp_fact()

    <?php
    $fact1 = gmp_fact(5); // 5 * 4 * 3 * 2 * 1
    echo gmp_strval($fact1) . "\n";

    $fact2 = gmp_fact(50); // 50 * 49 * 48, ... etc
    echo gmp_strval($fact2) . "\n";
    ?>

O exemplo acima produzirá:

    120
    30414093201713378043612608166064768844377641568960512000000000000

# gmp_gcd

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_gcd — Calcula o MDC

### Descrição

function gmp_gcd(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Calcula o máximo divisor comum de `num1` e `num2`. O resultado é sempre positivo, mesmo que um ou ambos os argumentos sejam negativos.

### Parâmetros

`num1`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`num2`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

Um número positivo GMP divisor de `num1` e `num2`.

### Exemplos

Exemplo #1 Exemplo de gmp_gcd()

    <?php
    $gcd = gmp_gcd("12", "21");
    echo gmp_strval($gcd) . "\n";
    ?>

O exemplo acima produzirá:

    3

### Veja Também

- gmp_lcm() - Calcula o MMC

# gmp_gcdext

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_gcdext — Calcula MDC e multiplicadores

### Descrição

function gmp_gcdext(GMP|int|string `$num1`, GMP|int|string `$num2`): array

Calcula g, s, e t, de forma que `a*s + b*t = g = gcd(a,b)`, onde gcd é o máximo divisor comum (MDC). Retorna um array com os respectivos elementos g, s e t.

Esta função pode ser usada para resolver equações lineares de Diophantine com duas variáveis. São equações que permitem somente soluções com inteiros e têm a forma: `a*x + b*y = c`. Para mais informações, acesse a página » "Equação de Diophantine" (em inglês) na MathWorld.

### Parâmetros

`num1`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`num2`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

Um array de números GMP.

### Exemplos

Exemplo #1 Resolvendo uma equação linear de Diophantine

    <?php
    // Soluciona a equação a*s + b*t = g
    // onde a = 12, b = 21, g = MDC(12, 21) = 3
    $a = gmp_init(12);
    $b = gmp_init(21);
    $g = gmp_gcd($a, $b);
    $r = gmp_gcdext($a, $b);

    $check_gcd = (gmp_strval($g) == gmp_strval($r['g']));
    $eq_res = gmp_add(gmp_mul($a, $r['s']), gmp_mul($b, $r['t']));
    $check_res = (gmp_strval($g) == gmp_strval($eq_res));

    if ($check_gcd && $check_res) {
        $fmt = "Solução: %d*%d + %d*%d = %d\n";
        printf($fmt, gmp_strval($a), gmp_strval($r['s']), gmp_strval($b),
        gmp_strval($r['t']), gmp_strval($r['g']));
    } else {
        echo "Erro ao solucionar a equação\n";
    }

    // saída: Solução: 12*2 + 21*-1 = 3
    ?>

# gmp_hamdist

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_hamdist — Distância de Hamming

### Descrição

function gmp_hamdist(GMP|int|string `$num1`, GMP|int|string `$num2`): int

Retorna a distância de Hamming entre `num1` e `num2`. Ambos argumentos devem ser positivos.

### Parâmetros

`num1`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

  Tem que ser positivo.

`num2`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

  Tem que ser positivo.

### Valor Retornado

A distância de Hamming entre `num1` e `num2`, do tipo int.

### Exemplos

Exemplo #1 Exemplo de gmp_hamdist()

    <?php
    $ham1 = gmp_init("1001010011", 2);
    $ham2 = gmp_init("1011111100", 2);
    echo gmp_hamdist($ham1, $ham2) . "\n";

    /* a distância de Hamming é equivalente a : */
    echo gmp_popcount(gmp_xor($ham1, $ham2)) . "\n";
    ?>

O exemplo acima produzirá:

    6
    6

### Veja Também

- gmp_popcount() - Contagem de população
- gmp_xor() - Operação binária XOR

# gmp_import

(PHP 5 >= 5.6.1, PHP 7, PHP 8)

gmp_import — Importa de uma string binária

### Descrição

function gmp_import(string `$data`, int `$word_size` = 1, int `$flags` = GMP_MSW_FIRST | GMP_NATIVE_ENDIAN): GMP

Importa um número GMP de uma string binária.

### Parâmetros

`data`

  A string binária que está sendo importada

`word_size`

  O valor padrão é 1. O número de bytes em cada bloco de dados binários. Isso é usado principalmente em conjunto com o parâmetro options.

`flags`

  O valor padrão é `GMP_MSW_FIRST` | `GMP_NATIVE_ENDIAN`.

### Valor Retornado

Retorna um número GMP.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Esta função não mais retorna `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo de gmp_import()

    <?php
    $number = gmp_import("\0");
    echo gmp_strval($number) . "\n";

    $number = gmp_import("\0\1\2");
    echo gmp_strval($number) . "\n";
    ?>

O exemplo acima produzirá:

    0
    258

### Veja Também

- gmp_export() - Exporta para uma string binária

# gmp_init

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_init — Cria um número GMP

### Descrição

function gmp_init(int|string `$num`, int `$base` = 0): GMP

Cria um número GMP a partir de um inteiro ou uma string.

### Parâmetros

`num`
  Um inteiro ou uma string. A string pode representar um decimal, hexadecimal ou octal.
`base`
  A base a ser usada na conversão da representação em string. Uma base explícita pode estar entre `2` e `62`. Para bases até `36`, é indiferente usar maiúsculas ou minúsculas; as letras terão o mesmo valor. Para bases de `37` a `62`, letras maiúsculas representam a faixa de `10` a `35` e as minúsculas representam os valores de `36` a `61`. Se a `base` for `0`, a base real é determinada pelos caracteres que vêm na frente de `num`. Se os dois primeiros caracteres forem `0x` ou `0X`, a string é interpretada como um inteiro hexadecimal. Se os dois primeiros caracteres forem `0b` ou `0B`, a string é interpretada como um inteiro binário. Se os dois primeiros caracteres forem `0o` ou `0O`, a string é interpretada como um inteiro octal. Além disso, se o primeiro caractere for `0`, a string também é interpretada como um inteiro octal. Em todos os outros casos, a string é interpretada como um inteiro decimal.

### Valor Retornado

Um objeto GMP.

### Registro de Alterações

Versão | Descrição
--- | ---
8.1.0 | Suporte a prefixos octais explícitos `0o` e `0O` foi adicionado para strings do parâmetro `num`. A interpretação de tais prefixos quando `base` é `0` também foi adicionada.

### Exemplos

Exemplo #1 Criando um número GMP

    <?php
    $a = gmp_init (123456);
    $b = gmp_init ("0xFFFFDEBACDFEDF7200");
    ?>

### Notas

> Nota:

> Não é necessário chamar esta função para usar inteiros ou strings no lugar de números GMP nas funções GMP (como em gmp_add()). Argumentos das funções são automaticamente convertidos para números GMP, se esta conversão for possível e necessária, usando as mesmas regras de gmp_init().

### Veja Também

- GMP::__construct() - Cria um número GMP

# gmp_intval

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_intval — Converte um número GMP para um inteiro

### Descrição

function gmp_intval(GMP|int|string `$num`): int

Esta função converte um número GMP para um int nativo do PHP.

### Parâmetros

`num`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

Um valor int de `num`.

### Exemplos

Exemplo #1 Exemplo gmp_intval()

    <?php
    // Mostra o valor correto
    echo gmp_intval("2147483647") . "\n";

    // Mostra um resultado errado, acima do limite de inteiro do PHP
    echo gmp_intval("2147483648") . "\n";

    // mostra o valor correto
    echo gmp_strval("2147483648") . "\n";
    ?>

O exemplo acima produzirá:

    2147483647
    2147483647
    2147483648

### Notas

Aviso

Esta função retorna um resultado útil somente se o número realmente cabe em um inteiro PHP (isto é, tipo longo com sinal). Para simplesmente mostrar o número GMP, use gmp_strval().

# gmp_invert

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_invert — Inverso modular

### Descrição

function gmp_invert(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP|false

Computa o inverso de `num1` módulo `num2`.

### Parâmetros

`num1`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`num2`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

Um número GMP em caso de sucesso ou `false` se um inverso não existir.

### Exemplos

Exemplo #1 Exemplo de gmp_invert()

    <?php
    echo gmp_invert("5", "10"); // sem inverso, não mostra nada, resultado é FALSE
    $invert = gmp_invert("5", "11");
    echo gmp_strval($invert) . "\n";
    ?>

O exemplo acima produzirá:

    9

# gmp_jacobi

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_jacobi — Símbolo de Jacobi

### Descrição

function gmp_jacobi(GMP|int|string `$num1`, GMP|int|string `$num2`): int

Computa o » Símbolo de Jacobi de `num1` e `num2`. `num2` deve ser ímpar e positivo.

### Parâmetros

`num1`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`num2`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

  Deve ser ímpar e positivo.

### Valor Retornado

Um objeto GMP.

### Exemplos

Exemplo #1 Exemplo de gmp_jacobi()

    <?php
    echo gmp_jacobi("1", "3") . "\n";
    echo gmp_jacobi("2", "3") . "\n";
    ?>

O exemplo acima produzirá:

    1
    0

### Veja Também

- gmp_kronecker() - Símbolo de Kronecker
- gmp_legendre() - Símbolo de Legendre

# gmp_kronecker

(PHP 7 >= 7.3.0, PHP 8)

gmp_kronecker — Símbolo de Kronecker

### Descrição

function gmp_kronecker(GMP|int|string `$num1`, GMP|int|string `$num2`): int

Esta função computa o símbolo de Kronecker de `num1` e `num2`.

### Parâmetros

`num1`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`num2`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

Retorna o símbolo de Kronecker de `num1` e `num2`.

### Veja Também

- gmp_jacobi() - Símbolo de Jacobi
- gmp_legendre() - Símbolo de Legendre

# gmp_lcm

(PHP 7 >= 7.3.0, PHP 8)

gmp_lcm — Calcula o MMC

### Descrição

function gmp_lcm(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Esta função computa o mínimo múltiplo comum (MMC) de `num1` e `num2`.

### Parâmetros

`num1`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`num2`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

Um objeto GMP.

### Veja Também

- gmp_gcd() - Calcula o MDC

# gmp_legendre

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_legendre — Símbolo de Legendre

### Descrição

function gmp_legendre(GMP|int|string `$num1`, GMP|int|string `$num2`): int

Computa o » Símbolo de Legendre de `num1` e `num2`. `num2` deve ser ímpar e positivo.

### Parâmetros

`num1`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`num2`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

  Precisa ser ímpar e positivo.

### Valor Retornado

Um objeto GMP.

### Exemplos

Exemplo #1 Exemplo da gmp_legendre()

    <?php
    echo gmp_legendre("1", "3") . "\n";
    echo gmp_legendre("2", "3") . "\n";
    ?>

O exemplo acima produzirá:

    1
    0

### Veja Também

- gmp_jacobi() - Símbolo de Jacobi
- gmp_kronecker() - Símbolo de Kronecker

# gmp_mod

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_mod — Operação Módulo

### Descrição

function gmp_mod(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Calcula o resto da divisão de `num1` por `num2`. O resultado é sempre não-negativo, o sinal de `num2` é ignorado.

### Parâmetros

`num1`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`num2`

  O resto da divisão (módulo) que será calculado.

  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

Um objeto GMP.

### Exemplos

Exemplo #1 Exemplo de gmp_mod()

    <?php
    $mod = gmp_mod("8", "3");
    echo gmp_strval($mod) . "\n";
    ?>

O exemplo acima produzirá:

    2

# gmp_mul

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_mul — Multiplica números

### Descrição

function gmp_mul(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Multiplica `num1` por `num2` e retorna o resultado.

### Parâmetros

`num1`

  Um número que será multiplicado por `num2`.

  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`num2`

  Um número que será multiplicado por `num1`.

  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

Um objeto GMP.

### Exemplos

Exemplo #1 Exemplo da gmp_mul()

    <?php
    $mul = gmp_mul("12345678", "2000");
    echo gmp_strval($mul) . "\n";
    ?>

O exemplo acima produzirá:

    24691356000

# gmp_neg

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_neg — Negativa o número

### Descrição

function gmp_neg(GMP|int|string `$num`): GMP

Retorna o valor negativo de um número.

### Parâmetros

`num`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

Retorna -`num`, como um número GMP.

### Exemplos

Exemplo #1 Exemplo de gmp_neg()

    <?php
    $neg1 = gmp_neg("1");
    echo gmp_strval($neg1) . "\n";
    $neg2 = gmp_neg("-1");
    echo gmp_strval($neg2) . "\n";
    ?>

O exemplo acima produzirá:

    -1
    1

# gmp_nextprime

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

gmp_nextprime — Encontra o próximo número primo

### Descrição

function gmp_nextprime(GMP|int|string `$num`): GMP

Encontra o próximo número primo

### Parâmetros

`num`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

Retorna o próximo número primo maior que `num`, como um número GMP.

### Exemplos

Exemplo #1 Exemplo de gmp_nextprime()

    <?php
    $prime1 = gmp_nextprime(10); // o próximo número primo maior que 10
    $prime2 = gmp_nextprime(-1000); // o próximo número primo maior que -1000

    echo gmp_strval($prime1) . "\n";
    echo gmp_strval($prime2) . "\n";
    ?>

O exemplo acima produzirá:

    11
    2

### Notas

> Nota:

> Esta função usa um algoritmo probabilístico para identificar primos e as chances de se obter um número composto é extremamente pequena.

# gmp_or

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_or — Operação binária OR

### Descrição

function gmp_or(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Faz a operação binária inclusiva OR de dois números GMP.

### Parâmetros

`num1`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`num2`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

Um objeto GMP.

### Exemplos

Exemplo #1 Exemplo de gmp_or()

    <?php
    $or1 = gmp_or("0xfffffff2", "4");
    echo gmp_strval($or1, 16) . "\n";
    $or2 = gmp_or("0xfffffff2", "2");
    echo gmp_strval($or2, 16) . "\n";
    ?>

O exemplo acima produzirá:

    fffffff6
    fffffff2

# gmp_perfect_power

(PHP 7 >= 7.3.0, PHP 8)

gmp_perfect_power — Verificação de potência perfeita

### Descrição

function gmp_perfect_power(GMP|int|string `$num`): bool

Verifica se `num` é uma potência perfeita.

### Parâmetros

`num`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

Retorna `true` se `num` for uma potência perfeita, `false` caso contrário.

### Veja Também

- gmp_perfect_square() - Verificação de quadrado perfeito

# gmp_perfect_square

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_perfect_square — Verificação de quadrado perfeito

### Descrição

function gmp_perfect_square(GMP|int|string `$num`): bool

Verifica se um número é um quadrado perfeito.

### Parâmetros

`num`

  O número a ser verificado como um quadrado perfeito.

  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

Retorna `true` se `num` for um quadrado perfeito, `false` caso contrário.

### Exemplos

Exemplo #1 Exemplo de gmp_perfect_square()

    <?php
    // 3 * 3, quadrado perfeito
    var_dump(gmp_perfect_square("9"));

    // não é um quadrado perfeito
    var_dump(gmp_perfect_square("7"));

    // 1234567890 * 1234567890, quadrado perfeito
    var_dump(gmp_perfect_square("1524157875019052100"));
    ?>

O exemplo acima produzirá:

    bool(true)
    bool(false)
    bool(true)

### Veja Também

- gmp_perfect_power() - Verificação de potência perfeita
- gmp_sqrt() - Calcula a raiz quadrada
- gmp_sqrtrem() - Raiz quadrada com resto

# gmp_popcount

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_popcount — Contagem de população

### Descrição

function gmp_popcount(GMP|int|string `$num`): int

Obtém a contagem de população.

### Parâmetros

`num`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

A contagem de população de `num`, como um int.

### Exemplos

Exemplo #1 Exemplo de gmp_popcount()

    <?php
    $pop1 = gmp_init("10000101", 2); // 3 1's
    echo gmp_popcount($pop1) . "\n";
    $pop2 = gmp_init("11111110", 2); // 7 1's
    echo gmp_popcount($pop2) . "\n";
    ?>

O exemplo acima produzirá:

    3
    7

# gmp_pow

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_pow — Elevar o número a uma potência

### Descrição

function gmp_pow(GMP|int|string `$num`, int `$exponent`): GMP

Eleva `num` à potência `exponent`.

### Parâmetros

`num`

  O número da base.

  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`exponent`

  A potência positiva à qual `num` será elevado.

### Valor Retornado

O novo número (exponenciado), como um número GMP. O caso de `0^0` produz 1.

### Exemplos

Exemplo #1 Exemplo gmp_pow()

    <?php
    $pow1 = gmp_pow("2", 31);
    echo gmp_strval($pow1) . "\n";
    $pow2 = gmp_pow("0", 0);
    echo gmp_strval($pow2) . "\n";
    $pow3 = gmp_pow("2", -1); // Expoente negativo, gera um alerta
    echo gmp_strval($pow3) . "\n";
    ?>

O exemplo acima produzirá:

    2147483648
    1

# gmp_powm

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_powm — Eleva um número a uma potência com módulo

### Descrição

function gmp_powm(GMP|int|string `$num`, GMP|int|string `$exponent`, GMP|int|string `$modulus`): GMP

Calcula o resto da divisão de (`num` elevado à potência `exponent`) por `modulus`. Se `exponent` for negativo, o resultado é indefinido.

### Parâmetros

`num`

  O número da base.

  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`exponent`

  A potência positiva à qual `num` será elevado.

  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`modulus`

  O divisor para obtenção do resto (módulo).

  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

O novo número (exponenciado), como um número GMP.

### Exemplos

Exemplo #1 Exemplo de gmp_powm()

    <?php
    $pow1 = gmp_powm("2", "31", "2147483649");
    echo gmp_strval($pow1) . "\n";
    ?>

O exemplo acima produzirá:

    2147483648

# gmp_prob_prime

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_prob_prime — Verifica se o número é "provavelmente primo"

### Descrição

function gmp_prob_prime(GMP|int|string `$num`, int `$repetitions` = 10): int

A função usa o teste probabilístico de Miller-Rabin para verificar se um número é primo.

### Parâmetros

`num`

  O número a ser verificado como um primo.

  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`repetitions`

  Valores razoáveis de `repetitions` variam de 5 a 10 (o padrão é 10); um valor mais alto diminui a probabilidade de um não-primo passar como um "provável" primo.

  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

Se esta função retornar 0, `num` definitivamente não é primo. Se retornar 1, `num` é "provavelmente" primo. Se retornar 2, `num` com certeza é primo.

### Exemplos

Exemplo #1 Exemplo de gmp_prob_prime()

    <?php
    // definitivamente não é primo
    echo gmp_prob_prime("6") . "\n";

    // provavelmente um primo
    echo gmp_prob_prime("1111111111111111111") . "\n";

    // definitamente é primo
    echo gmp_prob_prime("11") . "\n";
    ?>

O exemplo acima produzirá:

    0
    1
    2

# gmp_random

(PHP 4 >= 4.0.4, PHP 5, PHP 7)

gmp_random — Número aleatório

Aviso

Esta função foi DESCONTINUADA a partir do PHP 7.2.0 e foi REMOVIDA a partir do PHP 8.0.0. O uso desta função é fortemente desencorajado.

### Descrição

function gmp_random(int `$limiter` = 20): GMP

Gera um número aleatório. O número será entre 0 e (2 ** n) - 1, onde n é o número de bits por membro multiplicado por `limiter`. Se `limiter` for negativo, são gerados números negativos.

Um membro é um mecanismo interno do GMP. O número de bits em um membro não é estatico, e pode variar de sistema para sistema. Geralmente, o número de bits em um membro é 32 ou 64, mas isto não é garantido.

Cuidado

Esta função não gera valores criptograficamente seguros e não deve ser usada para propósitos criptográficos ou fins que exijam que os valores retornados sejam impossíveis de adivinhar.

Se aleatoriedade criptograficamente segura for necessária, a classe Random\Randomizer pode ser usada com o mecanismo Random\Engine\Secure. Para casos de uso simples, as funções random_int() e random_bytes() fornecem uma API conveniente e segura que é garantida pelo CSPRNG do sistema operacional.

### Parâmetros

`limiter`

  O limitador.

  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

Um número GMP aleatório.

### Exemplos

Exemplo #1 Exemplo de gmp_random()

    <?php
    $rand1 = gmp_random(1); // número aleatório de 0 a 1 * bits por membro
    $rand2 = gmp_random(2); // número aleatório de 0 a 2 * bits por membro

    echo gmp_strval($rand1) . "\n";
    echo gmp_strval($rand2) . "\n";
    ?>

O exemplo acima produzirá:

    1915834968
    8642564075890328087

# gmp_random_bits

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

gmp_random_bits — Numero aleatório

### Descrição

function gmp_random_bits(int `$bits`): GMP

Gera um número aleatório. O número estará entre `0` e `2$bits - 1`.

`bits` precisa ser maior que 0, e o valor máximo é restrito pela memória disponível.

Cuidado

Esta função não gera valores criptograficamente seguros e não deve ser usada para propósitos criptográficos ou fins que exijam que os valores retornados sejam impossíveis de adivinhar.

Se aleatoriedade criptograficamente segura for necessária, a classe Random\Randomizer pode ser usada com o mecanismo Random\Engine\Secure. Para casos de uso simples, as funções random_int() e random_bytes() fornecem uma API conveniente e segura que é garantida pelo CSPRNG do sistema operacional.

### Parâmetros

`bits`

  O número de bits a gerar.

### Valor Retornado

Um número GMP aleatório.

### Erros/Exceções

Se `bits` for menor que `1`, uma exceção ValueError será lançada.

### Exemplos

Exemplo #1 Exemplo de gmp_random_bits()

    <?php
    $rand1 = gmp_random_bits(3); // número aleatório de 0 a 7
    $rand2 = gmp_random_bits(5); // número aleatório de 0 a 31

    echo gmp_strval($rand1) . "\n";
    echo gmp_strval($rand2) . "\n";
    ?>

O exemplo acima produzirá:

    3
    15

# gmp_random_range

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

gmp_random_range — Obtém um inteiro uniformemente selecionado

### Descrição

function gmp_random_range(GMP|int|string `$min`, GMP|int|string `$max`): GMP

Gera um número aleatório. O número estará entre `min` e `max`.

`min` e `max` podem ambos ser negativos mas `min` precisa sempre ser menor que `max`.

Cuidado

Esta função não gera valores criptograficamente seguros e não deve ser usada para propósitos criptográficos ou fins que exijam que os valores retornados sejam impossíveis de adivinhar.

Se aleatoriedade criptograficamente segura for necessária, a classe Random\Randomizer pode ser usada com o mecanismo Random\Engine\Secure. Para casos de uso simples, as funções random_int() e random_bytes() fornecem uma API conveniente e segura que é garantida pelo CSPRNG do sistema operacional.

### Parâmetros

`min`

  Um número GMP representando o limite inferior para o número aleatório.

`max`

  Um número GMP representando o limite superior para o número aleatório.

### Valor Retornado

Retorna um objeto GMP que contém um inteiro uniformemente selecionado do intervalo fechado [`min`, `max`]. Tanto `min` quanto `max` são valores de retorno possíveis.

### Erros/Exceções

Se `max` for menor que `min`, uma exceção ValueError será lançada.

### Exemplos

Exemplo #1 Exemplo de gmp_random_range()

    <?php
    $rand1 = gmp_random_range(0, 100);    // número aleatório entre 0 e 100
    $rand2 = gmp_random_range(-100, -10); // número aleatório entre -100 e -10

    echo gmp_strval($rand1) . "\n";
    echo gmp_strval($rand2) . "\n";
    ?>

O exemplo acima produzirá:

    42
    -67

# gmp_random_seed

(PHP 7, PHP 8)

gmp_random_seed — Define a semente do gerador de números aleatórios

### Descrição

function gmp_random_seed(GMP|int|string `$seed`): void

### Parâmetros

`seed`

  A semente a ser definida para as funções gmp_random(), gmp_random_bits() e gmp_random_range().

  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

Nenhum valor é retornado.

### Erros/Exceções

Lança uma exceção ValueError se o parâmetro `seed` for inválido.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | Se `seed` for inválido, gmp_random_seed() agora lança uma exceção ValueError. Anteriormente, emitia um `E_WARNING` e retornava `false`.

### Exemplos

Exemplo #1 Exemplo de gmp_random_seed()

    <?php
    // define a semente
    gmp_random_seed(100);

    var_dump(gmp_strval(gmp_random(1)));

    // define a semente para algo diferente
    gmp_random_seed(gmp_init(-100));

    var_dump(gmp_strval(gmp_random_bits(10)));

    // define a semente para algo inválido
    var_dump(gmp_random_seed('not a number'));

O exemplo acima produzirá:

    string(20) "15370156633245019617"
    string(3) "683"

    Warning: gmp_random_seed(): Unable to convert variable to GMP - string is not an integer in %s on line %d
    bool(false)

### Veja Também

- gmp_init() - Cria um número GMP
- gmp_random() - Número aleatório
- gmp_random_bits() - Numero aleatório
- gmp_random_range() - Obtém um inteiro uniformemente selecionado

# gmp_root

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

gmp_root — Obtém a parte inteira da raiz enésima

### Descrição

function gmp_root(GMP|int|string `$num`, int `$nth`): GMP

Obtém a raiz enésima (sendo n definido no parâmetro `nth`) do número informado em `num` e retorna o componente inteiro do resultado.

### Parâmetros

`num`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`nth`

  A raiz positiva para obter de `num`.

### Valor Retornado

O componente inteiro da raiz resultante, como um número GMP.

# gmp_rootrem

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

gmp_rootrem — Obtém a parte inteira e o resto da raiz enésima

### Descrição

function gmp_rootrem(GMP|int|string `$num`, int `$nth`): array

Obtém a raiz enésima (sendo n definido no parâmetro `nth`) do número informado em `num` e retorna o componente inteiro e o resto do resultado.

### Parâmetros

`num`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`nth`

  A raiz positiva para obter de `num`.

### Valor Retornado

Um array de dois elementos, onde o primeiro elemento é o componente inteiro da raiz e o segundo elemento é o resto, ambos representados como números GMP.

# gmp_scan0

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_scan0 — Procura por 0

### Descrição

function gmp_scan0(GMP|int|string `$num1`, int `$start`): int

Pesquisa `num1`, iniciando com o bit definido em `start`, no sentido dos bits mais significativos, até que o primeiro bit 0 seja encontrado.

### Parâmetros

`num1`

  O número a ser pesquisado.

  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`start`

  O bit inicial.

### Valor Retornado

Retorna a posição do bit encontrado, como um int. A primeira posição é 0.

### Exemplos

Exemplo #1 Exemplo de gmp_scan0()

    <?php
    // Bit "0" é encontrado na posição 3. A posição inicia em 0.
    $s1 = gmp_init("10111", 2);
    echo gmp_scan0($s1, 0) . "\n";

    // Bit "0" é encontrado na posição 7. A posição inicia em 5.
    $s2 = gmp_init("101110000", 2);
    echo gmp_scan0($s2, 5) . "\n";
    ?>

O exemplo acima produzirá:

    3
    7

# gmp_scan1

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_scan1 — Procura por 1

### Descrição

function gmp_scan1(GMP|int|string `$num1`, int `$start`): int

Pesquisa `num1`, iniciando com o bit definido em `start`, no sentido dos bits mais significativos, até que o primeiro bit 1 seja encontrado.

### Parâmetros

`num1`

  O número a ser pesquisado.

  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`start`

  O bit inicial.

### Valor Retornado

Retorna a posição do bit encontrado, como um int. A primeira posição é 0. Se nenhum bit 1 for encontrado, retorna -1.

### Exemplos

Exemplo #1 Exemplo de gmp_scan1()

    <?php
    // Bit "1" é encontrado na posição 3. A posição inicia em 0.
    $s1 = gmp_init("01000", 2);
    echo gmp_scan1($s1, 0) . "\n";

    // Bit "1" é encontrado na posição 9. A posição inicia em 5.
    $s2 = gmp_init("01000001111", 2);
    echo gmp_scan1($s2, 5) . "\n";
    ?>

O exemplo acima produzirá:

    3
    9

# gmp_setbit

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_setbit — Define um bit

### Descrição

function gmp_setbit(GMP `$num`, int `$index`, bool `$value` = `true`): void

Define para 1 o bit na posição `index` no número `num`.

### Parâmetros

`num`

  Um objeto GMP.

`index`

  A posição do bit a ser definido. Posição 0 representa o bit menos significativo.

`value`

  True para definir o bit (igual a 1 / ligado); false para limpar o bit (igual a 0 / desligado).

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo de gmp_setbit() - posição 0

    <?php
    $a = gmp_init("2"); //
    echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
    gmp_setbit($a, 0); // 0b10 agora se torna 0b11
    echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
    ?>

O exemplo acima produzirá:

    2 -> 0b10
    3 -> 0b11

Exemplo #2 Exemplo de gmp_setbit() - posição 1

    <?php
    $a = gmp_init("0xfd");
    echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
    gmp_setbit($a, 1); // posição inicia em 0
    echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
    ?>

O exemplo acima produzirá:

    253 -> 0b11111101
    255 -> 0b11111111

Exemplo #3 Exemplo de gmp_setbit() - limpando um bit

    <?php
    $a = gmp_init("0xff");
    echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
    gmp_setbit($a, 0, false); // limpa o bit na posição 0
    echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
    ?>

O exemplo acima produzirá:

    255 -> 0b11111111
    254 -> 0b11111110

### Notas

> Nota:

> Ao contrário da maioria das outras funções GMP, gmp_setbit() deve ser chamada com um objeto GMP que já exista (usando gmp_init() por exemplo). Um objeto não será criado automaticamente.

### Veja Também

- gmp_clrbit() - Limpa um bit
- gmp_testbit() - Testa se um bit está definido

# gmp_sign

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sign — Sinal do número

### Descrição

function gmp_sign(GMP|int|string `$num`): int

Verifica o sinal de um número.

### Parâmetros

`num`

  Pode ser um objeto GMP, ou uma string numérica desde que seja possível convertê-la para um int.

### Valor Retornado

Retorna 1 se `num` for positivo, -1 se `num` for negativo, e 0 se `num` for zero.

### Exemplos

Exemplo #1 Exemplo de gmp_sign()

    <?php
    // positivo
    echo gmp_sign("500") . "\n";

    // negativo
    echo gmp_sign("-500") . "\n";

    // zero
    echo gmp_sign("0") . "\n";
    ?>

O exemplo acima produzirá:

    1
    -1
    0

### Veja Também

- gmp_abs() - Valor absoluto
- abs() - Valor absoluto

# gmp_sqrt

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sqrt — Calcula a raiz quadrada

### Descrição

function gmp_sqrt(GMP|int|string `$num`): GMP

Calcula a raiz quadrada de `num`.

### Parâmetros

`num`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

A parte inteira da raiz quadrada, como um número GMP.

### Exemplos

Exemplo #1 Exemplo de gmp_sqrt()

    <?php
    $sqrt1 = gmp_sqrt("9");
    $sqrt2 = gmp_sqrt("7");
    $sqrt3 = gmp_sqrt("1524157875019052100");

    echo gmp_strval($sqrt1) . "\n";
    echo gmp_strval($sqrt2) . "\n";
    echo gmp_strval($sqrt3) . "\n";
    ?>

O exemplo acima produzirá:

    3
    2
    1234567890

# gmp_sqrtrem

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sqrtrem — Raiz quadrada com resto

### Descrição

function gmp_sqrtrem(GMP|int|string `$num`): array

Calcula a raiz quadrada de um número, com resto.

### Parâmetros

`num`

  O número do qual será calculada a raiz quadrada.

  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

Retorna um array onde o primeiro elemento é a raiz quadrada inteira de `num` e o segundo é o resto (isto é, a diferença entre `num` e o quadrado do primeiro elemento).

### Exemplos

Exemplo #1 Exemplo de gmp_sqrtrem()

    <?php
    list($sqrt1, $sqrt1rem) = gmp_sqrtrem("9");
    list($sqrt2, $sqrt2rem) = gmp_sqrtrem("7");
    list($sqrt3, $sqrt3rem) = gmp_sqrtrem("1048576");

    echo gmp_strval($sqrt1) . ", " . gmp_strval($sqrt1rem) . "\n";
    echo gmp_strval($sqrt2) . ", " . gmp_strval($sqrt2rem) . "\n";
    echo gmp_strval($sqrt3) . ", " . gmp_strval($sqrt3rem) . "\n";
    ?>

O exemplo acima produzirá:

    3, 0
    2, 3
    1024, 0

# gmp_strval

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_strval — Converte um número GMP para uma string

### Descrição

function gmp_strval(GMP|int|string `$num`, int `$base` = 10): string

Converte o número GMP para uma representação em string na base `base`. A base padrão é 10.

### Parâmetros

`num`

  O número GMP que será convertido para uma string.

  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`base`

  A base do número retornado. A base padrão é 10. Valores permitidos para base são de 2 à 62 e -2 a -36.

### Valor Retornado

O número, como uma string.

### Exemplos

Exemplo #1 Convertendo um número GMP para uma string

    <?php
    $a = gmp_init("0x41682179fbf5");
    printf("Decimal: %s, 36-based: %s", gmp_strval($a), gmp_strval($a,36));
    ?>

# gmp_sub

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sub — Subtrai números

### Descrição

function gmp_sub(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Subtrai `num2` de `num1` e retorna o resultado.

### Parâmetros

`num1`

  O minuendo.

  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`num2`

  O subtraendo, que será subtraído de `num1`.

  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

Um objeto GMP.

### Exemplos

Exemplo #1 Exemplo da gmp_sub()

    <?php
    $sub = gmp_sub("281474976710656", "4294967296"); // 2^48 - 2^32
    echo gmp_strval($sub) . "\n";
    ?>

O exemplo acima produzirá:

    281470681743360

# gmp_testbit

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gmp_testbit — Testa se um bit está definido

### Descrição

function gmp_testbit(GMP|int|string `$num`, int `$index`): bool

Teste se o bit especificado está definido.

### Parâmetros

`num`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`index`

  O bit a ser testado.

### Valor Retornado

Retorna `true` se o bit estiver definido em `num`, caso contrário, `false`.

### Erros/Exceções

Um erro de nível `E_WARNING` será emitido quando `index` for menor que zero, e `false` será retornado.

### Exemplos

Exemplo #1 Exemplo de gmp_testbit()

    <?php
    $n = gmp_init("1000000");
    var_dump(gmp_testbit($n, 1));
    gmp_setbit($n, 1);
    var_dump(gmp_testbit($n, 1));
    ?>

O exemplo acima produzirá:

    bool(false)
    bool(true)

### Veja Também

- gmp_setbit() - Define um bit
- gmp_clrbit() - Limpa um bit

# gmp_xor

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_xor — Operação binária XOR

### Descrição

function gmp_xor(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Faz a operação binária exclusiva OR (XOR) de dois números GMP.

### Parâmetros

`num1`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).
`num2`
  Um objeto GMP, um int ou uma string que possa ser interpretado como um número seguindo a mesma lógica como se a string fosse usada em gmp_init() com detecção automática de base (ou seja, quando `base` é igual a 0).

### Valor Retornado

Um objeto GMP.

### Exemplos

Exemplo #1 Exemplo de gmp_xor()

    <?php
    $xor1 = gmp_init("1101101110011101", 2);
    $xor2 = gmp_init("0110011001011001", 2);

    $xor3 = gmp_xor($xor1, $xor2);

    echo gmp_strval($xor3, 2) . "\n";
    ?>

O exemplo acima produzirá:

    1011110111000100

## Índice

- gmp_abs — Valor absoluto
- gmp_add — Adiciona números
- gmp_and — Operação binária AND
- gmp_binomial — Calcula o coeficiente binomial
- gmp_clrbit — Limpa um bit
- gmp_cmp — Compara números
- gmp_com — Calcula o complemento de um
- gmp_div — Sinônimo de gmp_div_q
- gmp_div_q — Divide números
- gmp_div_qr — Divide números e obtém quociente e resto
- gmp_div_r — Resto da divisão de dois números
- gmp_divexact — Divisão exata de números
- gmp_export — Exporta para uma string binária
- gmp_fact — Fatorial
- gmp_gcd — Calcula o MDC
- gmp_gcdext — Calcula MDC e multiplicadores
- gmp_hamdist — Distância de Hamming
- gmp_import — Importa de uma string binária
- gmp_init — Cria um número GMP
- gmp_intval — Converte um número GMP para um inteiro
- gmp_invert — Inverso modular
- gmp_jacobi — Símbolo de Jacobi
- gmp_kronecker — Símbolo de Kronecker
- gmp_lcm — Calcula o MMC
- gmp_legendre — Símbolo de Legendre
- gmp_mod — Operação Módulo
- gmp_mul — Multiplica números
- gmp_neg — Negativa o número
- gmp_nextprime — Encontra o próximo número primo
- gmp_or — Operação binária OR
- gmp_perfect_power — Verificação de potência perfeita
- gmp_perfect_square — Verificação de quadrado perfeito
- gmp_popcount — Contagem de população
- gmp_pow — Elevar o número a uma potência
- gmp_powm — Eleva um número a uma potência com módulo
- gmp_prob_prime — Verifica se o número é "provavelmente primo"
- gmp_random — Número aleatório
- gmp_random_bits — Numero aleatório
- gmp_random_range — Obtém um inteiro uniformemente selecionado
- gmp_random_seed — Define a semente do gerador de números aleatórios
- gmp_root — Obtém a parte inteira da raiz enésima
- gmp_rootrem — Obtém a parte inteira e o resto da raiz enésima
- gmp_scan0 — Procura por 0
- gmp_scan1 — Procura por 1
- gmp_setbit — Define um bit
- gmp_sign — Sinal do número
- gmp_sqrt — Calcula a raiz quadrada
- gmp_sqrtrem — Raiz quadrada com resto
- gmp_strval — Converte um número GMP para uma string
- gmp_sub — Subtrai números
- gmp_testbit — Testa se um bit está definido
- gmp_xor — Operação binária XOR

# A classe GMP

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

## Introdução

Representa um número GMP. Este objeto suporta sobrecarga dos operadores aritméticos, binários e comparativos.

> Nota:

> Nenhuma interface orientada a objeto é provida para manipular objetos GMP. Para isto, favor usar a API GMP procedural.

## Resumo da classe

final class GMP {
/* Métodos */
public function __construct(int|string `$num` = 0, int `$base` = 0)
public function __serialize(): array
public function __unserialize(array `$data`): void
}

## Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | GMP agora é marcada como final.

# GMP::__construct

(PHP 8 >= 8.2.4)

GMP::__construct — Cria um número GMP

### Descrição

public function GMP::__construct(int|string `$num` = 0, int `$base` = 0)

Cria um número GMP a partir de um inteiro ou de uma string.

### Parâmetros

`num`
  Um inteiro ou uma string. A string pode representar um decimal, hexadecimal ou octal.
`base`
  A base a ser usada na conversão da representação em string. Uma base explícita pode estar entre `2` e `62`. Para bases até `36`, é indiferente usar maiúsculas ou minúsculas; as letras terão o mesmo valor. Para bases de `37` a `62`, letras maiúsculas representam a faixa de `10` a `35` e as minúsculas representam os valores de `36` a `61`. Se a `base` for `0`, a base real é determinada pelos caracteres que vêm na frente de `num`. Se os dois primeiros caracteres forem `0x` ou `0X`, a string é interpretada como um inteiro hexadecimal. Se os dois primeiros caracteres forem `0b` ou `0B`, a string é interpretada como um inteiro binário. Se os dois primeiros caracteres forem `0o` ou `0O`, a string é interpretada como um inteiro octal. Além disso, se o primeiro caractere for `0`, a string também é interpretada como um inteiro octal. Em todos os outros casos, a string é interpretada como um inteiro decimal.

### Veja Também

- gmp_init() - Cria um número GMP

# GMP::__serialize

(PHP 8 >= 8.1.0)

GMP::__serialize — Serializa o objeto GMP

### Descrição

public function GMP::__serialize(): array

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

# GMP::__unserialize

(PHP 8 >= 8.1.0)

GMP::__unserialize — Desserializa o parâmetro `data` em um objeto GMP

### Descrição

public function GMP::__unserialize(array `$data`): void

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`data`

  O valor a ser desserializado.

### Valor Retornado

Nenhum valor é retornado.

## Índice

- GMP::__construct — Cria um número GMP
- GMP::__serialize — Serializa o objeto GMP
- GMP::__unserialize — Desserializa o parâmetro data em um objeto GMP

- Instalação/Configuração
  - Dependências
  - Instalação
- Constantes predefinidas
- Exemplos
- Funções GMP
  - gmp_abs — Valor absoluto
  - gmp_add — Adiciona números
  - gmp_and — Operação binária AND
  - gmp_binomial — Calcula o coeficiente binomial
  - gmp_clrbit — Limpa um bit
  - gmp_cmp — Compara números
  - gmp_com — Calcula o complemento de um
  - gmp_div — Sinônimo de gmp_div_q
  - gmp_div_q — Divide números
  - gmp_div_qr — Divide números e obtém quociente e resto
  - gmp_div_r — Resto da divisão de dois números
  - gmp_divexact — Divisão exata de números
  - gmp_export — Exporta para uma string binária
  - gmp_fact — Fatorial
  - gmp_gcd — Calcula o MDC
  - gmp_gcdext — Calcula MDC e multiplicadores
  - gmp_hamdist — Distância de Hamming
  - gmp_import — Importa de uma string binária
  - gmp_init — Cria um número GMP
  - gmp_intval — Converte um número GMP para um inteiro
  - gmp_invert — Inverso modular
  - gmp_jacobi — Símbolo de Jacobi
  - gmp_kronecker — Símbolo de Kronecker
  - gmp_lcm — Calcula o MMC
  - gmp_legendre — Símbolo de Legendre
  - gmp_mod — Operação Módulo
  - gmp_mul — Multiplica números
  - gmp_neg — Negativa o número
  - gmp_nextprime — Encontra o próximo número primo
  - gmp_or — Operação binária OR
  - gmp_perfect_power — Verificação de potência perfeita
  - gmp_perfect_square — Verificação de quadrado perfeito
  - gmp_popcount — Contagem de população
  - gmp_pow — Elevar o número a uma potência
  - gmp_powm — Eleva um número a uma potência com módulo
  - gmp_prob_prime — Verifica se o número é "provavelmente primo"
  - gmp_random — Número aleatório
  - gmp_random_bits — Numero aleatório
  - gmp_random_range — Obtém um inteiro uniformemente selecionado
  - gmp_random_seed — Define a semente do gerador de números aleatórios
  - gmp_root — Obtém a parte inteira da raiz enésima
  - gmp_rootrem — Obtém a parte inteira e o resto da raiz enésima
  - gmp_scan0 — Procura por 0
  - gmp_scan1 — Procura por 1
  - gmp_setbit — Define um bit
  - gmp_sign — Sinal do número
  - gmp_sqrt — Calcula a raiz quadrada
  - gmp_sqrtrem — Raiz quadrada com resto
  - gmp_strval — Converte um número GMP para uma string
  - gmp_sub — Subtrai números
  - gmp_testbit — Testa se um bit está definido
  - gmp_xor — Operação binária XOR
- GMP — A classe GMP
  - GMP::__construct — Cria um número GMP
  - GMP::__serialize — Serializa o objeto GMP
  - GMP::__unserialize — Desserializa o parâmetro data em um objeto GMP

# Funções Matemáticas

# Introdução

Estas funções matemáticas lidam apenas com valores dentro dos limites dos tipos int e float. Para manipular números maiores, consulte matemática com precisão arbitrária ou funções GNU de precisão múltipla.

## Veja Também

- Operadores aritméticos
- Funções matemáticas com precisão arbitrária
- Funções GNU de precisão múltipla

# Constantes predefinidas

As constantes abaixo estão sempre disponíveis como parte do núcleo do PHP.

Constantes matemáticas
`M_PI` (float)
  Aproximação do número π (pi). (`3.14159265358979323846`).
`M_E` (float)
  Aproximação do número de Euler `e` (`2.7182818284590452354`).
`M_LOG2E` (float)
  Aproximação de `log2(e)` (`1.4426950408889634074`).
`M_LOG10E` (float)
  Aproximação de `log10(e)` (`0.43429448190325182765`).
`M_LN2` (float)
  Aproximação de `ln(2)` (`0.69314718055994530942`).
`M_LN10` (float)
  Aproximação de `ln(10)` (`2.30258509299404568402`).
`M_PI_2` (float)
  Aproximação de `π/2` (`1.57079632679489661923`).
`M_PI_4` (float)
  Aproximação de `π/4` (`0.78539816339744830962`).
`M_1_PI` (float)
  Aproximação de `1/π` (`0.31830988618379067154`).
`M_2_PI` (float)
  Aproximação de `2/π` (`0.63661977236758134308`).
`M_SQRTPI` (float)
  Aproximação de `sqrt(π)` (`1.77245385090551602729`).
`M_2_SQRTPI` (float)
  Aproximação de `2/sqrt(π)` (`1.12837916709551257390`).
`M_SQRT2` (float)
  Aproximação de `sqrt(2)` (`1.41421356237309504880`).
`M_SQRT3` (float)
  Aproximação de `sqrt(3)` (`1.73205080756887729352`).
`M_SQRT1_2` (float)
  Aproximação de `1/sqrt(2)` (`0.70710678118654752440`).
`M_LNPI` (float)
  Aproximação de `ln(π)` (`1.14472988584940017414`).
`M_EULER` (float)
  Aproximação da constante de Euler γ (`0.57721566490153286061`).

Constantes de ponto flutuante IEEE 754
`NAN` (float)
  Um não-número (Not A Number)
`INF` (float)
  Infinito

Constantes de arredondamento

> Nota: A partir do PHP 8.4.0, é recomendado usar a enumeração RoundingMode no lugar destas constantes.

`PHP_ROUND_HALF_UP` (int)
  Arredonda a metade na direção oposta ao zero.
`PHP_ROUND_HALF_DOWN` (int)
  Arredonda a metade na direção do zero.
`PHP_ROUND_HALF_EVEN` (int)
  Arredonda a metade para o número par.
`PHP_ROUND_HALF_ODD` (int)
  Arredonda a metade para o número ímpar.

# A enumeração RoundingMode

(PHP 8 >= 8.4.0)

## Introdução

A enumeração RoundingMode é usada para especificar como o arredondamento deve ser realizado por round(), bcround() e BCMath\Number::round().

## Resumo da enumeração

enum RoundingMode
{
case HalfAwayFromZero ; // Arredonda para o inteiro mais próximo. Se a parte decimal for igual a `5`, arredonda para o inteiro com maior valor absoluto.
case HalfTowardsZero ; // Arredonda para o inteiro mais próximo. Se a parte decimal for igual a `5`, arredonda para o inteiro com menor valor absoluto.
case HalfEven ; // Arredonda para o inteiro mais próximo. Se a parte decimal for igual a `5`, arredonda para o inteiro par.
case HalfOdd ; // Arredonda para o inteiro mais próximo. Se a parte decimal for igual a `5`, arredonda para o inteiro ímpar.
case TowardsZero ; // Arredonda para o inteiro mais próximo com um valor absoluto menor ou igual.
case AwayFromZero ; // Arredonda para o inteiro mais próximo com um valor absoluto maior ou igual.
case NegativeInfinity ; // Arredonda para o maior inteiro que seja menor ou igual.
case PositiveInfinity ; // Arredonda para o menor inteiro que seja maior ou igual.
}

# Funções de Math

# abs

(PHP 4, PHP 5, PHP 7, PHP 8)

abs — Valor absoluto

### Descrição

function abs(int|float `$num`): int|float

Retorna o valor absoluto de `num`.

### Parâmetros

`num`

  O valor numérico a processar

### Valor Retornado

O valor absoluto de `num`. Se o argumento `num` for do tipo float, o número retornado também será float, caso contrário será int (pois float normalmente tem uma faixa de valores maior que int).

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `num` não aceita mais objetos internos que suportem conversão numérica.

### Exemplos

Exemplo #1 Exemplo de abs()

    <?php
    var_dump(abs(-4.2));
    var_dump(abs(5));
    var_dump(abs(-5));
    ?>

O exemplo acima produzirá:

    float(4.2)
    int(5)
    int(5)

### Veja Também

- gmp_abs() - Valor absoluto
- gmp_sign() - Sinal do número

# acos

(PHP 4, PHP 5, PHP 7, PHP 8)

acos — Arco cosseno

### Descrição

function acos(float `$num`): float

Retorna o arco cosseno de `num` em radianos. acos() é a função inversa de cos(), o que significa que `$num == cos(acos($num))` para qualquer valor de `num` que esteja no domínio de acos().

### Parâmetros

`num`

  O argumento a processar

### Valor Retornado

O arco cosseno de `num` em radianos.

### Veja Também

- cos() - Cosseno
- acosh() - Arco cosseno hiperbólico
- asin() - Arco seno
- atan() - Arco tangente

# acosh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

acosh — Arco cosseno hiperbólico

### Descrição

function acosh(float `$num`): float

Retorna o arco cosseno hiperbólico de `num`, isto é, o valor cujo cosseno hiperbólico é `num`.

### Parâmetros

`num`

  O valor a processar

### Valor Retornado

O arco cosseno hiperbólico de `num`

### Veja Também

- cosh() - Cosseno hiperbólico
- acos() - Arco cosseno
- asinh() - Arco seno hiperbólico
- atanh() - Arco tangente hiperbólico

# asin

(PHP 4, PHP 5, PHP 7, PHP 8)

asin — Arco seno

### Descrição

function asin(float `$num`): float

Retorna o arco seno de `num` em radianos. asin() é a função inversa da função sin(), o que significa que `$num == sin(asin($num))` para qualquer valor de `num` que esteja no domínio da função asin().

### Parâmetros

`num`

  O argumento a processar

### Valor Retornado

O arco seno de `num` em radianos

### Veja Também

- sin() - Seno
- asinh() - Arco seno hiperbólico
- acos() - Arco cosseno
- atan() - Arco tangente

# asinh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

asinh — Arco seno hiperbólico

### Descrição

function asinh(float `$num`): float

Retorna o arco seno hiperbólico de `num`, isto é, o valor cujo seno hiperbólico é `num`.

### Parâmetros

`num`

  O argumento a processar

### Valor Retornado

O arco seno hiperbólico de `num`

### Veja Também

- sinh() - Seno hiperbólico
- asin() - Arco seno
- acosh() - Arco cosseno hiperbólico
- atanh() - Arco tangente hiperbólico

# atan

(PHP 4, PHP 5, PHP 7, PHP 8)

atan — Arco tangente

### Descrição

function atan(float `$num`): float

Retorna o arco tangente de `num` em radianos. atan() é a função inversa da função tan(), o que significa que `$num == tan(atan($num))` para qualquer valor de `num` que esteja no domínio de atan().

### Parâmetros

`num`

  O argumento a processar

### Valor Retornado

O arco tangente de `num` em radianos.

### Veja Também

- tan() - Tangente
- atanh() - Arco tangente hiperbólico
- asin() - Arco seno
- acos() - Arco cosseno

# atan2

(PHP 4, PHP 5, PHP 7, PHP 8)

atan2 — Arco tangente de duas variáveis

### Descrição

function atan2(float `$y`, float `$x`): float

Esta função calcula o arco tangente das duas variaveis `x` e `y`. É similar a calcular o arco tangente de `y` / `x`, exceto que os sinais de ambos os argumentos são usados para determinar o quadrante do resultado.

Esta função retorna o resultado em radianos entre -PI e PI (inclusive).

### Parâmetros

`y`

  Dividendo

`x`

  Divisor

### Valor Retornado

O arco tangente de `y`/`x` em radianos.

### Veja Também

- atan() - Arco tangente

# atanh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

atanh — Arco tangente hiperbólico

### Descrição

function atanh(float `$num`): float

Retorna o arco tangente hiperbólico de `num`, isto é, o valor cuja tangente hiperbólica é `num`.

### Parâmetros

`num`

  O argumento a processar

### Valor Retornado

O arco tangente hiperbólico de `num`

### Veja Também

- tanh() - Tangente hiperbólica
- atan() - Arco tangente
- asinh() - Arco seno hiperbólico
- acosh() - Arco cosseno hiperbólico

# base_convert

(PHP 4, PHP 5, PHP 7, PHP 8)

base_convert — Converte um número entre bases arbitrárias

### Descrição

function base_convert(string `$num`, int `$from_base`, int `$to_base`): string

Retorna uma string contendo `num` representado na base `to_base`. A base na qual `num` é informada está especificada em `from_base`. Tanto `from_base` quanto `to_base` devem estar entre 2 e 36, inclusive. Dígitos em números com uma base maior do que 10 serão representados com letras a-z, com 'a' significando 10, 'b' significando 11 e 'z' significando 35. A forma das letras não importa, ou seja `num` é interpretado sem sensibilidade a maiúsculas/minúsculas.

Aviso

base_convert() pode perder precisão com números grandes devido a propriedade relacionadaa ao o tipo interno de float usado. Consulte a seção Números de ponto flutuante no manual para mais informações e limitações específicas.

### Parâmetros

`num`

  O número a ser convertido. Quaisquer caracteres inválidos em `num` serão ignorados silenciosamente. A partir do PHP 7.4.0, informar caracteres inválidos foi descontinuado.

`from_base`

  A base em que `num` está

`to_base`

  A base para a qual deve-se converter `num`

### Valor Retornado

`num` convertido para a base `to_base`

### Registro de Alterações

Versão | Descrição
--- | ---
7.4.0 | Passar caracteres inválidos agora gerará uma nota de descontinuação. O resultado ainda é calculado como se os caracteres inválidos não existissem.

### Exemplos

Exemplo #1 Exemplo de base_convert()

    <?php
    $hexadecimal = 'a37334';
    echo base_convert($hexadecimal, 16, 2);
    ?>

O exemplo acima produzirá:

    101000110111001100110100

### Veja Também

- intval() - Obtém o valor em número inteiro de uma variável

# bindec

(PHP 4, PHP 5, PHP 7, PHP 8)

bindec — Binário para decimal

### Descrição

function bindec(string `$binary_string`): int|float

Retorna o equivalente decimal do número binário representado pelo argumento `binary_string`.

bindec() converte um número binário em um int ou, se necessário por questão de tamanho, um float.

bindec() interpreta todos os valores de `binary_string` como inteiros sem sinal. Isto é devido a bindec() enxergar o bit mais significativo como uma outra ordem de magnitude e não como um bit de sinal.

### Parâmetros

`binary_string`

  A string binária a converter. Quaisquer caracteres inválidos em `binary_string` são silenciosamente ignorados. A partir do PHP 7.4.0, fornecer qualquer caractere inválido foi descontinuado.

Aviso

O parâmetro deve ser uma string. Usar outros tipos de dados produzirá resultados inesperados.

### Valor Retornado

O valor decimal de `binary_string`

### Registro de Alterações

Versão | Descrição
--- | ---
7.4.0 | Passar caracteres inválidos agora irá gerar uma nota de descontinuação. O resultado ainda será computado como se os caracteres inválidos não existissem.

### Exemplos

Exemplo #1 Exemplo de bindec()

    <?php
    echo bindec('110011') . "\n";
    echo bindec('000110011') . "\n";

    echo bindec('111');
    ?>

O exemplo acima produzirá:

    51
    51
    7

Exemplo #2 bindec() interpreta a entrada como inteiros sem sinal

    <?php
    /*
     * A lição deste exemplo está na saída
     * e não no código do PHP em si.
     */

    $magnitude_lower = pow(2, (PHP_INT_SIZE * 8) - 2);
    p($magnitude_lower - 1);
    p($magnitude_lower, 'Percebeu a rolagem?  Veja da próxima vez...');

    p(PHP_INT_MAX, 'PHP_INT_MAX');
    p(~PHP_INT_MAX, 'interpretado como um a mais que PHP_INT_MAX');

    if (PHP_INT_SIZE == 4) {
        $note = 'interpretado como o maior inteiro sem sinal';
    } else {
        $note = 'interpretado como o maior inteiro sem sinal
                  (18446744073709551615) porém distorcido pela precisão de float';
    }
    p(-1, $note);

    function p($input, $note = '') {
        echo "entrada:        $input\n";

        $format = '%0' . (PHP_INT_SIZE * 8) . 'b';
        $bin = sprintf($format, $input);
        echo "binário:       $bin\n";

        ini_set('precision', 20);  // Para legibilidade em máquinas 64 bits.
        $dec = bindec($bin);
        echo 'bindec():     ' . $dec . "\n";

        if ($note) {
            echo "NOTA:         $note\n";
        }

        echo "\n";
    }
    ?>

Saída do exemplo acima em máquinas de 32 bits:

    input:        1073741823
    binary:       00111111111111111111111111111111
    bindec():     1073741823

    input:        1073741824
    binary:       01000000000000000000000000000000
    bindec():     1073741824
    NOTE:         Percebeu a rolagem?  Veja da próxima vez...

    input:        2147483647
    binary:       01111111111111111111111111111111
    bindec():     2147483647
    NOTE:         PHP_INT_MAX

    input:        -2147483648
    binary:       10000000000000000000000000000000
    bindec():     2147483648
    NOTE:         interpretado como um a mais que PHP_INT_MAX

    input:        -1
    binary:       11111111111111111111111111111111
    bindec():     4294967295
    NOTE:         interpretado como o maior inteiro sem sinal

Saída do exemplo acima em máquinas de 64 bits:

    input:        4611686018427387903
    binary:       0011111111111111111111111111111111111111111111111111111111111111
    bindec():     4611686018427387903

    input:        4611686018427387904
    binary:       0100000000000000000000000000000000000000000000000000000000000000
    bindec():     4611686018427387904
    NOTE:         Percebeu a rolagem?  Veja da próxima vez...

    input:        9223372036854775807
    binary:       0111111111111111111111111111111111111111111111111111111111111111
    bindec():     9223372036854775807
    NOTE:         PHP_INT_MAX

    input:        -9223372036854775808
    binary:       1000000000000000000000000000000000000000000000000000000000000000
    bindec():     9223372036854775808
    NOTE:         interpretado como um a mais que PHP_INT_MAX

    input:        -1
    binary:       1111111111111111111111111111111111111111111111111111111111111111
    bindec():     18446744073709551616
    NOTE:         interpretado como o maior inteiro sem sinal
                  (18446744073709551615) porém distorcido pela precisão de float

### Notas

> Nota:

> A função pode converter números que são grandes demais para caber no tipo int da plataforma, valores maiores são retornados como float neste caso.

### Veja Também

- decbin() - Decimal para binário
- octdec() - Octal para decimal
- hexdec() - Hexadecimal para decimal
- base_convert() - Converte um número entre bases arbitrárias

# ceil

(PHP 4, PHP 5, PHP 7, PHP 8)

ceil — Arredonda frações para cima

### Descrição

function ceil(int|float `$num`): float

Retorna o próximo maior valor inteiro arredondando-se `num` para cima, se necessário.

### Parâmetros

`num`

  O valor a ser arredondado

### Valor Retornado

`num` arredondado pra o próximo inteiro. O valor retornado de ceil() ainda será do tipo float porque a faixa de valores suportados por float é normalmente maior do que o do tipo int.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `num` não mais aceita objetos internos que suportam conversão numérica.

### Exemplos

Exemplo #1 Exemplo de ceil()

    <?php
    echo ceil(4.3), PHP_EOL;    // 5
    echo ceil(9.999), PHP_EOL;  // 10
    echo ceil(-3.14), PHP_EOL; // -3
    ?>

### Veja Também

- floor() - Arredonda frações para baixo
- round() - Arredonda um float

# cos

(PHP 4, PHP 5, PHP 7, PHP 8)

cos — Cosseno

### Descrição

function cos(float `$num`): float

cos() retorna o cosseno do parâmetro `num`. O parâmetro `num` deve estar em radianos.

### Parâmetros

`num`

  Um ângulo em radianos

### Valor Retornado

O cosseno de `num`

### Exemplos

Exemplo #1 Exemplo de cos()

    <?php

    echo cos(M_PI); // -1

    ?>

### Veja Também

- acos() - Arco cosseno
- sin() - Seno
- tan() - Tangente
- deg2rad() - Converte o número em graus para o equivalente em radianos

# cosh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cosh — Cosseno hiperbólico

### Descrição

function cosh(float `$num`): float

Retorna o cosseno hiperbólico de `num`, definido por `(exp($num) + exp(-$num))/2`.

### Parâmetros

`num`

  O argumento a processar

### Valor Retornado

O cosseno hiperbólico de `num`

### Veja Também

- cos() - Cosseno
- acosh() - Arco cosseno hiperbólico
- sinh() - Seno hiperbólico
- tanh() - Tangente hiperbólica

# decbin

(PHP 4, PHP 5, PHP 7, PHP 8)

decbin — Decimal para binário

### Descrição

function decbin(int `$num`): string

Retorna uma string contendo uma representação binária do argumento `num` informado.

### Parâmetros

`num`

  Valor decimal a ser convertido

  Limites de entrada em máquinas de 32 bits
  `num` positivo | `num` negativo | valor de retorno
  --- | --- | ---
  0 |  | 0
  1 |  | 1
  2 |  | 10
  ... progressão normal ...
  2147483646 |  | 1111111111111111111111111111110
  2147483647 (maior inteiro com sinal) |  | 1111111111111111111111111111111 (31 números 1)
  2147483648 | -2147483648 | 10000000000000000000000000000000
  ... progressão normal ...
  4294967294 | -2 | 11111111111111111111111111111110
  4294967295 (maior inteiro sem sinal) | -1 | 11111111111111111111111111111111 (32 números 1)

  Limites de entrada em máquinas de 64 bits
  `num` positivo | `num` negativo | valor de retorno
  --- | --- | ---
  0 |  | 0
  1 |  | 1
  2 |  | 10
  ... progressão normal ...
  9223372036854775806 |  | 111111111111111111111111111111111111111111111111111111111111110
  9223372036854775807 (maior inteiro com sinal) |  | 111111111111111111111111111111111111111111111111111111111111111 (63 números 1)
  | -9223372036854775808 | 1000000000000000000000000000000000000000000000000000000000000000
  ... progressão normal ...
  | -2 | 1111111111111111111111111111111111111111111111111111111111111110
  | -1 | 1111111111111111111111111111111111111111111111111111111111111111 (64 números 1)

### Valor Retornado

Representação de `num` em string binária.

### Exemplos

Exemplo #1 Exemplo de decbin()

    <?php
    echo decbin(12) . "\n";
    echo decbin(26);
    ?>

O exemplo acima produzirá:

    1100
    11010

### Veja Também

- bindec() - Binário para decimal
- decoct() - Decimal para octal
- dechex() - Decimal para hexadecimal
- base_convert() - Converte um número entre bases arbitrárias
- printf() - Envia uma string formatada para a saída, usando `%b`, `%032b` ou `%064b` como formato
- sprintf() - Retona uma string formatada, usando `%b`, `%032b` ou `%064b` como formato

# dechex

(PHP 4, PHP 5, PHP 7, PHP 8)

dechex — Decimal para hexadecimal

### Descrição

function dechex(int `$num`): string

Retorna uma string contendo uma representação hexadecimal do argumento sem sinal `num` fornecido.

O maior número que pode ser convertido é `PHP_INT_MAX``* 2 + 1` (ou `-1`): em plataformas de 32 bits, será `4294967295` em decimal, que resulta em dechex() retornando `ffffffff`.

### Parâmetros

`num`

  O valor decimal a ser convertido

  Como o tipo int do PHP tem sinal, mas dechex() lida com inteiros sem sinal, inteiros negativos serão tratados como se fossem sem sinal.

### Valor Retornado

Representação de `num` em string hexadecimal.

### Exemplos

Exemplo #1 Exemplo de dechex()

    <?php
    echo dechex(10) . "\n";
    echo dechex(47);
    ?>

O exemplo acima produzirá:

    a
    2f

Exemplo #2 Exemplo de dechex() com inteiros grandes

    <?php
    // A saída abaixo assume uma plataforma de 32 bits.
    // Note que a saída é a mesma para todos os valores.
    echo dechex(-1)."\n";
    echo dechex(PHP_INT_MAX * 2 + 1)."\n";
    echo dechex(pow(2, 32) - 1)."\n";
    ?>

O exemplo acima produzirá:

    ffffffff
    ffffffff
    ffffffff

### Veja Também

- hexdec() - Hexadecimal para decimal
- decbin() - Decimal para binário
- decoct() - Decimal para octal
- base_convert() - Converte um número entre bases arbitrárias

# decoct

(PHP 4, PHP 5, PHP 7, PHP 8)

decoct — Decimal para octal

### Descrição

function decoct(int `$num`): string

Retorna uma string contendo uma representação octal do argumento `num` fornecido. O maior número que pode ser convertido depende da plataforma em uso. Para plataformas de 32 bits é normalmente `4294967295` em decimal, resultando em `37777777777`. Para plataformas de 64 bits é normalmente `9223372036854775807` em decimal resultando em `777777777777777777777`.

### Parâmetros

`num`

  Valor decimal a ser convertido

### Valor Retornado

Representação de `num` em string octal.

### Exemplos

Exemplo #1 Exemplo de decoct()

    <?php
    echo decoct(15) . "\n";
    echo decoct(264);
    ?>

O exemplo acima produzirá:

    17
    410

### Veja Também

- octdec() - Octal para decimal
- decbin() - Decimal para binário
- dechex() - Decimal para hexadecimal
- base_convert() - Converte um número entre bases arbitrárias

# deg2rad

(PHP 4, PHP 5, PHP 7, PHP 8)

deg2rad — Converte o número em graus para o equivalente em radianos

### Descrição

function deg2rad(float `$num`): float

Esta função converte `num` de graus para o equivalente em radianos.

### Parâmetros

`num`

  Valor do ângulo em graus

### Valor Retornado

O radiano equivalente ao `num`

### Exemplos

Exemplo #1 Exemplo de deg2rad()

    <?php

    echo deg2rad(45), PHP_EOL; // 0.785398163397
    var_dump(deg2rad(45) === M_PI_4); // bool(true)

    ?>

### Veja Também

- rad2deg() - Converte o número em radianos para o equivalente em graus

# exp

(PHP 4, PHP 5, PHP 7, PHP 8)

exp — Calcula o expoente de `e`

### Descrição

function exp(float `$num`): float

Retorna `e` elevada à potência de `num`.

> Nota:

> '`e`' é a base do sistema natural de logaritmos, ou aproximadamente 2.718282.

### Parâmetros

`num`

  O argumento a ser processado

### Valor Retornado

'e' elevado à potência de `num`

### Exemplos

Exemplo #1 Exemplo de exp()

    <?php
    echo exp(12), PHP_EOL;
    echo exp(5.7);
    ?>

O exemplo acima produzirá:

    162754.791419
    298.86740096706

### Veja Também

- log() - Logaritmo natural
- pow() - Expressão exponencial

# expm1

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

expm1 — Retorna `exp($num) - 1`, computado de forma precisa mesmo quando o valor do número está próximo de zero.

### Descrição

function expm1(float `$num`): float

expm1() retorna o equivalente a `exp($`num`) - 1` computado de forma precisa mesmo se o valor de `num` for próximo de zero, que é um caso onde `exp($`num`) - 1` poderia ser impreciso devido à subtração de dois números quase iguais.

### Parâmetros

`num`

  O argumento a ser processado

### Valor Retornado

`e` elevado à potência de `num` menos um.

### Veja Também

- log1p() - Retorna log(1 + número), calculado de forma que seja preciso mesmo quando o valor do número seja próximo de zero.
- exp() - Calcula o expoente de e

# fdiv

(PHP 8)

fdiv — Divide dois números de acordo com a IEEE 754

### Descrição

function fdiv(float `$num1`, float `$num2`): float

Retorna o resultado em ponto flutuante da divisão de `num1` por `num2`. Se `num2` for zero, um dos valores `INF`, -`INF` ou `NAN` será retornado.

Note que em comparações, `NAN` nunca será igual (`==`) ou idêntica (`===`) a nenhum valor, incluindo a si mesma.

### Parâmetros

`num1`

  O dividendo (numerador)

`num2`

  O divisor

### Valor Retornado

O resultado em ponto flutuante de `num1`/`num2`

### Exemplos

Exemplo #1 Usando fdiv()

    <?php
    var_dump(fdiv(5.7, 1.3)); // float(4.384615384615385)
    var_dump(fdiv(4, 2)); // float(2)
    var_dump(fdiv(1.0, 0.0)); // float(INF)
    var_dump(fdiv(-1.0, 0.0)); // float(-INF)
    var_dump(fdiv(0.0, 0.0)); // float(NAN)
    ?>

### Veja Também

- Operador de divisão `/`
- intdiv() - Divisão de inteiros - Divisão de inteiros
- fmod() - Retorna o resto (módulo) em ponto flutuante da divisão dos argumentos
- fpow() - Eleva um número à potência de outro, de acordo com a IEEE 754

# floor

(PHP 4, PHP 5, PHP 7, PHP 8)

floor — Arredonda frações para baixo

### Descrição

function floor(int|float `$num`): float

Retorna o próximo menor valor inteiro (como float), arredondando `num` para baixo, se necessário.

### Parâmetros

`num`

  O valor numérico a ser arredondado

### Valor Retornado

`num` arredondado para o inteiro menor mais próximo. O valor retornado por floor() ainda será do tipo float.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | `num` não mais aceita tipos internos que suportam conversão numérica.

### Exemplos

Exemplo #1 Exemplos de floor()

    <?php
    echo floor(4.3), PHP_EOL;   // 4
    echo floor(9.999), PHP_EOL; // 9
    echo floor(-3.14), PHP_EOL; // -4
    ?>

### Veja Também

- ceil() - Arredonda frações para cima
- round() - Arredonda um float

# fmod

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

fmod — Retorna o resto (módulo) em ponto flutuante da divisão dos argumentos

### Descrição

function fmod(float `$num1`, float `$num2`): float

Retorna o resto em ponto flutuante da divisão do dividendo (`num1`) pelo divisor (`num2`). O resto (r) é definido como: num1 = i * num2 + r, para algum inteiro i. Se o `num2` for diferente de zero, r terá o mesmo sinal de `num1` e uma magnitude menor que a magnitude de `num2`.

### Parâmetros

`num1`

  O dividendo

`num2`

  O divisor

### Valor Retornado

O resto em ponto flutuante de `num1`/`num2`. `NAN` (float) se o segundo argumento for 0.

### Exemplos

Exemplo #1 Usando fmod()

    <?php
    $x = 5.7;
    $y = 1.3;
    $r = fmod($x, $y);
    // $r é igual a 0.5, porque 4 * 1.3 + 0.5 = 5.7

    var_dump($x, $y, $r);
    ?>

### Veja Também

- `/` - Divisão de ponto flutuante
- `%` - Módulo de inteiros
- intdiv() - Divisão de inteiros - Divisão de inteiros

# fpow

(PHP 8 >= 8.4.0)

fpow — Eleva um número à potência de outro, de acordo com a IEEE 754

### Descrição

function fpow(float `$num`, float `$exponent`): float

Retorna o resultado em ponto flutuante da elevação de `num` à potência de `exponent`. Se `num` for zero e `exponent` for menor que zero, retorna `INF`.

### Parâmetros

`num`
  A base a ser usada.
`exponent`
  O expoente.

### Valor Retornado

Retorna um float correspondente a `$num$exponent`.

### Exemplos

Exemplo #1 Exemplo de fpow()

    <?php
    var_dump(fpow(10, 2));
    var_dump(fpow(0, -3));
    var_dump(fpow(-1, 5.5));
    ?>

O exemplo acima produzirá:

    float(100)
    float(INF)
    float(NAN)

### Veja Também

- Operador de exponenciação `**`
- pow() - Expressão exponencial
- fdiv() - Divide dois números de acordo com a IEEE 754
- fmod() - Retorna o resto (módulo) em ponto flutuante da divisão dos argumentos

# hexdec

(PHP 4, PHP 5, PHP 7, PHP 8)

hexdec — Hexadecimal para decimal

### Descrição

function hexdec(string `$hex_string`): int|float

Retorna o equivalente em decimal do número hexadecimal representado pelo argumento `hex_string`. hexdec() converte uma string hexadecimal para um número decimal.

hexdec() irá ignorar qualquer caractere não hexadecimal que encontrar. A partir do PHP 7.4.0 fornecer caracteres inválidos foi descontinuado.

### Parâmetros

`hex_string`

  A string hexadecimal a ser convertida

### Valor Retornado

A representação decimal de `hex_string`

### Registro de Alterações

Versão | Descrição
--- | ---
7.4.0 | Passar caracteres inválidos agora irá gerar uma nota de descontinuação. O resultado ainda será computado como se os caracteres inválidos não existissem.

### Exemplos

Exemplo #1 Exemplo de hexdec()

    <?php
    var_dump(hexdec("ee")); // exibe "int(238)"
    var_dump(hexdec("a0")); // exibe "int(160)"
    ?>

Exemplo #2 hexdec() com caracteres inválidos

    <?php
    var_dump(hexdec("See"));  // print "int(238)"
    var_dump(hexdec("that")); // mostra "int(10)"
    ?>

### Notas

> Nota:

> A função pode converter números que são longos demais para caber nos tipos int das plataformas, valores maiores são retornados como float neste caso.

### Veja Também

- dechex() - Decimal para hexadecimal
- bindec() - Binário para decimal
- octdec() - Octal para decimal
- base_convert() - Converte um número entre bases arbitrárias

# hypot

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

hypot — Calcula o comprimento da hipotenusa de triângulo retângulo

### Descrição

function hypot(float `$x`, float `$y`): float

hypot() retorna o comprimento da hipotenusa de um triângulo retângulo com lados de tamanho `x` e `y`, ou a distância do ponto (`x`, `y`) a partir da origem. É o equivalente a `sqrt($x*$x + $y*$y)`.

### Parâmetros

`x`

  Comprimento do primeiro lado

`y`

  Comprimento do segundo lado

### Valor Retornado

Comprimento calculado da hipotenusa

# intdiv

(PHP 7, PHP 8)

intdiv — Divisão de inteiros

### Descrição

function intdiv(int `$num1`, int `$num2`): int

Retorna o quociente inteiro da divisão de `num1` por `num2`.

### Parâmetros

`num1`

  Número a ser dividido.

`num2`

  Número que divide o `num1`.

### Valor Retornado

O quociente inteiro da divisão de `num1` por `num2`.

### Erros/Exceções

Se `num2` for `0`, uma exceção DivisionByZeroError é lançada. Se `num1` for `PHP_INT_MIN` e `num2` for `-1`, então uma exceção ArithmeticError é lançada.

### Exemplos

Exemplo #1 Exemplo de intdiv()

    <?php
    var_dump(intdiv(3, 2));
    var_dump(intdiv(-3, 2));
    var_dump(intdiv(3, -2));
    var_dump(intdiv(-3, -2));
    var_dump(intdiv(PHP_INT_MAX, PHP_INT_MAX));
    var_dump(intdiv(PHP_INT_MIN, PHP_INT_MIN));
    ?>

O exemplo acima produzirá:

    int(1)
    int(-1)
    int(-1)
    int(1)
    int(1)
    int(1)

Exemplo #2 Exemplo de intdiv() com divisor inválido

    <?php
    try {
        intdiv(PHP_INT_MIN, -1);
    } catch (Error $e) {
        echo get_class($e), ': ', $e->getMessage(), PHP_EOL;
    }

    try {
        intdiv(1, 0);
    } catch (Error $e) {
        echo get_class($e), ': ', $e->getMessage(), PHP_EOL;
    }
    ?>

O exemplo acima produzirá:

    ArithmeticError: Division of PHP_INT_MIN by -1 is not an integer
    DivisionByZeroError: Division by zero

### Veja Também

- `/` - Divisão de ponto flutuante
- `%` - Resto de divisão de inteiros
- fmod() - Retorna o resto (módulo) em ponto flutuante da divisão dos argumentos - Resto de divisão em ponto flutuante

# is_finite

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

is_finite — Verifica se um float é finito

### Descrição

function is_finite(float `$num`): bool

Retorna informando se `num` é um float finito.

Um float finito não é `NAN` (is_nan()), nem um infinito (is_infinite()).

### Parâmetros

`num`

  O float a ser verificado

### Valor Retornado

`true` se `num` não for `NAN`, `INF` nem -`INF`, caso contrário retorna `false`.

### Exemplos

Exemplo #1 Exemplo de is_finite()

    <?php
    $float = 1.2345;
    var_dump($float, is_finite($float));

    $nan = sqrt(-1);
    var_dump($nan, is_finite($nan));

    $inf = 1e308 * 2;
    var_dump($inf, is_finite($inf));
    ?>

O exemplo acima produzirá:

    float(1.2345)
    bool(true)
    float(NAN)
    bool(false)
    float(INF)
    bool(false)

### Veja Também

- is_infinite() - Verifica se um float é infinito
- is_nan() - Verifica se um float é NAN

# is_infinite

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

is_infinite — Verifica se um float é infinito

### Descrição

function is_infinite(float `$num`): bool

Retorna informando se `num` é `INF` ou -`INF`.

### Parâmetros

`num`

  O float a ser verificado

### Valor Retornado

`true` se `num` for `INF` ou -`INF`, senão retorna `false`.

### Exemplos

Exemplo #1 Exemplo de is_infinite()

    <?php
    $inf = 1e308 * 2;

    var_dump($inf, is_infinite($inf));

    $negative_inf = -$inf;

    var_dump($negative_inf, is_infinite($negative_inf));
    ?>

O exemplo acima produzirá:

    float(INF)
    bool(true)
    float(-INF)
    bool(true)

### Veja Também

- is_finite() - Verifica se um float é finito
- is_nan() - Verifica se um float é NAN

# is_nan

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

is_nan — Verifica se um float é NAN

### Descrição

function is_nan(float `$num`): bool

Retorna indicando se o `num` é um `NAN` (Not A Number).

`NAN` é retornado de operações matemáticas que são indefinidas, por exemplo ao passar parâmetros fora do domínio de entrada da função. A raiz quadrada (sqrt()) só é definida para números positivos, e informar um número negativo resultará em `NAN`. Outros exemplos de operações que retornam `NAN` são a divisão de `INF` por `INF` e operações que envolvam um valor `NAN` existente.

> Nota:

> Apesar do nome Not A Number, `NAN` é um valor válido do tipo float.

Cuidado

`NAN` não se compara em igualdade a `NAN`. Para verificar se um float é `NAN`, is_nan() deve ser utilizado. Usar `$float === NAN` não funcionará.

### Parâmetros

`num`

  O float a ser verificado

### Valor Retornado

`true` se `num` for `NAN`, senão retorna `false`.

### Exemplos

Exemplo #1 Exemplo de is_nan()

    <?php
    $nan = sqrt(-1);

    var_dump($nan, is_nan($nan));
    ?>

O exemplo acima produzirá:

    float(NAN)
    bool(true)

### Veja Também

- is_finite() - Verifica se um float é finito
- is_infinite() - Verifica se um float é infinito

# log

(PHP 4, PHP 5, PHP 7, PHP 8)

log — Logaritmo natural

### Descrição

function log(float `$num`, float `$base` = `M_E`): float

Se a `base` opcional for informada, log() retorna logbase `num`, senão log() retorna o logaritmo natural de `num`.

### Parâmetros

`num`

  O valor para o qual o logaritmo será calculado

`base`

  A base logaritmica opcional a ser utilizada (padrão é 'e' para logaritmo natural).

### Valor Retornado

O logarimo de `num` na `base`, se fornecida, ou o logaritmo natural.

### Veja Também

- log10() - Logaritmo na base 10
- exp() - Calcula o expoente de e
- pow() - Expressão exponencial
- error_log() - Envia uma mensagem de erro para as rotinas de tratamento de erros definidas

# log10

(PHP 4, PHP 5, PHP 7, PHP 8)

log10 — Logaritmo na base 10

### Descrição

function log10(float `$num`): float

Retorna o logaritmo na base 10 de `num`.

### Parâmetros

`num`

  O argumento a ser processado

### Valor Retornado

O logaritmo na base 10 de `num`

### Veja Também

- log() - Logaritmo natural

# log1p

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

log1p — Retorna log(1 + número), calculado de forma que seja preciso mesmo quando o valor do número seja próximo de zero.

### Descrição

function log1p(float `$num`): float

log1p() retorna log(1 + `num`) computado de forma que seja preciso mesmo quando o valor de `num` esteja próximo de zero. log() poderia retornar apenas log(1) neste caso devido à falta de precisão.

### Parâmetros

`num`

  O argumento a ser processado

### Valor Retornado

log(1 + `num`)

### Veja Também

- expm1() - Retorna exp($num) - 1, computado de forma precisa mesmo quando o valor do número está próximo de zero.
- log() - Logaritmo natural
- log10() - Logaritmo na base 10

# max

(PHP 4, PHP 5, PHP 7, PHP 8)

max — Localiza o maior valor

### Descrição

function max(mixed `$value`, mixed `...$values`): mixed

Forma alternativa (não suportada com argumentos nomeados):

function max(array `$value_array`): mixed

Se o primeiro e único parâmetro for um array, max() retorna o maior valor do array. Se no mínimo dois parâmetros forem fornecidos, max() retorna o maior desses valores.

> Nota:

> Valores de diferentes tipos serão comparados utilizando as regras padrões de comparação. Por exemplo, uma string não numérica será comparada a um int como se fosse `0`, mas várias strings não numéricas serão comparadas alfanumericamente. O valor real retornado terá o tipo do original, sem nenhuma conversão aplicada.

Cuidado

Cuidado ao passar argumentos de tipos diferentes, pois max() pode produzir resultados imprevisíveis.

### Parâmetros

`value`

  Qualquer valor comparável.

`values`

  Quaisquer valores comparáveis.

`value_array`

  Um array contendo os valores.

### Valor Retornado

max() retorna o parâmetro considerado o "maior" de acordo com as comparações padrões. Se vários valores de tipos diferentes forem considerados iguais (por exemplo, `0` e `'abc'`) então o primeiro fornecido à função será retornado.

### Erros/Exceções

Se um array vazio for informado, max() lança um ValueError.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | max() lança um ValueError em caso de erros. Anteriormente, retornava `false` e emitia um alerta `E_WARNING`.
8.0.0 | Como as comparações de strings com números foram alteradas, max() não mais retorna um valor diferente por conta da ordem dos argumentos informados.

### Exemplos

Exemplo #1 Exemplos de max()

    <?php
    echo max(2, 3, 1, 6, 7), PHP_EOL;  // 7
    echo max(array(2, 4, 5)), PHP_EOL; // 5

    // Aqui na prática compara-se -1 < 0, então 'hello' é o maior valor
    echo max('hello', -1), PHP_EOL;    // hello

    // Arrays de múltiplos valores e tamanhos diferentes, retora o mais longo
    $val = max(array(2, 2, 2), array(1, 1, 1, 1)); // array(1, 1, 1, 1)
    var_dump($val);

    // Em arrays de mesmo tamanho compara-se da esquerda para direita
    // e nesse exemplo: 2 == 2, mas 5 > 4
    $val = max(array(2, 4, 8), array(2, 5, 1)); // array(2, 5, 1)
    var_dump($val);

    // Se um array e um não array são informados, o array será retornado
    // pois é considerado maior que qualquer outro valor
    $val = max('string', array(2, 5, 7), 42);   // array(2, 5, 7)
    var_dump($val);

    // Se um argumento é NULL ou booleano, ele será comparado contra
    // outros valores utilizando a regra FALSE < TRUE independente dos tipos envolvidos.
    // No exemplo abaixo -10 é tratado como TRUE na comparação
    $val = max(-10, FALSE); // -10
    var_dump($val);

    // 0 por outro lado é considerado false, de forma que é "menor que" TRUE
    $val = max(0, TRUE); // TRUE
    var_dump($val);
    ?>

### Veja Também

- min() - Encontra o menor valor
- count() - Conta todos os elementos de um array ou de um objeto Countable

# min

(PHP 4, PHP 5, PHP 7, PHP 8)

min — Encontra o menor valor

### Descrição

function min(mixed `$value`, mixed `...$values`): mixed

Forma alternativa (não suportada com argumentos nomeados):

function min(array `$value_array`): mixed

Se o primeiro e único argumento é um array, min() retorna o menor valor no array. Se no mínimo dois parâmetros são fornecidos, min() retorna o menor deles.

> Nota:

> Valores de tipos diferentes serão comparados utilizando as regras padrões de comparação. Por exemplo, uma string não numérica será comparada com um inteiro int como se fosse `0`, mas várias strings não numéricos serão comparadas alfanumericamente. O valor real retornado terá o tipo do original, sem nenhuma conversão aplicada.

Cuidado

Cuidado ao passar argumentos de tipos diferentes, pois min() pode produzir resultados imprevisíveis.

### Parâmetros

`value`

  Qualquer valor comparável.

`values`

  Quaisquer valores comparáveis.

`value_array`

  Um array contendo os valores.

### Valor Retornado

min() retorna o valor considerado o "menor" de acordo com as comparações padrão. Se valores de diferentes tipos forem avaliados como iguais (por exemplo `0` e `'abc'`) então o primeiro valor fornecido à função será retornado.

### Erros/Exceções

Se um array vazio for informado, min() lança um ValueError.

### Registro de Alterações

Versão | Descrição
--- | ---
8.0.0 | min() lança um ValueError em caso de falhas; anteriormente retornava `false` e emitia um alerta `E_WARNING`.
8.0.0 | Como as comparações de número e string foram alteradas, min() não mais retorna um valor diferente por conta da ordem dos argumentos informados.

### Exemplos

Exemplo #1 Exemplos de min()

    <?php
    echo min(2, 3, 1, 6, 7), PHP_EOL;  // 1
    echo min(array(2, 4, 5)), PHP_EOL; // 2

    // Aqui a comparação que ocorre é -1 < 0, e -1 é o menor valor
    echo min('hello', -1), PHP_EOL;    // -1

    // Quando comparando arrays de vários comprimentos, min retorna o mais curto
    $val = min(array(2, 2, 2), array(1, 1, 1, 1)); // array(2, 2, 2)
    var_dump($val);

    // Vários arrays de mesmo tamanho, a comparação ocorre nos elementos, da esquerda para direita
    // so in our example: 2 == 2, but 4 < 5
    $val = min(array(2, 4, 8), array(2, 5, 1)); // array(2, 4, 8)
    var_dump($val);

    // Se for fornecido um array e um primitivo, o array nunca é retornado
    // pois as comparações tratam os arrays como maiores que outros valores
    $val = min('string', array(2, 5, 7), 42);   // string
    var_dump($val);

    // Se um argumento é null ou booleano, ele será comparado com outros valores
    // usando a regra que FALSE < TRUE e NULL == FALSE,
    // independente dos tipos envolvidos
    // Nos exemplos abaixo -10 e 10 são tratados como TRUE nas comparações
    $val = min(-10, FALSE, 10); // FALSE
    var_dump($val);

    $val = min(-10, NULL, 10);  // NULL
    var_dump($val);

    // 0, por outro lado, é tratado como FALSE, então é "menor que" TRUE
    $val = min(0, TRUE); // 0
    var_dump($val);
    ?>

### Veja Também

- max() - Localiza o maior valor
- count() - Conta todos os elementos de um array ou de um objeto Countable

# octdec

(PHP 4, PHP 5, PHP 7, PHP 8)

octdec — Octal para decimal

### Descrição

function octdec(string `$octal_string`): int|float

Retorna o decimal equivalente do número octal representado pelo argumento `octal_string`.

### Parâmetros

`octal_string`

  A string octal a ser convertida. Quaisquer caracteres inválidos em `octal_string` são ignorados silenciosamente. A partir do PHP 7.4.0, informar caracteres inválidos foi descontinuado.

### Valor Retornado

A representação decimal de `octal_string`

### Registro de Alterações

Versão | Descrição
--- | ---
7.4.0 | Passar caracteres inválidos gerará um aviso de descontinuação. O resultado será calculado como se os caracteres inválidos não existissem.

### Exemplos

Exemplo #1 Exemplo da octdec()

    <?php
    echo octdec('77') . "\n";
    echo octdec(decoct(45));
    ?>

O exemplo acima produzirá:

    63
    45

### Notas

> Nota:

> A função pode converter números que são muito grandes para caber no tipo int da plataforma, e nesse caso os valores são retornados como float.

### Veja Também

- decoct() - Decimal para octal
- bindec() - Binário para decimal
- hexdec() - Hexadecimal para decimal
- base_convert() - Converte um número entre bases arbitrárias

# pi

(PHP 4, PHP 5, PHP 7, PHP 8)

pi — Obtém o valor de pi

### Descrição

function pi(): float

Retorna uma aproximação de pi. Alternativamente, pode-se usar a constante `M_PI` que fornece resultado idêntico a pi().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

O valor de pi como float.

### Exemplos

Exemplo #1 Exemplo de pi()

    <?php
    echo pi(), PHP_EOL; // 3.1415926535898
    echo M_PI, PHP_EOL; // 3.1415926535898
    ?>

# pow

(PHP 4, PHP 5, PHP 7, PHP 8)

pow — Expressão exponencial

### Descrição

function pow(mixed `$num`, mixed `$exponent`): int|float|object

Retorna `num` elevado à porência de `exponent`.

> Nota:

> É possível usar o operador ** no lugar desta função.

### Parâmetros

`num`

  A base a ser usada

`exponent`

  O expoente

### Valor Retornado

`num` elevado à potência de `exponent`. Se ambos os valores forem inteiros não negativos e o resultado puder ser representado como um inteiro, o resultado será retornado com o tipo int, caso contrário será retornado como um float.

Extensões do PHP podem substituir o comportamento desta operação e podem fazer com que ela retorne um objeto.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Elevar `0` a um `exponent` negativo agora foi descontinuado.

### Exemplos

Exemplo #1 Alguns exemplos de pow()

    <?php

    var_dump(pow(2, 8)); // int(256)
    echo pow(-1, 20), PHP_EOL; // 1
    echo pow(0, 0), PHP_EOL; // 1
    echo pow(10, -1), PHP_EOL; // 0.1

    echo pow(-1, 5.5), PHP_EOL; // NAN
    ?>

Exemplo #2 Exemplos de pow() com objeto da extensão GMP

    <?php
    var_dump(pow(new GMP("3"), new GMP("2"))); // object(GMP)
    ?>

### Notas

> Nota:

> Esta função converterá todas as entradas para números, mesmo valores não escalares, o que pode levar a resultados estranhos.

### Veja Também

- Operador de exponenciação `**`
- fpow() - Eleva um número à potência de outro, de acordo com a IEEE 754
- exp() - Calcula o expoente de e
- sqrt() - Raiz quadrada
- bcpow() - Eleva um número de precisão arbitrária a outro
- gmp_pow() - Elevar o número a uma potência

# rad2deg

(PHP 4, PHP 5, PHP 7, PHP 8)

rad2deg — Converte o número em radianos para o equivalente em graus

### Descrição

function rad2deg(float `$num`): float

Esta função converte `num` de radianos para graus.

### Parâmetros

`num`

  Um valor em radianos

### Valor Retornado

O equivalente de `num` em graus

### Exemplos

Exemplo #1 Exemplo de rad2deg()

    <?php

    echo rad2deg(M_PI_4); // 45

    ?>

### Veja Também

- deg2rad() - Converte o número em graus para o equivalente em radianos

# round

(PHP 4, PHP 5, PHP 7, PHP 8)

round — Arredonda um float

### Descrição

function round(int|float `$num`, int `$precision` = 0, int|RoundingMode `$mode` = `RoundingMode::HalfAwayFromZero`): float

Retorna um valor arredondado de `num` com a precisão especificada em `precision` (número de dígitos depois do ponto decimal). `precision` também pode ser negativo ou zero (padrão).

### Parâmetros

`num`

  Valor a ser arredondado.

`precision`

  O número opcional de dígitos decimais para arredondar.

  Se `precision` for positivo, `num` será arredondado para `precision` de dígitos significativos depois do ponto decimal.

  Se `precision` for negativo, `num` será arredondado para `precision` de dígitos significativos depois do ponto decimal, isto é: o múltiplo mais próximo de `pow(10, -$precision)`, por exemplo: para um `precision` de -1 `num` é arredondado para dezenas, para um `precision` de -2 para centenas, etc.

`mode`

  Use RoundingMode ou uma das seguintes constantes a seguir para especificar o modo com o qual o arredondamento ocorre.

  Constantes | Descrição
  --- | ---
  `PHP_ROUND_HALF_UP` | Arredonda `num` para longe de zero quando ele está na metade do caminho, tornando 1.5 em 2 e -1.5 em -2.
  `PHP_ROUND_HALF_DOWN` | Arredonda `num` na direção de zero quando ele está na metade do caminho, tornando 1.5 em 1 e -1.5 em -1.
  `PHP_ROUND_HALF_EVEN` | Arredonda `num` em direção ao valor par mais próximo quando ele está na metade do caminho, tornando ambos 1.5 e 2.5 em 2.
  `PHP_ROUND_HALF_ODD` | Arredonda `num` em direção ao valor ímpar mais próximo quando ele está na metade do caminho, tornando 1.5 em 1 e 2.5 em 3.

  No entanto, observe que alguns modos novos adicionados existem apenas em RoundingMode.

### Valor Retornado

O valor arredondado para `precision` fornecido como um float.

### Erros/Exceções

A função lança uma exceção ValueError se `mode` for inválido. Antes do PHP 8.4.0, um modo inválido seria considerado, silenciosamente, como o padrão `PHP_ROUND_HALF_UP`.

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Quatro novos modos de arredondamento foram adicionados.
8.4.0 | Agora lança uma exceção ValueError se `mode` for inválido.
8.0.0 | `num` não mais aceita objetos internos que suportam conversões numéricas.

### Exemplos

Exemplo #1 Exemplos de round()

    <?php
    var_dump(round(3.4));
    var_dump(round(3.5));
    var_dump(round(3.6));
    var_dump(round(3.6, 0));
    var_dump(round(5.045, 2));
    var_dump(round(5.055, 2));
    var_dump(round(345, -2));
    var_dump(round(345, -3));
    var_dump(round(678, -2));
    var_dump(round(678, -3));
    ?>

O exemplo acima produzirá:

    float(3)
    float(4)
    float(4)
    float(4)
    float(5.05)
    float(5.06)
    float(300)
    float(0)
    float(700)
    float(1000)

Exemplo #2 Como `precision` afeta um float

    <?php
    $numero = 135.79;

    var_dump(round($numero, 3));
    var_dump(round($numero, 2));
    var_dump(round($numero, 1));
    var_dump(round($numero, 0));
    var_dump(round($numero, -1));
    var_dump(round($numero, -2));
    var_dump(round($numero, -3));
    ?>

O exemplo acima produzirá:

    float(135.79)
    float(135.79)
    float(135.8)
    float(136)
    float(140)
    float(100)
    float(0)

Exemplo #3 Exemplos de `mode`

    <?php
    echo 'Modos de arredondamento com 9.5' . PHP_EOL;
    var_dump(round(9.5, 0, PHP_ROUND_HALF_UP));
    var_dump(round(9.5, 0, PHP_ROUND_HALF_DOWN));
    var_dump(round(9.5, 0, PHP_ROUND_HALF_EVEN));
    var_dump(round(9.5, 0, PHP_ROUND_HALF_ODD));

    echo PHP_EOL;
    echo 'Modos de arredondamento com 8.5' . PHP_EOL;
    var_dump(round(8.5, 0, PHP_ROUND_HALF_UP));
    var_dump(round(8.5, 0, PHP_ROUND_HALF_DOWN));
    var_dump(round(8.5, 0, PHP_ROUND_HALF_EVEN));
    var_dump(round(8.5, 0, PHP_ROUND_HALF_ODD));
    ?>

O exemplo acima produzirá:

    Modos de arredondamento com 9.5
    float(10)
    float(9)
    float(10)
    float(9)

    Modos de arredondamento com 8.5
    float(9)
    float(8)
    float(8)
    float(9)

Exemplo #4 Exemplos de `mode` com `precision`

    <?php
    echo 'Usando PHP_ROUND_HALF_UP com precisão decimal de 1 dígito' . PHP_EOL;
    var_dump(round( 1.55, 1, PHP_ROUND_HALF_UP));
    var_dump(round(-1.55, 1, PHP_ROUND_HALF_UP));

    echo PHP_EOL;
    echo 'Usando PHP_ROUND_HALF_DOWN com precisão decimal de 1 dígito' . PHP_EOL;
    var_dump(round( 1.55, 1, PHP_ROUND_HALF_DOWN));
    var_dump(round(-1.55, 1, PHP_ROUND_HALF_DOWN));

    echo PHP_EOL;
    echo 'Usando PHP_ROUND_HALF_EVEN com precisão decimal de 1 dígito' . PHP_EOL;
    var_dump(round( 1.55, 1, PHP_ROUND_HALF_EVEN));
    var_dump(round(-1.55, 1, PHP_ROUND_HALF_EVEN));

    echo PHP_EOL;
    echo 'Usando PHP_ROUND_HALF_ODD com precisão decimal de 1 dígito' . PHP_EOL;
    var_dump(round( 1.55, 1, PHP_ROUND_HALF_ODD));
    var_dump(round(-1.55, 1, PHP_ROUND_HALF_ODD));
    ?>

O exemplo acima produzirá:

    Usando PHP_ROUND_HALF_UP com precisão decimal de 1 digito
    float(1.6)
    float(-1.6)

    Usando PHP_ROUND_HALF_DOWN com precisão decimal de 1 digito
    float(1.5)
    float(-1.5)

    Usando PHP_ROUND_HALF_EVEN com precisão decimal de 1 digito
    float(1.6)
    float(-1.6)

    Usando PHP_ROUND_HALF_ODD com precisão decimal de 1 digito
    float(1.5)
    float(-1.5)

Exemplo #5 Exemplo de uso de RoundingMode

    <?php
    foreach (RoundingMode::cases() as $mode) {
        foreach ([
            8.5,
            9.5,
            -3.5,
        ] as $number) {
            printf("%-17s: %+.17g -> %+.17g\n", $mode->name, $number, round($number, 0, $mode));
        }
        echo "\n";
    }
    ?>

O exemplo acima produzirá:

    HalfAwayFromZero : +8.5 -> +9
    HalfAwayFromZero : +9.5 -> +10
    HalfAwayFromZero : -3.5 -> -4

    HalfTowardsZero  : +8.5 -> +8
    HalfTowardsZero  : +9.5 -> +9
    HalfTowardsZero  : -3.5 -> -3

    HalfEven         : +8.5 -> +8
    HalfEven         : +9.5 -> +10
    HalfEven         : -3.5 -> -4

    HalfOdd          : +8.5 -> +9
    HalfOdd          : +9.5 -> +9
    HalfOdd          : -3.5 -> -3

    TowardsZero      : +8.5 -> +8
    TowardsZero      : +9.5 -> +9
    TowardsZero      : -3.5 -> -3

    AwayFromZero     : +8.5 -> +9
    AwayFromZero     : +9.5 -> +10
    AwayFromZero     : -3.5 -> -4

    NegativeInfinity : +8.5 -> +8
    NegativeInfinity : +9.5 -> +9
    NegativeInfinity : -3.5 -> -4

    PositiveInfinity : +8.5 -> +9
    PositiveInfinity : +9.5 -> +10
    PositiveInfinity : -3.5 -> -3

### Veja Também

- ceil() - Arredonda frações para cima
- floor() - Arredonda frações para baixo
- number_format() - Formata um número com milhares agrupados

# sin

(PHP 4, PHP 5, PHP 7, PHP 8)

sin — Seno

### Descrição

function sin(float `$num`): float

sin() retorna o seno do parâmetro `num`. O argumento `num` deve estar em radianos.

### Parâmetros

`num`

  O valor em radianos

### Valor Retornado

O seno do `num`

### Exemplos

Exemplo #1 Exemplo da sin()

    <?php
    // Precisão depende da diretiva precision
    echo sin(deg2rad(60)), PHP_EOL;  //  0.866025403 ...
    echo sin(60), PHP_EOL;           // -0.304810621 ...
    ?>

### Veja Também

- asin() - Arco seno
- sinh() - Seno hiperbólico
- cos() - Cosseno
- tan() - Tangente
- deg2rad() - Converte o número em graus para o equivalente em radianos

# sinh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

sinh — Seno hiperbólico

### Descrição

function sinh(float `$num`): float

Retorna o seno hiperbólico de `num`, definido como `(exp($num) - exp(-$num))/2`.

### Parâmetros

`num`

  O argumento para processar

### Valor Retornado

O seno hiperbólico de `num`

### Veja Também

- sin() - Seno
- asinh() - Arco seno hiperbólico
- cosh() - Cosseno hiperbólico
- tanh() - Tangente hiperbólica

# sqrt

(PHP 4, PHP 5, PHP 7, PHP 8)

sqrt — Raiz quadrada

### Descrição

function sqrt(float `$num`): float

Retorna a raiz quadrada de `num`.

### Parâmetros

`num`

  O argumento para processar

### Valor Retornado

A raiz quadrada de `num` ou o valor especial `NAN` para números negativos.

### Exemplos

Exemplo #1 Exemplo da sqrt()

    <?php
    // Precisão depende de sua diretiva precision
    echo sqrt(9), PHP_EOL; // 3
    echo sqrt(10), PHP_EOL; // 3.16227766 ...
    ?>

### Veja Também

- pow() - Expressão exponencial
- `M_SQRTPI` - `sqrt(pi)`
- `M_2_SQRTPI` - `2/sqrt(pi)`
- `M_SQRT2` - `sqrt(2)`
- `M_SQRT3` - `sqrt(3)`
- `M_SQRT1_2` - `1/sqrt(2)`

# tan

(PHP 4, PHP 5, PHP 7, PHP 8)

tan — Tangente

### Descrição

function tan(float `$num`): float

tan() retorna a tangente do parâmetro `num`. O argumento `num` deve estar em radianos.

### Parâmetros

`num`

  O argumento para processar em radianos

### Valor Retornado

A tangente de `num`

### Exemplos

Exemplo #1 Exemplo da tan()

    <?php

    echo tan(M_PI_4); // 1

    ?>

### Veja Também

- atan() - Arco tangente
- atan2() - Arco tangente de duas variáveis
- sin() - Seno
- cos() - Cosseno
- tanh() - Tangente hiperbólica
- deg2rad() - Converte o número em graus para o equivalente em radianos

# tanh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

tanh — Tangente hiperbólica

### Descrição

function tanh(float `$num`): float

Retorna a tangente hiperbólica de `num`, definida como `sinh($num)/cosh($num)`.

### Parâmetros

`num`

  O argumento para processar

### Valor Retornado

A tangente hiperbólica de `num`

### Veja Também

- tan() - Tangente
- atanh() - Arco tangente hiperbólico
- sinh() - Seno hiperbólico
- cosh() - Cosseno hiperbólico

## Índice

- abs — Valor absoluto
- acos — Arco cosseno
- acosh — Arco cosseno hiperbólico
- asin — Arco seno
- asinh — Arco seno hiperbólico
- atan — Arco tangente
- atan2 — Arco tangente de duas variáveis
- atanh — Arco tangente hiperbólico
- base_convert — Converte um número entre bases arbitrárias
- bindec — Binário para decimal
- ceil — Arredonda frações para cima
- cos — Cosseno
- cosh — Cosseno hiperbólico
- decbin — Decimal para binário
- dechex — Decimal para hexadecimal
- decoct — Decimal para octal
- deg2rad — Converte o número em graus para o equivalente em radianos
- exp — Calcula o expoente de e
- expm1 — Retorna exp($num) - 1, computado de forma precisa mesmo quando o valor do número está próximo de zero.
- fdiv — Divide dois números de acordo com a IEEE 754
- floor — Arredonda frações para baixo
- fmod — Retorna o resto (módulo) em ponto flutuante da divisão dos argumentos
- fpow — Eleva um número à potência de outro, de acordo com a IEEE 754
- hexdec — Hexadecimal para decimal
- hypot — Calcula o comprimento da hipotenusa de triângulo retângulo
- intdiv — Divisão de inteiros
- is_finite — Verifica se um float é finito
- is_infinite — Verifica se um float é infinito
- is_nan — Verifica se um float é NAN
- log — Logaritmo natural
- log10 — Logaritmo na base 10
- log1p — Retorna log(1 + número), calculado de forma que seja preciso mesmo quando o valor do número seja próximo de zero.
- max — Localiza o maior valor
- min — Encontra o menor valor
- octdec — Octal para decimal
- pi — Obtém o valor de pi
- pow — Expressão exponencial
- rad2deg — Converte o número em radianos para o equivalente em graus
- round — Arredonda um float
- sin — Seno
- sinh — Seno hiperbólico
- sqrt — Raiz quadrada
- tan — Tangente
- tanh — Tangente hiperbólica

- Constantes predefinidas
- RoundingMode — A enumeração RoundingMode
- Funções de Math
  - abs — Valor absoluto
  - acos — Arco cosseno
  - acosh — Arco cosseno hiperbólico
  - asin — Arco seno
  - asinh — Arco seno hiperbólico
  - atan — Arco tangente
  - atan2 — Arco tangente de duas variáveis
  - atanh — Arco tangente hiperbólico
  - base_convert — Converte um número entre bases arbitrárias
  - bindec — Binário para decimal
  - ceil — Arredonda frações para cima
  - cos — Cosseno
  - cosh — Cosseno hiperbólico
  - decbin — Decimal para binário
  - dechex — Decimal para hexadecimal
  - decoct — Decimal para octal
  - deg2rad — Converte o número em graus para o equivalente em radianos
  - exp — Calcula o expoente de e
  - expm1 — Retorna exp($num) - 1, computado de forma precisa mesmo quando o valor do número está próximo de zero.
  - fdiv — Divide dois números de acordo com a IEEE 754
  - floor — Arredonda frações para baixo
  - fmod — Retorna o resto (módulo) em ponto flutuante da divisão dos argumentos
  - fpow — Eleva um número à potência de outro, de acordo com a IEEE 754
  - hexdec — Hexadecimal para decimal
  - hypot — Calcula o comprimento da hipotenusa de triângulo retângulo
  - intdiv — Divisão de inteiros
  - is_finite — Verifica se um float é finito
  - is_infinite — Verifica se um float é infinito
  - is_nan — Verifica se um float é NAN
  - log — Logaritmo natural
  - log10 — Logaritmo na base 10
  - log1p — Retorna log(1 + número), calculado de forma que seja preciso mesmo quando o valor do número seja próximo de zero.
  - max — Localiza o maior valor
  - min — Encontra o menor valor
  - octdec — Octal para decimal
  - pi — Obtém o valor de pi
  - pow — Expressão exponencial
  - rad2deg — Converte o número em radianos para o equivalente em graus
  - round — Arredonda um float
  - sin — Seno
  - sinh — Seno hiperbólico
  - sqrt — Raiz quadrada
  - tan — Tangente
  - tanh — Tangente hiperbólica

# Estatísticas

# Introdução

Aviso

Esta extensão está sem manutenção.

Esta é a extensão Statistic. Ela contém algumas dezenas de funções úteis para cálculos estatísticos. É um encapsulador em torno de duas bibliotecas científicas a saber, DCDFLIB (Biblioteca de rotinas C para Função Distribuição Acumulada, Inversas e Outros Parâmetros) de B. Brown e J. Lavato e RANDLIB de Barry Brown, James Lavato e Kathy Russell. Inclui funções CD e PD.

# Instalação/Configuração

## Índice

- Dependências
- Instalação

## Dependências

Não são necessárias bibliotecas externas. A extensão vem com as bibliotecas utilizadas.

## Instalação

Esta extensão » PECL não é distribuída com o PHP.

Esta extensão é considerada sem manutenção e abandonada. No entanto, o código-fonte desta extensão ainda está disponível no SVN do PECL aqui: » https://pecl.php.net/package/stats.

Binários do Windows (arquivos DLL) para esta extensão PECL estão disponíveis no site do PECL.

# Funções de Statistic

# stats_absolute_deviation

(PECL stats >= 1.0.0)

stats_absolute_deviation — Retorna o desvio absoluto de um array de valores

### Descrição

function stats_absolute_deviation(array `$a`): float

Retorna o desvio absoluto dos valores em `a`.

### Parâmetros

`a`

  The input array

### Valor Retornado

Retorna o desvio absoluto dos valores em `a`, ou `false` se `a` estiver vazio ou não for um array.

# stats_cdf_beta

(PECL stats >= 1.0.0)

stats_cdf_beta — Calcula qualquer parâmetro da distribuição beta, dados os valores dos outros

### Descrição

function stats_cdf_beta(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Retorna a função distribuição acumulada, sua inversa ou um de seus parâmetros, da distribuição beta. Os tipos do valor de retorno e dos parâmetros (`par1`, `par2` e `par3`) são determinados por `which`.

A tabela a seguir lista o valor de retorno e os parâmetros em relação a `which`. FDA, x, alfa e beta denotam a função distribuição acumulada, o valor da variável aleatória e os parâmetros de forma da distribuição beta, respectivamente.

Valor de retorno e parâmetros
`which` | Valor de retorno | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | FDA | x | alfa | beta
2 | x | FDA | alfa | beta
3 | alfa | x | FDA | beta
4 | beta | x | FDA | alfa

### Parâmetros

`par1`

  O primeiro parâmetro

`par2`

  O segundo parâmetro

`par3`

  O terceiro parâmetro

`which`

  O sinalizador para determinar o que deve ser calculado

### Valor Retornado

Retorna FDA, x, alfa ou beta, determinado por `which`.

# stats_cdf_binomial

(PECL stats >= 1.0.0)

stats_cdf_binomial — Calcula qualquer parâmetro da distribuição binomial, dados os valores dos outros

### Descrição

function stats_cdf_binomial(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Retorna a função distribuição acumulada, sua inversa ou um de seus parâmetros da distribuição binomial. Os tipos do valor de retorno e dos parâmetros (`par1`, `par2` e `par3`) são determinados por `which`.

A tabela a seguir lista o valor de retorno e os parâmetros em relação a `which`. FDA, x, n e p denotam a função distribuição acumulada, o número de sucessos, o número de tentativas e a taxa de sucesso para cada tentativa, respectivamente.

Valor de retorno e parâmetros
`which` | Valor de retorno | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | FDA | x | n | p
2 | x | FDA | n | p
3 | n | x | FDA | p
4 | p | x | FDA | n

### Parâmetros

`par1`

  O primeiro parâmetro

`par2`

  O segundo parâmetro

`par3`

  O terceiro parâmetro

`which`

  O sinalizador para determinar o que deve ser calculado

### Valor Retornado

Retorna FDA, x, n ou p, determinado por `which`.

# stats_cdf_cauchy

(PECL stats >= 1.0.0)

stats_cdf_cauchy — Calcula qualquer parâmetro da distribuição de Cauchy, dados os valores dos outros

### Descrição

function stats_cdf_cauchy(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Retorna a função distribuição acumulada, sua inversa ou um de seus parâmetros, da distribuição de Cauchy. O tipo do valor de retorno e os parâmetros (`par1`, `par2` e `par3`) são determinados por `which`.

A tabela a seguir lista o valor de retorno e os parâmetros por `which`. FDA, x, x0 e gama denotam a função distribuição acumulada, o valor da variável aleatória, a localização e o parâmetro de escala da distribuição de Cauchy, respectivamente.

Valor de retorno e parâmetros
`which` | Valor de retorno | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | FDA | x | x0 | gama
2 | x | FDA | x0 | gama
3 | x0 | x | FDA | gama
4 | gama | x | FDA | x0

### Parâmetros

`par1`

  O primeiro parâmetro

`par2`

  O segundo parâmetro

`par3`

  O terceiro parâmetro

`which`

  O sinalizador para determinar o que deve ser calculado

### Valor Retornado

Retorna FDA, x, x0 ou gamma, determinado por `which`.

# stats_cdf_chisquare

(PECL stats >= 1.0.0)

stats_cdf_chisquare — Calcula qualquer parâmetro da distribuição qui-quadrado, dados os valores dos outros

### Descrição

function stats_cdf_chisquare(float `$par1`, float `$par2`, int `$which`): float

Retorna a função distribuição acumulada, sua inversa ou um de seus parâmetros, da distribuição de qui-quadrado. O tipo do valor de retorno e os parâmetros (`par1` e `par2`) são determinados por `which`.

A tabela a seguir lista o valor de retorno e os parâmetros por `which`. FDA, x e k denotam a função distribuição acumulada, o valor da variável aleatória e o grau de liberdade da distribuição qui-quadrado, respectivamente.

Valor de retorno e parâmetros
`which` | Valor de retorno | `par1` | `par2`
--- | --- | --- | ---
1 | FDA | x | k
2 | x | FDA | k
3 | k | x | FDA

### Parâmetros

`par1`

  O primeiro parâmetro

`par2`

  O segundo parâmetro

`which`

  O sinalizador para determinar o que deve ser calculado

### Valor Retornado

Retorna FDA, x ou k, determinado por `which`.

# stats_cdf_exponential

(PECL stats >= 1.0.0)

stats_cdf_exponential — Calcula qualquer parâmetro da distribuição exponencial, dados os valores dos outros

### Descrição

function stats_cdf_exponential(float `$par1`, float `$par2`, int `$which`): float

Retorna a função distribuição acumulada, sua inversa ou um de seus parâmetros, da distribuição de exponencial. O tipo do valor de retorno e os parâmetros (`par1` e `par2`) são determinados por `which`.

A tabela a seguir lista o valor de retorno e os parâmetros por `which`. FDA, x e lambda denotam a função distribuição acumulada, o valor da variável aleatória e o parâmetro de taxa da distribuição exponencial, respectivamente.

Valor de retorno e parâmetros
`which` | Valor de retorno | `par1` | `par2`
--- | --- | --- | ---
1 | FDA | x | lambda
2 | x | FDA | lambda
3 | lambda | x | FDA

### Parâmetros

`par1`

  O primeiro parâmetro

`par2`

  O segundo parâmetro

`which`

  O sinalizador para determinar o que deve ser calculado

### Valor Retornado

Retorna FDA, x ou lambda, determinado por `which`.

# stats_cdf_f

(PECL stats >= 1.0.0)

stats_cdf_f — Calcula qualquer parâmetro da distribuição F, dados os valores dos outros

### Descrição

function stats_cdf_f(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Retorna a função distribuição acumulada, sua inversa ou um de seus parâmetros, da distribuição F. O tipo do valor de retorno e os parâmetros (`par1`, `par2` e `par3`) são determinados por `which`.

A tabela a seguir lista o valor de retorno e os parâmetros por `which`. FDA, x, d1 e d2 denotam a função distribuição acumulada, o valor da variável aleatória e o grau de liberdade da distribuição F, respectivamente.

Valor de retorno e parâmetros
`which` | Valor de retorno | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | FDA | x | d1 | d2
2 | x | FDA | d1 | d2
3 | d1 | x | FDA | d2
4 | d2 | x | FDA | d1

### Parâmetros

`par1`

  O primeiro parâmetro

`par2`

  O segundo parâmetro

`par3`

  O terceiro parâmetro

`which`

  O sinalizador para determinar o que deve ser calculado

### Valor Retornado

Retorna FDA, x, d1 ou d2, determinado por `which`.

# stats_cdf_gamma

(PECL stats >= 1.0.0)

stats_cdf_gamma — Calcula qualquer parâmetro da distribuição gama, dados os valores dos outros

### Descrição

function stats_cdf_gamma(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Retorna a função distribuição acumulada, sua inversa ou um de seus parâmetros, da distribuição gama. O tipo do valor de retorno e os parâmetros (`par1`, `par2` e `par3`) são determinados por `which`.

A tabela a seguir lista o valor de retorno e os parâmetros por `which`. FDA, x, k e teta denotam a função distribuição acumulada, o valor da variável aleatória e os parâmetros de forma e escala da distribuição gama, respectivamente.

Valor de retorno e parâmetros
`which` | Valor de retorno | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | FDA | x | k | teta
2 | x | FDA | k | teta
3 | k | x | FDA | teta
4 | teta | x | FDA | k

### Parâmetros

`par1`

  O primeiro parâmetro

`par2`

  O segundo parâmetro

`par3`

  O terceiro parâmetro

`which`

  O sinalizador para determinar o que deve ser calculado

### Valor Retornado

Retorna FDA, x, k ou teta, determinado por `which`.

# stats_cdf_laplace

(PECL stats >= 1.0.0)

stats_cdf_laplace — Calcula qualquer parâmetro da distribuição de Laplace, dados os valores dos outros

### Descrição

function stats_cdf_laplace(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Retorna a função distribuição acumulada, sua inversa ou um de seus parâmetros, da distribuição de Laplace. O tipo do valor de retorno e os parâmetros (`par1`, `par2` e `par3`) são determinados por `which`.

A tabela a seguir lista o valor de retorno e os parâmetros por `which`. FDA, x, mi e b denotam a função distribuição acumulada, o valor da variável aleatória e a localização e o parâmetro de escala da distribuição de Laplace, respectivamente.

Valor de retorno e parâmetros
`which` | Valor de retorno | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | FDA | x | mi | b
2 | x | FDA | mi | b
3 | mi | x | FDA | b
4 | b | x | FDA | mi

### Parâmetros

`par1`

  O primeiro parâmetro

`par2`

  O segundo parâmetro

`par3`

  O terceiro parâmetro

`which`

  O sinalizador para determinar o que deve ser calculado

### Valor Retornado

Retorna FDA, x, mi ou b, determinado por `which`.

# stats_cdf_logistic

(PECL stats >= 1.0.0)

stats_cdf_logistic — Calcula qualquer parâmetro da distribuição logística, dados os valores dos outros

### Descrição

function stats_cdf_logistic(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Retorna a função distribuição acumulada, sua inversa ou um de seus parâmetros, da distribuição logística. O tipo do valor de retorno e os parâmetros (`par1`, `par2` e `par3`) são determinados por `which`.

A tabela a seguir lista o valor de retorno e os parâmetros por `which`. FDA, x, mi e s denotam a função distribuição acumulada, o valor da variável aleatória e a localização e o parâmetro de escala da distribuição logística, respectivamente.

Valor de retorno e parâmetros
`which` | Valor de retorno | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | FDA | x | mi | s
2 | x | FDA | mi | s
3 | mi | x | FDA | s
4 | s | x | FDA | mi

### Parâmetros

`par1`

  O primeiro parâmetro

`par2`

  O segundo parâmetro

`par3`

  O terceiro parâmetro

`which`

  O sinalizador para determinar o que deve ser calculado

### Valor Retornado

Retorna FDA, x, mi ou s, determinado por `which`.

# stats_cdf_negative_binomial

(PECL stats >= 1.0.0)

stats_cdf_negative_binomial — Calcula qualquer parâmetro da distribuição binomial negativa, dados os valores dos outros

### Descrição

function stats_cdf_negative_binomial(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Retorna a função distribuição acumulada, sua inversa ou um de seus parâmetros, da distribuição binomial negativa. O tipo do valor de retorno e os parâmetros (`par1`, `par2` e `par3`) são determinados por `which`.

A tabela a seguir lista o valor de retorno e os parâmetros por `which`. FDA, x, r e p denotam a função distribuição acumulada, o número de falhas, o número de sucessos e a taxa de sucesso para cada tentativa, respectivamente.

Valor de retorno e parâmetros
`which` | Valor de retorno | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | FDA | x | r | p
2 | x | FDA | r | p
3 | r | x | FDA | p
4 | p | x | FDA | r

### Parâmetros

`par1`

  O primeiro parâmetro

`par2`

  O segundo parâmetro

`par3`

  O terceiro parâmetro

`which`

  O sinalizador para determinar o que deve ser calculado

### Valor Retornado

Retorna FDA, x, r ou p, determinado por `which`.

# stats_cdf_noncentral_chisquare

(PECL stats >= 1.0.0)

stats_cdf_noncentral_chisquare — Calcula qualquer parâmetro da distribuição qui-quadrado não centralizada, dados os valores dos outros

### Descrição

function stats_cdf_noncentral_chisquare(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Retorna a função distribuição acumulada, sua inversa ou um de seus parâmetros, da distribuição qui-quadrado não centralizada. O tipo do valor de retorno e os parâmetros (`par1`, `par2` e `par3`) são determinados por `which`.

A tabela a seguir lista o valor de retorno e os parâmetros por `which`. FDA, x, k e lambda denotam a função distribuição acumulada, o valor da variável aleatória, o grau de liberdade e o parâmetro de não centralidade da distribuição, respectivamente.

Valor de retorno e parâmetros
`which` | Valor de retorno | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | FDA | x | k | lambda
2 | x | FDA | k | lambda
3 | k | x | FDA | lambda
4 | lambda | x | FDA | k

### Parâmetros

`par1`

  O primeiro parâmetro

`par2`

  O segundo parâmetro

`par3`

  O terceiro parâmetro

`which`

  O sinalizador para determinar o que deve ser calculado

### Valor Retornado

Retorna FDA, x, k ou lambda, determinado por `which`.

# stats_cdf_noncentral_f

(PECL stats >= 1.0.0)

stats_cdf_noncentral_f — Calcula qualquer parâmetro da distribuição F não centralizada, dados os valores dos outros

### Descrição

function stats_cdf_noncentral_f(
float `$par1`,
float `$par2`,
float `$par3`,
float `$par4`,
int `$which`
): float

Retorna a função distribuição acumulada, sua inversa ou um de seus parâmetros, da distribuição F não centralizada. O tipo do valor de retorno e os parâmetros (`par1`, `par2`, `par3` e `par4`) são determinados por `which`.

A tabela a seguir lista o valor de retorno e os parâmetros por `which`. FDA, x, ni1, ni2 e lambda denotam a função distribuição acumulada, o valor da variável aleatória, o grau de liberdade e o parâmetro de não centralidade da distribuição, respectivamente.

Valor de retorno e parâmetros
`which` | Valor de retorno | `par1` | `par2` | `par3` | `par4`
--- | --- | --- | --- | --- | ---
1 | FDA | x | ni1 | ni2 | lambda
2 | x | FDA | ni1 | ni2 | lambda
3 | ni1 | x | FDA | ni2 | lambda
4 | ni2 | x | FDA | ni1 | lambda
5 | lambda | x | FDA | ni1 | ni2

### Parâmetros

`par1`

  O primeiro parâmetro

`par2`

  O segundo parâmetro

`par3`

  O terceiro parâmetro

`par4`

  The fourth parameter

`which`

  O sinalizador para determinar o que deve ser calculado

### Valor Retornado

Retorna FDA, x, ni1, ni2 ou lambda, determinado por `which`.

# stats_cdf_noncentral_t

(PECL stats >= 1.0.0)

stats_cdf_noncentral_t — Calcula qualquer parâmetro da distribuição t não centralizada e fornece valores para os outros

### Descrição

function stats_cdf_noncentral_t(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Retorna a função distribuição acumulada, sua inversa, ou um de seus parâmetros, da distribuição t não centralizada. O tipo do valor de retorno e os parâmetros (`par1`, `par2` e `par3`) são determinados por `which`.

A tabela a seguir lista o valor de retorno e os parâmetros por `which`. FDA, x, ni e mi denotam a função distribuição acumulada, o valor da variável aleatória, os graus de liberdade e o parâmetro de não centralidade da distribuição, respectivamente.

Valor de retorno e parâmetros
`which` | Valor de retorno | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | FDA | x | ni | mi
2 | x | FDA | ni | mi
3 | ni | x | FDA | mi
4 | mi | x | FDA | ni

### Parâmetros

`par1`

  O primeiro parâmetro

`par2`

  O segundo parâmetro

`par3`

  O terceiro parâmetro

`which`

  O sinalizador para determinar o que deve ser calculado

### Valor Retornado

Retorna FDA, x, ni ou mi, determinado por `which`.

# stats_cdf_normal

(PECL stats >= 1.0.0)

stats_cdf_normal — Calcula qualquer parâmetro da distribuição normal, dados os valores dos outros

### Descrição

function stats_cdf_normal(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Retorna a função distribuição acumulada, sua inversa ou um de seus parâmetros, da distribuição normal. O tipo do valor de retorno e os parâmetros (`par1`, `par2` e `par3`) são determinados por `which`.

A tabela a seguir lista o valor de retorno e os parâmetros por `which`. FDA, x, mu e sigma denotam a função distribuição acumulada, o valor da variável aleatória, a média e o desvio padrão da distribuição normal, respectivamente.

Valor de retorno e parâmetros
`which` | Valor de retorno | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | FDA | x | mi | sigma
2 | x | FDA | mi | sigma
3 | mi | x | FDA | sigma
4 | sigma | x | FDA | mi

### Parâmetros

`par1`

  O primeiro parâmetro

`par2`

  O segundo parâmetro

`par3`

  O terceiro parâmetro

`which`

  O sinalizador para determinar o que deve ser calculado

### Valor Retornado

Retorna FDA, x, mi ou sigma, determinado por `which`.

# stats_cdf_poisson

(PECL stats >= 1.0.0)

stats_cdf_poisson — Calcula qualquer parâmetro da distribuição de Poisson, dados os valores dos outros

### Descrição

function stats_cdf_poisson(float `$par1`, float `$par2`, int `$which`): float

Retorna a função distribuição acumulada, sua inversa ou um de seus parâmetros da distribuição de Poisson. O tipo do valor de retorno e dos parâmetros (`par1` e `par2`) são determinados por `which`.

A tabela a seguir lista o valor de retorno e os parâmetros por `which`. FDA, x e lambda denotam a função distribuição acumulada, o valor da variável aleatória e o parâmetro da distribuição de Poisson, respectivamente.

Valor de retorno e parâmetros
`which` | Valor de retorno | `par1` | `par2`
--- | --- | --- | ---
1 | FDA | x | lambda
2 | x | FDA | lambda
3 | lambda | x | FDA

### Parâmetros

`par1`

  O primeiro parâmetro

`par2`

  O segundo parâmetro

`which`

  O sinalizador para determinar o que deve ser calculado

### Valor Retornado

Retorna FDA, x ou lambda, determinado por `which`.

# stats_cdf_t

(PECL stats >= 1.0.0)

stats_cdf_t — Calcula qualquer parâmetro da distribuição t, dados os valores dos outros

### Descrição

function stats_cdf_t(float `$par1`, float `$par2`, int `$which`): float

Retorna a função distribuição acumulada, sua inversa ou um de seus parâmetros da distribuição t. O tipo do valor de retorno e dos parâmetros (`par1` e `par2`) são determinados por `which`.

A tabela a seguir lista o valor de retorno e os parâmetros por `which`. FDA, x e ni denotam a função distribuição acumulada, o valor da variável aleatória e os graus de liberdade da distribuição t, respectivamente.

Valor de retorno e parâmetros
`which` | Valor de retorno | `par1` | `par2`
--- | --- | --- | ---
1 | FDA | x | ni
2 | x | FDA | ni
3 | ni | x | FDA

### Parâmetros

`par1`

  O primeiro parâmetro

`par2`

  O segundo parâmetro

`which`

  O sinalizador para determinar o que deve ser calculado

### Valor Retornado

Retorna FDA, x ou ni, determinado por `which`.

# stats_cdf_uniform

(PECL stats >= 1.0.0)

stats_cdf_uniform — Calcula qualquer parâmetro da distribuição uniforme, dados os valores dos outros

### Descrição

function stats_cdf_uniform(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Retorna a função distribuição acumulada, sua inversa ou um de seus parâmetros, da distribuição uniforme. O tipo do valor de retorno e os parâmetros (`par1`, `par2` e `par3`) são determinados por `which`.

A tabela a seguir lista o valor de retorno e os parâmetros por `which`. FDA, x, a e b denotam a função distribuição acumulada, o valor da variável aleatória, o limite inferior e o limite superior da distribuição uniforme, respectivamente.

Valor de retorno e parâmetros
`which` | Valor de retorno | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | FDA | x | a | b
2 | x | FDA | a | b
3 | a | x | FDA | b
4 | b | x | FDA | a

### Parâmetros

`par1`

  O primeiro parâmetro

`par2`

  O segundo parâmetro

`par3`

  O terceiro parâmetro

`which`

  O sinalizador para determinar o que deve ser calculado

### Valor Retornado

Retorna FDA, x, a ou b, determinado por `which`.

# stats_cdf_weibull

(PECL stats >= 1.0.0)

stats_cdf_weibull — Calcula qualquer parâmetro da distribuição de Weibull, dados os valores dos outros

### Descrição

function stats_cdf_weibull(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Retorna a função distribuição acumulada, sua inversa ou um de seus parâmetros, da distribuição de Weibull. O tipo do valor de retorno e os parâmetros (`par1`, `par2` e `par3`) são determinados por `which`.

A tabela a seguir lista o valor de retorno e os parâmetros por `which`. FDA, x, k e lambda denotam a função distribuição acumulada, o valor da variável aleatória, a forma e o parâmetro de escala da distribuição Weibull, respectivamente.

Valor de retorno e parâmetros
`which` | Valor de retorno | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | FDA | x | k | lambda
2 | x | FDA | k | lambda
3 | k | x | FDA | lambda
4 | lambda | x | FDA | k

### Parâmetros

`par1`

  O primeiro parâmetro

`par2`

  O segundo parâmetro

`par3`

  O terceiro parâmetro

`which`

  O sinalizador para determinar o que deve ser calculado

### Valor Retornado

Retorna FDA, x, k ou lambda, determinado por `which`.

# stats_covariance

(PECL stats >= 1.0.0)

stats_covariance — Calcula a covariância de dois conjuntos de dados

### Descrição

function stats_covariance(array `$a`, array `$b`): float

Retorna a covariância de `a` e `b`.

### Parâmetros

`a`

  O primeiro array

`b`

  O segundo array

### Valor Retornado

Retorna a covariância de `a` e `b`, ou `false` em caso de falha.

# stats_dens_beta

(PECL stats >= 1.0.0)

stats_dens_beta — Função de densidade de probabilidade da distribuição beta

### Descrição

function stats_dens_beta(float `$x`, float `$a`, float `$b`): float

Retorna a densidade de probabilidade em `x`, onde a variável aleatória segue a distribuição beta cujos parâmetros de forma são `a` e `b`.

### Parâmetros

`x`

  O valor no qual a densidade de probabilidade é calculada

`a`

  O parâmetro de forma da distribuição

`b`

  O parâmetro de forma da distribuição

### Valor Retornado

A densidade de probabilidade em `x` ou `false` para falha.

# stats_dens_cauchy

(PECL stats >= 1.0.0)

stats_dens_cauchy — Função de densidade de probabilidade da distribuição de Cauchy

### Descrição

function stats_dens_cauchy(float `$x`, float `$ave`, float `$stdev`): float

Retorna a densidade de probabilidade em `x`, onde a variável aleatória segue a distribuição de Cauchy, cuja localização e escala são `ave` e `stdev`, respectivamente.

### Parâmetros

`x`

  O valor no qual a densidade de probabilidade é calculada

`ave`

  O parâmetro de localização da distribuição

`stdev`

  O parâmetro de escala da distribuição

### Valor Retornado

A densidade de probabilidade em `x` ou `false` para falha.

# stats_dens_chisquare

(PECL stats >= 1.0.0)

stats_dens_chisquare — Função de densidade de probabilidade da distribuição qui-quadrado

### Descrição

function stats_dens_chisquare(float `$x`, float `$dfr`): float

Retorna a densidade de probabilidade em `x`, onde a variável aleatória segue a distribuição qui-quadrado cujo grau de liberdade é `dfr`.

### Parâmetros

`x`

  O valor no qual a densidade de probabilidade é calculada

`dfr`

  O grau de liberdade da distribuição

### Valor Retornado

A densidade de probabilidade em `x` ou `false` para falha.

# stats_dens_exponential

(PECL stats >= 1.0.0)

stats_dens_exponential — Função de densidade de probabilidade da distribuição exponencial

### Descrição

function stats_dens_exponential(float `$x`, float `$scale`): float

Retorna a densidade de probabilidade em `x`, onde a variável aleatória segue a distribuição exponencial cuja escala é `scale`.

### Parâmetros

`x`

  O valor no qual a densidade de probabilidade é calculada

`scale`

  A escala da distribuição

### Valor Retornado

A densidade de probabilidade em `x` ou `false` para falha.

# stats_dens_f

(PECL stats >= 1.0.0)

stats_dens_f — Função de densidade de probabilidade da distribuição F

### Descrição

function stats_dens_f(float `$x`, float `$dfr1`, float `$dfr2`): float

Retorna a densidade de probabilidade em `x`, onde a variável aleatória segue a distribuição F cujos graus de liberdade são `dfr1` e `dfr2`.

### Parâmetros

`x`

  O valor no qual a densidade de probabilidade é calculada

`dfr1`

  O grau de liberdade da distribuição

`dfr2`

  O grau de liberdade da distribuição

### Valor Retornado

A densidade de probabilidade em `x` ou `false` para falha.

# stats_dens_gamma

(PECL stats >= 1.0.0)

stats_dens_gamma — Função de densidade de probabilidade da distribuição gama

### Descrição

function stats_dens_gamma(float `$x`, float `$shape`, float `$scale`): float

Retorna a densidade de probabilidade em `x`, onde a variável aleatória segue a distribuição gama cujo parâmetro de forma é `shape` e o parâmetro de escala é `scale`.

### Parâmetros

`x`

  O valor no qual a densidade de probabilidade é calculada

`shape`

  O parâmetro de forma da distribuição

`scale`

  O parâmetro de escala da distribuição

### Valor Retornado

A densidade de probabilidade em `x` ou `false` para falha.

# stats_dens_laplace

(PECL stats >= 1.0.0)

stats_dens_laplace — Função de densidade de probabilidade da distribuição de Laplace

### Descrição

function stats_dens_laplace(float `$x`, float `$ave`, float `$stdev`): float

Retorna a densidade de probabilidade em `x`, onde a variável aleatória segue a distribuição de Laplace, cujo parâmetro de localização é `ave` e o parâmetro de escala é `stdev`.

### Parâmetros

`x`

  O valor no qual a densidade de probabilidade é calculada

`ave`

  O parâmetro de localização da distribuição

`stdev`

  O parâmetro de forma da distribuição

### Valor Retornado

A densidade de probabilidade em `x` ou `false` para falha.

# stats_dens_logistic

(PECL stats >= 1.0.0)

stats_dens_logistic — Função de densidade de probabilidade da distribuição logística

### Descrição

function stats_dens_logistic(float `$x`, float `$ave`, float `$stdev`): float

Retorna a densidade de probabilidade em `x`, onde a variável aleatória segue a distribuição logística cujo parâmetro de localização é `ave` e o parâmetro de escala é `stdev`.

### Parâmetros

`x`

  O valor no qual a densidade de probabilidade é calculada

`ave`

  O parâmetro de localização da distribuição

`stdev`

  O parâmetro de forma da distribuição

### Valor Retornado

A densidade de probabilidade em `x` ou `false` para falha.

# stats_dens_normal

(PECL stats >= 1.0.0)

stats_dens_normal — Função de densidade de probabilidade da distribuição normal

### Descrição

function stats_dens_normal(float `$x`, float `$ave`, float `$stdev`): float

Retorna a densidade de probabilidade em `x`, onde a variável aleatória segue a distribuição normal, cuja média é `ave` e o desvio padrão é `stdev`.

### Parâmetros

`x`

  O valor no qual a densidade de probabilidade é calculada

`ave`

  A média da distribuição

`stdev`

  O desvio padrão da distribuição

### Valor Retornado

A densidade de probabilidade em `x` ou `false` para falha.

# stats_dens_pmf_binomial

(PECL stats >= 1.0.0)

stats_dens_pmf_binomial — Função de massa de probabilidade da distribuição binomial

### Descrição

function stats_dens_pmf_binomial(float `$x`, float `$n`, float `$pi`): float

Retorna a massa de probabilidade em `x`, onde a variável aleatória segue a distribuição binomial cujo número de tentativas é `n` e a taxa de sucesso é `pi`.

### Parâmetros

`x`

  O valor no qual a massa de probabilidade é calculada

`n`

  O número de tentativas da distribuição

`pi`

  A taxa de sucesso da distribuição

### Valor Retornado

A massa de probabilidade em `x` ou `false` para falha.

# stats_dens_pmf_hypergeometric

(PECL stats >= 1.0.0)

stats_dens_pmf_hypergeometric — Função de massa de probabilidade da distribuição hipergeométrica

### Descrição

function stats_dens_pmf_hypergeometric(
float `$n1`,
float `$n2`,
float `$N1`,
float `$N2`
): float

Retorna a massa de probabilidade em `n1`, onde a variável aleatória segue a distribuição hipergeométrica cujo número de falhas é `n2`, o número de amostras de sucesso é `N1`, e o número de amostras de falhas é `N2`.

### Parâmetros

`n1`

  O número de sucessos em que a massa de probabilidade é calculada

`n2`

  O número de falhas da distribuição

`N1`

  O número de amostras de sucesso da distribuição

`N2`

  O número de amostras de falha da distribuição

### Valor Retornado

A massa de probabilidade em `n1` ou `false` para falha.

# stats_dens_pmf_negative_binomial

(PECL stats >= 1.0.0)

stats_dens_pmf_negative_binomial — Função de massa de probabilidade da distribuição binomial negativa

### Descrição

function stats_dens_pmf_negative_binomial(float `$x`, float `$n`, float `$pi`): float

Retorna a massa de probabilidade em `x`, onde a variável aleatória segue a distribuição binomial negativa, da qual o número de sucessos é `n` e a taxa de sucesso é `pi`.

### Parâmetros

`x`

  O valor no qual a massa de probabilidade é calculada

`n`

  O número do sucesso da distribuição

`pi`

  A taxa de sucesso da distribuição

### Valor Retornado

A massa de probabilidade em `x` ou `false` para falha.

# stats_dens_pmf_poisson

(PECL stats >= 1.0.0)

stats_dens_pmf_poisson — Função de massa de probabilidade da distribuição de Poisson

### Descrição

function stats_dens_pmf_poisson(float `$x`, float `$lb`): float

Retorna a massa de probabilidade em `x`, onde a variável aleatória segue a distribuição de Poisson cujo parâmetro é `lb`.

### Parâmetros

`x`

  O valor no qual a massa de probabilidade é calculada

`lb`

  O parâmetro da distribuição de Poisson

### Valor Retornado

A massa de probabilidade em `x` ou `false` para falha.

# stats_dens_t

(PECL stats >= 1.0.0)

stats_dens_t — Função de densidade de probabilidade da distribuição t

### Descrição

function stats_dens_t(float `$x`, float `$dfr`): float

Retorna a densidade de probabilidade em `x`, onde a variável aleatória segue a distribuição t cujo grau de liberdade é `dfr`.

### Parâmetros

`x`

  O valor no qual a densidade de probabilidade é calculada

`dfr`

  O grau de liberdade da distribuição

### Valor Retornado

A densidade de probabilidade em `x` ou `false` para falha.

# stats_dens_uniform

(PECL stats >= 1.0.0)

stats_dens_uniform — Função de densidade de probabilidade da distribuição uniforme

### Descrição

function stats_dens_uniform(float `$x`, float `$a`, float `$b`): float

Retorna a densidade de probabilidade em `x`, onde a variável aleatória segue a distribuição uniforme cujo limite inferior é `a` e o limite superior é `b`.

### Parâmetros

`x`

  O valor no qual a densidade de probabilidade é calculada

`a`

  O limite inferior da distribuição

`b`

  O limite superior da distribuição

### Valor Retornado

A densidade de probabilidade em `x` ou `false` para falha.

# stats_dens_weibull

(PECL stats >= 1.0.0)

stats_dens_weibull — Função de densidade de probabilidade da distribuição Weibull

### Descrição

function stats_dens_weibull(float `$x`, float `$a`, float `$b`): float

Retorna a densidade de probabilidade em `x`, onde a variável aleatória segue a distribuição Weibull, cujo parâmetro de forma é `a` e o parâmetro de escala é `b`.

### Parâmetros

`x`

  O valor no qual a densidade de probabilidade é calculada

`a`

  O parâmetro de forma da distribuição

`b`

  O parâmetro de escala da distribuição

### Valor Retornado

A densidade de probabilidade em `x` ou `false` para falha.

# stats_harmonic_mean

(PECL stats >= 1.0.0)

stats_harmonic_mean — Retorna a média harmônica de um array de valores

### Descrição

function stats_harmonic_mean(array `$a`): number

Retorna a média harmônica dos valores em `a`.

### Parâmetros

`a`

  O array de entrada

### Valor Retornado

Retorna a média harmônica dos valores em `a`, ou `false` se `a` estiver vazio ou não for um array.

# stats_kurtosis

(PECL stats >= 1.0.0)

stats_kurtosis — Calcula a curtose dos dados no array

### Descrição

function stats_kurtosis(array `$a`): float

Retorna a curtose dos valores em `a`.

### Parâmetros

`a`

  O array de entrada

### Valor Retornado

Retorna a curtose dos valores em `a`, ou `false` se `a` estiver vazio ou não for um array.

# stats_rand_gen_beta

(PECL stats >= 1.0.0)

stats_rand_gen_beta — Gera um desvio aleatório da distribuição beta

### Descrição

function stats_rand_gen_beta(float `$a`, float `$b`): float

Retorna um desvio aleatório da distribuição beta com os parâmetros A e B. A densidade de beta é x^(a-1) * (1-x)^(b-1) / B(a,b) para 0 < x < 1. Método por R. C. H. Cheng.

### Parâmetros

`a`

  O parâmetro de forma da distribuição beta

`b`

  O parâmetro de forma da distribuição beta

### Valor Retornado

Um desvio aleatório

# stats_rand_gen_chisquare

(PECL stats >= 1.0.0)

stats_rand_gen_chisquare — Gera um desvio aleatório da distribuição qui-quadrado

### Descrição

function stats_rand_gen_chisquare(float `$df`): float

Retorna um desvio aleatório da distribuição qui-quadrado onde os graus de liberdade são `df`.

### Parâmetros

`df`

  Os graus de liberdade

### Valor Retornado

Um desvio aleatório

# stats_rand_gen_exponential

(PECL stats >= 1.0.0)

stats_rand_gen_exponential — Gera um desvio aleatório da distribuição exponencial

### Descrição

function stats_rand_gen_exponential(float `$av`): float

Retorna um desvio aleatório da distribuição exponencial da qual a escala é `av`.

### Parâmetros

`av`

  O parâmetro de escala

### Valor Retornado

Um desvio aleatório

# stats_rand_gen_f

(PECL stats >= 1.0.0)

stats_rand_gen_f — Gera um desvio aleatório da distribuição F

### Descrição

function stats_rand_gen_f(float `$dfn`, float `$dfd`): float

Gera um desvio aleatório da distribuição F (razão de variância) com graus de liberdade "dfn" no numerador e graus de liberdade "dfd" no denominador. Método: gera diretamente a razão das variáveis ​​qui-quadrado.

### Parâmetros

`dfn`

  Os graus de liberdade no numerador

`dfd`

  Os graus de liberdade no denominador

### Valor Retornado

Um desvio aleatório

# stats_rand_gen_funiform

(PECL stats >= 1.0.0)

stats_rand_gen_funiform — Gera um float uniforme entre o limite inferior (exclusive) e superior (exclusive)

### Descrição

function stats_rand_gen_funiform(float `$low`, float `$high`): float

Retorna um desvio aleatório da distribuição uniforme entre `low` e `high`.

### Parâmetros

`low`

  O limite inferior (exclusive)

`high`

  O limite superior (exclusive)

### Valor Retornado

Um desvio aleatório

# stats_rand_gen_gamma

(PECL stats >= 1.0.0)

stats_rand_gen_gamma — Gera um desvio aleatório da distribuição gama

### Descrição

function stats_rand_gen_gamma(float `$a`, float `$r`): float

Gera um desvio aleatório da distribuição gama cuja densidade é (A**R)/Gama(R) * X**(R-1) * Exp(-A*X).

### Parâmetros

`a`

  Parâmetro de localização da distribuição gama (`a` > 0).

`r`

  Parâmetro de forma da distribuição gama (`r` > 0).

### Valor Retornado

Um desvio aleatório

# stats_rand_gen_ibinomial

(PECL stats >= 1.0.0)

stats_rand_gen_ibinomial — Gera um desvio aleatório da distribuição binomial

### Descrição

function stats_rand_gen_ibinomial(int `$n`, float `$pp`): int

Retorna um desvio aleatório da distribuição binomial cujo número de tentativas é `n` e cuja probabilidade de um evento em cada tentativa é `pp`.

### Parâmetros

`n`

  O número de tentativas

`pp`

  A probabilidade de um evento em cada tentativa

### Valor Retornado

Um desvio aleatório

# stats_rand_gen_ibinomial_negative

(PECL stats >= 1.0.0)

stats_rand_gen_ibinomial_negative — Gera um desvio aleatório da distribuição binomial negativa

### Descrição

function stats_rand_gen_ibinomial_negative(int `$n`, float `$p`): int

Retorna um desvio aleatório de uma distribuição binomial negativa onde o número de sucessos é `n` e a taxa de sucesso é `p`.

### Parâmetros

`n`

  O número do sucessos

`p`

  A taxa de sucesso

### Valor Retornado

Um desvio aleatório, que é o número de falhas.

# stats_rand_gen_int

(PECL stats >= 1.0.0)

stats_rand_gen_int — Gera um inteiro aleatório entre 1 e 2147483562

### Descrição

function stats_rand_gen_int(): int

Retorna um inteiro aleatório entre 1 e 2147483562

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um inteiro aleatório

# stats_rand_gen_ipoisson

(PECL stats >= 1.0.0)

stats_rand_gen_ipoisson — Gera um único desvio aleatório de uma distribuição de Poisson

### Descrição

function stats_rand_gen_ipoisson(float `$mu`): int

Retorna um desvio aleatório da distribuição de Poisson com parâmetro `mu`.

### Parâmetros

`mu`

  O parâmetro da distribuição de Poisson

### Valor Retornado

Um desvio aleatório

# stats_rand_gen_iuniform

(PECL stats >= 1.0.0)

stats_rand_gen_iuniform — Gera inteiros distribuídos uniformemente entre um número inferior (inclusive) e um superior (inclusive)

### Descrição

function stats_rand_gen_iuniform(int `$low`, int `$high`): int

Retorna um inteiro aleatório da distribuição uniforme discreta entre `low` (inclusive) e `high` (inclusive).

### Parâmetros

`low`

  O limite inferior

`high`

  O limite superior

### Valor Retornado

Um inteiro aleatório

# stats_rand_gen_noncentral_chisquare

(PECL stats >= 1.0.0)

stats_rand_gen_noncentral_chisquare — Gera um desvio aleatório da distribuição qui-quadrado não centralizada

### Descrição

function stats_rand_gen_noncentral_chisquare(float `$df`, float `$xnonc`): float

Retorna um desvio aleatório da distribuição qui-quadrado não centralizada com graus de liberdade `df`, e parâmetro não central `xnonc`.

### Parâmetros

`df`

  Os graus de liberdade

`xnonc`

  O parâmetro de não centralidade

### Valor Retornado

Um desvio aleatório

# stats_rand_gen_noncentral_f

(PECL stats >= 1.0.0)

stats_rand_gen_noncentral_f — Gera um desvio aleatório da distribuição F não centralizada

### Descrição

function stats_rand_gen_noncentral_f(float `$dfn`, float `$dfd`, float `$xnonc`): float

Retorna um desvio aleatório da distribuição F não central, onde os graus de liberdade são `dfn` (numerador) e `dfd` (denominador), e o parâmetro de não centralidade é `xnonc`.

### Parâmetros

`dfn`

  Os graus de liberdade do numerador

`dfd`

  Os graus de liberdade do denominador

`xnonc`

  O parâmetro de não centralidade

### Valor Retornado

Um desvio aleatório

# stats_rand_gen_noncentral_t

(PECL stats >= 1.0.0)

stats_rand_gen_noncentral_t — Gera um único desvio aleatório de uma distribuição t não centralizada

### Descrição

function stats_rand_gen_noncentral_t(float `$df`, float `$xnonc`): float

Retorna um desvio aleatório da distribuição t não central com os graus de liberdade `df`, e o parâmetro de não centralidade `xnonc`.

### Parâmetros

`df`

  Os graus de liberdade

`xnonc`

  O parâmetro de não centralidade

### Valor Retornado

Um desvio aleatório

# stats_rand_gen_normal

(PECL stats >= 1.0.0)

stats_rand_gen_normal — Gera um único desvio aleatório de uma distribuição normal

### Descrição

function stats_rand_gen_normal(float `$av`, float `$sd`): float

Retorna um desvio aleatório da distribuição normal com média `av`, e desvio padrão `sd`.

### Parâmetros

`av`

  A média da distribuição normal

`sd`

  O desvio padrão da distribuição normal

### Valor Retornado

Um desvio aleatório

# stats_rand_gen_t

(PECL stats >= 1.0.0)

stats_rand_gen_t — Gera um único desvio aleatório de uma distribuição t

### Descrição

function stats_rand_gen_t(float `$df`): float

Retorna um desvio aleatório da distribuição t com os graus de liberdade `df`.

### Parâmetros

`df`

  Os graus de liberdade

### Valor Retornado

Um desvio aleatório

# stats_rand_get_seeds

(PECL stats >= 1.0.0)

stats_rand_get_seeds — Obtém os valores iniciais do gerador de números aleatórios

### Descrição

function stats_rand_get_seeds(): array

Retorna os valores de semente atuais do gerador de números aleatórios

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um array de dois inteiros.

# stats_rand_phrase_to_seeds

(PECL stats >= 1.0.0)

stats_rand_phrase_to_seeds — Gera duas sementes para o gerador de números aleatórios RGN

### Descrição

function stats_rand_phrase_to_seeds(string `$phrase`): array

Gera duas sementes para o gerador de números aleatórios a partir de uma frase no parâmetro `phrase`.

### Parâmetros

`phrase`

  A frase de entrada

### Valor Retornado

Retorna um array de dois inteiros.

# stats_rand_ranf

(PECL stats >= 1.0.0)

stats_rand_ranf — Gera um número de ponto flutuante aleatório entre 0 e 1

### Descrição

function stats_rand_ranf(): float

Retorna um número de ponto flutuante aleatório de uma distribuição uniforme entre 0 (exclusive) e 1 (exclusive).

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Um número de ponto flutuante aleatório

# stats_rand_setall

(PECL stats >= 1.0.0)

stats_rand_setall — Define valores de semente para o gerador aleatório

### Descrição

function stats_rand_setall(int `$iseed1`, int `$iseed2`): void

Define `iseed1` e `iseed2` como valores iniciais para o gerador aleatório usado em funções estatísticas.

### Parâmetros

`iseed1`

  O valor que é usado como semente aleatória

`iseed2`

  O valor que é usado como semente aleatória

### Valor Retornado

Nenhum valor é retornado.

# stats_skew

(PECL stats >= 1.0.0)

stats_skew — Calcula a assimetria dos dados no array

### Descrição

function stats_skew(array `$a`): float

Retorna a assimetria dos valores em `a`.

### Parâmetros

`a`

  O array de entrada

### Valor Retornado

Retorna a assimetria dos valores em `a`, ou `false` se `a` estiver vazio ou não for um array.

# stats_standard_deviation

(PECL stats >= 1.0.0)

stats_standard_deviation — Retorna o desvio padrão

### Descrição

function stats_standard_deviation(array `$a`, bool `$sample` = `false`): float

Retorna o desvio padrão dos valores em `a`.

### Parâmetros

`a`

  O array de dados para encontrar o desvio padrão. Observe que todos os valores do array serão convertidos para float.

`sample`

  Indica se `a` representa uma amostra da população; o padrão é `false`.

### Valor Retornado

Retorna o desvio padrão em caso de sucesso; `false` em caso de falha.

### Erros/Exceções

Gera uma `E_WARNING` quando há menos de 2 valores em `a`.

# stats_stat_binomial_coef

(PECL stats >= 1.0.0)

stats_stat_binomial_coef — Retorna um coeficiente binomial

### Descrição

function stats_stat_binomial_coef(int `$x`, int `$n`): float

Retorna o coeficiente binomial de `n` elementos e `x` escolhas.

### Parâmetros

`x`

  O número de escolhas do conjunto

`n`

  O número de elementos no conjunto

### Valor Retornado

Retorna o coeficiente binomial

# stats_stat_correlation

(PECL stats >= 1.0.0)

stats_stat_correlation — Retorna o coeficiente de correlação de Pearson de dois conjuntos de dados

### Descrição

function stats_stat_correlation(array `$arr1`, array `$arr2`): float

Retorna o coeficiente de correlação de Pearson entre `arr1` e `arr2`.

### Parâmetros

`arr1`

  O primeiro array

`arr2`

  O segundo array

### Valor Retornado

Retorna o coeficiente de correlação de Pearson entre `arr1` e `arr2`, ou `false` em caso de falha.

# stats_stat_factorial

(PECL stats >= 1.0.0)

stats_stat_factorial — Retorna o fatorial de um inteiro

### Descrição

function stats_stat_factorial(int `$n`): float

Retorna o fatorial de um inteiro, `n`.

### Parâmetros

`n`

  Um inteiro

### Valor Retornado

O fatorial de `n`.

# stats_stat_independent_t

(PECL stats >= 1.0.0)

stats_stat_independent_t — Retorna o valor t do teste t independente de duas amostras

### Descrição

function stats_stat_independent_t(array `$arr1`, array `$arr2`): float

Retorna o valor t do teste t independente de duas amostras entre `arr1` e `arr2`.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`arr1`

  O primeiro conjunto de valores

`arr2`

  O segundo conjunto de valores

### Valor Retornado

Retorna o valor t, ou `false` se houver falha.

# stats_stat_innerproduct

(PECL stats >= 1.0.0)

stats_stat_innerproduct — Retorna o produto interno de dois vetores

### Descrição

function stats_stat_innerproduct(array `$arr1`, array `$arr2`): float

Retorna o produto interno de `arr1` e `arr2`.

### Parâmetros

`arr1`

  O primeiro array

`arr2`

  O segundo array

### Valor Retornado

Retorna o produto interno de `arr1` e `arr2`, ou `false` em caso de falha.

# stats_stat_paired_t

(PECL stats >= 1.0.0)

stats_stat_paired_t — Retorna o valor t do teste t dependente para amostras pareadas

### Descrição

function stats_stat_paired_t(array `$arr1`, array `$arr2`): float

Retorna o valor t do teste t dependente para amostras pareadas `arr1` e `arr2`.

### Parâmetros

`arr1`

  As amostras do primeiro par

`arr2`

  As amostras do segundo par

### Valor Retornado

Retorna o valor t, ou `false` se houver falha.

# stats_stat_percentile

(PECL stats >= 1.0.0)

stats_stat_percentile — Retorna o valor do percentil

### Descrição

function stats_stat_percentile(array `$arr`, float `$perc`): float

Retorna o valor do `perc`-ésimo percentil do array `arr`.

### Parâmetros

`arr`

  O array de entrada

`perc`

  O percentil

### Valor Retornado

Retorna os valores de percentil do array de entrada.

# stats_stat_powersum

(PECL stats >= 1.0.0)

stats_stat_powersum — Retorna a soma de potências de um vetor

### Descrição

function stats_stat_powersum(array `$arr`, float `$power`): float

Retorna a soma da `power`-ésima potência de um vetor representado como um array `arr`.

### Parâmetros

`arr`

  O array de entrada

`power`

  A potência

### Valor Retornado

Retorna a soma de potências do array de entrada.

# stats_variance

(PECL stats >= 1.0.0)

stats_variance — Retorna a variância

### Descrição

function stats_variance(array `$a`, bool `$sample` = `false`): float

Retorna a variância dos valores em `a`.

### Parâmetros

`a`

  O array de dados para encontrar o desvio padrão. Observe que todos os valores do array serão convertidos para float.

`sample`

  Indica se `a` representa uma amostra da população; o padrão é `false`.

### Valor Retornado

Retorna a variância em caso de sucesso; `false` em caso de falha.

## Índice

- stats_absolute_deviation — Retorna o desvio absoluto de um array de valores
- stats_cdf_beta — Calcula qualquer parâmetro da distribuição beta, dados os valores dos outros
- stats_cdf_binomial — Calcula qualquer parâmetro da distribuição binomial, dados os valores dos outros
- stats_cdf_cauchy — Calcula qualquer parâmetro da distribuição de Cauchy, dados os valores dos outros
- stats_cdf_chisquare — Calcula qualquer parâmetro da distribuição qui-quadrado, dados os valores dos outros
- stats_cdf_exponential — Calcula qualquer parâmetro da distribuição exponencial, dados os valores dos outros
- stats_cdf_f — Calcula qualquer parâmetro da distribuição F, dados os valores dos outros
- stats_cdf_gamma — Calcula qualquer parâmetro da distribuição gama, dados os valores dos outros
- stats_cdf_laplace — Calcula qualquer parâmetro da distribuição de Laplace, dados os valores dos outros
- stats_cdf_logistic — Calcula qualquer parâmetro da distribuição logística, dados os valores dos outros
- stats_cdf_negative_binomial — Calcula qualquer parâmetro da distribuição binomial negativa, dados os valores dos outros
- stats_cdf_noncentral_chisquare — Calcula qualquer parâmetro da distribuição qui-quadrado não centralizada, dados os valores dos outros
- stats_cdf_noncentral_f — Calcula qualquer parâmetro da distribuição F não centralizada, dados os valores dos outros
- stats_cdf_noncentral_t — Calcula qualquer parâmetro da distribuição t não centralizada e fornece valores para os outros
- stats_cdf_normal — Calcula qualquer parâmetro da distribuição normal, dados os valores dos outros
- stats_cdf_poisson — Calcula qualquer parâmetro da distribuição de Poisson, dados os valores dos outros
- stats_cdf_t — Calcula qualquer parâmetro da distribuição t, dados os valores dos outros
- stats_cdf_uniform — Calcula qualquer parâmetro da distribuição uniforme, dados os valores dos outros
- stats_cdf_weibull — Calcula qualquer parâmetro da distribuição de Weibull, dados os valores dos outros
- stats_covariance — Calcula a covariância de dois conjuntos de dados
- stats_dens_beta — Função de densidade de probabilidade da distribuição beta
- stats_dens_cauchy — Função de densidade de probabilidade da distribuição de Cauchy
- stats_dens_chisquare — Função de densidade de probabilidade da distribuição qui-quadrado
- stats_dens_exponential — Função de densidade de probabilidade da distribuição exponencial
- stats_dens_f — Função de densidade de probabilidade da distribuição F
- stats_dens_gamma — Função de densidade de probabilidade da distribuição gama
- stats_dens_laplace — Função de densidade de probabilidade da distribuição de Laplace
- stats_dens_logistic — Função de densidade de probabilidade da distribuição logística
- stats_dens_normal — Função de densidade de probabilidade da distribuição normal
- stats_dens_pmf_binomial — Função de massa de probabilidade da distribuição binomial
- stats_dens_pmf_hypergeometric — Função de massa de probabilidade da distribuição hipergeométrica
- stats_dens_pmf_negative_binomial — Função de massa de probabilidade da distribuição binomial negativa
- stats_dens_pmf_poisson — Função de massa de probabilidade da distribuição de Poisson
- stats_dens_t — Função de densidade de probabilidade da distribuição t
- stats_dens_uniform — Função de densidade de probabilidade da distribuição uniforme
- stats_dens_weibull — Função de densidade de probabilidade da distribuição Weibull
- stats_harmonic_mean — Retorna a média harmônica de um array de valores
- stats_kurtosis — Calcula a curtose dos dados no array
- stats_rand_gen_beta — Gera um desvio aleatório da distribuição beta
- stats_rand_gen_chisquare — Gera um desvio aleatório da distribuição qui-quadrado
- stats_rand_gen_exponential — Gera um desvio aleatório da distribuição exponencial
- stats_rand_gen_f — Gera um desvio aleatório da distribuição F
- stats_rand_gen_funiform — Gera um float uniforme entre o limite inferior (exclusive) e superior (exclusive)
- stats_rand_gen_gamma — Gera um desvio aleatório da distribuição gama
- stats_rand_gen_ibinomial — Gera um desvio aleatório da distribuição binomial
- stats_rand_gen_ibinomial_negative — Gera um desvio aleatório da distribuição binomial negativa
- stats_rand_gen_int — Gera um inteiro aleatório entre 1 e 2147483562
- stats_rand_gen_ipoisson — Gera um único desvio aleatório de uma distribuição de Poisson
- stats_rand_gen_iuniform — Gera inteiros distribuídos uniformemente entre um número inferior (inclusive) e um superior (inclusive)
- stats_rand_gen_noncentral_chisquare — Gera um desvio aleatório da distribuição qui-quadrado não centralizada
- stats_rand_gen_noncentral_f — Gera um desvio aleatório da distribuição F não centralizada
- stats_rand_gen_noncentral_t — Gera um único desvio aleatório de uma distribuição t não centralizada
- stats_rand_gen_normal — Gera um único desvio aleatório de uma distribuição normal
- stats_rand_gen_t — Gera um único desvio aleatório de uma distribuição t
- stats_rand_get_seeds — Obtém os valores iniciais do gerador de números aleatórios
- stats_rand_phrase_to_seeds — Gera duas sementes para o gerador de números aleatórios RGN
- stats_rand_ranf — Gera um número de ponto flutuante aleatório entre 0 e 1
- stats_rand_setall — Define valores de semente para o gerador aleatório
- stats_skew — Calcula a assimetria dos dados no array
- stats_standard_deviation — Retorna o desvio padrão
- stats_stat_binomial_coef — Retorna um coeficiente binomial
- stats_stat_correlation — Retorna o coeficiente de correlação de Pearson de dois conjuntos de dados
- stats_stat_factorial — Retorna o fatorial de um inteiro
- stats_stat_independent_t — Retorna o valor t do teste t independente de duas amostras
- stats_stat_innerproduct — Retorna o produto interno de dois vetores
- stats_stat_paired_t — Retorna o valor t do teste t dependente para amostras pareadas
- stats_stat_percentile — Retorna o valor do percentil
- stats_stat_powersum — Retorna a soma de potências de um vetor
- stats_variance — Retorna a variância

- Instalação/Configuração
  - Dependências
  - Instalação
- Funções de Statistic
  - stats_absolute_deviation — Retorna o desvio absoluto de um array de valores
  - stats_cdf_beta — Calcula qualquer parâmetro da distribuição beta, dados os valores dos outros
  - stats_cdf_binomial — Calcula qualquer parâmetro da distribuição binomial, dados os valores dos outros
  - stats_cdf_cauchy — Calcula qualquer parâmetro da distribuição de Cauchy, dados os valores dos outros
  - stats_cdf_chisquare — Calcula qualquer parâmetro da distribuição qui-quadrado, dados os valores dos outros
  - stats_cdf_exponential — Calcula qualquer parâmetro da distribuição exponencial, dados os valores dos outros
  - stats_cdf_f — Calcula qualquer parâmetro da distribuição F, dados os valores dos outros
  - stats_cdf_gamma — Calcula qualquer parâmetro da distribuição gama, dados os valores dos outros
  - stats_cdf_laplace — Calcula qualquer parâmetro da distribuição de Laplace, dados os valores dos outros
  - stats_cdf_logistic — Calcula qualquer parâmetro da distribuição logística, dados os valores dos outros
  - stats_cdf_negative_binomial — Calcula qualquer parâmetro da distribuição binomial negativa, dados os valores dos outros
  - stats_cdf_noncentral_chisquare — Calcula qualquer parâmetro da distribuição qui-quadrado não centralizada, dados os valores dos outros
  - stats_cdf_noncentral_f — Calcula qualquer parâmetro da distribuição F não centralizada, dados os valores dos outros
  - stats_cdf_noncentral_t — Calcula qualquer parâmetro da distribuição t não centralizada e fornece valores para os outros
  - stats_cdf_normal — Calcula qualquer parâmetro da distribuição normal, dados os valores dos outros
  - stats_cdf_poisson — Calcula qualquer parâmetro da distribuição de Poisson, dados os valores dos outros
  - stats_cdf_t — Calcula qualquer parâmetro da distribuição t, dados os valores dos outros
  - stats_cdf_uniform — Calcula qualquer parâmetro da distribuição uniforme, dados os valores dos outros
  - stats_cdf_weibull — Calcula qualquer parâmetro da distribuição de Weibull, dados os valores dos outros
  - stats_covariance — Calcula a covariância de dois conjuntos de dados
  - stats_dens_beta — Função de densidade de probabilidade da distribuição beta
  - stats_dens_cauchy — Função de densidade de probabilidade da distribuição de Cauchy
  - stats_dens_chisquare — Função de densidade de probabilidade da distribuição qui-quadrado
  - stats_dens_exponential — Função de densidade de probabilidade da distribuição exponencial
  - stats_dens_f — Função de densidade de probabilidade da distribuição F
  - stats_dens_gamma — Função de densidade de probabilidade da distribuição gama
  - stats_dens_laplace — Função de densidade de probabilidade da distribuição de Laplace
  - stats_dens_logistic — Função de densidade de probabilidade da distribuição logística
  - stats_dens_normal — Função de densidade de probabilidade da distribuição normal
  - stats_dens_pmf_binomial — Função de massa de probabilidade da distribuição binomial
  - stats_dens_pmf_hypergeometric — Função de massa de probabilidade da distribuição hipergeométrica
  - stats_dens_pmf_negative_binomial — Função de massa de probabilidade da distribuição binomial negativa
  - stats_dens_pmf_poisson — Função de massa de probabilidade da distribuição de Poisson
  - stats_dens_t — Função de densidade de probabilidade da distribuição t
  - stats_dens_uniform — Função de densidade de probabilidade da distribuição uniforme
  - stats_dens_weibull — Função de densidade de probabilidade da distribuição Weibull
  - stats_harmonic_mean — Retorna a média harmônica de um array de valores
  - stats_kurtosis — Calcula a curtose dos dados no array
  - stats_rand_gen_beta — Gera um desvio aleatório da distribuição beta
  - stats_rand_gen_chisquare — Gera um desvio aleatório da distribuição qui-quadrado
  - stats_rand_gen_exponential — Gera um desvio aleatório da distribuição exponencial
  - stats_rand_gen_f — Gera um desvio aleatório da distribuição F
  - stats_rand_gen_funiform — Gera um float uniforme entre o limite inferior (exclusive) e superior (exclusive)
  - stats_rand_gen_gamma — Gera um desvio aleatório da distribuição gama
  - stats_rand_gen_ibinomial — Gera um desvio aleatório da distribuição binomial
  - stats_rand_gen_ibinomial_negative — Gera um desvio aleatório da distribuição binomial negativa
  - stats_rand_gen_int — Gera um inteiro aleatório entre 1 e 2147483562
  - stats_rand_gen_ipoisson — Gera um único desvio aleatório de uma distribuição de Poisson
  - stats_rand_gen_iuniform — Gera inteiros distribuídos uniformemente entre um número inferior (inclusive) e um superior (inclusive)
  - stats_rand_gen_noncentral_chisquare — Gera um desvio aleatório da distribuição qui-quadrado não centralizada
  - stats_rand_gen_noncentral_f — Gera um desvio aleatório da distribuição F não centralizada
  - stats_rand_gen_noncentral_t — Gera um único desvio aleatório de uma distribuição t não centralizada
  - stats_rand_gen_normal — Gera um único desvio aleatório de uma distribuição normal
  - stats_rand_gen_t — Gera um único desvio aleatório de uma distribuição t
  - stats_rand_get_seeds — Obtém os valores iniciais do gerador de números aleatórios
  - stats_rand_phrase_to_seeds — Gera duas sementes para o gerador de números aleatórios RGN
  - stats_rand_ranf — Gera um número de ponto flutuante aleatório entre 0 e 1
  - stats_rand_setall — Define valores de semente para o gerador aleatório
  - stats_skew — Calcula a assimetria dos dados no array
  - stats_standard_deviation — Retorna o desvio padrão
  - stats_stat_binomial_coef — Retorna um coeficiente binomial
  - stats_stat_correlation — Retorna o coeficiente de correlação de Pearson de dois conjuntos de dados
  - stats_stat_factorial — Retorna o fatorial de um inteiro
  - stats_stat_independent_t — Retorna o valor t do teste t independente de duas amostras
  - stats_stat_innerproduct — Retorna o produto interno de dois vetores
  - stats_stat_paired_t — Retorna o valor t do teste t dependente para amostras pareadas
  - stats_stat_percentile — Retorna o valor do percentil
  - stats_stat_powersum — Retorna a soma de potências de um vetor
  - stats_variance — Retorna a variância

# Análise Técnica para Negociadores

# Introdução

A extensão Trader é uma biblioteca de ações gratuita e de código aberto baseada na TA-Lib. É dedicada a desenvolvedores de software de negociação que precisam realizar análises técnicas de dados do mercado financeiro. Além de muitos indicadores como ADX, MACD, RSI, Estocástico e TRIX, o reconhecimento de padrões de candlestick e diversas funções aritméticas e algébricas vetoriais estão presentes.

Os cálculos podem ser feitos de duas maneiras: TA-Lib e Metastock. Alterá-los usando trader_set_compat() afetará o funcionamento de algumas funções de Trader.

Algumas funções de Trader fornecem resultados diferentes dependendo do "ponto de partida" dos dados envolvidos. Isso é frequentemente chamado de função com memórias. Um exemplo dessa função é a Média Móvel Exponencial. É possível controlar o período instável (a quantidade de dados a ser removida) usando a função trader_set_unstable_period().

Documentação estendida sobre indicadores, fórmulas e implementações em outras linguagens de programação pode ser encontrada em » https://ta-lib.org/.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução

## Dependências

A extensão do trader é baseada na » TA-Lib. A TA-Lib é totalmente integrada à extensão, portanto, não são necessárias bibliotecas externas.

## Instalação

Esta extensão » PECL não é distribuída com o PHP.

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/trader.

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

Opções de Configuração de Trader
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
trader.real_precision | 3 | `INI_ALL` | Desde o trader 0.2.1
trader.real_round_mode | HALF_DOWN | `INI_ALL` | Desde o trader 0.3.0

Aqui está uma breve explicação das diretivas de configuração.

`trader.real_precision` int

  Todos os valores nos arrays retornados serão arredondados para essa precisão. No entanto, os cálculos dentro do TA-Lib ocorrem com valores não arredondados.

`trader.real_round_mode` string

  Controla a política de arredondamento real do trader. Os valores válidos são `HALF_UP`, `HALF_DOWN`, `HALF_EVEN` e `HALF_ODD`. O comportamento é idêntico ao da função round() usada com o argumento mode.

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`TRADER_MA_TYPE_SMA` (int)
`TRADER_MA_TYPE_EMA` (int)
`TRADER_MA_TYPE_WMA` (int)
`TRADER_MA_TYPE_DEMA` (int)
`TRADER_MA_TYPE_TEMA` (int)
`TRADER_MA_TYPE_TRIMA` (int)
`TRADER_MA_TYPE_KAMA` (int)
`TRADER_MA_TYPE_MAMA` (int)
`TRADER_MA_TYPE_T3` (int)
`TRADER_REAL_MIN` (float)
`TRADER_REAL_MAX` (float)
`TRADER_FUNC_UNST_ADX` (int)
`TRADER_FUNC_UNST_ADXR` (int)
`TRADER_FUNC_UNST_ATR` (int)
`TRADER_FUNC_UNST_CMO` (int)
`TRADER_FUNC_UNST_DX` (int)
`TRADER_FUNC_UNST_EMA` (int)
`TRADER_FUNC_UNST_HT_DCPERIOD` (int)
`TRADER_FUNC_UNST_HT_DCPHASE` (int)
`TRADER_FUNC_UNST_HT_PHASOR` (int)
`TRADER_FUNC_UNST_HT_SINE` (int)
`TRADER_FUNC_UNST_HT_TRENDLINE` (int)
`TRADER_FUNC_UNST_HT_TRENDMODE` (int)
`TRADER_FUNC_UNST_KAMA` (int)
`TRADER_FUNC_UNST_MAMA` (int)
`TRADER_FUNC_UNST_MFI` (int)
`TRADER_FUNC_UNST_MINUS_DI` (int)
`TRADER_FUNC_UNST_MINUS_DM` (int)
`TRADER_FUNC_UNST_NATR` (int)
`TRADER_FUNC_UNST_PLUS_DI` (int)
`TRADER_FUNC_UNST_PLUS_DM` (int)
`TRADER_FUNC_UNST_RSI` (int)
`TRADER_FUNC_UNST_STOCHRSI` (int)
`TRADER_FUNC_UNST_T3` (int)
`TRADER_FUNC_UNST_ALL` (int)
`TRADER_FUNC_UNST_NONE` (int)
`TRADER_COMPATIBILITY_DEFAULT` (int)
`TRADER_COMPATIBILITY_METASTOCK` (int)
`TRADER_ERR_SUCCESS` (int)
`TRADER_ERR_LIB_NOT_INITIALIZE` (int)
`TRADER_ERR_BAD_PARAM` (int)
`TRADER_ERR_ALLOC_ERR` (int)
`TRADER_ERR_GROUP_NOT_FOUND` (int)
`TRADER_ERR_FUNC_NOT_FOUND` (int)
`TRADER_ERR_INVALID_HANDLE` (int)
`TRADER_ERR_INVALID_PARAM_HOLDER` (int)
`TRADER_ERR_INVALID_PARAM_HOLDER_TYPE` (int)
`TRADER_ERR_INVALID_PARAM_FUNCTION` (int)
`TRADER_ERR_INPUT_NOT_ALL_INITIALIZE` (int)
`TRADER_ERR_OUTPUT_NOT_ALL_INITIALIZE` (int)
`TRADER_ERR_OUT_OF_RANGE_START_INDEX` (int)
`TRADER_ERR_OUT_OF_RANGE_END_INDEX` (int)
`TRADER_ERR_INVALID_LIST_TYPE` (int)
`TRADER_ERR_BAD_OBJECT` (int)
`TRADER_ERR_NOT_SUPPORTED` (int)
`TRADER_ERR_INTERNAL_ERROR` (int)
`TRADER_ERR_UNKNOWN_ERROR` (int)

# Funções de Trader

# trader_acos

(PECL trader >= 0.2.0)

trader_acos — Arco cosseno trigonométrico vetorial

### Descrição

function trader_acos(array `$real`): array

Calcula o arco cosseno para cada valor em `real` e retorna o array resultante.

### Parâmetros

`real`

  Array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_ad

(PECL trader >= 0.2.0)

trader_ad — Linha Chaikin A/D

### Descrição

function trader_ad(
array `$high`,
array `$low`,
array `$close`,
array `$volume`
): array

### Parâmetros

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

`volume`

  Volume negociado, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_add

(PECL trader >= 0.2.0)

trader_add — Adição Aritmética Vetorial

### Descrição

function trader_add(array `$real0`, array `$real1`): array

Calcula a adição vetorial de `real0` a `real1` e retorna o vetor resultante.

### Parâmetros

`real0`

  Array de valores reais.

`real1`

  Array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_adosc

(PECL trader >= 0.2.0)

trader_adosc — Oscilador A/D Chaikin

### Descrição

function trader_adosc(
array `$high`,
array `$low`,
array `$close`,
array `$volume`,
int `$fastPeriod` = ?,
int `$slowPeriod` = ?
): array

### Parâmetros

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

`volume`

  Volume negociado, array de valores reais.

`fastPeriod`

  Número de período para o MA rápido. Intervalo válido de 2 a 100000.

`slowPeriod`

  Número de período para o MA lento. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_adx

(PECL trader >= 0.2.0)

trader_adx — Índice de Movimento Direcional Médio

### Descrição

function trader_adx(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Parâmetros

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_adxr

(PECL trader >= 0.2.0)

trader_adxr — Taxa do Índice de Movimento Direcional Médio

### Descrição

function trader_adxr(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Parâmetros

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_apo

(PECL trader >= 0.2.0)

trader_apo — Oscilador de Preço Absoluto

### Descrição

function trader_apo(
array `$real`,
int `$fastPeriod` = ?,
int `$slowPeriod` = ?,
int `$mAType` = ?
): array

### Parâmetros

`real`

  Array de valores reais.

`fastPeriod`

  Número de período para o MA rápido. Intervalo válido de 2 a 100000.

`slowPeriod`

  Número de período para o MA lento. Intervalo válido de 2 a 100000.

`mAType`

  Tipo de Média Móvel. As constantes TRADER_MA_TYPE_* devem ser usadas.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_aroon

(PECL trader >= 0.2.0)

trader_aroon — Aroon

### Descrição

function trader_aroon(array `$high`, array `$low`, int `$timePeriod` = ?): array

### Parâmetros

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_aroonosc

(PECL trader >= 0.2.0)

trader_aroonosc — Oscilador Aroon

### Descrição

function trader_aroonosc(array `$high`, array `$low`, int `$timePeriod` = ?): array

### Parâmetros

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_asin

(PECL trader >= 0.2.0)

trader_asin — Arco seno trigonométrico vetorial

### Descrição

function trader_asin(array `$real`): array

Calcula o arco seno para cada valor em `real` e retorna o array resultante.

### Parâmetros

`real`

  Array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_atan

(PECL trader >= 0.2.0)

trader_atan — Arco Tangente Trigonométrico Vetorial

### Descrição

function trader_atan(array `$real`): array

Calcula o arco tangente para cada valor em `real` e retorna o array resultante.

### Parâmetros

`real`

  Array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_atr

(PECL trader >= 0.2.0)

trader_atr — Intervalo Verdadeiro Média

### Descrição

function trader_atr(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Parâmetros

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_avgprice

(PECL trader >= 0.2.0)

trader_avgprice — Preço médio

### Descrição

function trader_avgprice(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_bbands

(PECL trader >= 0.2.0)

trader_bbands — Bandas de Bollinger

### Descrição

function trader_bbands(
array `$real`,
int `$timePeriod` = ?,
float `$nbDevUp` = ?,
float `$nbDevDn` = ?,
int `$mAType` = ?
): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

`nbDevUp`

  Multiplicador de desvio para banda superior. Intervalo válido de TRADER_REAL_MIN a TRADER_REAL_MAX.

`nbDevDn`

  Multiplicador de desvio para a banda inferior. Intervalo válido de TRADER_REAL_MIN a TRADER_REAL_MAX.

`mAType`

  Tipo de Média Móvel. As constantes TRADER_MA_TYPE_* devem ser usadas.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_beta

(PECL trader >= 0.2.0)

trader_beta — Beta

### Descrição

function trader_beta(array `$real0`, array `$real1`, int `$timePeriod` = ?): array

### Parâmetros

`real0`

  Array de valores reais.

`real1`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_bop

(PECL trader >= 0.2.0)

trader_bop — Equilíbrio de poder

### Descrição

function trader_bop(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cci

(PECL trader >= 0.2.0)

trader_cci — Índice de Canal de Commodities

### Descrição

function trader_cci(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Parâmetros

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdl2crows

(PECL trader >= 0.2.0)

trader_cdl2crows — Dois corvos

### Descrição

function trader_cdl2crows(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdl3blackcrows

(PECL trader >= 0.2.0)

trader_cdl3blackcrows — Três Corvos Negros

### Descrição

function trader_cdl3blackcrows(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdl3inside

(PECL trader >= 0.2.0)

trader_cdl3inside — Três velas internas para cima/baixo

### Descrição

function trader_cdl3inside(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdl3linestrike

(PECL trader >= 0.2.0)

trader_cdl3linestrike — Strike de três linhas

### Descrição

function trader_cdl3linestrike(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdl3outside

(PECL trader >= 0.2.0)

trader_cdl3outside — Três exteriores para cima/baixo

### Descrição

function trader_cdl3outside(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdl3starsinsouth

(PECL trader >= 0.2.0)

trader_cdl3starsinsouth — Três Estrelas no Sul

### Descrição

function trader_cdl3starsinsouth(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdl3whitesoldiers

(PECL trader >= 0.2.0)

trader_cdl3whitesoldiers — Três Soldados Brancos Avançando

### Descrição

function trader_cdl3whitesoldiers(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlabandonedbaby

(PECL trader >= 0.2.0)

trader_cdlabandonedbaby — Bebê Abandonado

### Descrição

function trader_cdlabandonedbaby(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

`penetration`

  Percentual de penetração de um candle em outro candle.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdladvanceblock

(PECL trader >= 0.2.0)

trader_cdladvanceblock — Bloco Avançado

### Descrição

function trader_cdladvanceblock(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlbelthold

(PECL trader >= 0.2.0)

trader_cdlbelthold — Cinturão de Espera

### Descrição

function trader_cdlbelthold(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlbreakaway

(PECL trader >= 0.2.0)

trader_cdlbreakaway — Lacuna de Ruptura

### Descrição

function trader_cdlbreakaway(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlclosingmarubozu

(PECL trader >= 0.2.0)

trader_cdlclosingmarubozu — Marubozu de Fechamento

### Descrição

function trader_cdlclosingmarubozu(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlconcealbabyswall

(PECL trader >= 0.2.0)

trader_cdlconcealbabyswall — Engolimento de Bebê Escondido

### Descrição

function trader_cdlconcealbabyswall(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlcounterattack

(PECL trader >= 0.2.0)

trader_cdlcounterattack — Contra-ataque

### Descrição

function trader_cdlcounterattack(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdldarkcloudcover

(PECL trader >= 0.2.0)

trader_cdldarkcloudcover — Nuvem Negra

### Descrição

function trader_cdldarkcloudcover(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

`penetration`

  Percentual de penetração de um candle em outro candle.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdldoji

(PECL trader >= 0.2.0)

trader_cdldoji — Doji

### Descrição

function trader_cdldoji(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdldojistar

(PECL trader >= 0.2.0)

trader_cdldojistar — Doji Estrela

### Descrição

function trader_cdldojistar(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdldragonflydoji

(PECL trader >= 0.2.0)

trader_cdldragonflydoji — Doji Libélula

### Descrição

function trader_cdldragonflydoji(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlengulfing

(PECL trader >= 0.2.0)

trader_cdlengulfing — Padrão de Engolimento

### Descrição

function trader_cdlengulfing(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdleveningdojistar

(PECL trader >= 0.2.0)

trader_cdleveningdojistar — Doji Estrela da Noite

### Descrição

function trader_cdleveningdojistar(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

`penetration`

  Percentual de penetração de um candle em outro candle.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdleveningstar

(PECL trader >= 0.2.0)

trader_cdleveningstar — Estrela da Noite

### Descrição

function trader_cdleveningstar(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

`penetration`

  Percentual de penetração de um candle em outro candle.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlgapsidesidewhite

(PECL trader >= 0.2.0)

trader_cdlgapsidesidewhite — Linhas brancas lado a lado com gap de alta/baixa

### Descrição

function trader_cdlgapsidesidewhite(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlgravestonedoji

(PECL trader >= 0.2.0)

trader_cdlgravestonedoji — Doji Lápide

### Descrição

function trader_cdlgravestonedoji(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlhammer

(PECL trader >= 0.2.0)

trader_cdlhammer — Martelo

### Descrição

function trader_cdlhammer(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlhangingman

(PECL trader >= 0.2.0)

trader_cdlhangingman — Homem enforcado

### Descrição

function trader_cdlhangingman(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlharami

(PECL trader >= 0.2.0)

trader_cdlharami — Harami

### Descrição

function trader_cdlharami(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlharamicross

(PECL trader >= 0.2.0)

trader_cdlharamicross — Cruz Harami

### Descrição

function trader_cdlharamicross(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlhighwave

(PECL trader >= 0.2.0)

trader_cdlhighwave — Vela de onda alta

### Descrição

function trader_cdlhighwave(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlhikkake

(PECL trader >= 0.2.0)

trader_cdlhikkake — Hikkake

### Descrição

function trader_cdlhikkake(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlhikkakemod

(PECL trader >= 0.2.0)

trader_cdlhikkakemod — Hikkake Modificado

### Descrição

function trader_cdlhikkakemod(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlhomingpigeon

(PECL trader >= 0.2.0)

trader_cdlhomingpigeon — Ave Migratória

### Descrição

function trader_cdlhomingpigeon(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlidentical3crows

(PECL trader >= 0.2.0)

trader_cdlidentical3crows — Três Corvos Idênticos

### Descrição

function trader_cdlidentical3crows(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlinneck

(PECL trader >= 0.2.0)

trader_cdlinneck — In-Neck

### Descrição

function trader_cdlinneck(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlinvertedhammer

(PECL trader >= 0.2.0)

trader_cdlinvertedhammer — Martelo Invertido

### Descrição

function trader_cdlinvertedhammer(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlkicking

(PECL trader >= 0.2.0)

trader_cdlkicking — Chute nos pneus

### Descrição

function trader_cdlkicking(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlkickingbylength

(PECL trader >= 0.2.0)

trader_cdlkickingbylength — Chute - touro/urso determinado pelo Marubozu mais longo

### Descrição

function trader_cdlkickingbylength(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlladderbottom

(PECL trader >= 0.2.0)

trader_cdlladderbottom — Escada de Baixo

### Descrição

function trader_cdlladderbottom(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdllongleggeddoji

(PECL trader >= 0.2.0)

trader_cdllongleggeddoji — Doji de Pernas Compridas

### Descrição

function trader_cdllongleggeddoji(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdllongline

(PECL trader >= 0.2.0)

trader_cdllongline — Vela de Linha Longa

### Descrição

function trader_cdllongline(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlmarubozu

(PECL trader >= 0.2.0)

trader_cdlmarubozu — Marubozu

### Descrição

function trader_cdlmarubozu(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlmatchinglow

(PECL trader >= 0.2.0)

trader_cdlmatchinglow — Matching Low

### Descrição

function trader_cdlmatchinglow(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlmathold

(PECL trader >= 0.2.0)

trader_cdlmathold — Aperto do Mat

### Descrição

function trader_cdlmathold(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

`penetration`

  Percentual de penetração de um candle em outro candle.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlmorningdojistar

(PECL trader >= 0.2.0)

trader_cdlmorningdojistar — Estrela da Manhã Doji

### Descrição

function trader_cdlmorningdojistar(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

`penetration`

  Percentual de penetração de um candle em outro candle.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlmorningstar

(PECL trader >= 0.2.0)

trader_cdlmorningstar — Estrela da Manhã

### Descrição

function trader_cdlmorningstar(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

`penetration`

  Percentual de penetração de um candle em outro candle.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlonneck

(PECL trader >= 0.2.0)

trader_cdlonneck — On-Neck

### Descrição

function trader_cdlonneck(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlpiercing

(PECL trader >= 0.2.0)

trader_cdlpiercing — Piercing

### Descrição

function trader_cdlpiercing(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlrickshawman

(PECL trader >= 0.2.0)

trader_cdlrickshawman — Homem da Carruagem

### Descrição

function trader_cdlrickshawman(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlrisefall3methods

(PECL trader >= 0.2.0)

trader_cdlrisefall3methods — Três Métodos de Subida/Descida

### Descrição

function trader_cdlrisefall3methods(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlseparatinglines

(PECL trader >= 0.2.0)

trader_cdlseparatinglines — Linhas de Separação

### Descrição

function trader_cdlseparatinglines(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlshootingstar

(PECL trader >= 0.2.0)

trader_cdlshootingstar — Estrela Cadente

### Descrição

function trader_cdlshootingstar(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlshortline

(PECL trader >= 0.2.0)

trader_cdlshortline — Vela de Linha Curta

### Descrição

function trader_cdlshortline(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlspinningtop

(PECL trader >= 0.2.0)

trader_cdlspinningtop — Pião Giratório

### Descrição

function trader_cdlspinningtop(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlstalledpattern

(PECL trader >= 0.2.0)

trader_cdlstalledpattern — Padrão de Deliberação

### Descrição

function trader_cdlstalledpattern(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlsticksandwich

(PECL trader >= 0.2.0)

trader_cdlsticksandwich — Vela Prensada

### Descrição

function trader_cdlsticksandwich(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdltakuri

(PECL trader >= 0.2.0)

trader_cdltakuri — Takuri (Doji Libélula com sombra inferior muito longa)

### Descrição

function trader_cdltakuri(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdltasukigap

(PECL trader >= 0.2.0)

trader_cdltasukigap — Lacuna Tasuki

### Descrição

function trader_cdltasukigap(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlthrusting

(PECL trader >= 0.2.0)

trader_cdlthrusting — Thrusting

### Descrição

function trader_cdlthrusting(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdltristar

(PECL trader >= 0.2.0)

trader_cdltristar — Tri-Star

### Descrição

function trader_cdltristar(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlunique3river

(PECL trader >= 0.2.0)

trader_cdlunique3river — Unique 3 River

### Descrição

function trader_cdlunique3river(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlupsidegap2crows

(PECL trader >= 0.2.0)

trader_cdlupsidegap2crows — Dois Corvos de Alta com Gap

### Descrição

function trader_cdlupsidegap2crows(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cdlxsidegap3methods

(PECL trader >= 0.2.0)

trader_cdlxsidegap3methods — Três Métodos de Lacunas Positivas/Negativas

### Descrição

function trader_cdlxsidegap3methods(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parâmetros

`open`

  Preço de abertura, array de valores reais.

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_ceil

(PECL trader >= 0.2.0)

trader_ceil — Teto vetorial

### Descrição

function trader_ceil(array `$real`): array

Calcula o próximo número inteiro mais alto para cada valor em `real` e retorna o array resultante.

### Parâmetros

`real`

  Array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cmo

(PECL trader >= 0.2.0)

trader_cmo — Oscilador de Momentum Chande

### Descrição

function trader_cmo(array `$real`, int `$timePeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_correl

(PECL trader >= 0.2.0)

trader_correl — Coeficiente de correlação de Pearson (r)

### Descrição

function trader_correl(array `$real0`, array `$real1`, int `$timePeriod` = ?): array

### Parâmetros

`real0`

  Array de valores reais.

`real1`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cos

(PECL trader >= 0.2.0)

trader_cos — Cosseno Trigonométrico Vetorial

### Descrição

function trader_cos(array `$real`): array

Calcula o cosseno para cada valor em `real` e retorna o array resultante.

### Parâmetros

`real`

  Array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_cosh

(PECL trader >= 0.2.0)

trader_cosh — Cosseno Hiperbólico Trigonométrico Vetorial

### Descrição

function trader_cosh(array `$real`): array

Calcula o cosseno hiperbólico para cada valor em `real` e retorna o array resultante.

### Parâmetros

`real`

  Array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_dema

(PECL trader >= 0.2.0)

trader_dema — Média Móvel Exponencial Dupla

### Descrição

function trader_dema(array `$real`, int `$timePeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_div

(PECL trader >= 0.2.0)

trader_div — Divisão Aritmética Vetorial

### Descrição

function trader_div(array `$real0`, array `$real1`): array

Divide cada valor de `real0` pelo valor correspondente de `real1` e retorna o array resultante.

### Parâmetros

`real0`

  Array de valores reais.

`real1`

  Array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_dx

(PECL trader >= 0.2.0)

trader_dx — Índice de movimento direcional

### Descrição

function trader_dx(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Parâmetros

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_ema

(PECL trader >= 0.2.0)

trader_ema — Média Móvel Exponencial

### Descrição

function trader_ema(array `$real`, int `$timePeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_errno

(PECL trader >= 0.3.0)

trader_errno — Obtém código de erro

### Descrição

function trader_errno(): int

Obtém o código de erro da última operação.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o código de erro identificado por uma das constantes TRADER_ERR_*.

# trader_exp

(PECL trader >= 0.2.0)

trader_exp — Exponenciação Aritmética Vetorial

### Descrição

function trader_exp(array `$real`): array

Calcula `e` elevado à potência de cada valor em `real`. Retorna um array com os dados calculados.

### Parâmetros

`real`

  Array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_floor

(PECL trader >= 0.2.0)

trader_floor — Piso Vetorial

### Descrição

function trader_floor(array `$real`): array

Calcule o próximo número inteiro mais baixo para cada valor em `real` e retorna o array resultante.

### Parâmetros

`real`

  Array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_get_compat

(PECL trader >= 0.2.2)

trader_get_compat — Obtém modo de compatibilidade

### Descrição

function trader_get_compat(): int

Obtém o modo de compatibilidade que afeta a maneira como os cálculos são feitos por todas as funções de extensão.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o ID do modo de compatibilidade que pode ser identificado pela série de constantes TRADER_COMPATIBILITY_*.

# trader_get_unstable_period

(PECL trader >= 0.2.2)

trader_get_unstable_period — Obtém o período instável

### Descrição

function trader_get_unstable_period(int `$functionId`): int

Obtém o fator de período instável para uma função em particular.

### Parâmetros

`functionId`

  ID da função do fator a ser lido. A série de constantes TRADER_FUNC_UNST_* deve ser usada.

### Valor Retornado

Retorna o fator de período instável para a função correspondente.

# trader_ht_dcperiod

(PECL trader >= 0.2.0)

trader_ht_dcperiod — Transformada de Hilbert - Período do Ciclo Dominante

### Descrição

function trader_ht_dcperiod(array `$real`): array

### Parâmetros

`real`

  Array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_ht_dcphase

(PECL trader >= 0.2.0)

trader_ht_dcphase — Transformada de Hilbert - Fase do Ciclo Dominante

### Descrição

function trader_ht_dcphase(array `$real`): array

### Parâmetros

`real`

  Array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_ht_phasor

(PECL trader >= 0.2.0)

trader_ht_phasor — Transformada de Hilbert - Componentes Fasoriais

### Descrição

function trader_ht_phasor(array `$real`): array

### Parâmetros

`real`

  Array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_ht_sine

(PECL trader >= 0.2.0)

trader_ht_sine — Transformada de Hilbert - Onda Senoidal

### Descrição

function trader_ht_sine(array `$real`): array

### Parâmetros

`real`

  Array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_ht_trendline

(PECL trader >= 0.2.0)

trader_ht_trendline — Transformada de Hilbert - Linha de Tendência Instantânea

### Descrição

function trader_ht_trendline(array `$real`): array

### Parâmetros

`real`

  Array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_ht_trendmode

(PECL trader >= 0.2.0)

trader_ht_trendmode — Transformada de Hilbert - Modo de Tendência vs. Modo de Ciclo

### Descrição

function trader_ht_trendmode(array `$real`): array

### Parâmetros

`real`

  Array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_kama

(PECL trader >= 0.2.0)

trader_kama — Média Móvel Adaptativa de Kaufman

### Descrição

function trader_kama(array `$real`, int `$timePeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_linearreg

(PECL trader >= 0.2.0)

trader_linearreg — Regressão Linear

### Descrição

function trader_linearreg(array `$real`, int `$timePeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_linearreg_angle

(PECL trader >= 0.2.0)

trader_linearreg_angle — Ângulo de Regressão Linear

### Descrição

function trader_linearreg_angle(array `$real`, int `$timePeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_linearreg_intercept

(PECL trader >= 0.2.0)

trader_linearreg_intercept — Interceptação de regressão linear

### Descrição

function trader_linearreg_intercept(array `$real`, int `$timePeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_linearreg_slope

(PECL trader >= 0.2.0)

trader_linearreg_slope — Inclinação da regressão linear

### Descrição

function trader_linearreg_slope(array `$real`, int `$timePeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_ln

(PECL trader >= 0.2.0)

trader_ln — Logaitmo natural vetorial

### Descrição

function trader_ln(array `$real`): array

Calcular o logaritmo natural para cada valor em `real` e retorna o array resultante.

### Parâmetros

`real`

  Array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_log10

(PECL trader >= 0.2.0)

trader_log10 — Log10 Vetorial

### Descrição

function trader_log10(array `$real`): array

Calcula o logartimo na base 10 para cada valor em `real` e retorna o array resultante.

### Parâmetros

`real`

  Array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_ma

(PECL trader >= 0.2.0)

trader_ma — Média móvel

### Descrição

function trader_ma(array `$real`, int `$timePeriod` = ?, int `$mAType` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

`mAType`

  Tipo de Média Móvel. As constantes TRADER_MA_TYPE_* devem ser usadas.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_macd

(PECL trader >= 0.2.0)

trader_macd — Convergência/Divergência da Média Móvel

### Descrição

function trader_macd(
array `$real`,
int `$fastPeriod` = ?,
int `$slowPeriod` = ?,
int `$signalPeriod` = ?
): array

### Parâmetros

`real`

  Array de valores reais.

`fastPeriod`

  Número de período para o MA rápido. Intervalo válido de 2 a 100000.

`slowPeriod`

  Número de período para o MA lento. Intervalo válido de 2 a 100000.

`signalPeriod`

  Suavização da linha de sinal (número de período). Intervalo válido de 1 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_macdext

(PECL trader >= 0.2.0)

trader_macdext — Convergência/Divergência da Média Móvel com tipo MM controlável

### Descrição

function trader_macdext(
array `$real`,
int `$fastPeriod` = ?,
int `$fastMAType` = ?,
int `$slowPeriod` = ?,
int `$slowMAType` = ?,
int `$signalPeriod` = ?,
int `$signalMAType` = ?
): array

### Parâmetros

`real`

  Array de valores reais.

`fastPeriod`

  Número de período para o MA rápido. Intervalo válido de 2 a 100000.

`fastMAType`

  Tipo de Média Móvel para o MA rápido. As constantes TRADER_MA_TYPE_* devem ser usadas.

`slowPeriod`

  Número de período para o MA lento. Intervalo válido de 2 a 100000.

`slowMAType`

  Tipo de Média Móvel para o MA lento. As constantes TRADER_MA_TYPE_* devem ser usadas.

`signalPeriod`

  Suavização da linha de sinal (número de período). Intervalo válido de 1 a 100000.

`signalMAType`

  Tipo de Média Móvel para a linha de sinal. As constantes TRADER_MA_TYPE_* devem ser usadas.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_macdfix

(PECL trader >= 0.2.0)

trader_macdfix — Convergência/Divergência da Média Móvel Fixa 26/12

### Descrição

function trader_macdfix(array `$real`, int `$signalPeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`signalPeriod`

  Suavização da linha de sinal (número de período). Intervalo válido de 1 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_mama

(PECL trader >= 0.2.0)

trader_mama — Média Móvel Adaptativa MESA

### Descrição

function trader_mama(array `$real`, float `$fastLimit` = ?, float `$slowLimit` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`fastLimit`

  Limite superior usado no algoritmo adaptativo. Intervalo válido de 0.01 a 0.99.

`slowLimit`

  Limite inferior usado no algoritmo adaptativo. Intervalo válido de 0.01 a 0.99.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_mavp

(PECL trader >= 0.2.0)

trader_mavp — Média móvel com período variável

### Descrição

function trader_mavp(
array `$real`,
array `$periods`,
int `$minPeriod` = ?,
int `$maxPeriod` = ?,
int `$mAType` = ?
): array

### Parâmetros

`real`

  Array de valores reais.

`periods`

  Array de valores reais.

`minPeriod`

  Valor inferior ao mínimo que será modificado para período mínimo. Intervalo válido de 2 a 100000.

`maxPeriod`

  Valor superior ao mínimo que será modificado para período máximo. Intervalo válido de 2 a 100000.

`mAType`

  Tipo de Média Móvel. As constantes TRADER_MA_TYPE_* devem ser usadas.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_max

(PECL trader >= 0.2.0)

trader_max — Maior valor em um período especificado

### Descrição

function trader_max(array `$real`, int `$timePeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_maxindex

(PECL trader >= 0.2.0)

trader_maxindex — Índice de maior valor em um período especificado

### Descrição

function trader_maxindex(array `$real`, int `$timePeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_medprice

(PECL trader >= 0.2.0)

trader_medprice — Preço mediano

### Descrição

function trader_medprice(array `$high`, array `$low`): array

### Parâmetros

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_mfi

(PECL trader >= 0.2.0)

trader_mfi — Índice de Fluxo de Dinheiro

### Descrição

function trader_mfi(
array `$high`,
array `$low`,
array `$close`,
array `$volume`,
int `$timePeriod` = ?
): array

### Parâmetros

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

`volume`

  Volume negociado, array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_midpoint

(PECL trader >= 0.2.0)

trader_midpoint — Ponto médio ao longo do período

### Descrição

function trader_midpoint(array `$real`, int `$timePeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_midprice

(PECL trader >= 0.2.0)

trader_midprice — Preço do ponto médio ao longo do período

### Descrição

function trader_midprice(array `$high`, array `$low`, int `$timePeriod` = ?): array

### Parâmetros

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_min

(PECL trader >= 0.2.0)

trader_min — Menor valor em um período especificado

### Descrição

function trader_min(array `$real`, int `$timePeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_minindex

(PECL trader >= 0.2.0)

trader_minindex — Índice de menor valor em um período especificado

### Descrição

function trader_minindex(array `$real`, int `$timePeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_minmax

(PECL trader >= 0.2.0)

trader_minmax — Valores mais baixos e mais altos durante um período especificado

### Descrição

function trader_minmax(array `$real`, int `$timePeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_minmaxindex

(PECL trader >= 0.2.0)

trader_minmaxindex — Índices de valores mais baixos e mais altos durante um período especificado

### Descrição

function trader_minmaxindex(array `$real`, int `$timePeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_minus_di

(PECL trader >= 0.2.0)

trader_minus_di — Indicador direcional negativo

### Descrição

function trader_minus_di(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Parâmetros

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_minus_dm

(PECL trader >= 0.2.0)

trader_minus_dm — Movimento Direcional Negativo

### Descrição

function trader_minus_dm(array `$high`, array `$low`, int `$timePeriod` = ?): array

### Parâmetros

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_mom

(PECL trader >= 0.2.0)

trader_mom — Momento

### Descrição

function trader_mom(array `$real`, int `$timePeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_mult

(PECL trader >= 0.2.0)

trader_mult — Multiplicação Aritmética Vetorial

### Descrição

function trader_mult(array `$real0`, array `$real1`): array

Calcula o produto escalar de `real0` com `real1` e retorna o vetor resultante.

### Parâmetros

`real0`

  Array de valores reais.

`real1`

  Array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_natr

(PECL trader >= 0.2.0)

trader_natr — Intervalo médio verdadeiro normalizado

### Descrição

function trader_natr(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Parâmetros

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_obv

(PECL trader >= 0.2.0)

trader_obv — Volume em Equilíbrio

### Descrição

function trader_obv(array `$real`, array `$volume`): array

### Parâmetros

`real`

  Array de valores reais.

`volume`

  Volume negociado, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_plus_di

(PECL trader >= 0.2.0)

trader_plus_di — Indicador Direcional Positivo

### Descrição

function trader_plus_di(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Parâmetros

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_plus_dm

(PECL trader >= 0.2.0)

trader_plus_dm — Movimento Direcional Positivo

### Descrição

function trader_plus_dm(array `$high`, array `$low`, int `$timePeriod` = ?): array

### Parâmetros

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_ppo

(PECL trader >= 0.2.0)

trader_ppo — Oscilador de Preço Percentual

### Descrição

function trader_ppo(
array `$real`,
int `$fastPeriod` = ?,
int `$slowPeriod` = ?,
int `$mAType` = ?
): array

### Parâmetros

`real`

  Array de valores reais.

`fastPeriod`

  Número de período para o MA rápido. Intervalo válido de 2 a 100000.

`slowPeriod`

  Número de período para o MA lento. Intervalo válido de 2 a 100000.

`mAType`

  Tipo de Média Móvel. As constantes TRADER_MA_TYPE_* devem ser usadas.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_roc

(PECL trader >= 0.2.0)

trader_roc — Taxa de variação: ((preço/preçoAnterior)-1)*100

### Descrição

function trader_roc(array `$real`, int `$timePeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_rocp

(PECL trader >= 0.2.0)

trader_rocp — Taxa de variação Percentual: (preço-preçoAnterior)/preçoAnterior

### Descrição

function trader_rocp(array `$real`, int `$timePeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_rocr

(PECL trader >= 0.2.0)

trader_rocr — Taxa de variação: (preço/preçoAnterior)

### Descrição

function trader_rocr(array `$real`, int `$timePeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_rocr100

(PECL trader >= 0.2.0)

trader_rocr100 — Taxa de variação na escala 100: (preço/preçoAnterior)*100

### Descrição

function trader_rocr100(array `$real`, int `$timePeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_rsi

(PECL trader >= 0.2.0)

trader_rsi — Índice de Força Relativa

### Descrição

function trader_rsi(array `$real`, int `$timePeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_sar

(PECL trader >= 0.2.0)

trader_sar — SAR parabólico

### Descrição

function trader_sar(
array `$high`,
array `$low`,
float `$acceleration` = ?,
float `$maximum` = ?
): array

### Parâmetros

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`acceleration`

  Fator de Aceleração utilizado até o valor Máximo. Intervalo válido de 0 a TRADER_REAL_MAX.

`maximum`

  Fator de Aceleração: Valor máximo. Intervalo válido de 0 a TRADER_REAL_MAX.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_sarext

(PECL trader >= 0.2.0)

trader_sarext — SAR Parabólico - Estendido

### Descrição

function trader_sarext(
array `$high`,
array `$low`,
float `$startValue` = ?,
float `$offsetOnReverse` = ?,
float `$accelerationInitLong` = ?,
float `$accelerationLong` = ?,
float `$accelerationMaxLong` = ?,
float `$accelerationInitShort` = ?,
float `$accelerationShort` = ?,
float `$accelerationMaxShort` = ?
): array

### Parâmetros

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`startValue`

  Valor inicial e direção. 0 para Automático, > 0 para Longo, < 0 para Curto. Intervalo válido de TRADER_REAL_MIN a TRADER_REAL_MAX.

`offsetOnReverse`

  Deslocamento percentual adicionado/removido do stop inicial na reversão curta/longa. Intervalo válido de 0 a TRADER_REAL_MAX.

`accelerationInitLong`

  Valor inicial do Fator de Aceleração para a direção Longa. Intervalo válido de 0 a TRADER_REAL_MAX.

`accelerationLong`

  Fator de Aceleração para a direção Longa. Intervalo válido de 0 a TRADER_REAL_MAX.

`accelerationMaxLong`

  Valor máximo do Fator de Aceleração para a direção Longa. Intervalo válido de 0 a TRADER_REAL_MAX.

`accelerationInitShort`

  Valor inicial do Fator de Aceleração para a direção Curta. Intervalo válido de 0 a TRADER_REAL_MAX.

`accelerationShort`

  Fator de Aceleração para a direção Curta. Intervalo válido de 0 a TRADER_REAL_MAX.

`accelerationMaxShort`

  Valor máximo do Fator de Aceleração para a direção Curta. Intervalo válido de 0 a TRADER_REAL_MAX.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_set_compat

(PECL trader >= 0.2.2)

trader_set_compat — Define o modo de compatibilidade

### Descrição

function trader_set_compat(int `$compatId`): void

Define o modo de compatibilidade que afetará a maneira como os cálculos são feitos por todas as funções de extensão.

### Parâmetros

`compatId`

  ID de compatibilidade. A série de constantes TRADER_COMPATIBILITY_* deve ser usada.

### Valor Retornado

Nenhum valor é retornado.

# trader_set_unstable_period

(PECL trader >= 0.2.2)

trader_set_unstable_period — Define período instável

### Descrição

function trader_set_unstable_period(int `$functionId`, int `$timePeriod`): void

Influencia o fator de período instável para funções sensíveis a ele. Mais informações sobre períodos instáveis ​​podem ser encontradas na página de documentação da API » TA-Lib.

### Parâmetros

`functionId`

  O ID da função para o qual o fator deve ser definido. A série constante TRADER_FUNC_UNST_* pode ser usada para afetar a função correspondente.

`timePeriod`

  Valor do período instável.

### Valor Retornado

Nenhum valor é retornado.

# trader_sin

(PECL trader >= 0.2.0)

trader_sin — Seno trigonométrico vetorial

### Descrição

function trader_sin(array `$real`): array

Calcula o seno para cada valor em `real` e retorna o array resultante.

### Parâmetros

`real`

  Array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_sinh

(PECL trader >= 0.2.0)

trader_sinh — Seno hiperbólico trigonométrico vetorial

### Descrição

function trader_sinh(array `$real`): array

Calcula o seno hiperbólico para cada valor em `real` e retorna o array resultante.

### Parâmetros

`real`

  Array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_sma

(PECL trader >= 0.2.0)

trader_sma — Média Móvel Simples

### Descrição

function trader_sma(array `$real`, int `$timePeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_sqrt

(PECL trader >= 0.2.0)

trader_sqrt — Raiz quadrada vetorial

### Descrição

function trader_sqrt(array `$real`): array

Calcula a raiz quadrada de cada valor em `real` e retorna o array resultante.

### Parâmetros

`real`

  Array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_stddev

(PECL trader >= 0.2.0)

trader_stddev — Desvio Padrão

### Descrição

function trader_stddev(array `$real`, int `$timePeriod` = ?, float `$nbDev` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

`nbDev`

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_stoch

(PECL trader >= 0.2.0)

trader_stoch — Estocástico

### Descrição

function trader_stoch(
array `$high`,
array `$low`,
array `$close`,
int `$fastK_Period` = ?,
int `$slowK_Period` = ?,
int `$slowK_MAType` = ?,
int `$slowD_Period` = ?,
int `$slowD_MAType` = ?
): array

### Parâmetros

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

`fastK_Period`

  Período de tempo para a construção da linha Fast-K. Intervalo válido de 1 a 100000.

`slowK_Period`

  Suavização na construção da linha Slow-K. Intervalo válido de 1 a 100000, geralmente 3.

`slowK_MAType`

  Tipo de Média Móvel para o Slow-K. As constantes TRADER_MA_TYPE_* devem ser usadas.

`slowD_Period`

  Suavização na construção da linha Slow-D. Intervalo válido de 1 a 100000.

`slowD_MAType`

  Tipo de Média Móvel para o Slow-D. As constantes TRADER_MA_TYPE_* devem ser usadas.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_stochf

(PECL trader >= 0.2.0)

trader_stochf — Estocástico Rápido

### Descrição

function trader_stochf(
array `$high`,
array `$low`,
array `$close`,
int `$fastK_Period` = ?,
int `$fastD_Period` = ?,
int `$fastD_MAType` = ?
): array

### Parâmetros

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

`fastK_Period`

  Período de tempo para a construção da linha Fast-K. Intervalo válido de 1 a 100000.

`fastD_Period`

  Suavização na construção da linha Fast-D. Intervalo válido de 1 a 100000, geralmente 3.

`fastD_MAType`

  Tipo de Média Móvel para o Fast-D. As constantes TRADER_MA_TYPE_* devem ser usadas.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_stochrsi

(PECL trader >= 0.2.0)

trader_stochrsi — Índice de Força Relativa Estocástica

### Descrição

function trader_stochrsi(
array `$real`,
int `$timePeriod` = ?,
int `$fastK_Period` = ?,
int `$fastD_Period` = ?,
int `$fastD_MAType` = ?
): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

`fastK_Period`

  Período de tempo para a construção da linha Fast-K. Intervalo válido de 1 a 100000.

`fastD_Period`

  Suavização na construção da linha Fast-D. Intervalo válido de 1 a 100000, geralmente 3.

`fastD_MAType`

  Tipo de Média Móvel para o Fast-D. As constantes TRADER_MA_TYPE_* devem ser usadas.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_sub

(PECL trader >= 0.2.0)

trader_sub — Subtração Aritmética Vetorial

### Descrição

function trader_sub(array `$real0`, array `$real1`): array

Calcula a subtração vetorial de `real1` de `real0` e retorna o vetor resultante.

### Parâmetros

`real0`

  Array de valores reais.

`real1`

  Array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_sum

(PECL trader >= 0.2.0)

trader_sum — Somatória

### Descrição

function trader_sum(array `$real`, int `$timePeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_t3

(PECL trader >= 0.2.0)

trader_t3 — Média Móvel Exponencial Tripla (T3)

### Descrição

function trader_t3(array `$real`, int `$timePeriod` = ?, float `$vFactor` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

`vFactor`

  Fator de volume. Intervalo válido de 1 a 0.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_tan

(PECL trader >= 0.2.0)

trader_tan — Tangente trigonométrica vetorial

### Descrição

function trader_tan(array `$real`): array

Calcula a tangente para cada valor em `real` e retorna o array resultante.

### Parâmetros

`real`

  Array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_tanh

(PECL trader >= 0.2.0)

trader_tanh — Tangente Hiperbólica Trigonométrica Vetorial

### Descrição

function trader_tanh(array `$real`): array

Calcula a tangente hperbólica para cada valor em `real` e retorna o array resultante.

### Parâmetros

`real`

  Array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_tema

(PECL trader >= 0.2.0)

trader_tema — Média Móvel Exponencial Tripla

### Descrição

function trader_tema(array `$real`, int `$timePeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_trange

(PECL trader >= 0.2.0)

trader_trange — Intervalo Verdadeiro

### Descrição

function trader_trange(array `$high`, array `$low`, array `$close`): array

### Parâmetros

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_trima

(PECL trader >= 0.2.0)

trader_trima — Média Móvel Triangular

### Descrição

function trader_trima(array `$real`, int `$timePeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_trix

(PECL trader >= 0.2.0)

trader_trix — Taxa de variação (ROC) de 1 dia de uma EMA triplamente suave

### Descrição

function trader_trix(array `$real`, int `$timePeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_tsf

(PECL trader >= 0.2.0)

trader_tsf — Previsão de série temporal

### Descrição

function trader_tsf(array `$real`, int `$timePeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_typprice

(PECL trader >= 0.2.0)

trader_typprice — Preço típico

### Descrição

function trader_typprice(array `$high`, array `$low`, array `$close`): array

### Parâmetros

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_ultosc

(PECL trader >= 0.2.0)

trader_ultosc — Oscilador Final

### Descrição

function trader_ultosc(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod1` = ?,
int `$timePeriod2` = ?,
int `$timePeriod3` = ?
): array

### Parâmetros

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

`timePeriod1`

  Number of bars for 1st period. Valid range from 1 to 100000.

`timePeriod2`

  Number of bars for 2nd period. Valid range from 1 to 100000.

`timePeriod3`

  Number of bars for 3rd period. Valid range from 1 to 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_var

(PECL trader >= 0.2.0)

trader_var — Variância

### Descrição

function trader_var(array `$real`, int `$timePeriod` = ?, float `$nbDev` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

`nbDev`

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_wclprice

(PECL trader >= 0.2.0)

trader_wclprice — Preço de fechamento ponderado

### Descrição

function trader_wclprice(array `$high`, array `$low`, array `$close`): array

### Parâmetros

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_willr

(PECL trader >= 0.2.0)

trader_willr — %R de Williams

### Descrição

function trader_willr(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Parâmetros

`high`

  Preço alto, array de valores reais.

`low`

  Preço baixo, array de valores reais.

`close`

  Preço de fechamento, array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

# trader_wma

(PECL trader >= 0.2.0)

trader_wma — Média Móvel Ponderada

### Descrição

function trader_wma(array `$real`, int `$timePeriod` = ?): array

### Parâmetros

`real`

  Array de valores reais.

`timePeriod`

  Número de período. Intervalo válido de 2 a 100000.

### Valor Retornado

Retorna um array com os dados calculados ou false em caso de falha.

## Índice

- trader_acos — Arco cosseno trigonométrico vetorial
- trader_ad — Linha Chaikin A/D
- trader_add — Adição Aritmética Vetorial
- trader_adosc — Oscilador A/D Chaikin
- trader_adx — Índice de Movimento Direcional Médio
- trader_adxr — Taxa do Índice de Movimento Direcional Médio
- trader_apo — Oscilador de Preço Absoluto
- trader_aroon — Aroon
- trader_aroonosc — Oscilador Aroon
- trader_asin — Arco seno trigonométrico vetorial
- trader_atan — Arco Tangente Trigonométrico Vetorial
- trader_atr — Intervalo Verdadeiro Média
- trader_avgprice — Preço médio
- trader_bbands — Bandas de Bollinger
- trader_beta — Beta
- trader_bop — Equilíbrio de poder
- trader_cci — Índice de Canal de Commodities
- trader_cdl2crows — Dois corvos
- trader_cdl3blackcrows — Três Corvos Negros
- trader_cdl3inside — Três velas internas para cima/baixo
- trader_cdl3linestrike — Strike de três linhas
- trader_cdl3outside — Três exteriores para cima/baixo
- trader_cdl3starsinsouth — Três Estrelas no Sul
- trader_cdl3whitesoldiers — Três Soldados Brancos Avançando
- trader_cdlabandonedbaby — Bebê Abandonado
- trader_cdladvanceblock — Bloco Avançado
- trader_cdlbelthold — Cinturão de Espera
- trader_cdlbreakaway — Lacuna de Ruptura
- trader_cdlclosingmarubozu — Marubozu de Fechamento
- trader_cdlconcealbabyswall — Engolimento de Bebê Escondido
- trader_cdlcounterattack — Contra-ataque
- trader_cdldarkcloudcover — Nuvem Negra
- trader_cdldoji — Doji
- trader_cdldojistar — Doji Estrela
- trader_cdldragonflydoji — Doji Libélula
- trader_cdlengulfing — Padrão de Engolimento
- trader_cdleveningdojistar — Doji Estrela da Noite
- trader_cdleveningstar — Estrela da Noite
- trader_cdlgapsidesidewhite — Linhas brancas lado a lado com gap de alta/baixa
- trader_cdlgravestonedoji — Doji Lápide
- trader_cdlhammer — Martelo
- trader_cdlhangingman — Homem enforcado
- trader_cdlharami — Harami
- trader_cdlharamicross — Cruz Harami
- trader_cdlhighwave — Vela de onda alta
- trader_cdlhikkake — Hikkake
- trader_cdlhikkakemod — Hikkake Modificado
- trader_cdlhomingpigeon — Ave Migratória
- trader_cdlidentical3crows — Três Corvos Idênticos
- trader_cdlinneck — In-Neck
- trader_cdlinvertedhammer — Martelo Invertido
- trader_cdlkicking — Chute nos pneus
- trader_cdlkickingbylength — Chute - touro/urso determinado pelo Marubozu mais longo
- trader_cdlladderbottom — Escada de Baixo
- trader_cdllongleggeddoji — Doji de Pernas Compridas
- trader_cdllongline — Vela de Linha Longa
- trader_cdlmarubozu — Marubozu
- trader_cdlmatchinglow — Matching Low
- trader_cdlmathold — Aperto do Mat
- trader_cdlmorningdojistar — Estrela da Manhã Doji
- trader_cdlmorningstar — Estrela da Manhã
- trader_cdlonneck — On-Neck
- trader_cdlpiercing — Piercing
- trader_cdlrickshawman — Homem da Carruagem
- trader_cdlrisefall3methods — Três Métodos de Subida/Descida
- trader_cdlseparatinglines — Linhas de Separação
- trader_cdlshootingstar — Estrela Cadente
- trader_cdlshortline — Vela de Linha Curta
- trader_cdlspinningtop — Pião Giratório
- trader_cdlstalledpattern — Padrão de Deliberação
- trader_cdlsticksandwich — Vela Prensada
- trader_cdltakuri — Takuri (Doji Libélula com sombra inferior muito longa)
- trader_cdltasukigap — Lacuna Tasuki
- trader_cdlthrusting — Thrusting
- trader_cdltristar — Tri-Star
- trader_cdlunique3river — Unique 3 River
- trader_cdlupsidegap2crows — Dois Corvos de Alta com Gap
- trader_cdlxsidegap3methods — Três Métodos de Lacunas Positivas/Negativas
- trader_ceil — Teto vetorial
- trader_cmo — Oscilador de Momentum Chande
- trader_correl — Coeficiente de correlação de Pearson (r)
- trader_cos — Cosseno Trigonométrico Vetorial
- trader_cosh — Cosseno Hiperbólico Trigonométrico Vetorial
- trader_dema — Média Móvel Exponencial Dupla
- trader_div — Divisão Aritmética Vetorial
- trader_dx — Índice de movimento direcional
- trader_ema — Média Móvel Exponencial
- trader_errno — Obtém código de erro
- trader_exp — Exponenciação Aritmética Vetorial
- trader_floor — Piso Vetorial
- trader_get_compat — Obtém modo de compatibilidade
- trader_get_unstable_period — Obtém o período instável
- trader_ht_dcperiod — Transformada de Hilbert - Período do Ciclo Dominante
- trader_ht_dcphase — Transformada de Hilbert - Fase do Ciclo Dominante
- trader_ht_phasor — Transformada de Hilbert - Componentes Fasoriais
- trader_ht_sine — Transformada de Hilbert - Onda Senoidal
- trader_ht_trendline — Transformada de Hilbert - Linha de Tendência Instantânea
- trader_ht_trendmode — Transformada de Hilbert - Modo de Tendência vs. Modo de Ciclo
- trader_kama — Média Móvel Adaptativa de Kaufman
- trader_linearreg — Regressão Linear
- trader_linearreg_angle — Ângulo de Regressão Linear
- trader_linearreg_intercept — Interceptação de regressão linear
- trader_linearreg_slope — Inclinação da regressão linear
- trader_ln — Logaitmo natural vetorial
- trader_log10 — Log10 Vetorial
- trader_ma — Média móvel
- trader_macd — Convergência/Divergência da Média Móvel
- trader_macdext — Convergência/Divergência da Média Móvel com tipo MM controlável
- trader_macdfix — Convergência/Divergência da Média Móvel Fixa 26/12
- trader_mama — Média Móvel Adaptativa MESA
- trader_mavp — Média móvel com período variável
- trader_max — Maior valor em um período especificado
- trader_maxindex — Índice de maior valor em um período especificado
- trader_medprice — Preço mediano
- trader_mfi — Índice de Fluxo de Dinheiro
- trader_midpoint — Ponto médio ao longo do período
- trader_midprice — Preço do ponto médio ao longo do período
- trader_min — Menor valor em um período especificado
- trader_minindex — Índice de menor valor em um período especificado
- trader_minmax — Valores mais baixos e mais altos durante um período especificado
- trader_minmaxindex — Índices de valores mais baixos e mais altos durante um período especificado
- trader_minus_di — Indicador direcional negativo
- trader_minus_dm — Movimento Direcional Negativo
- trader_mom — Momento
- trader_mult — Multiplicação Aritmética Vetorial
- trader_natr — Intervalo médio verdadeiro normalizado
- trader_obv — Volume em Equilíbrio
- trader_plus_di — Indicador Direcional Positivo
- trader_plus_dm — Movimento Direcional Positivo
- trader_ppo — Oscilador de Preço Percentual
- trader_roc — Taxa de variação: ((preço/preçoAnterior)-1)*100
- trader_rocp — Taxa de variação Percentual: (preço-preçoAnterior)/preçoAnterior
- trader_rocr — Taxa de variação: (preço/preçoAnterior)
- trader_rocr100 — Taxa de variação na escala 100: (preço/preçoAnterior)*100
- trader_rsi — Índice de Força Relativa
- trader_sar — SAR parabólico
- trader_sarext — SAR Parabólico - Estendido
- trader_set_compat — Define o modo de compatibilidade
- trader_set_unstable_period — Define período instável
- trader_sin — Seno trigonométrico vetorial
- trader_sinh — Seno hiperbólico trigonométrico vetorial
- trader_sma — Média Móvel Simples
- trader_sqrt — Raiz quadrada vetorial
- trader_stddev — Desvio Padrão
- trader_stoch — Estocástico
- trader_stochf — Estocástico Rápido
- trader_stochrsi — Índice de Força Relativa Estocástica
- trader_sub — Subtração Aritmética Vetorial
- trader_sum — Somatória
- trader_t3 — Média Móvel Exponencial Tripla (T3)
- trader_tan — Tangente trigonométrica vetorial
- trader_tanh — Tangente Hiperbólica Trigonométrica Vetorial
- trader_tema — Média Móvel Exponencial Tripla
- trader_trange — Intervalo Verdadeiro
- trader_trima — Média Móvel Triangular
- trader_trix — Taxa de variação (ROC) de 1 dia de uma EMA triplamente suave
- trader_tsf — Previsão de série temporal
- trader_typprice — Preço típico
- trader_ultosc — Oscilador Final
- trader_var — Variância
- trader_wclprice — Preço de fechamento ponderado
- trader_willr — %R de Williams
- trader_wma — Média Móvel Ponderada

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
- Constantes predefinidas
- Funções de Trader
  - trader_acos — Arco cosseno trigonométrico vetorial
  - trader_ad — Linha Chaikin A/D
  - trader_add — Adição Aritmética Vetorial
  - trader_adosc — Oscilador A/D Chaikin
  - trader_adx — Índice de Movimento Direcional Médio
  - trader_adxr — Taxa do Índice de Movimento Direcional Médio
  - trader_apo — Oscilador de Preço Absoluto
  - trader_aroon — Aroon
  - trader_aroonosc — Oscilador Aroon
  - trader_asin — Arco seno trigonométrico vetorial
  - trader_atan — Arco Tangente Trigonométrico Vetorial
  - trader_atr — Intervalo Verdadeiro Média
  - trader_avgprice — Preço médio
  - trader_bbands — Bandas de Bollinger
  - trader_beta — Beta
  - trader_bop — Equilíbrio de poder
  - trader_cci — Índice de Canal de Commodities
  - trader_cdl2crows — Dois corvos
  - trader_cdl3blackcrows — Três Corvos Negros
  - trader_cdl3inside — Três velas internas para cima/baixo
  - trader_cdl3linestrike — Strike de três linhas
  - trader_cdl3outside — Três exteriores para cima/baixo
  - trader_cdl3starsinsouth — Três Estrelas no Sul
  - trader_cdl3whitesoldiers — Três Soldados Brancos Avançando
  - trader_cdlabandonedbaby — Bebê Abandonado
  - trader_cdladvanceblock — Bloco Avançado
  - trader_cdlbelthold — Cinturão de Espera
  - trader_cdlbreakaway — Lacuna de Ruptura
  - trader_cdlclosingmarubozu — Marubozu de Fechamento
  - trader_cdlconcealbabyswall — Engolimento de Bebê Escondido
  - trader_cdlcounterattack — Contra-ataque
  - trader_cdldarkcloudcover — Nuvem Negra
  - trader_cdldoji — Doji
  - trader_cdldojistar — Doji Estrela
  - trader_cdldragonflydoji — Doji Libélula
  - trader_cdlengulfing — Padrão de Engolimento
  - trader_cdleveningdojistar — Doji Estrela da Noite
  - trader_cdleveningstar — Estrela da Noite
  - trader_cdlgapsidesidewhite — Linhas brancas lado a lado com gap de alta/baixa
  - trader_cdlgravestonedoji — Doji Lápide
  - trader_cdlhammer — Martelo
  - trader_cdlhangingman — Homem enforcado
  - trader_cdlharami — Harami
  - trader_cdlharamicross — Cruz Harami
  - trader_cdlhighwave — Vela de onda alta
  - trader_cdlhikkake — Hikkake
  - trader_cdlhikkakemod — Hikkake Modificado
  - trader_cdlhomingpigeon — Ave Migratória
  - trader_cdlidentical3crows — Três Corvos Idênticos
  - trader_cdlinneck — In-Neck
  - trader_cdlinvertedhammer — Martelo Invertido
  - trader_cdlkicking — Chute nos pneus
  - trader_cdlkickingbylength — Chute - touro/urso determinado pelo Marubozu mais longo
  - trader_cdlladderbottom — Escada de Baixo
  - trader_cdllongleggeddoji — Doji de Pernas Compridas
  - trader_cdllongline — Vela de Linha Longa
  - trader_cdlmarubozu — Marubozu
  - trader_cdlmatchinglow — Matching Low
  - trader_cdlmathold — Aperto do Mat
  - trader_cdlmorningdojistar — Estrela da Manhã Doji
  - trader_cdlmorningstar — Estrela da Manhã
  - trader_cdlonneck — On-Neck
  - trader_cdlpiercing — Piercing
  - trader_cdlrickshawman — Homem da Carruagem
  - trader_cdlrisefall3methods — Três Métodos de Subida/Descida
  - trader_cdlseparatinglines — Linhas de Separação
  - trader_cdlshootingstar — Estrela Cadente
  - trader_cdlshortline — Vela de Linha Curta
  - trader_cdlspinningtop — Pião Giratório
  - trader_cdlstalledpattern — Padrão de Deliberação
  - trader_cdlsticksandwich — Vela Prensada
  - trader_cdltakuri — Takuri (Doji Libélula com sombra inferior muito longa)
  - trader_cdltasukigap — Lacuna Tasuki
  - trader_cdlthrusting — Thrusting
  - trader_cdltristar — Tri-Star
  - trader_cdlunique3river — Unique 3 River
  - trader_cdlupsidegap2crows — Dois Corvos de Alta com Gap
  - trader_cdlxsidegap3methods — Três Métodos de Lacunas Positivas/Negativas
  - trader_ceil — Teto vetorial
  - trader_cmo — Oscilador de Momentum Chande
  - trader_correl — Coeficiente de correlação de Pearson (r)
  - trader_cos — Cosseno Trigonométrico Vetorial
  - trader_cosh — Cosseno Hiperbólico Trigonométrico Vetorial
  - trader_dema — Média Móvel Exponencial Dupla
  - trader_div — Divisão Aritmética Vetorial
  - trader_dx — Índice de movimento direcional
  - trader_ema — Média Móvel Exponencial
  - trader_errno — Obtém código de erro
  - trader_exp — Exponenciação Aritmética Vetorial
  - trader_floor — Piso Vetorial
  - trader_get_compat — Obtém modo de compatibilidade
  - trader_get_unstable_period — Obtém o período instável
  - trader_ht_dcperiod — Transformada de Hilbert - Período do Ciclo Dominante
  - trader_ht_dcphase — Transformada de Hilbert - Fase do Ciclo Dominante
  - trader_ht_phasor — Transformada de Hilbert - Componentes Fasoriais
  - trader_ht_sine — Transformada de Hilbert - Onda Senoidal
  - trader_ht_trendline — Transformada de Hilbert - Linha de Tendência Instantânea
  - trader_ht_trendmode — Transformada de Hilbert - Modo de Tendência vs. Modo de Ciclo
  - trader_kama — Média Móvel Adaptativa de Kaufman
  - trader_linearreg — Regressão Linear
  - trader_linearreg_angle — Ângulo de Regressão Linear
  - trader_linearreg_intercept — Interceptação de regressão linear
  - trader_linearreg_slope — Inclinação da regressão linear
  - trader_ln — Logaitmo natural vetorial
  - trader_log10 — Log10 Vetorial
  - trader_ma — Média móvel
  - trader_macd — Convergência/Divergência da Média Móvel
  - trader_macdext — Convergência/Divergência da Média Móvel com tipo MM controlável
  - trader_macdfix — Convergência/Divergência da Média Móvel Fixa 26/12
  - trader_mama — Média Móvel Adaptativa MESA
  - trader_mavp — Média móvel com período variável
  - trader_max — Maior valor em um período especificado
  - trader_maxindex — Índice de maior valor em um período especificado
  - trader_medprice — Preço mediano
  - trader_mfi — Índice de Fluxo de Dinheiro
  - trader_midpoint — Ponto médio ao longo do período
  - trader_midprice — Preço do ponto médio ao longo do período
  - trader_min — Menor valor em um período especificado
  - trader_minindex — Índice de menor valor em um período especificado
  - trader_minmax — Valores mais baixos e mais altos durante um período especificado
  - trader_minmaxindex — Índices de valores mais baixos e mais altos durante um período especificado
  - trader_minus_di — Indicador direcional negativo
  - trader_minus_dm — Movimento Direcional Negativo
  - trader_mom — Momento
  - trader_mult — Multiplicação Aritmética Vetorial
  - trader_natr — Intervalo médio verdadeiro normalizado
  - trader_obv — Volume em Equilíbrio
  - trader_plus_di — Indicador Direcional Positivo
  - trader_plus_dm — Movimento Direcional Positivo
  - trader_ppo — Oscilador de Preço Percentual
  - trader_roc — Taxa de variação: ((preço/preçoAnterior)-1)*100
  - trader_rocp — Taxa de variação Percentual: (preço-preçoAnterior)/preçoAnterior
  - trader_rocr — Taxa de variação: (preço/preçoAnterior)
  - trader_rocr100 — Taxa de variação na escala 100: (preço/preçoAnterior)*100
  - trader_rsi — Índice de Força Relativa
  - trader_sar — SAR parabólico
  - trader_sarext — SAR Parabólico - Estendido
  - trader_set_compat — Define o modo de compatibilidade
  - trader_set_unstable_period — Define período instável
  - trader_sin — Seno trigonométrico vetorial
  - trader_sinh — Seno hiperbólico trigonométrico vetorial
  - trader_sma — Média Móvel Simples
  - trader_sqrt — Raiz quadrada vetorial
  - trader_stddev — Desvio Padrão
  - trader_stoch — Estocástico
  - trader_stochf — Estocástico Rápido
  - trader_stochrsi — Índice de Força Relativa Estocástica
  - trader_sub — Subtração Aritmética Vetorial
  - trader_sum — Somatória
  - trader_t3 — Média Móvel Exponencial Tripla (T3)
  - trader_tan — Tangente trigonométrica vetorial
  - trader_tanh — Tangente Hiperbólica Trigonométrica Vetorial
  - trader_tema — Média Móvel Exponencial Tripla
  - trader_trange — Intervalo Verdadeiro
  - trader_trima — Média Móvel Triangular
  - trader_trix — Taxa de variação (ROC) de 1 dia de uma EMA triplamente suave
  - trader_tsf — Previsão de série temporal
  - trader_typprice — Preço típico
  - trader_ultosc — Oscilador Final
  - trader_var — Variância
  - trader_wclprice — Preço de fechamento ponderado
  - trader_willr — %R de Williams
  - trader_wma — Média Móvel Ponderada

- BC Math — Funções matemáticas de precisão arbitrária
  - Instalação/Configuração
  - BC Math Funções
  - BcMath\Number — A classe BcMath\Number
- GMP — Precisão Múltipla GNU
  - Instalação/Configuração
  - Constantes predefinidas
  - Exemplos
  - Funções GMP
  - GMP — A classe GMP
- Math — Funções Matemáticas
  - Constantes predefinidas
  - RoundingMode — A enumeração RoundingMode
  - Funções de Math
- Estatísticas
  - Instalação/Configuração
  - Funções de Statistic
- Trader — Análise Técnica para Negociadores
  - Instalação/Configuração
  - Constantes predefinidas
  - Funções de Trader

# Saída de MIME Não-Texto

# Formato de dados de formulários

# Introdução

Forms Data Format (FDF) é um formato para lidar com formulários em documentos PDF. Deve-se ler a documentação em » http://www.adobe.com/devnet/acrobat/fdftoolkit.html para obter mais informações sobre o que é FDF e como ele é usado em geral.

A ideia geral do FDF é semelhante aos formulários HTML. A diferença é basicamente o formato como os dados são transmitidos ao servidor quando o botão de envio é pressionado (na verdade, este é o Form Data Format) e o formato do formulário em si (que é o Portable Document Format, PDF). O processamento dos dados FDF é um dos recursos fornecidos pelas funções fdf. Mas há mais. Pode-se também pegar um formulário PDF existente e preencher os campos de entrada com dados sem modificar o formulário em si. Nesse caso, criaria-se um documento FDF (fdf_create()), definiria-se os valores de cada campo de entrada (fdf_set_value()) e associaria-se este documento a um formulário PDF (fdf_set_file()). Finalmente, ele deve ser enviado ao navegador com MimeType `application/vnd.fdf`. O plug-in do leitor Acrobat do navegador reconhece o MimeType, lê o formulário PDF associado e preenche os dados do documento FDF.

Se um documento FDF for aberto em um editor de texto, será encontrado um objeto de catálogo com o nome `FDF`. Esse objeto pode conter várias entradas como `Fields`, `F`, `Status` etc. As entradas mais comumente usadas são `Fields`, que aponta para uma lista de campos de entrada, e `F`, que contém o nome do arquivo do documento PDF ao qual esses dados pertencem. Essas entradas são referidas na documentação do FDF como /F-Key ou /Status-Key. A modificação dessas entradas é feita por funções como fdf_set_file() e fdf_set_status(). Os campos são modificados com fdf_set_value(), fdf_set_opt() etc.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Tipos de Recurso

## Dependências

Será necessário o SDK do kit de ferramentas FDF, disponível em » http://www.adobe.com/devnet/acrobat/fdftoolkit.html. A partir do PHP 4.3.0, é necessária pelo menos a versão 5.0 do SDK. A biblioteca do kit de ferramentas FDF está disponível apenas em formato binário, as plataformas suportadas pela Adobe são Win32, Linux, Solaris e AIX.

## Instalação

Esta extensão é considerada sem manutenção e abandonada. No entanto, o código-fonte desta extensão ainda está disponível no SVN do PECL aqui: » https://svn.php.net/viewvc/pecl/fdf.

Esta extensão não está mais incluída no PHP.

> Nota: Se houver problemas ao configurar o PHP com suporte a fdftk, verifique se o arquivo de cabeçalho fdftk.h e a biblioteca libfdftk.so estão no lugar certo. O script configure suporta tanto a estrutura de diretório da distribuição do FDF SDK quanto o layout usual DIR/include / DIR/lib, então pode-se apontá-lo diretamente para o diretório de distribuição descompactado ou pode-se colocar o arquivo de cabeçalho e a biblioteca apropriada para a plataforma em, por exemplo, /usr/local/include e /usr/local/lib e configurar com --with-fdftk=/usr/local.

> Nota: Nota para usuários do Win32
> Para que esta extensão funcione, existem arquivos DLL que devem estar disponíveis no PATH do sistema Windows. Para saber como fazer isso, veja a FAQ intitulada "Como eu adiciono o meu diretório PHP ao PATH do Windows". Embora copiar arquivos DLL da pasta do PHP para o diretório system do Windows também funcione (porque o diretório system está, por padrão, no PATH do sistema), isso não é recomendado. Esta extensão requer que os seguintes arquivos estejam no PATH: fdftk.dll

## Tipos de Recurso

A maioria das funções fdf requer um recurso `fdf` como seu primeiro parâmetro. Um recurso `fdf` é um identificador para um arquivo fdf aberto. Recursos `fdf` podem ser obtidos usando fdf_create(), fdf_open() e fdf_open_string().

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

`FDFValue` (int)
`FDFStatus` (int)
`FDFFile` (int)
`FDFID` (int)
`FDFFf` (int)
`FDFSetFf` (int)
`FDFClearFf` (int)
`FDFFlags` (int)
`FDFSetF` (int)
`FDFClrF` (int)
`FDFAP` (int)
`FDFAS` (int)
`FDFAction` (int)
`FDFAA` (int)
`FDFAPRef` (int)
`FDFIF` (int)
`FDFEnter` (int)
`FDFExit` (int)
`FDFDown` (int)
`FDFUp` (int)
`FDFFormat` (int)
`FDFValidate` (int)
`FDFKeystroke` (int)
`FDFCalculate` (int)
`FDFNormalAP` (int)
`FDFRolloverAP` (int)
`FDFDownAP` (int)

# Exemplos

Os exemplos a seguir mostram apenas a avaliação dos dados do formulário.

Exemplo #1 Avaliando um documento FDF

    <?php
    // Abre fdf a partir da string de entrada fornecida pela extensão
    // O formulário pdf continha vários campos de texto de entrada com os nomes
    // volume, date, comment, publisher, preparer, e duas caixas de seleção
    // show_publisher e show_preparer.
    $fdf = fdf_open_string($HTTP_FDF_DATA);
    $volume = fdf_get_value($fdf, "volume");
    echo "O campo volume tem o valor '<b>$volume</b>'<br />";

    $date = fdf_get_value($fdf, "date");
    echo "O campo date tem o valor '<b>$date</b>'<br />";

    $comment = fdf_get_value($fdf, "comment");
    echo "O campo comment tem o valor '<b>$comment</b>'<br />";

    if (fdf_get_value($fdf, "show_publisher") == "On") {
        $publisher = fdf_get_value($fdf, "publisher");
        echo "O campo publisher tem o valor '<b>$publisher</b>'<br />";
    } else
        echo "O publisher não deve ser mostrado.<br />";

    if (fdf_get_value($fdf, "show_preparer") == "On") {
        $preparer = fdf_get_value($fdf, "preparer");
        echo "O campo preparer tem o valor '<b>$preparer</b>'<br />";
    } else
        echo "O preparer não deve ser mostrado.<br />";
    fdf_close($fdf);
    ?>

# Funções de FDF

# fdf_add_doc_javascript

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_add_doc_javascript — Adiciona código javascript ao documento FDF

### Descrição

function fdf_add_doc_javascript(resource `$fdf_document`, string `$script_name`, string `$script_code`): bool

Adiciona um script ao FDF, que o Acrobat então adiciona aos scripts de um documento, uma vez que o FDF é importado para ele.

### Parâmetros

`fdf_document`
  O identificador do documento FDF, retornado por fdf_create(), fdf_open() ou fdf_open_string().
`script_name`
  O nome do script.
`script_code`
  O código do script. É fortemente sugerido usar `\r` para quebras de linha dentro do código do script.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Adicionar código JavaScript a um FDF

    <?php
    $fdf = fdf_create();
    fdf_add_doc_javascript($fdf, "PlusOne", "function PlusOne(x)\r{\r  return x+1;\r}\r");
    fdf_save($fdf);
    ?>

criará um FDF como este:

    %FDF-1.2
    %âãÏÓ
    1 0 obj
    <<
    /FDF << /JavaScript << /Doc [ (PlusOne)(function PlusOne\(x\)\r{\r  return x+1;\r}\r)] >> >>
    >>
    endobj
    trailer
    <<
    /Root 1 0 R

    >>
    %%EOF

# fdf_add_template

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_add_template — Adiciona um modelo ao documento FDF

### Descrição

function fdf_add_template(
resource `$fdf_document`,
int `$newpage`,
string `$filename`,
string `$template`,
int `$rename`
): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

# fdf_close

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_close — Fecha um documento FDF

### Descrição

function fdf_close(resource `$fdf_document`): void

Fecha o documento FDF

### Parâmetros

`fdf_document`
  O identificador do documento FDF, retornado por fdf_create(), fdf_open() ou fdf_open_string().

### Valor Retornado

Nenhum valor é retornado.

### Veja Também

- fdf_open() - Abre um documento FDF

# fdf_create

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_create — Cria um novo documento FDF

### Descrição

function fdf_create(): resource

Cria um novo documento FDF.

Esta função é necessária se a intenção for preencher campos de entrada em um documento PDF com dados.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna um identificador de documento FDF ou `false` em caso de erro.

### Exemplos

Exemplo #1 Preenchendo um documento PDF

    <?php
    $outfdf = fdf_create();
    fdf_set_value($outfdf, "volume", $volume, 0);

    fdf_set_file($outfdf, "http:/testfdf/resultlabel.pdf");
    fdf_save($outfdf, "outtest.fdf");
    fdf_close($outfdf);
    Header("Content-type: application/vnd.fdf");
    $fp = fopen("outtest.fdf", "r");
    fpassthru($fp);
    unlink("outtest.fdf");
    ?>

### Veja Também

- fdf_close() - Fecha um documento FDF
- fdf_save() - Salva um documento FDF
- fdf_open() - Abre um documento FDF

# fdf_enum_values

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_enum_values — Chama uma função definida pelo usuário para cada valor do documento

### Descrição

function fdf_enum_values(resource `$fdf_document`, callable `$function`, mixed `$userdata` = ?): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

# fdf_errno

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_errno — Retorna o código de erro para a última operação fdf

### Descrição

function fdf_errno(): int

Obtém o código de erro definido pela última chamada de função FDF.

Uma descrição textual do erro pode ser obtida usando fdf_error().

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna o código de erro como um inteiro ou zero se não houver erros.

### Veja Também

- fdf_error() - Retorna a descrição do erro para o código de erro FDF

# fdf_error

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_error — Retorna a descrição do erro para o código de erro FDF

### Descrição

function fdf_error(int `$error_code` = -1): string

Obtém uma descrição textual para o código de erro FDF fornecido em `error_code`.

### Parâmetros

`error_code`
  Um código de erro obtido com fdf_errno(). Se não fornecido, esta função usa o código de erro interno definido pela última operação.

### Valor Retornado

Retorna a mensagem de erro como uma string, ou a string `no error` se nada deu errado.

### Veja Também

- fdf_errno() - Retorna o código de erro para a última operação fdf

# fdf_get_ap

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_ap — Obtém a aparência de um campo

### Descrição

function fdf_get_ap(
resource `$fdf_document`,
string `$field`,
int `$face`,
string `$filename`
): bool

Obtém a aparência de um campo informado no parâmetro `field` (ou seja, o valor da chave /AP) e o armazena em um arquivo.

### Parâmetros

`fdf_document`
  O identificador do documento FDF, retornado por fdf_create(), fdf_open() ou fdf_open_string().
`field`
`face`
  Os valores possíveis são `FDFNormalAP`, `FDFRolloverAP` e `FDFDownAP`.
`filename`
  A aparência será armazenada neste parâmetro.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# fdf_get_attachment

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_attachment — Extrai o arquivo carregado incorporado no FDF

### Descrição

function fdf_get_attachment(resource `$fdf_document`, string `$fieldname`, string `$savepath`): array

Extrai um arquivo carregado por meio do campo "file selection" `fieldname` e o armazena em `savepath`.

### Parâmetros

`fdf_document`
  O identificador do documento FDF, retornado por fdf_create(), fdf_open() ou fdf_open_string().
`fieldname`
`savepath`
  Pode ser o nome de um arquivo simples ou um diretório existente no qual o arquivo deve ser criado sob seu nome original. Qualquer arquivo existente sob o mesmo nome será sobrescrito.

  > Nota: Parece não haver outra maneira de descobrir o nome do arquivo original, a não ser armazenar o arquivo usando um diretório como `savepath` e verificar o nome base em que ele foi armazenado.

### Valor Retornado

O array retornado contém os seguintes campos:

- `path` - caminho onde o arquivo foi armazenado
- `size` - tamanho do arquivo armazenado em bytes
- `type` - tipo de mídia se fornecido no FDF

### Exemplos

Exemplo #1 Armazenando um arquivo carregado

    <?php
      $fdf = fdf_open_string($HTTP_FDF_DATA);
      $data = fdf_get_attachment($fdf, "filename", "/tmpdir");
      echo "O arquivo enviado está armazenado em $data[path]";
    ?>

# fdf_get_encoding

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_encoding — Obtém o valor da chave /Encoding

### Descrição

function fdf_get_encoding(resource `$fdf_document`): string

Obtém o valor da chave `/Encoding`.

### Parâmetros

`fdf_document`
  O identificador do documento FDF, retornado por fdf_create(), fdf_open() ou fdf_open_string().

### Valor Retornado

Retorna a codificação como uma string. Uma string vazia é retornada se o esquema `PDFDocEncoding/Unicode` padrão for usado.

### Veja Também

- fdf_set_encoding() - Define a codificação de caracteres FDF

# fdf_get_file

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_file — Obtém o valor da chave /F

### Descrição

function fdf_get_file(resource `$fdf_document`): string

Obtém o valor da chave `/F`.

### Parâmetros

`fdf_document`
  O identificador do documento FDF, retornado por fdf_create(), fdf_open() ou fdf_open_string().

### Valor Retornado

Retorna o valor da chave, como uma string.

### Veja Também

- fdf_set_file() - Define o documento PDF para exibição de dados FDF

# fdf_get_flags

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_flags — Obtém os sinalizadores de um campo

### Descrição

function fdf_get_flags(resource `$fdf_document`, string `$fieldname`, int `$whichflags`): int
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

# fdf_get_opt

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECLv)

fdf_get_opt — Obtém um valor do array de opções de um campo

### Descrição

function fdf_get_opt(resource `$fdf_document`, string `$fieldname`, int `$element` = -1): mixed
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

# fdf_get_status

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_status — Obtém o valor da chave /STATUS

### Descrição

function fdf_get_status(resource `$fdf_document`): string

Obtém o valor da chave `/STATUS`.

### Parâmetros

`fdf_document`
  O identificador do documento FDF, retornado por fdf_create(), fdf_open() ou fdf_open_string().

### Valor Retornado

Retorna o valor da chave, como uma string.

### Veja Também

- fdf_set_status() - Define o valor da chave /STATUS

# fdf_get_value

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_value — Obtém o valor de um campo

### Descrição

function fdf_get_value(resource `$fdf_document`, string `$fieldname`, int `$which` = -1): mixed

Obtém o valor do campo solicitado.

### Parâmetros

`fdf_document`
  O identificador do documento FDF, retornado por fdf_create(), fdf_open() ou fdf_open_string().
`fieldname`
  Nome do campo FDF, como uma string.
`which`
  Elementos de um campo array podem ser recuperados passando este parâmetro opcional, começando em zero. Para campos não array, este parâmetro será ignorado.

### Valor Retornado

Retorna o valor do campo.

### Veja Também

- fdf_set_value() - Define o valor de um campo

# fdf_get_version

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_version — Obtém o número da versão para a API ou arquivo FDF

### Descrição

function fdf_get_version(resource `$fdf_document` = ?): string

Retorna a versão FDF para o documento fornecido ou o número da versão da API do kit de ferramentas se nenhum parâmetro for fornecido.

### Parâmetros

`fdf_document`
  O identificador do documento FDF, retornado por fdf_create(), fdf_open() ou fdf_open_string().

### Valor Retornado

Retorna a versão como uma string. Para o atual kit de ferramentas FDF 5.0, o número da versão da API é `5.0` e o número da versão do documento é `1.2`, `1.3` ou `1.4`.

### Veja Também

- fdf_set_version() - Define o número da versão para um arquivo FDF

# fdf_header

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVNf)

fdf_header — Define cabeçalhos de saída específicos de FDF

### Descrição

function fdf_header(): void

Esta é uma função de conveniência para definir cabeçalhos HTTP apropriados para saída FDF. Ela define o `Content-type:` para `application/vnd.fdf`.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Nenhum valor é retornado.

# fdf_next_field_name

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_next_field_name — Obtém o próximo nome de campo

### Descrição

function fdf_next_field_name(resource `$fdf_document`, string `$fieldname` = ?): string

Obtém o nome do campo após o campo fornecido. Este nome pode ser usado com várias funções.

### Parâmetros

`fdf_document`
  O identificador do documento FDF, retornado por fdf_create(), fdf_open() ou fdf_open_string().
`fieldname`
  Nome do campo FDF, como uma string. Se não for fornecido, o primeiro campo será assumido.

### Valor Retornado

Retorna o nome do campo como uma string.

### Exemplos

Exemplo #1 Detectando todos os nomes de campos em um FDF

    <?php
    $fdf = fdf_open($HTTP_FDF_DATA);
    for ($field = fdf_next_field_name($fdf);
        $field != "";
        $field = fdf_next_field_name($fdf, $field)) {
        echo "field: $field\n";
    }
    ?>

### Veja Também

- fdf_get_value() - Obtém o valor de um campo

# fdf_open

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_open — Abre um documento FDF

### Descrição

function fdf_open(string `$filename`): resource

Abre um arquivo com dados de formulário.

Pode-se também usar fdf_open_string() para processar os resultados de uma solicitação POST de formulário PDF.

### Parâmetros

`filename`
  Caminho para o arquivo FDF. Este arquivo deve conter os dados conforme retornados de um formulário PDF ou criados usando fdf_create() e fdf_save().

### Valor Retornado

Retorna um identificador de documento FDF ou `false` em caso de erro.

### Exemplos

Exemplo #1 Acessando os dados do formulário

    <?php
    // Salva os dados FDF em um arquivo temporário
    $fdffp = fopen("test.fdf", "w");
    fwrite($fdffp, $HTTP_FDF_DATA, strlen($HTTP_FDF_DATA));
    fclose($fdffp);

    // Abre arquivo temporário e avalia dados
    $fdf = fdf_open("test.fdf");
    /* ... */
    fdf_close($fdf);
    ?>

### Veja Também

- fdf_open_string() - Lê um documento FDF de uma string
- fdf_close() - Fecha um documento FDF
- fdf_create() - Cria um novo documento FDF
- fdf_save() - Salva um documento FDF

# fdf_open_string

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_open_string — Lê um documento FDF de uma string

### Descrição

function fdf_open_string(string `$fdf_data`): resource

Lê dados de formulário de uma string.

Pode-se usar fdf_open_string() junto com $HTTP_FDF_DATA para processar a entrada do formulário FDF de um cliente remoto.

### Parâmetros

`fdf_data`
  Os dados retornados de um formulário PDF ou criados usando fdf_create() e fdf_save_string().

### Valor Retornado

Retorna um identificador de documento FDF ou `false` em caso de erro.

### Exemplos

Exemplo #1 Acessando os dados do formulário

    <?php
    $fdf = fdf_open_string($HTTP_FDF_DATA);
    /* ... */
    fdf_close($fdf);
    ?>

### Veja Também

- fdf_open() - Abre um documento FDF
- fdf_close() - Fecha um documento FDF
- fdf_create() - Cria um novo documento FDF
- fdf_save_string() - Retorna o documento FDF como uma string

# fdf_remove_item

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_remove_item — Define o quadro de destino para o formulário

### Descrição

function fdf_remove_item(resource `$fdf_document`, string `$fieldname`, int `$item`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

# fdf_save

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_save — Salva um documento FDF

### Descrição

function fdf_save(resource `$fdf_document`, string `$filename` = ?): bool

Salva um documento FDF.

### Parâmetros

`fdf_document`
  O identificador do documento FDF, retornado por fdf_create(), fdf_open() ou fdf_open_string().
`filename`
  Se fornecido, o FDF resultante será escrito neste parâmetro. Caso contrário, esta função escreverá o FDF no fluxo de saída PHP padrão.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- fdf_close() - Fecha um documento FDF
- fdf_create() - Cria um novo documento FDF
- fdf_save_string() - Retorna o documento FDF como uma string

# fdf_save_string

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_save_string — Retorna o documento FDF como uma string

### Descrição

function fdf_save_string(resource `$fdf_document`): string

Retorna o documento FDF como uma string.

### Parâmetros

`fdf_document`
  O identificador do documento FDF, retornado por fdf_create(), fdf_open() ou fdf_open_string().

### Valor Retornado

Retorna o documento como uma string ou `false` em caso de erro.

### Exemplos

Exemplo #1 Recuperando FDF como uma string

    <?php
    $fdf = fdf_create();
    fdf_set_value($fdf, "foo", "bar");
    $str = fdf_save_string($fdf);
    fdf_close($fdf);
    echo $str;
    ?>

O exemplo acima produzirá:

    %FDF-1.2
    %âãÏÓ
    1 0 obj
    <<
    /FDF << /Fields 2 0 R >>
    >>
    endobj
    2 0 obj
    [
    << /T (foo)/V (bar)>>
    ]
    endobj
    trailer
    <<
    /Root 1 0 R

    >>
    %%EOF

### Veja Também

- fdf_open_string() - Lê um documento FDF de uma string
- fdf_close() - Fecha um documento FDF
- fdf_create() - Cria um novo documento FDF
- fdf_save() - Salva um documento FDF

# fdf_set_ap

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_ap — Define a aparência de um campo

### Descrição

function fdf_set_ap(
resource `$fdf_document`,
string `$field_name`,
int `$face`,
string `$filename`,
int `$page_number`
): bool

Define a aparência de um campo (ou seja, o valor da chave `/AP`).

### Parâmetros

`fdf_document`
  O identificador do documento FDF, retornado por fdf_create(), fdf_open() ou fdf_open_string().
`field_name`
`face`
  Os valores possíveis são `FDFNormalAP`, `FDFRolloverAP` e `FDFDownAP`.
`filename`
`page_number`

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# fdf_set_encoding

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_encoding — Define a codificação de caracteres FDF

### Descrição

function fdf_set_encoding(resource `$fdf_document`, string `$encoding`): bool

Define a codificação de caracteres para o documento FDF.

### Parâmetros

`fdf_document`
  O identificador do documento FDF, retornado por fdf_create(), fdf_open() ou fdf_open_string().
`encoding`
  O nome da codificação. Os seguintes valores são suportados: "`Shift-JIS`", "`UHC`", "`GBK`" e "`BigFive`". Uma string vazia redefine a codificação para o esquema padrão `PDFDocEncoding/Unicode`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# fdf_set_file

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_file — Define o documento PDF para exibição de dados FDF

### Descrição

function fdf_set_file(resource `$fdf_document`, string `$url`, string `$target_frame` = ?): bool

Seleciona um documento PDF diferente para exibir os resultados do formulário em vez do formulário de onde ele se originou.

### Parâmetros

`fdf_document`
  O identificador do documento FDF, retornado por fdf_create(), fdf_open() ou fdf_open_string().
`url`
  Deve ser fornecido como uma URL absoluta.
`target_frame`
  Use este parâmetro para especificar o quadro no qual o documento será exibido. Você também pode definir o valor padrão para este parâmetro usando fdf_set_target_frame().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Passando dados FDF para um segundo formulário

    <?php
      /* define tipo de conteúdo para Adobe FDF */
      fdf_header();

      /* inicia novo fdf */
      $fdf = fdf_create();

      /* define o campo "foo" para o valor "bar" */
      fdf_set_value($fdf, "foo", "bar");

      /* diz ao cliente para exibir dados FDF usando "fdf_form.pdf" */
      fdf_set_file($fdf, "http://www.example.com/fdf_form.pdf");

      /* exibe o fdf */
      fdf_save($fdf);

      /* limpa */
      fdf_close($fdf);
    ?>

### Veja Também

- fdf_get_file() - Obtém o valor da chave /F
- fdf_set_target_frame() - Define o quadro de destino para exibição do formulário

# fdf_set_flags

(PHP 4 >= 4.0.2, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_flags — Define um sinalizador de um campo

### Descrição

function fdf_set_flags(
resource `$fdf_document`,
string `$fieldname`,
int `$whichFlags`,
int `$newFlags`
): bool

Define determinados sinalizadores do campo fornecido.

### Parâmetros

`fdf_document`
  O identificador do documento FDF, retornado por fdf_create(), fdf_open() ou fdf_open_string().
`fieldname`
  Nome do campo FDF, como uma string.
`whichFlags`
`newFlags`

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- fdf_set_opt() - Define uma opção de um campo

# fdf_set_javascript_action

(PHP 4 >= 4.0.2, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_javascript_action — Define uma ação javascript de um campo

### Descrição

function fdf_set_javascript_action(
resource `$fdf_document`,
string `$fieldname`,
int `$trigger`,
string `$script`
): bool

Define uma ação javascript para o campo fornecido.

### Parâmetros

`fdf_document`
  O identificador do documento FDF, retornado por fdf_create(), fdf_open() ou fdf_open_string().
`fieldname`
  Nome do campo FDF, como uma string.
`trigger`
`script`

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- fdf_set_submit_form_action() - Define uma ação de envio de formulário de um campo

# fdf_set_on_import_javascript

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_on_import_javascript — Adiciona código javascript para ser executado quando o Acrobat abre o FDF

### Descrição

function fdf_set_on_import_javascript(resource `$fdf_document`, string `$script`, bool `$before_data_import`): bool
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Veja Também

- fdf_add_doc_javascript() - Adiciona código javascript ao documento FDF
- fdf_set_javascript_action() - Define uma ação javascript de um campo

# fdf_set_opt

(PHP 4 >= 4.0.2, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_opt — Define uma opção de um campo

### Descrição

function fdf_set_opt(
resource `$fdf_document`,
string `$fieldname`,
int `$element`,
string `$str1`,
string `$str2`
): bool

Define opções do campo fornecido.

### Parâmetros

`fdf_document`
  O identificador do documento FDF, retornado por fdf_create(), fdf_open() ou fdf_open_string().
`fieldname`
  Nome do campo FDF, como uma string.
`element`
`str1`
`str2`

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- fdf_set_flags() - Define um sinalizador de um campo

# fdf_set_status

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_status — Define o valor da chave /STATUS

### Descrição

function fdf_set_status(resource `$fdf_document`, string `$status`): bool

Define o valor da chave `/STATUS`. Quando um cliente recebe um FDF com um status definido, ele apresentará o valor em uma caixa de alerta.

### Parâmetros

`fdf_document`
  O identificador do documento FDF, retornado por fdf_create(), fdf_open() ou fdf_open_string().
`status`

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- fdf_get_status() - Obtém o valor da chave /STATUS

# fdf_set_submit_form_action

(PHP 4 >= 4.0.2, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_submit_form_action — Define uma ação de envio de formulário de um campo

### Descrição

function fdf_set_submit_form_action(
resource `$fdf_document`,
string `$fieldname`,
int `$trigger`,
string `$script`,
int `$flags`
): bool

Define uma ação de envio de formulário para o campo fornecido.

### Parâmetros

`fdf_document`
  O identificador do documento FDF, retornado por fdf_create(), fdf_open() ou fdf_open_string().
`fieldname`
  Nome do campo FDF, como uma string.
`trigger`
`script`
`flags`

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- fdf_set_javascript_action() - Define uma ação javascript de um campo

# fdf_set_target_frame

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_target_frame — Define o quadro de destino para exibição do formulário

### Descrição

function fdf_set_target_frame(resource `$fdf_document`, string `$frame_name`): bool

Define o quadro de destino para exibir um PDF de resultado definido com fdf_save_file().

### Parâmetros

`fdf_document`
  O identificador do documento FDF, retornado por fdf_create(), fdf_open() ou fdf_open_string().
`frame_name`
  O nome do quadro, como uma string.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- fdf_save_file()

# fdf_set_value

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_value — Define o valor de um campo

### Descrição

function fdf_set_value(
resource `$fdf_document`,
string `$fieldname`,
mixed `$value`,
int `$isName` = ?
): bool

Define o valos do parâmetro `value` para o campo fornecido.

### Parâmetros

`fdf_document`
  O identificador do documento FDF, retornado por fdf_create(), fdf_open() ou fdf_open_string().
`fieldname`
  Nome do campo FDF, como uma string.
`value`
  Este parâmetro será armazenado como uma string, a menos que seja um array. Neste caso, todos os elementos do array serão armazenados como um array de valores.
`isName`

  > Nota: Em versões mais antigas do kit de ferramentas FDF, o último parâmetro determinava se o valor do campo deveria ser convertido em um Nome PDF (= 1) ou definido como uma String PDF (= 0). O valor não é mais usado na versão atual do toolkit 5.0. Por razões de compatibilidade, ele ainda é suportado como um parâmetro opcional, mas ignorado internamente.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- fdf_get_value() - Obtém o valor de um campo
- fdf_remove_item() - Define o quadro de destino para o formulário

# fdf_set_version

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_version — Define o número da versão para um arquivo FDF

### Descrição

function fdf_set_version(resource `$fdf_document`, string `$version`): bool

Define a versão informada no parâmetro `version` do FDF para o documento fornecido.

Alguns recursos suportados por esta extensão estão disponíveis apenas em versões mais recentes do FDF.

### Parâmetros

`fdf_document`
  O identificador do documento FDF, retornado por fdf_create(), fdf_open() ou fdf_open_string().
`version`
  O número da versão. Para o atual kit de ferramentas FDF 5.0, pode ser ou `1.2`, `1.3` ou `1.4`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- fdf_get_version() - Obtém o número da versão para a API ou arquivo FDF

## Índice

- fdf_add_doc_javascript — Adiciona código javascript ao documento FDF
- fdf_add_template — Adiciona um modelo ao documento FDF
- fdf_close — Fecha um documento FDF
- fdf_create — Cria um novo documento FDF
- fdf_enum_values — Chama uma função definida pelo usuário para cada valor do documento
- fdf_errno — Retorna o código de erro para a última operação fdf
- fdf_error — Retorna a descrição do erro para o código de erro FDF
- fdf_get_ap — Obtém a aparência de um campo
- fdf_get_attachment — Extrai o arquivo carregado incorporado no FDF
- fdf_get_encoding — Obtém o valor da chave /Encoding
- fdf_get_file — Obtém o valor da chave /F
- fdf_get_flags — Obtém os sinalizadores de um campo
- fdf_get_opt — Obtém um valor do array de opções de um campo
- fdf_get_status — Obtém o valor da chave /STATUS
- fdf_get_value — Obtém o valor de um campo
- fdf_get_version — Obtém o número da versão para a API ou arquivo FDF
- fdf_header — Define cabeçalhos de saída específicos de FDF
- fdf_next_field_name — Obtém o próximo nome de campo
- fdf_open — Abre um documento FDF
- fdf_open_string — Lê um documento FDF de uma string
- fdf_remove_item — Define o quadro de destino para o formulário
- fdf_save — Salva um documento FDF
- fdf_save_string — Retorna o documento FDF como uma string
- fdf_set_ap — Define a aparência de um campo
- fdf_set_encoding — Define a codificação de caracteres FDF
- fdf_set_file — Define o documento PDF para exibição de dados FDF
- fdf_set_flags — Define um sinalizador de um campo
- fdf_set_javascript_action — Define uma ação javascript de um campo
- fdf_set_on_import_javascript — Adiciona código javascript para ser executado quando o Acrobat abre o FDF
- fdf_set_opt — Define uma opção de um campo
- fdf_set_status — Define o valor da chave /STATUS
- fdf_set_submit_form_action — Define uma ação de envio de formulário de um campo
- fdf_set_target_frame — Define o quadro de destino para exibição do formulário
- fdf_set_value — Define o valor de um campo
- fdf_set_version — Define o número da versão para um arquivo FDF

- Instalação/Configuração
  - Dependências
  - Instalação
  - Tipos de Recurso
- Constantes predefinidas
- Exemplos
- Funções de FDF
  - fdf_add_doc_javascript — Adiciona código javascript ao documento FDF
  - fdf_add_template — Adiciona um modelo ao documento FDF
  - fdf_close — Fecha um documento FDF
  - fdf_create — Cria um novo documento FDF
  - fdf_enum_values — Chama uma função definida pelo usuário para cada valor do documento
  - fdf_errno — Retorna o código de erro para a última operação fdf
  - fdf_error — Retorna a descrição do erro para o código de erro FDF
  - fdf_get_ap — Obtém a aparência de um campo
  - fdf_get_attachment — Extrai o arquivo carregado incorporado no FDF
  - fdf_get_encoding — Obtém o valor da chave /Encoding
  - fdf_get_file — Obtém o valor da chave /F
  - fdf_get_flags — Obtém os sinalizadores de um campo
  - fdf_get_opt — Obtém um valor do array de opções de um campo
  - fdf_get_status — Obtém o valor da chave /STATUS
  - fdf_get_value — Obtém o valor de um campo
  - fdf_get_version — Obtém o número da versão para a API ou arquivo FDF
  - fdf_header — Define cabeçalhos de saída específicos de FDF
  - fdf_next_field_name — Obtém o próximo nome de campo
  - fdf_open — Abre um documento FDF
  - fdf_open_string — Lê um documento FDF de uma string
  - fdf_remove_item — Define o quadro de destino para o formulário
  - fdf_save — Salva um documento FDF
  - fdf_save_string — Retorna o documento FDF como uma string
  - fdf_set_ap — Define a aparência de um campo
  - fdf_set_encoding — Define a codificação de caracteres FDF
  - fdf_set_file — Define o documento PDF para exibição de dados FDF
  - fdf_set_flags — Define um sinalizador de um campo
  - fdf_set_javascript_action — Define uma ação javascript de um campo
  - fdf_set_on_import_javascript — Adiciona código javascript para ser executado quando o Acrobat abre o FDF
  - fdf_set_opt — Define uma opção de um campo
  - fdf_set_status — Define o valor da chave /STATUS
  - fdf_set_submit_form_action — Define uma ação de envio de formulário de um campo
  - fdf_set_target_frame — Define o quadro de destino para exibição do formulário
  - fdf_set_value — Define o valor de um campo
  - fdf_set_version — Define o número da versão para um arquivo FDF

# Guarda de Privacidade GNU

# Introdução

Este módulo permite interação com o » gnupg.

# Instalação/Configuração

## Índice

- Dependências
- Instalação

## Dependências

Esta extensão requer a » biblioteca gpgme

## Instalação

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/gnupg.

# Constantes predefinidas

`GNUPG_SIG_MODE_NORMAL` (int)
`GNUPG_SIG_MODE_DETACH` (int)
`GNUPG_SIG_MODE_CLEAR` (int)
`GNUPG_VALIDITY_UNKNOWN` (int)
`GNUPG_VALIDITY_UNDEFINED` (int)
`GNUPG_VALIDITY_NEVER` (int)
`GNUPG_VALIDITY_MARGINAL` (int)
`GNUPG_VALIDITY_FULL` (int)
`GNUPG_VALIDITY_ULTIMATE` (int)
`GNUPG_PROTOCOL_OpenPGP` (int)
`GNUPG_PROTOCOL_CMS` (int)
`GNUPG_SIGSUM_VALID` (int)
`GNUPG_SIGSUM_GREEN` (int)
`GNUPG_SIGSUM_RED` (int)
`GNUPG_SIGSUM_KEY_REVOKED` (int)
`GNUPG_SIGSUM_KEY_EXPIRED` (int)
`GNUPG_SIGSUM_KEY_MISSING` (int)
`GNUPG_SIGSUM_SIG_EXPIRED` (int)
`GNUPG_SIGSUM_CRL_MISSING` (int)
`GNUPG_SIGSUM_CRL_TOO_OLD` (int)
`GNUPG_SIGSUM_BAD_POLICY` (int)
`GNUPG_SIGSUM_SYS_ERROR` (int)
`GNUPG_ERROR_WARNING` (int)
`GNUPG_ERROR_EXCEPTION` (int)
`GNUPG_ERROR_SILENT` (int)

# Exemplos

## Índice

- Assinatura com texto claro

## Assinatura com texto claro

Este exemplo irá assinar de forma clara um texto fornecido.

Exemplo #1 Exemplo de assinatura clara com gnupg (procedural)

    <?php
    // inicia gnupg
    $res = gnupg_init();
    // não é realmente necessário. Assinatura de forma clara é o padrão
    gnupg_setsignmode($res,GNUPG_SIG_MODE_CLEAR);
    // adiciona chave com senha 'test' para assinatura
    gnupg_addsignkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
    // assina
    $signed = gnupg_sign($res,"just a test");
    echo $signed;
    ?>

Exemplo #2 Exemplo de assinatura clara com gnupg (OO)

    <?php
    // nova classe
    $gnupg = new gnupg();
    // não é realmente necessário. Assinatura de forma clara é o padrão
    $gnupg->setsignmode(gnupg::SIG_MODE_CLEAR);
    // adiciona chave com senha 'test' para assinatura
    $gnupg->addsignkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
    // assina
    $signed = $gnupg->sign("just a test");
    echo $signed;
    ?>

Exemplo #3 keylistiterator

Esta extensão também vem com um iterador para um chaveiro.

    <?php
    // cria um novo iterador para listar todas as chaves públicas que correspondem a 'exemplo'
    $iterator = new gnupg_keylistiterator("exemplo");
    foreach($iterator as $fingerprint => $userid){
        echo $fingerprint." -> ".$userid."\n";
    }
    ?>

# Funções de GnuPG

# Notas

Esta extensão utiliza o chaveiro do usuário atual. Este chaveiro normalmente está localizado em ~/.gnupg/. Para especificar um local personalizado, armazene o caminho para o chaveiro na variável de ambiente GNUPGHOME. Consulte putenv para obter mais informações sobre como fazer isso.

Algumas funções requerem a especificação de uma chave. Esta especificação pode ser qualquer coisa que se refira a uma chave exclusiva (userid, key-id, impressão digital, ...). Esta documentação usa a impressão digital em todos os exemplos.

> Nota: Como alternativa às funções explicitamente documentadas usando resources, você também pode usar um estilo orientado a objetos usando objetos gnupg.

# gnupg_adddecryptkey

(PECL gnupg >= 0.5)

gnupg_adddecryptkey — Adiciona uma chave para descriptografia

### Descrição

function gnupg_adddecryptkey(resource `$identifier`, string `$fingerprint`, string `$passphrase`): bool

### Parâmetros

`identifier`
  O identificador gnupg, obtido de uma chamada a gnupg_init() ou gnupg.
`fingerprint`
  A chave da impressão digital.
`passphrase`
  A frase secreta.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo procedural de gnupg_adddecryptkey()

    <?php
    $res = gnupg_init();
    gnupg_adddecryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
    ?>

Exemplo #2 Exemplo orientado a objeto de gnupg_adddecryptkey()

    <?php
    $gpg = new gnupg();
    $gpg->adddecryptkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
    ?>

# gnupg_addencryptkey

(PECL gnupg >= 0.5)

gnupg_addencryptkey — Adiciona uma chave para criptografia

### Descrição

function gnupg_addencryptkey(resource `$identifier`, string `$fingerprint`): bool

### Parâmetros

`identifier`
  O identificador gnupg, obtido de uma chamada a gnupg_init() ou gnupg.
`fingerprint`
  A chave da impressão digital.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo procedural de gnupg_addencryptkey()

    <?php
    $res = gnupg_init();
    gnupg_addencryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC");
    ?>

Exemplo #2 Exemplo orientado a objeto de gnupg_addencryptkey()

    <?php
    $gpg = new gnupg();
    $gpg->addencryptkey("8660281B6051D071D94B5B230549F9DC851566DC");
    ?>

# gnupg_addsignkey

(PECL gnupg >= 0.5)

gnupg_addsignkey — Adiciona uma chave para assinatura

### Descrição

function gnupg_addsignkey(resource `$identifier`, string `$fingerprint`, string `$passphrase` = ?): bool

### Parâmetros

`identifier`
  O identificador gnupg, obtido de uma chamada a gnupg_init() ou gnupg.
`fingerprint`
  A chave da impressão digital.
`passphrase`
  A frase secreta.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo procedural de gnupg_addsignkey()

    <?php
    $res = gnupg_init();
    gnupg_addsignkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
    ?>

Exemplo #2 Exemplo orientado a objeto de gnupg_addsignkey()

    <?php
    $gpg = new gnupg();
    $gpg->addsignkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
    ?>

# gnupg_cleardecryptkeys

(PECL gnupg >= 0.5)

gnupg_cleardecryptkeys — Remove todas as chaves que foram definidas para descriptografia antes

### Descrição

function gnupg_cleardecryptkeys(resource `$identifier`): bool

### Parâmetros

`identifier`
  O identificador gnupg, obtido de uma chamada a gnupg_init() ou gnupg.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo procedural de gnupg_cleardecryptkeys()

    <?php
    $res = gnupg_init();
    gnupg_cleardecryptkeys($res);
    ?>

Exemplo #2 Exemplo orientado a objeto de gnupg_cleardecryptkeys()

    <?php
    $gpg = new gnupg();
    $gpg->cleardecryptkeys();
    ?>

# gnupg_clearencryptkeys

(PECL gnupg >= 0.5)

gnupg_clearencryptkeys — Remove todas as chaves que foram definidas para criptografia antes

### Descrição

function gnupg_clearencryptkeys(resource `$identifier`): bool

### Parâmetros

`identifier`
  O identificador gnupg, obtido de uma chamada a gnupg_init() ou gnupg.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo procedural de gnupg_clearencryptkeys()

    <?php
    $res = gnupg_init();
    gnupg_clearencryptkeys($res);
    ?>

Exemplo #2 Exemplo orientado a objeto de gnupg_clearencryptkeys()

    <?php
    $gpg = new gnupg();
    $gpg->clearencryptkeys();
    ?>

# gnupg_clearsignkeys

(PECL gnupg >= 0.5)

gnupg_clearsignkeys — Remove todas as chaves que foram definidas para assinatura antes

### Descrição

function gnupg_clearsignkeys(resource `$identifier`): bool

### Parâmetros

`identifier`
  O identificador gnupg, obtido de uma chamada a gnupg_init() ou gnupg.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo procedural de gnupg_clearsignkeys()

    <?php
    $res = gnupg_init();
    gnupg_clearsignkeys($res);
    ?>

Exemplo #2 Exemplo orientado a objeto de gnupg_clearsignkeys()

    <?php
    $gpg = new gnupg();
    $gpg->clearsignkeys();
    ?>

# gnupg_decrypt

(PECL gnupg >= 0.1)

gnupg_decrypt — Descriptografa um texto fornecido

### Descrição

function gnupg_decrypt(resource `$identifier`, string `$text`): string|false

Descriptografa o texto fornecido com as chaves que foram definidas com gnupg_adddecryptkey anteriormente.

### Parâmetros

`identifier`
  O identificador gnupg, obtido de uma chamada a gnupg_init() ou gnupg.
`text`
  O texto sendo descriptografado.

### Valor Retornado

Em caso de sucesso, esta função retorna o texto descriptografado. Em caso de falha, esta função retorna `false`.

### Exemplos

Exemplo #1 Exemplo procedural de gnupg_decrypt()

    <?php
    $res = gnupg_init();
    gnupg_adddecryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
    $plain = gnupg_decrypt($res,$encrypted_text);
    echo $plain;
    ?>

Exemplo #2 Exemplo orientado a objeto de gnupg_decrypt()

    <?php
    $gpg = new gnupg();
    $gpg->adddecryptkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
    $plain = $gpg->decrypt($encrypted_text);
    echo $plain;
    ?>

# gnupg_decryptverify

(PECL gnupg >= 0.2)

gnupg_decryptverify — Descriptografa e verifica um texto fornecido

### Descrição

function gnupg_decryptverify(resource `$identifier`, string `$text`, string `&$plaintext`): array|false

Descriptografa e verifica um texto fornecido e retorna informações sobre a assinatura.

### Parâmetros

`identifier`
  O identificador gnupg, obtido de uma chamada a gnupg_init() ou gnupg.
`text`
  O texto sendo descriptografado.
`plaintext`
  O parâmetro `plaintext` é preenchido com o texto descriptografado.

### Valor Retornado

Em caso de sucesso, esta função retorna informações sobre a assinatura e preenche o parâmetro `plaintext` com o texto descriptografado. Em caso de falha, esta função retorna `false`.

### Exemplos

Exemplo #1 Exemplo procedural de gnupg_decryptverify()

    <?php
    $plaintext = "";
    $res = gnupg_init();
    gnupg_adddecryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
    $info = gnupg_decryptverify($res,$text,$plaintext);
    print_r($info);
    ?>

Exemplo #2 Exemplo orientado a objeto de gnupg_decryptverify()

    <?php
    $plaintext = "";
    $gpg = new gnupg();
    $gpg->adddecryptkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
    $info = $gpg->decryptverify($text,$plaintext);
    print_r($info);
    ?>

# gnupg_deletekey

(PECL gnupg >= 0.5)

gnupg_deletekey — Exclui uma chave do chaveiro

### Descrição

function gnupg_deletekey(resource `$identifier`, string `$key`, bool `$allow_secret`): bool

### Parâmetros

`identifier`
  O identificador gnupg, obtido de uma chamada a gnupg_init() ou gnupg.
`key`
  A chave a ser excluída.
`allow_secret`
  Especifica se as chaves secretas também devem ser excluídas.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo procedural de gnupg_deletekey()

    <?php
    $res = gnupg_init();
    gnupg_deletekey($res, "8660281B6051D071D94B5B230549F9DC851566DC");
    ?>

Exemplo #2 Exemplo orientado a objeto de gnupg_deletekey()

    <?php
    $gpg = new gnupg();
    $gpg->deletekey("8660281B6051D071D94B5B230549F9DC851566DC");
    ?>

# gnupg_encrypt

(PECL gnupg >= 0.1)

gnupg_encrypt — Criptografa um texto fornecido

### Descrição

function gnupg_encrypt(resource `$identifier`, string `$plaintext`): string|false

Criptografa o `plaintext` fornecido com as chaves, que foram definidas com gnupg_addencryptkey anteriormente e retorna o texto criptografado.

### Parâmetros

`identifier`
  O identificador gnupg, obtido de uma chamada a gnupg_init() ou gnupg.
`plaintext`
  O texto a ser sendo criptografado.

### Valor Retornado

Em caso de sucesso, esta função retorna o texto criptografado. Em caso de falha, esta função retorna `false`.

### Exemplos

Exemplo #1 Exemplo procedural de gnupg_encrypt()

    <?php
    $res = gnupg_init();
    gnupg_addencryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC");
    $enc = gnupg_encrypt($res, "somente um teste");
    echo $enc;
    ?>

Exemplo #2 Exemplo orientado a objeto de gnupg_encrypt()

    <?php
    $gpg = new gnupg();
    $gpg->addencryptkey("8660281B6051D071D94B5B230549F9DC851566DC");
    $enc = $gpg->encrypt("somente um teste");
    echo $enc;
    ?>

# gnupg_encryptsign

(PECL gnupg >= 0.2)

gnupg_encryptsign — Criptografa e assina um texto fornecido

### Descrição

function gnupg_encryptsign(resource `$identifier`, string `$plaintext`): string|false

Criptografa e assina o `plaintext` fornecido com as chaves, que foram definidas com gnupg_addsignkey e gnupg_addencryptkey anteriormente e retorna o texto criptografado e assinado.

### Parâmetros

`identifier`
  O identificador gnupg, obtido de uma chamada a gnupg_init() ou gnupg.
`plaintext`
  O texto a ser criptografado.

### Valor Retornado

Em caso de sucesso, esta função retorna o texto criptografado e assinado. Em caso de falha, esta função retorna `false`.

### Exemplos

Exemplo #1 Exemplo procedural de gnupg_encryptsign()

    <?php
    $res = gnupg_init();
    gnupg_addencryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC");
    gnupg_addsignkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
    $enc = gnupg_encryptsign($res, "just a test");
    echo $enc;
    ?>

Exemplo #2 Exemplo orientado a objeto de gnupg_encryptsign()

    <?php
    $gpg = new gnupg();
    $gpg->addencryptkey("8660281B6051D071D94B5B230549F9DC851566DC");
    $gpg->addsignkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
    $enc = $gpg->encryptsign("just a test");
    echo $enc;
    ?>

# gnupg_export

(PECL gnupg >= 0.1)

gnupg_export — Exporta uma chave

### Descrição

function gnupg_export(resource `$identifier`, string `$fingerprint`): string|false

Exporta a chave `fingerprint`.

### Parâmetros

`identifier`
  O identificador gnupg, obtido de uma chamada a gnupg_init() ou gnupg.
`fingerprint`
  A chave da impressão digital.

### Valor Retornado

Em caso de sucesso, esta função retorna os dados da chave. Em caso de falha, esta função retorna `false`.

### Exemplos

Exemplo #1 Exemplo procedural de gnupg_export()

    <?php
    $res = gnupg_init();
    $export = gnupg_export($res,"8660281B6051D071D94B5B230549F9DC851566DC");
    echo $export;
    ?>

Exemplo #2 Exemplo orientado a objeto de gnupg_export()

    <?php
    $gpg = new gnupg();
    $export = $gpg->export("8660281B6051D071D94B5B230549F9DC851566DC");
    ?>

# gnupg_getengineinfo

(PECL gnupg >= 1.5)

gnupg_getengineinfo — Retorna as informações do mecanismo

### Descrição

function gnupg_getengineinfo(resource `$identifier`): array

### Parâmetros

`identifier`
  O identificador gnupg, obtido de uma chamada a gnupg_init() ou gnupg.

### Valor Retornado

Retorna um array com informações do mecanismo consistindo de `protocol` (protocolo), `file_name` (nome do arquivo) e `home_dir` (diretório inicial).

### Exemplos

Exemplo #1 Exemplo procedural de gnupg_getengineinfo()

    <?php
    $res = gnupg_init();
    print_r(gnupg_getengineinfo($res));
    ?>

O exemplo acima produzirá:

    array(3) {
      ["protocol"]=>
      int(0)
      ["file_name"]=>
      string(12) "/usr/bin/gpg"
      ["home_dir"]=>
      string(0) ""
    }

Exemplo #2 Exemplo orientado a objeto de gnupg_getengineinfo()

    <?php
    $gpg = new gnupg(["file_name" => "/usr/bin/gpg2", "home_dir" => "/var/www/.gnupg"]);
    print_r($gpg->getengineinfo());
    ?>

O exemplo acima produzirá:

    array(3) {
      ["protocol"]=>
      int(0)
      ["file_name"]=>
      string(13) "/usr/bin/gpg2"
      ["home_dir"]=>
      string(15) "/var/www/.gnupg"
    }

# gnupg_geterror

(PECL gnupg >= 0.1)

gnupg_geterror — Retorna o texto de erro, se uma função falhar

### Descrição

function gnupg_geterror(resource `$identifier`): string|false

### Parâmetros

`identifier`
  O identificador gnupg, obtido de uma chamada a gnupg_init() ou gnupg.

### Valor Retornado

Retorna um texto de erro, se ocorreu um erro, caso contrário, `false`.

### Exemplos

Exemplo #1 Exemplo procedural de gnupg_geterror()

    <?php
    $res = gnupg_init();
    echo gnupg_geterror($res);
    ?>

Exemplo #2 Exemplo orientado a objeto de gnupg_geterror()

    <?php
    $gpg = new gnupg();
    echo $gpg->geterror();
    ?>

# gnupg_geterrorinfo

(PECL gnupg >= 1.5)

gnupg_geterrorinfo — Retorna as informações de erro

### Descrição

function gnupg_geterrorinfo(resource `$identifier`): array

### Parâmetros

`identifier`
  O identificador gnupg, obtido de uma chamada a gnupg_init() ou gnupg.

### Valor Retornado

Retorna um array com informações de erro.

### Exemplos

Exemplo #1 Exemplo procedural de gnupg_geterrorinfo()

    <?php
    $res = gnupg_init();
    // isso é chamado sem nenhum erro
    print_r(gnupg_geterrorinfo($res));
    ?>

O exemplo acima produzirá:

    array(4) {
      ["generic_message"]=>
      bool(false)
      ["gpgme_code"]=>
      int(0)
      ["gpgme_source"]=>
      string(18) "Unspecified source"
      ["gpgme_message"]=>
      string(7) "Success"
    }

Exemplo #2 Exemplo orientado a objeto de gnupg_geterrorinfo()

    <?php
    $gpg = new gnupg();
    // chamada com erro
    $gpg->decrypt('abc');
    // informações de erro devem ser exibidas
    print_r($gpg->geterrorinfo());
    ?>

O exemplo acima produzirá:

    array(4) {
      ["generic_message"]=>
      string(14) "decrypt failed"
      ["gpgme_code"]=>
      int(117440570)
      ["gpgme_source"]=>
      string(5) "GPGME"
      ["gpgme_message"]=>
      string(7) "No data"
    }

# gnupg_getprotocol

(PECL gnupg >= 0.1)

gnupg_getprotocol — Retorna o protocolo atualmente ativo para todas as operações

### Descrição

function gnupg_getprotocol(resource `$identifier`): int

### Parâmetros

`identifier`
  O identificador gnupg, obtido de uma chamada a gnupg_init() ou gnupg.

### Valor Retornado

Retorna o protocolo ativo no momento, que pode ser uma das constantes `GNUPG_PROTOCOL_OpenPGP` ou `GNUPG_PROTOCOL_CMS`.

### Exemplos

Exemplo #1 Exemplo procedural de gnupg_getprotocol()

    <?php
    $res = gnupg_init();
    echo gnupg_getprotocol($res);
    ?>

Exemplo #2 Exemplo orientado a objeto de gnupg_getprotocol()

    <?php
    $gpg = new gnupg();
    echo $gpg->getprotocol();
    ?>

# gnupg_gettrustlist

(PECL gnupg >= 0.5)

gnupg_gettrustlist — Pesquisa os itens confiáveis

### Descrição

function gnupg_gettrustlist(resource `$identifier`, string `$pattern`): ?array

### Parâmetros

`identifier`
  O identificador gnupg, obtido de uma chamada a gnupg_init() ou gnupg.
`pattern`
  Expressão para limitar a lista de itens confiáveis ​​somente àqueles que correspondem ao padrão.

### Valor Retornado

Em caso de sucesso, esta função retorna um array de itens confiáveis. Em caso de falha, esta função retorna `null`.

### Exemplos

Exemplo #1 Exemplo procedural de gnupg_gettrustlist()

    <?php
    $res = gnupg_init();
    $items = gnupg_gettrustlist($res);
    print_r($items);
    ?>

Exemplo #2 Exemplo orientado a objeto de gnupg_gettrustlist()

    <?php
    $gpg = new gnupg();
    $items = $gpg->gettrustlist();
    print_r($items);
    ?>

# gnupg_import

(PECL gnupg >= 0.3)

gnupg_import — Importa uma chave

### Descrição

function gnupg_import(resource `$identifier`, string `$keydata`): array|false

Importa a chave `keydata` e retorna um array com informações sobre o processo de importação.

### Parâmetros

`identifier`
  O identificador gnupg, obtido de uma chamada a gnupg_init() ou gnupg.
`keydata`
  A chave de dados que está sendo importada.

### Valor Retornado

Em caso de sucesso, esta função retorna um array de informações sobre o processo de importação. Em caso de falha, esta função retorna `false`.

### Exemplos

Exemplo #1 Exemplo procedural de gnupg_import()

    <?php
    $res = gnupg_init();
    $info = gnupg_import($res,$keydata);
    print_r($info);
    ?>

Exemplo #2 Exemplo orientado a objeto de gnupg_import()

    <?php
    $gpg = new gnupg();
    $info = $gpg->import($keydata);
    print_r($info);
    ?>

# gnupg_init

(PECL gnupg >= 0.4)

gnupg_init — Inicializa uma conexão

### Descrição

function gnupg_init(?array `$options` = `null`): resource

### Parâmetros

`options`

  Deve ser um array associativo. É usado para alterar a configuração padrão do mecanismo de criptografia.

  Substituições de configuração
  chave | tipo | descrição
  --- | --- | ---
  file_name | string | É o nome do arquivo do programa executável que implementa este protocolo que geralmente é o caminho do executável `gpg`.
  home_dir | string | É o nome do diretório de configuração. Ele também substitui a variável de ambiente `GNUPGHOME` que é usada para o mesmo propósito.

### Valor Retornado

Uma conexão do GnuPG do tipo resource usada por outras funções do GnuPG.

### Registro de Alterações

Versão | Descrição
--- | ---
PECL gnupg 1.5.0 | O parâmetro `options` foi adicionado.

### Exemplos

Exemplo #1 Exemplo procedural de gnupg_init() com configuração padrão

    <?php
    $res = gnupg_init();
    ?>

Exemplo #2 Exemplo procedural de gnupg_init() com nome de arquivo e diretório inicial alterados

    <?php
    $res = gnupg_init(["file_name" => "/usr/bin/gpg2", "home_dir" => "/var/www/.gnupg"]);
    ?>

Exemplo #3 Exemplo orientado a objeto de inicializador gnupg initializer com configuração padrão

    <?php
    $gpg = new gnupg();
    ?>

Exemplo #4 Exemplo orientado a objeto de inicializador gnupg com nome de arquivo e diretório inicial alterados

    <?php
    $gpg = new gnupg(["file_name" => "/usr/bin/gpg2", "home_dir" => "/var/www/.gnupg"]);
    ?>

# gnupg_keyinfo

(PECL gnupg >= 0.1)

gnupg_keyinfo — Retorna um array com informações sobre todas as chaves que correspondem ao padrão fornecido

### Descrição

function gnupg_keyinfo(resource `$identifier`, string `$pattern`): array|false

### Parâmetros

`identifier`
  O identificador gnupg, obtido de uma chamada a gnupg_init() ou gnupg.
`pattern`
  O padrão sendo verificado em relação às chaves.

### Valor Retornado

Retorna um array com informações sobre todas as chaves que correspondem ao padrão fornecido ou `false`, se ocorreu um erro.

### Exemplos

Exemplo #1 Exemplo procedural de gnupg_keyinfo()

    <?php
    $res = gnupg_init();
    $info = gnupg_keyinfo($res, 'test');
    print_r($info);
    ?>

Exemplo #2 Exemplo orientado a objeto de gnupg_keyinfo()

    <?php
    $gpg = new gnupg();
    $info = $gpg->keyinfo("test");
    print_r($info);
    ?>

# gnupg_listsignatures

(PECL gnupg >= 0.5)

gnupg_listsignatures — Lista as assinaturas de clave

### Descrição

function gnupg_listsignatures(resource `$identifier`, string `$keyid`): ?array

### Parâmetros

`identifier`
  O identificador gnupg, obtido de uma chamada a gnupg_init() ou gnupg.
`keyid`
  O ID da chave para o qual as assinaturas serão listadas.

### Valor Retornado

Em caso de sucesso, esta função retorna um array de assinaturas de chave. Em caso de falha, esta função retorna `null`.

### Exemplos

Exemplo #1 Exemplo procedural de gnupg_listsignatures()

    <?php
    $res = gnupg_init();
    $signatures = gnupg_listsignatures($res, "8660281B6051D071D94B5B230549F9DC851566DC");
    print_r($signatures);
    ?>

Exemplo #2 Exemplo orientado a objeto de gnupg_listsignatures()

    <?php
    $gpg = new gnupg();
    $signatures = $gpg->listsignatures("8660281B6051D071D94B5B230549F9DC851566DC");
    print_r($signatures);
    ?>

# gnupg_setarmor

(PECL gnupg >= 0.1)

gnupg_setarmor — Alterna a saída blindada

### Descrição

function gnupg_setarmor(resource `$identifier`, int `$armor`): bool

Alterna a saída blindada.

### Parâmetros

`identifier`
  O identificador gnupg, obtido de uma chamada a gnupg_init() ou gnupg.
`armor`
  Passe um valor inteiro diferente de zero para esta função para habilitar saída blindada (padrão). Passe 0 para desabilitar saída blindada.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo procedural de gnupg_setarmor()

    <?php
    $res = gnupg_init();
    gnupg_setarmor($res,1); // habilita saída blindada;
    gnupg_setarmor($res,0); // desabilita saída blindada;
    ?>

Exemplo #2 Exemplo orientado a objeto de gnupg_setarmor()

    <?php
    $gpg = new gnupg();
    $gpg->setarmor(1); // habilita saída blindada;
    $gpg->setarmor(0); // desabilita saída blindada;
    ?>

# gnupg_seterrormode

(PECL gnupg >= 0.6)

gnupg_seterrormode — Define o modo para relato de erros

### Descrição

function gnupg_seterrormode(resource `$identifier`, int `$errormode`): void

Define o modo para error_reporting.

### Parâmetros

`identifier`
  O identificador gnupg, obtido de uma chamada a gnupg_init() ou gnupg.
`errormode`
  O modo de erro. `errormode` recebe uma constante indicando que tipo de relato de erros deve ser usado. Os valores possíveis são `GNUPG_ERROR_WARNING`, `GNUPG_ERROR_EXCEPTION` e `GNUPG_ERROR_SILENT`. Por padrão, `GNUPG_ERROR_SILENT` é usado.

### Valor Retornado

Nenhum valor é retornado.

### Exemplos

Exemplo #1 Exemplo procedural de gnupg_seterrormode()

    <?php
    $res = gnupg_init();
    gnupg_seterrormode($res,GNUPG_ERROR_WARNING); // emite um alerta PHP em caso de erro
    ?>

Exemplo #2 Exemplo orientado a objeto de gnupg_seterrormode()

    <?php
    $gpg = new gnupg();
    $gpg->seterrormode(gnupg::ERROR_EXCEPTION); // lança uma exceção em caso de erro
    ?>

# gnupg_setsignmode

(PECL gnupg >= 0.1)

gnupg_setsignmode — Define o modo de assinatura

### Descrição

function gnupg_setsignmode(resource `$identifier`, int `$signmode`): bool

Define o modo de assinatura.

### Parâmetros

`identifier`
  O identificador gnupg, obtido de uma chamada a gnupg_init() ou gnupg.
`sigmode`
  O modo de assinatura. `signmode` recebe uma constante indicando que tipo de assinatura deve ser produzida. Os valores possíveis são `GNUPG_SIG_MODE_NORMAL`, `GNUPG_SIG_MODE_DETACH` e `GNUPG_SIG_MODE_CLEAR`. Por padrão, `GNUPG_SIG_MODE_CLEAR` é usado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Exemplo procedural de gnupg_setsignmode()

    <?php
    $res = gnupg_init();
    gnupg_setsignmode($res,GNUPG_SIG_MODE_DETACH); // produz uma assinatura destacada
    ?>

Exemplo #2 Exemplo orientado a objeto de gnupg_setsignmode()

    <?php
    $gpg = new gnupg();
    $gpg->setsignmode(gnupg::SIG_MODE_DETACH); // produz uma assinatura destacada
    ?>

# gnupg_sign

(PECL gnupg >= 0.1)

gnupg_sign — Assina um texto fornecido

### Descrição

function gnupg_sign(resource `$identifier`, string `$plaintext`): string|false

Assina o `plaintext` fornecido com as chaves que foram definidas com gnupg_addsignkey anteriormente e retorna o texto assinado ou a assinatura, dependendo do que foi definido com gnupg_setsignmode.

### Parâmetros

`identifier`
  O identificador gnupg, obtido de uma chamada a gnupg_init() ou gnupg.
`plaintext`
  O texto simples sendo assinado.

### Valor Retornado

Em caso de sucesso, esta função retorna o texto assinado ou a assinatura. Em caso de falha, esta função retorna `false`.

### Exemplos

Exemplo #1 Exemplo procedural de gnupg_sign()

    <?php
    $res = gnupg_init();
    gnupg_addsignkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","teste");
    $signed = gnupg_sign($res, "somente um teste");
    echo $signed;
    ?>

Exemplo #2 Exemplo orientado a objeto de gnupg_sign()

    <?php
    $gpg = new gnupg();
    $gpg->addsignkey("8660281B6051D071D94B5B230549F9DC851566DC","teste");
    $signed = $gpg->sign("somente um teste");
    echo $signed;
    ?>

# gnupg_verify

(PECL gnupg >= 0.1)

gnupg_verify — Verifica um texto assinado

### Descrição

function gnupg_verify(
resource `$identifier`,
string `$signed_text`,
string `$signature`,
string `&$plaintext` = ?
): array|false

Verifica o texto fornecido em `signed_text` e retorna informações sobre a assinatura.

### Parâmetros

`identifier`
  O identificador gnupg, obtido de uma chamada a gnupg_init() ou gnupg.
`signed_text`
  O texto assinado.
`signature`
  A assinatura. Para verificar um texto assinado sem criptografia, defina a assinatura como `false`.
`plaintext`
  O texto simples. Se este parâmetro opcional for passado, ele é preenchido com o texto simples.

### Valor Retornado

Em caso de sucesso, esta função retorna informações sobre a assinatura. Em caso de falha, esta função retorna `false`.

### Exemplos

Exemplo #1 Exemplo procedural de gnupg_verify()

    <?php
    $plaintext = "";
    $res = gnupg_init();
    // assinatura nítida
    $info = gnupg_verify($res,$signed_text,false,$plaintext);
    print_r($info);
    // assinatura separada
    $info = gnupg_verify($res,$signed_text,$signature);
    print_r($info);
    ?>

Exemplo #2 Exemplo orientado a objeto de gnupg_verify()

    <?php
    $plaintext = "";
    $gpg = new gnupg();
    // assinatura nítida
    $info = $gpg->verify($signed_text,false,$plaintext);
    print_r($info);
    // assinatura separada
    $info = $gpg->verify($signed_text,$signature);
    print_r($info);
    ?>

## Índice

- gnupg_adddecryptkey — Adiciona uma chave para descriptografia
- gnupg_addencryptkey — Adiciona uma chave para criptografia
- gnupg_addsignkey — Adiciona uma chave para assinatura
- gnupg_cleardecryptkeys — Remove todas as chaves que foram definidas para descriptografia antes
- gnupg_clearencryptkeys — Remove todas as chaves que foram definidas para criptografia antes
- gnupg_clearsignkeys — Remove todas as chaves que foram definidas para assinatura antes
- gnupg_decrypt — Descriptografa um texto fornecido
- gnupg_decryptverify — Descriptografa e verifica um texto fornecido
- gnupg_deletekey — Exclui uma chave do chaveiro
- gnupg_encrypt — Criptografa um texto fornecido
- gnupg_encryptsign — Criptografa e assina um texto fornecido
- gnupg_export — Exporta uma chave
- gnupg_getengineinfo — Retorna as informações do mecanismo
- gnupg_geterror — Retorna o texto de erro, se uma função falhar
- gnupg_geterrorinfo — Retorna as informações de erro
- gnupg_getprotocol — Retorna o protocolo atualmente ativo para todas as operações
- gnupg_gettrustlist — Pesquisa os itens confiáveis
- gnupg_import — Importa uma chave
- gnupg_init — Inicializa uma conexão
- gnupg_keyinfo — Retorna um array com informações sobre todas as chaves que correspondem ao padrão fornecido
- gnupg_listsignatures — Lista as assinaturas de clave
- gnupg_setarmor — Alterna a saída blindada
- gnupg_seterrormode — Define o modo para relato de erros
- gnupg_setsignmode — Define o modo de assinatura
- gnupg_sign — Assina um texto fornecido
- gnupg_verify — Verifica um texto assinado

- Instalação/Configuração
  - Dependências
  - Instalação
- Constantes predefinidas
- Exemplos
  - Assinatura com texto claro
- Funções de GnuPG
  - gnupg_adddecryptkey — Adiciona uma chave para descriptografia
  - gnupg_addencryptkey — Adiciona uma chave para criptografia
  - gnupg_addsignkey — Adiciona uma chave para assinatura
  - gnupg_cleardecryptkeys — Remove todas as chaves que foram definidas para descriptografia antes
  - gnupg_clearencryptkeys — Remove todas as chaves que foram definidas para criptografia antes
  - gnupg_clearsignkeys — Remove todas as chaves que foram definidas para assinatura antes
  - gnupg_decrypt — Descriptografa um texto fornecido
  - gnupg_decryptverify — Descriptografa e verifica um texto fornecido
  - gnupg_deletekey — Exclui uma chave do chaveiro
  - gnupg_encrypt — Criptografa um texto fornecido
  - gnupg_encryptsign — Criptografa e assina um texto fornecido
  - gnupg_export — Exporta uma chave
  - gnupg_getengineinfo — Retorna as informações do mecanismo
  - gnupg_geterror — Retorna o texto de erro, se uma função falhar
  - gnupg_geterrorinfo — Retorna as informações de erro
  - gnupg_getprotocol — Retorna o protocolo atualmente ativo para todas as operações
  - gnupg_gettrustlist — Pesquisa os itens confiáveis
  - gnupg_import — Importa uma chave
  - gnupg_init — Inicializa uma conexão
  - gnupg_keyinfo — Retorna um array com informações sobre todas as chaves que correspondem ao padrão fornecido
  - gnupg_listsignatures — Lista as assinaturas de clave
  - gnupg_setarmor — Alterna a saída blindada
  - gnupg_seterrormode — Define o modo para relato de erros
  - gnupg_setsignmode — Define o modo de assinatura
  - gnupg_sign — Assina um texto fornecido
  - gnupg_verify — Verifica um texto assinado

# wkhtmltox

# Introdução

libwkhtmltox é uma biblioteca LGPLv3 de código aberto para renderizar HTML em PDF e vários formatos de imagem usando o mecanismo de renderização QtWebKit.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Configurações em Execução

## Dependências

As fontes e as versões binárias de libwkhtmltox são distribuídas em » wkhtmltopdf.org.

Cuidado

Usuários de Windows devem realizar o passo adicional de incluir o wkhtmltox.dll na variável de ambiente PATH.

## Instalação

O código fonte desta extensão e os binários para Windows são hospedados pelo » github,

Buscando o código-fonte e construindo a extensão:

    git clone https://github.com/krakjoe/wkhtmltox
    cd wkhtmltox
    phpize
    ./configure --with-wkhtmltox=/path/to/wkhtmltox/installation
    make
    sudo make install

Buscando atualizações e reconstruindo a extensão:

    cd wkhtmltox
    phpize --clean
    git pull origin master
    phpize
    ./configure --with-wkhtmltox=/path/to/wkhtmltox/installation
    make
    sudo make install

## Configurações em Execução

O comportamento destas funções é afetado pelas configurações do php.ini.

wkhtmltox Opções de Configuração
Nome | Padrão | Modificável | Registro de Alterações
--- | --- | --- | ---
wkhtmltox.graphics | Off | `INI_SYSTEM`|`INI_PERDIR` | >= 0.3.2

Para mais detalhes e definições dos modos INI_*, consulte os Onde uma configuração deve ser definida.

Aqui está uma breve explicação das diretivas de configuração.

`wkhtmltox.graphics` bool

  Permite que libwkhtmltox use gráficos.

# A classe wkhtmltox\PDF\Converter

(wkhtmltox >= 0.1.0)

## Introdução

Converte uma entrada HTML, ou conjunto de entradas HTML, em saída PDF.

## Resumo da classe

class wkhtmltox\PDF\Converter {
/* Constructor */
public function __construct(array `$settings` = ?)
/* Métodos */
public function add(wkhtmltox\PDF\Object `$object`): void
public function convert(): ?string
public function getVersion(): string
}

# wkhtmltox\PDF\Converter::add

(wkhtmltox >= 0.1.0)

wkhtmltox\PDF\Converter::add — Adiciona um objeto para conversão

### Descrição

public function wkhtmltox\PDF\Converter::add(wkhtmltox\PDF\Object `$object`): void

Adiciona o objeto fornecido à conversão

### Parâmetros

`object`

  O objeto a ser adicionado.

# wkhtmltox\PDF\Converter::__construct

(wkhtmltox >= 0.1.0)

wkhtmltox\PDF\Converter::__construct — Criar um novo conversor de PDF

### Descrição

public function wkhtmltox\PDF\Converter::__construct(array `$settings` = ?)

Cria um conversor de PDF, usando configurações opcionais.

### Parâmetros

`settings`

  Nome | Descrição | Valores | Registro de modificações
  --- | --- | --- | ---
  size.pageSize | tamanho do papel do documento de saída | A4 | >= 0.1.0
  size.width | largura do documento de saída | 210mm | >= 0.1.0
  size.height | altura do documento de saída | 297mm | >= 0.1.0
  orientation | orientação do documento de saída |
  Paisagem
  Retrato
  | >= 0.1.0
  colorMode | modo de cor do documento de saída |
  Colorido
  Escala de cinza
  | >= 0.1.0
  resolution | resolução do documento de saída | provavelmente não tem efeito | >= 0.1.0
  dpi | ppp (pontos por polegada) para usar durante a impressão | 80 | >= 0.1.0
  pageOffset | inteiro adicionado aos números de página gerando cabeçalhos, rodapés e sumário |  | >= 0.1.0
  copies |  |  | >= 0.1.0
  collate | cópias agrupadas | booleano | >= 0.1.0
  outline | gera estrutura de tópicos do PDF | booleano | >= 0.1.0
  outlineDepth | profundidade máxima da estrutura de tópicos |  | >= 0.1.0
  dumpOutline | caminho do arquivo para despejar o XML de estrutura de tópicos |  | >= 0.1.0
  out | caminho do arquivo de saída, se o stdout "-" for usado |  | >= 0.1.0
  documentTitle | título para o documento de saída |  | >= 0.1.0
  useCompression | habilita ou desabilita a compressão sem perdas | boolean | >= 0.1.0
  margin.top | tamanho da margem superior | 2cm | >= 0.1.0
  margin.bottom | tamanho da margem inferior | 2cm | >= 0.1.0
  margin.left | tamanho da margem esquerda | 2cm | >= 0.1.0
  margin.right | tamanho da margem direita | 2cm | >= 0.1.0
  imageDPI | PPP máximo para imagens no documento de saída |  | >= 0.1.0
  imageQuality | o fator de compressão JPEG para imagens no documento de saída | 94 | >= 0.1.0
  load.cookieJar | caminho do arquivo usado para carregar e armazenar cookies | /tmp/cookies.txt | >= 0.1.0

# wkhtmltox\PDF\Converter::convert

(wkhtmltox >= 0.1.0)

wkhtmltox\PDF\Converter::convert — Executa conversão de PDF

### Descrição

public function wkhtmltox\PDF\Converter::convert(): ?string

Executa a conversão de todos os objetos adicionados anteriormente.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Quando o valor de retorno for usado, ele será preenchido com o conteúdo do buffer de conversão.

# wkhtmltox\PDF\Converter::getVersion

(wkhtmltox >= 0.3.2)

wkhtmltox\PDF\Converter::getVersion — Determina a versão do conversor

### Descrição

public function wkhtmltox\PDF\Converter::getVersion(): string

Determina a versão do conversor conforme relatado por libwkhtmltox.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string de versão.

## Índice

- wkhtmltox\PDF\Converter::add — Adiciona um objeto para conversão
- wkhtmltox\PDF\Converter::__construct — Criar um novo conversor de PDF
- wkhtmltox\PDF\Converter::convert — Executa conversão de PDF
- wkhtmltox\PDF\Converter::getVersion — Determina a versão do conversor

# A classe wkhtmltox\PDF\Object

(wkhtmltox >= 0.1.0)

## Introdução

Representa um documento HTML, entrada para conversor PDF.

## Resumo da classe

class wkhtmltox\PDF\Object {
/* Constructor */
public function __construct(string `$buffer`, array `$settings` = ?)
}

# wkhtmltox\PDF\Object::__construct

(wkhtmltox >= 0.1.0)

wkhtmltox\PDF\Object::__construct — Criar um novo objeto PDF

### Descrição

public function wkhtmltox\PDF\Object::__construct(string `$buffer`, array `$settings` = ?)

Cria um novo objeto PDF a partir do buffer fornecido e das configurações opcionais.

### Parâmetros

`buffer`

  HTML

`settings`

  Nome | Descrição | Valores | Registro de Modificações
  --- | --- | --- | ---
  page | URL ou caminho do HTML a ser convertido |  | >= 0.1.0
  useExternalLinks | defina como true para converter links externos na entrada em links PDF externos na saída | booleano | >= 0.1.0
  useLocalLinks | defina como true para converter links internos na entrada em links PDF internos na saída | booleano | >= 0.1.0
  produceForms | defina como true para transformar formulários HTML em formulários PDF | booleano | >= 0.1.0
  replacements | não documentado |  | >= 0.1.0
  includeInOutline | defina como true para incluir seções deste objeto no esboço e no sumário | booleano | >= 0.1.0
  pagesCount | defina como true para fazer a contagem de páginas no sumário, incluindo o número de páginas neste objeto | booleano | >= 0.1.0
  tocXsl | defina como folha de estilo para converter este objeto em um objeto de sumário |  | >= 0.1.0
  toc.useDottedLines | defina como true para usar linhas pontilhadas no sumário | booleano | >= 0.1.0
  toc.captionText | o texto da legenda para o sumário |  | >= 0.1.0
  toc.forwardLinks | defina como true para criar links do sumário para o conteúdo | booleano | >= 0.1.0
  toc.backLinks | defina como true para criar links do conteúdo para o sumário | booleano | >= 0.1.0
  toc.indentation | recuo para o sumário | 2em | >= 0.1.0
  toc.fontScale | o fator para reduzir a fonte em cada nível do sumário | 0.8 | >= 0.1.0
  header.fontSize | tamanho da fonte para uso no cabeçalho | 13 | >= 0.1.0
  header.fontName | nome da fonte para uso no cabeçalho | times | >= 0.1.0
  header.left | texto à esquerda do cabeçalho |  | >= 0.1.0
  header.center | texto no centro do cabeçalho |  | >= 0.1.0
  header.right | texto à direita do cabeçalho |  | >= 0.1.0
  header.line | habilita ou desabilita a regra horizontal sob o cabeçalho | booleano | >= 0.1.0
  header.spacing | espaço entre o cabeçalho e o conteúdo | 1.8 | >= 0.1.0
  header.htmlUrl | URL ou caminho do HTML a ser usado no cabeçalho |  | >= 0.1.0
  footer.fontSize | tamanho da fonte para uso no rodapé | 13 | >= 0.1.0
  footer.fontName | nome da fonte para uso no rodapé | times | >= 0.1.0
  footer.left | texto à esquerda do rodapé |  | >= 0.1.0
  footer.center | texto no centro do rodapé |  | >= 0.1.0
  footer.right | texto à direita do rodapé |  | >= 0.1.0
  footer.line | habilita ou desabilita a régua horizontal sob o rodapé | booleano | >= 0.1.0
  footer.spacing | espaço entre o rodapé e o conteúdo | 1.8 | >= 0.1.0
  footer.htmlUrl | URL ou caminho do HTML para usar no rodapé |  | >= 0.1.0
  load.username | nome de usuário a ser usado ao fazer login em um site | bart | >= 0.1.0
  load.password | a senha usada para acessar um site | elbarto | >= 0.1.0
  load.jsdelay | o tempo em milissegundos que se espera após o carregamento de uma página até que ela seja capturada | 1200 | >= 0.1.0
  load.zoomFactor | o nível de zoom que deve ser aplicado ao conteúdo | 2.2 | >= 0.1.0
  load.customHeaders | cabeçalhos personalizados a serem enviados ao solicitar a página principal da web |  | >= 0.1.0
  load.repertCustomHeaders | defina como true para enviar com todas as solicitações | boolean | >= 0.1.0
  load.cookies | string de cookie a ser enviada ao solicitar a página principal da web |  | >= 0.1.0
  load.post | String POST a ser enviada ao solicitar a página principal da web |  | >= 0.1.0
  load.blockLocalFileAccess | impede que arquivos locais e arquivos encaminhados acessem outros arquivos locais. | boolean | >= 0.1.0
  load.stopSlowScript | interrompe a execução de javascript lento | boolean |
  load.debugJavascript | permite que o javascript gere avisos | boolean | >= 0.1.0
  load.loadErrorHandling | define a estratégia de tratamento de erros |
  abort | interrompe o processo de conversão
  skip | não adiciona o objeto à saída final
  ignore | tenta adicionar o objeto à saída final
  | >= 0.1.0
  load.proxy |  |  | >= 0.1.0
  web.background | inclui imagem de fundo na saída | boolean | >= 0.1.0
  web.loadImages | inclui imagens na saída | boolean | >= 0.1.0
  web.enableJavascript | ativa ou desativa o javascript | boolean | >= 0.1.0
  web.enableIntelligentShrinking | permite tentar ajustar mais conteúdo na página, aplicando-se apenas à saída em PDF | boolean | >= 0.1.0
  web.minimumFontSize | o tamanho mínimo de fonte permitido | 9 | >= 0.1.0
  web.printMediaType | imprime conteúdo usando mídia impressa em vez de mídia digital | boolean | >= 0.1.0
  web.defaultEncoding | conteúdo a ser usado onde nenhuma codificação for especificada | utf-8 | >= 0.1.0
  web.userStyleSheet | URL ou caminho para uma folha de estilo especificada pelo usuário | /path/to/style.css | >= 0.1.0
  web.enablePlugins | ativa ou desativa plugins NS | boolean | >= 0.1.0

## Índice

- wkhtmltox\PDF\Object::__construct — Criar um novo objeto PDF

# A classe wkhtmltox\Image\Converter

(wkhtmltox >= 0.1.0)

## Introdução

Converte uma entrada HTML em vários formatos de imagem.

## Resumo da classe

class wkhtmltox\Image\Converter {
/* Constructor */
public function __construct(string `$buffer` = ?, array `$settings` = ?)
/* Métodos */
public function convert(): ?string
public function getVersion(): string
}

# wkhtmltox\Image\Converter::__construct

(wkhtmltox >= 0.1.0)

wkhtmltox\Image\Converter::__construct — Cria um novo conversor de imagem

### Descrição

public function wkhtmltox\Image\Converter::__construct(string `$buffer` = ?, array `$settings` = ?)

Cria um conversor de imagem, opcionalmente recebendo um buffer de entrada e definições de configuração.

### Parâmetros

`buffer`

  HTML

`settings`

  Nome | Descrição | Valores | Registro de modificações
  --- | --- | --- | ---
  in | URL ou caminho do arquivo de entrada, se "-" stdin for usado | /path/to/markup.html | >= 0.1.0
  out | caminho do arquivo de saída, se "-" stdout for usado, por padrão um buffer interno é usado | /path/to/output.png | >= 0.1.0
  fmt | formato de saída a ser usado |
  "" | padrão
  jpg | saída como JPEG
  png | saída como PNG
  bmp | saída como bitmap
  svg | saída como SVG
  | >= 0.1.0
  transparent | ao gerar um PNG ou SVG, torna o fundo branco transparente | boolean | >= 0.1.0
  screenWidth | a largura da tela usada para renderizar em pixels | 800 | >= 0.1.0
  smartWidth | quando true, screenWidth é expandido para a largura do conteúdo | boolean | >= 0.1.0
  quality | fator de compressão a ser usado ao gerar uma imagem JPEG | 94 | >= 0.1.0
  crop.left | coordenada esquerda/x da janela a ser capturada em pixels | 200 | >= 0.1.0
  crop.top | coordenada superior/y da janela a ser capturada em pixels | 200 | >= 0.1.0
  crop.width | largura da janela a ser capturada em pixels | 200 | >= 0.1.0
  crop.height | altura da janela a ser capturada em pixels | 200 | >= 0.1.0
  load.cookieJar | caminho do arquivo usado para carregar e armazenar cookies | /tmp/cookies.txt | >= 0.1.0
  load.username | nome de usuário a ser usado ao fazer login em um site | bart | >= 0.1.0
  load.password | a senha usada para acessar um site | elbarto | >= 0.1.0
  load.jsdelay | o tempo em milissegundos que se espera após o carregamento de uma página até que ela seja capturada | 1200 | >= 0.1.0
  load.zoomFactor | o nível de zoom que deve ser aplicado ao conteúdo | 2.2 | >= 0.1.0
  load.customHeaders | cabeçalhos personalizados a serem enviados ao solicitar a página principal da web |  | >= 0.1.0
  load.repertCustomHeaders | defina como true para enviar com todas as solicitações | boolean | >= 0.1.0
  load.cookies | string de cookie a ser enviada ao solicitar a página principal da web |  | >= 0.1.0
  load.post | String POST a ser enviada ao solicitar a página principal da web |  | >= 0.1.0
  load.blockLocalFileAccess | impede que arquivos locais e arquivos encaminhados acessem outros arquivos locais. | boolean | >= 0.1.0
  load.stopSlowScript | interrompe a execução de javascript lento | boolean |
  load.debugJavascript | permite que o javascript gere avisos | boolean | >= 0.1.0
  load.loadErrorHandling | define a estratégia de tratamento de erros |
  abort | interrompe o processo de conversão
  skip | não adiciona o objeto à saída final
  ignore | tenta adicionar o objeto à saída final
  | >= 0.1.0
  load.proxy |  |  | >= 0.1.0
  web.background | inclui imagem de fundo na saída | boolean | >= 0.1.0
  web.loadImages | inclui imagens na saída | boolean | >= 0.1.0
  web.enableJavascript | ativa ou desativa o javascript | boolean | >= 0.1.0
  web.enableIntelligentShrinking | permite tentar ajustar mais conteúdo na página, aplicando-se apenas à saída em PDF | boolean | >= 0.1.0
  web.minimumFontSize | o tamanho mínimo de fonte permitido | 9 | >= 0.1.0
  web.printMediaType | imprime conteúdo usando mídia impressa em vez de mídia digital | boolean | >= 0.1.0
  web.defaultEncoding | conteúdo a ser usado onde nenhuma codificação for especificada | utf-8 | >= 0.1.0
  web.userStyleSheet | URL ou caminho para uma folha de estilo especificada pelo usuário | /path/to/style.css | >= 0.1.0
  web.enablePlugins | ativa ou desativa plugins NS | boolean | >= 0.1.0

# wkhtmltox\Image\Converter::convert

(wkhtmltox >= 0.1.0)

wkhtmltox\Image\Converter::convert — Executa conversão de imagem

### Descrição

public function wkhtmltox\Image\Converter::convert(): ?string

Executa a conversão do buffer de entrada.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Quando o valor de retorno for usado, ele será preenchido com o conteúdo do buffer de conversão.

# wkhtmltox\Image\Converter::getVersion

(wkhtmltox >= 0.3.2)

wkhtmltox\Image\Converter::getVersion — Determina a versão do conversor

### Descrição

public function wkhtmltox\Image\Converter::getVersion(): string

Determina a versão do conversor conforme relatado por libwkhtmltox.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Retorna uma string de versão

Aviso

Isso ainda não foi implementado pelo libwkhtmltox.

## Índice

- wkhtmltox\Image\Converter::__construct — Cria um novo conversor de imagem
- wkhtmltox\Image\Converter::convert — Executa conversão de imagem
- wkhtmltox\Image\Converter::getVersion — Determina a versão do conversor

- Instalação/Configuração
  - Dependências
  - Instalação
  - Configurações em Execução
- wkhtmltox\PDF\Converter — A classe wkhtmltox\PDF\Converter
  - wkhtmltox\PDF\Converter::add — Adiciona um objeto para conversão
  - wkhtmltox\PDF\Converter::__construct — Criar um novo conversor de PDF
  - wkhtmltox\PDF\Converter::convert — Executa conversão de PDF
  - wkhtmltox\PDF\Converter::getVersion — Determina a versão do conversor
- wkhtmltox\PDF\Object — A classe wkhtmltox\PDF\Object
  - wkhtmltox\PDF\Object::__construct — Criar um novo objeto PDF
- wkhtmltox\Image\Converter — A classe wkhtmltox\Image\Converter
  - wkhtmltox\Image\Converter::__construct — Cria um novo conversor de imagem
  - wkhtmltox\Image\Converter::convert — Executa conversão de imagem
  - wkhtmltox\Image\Converter::getVersion — Determina a versão do conversor

# Criação de documento PostScript

# Introdução

Este módulo permite criar documentos PostScript. Tem muitas semelhanças com a extensão pdf. Na verdade a API é quase idêntica e em muitos casos pode-se simplesmente substituir o prefixo de cada função de pdf_ para ps_. Isso também funciona para funções que não têm significado no documento PostScript (como adicionar hiperlinks), mas terão efeito se o documento for convertido para PDF.

Documentos criados por esta extensão às vezes são até superiores aos documentos criados com a extensão pdf, porque as funções de renderização de texto do pslib podem lidar com kerning, hifenização e ligaduras, o que resulta em uma saída muito melhor de texto em caixa.

# Instalação/Configuração

## Índice

- Dependências
- Instalação
- Tipos de Recurso

## Dependências

É necessário pelo menos a biblioteca pslib >= 0.1.12. A biblioteca ps (pslib) está disponível em » http://pslib.sourceforge.net/.

## Instalação

Informações para instalar esta extensão PECL podem ser encontradas no capítulo Instalação de Extensões PECL do manual. Informações adicionais, como novas versões, downloads, arquivos fontes, informações do mantenedor e um CHANGELOG, podem ser encontradas aqui: » https://pecl.php.net/package/ps.

## Tipos de Recurso

Esta extensão define um recurso de documento PostScript retornado por ps_new().

# Constantes predefinidas

As constantes abaixo são definidas por esta extensão e só estarão disponíveis quando a extensão tiver sido compilada no PHP ou tiver sido carregada dinamicamente em tempo de execução.

As duas tabelas a seguir listam todas as constantes definidas pela extensão ps.

Constantes para limites de linha
Nome | Significado
--- | ---
`ps_LINECAP_BUTT` |
`ps_LINECAP_ROUND` |
`ps_LINECAP_SQUARED` |

Constantes para junções de linha
Nome | Significado
--- | ---
`ps_LINEJOIN_MITER` |
`ps_LINEJOIN_ROUND` |
`ps_LINEJOIN_BEVEL` |

# Funções de PS

## Informações de contato

Se você tiver comentários, correções de bugs ou melhorias para esta extensão ou pslib, envie-me um e-mail » steinm@php.net. Qualquer ajuda é muito bem vinda.

# ps_add_bookmark

(PECL ps >= 1.1.0)

ps_add_bookmark — Adiciona marcador à página atual

### Descrição

function ps_add_bookmark(
resource `$psdoc`,
string `$text`,
int `$parent` = 0,
int `$open` = 0
): int

Adiciona um marcador para a página atual. Os marcadores geralmente aparecem em visualizadores de PDF à esquerda da página, em uma árvore hierárquica. Clicar em um marcador irá para a página especificada.

A nota não ficará visível se o documento for impresso ou visualizado, mas aparecerá se o documento for convertido para PDF pelo Acrobat Distiller™ ou Ghostview.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`text`

  O texto usado para exibir o marcador.

`parent`

  Um marcador criado anteriormente por esta função que é usado como pai do novo marcador.

`open`

  Se `open` for diferente de zero, o marcador será mostrado como aberto pelo visualizador de PDF.

### Valor Retornado

O valor retornado é uma referência para o marcador. Ele só é usado se o marcador for usado como pai. O valor será maior que zero se a função for bem-sucedida. Em caso de erro, zero será retornado.

### Veja Também

- ps_add_launchlink() - Adiciona hiperlink que inicia o arquivo
- ps_add_pdflink() - Adiciona link para uma página em um segundo documento PDF
- ps_add_weblink() - Adiciona link para um local da web

# ps_add_launchlink

(PECL ps >= 1.1.0)

ps_add_launchlink — Adiciona hiperlink que inicia o arquivo

### Descrição

function ps_add_launchlink(
resource `$psdoc`,
float `$llx`,
float `$lly`,
float `$urx`,
float `$ury`,
string `$filename`
): bool

Coloca um hiperlink na posição fornecida, apontando para um programa de arquivo que está sendo iniciado ao ser clicado. A posição de origem do hiperlink é um retângulo com seu canto inferior esquerdo em (llx, lly) e seu canto superior direito em (urx, ury). O retângulo tem, por padrão, uma borda azul fina.

A nota não ficará visível se o documento for impresso ou visualizado, mas aparecerá se o documento for convertido para PDF pelo Acrobat Distiller™ ou Ghostview.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`llx`

  A coordenada x do canto inferior esquerdo.

`lly`

  A coordenada y do canto inferior esquerdo.

`urx`

  A coordenada x do canto superior direito.

`ury`

  A coordenada y do canto superior direito.

`filename`

  O caminho do programa a ser iniciado quando o hiperlink é clicado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_add_locallink() - Adiciona link para uma página no mesmo documento
- ps_add_pdflink() - Adiciona link para uma página em um segundo documento PDF
- ps_add_weblink() - Adiciona link para um local da web

# ps_add_locallink

(PECL ps >= 1.1.0)

ps_add_locallink — Adiciona link para uma página no mesmo documento

### Descrição

function ps_add_locallink(
resource `$psdoc`,
float `$llx`,
float `$lly`,
float `$urx`,
float `$ury`,
int `$page`,
string `$dest`
): bool

Coloca um hiperlink na posição especificada, apontando para uma página no mesmo documento. Clicar no link levará para a página especificada. A primeira página de um documento tem o número 1.

A posição de origem do hiperlink é um retângulo com seu canto inferior esquerdo em (`llx`, `lly`) e seu canto superior direito em (`urx`, `ury`). O retângulo tem, por padrão, uma borda azul fina.

A nota não ficará visível se o documento for impresso ou visualizado, mas aparecerá se o documento for convertido para PDF pelo Acrobat Distiller™ ou Ghostview.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`llx`

  A coordenada x do canto inferior esquerdo.

`lly`

  A coordenada y do canto inferior esquerdo.

`urx`

  A coordenada x do canto superior direito.

`ury`

  A coordenada y do canto superior direito.

`page`

  O número da página exibida ao clicar no link.

`dest`

  O parâmetro `dest` determina como o documento está sendo visualizado. Pode ser `fitpage`, `fitwidth`, `fitheight` ou `fitbbox`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_add_launchlink() - Adiciona hiperlink que inicia o arquivo
- ps_add_pdflink() - Adiciona link para uma página em um segundo documento PDF
- ps_add_weblink() - Adiciona link para um local da web

# ps_add_note

(PECL ps >= 1.1.0)

ps_add_note — Adiciona nota à página atual

### Descrição

function ps_add_note(
resource `$psdoc`,
float `$llx`,
float `$lly`,
float `$urx`,
float `$ury`,
string `$contents`,
string `$title`,
string `$icon`,
int `$open`
): bool

Adiciona uma nota em uma determinada posição na página. As notas são como pequenas folhas retangulares com texto, que podem ser colocadas em qualquer lugar da página. Elas são exibidas dobradas ou desdobradas. Se dobradas, o ícone especificado é usado como um espaço reservado.

A nota não ficará visível se o documento for impresso ou visualizado, mas aparecerá se o documento for convertido para PDF pelo Acrobat Distiller™ ou Ghostview.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`llx`

  A coordenada x do canto inferior esquerdo.

`lly`

  A coordenada y do canto inferior esquerdo.

`urx`

  A coordenada x do canto superior direito.

`ury`

  A coordenada y do canto superior direito.

`contents`

  O texto da nota.

`title`

  O título da nota conforme exibido no cabeçalho da nota.

`icon`

  O ícone exibido se a nota estiver dobrada. Este parâmetro pode ser definido como `comment`, `insert`, `note`, `paragraph`, `newparagraph`, `key` ou `help`.

`open`

  Se `open` for diferente de zero, a nota será exibida desdobrada após a abertura do documento com um visualizador de PDF.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_add_pdflink() - Adiciona link para uma página em um segundo documento PDF
- ps_add_launchlink() - Adiciona hiperlink que inicia o arquivo
- ps_add_locallink() - Adiciona link para uma página no mesmo documento
- ps_add_weblink() - Adiciona link para um local da web

# ps_add_pdflink

(PECL ps >= 1.1.0)

ps_add_pdflink — Adiciona link para uma página em um segundo documento PDF

### Descrição

function ps_add_pdflink(
resource `$psdoc`,
float `$llx`,
float `$lly`,
float `$urx`,
float `$ury`,
string `$filename`,
int `$page`,
string `$dest`
): bool

Coloca um hiperlink na posição fornecida, apontando para um segundo documento PDF. Clicar no link redirecionará para o documento na página fornecida. A primeira página de um documento tem o número 1.

A posição de origem do hiperlink é um retângulo com seu canto inferior esquerdo em (`llx`, `lly`) e seu canto superior direito em (`urx`, `ury`). O retângulo tem, por padrão, uma borda azul fina.

A nota não ficará visível se o documento for impresso ou visualizado, mas aparecerá se o documento for convertido para PDF pelo Acrobat Distiller™ ou Ghostview.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`llx`

  A coordenada x do canto inferior esquerdo.

`lly`

  A coordenada y do canto inferior esquerdo.

`urx`

  A coordenada x do canto superior direito.

`ury`

  A coordenada y do canto superior direito.

`filename`

  O nome do documento PDF a ser aberto ao clicar neste link.

`page`

  O número da página do documento PDF de destino.

`dest`

  O parâmetro `dest` determina como o documento está sendo visualizado. Pode ser `fitpage`, `fitwidth`, `fitheight` ou `fitbbox`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_add_launchlink() - Adiciona hiperlink que inicia o arquivo
- ps_add_locallink() - Adiciona link para uma página no mesmo documento
- ps_add_weblink() - Adiciona link para um local da web

# ps_add_weblink

(PECL ps >= 1.1.0)

ps_add_weblink — Adiciona link para um local da web

### Descrição

function ps_add_weblink(
resource `$psdoc`,
float `$llx`,
float `$lly`,
float `$urx`,
float `$ury`,
string `$url`
): bool

Coloca um hiperlink na posição fornecida, apontando para uma página da web. A posição de origem do hiperlink é um retângulo com seu canto inferior esquerdo em (`llx`, `lly`) e seu canto superior direito em (`urx`, `ury`). O retângulo tem, por padrão, uma borda fina azul.

A nota não ficará visível se o documento for impresso ou visualizado, mas aparecerá se o documento for convertido para PDF pelo Acrobat Distiller™ ou Ghostview.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`llx`

  A coordenada x do canto inferior esquerdo.

`lly`

  A coordenada y do canto inferior esquerdo.

`urx`

  A coordenada x do canto superior direito.

`ury`

  A coordenada y do canto superior direito.

`url`

  A URL do hiperlink a ser aberto ao clicar neste link, por exemplo, `http://www.php.net`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_add_launchlink() - Adiciona hiperlink que inicia o arquivo
- ps_add_locallink() - Adiciona link para uma página no mesmo documento
- ps_add_pdflink() - Adiciona link para uma página em um segundo documento PDF

# ps_arc

(PECL ps >= 1.1.0)

ps_arc — Desenha um arco no sentido anti-horário

### Descrição

function ps_arc(
resource `$psdoc`,
float `$x`,
float `$y`,
float `$radius`,
float `$alpha`,
float `$beta`
): bool

Desenha uma parte de um círculo com um ponto médio em (`x`, `y`). O arco começa em um ângulo `alpha` e termina em um ângulo `beta`. Ele é desenhado no sentido anti-horário (use ps_arcn() para desenhar no sentido horário). O subcaminho adicionado ao caminho atual começa no arco no ângulo `alpha` e termina no arco no ângulo `beta`.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`x`

  A coordenada x do ponto médio do círculo.

`y`

  A coordenada y do ponto médio do círculo.

`radius`

  O raio do círculo.

`alpha`

  O ângulo inicial em graus.

`beta`

  O ângulo final em graus.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_arcn() - Desenha um arco no sentido horário

# ps_arcn

(PECL ps >= 1.1.0)

ps_arcn — Desenha um arco no sentido horário

### Descrição

function ps_arcn(
resource `$psdoc`,
float `$x`,
float `$y`,
float `$radius`,
float `$alpha`,
float `$beta`
): bool

Desenha uma parte de um círculo com um ponto médio em (`x`, `y`). O arco começa em um ângulo `alpha` e termina em um ângulo `beta`. Ele é desenhado no sentido horário (use ps_arc() para desenhar no sentido anti-horário). O subcaminho adicionado ao caminho atual começa no arco no ângulo `beta` e termina no arco em ângulo `alpha`.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`x`

  A coordenada x do ponto médio do círculo.

`y`

  A coordenada y do ponto médio do círculo.

`radius`

  O raio do círculo.

`alpha`

  O ângulo inicial em graus.

`beta`

  O ângulo final em graus.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_arc() - Desenha um arco no sentido anti-horário

# ps_begin_page

(PECL ps >= 1.1.0)

ps_begin_page — Inicia uma nova página

### Descrição

function ps_begin_page(resource `$psdoc`, float `$width`, float `$height`): bool

Inicia uma nova página. Embora os parâmetros `width` e `height` impliquem um tamanho de página diferente para cada página, isso não é possível em PostScript. A primeira chamada de ps_begin_page() definirá o tamanho da página para todo o documento. Chamadas consecutivas não terão efeito, exceto para criar uma nova página. A situação é diferente se você pretende converter o documento PostScript para PDF. Esta função insere marcas de PDF no documento, que podem definir o tamanho de cada página individualmente. O documento PDF resultante terá tamanhos de página diferentes.

Embora o PostScript não reconheça diferentes tamanhos de página, o pslib coloca uma caixa delimitadora para cada página do documento. Este tamanho é avaliado por alguns visualizadores PostScript e terá precedência sobre a BoundingBox no cabeçalho do documento. Isso pode levar a resultados inesperados quando se define uma BoundingBox cujo canto inferior esquerdo não é (0, 0), porque a caixa delimitadora da página sempre terá um canto inferior esquerdo (0, 0) e sobrescreve a configuração global.

Cada página é encapsulada em salvar/restaurar. Isso significa que a maioria das configurações feitas em uma página não serão mantidas na página seguinte.

Se, até a primeira chamada de ps_begin_page(), não houver nenhuma chamada de ps_findfont(), o cabeçalho do documento PostScript será exibido e a caixa delimitadora será definida para o tamanho da primeira página. O canto inferior esquerdo da caixa delimitadora é definido como (0, 0). Se ps_findfont() tiver sido chamado antes, o cabeçalho já terá sido exibido e o documento não terá uma caixa delimitadora válida. Para evitar isso, deve-se chamar ps_set_info() para definir o campo de informações `BoundingBox` e possivelmente `Orientation` antes de quaisquer chamadas de ps_findfont() ou ps_begin_page().

> Nota:

> Até a versão 0.2.6 do pslib, esta função sempre sobrescreverá o BoundingBox e a Orientation, caso tenha sido definida anteriormente com ps_set_info() e ps_findfont() não tenha sido chamada anteriormente.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`width`

  A largura da página em pixels, por exemplo, 596 para o formato A4.

`height`

  A altura da página em pixels, por exemplo, 842 para o formato A4.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_end_page() - Termina uma página
- ps_findfont() - Carrega uma fonte
- ps_set_info() - Define campos de informação do documento

# ps_begin_pattern

(PECL ps >= 1.2.0)

ps_begin_pattern — Inicia um novo padrão

### Descrição

function ps_begin_pattern(
resource `$psdoc`,
float `$width`,
float `$height`,
float `$xstep`,
float `$ystep`,
int `$painttype`
): int|false

Inicia um novo padrão. Um padrão é como uma página contendo, por exemplo, um desenho que pode ser usado para preencher áreas. É usado como uma cor, chamando ps_setcolor() e definindo o parâmetro de espaço de cores com o valor `pattern`.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`width`

  A largura do padrão em pixels.

`height`

  A altura do padrão em pixels.

`xstep`

  A distância em pixels dos posicionamentos do padrão na direção horizontal.

`ystep`

  A distância em pixels dos posicionamentos do padrão na direção vertical.

`painttype`

  Deve ser 1 ou 2.

### Valor Retornado

O identificador do padrão ou `false` em caso de falha.

### Exemplos

Exemplo #1 Criando e usando um padrão

    <?php
    $ps = ps_new();

    if (!ps_open_file($ps, "padrao.ps")) {
      print "Não é possível abrir o arquivo PostScript\n";
      exit;
    }

    ps_set_parameter($ps, "warning", "true");
    ps_set_info($ps, "Creator", "padrao.php");
    ps_set_info($ps, "Author", "Uwe Steinmann");
    ps_set_info($ps, "Title", "Exemplo de Padrão");

    $pspattern = ps_begin_pattern($ps, 10.0, 10.0, 10.0, 10.0, 1);
    ps_setlinewidth($ps, 0.2);
    ps_setcolor($ps, "stroke", "rgb", 0.0, 0.0, 1.0, 0.0);
    ps_moveto($ps, 0, 0);
    ps_lineto($ps, 7, 7);
    ps_stroke($ps);
    ps_moveto($ps, 0, 7);
    ps_lineto($ps, 7, 0);
    ps_stroke($ps);
    ps_end_pattern($ps);

    ps_begin_page($ps, 596, 842);
    ps_setcolor($ps, "both", "pattern", $pspattern, 0.0, 0.0, 0.0);
    ps_rect($ps, 50, 400, 200, 200);
    ps_fill($ps);
    ps_end_page($ps);

    ps_close($ps);
    ps_delete($ps);
    ?>

### Veja Também

- ps_end_pattern() - Termina um padrão
- ps_setcolor() - Define a cor atual
- ps_shading_pattern() - Cria um padrão com base em um sombreamento

# ps_begin_template

(PECL ps >= 1.2.0)

ps_begin_template — Inicia um novo modelo

### Descrição

function ps_begin_template(resource `$psdoc`, float `$width`, float `$height`): int

Inicia um novo modelo. Um modelo é chamado de formulário na linguagem PostScript. Ele é criado de forma semelhante a um padrão, mas usado como uma imagem. Os modelos são frequentemente usados ​​para desenhos que são colocados várias vezes ao longo do documento, por exemplo, como o logotipo de uma empresa. Todas as funções de desenho podem ser usadas dentro de um modelo. O modelo não será desenhado até que seja colocado por ps_place_image().

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`width`

  A largura do modelo em pixels.

`height`

  A altura do modelo em pixels.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Criando e usando um modelo

    <?php
    $ps = ps_new();

    if (!ps_open_file($ps, "modelo.ps")) {
      print "Não é possível abrir o arquivo PostScript\n";
      exit;
    }

    ps_set_parameter($ps, "warning", "true");
    ps_set_info($ps, "Creator", "modelo.php");
    ps_set_info($ps, "Author", "Uwe Steinmann");
    ps_set_info($ps, "Title", "Exemplo de modelo");

    $pstemplate = ps_begin_template($ps, 30.0, 30.0);
    ps_moveto($ps, 0, 0);
    ps_lineto($ps, 30, 30);
    ps_moveto($ps, 0, 30);
    ps_lineto($ps, 30, 0);
    ps_stroke($ps);
    ps_end_template($ps);

    ps_begin_page($ps, 596, 842);
    ps_place_image($ps, $pstemplate, 20.0, 20.0, 1.0);
    ps_place_image($ps, $pstemplate, 50.0, 30.0, 0.5);
    ps_place_image($ps, $pstemplate, 70.0, 70.0, 0.6);
    ps_place_image($ps, $pstemplate, 30.0, 50.0, 1.3);
    ps_end_page($ps);

    ps_close($ps);
    ps_delete($ps);
    ?>

### Veja Também

- ps_end_template() - Termina um modelo

# ps_circle

(PECL ps >= 1.1.0)

ps_circle — Desenha um círculo

### Descrição

function ps_circle(
resource `$psdoc`,
float `$x`,
float `$y`,
float `$radius`
): bool

Desenha um círculo com seu ponto médio em (`x`, `y`). O círculo começa e termina na posição (`x`+`radius`, `y`). Se esta função for chamada fora de um caminho, ela iniciará um novo caminho. Se for chamada dentro de um caminho, ela adicionará o círculo como um subcaminho. Se a última operação de desenho não terminar no ponto (`x`+`radius`, `y`), haverá uma lacuna no caminho.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`x`

  A coordenada x do ponto médio do círculo.

`y`

  A coordenada y do ponto médio do círculo.

`radius`

  O raio do círculo.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_arc() - Desenha um arco no sentido anti-horário
- ps_arcn() - Desenha um arco no sentido horário

# ps_clip

(PECL ps >= 1.1.0)

ps_clip — Recorta o desenho no caminho atual

### Descrição

function ps_clip(resource `$psdoc`): bool

Pega o caminho atual e o utiliza para definir a borda de uma área de recorte. Tudo o que for desenhado fora dessa área não ficará visível.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_closepath() - Fecha caminho

# ps_close

(PECL ps >= 1.1.0)

ps_close — Fecha um documento PostScript

### Descrição

function ps_close(resource `$psdoc`): bool

Fecha o documento PostScript.

Esta função grava a parte final do documento PostScript. Ela também grava a árvore de favoritos. ps_close() não libera nenhum recurso, o que é feito por ps_delete().

Esta função também é chamada por ps_delete() se não tiver sido chamada antes.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_open_file() - Abre um arquivo para saída
- ps_delete() - Exclui todos os recursos de um documento PostScript

# ps_close_image

(PECL ps >= 1.1.0)

ps_close_image — Fecha a imagem e libera memória

### Descrição

function ps_close_image(resource `$psdoc`, int `$imageid`): void|false

Fecha uma imagem e libera seus recursos. Uma vez fechada, uma imagem não pode mais ser usada.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`imageid`

  Identificador de recurso da imagem retornado por ps_open_image() ou ps_open_image_file().

### Valor Retornado

Retorna `null` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_open_image() - Lê uma imagem para posicionamento posterior
- ps_open_image_file() - Abre a imagem do arquivo

# ps_closepath

(PECL ps >= 1.1.0)

ps_closepath — Fecha caminho

### Descrição

function ps_closepath(resource `$psdoc`): bool

Conecta o último ponto com o primeiro ponto de um caminho. O caminho resultante pode ser usado para traçar, preencher, recortar, etc.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_clip() - Recorta o desenho no caminho atual
- ps_closepath_stroke() - Fecha e traça o caminho

# ps_closepath_stroke

(PECL ps >= 1.1.0)

ps_closepath_stroke — Fecha e traça o caminho

### Descrição

function ps_closepath_stroke(resource `$psdoc`): bool

Conecta o último ponto com o primeiro ponto de um caminho e desenha a linha fechada resultante.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_closepath() - Fecha caminho

# ps_continue_text

(PECL ps >= 1.1.0)

ps_continue_text — Continua o texto na próxima linha

### Descrição

function ps_continue_text(resource `$psdoc`, string `$text`): bool

Gera um texto uma linha abaixo da última linha. O espaçamento entre linhas é obtido do valor "leading", que deve ser definido com ps_set_value(). A posição real do texto é determinada pelos valores "textx" e "texty", que podem ser solicitados com ps_get_value().

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`text`

  O texto a ser gerado.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_show() - Exibe texto
- ps_show_xy() - Exibe texto na posição fornecida
- ps_show_boxed() - Gera texto em uma caixa

# ps_curveto

(PECL ps >= 1.1.0)

ps_curveto — Desenha uma curva

### Descrição

function ps_curveto(
resource `$psdoc`,
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$x3`,
float `$y3`
): bool

Adiciona uma seção de uma curva de Bézier cúbica descrita pelos três pontos de controle fornecidos para o caminho atual.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`x1`

  Coordenada x do primeiro ponto de controle.

`y1`

  Coordenada y do primeiro ponto de controle.

`x2`

  Coordenada x do segundo ponto de controle.

`y2`

  Coordenada y do segundo ponto de controle.

`x3`

  Coordenada x do terceiro ponto de controle.

`y3`

  Coordenada y do terceiro ponto de controle.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_lineto() - Desenha uma linha

# ps_delete

(PECL ps >= 1.1.0)

ps_delete — Exclui todos os recursos de um documento PostScript

### Descrição

function ps_delete(resource `$psdoc`): bool

Principalmente, libera a memória usada pelo documento. Também fecha um arquivo, caso ele não tenha sido fechado antes com ps_close(). Em qualquer caso, você deve fechar o arquivo com ps_close() antes, porque ps_close() não apenas fecha o arquivo, mas também gera a parte final contendo comentários PostScript, como o número de páginas no documento e a hierarquia de marcadores.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_close() - Fecha um documento PostScript

# ps_end_page

(PECL ps >= 1.1.0)

ps_end_page — Termina uma página

### Descrição

function ps_end_page(resource `$psdoc`): bool

Termina uma página que foi iniciada com ps_begin_page(). Termina uma página e sai do contexto de desenho atual, o que, por exemplo, requer o recarregamento das fontes, caso elas estejam sendo carregadas dentro da página, e a definição de muitos outros parâmetros de desenho, como a largura da linha ou a cor.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_begin_page() - Inicia uma nova página

# ps_end_pattern

(PECL ps >= 1.2.0)

ps_end_pattern — Termina um padrão

### Descrição

function ps_end_pattern(resource `$psdoc`): bool

Termina um padrão iniciado com ps_begin_pattern(). Uma vez finalizado, um padrão pode ser usado como uma cor para preencher áreas.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_begin_pattern() - Inicia um novo padrão

# ps_end_template

(PECL ps >= 1.2.0)

ps_end_template — Termina um modelo

### Descrição

function ps_end_template(resource `$psdoc`): bool

Termina um modelo iniciado com ps_begin_template(). Após o término de um modelo, ele pode ser usado como uma imagem.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_begin_template() - Inicia um novo modelo

# ps_fill

(PECL ps >= 1.1.0)

ps_fill — Preenche o caminho atual

### Descrição

function ps_fill(resource `$psdoc`): bool

Preenche o caminho construído com funções de desenho chamadas anteriormente, como ps_lineto().

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_fill_stroke() - Preenche e traça o caminho atual
- ps_stroke() - Desenha o caminho atual

# ps_fill_stroke

(PECL ps >= 1.1.0)

ps_fill_stroke — Preenche e traça o caminho atual

### Descrição

function ps_fill_stroke(resource `$psdoc`): bool

Preenche e desenha o caminho construído com funções de desenho chamadas anteriormente, como ps_lineto().

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_fill() - Preenche o caminho atual
- ps_stroke() - Desenha o caminho atual

# ps_findfont

(PECL ps >= 1.1.0)

ps_findfont — Carrega uma fonte

### Descrição

function ps_findfont(
resource `$psdoc`,
string `$fontname`,
string `$encoding`,
bool `$embed` = `false`
): int

Carrega uma fonte para uso posterior. Antes que o texto seja gerado com uma fonte carregada, ele deve ser definido com ps_setfont(). Esta função precisa do arquivo de métricas de fontes da Adobe para calcular o espaço usado pelos caracteres. Uma fonte carregada dentro de uma página estará disponível apenas naquela página. As fontes que serão usadas no documento completo devem ser carregadas antes da primeira chamada de ps_begin_page(). Chamar ps_findfont() entre páginas tornará essa fonte disponível para todas as páginas seguintes.

O nome do arquivo afm deve ser `fontname``.afm`. Se a fonte for incorporada, o arquivo `fontname``.pfb` contendo o contorno da fonte também deve estar presente.

Chamar ps_findfont() antes da primeira página requer a geração do cabeçalho PostScript que inclui o BoundingBox para todo o documento. Normalmente, o BoundingBox é definido com a primeira chamada de ps_begin_page(), que agora vem depois de ps_findfont(). Consequentemente, o BoundingBox não foi definido e um aviso será emitido quando ps_findfont() for chamado. Para evitar essa situação, deve-se chamar ps_set_parameter() para definir o BoundingBox antes de ps_findfont() ser chamado.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`fontname`

  O nome da fonte.

`encoding`

  ps_findfont() tentará carregar o arquivo passado no parâmetro `encoding`. Os arquivos de codificação têm a mesma sintaxe daqueles usados ​​por dvips(1). Eles contêm um vetor de codificação de fonte (que atualmente não é usado, mas deve estar presente) e uma lista de ligaduras extras para estender a lista de ligaduras derivadas do arquivo afm.

  `encoding` pode ser `null` ou a string vazia se a codificação padrão (TeXBase1) for usada.

  Se a codificação for definida como `builtin`, não haverá recodificação e a codificação específica da fonte será usada. Isso é muito útil com fontes de símbolos.

`embed`

  Se definido para um valor maior que zero, a fonte será incorporada ao documento. Isso requer a presença do contorno da fonte (arquivo .pfb).

### Valor Retornado

Retorna o identificador da fonte ou zero em caso de erro. O identificador é um número positivo.

### Veja Também

- ps_begin_page() - Inicia uma nova página
- ps_setfont() - Define a fonte a ser usada na saída seguinte

# ps_get_buffer

(PECL ps >= 1.1.0)

ps_get_buffer — Busca o buffer completo contendo os dados PS gerados

### Descrição

function ps_get_buffer(resource `$psdoc`): string

Esta função ainda não foi implementada. Ela sempre retornará uma string vazia. A ideia para uma implementação posterior é gravar o conteúdo do arquivo PostScript em um buffer interno se a criação na memória for solicitada e recuperar o conteúdo do buffer com esta função. Atualmente, os documentos criados na memória são enviados ao navegador sem buffer.

Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

### Veja Também

- ps_open_file() - Abre um arquivo para saída

# ps_get_parameter

(PECL ps >= 1.1.0)

ps_get_parameter — Obtém certos parâmetros

### Descrição

function ps_get_parameter(resource `$psdoc`, string `$name`, float `$modifier` = ?): string|false

Obtém vários parâmetros que foram definidos diretamente por ps_set_parameter() ou indiretamente por uma das outras funções. Parâmetros são, por definição, valores string. Esta função não pode ser usada para recuperar recursos que também foram definidos por ps_set_parameter().

O parâmetro `name` pode ter os seguintes valores.

`fontname`

  O nome da fonte atualmente ativa ou a fonte cujo identificador é passado no parâmetro `modifier`.

`fontencoding`

  A codificação da fonte atualmente ativa.

`dottedversion`

  A versão da biblioteca pslib subjacente no formato <primário>.<secundário>.<terciário>

`scope`

  O escopo do desenho atual. Pode ser object, document, null, page, pattern, path, template, prolog, font, glyph.

`ligaturedisolvechar`

  O caractere que dissolve uma ligadura. Se estiver sendo usada uma fonte que contém a ligadura `ff' e `|' é o caractere que dissolve a ligadura, então `f|f' resultará em dois `f' em vez da ligadura `ff'.

`imageencoding`

  A codificação usada para codificar imagens. Pode ser `hex` ou `85`. A codificação hexadecimal usa dois bytes no arquivo PostScript para cada byte na imagem. 85 significa codificação ASCII85.

`linenumbermode`

  Defina como `paragraph` se as linhas forem numeradas dentro de um parágrafo ou `box` se forem numeradas dentro da caixa ao redor.

`linebreak`

  Usado somente se o texto for gerado com ps_show_boxed(). Se definido como `true`, um retorno de carro adicionará uma quebra de linha.

`parbreak`

  Usado somente se o texto for gerado com ps_show_boxed(). Se definido como `true`, um retorno de carro iniciará um novo parágrafo.

`hyphenation`

  Usado somente se o texto for gerado com ps_show_boxed(). Se definido como `true`, o parágrafo será hifenizado se um dicionário de hifenização estiver definido e existir.

`hyphendict`

  Nome do arquivo do dicionário usado para o padrão de hifenização.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`name`

  Nome do parâmetro.

`modifier`

  Um identificador necessário se um parâmetro de um recurso for solicitado, por exemplo, o tamanho de uma imagem. Nesse caso, o ID do recurso é passado.

### Valor Retornado

Retorna o valor do parâmetro ou `false` em caso de falha.

### Veja Também

- ps_set_parameter() - Define certos parâmetros

# ps_get_value

(PECL ps >= 1.1.0)

ps_get_value — Obtém determinados valores

### Descrição

function ps_get_value(resource `$psdoc`, string `$name`, float `$modifier` = ?): float

Obtém vários valores que foram definidos por ps_set_value(). Os valores são, por definição, números float.

O parâmetro `name` pode ter os seguintes valores.

`fontsize`

  O tamanho da fonte atualmente ativa ou da fonte cujo identificador é passado no parâmetro `modifier`.

`font`

  A fonte atualmente ativa.

`imagewidth`

  A largura da imagem cujo id é passado no parâmetro `modifier`.

`imageheight`

  A altura da imagem cujo id é passado no parâmetro `modifier`.

`capheight`

  A altura de um M maiúsculo na fonte atualmente ativa ou na fonte cujo identificador é passado no parâmetro `modifier`.

`ascender`

  O ascendente da fonte atualmente ativa ou da fonte cujo identificador é passado no parâmetro `modifier`.

`descender`

  O descendente da fonte atualmente ativa ou da fonte cujo identificador é passado no parâmetro `modifier`.

`italicangle`

  O ângulo itálico da fonte atualmente ativa ou da fonte cujo identificador é passado no parâmetro `modifier`.

`underlineposition`

  A posição sublinhada da fonte atualmente ativa ou da fonte cujo identificador é passado no parâmetro `modifier`.

`underlinethickness`

  A espessura do sublinhado da fonte atualmente ativa ou da fonte cujo identificador é passado no parâmetro `modifier`.

`textx`

  A posição x atual para saída de texto.

`texty`

  A posição y atual para saída de texto.

`textrendering`

  O modo atual para renderização de texto.

`textrise`

  O espaço pelo qual o texto é elevado acima da linha de base.

`leading`

  A distância entre as linhas de texto em pontos.

`wordspacing`

  O espaço entre palavras como um múltiplo da largura de um caractere de espaço.

`charspacing`

  O espaço entre caracteres. Se o espaçamento for diferente de 0.0, as ligaduras sempre serão dissolvidas.

`hyphenminchars`

  Número mínimo de caracteres hifenizados no final de uma palavra.

`parindent`

  Recuo da primeira linha n em um parágrafo.

`numindentlines`

  Número de linhas em um parágrafo a recuar se parindent for diferente de 0.0.

`parskip`

  Distância entre parágrafos.

`linenumberspace`

  Espaço total na frente de cada linha para o número da linha.

`linenumbersep`

  Espaço entre a linha e o número da linha.

`major`

  O número da versão principal do pslib.

`minor`

  O número da versão secundária do pslib.

`subminor`, `revision`

  O número da versão terciária do pslib.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`name`

  Nome do valor.

`modifier`

  O parâmetro `modifier` especifica o recurso para o qual o valor deve ser recuperado. Pode ser o ID de uma fonte ou uma imagem.

### Valor Retornado

Retorna o valor do parâmetro ou `false`.

### Veja Também

- ps_set_value() - Define certos valores

# ps_hyphenate

(PECL ps >= 1.1.1)

ps_hyphenate — Hifeniza uma palavra

### Descrição

function ps_hyphenate(resource `$psdoc`, string `$text`): array|false

Hifeniza a palavra passada. ps_hyphenate() avalia o valor hyphenminchars (definido por ps_set_value()) e o parâmetro hyphendict (definido por ps_set_parameter()). hyphendict deve ser definido antes de chamar esta função.

Esta função requer que a categoria de localidade `LC_CTYPE` seja definida corretamente. Isso é feito quando a extensão é inicializada usando as variáveis de ambiente. Em sistemas Unix, leia a página de manual de "locale" para mais informações.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`text`
  `text` não deve conter caracteres não alfabéticos. Posições possíveis para quebras são retornadas em um array de números inteiros. Cada número é a posição do caractere em `text` após o qual uma hifenização pode ocorrer.

### Valor Retornado

Um array de inteiros indicando a posição de possíveis quebras no texto ou `false` em caso de falha.

### Exemplos

Exemplo #1 Hifenizando um texto

    <?php
    $word = "Koordinatensystem";
    $psdoc = ps_new();
    ps_set_parameter($psdoc, "hyphendict", "hyph_de.dic");
    $hyphens = ps_hyphenate($psdoc, $word);
    for($i=0; $i<strlen($word); $i++) {
      echo $word[$i];
      if(in_array($i, $hyphens))
        echo "-";
    }
    ps_delete($psdoc);
    ?>

O exemplo acima produzirá:

    Ko-ordi-na-ten-sys-tem

### Veja Também

- ps_show_boxed() - Gera texto em uma caixa
- locale(1)

# ps_include_file

(PECL ps >= 1.3.4)

ps_include_file — Lê um arquivo externo com código PostScript bruto

### Descrição

function ps_include_file(resource `$psdoc`, string `$file`): bool

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`file`

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# ps_lineto

(PECL ps >= 1.1.0)

ps_lineto — Desenha uma linha

### Descrição

function ps_lineto(resource `$psdoc`, float `$x`, float `$y`): bool

Adiciona uma linha reta do ponto atual às coordenadas fornecidas para o caminho atual. Use ps_moveto() para definir o ponto inicial da linha.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`x`

  Coordenada x do ponto final da linha.

`y`

  Coordenada y do ponto final da linha.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Desenhando um retângulo

    <?php
    $ps = ps_new();
    if (!ps_open_file($ps, "retangulo.ps")) {
      print "Não é possível abrir o arquivo PostScript\n";
      exit;
    }

    ps_set_info($ps, "Creator", "retangulo.php");
    ps_set_info($ps, "Author", "Uwe Steinmann");
    ps_set_info($ps, "Title", "Exemplo de ps_lineto");

    ps_begin_page($ps, 596, 842);
    ps_moveto($ps, 100, 100);
    ps_lineto($ps, 100, 200);
    ps_lineto($ps, 200, 200);
    ps_lineto($ps, 200, 100);
    ps_lineto($ps, 100, 100);
    ps_stroke($ps);
    ps_end_page($ps);

    ps_delete($ps);
    ?>

### Veja Também

- ps_moveto() - Define o ponto atual

# ps_makespotcolor

(PECL ps >= 1.1.0)

ps_makespotcolor — Cria cor especial

### Descrição

function ps_makespotcolor(resource `$psdoc`, string `$name`, int `$reserved` = 0): int

Cria uma cor especial a partir da cor de preenchimento atual. A cor de preenchimento deve ser definida no espaço de cores RGB, CMYK ou Gray. O nome da cor especial pode ser um nome arbitrário. Uma cor especial pode ser definida como qualquer cor com ps_setcolor(). Quando o documento não é impresso, mas exibido por um visualizador PostScript, a cor fornecida no espaço de cores especificado é usada.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`name`

  Nome da cor especial, por exemplo, Pantone 5565.

### Valor Retornado

O ID da nova cor especial ou 0 em caso de erro.

### Exemplos

Exemplo #1 Criando e usando uma cor especial

    <?php
    $ps = ps_new();
    if (!ps_open_file($ps, "spotcolor.ps")) {
      print "Não é possível abrir o arquivo PostScript\n";
      exit;
    }

    ps_set_info($ps, "Creator", "spotcolor.php");
    ps_set_info($ps, "Author", "Uwe Steinmann");
    ps_set_info($ps, "Title", "Exemplo de ps_makespotcolor");

    ps_begin_page($ps, 596, 842);
    ps_setcolor($ps, "fill", "cmyk", 0.37, 0.0, 0.34, 0.34);
    $spotcolor = ps_makespotcolor($ps, "PANTONE 5565 C", 0);
    ps_setcolor($ps, "fill", "spot", $spotcolor, 0.5, 0.0, 0.0);
    ps_moveto($ps, 100, 100);
    ps_lineto($ps, 100, 200);
    ps_lineto($ps, 200, 200);
    ps_lineto($ps, 200, 100);
    ps_lineto($ps, 100, 100);
    ps_fill($ps);
    ps_end_page($ps);

    ps_delete($ps);
    ?>

Este exemplo cria a cor especial "PANTONE 5565 C", que é um verde mais escuro (oliva) e preenche um retângulo com 50% de intensidade.

### Veja Também

- ps_setcolor() - Define a cor atual

# ps_moveto

(PECL ps >= 1.1.0)

ps_moveto — Define o ponto atual

### Descrição

function ps_moveto(resource `$psdoc`, float `$x`, float `$y`): bool

Define o ponto atual para novas coordenadas. Se esta for a primeira chamada de ps_moveto() após o término de um caminho anterior, ela iniciará um novo caminho. Se esta função for chamada no meio de um caminho, ela apenas definirá o ponto atual e iniciará um subcaminho.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`x`

  Coordenada x do ponto de destino.

`y`

  Coordenada y do ponto de destino.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_lineto() - Desenha uma linha

# ps_new

(PECL ps >= 1.1.0)

ps_new — Cria um novo objeto de documento PostScript

### Descrição

function ps_new(): resource|false

Cria uma nova instância de documento. Não cria o arquivo em disco ou na memória, apenas configura tudo. ps_new() geralmente é seguido por uma chamada de ps_open_file() para criar o documento PostScript.

### Parâmetros

Esta função não possui parâmetros.

### Valor Retornado

Recurso de documento PostScript ou `false` em caso de falha. O valor de retorno é passado para todas as outras funções como o primeiro argumento.

### Veja Também

- ps_delete() - Exclui todos os recursos de um documento PostScript

# ps_open_file

(PECL ps >= 1.1.0)

ps_open_file — Abre um arquivo para saída

### Descrição

function ps_open_file(resource `$psdoc`, string `$filename` = ?): bool

Cria um novo arquivo no disco e grava o documento PostScript nele. O arquivo será fechado quando ps_close() for chamado.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`filename`

  O nome do arquivo postscript. Se `filename` não for passado, o documento será criado na memória e toda a saída irá diretamente para o navegador.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_close() - Fecha um documento PostScript

# ps_open_image

(PECL ps >= 1.1.0)

ps_open_image — Lê uma imagem para posicionamento posterior

### Descrição

function ps_open_image(
resource `$psdoc`,
string `$type`,
string `$source`,
string `$data`,
int `$length`,
int `$width`,
int `$height`,
int `$components`,
int `$bpc`,
string `$params`
): int

Lê uma imagem que já está disponível na memória. O parâmetro `source` não é avaliado atualmente e assume-se que é `memory`. Os dados da imagem são uma sequência de pixels que começa no canto superior esquerdo e termina no canto inferior direito. Cada pixel consiste em `components` componentes de cor, e cada componente possui bits `bpc`.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`type`

  O tipo da imagem. Os valores possíveis são `png`, `jpeg` ou `eps`.

`source`

  Não usado.

`data`

  Os dados da imagem.

`length`

  O comprimento dos dados da imagem.

`width`

  A largura da imagem.

`height`

  A altura da imagem.

`components`

  O número de componentes para cada pixel. Pode ser 1 (imagens em escala de cinza), 3 (imagens RGB) ou 4 (imagens CMYK, RGBA).

`bpc`

  Número de bits por componente (geralmente 8).

`params`

### Valor Retornado

Retorna o identificador da imagem ou zero em caso de erro. O identificador é um número positivo maior que 0.

### Veja Também

- ps_open_image_file() - Abre a imagem do arquivo
- ps_place_image() - Coloca a imagem na página
- ps_close_image() - Fecha a imagem e libera memória

# ps_open_image_file

(PECL ps >= 1.1.0)

ps_open_image_file — Abre a imagem do arquivo

### Descrição

function ps_open_image_file(
resource `$psdoc`,
string `$type`,
string `$filename`,
string `$stringparam` = ?,
int `$intparam` = 0
): int

Carrega uma imagem para uso posterior.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`type`

  O tipo da imagem. Os valores possíveis são `png`, `jpeg` ou `eps`.

`filename`

  O nome do arquivo que contém os dados da imagem.

`stringparam`

  Não usado.

`intparam`

  Não usado.

### Valor Retornado

Retorna o identificador da imagem ou zero em caso de erro. O identificador é um número positivo maior que 0.

### Veja Também

- ps_open_image() - Lê uma imagem para posicionamento posterior
- ps_place_image() - Coloca a imagem na página
- ps_close_image() - Fecha a imagem e libera memória

# ps_open_memory_image

(PECL ps >= 1.1.0)

ps_open_memory_image — Pega uma imagem GD e retorna uma imagem para posicionamento em um documento PS

### Descrição

function ps_open_memory_image(resource `$psdoc`, int `$gd`): int
Aviso

Esta função não está documentada; apenas a lista de argumentos está disponível.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`gd`

# ps_place_image

(PECL ps >= 1.1.0)

ps_place_image — Coloca a imagem na página

### Descrição

function ps_place_image(
resource `$psdoc`,
int `$imageid`,
float `$x`,
float `$y`,
float `$scale`
): bool

Insere uma imagem carregada anteriormente na página. A imagem pode ser redimensionada. Se a imagem também precisar ser rotacionada, será necessário antes rotacionar o sistema de coordenadas com ps_rotate().

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`imageid`

  O identificador de recurso da imagem retornado por ps_open_image() ou ps_open_image_file().

`x`

  Coordenada x do canto inferior esquerdo da imagem.

`y`

  Coordenada y do canto inferior esquerdo da imagem.

`scale`

  O fator de escala da imagem. Uma escala de 1.0 resultará em uma resolução de 72 dpi, pois cada pixel equivale a 1 ponto.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_open_image() - Lê uma imagem para posicionamento posterior
- ps_open_image_file() - Abre a imagem do arquivo

# ps_rect

(PECL ps >= 1.1.0)

ps_rect — Desenha um retângulo

### Descrição

function ps_rect(
resource `$psdoc`,
float `$x`,
float `$y`,
float `$width`,
float `$height`
): bool

Desenha um retângulo com seu canto inferior esquerdo em (`x`, `y`). O retângulo começa e termina em seu canto inferior esquerdo. Se esta função for chamada fora de um caminho, ela iniciará um novo caminho. Se for chamada dentro de um caminho, ela adicionará o retângulo como um subcaminho. Se a última operação de desenho não terminar no canto inferior esquerdo, então haverá uma lacuna no caminho.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`x`

  Coordenada x do canto inferior esquerdo do retângulo.

`y`

  Coordenada y do canto inferior esquerdo do retângulo.

`width`

  A largura da imagem.

`height`

  A altura da imagem.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_arc() - Desenha um arco no sentido anti-horário
- ps_circle() - Desenha um círculo
- ps_lineto() - Desenha uma linha

# ps_restore

(PECL ps >= 1.1.0)

ps_restore — Restaura o contexto salvo anteriormente

### Descrição

function ps_restore(resource `$psdoc`): bool

Restaura um contexto gráfico salvo anteriormente. Qualquer chamada a ps_save() deve ser acompanhada por uma chamada a ps_restore(). Todas as transformações de coordenadas, configurações de estilo de linha, configurações de cor, etc. serão restauradas ao estado anterior à chamada de ps_save().

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_save() - Salva o contexto atual

# ps_rotate

(PECL ps >= 1.1.0)

ps_rotate — Define o fator de rotação

### Descrição

function ps_rotate(resource `$psdoc`, float `$rot`): bool

Define a rotação do sistema de coordenadas.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`rot`

  Ângulo de rotação em graus.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Rotação do sistema de coordenadas

    <?php
    function rectangle($ps) {
        ps_moveto($ps, 0, 0);
        ps_lineto($ps, 0, 50);
        ps_lineto($ps, 50, 50);
        ps_lineto($ps, 50, 0);
        ps_lineto($ps, 0, 0);
        ps_stroke($ps);
    }

    $ps = ps_new();
    if (!ps_open_file($ps, "rotacao.ps")) {
      print "Não é possível abrir o arquivo PostScript\n";
      exit;
    }

    ps_set_info($ps, "Creator", "rotacao.php");
    ps_set_info($ps, "Author", "Uwe Steinmann");
    ps_set_info($ps, "Title", "Exemplo de rotação");
    ps_set_info($ps, "BoundingBox", "0 0 596 842");

    $psfont = ps_findfont($ps, "Helvetica", "", 0);

    ps_begin_page($ps, 596, 842);
    ps_set_text_pos($ps, 100, 100);
    ps_save($ps);
    ps_translate($ps, 100, 100);
    ps_rotate($ps, 45);
    rectangle($ps);
    ps_restore($ps);
    ps_setfont($ps, $psfont, 8.0);
    ps_show($ps, "Texto sem rotação");
    ps_end_page($ps);

    ps_delete($ps);
    ?>

O exemplo acima ilustra uma maneira muito comum de rotacionar um gráfico (neste caso, apenas um retângulo) simplesmente rotacionando o sistema de coordenadas. Como o sistema de coordenadas do gráfico assume (0,0) como a origem, o sistema de coordenadas da página também é transladado para posicionar o gráfico fora da borda da página. Preste atenção à ordem de ps_translate() e ps_rotate(). No caso acima, o retângulo é rotacionado em torno do ponto (100, 100) no sistema de coordenadas não transladado. Trocar as duas instruções tem um resultado completamente diferente.

Para gerar o texto na posição original, todas as modificações do sistema de coordenadas são encapsuladas em ps_save() e ps_restore().

### Veja Também

- ps_scale() - Define o fator de escala
- ps_translate() - Defina o ponto de translação

# ps_save

(PECL ps >= 1.1.0)

ps_save — Salva o contexto atual

### Descrição

function ps_save(resource `$psdoc`): bool

Salva o contexto gráfico atual, contendo cores, configurações de translação e rotação, e muito mais. Um contexto salvo pode ser restaurado com ps_restore().

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_restore() - Restaura o contexto salvo anteriormente

# ps_scale

(PECL ps >= 1.1.0)

ps_scale — Define o fator de escala

### Descrição

function ps_scale(resource `$psdoc`, float `$x`, float `$y`): bool

Define a escala horizontal e vertical do sistema de coordenadas.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`x`

  Fator de escala na direção horizontal.

`y`

  Fator de escala na direção vertical.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_rotate() - Define o fator de rotação
- ps_translate() - Defina o ponto de translação

# ps_set_border_color

(PECL ps >= 1.1.0)

ps_set_border_color — Define a cor da borda para anotações

### Descrição

function ps_set_border_color(
resource `$psdoc`,
float `$red`,
float `$green`,
float `$blue`
): bool

Links adicionados com uma das funções ps_add_weblink(), ps_add_pdflink(), etc. serão exibidos com um retângulo ao redor quando o documento PostScript for convertido para PDF e exibido em um visualizador de PDF. Este retângulo não é visível no documento PostScript. Esta função define a cor da linha da borda do retângulo.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`red`

  O componente vermelho da cor da borda.

`green`

  O componente verde da cor da borda.

`blue`

  O componente azul da cor da borda.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_set_border_dash() - Define o comprimento dos traços para a borda das anotações
- ps_set_border_style() - Define o estilo de borda das anotações

# ps_set_border_dash

(PECL ps >= 1.1.0)

ps_set_border_dash — Define o comprimento dos traços para a borda das anotações

### Descrição

function ps_set_border_dash(resource `$psdoc`, float `$black`, float `$white`): bool

Links adicionados com uma das funções ps_add_weblink(), ps_add_pdflink(), etc. serão exibidos com um retângulo arredondado quando o documento PostScript for convertido para PDF e exibido em um visualizador de PDF. Este retângulo não é visível no documento PostScript. Esta função define o comprimento da parte preta e branca de uma linha de borda tracejada.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`black`

  O comprimento do traço.

`white`

  O comprimento do espaço entre os traços.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_set_border_color() - Define a cor da borda para anotações
- ps_set_border_style() - Define o estilo de borda das anotações

# ps_set_border_style

(PECL ps >= 1.1.0)

ps_set_border_style — Define o estilo de borda das anotações

### Descrição

function ps_set_border_style(resource `$psdoc`, string `$style`, float `$width`): bool

Links adicionados com uma das funções ps_add_weblink(), ps_add_pdflink(), etc. serão exibidos com um retângulo ao redor quando o documento PostScript for convertido para PDF e exibido em um visualizador de PDF. Este retângulo não é visível no documento PostScript. Esta função define a aparência e a largura da linha da borda.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`style`

  `style` pode ser `solid` ou `dashed`.

`width`

  A largura da linha da borda.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_set_border_color() - Define a cor da borda para anotações
- ps_set_border_dash() - Define o comprimento dos traços para a borda das anotações

# ps_set_info

(PECL ps >= 1.1.0)

ps_set_info — Define campos de informação do documento

### Descrição

function ps_set_info(resource `$psdoc`, string `$key`, string `$value`): bool

Define determinados campos de informação do documento. Esses campos serão exibidos como um comentário no cabeçalho do arquivo PostScript. Se o documento for convertido para PDF, esses campos também serão usados ​​para as informações do documento.

A `BoundingBox` geralmente é definida com o valor atribuído à primeira página. Isso só funciona se a ps_findfont() não tiver sido chamada antes. Nesses casos, a BoundingBox permaneceria indefinida, a menos que seja dadosefinida explicitamente com esta função.

Esta função não terá mais efeito quando o cabeçalho do arquivo postscript já tiver sido escrito. Ela deve ser chamada antes da primeira página ou da primeira chamada de ps_findfont().

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`key`

  O nome do campo de informações a ser definido. Os valores que podem ser definidos são `Keywords`, `Subject`, `Title`, `Creator`, `Author`, `BoundingBox` e `Orientation`. Esteja ciente de que alguns deles têm um significado para visualizadores PostScript.

`value`

  O valor do campo de informação. O campo `Orientation` pode ser definido para `Portrait` ou `Landscape`. O campo `BoundingBox` é uma string consistindo em quatro números. Os dois primeiros números são as coordenadas do canto inferior esquerdo da página. Os dois últimos números são as coordenadas do canto superior direito.

  > Nota:

  > Até a versão 0.2.6 do pslib, o BoundingBox e a Orientation serão substituídos por ps_begin_page(), a menos que ps_findfont() tenha sido chamada antes.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_findfont() - Carrega uma fonte
- ps_begin_page() - Inicia uma nova página

# ps_set_parameter

(PECL ps >= 1.1.0)

ps_set_parameter — Define certos parâmetros

### Descrição

function ps_set_parameter(resource `$psdoc`, string `$name`, string `$value`): bool

Define diversos parâmetros que são usados ​​por muitas funções. Parâmetros são, por definição, valores de string.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`name`

  Para uma lista de nomes possíveis, veja ps_get_parameter().

`value`

  O valor do parâmetro.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_get_parameters()
- ps_set_value() - Define certos valores

# ps_set_text_pos

(PECL ps >= 1.1.0)

ps_set_text_pos — Define a posição para saída de texto

### Descrição

function ps_set_text_pos(resource `$psdoc`, float `$x`, float `$y`): bool

Define a posição para a próxima saída de texto. Alternativamente, podem ser definidos os valores x e y separadamente chamando ps_set_value() e escolhendo `textx` respectivamente `texty` como o nome do valor.

Se a intenção for exibir texto em uma determinada posição, é mais conveniente usar ps_show_xy() em vez de definir a posição do texto e chamar ps_show().

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`x`

  Coordenada x da nova posição do texto.

`y`

  Coordenada y da nova posição do texto.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Colocando texto em uma determinada posição

    <?php
    $ps = ps_new();
    if (!ps_open_file($ps, "text.ps")) {
      print "Não é possível abrir o arquivo PostScript\n";
      exit;
    }

    ps_set_info($ps, "Creator", "rectangle.php");
    ps_set_info($ps, "Author", "Uwe Steinmann");
    ps_set_info($ps, "Title", "Exemplo de posicionamento de texto");

    ps_begin_page($ps, 596, 842);
    $psfont = ps_findfont($ps, "Helvetica", "", 0);
    ps_setfont($ps, $psfont, 8.0);
    ps_show_xy($ps, "Algum texto em (100, 100)", 100, 100);

    ps_set_value($ps, "textx", 100);
    ps_set_value($ps, "texty", 120);
    ps_show($ps, "Algum texto em (100, 120)");
    ps_end_page($ps);

    ps_delete($ps);
    ?>

### Veja Também

- ps_set_value() - Define certos valores
- ps_show() - Exibe texto

# ps_set_value

(PECL ps >= 1.1.0)

ps_set_value — Define certos valores

### Descrição

function ps_set_value(resource `$psdoc`, string `$name`, float `$value`): bool

Define vários valores que são usados ​​por muitas funções. Os parâmetros são, por definição, valores float.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`name`

  O parâmetro `name` pode ter um dos seguintes valores:

  textrendering

    A maneira como o texto é exibido.

  textx

    A coordenada x para saída de texto.

  texty

    A coordenada y para saída de texto.

  wordspacing

    A distância entre palavras em relação à largura de um espaço.

  leading

    A distância entre linhas em pixels.

`value`

  O valor do parâmetro.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_get_value() - Obtém determinados valores
- ps_set_parameter() - Define certos parâmetros

# ps_setcolor

(PECL ps >= 1.1.0)

ps_setcolor — Define a cor atual

### Descrição

function ps_setcolor(
resource `$psdoc`,
string `$type`,
string `$colorspace`,
float `$c1`,
float `$c2`,
float `$c3`,
float `$c4`
): bool

Define a cor para desenho, preenchimento ou ambos.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`type`

  O parâmetro `type` pode ser `both`, `fill` ou `fillstroke`.

`colorspace`

  O espaço de cores deve ser um dos seguintes: `gray`, `rgb`, `cmyk`, `spot` ou `pattern`. Dependendo do espaço de cores, apenas o primeiro, os três primeiros ou todos os parâmetros serão usados.

`c1`

  Dependendo do espaço de cores, este pode ser o componente vermelho (rgb), o componente ciano (cmyk), o valor de cinza (gray), o identificador da cor especial ou o identificador do padrão.

`c2`

  Dependendo do espaço de cores, este pode ser o componente verde (rgb) ou o componente magenta (cmyk).

`c3`

  Dependendo do espaço de cores, este pode ser o componente azul (rgb) ou o componente amarelo (cmyk).

`c4`

  Isso deve ser definido somente no espaço de cores cmyk e especifica o componente preto.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Notas

Cuidado

O segundo parâmetro nem sempre é avaliado atualmente. A cor é às vezes definida para preenchimento e desenho, como se `fillstroke` fosse passado.

# ps_setdash

(PECL ps >= 1.1.0)

ps_setdash — Define a aparência de uma linha tracejada

### Descrição

function ps_setdash(resource `$psdoc`, float `$on`, float `$off`): bool

Define o comprimento das partes preta e branca de uma linha tracejada.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`on`

  O comprimento do traço.

`off`

  O comprimento do espaço entre os traços.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_setpolydash() - Define a aparência de uma linha tracejada

# ps_setflat

(PECL ps >= 1.1.0)

ps_setflat — Define planicidade

### Descrição

function ps_setflat(resource `$psdoc`, float `$value`): bool

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`value`

  O parâmetro `value` deve estar entre 0.2 e 1.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# ps_setfont

(PECL ps >= 1.1.0)

ps_setfont — Define a fonte a ser usada na saída seguinte

### Descrição

function ps_setfont(resource `$psdoc`, int `$fontid`, float `$size`): bool

Define uma fonte, que deve ser carregada previamente com ps_findfont(). A saída de texto sem definir uma fonte resulta em erro.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`fontid`

  O identificador de fonte retornado por ps_findfont().

`size`

  O tamanho da fonte.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_findfont() - Carrega uma fonte
- ps_set_text_pos() - Define a posição para saída de texto para um exemplo

# ps_setgray

(PECL ps >= 1.1.0)

ps_setgray — Define o valor de cinza

### Descrição

function ps_setgray(resource `$psdoc`, float `$gray`): bool

Define o valor de cinza para todas as operações de desenho seguintes.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`gray`

  O valor deve estar entre 0 (branco) e 1 (preto).

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_setcolor() - Define a cor atual

# ps_setlinecap

(PECL ps >= 1.1.0)

ps_setlinecap — Define a aparência das extremidades da linha

### Descrição

function ps_setlinecap(resource `$psdoc`, int `$type`): bool

Define a aparência das extremidades da linha.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`type`

  O tipo de extremidades da linha. Os valores possíveis são `PS_LINECAP_BUTT`, `PS_LINECAP_ROUND` ou `PS_LINECAP_SQUARED`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_setlinejoin() - Define como as linhas conectadas são unidas
- ps_setlinewidth() - Define a largura de uma linha
- ps_setmiterlimit() - Define o limite de esquadria

# ps_setlinejoin

(PECL ps >= 1.1.0)

ps_setlinejoin — Define como as linhas conectadas são unidas

### Descrição

function ps_setlinejoin(resource `$psdoc`, int `$type`): bool

Define como as linhas são unidas.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`type`

  A maneira como as linhas são unidas. Os valores possíveis são `PS_LINEJOIN_MITER`, `PS_LINEJOIN_ROUND` ou `PS_LINEJOIN_BEVEL`.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_setlinecap() - Define a aparência das extremidades da linha
- ps_setlinewidth() - Define a largura de uma linha
- ps_setmiterlimit() - Define o limite de esquadria

# ps_setlinewidth

(PECL ps >= 1.1.0)

ps_setlinewidth — Define a largura de uma linha

### Descrição

function ps_setlinewidth(resource `$psdoc`, float `$width`): bool

Define a largura da linha para todas as operações de desenho seguintes.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`width`

  A largura das linhas em pontos.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_setlinecap() - Define a aparência das extremidades da linha
- ps_setlinejoin() - Define como as linhas conectadas são unidas
- ps_setmiterlimit() - Define o limite de esquadria

# ps_setmiterlimit

(PECL ps >= 1.1.0)

ps_setmiterlimit — Define o limite de esquadria

### Descrição

function ps_setmiterlimit(resource `$psdoc`, float `$value`): bool

Se duas linhas se unirem em um ângulo pequeno e a junção da linha for definida como `PS_LINEJOIN_MITER`, então a ponta resultante será muito longa. O limite de esquadria é a proporção máxima entre o comprimento da esquadria (o comprimento da ponta) e a largura da linha.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`value`

  A proporção máxima entre o comprimento da esquadria e a largura da linha. Valores maiores (> 10) resultarão em pontas muito longas quando duas linhas se encontram em um ângulo pequeno. O padrão deve ser mantido, a menos que se saiba o que está sendo feito.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_setlinecap() - Define a aparência das extremidades da linha
- ps_setlinejoin() - Define como as linhas conectadas são unidas
- ps_setlinewidth() - Define a largura de uma linha

# ps_setoverprintmode

(PECL ps >= 1.3.0)

ps_setoverprintmode — Define o modo de sobreimpressão

### Descrição

function ps_setoverprintmode(resource `$psdoc`, int `$mode`): bool

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`mode`

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

# ps_setpolydash

(PECL ps >= 1.1.0)

ps_setpolydash — Define a aparência de uma linha tracejada

### Descrição

function ps_setpolydash(resource `$psdoc`, float `$arr`): bool

Define o comprimento das partes preta e branca de uma linha tracejada. ps_setpolydash() é usada para definir padrões de traços mais complexos.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`arr`

  `arr` é uma lista de elementos de comprimento alternados para as partes preta e branca.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Desenhando uma linha tracejada

    <?php
    $ps = ps_new();
    if (!ps_open_file($ps, "polydash.ps")) {
       print "Não é possível abrir o arquivo PostScript\n";
         exit;
    }

    ps_set_info($ps, "Creator", "polydash.php");
    ps_set_info($ps, "Author", "Uwe Steinmann");
    ps_set_info($ps, "Title", "Exemplo de linha tracejada");

    ps_begin_page($ps, 596, 842);
    ps_setpolydash($ps, array(10, 5, 2, 5));
    ps_moveto($ps, 100, 100);
    ps_lineto($ps, 200, 200);
    ps_stroke($ps);
    ps_end_page($ps);

    ps_delete($ps);
    ?>

Este exemplo desenha uma linha com 10 pontos de comprimento e 2 pontos de distância, e intervalos de 5 pontos entre elas.

### Veja Também

- ps_setdash() - Define a aparência de uma linha tracejada

# ps_shading

(PECL ps >= 1.3.0)

ps_shading — Cria um sombreamento para uso posterior

### Descrição

function ps_shading(
resource `$psdoc`,
string `$type`,
float `$x0`,
float `$y0`,
float `$x1`,
float `$y1`,
float `$c1`,
float `$c2`,
float `$c3`,
float `$c4`,
string `$optlist`
): int|false

Cria um sombreamento, que pode ser usado por ps_shfill() ou ps_shading_pattern().

A cor do sombreamento pode estar em qualquer espaço de cor, exceto `pattern`.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`type`

  O tipo de sombreamento pode ser `radial` ou `axial`. Cada sombreamento começa com a cor de preenchimento atual e termina com os valores de cor fornecidos nos parâmetros `c1` a `c4` (consulte ps_setcolor() para saber o significado).

`x0, x1, y0, y1`

  As coordenadas `x0`, `y0`, `x1`, `y1` são os pontos inicial e final do sombreamento. Se o tipo de sombreamento for `radial`, os dois pontos serão os pontos médios de um círculo inicial e final.

`c1, c2, c3, c4`

  Veja ps_setcolor() para saber seu significado.

`optlist`

  Se o sombreamento for do tipo `radial`, o `optlist` também deve conter os parâmetros `r0` e `r1` com o raio do círculo inicial e final.

### Valor Retornado

Retorna o identificador do padrão ou `false` em caso de falha.

### Veja Também

- ps_shading_pattern() - Cria um padrão com base em um sombreamento
- ps_shfill() - Preenche uma área com um sombreamento

# ps_shading_pattern

(PECL ps >= 1.3.0)

ps_shading_pattern — Cria um padrão com base em um sombreamento

### Descrição

function ps_shading_pattern(resource `$psdoc`, int `$shadingid`, string `$optlist`): int|false

Cria um padrão com base em um sombreamento, que deve ser criado previamente com ps_shading(). Padrões de sombreamento podem ser usados ​​como padrões normais.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`shadingid`

  O identificador de um sombreamento criado anteriormente com ps_shading().

`optlist`

  Este argumento não é usado atualmente.

### Valor Retornado

O identificador do padrão ou `false` em caso de falha.

### Veja Também

- ps_shading() - Cria um sombreamento para uso posterior
- ps_shfill() - Preenche uma área com um sombreamento

# ps_shfill

(PECL ps >= 1.3.0)

ps_shfill — Preenche uma área com um sombreamento

### Descrição

function ps_shfill(resource `$psdoc`, int `$shadingid`): bool

Preenche uma área com um sombreamento, que deve ser criado antes com ps_shading(). Esta é uma maneira alternativa de criar um padrão a partir de um sombreamento ps_shading_pattern() e usar o padrão como cor de preenchimento.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`shadingid`

  O identificador de um sombreamento criado anteriormente com ps_shading().

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_shading() - Cria um sombreamento para uso posterior
- ps_shading_pattern() - Cria um padrão com base em um sombreamento

# ps_show

(PECL ps >= 1.1.0)

ps_show — Exibe texto

### Descrição

function ps_show(resource `$psdoc`, string `$text`): bool

Gera um texto na posição atual de texto. A posição do texto pode ser definida armazenando as coordenadas x e y nos valores `textx` e `texty` com a função ps_set_value(). A função emitirá um erro se uma fonte não tiver sido definida anteriormente com ps_setfont().

ps_show() avalia os seguintes parâmetros e valores conforme definidos por ps_set_parameter() e ps_set_value().

charspacing (valor)

  Distância entre dois glifos consecutivos. Se este valor for diferente de zero, todas as ligaduras serão resolvidas. Valores menores que zero são permitidos.

kerning (parâmetro)

  Definir este parâmetro como "false" desativará o kerning. O kerning é ativado por padrão.

ligatures (parâmetro)

  Definir este parâmetro como "false" desativará o uso de ligaduras. As ligaduras são ativadas por padrão.

underline (parâmetro)

  Definir este parâmetro como "true" ativará o sublinhado. O sublinhado está desativado por padrão.

overline (parâmetro)

  Definir este parâmetro como "true" ativará o texto com linha superior. Texto com linha superior está desativado por padrão.

strikeout (parâmetro)

  Definir este parâmetro como "true" ativará o recurso de texto tachado. O texto tachado está desativado por padrão.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`text`

  O texto a ser exibido.

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Veja Também

- ps_continue_text() - Continua o texto na próxima linha
- ps_show_xy() - Exibe texto na posição fornecida
- ps_setfont() - Define a fonte a ser usada na saída seguinte

# ps_show_boxed

(PECL ps >= 1.1.0)

ps_show_boxed — Gera texto em uma caixa

### Descrição

function ps_show_boxed(
resource `$psdoc`,
string `$text`,
float `$left`,
float `$bottom`,
float `$width`,
float `$height`,
string `$hmode`,
string `$feature` = ?
): int

Gera um texto em uma determinada caixa. O canto inferior esquerdo da caixa está em (`left`, `bottom`). Quebras de linha serão inseridas onde necessário. Vários espaços são tratados como um. Tabulações são tratadas como espaços.

O texto será hifenizado se o parâmetro `hyphenation` estiver definido como `true` e o parâmetro `hyphendict` contiver um nome de arquivo válido para um arquivo de hifenização. O espaçamento entre linhas é obtido do valor `leading`. Os parágrafos podem ser separados por uma linha vazia, como no TeX. Se o valor `parindent` estiver definido como > 0.0, as primeiras n linhas serão recuadas. O número n de linhas é definido pelo parâmetro `numindentlines`. Para evitar o recuo dos primeiros m parágrafos, defina o valor `parindentskip` como um número positivo.

### Parâmetros

`psdoc`

  Identificador de recurso do arquivo postscript conforme retornado por ps_new().

`text`

  O texto a ser exibido na caixa fornecida.

`left`

  Coordenada x do canto inferior esquerdo da caixa.

`bottom`

  Coordenada y do canto inferior esquerdo da caixa.

`width`

  Largura da caixa.

`height`

  Altura da caixa.

`hmode`

  O parâmetro `hmode` pode ser `justify`, `fulljustify`, `right`, `left` ou `center`. A diferença entre `justify` e `fulljustify` afeta apenas a última linha da caixa. No modo `fulljustify`, a última linha será justificada à esquerda e à direita, a menos que esta também seja a última linha do parágrafo. No modo `justify`, ela sempre será justificada à esquerda.

`feature`

#### Parâmetros usados

A saída de ps_show_boxed() pode ser configurada com vários parâmetros e valores que devem ser definidos com ps_set_parameter() ou ps_set_value(). Além dos parâmetros e valores que afetam a saída de texto, os seguintes parâmetros e valores são avaliados.

leading (valor)

  Distância entre linhas de base de duas linhas consecutivas.

linebreak (parâmetro)

  Se definido como `true`, um retorno de carro inicia uma nova linha em vez de ser tratado como um espaço. O padrão é `false`.

parbreak (parâmetro)

  Se definido como `true`, um retorno de carro em uma única linha inicia um novo parágrafo em vez de ser tratado como um espaço. O padrão é `true`.

hyphenation (parâmetro)

  Se definido como `true`, ativa a hifenização. Isso requer que um dicionário seja definido com o parâmetro `hyphendict`. O padrão é `false`.

hyphendict (parâmetro)

  Nome do arquivo do dicionário usado para o padrão de hifenização (veja abaixo).

hyphenminchar (valor)

  O número de caracteres que devem sobrar pelo menos antes ou depois do hífen. Isso implica que apenas palavras com pelo menos o dobro desse valor serão hifenizadas. O valor padrão é três. Definir um valor igual a zero resultará no valor padrão.

parindent (valor)

  Define a quantidade de espaço em pixels para recuar as primeiras m linhas de um parágrafo. m pode ser definido com o valor `numindentlines`.

parskip (valor)

  Define a quantidade de espaço extra em pixels entre parágrafos. O padrão é `0`, o que resultará em uma distância de linha normal.

numindentlines (valor)

  Número de linhas a partir do início do parágrafo que serão recuadas. O padrão é `1`.

parindentskip (valor)

  Número de parágrafos na caixa cujas primeiras linhas não serão recuadas. O padrão é `0`. Isso é útil para parágrafos logo após um título de seção ou texto continuado em uma segunda caixa. Em ambos os casos, seria definido como `1`.

linenumbermode (parâmetro)

  Define como as linhas devem ser numeradas. Os valores possíveis são `box` para numerar linhas em toda a caixa ou `paragraph` para numerar linhas dentro de cada parágrafo.

linenumberspace (valor)

  O espaço para a coluna à esquerda da linha numerada que contém o número da linha. O número da linha será justificado à direita nesta coluna. O padrão é `20`.

linenumbersep (valor)

  O espaço entre a coluna com os números das linhas e a própria linha. O padrão é `5`.

#### Hyphenation

O texto será hifenizado se o parâmetro `hyphenation` estiver definido como verdadeiro e um dicionário de hifenização válido estiver definido. O pslib não fornece seu próprio dicionário de hifenização, mas utiliza um do OpenOffice, Scribus ou Koffice. Os dicionários para diferentes idiomas podem ser encontrados em um dos seguintes diretórios, se o software estiver instalado:

- /usr/share/apps/koffice/hyphdicts/
- /usr/lib/scribus/dicts/
- /usr/lib/openoffice/share/dict/ooo/

Atualmente, o Scribus parece ter os dicionários de hifenização mais completos.

### Valor Retornado

Número de cara
[file cut: first 33554432 bytes kept]
